pmx-canvas 0.3.3 → 0.4.0

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

@@ -10,12 +10,17 @@
  * - Idempotent operations where possible
  * - --yes for destructive actions, --dry-run for preview
  */
-/**
- * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
- * `=` or space-separated value) and set the invocation's target override.
- * Returns the remaining args for command dispatch. Invalid values are a loud
- * `die` — never a silent fallback to the default port. `--server-url` wins
- * over `--port` when both are given.
- */
-export declare function extractGlobalTargetFlags(args: string[]): string[];
+import { extractGlobalTargetFlags } from './shared.js';
+import './commands/nodes.js';
+import './commands/edges.js';
+import './commands/groups.js';
+import './commands/view.js';
+import './commands/query.js';
+import './commands/pins.js';
+import './commands/history.js';
+import './commands/ax.js';
+import './commands/webview.js';
+import './commands/apps.js';
+import './commands/copilot.js';
+export { extractGlobalTargetFlags };
 export declare function runAgentCli(rawArgs: string[]): Promise<void>;

package/dist/types/cli/commands/apps.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/ax.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/copilot.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/edges.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/groups.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/history.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/nodes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/pins.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/query.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/view.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/cli/commands/webview.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,73 @@
+/**
+ * Shared core for the agent-native CLI.
+ *
+ * Holds the command registry (COMMANDS + cmd()), flag parsing, output/die,
+ * target resolution (getBaseUrl + global --port/--server-url handling), the
+ * operation invoker, and every helper used by two or more command domains.
+ * Command modules in src/cli/commands/ import from here only — this module
+ * must never import from agent.ts or any command module (cycle-free).
+ */
+declare function getBaseUrl(): string;
+/**
+ * Extract the global `--port <n>` / `--server-url <url>` flags (any position,
+ * `=` or space-separated value) and set the invocation's target override.
+ * Returns the remaining args for command dispatch. Invalid values are a loud
+ * `die` — never a silent fallback to the default port. `--server-url` wins
+ * over `--port` when both are given.
+ */
+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[]): {
+    positional: string[];
+    flags: Record<string, string | true>;
+};
+declare function requireFlag(flags: Record<string, string | true>, name: string, hint: string): string;
+declare function getStringFlag(flags: Record<string, string | true>, ...names: string[]): string | undefined;
+declare function optionalNumberFlag(flags: Record<string, string | true>, name: string, hint: string): number | undefined;
+/**
+ * AX `source` for a CLI-originated action. Defaults to `cli`, but honors an
+ * explicit `--source <label>` so an adapterless agent using the CLI as a fallback
+ * transport (e.g. `--source codex`) attributes its actions correctly — keeping
+ * loop-safety (a consumer never gets back its own steering) accurate (report #69).
+ */
+declare function resolveAxSource(flags: Record<string, string | true>): string;
+declare function optionalFiniteFlag(flags: Record<string, string | true>, name: string, hint: string): number | undefined;
+declare function optionalPositiveFiniteFlag(flags: Record<string, string | true>, name: string, hint: string): number | undefined;
+declare function optionalPositiveFiniteFlagWithAliases(flags: Record<string, string | true>, hint: string, ...names: string[]): number | undefined;
+declare function optionalBooleanFlag(flags: Record<string, string | true>, name: string, hint: string): boolean | undefined;
+declare function applyStrictSizeFlags(body: Record<string, unknown>, flags: Record<string, string | true>): void;
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+declare function parseJsonValue(raw: string, label: string, hint: string): unknown;
+declare function readOptionalTextInput(flags: Record<string, string | true>, options: {
+    fileFlags?: string[];
+    valueFlags?: string[];
+    allowStdin?: boolean;
+    label: string;
+    hint: string;
+}): Promise<string | undefined>;
+declare function applyCommonGeometryFlags(body: Record<string, unknown>, flags: Record<string, string | true>, hints: {
+    x: string;
+    y: string;
+    width: string;
+    height: string;
+}): void;
+declare function buildJsonRenderRequestBody(flags: Record<string, string | true>): Promise<Record<string, unknown>>;
+declare function buildHtmlPrimitiveRequestBody(flags: Record<string, string | true>): Promise<Record<string, unknown>>;
+declare function buildGraphRequestBody(flags: Record<string, string | true>, options?: {
+    requireData?: boolean;
+    allowStdin?: boolean;
+}): Promise<Record<string, unknown>>;
+declare function runWebArtifactBuildCommand(flags: Record<string, string | true>): Promise<void>;
+declare const COMMANDS: Record<string, {
+    run: (args: string[]) => Promise<void>;
+    help: string;
+    examples: string[];
+}>;
+declare const RESOURCE_COMMAND_ALIASES: Record<string, Record<string, string>>;
+declare const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>>;
+declare function cmd(name: string, help: string, examples: string[], run: (args: string[]) => Promise<void>): void;
+declare function showCommandHelp(name: string): void;
+declare function readStdin(): Promise<string>;
+export { COMMANDS, RESOURCE_COMMAND_ALIASES, RESOURCE_SUBCOMMAND_HINTS, applyCommonGeometryFlags, applyStrictSizeFlags, buildGraphRequestBody, buildHtmlPrimitiveRequestBody, buildJsonRenderRequestBody, cmd, die, getBaseUrl, getStringFlag, invokeOperation, isRecord, optionalBooleanFlag, optionalFiniteFlag, optionalNumberFlag, optionalPositiveFiniteFlag, optionalPositiveFiniteFlagWithAliases, output, parseFlags, parseJsonValue, readOptionalTextInput, readStdin, requireFlag, resolveAxSource, runWebArtifactBuildCommand, showCommandHelp, };

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

