@nu-appdev/northwestern-starlight-theme 1.2.0 → 1.3.0

package/src/scripts/mermaid/fullscreen.ts

@@ -0,0 +1,120 @@
+/**
+ * Fullscreen viewer coordinator.
+ *
+ * Wires together overlay construction, pan/zoom interaction, keyboard/focus
+ * management, and controls bar action dispatch. Manages the open/close
+ * lifecycle including entry/exit animations and focus restoration.
+ */
+
+import { installKeyboardAndFocus } from "./focus";
+import { buildOverlay } from "./overlay";
+import { createPanZoomController } from "./pan-zoom";
+import { downloadDiagramSvg, flashSuccess, showToast, writeToClipboard } from "./ui";
+
+const OPEN_SCALE = "scale(0.97)";
+const OPEN_TRANSITION = "transform 300ms cubic-bezier(0.16, 1, 0.3, 1)";
+const OPEN_DURATION_MS = 300;
+const CLOSE_TRANSITION = "transform 200ms ease-in";
+const CLOSE_DURATION_MS = 200;
+const CLOSE_SCALE_FACTOR = 0.97;
+
+/**
+ * Open the fullscreen viewer for a rendered Mermaid diagram.
+ *
+ * @param diagramSvg - The rendered SVG element to display (cloned, not modified).
+ * @param diagramContainer - The `pre.mermaid` container holding the diagram.
+ * @param triggerButton - The button that opened fullscreen (receives focus on close).
+ * @param openedViaKeyboard - `true` if opened with Enter/Space (shows focus ring on first control).
+ */
+export function openFullscreen(
+    diagramSvg: SVGElement,
+    diagramContainer: HTMLElement,
+    triggerButton?: HTMLElement,
+    openedViaKeyboard = false,
+): void {
+    const { overlay, controls, viewport, wrapper, zoomBadge, diagramSource } = buildOverlay(
+        diagramSvg,
+        diagramContainer,
+    );
+
+    overlay.style.opacity = "0";
+    wrapper.style.transform = OPEN_SCALE;
+    wrapper.style.transition = OPEN_TRANSITION;
+    document.body.appendChild(overlay);
+    document.body.style.overflow = "hidden";
+
+    requestAnimationFrame(() => {
+        overlay.style.opacity = "1";
+        wrapper.style.transform = "scale(1)";
+        setTimeout(() => {
+            wrapper.style.transition = "";
+        }, OPEN_DURATION_MS);
+    });
+
+    const panZoom = createPanZoomController(viewport, wrapper, zoomBadge);
+
+    controls.addEventListener("click", (event) => {
+        const button = (event.target as HTMLElement).closest<HTMLButtonElement>(".nu-mermaid-overlay-btn");
+        if (!button) return;
+
+        switch (button.dataset.action) {
+            case "close":
+                closeOverlay();
+                break;
+            case "zoom-in":
+                panZoom.zoomTo(panZoom.scale * 1.3);
+                break;
+            case "zoom-out":
+                panZoom.zoomTo(panZoom.scale * 0.7);
+                break;
+            case "zoom-reset":
+                panZoom.resetView();
+                break;
+            case "download-svg":
+                downloadDiagramSvg(diagramSvg, diagramContainer);
+                flashSuccess(button, "Downloaded!");
+                break;
+            case "copy-svg":
+                writeToClipboard(diagramSvg.outerHTML, button);
+                showToast(viewport, "SVG copied to clipboard");
+                break;
+            case "copy-source":
+                if (diagramSource) {
+                    writeToClipboard(diagramSource, button);
+                    showToast(viewport, "Mermaid source copied to clipboard");
+                }
+                break;
+        }
+    });
+
+    overlay.addEventListener("click", (event) => {
+        if (event.target === overlay) closeOverlay();
+    });
+
+    const removeKeyboardHandlers = installKeyboardAndFocus({
+        overlay,
+        controls,
+        panZoom,
+        onClose: closeOverlay,
+        openedViaKeyboard,
+    });
+
+    let closed = false;
+    function closeOverlay(): void {
+        if (closed) return;
+        closed = true;
+        panZoom.destroy();
+
+        overlay.style.opacity = "0";
+        wrapper.style.transition = CLOSE_TRANSITION;
+        wrapper.style.transform = `translate(${panZoom.panX}px, ${panZoom.panY}px) scale(${panZoom.scale * CLOSE_SCALE_FACTOR})`;
+
+        triggerButton?.focus();
+
+        setTimeout(() => {
+            removeKeyboardHandlers();
+            document.body.style.overflow = "";
+            overlay.remove();
+        }, CLOSE_DURATION_MS);
+    }
+}

