@bendyline/squisq-editor-react 1.4.0 → 1.5.0

package/src/tiptapBridge.ts

@@ -11,6 +11,9 @@
  * using squisq's own parser.
  */
 
+import { templateLabel } from './TemplatePicker';
+import { resolveIcon } from '@bendyline/squisq/icons';
+
 // Hoisted regex patterns for inline markdown ↔ HTML conversion
 const RE_BOLD_STAR = /\*\*(.+?)\*\*/g;
 const RE_BOLD_UNDER = /__(.+?)__/g;
@@ -29,6 +32,14 @@ const RE_IMAGE = /!\[(.*?)\]\((.+?)\)/g;
 // remark-stringify may round-trip the colon as `\:` — tolerate either.
 const RE_MENTION = /@\[([^\]]+?)\]\(([a-z][a-z0-9+.-]*)\\?:([^)\s]+)\)/gi;
 const RE_MENTION_TAG = /<span\b[^>]*?\bdata-mention\b[^>]*?>(?:<[^>]+>)*([^<]*)<\/span>/gi;
+
+// Inline FontAwesome icon. Markdown form: `{[github]}` (bare) or
+// `{[fa-solid:user]}` (qualified). HTML form (produced by the
+// `InlineIcon` Tiptap node and consumed back by `htmlToInline`):
+// `<i data-icon="github" data-family="brands" data-name="github"
+//     class="fa-brands fa-github" contenteditable="false"></i>`.
+const RE_ICON_MD = /\{\[([a-zA-Z0-9_:-]+)\]\}/g;
+const RE_ICON_TAG = /<i\b[^>]*?\bdata-icon="([^"]*)"[^>]*?><\/i>/gi;
 const RE_STRONG_TAG = /<strong>(.*?)<\/strong>/g;
 const RE_B_TAG = /<b>(.*?)<\/b>/g;
 const RE_EM_TAG = /<em>(.*?)<\/em>/g;
@@ -183,8 +194,11 @@ export function markdownToTiptap(markdown: string): string {
       let text = headingMatch[2];
       let attrs = '';
 
-      // Extract {[template key=value …]} annotation
-      const annotMatch = text.match(/\s*\{\[([^\]]+)\]\}\s*$/);
+      // Extract {[template key=value …]} annotation. Trailing `[\s\]\}]*`
+      // tolerates accidental doubled `]}` that users type while learning
+      // the syntax — must stay in sync with TEMPLATE_ANNOTATION_RE in
+      // packages/core/src/markdown/convert.ts.
+      const annotMatch = text.match(/\s*\{\[([^\]]+)\]\}[\s\]}]*$/);
       if (annotMatch) {
         text = text.slice(0, annotMatch.index!).trimEnd();
         const tokens = annotMatch[1].trim().split(/\s+/);
@@ -263,6 +277,44 @@ export function markdownToTiptap(markdown: string): string {
       continue;
     }
 
+    // Standalone image — emit as a top-level block `<img>` instead of
+    // wrapping in `<p>`. The Tiptap Image extension is configured with
+    // `inline: false`, so `<p><img></p>` parses to an empty paragraph
+    // (the block image can't live inside the paragraph). That bug
+    // manifested as a broken-image glyph after a markdown → WYSIWYG
+    // round-trip for any dropped/pasted image.
+    const standaloneImageMatch = line.trim().match(/^!\[(.*?)\]\((.+?)\)$/);
+    if (standaloneImageMatch) {
+      flushList();
+      const alt = escapeHtml(standaloneImageMatch[1] ?? '');
+      const src = escapeHtml(standaloneImageMatch[2] ?? '');
+      outputBlocks.push(`<img alt="${alt}" src="${src}">`);
+      continue;
+    }
+
+    // Standalone raw HTML `<img>` line — emitted by `tiptapToMarkdown`
+    // when the user has resized an image (width/height attrs are
+    // serialized as HTML rather than markdown shorthand so the
+    // dimensions survive round-trip). Pass the tag through unchanged
+    // so Tiptap's Image extension parses width/height attributes.
+    const trimmed = line.trim();
+    if (/^<img\b[^>]*>$/i.test(trimmed)) {
+      flushList();
+      outputBlocks.push(trimmed);
+      continue;
+    }
+
+    // Standalone `<video>` / `<audio>` line — emitted by the recorder
+    // (RecorderEntry) when it saves a clip, and by `tiptapToMarkdown`
+    // when the WYSIWYG editor's TiptapVideo/TiptapAudio nodes serialize
+    // back to markdown. Pass through unchanged so the editor's parseHTML
+    // picks up the tag attributes (`src`, `controls`, …).
+    if (/^<(?:video|audio)\b[^>]*>(?:[\s\S]*?<\/(?:video|audio)>)?$/i.test(trimmed)) {
+      flushList();
+      outputBlocks.push(trimmed);
+      continue;
+    }
+
     // Regular paragraph
     flushList();
     outputBlocks.push(`<p>${inlineToHtml(line)}</p>`);
@@ -306,6 +358,15 @@ export function tiptapToMarkdown(html: string): string {
       const tmplMatch = attrs.match(/data-template="([^"]+)"/);
       if (tmplMatch) {
         let annotation = tmplMatch[1];
+        // Defensive: an earlier broken build briefly rendered the
+        // template label as a real text node inside the badge, which
+        // bled the label into the heading's textContent. Strip a
+        // trailing copy of the template's label so existing documents
+        // self-heal on save.
+        const label = templateLabel(annotation);
+        if (label && text.endsWith(label)) {
+          text = text.slice(0, -label.length).trimEnd();
+        }
         const paramsMatch = attrs.match(/data-template-params="([^"]+)"/);
         if (paramsMatch) {
           annotation += ' ' + unescapeHtml(paramsMatch[1]);
@@ -486,13 +547,27 @@ export function tiptapToMarkdown(html: string): string {
       const src = /\bsrc="([^"]*)"/i.exec(attrs)?.[1];
       if (src) {
         const alt = /\balt="([^"]*)"/i.exec(attrs)?.[1] ?? '';
