pmx-canvas 0.1.36 → 0.2.0

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

@@ -0,0 +1,121 @@
+/**
+ * Composite MCP tools (plan-006: MCP tool consolidation).
+ *
+ * A composite tool folds several single-purpose MCP tools into one tool with an
+ * `action` discriminator. It is a PRESENTATION-LAYER construct only: each action
+ * dispatches to an already-registered operation (`src/server/operations/ops/*`)
+ * via the same invoker, reusing that operation's own `mcp.buildInput` and
+ * `mcp.formatResult`. So `canvas_edge { action: "add", ... }` is byte-identical
+ * 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).
+ *
+ * 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:
+ * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
+ * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
+ * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
+ * returns a binary image payload the composite/registry JSON wire shape does not
+ * model.)
+ *
+ * Not shipped here: the `canvas_snapshot` composite (plan-006 #7). Its target
+ * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
+ * `snapshot.save`), so it cannot be added additively without a name clash, and
+ * repurposing `canvas_snapshot` to be action-discriminated now would break
+ * existing callers. It lands in v0.3, in the same change that removes the legacy
+ * single-purpose snapshot tools and frees the name.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { type ZodRawShape } from 'zod';
+/**
+ * One composite MCP tool: a frozen tool name + its action→operation routing.
+ *
+ * Two flavours:
+ *  - Single-discriminator (the wave-1 composites + the 4 single-discriminator AX
+ *    composites): the flat `actions` map routes one `action` value → one op.
+ *  - 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
+ *    `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.
+ */
+export interface CompositeToolDefinition {
+    /** Frozen public tool name (see tests/unit/mcp-tool-freeze.test.ts). */
+    toolName: string;
+    description: string;
+    /** Human-readable action list for the `action` enum description. */
+    actionSummary: string;
+    /**
+     * Map of `action` value → registry operation name (single-discriminator
+     * composites). Empty for two-discriminator composites. Every referenced op
+     * MUST have an `mcp` block — its `buildInput`/`formatResult` are reused so the
+     * composite action matches the legacy standalone tool exactly.
+     */
+    actions: Record<string, string>;
+    /**
+     * Two-discriminator extension (e.g. `canvas_ax_gate`). The extra discriminator
+     * shape — a single `kind` enum — merged into the advertised schema alongside
+     * `action`.
+     */
+    extraDiscriminatorShape?: ZodRawShape;
+    /**
+     * Two-discriminator extension: the action enum values (used to build the
+     * `action` discriminator when there is no flat `actions` map to derive it from).
+     */
+    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`).
+     */
+    memberOps?: string[];
+    /**
+     * Two-discriminator extension: resolve the op name from the validated
+     * discriminators. Returns `undefined` for an invalid combo so dispatch can
+     * raise a loud error instead of silently no-op'ing.
+     */
+    resolveOp?: (input: {
+        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
+     * field of the same name (e.g. `ax.approval.request` has its own `action`
+     * field — namespaced to `approvalAction` in the composite so the `action`
+     * discriminator wins, then mapped back before invoking the op). Keys are the
+     * composite (public) field names; values are the op field names.
+     */
+    fieldRemap?: Record<string, string>;
+}
+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.
+ */
+export declare function buildCompositeDeprecationNotes(definitions?: CompositeToolDefinition[]): Map<string, string>;

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

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,8 @@
+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 { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
+export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
+export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
+export { OperationError, defineOperation, type Operation, type OperationContext, type OperationDefinition, type OperationErrorStatus, } from './types.js';

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

@@ -0,0 +1,13 @@
+export interface OperationInvoker {
+    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+/** Runs operations in-process against the shared canvasState singleton. */
+export declare class LocalOperationInvoker implements OperationInvoker {
+    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+}
+/** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
+export declare class HttpOperationInvoker implements OperationInvoker {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+}

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

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { OperationInvoker } from './invoker.js';
+import { type OperationMcpToolHost } from './types.js';
+import { type CompositeToolDefinition } from './composites.js';
+export interface OperationToolHost extends OperationMcpToolHost {
+    invoker(): OperationInvoker;
+}
+export declare function registerOperationTools(server: McpServer, getHost: () => Promise<OperationToolHost>): void;
+/**
+ * Register composite (action-discriminated) MCP tools (plan-006). Each action
+ * dispatches to a registered operation, reusing that op's `mcp.buildInput` and
+ * `mcp.formatResult` so the composite action is byte-identical to the standalone
+ * tool it folds. Defaults to `compositeToolDefinitions`.
+ */
+export declare function registerCompositeTools(server: McpServer, getHost: () => Promise<OperationToolHost>, definitions?: CompositeToolDefinition[]): void;

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

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

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

@@ -0,0 +1,33 @@
+import { type ExternalMcpTransportConfig } from '../../mcp-app-runtime.js';
+import { type Operation, type OperationContext } from '../types.js';
+export interface OpenMcpAppCoreInput {
+    transport: ExternalMcpTransportConfig;
+    toolName: string;
+    toolArguments?: Record<string, unknown>;
+    nodeId?: string;
+    serverName?: string;
+    title?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    timeoutMs?: number;
+}
+export interface OpenMcpAppCoreResult {
+    ok: true;
+    id?: string;
+    nodeId: string | null;
+    toolCallId: string;
+    sessionId: string;
+    resourceUri: string;
+}
+/**
+ * Open an external MCP app: connect + call + read resource (openExternalMcpApp),
+ * close any prior session on an in-place node, emit `ext-app-open` +
+ * `ext-app-result`, then resolve the resulting canvas node id. This is the exact
+ * legacy SDK `openMcpApp` body, relocated; both the mcpapp.open op AND the SDK
+ * call it. The diagram.open op delegates here after building the Excalidraw input
+ * (the SSE pair fires ONCE — diagram.open does not re-emit).
+ */
+export declare function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationContext): Promise<OpenMcpAppCoreResult>;
+export declare const appOperations: Operation[];

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * Shared helpers for the AX operation modules (ax-state.ts, ax-work.ts, and the
+ * later timeline/delivery waves). These were replicated per-file during the
+ * plan-007 Slice B migration; centralizing them here keeps one definition site
+ * as more AX op files land.
+ *
+ * `normalizeAxSource` / `normalizeAxNodeIds` are reimplemented from server.ts
+ * because `operations/` must never import server.ts (the SSE emitter is injected;
+ * see plan-005). This module likewise must not import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { PmxAxSource } from '../../ax-state.js';
+export declare const AX_SOURCES: readonly ["agent", "api", "browser", "cli", "codex", "copilot", "mcp", "sdk", "system"];
+/** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
+export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
+    agent: "agent";
+    api: "api";
+    browser: "browser";
+    cli: "cli";
+    codex: "codex";
+    copilot: "copilot";
+    mcp: "mcp";
+    sdk: "sdk";
+    system: "system";
+}>>;
+/** An absent or unrecognized source falls back to the per-surface default. */
+export declare function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource;
+export declare function normalizeAxNodeIds(value: unknown): string[];
+/** The plain JSON tool result shared by AX ops whose MCP body is the wire body. */
+export declare function axJsonResult(result: unknown): CallToolResult;

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

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

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

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

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

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

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

@@ -0,0 +1,19 @@
+import { type Operation } from '../types.js';
+export interface BatchEnvelope {
+    ok: boolean;
+    results: Array<Record<string, unknown>>;
+    refs: Record<string, unknown>;
+    failedIndex?: number;
+    error?: string;
+}
+export declare const batchOperations: Operation[];
+/**
+ * Typed SDK entry point: run a batch through the registry's single execution
+ * path (`executeOperation('canvas.batch')`). The op emits the one final
+ * canvas-layout-update itself, so callers must NOT emit again.
+ */
+export declare function runCanvasBatchOperation(operations: Array<{
+    op: string;
+    assign?: string;
+    args?: Record<string, unknown>;
+}>): Promise<BatchEnvelope>;

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

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

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

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

package/dist/types/server/operations/ops/json-render.d.ts

@@ -0,0 +1,31 @@
+import { type Operation } from '../types.js';
+/** Legacy server.ts parseGraphPayloadData: a graph dataset must be an array of records. */
+export declare function parseGraphPayloadData(value: unknown): Array<Record<string, unknown>> | null;
+export interface StreamJsonRenderInput {
+    nodeId?: string;
+    title?: string;
+    patches?: unknown[];
+    done?: boolean;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    strictSize?: boolean;
+}
+export interface StreamJsonRenderResult {
+    id: string;
+    url: string;
+    ok: true;
+    applied: number;
+    skipped: number;
+    specVersion: number;
+    elementCount: number;
+    streamStatus: 'open' | 'closed';
+}
+/**
+ * Create-or-append core for streaming json-render nodes (the SDK's
+ * streamJsonRenderNode wraps this directly). Throws OperationError(400) when
+ * the append target is missing or not a json-render node.
+ */
+export declare function streamJsonRenderCore(input: StreamJsonRenderInput): StreamJsonRenderResult;
+export declare const jsonRenderOperations: Operation[];

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

@@ -0,0 +1,62 @@
+import { type CanvasLayout, type CanvasNodeState } from '../../canvas-state.js';
+import { type Operation } from '../types.js';
+export declare const NODE_TYPES: readonly ["markdown", "status", "context", "ledger", "trace", "file", "image", "mcp-app", "webpage", "html", "group"];
+/** Per-type default node frame size (formerly copy-pasted ladders). */
+export declare function defaultNodeSize(type: string): {
+    width: number;
+    height: number;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function pickFiniteNumber(record: Record<string, unknown>, key: string): number | undefined;
+export declare function getRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function pickPositiveNumber(record: Record<string, unknown>, key: string): number | undefined;
+export declare function resolveCreateGeometry(body: Record<string, unknown>): {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+};
+export declare function setGroupChildrenFromApi(groupId: string, childIds: string[]): boolean;
+export declare function nodeAppSessionId(node: CanvasNodeState | undefined): string | null;
+export declare function closeNodeAppSession(node: CanvasNodeState | undefined): void;
+export declare function buildNodeResponse(node: CanvasNodeState): Record<string, unknown>;
+export declare function wantsFullPayload(input?: Record<string, unknown>): boolean;
+export declare function compactNodePayload(node: CanvasNodeState | undefined): Record<string, unknown> | null;
+export declare function buildSummaryFromLayout(layout: CanvasLayout, pinnedIds: string[]): Record<string, unknown>;
+export declare function compactLayoutPayload(layout: CanvasLayout, pinnedIds: string[]): Record<string, unknown>;
+export declare function agentSafeFullLayoutPayload(layout: CanvasLayout): Record<string, unknown>;
+/**
+ * Node-create/update MCP payload: exposes both `id` and a `nodeId` alias so
+ * agents using either key (or a cached schema) work — matching the
+ * external-app / web-artifact responses that already return both.
+ */
+export declare function createdNodePayloadFromNode(node: CanvasNodeState, options?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create a basic (non-webpage / non-group / non-primitive) node. Union of the
+ * legacy handleCanvasAddNode generic branch; the SDK passes fileMode 'path',
+ * the HTTP/MCP operation passes fileMode 'auto'.
+ */
+export declare function createBasicCanvasNode(body: Record<string, unknown>, options: {
+    fileMode: 'auto' | 'path';
+}): {
+    node: CanvasNodeState;
+    needsCodeGraphRecompute: boolean;
+};
+/**
+ * Build a node patch with the full HTTP superset semantics (webpage
+ * titleSource, html top-level fields, axCapabilities merge, group children,
+ * structured spec/graph updates, trace fields). Throws OperationError on
+ * validation failures. The SDK's updateNode delegates here.
+ */
+export declare function buildNodePatch(existing: CanvasNodeState, body: Record<string, unknown>): {
+    patch: Partial<CanvasNodeState>;
+    groupChildIds?: string[];
+};
+/**
+ * Remove a node (closing any mcp-app session). Missing id → OperationError 404
+ * on ALL surfaces (plan-005 deliberately unifies the old silent local success).
+ */
+export declare function removeNodeCore(id: string): {
+    needsCodeGraphRecompute: boolean;
+};
+export declare const nodeOperations: Operation[];

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

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

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).