package/src/scripts/mermaid/index.ts

@@ -0,0 +1,2 @@
+export { openFullscreen } from "./fullscreen";
+export { diagramSources, renderAllDiagrams, type ThemeMode } from "./render";

package/src/scripts/mermaid/overlay.ts

@@ -0,0 +1,132 @@
+/**
+ * DOM construction for the fullscreen Mermaid viewer.
+ *
+ * Builds the complete overlay element tree: dialog shell, controls bar with
+ * zoom/download/copy/close buttons, scrollable viewport, diagram wrapper,
+ * and zoom percentage badge. Returns typed element references for the coordinator.
+ */
+
+import { diagramSources } from "./render";
+import { createActionButton, createZoomButton, ICON_PATHS } from "./ui";
+
+/** Element references returned by {@link buildOverlay} for the coordinator to wire up. */
+export interface OverlayElements {
+    /** Root dialog element covering the full viewport. */
+    overlay: HTMLDivElement;
+    /** Top controls bar containing zoom, download, copy, and close buttons. */
+    controls: HTMLDivElement;
+    /** Scrollable/pannable area containing the diagram. */
+    viewport: HTMLDivElement;
+    /** Inner wrapper around the cloned SVG (receives pan/zoom transforms). */
+    wrapper: HTMLDivElement;
+    /** Zoom percentage indicator in the viewport corner. */
+    zoomBadge: HTMLSpanElement;
+    /** Raw Mermaid source text if available (for "Copy Mermaid" action). */
+    diagramSource: string | undefined;
+}
+
+const CONTROLS_BAR_HEIGHT_PX = 120;
+const VIEWPORT_FILL_RATIO = 0.92;
+
+/**
+ * Build the complete overlay DOM tree for a given diagram.
+ *
+ * The SVG is cloned and scaled to fit the viewport at 92% fill. The original
+ * diagram element is not modified.
+ */
+export function buildOverlay(sourceSvg: SVGElement, diagramContainer: HTMLElement): OverlayElements {
+    const overlay = document.createElement("div");
+    overlay.className = "nu-mermaid-overlay";
+    overlay.setAttribute("role", "dialog");
+    overlay.setAttribute("aria-modal", "true");
+    overlay.setAttribute("aria-label", "Mermaid diagram fullscreen viewer");
+
+    const controls = buildControlsBar(diagramContainer);
+    overlay.appendChild(controls.element);
+
+    const { viewport, wrapper, zoomBadge } = buildViewport(sourceSvg);
+    overlay.appendChild(viewport);
+
+    return {
+        overlay,
+        controls: controls.element,
+        viewport,
+        wrapper,
+        zoomBadge,
+        diagramSource: controls.diagramSource,
+    };
+}
+
+const OVERLAY_BTN_CLASS = "nu-mermaid-btn nu-mermaid-overlay-btn";
+
+function buildControlsBar(diagramContainer: HTMLElement) {
+    const bar = document.createElement("div");
+    bar.className = "nu-mermaid-overlay-controls";
+
+    bar.appendChild(createZoomButton("Zoom In (+)", "zoom-in", ICON_PATHS.zoomIn, OVERLAY_BTN_CLASS));
+    bar.appendChild(createZoomButton("Zoom Out (-)", "zoom-out", ICON_PATHS.zoomOut, OVERLAY_BTN_CLASS));
+    bar.appendChild(createActionButton("Reset (0)", "zoom-reset", ICON_PATHS.reset, OVERLAY_BTN_CLASS));
+
+    const separator = document.createElement("span");
+    separator.className = "nu-mermaid-separator";
+    bar.appendChild(separator);
+
+    bar.appendChild(createActionButton("Download SVG", "download-svg", ICON_PATHS.download, OVERLAY_BTN_CLASS));
+    bar.appendChild(createActionButton("Copy SVG", "copy-svg", ICON_PATHS.copy, OVERLAY_BTN_CLASS));
+
+    const diagramSource = diagramSources.get(diagramContainer);
+    if (diagramSource) {
+        bar.appendChild(createActionButton("Copy Mermaid", "copy-source", ICON_PATHS.code, OVERLAY_BTN_CLASS));
+    }
+
+    const spacer = document.createElement("span");
+    spacer.className = "nu-mermaid-spacer";
+    bar.appendChild(spacer);
+
+    bar.appendChild(
+        createActionButton("Close (Esc)", "close", ICON_PATHS.close, `${OVERLAY_BTN_CLASS} nu-mermaid-close`),
+    );
+
+    return { element: bar, diagramSource };
+}
+
+function buildViewport(sourceSvg: SVGElement) {
+    const viewport = document.createElement("div");
+    viewport.className = "nu-mermaid-viewport";
+
+    const wrapper = document.createElement("div");
+    wrapper.className = "mermaid nu-mermaid-fullscreen";
+
+    const clonedSvg = sourceSvg.cloneNode(true) as SVGElement;
+    clonedSvg.removeAttribute("style");
+
+    const { width, height } = parseSvgDimensions(sourceSvg);
+    const fitScale = calculateFitScale(width, height);
+    clonedSvg.setAttribute("width", String(Math.round(width * fitScale)));
+    clonedSvg.setAttribute("height", String(Math.round(height * fitScale)));
+
+    const zoomBadge = document.createElement("span");
+    zoomBadge.className = "nu-mermaid-zoom-badge";
+    zoomBadge.textContent = "100%";
+
+    wrapper.appendChild(clonedSvg);
+    viewport.appendChild(wrapper);
+    viewport.appendChild(zoomBadge);
+
+    return { viewport, wrapper, zoomBadge };
+}
+
+function parseSvgDimensions(svg: SVGElement): { width: number; height: number } {
+    const viewBox = svg.getAttribute("viewBox");
+    if (viewBox) {
+        const [, , w, h] = viewBox.split(/[\s,]+/).map(Number);
+        if (w > 0 && h > 0) return { width: w, height: h };
+    }
+    return { width: 800, height: 600 };
+}
+
+function calculateFitScale(contentWidth: number, contentHeight: number): number {
+    const maxWidth = window.innerWidth * VIEWPORT_FILL_RATIO;
+    const maxHeight = (window.innerHeight - CONTROLS_BAR_HEIGHT_PX) * VIEWPORT_FILL_RATIO;
+    return Math.min(maxWidth / contentWidth, maxHeight / contentHeight);
+}

