# Visual Node Directory: Comprehensive Canvas Reference
### *A complete visual and functional catalog of every card, terminal, and tool in Nodestr.*
The Nodestr canvas provides 12 specialized node types categorized into 5 functional families: **Basic Nodes**, **Tables & Data**, **AI / LLM**, **I/O Ingestion & Egress**, and **Canvas Structure & Tools**.
Use this directory to understand the anatomy, ports, shortcuts, and capabilities of every node.
---
## 1. Quick Navigation by Family
| Family | Nodes Included | Primary Role |
| :--- | :--- | :--- |
| **Basic** | Text Node, Switch Node, Find & Replace, Output Hub | Core text drafting, multi-branch switching, string remapping, and final document compilation. |
| **Tables & Data** | Table Node, Record Selector Node | Tabular dataset management, parametric prompts, and synchronized multi-table record stepping. |
| **AI / LLM** | AI Agent Node | Autonomous LLM execution across 6 providers with streaming, encrypted BYOK keys, and human verification. |
| **I/O Ingestion & Egress** | File Loader Node, Document Exporter Node | Client-side file parsing (.docx, .xlsx, .pdf, .md) with auto-chunking, and multi-format download / Google Drive sync. |
| **Canvas Structure** | Group Node, Frame, Sticky Note | Sub-graph encapsulation, 60fps clamped cluster framing, and stationery WYSIWYG rich text annotations. |
---
## 2. Basic Family
### A. Text Node
- **Category**: Basic Text Card
- **Shortcut**: `Shift + A` → Text Node
- **Ports & Handles**:
- `+ Add Input` (Left edge): Chained upstream inputs that feed into the card's text.
- `All out` (Top-right, Green): Emits the concatenated, formatted text of this card.
- `out-{inputId}` (Right edge): 1:1 individual slot output mirroring each connected input.
- **Visual Anatomy**: Compact card with a multi-line rich text field, optional title placard, and pill token tray.
- **Key Capabilities**:
- Multi-line rich text editor powered by TipTap with full-screen expansion modal (`Ctrl+Enter` or double-click).
- Connects to Table Nodes via `All Records` to unlock dynamic `+ ColumnName` variable pill chips.
- Evaluates `{{ColumnName}}` tokens with live value previews and inline removal badges.
- Toggle between single-row `📄 Record` mode and full-dataset `📊 Table` Markdown injection.
### B. Switch Node (Select)
- **Category**: Multi-Branch Switcher
- **Shortcut**: `Shift + A` → Switch Node
- **Ports & Handles**:
- `Option 1`, `Option 2`, ... (Left edge, expandable via `+ Add Input`): Receives alternative text branches.
- `Out` (Top-right, Green): Emits the currently active selected option.
- **Visual Anatomy**: Segmented selector pills or dropdown menu showing the active branch.
- **Key Capabilities**:
- Switch between tone variants, persona prompts, or alternative copy drafts with a single click.
- Hot swapping: changes immediately propagate downstream to the Output Hub without re-wiring edges.
- Unchosen branches are completely bypassed during prompt compilation, saving tokens and memory.
### C. Find & Replace Node
- **Category**: Pipeline Text Remapping
- **Shortcut**: `Shift + A` → Find & Replace
- **Ports & Handles**:
- `IN` (Left edge, dynamic inputs): Accepts upstream text streams.
- `All out` (Top-right, Green): Emits the sequential transformed stream.
- `OUT` (Right edge): 1:1 individual transformed slot outputs.
- **Visual Anatomy**: Table of sequential rule rows (`Find...` and `Replace...` fields), 3-dot settings menu, and live preview drawer.
- **Key Capabilities**:
- Sequential top-to-bottom rule execution with Case-Sensitive (`Aa`) and Regular Expression (`.*`) toggles.
- **Dynamic Table Columns Pill Bar**: Wiring a Table Node reveals clickable `+ ColumnName` pills.
- **Visual Pill Chips in Replace Fields**: Tokens render as formatted pills with live record values rather than raw text.
- **Automated Batch Tokenization**: Draft text naturally and bind table data across batches without manual search-and-replace.
- **Live Preview Drawer**: Shows transformed text with amber `<mark>` highlight badges over all replaced phrases.
### D. Output Hub Node
- **Category**: Central Terminal & Batch Engine
- **Shortcut**: `Shift + A` → Output Hub Node
- **Ports & Handles**:
- `IN` (Left edge, dynamic inputs): Aggregates all upstream text nodes, prompt cards, and tables.
- `Out` (Right edge, Green): Passthrough port emitting the complete compiled Markdown stream downstream.
- **Visual Anatomy**: Prominent emerald-tinted terminal card with live prompt preview, 1-click copy button, and batch action trigger.
- **Key Capabilities**:
- Real-time prompt compilation sorting all upstream nodes in top-to-bottom spatial order.
- **Deterministic Output Hub Batch Compiler**: Single `Run Batch (N rows)` trigger inside the node body.
- **Pre-Flight Audit**: Scans for missing cells, unresolved `{{Token}}` typos, and exact character counts in <20ms.
- **Human-Verified AI Safety Lock**: Blocks blind automated AI loops until `Extract to Text` is confirmed.
- Right-hand `Out` port connects directly into Document Exporter Nodes for seamless publishing.
---
## 3. Tables & Data Family
### A. Table Node
- **Category**: Tabular Dataset
- **Shortcut**: `Shift + A` → Table Node
- **Ports & Handles**:
- `Record Selector` (Left edge, Violet): Receives master index synchronization from Record Selector Nodes.
- `All Records` (Right edge, Royal Blue): Bundles all records for downstream consumer `[ 📄 Record | 📊 Table ]` toggles.
- Scalar Column Handles (Right edge, Sky Blue): Emits individual scalar columns when `Single Record` mode is active.
- **Visual Anatomy**: Segmented `[ All Records | Single Record ]` mode button, compact Used Schemas list, active record indicator, and `Value Only` / `Field/Value Pair` footer switch.
- **Key Capabilities**:
- Segmented Mode Switch: Easily toggle between `All Records` (bundles entire dataset) and `Single Record` (active row stepper & scalar handles).
- Full spreadsheet grid modal: double-click to add columns, edit rows, or paste tab-separated spreadsheet data.
- Enforces system limits: up to 12 columns in Local Mode, 16 in Cloud Mode; up to 100 rows per table.
- Single Point of Control: easily switch between independent row steppers or master synchronization.
- Directly drives the Output Hub Batch Compiler for automated multi-row generation.
### B. Record Selector Node
- **Category**: Master Record Synchronizer
- **Shortcut**: `Shift + A` → Record Selector Node
- **Ports & Handles**:
- `Sync Out` (Right edge, Violet): Connects to the `Record Selector` handle of one or more Table Nodes.
- **Visual Anatomy**: Interactive stepper pill displaying `Record X of Y: Label` with previous/next controls.
- **Key Capabilities**:
- Coordinates multiple partitioned tables (e.g. Customers, Plans, Invoices) to advance in lockstep.
- Locks downstream consumer node steppers to read-only (`🔗`), eliminating out-of-sync data errors.
- Keyboard and arrow navigation for rapid record switching during live prompt testing.
---
## 4. AI / LLM Family
### AI Agent Node
- **Category**: Autonomous LLM Execution
- **Shortcut**: `Shift + A` → AI Agent Node
- **Ports & Handles**:
- `Prompt` (Left edge): Primary instruction or user prompt stream.
- `Assign Role` (Left edge): System persona and behavioral constraints.
- `Source Material` (Left edge): Background context, documents, or data tables.
- `Response` (Right edge, Purple): Emits streaming markdown output downstream.
- **Visual Anatomy**: Purple-tinted agent card with model selector, temperature slider, token budget, and streaming output terminal.
- **Key Capabilities**:
- Multi-provider execution: Gemini, OpenAI, Claude, DeepSeek, Groq, and local privacy-first Ollama models.
- Client-side AES-GCM encrypted API key storage (BYOK); keys never touch external third-party servers.
- **Extract to Text**: Converts generated AI responses into editable Text Nodes for inspection and human verification.
- In-node token consumption metrics and cost calculation ledger.
---
## 5. I/O Ingestion & Egress Family
### A. File Loader Node
- **Category**: Document Ingestion & Chunking
- **Shortcut**: `Shift + A` → File Loader
- **Ports & Handles**:
- Upload Dropzone: Drag-and-drop file upload or public cloud link input.
- `Raw Out` (Top-right): Emits the complete, unchunked document text downstream.
- **Visual Anatomy**: Dashed ingestion container with file metadata badges and chunking configuration controls.
- **Key Capabilities**:
- Client-side parsing for Word (.docx), Excel (.xlsx), CSV, Markdown (.md), Plain Text, and PDF files.
- Semantic chunking strategies: automatic splitting by H1/H2 headings, paragraph counts, or token budgets.
- Spawns organized canvas frames of connected text cards automatically with zero file exposure.
### B. Document Exporter Node
- **Category**: Multi-Format Publishing Terminal
- **Shortcut**: `Shift + A` → Document Exporter
- **Ports & Handles**:
- `In` (Left edge): Receives compiled Markdown from Output Hubs, Text Nodes, or Tables.
- **Visual Anatomy**: Egress card with format picker pills, file naming controls, and 1-click download button.
- **Key Capabilities**:
- Multi-format local export: Word (.docx), Excel (.xlsx), Markdown (.md), PDF, CSV, and Plain Text (.txt).
- Cloud export: 1-click publishing directly into Google Drive as native Google Docs or Google Sheets.
- Lossless layout preservation: formats headings, callout boxes, and GitHub-Flavored Markdown tables accurately.
---
## 6. Canvas Structure & Tools Family
### A. Group Node
- **Category**: Sub-Graph Encapsulation
- **Shortcut**: Select nodes → `Ctrl + G` (or `Cmd + G`)
- **Ports & Handles**:
- Parent Proxy Inputs: Mirror internal `Group Input Node` handles.
- `All out` (Header) + Parent Proxy Outputs: Mirror internal `Group Output Node` handles in explicit spatial order.
- **Visual Anatomy**: Clean container card with breadcrumb path, child node count badge, and Enter Sub-Graph icon.
- **Key Capabilities**:
- Collapses complex multi-node workflows into clean, reusable parent cards with zero canvas clutter.
- Double-click header or click Enter to zoom into an isolated child canvas workspace.
- Bidirectional drag re-ordering: reordering handles inside immediately syncs to parent ports.
- Seamless TabBar breadcrumb navigation back to parent workspaces.
### B. Frame
- **Category**: Visual Boundary & Organization
- **Shortcut**: `Shift + F` (or Frame tool on bottom dock)
- **Ports & Handles**:
- None (Structural organizational container; 100% compiler isolation).
- **Visual Anatomy**: Color-coded boundary rectangle with title placard and 12x12px corner resize handles.
- **Key Capabilities**:
- 60fps corner and edge resizing with automatic baseline clamping to child boundaries.
- **Marquee Select Exclusion**: Dragging a selection box over nodes never accidentally touches the frame.
- **Synchronized Frame Selection**: Selecting all child nodes automatically selects the frame for unified dragging.
- Color-coded borders and title placards for clear visual clustering.
### C. Sticky Note
- **Category**: Canvas Annotation
- **Shortcut**: `Shift + N` (or Sticky Note tool on bottom dock)
- **Ports & Handles**:
- None (Zero connection handles; impossible to accidentally wire into prompt streams).
- **Visual Anatomy**: Stationery paper card with generous padding, points dropdown, and clean typography.
- **Key Capabilities**:
- True WYSIWYG rich text powered by TipTap: bold, italics, checklists, headings, and text alignment.
- 6 curated stationery tints (Yellow, Blue, Green, Pink, Violet, Dark) with matching subtle borders.
- 100% compiler isolation: notes are excluded from prompt compilation and mobile output views.
- Global visibility toggle with `Shift + H` or the left viewport eye control.