pmx-canvas 0.1.35 → 0.2.0

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

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const snapshotOperations: Operation[];

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

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const validateOperations: Operation[];

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

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const viewportOperations: Operation[];

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

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const webviewOperations: Operation[];

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

@@ -0,0 +1,15 @@
+import { type Operation } from './types.js';
+export declare function registerOperation(op: Operation): void;
+export declare function getOperation(name: string): Operation;
+export declare function listOperations(): Operation[];
+type OperationEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare function setOperationEventEmitter(emitter: OperationEventEmitter | null): void;
+/** True while operation SSE emits are being suppressed (inside a meta-op such as
+ * canvas.batch). Ops whose effect depends on a live SSE emit firing — e.g.
+ * mcpapp.open, whose canvas node is created as a side-effect of `ext-app-open` —
+ * use this to reject loudly instead of silently no-op'ing in a suppressed run. */
+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 {};

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

@@ -0,0 +1,116 @@
+/**
+ * Operation registry core types (plan-005).
+ *
+ * One `Operation` describes a canvas operation once: input schema, the single
+ * handler implementation, and how the operation surfaces over HTTP and MCP.
+ * `defineOperation` wraps the typed pieces into a transport-agnostic record.
+ *
+ * Modules in `operations/` must never import `../server.ts` or `../index.ts`
+ * (the SSE emitter is injected via `setOperationEventEmitter`; the SDK imports
+ * the operation cores directly).
+ */
+import type { ZodRawShape } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export type OperationErrorStatus = 400 | 404 | 409;
+/** Operation failure that maps to an HTTP status + `{ ok:false, error }` body and MCP `isError`. */
+export declare class OperationError extends Error {
+    readonly status: OperationErrorStatus;
+    /** Extra fields merged into the HTTP `{ ok:false, error }` body (e.g. the legacy
+     *  webview-failure `webview` status snapshot). Omit for the plain envelope. */
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, status?: OperationErrorStatus, details?: Record<string, unknown>);
+}
+export interface OperationContext {
+    /** Emit a workbench SSE event (e.g. extra `canvas-layout-update` frames, focus, viewport). */
+    emit(event: string, payload?: Record<string, unknown>): void;
+}
+export interface OperationHttpRoute {
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    /** EXACT legacy path; `:param` segments capture path parameters. */
+    path: string;
+    /**
+     * Per-op input reader. The default merges query params, a JSON object body
+     * (arrays/primitives are preserved by the shared reader — a per-op reader
+     * decides how to use them), and path params (params win).
+     */
+    readInput?: (req: Request, params: Record<string, string>, url: URL) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /** HTTP status for a successful result. Defaults to 200. */
+    status?: (result: unknown) => number;
+    /**
+     * Return parsed non-2xx JSON bodies to operation callers instead of throwing.
+     * Use only for operations whose MCP contract formats structured failure bodies
+     * itself (for example canvas.batch partial failures).
+     */
+    errorBodyAsResult?: boolean;
+}
+/** Host capabilities available to MCP result formatters. */
+export interface OperationMcpToolHost {
+    getPinnedNodeIds(): Promise<string[]>;
+    /**
+     * Invoke another registered operation over the host's transport (local or
+     * HTTP) — structural subset of OperationInvoker to avoid an import cycle.
+     * Used by formatters that need a follow-up read (undo/redo history flags,
+     * restore summary).
+     */
+    invoker(): {
+        invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+    };
+}
+export interface OperationMcpTool {
+    /** Frozen legacy tool name (see tests/unit/mcp-tool-freeze.test.ts). */
+    toolName: string;
+    description: string;
+    /**
+     * MCP-only presentation flags and typed overrides merged over the operation
+     * input shape when advertising the tool schema (e.g. `full` / `verbose`).
+     */
+    extraShape?: ZodRawShape;
+    /** Map raw MCP args onto operation input. May throw OperationError. */
+    buildInput?: (input: Record<string, unknown>) => Record<string, unknown>;
+    /** Format the wire-shaped operation result into a tool result. */
+    formatResult?: (result: unknown, input: Record<string, unknown>, host: OperationMcpToolHost) => Promise<CallToolResult> | CallToolResult;
+}
+/** Registered, transport-agnostic operation record. */
+export interface Operation {
+    name: string;
+    /** true → the registry emits one `canvas-layout-update` after success. */
+    mutates: boolean;
+    /** Raw zod shape (for MCP tool schemas). */
+    inputShape: ZodRawShape;
+    http: OperationHttpRoute | null;
+    mcp: OperationMcpTool | null;
+    /** Validate raw input, run the handler, serialize to the canonical wire shape. */
+    execute(rawInput: unknown, ctx: OperationContext): Promise<unknown>;
+}
+/**
+ * Structural view of a zod schema (avoids fighting zod's generic variance).
+ * Any `z.looseObject(...)` satisfies this.
+ */
+export interface OperationInputSchema<I> {
+    safeParse(value: unknown): {
+        success: true;
+        data: I;
+    } | {
+        success: false;
+        error: {
+            issues: Array<{
+                path: PropertyKey[];
+                message: string;
+            }>;
+        };
+    };
+}
+export interface OperationDefinition<I extends Record<string, unknown>, O> {
+    name: string;
+    mutates: boolean;
+    /** MUST be loose (z.looseObject / .passthrough()) — legacy ignores unknown keys. */
+    input: OperationInputSchema<I>;
+    inputShape: ZodRawShape;
+    http?: OperationHttpRoute;
+    mcp?: OperationMcpTool;
+    /** The single implementation. Mutate via canvasState/canvas-operations so history records. */
+    handler: (input: I, ctx: OperationContext) => O | Promise<O>;
+    /** Map handler output to the HTTP wire body. Defaults to identity. */
+    serialize?: (output: O) => unknown;
+}
+export declare function defineOperation<I extends Record<string, unknown>, O>(def: OperationDefinition<I, O>): Operation;