package/src/scripts/mermaid/pan-zoom.ts

@@ -0,0 +1,285 @@
+/**
+ * Pan/zoom interaction controller for the fullscreen Mermaid viewport.
+ *
+ * Manages all pointer interactions: cursor-anchored wheel zoom, mouse drag
+ * with momentum, touch pan/pinch-to-zoom, and double-click zoom.
+ * Returns a controller object with methods to programmatically zoom, pan,
+ * reset, and tear down all listeners.
+ */
+
+/** Controller returned by {@link createPanZoomController}. */
+export interface PanZoomController {
+    /** Current horizontal pan offset in pixels. */
+    readonly panX: number;
+    /** Current vertical pan offset in pixels. */
+    readonly panY: number;
+    /** Current zoom scale relative to initial fit (1.0 = 100%). */
+    readonly scale: number;
+    /** Set the zoom scale, clamped to [{@link MIN_SCALE}, {@link MAX_SCALE}]. */
+    zoomTo(scale: number): void;
+    /** Reset pan and zoom to the initial state (0, 0, 1.0). */
+    resetView(): void;
+    /** Shift the pan offset by the given pixel deltas. */
+    panBy(dx: number, dy: number): void;
+    /** Cancel any active inertia and remove all event listeners. */
+    destroy(): void;
+}
+
+const MIN_SCALE = 0.1;
+const MAX_SCALE = 20;
+const WHEEL_ZOOM_IN_FACTOR = 1.1;
+const WHEEL_ZOOM_OUT_FACTOR = 0.9;
+const DOUBLE_CLICK_ZOOM_FACTOR = 1.5;
+const INERTIA_FRICTION = 0.92;
+const INERTIA_MIN_VELOCITY = 0.5;
+const INERTIA_RELEASE_WINDOW_MS = 50;
+const FRAME_DURATION_MS = 16;
+
+/**
+ * Create a pan/zoom controller bound to the given viewport elements.
+ *
+ * @param viewport - The scrollable container that receives pointer events.
+ * @param wrapper - The inner element that receives CSS transforms.
+ * @param zoomBadge - The element displaying the current zoom percentage.
+ */
+export function createPanZoomController(
+    viewport: HTMLElement,
+    wrapper: HTMLElement,
+    zoomBadge: HTMLElement,
+): PanZoomController {
+    let scale = 1;
+    let panX = 0;
+    let panY = 0;
+
+    function applyTransform(): void {
+        wrapper.style.transform = `translate(${panX}px, ${panY}px) scale(${scale})`;
+        wrapper.style.transformOrigin = "center center";
+        zoomBadge.textContent = `${Math.round(scale * 100)}%`;
+    }
+
+    function clampScale(value: number): number {
+        return Math.min(Math.max(MIN_SCALE, value), MAX_SCALE);
+    }
+
+    function zoomTo(newScale: number): void {
+        scale = clampScale(newScale);
+        applyTransform();
+    }
+
+    function resetView(): void {
+        scale = 1;
+        panX = 0;
+        panY = 0;
+        applyTransform();
+    }
+
+    function panBy(dx: number, dy: number): void {
+        panX += dx;
+        panY += dy;
+        applyTransform();
+    }
+
+    /**
+     * Zoom toward a specific screen coordinate so the point under the
+     * cursor/finger stays fixed. Used by wheel, double-click, and pinch.
+     */
+    function zoomTowardPoint(clientX: number, clientY: number, targetScale: number): void {
+        const clamped = clampScale(targetScale);
+        const rect = viewport.getBoundingClientRect();
+        const cursorX = clientX - rect.left - rect.width / 2;
+        const cursorY = clientY - rect.top - rect.height / 2;
+        const ratio = 1 - clamped / scale;
+        panX += (cursorX - panX) * ratio;
+        panY += (cursorY - panY) * ratio;
+        scale = clamped;
+        applyTransform();
+    }
+
+    let velocityX = 0;
+    let velocityY = 0;
+    let lastMoveTimestamp = 0;
+    let inertiaFrameId = 0;
+
+    function runInertia(): void {
+        cancelAnimationFrame(inertiaFrameId);
+        function tick(): void {
+            if (Math.abs(velocityX) < INERTIA_MIN_VELOCITY && Math.abs(velocityY) < INERTIA_MIN_VELOCITY) return;
+            panX += velocityX;
+            panY += velocityY;
+            velocityX *= INERTIA_FRICTION;
+            velocityY *= INERTIA_FRICTION;
+            applyTransform();
+            inertiaFrameId = requestAnimationFrame(tick);
+        }
+        inertiaFrameId = requestAnimationFrame(tick);
+    }
+
+    function cancelInertia(): void {
+        cancelAnimationFrame(inertiaFrameId);
+        velocityX = 0;
+        velocityY = 0;
+    }
+
+    /** Record the velocity for a movement delta, normalized to 16ms frames. */
+    function trackVelocity(dx: number, dy: number, timestamp: number): void {
+        const elapsed = timestamp - lastMoveTimestamp;
+        if (elapsed > 0) {
+            velocityX = dx * (FRAME_DURATION_MS / elapsed);
+            velocityY = dy * (FRAME_DURATION_MS / elapsed);
+        }
+        lastMoveTimestamp = timestamp;
+    }
+
+    /** Start inertia only if the last movement was recent (finger/mouse was still moving at release). */
+    function releaseWithMomentum(): void {
+        if (performance.now() - lastMoveTimestamp < INERTIA_RELEASE_WINDOW_MS) {
+            runInertia();
+        }
+    }
+
+    function handleWheel(event: WheelEvent): void {
+        event.preventDefault();
+        const factor = event.deltaY > 0 ? WHEEL_ZOOM_OUT_FACTOR : WHEEL_ZOOM_IN_FACTOR;
+        zoomTowardPoint(event.clientX, event.clientY, scale * factor);
+    }
+
+    viewport.addEventListener("wheel", handleWheel, { passive: false });
+
+    let isMousePanning = false;
+    let mouseAnchorX = 0;
+    let mouseAnchorY = 0;
+    let previousMouseX = 0;
+    let previousMouseY = 0;
+
+    function handleMouseDown(event: MouseEvent): void {
+        cancelInertia();
+        isMousePanning = true;
+        mouseAnchorX = event.clientX - panX;
+        mouseAnchorY = event.clientY - panY;
+        previousMouseX = event.clientX;
+        previousMouseY = event.clientY;
+        lastMoveTimestamp = performance.now();
+        viewport.style.cursor = "grabbing";
+        event.preventDefault();
+    }
+
+    function handleMouseMove(event: MouseEvent): void {
+        if (!isMousePanning) return;
+        trackVelocity(event.clientX - previousMouseX, event.clientY - previousMouseY, performance.now());
+        previousMouseX = event.clientX;
+        previousMouseY = event.clientY;
+        panX = event.clientX - mouseAnchorX;
+        panY = event.clientY - mouseAnchorY;
+        applyTransform();
+    }
+
+    function handleMouseUp(): void {
+        isMousePanning = false;
+        viewport.style.cursor = "grab";
+        releaseWithMomentum();
+    }
+
+    viewport.addEventListener("mousedown", handleMouseDown);
+    window.addEventListener("mousemove", handleMouseMove);
+    window.addEventListener("mouseup", handleMouseUp);
+
+    let isTouchPanning = false;
+    let pinchDistance = 0;
+    let touchCenterX = 0;
+    let touchCenterY = 0;
+
+    function handleTouchStart(event: TouchEvent): void {
+        cancelInertia();
+        if (event.touches.length === 1) {
+            isTouchPanning = true;
+            touchCenterX = event.touches[0].clientX;
+            touchCenterY = event.touches[0].clientY;
+            lastMoveTimestamp = performance.now();
+        } else if (event.touches.length === 2) {
+            isTouchPanning = false;
+            pinchDistance = Math.hypot(
+                event.touches[0].clientX - event.touches[1].clientX,
+                event.touches[0].clientY - event.touches[1].clientY,
+            );
+            touchCenterX = (event.touches[0].clientX + event.touches[1].clientX) / 2;
+            touchCenterY = (event.touches[0].clientY + event.touches[1].clientY) / 2;
+        }
+        event.preventDefault();
+    }
+
+    function handleTouchMove(event: TouchEvent): void {
+        if (event.touches.length === 1 && isTouchPanning) {
+            const dx = event.touches[0].clientX - touchCenterX;
+            const dy = event.touches[0].clientY - touchCenterY;
+            trackVelocity(dx, dy, performance.now());
+            panX += dx;
+            panY += dy;
+            touchCenterX = event.touches[0].clientX;
+            touchCenterY = event.touches[0].clientY;
+            applyTransform();
+        } else if (event.touches.length === 2) {
+            const distance = Math.hypot(
+                event.touches[0].clientX - event.touches[1].clientX,
+                event.touches[0].clientY - event.touches[1].clientY,
+            );
+            const midX = (event.touches[0].clientX + event.touches[1].clientX) / 2;
+            const midY = (event.touches[0].clientY + event.touches[1].clientY) / 2;
+
+            if (pinchDistance > 0) {
+                zoomTowardPoint(midX, midY, scale * (distance / pinchDistance));
+                panX += midX - touchCenterX;
+                panY += midY - touchCenterY;
+                applyTransform();
+            }
+
+            pinchDistance = distance;
+            touchCenterX = midX;
+            touchCenterY = midY;
+        }
+        event.preventDefault();
+    }
+
+    function handleTouchEnd(): void {
+        const wasPanning = isTouchPanning;
+        isTouchPanning = false;
+        pinchDistance = 0;
+        if (wasPanning) releaseWithMomentum();
+    }
+
+    viewport.addEventListener("touchstart", handleTouchStart, { passive: false });
+    viewport.addEventListener("touchmove", handleTouchMove, { passive: false });
+    viewport.addEventListener("touchend", handleTouchEnd);
+
+    function handleDoubleClick(event: MouseEvent): void {
+        event.preventDefault();
+        zoomTowardPoint(event.clientX, event.clientY, scale * DOUBLE_CLICK_ZOOM_FACTOR);
+    }
+
+    viewport.addEventListener("dblclick", handleDoubleClick);
+
+    return {
+        get panX() {
+            return panX;
+        },
+        get panY() {
+            return panY;
+        },
+        get scale() {
+            return scale;
+        },
+        zoomTo,
+        resetView,
+        panBy,
+        destroy(): void {
+            cancelInertia();
+            viewport.removeEventListener("wheel", handleWheel);
+            viewport.removeEventListener("mousedown", handleMouseDown);
+            window.removeEventListener("mousemove", handleMouseMove);
+            window.removeEventListener("mouseup", handleMouseUp);
+            viewport.removeEventListener("touchstart", handleTouchStart);
+            viewport.removeEventListener("touchmove", handleTouchMove);
+            viewport.removeEventListener("touchend", handleTouchEnd);
+            viewport.removeEventListener("dblclick", handleDoubleClick);
+        },
+    };
+}