-        lines.push(`![${alt}](${src})`);
+        lines.push(serializeImage(src, alt, attrs));
         lines.push('');
       }
       remaining = remaining.slice(imgMatch[0].length);
       continue;
     }
 
+    // Block-level `<video>` / `<audio>` — emitted by our TiptapVideo /
+    // TiptapAudio atom nodes (block group). Serialize the whole tag
+    // (opening + closing) back to markdown unchanged; CommonMark allows
+    // inline HTML, and our renderer plus the InlinePreviewGutter both
+    // know how to parse the htmlElement back out.
+    const mediaMatch = remaining.match(/^<(video|audio)\b([^>]*)>(?:[\s\S]*?<\/\1>)?/);
+    if (mediaMatch) {
+      const tag = mediaMatch[1] === 'video' ? 'video' : 'audio';
+      lines.push(serializeMediaTag(tag, mediaMatch[2] ?? ''));
+      lines.push('');
+      remaining = remaining.slice(mediaMatch[0].length);
+      continue;
+    }
+
     // Skip unknown tags or whitespace
     const skipMatch = remaining.match(/^(<[^>]+>|\s+)/);
     if (skipMatch) {
@@ -579,6 +654,51 @@ function parseAlignments(separatorLine: string): (string | null)[] {
 
 // ─── Helpers ─────────────────────────────────────────────
 
+/**
+ * Serialize a parsed `<img>` tag back to markdown. When the tag carries
+ * an explicit `width` and/or `height` we emit a raw HTML `<img>` (the
+ * markdown shorthand `![alt](src)` has no syntax for dimensions);
+ * otherwise the friendlier shorthand is used. Markdown allows inline
+ * HTML, so the HTML form parses and renders identically in any
+ * CommonMark/GFM viewer.
+ */
+/**
+ * Serialize a `<video>` or `<audio>` tag (from the Tiptap atom node's
+ * `renderHTML`) back to markdown. We re-emit only the attributes the
+ * recorder + the renderer care about, in a stable order, so the
+ * round-tripped markdown stays deterministic regardless of how Tiptap
+ * decided to order them on its output.
+ */
+function serializeMediaTag(tag: 'video' | 'audio', attrs: string): string {
+  const src = /\bsrc="([^"]*)"/i.exec(attrs)?.[1] ?? '';
+  const controls = /\bcontrols\b/i.test(attrs);
+  const width = /\bwidth="([^"]*)"/i.exec(attrs)?.[1];
+  const height = /\bheight="([^"]*)"/i.exec(attrs)?.[1];
+  const poster = tag === 'video' ? /\bposter="([^"]*)"/i.exec(attrs)?.[1] : undefined;
+  const parts = [`<${tag} src="${src}"`];
+  if (controls) parts.push(' controls');
+  if (width) parts.push(` width="${width}"`);
+  if (height) parts.push(` height="${height}"`);
+  if (poster) parts.push(` poster="${poster}"`);
+  parts.push(`></${tag}>`);
+  return parts.join('');
+}
+
+function serializeImage(src: string, alt: string, attrs: string): string {
+  const width = /\bwidth="([^"]*)"/i.exec(attrs)?.[1];
+  const height = /\bheight="([^"]*)"/i.exec(attrs)?.[1];
+  const title = /\btitle="([^"]*)"/i.exec(attrs)?.[1];
+  if (!width && !height) {
+    return `![${alt}](${src})`;
+  }
+  const parts = [`<img alt="${alt}" src="${src}"`];
+  if (width) parts.push(` width="${width}"`);
+  if (height) parts.push(` height="${height}"`);
+  if (title) parts.push(` title="${title}"`);
+  parts.push('>');
+  return parts.join('');
+}
+
 function escapeHtml(text: string): string {
   return text
     .replace(/&/g, '&amp;')
@@ -597,7 +717,56 @@ function unescapeHtml(text: string): string {
 
 /** Convert inline markdown to HTML for Tiptap consumption */
 function inlineToHtml(text: string): string {
-  let result = escapeHtml(text);
+  // Extract images/mentions/links to opaque placeholders BEFORE running
+  // any inline-formatting regexes. Otherwise `_` characters inside a URL
+  // (e.g. `mikehome_files/IMG_6829.JPEG`) get turned into `<em>` tags by
+  // the underscore-italic rule, mangling the src so the image renders
+  // broken after a markdown ↔ WYSIWYG round-trip.
+  const placeholders: string[] = [];
+  const stash = (html: string): string => {
+    const token = `\u0000PH${placeholders.length}\u0000`;
+    placeholders.push(html);
+    return token;
+  };
+
+  // We run extraction on the RAW text (before escapeHtml) so the
+  // captured groups are the literal markdown contents; then we
+  // selectively escape the parts of each placeholder that need it.
+
+  // Images first: ![alt](src) — must be before links so the `!` prefix is consumed
+  let staged = text.replace(RE_IMAGE, (_m, alt, src) =>
+    stash(`<img alt="${escapeHtml(alt)}" src="${escapeHtml(src)}">`),
+  );
+
+  // Mentions: @[Display](scheme:id) — must run before links so the
+  // bracket+paren isn't consumed as a regular link.
+  staged = staged.replace(RE_MENTION, (_m, label, kind, id) =>
+    stash(
+      `<span data-mention="true" data-kind="${escapeHtml(kind)}" data-id="${escapeHtml(id)}" data-label="${escapeHtml(label)}" class="mention">@${escapeHtml(label)}</span>`,
+    ),
+  );
+
+  // FontAwesome inline icons: {[github]} / {[fa-solid:user]} — resolve
+  // against the FA catalog so unknown / ambiguous tokens stay as
+  // literal text (preserved through escapeHtml later). Stashing here
+  // alongside images/mentions keeps the `_` and other punctuation in
+  // the class attribute from being mangled by the underscore-italic
+  // regex below.
+  staged = staged.replace(RE_ICON_MD, (full, token) => {
+    const icon = resolveIcon(token);
+    if (!icon) return full; // leave literal text — author may have meant it
+    return stash(
+      `<i class="fa-${icon.family} fa-${icon.name}" data-icon="${escapeHtml(token)}" data-family="${icon.family}" data-name="${icon.name}" contenteditable="false"></i>`,
+    );
+  });
+
+  // Links: [text](url) — stash but keep the link text available to
+  // inline formatting by recursing.
+  staged = staged.replace(RE_LINK, (_m, linkText, href) =>
+    stash(`<a href="${escapeHtml(href)}">${inlineToHtml(linkText)}</a>`),
+  );
+
+  let result = escapeHtml(staged);
 
   // Bold: **text** or __text__
   result = result.replace(RE_BOLD_STAR, '<strong>$1</strong>');
@@ -613,21 +782,11 @@ function inlineToHtml(text: string): string {
   // Inline code: `text`
   result = result.replace(RE_INLINE_CODE, '<code>$1</code>');
 
-  // Images first: ![alt](src) — must be before links so the `!` prefix is consumed
-  result = result.replace(RE_IMAGE, '<img alt="$1" src="$2">');
-
-  // Mentions: @[Display](scheme:id) — must run before links so the
-  // bracket+paren isn't consumed as a regular link. The input here has
-  // already been run through escapeHtml at the top of this function, so
-  // the captured groups are safe to interpolate directly.
-  result = result.replace(
-    RE_MENTION,
-    (_match, label, kind, id) =>
-      `<span data-mention="true" data-kind="${kind}" data-id="${id}" data-label="${label}" class="mention">@${label}</span>`,
-  );
-
-  // Links: [text](url)
-  result = result.replace(RE_LINK, '<a href="$2">$1</a>');
+  // Restore placeholders. escapeHtml turned each `\u0000PHn\u0000` into
+  // the same string (the NULs and digits are escape-safe), so the
+  // restoration regex still matches.
+  // eslint-disable-next-line no-control-regex
+  result = result.replace(/\u0000PH(\d+)\u0000/g, (_m, idx) => placeholders[Number(idx)] ?? '');
 
   return result;
 }
@@ -640,6 +799,12 @@ function htmlToInline(html: string): string {
   // spaces + newline) before stripping tags so the newline survives.
   result = result.replace(/<br\s*\/?>/gi, '  \n');
 
+  // FontAwesome inline icons — emit the original token. Must run before
+  // RE_I_TAG (which matches a bare `<i>` and would otherwise eat icon
+  // tags too). The token captured via data-icon already carries the
+  // qualified form when needed, so source round-trips exactly.
+  result = result.replace(RE_ICON_TAG, (_m, token) => `{[${token}]}`);
+
   // Strong
   result = result.replace(RE_STRONG_TAG, '**$1**');
   result = result.replace(RE_B_TAG, '**$1**');
@@ -670,11 +835,14 @@ function htmlToInline(html: string): string {
 
   // Images — order-agnostic attribute parsing (tiptap emits src-first,
   // our markdown-to-html emits alt-first; either must serialize back).
+  // When a width/height is present we serialize as raw HTML `<img>` so
+  // the dimensions survive the round-trip; otherwise the markdown
+  // shorthand `![alt](src)` is used.
   result = result.replace(RE_IMG_TAG, (match, attrs: string) => {
     const src = /\bsrc="([^"]*)"/i.exec(attrs)?.[1];
     if (!src) return match;
     const alt = /\balt="([^"]*)"/i.exec(attrs)?.[1] ?? '';
-    return `![${alt}](${src})`;
+    return serializeImage(src, alt, attrs);
   });
 
   // Strip remaining tags

package/src/useHeadingLayout.ts

@@ -0,0 +1,294 @@
+/**
+ * useHeadingLayout
+ *
+ * Shared positioning hook for the editor gutters (`OutlinePanel` and
+ * `InlinePreviewGutter`). Each gutter needs to know:
+ *   - where every heading sits vertically inside the wrapper
+ *   - where the editor "page" edges sit horizontally
+ *   - how to scroll the editor to a particular heading
+ *
+ * Two backends, picked from `EditorContext.activeView`:
+ *   - **wysiwyg** — query DOM headings inside `.squisq-wysiwyg-container`,
+ *     measure with `getBoundingClientRect`, scroll via `scrollIntoView`.
+ *     Live updates via `ResizeObserver` + `MutationObserver`.
+ *   - **raw** — walk `doc.blocks`, derive each heading's line number from
+ *     `MarkdownHeading.position.start.line`, ask Monaco for the line's
+ *     pixel offset via `getTopForLineNumber`, scroll via
+ *     `revealLineInCenterIfOutsideViewport` + `setPosition`. Live updates
+ *     via `onDidScrollChange` + `onDidChangeModelContent`.
+ *
+ * Both backends produce coordinates in the *wrapper's* reference frame
+ * (i.e., `.squisq-editor-with-gutter`), so the rendering layers — cards,
+ * extent bars, outline rows — don't care which editor is active.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { RefObject } from 'react';
+import type { Block } from '@bendyline/squisq/schemas';
+import { flattenBlocks, hasTemplate } from '@bendyline/squisq/doc';
+import { useEditorContext } from './EditorContext';
+
+export interface HeadingLayoutEntry {
+  /** The block (heading-rooted unit) this entry represents. */
+  block: Block;
+  /** Heading top, in px relative to the wrapper's top edge. */
+  top: number;
+  /** Where this block ends — the next heading's top, or the editor bottom. */
+  bottom: number;
+  /** True when the heading has a recognised template annotation. */
+  annotated: boolean;
+}
+
+export interface HeadingLayout {
+  /** All headings, in document order. */
+  entries: HeadingLayoutEntry[];
+  /** Editor page's left/right edges, in px relative to the wrapper. */
+  pageEdges: { left: number; right: number } | null;
+  /** Scroll the active editor to bring the block's heading into view. */
+  scrollToBlock: (block: Block) => void;
+  /** True once a measurement has produced numbers (avoids flicker on mount). */
+  ready: boolean;
+}
+
+/**
+ * @param refInsideWrapper — any DOM ref under `.squisq-editor-with-gutter`.
+ *        The hook walks up to find the wrapper.
+ */
+export function useHeadingLayout(refInsideWrapper: RefObject<HTMLElement | null>): HeadingLayout {
+  const { doc, activeView, monacoEditor, tiptapEditor } = useEditorContext();
+
+  const flatBlocks = useMemo(() => (doc ? flattenBlocks(doc.blocks) : []), [doc]);
+
+  const [entries, setEntries] = useState<HeadingLayoutEntry[]>([]);
+  const [pageEdges, setPageEdges] = useState<{ left: number; right: number } | null>(null);
+
+  // ── WYSIWYG backend ────────────────────────────────────────────────
+
+  useEffect(() => {
+    if (activeView !== 'wysiwyg') return;
+    const node = refInsideWrapper.current;
+    if (!node) return;
+    const wrapper = findWrapper(node);
+    if (!wrapper) return;
+    const wysiwygContainer = wrapper.querySelector<HTMLElement>('.squisq-wysiwyg-container');
+    if (!wysiwygContainer) return;
+
+    let raf = 0;
+    const recompute = () => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(() => {
+        const headings = Array.from(
+          wysiwygContainer.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6'),
+        );
+        const wrapperRect = wrapper.getBoundingClientRect();
+        const editorRect = wysiwygContainer.getBoundingClientRect();
+        const next: HeadingLayoutEntry[] = [];
+        flatBlocks.forEach((block, i) => {
+          const h = headings[i];
+          if (!h) return;
+          const top = h.getBoundingClientRect().top - wrapperRect.top;
+          const nextH = headings[i + 1];
+          const bottom = nextH
+            ? nextH.getBoundingClientRect().top - wrapperRect.top
+            : editorRect.bottom - wrapperRect.top;
+          next.push({
+            block,
+            top,
+            bottom,
+            annotated: !!h.getAttribute('data-template'),
+          });
+        });
+        setEntries((prev) => (sameEntries(prev, next) ? prev : next));
+
+        // Page edges — anchor to the .squisq-wysiwyg-editor (the centered "page").
+        const page = wysiwygContainer.querySelector<HTMLElement>('.squisq-wysiwyg-editor');
+        if (page) {
+          const pageRect = page.getBoundingClientRect();
+          const left = pageRect.left - wrapperRect.left;
+          const right = pageRect.right - wrapperRect.left;
+          setPageEdges((prev) =>
+            prev != null && Math.abs(prev.left - left) < 0.5 && Math.abs(prev.right - right) < 0.5
+              ? prev
+              : { left, right },
+          );
+        }
+      });
+    };
+
+    recompute();
+    const ro = new ResizeObserver(recompute);
+    ro.observe(wysiwygContainer);
+    const editorSurface = wysiwygContainer.querySelector('.squisq-wysiwyg-editor');
+    if (editorSurface) ro.observe(editorSurface);
+    const mo = new MutationObserver(recompute);
+    mo.observe(wysiwygContainer, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ['data-template', 'data-template-params'],
+    });
+    wysiwygContainer.addEventListener('scroll', recompute, { passive: true });
+    window.addEventListener('resize', recompute);
+    const settle = window.setTimeout(recompute, 250);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      window.clearTimeout(settle);
+      ro.disconnect();
+      mo.disconnect();
+      wysiwygContainer.removeEventListener('scroll', recompute);
+      window.removeEventListener('resize', recompute);
+    };
+  }, [activeView, flatBlocks, refInsideWrapper]);
+
+  // ── Raw (Monaco) backend ───────────────────────────────────────────
+
+  useEffect(() => {
+    if (activeView !== 'raw') return;
+    if (!monacoEditor) return;
+    const node = refInsideWrapper.current;
+    if (!node) return;
+    const wrapper = findWrapper(node);
+    if (!wrapper) return;
+
+    let raf = 0;
+    const recompute = () => {
+      cancelAnimationFrame(raf);
+      raf = requestAnimationFrame(() => {
+        const wrapperRect = wrapper.getBoundingClientRect();
+        const monacoRoot = monacoEditor.getDomNode() as HTMLElement | null;
+        if (!monacoRoot) return;
+        const monacoRect = monacoRoot.getBoundingClientRect();
+        // Y of the editor's content top in wrapper coordinates.
+        const monacoTop = monacoRect.top - wrapperRect.top;
+        const scrollTop = monacoEditor.getScrollTop();
+
+        const layoutInfo = monacoEditor.getLayoutInfo();
+        const next: HeadingLayoutEntry[] = [];
+        flatBlocks.forEach((block, i) => {
+          const line = block.sourceHeading?.position?.start.line;
+          if (typeof line !== 'number') return;
+          const lineTop = monacoEditor.getTopForLineNumber(line) - scrollTop + monacoTop;
+          // Bottom = next block's top, or the visible bottom of the editor.
+          const nextBlock = flatBlocks[i + 1];
+          const nextLine = nextBlock?.sourceHeading?.position?.start.line;
+          const bottom =
+            typeof nextLine === 'number'
+              ? monacoEditor.getTopForLineNumber(nextLine) - scrollTop + monacoTop
+              : monacoTop + layoutInfo.height;
+          const tplName = block.sourceHeading?.templateAnnotation?.template;
+          next.push({
+            block,
+            top: lineTop,
+            bottom,
+            annotated: !!tplName && hasTemplate(tplName),
+          });
+        });
+        setEntries((prev) => (sameEntries(prev, next) ? prev : next));
+
+        // Page edges — Monaco's editor area extends to its container's
+        // box edges; treat the whole editor as the "page".
+        const left = monacoRect.left - wrapperRect.left;
+        const right = monacoRect.right - wrapperRect.left;
+        setPageEdges((prev) =>
+          prev != null && Math.abs(prev.left - left) < 0.5 && Math.abs(prev.right - right) < 0.5
+            ? prev
+            : { left, right },
+        );
+      });
+    };
+
+    recompute();
+    const scrollSub = monacoEditor.onDidScrollChange(recompute);
+    const contentSub = monacoEditor.onDidChangeModelContent(recompute);
+    const layoutSub = monacoEditor.onDidLayoutChange(recompute);
+    const ro = new ResizeObserver(recompute);
+    const monacoRoot = monacoEditor.getDomNode();
+    if (monacoRoot) ro.observe(monacoRoot);
+    window.addEventListener('resize', recompute);
+    const settle = window.setTimeout(recompute, 250);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      window.clearTimeout(settle);
+      scrollSub.dispose();
+      contentSub.dispose();
+      layoutSub.dispose();
+      ro.disconnect();
+      window.removeEventListener('resize', recompute);
+    };
+  }, [activeView, monacoEditor, flatBlocks, refInsideWrapper]);
+
+  // Reset edges when the active view changes — the previous view's
+  // measurements don't carry over to the next.
+  useEffect(() => {
+    setEntries([]);
+    setPageEdges(null);
+  }, [activeView]);
+
+  // ── scrollToBlock ──────────────────────────────────────────────────
+
+  const scrollToBlock = useCallback(
+    (block: Block) => {
+      if (activeView === 'wysiwyg') {
+        const node = refInsideWrapper.current;
+        const wrapper = node ? findWrapper(node) : null;
+        const wysiwygContainer = wrapper?.querySelector<HTMLElement>('.squisq-wysiwyg-container');
+        if (!wysiwygContainer) return;
+        const headings = wysiwygContainer.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6');
+        const index = flatBlocks.findIndex((b) => b.id === block.id);
+        if (index < 0 || index >= headings.length) return;
+        headings[index].scrollIntoView({ behavior: 'smooth', block: 'start' });
+        if (tiptapEditor) {
+          try {
+            tiptapEditor.chain().focus().run();
+          } catch {
+            // ignore
+          }
+        }
+        return;
+      }
+      if (activeView === 'raw' && monacoEditor) {
+        const line = block.sourceHeading?.position?.start.line;
+        if (typeof line !== 'number') return;
+        monacoEditor.revealLineInCenter(line);
+        monacoEditor.setPosition({ lineNumber: line, column: 1 });
+        monacoEditor.focus();
+      }
+    },
+    [activeView, flatBlocks, monacoEditor, refInsideWrapper, tiptapEditor],
+  );
+
+  return {
+    entries,
+    pageEdges,
+    scrollToBlock,
+    ready: entries.length > 0 || pageEdges != null,
+  };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function findWrapper(node: HTMLElement): HTMLElement | null {
+  let cur: HTMLElement | null = node.parentElement;
+  while (cur) {
+    if (cur.classList.contains('squisq-editor-with-gutter')) return cur;
+    cur = cur.parentElement;
+  }
+  // Fallback: immediate parent (during transitional renames).
+  return node.parentElement;
+}
+
+function sameEntries(a: HeadingLayoutEntry[], b: HeadingLayoutEntry[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x.block.id !== y.block.id) return false;
+    if (x.annotated !== y.annotated) return false;
+    if (Math.abs(x.top - y.top) > 0.5) return false;
+    if (Math.abs(x.bottom - y.bottom) > 0.5) return false;
+  }
+  return true;
+}

