pmx-canvas 0.9.3 → 0.11.0

package/docs/design.md

@@ -87,8 +87,8 @@ Components reference tokens only. Raw colour values live only in the theme files
 - Tints are derived — `color-mix(in srgb, var(--c-pin) 12%, transparent)` — so the 22 alpha
   copies, `--c-warn-alt` and `--c-glow-accent` go.
 - `--c-thinking` becomes `--c-agent`.
-- **Kinds carry no colour.** Type icons use `--c-muted`; the glyph tells the kind, plus the kind
-  word on zoomed-out tiles (Zoom board). Minimap rects and group-chip kind dots are neutral, and
+- **Kinds carry no colour.** Type icons use `--c-muted`; the glyph tells the kind.
+  Minimap rects and group-chip kind dots are neutral, and
   only meaning colours mark them (pinned, agent at work). `KIND_COLOR`, `--kind-accent` and
   `--c-purple` go. Nine kind hues cannot all stay clear of ten meaning colours in nine themes,
   and every hue a kind borrows is one a meaning loses.
@@ -141,7 +141,7 @@ the same change.
 | [`Flows.dc.html`](design/Flows.dc.html) | Data lineage with staleness, what a finding rests on, opening a group | 3, 5 |
 | [`Uses.dc.html`](design/Uses.dc.html) | One relation layer for research, dependencies, decisions and agent flows | 3 |
 | [`Types1.dc.html`](design/Types1.dc.html)–[`Types3.dc.html`](design/Types3.dc.html) | Every node type, today vs proposed | 0, 4 |
-| [`Zoom.dc.html`](design/Zoom.dc.html) | Fit-all readability when frames are unmounted | 4 |
+| [`Zoom.dc.html`](design/Zoom.dc.html) | Native spatial scaling at every zoom, maintainer override 2026-10-25 | 4 |
 | [`Pane600.dc.html`](design/Pane600.dc.html) | Home and a board at the narrow end, 600 px | all |
 | [`Vision.dc.html`](design/Vision.dc.html) | How each design area maps to the vision, and the open decisions | — |
 
@@ -377,7 +377,7 @@ workflow. A demo of existing features must not be used to claim full sketch pari
 | **1. Context made visible** — its curation evaluation moved to the end of the plan (2026-10-19) | Part 1 bet, moves 0a, 2, 7 | Surface `context_reads` (already recorded since 0.7.0: who read, which nodes were delivered) per node and per board as read / not read / changed since read, using revisions; who pinned; activity lens and session receipt from presence activity and revisions; board pins (`board_pins`, tiered brief, `canvas_board pin/unpin`) and Home's pinned-boards section | What the agent did with context, Nodes in context, Board pins, Home (Folders) | From the board alone, a person can answer "did the agent read what I pinned, and is its copy current?" The evaluation in `docs/evals/` reads the same data |
 | **2. Connected memory views** — implemented, verification gates apply | Moves 0, 14 | One board/card projection for Home, links/backlinks, brief discovery and `canvas://graph{?focus,depth}`; saved wiki ID bindings, direct cross-board card edges, previous-board chains, persisted Map positions | Home Map, Home Graph (deviations below) | Map and Graph are generated from the library; orphans visible; works at 600 px and in a full window |
 | **3. Relations layer** | Moves 0, 1, 13 | Edge `reason` and an open `kind` with a per-board vocabulary; relations carried in the brief's text form; "derived from" with staleness from provenance and recipes; relation queries for the inspector | Relations, Lineage, One relation layer | Hovering a node explains each link; a changed source turns downstream nodes amber; the agent's brief includes relations |
-| **4. Frame host and viewers** | Moves 5, 9 | One frame host passing the full theme tokens; json-render defaults to the canvas theme with an opt-out for design experiments; zoomed-out cards for unmounted frames | Node types 1–3, Zoomed out | No viewer draws its own background; 20 portals mount no more frames than none; fit-all is readable |
+| **4. Frame host and viewers** | Moves 5, 9 | One frame host passing the full theme tokens; json-render defaults to the canvas theme with an opt-out for design experiments; native proportional canvas at every zoom | Node types 1–3, Zoom | Viewers use the canvas palette and fill their authored space; approaching a viewer mounts it automatically and retains its state when panning away; no alternate grid or lifetime preview cap |
 | **5. Agent output and groups as pages** | Moves 3, 0 | Work items, gates and asks as nodes; make board / inline board; opening a group keeps its outside links | One relation layer (agent flow), Lineage (open a group) | Agent output is styled by the same shell and tokens; a group opened as a board shows its outside stubs |
 | **Later: hosted version** | Part 4 (moved from Part 3, 2026-10-19) | Read-only link, comments, second writer, accounts and roles; org → team → personal scopes with configurable categories and per-user pins; built once for the ChatGPT Sites and later Cloudflare editions | HomeTeam is the earlier two-root look ahead; updated scope/category drawings are required before building, retaining explicit publication and locked cards for unreadable boards | Exports and shared views inherit the tokens; a viewer sees the same meaning colours; nothing personal reaches a wider audience without explicit publication |
 
