pmx-canvas 0.3.2 → 0.3.4

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

@@ -17,6 +17,8 @@ export declare function removePidFile(path: string): void;
 export interface HealthStatus {
     responsive: boolean;
     workspace: string | null;
+    /** The serving process's own pid, self-reported by /health (0.3.3+ servers). */
+    pid: number | null;
 }
 export declare function readHealthStatus(url: string): Promise<HealthStatus>;
 export declare function isHealthy(url: string): Promise<boolean>;
@@ -65,6 +67,21 @@ export declare function startDaemonMode(options: DaemonPaths & {
     waitMs: number;
     entry: string;
 }): Promise<void>;
+/**
+ * Resolve the pid story `serve status` reports. The AUTHORITATIVE pid is the
+ * serving process's self-reported /health pid: the pid file can go stale when
+ * something other than `serve --daemon` (re)spawned the server on this port —
+ * e.g. a host adapter respawn (0.3.2 report Finding P). Reporting the dead
+ * file pid as `pid` while `running` was true made agents read a contradiction
+ * (`running: true, pidRunning: false`); report the real listener instead and
+ * mark the file explicitly stale. Pre-0.3.3 servers don't self-report a pid —
+ * for those, fall back to the pid-file view unchanged.
+ */
+export declare function resolveDaemonPidView(pidFilePid: number | null, pidFilePidRunning: boolean, health: HealthStatus): {
+    pid: number | null;
+    pidRunning: boolean;
+    pidFileStale: boolean;
+};
 export declare function showServeStatus(options: DaemonPaths & {
     entry: string;
 }): Promise<void>;

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

@@ -38,6 +38,19 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
 export declare function resolveExtAppSandbox(value: unknown): string;
 export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string;
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export declare function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): 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/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/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

@@ -95,15 +95,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/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/RELEASE.md

@@ -124,6 +124,17 @@ If this is the first release from your machine, run `bunx npm login`
 once so Bun can reuse your npm credentials. CI does not need this —
 it uses `NPM_TOKEN` directly.
 
