pmx-canvas 0.1.18 → 0.1.20

package/docs/bun-webview-integration.md

@@ -0,0 +1,296 @@
+# Bun.WebView Integration
+
+PMX Canvas now uses Bun's built-in `Bun.WebView` API for **headless canvas automation**, while keeping the current external browser launcher for the normal interactive canvas window.
+
+This document tracks:
+
+- what is implemented today
+- what was validated on stable Bun `v1.3.12`
+- what still remains future work
+
+## Current Status
+
+**Implemented** for Phase 1.
+
+The repo now targets Bun `>=1.3.12`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
+
+- start a headless browser session for `/workbench`
+- report WebView runtime status
+- evaluate JavaScript in the page
+- resize the automation viewport
+- capture screenshots
+- stop and clean up the automation session explicitly
+
+What is **not** implemented:
+
+- replacing `openUrlInExternalBrowser()` for the visible user-facing canvas window
+- headed Bun.WebView window support
+- Chrome-only CDP tooling
+
+## Why This Exists
+
+The existing browser-launch path in [`src/server/server.ts`](../src/server/server.ts) still opens the interactive canvas with platform-specific shell behavior:
+
+- macOS: AppleScript / `osascript`
+- Windows: `cmd /c start` or a resolved browser executable
+- Linux: `xdg-open`
+
+That path is still appropriate for humans, but it provides no programmatic control once the browser is open.
+
+`Bun.WebView` gives PMX Canvas a controlled browser session that the server can own directly. That unlocks:
+
+- agent-visible screenshots
+- browser-backed evaluation of rendered canvas state
+- controlled viewport sizing
+- future browser automation tools without depending on Playwright for the basic runtime
+
+## Implemented Surface
+
+### Server layer
+
+Implemented in [`src/server/server.ts`](../src/server/server.ts):
+
+- `getCanvasAutomationWebViewStatus()`
+- `startCanvasAutomationWebView(url, options)`
+- `stopCanvasAutomationWebView()`
+- `evaluateCanvasAutomationWebView(expression)`
+- `resizeCanvasAutomationWebView(width, height)`
+- `screenshotCanvasAutomationWebView(options)`
+
+Important behavior:
+
+- runtime-gated: if `Bun.WebView` is unavailable, PMX Canvas returns a clear error
+- headless-only: PMX Canvas does not rely on `headless: false`
+- explicit lifecycle: start and stop are owned by the server
+- screenshot normalization handles Bun return types correctly, including `Blob`
+
+### HTTP API
+
+Implemented in [`src/server/server.ts`](../src/server/server.ts):
+
+- `GET /api/workbench/webview`
+- `POST /api/workbench/webview/start`
+- `POST /api/workbench/webview/evaluate`
+- `POST /api/workbench/webview/resize`
+- `POST /api/workbench/webview/screenshot`
+- `DELETE /api/workbench/webview`
+
+Current HTTP behavior:
+
+- `GET` returns runtime support plus active-session status
+- `POST` starts a new headless automation session for the current `/workbench`
+- `POST /evaluate` runs JavaScript in the active automation session and returns JSON
+- `POST /resize` updates the active automation viewport and returns JSON status
+- `POST /screenshot` returns image bytes for the active automation session
+- `DELETE` stops the current automation session
+
+Current options accepted by `POST /api/workbench/webview/start`:
+
+- `backend`: `"chrome"` or `"webkit"`
+- `width`
+- `height`
+- `chromePath`
+- `chromeArgv`
+- `dataStoreDir`
+
+### SDK
+
+Implemented in [`src/server/index.ts`](../src/server/index.ts):
+
+- `canvas.start({ automationWebView: ... })`
+- `canvas.startAutomationWebView(options)`
+- `canvas.stopAutomationWebView()`
+- `canvas.getAutomationWebViewStatus()`
+- `canvas.evaluateAutomationWebView(expression)`
+- `canvas.resizeAutomationWebView(width, height)`
+- `canvas.screenshotAutomationWebView(options)`
+
+### CLI
+
+Implemented in [`src/cli/index.ts`](../src/cli/index.ts):
+
+- `--webview-automation`
+- `--webview-backend`
+- `--webview-width`
+- `--webview-height`
+- `--webview-chrome-path`
+- `--webview-chrome-argv`
+- `--webview-data-dir`
+
+Implemented in [`src/cli/agent.ts`](../src/cli/agent.ts):
+
+- `pmx-canvas webview status`
+- `pmx-canvas webview start`
+- `pmx-canvas webview evaluate`
+- `pmx-canvas webview resize`
+- `pmx-canvas webview screenshot`
+- `pmx-canvas webview stop`
+
+Example:
+
+```bash
+pmx-canvas --no-open --webview-automation
+pmx-canvas --webview-automation --webview-backend=chrome
+pmx-canvas webview start --backend chrome --width 1440 --height 900
+pmx-canvas webview evaluate --expression "document.title"
+pmx-canvas webview resize --width 1280 --height 800
+pmx-canvas webview screenshot --output ./canvas.png
+pmx-canvas webview stop
+```
+
+These flags are intentionally automation-only. They do **not** imply a visible Bun-managed window.
+
+### MCP
+
+Implemented in [`src/mcp/server.ts`](../src/mcp/server.ts):
+
+- `canvas_webview_status`
+- `canvas_webview_start`
+- `canvas_webview_stop`
+- `canvas_evaluate`
+- `canvas_resize`
+- `canvas_screenshot`
+
+Current MCP behavior:
+
+- automation lifecycle is explicit rather than implicit
+- screenshot returns an MCP image payload plus JSON metadata
+- evaluate/resize/screenshot require an active automation session
+- start accepts the same backend/viewport/data-store options as the server layer
+
+## Backend Strategy
+
+PMX Canvas follows Bun's current stable backend reality.
+
+### WebKit backend
+
+- macOS only
+- good default on macOS when CDP is not required
+- zero external Chrome dependency
+
+### Chrome backend
+
+- required on Linux and Windows
+- also supported on macOS
+- preferred when backend consistency or future CDP-based tooling matters
+
+### Current default behavior
+
+PMX Canvas defaults to:
+
+- `webkit` on macOS
+- `chrome` elsewhere
+
+If `chromePath` or `chromeArgv` is provided, PMX Canvas forces a Chrome-backed session.
+
+## Bun Runtime Requirements
+
+The repo now requires:
+
+- Bun `>=1.3.12`
+
+That change is reflected in:
+
+- [`package.json`](../package.json)
+- [`.github/workflows/test.yml`](../.github/workflows/test.yml)
+
+PMX Canvas still keeps a runtime guard because older local Bun versions can exist in user environments. If `Bun.WebView` is missing, startup fails cleanly for the automation path instead of partially starting.
+
+## Validation Results
+
+Validated on Bun `v1.3.12`.
+
+### Unit coverage
+
+Verified by tests in:
+
+- [`tests/unit/server-api.test.ts`](../tests/unit/server-api.test.ts)
+- [`tests/unit/cli-webview.test.ts`](../tests/unit/cli-webview.test.ts)
+- [`tests/unit/webview-automation.test.ts`](../tests/unit/webview-automation.test.ts)
+
+Covered behavior:
+
+- WebView status over HTTP
+- start/stop lifecycle over HTTP
+- evaluate/resize/screenshot over HTTP
+- CLI status/start/evaluate/resize/screenshot/stop commands
+- graceful unsupported-runtime handling
+- SDK start/evaluate/resize/screenshot flow
+
+### Live runtime smoke
+
+Validated manually after upgrading the local runtime to Bun `1.3.12`:
+
+- `pmx-canvas --port=4529 --no-open --webview-automation --webview-backend=chrome`
+- `GET /api/workbench/webview`
+- `DELETE /api/workbench/webview`
+- SDK smoke with:
+  - `startAutomationWebView`
+  - `evaluateAutomationWebView('document.title')`
+  - `resizeAutomationWebView(...)`
+  - `screenshotAutomationWebView(...)`
+
+Observed results:
+
+- automation session started successfully
+- status endpoint reported `active: true`
+- JS evaluation returned `"PMX Canvas"`
+- viewport resize updated status correctly
+- screenshots returned non-zero image bytes on both WebKit and Chrome backends during smoke testing
+
+## Implementation Notes
+
+### Screenshot normalization bug
+
+During real runtime validation, a bug was found in the first implementation:
+
+- PMX Canvas assumed `view.screenshot()` returned only `Uint8Array` or `ArrayBuffer`
+- on this machine, Bun could also return a `Blob`
+- that caused zero-byte screenshots in the wrapper even though Bun was returning valid image data
+
+This was fixed in [`src/server/server.ts`](../src/server/server.ts) by normalizing:
+
+- `Uint8Array`
+- `ArrayBuffer`
+- `Blob`
+
+The regression is now covered by [`tests/unit/webview-automation.test.ts`](../tests/unit/webview-automation.test.ts).
+
+### Why the interactive browser path still exists
+
+Even with Bun `v1.3.12`, PMX Canvas should still keep `openUrlInExternalBrowser()` for the normal canvas window because Bun's current documented WebView surface is still effectively headless automation. There is no reason yet to promise a headed replacement window to users.
+
+## Known Limits
+
+These are current, accepted constraints:
+
+- no visible Bun-managed canvas window
+- no persistent automation-session orchestration beyond the single owned server session
+- no Chrome-only CDP tool surface yet
+
+## Future Work
+
+### Near-term
+
+The most obvious next steps are:
+
+1. Add an optional `canvas_cdp` MCP tool for Chrome-backed sessions only
+2. Decide whether the default macOS backend should stay `webkit` or move to `chrome` for stricter cross-platform parity
+3. Add more backend-specific test coverage if Bun behavior diverges between WebKit and Chrome
+
+### Later
+
+Defer these until Bun's API justifies them:
+
+1. Replace `openUrlInExternalBrowser()` with Bun.WebView for the normal interactive canvas window
+2. Add headed window management semantics
+3. Build user-facing browser controls around Bun.WebView if Bun documents those behaviors as stable
+
+## Decision Summary
+
+The project should continue with this split:
+
+- **Interactive canvas for humans**: external browser
+- **Programmatic canvas automation for agents/server workflows**: Bun.WebView
+
+That keeps the current user-facing behavior stable while giving PMX Canvas a real browser automation surface that is built into the runtime.