@@ -630,6 +630,171 @@ curation evaluation after its remaining features. Local categories and lifecycle
 without a model; Jev-style classification is optional longer-term assistance, not a dependency
 of Wave 3 or the org/team/personal structure.
 
+## 0.11 implementation notes
+
+Chrome §9–10 and Types1–3 drive the section-heading, header, typography and viewer
+pass. Fit and focus reserve a 44 px screen-space top lane. JSON viewers inherit the
+named canvas palette; only duplicate root titles disappear. Mermaid renders inline.
+File-header metadata may clip within its own text container, but Reload and AX
+evidence actions and their hover/focus hints stay outside that clip (Types1).
+The maintainer's 2026-10-25 decision supersedes the earlier reading-flow footer:
+**Set as README** lives only in the card's ⋯ menu, becoming **Remove as README**
+for the current README. The agent normally assigns it; this menu is the human override.
+The designated card keeps a quiet, always-visible **README** word in its header,
+including heading-display Markdown. It uses neutral metadata ink, not pin blue or
+selection styling; the title yields before this identifier truncates.
+Ordinary Markdown keeps its visible **Edit** action; heading display has no footer.
+Chrome and Types1 reflect this decision. The menu takes keyboard focus, supports
+arrows and Tab, and restores the opener on activation or Escape.
+**Present** explains saved tours versus group-derived stops on hover and keyboard
+focus, with an accessible description. The narrow ⋯ menu shows the same explanation
+in flow below Present rather than clipping a floating tooltip. Chrome records the
+owner's exact copy; no tour behavior changes. Its saved-tour instruction says
+**ask your agent to define the stops**, not that a visual human tour editor exists.
+During presentation, **Back** and **Next** sit beside **Exit presentation** at
+the top-right, following the existing shared server cursor. The owner's final
+placement decision puts instructions only in each button's hover/focus tooltip:
+Previous stop (← / ↑), Next stop (→ / ↓ / Space), Exit presentation (Esc).
+There is no lower-left instruction panel. Unavailable end buttons remain focusable
+for their descriptions. Node/rectangle fitting reserves the controls' measured
+height; explicit camera targets and deterministic recordings remain unchanged.
+HTML primitives put **Copy JSON** in the card's ⋯ menu, not their inner header;
+**Copy prompt** is removed. JSON comes from the current mounted document, including
+unsaved interactive edits, through the nonce-bound sandbox bridge. Unloaded or
+replaced documents and denied clipboard access report failure, not stale data or
+success. Raw HTML and the custom presentation primitive have no JSON-export menu
+action. Primitive-specific Copy diff, Copy SVG and similar controls stay in place.
+The maintainer's 2026-10-25 correction rejects the experimental CSS zoom, content
+enlargement and alternate overview. The original world matrix scales cards,
+embedded contents, groups and connections proportionally at every zoom. Only title
+text grows, up to 1.2× inside a fixed 22 px header line. Header controls, padding and
+body space stay fixed in world pixels; enlarging the whole header would resize the
+iframe viewport and reflow charts while zooming. Card bodies never counter-scale.
+All cards share the same stacking and input boundary. A separate
+ext-app portal was rejected in review because it covered higher cards, bypassed
+pan gestures, and disappeared during presentation. The common world also owns
+clipping when a dock resizes the canvas. Headed Linux WebKit reproduced CSS zoom
+shrinking the iframe's internal layout and retaining stale dimensions through
+zoom transitions. Restoring the matrix keeps inner widths stable in the same probe.
+Native WKWebView compositor health remains unverified, not established by that result.
+Automatic previews mount on first approach at any scale, then retain their
+documents to preserve arbitrary app state. The rejected lifetime cap starved later
+board regions. Memory now grows with visited viewers. Visible viewers start loading
+automatically without a shared bootstrap queue or per-card clicks. A slow document
+does not hold another card's loading slot.
+Each loading replacement temporarily coexists with its painted document.
+
+The demo gives ordinary standalone charts the full authored card height instead
+of imposing a smaller plot-height cap. Compact chart types keep compact cards:
+the 36 px sparkline sits in a 120 px card, four dot-plot rows in 240 px, three bullet
+rows in 260 px, and the slopegraph in 300 px. These are demo authoring choices,
+not enforced sizes on user cards. Explicit chart `height` still caps content,
+independently of `nodeHeight`. Dashboard and form stacks explicitly use stretch
+alignment; the catalog's start-aligned default is unchanged, as are compact action
+buttons. Work-item controls must fit their authored cards without accidental
+overflow or truncated status. Enlarging the demo to 440×300 did not meet that
+requirement and is not acceptance evidence. The card body now scrolls only its
+content when needed; step controls and Edit share one fixed footer row. The full
+status word takes priority over the title. Steering input and send button wrap
+together. Expanded documents keep their sticky footer. The demo returns to a
+240 px height, with 360 and 440 px widths exercised in both Chromium and WebKit.
+Bodies still shrink proportionally.
+
+Static exports use the same embedded chart layout and named palettes, retain
+heading display, and match the live 37 px card header. Fonts and shared palette
+CSS are embedded for offline use. Saved positions, sizes and specs are unchanged;
+live work controls are intentionally absent. Export is a separate acceptance
+surface, not established by live canvas checks. Close slopegraph labels separate
+without moving data endpoints; short same-ink leaders retain their association
+(Types3). An explicitly overcrowded chart still requires adequate authored height.
+
+Relation labels keep their curve midpoint when clear. Otherwise the pill and its
+hit area move together to nearby open space, avoiding cards, group headers,
+connection handles and earlier labels. A dashed leader in the relation's ink
+ties it back to the curve. Card positions, curve routing and stacking do not
+change. Font measurements determine pill width. Dense boards can still require
+panning to a displaced label; labels remain hidden below the existing 35% floor.
+
+`ViewerHost` owns preview admission, without a second positioning or recovery path.
+`RefreshingViewerFrame` owns document loading, the painted replacement handoff and
+Retry. HTML readiness and the ext-app protocol use that host; JSON additionally
+restores its viewer-local state before promotion. The ext-app adapter no longer
+has a separate paint/recovery ladder. Document preparation failures do not fall
+back to another transport that the embedding probe already rejected.
+Ext-app protocol bootstrap runs once after initialization, or after the loaded
+document's bounded notification-only bootstrap interval. The host waits for
+input/result delivery and paint before declaring it ready; bootstrap errors use
+the same Retry as other loading failures.
+Webpages show cached text until an explicit live-preview request; Mermaid
+and native board thumbnails render inline. Mermaid's inline
+and standalone/export renderers share their palette, serialization and sanitizer.
+Inline rendering uses Mermaid's strict security mode and DOMPurify, including
+sanitized `foreignObject` labels, instead of the old diagram iframe sandbox.
+Mermaid is the exception to the static-import rule: the SPA loads it on the first
+diagram, using hashed chunks from the same server. A six-Markdown-card cold-boot
+probe requested only the entry and its small shared chunk, not Mermaid's 3.46 MB.
+With Bun 1.4.4, headed Chromium 145, 4× CPU throttling and five alternating fresh
+contexts per variant, the baseline median was 1,423.9 ms and the candidate median
+1,349.1 ms to six populated cards plus two animation frames. Ranges overlap
+(1,277.3–1,484.7 ms versus 1,315.2–1,510.1 ms), so this is not a speedup claim.
+The baseline is 0.10.0 rebuilt with the same compiler; both variants use current
+CSS and local intercepted responses, not a network or native-host benchmark.
+Reproduce with `DISPLAY=:99 node scripts/benchmark-canvas-boot.mjs <disposable-server-url> <baseline-index.js>`.
+The populated-board check uses `scripts/benchmark-populated-canvas.mjs`, the same
+70-card fixture and 18% camera, headed Chromium 145 at 1440×900, and three cold-cache
+loads plus three warm reloads per build, with other browsers and tests stopped.
+All 33 visible viewers rendered. The final comparison found baseline 0.10.0 at
+6.71–7.67 s cold and 7.17–7.32 s warm; the candidate took 7.59–8.19 s cold and
+8.00–8.39 s warm. This remains a loading cost, not an orb-only explanation or a
+speedup. Main-page long tasks totalled 4.43–4.87 s on the candidate versus
+3.46–4.20 s on baseline. Each chart document contains about 1.49 MB decoded
+(baseline 1.47 MB). Parent Resource Timing alone misses baseline iframe bytes
+and can duplicate candidate navigation bytes; do not compare or sum those totals.
+The script records frame resources separately. Removing the provisional four-document queue produced overlapping
+completion ranges and a later first viewer; the simpler independent loading path
+avoids cross-card blocking, not a claimed performance win. Warm-load aborted
+presence requests are recorded separately from viewer failures; no viewer failed.
+At the default 52% camera there are no visible iframe viewers. The candidate's
+board appeared in 0.67–0.70 s cold and 0.52–0.65 s warm versus baseline's
+1.08–1.32 s and 1.06–1.36 s. That measures deferred offscreen work, not faster
+viewer rendering. Local document responses were 2–6 ms. Portal-URL checks use
+Amp's local hairpin forwarding inside this orb, so they do not measure external
+portal transport or the user's connection. These are instrumented local readiness
+timings, not native paint latency. Linux WebKit's full fit-all load exceeded this orb's memory limit
+on both baseline and candidate; narrower populated-row checks are separate evidence.
+The self-contained MCP App cannot fetch those chunks: its document includes
+Mermaid and grows from about 1.32 MB to 4.78 MB uncompressed. This is an introduced delivery
+cost, not eliminated debt or measured native performance. Keeping one renderer
+and an offline-capable MCP document is the tradeoff; native boot remains unmeasured.
+The bundle audit found one Mermaid core, one shared renderer and one DOMPurify,
+not an embedded copy of the standalone viewer. The old standalone Mermaid bundle
+already weighed 3,492,157 bytes; moving its renderer inline brings that dependency
+tree into the self-contained MCP host. The dependency graph contains different
+major versions of `marked`, `layout-base` and `cose-base` required by Mermaid's
+renderers; forcing aliases would not be a safe deduplication. Inspect the graph
+with `bun build src/client/mcp-app/index.tsx --target=browser --format=iife --minify --metafile=/tmp/mcp-meta.json --outfile=/tmp/mcp.js`.
+Removing the payload from MCP startup requires a different script-delivery/CSP
+contract or a reduced diagram catalog, rather than deleting a duplicate host.
+Static export checks separately cover all twelve graph variants, compact plots,
+all nine named themes and 600, 1024 and 1920 px widths in headed Chromium.
+The populated 70-card export matches live saved geometry and renders offline
+without HTTP(S) requests; bounded Linux WebKit checks cover the compact chart
+section and dashboard. Linked boards and live MCP apps retain honest unavailable
+placeholders. Arbitrary user HTML can still contain external requests.
+
+There is no threshold-triggered grid or list. Zoom's revised drawing keeps the
+same positions, sizes, groups, connections and native content at every scale.
+Fit-all is for orientation; zoom or expand to read details. The earlier overview's
+scrolling and overlay-clearance fixes are superseded by its complete removal.
+
+Visual audit: Harbor headings use the drawing's 20 px semibold `#e6eef7` on
+`#081524` (15.69:1). The initial dim capture had the existing relation-focus
+highlight active, which applies 0.35 opacity to unrelated cards; Escape clears
+that view state. A neighboring card outside a 600 px viewport is spatially
+clipped, not internally truncated: focusing it restores the complete title.
+Expanded pin hints remain while their button has keyboard `:focus-visible`, even
+after pointer movement; Tab away dismisses the hint after its fade transition.
+
 ## Definition of done for any design work
 
 1. It is drawn in the proposal canvas first, at 600 px and at full-window width.

