pmx-canvas 0.2.7 → 0.3.1

package/dist/types/mcp/canvas-access.d.ts

@@ -1,10 +1,6 @@
 import { type CanvasLayout, type CanvasNodeState, type PmxCanvas } from '../server/index.js';
 import type { PmxAxSource } from '../server/ax-state.js';
 import { type OperationInvoker } from '../server/operations/index.js';
-type RefreshWebpageNodeResult = Awaited<ReturnType<PmxCanvas['refreshWebpageNode']>>;
-type AddHtmlNodeInput = Parameters<PmxCanvas['addHtmlNode']>[0];
-type AddHtmlPrimitiveInput = Parameters<PmxCanvas['addHtmlPrimitive']>[0];
-type AddHtmlPrimitiveResult = ReturnType<PmxCanvas['addHtmlPrimitive']>;
 type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
 type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
 type SubmitAxInteractionInput = Parameters<PmxCanvas['submitAxInteraction']>[0];
@@ -33,9 +29,6 @@ export interface CanvasAccess {
     invoker(): OperationInvoker;
     getLayout(): Promise<CanvasLayout>;
     getNode(id: string): Promise<CanvasNodeState | undefined>;
-    refreshWebpageNode(id: string, url?: string): Promise<RefreshWebpageNodeResult>;
-    addHtmlNode(input: AddHtmlNodeInput): Promise<string>;
-    addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult>;
     getAxState(): Promise<AxStateResult>;
     getAxContext(options?: {
         consumer?: string;

package/dist/types/server/ax-state-manager.d.ts

@@ -7,8 +7,9 @@
  *
  *   • Canvas-bound (`_axState`): focus, work items, approval gates, review
  *     annotations, elicitations, mode requests, policy. Snapshotted, cleared by
- *     `canvas_clear`, replaced by `restore`. Mutators record undo/redo history
- *     (via the injected `recordMutation` / `suppressed` callbacks).
+ *     `canvas_view` (`clear` action), replaced by `restore`. Mutators record
+ *     undo/redo history (via the injected `recordMutation` / `suppressed`
+ *     callbacks).
  *   • Timeline (audit-only): agent events, evidence, steering. DB-direct, NOT in
  *     `_axState`, NOT history-recorded, NOT snapshotted, retention-bounded.
  *   • Host/session: a single host-capability row in its own table.

package/dist/types/server/bundled-skills.d.ts

@@ -3,9 +3,9 @@
  *
  * Skill files ship inside the npm package under `skills/<name>/SKILL.md`
  * but until 0.1.2 they were not discoverable to the agent — an agent
- * calling `canvas_build_web_artifact` had no way to find the companion
- * `skills/web-artifacts-builder/SKILL.md` prompt that documents the
- * workflow, stack choices, and gotchas.
+ * calling `canvas_app` (`build-artifact` action) had no way to find the
+ * companion `skills/web-artifacts-builder/SKILL.md` prompt that documents
+ * the workflow, stack choices, and gotchas.
  *
  * This module locates the bundled `skills/` directory relative to the
  * package root (works for both repo-local development and global npm

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

@@ -34,7 +34,7 @@ export interface StructuredValidationResult {
     summary: Record<string, unknown>;
 }
 declare const CANONICAL_GRAPH_TYPES: readonly ["line", "bar", "pie", "area", "scatter", "radar", "stacked-bar", "composed", "sparkline", "dot-plot", "bullet", "slopegraph"];
-type CanvasGraphType = typeof CANONICAL_GRAPH_TYPES[number];
+type CanvasGraphType = (typeof CANONICAL_GRAPH_TYPES)[number];
 export declare function describeCanvasSchema(): {
     ok: true;
     source: 'running-server';

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

@@ -174,6 +174,8 @@ declare class CanvasStateManager {
     private _stateFilePath;
     private _db;
     private _saveTimer;
+    /** Workspace root backing persistence and workspace-relative path resolution. */
+    get workspaceRoot(): string;
     /** Set the workspace root to enable auto-persistence. */
     setWorkspaceRoot(workspaceRoot: string): void;
     private get blobsDir();

package/dist/types/server/ext-app-lookup.d.ts

@@ -9,9 +9,7 @@
  * Resolution order:
  *   1. The direct prefixed form (`ext-app-<toolCallId>` if not already
  *      prefixed, otherwise `toolCallId` as-is).
- *   2. The legacy `ext-app-ext-app-…` form, for canvases persisted before
- *      v0.1.4 and still on disk. Remove this fallback in v0.2.x.
- *   3. A scan of the layout for any `mcp-app` ext-app node carrying that
+ *   2. A scan of the layout for any `mcp-app` ext-app node carrying that
  *      `toolCallId` in its data.
  */
 import type { CanvasNodeState } from './canvas-state.js';

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

@@ -1,5 +1,5 @@
 export declare const HTML_PRIMITIVE_KINDS: readonly ["choice-grid", "plan-timeline", "review-sheet", "pr-writeup", "system-map", "code-walkthrough", "design-sheet", "component-gallery", "interaction-prototype", "flowchart", "deck", "presentation", "illustration-set", "explainer", "status-report", "incident-report", "triage-board", "config-editor", "prompt-tuner"];
-export type HtmlPrimitiveKind = typeof HTML_PRIMITIVE_KINDS[number];
+export type HtmlPrimitiveKind = (typeof HTML_PRIMITIVE_KINDS)[number];
 export interface HtmlPrimitiveDescriptor {
     kind: HtmlPrimitiveKind;
     title: string;

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

@@ -13,7 +13,7 @@ import { type SerializedCanvasNode } from './canvas-serialization.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
-import { type DiagramPresetOpenInput } from './diagram-presets.js';
+import type { DiagramPresetOpenInput } from './diagram-presets.js';
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 import type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus } from './server.js';
 /**
@@ -557,21 +557,21 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, screenshotCanvasAutomationWebView, } from './server.js';
 export { canvasState } from './canvas-state.js';
-export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions } from './canvas-state.js';
+export type { CanvasAnnotation, CanvasSnapshot, CanvasSnapshotGcResult, CanvasSnapshotListOptions, } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';
 export type { SpatialCluster, SpatialContext, SpatialNeighbor, NodeSpatialInfo } from './spatial-analysis.js';
 export { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 export { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 export { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
-export { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
+export { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors, } from './html-primitives.js';
 export { buildWebArtifactOnCanvas, executeWebArtifactBuild, openWebArtifactInCanvas, resolveWebArtifactScriptPath, resolveWorkspacePath, } from './web-artifacts.js';
 export { buildGraphSpec, buildJsonRenderViewerHtml, createJsonRenderNodeData, GRAPH_NODE_SIZE, JSON_RENDER_NODE_SIZE, normalizeAndValidateJsonRenderSpec, } from '../json-render/server.js';
 export type { CodeGraphSummary, CodeGraphEdge } from './code-graph.js';
 export type { MutationEntry, MutationSummary, SnapshotDiffResult } from './mutation-history.js';
 export type { WebArtifactBuildInput, WebArtifactBuildOutput, WebArtifactCanvasBuildResult, WebArtifactCanvasOpenResult, } from './web-artifacts.js';
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
-export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
+export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult, } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';
 export type { PmxAxApprovalGate, PmxAxApprovalStatus, PmxAxCommandDescriptor, PmxAxContext, PmxAxEvent, PmxAxElicitation, PmxAxElicitationStatus, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxModeRequestStatus, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxTimelineSummary, PmxAxWorkItem, PmxAxWorkItemStatus, } from './ax-state.js';
 export type { AxTimelineQuery } from './canvas-db.js';

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

@@ -9,17 +9,22 @@
  * to the standalone `canvas_add_edge` — same op, same arg mapping, same result
  * shape — by construction. No handler logic lives here.
  *
- * Migration (docs/api-stability.md + plan-006): composites land ADDITIVELY in
- * v0.2 alongside the legacy single-purpose tools (the tool surface grows, then
- * shrinks when the legacy tools are removed in v0.3). Every action here maps to a
- * registry-backed operation (plan-005 slices 1–7 + plan-008 Wave 1).
+ * Migration (docs/api-stability.md + plan-006): composites landed ADDITIVELY in
+ * v0.2 alongside the legacy single-purpose tools. As of v0.3.0 the legacy tools
+ * those composites fold are REMOVED (registration-suppressed — see
+ * `compositeFoldedOpNames` below); every action here maps to a registry-backed
+ * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
+ * through its composite (or `canvas_batch`).
  *
- * Still deferred (its legacy standalone tool keeps working; see plan-008): the
- * `canvas_snapshot` composite (the v0.3 name collision). The action enums are
- * forward-compatible: adding an action later is additive. (`canvas_webview`
- * shipped in plan-008 Wave 3 via runner injection; `canvas_app` shipped in Wave 4
- * — open-mcp-app / diagram / build-artifact. Wave 5 folded the last three legacy
- * tools deprecate-only — NO per-action input-injection mechanism was needed:
+ * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
+ * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
+ * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
+ * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
+ * deprecated (description-prefixed) per docs/api-stability.md's
+ * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
+ * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
+ * diagram / build-artifact. Wave 5 folded the last three legacy tools
+ * deprecate-only — NO per-action input-injection mechanism was needed:
  * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
  * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
  * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
@@ -30,8 +35,8 @@
  * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
  * `snapshot.save`), so it cannot be added additively without a name clash, and
  * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.3, in the same change that removes the legacy
- * single-purpose snapshot tools and frees the name.
+ * existing callers. It lands in v0.4, in the same change that removes the 6
+ * kept-but-deprecated legacy snapshot tools and frees the name.
  *
  * This module must never import server.ts or index.ts.
  */
@@ -45,7 +50,7 @@ import { type ZodRawShape } from 'zod';
  *  - Two-discriminator (`canvas_ax_gate`, plan-007 Slice C): a `kind` × `action`
  *    matrix folds 9 ops into one tool. Set `extraDiscriminatorShape` (the `kind`
  *    enum), `memberOps` (the op names — used to derive the schema union + the
- *    deprecation notes), `actionEnum` (the action discriminator values), and
+ *    folded-op set), `actionEnum` (the action discriminator values), and
  *    `resolveOp` (maps `{ kind, action }` → op name, or undefined for an invalid
  *    combo → a loud error at dispatch). The flat `actions` map is left empty for
  *    these; the matrix path uses `resolveOp` instead.
@@ -76,8 +81,9 @@ export interface CompositeToolDefinition {
     actionEnum?: readonly string[];
     /**
      * Two-discriminator extension: every member op name. Used to build the schema
-     * union (all member-op fields, optional) and to derive a deprecation note per
-     * member op (each mapped back to its (kind, action) by `describeOp`).
+     * union (all member-op fields, optional) and to populate the folded-op set
+     * (`compositeFoldedOpNames`) that suppresses each member op's standalone
+     * registration.
      */
     memberOps?: string[];
     /**
@@ -110,12 +116,12 @@ export interface CompositeToolDefinition {
 }
 export declare const compositeToolDefinitions: CompositeToolDefinition[];
 /**
- * Deprecation notes for the legacy single-purpose tools, DERIVED from the
- * composites: every operation a composite folds gets a `Deprecated: use
- * canvas_x with action "y".` prefix on its standalone tool description, steering
- * agents to the composite during the v0.2 overlap window (the legacy tools and
- * these notes are removed together in v0.3). Keyed by registry operation name.
- * Deriving it keeps the deprecation list in lockstep with the composites — a new
- * folded action automatically deprecates the tool it replaces.
+ * Operation names FOLDED by a composite, DERIVED from the composites: every op
+ * a composite folds had its standalone single-purpose tool REMOVED in v0.3.0
+ * (see docs/api-stability.md). This set is the do-not-register list —
+ * `registerOperationTools` skips any op whose name is in it, since the op is
+ * only reachable through its composite (and through `canvas_batch`) now.
+ * Deriving it from the composites keeps suppression in lockstep with them — a
+ * newly folded action is automatically suppressed from standalone registration.
  */
-export declare function buildCompositeDeprecationNotes(definitions?: CompositeToolDefinition[]): Map<string, string>;
+export declare function compositeFoldedOpNames(definitions?: CompositeToolDefinition[]): Set<string>;

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

@@ -1,7 +1,8 @@
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,
  * or primitive) — per-op `readInput` decides what to do with non-object
- * bodies; the shared reader never coerces.
+ * bodies; the shared reader never coerces. A non-empty body that fails to
+ * parse is a 400 (OperationError), never a silent empty input.
  */
 export declare function readJsonValue(req: Request): Promise<unknown>;
 export declare function dispatchOperationRoute(req: Request, url: URL): Promise<Response | null>;

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

@@ -1,7 +1,7 @@
 export { executeOperation, getOperation, listOperations, registerOperation, setOperationEventEmitter, } from './registry.js';
 export { dispatchOperationRoute } from './http.js';
 export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
-export { type OpenMcpAppCoreResult } from './ops/app.js';
+export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
 export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';

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

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

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

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

package/dist/types/server/operations/ops/ext-app.d.ts

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

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

@@ -5,7 +5,7 @@
  * agent is ABOUT to make (create / move / connect / remove / edit) so the canvas
  * can paint a faint placeholder before the real mutation lands. Like a
  * multiplayer cursor, it auto-expires, is count-capped, and never enters
- * `canvas_get_layout`, `state.json`, or snapshots.
+ * `canvas_query` (`layout` action), `state.json`, or snapshots.
  *
  * This module is import-shared by the server (IntentRegistry + the intent ops)
  * and the client (intent-store + IntentLayer); it must stay free of any

package/docs/RELEASE.md

@@ -46,14 +46,18 @@ and exercises the CLI flows from
 
 ## Versioning
 
-Semantic versioning. While we are still in `0.1.x`:
-
-- Patch (`0.1.x → 0.1.x+1`): bug fixes, hardening, internal cleanups,
-  additive CLI flags / MCP fields with backwards-compat fallbacks.
-- Minor (`0.1.x → 0.2.0`): documented breaking changes (e.g. dropping
-  the `hostMode + path` fallback in `getCanvasNodeKind`, removing legacy
-  `ext-app-ext-app-…` ID handling, JSON-shape changes that aren't
-  additive).
+Semantic versioning, in 0.x semver honestly (see `docs/api-stability.md`).
+We are pre-1.0, so minor versions — not just major — are the breaking-change
+boundary:
+
+- Patch (`0.x.y → 0.x.y+1`): bug fixes, hardening, internal cleanups,
+  additive CLI flags / MCP fields with backwards-compat fallbacks. Never
+  breaks a public surface.
+- Minor (`0.x → 0.x+1`): documented breaking changes are allowed only here
+  (e.g. the 0.2 → 0.3 removal of the 57 deprecated legacy single-purpose MCP
+  tools in favor of their composite replacements). Every breaking change in
+  a minor needs a `### Breaking` CHANGELOG entry naming the replacement —
+  see the release-blocker gate below.
 - Major (`0.x → 1.0`): production-stability commitment.
 
 CLAUDE.md rule #5 (CanvasStateManager / PmxCanvas SDK / HTTP / MCP
@@ -70,6 +74,11 @@ Each release section uses these subheadings:
   command/flag, SDK export, JSON shape).
 - **Changed** — behavior changes that aren't strictly bug fixes
   (response shape additions, schema cleanups, stricter validation).
+- **Breaking** — removed or incompatibly changed public surface (see
+  `docs/api-stability.md`). Required at minor version boundaries whenever a
+  public surface breaks; must name the replacement.
+- **Deprecated** — public surface marked for removal in a future minor,
+  per the `docs/api-stability.md` deprecation policy.
 - **Fixed** — bug fixes.
 - **Internal** — refactors, test additions, docs that don't affect
   the public surface.
@@ -78,6 +87,12 @@ Don't ship a release without a CHANGELOG entry. The GitHub release
 notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
 expands on the CHANGELOG with examples and migration notes.
 
+**Release-blocker gate:** a breaking change without a `### Breaking`
+CHANGELOG entry blocks the release (`docs/api-stability.md`). Check the
+diff against the previous tag for removed/renamed public surface — MCP
+tool names, HTTP routes, SDK exports, CLI flags — before tagging; if
+anything broke and isn't named under `### Breaking`, add the entry first.
+
 ## Tag → publish
 
 The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))

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

@@ -20,9 +20,9 @@ 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 |
+| `deliverSteer()` | `GET /api/canvas/ax/delivery/pending?consumer=<id>` · `canvas_ax_delivery { action: "claim" }` → act → `POST …/delivery/<id>/mark` · `canvas_ax_delivery { action: "mark" }` | 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 |
+| `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_ax_gate { kind: "approval"\|"elicitation"\|"mode", action: "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)
@@ -37,8 +37,8 @@ message; it does **not** wake the agent. It reaches the next turn only when:
 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.
+   *to-do*, not narration: act on it, then `canvas_ax_delivery { action: "mark" }`
+   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
@@ -69,9 +69,9 @@ turn"), never imply it interrupts the agent now.
   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.
+  data the agent had to poll. With `canvas_ax_gate { kind: "approval", action: "await" }`
+  (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
 

package/docs/ax-state-contract.md

@@ -6,7 +6,7 @@ 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` |
+| Partition | Members | Storage | Snapshotted | Cleared by `canvas_view { action: "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 | ❌ | ❌ | ❌ |
@@ -15,14 +15,15 @@ holds and delegates to.
 **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 via `canvas_ax_timeline { action: "read" }` / `canvas://ax-timeline`. The
+host-capability row is reported by adapters and read via `canvas_ax_state {
+action: "get" }`.
 
 ## 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`
+- **Canvas-bound:** `canvas_ax_state { action: "get" }`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-work`
+- **Timeline:** `canvas_ax_timeline { action: "read" }`, `canvas://ax-timeline`, `canvas://ax-pending-steering`, `canvas://ax-delivery`
+- **Host:** `canvas_ax_state { action: "get" }`
 
 ## Node-deletion semantics (soft-orphan + audit)
 

package/docs/bun-webview-integration.md

@@ -144,11 +144,11 @@ These flags are intentionally automation-only. They do **not** imply a visible B
 
 Implemented in [`src/mcp/server.ts`](../src/mcp/server.ts):
 
-- `canvas_webview_status`
-- `canvas_webview_start`
-- `canvas_webview_stop`
-- `canvas_evaluate`
-- `canvas_resize`
+- `canvas_webview { action: "status" }`
+- `canvas_webview { action: "start" }`
+- `canvas_webview { action: "stop" }`
+- `canvas_webview { action: "evaluate" }`
+- `canvas_webview { action: "resize" }`
 - `canvas_screenshot`
 
 Current MCP behavior:

package/docs/cli.md

@@ -217,7 +217,7 @@ take a screenshot when the drawn form matters.
 
 Humans draw with the pen toolbar button and remove marks with the eraser button.
 If an agent already knows the annotation ID from context, it can remove it through
-MCP with `canvas_remove_annotation`.
+MCP with `canvas_view { action: "remove-annotation", id }`.
 
 ## When to reach for the CLI
 

package/docs/http-api.md

@@ -3,14 +3,18 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+A non-empty request body that is not valid JSON returns
+`400 { "ok": false, "error": "Malformed JSON body." }` on every route; empty
+bodies are treated as an empty request.
+
 ## Canvas state
 
 ```bash
 # Get canvas state
 curl http://localhost:4313/api/canvas/state
 
-# Search nodes
-curl "http://localhost:4313/api/canvas/search?q=auth"
+# Search nodes (optional limit= caps the result count)
+curl "http://localhost:4313/api/canvas/search?q=auth&limit=10"
 
 # Validate the current layout
 curl http://localhost:4313/api/canvas/validate
@@ -133,7 +137,7 @@ Host-agnostic agent-experience primitives across three state partitions.
 Canvas-bound state (work items, approval gates, review annotations) rides
 canvas snapshots; timeline state (events, evidence, steering) persists for
 diagnostics but is retention-bounded and not restored by snapshots; the host
-capability is reported by adapters and survives `canvas_clear`.
+capability is reported by adapters and survives `canvas_view { action: "clear" }`.
 
 ```bash
 # Timeline — record a normalized agent-event
@@ -272,6 +276,34 @@ 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.
 
+## Ghost Cursor intents (ephemeral)
+
+Intents are verb-routed over HTTP — there is **no `action` field**. That
+discriminator exists only on the MCP `canvas_intent` composite; `POST` always
+signals a *new* intent, so a body like `{"action":"clear"}` is rejected by the
+registry's kind validation. Pick the operation by method + path:
+
+```bash
+# Signal a ghost — returns { ok, intent } with the id. Auto-expires after ttlMs
+# (default 8000, max 60000), so cleanup is optional.
+curl -X POST http://localhost:4313/api/canvas/ax/intent \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"create","position":{"x":400,"y":300},"nodeType":"markdown","label":"Add evidence","reason":"collecting run logs"}'
+
+# Update the ghost (position/label/reason/confidence/ttlMs; vetoed:true dissolves
+# it AND poisons the id so a later linked settle is rejected)
+curl -X PATCH http://localhost:4313/api/canvas/ax/intent/<id> \
+  -H "Content-Type: application/json" \
+  -d '{"position":{"x":520,"y":300},"reason":"moved next to the trace"}'
+
+# Clear the ghost: plain DELETE dissolves it; settle it into the real node it
+# became via settledNodeId, or veto it. Fields are accepted as JSON body or
+# query params (?vetoed=true/false is coerced; other values are rejected 400).
+curl -X DELETE http://localhost:4313/api/canvas/ax/intent/<id>
+curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?settledNodeId=node-42"
+curl -X DELETE "http://localhost:4313/api/canvas/ax/intent/<id>?vetoed=true"
+```
+
 ## Diagrams (Excalidraw preset)
 
 ```bash