pmx-canvas 0.4.6 → 0.4.7

package/skills/pmx-canvas/SKILL.md

@@ -105,6 +105,7 @@ exit 1 on failure.
 | Persistent context cards | `context` via `canvas_node` |
 | Event/check stream | `ledger` or `trace` via `canvas_node` |
 | Local source with live updates | `file` via `canvas_node` |
+| Tabular data (`.csv`/`.tsv`), a PDF, or any other file on disk (0.4.6+) | `file` via `canvas_node` — CSV/TSV render as tables, PDFs render inline, other binaries show a size placeholder. Never paste a CSV into a markdown fence. |
 | Code review / unified diff (0.4.6+) | `diff` via `canvas_node` (content = diff text; link to its file node with a `references` edge) |
 | Flowchart / sequence / state diagram (0.4.6+) | `mermaid` via `canvas_node` (content = mermaid source; renders client-side, no hosted app) |
 | Image | `image` via `canvas_node` |
@@ -113,6 +114,9 @@ exit 1 on failure.
 | Chart | `graph` via `canvas_render` |
 | Live work-item board (0.4.6+) | `canvas_render { action: "workboard" }` — one board node, auto-refreshes on work-item changes |
 | Generated communication surface | HTML primitive via `canvas_node` |
+| Give the agent tasks + watch progress + loop (0.4.7+) | `ax-board` HTML primitive — a live AX control surface, created AX-enabled |
+| The same, drawn as a task flow, and materializable to real nodes+edges (0.4.7+) | `ax-flow` HTML primitive — **Materialize to board** lays the steps out as nodes joined by `flow` edges with a loop-back edge, each linked to a work item |
+| Drive a flow WITHOUT the panel (0.4.7+) | Materialized step nodes carry native Start/Done/Blocked controls, and the anchor adds Run loop/Stop + steer. The native loop runs server-side, so it survives a browser reload and keeps advancing while the tab is closed. |
 | Self-contained HTML/JS | `html` via `canvas_node` |
 | Hosted interactive MCP app | `canvas_app { action: "open-mcp-app" }` |
 | Excalidraw diagram (interactive/human drawing) | `canvas_app { action: "diagram" }` — prefer `mermaid` for agent-authored diagrams |
@@ -190,10 +194,23 @@ distant nodes, an auto-placed node lands off-camera.
 3. Never fit the whole board to "show" new work — on a board with outliers that miniaturizes
    everything. Always pass explicit `nodeIds` to `fit`.
 4. Never leave user-facing output at far coordinates without a focus/fit.
+5. **Do not hand-compute a whole board's coordinates.** Create the nodes (omitting x/y), then
+   `canvas_view { action: "arrange", layout: "grid" | "column" | "flow" }` and finish with a
+   `fit` over the new ids. Manual pixel math is what produces long-line, unbalanced boards.
+6. `fit` sizes itself to the connected browser window (0.4.6+) — you do not need to guess
+   `width`/`height`. Pass them only to fit for a window other than the human's.
+7. **Docking is explicit (0.4.6+).** Nodes render on the canvas where you put them; a node is
+   only a HUD pill if you set `dockPosition`. An edge whose endpoint is docked cannot be drawn —
+   `validate` reports it as `hiddenEdgeEndpoints` and fails `ok`, because the edge visually
+   trails off into empty canvas.
 
 **Size for content.** Omitting `width`/`height` gives readable per-type defaults — prefer them:
 markdown 640×420, status 360×200, file 520×360, diff 640×420, mermaid 640×460, html 720×640,
-graph 760×520, mcp-app 960×600, web-artifact 960×720. Since 0.4.6 the server clamps explicit creation sizes UP to per-type
+graph 760×520, mcp-app 960×600, web-artifact 960×720. A *hosted* app opened with
+`canvas_app { action: "open-mcp-app" | "diagram" }` — including the Excalidraw diagram preset — is
+the exception: it opens at 720×500, not 960×600 (960×600 is the default for an `mcp-app` node you
+create directly). Pass `width`/`height` to that action when you want a bigger diagram tile.
+Since 0.4.6 the server clamps explicit creation sizes UP to per-type
 readability floors (e.g. markdown 360×180, graph/json-render/html 420×280, mcp-app 480×320) —
 a tiny probe size silently becomes the floor. `strictSize: true` is the only opt-out (a fixed
 scrolling frame you genuinely want small). `canvas_query { action: "validate" }` additionally