package/docs/http-api.md

@@ -3,6 +3,37 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+## Operation cancellation and progress (0.10)
+
+Registry-backed operation routes use the request's abort signal. Disconnecting
+stops supported AX waits, cancels webpage fetching and prevents later batch
+operations from starting. Completed writes remain. Cancellation is cooperative:
+external app builds/runtime calls and local WebView captures cannot be interrupted
+mid-call. A standalone cancelled operation returns HTTP 499 with
+`{ "ok": false, "cancelled": true, "error": "Operation cancelled." }` when the
+connection still permits a response. An interrupted batch retains completed
+`results` and `refs` in its partial-failure body and adds `cancelled: true`.
+Disconnected clients must inspect state before retrying; they may never receive
+that body. Cancellation is not rollback.
+
+Send `Accept: application/x-ndjson` to opt into batch and supported AX wait progress
+over the operation response stream. Each newline-delimited JSON frame is one of:
+
+```json
+{"type":"progress","progress":{"progress":1,"total":3,"message":"node.add"}}
+{"type":"result","status":200,"body":{"ok":true,"results":[],"refs":{}}}
+```
+
+The examples show frame shapes, not one complete batch. The terminal `result`
+frame carries the ordinary operation status and body; the stream's HTTP 200 does
+not establish operation success. Without this header, routes keep their ordinary
+JSON status/body. Early validation errors may still be ordinary JSON. The
+in-process and HTTP operation invokers accept optional `{ signal, onProgress }`;
+the HTTP invoker negotiates this stream only when given a progress callback.
+
+AX wait routes accept `timeoutMs` as well as the direct-HTTP `waitMs` parameter;
+`timeoutMs` takes precedence when both are supplied.
+
 ## Knowledge lifecycle data (plan 017 slice 1)
 
 The slice-1 data contract now also drives the workbench, due engine and qualified agent context.
