pmx-canvas 0.7.3 → 0.8.0

package/dist/types/client/state/session-store.d.ts

@@ -155,12 +155,13 @@ export declare function endSession(session: {
     agentId: string | null;
 }): Promise<boolean>;
 export interface SessionReceipt {
-    label: string;
+    /** Distinct labels of the sessions on this card (one unless merged). */
+    labels: string[];
+    /** Endings folded into this card (see applySessionReceipt). */
+    sessions: number;
     endedAt: string;
     /** Why it ended — the receipt should answer this, not leave the human asking. */
     endedBy?: 'human' | 'agent' | 'idle-timeout';
-    /** The session changed nothing on the board (its pre-session snapshot was dropped). */
-    unchanged?: boolean;
     /** Cancelled (withdrawn items), rejected (human's explicit no on a gate), and
      * held (TTL expired unanswered) are three different outcomes — never one
      * "vetoed" pile. */
@@ -171,13 +172,42 @@ export interface SessionReceipt {
         rejected: number;
         held: number;
     };
+    /** The pre-session snapshot; null when the board was empty at attach, or on a
+     * merged receipt (each session's snapshot is in History). */
     snapshot: {
         id: string;
         name: string;
     } | null;
+    /** What the session did with context (docs/design/AgentContext.dc.html receipt). */
+    context: SessionContextActivity;
+}
+export interface ReceiptNode {
+    id: string;
+    title: string;
+    reason?: string;
+}
+export interface SessionContextActivity {
+    read: ReceiptNode[];
+    pinned: ReceiptNode[];
+    created: ReceiptNode[];
+    edited: ReceiptNode[];
+    changedSinceRead: ReceiptNode[];
 }
+/**
+ * The agent-activity lens: while on, nodes the last session did not touch
+ * (read, pin, create, edit) are dimmed. Null when off.
+ */
+export declare const activityLensNodeIds: import("@preact/signals-core").Signal<Set<string> | null>;
+export declare function setActivityLens(on: boolean): void;
 /** The last ended session's receipt (design item 2); client-side, cleared on dismiss. */
 export declare const sessionReceipt: import("@preact/signals-core").Signal<SessionReceipt | null>;
+/**
+ * The receipt rule: a pop-up only for a top-level session that changed the
+ * board or read/pinned context. `unchanged` endings and worker endings
+ * (`parentAgentId` set — their orchestrator's receipt covers the board since
+ * it attached) stay in the timeline and History only, and never replace or
+ * extend an open receipt. Qualifying endings while one is up merge into it.
+ */
 export declare function applySessionReceipt(data: Record<string, unknown>): void;
 export declare function dismissSessionReceipt(): void;
 export declare function resetSessionStore(): void;

package/dist/types/client/state/workbench-transport.d.ts

@@ -0,0 +1,16 @@
+/** The normal workbench uses HTTP; an MCP App installs its host transport before mounting. */
+type WorkbenchFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare function installWorkbenchTransport(transport: WorkbenchFetch | undefined): void;
+export declare function isHostedWorkbench(): boolean;
+export declare const workbenchFetch: WorkbenchFetch;
+type WorkbenchDownload = (file: {
+    name: string;
+    mimeType: string;
+    text: string;
+}) => Promise<{
+    isError?: boolean;
+}>;
+export declare function installWorkbenchDownload(download: WorkbenchDownload | undefined): void;
+/** Export files live on PMX, not on the embedded frame's sandbox origin. */
+export declare function downloadWorkbenchExport(path: string): Promise<void>;
+export {};

package/dist/types/client/theme/tokens.d.ts

