@plannotator/ui 0.33.0 → 0.35.0

package/hooks/useHtmlRefresh.ts

@@ -1,15 +1,22 @@
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
 
+/**
+ * A successful snapshot. `Extra` lets a host carry document metadata read
+ * alongside the bytes (Plannotator: the root document's version diff) through
+ * to `onSnapshot`; the hook never reads anything but `rawHtml`.
+ */
+export type HtmlRefreshOkSnapshot<Extra extends object = object> = { status: 'ok'; rawHtml: string } & Extra;
+
 /** What a host's `fetchSnapshot` resolves to. */
-export type HtmlRefreshSnapshot =
-  | { status: 'ok'; rawHtml: string }
+export type HtmlRefreshSnapshot<Extra extends object = object> =
+  | HtmlRefreshOkSnapshot<Extra>
   | { status: 'missing' }
   | { status: 'unavailable' };
 
 /** The outcome of one `refresh()` call, for host notifications (toasts). */
 export type HtmlRefreshResult = 'refreshed' | 'missing' | 'unavailable';
 
-export interface UseHtmlRefreshOptions {
+export interface UseHtmlRefreshOptions<Extra extends object = object> {
   /** Whether refresh is offered at all. Default true. */
   enabled?: boolean;
   /**
@@ -22,9 +29,11 @@ export interface UseHtmlRefreshOptions {
   documentKey?: string | null;
   /** Fetch the current bytes of the document. Called with `documentKey`.
    *  A rejection is treated as `{ status: 'unavailable' }`. */
-  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot>;
-  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). */
-  onSnapshot: (rawHtml: string) => void;
+  fetchSnapshot: (documentKey: string | null) => Promise<HtmlRefreshSnapshot<Extra>>;
+  /** Apply the refreshed bytes (the host owns the viewer's `rawHtml`). The
+   *  whole successful snapshot is the second argument, for hosts whose
+   *  `fetchSnapshot` reads metadata alongside the bytes. */
+  onSnapshot: (rawHtml: string, snapshot: HtmlRefreshOkSnapshot<Extra>) => void;
   /**
    * Once per refresh: the ids the remounted viewer could not re-anchor,
    * possibly empty. Wire the viewer's `onUnanchoredChange` to the returned
@@ -57,14 +66,14 @@ export interface UseHtmlRefreshReturn {
  * restore acknowledgement is armed per reload generation and consumed by
  * the first viewer report for that generation.
  */
-export function useHtmlRefresh({
+export function useHtmlRefresh<Extra extends object = object>({
   enabled = true,
   documentKey,
   fetchSnapshot,
   onSnapshot,
   onUnanchored,
   onResult,
-}: UseHtmlRefreshOptions): UseHtmlRefreshReturn {
+}: UseHtmlRefreshOptions<Extra>): UseHtmlRefreshReturn {
   const [isRefreshing, setIsRefreshing] = useState(false);
   const [reloadGeneration, setReloadGeneration] = useState(0);
   const keyed = documentKey !== undefined;
@@ -98,7 +107,7 @@ export function useHtmlRefresh({
       // A rejecting fetch is an unavailable snapshot: the host hears it
       // through onResult like any other outcome, never as an unhandled
       // rejection out of refresh().
-      let result: HtmlRefreshSnapshot;
+      let result: HtmlRefreshSnapshot<Extra>;
       try {
         result = await fetchSnapshot(requestKey);
       } catch {
@@ -111,7 +120,7 @@ export function useHtmlRefresh({
         return;
       }
 
-      onSnapshot(result.rawHtml);
+      onSnapshot(result.rawHtml, result);
       const nextGeneration = reloadGenerationRef.current + 1;
       reloadGenerationRef.current = nextGeneration;
       // Armed until the remounted viewer's bridge reports its restore. The

package/hooks/useSharing.ts

@@ -76,6 +76,12 @@ interface UseSharingResult {
   clearShareLoadError: () => void;
 }
 
+type ShortShareUrlLifecycle =
+  | { readonly _tag: 'none' }
+  | { readonly _tag: 'incoming-hydration' }
+  | { readonly _tag: 'generating'; readonly requestContext: object }
+  | { readonly _tag: 'associated'; readonly requestContext: object }
+  | { readonly _tag: 'failed'; readonly requestContext: object };
 
 // Share payloads are base64url-encoded deflate output: charset [A-Za-z0-9_-],
 // realistically >=30 chars, and virtually always mixed-case because deflate
@@ -133,6 +139,7 @@ export function useSharing(
   ]);
   const latestShareRequestContextRef = useRef(shareRequestContext);
   latestShareRequestContextRef.current = shareRequestContext;
+  const shortShareUrlLifecycleRef = useRef<ShortShareUrlLifecycle>({ _tag: 'none' });
 
   const clearPendingSharedAnnotations = useCallback(() => {
     setPendingSharedAnnotations(null);
@@ -148,6 +155,11 @@ export function useSharing(
       const pathMatch = window.location.pathname.match(/^\/p\/([A-Za-z0-9]{6,16})$/);
       if (pathMatch) {
         const pasteId = pathMatch[1];
+        // Capture before the async fetch. Concurrent loads (including the
+        // development Strict Mode replay) can complete after an earlier load
+        // removes /p/<id> from history; every completion must preserve the
+        // original short URL.
+        const incomingShortUrl = window.location.href;
 
         // Extract key and optional paste origin from fragment: #key=<k>&paste=<base64url>
         const fragment = window.location.hash.slice(1);
@@ -180,7 +192,8 @@ export function useSharing(
 
           setPendingSharedAnnotations(restoredAnnotations);
           setIsSharedSession(true);
-          setShortShareUrl(window.location.href);
+          shortShareUrlLifecycleRef.current = { _tag: 'incoming-hydration' };
+          setShortShareUrl(incomingShortUrl);
           onSharedLoad?.();
 
           // Remove the /p/<id> path from browser history so a refresh doesn't
@@ -294,17 +307,43 @@ export function useSharing(
     refreshShareUrl();
   }, [refreshShareUrl]);
 
-  // Clear stale short URL when content changes (does NOT auto-regenerate —
-  // the user must explicitly click "Create short link" again).
-  // Skip on shared session load — the incoming short URL must survive.
-  const isSharedRef = useRef(false);
+  // An incoming short URL becomes associated with the fully hydrated share
+  // context on its first committed render. From then on it follows the same
+  // lifecycle as a locally generated URL: any shareable-content change makes
+  // the immutable paste stale, so discard the URL without auto-uploading a
+  // replacement. Markdown users can still use the fresh hash URL; creating a
+  // new short link remains an explicit action.
   useEffect(() => {
-    if (isSharedSession) { isSharedRef.current = true; return; }
-    if (isSharedRef.current) { isSharedRef.current = false; return; }
+    const lifecycle = shortShareUrlLifecycleRef.current;
+    if (lifecycle._tag === 'incoming-hydration') {
+      if (!shortShareUrl) return;
+      // Hydration writes fresh annotation and attachment arrays, so this first
+      // committed request context represents the loaded snapshot. If those
+      // setters ever preserve identity, replace this consume-on-next-effect
+      // handoff with an explicit post-hydration signal.
+      shortShareUrlLifecycleRef.current = {
+        _tag: 'associated',
+        requestContext: shareRequestContext,
+      };
+      return;
+    }
+    if (
+      (
+        lifecycle._tag === 'generating'
+        || lifecycle._tag === 'associated'
+        || lifecycle._tag === 'failed'
+      )
+      && lifecycle.requestContext === shareRequestContext
+    ) {
+      return;
+    }
+    if (lifecycle._tag === 'none' && !shortShareUrl) return;
+
+    shortShareUrlLifecycleRef.current = { _tag: 'none' };
     setIsGeneratingShortUrl(false);
     setShortShareUrl('');
     setShortUrlError('');
-  }, [markdown, annotations, globalAttachments, rawHtml, isSharedSession, contentRevision]);
+  }, [shareRequestContext, shortShareUrl]);
 
   /**
    * Generate a short URL via the paste service.
@@ -318,6 +357,10 @@ export function useSharing(
     setIsGeneratingShortUrl(true);
     setShortUrlError('');
     const requestContext = shareRequestContext;
+    shortShareUrlLifecycleRef.current = {
+      _tag: 'generating',
+      requestContext,
+    };
 
     try {
       const htmlForShare = rawHtml
@@ -334,15 +377,21 @@ export function useSharing(
       if (latestShareRequestContextRef.current !== requestContext) return null;
 
       if (result) {
+        shortShareUrlLifecycleRef.current = {
+          _tag: 'associated',
+          requestContext,
+        };
         setShortShareUrl(result.shortUrl);
         return result.shortUrl;
       } else {
+        shortShareUrlLifecycleRef.current = { _tag: 'failed', requestContext };
         setShortShareUrl('');
         setShortUrlError('Short URL service unavailable');
         return null;
       }
     } catch (e) {
       if (latestShareRequestContextRef.current !== requestContext) return null;
+      shortShareUrlLifecycleRef.current = { _tag: 'failed', requestContext };
       setShortShareUrl('');
       setShortUrlError(e instanceof Error ? e.message : 'Failed to generate short URL');
       return null;

package/hooks/useUndoHistory.ts

@@ -0,0 +1,83 @@
+import { useRef } from 'react';
+import {
+  createUndoHistoryState,
+  recordUndoAction,
+  takeRedoAction,
+  takeUndoAction,
+  type HistoryDirection,
+  type UndoHistoryState,
+} from '../utils/undoHistory';
+
+/** Imperative bounded history API used by surface-specific command adapters. */
+export interface UndoHistoryApi<TAction> {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  record: (action: TAction) => void;
+  undo: () => boolean;
+  redo: () => boolean;
+  clear: () => void;
+}
+
+interface UndoHistoryOptions<TAction> {
+  context: string;
+  apply: (action: TAction, direction: HistoryDirection) => void;
+  capacity?: number;
+}
+
+/**
+ * Keep one bounded stack for the active surface context while replaying
+ * actions through the latest adapter callbacks. A context change starts a
+ * fresh baseline synchronously, before any shortcut can reach the new view.
+ */
+export function useUndoHistory<TAction>({
+  context,
+  apply,
+  capacity = 50,
+}: UndoHistoryOptions<TAction>): UndoHistoryApi<TAction> {
+  const optionsRef = useRef({ apply, capacity });
+  optionsRef.current = { apply, capacity };
+  const historyRef = useRef<{
+    context: string;
+    state: UndoHistoryState<TAction>;
+  }>({ context, state: createUndoHistoryState<TAction>() });
+  if (historyRef.current.context !== context) {
+    historyRef.current = { context, state: createUndoHistoryState<TAction>() };
+  }
+  const apiRef = useRef<UndoHistoryApi<TAction> | null>(null);
+
+  if (!apiRef.current) {
+    apiRef.current = {
+      get canUndo() {
+        return historyRef.current.state.past.length > 0;
+      },
+      get canRedo() {
+        return historyRef.current.state.future.length > 0;
+      },
+      record(action) {
+        const history = historyRef.current;
+        history.state = recordUndoAction(history.state, action, optionsRef.current.capacity);
+      },
+      undo() {
+        const history = historyRef.current;
+        const step = takeUndoAction(history.state);
+        if (step.action === null) return false;
+        history.state = step.state;
+        optionsRef.current.apply(step.action, 'undo');
+        return true;
+      },
+      redo() {
+        const history = historyRef.current;
+        const step = takeRedoAction(history.state, optionsRef.current.capacity);
+        if (step.action === null) return false;
+        history.state = step.state;
+        optionsRef.current.apply(step.action, 'redo');
+        return true;
+      },
+      clear() {
+        historyRef.current.state = createUndoHistoryState<TAction>();
+      },
+    };
+  }
+
+  return apiRef.current;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -74,7 +74,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.2",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.0",
+    "@plannotator/core": "workspace:*",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",

package/shortcuts/history.shortcuts.ts

@@ -0,0 +1,25 @@
+import { defineShortcutScope } from './core';
+import { createShortcutScopeHook } from './runtime';
+
+export const historyShortcuts = defineShortcutScope({
+  id: 'history',
+  title: 'History',
+  shortcuts: {
+    undo: {
+      description: 'Undo annotation change',
+      bindings: ['Mod+Z'],
+      section: 'History',
+      preventDefault: true,
+      displayOrder: 10,
+    },
+    redo: {
+      description: 'Redo annotation change',
+      bindings: ['Mod+Shift+Z', 'Mod+Y'],
+      section: 'History',
+      preventDefault: true,
+      displayOrder: 20,
+    },
+  },
+});
+
+export const useHistoryShortcuts = createShortcutScopeHook(historyShortcuts);

package/shortcuts/index.ts

@@ -1,5 +1,6 @@
 export * from './core';
 export * from './runtime';
+export { historyShortcuts, useHistoryShortcuts } from './history.shortcuts';
 
 // plan-review scopes
 export { annotationModeShortcuts, useAnnotationModeShortcuts } from './plan-review/annotationMode.shortcuts';

package/shortcuts/plan-review/imageAnnotator.shortcuts.ts

@@ -27,14 +27,23 @@ export const imageAnnotatorShortcuts = defineShortcutScope({
       description: 'Undo',
       bindings: ['Mod+Z'],
       section: 'Image Annotator',
+      preventDefault: true,
       displayOrder: 40,
     },
+    redo: {
+      description: 'Redo',
+      bindings: ['Mod+Shift+Z', 'Mod+Y'],
+      section: 'Image Annotator',
+      preventDefault: true,
+      displayOrder: 50,
+    },
     save: {
       description: 'Save and close annotator',
       bindings: ['Enter', 'Escape'],
       section: 'Image Annotator',
+      preventDefault: true,
       hint: 'When the image name field is focused, Escape blurs it first and Enter confirms the name; both close the annotator otherwise.',
-      displayOrder: 50,
+      displayOrder: 60,
     },
   },
 });

package/utils/math.ts

@@ -48,6 +48,12 @@ let rendererSource: MathRendererSource | null = null;
  */
 let loader: MathRendererLoader | null = null;
 let pending: Promise<MathRenderer> | null = null;
+/**
+ * Bumped by `resetMathRenderer()`. A load in flight across a reset must not
+ * fill the slot when it lands: the reset promised an empty slot, and the next
+ * `loadMathRenderer()` re-invokes the registered loader instead.
+ */
+let resetEpoch = 0;
 const listeners = new Set<() => void>();
 
 function notify(): void {
@@ -84,14 +90,22 @@ export function subscribeMathRenderer(listener: () => void): () => void {
  * Swap the loader `loadMathRenderer()` uses. Host seam
  * (`configurePlannotatorUI({ mathRendererLoader })`): a host may return a
  * module that imports katex AND its stylesheet in one chunk. A load already in
- * flight keeps going; the new loader is used from the next `loadMathRenderer()`
- * call that finds the slot empty.
+ * flight keeps going and still fills the slot when it lands (the component
+ * that started it is waiting on that result and would otherwise never
+ * typeset); the new loader is used from the next `loadMathRenderer()` call
+ * that finds the slot empty. Passing `null` unregisters the host loader and
+ * restores the package default.
  */
-export function setMathRendererLoader(next: MathRendererLoader): void {
+export function setMathRendererLoader(next: MathRendererLoader | null): void {
   loader = next;
   pending = null;
 }
 
+/** The registered host loader, or `null` while the package default applies. */
+export function getMathRendererLoader(): MathRendererLoader | null {
+  return loader;
+}
+
 /**
  * Load and register the renderer. Idempotent: a filled slot resolves at once,
  * a load in flight is shared, and a rejected load is dropped so the next call
@@ -100,9 +114,12 @@ export function setMathRendererLoader(next: MathRendererLoader): void {
 export function loadMathRenderer(): Promise<MathRenderer> {
   if (renderer) return Promise.resolve(renderer);
   if (!pending) {
+    const epoch = resetEpoch;
     const attempt = (loader ? loader() : loadDefaultMathRenderer()).then(
       (loaded) => {
-        setMathRenderer(loaded, 'loader');
+        // A reset since this load started wants the slot empty: hand the
+        // result to the caller that awaited it, but do not register it.
+        if (epoch === resetEpoch) setMathRenderer(loaded, 'loader');
         return loaded;
       },
       (err: unknown) => {
@@ -115,12 +132,19 @@ export function loadMathRenderer(): Promise<MathRenderer> {
   return pending;
 }
 
-/** Test hook: clear the slot, the loader override and any pending load. */
+/**
+ * Test hook: empty the slot (renderer and source) and forget any load in
+ * flight, so the next `loadMathRenderer()` invokes the loader afresh and a
+ * stale in-flight result cannot fill the slot after the reset. The registered
+ * loader is KEPT: resetting the renderer is not unregistering the host seam
+ * (a host's `configurePlannotatorUI` runs once, before any reset a test issues
+ * later). To drop the loader too, call `setMathRendererLoader(null)`.
+ */
 export function resetMathRenderer(): void {
   renderer = null;
   rendererSource = null;
-  loader = null;
   pending = null;
+  resetEpoch += 1;
   notify();
 }
 

package/utils/mermaid-math-slot.ts

@@ -0,0 +1,56 @@
+/**
+ * Mermaid's KaTeX, served from the math renderer slot.
+ *
+ * Mermaid renders `$$...$$` labels through its own `import("katex")`
+ * (`renderKatexUnsanitized` in the runtime; there is no config flag and no
+ * hook for it, and chunk emission is static), so a host that registers a
+ * `mathRendererLoader` and aliases `./math-default-loader` away still gets a
+ * shared `katex-*.js` chunk out of the Mermaid runtime, and a math document
+ * fetches two files: the host's loader chunk plus that shared chunk.
+ *
+ * This module is the alias target that removes it. A host redirects the
+ * `katex` specifier, for importers inside the `mermaid` package ONLY, to
+ * `@plannotator/ui/utils/mermaid-math-slot` (HANDOFF.md "Lazy renderers and
+ * eager entries", item 2). Its default export has the one method Mermaid
+ * calls, `renderToString`, and delegates to whatever renderer fills the slot
+ * in `./math`: the host's loader result, or the eager KaTeX registration.
+ * Mermaid's own options (`throwOnError: true`, `displayMode: true`, the
+ * MathML `output` mode) are passed through untouched, so a KaTeX renderer
+ * produces exactly the markup Mermaid produced from its direct import.
+ *
+ * The slot must be filled by the time Mermaid asks: `MermaidBlock` awaits
+ * `loadMathRenderer()` before rendering a diagram whose source carries a
+ * `$$` label (`hasMermaidMath`), which is a no-op resolve on a filled slot
+ * and the host's loader otherwise. An empty slot here means that load
+ * failed, and the error below surfaces in the block's error panel with the
+ * source, instead of a silently unlabeled node.
+ *
+ * Nothing imports this module by default: Plannotator never aliases, so its
+ * Mermaid keeps its direct KaTeX (inlined by the single-file builds), and
+ * this file must never import `katex` itself, or the redirect would re-create
+ * the chunk it exists to remove (`tests/entry-assets.test.ts` pins that).
+ */
+
+import { getMathRenderer, type MathRenderer } from './math';
+
+/** Mermaid's own test for a math label (`katexRegex` in the runtime). */
+const MERMAID_MATH_REGEX = /\$\$(.*)\$\$/;
+
+/** True when a diagram source carries at least one `$$...$$` label. */
+export function hasMermaidMath(source: string): boolean {
+  return MERMAID_MATH_REGEX.test(source);
+}
+
+/** Thrown when Mermaid asks for KaTeX while the math slot is still empty. */
+export const MERMAID_MATH_SLOT_EMPTY_MESSAGE =
+  'Math label: no math renderer is registered (the mathRendererLoader did not resolve before the diagram rendered)';
+
+const slotRenderer: MathRenderer = {
+  renderToString(tex, options) {
+    const renderer = getMathRenderer();
+    if (!renderer) throw new Error(MERMAID_MATH_SLOT_EMPTY_MESSAGE);
+    return renderer.renderToString(tex, options);
+  },
+};
+
+export default slotRenderer;

package/utils/parser.ts

@@ -1,5 +1,6 @@
 import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachment } from '../types';
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
+import { resolveReplyParents } from '@plannotator/core/annotation-threads';
 import { skillReferenceExportBlock } from './skillReferences';
 
 /**
@@ -1210,34 +1211,60 @@ export const exportAnnotations = (
 
   // Threaded replies (`inReplyTo`): a reply is emitted as a nested exchange
   // under its parent's entry rather than as its own numbered entry, so the
-  // coding agent reads the conversation in order. Replies whose parent is
-  // not in the export render as ordinary entries. With no `inReplyTo`
+  // coding agent reads the conversation in order. The threading rule is the
+  // shared one (resolveReplyParents): a reply whose parent is not in the
+  // export, a self-reference, and every member of an inReplyTo cycle render
+  // as ordinary entries in original order, so no annotation is ever dropped
+  // and the header count always equals what is emitted. With no `inReplyTo`
   // anywhere the output is byte-identical to the ungrouped export.
-  const exportedIds = new Set(sortedAnns.map((a: any) => a.id));
-  const isReply = (a: any) => typeof a.inReplyTo === 'string' && a.inReplyTo !== a.id && exportedIds.has(a.inReplyTo);
+  const replyParents = resolveReplyParents(sortedAnns as any[]);
+  const isReply = (a: any) => replyParents.get(a.id) != null;
   const hasReplies = sortedAnns.some(isReply);
-  const repliesOf = (parent: any): any[] =>
-    hasReplies ? sortedAnns.filter((a: any) => isReply(a) && a.inReplyTo === parent.id).sort((a: any, b: any) => a.createdA - b.createdA) : [];
+  // Children are grouped once (creation order within a parent); the old
+  // per-level re-filter and re-sort of the whole list made a long thread
+  // quadratic in both time and output size.
+  const repliesByParent = new Map<string, any[]>();
   if (hasReplies) {
+    for (const a of sortedAnns as any[]) {
+      const parent = replyParents.get(a.id);
+      if (!parent) continue;
+      const list = repliesByParent.get(parent) ?? [];
+      list.push(a);
+      repliesByParent.set(parent, list);
+    }
+    for (const list of repliesByParent.values()) list.sort((a: any, b: any) => a.createdA - b.createdA);
     emitOrder = emitOrder.filter((a) => !isReply(a));
     // Numbers stay consecutive over the entries that are actually emitted.
     annotationNumbers.clear();
     emitOrder.forEach((ann, index) => annotationNumbers.set(ann, index + 1));
   }
-  const replyBlock = (parent: any, depth = 0): string => {
-    let block = '';
-    for (const reply of repliesOf(parent)) {
+  // Nesting indent is capped so the export stays linear in the thread size
+  // (an uncapped indent on a 5,000-deep chain is 25 MB of whitespace) and
+  // the emission is an explicit stack rather than recursion, so a deep chain
+  // costs neither stack frames nor repeated string copies.
+  const MAX_REPLY_INDENT_DEPTH = 8;
+  const replyBlock = (parent: any): string => {
+    const parts: string[] = [];
+    const stack: Array<{ reply: any; depth: number }> = [];
+    const pushReplies = (of: any, depth: number) => {
+      const replies = repliesByParent.get(of.id);
+      if (!replies) return;
+      for (let i = replies.length - 1; i >= 0; i--) stack.push({ reply: replies[i], depth });
+    };
+    pushReplies(parent, 0);
+    while (stack.length > 0) {
+      const { reply, depth } = stack.pop()!;
       const who = reply.author ? `${reply.author}` : 'reply';
-      const indent = '  '.repeat(depth);
-      block += `${indent}- **Reply (${who}):** ${String(reply.text ?? '').replace(/\r?\n/g, `\n${indent}  `)}\n`;
+      const indent = '  '.repeat(Math.min(depth, MAX_REPLY_INDENT_DEPTH));
+      parts.push(`${indent}- **Reply (${who}):** ${String(reply.text ?? '').replace(/\r?\n/g, `\n${indent}  `)}\n`);
       if (reply.images && reply.images.length > 0) {
         reply.images.forEach((img: ImageAttachment) => {
-          block += `${indent}  - [${img.name}] \`${img.path}\`\n`;
+          parts.push(`${indent}  - [${img.name}] \`${img.path}\`\n`);
         });
       }
-      block += replyBlock(reply, depth + 1);
+      pushReplies(reply, depth + 1);
     }
-    return block;
+    return parts.join('');
   };
 
   let lastEmittedPage: string | null = null;

package/utils/runtimeRetry.ts

@@ -0,0 +1,31 @@
+/**
+ * A shared retry epoch for lazily loaded diagram runtimes.
+ *
+ * Mermaid and Graphviz memoize one runtime per module, so when a chunk
+ * import fails every block on the page fails together. Each block's Retry
+ * button used to bump only that block's own token, leaving its siblings on
+ * their error panels after the shared runtime had recovered. Bumping the
+ * epoch notifies every subscribed block, so one Retry re-attempts all of
+ * them (the memoized loader still issues a single import for the batch).
+ */
+export interface RuntimeRetryEpoch {
+  /** Ask every subscriber to re-attempt. */
+  bump(): void;
+  /** Subscribe; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+}
+
+export function createRuntimeRetryEpoch(): RuntimeRetryEpoch {
+  const listeners = new Set<() => void>();
+  return {
+    bump() {
+      for (const listener of [...listeners]) listener();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}