pmx-canvas 0.7.3 → 0.8.2

package/src/server/mcp-app-runtime.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
@@ -18,6 +19,13 @@ import type { McpUiClientCapabilities, McpUiResourceCsp, McpUiResourceMeta } fro
 import { getToolUiResourceUri } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 
+// A restriction follows async rehydration spawned by an embedded operation,
+// without disabling independent requests from the local workbench.
+const externalMcpDisabled = new AsyncLocalStorage<boolean>();
+export function withoutExternalMcp<T>(run: () => T): T {
+  return externalMcpDisabled.run(true, run);
+}
+
 export interface ExternalMcpHttpTransportConfig {
   type: 'http';
   url: string;
@@ -210,6 +218,9 @@ async function createSession(
   serverName?: string,
   timeoutMs?: number,
 ): Promise<McpAppSession> {
+  if (externalMcpDisabled.getStore()) {
+    throw new Error('Open external MCP apps from the local PMX workbench; embedded actions cannot launch them.');
+  }
   const transport = buildTransport(transportConfig);
   const client = new Client({ name: 'pmx-canvas-app-host', version: '0.1.0' }, { capabilities: clientCapabilities });
   await client.connect(transport, requestOptions(timeoutMs));

package/src/server/operations/composites.ts

@@ -323,14 +323,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_ax_timeline',
     description:
-      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message); "reads" returns the context read log — which canvas context each agent read and which pinned nodes reached it — with a per-consumer summary (limit). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
-    actionSummary: 'read | record-event | add-evidence | send-steering | reads',
+      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message); "reads" returns the context read log — which canvas context each agent read and which pinned nodes reached it — with a per-consumer summary (limit); "read-status" returns, per node on a board, when an agent last read its content, who, and the content revision it read (board). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
+    actionSummary: 'read | record-event | add-evidence | send-steering | reads | read-status',
     actions: {
       read: 'ax.timeline.get',
       'record-event': 'ax.event.record',
       'add-evidence': 'ax.evidence.add',
       'send-steering': 'ax.steer',
       reads: 'ax.reads.list',
+      'read-status': 'ax.reads.status',
     },
   },
   {
@@ -346,7 +347,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_intent',
     description:
-      'Ghost Cursor of Intent — announce the spatial move you are ABOUT to make so the canvas paints a faint pre-commit placeholder (legibility: the human sees the next move forming, and can veto it). Action "signal" registers an intent (kind create|move|connect|remove|edit; pass position for create/move, nodeId for move/edit/remove, edge for connect; optional label, reason, confidence 0..1, seq, ttlMs, and a stable id); "update" patches a live intent by id; "clear" abandons/dissolves it. To make veto authoritative, pass the returned id as intentId on the real canvas_node/canvas_edge/canvas_group/canvas_render mutation: vetoed or expired intents are rejected, and a successful linked mutation settles the ghost automatically. Intents are ephemeral presence: never persisted, never snapshotted, auto-expire (~8s).',
+      'Ghost Cursor of Intent — announce the spatial move you are ABOUT to make so the canvas paints a faint pre-commit placeholder (legibility: the human sees the next move forming, and can veto it). Action "signal" registers an intent (kind create|move|connect|remove|edit; pass position for move — omit it for create to ghost where the canvas will place the node, and the linked create lands there — nodeId for move/edit/remove, edge for connect; optional label, reason, confidence 0..1, seq, ttlMs, and a stable id); "update" patches a live intent by id; "clear" abandons/dissolves it. To make veto authoritative, pass the returned id as intentId on the real canvas_node/canvas_edge/canvas_group/canvas_render mutation: vetoed or expired intents are rejected, and a successful linked mutation settles the ghost automatically. Intents are ephemeral presence: never persisted, never snapshotted, auto-expire (~8s).',
     actionSummary: 'signal | update | clear',
     actions: {
       signal: 'intent.signal',

package/src/server/operations/http.ts

@@ -20,7 +20,7 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
-function matchPath(template: string, pathname: string): Record<string, string> | null {
+export function matchOperationPath(template: string, pathname: string): Record<string, string> | null {
   const templateSegments = template.split('/');
   const pathSegments = pathname.split('/');
   if (templateSegments.length !== pathSegments.length) return null;
@@ -58,7 +58,7 @@ export async function readJsonValue(req: Request): Promise<unknown> {
   }
 }
 
-async function defaultReadInput(
+export async function readOperationInput(
   req: Request,
   params: Record<string, string>,
   url: URL,
@@ -80,12 +80,12 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
   for (const op of listOperations()) {
     const route = op.http;
     if (!route || route.method !== req.method) continue;
-    const params = matchPath(route.path, url.pathname);
+    const params = matchOperationPath(route.path, url.pathname);
     if (!params) continue;
     try {
       const input = route.readInput
         ? await route.readInput(req, params, url)
-        : await defaultReadInput(req, params, url);
+        : await readOperationInput(req, params, url);
       // The workbench marks its own HTTP calls: a human dragging/editing in
       // the browser is not agent activity, so it never synthesizes an
       // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.

package/src/server/operations/invoker.ts

@@ -32,13 +32,17 @@ export class LocalOperationInvoker implements OperationInvoker {
   private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
-  constructor(source = 'api') {
+  constructor(
+    source = 'api',
+    private readonly allowExternalMcp = true,
+  ) {
     this.source = agentSourceLabel(source);
     this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
-    return await executeOperation(name, defaultPresenceSource(name, input, this.source), {
+    const args = this.allowExternalMcp ? input : { ...input, allowExternalMcp: false };
+    return await executeOperation(name, defaultPresenceSource(name, args, this.source), {
       source: this.source,
       proxiedRead: this.proxiedRead,
     });
@@ -56,14 +60,19 @@ export class HttpOperationInvoker implements OperationInvoker {
   private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
-  constructor(baseUrl: string, source = 'api') {
+  constructor(
+    baseUrl: string,
+    source = 'api',
+    private readonly allowExternalMcp = true,
+  ) {
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.source = agentSourceLabel(source);
     this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
-    const input = defaultPresenceSource(name, rawInput, this.source);
+    const args = this.allowExternalMcp ? rawInput : { ...rawInput, allowExternalMcp: false };
+    const input = defaultPresenceSource(name, args, this.source);
     const op = getOperation(name);
     const route = op.http;
     if (!route) throw new OperationError(`Operation "${name}" has no HTTP route.`, 400);

package/src/server/operations/mcp.ts

@@ -43,6 +43,12 @@ async function invokeMcpOperation(
       .filter((item): item is Extract<(typeof formatted.content)[number], { type: 'text' }> => item.type === 'text')
       .map((item) => item.text)
       .join('');
+    if (op.name === 'node.get') {
+      // Compact responses can still deliver text. Metadata without text or
+      // data must not mark unseen content read.
+      const node = JSON.parse(text) as { data?: unknown; content?: string | null };
+      if (node.data === undefined && !node.content) return formatted;
+    }
     try {
       await host.recordContextRead(
         contextReadFromPayload(

package/src/server/operations/ops/ax-read.ts

@@ -13,7 +13,7 @@
  */
 import { agentPresence } from '../../agent-presence.js';
 import { z } from 'zod';
-import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../agent-context.js';
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from '../../ax-context.js';
 import { applyAxInteraction } from '../../ax-interaction.js';
 import {

package/src/server/operations/ops/ax-timeline.ts

@@ -502,6 +502,10 @@ const axReadsRecordShape = {
   source: z.string().optional().describe('Transport label (default "api").'),
   pinnedNodeIds: z.array(z.string()).optional().describe('Pins at read time; defaults to the current pins.'),
   deliveredNodeIds: z.array(z.string()).describe('Pinned ids present in what the agent received.'),
+  readNodeIds: z
+    .array(z.string())
+    .optional()
+    .describe('Ids of every serialized node in what the agent received; defaults to deliveredNodeIds.'),
   bytes: z.number().int().nonnegative().describe('Size of what the agent received.'),
   boardId: z.string().nullable().optional().describe('Board that was read, captured before delivery.'),
 };
@@ -527,6 +531,7 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
         agentId: input.agentId ?? null,
         pinnedNodeIds: input.pinnedNodeIds ?? [...canvasState.contextPinnedNodeIds],
         deliveredNodeIds: input.deliveredNodeIds,
+        ...(input.readNodeIds ? { readNodeIds: input.readNodeIds } : {}),
         bytes: input.bytes,
       },
       input.boardId === undefined ? canvasState.activeBoardId : input.boardId,
@@ -535,6 +540,37 @@ const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchem
   },
 });
 
+const axReadsStatusShape = {
+  board: z.string().optional().describe('Board id; defaults to the open board.'),
+};
+const axReadsStatusSchema = z.looseObject(axReadsStatusShape);
+
+/**
+ * Per node: when an agent last read its content, who, and at which revision
+ * (vs the node's revision now); and per pin: who pinned it, when and why.
+ */
+const axReadsStatusOperation = defineOperation<z.infer<typeof axReadsStatusSchema>, Record<string, unknown>>({
+  name: 'ax.reads.status',
+  mutates: false,
+  input: axReadsStatusSchema,
+  inputShape: axReadsStatusShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/context-status',
+  },
+  handler: (input) => {
+    const boardId =
+      typeof input.board === 'string' && input.board.trim() ? input.board.trim() : canvasState.activeBoardId;
+    const pins =
+      boardId === canvasState.activeBoardId
+        ? canvasState.getContextPinMeta()
+        : boardId
+          ? (canvasState.readBoard(boardId, false)?.state.contextPinMeta ?? {})
+          : {};
+    return { ok: true, boardId, nodes: canvasState.getNodeReadStatus(boardId), pins };
+  },
+});
+
 export const axTimelineOperations: Operation[] = [
   axEventRecordOperation,
   axEvidenceAddOperation,
@@ -545,4 +581,5 @@ export const axTimelineOperations: Operation[] = [
   axCommandInvokeOperation,
   axReadsListOperation,
   axReadsRecordOperation,
+  axReadsStatusOperation,
 ];

package/src/server/operations/ops/boards.ts

@@ -15,7 +15,7 @@ import { z } from 'zod';
 import { normalizeBoardCategory } from '../../../shared/boards.js';
 import { canvasState, type CanvasLayout } from '../../canvas-state.js';
 import { openCanvasBoard } from '../../canvas-operations.js';
-import { summarizeNodeForAgentContext } from '../../agent-context.js';
+import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
 
 export function boardsPayload(): Record<string, unknown> {

package/src/server/operations/ops/canvas-wire.ts

@@ -70,15 +70,15 @@ const applyUpdatesSchema = z.looseObject(applyUpdatesShape);
 
 const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>, Record<string, unknown>>({
   name: 'canvas.apply-updates',
-  mutates: false,
+  mutates: true,
   input: applyUpdatesSchema,
   inputShape: applyUpdatesShape,
   http: {
     method: 'POST',
     path: '/api/canvas/update',
   },
-  // Legacy wire: one layout update only when something actually applied.
-  handler: (input, ctx) => {
+  // The registry emits the layout update, as for other mutating operations.
+  handler: (input) => {
     const body: Record<string, unknown> = input;
     const updates = Array.isArray(body.updates) ? body.updates : [];
     const result =
@@ -94,9 +94,6 @@ const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>
             return suppressedResult;
           })()
         : applyCanvasNodeUpdates(updates);
-    if (result.applied > 0) {
-      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
-    }
     return { ok: true, ...result };
   },
 });

package/src/server/operations/ops/intent.ts

@@ -15,9 +15,12 @@
  */
 import { z } from 'zod';
 import { INTENT_EDGE_TYPES, INTENT_KINDS } from '../../../shared/ax-intent.js';
+import { canvasState } from '../../canvas-state.js';
 import { intentRegistry } from '../../intent-registry.js';
+import { findOpenCanvasPosition } from '../../placement.js';
 import { readJsonValue } from '../http.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
+import { defaultNodeSize } from './nodes.js';
 
 const positionShape = z.object({ x: z.number(), y: z.number() });
 
@@ -28,7 +31,11 @@ const intentSignalShape = {
     .enum(INTENT_KINDS)
     .optional()
     .describe('create | move | connect | remove | edit — the move about to be made.'),
-  position: positionShape.optional().describe('World coords: where a create forms, or the destination of a move.'),
+  position: positionShape
+    .optional()
+    .describe(
+      'World coords: the destination of a move, or where a create forms. Omit it for a create to ghost where the canvas will place the node.',
+    ),
   nodeId: z.string().optional().describe('The existing node a move/edit/remove targets.'),
   edge: z
     .object({ from: z.string(), to: z.string(), type: z.enum(INTENT_EDGE_TYPES) })
@@ -46,6 +53,24 @@ const intentSignalShape = {
 
 const intentSignalSchema = z.looseObject(intentSignalShape);
 
+/**
+ * Where a create without a position will land: the same auto-placement the
+ * create ops use, with live create ghosts as obstacles so staged ghosts do not
+ * stack. An agent announcing work before it knows the layout must not have to
+ * guess a position (a guessed 0,0 put every first ghost in the top-left corner).
+ */
+function openPositionForCreate(nodeType: unknown): { x: number; y: number } {
+  const size = defaultNodeSize(typeof nodeType === 'string' ? nodeType : 'markdown');
+  const ghosts = intentRegistry
+    .list()
+    .flatMap((intent) =>
+      intent.kind === 'create' && intent.position
+        ? [{ position: intent.position, size: defaultNodeSize(intent.nodeType ?? 'markdown') }]
+        : [],
+    );
+  return findOpenCanvasPosition([...canvasState.getLayout().nodes, ...ghosts], size.width, size.height);
+}
+
 const intentSignalOperation = defineOperation<z.infer<typeof intentSignalSchema>, Record<string, unknown>>({
   name: 'intent.signal',
   mutates: false,
@@ -53,7 +78,11 @@ const intentSignalOperation = defineOperation<z.infer<typeof intentSignalSchema>
   inputShape: intentSignalShape,
   http: { method: 'POST', path: '/api/canvas/ax/intent' },
   handler: (input) => {
-    const intent = intentRegistry.signal(input);
+    const placed =
+      input.kind === 'create' && !input.position
+        ? { ...input, position: openPositionForCreate(input.nodeType) }
+        : input;
+    const intent = intentRegistry.signal(placed);
     return { ok: true, intent } as unknown as Record<string, unknown>;
   },
 });

package/src/server/operations/ops/json-render.ts

@@ -50,8 +50,8 @@ import {
   isRecord,
   pickFiniteNumber,
   pickPositiveNumber,
-  resolveCreateGeometry,
 } from './nodes.js';
+import { resolveCreateGeometry } from '../../canvas-geometry.js';
 
 /** Legacy server.ts parseGraphPayloadData: a graph dataset must be an array of records. */
 export function parseGraphPayloadData(value: unknown): Array<Record<string, unknown>> | null {
@@ -309,7 +309,11 @@ const jsonRenderStreamOperation = defineOperation<z.infer<typeof jsonRenderStrea
       // node degrades to the bare { ok, id, nodeId } payload.
       let created: Record<string, unknown> = { ok: true, id, nodeId: id };
       try {
-        const node = (await host.invoker().invoke('node.get', { id, includeBlobs: true })) as CanvasNodeState;
+        const node = (await host.invoker().invoke('node.get', {
+          id,
+          includeBlobs: true,
+          contextDelivery: false,
+        })) as CanvasNodeState;
         created = { ok: true, node: compactNodePayload(node), id, nodeId: id };
       } catch {
         // keep the bare payload (legacy c.getNode → undefined path)

package/src/server/operations/ops/nodes.ts

@@ -22,13 +22,13 @@ import {
   removeCanvasNode,
   resolveHtmlContent,
   scheduleCodeGraphRecompute,
-  validateCanvasNodePatch,
   MARKDOWN_NODE_DEFAULT_SIZE,
   MCP_APP_NODE_DEFAULT_SIZE,
   IMAGE_NODE_DEFAULT_SIZE,
   LEDGER_NODE_DEFAULT_SIZE,
   type CanvasSizeAdjustment,
 } from '../../canvas-operations.js';
+import { resolveCreateGeometry, resolvePatchGeometry, validateCanvasNodePatch } from '../../canvas-geometry.js';
 import { normalizeNodeAxCapabilities } from '../../ax-interaction.js';
 import { applyFileContentToNodeData, readFileNodeContent } from '../../file-content.js';
 import { unwatchFileForNode, watchFileForNode } from '../../file-watcher.js';
@@ -126,81 +126,6 @@ export function pickPositiveNumber(record: Record<string, unknown>, key: string)
   return value !== undefined && value > 0 ? value : undefined;
 }
 
-function normalizeGeometryInput(body: Record<string, unknown>): {
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
-  position?: { x?: number; y?: number };
-  size?: { width?: number; height?: number };
-} {
-  const position = getRecord(body.position);
-  const size = getRecord(body.size);
-  return {
-    ...(pickFiniteNumber(body, 'x') !== undefined ? { x: pickFiniteNumber(body, 'x') } : {}),
-    ...(pickFiniteNumber(body, 'y') !== undefined ? { y: pickFiniteNumber(body, 'y') } : {}),
-    ...(pickFiniteNumber(body, 'width') !== undefined ? { width: pickFiniteNumber(body, 'width') } : {}),
-    ...(pickFiniteNumber(body, 'height') !== undefined ? { height: pickFiniteNumber(body, 'height') } : {}),
-    ...(position
-      ? {
-          position: {
-            ...(pickFiniteNumber(position, 'x') !== undefined ? { x: pickFiniteNumber(position, 'x') } : {}),
-            ...(pickFiniteNumber(position, 'y') !== undefined ? { y: pickFiniteNumber(position, 'y') } : {}),
-          },
-        }
-      : {}),
-    ...(size
-      ? {
-          size: {
-            ...(pickFiniteNumber(size, 'width') !== undefined ? { width: pickFiniteNumber(size, 'width') } : {}),
-            ...(pickFiniteNumber(size, 'height') !== undefined ? { height: pickFiniteNumber(size, 'height') } : {}),
-          },
-        }
-      : {}),
-  };
-}
-
-export function resolveCreateGeometry(body: Record<string, unknown>): {
-  x?: number;
-  y?: number;
-  width?: number;
-  height?: number;
-} {
-  const geometry = normalizeGeometryInput(body);
-  const x = geometry.x ?? geometry.position?.x;
-  const y = geometry.y ?? geometry.position?.y;
-  const width = geometry.width ?? geometry.size?.width;
-  const height = geometry.height ?? geometry.size?.height;
-  return {
-    ...(x !== undefined ? { x } : {}),
-    ...(y !== undefined ? { y } : {}),
-    ...(width !== undefined ? { width } : {}),
-    ...(height !== undefined ? { height } : {}),
-  };
-}
-
-function resolvePatchGeometry(
-  body: Record<string, unknown>,
-  existing: CanvasNodeState,
-): {
-  position?: { x: number; y: number };
-  size?: { width: number; height: number };
-} {
-  const geometry = normalizeGeometryInput(body);
-  const x = geometry.x ?? geometry.position?.x;
-  const y = geometry.y ?? geometry.position?.y;
-  const width = geometry.width ?? geometry.size?.width;
-  const height = geometry.height ?? geometry.size?.height;
-  return {
-    ...(x !== undefined || y !== undefined
-      ? { position: { x: x ?? existing.position.x, y: y ?? existing.position.y } }
-      : {}),
-    ...(width !== undefined || height !== undefined
-      ? { size: { width: width ?? existing.size.width, height: height ?? existing.size.height } }
-      : {}),
-  };
-}
-
 type StringListField = { value?: string[]; error?: string };
 
 function parseStringListField(field: string, value: unknown): StringListField {
@@ -1057,6 +982,7 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
 
 const nodeUpdateShape = {
   id: z.string().describe('Node ID to update'),
+  expectedContentRevision: z.number().int().nonnegative().optional().describe('Reject an edit based on stale content'),
   intentId: z
     .string()
     .optional()
@@ -1199,6 +1125,12 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
     const id = input.id;
     const existing = canvasState.getNode(id);
     if (!existing) throw new OperationError(`Node "${id}" not found.`, 404);
+    if (input.expectedContentRevision !== undefined) {
+      if (body.refresh === true) throw new OperationError('Conditional edits do not support webpage refresh.');
+      if (input.expectedContentRevision !== (existing.contentRevision ?? 0)) {
+        throw new OperationError('This node changed. Reopen the editor before saving your changes.', 409);
+      }
+    }
     if (existing.type === 'webpage' && body.refresh === true) {
       const rawUrl = typeof body.url === 'string' ? body.url : undefined;
       let url: string | undefined;

package/src/server/operations/ops/query.ts

@@ -28,7 +28,7 @@ import {
   type ContextBriefLibraryBoard,
   type ContextBriefSourceEntry,
 } from '../../context-brief.js';
-import { summarizeNodeForAgentContext } from '../../agent-context.js';
+import { summarizeNodeForAgentContext } from '../../../shared/agent-context.js';
 import { defineOperation, OperationError, type Operation, type OperationMcpToolHost } from '../types.js';
 import { buildSummaryFromLayout, isRecord } from './nodes.js';
 import { readTargetBoard } from './boards.js';
@@ -46,6 +46,7 @@ const pinShape = {
     .unknown()
     .optional()
     .describe('set: replace all pins, add: add to existing pins, remove: unpin these nodes (default: set)'),
+  reason: z.unknown().optional().describe('Why these nodes matter; kept with newly pinned nodes and shown on hover.'),
 };
 
 const pinSchema = z.looseObject(pinShape);
@@ -69,6 +70,10 @@ const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, u
         .enum(['set', 'add', 'remove'])
         .optional()
         .describe('set: replace all pins, add: add to existing pins, remove: unpin these nodes (default: set)'),
+      reason: z
+        .string()
+        .optional()
+        .describe('Why these nodes matter; kept with newly pinned nodes and shown to the human on hover.'),
     },
     // The wire body is { ok, count } (legacy HTTP shape); the tool reports the
     // resulting pin list, so re-read it from the host. (Legacy RemoteCanvasAccess
@@ -91,7 +96,8 @@ const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, u
     // Legacy 'set' capped at MAX_PINS BEFORE setCanvasContextPins dedupes —
     // replicated as-is. add/remove (formerly client-side in the MCP access
     // layer) pass through; setCanvasContextPins normalizes them.
-    const result = setCanvasContextPins(mode === 'set' ? nodeIds.slice(0, MAX_PINS) : nodeIds, mode);
+    const reason = typeof body.reason === 'string' && body.reason.trim() ? body.reason.trim().slice(0, 280) : undefined;
+    const result = setCanvasContextPins(mode === 'set' ? nodeIds.slice(0, MAX_PINS) : nodeIds, mode, reason);
     ctx.emit('context-pins-changed', { count: result.count, nodeIds: result.nodeIds });
     return { ok: true, count: result.count };
   },

package/src/server/operations/ops/snapshots.ts

@@ -318,7 +318,7 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
       };
     },
   },
-  handler: async ({ id }) => {
+  handler: async ({ id }, ctx) => {
     // Awaits only the synchronous restore; restoreCanvasSnapshot fires the
     // async ext-app rehydration itself and schedules a deferred
     // canvas-layout-update through setCanvasLayoutUpdateEmitter when it
@@ -326,6 +326,9 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
     // add a manual emit here or the frame is doubled.
     const result = await restoreCanvasSnapshot(id ?? '');
     if (!result.ok) throw new OperationError('Snapshot not found', 404);
+    const nodeIds = [...canvasState.contextPinnedNodeIds];
+    ctx.emit('context-pins-changed', { count: nodeIds.length, nodeIds });
+    ctx.emit('ax-state-changed', {});
     return { ok: true };
   },
 });

package/src/server/operations/ops/viewport.ts

@@ -15,7 +15,13 @@
 import { z } from 'zod';
 import { tourSchema, derivedTour } from '../../../shared/tour.js';
 import { canvasState } from '../../canvas-state.js';
-import { arrangeCanvasNodes, clearCanvas, fitCanvasView, setClientViewportSize } from '../../canvas-operations.js';
+import {
+  arrangeCanvasNodes,
+  clearCanvas,
+  fitCanvasView,
+  getClientViewportSize,
+  setClientViewportSize,
+} from '../../canvas-operations.js';
 import { validateCanvasLayout } from '../../canvas-validation.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { closeNodeAppSession, isRecord } from './nodes.js';
@@ -230,6 +236,10 @@ const viewportSetShape = {
   x: z.unknown().optional().describe('Viewport x offset'),
   y: z.unknown().optional().describe('Viewport y offset'),
   scale: z.unknown().optional().describe('Viewport zoom scale'),
+  center: z
+    .unknown()
+    .optional()
+    .describe('World point {x, y} to centre in the canvas area (instead of x/y); uses scale or the current zoom'),
   recordHistory: z.unknown().optional().describe('Pass false to skip the undo-history entry'),
   clientWidth: z.unknown().optional().describe("The reporting client's window width in CSS pixels"),
   clientHeight: z.unknown().optional().describe("The reporting client's window height in CSS pixels"),
@@ -255,12 +265,26 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
     setClientViewportSize(body.clientWidth, body.clientHeight);
     // A size-only report is not a camera command. Echoing the stored camera
     // here would cancel an in-flight browser focus with its stale fallback.
-    if (![body.x, body.y, body.scale].some((value) => typeof value === 'number')) return { ok: true };
-    const next = {
+    const center = body.center;
+    if (center === undefined && ![body.x, body.y, body.scale].some((value) => typeof value === 'number'))
+      return { ok: true };
+    const scale = typeof body.scale === 'number' ? body.scale : canvasState.viewport.scale;
+    let next = {
       x: typeof body.x === 'number' ? body.x : canvasState.viewport.x,
       y: typeof body.y === 'number' ? body.y : canvasState.viewport.y,
-      scale: typeof body.scale === 'number' ? body.scale : canvasState.viewport.scale,
+      scale,
     };
+    if (center !== undefined) {
+      if (!isRecord(center) || typeof center.x !== 'number' || typeof center.y !== 'number') {
+        throw new OperationError('center must be a world point {x, y}.');
+      }
+      if (body.x !== undefined || body.y !== undefined) throw new OperationError('Pass center or x/y, not both.');
+      // Screen-space translate (architecture rule 9): put the world point at
+      // the middle of the canvas area the browser last reported (fit's default
+      // size when no tab has reported one).
+      const area = getClientViewportSize() ?? { width: 1440, height: 900 };
+      next = { x: area.width / 2 - center.x * scale, y: area.height / 2 - center.y * scale, scale };
+    }
     if (body.recordHistory === false) {
       canvasState.withSuppressedRecording(() => {
         canvasState.setViewport(next);
@@ -269,7 +293,7 @@ const viewportSetOperation = defineOperation<z.infer<typeof viewportSetSchema>,
       canvasState.setViewport(next);
     }
     ctx.emit('canvas-viewport-update', { viewport: canvasState.viewport });
-    return { ok: true };
+    return { ok: true, viewport: canvasState.viewport };
   },
 });