package/dist/types/server/operations/webview-runner.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Webview runner injection (plan-008 Wave 3).
+ *
+ * The Bun.WebView automation machinery (startCanvasAutomationWebView / stop /
+ * evaluate / resize / status) lives in `../server.ts`, which `operations/` must
+ * NEVER import (the isolation rule). The webview ops call into the runner
+ * declared here; `server.ts` injects the real implementation at module load via
+ * `setWebviewRunner`, exactly mirroring how `setOperationEventEmitter` injects
+ * the SSE emitter.
+ *
+ * `screenshot` is intentionally NOT part of this runner: it returns a binary
+ * payload and stays a standalone hand-written tool (`canvas_screenshot`).
+ */
+/** Webview status shape (structurally the server.ts CanvasAutomationWebViewStatus). */
+export interface WebviewStatus {
+    supported: boolean;
+    active: boolean;
+    headlessOnly: true;
+    url: string | null;
+    backend: 'webkit' | 'chrome' | null;
+    width: number | null;
+    height: number | null;
+    dataStoreDir: string | null;
+    startedAt: string | null;
+    lastError: string | null;
+}
+/** Start options (structurally the server.ts CanvasAutomationWebViewOptions). */
+export interface WebviewStartOptions {
+    backend?: 'webkit' | 'chrome';
+    width?: number;
+    height?: number;
+    chromePath?: string;
+    chromeArgv?: string[];
+    dataStoreDir?: string;
+}
+/** Outcome of a start attempt, carrying the success/error asymmetry the legacy
+ * route preserved:
+ *  - success → 200 { ok:true, webview }
+ *  - the canvas server is not running → 503 { ok:false, error } (no webview)
+ *  - a supported start failed → 500, an unsupported runtime → 501; both return
+ *    { ok:false, error, webview } and the 500-vs-501 split is read off
+ *    `webview.supported` (the status), so no separate field is needed. */
+export type WebviewStartResult = {
+    ok: true;
+    webview: WebviewStatus;
+} | {
+    ok: false;
+    serverNotRunning: true;
+    error: string;
+} | {
+    ok: false;
+    serverNotRunning?: false;
+    error: string;
+    webview: WebviewStatus;
+};
+export interface WebviewRunner {
+    /** Current automation status (never throws). */
+    status(): WebviewStatus;
+    /** Start or replace the headless automation session for the workbench page. */
+    start(options: WebviewStartOptions): Promise<WebviewStartResult>;
+    /** Stop the active session (resolves false when none was active). May throw. */
+    stop(): Promise<boolean>;
+    /** Resize the active viewport. Throws when no session is active. */
+    resize(width: number, height: number): Promise<WebviewStatus>;
+    /** Evaluate JavaScript in the active page. Throws when no session is active. */
+    evaluate(expression: string): Promise<unknown>;
+}
+export declare function setWebviewRunner(runner: WebviewRunner | null): void;
+export declare function getWebviewRunner(): WebviewRunner;

