@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -74,12 +74,50 @@ export interface PageOverlayRect {
 export interface PageBoundaryMeasurement {
   prevPageId: string;
   nextPageId: string;
+  boundaryIndex?: number;
   /** Widget top edge = bottom of the previous page. */
   topPx: number;
   /** Widget bottom edge = top of the next page. */
   bottomPx: number;
 }
 
+export interface VisiblePageIndexRange {
+  start: number;
+  end: number;
+}
+
+function normalizeVisiblePageIndexRange(
+  range: VisiblePageIndexRange | null | undefined,
+  pageCount: number,
+): VisiblePageIndexRange | null {
+  if (!range || pageCount <= 0) return null;
+  const start = Math.max(0, Math.min(range.start, pageCount));
+  const end = Math.max(start, Math.min(range.end, pageCount));
+  if (start >= end) return null;
+  return { start, end };
+}
+
+function collectBoundaryIndicesForVisibleRange(
+  range: VisiblePageIndexRange,
+  pageCount: number,
+): number[] {
+  if (pageCount <= 1) return [];
+  const startBoundaryIndex = Math.max(0, range.start - 1);
+  const endBoundaryIndex = Math.min(pageCount - 2, range.end - 1);
+  if (startBoundaryIndex > endBoundaryIndex) return [];
+  const indices: number[] = [];
+  for (let index = startBoundaryIndex; index <= endBoundaryIndex; index += 1) {
+    indices.push(index);
+  }
+  return indices;
+}
+
+function parsePageBoundaryIndex(prevPageId: string): number | undefined {
+  const match = /^page-(\d+)$/.exec(prevPageId);
+  if (!match) return undefined;
+  return Number.parseInt(match[1] ?? "", 10);
+}
+
 /**
  * Pure helper: turn pre-measured page-boundary widget positions into
  * one `PageOverlayRect` per page.  No DOM access — the caller supplies
@@ -104,6 +142,8 @@ export function resolvePageOverlayRects(
         pageCount: number;
         /** Total scroll-root height in the overlay's coordinate space. */
         scrollHeight: number;
+        /** Optional viewport-bounded page range. */
+        visiblePageIndexRange?: VisiblePageIndexRange | null;
       }
     // Legacy two-arg path preserved for backward compat.  Walks
     // offsetTop chain inside the scroll-root; used by harness code
