pmx-canvas 0.8.2 → 0.9.0

package/src/client/state/boards-store.ts

@@ -1,100 +1,239 @@
-import { signal } from '@preact/signals';
+import { batch, effect, signal } from '@preact/signals';
+import { knowledgeLifecycleEnabled } from './workspace-settings';
 import { requestJson } from './intent-bridge';
+import { focusNode, hasInitialServerLayout, hiddenByCollapsedGroup, nodes, toggleCollapsed } from './canvas-store';
+import type { MemoryTarget } from '../../shared/memory-graph.js';
+import type { RelationDefinition } from '../../shared/relations.js';
 
 /**
  * Many boards (plan 012): the workspace's boards and which one is open. The
  * server is the authority; this mirrors GET /api/canvas/boards and the
- * `boards-changed` SSE frame. `activeBoardId === null` is Home.
+ * `boards-changed` SSE frame. Null means no server board is open; browsingMemory
+ * separately keeps a human in the library while agents open boards.
  */
 export interface BoardSummary {
   id: string;
   name: string;
-  category: string | null;
+  folder: string | null;
   createdAt: string;
   lastOpenedAt: string | null;
   nodeCount: number;
   readmeNodeId?: string | null;
+  mapPosition?: { x: number; y: number } | null;
+  previousBoardId?: string | null;
+  relationVocabulary?: RelationDefinition[];
   summary?: string | null;
   pinnedTitles?: Array<{ nodeId: string; title: string }>;
-  links?: Array<{ nodeId: string; boardId: string; title: string | null; missing: boolean }>;
-  backlinks?: Array<{ boardId: string; title: string; nodeId: string }>;
+  links?: Array<{
+    id?: string;
+    nodeId: string;
+    boardId: string;
+    cardId?: string;
+    cardTitle?: string | null;
+    title: string | null;
+    missing: boolean;
+    kind?: string;
+  }>;
+  backlinks?: Array<{ id?: string; boardId: string; title: string; nodeId: string; cardId?: string; kind?: string }>;
+  /** Home thumbnail (docs/design/Home.dc.html): cards as 0–1 rectangles of the board's extent. */
+  preview?: Array<{ x: number; y: number; w: number; h: number; pinned?: true }>;
+  /** Roughly what this board's map costs in the brief when pinned (README + pinned card summaries). */
+  mapChars?: number;
+  /** In the agent's working set (vision move 0a); null when not pinned. */
+  pin?: { pinnedBy: { actor: string; source: string; agentId?: string }; pinnedAt: string; reason?: string } | null;
 }
 
 interface BoardsPayload {
+  catalogEpoch: string;
+  catalogRevision: number;
+  reloadRevision: number;
+  boardGeneration: number;
   activeBoardId: string | null;
   boards: BoardSummary[];
 }
 
 export const boardList = signal<BoardSummary[]>([]);
 export const activeBoardId = signal<string | null>(null);
+/** An explicitly opened library view stays visible while agents switch boards. */
+export const browsingMemory = signal(false);
+/** Review belongs to this navigation incarnation, never merely a reused card ID. */
+export const lifecycleTarget = signal<{ boardId: string; nodeId: string; incarnation: number } | null>(null);
+export const lifecycleFilter = signal<'All' | 'To review' | 'Retired'>('All');
+effect(() => {
+  activeBoardId.value;
+  lifecycleFilter.value = 'All';
+});
+/** Layout/pin/reconnect invalidation for the library's shared graph projection. */
+export const memoryGraphRevision = signal(0);
 /** False until the first list arrives — Home must not flash before the server answers. */
 export const boardsLoaded = signal(false);
 
-let onBoardSwitched: (() => void) | null = null;
-let boardsRevision = 0;
+let onBoardSwitched: ((initial: boolean) => void) | null = null;
+export let catalogEpoch: string | null = null;
+export let boardGeneration: number | null = null;
+/** Invalidates suspended writes when the canonical board/library is replaced. */
+export let boardIncarnation = 0;
+let catalogRevision = 0;
+let reloadRevision: number | null = null;
 let openRequestSequence = 0;
 let openRequestQueue: Promise<void> = Promise.resolve();
