pmx-canvas 0.4.6 → 0.4.7

package/dist/types/cli/shared.d.ts

@@ -19,7 +19,19 @@ export declare function extractGlobalTargetFlags(args: string[]): string[];
 declare function die(message: string, hint?: string): never;
 declare function output(data: unknown): void;
 declare function invokeOperation(name: string, input: Record<string, unknown>): Promise<unknown>;
-declare function parseFlags(args: string[]): {
+/**
+ * `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.
+ */
+declare function parseFlags(args: string[], options?: {
+    boolFlags?: readonly string[];
+}): {
     positional: string[];
     flags: Record<string, string | true>;
 };

package/dist/types/client/canvas/CanvasNode.d.ts

@@ -1,4 +1,15 @@
 import type { CanvasNodeState } from '../types';
+/**
+ * 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 declare function nodeChromeScale(viewportScale: number, nodeHeight: number, nodeWidth?: number): number;
 interface CanvasNodeProps {
     node: CanvasNodeState;
     children: preact.ComponentChildren;

package/dist/types/client/canvas/EdgeLayer.d.ts

@@ -1,5 +1,13 @@
 import type { Signal } from '@preact/signals';
 import type { CanvasEdge, CanvasNodeState } from '../types';
+/**
+ * Edges are drawn in world space, so a 1.5px stroke renders as 0.4 screen px at
+ * 26% zoom. Full inverse compensation keeps edge chrome at a constant SCREEN
+ * size while zoomed out (standard graph-editor behaviour). Deliberately
+ * uncapped — the 2.2 cap used for node chrome still leaves hairlines invisible
+ * at overview zoom.
+ */
+export declare function edgeChromeScale(scale: number): number;
 interface EdgeLayerProps {
     nodes: Signal<Map<string, CanvasNodeState>>;
     edges: Signal<Map<string, CanvasEdge>>;

package/dist/types/client/nodes/AxStepControls.d.ts

@@ -0,0 +1,4 @@
+import type { CanvasNodeState } from '../types';
+export declare function AxStepControls({ node }: {
+    node: CanvasNodeState;
+}): import("preact/jsx-runtime").JSX.Element | null;

package/dist/types/client/nodes/FileNode.d.ts

@@ -1,4 +1,18 @@
 import type { CanvasNodeState } from '../types';
+export interface DelimitedTable {
+    header: string[];
+    /** Rectangular: every row padded (short) or truncated (long) to the header width. */
+    rows: string[][];
+}
+/**
+ * RFC4180-ish delimited-text parser. Quoted fields may contain the delimiter,
+ * newlines, and `""` escapes; CRLF, LF and lone CR all end a record; a trailing
+ * newline produces no phantom empty row. Ragged records are squared off against
+ * the header width instead of throwing.
+ */
+export declare function parseDelimitedText(text: string, delimiter: string): DelimitedTable;
+/** Human-readable byte size, e.g. `4.2 MB`. */
+export declare function formatBytes(bytes: number): string;
 export declare function FileNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;

package/dist/types/client/state/canvas-store.d.ts

@@ -83,6 +83,16 @@ export declare function applyServerCanvasLayout(layout: Pick<CanvasLayout, 'node
  * Cancels any in-flight animation. Direct manipulation (pan/zoom gestures)
  * should use setViewport() instead for instant response.
  */
+/**
+ * Zoom by a factor about the CENTRE of the viewport.
+ *
+ * The toolbar's +/- used to change `scale` alone and keep `x`/`y`, which anchors
+ * the zoom at the world origin — so zooming in visibly slid the board up-left and
+ * zooming out pushed it down-right, instead of magnifying what you were looking
+ * at. Same correction the pointer-anchored wheel zoom applies, with the viewport
+ * centre as the anchor.
+ */
+export declare function zoomByFactor(factor: number, duration?: number): void;
 export declare function animateViewport(target: ViewportState, duration?: number, options?: {
     recordHistory?: boolean;
 }): void;

package/dist/types/client/state/intent-bridge.d.ts

@@ -155,6 +155,15 @@ export declare function updateViewportFromClient(viewport: {
 }): Promise<{
     ok: boolean;
 }>;
+/**
+ * Report this window's size WITHOUT touching the stored viewport. The
+ * viewport op defaults every omitted coordinate to the server's CURRENT
+ * viewport, so a body carrying only the size records the size and leaves the
+ * viewport exactly as it was — never echoing a stale client viewport back over
+ * the server's. Called on connect and on resize so an agent `fit` has the real
+ * window size before the human ever pans or zooms.
+ */
+export declare function reportClientViewportSize(): Promise<void>;
 /** Create a group containing the given child node IDs. */
 export declare function createGroupFromClient(opts: {
     title?: string;

package/dist/types/server/ax-flow-loop.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Advance every running flow loop on the canvas. Safe to call on any work-item
+ * change: flows that are not running, not ready, or already advanced are no-ops.
+ */
+export declare function advanceAxFlowLoops(): void;

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-state.d.ts

@@ -277,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,25 +1,5 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
-/**
- * Per-type minimum node size (0.4.5 report follow-up): agents frequently
- * create nodes with explicit frames far too small for their content — clipped
- * markdown, charts squeezed behind inner scrollbars. Explicit sizes below the
- * floor are clamped UP at creation (canvas-operations.ts creators);
- * `strictSize: true` is the escape hatch for a genuinely small fixed frame.
- * Floors sit below every type default and above the point of unreadability.
- * Creation-only: later updates are untouched (the browser's drag-resize
- * enforces its own 200×100 floor client-side), but `validate` reports any
- * node below its floor as an advisory sizeWarning. Absent types (trace,
- * group, prompt/response) are intentionally unclamped — trace is small by
- * design, groups size to their children.
- */
-export declare const NODE_MIN_CREATE_SIZES: Partial<Record<CanvasNodeState['type'], {
-    width: number;
-    height: number;
-}>>;
-export declare function clampCreateNodeSize(type: CanvasNodeState['type'], width: number, height: number, strictSize?: boolean): {
-    width: number;
-    height: number;
-};
+export { NODE_MIN_SIZES, clampCreateNodeSize, nodeMinSize } from '../shared/node-sizes.js';
 export interface CanvasValidationPair {
     aId: string;
     aTitle: string | null;
@@ -41,6 +21,12 @@ export interface CanvasSizeWarning {
     minWidth: number;
     minHeight: number;
 }
+export interface CanvasHiddenEdgeEndpoint {
+    edgeId: string;
+    nodeId: string;
+    nodeTitle: string | null;
+    dockPosition: 'left' | 'right';
+}
 export interface CanvasValidationResult {
     ok: boolean;
     collisions: CanvasValidationPair[];
@@ -51,6 +37,13 @@ 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: {
@@ -60,6 +53,7 @@ export interface CanvasValidationResult {
         containments: number;
         containmentViolations: number;
         missingEdgeEndpoints: number;
+        hiddenEdgeEndpoints: number;
         sizeWarnings: number;
     };
 }

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/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/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/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/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

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

package/docs/mcp.md

@@ -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
 

package/docs/node-types.md

@@ -14,7 +14,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `context` | Context cards, token usage, workspace grounding |
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
-| `file` | Live file viewer with auto-update on disk changes |
+| `file` | Live file viewer with auto-update on disk changes — also renders CSV/TSV as tables and PDFs inline |
 | `diff` | Unified diff viewer: per-file headers, hunk rows, +/− colored lines |
 | `mermaid` | Mermaid diagram rendered client-side from text (flowchart, sequence, state, …) |
 | `image` | Image viewer (file paths, data URIs, URLs) |
@@ -50,6 +50,20 @@ automatically via `fs.watch()`.
 canvas_node({ action: 'add', type: 'file', content: 'src/server/index.ts' })
 ```
 
+The same node type handles non-source files, so you never have to pick a
+different type by extension:
+
+- **`.csv` / `.tsv`** render as a real table (quoted fields, embedded newlines,
+  and escaped quotes are parsed properly) instead of raw delimited text. Very
+  long files render a bounded number of rows and say how many were omitted.
+- **`.pdf`** renders in an embedded viewer, served from
+  `GET /api/canvas/file-bytes?nodeId=…`. In hosts that block src-URL iframes
+  (Amp orb portals) the node offers an "Open PDF" link instead of a blank frame.
+- **Other binary files** show a placeholder with the name and size rather than
+  decoding bytes into mojibake.
+- **Text files over 2 MB** render truncated with a banner saying so, so a huge
+  log can never exhaust memory.
+
 ## Image nodes
 
 Image nodes display local paths, remote URLs, and data URIs. File-backed and
@@ -221,6 +235,36 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+Two kinds are **live AX control surfaces** rather than static documents, and are
+the only primitives created with AX enabled:
+
+- **`ax-board`** — give the agent tasks, watch their status change as it works,
+  send steering, and run a bounded task loop. Task rows read from live AX state,
+  so a status the agent sets anywhere shows up here.
+- **`ax-flow`** — the same controls drawn as a task flow with an explicit
+  loop-back rail, plus **Materialize to board**: the flow is laid out as real
+  canvas nodes joined by `flow` edges (and a dashed `references` loop edge),
+  each linked to a work item so the node's status chip tracks progress.
+  Re-materializing replaces the previous flow instead of duplicating it.
+
+A steer emitted from either surface is *queued* on the timeline — it reaches the
+agent on its next turn rather than waking it. Both stop their loop if the panel
+reloads; the work items are the durable record.
+
+### The flow on ordinary nodes
+
+You do not need the panel to drive a flow. A materialized step node carries
+`data.axStep`, and the canvas renders native controls on it — **Start / Done /
+Blocked** on every step, plus **Run loop / Stop** and a steer box on the first
+one. These are canvas chrome, not sandboxed content, so they work on any node
+type carrying the stamp.
+
+The native loop runs **server-side**, which is the one real difference from the
+panel: it advances when a step's work item is completed, survives a browser
+reload, and keeps going while the tab is closed. Same bounds either way — it only
+advances while running, stops at its run cap (hard limit 20), and Stop is
+persisted immediately. `blocked` or `cancelled` halts it without disarming.
+
 ```ts
 canvas_node({
   action: 'add',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
@@ -46,7 +46,7 @@
     "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
     "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
-    "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
+    "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",
     "test:e2e-cli": "bash scripts/e2e-cli-coverage.sh",