pmx-canvas 0.6.3 → 0.6.5

package/docs/http-api.md

@@ -9,6 +9,40 @@ bodies are treated as an empty request. As of 0.4.0 every error response is a
 JSON envelope of that same shape (`{ ok: false, error }`, status unchanged) —
 no plain-text errors remain.
 
+Node-create responses include `sizeAdjustment` when a frame dimension was
+defaulted or raised to its node type's readability floor. It contains the
+`requested` dimensions (`null` when omitted), the final `applied` dimensions,
+and a `reason` (`defaulted`, `clamped-to-minimum`, or
+`defaulted-and-clamped-to-minimum`; groups also use `fit-to-children`). `strictSize: true`
+still bypasses the readability clamp, but omitted dimensions are reported as
+defaulted. MCP create actions return the same size report.
+Updates preserve explicit dimensions without applying creation floors; their
+returned node `size` is the applied size. Omitted update dimensions retain the
+existing size and are not reported as defaulted adjustments.
+
+Both group-create routes report defaults or final child-derived dimensions, including
+when children override supplied width/height because x/y were omitted. Explicit manual
+frames retain their existing semantics. Group child replacement reports `fit-to-children`
+when it changes the frame; `group.add` reports the previous frame as `requested` and
+the final frame as `applied`. Reports survive compact/full MCP and batch responses.
+External MCP app creation and web-artifact builds that open a node report their default
+frames too; reusing an existing app node or building without opening does not report a
+creation default. These reports describe the synchronous operation, not later browser
+content auto-height or indirect parent-group reflow after editing a child.
+
+## Board tours
+
+- `GET /api/canvas/tour` → `{ tour: { stops: [...] }, derived: boolean }`.
+- `POST /api/canvas/tour` with `{ "tour": { "stops": [...] } }` persists the tour;
+  `{ "tour": null }` resets to derived group reading order. Returns `{ "ok": true }`.
+- `GET /api/canvas/state` includes optional `tour`. Tour writes broadcast a layout
+  update and are included in snapshots/undo. They are board-wide writes under a scope fence.
+
+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
+the CLI, not an HTTP job endpoint.
+
 ## Canvas state
 
 ```bash
@@ -35,6 +69,10 @@ curl -X POST http://localhost:4313/api/canvas/json-render \
   -H "Content-Type: application/json" \
   -d '{"title":"Panel","nodeHeight":280,"spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Live"},"children":[]}}}}'
 
+# For graph nodes, `height` is the chart's plot height, not the node frame.
+# Set the frame with `nodeHeight` (`heightPx` in the SDK). A graph request that
+# supplies only `height` gets the default frame height and a response warning.
+
 # Validate an HTML primitive without creating a node
 curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
@@ -70,6 +108,11 @@ A node creation request must resolve a `type` — pass it in the body (`{ "type"
 ... }`) or as a `?type=` query param. An empty / type-less body returns `400`
 rather than silently creating a markdown node.
 
+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%
+with scrolling. [Mermaid sizing and readability](node-types.md#mermaid-nodes).
+
 ### File node content and bytes
 
 A `file` node reads its file server-side. Text is stored on the node as
@@ -145,6 +188,31 @@ 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.
 
+## Viewport
+
+```bash
+# Set the camera transform (screen = world * scale + {x,y})
+curl -X POST http://localhost:4313/api/canvas/viewport \
+  -H "Content-Type: application/json" \
+  -d '{"x":64,"y":96,"scale":0.8}'
+
+# Fit selected nodes (omit nodeIds to fit the whole canvas)
+curl -X POST http://localhost:4313/api/canvas/fit \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1"],"width":1200,"height":700}'
+
+# Focus without moving the camera
+curl -X POST http://localhost:4313/api/canvas/focus \
+  -H "Content-Type: application/json" \
+  -d '{"id":"node-1","noPan":true}'
+```
+
+Viewport `x`/`y`, fit `width`/`height`, and fit padding are interpreted against
+the **canvas area**, excluding the tool rail, top bar, and other surrounding
+page chrome—not the full browser window. Camera, fit, and focus-only requests
+do not create or refresh agent writer presence. Use the explicit presence API
+when an agent should publish a cursor or `focusNodeId`.
+
 ## Pins
 
 ```bash
