pmx-canvas 0.10.0 → 0.12.0

package/src/server/ax-state-manager.ts

@@ -137,9 +137,18 @@ function logAxStateWarning(action: string, error: unknown, details?: Record<stri
 
 export class AxStateManager {
   private _axState: PmxAxState = createEmptyAxState();
-  private _axHostCapability: PmxAxHostCapability | null = null;
 
-  constructor(private readonly deps: AxStateManagerDeps) {}
+  constructor(
+    private readonly deps: AxStateManagerDeps,
+    private readonly host: { capability: PmxAxHostCapability | null } = { capability: null },
+  ) {}
+
+  private get _axHostCapability() {
+    return this.host.capability;
+  }
+  private set _axHostCapability(value: PmxAxHostCapability | null) {
+    this.host.capability = value;
+  }
 
   // ── Normalization (against the owner's current node set) ──────────
   private normalizeForCurrentNodes(state: unknown): PmxAxState {
@@ -1088,7 +1097,9 @@ export class AxStateManager {
    * whose source equals the consumer to prevent delivery loops (e.g. Copilot
    * should not be handed back steering it originated).
    */
-  getPendingSteering(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+  getPendingSteering(
+    options: { consumer?: string; limit?: number; addressedOnly?: boolean; offset?: number } = {},
+  ): PmxAxSteeringMessage[] {
     const db = this.deps.getDb();
     return db ? loadPendingAxSteeringFromDB(db, options) : [];
   }
@@ -1098,7 +1109,9 @@ export class AxStateManager {
    * #57) — so a fresh steer is visible even behind a long backlog. Loop-safe like
    * getPendingSteering, but ordered DESC instead of the FIFO ASC delivery queue.
    */
-  getPendingSteeringForContext(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+  getPendingSteeringForContext(
+    options: { consumer?: string; limit?: number; addressedOnly?: boolean; offset?: number } = {},
+  ): PmxAxSteeringMessage[] {
     const db = this.deps.getDb();
     return db ? loadNewestPendingAxSteeringFromDB(db, options) : [];
   }

package/src/server/ax-wait.ts

@@ -24,7 +24,8 @@ export async function waitForAxResolution<T extends { status: string }>(opts: {
   signal?: AbortSignal;
 }): Promise<AxWaitResult<T>> {
   opts.signal?.throwIfAborted();
-  const { read, isResolved } = opts;
+  const read = canvasState.bindBoard(opts.read);
+  const { isResolved } = opts;
   const timeoutMs = Math.max(0, Math.min(opts.timeoutMs, AX_WAIT_MAX_MS));
   const pendingOf = (v: T | null): boolean => (v ? !isResolved(v) : false);
 
@@ -40,13 +41,18 @@ export async function waitForAxResolution<T extends { status: string }>(opts: {
       done = true;
       clearTimeout(timer);
       dispose();
+      disposeOwner();
       opts.signal?.removeEventListener('abort', onAbort);
       if (opts.signal?.aborted) {
         reject(opts.signal.reason);
         return;
       }
-      const v = read();
-      resolve({ value: v, pending: pendingOf(v) });
+      try {
+        const v = read();
+        resolve({ value: v, pending: pendingOf(v) });
+      } catch (error) {
+        reject(error);
+      }
     };
     const onAbort = finish;
     const check = (type: string): void => {
@@ -56,6 +62,9 @@ export async function waitForAxResolution<T extends { status: string }>(opts: {
     };
     const timer = setTimeout(finish, timeoutMs);
     const dispose = canvasState.onChange(check);
+    const disposeOwner = canvasState.onBoardDispose(() => {
+      finish();
+    });
     opts.signal?.addEventListener('abort', onAbort, { once: true });
     if (opts.signal?.aborted) finish();
   });
@@ -77,7 +86,8 @@ export async function waitForAxCondition(opts: {
 }): Promise<void> {
   opts.signal?.throwIfAborted();
   const timeoutMs = Math.max(0, Math.min(opts.timeoutMs, AX_WAIT_MAX_MS));
-  if (timeoutMs === 0 || opts.ready()) return;
+  const ready = canvasState.bindBoard(opts.ready);
+  if (timeoutMs === 0 || ready()) return;
   const channel = opts.channel ?? 'ax-timeline';
   await new Promise<void>((resolve, reject) => {
     let done = false;
@@ -86,6 +96,7 @@ export async function waitForAxCondition(opts: {
       done = true;
       clearTimeout(timer);
       dispose();
+      disposeOwner();
       opts.signal?.removeEventListener('abort', finish);
       if (opts.signal?.aborted) {
         reject(opts.signal.reason);
@@ -94,10 +105,13 @@ export async function waitForAxCondition(opts: {
       resolve();
     };
     const check = (type: string): void => {
-      if (type === channel && opts.ready()) finish();
+      if (type === channel && ready()) finish();
     };
     const timer = setTimeout(finish, timeoutMs);
-    const dispose = canvasState.onChange(check);
+    // Steering is workspace-wide and can be sent from another board. Keep
+    // ready() bound to its owner but listen outside the board-specific filter.
+    const dispose = canvasState.withVisibleBoard(() => canvasState.onChange(check));
+    const disposeOwner = canvasState.onBoardDispose(finish);
     opts.signal?.addEventListener('abort', finish, { once: true });
     if (opts.signal?.aborted) finish();
   });

package/src/server/board-export.ts

@@ -12,7 +12,8 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { Marked, Renderer, type RendererThis, type Tokens } from 'marked';
-import { canvasThemeScheme } from '../shared/themes.js';
+import { isWorkCardState, WORK_CARD_STATES } from '../shared/ax-kinds.js';
+import { canvasThemeScheme, normalizeCanvasThemeName, type CanvasThemeName } from '../shared/themes.js';
 import { delimiterForPath, parseDelimitedText } from '../shared/delimited-text.js';
 import { buildJsonRenderViewerHtml, escapeInlineScriptSource, readJsonRenderBundle } from '../json-render/server.js';
 import type { JsonRenderSpec } from '../json-render/server.js';
@@ -58,6 +59,7 @@ interface ExportCard {
   w: number;
   h: number;
   group?: true;
+  heading?: true;
   html?: string;
   frame?: string;
 }
@@ -66,7 +68,7 @@ interface Collected {
   manifest: ExportManifest;
   cards: ExportCard[];
   edges: CanvasEdge[];
-  scheme: 'dark' | 'light';
+  theme: CanvasThemeName;
   needsJsonRender: boolean;
   needsMermaid: boolean;
 }
@@ -207,9 +209,7 @@ async function collect(
   const read = canvasState.readBoard(boardId);
   if (!read) return null;
   const { board, state } = read;
-  const theme = canvasThemeScheme(state.theme ?? canvasState.theme);
-  // Exports collapse to a scheme; surface documents take the theme that draws it.
-  const surfaceTheme = theme === 'light' ? 'daylight' : 'harbor';
+  const theme = normalizeCanvasThemeName(state.theme ?? canvasState.theme);
   const remoteImages = new Set<string>();
   const links = new Set<string>();
   const frameNetworkDestinations = new Set<string>();
@@ -278,15 +278,28 @@ async function collect(
         card.group = true;
         break;
       case 'markdown':
+        if (data.display === 'heading') card.heading = true;
         card.html = `<div class="md">${await markdown.parse(text(data.content))}</div>`;
         break;
       case 'status':
-        card.html = rows([
-          ['Phase', text(data.phase).trim() || text(data.content).trim() || text(data.status).trim() || 'idle'],
-          ['Message', data.message],
-          ['Detail', data.detail],
-          ['Active tool', data.activeTool],
-        ]);
+        if (typeof data.workItemId === 'string' && data.liveWorkAvailable === false) {
+          placeholder('Task unavailable. The linked task is no longer on this board.');
+          break;
+        }
+        card.html = isWorkCardState(data.workState)
+          ? rows([
+              ['Task view', typeof data.workItemId === 'string' ? 'Read-only snapshot of linked task' : undefined],
+              ['Task source', typeof data.workItemId === 'string' ? data.liveWorkSource : undefined],
+              ['Work state', WORK_CARD_STATES[data.workState].label],
+              ['Detail', data.detail],
+              ['Progress', typeof data.progress === 'number' ? `${data.progress}%` : undefined],
+            ])
+          : rows([
+              ['Phase', text(data.phase).trim() || text(data.content).trim() || text(data.status).trim() || 'idle'],
+              ['Message', data.message],
+              ['Detail', data.detail],
+              ['Active tool', data.activeTool],
+            ]);
         break;
       case 'context': {
         const items = Array.isArray(data.cards) ? (data.cards as Array<Record<string, unknown>>) : [];
@@ -385,8 +398,7 @@ async function collect(
         const html = text(data.html) || text(data.content);
         collectFrameNetworkDestinations(html, frameNetworkDestinations);
         manifest.frames += 1;
-        if (withFrames)
-          card.frame = buildHtmlSurfaceDocument(html, { theme: surfaceTheme, title, inlineThemeCss: themeCss });
+        if (withFrames) card.frame = buildHtmlSurfaceDocument(html, { theme, title, inlineThemeCss: themeCss });
         break;
       }
       case 'mermaid':
@@ -398,7 +410,7 @@ async function collect(
               '<script src="/canvas/mermaid-entry.js"></script>',
               `<script src="${MERMAID_SRC}"></script>`,
             ),
-            { theme: surfaceTheme, title, inlineThemeCss: themeCss },
+            { theme, title, inlineThemeCss: themeCss },
           );
         }
         break;
@@ -415,7 +427,8 @@ async function collect(
             title,
             spec: data.spec as JsonRenderSpec,
             theme,
-            display: 'site',
+            // The saved card owns the viewport, just as on the live canvas.
+            // Omitting display selects embedded layout and its duplicate-title policy.
           });
         }
         break;
@@ -444,7 +457,7 @@ async function collect(
   manifest.links = [...links];
   manifest.frameNetworkDestinations = [...frameNetworkDestinations];
   manifest.embeddedCodeCanAccessNetwork = manifest.frames > 0;
-  return { manifest, cards, edges: state.edges, scheme: theme, needsJsonRender, needsMermaid };
+  return { manifest, cards, edges: state.edges, theme, needsJsonRender, needsMermaid };
 }
 
 /** What an export of `boardId` would put in the file, without building it. */
@@ -467,7 +480,7 @@ export async function buildBoardExport(
 ): Promise<{ html: string; manifest: ExportManifest } | null> {
   const collected = await collect(boardId, includeFiles, true, includeDerivedText);
   if (!collected) return null;
-  const { manifest, cards, edges: snapshotEdges, scheme, needsJsonRender, needsMermaid } = collected;
+  const { manifest, cards, edges: snapshotEdges, theme, needsJsonRender, needsMermaid } = collected;
 
   // Store each viewer bundle once; frames reference it by placeholder.
   const assets: Record<string, string> = {};
@@ -496,7 +509,7 @@ export async function buildBoardExport(
   const exportedAt = new Date().toISOString();
   const html = exportPage({
     title: manifest.boardName,
-    scheme,
+    theme,
     exportedAt,
     board: { cards, edges },
     assets,
@@ -536,7 +549,7 @@ export function exportsFolder(): string | null {
 
 function exportPage(input: {
   title: string;
-  scheme: 'dark' | 'light';
+  theme: CanvasThemeName;
   exportedAt: string;
   board: {
     cards: ExportCard[];
@@ -545,14 +558,22 @@ function exportPage(input: {
   assets: Record<string, string>;
 }): string {
   const date = new Date(input.exportedAt).toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' });
+  // Use the workbench's shipped faces and shared palette without offline requests.
+  const fonts = (readAsset('global.css').match(/@font-face\s*\{[^}]*\}/g) ?? [])
+    .join('\n')
+    .replace(
+      /url\("fonts\/([\w.-]+\.woff2)"\)/g,
+      (_, file: string) =>
+        `url("data:font/woff2;base64,${readFileSync(join(canvasBundleDir(), 'fonts', file)).toString('base64')}")`,
+    );
   return `<!doctype html>
-<html lang="en" data-scheme="${input.scheme}">
+<html lang="en" data-scheme="${canvasThemeScheme(input.theme)}" data-theme="${input.theme}">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="PMX Canvas">
 <title>${escapeHtml(input.title)}</title>
-<style>${EXPORT_CSS}</style>
+<style>${fonts}\n${readAsset('surface-theme.css')}\n${EXPORT_CSS}</style>
 </head>
 <body>
 <header class="bar">
@@ -574,10 +595,9 @@ function exportPage(input: {
 }
 
 const EXPORT_CSS = `
-:root{--bg:#0b1016;--panel:#121a23;--line:#263241;--text:#e8edf2;--soft:#9aa7b4;--accent:#4bbcff;--add:#2ea66f;--del:#e25d6e}
-[data-scheme=light]{--bg:#f4f6f8;--panel:#ffffff;--line:#d5dbe1;--text:#17202a;--soft:#5b6875;--accent:#0a6fc2;--add:#1c7a4f;--del:#b3263a}
+:root{--bg:var(--c-bg);--panel:var(--c-panel);--line:var(--c-line);--text:var(--c-text);--soft:var(--c-muted);--accent:var(--c-accent);--add:var(--c-ok);--del:var(--c-danger)}
 *{box-sizing:border-box}
-html,body{margin:0;height:100%;background:var(--bg);color:var(--text);font:15px/1.65 system-ui,-apple-system,Segoe UI,sans-serif}
+html,body{margin:0;height:100%;background:var(--bg);color:var(--text);font:13px/1.6 var(--font-ui)}
 .bar{position:fixed;top:0;left:0;right:0;height:48px;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:0 16px;background:var(--panel);border-bottom:1px solid var(--line);z-index:5}
 .bar .name{display:flex;flex-direction:column;min-width:0}
 .bar .name strong,.bar .name span{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
@@ -592,12 +612,16 @@ button:focus-visible,a:focus-visible,[tabindex]:focus-visible{outline:2px solid
 #edges{position:absolute;left:0;top:0;overflow:visible;pointer-events:none}
 #edges line{stroke:var(--soft);stroke-width:1.5}
 #edges text{fill:var(--soft);font-size:12px;text-anchor:middle}
-.card{position:absolute;display:flex;flex-direction:column;background:var(--panel);border:1px solid var(--line);border-radius:10px;overflow:hidden;box-shadow:0 6px 24px rgba(0,0,0,.18)}
+.card{position:absolute;display:flex;flex-direction:column;background:var(--panel);border:1px solid var(--line);border-radius:var(--r-node);overflow:hidden;box-shadow:var(--e-1)}
 .card.group{background:color-mix(in srgb,var(--accent) 5%,transparent);border-style:dashed;box-shadow:none}
-.card-title{position:relative;flex-shrink:0;width:100%;text-align:left;padding:12px 42px 12px 18px;font-weight:600;font-size:13px;border:0;border-bottom:1px solid var(--line);border-radius:0;cursor:zoom-in;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;background:color-mix(in srgb,var(--soft) 5%,var(--panel))}
+.card-title{position:relative;flex-shrink:0;width:100%;text-align:left;padding:7px 38px 7px 12px;font-weight:600;font-size:12px;line-height:22px;border:0;border-bottom:1px solid var(--line);border-radius:0;cursor:zoom-in;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;background:transparent}
 button.card-title:after{content:'↗';position:absolute;right:16px;color:var(--soft);font-size:16px}
 .card.group .card-title{border-bottom:none;cursor:default;color:var(--soft)}
-.card-body{flex:1;min-height:0;min-width:0;overflow:auto;padding:20px;overflow-wrap:anywhere;overscroll-behavior:contain;cursor:auto}
+.card-body{flex:1;min-height:0;min-width:0;overflow:auto;padding:10px 14px;font-size:var(--fs-ui);color:var(--c-text-soft);overflow-wrap:anywhere;overscroll-behavior:contain;cursor:auto}
+.card.heading{background:transparent;border-color:transparent;box-shadow:none}
+.card.heading .card-title{padding:8px 38px 0 16px;border:0;font-size:var(--fs-heading);line-height:28px;letter-spacing:-.01em}
+.card.heading .card-body{padding:0 16px 8px;color:var(--soft)}
+.card.heading:not(:hover):not(:focus-within) .card-title:after{visibility:hidden}
 .card-body>:first-child,.md>:first-child{margin-top:0}.card-body>:last-child,.md>:last-child{margin-bottom:0}
 .card iframe,#overlay-body iframe{flex:1;min-height:0;width:100%;height:100%;border:0;background:var(--bg)}
 .md h1,.md h2,.md h3,.md h4,.md h5,.md h6{margin:1.4em 0 .6em;line-height:1.3;font-weight:650;letter-spacing:-.02em}
@@ -607,7 +631,7 @@ button.card-title:after{content:'↗';position:absolute;right:16px;color:var(--s
 .md input[type=checkbox]{accent-color:var(--accent);margin-right:.5em}
 .md blockquote{margin:1em 0;padding:10px 16px;border-left:3px solid var(--accent);background:color-mix(in srgb,var(--accent) 7%,var(--panel));color:var(--soft)}
 .md blockquote>:last-child{margin-bottom:0}.md hr{border:0;border-top:1px solid var(--line);margin:24px 0}
-.md code,pre{font:13px/1.65 ui-monospace,SFMono-Regular,Menlo,monospace;tab-size:2}
+.md code,pre{font:13px/1.65 var(--font-code);tab-size:2}
 .md :not(pre)>code{padding:2px 5px;border:1px solid var(--line);border-radius:4px;background:color-mix(in srgb,var(--soft) 8%,var(--panel))}
 pre{margin:0 0 16px;padding:14px 16px;border:1px solid var(--line);border-radius:8px;background:color-mix(in srgb,var(--soft) 5%,var(--panel));white-space:pre;overflow:auto;overflow-wrap:normal;overscroll-behavior:contain}
 .prose{white-space:pre-wrap}.table-scroll{width:100%;max-width:100%;overflow:auto;margin:16px 0;border:1px solid var(--line);border-radius:8px;overscroll-behavior:contain}
@@ -629,7 +653,7 @@ details{margin-top:16px}summary{cursor:pointer;color:var(--soft);margin-bottom:1
 #overlay .sheet{width:min(1100px,100%);height:min(90vh,100%);display:flex;flex-direction:column;background:var(--panel);border:1px solid var(--line);border-radius:12px;overflow:hidden}
 #overlay .sheet>header{display:flex;justify-content:space-between;align-items:center;padding:10px 14px;border-bottom:1px solid var(--line)}
 #overlay-body{flex:1;min-height:0;overflow:hidden;display:flex;flex-direction:column}
-#overlay-body .card-body{padding:28px 32px}#overlay-body .md{max-width:960px;margin:0 auto}
+#overlay-body .card-body{padding:28px 32px;font-size:15px}#overlay-body .md{max-width:960px;margin:0 auto}
 @media(max-width:600px){#overlay{padding:8px}#overlay .sheet{height:100%}#overlay-body .card-body{padding:18px}.bar{padding:0 10px}.bar .name span{display:none}}
 `;
 
@@ -660,7 +684,7 @@ const body = (card) => {
 const ordered = [...board.cards].sort((a, b) => (b.group ? 1 : 0) - (a.group ? 1 : 0));
 for (const card of ordered) {
   const el = document.createElement('section');
-  el.className = 'card' + (card.group ? ' group' : '');
+  el.className = 'card' + (card.group ? ' group' : '') + (card.heading ? ' heading' : '');
   el.dataset.nodeId = card.id;
   el.dataset.nodeType = card.kind;
   Object.assign(el.style, { left: card.x + 'px', top: card.y + 'px', width: card.w + 'px', height: card.h + 'px' });

package/src/server/board-local.ts

@@ -0,0 +1,20 @@
+import { canvasState } from './canvas-state.js';
+
+/** Board-owned runtime state, discarded with its owner rather than on navigation. */
+export function createBoardLocal<T>(create: () => T, dispose?: (value: T) => void) {
+  // Hoisted for canvas-state's mutation-history dependency; access the owner only on read.
+  const values = new WeakMap<object, T>();
+  return {
+    get current(): T {
+      const owner = canvasState.boardIdentity;
+      let value = values.get(owner);
+      if (value === undefined) {
+        value = create();
+        values.set(owner, value);
+        const created = value;
+        canvasState.onBoardDispose(() => dispose?.(created));
+      }
+      return value;
+    },
+  };
+}

package/src/server/board-move.ts

@@ -0,0 +1,297 @@
+import type { ActorAttribution } from './attribution.js';
+import { createEmptyAxState } from './ax-state.js';
+import type { CanvasBoard, PersistedCanvasState } from './canvas-db.js';
+import type { CanvasNodeState } from './canvas-state.js';
+import type { DocumentImport } from './document-import.js';
+import { OperationError } from './operations/types.js';
+
+export interface BoardMoveInput {
+  sourceBoardId: string;
+  nodeIds: string[];
+  name: string;
+  expectedRevision: number;
+  requestId: string;
+  preview?: boolean;
+}
+
+export interface BoardMovePreview {
+  sourceBoardId: string;
+  nodeIds: string[];
+  affectedBoardIds: string[];
+  readmeNodeId: string | null;
+  pinnedNodeIds: string[];
+  liveTaskNodeIds: string[];
+  attachmentIds: string[];
+  blockers: string[];
+  notices: string[];
+}
+
+export interface BoardMoveResult {
+  sourceBoardId: string;
+  destinationBoardId: string;
+  portalId: string;
+  nodeIds: string[];
+  affectedBoardIds: string[];
+}
+
+export interface MoveBoard {
+  board: CanvasBoard;
+  state: PersistedCanvasState;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+function attachmentId(node: CanvasNodeState): string | undefined {
+  const value = node.data.attachmentId ?? record(node.data.source)?.attachmentId;
+  return typeof value === 'string' ? value : undefined;
+}
+
+/** Pure relocation plan. Preview and commit run the same checks on a consistent library view. */
+export function prepareBoardMove(
+  input: BoardMoveInput,
+  library: Map<string, MoveBoard>,
+  destinationId: string,
+  portalId: string,
+  imports: DocumentImport[],
+  runtimeBlockers: ReadonlyMap<string, string>,
+  actor: ActorAttribution,
+  at: string,
+): { preview: BoardMovePreview; states: Map<string, PersistedCanvasState> } {
+  const source = library.get(input.sourceBoardId);
+  if (!source) throw new OperationError('Source board not found.', 404);
+  if (input.expectedRevision !== (source.state.revisionState?.revision ?? 0))
+    throw new OperationError('The source board changed. Preview the move again.', 409);
+  if (!input.nodeIds.length) throw new OperationError('Select at least one card to move.');
+  const nodes = new Map(source.state.nodes.map((node) => [node.id, node]));
+  const moving = new Set<string>();
+  const include = (id: string) => {
+    if (moving.has(id)) return;
+    const node = nodes.get(id);
+    if (!node) throw new OperationError(`Selected card "${id}" no longer exists.`, 409);
+    moving.add(id);
+    if (node.type === 'group') {
+      for (const child of strings(node.data.children)) include(child);
+      for (const child of nodes.values()) if (child.data.parentGroup === id) include(child.id);
+    }
+  };
+  for (const id of input.nodeIds) include(id);
+  const blockers = new Set<string>();
+  const movedAttachments = new Set<string>();
+  const liveTasks: string[] = [];
+  const blocks = (id: string, reason: string) => blockers.add(`${id}: ${reason}`);
+  for (const node of source.state.nodes) {
+    const moves = moving.has(node.id);
+    const data = node.data;
+    if (moves) {
+      const runtime = runtimeBlockers.get(node.id);
+      if (runtime) blocks(node.id, runtime);
+      if (
+        data.streamStatus === 'open' ||
+        data._activeResponseId ||
+        (['prompt', 'response'].includes(node.type) &&
+          ['pending', 'sending', 'streaming'].includes(String(data.threadStatus ?? data.status)))
+      )
+        blocks(node.id, 'finish the active producer before moving this card');
+      if (
+        (node.type === 'context' && node.id === 'context-main') ||
+        (node.type === 'status' && node.id === 'status-main')
+      )
+        blocks(node.id, 'this presentation is owned by the host adapter');
+      if (data.appSessionId || data.transportConfig || data.sessionStatus === 'reconnecting')
+        blocks(node.id, 'the external app binding cannot be relocated without reconnecting');
+      if (data.workboard || data.axStep || data.axFlow || data.axFlowId)
+        blocks(node.id, 'materialized task/flow controls retain authority on this board');
+      if (node.type === 'status' && typeof data.workItemId === 'string') liveTasks.push(node.id);
+      const attachment = attachmentId(node);
+      if (attachment) movedAttachments.add(attachment);
+      if (
+        ['html', 'json-render', 'graph', 'mcp-app'].includes(node.type) &&
+        /ax[.:](work|approval|flow|elicitation|mode)|data-ax-|\/api\/canvas\/ax/.test(JSON.stringify(data))
+      )
+        blocks(node.id, 'embedded action targets cannot retain their board authority after this move');
+    }
+    // Declared local bindings are not opaque strings to rewrite. Both ends must move together.
+    const local = [
+      ...strings(data.embeddedNodeIds),
+      ...strings(data.contextNodeIds),
+      data.embeddedNodeId,
+      data.embeddedGraphId,
+      data.sourceNodeId,
+      data.promptNodeId,
+      data.responseNodeId,
+      data.parentNodeId,
+    ].filter((id): id is string => typeof id === 'string');
+    for (const text of [data.url, data.html, data.content, ...strings(data.embeddedUrls)]) {
+      if (typeof text !== 'string') continue;
+      for (const match of text.matchAll(/\/api\/canvas\/[^\s"'<>]+/g)) {
+        const url = new URL(match[0].replaceAll('&amp;', '&'), 'http://canvas.local');
+        let target =
+          url.pathname === '/api/canvas/json-render/view' || url.pathname === '/api/canvas/file-bytes'
+            ? url.searchParams.get('nodeId')
+            : url.pathname.match(/^\/api\/canvas\/image\/(.+)$/)?.[1];
+        if (url.pathname.startsWith('/api/canvas/surface/')) {
+          try {
+            target = decodeURIComponent(url.pathname.slice('/api/canvas/surface/'.length));
+          } catch {
+            // Malformed examples in authored text cannot resolve to a surface.
+            continue;
+          }
+        }
+        if (target) local.push(target);
+      }
+    }
+    for (const id of local)
+      if (moving.has(id) !== moves)
+        blocks(node.id, `include both ends of the local viewer/content reference to "${id}"`);
+  }
+  for (const node of source.state.nodes) {
+    const attachment = attachmentId(node);
+    if (attachment && movedAttachments.has(attachment) && !moving.has(node.id))
+      blocks(node.id, 'include every card sharing this attachment/import');
+  }
+  for (const job of imports) {
+    if (!movedAttachments.has(job.attachmentId) && !job.committedNodeIds.some((id) => moving.has(id))) continue;
+    if (job.status === 'requested' || job.status === 'drafted')
+      blocks(job.id, 'finish or cancel the document import first');
+    if (!movedAttachments.has(job.attachmentId) || job.committedNodeIds.some((id) => !moving.has(id)))
+      blocks(job.id, 'include the original attachment and every imported section');
+  }
+  for (const stop of source.state.tour?.stops ?? []) {
+    if ('nodeId' in stop.target && moving.has(stop.target.nodeId))
+      blocks(stop.target.nodeId, 'a source-board tour targets this card; remove that stop before moving');
+  }
+  const ax = source.state.ax ?? createEmptyAxState();
+  for (const item of [...ax.workItems, ...ax.approvalGates, ...ax.elicitations, ...ax.modeRequests]) {
+    for (const id of item.nodeIds)
+      if (moving.has(id)) blocks(id, `board-owned work/approval/input record "${item.id}" anchors this card`);
+  }
+  for (const review of ax.reviewAnnotations)
+    if (review.nodeId && moving.has(review.nodeId))
+      blocks(review.nodeId, `board-local review annotation "${review.id}" anchors this card`);
+
+  const states = new Map<string, PersistedCanvasState>();
+  const destination: PersistedCanvasState = {
+    version: 1,
+    theme: source.state.theme,
+    viewport: { x: 0, y: 0, scale: 1 },
+    nodes: [],
+    edges: [],
+    contextPins: [],
+    contextPinMeta: {},
+    annotations: [],
+    ax: createEmptyAxState(),
+  };
+  const locate = (boardId: string, cardId: string) =>
+    boardId === input.sourceBoardId && moving.has(cardId) ? destinationId : boardId;
+  for (const [boardId, entry] of library) {
+    const state = structuredClone(entry.state);
+    const prior = JSON.stringify(state);
+    state.edges = state.edges.flatMap((edge) => {
+      const owner = locate(boardId, edge.from);
+      const target = locate(edge.toBoardId ?? boardId, edge.to);
+      const next = { ...edge };
+      if (target === owner) delete next.toBoardId;
+      else next.toBoardId = target;
+      if (owner === destinationId) {
+        destination.edges.push(next);
+        return [];
+      }
+      return [next];
+    });
+    state.nodes = state.nodes.flatMap((node) => {
+      const data = node.data;
+      for (const link of Array.isArray(data.wikiLinks) ? data.wikiLinks : []) {
+        const target = record(record(link)?.target);
+        if (target?.boardId === input.sourceBoardId && typeof target.cardId === 'string' && moving.has(target.cardId))
+          target.boardId = destinationId;
+      }
+      const provenance = record(data.provenance);
+      for (const target of Array.isArray(provenance?.sources) ? provenance.sources : []) {
+        const ref = record(target);
+        if (ref?.boardId === input.sourceBoardId && typeof ref.cardId === 'string' && moving.has(ref.cardId))
+          ref.boardId = destinationId;
+      }
+      if (boardId !== input.sourceBoardId) return [node];
+      if (!moving.has(node.id)) {
+        if (node.type === 'group') data.children = strings(data.children).filter((id) => !moving.has(id));
+        return [node];
+      }
+      if (typeof data.parentGroup === 'string' && !moving.has(data.parentGroup)) delete data.parentGroup;
+      if (node.type === 'status' && typeof data.workItemId === 'string') data.workItemBoardId ??= input.sourceBoardId;
+      destination.nodes.push(node);
+      if (state.contextPins.includes(node.id)) {
+        destination.contextPins.push(node.id);
+        const meta = state.contextPinMeta?.[node.id];
+        if (meta) destination.contextPinMeta![node.id] = meta;
+      }
+      return [];
+    });
+    if (boardId === input.sourceBoardId) {
+      state.contextPins = state.contextPins.filter((id) => !moving.has(id));
+      for (const id of moving) if (state.contextPinMeta) delete state.contextPinMeta[id];
+      if (state.ax) {
+        state.ax.focus.nodeIds = state.ax.focus.nodeIds.filter((id) => !moving.has(id));
+        if (state.ax.focus.primaryNodeId && moving.has(state.ax.focus.primaryNodeId))
+          state.ax.focus.primaryNodeId = null;
+      }
+    }
+    if (prior !== JSON.stringify(state) || boardId === input.sourceBoardId) states.set(boardId, state);
+  }
+  const revision =
+    Math.max(
+      source.state.revisionState?.revision ?? 0,
+      ...destination.nodes.flatMap((node) => [node.contentRevision ?? 0, node.linksRevision ?? 0]),
+      ...destination.edges.map((edge) => edge.revision ?? 0),
+    ) + 1;
+  const selected = [...moving].map((id) => nodes.get(id)!);
+  states.get(input.sourceBoardId)!.nodes.push({
+    id: portalId,
+    type: 'board',
+    data: { boardId: destinationId, title: input.name },
+    position: {
+      x: Math.min(...selected.map((node) => node.position.x)),
+      y: Math.min(...selected.map((node) => node.position.y)),
+    },
+    size: { width: 360, height: 200 },
+    zIndex: Math.max(...selected.map((node) => node.zIndex)),
+    collapsed: false,
+    pinned: false,
+    createdBy: actor,
+    lastEditedBy: actor,
+    contentRevision: revision,
+    contentChangedAt: at,
+    freshnessStartedAt: at,
+  });
+  states.set(destinationId, destination);
+  for (const state of states.values()) {
+    const floor = Math.max(state.revisionState?.revision ?? 0, revision) + 1;
+    state.revisionState = { revision: floor, floor, tombstones: [] };
+  }
+  return {
+    states,
+    preview: {
+      sourceBoardId: input.sourceBoardId,
+      nodeIds: [...moving].sort(),
+      affectedBoardIds: [...states.keys()].filter((id) => id !== destinationId).sort(),
+      readmeNodeId:
+        source.board.readmeNodeId && moving.has(source.board.readmeNodeId) ? source.board.readmeNodeId : null,
+      pinnedNodeIds: destination.contextPins,
+      liveTaskNodeIds: liveTasks,
+      attachmentIds: [...movedAttachments],
+      blockers: [...blockers],
+      notices: [
+        'Moves the original cards and leaves a portal. This is not a copy.',
+        'Pre-move Undo/Redo is cleared on affected boards. Older snapshots remain inspectable but cannot be restored across the move.',
+        'Board-space annotations stay on the source. Live tasks keep their original owner.',
+      ],
+    },
+  };
+}