Block Catalog

The Block Catalog defines every built-in block type available in WeftOS. Each block has:

• A Zod schema constraining its props (used by the Weaver to generate valid descriptors)
• A Block Registry entry mapping the type name to renderer implementations
• Defined input/output ports for inter-block communication
• Defined actions it can trigger
• Rendering notes describing behavior on each target (Web, Terminal, HUD)

The Weaver generates JSON descriptors validated against these schemas. A descriptor that passes schema validation is guaranteed to be renderable on all supported targets.

Rendering Targets

Conventions

• All $state paths begin with / and follow JSON Pointer syntax (RFC 6901).
• Props marked with StateRef accept either a literal value or a { "$state": "/path" } reference.
• Default sizes are in 12-column grid units.

Layout Blocks (4)

1. Column

Vertical stack of children. The fundamental top-to-bottom layout container.

Props Schema:

Ports: None Actions: None

Rendering Notes:

• Web: CSS flexbox flex-direction: column
• Terminal: Newline-separated children, each rendered sequentially
• HUD: Stacked lines, each child gets proportional line allocation

Example Descriptor:

{
  "version": "0.2.0",
  "root": "main",
  "elements": {
    "main": {
      "type": "Column",
      "props": { "gap": 12 },
      "children": ["child-a", "child-b"]
    },
    "child-a": { "type": "Metric", "props": { "label": "CPU", "value": 42, "unit": "%" } },
    "child-b": { "type": "Metric", "props": { "label": "Mem", "value": 78, "unit": "%" } }
  }
}

2. Row

Horizontal layout of children. Wraps when overflow occurs if wrap is true.

Props Schema:

Ports: None Actions: None

Rendering Notes:

• Web: CSS flexbox flex-direction: row
• Terminal: Columns side-by-side (using terminal column widths), falls back to vertical if insufficient width
• HUD: Side-by-side text segments separated by |

3. Grid

CSS grid layout for complex multi-row, multi-column arrangements.

Props Schema:

Ports: None Actions: None

Rendering Notes:

• Web: CSS Grid with grid-template-columns: repeat(N, 1fr)
• Terminal: Table-style layout with fixed column widths
• HUD: Not supported; falls back to Column layout

4. Tabs

Tabbed container. Each child corresponds to one tab, ordered by labels.

Props Schema:

Ports: None Actions: None

Rendering Notes:

• Web: Tab bar at top, content area below; only active tab rendered
• Terminal: [Tab1] Tab2 Tab3 header with active tab highlighted; content below
• HUD: Not supported; renders only the active tab content with no tab bar

Data Display Blocks (6)

5. Metric

Single-value gauge displaying a labeled numeric or string value with optional unit and threshold coloring.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Card with large value text, label above, unit suffix, color-coded border
• Terminal: CPU: 42% or CPU: [======== ] 42% (bar if threshold defined)
• HUD: Single line: CPU: 42% or with bar: CPU: [======== ] 42%

Example Descriptor:

{
  "version": "0.2.0",
  "root": "cpu",
  "elements": {
    "cpu": {
      "type": "Metric",
      "props": {
        "label": "CPU",
        "value": { "$state": "/kernel/metrics/cpu_percent" },
        "unit": "%",
        "threshold": { "warn": 70, "crit": 90 }
      }
    }
  }
}

6. DataTable

Tabular data display with optional sorting and row selection.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: HTML table with striped rows, click-to-select, sortable column headers
• Terminal: ASCII table with column alignment
• HUD: Fixed-width columns, max 4 columns visible, truncated to 8 rows

7. ChainViewer

ExoChain event log viewer. Displays recent chain events with filtering.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Scrollable list with expandable event detail. Color-coded by event kind.
• Terminal: One line per event: #1042 shell.exec process.spawn coder [PERMIT] 12ms
• HUD: Compact list, 1 line per event, max 6 visible

8. CausalGraph

Force-directed (or radial/tree) visualization of the ECC causal graph.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Interactive force-directed graph (d3-force or R3F for 3D). Drag, zoom, tooltips.
• Terminal: ASCII adjacency list with indentation
• HUD: Linearized causal chain (numbered list of events), max 6 visible

9. DiffViewer

