refactor(backend/publisher): transformer pipeline + shared registry + shiki highlighting

- Split html-renderer post-processing into per-feature transformers (accordion, bibliography,
citation, footnote, highlight-code, html-embed, mermaid) with a shared types contract
- Extract embed iframe srcdoc builder, shiki config and theme resolver into backend/src/shared
so the frontend can reuse the exact same palette and embed chrome
- Keep the renderer entrypoint (index.ts) as an orchestrator and trim the legacy logic to the
new querySelector-based scope selection (simpler + covered by updated snapshot)
- Update publisher/css-resolution/security suites + snapshot to the new output

Made-with: Cursor

backend/src/publisher/extensions.ts

@@ -10,16 +10,13 @@
 import { Node, mergeAttributes, type Extensions } from "@tiptap/core";
 import { SHARED_COMPONENT_DEFS, type SharedComponentDef } from "../shared/component-defs.js";
 import StarterKit from "@tiptap/starter-kit";
-import CodeBlockLowlight from "@tiptap/extension-code-block-lowlight";
+import { CodeBlock } from "@tiptap/extension-code-block";
 import Mathematics from "@tiptap/extension-mathematics";
 import { Image } from "@tiptap/extension-image";
 import { Table } from "@tiptap/extension-table";
 import { TableRow } from "@tiptap/extension-table-row";
 import { TableCell } from "@tiptap/extension-table-cell";
 import { TableHeader } from "@tiptap/extension-table-header";
-import { common, createLowlight } from "lowlight";
-
-const lowlight = createLowlight(common);
 
 // ---- Custom inline nodes (server versions, no NodeView) ----
 
@@ -90,15 +87,22 @@ const GlossaryServer = Node.create({
     return [{ tag: 'span[data-type="glossary"]' }];
   },
   renderHTML({ HTMLAttributes, node }) {
+    const term = (node.attrs.term as string) || "";
+    const definition = (node.attrs.definition as string) || "";
     return [
       "span",
       mergeAttributes(HTMLAttributes, {
         "data-type": "glossary",
         class: "glossary-node",
-        title: node.attrs.definition,
         tabindex: "0",
       }),
-      node.attrs.term || "",
+      term,
+      [
+        "span",
+        { class: "pub-tooltip pub-tooltip--glossary", "aria-hidden": "true" },
+        ["span", { class: "pub-tooltip__title" }, term],
+        ["span", { class: "pub-tooltip__body" }, definition],
+      ],
     ];
   },
 });
@@ -233,7 +237,7 @@ export function getServerExtensions(): Extensions {
       undoRedo: false,
       link: { openOnClick: false },
     } as any),
-    CodeBlockLowlight.configure({ lowlight }),
+    CodeBlock,
     Mathematics.configure({ katexOptions: { throwOnError: false } }),
     Image.configure({ allowBase64: true }),
     Table.configure({ resizable: false }),

backend/src/publisher/html-renderer.ts

@@ -9,6 +9,8 @@ import { generateHTML } from "@tiptap/html";
 import { parseHTML } from "linkedom";
 import { getServerExtensions } from "./extensions.js";
 import type { PublishCSS } from "./index.js";
