pmx-canvas 0.9.3 → 0.11.0

package/skills/pmx-canvas/SKILL.md

@@ -106,7 +106,7 @@ for the authoritative stop, viewport, persistence, reset, group-order, and captu
 
 ## Runtime prerequisites
 
-PMX Canvas 0.9.3 requires **Bun >=1.4.4**, including when installed through npm.
+PMX Canvas 0.11.0 requires **Bun >=1.4.4**, including when installed through npm.
 Check `bun --version` and ensure Bun is on the MCP host's PATH, not just your shell's;
 use an absolute executable path if needed. Install/configure only when requested.
 For pinned installation, MCP configuration, managed services, and disposable verification,
@@ -264,10 +264,15 @@ json-render, a graph, or an HTML primitive is sufficient.
 
 ## Current MCP Composites
 
-The live MCP surface is **24 tools**: the 18 composites below plus 6 standalones. This table is
+The live MCP surface is **25 tools**: the 18 composites below plus 7 standalones. This table is
 kept in sync with the server's composite registry; `tools/list` on a fresh `pmx-canvas --mcp` is
 always authoritative, independent of the installed release version.
 
+Use `canvas_help {}` to list MCP registry operation names, then `canvas_help { op: "node.add" }`
+for that operation's public tool, argument schema and guidance. Help does not start or read a
+canvas. The schema includes routing selectors and required fields; handlers still enforce
+conditional requirements. Use `tools/list` for non-registry tools such as `canvas_screenshot`.
+
 | Composite | Actions |
 |-----------|---------|
 | `canvas_import` | `list`, `read`, `submit`, `unavailable` |
@@ -303,7 +308,7 @@ Important routing:
 As of v0.3.0, the 57 legacy single-purpose tools from the v0.2 compatibility window are removed.
 The composites above plus the retained standalones are now the whole MCP surface: `canvas_batch`,
 `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`, `canvas_ingest_activity`, and
