pmx-canvas 0.10.0 → 0.12.0

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,5 +1,7 @@
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { BarHint } from './BarHint';
+import { AttentionHistory } from './AttentionHistory';
+import { AttentionToast } from './AttentionToast';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
 import { DiffNode } from '../nodes/DiffNode';
@@ -242,8 +244,7 @@ export function ExpandedNodeOverlay() {
     };
   }, [handlePresentationKeyDown, presentationExitToken, presenting]);
 
-  // Focus trap (item 18): restore to the node this overlay opened from — its
-  // world element is unmounted while expanded and remounted on close.
+  // Restore to the same spatial card at every zoom.
   const panelRef = useRef<HTMLDivElement>(null);
   const restoreToNode = useCallback(
     () => (nodeId ? document.querySelector<HTMLElement>(`.canvas-node[data-node-id="${CSS.escape(nodeId)}"]`) : null),
@@ -398,6 +399,8 @@ export function ExpandedNodeOverlay() {
             {pendingClose ? 'Saving edits…' : 'esc or click outside to close'}
           </span>
         </div>
+        <AttentionToast />
+        <AttentionHistory />
         {canPresent && presenting && (
           <div
             ref={presentationOverlayRef}

package/src/client/canvas/GroupNavigation.tsx

@@ -0,0 +1,85 @@
+import { activeBoard } from '../state/boards-store';
+import { useLayoutEffect, useRef } from 'preact/hooks';
+import { reportClientViewportSize } from '../state/intent-bridge';
+import { focusNode, groupContents, groupPath, groupViewNodes, leaveGroup, nodes } from '../state/canvas-store';
+
+export function GroupBreadcrumbs() {
+  const path = groupPath.value;
+  const ref = useRef<HTMLElement>(null);
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    const resize = new ResizeObserver(() => void reportClientViewportSize());
+    resize.observe(element);
+    return () => resize.disconnect();
+  }, [path.length > 0]);
+  if (!path.length) return null;
+  return (
+    <nav
+      ref={ref}
+      class="group-breadcrumbs"
+      aria-label="Group navigation"
+      onPointerDown={(event) => event.stopPropagation()}
+    >
+      <button type="button" onClick={() => leaveGroup(0)}>
+        {activeBoard()?.name ?? 'Board'}
+      </button>
+      {path.map((visit, index) => (
+        <span key={visit.id}>
+          <span aria-hidden="true"> / </span>
+          <button
+            type="button"
+            aria-current={index === path.length - 1 ? 'location' : undefined}
+            disabled={index === path.length - 1}
+            onClick={() => leaveGroup(index + 1)}
+          >
+            {String(nodes.value.get(visit.id)?.data.title ?? 'Group')}
+          </button>
+        </span>
+      ))}
+      <button type="button" onClick={() => leaveGroup()} aria-label="Leave group">
+        Esc · goes up
+      </button>
+    </nav>
+  );
+}
+
+export function GroupOutsideLinks() {
+  const inside = groupContents.value;
+  if (!inside) return null;
+  const outside = [...groupViewNodes.value.values()].filter((node) => !inside.has(node.id));
+  const children = [...nodes.value.values()].filter((node) => inside.has(node.id));
+  const root = nodes.value.get(groupPath.value.at(-1)!.id)!;
+  const left = children.length ? Math.min(...children.map((node) => node.position.x)) - 24 : root.position.x;
+  const top = children.length ? Math.min(...children.map((node) => node.position.y)) - 40 : root.position.y;
+  const right = children.length
+    ? Math.max(...children.map((node) => node.position.x + node.size.width)) + 24
+    : left + 320;
+  const bottom = children.length
+    ? Math.max(...children.map((node) => node.position.y + node.size.height)) + 24
+    : top + 120;
+  return (
+    <>
+      <div class="group-inside-frame" style={{ left, top, width: right - left, height: bottom - top }}>
+        <span>Inside {String(root.data.title ?? 'Group')}</span>
+      </div>
+      {outside.map((node, index) => (
+        <div key={node.id} class="group-outside-endpoint" style={{ left: node.position.x, top: node.position.y }}>
+          {index === 0 && <span class="group-outside-label">Outside</span>}
+          <button
+            type="button"
+            class="group-outside-stub"
+            onPointerDown={(event) => event.stopPropagation()}
+            onClick={(event) => {
+              event.stopPropagation();
+              focusNode(node.id, { recordHistory: false, persistStacking: false });
+            }}
+          >
+            ↗ {String(node.data.title ?? node.type)}
+            <span>{node.type} · Show on canvas</span>
+          </button>
+        </div>
+      ))}
+    </>
+  );
+}

package/src/client/canvas/Presentation.tsx

@@ -4,6 +4,7 @@ import { canvasArea } from './canvas-area';
 import { cancelViewportAnimation, hasInitialServerLayout, viewport } from '../state/canvas-store';
 import {
   endPresentation,
+  presentationCursor,
   presentationError,
   presenting,
   recordingCamera,
@@ -11,6 +12,7 @@ import {
   stepTour,
 } from '../state/presentation';
 import { usePanZoom } from './use-pan-zoom';
+import { BarHint } from './BarHint';
 
 declare global {
   interface Window {
@@ -25,6 +27,9 @@ declare global {
 
 export function Presentation() {
   const active = presenting.value;
+  const cursor = presentationCursor.value;
+  const canBack = cursor !== null && cursor.index > 0;
+  const canNext = cursor !== null && cursor.index < cursor.total - 1;
   const ready = hasInitialServerLayout.value;
   const moveCamera = (camera: Camera) => {
     cancelViewportAnimation();
@@ -89,9 +94,54 @@ export function Presentation() {
           }}
           onContextMenu={(event) => event.preventDefault()}
         >
-          <button type="button" class="presentation-exit" onClick={endPresentation}>
-            Exit presentation
-          </button>
+          <div class="presentation-controls" role="group" aria-label="Presentation controls">
+            <BarHint
+              id="presentation-back-hint"
+              label="Previous stop"
+              shortcut="← / ↑"
+              fitWithin=".presentation-navigation"
+            >
+              <button
+                type="button"
+                class="presentation-step"
+                aria-describedby="presentation-back-hint"
+                aria-disabled={!canBack}
+                onClick={() => {
+                  if (canBack) void stepTour({ step: 'previous' });
+                }}
+              >
+                Back
+              </button>
+            </BarHint>
+            <BarHint
+              id="presentation-next-hint"
+              label="Next stop"
+              shortcut="→ / ↓ / Space"
+              fitWithin=".presentation-navigation"
+            >
+              <button
+                type="button"
+                class="presentation-step"
+                aria-describedby="presentation-next-hint"
+                aria-disabled={!canNext}
+                onClick={() => {
+                  if (canNext) void stepTour({ step: 'next' });
+                }}
+              >
+                Next
+              </button>
+            </BarHint>
+            <BarHint id="presentation-exit-hint" label="Exit presentation" shortcut="Esc" align="end">
+              <button
+                type="button"
+                class="presentation-exit"
+                aria-describedby="presentation-exit-hint"
+                onClick={endPresentation}
+              >
+                Exit presentation
+              </button>
+            </BarHint>
+          </div>
         </div>
       )}
       {presentationError.value && (

package/src/client/canvas/RelationsPanel.tsx

@@ -4,6 +4,7 @@ import { relationDefinition, relationSourceEnd } from '../../shared/relations.js
 import { activeBoardId, boardList, openMemoryTarget } from '../state/boards-store';
 import { edges, nodes } from '../state/canvas-store';
 import { requestJson } from '../state/intent-bridge';
+import { showRelationsOnCanvas } from '../state/relation-store';
 
 /** The expanded card's evidence and uses, from the same graph agents navigate. */
 export function RelationsPanel({ nodeId }: { nodeId: string }) {
@@ -50,6 +51,14 @@ export function RelationsPanel({ nodeId }: { nodeId: string }) {
   return (
     <aside class="relations-panel" aria-label="Relations">
       <h3>Relations</h3>
+      <div class="relation-navigation">
+        <button type="button" onClick={() => showRelationsOnCanvas(nodeId, 'lineage')}>
+          Show lineage
+        </button>
+        <button type="button" onClick={() => showRelationsOnCanvas(nodeId, 'connections')}>
+          Show on canvas
+        </button>
+      </div>
       {!graph && <p role="status">{unavailable ? 'Relations unavailable. Reopen to retry.' : 'Loading relations…'}</p>}
       {graph && relations.length === 0 && <p>No connections yet.</p>}
       {relations.map((edge, index) => {

package/src/client/canvas/SelectionBar.tsx

@@ -13,6 +13,7 @@ import { createEdgeFromClient, createGroupFromClient, removeNodeFromClient } fro
 import { sessionActive } from '../state/presence-store';
 import { BarHint } from './BarHint';
 import { useChromeHeight } from './use-chrome-height';
+import { openBoardMove } from './BoardMoveDialog';
 
 /**
  * Floating bottom-center bar for a multi-selection (rail-chrome-v2 phase 7,
@@ -174,6 +175,26 @@ export function SelectionBar() {
           </BarHint>
         </>
       )}
+      <BarHint label="Move to new board" side="up">
+        <button
+          type="button"
+          class="selection-bar-icon"
+          aria-label="Move to new board"
+          onClick={() => openBoardMove([...selectedNodeIds.value])}
+        >
+          <svg
+            width="16"
+            height="16"
+            viewBox="0 0 16 16"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="1.5"
+            aria-hidden="true"
+          >
+            <path d="M6 3H2v10h12V9M8 8l6-6M9 2h5v5" />
+          </svg>
+        </button>
+      </BarHint>
       <BarHint label="Pin to agent context" side="up">
         <button type="button" class="selection-bar-action is-pin" onClick={handlePinContext}>
           <span aria-hidden="true">✦</span>

package/src/client/canvas/SessionPanel.tsx

@@ -4,7 +4,9 @@ import { IconChevronRight, IconUndo } from '../icons';
 import { useNow } from './use-now';
 import { agentPhaseLabel } from '../../shared/agent-presence.js';
 import { formatCountdown, gateRemainingMs } from '../../shared/approval-gates.js';
-import { focusNode, selectedNodeIds } from '../state/canvas-store';
+import { focusNode, nodes, selectedNodeIds } from '../state/canvas-store';
+import { activeBoardId } from '../state/boards-store';
+import { createNodeFromClient } from '../state/intent-bridge';
 import { activeSession, agentPresences, attachedSessions, writerColor } from '../state/presence-store';
 import {
   type ApprovalGateView,
@@ -96,6 +98,35 @@ function clock(iso: string): string {
 }
 
 function WorkItemRow({ item }: { item: WorkItemView }) {
+  const [busy, setBusy] = useState(false);
+  const [pending, setPending] = useState<{ boardId: string; nodeId: string } | null>(null);
+  const boardId = activeBoardId.value;
+  const boardNodes = nodes.value;
+  const presentation = [...nodes.value.values()].find(
+    (node) => node.type === 'status' && node.data.workItemId === item.id,
+  );
+  useEffect(() => {
+    if (!pending) return;
+    if (boardId === pending.boardId && !boardNodes.has(pending.nodeId)) return;
+    if (boardId === pending.boardId) focusNode(pending.nodeId);
+    setPending(null);
+    setBusy(false);
+  }, [pending, boardId, boardNodes]);
+  const show = async () => {
+    if (presentation) return focusNode(presentation.id);
+    if (!boardId || busy) return;
+    setBusy(true);
+    const result = await createNodeFromClient({
+      type: 'status',
+      data: { workItemId: item.id },
+      width: 360,
+      height: 200,
+      expectedBoardId: boardId,
+    });
+    if (result.ok && result.id && activeBoardId.value === boardId) {
+      setPending({ boardId, nodeId: result.id });
+    } else setBusy(false);
+  };
   const glyph = WORK_GLYPH[item.status] ?? 'queued';
   const nodeId = item.nodeIds[0];
   return (
@@ -106,6 +137,9 @@ function WorkItemRow({ item }: { item: WorkItemView }) {
           {item.title}
         </button>
         {item.detail && <div class="session-item-detail">{item.detail}</div>}
+        <button type="button" class="session-show-work" disabled={busy} onClick={() => void show()}>
+          {busy ? 'Showing…' : presentation ? 'Show card' : 'Show on board'}
+        </button>
       </div>
       <span class="session-item-status">{WORK_STATUS_TEXT[item.status] ?? glyph}</span>
       <span class="session-item-time">{clock(item.updatedAt)}</span>

package/src/client/canvas/TextPrompt.tsx

@@ -1,5 +1,6 @@
 import { signal } from '@preact/signals';
 import { useEffect, useRef } from 'preact/hooks';
+import { useFocusTrap } from './use-focus-trap';
 
 /**
  * In-canvas replacement for `window.prompt`, which embedded browser panes
@@ -9,6 +10,8 @@ import { useEffect, useRef } from 'preact/hooks';
 interface TextPromptRequest {
   title: string;
   placeholder: string;
+  description?: string;
+  maxLength?: number;
   /** Prefilled (and pre-selected) value — edit flows start from the current text. */
   initial: string;
   /** Submitting an empty field resolves '' instead of null — "clear the value" flows. */
@@ -25,7 +28,7 @@ let promptSeq = 0;
 export function askText(
   title: string,
   placeholder: string,
-  opts: { initial?: string; allowEmpty?: boolean; confirm?: string } = {},
+  opts: { initial?: string; allowEmpty?: boolean; confirm?: string; description?: string; maxLength?: number } = {},
 ): Promise<string | null> {
   return new Promise((resolve) => {
     textPromptRequest.value?.resolve(null);
@@ -34,6 +37,8 @@ export function askText(
       seq: promptSeq,
       title,
       placeholder,
+      description: opts.description,
+      maxLength: opts.maxLength,
       initial: opts.initial ?? '',
       allowEmpty: opts.allowEmpty ?? false,
       confirm: opts.confirm ?? 'Add',
@@ -51,6 +56,8 @@ function settle(value: string | null): void {
 export function TextPrompt() {
   const request = textPromptRequest.value;
   const inputRef = useRef<HTMLInputElement>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  useFocusTrap(dialogRef, request !== null, { initial: inputRef });
 
   useEffect(() => {
     if (!request) return;
@@ -78,13 +85,21 @@ export function TextPrompt() {
   return (
     <div class="text-prompt-backdrop" onPointerDown={() => settle(null)}>
       <div
+        ref={dialogRef}
         class="text-prompt"
         role="dialog"
+        aria-modal="true"
         aria-label={request.title}
+        aria-describedby={request.description ? 'text-prompt-description' : undefined}
         data-testid="text-prompt"
         onPointerDown={(e) => e.stopPropagation()}
       >
         <div class="text-prompt-title">{request.title}</div>
+        {request.description && (
+          <div id="text-prompt-description" class="text-prompt-description">
+            {request.description}
+          </div>
+        )}
         <input
           // A fresh element per ask (so defaultValue applies) focused in the
           // ref callback, which Preact runs synchronously during commit — the
@@ -101,6 +116,8 @@ export function TextPrompt() {
           type="text"
           defaultValue={request.initial}
           placeholder={request.placeholder}
+          aria-label={request.title}
+          maxLength={request.maxLength}
           onKeyDown={(e) => {
             // Contained: the global shortcut layer must not see these.
             if (e.key === 'Enter') {

package/src/client/canvas/TopBar.tsx

@@ -38,6 +38,18 @@ import {
 } from '../state/session-store';
 import { formatCountdown, gateRemainingMs } from '../../shared/approval-gates.js';
 import { agentSessionsEnabled } from '../state/workspace-settings';
+import { humanName, setHumanName } from '../state/human-store';
+import { tabAgentKey } from '../state/intent-bridge';
+import { HUMAN_NAME_MAX_LENGTH } from '../../shared/human-presence.js';
+import { askText } from './TextPrompt';
+
+const PRESENT_DESCRIPTION = (
+  <span style={{ whiteSpace: 'pre-line' }}>
+    {
+      'A presentation follows either a saved tour or the board’s groups.\n\nSaved tour: ask your agent to define the stops and their order. Each stop can focus on a card, a group, a rectangular area, or a specific camera position.\n\nNo saved tour: every group becomes a stop, ordered top-to-bottom, then left-to-right. It doesn’t automatically visit every card.'
+    }
+  </span>
+);
 
 /**
  * The attached session's chip (rail-chrome-v2 phase 3): phase-colored, with a
@@ -481,12 +493,16 @@ export function TopBar() {
               )}
               {activeBoardId.value && (
                 <BarHint
+                  id="present-hint"
                   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."
+                  body={PRESENT_DESCRIPTION}
+                  align="end"
+                  fitWithin="body"
                 >
                   <button
                     type="button"
                     class="present-button"
+                    aria-describedby="present-hint"
                     onClick={() => {
                       void startPresentation();
                     }}
@@ -524,6 +540,32 @@ export function TopBar() {
             <TopBarMore boardOpen={!!activeBoardId.value} onFit={handleFit} />
           </>
         )}
+        {!isHostedWorkbench() && !tabAgentKey && (
+          <span class="human-name-control">
+            <BarHint label="Your name" body={`Shown on your cursor: ${humanName.value}`} align="end">
+              <button
+                type="button"
+                class="top-bar-btn human-name-button"
+                aria-label={`Your name: ${humanName.value}`}
+                aria-haspopup="dialog"
+                onClick={async (event) => {
+                  const button = event.currentTarget;
+                  const name = await askText('Your name on this canvas', 'e.g. Alex', {
+                    initial: humanName.value,
+                    confirm: 'Save name',
+                    maxLength: HUMAN_NAME_MAX_LENGTH,
+                    description:
+                      'Shown on your cursor. Self-reported, not a verified identity or an access grant. Saved in this browser.',
+                  });
+                  if (name !== null) setHumanName(name);
+                  button.focus({ preventScroll: true });
+                }}
+              >
+                {writerInitial(humanName.value)}
+              </button>
+            </BarHint>
+          </span>
+        )}
       </div>
     </div>
   );
@@ -592,14 +634,17 @@ function TopBarMore({ boardOpen, onFit }: { boardOpen: boolean; onFit: () => voi
             </button>
           )}
           {boardOpen && (
-            <button
-              type="button"
-              role="menuitem"
-              class="toolbar-menu-item"
-              onClick={run(() => void startPresentation())}
-            >
-              Present board
-            </button>
+            <BarHint id="present-menu-hint" label="Present board" body={PRESENT_DESCRIPTION}>
+              <button
+                type="button"
+                role="menuitem"
+                class="toolbar-menu-item"
+                aria-describedby="present-menu-hint"
+                onClick={run(() => void startPresentation())}
+              >
+                Present board
+              </button>
+            </BarHint>
           )}
           <button type="button" role="menuitem" class="toolbar-menu-item" onClick={run(() => zoomByFactor(1.25))}>
             Zoom in

package/src/client/canvas/auto-fit.ts

@@ -7,12 +7,6 @@ export const AUTO_FIT_MAX_HEIGHT = 600;
 // Iframe surfaces (charts/dashboards/rich html) can legitimately need more room
 // than a text node, so they grow to a higher ceiling before scrolling.
 export const AUTO_FIT_MAX_HEIGHT_IFRAME = 1400;
-// `.node-body` adds 12px padding top+bottom around an iframe surface (global.css).
-// The bridge reports the iframe's OWN document scrollHeight, so the grow target
-// must add titlebar + this body padding or the node settles ~24px short and the
-// surface shows a residual inner scrollbar. (The DOM auto-fit above doesn't need
-// this: body.scrollHeight already includes the body's padding.)
-export const AUTO_FIT_BODY_PADDING = 24;
 
 /** Node types the DOM auto-fit can't measure: iframe-backed surfaces (html/
  *  json-render/graph/mcp-app), where the body's scrollHeight equals the iframe
@@ -77,13 +71,17 @@ export function shouldContentFitIframeNode(node: CanvasNodeState): boolean {
 /**
  * Grow-only target height from a surface-reported content height. Returns null
  * when the node is exempt, the report is non-positive, or the node already fits
- * (so it never shrinks — monotonic growth can't oscillate). Adds the titlebar +
- * node-body padding so the content fully clears (no residual inner scrollbar),
- * capped at the iframe ceiling.
+ * (so it never shrinks). Callers measure the actual chrome in world pixels,
+ * including zoom-compensated headers and any captions. A fixed padding allowance
+ * makes a full-height viewer grow again on every content-height report.
  */
-export function computeContentGrowHeight(node: CanvasNodeState, contentHeight: number): number | null {
+export function computeContentGrowHeight(
+  node: CanvasNodeState,
+  contentHeight: number,
+  chromeHeight: number,
+): number | null {
   if (!shouldContentFitIframeNode(node) || !Number.isFinite(contentHeight) || contentHeight <= 0) return null;
-  const want = Math.min(contentHeight + AUTO_FIT_TITLEBAR_HEIGHT + AUTO_FIT_BODY_PADDING, AUTO_FIT_MAX_HEIGHT_IFRAME);
+  const want = Math.min(Math.ceil(contentHeight + chromeHeight), AUTO_FIT_MAX_HEIGHT_IFRAME);
   return want > node.size.height + 8 ? want : null;
 }
 

package/src/client/canvas/canvas-area.ts

@@ -55,12 +55,12 @@ export interface CanvasFitInsets {
  * both (0.5.0 Amp report, finding A; architecture rule 9's trap).
  */
 export function canvasFitInsets(): CanvasFitInsets {
-  let top = 16;
+  let top = 44;
   let bottom = 16;
   try {
     const area = canvasArea();
     const areaBottom = area.top + area.height;
-    for (const selector of ['.lifecycle-filters', '.relation-legend']) {
+    for (const selector of ['.lifecycle-filters', '.relation-legend', '.group-breadcrumbs']) {
       const el = document.querySelector(selector);
       if (!(el instanceof HTMLElement) || !el.isConnected) continue;
       const rect = el.getBoundingClientRect();

package/src/client/canvas/use-focus-trap.ts

@@ -71,7 +71,12 @@ export function useFocusTrap(
       // from (focus mode unmounts the node while expanded) names the element
       // to return to, which may only exist after the next frame.
       if (restoreTo) {
-        requestAnimationFrame(() => restoreTo()?.focus());
+        requestAnimationFrame(() => {
+          // A newly opened menu owns focus before this deferred return runs.
+          if (document.activeElement === document.body || root.contains(document.activeElement)) {
+            restoreTo()?.focus();
+          }
+        });
       } else if (previous && document.contains(previous) && previous !== document.body) {
         previous.focus();
       }

package/src/client/mermaid-entry.ts

@@ -5,16 +5,10 @@
  * HTML-escaped diagram source in `<pre class="mermaid-source">`; this script
  * reads it back via textContent, renders it to SVG, and re-renders when the
  * parent canvas live-switches the theme (the theme bridge toggles the document's
- * `data-theme` attribute). Keeping mermaid out of the main SPA bundle keeps the
- * canvas boot lean — only mermaid-node surfaces pay for the library.
+ * `data-theme` attribute). Standalone views and exports share the canvas renderer.
  */
 
-import mermaid from 'mermaid';
-import { canvasThemeScheme } from '../shared/themes.js';
-
-function documentScheme(): 'dark' | 'light' {
-  return canvasThemeScheme(document.documentElement.getAttribute('data-theme'));
-}
+import { renderMermaid } from './mermaid-render.js';
 
 function showError(container: HTMLElement, message: string): void {
   container.innerHTML = '';
@@ -65,18 +59,14 @@ function fitDiagram(container: HTMLElement): void {
 }
 
 async function renderDiagram(source: string, container: HTMLElement): Promise<void> {
-  const scheme = documentScheme();
-  mermaid.initialize({
-    startOnLoad: false,
-    theme: scheme === 'dark' ? 'dark' : 'default',
-    securityLevel: 'strict',
-  });
-  renderSeq += 1;
+  const sequence = ++renderSeq;
   try {
-    const { svg } = await mermaid.render(`pmx-mermaid-${renderSeq}`, source);
+    const svg = await renderMermaid(source);
+    if (sequence !== renderSeq) return;
     container.innerHTML = svg;
     fitDiagram(container);
   } catch (error) {
+    if (sequence !== renderSeq) return;
     // Never leave a blank/black frame: show the parse/render error instead.
     showError(container, error instanceof Error ? error.message : String(error));
   }
@@ -98,11 +88,7 @@ function boot(): void {
   void renderDiagram(source, container);
   // Live theme switching: the parent's theme bridge toggles data-theme on the
   // root element; re-render so the diagram palette follows the canvas theme.
-  let lastScheme = documentScheme();
   const observer = new MutationObserver(() => {
-    const scheme = documentScheme();
-    if (scheme === lastScheme) return;
-    lastScheme = scheme;
     void renderDiagram(source, container);
   });
   observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });

package/src/client/mermaid-render.ts

@@ -0,0 +1,39 @@
+import DOMPurify from 'dompurify';
+
+// Mermaid configuration is global: serialize configuration with each render.
+let rendering: Promise<unknown> = Promise.resolve();
+
+export function renderMermaid(source: string): Promise<string> {
+  const result = rendering.then(async () => {
+    // Diagram-only dependency: the SPA splits this module; self-contained MCP
+    // documents defer its initialization without requiring external assets.
+    const { default: mermaid } = await import('mermaid');
+    const style = getComputedStyle(document.documentElement);
+    const token = (name: string) => style.getPropertyValue(name).trim();
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      theme: 'base',
+      fontFamily: token('--font-ui'),
+      themeVariables: {
+        primaryColor: token('--c-panel-soft'),
+        primaryTextColor: token('--c-text'),
+        primaryBorderColor: token('--c-line'),
+        lineColor: token('--c-muted'),
+        secondaryColor: token('--c-panel'),
+        tertiaryColor: token('--c-panel'),
+        edgeLabelBackground: token('--c-panel'),
+        fontSize: '12px',
+      },
+    });
+    const { svg } = await mermaid.render(`mermaid-${crypto.randomUUID()}`, source);
+    return DOMPurify.sanitize(svg, {
+      ADD_TAGS: ['foreignObject'],
+      ADD_ATTR: ['dominant-baseline'],
+      HTML_INTEGRATION_POINTS: { foreignobject: true },
+    });
+  });
+  // A malformed diagram must not prevent the next diagram from rendering.
+  rendering = result.catch(() => {});
+  return result;
+}