@@ -158,12 +198,26 @@ export function resolvePageOverlayRects(
   // emits widgets out-of-order (it doesn't today, but the cost is
   // negligible).
   const boundaries = [...widgets].sort((a, b) => a.topPx - b.topPx);
+  const normalizedVisiblePageIndexRange = Array.isArray(input)
+    ? null
+    : normalizeVisiblePageIndexRange(input.visiblePageIndexRange, pageCount);
+  const boundaryByIndex = new Map<number, PageBoundaryMeasurement>();
+  boundaries.forEach((boundary, index) => {
+    const boundaryIndex =
+      boundary.boundaryIndex ??
+      parsePageBoundaryIndex(boundary.prevPageId) ??
+      index;
+    boundaryByIndex.set(boundaryIndex, boundary);
+  });
+  const pageStart = normalizedVisiblePageIndexRange?.start ?? 0;
+  const pageEnd = normalizedVisiblePageIndexRange?.end ?? pageCount;
 
   const rects: PageOverlayRect[] = [];
-  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
-    const boundaryBefore = pageIndex === 0 ? null : boundaries[pageIndex - 1];
+  for (let pageIndex = pageStart; pageIndex < pageEnd; pageIndex += 1) {
+    const boundaryBefore =
+      pageIndex === 0 ? null : (boundaryByIndex.get(pageIndex - 1) ?? null);
     const boundaryAfter =
-      pageIndex === pageCount - 1 ? null : boundaries[pageIndex];
+      pageIndex === pageCount - 1 ? null : (boundaryByIndex.get(pageIndex) ?? null);
 
     let pageId: string | null = null;
     if (boundaryBefore) pageId = boundaryBefore.nextPageId;
@@ -204,14 +258,36 @@ export function resolvePageOverlayRects(
  * ancestor.
  */
 export function measureWidgetsViaBoundingRect(
-  queryRoot: Pick<HTMLElement, "querySelectorAll"> | null,
+  queryRoot: Pick<HTMLElement, "querySelectorAll"> &
+    Partial<Pick<HTMLElement, "querySelector">> | null,
   originElement: HTMLElement | null,
+  options?: {
+    pageCount?: number;
+    visiblePageIndexRange?: VisiblePageIndexRange | null;
+  },
 ): PageBoundaryMeasurement[] {
   if (!queryRoot || !originElement) return [];
   const originRect = originElement.getBoundingClientRect();
-  const widgets = Array.from(
-    queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  const normalizedVisiblePageIndexRange = normalizeVisiblePageIndexRange(
+    options?.visiblePageIndexRange,
+    options?.pageCount ?? 0,
   );
+  const queryOne =
+    typeof queryRoot.querySelector === "function"
+      ? queryRoot.querySelector.bind(queryRoot)
+      : null;
+  const widgets = normalizedVisiblePageIndexRange && queryOne && options?.pageCount
+    ? collectBoundaryIndicesForVisibleRange(
+        normalizedVisiblePageIndexRange,
+        options.pageCount,
+      )
+        .map((boundaryIndex) =>
+          queryOne(`[data-page-frame-end="page-${boundaryIndex}"]`),
+        )
+        .filter((widget): widget is HTMLElement => widget !== null)
+    : Array.from(
+        queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+      );
   const out: PageBoundaryMeasurement[] = [];
   for (const widget of widgets) {
     const prevPageId = widget.getAttribute("data-page-frame-end");
@@ -221,6 +297,7 @@ export function measureWidgetsViaBoundingRect(
     out.push({
       prevPageId,
       nextPageId,
+      boundaryIndex: parsePageBoundaryIndex(prevPageId),
       topPx: rect.top - originRect.top,
       bottomPx: rect.bottom - originRect.top,
     });
@@ -242,11 +319,33 @@ export function measureWidgetsViaBoundingRect(
  * "scroll root is often not the right origin", not about arithmetic.
  */
 export function measureWidgetsViaOffsetChain(
-  scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll">,
+  scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll"> &
+    Partial<Pick<HTMLElement, "querySelector">>,
+  options?: {
+    pageCount?: number;
+    visiblePageIndexRange?: VisiblePageIndexRange | null;
+  },
 ): PageBoundaryMeasurement[] {
-  const widgets = Array.from(
-    scrollRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  const normalizedVisiblePageIndexRange = normalizeVisiblePageIndexRange(
+    options?.visiblePageIndexRange,
+    options?.pageCount ?? 0,
   );
+  const queryOne =
+    typeof scrollRoot.querySelector === "function"
+      ? scrollRoot.querySelector.bind(scrollRoot)
+      : null;
+  const widgets = normalizedVisiblePageIndexRange && queryOne && options?.pageCount
+    ? collectBoundaryIndicesForVisibleRange(
+        normalizedVisiblePageIndexRange,
+        options.pageCount,
+      )
+        .map((boundaryIndex) =>
+          queryOne(`[data-page-frame-end="page-${boundaryIndex}"]`),
+        )
+        .filter((widget): widget is HTMLElement => widget !== null)
+    : Array.from(
+        scrollRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+      );
   const out: PageBoundaryMeasurement[] = [];
   for (const widget of widgets) {
     const prevPageId = widget.getAttribute("data-page-frame-end");
@@ -254,7 +353,13 @@ export function measureWidgetsViaOffsetChain(
     if (!prevPageId || !nextPageId) continue;
     const topPx = resolveOffsetTop(widget, scrollRoot);
     const bottomPx = topPx + resolveOffsetHeight(widget);
-    out.push({ prevPageId, nextPageId, topPx, bottomPx });
+    out.push({
+      prevPageId,
+      nextPageId,
+      boundaryIndex: parsePageBoundaryIndex(prevPageId),
+      topPx,
+      bottomPx,
+    });
   }
   return out;
 }
@@ -297,6 +402,7 @@ export interface TwPageStackOverlayLayerProps {
    * time this changes so the overlays stay aligned with content.
    */
   renderFrameRevision: number;
+  visiblePageIndexRange?: VisiblePageIndexRange | null;
   /** Optional test id applied to the overlay root. */
   "data-testid"?: string;
 }
@@ -313,6 +419,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   facet,
   scrollRoot,
   renderFrameRevision,
+  visiblePageIndexRange,
   "data-testid": testId,
 }) => {
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
@@ -351,7 +458,10 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     const origin = overlayRootRef.current;
     const pageCount = facet.getPageCount();
     if (origin) {
-      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin);
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
+        pageCount,
+        visiblePageIndexRange,
+      });
       const originRect = origin.getBoundingClientRect();
       setRects(
         resolvePageOverlayRects({
@@ -359,12 +469,24 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
           pageCount,
           scrollHeight:
             origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
+          visiblePageIndexRange,
         }),
       );
     } else {
-      setRects(resolvePageOverlayRects([scrollRoot, pageCount]));
+      const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
+        pageCount,
+        visiblePageIndexRange,
+      });
+      setRects(
+        resolvePageOverlayRects({
+          widgets,
+          pageCount,
+          scrollHeight: scrollRoot.clientHeight,
+          visiblePageIndexRange,
+        }),
+      );
     }
-  }, [facet, scrollRoot]);
+  }, [facet, scrollRoot, visiblePageIndexRange]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {

package/src/ui-tailwind/chrome-overlay/tw-revision-margin-bar-layer.tsx

@@ -0,0 +1,51 @@
+import * as React from "react";
+import type { RenderBlockDecoration } from "../../runtime/render/render-frame-types";
+import { AUTHOR_PALETTE } from "../../ui/headless/revision-decoration-model";
+
+const BAR_WIDTH_PX = 3;
+const BAR_LEFT_OFFSET_PX = 8;
+
+export interface TwRevisionMarginBarLayerProps {
+  /** Decoration rects from `frame.decorationIndex.revisions`. */
+  revisionDecorations: readonly RenderBlockDecoration[];
+  /**
+   * Author palette index keyed by revisionId.
+   * Build from `RevisionDecorationEntry.authorPaletteIndex` before passing.
+   */
+  authorPaletteIndexById: ReadonlyMap<string, number>;
+  /** Left edge of the page body in overlay coordinates (px). */
+  pageBodyLeftPx: number;
+}
+
+export const TwRevisionMarginBarLayer = React.memo(function TwRevisionMarginBarLayer({
+  revisionDecorations,
+  authorPaletteIndexById,
+  pageBodyLeftPx,
+}: TwRevisionMarginBarLayerProps) {
+  if (revisionDecorations.length === 0) return null;
+
+  return (
+    <>
+      {revisionDecorations.map((dec, idx) => {
+        const paletteIdx = authorPaletteIndexById.get(dec.refId) ?? 0;
+        const color = AUTHOR_PALETTE[paletteIdx % AUTHOR_PALETTE.length];
+        return (
+          <div
+            key={`rev-bar-${dec.refId}-${idx}`}
+            aria-hidden
+            style={{
+              position: "absolute",
+              top: dec.frame.topPx,
+              left: pageBodyLeftPx - BAR_LEFT_OFFSET_PX - BAR_WIDTH_PX,
+              width: BAR_WIDTH_PX,
+              height: dec.frame.heightPx,
+              backgroundColor: color,
+              borderRadius: 1,
+              pointerEvents: "none",
+            }}
+          />
+        );
+      })}
+    </>
+  );
+});

package/src/ui-tailwind/chrome-overlay/tw-scope-card-layer.tsx

@@ -114,10 +114,18 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   const pinnedModel = pinnedScopeId
     ? models.find((m) => m.scopeId === pinnedScopeId) ?? null
     : null;
-  if (pinnedScopeId && !pinnedModel) {
-    // Async cleanup via effect to avoid setState during render.
-    queueMicrotask(() => setPinnedScopeId(null));
-  }
+
+  // R2.b — when a pinned scope disappears from the model list (e.g. the
+  // host cleared the overlay), drop the pin. Must run in an effect, not
+  // inline in render: a render-phase setState call violates React's
+  // render-purity contract and can trigger "Maximum update depth
+  // exceeded" in React 18 concurrent mode where renders are retried
+  // before commit.
+  React.useEffect(() => {
+    if (pinnedScopeId && !models.find((m) => m.scopeId === pinnedScopeId)) {
+      setPinnedScopeId(null);
+    }
+  }, [pinnedScopeId, models]);
 
   const effectiveScopeId = pinnedModel ? pinnedScopeId : activeScopeId;
   if (!effectiveScopeId) return null;

package/src/ui-tailwind/chrome-overlay/tw-scope-card.tsx

@@ -20,6 +20,7 @@
  */
 
 import * as React from "react";
+import { X } from "lucide-react";
 import type {
   EditorRole,
   IssueMetadataValue,
@@ -148,13 +149,25 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
   const headerId = React.useId();
   const liveRegionId = React.useId();
 
-  // --- Focus management ----------------------------------------------------
+  // Cached focusable list — populated on mount and on subtree mutations so
+  // Tab handler never calls getFocusable() per-keystroke (perf §7).
+  const focusablesRef = React.useRef<HTMLElement[]>([]);
+
+  // --- Focus management + focusable cache init ----------------------------
   React.useEffect(() => {
     const root = rootRef.current;
     if (!root) return undefined;
-    const first = getFocusable(root)[0];
+
+    const refresh = () => { focusablesRef.current = getFocusable(root); };
+    refresh();
+
+    const observer = new MutationObserver(refresh);
+    observer.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ["disabled", "hidden", "inert"] });
+
+    const first = focusablesRef.current[0];
     first?.focus();
-    return undefined;
+
+    return () => observer.disconnect();
   }, []);
 
   // --- Escape + click-outside ---------------------------------------------
@@ -183,18 +196,17 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
     };
   }, [onClose, pinned]);
 