@@ -186,9 +217,15 @@ content auto-height or indirect parent-group reflow after editing a child.
   update and are included in snapshots/undo. They are board-wide writes under a scope fence.
 - `POST /api/canvas/tour/go` with `{ "stop": 2 }` or `{ "step": "next" | "previous" }`
   (plus optional `"present": false`) moves the shared tour cursor →
-  `{ ok, index, total, stop }`; 400 when the stop does not exist or the board has no stops.
+  `{ ok, index, total, stop, catalogEpoch, boardGeneration, sequence }`;
+  400 when the stop does not exist or the board has no stops.
   Broadcasts `canvas-tour-step`; idle workbenches start presenting unless `present` is false.
+  Response and event share the same monotonically increasing `sequence` within the
+  server's `catalogEpoch`. Viewers accept only newer steps for their current epoch
+  and board generation, so delayed echoes cannot rewind or replay the camera.
 - `POST /api/canvas/tour/exit` leaves presentation in every viewer (`canvas-tour-exit`).
+  Returns `{ ok, catalogEpoch, boardGeneration, sequence }`; the event shares that
+  identity and the step sequence, so an old exit cannot dismiss a newer presentation.
 - `POST /api/canvas/camera/move` with exactly one of `nodeId`, `rect: { x, y, width, height }`
   or `viewport: { x, y, scale }`, plus optional `duration`, `easing`, `padding`, `pullback`
   → `{ ok, stop, viewport }`. Broadcasts `canvas-camera-move`; browsers ease to the target in