@@ -1 +1 @@
-export declare function ExpandedNodeOverlay(): import("preact/src").JSX.Element | null;
+export declare function ExpandedNodeOverlay(): import("preact/jsx-runtime").JSX.Element | null;

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

@@ -1 +1 @@
-export {};
+import './uuid-polyfill';

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

@@ -51,6 +51,16 @@ export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: strin
  * the host also checks event.source against the live iframe.
  */
 export declare function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string;
+/**
+ * Base styles injected into every ext-app document (Finding Q, 0.3.4 report):
+ * apps aspect-fit their drawn surface to the frame width, and on narrow/tall
+ * tiles the leftover region shows the app document's own body background —
+ * pure black for the hosted Excalidraw bundle, in every engine. Making the
+ * app document transparent lets the host iframe's theme background
+ * (var(--c-panel)) show through the letterbox instead. Background only — app
+ * content, its drawn scene, and its own foreground styling are untouched.
+ */
+export declare function buildExtAppSurfaceBaseStyles(): string;
 export declare function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string;
 export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
     width: number;

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

@@ -6,4 +6,4 @@ export declare function HtmlNode({ node, expanded, presentation, presentationExi
     presentation?: boolean;
     presentationExitToken?: string;
     autoFocus?: boolean;
-}): import("preact/src").JSX.Element;
+}): import("preact/jsx-runtime").JSX.Element;

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

@@ -3,4 +3,4 @@ export declare function isSameOriginFrameDocumentUrl(url: string, origin?: strin
 export declare function McpAppNode({ node, expanded }: {
     node: CanvasNodeState;
     expanded?: boolean;
-}): import("preact/src").JSX.Element;
+}): import("preact/jsx-runtime").JSX.Element;

package/dist/types/client/nodes/use-ax-surface-bridge.d.ts

