@elabs-ai/components-editor 4.0.0

package/src/markdown-academic/citations.tsx

@@ -0,0 +1,442 @@
+"use client";
+
+/**
+ * Citations — Pandoc / Better-BibTeX keys (`[@smith2020]`) resolved through a
+ * consumer hook (`resolveCitation(key) => CitationData | null`).
+ *
+ * The library NEVER owns the bibliography database or CSL formatting — that lives
+ * in the app (pass `formatted` for a citeproc-rendered reference, or the lightweight
+ * `author`/`year`/`title` bits for the built-in assembler). The library renders:
+ * inline cites (numeric `[1]` or author-year `(Smith 2020)`) and a generated
+ * bibliography, with consistent numbering shared between them.
+ *
+ * `[@key]` stays a plain text node in mdast (it is NOT markdown link syntax), so a
+ * text-node transform (`remarkBrandCitations`) rewrites the spans — the same shape
+ * as the wikilink resolver. Numbering is owned by `collectCitations` (a single
+ * pre-pass over the source) so an inline `[1]` and bibliography entry 1 always agree.
+ */
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { Separator } from "@elabs-ai/components-ui";
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useId,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import { visit } from "unist-util-visit";
+
+/* ------------------------------------------------------------------ */
+/* Public contract                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Resolved citation data, returned by the consumer's `resolveCitation` hook.
+ * Provide `formatted` (your CSL/citeproc output) for a verbatim bibliography
+ * entry; otherwise the built-in assembler uses `author` / `year` / `title` /
+ * `container`. The library does NOT format CSL.
+ */
+export interface CitationData {
+  /** The citation key (echoed back; optional). */
+  key?: string;
+  /** Inline author label for author-year + bibliography lead (e.g. `"Smith et al."`). */
+  author?: string;
+  /** Publication year. */
+  year?: string | number;
+  /** Work title. */
+  title?: string;
+  /** Container — journal, book, publisher, or site. */
+  container?: string;
+  /** Canonical URL (the bibliography link). */
+  url?: string;
+  /** DOI — linked as `https://doi.org/<doi>` when no `url` is given. */
+  doi?: string;
+  /** Fully-formatted reference (app's CSL output) — rendered verbatim when set. */
+  formatted?: string;
+}
+
+/** Consumer hook: citation key → data, or `null` when unknown (renders `[?]`). */
+export type ResolveCitation = (key: string) => CitationData | null;
+
+/** Inline citation rendering style. */
+export type CitationStyle = "numeric" | "author-year";
+
+/** One resolved citation with its assigned number (numbers skip unresolved keys). */
+export interface ResolvedCitation {
+  key: string;
+  /** 1-based number (numeric style + bibliography); `undefined` when unresolved. */
+  n?: number;
+  data: CitationData | null;
+}
+
+/** A single `@key` reference inside a citation bracket. */
+export interface CiteItem {
+  key: string;
+  /** Locator text after the key, e.g. `"p. 5"`. */
+  locator?: string;
+  /** `-@key` → suppress the author in author-year style. */
+  suppressAuthor?: boolean;
+  /** Prose before the key, e.g. `"see"`. */
+  prefix?: string;
+}
+
+/* ------------------------------------------------------------------ */
+/* Parsing (shared by the transform AND the numbering pre-pass)         */
+/* ------------------------------------------------------------------ */
+
+// A key char-class wide enough for Better-BibTeX / CSL keys without swallowing
+// trailing punctuation: letters, digits, and `_:.#$%&+?<>~/-` (no whitespace).
+const ITEM_RE = /^\s*([^@]*?)\s*(-)?@([\p{L}\d][\w:.#$%&+?<>~/-]*)\s*(.*)$/u;
+
+/** Parse one `;`-separated cite item; `null` if it has no `@key`. */
+function parseItem(raw: string): CiteItem | null {
+  const m = ITEM_RE.exec(raw);
+  if (!m) return null;
+  const [, prefix, suppress, key, rest] = m;
+  if (!key) return null;
+  const locator = (rest ?? "").replace(/^\s*,\s*/, "").trim();
+  const item: CiteItem = { key };
+  if (suppress) item.suppressAuthor = true;
+  if (prefix?.trim()) item.prefix = prefix.trim();
+  if (locator) item.locator = locator;
+  return item;
+}
+
+/**
+ * Parse a bracket's inner text into cite items, or `null` if it is not a citation
+ * (no `@key` token) — so ordinary `[bracketed]` prose is left untouched.
+ */
+export function parseCitationBracket(inner: string): CiteItem[] | null {
+  if (!inner.includes("@")) return null;
+  const items: CiteItem[] = [];
+  for (const part of inner.split(";")) {
+    const item = parseItem(part);
+    if (!item) return null; // every `;`-part must be a valid cite, else it's prose
+    items.push(item);
+  }
+  return items.length > 0 ? items : null;
+}
+
+// Find candidate citation brackets in a text node. Excludes a preceding `]` or `!`
+// (reference-link / image syntax) and a following `(`/`[` (inline / reference link).
+const BRACKET_RE = /(?<![\]!])\[([^[\]]+)\](?![([])/g;
+
+/* ------------------------------------------------------------------ */
+/* collectCitations — the single numbering authority                    */
+/* ------------------------------------------------------------------ */
+
+export interface CollectedCitations {
+  /** Resolved citations in first-appearance order (the bibliography list). */
+  order: ResolvedCitation[];
+  /** Lookup by key — both resolved and unresolved keys. */
+  byKey: Map<string, ResolvedCitation>;
+}
+
+/**
+ * Scan the markdown body once, in document order, resolving each unique citation
+ * key and numbering the resolved ones. The inline transform stays numbering-free
+ * and reads back from `byKey`, so inline `[1]` and bibliography entry 1 agree.
+ */
+export function collectCitations(markdown: string, resolve: ResolveCitation): CollectedCitations {
+  const byKey = new Map<string, ResolvedCitation>();
+  const order: ResolvedCitation[] = [];
+  let m: RegExpExecArray | null;
+  BRACKET_RE.lastIndex = 0;
+  while ((m = BRACKET_RE.exec(markdown)) !== null) {
+    const items = parseCitationBracket(m[1]!);
+    if (!items) continue;
+    for (const { key } of items) {
+      if (byKey.has(key)) continue;
+      const data = resolve(key);
+      const entry: ResolvedCitation = { key, data };
+      if (data) {
+        entry.n = order.length + 1;
+        order.push(entry);
+      }
+      byKey.set(key, entry);
+    }
+  }
+  return { order, byKey };
+}
+
+/* ------------------------------------------------------------------ */
+/* remark transform: `[@key]` → <brand-cite>                            */
+/* ------------------------------------------------------------------ */
+
+export const CITE_TAG = "brand-cite";
+export const CITE_PROP = "dataCite";
+const CITE_ATTR = "data-cite";
+
+interface CitePayload {
+  items: CiteItem[];
+  /** Original bracket text, for the graceful all-unresolved fallback. */
+  original: string;
+}
+
+interface MdTextNode {
+  type: string;
+  value?: string;
+}
+
+/** Rewrite `[@key]` citation spans in text nodes into `<brand-cite>` elements. */
+export function remarkBrandCitations() {
+  return (tree: unknown) => {
+    visit(tree as never, "text", (node: MdTextNode, index: number | undefined, parent) => {
+      const p = parent as { children?: unknown[] } | undefined;
+      const text = node.value;
+      if (!p?.children || index == null || typeof text !== "string" || !text.includes("@")) return;
+
+      const next: unknown[] = [];
+      let last = 0;
+      BRACKET_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = BRACKET_RE.exec(text)) !== null) {
+        const items = parseCitationBracket(m[1]!);
+        if (!items) continue;
+        if (m.index > last) next.push({ type: "text", value: text.slice(last, m.index) });
+        const payload: CitePayload = { items, original: m[0] };
+        next.push({
+          type: "brandCite",
+          data: { hName: CITE_TAG, hProperties: { [CITE_PROP]: JSON.stringify(payload) } },
+        });
+        last = m.index + m[0].length;
+      }
+      if (next.length === 0) return;
+      if (last < text.length) next.push({ type: "text", value: text.slice(last) });
+      p.children.splice(index, 1, ...next);
+      return index + next.length;
+    });
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Context (numbering shared by inline cites + bibliography)            */
+/* ------------------------------------------------------------------ */
+
+interface CitationState {
+  byKey: Map<string, ResolvedCitation>;
+  order: ResolvedCitation[];
+  style: CitationStyle;
+}
+
+const CitationContext = createContext<CitationState | null>(null);
+
+export interface CitationProviderProps extends CollectedCitations {
+  style: CitationStyle;
+  children: ReactNode;
+}
+
+export function CitationProvider({ byKey, order, style, children }: CitationProviderProps) {
+  return (
+    <CitationContext.Provider value={{ byKey, order, style }}>{children}</CitationContext.Provider>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* Rendering helpers                                                    */
+/* ------------------------------------------------------------------ */
+
+function hoverTitle(data: CitationData): string {
+  if (data.formatted) return data.formatted;
+  const parts = [
+    data.author,
+    data.year != null ? `(${data.year})` : undefined,
+    data.title,
+    data.container,
+  ].filter(Boolean);
+  return parts.join(". ");
+}
+
+function CiteLink({ entry, label }: { entry: ResolvedCitation; label: string }) {
+  // For numeric style the visible label is a bare "[1]" — give AT a real name
+  // (the `title` tooltip is for mouse users and is not reliably announced).
+  const name = entry.data ? hoverTitle(entry.data) : entry.key;
+  return (
+    <a
+      href={`#ref-${cssId(entry.key)}`}
+      title={entry.data ? hoverTitle(entry.data) : undefined}
+      aria-label={`Citation: ${name}`}
+      // #317/#399 — the on-surface `-text` rung, NOT the `--primary` FILL: an
+      // inline cite is body text inside a paragraph and owes WCAG 1.4.3 AA
+      // (4.5:1), which `--primary` missed at 4.29-4.31:1 in light. The
+      // resting `underline` is the separate 1.4.1 non-colour cue (#317's
+      // link-in-text-block half) — keep both.
+      className="text-primary-text underline hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      {label}
+    </a>
+  );
+}
+
+/** Make a citation key safe for use in an element id / fragment. */
+function cssId(key: string): string {
+  return key.replace(/[^\w-]/g, "-");
+}
+
+/* ------------------------------------------------------------------ */
+/* InlineCite — the <brand-cite> renderer                               */
+/* ------------------------------------------------------------------ */
+
+type TagProps = { node?: unknown; children?: ReactNode } & Record<string, unknown>;
+
+function readCite(rest: TagProps): CitePayload | null {
+  const raw = (rest[CITE_ATTR] as string | undefined) ?? (rest[CITE_PROP] as string | undefined);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as CitePayload;
+  } catch {
+    return null;
+  }
+}
+
+/** Renderer for the inline `<brand-cite>` element produced by the transform. */
+export function InlineCite({ node: _n, children: _c, ...rest }: TagProps) {
+  const ctx = useContext(CitationContext);
+  const payload = readCite(rest);
+  if (!payload) return null;
+  if (!ctx) return <span>{payload.original}</span>;
+
+  const resolved = payload.items.map((it) => ({ it, entry: ctx.byKey.get(it.key) }));
+  const anyResolved = resolved.some((r) => r.entry?.data);
+  if (!anyResolved) {
+    // Graceful: nothing resolved → keep the literal, marked for sighted + AT.
+    return (
+      <span className="text-muted-foreground" title="Unresolved citation">
+        {payload.original}
+      </span>
+    );
+  }
+
+  const numeric = ctx.style === "numeric";
+  const open = numeric ? "[" : "(";
+  const close = numeric ? "]" : ")";
+  const sep = numeric ? ", " : "; ";
+
+  return (
+    <span className="whitespace-nowrap text-meta tabular-nums">
+      {open}
+      {resolved.map(({ it, entry }, i) => {
+        const label = numeric ? numericLabel(it, entry) : authorYearLabel(it, entry);
+        return (
+          <span key={`${it.key}-${i}`}>
+            {i > 0 ? sep : null}
+            {entry?.data ? (
+              <CiteLink entry={entry} label={label} />
+            ) : (
+              <span className="text-muted-foreground" title={`Unresolved: @${it.key}`}>
+                {label}
+              </span>
+            )}
+          </span>
+        );
+      })}
+      {close}
+    </span>
+  );
+}
+
+function numericLabel(it: CiteItem, entry?: ResolvedCitation): string {
+  if (!entry?.data || entry.n == null) return "?";
+  return it.locator ? `${entry.n}, ${it.locator}` : String(entry.n);
+}
+
+function authorYearLabel(it: CiteItem, entry?: ResolvedCitation): string {
+  if (!entry?.data) return `@${it.key}?`;
+  const d = entry.data;
+  const head = it.suppressAuthor ? "" : d.author ? `${d.author} ` : "";
+  const year = d.year != null ? String(d.year) : "";
+  const core = `${head}${year}`.trim() || d.title || it.key;
+  const prefixed = it.prefix ? `${it.prefix} ${core}` : core;
+  return it.locator ? `${prefixed}, ${it.locator}` : prefixed;
+}
+
+/* ------------------------------------------------------------------ */
+/* Bibliography                                                         */
+/* ------------------------------------------------------------------ */
+
+function assembledReference(data: CitationData): string {
+  if (data.formatted) return data.formatted;
+  const parts = [
+    data.author,
+    data.year != null ? `(${data.year}).` : undefined,
+    data.title ? `${data.title}.` : undefined,
+    data.container ? `${data.container}.` : undefined,
+  ].filter(Boolean);
+  return parts.join(" ");
+}
+
+function referenceHref(data: CitationData): string | undefined {
+  if (data.url) return data.url;
+  if (data.doi) return `https://doi.org/${data.doi}`;
+  return undefined;
+}
+
+export interface BibliographyProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "style"> {
+  /** Resolved citations; defaults to the citations collected by `MarkdownPreview`. */
+  entries?: ResolvedCitation[];
+  /** Numbering style; defaults to the preview's `citationStyle`. */
+  style?: CitationStyle;
+  /** Section heading label. Default `"References"`. */
+  title?: string;
+}
+
+/**
+ * The generated reference list. Reads the preview's collected citations by default
+ * (the `::bibliography` block), or accepts an explicit `entries` array standalone.
+ * One focal separation gesture — a top `Separator` — over a quiet label + list.
+ */
+export const Bibliography = forwardRef<HTMLElement, BibliographyProps>(function Bibliography(
+  { entries, style, title = "References", className, ...props },
+  ref,
+) {
+  const ctx = useContext(CitationContext);
+  const labelId = useId();
+  const list = entries ?? ctx?.order ?? [];
+  const resolvedStyle = style ?? ctx?.style ?? "numeric";
+  const numeric = resolvedStyle === "numeric";
+
+  if (list.length === 0) return null;
+
+  return (
+    <section ref={ref} aria-labelledby={labelId} className={cn("mt-8", className)} {...props}>
+      <Separator className="mb-3" />
+      <p id={labelId} className="mb-2 text-meta font-medium text-muted-foreground">
+        {title}
+      </p>
+      <ol className="space-y-2">
+        {list.map((entry) => {
+          const data = entry.data;
+          if (!data) return null;
+          const href = referenceHref(data);
+          return (
+            <li
+              key={entry.key}
+              id={`ref-${cssId(entry.key)}`}
+              className="flex gap-2 text-caption text-foreground scroll-mt-4"
+            >
+              {numeric && entry.n != null ? (
+                <span className="shrink-0 tabular-nums text-muted-foreground">[{entry.n}]</span>
+              ) : null}
+              <span className="min-w-0">
+                {assembledReference(data)}{" "}
+                {href ? (
+                  <a
+                    href={href}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    // #317/#399 — bibliography DOI/URL is body text: `-text` rung
+                    // + resting underline (the non-colour cue).
+                    className="break-words text-primary-text underline underline-offset-2 hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {data.url ?? `doi:${data.doi}`}
+                  </a>
+                ) : null}
+              </span>
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  );
+});

package/src/markdown-academic/footnotes.tsx

@@ -0,0 +1,235 @@
+"use client";
+
+/**
+ * Branded GFM footnotes (`[^1]` … `[^1]: definition`).
+ *
+ * GFM footnotes already PARSE (remark-gfm is always on), but Streamdown's default
+ * hast handlers render them with broken in-page anchors (a doubled `user-content-`
+ * id prefix so ref/backref hrefs don't resolve) and `target="_blank"` on what are
+ * same-page jumps. So we OWN the render: `remarkBrandFootnotes` rewrites the
+ * `footnoteReference` / `footnoteDefinition` mdast nodes into our own `brand-*`
+ * elements BEFORE mdast→hast runs, giving consistent ids, real same-page links,
+ * and quiet branded chrome.
+ *
+ * Why replace the node TYPE (not just set `data.hName`): mdast-util-to-hast has
+ * built-in handlers for `footnoteReference` / `footnoteDefinition` that ignore
+ * `data.hName`. Only a node type with NO handler falls through to the unknown
+ * handler, which honors `hName` / `hProperties`. So we swap in fresh custom-typed
+ * nodes — and we keep every `id`/`href` on our React output (post-sanitization),
+ * never on raw hast the sanitizer could strip.
+ */
+import { Separator } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { forwardRef, useId, type HTMLAttributes, type ReactNode } from "react";
+import { visit } from "unist-util-visit";
+
+/** Inline footnote marker (`<sup><a>…</a></sup>`). */
+export const FOOTNOTE_REF_TAG = "brand-footnote-ref";
+/** The branded footnote-definition section appended at document end. */
+export const FOOTNOTE_LIST_TAG = "brand-footnote-list";
+/** A single footnote definition row (`<li>` + backref). */
+export const FOOTNOTE_ITEM_TAG = "brand-footnote-item";
+/** hast property carrying the JSON payload (rendered as `data-fn`). */
+export const FOOTNOTE_PROP = "dataFn";
+const FOOTNOTE_ATTR = "data-fn";
+
+interface FootnotePayload {
+  /** Footnote identifier (the `1` / `longname` in `[^1]`). */
+  id: string;
+  /** Display number, assigned in first-reference order. */
+  n: number;
+  /** Unique element id for this reference occurrence (the backref target). */
+  refId?: string;
+  /** All reference element ids for this footnote — one back-ref per occurrence. */
+  refs?: string[];
+}
+
+/* ------------------------------------------------------------------ */
+/* remark transform                                                     */
+/* ------------------------------------------------------------------ */
+
+interface MdNode {
+  type: string;
+  identifier?: string;
+  value?: string;
+  children?: MdNode[];
+  data?: { hName?: string; hProperties?: Record<string, unknown> };
+}
+
+function payloadProps(payload: FootnotePayload) {
+  return { [FOOTNOTE_PROP]: JSON.stringify(payload) };
+}
+
+/**
+ * Rewrite footnote refs + definitions into branded elements. Numbering follows
+ * first-reference order (GFM behavior); repeated references reuse the number but
+ * get a unique element id. Unreferenced definitions are dropped (also GFM).
+ */
+export function remarkBrandFootnotes() {
+  return (tree: unknown) => {
+    const root = tree as MdNode;
+
+    // Pass 1 — collect definitions (and remove them; re-emitted at the end).
+    const defs = new Map<string, MdNode>();
+    visit(
+      root as never,
+      "footnoteDefinition",
+      (node: MdNode, index, parent: MdNode | undefined) => {
+        if (!node.identifier || !parent?.children || index == null) return;
+        defs.set(node.identifier, node);
+        parent.children.splice(index, 1);
+        return index; // re-visit the now-shifted index
+      },
+    );
+
+    // Pass 2 — number references in document order + replace with branded refs.
+    const numberOf = new Map<string, number>();
+    const refsOf = new Map<string, string[]>();
+    const order: string[] = [];
+    visit(root as never, "footnoteReference", (node: MdNode, index, parent: MdNode | undefined) => {
+      if (!node.identifier || !parent?.children || index == null) return;
+      const id = node.identifier;
+      let n = numberOf.get(id);
+      if (n == null) {
+        n = order.length + 1;
+        numberOf.set(id, n);
+        order.push(id);
+      }
+      const refs = refsOf.get(id) ?? [];
+      const refId = refs.length === 0 ? `fnref-${id}` : `fnref-${id}-${refs.length + 1}`;
+      refs.push(refId);
+      refsOf.set(id, refs);
+      parent.children[index] = {
+        type: "brandFootnoteRef",
+        data: { hName: FOOTNOTE_REF_TAG, hProperties: payloadProps({ id, n, refId }) },
+      };
+    });
+
+    if (order.length === 0) return;
+
+    // Pass 3 — emit the branded definition section at the document end. Each item
+    // is a custom element; the definition BODY stays real mdast (rendered + safely
+    // sanitized as normal prose), while every id/anchor lives on our React output.
+    // Carry every occurrence's ref id so the item renders one back-ref per mention.
+    const items: MdNode[] = order.map((id, i) => {
+      const def = defs.get(id);
+      const body: MdNode[] = def?.children
+        ? def.children.map((c) => structuredClone(c))
+        : [{ type: "paragraph", children: [{ type: "text", value: "Missing footnote." }] }];
+      return {
+        type: "brandFootnoteItem",
+        data: {
+          hName: FOOTNOTE_ITEM_TAG,
+          hProperties: payloadProps({ id, n: i + 1, refs: refsOf.get(id) ?? [`fnref-${id}`] }),
+        },
+        children: body,
+      };
+    });
+
+    root.children = root.children ?? [];
+    root.children.push({
+      type: "brandFootnoteList",
+      data: { hName: FOOTNOTE_LIST_TAG },
+      children: items,
+    });
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* React renderers (registered on MarkdownPreview's components map)      */
+/* ------------------------------------------------------------------ */
+
+type TagProps = { node?: unknown; children?: ReactNode } & Record<string, unknown>;
+
+function readPayload(rest: TagProps): FootnotePayload | null {
+  const raw =
+    (rest[FOOTNOTE_ATTR] as string | undefined) ?? (rest[FOOTNOTE_PROP] as string | undefined);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as FootnotePayload;
+  } catch {
+    return null;
+  }
+}
+
+/** Inline footnote marker — a quiet superscript same-page link. */
+export function FootnoteRef({ node: _n, children: _c, ...rest }: TagProps) {
+  const payload = readPayload(rest);
+  if (!payload) return null;
+  const { id, n, refId } = payload;
+  return (
+    <sup className="leading-none">
+      <a
+        id={refId ?? `fnref-${id}`}
+        href={`#fn-${id}`}
+        data-footnote-ref=""
+        aria-label={`Footnote ${n}`}
+        // #399 — a footnote marker is superscript body text: `-text` rung.
+        className="px-0.5 font-medium text-primary-text underline tabular-nums hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        {n}
+      </a>
+    </sup>
+  );
+}
+
+/** A single footnote definition row — the `<li>` + one "↩" back-ref per mention. */
+export function FootnoteItem({ node: _n, children, ...rest }: TagProps) {
+  const payload = readPayload(rest);
+  if (!payload) return null;
+  const { id, n, refs } = payload;
+  // One back-ref per occurrence (GFM behavior); a single mention → a lone "↩".
+  const refList = refs && refs.length > 0 ? refs : [`fnref-${id}`];
+  return (
+    <li
+      id={`fn-${id}`}
+      className="scroll-mt-4 ps-1 [&>p]:m-0 [&>p]:inline [&>p]:text-caption [&>p]:text-muted-foreground"
+    >
+      {children}{" "}
+      {refList.map((refId, i) => (
+        <a
+          key={refId}
+          href={`#${refId}`}
+          data-footnote-backref=""
+          aria-label={
+            refList.length > 1
+              ? `Back to reference ${n}, mention ${i + 1}`
+              : `Back to reference ${n}`
+          }
+          className="ms-0.5 inline-flex items-center text-muted-foreground no-underline hover:text-foreground focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <span aria-hidden="true">↩</span>
+          {refList.length > 1 ? (
+            <sub className="ms-0.5 leading-none tabular-nums">{i + 1}</sub>
+          ) : null}
+        </a>
+      ))}
+    </li>
+  );
+}
+
+export type FootnoteListProps = HTMLAttributes<HTMLElement>;
+
+/**
+ * The branded footnote-definition section. One focal separation gesture — a top
+ * `Separator` (the classic footnote rule) — over a quiet label + the definition
+ * list; no fill, no border box. The label id is per-instance (`useId`) so two
+ * previews on one page don't collide.
+ */
+export const FootnoteList = forwardRef<HTMLElement, FootnoteListProps>(function FootnoteList(
+  { className, children, ...props },
+  ref,
+) {
+  const labelId = useId();
+  return (
+    <section ref={ref} aria-labelledby={labelId} className={cn("mt-8", className)} {...props}>
+      <Separator className="mb-3" />
+      <p id={labelId} className="mb-2 text-meta font-medium text-muted-foreground">
+        Footnotes
+      </p>
+      <ol className="list-decimal space-y-1.5 ps-6 text-caption text-muted-foreground marker:text-muted-foreground">
+        {children}
+      </ol>
+    </section>
+  );
+});