pmx-canvas 0.1.17 → 0.1.19

package/docs/node-types.md

@@ -0,0 +1,244 @@
+# Node types
+
+Canvas nodes are typed. Each type has a dedicated renderer, schema, and (for
+structured types) a dedicated MCP tool. This page is the user-facing reference
+for what each type is for and how to create one. For tool/HTTP/SDK signatures,
+see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
+
+## Overview
+
+| Type | Purpose |
+|------|---------|
+| `markdown` | Rich markdown with rendered preview |
+| `status` | Compact status indicator (phase, message, elapsed time) |
+| `context` | Context cards, token usage, workspace grounding |
+| `ledger` | Execution ledger summary |
+| `trace` | Agent trace pills (tool calls, subagent activity) |
+| `file` | Live file viewer with auto-update on disk changes |
+| `image` | Image viewer (file paths, data URIs, URLs) |
+| `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
+| `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |
+| `json-render` | Structured UI from JSON specs (cards, tables, forms) |
+| `graph` | Charts (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `html` | Self-contained HTML/JS in a sandboxed iframe |
+| `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
+| `group` | Spatial container/frame around other nodes |
+
+Thread node types `prompt` and `response` exist internally for agent
+conversation rendering and are not created through public APIs.
+
+## Choosing the right visual tier
+
+Three rendering tiers cover increasing levels of complexity. Pick the lowest
+that fits the work — each step adds capability and bundle weight.
+
+| Tier | Type | Use when | Bundle weight |
+|------|------|----------|---------------|
+| 1 | `json-render` | You can describe the UI as a spec (forms, tables, dashboards from a component catalog) | None — runtime already loaded |
+| 2 | `html` | You have/can write self-contained HTML+JS (Chart.js, D3, custom widgets, interactive demos) | None — sandboxed iframe |
+| 3 | `web-artifact` | You need a full React/Tailwind app with shadcn components, routing, or shared state | Build step |
+
+## File nodes
+
+File nodes display project files with line numbers and language detection.
+When an agent edits a file through its normal tools, the canvas node updates
+automatically via `fs.watch()`.
+
+```ts
+canvas_add_node({ type: 'file', content: 'src/server/index.ts' })
+```
+
+## Image nodes
+
+Image nodes display local paths, remote URLs, and data URIs. File-backed and
+HTTP(S)-backed images preserve provenance so agents can tell where evidence
+came from. Nodes can carry validation status or warnings.
+
+```ts
+canvas_add_node({
+  type: 'image',
+  content: 'artifacts/dashboard.png',
+  data: {
+    validationStatus: 'passed',
+    validationMessage: 'Screenshot matches the requested dashboard state.',
+  },
+})
+```
+
+## Webpage nodes
+
+Webpage nodes store the source URL on the node, fetch the page server-side,
+and cache extracted text for search, pins, and agent context. Saved canvases
+keep enough information for an agent to refresh the node from the original
+URL later.
+
+```ts
+canvas_add_node({ type: 'webpage', url: 'https://example.com/docs' })
+canvas_refresh_webpage_node({ id: 'node-abc123' })
+```
+
+## MCP App nodes
+
+`mcp-app` nodes embed other MCP servers' UI resources (`ui://...`) directly
+on the canvas as sandboxed iframes. Any server implementing the
+[MCP Apps extension](https://modelcontextprotocol.io/docs/extensions/apps)
+can be opened with `canvas_open_mcp_app`.
+
+Generic `pmx-canvas node add --type mcp-app` is intentionally rejected —
+these nodes need tool/session metadata. Use `canvas_open_mcp_app` (or the
+`canvas_add_diagram` Excalidraw preset) instead.
+
+### Excalidraw preset (hand-drawn diagrams)
+
+[Excalidraw](https://github.com/excalidraw/excalidraw-mcp) ships a hosted MCP
+server at `https://mcp.excalidraw.com/mcp`. PMX Canvas exposes a one-call
+preset:
+
+```ts
+canvas_add_diagram({
+  elements: [
+    { type: 'rectangle', id: 'a', x: 80, y: 120, width: 180, height: 80,
+      roundness: { type: 3 }, backgroundColor: '#a5d8ff', fillStyle: 'solid',
+      label: { text: 'Agent', fontSize: 18 } },
+    { type: 'rectangle', id: 'b', x: 380, y: 120, width: 180, height: 80,
+      roundness: { type: 3 }, backgroundColor: '#d0bfff', fillStyle: 'solid',
+      label: { text: 'PMX Canvas', fontSize: 18 } },
+    { type: 'arrow', id: 'a1', x: 260, y: 160, width: 120, height: 0,
+      startBinding: { elementId: 'a' }, endBinding: { elementId: 'b' },
+      label: { text: 'adds nodes' } },
+  ],
+  title: 'Agent → Canvas',
+});
+```
+
+For any other MCP App, call `canvas_open_mcp_app` directly with the server's
+transport, tool name, and arguments.
+
+## json-render nodes
+
+`json-render` nodes turn structured JSON specs into rendered UI panels
+(dashboards, tables, forms, cards) without writing HTML. PMX Canvas ships the
+[`@json-render/*`](https://www.npmjs.com/package/@json-render/core) runtime
+and component catalog (core + react + shadcn).
+
+```ts
+canvas_add_json_render_node({
+  title: 'Deploy status',
+  spec: {
+    root: 'card',
+    elements: {
+      card: { type: 'Card', props: { title: 'Deploy' }, children: ['status'] },
+      status: { type: 'Badge', props: { variant: 'default', text: 'Healthy' } },
+    },
+  },
+});
+```
+
+`Badge` uses shadcn variants: `default`, `secondary`, `destructive`,
+`outline`. Older saved specs using `label` or status variants such as
+`success`/`warning` are normalized during validation.
+
+Use `canvas_describe_schema` / `canvas_validate_spec` to introspect the
+component catalog before building a spec.
+
+## HTML nodes
+
+`html` nodes render a self-contained HTML/JS document in a sandboxed iframe.
+They sit between `json-render` (no custom JS) and `web-artifact` (full bundled
+React app) — perfect for Chart.js, D3, custom widgets, and any HTML you can
+write or paste.
+
+The sandbox runs with `allow-scripts` only — no same-origin access, no
+top-level navigation, no form submission. Inline `<script>` and CDN
+`<script src>` both work. The canvas auto-injects its theme tokens
+(`--c-*` and `--color-*` aliases) into the iframe `<head>` so artifacts can
+match the active theme.
+
+```ts
+canvas_add_html_node({
+  title: 'Cost projection',
+  html: '<canvas id="c"></canvas><script src="https://cdn.jsdelivr.net/npm/chart.js"></script><script>...</script>',
+})
+```
+
+A fragment without `<html>`/`<head>` is wrapped in a full document
+automatically. Default size is 720×640.
+
+## Web artifacts
+
+A **web artifact** is a single-file, fully bundled HTML app (React + Tailwind
++ shadcn) the agent builds from TSX source. Use it when the work calls for a
+real interactive app — charts, forms, mini-dashboards — beyond what a static
+node or `html` snippet can express.
+
+`canvas_build_web_artifact` takes source strings (`App.tsx`, optional
+`index.css`, `main.tsx`, `index.html`, plus extra files), runs the bundled
+web-artifacts-builder scripts, writes the self-contained HTML to
+`.pmx-canvas/artifacts/<slug>.html`, and (by default) opens it in the canvas.
+
+```bash
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+```
+
+The scaffold includes `recharts`. Pass `--deps name,name2` for additional
+package dependencies. Failed or empty CLI bundles print `ok: false`, exit
+non-zero, and do not create a canvas node.
+
+The matching agent skill is at
+[`skills/web-artifacts-builder/SKILL.md`](../skills/web-artifacts-builder/SKILL.md).
+
+## Groups
+
+Groups are spatial containers that visually contain other nodes. They render
+as dashed-border frames with a title bar and optional accent color.
+
+- Select 2+ nodes and click "Group" in the selection bar
+- Right-click a group to ungroup
+- Collapsing a group hides children and shows a summary
+- By default, group creation preserves the children's current positions and
+  expands the frame around them
+- Pass `childLayout` to auto-pack children (`grid`, `column`, `flow`)
+- Pass explicit `x`, `y`, `width`, and `height` to create a manual frame and
+  lay children out inside it
+
+```ts
+canvas_create_group({ title: 'Auth Module', childIds: ['node-1', 'node-2'], color: '#4a9eff' })
+```
+
+## Edge types
+
+All edges support labels, styles (solid/dashed/dotted), and animation.
+
+| Type | Use case |
+|------|----------|
+| `flow` | Sequential steps, data flow |
+| `depends-on` | Dependencies between tasks |
+| `relation` | General relationships |
+| `references` | Cross-references, evidence links |
+
+## Schema-driven discovery
+
+Agents don't have to guess node shapes. The running server exposes its create
+schemas, json-render component catalog, and node-type examples:
+
+- `canvas_describe_schema` / `GET /api/canvas/schema` — list all node-create
+  schemas, required fields, json-render components, and sample payloads
+- `canvas_validate_spec` / `POST /api/canvas/schema/validate` — validate a
+  json-render spec or graph payload **without** creating a node
+- `canvas_validate` / `GET /api/canvas/validate` — validate the current
+  layout for collisions, containment, and missing edge endpoints
+- `canvas://schema` — the same data as an MCP resource
+
+The CLI's `node schema` / `validate spec` subcommands surface the same data
+from the terminal.
+
+MCP node creation uses dedicated tools for structured node families. Read
+`mcp.nodeTypeRouting` from `canvas_describe_schema` when in doubt:
+`json-render` → `canvas_add_json_render_node`,
+`graph` → `canvas_add_graph_node`,
+`html` → `canvas_add_html_node`,
+`web-artifact` → `canvas_build_web_artifact`,
+`mcp-app` → `canvas_open_mcp_app`,
+`group` → `canvas_create_group`.
+Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) use
+`canvas_add_node`.

package/docs/plans/plan-001-semantic-watch-mvp.md

@@ -0,0 +1,335 @@
+---
+title: Semantic Watch CLI MVP
+status: draft
+date: 2026-04-18
+---
+
+# Semantic Watch CLI MVP
+
+## Summary
+
+Add a new agent-facing CLI command:
+
+```bash
+pmx-canvas watch
+```
+
+The command connects to the existing `/api/workbench/events` SSE stream and emits
+compact, low-token summaries of **meaningful human intent changes** on the canvas.
+
+This is **not** a raw browser telemetry tap. The watcher consumes authoritative
+server events, keeps prior layout state locally, computes semantic diffs locally,
+and emits one compact line or one JSON object only when the canvas state makes a
+changed intent legible.
+
+## Problem
+
+PMX Canvas promises that spatial arrangement is communication and that pinned
+context closes the human-to-agent loop. In practice, only pins cross that
+boundary reliably today.
+
+The current gap:
+
+- agents can poll resources like `canvas://pinned-context` and
+  `canvas://spatial-context`
+- browsers receive rich SSE updates
+- there is no CLI primitive that turns those updates into a low-noise,
+  low-token stream that an agent or hook can follow
+
+## Goals
+
+- Provide a long-running `watch` command for agents and hooks.
+- Reuse the existing `/api/workbench/events` SSE stream.
+- Reduce full layout snapshots into compact semantic deltas locally.
+- Keep token cost low by suppressing raw gesture noise.
+- Expose a machine-readable mode for hooks and automation.
+
+## Non-Goals
+
+- No new browser-only collaboration protocol.
+- No raw pointer, drag-frame, or selection telemetry.
+- No `select` event in v1.
+- No `collapse` event in v1 until collapsed state is synced immediately and
+  authoritatively to the server.
+- No node content/body text in watch output.
+- No attempt to narrate every movement; only semantic movement changes.
+
+## Authoritative Signal Sources
+
+The command must only depend on signals the server can already observe.
+
+### Existing sources
+
+- `GET /api/workbench/events`
+  - initial `canvas-layout-update` snapshot on connect
+  - subsequent `canvas-layout-update` envelopes on node/edge/layout mutations
+  - `context-pins-changed` on pin updates
+- `GET /api/canvas/pinned-context`
+  - initial current pin set on watcher startup
+- local semantic derivation using `buildSpatialContext(...)`
+
+### Explicitly excluded from v1
+
+- client-only `selectedNodeIds`
+- locally toggled `collapsed` state that has not yet been persisted
+
+## CLI UX
+
+### Command
+
+```bash
+pmx-canvas watch [options]
+```
+
+### Output modes
+
+- Default: compact human-readable lines
+- `--compact`: explicit compact mode (same as default)
+- `--json`: emit one JSON object per semantic event, JSONL-style
+
+`--compact` and `--json` are mutually exclusive.
+
+### Filters
+
+```bash
+--events context-pin,move-end,group,connect,remove
+```
+
+Supported semantic event kinds in v1:
+
+- `context-pin`
+- `move-end`
+- `group`
+- `connect`
+- `remove`
+
+If omitted, all v1 semantic kinds are enabled.
+
+### Control flags
+
+```bash
+--max-events 3
+```
+
+Stop after emitting N semantic events. This exists mainly to support scripted
+usage and unit tests without changing the default streaming behavior.
+
+## Event Model
+
+### 1. `context-pin`
+
+Source:
+
+- direct `context-pins-changed` SSE event
+
+Payload:
+
+- added pinned node IDs/titles
+- removed pinned node IDs/titles
+
+Rules:
+
+- emit only when the pin set actually changed
+- do not emit on startup bootstrap
+
+Compact example:
+
+```text
+context-pin +2 -1: "Bug report", "auth.ts" | removed: "old note"
+```
+
+JSON example:
+
+```json
+{"type":"context-pin","added":[{"id":"n1","title":"Bug report","nodeType":"markdown"}],"removed":[]}
+```
+
+### 2. `connect`
+
+Source:
+
+- added edges in a `canvas-layout-update` diff
+
+Payload:
+
+- added edges with `from`, `to`, edge type, and node titles when available
+
+Rules:
+
+- emit for newly added edges only
+- ignore unchanged edges
+
+Compact example:
+
+```text
+connect 1: "Bug report" -> "auth.ts" (relation)
+```
+
+### 3. `remove`
+
+Source:
+
+- removed nodes and removed edges in a `canvas-layout-update` diff
+
+Payload:
+
+- removed node summaries
+- removed edge summaries
+
+Rules:
+
+- emit only for removals after bootstrap
+- group all removals from one layout update into one semantic event
+
+Compact example:
+
+```text
+remove 2 nodes: "Old note", "scratch.ts"
+```
+
+### 4. `group`
+
+Source:
+
+- group node creation or group membership change detected from layout diffs
+
+Payload:
+
+- created groups
+- membership changes for existing groups
+- child additions/removals by group
+
+Rules:
+
+- treat new `group` nodes as group creation
+- compare `group.data.children` arrays for membership deltas
+- emit one grouped summary per layout update
+
+Compact examples:
+
+```text
+group created: "API Group" (2 children)
+group updated: "API Group" +1 -0 children
+```
+
+### 5. `move-end`
+
+Source:
+
+- node position changes between two `canvas-layout-update` snapshots
+
+Important:
+
+- derive from **layout diffs**, not pointer events
+- emit only when movement caused a semantic change
+
+Semantic triggers:
+
+- the moved node’s proximity-cluster peers changed
+- the moved node entered or left a pinned neighborhood
+- a pinned node moved and its neighborhood changed
+
+Rules:
+
+- suppress pure coordinate churn
+- suppress movement that did not change spatial meaning
+- ignore newly created or removed nodes when computing move-end
+
+Compact examples:
+
+```text
+move-end: "auth.ts" cluster changed
+move-end: "session.ts" entered pinned neighborhood of "Bug report"
+```
+
+## Bootstrap Behavior
+
+On startup:
+
+1. fetch current pins from `/api/canvas/pinned-context`
+2. connect to `/api/workbench/events`
+3. accept the initial `canvas-layout-update` snapshot as the baseline
+4. emit nothing during bootstrap
+
+This avoids startup noise and prevents the watcher from replaying the whole
+canvas as if it were a fresh user action stream.
+
+## Local Reduction Algorithm
+
+Maintain local watcher state:
+
+- `currentLayout`
+- `currentPinnedIds`
+- derived `previousSpatialContext`
+
+On each relevant SSE event:
+
+### `context-pins-changed`
+
+- diff old pin set vs new pin set
+- emit `context-pin` if changed
+- update `currentPinnedIds`
+- recompute local spatial context baseline
+
+### `canvas-layout-update`
+
+- if no baseline exists, store it and stop
+- diff previous layout vs next layout
+- emit `connect`, `remove`, and `group` events from structural diffs
+- compute old/new spatial context with the current pin set
+- detect moved nodes
+- emit `move-end` only for nodes whose movement changed:
+  - cluster peers
+  - pinned-neighborhood membership
+- replace baseline with the new layout/spatial context
+
+## Token Budget Rules
+
+The watcher exists to save tokens, so its output contract must stay strict.
+
+Rules:
+
+- no full layout snapshots in emitted output
+- no node body text or file content
+- no duplicate emission for unchanged semantic state
+- one semantic event object/line per meaning change, not per low-level SSE frame
+- compact mode should usually stay under one short line per event
+
+## Implementation Plan
+
+### Files
+
+- add a new CLI watcher module for:
+  - SSE parsing
+  - semantic reduction
+  - compact/JSON formatting
+- wire the command into `src/cli/agent.ts`
+- add `watch` to `src/cli/index.ts` command help/router
+- add unit coverage for:
+  - context pin diffs
+  - connect/remove diffs
+  - group diffs
+  - move-end semantic suppression and emission
+
+### Reuse
+
+- reuse `/api/workbench/events`
+- reuse `/api/canvas/pinned-context`
+- reuse `buildSpatialContext(...)`
+
+## Verification Plan
+
+- unit tests for semantic reducer behavior
+- unit tests for CLI watch output/filtering
+- `bun run test`
+
+If implementation touches browser-visible UI or client code later, escalate
+verification. For this MVP, CLI/server-side verification is expected to be
+sufficient.
+
+## Deferred Work
+
+- watchable `collapse` after immediate server sync exists
+- explicit `cluster-changed` or `neighborhood-changed` top-level event kinds
+- reconnect/backoff behavior for long-lived watches
+- MCP-side semantic watcher surface if needed later