pmx-canvas 0.7.2 → 0.8.0

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 {

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 };
   },
 });
 

package/src/server/operations/registry.ts

@@ -12,8 +12,9 @@ import { canvasState } from '../canvas-state.js';
 import { intentRegistry } from '../intent-registry.js';
 import { humanPresence } from '../human-presence.js';
 import { withCurrentActor } from '../attribution.js';
+import { withoutExternalMcp } from '../mcp-app-runtime.js';
 import { agentPresence, describeWrite } from '../agent-presence.js';
-import { checkScopeFence, checkScopeOwnership } from '../scope-fence.js';
+import { checkScopeFence, checkScopeOwnership, describeOpTarget } from '../scope-fence.js';
 import { CONTEXT_READ_OPS, contextReadFromPayload } from '../context-reads.js';
 import { openBoardForWrite } from '../canvas-operations.js';
 import { boardsPayload } from './ops/boards.js';
@@ -108,6 +109,20 @@ function allowedIntentKinds(name: string, rawInput: unknown): readonly PmxAxInte
  * chunk is exactly the high-frequency churn class the batch exemption exists
  * for; the stream's CREATING call (no nodeId yet) still ghosts once.
  */
+/**
+ * A linked create that carries no x/y lands on its ghost, so the node appears
+ * where the human watched it form. A group built from children keeps the frame
+ * its children give it.
+ */
+function landOnGhost(name: string, rawInput: unknown, intentId: string): unknown {
+  if (!INTENT_KINDS_BY_OPERATION[name]?.includes('create')) return rawInput;
+  const input = asRecord(rawInput);
+  if (typeof input.x === 'number' || typeof input.y === 'number') return rawInput;
+  if (name === 'group.create' && Array.isArray(input.childIds) && input.childIds.length > 0) return rawInput;
+  const position = intentRegistry.list().find((intent) => intent.id === intentId)?.position;
+  return position ? { ...input, x: position.x, y: position.y } : rawInput;
+}
+
 function autoGhostExempt(name: string, rawInput: unknown): boolean {
   if (name !== 'jsonrender.stream') return false;
   const input =
@@ -238,6 +253,11 @@ function heldByHuman(name: string, rawInput: unknown): { nodeId: string; name: s
   if (locked.size === 0) return null;
   const input = asRecord(rawInput);
   const ids = [input.id, input.nodeId, input.groupId, input.from, input.to].filter(isString);
+  if (name === 'canvas.apply-updates' || name === 'node.update') {
+    // Fence and lock targets must agree, including translated children and
+    // the automatic parent frames re-fitted by a child write.
+    ids.push(...(describeOpTarget(getOperation(name), rawInput).nodeIds ?? []));
+  }
   if (MEMBERSHIP_OPS.has(name)) {
     for (const key of ['childIds', 'children']) {
       const list = input[key];
@@ -383,7 +403,12 @@ export async function executeOperation(
           ? (canvasState.readBoard(requestedBoard, false)?.state.contextPins ?? [])
           : [...canvasState.contextPinnedNodeIds]
         : [];
-      const result = await executeOperationInner(name, rawInput, meta);
+      const run = () => executeOperationInner(name, rawInput, meta);
+      // False is a caller-imposed restriction, never a grant of authority.
+      // DELETE invokers encode it as a query string.
+      const result = await (input.allowExternalMcp === false || input.allowExternalMcp === 'false'
+        ? withoutExternalMcp(run)
+        : run());
       if (recordRead) {
         canvasState.recordContextRead(
           contextReadFromPayload(
@@ -442,6 +467,14 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   if (TRUSTED_HUMAN_ONLY_OPS.has(name) && !meta.humanAuthor) {
     throw new OperationError('This action requires trusted human authority.', 403);
   }
+  // Embedded clients carry their captured board through the transport. Refuse
+  // stale writes before Home can auto-open a recent board or any mutation runs.
+  const rawExpectedBoard = asRecord(rawInput).expectedBoardId;
+  // HTTP DELETE query values are strings, including Home's JSON null.
+  const expectedBoard = rawExpectedBoard === 'null' ? null : rawExpectedBoard;
+  if (expectedBoard !== undefined && expectedBoard !== canvasState.activeBoardId) {
+    throw new OperationError('The active board changed. Refresh before retrying this action.', 409);
+  }
   // File drops carry their captured board through the HTTP round trip. Check
   // before opening a recent board from Home, not just before reading the file.
   const capturedBoard = asRecord(rawInput).boardId;
@@ -488,15 +521,16 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
     throw new OperationError(`Operation "${name}" cannot be committed through a ghost intent.`);
   }
   if (intentId) {
+    const input = landOnGhost(name, rawInput, intentId);
     return intentRegistry.runCommit(
       intentId,
       allowedKinds!,
       async () => {
-        const result = await op.execute(rawInput, operationContext);
+        const result = await op.execute(input, operationContext);
         if (op.mutates) {
           emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
         }
-        notePresence(name, rawInput, meta, op, result);
+        notePresence(name, input, meta, op, result);
         return result;
       },
       settledNodeId,

package/src/server/scope-fence.ts

@@ -25,6 +25,7 @@
  */
 import { type FenceRect, fenceRectFromNodes } from '../shared/scope-fence.js';
 import { canvasState } from './canvas-state.js';
+import { resolvePatchGeometry, validCanvasNodeUpdates } from './canvas-geometry.js';
 import type { Operation } from './operations/types.js';
 
 /** Bounding box of the fenced nodes plus padding; null when none of them exist. */
@@ -103,6 +104,48 @@ function groupChildren(input: Record<string, unknown>): string[] {
   return 'children' in data ? stringList(data.children) : [];
 }
 
+/** Automatic frames are write targets when their descendants can cause a re-fit.
+ * Conservatively include them even if the resulting bounds happen to be equal.
+ * A manual frame does not re-fit, so propagation stops there. */
+function includeAutoFrameParents(nodeIds: string[]): string[] {
+  const targets = new Set(nodeIds);
+  for (const id of targets) {
+    const parentId = canvasState.getNode(id)?.data.parentGroup;
+    if (typeof parentId !== 'string') continue;
+    const parent = canvasState.getNode(parentId);
+    if (parent?.type === 'group' && parent.data.frameMode !== 'manual') targets.add(parentId);
+  }
+  return [...targets];
+}
+
+/** `canvasState.applyUpdates`: group moves translate children unless that child has its own position update. */
+function applyUpdatesTarget(input: Record<string, unknown>): FenceTarget {
+  const updates = validCanvasNodeUpdates(input.updates);
+  const explicitPositionIds = new Set(
+    updates.filter((update) => update.position !== undefined).map((update) => update.id),
+  );
+  const nodeIds: string[] = [];
+  const points: Array<{ x: number; y: number }> = [];
+  for (const update of updates) {
+    const id = update.id;
+    nodeIds.push(id);
+    if (!update.position) continue;
+    const { x, y } = update.position;
+    points.push({ x, y });
+    const node = canvasState.getNode(id);
+    if (node?.type !== 'group') continue;
+    const deltaX = x - node.position.x;
+    const deltaY = y - node.position.y;
+    for (const childId of stringList(node.data.children)) {
+      if (explicitPositionIds.has(childId)) continue;
+      nodeIds.push(childId);
+      const child = canvasState.getNode(childId);
+      if (child) points.push({ x: child.position.x + deltaX, y: child.position.y + deltaY });
+    }
+  }
+  return { nodeIds: includeAutoFrameParents(nodeIds), points };
+}
+
 function createTarget(input: Record<string, unknown>, extraNodeIds: string[] = []): FenceTarget {
   const x = Number(input.x);
   const y = Number(input.y);
@@ -118,17 +161,19 @@ export function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget
   const input = asRecord(rawInput);
   if (BOARD_WIDE_OPS.has(op.name)) return { boardWide: true };
   switch (op.name) {
+    case 'canvas.apply-updates':
+      return applyUpdatesTarget(input);
     case 'node.update': {
-      // A group's membership change reparents (and may reposition) its children.
-      const nodeIds = [str(input.id), ...groupChildren(input)];
-      // A move's DESTINATION must also land inside the fence — otherwise an
-      // agent relocates a fenced node outward, and since the fence rect is
-      // derived from live node positions, that grows its own writable region
-      // past the human-seeded region.
-      const x = Number(input.x);
-      const y = Number(input.y);
-      if (Number.isFinite(x) && Number.isFinite(y)) return { points: [{ x, y }], nodeIds };
-      return { nodeIds };
+      const id = str(input.id);
+      const existing = canvasState.getNode(id);
+      const geometry = existing ? resolvePatchGeometry(input, existing) : {};
+      // Share the bulk translation rules after resolving PATCH aliases and
+      // omitted axes. Check children's destinations as well as the group origin.
+      const target = applyUpdatesTarget({ updates: [{ id, ...geometry }] });
+      return {
+        ...target,
+        nodeIds: includeAutoFrameParents([id, ...(target.nodeIds ?? []), ...groupChildren(input)]),
+      };
     }
     case 'node.remove':
       return { nodeIds: [str(input.id)] };

package/src/server/server.ts

@@ -62,8 +62,10 @@ import { getMcpAppHostSnapshot } from './mcp-app-host.js';
 import { closeMcpAppSession, closeAllMcpAppSessions } from './mcp-app-runtime.js';
 import { findOpenCanvasPosition } from './placement.js';
 import { overlapsAny } from '../shared/placement.js';
+import { CANVAS_APP_WRITE_CONTRACT } from '../shared/canvas-app.js';
+import { withoutExternalMcp } from './mcp-app-runtime.js';
 import { mutationHistory } from './mutation-history.js';
-import { buildAgentContextPreamble } from './agent-context.js';
+import { buildAgentContextPreamble } from '../shared/agent-context.js';
 import { buildCanvasAxSurfaceSnapshot } from './ax-context.js';
 import { resolveNodeAxCapabilities } from './ax-interaction.js';
 import { normalizeCanvasTheme, type CanvasTheme } from './canvas-db.js';
@@ -145,20 +147,27 @@ agentPresence.setSessionStartListener((presence) => {
   const startedAt = new Date().toISOString();
   return canvasState.saveSnapshot(`Before session · ${presence.label} · ${startedAt.slice(11, 16)}`)?.id ?? null;
 });
-agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
+agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy, startedAt) => {
   const ax = canvasState.getAxState();
   const endedAt = new Date().toISOString();
+  const layout = canvasState.getLayout();
   let snapshot = startSnapshotId
     ? (canvasState.listSnapshots({ all: true }).find((entry) => entry.id === startSnapshotId) ?? null)
     : null;
-  let unchanged = !startSnapshotId && canvasState.getLayout().nodes.length === 0;
+  let unchanged = !startSnapshotId && layout.nodes.length === 0;
+  // Nodes the session added and changed: the diff against the start snapshot,
+  // or every node when the board was empty at attach (no snapshot was taken).
+  let addedIds = startSnapshotId ? new Set<string>() : new Set(layout.nodes.map((node) => node.id));
+  let modifiedIds = new Set<string>();
   // A session that changed NOTHING on the board leaves no snapshot behind —
   // session churn (idle timeouts, receipt tests, attach/detach cycles) was
   // flooding the History drawer with identical boards.
   if (snapshot) {
     const snapData = canvasState.getSnapshotData(snapshot.id);
     if (snapData) {
-      const diff = diffLayouts(snapData.name, snapData, canvasState.getLayout());
+      const diff = diffLayouts(snapData.name, snapData, layout);
+      addedIds = new Set(diff.addedNodes.map((node) => node.id));
+      modifiedIds = new Set(diff.modifiedNodes.map((node) => node.id));
       if (
         diff.addedNodes.length === 0 &&
         diff.removedNodes.length === 0 &&
@@ -188,6 +197,10 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
     rejected: ax.approvalGates.filter((gate) => gate.status === 'rejected').length,
     held: ax.approvalGates.filter((gate) => gate.status === 'held').length,
   };
+  const context = sessionContextActivity(layout.nodes, startedAt, addedIds, modifiedIds);
+  // Reading or pinning is something the human wants to see even when the
+  // board itself did not change ("did the agent read what I pinned?").
+  if (context.read.length > 0 || context.pinned.length > 0) unchanged = false;
   // No agent `sessionId` here: the SSE envelope reserves that key for the
   // workbench session and would overwrite it. The label is what the receipt shows.
   emitPrimaryWorkbenchEvent('agent-session-ended', {
@@ -198,9 +211,63 @@ agentPresence.setSessionEndListener((presence, startSnapshotId, endedBy) => {
     counts,
     unchanged,
     snapshot: snapshot ? { id: snapshot.id, name: snapshot.name } : null,
+    context,
   });
 });
 
+interface ReceiptNode {
+  id: string;
+  title: string;
+  reason?: string;
+}
+
+/**
+ * What an agent session did with the board's context (docs/design/AgentContext.dc.html
+ * lens and receipt): nodes read since it attached, pins it made, nodes it created and
+ * edited, and pinned nodes whose content changed after the latest read.
+ */
+function sessionContextActivity(
+  nodes: CanvasNodeState[],
+  startedAt: string | null,
+  addedIds: Set<string>,
+  modifiedIds: Set<string>,
+): {
+  read: ReceiptNode[];
+  pinned: ReceiptNode[];
+  created: ReceiptNode[];
+  edited: ReceiptNode[];
+  changedSinceRead: ReceiptNode[];
+} {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const entry = (node: CanvasNodeState): ReceiptNode => ({
+    id: node.id,
+    title: typeof node.data.title === 'string' && node.data.title.trim() ? node.data.title : node.id,
+  });
+  const boardId = canvasState.activeBoardId;
+  const read = startedAt
+    ? canvasState.getReadNodeIdsSince(boardId, startedAt).flatMap((id) => {
+        const node = byId.get(id);
+        return node ? [entry(node)] : [];
+      })
+    : [];
+  const pinned = Object.entries(canvasState.getContextPinMeta()).flatMap(([id, meta]) => {
+    const node = byId.get(id);
+    if (!node || meta.pinnedBy.actor !== 'agent' || !startedAt || meta.pinnedAt < startedAt) return [];
+    return [{ ...entry(node), ...(meta.reason ? { reason: meta.reason } : {}) }];
+  });
+  const created = nodes.filter((node) => addedIds.has(node.id) && node.createdBy?.actor === 'agent').map(entry);
+  const edited = nodes.filter((node) => modifiedIds.has(node.id) && node.lastEditedBy?.actor === 'agent').map(entry);
+  const readStatus = new Map(canvasState.getNodeReadStatus(boardId).map((status) => [status.nodeId, status]));
+  const changedSinceRead = [...canvasState.contextPinnedNodeIds].flatMap((id) => {
+    const node = byId.get(id);
+    const status = readStatus.get(id);
+    // Only pins this session read: the receipt says "changed after <agent> read it".
+    const readThisSession = status && startedAt !== null && status.lastReadAt >= startedAt;
+    return node && status && readThisSession && (node.contentRevision ?? 0) > status.readRevision ? [entry(node)] : [];
+  });
+  return { read, pinned, created, edited, changedSinceRead };
+}
+
 // Webview-runner wiring (plan-008 Wave 3): the webview ops never import this
 // module — the Bun.WebView automation runner is injected here, mirroring the
 // setOperationEventEmitter pattern. The closures call the real automation
@@ -1181,6 +1248,7 @@ const CANVAS_STATIC_MIME: Record<string, string> = {
   '.json': 'application/json',
   '.map': 'application/json',
   '.wasm': 'application/wasm',
+  '.woff2': 'font/woff2',
 };
 
 const CANVAS_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
@@ -1737,10 +1805,12 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   const html = await buildJsonRenderViewerHtml({
     title,
     spec,
+    nodeId,
+    stateToken: url.searchParams.get('stateToken') ?? undefined,
     ...(theme ? { theme } : {}),
     ...(display ? { display } : {}),
     ...(devtoolsEnabled ? { devtools: true } : {}),
-    ...(axToken ? { nodeId, axToken } : {}),
+    ...(axToken ? { axToken } : {}),
     // Seed the read-side AX state (only for AX-enabled nodes) so specs can bind /ax.
     ...(axToken && axEnabled ? { axState: buildCanvasAxSurfaceSnapshot() } : {}),
     // Content-fit: report natural height (charts render intrinsic) so the node grows.
@@ -3261,6 +3331,7 @@ export interface CanvasServerOptions {
   workspaceRoot?: string;
   autoOpenBrowser?: boolean;
   allowPortFallback?: boolean;
+  allowExternalMcp?: boolean;
 }
 
 export function startCanvasServer(options: CanvasServerOptions = {}): string | null {
@@ -3279,6 +3350,12 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
     primaryWorkbenchAutoOpenEnabled = options.autoOpenBrowser;
   }
 
+  // A recorded agent read changes what the workbench marks as read; tell the
+  // browser only (an MCP notification would make a read cause more reads).
+  canvasState.setContextReadListener((boardId) => {
+    emitPrimaryWorkbenchEvent('context-status-changed', { boardId });
+  });
+
   // Ensure direct HTTP server usage records undo/redo history, not just PmxCanvas.start().
   canvasState.onMutation((info) => {
     mutationHistory.record({
@@ -3302,7 +3379,9 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
   if (loaded) {
     console.log('  Canvas state restored from .pmx-canvas/canvas.db');
     primeCanvasRuntimeBackends({ forceRehydrateExtApps: true });
-    void syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true }).finally(() => {
+    const rehydrate = () => syncCanvasRuntimeBackends({ forceRehydrateExtApps: true, alreadyPrimed: true });
+    const pending = options.allowExternalMcp === false ? withoutExternalMcp(rehydrate) : rehydrate();
+    void pending.finally(() => {
       emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
     });
   }
@@ -3359,6 +3438,7 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
               workspace: activeWorkspaceRoot,
               pid: process.pid,
               version: serverPackageVersion(),
+              contracts: [CANVAS_APP_WRITE_CONTRACT],
               persistence: canvasState.persistenceHealth,
             });
           }

package/src/server/spatial-analysis.ts

@@ -11,7 +11,7 @@
  */
 
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge } from './canvas-state.js';
-import { summarizeNodeForAgentContext } from './agent-context.js';
+import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -73,7 +73,7 @@ export interface SpatialContext {
 // ── Helpers ──────────────────────────────────────────────────────────
 
 /** Euclidean distance between two node centers */
-function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number {
+export function centerDistance(a: CanvasNodeState, b: CanvasNodeState): number {
   const ax = a.position.x + a.size.width / 2;
   const ay = a.position.y + a.size.height / 2;
   const bx = b.position.x + b.size.width / 2;

package/src/server/workboard.ts

@@ -77,7 +77,12 @@ export function buildWorkboardSpec(workItems: PmxAxWorkItem[]): JsonRenderSpec {
         };
         cardChildren.push(`${cardId}-detail`);
       }
-      elements[cardId] = { type: 'Card', props: { title: item.title }, children: cardChildren };
+      // wrap-anywhere: an unbreakable token in a title must wrap, not spill into the next column.
+      elements[cardId] = {
+        type: 'Card',
+        props: { title: item.title, className: 'wrap-anywhere' },
+        children: cardChildren,
+      };
       columnChildren.push(cardId);
     }
     elements[columnId] = {

package/src/{server → shared}/agent-context.ts

@@ -1,5 +1,5 @@
-import type { CanvasNodeState } from './canvas-state.js';
-import { getCanvasNodeKind } from '../shared/canvas-node-kind.js';
+import type { CanvasNodeState } from '../server/canvas-state.js';
+import { getCanvasNodeKind } from './canvas-node-kind.js';
 
 const DEFAULT_CONTEXT_TEXT_LENGTH = 700;
 const DEFAULT_WEBPAGE_CONTEXT_TEXT_LENGTH = 1600;