package/src/scripts/mermaid/render.ts

@@ -0,0 +1,143 @@
+/**
+ * Diagram source registry, Mermaid runtime adapter, and viewport-aware render scheduler.
+ *
+ * Captures raw diagram definitions before `astro-mermaid` replaces them with SVG,
+ * lazily renders diagrams as they enter the viewport, and re-renders on theme changes.
+ */
+
+/** Active theme mode derived from the `data-theme` attribute on `<html>`. */
+export type ThemeMode = "light" | "dark";
+
+type MermaidRuntime = typeof import("mermaid")["default"];
+
+const DIAGRAM_SELECTOR = "pre.mermaid:not(.nu-mermaid-fullscreen)";
+const PRERENDER_MARGIN = "200px";
+
+/** Registry mapping diagram containers to their raw Mermaid source text. */
+export const diagramSources = new WeakMap<Element, string>();
+
+/** Tracks which theme each diagram was last rendered with to avoid redundant re-renders. */
+const renderedThemes = new WeakMap<HTMLElement, ThemeMode>();
+
+/** Per-container render version to discard stale async completions. */
+const renderVersions = new WeakMap<HTMLElement, number>();
+
+let runtimePromise: Promise<MermaidRuntime> | undefined;
+
+/** Resolve the active theme from the document's `data-theme` attribute. */
+export function resolveThemeMode(): ThemeMode {
+    return document.documentElement.dataset.theme === "light" ? "light" : "dark";
+}
+
+/** Lazy-load the Mermaid runtime. Cached after first import. */
+async function loadRuntime(): Promise<MermaidRuntime> {
+    runtimePromise ??= import("mermaid").then((m) => m.default);
+    return runtimePromise;
+}
+
+/** Read the Northwestern Mermaid config injected by the theme integration for the given mode. */
+function themeConfig(mode: ThemeMode): Record<string, unknown> {
+    return window.__NU_MERMAID_CONFIGS__?.[mode] ?? {};
+}
+
+/**
+ * Walk the DOM and capture raw source text from all `pre.mermaid` elements.
+ *
+ * Prefers the `data-diagram` attribute (set by `astro-mermaid` before it renders SVG)
+ * over `textContent`, which may contain concatenated SVG text nodes after rendering.
+ * Persists source back to `data-diagram` so it survives across render cycles and
+ * Astro view transitions.
+ */
+export function captureDiagramSources(): void {
+    for (const element of document.querySelectorAll<HTMLElement>("pre.mermaid")) {
+        if (diagramSources.has(element)) continue;
+
+        const source = element.getAttribute("data-diagram")?.trim() || element.textContent?.trim() || "";
+        if (!source) continue;
+
+        diagramSources.set(element, source);
+        if (!element.hasAttribute("data-diagram")) {
+            element.setAttribute("data-diagram", source);
+        }
+    }
+}
+
+/**
+ * Render a single diagram container with the given theme.
+ *
+ * Initializes the Mermaid runtime with the Northwestern theme config,
+ * generates SVG, and injects it into the container.
+ */
+async function renderDiagram(container: HTMLElement, mode: ThemeMode, index: number): Promise<void> {
+    const source =
+        diagramSources.get(container) ??
+        container.getAttribute("data-diagram")?.trim() ??
+        container.textContent?.trim();
+    if (!source) return;
+
+    const version = (renderVersions.get(container) ?? 0) + 1;
+    renderVersions.set(container, version);
+
+    const mermaidRuntime = await loadRuntime();
+    if (renderVersions.get(container) !== version) return;
+
+    mermaidRuntime.initialize({ startOnLoad: false, ...(themeConfig(mode) as Record<string, unknown>) });
+
+    const renderId = `nu-mermaid-${mode}-${index}-${Math.random().toString(36).slice(2, 8)}`;
+    // mermaid.render returns sanitized SVG from trusted diagram source (user-authored markdown)
+    const { svg, bindFunctions } = await mermaidRuntime.render(renderId, source);
+    if (renderVersions.get(container) !== version) return;
+
+    // SVG is generated by Mermaid from user-authored markdown, not external input
+    container.innerHTML = svg;
+    bindFunctions?.(container);
+    renderedThemes.set(container, mode);
+}
+
+/** Check whether a container needs rendering for the given mode. */
+function needsRender(container: HTMLElement, mode: ThemeMode): boolean {
+    return renderedThemes.get(container) !== mode || !container.querySelector("svg");
+}
+
+/**
+ * Render all mermaid diagrams on the page.
+ *
+ * @param forceAll - When `true` (e.g., theme change), re-renders every diagram immediately.
+ *   When `false` (default), uses an IntersectionObserver to lazily render diagrams
+ *   as they scroll within {@link PRERENDER_MARGIN} of the viewport.
+ */
+export async function renderAllDiagrams(forceAll = false): Promise<void> {
+    captureDiagramSources();
+    const mode = resolveThemeMode();
+    const containers = [...document.querySelectorAll<HTMLElement>(DIAGRAM_SELECTOR)];
+    if (!containers.length) return;
+
+    if (forceAll) {
+        for (const [index, container] of containers.entries()) {
+            if (needsRender(container, mode)) {
+                await renderDiagram(container, mode, index);
+            }
+        }
+        return;
+    }
+
+    const observer = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                const container = entry.target as HTMLElement;
+                const currentMode = resolveThemeMode();
+                if (!needsRender(container, currentMode)) continue;
+                observer.unobserve(container);
+                void renderDiagram(container, currentMode, containers.indexOf(container));
+            }
+        },
+        { rootMargin: PRERENDER_MARGIN },
+    );
+
+    for (const container of containers) {
+        if (needsRender(container, mode)) {
+            observer.observe(container);
+        }
+    }
+}