fix: align published article with template design

Theme toggle:
- Replace emoji button with SVG sun/moon icons from ThemeToggle.astro
- Fix id mismatch (class="theme-toggle" -> id="theme-toggle")
- Add spin animation and system theme detection

Hero:
- Add .hero-title class to h1 so clamp font-size styles apply

DOM structure:
- Change <article> to <main> in content-grid to match template
selectors (.content-grid main) used across _base.css, _layout.css,
_table.css for typography, figures, references

Component CSS:
- Add styles for note, quoteBlock, sidenote, stack, reference,
wide, fullWidth components (div[data-component="..."])

Code highlighting:
- Load highlight.js runtime + call hljs.highlightAll() for syntax
coloring in published code blocks

Performance:
- Debounce CommentsSidebar position updates and TOC heading extraction

Made-with: Cursor

backend/src/publisher/html-renderer.ts

@@ -29,6 +29,7 @@ export interface PublishMeta {
   affiliations: PublishAffiliation[];
   date: string;
   doi?: string;
+  licence?: string;
   ogImage?: string;
   pdfUrl?: string;
 }
@@ -82,8 +83,10 @@ export function renderArticleHTML(
         integrity="sha384-zh0CIslj3dQfMxK3pZnPJAb3bprHitCE2vBz9TyOTICAn3fso5GYa90qPNMBclov"
         crossorigin="anonymous">
 
-  <!-- highlight.js theme -->
+  <!-- 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>
 
   <!-- Mermaid (renders <pre class="mermaid"> blocks) -->
   <script type="module">
@@ -109,6 +112,106 @@ ${css.print}
 
 /* Publisher-only overrides */
 
+/* Theme toggle icon wrapper (from ThemeToggle.astro) */
+#theme-toggle .icon-wrapper {
+  display: grid;
+  place-items: center;
+  width: 20px;
+  height: 20px;
+}
+#theme-toggle .icon-wrapper .icon {
+  grid-area: 1 / 1;
+  filter: none !important;
+}
+#theme-toggle .icon-wrapper.animated .icon {
+  transition: opacity 0.35s ease;
+}
+#theme-toggle .icon-wrapper.spin-cw { animation: spin-cw 0.5s cubic-bezier(0.4,0,0.2,1); }
+#theme-toggle .icon-wrapper.spin-ccw { animation: spin-ccw 0.5s cubic-bezier(0.4,0,0.2,1); }
+@keyframes spin-cw { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+@keyframes spin-ccw { from { transform: rotate(0deg); } to { transform: rotate(-360deg); } }
+
+/* Note component */
+div[data-component="note"] {
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
+  padding: 1rem 1.25rem;
+  margin: 1em 0;
+  background: var(--surface-bg, rgba(0,0,0,0.02));
+}
+div[data-component="note"][data-variant="warning"] {
+  border-color: #f59e0b;
+  background: rgba(245,158,11,0.06);
+}
+div[data-component="note"][data-variant="danger"] {
+  border-color: #ef4444;
+  background: rgba(239,68,68,0.06);
+}
+div[data-component="note"][data-variant="success"] {
+  border-color: #22c55e;
+  background: rgba(34,197,94,0.06);
+}
+div[data-component="note"] > *:first-child { margin-top: 0; }
+div[data-component="note"] > *:last-child { margin-bottom: 0; }
+
+/* Quote component */
+div[data-component="quoteBlock"] {
+  border-left: 3px solid var(--primary-color, var(--border-color));
+  padding: 1rem 1.25rem;
+  margin: 1.5em 0;
+  font-style: italic;
+  color: var(--muted-color);
+}
+div[data-component="quoteBlock"] > *:first-child { margin-top: 0; }
+div[data-component="quoteBlock"] > *:last-child { margin-bottom: 0; }
+
+/* Sidenote component */
+div[data-component="sidenote"] {
+  font-size: 0.85em;
+  color: var(--muted-color);
+  border-left: 2px solid var(--border-color);
+  padding-left: 0.75rem;
+  margin: 1em 0;
+}
+div[data-component="sidenote"] > *:first-child { margin-top: 0; }
+div[data-component="sidenote"] > *:last-child { margin-bottom: 0; }
+
+/* Reference wrapper */
+div[data-component="reference"] {
+  margin: 1.5em 0;
+}
+div[data-component="reference"] > *:first-child { margin-top: 0; }
+div[data-component="reference"] > *:last-child { margin-bottom: 0; }
+
+/* Stack / multi-column layout */
+div[data-component="stack"] {
+  display: grid;
+  gap: 1rem;
+  margin: 1.5em 0;
+}
+div[data-component="stack"][data-layout="2-column"] { grid-template-columns: 1fr 1fr; }
+div[data-component="stack"][data-layout="3-column"] { grid-template-columns: 1fr 1fr 1fr; }
+div[data-component="stack"][data-layout="4-column"] { grid-template-columns: 1fr 1fr 1fr 1fr; }
+div[data-component="stack"][data-gap="small"] { gap: 0.5rem; }
+div[data-component="stack"][data-gap="large"] { gap: 2rem; }
+div[data-type="stack-column"] { min-width: 0; }
+div[data-type="stack-column"] > *:first-child { margin-top: 0; }
+div[data-type="stack-column"] > *:last-child { margin-bottom: 0; }
+@media (max-width: 640px) {
+  div[data-component="stack"] { grid-template-columns: 1fr !important; }
+}
+
+/* Wide / full-width helpers for published content (if not already from _layout.css) */
+div[data-component="wide"] {
+  width: min(1100px, 100vw - 64px);
+  margin-left: 50%;
+  transform: translateX(-50%);
+}
+div[data-component="fullWidth"] {
+  width: 100vw;
+  margin-left: calc(50% - 50vw);
+}
+
 /* Accordion as details/summary */
 details[data-component="accordion"] {
   border: 1px solid var(--border-color);
@@ -138,6 +241,122 @@ details[data-component="accordion"] > summary::before {
 details[data-component="accordion"][open] > summary::before { transform: rotate(90deg); }
 details[data-component="accordion"] > .accordion-content { padding: 0 1rem 1rem; }
 
+/* Footer */
+.footer {
+  contain: layout style;
+  font-size: 0.8em;
+  line-height: 1.7em;
+  margin-top: 60px;
+  margin-bottom: 0;
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+  color: rgba(0, 0, 0, 0.5);
+}
+
+.footer-inner {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 60px 16px 48px;
+  display: grid;
+  grid-template-columns: 220px minmax(0, 680px) 260px;
+  gap: 32px;
+  align-items: start;
+}
+
+.citation-block,
+.references-block,
+.reuse-block,
+.doi-block {
+  display: contents;
+}
+
+.citation-block > .footer-heading,
+.references-block > .footer-heading,
+.reuse-block > .footer-heading,
+.doi-block > .footer-heading {
+  grid-column: 1;
+  font-size: 15px;
+  font-weight: 600;
+  margin: 0;
+  text-align: right;
+  padding-right: 30px;
+}
+
+.citation-block > :not(.footer-heading),
+.references-block > :not(.footer-heading),
+.reuse-block > :not(.footer-heading),
+.doi-block > :not(.footer-heading) {
+  grid-column: 2;
+}
+
+.citation-block .footer-heading { margin: 0 0 8px; }
+
+.citation-block p,
+.reuse-block p,
+.doi-block p,
+.footnotes ol,
+.footnotes ol p,
+.references { margin-top: 0; }
+
+.citation {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-size: 11px;
+  line-height: 15px;
+  border: 1px solid rgba(0, 0, 0, 0.1);
+  background: rgba(0, 0, 0, 0.02);
+  padding: 10px 18px;
+  border-radius: 3px;
+  color: rgba(150, 150, 150, 1);
+  overflow: hidden;
+  margin-top: -12px;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.citation a { color: rgba(0, 0, 0, 0.6); text-decoration: underline; }
+.citation.short { margin-top: -4px; }
+
+.references-block .footer-heading { margin: 0; }
+.references-block ol { padding: 0 0 0 15px; }
+.references-block li { margin-bottom: 1em; }
+.references-block a { color: var(--text-color); }
+
+.footer a {
+  color: var(--primary-color);
+  border-bottom: 1px solid var(--link-underline);
+  text-decoration: none;
+}
+.footer a:hover {
+  color: var(--primary-color-hover);
+  border-bottom-color: var(--link-underline-hover);
+}
+
+.template-credit { display: contents; }
+.template-credit p {
+  grid-column: 2;
+  margin: 24px 0 0 0;
+  font-size: 0.85em;
+  color: rgba(0, 0, 0, 0.5);
+}
+.template-credit a { color: rgba(0, 0, 0, 0.6); border-bottom: 1px solid rgba(0, 0, 0, 0.15); }
+.template-credit a:hover { color: rgba(0, 0, 0, 0.8); border-bottom-color: rgba(0, 0, 0, 0.3); }
+
+[data-theme="dark"] .footer { border-top-color: rgba(255, 255, 255, 0.15); color: rgba(200, 200, 200, 0.8); }
+[data-theme="dark"] .citation { background: rgba(255, 255, 255, 0.04); border-color: rgba(255, 255, 255, 0.15); color: rgba(200, 200, 200, 1); }
+[data-theme="dark"] .citation a { color: rgba(255, 255, 255, 0.75); }
+[data-theme="dark"] .footer a { color: var(--primary-color); }
+[data-theme="dark"] .template-credit p { color: rgba(200, 200, 200, 0.6); }
+[data-theme="dark"] .template-credit a { color: rgba(200, 200, 200, 0.7); border-bottom-color: rgba(255, 255, 255, 0.2); }
+[data-theme="dark"] .template-credit a:hover { color: rgba(200, 200, 200, 0.9); border-bottom-color: rgba(255, 255, 255, 0.35); }
+
+@media (max-width: 1100px) {
+  .footer-inner { grid-template-columns: 1fr; gap: 16px; display: block; padding: 40px 16px; }
+  .footer-inner > .footer-heading { grid-column: auto; margin-top: 16px; }
+}
+
+@media (min-width: 768px) {
+  .references-block ol { padding: 0 0 0 30px; margin-left: -30px; }
+}
+
 /* PDF download link */
 a.pdf-link {
   display: inline-flex;
@@ -157,7 +376,16 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
   </style>
 </head>
 <body>
-  <button class="theme-toggle" aria-label="Toggle theme" onclick="toggleTheme()">&#127763;</button>
+  <button id="theme-toggle" aria-label="Toggle color theme">
+    <span class="icon-wrapper">
+      <svg class="icon icon--sun" width="20" height="20" viewBox="0 0 24 24" aria-hidden="true" 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 icon--moon" style="opacity:0" width="20" height="20" viewBox="0 0 24 24" aria-hidden="true" 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>
+    </span>
+  </button>
 
   <!-- Mobile TOC toggle -->
   <button class="toc-mobile-toggle" aria-label="Open table of contents" aria-expanded="false">
@@ -180,7 +408,7 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
 
   <!-- Hero -->
   <section class="hero">
-    <h1>${safeTitle}</h1>
+    <h1 class="hero-title">${safeTitle}</h1>
     ${meta.subtitle ? `<p class="hero-desc">${escapeHtml(meta.subtitle)}</p>` : ""}
   </section>
 
@@ -193,13 +421,16 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
       <div id="toc-placeholder"></div>
     </nav>
 
-    <article>
+    <main>
       <div class="tiptap">
         ${enrichedBody}
       </div>
-    </article>
+    </main>
   </section>
 
+  <!-- Footer -->
+  ${renderFooter(meta)}
+
   <!-- Image lightbox -->
   <dialog class="lightbox" id="lightbox">
     <img id="lightbox-img" src="" alt="">
@@ -207,14 +438,44 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
 
   <script>
   (function() {
-    // Theme
-    window.toggleTheme = function() {
-      var next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
-      document.documentElement.setAttribute('data-theme', next);
-      localStorage.setItem('theme', next);
-    };
+    // Theme toggle (matches template ThemeToggle.astro)
+    var btn = document.getElementById('theme-toggle');
+    var sunIcon = btn && btn.querySelector('.icon--sun');
+    var moonIcon = btn && btn.querySelector('.icon--moon');
+    var wrapper = btn && btn.querySelector('.icon-wrapper');
+    var media = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)');
+    var prefersDark = media && media.matches;
     var saved = localStorage.getItem('theme');
-    if (saved) document.documentElement.setAttribute('data-theme', saved);
+
+    function applyTheme(mode) {
+      document.documentElement.dataset.theme = mode;
+      if (sunIcon && moonIcon) {
+        sunIcon.style.opacity = mode === 'dark' ? '0' : '1';
+        moonIcon.style.opacity = mode === 'dark' ? '1' : '0';
+      }
+    }
+    applyTheme(saved || (prefersDark ? 'dark' : 'light'));
+    requestAnimationFrame(function() { if (wrapper) wrapper.classList.add('animated'); });
+
+    if (!saved && media) {
+      var syncSystem = function(e) { applyTheme(e.matches ? 'dark' : 'light'); };
+      if (media.addEventListener) media.addEventListener('change', syncSystem);
+    }
+
+    if (btn) {
+      btn.addEventListener('click', function() {
+        var next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+        localStorage.setItem('theme', next);
+        if (wrapper) {
+          var cls = next === 'dark' ? 'spin-cw' : 'spin-ccw';
+          wrapper.classList.remove('spin-cw', 'spin-ccw');
+          void wrapper.offsetWidth;
+          wrapper.classList.add(cls);
+          wrapper.addEventListener('animationend', function() { wrapper.classList.remove(cls); }, { once: true });
+        }
+        applyTheme(next);
+      });
+    }
 
     // Lightbox
     document.querySelectorAll('.tiptap img').forEach(function(img) {
@@ -232,7 +493,7 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
     // ---- Table of Contents ----
     var holder = document.getElementById('toc-placeholder');
     var holderMobile = document.getElementById('toc-mobile-placeholder');
-    var articleRoot = document.querySelector('.content-grid article');
+    var articleRoot = document.querySelector('.content-grid main');
     if (!articleRoot) return;
     var headings = articleRoot.querySelectorAll('h2, h3, h4');
     if (!headings.length) return;
@@ -425,6 +686,67 @@ dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; bo
     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(); });
 
+    // ---- Footer: move references & footnotes ----
+    (function() {
+      var footer = document.querySelector('footer.footer');
+      if (!footer) return;
+      var target = footer.querySelector('.references-block');
+      if (!target) return;
+      var contentRoot = document.querySelector('.content-grid main') || document.body;
+
+      var ensureHeading = function(text) {
+        var exists = Array.from(target.children).some(function(c) {
+          return c.classList.contains('footer-heading') && c.textContent.trim().toLowerCase() === text.toLowerCase();
+        });
+        if (!exists) {
+          var h = document.createElement('p');
+          h.className = 'footer-heading';
+          h.setAttribute('role', 'heading');
+          h.setAttribute('aria-level', '2');
+          h.textContent = text;
+          target.appendChild(h);
+        }
+      };
+
+      var moveIntoFooter = function(el, headingText) {
+        if (!el) return false;
+        var firstH = el.querySelector(':scope > h1, :scope > h2, :scope > h3, :scope > .footer-heading, :scope > .bibliography-title');
+        if (firstH) {
+          var t = (firstH.textContent || '').trim().toLowerCase();
+          if (t === headingText.toLowerCase() || t.includes('reference') || t.includes('bibliograph')) firstH.remove();
+        }
+        ensureHeading(headingText);
+        target.appendChild(el);
+        return true;
+      };
+
+      var findAllOutsideFooter = function(selectors) {
+        var results = [];
+        for (var i = 0; i < selectors.length; i++) {
+          var els = contentRoot.querySelectorAll(selectors[i]);
+          els.forEach(function(el) { if (!footer.contains(el) && results.indexOf(el) === -1) results.push(el); });
+        }
+        return results;
+      };
+
+      var findFirst = function(selectors) { var a = findAllOutsideFooter(selectors); return a.length ? a[0] : null; };
+
+      var run = function() {
+        if (footer.dataset.processed === 'true') return;
+        var refs = findAllOutsideFooter(['[data-type="bibliography"]', '#bibliography-references-list', '#references', '#refs', '.bibliography']);
+        var notes = findFirst(['.footnotes', 'section.footnotes', 'div.footnotes']);
+        var moved = false;
+        refs.forEach(function(el) { if (moveIntoFooter(el, 'References')) moved = true; });
+        if (moveIntoFooter(notes, 'Footnotes')) moved = true;
+        if (moved) footer.dataset.processed = 'true';
+      };
+
+      run();
+      if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', run, { once: true });
+      window.addEventListener('load', function() { setTimeout(run, 100); }, { once: true });
+      setTimeout(run, 300);
+    })();
+
     // Hash navigation
     if (window.location.hash) {
       var target = document.querySelector(window.location.hash);
@@ -600,3 +922,89 @@ function formatDate(dateStr: string): string {
     return dateStr;
   }
 }
+
+function extractYear(dateStr?: string): number | undefined {
+  if (!dateStr) return undefined;
+  const d = new Date(dateStr);
+  if (!Number.isNaN(d.getTime())) return d.getFullYear();
+  const m = dateStr.match(/(19|20)\d{2}/);
+  return m ? Number(m[0]) : undefined;
+}
+
+function buildCitationText(meta: PublishMeta): string {
+  const authorNames = meta.authors.map((a) => a.name);
+  const authorsStr = authorNames.join(", ");
+  const year = extractYear(meta.date);
+  const title = meta.title.replace(/\s+/g, " ").trim();
+  return `${authorsStr}${year ? ` (${year})` : ""}. "${title}".`;
+}
+
+function buildBibtex(meta: PublishMeta): string {
+  const authorNames = meta.authors.map((a) => a.name);
+  const authorsBib = authorNames.join(" and ");
+  const title = meta.title.replace(/\s+/g, " ").trim();
+  const year = extractYear(meta.date);
+  const keyAuthor = (authorNames[0] || "article")
+    .split(/\s+/)
+    .slice(-1)[0]
+    .toLowerCase();
+  const keyTitle = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+  const bibKey = `${keyAuthor}${year ?? ""}_${keyTitle}`;
+  const parts = [
+    `  title={${title}}`,
+    `  author={${authorsBib}}`,
+  ];
+  if (year) parts.push(`  year={${year}}`);
+  if (meta.doi) parts.push(`  doi={${meta.doi}}`);
+  return `@misc{${bibKey},\n${parts.join(",\n")}\n}`;
+}
+
+function renderFooter(meta: PublishMeta): string {
+  const citationText = buildCitationText(meta);
+  const bibtex = buildBibtex(meta);
+
+  let sections = "";
+
+  // Citation block
+  sections += `
+    <section class="citation-block">
+      <p class="footer-heading" role="heading" aria-level="2">Citation</p>
+      <p>For attribution in academic contexts, please cite this work as</p>
+      <pre class="citation short">${escapeHtml(citationText)}</pre>
+      <p>BibTeX citation</p>
+      <pre class="citation long">${escapeHtml(bibtex)}</pre>
+    </section>`;
+
+  // DOI block
+  if (meta.doi) {
+    sections += `
+    <section class="doi-block">
+      <p class="footer-heading" role="heading" aria-level="2">DOI</p>
+      <p><a href="https://doi.org/${escapeHtml(meta.doi)}" target="_blank" rel="noopener noreferrer">${escapeHtml(meta.doi)}</a></p>
+    </section>`;
+  }
+
+  // Licence / Reuse block
+  if (meta.licence) {
+    sections += `
+    <section class="reuse-block">
+      <p class="footer-heading" role="heading" aria-level="2">Reuse</p>
+      <p>${meta.licence}</p>
+    </section>`;
+  }
+
+  // References placeholder (JS will move bibliography + footnotes here)
+  sections += `
+    <section class="references-block"></section>`;
+
+  // Template credit
+  sections += `
+    <div class="template-credit">
+      <p>Made with &#10084;&#65039; with <a href="https://huggingface.co/spaces/tfrere/research-article-template" target="_blank" rel="noopener noreferrer">research article template</a></p>
+    </div>`;
+
+  return `<footer class="footer"><div class="footer-inner">${sections}</div></footer>`;
+}

backend/src/publisher/index.ts

@@ -236,6 +236,7 @@ export async function publishDocument(docName: string, token?: string): Promise<
     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

frontend/src/components/CommentsSidebar.tsx

@@ -86,22 +86,29 @@ export function CommentsSidebar({ editor, commentStore, user, editorContainer }:
     setPositioned(result);
   }, [editor, editorContainer, comments]);
 
+  const posTimerRef = useRef(0);
+
   useEffect(() => {
     updatePositions();
 
-    const onScroll = () => updatePositions();
+    const debouncedPositions = () => {
+      clearTimeout(posTimerRef.current);
+      posTimerRef.current = window.setTimeout(updatePositions, 200);
+    };
+
     const editorEl = editor?.view?.dom;
     const scrollTarget = editorContainer;
 
     if (editorEl) {
       if (scrollTarget) {
-        scrollTarget.addEventListener("scroll", onScroll, { passive: true });
+        scrollTarget.addEventListener("scroll", debouncedPositions, { passive: true });
       }
-      const observer = new MutationObserver(updatePositions);
+      const observer = new MutationObserver(debouncedPositions);
       observer.observe(editorEl, { childList: true, subtree: true, characterData: true });
       return () => {
-        scrollTarget?.removeEventListener("scroll", onScroll);
+        scrollTarget?.removeEventListener("scroll", debouncedPositions);
         observer.disconnect();
+        clearTimeout(posTimerRef.current);
       };
     }
   }, [editor, editorContainer, updatePositions]);

frontend/src/components/TableOfContents.tsx

@@ -60,12 +60,23 @@ export function TableOfContents({ editor }: TableOfContentsProps) {
   const [activePos, setActivePos] = useState<number | null>(null);
   const rafRef = useRef(0);
 
+  const debounceRef = useRef(0);
+
   useEffect(() => {
     if (!editor) return;
-    const update = () => setHeadings(extractHeadings(editor));
-    update();
-    editor.on("update", update);
-    return () => { editor.off("update", update); };
+    setHeadings(extractHeadings(editor));
+    const debouncedUpdate = () => {
+      clearTimeout(debounceRef.current);
+      debounceRef.current = window.setTimeout(
+        () => setHeadings(extractHeadings(editor)),
+        300,
+      );
+    };
+    editor.on("update", debouncedUpdate);
+    return () => {
+      editor.off("update", debouncedUpdate);
+      clearTimeout(debounceRef.current);
+    };
   }, [editor]);
 
   useEffect(() => {