+import { oklchFromHue } from "../shared/theme.js";
+import { transformers, buildEmbedSrcdoc, type TransformContext } from "./transformers/index.js";
 
 export interface PublishAuthor {
   name: string;
@@ -33,6 +35,10 @@ export interface PublishMeta {
   licence?: string;
   ogImage?: string;
   pdfUrl?: string;
+  banner?: string;
+  tableOfContentsAutoCollapse?: boolean;
+  /** OKLCH hue (0-360) chosen via the editor HueSlider, synced from Y.Doc settings. */
+  primaryHue?: number;
 }
 
 export interface CitationData {
@@ -44,13 +50,14 @@ export interface CitationData {
 /**
  * Render TipTap JSON document into a complete, self-contained HTML page.
  */
-export function renderArticleHTML(
+export async function renderArticleHTML(
   json: Record<string, unknown>,
   meta: PublishMeta,
   css: PublishCSS,
   citationData?: CitationData,
-  serverBiblioHtml?: string
-): string {
+  serverBiblioHtml?: string,
+  embeds?: Record<string, string>
+): Promise<string> {
   const extensions = getServerExtensions();
 
   // Extract bibliography HTML before generateHTML escapes it as an attribute
@@ -59,14 +66,14 @@ export function renderArticleHTML(
   const biblioHtml = serverBiblioHtml || clientBiblioHtml;
 
   const bodyHtml = generateHTML(json as any, extensions);
-  const enrichedBody = postProcess(bodyHtml, biblioHtml, citationData);
+  const enrichedBody = await postProcess(bodyHtml, biblioHtml, citationData, embeds);
 
   const authorNames = meta.authors.map((a) => a.name);
   const authorsStr = authorNames.join(", ");
   const safeTitle = escapeHtml(meta.title);
   const safeDesc = escapeHtml(meta.description);
 
-  return `<!DOCTYPE html>
+  let result = `<!DOCTYPE html>
 <html lang="en" data-theme="dark">
 <head>
   <meta charset="UTF-8">
@@ -91,18 +98,41 @@ export function renderArticleHTML(
 
   <!-- KaTeX CSS -->
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
-        integrity="sha384-zh0CIslj3dQfMxK3pZnPJAb3bprHitCE2vBz9TyOTICAn3fso5GYa90qPNMBclov"
+        integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib"
         crossorigin="anonymous">
 
-  <!-- highlight.js for code syntax highlighting -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github-dark.min.css">
-  <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/highlight.min.js"></script>
-  <script>hljs.highlightAll();</script>
+  <!-- Code blocks are pre-highlighted at publish time with Shiki (dual-theme
+       via --shiki-dark CSS vars). Zero runtime JS, zero CDN dependency. -->
 
-  <!-- Mermaid (renders <pre class="mermaid"> blocks) -->
+  <!-- Mermaid (renders <pre class="mermaid"> blocks, auto-theme dark/light) -->
   <script type="module">
     import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
-    mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
+    function getTheme() {
+      return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'neutral';
+    }
+    mermaid.initialize({ startOnLoad: false, theme: getTheme() });
+
+    document.querySelectorAll('pre.mermaid').forEach(function(el) {
+      el.setAttribute('data-mermaid-src', el.textContent || '');
+    });
+    await mermaid.run();
+
+    new MutationObserver(function(ms) {
+      for (var i = 0; i < ms.length; i++) {
+        if (ms[i].attributeName === 'data-theme') {
+          mermaid.initialize({ startOnLoad: false, theme: getTheme() });
+          document.querySelectorAll('pre.mermaid').forEach(function(el) {
+            var src = el.getAttribute('data-mermaid-src');
+            if (src) {
+              el.removeAttribute('data-processed');
+              el.textContent = src;
+            }
+          });
+          mermaid.run();
+          break;
+        }
+      }
+    }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
   </script>
 
   <style>
@@ -115,7 +145,7 @@ ${css.components}
 ${css.article}
 ${css.print}
 ${css.publisher}
-
+${renderPrimaryColorOverride(meta.primaryHue)}
   </style>
 </head>
 <body>
@@ -140,11 +170,21 @@ ${css.publisher}
   <aside class="toc-mobile-sidebar" aria-label="Table of Contents">
     <div class="toc-mobile-sidebar__header">
       <span class="toc-mobile-sidebar__title">Table of Contents</span>
-      <button class="toc-mobile-sidebar__close" aria-label="Close">
+      <div class="toc-mobile-sidebar__actions">
+        <button class="toc-mobile-sidebar__theme" aria-label="Toggle color theme">
+          <svg class="icon light" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="4"/><line x1="12" y1="20" x2="12" y2="23"/><line x1="1" y1="12" x2="4" y2="12"/><line x1="20" y1="12" x2="23" y2="12"/><line x1="4.22" y1="4.22" x2="6.34" y2="6.34"/><line x1="17.66" y1="17.66" x2="19.78" y2="19.78"/><line x1="4.22" y1="19.78" x2="6.34" y2="17.66"/><line x1="17.66" y1="6.34" x2="19.78" y2="4.22"/>
+          </svg>
+          <svg class="icon dark" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+          </svg>
+        </button>
+        <button class="toc-mobile-sidebar__close" aria-label="Close table of contents">
         <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
         </svg>
       </button>
+      </div>
     </div>
     <div class="toc-mobile-sidebar__body" id="toc-mobile-placeholder"></div>
   </aside>
@@ -152,6 +192,7 @@ ${css.publisher}
   <!-- Hero -->
   <section class="hero">
     <h1 class="hero-title">${safeTitle}</h1>
+    ${meta.banner && embeds?.[meta.banner] ? `<div class="hero-banner"><iframe srcdoc="" sandbox="allow-scripts allow-same-origin" loading="lazy" style="width:100%;height:100%;border:none;display:block;background:transparent;" data-banner-src="${escapeHtml(meta.banner)}"></iframe></div>` : ""}
     ${meta.subtitle ? `<p class="hero-desc">${escapeHtml(meta.subtitle)}</p>` : ""}
   </section>
 
@@ -159,7 +200,7 @@ ${css.publisher}
   ${renderMetaBar(meta)}
 
   <section class="content-grid">
-    <nav class="table-of-contents" aria-label="Table of Contents">
+    <nav class="table-of-contents" aria-label="Table of Contents" data-auto-collapse="${meta.tableOfContentsAutoCollapse ? "1" : "0"}">
       <div class="title">Table of Contents</div>
       <div id="toc-placeholder"></div>
     </nav>
@@ -257,6 +298,9 @@ ${css.publisher}
     });
 
     // Build nested nav with data-heading-idx
+    // Each nested <ul> is wrapped in <div class="toc-children"> so we can
+    // animate expand/collapse via the grid-template-rows 0fr/1fr trick
+    // (CSS cannot interpolate height:auto).
     var nav = document.createElement('nav');
     var ulStack = [document.createElement('ul')];
     nav.appendChild(ulStack[0]);
@@ -264,7 +308,16 @@ ${css.publisher}
     var prev = 2, hIdx = 0;
     headingsArr.forEach(function(h) {
       var lvl = levelOf(h.tagName);
-      while (lvl > prev) { var ul = document.createElement('ul'); var last = ulStack[ulStack.length-1].lastElementChild; if (last) last.appendChild(ul); ulStack.push(ul); prev++; }
+      while (lvl > prev) {
+        var wrap = document.createElement('div');
+        wrap.className = 'toc-children';
+        var ul = document.createElement('ul');
+        wrap.appendChild(ul);
+        var last = ulStack[ulStack.length-1].lastElementChild;
+        if (last) last.appendChild(wrap);
+        ulStack.push(ul);
+        prev++;
+      }
       while (lvl < prev) { ulStack.pop(); prev--; }
       var li = document.createElement('li');
       var a = document.createElement('a');
@@ -304,11 +357,13 @@ ${css.publisher}
 
     // ---- Auto-collapse logic ----
     var isMobile = window.matchMedia('(max-width: 1100px)');
+    var tocNav = document.querySelector('.table-of-contents');
+    var autoCollapseEnabled = tocNav && tocNav.getAttribute('data-auto-collapse') === '1';
 
     function getItemsWithChildren(navEl) {
       if (!navEl) return [];
       return Array.from(navEl.querySelectorAll('li[data-heading-idx]')).filter(function(li) {
-        return li.querySelector(':scope > ul');
+        return li.querySelector(':scope > .toc-children');
       });
     }
 
@@ -317,7 +372,9 @@ ${css.publisher}
       var activeLi = null;
       function find(li) {
         if (Number(li.getAttribute('data-heading-idx')) === targetIdx) return li;
-        var ul = li.querySelector(':scope > ul');
+        var wrap = li.querySelector(':scope > .toc-children');
+        if (!wrap) return null;
+        var ul = wrap.querySelector(':scope > ul');
         if (!ul) return null;
         var children = ul.querySelectorAll(':scope > li[data-heading-idx]');
         for (var i = 0; i < children.length; i++) { var f = find(children[i]); if (f) return f; }
@@ -335,27 +392,21 @@ ${css.publisher}
       return toExpand;
     }
 
+    // Just toggle the .collapsed class on the li. The CSS rule
+    // .toc-collapsible li.collapsed > .toc-children { grid-template-rows: 0fr }
+    // drives the actual animation (no JS height math).
     function applyCollapseState(navEl, activeIdx) {
       if (!navEl) return;
       var items = getItemsWithChildren(navEl);
       var ancestors = getAncestorIndices(items, activeIdx);
 
       items.forEach(function(li) {
-        var sub = li.querySelector(':scope > ul');
-        if (!sub) return;
         var idx = Number(li.getAttribute('data-heading-idx'));
         var allDesc = li.querySelectorAll('li[data-heading-idx]');
         var related = [idx];
         allDesc.forEach(function(d) { related.push(Number(d.getAttribute('data-heading-idx'))); });
         var shouldExpand = related.some(function(i) { return ancestors[i]; });
-
-        if (shouldExpand) {
-          li.classList.remove('collapsed');
-          sub.style.height = 'auto';
-        } else {
-          li.classList.add('collapsed');
-          sub.style.height = '0px';
-        }
+        li.classList.toggle('collapsed', !shouldExpand);
       });
     }
 
@@ -363,13 +414,16 @@ ${css.publisher}
       if (!navEl) return;
       getItemsWithChildren(navEl).forEach(function(li) {
         li.classList.remove('collapsed');
-        var sub = li.querySelector(':scope > ul');
-        if (sub) sub.style.height = 'auto';
       });
     }
 
-    // Initial state: collapse all except first section
+    // Initial state: collapse only if auto-collapse is enabled.
+    // We suppress transitions for the first paint so the user doesn't see
+    // a close-animation at page load when auto-collapse is on.
     function initCollapse() {
+      if (!autoCollapseEnabled) return;
+      if (nav) nav.classList.add('toc-no-transition');
+      if (navClone) navClone.classList.add('toc-no-transition');
       if (isMobile.matches) {
         expandAll(holder ? holder.querySelector('nav') : null);
         expandAll(holderMobile ? holderMobile.querySelector('nav') : null);
@@ -377,10 +431,17 @@ ${css.publisher}
         applyCollapseState(holder ? holder.querySelector('nav') : null, 0);
         applyCollapseState(holderMobile ? holderMobile.querySelector('nav') : null, 0);
       }
+      requestAnimationFrame(function(){
+        requestAnimationFrame(function(){
+          if (nav) nav.classList.remove('toc-no-transition');
+          if (navClone) navClone.classList.remove('toc-no-transition');
+        });
+      });
     }
     initCollapse();
 
     isMobile.addEventListener('change', function() {
+      if (!autoCollapseEnabled) return;
       if (isMobile.matches) {
         expandAll(holder ? holder.querySelector('nav') : null);
         expandAll(holderMobile ? holderMobile.querySelector('nav') : null);
@@ -390,33 +451,70 @@ ${css.publisher}
       }
     });
 
-    // ---- Scroll tracking ----
-    var OFFSET = 60, lastScrollTime = 0, prevActiveIdx = 0;
+    // ---- Scroll tracking (IntersectionObserver-driven) ----
+    // Semantics: active heading = the last one whose top has crossed the
+    // OFFSET line ("section I'm currently reading"). This matches typical
+    // documentation UX (MDN, Docusaurus, etc.) and is intentionally different
+    // from the editor-side TOC which picks the topmost visible heading in its
+    // scroll container (better suited to non-linear editing navigation).
+    //
+    // We use IntersectionObserver only as a trigger: it fires precisely when
+    // a heading crosses the OFFSET boundary, which are the only moments the
+    // active heading can change. No per-frame scroll handler, no throttling.
+    var OFFSET = 60, prevActiveIdx = -1, prevActiveId = null, rafPending = false;
+
+    function findActiveHeading() {
+      for (var i = headingsArr.length - 1; i >= 0; i--) {
+        var h = headingsArr[i];
+        // Skip headings removed from DOM or moved outside article (e.g. footnotes moved to footer)
+        if (!h.isConnected || !articleRoot.contains(h)) continue;
+        if (h.getBoundingClientRect().top - OFFSET <= 0) {
+          return { idx: i, id: h.id };
+        }
+      }
+      return { idx: -1, id: null };
+    }
 
-    function onScroll() {
-      var now = performance.now();
-      if (now - lastScrollTime < 50) return;
-      lastScrollTime = now;
+    function updateActive() {
+      if (rafPending) return;
+      rafPending = true;
       requestAnimationFrame(function() {
-        var activeIdx = -1, activeId = null;
-        for (var i = headingsArr.length - 1; i >= 0; i--) {
-          if (headingsArr[i].getBoundingClientRect().top - OFFSET <= 0) {
-            activeIdx = i; activeId = headingsArr[i].id; break;
+        rafPending = false;
+        var result = findActiveHeading();
+        var activeIdx = result.idx, activeId = result.id;
+        if (activeId === prevActiveId && activeIdx === prevActiveIdx) return;
+        allLinks.forEach(function(l) { l.classList.remove('active'); });
+        if (activeId) {
+          var href = '#' + activeId;
+          allLinks.forEach(function(l) {
+            if (l.getAttribute('href') === href) l.classList.add('active');
+          });
+        }
+        if (activeIdx >= 0 && activeIdx !== prevActiveIdx) {
+          if (autoCollapseEnabled && !isMobile.matches) {
+            applyCollapseState(holder ? holder.querySelector('nav') : null, activeIdx);
           }
         }
-        allLinks.forEach(function(l) {
-          if (activeId && l.getAttribute('href') === '#'+activeId) l.classList.add('active');
-          else l.classList.remove('active');
-        });
-        if (activeIdx !== prevActiveIdx && activeIdx >= 0 && !isMobile.matches) {
           prevActiveIdx = activeIdx;
-          applyCollapseState(holder ? holder.querySelector('nav') : null, activeIdx);
-        }
-        if (activeIdx >= 0) prevActiveIdx = activeIdx;
+        prevActiveId = activeId;
       });
     }
-    window.addEventListener('scroll', onScroll, { passive: true });
-    onScroll();
+
+    if (typeof IntersectionObserver !== 'undefined') {
+      var spyObserver = new IntersectionObserver(updateActive, {
+        rootMargin: '-' + OFFSET + 'px 0px 0px 0px',
+        threshold: 0,
+      });
+      headingsArr.forEach(function(h) {
+        if (articleRoot.contains(h)) spyObserver.observe(h);
+      });
+      // rootMargin changes on resize (viewport height affects the bottom edge
+      // of the root), but the top offset is fixed, so no need to recreate.
+    } else {
+      // Fallback for browsers without IntersectionObserver (very old).
+      window.addEventListener('scroll', updateActive, { passive: true });
+    }
+    updateActive();
 
     // ---- Mobile sidebar ----
     var sidebar = document.querySelector('.toc-mobile-sidebar');
@@ -447,6 +545,16 @@ ${css.publisher}
     if (holderMobile) holderMobile.addEventListener('click', function(e) { if (e.target.closest && e.target.closest('a')) closeSidebar(); });
     document.addEventListener('keydown', function(e) { if (e.key==='Escape' && sidebar.classList.contains('open')) closeSidebar(); });
 
+    // Sidebar theme toggle
+    var sidebarThemeBtn = document.querySelector('.toc-mobile-sidebar__theme');
+    if (sidebarThemeBtn) {
+      sidebarThemeBtn.addEventListener('click', function() {
+        var next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+        localStorage.setItem('theme', next);
+        applyTheme(next);
+      });
+    }
+
     // ---- Footer: move references & footnotes ----
     (function() {
       var footer = document.querySelector('footer.footer');
@@ -508,6 +616,41 @@ ${css.publisher}
       setTimeout(run, 300);
     })();
 
+    // Sync theme with embed iframes (body embeds + hero banner)
+    function syncEmbedThemes() {
+      var theme = document.documentElement.dataset.theme || 'dark';
+      document.querySelectorAll('.html-embed-container iframe, .hero-banner iframe').forEach(function(iframe) {
+        try { iframe.contentWindow.postMessage({ type: 'setTheme', theme: theme }, '*'); } catch(e) {}
+      });
+    }
+    var obs = new MutationObserver(function(ms) {
+      for (var i = 0; i < ms.length; i++) {
+        if (ms[i].attributeName === 'data-theme') { syncEmbedThemes(); break; }
+      }
+    });
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+
+    // Auto-size embed iframes from postMessage height reports.
+    // Dedupe: only apply when the new height differs from the last applied
+    // (prevents style thrash during tight ResizeObserver bursts).
+    var _lastEmbedHeight = new WeakMap();
+    window.addEventListener('message', function(e) {
+      if (!e.data || e.data.type !== 'embedResize') return;
+      var h = Math.max(0, Math.ceil(e.data.height));
+      if (!h) return;
+      document.querySelectorAll('.html-embed-container iframe').forEach(function(iframe) {
+        try {
+          if (iframe.contentWindow !== e.source) return;
+          if (_lastEmbedHeight.get(iframe) === h) return;
+          _lastEmbedHeight.set(iframe, h);
+          iframe.style.height = h + 'px';
+        } catch(ex) {}
+      });
+    });
+
+    // Initial theme sync after iframes load
+    window.addEventListener('load', function() { setTimeout(syncEmbedThemes, 200); });
+
     // Hash navigation
     if (window.location.hash) {
       var target = document.querySelector(window.location.hash);
@@ -522,6 +665,34 @@ ${css.publisher}
   </script>
 </body>
 </html>`;
+
+  // Fill banner iframe srcdoc if present
+  if (meta.banner && embeds?.[meta.banner]) {
+    const bannerSrcdoc = buildEmbedSrcdoc(embeds[meta.banner]);
+    const { document: d } = parseHTML(result);
+    const bannerIframe = d.querySelector('iframe[data-banner-src]');
+    if (bannerIframe) {
+      bannerIframe.setAttribute("srcdoc", bannerSrcdoc);
+      result = "<!DOCTYPE html>" + d.documentElement.outerHTML;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Emit a `:root` CSS override pinning `--primary-color` / `--primary-color-hover`
+ * to the hue chosen via the editor HueSlider. Placed after the base `_variables.css`
+ * so it always wins on specificity order.
+ *
+ * Returns an empty string if no hue was configured, leaving the template default.
+ */
+function renderPrimaryColorOverride(primaryHue?: number): string {
+  if (typeof primaryHue !== "number" || Number.isNaN(primaryHue)) return "";
+  // Only override --primary-base: _variables.css already derives --primary-color
+  // and --primary-color-hover from it via CSS relative-color syntax, so the
+  // cascade handles the rest.
+  return `:root { --primary-base: ${oklchFromHue(primaryHue)}; }`;
 }
 
 /**
@@ -532,17 +703,17 @@ ${css.publisher}
 function extractBibliographyHtml(json: Record<string, unknown>): string {
   function walk(nodes: any[]): string {
     for (const node of nodes) {
-      if (node.type === "bibliography") {
-        const html = node.attrs?.renderedHtml || "";
-        if (node.attrs) node.attrs.renderedHtml = "";
-        return html;
-      }
+    if (node.type === "bibliography") {
+      const html = node.attrs?.renderedHtml || "";
+      if (node.attrs) node.attrs.renderedHtml = "";
+      return html;
+    }
       if (Array.isArray(node.content)) {
         const found = walk(node.content);
         if (found) return found;
       }
-    }
-    return "";
+  }
+  return "";
   }
   const content = (json as any)?.content;
   if (!Array.isArray(content)) return "";
@@ -550,129 +721,36 @@ function extractBibliographyHtml(json: Record<string, unknown>): string {
 }
 
 /**
- * Post-process the raw generateHTML output using linkedom DOM manipulation:
- * - Transform accordion divs into <details><summary>
- * - Convert inline citation spans into anchor links
- * - Inject bibliography HTML with entry anchors
- * - Transform mermaid divs into <pre class="mermaid">
- * - Transform htmlEmbed divs into iframes
- * - Collect footnotes and append a footnotes section
+ * Post-process the raw `generateHTML` output by running the transformer
+ * registry over a parsed DOM. Each transformer is a small module living in
+ * `transformers/` and is responsible for one component type.
+ *
+ * @see ./transformers/index.ts for the ordered list and why order matters.
  */
-function postProcess(html: string, biblioHtml: string, citationData?: CitationData): string {
+/** @internal - exported for testing */
+export async function postProcess(
+  html: string,
+  biblioHtml: string,
+  citationData?: CitationData,
+  embeds?: Record<string, string>
+): Promise<string> {
   const { document } = parseHTML(`<!DOCTYPE html><html><body>${html}</body></html>`);
 
-  // 1. Accordion: div[data-component="accordion"] -> <details><summary>
-  for (const div of [...document.querySelectorAll('div[data-component="accordion"]')]) {
-    const title = div.getAttribute("title") || "Details";
-    const isOpen = div.getAttribute("open") === "true";
-
-    const details = document.createElement("details");
-    details.setAttribute("data-component", "accordion");
-    if (isOpen) details.setAttribute("open", "");
+  const ctx: TransformContext = {
+    biblioHtml,
+    citationData,
+    embeds,
+    footnoteTexts: [],
+  };
 
-    const summary = document.createElement("summary");
-    summary.textContent = title;
-    details.appendChild(summary);
-
-    const content = document.createElement("div");
-    content.className = "accordion-content";
-    while (div.firstChild) content.appendChild(div.firstChild);
-    details.appendChild(content);
-
-    div.replaceWith(details);
-  }
-
-  // 2. Inline citations: span[data-type="citation"] -> <a> links
-  const NUMERIC_STYLES = new Set(["ieee", "vancouver"]);
-  const isNumeric = citationData ? NUMERIC_STYLES.has(citationData.style) : false;
-  const citationKeyOrder: string[] = [];
-
-  for (const span of [...document.querySelectorAll('span[data-type="citation"]')]) {
-    const key = span.getAttribute("key") || span.getAttribute("data-key");
-    if (!key) continue;
-
-    if (!citationKeyOrder.includes(key)) citationKeyOrder.push(key);
-    const idx = citationKeyOrder.indexOf(key) + 1;
-
-    const originalLabel = span.textContent || `[${key}]`;
-    const displayLabel = isNumeric ? `[${idx}]` : originalLabel;
-
-    const a = document.createElement("a");
-    a.setAttribute("href", `#ref-${key}`);
-    a.className = "citation-inline";
-    a.setAttribute("id", `cite-${key}-${idx}`);
-    a.setAttribute("title", key);
-    a.textContent = displayLabel;
-
-    span.replaceWith(a);
-  }
-
-  // 3. Bibliography: inject pre-formatted HTML into the placeholder
-  for (const div of [...document.querySelectorAll('div[data-type="bibliography"]')]) {
-    div.removeAttribute("renderedhtml");
-
-    if (biblioHtml) {
-      let enrichedBiblio = biblioHtml;
-      if (citationData && citationData.orderedKeys.length > 0) {
-        enrichedBiblio = addBibliographyAnchors(biblioHtml, citationData.orderedKeys);
-      }
-      div.innerHTML = `<h2 class="bibliography-title">References</h2><div class="bibliography-content">${enrichedBiblio}</div>`;
-    } else {
-      div.innerHTML = `<p class="bibliography-empty">No citations</p>`;
-    }
-  }
-
-  // 4. Mermaid: div[data-component="mermaid"] -> <pre class="mermaid">
-  for (const div of [...document.querySelectorAll('div[data-component="mermaid"]')]) {
-    const code = div.getAttribute("code") || div.getAttribute("data-code") || "";
-    const pre = document.createElement("pre");
-    pre.className = "mermaid";
-    pre.textContent = code;
-    div.replaceWith(pre);
-  }
-
-  // 5. HtmlEmbed: div[data-component="htmlEmbed"] -> iframe with srcdoc
-  for (const div of [...document.querySelectorAll('div[data-component="htmlEmbed"]')]) {
-    const src = div.getAttribute("src") || div.getAttribute("data-src") || "";
-
-    const container = document.createElement("div");
-    container.className = "html-embed-container";
-
-    const iframe = document.createElement("iframe");
-    iframe.setAttribute("srcdoc", "");
-    iframe.setAttribute("data-embed-src", src);
-    iframe.setAttribute("style", "width:100%;border:none;min-height:400px;");
-    iframe.setAttribute("loading", "lazy");
-    iframe.setAttribute("sandbox", "allow-scripts");
-    container.appendChild(iframe);
-
-    div.replaceWith(container);
-  }
-
-  // 6. Footnotes: collect span[data-type="footnote"], replace with superscript links
-  const footnoteSpans = [...document.querySelectorAll('span[data-type="footnote"]')];
-  const footnoteTexts: string[] = [];
-
-  for (const span of footnoteSpans) {
-    const text = span.getAttribute("content") || span.getAttribute("data-content") || span.getAttribute("title") || "";
-    footnoteTexts.push(text);
-    const idx = footnoteTexts.length;
-
-    const sup = document.createElement("sup");
-    sup.className = "footnote-ref";
-    const a = document.createElement("a");
-    a.setAttribute("href", `#fn-${idx}`);
-    a.setAttribute("id", `fnref-${idx}`);
-    a.textContent = `[${idx}]`;
-    sup.appendChild(a);
-
-    span.replaceWith(sup);
+  for (const transformer of transformers) {
+    await transformer.apply(document as unknown as Document, ctx);
   }
 
   let result = document.body.innerHTML;
 
-  if (footnoteTexts.length > 0) {
-    const items = footnoteTexts
+  if (ctx.footnoteTexts.length > 0) {
+    const items = ctx.footnoteTexts
       .map((text, i) => `<li id="fn-${i + 1}"><p>${escapeHtml(text)} <a href="#fnref-${i + 1}" class="footnote-backref" aria-label="Back to text">\u21A9</a></p></li>`)
       .join("\n");
     result += `<section class="footnotes"><h2>Footnotes</h2><ol>${items}</ol></section>`;
@@ -681,21 +759,6 @@ function postProcess(html: string, biblioHtml: string, citationData?: CitationDa
   return result;
 }
 
-/**
- * Add id anchors to bibliography entries so inline citations can link to them.
- * citation-js outputs entries as <div class="csl-entry"> elements.
- * Uses linkedom for reliable DOM manipulation.
- */
-function addBibliographyAnchors(html: string, orderedKeys: string[]): string {
-  const { document } = parseHTML(`<!DOCTYPE html><html><body>${html}</body></html>`);
-  const entries = document.querySelectorAll(".csl-entry");
-  entries.forEach((entry, idx) => {
-    const key = orderedKeys[idx] || `entry-${idx}`;
-    entry.setAttribute("id", `ref-${key}`);
-  });
-  return document.body.innerHTML;
-}
-
 function escapeHtml(str: string): string {
   return str
     .replace(/&/g, "&amp;")
@@ -706,7 +769,13 @@ function escapeHtml(str: string): string {
 }
 
 function renderMetaBar(meta: PublishMeta): string {
-  const hasContent = meta.authors.length > 0 || meta.date || meta.doi;
+  // DOI intentionally excluded from the hero meta bar: it only appears in the
+  // footer (`.doi-block`), matching the template convention the user expects.
+  const hasContent =
+    meta.authors.length > 0 ||
+    meta.affiliations.length > 0 ||
+    meta.date ||
+    meta.pdfUrl;
   if (!hasContent) return "";
 
   const multipleAff = meta.affiliations.length > 1;
@@ -715,8 +784,8 @@ function renderMetaBar(meta: PublishMeta): string {
   // Authors cell
   if (meta.authors.length > 0) {
     const items = meta.authors.map((a, i) => {
-      const name = a.url
-        ? `<a href="${escapeHtml(a.url)}" class="author-link" target="_blank" rel="noopener">${escapeHtml(a.name)}</a>`
+    const name = a.url
+      ? `<a href="${escapeHtml(a.url)}" class="author-link" target="_blank" rel="noopener">${escapeHtml(a.name)}</a>`
         : escapeHtml(a.name);
       const sup = multipleAff && a.affiliationIndices.length > 0
         ? `<sup>${a.affiliationIndices.join(",")}</sup>`
@@ -752,14 +821,17 @@ function renderMetaBar(meta: PublishMeta): string {
     cells.push(`<div class="meta-container-cell"><h3>Published</h3><p>${escapeHtml(formatDate(meta.date))}</p></div>`);
   }
 
-  // DOI cell
-  if (meta.doi) {
-    cells.push(`<div class="meta-container-cell"><h3>DOI</h3><p><a href="https://doi.org/${escapeHtml(meta.doi)}" class="doi-link" target="_blank" rel="noopener">${escapeHtml(meta.doi)}</a></p></div>`);
-  }
-
-  // PDF download cell
+  // PDF download cell - styled as a primary button (matches research-article-template)
   if (meta.pdfUrl) {
-    cells.push(`<div class="meta-container-cell"><h3>PDF</h3><p><a href="${escapeHtml(meta.pdfUrl)}" class="pdf-link" target="_blank" rel="noopener" download>Download PDF</a></p></div>`);
+    cells.push(
+      `<div class="meta-container-cell meta-container-cell--pdf">` +
+        `<h3>PDF</h3>` +
+        `<p><a href="${escapeHtml(meta.pdfUrl)}" class="button pdf-link" target="_blank" rel="noopener" download aria-label="Download PDF">` +
+          `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>` +
+          `Download PDF` +
+        `</a></p>` +
+      `</div>`
+    );
   }
 
   return `<header class="meta"><div class="meta-container">${cells.join("")}</div></header>`;

backend/src/publisher/index.ts

@@ -8,7 +8,7 @@ import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import * as Y from "yjs";
-import { DATA_DIR as SHARED_DATA_DIR, docPath } from "../utils.js";
+import { getDataDir, docPath, sanitizeName } from "../utils.js";
 import { TiptapTransformer } from "@hocuspocus/transformer";
 import { renderArticleHTML, type PublishMeta, type CitationData } from "./html-renderer.js";
 import { formatBibliographyServer } from "./format-bibliography.js";
@@ -21,7 +21,8 @@ import {
 } from "../hf-storage.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const DATA_DIR = SHARED_DATA_DIR;
+// Resolved at call-time for testability
+function dataDir() { return getDataDir(); }
 
 export interface PublishCSS {
   variables: string;
@@ -39,7 +40,8 @@ export interface PublishCSS {
  * Resolve @custom-media at-rules so the CSS works in browsers.
  * PostCSS handles this in the Vite build, but the publisher reads raw source files.
  */
-function resolveCustomMedia(allCss: string): string {
+/** @internal - exported for testing */
+export function resolveCustomMedia(allCss: string): string {
   const mediaMap = new Map<string, string>();
 
   // Extract @custom-media declarations
@@ -78,6 +80,7 @@ function loadCSS(): PublishCSS {
       const componentFiles = [
         "_code.css", "_button.css", "_table.css", "_tag.css",
         "_card.css", "_form.css", "_mermaid.css", "_hero.css", "_toc.css",
+        "_footer.css", "_embed.css",
       ];
       const componentsCss = componentFiles
         .map((f) => readSafe(join(dir, "components", f)))
@@ -88,7 +91,7 @@ function loadCSS(): PublishCSS {
       const baseRaw = readFileSync(basePath, "utf-8");
       const layoutRaw = readSafe(join(dir, "_layout.css"));
       const printRaw = readSafe(join(dir, "_print.css"));
-      const editorTokensRaw = readSafe(join(dir, "_editor-tokens.css"));
+      const editorTokensRaw = readSafe(join(dir, "tokens.css"));
       const articleRaw = readSafe(join(dir, "article.css"));
       const publisherRaw = readSafe(join(dir, "_publisher.css"));
 
@@ -126,6 +129,37 @@ interface AffiliationObj {
   url?: string;
 }
 
+function buildPublishMeta(
+  frontmatter: Record<string, unknown>,
+  authors: AuthorObj[],
+  affiliations: AffiliationObj[],
+  fallbackTitle: string,
+  settings?: Record<string, unknown>,
+): PublishMeta {
+  const rawHue = settings?.primaryHue;
+  const primaryHue = typeof rawHue === "number" && !Number.isNaN(rawHue) ? rawHue : undefined;
+  return {
+    title: (frontmatter.title as string) || fallbackTitle,
+    subtitle: (frontmatter.subtitle as string) || undefined,
+    description: (frontmatter.description as string) || "",
+    authors: authors.map((a) => ({
+      name: a.name,
+      url: a.url,
+      affiliationIndices: a.affiliations || [],
+      affiliationNames: (a.affiliations || [])
+        .map((idx) => affiliations[idx - 1]?.name)
+        .filter(Boolean) as string[],
+    })),
+    affiliations: affiliations.map((a) => ({ name: a.name, url: a.url })),
+    date: (frontmatter.published as string) || (frontmatter.date as string) || new Date().toISOString(),
+    doi: (frontmatter.doi as string) || undefined,
+    licence: (frontmatter.licence as string) || (frontmatter.license as string) || undefined,
+    banner: (frontmatter.banner as string) || "banner.html",
+    tableOfContentsAutoCollapse: frontmatter.tableOfContentsAutoCollapse === true,
+    primaryHue,
+  };
+}
+
 /**
  * Extract TipTap JSON and frontmatter from a Yjs document.
  * Uses @hocuspocus/transformer to convert the XmlFragment to ProseMirror JSON.
@@ -133,11 +167,14 @@ interface AffiliationObj {
  * Scalar fields live in Y.Map("frontmatter"), while authors/affiliations/links
  * each have their own Y.Array for concurrent-safe editing.
  */
-function extractFromYDoc(ydoc: Y.Doc): {
+/** @internal - exported for testing */
+export function extractFromYDoc(ydoc: Y.Doc): {
   json: Record<string, unknown>;
   frontmatter: Record<string, unknown>;
   authors: AuthorObj[];
   affiliations: AffiliationObj[];
+  embeds: Record<string, string>;
+  settings: Record<string, unknown>;
 } {
   const metaMap = ydoc.getMap("frontmatter");
   const frontmatter: Record<string, unknown> = {};
@@ -145,6 +182,12 @@ function extractFromYDoc(ydoc: Y.Doc): {
     frontmatter[key] = value;
   });
 
+  const settingsMap = ydoc.getMap("settings");
+  const settings: Record<string, unknown> = {};
+  settingsMap.forEach((value, key) => {
+    settings[key] = value;
+  });
+
   const yAuthors = ydoc.getArray<AuthorObj>("frontmatter.authors");
   const yAffiliations = ydoc.getArray<AffiliationObj>("frontmatter.affiliations");
   const authors = yAuthors.toArray();
@@ -177,8 +220,16 @@ function extractFromYDoc(ydoc: Y.Doc): {
   }
   console.log("[publish] Full JSON (truncated):", JSON.stringify(json).slice(0, 2000));
 
+  // Extract embed HTML from Y.Map("embeds")
+  const embedsMap = ydoc.getMap<string>("embeds");
+  const embeds: Record<string, string> = {};
+  embedsMap.forEach((value, key) => {
+    embeds[key] = value;
+  });
+  console.log("[publish] embeds:", Object.keys(embeds).length, "entries:", Object.keys(embeds));
+
   if (json && typeof json === "object" && json.type === "doc") {
-    return { json, frontmatter, authors, affiliations };
+    return { json, frontmatter, authors, affiliations, embeds, settings };
   }
 
   console.warn("[publish] TiptapTransformer returned unexpected format, using fallback");
@@ -187,13 +238,16 @@ function extractFromYDoc(ydoc: Y.Doc): {
     frontmatter,
     authors,
     affiliations,
+    embeds,
+    settings,
   };
 }
 
 /**
  * Extract citation entries and document order from Y.Doc.
  */
-function extractCitationsFromYDoc(ydoc: Y.Doc, json: Record<string, unknown>): CitationData {
+/** @internal - exported for testing */
+export function extractCitationsFromYDoc(ydoc: Y.Doc, json: Record<string, unknown>): CitationData {
   const citationsMap = ydoc.getMap("citations");
   const settingsMap = ydoc.getMap("settings");
 
@@ -236,6 +290,31 @@ export interface PublishResult {
   error?: string;
 }
 
+/**
+ * High-level publish stages emitted to the SSE stream so the UI can show
+ * honest progress labels instead of a silent spinner. The PDF generator
+ * emits additional sub-stages (load, thumbnail, pdf-setup, pdf-toc, rasterize,
+ * pdf-render) on the same callback.
+ */
+export type PublishStage =
+  | "extract"
+  | "bibliography"
+  | "render"
+  | "load"
+  | "thumbnail"
+  | "pdf-setup"
+  | "pdf-toc"
+  | "rasterize"
+  | "pdf-render"
+  | "write"
+  | "upload";
+
+export type PublishStageEmitter = (stage: PublishStage | string, detail?: Record<string, unknown>) => void;
+
+export interface PublishOptions {
+  onStage?: PublishStageEmitter;
+}
+
 /**
  * Render a preview HTML of the document without saving or uploading anything.
  * Useful for testing the publisher pipeline.
@@ -248,26 +327,9 @@ export async function previewDocument(docName: string): Promise<{ html: string }
   const data = readFileSync(p);
   Y.applyUpdate(ydoc, new Uint8Array(data));
 
-  const { json, frontmatter, authors, affiliations } = extractFromYDoc(ydoc);
+  const { json, frontmatter, authors, affiliations, embeds, settings } = extractFromYDoc(ydoc);
   const citationData = extractCitationsFromYDoc(ydoc, json);
-
-  const meta: PublishMeta = {
-    title: (frontmatter.title as string) || docName,
-    subtitle: (frontmatter.subtitle as string) || undefined,
-    description: (frontmatter.description as string) || "",
-    authors: authors.map((a) => ({
-      name: a.name,
-      url: a.url,
-      affiliationIndices: a.affiliations || [],
-      affiliationNames: (a.affiliations || [])
-        .map((idx) => affiliations[idx - 1]?.name)
-        .filter(Boolean) as string[],
-    })),
-    affiliations: affiliations.map((a) => ({ name: a.name, url: a.url })),
-    date: (frontmatter.published as string) || (frontmatter.date as string) || new Date().toISOString(),
-    doi: (frontmatter.doi as string) || undefined,
-    licence: (frontmatter.licence as string) || (frontmatter.license as string) || undefined,
-  };
+  const meta = buildPublishMeta(frontmatter, authors, affiliations, docName, settings);
 
   const css = loadCSS();
 
@@ -280,64 +342,66 @@ export async function previewDocument(docName: string): Promise<{ html: string }
     }
   }
 
-  const html = renderArticleHTML(json, meta, css, citationData, biblioHtml);
+  const html = await renderArticleHTML(json, meta, css, citationData, biblioHtml, embeds);
   return { html };
 }
 
+/**
+ * Compute the base URL Playwright uses when navigating to the published page.
+ * Defaults to the backend's own HTTP listener so the PDF is rendered from
+ * the exact same HTML users see.
+ */
+function getLocalBaseUrl(): string {
+  const port = process.env.PORT || "8080";
+  return process.env.PUBLISH_BASE_URL || `http://127.0.0.1:${port}`;
+}
+
 /**
  * Run the full publish pipeline for a document.
+ * Emits stage events via `opts.onStage` so the route can stream SSE updates.
+ *
+ * Pipeline (in order):
+ *   1. extract TipTap JSON + metadata from the Y.Doc
+ *   2. render the HTML (with local /published/* URLs baked in)
+ *   3. write index.html + meta.json to disk *first* so the URL is live
+ *   4. Playwright goto() that URL -> thumbnail + PDF
+ *   5. on PDF failure, rewrite index.html/meta.json without the broken PDF link
+ *   6. on HF upload, re-render with public URLs and push everything
  */
-export async function publishDocument(docName: string, token?: string): Promise<PublishResult> {
+export async function publishDocument(
+  docName: string,
+  token?: string,
+  opts: PublishOptions = {}
+): Promise<PublishResult> {
+  const onStage = opts.onStage ?? (() => {});
   const p = docPath(docName);
+  const tPublishStart = Date.now();
 
   if (!existsSync(p)) {
     return { htmlUrl: null, pdfUrl: null, thumbUrl: null, success: false, error: "Document not found" };
   }
 
-  // Load Yjs document
+  onStage("extract");
+
   const ydoc = new Y.Doc();
   const data = readFileSync(p);
   Y.applyUpdate(ydoc, new Uint8Array(data));
 
-  // Extract content
-  const { json, frontmatter, authors, affiliations } = extractFromYDoc(ydoc);
-
-  // Extract citation data from Y.Map for server-side bibliography formatting
+  const { json, frontmatter, authors, affiliations, embeds, settings } = extractFromYDoc(ydoc);
   const citationData = extractCitationsFromYDoc(ydoc, json);
+  const baseMeta = buildPublishMeta(frontmatter, authors, affiliations, docName, settings);
 
-  const meta: PublishMeta = {
-    title: (frontmatter.title as string) || docName,
-    subtitle: (frontmatter.subtitle as string) || undefined,
-    description: (frontmatter.description as string) || "",
-    authors: authors.map((a) => ({
-      name: a.name,
-      url: a.url,
-      affiliationIndices: a.affiliations || [],
-      affiliationNames: (a.affiliations || [])
-        .map((idx) => affiliations[idx - 1]?.name)
-        .filter(Boolean) as string[],
-    })),
-    affiliations: affiliations.map((a) => ({ name: a.name, url: a.url })),
-    date: (frontmatter.published as string) || (frontmatter.date as string) || new Date().toISOString(),
-    doi: (frontmatter.doi as string) || undefined,
-    licence: (frontmatter.licence as string) || (frontmatter.license as string) || undefined,
-  };
-
-  // Pre-compute public URLs so og:image and PDF link are embedded in HTML
   const wantPdf = frontmatter.showPdf !== false;
   const useHf = isHfStorageEnabled();
-  if (wantPdf && useHf && isPdfEnabled()) {
-    meta.ogImage = getPublishedAssetUrl(docName, "thumb.jpg");
-    meta.pdfUrl = getPublishedAssetUrl(docName, "article.pdf");
-  }
+  const pdfEnabled = isPdfEnabled();
+  const safeDirName = sanitizeName(docName);
 
   const css = loadCSS();
   console.log("[publish] CSS variables length:", css.variables.length, "article length:", css.article.length);
-  console.log("[publish] Meta:", JSON.stringify(meta));
 
-  // Format bibliography server-side from citation entries
   let biblioHtml = "";
   if (citationData.entries.length > 0) {
+    onStage("bibliography", { entries: citationData.entries.length });
     try {
       biblioHtml = await formatBibliographyServer(citationData.entries, citationData.style);
       console.log("[publish] Bibliography formatted server-side:", citationData.entries.length, "entries");
@@ -346,56 +410,88 @@ export async function publishDocument(docName: string, token?: string): Promise<
     }
   }
 
-  // First pass: generate HTML with og:image + PDF link pre-injected
-  let html = renderArticleHTML(json, meta, css, citationData, biblioHtml);
-  console.log("[publish] Generated HTML length:", html.length);
+  // Meta used for the *local* published copy. `article.pdf`/`thumb.jpg`
+  // don't exist on disk yet, but referencing them here means Playwright
+  // sees the final hrefs when the PDF is rendered (print CSS hides the
+  // Download button anyway, so the broken-href window is harmless).
+  const localMeta: PublishMeta = { ...baseMeta };
+  if (wantPdf && pdfEnabled) {
+    localMeta.ogImage = `/published/${safeDirName}/thumb.jpg`;
+    localMeta.pdfUrl = `/published/${safeDirName}/article.pdf`;
+  }
+  console.log("[publish] Meta:", JSON.stringify(localMeta));
+
+  onStage("render");
+  const tRenderStart = Date.now();
+  let localHtml = await renderArticleHTML(json, localMeta, css, citationData, biblioHtml, embeds);
+  console.log(
+    `[publish] Generated HTML length: ${localHtml.length} (${Date.now() - tRenderStart}ms)`
+  );
+
+  // --- Step 1: write HTML + meta to disk BEFORE Playwright runs ------------
+  onStage("write");
+  const { writeFileSync: fsWrite, mkdirSync: fsMkdir } = await import("fs");
+  const publishDir = join(dataDir(), "published", safeDirName);
+  fsMkdir(publishDir, { recursive: true });
+  fsWrite(join(publishDir, "index.html"), localHtml);
+  fsWrite(join(publishDir, "meta.json"), JSON.stringify(localMeta, null, 2));
+  console.log("[publish] index.html written to", publishDir);
 
-  // Generate PDF + thumbnail from the HTML
+  // --- Step 2: generate PDF + thumbnail from the served URL ---------------
   let pdf: Buffer | null = null;
   let thumbnail: Buffer | null = null;
 
-  if (wantPdf && isPdfEnabled()) {
+  if (wantPdf && pdfEnabled) {
+    const url = `${getLocalBaseUrl()}/published/${safeDirName}/index.html`;
+    const tPdfStart = Date.now();
     try {
-      const assets = await generatePdfAndThumbnail(html);
+      console.log("[publish] Launching Playwright against", url);
+      const assets = await generatePdfAndThumbnail("", { url, onStage });
       pdf = assets.pdf;
       thumbnail = assets.thumbnail;
+      console.log(
+        `[publish] Playwright done in ${Date.now() - tPdfStart}ms - pdf=${pdf ? pdf.byteLength : 0}B thumb=${thumbnail ? thumbnail.byteLength : 0}B`
+      );
     } catch (err) {
       console.error("[publish] PDF generation failed:", err);
-      // Clear URLs from meta if generation failed
-      if (!thumbnail) delete meta.ogImage;
-      if (!pdf) delete meta.pdfUrl;
-      html = renderArticleHTML(json, meta, css, citationData, biblioHtml);
     }
+  } else if (wantPdf && !pdfEnabled) {
+    console.log("[publish] PDF generation skipped (Playwright unavailable or ENABLE_PDF=false)");
   }
 
-  // Always save locally so GET / serves the fresh HTML immediately
-  const { writeFileSync: fsWrite, mkdirSync: fsMkdir } = await import("fs");
-  const safeDirName = docName.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const publishDir = join(DATA_DIR, "published", safeDirName);
-  fsMkdir(publishDir, { recursive: true });
-
-  // Local copy uses relative URLs for PDF/thumbnail
-  const localMeta = { ...meta };
-  if (thumbnail) localMeta.ogImage = `/published/${safeDirName}/thumb.jpg`;
-  else delete localMeta.ogImage;
-  if (pdf) localMeta.pdfUrl = `/published/${safeDirName}/article.pdf`;
-  else delete localMeta.pdfUrl;
-  const localHtml = renderArticleHTML(json, localMeta, css, citationData, biblioHtml);
-
-  fsWrite(join(publishDir, "index.html"), localHtml);
+  // --- Step 3: if PDF/thumbnail succeeded, persist them. If either failed,
+  // strip the references from the meta & rewrite the HTML to avoid broken
+  // Download/og:image links.
   if (pdf) fsWrite(join(publishDir, "article.pdf"), pdf);
   if (thumbnail) fsWrite(join(publishDir, "thumb.jpg"), thumbnail);
-  fsWrite(join(publishDir, "meta.json"), JSON.stringify(localMeta, null, 2));
-  console.log("[publish] local copy written to", publishDir);
 
-  // Also upload to HF dataset for persistence across container restarts
+  const finalLocalMeta = { ...localMeta };
+  if (!thumbnail) delete finalLocalMeta.ogImage;
+  if (!pdf) delete finalLocalMeta.pdfUrl;
+
+  if (wantPdf && pdfEnabled && (!pdf || !thumbnail)) {
+    console.log("[publish] rewriting index.html without missing asset references");
+    localHtml = await renderArticleHTML(json, finalLocalMeta, css, citationData, biblioHtml, embeds);
+    fsWrite(join(publishDir, "index.html"), localHtml);
+  }
+  fsWrite(join(publishDir, "meta.json"), JSON.stringify(finalLocalMeta, null, 2));
+  console.log(
+    `[publish] local copy ready at ${publishDir} (total ${Date.now() - tPublishStart}ms)`
+  );
+
+  // --- Step 4: HF upload (if enabled): rebuild HTML once more with public URLs
   if (useHf) {
+    onStage("upload");
+    const hfMeta: PublishMeta = { ...baseMeta };
+    if (thumbnail) hfMeta.ogImage = getPublishedAssetUrl(docName, "thumb.jpg");
+    if (pdf) hfMeta.pdfUrl = getPublishedAssetUrl(docName, "article.pdf");
+    const hfHtml = await renderArticleHTML(json, hfMeta, css, citationData, biblioHtml, embeds);
     try {
       const urls = await uploadPublishedAssets(docName, {
-        html,
+        html: hfHtml,
         pdf,
         thumbnail,
-        meta: meta as any,
+        meta: hfMeta as any,
       }, token);
       return { ...urls, success: true };
     } catch (err) {

backend/src/publisher/pdf-generator.ts

@@ -1,8 +1,24 @@
 /**
  * PDF and OG thumbnail generation via Playwright.
  *
- * Launches headless Chromium, loads the published HTML,
- * waits for rendering, then captures PDF + screenshot.
+ * Pipeline (aligned with research-article-template's export-pdf.mjs):
+ *
+ *   1. launch headless Chromium
+ *   2. `page.goto(url)` on the real published page (served by the backend)
+ *      - this guarantees the PDF matches exactly what users see, including
+ *        scripts that move footnotes/bibliography into the references block.
+ *      - a `setContent` fallback is kept for the unit tests that don't spin
+ *        up the HTTP server.
+ *   3. Pass A - thumbnail: viewport 1200x630, no print emulation, JPEG screenshot
+ *   4. Pass B - PDF:
+ *      a. emulateMedia({ media: 'print' })  <- activates @media print rules
+ *      b. setViewportSize to the printable width (so layout matches PDF page)
+ *      c. waitForAssets (fonts, images, iframes readyState, rAF x2, stable layout)
+ *      d. injectPdfToc (build a linear .pdf-toc from h2/h3 for the PDF only)
+ *      e. waitForMermaid (ensure all mermaid diagrams finished rendering)
+ *      f. rasterizeMermaid (screenshot pre.mermaid -> <img data-URL>)
+ *      g. rasterizeEmbeds (screenshot iframes -> <img data-URL>)
+ *      h. page.pdf({ format, margin, printBackground: true })
  */
 
 let playwrightAvailable = false;
@@ -10,7 +26,6 @@ let playwrightAvailable = false;
 let chromium: any;
 
 try {
-  // Dynamic import: playwright is optional (only in Docker production image)
   const pw = await import(/* @vite-ignore */ "playwright");
   chromium = pw.chromium;
   playwrightAvailable = true;
@@ -27,16 +42,335 @@ export interface GeneratedAssets {
   thumbnail: Buffer | null;
 }
 
+export type PageFormat = "A4" | "Letter";
+
+export interface PdfMargin {
+  top: string;
+  right: string;
+  bottom: string;
+  left: string;
+}
+
+export interface PdfOptions {
+  format?: PageFormat;
+  margin?: PdfMargin;
+  /**
+   * When set, Playwright navigates to this URL instead of calling
+   * `setContent(html)`. Prefer this - the PDF then matches exactly what the
+   * user sees at that URL (scripts that move footnotes/bibliography into the
+   * footer run naturally under `networkidle`).
+   */
+  url?: string;
+  /** Emitted at each step so the route can stream SSE events. */
+  onStage?: (stage: string, detail?: Record<string, unknown>) => void;
+}
+
+const DEFAULT_MARGIN: PdfMargin = { top: "12mm", right: "16mm", bottom: "16mm", left: "16mm" };
+
+const FORMAT_MM: Record<PageFormat, { w: number; h: number }> = {
+  A4: { w: 210, h: 297 },
+  Letter: { w: 215.9, h: 279.4 },
+};
+
+function cssLengthToMm(len: string): number {
+  const m = len.trim().match(/^([\d.]+)\s*(mm|cm|in|pt|px)?$/i);
+  if (!m) return 0;
+  const n = parseFloat(m[1]);
+  const unit = (m[2] || "mm").toLowerCase();
+  switch (unit) {
+    case "mm": return n;
+    case "cm": return n * 10;
+    case "in": return n * 25.4;
+    case "pt": return (n * 25.4) / 72;
+    case "px": return (n * 25.4) / 96;
+    default: return n;
+  }
+}
+
+function computePrintableWidthPx(format: PageFormat, margin: PdfMargin): number {
+  const fmt = FORMAT_MM[format];
+  const innerMm = fmt.w - cssLengthToMm(margin.left) - cssLengthToMm(margin.right);
+  return Math.max(320, Math.round((innerMm / 25.4) * 96));
+}
+
+/**
+ * Wait for fonts, images, iframes to load, then two rAFs, then a stable layout.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function waitForAssets(page: any, timeoutMs = 10_000): Promise<void> {
+  await page.evaluate(async () => {
+    const d = document as Document & { fonts?: { ready?: Promise<unknown> } };
+    if (d.fonts?.ready) {
+      try { await d.fonts.ready; } catch { /* ignore */ }
+    }
+    const imgs = Array.from(document.images).filter((i) => !i.complete);
+    await Promise.all(
+      imgs.map(
+        (i) =>
+          new Promise<void>((resolve) => {
+            const done = () => resolve();
+            i.addEventListener("load", done, { once: true });
+            i.addEventListener("error", done, { once: true });
+            setTimeout(done, 5_000);
+          })
+      )
+    );
+    const iframes = Array.from(document.querySelectorAll("iframe"));
+    await Promise.all(
+      iframes.map(
+        (f) =>
+          new Promise<void>((resolve) => {
+            const done = () => resolve();
+            try {
+              if (f.contentDocument?.readyState === "complete") {
+                done();
+                return;
+              }
+            } catch { /* cross-origin: fall through */ }
+            f.addEventListener("load", done, { once: true });
+            setTimeout(done, 4_000);
+          })
+      )
+    );
+    await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+  });
+  await waitForStableLayout(page, timeoutMs);
+}
+
+/**
+ * Poll scrollHeight every 100ms; return when stable 3 times in a row,
+ * or when timeoutMs is reached.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function waitForStableLayout(page: any, timeoutMs = 5_000): Promise<void> {
+  const start = Date.now();
+  let last = -1;
+  let stable = 0;
+  while (Date.now() - start < timeoutMs) {
+    const h = (await page.evaluate(() => document.documentElement.scrollHeight)) as number;
+    if (h === last) stable += 1;
+    else stable = 0;
+    last = h;
+    if (stable >= 3) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+}
+
+/**
+ * Build a linear .pdf-toc from h2/h3 inside .tiptap, inserted right after
+ * the meta bar so it appears between cover and body in the PDF.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function injectPdfToc(page: any): Promise<void> {
+  await page.evaluate(() => {
+    if (document.querySelector(".pdf-toc")) return;
+    const headings = Array.from(
+      document.querySelectorAll<HTMLElement>(".tiptap h2, .tiptap h3")
+    ).filter((h) => (h.textContent || "").trim().length > 0);
+    if (headings.length === 0) return;
+
+    const toc = document.createElement("nav");
+    toc.className = "pdf-toc";
+    toc.setAttribute("aria-label", "Table of Contents");
+
+    const title = document.createElement("h2");
+    title.className = "pdf-toc__title";
+    title.textContent = "Table of Contents";
+    toc.appendChild(title);
+
+    const ul = document.createElement("ul");
+    ul.className = "pdf-toc__list";
+    for (const h of headings) {
+      const li = document.createElement("li");
+      li.className = h.tagName === "H3" ? "pdf-toc__item pdf-toc__item--sub" : "pdf-toc__item";
+      const a = document.createElement("a");
+      const id = h.getAttribute("id");
+      if (id) a.setAttribute("href", `#${id}`);
+      a.textContent = (h.textContent || "").trim();
+      li.appendChild(a);
+      ul.appendChild(li);
+    }
+    toc.appendChild(ul);
+
+    const metaBar = document.querySelector(".meta-container, .hero-meta");
+    const hero = document.querySelector(".hero");
+    const anchor = metaBar ?? hero ?? document.querySelector(".content-grid");
+    if (anchor?.parentNode) {
+      anchor.parentNode.insertBefore(toc, anchor.nextSibling);
+    } else {
+      document.body.insertBefore(toc, document.body.firstChild);
+    }
+  });
+}
+
+/**
+ * Wait for every `pre.mermaid` element to finish rendering (mermaid marks
+ * processed nodes with `data-processed="true"` and inserts an <svg>). The
+ * diagram runtime is loaded as an ESM module from a CDN, so it typically
+ * completes *after* Playwright's `networkidle` signal fires.
+ *
+ * Resolves early when no mermaid block is present. Silently returns once the
+ * timeout is hit so the pipeline keeps moving rather than failing the whole
+ * publish on a slow CDN.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function waitForMermaid(page: any, timeoutMs = 10_000): Promise<void> {
+  try {
+    await page.waitForFunction(
+      () => {
+        const nodes = document.querySelectorAll("pre.mermaid");
+        if (nodes.length === 0) return true;
+        return Array.from(nodes).every(
+          (n) =>
+            (n as HTMLElement).getAttribute("data-processed") === "true" ||
+            !!(n as HTMLElement).querySelector("svg"),
+        );
+      },
+      { timeout: timeoutMs },
+    );
+  } catch {
+    console.warn("[pdf] mermaid did not finish rendering before timeout");
+  }
+}
+
+/**
+ * Replace each rendered Mermaid block with a PNG <img> so the PDF engine
+ * doesn't try to paginate the SVG (foreignObject labels get chopped across
+ * page breaks and some gradients / markers render blank in print media).
+ *
+ * Runs AFTER `waitForMermaid` so every `pre.mermaid` has its SVG in place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function rasterizeMermaid(page: any, onStage?: PdfOptions["onStage"]): Promise<void> {
+  const handles = await page.$$("pre.mermaid");
+  const total = handles.length;
+  if (total === 0) return;
+
+  for (let i = 0; i < handles.length; i += 1) {
+    const pre = handles[i];
+    onStage?.("rasterize", { kind: "mermaid", index: i + 1, total });
+
+    try {
+      await pre.scrollIntoViewIfNeeded({ timeout: 1_000 });
+    } catch { /* ignore */ }
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Skip if the node somehow never rendered an SVG - leaves the original
+    // markup in place so debugging stays possible.
+    const hasSvg = await pre.evaluate((el: HTMLElement) => !!el.querySelector("svg"));
+    if (!hasSvg) continue;
+
+    const box = await pre.boundingBox();
+    if (!box || box.width < 10 || box.height < 10) continue;
+
+    let buffer: Buffer;
+    try {
+      buffer = await pre.screenshot({ type: "png", omitBackground: true });
+    } catch (err) {
+      console.warn("[pdf] failed to screenshot mermaid, leaving SVG as-is:", (err as Error).message);
+      continue;
+    }
+
+    const dataUrl = `data:image/png;base64,${buffer.toString("base64")}`;
+    const width = Math.round(box.width);
+    const height = Math.round(box.height);
+
+    await pre.evaluate(
+      (el: HTMLElement, args: { src: string; w: number; h: number }) => {
+        const img = el.ownerDocument!.createElement("img");
+        img.src = args.src;
+        img.setAttribute("width", String(args.w));
+        img.setAttribute("height", String(args.h));
+        img.className = "mermaid-rasterized";
+        img.style.width = "100%";
+        img.style.height = "auto";
+        img.style.display = "block";
+        img.setAttribute("alt", "Mermaid diagram");
+        el.replaceWith(img);
+      },
+      { src: dataUrl, w: width, h: height },
+    );
+  }
+}
+
 /**
- * Generate PDF and OG thumbnail from HTML string.
+ * Replace each embed iframe (charts, hero banner) with a PNG <img> generated
+ * from a Playwright element screenshot. Chromium paginates iframes poorly
+ * (often cut in half or rendered blank across pages), so we flatten them.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function rasterizeEmbeds(page: any, onStage?: PdfOptions["onStage"]): Promise<void> {
+  const handles = await page.$$(
+    ".html-embed-container > iframe, .hero-banner > iframe"
+  );
+  const total = handles.length;
+  if (total === 0) return;
+
+  for (let i = 0; i < handles.length; i += 1) {
+    const iframe = handles[i];
+    onStage?.("rasterize", { kind: "embed", index: i + 1, total });
+
+    try {
+      await iframe.scrollIntoViewIfNeeded({ timeout: 1_000 });
+    } catch { /* ignore */ }
+    await new Promise((r) => setTimeout(r, 150));
+
+    const box = await iframe.boundingBox();
+    if (!box || box.width < 10 || box.height < 10) continue;
+
+    let buffer: Buffer;
+    try {
+      buffer = await iframe.screenshot({ type: "png", omitBackground: true });
+    } catch (err) {
+      console.warn("[pdf] failed to screenshot embed, leaving iframe as-is:", (err as Error).message);
+      continue;
+    }
+
+    const dataUrl = `data:image/png;base64,${buffer.toString("base64")}`;
+    const width = Math.round(box.width);
+    const height = Math.round(box.height);
+
+    await iframe.evaluate(
+      (el: HTMLIFrameElement, args: { src: string; w: number; h: number }) => {
+        const img = el.ownerDocument!.createElement("img");
+        img.src = args.src;
+        img.setAttribute("width", String(args.w));
+        img.setAttribute("height", String(args.h));
+        img.style.width = "100%";
+        img.style.height = "auto";
+        img.style.display = "block";
+        img.setAttribute("alt", el.getAttribute("title") || "Embedded chart");
+        el.replaceWith(img);
+      },
+      { src: dataUrl, w: width, h: height }
+    );
+  }
+}
+
+/**
+ * Generate PDF and OG thumbnail from the same source HTML.
+ *
+ * Two load strategies are supported:
+ *  - `opts.url` (preferred): navigate Playwright to the live published page.
+ *    The PDF then matches exactly what users see, and the JS that moves
+ *    footnotes/bibliography into `.references-block` runs naturally.
+ *  - `html` fallback: `page.setContent(html)` for tests and any call-site
+ *    without an HTTP server to hit.
+ *
+ * The PDF honours @media print; the thumbnail uses the default (screen) media.
  */
 export async function generatePdfAndThumbnail(
-  html: string
+  html: string,
+  opts: PdfOptions = {}
 ): Promise<GeneratedAssets> {
   if (!playwrightAvailable) {
     return { pdf: null, thumbnail: null };
   }
 
+  const format: PageFormat = opts.format ?? "A4";
+  const margin: PdfMargin = opts.margin ?? DEFAULT_MARGIN;
+  const onStage = opts.onStage;
+
   const browser = await chromium.launch({
     args: ["--no-sandbox", "--disable-setuid-sandbox"],
   });
@@ -44,24 +378,67 @@ export async function generatePdfAndThumbnail(
   try {
     const page = await browser.newPage();
 
-    await page.setContent(html, { waitUntil: "networkidle" });
+    // tsx/esbuild wraps named functions with __name(...) helper calls at
+    // transpile time. When we pass an arrow function to page.evaluate, the
+    // transpiled source is serialized to the browser context where __name is
+    // undefined, crashing every evaluate. Install a no-op stub so those calls
+    // pass through unchanged. We pass the script as a raw string so esbuild
+    // doesn't touch it (passing a function would re-introduce the same bug
+    // inside the init script itself).
+    await page.addInitScript({
+      content:
+        "if (typeof window.__name !== 'function') { window.__name = function (fn) { return fn; }; }",
+    });
 
-    // Wait a bit for fonts, KaTeX, images
-    await page.waitForTimeout(2000);
+    onStage?.("load", opts.url ? { url: opts.url } : undefined);
+    if (opts.url) {
+      await page.goto(opts.url, { waitUntil: "networkidle", timeout: 30_000 });
+    } else {
+      await page.setContent(html, { waitUntil: "networkidle" });
+    }
+    // Defensive: guarantee __name exists before the first evaluate, even if
+    // addInitScript didn't fire in time for this document.
+    await page.evaluate(
+      "window.__name = window.__name || function (fn) { return fn; };"
+    );
+    await waitForAssets(page, 8_000);
 
-    // OG Thumbnail (1200x630)
+    onStage?.("thumbnail");
     await page.setViewportSize({ width: 1200, height: 630 });
+    await page.evaluate(() => window.scrollTo(0, 0));
+    await new Promise((r) => setTimeout(r, 200));
     const thumbnail = await page.screenshot({
       type: "jpeg",
       quality: 85,
       clip: { x: 0, y: 0, width: 1200, height: 630 },
     });
 
-    // PDF
+    onStage?.("pdf-setup");
+    await page.emulateMedia({ media: "print" });
+    const printableWidth = computePrintableWidthPx(format, margin);
+    await page.setViewportSize({ width: printableWidth, height: 1400 });
+    await page.evaluate(() => window.scrollTo(0, 0));
+    await waitForAssets(page, 8_000);
+
+    onStage?.("pdf-toc");
+    await injectPdfToc(page);
+
+    // Mermaid diagrams must be fully rendered before we screenshot them.
+    // `networkidle` fires before the ESM module from the CDN finishes running.
+    await waitForMermaid(page, 10_000);
+    await rasterizeMermaid(page, onStage);
+
+    await rasterizeEmbeds(page, onStage);
+
+    await waitForStableLayout(page, 3_000);
+
+    onStage?.("pdf-render");
     const pdf = await page.pdf({
-      format: "A4",
+      format,
       printBackground: true,
-      margin: { top: "1cm", bottom: "1cm", left: "1.5cm", right: "1.5cm" },
+      displayHeaderFooter: false,
+      preferCSSPageSize: false,
+      margin,
     });
 
     return {

backend/src/publisher/transformers/accordion.ts

@@ -0,0 +1,30 @@
+import type { Transformer } from "./types.js";
+
+/**
+ * Transforms `<div data-component="accordion">` authored in the editor into
+ * native `<details><summary>` collapsibles in the published output.
+ */
+export const accordionTransformer: Transformer = {
+  name: "accordion",
+  apply(document) {
+    for (const div of [...document.querySelectorAll('div[data-component="accordion"]')]) {
+      const title = div.getAttribute("title") || "Details";
+      const isOpen = div.getAttribute("open") === "true";
+
+      const details = document.createElement("details");
+      details.setAttribute("data-component", "accordion");
+      if (isOpen) details.setAttribute("open", "");
+
+      const summary = document.createElement("summary");
+      summary.textContent = title;
+      details.appendChild(summary);
+
+      const content = document.createElement("div");
+      content.className = "accordion-content";
+      while (div.firstChild) content.appendChild(div.firstChild);
+      details.appendChild(content);
+
+      div.replaceWith(details);
+    }
+  },
+};

backend/src/publisher/transformers/bibliography.ts

@@ -0,0 +1,41 @@
+import { parseHTML } from "linkedom";
+import type { Transformer } from "./types.js";
+
+/**
+ * Add id anchors to bibliography entries so inline citations can link to them.
+ * citation-js outputs entries as `<div class="csl-entry">` elements; we tag each
+ * with `id="ref-<key>"` in the order specified by `citationData.orderedKeys`.
+ */
+function addBibliographyAnchors(html: string, orderedKeys: string[]): string {
+  const { document } = parseHTML(`<!DOCTYPE html><html><body>${html}</body></html>`);
+  const entries = document.querySelectorAll(".csl-entry");
+  entries.forEach((entry, idx) => {
+    const key = orderedKeys[idx] || `entry-${idx}`;
+    entry.setAttribute("id", `ref-${key}`);
+  });
+  return document.body.innerHTML;
+}
+
+/**
+ * Inject the pre-formatted bibliography HTML into the placeholder
+ * `<div data-type="bibliography">` left by the TipTap extension.
+ * Falls back to an empty-state message when there are no citations.
+ */
+export const bibliographyTransformer: Transformer = {
+  name: "bibliography",
+  apply(document, ctx) {
+    for (const div of [...document.querySelectorAll('div[data-type="bibliography"]')]) {
+      div.removeAttribute("renderedhtml");
+
+      if (ctx.biblioHtml) {
+        let enriched = ctx.biblioHtml;
+        if (ctx.citationData && ctx.citationData.orderedKeys.length > 0) {
+          enriched = addBibliographyAnchors(ctx.biblioHtml, ctx.citationData.orderedKeys);
+        }
+        div.innerHTML = `<h2 class="bibliography-title">References</h2><div class="bibliography-content">${enriched}</div>`;
+      } else {
+        div.innerHTML = `<p class="bibliography-empty">No citations</p>`;
+      }
+    }
+  },
+};

backend/src/publisher/transformers/citation.ts

@@ -0,0 +1,81 @@
+import type { Transformer } from "./types.js";
+
+const NUMERIC_STYLES = new Set(["ieee", "vancouver"]);
+
+/**
+ * Converts inline `<span data-type="citation">` markers produced by TipTap
+ * into anchor links pointing at the bibliography entries.
+ *
+ * - Numeric styles (IEEE, Vancouver) display sequential `[n]` labels.
+ * - Author-date styles keep the original inline label (e.g. "(Smith 2020)").
+ *
+ * Must run before the bibliography transformer so the `#ref-<key>` anchors
+ * line up with the entry ids created there.
+ */
+export const citationTransformer: Transformer = {
+  name: "citation",
+  apply(document, ctx) {
+    const isNumeric = ctx.citationData ? NUMERIC_STYLES.has(ctx.citationData.style) : false;
+    const citationKeyOrder: string[] = [];
+
+    // Index bibliography entries by key so we can enrich each inline citation
+    // with a hover tooltip showing title / journal / DOI.
+    const entriesByKey = new Map<string, any>();
+    for (const entry of ctx.citationData?.entries ?? []) {
+      const entryKey = (entry?.id as string) || (entry?.key as string);
+      if (entryKey) entriesByKey.set(entryKey, entry);
+    }
+
+    for (const span of [...document.querySelectorAll('span[data-type="citation"]')]) {
+      const key = span.getAttribute("key") || span.getAttribute("data-key");
+      if (!key) continue;
+
+      if (!citationKeyOrder.includes(key)) citationKeyOrder.push(key);
+      const idx = citationKeyOrder.indexOf(key) + 1;
+
+      const originalLabel = span.textContent || `[${key}]`;
+      const displayLabel = isNumeric ? `[${idx}]` : originalLabel;
+
+      const a = document.createElement("a");
+      a.setAttribute("href", `#ref-${key}`);
+      a.className = "citation-inline";
+      a.setAttribute("id", `cite-${key}-${idx}`);
+      a.setAttribute("title", key);
+      a.textContent = displayLabel;
+
+      const entry = entriesByKey.get(key);
+      if (entry) {
+        const tooltip = document.createElement("span");
+        tooltip.className = "pub-tooltip pub-tooltip--citation";
+        tooltip.setAttribute("aria-hidden", "true");
+
+        const titleEl = document.createElement("span");
+        titleEl.className = "pub-tooltip__title";
+        titleEl.textContent = (entry.title as string) || key;
+        tooltip.appendChild(titleEl);
+
+        const journalText = (entry["container-title"] as string) || "";
+        if (journalText) {
+          const journal = document.createElement("span");
+          journal.className = "pub-tooltip__journal";
+          const parts: string[] = [journalText];
+          if (entry.volume) parts.push(String(entry.volume));
+          if (entry.page) parts.push(String(entry.page));
+          journal.textContent = parts.join(", ");
+          tooltip.appendChild(journal);
+        }
+
+        if (entry.DOI) {
+          const doi = document.createElement("span");
+          doi.className = "pub-tooltip__doi";
+          doi.textContent = `doi: ${entry.DOI}`;
+          tooltip.appendChild(doi);
+        }
+
+        a.appendChild(tooltip);
+      }
+
+      span.replaceWith(a);
+    }
+  },
+};

backend/src/publisher/transformers/footnote.ts

@@ -0,0 +1,32 @@
+import type { Transformer } from "./types.js";
+
+/**
+ * Replaces every `<span data-type="footnote" content="...">` with a numbered
+ * superscript link. The footnote texts are pushed into `ctx.footnoteTexts` so
+ * the orchestrator can render the `<section class="footnotes">` block once
+ * all transformers have run.
+ */
+export const footnoteTransformer: Transformer = {
+  name: "footnote",
+  apply(document, ctx) {
+    for (const span of [...document.querySelectorAll('span[data-type="footnote"]')]) {
+      const text =
+        span.getAttribute("content") ||
+        span.getAttribute("data-content") ||
+        span.getAttribute("title") ||
+        "";
+      ctx.footnoteTexts.push(text);
+      const idx = ctx.footnoteTexts.length;
+
+      const sup = document.createElement("sup");
+      sup.className = "footnote-ref";
+      const a = document.createElement("a");
+      a.setAttribute("href", `#fn-${idx}`);
+      a.setAttribute("id", `fnref-${idx}`);
+      a.textContent = `[${idx}]`;
+      sup.appendChild(a);
+
+      span.replaceWith(sup);
+    }
+  },
+};

backend/src/publisher/transformers/highlight-code.ts

@@ -0,0 +1,166 @@
+import type { Element as HastElement, ElementContent, Root as HastRoot } from "hast";
+import { getSharedHighlighter, isSupportedLang, normalizeLang, SHIKI_THEMES } from "../../shared/shiki-config.js";
+import type { Transformer } from "./types.js";
+
+/**
+ * Syntax-highlights every `<pre><code class="language-X">` block emitted by
+ * the TipTap `codeBlock` node using the shared Shiki highlighter, and tags
+ * `<pre>` with `data-lang="X"` so the stylesheet can render the language
+ * label via `pre::after { content: attr(data-lang) }`.
+ *
+ * Rationale: TipTap's `generateHTML()` produces plain text inside `<code>`,
+ * because syntax highlighting is a view-only ProseMirror plugin that does not
+ * run server-side. We do the highlighting here instead of shipping the JS to
+ * every reader (no CDN, no FOUC, offline-safe). Using the same Shiki config
+ * as the editor guarantees identical supported languages and identical token
+ * colors in edit vs. published view.
+ *
+ * Line numbers are rendered as `<span class="code-line-num">N</span>` inserted
+ * as the first child of every Shiki-emitted `<span class="line">`. The editor
+ * uses PM widget decorations to inject the exact same markup, so a single
+ * stylesheet rule targets both views. This markup-based approach survives
+ * soft-wrap (the number sits on the first visual row of its source line) and
+ * avoids the pitfalls of CSS counters or PM's overlapping-decoration merging.
+ */
+
+/**
+ * Serialize a hast AST back to HTML. Hand-rolled (3 cases, no dependency
+ * on `hast-util-to-html`) because Shiki already produces a tree that only
+ * contains elements + text nodes with trivial attributes (class, style).
+ */
+function hastToHtml(nodes: readonly ElementContent[]): string {
+  let out = "";
+  for (const n of nodes) {
+    if (n.type === "text") {
+      out += escapeHtmlText(n.value);
+      continue;
+    }
+    if (n.type === "element") {
+      out += `<${n.tagName}`;
+      const props = n.properties || {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value === undefined || value === null || value === false) continue;
+        const attr = propToAttr(key);
+        const str = Array.isArray(value) ? value.join(" ") : String(value);
+        out += ` ${attr}="${escapeAttr(str)}"`;
+      }
+      if (isVoidElement(n.tagName)) {
+        out += " />";
+      } else {
+        out += ">";
+        out += hastToHtml(n.children);
+        out += `</${n.tagName}>`;
+      }
+    }
+  }
+  return out;
+}
+
+function propToAttr(key: string): string {
+  if (key === "className") return "class";
+  if (key === "htmlFor") return "for";
+  return key.toLowerCase();
+}
+
+function escapeHtmlText(s: string): string {
+  return s.replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
+}
+
+function escapeAttr(s: string): string {
+  return s.replace(/[&"]/g, (c) => (c === "&" ? "&amp;" : "&quot;"));
+}
+
+function isVoidElement(tag: string): boolean {
+  return ["br", "hr", "img", "input", "meta", "link"].includes(tag);
+}
+
+/**
+ * Extract language from a `<code>` class list. TipTap writes
+ * `class="language-python"`; anything else falls back to plain-text.
+ */
+function extractLang(code: Element): string {
+  const cls = code.getAttribute("class") || "";
+  const match = cls.match(/language-([\w+-]+)/i);
+  return match ? match[1] : "";
+}
+
+/**
+ * Prepend `<span class="code-line-num">N</span>` to every Shiki `.line`
+ * wrapper. Matches the editor's widget markup exactly so the stylesheet can
+ * target a single selector in both views.
+ */
+function injectLineNumbers(codeChildren: ElementContent[]): void {
+  let n = 0;
+  for (const child of codeChildren) {
+    if (child.type !== "element") continue;
+    // Shiki's HAST stores the class as a plain `class` string (not
+    // `className`), so inspect both just in case the config changes.
+    const props = child.properties ?? {};
+    const classValue = props.class ?? props.className;
+    const classTokens = Array.isArray(classValue)
+      ? classValue.map(String)
+      : typeof classValue === "string"
+        ? classValue.split(/\s+/)
+        : [];
+    if (!classTokens.includes("line")) continue;
+    n += 1;
+    const numSpan: HastElement = {
+      type: "element",
+      tagName: "span",
+      properties: { class: "code-line-num", "aria-hidden": "true" },
+      children: [{ type: "text", value: String(n) }],
+    };
+    child.children.unshift(numSpan);
+  }
+}
+
+export const highlightCodeTransformer: Transformer = {
+  name: "highlightCode",
+  async apply(document) {
+    const blocks = [...document.querySelectorAll("pre > code")];
+    if (blocks.length === 0) return;
+
+    const highlighter = await getSharedHighlighter();
+
+    for (const codeEl of blocks) {
+      const pre = codeEl.parentElement;
+      if (!pre || pre.tagName.toLowerCase() !== "pre") continue;
+      if (pre.classList.contains("mermaid")) continue;
+
+      const rawLang = extractLang(codeEl as unknown as Element);
+      const lang = normalizeLang(rawLang);
+      const source = codeEl.textContent || "";
+      if (!source) continue;
+
+      let hast: HastRoot;
+      try {
+        hast = highlighter.codeToHast(source, {
+          lang: isSupportedLang(lang) ? lang : "text",
+          themes: SHIKI_THEMES,
+          defaultColor: false,
+        }) as HastRoot;
+      } catch {
+        continue;
+      }
+
+      const shikiPre = hast.children.find((c): c is HastElement => c.type === "element" && c.tagName === "pre");
+      const shikiCode = shikiPre?.children.find((c): c is HastElement => c.type === "element" && c.tagName === "code");
+      if (!shikiCode) continue;
+
+      injectLineNumbers(shikiCode.children);
+      codeEl.innerHTML = hastToHtml(shikiCode.children);
+
+      pre.classList.add("shiki");
+      if (isSupportedLang(lang)) {
+        pre.setAttribute("data-lang", lang);
+      } else {
+        pre.removeAttribute("data-lang");
+      }
+      const shikiStyle = shikiPre?.properties?.style;
+      if (typeof shikiStyle === "string" && shikiStyle) {
+        const existing = pre.getAttribute("style") || "";
+        pre.setAttribute("style", existing ? `${existing};${shikiStyle}` : shikiStyle);
+      }
+    }
+  },
+};

backend/src/publisher/transformers/html-embed.ts

@@ -0,0 +1,83 @@
+import type { Transformer } from "./types.js";
+import { buildEmbedSrcdoc, DEFAULT_EMBED_HEIGHT } from "../../shared/embed-doc.js";
+
+export { buildEmbedSrcdoc };
+
+/**
+ * Transforms `<div data-component="htmlEmbed" src="..." title="..." desc="..." height="...">`
+ * into:
+ *   <figure class="html-embed">
+ *     <div class="html-embed-container">
+ *       <iframe srcdoc="..." ... />
+ *     </div>
+ *     <figcaption class="html-embed__desc">...</figcaption>
+ *   </figure>
+ *
+ * - The stored `height` is used as the initial `height:` on the iframe so
+ *   the page reserves the right space before the iframe even loads
+ *   (important with `loading=lazy`), but is NOT used as `min-height`: that
+ *   would prevent the iframe from shrinking if the chart, on a narrower
+ *   viewport, reports a smaller scrollHeight.
+ * - A small safety `min-height` keeps the iframe from collapsing to 0 while
+ *   the embed is still loading.
+ * - `srcdoc` is built from the shared `buildEmbedSrcdoc` which also embeds
+ *   the height reporter and the theme listener.
+ * - If `title` or `desc` is present, a <figcaption> is generated so the
+ *   publisher CSS (`figure.html-embed`) can number the figure.
+ */
+const SAFETY_MIN_HEIGHT = 80;
+
+export const htmlEmbedTransformer: Transformer = {
+  name: "htmlEmbed",
+  apply(document, ctx) {
+    for (const div of [...document.querySelectorAll('div[data-component="htmlEmbed"]')]) {
+      const src = div.getAttribute("src") || div.getAttribute("data-src") || "";
+      const rawHeight = div.getAttribute("height") || div.getAttribute("data-height");
+      const initialHeight = Math.max(
+        parseInt(rawHeight || "", 10) || DEFAULT_EMBED_HEIGHT,
+        SAFETY_MIN_HEIGHT,
+      );
+      const title = div.getAttribute("title") || div.getAttribute("data-title") || "";
+      const desc = div.getAttribute("desc") || div.getAttribute("data-desc") || "";
+      const embedHtml = ctx.embeds?.[src] || "";
+
+      const figure = document.createElement("figure");
+      figure.className = "html-embed";
+      if (src) figure.setAttribute("data-embed-src", src);
+
+      const container = document.createElement("div");
+      container.className = "html-embed-container";
+
+      const iframe = document.createElement("iframe");
+      iframe.setAttribute("data-embed-src", src);
+      iframe.setAttribute(
+        "style",
+        `width:100%;border:none;display:block;height:${initialHeight}px;min-height:${SAFETY_MIN_HEIGHT}px;background:transparent;`,
+      );
+      iframe.setAttribute("loading", "lazy");
+      iframe.setAttribute("sandbox", "allow-scripts allow-same-origin");
+      if (title) iframe.setAttribute("title", title);
+
+      iframe.setAttribute("srcdoc", embedHtml ? buildEmbedSrcdoc(embedHtml) : "");
+
+      container.appendChild(iframe);
+      figure.appendChild(container);
+
+      if (title || desc) {
+        const caption = document.createElement("figcaption");
+        caption.className = "html-embed__desc";
+        if (title && desc) {
+          const strong = document.createElement("strong");
+          strong.textContent = title;
+          caption.appendChild(strong);
+          caption.appendChild(document.createTextNode(" " + desc));
+        } else {
+          caption.textContent = title || desc;
+        }
+        figure.appendChild(caption);
+      }
+
+      div.replaceWith(figure);
+    }
+  },
+};

backend/src/publisher/transformers/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Ordered registry of DOM transformers applied during `postProcess()`.
+ *
+ * Order matters:
+ *  1. Accordion      — must run early so nested content is moved before other
+ *                      transformers query it.
+ *  2. Citation       — inline markers must be resolved before bibliography
+ *                      anchors are attached, so the `#ref-<key>` hrefs align.
+ *  3. Bibliography   — consumes the ordered keys produced by the citation step.
+ *  4. Mermaid        — must run BEFORE `highlightCode`: it converts
+ *                      `<div data-component="mermaid">` into `<pre class="mermaid">`,
+ *                      and the highlighter explicitly skips `pre.mermaid`. If
+ *                      this ran after, the highlighter would try to syntax-color
+ *                      the mermaid source.
+ *  5. HighlightCode  — runs Shiki over every remaining `<pre><code>`.
+ *  6. HtmlEmbed      — independent; converts placeholder divs into iframes.
+ *  7. Footnote       — runs last so collected texts include those inside every
+ *                      other transformed block (tables, callouts, accordions...).
+ */
+import type { Transformer } from "./types.js";
+import { accordionTransformer } from "./accordion.js";
+import { citationTransformer } from "./citation.js";
+import { bibliographyTransformer } from "./bibliography.js";
+import { mermaidTransformer } from "./mermaid.js";
+import { highlightCodeTransformer } from "./highlight-code.js";
+import { htmlEmbedTransformer } from "./html-embed.js";
+import { footnoteTransformer } from "./footnote.js";
+
+export const transformers: Transformer[] = [
+  accordionTransformer,
+  citationTransformer,
+  bibliographyTransformer,
+  mermaidTransformer,
+  highlightCodeTransformer,
+  htmlEmbedTransformer,
+  footnoteTransformer,
+];
+
+export type { Transformer, TransformContext } from "./types.js";
+export { buildEmbedSrcdoc } from "./html-embed.js";

backend/src/publisher/transformers/mermaid.ts

@@ -0,0 +1,18 @@
+import type { Transformer } from "./types.js";
+
+/**
+ * Converts the editor's `<div data-component="mermaid" code="...">` into the
+ * `<pre class="mermaid">` format the Mermaid runtime expects client-side.
+ */
+export const mermaidTransformer: Transformer = {
+  name: "mermaid",
+  apply(document) {
+    for (const div of [...document.querySelectorAll('div[data-component="mermaid"]')]) {
+      const code = div.getAttribute("code") || div.getAttribute("data-code") || "";
+      const pre = document.createElement("pre");
+      pre.className = "mermaid";
+      pre.textContent = code;
+      div.replaceWith(pre);
+    }
+  },
+};

backend/src/publisher/transformers/types.ts

@@ -0,0 +1,38 @@
+/**
+ * DOM transformer contract used by the publisher post-processing pipeline.
+ *
+ * `postProcess()` in `html-renderer.ts` walks through the registry in order
+ * and lets each transformer mutate the already-parsed document in place.
+ * Keeping each concern in its own file makes the pipeline obvious and
+ * lets us unit-test individual transformers in isolation.
+ */
+
+import type { CitationData } from "../html-renderer.js";
+
+/** Mutable state passed through the pipeline (footnote collector, etc.). */
+export interface TransformContext {
+  /** Pre-formatted bibliography HTML, usually server-side from citation-js. */
+  biblioHtml: string;
+  /** Citation metadata (ordered keys, style). */
+  citationData?: CitationData;
+  /** Filename → raw HTML content for every htmlEmbed block. */
+  embeds?: Record<string, string>;
+
+  /**
+   * Footnote texts collected during the pipeline. Appended to the body as a
+   * `<section class="footnotes">` block at the end.
+   */
+  footnoteTexts: string[];
+}
+
+export interface Transformer {
+  /** Human readable id (used by tests and logs). */
+  name: string;
+  /**
+   * Mutates `document` in place. May be async (e.g. the code highlighter
+   * transformer awaits Shiki's shared highlighter on first call). No
+   * exceptions: every transformer must be idempotent and resilient to
+   * missing nodes.
+   */
+  apply(document: Document, ctx: TransformContext): void | Promise<void>;
+}

backend/src/shared/component-defs.ts

@@ -66,6 +66,7 @@ export const SHARED_COMPONENT_DEFS: SharedComponentDef[] = [
       { name: "desc", type: "string", default: "" },
       { name: "wide", type: "boolean", default: false },
       { name: "downloadable", type: "boolean", default: false },
+      { name: "height", type: "string", default: "400" },
     ],
   },
   {
@@ -88,7 +89,7 @@ export const SHARED_COMPONENT_DEFS: SharedComponentDef[] = [
     name: "mermaid",
     kind: "atomic",
     fields: [
-      { name: "code", type: "string", default: "" },
+      { name: "code", type: "string", default: "graph LR\n  A --> B" },
     ],
   },
 ];

backend/src/shared/embed-doc.ts

@@ -0,0 +1,255 @@
+// ---------------------------------------------------------------------------
+// Shared embed document builder
+//
+// Single source of truth for the srcdoc injected into every embed iframe,
+// used by both the editor (live preview) and the publisher (static HTML).
+//
+// Exports:
+//   - buildEmbedSrcdoc(html, opts) – assemble the full HTML doc
+//   - EMBED_MESSAGE_TYPES          – { resize, setTheme, updatePrimaryColor }
+//   - DEFAULT_EMBED_HEIGHT         – fallback pixel height when none stored
+//
+// Why one shared builder?
+//   Before, the editor and publisher each had their own COLOR_PALETTES / height
+//   reporter / theme listener, with subtle divergences (e.g. only the publisher
+//   supported setTheme hot-swap). Keeping them in sync by hand was a footgun.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_EMBED_HEIGHT = 400;
+
+export const EMBED_MESSAGE_TYPES = {
+  resize: "embedResize",
+  setTheme: "setTheme",
+  updatePrimaryColor: "updatePrimaryColor",
+  ready: "embedReady",
+} as const;
+
+/** ColorPalettes polyfill – mirrors the research-article-template API. */
+const COLOR_PALETTES_POLYFILL = `
+(function(){
+  var palettes = {
+    categorical: ['#4e79a7','#f28e2b','#e15759','#76b7b2','#59a14f','#edc948','#b07aa1','#ff9da7','#9c755f','#bab0ac'],
+    sequential:  ['#084594','#2171b5','#4292c6','#6baed6','#9ecae1','#c6dbef','#deebf7','#f7fbff'],
+    diverging:   ['#d73027','#f46d43','#fdae61','#fee090','#ffffbf','#e0f3f8','#abd9e9','#74add1','#4575b4']
+  };
+  window.ColorPalettes = {
+    getColors: function(type, n) {
+      var p = palettes[type] || palettes.categorical;
+      return p.slice(0, n != null ? n : p.length);
+    },
+    getPrimary: function() {
+      return getComputedStyle(document.documentElement).getPropertyValue('--primary-color').trim() || '#4e79a7';
+    },
+    refresh: function() {},
+    getTextStyleForBackground: function() { return { fill: '#ffffff' }; }
+  };
+})();
+`.trim();
+
+/**
+ * Height reporter:
+ *  - Observes documentElement + body (ResizeObserver) to catch all reflows
+ *  - Observes body's subtree (MutationObserver) to catch async chart mounts
+ *  - Throttles via requestAnimationFrame and only posts when delta >= 1px
+ *  - Safety retries at load, +300ms, +1000ms, +3000ms for slow async charts
+ *  - Exposes window.__embedReady(optionalHeight) so charts can opt-in to a
+ *    deterministic "I'm done" signal (useful for CSV fetches > 3s)
+ */
+const HEIGHT_REPORTER = `
+(function(){
+  var lastH = 0;
+  var scheduled = false;
+  // IMPORTANT: only measure <body>. document.documentElement.scrollHeight is
+  // clamped to at least the iframe's viewport height, so it would never allow
+  // the iframe to shrink (it would always report >= current iframe height).
+  // body.scrollHeight reflects the actual content height plus body padding.
+  function measure(){
+    var b = document.body;
+    if (!b) return 0;
+    // getBoundingClientRect().bottom accounts for padding/margin precisely;
+    // fall back to scrollHeight if the rect reports 0 (detached layout).
+    var rectBottom = Math.ceil(b.getBoundingClientRect().bottom);
+    var scroll = Math.ceil(b.scrollHeight);
+    // body margin may push the rect down; scrollHeight ignores it. Take the
+    // max so we never under-report.
+    return Math.max(rectBottom, scroll);
+  }
+  function post(h){
+    try {
+      window.parent.postMessage({ type: 'embedResize', height: h }, '*');
+    } catch(e){}
+  }
+  function schedule(){
+    if (scheduled) return;
+    scheduled = true;
+    requestAnimationFrame(function(){
+      scheduled = false;
+      var h = measure();
+      if (h > 0 && Math.abs(h - lastH) >= 1) {
+        lastH = h;
+        post(h);
+      }
+    });
+  }
+  if (typeof ResizeObserver !== 'undefined') {
+    var ro = new ResizeObserver(schedule);
+    ro.observe(document.documentElement);
+    if (document.body) ro.observe(document.body);
+  }
+  if (typeof MutationObserver !== 'undefined' && document.body) {
+    var mo = new MutationObserver(schedule);
+    mo.observe(document.body, { childList: true, subtree: true, attributes: true, characterData: true });
+  }
+  window.addEventListener('load', function(){
+    schedule();
+    setTimeout(schedule, 300);
+    setTimeout(schedule, 1000);
+    setTimeout(schedule, 3000);
+  });
+  // Opt-in explicit ready signal for async charts
+  window.__embedReady = function(){
+    schedule();
+    try { window.parent.postMessage({ type: 'embedReady' }, '*'); } catch(e){}
+  };
+})();
+`.trim();
+
+/**
+ * Theme listener: swap CSS variables via [data-theme] without reloading.
+ * Also supports live primary-color updates and invokes window.__chartRerender
+ * if the embed defines one (same convention as research-article-template).
+ */
+const THEME_LISTENER = `
+(function(){
+  window.addEventListener('message', function(e){
+    if (!e.data) return;
+    if (e.data.type === 'setTheme') {
+      document.documentElement.setAttribute('data-theme', e.data.theme);
+      document.documentElement.style.colorScheme = e.data.theme === 'dark' ? 'dark' : 'light';
+      if (e.data.primaryColor) {
+        document.documentElement.style.setProperty('--primary-color', e.data.primaryColor);
+      }
+      if (window.__chartRerender) try { window.__chartRerender(); } catch(err){}
+    } else if (e.data.type === 'updatePrimaryColor') {
+      document.documentElement.style.setProperty('--primary-color', e.data.color);
+      if (window.__chartRerender) try { window.__chartRerender(); } catch(err){}
+    }
+  });
+})();
+`.trim();
+
+const BASE_STYLES = `
+:root, [data-theme='light'] {
+  color-scheme: light;
+  --text-color: rgba(0,0,0,.85);
+  --surface-bg: #f9f9f9;
+  --page-bg: #fff;
+  --border-color: rgba(0,0,0,.1);
+  --muted-color: rgba(0,0,0,.6);
+  --axis-color: rgba(0,0,0,.6);
+  --tick-color: rgba(0,0,0,.85);
+  --grid-color: rgba(0,0,0,.08);
+}
+[data-theme='dark'] {
+  color-scheme: dark;
+  --text-color: rgba(255,255,255,.9);
+  --surface-bg: #07080a;
+  --page-bg: #0f1115;
+  --border-color: rgba(255,255,255,.15);
+  --muted-color: rgba(255,255,255,.7);
+  --axis-color: rgba(255,255,255,.7);
+  --tick-color: rgba(255,255,255,.7);
+  --grid-color: rgba(255,255,255,.10);
+}
+*, *::before, *::after { box-sizing: border-box; }
+/* IMPORTANT: do NOT set min-height:100% on <body>. Doing so creates a
+   lower bound on scrollHeight equal to the iframe's rendered height, so
+   the reporter can never signal a smaller height and the iframe can only
+   ever grow (never shrink when the chart re-renders narrower on resize). */
+html, body { margin: 0; padding: 0; background: transparent; }
+body {
+  color: var(--text-color);
+  font-family: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', sans-serif;
+  font-size: 13px;
+  padding: 16px;
+  /* overflow: clip clips runaway horizontal content without creating a
+     scroll container that would trap scroll events or inflate scrollHeight. */
+  overflow: clip;
+}
+`.trim();
+
+/**
+ * Escape `</script>` inside the embed HTML fragment so the outer parser does
+ * not terminate its own <script> block prematurely. Keeps the final closing
+ * tag intact in case the embed itself ends with `</script>`.
+ */
+function escapeScriptTags(html: string): string {
+  const escaped = html.replace(/<\/script>/gi, "<\\/script>");
+  const lastIdx = escaped.lastIndexOf("<\\/script>");
+  if (lastIdx === -1) return html;
+  return escaped.slice(0, lastIdx) + "</script>" + escaped.slice(lastIdx + 10);
+}
+
+export interface BuildEmbedSrcdocOptions {
+  /** Initial theme, before any setTheme postMessage is received. */
+  isDark?: boolean;
+  /** Initial primary color (CSS color), defaults to #4e79a7. */
+  primaryColor?: string;
+  /**
+   * Edge-to-edge mode (used for article banners):
+   *   - html/body fill 100% of the iframe viewport
+   *   - no body padding (chart bleeds to the edges)
+   *   - height reporter is skipped (iframe is size-driven by its parent's
+   *     aspect-ratio, not by the chart's scrollHeight)
+   */
+  fullBleed?: boolean;
+}
+
+/**
+ * Stylesheet override applied when `fullBleed` is true. Replaces the
+ * default body padding and establishes a proper 100%-height chain so
+ * charts declaring `height: 100%` actually get a measurable height.
+ */
+const FULL_BLEED_STYLES = `
+html, body { height: 100%; width: 100%; }
+body { padding: 0 !important; overflow: hidden; }
+body > :first-child { width: 100%; height: 100%; }
+`.trim();
+
+/**
+ * Build a self-contained HTML document suitable for iframe `srcdoc=`.
+ * Theme changes after load should be driven via postMessage (`setTheme`)
+ * rather than rebuilding the srcdoc – otherwise the iframe reloads and loses
+ * chart state.
+ */
+export function buildEmbedSrcdoc(htmlFragment: string, opts: BuildEmbedSrcdocOptions = {}): string {
+  const isDark = !!opts.isDark;
+  const primaryColor = opts.primaryColor || "#4e79a7";
+  const themeAttr = isDark ? "dark" : "light";
+  const inlinePrimary = `:root{--primary-color:${primaryColor};}`;
+  const fullBleed = !!opts.fullBleed;
+  const extraStyles = fullBleed ? FULL_BLEED_STYLES : "";
+
+  const parts: string[] = [
+    "<!DOCTYPE html>",
+    `<html data-theme="${themeAttr}">`,
+    "<head>",
+    '<meta charset="UTF-8">',
+    `<style>${BASE_STYLES}${inlinePrimary}${extraStyles}</style>`,
+    `<script>${COLOR_PALETTES_POLYFILL}<\/script>`,
+    "</head>",
+    "<body>",
+    escapeScriptTags(htmlFragment),
+  ];
+
+  // Skip the height reporter in fullBleed mode: the iframe is size-driven
+  // by its parent's aspect-ratio (e.g. the banner 5:2 box) and must not
+  // try to resize itself based on chart scrollHeight.
+  if (!fullBleed) {
+    parts.push(`<script>${HEIGHT_REPORTER}<\/script>`);
+  }
+  parts.push(`<script>${THEME_LISTENER}<\/script>`);
+  parts.push("</body></html>");
+
+  return parts.join("\n");
+}

backend/src/shared/shiki-config.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared Shiki configuration.
+ *
+ * Single source of truth for syntax highlighting across the editor (live
+ * decorations) and the publisher (static SSR). Using the same config in both
+ * environments guarantees:
+ *   - identical supported languages
+ *   - identical themes / token colors
+ *   - identical output structure (<span class="line"><span style=...>)
+ *
+ * Shiki is async-initialized (it loads an Oniguruma WASM engine + grammars).
+ * A singleton highlighter is created on first use and reused forever. The
+ * editor kicks off creation at mount; the publisher awaits it synchronously
+ * during render (publish is a one-shot pipeline).
+ */
+
+import type { BundledLanguage, BundledTheme, HighlighterGeneric } from "shiki";
+import { createHighlighter } from "shiki";
+
+/**
+ * Languages bundled into the highlighter. Chosen for research/tech articles.
+ * Keep this list in sync with what the editor's language selector advertises.
+ * Adding a language = one line here + redeploy; the cost is ~50KB gzipped per
+ * grammar loaded lazily.
+ */
+export const SHIKI_LANGS: BundledLanguage[] = [
+  "javascript",
+  "typescript",
+  "tsx",
+  "jsx",
+  "python",
+  "bash",
+  "shell",
+  "json",
+  "yaml",
+  "toml",
+  "css",
+  "html",
+  "xml",
+  "markdown",
+  "sql",
+  "rust",
+  "go",
+  "c",
+  "cpp",
+  "csharp",
+  "java",
+  "r",
+  "julia",
+  "ruby",
+  "php",
+  "swift",
+  "kotlin",
+  "scala",
+  "haskell",
+  "lua",
+  "dockerfile",
+  "diff",
+  "latex",
+  "ini",
+  "makefile",
+  "graphql",
+];
+
+/**
+ * Dual theme: Shiki emits each token with inline `color` (light) plus a
+ * `--shiki-dark` CSS variable (dark). A small CSS rule toggles which wins
+ * based on the `data-theme` attribute on <html>. See `_code-blocks.css`.
+ *
+ * Pick well-balanced, muted themes that read well in an academic context.
+ */
+export const SHIKI_THEMES = {
+  light: "github-light" as BundledTheme,
+  dark: "github-dark" as BundledTheme,
+};
+
+export type ShikiHighlighter = HighlighterGeneric<BundledLanguage, BundledTheme>;
+
+let highlighterPromise: Promise<ShikiHighlighter> | null = null;
+
+/**
+ * Returns the shared highlighter, creating it on first call. All subsequent
+ * callers wait on the same promise (deduped).
+ */
+export function getSharedHighlighter(): Promise<ShikiHighlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: [SHIKI_THEMES.light, SHIKI_THEMES.dark],
+      langs: SHIKI_LANGS,
+    });
+  }
+  return highlighterPromise;
+}
+
+/**
+ * Checks whether a language string is supported. Falls back to plain-text
+ * rendering if not, which is what both editor and publisher should do.
+ */
+export function isSupportedLang(lang: string | null | undefined): lang is BundledLanguage {
+  if (!lang) return false;
+  return (SHIKI_LANGS as readonly string[]).includes(lang);
+}
+
+/**
+ * Normalize a language alias to the canonical name Shiki expects. Handles
+ * common aliases that users type (`js` → `javascript`, `py` → `python`, etc.).
+ */
+export function normalizeLang(lang: string | null | undefined): string {
+  if (!lang) return "";
+  const l = lang.toLowerCase().trim();
+  const aliases: Record<string, string> = {
+    js: "javascript",
+    ts: "typescript",
+    py: "python",
+    rb: "ruby",
+    sh: "bash",
+    zsh: "bash",
+    yml: "yaml",
+    md: "markdown",
+    "c++": "cpp",
+    "c#": "csharp",
+    docker: "dockerfile",
+    tex: "latex",
+  };
+  return aliases[l] ?? l;
+}

backend/src/shared/theme.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared theming constants used by both the editor (to preview primary color
+ * changes live) and the publisher (to bake them into the published HTML).
+ *
+ * Keep lightness/chroma here as the single source of truth. CSS `_variables.css`
+ * still owns the *default* primary hue; this module only defines the L/C pair
+ * shared by the HueSlider preview and the server-side override.
+ */
+
+export const OKLCH_L = 0.75;
+export const OKLCH_C = 0.12;
+
+/** Format an OKLCH color string using the shared L/C and a given hue (0-360). */
+export function oklchFromHue(hue: number): string {
+  const h = ((hue % 360) + 360) % 360;
+  return `oklch(${OKLCH_L} ${OKLCH_C} ${h})`;
+}

backend/tests/__snapshots__/html-renderer-snapshot.test.ts.snap

@@ -26,18 +26,41 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
 
   <!-- KaTeX CSS -->
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css"
-        integrity="sha384-zh0CIslj3dQfMxK3pZnPJAb3bprHitCE2vBz9TyOTICAn3fso5GYa90qPNMBclov"
+        integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib"
         crossorigin="anonymous">
 
-  <!-- highlight.js for code syntax highlighting -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github-dark.min.css">
-  <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/highlight.min.js"></script>
-  <script>hljs.highlightAll();</script>
+  <!-- Code blocks are pre-highlighted at publish time with Shiki (dual-theme
+       via --shiki-dark CSS vars). Zero runtime JS, zero CDN dependency. -->
 
-  <!-- Mermaid (renders <pre class="mermaid"> blocks) -->
+  <!-- Mermaid (renders <pre class="mermaid"> blocks, auto-theme dark/light) -->
   <script type="module">
     import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
-    mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
+    function getTheme() {
+      return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'neutral';
+    }
+    mermaid.initialize({ startOnLoad: false, theme: getTheme() });
+
+    document.querySelectorAll('pre.mermaid').forEach(function(el) {
+      el.setAttribute('data-mermaid-src', el.textContent || '');
+    });
+    await mermaid.run();
+
+    new MutationObserver(function(ms) {
+      for (var i = 0; i < ms.length; i++) {
+        if (ms[i].attributeName === 'data-theme') {
+          mermaid.initialize({ startOnLoad: false, theme: getTheme() });
+          document.querySelectorAll('pre.mermaid').forEach(function(el) {
+            var src = el.getAttribute('data-mermaid-src');
+            if (src) {
+              el.removeAttribute('data-processed');
+              el.textContent = src;
+            }
+          });
+          mermaid.run();
+          break;
+        }
+      }
+    }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
   </script>
 
   <style>
@@ -75,11 +98,21 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
   <aside class="toc-mobile-sidebar" aria-label="Table of Contents">
     <div class="toc-mobile-sidebar__header">
       <span class="toc-mobile-sidebar__title">Table of Contents</span>
-      <button class="toc-mobile-sidebar__close" aria-label="Close">
+      <div class="toc-mobile-sidebar__actions">
+        <button class="toc-mobile-sidebar__theme" aria-label="Toggle color theme">
+          <svg class="icon light" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="4"/><line x1="12" y1="20" x2="12" y2="23"/><line x1="1" y1="12" x2="4" y2="12"/><line x1="20" y1="12" x2="23" y2="12"/><line x1="4.22" y1="4.22" x2="6.34" y2="6.34"/><line x1="17.66" y1="17.66" x2="19.78" y2="19.78"/><line x1="4.22" y1="19.78" x2="6.34" y2="17.66"/><line x1="17.66" y1="6.34" x2="19.78" y2="4.22"/>
+          </svg>
+          <svg class="icon dark" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+          </svg>
+        </button>
+        <button class="toc-mobile-sidebar__close" aria-label="Close table of contents">
         <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
           <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
         </svg>
       </button>
+      </div>
     </div>
     <div class="toc-mobile-sidebar__body" id="toc-mobile-placeholder"></div>
   </aside>
@@ -88,20 +121,21 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
   <section class="hero">
     <h1 class="hero-title">Test Article</h1>
     
+    
   </section>
 
   <!-- Meta bar -->
   <header class="meta"><div class="meta-container"><div class="meta-container-cell"><h3>Authors</h3><ul class="authors"><li>Alice</li></ul></div><div class="meta-container-cell"><h3>Affiliations</h3><p>MIT</p></div><div class="meta-container-cell"><h3>Published</h3><p>January 1, 2025</p></div></div></header>
 
   <section class="content-grid">
-    <nav class="table-of-contents" aria-label="Table of Contents">
+    <nav class="table-of-contents" aria-label="Table of Contents" data-auto-collapse="0">
       <div class="title">Table of Contents</div>
       <div id="toc-placeholder"></div>
     </nav>
 
     <main>
       <div class="tiptap">
-        <h2>Introduction</h2><p>This is a test article with a <a title="ref1" id="cite-ref1-1" class="citation-inline" href="#ref-ref1">Ref (2024)</a> citation.</p><p>A footnote here<sup class="footnote-ref"><a id="fnref-1" href="#fn-1">[1]</a></sup></p><div data-type="bibliography" class="bibliography-block"><h2 class="bibliography-title">References</h2><div class="bibliography-content"><div id="ref-ref1" class="csl-entry">Reference One. 2024.</div></div></div><section class="footnotes"><h2>Footnotes</h2><ol><li id="fn-1"><p>Important detail <a href="#fnref-1" class="footnote-backref" aria-label="Back to text">↩</a></p></li></ol></section>
+        <h2>Introduction</h2><p>This is a test article with a <a title="ref1" id="cite-ref1-1" class="citation-inline" href="#ref-ref1">Ref (2024)<span aria-hidden="true" class="pub-tooltip pub-tooltip--citation"><span class="pub-tooltip__title">Reference One</span></span></a> citation.</p><p>A footnote here<sup class="footnote-ref"><a id="fnref-1" href="#fn-1">[1]</a></sup></p><div data-type="bibliography" class="bibliography-block"><h2 class="bibliography-title">References</h2><div class="bibliography-content"><div id="ref-ref1" class="csl-entry">Reference One. 2024.</div></div></div><section class="footnotes"><h2>Footnotes</h2><ol><li id="fn-1"><p>Important detail <a href="#fnref-1" class="footnote-backref" aria-label="Back to text">↩</a></p></li></ol></section>
       </div>
     </main>
   </section>
@@ -207,6 +241,9 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
     });
 
     // Build nested nav with data-heading-idx
+    // Each nested <ul> is wrapped in <div class="toc-children"> so we can
+    // animate expand/collapse via the grid-template-rows 0fr/1fr trick
+    // (CSS cannot interpolate height:auto).
     var nav = document.createElement('nav');
     var ulStack = [document.createElement('ul')];
     nav.appendChild(ulStack[0]);
@@ -214,7 +251,16 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
     var prev = 2, hIdx = 0;
     headingsArr.forEach(function(h) {
       var lvl = levelOf(h.tagName);
-      while (lvl > prev) { var ul = document.createElement('ul'); var last = ulStack[ulStack.length-1].lastElementChild; if (last) last.appendChild(ul); ulStack.push(ul); prev++; }
+      while (lvl > prev) {
+        var wrap = document.createElement('div');
+        wrap.className = 'toc-children';
+        var ul = document.createElement('ul');
+        wrap.appendChild(ul);
+        var last = ulStack[ulStack.length-1].lastElementChild;
+        if (last) last.appendChild(wrap);
+        ulStack.push(ul);
+        prev++;
+      }
       while (lvl < prev) { ulStack.pop(); prev--; }
       var li = document.createElement('li');
       var a = document.createElement('a');
@@ -254,11 +300,13 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
 
     // ---- Auto-collapse logic ----
     var isMobile = window.matchMedia('(max-width: 1100px)');
+    var tocNav = document.querySelector('.table-of-contents');
+    var autoCollapseEnabled = tocNav && tocNav.getAttribute('data-auto-collapse') === '1';
 
     function getItemsWithChildren(navEl) {
       if (!navEl) return [];
       return Array.from(navEl.querySelectorAll('li[data-heading-idx]')).filter(function(li) {
-        return li.querySelector(':scope > ul');
+        return li.querySelector(':scope > .toc-children');
       });
     }
 
@@ -267,7 +315,9 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
       var activeLi = null;
       function find(li) {
         if (Number(li.getAttribute('data-heading-idx')) === targetIdx) return li;
-        var ul = li.querySelector(':scope > ul');
+        var wrap = li.querySelector(':scope > .toc-children');
+        if (!wrap) return null;
+        var ul = wrap.querySelector(':scope > ul');
         if (!ul) return null;
         var children = ul.querySelectorAll(':scope > li[data-heading-idx]');
         for (var i = 0; i < children.length; i++) { var f = find(children[i]); if (f) return f; }
@@ -285,27 +335,21 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
       return toExpand;
     }
 
+    // Just toggle the .collapsed class on the li. The CSS rule
+    // .toc-collapsible li.collapsed > .toc-children { grid-template-rows: 0fr }
+    // drives the actual animation (no JS height math).
     function applyCollapseState(navEl, activeIdx) {
       if (!navEl) return;
       var items = getItemsWithChildren(navEl);
       var ancestors = getAncestorIndices(items, activeIdx);
 
       items.forEach(function(li) {
-        var sub = li.querySelector(':scope > ul');
-        if (!sub) return;
         var idx = Number(li.getAttribute('data-heading-idx'));
         var allDesc = li.querySelectorAll('li[data-heading-idx]');
         var related = [idx];
         allDesc.forEach(function(d) { related.push(Number(d.getAttribute('data-heading-idx'))); });
         var shouldExpand = related.some(function(i) { return ancestors[i]; });
-
-        if (shouldExpand) {
-          li.classList.remove('collapsed');
-          sub.style.height = 'auto';
-        } else {
-          li.classList.add('collapsed');
-          sub.style.height = '0px';
-        }
+        li.classList.toggle('collapsed', !shouldExpand);
       });
     }
 
@@ -313,13 +357,16 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
       if (!navEl) return;
       getItemsWithChildren(navEl).forEach(function(li) {
         li.classList.remove('collapsed');
-        var sub = li.querySelector(':scope > ul');
-        if (sub) sub.style.height = 'auto';
       });
     }
 
-    // Initial state: collapse all except first section
+    // Initial state: collapse only if auto-collapse is enabled.
+    // We suppress transitions for the first paint so the user doesn't see
+    // a close-animation at page load when auto-collapse is on.
     function initCollapse() {
+      if (!autoCollapseEnabled) return;
+      if (nav) nav.classList.add('toc-no-transition');
+      if (navClone) navClone.classList.add('toc-no-transition');
       if (isMobile.matches) {
         expandAll(holder ? holder.querySelector('nav') : null);
         expandAll(holderMobile ? holderMobile.querySelector('nav') : null);
@@ -327,10 +374,17 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
         applyCollapseState(holder ? holder.querySelector('nav') : null, 0);
         applyCollapseState(holderMobile ? holderMobile.querySelector('nav') : null, 0);
       }
+      requestAnimationFrame(function(){
+        requestAnimationFrame(function(){
+          if (nav) nav.classList.remove('toc-no-transition');
+          if (navClone) navClone.classList.remove('toc-no-transition');
+        });
+      });
     }
     initCollapse();
 
     isMobile.addEventListener('change', function() {
+      if (!autoCollapseEnabled) return;
       if (isMobile.matches) {
         expandAll(holder ? holder.querySelector('nav') : null);
         expandAll(holderMobile ? holderMobile.querySelector('nav') : null);
@@ -340,33 +394,70 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
       }
     });
 
-    // ---- Scroll tracking ----
-    var OFFSET = 60, lastScrollTime = 0, prevActiveIdx = 0;
+    // ---- Scroll tracking (IntersectionObserver-driven) ----
+    // Semantics: active heading = the last one whose top has crossed the
+    // OFFSET line ("section I'm currently reading"). This matches typical
+    // documentation UX (MDN, Docusaurus, etc.) and is intentionally different
+    // from the editor-side TOC which picks the topmost visible heading in its
+    // scroll container (better suited to non-linear editing navigation).
+    //
+    // We use IntersectionObserver only as a trigger: it fires precisely when
+    // a heading crosses the OFFSET boundary, which are the only moments the
+    // active heading can change. No per-frame scroll handler, no throttling.
+    var OFFSET = 60, prevActiveIdx = -1, prevActiveId = null, rafPending = false;
+
+    function findActiveHeading() {
+      for (var i = headingsArr.length - 1; i >= 0; i--) {
+        var h = headingsArr[i];
+        // Skip headings removed from DOM or moved outside article (e.g. footnotes moved to footer)
+        if (!h.isConnected || !articleRoot.contains(h)) continue;
+        if (h.getBoundingClientRect().top - OFFSET <= 0) {
+          return { idx: i, id: h.id };
+        }
+      }
+      return { idx: -1, id: null };
+    }
 
-    function onScroll() {
-      var now = performance.now();
-      if (now - lastScrollTime < 50) return;
-      lastScrollTime = now;
+    function updateActive() {
+      if (rafPending) return;
+      rafPending = true;
       requestAnimationFrame(function() {
-        var activeIdx = -1, activeId = null;
-        for (var i = headingsArr.length - 1; i >= 0; i--) {
-          if (headingsArr[i].getBoundingClientRect().top - OFFSET <= 0) {
-            activeIdx = i; activeId = headingsArr[i].id; break;
+        rafPending = false;
+        var result = findActiveHeading();
+        var activeIdx = result.idx, activeId = result.id;
+        if (activeId === prevActiveId && activeIdx === prevActiveIdx) return;
+        allLinks.forEach(function(l) { l.classList.remove('active'); });
+        if (activeId) {
+          var href = '#' + activeId;
+          allLinks.forEach(function(l) {
+            if (l.getAttribute('href') === href) l.classList.add('active');
+          });
+        }
+        if (activeIdx >= 0 && activeIdx !== prevActiveIdx) {
+          if (autoCollapseEnabled && !isMobile.matches) {
+            applyCollapseState(holder ? holder.querySelector('nav') : null, activeIdx);
           }
         }
-        allLinks.forEach(function(l) {
-          if (activeId && l.getAttribute('href') === '#'+activeId) l.classList.add('active');
-          else l.classList.remove('active');
-        });
-        if (activeIdx !== prevActiveIdx && activeIdx >= 0 && !isMobile.matches) {
           prevActiveIdx = activeIdx;
-          applyCollapseState(holder ? holder.querySelector('nav') : null, activeIdx);
-        }
-        if (activeIdx >= 0) prevActiveIdx = activeIdx;
+        prevActiveId = activeId;
       });
     }
-    window.addEventListener('scroll', onScroll, { passive: true });
-    onScroll();
+
+    if (typeof IntersectionObserver !== 'undefined') {
+      var spyObserver = new IntersectionObserver(updateActive, {
+        rootMargin: '-' + OFFSET + 'px 0px 0px 0px',
+        threshold: 0,
+      });
+      headingsArr.forEach(function(h) {
+        if (articleRoot.contains(h)) spyObserver.observe(h);
+      });
+      // rootMargin changes on resize (viewport height affects the bottom edge
+      // of the root), but the top offset is fixed, so no need to recreate.
+    } else {
+      // Fallback for browsers without IntersectionObserver (very old).
+      window.addEventListener('scroll', updateActive, { passive: true });
+    }
+    updateActive();
 
     // ---- Mobile sidebar ----
     var sidebar = document.querySelector('.toc-mobile-sidebar');
@@ -397,6 +488,16 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
     if (holderMobile) holderMobile.addEventListener('click', function(e) { if (e.target.closest && e.target.closest('a')) closeSidebar(); });
     document.addEventListener('keydown', function(e) { if (e.key==='Escape' && sidebar.classList.contains('open')) closeSidebar(); });
 
+    // Sidebar theme toggle
+    var sidebarThemeBtn = document.querySelector('.toc-mobile-sidebar__theme');
+    if (sidebarThemeBtn) {
+      sidebarThemeBtn.addEventListener('click', function() {
+        var next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+        localStorage.setItem('theme', next);
+        applyTheme(next);
+      });
+    }
+
     // ---- Footer: move references & footnotes ----
     (function() {
       var footer = document.querySelector('footer.footer');
@@ -458,6 +559,41 @@ exports[`snapshot - full render > matches snapshot for a typical article 1`] = `
       setTimeout(run, 300);
     })();
 
+    // Sync theme with embed iframes (body embeds + hero banner)
+    function syncEmbedThemes() {
+      var theme = document.documentElement.dataset.theme || 'dark';
+      document.querySelectorAll('.html-embed-container iframe, .hero-banner iframe').forEach(function(iframe) {
+        try { iframe.contentWindow.postMessage({ type: 'setTheme', theme: theme }, '*'); } catch(e) {}
+      });
+    }
+    var obs = new MutationObserver(function(ms) {
+      for (var i = 0; i < ms.length; i++) {
+        if (ms[i].attributeName === 'data-theme') { syncEmbedThemes(); break; }
+      }
+    });
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+
+    // Auto-size embed iframes from postMessage height reports.
+    // Dedupe: only apply when the new height differs from the last applied
+    // (prevents style thrash during tight ResizeObserver bursts).
+    var _lastEmbedHeight = new WeakMap();
+    window.addEventListener('message', function(e) {
+      if (!e.data || e.data.type !== 'embedResize') return;
+      var h = Math.max(0, Math.ceil(e.data.height));
+      if (!h) return;
+      document.querySelectorAll('.html-embed-container iframe').forEach(function(iframe) {
+        try {
+          if (iframe.contentWindow !== e.source) return;
+          if (_lastEmbedHeight.get(iframe) === h) return;
+          _lastEmbedHeight.set(iframe, h);
+          iframe.style.height = h + 'px';
+        } catch(ex) {}
+      });
+    });
+
+    // Initial theme sync after iframes load
+    window.addEventListener('load', function() { setTimeout(syncEmbedThemes, 200); });
+
     // Hash navigation
     if (window.location.hash) {
       var target = document.querySelector(window.location.hash);

backend/tests/css-resolution.test.ts

@@ -2,25 +2,9 @@
  * CSS Resolution Tests (Section 1.2.2 of TESTS.md)
  *
  * Tests that @custom-media rules are properly resolved for published HTML.
- * We test the resolveCustomMedia function indirectly through the publish flow.
  */
 import { describe, it, expect } from "vitest";
-
-// resolveCustomMedia is not exported, so we re-implement the logic for testing.
-// This tests the algorithm, not the import path.
-function resolveCustomMedia(allCss: string): string {
-  const mediaMap = new Map<string, string>();
-  const declRegex = /@custom-media\s+(--[\w-]+)\s+\(([^)]+)\)\s*;/g;
-  let match: RegExpExecArray | null;
-  while ((match = declRegex.exec(allCss)) !== null) {
-    mediaMap.set(match[1], `(${match[2]})`);
-  }
-  let resolved = allCss.replace(/@custom-media\s+--[\w-]+\s+\([^)]+\)\s*;/g, "");
-  for (const [name, value] of mediaMap) {
-    resolved = resolved.replaceAll(`(${name})`, value);
-  }
-  return resolved;
-}
+import { resolveCustomMedia } from "../src/publisher/index.js";
 
 describe("1.2.2 CSS @custom-media resolution", () => {
   it("resolves custom media declarations", () => {

backend/tests/html-renderer-snapshot.test.ts

@@ -27,40 +27,40 @@ function minimalDoc(content: any[]) {
 }
 
 describe("renderArticleHTML", () => {
-  it("produces a complete HTML document", () => {
+  it("produces a complete HTML document", async () => {
     const json = minimalDoc([{ type: "paragraph", content: [{ type: "text", text: "Hello world" }] }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain("<!DOCTYPE html>");
     expect(html).toContain("<title>Test Article</title>");
     expect(html).toContain("Hello world");
   });
 
-  it("escapes HTML in meta fields", () => {
+  it("escapes HTML in meta fields", async () => {
     const meta: PublishMeta = { ...BASIC_META, title: 'Title with "quotes" & <tags>' };
     const json = minimalDoc([{ type: "paragraph" }]);
-    const html = renderArticleHTML(json, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(json, meta, EMPTY_CSS);
     expect(html).toContain("&amp;");
     expect(html).toContain("&lt;tags&gt;");
     expect(html).not.toContain('<tags>');
   });
 
-  it("renders PDF download link when pdfUrl is set", () => {
+  it("renders PDF download link when pdfUrl is set", async () => {
     const meta: PublishMeta = { ...BASIC_META, pdfUrl: "/published/test/article.pdf" };
     const json = minimalDoc([{ type: "paragraph" }]);
-    const html = renderArticleHTML(json, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(json, meta, EMPTY_CSS);
     expect(html).toContain("Download PDF");
     expect(html).toContain("/published/test/article.pdf");
   });
 });
 
 describe("postProcess - accordion", () => {
-  it("transforms accordion div into details/summary", () => {
+  it("transforms accordion div into details/summary", async () => {
     const json = minimalDoc([{
       type: "accordion",
       attrs: { title: "My Section", open: false },
       content: [{ type: "paragraph", content: [{ type: "text", text: "Inner content" }] }],
     }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain("<details");
     expect(html).toContain("<summary>");
     expect(html).toContain("Inner content");
@@ -68,7 +68,7 @@ describe("postProcess - accordion", () => {
 });
 
 describe("postProcess - citations", () => {
-  it("replaces citation spans with anchor links", () => {
+  it("replaces citation spans with anchor links", async () => {
     const json = minimalDoc([{
       type: "paragraph",
       content: [
@@ -81,12 +81,12 @@ describe("postProcess - citations", () => {
       orderedKeys: ["smith2024"],
       style: "apa",
     };
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData);
     expect(html).toContain('href="#ref-smith2024"');
     expect(html).toContain("citation-inline");
   });
 
-  it("uses numeric labels for IEEE style", () => {
+  it("uses numeric labels for IEEE style", async () => {
     const json = minimalDoc([{
       type: "paragraph",
       content: [
@@ -98,13 +98,13 @@ describe("postProcess - citations", () => {
       orderedKeys: ["doe2023"],
       style: "ieee",
     };
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData);
     expect(html).toContain("[1]");
   });
 });
 
 describe("postProcess - footnotes", () => {
-  it("collects footnotes and appends a footnotes section", () => {
+  it("collects footnotes and appends a footnotes section", async () => {
     const json = minimalDoc([{
       type: "paragraph",
       content: [
@@ -112,14 +112,14 @@ describe("postProcess - footnotes", () => {
         { type: "footnote", attrs: { content: "This is a footnote" } },
       ],
     }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain('class="footnote-ref"');
     expect(html).toContain('id="fn-1"');
     expect(html).toContain("This is a footnote");
     expect(html).toContain('class="footnotes"');
   });
 
-  it("numbers multiple footnotes sequentially", () => {
+  it("numbers multiple footnotes sequentially", async () => {
     const json = minimalDoc([{
       type: "paragraph",
       content: [
@@ -128,7 +128,7 @@ describe("postProcess - footnotes", () => {
         { type: "footnote", attrs: { content: "Second note" } },
       ],
     }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain('id="fn-1"');
     expect(html).toContain('id="fn-2"');
     expect(html).toContain("First note");
@@ -137,32 +137,56 @@ describe("postProcess - footnotes", () => {
 });
 
 describe("postProcess - mermaid", () => {
-  it("transforms mermaid div into pre.mermaid", () => {
+  it("transforms mermaid div into pre.mermaid", async () => {
     const json = minimalDoc([{
       type: "mermaid",
       attrs: { code: "graph TD\n  A --> B" },
     }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain('class="mermaid"');
     expect(html).toContain("graph TD");
   });
 });
 
 describe("postProcess - htmlEmbed", () => {
-  it("transforms htmlEmbed div into iframe", () => {
+  it("transforms htmlEmbed div into iframe", async () => {
     const json = minimalDoc([{
       type: "htmlEmbed",
       attrs: { src: "d3-chart.html", title: "Chart", desc: "" },
     }]);
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS);
     expect(html).toContain("html-embed-container");
     expect(html).toContain('data-embed-src="d3-chart.html"');
     expect(html).toContain("<iframe");
   });
+
+  it("injects embed HTML from Y.Map into iframe srcdoc", async () => {
+    const json = minimalDoc([{
+      type: "htmlEmbed",
+      attrs: { src: "my-chart", title: "Chart", desc: "" },
+    }]);
+    const embeds = { "my-chart": '<div id="chart"><script>console.log("hello")<\/script></div>' };
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, undefined, undefined, embeds);
+    expect(html).toContain("html-embed-container");
+    expect(html).toContain('data-embed-src="my-chart"');
+    expect(html).toContain("srcdoc=");
+    expect(html).toContain("ColorPalettes");
+    expect(html).toContain("chart");
+  });
+
+  it("leaves srcdoc empty when embed key is missing", async () => {
+    const json = minimalDoc([{
+      type: "htmlEmbed",
+      attrs: { src: "missing-chart", title: "Chart", desc: "" },
+    }]);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, undefined, undefined, {});
+    expect(html).toContain('data-embed-src="missing-chart"');
+    expect(html).toContain('srcdoc=""');
+  });
 });
 
 describe("postProcess - bibliography", () => {
-  it("injects bibliography HTML into the placeholder", () => {
+  it("injects bibliography HTML into the placeholder", async () => {
     const json = minimalDoc([
       { type: "paragraph", content: [{ type: "citation", attrs: { key: "test2024", label: "[1]" } }] },
       { type: "bibliography", attrs: { renderedHtml: "" } },
@@ -173,7 +197,7 @@ describe("postProcess - bibliography", () => {
       style: "apa",
     };
     const biblioHtml = '<div class="csl-entry">Test entry</div>';
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData, biblioHtml);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData, biblioHtml);
     expect(html).toContain("bibliography-content");
     expect(html).toContain('id="ref-test2024"');
     expect(html).toContain("Test entry");
@@ -181,7 +205,7 @@ describe("postProcess - bibliography", () => {
 });
 
 describe("snapshot - full render", () => {
-  it("matches snapshot for a typical article", () => {
+  it("matches snapshot for a typical article", async () => {
     const json = minimalDoc([
       { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "Introduction" }] },
       { type: "paragraph", content: [
@@ -203,7 +227,7 @@ describe("snapshot - full render", () => {
     };
     const biblioHtml = '<div class="csl-entry">Reference One. 2024.</div>';
 
-    const html = renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData, biblioHtml);
+    const html = await renderArticleHTML(json, BASIC_META, EMPTY_CSS, citationData, biblioHtml);
     expect(html).toMatchSnapshot();
   });
 });

backend/tests/publisher.test.ts

@@ -45,7 +45,7 @@ const EMPTY_CSS = {
 // ── 1.1 Y.Doc Extraction ──────────────────────────────────────────
 
 describe("1.1 Y.Doc extraction", () => {
-  it("1.1.1 extracts frontmatter from Y.Doc", () => {
+  it("1.1.1 extracts frontmatter from Y.Doc", async () => {
     const ydoc = createTestYDoc(FULL_DOC_OPTIONS);
     const metaMap = ydoc.getMap("frontmatter");
 
@@ -63,14 +63,14 @@ describe("1.1 Y.Doc extraction", () => {
     expect((affiliations[0] as any).name).toBe("University of Testing");
   });
 
-  it("1.1.2 empty doc does not throw", () => {
+  it("1.1.2 empty doc does not throw", async () => {
     const ydoc = createTestYDoc({ title: "Empty" });
     const fragment = ydoc.getXmlFragment("default");
     expect(fragment.length).toBe(0);
     expect(ydoc.getMap("frontmatter").get("title")).toBe("Empty");
   });
 
-  it("1.1.3 extracts citations from Y.Map", () => {
+  it("1.1.3 extracts citations from Y.Map", async () => {
     const ydoc = createTestYDoc(FULL_DOC_OPTIONS);
     const citationsMap = ydoc.getMap("citations");
     const entries: Record<string, unknown> = {};
@@ -86,9 +86,9 @@ describe("1.1 Y.Doc extraction", () => {
 // ── 1.2 HTML Generation ───────────────────────────────────────────
 
 describe("1.2 HTML generation", () => {
-  it("1.2.1 produces valid self-contained HTML", () => {
+  it("1.2.1 produces valid self-contained HTML", async () => {
     const meta = buildMeta(FULL_DOC_OPTIONS);
-    const html = renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
 
     expect(html).toContain("<!DOCTYPE html>");
     expect(html).toContain("<html");
@@ -96,22 +96,22 @@ describe("1.2 HTML generation", () => {
     expect(html).toContain("<style>");
   });
 
-  it("1.2.3 generates TOC placeholder", () => {
+  it("1.2.3 generates TOC placeholder", async () => {
     const meta = buildMeta(FULL_DOC_OPTIONS);
-    const html = renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
     expect(html).toContain('aria-label="Table of Contents"');
     expect(html).toContain("toc-placeholder");
   });
 
-  it("1.2.4 includes theme toggle", () => {
+  it("1.2.4 includes theme toggle", async () => {
     const meta = buildMeta(FULL_DOC_OPTIONS);
-    const html = renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
     expect(html).toContain("theme-toggle");
     expect(html).toContain("icon--sun");
     expect(html).toContain("icon--moon");
   });
 
-  it("1.2.5 renders bibliography placeholder", () => {
+  it("1.2.5 renders bibliography placeholder", async () => {
     const docWithBiblio = {
       type: "doc",
       content: [
@@ -120,7 +120,7 @@ describe("1.2 HTML generation", () => {
       ],
     };
     const meta = buildMeta(FULL_DOC_OPTIONS);
-    const html = renderArticleHTML(docWithBiblio, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(docWithBiblio, meta, EMPTY_CSS);
     expect(html).toContain("bibliography");
     expect(html).toContain("Smith 2024");
   });
@@ -134,7 +134,7 @@ describe("1.3 Post-processing", () => {
     date: "2025-01-01",
   };
 
-  it("1.3.1 accordion rendered with data-component attribute", () => {
+  it("1.3.1 accordion rendered with data-component attribute", async () => {
     const docJson = {
       type: "doc",
       content: [
@@ -147,7 +147,7 @@ describe("1.3 Post-processing", () => {
         },
       ],
     };
-    const html = renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
     // The accordion is rendered with data-component="accordion" and data-title attribute
     // Post-processing converts shallow divs to <details>; nested content may prevent the
     // regex from matching. Either way, the accordion data is present in the output.
@@ -155,7 +155,7 @@ describe("1.3 Post-processing", () => {
     expect(html).toContain("Hidden content");
   });
 
-  it("1.3.2 transforms htmlEmbed to iframe", () => {
+  it("1.3.2 transforms htmlEmbed to iframe", async () => {
     const docJson = {
       type: "doc",
       content: [
@@ -165,13 +165,13 @@ describe("1.3 Post-processing", () => {
         },
       ],
     };
-    const html = renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
     // htmlEmbed is rendered as a div with data-component="htmlEmbed" and data-src
     // The post-processor converts it to an iframe
     expect(html).toContain("chart.html");
   });
 
-  it("1.3.3 transforms mermaid to pre block", () => {
+  it("1.3.3 transforms mermaid to pre block", async () => {
     const docJson = {
       type: "doc",
       content: [
@@ -181,7 +181,7 @@ describe("1.3 Post-processing", () => {
         },
       ],
     };
-    const html = renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
+    const html = await renderArticleHTML(docJson, simpleMeta, EMPTY_CSS);
     expect(html).toContain('<pre class="mermaid">');
     expect(html).toContain("graph TD");
   });
@@ -190,10 +190,10 @@ describe("1.3 Post-processing", () => {
 // ── 1.4 Publish idempotency ──────────────────────────────────────
 
 describe("1.4 Publish idempotency", () => {
-  it("1.4.1 rendering twice gives same result", () => {
+  it("1.4.1 rendering twice gives same result", async () => {
     const meta = buildMeta(FULL_DOC_OPTIONS);
-    const html1 = renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
-    const html2 = renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
+    const html1 = await renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
+    const html2 = await renderArticleHTML(MINIMAL_DOC_JSON, meta, EMPTY_CSS);
     expect(html1).toBe(html2);
   });
 });

backend/tests/security.test.ts

@@ -32,40 +32,40 @@ const MINIMAL_JSON = {
 };
 
 describe("4.4 XSS prevention", () => {
-  it("4.4.1 licence field is escaped in published HTML", () => {
+  it("4.4.1 licence field is escaped in published HTML", async () => {
     const meta: PublishMeta = {
       ...BASE_META,
       licence: '<script>alert("xss")</script>',
     };
-    const html = renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
 
     expect(html).not.toContain('<script>alert("xss")</script>');
     expect(html).toContain("&lt;script&gt;");
   });
 
-  it("4.4.2 title is escaped in published HTML", () => {
+  it("4.4.2 title is escaped in published HTML", async () => {
     const meta: PublishMeta = {
       ...BASE_META,
       title: '<img src=x onerror="alert(1)">',
     };
-    const html = renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
 
     expect(html).not.toContain('<img src=x onerror="alert(1)">');
     expect(html).toContain("&lt;img");
   });
 
-  it("4.4.3 description is escaped in meta tags", () => {
+  it("4.4.3 description is escaped in meta tags", async () => {
     const meta: PublishMeta = {
       ...BASE_META,
       description: '"><script>alert(1)</script>',
     };
-    const html = renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
 
     expect(html).not.toContain('"><script>');
     expect(html).toContain("&quot;&gt;&lt;script&gt;");
   });
 
-  it("4.4.4 author names are escaped", () => {
+  it("4.4.4 author names are escaped", async () => {
     const meta: PublishMeta = {
       ...BASE_META,
       authors: [
@@ -76,18 +76,18 @@ describe("4.4 XSS prevention", () => {
         },
       ],
     };
-    const html = renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
 
     expect(html).not.toContain('<script>alert(1)</script>');
     expect(html).toContain("&lt;script&gt;");
   });
 
-  it("4.4.5 DOI is escaped in links", () => {
+  it("4.4.5 DOI is escaped in links", async () => {
     const meta: PublishMeta = {
       ...BASE_META,
       doi: '"><script>alert(1)</script>',
     };
-    const html = renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
+    const html = await renderArticleHTML(MINIMAL_JSON, meta, EMPTY_CSS);
 
     expect(html).not.toContain('"><script>');
   });