@@ -198,6 +235,29 @@ content auto-height or indirect parent-group reflow after editing a child.
 Tour steps and camera moves are navigation: no undo entry, no agent-presence write, no
 scope-fence check.
 
+`tour/go` and `tour/exit` accept optional `presenter: { clientId, intent,
+catalogEpoch, boardGeneration }`. The workbench assigns each document a random ID
+and each gesture an increasing positive safe-integer intent. The server rejects
+an old activation or an intent no newer than that document's accepted watermark
+with `{ ok: true, superseded: true }`, without moving the cursor or emitting an event.
+A structurally valid newer command supersedes older ones even if its stop is missing.
+This lets Present proceed while an earlier Exit request is stalled, without that
+late Exit stopping the restart. Resume reads cannot outlive their originating intent.
+
+This is latest-intent-wins, not FIFO: reversed relative Next requests can coalesce.
+Different documents, including a reload, remain independent; unfenced agent calls
+and other documents still act in server arrival order. Reload is not cancellation
+of an old document's pending request. A board activation retains at most 4096
+document IDs, refusing new IDs with 409 rather than evicting an ordering record.
+Switching boards resets that limit; requests stamped with the old activation still
+cannot apply. The SDK exposes the same fence through `goToTourStop(step,
+{ presenter })` and `exitTour(presenter)`; fenced go may return `{ superseded: true }`.
+
+Presentation's Back/Next buttons share this cursor with keyboard and agent navigation.
+They sit beside Exit at the top; hover/focus tooltips show the shortcuts. Node and
+rectangle targets fit below those controls, while explicit viewport targets remain
+exact. Presentation does not change the saved board viewport.
+
 The [tour model and recording walkthrough](cli.md#tour-and-presentation) describes
 targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to hide
 chrome; camera movement is local to that viewer. Recording writes local files via
@@ -357,6 +417,14 @@ stored once per file. Live MCP apps become placeholders; local file contents
 are left out unless `includeFiles` is true. Files are written to `exports/`
 beside the database. Built-app files are only embedded when they are regular,
 bounded-size files inside the board's owned `.pmx-canvas/artifacts/` directory.
+Exports retain saved card positions and sizes, heading display, and the board's
+named theme. Charts and dashboards use embedded card layout without repeating
+the shell title; explicit chart heights remain unchanged. Viewer bundles, palette
+CSS and shell fonts are embedded. Read-only exports omit live work controls.
+When running from source, run `bun run build` before exporting. Export requires
+the complete built viewer assets, `surface-theme.css`, and the font files referenced
+by `global.css`; the installed package includes them. A missing asset tree is not
+a supported text-only export mode.
 The preview manifest lists card links, remote images, and statically visible
 network destinations in embedded HTML. Imported source-linked Markdown is also
 excluded unless `includeDerivedText=true`, independently of `includeFiles`;
@@ -431,6 +499,13 @@ opening that board or changing where writes go. This is supported by
 return 404. Omit `board` to read the active board. Live AX session/delivery reads
 and fixed MCP resources continue to describe the open board.
 
+The workbench's `POST /api/canvas/update` accepts `{updates: [{id, position?, size?,
+collapsed?, zIndex?}], expectedBoardId?, recordHistory?}`. `zIndex` is finite and
+persists stacking without changing geometry. The workbench raises a group and its
+children together, keeping the frame below its children. Title-bar gestures save
+stacking and geometry together on release. Layout notifications and reloads retain
+that order.
+
 ```bash
 # Get canvas state
 curl http://localhost:4313/api/canvas/state
@@ -582,6 +657,10 @@ hosted MCP App still refuses file-linked edits. This is not a crash-recovery dis
 Replacing a JSON-render node's `spec` preserves its current title; include `title`
 to rename it explicitly. A new authored spec still resets the viewer's local drafts.
 
+Markdown nodes accept `data: { "display": "heading" | "card" }` on creation and
+update. Heading display removes the card frame and uses its title as a section
+label; it does not alter content, position, or pin membership.
+
 Mermaid nodes accept `data: { "fit": "contain" | "none" }` on both
 `POST /api/canvas/node` and `PATCH /api/canvas/node/:id`. The default, `contain`,
 shrinks overflowing diagrams without changing aspect ratio; `none` keeps 100%
@@ -1263,6 +1342,8 @@ all consume this stream. Auto-reconnect with exponential backoff.
 
 The direct workbench's `connected` snapshot renews its per-process
 `workbenchToken` (also embedded in boot HTML) over both SSE and polling.
+It is followed by `boards-changed` before the layout, so later tour commands
+already have a board identity even when the separate catalog HTTP read is delayed.
 A same-bundle daemon restart does not reload the page or discard an open draft.
 Registered writes and file saves marked as workbench calls with a supplied stale capability
 return 409 until reconnect renews it; they are never silently recorded as agent

