pmx-canvas 0.8.2 → 0.9.0

package/src/client/nodes/McpAppNode.tsx

@@ -1,9 +1,10 @@
 import type { RefObject } from 'preact';
-import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { canvasThemeScheme } from '../../shared/themes.js';
 import type { CanvasNodeState } from '../types';
 import { axSurfaceState, canvasTheme } from '../state/canvas-store';
+import { showToast } from '../state/attention-bridge';
 import { iframeMode } from '../state/iframe-mode';
 import { shouldContentFitIframeNode } from '../canvas/auto-fit';
 import { ExtAppFrame } from './ExtAppFrame';
@@ -65,9 +66,9 @@ type ViewerFrameSource = { src?: string; srcdoc?: string };
 /**
  * Keep the last painted viewer in front while its replacement navigates. Viewer
  * specs are immutable documents, so updates normally change `?v=` and reload the
- * iframe; putting the new document in a hidden sibling avoids exposing Chromium's
- * white navigation paint. Two animation frames after load gives the new document
- * a composited paint before the old one is removed.
+ * iframe; putting the new document behind the old one conceals Chromium's white
+ * navigation paint without suppressing rendering. Wait for restore and render commit,
+ * then two animation frames before the old viewer is removed.
  */
 export function RefreshingViewerFrame({
   source,
@@ -83,7 +84,7 @@ export function RefreshingViewerFrame({
   source: ViewerFrameSource;
   iframeRef: RefObject<HTMLIFrameElement>;
   onLoad: () => void;
-  onDocumentLoad?: (frame: HTMLIFrameElement) => void;
+  onDocumentLoad?: (frame: HTMLIFrameElement, signal: AbortSignal) => void | Promise<boolean | 'cancelled' | void>;
   title: string;
   className?: string;
   sandbox?: string;
@@ -91,50 +92,77 @@ export function RefreshingViewerFrame({
   tabIndex?: number;
 }) {
   const sourceKey = source.src ?? source.srcdoc ?? '';
-  const [painted, setPainted] = useState({ key: sourceKey, source });
-  const [pending, setPending] = useState<{ key: string; source: ViewerFrameSource } | null>(null);
+  const [painted, setPainted] = useState({ key: sourceKey, source, attempt: 0 });
+  const [pending, setPending] = useState<{ key: string; source: ViewerFrameSource; attempt: number } | null>(null);
   const promotionRef = useRef(0);
+  const readiness = useRef(new Set<AbortController>());
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     promotionRef.current += 1;
+    for (const controller of readiness.current) controller.abort();
+    readiness.current.clear();
     if (!sourceKey || sourceKey === painted.key) {
       setPending(null);
       return;
     }
     if (!painted.key) {
-      setPainted({ key: sourceKey, source });
+      setPainted({ key: sourceKey, source, attempt: 0 });
       return;
     }
-    setPending({ key: sourceKey, source });
+    setPending({ key: sourceKey, source, attempt: 0 });
   }, [sourceKey, painted.key]);
 
   useEffect(
     () => () => {
       promotionRef.current += 1;
+      for (const controller of readiness.current) controller.abort();
+      readiness.current.clear();
     },
     [],
   );
 
-  const frame = (entry: { key: string; source: ViewerFrameSource }, isPending: boolean) => (
+  const frame = (entry: { key: string; source: ViewerFrameSource; attempt: number }, isPending: boolean) => (
     <iframe
-      key={entry.key}
+      key={`${entry.key}:${entry.attempt}`}
       ref={isPending ? undefined : iframeRef}
       {...entry.source}
       class={className}
       sandbox={sandbox}
       allow={allow}
       tabIndex={tabIndex}
+      inert={isPending}
+      aria-hidden={isPending ? true : undefined}
       loading={iframeMode.value === 'srcdoc' ? undefined : 'lazy'}
-      onLoad={(event) => {
+      onLoad={async (event) => {
         // Seed runtime state while a replacement is still behind the painted
-        // frame, rather than mounting an empty viewer after promotion.
-        onDocumentLoad?.(event.currentTarget);
+        // frame, and wait until that document has committed its rendered UI.
+        const token = isPending ? ++promotionRef.current : promotionRef.current;
+        const loadedFrame = event.currentTarget;
+        const controller = new AbortController();
+        readiness.current.add(controller);
+        const ready = onDocumentLoad?.(loadedFrame, controller.signal);
+        const loaded = ready ? await ready : undefined;
+        readiness.current.delete(controller);
+        if (promotionRef.current !== token || loaded === 'cancelled') return;
+        if (loaded === false) {
+          if (entry.attempt === 0) {
+            const retry = { ...entry, attempt: 1 };
+            if (isPending) setPending(retry);
+            else setPainted(retry);
+          } else {
+            if (isPending) setPending(null);
+            showToast(
+              'remove',
+              'Viewer could not load',
+              `${isPending ? 'Keeping the last view. ' : ''}Reload to retry.`,
+            );
+          }
+          return;
+        }
         if (!isPending) {
           onLoad();
           return;
         }
-        const token = ++promotionRef.current;
-        const loadedFrame = event.currentTarget;
         requestAnimationFrame(() =>
           requestAnimationFrame(() => {
             if (promotionRef.current !== token) return;
@@ -150,7 +178,8 @@ export function RefreshingViewerFrame({
         inset: 0,
         width: '100%',
         height: '100%',
-        visibility: isPending ? 'hidden' : 'visible',
+        visibility: 'visible',
+        zIndex: isPending ? 0 : 1,
         background: 'var(--c-panel-soft)',
       }}
       title={title}
@@ -299,8 +328,9 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
       <RefreshingViewerFrame
         source={surfaceFrame}
         iframeRef={iframeRef}
-        onDocumentLoad={(frame) => {
-          if (stateToken && frame.contentWindow) restoreViewerRuntimeState(node.id, stateToken, frame.contentWindow);
+        onDocumentLoad={(frame, signal) => {
+          if (stateToken && frame.contentWindow)
+            return restoreViewerRuntimeState(node.id, stateToken, frame.contentWindow, signal);
         }}
         onLoad={pushAxState}
         title={`MCP App: ${sourceServer}`}

package/src/client/nodes/MdFormatBar.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { BarHint } from '../canvas/BarHint';
 import { modChord } from '../utils/platform';
 import { type FormatAction, FORMAT_ACTIONS, getSelectionRect } from './md-format';
 
@@ -83,27 +84,29 @@ export function MdFormatBar({ textareaRef }: { textareaRef: { current: HTMLTextA
       onMouseDown={(e) => e.preventDefault()}
     >
       {PRIMARY_ACTIONS.map((a) => (
-        <button
-          key={a.key}
-          type="button"
-          class={`md-format-btn md-format-btn-${a.key}`}
-          title={`${a.label} (${modChord(a.shortcut!.toUpperCase())})`}
-          onClick={() => runAction(a)}
-        >
-          {a.icon}
-        </button>
+        <BarHint key={a.key} label={a.label} shortcut={modChord(a.shortcut!.toUpperCase())}>
+          <button
+            type="button"
+            class={`md-format-btn md-format-btn-${a.key}`}
+            aria-label={a.label}
+            onClick={() => runAction(a)}
+          >
+            {a.icon}
+          </button>
+        </BarHint>
       ))}
       <div class="md-format-divider" />
       {SECONDARY_ACTIONS.map((a) => (
-        <button
-          key={a.key}
-          type="button"
-          class={`md-format-btn md-format-btn-${a.key}`}
-          title={a.label}
-          onClick={() => runAction(a)}
-        >
-          {a.icon}
-        </button>
+        <BarHint key={a.key} label={a.label}>
+          <button
+            type="button"
+            class={`md-format-btn md-format-btn-${a.key}`}
+            aria-label={a.label}
+            onClick={() => runAction(a)}
+          >
+            {a.icon}
+          </button>
+        </BarHint>
       ))}
     </div>
   );

package/src/client/nodes/PromptNode.tsx

@@ -169,7 +169,7 @@ export function PromptNode({ node, expanded = false }: { node: CanvasNodeState;
       Promise.all(
         assistantTurns.map(async ({ turn, index }) => {
           const html = await renderMarkdown(turn.text);
-          return { index, html: sanitizeMarkdownHtml(html) };
+          return { index, html: sanitizeMarkdownHtml(html ?? '') };
         }),
       ).then((results) => {
         if (cancelled) return;

package/src/client/nodes/ResponseNode.tsx

@@ -36,7 +36,7 @@ export function ResponseNode({ node, expanded = false }: { node: CanvasNodeState
     }
     let cancelled = false;
     renderMarkdown(content).then((html) => {
-      if (!cancelled) setRendered(sanitizeMarkdownHtml(html));
+      if (!cancelled) setRendered(sanitizeMarkdownHtml(html ?? ''));
     });
     return () => {
       cancelled = true;

package/src/client/nodes/viewer-runtime-state.ts

@@ -7,7 +7,7 @@ type Snapshot = {
   version: unknown;
   documentUrl: unknown;
   state: Record<string, unknown> | null;
-  owners: Array<{ token: string; source: Window }>;
+  owners: Array<{ token: string; source: Window; mounted: () => void; ready: () => void; cancel: () => void }>;
 };
 
 // Tab-local UI state only: never persist form drafts in canvas data or AX. Keep
@@ -17,7 +17,12 @@ type Snapshot = {
 const snapshots = new Map<string, Snapshot>();
 let listening = false;
 
-export function restoreViewerRuntimeState(nodeId: string, token: string, source: Window): void {
+export function restoreViewerRuntimeState(
+  nodeId: string,
+  token: string,
+  source: Window,
+  signal?: AbortSignal,
+): Promise<boolean | 'cancelled'> {
   if (!listening) {
     listening = true;
     effect(() => {
@@ -30,8 +35,10 @@ export function restoreViewerRuntimeState(nodeId: string, token: string, source:
           snapshot.epoch !== epoch ||
           snapshot.version !== node.data.specVersion ||
           snapshot.documentUrl !== node.data.url
-        )
+        ) {
+          for (const owner of snapshot.owners) owner.cancel();
           snapshots.delete(id);
+        }
       }
     });
     window.addEventListener('message', (event: MessageEvent) => {
@@ -42,37 +49,62 @@ export function restoreViewerRuntimeState(nodeId: string, token: string, source:
         nodeId?: string;
         state?: unknown;
       } | null;
-      if (
-        !message ||
-        message.source !== JSON_VIEWER_STATE_SOURCE ||
-        message.type !== 'snapshot' ||
-        typeof message.nodeId !== 'string'
-      )
-        return;
+      if (!message || message.source !== JSON_VIEWER_STATE_SOURCE || typeof message.nodeId !== 'string') return;
       const snapshot = snapshots.get(message.nodeId);
       const ownerIndex =
         snapshot?.owners.findIndex((owner) => owner.token === message.token && owner.source === event.source) ?? -1;
       if (!snapshot || ownerIndex < 0) return;
+      if (message.type === 'mounted') {
+        snapshot.owners[ownerIndex]!.mounted();
+        return;
+      }
+      if (message.type === 'ready') {
+        snapshot.owners[ownerIndex]!.ready();
+        return;
+      }
+      if (message.type !== 'snapshot') return;
       if (!message.state || typeof message.state !== 'object' || Array.isArray(message.state)) return;
       const { ax: _ax, ...state } = message.state as Record<string, unknown>;
       snapshot.state = state;
       // Once the replacement emits, the retired document cannot overwrite it.
+      const retired = snapshot.owners.slice(0, ownerIndex);
       snapshot.owners = snapshot.owners.slice(ownerIndex);
+      for (const owner of retired) owner.cancel();
     });
   }
   const node = nodes.value.get(nodeId);
-  if (!node) return;
-  let snapshot = snapshots.get(nodeId);
-  if (!snapshot) {
-    snapshot = {
-      epoch: canvasInteractionEpoch.value,
-      version: node.data.specVersion,
-      documentUrl: node.data.url,
-      state: null,
-      owners: [],
+  if (!node || signal?.aborted) return Promise.resolve('cancelled');
+  const snapshot: Snapshot = snapshots.get(nodeId) ?? {
+    epoch: canvasInteractionEpoch.value,
+    version: node.data.specVersion,
+    documentUrl: node.data.url,
+    state: null,
+    owners: [],
+  };
+  snapshots.set(nodeId, snapshot);
+  const ready = new Promise<boolean | 'cancelled'>((resolve) => {
+    const finish = (loaded: boolean | 'cancelled') => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', owner.cancel);
+      if (loaded !== true) snapshot.owners = snapshot.owners.filter((entry) => entry !== owner);
+      resolve(loaded);
     };
-    snapshots.set(nodeId, snapshot);
-  }
-  snapshot.owners = [...snapshot.owners.filter((owner) => owner.source !== source).slice(-1), { token, source }];
+    const owner = {
+      token,
+      source,
+      mounted: () => clearTimeout(timer),
+      ready: () => finish(true),
+      cancel: () => finish('cancelled'),
+    };
+    // A missing runtime fails, but a healthy offscreen document can wait for
+    // paint indefinitely. Its synchronous mount acknowledgement ends the deadline;
+    // only the later frame-gated ready message may promote it.
+    const timer = setTimeout(() => finish(false), 10_000);
+    for (const previous of snapshot.owners.filter((entry) => entry.source === source)) previous.cancel();
+    while (snapshot.owners.length > 1) snapshot.owners[0]!.cancel();
+    snapshot.owners.push(owner);
+    signal?.addEventListener('abort', owner.cancel, { once: true });
+  });
   source.postMessage({ source: JSON_VIEWER_STATE_SOURCE, type: 'restore', token, state: snapshot.state }, '*');
+  return ready;
 }

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

@@ -16,6 +16,8 @@ import {
   type AttentionEntry,
   type AttentionTone,
 } from './attention-store';
+import { nearPins } from './near-pin-store';
+import { activeBoardId } from './boards-store';
 
 let reducer = new SemanticWatchReducer();
 let toastQueue: AttentionEntry[] = [];
@@ -77,13 +79,39 @@ function formatReason(reason: string): string {
   if (reason === 'left cluster') return 'moved away from its cluster';
   if (reason === 'cluster changed') return 'shifted into a different cluster';
   if (reason === 'pinned neighborhood changed') return 'changed the local focus field';
-  const enteredMatch = /^entered pinned neighborhood of "(.+)"$/.exec(reason);
-  if (enteredMatch) return `moved into focus around ${enteredMatch[1]}`;
-  const leftMatch = /^left pinned neighborhood of "(.+)"$/.exec(reason);
-  if (leftMatch) return `moved out of focus around ${leftMatch[1]}`;
   return reason;
 }
 
+function pinTitlesFrom(reasons: string[], verb: 'entered' | 'left'): string[] {
+  const pattern = new RegExp(`^${verb} pinned neighborhood of "(.+)"$`);
+  return reasons.flatMap((reason) => pattern.exec(reason)?.[1] ?? []);
+}
+
+/**
+ * NearPin.dc.html §3: one entry naming the node and the pin, saying what the
+ * agent gets. "Out of the brief" only once the node is near no pin at all.
+ */
+function nearPinEntry(name: string, nodeId: string, reasons: string[]): { title: string; body: string } | null {
+  const quoted = (titles: string[]) => titles.map((title) => `“${title}”`).join(' and ');
+  const entered = pinTitlesFrom(reasons, 'entered');
+  if (entered.length > 0) {
+    return {
+      title: 'Near a pin',
+      body: `“${name}” is now near ${quoted(entered)} — the agent gets its title and summary.`,
+    };
+  }
+  const left = pinTitlesFrom(reasons, 'left');
+  if (left.length === 0) return null;
+  const still = nearPins.value.get(nodeId) ?? [];
+  return {
+    title: 'Left a pin',
+    body:
+      still.length > 0
+        ? `“${name}” left ${quoted(left)} — still near ${quoted(still.map((pin) => pin.pinTitle))}.`
+        : `“${name}” left ${quoted(left)} — it is out of the agent’s brief.`,
+  };
+}
+
 function entryFromContextPin(event: ContextPinWatchEvent): AttentionEntry | null {
   const addedNames = event.added.map((node) => quoteLabel(node.title, node.id));
   const removedNames = event.removed.map((node) => quoteLabel(node.title, node.id));
@@ -118,7 +146,7 @@ function entryFromConnect(event: ConnectWatchEvent): AttentionEntry | null {
       'relationship',
       'Relationship added',
       `${quoteLabel(edge.fromTitle, edge.fromId)} linked to ${quoteLabel(edge.toTitle, edge.toId)}`,
-      [edge.fromId, edge.toId],
+      [edge.fromId, ...(!edge.toBoardId || edge.toBoardId === activeBoardId.value ? [edge.toId] : [])],
       event.timestamp ? Date.parse(event.timestamp) || Date.now() : Date.now(),
     );
   }
@@ -127,13 +155,33 @@ function entryFromConnect(event: ConnectWatchEvent): AttentionEntry | null {
     'relationship',
     'Relationships added',
     `${event.edges.length} connections changed the board structure`,
-    event.edges.flatMap((edge) => [edge.fromId, edge.toId]),
+    event.edges.flatMap((edge) => [
+      edge.fromId,
+      ...(!edge.toBoardId || edge.toBoardId === activeBoardId.value ? [edge.toId] : []),
+    ]),
     event.timestamp ? Date.parse(event.timestamp) || Date.now() : Date.now(),
   );
 }
 
 function entryFromRemove(event: RemoveWatchEvent): AttentionEntry | null {
   if (event.nodes.length === 0 && event.edges.length === 0) return null;
+  // LinksChanged.dc.html: a removed link leaves no line to mark, so Updates names it.
+  if (event.nodes.length === 0) {
+    const links = event.edges.map(
+      (edge) =>
+        `“${quoteLabel(edge.fromTitle, edge.fromId)}” – “${quoteLabel(edge.toTitle, edge.toId)}” (${edge.edgeType})`,
+    );
+    return makeEntry(
+      'remove',
+      links.length === 1 ? 'Link removed' : 'Links removed',
+      summarizeNames(links),
+      event.edges.flatMap((edge) => [
+        edge.fromId,
+        ...(!edge.toBoardId || edge.toBoardId === activeBoardId.value ? [edge.toId] : []),
+      ]),
+      event.timestamp ? Date.parse(event.timestamp) || Date.now() : Date.now(),
+    );
+  }
   const nodeNames = event.nodes.map((node) => quoteLabel(node.title, node.id));
   const parts: string[] = [];
   if (nodeNames.length > 0) parts.push(summarizeNames(nodeNames));
@@ -144,7 +192,13 @@ function entryFromRemove(event: RemoveWatchEvent): AttentionEntry | null {
     'remove',
     'Items removed',
     parts.join(' · '),
-    [...event.nodes.map((node) => node.id), ...event.edges.flatMap((edge) => [edge.fromId, edge.toId])],
+    [
+      ...event.nodes.map((node) => node.id),
+      ...event.edges.flatMap((edge) => [
+        edge.fromId,
+        ...(!edge.toBoardId || edge.toBoardId === activeBoardId.value ? [edge.toId] : []),
+      ]),
+    ],
     event.timestamp ? Date.parse(event.timestamp) || Date.now() : Date.now(),
   );
 }
@@ -184,14 +238,9 @@ function entryFromMoveEnd(event: MoveEndWatchEvent): AttentionEntry | null {
   const createdAt = event.timestamp ? Date.parse(event.timestamp) || Date.now() : Date.now();
 
   if (reasons.some((reason) => reason.includes('pinned neighborhood'))) {
-    if (event.nodes.length === 1) {
-      return makeEntry(
-        'neighborhood',
-        'Neighborhood changed',
-        `${names[0]} ${formatReason(event.nodes[0].reasons[0])}`,
-        event.nodes.map((node) => node.id),
-        createdAt,
-      );
+    const near = event.nodes.length === 1 ? nearPinEntry(names[0], event.nodes[0].id, event.nodes[0].reasons) : null;
+    if (near) {
+      return makeEntry('neighborhood', near.title, near.body, [event.nodes[0].id], createdAt);
     }
     return makeEntry(
       'neighborhood',