@@ -341,13 +409,20 @@ When that session ends (`attached: false`, `session-end`, or the idle expiry)
 the stream carries one `agent-session-ended` frame:
 
 ```json
-{ "label": "Copilot", "endedAt": "…", "counts": { "items": 4, "done": 3, "vetoed": 1 },
+{ "label": "Copilot", "parentAgentId": null, "endedAt": "…", "endedBy": "agent",
+  "unchanged": false, "counts": { "items": 4, "done": 3, "cancelled": 1, "rejected": 0, "held": 0 },
   "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00" } }
 ```
 
-`items`/`done` count the work items on the board; `vetoed` counts cancelled
-items plus rejected or held gates. `snapshot` is null when the board was
-empty at attach. The browser renders this as the session receipt; its *View
+`items`/`done` count the work items on the board; cancelled items, rejected
+gates, and held gates have separate counts. `snapshot` is null when the board was
+empty at attach or unchanged at end (the redundant snapshot is removed).
+The browser shows a receipt only for a changed top-level session: `unchanged: true`
+and worker endings (`parentAgentId` set) never open or replace a popup. An empty
+board that stays empty is unchanged too. This only filters the popup: session-end
+events, timeline records, and changed-session snapshots remain available.
+There is at most one receipt, replaced by the next qualifying ending and kept until
+dismissed so restore/diff actions do not disappear on a timer. Its *View
 diff* is `GET /api/canvas/snapshots/<id>/diff` against that snapshot, and
 restoring the snapshot undoes the session. Adapters should end their session
 explicitly so the human gets the receipt promptly rather than after the idle

package/docs/mcp.md

@@ -13,6 +13,15 @@ nodes in the browser, agents are notified immediately.
 > snapshot standalones — each step per [`api-stability.md`](api-stability.md)'s
 > deprecate-one-minor-before-removal rule. **Prefer the composites.**
 
