pmx-canvas 0.4.5 → 0.4.7

package/dist/types/server/ax-interaction.d.ts

@@ -15,10 +15,10 @@
  * import cycle (canvas-state → canvas-provenance must not pull this in).
  */
 import { z } from 'zod';
-import type { CanvasNodeState } from './canvas-state.js';
+import type { CanvasEdge, CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { CanvasNodeType } from './canvas-provenance.js';
 import type { PmxAxApprovalGate, PmxAxElicitation, PmxAxEvent, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxMode, PmxAxModeRequest, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxSource, PmxAxSteeringMessage, PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
-export declare const AX_INTERACTION_TYPES: readonly ["ax.event.record", "ax.steer", "ax.work.create", "ax.work.update", "ax.evidence.add", "ax.approval.request", "ax.approval.resolve", "ax.review.add", "ax.focus.set", "ax.command.invoke", "ax.elicitation.request", "ax.mode.request"];
+export declare const AX_INTERACTION_TYPES: readonly ["ax.event.record", "ax.steer", "ax.work.create", "ax.work.update", "ax.evidence.add", "ax.approval.request", "ax.approval.resolve", "ax.review.add", "ax.focus.set", "ax.command.invoke", "ax.elicitation.request", "ax.mode.request", "ax.flow.materialize"];
 export type AxInteractionType = (typeof AX_INTERACTION_TYPES)[number];
 export type AxDeliveryMode = 'record-only' | 'notify-agent' | 'send-to-agent';
 export interface NodeAxCapabilities {
@@ -59,6 +59,7 @@ declare const InteractionEnvelopeSchema: z.ZodObject<{
         "ax.command.invoke": "ax.command.invoke";
         "ax.elicitation.request": "ax.elicitation.request";
         "ax.mode.request": "ax.mode.request";
+        "ax.flow.materialize": "ax.flow.materialize";
     }>;
     sourceNodeId: z.ZodString;
     sourceSurface: z.ZodOptional<z.ZodEnum<{
@@ -98,6 +99,13 @@ export interface AxInteractionInput {
  */
 export interface AxInteractionManager {
     getNode(id: string): CanvasNodeState | undefined;
+    /** Canvas read for `ax.flow.materialize` (placement obstacles + stale flow sweep). */
+    getLayout(): CanvasLayout;
+    addNode(node: CanvasNodeState): void;
+    updateNode(id: string, patch: Partial<CanvasNodeState>): void;
+    /** Also drops the node's edges — the flow's replace path relies on that. */
+    removeNode(id: string): void;
+    addEdge(edge: CanvasEdge): boolean;
     recordAxEvent(input: {
         kind: PmxAxEventKind;
         summary: string;
@@ -200,6 +208,17 @@ export interface AxInteractionResult {
     result: AxInteractionPublicResult;
     events: AxInteractionEvent[];
 }
+export interface AxFlowMaterializeInput {
+    title?: string;
+    steps: Array<{
+        title: string;
+        detail?: string;
+    }>;
+    loop?: {
+        enabled?: boolean;
+        maxRuns?: number;
+    };
+}
 /**
  * Validate + execute a node-originated AX interaction. Returns the public result
  * plus the SSE events the caller should emit (accepted/rejected outcome + the

package/dist/types/server/canvas-operations.d.ts

@@ -259,5 +259,10 @@ export declare function createCanvasGraphNode(input: GraphNodeInput): {
     spec: JsonRenderSpec;
     node: CanvasNodeState;
 };
+export declare function setClientViewportSize(width: unknown, height: unknown): void;
+export declare function getClientViewportSize(): {
+    width: number;
+    height: number;
+} | null;
 export declare function fitCanvasView(options?: CanvasFitViewOptions): CanvasFitViewResult;
 export {};

package/dist/types/server/canvas-provenance.d.ts

@@ -1,4 +1,4 @@
-export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'html' | 'group';
+export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
 export type CanvasNodeProvenanceSourceKind = 'workspace-file' | 'webpage-url' | 'mcp-tool' | 'artifact-file' | 'image-url';
 export type CanvasNodeRefreshStrategy = 'file-watch' | 'file-read-write' | 'image-reload' | 'webpage-refresh' | 'mcp-app-rehydrate' | 'artifact-reopen';
 export interface CanvasNodeProvenance {

package/dist/types/server/canvas-state.d.ts

@@ -53,7 +53,7 @@ export interface CanvasSnapshotGcResult {
 }
 export interface CanvasNodeState {
     id: string;
-    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'html' | 'group';
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
     position: {
         x: number;
         y: number;
@@ -154,6 +154,15 @@ declare class CanvasStateManager {
      * — e.g. the long-lived MCP subscription — may ignore the return value).
      */
     onChange(cb: (type: CanvasChangeType) => void): () => void;
+    private _workItemsChangedListener;
+    /**
+     * Register THE work-item change listener (single slot, last-write-wins).
+     * Fired after addWorkItem/updateWorkItem completes (including the node
+     * status mirror), so live views like the workboard can rebuild from the
+     * fresh work-item list.
+     */
+    setWorkItemsChangedListener(listener: (() => void) | null): void;
+    private notifyWorkItemsChanged;
     private notifyChange;
     private _mutationRecorder;
     private _suppressRecordingDepth;
@@ -268,6 +277,14 @@ declare class CanvasStateManager {
     setTheme(theme: CanvasTheme): CanvasTheme;
     get contextPinnedNodeIds(): Set<string>;
     getAxState(): PmxAxState;
+    /**
+     * Replace the canvas-bound AX partition from a persisted blob, normalized against
+     * the current node set — the same operation snapshot restore performs internally
+     * (`applyPersistedState`), exposed for the demo seed. Both restore nodes whose
+     * `data.axStep.workItemId` only resolves if the work items come back with their
+     * original ids, so this preserves them verbatim rather than re-creating them.
+     */
+    applyPersistedAxState(ax: unknown): void;
     getAxFocus(): PmxAxFocusState;
     setAxFocus(nodeIds: string[], options?: {
         source?: PmxAxSource;

package/dist/types/server/canvas-validation.d.ts

@@ -1,4 +1,5 @@
-import type { CanvasLayout } from './canvas-state.js';
+import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
+export { NODE_MIN_SIZES, clampCreateNodeSize, nodeMinSize } from '../shared/node-sizes.js';
 export interface CanvasValidationPair {
     aId: string;
     aTitle: string | null;
@@ -11,6 +12,21 @@ export interface CanvasContainmentIssue {
     childId: string;
     childTitle: string | null;
 }
+export interface CanvasSizeWarning {
+    id: string;
+    title: string | null;
+    type: CanvasNodeState['type'];
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+}
+export interface CanvasHiddenEdgeEndpoint {
+    edgeId: string;
+    nodeId: string;
+    nodeTitle: string | null;
+    dockPosition: 'left' | 'right';
+}
 export interface CanvasValidationResult {
     ok: boolean;
     collisions: CanvasValidationPair[];
@@ -21,6 +37,15 @@ export interface CanvasValidationResult {
         from: string;
         to: string;
     }>;
+    /**
+     * Edges whose endpoint node is DOCKED — it renders in the HUD column, not on
+     * the canvas, so the edge visually terminates in empty space even though both
+     * endpoint IDs resolve (0.4.6 orb feedback #1). Advisory: reported for
+     * diagnosis, but does NOT fail `ok` (see the note at the return site).
+     */
+    hiddenEdgeEndpoints: CanvasHiddenEdgeEndpoint[];
+    /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
+    sizeWarnings: CanvasSizeWarning[];
     summary: {
         nodes: number;
         edges: number;
@@ -28,6 +53,8 @@ export interface CanvasValidationResult {
         containments: number;
         containmentViolations: number;
         missingEdgeEndpoints: number;
+        hiddenEdgeEndpoints: number;
+        sizeWarnings: number;
     };
 }
 export declare function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResult;

package/dist/types/server/file-content.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared disk reader for `file` canvas nodes.
+ *
+ * Both entry points that put a file on the canvas — `buildFileNodeData`
+ * (creation) and the file watcher (live updates) — go through here so their
+ * notion of "what this file is" can never drift. Reading a file blind with
+ * `readFileSync(path, 'utf-8')` turned binaries into mojibake and had no size
+ * ceiling at all, so a multi-GB file was pulled into memory as a string.
+ */
+/** Text past this many bytes is stored truncated instead of whole. */
+export declare const MAX_FILE_TEXT_BYTES: number;
+export type FileNodeContent = 
+/** Missing, unreadable, or not a regular file — the node stays path-backed. */
+{
+    kind: 'unavailable';
+} | {
+    kind: 'binary';
+    byteSize: number;
+    mtimeMs: number;
+    mimeType?: string;
+} | {
+    kind: 'text';
+    byteSize: number;
+    mtimeMs: number;
+    text: string;
+    lineCount: number;
+    truncated: boolean;
+};
+/**
+ * PDF check straight from a path, for the byte route's server-derived
+ * Content-Type. Reads only the magic-byte prefix. Any read failure is "not a
+ * PDF" — the caller then serves an opaque download rather than an inline type.
+ */
+export declare function isPdfFilePath(filePath: string): boolean;
+/**
+ * Classify a file and read at most `MAX_FILE_TEXT_BYTES` of it.
+ *
+ * Never throws: an unreadable path is reported as `unavailable`, matching the
+ * pre-existing behavior where a bad path still rendered as a file node.
+ */
+export declare function readFileNodeContent(filePath: string): FileNodeContent;
+/**
+ * Map a read result onto `file` node data in place, clearing the fields the new
+ * state contradicts (a file that turns binary must not keep stale decoded text).
+ */
+export declare function applyFileContentToNodeData(data: Record<string, unknown>, content: FileNodeContent): Record<string, unknown>;

package/dist/types/server/html-primitives.d.ts

@@ -1,4 +1,5 @@
-export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "presentation", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner"];
+import type { AxInteractionType } from './ax-interaction.js';
+export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "presentation", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner", "ax-board", "ax-flow"];
 export type HtmlPrimitiveKind = (typeof HTML_PRIMITIVE_KINDS)[number];
 export interface HtmlPrimitiveDescriptor {
     kind: HtmlPrimitiveKind;
@@ -11,6 +12,17 @@ export interface HtmlPrimitiveDescriptor {
     };
     dataShape: string;
     example: Record<string, unknown>;
+    /**
+     * AX capabilities this kind REQUIRES to function. `html` is AX-opt-in, so a
+     * primitive that emits interactions is inert without them — node creation
+     * applies this to `data.axCapabilities` (an explicit caller value still wins,
+     * and the server clamps both to the `html` type ceiling). Only set it on kinds
+     * that actually emit; every other kind stays AX-free.
+     */
+    axCapabilities?: {
+        enabled: true;
+        allowed: AxInteractionType[];
+    };
 }
 export interface HtmlPrimitiveInput {
     kind: HtmlPrimitiveKind;

package/dist/types/server/html-surface.d.ts

@@ -53,6 +53,14 @@ export declare function buildAxStateBridge(axToken: string, snapshotJson: string
  * and the json-render injection site stay byte-identical (no drift).
  */
 export declare function buildContentHeightReporter(frameToken: string): string;
+/**
+ * Author-HTML fragment for a `mermaid` node surface: the HTML-escaped diagram
+ * source in a hidden `<pre>` the entry script reads back via textContent, plus
+ * the separately-built renderer bundle (dist/canvas/mermaid-entry.js — kept out
+ * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
+ * data and must not be parsed as markup.
+ */
+export declare function buildMermaidSurfaceHtml(source: string): string;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
     /**

package/dist/types/server/index.d.ts

@@ -161,9 +161,12 @@ export declare class PmxCanvas extends EventEmitter {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     sendSteering(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     /**
@@ -198,6 +201,7 @@ export declare class PmxCanvas extends EventEmitter {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -206,6 +210,7 @@ export declare class PmxCanvas extends EventEmitter {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;

package/dist/types/server/operations/ops/ax-work.d.ts

@@ -1,2 +1,3 @@
+import '../../ax-flow-loop.js';
 import { type Operation } from '../types.js';
 export declare const axWorkOperations: Operation[];

package/dist/types/server/operations/ops/nodes.d.ts

@@ -1,6 +1,6 @@
 import { type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
 import { type Operation } from '../types.js';
-export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "image", "mcp-app", "webpage", "html", "group"];
+export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "diff", "mermaid", "image", "mcp-app", "webpage", "html", "group"];
 /** Per-type default node frame size (formerly copy-pasted ladders). */
 export declare function defaultNodeSize(type: string): {
     width: number;

package/dist/types/server/server.d.ts

@@ -22,6 +22,7 @@
  * - POST /api/canvas/json-render  -> create a native json-render node
  * - POST /api/canvas/graph        -> create a native graph node
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
+ * - GET  /api/canvas/file-bytes?nodeId=... -> raw bytes for a file node
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
  * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)

package/dist/types/server/web-artifacts.d.ts

@@ -53,6 +53,20 @@ export interface WebArtifactCanvasBuildResult extends WebArtifactBuildOutput {
 }
 export declare function resolveWorkspacePath(pathLike: string, cwd?: string): string;
 export declare function resolveWebArtifactScriptPath(kind: 'init' | 'bundle'): string;
+export type NodeVersionCheck = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Pure preflight comparison used before any package-manager invocation.
+ * `detected` is raw `node --version` output ("v20.11.1"), or null when no node
+ * executable answered; `required` is a `major.minor` floor; `packageManager` is
+ * the pin that imposes it (e.g. "pnpm@11.1.2"). Returns an actionable message
+ * instead of throwing so every caller surfaces it on its own error channel.
+ */
+export declare function checkWebArtifactNodeVersion(detected: string | null, required: string, packageManager: string): NodeVersionCheck;
 export declare function executeWebArtifactBuild(input: WebArtifactBuildInput): Promise<WebArtifactBuildOutput>;
 export declare function openWebArtifactInCanvas(input: {
     title: string;

package/dist/types/server/workboard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Live AX work-item board, materialized as a json-render node.
+ *
+ * `buildWorkboardSpec` is the pure spec builder (status columns of work-item
+ * cards); `renderWorkboard` is the operation core (create-or-rebuild the
+ * single `data.workboard === true` json-render node); `refreshWorkboardNodes`
+ * is the live-refresh hook this module registers on `canvasState` so every
+ * addWorkItem/updateWorkItem rebuilds the board from the fresh work-item list
+ * through the SAME spec/update path the operation uses.
+ *
+ * The refresh runs inside `withSuppressedRecording` so live board rebuilds do
+ * not spam undo/redo history (persistence and SSE emits are unaffected).
+ */
+import type { JsonRenderSpec } from '../json-render/server.js';
+import type { PmxAxWorkItem } from './ax-state.js';
+export declare const WORKBOARD_NODE_TITLE = "Work Board";
+export declare const WORKBOARD_NODE_SIZE: {
+    width: number;
+    height: number;
+};
+/**
+ * Build the workboard json-render spec from a work-item list: one column per
+ * status (todo → in-progress → blocked → done → cancelled; empty statuses are
+ * omitted), each item a Card with an agentId Badge and detail Text when
+ * present. An empty list renders a single muted "No work items" text block.
+ */
+export declare function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec;
+/**
+ * Operation core for `render.workboard`: rebuild the existing workboard node
+ * in place, or create one (tagged `data.workboard: true`) when none exists.
+ */
+export declare function renderWorkboard(input?: {
+    x?: number;
+    y?: number;
+}): {
+    ok: true;
+    id: string;
+    created: boolean;
+    itemCount: number;
+};
+/**
+ * Live refresh: rebuild every workboard node's spec from the current work-item
+ * list. Registered below as the canvasState work-item change listener. Node
+ * updates never touch work items, so this cannot recurse.
+ */
+export declare function refreshWorkboardNodes(): void;

package/dist/types/shared/ax-flow.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The node-data contract for a materialized AX flow.
+ *
+ * `ax.flow.materialize` stamps every step node with `data.axStep` and the anchor
+ * (first) step with `data.axFlow`. Three consumers read those stamps and none of
+ * them owns the shape, so it lives here:
+ *   - the server loop (`ax-flow-loop.ts`) advances the flow from work-item changes
+ *   - the browser renders native Start/Done/Blocked + Run loop/Stop controls
+ *   - snapshots/restore carry the stamps as ordinary node data
+ *
+ * Node data is `Record<string, unknown>` on both sides, so the readers below are
+ * the ONLY way to narrow it: they validate rather than cast, because a stamp can
+ * also arrive from a restored snapshot or a hand-edited node.
+ */
+/** Hard ceiling on loop passes, whatever a node's stamped `maxRuns` claims. */
+export declare const AX_FLOW_LOOP_HARD_CAP = 20;
+/** One step of a flow, as recorded on the anchor node. */
+export interface AxFlowStepRef {
+    /** 1-based position in the flow. */
+    index: number;
+    nodeId: string;
+    workItemId: string;
+    title: string;
+}
+export interface AxFlowLoopState {
+    /** The loop only advances while this is true; Stop persists `false`. */
+    running: boolean;
+    /** Completed passes. `run >= maxRuns` ends the loop. */
+    run: number;
+    maxRuns: number;
+}
+/** `data.axStep` — stamped on EVERY step node, including the anchor. */
+export interface AxFlowStepStamp {
+    flowId: string;
+    index: number;
+    total: number;
+    workItemId: string;
+}
+/** `data.axFlow` — stamped on the anchor (first) step node only. */
+export interface AxFlowStamp {
+    flowId: string;
+    title: string;
+    steps: AxFlowStepRef[];
+    loop: AxFlowLoopState;
+}
+/** Clamp a stamped `maxRuns` into [1, AX_FLOW_LOOP_HARD_CAP]. */
+export declare function clampAxFlowMaxRuns(value: unknown): number;
+/** Read `data.axStep`, or null when the node carries no valid step stamp. */
+export declare function readAxStep(data: Record<string, unknown>): AxFlowStepStamp | null;
+/** Read `data.axFlow`, or null when the node is not a flow anchor. */
+export declare function readAxFlow(data: Record<string, unknown>): AxFlowStamp | null;

package/dist/types/shared/ax-surface-protocol.d.ts

@@ -16,3 +16,10 @@ export declare const AX_SURFACE_ACK_SOURCE = "pmx-canvas-ax-ack";
 export declare const HTML_SURFACE_PUSH_SOURCE = "pmx-canvas-html-node";
 /** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
 export declare const EXT_APP_BOOT_BEACON_SOURCE = "pmx-canvas-ext-app-alive";
+/**
+ * Parent→ext-app paint probe (Finding N): the parent asks the app document to
+ * answer with a double-rAF `paint-tick` beacon. A frame whose rendering
+ * pipeline is live answers within a frame or two; silence past the timeout is
+ * the paint-fail signal that drives the recovery ladder.
+ */
+export declare const EXT_APP_PAINT_PROBE_SOURCE = "pmx-canvas-ext-app-paint-probe";

package/dist/types/shared/node-sizes.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-type minimum node size — the readability floor.
+ *
+ * Agents frequently create nodes with explicit frames far too small for their
+ * content (clipped markdown, charts squeezed behind inner scrollbars), so the
+ * server clamps undersized explicit sizes UP at creation and `validate` reports
+ * anything below the floor.
+ *
+ * This lives in `shared/` because BOTH sides must honor it. The 0.4.6 report's
+ * Finding AA: the server clamped a 200x100 markdown node up to 360x180, and
+ * then the browser's DOM auto-fit measured the (short) content and persisted
+ * 360x132 — undoing the guarantee on the most common path, a connected
+ * workbench. A floor only one side knows about is not a floor.
+ *
+ * `strictSize: true` is the escape hatch for a deliberately small fixed frame,
+ * and it exempts a node from both the creation clamp and the auto-fit floor.
+ * Types absent from the table are intentionally unclamped — `trace` is small by
+ * design, `group` sizes to its children.
+ */
+export declare const NODE_MIN_SIZES: Record<string, {
+    width: number;
+    height: number;
+}>;
+/** The readability floor for a node type, or undefined when it has none. */
+export declare function nodeMinSize(type: string): {
+    width: number;
+    height: number;
+} | undefined;
+/** Creation-time clamp: an explicit size below the floor is raised to it. */
+export declare function clampCreateNodeSize(type: string, width: number, height: number, strictSize?: boolean): {
+    width: number;
+    height: number;
+};

package/docs/cli.md

@@ -17,7 +17,7 @@ pmx-canvas --server-url http://127.0.0.1:4750 status  # same, by URL
 
 ```bash
 pmx-canvas                            # Start canvas, open browser
-pmx-canvas --demo                     # Start with the saved dashboard demo board
+pmx-canvas --demo                     # Start with the showcase demo board
 pmx-canvas --port=8080                # Custom port
 pmx-canvas --no-open                  # Headless (for agents/CI)
 pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest | volt
@@ -119,11 +119,28 @@ pmx-canvas watch --events context-pin,move-end
 pmx-canvas watch --json --events context-pin --max-events 1
 ```
 
-## Focus
+## Focus and fit
 
 ```bash
 pmx-canvas focus <node-id>            # Pan viewport to a node
 pmx-canvas focus <node-id> --no-pan   # Select/raise without panning
+pmx-canvas fit                        # Fit the viewport to every node
+pmx-canvas fit <id-a> <id-b>          # Fit to just these nodes
+```
+
+`fit` sizes itself to the connected browser window, so you rarely need to pass
+`--width` / `--height`. After creating output a human should see, focus a single
+node or fit the new ids — auto-placement is board-relative, not camera-relative.
+
+## Snapshots
+
+```bash
+pmx-canvas snapshot save --name "before-refactor"
+pmx-canvas snapshot list
+pmx-canvas snapshot restore <snapshot-id>
+pmx-canvas snapshot delete <snapshot-id>
+pmx-canvas snapshot gc --keep 20      # Delete all but the newest N
+pmx-canvas diff <snapshot-id>         # Compare the canvas against a snapshot
 ```
 
 ## AX context
@@ -201,6 +218,18 @@ pmx-canvas ax policy get
 pmx-canvas ax policy set --excluded-tools shell,write --mode concise
 ```
 
+## Environment smoke check
+
+```bash
+pmx-canvas smoke                 # one-command check of a running canvas
+pmx-canvas smoke --port 4750     # target a specific daemon
+```
+
+Verifies server health + workspace, CLI/server version skew, the MCP
+initialize handshake, a temporary node create/search/remove round-trip (the
+temp node is always removed, including on failure), and board validation.
+Prints a JSON report and exits 1 if any check fails.
+
 ## Copilot adapter
 
 Install the bundled GitHub Copilot extension adapter into a repo. The adapter

package/docs/environment.md

@@ -29,6 +29,7 @@ optional; defaults are listed.
 | `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe, forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there), and defaults the event transport to polling instead of SSE (the portal proxy buffers streams; `?transport=sse` overrides for diagnosis). |
 | `PORT` | server | Portal-assigned service port, honored ONLY when `AMP_ORB` is also set (Amp orbs) — after `--port`, `PMX_WEB_CANVAS_PORT`, and `PMX_CANVAS_PORT`, before the 4313 default. A stray `PORT` in normal shells never changes the port. |
 | `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
+| `PMX_CANVAS_AUTO_INTENT` | server | `0` turns off the auto-ghost: agent mutations that arrive without an explicit `canvas_intent` signal stop synthesizing a short ghost cursor. Any other value (or unset) leaves it on. |
 | `PMX_CANVAS_DIST` | server | Explicit client bundle directory to serve instead of the packaged `dist/canvas`. |
 | `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` | server | Startup timeout for the Bun.WebView automation session. |
 

package/docs/http-api.md

@@ -64,6 +64,23 @@ 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.
 
+### File node content and bytes
+
+A `file` node reads its file server-side. Text is stored on the node as
+`data.fileContent` (with `data.lineCount`); `data.byteSize` is always set.
+Non-text files are never decoded into mojibake — they carry `data.binary: true`
+with no `fileContent`, plus `data.mimeType` when the type is known
+(`application/pdf` for PDFs). A text file larger than 2 MB is stored truncated
+with `data.truncated: true`.
+
+```bash
+# Raw bytes for a binary file node (PDF viewer, downloads)
+curl http://localhost:4313/api/canvas/file-bytes?nodeId=node-abc123
+```
+
+The byte route is workspace-scoped: a file node whose path resolves outside the
+workspace root returns `403`, and an unknown node id returns `404`.
+
 ## Edges
 
 ```bash
@@ -306,6 +323,18 @@ curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?settledNodeId=no
 curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?vetoed=true"
 ```
 
+## Live work board
+
+```bash
+# Materialize (or refresh) the one board node showing all AX work items by status.
+curl -X POST http://localhost:4313/api/canvas/workboard \
+  -H 'Content-Type: application/json' -d '{}'
+```
+
+The board is a `json-render` node tagged `data.workboard: true`. Repeat calls
+are idempotent (`created: false`) and the board refreshes itself whenever a
+work item changes — no polling needed.
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -38,7 +38,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
-| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
+| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `remove` | `canvas_add_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` |
@@ -227,6 +227,18 @@ interaction against the node's effective capabilities.
 - **Commands:** `canvas_invoke_command` runs a registry command (`pmx.plan`,
   `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); unknown
   names are rejected and a successful call records a `command` agent-event.
+  Commands *record* a signal for the agent — they do not execute anything
+  server-side.
+- **`ax.flow.materialize`:** the one interaction that creates canvas nodes, and
+  it is deliberately narrow. The caller supplies text only — up to 12 steps with
+  a title (<= 120 chars) and optional detail — and the SERVER owns the resulting
+  shape: one `markdown` node per step, `flow` edges between them, a dashed
+  `references` loop edge when looping, and one work item per step linked to its
+  node (so the existing status-chip mirroring shows progress). The surface never
+  names a node type, geometry, or node data. Re-materializing replaces the
+  previous flow: the source node keeps a manifest of the ids it created, and
+  only nodes on that manifest that still carry the matching flow id are removed,
+  so a surface can never delete anything it did not create.
 
 ## Change notifications