+## Sync consumer skill mirrors
+
+Every release since 0.3.0 has been retested against **stale** skill mirrors:
+consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
+skill under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
+repeatedly had to sync them mid-cycle before results were trustworthy. After
+publishing, update the installed package in the consumer workspace and re-sync
+its four mirrors from
+`<global npm root>/pmx-canvas/skills/pmx-canvas/` so the first test pass runs
+against the released skill, not the previous version's guidance.
+
 ## GitHub release
 
 After `npm publish` succeeds:

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/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` | agent CLI, MCP transport | Client-side default target port for CLI commands and the `--mcp` same-workspace lookup. Does not change what the server binds. |
+| `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 | Legacy JSON state path (back-compat; a `.db` value is treated as the DB path). |
+| `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/node-types.md

@@ -268,6 +268,11 @@ The scaffold includes `recharts`. Pass `--deps name,name2` for additional
 package dependencies. Failed or empty CLI bundles print `ok: false`, exit
 non-zero, and do not create a canvas node.
 
+Platform note: the artifact build pipeline runs through bundled bash scripts
+and requires a POSIX shell — it is not supported on native Windows yet.
+Already-built artifacts render fine on every platform; only the build step is
+POSIX-only.
+
 The matching agent skill is at
 [`skills/web-artifacts-builder/SKILL.md`](../skills/web-artifacts-builder/SKILL.md).
 

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -6,24 +6,33 @@
 
 Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision** (needs a maintainer call before code), or **small** (safe standalone change).
 
+## Decision analysis (2026-07-08, maintainer-approved)
+
+The remaining items were re-analyzed with pros/cons and tiered; the maintainer approved this ordering:
+
+- **Tier 1 (do):** CLI raw fetches → operation invoker **together with** the H3 parser/module split (same file, one project); H7 test coverage **as a prerequisite** for any client refactor; M2 AX-bridge dedup (first client task after H7); the M8 flake subset (mock the Excalidraw network tests, share `getAvailablePort`, Playwright `retries`/`forbidOnly`, `e2e-cli` into CI). *C1b done (2026-07-08):* all 60 raw `api()` calls migrated onto the invoker (9-agent verified mapping; `webartifact.build` gained `errorBodyAsResult`; batch failure prints the envelope + exits 1; the `api()` helper is deleted; two deliberate raw `fetch` sites remain — binary screenshot, SSE watch). *H3 module split done (2026-07-09):* `agent.ts` is a 227-line entry over `src/cli/shared.ts` (cycle-free core: registry, parser, transport) + 11 `src/cli/commands/*` domain modules, moved byte-identically; ax-parity reads the whole cli tree. **Parser sub-item reshaped:** `parseFlags`/`BOOL_FLAGS` is now single-sited in shared.ts; `index.ts` keeps its intentionally tiny fixed-flag launcher reader (different domain — server launch, not agent commands). The spec-driven per-command flag parser (`defineCommand`) remains the ideal but is a redesign of all 83 command surfaces — deferred to a future CLI UX change, not worth manufactured churn now.
+- **Tier 2 (reshaped):** the PmxCanvas→executeOperation collapse is **not** mechanical — `executeOperation` is async while 57/76 SDK methods are sync with typed returns, so a full collapse is a breaking SDK change. Verdict: migrate only the already-async/void methods now; decide the full async-SDK question as a **v0.4 breaking item** with the `canvas_snapshot` composite. Post-registry the sync methods are thin presentation over the shared cores (single logic site) — not logic duplication. H5 (sse-bridge factory) proceeds **after H7**. M6 gets the middle path: runtime per-action required-field errors, no `oneOf` schema break (many MCP hosts handle `oneOf` poorly). M1 gets the minimum four (minify, devtools→devDeps, lazy-load, replace the python mtime gate); the React-stack decision stays open.
+- **Tier 3 (cheap batch):** CI check that CLAUDE.md/AGENTS.md stay identical (instead of doc generation); document `PMX_DATA` + the `PMX_CANVAS_JSON_RENDER_*`/`PMX_MCP_APP_HOST_*` env families; publish.yml verifies the tag SHA passed test.yml; `@types/turndown` → devDependencies; L1 dead `ContextPinHud`; L4 one-shot migration marker; L6 timer-leak fixes.
+- **Tier 4 (closed as by-design / parked):** the six server-coupled routes (nothing to dedup — injection machinery for single-copy handlers isn't worth it); M3 ExtAppFrame refactor (the timing hacks are load-bearing WebKit fixes — document invariants, enter only when a feature forces it); M7 notification fan-out, L2, L3, `noUncheckedIndexedAccess` (parked); M10 packaging closed after the `@types` one-liner (`bin`→`src` under Bun and shipped `dist/` are both load-bearing by design).
+
 ## Phase 1 — finish what was started
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
 | Complete the registry migration | C1 | Fold the remaining hand-written routes in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. **Slice 1 done post-0.3.0:** the 7 `/api/ext-app/*` routes moved to `ops/ext-app.ts` (~290 lines out of `server.ts`, the 5 clone handlers — old M5 — collapsed to one parametrized definition; wire envelopes byte-identical, no new MCP tools). **Slice 2 done:** the 15 ax wire routes (8 GET lists + `ax/context` + `ax/surface-snapshot` + `pinned-context` + `code-graph` + `ax/activity` + `ax/interaction` + legacy `PATCH /api/canvas/ax`) moved to `ops/ax-read.ts` (~370 more lines out of `server.ts`); `open-external` stays hand-written (coupled to the live server port + system browser opener). **Slice 3 done:** theme GET/POST, canvas update, viewport, annotation POST, and node `:id/refresh` moved to the registry (`ops/canvas-wire.ts`, plus additions to `ops/viewport.ts`, `ops/annotation.ts`, `ops/nodes.ts`); the two dispatch gates unified into one `/api/` gate; `server.ts` is at ~2,980 lines (from 3,873 at the audit). **Remaining routes (~20)** are the deliberate poor fits (SSE, binary, HTML/static, file bodies) plus four server-coupled handlers: `prompt` + workbench `state`/`open`/`intent` (module-local `primaryWorkbench*` session state), `render` (Excalidraw URL-normalizer chain), `open-external` (live port + system browser). Those need state injection like the webview runner — a deliberate follow-up, not mechanical. After routes, the bigger halves remain: `PmxCanvas` (76 methods) onto `executeOperation`, and the CLI's raw fetches onto the invoker. | project (in progress) |
-| One HTTP envelope | M4 residual | Registry ops return bare bodies, legacy ext-app handlers `{ok:true,result}`, 404s plaintext. Unify (naturally falls out of C1). Also: surface persistence save failures via a `/health` degraded flag — `canvas-state.ts` has 63 catch→warn→continue sites. | project (with C1) |
+| One HTTP envelope | M4 residual | Registry ops return bare bodies, legacy ext-app handlers `{ok:true,result}`, 404s plaintext. **Reclassified v0.4-breaking (2026-08-03):** unifying changes response shapes that the Copilot adapter and the external test harnesses parse — it cannot ship in a patch. Bundle with the other v0.4 breaking items (`canvas_snapshot` composite, async-SDK decision). The `/health` degraded flag for the 63 catch→warn→continue persistence sites is additive and can ship earlier. | project (v0.4) |
 | `dist/` commit policy | C3 residual | **Decided + done post-0.3.0:** `dist/` stays committed; `test.yml` now has a `dist/types` staleness gate (rebuild + fail on drift). The `dist/canvas`/`dist/json-render` bundles are deliberately not byte-checked — bundler output varies across bun versions; their staleness story folds into M1. | done |
 | Skill-mirror validator | C2 residual | `validate:agent-skills` exits 0 when the (local-only, gitignored) trees are absent. Docs are honest about this now; decide whether to repoint, gate, or delete the check. | decision |
-| Generate CLAUDE.md/AGENTS.md from one source | M9 residual | The twins are byte-identical again but still hand-maintained; generate or symlink to prevent the next drift. | small |
+| Generate CLAUDE.md/AGENTS.md from one source | M9 residual | **Done (tier-3 batch):** CI fails on any CLAUDE.md/AGENTS.md byte drift (`test.yml` identity gate) — the cheap alternative to generation the decision analysis chose. Generation/symlinking stays unnecessary while the gate holds. | done |
 
 ## Phase 2 — make the safety net real
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
 | Lint/format tooling | H6 | **Done post-0.3.0:** Biome 2.5 adopted — `bun run lint` / `lint:fix`, wired into `release:check` (making RELEASE.md's "lints" claim true) and CI. First-run format sweep landed as its own mechanical commit; 7 lint errors hand-fixed (incl. a real conditional-hooks bug in `SelectionBar.tsx`). Deliberately disabled rules to revisit: a11y group, `useExhaustiveDependencies` (misfires on Preact signals), `noNonNullAssertion` (143 deliberate uses), `noArrayIndexKey` (13 sites). ~77 warnings (unused imports/vars, optional-chain) left as a burn-down list — warnings don't fail the gate. | done |
-| Client + server unit coverage | H7 | Zero component render tests (no DOM test lib in repo); untested big modules: `ax-state-manager.ts` (826 lines), `mcp-app-host.ts` (814), `canvas-schema.ts` (644), `shared/semantic-attention.ts` (600, in zero test files). Coverage is collected but gates nothing; tests aren't typechecked. Add `happy-dom` + `@testing-library/preact`, a tests tsconfig, and a coverage threshold. | project |
+| Client + server unit coverage | H7 | **Done post-0.3.3 (first tranche):** happy-dom + @testing-library/preact harness under `tests/client/` (own preload so DOM globals never leak into server suites); 20 client render tests incl. the SelectionBar conditional-hooks regression; `semantic-attention` (25 tests) and `canvas-schema` (21 tests incl. an M12 stale-tool-drift invariant) covered; tests are TYPECHECKED (`tsconfig.tests.json`, 270 latent errors fixed, wired into `typecheck` + CI); coverage now GATES via `scripts/check-coverage.ts` total floors (bun's bunfig threshold is per-file and its table form is silently ignored — documented). **Remaining (opportunistic):** dedicated tests for `ax-state-manager.ts` and `mcp-app-host.ts`, and growing the client suite alongside H5/M2 work. | first tranche done |
 | Daemon port/lock lifecycle | H4 | **Fixed post-0.3.0** (`src/cli/daemon.ts` + `tests/unit/cli-daemon.test.ts`). Note the original finding was partly wrong: the daemon child was already strict-port (`PmxCanvas.start` pins `allowPortFallback: false`), so fallback-blind polling could not occur. The real defects — fixed — were: the pre-check accepted any responsive `/health` as "already running" (even a foreign workspace's daemon), a TOCTOU double-spawn window, the pid recorded only after health passed (slow start → unkillable orphan), and no PID-recycling guard. The flaky `pmx-canvas-sdk.test.ts` port collision is NOT this — it's M8's copy-pasted `getAvailablePort()` racing. | done |
-| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs — they should be mocked or moved to a network-tagged tier. | project |
+| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs. **M8 subset done (2026-07-08):** those tests now run against the local stdio fixture via `PMX_CANVAS_EXCALIDRAW_MCP_COMMAND`; `getAvailablePort` is one shared helper; Playwright has `retries`/`forbidOnly` on CI; `e2e-cli` is a CI job. **Remaining (parked):** the `tests/unit/` monolith split and the `waitForPersistence` fixed-sleep sweep. | subset done |
 | `noUncheckedIndexedAccess` | L7 residual | Enable in tsconfig; will surface many index-access errors — treat as its own sweep. | small (noisy) |
 
 ## Phase 3 — client consolidation
@@ -31,7 +40,7 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 | Item | Source | What's open | Shape |
 |---|---|---|---|
 | One node factory | H5 | `sse-bridge.ts` (1,066 lines) keeps its own `DEFAULT_POSITIONS`/`makeNode` divergent from `canvas-store`; `responseToThreadMap` is not cleaned on SSE reconnect; server-side `syncEventToCanvasState` (~330 lines) mirrors it as an if/else chain with geometry defaults duplicated against `ensureDefaultDockedNodes`. Share one factory; treat `canvas-layout-update` as the single source of truth; table-drive the event sync. | project |
-| Shared AX iframe bridge | M2 | The ~33-line `onAxMessage` listener is copy-pasted in `HtmlNode.tsx`, `McpAppNode.tsx`, `ExtAppFrame.tsx`; `pmx-canvas-ax` protocol string spread across 9 sites. This is the sandboxed-surface trust boundary (prior near-miss: LRN-20260607-005). Extract `useAxSurfaceBridge` + a protocol-constants module. | project (security-adjacent) |
+| Shared AX iframe bridge | M2 | **Done (2026-08-03):** `useAxSurfaceBridge` (`src/client/nodes/use-ax-surface-bridge.ts`) single-sites the sandboxed-surface trust boundary previously copy-pasted in `HtmlNode.tsx`, `McpAppNode.tsx`, `ExtAppFrame.tsx`; `src/shared/ax-surface-protocol.ts` owns the wire tags (`pmx-canvas-ax`, `-ack`, `pmx-canvas-html-node`, the ext-app boot beacon) — client parsers import them, generated surface scripts (html-surface.ts, ext-app builders, json-render viewer) interpolate them byte-identically. Client render tests pin the validation gates + submit→ack round-trip (`tests/client/use-ax-surface-bridge.test.tsx`). | done |
 | `ExtAppFrame.tsx` timing hacks | M3 | 915 lines, 12 refs, 7 `setTimeout`s, 5 rAFs, WebKit remount slot counter, 1200 ms fallback bootstrap, two near-duplicate `buildHostContext` blocks. Extract `useExtAppBridge`; single `buildHostContext`. | project |
 | json-render stack decision | M1 | Preact + React 19 + recharts all runtime deps; 7 exact-pinned `@json-render/*` incl. 3 devtools packages shipped; `dist/json-render/index.js` 1.37 MB and `dist/canvas/index.js` 599 KB both unminified; build script shells to python3 with a stale-bundle fallback. Minimum: minify, move devtools to devDependencies, lazy-load the viewer, replace the python mtime gate. Bigger call: separate optional package if the React stack stays. | decision + project |
 | Client dead code / duplication | L1, L2, L3 | `ContextPinHud.tsx` unreferenced; three pure re-export shims; two parallel markdown-format stacks; `global.css` 3,746 lines with 11 `!important` vs 227 inline styles and unscaled z-indexes. | small (batchable) |
@@ -40,12 +49,21 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 
 | Item | Source | What's open |
 |---|---|---|
-| Per-action composite schemas | M6 | Composite tools advertise every field optional; per-action required fields fail only at runtime. Decide: `oneOf` schemas vs per-action requirement docs. (Now the only schema surface agents see.) |
+| Per-action composite schemas | M6 | **Done (2026-08-03, middle path per the decision analysis):** composite dispatch re-enforces each member op's required MCP fields at runtime and names the missing field (`requiredMcpFields` in `operations/mcp.ts`) — no `oneOf` schema break (many MCP hosts handle `oneOf` poorly). Advertised schemas stay all-optional by design. |
 | Packaging | M10 | `files` ships both `src/` and `dist/` (~double tarball, two import paths); `bin` points at raw `.ts` (undocumented Bun-only constraint); `@types/turndown` in runtime deps. |
-| Env var hygiene | M11 residual | `PMX_CANVAS_PORT` vs `PMX_WEB_CANVAS_PORT` applied inconsistently across entry points; `PMX_DATA` (15 uses) and the `PMX_CANVAS_JSON_RENDER_*` / `PMX_MCP_APP_HOST_*` families undocumented. |
-| `publish.yml` e2e gap | M11 residual | Publishing skips e2e with no verification that the tagged SHA passed `test.yml`. |
+| Env var hygiene | M11 residual | Docs side **done (tier-3 batch)**: `docs/environment.md` covers `PMX_DATA` + the `PMX_CANVAS_JSON_RENDER_*`/`PMX_MCP_APP_HOST_*` families. Still open: `PMX_CANVAS_PORT` vs `PMX_WEB_CANVAS_PORT` applied inconsistently across entry points (partly mitigated by the global `--port`/`--server-url` CLI flags). |
+| `publish.yml` e2e gap | M11 residual | **Done (tier-3 batch):** publish.yml verifies the tagged SHA has a successful `test.yml` run before publishing. |
 | MCP notification fan-out | M7 residual | Five `canvas://` resource URIs notify on every mutation regardless of type (`mcp/server.ts:95-99`). |
-| Legacy migration code on every boot | L4 | JSON→SQLite migration runs unconditionally (`canvas-state.ts:758,785`); gate behind a one-shot marker and retire. |
+| Legacy migration code on every boot | L4 | **Parked deliberately (2026-07-08):** the "unconditional" run is a couple of `existsSync` stats per boot — a one-shot marker adds state machinery to save nothing measurable and risks breaking upgrades from old layouts. Retire the migration code wholesale in a future major instead. |
 | Suppression/mutation plumbing | L5 | Two parallel suppression depth-counters; `onMutation` is a single-slot setter wired twice (last-write-wins). |
 | Module-global lifecycle leaks | L6 | ~20 module-level `let`s in `server.ts`; code-graph debounce timer survives `stopCanvasServer`; remote SSE watcher loop has no cancellation. |
 | June doc citations | L7 residual | `tech-debt-assessment-2026-06.md` cites gitignored `.learnings/` entries future maintainers can't read. |
+
+## Added post-0.3.3 (2026-08-03 sweep)
+
+| Item | What's open |
+|---|---|
+| Windows web-artifacts | The artifact build pipeline is bash-script-backed (POSIX-only); `tests/unit/web-artifacts.test.ts` self-skips on win32 and docs now state the boundary. Decide: port the build scripts to a cross-platform runner, or keep the documented "build on POSIX, render anywhere" stance. |
+| Composite parity no longer machine-checked | Since v0.3.0 removed the legacy standalones, the byte-identical composite-vs-legacy guarantee has no head-to-head test — regressions in `buildInput`/`formatResult` reuse surface only via output-shape assertions. Accepted at review; revisit if a composite drifts. |
+| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap" (0.3.3 report leaves it open), inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. Only scope on a failing report cycle. |
+| Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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",
@@ -40,18 +40,19 @@
     "pack:dry-run": "bun pm pack --dry-run",
     "release:check": "bun run build && bun run typecheck && bun run lint && bun run test:all",
     "release:smoke": "bash scripts/release-smoke.sh",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "test": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
     "test:unit": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage",
+    "test:client": "bun test --preload ./tests/client/setup.ts tests/client",
+    "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",
     "test:e2e-cli": "bash scripts/e2e-cli-coverage.sh",
     "test:web-canvas:headed": "bun run build && bash scripts/run-playwright.sh --headed",
     "test:e2e:headed": "bun run test:web-canvas:headed",
-    "test:all": "bun run test && bun run test:web-canvas",
+    "test:all": "bun run test && bun run test:client && bun run test:web-canvas",
     "test:install-browsers": "bun x playwright install chromium",
     "validate:agent-skills": "bash scripts/validate-agent-skill-mirrors.sh",
     "prepublishOnly": "bun run build && bun run typecheck"
@@ -68,7 +69,6 @@
     "@modelcontextprotocol/ext-apps": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
-    "@types/turndown": "^5.0.6",
     "marked": "^15.0.0",
     "preact": "^10.25.0",
     "react": "^19.2.3",
@@ -79,11 +79,14 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
+    "@happy-dom/global-registrator": "^20.10.6",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.1.18",
+    "@testing-library/preact": "^3.2.4",
     "@types/bun": "latest",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/turndown": "^5.0.6",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.7.0"

package/skills/pmx-canvas/SKILL.md

@@ -217,14 +217,17 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   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 auto-recovers: after boot, each
-  present-at-load ext-app is remounted through a **serialized, boot-aware queue** (one app at a
-  time, each waiting for the previous app's handshake + scene replay), with a watchdog retry for
-  iframes that never boot — so multi-app boards converge to painted tiles within a few seconds of
-  panel load. In rare cases a tile can still end up black (compositing success is not observable
-  from page JS, so retries are bounded); recovery is deterministic: **expand-then-close** 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.
+  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). Keep the cautionary behavior:
+  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.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look