Side-by-side or unified diff display for code changes.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Side-by-side diff with syntax highlighting (CodeMirror merge view)
• Terminal: Unified diff format with ANSI color (green/red)
• HUD: Not rendered; falls back to summary text: "N files changed, +A/-D lines"

10. CodeEditor

Source code editor/viewer powered by CodeMirror 6.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: CodeMirror 6 instance with theme, line numbers, folding
• Terminal: Syntax-highlighted text (read-only); no editing in terminal mode
• HUD: Not rendered; falls back to file name and line count summary

Interactive Blocks (5)

11. Button

Action trigger. Clicking (or voice-activating on HUD) dispatches a configured action.

Props Schema:

Ports: None

Actions: Configured via the on.press event handler in the descriptor.

Rendering Notes:

• Web: Styled button element, color per variant
• Terminal: [Spawn Coder] clickable text (if terminal supports hyperlinks) or labeled action
• HUD: Listed in the hint bar at bottom of screen as a voice command

Example Descriptor:

{
  "version": "0.2.0",
  "root": "btn",
  "elements": {
    "btn": {
      "type": "Button",
      "props": { "label": "Spawn Coder", "variant": "primary" },
      "on": {
        "press": {
          "action": "kernel_exec",
          "params": { "command": "process.spawn coder" }
        }
      }
    }
  }
}

12. ConsolePan

Embedded WeftOS terminal emulator. xterm.js-backed in Web mode. Full ShellAdapter integration.

Props Schema:

Ports:

Actions: Commands entered by the user dispatch kernel_exec actions internally.

Rendering Notes:

• Web: xterm.js instance with WebGL addon, ANSI color, tab completion
• Terminal: Passthrough (already in a terminal context); commands pipe to ShellAdapter
• HUD: Not directly rendered; voice commands route through the same ShellAdapter pipeline

13. ApprovalGate

Governance approval widget. Displays an action's EffectVector and allows approve/deny.

Props Schema:

Ports:

Actions: On approve/deny, dispatches governance_check action.

Rendering Notes:

• Web: Card showing EffectVector radar chart, risk score, approve/deny buttons
• Terminal: Text EffectVector + [APPROVE] [DENY] prompt
• HUD: Summary line + voice commands "approve" / "deny"

14. TextInput

Form input field for user text entry.

Props Schema:

Ports:

Actions: None (data flows via ports).

Rendering Notes:

• Web: Styled input element with label
• Terminal: Inline prompt: Label: [____]
• HUD: Not interactive (voice input only); renders as a display of current value

15. Markdown

Rich text / narrative display. Renders Markdown content.

Props Schema:

Ports: None Actions: None

Rendering Notes:

• Web: react-markdown with syntax highlighting for code blocks
• Terminal: Rendered via marked-terminal or plain text with basic formatting
• HUD: Plain text only, headings uppercased, code blocks ignored

OS Capability Blocks (3)

16. WebBrowser

Embedded WebView for browsing URLs. Uses Tauri's native WebView.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Tauri WebView with address bar, back/forward
• Terminal: Not rendered; shows URL as a hyperlink
• HUD: Not rendered; shows URL text only

17. ResourceTree

File/asset browser for the project's ExoResourceTree.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: Tree view with expand/collapse, file icons, click-to-select
• Terminal: Indented tree listing (like tree command)
• HUD: Flat list of top-level entries, max 8 visible

18. ServiceMap

2D or 3D mesh topology visualization showing services and their connections.

Props Schema:

Ports:

Actions: None

Rendering Notes:

• Web: D3 force-directed graph or hierarchical tree, color-coded by health
• Terminal: ASCII box-and-arrow diagram
• HUD: Radial topology view (same layout as RadialTopology block)

Nesting Rules

1. Only layout blocks (Column, Row, Grid, Tabs) may have children.
2. Maximum nesting depth: 6 levels. Prevents pathological recursion in agent-generated descriptors.
3. A child block cannot reference its ancestor's ports (prevents circular data flow).
4. Any block can serve as the root of its own descriptor (composability -- a saved assembly becomes a reusable block).

Validation

All descriptors MUST pass validation against block-descriptor-schema.json (JSON Schema draft 2020-12) before rendering. Additionally, each block's props must pass the block-type-specific Zod schema. A descriptor that passes both levels of validation is guaranteed renderable on all supported targets.