package/src/utils/collectInlineFontAwesomeCss.ts

@@ -0,0 +1,69 @@
+/**
+ * Collect FontAwesome `@font-face` + utility CSS rules from the host
+ * document's loaded stylesheets so we can inline them into a sandboxed
+ * iframe preview.
+ *
+ * Why: an iframe rendered via `srcDoc` cannot reliably load
+ * FontAwesome from a cross-origin CDN. Tracking prevention, stricter
+ * origin policies, and the iframe's about:srcdoc origin all conspire
+ * to silently drop font fetches. The icons end up invisible even
+ * though the `<i class="fa-…">` tags are present in the markup. The
+ * host page (editor-react ships a bundled `@import` of
+ * `@fortawesome/fontawesome-free`) already has the font loaded and its
+ * woff2 URLs resolve to same-origin assets, so we extract those rules
+ * once and pass them into the renderer as inline CSS.
+ *
+ * Returns `undefined` when no FA rules are found — typical for SSR or
+ * for hosts that don't bundle FA — in which case the renderer falls
+ * back to its cdnjs `<link>` (still works in plain standalone HTML).
+ */
+export function collectInlineFontAwesomeCss(): string | undefined {
+  if (typeof document === 'undefined') return undefined;
+
+  const collected: string[] = [];
+
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList | null = null;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      // Cross-origin stylesheets throw on `.cssRules` access. We can't
+      // read them, but they're also not where editor-react's bundled
+      // FA lives, so it's safe to skip them.
+      continue;
+    }
+    if (!rules) continue;
+
+    for (const rule of Array.from(rules)) {
+      if (isFontAwesomeRule(rule)) {
+        collected.push(rule.cssText);
+      }
+    }
+  }
+
+  return collected.length > 0 ? collected.join('\n') : undefined;
+}
+
+/**
+ * Match `@font-face` declarations whose family starts with
+ * "Font Awesome", plus the FA utility classes (the `.fa-*` rules that
+ * set `content: "\fXXX"` and font-family). The former gets the woff2
+ * loaded into the iframe, the latter wires the `<i>` markup to it.
+ */
+function isFontAwesomeRule(rule: CSSRule): boolean {
+  const text = rule.cssText;
+  // `@font-face { font-family: "Font Awesome 6 Brands"; … }`
+  if (rule.type === CSSRule.FONT_FACE_RULE) {
+    return /font-family:\s*['"]?Font Awesome/i.test(text);
+  }
+  // `.fa-github::before { content: "\f09b"; }` and the base
+  // `.fa-brands { font-family: "Font Awesome 6 Brands"; … }` rules.
+  // FA's stylesheet prefixes selectors with `.fa`, `.fas`, `.far`,
+  // `.fab`, `.fa-solid`, `.fa-regular`, `.fa-brands`. Match the
+  // family name in the declaration block to avoid false positives
+  // (e.g. someone else's `.fa-…` class that doesn't use the font).
+  if (rule.type === CSSRule.STYLE_RULE) {
+    return /Font Awesome/i.test(text) || /content:\s*["']\\[ef]/.test(text);
+  }
+  return false;
+}