@@ -258,6 +275,49 @@ or host actions.
 Read [AX HTML control surfaces](references/ax-html-control-surface.md) before building an
 interactive AX-enabled HTML node.
 
+### Ready-made control surfaces (0.4.7+) — prefer these over hand-rolling
+
+Two HTML primitives ship AX-enabled, so you do not need to author a control surface or pass
+`axCapabilities` yourself. They are the ONLY primitives created with AX on; every other kind is
+still a static document.
+
+- **`ax-board`** — task list: create tasks, watch status change live, steer, bounded loop.
+- **`ax-flow`** — the same controls drawn as a task flow with a loop-back rail, plus
+  **Materialize to board**.
+
+**`ax.flow.materialize`** is the one interaction that creates canvas nodes, and it is deliberately
+narrow: you supply TEXT ONLY (<= 12 steps, title <= 120 chars) and the server owns the result —
+one `markdown` node per step, `flow` edges between them, a dashed `references` loop edge, and one
+work item per step linked to its node. Re-materializing REPLACES the previous flow (the source
+node keeps a manifest of what it created), so it is safe to call repeatedly.
+
+**The flow also works without the panel.** Materialized step nodes carry `data.axStep`, and the
+canvas renders native Start / Done / Blocked controls on them, with Run loop / Stop and a steer box
+on the anchor (first) step. Those controls also follow the node into focus mode. The native loop
+runs **server-side**: it advances when a step's work item completes, survives a browser reload, and
+keeps going while the tab is closed — unlike the panel's loop, which dies with the iframe. Bounds
+are the same either way: advances only while running, hard cap 20 runs, Stop persists immediately,
+and `blocked`/`cancelled` halts it.
+
+When you want the agent to work through a checklist the human can watch and steer, reach for
+`ax-flow` + materialize rather than a markdown to-do list — the status chips and the loop come free.
+
+### Working a flow: keep the board honest as you go
+
+A materialized flow is only useful if it tracks reality. While you work one:
+
+1. **Move the step to `in-progress` BEFORE you start it, and to `done` when it is actually done** —
+   not in a batch at the end. The human is watching the chips to know where you are; a board that
+   only updates on completion tells them nothing while it matters.
+2. **Pin the in-progress step as context** (`canvas_pin_nodes` with just that node, or
+   `POST /api/canvas/context-pins` mode `set`). This makes the active step the one thing in
+   `canvas://pinned-context`, so the board's "what am I working on" and your own context are the
+   same answer instead of drifting apart. Re-pin as you advance.
+3. **Mark `blocked` rather than going quiet** when you are stuck — a stalled `in-progress` chip is
+   indistinguishable from a crashed agent.
+4. Read steering back with `canvas_ax_delivery` as you go; a human watching a live flow steers
+   mid-run, and a steer you never claim is a correction you ignored.
+
 ## Resources
 
 Read the smallest resource that answers the question:
@@ -308,8 +368,8 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - A hosted ext-app (Excalidraw) resized NARROW/TALL (e.g. 360x529) can show its diagram in the
   upper region with the app's own dark fill below it — in every engine (0.3.4 report Finding Q).
   This letterboxing lives inside the hosted app bundle's root container, not in PMX (a body-level
-  background override ships but cannot reach the app's inner root). Keep ext-app tiles near the
-  app's aspect (the 960x738 default, or the same ratio), or expand the node — the fullscreen
+  background override ships but cannot reach the app's inner root). Keep ext-app tiles landscape —
+  at or above the 720x500 they open at, or the same ratio — or expand the node: the fullscreen
   overlay renders full-bleed. The durable fix is upstream in the excalidraw-mcp app.
 - Behind proxies that buffer streaming responses (e.g. portal hosts), the workbench auto-falls
   back from SSE to a polling transport within ~3s, so the board still boots and stays live.