package/docs/RELEASE.md

@@ -35,6 +35,11 @@ bun run release:smoke       # packs + boots from a clean dir
 bun run pack:dry-run        # confirms the tarball shape
 ```
 
+`bun run test:web-canvas` invokes Playwright through
+`scripts/run-playwright.sh`, which runs the Playwright CLI under Node —
+do not call `bun x playwright test` directly; it fails before test
+discovery with a `.esm.preflight` loader error (ERR-20260508-001).
+
 `bun run test:e2e-cli` starts a local server in a fresh temp workspace
 and exercises the CLI flows from
 [`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).

package/docs/adr-001-bun-only-runtime.md

@@ -0,0 +1,46 @@
+# ADR-001: Bun-only runtime, MCP + HTTP as the universal surfaces
+
+**Status:** Accepted
+**Date:** 2026-06-12
+**Context for:** v0.2 stability release (docs/tech-debt-assessment-2026-06.md, Phase 2)
+
+## Context
+
+pmx-canvas ships as TypeScript source executed directly by Bun. `package.json` points `main`/`exports` at `src/server/index.ts`, the `bin` entry is `src/cli/index.ts` with a `#!/usr/bin/env bun` shebang, and `engines` requires `bun >= 1.3.14`. There is no compiled JS distribution; `dist/` carries only the client bundle, the json-render viewer, and type declarations.
+
+The runtime dependence on Bun is not incidental. `Bun.serve` is the HTTP + SSE server, `bun:sqlite` is the persistence layer, `Bun.WebView` backs the screenshot/evaluate automation tools, and `bun test` is the test runner. These are load-bearing APIs across `src/server/`, not shims that a bundler could paper over.
+
+The recurring question is whether v0.2 should add a Node-compatible dual build (ESM + CJS dist, ported server internals) so Node projects can `import 'pmx-canvas'`. The tech debt assessment already leaned no; this ADR makes the decision explicit and binding.
+
+The decisive observation: nobody integrates with pmx-canvas by importing it. Agents connect over MCP (stdio). Everything else (scripts, harnesses, CI, other languages) talks HTTP + SSE on localhost. The in-process SDK is a convenience for Bun-native tooling and our own CLI, not the distribution channel. A Node build would be sustained effort (porting `Bun.serve`, replacing `bun:sqlite`, a second test matrix, a real build step where today there is none) spent on the least differentiated integration path, while the operation registry refactor is actively consolidating the surfaces that do matter.
+
+## Decision
+
+pmx-canvas stays Bun-only for the SDK and runtime.
+
+1. MCP (stdio) and the HTTP API are the universal integration surfaces. They are runtime-agnostic by construction: any client that can spawn a process or open a socket can use them.
+2. No Node dual-build (ESM + CJS dist of the server/SDK) will be produced. The package continues to ship TypeScript source executed by Bun.
+3. The programmatic SDK (`import { createCanvas } from 'pmx-canvas'`) is documented as Bun-runtime-only.
+4. Bun-specific APIs (`Bun.serve`, `bun:sqlite`, `Bun.WebView`, `bun test`) remain first-class; no compatibility shims are added for hypothetical Node hosting.
+
+## Consequences
+
+The honest costs:
+
+- **Node-based programmatic consumers cannot import the package.** A Node project that wants canvas access must run the server (any of: `bunx pmx-canvas`, a daemon, MCP auto-start) and integrate over HTTP or MCP. This is a real limitation for anyone wanting in-process embedding from Node, and we are accepting it deliberately.
+- **`bin` requires bun on PATH.** The CLI shebang is `#!/usr/bin/env bun`. `npm install -g pmx-canvas` succeeds but the binary fails at invocation on a machine without bun.
+- **npx-style installation has a sharp edge.** `npx pmx-canvas` fetches the package fine but execution still resolves the bun shebang; without bun installed it fails with a confusing error rather than a clear "install bun" message. `bunx pmx-canvas` is the canonical one-shot command and docs must lead with it. The README and CLI install docs should state the bun prerequisite up front, and a fast preflight check in `src/cli/index.ts` that prints an actionable message when bun is missing is cheap insurance (worth doing, not required by this ADR).
+- **MCP client configs must spawn bun.** MCP server entries point at `bunx pmx-canvas --mcp` (or a bun invocation), not `node`/`npx`. Example configs in docs must be consistent about this.
+- **We forgo the npm-ecosystem long tail.** Some integrations will never happen because `import` was the only path their authors would take. We judge that tail small relative to the agents-over-MCP center of mass.
+
+What we gain: zero build step for the server, one runtime to test against, continued free use of `bun:sqlite` and `Bun.serve` without abstraction layers, and engineering time pointed at the operation registry and AX surface instead of distribution plumbing.
+
+## Alternatives considered
+
+- **Full Node dual-build (ESM + CJS dist).** Requires replacing `Bun.serve` (Hono/Express adapter), `bun:sqlite` (better-sqlite3, a native dependency with its own install pain), and dropping or forking `Bun.WebView`. Doubles the test matrix permanently. Rejected: high sustained cost on the path with the least demand.
+- **Node-compatible SDK client only (thin HTTP wrapper published for Node).** Cheaper, but it is just a typed fetch client; any consumer can write one in an afternoon, and an official one creates a second public surface to version and freeze. Rejected for v0.2; can be revisited if real demand appears, without violating this ADR (the server stays Bun-only either way).
+- **Compile-to-single-binary (`bun build --compile`).** Solves "bun on PATH" for the CLI but not programmatic import, adds per-platform release artifacts, and complicates the MCP spawn story. Out of scope for v0.2; does not change this decision.
+
+## Revisit triggers
+
+Reopen this ADR if (a) a major MCP host platform cannot spawn bun, or (b) repeated, concrete integration requests arrive that HTTP/MCP genuinely cannot serve (in-process embedding with shared memory, for example). Absent those, Bun-only stands.