package/docs/mcp.md

@@ -1,10 +1,92 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **24 tools**, **15 static canvas
+PMX Canvas ships an MCP stdio server with **25 tools**, **15 static canvas
 resources**, and two canvas resource templates, plus per-skill resources at
 `canvas://skills/<name>` and the `skill://{name}/{+path}` template. The server emits
-`notifications/resources/updated` when canvas state changes — humans pin
-nodes in the browser, agents are notified immediately.
+`notifications/resources/updated` to subscribed connections when canvas state changes.
+This uses MCP SDK v1, not SDK v2.
+
+## Operation help (0.10)
+
+Call `canvas_help {}` for the sorted registry names exposed through MCP, then
+`canvas_help { op: "node.add" }` for one operation's public `tool`, `description`
+and JSON `inputSchema`. The schema includes required fields, public field names
+and constant routing selectors (`action`, and `kind` for gates). For example,
+`ax.approval.request` maps to `canvas_ax_gate` with `kind: "approval"`,
+`action: "request"` and the optional `approvalAction` field.
+
+Text contains the JSON result; structured content wraps it in `{ result }`.
+Unknown names, internal/human-only operations and non-registry tools such as
+`canvas_screenshot` return text-only `isError`; use `tools/list` for those tools.
+Help reads registry metadata only: it never starts a canvas, writes state, records
+a content read or advances a cursor. It is read-only and idempotent.
+
+Help derives its schema and guidance from the operation registry, not from live
+board state. Handlers still enforce conditional requirements and authorization.
+Existing input schemas stay in `tools/list`; help does not enable lazy discovery
+in hosts. Repeated equivalent output branches are grouped within each tool,
+preserving operation/payload validation and partial-error receipts.
+
+## Tool results and effect hints (0.10)
+
+All 25 tools advertise an object `outputSchema`. Registry-dispatched tools return
+`structuredContent.result = { operation, outcome, data }`. `operation` names the
+dispatched action (for example `node.add`), `outcome` is `success`, `error` or
+`partial`, and `data` is the existing compact tool result. Prose results use
+`data.message`. Exceptions use `operation: null`, `outcome: "error"` and
+`data.message`; this does not guarantee that nothing changed before the exception.
+Batch failures retain completed `results` and `refs`, with `partial` when at least
+one entry completed. Check both `isError` and the outcome before using a result.
+
+The three handwritten tools keep direct structured objects: `canvas_ax_interaction`
+returns its accepted interaction, `canvas_ingest_activity` its event and reaction
+records, and `canvas_screenshot` capture metadata alongside model-visible image
+content. Their errors are text-only `isError` replies. Existing model-facing text
+and compact/full projections remain unchanged; structured results do not introduce
+additional full-card or UI payloads. Inspect the advertised schema for each tool.
+
+All tools declare `readOnlyHint`, `destructiveHint`, `idempotentHint` and
+`openWorldHint`. Composite hints cover every action, not only their read actions.
+`canvas_query` is not read-only because context reads can advance a durable
+consumer cursor. Hints describe effects; they grant no permission or retry guarantee.
+
+## Cancellation and progress (0.10)
+
+MCP cancellation reaches the operation layer in both local and daemon-attached
+connections. Supported AX waits release their listeners and timers immediately;
+batches stop before the next operation and keep completed writes. Webpage fetches
+receive the signal and stop before writing fetched content after cancellation.
+Cancellation does not roll back a created node or other completed mutations.
+If webpage creation already committed, its receipt retains `fetch.cancelled: true`.
+External app builds/runtime calls and local WebView captures are not interruptible
+mid-call; do not treat cancellation as proof that those side effects stopped.
+
+Calls supplying `_meta.progressToken` receive `notifications/progress` at batch
+entry boundaries and supported AX wait start/completion, with `progress`, optional
+`total`, optional `message` and the same token. This works over the daemon bridge
+as well as local stdio. No token means
+no progress notifications. A host that aborts its connection may not receive a
+partial result; inspect canvas state before retrying. See the
+[HTTP streaming contract](http-api.md#operation-cancellation-and-progress-010).
+
+## Resource subscriptions (0.10)
+
+The server advertises `resources.subscribe`. Send `resources/subscribe` with an
+exact live URI, then `resources/unsubscribe` to stop. Subscriptions belong to the
+connection and disappear on close; reconnecting clients must subscribe again.
+
+Live resources are `canvas://layout`, `boards`, `summary`, `context`, `graph`,
+`spatial-context`, `history`, `code-graph`, `pinned-context`, `ax`, `ax-context`,
+`ax-timeline`, `ax-work`, `ax-pending-steering` and `ax-delivery` (each with the
+`canvas://` prefix). Parameterized context and graph URIs are supported, for example
+`canvas://context?consumer=my-agent&budget=3000`; notifications echo the exact
+subscribed URI. Static schema and bundled skill resources do not support subscriptions.
+
+Notifications invalidate cached data, not deliver it. Read the resource when needed.
+They can be broader than the underlying change, and daemon reconnection invalidates
+subscribed resources to cover missed events. Notification delivery does not record
+a context read or advance a consumer cursor. Explicit `resources/read` works without
+subscriptions, including on hosts that do not use this capability.
 
 > **Consolidation complete (plan-006/008).** The MCP surface shrank from 84
 > tools to 22: 16 action-discriminated **composites** (recommended — see
@@ -64,6 +146,10 @@ tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
 presents a stop in the workbench, `"tour-exit"` leaves presentation, and
 `canvas_view { action: "move", nodeId | rect | viewport, duration, easing, padding, pullback }`
 eases the camera. None of these enter undo history.
+`tour-go` and `tour-exit` also accept the optional document `presenter` fence
+described in [HTTP board tours](http-api.md#board-tours). Superseded requests return
+`{ ok: true, superseded: true }` with no delivery or event. Ordinary agent calls
+omit it and retain shared arrival-order navigation.
 See the [tour model and CLI walkthrough](cli.md#tour-and-presentation) for stop
 fields. Recording is a local CLI operation; no remote recording/file-writing
 tool is added.
@@ -83,12 +169,12 @@ Add to your agent's MCP config:
 }
 ```
 
-The canvas auto-starts on first tool call.
+The canvas auto-starts on first canvas operation, not on `canvas_help`.
 
 ## Private MCP App preview
 
 `pmx-canvas --mcp-app` runs a **separate, experimental stdio profile**; the
-24-tool `--mcp` profile above is unchanged. Build from this checkout first:
+25-tool `--mcp` profile above is separate. Build from this checkout first:
 
 ```bash
 bun run build
@@ -358,7 +444,7 @@ Single-card and layout reads record delivered content, not incident relations.
 Use a complete graph or brief relation entry to acknowledge those relations.
 Reads never mark full card content read or
 switch the workbench. Pull needed cards in full separately.
-No new tool is added: the tool count stays 24.
+These reads add no tools beyond the catalog listed above.
 
 Library search is `canvas_query { action: "search", query: "auth", scope:
 "library" }`. It returns board/card IDs and never switches the active board.
@@ -431,6 +517,10 @@ into `persistFile: true` with both preconditions and top-level `content` to save
 workspace `.md` file and card together. In this mode, `data` accepts only the `rendered` preview;
 refused saves change neither. See [the file-save contract](http-api.md#nodes).
 
+For Markdown nodes, `canvas_node` actions `add` and `update` accept
+`data: { display: "heading" | "card" }`. Heading display uses the existing title
+and content as a frameless section label, without changing pin membership.
+
 For Mermaid nodes, `canvas_node` actions `add` and `update` accept
 `data: { fit: "contain" | "none" }`. Contain is the default, shrinking overflow
 uniformly; none keeps 100% with scrolling. Use Open as site for 100% without
@@ -491,13 +581,14 @@ agent intends to publish its own cursor or attention target.
 
 ## Standalone tools
 
-6 tools that intentionally stay outside the composites — folding them would
+7 tools that intentionally stay outside the composites — folding them would
 hurt (distinct callers, binary payloads, trust-boundary or execution-intent
 semantics). See [Migration reference](#migration-reference) below for the
 legacy tools the composites replaced.
 
 | Tool | Description |
 |------|-------------|
+| `canvas_help` | List MCP registry operations or fetch one operation's public arguments and guidance (`op` optional); no canvas access |
 | `canvas_batch` | Run a batch of canvas operations with `$ref` support |
 | `canvas_pin_nodes` | Pin nodes to include in agent context (`nodeIds`, `mode` set/add/remove, optional `reason` shown to the human) |
 | `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
@@ -703,20 +794,9 @@ interaction against the node's effective capabilities.
 
 ## Change notifications
 
-The MCP server emits `notifications/resources/updated` whenever canvas state
-changes:
-
-- Pin changes notify `canvas://pinned-context`, `canvas://ax`, and `canvas://ax-context`
-- AX focus changes notify `canvas://ax` and `canvas://ax-context`
-- Canvas-bound AX mutations (work items, approval gates, review annotations,
-  host capability) notify `canvas://ax`, `canvas://ax-work`, and `canvas://ax-context`
-- AX timeline mutations (agent-events, evidence, steering) notify
-  `canvas://ax-timeline` and `canvas://ax-context`
-- All mutations notify `canvas://layout`, `canvas://summary`,
-  `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`
-
-This closes the human-to-agent loop: spatial curation in the browser becomes
-an immediate signal in the agent's context.
+Notifications require an explicit subscription to each live resource URI. See
+[Resource subscriptions](#resource-subscriptions-010) for connection lifetime,
+reconnection and broad cache invalidation. Receiving a notification is not a content read.
 
 ## Codex App Adapter
 

package/docs/node-types.md

@@ -1,9 +1,9 @@
 # Node types
 
-`board` is a native text-only link. Set `data.boardId` to the durable target ID. Its header pin pins the
+`board` is a native link with a lightweight board thumbnail. Set `data.boardId` to the durable target ID. Its header pin pins the
 linked board into the agent's working set (`canvas_board { action: "pin" }`), not the portal card.
 Titles resolve from that ID, so renames and folder moves are safe; deleted
-targets render explicitly as missing. It is not an iframe or a cross-board card
+targets render explicitly as missing, with **Link to board…** to choose a replacement. It is not an iframe or a cross-board card
 edge. Static exports lock the card and intentionally do not embed the target
 title or summary, so exporting this board does not disclose another board.
 
@@ -32,7 +32,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `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 |
-| `board` | Text-only link to another board, with its README summary and navigation |
+| `board` | Lightweight thumbnail link to another board, with its README summary and navigation |
 
 Creation applies per-type frame defaults and readability minimums. When a
 dimension is defaulted or clamped, HTTP and MCP create responses include a
@@ -48,6 +48,11 @@ response warns about the distinction.
 Thread node types `prompt` and `response` exist internally for agent
 conversation rendering and are not created through public APIs.
 
+The spatial board and its content scale proportionally at every zoom, without
+switching layouts. Iframe previews mount automatically near the viewport and
+remain mounted to preserve arbitrary app state. There is no lifetime preview cap;
+memory use grows with the viewers visited. Board links and Mermaid render inline.
+
 Full node reads expose server-owned `createdBy`, `lastEditedBy`, and
 `contentRevision`. Authors distinguish human, agent, system, and unknown;
 legacy nodes remain unknown. The revision advances on semantic content changes,
@@ -73,6 +78,15 @@ that fits the work — each step adds capability and bundle weight.
 
 ## Markdown tasks
 
+Use **Display as heading** in a Markdown card's context menu for a frameless section
+label. Its title becomes the heading and its content remains below it. **Display as card**
+restores the frame; this does not change the content or context pins. Agents can set
+`data.display` to `"heading"` or `"card"` through ordinary node creation or updates.
+**Set as README** in the card's ⋯ menu designates the board's existing README field;
+the current README instead offers **Remove as README** to clear it. A quiet **README**
+word stays visible in the designated card's header, including heading display.
+**Edit** stays visible below ordinary Markdown. Heading display has no footer.
+
 Tick a task directly on its card, including quoted and nested tasks. A card click changes
 only that task's `[ ]` or `[x]` marker, preserving the rest of the source exactly.
 Task-shaped text in code examples and raw HTML checkboxes are not Markdown task controls.
@@ -119,6 +133,9 @@ different type by extension:
 
 ## Mermaid nodes
 
+Diagrams render inline with the canvas palette, rather than in an iframe. Invalid
+source shows a visible error and **Retry**. Native WebKit hosts remain best-effort.
+
 Mermaid diagrams default to `data.fit: "contain"`: when the diagram overflows
 the available body, it shrinks uniformly until the entire diagram fits. Small
 diagrams stay at 100%; aspect ratio, labels, and edges are preserved, in both
@@ -216,6 +233,12 @@ with the server's transport, tool name, and arguments.
 
 ## json-render nodes
 
+Embedded dashboards and charts inherit all nine named canvas themes. Their root
+card fills the viewer without an extra panel or shadow. A root title identical to
+the canvas card title is hidden; distinct authored titles and descriptions remain.
+Theme changes preserve viewer-local inputs. A failed replacement keeps the last
+painted document and offers **Retry** instead of repeatedly reloading it.
+
 `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) 0.21.0 runtime
@@ -372,6 +395,10 @@ Fitting waits for local or remote human grabs to end. A growing ungrouped,
 screen-unpinned card moves downward if needed to leave a 24px gap from neighboring
 cards, without moving those neighbors. A relocation records one undo step for
 both size and position; height-only adjustments do not add undo entries.
+Repeated measurements from the same document do not reverse Undo or a smaller
+height set by another writer. Changed content dimensions, width or chrome can
+fit again. Replacing or reopening the viewer starts a fresh measurement, so this
+suppression does not survive reload, collapse/reopen or a board switch.
 Grouped or screen-pinned cards retain their positions. Collapsed cards and cards
 marked `strictSize` or `userResized` are not automatically resized. Hosted MCP
 apps and webpage viewers do not use this authored-content fitting behavior.
@@ -431,6 +458,14 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+The card's ⋯ menu offers **Copy JSON** for primitives with JSON export (all except
+the custom `presentation` template). It copies the mounted document's current
+state, including interactive edits, rather than the original server data.
+Open the viewer first; unavailable/reloading content or denied clipboard access
+shows a failure message. Copy prompt and the shared inner-header copy buttons are
+removed. Primitive-specific actions such as Copy diff and Copy SVG remain.
+Ordinary HTML nodes do not receive this menu item.
+
 Omitted fields may use the template's examples. Explicit empty arrays, empty
 strings, or `null` mean “show nothing”: the field's section, heading, and
 dependent controls are omitted rather than replaced with sample content.