pmx-canvas 0.6.5 → 0.7.0

package/src/client/canvas/TopBar.tsx

@@ -1,3 +1,6 @@
+import { exportDialogOpen } from './ExportDialog';
+import { activeBoardId } from '../state/boards-store';
+import { BoardSwitcher } from './BoardSwitcher';
 import type { ComponentChildren } from 'preact';
 import { presenting } from '../state/presentation';
 import { useEffect, useState } from 'preact/hooks';
@@ -264,8 +267,8 @@ export function TopBar() {
   const isTraceOn = traceEnabled.value;
   const traceNodeCount = Array.from(nodes.value.values()).filter((n) => n.type === 'trace').length;
 
-  // Board identity = workspace basename, fetched once from /health. The
-  // canvas has no board-name concept — the workspace IS the board.
+  // Until the board list arrives, the switcher shows the workspace basename
+  // (fetched once from /health).
   const [workspaceName, setWorkspaceName] = useState<string>('');
   useEffect(() => {
     let cancelled = false;
@@ -314,9 +317,7 @@ export function TopBar() {
       >
         <span class={`connection-dot ${degraded ?? status}`} aria-label={`Canvas status: ${statusTitle}`} />
       </BarHint>
-      <span class="top-bar-title" title={workspaceName || 'PMX Canvas'}>
-        {workspaceName || 'PMX Canvas'}
-      </span>
+      <BoardSwitcher fallbackName={workspaceName || 'PMX Canvas'} />
       <span class="top-bar-meta hud-collapsible-text">{sessionId.value ? sessionId.value.slice(0, 12) : '…'}</span>
       <span class="top-bar-meta hud-collapsible-text">{countsLabel}</span>
 
@@ -330,20 +331,35 @@ export function TopBar() {
 
       <div class="top-bar-sep" />
 
-      <BarHint
-        label="Present board"
-        body="Arrow keys or Space step through stops; Esc exits. Without a saved tour, groups are read top-to-bottom, left-to-right."
-      >
-        <button
-          type="button"
-          class="present-button"
-          onClick={() => {
-            presenting.value = true;
-          }}
+      {activeBoardId.value && (
+        <BarHint label="Export board" body="One HTML file of this board that anyone can open, no install needed.">
+          <button
+            type="button"
+            class="present-button"
+            onClick={() => {
+              exportDialogOpen.value = true;
+            }}
+          >
+            Export
+          </button>
+        </BarHint>
+      )}
+      {activeBoardId.value && (
+        <BarHint
+          label="Present board"
+          body="Arrow keys or Space step through stops; Esc exits. Without a saved tour, groups are read top-to-bottom, left-to-right."
         >
-          Present
-        </button>
-      </BarHint>
+          <button
+            type="button"
+            class="present-button"
+            onClick={() => {
+              presenting.value = true;
+            }}
+          >
+            Present
+          </button>
+        </BarHint>
+      )}
       <BarHint label="Zoom out" shortcut={modChord('\u2212')}>
         <button type="button" class="top-bar-btn" onClick={() => zoomByFactor(1 / 1.25)} aria-label="Zoom out">
           <IconZoomOut />

package/src/client/canvas/import-files.ts

@@ -1,4 +1,6 @@
-import { createNodeFromClient } from '../state/intent-bridge';
+import { createNodeFromClient, requestJson } from '../state/intent-bridge';
+import { activeBoardId } from '../state/boards-store';
+import { showToast } from '../state/attention-bridge';
 
 const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'bmp', 'ico', 'avif']);
 const MD_EXTS = new Set(['md', 'mdx', 'markdown']);
@@ -17,6 +19,7 @@ export function nodeTypeFromFilename(name: string): 'image' | 'markdown' | 'file
  * markdown, everything else a file node with the text inlined.
  */
 export async function importFiles(files: File[], baseWx: number, baseWy: number): Promise<void> {
+  const boardId = activeBoardId.value;
   const nodeW = 400;
   const nodeH = 300;
   const spacing = 20;
@@ -32,12 +35,24 @@ export async function importFiles(files: File[], baseWx: number, baseWy: number)
     const type = nodeTypeFromFilename(file.name);
     const fileName = file.name;
 
+    if (/\.(pdf|pptx?|xlsx?|docx?|od[pts])$/i.test(fileName)) {
+      if (!boardId || file.size === 0 || file.size > 20 * 1024 * 1024) {
+        showToast('remove', 'File not attached', 'Open a board and choose a nonempty file under 20 MiB.');
+        continue;
+      }
+      const query = new URLSearchParams({ boardId, name: fileName, mime: file.type, x: String(wx), y: String(wy) });
+      showToast('context', 'Attaching document', fileName);
+      await requestJson('attachDocument', `/api/canvas/attachments?${query}`, null, { method: 'POST', body: file });
+      continue;
+    }
+    if (activeBoardId.value !== boardId) return;
     if (type === 'image') {
       const reader = new FileReader();
       const dataUri: string = await new Promise((resolve) => {
         reader.onload = () => resolve(reader.result as string);
         reader.readAsDataURL(file);
       });
+      if (activeBoardId.value !== boardId) return;
       await createNodeFromClient({
         type: 'image',
         title: fileName,
@@ -46,9 +61,11 @@ export async function importFiles(files: File[], baseWx: number, baseWy: number)
         y: wy,
         width: nodeW,
         height: nodeH,
+        ...(boardId ? { boardId } : {}),
       });
     } else {
       const text = await file.text();
+      if (activeBoardId.value !== boardId) return;
       const isWide = type === 'markdown' || type === 'file';
       await createNodeFromClient({
         type,
@@ -58,6 +75,7 @@ export async function importFiles(files: File[], baseWx: number, baseWy: number)
         y: wy,
         width: isWide ? 720 : nodeW,
         height: isWide ? 500 : nodeH,
+        ...(boardId ? { boardId } : {}),
       });
     }
   }

package/src/client/canvas/kind-colors.ts

@@ -7,6 +7,7 @@ export const KIND_COLOR: Record<CanvasNodeState['type'], string> = {
   webpage: 'var(--c-warn)',
   'json-render': 'var(--c-ok)',
   graph: 'var(--c-purple)',
+  board: 'var(--c-accent)',
   prompt: 'var(--c-accent)',
   response: 'var(--c-ok)',
   status: 'var(--c-warn)',

package/src/client/icons.tsx

@@ -538,6 +538,8 @@ export function getNodeIcon(type: string): (p: IconProps) => JSX.Element {
       return IconNodeJsonRender;
     case 'graph':
       return IconNodeGraph;
+    case 'board':
+      return IconNodeGraph;
     case 'html':
       return IconNodeWebpage;
     default:

package/src/client/nodes/AttachmentNode.tsx

@@ -0,0 +1,148 @@
+import { useEffect, useState } from 'preact/hooks';
+import type { DocumentImport } from '../../server/document-import';
+import type { CanvasNodeState } from '../types';
+import { activeBoardId } from '../state/boards-store';
+import { requestJson } from '../state/intent-bridge';
+import { expandNode, collapseExpandedNode } from '../state/canvas-store';
+
+/** Originals stay useful even when the connected host cannot extract them. */
+export function AttachmentNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
+  const attachmentId = String(node.data.attachmentId);
+  const boardId = activeBoardId.value;
+  const [job, setJob] = useState<DocumentImport | null>(null);
+  const [review, setReview] = useState(expanded);
+  const [consent, setConsent] = useState(false);
+  const [busy, setBusy] = useState(false);
+  useEffect(() => {
+    let current = true;
+    const read = async () => {
+      const result = await requestJson<{ imports?: DocumentImport[] } | null>(
+        'readImports',
+        `/api/canvas/imports?boardId=${encodeURIComponent(boardId ?? '')}`,
+        null,
+      );
+      if (current) setJob(result?.imports?.find((entry) => entry.attachmentId === attachmentId) ?? null);
+    };
+    void read();
+    const timer = window.setInterval(() => void read(), 2000);
+    return () => {
+      current = false;
+      window.clearInterval(timer);
+    };
+  }, [attachmentId, boardId]);
+  useEffect(() => {
+    if (!review) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.stopPropagation();
+        setReview(false);
+      }
+    };
+    window.addEventListener('keydown', onKey, true);
+    return () => window.removeEventListener('keydown', onKey, true);
+  }, [review]);
+  const act = async (action: 'request' | 'cancel' | 'commit') => {
+    if (!job) return;
+    setBusy(true);
+    const result = await requestJson<{ import?: DocumentImport } | null>(
+      `import.${action}`,
+      `/api/canvas/imports/${job.id}/${action}`,
+      null,
+      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ consent: true }) },
+    );
+    setBusy(false);
+    if (result?.import) {
+      setJob(result.import);
+      setConsent(false);
+      setReview(false);
+      if (expanded && action === 'commit') collapseExpandedNode();
+    }
+  };
+  const canRequest = job && ['attached', 'cancelled', 'unavailable'].includes(job.status);
+  return (
+    <div class="attachment-node" onPointerDown={(event) => event.stopPropagation()}>
+      <div class="attachment-status">
+        {job?.status === 'requested'
+          ? 'Waiting for agent'
+          : job?.status === 'drafted'
+            ? 'Ready for review'
+            : job?.status === 'committed'
+              ? 'Markdown added'
+              : 'Original attached'}
+      </div>
+      <a href={`/api/canvas/attachments/${attachmentId}/bytes`} target="_blank" rel="noopener noreferrer">
+        Download original · {Math.ceil(Number(node.data.size ?? 0) / 1024)} KB
+      </a>
+      {job?.reason && <p>{job.reason}</p>}
+      {canRequest && !consent && (
+        <button type="button" class="home-board-action" onClick={() => setConsent(true)}>
+          Ask agent to import
+        </button>
+      )}
+      {consent && (
+        <>
+          <p>
+            The connected agent may send this file to its model provider. It needs file-reading tools and access to the
+            original. Canvas does not convert files itself.
+          </p>
+          <button type="button" class="home-board-action" disabled={busy} onClick={() => void act('request')}>
+            Allow processing & request
+          </button>
+          <button type="button" class="home-board-action" onClick={() => setConsent(false)}>
+            Not now
+          </button>
+        </>
+      )}
+      {job?.status === 'requested' && (
+        <p>
+          No automatic extraction. Ask your connected agent to check its pending steering or use canvas_import list.
+        </p>
+      )}
+      {job?.status === 'drafted' && (
+        <button
+          type="button"
+          class="home-board-action"
+          onClick={() => (expanded ? setReview(true) : expandNode(node.id))}
+        >
+          Review Markdown · {job.sections.length} {job.sections.length === 1 ? 'card' : 'cards'}
+        </button>
+      )}
+      {job && ['requested', 'drafted'].includes(job.status) && (
+        <button type="button" class="home-board-action" disabled={busy} onClick={() => void act('cancel')}>
+          Cancel import
+        </button>
+      )}
+      {review && job?.status === 'drafted' && (
+        <div class="attachment-review" role="dialog" aria-label="Review imported Markdown">
+          <h3>Review imported Markdown</h3>
+          <p>Source material, not instructions or verified knowledge. {job.agentDescription}</p>
+          {job.warnings.length > 0 && (
+            <ul>
+              {job.warnings.map((warning) => (
+                <li key={warning}>{warning}</li>
+              ))}
+            </ul>
+          )}
+          {job.sections.map((section, index) => (
+            <section key={index}>
+              <h4>{section.title}</h4>
+              <p>{section.reference || 'Source location not supplied'}</p>
+              <pre>{section.markdown}</pre>
+            </section>
+          ))}
+          <button type="button" class="home-board-action" onClick={() => setReview(false)}>
+            Close review
+          </button>
+          <button
+            type="button"
+            class="home-view-new"
+            disabled={busy || boardId !== job.boardId}
+            onClick={() => void act('commit')}
+          >
+            Add to board
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/nodes/BoardNode.tsx

@@ -0,0 +1,35 @@
+import type { CanvasNodeState } from '../types';
+import { boardList, openBoard } from '../state/boards-store';
+
+/** Native text-only cross-board link. Target identity is the durable board id. */
+export function BoardNode({ node }: { node: CanvasNodeState }) {
+  const boardId = typeof node.data.boardId === 'string' ? node.data.boardId : '';
+  const target = boardList.value.find((board) => board.id === boardId);
+  return (
+    <div class="board-node">
+      <div class="board-node-content">
+        <div class="board-node-label">Linked board</div>
+        <strong class="board-node-title">{target?.name ?? 'Missing board'}</strong>
+        <div class="board-node-meta">{target ? `${target.nodeCount} nodes` : boardId || 'No target id'}</div>
+        {target?.summary && <p class="board-node-summary">{target.summary}</p>}
+        {!!target?.pinnedTitles?.length && (
+          <p class="board-node-meta">Pinned: {target.pinnedTitles.map((pin) => pin.title).join(', ')}</p>
+        )}
+        {!!target?.backlinks?.length && (
+          <p class="board-node-meta">
+            Linked from: {[...new Set(target.backlinks.map((link) => link.title))].join(', ')}
+          </p>
+        )}
+      </div>
+      <button
+        class="board-node-open"
+        type="button"
+        disabled={!target}
+        onClick={() => target && void openBoard(target.id)}
+      >
+        {target ? 'Open board' : 'Target unavailable'}
+        {target && <span aria-hidden="true">↗</span>}
+      </button>
+    </div>
+  );
+}

package/src/client/nodes/FileNode.tsx

@@ -4,6 +4,7 @@ import { iframeMode } from '../state/iframe-mode';
 import { fetchFile, updateNodeFromClient } from '../state/intent-bridge';
 import type { CanvasNodeState } from '../types';
 import { runNodeAxInteraction } from './ax-node-actions';
+import { AttachmentNode } from './AttachmentNode';
 
 /** Guess a language label from a file extension for display. */
 function langFromPath(path: string): string {
@@ -134,6 +135,11 @@ export function formatBytes(bytes: number): string {
 }
 
 export function FileNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
+  if (typeof node.data.attachmentId === 'string') return <AttachmentNode node={node} expanded={expanded} />;
+  return <TextFileNode node={node} expanded={expanded} />;
+}
+
+function TextFileNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
   const filePath = (node.data.path as string) || (node.data.content as string) || '';
   const title = (node.data.title as string) || filePath.split('/').pop() || 'File';
   const cachedContent = node.data.fileContent as string | undefined;

package/src/client/nodes/MarkdownNode.tsx

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 import { expandNode, updateNodeData } from '../state/canvas-store';
 import { fetchFile, renderMarkdown, saveFile, updateNodeFromClient } from '../state/intent-bridge';
 import type { CanvasNodeState } from '../types';
+import { activeBoard, setBoardReadme } from '../state/boards-store';
 import { MdFormatBar } from './MdFormatBar';
 import { handleFormatShortcut, handleTab } from './md-format';
 import { InlineMarkdownEditor } from './InlineMarkdownEditor';
@@ -82,6 +83,7 @@ export function toggleTaskMarker(markdown: string, index: number): string {
 }
 
 export function MarkdownNode({ node, expanded = false }: { node: CanvasNodeState; expanded?: boolean }) {
+  const board = activeBoard();
   const path = node.data.path as string;
   const [content, setContent] = useState('');
   const [rendered, setRendered] = useState('');
@@ -362,26 +364,52 @@ export function MarkdownNode({ node, expanded = false }: { node: CanvasNodeState
   // ── Card preview ──────────────────────────────────────────────
 
   return (
-    <div style={{ height: '100%', position: 'relative' }}>
-      {reviewBanner}
-      <RenderedMarkdown
-        html={rendered}
-        style={{ padding: rendered ? '0' : '12px', color: rendered ? undefined : 'var(--c-dim)' }}
-        // Task checkboxes are live on the card itself — no need to expand to tick one.
-        onTaskToggle={(index) => {
-          const next = toggleTaskMarker(content, index);
-          if (next !== content) handleInlineSave(next);
-        }}
-      />
-      {!loaded && <div style={{ color: 'var(--c-dim)', fontStyle: 'italic', padding: '12px' }}>Loading…</div>}
-      {loaded && !rendered && (
-        <div style={{ color: 'var(--c-dim)', fontStyle: 'italic', padding: '12px' }}>Empty node</div>
+    <div class="md-card-preview">
+      <div class="md-card-content">
+        {reviewBanner}
+        <RenderedMarkdown
+          html={rendered}
+          style={{ padding: rendered ? '0' : '12px', color: rendered ? undefined : 'var(--c-dim)' }}
+          // Task checkboxes are live on the card itself — no need to expand to tick one.
+          onTaskToggle={(index) => {
+            const next = toggleTaskMarker(content, index);
+            if (next !== content) handleInlineSave(next);
+          }}
+        />
+        {!loaded && <div style={{ color: 'var(--c-dim)', fontStyle: 'italic', padding: '12px' }}>Loading…</div>}
+        {loaded && !rendered && (
+          <div style={{ color: 'var(--c-dim)', fontStyle: 'italic', padding: '12px' }}>Empty node</div>
+        )}
+      </div>
+      {node.data.source && typeof node.data.source === 'object' && 'attachmentId' in node.data.source && (
+        <div class="md-import-source">
+          Source material ·{' '}
+          <a
+            href={`/api/canvas/attachments/${encodeURIComponent(String(node.data.source.attachmentId))}/bytes`}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            {String((node.data.source as Record<string, unknown>).filename ?? 'Original')}
+          </a>
+          {' · '}
+          {String((node.data.source as Record<string, unknown>).reference ?? 'Location not supplied')}
+        </div>
       )}
-      {/* Hover-revealed, solid-backed chip — always-on it sat on the first
-          line of content (double-click edits inline; this is discovery). */}
-      <button type="button" class="md-edit-btn" onClick={() => expandNode(node.id)}>
-        Edit
-      </button>
+      <div class="md-card-actions">
+        {board && (
+          <button
+            type="button"
+            class="md-readme-btn"
+            aria-pressed={board.readmeNodeId === node.id}
+            onClick={() => void setBoardReadme(board.id, board.readmeNodeId === node.id ? null : node.id)}
+          >
+            {board.readmeNodeId === node.id ? 'README' : 'Set as README'}
+          </button>
+        )}
+        <button type="button" class="md-card-edit" onClick={() => expandNode(node.id)}>
+          Edit
+        </button>
+      </div>
     </div>
   );
 }

package/src/client/nodes/ax-node-actions.ts

@@ -19,11 +19,8 @@ export async function runNodeAxInteraction(
     sourceSurface: 'native-node',
     ...(payload ? { payload } : {}),
   });
-  if (res.ok) {
-    showToast('context', successTitle, '', [node.id]);
-  } else {
-    showToast('remove', 'AX action failed', res.error ?? res.code ?? 'Unknown error', [node.id]);
-  }
+  // A refusal is toasted by the bridge with the server's reason.
+  if (res.ok) showToast('context', successTitle, '', [node.id]);
 }
 
 /** Shared style for the small inline AX action button on native nodes. */

package/src/client/nodes/use-ax-surface-bridge.ts

@@ -50,8 +50,8 @@ export function useAxSurfaceBridge(options: {
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
+        // A refusal is toasted by the bridge with the server's reason.
         if (res.ok) showToast('context', 'AX interaction', interactionType, [nodeId]);
-        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
         iframeRef.current?.contentWindow?.postMessage(
           {
             source: AX_SURFACE_ACK_SOURCE,

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

@@ -0,0 +1,167 @@
+import { signal } from '@preact/signals';
+import { requestJson } from './intent-bridge';
+
+/**
+ * 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.
+ */
+export interface BoardSummary {
+  id: string;
+  name: string;
+  category: string | null;
+  createdAt: string;
+  lastOpenedAt: string | null;
+  nodeCount: number;
+  readmeNodeId?: string | null;
+  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 }>;
+}
+
+interface BoardsPayload {
+  activeBoardId: string | null;
+  boards: BoardSummary[];
+}
+
+export const boardList = signal<BoardSummary[]>([]);
+export const activeBoardId = signal<string | null>(null);
+/** 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 openRequestSequence = 0;
+let openRequestQueue: Promise<void> = Promise.resolve();
+
+/** The SSE bridge resyncs the canvas when the open board changes under it. */
+export function setBoardSwitchHandler(handler: (() => 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;
+  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?.();
+}
+
+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);
+}
+
+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, {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  return revision === boardsRevision ? payload : null;
+}
+
+/** Open a board, or Home with null. */
+export async function openBoard(id: string | null): Promise<void> {
+  const sequence = ++openRequestSequence;
+  const revision = boardsRevision;
+  let payload: BoardsPayload | null = null;
+  const request = openRequestQueue.then(async () => {
+    payload = await post('openBoard', '/api/canvas/boards/open', 'POST', { id }, revision);
+  });
+  openRequestQueue = request.catch(() => undefined);
+  await request;
+  // post drops replies superseded by SSE; also ignore an older open request.
+  if (sequence === openRequestSequence) applyBoards(payload);
+}
+
+export async function createAndOpenBoard(name: string): Promise<void> {
+  const sequence = ++openRequestSequence;
+  const created = await requestJson<{ board?: BoardSummary } | null>('createBoard', '/api/canvas/boards', null, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name }),
+  });
+  if (created?.board && sequence === openRequestSequence) await openBoard(created.board.id);
+}
+
+export interface BoardCopyCard {
+  id: string;
+  type: string;
+  title: string | null;
+  reusable: boolean;
+}
+
+export interface BoardCopyPreview {
+  sourceBoardId: string;
+  readmeNodeId: string | null;
+  cards: BoardCopyCard[];
+  edges: Array<{ id: string; from: string; to: string; type: string }>;
+}
+
+export async function previewBoardCopy(sourceBoardId: string): Promise<BoardCopyPreview | null> {
+  return requestJson<BoardCopyPreview | null>('previewBoardCopy', '/api/canvas/boards/from', null, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sourceBoardId, name: 'Preview', preview: true }),
+  });
+}
+
+export async function createBoardFrom(opts: {
+  sourceBoardId: string;
+  name: string;
+  category?: string;
+  nodeIds: string[];
+  includeReadme: boolean;
+  includeStructure: boolean;
+}): Promise<BoardSummary | null> {
+  const result = await requestJson<{ board?: BoardSummary } | null>(
+    'createBoardFrom',
+    '/api/canvas/boards/from',
+    null,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(opts),
+    },
+  );
+  await loadBoards();
+  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> {
+  const payload = await post('updateBoard', `/api/canvas/boards/${encodeURIComponent(id)}`, 'PATCH', {
+    ...patch,
+    ...(patch.category === null ? { category: '' } : {}),
+  });
+  applyBoards(payload);
+}
+
+export async function setBoardReadme(id: string, readmeNodeId: string | null): Promise<void> {
+  const payload = await post('setBoardReadme', `/api/canvas/boards/${encodeURIComponent(id)}`, 'PATCH', {
+    readmeNodeId,
+  });
+  applyBoards(payload);
+}
+
+export async function deleteBoard(id: string): Promise<void> {
+  const payload = await post('deleteBoard', `/api/canvas/boards/${encodeURIComponent(id)}`, 'DELETE');
+  applyBoards(payload);
+}
+
+export function activeBoard(): BoardSummary | null {
+  return boardList.value.find((board) => board.id === activeBoardId.value) ?? null;
+}