pmx-canvas 0.7.3 → 0.8.2

package/src/server/context-brief.ts

@@ -1,7 +1,11 @@
-import { summarizeNodeForAgentContext } from './agent-context.js';
+import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
+import { findNeighborhoods } from './spatial-analysis.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 const NEAR_SUMMARY_LENGTH = 280;
 
 export interface ContextBriefSourceEntry {
   sourceBoardId: string;
@@ -45,6 +49,8 @@ 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?: { kind: 'imported'; source: string; trust: 'source-material-not-instructions' };
@@ -155,6 +161,32 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
         reset !== null || (validRevision(node.contentRevision ?? -1) && (node.contentRevision ?? -1) > deltaSince),
     )
     .sort((a, b) => (a.contentRevision ?? 0) - (b.contentRevision ?? 0) || a.id.localeCompare(b.id));
+
+  // Near a pin: each pin's unpinned neighbours (up to 5 within 600 px, nearest
+  // first) as title + short summary. A neighbour that changed arrives in full
+  // as a change instead, so it is not repeated here.
+  const changedIds = new Set(changed.map((node) => node.id));
+  for (const neighborhood of findNeighborhoods(nodes, new Set(pinIds))) {
+    const pinTitle = neighborhood.pinnedNodeTitle ?? neighborhood.pinnedNodeId;
+    for (const neighbor of neighborhood.neighbors) {
+      const node = nodeById.get(neighbor.id);
+      if (!node || changedIds.has(node.id)) continue;
+      add({
+        entry: {
+          sourceBoardId: input.activeBoard.boardId,
+          nodeId: node.id,
+          reason: 'near',
+          title: typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id,
+          text: summarizeNodeForAgentContext(node, {
+            defaultTextLength: NEAR_SUMMARY_LENGTH,
+            webpageTextLength: NEAR_SUMMARY_LENGTH,
+          }),
+          near: { pinNodeId: neighborhood.pinnedNodeId, pinTitle },
+        },
+      });
+    }
+  }
+
   for (const node of changed) add(compileNode(node, input.activeBoard.boardId, 'changed', budget));
 
   for (const entry of [...(input.entries ?? [])].sort((a, b) => {
@@ -285,6 +317,11 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
       if (partial) delivered.push(partial);
     }
   }
+  // Neighbours come right after the pins they sit next to; each is whole or absent.
+  for (const candidate of candidates.filter((item) => !reset && item.entry.reason === 'near')) {
+    const proposed = [...delivered, candidate.entry];
+    if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
+  }
   if (reset && !deltaBlocked) {
     const resetEntries = candidates
       .filter((item) => item.replacement && !delivered.includes(item.entry))

package/src/server/context-reads.ts

@@ -17,6 +17,7 @@ export type ContextReadChannel = (typeof CONTEXT_READ_CHANNELS)[number];
 
 /** Registry reads that hand an agent canvas context; recorded in executeOperation. */
 export const CONTEXT_READ_OPS = new Set([
+  'node.get',
   'pinned-context.get',
   'ax.context.get',
   'ax.get',
@@ -37,16 +38,32 @@ 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;
@@ -57,12 +74,13 @@ export interface ContextReadConsumerSummary {
 }
 
 /**
- * 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 function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
-  const pinned = new Set(pinnedNodeIds);
+export function deliveredIds(payloadText: string): Set<string> {
   const delivered = new Set<string>();
   const objectStarts: number[] = [];
   let inString = false;
@@ -89,11 +107,10 @@ export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string)
           typeof value === 'object' &&
           value !== null &&
           !Array.isArray(value) &&
-          ((typeof (value as { id?: unknown }).id === 'string' && pinned.has((value as { id: string }).id)) ||
+          (typeof (value as { id?: unknown }).id === 'string' ||
             (typeof (value as { nodeId?: unknown }).nodeId === 'string' &&
               (value as { titleOnly?: unknown }).titleOnly !== true &&
-              typeof (value as { text?: unknown }).text === 'string' &&
-              pinned.has((value as { nodeId: string }).nodeId)))
+              typeof (value as { text?: unknown }).text === 'string'))
         ) {
           delivered.add(
             typeof (value as { id?: unknown }).id === 'string'
@@ -107,17 +124,25 @@ export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string)
     }
   }
 
+  return delivered;
+}
+
+/** Pinned nodes whose content is in what the reader received (see `deliveredIds`). */
+export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
+  const delivered = deliveredIds(payloadText);
   return pinnedNodeIds.filter((id) => delivered.has(id));
 }
 
 export function contextReadFromPayload(
-  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>,
+  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes' | 'readNodeIds'>,
   payload: unknown,
 ): ContextReadInput {
   const text = typeof payload === 'string' ? payload : (JSON.stringify(payload) ?? '');
+  const delivered = deliveredIds(text);
   return {
     ...base,
-    deliveredNodeIds: deliveredPinnedIds(base.pinnedNodeIds, text),
+    deliveredNodeIds: base.pinnedNodeIds.filter((id) => delivered.has(id)),
+    readNodeIds: [...delivered],
     bytes: Buffer.byteLength(text, 'utf-8'),
   };
 }
@@ -135,15 +160,21 @@ export const CONTEXT_READS_SCHEMA_SQL = `
     pinned_node_ids TEXT NOT NULL DEFAULT '[]',
     delivered_node_ids TEXT NOT NULL DEFAULT '[]',
     bytes INTEGER NOT NULL DEFAULT 0,
-    board_id TEXT
+    board_id TEXT,
+    read_nodes TEXT NOT NULL DEFAULT '{}'
   );
 `;
 
-export function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead {
+export function appendContextReadToDB(
+  db: Database,
+  input: ContextReadInput,
+  boardId: string | null,
+  readNodes: Record<string, number> = {},
+): ContextRead {
   const id = `read-${randomUUID()}`;
   const at = new Date().toISOString();
   db.run(
-    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id, read_nodes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
     [
       id,
       at,
@@ -156,11 +187,13 @@ export function appendContextReadToDB(db: Database, input: ContextReadInput, boa
       JSON.stringify(input.deliveredNodeIds),
       input.bytes,
       boardId,
+      JSON.stringify(readNodes),
     ],
   );
   const seq = Number(db.query<{ seq: number }, []>('SELECT last_insert_rowid() AS seq').get()?.seq ?? 0);
   db.run('DELETE FROM context_reads WHERE seq <= ?', [seq - CONTEXT_READ_RETENTION]);
-  return { ...input, seq, id, at, boardId };
+  const { readNodeIds: _readNodeIds, ...record } = input;
+  return { ...record, seq, id, at, boardId, readNodes };
 }
 
 interface ContextReadRow {
@@ -176,6 +209,7 @@ interface ContextReadRow {
   delivered_node_ids: string;
   bytes: number;
   board_id: string | null;
+  read_nodes: string;
 }
 
 function rowToContextRead(row: ContextReadRow): ContextRead {
@@ -190,11 +224,49 @@ function rowToContextRead(row: ContextReadRow): ContextRead {
     agentId: row.agent_id,
     pinnedNodeIds: JSON.parse(row.pinned_node_ids) as string[],
     deliveredNodeIds: JSON.parse(row.delivered_node_ids) as string[],
+    readNodes: JSON.parse(row.read_nodes) as Record<string, number>,
     bytes: row.bytes,
     boardId: row.board_id,
   };
 }
 
+/** Per node on a board, the latest agent read that delivered its content (newest row wins). */
+export function loadNodeReadStatusFromDB(db: Database, boardId: string): NodeReadStatus[] {
+  const rows = db
+    .query<ContextReadRow, [string]>('SELECT * FROM context_reads WHERE board_id = ? ORDER BY seq DESC')
+    .all(boardId);
+  const status = new Map<string, NodeReadStatus>();
+  for (const read of rows.map(rowToContextRead)) {
+    for (const [nodeId, readRevision] of Object.entries(read.readNodes)) {
+      const known = status.get(nodeId);
+      if (known) {
+        known.readCount += 1;
+        continue;
+      }
+      status.set(nodeId, {
+        nodeId,
+        lastReadAt: read.at,
+        lastReadBy: read.consumer ?? read.agentId ?? read.source,
+        readRevision,
+        readCount: 1,
+      });
+    }
+  }
+  return [...status.values()];
+}
+
+/** Every node on a board whose content an agent read at or after `since` (ISO). */
+export function loadReadNodeIdsSince(db: Database, boardId: string, since: string): string[] {
+  const rows = db
+    .query<{ read_nodes: string }, [string, string]>(
+      'SELECT read_nodes FROM context_reads WHERE board_id = ? AND at >= ? ORDER BY seq',
+    )
+    .all(boardId, since);
+  const ids = new Set<string>();
+  for (const row of rows) for (const id of Object.keys(JSON.parse(row.read_nodes) as object)) ids.add(id);
+  return [...ids];
+}
+
 /** Newest first. The summary covers every retained row, not just the returned page. */
 export function loadContextReadsFromDB(
   db: Database,

package/src/server/demo-state.json

@@ -3134,7 +3134,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 41,
+      "contentRevision": 46,
       "kind": "markdown",
       "title": "Sprint 41 — canvas polish",
       "content": "Three nodes, one frame. Moving the frame moves the children; ungrouping leaves them exactly where they are.\n\n- Group children keep their own positions by default\n- `childLayout` opts into auto-packing\n- The frame is stored as `data.children` on the group",
@@ -3174,7 +3174,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 42,
+      "contentRevision": 47,
       "kind": "status",
       "title": "Sprint state",
       "content": null,
@@ -3215,7 +3215,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 43,
+      "contentRevision": 48,
       "kind": "trace",
       "title": "canvas_group",
       "content": null,
@@ -3256,7 +3256,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 44,
+      "contentRevision": 45,
       "kind": "group",
       "title": "Sprint 41",
       "content": null,
@@ -3292,7 +3292,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 45,
+      "contentRevision": 49,
       "kind": "markdown",
       "title": "⑦ HTML primitives",
       "content": "All 21 generated communication surfaces — self-contained sandboxed documents, no build step.",
@@ -3377,7 +3377,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 46,
+      "contentRevision": 50,
       "kind": "html",
       "title": "How should the demo board be generated?",
       "content": "Side-by-side options with tradeoffs, pros, cons, and code or evidence snippets.",
@@ -3487,7 +3487,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 47,
+      "contentRevision": 51,
       "kind": "html",
       "title": "Demo board rebuild",
       "content": "Implementation plan with milestones, data flow, code checkpoints, and risks.",
@@ -3566,7 +3566,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 48,
+      "contentRevision": 52,
       "kind": "html",
       "title": "Review — auto-fit floor",
       "content": "Annotated PR/code review sheet with severity-colored findings and diff excerpts.",
@@ -3654,7 +3654,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 49,
+      "contentRevision": 53,
       "kind": "html",
       "title": "PR — replace the demo board",
       "content": "Reviewer-ready PR narrative with motivation, before/after, file tour, test plan, and rollout notes.",
@@ -3766,7 +3766,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 50,
+      "contentRevision": 54,
       "kind": "html",
       "title": "Canvas server map",
       "content": "Module or architecture map with boxes, relationships, entry points, and hot paths.",
@@ -3895,7 +3895,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 51,
+      "contentRevision": 55,
       "kind": "html",
       "title": "Walkthrough — creating a node",
       "content": "Guided code-path map with modules, ordered file steps, snippets, key files, and gotchas.",
@@ -3998,7 +3998,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 52,
+      "contentRevision": 56,
       "kind": "html",
       "title": "Board typography directions",
       "content": "Visual design directions, tokens, swatches, type samples, and rationale.",
@@ -4081,7 +4081,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 53,
+      "contentRevision": 57,
       "kind": "html",
       "title": "Node titlebar states",
       "content": "Contact sheet for component variants, states, sizes, and accessibility notes.",
@@ -4179,7 +4179,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 54,
+      "contentRevision": 58,
       "kind": "html",
       "title": "Node expand transition",
       "content": "Throwaway interaction or motion sandbox with a live stage, controls, annotations, and copyable config.",
@@ -4265,7 +4265,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 55,
+      "contentRevision": 59,
       "kind": "html",
       "title": "Release pipeline",
       "content": "Clickable flowchart for pipelines, user journeys, process diagrams, and failure paths.",
@@ -4360,7 +4360,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 56,
+      "contentRevision": 60,
       "kind": "html",
       "title": "Why a spatial canvas",
       "content": "Arrow-key HTML deck with sections, speaker notes, and copyable JSON payload. Slides: Chat is a queue, work is a graph, The canvas is the agent’s working memory, Pinning is the steering wheel.",
@@ -4478,7 +4478,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 57,
+      "contentRevision": 61,
       "kind": "html",
       "title": "PMX Canvas 0.4.7 briefing",
       "content": "PowerPoint-style fullscreen-ready HTML presentation with slide navigation, progress, speaker notes, and presentation metadata. Slides: Where we are, What changed in 0.4.7, Next.",
@@ -4643,7 +4643,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 58,
+      "contentRevision": 62,
       "kind": "html",
       "title": "Figures — the collaboration loop",
       "content": "Inline SVG figure sheet with captions and per-figure SVG copy/export controls.",
@@ -4749,7 +4749,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 59,
+      "contentRevision": 63,
       "kind": "html",
       "title": "How context pins work",
       "content": "Readable explainer with TLDR, collapsible steps, annotated snippets, FAQ, and glossary.",
@@ -4870,7 +4870,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 60,
+      "contentRevision": 64,
       "kind": "html",
       "title": "Blank ext-app tiles on WebKit",
       "content": "Post-incident report with impact metrics, minute-by-minute timeline, root cause, log excerpts, and action checklist.",
@@ -4956,7 +4956,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 61,
+      "contentRevision": 65,
       "kind": "html",
       "title": "Weekly canvas status",
       "content": "Skimmable report with metrics, shipped/slipped lists, blockers, and next actions.",
@@ -5042,7 +5042,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 62,
+      "contentRevision": 66,
       "kind": "html",
       "title": "Post-0.4.7 triage",
       "content": "Draggable Now/Next/Later/Cut board with copy-as-markdown export.",
@@ -5134,7 +5134,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 63,
+      "contentRevision": 67,
       "kind": "html",
       "title": "Canvas feature flags",
       "content": "Form-like editor for flags or structured config with dependency warnings and copy-diff export.",
@@ -5203,7 +5203,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 64,
+      "contentRevision": 68,
       "kind": "html",
       "title": "Board summary prompt",
       "content": "Side-by-side prompt/template editor with live variable previews and copy export.",
@@ -5256,7 +5256,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 65,
+      "contentRevision": 69,
       "kind": "html",
       "title": "Agent board",
       "content": "Live agent work board: hand the agent tasks, watch status, steer, and run bounded task loops.",
@@ -5337,7 +5337,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 77,
+      "contentRevision": 85,
       "kind": "html",
       "title": "Release flow",
       "content": "HTML primitive: ax-flow\nLive task-flow control panel: a step diagram with an explicit loop-back, per-step status, and a one-click materialize onto the board.\nRelease flow PMX HTML primitive / ax-flow Release flow Live task-flow control panel: a step diagram with an explicit loop-back, per-step status, and a one-click materialize onto the board. Copy JSON Copy prompt AX bridge unavailable This flow is not running as an AX-enabled canvas node, so its controls are inert. Release flow Each step is a canvas AX work item. Materialize drops the same flow onto the board as real nodes. loops back to step 1 · max 3 runs Run the flow Queue every step A step is queued once — after that its status control advances it (todo → in-progress → done). or run the whole flow as a bounded loop: max runs Start loop Steer Queue steering message Queued for the agent's next turn — steering is recorded on the timeline, it does not wake a running agent. Loop run 0 of 0 Each run is its own work item. When you mark the current run done , the surface opens the next run...",
@@ -5373,7 +5373,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 67,
+      "contentRevision": 71,
       "kind": "markdown",
       "title": "⑧ Agent at work",
       "content": "A task caught mid-flight: one work item per step, status chips on the nodes, controls that steer the agent.",
@@ -5454,7 +5454,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 78,
+      "contentRevision": 86,
       "kind": "markdown",
       "title": "1. Reproduce",
       "content": "Ran the publish gate 20× in a loop. Fails 3 in 20, always on the registry probe.",
@@ -5500,7 +5500,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 79,
+      "contentRevision": 87,
       "kind": "markdown",
       "title": "2. Fix",
       "content": "Retry the probe with backoff instead of failing the gate on the first timeout.",
@@ -5592,7 +5592,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 81,
+      "contentRevision": 83,
       "kind": "markdown",
       "title": "4. Ship",
       "content": "Land the patch, then watch the next three releases.",
@@ -5628,7 +5628,7 @@
         "actor": "agent",
         "source": "api"
       },
-      "contentRevision": 82,
+      "contentRevision": 88,
       "kind": "markdown",
       "title": "How to read this band",
       "content": "Each step is a real **AX work item**, so the chip on a step node is the\nagent’s live status — it moves as the agent works.\n\nThe buttons in each step footer steer it: **Start**, **Done** and\n**Blocked** write that step’s work item, which the agent reads back from\n`canvas://ax-work`.\n\nStep 2 is pinned, so `canvas://pinned-context` hands the agent the\nstep it is actually on.",

package/src/server/html-surface.ts

@@ -226,12 +226,11 @@ export function buildMermaidSurfaceHtml(
 ): string {
   // srcdoc-rendered surfaces in hosts that block sub-frame subresources (the
   // Claude Code desktop browser blocks the script request too, not just the
-  // frame document) get the renderer embedded as a data: URL — no network
-  // request for the host to block, and base64 has no `<` for the HTML script
-  // parser to trip on (a 3.5MB bundle inlined as literal script text hits the
-  // `<!--` script-data-escaped states and renders as page text).
+  // frame document) get an inline bootstrap. Assigning decoded script text
+  // avoids HTML parser escaped states (`<!--`, `</script>`) in the bundle,
+  // without requiring data: script URLs that MCP App hosts may prohibit.
   const entry = inlineEntry
-    ? `<script src="data:text/javascript;charset=utf-8;base64,${Buffer.from(inlineEntry, 'utf-8').toString('base64')}"></script>`
+    ? `<script>(()=>{const s=document.createElement('script');s.textContent=new TextDecoder().decode(Uint8Array.from(atob('${Buffer.from(inlineEntry, 'utf-8').toString('base64')}'),c=>c.charCodeAt(0)));document.head.appendChild(s)})()</script>`
     : '<script src="/canvas/mermaid-entry.js"></script>';
   return `<pre class="mermaid-source" data-fit="${fit}" data-frame-token="${sanitizeFrameToken(frameToken)}" style="display:none">${escapeSurfaceHtml(source)}</pre>${entry}`;
 }

package/src/server/index.ts

@@ -83,6 +83,7 @@ import { executeOperation, runCanvasBatchOperation, type OpenMcpAppCoreResult }
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
 import { serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
+import { contextReadFromPayload } from './context-reads.js';
 import {
   buildHtmlPrimitive,
   getHtmlPrimitiveSemanticMetadata,
@@ -218,6 +219,8 @@ export class PmxCanvas extends EventEmitter {
   async 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
@@ -225,7 +228,11 @@ export class PmxCanvas extends EventEmitter {
      */
     allowPortFallback?: boolean;
   }): Promise<void> {
-    const base = startCanvasServer({ port: this._port, allowPortFallback: options?.allowPortFallback ?? false });
+    const base = startCanvasServer({
+      port: this._port,
+      allowPortFallback: options?.allowPortFallback ?? false,
+      allowExternalMcp: options?.allowExternalMcp,
+    });
     if (!base) {
       throw new Error(`Failed to start canvas server on port ${this._port}`);
     }
@@ -900,6 +907,11 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getContextReads(limit);
   }
 
+  /** 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> {
+    return canvasState.getNodeReadStatus(board ?? canvasState.activeBoardId);
+  }
+
   listWorkItems(): PmxAxWorkItem[] {
     return canvasState.getWorkItems();
   }
@@ -1242,10 +1254,29 @@ export class PmxCanvas extends EventEmitter {
   }
 
   getNode(id: string, options?: { board?: string }): SdkCanvasNode | undefined {
+    const boardId = options?.board ?? canvasState.activeBoardId;
+    const board = options?.board ? canvasState.readBoard(options.board) : null;
+    if (options?.board && !board) throw new Error(`Board "${options.board}" not found.`);
     const node = options?.board
-      ? this.getLayout(options).nodes.find((candidate) => candidate.id === id)
+      ? board?.layout.nodes.find((candidate) => candidate.id === id)
       : canvasState.getNode(id);
-    return node ? toSdkNode(node) : undefined;
+    if (!node) return undefined;
+    const result = toSdkNode(node);
+    canvasState.recordContextRead(
+      contextReadFromPayload(
+        {
+          channel: 'operation',
+          resource: 'node.get',
+          source: 'sdk',
+          consumer: null,
+          agentId: null,
+          pinnedNodeIds: options?.board ? (board?.state.contextPins ?? []) : [...canvasState.contextPinnedNodeIds],
+        },
+        result,
+      ),
+      boardId,
+    );
+    return result;
   }
 
   search(query: string): ReturnType<typeof searchNodes> {
@@ -1298,8 +1329,13 @@ export class PmxCanvas extends EventEmitter {
     return applyCanvasNodeUpdates(updates);
   }
 
-  setContextPins(nodeIds: string[], mode: 'set' | 'add' | 'remove' = 'set'): { count: number; nodeIds: string[] } {
-    const result = setCanvasContextPins(nodeIds, mode);
+  /** `reason` is kept with newly pinned nodes and shown to the human on hover. */
+  setContextPins(
+    nodeIds: string[],
+    mode: 'set' | 'add' | 'remove' = 'set',
+    reason?: string,
+  ): { count: number; nodeIds: string[] } {
+    const result = setCanvasContextPins(nodeIds, mode, reason);
     emitPrimaryWorkbenchEvent('context-pins-changed', { count: result.count, nodeIds: result.nodeIds });
     return result;
   }