package/docs/api-stability.md

@@ -0,0 +1,57 @@
+# API Stability Contract (v0.2)
+
+**Status:** Accepted, effective from v0.2.0
+**Date:** 2026-06-12
+**Context:** docs/tech-debt-assessment-2026-06.md item 7 (breaking patch releases, no deprecation path) and Phase 2 of the direction proposal. See also docs/adr-001-bun-only-runtime.md for which surfaces are universal.
+
+The problem this fixes: 0.1.35 and 0.1.36 both changed HTTP contract behavior in patch releases. Consumers could not pin safely. From v0.2.0, they can.
+
+## Public surfaces
+
+These four surfaces are the contract. Anything not listed here is internal.
+
+1. **HTTP API:** all `/api/canvas/*` routes documented in `docs/http-api.md`: method, path, request shape, response shape, and status codes.
+2. **MCP surface:** tool names, tool input schemas (field names, types, required/optional status), and the fixed resource URIs (`canvas://layout`, `canvas://pinned-context`, and the rest of the frozen 14). Per-skill resources (`canvas://skills/<name>`) track the `skills/` directory and are explicitly not frozen by name.
+3. **CLI:** the `pmx-canvas` subcommands and flags documented in `docs/cli.md` (including `serve`, `--mcp`, `--port`, `--theme`), their argument shapes, and their output formats where documented as machine-readable.
+4. **SDK:** the exports of the package entry (`src/server/index.ts` via the `exports` map): the `PmxCanvas` class surface, `createCanvas`, and the exported types and helpers. Bun runtime only, per ADR-001.
+
+## Policy
+
+We are in 0.x semver, and we use it honestly:
+
+- **Minor versions (0.2 → 0.3) may break public surfaces.** Breaking changes are allowed only at minor boundaries.
+- **Patch versions never break public surfaces.** A patch may fix bugs, tighten validation of inputs that were never accepted as documented, and add purely additive fields. If a documented request that worked stops working, or a documented response shape changes, that is not a patch.
+- **Every breaking change gets a CHANGELOG entry under a `### Breaking` heading before release.** Not after, not in a follow-up. The release checklist in docs/RELEASE.md treats a breaking change without that heading as a release blocker.
+- **MCP tool names are frozen by `tests/unit/mcp-tool-freeze.test.ts`.** The test pins the literal tool-name list and the fixed resource URIs. Renaming or removing a tool requires editing that test in the same commit, which makes the break deliberate and reviewable rather than accidental. If you find yourself updating the freeze test, you owe a `### Breaking` entry and a minor version.
+- **Additive changes are always allowed:** new tools, new routes, new optional input fields, new response fields. Consumers must tolerate unknown fields in responses.
+
+## Deprecation
+
+A public surface is marked deprecated at least one minor version before removal. Concretely:
+
+1. Mark it in the docs (`docs/http-api.md`, `docs/mcp.md`, `docs/cli.md`, or `docs/sdk.md`) and in the MCP tool description where applicable.
+2. Record it in the CHANGELOG under `### Deprecated` in the minor that deprecates it.
+3. Remove it no earlier than the next minor, with a `### Breaking` entry naming the replacement.
+
+So a tool deprecated in 0.2.x survives all of 0.2.x and may be removed in 0.3.0. Plan-006 (MCP tool consolidation) is the first consumer of this mechanism.
+
+## Explicitly out of contract
+
+These can change in any release without notice:
+
+- **SSE event payload internals.** The existence of the `/api/workbench/events` stream is public; the field-level shape of individual event frames is not. Build on the HTTP read endpoints, not on event internals.
+- **Undocumented endpoints.** Anything reachable but not in `docs/http-api.md` (internal prompt/trace/theme plumbing, browser-only routes) is internal.
+- **The `.pmx-canvas/` on-disk layout.** `canvas.db` schema, artifact directory structure, daemon pid/log files. Migrations keep old data readable; the format itself is ours to change.
+- **Anything under `src/` not exported from the package entry.** Deep imports (`pmx-canvas/src/server/whatever`) get no stability promise even where the file layout makes them possible.
+- **Browser UI:** DOM structure, CSS custom properties, client bundle internals.
+
+## Enforcement: the operation registry
+
+The contract is only as real as its single source of truth. The operation registry (`src/server/operations/`, docs/plans/plan-005-operation-registry.md) gives each canvas operation exactly one zod input schema and one handler, from which the HTTP route, MCP tool, CLI command, and SDK method derive. One schema per operation means one place where the contract lives, one diff to review when it changes, and no cross-surface drift of the kind that produced the 0.1.x breakages (the same operation behaving differently over HTTP vs local MCP access).
+
+Two mechanical guards back the policy:
+
+- `tests/unit/mcp-tool-freeze.test.ts`: tool names and fixed resource URIs cannot change silently.
+- `tests/unit/operation-parity.test.ts`: migrated operations behave identically across surfaces, including tolerance of unknown input keys (schemas stay loose; strict parsing would be an invisible break).
+
+Operations not yet migrated to the registry are covered by the same policy; the registry just makes compliance cheap instead of disciplined.