+## Board tours
+
+`canvas_view { action: "get-tour" }` returns `{ tour, derived }`, using group
+reading order when there is no saved tour. `canvas_view { action: "set-tour",
+tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
+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.
+
 ## Connect
 
 Add to your agent's MCP config:
@@ -42,7 +51,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_edge` | `add` · `update` · `remove` | `canvas_add_edge`, `canvas_update_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
 | `canvas_query` | `search` · `layout` · `validate` | `canvas_search`, `canvas_get_layout`, `canvas_validate` |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | `canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`, `canvas_resize`, `canvas_evaluate` |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | `canvas_open_mcp_app`, `canvas_add_diagram`, `canvas_build_web_artifact` |
@@ -54,6 +63,11 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
+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
+changing the node setting. [Sizing and readability](node-types.md#mermaid-nodes).
+
 ### `canvas_intent` — Ghost Cursor of Intent
 
 Announce the spatial move you are **about** to make so the canvas paints a faint
@@ -92,6 +106,16 @@ fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
 fold completed in v0.4.0: `canvas_snapshot { action: "save" | "list" | "restore" |
 "delete" | "gc" | "diff" }` replaced the 6 deprecated snapshot standalones.
 
+### Viewport coordinates
+
+`canvas_view { action: "focus" | "fit" }` controls the camera without counting
+as a writer operation or refreshing agent presence. Viewport translation uses
+screen-space canvas-area coordinates (`screen = world * scale + viewport`). Fit
+dimensions and padding likewise refer to the canvas area after excluding the
+tool rail, top bar, and surrounding page chrome—not the full browser window.
+Use `canvas_ax_state { action: "set-presence", cursor, focusNodeId }` when the
+agent intends to publish its own cursor or attention target.
+
 ## Standalone tools
 
 6 tools that intentionally stay outside the composites — folding them would

package/docs/node-types.md

@@ -26,6 +26,17 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
 | `group` | Spatial container/frame around other nodes |
 
+Creation applies per-type frame defaults and readability minimums. When a
+dimension is defaulted or clamped, HTTP and MCP create responses include a
+`sizeAdjustment` with requested and applied dimensions plus the reason.
+`strictSize: true` bypasses minimum-size clamping; it does not change defaults
+for omitted dimensions.
+
+For `graph` nodes, `height` controls the chart plot inside the viewer.
+`nodeHeight` controls the canvas node frame (`heightPx` is the SDK alias). If
+only `height` is supplied, the frame keeps its default height and the create
+response warns about the distinction.
+
 Thread node types `prompt` and `response` exist internally for agent
 conversation rendering and are not created through public APIs.
 
@@ -64,6 +75,34 @@ different type by extension:
 - **Text files over 2 MB** render truncated with a banner saying so, so a huge
   log can never exhaust memory.
 
+## Mermaid nodes
+
+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
+dark and light themes. Resizing a card or expanding it recalculates the fit.
+`strictSize` keeps the requested node geometry while the diagram fits inside it;
+ordinary cards retain their grow-only automatic sizing.
+
+Fitting a large diagram makes its text smaller. Use **Expand** for more space,
+or **Open as site** for a 100% natural-size diagram with scrolling. Set
+`data.fit: "none"` to use that natural-size, scrollable view inside the card too.
+This setting is independent of the canvas camera's **Fit view** action.
+
+```ts
+canvas_node({ action: 'add', type: 'mermaid', content: 'flowchart TD; A-->B-->C-->D',
+  width: 920, height: 870, strictSize: true, data: { fit: 'contain' } })
+canvas_node({ action: 'update', id: 'node-id', data: { fit: 'none' } })
+```
+
+HTTP uses the same `data` object in `POST /api/canvas/node` and
+`PATCH /api/canvas/node/:id`. CLI creation and updates expose `--fit`:
+
+```bash
+pmx-canvas node add --type mermaid --content 'flowchart TD; A-->B-->C-->D' --fit contain --width 920 --height 870 --strict-size
+pmx-canvas node update node-id --fit none
+```
+
 ## Image nodes
 
 Image nodes display local paths, remote URLs, and data URIs. File-backed and
@@ -137,7 +176,7 @@ with the server's transport, tool name, and arguments.
 
 `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
