pmx-canvas 0.4.4 → 0.4.6

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

@@ -56,7 +56,8 @@ export declare function loadPendingAxSteeringFromDB(db: Database, options?: {
 /**
  * NEWEST undelivered steering first (report #57) for the compact AX context lead
  * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
- * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * the consumer's own steering and steering targeted at a different consumer in SQL
+ * so the LIMIT applies after both filters.
  * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
  * delivery queue uses for ordered processing.
  */
@@ -64,7 +65,7 @@ export declare function loadNewestPendingAxSteeringFromDB(db: Database, options?
     consumer?: string;
     limit?: number;
 }): PmxAxSteeringMessage[];
-/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own; target-scoped). */
 export declare function countPendingAxSteeringFromDB(db: Database, consumer?: string): number;
 export declare function loadAxTimelineSummaryFromDB(db: Database): PmxAxTimelineSummary;
 export declare function upsertAxHostCapabilityToDB(db: Database, cap: PmxAxHostCapability): void;

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

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

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

@@ -53,7 +53,7 @@ export interface CanvasSnapshotGcResult {
 }
 export interface CanvasNodeState {
     id: string;
-    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'image' | 'html' | 'group';
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
     position: {
         x: number;
         y: number;
@@ -154,6 +154,15 @@ declare class CanvasStateManager {
      * — e.g. the long-lived MCP subscription — may ignore the return value).
      */
     onChange(cb: (type: CanvasChangeType) => void): () => void;
+    private _workItemsChangedListener;
+    /**
+     * Register THE work-item change listener (single slot, last-write-wins).
+     * Fired after addWorkItem/updateWorkItem completes (including the node
+     * status mirror), so live views like the workboard can rebuild from the
+     * fresh work-item list.
+     */
+    setWorkItemsChangedListener(listener: (() => void) | null): void;
+    private notifyWorkItemsChanged;
     private notifyChange;
     private _mutationRecorder;
     private _suppressRecordingDepth;
@@ -280,6 +289,7 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem;
@@ -288,9 +298,17 @@ declare class CanvasStateManager {
         status?: PmxAxWorkItemStatus;
         detail?: string | null;
         nodeIds?: string[];
+        agentId?: string | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxWorkItem | null;
+    /**
+     * Mirror a work item's status onto every linked canvas node's `data.axWorkStatus`,
+     * through the standard node-update path (persistence + undo/redo, same as any other
+     * node data change). Nodes unlinked by an updateWorkItem nodeIds change have the
+     * mirrored status cleared.
+     */
+    private mirrorAxWorkStatusToNodes;
     getApprovalGates(): PmxAxApprovalGate[];
     requestApproval(input: {
         title: string;
@@ -376,6 +394,7 @@ declare class CanvasStateManager {
         data?: Record<string, unknown> | null;
     }, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
     }): PmxAxEvent;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
@@ -389,6 +408,8 @@ declare class CanvasStateManager {
     }): PmxAxEvidence;
     recordSteeringMessage(message: string, options?: {
         source?: PmxAxSource;
+        agentId?: string | null;
+        target?: string | null;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
     ingestActivity(input: {

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

@@ -1,4 +1,25 @@
-import type { CanvasLayout } from './canvas-state.js';
+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 interface CanvasValidationPair {
     aId: string;
     aTitle: string | null;
@@ -11,6 +32,15 @@ export interface CanvasContainmentIssue {
     childId: string;
     childTitle: string | null;
 }
+export interface CanvasSizeWarning {
+    id: string;
+    title: string | null;
+    type: CanvasNodeState['type'];
+    width: number;
+    height: number;
+    minWidth: number;
+    minHeight: number;
+}
 export interface CanvasValidationResult {
     ok: boolean;
     collisions: CanvasValidationPair[];
@@ -21,6 +51,8 @@ export interface CanvasValidationResult {
         from: string;
         to: string;
     }>;
+    /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
+    sizeWarnings: CanvasSizeWarning[];
     summary: {
         nodes: number;
         edges: number;
@@ -28,6 +60,7 @@ export interface CanvasValidationResult {
         containments: number;
         containmentViolations: number;
         missingEdgeEndpoints: number;
+        sizeWarnings: number;
     };
 }
 export declare function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResult;

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

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

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

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

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

@@ -11,9 +11,10 @@
 import { z } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { PmxAxSource } from '../../ax-state.js';
-export declare const AX_SOURCES: readonly ["agent", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
+export declare const AX_SOURCES: readonly ["agent", "amp", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
 export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
+    amp: "amp";
     agent: "agent";
     api: "api";
     browser: "browser";
@@ -24,6 +25,8 @@ export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
     sdk: "sdk";
     system: "system";
 }>>;
+/** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
+export declare const AX_AGENT_ID_SHAPE: z.ZodOptional<z.ZodString>;
 /** An absent or unrecognized source falls back to the per-surface default. */
 export declare function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource;
 export declare function normalizeAxNodeIds(value: unknown): string[];

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

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

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

@@ -11,5 +11,13 @@ export declare function setOperationEventEmitter(emitter: OperationEventEmitter
 export declare function isEmitSuppressed(): boolean;
 /** Run `fn` with all operation SSE emits suppressed; restores depth on finally. */
 export declare function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T>;
-export declare function executeOperation(name: string, rawInput: unknown): Promise<unknown>;
+export interface ExecuteOperationMeta {
+    /**
+     * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
+     * (a human dragging a node is not agent activity) and by canvas.batch for
+     * its inner dispatches (batch churn is exempt, matching the skill contract).
+     */
+    suppressAutoGhost?: boolean;
+}
+export declare function executeOperation(name: string, rawInput: unknown, meta?: ExecuteOperationMeta): Promise<unknown>;
 export {};

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

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

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

@@ -43,6 +43,12 @@ export interface PmxAxIntent {
     seq?: number;
     /** Source label of the surface that signalled the intent (mcp/api/sdk/...). */
     source?: string;
+    /**
+     * Server-synthesized ghost for an agent mutation that arrived WITHOUT an
+     * explicit canvas_intent signal (auto-ghost). Rendered visually lighter than
+     * a deliberate signal, and not vetoable — it settles immediately.
+     */
+    auto?: boolean;
     /** Epoch ms when the intent was first signalled. */
     createdAt: number;
     /** Epoch ms when the intent auto-dissolves if not settled/cleared first. */

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

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

package/docs/cli.md

@@ -201,6 +201,18 @@ pmx-canvas ax policy get
 pmx-canvas ax policy set --excluded-tools shell,write --mode concise
 ```
 
+## Environment smoke check
+
+```bash
+pmx-canvas smoke                 # one-command check of a running canvas
+pmx-canvas smoke --port 4750     # target a specific daemon
+```
+
+Verifies server health + workspace, CLI/server version skew, the MCP
+initialize handshake, a temporary node create/search/remove round-trip (the
+temp node is always removed, including on failure), and board validation.
+Prints a JSON report and exits 1 if any check fails.
+
 ## Copilot adapter
 
 Install the bundled GitHub Copilot extension adapter into a repo. The adapter

package/docs/environment.md

@@ -27,6 +27,7 @@ optional; defaults are listed.
 |---|---|---|
 | `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`, `volt`. |
 | `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_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

@@ -306,6 +306,18 @@ curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?settledNodeId=no
 curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?vetoed=true"
 ```
 
+## Live work board
+
+```bash
+# Materialize (or refresh) the one board node showing all AX work items by status.
+curl -X POST http://localhost:4313/api/canvas/workboard \
+  -H 'Content-Type: application/json' -d '{}'
+```
+
+The board is a `json-render` node tagged `data.workboard: true`. Repeat calls
+are idempotent (`created: false`) and the board refreshes itself whenever a
+work item changes — no polling needed.
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -38,7 +38,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
-| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
+| `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` · `workboard` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `remove` | `canvas_add_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |

package/docs/node-types.md

@@ -15,6 +15,8 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `ledger` | Execution ledger summary |
 | `trace` | Agent trace pills (tool calls, subagent activity) |
 | `file` | Live file viewer with auto-update on disk changes |
+| `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) |
 | `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
 | `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.4",
-  "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
+  "version": "0.4.6",
+  "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",
   "module": "./src/server/index.ts",
@@ -32,7 +32,7 @@
     "dev:demo": "bun run src/cli/index.ts --demo",
     "dev:portless": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313",
     "dev:portless:demo": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313 --demo",
-    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
+    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && bun build src/client/mermaid-entry.ts --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
     "build:json-render": "bash scripts/build-json-render.sh",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "bun run build:client && bun run build:json-render && bun run build:types",
@@ -68,6 +68,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
     "marked": "^15.0.0",
+    "mermaid": "^11.16.1",
     "preact": "^10.25.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",

package/skills/pmx-canvas/SKILL.md

@@ -44,9 +44,18 @@ Humans curate agent context by pinning nodes; agents read that curation through
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
    high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
    `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
+   Since 0.4.5, an agent mutation WITHOUT a signal still shows a server-synthesized **auto-ghost**
+   (rendered lighter — dimmer, dotted, no veto — and settled instantly). That is a visibility
+   floor, not a replacement: only an explicit signal gives the human a real pre-mutation veto
+   window, your reasoning (`reason`), and staged multi-step previews. Batch and browser-human
+   actions never auto-ghost.
 6. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
+7b. **Show the human.** After creating user-facing output, bring the camera to it: a single node
+   gets `canvas_view { action: "focus", id }` (pans by default), a small cluster gets
+   `canvas_view { action: "fit", nodeIds: [...] }` with exactly the new ids. See
+   **In-View Placement & Sizing** below — auto-placement is board-relative, not camera-relative.
 8. **Verify context pins.** Pin with `canvas_pin_nodes` or the browser's **Pin as context**, then
    read `canvas://pinned-context`.
 9. **Clean up temporary nodes.** Remove retry/test fixtures and restore the baseline snapshot when
@@ -62,6 +71,10 @@ pmx-canvas serve status
 ```
 
 Both surfaces report `workspace`. It must match the intended workspace root.
+For a full environment check in one command (health + workspace, CLI/server
+version skew, MCP initialize handshake, temp-node create/search/remove
+round-trip, board validation), run `pmx-canvas smoke` (0.4.6+) — JSON report,
+exit 1 on failure.
 
 - If `responsive: true` but `pidRunning: false`, treat the listener as potentially stale.
 - On mismatch, do not mutate. Start the intended workspace on an explicit free port:
@@ -92,14 +105,17 @@ Both surfaces report `workspace`. It must match the intended workspace root.
 | Persistent context cards | `context` via `canvas_node` |
 | Event/check stream | `ledger` or `trace` via `canvas_node` |
 | Local source with live updates | `file` via `canvas_node` |
+| Code review / unified diff (0.4.6+) | `diff` via `canvas_node` (content = diff text; link to its file node with a `references` edge) |
+| Flowchart / sequence / state diagram (0.4.6+) | `mermaid` via `canvas_node` (content = mermaid source; renders client-side, no hosted app) |
 | Image | `image` via `canvas_node` |
 | Cached URL content | `webpage` via `canvas_node` |
 | Structured UI | `json-render` via `canvas_render` |
 | Chart | `graph` via `canvas_render` |
+| Live work-item board (0.4.6+) | `canvas_render { action: "workboard" }` — one board node, auto-refreshes on work-item changes |
 | Generated communication surface | HTML primitive via `canvas_node` |
 | Self-contained HTML/JS | `html` via `canvas_node` |
 | Hosted interactive MCP app | `canvas_app { action: "open-mcp-app" }` |
-| Excalidraw diagram | `canvas_app { action: "diagram" }` |
+| Excalidraw diagram (interactive/human drawing) | `canvas_app { action: "diagram" }` — prefer `mermaid` for agent-authored diagrams |
 | Bundled React artifact | `canvas_app { action: "build-artifact" }` |
 
 Use the lightest tier that communicates the result. Do not build a web artifact when markdown,
@@ -159,6 +175,35 @@ v0.4.0 after their deprecated 0.3.x window.
 - Edge types: `flow`, `depends-on`, `relation`, `references`.
 - After manual or batch layout changes, run `canvas_query { action: "validate" }`.
 
+## In-View Placement & Sizing (required for user-facing nodes)
+
+Auto-placement (omitting `x`/`y`) is **board-relative, not camera-relative**: it places right of
+the last node or scans rows from the origin, ignoring where the human is looking. On a board with
+distant nodes, an auto-placed node lands off-camera.
+
+1. Omit `x`/`y` only on an empty or locally dense board. Otherwise place near the human's
+   attention: the pinned/focused neighborhood, or explicit coordinates beside the last
+   user-facing output (gap ≥ 24–48 px).
+2. After creating nodes the human should see, pan the camera (operating-sequence step 7b):
+   `focus` for one node, `fit` with exactly the new `nodeIds` for a cluster. Use `noPan`
+   (`focus --no-pan`) only when you must not steal the camera.
+3. Never fit the whole board to "show" new work — on a board with outliers that miniaturizes
+   everything. Always pass explicit `nodeIds` to `fit`.
+4. Never leave user-facing output at far coordinates without a focus/fit.
+
+**Size for content.** Omitting `width`/`height` gives readable per-type defaults — prefer them:
+markdown 640×420, status 360×200, file 520×360, diff 640×420, mermaid 640×460, html 720×640,
+graph 760×520, mcp-app 960×600, web-artifact 960×720. Since 0.4.6 the server clamps explicit creation sizes UP to per-type
+readability floors (e.g. markdown 360×180, graph/json-render/html 420×280, mcp-app 480×320) —
+a tiny probe size silently becomes the floor. `strictSize: true` is the only opt-out (a fixed
+scrolling frame you genuinely want small). `canvas_query { action: "validate" }` additionally
+reports any node below its floor as an advisory `sizeWarnings` entry — treat a non-empty list
+as layout work left to do.
+
+**Token hygiene.** For routine state checks use `canvas_ax_state { action: "get" }` WITHOUT
+`includeContext` — the full AX context payload is ~10× larger; request it only when you are
+actually consuming context.
+
 ## Context Pins
 
 Context pins are the primary human-to-agent bridge:
@@ -236,24 +281,25 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Hosted MCP-app/ext-app nodes such as Excalidraw require the in-canvas host bridge and are not
   standalone **Open as site** targets. URL-backed viewers and bundled web artifacts remain
   openable.
-- A hosted ext-app (Excalidraw) node that is already on the board when a **WebKit** host panel
-  loads (e.g. the GitHub Copilot app's embedded WKWebView) can render as a black tile — a host
-  compositor paint race on the nested iframe, **not** a broken node (the session is healthy and
-  `sessionStatus` is `ready`; it renders fine in Chrome, the Codex browser, and for nodes created
-  live after the panel hydrates). Under WebKit the canvas ATTEMPTS auto-recovery: after boot,
-  each present-at-load ext-app is remounted through a serialized, boot-aware queue (one app at a
-  time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
-  hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
-  Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
-  success is not observable from page JS, so retries are bounded). Since 0.4.1 the canvas also
-  fires a post-boot **repaint nudge** under WebKit (a 1px layout bounce that forces the
-  compositor to re-rasterize the frame — the cheap half of the proven enlarge-close unstick;
-  shows as `repaint-nudge` in the recovery trail). Keep the cautionary behavior anyway:
-  recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
-  the fullscreen overlay, which always paints), or open the workbench in a normal browser
-  (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
-  fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
-  what the recovery queue actually did in that panel.
+- A standalone html surface (`/api/canvas/surface/:id` opened as a site) is a VISUAL view: it
+  renders the same content and theme, but `window.PMX_AX` is not injected without the canvas
+  iframe's per-mount nonce, so AX buttons only work inside the in-canvas node (0.4.4 Codex note).
+  Do not tell a user a standalone tab's controls will steer the agent.
+- A hosted ext-app (Excalidraw) node in a **WebKit** host panel (e.g. the GitHub Copilot app's
+  embedded WKWebView) historically could render as a black tile — a host compositor paint race
+  on the nested iframe, **not** a broken node (the session is healthy, `sessionStatus` is
+  `ready`, and it renders fine in Chrome/Codex). Since 0.4.6 the canvas runs a **paint oracle +
+  recovery ladder** under WebKit: present-at-load ext-apps mount strictly one at a time (the
+  cold burst was the trigger), each frame answers a double-rAF **paint probe** after settle, and
+  on silence the ladder escalates — soft-expand cycle (the automatic analogue of the proven
+  enlarge+close) → serialized remount → an explicit "App surface failed to paint / Retry"
+  affordance. The connecting overlay stays up until paint is confirmed, so a black layer is
+  never presented as ready. The recovery trail
+  (`GET /api/canvas/debug/ext-app-recovery` / `window.__PMX_EXTAPP_LOG`) now records
+  `mount-slot`, `paint-ok`, `paint-fail`, `soft-expand-cycle`, and `recovery-exhausted` — when
+  diagnosing, trust `paint-ok`/`paint-fail`, and never assert health from `settled` alone. If a
+  tile still shows the Retry affordance, click Retry (fresh recovery budget) or expand-then-close;
+  attach the recovery trail when reporting.
 - Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
   while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
   0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its
@@ -272,11 +318,12 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   iframe) can block child iframes from loading ANY `src` URL, breaking every iframe-backed node
   with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
   same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
-  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and stamps
-  the page so the embedded client skips the (there-unreliable) probe, goes straight to `srcdoc`,
-  AND defaults to the polling transport (the portal proxy buffers SSE — waiting out the watchdog
-  could trip the boot modal); HTML surfaces also inline their theme stylesheet so they render
-  styled. External app
+  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and adapts
+  end to end: it binds the portal-assigned `$PORT` automatically (no port flag in the service
+  command), stamps the page so the embedded client skips the (there-unreliable) probe, goes
+  straight to `srcdoc`, AND defaults to the polling transport (the portal proxy buffers SSE —
+  waiting out the watchdog could trip the boot modal); HTML surfaces also inline their theme
+  stylesheet so they render styled. External app
   URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
   `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and