package/docs/ax-host-adapter-contract.md

@@ -0,0 +1,65 @@
+# AX host-adapter contract
+
+PMX Canvas owns the **AX data layer** — work items, approval gates, steering,
+evidence, review annotations, elicitations, mode requests, the timeline, host
+capabilities, and the tool/prompt policy — over HTTP and MCP. What makes AX
+*interactive* on a given coding harness (GitHub Copilot, Codex, Claude Code, …) is
+a thin **adapter** that wires PMX's neutral surfaces to that harness's lifecycle.
+
+"Agnostic" means a documented interface plus PMX-side behavior plus one small
+reference adapter per harness — not zero-adapter magic. The genuinely harness-owned
+acts (waking a turn, per-turn context injection, forwarding native tool hooks,
+native modals) still need a per-harness adapter; PMX owns everything on its side of
+the line (queues, endpoints, schemas, the canvas-surface fallback).
+
+## The interface
+
+Every adapter implements as much of this as its host allows; PMX provides the
+surface each one binds to.
+
+| Adapter method | PMX surface (owned) | Harness-owned part |
+| --- | --- | --- |
+| `pullContext()` | `GET /api/canvas/ax/context?consumer=<id>` · `canvas://ax-context` — full board **plus** a compact `delivery` lead block | When/where to inject it into the model's turn |
+| `deliverSteer()` | `GET /api/canvas/ax/delivery/pending?consumer=<id>` · `canvas_claim_ax_delivery` → act → `POST …/delivery/<id>/mark` · `canvas_mark_ax_delivery` | Calling the host's native send/wake |
+| `ingestActivity(event)` | `POST /api/canvas/ax/activity` · `canvas_ingest_activity` — board auto-reacts | Forwarding the host's tool/session hooks |
+| `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_await_*` | Optionally surfacing a native modal; the agent must await PMX |
+| `mirrorLog(event)` *(optional)* | `GET /api/canvas/ax/timeline` · `canvas://ax-timeline` | Writing AX events into the host's own chat/session log |
+
+## Steering is gated, not pushed (#54)
+
+A board action (e.g. an `ax.steer` emit from a surface button) enqueues a steering
+message; it does **not** wake the agent. It reaches the next turn only when:
+
+1. **The pin/focus gate is open.** A typical adapter injects `/api/canvas/ax/context`
+   only when something is pinned or focused (`pinned.count > 0 || focus.nodeIds.length > 0`).
+   A steering board must therefore stay pinned, or its button should also emit
+   `ax.focus.set` on the board node, to hold the gate open.
+2. **A human message fires the turn.** A sandbox button click cannot itself create a
+   new agent turn (an app-platform constraint). Any human prompt triggers the injection.
+3. **The agent acts, then acks.** Injected `pendingSteering` / `pendingActivity` is
+   *to-do*, not narration: act on it, then `canvas_mark_ax_delivery` the steering
+   (or resolve the work item / gate). Until acked, steering re-injects every gated turn.
+
+The `delivery` lead block (`GET /api/canvas/ax/context?consumer=<id>`) is the
+robustness hedge: it's compact and sits above the full dump, so an adapter can inject
+it un-truncated even on a busy board where the full context is clipped.
+
+## The two primitives that close the loop
+
+- **Activity ingestion (bidirectional board).** Before, AX was one-directional
+  (agent → board). With `ingestActivity`, the agent's *real work* flows back: a failed
+  tool becomes a blocked work item + a review finding + evidence without the agent
+  remembering to push it. Reactions are kind-driven and overridable per call.
+- **Blocking gates (gates that actually gate).** Before, an approval gate was inert
+  data the agent had to poll. With `canvas_await_approval` (and the `?waitMs` HTTP
+  long-poll), the agent requests a gate then *blocks* until the human resolves it in
+  the browser — real human-in-the-loop control on any harness.
+
+## What stays harness-owned
+
+Waking a turn, the exact per-turn injection timing, forwarding native tool hooks, and
+native blocking modals are the host's job — PMX defines the neutral interface and owns
+its side. Model/abort control (`setModel`, `abort`) is intentionally out of scope.
+
+See [`docs/http-api.md`](http-api.md) and [`docs/mcp.md`](mcp.md) for the full surface,
+and the per-harness notes under `skills/pmx-canvas/references/`.