@@ -11,10 +11,8 @@ export interface CanvasTokens {
     accent: string;
     ok: string;
     warn: string;
-    warnAlt: string;
     danger: string;
-    purple: string;
-    thinking: string;
+    agent: string;
     subagent: string;
     font: string;
     mono: string;

package/dist/types/client/types.d.ts

@@ -18,8 +18,17 @@ export interface CanvasNodeState {
     zIndex: number;
     collapsed: boolean;
     pinned: boolean;
+    contentRevision?: number;
+    /** Who created / last edited the node's content (server attribution). */
+    createdBy?: NodeActor;
+    lastEditedBy?: NodeActor;
     data: Record<string, unknown>;
 }
+export interface NodeActor {
+    actor: 'human' | 'agent' | 'system' | 'unknown';
+    source: string;
+    agentId?: string;
+}
 export interface CanvasEdge {
     id: string;
     from: string;

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

@@ -66,7 +66,7 @@ export type GraphChartType = 'LineChart' | 'BarChart' | 'PieChart' | 'AreaChart'
 export declare function escapeInlineScriptSource(source: string): string;
 export declare function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback?: string): string;
 export declare function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec;
-/** shadcn 0.21 ignores these props unless the renderer supplies a two-way binding. */
+/** Binding-only form props that normalization could not bind (see bindLiteralFormValues). */
 export declare function jsonRenderFormWarnings(spec: JsonRenderSpec): string[];
 export declare function normalizeGraphType(value: string): GraphChartType;
 export declare function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec;

package/dist/types/mcp/app-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Private, single-workspace profile. No public HTTP listener or tenant routing. */
+export declare function createCanvasAppServer(): McpServer;

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

@@ -88,5 +88,5 @@ export declare function shouldAttachToExistingDaemon(occupant: {
  * FS-safe (defaults to false on any error).
  */
 export declare function looksLikeIncidentalCwd(cwd: string): boolean;
-export declare function createCanvasAccess(): Promise<CanvasAccess>;
+export declare function createCanvasAccess(allowExternalMcp?: boolean): Promise<CanvasAccess>;
 export {};

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

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanvasAccess } from './canvas-access.js';
+/** Focused app profile; deliberately does not register the general-purpose composites. */
+export declare function registerCanvasApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void;

package/dist/types/mcp/workbench-app.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanvasAccess } from './canvas-access.js';
+/** HTTP-shaped replies let the real workbench retain its existing API contracts. */
+export declare function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void;

package/dist/types/server/agent-presence.d.ts

@@ -99,7 +99,7 @@ export declare function estimateContextBudget(): ContextBudget;
 /** Returns the id of the pre-session snapshot the server took, if any. */
 type SessionStartListener = (presence: AgentPresence) => string | null;
 export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
-type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason) => void;
+type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason, startedAt: string | null) => void;
 export declare class AgentPresenceRegistry {
     private readonly presences;
     /** Newest first; bounded. Survives a writer fading — the feed is history, the writer list is presence. */

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

@@ -1,6 +1,6 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
-import type { AgentContextNode } from './agent-context.js';
+import type { AgentContextNode } from '../shared/agent-context.js';
 import type { ActorAttribution } from './attribution.js';
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 export interface PmxAxFocusState {

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

@@ -5,6 +5,7 @@
  * WAL-mode persistence. Replaces the previous JSON file-based approach.
  */
 import { Database } from 'bun:sqlite';
+import type { ActorAttribution } from './attribution.js';
 import { type Tour } from '../shared/tour.js';
 import { type CanvasThemeName } from '../shared/themes.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
@@ -20,9 +21,16 @@ export interface PersistedCanvasState {
     edges: CanvasEdge[];
     annotations?: CanvasAnnotation[];
     contextPins: string[];
+    /** Who pinned each context pin, when and why; pins without an entry have an unknown pinner. */
+    contextPinMeta?: Record<string, ContextPinMeta>;
     ax?: PmxAxState;
     revisionState?: PersistedRevisionState;
 }
+export interface ContextPinMeta {
+    pinnedBy: ActorAttribution;
+    pinnedAt: string;
+    reason?: string;
+}
 export interface PersistedRevisionState {
     revision: number;
     floor: number;

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

@@ -0,0 +1,25 @@
+import type { CanvasNodeState, CanvasNodeUpdate } from './canvas-state.js';
+/** Flat fields take precedence over nested aliases; absent axes remain absent. */
+export declare function resolveCreateGeometry(body: Record<string, unknown>): {
+    x: number | undefined;
+    y: number | undefined;
+    width: number | undefined;
+    height: number | undefined;
+};
+/** Guards and PATCH execution must resolve aliases and single-axis moves identically. */
+export declare function resolvePatchGeometry(body: Record<string, unknown>, existing: CanvasNodeState): {
+    size?: {
+        width: number;
+        height: number;
+    } | undefined;
+    position?: {
+        x: number;
+        y: number;
+    } | undefined;
+};
+export declare function validateCanvasNodePatch(patch: {
+    position?: unknown;
+    size?: unknown;
+}): string | null;
+/** Invalid patches cannot count as explicit child-position overrides. */
+export declare function validCanvasNodeUpdates(input: unknown): CanvasNodeUpdate[];

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

@@ -130,16 +130,6 @@ export declare function syncCanvasRuntimeBackends(options?: {
     rehydrated: number;
     failed: number;
 }>;
-export declare function validateCanvasNodePatch(patch: {
-    position?: {
-        x: number;
-        y: number;
-    };
-    size?: {
-        width: number;
-        height: number;
-    };
-}): string | null;
 export declare function mergeTraceNodeDataFields(base: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown>;
 export declare function hasTraceNodeDataFields(input: Record<string, unknown>): boolean;
 export declare function scheduleCodeGraphRecompute(onComplete?: () => void): void;
@@ -189,7 +179,7 @@ export declare function applyCanvasNodeUpdates(updates: CanvasNodeUpdate[]): {
     applied: number;
     skipped: number;
 };
-export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPinMode): {
+export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPinMode, reason?: string): {
     count: number;
     nodeIds: string[];
 };

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

@@ -12,11 +12,11 @@
  * the one-shot boot migration into SQLite was retired.
  */
 import { type Tour } from '../shared/tour.js';
-import { type CanvasBoard, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type CanvasBoard, type ContextPinMeta, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
 import { type DocumentImport, type DocumentImportStatus, type ImportSection, type Attachment } from './document-import.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 import { type ActorAttribution } from './attribution.js';
-import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput } from './context-reads.js';
+import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput, type NodeReadStatus } from './context-reads.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -171,6 +171,8 @@ declare class CanvasStateManager {
     private _tour;
     private _theme;
     private _contextPinnedNodeIds;
+    /** Who pinned each pin, when and why; kept only for ids in `_contextPinnedNodeIds`. */
+    private _contextPinMeta;
     private _workspaceRoot;
     private _contentRevision;
     private _revisionFloor;
@@ -185,12 +187,15 @@ declare class CanvasStateManager {
      */
     onChange(cb: (type: CanvasChangeType) => void): () => void;
     private _workItemsChangedListener;
+    /** Single slot (architecture rule 8): server.ts tells the workbench a read landed. Never MCP. */
+    private _contextReadListener;
     /**
      * Register THE work-item change listener (single slot, last-write-wins).
      * Fired after addWorkItem/updateWorkItem completes (including the node
      * status mirror), so live views like the workboard can rebuild from the
      * fresh work-item list.
      */
+    setContextReadListener(listener: ((boardId: string | null) => void) | null): void;
     setWorkItemsChangedListener(listener: (() => void) | null): void;
     private notifyWorkItemsChanged;
     private notifyChange;
@@ -609,6 +614,12 @@ declare class CanvasStateManager {
     getAxTimelineSummary(): PmxAxTimelineSummary;
     /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
     recordContextRead(input: ContextReadInput, boardId?: string | null): ContextRead | null;
+    /** The delivered ids that are nodes on the read board, each with its content revision now. */
+    private readRevisions;
+    /** Per node on a board, the latest agent read that delivered its content. */
+    getNodeReadStatus(boardId?: string | null): NodeReadStatus[];
+    /** Nodes on a board whose content an agent read at or after `since` (ISO). */
+    getReadNodeIdsSince(boardId: string | null, since: string): string[];
     getContextReads(limit?: number): {
         reads: ContextRead[];
         summary: ContextReadConsumerSummary[];
@@ -619,7 +630,18 @@ declare class CanvasStateManager {
         steering: PmxAxSteeringMessage[];
         summary: PmxAxTimelineSummary;
     };
-    setContextPins(nodeIds: string[]): void;
+    /**
+     * Replace the pin set. Newly pinned nodes are attributed to the current
+     * actor (with `reason` when given); pins that stay keep their attribution.
+     * `restore` re-applies saved attribution, so undo does not re-attribute.
+     */
+    setContextPins(nodeIds: string[], options?: {
+        reason?: string;
+        restore?: Map<string, ContextPinMeta>;
+    }): void;
+    /** Who pinned each current pin, when and why (pins with an unknown pinner are absent). */
+    getContextPinMeta(): Record<string, ContextPinMeta>;
+    private pinMetaRecord;
     clearContextPins(): void;
     /** Move child nodes into a group. Sets data.parentGroup on children and data.children on the group. */
     groupNodes(groupId: string, childIds: string[], options?: GroupNodesOptions): boolean;

package/dist/types/server/context-brief.d.ts

@@ -1,5 +1,7 @@
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
-export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export type ContextBriefReason = 'pinned' | 'near' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+/** A near entry carries a short summary, never full content: pin the node to send that. */
+export declare const NEAR_SUMMARY_LENGTH = 280;
 export interface ContextBriefSourceEntry {
     sourceBoardId: string;
     nodeId: string;
@@ -57,6 +59,11 @@ export interface CompiledContextEntry {
     text: string;
     /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
     titleOnly?: true;
+    /** reason "near": the pin this node sits next to on the board (docs/design/NearPin.dc.html). */
+    near?: {
+        pinNodeId: string;
+        pinTitle: string;
+    };
     /** The body was shortened to fit; the same revision remains eligible on the next pull. */
     truncated?: true;
     provenance?: {

package/dist/types/server/context-reads.d.ts

@@ -22,14 +22,29 @@ export interface ContextRead {
     agentId: string | null;
     pinnedNodeIds: string[];
     deliveredNodeIds: string[];
+    /** Every node on the read board whose content was delivered, with its content revision at read time. */
+    readNodes: Record<string, number>;
     bytes: number;
     /** The board open when the read happened (null on Home). */
     boardId: string | null;
 }
-export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId' | 'readNodes'> & {
     /** Explicit read target, captured before asynchronous formatting/proxy work. */
     boardId?: string | null;
+    /** Ids of every serialized node in what the reader received; the server keeps those on the board. */
+    readNodeIds?: string[];
 };
+/** One node's read state on a board: the latest agent read that delivered its content. */
+export interface NodeReadStatus {
+    nodeId: string;
+    lastReadAt: string;
+    /** Who read it: consumer, else agent id, else transport label. */
+    lastReadBy: string;
+    /** The node's content revision in that read; newer current revision means "changed since read". */
+    readRevision: number;
+    /** How many retained agent reads delivered its content. */
+    readCount: number;
+}
 export interface ContextReadConsumerSummary {
     consumer: string;
     reads: number;
@@ -39,14 +54,22 @@ export interface ContextReadConsumerSummary {
     resources: Record<string, number>;
 }
 /**
- * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
- * what the reader received. A bare id list, a title, or a clipped-off node does
- * not count — the agent got the pin's name, not its content.
+ * Ids of every serialized node (an object carrying `"id": "<id>"`, or a
+ * `nodeId` with its text) in what the reader received. A bare id list, a
+ * title, or a clipped-off node does not count — the agent got the node's
+ * name, not its content. Non-node ids (edges, intents) are dropped by the
+ * caller against the board's nodes.
  */
+export declare function deliveredIds(payloadText: string): Set<string>;
+/** Pinned nodes whose content is in what the reader received (see `deliveredIds`). */
 export declare function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[];
-export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>, payload: unknown): ContextReadInput;
-export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT\n  );\n";
-export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead;
+export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes' | 'readNodeIds'>, payload: unknown): ContextReadInput;
+export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT,\n    read_nodes TEXT NOT NULL DEFAULT '{}'\n  );\n";
+export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null, readNodes?: Record<string, number>): ContextRead;
+/** Per node on a board, the latest agent read that delivered its content (newest row wins). */
+export declare function loadNodeReadStatusFromDB(db: Database, boardId: string): NodeReadStatus[];
+/** Every node on a board whose content an agent read at or after `since` (ISO). */
+export declare function loadReadNodeIdsSince(db: Database, boardId: string, since: string): string[];
 /** Newest first. The summary covers every retained row, not just the returned page. */
 export declare function loadContextReadsFromDB(db: Database, limit?: number): {
     reads: ContextRead[];

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

@@ -42,6 +42,8 @@ export declare class PmxCanvas extends EventEmitter {
     start(options?: {
         open?: boolean;
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
+        /** Embedded startup must not launch external MCP backends from saved nodes. */
+        allowExternalMcp?: boolean;
         /**
          * Bind a nearby free port when the preferred one is taken instead of
          * failing. Default false (an explicit SDK port is honored exactly); the
@@ -293,6 +295,8 @@ export declare class PmxCanvas extends EventEmitter {
     restoreBackup(file: string): Promise<void>;
     /** The context read log: which canvas context each agent read and which pinned nodes reached it. */
     getContextReads(limit?: number): ReturnType<typeof canvasState.getContextReads>;
+    /** Per node on a board: when an agent last read its content, who, and the content revision it read. */
+    getNodeReadStatus(board?: string): ReturnType<typeof canvasState.getNodeReadStatus>;
     listWorkItems(): PmxAxWorkItem[];
     addWorkItem(input: {
         title: string;
@@ -519,7 +523,8 @@ export declare class PmxCanvas extends EventEmitter {
         applied: number;
         skipped: number;
     };
-    setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove'): {
+    /** `reason` is kept with newly pinned nodes and shown to the human on hover. */
+    setContextPins(nodeIds: string[], mode?: 'set' | 'add' | 'remove', reason?: string): {
         count: number;
         nodeIds: string[];
     };

package/dist/types/server/mcp-app-runtime.d.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, ListToolsResult, ReadResourceResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { McpUiResourceMeta } from '@modelcontextprotocol/ext-apps';
+export declare function withoutExternalMcp<T>(run: () => T): T;
 export interface ExternalMcpHttpTransportConfig {
     type: 'http';
     url: string;

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

@@ -1,3 +1,4 @@
+export declare function matchOperationPath(template: string, pathname: string): Record<string, string> | null;
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,
  * or primitive) — per-op `readInput` decides what to do with non-object
@@ -5,4 +6,5 @@
  * parse is a 400 (OperationError), never a silent empty input.
  */
 export declare function readJsonValue(req: Request): Promise<unknown>;
+export declare function readOperationInput(req: Request, params: Record<string, string>, url: URL): Promise<Record<string, unknown>>;
 export declare function dispatchOperationRoute(req: Request, url: URL): Promise<Response | null>;

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

@@ -9,18 +9,20 @@ export interface OperationInvoker {
 export declare function agentSourceLabel(fallback: string): string;
 /** Runs operations in-process against the shared canvasState singleton. */
 export declare class LocalOperationInvoker implements OperationInvoker {
+    private readonly allowExternalMcp;
     private readonly source;
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
-    constructor(source?: string);
+    constructor(source?: string, allowExternalMcp?: boolean);
     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 allowExternalMcp;
     private readonly baseUrl;
     private readonly source;
     private readonly proxiedRead;
     /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
-    constructor(baseUrl: string, source?: string);
+    constructor(baseUrl: string, source?: string, allowExternalMcp?: boolean);
     invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown>;
 }

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

@@ -11,12 +11,6 @@ export declare function isRecord(value: unknown): value is Record<string, unknow
 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;

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

@@ -108,6 +108,7 @@ export interface CanvasServerOptions {
     workspaceRoot?: string;
     autoOpenBrowser?: boolean;
     allowPortFallback?: boolean;
+    allowExternalMcp?: boolean;
 }
 export declare function startCanvasServer(options?: CanvasServerOptions): string | null;
 export declare function stopCanvasServer(): void;

package/dist/types/server/spatial-analysis.d.ts

@@ -68,6 +68,8 @@ export interface SpatialContext {
     }[];
     annotations: SpatialAnnotationContext[];
 }
+/** Euclidean distance between two node centers */
+export declare function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number;
 /**
  * Detect proximity clusters using single-linkage clustering.
  * Two nodes are "close" if their edge-to-edge gap is within the threshold.

package/dist/types/shared/agent-context.d.ts

@@ -0,0 +1,22 @@
+import type { CanvasNodeState } from '../server/canvas-state.js';
+export interface AgentContextNode {
+    id: string;
+    type: CanvasNodeState['type'];
+    kind: string;
+    title: string | null;
+    content: string | null;
+    metadata?: Record<string, unknown>;
+    position?: {
+        x: number;
+        y: number;
+    };
+}
+interface AgentContextOptions {
+    defaultTextLength?: number;
+    webpageTextLength?: number;
+    includePosition?: boolean;
+}
+export declare function summarizeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): string;
+export declare function serializeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): AgentContextNode;
+export declare function buildAgentContextPreamble(nodes: CanvasNodeState[], options?: AgentContextOptions): string;
+export {};

package/dist/types/shared/agent-presence.d.ts

@@ -1,7 +1,7 @@
 /**
- * Agent presence — the contract behind every agent surface in the rail chrome
- * (rail-chrome-v2 phase 2). Shared by server and client so the two cannot
- * drift. See design/rail-chrome-v2/PLAN.md, "Phase 2 contract".
+ * Agent presence — the contract behind every agent surface in the rail chrome.
+ * Shared by server and client so the two cannot drift. See
+ * docs/ax-state-contract.md, "Agent presence (contract)".
  *
  * Presence is DERIVED from feeds that already exist (AX activity ingest,
  * agent-originated mutations) plus an explicit set for adapters with richer
@@ -121,10 +121,3 @@ export declare function externalWriters(presences: readonly AgentPresence[]): Ag
 export declare function estimateTokens(text: string): number;
 /** Chip label per phase — shared by the top-bar chip and the on-canvas cursor chip. */
 export declare function agentPhaseLabel(presence: Pick<AgentPresence, 'phase' | 'detail'>): string;
-/**
- * Stable per-agent identity hue (0-359) from the writer key. Phase colors
- * kept telling the human WHAT an agent is doing while erasing WHO — two
- * thinking agents rendered identically. Identity rides the glyph/border;
- * phase stays on dots and labels.
- */
-export declare function agentIdentityHue(key: string): number;

package/dist/types/shared/canvas-app.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const CANVAS_APP_URI = "ui://pmx/canvas";
+export declare const CANVAS_APP_WRITE_CONTRACT = "pmx-embedded-workbench-v4";
+export declare const canvasAppSnapshotSchema: z.ZodObject<{
+    boardId: z.ZodNullable<z.ZodString>;
+    boardName: z.ZodString;
+    boards: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    revision: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodString;
+        text: z.ZodString;
+        contentRevision: z.ZodNumber;
+        editableContent: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        size: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        image: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    pinnedNodeIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CanvasAppSnapshot = z.infer<typeof canvasAppSnapshotSchema>;
+/** Share only curated text, never image bytes or the whole board's contents. */
+export declare function canvasAppContext(snapshot: Pick<CanvasAppSnapshot, 'boardId' | 'boardName' | 'pinnedNodeIds'> & {
+    nodes: Pick<CanvasAppSnapshot['nodes'][number], 'id' | 'type' | 'title' | 'text' | 'contentRevision'>[];
+}, selectedIds: string[], focusedIds?: string[]): {
+    boardId: string | null;
+    boardName: string;
+    selectedNodeIds: string[];
+    focusedNodeIds: string[];
+    pinnedNodeIds: string[];
+    nodes: {
+        id: string;
+        type: string;
+        title: string;
+        contentRevision: number;
+        text: string;
+    }[];
+};

package/dist/types/shared/themes.d.ts

@@ -9,7 +9,7 @@
  * theme picker, server validation, and surface documents pick it up from this
  * list.
  */
-export declare const CANVAS_THEMES: readonly ["dark", "light", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest", "volt"];
+export declare const CANVAS_THEMES: readonly ["harbor", "daylight", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest", "volt"];
 export type CanvasThemeName = (typeof CANVAS_THEMES)[number];
 export declare function isCanvasTheme(value: unknown): value is CanvasThemeName;
 export declare function normalizeCanvasThemeName(value: unknown, fallback?: CanvasThemeName): CanvasThemeName;