-`canvas_invoke_command`. Snapshots are the `canvas_snapshot` composite (actions
+`canvas_invoke_command`, plus `canvas_help`. Snapshots are the `canvas_snapshot` composite (actions
 `save | list | restore | restore-node | delete | gc | diff`); the 6 legacy snapshot standalones were removed in
 v0.4.0 after their deprecated 0.3.x window.
 
@@ -520,6 +525,10 @@ Use the visible workbench when the human is actively curating layout:
 - Drop files or URLs to create matching nodes; an empty board shows starter actions (new note,
   pick files, paste a link, start an agent session).
 - Use a markdown node's Edit button to edit its content.
+- For a frameless section label, set Markdown `data.display: "heading"` (or choose
+  **Display as heading** in its menu). `"card"` restores the ordinary frame.
+- Zoom keeps the same spatial board and scales card content proportionally.
+  Viewers load automatically near the viewport, including at fit-all zoom.
 - **Groups** are frames with the name pill and an action cluster (auto-arrange children, collapse,
   ⋯ rename / ungroup / pin all) on the top edge. Membership changes only on release while the
   "release to add to <group>" pill shows (Esc keeps it out); dragging a child fully out offers
@@ -683,7 +692,7 @@ Single-card and layout reads record content delivery, not incident relations.
 Graph cards and complete brief relations carry a captured `linksRevision`: reads
 acknowledge that version, not later changes. Brief delivery is qualified by source board.
 Reads never switch boards or mark full content read; pull needed cards in full separately. MCP remains
-24 tools and 15 static canvas resources, with two canvas templates (context/graph).
+25 tools and 15 static canvas resources, with two canvas templates (context/graph).
 
 Markdown saves bind `[[Board]]`, `[[Board#Card]]`, and `|alias` forms to durable
 IDs; code spans/fences are ignored. Ambiguous/missing targets never guess or
@@ -782,23 +791,12 @@ changes do not advance content revisions, while semantic edits and undo do.
 - A hosted ext-app (Excalidraw) node in a **WebKit** host panel (e.g. the GitHub Copilot app's
   embedded WKWebView) can remain blank even when its API session is healthy and `sessionStatus`
   is `ready`. This host-specific rendering issue remains open; successful Chrome/Codex rendering
-  does not establish native-host health. Since 0.4.6 the canvas runs a **paint oracle +
-  recovery ladder** under WebKit: present-at-load ext-apps mount strictly one at a time (the
-  cold burst was the trigger), each frame answers a double-rAF **paint probe** after settle, and
-  on silence the ladder escalates — soft-expand cycle (the automatic analogue of the proven
-  enlarge+close) → serialized remount → an explicit "App surface failed to paint / Retry"
-  affordance. Native Copilot/WebKit surfaces can still remain blank despite a successful
-  probe, including when visibility is reported as visible. The recovery trail
-  (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
-  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, `recovery-exhausted`, and
-  `assume-visible-rearm`. Treat `paint-ok`/`paint-fail` as diagnostic evidence, not compositor
-  proof. Require a rendered screenshot in the affected host before declaring its surface
-  healthy; a Chromium pass does not close a native Copilot/WebKit failure. In a host that
-  reports the document hidden, `paint-ok` is recorded as
-  `paint-ok (unverified: host hidden)` — the app answered the paint probe, but nothing is
-  proven composited, so do not treat it as a verified paint. If a
-  tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
-  attach the recovery trail when reporting.
+  does not establish native-host health. Viewers now share one loading/paint handoff and
+  explicit **Retry**. The old WebKit recovery ladder and its
+  diagnostic log endpoint are removed. A double-rAF acknowledgement establishes document
+  scheduling, not native compositor health. Require a rendered screenshot in the affected
+  host before declaring its surface healthy. A failed replacement keeps the last painted
+  document; use its Retry control rather than expecting automatic remount cycles.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
   while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
   0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its

package/skills/pmx-canvas/references/full-reference.md

@@ -431,10 +431,15 @@ When you do set a color (group/graph), use this palette consistently to convey m
 ## MCP Tools Reference
 
 PMX Canvas exposes **18 action-discriminated composites** (the whole recommended surface) plus
-**6 first-class standalones** — 24 tools total. The composites fold the older
+**7 first-class standalones** — 25 tools total. The composites fold the older
 single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
 **field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
 
+`canvas_help {}` lists MCP registry operation names. `canvas_help { op: "node.add" }`
+returns that operation's public tool, description and JSON argument schema, including
+routing selectors and required fields. It does not start or read a canvas. Handlers still
+enforce conditional requirements. Non-registry tools use `tools/list` instead.
+
 > **Legacy single-purpose tools were removed in v0.3.0.** The old names (`canvas_add_node`,
 > `canvas_update_node`, `canvas_request_approval`, `canvas_add_work_item`, …) are no longer
 > registered — use the composites below and fresh MCP `tools/list` for the installed runtime's
@@ -531,7 +536,7 @@ AX excerpts and annotation anchors, including `canvas://ax-context` and
 or brief relation entry instead.
 Single-card and layout reads record content delivery, not incident relations.
 Reads never switch boards or record full content reads. Pull cards in full
-when needed. Counts stay 24 tools, 15 static canvas resources; there are now two
+when needed. Counts are 25 tools, 15 static canvas resources; there are now two
 canvas templates, context and graph, besides the skill file template.
 
 Markdown save resolves `[[Board]]`, `[[Board#Card]]`, and `|alias` forms into
@@ -550,10 +555,15 @@ Once the board list has loaded, all workbench context-pin writes send the captur
 `expectedBoardId`; a server-side board switch returns 409 instead of changing
 another board's pins. Receipt pin actions require reopening the owning board.
 
-Embedded JSON/graph runtime readiness waits up to 10 seconds after document load
-and retries a failed handoff once while retaining the last painted document.
-After another failure, the error toast/history say **Reload to retry**; a later
-healthy authored update can recover. This is not an overall network-load timeout.
+Embedded previews mount automatically near the viewport at every zoom and remain
+mounted to preserve arbitrary app state. There is no lifetime preview cap. Mermaid renders
+inline, without an iframe. JSON/graph viewers inherit all nine named canvas themes
+and keep form drafts when the theme changes. During replacement, the pending
+document temporarily coexists with its painted predecessor.
+
+A network load or missing JSON runtime times out after 10 seconds and offers a
+visible **Retry**, retaining the last painted document during replacement.
+An already mounted offscreen runtime may wait for paint without being timed out.
 
 Native edge add accepts optional `toBoardId`: `from` is on the open source board,
 `to` is a card on the target board. CLI: `pmx-canvas edge add --from <source> --to <target>
@@ -1124,11 +1134,39 @@ Use native `json-render` and `graph` nodes when the output should stay fully ins
 
 Spec elements support an `on` map (`on.press`, `on.change`, …) binding events to actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or, when named after an AX interaction type, a capability-gated AX emit. e.g. a Button with `on: { press: { action: 'ax.work.create', params: { title: '…' } } }` lets a human turn a panel control into a tracked work item; the viewer forwards it to the canvas, which validates and submits it server-side (clamped to the node's own id). See **Node AX Interactions** above.
 
+## MCP results and cancellation (0.10)
+
+The 25-tool catalog remains on MCP SDK v1. Each tool advertises `outputSchema`
+and effect annotations. Help returns `structuredContent.result` with operation
+metadata (or the name list); it records no content reads. Registry-dispatched tools expose
+`structuredContent.result = { operation, outcome, data }`, where `outcome` is
+`success`, `error` or `partial`; `data` matches the existing compact text JSON,
+or `{message}` for prose. Exceptions use `operation: null`; they do not prove no
+writes occurred. Interaction, activity-ingestion and screenshot tools instead
+use direct structured objects matching their schemas. Check `isError` and domain
+outcomes. A composite's annotations cover all its actions, not just reads.
+
+Cancellation releases supported AX waits, aborts webpage fetches before late
+content writes, and stops subsequent batch operations. Completed writes remain;
+batch partial results retain `results` and `refs`. A created webpage can remain
+with `fetch.cancelled: true`. External app builds/runtime calls and local WebView
+captures are not interruptible mid-call. After a disconnect, inspect state before
+retrying because the response may not arrive. `_meta.progressToken` enables batch
+and supported AX wait progress notifications, including through the daemon connection. Without
+a token, calls return their normal result without progress notifications.
+
 ## MCP Resources
 
 These resources give you read access to canvas intelligence. Read them to understand
 what the human has set up and what they're focusing on.
 
+As of 0.10, live resource updates require `resources/subscribe` on each connection.
+Subscribe to the exact URI you read, including context/graph query parameters;
+`resources/unsubscribe` stops it, and reconnecting requires a new subscription.
+Notifications invalidate cached data but do not deliver content, record a read, or
+advance a consumer cursor. Explicit `resources/read` remains available without
+subscriptions. Static schema and bundled skills do not support subscriptions.
+
 | Resource | What it provides |
 |----------|-----------------|
 | `canvas://context{?budget,consumer,since}` | Budgeted cross-board map brief with optional durable consumer cursor |

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.9.3**, which requires **Bun >=1.4.4** even when
+The examples pin **PMX Canvas 0.11.0**, which requires **Bun >=1.4.4** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -22,11 +22,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.9.3
+npm install -g pmx-canvas@0.11.0
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.9.3` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.11.0` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -96,7 +96,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.9.3", "--mcp"],
+      "args": ["pmx-canvas@0.11.0", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -140,7 +140,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.9.3", "--mcp"],
+      "args": ["pmx-canvas@0.11.0", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -174,8 +174,8 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; for the full unfiltered 0.9.3 server there
-are 24 tools. If still absent, inspect the server status, command/PATH and target instead
+Discover `canvas` tools with `tool_search`; the full unfiltered 0.11.0 server has 25 tools,
+including `canvas_help`. If still absent, inspect the server status, command/PATH and target instead
 of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
 
 ### Verify native tools, then steering

package/skills/published-consumer-e2e/scripts/run-published-consumer-e2e.sh

@@ -75,11 +75,9 @@ if [[ -f "${REPO_ROOT}/LICENSE" ]]; then
   cp "${REPO_ROOT}/LICENSE" "${PACKAGE_STAGING}/package/LICENSE"
 fi
 cp -R "${REPO_ROOT}/src" "${PACKAGE_STAGING}/package/src"
-mkdir -p "${PACKAGE_STAGING}/package/dist/canvas" "${PACKAGE_STAGING}/package/dist/json-render"
-cp "${REPO_ROOT}/dist/canvas/index.js" "${PACKAGE_STAGING}/package/dist/canvas/index.js"
-cp "${REPO_ROOT}/dist/canvas/global.css" "${PACKAGE_STAGING}/package/dist/canvas/global.css"
-cp "${REPO_ROOT}/dist/json-render/index.js" "${PACKAGE_STAGING}/package/dist/json-render/index.js"
-cp "${REPO_ROOT}/dist/json-render/index.css" "${PACKAGE_STAGING}/package/dist/json-render/index.css"
+mkdir -p "${PACKAGE_STAGING}/package/dist"
+cp -R "${REPO_ROOT}/dist/canvas" "${PACKAGE_STAGING}/package/dist/canvas"
+cp -R "${REPO_ROOT}/dist/json-render" "${PACKAGE_STAGING}/package/dist/json-render"
 TARBALL="pmx-canvas-published-consumer.tgz"
 tar -czf "${PACK_DIR}/${TARBALL}" -C "${PACKAGE_STAGING}" package
 

package/src/client/canvas/BarHint.tsx

@@ -20,6 +20,7 @@ export function BarPortal({ children }: { children: VNode }) {
  * `title` hints, which are delay-gated and never render in embedded panes.
  */
 export function BarHint({
+  id,
   label,
   shortcut,
   body,
@@ -29,10 +30,12 @@ export function BarHint({
   fitWithin,
   children,
 }: {
+  /** Optional description target for the control's aria-describedby. */
+  id?: string;
   label: string;
   shortcut?: string;
-  /** One or two plain sentences under the label — the explanation a native `title` used to hide. */
-  body?: string;
+  /** Explanatory text, optionally split into readable paragraphs. */
+  body?: ComponentChildren;
   align?: 'start' | 'center' | 'end';
   /** Which way the tooltip opens. Bars at the bottom of the region open 'up'. */
   side?: 'down' | 'up';
@@ -73,7 +76,7 @@ export function BarHint({
       onFocusIn={fitWithin ? fit : undefined}
     >
       {children}
-      <span class="toolbar-tooltip" role="tooltip">
+      <span id={id} class="toolbar-tooltip" role="tooltip">
         <span class="toolbar-tooltip-label">{label}</span>
         {body && <span class="toolbar-tooltip-body">{body}</span>}
         {shortcut && (

package/src/client/canvas/CanvasNode.tsx

@@ -1,4 +1,4 @@
-import { boardList } from '../state/boards-store';
+import { activeBoard, boardList } from '../state/boards-store';
 import { cardQualification, effectiveLifecycleFilter as lifecycleFilter } from '../state/knowledge-store';
 import { knowledgeLifecycleEnabled } from '../state/workspace-settings';
 import { relationHighlight } from '../state/relation-store';
@@ -50,7 +50,7 @@ import { AxStepControls } from '../nodes/AxStepControls';
 import { getNodeIcon, IconChevronRight, IconClose, IconMore, IconExpand, IconPin } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
-import { AUTO_FIT_TITLEBAR_HEIGHT, computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
+import { computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
 import { activeGuides, buildSnapCache, clearSnapCache, snapToGuides } from './snap-guides';
 import { useNodeDrag } from './use-node-drag';
 import { useNodeResize } from './use-node-resize';
@@ -89,44 +89,6 @@ export function nearestNodeInDirection(
   return best;
 }
 
-/** Fraction of a node's height the title bar may occupy before it starts
- *  crowding out the content it is labelling. */
-const MAX_TITLEBAR_HEIGHT_RATIO = 0.4;
-/** Fraction of a node's width the fixed title-bar chrome may occupy before it
- *  starts eating the node's NAME. */
-const MAX_TITLEBAR_CHROME_WIDTH_RATIO = 0.55;
-/** Unscaled width of everything in the bar that is not the title: type icon,
- *  status/type pill, the control cluster, and the gaps between them. */
-const TITLEBAR_CHROME_BASE_WIDTH = 175;
-
-/**
- * How much to enlarge node chrome (title bar, badges, icons) when zoomed out so
- * it stays legible. Full inverse compensation is capped at 2.2x — but the cap
- * alone ignored the node it is drawn on, so on SHORT nodes the growing bar ate
- * the body: a 116px-tall section label at 46% zoom gave the title bar 72% of the
- * node and left 14px for text that needed 41, so the markdown was simply cut off.
- * The scale is therefore also bounded by the node's own height, keeping the bar
- * under MAX_TITLEBAR_HEIGHT_RATIO of it. Tall nodes are unaffected (their height
- * never binds); pass height 0 for collapsed/auto-height nodes to skip the bound.
- */
-export function nodeChromeScale(viewportScale: number, nodeHeight: number, nodeWidth = 0): number {
-  if (!Number.isFinite(viewportScale) || viewportScale >= 1) return 1;
-  const zoomScale = Math.min(2.2, 1 / Math.max(viewportScale, 0.01));
-  let bounded = zoomScale;
-  if (Number.isFinite(nodeHeight) && nodeHeight > 0) {
-    bounded = Math.min(bounded, (nodeHeight * MAX_TITLEBAR_HEIGHT_RATIO) / AUTO_FIT_TITLEBAR_HEIGHT);
-  }
-  // Width matters as much as height: the icon, pill and control cluster are all
-  // flex-shrink: 0, so the NAME is the only thing that gives way. Unbounded, a
-  // 360px step node at 52% zoom spent 100 of 187 bar pixels on controls alone and
-  // the title collapsed to nothing. Bound the scale so the fixed chrome can never
-  // take more than MAX_TITLEBAR_CHROME_WIDTH_RATIO of the node.
-  if (Number.isFinite(nodeWidth) && nodeWidth > 0) {
-    bounded = Math.min(bounded, (nodeWidth * MAX_TITLEBAR_CHROME_WIDTH_RATIO) / TITLEBAR_CHROME_BASE_WIDTH);
-  }
-  return Math.max(1, bounded);
-}
-
 /** A header title keeps at least this much room, or all of it when shorter (HeaderMarks.dc.html). */
 const TITLE_MIN_WIDTH = 140;
 
@@ -217,7 +179,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
       document.removeEventListener('keydown', escListener.current);
       escListener.current = null;
     }
-    persistLayout();
+    persistLayout({ raisedNodeId: node.id });
     // Membership changes ONLY here, and only while the pill was showing.
     const target = dragDropTarget.value;
     endDropTracking();
@@ -308,7 +270,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
         toggleSelected(node.id);
         return;
       }
-      bringToFront(node.id);
+      bringToFront(node.id, false);
       // User wins (phase 8): hold the node for the drag; an agent mid-edit yields.
       reportHumanGrab(node.id);
       noteNearAtGrab(node.id);
@@ -359,6 +321,15 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     (e: KeyboardEvent) => {
       const target = e.target as HTMLElement | null;
       if (target && target !== e.currentTarget && target.closest('input, textarea, [contenteditable="true"]')) return;
+      if (e.key === 'ContextMenu' || (e.shiftKey && e.key === 'F10')) {
+        const more = shellRef.current?.querySelector<HTMLButtonElement>('.node-hover-control[aria-haspopup="menu"]');
+        if (more) {
+          e.preventDefault();
+          e.stopPropagation();
+          more.click();
+        }
+        return;
+      }
       const dir = ARROW_DIRS[e.key];
       if (dir) {
         e.preventDefault();
@@ -445,10 +416,14 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
   const isTrace = node.type === 'trace';
   const isTraceRunning = isTrace && node.data.status === 'running';
   const isGroup = node.type === 'group';
+  const isHeading = node.type === 'markdown' && node.data.display === 'heading';
+  const graphType = (node.data.graphConfig as { graphType?: string } | undefined)?.graphType;
   const isStrictSize = node.data.strictSize === true;
   const viewportScale = Math.max(viewport.value.scale, 0.01);
-  const chromeScale = nodeChromeScale(viewportScale, node.collapsed ? 0 : node.size.height, node.size.width);
-  const chipFold = useHeaderFold(titleRef, headerChip(node, isContextPinned), title, node.size.width, chromeScale);
+  // Text alone may grow within the fixed header line. Enlarging the whole bar
+  // resizes embedded viewports and reflows their content while zooming.
+  const titleScale = Math.min(1.2, Math.max(1, 1 / viewportScale));
+  const chipFold = useHeaderFold(titleRef, headerChip(node, isContextPinned), title, node.size.width, titleScale);
 
   const groupColor = isGroup && node.data.color ? (node.data.color as string) : undefined;
   const nodeStyle: Record<string, string | number> = {
@@ -457,7 +432,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     width: `${node.size.width}px`,
     height: node.collapsed ? 'auto' : `${node.size.height}px`,
     zIndex: node.zIndex,
-    '--node-chrome-scale': chromeScale.toFixed(3),
+    '--node-title-scale': titleScale.toFixed(3),
     '--node-port-scale': (1 / viewportScale).toFixed(3),
     ...(groupColor ? { '--group-color': groupColor } : {}),
   };
@@ -477,6 +452,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
     isTrace ? 'trace-node' : '',
     isTraceRunning ? 'trace-running' : '',
     isGroup ? 'group-node' : '',
+    isHeading ? 'heading-node' : '',
     isStrictSize ? 'strict-size' : '',
     isAgentMutating ? 'agent-mutating' : '',
     sessionChromeActive.value && sessionEditedIds.value.has(node.id) ? 'session-edited' : '',
@@ -623,7 +599,9 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
                 ) : (
                   <span class="group-name">{title}</span>
                 )}
-                <span class="group-count">{groupChildren.length}</span>
+                <span class="group-count">
+                  {groupChildren.length} {groupChildren.length === 1 ? 'node' : 'nodes'}
+                </span>
               </span>
               <span class="group-edge-spacer" />
               <span class="group-actions" role="toolbar" aria-label={`${title} actions`}>
@@ -740,7 +718,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
               <NodeTypeIcon node={node} pinned={isContextPinned} title={title} fold={chipFold}>
                 {(() => {
                   const NodeIcon = getNodeIcon(node.type);
-                  return <NodeIcon size={Math.round(14 * chromeScale)} />;
+                  return <NodeIcon size={14} />;
                 })()}
               </NodeTypeIcon>
               {/* The kind-colored icon says what type this is (rail-chrome-v2 card
@@ -766,6 +744,14 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
                   {title}
                 </span>
               )}
+              {activeBoard()?.readmeNodeId === node.id && <span class="node-readme-mark">README</span>}
+              {node.type === 'graph' && graphType && <span class="node-header-meta">{graphType}</span>}
+              {node.type === 'file' && <div class="node-file-toolbar" data-file-toolbar={node.id} />}
+              {node.type === 'status' && typeof node.data.updatedAt === 'string' && (
+                <time class="node-header-meta" dateTime={node.data.updatedAt}>
+                  {new Date(node.data.updatedAt).toLocaleTimeString()}
+                </time>
+              )}
               <NearPinMark node={node} pinned={isContextPinned} fold={chipFold} />
               <NodeContextMark node={node} pinned={isContextPinned} fold={chipFold} />
               <div class="node-controls">
@@ -827,6 +813,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
                     onContextMenu?.(e, node.id);
                   }}
                   aria-label="More actions"
+                  aria-haspopup="menu"
                 >
                   <IconMore size={14} />
                 </button>

package/src/client/canvas/CanvasViewport.tsx

@@ -17,6 +17,7 @@ import { HtmlNode } from '../nodes/HtmlNode';
 import { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
+import { ViewerHost } from '../nodes/ViewerHost';
 import {
   activeNodeId,
   cancelViewportAnimation,
@@ -111,9 +112,10 @@ class WorldNode extends Component<{
 
   render() {
     const { node, onContextMenu } = this.props;
+    const viewer = ['html', 'mcp-app', 'json-render', 'graph', 'webpage', 'mermaid'].includes(node.type);
     return (
       <CanvasNode node={node} onContextMenu={onContextMenu}>
-        {renderNodeContent(node)}
+        {viewer ? <ViewerHost node={node}>{renderNodeContent(node)}</ViewerHost> : renderNodeContent(node)}
       </CanvasNode>
     );
   }
@@ -873,9 +875,8 @@ export function CanvasViewport({
                   : 'default',
       }}
     >
-      {/* D4: CSS matrix(a,b,c,d,tx,ty) — scale uniformly (a=d=scale, b=c=0)
-          then translate (tx=v.x, ty=v.y). transformOrigin: '0 0' ensures
-          the scale pivot is the top-left corner of the world layer. */}
+      {/* Scale the complete spatial world proportionally, including iframe
+          contents. CSS zoom changes embedded viewport semantics in WebKit. */}
       <div
         ref={worldRef}
         class="canvas-world"
@@ -894,9 +895,7 @@ export function CanvasViewport({
         <IntentLayer />
         <AgentPresenceLayer />
         <HumanPresenceLayer />
-        <EdgeLayer nodes={nodes} edges={edges} part="lines" />
-        <EdgeLayer nodes={nodes} edges={edges} part="pills" />
-        <EdgeLayer nodes={nodes} edges={edges} part="pill-hits" />
+        <EdgeLayer nodes={nodes} edges={edges} />
         {draggingEdge.value && (
           <div
             class="edge-hint-pill"

package/src/client/canvas/ContextMenu.tsx

@@ -1,6 +1,6 @@
 import type { ComponentChildren } from 'preact';
 import { knowledgeLifecycleEnabled } from '../state/workspace-settings';
-import { useCallback, useLayoutEffect, useState } from 'preact/hooks';
+import { useCallback, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import {
   contextPinnedNodeIds,
   edges,
@@ -28,8 +28,9 @@ import {
   updateNodeFromClient,
 } from '../state/intent-bridge';
 import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
+import { canCopyPrimitiveJson, copyPrimitiveJson } from '../nodes/primitive-copy';
 import { askText } from './TextPrompt';
-import { activeBoard, boardIncarnation } from '../state/boards-store';
+import { activeBoard, boardIncarnation, setBoardReadme } from '../state/boards-store';
 import { openLifecycle } from '../state/knowledge-store';
 import { RELATION_KINDS, relationKind } from '../../shared/relations.js';
 import { EXPANDABLE_TYPES } from '../types';
@@ -62,7 +63,9 @@ export function useContextMenu() {
   const openNodeMenu = useCallback((e: MouseEvent, nodeId: string) => {
     e.preventDefault();
     e.stopPropagation();
-    setMenu({ kind: 'node', x: e.clientX, y: e.clientY, nodeId });
+    const trigger = e.detail === 0 && e.target instanceof Element ? e.target.closest('button') : null;
+    const bounds = trigger?.getBoundingClientRect();
+    setMenu({ kind: 'node', x: bounds?.left ?? e.clientX, y: bounds?.bottom ?? e.clientY, nodeId });
   }, []);
 
   const openCanvasMenu = useCallback((e: MouseEvent, canvasX: number, canvasY: number) => {
@@ -113,6 +116,21 @@ const GROUP_COLOR_PRESETS = [
 ] as const;
 
 export function ContextMenu({ menu, onClose }: ContextMenuProps) {
+  const root = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const element = root.current;
+    const trigger = document.activeElement;
+    element?.querySelector<HTMLButtonElement>('button:not(:disabled)')?.focus();
+    return () => {
+      if (element?.contains(document.activeElement) && trigger instanceof HTMLElement && trigger.isConnected) {
+        // Card controls hide when the menu takes focus. Reveal the opener
+        // through its card before restoring focus to the button itself.
+        trigger.closest<HTMLElement>('.canvas-node')?.focus({ preventScroll: true });
+        trigger.focus({ preventScroll: true });
+      }
+    };
+  }, [menu]);
+
   let items: MenuItem[];
   if (menu.kind === 'node') {
     const node = nodes.value.get(menu.nodeId);
@@ -215,6 +233,9 @@ export function ContextMenu({ menu, onClose }: ContextMenuProps) {
 
   return (
     <div
+      ref={root}
+      role="menu"
+      aria-label={menu.kind === 'node' ? 'Node actions' : menu.kind === 'edge' ? 'Edge actions' : 'Canvas actions'}
       class="context-menu"
       style={{
         position: 'fixed',
@@ -224,6 +245,27 @@ export function ContextMenu({ menu, onClose }: ContextMenuProps) {
       }}
       onPointerDown={(e) => e.stopPropagation()}
       onClick={(e) => e.stopPropagation()}
+      onBlur={(e) => {
+        if (e.relatedTarget instanceof Node && !e.currentTarget.contains(e.relatedTarget)) onClose();
+      }}
+      onKeyDown={(e) => {
+        e.stopPropagation();
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          onClose();
+        } else if (e.target instanceof HTMLButtonElement && ['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) {
+          e.preventDefault();
+          const controls = [...e.currentTarget.querySelectorAll<HTMLElement>('button:not(:disabled), input, select')];
+          const index = controls.indexOf(e.target);
+          const next =
+            e.key === 'Home'
+              ? 0
+              : e.key === 'End'
+                ? controls.length - 1
+                : (index + (e.key === 'ArrowUp' ? -1 : 1) + controls.length) % controls.length;
+          controls[next]?.focus();
+        }
+      }}
     >
       {items.map((item) => {
         const baseKey = item.separator
@@ -251,6 +293,8 @@ export function ContextMenu({ menu, onClose }: ContextMenuProps) {
           <button
             key={itemKey}
             type="button"
+            role="menuitem"
+            disabled={!item.action}
             class={`context-menu-item${item.danger ? ' is-danger' : ''}`}
             onClick={() => {
               item.action?.();
@@ -622,6 +666,22 @@ function buildNodeMenuItems(node: CanvasNodeState): MenuItem[] {
   items.push({ separator: true });
 
   // Type-specific
+  if (canCopyPrimitiveJson(node)) {
+    items.push({ label: 'Copy JSON', action: () => void copyPrimitiveJson(node.id) });
+  }
+  if (node.type === 'markdown') {
+    items.push({
+      label: node.data.display === 'heading' ? 'Display as card' : 'Display as heading',
+      action: () =>
+        void updateNodeFromClient(node.id, { data: { display: node.data.display === 'heading' ? 'card' : 'heading' } }),
+    });
+    const board = activeBoard();
+    if (board)
+      items.push({
+        label: board.readmeNodeId === node.id ? 'Remove as README' : 'Set as README',
+        action: () => void setBoardReadme(board.id, board.readmeNodeId === node.id ? null : node.id),
+      });
+  }
   if ((node.type === 'markdown' || node.type === 'file' || node.type === 'image') && localPath) {
     items.push({
       label: 'Open in browser',