package/docs/ax-state-contract.md

@@ -0,0 +1,72 @@
+# AX state contract (authoritative)
+
+The agent-experience (AX) state is split into **three partitions** with distinct
+storage and lifecycle rules. This document is the authoritative spec for the
+snapshot-vs-audit boundary; it is the documented module boundary for
+`AxStateManager` (`src/server/ax-state-manager.ts`), which `CanvasStateManager`
+holds and delegates to.
+
+| Partition | Members | Storage | Snapshotted | Cleared by `canvas_clear` | Cleared by `restore` |
+|-----------|---------|---------|:-----------:|:-------------------------:|:--------------------:|
+| **Canvas-bound** | `focus`, `workItems`, `approvalGates`, `reviewAnnotations`, `elicitations`, `modeRequests`, `policy` | in-memory `_axState` + one JSON blob in the `ax_state` table | ✅ | ✅ | ✅ (replaced by the snapshot's AX) |
+| **Timeline (audit-only)** | `agent-event`, `evidence-item`, `steering-message` | `ax_events` / `ax_evidence` / `ax_steering` tables, 500-row retention, sequential ids | ❌ | ❌ | ❌ |
+| **Host/session** | `host-capability` | `ax_host_capabilities` table | ❌ | ❌ | ❌ |
+
+**Rules.** Canvas-bound state travels with the canvas (snapshot / restore / clear);
+timeline and host data are diagnostic and survive all three. Timeline rows are
+append-only, retention-bounded (`AX_TIMELINE_RETENTION = 500` per table), and
+read via `canvas_get_ax_timeline` / `canvas://ax-timeline`. The host-capability
+row is reported by adapters and read via `canvas_get_ax`.
+
+## Read surfaces
+
+- **Canvas-bound:** `canvas_get_ax`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-work`
+- **Timeline:** `canvas_get_ax_timeline`, `canvas://ax-timeline`, `canvas://ax-pending-steering`, `canvas://ax-delivery`
+- **Host:** `canvas_get_ax`
+
+## Node-deletion semantics (soft-orphan + audit)
+
+When a node is removed, the canvas-bound partition is re-normalized against the
+surviving node set (`AxStateManager.revalidateAfterNodeRemoval`):
+
+- **Work items / approval gates / elicitations / mode requests** that referenced
+  the deleted node keep the item but **strip the dangling node id** ("re-anchored").
+  The data semantics are soft-orphan: the work is not destroyed.
+- **Node-anchored review annotations** (`anchorType: 'node'`) for the deleted node
+  are **dropped entirely** ("removed") — they are meaningless without their node.
+
+This re-normalization was previously **silent**. It now records exactly one
+auditable **timeline** event when (and only when) something was actually affected:
+
+```
+kind:    'note'
+source:  'system'
+summary: 'Node "<title>" deleted — re-anchored N AX item(s),
+          removed M node-anchored review annotation(s). [(focus anchor cleared)]'
+data:    {
+  systemEvent:      'ax-node-orphan',
+  removedNodeId:    '<node id>',
+  reanchoredIds:    [ ...work/gate/elicitation/mode ids... ],
+  removedReviewIds: [ ...review annotation ids... ],
+  reanchoredFocus:  <boolean>,   // true if focus.nodeIds referenced the deleted node
+}
+```
+
+The audit lives in the **timeline** (audit partition) — correct per the contract:
+it is diagnostic continuity, not canvas-bound state, so it survives clear/restore
+and is not part of any snapshot. `recordAxEvent` is timeline-only and does not
+re-enter the canvas-bound normalization path, so there is no recursion.
+
+The audit is scoped to `removeNode` (the live, observable change). `restore`
+replaces the whole canvas wholesale and its snapshot AX was already consistent
+when it was saved, so it is not audited.
+
+**Append-only / undo semantics.** The note records a historical fact (at time T,
+deleting node X re-anchored these items), not current state. It is **not rolled
+back on undo** and **not duplicated on redo**: undo restores the canvas-bound AX
+state (the re-anchoring is reversed in the live state) but leaves the note as a
+record; redo replays `removeNode` inside suppressed recording
+(`_suppressRecordingDepth > 0`), which re-runs the re-normalization but does
+**not** append a second note. Consumers should read `reanchoredIds` /
+`removedReviewIds` against the *current* canvas-bound state, not assume the
+referenced items are still re-anchored.

package/docs/http-api.md

@@ -46,8 +46,18 @@ curl -X POST http://localhost:4313/api/canvas/node \
 curl -X POST http://localhost:4313/api/canvas/node \
   -H "Content-Type: application/json" \
   -d '{"type":"html-primitive","kind":"choice-grid","title":"Options","data":{"items":[{"title":"Small patch","summary":"Least disruption."}]}}'
+
+# Opt an html node into AX. Top-level `html` AND `axCapabilities` are accepted on
+# POST add and PATCH update (and may also be nested under `data`).
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html","title":"AX board","html":"<p>steering board</p>","axCapabilities":{"enabled":true,"allowed":["ax.steer"]}}'
 ```
 
+A node creation request must resolve a `type` — pass it in the body (`{ "type":
+... }`) or as a `?type=` query param. An empty / type-less body returns `400`
+rather than silently creating a markdown node.
+
 ## Edges
 
 ```bash
@@ -177,7 +187,9 @@ curl http://localhost:4313/api/canvas/ax/host-capability
 
 Validation: `/ax/event` requires a valid `kind` + `summary` (400 otherwise);
 `/ax/evidence` requires `kind` + `title`; `/ax/steer`, `/ax/work`,
-`/ax/approval`, `/ax/review` require their primary field; `PATCH /ax/work/:id`
+`/ax/approval`, `/ax/review` require their primary field; `POST`/`PATCH /ax/work`
+reject an unknown `status` with 400 (the tokens are `todo`, `in-progress`,
+`blocked`, `done`, `cancelled` — hyphens, not underscores); `PATCH /ax/work/:id`
 and `PATCH /ax/review/:id` return 404 for unknown IDs; approval resolve returns
 404 if the gate is missing or already resolved.
 
@@ -218,6 +230,24 @@ curl -X POST http://localhost:4313/api/canvas/ax/mode/<id>/resolve \
   -d '{"decision":"approved"}'
 curl http://localhost:4313/api/canvas/ax/mode
 
+# Activity ingestion — forward an agent tool/session event; the board auto-reacts
+# (kind-driven, overridable: failure → work item + review + evidence; tool-result
+# + outcome:"success" → evidence). Set a reaction to false to suppress it.
+curl -X POST http://localhost:4313/api/canvas/ax/activity \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"failure","title":"tsc failed","summary":"type error in x.ts","nodeIds":["node-1"],"source":"api"}'
+
+# Blocking gate read — read one gate, or long-poll with ?waitMs until the human
+# resolves it in the browser (gates that actually gate). Returns { <primitive>, pending }.
+curl "http://localhost:4313/api/canvas/ax/approval/<id>"                 # immediate read
+curl "http://localhost:4313/api/canvas/ax/approval/<id>?waitMs=30000"    # blocks ≤30s / until resolved
+curl "http://localhost:4313/api/canvas/ax/elicitation/<id>?waitMs=30000"
+curl "http://localhost:4313/api/canvas/ax/mode/<id>?waitMs=30000"
+
+# Context — optional ?consumer= filters the compact, loop-safe `delivery` lead block
+# (undelivered steering + open work/approvals it can act on) for per-turn injection.
+curl "http://localhost:4313/api/canvas/ax/context?consumer=copilot"
+
 # Commands — list the registry, invoke a command (records a `command` agent-event)
 curl http://localhost:4313/api/canvas/ax/command
 curl -X POST http://localhost:4313/api/canvas/ax/command \
@@ -234,7 +264,9 @@ curl -X POST http://localhost:4313/api/canvas/ax/policy \
 Validation: `/ax/interaction` returns `{ ok: false, code }` (403 `ax-disabled` /
 `not-allowed`, 400 `invalid-payload` / `unknown-command`, 404 `unknown-node`);
 `/ax/command` rejects an unknown command name with 400; `/ax/elicitation/:id/respond`
-and `/ax/mode/:id/resolve` return 404 for unknown IDs.
+and `/ax/mode/:id/resolve` return 404 for unknown IDs; `/ax/activity` requires a
+valid `kind` + `title` (400 otherwise); the single-item gate GETs return 404 for
+unknown IDs and clamp `?waitMs` to ≤120000.
 
 ## Diagrams (Excalidraw preset)