clawft

Block Catalog

All 18 built-in block types with props schemas, ports, actions, and rendering notes

Block Catalog

Status as of 0.8.4: design reference. ADR-013 (JSON block descriptor) is superseded by the egui shell, and the React and Tauri renderers this schema targeted were removed on 2026-10-18 (docs/adr/adr-013-json-block-descriptor.md, docs/adr/adr-038-tauri-desktop-shell.md). The shipped UI path is canon primitives plus TOML surface descriptions: see the GUI Layer guide. Nothing on this page describes a renderer you can run today.

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

TargetRendererContext
Web (React)@weftos/react-rendererFormer React GUI (removed 2026-10-18)
TerminalInk / xterm.js inlineConsolePan rich output, CLI mode
Mentra HUDConstraint engine (400x240, mono)Smart glasses display
ShellPlain text formatterPure SSH / headless mode

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.

FieldValue
TypeColumn
Has childrenYes
Default sizewidth: 12, height: auto

Props Schema:

PropTypeRequiredDefaultDescription
gapnumberNo8Vertical gap between children in pixels

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.

FieldValue
TypeRow
Has childrenYes
Default sizewidth: 12, height: auto

Props Schema:

PropTypeRequiredDefaultDescription
gapnumberNo8Horizontal gap between children in pixels
wrapbooleanNofalseWhether children wrap to next line on overflow

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.

FieldValue
TypeGrid
Has childrenYes
Default sizewidth: 12, height: auto

Props Schema:

PropTypeRequiredDefaultDescription
columnsnumberYes--Number of columns in the grid
gapnumberNo8Gap between grid cells in pixels

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.

FieldValue
TypeTabs
Has childrenYes (one per tab)
Default sizewidth: 12, height: 6

Props Schema:

PropTypeRequiredDefaultDescription
labelsstring[]Yes--Tab labels, one per child
activeTabnumberNo0Zero-based index of the initially active tab

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.

FieldValue
TypeMetric
Has childrenNo
Default sizewidth: 3, height: 2

Props Schema:

PropTypeRequiredDefaultDescription
labelstringYes--Human-readable label
valuenumber or StateRefYes--The metric value
unitstringNo--Unit suffix (e.g., "%", "MB", "events")
thresholdobjectNo--Warning/critical thresholds
threshold.warnnumberNo--Value above which the display turns yellow
threshold.critnumberNo--Value above which the display turns red

Ports:

PortDirectionData TypeDescription
valueoutnumberEmits current resolved value for downstream blocks

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.

FieldValue
TypeDataTable
Has childrenNo
Default sizewidth: 12, height: 6

Props Schema:

PropTypeRequiredDefaultDescription
columnsarray of {key, label}Yes--Column definitions
rowsStateRefYes--$state path to array of row objects
sortablebooleanNofalseWhether columns are sortable by click

Ports:

PortDirectionData TypeDescription
selectedRowoutobjectEmits the currently selected row object
filterinstringReceives a filter string to narrow visible rows

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.

FieldValue
TypeChainViewer
Has childrenNo
Default sizewidth: 12, height: 6

Props Schema:

PropTypeRequiredDefaultDescription
fromSeqnumberNo(latest)Starting sequence number
limitnumberNo50Maximum events to display
filterstringNo--Filter string for event kind or source

Ports:

PortDirectionData TypeDescription
selectedEventoutChainEventEmits the currently selected chain event

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.

FieldValue
TypeCausalGraph
Has childrenNo
Default sizewidth: 12, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
depthnumberNo3Graph traversal depth from root nodes
querystringNo--HNSW semantic query to select root nodes
layout"force" or "tree" or "radial"No"force"Graph layout algorithm

Ports:

PortDirectionData TypeDescription
selectedNodeoutCausalNodeEmits the currently selected graph node
highlightinstring[]Receives node IDs to highlight

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.

FieldValue
TypeDiffViewer
Has childrenNo
Default sizewidth: 12, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
leftstring or StateRefYes--Left (before) content
rightstring or StateRefYes--Right (after) content
languagestringNo"text"Syntax highlighting language

Ports:

PortDirectionData TypeDescription
selectedHunkoutDiffHunkEmits the currently selected diff hunk

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.

FieldValue
TypeCodeEditor
Has childrenNo
Default sizewidth: 12, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
valuestring or StateRefYes--Source code content
languagestringYes--Syntax highlighting language
readOnlybooleanNofalseWhether editing is disabled

Ports:

PortDirectionData TypeDescription
contentoutstringEmits current editor content on change
cursorout{line, col}Emits cursor position on move

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.

FieldValue
TypeButton
Has childrenNo
Default sizewidth: 2, height: 1

Props Schema:

PropTypeRequiredDefaultDescription
labelstringYes--Button text
variant"primary" or "secondary" or "danger"No"primary"Visual variant
disabledbooleanNofalseWhether the button is disabled

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.

FieldValue
TypeConsolePan
Has childrenNo
Default sizewidth: 12, height: 6

Props Schema:

PropTypeRequiredDefaultDescription
initialCommandstringNo--Command to execute on mount
contextServicestringNo--Pre-scoped service namespace (e.g., "ecc" makes all commands default to ecc.*)

Ports:

PortDirectionData TypeDescription
lastOutputoutShellResultEmits the result of the last executed command
injectinstringReceives a command string to execute programmatically

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.

FieldValue
TypeApprovalGate
Has childrenNo
Default sizewidth: 6, height: 4

Props Schema:

PropTypeRequiredDefaultDescription
actionstringYes--The action being gated (e.g., "process.spawn coder")
effect_vectorStateRefYes--$state path to the computed EffectVector

Ports:

PortDirectionData TypeDescription
decisionout"permit" or "deny"Emits the user's governance decision

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.

FieldValue
TypeTextInput
Has childrenNo
Default sizewidth: 6, height: 1

Props Schema:

PropTypeRequiredDefaultDescription
labelstringYes--Field label
placeholderstringNo--Placeholder text
valuestring or StateRefNo""Initial/bound value

Ports:

PortDirectionData TypeDescription
valueoutstringEmits current input value on change

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.

FieldValue
TypeMarkdown
Has childrenNo
Default sizewidth: 12, height: auto

Props Schema:

PropTypeRequiredDefaultDescription
contentstring or StateRefYes--Markdown text to render
allowHtmlbooleanNofalseWhether embedded HTML is allowed (security consideration)

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 (specified for the removed Tauri shell).

FieldValue
TypeWebBrowser
Has childrenNo
Default sizewidth: 12, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
urlstringYes--Initial URL to load
allowNavigationbooleanNotrueWhether the user can navigate away from the initial URL

Ports:

PortDirectionData TypeDescription
currentUrloutstringEmits the current URL after navigation

Actions: None

Rendering Notes:

  • Web: 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.

FieldValue
TypeResourceTree
Has childrenNo
Default sizewidth: 4, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
rootPathstringNo"/"Root path to display
filterstringNo--Glob filter for visible entries

Ports:

PortDirectionData TypeDescription
selectedPathoutstringEmits the path of the selected file/directory

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.

FieldValue
TypeServiceMap
Has childrenNo
Default sizewidth: 12, height: 8

Props Schema:

PropTypeRequiredDefaultDescription
layout"force" or "hierarchical"No"force"Layout algorithm
showScoresbooleanNofalseWhether to display health scores on nodes

Ports:

PortDirectionData TypeDescription
selectedServiceoutServiceEntryEmits the currently selected service node

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.

On this page