pmx-canvas 0.8.2 → 0.9.0

package/src/client/state/intent-bridge.ts

@@ -1,10 +1,11 @@
-import { canvasArea } from '../canvas/canvas-area';
+import { canvasArea, canvasFitInsets } from '../canvas/canvas-area';
 import { showToast } from './attention-bridge';
 import { isHostedWorkbench, workbenchFetch } from './workbench-transport';
 import type { AgentPresenceSnapshot } from '../../shared/agent-presence.js';
-import type { CanvasEdge } from '../types';
+import type { CanvasEdge, CanvasNodeState } from '../types';
 import { addEdge, canvasInteractionEpoch, nodes } from './canvas-store';
-import { boardsLoaded } from './boards-store';
+import { activeBoardId, boardsLoaded } from './boards-store';
+import { humanClientId } from './human-store';
 function logRequestError(action: string, error: unknown): void {
   console.error(`[intent-bridge] ${action} failed`, error);
 }
@@ -141,7 +142,11 @@ export async function vetoGhostIntent(intent: {
 }
 
 /** Fetch rendered markdown HTML from the server. */
-export async function renderMarkdown(markdown: string): Promise<string> {
+export async function renderMarkdown(
+  markdown: string,
+  nodeId?: string,
+  expectedBoardId: string | null = activeBoardId.value,
+): Promise<string | null> {
   const data = await requestJson<{ html?: string }>(
     'renderMarkdown',
     '/api/render',
@@ -149,10 +154,10 @@ export async function renderMarkdown(markdown: string): Promise<string> {
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ markdown }),
+      body: JSON.stringify({ markdown, ...(nodeId ? { nodeId, expectedBoardId } : {}) }),
     },
   );
-  return data.html ?? '';
+  return data.html ?? null;
 }
 
 /** Fetch file content from the server. */
@@ -163,20 +168,6 @@ export async function fetchFile(path: string): Promise<{
   return requestJson('fetchFile', `/api/file?path=${encodeURIComponent(path)}`, { content: '' });
 }
 
-/** Save file content to the server. */
-export async function saveFile(path: string, content: string): Promise<{ ok: boolean; updatedAt?: string }> {
-  return requestJson(
-    'saveFile',
-    '/api/file/save',
-    { ok: false },
-    {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path, content }),
-    },
-  );
-}
-
 /** Fetch current workbench state. */
 export async function fetchWorkbenchState(): Promise<Record<string, unknown>> {
   return requestJson('fetchWorkbenchState', '/api/workbench/state', {});
@@ -192,8 +183,12 @@ export async function openWorkbenchFile(path: string): Promise<{ ok: boolean }>
 }
 
 /** Fetch canvas state from server. */
-export async function fetchCanvasState(): Promise<Record<string, unknown>> {
-  return requestJson('fetchCanvasState', '/api/canvas/state?includeBlobs=true', {});
+export async function fetchCanvasState(expectedBoardId: string | null): Promise<Record<string, unknown>> {
+  return requestJson(
+    'fetchCanvasState',
+    `/api/canvas/state?includeBlobs=true&expectedBoardId=${encodeURIComponent(expectedBoardId ?? 'null')}`,
+    {},
+  );
 }
 
 export async function saveCanvasTheme(theme: string): Promise<{ ok: boolean; theme?: string }> {
@@ -262,7 +257,11 @@ export async function pushCanvasUpdate(
   await requestBestEffort('pushCanvasUpdate', '/api/canvas/update', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ updates, ...(options.recordHistory === false ? { recordHistory: false } : {}) }),
+    body: JSON.stringify({
+      updates,
+      ...(boardsLoaded.value ? { expectedBoardId: activeBoardId.value } : {}),
+      ...(options.recordHistory === false ? { recordHistory: false } : {}),
+    }),
   });
 }
 
@@ -272,6 +271,7 @@ export async function createEdgeFromClient(
   to: string,
   type: string,
   label?: string,
+  options: { toBoardId?: string; expectedBoardId?: string | null } = {},
 ): Promise<{ ok: boolean; id?: string }> {
   const epoch = canvasInteractionEpoch.value;
   const result = await requestJson<({ ok: true } & CanvasEdge) | { ok: false; error?: string }>(
@@ -281,10 +281,10 @@ export async function createEdgeFromClient(
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ from, to, type, label }),
+      body: JSON.stringify({ from, to, type, label, ...options }),
     },
   );