@@ -0,0 +1,20 @@
+import type { RefObject } from 'preact';
+/** Sandboxed surfaces that emit through this bridge (clamped to their own node server-side). */
+export type AxSurfaceBridgeSurface = 'json-render' | 'html-node' | 'mcp-app';
+/**
+ * The sandboxed-surface AX trust boundary, single-sited (plan-009 M2; the
+ * listener was copy-pasted across HtmlNode, McpAppNode, and ExtAppFrame — a
+ * prior near-miss lived exactly in that duplication). Receives a
+ * `window.PMX_AX.emit(...)` message from THIS node's iframe, validates the
+ * event source against the live contentWindow plus the per-mount nonce token
+ * and node id, submits the interaction through the capability-gated endpoint
+ * (the server re-validates capabilities and clamps sandboxed surfaces to their
+ * own node), and acks the result back so the surface can self-confirm (#55).
+ */
+export declare function useAxSurfaceBridge(options: {
+    enabled: boolean;
+    token: string;
+    nodeId: string;
+    sourceSurface: AxSurfaceBridgeSurface;
+    iframeRef: RefObject<HTMLIFrameElement>;
+}): void;

package/dist/types/client/state/node-factory.d.ts

@@ -0,0 +1,29 @@
+import type { CanvasNodeState } from '../types';
+export declare const DEFAULT_POSITIONS: Record<CanvasNodeState['type'], {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}> & Record<'prompt' | 'response', {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+/**
+ * Build a canvas node with the shared client defaults. `position`/`size`
+ * default to the type's DEFAULT_POSITIONS entry; callers that compute
+ * placement (auto-placement, event-supplied geometry) pass explicit values.
+ * Status nodes sit at zIndex 0 (background chrome), everything else at 1.
+ */
+export declare function makeNodeState(id: string, type: CanvasNodeState['type'], data: Record<string, unknown>, options?: {
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    dockPosition?: 'left' | 'right' | null;
+}): CanvasNodeState;

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

@@ -35,7 +35,6 @@ export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapsh
 export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
 export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
 export declare function readBlobFromDB(db: Database, sha256: string): string | null;
-export declare function hasBlobInDB(db: Database, sha256: string): boolean;
 export interface AxTimelineQuery {
     limit?: number;
     sessionId?: string;

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

@@ -128,6 +128,8 @@ export declare function validateCanvasNodePatch(patch: {
 export declare function mergeTraceNodeDataFields(base: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown>;
 export declare function hasTraceNodeDataFields(input: Record<string, unknown>): boolean;
 export declare function scheduleCodeGraphRecompute(onComplete?: () => void): void;
+/** Clear a pending recompute so the timer cannot outlive its server (start/stop cycles, tests). */
+export declare function cancelCodeGraphRecompute(): void;
 /**
  * Resolve an html-node `html` field that may be a path to a local .html/.htm file.
  *

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

@@ -7,7 +7,9 @@
  *
  * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
  * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
- * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
+ * Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+ * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
+ * the one-shot boot migration into SQLite was retired.
  */
 import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
@@ -155,7 +157,7 @@ declare class CanvasStateManager {
     private notifyChange;
     private _mutationRecorder;
     private _suppressRecordingDepth;
-    /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
+    /** Register THE mutation recorder (single slot, last-write-wins — see note above). */
     onMutation(cb: (info: MutationRecordInfo) => void): void;
     /** Run a function with mutation recording suppressed (for undo/redo replay and computed edges). */
     withSuppressedRecording(fn: () => void): void;
@@ -171,7 +173,6 @@ declare class CanvasStateManager {
     private translateGroupChildren;
     private recomputeParentGroupBounds;
     private compactGroupChildren;
-    private _stateFilePath;
     private _db;
     private _saveTimer;
     /** Workspace root backing persistence and workspace-relative path resolution. */
@@ -188,20 +189,9 @@ declare class CanvasStateManager {
     isBlobReference(value: unknown): value is PersistedBlobRef;
     resolveBlobReference(value: unknown): unknown;
     private externalizePersistedStateBlobs;
-    /**
-     * One-time migration: rename files from the pre-consolidation layout
-     * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
-     * No-op when the new layout already exists.
-     */
-    private migrateLegacyLayout;
-    /**
-     * One-time migration: import state.json + snapshot JSON files + blob files
-     * into the SQLite database. Renames originals to `.bak`.
-     */
-    private migrateJsonToSqlite;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
+    /** Load canvas state from SQLite. Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
     /**
      * Whether this workspace's canvas DB already holds saved state. Used to gate
@@ -215,6 +205,15 @@ declare class CanvasStateManager {
     flushToDisk(): void;
     /** Write current state to SQLite immediately. */
     private saveToDisk;
+    private _lastPersistenceError;
+    /** Health view of state persistence: ok until a save fails, ok again after the next success. */
+    get persistenceHealth(): {
+        ok: boolean;
+        lastError: {
+            message: string;
+            at: string;
+        } | null;
+    };
     /** Close the SQLite database cleanly. Call on server shutdown. */
     close(): void;
     private get snapshotsDir();

package/dist/types/server/diagram-presets.d.ts

@@ -7,6 +7,14 @@ export declare const EXCALIDRAW_SAVE_CHECKPOINT_TOOL = "save_checkpoint";
 export declare const EXCALIDRAW_READ_CHECKPOINT_TOOL = "read_checkpoint";
 export declare const DEFAULT_EXCALIDRAW_ELEMENTS: ReadonlyArray<Record<string, unknown>>;
 export declare const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig;
+/**
+ * The diagram preset targets the hosted Excalidraw MCP server. Tests set
+ * PMX_CANVAS_EXCALIDRAW_MCP_COMMAND (a stdio command line, e.g.
+ * "bun run tests/fixtures/mcp-app-fixture.ts") so the unit suite never does a
+ * real network round-trip — the hosted dependency made diagram tests time out
+ * under parallel load (plan-009 M8).
+ */
+export declare function resolveExcalidrawTransport(): ExternalMcpTransportConfig;
 export interface DiagramPresetOpenInput {
     elements: unknown;
     nodeId?: string;

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

@@ -16,27 +16,12 @@
  * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
  * through its composite (or `canvas_batch`).
  *
- * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
- * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
- * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
- * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
- * deprecated (description-prefixed) per docs/api-stability.md's
- * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
- * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
- * diagram / build-artifact. Wave 5 folded the last three legacy tools
- * deprecate-only — NO per-action input-injection mechanism was needed:
- * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
- * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
- * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
- * returns a binary image payload the composite/registry JSON wire shape does not
- * model.)
- *
- * Not shipped here: the `canvas_snapshot` composite (plan-006 #7). Its target
- * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
- * `snapshot.save`), so it cannot be added additively without a name clash, and
- * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.4, in the same change that removes the 6
- * kept-but-deprecated legacy snapshot tools and frees the name.
+ * v0.4.0 completed the fold: the `canvas_snapshot` composite shipped (its name
+ * was held by the legacy save-snapshot standalone through v0.3.x, which — with
+ * the other 5 snapshot standalones — was deprecated in 0.3.0 and removed here
+ * per docs/api-stability.md's deprecate-one-minor-before-removal rule).
+ * `canvas_screenshot` stays standalone — it returns a binary image payload the
+ * composite/registry JSON wire shape does not model.
  *
  * This module must never import server.ts or index.ts.
  */
@@ -95,15 +80,6 @@ export interface CompositeToolDefinition {
         kind: string;
         action: string;
     }) => string | undefined;
-    /**
-     * Two-discriminator extension: human-readable `(kind, action)` for a member op
-     * (the inverse of `resolveOp`), used to build that op's deprecation note. The
-     * `kind` field-collision is resolved here (see `gateFieldRemap`).
-     */
-    describeOp?: (opName: string) => {
-        kind: string;
-        action: string;
-    } | undefined;
     /**
      * Field-name remap applied to the composite's advertised schema and undone at
      * dispatch. Resolves a collision between a discriminator name and a member-op

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

@@ -24,6 +24,7 @@
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
  * - 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)
  * - GET  /api/workbench/state    -> workbench state snapshot
  * - POST /api/workbench/intent   -> workbench intents
  * - GET  /api/workbench/webview  -> Bun.WebView automation status

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

@@ -0,0 +1,18 @@
+/**
+ * Wire-protocol source tags for sandboxed-surface ↔ canvas postMessage traffic
+ * (plan-009 M2): one module owns the strings that used to be spread across the
+ * client node components, the server-side surface script generators, the
+ * ext-app script builders, and the json-render viewer. These are the trust
+ * boundary between opaque-origin iframes and the canvas — a typo'd tag fails
+ * SILENTLY (the listener just ignores the message), so single-siting them is a
+ * correctness measure, not cosmetics. The values are a persisted wire contract
+ * with already-generated surface documents: never change them.
+ */
+/** A sandboxed surface emitting an AX interaction to the parent canvas. */
+export declare const AX_SURFACE_EMIT_SOURCE = "pmx-canvas-ax";
+/** The parent canvas acking an AX interaction back to the emitting surface (#55). */
+export declare const AX_SURFACE_ACK_SOURCE = "pmx-canvas-ax-ack";
+/** Parent→surface pushes (theme updates, live AX state) into html/viewer iframes. */
+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";

package/docs/bun-webview-integration.md

@@ -173,6 +173,11 @@ PMX Canvas follows Bun's current stable backend reality.
 - required on Linux and Windows
 - also supported on macOS
 - preferred when backend consistency or future CDP-based tooling matters
+- can trigger a native "Allow remote debugging?" dialog on first start in some
+  hosts — approve it promptly or the start times out with `ok:false`. Raise
+  `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` (e.g. `30000`) when the prompt or a slow
+  Chrome launch is expected, and retry once before classifying a timeout as a
+  failure.
 
 ### Current default behavior
 

package/docs/cli.md

@@ -51,6 +51,11 @@ pmx-canvas node add --help --type webpage --json
 pmx-canvas external-app add --kind excalidraw --title "Diagram"
 
 pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
+
+# Updates return a compact { ok, id, position, size, updatedFields } envelope;
+# pass --full for the complete node payload (ext-app payloads can be huge).
+pmx-canvas node update <node-id> --width 840 --height 620
+pmx-canvas node update <node-id> --title "Renamed" --full
 ```
 
 `--from-search` / `--to-search` must each resolve to exactly one node — broad

package/docs/environment.md

@@ -0,0 +1,48 @@
+# Environment variables
+
+Every `PMX_*` variable the server, CLI, MCP transport, and build read. All are
+optional; defaults are listed.
+
+## Ports and workspace targeting
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PMX_WEB_CANVAS_PORT` | server, CLI `serve` | Preferred server port (default `4313`). CLI `--port` wins over it. |
+| `PMX_CANVAS_PORT` | all entry points | Client-side target port for CLI commands and the `--mcp` lookup; as of 0.4.0 the server also falls back to it when `--port`/`PMX_WEB_CANVAS_PORT` are unset, so one var can drive the whole stack. |
+| `PMX_CANVAS_URL` | agent CLI, MCP transport | Full base URL target (wins over `PMX_CANVAS_PORT`). |
+| `PMX_CANVAS_WORKSPACE_ROOT` | server, MCP transport | Pins the workspace root for daemon binds and the MCP same-workspace lookup, overriding the launch cwd. Set it when a host spawns `--mcp` from an incidental dir. |
+| `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT` | MCP transport | `1` forces a separate canvas instead of attaching to a different-workspace daemon on the preferred port. |
+
+## Persistence
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PMX_CANVAS_DB_PATH` | server | Overrides the SQLite path (default `.pmx-canvas/canvas.db`). |
+| `PMX_CANVAS_STATE_FILE` | server | `.db`-path alias only as of 0.4.0 (non-`.db` values are ignored with a boot warning; the pre-0.2 JSON import was removed). |
+| `PMX_CANVAS_BLOB_THRESHOLD_BYTES` | server | Node payloads above this many JSON bytes are stored as blobs (default `2048`). |
+
+## Server behavior
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`. |
+| `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
+| `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. |
+
+## MCP app host (security-relevant)
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PMX_MCP_APP_HOST_MODE` | server | Gates which hosted MCP app servers may be opened. |
+| `PMX_MCP_APP_HOST_ALLOWLIST` | server | Additional allowed MCP app server origins. |
+| `PMX_MCP_APP_HOST_STATE_FILE` | server | Overrides the app-host session state file. |
+
+## Build and diagnostics
+
+| Variable | Read by | Effect |
+|---|---|---|
+| `PMX_CANVAS_JSON_RENDER_DEVTOOLS` | server | `1` (plus `?devtools=1` on the viewer URL) enables the json-render devtools overlay. |
+| `PMX_CANVAS_FORCE_JSON_RENDER_REBUILD` | json-render build | `1` forces the viewer bundle rebuild even when outputs exist. |
+| `PMX_CANVAS_EXCALIDRAW_MCP_COMMAND` | server (tests) | Stdio command replacing the hosted Excalidraw MCP server for the diagram preset, e.g. `bun run tests/fixtures/mcp-app-fixture.ts`. |
+| `PMX_SESSION_LOG` / `PMX_TEST_LOG` | server | Path for MCP-app host session diagnostics logging (session wins over test). |

package/docs/http-api.md

@@ -5,7 +5,9 @@ any language. Default base URL: `http://localhost:4313`.
 
 A non-empty request body that is not valid JSON returns
 `400 { "ok": false, "error": "Malformed JSON body." }` on every route; empty
-bodies are treated as an empty request.
+bodies are treated as an empty request. As of 0.4.0 every error response is a
+JSON envelope of that same shape (`{ ok: false, error }`, status unchanged) —
+no plain-text errors remain.
 
 ## Canvas state
 
@@ -321,6 +323,28 @@ curl -N http://localhost:4313/api/workbench/events
 The browser, the CLI `watch` command, and the MCP resource notifications
 all consume this stream. Auto-reconnect with exponential backoff.
 
+## Polling transport (proxy-safe)
+
+Some proxies (e.g. the Amp orb portal) buffer streaming responses and only
+flush them on close, so the SSE stream above delivers nothing. The polling
+transport returns the same events as short-lived JSON responses that pass
+through any proxy:
+
+```bash
+# No `since`: a full connect snapshot (same events an SSE connect sends) + the
+# current cursor. With `since=<seq>`: only events after that cursor.
+curl "http://localhost:4313/api/workbench/poll"
+curl "http://localhost:4313/api/workbench/poll?since=42"
+```
+
+Responses are `{ ok, transport: "poll", snapshot, seq, events }` — poll again
+with `since=<seq>` every couple of seconds. A `since` from a previous server
+run or one that fell off the bounded event ring recovers with a fresh
+snapshot. The browser client uses this automatically: if the SSE stream
+produces no event within 3 seconds of connecting, it switches to polling.
+Force a transport with `/workbench?transport=poll` (or `transport=sse` to
+disable the fallback).
+
 ## Time travel
 
 ```bash

package/docs/mcp.md

@@ -1,19 +1,17 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **27 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **22 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
-> **Consolidation completed in v0.3.0 (plan-006/008).** The MCP surface shrank
-> from 84 tools to 27: 15 action-discriminated **composites** (recommended —
-> see below) plus 12 standalone tools. The 57 legacy single-purpose tools that
-> the composites replaced were removed in v0.3.0 per
-> [`api-stability.md`](api-stability.md); their descriptions carried
-> `Deprecated:` prefixes for one minor before removal. The 6 snapshot tools
-> remain registered as deprecated standalones — they fold into a
-> `canvas_snapshot` composite in v0.4 (see [Standalone tools](#standalone-tools)
-> below). **Prefer the composites.**
+> **Consolidation complete (plan-006/008).** The MCP surface shrank from 84
+> tools to 22: 16 action-discriminated **composites** (recommended — see
+> below) plus 6 standalone tools. The 57 legacy single-purpose tools the
+> composites replaced were removed in v0.3.0, and v0.4.0 finished the fold by
+> shipping the `canvas_snapshot` composite and removing the 6 deprecated
+> snapshot standalones — each step per [`api-stability.md`](api-stability.md)'s
+> deprecate-one-minor-before-removal rule. **Prefer the composites.**
 
 ## Connect
 
@@ -54,6 +52,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` |
 | `canvas_ax_delivery` | `claim` · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
+| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
 ### `canvas_intent` — Ghost Cursor of Intent
 
@@ -89,20 +88,16 @@ tools). `canvas_screenshot` also stays standalone — it returns a binary image
 the composite/registry JSON wire shape does not model. (Wave 5 folded
 `canvas_refresh_webpage_node` → `canvas_node { action: "update", refresh: true }` after
 fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
-`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The 6
-snapshot tools are the one deferred fold: a `canvas_snapshot` composite is
-planned for v0.4 (the name collides with the legacy `canvas_snapshot` save
-tool, and [`api-stability.md`](api-stability.md) requires deprecating a tool
-for one minor before removing it) — they stay registered as deprecated
-standalones until then.
+`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The snapshot
+fold completed in v0.4.0: `canvas_snapshot { action: "save" | "list" | "restore" |
+"delete" | "gc" | "diff" }` replaced the 6 deprecated snapshot standalones.
 
 ## Standalone tools
 
-12 tools that intentionally stay outside the composites — either because
-folding them would hurt (distinct callers, binary payloads, trust-boundary or
-execution-intent semantics), or because they're mid-deprecation pending a
-v0.4 composite. See [Migration reference](#migration-reference) below for the
-57 tools these composites replaced.
+6 tools that intentionally stay outside the composites — folding them would
+hurt (distinct callers, binary payloads, trust-boundary or execution-intent
+semantics). See [Migration reference](#migration-reference) below for the
+legacy tools the composites replaced.
 
 | Tool | Description |
 |------|-------------|
@@ -112,12 +107,6 @@ v0.4 composite. See [Migration reference](#migration-reference) below for the
 | `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
 | `canvas_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |
 | `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
-| `canvas_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Save current canvas as a named snapshot |
-| `canvas_list_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). List saved snapshots, bounded to the newest 20 by default |
-| `canvas_restore` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Restore canvas from a saved snapshot |
-| `canvas_delete_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete a saved snapshot |
-| `canvas_gc_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete old snapshots while keeping the newest N |
-| `canvas_diff` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Compare current canvas vs a saved snapshot |
 
 `canvas_node { action: "add", type: "html" }` accepts optional `summary`, `agentSummary`,
 `embeddedNodeIds`, and `embeddedUrls`. PMX also derives a bounded text summary from visible
@@ -125,7 +114,9 @@ HTML, so rich HTML nodes stay searchable and readable in pinned/spatial context.
 
 ## Migration reference
 
-The 57 legacy single-purpose tools below were removed in v0.3.0. Each row is
+The 57 legacy single-purpose tools below were removed in v0.3.0, and v0.4.0
+additionally removed the 6 deprecated snapshot standalones (see the
+`canvas_snapshot` composite row above for their replacements). Each row is
 the composite call that replaces it — kept as a lookup table for anyone
 migrating an older integration.
 
@@ -304,5 +295,5 @@ CLI and MCP are kept aligned for the main canvas operations: node and edge
 creation, graph/json-render/html/html-primitive nodes, web artifacts, external apps, groups,
 batch builds, layout validation, snapshots, search, focus, pins, undo/redo,
 semantic watch streams, WebView automation, and daemon/server control where
-it applies. A few agent-native capabilities — resource subscriptions and
-`canvas_diff` — remain MCP-only.
+it applies. A few agent-native capabilities — such as resource
+subscriptions — remain MCP-only.