-  // --- Focus trap ----------------------------------------------------------
+  // --- Focus trap (reads cached list — no DOM query per Tab) --------------
   const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
     if (event.key !== "Tab") return;
-    const root = rootRef.current;
-    if (!root) return;
-    const focusables = getFocusable(root);
+    const focusables = focusablesRef.current;
     if (focusables.length === 0) return;
     const first = focusables[0];
     const last = focusables[focusables.length - 1];
     const active = document.activeElement;
+    const root = rootRef.current;
     if (event.shiftKey) {
-      if (active === first || !root.contains(active)) {
+      if (active === first || !root?.contains(active)) {
         event.preventDefault();
         last.focus();
       }
@@ -266,7 +278,7 @@ export const TwScopeCard: React.FC<TwScopeCardProps> = ({
             onClick={onClose}
             data-testid="scope-card-close"
           >
-            ×
+            <X className="h-3.5 w-3.5" aria-hidden="true" />
           </button>
         </div>
       </div>
@@ -614,9 +626,17 @@ function formatRelative(isoString: string): string {
 function getFocusable(root: HTMLElement): HTMLElement[] {
   const selector =
     'button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"]), input:not([disabled]), select:not([disabled]), textarea:not([disabled])';
-  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter(
-    (el) => !el.hasAttribute("inert") && el.offsetParent !== null,
-  );
+  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter((el) => {
+    if (el.hasAttribute("inert")) return false;
+    // Walk the ancestor chain for visibility/display — tolerates display:contents.
+    let node: HTMLElement | null = el;
+    while (node && node !== root) {
+      const s = getComputedStyle(node);
+      if (s.display === "none" || s.visibility === "hidden") return false;
+      node = node.parentElement;
+    }
+    return true;
+  });
 }
 
 function posturePresentationLabel(posture: ScopeCardModel["posture"]): string {

package/src/ui-tailwind/chrome-overlay/tw-toc-outline-sidebar.tsx

@@ -0,0 +1,133 @@
+/**
+ * Lane 6d — Slice N8: TOC outline sidebar (P11.8).
+ *
+ * Renders the formal TOC field entries from `getTocSnapshot()` as a
+ * collapsible left panel.  Unlike the heading-based nav panel (which
+ * uses `DocumentNavigationSnapshot.headings`), this sidebar reflects the
+ * actual `<w:sdt>` / `TOC` field content — complete with the document
+ * author's chosen heading levels, custom styles, and page numbers.
+ *
+ * Navigation: clicking an entry calls `onNavigate(entry)`.  The host
+ * is responsible for resolving `entry.anchor` or `entry.bookmarkName`
+ * into a runtime scroll (typically via `runtime.setSelection` or
+ * `onNavigateHeading(entry.headingId)`).
+ *
+ * `status === "stale"` shows a banner so the reviewer knows the TOC
+ * needs a refresh before page numbers are reliable.
+ */
+
+import React from "react";
+import type { TocSnapshot, TocEntrySnapshot } from "../../api/public-types";
+
+export interface TwTocOutlineSidebarProps {
+  /** `null` when the document has no TOC field. */
+  tocSnapshot: TocSnapshot | null;
+  /** Called when the user clicks a TOC entry. */
+  onNavigate: (entry: TocEntrySnapshot) => void;
+  /** Whether the sidebar is currently open. */
+  open: boolean;
+  /** Called when the close button is pressed. */
+  onClose: () => void;
+}
+
+/**
+ * Indentation step per outline level (px).  Levels start at 1 so
+ * level-1 gets 0 extra indentation; level-2 gets 12 px, etc.
+ */
+const INDENT_PX_PER_LEVEL = 12;
+
+export function TwTocOutlineSidebar({
+  tocSnapshot,
+  onNavigate,
+  open,
+  onClose,
+}: TwTocOutlineSidebarProps): React.ReactElement | null {
+  if (!open) return null;
+
+  const entries = tocSnapshot?.entries ?? [];
+  const isStale = tocSnapshot?.status === "stale";
+
+  return (
+    <aside
+      aria-label="Table of contents"
+      data-toc-sidebar=""
+      className="flex h-full w-56 shrink-0 flex-col border-r border-border bg-surface"
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between border-b border-border px-3 py-2">
+        <span className="text-xs font-medium uppercase tracking-wider text-secondary">
+          Table of Contents
+        </span>
+        <button
+          type="button"
+          aria-label="Close table of contents"
+          data-toc-close=""
+          onClick={onClose}
+          className="inline-flex h-6 w-6 items-center justify-center rounded-md text-secondary transition-colors hover:bg-surface-hover"
+        >
+          {/* ×  */}
+          <svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+            <path d="M1 1l10 10M11 1L1 11" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+          </svg>
+        </button>
+      </div>
+
+      {/* Stale banner */}
+      {isStale ? (
+        <div
+          role="status"
+          data-toc-stale=""
+          className="border-b border-border bg-[var(--color-warning-soft,theme(colors.amber.50))] px-3 py-1.5 text-[11px] text-[var(--color-warning,theme(colors.amber.700))]"
+        >
+          Table of contents may be out of date.
+        </div>
+      ) : null}
+
+      {/* Entry list */}
+      <nav
+        className="flex-1 overflow-y-auto px-2 py-2"
+        aria-label="Document outline"
+      >
+        {entries.length > 0 ? (
+          <ul className="space-y-px">
+            {entries.map((entry) => {
+              const indent = (entry.level - 1) * INDENT_PX_PER_LEVEL;
+              return (
+                <li key={entry.tocEntryId}>
+                  <button
+                    type="button"
+                    data-toc-entry-id={entry.tocEntryId}
+                    data-toc-level={entry.level}
+                    className="flex w-full items-baseline gap-1 rounded-md px-2 py-1 text-left text-xs text-primary transition-colors hover:bg-surface-hover"
+                    style={{ paddingLeft: `${8 + indent}px` }}
+                    onClick={() => onNavigate(entry)}
+                  >
+                    <span className="flex-1 truncate">{entry.text}</span>
+                    {entry.pageIndex != null ? (
+                      <span
+                        aria-label={`page ${entry.pageIndex + 1}`}
+                        className="shrink-0 tabular-nums text-tertiary"
+                      >
+                        {entry.pageIndex + 1}
+                      </span>
+                    ) : null}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        ) : tocSnapshot === null ? (
+          <p className="px-2 py-4 text-xs text-tertiary">
+            No table of contents found in this document.
+          </p>
+        ) : (
+          <p className="px-2 py-4 text-xs text-tertiary">
+            The table of contents is empty.
+          </p>
+        )}
+      </nav>
+    </aside>
+  );
+}
+
+export default TwTocOutlineSidebar;

package/src/ui-tailwind/editor-surface/chart-node-view.tsx

@@ -12,6 +12,7 @@
  */
 
 import React from "react";
+import { flushSync } from "react-dom";
 import { createRoot, type Root } from "react-dom/client";
 import type { Node as PMNode } from "prosemirror-model";
 import type { NodeViewConstructor } from "prosemirror-view";
@@ -24,6 +25,7 @@ const DEFAULT_HEIGHT = 336;
 class ChartNodeViewInstance {
   readonly dom: HTMLElement;
   private _root: Root | null = null;
+  private _mountedChartId: string | null = null;
 
   constructor(node: PMNode) {
     this.dom = document.createElement("span");
@@ -33,41 +35,78 @@ class ChartNodeViewInstance {
     this._mount(node);
   }
 
+  /**
+   * Mount or update the React root to render the chart whose id lives in
+   * `node.attrs.parsedChartId`. Transitions handled explicitly:
+   *
+   *   - id present, entry in store → create/reuse root, render ChartSurface.
+   *   - id present, entry missing  → unmount any prior root (don't leave a
+   *                                  stale chart from a previous id mounted).
+   *   - id null / undefined        → unmount any prior root (no chart).
+   *
+   * The previous implementation handled only the first case and silently
+   * left the prior React tree mounted on null / missing-entry transitions.
+   */
   private _mount(node: PMNode): void {
-    const parsedChartId = node.attrs.parsedChartId as string | null;
-    if (!parsedChartId) return;
+    const parsedChartId = (node.attrs.parsedChartId as string | null) ?? null;
+
+    if (!parsedChartId) {
+      this._unmountRoot();
+      return;
+    }
 
     const entry = chartModelStore.get(parsedChartId);
-    if (!entry) return;
+    if (!entry) {
+      this._unmountRoot();
+      return;
+    }
 
     const width = (node.attrs.widthPx as number | null) ?? entry.widthPx ?? DEFAULT_WIDTH;
     const height = (node.attrs.heightPx as number | null) ?? entry.heightPx ?? DEFAULT_HEIGHT;
+    const previewMediaId = node.attrs.previewMediaId as string | null;
+    const previewSrc = node.attrs.previewSrc as string | null;
 
     const el = React.createElement(ChartSurface, {
       model: entry.model,
       width,
       height,
       theme: entry.theme,
+      ...(previewMediaId ? { previewMediaId } : {}),
+      ...(previewMediaId && previewSrc
+        ? {
+            resolveMediaUrl: (mediaId: string) =>
+              mediaId === previewMediaId ? previewSrc : undefined,
+          }
+        : {}),
     });
 
     if (!this._root) {
       this._root = createRoot(this.dom);
     }
-    this._root.render(el);
+    flushSync(() => {
+      this._root?.render(el);
+    });
+    this._mountedChartId = parsedChartId;
+  }
+
+  private _unmountRoot(): void {
+    if (this._root) {
+      this._root.unmount();
+      this._root = null;
+    }
+    this._mountedChartId = null;
   }
 
   update(node: PMNode): boolean {
-    const parsedChartId = node.attrs.parsedChartId as string | null;
-    if (!parsedChartId) return false;
+    // Handle every `parsedChartId` transition in-place so PM doesn't
+    // destroy/recreate this NodeView on attr-only changes. Returning true
+    // tells PM "I handled this update."
     this._mount(node);
     return true;
   }
 
   destroy(): void {
-    if (this._root) {
-      this._root.unmount();
-      this._root = null;
-    }
+    this._unmountRoot();
   }
 
   stopEvent(): boolean {