package/docs/cli.md

@@ -0,0 +1,143 @@
+# CLI reference
+
+The CLI is the shell-native way to run and control PMX Canvas. It targets
+`http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
+`PMX_CANVAS_PORT` when the server runs elsewhere.
+
+## Server lifecycle
+
+```bash
+pmx-canvas                            # Start canvas, open browser
+pmx-canvas --demo                     # Start with the saved dashboard demo board
+pmx-canvas --port=8080                # Custom port
+pmx-canvas --no-open                  # Headless (for agents/CI)
+pmx-canvas --theme=light              # dark | light | high-contrast
+pmx-canvas --mcp                      # Run as MCP server (stdio)
+pmx-canvas --webview-automation       # Start headless Bun.WebView session
+pmx-canvas open                       # Open the current workbench in a browser
+```
+
+### Daemon mode
+
+Run detached with pid/log tracking instead of holding a terminal:
+
+```bash
+pmx-canvas serve --daemon --no-open --wait-ms=20000   # Start detached, wait for health
+pmx-canvas serve status                               # Inspect daemon health + pid
+pmx-canvas serve stop                                 # Stop the daemon for this port
+```
+
+## Nodes and edges
+
+```bash
+pmx-canvas node add --type webpage --url https://example.com/docs
+pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
+pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
+pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y   # Alias
+pmx-canvas html primitive add --kind choice-grid --data-file ./options.json --title "Options"
+pmx-canvas html primitive schema --summary
+pmx-canvas node add --help --type webpage --json                                        # Schema for one type
+
+pmx-canvas external-app add --kind excalidraw --title "Diagram"
+
+pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
+```
+
+`--from-search` / `--to-search` must each resolve to exactly one node — broad
+queries fail rather than guess. Use the full visible title.
+
+CLI create commands return the created node shape with normalized title,
+content, and geometry, which makes scripting stacked layouts and batch
+follow-ups easier.
+
+### Graph height flags
+
+Graph height flags split by target:
+
+- `--node-height` / `--nodeHeight` — the canvas node frame
+- `--chart-height` — the chart content inside the node
+- `--height` — accepted as a frame-height compatibility alias
+
+For MCP/HTTP payloads, use `nodeHeight` for the frame and `height` for chart
+content.
+
+## Discovery and validation
+
+```bash
+pmx-canvas node schema --type json-render --component Table --summary
+pmx-canvas validate                                                      # Layout validation
+pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
+pmx-canvas validate spec --type html-primitive --kind choice-grid --data-json '{"items":[{"title":"A"}]}' --summary
+```
+
+The schema commands surface the running server's data, which is strictly
+better than guessing flags or payloads.
+
+## Batch and arrange
+
+```bash
+pmx-canvas batch --file ./canvas-ops.json
+```
+
+See [HTTP API → batch](http-api.md#batch-operations) for the operation
+schema; the same JSON works for the CLI batch file.
+
+## Web artifacts
+
+```bash
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+```
+
+Failed or empty CLI bundles print `ok: false`, exit non-zero, and do not
+create a canvas node.
+
+## Watch (semantic deltas)
+
+`pmx-canvas watch` consumes the SSE stream and emits compact semantic deltas
+for agents that need low-token updates instead of full layout snapshots. It
+filters noise from harmless moves and reports meaningful events such as pins,
+node additions/removals, group changes, edge connections, and moves that
+change spatial clustering.
+
+```bash
+pmx-canvas watch --events context-pin,move-end
+pmx-canvas watch --json --events context-pin --max-events 1
+```
+
+## Focus
+
+```bash
+pmx-canvas focus <node-id>            # Pan viewport to a node
+pmx-canvas focus <node-id> --no-pan   # Select/raise without panning
+```
+
+## WebView automation
+
+Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:
+
+```bash
+pmx-canvas webview status
+pmx-canvas webview start --backend chrome --width 1440 --height 900
+pmx-canvas webview evaluate --expression "document.title"
+pmx-canvas webview resize --width 1280 --height 800
+pmx-canvas webview screenshot --output ./canvas.png
+pmx-canvas webview stop
+```
+
+Use WebView for visual annotation inspection. Agent-readable canvas context only
+reports annotation targets and bounds; it does not describe whether the human
+drew an arrow, line, circle, or other shape. Inspect `.annotation-layer path` or
+take a screenshot when the drawn form matters.
+
+Humans draw with the pen toolbar button and remove marks with the eraser button.
+If an agent already knows the annotation ID from context, it can remove it through
+MCP with `canvas_remove_annotation`.
+
+## When to reach for the CLI
+
+- Direct terminal control without MCP wiring
+- Shell scripts and CI-friendly automation
+- Schema-driven discovery from the running server
+- Local debugging of canvas, webview, and screenshot flows
+- A control surface that covers normal canvas work without MCP wiring

package/docs/evals/e2e-cli-coverage.md

@@ -0,0 +1,61 @@
+---
+id: eval-20260424-001
+pattern-key: pmx-canvas.cli-e2e-fresh-workspace
+source: pmx-canvas-0.1.2-e2e-cli-coverage-report
+promoted-rule: "Fresh-workspace CLI coverage must verify node creation, parseable JSON, web-artifact failure behavior, external apps, arrange/validate, and focus no-pan before release."
+promoted-to: package.json test:e2e-cli
+created: 2026-04-24
+last-run: 2026-04-25
+last-result: pass
+---
+
+# PMX Canvas CLI E2E Coverage Eval
+
+## What This Tests
+
+Prevents regressions in the published-agent CLI flows that caused the 0.1.2 E2E report failures.
+
+## Precondition
+
+- Bun is installed.
+- The repo has been built with `bun run build` when client/browser assets changed.
+- Network is available for the hosted Excalidraw MCP preset and web-artifact dependency install.
+- Port `4567` is free, or `PMX_CANVAS_E2E_PORT` is set to a free port.
+
+## Verification Method
+
+Command check:
+
+```bash
+bun run test:e2e-cli
+```
+
+The command runs `scripts/e2e-cli-coverage.sh`, which creates a fresh temp workspace, starts the local PMX Canvas CLI server, and verifies:
+
+- `layout` and `node list` emit JSON parseable by Python's `json` module.
+- Core node types can be created through the CLI, including two webpage input paths.
+- Graph nodes accept `--data` as an alias for `--data-json`.
+- All graph variants create successfully: line, bar, pie, area, scatter, radar, stacked-bar, composed.
+- Simple and dashboard-shaped json-render specs create successfully.
+- Generic `node add --type mcp-app` is rejected with guidance.
+- `external-app add --kind excalidraw` creates a tool-backed app node.
+- Broken web-artifact builds return `ok: false`, exit non-zero, and do not create a node.
+- One successful web-artifact build emits a substantial bundled React/Recharts app, opens a node, and browser-verifies the real app content renders in the iframe.
+- `focus --no-pan` selects without viewport panning.
+- `arrange --layout grid` and `validate` agree on a valid layout.
+- Search can find artifact nodes and `status` reports expected graph/json-render/web-artifact counts.
+
+## Expected Result
+
+**Pass:** `PMX Canvas CLI E2E coverage passed` and exit code 0.
+
+**Fail:** Any command exits non-zero, JSON parsing fails, an assertion fails, or the server does not become healthy.
+
+## Recovery Action
+
+If this eval fails:
+
+1. Re-run with `PMX_CANVAS_E2E_KEEP_WORKDIR=1 bun run test:e2e-cli` to preserve the temp workspace.
+2. Inspect the preserved `.pmx-canvas/` state and `pmx-canvas.log` printed by the script.
+3. Fix the failing CLI/server path and add or update the narrower unit regression.
+4. Re-run `bun run test:e2e-cli`, then `bun run test:all` before release.

package/docs/http-api.md

@@ -0,0 +1,201 @@
+# HTTP API reference
+
+REST endpoints for all canvas operations + an SSE event stream. Works from
+any language. Default base URL: `http://localhost:4313`.
+
+## Canvas state
+
+```bash
+# Get canvas state
+curl http://localhost:4313/api/canvas/state
+
+# Search nodes
+curl "http://localhost:4313/api/canvas/search?q=auth"
+
+# Validate the current layout
+curl http://localhost:4313/api/canvas/validate
+
+# Inspect running-server schemas
+curl http://localhost:4313/api/canvas/schema
+
+# Validate a json-render spec without creating a node
+curl -X POST http://localhost:4313/api/canvas/schema/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"json-render","spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Preview"},"children":[]}}}}'
+
+# Validate an HTML primitive without creating a node
+curl -X POST http://localhost:4313/api/canvas/schema/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html-primitive","kind":"choice-grid","data":{"items":[{"title":"A"}]}}'
+```
+
+## Nodes
+
+```bash
+# Add a node
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"markdown","title":"Hello","content":"# World"}'
+
+# Add an html node (sandboxed iframe)
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html","title":"Chart","html":"<canvas id=\"c\"></canvas><script src=\"https://cdn.jsdelivr.net/npm/chart.js\"></script><script>/* ... */</script>"}'
+
+# Add a generated HTML primitive as a sandboxed html node
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html-primitive","kind":"choice-grid","title":"Options","data":{"items":[{"title":"Small patch","summary":"Least disruption."}]}}'
+```
+
+## Edges
+
+```bash
+# Add an edge
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"from":"node-1","to":"node-2","type":"flow","label":"next"}'
+
+# Add an edge by unique search match instead of explicit IDs
+curl -X POST http://localhost:4313/api/canvas/edge \
+  -H "Content-Type: application/json" \
+  -d '{"fromSearch":"DVT O3 — GitOps","toSearch":"deep work trend","type":"relation"}'
+```
+
+Search-based edge creation is intentionally strict: `fromSearch` and
+`toSearch` must each resolve to exactly one node. Broad queries that match
+multiple nodes fail; use the full visible title.
+
+## Annotations
+
+```bash
+# Add a freehand annotation. The default/currentColor stroke follows the active theme.
+curl -X POST http://localhost:4313/api/canvas/annotation \
+  -H "Content-Type: application/json" \
+  -d '{"points":[{"x":100,"y":120},{"x":220,"y":120}],"color":"currentColor","width":4}'
+
+# Remove an annotation
+curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
+```
+
+Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
+inspection or screenshots when the drawn shape matters.
+
+## Pins
+
+```bash
+# Pin nodes for agent context
+curl -X POST http://localhost:4313/api/canvas/context-pins \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1","node-2"]}'
+
+# Get pinned context
+curl http://localhost:4313/api/canvas/pinned-context
+```
+
+## Diagrams (Excalidraw preset)
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/diagram \
+  -H "Content-Type: application/json" \
+  -d '{"elements":[{"type":"rectangle","id":"r1","x":60,"y":60,"width":180,"height":80,"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid","label":{"text":"Hello","fontSize":18}}],"title":"Diagram"}'
+```
+
+## SSE event stream
+
+```bash
+curl -N http://localhost:4313/api/workbench/events
+```
+
+The browser, the CLI `watch` command, and the MCP resource notifications
+all consume this stream. Auto-reconnect with exponential backoff.
+
+## Time travel
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/undo
+curl -X POST http://localhost:4313/api/canvas/redo
+curl http://localhost:4313/api/canvas/history
+```
+
+## WebView automation
+
+```bash
+# Start WebView automation
+curl -X POST http://localhost:4313/api/workbench/webview/start \
+  -H "Content-Type: application/json" \
+  -d '{"backend":"chrome","width":1280,"height":800}'
+
+# Evaluate JS in the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"expression":"document.title"}'
+
+# Resize the active WebView session
+curl -X POST http://localhost:4313/api/workbench/webview/resize \
+  -H "Content-Type: application/json" \
+  -d '{"width":1440,"height":900}'
+
+# Capture a screenshot
+curl -X POST http://localhost:4313/api/workbench/webview/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"format":"png"}' \
+  --output canvas.png
+```
+
+## Batch operations
+
+Build a canvas in one shot. Earlier results can be referenced from later
+operations via `$assigned-name.field`.
+
+```bash
+curl -X POST http://localhost:4313/api/canvas/batch \
+  -H "Content-Type: application/json" \
+  -d '{"operations":[{"op":"node.add","assign":"a","args":{"type":"markdown","title":"A"}},{"op":"group.create","args":{"title":"Frame","childIds":["$a.id"]}}]}'
+```
+
+Supported operations:
+
+- `node.add`, `node.update`
+- `graph.add`
+- `edge.add`
+- `group.create`, `group.add`, `group.remove`
+- `pin.set`, `pin.add`, `pin.remove`
+- `snapshot.save`
+- `arrange`
+
+`node.add` supports `type: "webpage"` inside batch. The batch itself still
+succeeds when the webpage node is created but the fetch fails; the
+per-operation result includes `fetch: { ok, error? }` plus a top-level
+`error` field for the fetch problem.
+
+Example with assignments:
+
+```json
+{
+  "operations": [
+    {
+      "op": "graph.add",
+      "assign": "wins",
+      "args": {
+        "title": "Major wins",
+        "graphType": "bar",
+        "data": [
+          { "label": "Docs", "value": 5 },
+          { "label": "Tests", "value": 8 }
+        ],
+        "xKey": "label",
+        "yKey": "value"
+      }
+    },
+    {
+      "op": "group.create",
+      "assign": "frame",
+      "args": {
+        "title": "Quarterly graphs",
+        "childIds": ["$wins.id"]
+      }
+    }
+  ]
+}
+```