pmx-canvas 0.4.6 → 0.4.8

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/ExtAppFrame.d.ts

@@ -18,6 +18,38 @@ interface ExtAppHostDimensionsTarget {
  * everywhere we can test (Chrome / Codex / Playwright).
  */
 export declare function isWebKitOnlyHost(userAgent: string): boolean;
+/**
+ * Finding N (0.4.7 report): the GitHub Copilot panel's WKWebView reports
+ * `document.visibilityState === 'hidden'` CONTINUOUSLY — the workbench document
+ * never transitions to 'visible' even with the panel open and on-screen. Two
+ * things break as a result: the `visibilitychange` re-arm below can never fire
+ * (there is no transition to listen for), and `paint-ok` becomes a false green —
+ * the app document happily answers the double-rAF paint probe while the
+ * compositor still shows black. The instrumented trail from that session carries
+ * `visibility: "hidden"` on essentially every recovery event.
+ *
+ * So: when the document CLAIMS hidden but the frame is demonstrably on-screen,
+ * do not trust the claim — spend one more recovery round as if visible. A host
+ * that ever reports 'visible' has a working signal and is left to the
+ * visibilitychange path, which keeps a genuinely backgrounded panel quiet.
+ */
+export declare function shouldAssumeVisibleRearm(options: {
+    userAgent: string;
+    visibilityState: string;
+    rect: {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    alreadyRearmed: boolean;
+}): boolean;
 export declare const WEBKIT_REMOUNT_SETTLE_MS = 1000;
 export interface WebkitRemountTask {
     /** Perform the remount. Return false if the node no longer needs it (skips the boot wait). */

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

@@ -22,6 +22,20 @@ export interface PersistedCanvasState {
 }
 export declare function openCanvasDb(dbPath: string): Database;
 export declare function checkpointCanvasDb(db: Database): void;
+/**
+ * Delete blob rows nothing references any more. Blobs are content-addressed and
+ * written with INSERT OR IGNORE, so editing a node's html supersedes its old blob
+ * and leaves it orphaned — without this, `canvas.db` (which is git-committable)
+ * would grow without bound once externalization applies to ordinary html nodes.
+ *
+ * References are collected by scanning the raw persisted JSON for sha256 fields
+ * rather than parsing every node. That deliberately OVER-approximates: a stray
+ * 64-hex string keeps a blob alive that could have been dropped, which wastes a
+ * little space. The opposite error would delete live content, so the scan is
+ * biased to the safe side on purpose. Snapshot rows are scanned too — a snapshot
+ * restore must still find its blobs.
+ */
+export declare function gcBlobsInDB(db: Database): number;
 export declare function finalizeCanvasDbForClose(db: Database): void;
 export declare function saveStateToDB(db: Database, state: PersistedCanvasState): void;
 /** Check if the DB has been populated with canvas state at least once. */

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/RELEASE.md

@@ -44,6 +44,25 @@ discovery with a `.esm.preflight` loader error (ERR-20260508-001).
 and exercises the CLI flows from
 [`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).
 
+**Bump the pinned version examples.** `Readme.md` pins an exact version in
+its install/orb-setup snippets *because* it tells readers to pin. Three
+releases in a row shipped pointing at the previous version — twice the
+surrounding prose described features that pin does not have, so a reader
+following it copy-pasted a broken setup.
+
+```bash
+grep -rn "pmx-canvas@0\." Readme.md docs/    # every hit must be the version you are about to ship
+```
+
+**If this release touches CI or the release workflows, review that as
+release content.** A changed gate gets its first real run *on this
+release*: `e2e-cli` once launched Playwright without installing the
+browser, the publish gate once queried `GITHUB_SHA` (the tag object, not
+the commit) so it would have blocked every annotated tag, and
+`test:coverage` once lacked `PMX_CANVAS_DISABLE_BROWSER_OPEN=1` so it
+failed *and* opened a real browser. Ask what happens on a fresh runner
+and on a tag event, not just on your machine.
+
 ## Versioning
 
 Semantic versioning, in 0.x semver honestly (see `docs/api-stability.md`).
@@ -87,6 +106,23 @@ Don't ship a release without a CHANGELOG entry. The GitHub release
 notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
 expands on the CHANGELOG with examples and migration notes.
 
+**Check the entries are under a NEW heading.** Feature commits land bullets
+at the top of the file, and three times in the 0.3.x–0.4.x cycles they were
+appended under the *already-published* section instead — so the release
+notes shipped empty while the previous release's published history claimed
+features it never had. Before tagging:
+
+```bash
+# every bullet added since the last tag must sit above the last released heading
+git diff v<PREVIOUS>..HEAD -- CHANGELOG.md | grep '^+' | head -40
+grep -n '^## \[' CHANGELOG.md | head -3
+```
+
+Same rule in reverse: never retro-edit a published section to describe new
+behavior (a theme's colour was changed in place once, so the released notes
+described a build that never shipped it). Correct it forward under the new
+version instead.
+
 **Release-blocker gate:** a breaking change without a `### Breaking`
 CHANGELOG entry blocks the release (`docs/api-stability.md`). Check the
 diff against the previous tag for removed/renamed public surface — MCP
@@ -95,6 +131,18 @@ anything broke and isn't named under `### Breaking`, add the entry first.
 
 ## Tag → publish
 
+**Immediately before tagging, re-read the Test CI conclusion — never assert it
+from memory.** v0.3.2 was tagged and published while its Test run had concluded
+*failure*: an interruption landed between the watch finishing and the tag step,
+and "CI was green" was recalled rather than checked. A `gh run watch` exiting 0
+is only evidence if you actually read its output.
+
+```bash
+gh run view <run-id> --json status,conclusion -q '.status + " / " + .conclusion'
+gh run view <run-id> --json jobs -q '.jobs[] | .name + ": " + .conclusion'
+# every job must read `success` — a matrix job added in THIS release has never run green before
+```
+
 The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))
 triggers on tags matching `v*`:
 

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