+[`@json-render/*`](https://www.npmjs.com/package/@json-render/core) 0.21.0 runtime
 and component catalog (core + react + shadcn).
 
 ```ts
@@ -158,6 +197,56 @@ canvas_render({
 `outline`. Older saved specs using `label` or status variants such as
 `success`/`warning` are normalized during validation.
 
+Specs preserve top-level `state` and element-level `repeat`, `watch`, and
+`slots`. Use `$bindState` with JSON Pointer paths for editable form values;
+`$state` only reads a value. Nested repeats can use `statePath: { "$item": "tasks" }`
+to iterate the current item's tasks. Watchers run after changes, not on mount.
+
+**Seed form values through bindings, not literal `value` props.** In shadcn
+0.21, `Input`, `Textarea`, `Select`, `Radio`, `Slider`, `ToggleGroup`, and
+`Tabs` ignore an unbound `value`; `ButtonGroup` ignores unbound `selected`.
+This includes read-only `$state` expressions. PMX returns a `warnings` array
+from `POST /api/canvas/json-render`, `POST /api/canvas/schema/validate`, and
+`canvas_render` actions `add-json-render` and `validate`. Warnings name the
+element/property; they do not reject or rewrite the spec. PMX does not invent
+state paths because repeated controls and existing actions may need distinct
+or deliberately shared state.
+
+```json
+{
+  "root": "postcode",
+  "state": { "form": { "postcode": "nw1 6xe" } },
+  "elements": {
+    "postcode": {
+      "type": "Input",
+      "props": {
+        "label": "Postcode",
+        "name": "postcode",
+        "value": { "$bindState": "/form/postcode" }
+      }
+    }
+  }
+}
+```
+
+Inside repeats, use `$bindItem` with seeded item data. `Checkbox`/`Switch`
+honor literal `checked`, `Toggle` honors literal `pressed`, and `Tabs` honors
+`defaultValue` for an uncontrolled initial tab. `Pagination` reads `page`
+directly; `DropdownMenu.value` is an output binding for selection, not a
+displayed selection. These do not require the same ignored-value warning.
+Use two-way bindings whenever edits or form checks must participate in state.
+
+Cards keep their body in `children` and accept
+`slots: { header: ['headingId'], footer: ['actionsId'] }`. Slot IDs reference
+entries in `elements`; a custom header replaces the title and description props.
+See the bundled [json-render guide](../skills/json-render-mcp/SKILL.md)
+for a complete state-bound form with watchers and footer actions.
+
+Form edits are viewer-local, not saved into the stored spec. Reloading the iframe
+or updating its spec (including streaming patches) resets that state. Finish
+streaming before collecting input, and persist important changes through an
+explicit server interaction.
+
 Elements may carry an `on` map (`on.press`, `on.change`, …) binding events to
 actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or
 host-provided handlers. PMX wires AX handlers named after interaction types, so a
@@ -185,9 +274,35 @@ source + per-viewer nonce + node id) and submits it server-side; `json-render` /
 `graph` viewers are sandboxed surfaces, so caller-supplied `nodeIds` are clamped
 to the node's own id. See the [MCP reference](mcp.md#node-interactions-capability-gated).
 
+AX handlers are fire-and-forget: `onSuccess` means local dispatch completed,
+not that the server accepted the operation. Confirm acceptance through AX state
+or timeline before showing a saved state or clearing a draft. The built-in
+`validateForm` action returns without calling `onSuccess`; do not chain submission
+through that callback.
+
 Use `canvas_render { action: "describe-schema" }` / `canvas_render { action:
 "validate" }` to introspect the component catalog before building a spec.
 
+### Automatic sizing of authored iframe cards
+
+HTML (except presentation decks), Mermaid, JSON-render, graph, and web-artifact
+cards can grow as their rendered content changes. This changes node geometry;
+**Fit view** only changes the camera. Height measurements include title-bar and
+body padding, grow only up to 1400px, and never change the width. Content beyond
+that limit may still scroll; this is not a general shrink-to-content action.
+
+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.
+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.
+
+Read the settled node geometry after mounting rather than treating requested
+dimensions as final. Prefer targeted node reads or the CLI's projected layout
+fields over fetching full content merely to check spacing.
+
 ## HTML nodes
 
 `html` nodes render a normal self-contained HTML/JS document in a sandboxed iframe.
@@ -235,6 +350,13 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+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.
+Other populated or omitted fields keep their normal behavior. Empty `slides`
+or flow `steps` also omit navigation/run controls; an AX board's live task
+controls remain available when only its optional note is empty.
+
 Two kinds are **live AX control surfaces** rather than static documents, and are
 the only primitives created with AX enabled:
 

package/docs/product-context-vision-2026-09.md

@@ -1,6 +1,6 @@
 # Vision extension: boards, personal wiki, and workspace context
 
-**Status:** Proposed for discussion, not an implementation commitment.
+**Status:** Proposed for discussion, not an implementation commitment. **Superseded in part, 2026-09-23:** the maintainer decided that boards are the wiki and that the destination is "share this board" ([vision, move 0 and Part 3](product-vision-2026-09.md); reasoning in the [review](product-vision-review-2026-09.md#design-sketch-boards-are-the-wiki)). The separate entity and revision store, the personal wiki as its own surface, and working-versus-confirmed machinery are not planned; boards, cards and the journal play those roles. Still in force: the publication and audience rules and the threat-model corrections, which apply when sharing reaches a second writer (Part 3), and the validation experiment, run on linked boards instead of a wiki.
 **Date:** 2026-09-06
 **Companions:** [Product review](product-review-2026-09.md), [product vision](product-vision-2026-09.md).
 **Request:** Review the existing vision and explore hosted users building their own wiki by describing their work, with their boards contributing context, and cross-cutting organizational context shared within a workspace. Reuse the logic of the personal/context-frame projects inside pmx-canvas's own store rather than depend on an external wiki.