+let navigationSequence = 0;
+/** Invalidates lifecycle UI work across suspension, including an off/on round trip. */
+export let lifecycleUiGeneration = 0;
+effect(() => {
+  knowledgeLifecycleEnabled.value;
+  lifecycleUiGeneration++;
+});
+
+/** Only the current transport's connected handshake may replace the server epoch. */
+export function connectBoardCatalog(epoch: string): void {
+  if (epoch === catalogEpoch) return;
+  catalogEpoch = epoch;
+  boardGeneration = null;
+  boardIncarnation++;
+  catalogRevision = 0;
+  reloadRevision = null;
+  openRequestSequence++;
+  navigationSequence++;
+  lifecycleTarget.value = null;
+}
 
 /** The SSE bridge resyncs the canvas when the open board changes under it. */
-export function setBoardSwitchHandler(handler: (() => void) | null): void {
+export function setBoardSwitchHandler(handler: ((initial: boolean) => void) | null): void {
   onBoardSwitched = handler;
 }
 
-export function applyBoards(data: { activeBoardId?: unknown; boards?: unknown; reloaded?: unknown } | null): void {
-  if (!data || !Array.isArray(data.boards)) return;
-  boardsRevision += 1;
+export function applyBoards(
+  data: {
+    activeBoardId?: unknown;
+    boards?: unknown;
+    catalogEpoch?: unknown;
+    catalogRevision?: unknown;
+    reloadRevision?: unknown;
+    boardGeneration?: unknown;
+  } | null,
+): void {
+  if (
+    !data ||
+    !Array.isArray(data.boards) ||
+    data.catalogEpoch !== catalogEpoch ||
+    typeof data.catalogRevision !== 'number' ||
+    typeof data.reloadRevision !== 'number' ||
+    data.catalogRevision <= catalogRevision
+  )
+    return;
+  catalogRevision = data.catalogRevision;
   const nextActive = typeof data.activeBoardId === 'string' ? data.activeBoardId : null;
-  // `reloaded`: the library was restored, so even the same board id holds new content.
-  const switched = boardsLoaded.value && (nextActive !== activeBoardId.value || data.reloaded === true);
-  boardList.value = data.boards as BoardSummary[];
-  activeBoardId.value = nextActive;
-  boardsLoaded.value = true;
-  if (switched) onBoardSwitched?.();
+  const initial = !boardsLoaded.value;
+  const establishesGeneration = boardGeneration === null && typeof data.boardGeneration === 'number';
+  // A restore stays observable even when a later GET overtakes its notification.
+  const switched =
+    !initial &&
+    (nextActive !== activeBoardId.value ||
+      (reloadRevision !== null && data.reloadRevision !== reloadRevision) ||
+      (boardGeneration !== null &&
+        typeof data.boardGeneration === 'number' &&
+        data.boardGeneration !== boardGeneration));
+  if (switched) {
+    boardIncarnation++;
+    lifecycleTarget.value = null;
+  }
+  if (typeof data.boardGeneration === 'number') boardGeneration = data.boardGeneration;
+  reloadRevision = data.reloadRevision;
+  batch(() => {
+    boardList.value = data.boards as BoardSummary[];
+    activeBoardId.value = nextActive;
+    boardsLoaded.value = true;
+    // Never render old cards with the replacement board's identity/draft keys.
+    if (switched || initial) onBoardSwitched?.(initial);
+    // A same-board restart may deliver its tagged snapshot before the first
+    // catalog. Drain it without detaching the editor or losing its selection.
+    else if (establishesGeneration) onBoardSwitched?.(true);
+  });
 }
 
 export async function loadBoards(): Promise<void> {
-  const revision = boardsRevision;
   const payload = await requestJson<BoardsPayload | null>('loadBoards', '/api/canvas/boards', null);
-  if (revision === boardsRevision) applyBoards(payload);
+  applyBoards(payload);
 }
 
-async function post(
-  action: string,
-  url: string,
-  method: string,
-  body?: unknown,
-  revision = boardsRevision,
-): Promise<BoardsPayload | null> {
-  const payload = await requestJson<BoardsPayload | null>(action, url, null, {
+async function post(action: string, url: string, method: string, body?: unknown): Promise<BoardsPayload | null> {
+  return requestJson<BoardsPayload | null>(action, url, null, {
     method,
     headers: { 'Content-Type': 'application/json' },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }),
   });
-  return revision === boardsRevision ? payload : null;
+}
+
+/** Reserve navigation before an async save; later navigation cancels the pending jump. */
+export function claimNavigation(): () => boolean {
+  const sequence = ++navigationSequence;
+  return () => sequence === navigationSequence;
 }
 
 /** Open a board, or Home with null. */
 export async function openBoard(id: string | null): Promise<void> {
   const sequence = ++openRequestSequence;
-  const revision = boardsRevision;
+  navigationSequence++;
+  lifecycleTarget.value = null;
+  const epoch = catalogEpoch;
   let payload: BoardsPayload | null = null;
   const request = openRequestQueue.then(async () => {
-    payload = await post('openBoard', '/api/canvas/boards/open', 'POST', { id }, revision);
+    if (epoch === catalogEpoch) payload = await post('openBoard', '/api/canvas/boards/open', 'POST', { id });
   });
   openRequestQueue = request.catch(() => undefined);
   await request;
-  // post drops replies superseded by SSE; also ignore an older open request.
-  if (sequence === openRequestSequence) applyBoards(payload);
+  if (sequence === openRequestSequence && epoch === catalogEpoch && payload) {
+    batch(() => {
+      applyBoards(payload);
+      if (id !== null) browsingMemory.value = false;
+    });
+  }
+}
+
+/** Used by wiki links, graph nodes and qualified library hits; never focus a stale board's same-ID card. */
+export async function openMemoryTarget(target: MemoryTarget, options: { review?: boolean } = {}): Promise<boolean> {
+  if (options.review && !knowledgeLifecycleEnabled.value) return false;
+  const lifecycleGeneration = lifecycleUiGeneration;
+  const opening = openBoard(target.boardId);
+  const sequence = navigationSequence;
+  await opening;
+  const incarnation = boardIncarnation;
+  if (!target.cardId) return sequence === navigationSequence && activeBoardId.value === target.boardId;
+  // A slow layout fetch must not turn a card jump into only a board switch.
+  for (let attempt = 0; attempt < 400; attempt++) {
+    if (
+      sequence !== navigationSequence ||
+      activeBoardId.value !== target.boardId ||
+      boardIncarnation !== incarnation ||
+      browsingMemory.value ||
+      (options.review && (!knowledgeLifecycleEnabled.value || lifecycleGeneration !== lifecycleUiGeneration))
+    )
+      return false;
+    if (hasInitialServerLayout.value && nodes.value.has(target.cardId)) {
+      const group = hiddenByCollapsedGroup.value.get(target.cardId);
+      if (group) toggleCollapsed(group);
+      focusNode(target.cardId);
+      if (options.review) lifecycleTarget.value = { boardId: target.boardId, nodeId: target.cardId, incarnation };
+      return true;
+    }
+    await new Promise((resolve) => window.setTimeout(resolve, 25));
+  }
+  return false;
 }
 
-export async function createAndOpenBoard(name: string): Promise<void> {
+/** Create a board (filed in `folder` when given) and open it. */
+export async function createAndOpenBoard(name: string, folder?: string | null): Promise<void> {
   const sequence = ++openRequestSequence;
+  navigationSequence++;
+  lifecycleTarget.value = null;
+  const epoch = catalogEpoch;
   const created = await requestJson<{ board?: BoardSummary } | null>('createBoard', '/api/canvas/boards', null, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ name }),
+    body: JSON.stringify({ name, ...(folder ? { folder } : {}) }),
   });
-  if (created?.board && sequence === openRequestSequence) await openBoard(created.board.id);
+  if (created?.board && sequence === openRequestSequence && epoch === catalogEpoch) await openBoard(created.board.id);
 }
 
 export interface BoardCopyCard {
@@ -122,7 +261,7 @@ export async function previewBoardCopy(sourceBoardId: string): Promise<BoardCopy
 export async function createBoardFrom(opts: {
   sourceBoardId: string;
   name: string;
-  category?: string;
+  folder?: string;
   nodeIds: string[];
   includeReadme: boolean;
   includeStructure: boolean;
@@ -141,13 +280,28 @@ export async function createBoardFrom(opts: {
   return result?.board ?? null;
 }
 
-/** Rename and/or re-file a board; `category: null` removes it from its category. */
-export async function updateBoard(id: string, patch: { name?: string; category?: string | null }): Promise<void> {
+/** Rename and/or re-file a board; `folder: null` unfiles it. */
+export async function updateBoard(
+  id: string,
+  patch: {
+    name?: string;
+    folder?: string | null;
+    mapPosition?: { x: number; y: number } | null;
+    relationVocabulary?: RelationDefinition[];
+  },
+): Promise<boolean> {
   const payload = await post('updateBoard', `/api/canvas/boards/${encodeURIComponent(id)}`, 'PATCH', {
     ...patch,
-    ...(patch.category === null ? { category: '' } : {}),
+    ...(patch.folder === null ? { folder: '' } : {}),
   });
   applyBoards(payload);
+  return payload !== null;
+}
+
+/** Pin a board into the agent's working set, or unpin it. */
+export async function setBoardPinned(id: string, pinned: boolean): Promise<void> {
+  const url = `/api/canvas/boards/${encodeURIComponent(id)}/${pinned ? 'pin' : 'unpin'}`;
+  applyBoards(await post(pinned ? 'pinBoard' : 'unpinBoard', url, 'POST', {}));
 }
 
 export async function setBoardReadme(id: string, readmeNodeId: string | null): Promise<void> {

package/src/client/state/canvas-store.ts

@@ -10,8 +10,10 @@ import {
 } from '../types';
 import { computeAutoArrange } from '../../shared/auto-arrange';
 import { canvasArea, canvasAreaCenter, canvasFitInsets } from '../canvas/canvas-area';
-import { pushCanvasUpdate, requestBestEffort, requestOk, updateViewportFromClient } from './intent-bridge';
+import { activeBoardId, boardsLoaded } from './boards-store';
+import { pushCanvasUpdate, requestBestEffort, requestJson, requestOk, updateViewportFromClient } from './intent-bridge';
 import { isHostedWorkbench } from './workbench-transport';
+import { syncAttentionFromSse } from './attention-bridge';
 
 function logCanvasStoreError(action: string, error: unknown): void {
   console.error(`[canvas-store] ${action} failed`, error);
@@ -101,6 +103,7 @@ export function getNeighborNodeIds(nodeId: string | null, edgeMap: Map<string, C
 
   const neighborIds = new Set<string>();
   for (const edge of edgeMap.values()) {
+    if (edge.toBoardId !== undefined) continue;
     if (edge.from === nodeId) neighborIds.add(edge.to);
     if (edge.to === nodeId) neighborIds.add(edge.from);
   }
@@ -149,12 +152,15 @@ export function clearSelection(): void {
 
 /** Clear transient UI state that must never follow a node id onto another board. */
 export function resetCanvasInteractionState(): void {
+  cancelViewportAnimation();
   if (expandedCloseTimer !== null) {
     clearTimeout(expandedCloseTimer);
     expandedCloseTimer = null;
   }
   batch(() => {
     canvasInteractionEpoch.value += 1;
+    contextPinsRevision++;
+    contextPinsPendingWrites = 0;
     activeNodeId.value = null;
     expandedNodeId.value = null;
     pendingExpandedNodeCloseId.value = null;
@@ -394,6 +400,10 @@ export function getSelectedNodes(): CanvasNodeState[] {
 }
 
 // ── Context pin actions ──────────────────────────────────────
+// Fence reads against both local writes and newer authoritative pin frames.
+export let contextPinsRevision = 0;
+export let contextPinsPendingWrites = 0;
+
 export function toggleContextPin(id: string): void {
   const next = new Set(contextPinnedNodeIds.value);
   if (next.has(id)) {
@@ -414,6 +424,14 @@ export function addContextPins(ids: string[]): void {
   syncContextPinsToServer(next);
 }
 
+export function removeContextPins(ids: string[]): void {
+  const next = new Set(contextPinnedNodeIds.value);
+  for (const id of ids) next.delete(id);
+  contextPinnedNodeIds.value = next;
+  persistLayout();
+  syncContextPinsToServer(new Set(ids), 'remove');
+}
+
 export function clearContextPins(): void {
   if (contextPinnedNodeIds.value.size === 0) return;
   contextPinnedNodeIds.value = new Set();
@@ -422,16 +440,51 @@ export function clearContextPins(): void {
 }
 
 export function replaceContextPinsFromServer(ids: string[]): void {
+  contextPinsRevision++;
   contextPinnedNodeIds.value = new Set(ids);
 }
 
-function syncContextPinsToServer(ids: Set<string>): void {
+/** Reconcile dropped frames and refused/normalized writes without replaying old pins. */
+export async function refreshContextPins(): Promise<void> {
+  if (contextPinsPendingWrites > 0) return;
+  const revision = contextPinsRevision;
+  const epoch = canvasInteractionEpoch.value;
+  // The agent brief filters retired cards. Only the raw event snapshot is authoritative
+  // for membership; consume its pin frame without replaying the rest of the snapshot.
+  const data = await requestJson<{
+    events?: Array<{ event: string; payload: { nodeIds?: string[]; boardId?: string | null } }>;
+  }>('refreshContextPins', '/api/workbench/poll', {});
+  const pins = data.events?.find((entry) => entry.event === 'context-pins-changed')?.payload;
+  if (
+    revision === contextPinsRevision &&
+    epoch === canvasInteractionEpoch.value &&
+    pins?.boardId === activeBoardId.value &&
+    Array.isArray(pins.nodeIds)
+  ) {
+    replaceContextPinsFromServer(pins.nodeIds);
+    syncAttentionFromSse({ event: 'context-pins-changed', data: pins });
+  }
+}
+
+function syncContextPinsToServer(ids: Set<string>, mode: 'set' | 'remove' = 'set'): void {
+  contextPinsRevision++;
+  contextPinsPendingWrites++;
+  const epoch = canvasInteractionEpoch.value;
   // Through the bridge so the write carries the workbench marker — a bare
   // fetch makes the human's pin look like an anonymous `api` agent.
   void requestBestEffort('syncContextPinsToServer', '/api/canvas/context-pins', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ nodeIds: Array.from(ids) }),
+    body: JSON.stringify({
+      nodeIds: Array.from(ids),
+      mode,
+      ...(boardsLoaded.value ? { expectedBoardId: activeBoardId.value } : {}),
+    }),
+  }).then(() => {
+    if (epoch !== canvasInteractionEpoch.value) return;
+    contextPinsPendingWrites--;
+    contextPinsRevision++;
+    void refreshContextPins();
   });
 }
 
@@ -535,7 +588,7 @@ export function removeEdgesForNode(nodeId: string): void {
   let changed = false;
   const next = new Map(edges.value);
   for (const [id, edge] of next) {
-    if (edge.from === nodeId || edge.to === nodeId) {
+    if (edge.from === nodeId || (edge.toBoardId === undefined && edge.to === nodeId)) {
       next.delete(id);
       changed = true;
     }
@@ -617,11 +670,7 @@ export function replaceViewport(next: ViewportState): void {
   viewport.value = next;
 }
 
-export function commitViewport(next: ViewportState): void {
-  commitViewportWithOptions(next);
-}
-
-function commitViewportWithOptions(next: ViewportState, options: { recordHistory?: boolean } = {}): void {
+export function commitViewport(next: ViewportState, options: { recordHistory?: boolean } = {}): void {
   viewport.value = next;
   persistLayout(options);
   void updateViewportFromClient(next, options);
@@ -634,11 +683,22 @@ export function applyServerCanvasLayout(
   const nextNodes = new Map<string, CanvasNodeState>();
   let nextMaxZ = 1;
   for (const node of layout.nodes) {
-    nextNodes.set(node.id, node);
+    const current = nodes.value.get(node.id);
+    // A poll captured before an acknowledged edit may arrive afterwards.
+    // Accept its geometry, but not older content or attribution. The initial
+    // layout belongs to a newly opened board, where IDs/revisions may repeat.
+    nextNodes.set(
+      node.id,
+      options.applyViewport !== true && current && (current.contentRevision ?? 0) > (node.contentRevision ?? 0)
+        ? { ...node, data: current.data, contentRevision: current.contentRevision, lastEditedBy: current.lastEditedBy }
+        : node,
+    );
     if (node.zIndex >= nextMaxZ) nextMaxZ = node.zIndex + 1;
   }
 
-  const edgeSource = layout.edges.filter((edge) => nextNodes.has(edge.from) && nextNodes.has(edge.to));
+  const edgeSource = layout.edges.filter(
+    (edge) => nextNodes.has(edge.from) && (edge.toBoardId !== undefined || nextNodes.has(edge.to)),
+  );
   const nextEdges = new Map<string, CanvasEdge>();
   for (const edge of edgeSource) {
     nextEdges.set(edge.id, edge);
@@ -728,13 +788,39 @@ export function animateViewport(
       animationId = requestAnimationFrame(tick);
     } else {
       animationId = null;
-      commitViewportWithOptions(target, options);
+      commitViewport(target, options);
     }
   }
 
   animationId = requestAnimationFrame(tick);
 }
 
+/**
+ * Drive the camera along `frameAt(t)`, t in [0, 1], over `duration` ms — the
+ * tour/camera-move path. Shares animateViewport's slot, so a pan gesture or a
+ * capture frame (cancelViewportAnimation) interrupts it. Duration 0 jumps.
+ */
+export function animateCameraPath(
+  frameAt: (t: number) => ViewportState,
+  duration: number,
+  onDone?: (end: ViewportState) => void,
+): void {
+  cancelViewportAnimation();
+  const start = performance.now();
+  const tick = (now: number) => {
+    const t = duration <= 0 ? 1 : Math.min(1, (now - start) / duration);
+    viewport.value = frameAt(t);
+    if (t < 1) {
+      animationId = requestAnimationFrame(tick);
+    } else {
+      animationId = null;
+      onDone?.(viewport.value);
+    }
+  };
+  if (duration <= 0) tick(start);
+  else animationId = requestAnimationFrame(tick);
+}
+
 /** Cancel any in-flight viewport animation (e.g. when user starts dragging). */
 export function cancelViewportAnimation(): void {
   if (animationId !== null) {
@@ -769,6 +855,7 @@ export function persistLayout(options: { recordHistory?: boolean } = {}): void {
         id: e.id,
         from: e.from,
         to: e.to,
+        ...(e.toBoardId !== undefined ? { toBoardId: e.toBoardId } : {}),
         type: e.type,
         label: e.label,
         style: e.style,

package/src/client/state/context-chip-store.ts

@@ -0,0 +1,70 @@
+import { signal } from '@preact/signals';
+import { activeBoardId, boardList } from './boards-store';
+import { requestJson } from './intent-bridge';
+
+/**
+ * The context chip (docs/design/ContextChip.dc.html): what the agent's brief
+ * costs in tokens, and when each pinned board was last read. The brief fetch is a measurement, not a delivery: it says so with
+ * `x-pmx-proxied-read`, so it is never booked as an agent read — not even from
+ * an `?agent=` tab, whose requests carry no workbench marker. Otherwise the
+ * recorded read would announce itself and refetch the chip in a loop.
+ */
+
+export interface BriefSize {
+  chars: number;
+}
+
+export interface BoardRead {
+  lastReadAt: string;
+  lastReadBy: string;
+}
+
+export const briefSize = signal<BriefSize | null>(null);
+export const pinnedBoardReads = signal<Map<string, BoardRead | null>>(new Map());
+
+/** A token count for display: 873, 1.1k. */
+export function formatTokens(tokens: number): string {
+  return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : `${Math.round(tokens)}`;
+}
+
+/** ≈ tokens for a character count (about four characters per token). */
+export function approxTokens(chars: number): string {
+  return formatTokens(chars / 4);
+}
+
+let timer: ReturnType<typeof setTimeout> | null = null;
+let generation = 0;
+
+/** Debounced: pins, reads and board changes arrive in bursts; content edits wait longer. */
+export function refreshContextChip(delayMs = 250): void {
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(() => {
+    timer = null;
+    void load();
+  }, delayMs);
+}
+
+async function load(): Promise<void> {
+  const request = ++generation;
+  const boardId = activeBoardId.value;
+  // A late answer for a board you have since left, or an older request, must not paint the chip.
+  const current = () => request === generation && boardId === activeBoardId.value;
+  const brief = await requestJson<{ entries?: unknown[] } | null>('fetchBriefSize', '/api/canvas/context', null, {
+    headers: { 'x-pmx-proxied-read': '1' },
+  });
+  if (!current()) return;
+  if (brief?.entries) briefSize.value = { chars: JSON.stringify(brief).length };
+  const pinned = boardList.value.filter((board) => board.pin);
+  if (pinned.length === 0) {
+    if (current()) pinnedBoardReads.value = new Map();
+    return;
+  }
+  // One request for every pinned board's latest read.
+  const status = await requestJson<{ boards?: Record<string, BoardRead | null> } | null>(
+    'fetchBoardReadStatus',
+    `/api/canvas/ax/context-status?boards=${pinned.map((board) => encodeURIComponent(board.id)).join(',')}`,
+    null,
+  );
+  if (current())
+    pinnedBoardReads.value = new Map(pinned.map((board) => [board.id, status?.boards?.[board.id] ?? null]));
+}

package/src/client/state/context-status-store.ts

@@ -1,5 +1,6 @@
 import { signal } from '@preact/signals';
 import { activeBoardId } from './boards-store';
+import { edges } from './canvas-store';
 import { requestJson } from './intent-bridge';
 
 /**
@@ -28,14 +29,18 @@ interface ContextStatusResponse {
   ok?: boolean;
   boardId?: string | null;
   nodes?: NodeReadStatus[];
+  /** Per node, the newest links revision an agent read carried. */
+  links?: Record<string, number>;
   pins?: Record<string, ContextPinMeta>;
 }
 
 export const nodeReadStatus = signal<Map<string, NodeReadStatus>>(new Map());
 export const contextPinMeta = signal<Record<string, ContextPinMeta>>({});
+export const seenLinks = signal<Record<string, number>>({});
 
 export function applyContextStatus(response: ContextStatusResponse): void {
   nodeReadStatus.value = new Map((response.nodes ?? []).map((entry) => [entry.nodeId, entry]));
+  seenLinks.value = response.links ?? {};
   contextPinMeta.value = response.pins ?? {};
 }
 
@@ -60,6 +65,54 @@ export function pinnedReadState(nodeId: string, currentRevision: number): Pinned
   return { kind: 'read', by: read.lastReadBy, at: read.lastReadAt, count: read.readCount };
 }
 
+/**
+ * The marks a link's pill carries (docs/design/LinkAuthorship.dc.html):
+ * - `agent`: the agent that drew or last relabelled it — a ✦ that stays until
+ *   a person edits, retypes or relabels the link. A read never clears it.
+ * - `notSeen`: a person's new or edited link that no read has carried yet —
+ *   temporary, cleared by the agent's next read of either end. Quiet until an
+ *   agent has read this board at all. An agent's link is never "not seen".
+ * The board's only person draws without a mark (another person's initial is
+ * Part 3, shared boards).
+ */
+export interface LinkMarks {
+  agent: string | null;
+  notSeen: boolean;
+}
+
+export function linkMarks(edge: {
+  from: string;
+  to: string;
+  toBoardId?: string;
+  revision?: number;
+  changedBy?: { actor: string; source: string; agentId?: string };
+}): LinkMarks {
+  if (edge.changedBy?.actor === 'agent') return { agent: writerName(edge.changedBy), notSeen: false };
+  const seen = seenLinks.value;
+  const notSeen =
+    !!edge.revision &&
+    Object.keys(seen).length > 0 &&
+    edge.revision > Math.max(seen[edge.from] ?? -1, edge.toBoardId === undefined ? (seen[edge.to] ?? -1) : -1);
+  return { agent: null, notSeen };
+}
+
+/**
+ * A card whose links changed after the last read that carried them (shown
+ * neutral, never amber). A link an agent drew does not count — that agent
+ * made it, and the link itself says "by <agent>". A removed link has no
+ * author left to check, so it counts.
+ */
+export function linksChanged(nodeId: string, linksRevision: number): boolean {
+  const seen = seenLinks.value[nodeId];
+  if (seen === undefined || linksRevision <= seen) return false;
+  const unseen = [...edges.value.values()].filter(
+    (edge) =>
+      (edge.from === nodeId || (edge.toBoardId === undefined && edge.to === nodeId)) && (edge.revision ?? 0) > seen,
+  );
+  if (unseen.some((edge) => edge.changedBy?.actor !== 'agent')) return true;
+  return !unseen.some((edge) => edge.revision === linksRevision);
+}
+
 /** Display name for an attributed writer: its agent id, else its transport label. */
 export function writerName(actor: { source: string; agentId?: string }): string {
   return actor.agentId?.trim() || actor.source;