@@ -327,10 +387,11 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
-  reflow on a live window resize in a normal browser. Some single-tab host browsers historically
-  didn't deliver live-resize events (current Codex builds do — the 0.4.0 retest saw a standalone
-  graph reflow on a native viewport resize), so if a resized standalone chart looks stale,
-  reload it or use a system browser for separate full-page viewing.
+  reflow on a live window resize. Some single-tab host browsers historically didn't deliver
+  live-resize events; current Codex builds do — the 0.4.6 pass watched a standalone graph reflow
+  live (SVG 1550×783 → 850×483 on a 1600×900 → 900×600 window resize) with no reload. Do not
+  present a system browser as a workaround for stale resizing; it is only a preference for viewing
+  a full page beside the canvas.
 - Some hosts cannot automate inside sandboxed workbench iframes. Verify those interactions in a
   system browser or through server-side AX state.
 - `pmx-canvas screenshot` requires an active WebView. Start it with

package/skills/pmx-canvas/evals/evals.json

@@ -417,7 +417,7 @@
       "id": 17,
       "name": "standalone-surface-open-as-site",
       "prompt": "Open the bar-chart graph node as a standalone full-page site for a screenshot, and also try to open the Excalidraw diagram node the same way. Tell me the correct surface URL for each.",
-      "expected_output": "For the graph/json-render node, uses the stable surface URL /api/canvas/surface/<id> which redirects to the full-viewport display=site viewer (reads surfaceUrl from the node, does not fabricate a path). Recognizes the hosted Excalidraw/ext-app node is NOT an open-as-site target (its surface route returns a clean 404 \u2014 it renders only with the in-canvas host bridge) and does not claim a standalone tab will work. Notes that some host browsers (e.g. the Codex in-app single-tab browser) don't deliver live-resize events, so a system browser is recommended for separate full-page viewing.",
+      "expected_output": "For the graph/json-render node, uses the stable surface URL /api/canvas/surface/<id> which redirects to the full-viewport display=site viewer (reads surfaceUrl from the node, does not fabricate a path). Recognizes the hosted Excalidraw/ext-app node is NOT an open-as-site target (its surface route returns a clean 404 \u2014 it renders only with the in-canvas host bridge, and open-external refuses it with the same message) and does not claim a standalone tab will work. Describes the standalone surface as reflowing live on a window resize; does not claim host browsers leave a resized chart stale until reload, and does not prescribe a system browser as a workaround.",
       "assertions": [
         {
           "name": "graph-site-surface-url",
@@ -430,8 +430,59 @@
           "type": "output_check"
         },
         {
-          "name": "host-browser-caveat",
-          "description": "Recommends a system browser for separate full-page viewing and/or notes single-tab host browsers may not reflow on live resize",
+          "name": "no-stale-resize-claim",
+          "description": "Does not assert that host browsers fail to deliver live resize (current Codex builds do — the 0.4.6 pass saw a standalone graph reflow live with no reload); a system browser may be offered as a viewing preference, never as a resize workaround",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 18,
+      "name": "in-view-placement-after-create",
+      "prompt": "The board already has a cluster of nodes from this morning, way off to the far right. Add a markdown summary of the incident and a status node for the follow-up, and make sure I can actually see them.",
+      "expected_output": "Places the new nodes near the human's attention (pinned/focused neighborhood or beside the last user-facing output) instead of trusting board-relative auto-placement on a spread-out board, then pans the camera: canvas_view {action:focus} for a single node, or canvas_view {action:fit, nodeIds:[...]} with exactly the new ids for the pair. Does not hand-compute the whole board's coordinates and does not fit the whole board to 'show' the new work — an outlier cluster would miniaturize everything.",
+      "assertions": [
+        {
+          "name": "ends-with-focus-or-fit",
+          "description": "Finishes with canvas_view {action:focus} (single node) or {action:fit} after creating the nodes, rather than leaving them off-camera",
+          "type": "output_check"
+        },
+        {
+          "name": "fit-targets-new-ids-only",
+          "description": "Passes exactly the new node ids to fit instead of fitting the whole board (a distant cluster would shrink everything)",
+          "type": "output_check"
+        },
+        {
+          "name": "no-whole-board-coordinate-math",
+          "description": "Places relative to the human's attention or uses create-then-arrange; does not hand-compute a full board layout in pixels",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 19,
+      "name": "node-size-discipline",
+      "prompt": "Add a markdown write-up of the outage and a bar chart of the error counts. Keep them tight — I don't want huge tiles.",
+      "expected_output": "Omits width/height and takes the per-type defaults (markdown 640×420, graph 760×520) rather than passing small probe sizes for human-readable content. Uses strictSize:true only for a deliberately fixed small frame, not to dodge the floor. Reads the size back from the create result or the layout before any layout math, because the server clamps an undersized explicit frame UP to the per-type floor (markdown 360×180, graph 420×280) — the returned size can differ from what was requested.",
+      "assertions": [
+        {
+          "name": "uses-type-defaults",
+          "description": "Omits width/height (or passes a readable size) instead of guessing a frame for readable content",
+          "type": "output_check"
+        },
+        {
+          "name": "no-tiny-probe-sizes",
+          "description": "Does not create human-readable nodes at tiny probe sizes that the floor would silently raise",
+          "type": "output_check"
+        },
+        {
+          "name": "strict-size-only-when-deliberate",
+          "description": "Reaches for strictSize:true only for an intentionally fixed small frame, not as a way around the readability floor",
+          "type": "output_check"
+        },
+        {
+          "name": "reads-back-created-size",
+          "description": "Reads the actual created size from the create result / canvas_query layout before positioning or sizing anything else, rather than assuming the requested size was kept",
           "type": "output_check"
         }
       ]

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

@@ -952,12 +952,15 @@ the host's embedded browser (e.g. Codex) opens `_blank` tabs in-place.
   renders with the in-canvas host bridge — a bare tab has no peer, so the surface route
   returns `404` ("This MCP app renders in the canvas and cannot be opened as a standalone
   site"); view/edit them in the canvas, or open them externally through their own app
-  (report #61). Only bundled `web-artifact` apps (redirect to `/artifact`) and URL-backed
-  `mcp-app` / `webpage` viewers redirect to their external site.
+  (report #61). `POST /api/canvas/open-external` refuses those nodes with the same message
+  instead of launching a browser at a URL that 404s. Only bundled `web-artifact` apps
+  (redirect to `/artifact`) and URL-backed `mcp-app` / `webpage` viewers redirect to their
+  external site.
 - `graph` / `json-render` nodes redirect to the full-viewport `display=site` viewer; the chart
-  fills the window and reflows on a live resize in a normal browser. Single-tab host browsers
-  that don't deliver live-resize events (e.g. the Codex in-app browser) can leave a resized chart
-  stale until reload — recommend a system browser for separate full-page viewing (report #67).
+  fills the window and reflows on a live resize. Current Codex builds deliver live-resize events —
+  the 0.4.6 pass watched a standalone graph reflow live (SVG 1550×783 → 850×483 on a
+  1600×900 → 900×600 window resize) with no reload — so do not present a system browser as a
+  workaround for stale resizing (report #67).
 - This is additive — opening a site never evicts or replaces canvas nodes.
 
 ### Choosing the Right Visual Tier
@@ -1112,7 +1115,7 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 
 | Node type | Allowed AX interaction types |
 |-----------|------------------------------|
-| `markdown` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `markdown` | `ax.steer`, `ax.work.create`, `ax.work.update`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `context` | `ax.focus.set`, `ax.steer`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `status` | `ax.work.create`, `ax.work.update`, `ax.approval.request`, `ax.mode.request`, `ax.event.record` |
 | `file` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
@@ -1121,6 +1124,8 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 | `ledger` | `ax.evidence.add`, `ax.event.record` |
 | `trace` | `ax.evidence.add`, `ax.event.record` |
 | `image` | `ax.evidence.add`, `ax.review.add` |
+| `diff` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `mermaid` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
 | `webpage` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
 | `group` | `ax.focus.set`, `ax.work.create`, `ax.command.invoke`, `ax.event.record` |
 

package/src/cli/commands/history.ts

@@ -81,7 +81,7 @@ cmd(
   'Show canvas mutation history',
   ['pmx-canvas history', 'pmx-canvas history --summary', 'pmx-canvas history --compact'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('history');
 
     const result = (await invokeOperation('history.get', {})) as Record<string, unknown>;

package/src/cli/commands/nodes.ts

@@ -691,7 +691,7 @@ cmd(
     'pmx-canvas node schema --summary',
   ],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('node schema');
 
     const result = await loadCanvasSchema();
@@ -783,7 +783,7 @@ cmd(
     'pmx-canvas node get node-abc123 --field title --field graphConfig',
   ],
   async (args) => {
-    const { positional, flags } = parseFlags(args);
+    const { positional, flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('node get');
 
     const id = positional[0];

package/src/cli/commands/query.ts

@@ -65,7 +65,7 @@ cmd(
     'pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary',
   ],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('validate spec');
 
     const type = getStringFlag(flags, 'type');

package/src/cli/commands/view.ts

@@ -44,7 +44,7 @@ cmd(
   'Get the full canvas layout (nodes, edges, viewport)',
   ['pmx-canvas layout', 'pmx-canvas layout --summary'],
   async (args) => {
-    const { flags } = parseFlags(args);
+    const { flags } = parseFlags(args, { boolFlags: ['summary'] });
     if (flags.help || flags.h) return showCommandHelp('layout');
 
     if (flags.summary || flags.compact) {

package/src/cli/index.ts

@@ -298,19 +298,25 @@ Agent CLI (works against running server):
   validate spec                       Validate json-render/graph payloads without creating nodes
   watch [--json] [--events ...]       Watch low-token semantic canvas changes
   focus <node-id>                     Pan to node
+  fit [node-id ...]                   Fit the viewport to all nodes or a subset
   ax status|context|focus             Inspect AX state and focus
   external-app add                    Add hosted external apps like Excalidraw
   diagram add                         Add an Excalidraw diagram node
+  html primitive add|schema           Add or inspect HTML communication primitives
   pin <ids...> | --list | --clear     Manage context pins
   undo / redo / history               Time travel
   snapshot save|list|restore|diff|delete
                                       Manage snapshots
+  diff <snapshot-id>                  Compare the canvas against a snapshot
   group create|add|remove             Manage groups
   web-artifact build                  Build bundled web artifacts
   clear --yes                         Clear canvas
   code-graph                          File dependencies
   spatial                             Spatial analysis
   watch                               Semantic watch stream
+  smoke                               Check that a running canvas works here
+  skills sync                         Sync installed copies of the bundled skills
+  copilot install-extension           Install the GitHub Copilot app extension
 
 Run any command with --help for details and examples:
   pmx-canvas node add --help

package/src/cli/shared.ts

@@ -47,6 +47,13 @@ export function extractGlobalTargetFlags(args: string[]): string[] {
     const arg = args[i];
     let name: 'port' | 'server-url' | null = null;
     let value: string | undefined;
+    if (arg === '--') {
+      // End of flags: everything after a bare `--` is an operand, so a literal
+      // `--port`-looking value is never mistaken for the global target flag.
+      // The separator itself is kept so parseFlags stops there too.
+      rest.push(...args.slice(i));
+      break;
+    }
     if (arg === '--port' || arg === '--server-url') {
       name = arg.slice(2) as 'port' | 'server-url';
       value = args[i + 1];
@@ -125,11 +132,25 @@ async function invokeOperation(name: string, input: Record<string, unknown>): Pr
 
 // ── Flag parsing ─────────────────────────────────────────────
 
-function parseFlags(args: string[]): { positional: string[]; flags: Record<string, string | true> } {
+/**
+ * `options.boolFlags` marks flags that are boolean FOR THIS COMMAND. Value
+ * flags consume the next token verbatim (so a unified diff beginning with
+ * `--- a/file` survives), which makes a flag that is boolean here and
+ * value-taking elsewhere ambiguous — `--summary` is boolean in `history` /
+ * `layout` / `node get` / `validate spec` but carries text in `node add`.
+ * Without this per-command override, `history --summary --limit 5` would
+ * swallow `--limit` as the summary's value. The global set below holds flags
+ * that are boolean everywhere.
+ */
+function parseFlags(
+  args: string[],
+  options: { boolFlags?: readonly string[] } = {},
+): { positional: string[]; flags: Record<string, string | true> } {
   const positional: string[] = [];
   const flags: Record<string, string | true> = {};
   // Boolean-only flags (never take a value argument)
-  const BOOL_FLAGS = new Set([
+  const BOOL_FLAGS = new Set<string>([
+    ...(options.boolFlags ?? []),
     'help',
     'h',
     'ids',
@@ -168,14 +189,22 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
   ]);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
+    // Conventional end-of-flags separator: the rest is positional, never flags.
+    if (arg === '--') {
+      positional.push(...args.slice(i + 1));
+      break;
+    }
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
       if (eq !== -1) {
         flags[arg.slice(2, eq)] = arg.slice(eq + 1);
       } else {
         const key = arg.slice(2);
-        // If not a boolean flag and next arg exists and isn't a flag, consume it as value
-        if (!BOOL_FLAGS.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        // A value flag consumes the very next token VERBATIM — including one
+        // that starts with `-`/`--`. Unified diffs legitimately begin with
+        // `--- a/file`, and the old "next token must not look like a flag"
+        // heuristic silently dropped that content.
+        if (!BOOL_FLAGS.has(key) && i + 1 < args.length) {
           flags[key] = args[++i];
         } else {
           flags[key] = true;
@@ -183,7 +212,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
       }
     } else if (arg.startsWith('-') && arg.length === 2) {
       const key = arg.slice(1);
-      if (!BOOL_FLAGS.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+      if (!BOOL_FLAGS.has(key) && i + 1 < args.length) {
         flags[key] = args[++i];
       } else {
         flags[key] = true;

package/src/client/App.tsx

@@ -36,10 +36,11 @@ import {
   traceEnabled,
   viewport,
   walkGraph,
+  zoomByFactor,
 } from './state/canvas-store';
 import { connectSSE } from './state/sse-bridge';
 import { intents } from './state/intent-store';
-import { saveCanvasTheme } from './state/intent-bridge';
+import { reportClientViewportSize, saveCanvasTheme } from './state/intent-bridge';
 import {
   IconArrange,
   IconClearTrace,
@@ -258,20 +259,12 @@ function Toolbar({
           </button>
         </ToolbarHint>
         <ToolbarHint label="Zoom in" shortcut={`${MOD_KEY}++`}>
-          <button
-            type="button"
-            onClick={() => animateViewport({ ...v, scale: Math.min(4, v.scale * 1.25) }, 150)}
-            aria-label="Zoom in"
-          >
+          <button type="button" onClick={() => zoomByFactor(1.25)} aria-label="Zoom in">
             <IconZoomIn />
           </button>
         </ToolbarHint>
         <ToolbarHint label="Zoom out" shortcut={`${MOD_KEY}+-`}>
-          <button
-            type="button"
-            onClick={() => animateViewport({ ...v, scale: Math.max(0.1, v.scale / 1.25) }, 150)}
-            aria-label="Zoom out"
-          >
+          <button type="button" onClick={() => zoomByFactor(1 / 1.25)} aria-label="Zoom out">
             <IconZoomOut />
           </button>
         </ToolbarHint>
@@ -585,6 +578,25 @@ export function App() {
     return connectSSE();
   }, []);
 
+  // Keep the server's idea of this window's size current (0.4.6 orb feedback
+  // #2) so an agent `fit` computes a scale that actually fits the human's
+  // window. Connect-time reporting lives in the SSE bridge; this covers resizes.
+  useEffect(() => {
+    let timer: number | null = null;
+    const schedule = () => {
+      if (timer !== null) window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        timer = null;
+        void reportClientViewportSize();
+      }, 400);
+    };
+    window.addEventListener('resize', schedule);
+    return () => {
+      if (timer !== null) window.clearTimeout(timer);
+      window.removeEventListener('resize', schedule);
+    };
+  }, []);
+
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       const mod = e.metaKey || e.ctrlKey;
@@ -640,12 +652,13 @@ export function App() {
         animateViewport({ x: 0, y: 0, scale: 1 }, 250);
       } else if (mod && (e.key === '=' || e.key === '+')) {
         e.preventDefault();
-        const cur = viewport.value;
-        animateViewport({ ...cur, scale: Math.min(4, cur.scale * 1.25) }, 150);
+        // Same centre-anchored zoom as the toolbar +/- buttons these shortcuts
+        // are advertised on (the tooltip names this key) — a raw scale change
+        // is origin-anchored and drifts the board away under the cursor.
+        zoomByFactor(1.25);
       } else if (mod && e.key === '-') {
         e.preventDefault();
-        const cur = viewport.value;
-        animateViewport({ ...cur, scale: Math.max(0.1, cur.scale / 1.25) }, 150);
+        zoomByFactor(1 / 1.25);
       } else if (e.key === 'Escape') {
         if (selectedNodeIds.value.size > 0) {
           clearSelection();

package/src/client/canvas/CanvasNode.tsx

@@ -21,15 +21,54 @@ import {
   viewport,
 } from '../state/canvas-store';
 import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-bridge';
+import { AxStepControls } from '../nodes/AxStepControls';
 import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
-import { computeAutoFitHeight, shouldAutoFitNode } from './auto-fit';
+import { AUTO_FIT_TITLEBAR_HEIGHT, 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';
 
+/** 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);
+}
+
 interface CanvasNodeProps {
   node: CanvasNodeState;
   children: preact.ComponentChildren;
@@ -220,7 +259,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
   const isGroup = node.type === 'group';
   const isStrictSize = node.data.strictSize === true;
   const viewportScale = Math.max(viewport.value.scale, 0.01);
-  const chromeScale = viewportScale < 1 ? Math.min(2.2, 1 / viewportScale) : 1;
+  const chromeScale = nodeChromeScale(viewportScale, node.collapsed ? 0 : node.size.height, node.size.width);
 
   const groupColor = isGroup && node.data.color ? (node.data.color as string) : undefined;
   const nodeStyle: Record<string, string | number> = {
@@ -261,9 +300,13 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
             return <NodeIcon size={Math.round(14 * chromeScale)} />;
           })()}
         </span>
-        <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
-        {typeof node.data.axWorkStatus === 'string' && (
+        {/* The icon already says what type this is, so the type badge yields to
+            the status chip rather than stacking two pills in front of the name —
+            on a narrow node that combination pushed the title to an ellipsis. */}
+        {typeof node.data.axWorkStatus === 'string' ? (
           <span class={`node-ax-status node-ax-status-${node.data.axWorkStatus}`}>{node.data.axWorkStatus}</span>
+        ) : (
+          <span class="node-type-badge">{TYPE_LABELS[node.type]}</span>
         )}
         {renaming ? (
           <input
@@ -278,7 +321,7 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
             onClick={(e) => e.stopPropagation()}
           />
         ) : (
-          <span class="node-title" onDblClick={handleTitleDblClick} title="Double-click to rename">
+          <span class="node-title" onDblClick={handleTitleDblClick} title={`${title} — double-click to rename`}>
             {title}
           </span>
         )}
@@ -356,6 +399,12 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
       {!node.collapsed && (
         <div ref={bodyRef} class="node-body">
           {children}
+          {/* AX flow step controls — rendered here rather than in a node renderer
+              because a materialized step can be ANY node type, and because the
+              body is what auto-fit measures (a footer outside it would be clipped
+              on a content-fitted node). Renders nothing unless the node carries a
+              `data.axStep` stamp. */}
+          <AxStepControls node={node} />
         </div>
       )}
       {!node.collapsed && (