duckfn-docs-kit 0.3.0 → 0.4.1

package/dist/remark.d.ts

@@ -13,7 +13,7 @@ import type { Plugin } from 'unified';
  */
 export declare const DEFAULT_VERSION_PLACEHOLDER = "{{DUCKFN_VERSION}}";
 export interface VersionPlaceholderOptions {
-    /** The real version string to substitute in, e.g. `0.0.15`. */
+    /** The real version string to substitute in, e.g. `0.0.17`. */
     version: string;
     /** Override the token if a site uses a different one. */
     placeholder?: string;

package/dist/source-dialog.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The "edit the source" dialog shared by `<dfk-mermaid>` and the SQL result `svg`
+ * viewer: a modal holding a plain-text CodeMirror editor and an Apply / Cancel
+ * pair.
+ *
+ * The editor writes back through the callback {@link open} is given rather than
+ * through an event, so the owner keeps its own source as the single truth — the
+ * dialog never renders anything and never decides what a change means.
+ *
+ * The `<dialog>` is built once and reused; the editor mounts on first open and is
+ * kept, because a reader who edits one diagram is likely to edit the next. The
+ * dialog is shown *before* the editor mounts: CodeMirror measures its container as
+ * it is constructed, and a `display: none` dialog measures to zero.
+ *
+ * This is browser-only code.
+ */
+export interface SourceDialogLabels {
+    title: string;
+    apply: string;
+    cancel: string;
+}
+export declare class SourceDialog {
+    #private;
+    readonly root: HTMLDialogElement;
+    constructor(labels: SourceDialogLabels);
+    setLabels(labels: SourceDialogLabels): void;
+    /**
+     * Shows the dialog with `source` in the editor. `onApply` receives the edited
+     * text — only when it differs from what was opened, so an unedited Apply is a
+     * plain close.
+     */
+    open(source: string, onApply: (value: string) => void): void;
+    /** Closes the dialog and releases the editor. The dialog node stays in place. */
+    destroy(): void;
+}

package/dist/sql/PreviewTabs.d.ts

@@ -1,37 +1,53 @@
+import { type DownloadPayload } from '../download';
 /**
  * Every renderer's result shell: a tab strip plus the panels behind it.
  *
- * The strip is one tab per preview row plus a `Table` tab that always comes
- * **last**; a renderer with a single view passes no items at all, so a plain
- * table result is a strip holding nothing but that trailing `Table` tab. Every
- * result therefore has the same chrome — which is where the fullscreen toggle
- * lives.
+ * The strip holds one tab per item — a preview row, a `Text` view, or the
+ * trailing `Table` view — and, at its right end, the chrome that acts on the
+ * result as a whole: the active tab's own {@link PreviewTabItem.actions}, a
+ * **download** button, and whatever the caller parks last (the fullscreen toggle
+ * `<dfk-sql>` owns). Every result therefore has the same chrome, and the panel
+ * behind a tab is built the first time that tab is shown.
  *
- * Retained mode: every button and panel is built in the constructor and held in
- * a field. Activating a tab mutates the nodes it owns (`hidden`, `classList`,
- * `aria-selected`, `tabIndex`) — there is no rebuild, and a panel is filled the
- * first time it is shown rather than up front.
- *
- * The table panel is mounted on first activation on purpose: VTable measures
- * its container when it is constructed, and a `hidden` panel measures to zero.
+ * Retained mode: every button, action container and panel is built in the
+ * constructor and held in a field. Activating a tab mutates the nodes it owns
+ * (`hidden`, `classList`, `aria-selected`, `tabIndex`) — there is no rebuild, and
+ * a panel is filled the first time it is shown rather than up front.
  */
-/** One preview row: its tab label and how to fill its panel. */
+/** One tab: its label, how to fill its panel, and what it offers the strip. */
 export interface PreviewTabItem {
     label: string;
-    mount(panel: HTMLElement): void;
-}
-/** What `PreviewTabs` needs from the caller to own the trailing table tab. */
-export interface PreviewTableHandle {
-    dispose(): void;
+    /**
+     * Fills the panel. Called once, the first time the tab is shown; an async mount
+     * may resolve with a disposer, which the strip runs when it is disposed (that is
+     * how the table's handle gets released, including when the countdown lands after
+     * {@link PreviewTabs.dispose}).
+     */
+    mount(panel: HTMLElement): void | (() => void) | Promise<void | (() => void)>;
+    /**
+     * Controls for the strip's right end, shown only while this tab is active — the
+     * place for actions that belong to *this* result (a table's search and view
+     * switches, a figure's zoom reset) rather than to every result.
+     */
+    actions?: HTMLElement;
+    /** This tab's file, or `null` while there is nothing to save yet. */
+    download?: () => DownloadPayload | null;
+    /** Told the result area's fullscreen state, for figures that zoom inside it. */
+    setFullscreen?: (value: boolean) => void;
 }
 export declare class PreviewTabs {
     #private;
     /**
-     * @param corner Node parked at the right end of the strip, outside the
-     * scrolling tab list. `<dfk-sql>` passes its fullscreen toggle: it owns that
-     * button's state, so it owns the node and only lends it here.
+     * @param corner Node parked at the very end of the strip, after the download
+     * button. `<dfk-sql>` passes its fullscreen toggle: it owns that button's state,
+     * so it owns the node and only lends it here.
      */
-    constructor(host: HTMLElement, items: readonly PreviewTabItem[], tableLabel: string, mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>, corner?: HTMLElement);
-    /** Releases the table (if it was ever shown) and empties every panel. */
+    constructor(host: HTMLElement, items: readonly PreviewTabItem[], downloadLabel: string, corner?: HTMLElement);
+    /** Releases every mounted item and empties the panels. */
     dispose(): void;
+    /**
+     * Records the result area's fullscreen state and passes it on to the tab on
+     * screen: a figure zooms only where the result is expanded (see `PanZoomView`).
+     */
+    setFullscreen(value: boolean): void;
 }

package/dist/sql/SvgViewer.d.ts

@@ -0,0 +1,53 @@
+import { type DownloadPayload } from '../download';
+/**
+ * The `svg` result view: an inline SVG a reader can zoom (in the result area's
+ * fullscreen), edit, and download — the same interactions a diagram gets from
+ * `<dfk-mermaid>`, which is why both are built on `PanZoomView` and
+ * `SourceDialog`.
+ *
+ * A plain class rather than a custom element: nothing hands it content through
+ * markup, and the SQL renderer already has the parsed node, so there is no
+ * upgrade to wait for.
+ *
+ * Like an embedded `<dfk-mermaid>`, the element contributes no frame — the result
+ * area's panel is the frame — and no floating cluster: its two controls travel out
+ * through {@link actions} for the result's tab strip, and its file travels out
+ * through {@link downloadPayload} for the strip's download button. Zoom is off
+ * until {@link setFullscreen} says the result area is expanded.
+ *
+ * This is browser-only code.
+ */
+/** The strings a figure's controls need. */
+export interface FigureLabels {
+    reset: string;
+    edit: string;
+    editTitle: string;
+    apply: string;
+    cancel: string;
+}
+export declare class SvgViewer {
+    #private;
+    /** The box in the tab panel: the panzoom viewport, and the frame's clipping box. */
+    readonly root: HTMLDivElement;
+    /** The controls the result area's tab strip shows while this tab is active. */
+    readonly actions: HTMLDivElement;
+    constructor(svg: SVGElement | null, markup: string, labels: FigureLabels, fallback: string);
+    /** Turns zoom and pan on or off; the result area calls this with its fullscreen. */
+    setFullscreen(value: boolean): void;
+    /**
+     * The file this view would be saved as: the SVG itself, or — when the markup
+     * does not parse and the view is showing it as text — that text.
+     */
+    downloadPayload(): DownloadPayload;
+    dispose(): void;
+}
+/**
+ * Parses SVG markup from a result cell into a node this document can host.
+ *
+ * `image/svg+xml` is strict XML: malformed markup (unclosed tags, a bare `&`,
+ * an HTML `<br>`) comes back as a `<parsererror>` element rather than throwing,
+ * so the caller can degrade to text. Script-bearing and event-handler content
+ * is stripped — inline SVG is *not* isolated (use the `iframe` renderer for
+ * untrusted markup).
+ */
+export declare function parseSvgMarkup(document: Document, markup: string): SVGElement | null;

package/dist/sql/client.js

@@ -1,4 +1,4 @@
-import { t as e } from "../register-CALCwFBv.js";
+import { t as e } from "../register-wdwf0LC4.js";
 //#region src/sql/client.ts
 typeof window < "u" && e();
 //#endregion

package/dist/sql/harness.js

@@ -8000,7 +8000,7 @@ var Eu, Du, Ou, ku, Au, ju, Mu, Nu, Pu, Fu, Iu, Lu, Ru, zu, Bu, Vu, Hu, Uu, Wu,
 		11
 	])), od = {
 		name: "@duckdb/duckdb-wasm",
-		version: "1.33.1-dev64.0",
+		version: "1.33.1-dev65.0",
 		description: "DuckDB powered by WebAssembly",
 		license: "MIT",
 		repository: {

package/dist/sql/remark.d.ts

@@ -34,8 +34,13 @@ export interface RunnableSqlConfig {
      *
      * `html` and `iframe` are the same renderer: both sandbox the markup in an
      * iframe, so scripts run with an opaque origin.
+     *
+     * `mermaid` renders the column's mermaid source as a diagram through
+     * `<dfk-mermaid>` (the same element a ```mermaid fence produces), so the result
+     * gets the element's zoom, fullscreen, source editing and SVG download for
+     * free.
      */
-    show?: 'table' | 'html' | 'iframe' | 'svg' | 'text';
+    show?: 'table' | 'html' | 'iframe' | 'svg' | 'text' | 'mermaid';
     /**
      * What this block is expected to do when the docs' own SQL test suite runs it
      * (`duckfn-docs-kit/sql/verify`). Defaults to `'ok'`; `'error'` marks a block

package/dist/sql/renderers.d.ts

@@ -5,6 +5,8 @@ import type { RunnableSqlConfig } from './remark';
  *
  * The registry is the seam later phases plug into. It ships `table` (VisActor
  * VTable), a `text` fallback, the markup previews `iframe` / `html` / `svg`,
+ * `mermaid` (which hands the cell to the kit's own `<dfk-mermaid>` element, so a
+ * query can produce a diagram the reader can zoom, expand, edit and download),
  * plus the `error` view every renderer shares.
  *
  * Heavy dependencies (`@visactor/vtable`) load through dynamic `import()`
@@ -23,6 +25,13 @@ export interface RenderContext {
      * renderer only borrows it so every result has the same chrome.
      */
     fullscreenButton: HTMLElement;
+    /**
+     * Subscribes to the result area's fullscreen state, calling back with the
+     * current value straight away and returning the unsubscribe. A renderer whose
+     * figure zooms only in fullscreen (`svg`, `mermaid`) forwards the value to its
+     * viewer; the subscription must be released by the renderer's disposer.
+     */
+    onFullscreenChange(listener: (value: boolean) => void): () => void;
 }
 /**
  * Renders `result` into `context.host`. Resolves with a disposer releasing any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [
@@ -58,10 +58,14 @@
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
-    "@duckdb/duckdb-wasm": "1.33.1-dev64.0",
+    "@duckdb/duckdb-wasm": "1.33.1-dev65.0",
+    "@panzoom/panzoom": "^4.6.2",
     "@visactor/vtable": "^1.26.8",
+    "@visactor/vtable-search": "^1.26.8",
     "codemirror": "^6.0.2",
+    "filenamify": "^7.0.3",
     "iconify-icon": "^3.0.3",
+    "mermaid": "^12.0.0",
     "playwright-core": "^1.63.0",
     "sql-formatter": "^15.9.0"
   },

package/src/IconButton.ts

@@ -0,0 +1,50 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el} from './dom';
+
+/**
+ * A compact icon-only button with a hover/focus tooltip, built once and then
+ * mutated. Shared by `<dfk-sql>`'s code-block cluster and `<dfk-mermaid>`'s
+ * diagram cluster: both want the same "floating icon row over content" idiom,
+ * and neither wants a second implementation of it.
+ *
+ * The tooltip is also the accessible name — an icon-only control has no text to
+ * fall back on. The two class names are written by this module and styled in
+ * *each* consumer's shadow-root CSS; that duplication is unavoidable (a shadow
+ * boundary stops one sheet from reaching the other tree), so the rules carry the
+ * same names and are kept in sync by hand.
+ */
+export class IconButton {
+  readonly root = el('button', {class: 'dfk-icon-button', type: 'button'});
+  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-icon',
+    attrs: {'aria-hidden': 'true'},
+  });
+
+  constructor(icon: string, onClick: () => void) {
+    this.root.appendChild(this.#icon);
+    this.root.addEventListener('click', onClick);
+    this.setIcon(icon);
+  }
+
+  setIcon(icon: string): void {
+    this.#icon.setAttribute('icon', icon);
+  }
+
+  setLabel(text: string): void {
+    this.root.setAttribute('data-tip', text);
+    this.root.setAttribute('aria-label', text);
+  }
+
+  /** Marks a toggle as currently on (e.g. the SQL block's wrap toggle). */
+  setOn(on: boolean): void {
+    this.root.classList.toggle('dfk-icon-on', on);
+  }
+
+  setDisabled(disabled: boolean): void {
+    if (disabled) {
+      this.root.setAttribute('disabled', '');
+    } else {
+      this.root.removeAttribute('disabled');
+    }
+  }
+}

package/src/codemirror.ts

@@ -0,0 +1,97 @@
+/**
+ * The CodeMirror 6 editor behind the kit's editable content: the code view of a
+ * runnable SQL block (`<dfk-sql>`) and the diagram-source dialog of a
+ * `<dfk-mermaid>`. One implementation, two languages — the SQL block asks for
+ * highlighting, the diagram editor takes the plain-text default.
+ *
+ * Every CodeMirror module arrives through a dynamic `import()` inside
+ * {@link mountCodeEditor}: a page full of blocks pays nothing for the editor on
+ * its critical path, and Docusaurus' Node prerender never evaluates any of it.
+ *
+ * This is browser-only code: `document` is touched only through the container
+ * the caller hands over, and everything else is behind the `import()`s.
+ */
+
+export interface CodeEditor {
+  getValue(): string;
+  setValue(value: string): void;
+  /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
+  setWrap(wrapped: boolean): void;
+  destroy(): void;
+}
+
+export interface CodeEditorOptions {
+  /**
+   * Highlight the document as SQL. Omitted, the editor is plain text — which is
+   * what a mermaid diagram gets: there is no first-party CodeMirror language for
+   * it, and a docs reader is editing prose-shaped source, not writing SQL.
+   */
+  language?: 'sql';
+}
+
+export async function mountCodeEditor(
+  container: HTMLElement,
+  value: string,
+  onChange: (value: string) => void,
+  options: CodeEditorOptions = {},
+): Promise<CodeEditor> {
+  const [{basicSetup}, {EditorView, keymap}, {defaultKeymap, historyKeymap}, {Compartment}] =
+    await Promise.all([
+      import('codemirror'),
+      import('@codemirror/view'),
+      import('@codemirror/commands'),
+      import('@codemirror/state'),
+    ]);
+  // Loaded only for the blocks that ask for it, so a diagram editor does not pull
+  // the SQL grammar (and its lezer parsers) into the page.
+  const language =
+    options.language === 'sql' ? [(await import('@codemirror/lang-sql')).sql()] : [];
+
+  // Wrapping is toggled from the outside, and reconfiguring it must not disturb
+  // the document or the undo history — that is exactly what a compartment is
+  // for, so the extension is swapped in place rather than rebuilt.
+  const wrap = new Compartment();
+
+  const view = new EditorView({
+    doc: value,
+    extensions: [
+      basicSetup,
+      ...language,
+      keymap.of([...defaultKeymap, ...historyKeymap]),
+      wrap.of([]),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          onChange(update.state.doc.toString());
+        }
+      }),
+    ],
+    parent: container,
+    // The tree the container really belongs to — `getRootNode()`, not CodeMirror's
+    // own `getRoot()`. `getRoot()` follows `assignedSlot` before `parentNode`, so a
+    // container in a *slotted* subtree is reported as living in the shadow root it
+    // is slotted **into**. The SQL result area is exactly that (light DOM, slotted
+    // into `<dfk-sql>` through `slot="dfk-result"`), so style-mod mounted the base
+    // theme in a shadow root, where it cannot reach slotted nodes at all: the
+    // editor laid out as plain block boxes — `.cm-scroller` stacked instead of
+    // flex, gutter above the code.
+    //
+    // `getRootNode()` stops at the tree that owns the container: `document` for
+    // that slotted light DOM, the shadow root for a genuine shadow child (the
+    // code view, a diagram's dialog) — which is where the `.cm-*` rules are
+    // needed. Pinning it to `document` would break the shadow cases instead.
+    root: container.getRootNode() as Document | ShadowRoot,
+  });
+
+  return {
+    getValue: () => view.state.doc.toString(),
+    setValue: (next: string) =>
+      view.dispatch({
+        changes: {from: 0, to: view.state.doc.length, insert: next},
+      }),
+    setWrap: (wrapped: boolean) =>
+      view.dispatch({
+        effects: wrap.reconfigure(wrapped ? EditorView.lineWrapping : []),
+      }),
+    destroy: () => view.destroy(),
+  };
+}

package/src/download.ts

@@ -0,0 +1,169 @@
+import filenamify from 'filenamify';
+import {el} from './dom';
+
+/**
+ * Saving something the kit rendered to a file: the payload shape, the click that
+ * performs the save, and how the file is named.
+ *
+ * Shared by `<dfk-mermaid>` (a downloaded diagram) and the SQL result chrome (a
+ * downloaded result of any kind), so a docs page has one definition of "what a
+ * download is" rather than one per component.
+ *
+ * This is browser-only code.
+ */
+
+/** One file's worth of text, ready to save. */
+export interface DownloadPayload {
+  /** The file name, extension included. */
+  name: string;
+  /** The blob's MIME type. */
+  mime: string;
+  /** The file's contents — text for every format the kit produces. */
+  text: string;
+}
+
+/**
+ * Saves a payload through a temporary object URL.
+ *
+ * The anchor is in the document for the click — some browsers ignore a detached
+ * one — and the URL is revoked on the next tick, once the download has been
+ * handed to the browser.
+ */
+export function saveDownload(payload: DownloadPayload): void {
+  const blob = new Blob([payload.text], {type: payload.mime});
+  const url = URL.createObjectURL(blob);
+  const link = el('a', {href: url, download: payload.name});
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+/** Used when nothing on the page says anything about what this is. */
+const DEFAULT_BASE = 'diagram';
+
+/**
+ * The length cap. `filenamify` truncates by grapheme, so a CJK heading is cut at
+ * 80 *characters*, not bytes, and an emoji survives whole.
+ */
+const MAX_LENGTH = 80;
+
+/** How a reserved character is spelled in the file name (`2. Registration: …`). */
+const REPLACEMENT = '-';
+
+/**
+ * The *format* characters (zero-width space, word joiner, byte-order mark…) and
+ * whitespace that a title can wear at its edges.
+ */
+const EDGE_NOISE = /^[\s\p{Cf}]+|[\s\p{Cf}]+$/gu;
+
+/**
+ * Trims a candidate down to its text, dropping format characters at the edges.
+ *
+ * Plain whitespace trimming is not enough: Docusaurus gives every heading an
+ * anchor link whose label is a zero-width space, so `textContent` of a heading is
+ * `"2. Registration\u200B"`. `filenamify` turns a format character into the
+ * replacement rather than dropping it, which would produce
+ * `2. Registration-.svg`. Only the *edges*: an interior zero-width joiner is what
+ * holds an emoji together.
+ */
+function cleanTitle(value: string | undefined): string {
+  return value === undefined ? '' : value.replace(EDGE_NOISE, '');
+}
+
+/**
+ * What a downloaded figure is called.
+ *
+ * The name is derived from the page, not from the figure: a diagram or an SVG
+ * result has no name of its own, and the reader downloading one is after "the
+ * figure from that section", not `diagram.svg`.
+ *
+ * Three sources, most specific first, each falling back to the next:
+ *
+ * 1. **The figure's own title** — mermaid's frontmatter (`---\ntitle: …\n---`,
+ *    which mermaid itself draws above the diagram); only read when `options.source`
+ *    is given.
+ * 2. **The nearest heading above it** — the section the figure belongs to, which
+ *    on a docs page is what a reader would call it.
+ * 3. **The document title** — the browser tab's title, for a figure that sits
+ *    above every heading on its page.
+ *
+ * Nothing found → `options.fallback` (or {@link DEFAULT_BASE}), with `extension`
+ * appended either way.
+ */
+export function sectionFileName(
+  element: Element,
+  extension: string,
+  options: {source?: string; fallback?: string} = {},
+): string {
+  const candidates = [
+    options.source === undefined ? undefined : frontmatterTitle(options.source),
+    precedingHeading(element),
+    element.ownerDocument.title,
+  ].map(cleanTitle);
+  const title = candidates.find((candidate) => candidate !== '');
+  if (title === undefined) {
+    return `${options.fallback ?? DEFAULT_BASE}.${extension}`;
+  }
+  // Filenames are a filesystem concern, so they go through a library rather than a
+  // hand-rolled character class. Three things it does that matter here and that a
+  // browser does *not*: it strips what Windows and macOS reject (`:`, `?`, `*`,
+  // `"`, `<`, `>`, `|`, the path separators and control characters), it trims the
+  // trailing dots and spaces Windows silently drops, and it avoids the reserved
+  // device names (`con`, `nul`, …). The `download` attribute's own sanitisation
+  // covers only `/` and `\`.
+  //
+  // It also normalises Unicode whitespace and drops format characters, which
+  // quietly cleans up Docusaurus' heading anchors: the `<a>` it appends to every
+  // heading contributes a zero-width space to `textContent`.
+  return `${filenamify(title, {replacement: REPLACEMENT, maxLength: MAX_LENGTH})}.${extension}`;
+}
+
+/**
+ * mermaid's frontmatter block, if the source opens with one.
+ *
+ * Only the top-level `title:` key is read. Mermaid's frontmatter is YAML, and the
+ * rest of it (a nested `config:`, `displayMode:`, …) is none of this module's
+ * business: a key that is always a plain scalar on one line does not justify a
+ * YAML parser, and anything indented — a nested key — is skipped by anchoring the
+ * match at the line start.
+ */
+function frontmatterTitle(source: string): string | undefined {
+  const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source.trimStart())?.[1];
+  if (block === undefined) {
+    return undefined;
+  }
+  const value = /^title\s*:\s*(.+)$/m.exec(block)?.[1];
+  return value === undefined ? undefined : unquote(value.trim());
+}
+
+/** Strips one pair of matching quotes, so `title: "A: B"` keeps its colon. */
+function unquote(value: string): string {
+  const first = value[0];
+  return (first === '"' || first === "'") && value.endsWith(first) ? value.slice(1, -1) : value;
+}
+
+/**
+ * The text of the last heading that precedes the figure, or `undefined`.
+ *
+ * The search is scoped to the enclosing `<article>` where there is one: a docs
+ * page's navbar, sidebar and footer are full of headings that have nothing to do
+ * with this figure, and the article is the one container that holds the page's
+ * own content.
+ */
+function precedingHeading(element: Element): string | undefined {
+  const scope: ParentNode = element.closest('article') ?? element.ownerDocument;
+  let found: string | undefined;
+  for (const heading of scope.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+    // `FOLLOWING` means the heading comes before the element in document order.
+    if (!(heading.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING)) {
+      // Headings are in document order, so nothing later can precede it either.
+      break;
+    }
+    const text = heading.textContent?.trim();
+    if (text) {
+      found = text;
+    }
+  }
+  return found;
+}

package/src/index.ts

@@ -1,7 +1,14 @@
 import type {HTMLAttributes} from 'react';
+// Imported as well as re-exported: the `HTMLElementTagNameMap` augmentation below
+// names the classes, and a module augmentation can only refer to local bindings.
+import {DfkFeatures} from './home/DfkFeatures';
+import {DfkHero} from './home/DfkHero';
+import {DfkMermaid} from './mermaid/DfkMermaid';
+import {DfkNextSteps} from './home/DfkNextSteps';
+import {DfkSql} from './sql/DfkSql';
 
 /**
- * Browser entry for duckfn-docs-kit: the home-page custom elements and the
+ * Browser entry for duckfn-docs-kit: the custom elements it registers and the
  * value types their `set*` methods accept.
  *
  * The components are retained-mode (build once, then mutate held nodes) and
@@ -13,17 +20,16 @@ import type {HTMLAttributes} from 'react';
  * web component, which `registerDfkElements()` registers as a side effect, so
  * this package ships no icon data.
  *
- * `TocToggle` and the remark plugin keep their own subpaths
- * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`) instead of
+ * `TocToggle` and the remark plugins keep their own subpaths
+ * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`,
+ * `duckfn-docs-kit/sql/remark`, `duckfn-docs-kit/mermaid/remark`) instead of
  * being merged here: a Docusaurus config file must never pull browser code into
  * Node, and a site that only wants the TOC collapse button should not pay for
  * the bundled `iconify-icon`.
  */
-export {DfkFeatures} from './home/DfkFeatures';
-export {DfkHero} from './home/DfkHero';
-export {DfkNextSteps} from './home/DfkNextSteps';
-export {DfkSql} from './sql/DfkSql';
+export {DfkFeatures, DfkHero, DfkMermaid, DfkNextSteps, DfkSql};
 export {registerDfkElements} from './register';
+export type {DfkMermaidConfig, DfkMermaidConfigInput} from './mermaid/config';
 export type {RunnableSqlConfig} from './sql/remark';
 export type {
   FeatureItem,
@@ -47,6 +53,23 @@ export type {
  */
 export type DfkElementProps = HTMLAttributes<HTMLElement>;
 
+/**
+ * The kit's tags in the DOM's own tag map, so `document.createElement('dfk-sql')`
+ * (and the kit's `el()` helper) is typed as the class it upgrades to. Without
+ * this, every place that builds a `dfk-*` element from scratch — `sql/renderers.ts`
+ * building a `<dfk-mermaid>` for a `mermaid` result, `docs/src/pages/index.tsx`
+ * mounting the home elements — would have to cast the result.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    'dfk-hero': DfkHero;
+    'dfk-features': DfkFeatures;
+    'dfk-next-steps': DfkNextSteps;
+    'dfk-sql': DfkSql;
+    'dfk-mermaid': DfkMermaid;
+  }
+}
+
 declare module 'react' {
   namespace JSX {
     interface IntrinsicElements {
@@ -54,6 +77,7 @@ declare module 'react' {
       'dfk-features': DfkElementProps;
       'dfk-next-steps': DfkElementProps;
       'dfk-sql': DfkElementProps;
+      'dfk-mermaid': DfkElementProps;
     }
   }
 }