-  if (epoch === canvasInteractionEpoch.value && nodes.value.has(from) && nodes.value.has(to)) {
+  if (epoch === canvasInteractionEpoch.value && nodes.value.has(from) && (options.toBoardId || nodes.value.has(to))) {
     if (result.ok) {
       const { ok, ...edge } = result;
       addEdge(edge);
@@ -333,8 +333,9 @@ export async function updateNodeFromClient(
     children?: string[];
     expectedContentRevision?: number;
     expectedBoardId?: string | null;
+    persistFile?: boolean;
   },
-): Promise<{ ok: boolean; id?: string; contentRevision?: number }> {
+): Promise<{ ok: boolean; id?: string; contentRevision?: number; lastEditedBy?: CanvasNodeState['lastEditedBy'] }> {
   return requestJson(
     'updateNodeFromClient',
     `/api/canvas/node/${encodeURIComponent(id)}`,
@@ -451,6 +452,8 @@ export async function updateViewportFromClient(
       body: JSON.stringify({
         ...viewport,
         ...clientWindowSize(),
+        clientId: humanClientId,
+        ...(boardsLoaded.value ? { expectedBoardId: activeBoardId.value } : {}),
         ...(options.recordHistory === false ? { recordHistory: false } : {}),
       }),
     },
@@ -462,7 +465,13 @@ export async function updateViewportFromClient(
  * `fit` computes against the human's REAL window instead of a hardcoded
  * 1440x900 (0.4.6 orb feedback #2: fit clipped nodes on both sides).
  */
-function clientWindowSize(): { clientWidth: number; clientHeight: number } | Record<string, never> {
+function clientWindowSize():
+  | {
+      clientWidth: number;
+      clientHeight: number;
+      clientInsets: { top: number; bottom: number };
+    }
+  | Record<string, never> {
   if (typeof window === 'undefined') return {};
   // The CANVAS REGION, not the window — with the rail + top-bar shell a
   // window-sized fit would hide nodes under the chrome.
@@ -470,7 +479,8 @@ function clientWindowSize(): { clientWidth: number; clientHeight: number } | Rec
   const clientWidth = Math.round(area.width);
   const clientHeight = Math.round(area.height);
   if (!clientWidth || !clientHeight) return {};
-  return { clientWidth, clientHeight };
+  const { top, bottom } = canvasFitInsets();
+  return { clientWidth, clientHeight, clientInsets: { top, bottom } };
 }
 
 /**
@@ -488,7 +498,11 @@ export async function reportClientViewportSize(): Promise<void> {
   await requestBestEffort('reportClientViewportSize', '/api/canvas/viewport', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ ...size, recordHistory: false }),
+    body: JSON.stringify({
+      ...size,
+      ...(boardsLoaded.value ? { expectedBoardId: activeBoardId.value } : {}),
+      recordHistory: false,
+    }),
   });
 }
 
@@ -595,7 +609,14 @@ export async function deleteSnapshot(id: string): Promise<{ ok: boolean }> {
 /** Patch an edge in place (label/type/style/animated) via the server. */
 export async function updateEdgeFromClient(
   edgeId: string,
-  patch: { label?: string; type?: string; style?: string; animated?: boolean },
+  patch: {
+    kind?: string | null;
+    reason?: string | null;
+    label?: string;
+    type?: string;
+    style?: string;
+    animated?: boolean;
+  },
 ): Promise<{ ok: boolean }> {
   return requestJson(
     'updateEdgeFromClient',

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

@@ -0,0 +1,43 @@
+import { computed, signal } from '@preact/signals';
+import { knowledgeLifecycleEnabled } from './workspace-settings';
+import type { KnowledgeResults } from '../../server/knowledge-lifecycle.js';
+import { memoryKey } from '../../shared/memory-graph.js';
+import { activeBoardId, boardIncarnation, lifecycleFilter } from './boards-store';
+import { contextPinnedNodeIds } from './canvas-store';
+import { requestJson } from './intent-bridge';
+
+import { lifecycleTarget } from './boards-store';
+export { lifecycleFilter, lifecycleTarget } from './boards-store';
+
+export const knowledge = signal<KnowledgeResults['list'] | null>(null);
+export const knowledgeUnavailable = signal(false);
+export const effectiveLifecycleFilter = computed(() =>
+  knowledgeLifecycleEnabled.value ? lifecycleFilter.value : 'All',
+);
+export const retirementUndo = signal<{ boardId: string; nodeId: string; incarnation: number } | null>(null);
+let sequence = 0;
+
+export async function refreshKnowledge(): Promise<void> {
+  const request = ++sequence;
+  const incarnation = boardIncarnation;
+  const result = await requestJson<KnowledgeResults['list'] | null>('knowledge', '/api/canvas/knowledge', null);
+  if (request !== sequence || incarnation !== boardIncarnation) return;
+  knowledgeUnavailable.value = result?.ok !== true;
+  if (result?.ok === true) knowledge.value = result;
+}
+
+export function cardQualification(nodeId: string) {
+  return activeBoardId.value
+    ? knowledge.value?.cards[memoryKey({ boardId: activeBoardId.value, cardId: nodeId })]
+    : undefined;
+}
+
+/** Raw pin membership survives retirement, but retired cards are not delivered. */
+export const activeContextPinnedNodeIds = computed(
+  () => new Set([...contextPinnedNodeIds.value].filter((id) => !cardQualification(id)?.retired)),
+);
+
+export function openLifecycle(nodeId: string): void {
+  if (knowledgeLifecycleEnabled.value && activeBoardId.value)
+    lifecycleTarget.value = { boardId: activeBoardId.value, nodeId, incarnation: boardIncarnation };
+}

package/src/client/state/near-pin-store.ts

@@ -1,10 +1,12 @@
-import { computed } from '@preact/signals';
-import { findNeighborhoods } from '../../server/spatial-analysis.js';
-import { contextPinnedNodeIds, nodes } from './canvas-store';
+import { computed, signal } from '@preact/signals';
+import { findNeighborhoods, gapDistance } from '../../server/spatial-analysis.js';
+import { contextPinnedNodeIds, nodes, selectedNodeIds } from './canvas-store';
+import { grabbingNodeId } from './human-store';
+import { activeContextPinnedNodeIds, cardQualification } from './knowledge-store';
 
 /**
  * Near a pin (docs/design/NearPin.dc.html): each pinned node pulls up to five
- * unpinned nodes within 600 px into the agent's brief as title + short
+ * unpinned nodes within a 600 px edge-to-edge gap into the agent's brief as title + short
  * summary. Same rule as the server's brief (`findNeighborhoods`), so the mark
  * claims exactly what the agent receives.
  */
@@ -22,11 +24,12 @@ let lastNear = new Map<string, NearPin[]>();
  * changes: the chips subscribed to it re-render only when a neighbourhood does.
  */
 export const nearPins = computed<Map<string, NearPin[]>>(() => {
-  const pins = contextPinnedNodeIds.value;
+  const pins = activeContextPinnedNodeIds.value;
   const near = new Map<string, NearPin[]>();
   if (pins.size > 0) {
     const nearest = new Map<string, Array<NearPin & { distance: number }>>();
-    for (const neighborhood of findNeighborhoods([...nodes.value.values()], pins)) {
+    const activeNodes = [...nodes.value.values()].filter((node) => !cardQualification(node.id)?.retired);
+    for (const neighborhood of findNeighborhoods(activeNodes, pins)) {
       const pinTitle = neighborhood.pinnedNodeTitle ?? neighborhood.pinnedNodeId;
       for (const neighbor of neighborhood.neighbors) {
         const list = nearest.get(neighbor.id) ?? [];
@@ -51,3 +54,109 @@ export const nearPins = computed<Map<string, NearPin[]>>(() => {
   lastNear = near;
   return near;
 });
+
+/** Pin id → its neighbours' ids: the tether layer looks a pin up, never scans the near map. */
+export const neighboursByPin = computed<Map<string, string[]>>(() => {
+  const byPin = new Map<string, string[]>();
+  for (const [nodeId, pins] of nearPins.value) {
+    for (const pin of pins) {
+      const list = byPin.get(pin.pinNodeId) ?? [];
+      list.push(nodeId);
+      byPin.set(pin.pinNodeId, list);
+    }
+  }
+  return byPin;
+});
+
+/** The node under the pointer: a hovered pin draws its neighbours (NearPin.dc.html §2). */
+export const hoveredNodeId = signal<string | null>(null);
+/** A near node whose pins the human asked to see from its chip ("Show pins"). */
+export const shownPinsFor = signal<string | null>(null);
+
+/**
+ * Pins drawn with tethers and the 600 px boundary around their edges: the pin being dragged,
+ * hovered or selected, or the pins of the near node whose chip said "Show
+ * pins". Dragging an unpinned node rings only its nearest pin (§3).
+ */
+export const tetherFocus = computed<{ pinIds: string[]; ringOnly: boolean }>(() => {
+  const pins = contextPinnedNodeIds.value;
+  if (pins.size === 0) return { pinIds: [], ringOnly: false };
+  const grabbed = grabbingNodeId.value;
+  if (grabbed && !pins.has(grabbed)) {
+    const dragged = nodes.value.get(grabbed);
+    let nearest: string | null = null;
+    let best = Number.POSITIVE_INFINITY;
+    for (const id of pins) {
+      const pin = nodes.value.get(id);
+      if (!dragged || !pin) continue;
+      const distance = gapDistance(dragged, pin);
+      if (distance < best) {
+        best = distance;
+        nearest = id;
+      }
+    }
+    return { pinIds: nearest ? [nearest] : [], ringOnly: true };
+  }
+  const ids = new Set<string>();
+  if (grabbed) ids.add(grabbed);
+  const hovered = hoveredNodeId.value;
+  if (hovered && pins.has(hovered)) ids.add(hovered);
+  for (const id of selectedNodeIds.value) if (pins.has(id)) ids.add(id);
+  const shown = shownPinsFor.value;
+  for (const pin of (shown && nearPins.value.get(shown)) || []) ids.add(pin.pinNodeId);
+  return { pinIds: [...ids], ringOnly: false };
+});
+
+/** The moment it changes (§3): the chip pulses once on a drop inside, fades on a drop outside. */
+export const nearChange = signal<{ nodeId: string; kind: 'in' | 'out'; pins: NearPin[] } | null>(null);
+let nearAtGrab: NearPin[] | undefined;
+
+export function noteNearAtGrab(nodeId: string): void {
+  clearNearChange(nodeId);
+  nearAtGrab = nearPins.value.get(nodeId);
+}
+
+export function settleNearAfterDrop(nodeId: string): void {
+  const before = nearAtGrab;
+  nearAtGrab = undefined;
+  const after = nearPins.value.get(nodeId);
+  if (after && !before) nearChange.value = { nodeId, kind: 'in', pins: after };
+  else if (before && !after) nearChange.value = { nodeId, kind: 'out', pins: before };
+}
+
+export function clearNearChange(nodeId: string): void {
+  if (nearChange.value?.nodeId === nodeId) nearChange.value = null;
+}
+
+/**
+ * The open near chip's card (§2), drawn over the canvas because a node paints
+ * contained. `at` is the chip's screen rect when it opened; the card closes
+ * when the view moves rather than chase a stale anchor.
+ */
+export const nearCard = signal<{
+  nodeId: string;
+  at: { left: number; right: number; top: number; bottom: number };
+  view: string;
+} | null>(null);
+let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function openNearCard(nodeId: string, chip: Element, view: string): void {
+  if (closeTimer) clearTimeout(closeTimer);
+  closeTimer = null;
+  const rect = chip.getBoundingClientRect();
+  nearCard.value = { nodeId, at: { left: rect.left, right: rect.right, top: rect.top, bottom: rect.bottom }, view };
+}
+
+/** Leaving the chip for the card must not close it: close after a short grace. */
+export function closeNearCardSoon(): void {
+  if (closeTimer) clearTimeout(closeTimer);
+  closeTimer = setTimeout(() => {
+    closeTimer = null;
+    nearCard.value = null;
+  }, 160);
+}
+
+export function keepNearCard(): void {
+  if (closeTimer) clearTimeout(closeTimer);
+  closeTimer = null;
+}

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

@@ -1,13 +1,12 @@
 import { computed, signal } from '@preact/signals';
 import type { PmxAxIntent } from '../../shared/ax-intent.js';
 import { intents } from './intent-store';
+import { agentSessionsEnabled } from './workspace-settings';
 import {
   HUMAN_STARTED_SESSION_LABEL,
   type AgentActivityEntry,
   type AgentPresence,
   type AgentPresenceSnapshot,
-  CONTEXT_BUDGET_DEFAULT_TOKENS,
-  type ContextBudget,
   externalWriters,
   isSessionActive,
 } from '../../shared/agent-presence.js';
@@ -21,7 +20,6 @@ import {
  * panel, command bar, presence layer, and top-bar chip all mount on it.
  */
 export const agentPresences = signal<AgentPresence[]>([]);
-export const contextBudget = signal<ContextBudget>({ used: 0, total: CONTEXT_BUDGET_DEFAULT_TOKENS });
 /** Recent agent writes, newest first — the External Steering activity feed. */
 export const agentActivity = signal<AgentActivityEntry[]>([]);
 
@@ -59,11 +57,14 @@ export function relativeAge(iso: string, now = Date.now()): string {
   return `${Math.floor(ms / 3_600_000)}h`;
 }
 
-/** Master gate for every agent surface: an attached session exists. */
+/** Attachment state is independent of whether the human opted into its UI. */
 export const sessionActive = computed(() => isSessionActive(agentPresences.value));
+export const sessionChromeActive = computed(() => agentSessionsEnabled.value && sessionActive.value);
 
-/** Live writers with no attached session — the External Steering mode. */
-export const externalWriterPresences = computed(() => externalWriters(agentPresences.value));
+/** With session UI off, attached agents still appear as ordinary live writers. */
+export const externalWriterPresences = computed(() =>
+  agentSessionsEnabled.value ? externalWriters(agentPresences.value) : agentPresences.value,
+);
 
 /**
  * Connected agents the human can ADDRESS from the composer: every live
@@ -147,15 +148,11 @@ export function presenceWorldPosition(
 export function applyPresenceSnapshot(snapshot: Partial<AgentPresenceSnapshot> | null | undefined): void {
   if (!snapshot) return;
   if (Array.isArray(snapshot.presences)) agentPresences.value = snapshot.presences;
-  if (snapshot.budget && Number.isFinite(snapshot.budget.used) && Number.isFinite(snapshot.budget.total)) {
-    contextBudget.value = { used: snapshot.budget.used, total: snapshot.budget.total };
-  }
   if (Array.isArray(snapshot.activity)) agentActivity.value = snapshot.activity;
 }
 
 export function resetPresence(): void {
   agentPresences.value = [];
-  contextBudget.value = { used: 0, total: CONTEXT_BUDGET_DEFAULT_TOKENS };
   agentActivity.value = [];
   activityFeedOpen.value = false;
   writersSheetOpen.value = false;

package/src/client/state/presentation.ts

@@ -1,7 +1,98 @@
 import { signal } from '@preact/signals';
+import { interpolateCamera, resolveStop, type TourStop } from '../../shared/tour.js';
+import { canvasArea } from '../canvas/canvas-area';
+import type { ViewportState } from '../types';
+import { animateCameraPath, nodes, viewport } from './canvas-store';
+import { requestBestEffort, requestJson } from './intent-bridge';
 
 export const presenting = signal(false);
 export const recordingCamera = signal(false);
+/** Why the current stop cannot be shown (missing target, no stops, server unreachable). */
+export const presentationError = signal('');
+
 export function ownsCamera(): boolean {
   return presenting.value || recordingCamera.value;
 }
+
+function prefersReducedMotion(): boolean {
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Ease this viewer's camera to a stop: log-space zoom, optional pull-back.
+ * Reduced motion jumps straight to the end. Throws when the target is missing.
+ */
+export function playStop(stop: TourStop, onDone?: (end: ViewportState) => void): void {
+  const area = canvasArea();
+  const target = resolveStop(stop, [...nodes.value.values()], area.width, area.height);
+  const from = { ...viewport.value };
+  const duration = prefersReducedMotion() ? 0 : (stop.duration ?? 1) * 1000;
+  animateCameraPath(
+    (t) => interpolateCamera(from, target, t, area.width, area.height, stop.easing, stop.pullback),
+    duration,
+    onDone,
+  );
+}
+
+let stepSeq = 0;
+
+/**
+ * Show a tour stop, entering presentation if needed. Entering hides the
+ * chrome, so the canvas area is measured only after that layout has
+ * committed (two frames); the latest step always wins.
+ */
+export function presentStop(stop: TourStop): void {
+  const seq = ++stepSeq;
+  const entering = !presenting.value;
+  presenting.value = true;
+  presentationError.value = '';
+  const play = () => {
+    if (seq !== stepSeq) return;
+    try {
+      playStop(stop);
+    } catch (error) {
+      presentationError.value = error instanceof Error ? error.message : String(error);
+    }
+  };
+  if (entering) requestAnimationFrame(() => requestAnimationFrame(play));
+  else play();
+}
+
+/**
+ * Move the server's shared tour cursor. The `canvas-tour-step` echo does the
+ * animating, here and in every other presenting viewer, so a human's keys and
+ * an agent's `tour.go` always agree on where the tour is.
+ */
+export async function stepTour(to: { stop: number } | { step: 'next' | 'previous' }): Promise<void> {
+  const result = await requestJson<{ ok: boolean; error?: string }>(
+    'step tour',
+    '/api/canvas/tour/go',
+    { ok: false, error: 'Could not reach the canvas server.' },
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...to, present: false }),
+    },
+  );
+  if (!result.ok) presentationError.value = result.error ?? 'Could not change the tour stop.';
+}
+
+/** Present from the first stop, or resume where the tour already is (`?present=1`). */
+export async function startPresentation(resume = false): Promise<void> {
+  presenting.value = true;
+  presentationError.value = '';
+  const at = resume
+    ? (await requestJson<{ position?: number | null }>('read tour', '/api/canvas/tour', {})).position
+    : null;
+  await stepTour({ stop: typeof at === 'number' ? at : 0 });
+}
+
+export function endPresentation(): void {
+  presenting.value = false;
+  presentationError.value = '';
+  void requestBestEffort('exit tour', '/api/canvas/tour/exit', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{}',
+  });
+}

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

@@ -0,0 +1,81 @@
+import { computed, effect, signal } from '@preact/signals';
+import { relationKind, relationPreset, relationSourceEnd } from '../../shared/relations.js';
+import { activeBoard, activeBoardId } from './boards-store';
+import { activeNodeId, edges, nodes, selectedNodeIds } from './canvas-store';
+
+export const relationFilter = signal<{ boardId: string; kind: string } | null>(null);
+
+effect(() => {
+  const filter = relationFilter.value;
+  if (
+    filter?.boardId === activeBoardId.value &&
+    ![...edges.value.values()].some((edge) => relationKind(edge) === filter.kind)
+  ) {
+    relationFilter.value = null;
+  }
+});
+
+// Hover is for hints, not for changing which cards remain readable.
+export const relationFocus = computed(() => activeNodeId.value);
+
+/** View-only highlights. They never infer evidence, change a decision or execute a flow. */
+export const relationHighlight = computed(() => {
+  const preset = relationPreset(activeBoard()?.relationVocabulary);
+  const focus = relationFocus.value;
+  const kind = relationFilter.value?.boardId === activeBoardId.value ? relationFilter.value.kind : null;
+  const list = [...edges.value.values()].filter((edge) => !edge.toBoardId || edge.toBoardId === activeBoardId.value);
+  const focusedCards = new Set(selectedNodeIds.value);
+  if (focus) focusedCards.add(focus);
+  if (focusedCards.size === 0 && !kind) return null;
+  // Selecting a frame focuses its contents too, including nested groups.
+  for (const id of focusedCards) {
+    const node = nodes.value.get(id);
+    if (node?.type === 'group' && Array.isArray(node.data.children))
+      for (const child of node.data.children) if (typeof child === 'string') focusedCards.add(child);
+  }
+  const cards = new Set(focusedCards);
+  const links = new Set<string>();
+  const add = (edge: (typeof list)[number]) => {
+    links.add(edge.id);
+    cards.add(edge.from);
+    cards.add(edge.to);
+  };
+  if (!kind) for (const edge of list) if (focusedCards.has(edge.from) && focusedCards.has(edge.to)) add(edge);
+  if (kind) {
+    for (const edge of list) if (relationKind(edge) === kind) add(edge);
+  } else if (preset === 'Dependencies' || preset === 'Decision') {
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const edge of list) {
+        if (links.has(edge.id)) continue;
+        const source = relationSourceEnd(edge);
+        const follows =
+          preset === 'Dependencies'
+            ? source && cards.has(source === 'from' ? edge.from : edge.to)
+            : ['option', 'if', 'chosen'].includes(relationKind(edge)) && cards.has(edge.to);
+        if (follows) {
+          add(edge);
+          changed = true;
+        }
+      }
+    }
+  } else if (preset === 'Flow') {
+    const progressed = new Set<string>();
+    for (const node of nodes.value.values())
+      if (['done', 'in-progress', 'blocked'].includes(String(node.data.axWorkStatus))) {
+        progressed.add(node.id);
+        cards.add(node.id);
+      }
+    for (const edge of list)
+      if (['flow', 'next', 'if-fails', 'loop'].includes(relationKind(edge)) && progressed.has(edge.from)) add(edge);
+  } else {
+    for (const edge of list)
+      if (
+        (focusedCards.has(edge.from) || focusedCards.has(edge.to)) &&
+        (preset !== 'Research' || ['supports', 'contradicts', 'cites', 'derived-from'].includes(relationKind(edge)))
+      )
+        add(edge);
+  }
+  return { cards, links };
+});