# brookmd — full documentation bundle

Generated by web/scripts/build-llms.mjs. Do not edit by hand.
Short index: https://md.hsingh.app/llms.txt


==============================================================================
# Source: packages/brookmd/README.md
==============================================================================

# brookmd

Zero-dep streaming markdown for the browser. Rust→WASM core, one Web Worker per stream, incremental parse with speculative closure for mid-stream constructs.

Drop in a streaming-aware renderer — **React, Vue, Svelte, Solid, a framework-agnostic `<brook-markdown>` Web Component, or the vanilla DOM mount** — wire each LLM stream to a `BrookClient`, and the markdown renders incrementally off the main thread, block by block, with stable identities so unchanged blocks never re-reconcile.

Parsing runs entirely **off the main thread** — each stream gets its own pooled Web Worker, so many concurrent LLM responses render without contending for the UI thread. On each token the parser re-parses only the **active tail**, not the whole document; patches cross the worker boundary as **verified splices** (not full re-sends, so emitted bytes stay O(n) even for one giant growing block); and heavy renderers (math, mermaid) are **deferred until a block closes** — code fences highlight as they stream, re-tokenizing only the last line rather than the whole block per chunk. The result is low retained memory and a main thread that stays responsive while streaming. See [the live demo](https://md.hsingh.app/).

> **Beyond the browser:** the same Rust core also powers experimental React
> Native, Swift (iOS/macOS), Kotlin/Android, Flutter, and C-ABI bindings —
> every platform speaks the same versioned wire, byte-for-byte. See the
> [platform matrix](https://github.com/siinghd/brookmd#platforms) in the
> repository README.

## Install

```bash
bun add brookmd     # or: npm i brookmd / pnpm add brookmd
```

brookmd ships **compiled, non-minified ESM** (`dist/*.js` + `.d.ts` types) plus
the compiled WASM — no raw `.ts`/`.tsx` source. The worker and WASM asset are
referenced with the **web-standard `new URL(asset,
import.meta.url)`** pattern, so any bundler with asset-module support resolves
them: **Vite** (the reference setup), **webpack 5**, **Rollup** (with asset
modules), **Parcel**, and **Next.js** (App Router — Turbopack *and* webpack;
**verified on Next.js 16**, see the [Next.js callout](#nextjs) below).

The streaming client (`<BrookMarkdown>` / `BrookClient`) is **browser-only** (it
constructs Web Workers). For **server-side / static rendering of finished
content** — SSR, React Server Components, build steps — use the worker-free,
synchronous [`brookmd/server`](#server-side-rendering) entry. The framework packages — `react`,
`vue`, `svelte`, `solid-js` — are all **optional** peer dependencies; you only
need the one whose binding you import. The framework-free entries
(`brookmd/client`, `brookmd/dom`, `brookmd/element`, and `brookmd/server`) need
none. (The bare `brookmd` entry re-exports the React component surface, so it
pulls `react` — import from `brookmd/client` if you want a framework-free core.)

> **Vite — one-line config.** Vite's dependency pre-bundling (esbuild) hoists
> the wasm-bindgen glue into `.vite/deps/`, which breaks the relative
> `new URL("…_bg.wasm", import.meta.url)` lookup so the worker can't load WASM
> (you'll see a 404 / "magic word" error). Exclude brookmd from pre-bundling:
>
> ```ts
> // vite.config.ts
> export default defineConfig({
>   optimizeDeps: { exclude: ["brookmd"] },
> });
> ```
>
> No other bundler needs this — it's specific to Vite's optimizer.

<a id="nextjs"></a>

> **Next.js (App Router) — one requirement.** Works on **Next.js** with
> **Turbopack** (the default for both `next dev` and `next build`) or webpack.
> Since 0.17.0 brookmd ships **compiled ESM**, so **no `transpilePackages` or
> other build config is needed** — earlier versions required it only because the
> package shipped raw TypeScript, which Next does not compile inside
> `node_modules`. That no longer applies.
>
> **Use it from a Client Component.** `<BrookMarkdown>` uses React hooks (and
> spawns a Web Worker on mount), so it must carry `"use client"` — it can't be
> a Server Component. (It is still SSR-safe: on the server it renders an empty
> shell and only starts streaming after hydration, so there's no SSR crash —
> the constraint is hooks, not the worker.)
>
> ```tsx
> "use client";
> import { BrookMarkdown } from "brookmd/react";
>
> export default function Answer({ stream }: { stream: AsyncIterable<string> }) {
>   return <BrookMarkdown stream={stream} />;
> }
> ```
>
> **Create the `stream` in Client Component code, not in a Server Component.**
> A `Response` / `ReadableStream` / `AsyncIterable` isn't serializable, so it
> can't be passed as a prop from a Server Component (e.g. `page.tsx`) — that
> throws *"Only plain objects can be passed to Client Components."* Pass a
> serializable prop (a URL, the chat messages) from the server and open the
> stream on the client — e.g. `stream={await fetch("/api/chat")}` from a client
> effect, or the `useBrookStream` hook (see [Quick start](#quick-start)).
>
> That's it — Turbopack bundles the worker and emits the `.wasm` to
> `_next/static/media` itself, so no extra asset/loader config is needed (and the
> Vite `optimizeDeps` workaround above does **not** apply). Both `next dev` and
> `next build && next start` are verified to spawn the worker, load the WASM, and
> stream markdown. _Dev tip:_ open the app on `localhost` — Next dev blocks
> cross-origin dev resources (HMR, chunks) from other hosts (e.g. `127.0.0.1`)
> unless you add them to `allowedDevOrigins` in `next.config`.

## Quick start

```ts
import { BrookClient, BrookMarkdown } from "brookmd";

// One client per stream. Spawns a Web Worker that owns a Rust parser.
const client = new BrookClient();

// Feed chunks as they arrive from your SSE / fetch reader.
for await (const delta of streamFromAi()) {
  client.append(delta);
}
client.finalize();
```

In React — pass the stream straight to `<BrookMarkdown>`. It owns the client,
pipes the stream, supersedes it if it changes, and cleans up on unmount:

```tsx
import { BrookMarkdown } from "brookmd/react";

export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
  return <BrookMarkdown stream={stream} />;
}
```

`stream` accepts an `AsyncIterable<string>` (e.g. SSE deltas), a `Response`, or
a `ReadableStream<Uint8Array>` — so `<BrookMarkdown stream={await fetch("/api/chat")} />`
works too.

Need the client handle (for `outline()` / `getMetrics()` / a shared client)? Use
the `useBrookStream` hook — same lifecycle, returns the owned client:

```tsx
import { BrookMarkdown, useBrookStream } from "brookmd/react";

export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
  const client = useBrookStream(stream);
  return <BrookMarkdown client={client} />;
}
```

### Chat UI defaults

Five flags an LLM chat UI almost always wants — each off by default because the
library's default is strict CommonMark, not because it is the better choice here:

```tsx
import { getDefaultPool } from "brookmd";
import { BrookMarkdown, useBrookStream } from "brookmd/react";
import { useEffect } from "react";

// Hoist the config and the overrides — a fresh object each render busts the
// per-block memo, so every block re-renders on every patch.
const chatConfig = {
  softBreaks: true, // a lone \n renders as <br> — models write chat prose, not CommonMark
  dirAuto: true,    // per-block dir="auto", so an Arabic answer renders RTL beside an English one
  a11y: true,       // task-list <label>s + <th scope="col">
  blockData: true,  // typed props.table / heading / code — toolbars from data, not HTML re-parsing
  gfmMath: true,    // $…$ / $$…$$ / \(…\) / \[…\] (only if your model emits LaTeX)
};

export function Answer({ stream }: { stream: AsyncIterable<string> }) {
  // Hide the one-time WASM init behind the user's typing, not the first token.
  useEffect(() => { getDefaultPool().warm(); }, []);
  const client = useBrookStream(stream, { config: chatConfig });
  return <BrookMarkdown client={client} className="brook-caret" stickToBottom />;
}
```

`className="brook-caret"` opts into the theme's [streaming
caret](#streaming-caret); drop it if you draw your own.

### Already holding a growing string? — `useBrookMarkdownString`

Many apps keep the streaming message as a **single growing string prop** (it
re-renders with the full text-so-far each token), not as a stream. Feed that
string straight in — `useBrookMarkdownString` diffs it for you and forwards only
the delta, so you don't hand-roll an append/reset bridge:

```tsx
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/react";

export function ChatMessage({ text, streaming }: { text: string; streaming: boolean }) {
  const client = useBrookMarkdownString(text, { streaming });
  return <BrookMarkdown client={client} />;
}
```

It handles the two shapes a controlled string takes: a **prefix-extension** (the
common token-by-token growth) appends only the new suffix; a **divergence** (e.g.
the finished text swapped for a re-processed final string — bolded numbers,
wrapped tickers) resets and reparses. Pass `streaming: false` once the content is
final so the last block commits (a finished code fence then highlights). The
framework-neutral primitive is **`client.setContent(fullString, { done })`** —
use it from any binding.

> **Transforming streamed content?** If the enrichment runs **live per token**
> (e.g. bold every number as it arrives), do it at **render time** via
> [`components`](#custom-components--overrides) — keep the markdown source
> append-only so parsing stays incremental. Re-transforming the *whole* string
> each token (so earlier bytes change) forces `setContent` to reparse every tick
> (O(n²)); that's what render-time overrides avoid. `setContent`'s reset path is
> for the **once**-at-the-end reprocess swap, not per-token rewrites. That swap
> is seamless: the current view stays on screen while the new string reparses —
> the document never blanks, scroll never moves, and blocks whose rendered
> content is unchanged keep their identity (and React keys), so only genuinely
> changed blocks re-render. (`setContent("")` is an explicit clear and resets
> immediately.)

### With the Vercel AI SDK (`useChat`)

`useChat` hands you each message as `parts`, and the assistant's text part grows
token by token — exactly the controlled-string shape above. Join the text parts
and pass the result straight in:

```tsx
import { useChat } from "@ai-sdk/react";
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/react";

// Hoisted — see the memoization note in `components`.
const components = { a: (p: any) => <a {...p} /> };

export function Thread() {
  const { messages, status } = useChat();
  // `status` describes the LAST message only — earlier ones are finished.
  return messages.map((m, i) => (
    <Answer key={m.id} message={m} streaming={status === "streaming" && i === messages.length - 1} />
  ));
}

function Answer(props: {
  message: { parts: Array<{ type: string; text?: string }> };
  streaming: boolean;
}) {
  const text = props.message.parts.map((p) => (p.type === "text" ? p.text ?? "" : "")).join("");
  const client = useBrookMarkdownString(text, { streaming: props.streaming });
  return <BrookMarkdown client={client} components={components} />;
}
```

> **Pass `streaming: false` when the message finishes — it is not inferred.**
> Omit it (or leave it `true`) and the stream stays OPEN forever: the last block
> never commits, so a finished code fence never highlights and never shows its
> copy button, and a streaming caret never stops blinking. brookmd deliberately
> refuses to infer "done" from an unchanged string — a caller who grows the text
> without the flag would re-finalize on every token, an O(n²) reparse trap.

One client per message, so re-rendering the thread never re-parses history, and
`getDefaultPool().warm()` in the chat shell (see [Chat UI
defaults](#chat-ui-defaults)) keeps WASM init off the first answer.

<details>
<summary>Full manual control (caller-owned client)</summary>

When you want to drive the stream yourself, pass a `client` you own — the
component never destroys it:

```tsx
import { useEffect, useState } from "react";
import { BrookClient, BrookMarkdown } from "brookmd";

export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
  const [client] = useState(() => new BrookClient());
  useEffect(() => () => client.destroy(), [client]);
  useEffect(() => {
    const ac = new AbortController();
    client.pipeFrom(stream, { signal: ac.signal }); // pipeFrom also accepts AsyncIterable
    return () => ac.abort();
  }, [client, stream]);
  return <BrookMarkdown client={client} />;
}
```

</details>

> **StrictMode note:** a stream (SSE generator / `Response`) can be consumed only
> once, so React StrictMode's dev-only double-mount may truncate it in
> development. Production mounts once and is unaffected.

Multiple concurrent streams just need multiple clients — each runs in its own worker, so they don't share main-thread budget.

## Framework bindings

`BrookClient` is framework-neutral — it owns the worker and exposes
`subscribe`/`getSnapshot`. Pick a renderer to put its blocks on screen. Every
binding below is thin glue over the same incremental DOM renderer, so they
share one identity contract: a committed block's node is never recreated, only
the streaming tail re-renders.

**One ownership rule across all bindings:** the renderer's teardown (React
unmount, `handle.destroy()`, element disconnect, etc.) frees only the rendered
DOM and the subscription — it **never** destroys the client. You call
`client.destroy()` when you're done with the stream. (React's `<BrookMarkdown>`,
documented [below](#brookmarkdown-react), is the same.)

### Vanilla / any framework — `brookmd/dom`

```ts
import { BrookClient } from "brookmd/client";
import { mountBrookMarkdown } from "brookmd/dom";

const client = new BrookClient();
const handle = mountBrookMarkdown(client, document.getElementById("out")!, {
  stickToBottom: true,
});

// Feed it from a fetch/SSE reader:
const reader = (await fetch("/api/chat")).body!.getReader();
const dec = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  client.append(dec.decode(value, { stream: true })); // stream:true carries multibyte across chunks
}
client.append(dec.decode());
client.finalize();

// Teardown: destroy BOTH — the renderer and the client you created.
handle.destroy();
client.destroy();
```

**Already holding a growing string?** There's no framework reactivity to wrap,
so just call **`client.setContent(fullString, { done })`** instead of the
`append` loop — it diffs internally (prefix → delta; divergence → reparse) and
finalizes on `done`. That's the same primitive the React/Vue/Svelte/Solid
controlled-string helpers wrap; in vanilla you call it directly.

`mountBrookMarkdown(client, container, options?)` returns
`{ destroy(), refresh(), openBlockId() }` — `openBlockId()` is the id of the
streaming **tail** block (the only one that can still re-render), or `null` when
nothing is open.
Options: `components`, `sanitize`, `virtualize`, `stickToBottom`, `className`,
`id`, `role`, `ariaLive`, `ariaAtomic`, `decorators`, `urlTransform`,
`onRenderMetrics`, `onLinkClick` (*since 0.30.0* — same delegated hook as React,
called with the native `MouseEvent`; see [Intercepting link
clicks](#intercepting-link-clicks--onlinkclick)), `highlightCode`
(default true), `streamingHighlight` (`boolean | "wavefront" | "eager"`, default
true — highlight a code fence while it is still streaming; see
[Streaming syntax highlighting](#streaming-syntax-highlighting)),
`batch` (default true — one DOM write per `requestAnimationFrame`),
`morphOpenBlocks` (default false — morph a growing generic open block's subtree in
place instead of rebuilding it via `innerHTML`, so only the changed parts repaint
and focus/selection in the streaming tail survive; the rendered result is
equivalent to the default rebuild path).
Block-kind overrides use `components` keyed by block-kind (`CodeBlock`, `Table`,
`Alert`, `Component`, …) with values `(props) => HTMLElement | string`. Tag-level
(lowercase `a`/`table`/`code`) overrides are **React-only** — there's no virtual
tree on the fast `innerHTML` path; a block-kind override can rewrite the `html`
it's handed instead.

### Web Component `<brook-markdown>` — `brookmd/element`

The universal binding — plain HTML, Angular, or any framework that renders DOM.
Register once, then use the element:

```ts
import { defineBrookMarkdown } from "brookmd/element";
defineBrookMarkdown(); // defines <brook-markdown>; pass a custom tag name if you like
```

```html
<!-- zero-JS streaming straight from a URL -->
<brook-markdown src="/api/post.md" gfm-math stick-to-bottom></brook-markdown>

<!-- one-shot from inline text -->
<brook-markdown># Hello **world**</brook-markdown>
```

```js
// or caller-owned streaming — drive your own client:
const el = document.querySelector("brook-markdown");
el.client = myBrookClient;             // element subscribes; never destroys it
el.components = { Thinking: (p) => myNode(p) };
myBrookClient.append(delta);
```

Config flags are **tri-state attributes**: absent = library default;
`gfm-math` / `gfm-math="true"` / `="1"` = on; `gfm-math="false"` / `="0"` = off
(the only way to turn off a default-on flag such as `gfm-alerts`). It renders in
light DOM so your markdown CSS applies, and `defineBrookMarkdown` is a no-op under
SSR (no `customElements`). A self-owned element (`src` / `markdown` / inline
text / `append()`) is torn down on disconnect; a caller-supplied `client` is left
alone.

**The full attribute surface:**

| Attributes | |
|---|---|
| content | `markdown`, `src` |
| renderer | `stick-to-bottom`, `virtualize` *(both since 0.30.0)* |
| config (tri-state) | `gfm-autolinks`, `gfm-alerts`, `gfm-tagfilter`, `gfm-footnotes`, `gfm-math`, `dir-auto`, `lenient-lists`, `soft-breaks`, `a11y`, `unsafe-html`, `block-html`, `retain-committed-html` |
| config (lists) | `component-tags`, `allow-schemes` — comma- or space-separated |

Properties (set them in JS, not as attributes): `client`, `components`,
`sanitize`, `onLinkClick` *(since 0.30.0)*. Methods: `append()`, `finalize()`,
`reset()`, `getClient()`. Config flags with no attribute of their own
(`inlineComponentTags`, `htmlAllowlist`, `dropHtmlTags`, `blockData`) are set by
assigning a caller-owned `client` you constructed with that config.

**Angular** consumes the same element — no separate package:

```ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
import { defineBrookMarkdown } from "brookmd/element";
defineBrookMarkdown(); // once at bootstrap

@Component({
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<brook-markdown [attr.src]="url" stick-to-bottom></brook-markdown>`,
})
export class Answer { url = "/api/post.md"; }
```

**Controlled growing string?** Assign a caller-owned client and drive it with
`setContent` — `el.client = myClient; myClient.setContent(fullString, { done })`
— the element subscribes and renders, you own the diffing. (The self-owned
`markdown` attribute is **one-shot** — it re-parses the whole document on each
change, so don't point it at a per-token-growing string; use a client +
`setContent` for that.)

### Vue 3 — `brookmd/vue`

```vue
<script setup lang="ts">
import { onBeforeUnmount } from "vue";
import { BrookClient } from "brookmd/client";
import { BrookMarkdown } from "brookmd/vue";

const client = new BrookClient();
// feed client.append(delta) from your stream, then client.finalize()
onBeforeUnmount(() => client.destroy());
</script>

<template>
  <BrookMarkdown :client="client" stick-to-bottom />
</template>
```

Props: `client` (required), `components`, `sanitize`, `virtualize`,
`stickToBottom`. There's also a `useBrookMarkdown` composable returning a
`container` ref if you'd rather mount into your own element.

**Already holding a growing string?** `useBrookMarkdownString` owns a client and
diffs the string for you (the Vue analogue of the React hook — see
[Controlled strings](#already-holding-a-growing-string--usebrookmarkdownstring)):

```vue
<script setup lang="ts">
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/vue";
const props = defineProps<{ text: string; streaming: boolean }>();
// Pass getters so the composable tracks the live values; it owns + destroys the client.
const client = useBrookMarkdownString(() => props.text, () => ({ streaming: props.streaming }));
</script>
<template><BrookMarkdown :client="client" /></template>
```

### Svelte (4 & 5) — `brookmd/svelte`

A Svelte action — works in both v4 and v5, no `.svelte` build step:

```svelte
<script lang="ts">
  import { onDestroy } from "svelte";
  import { BrookClient } from "brookmd/client";
  import { brookMarkdown } from "brookmd/svelte";

  const client = new BrookClient();
  // feed client.append(delta) then client.finalize()
  onDestroy(() => client.destroy());
</script>

<div use:brookMarkdown={{ client, stickToBottom: true }} />
```

**Growing string?** The `brookMarkdownString` action owns a client and diffs the
string — `use:brookMarkdownString={{ content, streaming }}` (it destroys its
client on `destroy`, so no manual cleanup):

```svelte
<script lang="ts">
  import { brookMarkdownString } from "brookmd/svelte";
  export let content: string;     // the growing message
  export let streaming: boolean;  // false once complete → finalizes
</script>

<div use:brookMarkdownString={{ content, streaming, stickToBottom: true }} />
```

### Solid — `brookmd/solid`

```tsx
import { onCleanup } from "solid-js";
import { BrookClient } from "brookmd/client";
import { BrookMarkdown } from "brookmd/solid";

const client = new BrookClient();
// feed client.append(delta) then client.finalize()
onCleanup(() => client.destroy());

<BrookMarkdown client={client} stickToBottom />;
```

**Growing string?** `createBrookMarkdownString` owns a client and diffs the string
(the Solid analogue of the React hook), driving `setContent` from a
`createEffect` and destroying the client on cleanup:

```tsx
import { BrookMarkdown, createBrookMarkdownString } from "brookmd/solid";

function Message(props: { text: string; streaming: boolean }) {
  const client = createBrookMarkdownString(() => props.text, () => ({ streaming: props.streaming }));
  return <BrookMarkdown client={client} />;
}
```

The Solid binding's mount/teardown logic is tested, but its JSX component shell
has so far only been exercised through a real Solid (`vite-plugin-solid`) build
in development, not in CI — treat it as the newest of the bindings and file an
issue if your Solid setup trips on it. The component is a thin `ref`'d `<div>`;
if you hit a transform edge, `mountBrookMarkdown` from `brookmd/dom` inside
`onMount`/`onCleanup` is the zero-surprise fallback.

## Server-side rendering

`<BrookMarkdown>` / `BrookClient` are browser-only (they spawn a Web Worker), but
the Rust→WASM core is a plain **synchronous** parser. So `brookmd/server` renders
**finished** markdown on the server with no worker and no async ceremony — Node
SSR, React Server Components, or a build step:

```ts
import { initBrook, renderToString } from "brookmd/server";

await initBrook();                                       // once at startup (loads the WASM)
const html = renderToString("# Hello\n\n**world**");   // sync HTML string, no worker
```

For React server rendering (RSC, static generation, or SSR), use
`<BrookMarkdownStatic>` from **`brookmd/server/react`** — a hookless, RSC-safe
component that renders finished content with the same `components` overrides
(inline/block component tags dispatch on the server too). It lives in its own
subpath so the core `brookmd/server` above stays importable with no `react`
installed:

```tsx
import { initBrook } from "brookmd/server";
import { BrookMarkdownStatic } from "brookmd/server/react";

await initBrook();
export default function Doc({ md }: { md: string }) {
  return (
    <BrookMarkdownStatic
      content={md}
      config={{ inlineComponentTags: ["tik"] }}
      components={{ tik: ({ symbol }) => <span className="ticker">{symbol}</span> }}
    />
  );
}
```

- **`initBrook()`** — async, idempotent. In Node it reads the package's `.wasm` off
  disk (Node's `fetch` can't load `file://`); on the web it fetches the
  bundler-resolved asset. On edge runtimes pass bytes yourself:
  `initBrookSync(wasmBytes)`.
- **`renderToString(md, { config })`** — synchronous HTML string, **zero React
  dependency** (imports cleanly with no `react` installed).
- **`parseToBlocks(md, { config })`** — the block array, for custom rendering.

**Document assembly.** A `Block.html` never ends with a newline — the terminator
that follows a top-level block belongs to the *document*, not the block.
`renderToString` therefore joins blocks with cmark's `cr()` rule: insert `\n`
before a block only when the output doesn't already end with one, and end the
document with one `\n`. An unconditional `"\n".join(...)` would double the
newline a raw HTML block serializes for itself. **If you assemble
`parseToBlocks` output into a document string yourself, use the same rule** —
it's what makes the output byte-identical to a reference CommonMark/GFM renderer
(652/652 CommonMark 0.31 and 24/24 GFM extension examples, byte-for-byte). See
`WIRE.md` §12.
- **`<BrookMarkdownStatic content config components />`** (from
  `brookmd/server/react`) — synchronous React tree for **render-once** contexts;
  render it with your framework's server renderer
  (`renderToStaticMarkup`, RSC, …). For live streaming, client-side code
  highlighting, or Mermaid, render `<BrookMarkdown>` on the client instead — it's a
  separate component. (If you SSR-then-hydrate, use the *same* component on both
  sides; the dedicated client renderers in `<BrookMarkdown>` don't hydrate
  `<BrookMarkdownStatic>`'s plainer markup.)

## What it does

| Concern | brookmd | conventional main-thread renderer |
|---|---|---|
| Re-parse on each token | No — only the active tail | Yes, full string |
| Where parse runs | Web Worker (off main thread) | Main thread |
| Block identity across chunks | Stable monotonic IDs | New keys on every render |
| Mid-stream unclosed `` ``` `` / `*` / `**` | Speculatively closed in render, replaced cleanly | Often renders raw or breaks |
| Half-streamed link `[label](https://…` | Label-only inert anchor (`data-brook-pending`), URL never leaks | Raw brackets + partial URL flash |
| Heavy renderers (syntax, math, mermaid) | Deferred until block close | Re-run per chunk |
| XSS sanitization | Allowlist in Rust + URL scheme check | Downstream sanitizer pass on the JS thread |

### Streaming links

A link's destination is the last thing a model emits — `[Earnings Call](https://…`
often spans many tokens. While a link is still streaming, brookmd renders it as
an **inert, label-only anchor**: the label text inside an `<a>` with no `href`
(the half-typed URL never flashes on screen), marked so you can style it:

```html
<a data-brook-pending="" target="_blank" rel="noopener noreferrer nofollow">Earnings Call</a>
```

An anchor without an `href` gets **no default link styling** from the browser, so
without a rule for the marker the link would "pop" blue only when the URL
completes. The bundled theme (`import "brookmd/styles.css"`) already styles it;
if you bring your own CSS, copy this:

```css
.brook-md a[data-brook-pending] {
  color: var(--brook-accent, #0969da); /* match your settled link's resting style */
  cursor: default;                    /* not clickable yet */
}
```

The moment the closing `)` arrives, the `href` appears and `data-brook-pending`
is dropped — committed and finalized output never carry the marker, and the
finished block is byte-identical to a one-shot parse. Two composition notes:
`urlTransform` runs only on a real `href`, so it never sees a half-streamed URL
prefix — only the complete one (it may run again on re-renders while the
surrounding block is still open); `decorators` skip text
inside `<a>` by default (`skipInside`), pending or not.

## Styling

brookmd emits semantic HTML under a `.brook-md` root and **ships no CSS by
default** — bring your own design system, or opt into the bundled theme:

```ts
import "brookmd/styles.css";
```

It gives good-looking output out of the box, **including the built-in syntax
highlighter's colors** (without any CSS, `highlight()` renders uncolored). The
theme is scoped to `.brook-md`, zero-runtime, and **does not change the rendered
HTML** — skip the import and nothing is styled.

> **Next.js Pages Router:** `brookmd/styles.css` is global CSS, which the Pages
> Router only allows importing from `pages/_app`. Import it there (App Router and
> other bundlers can import it from any component). Or skip it and bring your own
> `.brook-md` styles.

Re-theme by overriding a few CSS variables; it's light by default and switches to
dark automatically via `prefers-color-scheme` (force a mode with
`class="brook-md brook-dark"` or `brook-light`):

```css
.brook-md {
  --brook-accent: #7c3aed;   /* links */
  --brook-bg-code: #faf7ff;  /* code background */
  --brook-t-kw: #c026d3;     /* syntax: keywords (also --brook-t-str/num/com/fn/ty/…) */
}
```

### What the theme covers

Document elements, the highlighter's token colours (`.t-kw`, `.t-str`, …), the
pending-link marker — and *(since 0.30.0)* block spacing via `.brook-block` plus
the chrome the renderers emit: the code-block header and its controls
(`.brook-code-header`, `.brook-code-lang`, `.brook-code-copy`,
`.brook-code-streaming-pill`, `.brook-code-body`), the math and mermaid slots
(`.brook-math-*`, `.brook-mermaid-*`), GitHub-style alerts (`.markdown-alert*`),
and the footnote section. Writing your own CSS instead? Those are the class names
to target.

### Block-state classes

Every block the generic renderer emits is wrapped in a state-carrying element,
and these names are a **stable styling contract** — React, the DOM mount, and
the server renderer all emit the same ones:

| Class | Where | Means |
|---|---|---|
| `brook-md` | root | always present; `className` is appended to it |
| `brook-block` | every block wrapper | — |
| `brook-block-<kind>` | every block wrapper | the lowercased block kind: `brook-block-paragraph`, `brook-block-codeblock`, `brook-block-table`, `brook-block-mathblock`, … |
| `brook-open` | the streaming tail block | still growing — its HTML may change on the next patch |
| `brook-speculative` | a block closed by inference | may still be revised |
| `brook-streaming` | the code / math / mermaid slot | that renderer's own still-arriving state |
| `brook-bottom-anchor` | the `stickToBottom` sentinel | — |
| `brook-deferred` | root, while `deferTail` is deferring | — |

Use them to gate anything that must not run on half-arrived content — a KaTeX or
Mermaid pass skips `.brook-open` / `.brook-streaming` (see the [KaTeX
recipe](#math-with-katex)) — and to style the tail differently from settled text.

### Streaming caret

The theme ships an **opt-in** caret that follows the streaming tail. Add the
`brook-caret` class to the root; nothing else changes, and the rendered HTML is
identical with or without it:

```tsx
<BrookMarkdown client={client} className="brook-caret" />
```

```ts
mountBrookMarkdown(client, el, { className: "brook-caret" });
```

It is a `::after` bar on the last text element inside the `brook-open` block, so
exactly one caret is on screen. Code, math, and mermaid fences don't get one —
they already show a "streaming" pill. Retint it with `--brook-caret`, and it
stops blinking under `prefers-reduced-motion`. Bringing your own CSS? The
[block-state classes](#block-state-classes) are all it is built from.

### Tailwind / design systems

Two hooks, no wrapper components: `className` on the root, and the **element
path** of the [`components`](#custom-components--overrides) map for everything
inside a block. Overrides apply to the OPEN (streaming) block too, so the tail is
styled the whole way down instead of popping into place when it settles:

```tsx
import { BrookMarkdown, type Components } from "brookmd";

// HOIST it (module scope) or memoize. A fresh object each render busts the
// per-block memo, so every block re-parses on every patch — the single most
// expensive mistake you can make with this API.
const components: Components = {
  p: (p) => <p className="my-3 leading-7" {...p} />,
  ul: (p) => <ul className="my-3 list-disc pl-6" {...p} />,
  ol: (p) => <ol className="my-3 list-decimal pl-6" {...p} />,
  li: (p) => <li className="my-1" {...p} />,
  a: (p) => <a className="text-sky-600 underline underline-offset-2" {...p} />,
  h1: (p) => <h1 className="mt-6 text-2xl font-semibold" {...p} />,
  h2: (p) => <h2 className="mt-5 text-xl font-semibold" {...p} />,
  h3: (p) => <h3 className="mt-4 text-lg font-semibold" {...p} />,
  table: (p) => <table className="w-full border-collapse text-sm" {...p} />,
  code: (p) => <code className="rounded bg-slate-100 px-1 py-0.5" {...p} />,
  blockquote: (p) => <blockquote className="border-l-4 pl-4 italic" {...p} />,
};

<BrookMarkdown client={client} components={components} className="text-slate-900" />;
```

> **Using `@tailwindcss/typography`? Skip the theme import.** `.brook-md` is a
> plain `<div>`, so `class="prose brook-md"` works — but `brookmd/styles.css`
> resets `.brook-md > *` margins and sets its own type scale, which fights
> `prose`'s spacing. Pick one: the theme, or `prose` plus the token-colour
> variables (`--brook-t-kw`, …) if you still want the built-in highlighter's
> colours.

## Public API

### All entry points

Every subpath is independently importable; you pay only for what you import.

| Entry | What it is |
|---|---|
| `brookmd` | the common surface: `BrookClient`, `BrookPool`, `getDefaultPool`, `sourceFingerprint`, `BrookMarkdown`, `useBrookStream`, `useBrookMarkdownString`, `highlight`, `supportedLangs`, `htmlToReact`, `parseTrustedHtml`, `safeUrl`, `wrapLink` + the types (re-exports React, so it pulls `react`) |
| `brookmd/client` | framework-free core — `BrookClient`, `BrookPool`, `getDefaultPool`, `applyPatch`, `emptyBlockStore` |
| `brookmd/react` | `BrookMarkdown`, `useBrookStream`, `useBrookMarkdownString`, `blockKindProps` |
| `brookmd/server` | worker-free, **React-free** one-shot: `initBrook`, `initBrookSync`, `isBrookReady`, `renderToString`, `parseToBlocks` |
| `brookmd/server/react` | `BrookMarkdownStatic` — hookless, RSC-safe |
| `brookmd/dom` | `mountBrookMarkdown`, `tailOpenBlockId` |
| `brookmd/element` | `defineBrookMarkdown` (the `<brook-markdown>` Web Component) |
| `brookmd/vue` · `/svelte` · `/solid` | the framework bindings |
| `brookmd/highlight` | `highlight`, `supportedLangs`, `registerLanguage` *(since 0.30.0)* |
| `brookmd/html-to-react` | `htmlToReact`, `parseTrustedHtml`, `wrapLink`, `safeUrl` — render one block's HTML to a React tree yourself |
| `brookmd/block-props` | `blockProps`, `extractLang`, `htmlAttrs` — the framework-neutral block→props mapping the DOM renderer uses |
| `brookmd/worker-core` | `WorkerCore` — the worker's state machine, for hosting the parser in your own worker/runtime |
| `brookmd/types` | every type, value-free (`Block`, `ParserConfig`, `RenderMetrics`, `ListItemData`, `LinkClickInfo`, the wire types, …) |
| `brookmd/styles.css` | the optional theme |

### `BrookClient`

```ts
class BrookClient {
  constructor(options?: {
    pool?: BrookPool;
    config?: ParserConfig;
    onError?: (err: { message: string; fatal?: boolean }) => void; // worker/parse + WASM-init errors
    onBlock?: (block: Block) => void;                 // fires once per block as it commits
    coalesce?: boolean;                               // one rAF-scheduled notify per frame (default false)
    recovery?: boolean;                               // auto-heal a transient worker death (default true)
  });
  get failed(): Error | null;                       // terminal worker failure, else null (null through heals)
  append(chunk: string): void;                      // queue text for parsing
  pipeFrom(                                         // read → append → finalize
    src: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
    opts?: { signal?: AbortSignal },                // abort to supersede (no finalize)
  ): Promise<void>;
  finalize(): void;                                 // mark stream complete
  setContent(                                       // drive from a controlled full string
    full: string,                                   // diffs vs last: prefix → append delta; else seamless
    opts?: { done?: boolean },                      //   reset+reparse (view held, unchanged blocks keep identity)
  ): void;                                          // done:true → finalize
  reset(): void;                                    // wipe and reuse
  destroy(): void;                                  // free this stream's parser
  reattach(): void;                                 // re-register after destroy() (StrictMode double-mount)
  whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure
  subscribe(listener: () => void): () => void;      // React-friendly store
  getSnapshot(): Block[];                           // ordered current blocks
  getPersistable(source?: string): PersistableSnapshot;     // capture the rendered doc as JSON
  hydrate(                                                  // restore it: no worker, no parse
    snapshot: PersistableSnapshot,
    opts?: { source?: string },                             // source ⇒ a live thread can resume
  ): void;
  outline(): { level: number; text: string; id: number }[]; // heading table-of-contents (works mid-stream)
  toPlaintext(): string;                            // rendered document as plain text (search / summaries)
  getMetrics(): { bytes, patches, totalParseMs, throughputKBs,
                   retainedBytes, wasmMemoryBytes, ... };
}
```

`pipeFrom` is the LLM-native shortcut — hand it a `fetch` response and it
reads, appends, and finalizes for you:

```ts
const client = new BrookClient();
await client.pipeFrom(await fetch("/api/chat")); // streams the body in, then finalizes
```

Pass `onError` to be notified of worker/parse errors and a fatal WASM-init
failure (`{ fatal: true }`); without it, errors are only `console.error`'d and a
load failure surfaces as a rejected `whenReady()`. Pass `onBlock` to run a side
effect each time a block commits (e.g. lazy-highlight a finished code block).

Pass **`coalesce: true`** to collapse every patch that lands inside one frame
into a single `requestAnimationFrame`-scheduled notification, so a
`useSyncExternalStore` consumer renders at most once per frame instead of once
per patch. It is lossless (committed blocks are reference-stable, so only
superseded tail renders are skipped), the finalize patch always flushes
synchronously, and it degrades to synchronous emits where `requestAnimationFrame`
is unavailable (SSR, tests). The React hooks that own a client
(`useBrookStream` / `useBrookMarkdownString`) already set it; a client you
construct yourself defaults to `false`.

**`reattach()`** re-registers a client with the pool after `destroy()`. It exists
for React StrictMode's dev double-mount (destroy on the simulated unmount, then
the SAME instance remounts) — apps don't normally call it, and it is a no-op
while still attached.

A **transient worker death** heals invisibly by default: if a worker dies
mid-stream (e.g. a stale hashed worker URL 404s after a redeploy), the client
buffers the driven document, re-acquires a fresh worker, and re-feeds it once —
the view stays on screen and `onError` does **not** fire. Only if the replacement
also dies is the failure terminal (`onError` with `{ fatal: true }`, and
`client.failed` becomes the `Error`; it is `null` while healthy and through a
successful heal). Set `recovery: false` to disable the buffer and auto-recovery
(a fatal death is then immediately terminal) — worth it for memory-sensitive,
very large documents where retaining the full source is undesirable.

#### Per-stream config

```ts
const client = new BrookClient({
  config: {
    gfmAutolinks: true,   // bare www./http(s):// URLs + emails → links (default true)
    gfmAlerts: true,      // > [!NOTE] → callouts (default true)
    gfmTagfilter: false,  // GFM disallowed raw HTML: escape <script>/<title>/… under unsafeHtml (default false)
    gfmFootnotes: true,   // [^1] + [^1]: → footnote section (default false)
    gfmMath: true,        // $…$ / \(…\) inline + $$…$$ / \[…\] display math (default false)
    dirAuto: true,        // per-block dir="auto" for RTL/bidi text (default false)
    softBreaks: true,     // a single \n renders as <br> (the chat convention; default false)
    lenientLists: true,   // marker + 6+ SPACES → item text, not indented code (default false)
    a11y: true,           // task-list <label> + <th scope="col"> a11y markup (default false)
    unsafeHtml: false,    // pass raw HTML through (default false — keep it false for untrusted input)
    componentTags: ["Thinking", "Callout"], // BLOCK custom tags w/ markdown inside (default none)
    inlineComponentTags: ["tik", "cite"],   // INLINE custom tags (chips/citations) w/ markdown inside (default none)
    htmlAllowlist: ["br", "sub", "sup"],    // safe raw-HTML sanitizer: [] = allow all but dangerous; list = only those (default off)
    dropHtmlTags: [],                        // tags removed entirely (comments always dropped when sanitizing; default off)
    blockHtml: true,                         // extend the sanitizer to BLOCK raw HTML (<details>…); needs a list above (default false)
    allowSchemes: ["file"],                  // un-block a default-blocked URL scheme (default none — see "Security")
    blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
    retainCommittedHtml: false, // keep committed HTML inside the parser too (default false on the streaming path)
  },
});
```

Omitted fields use the defaults above, so `new BrookClient()` is unchanged.
Config is applied when the stream's parser is created and is **immutable** for
that stream (`reset()` keeps it; use a new client for different flags).

When to enable each flag:

- `gfmAutolinks` — on by default. Leave it on unless you want strict CommonMark.
- `gfmAlerts` — on by default. Leave it on unless you want strict CommonMark.
- `gfmMath: true` — when your LLM emits `$…$` or `$$…$$` (or LaTeX `\(…\)` /
  `\[…\]`). brookmd emits KaTeX-ready markup; you bring the KaTeX pass (or
  `components.MathBlock`).
- `gfmFootnotes: true` — when your input uses `[^1]` references and `[^1]:`
  definitions. Off by default; see the footnote streaming caveat above.
- `dirAuto: true` — when content can be RTL / mixed-direction. Emits per-block
  `dir="auto"` so the browser detects direction independently per block.
- `lenientLists: true` — when your LLM over-indents after a list marker. Strict
  CommonMark (§5.2) says a marker followed by **5 or more** columns of
  whitespace starts an indented code block, so a model writing
  `-       const value = 1;` renders as a `<pre><code>` block instead of a list
  item. This flag raises that cutoff to **6 columns of literal spaces**: at 6+
  the padding is absorbed into the item's content column and the text renders
  as the item's own markdown (inline formatting, links, and nested lists all
  parse normally). Off by default, so strict-CommonMark output is unchanged.

  Four cases stay strictly conformant **by design** — the flag is deliberately
  narrow, not a general "fix my indentation" pass:

  | Input | Stays | Why |
  | --- | --- | --- |
  | `-` + exactly 5 spaces | code block | 5 columns is the §5.2 boundary itself; relaxing it would swallow genuine one-space-past-the-minimum code |
  | `` - ```js `` (fence on the marker line) | fenced code | the marker line opens a real fence — there is no over-indentation to undo |
  | `-` then code indented on a **later** line | code block | the decision reads only the marker's own line; a later-line indent is unambiguous authored code |
  | `-\t\tfoo` (tab padding) | code block | tab padding is a deliberate authoring choice, unlike model over-indentation which is always literal spaces |

  Excluding tabs is what keeps the divergence from CommonMark down to a single
  spec example (274, `1.` + 6 spaces). Everything else in the 652-example suite
  renders identically with the flag on or off; the conformance suites
  themselves run in strict mode and are unaffected.

  The rule is a pure per-line comparison made when the marker is first scanned,
  so it costs no lookahead and no re-parse while streaming.
- `a11y: true` — opt-in accessibility markup that deviates from strict GFM
  byte-output: wraps task-list checkboxes in a `<label>` (screen-reader
  association) and adds `scope="col"` to table headers. Off by default so
  conformance output stays exact.
- `unsafeHtml: true` — only when rendering trusted HTML. For untrusted /
  LLM-produced HTML, pair this with `<BrookMarkdown sanitize={…} />` (DOMPurify or
  similar — see [Security](#security)).
- `gfmTagfilter: true` — the GFM "Disallowed Raw HTML" extension, for use with
  `unsafeHtml`: the nine disallowed tags (`<title>`, `<textarea>`, `<style>`,
  `<xmp>`, `<iframe>`, `<noembed>`, `<noframes>`, `<script>`, `<plaintext>`) get
  their leading `<` escaped so they display as text instead of taking effect —
  opening and closing forms, any case, in blocks and inline. Off by default
  (strict CommonMark passes them through under `unsafeHtml`); it's a tag
  denylist, **not** a sanitizer — untrusted input still wants `sanitize`.
- `componentTags: ["Thinking", …]` — when your LLM emits **block** custom tags
  like `<Thinking>…</Thinking>` (on their own line) and you want their inner
  content parsed as markdown and dispatched to a React component. Safe without
  `unsafeHtml` (attributes are sanitized; allowlisted tags only).
- `inlineComponentTags: ["tik", …]` — same idea for **inline** custom elements
  that sit inside a paragraph, heading, list item, or **table cell** (ticker
  chips, citations, `@mentions`). See [Inline component tags](#inline-component-tags).
- `htmlAllowlist` / `dropHtmlTags` — render a **safe subset of raw HTML** (e.g.
  `<br>`, `<sub>`, `<sup>`) natively without `unsafeHtml`, drop specific tags, and
  drop HTML comments. See [Safe raw HTML](#safe-raw-html).
- `blockHtml: true` — extend that sanitizer to **block-level** raw HTML, so a
  `<details><summary>…</summary>…</details>` block renders as real elements
  instead of an escaped code block. Needs one of the two lists above to be set;
  `<script>`/`<pre>`/`<style>`/`<textarea>` blocks stay escaped. See
  [Block-level raw HTML](#block-level-raw-html-blockhtml).
- `allowSchemes: ["file"]` — un-block a URL scheme brookmd blocks by default,
  for privileged hosts (Electron, extensions) that intercept link clicks instead
  of navigating. Script-executing schemes can never be re-enabled. See
  [Un-blocking a scheme](#un-blocking-a-scheme--allowschemes).
- `retainCommittedHtml: true` — keep every committed block's rendered HTML
  **inside the parser** as well. Off on the streaming path, which is what you
  want: the client receives each committed block exactly once and stores it
  itself, so a second copy in WASM serves nobody — dropping it roughly halves a
  long stream's `getMetrics().retainedBytes`, and the wire is byte-identical
  either way. Turn it on only if something reads the whole rendered document back
  out of the parser. The server renderers (`renderToString` / `parseToBlocks`) do
  exactly that and pin it on regardless of what you pass.

**Footnotes** (`gfmFootnotes`) work in streaming with one honest caveat: a
`[^1]` reference renders speculatively the moment it's seen (committed blocks
can't re-render), and the footnote **section is emitted at finalize**. So a
reference whose definition never arrives leaves a dangling link — the same
forward-reference cost as link reference definitions. Multiple references to
the same footnote each get a **unique id** (`fnref-N`, `fnref-N-2`, …) and the
definition lists **one backref per reference**. Remaining v1 limits:
single-block definitions (no continuation-indent / multi-paragraph) and no
nested footnotes. The section uses GitHub-style markup
(`<section class="footnotes">`, `<sup class="footnote-ref">`).

**Math** (`gfmMath`) recognizes both delimiter families LLMs emit — `$…$` /
`$$…$$` and LaTeX `\(…\)` / `\[…\]`. Inline math renders to
`<span class="math math-inline">…</span>`, display math to
`<div class="math math-display">…</div>` (and inline display to a `math-display`
span), each carrying the **HTML-escaped LaTeX as its text content** — exactly
what [KaTeX](https://katex.org)'s auto-render expects. brookmd
stays **zero-dep**: it produces the KaTeX-ready markup and never processes the
body as markdown; you bring the KaTeX pass (or override `components.MathBlock`,
which receives the raw LaTeX as `text`). Single `$` uses the **pandoc rule** so
prose and currency stay literal — the opener needs a non-space to its right, the
closer a non-space to its left and no digit after it, so `$5 and $10` is **not**
math. A `$$`/`\[` block is **blank-line tolerant** (multi-line `\begin{aligned}…`
stays one block) and renders incrementally while streaming, like a code fence.
Off by default (so `$` in plain prose is untouched) — enable it per stream when
your model emits LaTeX.

**Bidirectional text** (`dirAuto`) emits `dir="auto"` on each block-level text
element (`p`, `h1`–`h6`, `blockquote`, `ul`/`ol`/`li`, `table`), so the browser
runs the Unicode bidi algorithm **per block** — an Arabic/Hebrew paragraph
renders RTL while the English one beside it stays LTR, with no JS direction
detection. Code blocks never get it (code is always LTR). This is the per-block
model GitHub uses; it's the right fix for the common failure mode of detecting
one direction for a whole mixed-language document. Off by default (strict
CommonMark output is unchanged); turn it on for RTL or mixed-direction content.

### `BrookMarkdown` (React)

Subscribes to a `BrookClient`, renders each block keyed by its stable parser-assigned ID. Memoized so unchanged blocks never re-reconcile.

```tsx
<BrookMarkdown client={client} />
```

The root element accepts opt-in `className` (appended to the always-present
`brook-md` root class), `id`, `role`, and `aria-live` / `aria-atomic`. Set
`aria-live="polite"` to make the output a live region so screen readers announce
streamed content as it settles — `polite` coalesces rapid updates and does **not**
read every token. The same options exist on the DOM mount
(`mountBrookMarkdown(client, el, { ariaLive: "polite" })`), covering the Web
Component and the Vue/Svelte/Solid adapters.

#### Props

| Prop | Type | Default | What it does |
|---|---|---|---|
| `client` | `BrookClient` | — | A client you own and drive; the component never destroys it. |
| `stream` | `AsyncIterable<string> \| ReadableStream<Uint8Array> \| Response` | — | 1-line mode: the component owns an internal client. Exactly one of `client` / `stream` is required (neither → throws); `client` wins if both are given. |
| `streamConfig` | `ParserConfig` | — | [Per-stream config](#per-stream-config) for that internally created client (stream mode only). |
| `onStreamError` | `(err: Error) => void` | — | The `stream` source rejected. Worker/parse errors go to the client's `onError` instead. |
| `components` | `Components` | — | [Overrides](#custom-components--overrides). **Hoist it.** |
| `decorators` | `Decorator[]` | — | [Inline text decorators](#inline-text-decorators). **Hoist it.** |
| `urlTransform` | `UrlTransform` | — | Rewrite `href`/`src`/`poster`; the output is re-sanitized. **Hoist it.** |
| `sanitize` | `(html: string) => string` | — | Runs on every block's HTML **including the open tail**. **Hoist it.** |
| `streamingHighlight` | `boolean \| "wavefront" \| "eager"` | `"wavefront"` | [Where the colour front sits](#where-the-colour-front-sits-wavefront-default-vs-eager). |
| `virtualize` | `boolean` | `false` | `content-visibility: auto` on closed blocks — [long documents](#long-documents--virtualize). |
| `stickToBottom` | `boolean` | `false` | Emits the scroll-snap anchor — [stick to bottom](#stick-to-bottom-while-streaming--sticktobottom). |
| `deferTail` | `boolean` | `false` | Route the block list through React's `useDeferredValue`, so a burst of patches can yield to higher-priority updates; the root carries `brook-deferred` while a deferred render is in flight. Commit timing only — output is unchanged. rAF coalescing (`coalesce`) is the preferred way to absorb patch bursts. |
| `childMemo` | `boolean` | `false` | On an OPEN block, reuse the React nodes of top-level children whose HTML hasn't changed and re-parse only the new trailing content. Applies only when `components`/`sanitize` route the block off the `innerHTML` fast path; byte-identical either way. Worth it for a long, slowly growing streamed block under a custom map. |
| `className` / `id` / `role` | `string` | — | Set on the root; `className` is appended to `brook-md`. |
| `aria-live` / `aria-atomic` | `"off" \| "polite" \| "assertive"` / `boolean` | off | Live-region attributes — see [Accessible chat](#accessible-chat). |
| `onLinkClick` | `(event, link) => void` | — | Delegated link clicks — see [Intercepting link clicks](#intercepting-link-clicks--onlinkclick). *(since 0.30.0)* |
| `onRenderMetrics` | `RenderMetricsHook` | — | Fires once per ACTUAL block render with `{ renderCount, speculativeToggleCount, lastRenderMs, kind }` — render-churn instrumentation; a committed block that memo-skips never fires. Zero cost when omitted. **Hoist it.** |
| `onBlockError` | `(error, info) => void` | — | Per-block error boundary hook — see [`onBlockError`](#onblockerror). **Hoist it.** |

#### Accessible chat

Make the assistant's message a polite live region and mark it busy while it
streams:

```tsx
<div role="log" aria-live="polite" aria-busy={streaming}>
  <BrookMarkdown client={client} />
</div>
```

- `aria-live="polite"` announces content as it settles rather than reading every
  token. Put it on the container you own (as above) or on the root via the
  `aria-live` prop — one live region, not both.
- Turn on `a11y: true` in the [per-stream config](#per-stream-config): task-list
  checkboxes get a `<label>` (so the checkbox and its text are associated) and
  table headers get `scope="col"`.
- Flip `aria-busy` back to `false` when the stream finalizes, so assistive tech
  knows the message is complete. Where focus goes when a message lands is your
  app shell's decision, not the renderer's.

#### Custom components / overrides

Pass a `components` map to replace how elements render. Keys come in **two
namespaces**:

```tsx
import { useMemo } from "react";
import { BrookClient, BrookMarkdown, type Components } from "brookmd";

function Message({ client }: { client: BrookClient }) {
  // Memoize (or hoist to module scope). A fresh object every render busts
  // BrookMarkdown's block memo, so every block re-parses on every patch.
  const components: Components = useMemo(
    () => ({
      // tag-level (lowercase HTML names) — applied inside a block's HTML
      table: (props) => <table className="rounded border" {...props} />,
      a: (props) => <a target="_blank" rel="noreferrer" {...props} />,
      h1: "h2", // a string value just swaps the tag

      // block-kind (capitalized BlockKindTag) — replaces the whole block
      CodeBlock: ({ text, language, open }) => (
        <MyCodeBlockWithCopyButton code={text} lang={language} streaming={open} />
      ),

      // GitHub alerts (`> [!NOTE]` / `[!TIP]` / `[!WARNING]` / `[!CAUTION]` /
      // `[!IMPORTANT]`) — swap in your own callout component. The alert kind
      // is on `block.kind.data.kind`; `html` is the rendered inner body.
      Alert: ({ block, html }) => (
        <MyCallout kind={(block.kind.data as { kind: string }).kind}>
          <div dangerouslySetInnerHTML={{ __html: html }} />
        </MyCallout>
      ),
    }),
    [],
  );
  return <BrookMarkdown client={client} components={components} />;
}
```

**Tag-level** keys (`table`, `thead`, `tr`, `td`, `a`, `code`, `pre`, `h1`–`h6`,
`ul`, `ol`, `li`, `blockquote`, `p`, `img`, `del`, `input`, `hr`, …) replace that
element wherever it appears. The component receives the element's parsed
attributes (with `class`→`className` and `style` as an object) plus `children`.

**Block-kind** keys (`CodeBlock`, `Mermaid`, `MathBlock`, `Alert`, `Paragraph`,
`Heading`, `List`, `Blockquote`, `Table`, `Rule`, `Html`) replace the entire
block. The component receives [`BlockComponentProps`](#types): `{ block, html,
open, speculative }`, plus `text`/`language` for code/math blocks — and `meta`,
the rest of a fence's info string (```` ```ts title="src/main.ts" ````), for a
filename header (the alert type is at `block.kind.data.kind`).

> **One map, two prop contracts — the single biggest footgun.** The keys above
> are looked up by TWO dispatchers. The block-kind dispatcher passes
> `BlockComponentProps` (with `block`); the element dispatcher, which is what
> makes `a` / `code` / `table` overrides work, passes **the element's attributes
> and `children` only — no `block`**. The same name can hit both: an
> `inlineComponentTags` chip, or a `componentTags` tag that lands inside a list
> item or blockquote (where it is a real *nested* Component block, rendered as an
> element inside its container's HTML), takes the element path. So an override
> that reads `props.block.…` throws `can't access property "kind", block is
> undefined` for those occurrences — intermittently, because it depends on where
> the model happened to put the tag.
>
> Write any override for a name that can appear in both positions defensively:
>
> ```tsx
> const Thinking = ({ block, children }) =>
>   block ? <Panel data={block.kind.data}>{children}</Panel> : <span>{children}</span>;
> ```
>
> Three things make this survivable rather than fatal: block-kind keys are typed
> to `BlockComponentProps`, so a mismatched override is a **compile** error; a raw
> element whose name collides with a block-kind key (`<Table>`, `<Alert>`… — only
> reachable with raw-HTML passthrough on) is never dispatched to that override;
> and every block renders inside its own **error boundary**, so a throwing
> override costs that one block instead of unmounting the document. Wire
> [`onBlockError`](#onblockerror) to see them.

Rules worth knowing:

- **There is no `node` prop / no syntax tree.** Introspect via `className` /
  `data-*`, or — better — opt into the typed **[structured-data
  channel](#structured-block-data-setblockdata)** (`blockData: true`) and read
  `block.kind.data` (and the typed `props.table` / `heading` / `code` / `math` /
  `list` fields) directly — no HTML re-parsing.
- **Overrides apply to the OPEN (streaming) block too**, not just settled ones —
  so a design-system renderer (Tailwind classes on `p`/`ul`/`li`, inline
  `<a>`/`<code>` overrides) stays styled mid-stream. The tail's HTML is always
  well-formed (the parser speculatively closes it). If a `sanitize` is supplied
  it runs first, on every block.
- **No `components` prop ⇒ the original fast path** (`innerHTML`, byte-identical
  output). The HTML→React conversion runs only when you actually supply
  overrides, and is memoized per `(block id, html)` so committed blocks don't
  re-parse as the stream grows.
- For **code blocks** the built-in highlighter is the default; it is bypassed
  (so your override wins) when you pass `components.CodeBlock`, `components.pre`,
  or `components.code`.

#### Inline text decorators

Wrap or replace matched inline **text** while streaming — e.g. bold financial
figures — without writing your own HTML re-parser. A `decorators` entry runs
POST-parse on real inline **text nodes only** (never URLs, code, or markup), once
per committed block, so a long document stays **O(n)**.

```tsx
import { BrookMarkdown, wrapLink } from "brookmd";

// HOIST it (module scope) or memoize — a fresh identity each render busts the
// per-block memo and re-decorates every block on every patch (a dev warning fires).
const decorators = [
  { match: /\$[\d.]+[BMK]|FY\d{4}|\d+(?:[-–]\d+)?%/g, replace: (t) => <mark>{t}</mark> },
  // Linkify a ticker — route the href through the safe helper (see below):
  { match: /\$[A-Z]{1,5}\b/g, replace: (t) => wrapLink(t, { href: `/sym/${t.slice(1)}` }) },
];

<BrookMarkdown client={client} decorators={decorators} />;
```

- **Trusted surface — not sanitized.** A decorator's `replace` output is spliced
  straight into the tree and does **not** pass through brookmd's attribute sanitizer
  (React renders a `javascript:` href without complaint). Treat `decorators`
  exactly like `components`: build only trusted nodes, and route any link href
  through `wrapLink` or the exported `safeUrl`.
- **`skipInside`** defaults to `['a','code','pre','kbd']`; override per decorator.
- **Per-text-node.** A value split by inline markup (e.g. `$2.<em>5</em>B`) is two
  text nodes and won't match across them — match against settled, contiguous text.
- Matching is pure and stateless, so a value streamed char-by-char decorates
  **identically** to a one-shot render. Same API on `brookmd/dom`
  (`mountBrookMarkdown(client, el, { decorators })`); a decorator there returns a
  `Node` or string.

`urlTransform?: (url, { tag, attr }) => string` rewrites `href`/`src`/`poster`
URLs as blocks render (proxy images, add UTM params). Its output is re-sanitized
(`safeUrl(urlTransform(safeUrl(value)))`), so a buggy transform can never emit a
`javascript:` / `data:text/html` URL. Hoist/memoize it for the same reason as
`decorators`.

#### Math with KaTeX

With `gfmMath: true` brookmd emits KaTeX-ready markup and stays zero-dep — you
run the typesetting pass. Typeset each `.math` element **once its block has
closed**: an open block holds partial LaTeX, and feeding KaTeX a half-typed
formula throws on every patch. One observer over the scroller covers every
message in the thread:

```tsx
import { useEffect, useRef, type ReactNode } from "react";
import katex from "katex";

export function MathPass({ children }: { children: ReactNode }) {
  const root = useRef<HTMLDivElement>(null);
  useEffect(() => {
    const el = root.current;
    if (!el) return;
    const pass = () => {
      el.querySelectorAll<HTMLElement>(".math:not([data-tex])").forEach((node) => {
        if (node.closest(".brook-streaming, .brook-open")) return; // still streaming
        node.setAttribute("data-tex", "1");                        // idempotence marker
        try {
          katex.render(node.textContent ?? "", node, {
            displayMode: node.classList.contains("math-display"),
            throwOnError: false,
          });
        } catch {
          /* leave the raw LaTeX in place */
        }
      });
    };
    const obs = new MutationObserver(pass);
    obs.observe(el, { childList: true, subtree: true });
    pass();
    return () => obs.disconnect();
  }, []);
  return <div ref={root}>{children}</div>;
}
```

The two non-obvious parts are the `.brook-streaming, .brook-open` skip (see
[block-state classes](#block-state-classes)) and the `data-tex` marker, which
stops the observer re-typesetting what it already rendered. Prefer per-block
control? `components.MathBlock` receives the decoded LaTeX as `props.text`.

#### Mermaid diagrams

`Mermaid` is a block **slot**: brookmd renders the diagram source and never calls
a renderer. Render it as plain text while the fence is open and call
`mermaid.render` only once it closes — a half-arrived diagram throws on every
patch. The slot carries the fence's rendered `<pre><code>`, so the source is its
text content:

```tsx
import { useEffect, useState } from "react";
import mermaid from "mermaid";
import type { BlockComponentProps, Components } from "brookmd";

// brookmd's own escaped output — the text content IS the diagram source.
function mermaidSource(html: string): string {
  const el = document.createElement("div");
  el.innerHTML = html;
  return el.textContent ?? "";
}

const components: Components = {
  Mermaid: ({ html, open, block }: BlockComponentProps) => {
    const [svg, setSvg] = useState("");
    const source = mermaidSource(html);
    useEffect(() => {
      if (open || !source) return;
      let live = true;
      mermaid
        .render("brook-mermaid-" + block.id, source)
        .then((r: { svg: string }) => { if (live) setSvg(r.svg); })
        .catch(() => { /* keep the source on screen */ });
      return () => { live = false; };
    }, [open, source, block.id]);
    if (open || !svg) return <pre className="brook-mermaid-body">{source}</pre>;
    return <div dangerouslySetInnerHTML={{ __html: svg }} />;
  },
};
```

#### Bring your own highlighter

`components.CodeBlock` (or `components.pre` / `components.code`) bypasses the
built-in highlighter entirely. If yours is async, render plain while the fence is
open and highlight once on close — never per patch:

```tsx
import { useEffect, useState } from "react";
import type { BlockComponentProps, Components } from "brookmd";
import { highlightToHtml } from "./my-highlighter"; // (code, lang) => Promise<string>

const components: Components = {
  CodeBlock: ({ text = "", language, open }: BlockComponentProps) => {
    const [html, setHtml] = useState<string | null>(null);
    useEffect(() => {
      if (open) return;
      let live = true;
      highlightToHtml(text, language || "text").then((h) => { if (live) setHtml(h); });
      return () => { live = false; };
    }, [open, text, language]);
    if (open || html === null) return <pre><code>{text}</code></pre>;
    return <pre dangerouslySetInnerHTML={{ __html: html }} />;
  },
};
```

An override gives up the incremental streaming highlighter (the fence stays plain
until it closes). If all you need is one more language, keep the fast path and
register it instead — see [`registerLanguage`](#highlightcode-lang).

#### Interactive task lists

GFM task-list checkboxes are emitted `disabled` (`<input checked="" disabled=""
type="checkbox">`) because that is GFM's byte-exact output. Override the `input`
tag to make them live:

```tsx
import type { Components } from "brookmd";

const components: Components = {
  input: (p: { type?: string; checked?: boolean }) =>
    p.type === "checkbox" ? (
      <input type="checkbox" checked={!!p.checked} onChange={onToggle} />
    ) : (
      <input {...p} />
    ),
};
```

The rendered markup is a **view** of the markdown: to persist a toggle, flip
`[ ]` ⇄ `[x]` in your source string and re-feed it with `setContent`. With
`blockData: true`, a `List` block's `props.list.items[i].start` is the
document-absolute offset of that item's marker, which is enough to locate the
checkbox to rewrite (nested items carry no offset).

#### Lazy images

```tsx
const components = { img: (p: any) => <img loading="lazy" decoding="async" {...p} /> };
```

Pair it with `urlTransform` if you also proxy or resize remote image URLs.

### Structured block data (`setBlockData`)

Set `blockData: true` in the per-stream config and each block carries typed
structured data on `block.kind.data`, also surfaced as typed fields on the
component props — so you build toolbars, tables of contents, charts, copy
buttons, etc. from **data**, never by re-parsing the rendered HTML or walking
a syntax tree. Off by default; when off, output and CommonMark/GFM conformance are
byte-identical, so non-users pay nothing.

| Kind | `block.kind.data` | prop | use |
|------|-------------------|------|-----|
| `Table` | `{ headers, rows, aligns }`, cells `{ text, html }` | `props.table` | sort / filter / transpose / CSV / chart |
| `Heading` | `{ level, text, id }` | `props.heading` | table of contents with anchors |
| `CodeBlock` | `{ lang, meta?, code }` | `props.code` | decoded source (copy / run) |
| `MathBlock` | `{ latex }` | `props.math` | LaTeX source (re-render) |
| `List` | `{ ordered, start?, items? }`, items `{ html, start? }` | `props.list` | ordered-list numbering; `items[i].start` is the document-absolute offset of that top-level item's marker (absent for nested items) |
| `Blockquote` / `Alert` | `{ nested }` (Alert also `{ kind }`), each `{ html }` | `props.container` | render inner sub-blocks KEYED, so a streaming quote re-renders only its open last child |

Each cell's `text` is inline-stripped plaintext (for sort/filter/CSV/logic);
`html` is the inline-rendered display HTML. The data **streams** with the
document — a growing table or a heading carries its structured data on every
patch, in lock-step with the HTML — something a batch HTML-AST cannot do.

```tsx
// Table of contents from heading data — no DOM, works mid-stream:
const toc = client.getSnapshot()
  .filter((b) => b.kind.type === "Heading" && b.kind.data)
  .map((b) => b.kind.data as { level: number; text: string; id: string });
```

#### Table toolbar (CSV / copy)

`props.table` is the whole table as data, so a toolbar is a pure function of it —
no HTML re-parse — and it keeps working **while the table streams**, because the
override is invoked on open blocks too and `rows` grows as they arrive:

```tsx
import type { BlockComponentProps, Components, TableData } from "brookmd";

// RFC 4180: quote any field containing a comma, quote, or newline, and double
// internal quotes. Built from each cell's plaintext `text` — never the display HTML.
function toCsv(table: TableData): string {
  const quote = (v: string) => (/[",\n]/.test(v) ? '"' + v.replace(/"/g, '""') + '"' : v);
  const line = (cells: { text: string }[]) => cells.map((c) => quote(c.text)).join(",");
  return [line(table.headers), ...table.rows.map(line)].join("\n");
}

const components: Components = {
  Table: ({ table, html, open }: BlockComponentProps) => (
    <figure className="table-card">
      {table && (
        <button onClick={() => navigator.clipboard.writeText(toCsv(table))}>
          {open ? "Copy CSV (so far)" : "Copy CSV"}
        </button>
      )}
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </figure>
  ),
};
```

Needs `blockData: true` (with it off `props.table` is `undefined` — guard as
above). The same data drives sort, filter, transpose and charts: `text` is the
plaintext to compute on, `html` the markup to display.

### Component tags

LLMs increasingly emit custom component tags like `<Thinking>…</Thinking>`. By
default these are inert (escaped, or — with `unsafeHtml` — raw HTML whose body
is *not* markdown). Opt in by allowlisting the tag names:

```tsx
const client = new BrookClient({ config: { componentTags: ["Thinking", "Callout"] } });
```

Now a listed tag is a **markdown container**: its inner content is parsed as
markdown, it spans blank lines up to its matching close tag (not split like a
raw HTML block), it nests, and a `</Tag>` inside a code fence stays content. It's
**safe without `unsafeHtml`** — the tag is allowlisted and its attributes are
sanitized (event handlers dropped, dangerous URL schemes → `#`).

Each renders as a `Component` block. Override it in React by tag name (or with
the generic `Component` fallback). The override receives `tag`, the sanitized
`attrs`, the inner content as ready-to-render **`children`** (the easy path), and
also `html` (the inner already-rendered markdown string, for
`dangerouslySetInnerHTML`):

```tsx
<BrookMarkdown
  client={client}
  components={{
    Thinking: ({ children }) => (
      <details className="thinking">
        <summary>Reasoning</summary>
        {children}
      </details>
    ),
  }}
/>
```

> **`children` vs `html`.** A `Component` override that renders *neither* shows
> **empty** (a common first-try gotcha). Prefer **`children`** — a parsed React
> tree with nested overrides applied; reach for `dangerouslySetInnerHTML={{ __html:
> html }}` only when you need the raw string. `attrs` keys are React-form
> (`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly. While
> streaming, both reflect the partial inner content and re-render as more arrives.
> With no override the block renders as `<thinking …>…</thinking>`. Tag names
> match case-sensitively; off unless `componentTags` is set.

<a id="inline-component-tags"></a>

#### Inline component tags

`componentTags` handles **block** containers (a `<Thinking>` on its own line). For
**inline** custom elements — ticker chips, citations, `@mentions`, inline tooltips
that sit *inside* a paragraph, heading, list item, or **table cell** — use
`inlineComponentTags`:

```tsx
const client = new BrookClient({ config: { inlineComponentTags: ["tik"] } });

<BrookMarkdown
  client={client}
  components={{
    tik: ({ symbol, children }) => <span className="ticker">{children ?? symbol}</span>,
  }}
/>;
```

Now `Apple <tik symbol="AAPL">AAPL</tik> rose 2%` (or self-closing
`<tik symbol="AAPL"/>`) dispatches the inline `<tik>` to `components.tik`: its
inner is parsed as **inline markdown** (the `children`), its attributes become
props, and it's **safe without `unsafeHtml`** (attributes sanitized, allowlisted
tags only). It works everywhere inline content does — **including table cells**.
Tag names match **case-sensitively** and dispatch verbatim to `components[tag]`
(`<tik>`→`components.tik`, `<Cite>`→`components.Cite`). The
two lists are independent: list a tag under `componentTags` for blocks,
`inlineComponentTags` for inline, or both for both.

Where an allowlisted tag actually lands:

| Position | Result |
| --- | --- |
| Own line, top level | block `Component` — override gets `BlockComponentProps` |
| Own line inside a list item / blockquote | real **nested** Component block, emitted as an element inside the container's HTML — the override is dispatched by **element name**, so it gets attributes + `children` and **no `block`** |
| Mid-paragraph, listed in `inlineComponentTags` | inline element — attributes + `children`, no `block` |
| Mid-paragraph, NOT listed in `inlineComponentTags` | escaped text |
| Inside a table cell | escaped text (cells are inline-only) |

An allowlisted tag in a position that is not supported degrades **inertly**
(escaped) — it never consumes surrounding content. But note rows 2 and 3: those
DO render, through the element path, which is why an override that reads
`props.block` must guard for its absence (see [the two prop
contracts](#custom-components--overrides)).

> **Link-bridge alternative.** Before `inlineComponentTags`, the way to get an
> inline custom element was the link bridge: emit `[$AAPL](tik://AAPL)` and
> override `a` to render a chip when the href scheme matches. It's XSS-safe and
> renders inline-in-cells too — `inlineComponentTags` simply replaces that
> workaround with first-class inline elements.

### Safe raw HTML

LLMs emit a little raw HTML — `<br>`, `<sub>`/`<sup>`, `<mark>`, and HTML comments
as markers (`<!--mk:id-->`). `unsafeHtml` is all-or-nothing; instead opt into a
**sanitizer** that renders a safe subset natively. Setting `htmlAllowlist` and/or
`dropHtmlTags` (even to `[]`) engages it:

```ts
// Render only these inline tags; escape everything else:
new BrookClient({ config: { htmlAllowlist: ["br", "sub", "sup", "mark"] } });

// Or allow everything except a built-in dangerous set:
new BrookClient({ config: { htmlAllowlist: [] } });
```

- **HTML comments are dropped** — no more `<!--mk:id-->` surfacing as escaped text
  — in every mode except bare `unsafeHtml` pass-through.
- **`htmlAllowlist: ["br", …]`** renders only those inline tags; everything else is
  escaped. **`htmlAllowlist: []`** (empty) allows *all* tags **except a built-in
  dangerous set** (`script`, `style`, `iframe`, `object`, `embed`, `form`, `svg`,
  `xmp`, `plaintext`, … — **non-overridable**: allowlisting one still drops it).
- **`dropHtmlTags: ["mk", …]`** removes those tags entirely (markup gone; inner
  text stays as inert text).
- Every rendered tag's **attributes are sanitized**: `on*` handlers and `style`
  (a CSS beacon / clickjacking vector) are dropped, and dangerous URL schemes
  (`javascript:`, …, including multi-encoded) become `#` — in `href`, `src`,
  `srcset`, `poster`, `cite`, `action`, `data`, `longdesc` and `background`.
- A further set of **DOM-hazard attributes is dropped outright** (case-insensitive)
  — they neither execute nor carry a URL, but each lets authored markup reach
  past the text it should be:
  `srcdoc` (inline document injection), `is` (customized-built-in upgrade),
  `autofocus` / `contenteditable` (focus-steal, UI spoof), `id` / `name` (DOM
  clobbering — an element shadowing `document.getElementById` or a global),
  `slot` / `part` / `exportparts` (shadow-DOM injection), `form`, `formaction`,
  `formenctype`, `formmethod`, `formnovalidate`, `formtarget` (form hijack),
  `xmlns` / `xlink:*` (namespace escape hatch), and `ping` (tracking beacon).
  Some are inert *today* only because the tag that gives them meaning is already
  in the dangerous set — they are dropped anyway so the policy never depends on
  that coincidence. `class`, `title`, `alt`, `target`, `rel`, `data-*` and
  `aria-*` are unaffected.
- **This applies to raw HTML only.** [Component tags](#component-tags) stay
  permissive: their attributes become framework *props* on `components[tag]`, so
  `<Tab id="x">` keeps `id` — the consumer's component decides whether it ever
  reaches the DOM. `on*`, `style` and dangerous URL schemes are filtered there too.
- **Scope:** *inline* raw HTML by default. Block-level raw HTML stays escaped
  unless you also set `blockHtml` (below). Tag matching is case-insensitive.

#### Block-level raw HTML (`blockHtml`)

A model that emits a disclosure widget on its own lines —

```html
<details>
<summary>Sources</summary>
Three filings and a transcript.
</details>
```

— produces an *HTML block*, not inline HTML, so the sanitizer above leaves it
escaped. Opt in with `blockHtml` and it renders as real elements:

```ts
new BrookClient({ config: { htmlAllowlist: [], blockHtml: true } });
// or restrict it:
new BrookClient({ config: { htmlAllowlist: ["details", "summary"], blockHtml: true } });
```

- **Only meaningful with the sanitizer engaged.** `blockHtml` on its own does
  nothing; it extends `htmlAllowlist` / `dropHtmlTags` to block level. Default
  `false`, so existing sanitizer users keep escaped block HTML until they opt in.
- **Same policy, no exceptions.** Tags go through the same allow / drop /
  non-overridable-dangerous decision and the same hardened attribute policy as
  inline raw HTML — a block-level `<div onclick=… id=… srcdoc=…>` renders as a
  bare `<div>`.
- **Scope: CommonMark HTML block types 6 and 7** — a known block-level tag
  (`<details>`, `<div>`, `<table>`, `<section>`, …) or any other complete tag
  alone on its line. **Types 1–5 stay escaped/dropped**, as with the flag off:
  type 1 is the raw-text family (`<script>`, `<pre>`, `<style>`, `<textarea>`),
  where a browser reads everything after the opening tag as unparsed text — so a
  *speculative* close mid-stream is an mXSS vector — and types 2–5 (comments,
  processing instructions, CDATA, declarations) carry no renderable element at
  all. A block `<script>` is escaped in every configuration, including with
  `script` explicitly allowlisted and `unsafeHtml` also on.
- **Streaming: speculative closers.** While the block is still arriving, every
  still-open element gets a closer appended, so the HTML you have received *so
  far* is always a complete tree — `<div>\n<b>bol` renders as
  `<div><b>bol</b></div>`, and the closers simply stop being speculative when the
  author's own `</b></div>` lands (the emitted bytes don't change). A half-arrived
  tag (`<spa`, `<a href="htt`) renders as **nothing** until it completes, the same
  pending-invisible contract as a streaming markdown link's URL; if the stream
  ends on one, it settles as escaped text. Mis-nesting is repaired rather than
  propagated: `<b><i></b>` emits `<b><i></i></b>`, and a close tag matching
  nothing open is dropped. A type-6/7 block ends at a blank line even with tags
  open — the closers land there.
- **Markdown inside the HTML is not parsed** (the body is text + tags).
  Re-entering markdown inside a raw block is a later stage.

### Types

```ts
interface Block {
  id: number;
  kind: { type: "Paragraph" | "Heading" | "CodeBlock" | "List" | ...; data?: unknown };
  html: string;        // safe to inject via dangerouslySetInnerHTML
  open: boolean;       // still being built (last block in active tail)
  speculative: boolean; // closed by inference, may be revised
  start: number;
  end: number;
}

type BlockKindTag =
  | "Paragraph" | "Heading" | "CodeBlock" | "MathBlock" | "Mermaid" | "List"
  | "Blockquote" | "Alert" | "Table" | "Rule" | "Html" | "Component";

// Override map for <BrookMarkdown components={...} />. Block-kind keys are typed
// to BlockComponentProps; every other key is an ELEMENT override and receives
// that element's attributes + children — no `block`. (See "two prop contracts".)
type Components = {
  [K in BlockKindTag]?: React.ComponentType<BlockComponentProps> | string;
} & {
  [tag: string]: React.ComponentType<any> | string | undefined;
};

// Props a block-kind override receives (e.g. components.CodeBlock)
interface BlockComponentProps {
  block: Block;
  html: string;        // this block's rendered HTML (for `Component`: the INNER html)
  children?: unknown;  // React only: that inner content already parsed to a node tree
  open: boolean;
  speculative: boolean;
  text?: string;       // decoded source — CodeBlock / MathBlock
  language?: string;   // info string, first word — CodeBlock
  meta?: string;       // info string, the rest (`title="src/main.ts"`) — CodeBlock
  tag?: string;        // component-tag name — Component
  attrs?: Record<string, string>; // sanitized attrs, React name-form — Component
  // Typed structured data — present only with `blockData: true`:
  table?: TableData;          // { headers, rows, aligns }, cells { text, html }
  heading?: HeadingData;      // { level, text, id }
  code?: CodeBlockData;       // { lang, meta?, code }
  math?: MathBlockData;       // { latex }
  list?: ListData;            // { ordered, start?, items? }
  container?: ContainerData;  // { nested } — Blockquote / Alert
}
```

`htmlToReact(html, components)` and `parseTrustedHtml(html)` are also exported
for advanced use (e.g. rendering a single block's HTML to a React tree yourself).
Every type above also lives in the value-free `brookmd/types` entry — see [all
entry points](#all-entry-points).

### `highlight(code, lang)`

Optional. A tiny native-RegExp tokenizer that emits `<span class="t-…">` spans
(coloured by `brookmd/styles.css`, or by your own rules for those classes). The
language name is matched case-insensitively; an unknown language — or a block over
50 000 characters — falls through to plain escaped text.

```ts
import { highlight, supportedLangs } from "brookmd/highlight";
const html = highlight("const x = 1;", "ts");
supportedLangs(); // every info-string name currently registered
```

| Language | Info-string names |
|---|---|
| JavaScript / TypeScript | `js`, `javascript`, `jsx`, `ts`, `typescript`, `tsx` |
| Rust | `rust`, `rs` |
| Python | `python`, `py` |
| Go | `go` |
| Shell | `bash`, `sh`, `shell` |
| JSON / SQL | `json`, `sql` |
| HTML / XML / CSS | `html`, `xml`, `css` |
| *(since 0.30.0)* YAML, TOML, diff, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dockerfile | `yaml`, `yml`, `toml`, `diff`, `java`, `c`, `cpp`, `c++`, `cs`, `csharp`, `php`, `rb`, `ruby`, `swift`, `kt`, `kotlin`, `dockerfile` |

#### Adding a language — `registerLanguage` *(since 0.30.0)*

Register your own and it joins the **incremental streaming** highlighter — a
`components.CodeBlock` override would replace that machinery, this extends it:

```ts
import { registerLanguage } from "brookmd/highlight";

registerLanguage(["ini", "conf"], {
  // Tried in order at the cursor; every regex MUST be sticky (`/…/y`).
  pats: [
    ["com", /[#;][^\n]*/y],
    ["sel", /\[[^\]\n]*\]/y],
    ["attr", /[A-Za-z_][\w.-]*(?=\s*=)/y],
    ["str", /"(?:[^"\\]|\\.)*"/y],
    ["num", /-?\d+(?:\.\d+)?/y],
    ["pun", /[=,]/y],
    ["ws", /\s+/y],       // catch-all: unmatched characters emit as plain text
  ],
  kw: ["true", "false", "null"],
});
```

```ts
registerLanguage(names: string | string[], def: {
  pats: Array<[token: string, re: RegExp]>;
  kw?: Iterable<string>;
}): void
```

- **Token names** are the classes the theme already colours: `kw`, `str`, `rx`,
  `num`, `lt`, `com`, `fn`, `ty`, `mac`, `dec`, `attr`, `sel`, `tag`, `var`,
  `pun`, `txt`, plus `ws` (emitted verbatim, no span).
- **`ident` is the keyword hook.** A pattern classed `ident` (e.g.
  `["ident", /[A-Za-z_$][\w$]*/y]`) resolves per match: a name in `kw` becomes
  `kw`, a name followed by `(` becomes `fn`, a Capitalized name becomes `ty`, and
  anything else is emitted as plain text. `kw` on its own does nothing without an
  `ident` pattern.
- Registering an existing name **replaces** it, built-ins included. Names are
  lowercased; register at module scope, before the first fence renders.

### Streaming syntax highlighting

A code fence is highlighted **while it streams**, not only once it closes. On by
default; turn it off with `streamingHighlight={false}` (React) or
`{ streamingHighlight: false }` (the DOM mount options / Vue / Svelte / Solid),
which restores the plain-until-close behaviour.

It stays O(n) over the whole block rather than re-highlighting the fence on every
chunk. An open block keeps a **frozen prefix** — markup for everything behind a
checkpoint, which later bytes provably cannot rewrite — and re-tokenizes only the
**tail** after it, about one source line's worth per patch. When the fence closes,
the tokenizer resumes from that checkpoint instead of starting over, so a block
that streamed in highlights near-instantly.

Two things worth knowing:

- **The tail is speculative.** A prefix of source does not tokenize like the same
  prefix of a longer source: `const s = "hello` is a stray quote plus an
  identifier until its closing quote lands, and `123.456e` is `123` plus loose
  fragments until a digit arrives. So the last line's colours can shift as bytes
  come in. Nothing behind the checkpoint ever changes.
- **The settled markup is byte-identical** to `highlight(text, lang)` either way.
  Turning this on or off changes when colour appears, never what it is.

#### Where the colour front sits: `"wavefront"` (default) vs `"eager"`

`streamingHighlight` takes `boolean | "wavefront" | "eager"`; `true` means
`"wavefront"`.

|                 | frozen prefix | speculative tail                            |
| --------------- | ------------- | ------------------------------------------- |
| `"wavefront"`   | coloured      | plain text until its line completes          |
| `"eager"`       | coloured      | coloured, rebuilt every patch                |
| `false`         | plain         | plain (whole fence stays plain until close)  |

The default paints the tail as a **single text node** and updates its character
data per patch. Colour therefore follows a wavefront one checkpoint — in practice
one source line — behind the stream head, and at an LLM's token rate that is a
sub-second lag on one line.

That is a deliberate trade, and the tail is the right place to make it. The tail's
colours are *already* provisional by contract (see above): they may change on the
next byte, so they are the least trustworthy pixels on screen. What they cost is
not: highlighting them means building a span-dense subtree, throwing it away, and
building it again on every frame. Measured in a real browser on a streamed 32 KB
fence, that was **~758 ms** of extra work over the same fence with highlighting
off — and ~96% of it was style/layout/paint, not script. The final DOM is
identical either way (same 5,748 nodes); it was pure churn. Painting the tail as
text removes essentially all of it: element creations under the open `<code>` drop
from 7.5× the settled block's spans to 2.25× (i.e. the two unavoidable passes),
and trips through the HTML parser from ~1 per patch to ~0.13.

Pass `"eager"` to put the colour back on the tail per patch — worth it for short
fences, or when the fence is the whole point of the page and the cost is
acceptable. Nothing else changes: every mode streams the same TEXT at every patch
and settles to byte-identical markup.

Blocks past the highlighter's 50 000-character guard, unknown languages, and any
fence taken over by a `components.CodeBlock` / `pre` / `code` override are
unaffected — they behave exactly as before.

## Coverage

**CommonMark 0.31: 100% (652/652 spec examples), byte-exact** — every section,
including the hard ones (nested/loose lists, link reference definitions, link
precedence, lazy blockquote continuation). Plus GFM extensions, also **24/24
byte-exact**: tables, strikethrough, task lists, extended autolinks, GitHub
alerts (`> [!NOTE]` → styled callouts), footnotes (`[^1]` + `[^1]:`), and math
(`$…$`, `$$…$$`, `\(…\)`, `\[…\]`). Autolinks and alerts are on by default;
footnotes and math are opt-in per stream (see
[Per-stream config](#per-stream-config)).

*Byte-exact* means the full output string matches the reference renderer's
byte-for-byte — not a structurally normalized or whitespace-forgiving compare.
Both counts are the harnesses' **default** floors (`CMARK_MIN_EXACT=652`,
`GFM_MIN_EXACT=24`, pinned explicitly in the CI workflows), so a single byte of
regression fails the build even when the normalized tally stays green.

The only deviations from the reference output are deliberate brookmd choices,
folded by a documented `canonicalize` step applied to **both** sides before
comparison — the only transform on the byte-exact path, so it can erase our
intentional extras but never hide a structural divergence:

| Deliberate difference | Reference emits |
|---|---|
| `target="_blank" rel="noopener noreferrer nofollow"` on links (security-only) | no such attrs |
| `data-lang="…"` on code blocks (alongside `class="language-…"`) | `class` only |
| HTML5 void elements (`<br>`) | XHTML self-closing (`<br />`) |
| `style="text-align:…"` on table cells | GFM's deprecated `align="…"` |

See `crates/brookmd-core/tests/{cmark_spec,gfm_spec,footnotes,math}.rs` for the
runners, the `canonicalize` source, and the floors.

GitHub alerts render to GitHub-compatible markup
(`<div class="markdown-alert markdown-alert-note">…`), so existing markdown CSS
styles them, and they're overridable as a block kind via `components.Alert`.

## What it doesn't do

By design, not yet, or only partially:

- **Raw HTML in markdown** — escaped by default, not passed through. (Security
  default. The `unsafeHtml: true` config flag disables the escape but must never
  be enabled for untrusted input without a `sanitize` hook.)
- **Forward link references when streaming** — a `[ref]` used *before* its later
  `[ref]: url` definition can't resolve until the definition arrives; one-shot
  parsing handles it fully, streaming converges once the definition streams in.
- **Definition lists** — out of scope for v1.
- **KaTeX / Mermaid rendering** — brookmd emits KaTeX-ready math markup
  (`<span>`/`<div class="math …">` with `gfmMath` on) and a `Mermaid` slot, but
  stays zero-dep: bring your own KaTeX / mermaid pass (or a `components.MathBlock`
  / `components.Mermaid` override) for the actual SVG/MathML output. Both are
  ~20 lines — see the [KaTeX](#math-with-katex) and
  [Mermaid](#mermaid-diagrams) recipes.

## Performance

Every realistic streaming shape (long paragraph, fenced code block, GFM table,
blockquote/alert, flat list, math fence, reference-heavy document) parses in
**O(n) total work**, not O(n²) — at every chunk size from 16 bytes (char-by-char)
up. Each shape has an incremental cache that mirrors the structure of the block
so that an append only does work proportional to the *newly arrived* bytes, not
the growing tail. See [CHANGELOG.md](./CHANGELOG.md) for per-shape numbers and
the regression that prompted each cache; the canonical bench is
`crates/brookmd-core/examples/bench.rs` (`cargo run --release --example bench`).

Headline numbers are not durable across machines, but the curve is: chunk size
shouldn't change the order of magnitude for any shape. If you hit one that does,
file an issue with the input and chunking — that's the next bench scenario.

### Wire delta mode (automatic)

Parse work was already O(n), but until 0.23.0 the **bytes crossing the
worker→main-thread boundary** were not: every append re-emitted the open
block's full HTML, O(n²/chunk) total for one block that grows across many
chunks (a long streaming list, a big code fence). Since 0.23.0 the parser
emits **verified splices** instead — `{keep, append}` deltas against the
block's previous emit, established by byte comparison so reconstruction is
byte-exact by construction — and the client reassembles full blocks before
anything else sees them. Zero API change; `Block.html` is always complete.

Measured at a 200 KB document in 256-byte chunks, a streaming list's total
patch traffic drops from **119.6 MB to 0.78 MB (153× less, 2.8× faster
end-to-end)**; an unclosed code fence from **80.1 MB to 0.58 MB (137×, 4.9×
faster)**. Fast-committing prose is unchanged. Emitted bytes are now gated
linear in CI alongside the parse-work counters. Raw-boundary consumers (the
WASM `BrookParser`, native bindings, C ABI) keep byte-identical v1 wire by
default and can opt in with `setWireDelta(true)` — see
[`WIRE.md` §11](https://github.com/siinghd/brookmd/blob/main/crates/brookmd-core/WIRE.md).

## Instant thread reopen — persist and hydrate

Reopening a long thread normally means re-feeding its whole source through the
parser before the first paint: O(history) work between the click and the pixels,
which is exactly when a chat UI feels frozen.

It is also unnecessary. A committed block is emitted **once** and is **final**,
so the blocks a stream already produced are a complete description of the
document — there is nothing to re-derive. Capture them, store them, restore them:

```ts
// When the thread closes (or at any checkpoint):
await db.put(threadId, JSON.stringify(client.getPersistable()));

// When it reopens:
const client = new BrookClient();
client.hydrate(JSON.parse(await db.get(threadId))); // no worker, no WASM, no parse
// <BrookMarkdown client={client} /> paints the whole thread on the first frame.
```

Measured on a 1 MB / ~2250-block thread: **~5 ms to hydrate vs ~110 ms to
re-stream** it in 2 KB chunks (~51 ms even for a single-shot re-parse) — before
counting the worker spin-up and WASM init a re-stream also pays. Hydration is
O(blocks) of JSON handling; nothing parses.

Hydrated blocks are **ordinary committed blocks**: both renderers mount them
through the same path as live ones, so a reopened thread renders byte-identical
to the one the user closed.

### What to store, and when to throw it away

```ts
interface PersistableSnapshot {
  hydrateVersion: number; // envelope version; hydrate() refuses what it can't read
  blocks: Block[];        // exactly what getSnapshot() showed
  sourceLength: number;   // UTF-16 length of the markdown behind them
  sourceHash: string;     // fingerprint of that markdown — a staleness check
  done: boolean;          // had the stream been finalized?
}
```

Store it as JSON beside the thread. **Invalidate it when your source moves on**:
hydrate deliberately does *not* verify the blocks against the source, so a stale
snapshot would paint stale HTML. That is what `sourceHash` is for:

```ts
import { sourceFingerprint } from "brookmd";

if (snapshot.sourceHash === sourceFingerprint(mySource)) {
  client.hydrate(snapshot);                        // instant
} else {
  client.setContent(mySource, { done: true });     // the text changed — re-stream
}
```

Discard a snapshot whose `hydrateVersion` your build doesn't read, too. Either
way a failed hydrate is safe to fall back from: a malformed or unreadable
snapshot is rejected **whole**, with nothing written until every block has
validated.

> This envelope is a brookmd **package** format, *not* the parser wire contract
> ([`WIRE.md`](https://github.com/siinghd/brookmd/blob/main/crates/brookmd-core/WIRE.md)).
> The two are versioned independently.

### Resuming a thread that was still streaming

A `done: false` snapshot was captured mid-stream. Pass the original markdown as
`source` and the thread simply continues:

```ts
client.hydrate(snapshot, { source: markdownSoFar });
client.append(nextDelta); // or client.pipeFrom(await fetch("/api/chat"))
```

The parser's internal state cannot be serialized (it is an `Rc` graph, not
data), so continuing a document genuinely requires re-parsing what came before
it — but that cost moves **off the critical path**. On the first `append`
brookmd spins up the worker, re-feeds the source in the background, and keeps
the hydrated blocks on screen throughout: the reader scrolls and reads while the
parse catches up. New chunks need no buffering — they queue behind the re-feed
and land the moment it completes (they arrive at model token speed; the parser
catches up far faster). When the re-parse lands, unchanged blocks are adopted
**by reference and by id**, so nothing re-renders and nothing remounts at the
swap.

A `done: true` snapshot is terminal: it needs no `source`, no worker is ever
created for it, and `append()` throws — a finished thread cannot be extended
(`reset()` to start a new one). A `done: false` snapshot hydrated *without*
`source` is view-only: it paints, but appending throws, because a document
cannot be continued correctly without the text preceding it.

Nothing on the hydrate path touches a worker: `whenReady()` resolves immediately
and `client.ready` is `true`, so a readiness gate never sits over a thread that
is already on screen.

## Security

brookmd is XSS-safe by default — its HTML output is meant to be injected via
`innerHTML` without a downstream sanitizer:

- **Raw HTML is escaped** (the `unsafeHtml: true` config flag disables this;
  **never enable it for untrusted input without a `sanitize` hook**).
- **Dangerous URL schemes are neutralized** in `<a href>` and `<img src>` —
  `javascript:`, `vbscript:`, `data:text/html`, `data:text/javascript` (and
  `file:`, see below) become `#`. The check runs on the *decoded* URL and strips
  characters browsers ignore in the scheme, so obfuscations like
  `javascript&#58;…`, `javascript\:…`, `&#106;avascript:…`, and embedded
  tabs/newlines are caught, not just the literal form. (See
  `crates/brookmd-core/tests/security.rs`.)
- **The opt-in raw-HTML sanitizer removes DOM-hazard attributes.** Beyond `on*`,
  `style` and URL schemes, [Safe raw HTML](#safe-raw-html) drops `srcdoc`, `is`,
  `autofocus`, `contenteditable`, `id`/`name` (DOM clobbering), `slot`/`part`/
  `exportparts`, the `form*` family and `ping` from raw tags — a denylist by
  *policy*, not one that happens to be safe because some other tag is blocked.
  brookmd's own generated ids (footnote `fn-N`/`fnref-N`, heading slugs) are
  emitted by the renderer and never pass through the sanitizer, so they are
  unaffected. Component-tag props are exempt (see that section).
- **`htmlToReact` defends in depth**: it drops inline `on*` event-handler
  attributes and runs URL attributes through the same scheme filter. It's
  intended for brookmd's own (already-sanitized) HTML; if you hand it arbitrary
  third-party HTML, these guards are your only line of defense — prefer a
  dedicated HTML sanitizer for genuinely hostile input.

### Un-blocking a scheme — `allowSchemes`

`file:` is blocked by default. It can't execute script, but it has no legitimate
use in untrusted/LLM markdown, and in a **privileged** host — Electron, a browser
extension, a page on a `file://` origin — a live `file:` href is a
local-resource-disclosure / phishing vector. In an ordinary browser tab blocking
it costs nothing anyway: a page simply **refuses to navigate** to a `file:` URL,
so the href is inert there either way.

Some hosts genuinely need it. A coding-agent UI whose model links to local paths
wants the href present so it can **intercept the click** and open the file in an
editor or preview pane. `allowSchemes` is the opt-in for exactly that:

```ts
const client = new BrookClient({ config: { allowSchemes: ["file"] } });
```

- Takes **bare scheme names, no colon** (`["file"]`), matched
  case-insensitively.
- It **never restricts** anything — this is not a general allowlist. Schemes
  outside the built-in blocklist (`vscode:`, `ftp:`, `mailto:`, …) already render
  today and are unaffected by this setting.
- The **script-executing tier is non-overridable**: `javascript:`, `vbscript:`,
  `data:text/html`, `data:text/javascript`, and the scriptable `data:` media
  types (`data:image/svg`, `data:application/xhtml`, `data:text/xml`, …) stay
  blocked no matter what you list. Naming one is a silent no-op — the same rule
  as `htmlAllowlist`, where allowlisting `<script>` still cannot re-enable it.
- Applies uniformly to links, URI autolinks, images, and sanitized URL
  attributes.

Turning it on moves the risk to you: **intercept link clicks rather than letting
navigation happen**, and treat the path as untrusted input at the point you act
on it. In a privileged host, whether a model-authored `file:///…` is allowed to
reach a real file is the embedder's decision, not brookmd's.

### Intercepting link clicks — `onLinkClick`

*(since 0.30.0)* Model-authored links go wherever the model decided. If your
product wants an interstitial, an allowlist prompt, or in-app routing instead of
a bare new tab, take the click:

```tsx
<BrookMarkdown
  client={client}
  onLinkClick={(event, link) => {
    if (isInternal(link.href)) {
      event.preventDefault();                       // cancel the navigation
      router.push(new URL(link.href).pathname);     // route in-app instead
    } else if (!isTrusted(link.href)) {
      event.preventDefault();
      showInterstitial(link.href, link.text);
    }
  }}
/>
```

- **Delegated:** exactly one listener sits on the `.brook-md` root and resolves
  the anchor from the event target. No per-anchor prop, so links cost nothing
  extra and no block leaves its fast path.
- `link` is `{ href, text, element }` — `element` is the `<a>` itself.
- `event.preventDefault()` cancels navigation; do nothing and the default
  `target="_blank" rel="noopener noreferrer nofollow"` behaviour stands.
- A **streaming link with no URL yet** (`<a data-brook-pending>`, see [Streaming
  links](#streaming-links)) never fires it — there is no `href` to hand you.
- Hoist / memoize the handler, as with the other callbacks.
- Same hook on the DOM mount (`{ onLinkClick }`, with the native `MouseEvent`),
  forwarded by the Vue / Svelte / Solid bindings, and available as the
  `<brook-markdown>` element's `.onLinkClick` property.

This is also the piece that makes [`allowSchemes`](#un-blocking-a-scheme--allowschemes)
usable: a privileged host that un-blocks `file:` should intercept the click and
decide for itself, rather than letting navigation happen.

### Rendering untrusted / LLM HTML safely

If you enable `unsafeHtml` to render HTML from an untrusted source (e.g. an LLM
that returns raw HTML), **bring a real sanitizer** and pass it via
`<BrookMarkdown sanitize={…} />`. brookmd applies it to every block's HTML before
injection — **including the streaming (open) tail**, which the raw-`innerHTML`
fast path would otherwise expose. brookmd stays zero-dep; you choose the
sanitizer. The realistic pattern (matches the live demo):

```tsx
import DOMPurify from "dompurify";

// Hoist to module scope (or wrap in useCallback). A fresh arrow each render
// busts BrookMarkdown's per-block memo and re-runs every block through sanitize.
const sanitize = (html: string) => DOMPurify.sanitize(html);

// …then in your component:
<BrookMarkdown client={client} sanitize={sanitize} />
```

The built-in code/math renderers operate on already-escaped content and are not
run through `sanitize`, so syntax highlighting and math markup are preserved.
With no `sanitize` prop, rendering is byte-identical and zero-cost. For
genuinely hostile content where CSS-overlay/clickjacking matters, render inside
a sandboxed `<iframe>` instead — sanitization stops injection, not every
visual-overlay trick.

### Supply chain & security posture

brookmd ships **zero runtime dependencies** — `dependencies` and
`optionalDependencies` in `package.json` are both empty. The parsing core is Rust
compiled to WebAssembly, reproducibly buildable from `crates/brookmd-core/` via
`bun run build:wasm`. The package publishes **compiled, non-minified ESM**
(`dist/*.js` + `.d.ts`); it does not ship raw `.ts`/`.tsx` source.

**Frameworks are optional peers, by design.** `react`, `vue`, `svelte`, and
`solid-js` are declared as `peerDependencies` with
`peerDependenciesMeta.optional: true`. You install only the one you use — or none
(the `brookmd/dom` and `brookmd/element` entries need no framework at all). This
is the most important supply-chain property of the package: **a React-only
consumer never installs `vue` or `solid-js`, so those frameworks' transitive
internals never enter that consumer's lockfile.** `npm i brookmd` on its own pulls
in nothing else.

**Why a registry scan may flag `seroval` and `@vue/compiler-*`.** When a scanner
resolves *all* declared peers, it surfaces alerts on framework internals reachable
only through the optional peers — **none of which is brookmd code, and none of
which is installed unless you opt into that framework:**

- `seroval` (transitive of **solid-js**) — its `deserialize()` uses
  `(0, eval)(source)` and touches the network. This is Solid's SSR serialization
  layer; it is also the package some scanners label a "potential vulnerability".
- `@vue/compiler-core` (transitive of **vue**) — uses the `Function` constructor
  for template codegen.
- `@vue/compiler-sfc` (transitive of **vue**) — references `globalThis["fetch"]`.
- minified esm-bundler builds of those compilers read as "obfuscated code".

brookmd's own source contains **no `eval` and no `Function(...)` constructor**
(`grep -rnE '\beval\s*\(|\bnew Function\b|\bFunction\s*\(' packages/brookmd/src`
returns nothing). The
repository's [`socket.yml`](https://github.com/siinghd/brookmd/blob/main/socket.yml)
documents this and disables those upstream-framework alert types for brookmd's own
CI (which installs every framework as a devDependency for cross-framework tests).
If you prefer surgical handling, ignore the specific transitive packages instead
(e.g. `@SocketSecurity ignore seroval@<version>`).

**brookmd is browser-oriented (Web Worker + WASM).** The default path runs the
WASM parser inside a Web Worker — ideal for browsers and modern Node
(`worker_threads`), but **not** intended for non-browser or older environments
that lack Workers/WASM. If you need a worker-free, synchronous path (Node SSR /
React Server Components), use **`brookmd/server`** — it loads the same WASM
synchronously off disk and renders to a string without spawning a worker.

**First-party signals a scanner will (correctly) show.** These describe brookmd
itself and are kept *visible* rather than silenced:

- **Native code (`hasNativeCode`).** The first-party `dist/wasm/brook_md_core_bg.wasm`
  (~180 KB) is built from the Rust source in this repo and runs inside a sandboxed
  Web Worker (browser) or Node worker thread. It is reproducible from source, not a
  vendored third-party binary.
- **Network access (`networkAccess`).** Only `<brook-markdown src="URL">` (the URL
  *you* supply) and the wasm-bindgen glue loading the co-located `.wasm` via
  `fetch(new URL("…_bg.wasm", import.meta.url))` — which bundlers resolve to a
  local build artifact. No telemetry, no analytics, no first-party remote
  endpoints. In privileged contexts (browser extensions, Electron) treat the `src`
  value as any external URL and allowlist it in your CSP.
- **Filesystem access (`filesystemAccess`).** Node/SSR only: `brookmd/server` reads
  the package's own `.wasm` off disk (Node's `fetch` cannot load `file://` URLs).
  It reads only the package-internal asset, never a caller-supplied path.

The `socket.yml` at the repository root documents every signal with its
justification for Socket's GitHub app.

## Scaling

`BrookClient`s share a **worker pool** (`getDefaultPool()`), so concurrency
doesn't oversubscribe OS threads. Worker creation is lazy and load-aware:

- **1 stream → 1 worker**, and each new stream gets its own worker until the cap
  (`Math.min(navigator.hardwareConcurrency || 4, 8)`) — identical to the
  per-worker behavior for small stream counts.
- **Past the cap**, new streams attach to the least-loaded worker, which
  multiplexes them (a `BrookParser` per stream id). So **50 concurrent streams
  run on ≤8 workers (~6 each)**, not 50 threads.

`destroy()` frees a stream's parser and keeps the worker warm for its siblings;
the workers persist for the life of the page. Need isolation or manual teardown?
Construct your own `new BrookPool(factory, cap, { bootTimeoutMs })` and pass it as
an **option object** — `new BrookClient({ pool })` — or call `pool.disposeAll()`.
`bootTimeoutMs` (default 20 000) is how long a freshly spawned worker has to
report ready before it is failed; `0` disables the deadline.

`getDefaultPool()` is **browser-only** (it constructs `Worker`s) and is a
**per-page singleton** — don't rely on it in SSR/RSC. For isolation between
independent feature areas, give each its own `new BrookPool()`.

**Warm the pool to hide WASM init.** The one-time WASM load happens on the first
worker-bound op, which lands on the first-token critical path. Call
`getDefaultPool().warm()` on app load / route entry to start it early — the warm
worker is the one the first stream attaches to, so the init isn't wasted:

```ts
import { getDefaultPool } from "brookmd";
useEffect(() => { getDefaultPool().warm(); }, []); // (or your framework's mount hook)
```

### Long documents — `virtualize`

For very long documents (hundreds+ of blocks), pass `virtualize` to apply CSS
`content-visibility: auto` (+ a per-kind `contain-intrinsic-size`) to **closed**
blocks, so the browser skips style/layout/paint for off-screen content:

```tsx
<BrookMarkdown client={client} virtualize />
```

It's opt-in (off by default — short docs gain nothing) and never defers the
streaming tail (open/speculative blocks always render fully, so no flicker
where you're looking). It cuts **rendering cost, not DOM node count** — nodes
stay in the document (search, anchors, and a11y all keep working), they just
don't lay out while off-screen. Measured on a ~1800-block demo, an off-screen
**layout pass is ~7× cheaper** (≈1980ms → ≈284ms over 30 forced relayouts),
identical node count — i.e. whenever the browser would otherwise lay out
off-screen blocks (initial paint, resize, font load, scroll), that work is
skipped. No JS windowing, no scroll math, no dep — the browser does it natively.

Works best when `<BrookMarkdown>`'s parent uses normal block flow; a `flex`/`grid`
parent can interact with `contain-intrinsic-size` in surprising ways.

### Stick to bottom while streaming — `stickToBottom`

Pass `stickToBottom` and the view **follows the streaming tail, releasing when
the user scrolls up** (and re-locking when they scroll back near the bottom) —
the behavior every chat UI wants. It's **CSS-only** (CSS Scroll Snap, no JS, no
scroll listeners): brookmd emits a bottom snap target; you add one line to your
scroll container:

```tsx
<div className="chat-scroller">          {/* your existing scroll container */}
  <BrookMarkdown client={client} stickToBottom />
</div>
```
```css
.chat-scroller { overflow-y: auto; scroll-snap-type: y proximity; }
```

That's the whole feature. `proximity` (not `mandatory`) is what lets the user
scroll up freely. Note it **follows** the bottom — during very fast streaming
the lock can lag by a few px between snaps; it doesn't *hard-pin*. Re-snap on
content growth is solid in Chromium/Firefox; **Safari is weaker** at
re-snapping during streaming, so treat smooth following there as best-effort.

> **Metrics note:** because workers are shared, `getMetrics().wasmMemoryBytes`
> is the *shared* worker's heap — clients on the same worker report the same
> value. Aggregate with `Math.max`, not a sum.

<a id="onblockerror"></a>

### When a block fails to render — `onBlockError`

Every block renders inside its own error boundary. React's default response to
an uncaught render error is to unmount the **entire** tree, so before this a
single throwing `components` override blanked the whole document. Now the
failure costs that one block: the rest of the stream keeps rendering, and the
block is retried as soon as its HTML changes (so a streaming-tail failure heals
itself when the block settles).

```tsx
<BrookMarkdown
  client={client}
  components={components}
  onBlockError={(err, { blockId, kind, componentKeys, html }) => {
    reportToSentry(err, { blockId, kind, componentKeys, html });
  }}
/>
```

`componentKeys` is the override map's keys — the shortlist of suspects — and
`html` is the first 200 chars of the block that failed. Without the hook the same
detail goes to `console.error`. The overwhelmingly common cause is an override
reading `props.block.…` on the element path, where there is no `block`; see [the
two prop contracts](#custom-components--overrides).

## Architecture

```
┌── main thread ────────────────────────┐
│  BrookMarkdown — React, useSyncStore  │
│  BrookClient — message routing        │
└──┬──── postMessage(chunk) ────────────┘
   ▼
┌── Web Worker ─────────────────────────┐
│  worker.ts — coalesces chunks per    │
│              microtask, calls WASM   │
└──┬──── ffi ───────────────────────────┘
   ▼
┌── Rust → WASM (~170 KB after opt) ────┐
│  StreamParser:                        │
│    buffer: append-only                │
│    committed_offset                   │
│    [committed_blocks]                 │
│    [active_blocks]  (re-parsed tail)  │
│                                       │
│  scanner.rs → raw blocks              │
│  inline.rs  → emphasis stack + safe   │
│              link/code rendering      │
│  render.rs  → HTML with URL sanitize  │
└───────────────────────────────────────┘
```

Active tail re-parses on each chunk; committed blocks are frozen forever. Each block's ID is monotonic and is *preserved* across re-parses when its start offset and kind match a previously-seen active block — so React's keyed reconciliation reuses the DOM instead of remounting.

## License

MIT.


==============================================================================
# Source: skills/brookmd/SKILL.md
==============================================================================

---
name: brookmd
description: >-
  Render streaming markdown with brookmd — a Rust→WASM core in a Web Worker that
  incrementally parses an LLM token stream, speculatively closes mid-stream
  constructs, and keeps stable block identities so committed blocks never
  re-render. Use this skill when: installing or setting up brookmd
  (`npm i brookmd`); rendering streaming AI/LLM markdown in React, Vue, Svelte,
  Solid, a `<brook-markdown>` Web Component, or vanilla DOM; wiring a chat UI to
  the Vercel AI SDK, `useChat`, SSE deltas, or a growing string; SSR / Next.js
  App Router / Vite / RSC integration; overriding rendering with `components`,
  `decorators`, `blockData` toolbars, or component tags; math, KaTeX, or Mermaid;
  syntax highlighting, Shiki, or `registerLanguage`; security — `sanitize`,
  `unsafeHtml`, `htmlAllowlist`, `allowSchemes`, `urlTransform`, `onLinkClick`;
  styling, Tailwind, dark mode, or the streaming caret; performance —
  `virtualize`, `stickToBottom`, `hydrate`/`persist`, `warm()`, `getMetrics()`;
  or troubleshooting a blank `.brook-md`, a worker/WASM load failure, or blocks
  re-rendering on every patch.
---

# brookmd

Streaming markdown for the browser. One Rust core (CommonMark 0.31 + GFM,
byte-exact) compiled to WASM, run in a pooled Web Worker per stream, emitting
patches over a versioned JSON wire. Parsing is off the main thread and re-parses
only the active tail, so committed blocks never re-reconcile.

Zero runtime dependencies. `react` / `vue` / `svelte` / `solid-js` are optional
peers — you only need the one whose binding you import.

## Quick setup

```bash
npm i brookmd
```

```ts
import "brookmd/styles.css"; // optional theme; skip it to bring your own CSS
```

**Vite — one required line.** Pre-bundling hoists the wasm-bindgen glue into
`.vite/deps/`, which breaks the relative WASM lookup (404 / "magic word"):

```ts
// vite.config.ts
export default defineConfig({ optimizeDeps: { exclude: ["brookmd"] } });
```

**Next.js App Router** needs no `transpilePackages` and no loader config, but the
component must be `'use client'` (it uses hooks and spawns a Worker), and the
stream must be created in client code (a `Response`/`ReadableStream` is not
serializable across the RSC boundary).

## Basic usage

**From a stream** — the component owns the client, pipes the stream, supersedes
it if it changes, and cleans up on unmount:

```tsx
import { BrookMarkdown } from "brookmd/react";

// stream: AsyncIterable<string> | ReadableStream<Uint8Array> | Response
<BrookMarkdown stream={stream} />;
```

**From a growing string** — the shape most React chat UIs already have:

```tsx
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/react";

const client = useBrookMarkdownString(text, { streaming });
<BrookMarkdown client={client} />;
```

`setContent` diffing is done for you: a prefix-extension appends only the delta,
a divergence resets and reparses.

> **Pass `streaming: false` once the content is final.** Omitted or `true`
> leaves the stream OPEN, so the last block never commits — a finished code
> fence never highlights and never shows its Copy button. brookmd deliberately
> refuses to infer "done" from an absent flag: doing so would re-finalize on
> every token for callers who grow the string without it, an O(n²) reparse trap.

## Chat UI defaults

These four parser flags default **off** but are what a chat app almost always
wants, plus two client-side habits:

```tsx
const CONFIG: ParserConfig = {
  softBreaks: true, // a single \n becomes <br> — the chat convention models emit for
  dirAuto: true,    // per-block bidi, so an Arabic paragraph sits correctly beside an English one
  a11y: true,       // <label>-wrapped task checkboxes, scope="col" on table headers
  blockData: true,  // typed table/heading/code/math data → toolbars without an HTML re-parse
  gfmMath: true,    // $…$ / $$…$$ → KaTeX-ready markup (off by default so `$` in prose stays literal)
};

// 1. HOIST the components map (and decorators / urlTransform / sanitize) to module
//    scope. A fresh identity each render busts the per-block memo, so every
//    committed block re-renders on every patch.
const COMPONENTS: Components = { /* … */ };

// 2. Warm the pool on route entry so WASM init is off the first-token path.
useEffect(() => { getDefaultPool().warm(); }, []);
```

## Key `<BrookMarkdown>` props

| Prop | Type | Default | Meaning |
|---|---|---|---|
| `client` / `stream` | `BrookClient` / `AsyncIterable<string> \| ReadableStream<Uint8Array> \| Response` | — | Exactly one is required; `client` wins. |
| `streamConfig` | `ParserConfig` | — | Config for the internally created client (stream mode). |
| `components` | `Components` | — | Overrides. **Two prop contracts** — see below. |
| `sanitize` | `(html: string) => string` | — | Runs before every injection **including the open tail**. |
| `decorators` | `Decorator[]` | — | Inline TEXT-node matcher. Output is **trusted**. |
| `urlTransform` | `UrlTransform` | — | Rewrites `href`/`src`/`poster`; output is re-sanitized. |
| `onLinkClick` | `(event, { href, text, element }) => void` | — | *Since 0.30.0.* One delegated listener on the root; `preventDefault()` cancels. |
| `virtualize` | `boolean` | `false` | `content-visibility: auto` on **closed** blocks. |
| `stickToBottom` | `boolean` | `false` | Emits a snap sentinel; you add `scroll-snap-type: y proximity`. |
| `streamingHighlight` | `boolean \| "wavefront" \| "eager"` | `"wavefront"` | Highlight an open fence. |
| `className`, `id`, `role`, `aria-live`, `aria-atomic` | | — | Land on the `.brook-md` root. |
| `onBlockError` | `(error, info) => void` | — | Per-block error boundary hook. |
| `onStreamError` | `(err) => void` | — | Pipe errors; worker fatals carry `err.fatal`. |
| `onRenderMetrics` | `RenderMetricsHook` | — | Fires per ACTUAL block render. |
| `childMemo`, `deferTail` | `boolean` | `false` | Open-block child reuse / `useDeferredValue` routing. |

## `ParserConfig` — real defaults

| Field | Default | | Field | Default |
|---|---|---|---|---|
| `gfmAutolinks` | **`true`** | | `unsafeHtml` | `false` |
| `gfmAlerts` | **`true`** | | `componentTags` | off |
| `gfmTagfilter` | `false` | | `inlineComponentTags` | off |
| `gfmFootnotes` | `false` | | `htmlAllowlist` | unset = off |
| `gfmMath` | `false` | | `dropHtmlTags` | unset = off |
| `dirAuto` | `false` | | `blockHtml` | `false` |
| `lenientLists` | `false` | | `allowSchemes` | `[]` |
| `softBreaks` | `false` | | `blockData` | `false` |
| `a11y` | `false` | | `retainCommittedHtml` | `false` (worker path) |

Config is applied once when the stream's parser is created and is **immutable**
for that stream's lifetime — `reset()` keeps it; use a new client for different
flags. `streamingHighlight` is a *renderer* option, not part of `ParserConfig`.

## Framework bindings

```tsx
import { BrookMarkdown } from "brookmd/react";     // <BrookMarkdown stream={s} />
```
```ts
import { mountBrookMarkdown } from "brookmd/dom";  // mountBrookMarkdown(client, el, opts)
import { defineBrookMarkdown } from "brookmd/element"; // <brook-markdown src="…" gfm-math>
import { BrookMarkdown } from "brookmd/vue";       // <BrookMarkdown :client="client" />
import { brookMarkdown } from "brookmd/svelte";    // <div use:brookMarkdown={{ client }} />
import { BrookMarkdown } from "brookmd/solid";     // <BrookMarkdown client={client} />
import { renderToString } from "brookmd/server";   // sync, worker-free, React-free
import { BrookMarkdownStatic } from "brookmd/server/react"; // hookless, RSC-safe
```

On React Native use the **`brookmd-react-native`** package instead — the same
Rust core over JSI, no Web Worker.

## Common gotchas

1. **`components` has two prop contracts.** A capitalized block-kind key gets
   `BlockComponentProps` (with `block`); a lowercase tag key gets the element's
   attributes and `children` only — **no `block` prop**. A name reachable from
   both must guard: `block ? … : …`. Reading `props.block` unconditionally
   yields `can't access property "kind", block is undefined`.
2. **Inline object identity is the #1 perf footgun.** Hoist `components`,
   `decorators`, `urlTransform`, `sanitize`, `onBlockError` — a fresh identity
   re-renders every committed block on every patch. (`onLinkClick` is exempt: it
   is delegated to the root.)
3. **There is no `done()`** — it is `finalize()`. And `beginResume` is private.
4. **The root class is `brook-md`** (hyphenated); `className` is appended to it.
5. **`stickToBottom` is CSS-only** — you must add `scroll-snap-type: y proximity`
   to your scroll container.
6. **Blank `.brook-md` with no console output** = the worker never booted (often
   a stale hashed URL after a deploy). Watch `client.failed` / `onError`;
   `recovery` (default true) heals the first death invisibly, the second is fatal.
7. **Uncoloured code** = `brookmd/styles.css` was not imported.
8. **KaTeX/Mermaid must skip open blocks** (`.brook-open` / `.brook-streaming`,
   or `props.open`) — a half-typed formula or diagram throws on every patch.
9. **Vite needs `optimizeDeps.exclude`**; nothing else does.
10. **Next.js** — `'use client'`, and build the stream client-side.
11. **`getDefaultPool()` is browser-only** and a per-page singleton; don't rely
    on it in SSR/RSC.
12. **Don't SSR `BrookMarkdownStatic` and hydrate with `BrookMarkdown`** — use
    the same component on both sides.

## References

- [references/api.md](references/api.md) — subpath export map, every
  `<BrookMarkdown>` prop, `BrookClient` methods and options, full `ParserConfig`,
  the `components` two-contract rules, `BlockComponentProps` and the per-kind
  `blockData` shapes, the server API.
- [references/frameworks.md](references/frameworks.md) — React (incl.
  `useBrookStream`), Vue, Svelte, Solid, the Web Component's attributes and
  properties, vanilla `mountBrookMarkdown` + `MountHandle`, `brookmd/server`,
  Next.js, Vite, webpack/Rollup/Parcel, plain ESM, React Native, CSP.
- [references/styling.md](references/styling.md) — `styles.css`, the `--brook-*`
  variables, dark mode, the `brook-block` / `brook-open` / `brook-speculative` /
  `brook-streaming` class contract, the opt-in caret, code-block chrome, Tailwind
  (and why `prose` users should skip the theme import).
- [references/security.md](references/security.md) — the URL policy and
  never-allowed schemes, `allowSchemes`, raw-HTML tiers, the `sanitize` hook,
  trusted surfaces, `onLinkClick` interstitials.
- [references/recipes.md](references/recipes.md) — Vercel AI SDK `useChat`,
  KaTeX, Mermaid, Shiki, `registerLanguage`, a CSV table toolbar off `blockData`,
  interactive checkboxes, lazy images, accessible chat, persist/hydrate,
  `getMetrics()`.
- [references/troubleshooting.md](references/troubleshooting.md) — symptom →
  cause → fix for every failure above.
- [assets/examples/](assets/examples/tsconfig.json) — `basic-stream.tsx`,
  `ai-sdk-chat.tsx`, `full-featured.tsx`, `vanilla-dom.ts`, `web-component.html`,
  `server-render.ts`, `nextjs-app-router.tsx`. All typechecked.


==============================================================================
# Source: skills/brookmd/references/api.md
==============================================================================

# brookmd — API reference

Everything here is verified against the package source. Entries labelled
**since 0.30.0** are new in that release.

---

## 1. Subpath exports

`brookmd` ships compiled ESM (`dist/*.js` + `.d.ts`) plus the WASM binary. There
is no default export; import from the narrowest subpath you need.

| Subpath | Exports | SSR-safe? |
|---|---|---|
| `brookmd` | `BrookClient`, `BrookPool`, `getDefaultPool`, `sourceFingerprint`, `BrookMarkdown`, `useBrookStream`, `useBrookMarkdownString`, `highlight`, `registerLanguage`, `supportedLangs`, `htmlToReact`, `parseTrustedHtml`, `safeUrl`, `wrapLink` + all public types | yes |
| `brookmd/client` | `BrookClient`, `BrookPool`, `getDefaultPool`, `sourceFingerprint`, `applyPatch`, `emptyBlockStore`; types `BlockStore`, `OutlineEntry`, `PersistableSnapshot` | yes — the constructor never touches `Worker` |
| `brookmd/react` | `BrookMarkdown`, `useBrookStream`, `useBrookMarkdownString`, `blockKindProps`, `blocksEqual`; type `BlockErrorInfo` | yes |
| `brookmd/server` | `isBrookReady`, `initBrookSync`, `initBrook`, `parseToBlocks`, `renderToString` | server-only by design; **React-free** |
| `brookmd/server/react` | `BrookMarkdownStatic` (hookless, RSC-safe) | server / RSC |
| `brookmd/dom` | `mountBrookMarkdown`, `tailOpenBlockId`; types `MountHandle`, `MountOptions`, `DomComponents`, `DomBlockComponent` | import-safe; `mountBrookMarkdown` **throws** without `document` |
| `brookmd/element` | `defineBrookMarkdown`, `parseTriBool`; type `LinkClickHandler` | import-safe; `defineBrookMarkdown` is a no-op without `customElements` |
| `brookmd/vue` | `useBrookMarkdown`, `useTailBlockId`, `BrookMarkdown`, `useBrookMarkdownString` | yes |
| `brookmd/svelte` | `brookMarkdown`, `tailBlockId`, `brookMarkdownString` | yes |
| `brookmd/solid` | `BrookMarkdown`, `mountSolid`, `setupTailBlockId`, `createTailBlockId`, `setupBrookMarkdownString`, `createBrookMarkdownString` | yes |
| `brookmd/highlight` | `highlight`, `supportedLangs`, `escapeHtml`, `stepHighlight`, `registerLanguage` (**since 0.30.0**) | yes (pure strings) |
| `brookmd/html-to-react` | `htmlToReact`, `parseTrustedHtml`, `wrapLink`, `safeUrl`, `decodeEntities` | yes |
| `brookmd/block-props` | `blockProps`, `extractLang`, `htmlAttrs` | yes |
| `brookmd/worker-core` | `WorkerCore`; types `ParserLike`, `WorkerCoreDeps` | yes |
| `brookmd/types` | every public type (`RenderMetrics`, `RenderMetricsHook`, `ListItemData`, `WireHtmlDelta`, `WireActiveBlock`, …) | type-only |
| `brookmd/styles.css` | the optional default theme | n/a |

`react`, `vue`, `svelte` and `solid-js` are **optional** peer dependencies. The
bare `brookmd` entry re-exports the React surface, so it pulls `react` — import
from `brookmd/client` for a framework-free core.

---

## 2. `<BrookMarkdown>` (React) — props

`BrookMarkdownProps` is not exported as a type; use the prop names directly.
Exactly one of `client` or `stream` is required (`client` wins); passing neither
throws.

| Prop | Type | Default | Meaning |
|---|---|---|---|
| `client` | `BrookClient` | — | Caller-owned client. The component never destroys it. |
| `stream` | `AsyncIterable<string> \| ReadableStream<Uint8Array> \| Response` | — | One-line mode: the component owns an internal client via `useBrookStream`. |
| `streamConfig` | `ParserConfig` | — | Config for the internally created client (stream mode only). |
| `onStreamError` | `(err: Error) => void` | — | Pipe/source errors, and worker fatals carrying `err.fatal`. |
| `components` | `Components` | — | Override map. See §5 — it has **two prop contracts**. |
| `virtualize` | `boolean` | `false` | `content-visibility: auto` wrapper on **closed** blocks only. |
| `stickToBottom` | `boolean` | `false` | Emits `<div class="brook-bottom-anchor" style="scroll-snap-align:end">`; you add `scroll-snap-type: y proximity` to the scroller. |
| `sanitize` | `(html: string) => string` | — | Runs before every `innerHTML` injection **including the open tail**. Built-in code/math/mermaid renderers bypass it. |
| `decorators` | `Decorator[]` | — | Post-parse inline TEXT-node matcher. **Output is trusted / unsanitized.** |
| `urlTransform` | `UrlTransform` | — | Rewrites `href`/`src`/`poster`; output is re-sanitized. |
| `onLinkClick` | `(event: React.MouseEvent<HTMLElement>, link: LinkClickInfo) => void` | — | **Since 0.30.0.** One delegated listener on the `.brook-md` root. `event.preventDefault()` cancels navigation. Streaming links with no href yet (`<a data-brook-pending>`) never fire it. |
| `childMemo` | `boolean` | `false` | Reuse unchanged top-level children of an OPEN block (only on the `components`/`sanitize` walk path). |
| `streamingHighlight` | `boolean \| "wavefront" \| "eager"` | `true` ⇒ `"wavefront"` | Highlight an open fence. `"eager"` recolours the tail per patch; `false` = plain until close. |
| `deferTail` | `boolean` | `false` | Routes the block list through `useDeferredValue`; adds `brook-deferred` to the root while deferring. |
| `className` | `string` | — | Appended to the root class, which is always `brook-md`. |
| `id`, `role` | `string` | — | Set on the root. |
| `aria-live` | `"off" \| "polite" \| "assertive"` | off | Live region. |
| `aria-atomic` | `boolean` | off | Pair with `aria-live`. |
| `onRenderMetrics` | `RenderMetricsHook` | — | Fires per ACTUAL block render; also advances `client.getMetrics().renderCount`. |
| `onBlockError` | `(error, info: BlockErrorInfo) => void` | — | Per-block error boundary. `BlockErrorInfo = { blockId, kind, componentKeys, html }`. |

`LinkClickInfo = { href: string; text: string; element: HTMLAnchorElement }`.

`onLinkClick` is delegated, so — unlike `components` / `decorators` /
`urlTransform` / `sanitize` — a fresh closure each render re-renders **no**
blocks. Every other non-primitive prop must be hoisted or memoized.

### Hooks

```ts
useBrookStream(stream, options?): BrookClient
// options: { config?: ParserConfig; onError?: (err: Error & { fatal?: boolean }) => void }
```
Owns a client (`coalesce: true`), reattaches on mount, destroys on unmount,
aborts + `reset()`s when the stream identity changes.

```ts
useBrookMarkdownString(content, options?): BrookClient
// options: { config?: ParserConfig; streaming?: boolean; onError?: ... }
```
Drives `client.setContent(content, { done: streaming === false })`. A
prefix-extension appends only the delta; a divergence resets and reparses.

**Pass `streaming: false` once the content is final.** Omitted or `true` leaves
the stream OPEN, so the last block never commits — a finished fence never
highlights and never shows its Copy button. brookmd deliberately refuses to
infer "done" from an absent flag: that would re-finalize on every token for
callers who grow the string without it, which is an O(n²) reparse trap.

---

## 3. `BrookClient`

```ts
new BrookClient(options?)
```

| Option | Default | Meaning |
|---|---|---|
| `pool` | `getDefaultPool()` | Worker pool. Pass your own `BrookPool` for a custom worker factory. |
| `config` | — | `ParserConfig`, applied once when the stream's parser is created and **immutable** for that stream (a `reset()` keeps it). |
| `onError` | — | `(err: { message: string; fatal?: boolean }) => void`. |
| `onBlock` | — | `(block: Block) => void`, once per commit. |
| `coalesce` | `false` | rAF-batch store notifications. The finalize patch always flushes synchronously. |
| `recovery` | `true` | One transparent re-feed after a fatal worker death, so the view never blanks. |

**Methods.** `append(chunk)`, `finalize()` (there is **no `done()`**),
`pipeFrom(src, { signal })` (an abort skips finalize), `setContent(content, { done })`,
`reset()`, `destroy()`, `reattach()` (StrictMode), `subscribe(fn) => unsub`,
`getSnapshot(): Block[]`, `whenReady(): Promise<void>`,
`getPersistable(source?): PersistableSnapshot`, `hydrate(snapshot, { source }?)`,
`outline(): OutlineEntry[]`, `toPlaintext(): string`, `getMetrics()`.

`subscribe` and `getSnapshot` are arrow properties — safe to pass unbound to
`useSyncExternalStore`.

**Getters.** `ready: boolean`, `failed: Error | null`.

`getMetrics()` returns `{ bytes, patches, meanParseMicros, totalParseMs,
throughputKBs, committedBlocks, activeBlocks, lastPatchAgoMs, retainedBytes,
wasmMemoryBytes, renderCount, rebuildCount }`.

**Persistence.** `getPersistable()` captures `{ hydrateVersion, blocks,
sourceLength, sourceHash, done }`; `hydrate()` restores it into an untouched
client with no worker, no WASM and no parse. Validate
`snap.sourceHash === sourceFingerprint(mySource)` before hydrating. A `done: true`
snapshot is terminal (appending throws); a `done: false` one needs `{ source }`
to resume.

**Pool.** `new BrookPool(factory, cap, { bootTimeoutMs = 20000, setTimeout, clearTimeout })`
with `acquire`/`release`/`reattach`/`send`/`whenWorkerReady`/`warm`/`disposeAll`
and getters `workerCount` / `handlerCount`. The default pool's cap is
`min(navigator.hardwareConcurrency || 4, 8)`. `getDefaultPool()` is browser-only
and a per-page singleton — don't rely on it in SSR/RSC.

---

## 4. `ParserConfig`

Per-stream, applied once, immutable for that stream's lifetime. Use a new client
for different flags.

| Field | Type | Default | What it does |
|---|---|---|---|
| `gfmAutolinks` | `boolean` | **`true`** | Bare `www.` / `http(s)://` / `ftp://` / email autolinks. |
| `gfmAlerts` | `boolean` | **`true`** | `> [!NOTE]` → callouts. |
| `gfmTagfilter` | `boolean` | `false` | With `unsafeHtml` on, escapes the nine GFM-disallowed tags. |
| `gfmFootnotes` | `boolean` | `false` | `[^1]` + `[^1]:` → a footnote section. |
| `gfmMath` | `boolean` | `false` | `$…$` / `\(…\)` inline and `$$…$$` / `\[…\]` display → KaTeX-ready `.math` markup. |
| `dirAuto` | `boolean` | `false` | `dir="auto"` on block-level text elements (per-block bidi). |
| `lenientLists` | `boolean` | `false` | A marker followed by ≥6 columns of SPACE padding yields item text instead of indented code. |
| `softBreaks` | `boolean` | `false` | A bare `\n` inside inline content renders as `<br>`. |
| `a11y` | `boolean` | `false` | `<label>`-wrapped task checkboxes, `scope="col"` on `<th>`. |
| `unsafeHtml` | `boolean` | `false` | Pass raw HTML through unescaped. **Never for untrusted input.** |
| `componentTags` | `string[]` | off | Allowlist of BLOCK component tags; inner content parsed as markdown, attributes sanitized. Case-sensitive. |
| `inlineComponentTags` | `string[]` | off | Same, for INLINE positions (chips, citations, mentions). |
| `htmlAllowlist` | `string[]` | unset = off | Engages the safe raw-HTML sanitizer even when `[]` (= allow all but a dangerous set). A non-empty array renders only those tags. |
| `dropHtmlTags` | `string[]` | unset = off | Tags removed entirely (inner text stays). Also engages the sanitizer. |
| `blockHtml` | `boolean` | `false` | Extends the sanitizer to CommonMark HTML block types 6–7. Needs `htmlAllowlist`/`dropHtmlTags` to do anything. |
| `allowSchemes` | `string[]` | `[]` | Un-blocklist for overridable-blocked schemes (currently only `file`). Bare names, no colon. |
| `blockData` | `boolean` | `false` | Populate `block.kind.data` with typed table/heading/code/math/list/container data. |
| `retainCommittedHtml` | `boolean` | `false` on the worker path | Keep every committed block's HTML inside the parser. The server renderers pin it on. |

`streamingHighlight` is a **renderer** option (React prop / `MountOptions`), not
part of `ParserConfig`.

---

## 5. `components` — the two prop contracts

The same map is read by two dispatchers, and they pass different props.

**Block contract.** A capitalized block-kind key (`BlockKindTag`:
`Paragraph`, `Heading`, `CodeBlock`, `MathBlock`, `Mermaid`, `List`,
`Blockquote`, `Alert`, `Table`, `Rule`, `Html`, `Component`) — or a
`componentTags` tag matched at block level — receives `BlockComponentProps`.

**Tag contract.** The SAME key is also matched by ELEMENT NAME while converting
a block's HTML to React — that is how `a` / `code` / `table` / `img` overrides
work, and how an `inlineComponentTags` chip, or a component tag nested in a list
item or blockquote, renders. That call passes the element's attributes and
`children` only: **there is no `block` prop.**

So a component registered for a name that can appear in both positions must not
assume `block` exists:

```tsx
const Thinking = ({ block, children }: any) =>
  block ? <Panel data={block.kind.data}>{children}</Panel> : <span>{children}</span>;
```

Block-kind keys are typed to `BlockComponentProps` in the `Components` mapped
type, so the mismatch is a compile error rather than a runtime `undefined` deref.
brookmd also refuses to dispatch a raw element whose name collides with a
block-kind key, and wraps every block in an error boundary so a throwing
override costs one block instead of the document.

Dispatch order for a `Component` block: `components[tag]` → `components.Component`
→ `components[kind]`. The built-in `CodeBlock` / `MathBlock` / `Mermaid`
renderers are bypassed by `components.CodeBlock`, `components.pre`, or
`components.code`.

On the React path `attrs` are renamed `class` → `className` and `for` →
`htmlFor`, so `{...attrs}` spreads cleanly. The DOM path keeps the literal HTML
names.

The DOM renderer (`brookmd/dom`, and therefore `<brook-markdown>`) has only the
BLOCK contract: `DomComponents = Record<string, (props: BlockComponentProps) => HTMLElement | string>`.
Tag-level overrides are React-only.

### `BlockComponentProps`

| Prop | Type | When |
|---|---|---|
| `block` | `Block` | always (block contract) |
| `html` | `string` | always — for a `Component` block this is the INNER rendered HTML |
| `children` | `unknown` | React only, when a `components` map is supplied; cast to `ReactNode` |
| `open` | `boolean` | always — true while the block is still streaming |
| `speculative` | `boolean` | always — closed speculatively, may yet be revised |
| `text` | `string?` | decoded source for `CodeBlock` / `MathBlock` (populated even with `blockData` off) |
| `language` | `string?` | info-string language for `CodeBlock` (always on) |
| `meta` | `string?` | everything after the language word, trimmed (always on); appears only once it can no longer change |
| `tag` | `string?` | component tag name for `Component` blocks |
| `attrs` | `Record<string, string>?` | sanitized attributes for `Component` blocks |
| `table` | `TableData?` | `Table` + `blockData` |
| `heading` | `HeadingData?` | `Heading` + `blockData` |
| `code` | `CodeBlockData?` | `CodeBlock` + `blockData` |
| `math` | `MathBlockData?` | `MathBlock` + `blockData` |
| `list` | `ListData?` | `List` + `blockData` |
| `container` | `ContainerData?` | `Blockquote` / `Alert` + `blockData` |

`Block = { id: number; kind: BlockKind; start: number; end: number; html: string; open: boolean; speculative: boolean }`
and `BlockKind = { type: BlockKindTag; data?: unknown }`. `start`/`end` are
offsets into the source.

### `blockData` shapes

| Kind | `kind.data` with `blockData: true` | with it off |
|---|---|---|
| `Table` | `{ headers: TableCell[]; rows: TableCell[][]; aligns: Align[] }`, cell = `{ text, html }` | `undefined` |
| `Heading` | `{ level, text, id }` | a bare `number` (the level) — it is a union, guard before reading |
| `CodeBlock` | `{ lang, meta?, code }` — `code` is the decoded source | `{ lang }` (+ `meta`) |
| `MathBlock` | `{ latex }` — decoded LaTeX | no data |
| `List` | `{ ordered, start?, items?: ListItemData[] }`; `ListItemData = { html, start? }` where `start` is the document-absolute marker offset, absent for nested items | `{ ordered }` |
| `Blockquote` / `Alert` | `{ nested: NestedBlock[] }` (Alert also carries `{ kind }`) | Blockquote none; Alert `{ kind }` |

`Align = "left" | "center" | "right" | null`.

`props.list` is set only when `typeof data.start === "number"`; `props.heading`
only when the data is an object. `blockData` also enables keyed streaming fast
paths for open `Table` / `List` / `Blockquote`-`Alert` blocks, so a growing
container re-renders only its open last inner block.

---

## 6. Other types

```ts
interface Decorator {
  match: RegExp | string;                                  // tested per inline TEXT node
  replace: (matchText: string, groups: string[]) => BrookNode; // PURE
  skipInside?: string[];                                   // default ['a','code','pre','kbd']
}

type UrlTransform = (url: string, ctx: { tag: string; attr: "href" | "src" | "poster" }) => string;

interface OutlineEntry { level: number; text: string; id: number }
```

`decorators` run post-parse on real inline TEXT nodes only, once per committed
block — they never see URLs, code or markup, and a value split by inline markup
(`$2.<em>5</em>B`) is two text nodes and won't match across them.

---

## 7. Server API

```ts
import { initBrook, initBrookSync, isBrookReady, parseToBlocks, renderToString } from "brookmd/server";
import { BrookMarkdownStatic } from "brookmd/server/react";
```

- `initBrook(opts?)` — async, idempotent. Node reads the co-located `.wasm` off
  disk; the web path fetches the bundler-resolved asset. `initBrook({ wasm })`
  supplies bytes yourself. A failed init is not cached, so it can be retried.
- `initBrookSync(bytes)` — for edge runtimes with no filesystem.
- `renderToString(md, { config })` — synchronous HTML string, zero React.
- `parseToBlocks(md, { config })` — the block array.
- `<BrookMarkdownStatic content config components className id role aria-live aria-atomic />`
  — hookless, RSC-safe, **render-once**. No error boundary, no Mermaid, no
  client-side highlighting. Do not SSR `BrookMarkdownStatic` and hydrate with
  `BrookMarkdown`: use the same component on both sides.

**Document assembly rule.** A `Block.html` never ends with a newline. Insert a
`\n` before a block only when the output does not already end with one, and end
the document with a single `\n`. An unconditional `"\n".join(...)` doubles the
newline a raw HTML block serializes for itself.

See [../assets/examples/server-render.ts](../assets/examples/server-render.ts).


==============================================================================
# Source: skills/brookmd/references/frameworks.md
==============================================================================

# brookmd — framework bindings & bundler setup

One Rust→WASM core, one framework-neutral DOM renderer, thin bindings on top.
Entries labelled **since 0.30.0** are new in that release.

---

## React — `brookmd/react`

```tsx
import { BrookMarkdown } from "brookmd/react";

<BrookMarkdown stream={stream} />;              // component owns the client
```

```tsx
import { BrookMarkdown, useBrookStream } from "brookmd/react";

const client = useBrookStream(stream);          // returns the owned client
<BrookMarkdown client={client} />;              // read outline()/getMetrics() off it
```

```tsx
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/react";

// Already holding a growing string? setContent-diffing is done for you.
const client = useBrookMarkdownString(text, { streaming });
<BrookMarkdown client={client} />;
```

`useBrookStream(stream, { config, onError })` owns a client with
`coalesce: true`, `reattach()`es on mount, `destroy()`s on unmount, and aborts +
`reset()`s when the stream identity changes. A single-use stream (a `Response`,
a `ReadableStream`, an async generator) can only be consumed once, so React
**StrictMode**'s dev-only double mount may truncate it in development;
production mounts once and is unaffected.

`useBrookMarkdownString(content, { config, streaming, onError })` drives
`client.setContent(content, { done: streaming === false })`.

Full prop list: [api.md](api.md#2-brookmarkdown-react--props).
Examples: [basic-stream.tsx](../assets/examples/basic-stream.tsx),
[full-featured.tsx](../assets/examples/full-featured.tsx).

---

## Vanilla DOM — `brookmd/dom`

```ts
import { BrookClient } from "brookmd/client";
import { mountBrookMarkdown } from "brookmd/dom";

const client = new BrookClient();
const handle = mountBrookMarkdown(client, container, options);
// handle: { destroy(), refresh(), openBlockId(): number | null }
```

`mountBrookMarkdown` **throws** if `document` is undefined — import it anywhere,
call it only in the browser. The mount never destroys the client: you own the
worker/stream lifecycle.

`MountOptions`:

| Option | Default | Notes |
|---|---|---|
| `components` | — | `DomComponents` — block-kind / component-tag keys only, values `(props) => HTMLElement \| string`. **No lowercase tag-level overrides** (React-only). |
| `sanitize` | — | Applied to every generic block's HTML, including the open tail. |
| `virtualize` | `false` | `content-visibility: auto` on closed blocks. |
| `stickToBottom` | `false` | Emits the snap sentinel; you add `scroll-snap-type`. |
| `highlightCode` | `true` | Suppressed when `components.CodeBlock` is supplied. |
| `streamingHighlight` | `"wavefront"` | `true` \| `"wavefront"` \| `"eager"` \| `false`. |
| `batch` | `true` | One DOM write per `requestAnimationFrame`. |
| `morphOpenBlocks` | `false` | Morph a growing generic block's subtree in place, so only changed parts repaint and focus/selection in the tail survives. |
| `decorators`, `urlTransform` | — | Parity with the React props. |
| `onLinkClick` | — | **Since 0.30.0.** `(event: MouseEvent, link: LinkClickInfo) => void`. One listener on the root, removed by `handle.destroy()`. |
| `className`, `id`, `role`, `ariaLive`, `ariaAtomic` | — | Set on the root. |
| `onRenderMetrics` | — | Per-block render probe. |

Also exported: `tailOpenBlockId(snapshot): number | null`.

Example: [vanilla-dom.ts](../assets/examples/vanilla-dom.ts).

---

## Web Component `<brook-markdown>` — `brookmd/element`

```ts
import { defineBrookMarkdown } from "brookmd/element";
defineBrookMarkdown(); // or defineBrookMarkdown("my-markdown")
```

Idempotent, and a no-op where `customElements` is undefined (so it is
SSR-import-safe). It renders in **light DOM**, so your markdown CSS reaches the
content.

**Content priority:** `src` (fetch + stream) > `markdown` attribute > text
content. The `markdown` attribute is one-shot — it re-parses the whole document
on change, so never point it at a per-token-growing string.

**Config attributes are tri-state:** absent = library default; `""` / `"true"` /
`"1"` = true; `"false"` / `"0"` = false. Tri-state is the only way to turn OFF a
default-on flag.

| Attribute group | Attributes |
|---|---|
| Content | `markdown`, `src` |
| Lists | `component-tags`, `allow-schemes` |
| Parser flags | `gfm-autolinks`, `gfm-alerts`, `gfm-tagfilter`, `gfm-footnotes`, `gfm-math`, `dir-auto`, `lenient-lists`, `soft-breaks`, `a11y`, `unsafe-html`, `block-html`, `retain-committed-html` |
| Renderer flags (**since 0.30.0**) | `stick-to-bottom`, `virtualize` |

There is no attribute for `inline-component-tags`, `html-allowlist`,
`drop-html-tags` or `block-data`; drive those with a caller-owned client.

**Properties** (objects and functions cannot be attributes): `client`,
`components`, `sanitize`, `onLinkClick` (**since 0.30.0**).
**Methods:** `append(chunk)`, `finalize()`, `reset()`, `getClient()`.

A self-owned element (`src` / `markdown` / inline text / `append()`) destroys its
client on disconnect; a caller-supplied `client` is left alone.

Angular consumes the same element — add `CUSTOM_ELEMENTS_SCHEMA` and call
`defineBrookMarkdown()` once at bootstrap.

Example: [web-component.html](../assets/examples/web-component.html).

---

## Vue 3 — `brookmd/vue`

```vue
<script setup lang="ts">
import { BrookClient } from "brookmd/client";
import { BrookMarkdown } from "brookmd/vue";
const client = new BrookClient();
</script>

<template>
  <BrookMarkdown :client="client" :stick-to-bottom="true" />
</template>
```

Component props: `client` (required), `components`, `sanitize`, `virtualize`,
`stickToBottom`, `onLinkClick` (**since 0.30.0**) — only these reach the mount.

- `useBrookMarkdown(getOpts)` → `{ container }`; bind it as the `ref` of the
  element to fill. `getOpts` must read fields lazily so the watcher sees live
  identities; the six watched identities are `client`, `components`, `sanitize`,
  `virtualize`, `stickToBottom`, `onLinkClick`.
- `useBrookMarkdownString(getContent, getOptions?)` → the owned client
  (destroyed on unmount). `setContent` runs only in `onMounted` and a
  non-immediate `watch`, so nothing spawns a worker during SSR.
- `useTailBlockId(client)` → a ref of the open block's id.

---

## Svelte 4 & 5 — `brookmd/svelte`

```svelte
<script lang="ts">
  import { BrookClient } from "brookmd/client";
  import { brookMarkdown, tailBlockId } from "brookmd/svelte";
  const client = new BrookClient();
  const tail = tailBlockId(client);
</script>

<div use:brookMarkdown={{ client, stickToBottom: true }} />
```

Plain `.ts` actions — no `.svelte` compile step, so `use:` works unchanged in 4
and 5. `brookMarkdown` owns only the mount; the caller owns the client. It
remounts only when `client` / `components` / `sanitize` / `virtualize` /
`stickToBottom` / `onLinkClick` actually change identity.

`brookMarkdownString(node, { content, streaming?, config?, ...mountOptions })`
OWNS its client (constructed once from `config`, destroyed on teardown) and
reuses it across remounts so the `setContent` diff baseline survives.

`tailBlockId(client)` is a `Readable<number | null>` that changes only when the
tail id changes.

---

## Solid — `brookmd/solid`

```tsx
import { BrookClient } from "brookmd/client";
import { BrookMarkdown } from "brookmd/solid";

<BrookMarkdown client={client} class="chat" stickToBottom />;
```

`BrookMarkdownProps extends MountOptions` plus `client`, `class`, `style`, but
only `components`, `sanitize`, `virtualize`, `stickToBottom`, `onLinkClick`
(**since 0.30.0**), `highlightCode` and `batch` are forwarded to the mount.
`BrookMarkdown` returns `undefined` when `document` is undefined, so SSR is safe.

Also: `mountSolid`, `setupTailBlockId`, `createTailBlockId`,
`setupBrookMarkdownString`, `createBrookMarkdownString`.

---

## Server / SSR / RSC — `brookmd/server` + `brookmd/server/react`

```ts
import { initBrook, renderToString } from "brookmd/server";
await initBrook();                    // once at startup
const html = renderToString(markdown); // sync, no worker
```

```tsx
import { initBrook } from "brookmd/server";
import { BrookMarkdownStatic } from "brookmd/server/react";

await initBrook();
<BrookMarkdownStatic content={md} config={{ gfmMath: true }} components={COMPONENTS} />;
```

`brookmd/server` is React-free (the build asserts it imports no React), so it
works with no `react` installed. `BrookMarkdownStatic` is hookless and RSC-safe.

**SSR invariants.** The `BrookClient` constructor never touches `Worker` — the
pool is acquired lazily on the first worker-bound operation. Every entrypoint
cold-imports on a server with `window`/`document`/`navigator`/`Worker` deleted,
and the controlled-string helpers never feed the parser on the server. Do not
SSR `BrookMarkdownStatic` and hydrate with `BrookMarkdown`: use the same
component on both sides.

Example: [server-render.ts](../assets/examples/server-render.ts).

---

## Bundlers

### Vite — one required line

Vite's dependency pre-bundling hoists the wasm-bindgen glue into `.vite/deps/`,
which breaks the relative `new URL("…_bg.wasm", import.meta.url)` lookup, so the
worker cannot load WASM (a 404, or a "magic word" error). Exclude brookmd:

```ts
// vite.config.ts
export default defineConfig({
  optimizeDeps: { exclude: ["brookmd"] },
  worker: { format: "es" },
  build: { assetsInlineLimit: 0 },
});
```

`worker: { format: "es" }` and `assetsInlineLimit: 0` are what the reference
setup uses; only `optimizeDeps.exclude` is strictly required. No other bundler
needs this — it is specific to Vite's optimizer.

### Next.js App Router

Verified on Next 16 with Turbopack (the default for `next dev` and `next build`)
and with webpack. Two rules:

1. **`'use client'`.** `<BrookMarkdown>` uses hooks and spawns a Web Worker on
   mount, so it cannot be a Server Component. It is still SSR-safe: on the
   server it renders an empty shell and starts streaming after hydration.
2. **Open the stream in client code.** A `Response` / `ReadableStream` /
   `AsyncIterable` is not serializable, so passing one from a Server Component
   throws *"Only plain objects can be passed to Client Components."* Pass a URL
   or the messages, and fetch on the client.

**No `transpilePackages`** and no asset/loader config — brookmd has shipped
compiled ESM since 0.17.0, and Turbopack emits the `.wasm` itself. The Vite
`optimizeDeps` workaround does not apply.

`brookmd/styles.css` is global CSS: the App Router can import it anywhere; the
Pages Router only allows it from `pages/_app`.

Dev tip: open the app on `localhost` — Next dev blocks cross-origin dev
resources from other hosts (e.g. `127.0.0.1`) unless you list them in
`allowedDevOrigins`.

Example: [nextjs-app-router.tsx](../assets/examples/nextjs-app-router.tsx).

### webpack 5 / Rollup / Parcel

The worker and WASM are referenced with the web-standard
`new URL(asset, import.meta.url)` pattern, so any bundler with asset-module
support resolves them. These three are not machine-verified in the brookmd repo;
Vite and Node ESM/RSC are.

### Plain ESM / CDN, no bundler

Not supported as a first-class path. Nothing is inlined and there is no blob
worker — the wasm is a real asset fetched next to the worker script — so a
no-bundler setup must serve `dist/` with its relative layout intact.

### React Native

`brookmd` maps `dist/asset-urls.js` → `dist/asset-urls.native.js` under Metro,
and that shim throws with "use the brookmd-react-native package". Install
**`brookmd-react-native`** instead: it runs the same Rust core natively over JSI
rather than a Web Worker (RN ≥ 0.76, new architecture).

---

## Content Security Policy

Inferred from the loading mechanism — nothing in the repo states these:

- Same-origin **module worker** → `worker-src 'self'` (and `script-src 'self'`).
- Chromium with a restrictive `script-src` may additionally need
  `'wasm-unsafe-eval'` to instantiate the WASM module.
- **No `blob:` and no `eval` are required** — brookmd uses neither.


==============================================================================
# Source: skills/brookmd/references/recipes.md
==============================================================================

# brookmd — recipes

Copy-pasteable solutions to the things people actually build. Every map,
function and array below belongs at **module scope**: a fresh identity each
render busts the per-block memo and re-renders the whole document per patch.

Runnable versions: [../assets/examples/](../assets/examples/tsconfig.json).

---

## Vercel AI SDK `useChat`

`useChat` gives you a growing **string** per message (joined from
`message.parts`), not a stream — so bridge it with `useBrookMarkdownString`.

```tsx
import { memo } from "react";
import { useChat } from "@ai-sdk/react";
import { BrookMarkdown, useBrookMarkdownString } from "brookmd/react";
import { getDefaultPool } from "brookmd/client";
import type { ParserConfig } from "brookmd";

const CONFIG: ParserConfig = { softBreaks: true, dirAuto: true, a11y: true, blockData: true };

const Message = memo(function Message({ text, streaming }: { text: string; streaming: boolean }) {
  const client = useBrookMarkdownString(text, { config: CONFIG, streaming });
  return <BrookMarkdown client={client} components={COMPONENTS} className="brook-caret" />;
});

export function Chat() {
  const { messages, status } = useChat();
  useEffect(() => { getDefaultPool().warm(); }, []);
  const lastId = messages.at(-1)?.id ?? null;

  return messages.map((m) => (
    <Message
      key={m.id}
      text={m.parts.filter((p) => p.type === "text").map((p) => p.text).join("")}
      streaming={status === "streaming" && m.id === lastId}
    />
  ));
}
```

Three things that are easy to get wrong:

1. **`streaming: false` on finish.** Omitted or `true` leaves the stream OPEN,
   so the last block never commits: a finished fence never highlights and never
   shows its Copy button. brookmd refuses to infer "done" from an absent flag
   because that would re-finalize on every token — an O(n²) reparse trap.
2. **Only the last message can be streaming.** Gate on the message id, or every
   older bubble stays open forever.
3. **`getDefaultPool().warm()`** in the chat shell moves WASM init off the
   first-token critical path.

Full file: [ai-sdk-chat.tsx](../assets/examples/ai-sdk-chat.tsx).

---

## KaTeX

With `gfmMath: true` the core emits KaTeX-ready markup — `<span class="math
math-inline">` / `<div class="math math-display">` carrying the LaTeX — and
stays zero-dep. Two ways to typeset it.

### A. One observer pass over the subtree (what the demo app ships)

Cheap, framework-agnostic, and correct for the streaming case. The two
non-obvious guards are the ones that matter: **skip anything still inside an
open block** (half-typed LaTeX makes KaTeX throw on every patch) and mark what
you typeset so the pass is idempotent.

```tsx
useEffect(() => {
  const root = scrollerRef.current;
  if (!root) return;
  let retry = 0;

  const pass = () => {
    const katex = (window as any).katex;
    if (!katex) { retry = window.setTimeout(pass, 200); return; } // CDN not up yet
    root.querySelectorAll<HTMLElement>(".math:not([data-tex])").forEach((el) => {
      if (el.closest(".brook-streaming, .brook-open")) return; // still streaming
      el.setAttribute("data-tex", "1");                        // idempotence marker
      try {
        katex.render(el.textContent ?? "", el, {
          displayMode: el.classList.contains("math-display"),
          throwOnError: false,
          output: "html",
        });
      } catch { /* leave the raw LaTeX in place */ }
    });
  };

  const obs = new MutationObserver(() => pass());
  obs.observe(root, { childList: true, subtree: true });
  pass();
  return () => { obs.disconnect(); if (retry) clearTimeout(retry); };
}, []);
```

### B. A `components.MathBlock` override

Uses the **block** contract, so `props.text` is the decoded LaTeX (populated
even with `blockData` off; `props.math.latex` is the typed form when it is on)
and `props.open` tells you whether it is safe to typeset yet.

```tsx
const MathBlock = memo((props: BlockComponentProps) => {
  const html = useMemo(
    () => (props.open ? null : katex.renderToString(props.text ?? "", {
      displayMode: true, throwOnError: false,
    })),
    [props.text, props.open],
  );
  return html
    ? <div className="math math-display" dangerouslySetInnerHTML={{ __html: html }} />
    : <pre>{props.text}</pre>;
});
```

Note that `components.MathBlock` replaces the *block* slot only; **inline** math
still needs pass A (or your own inline walk).

---

## Mermaid

`mermaid.render` throws on a half-arrived diagram, which during streaming is
every patch but the last. Gate strictly on `!open`:

```tsx
const Mermaid = memo((props: BlockComponentProps) => {
  const [svg, setSvg] = useState<string | null>(null);
  const id = useRef(`mmd-${Math.random().toString(36).slice(2)}`);

  useEffect(() => {
    if (props.open) { setSvg(null); return; }          // never render a partial diagram
    let live = true;
    mermaid.render(id.current, props.text ?? "")
      .then((r) => { if (live) setSvg(r.svg); })
      .catch(() => {});
    return () => { live = false; };
  }, [props.text, props.open]);

  return svg
    ? <div dangerouslySetInnerHTML={{ __html: svg }} />
    : <pre className="mermaid-source">{props.text}</pre>;   // readable while streaming
});

const COMPONENTS: Components = { Mermaid };
```

The DOM renderer's variant returns `HTMLElement | string` instead of JSX.
brookmd's own default `Mermaid` slot just renders the source verbatim — it ships
no Mermaid runtime.

---

## Shiki (or any async highlighter)

`components.CodeBlock` bypasses the built-in highlighter entirely (so does
`components.pre` or `components.code`). An async highlighter cannot run per
patch, so render plain while `open` and highlight once on close:

```tsx
const CodeBlock = memo((props: BlockComponentProps) => {
  const { text = "", language = "text", open } = props;
  const [html, setHtml] = useState<string | null>(null);

  useEffect(() => {
    if (open) { setHtml(null); return; }               // plain until the fence closes
    let live = true;
    codeToHtml(text, { lang: language, theme: "github-dark" })
      .then((out) => { if (live) setHtml(out); }, () => {});
    return () => { live = false; };
  }, [text, language, open]);

  return html
    ? <div dangerouslySetInnerHTML={{ __html: html }} />
    : <pre><code>{text}</code></pre>;
});
```

`props.meta` carries everything after the language word in the info string
(e.g. `title="src/main.ts"`), and it appears only once it can no longer change —
so a filename header never flickers through a half-typed value.

Trade-off: replacing the slot forfeits brookmd's incremental streaming
highlighter. If all you need is a missing language, `registerLanguage` keeps it.

---

## Register a language with the built-in highlighter

**Since 0.30.0.** Adds a language *inside* the incremental streaming
highlighter, so it keeps colouring the open fence as it grows.

```ts
import { registerLanguage } from "brookmd/highlight";

registerLanguage(["hcl", "tf"], {
  // Ordered [token class, sticky regex] pairs. At each cursor position the
  // FIRST match wins, so put longer forms first. Every regex MUST carry the
  // `y` flag — it is matched against the whole source with `lastIndex` at the
  // cursor, so `^`/`$` (with `m`), lookaheads and `\b` all still work.
  pats: [
    ["com", /#.+/y],
    ["str", /"(?:\\.|[^"\\\n])*"/y],
    ["num", /\b\d+(?:\.\d+)?/y],
    ["ident", /\w+/y],   // required for `kw` to have anything to promote
    ["pun", /[=[\]{}(),.]/y],
    ["ws", /\s+/y],
  ],
  kw: ["resource", "variable", "module", "output", "true", "false"],
});
```

`names` is one name or an array of aliases, lower-cased. Token classes are the
`t-*` set the bundled theme already colours — `kw`, `str`, `rx`, `num`, `lt`,
`com`, `fn`, `ty`, `mac`, `dec`, `attr`, `sel`, `tag`, `var`, `pun`, `txt` —
plus `ws` (whitespace, emitted raw with no span) and `ident`, the pseudo-class
whose matches are promoted to `kw` when they appear in the `kw` set. `kw`
without an `ident` pattern does nothing. A pattern must never match the empty
string (registration throws).

It throws a `TypeError` (naming the offending pattern index) for a non-sticky
regex or an unknown token class. Registering an existing name **replaces** its
table — including a built-in one, which is how you retune `yaml` or `json`
rather than living with the shipped taste.

Caveat: while the block is still streaming, a registered language is
re-tokenized from the top on each patch instead of growing a frozen prefix (the
frozen-prefix rule needs to know which forms can run past a newline, and a
caller-supplied table does not say). The size cap bounds that work, and nothing
about the settled markup differs.

Built in as of 0.30.0: js/javascript/jsx, ts/tsx/typescript, rust/rs,
py/python, go, bash/sh/shell, json, sql, html/xml, css, java, c, cpp/c++,
cs/csharp, swift, kt/kotlin, php, rb/ruby, yaml/yml, toml, diff, dockerfile.
`supportedLangs()` returns the live list, registrations included. An unknown
language, or code longer than 50 000 characters, renders as plain escaped text.

---

## Table toolbar from `blockData`

With `blockData: true` a `Table` block's `props.table` is
`{ headers, rows, aligns }` where every cell is `{ text, html }` — `text` is
inline-stripped plaintext for sort/filter/CSV/chart, `html` is the display
markup. No HTML re-parse, no AST walk.

```tsx
// RFC-4180: quote any field containing a comma, quote, or newline; double
// internal quotes. Built from cell.text — never from the display HTML.
function toCsv(table: TableData): string {
  const quote = (s: string) => (/[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
  const line = (cells: { text: string }[]) => cells.map((c) => quote(c.text)).join(",");
  return [line(table.headers), ...table.rows.map(line)].join("\n");
}

const Table = memo((props: BlockComponentProps) => {
  const table = props.table;
  const [filter, setFilter] = useState("");

  // Guard: blockData may be off, or an open table may arrive before its data is
  // populated. Fall back to the block HTML instead of crashing.
  if (!table) return <div dangerouslySetInnerHTML={{ __html: sanitize(props.html) }} />;

  // Keep only UI state in React and DERIVE the rows, so the table keeps
  // reflecting rows that stream in (the override runs on open blocks too).
  const rows = filter
    ? table.rows.filter((r) => r.some((c) => c.text.toLowerCase().includes(filter.toLowerCase())))
    : table.rows;

  return (
    <div>
      <input value={filter} onChange={(e) => setFilter(e.target.value)} aria-label="Filter rows" />
      <button onClick={() => navigator.clipboard.writeText(toCsv(table))}>Copy CSV</button>
      {props.open && <span className="live-dot" title="streaming" />}
      <table>{/* render headers/rows from table.headers / rows, aligns[i] for text-align */}</table>
    </div>
  );
});
```

The block is keyed by its stable parser id, so this component's state survives
every streaming patch.

---

## Interactive task checkboxes

GFM task-list checkboxes are emitted `disabled` (byte-exact GFM). Override the
`input` **tag** to make them live. That is the element contract — attributes and
`children`, **no `block` prop** — so map back to the source via the block you
render it in, using `block.start` / `block.end`.

```tsx
const COMPONENTS: Components = {
  input: (p: any) =>
    p.type === "checkbox"
      ? <input type="checkbox" checked={!!p.checked} onChange={onToggle} />
      : <input {...p} />,
};
```

With `a11y: true` the core wraps the checkbox and its text in a `<label>`, which
is what you want for screen readers.

---

## Lazy images and image proxying

```tsx
const COMPONENTS: Components = {
  img: (p: any) => <img {...p} loading="lazy" decoding="async" />,
};

// Proxy remote images. Output is re-sanitized, so it can't smuggle a scheme.
const URL_TRANSFORM: UrlTransform = (url, ctx) =>
  ctx.attr === "src" && /^https?:/i.test(url)
    ? `/img-proxy?u=${encodeURIComponent(url)}`
    : url;
```

`urlTransform` works standalone — it does not need a `components` map. The core
emits `<img src alt [title]>` and nothing else, so `loading`/`decoding`/sizing
are yours to add.

---

## Accessible chat

```tsx
<BrookMarkdown
  client={client}
  role="log"            // a running record of messages
  aria-live="polite"    // coalesced announcements, not per-token
  aria-atomic={false}
  streamConfig={{ a11y: true }}
/>
```

`role`, `aria-live`, `aria-atomic`, `id` and `className` all land on the
`.brook-md` root, on React and on the DOM mount (and therefore on the web
component and the Vue/Svelte/Solid bindings). `a11y: true` adds `<label>`-wrapped
task checkboxes and `scope="col"` on table headers. If you SSR and hydrate, the
root's a11y attributes must match on both sides or React reports a hydration
mismatch.

Focus management (restoring focus after a stream replaces content, "skip to end
of message") belongs to your app shell — brookmd does not move focus.

---

## Persist and reopen a thread instantly

Re-feeding a long thread through the parser on reopen is O(source) and blocks
the first paint. Persist the rendered snapshot instead: restoring it is pure
JSON — **no worker, no WASM, no parse**.

```ts
import { BrookClient, sourceFingerprint } from "brookmd/client";

// On close / navigate away:
const snap = client.getPersistable(sourceText);   // { hydrateVersion, blocks, sourceLength, sourceHash, done }
localStorage.setItem(`thread:${id}`, JSON.stringify(snap));

// On reopen — must be an untouched client:
const client = new BrookClient();
const snap = JSON.parse(localStorage.getItem(`thread:${id}`)!);
if (snap.sourceHash === sourceFingerprint(sourceText)) {
  client.hydrate(snap, { source: sourceText });   // { source } only needed to resume
}
```

- A `done: true` snapshot is terminal: appending to it throws.
- A `done: false` snapshot needs `{ source }` to resume; the first
  `append`/`finalize` transparently restarts the parser from it.
- `getPersistable()` throws if you constructed the client with
  `recovery: false` and fed it manual `append`s — pass the source explicitly.
- `sourceHash` is a staleness check (FNV-1a), deliberately not a security
  primitive.

---

## Measure parse time

```ts
const m = client.getMetrics();
// { bytes, patches, meanParseMicros, totalParseMs, throughputKBs,
//   committedBlocks, activeBlocks, lastPatchAgoMs, retainedBytes,
//   wasmMemoryBytes, renderCount, rebuildCount }

console.log(`${m.bytes} B in ${m.totalParseMs.toFixed(1)} ms `
          + `(${m.meanParseMicros.toFixed(0)} µs/patch, ${m.throughputKBs.toFixed(0)} kB/s)`);
```

Per-block render churn:

```tsx
<BrookMarkdown
  client={client}
  onRenderMetrics={(blockId, m) => {
    // Fires only on an ACTUAL render — a memo-skipped committed block never does.
    if (m.renderCount > 50) console.warn("hot block", blockId, m.kind, m.renderCount);
  }}
/>
```

A committed block that keeps re-rendering means an unstable prop identity
(`components` / `decorators` / `urlTransform` / `sanitize` / `onBlockError`).

Note that `wasmMemoryBytes` and worker-level counters are shared across the
streams multiplexed onto one worker, so don't sum them across clients.

---

## Table of contents

```ts
const entries = client.outline();  // [{ level, text, id }, …] — id is the block id
```

`text` is plaintext with tags stripped and entities decoded; `id` is the stable
block id, usable as a scroll target and a React key. With `blockData: true` a
`Heading` block also carries `{ level, text, id }` where `id` is a GitHub-style
anchor slug — note `kind.data` for headings is a **union**: an object with
`blockData` on, a bare `number` (the level) with it off.

`client.toPlaintext()` gives the whole document as plain text.


==============================================================================
# Source: skills/brookmd/references/security.md
==============================================================================

# brookmd — security model

Sanitization happens in the Rust core, before any HTML crosses the worker
boundary. The defaults are safe for untrusted / model-generated markdown: raw
HTML is escaped, dangerous URL schemes are neutralized, and every link is
`rel`-hardened. Everything below is about the knobs that relax or extend that.

---

## 1. URL policy

Applied uniformly to links, URI autolinks, images, and sanitized URL attributes.
A blocked URL becomes `#`.

**Never allowed, non-overridable** — `allowSchemes` cannot re-enable these, the
same way allowlisting `<script>` cannot re-enable it:

- `javascript:`
- `vbscript:`
- `data:text/html`
- `data:text/javascript`
- the scriptable `data:` media types on the **href** path — `data:image/svg`,
  `data:application/xhtml`, `data:text/xml`, …

**Overridable-blocked** — currently just `file:`. Re-enable with bare scheme
names, no colon, matched case-insensitively:

```ts
new BrookClient({ config: { allowSchemes: ["file"] } });
```

Only do that in a host that intercepts link clicks instead of navigating (an
Electron or extension UI that opens the path in an editor). Local-resource
disclosure then becomes the embedder's responsibility.

**Not a general allowlist.** `allowSchemes` never *restricts* anything. Schemes
outside the built-in blocklist (`vscode:`, `ftp:`, `mailto:`, …) already render
and are unaffected.

**Images** keep their own allowlist: `http(s)`, `data:image/` (minus SVG, which
is never allowed), and relative paths.

**Every rendered link carries** `target="_blank" rel="noopener noreferrer nofollow"`
— including autolinks and the pending streaming anchor. This is a deliberate,
documented deviation from reference CommonMark output, folded by the
`canonicalize` step used for conformance comparison.

### `safeUrl` — the JS-side filter

```ts
import { safeUrl, wrapLink } from "brookmd";
```

`safeUrl(value)` decodes entities to a fixpoint (capped at 8 iterations), strips
control characters, and blocks the four script-executing prefixes, returning `#`
otherwise. Use it on any URL you build yourself in a `decorator` or a
`components` override. `wrapLink(text, attrs)` builds an `<a>` whose `href` is
already routed through it.

---

## 2. Raw HTML — four tiers

| Tier | Config | Behaviour |
|---|---|---|
| Default | — | Raw HTML is **escaped**. Safe for untrusted input. |
| Safe inline subset | `htmlAllowlist: [...]` or `dropHtmlTags: [...]` | Setting **either** (even to `[]`) engages the sanitizer for *inline* raw HTML. `htmlAllowlist: []` = allow every tag except a built-in dangerous set (`script`, `style`, `iframe`, `object`, `embed`, `form`, `input`, `svg`, …). A non-empty array renders only those tags and escapes the rest. Attributes are sanitized (event handlers dropped, dangerous URL schemes → `#`); HTML comments are dropped. Case-insensitive. |
| Safe block subset | `blockHtml: true` **plus** one of the above | Extends the sanitizer to CommonMark HTML block **types 6 and 7** — a known block-level tag alone on its line, so `<details><summary>…</summary>…</details>` renders as real elements. Types 1–5 stay escaped: type 1 is the raw-text family (`<script>`, `<pre>`, `<style>`, `<textarea>`), where a speculative mid-stream close is mXSS-prone; types 2–5 carry no renderable element. While the block streams, still-open elements get speculative closers, so what the reader has seen is a complete tree at every append. Markdown *inside* the HTML is not parsed. |
| Everything | `unsafeHtml: true` | Raw HTML passes through unescaped. **Never enable for untrusted input.** With it on, `gfmTagfilter: true` at least escapes GFM's nine disallowed tags. |

`dropHtmlTags` removes the markup entirely and leaves any text between an
open/close pair as inert text — useful for app marker tags, or as
belt-and-suspenders `["script","style"]`.

**Component tags are the safe alternative to `unsafeHtml`.** `componentTags:
["Thinking"]` / `inlineComponentTags: ["cite"]` allowlist named tags whose inner
content is parsed as **markdown** and whose attributes are sanitized — no
`unsafeHtml` needed. The renderer dispatches them through `components[tag]`.

---

## 3. The `sanitize` hook

For markdown from a model you do not control, and especially with `unsafeHtml`
on, pass a **hoisted** sanitizer. It runs before every `innerHTML` injection,
**including the open (streaming) tail** — so a half-arrived hostile tag is
sanitized on every patch, not just at commit.

```tsx
import DOMPurify from "dompurify";
import { BrookMarkdown } from "brookmd/react";

// Module scope: a fresh identity each render busts the per-block memo.
const sanitize = (html: string) => DOMPurify.sanitize(html);

<BrookMarkdown
  stream={stream}
  streamConfig={{ unsafeHtml: true }}
  sanitize={sanitize}
/>;
```

The same option exists on `MountOptions` (`brookmd/dom`), as the
`<brook-markdown>` `.sanitize` property, and on the Vue / Svelte / Solid
bindings.

**What `sanitize` does NOT cover:** the built-in `CodeBlock` / `MathBlock` /
`Mermaid` renderers operate on already-escaped content and deliberately bypass
it. If you replace those slots and inject HTML yourself, sanitize it yourself.

---

## 4. Trusted surfaces — read before writing an override

Two extension points are **trusted and un-sanitized**:

- **`decorators`.** A decorator's `replace` output is spliced straight into the
  render tree; it does not pass through brookmd's attribute sanitizer (that only
  runs on attributes the trusted core emitted). React and the DOM both happily
  render a `javascript:` href. Build only trusted nodes, and route any href
  through `safeUrl` or `wrapLink`.
- **`components`.** Same rule. Anything you `dangerouslySetInnerHTML` inside an
  override is on you.

**`urlTransform` is the exception — its output IS re-sanitized**
(`safeUrl(transform(safeUrl(value)))`), so a buggy or hostile transform can
never emit a `javascript:` / `data:text/html` URL that reaches the DOM.

---

## 5. `onLinkClick` — interstitials and in-app routing (since 0.30.0)

Model-generated URLs are attacker-influenced content. `onLinkClick` gives you a
single delegated hook to gate navigation, without a `components.a` override:

```tsx
const ALLOWED = /^https:\/\/(docs\.)?example\.com\//;

<BrookMarkdown
  stream={stream}
  onLinkClick={(event, link) => {
    if (!ALLOWED.test(link.href)) {
      event.preventDefault();      // cancels navigation
      openInterstitial(link.href); // "You are leaving…"
    }
  }}
/>;
```

`link` is `{ href, text, element }`. Exactly ONE listener sits on the
`.brook-md` root and resolves the anchor from the event target — no per-anchor
prop, no per-block cost, and the streaming path is untouched. A still-streaming
anchor (`<a data-brook-pending>`, label rendered, URL not yet arrived) is never
reported, because there is no `href` to hand you yet.

The same option exists on `MountOptions`, as the `<brook-markdown>`
`.onLinkClick` property, and on the Vue / Svelte / Solid bindings (there the
event is a native `MouseEvent`; in React it is the synthetic event).

`onLinkClick` is not a security boundary on its own — `rel="noopener
noreferrer nofollow"` and the scheme blocklist still do the hard work. It is the
place to add product policy on top.

---

## 6. Checklist for untrusted / model output

1. Leave `unsafeHtml` **off**. If the model must emit HTML, prefer
   `htmlAllowlist` (+ `blockHtml`) over `unsafeHtml`.
2. Pass a hoisted `sanitize` when you do relax raw HTML.
3. Use `componentTags` / `inlineComponentTags` instead of `unsafeHtml` for
   structured model output.
4. Never build a URL in a `decorator` or override without `safeUrl` / `wrapLink`.
5. Use `urlTransform` for image proxying — its output is re-sanitized.
6. Gate navigation with `onLinkClick` if your product needs an interstitial.
7. Leave `allowSchemes` empty unless you own the click handling.
8. Wire `onBlockError` so a throwing override is reported rather than silently
   swallowed by the per-block error boundary.


==============================================================================
# Source: skills/brookmd/references/styling.md
==============================================================================

# brookmd — styling

brookmd emits semantic HTML under a `.brook-md` root and **ships no CSS by
default**. Either bring your own design system, or opt into the bundled theme:

```ts
import "brookmd/styles.css";
```

The theme is scoped to `.brook-md`, zero-runtime, and **does not change the
rendered HTML** — skip the import and nothing is styled (including the built-in
highlighter's colours: without CSS, highlighted code renders uncoloured).

Entries labelled **since 0.30.0** are new in that release.

---

## 1. CSS variables

Re-theme by overriding a handful of custom properties rather than rewriting
selectors:

```css
.brook-md {
  --brook-accent: #7c3aed;   /* links */
  --brook-bg-code: #faf7ff;  /* code background */
  --brook-t-kw: #c026d3;     /* syntax: keywords */
}
```

| Group | Variables |
|---|---|
| Surfaces / text | `--brook-fg`, `--brook-fg-muted`, `--brook-fg-faint`, `--brook-border`, `--brook-bg-code`, `--brook-bg-inline`, `--brook-bg-quote`, `--brook-accent` |
| Alerts | `--brook-alert-note`, `--brook-alert-tip`, `--brook-alert-important`, `--brook-alert-warning`, `--brook-alert-caution` |
| Syntax tokens | `--brook-t-kw`, `--brook-t-str`, `--brook-t-num`, `--brook-t-com`, `--brook-t-fn`, `--brook-t-ty`, `--brook-t-mac`, `--brook-t-attr`, `--brook-t-tag`, `--brook-t-var`, `--brook-t-pun` |
| Motion | `--brook-caret` (colour), `--brook-caret-anim`, `--brook-pill-anim` — both animations are set to `none` under `prefers-reduced-motion: reduce` |
| Sizing | `--brook-radius`, `--brook-gap` |

**Dark mode** is automatic via `prefers-color-scheme`. Force a mode with
`class="brook-md brook-dark"` or `class="brook-md brook-light"` — the
`prefers-color-scheme` block is written as `.brook-md:not(.brook-light)`, so
`brook-light` wins in a dark OS and `.brook-md.brook-dark` wins in a light one.

---

## 2. The block-state class contract

These classes are a **stable, documented styling contract** (**since 0.30.0** —
they were emitted before, but undocumented). React, the DOM renderer, and the
static server renderer all emit the same names.

| Class | Where | Meaning |
|---|---|---|
| `brook-md` | root `<div>` | always present; `className` is appended to it |
| `brook-block` | per-block wrapper | every block on the generic path |
| `brook-block-<kind>` | per-block wrapper | lowercased kind: `brook-block-paragraph`, `-heading`, `-codeblock`, `-mathblock`, `-mermaid`, `-list`, `-blockquote`, `-alert`, `-table`, `-rule`, `-html`, `-component` |
| `brook-open` | per-block wrapper | the block is still streaming; its HTML may still change |
| `brook-speculative` | per-block wrapper | closed speculatively, may yet be revised |
| `brook-streaming` | code / math / mermaid slot | that renderer's own "still open" marker |
| `brook-deferred` | root | present while `deferTail` is deferring |
| `brook-bottom-anchor` | sentinel `<div>` | emitted by `stickToBottom` (`scroll-snap-align: end`) |

Core-emitted markup you can also target: `code.language-X[data-lang="X"]`,
`div.math.math-display` / `span.math.math-inline`,
`div.markdown-alert.markdown-alert-<kind>` with `p.markdown-alert-title`,
`section.footnotes[role="doc-endnotes"]` with `sup.footnote-ref`, and
`a[data-brook-pending]` for a streaming link whose URL has not arrived yet.

An anchor with no `href` gets no default link styling, so without a rule the
link "pops" blue only when the URL completes. The bundled theme already styles
it; if you bring your own CSS, copy:

```css
.brook-md a[data-brook-pending] {
  color: var(--brook-accent, #0969da);
  cursor: default;
}
```

---

## 3. Code-block chrome

The built-in `CodeBlock` renderer emits its own header bar with a language
label, a Copy button (closed blocks) or a "streaming" pill (open blocks), and a
scrollable body:

```
div.brook-code-block[.brook-streaming]
  div.brook-code-header
    span.brook-code-lang
    span.brook-code-streaming-pill   (open)
    button.brook-code-copy           (closed)
  div.brook-code-body
    pre > code                       (highlighted)
```

`MathBlock` and `Mermaid` mirror it: `brook-math-block` / `-header` / `-lang` /
`-body` and `brook-mermaid-block` / `-header` / `-lang` / `-body`, both reusing
`brook-code-streaming-pill` while open.

**Since 0.30.0 `brookmd/styles.css` styles all of this chrome.** Before that the
theme left it unstyled, so `import "brookmd/styles.css"` produced a themed
document with a raw button stack above every fence. If you are on an older
version, or you skip the theme, style those classes yourself.

The code body is keyboard-scrollable and labelled (`tabIndex={0}`,
`role="region"`, `aria-label="<lang> code"`), and the copy button carries
`aria-label` + `aria-live="polite"` — preserve those if you replace the slot.

---

## 4. Streaming caret (opt-in, since 0.30.0)

Add the `brook-caret` class to the root and `brookmd/styles.css` draws a blinking
caret at the end of the open (streaming) block:

```tsx
<BrookMarkdown stream={stream} className="brook-caret" />
```

```ts
mountBrookMarkdown(client, el, { className: "brook-caret" });
```

It is opt-in so default output is unchanged, and it is pure CSS keyed off
`brook-open` — no JS, no extra DOM, nothing on the streaming path. The selectors
are anchored so exactly one element in an open block can match: the trailing
paragraph or heading, the deepest last list item, the last cell of a streaming
table, the tail of a blockquote.

- **Retint** with `--brook-caret` (default `currentColor`).
- **Retime** with `--brook-caret-anim`; `prefers-reduced-motion: reduce` sets it
  (and the "streaming" pill's pulse) to `none`.
- **Switch it off wholesale** with
  `.brook-md.brook-caret ::after { content: none }`.
- It is deliberately **not** drawn inside code / math / mermaid fences — those
  show the "streaming" pill instead.

---

## 5. Tailwind and design systems

Two mechanisms, both of which also apply to the **open/streaming** block:

**Root class.** `className` is appended to `brook-md`, which is always kept:

```tsx
<BrookMarkdown stream={stream} className="prose prose-slate max-w-none" />
```

**Element-path `components`.** Lowercase tag keys receive the element's
attributes and `children` — no `block` prop. Hoist the map:

```tsx
const COMPONENTS: Components = {
  p:  (p: any) => <p className="my-3 leading-7" {...p} />,
  ul: (p: any) => <ul className="my-3 list-disc pl-6" {...p} />,
  ol: (p: any) => <ol className="my-3 list-decimal pl-6" {...p} />,
  li: (p: any) => <li className="my-1" {...p} />,
  a:  (p: any) => <a className="text-sky-600 underline underline-offset-2" {...p} />,
  h1: (p: any) => <h1 className="mt-6 mb-3 text-2xl font-semibold" {...p} />,
  h2: (p: any) => <h2 className="mt-6 mb-3 text-xl font-semibold" {...p} />,
  h3: (p: any) => <h3 className="mt-5 mb-2 text-lg font-semibold" {...p} />,
  table: (p: any) => <table className="w-full border-collapse text-sm" {...p} />,
  code: (p: any) => <code className="rounded bg-slate-100 px-1 py-0.5" {...p} />,
  blockquote: (p: any) => <blockquote className="border-l-4 pl-4 italic" {...p} />,
};
```

`class` is renamed to `className` on the React path, so `{...p}` spreads cleanly.
The DOM renderer has no tag-level path — use a block-kind override there and
rewrite the `html` it is handed.

> **`@tailwindcss/typography` users: skip `brookmd/styles.css`.** `.brook-md` is
> a plain `<div>`, so `class="prose brook-md"` works — but the theme's
> `.brook-md > * { margin: 0 0 var(--brook-gap) }` reset fights `prose`'s own
> vertical rhythm. Import the theme or use `prose`, not both. If you skip the
> theme you must supply the highlighter token colours yourself (see §6).

**The identity footgun.** A fresh `components` / `decorators` / `urlTransform` /
`sanitize` object on each render busts the per-block memo, so every committed
block re-renders on every patch. Define them at module scope, or `useMemo` with
a stable dependency list. (`onLinkClick` is the exception — it is delegated, so
a fresh closure costs nothing.)

---

## 6. Highlighter token classes

The built-in highlighter emits `<span class="t-…">`. The bundled theme colours
them from the `--brook-t-*` variables; without any CSS, code renders uncoloured.

`t-kw` (keyword), `t-str` (string), `t-rx` (regex), `t-num` (number), `t-lt`
(literal), `t-com` (comment), `t-fn` (function), `t-ty` (type), `t-mac`
(macro), `t-dec` (decorator), `t-attr` (attribute), `t-sel` (selector), `t-tag`
(tag), `t-var` (variable), `t-pun` (punctuation), `t-txt` (text). Whitespace
(the `ws` token class) is emitted raw, with no span.

A language table may also use the pseudo-class `ident`, whose matches are
promoted to `kw` when the word is in that language's keyword set.

These are also the token classes `registerLanguage` definitions emit — see
[recipes.md](recipes.md#register-a-language-with-the-built-in-highlighter).


==============================================================================
# Source: skills/brookmd/references/troubleshooting.md
==============================================================================

# brookmd — troubleshooting

Symptom → cause → fix.

---

## The container is empty: `<div class="brook-md">` with nothing in it and no console output

**Cause.** The worker script 404'd or its boot never completed — most often a
stale hashed worker URL in a long-lived tab after a deploy, or a bundler that
did not emit the worker/WASM asset.

**Fix.**
- Be on ≥ 0.24.0, where the client registers `error` / `messageerror` listeners
  on the worker and enforces a per-worker **boot deadline (default 20 000 ms)**.
- Render a fallback off the failure signals:

```ts
const client = new BrookClient({
  onError: (err) => { if (err.fatal) showReloadPrompt(); },
});
// …or poll the getter:
if (client.failed) showReloadPrompt();
```

- `recovery` defaults to **true**: the first fatal worker death is healed
  invisibly by re-feeding the buffered document, `failed` stays `null`, and
  `onError` does **not** fire. A *second* death is terminal — that is when
  `failed` is set and `onError` fires. Long-lived tabs should prompt a reload.
- Tune or disable the boot deadline with `new BrookPool(factory, cap, { bootTimeoutMs })`
  (`0` disables it) and pass the pool as `new BrookClient({ pool })`.
- With `recovery: false` you save the buffer on giant documents, but
  `getPersistable()` then throws unless you pass the source explicitly, and a
  worker death restarts the document with a dev warning instead of healing.

---

## Vite: WASM 404, or "magic word" / bad module error

**Cause.** Vite's dependency pre-bundling hoists the wasm-bindgen glue into
`.vite/deps/`, which breaks the relative `new URL("…_bg.wasm", import.meta.url)`
lookup.

**Fix.**

```ts
// vite.config.ts
export default defineConfig({
  optimizeDeps: { exclude: ["brookmd"] },
  worker: { format: "es" },
  build: { assetsInlineLimit: 0 },
});
```

Only `optimizeDeps.exclude` is strictly required. This is specific to Vite; no
other bundler needs it.

---

## Next.js: "Only plain objects can be passed to Client Components", or a hooks error

**Cause (a).** The component is a Server Component. `<BrookMarkdown>` uses hooks
and spawns a Web Worker on mount.
**Fix.** Put `'use client'` at the top of the file.

**Cause (b).** A `Response` / `ReadableStream` / `AsyncIterable` was passed as a
prop from a Server Component. Streams are not serializable.
**Fix.** Pass a URL or the messages from the server and open the stream in
client code.

You do **not** need `transpilePackages` (not since 0.17.0) or any
asset/loader config, and the Vite `optimizeDeps` workaround does not apply.

---

## React hydration mismatch on the root

**Cause.** The root's `className` / `role` / `aria-live` / `aria-atomic` / `id`
differ between the server markup and the client render.

**Fix.** Pass identical root a11y props on both sides. Also: do not SSR
`<BrookMarkdownStatic>` and hydrate with `<BrookMarkdown>` — the client
renderer's markup (code chrome, Mermaid slots) does not hydrate the static
renderer's plainer markup. Use the same component on both sides.

---

## Everything re-renders on every patch

**Cause.** An inline object/array/function identity for `components`,
`decorators`, `urlTransform`, `sanitize` or `onBlockError`. A fresh identity
busts the per-block memo, so every committed block re-renders per patch —
quadratic over a stream.

**Fix.** Define them at module scope, or `useMemo`/`useCallback` with a stable
dependency list. In development brookmd emits a one-shot warning when
`decorators` or `urlTransform` change identity. `onLinkClick` is exempt: it is
delegated to the root, so a fresh closure re-renders nothing.

Confirm with `onRenderMetrics` — a committed block whose `renderCount` keeps
climbing is the smoking gun.

---

## `can't access property "kind", block is undefined` and the page blanks

**Cause.** The `components` **two-contract collision**. The same key is served by
two dispatchers: the block dispatcher passes `BlockComponentProps` (with
`block`), the element dispatcher passes attributes + `children` only (**no
`block`**). A component registered for a name that can appear in both positions
read `props.block` unconditionally.

**Fix.** Guard:

```tsx
const Thinking = ({ block, children }: any) =>
  block ? <Panel data={block.kind.data}>{children}</Panel> : <span>{children}</span>;
```

Type block-kind keys to `BlockComponentProps` (the `Components` mapped type does
this for you, so the mismatch becomes a compile error), and never read
`props.block` on an element-path override. The per-block error boundary contains
the crash to one block; wire `onBlockError` to see it.

---

## Code renders uncoloured

**Cause.** `brookmd/styles.css` was not imported. The highlighter emits
`<span class="t-…">` and ships no colours of its own.

**Fix.** `import "brookmd/styles.css";` — or define the `--brook-t-*` variables /
`.t-*` rules yourself if you bring your own theme.

Related: a big fence can render unhighlighted for a beat because close-time
highlighting is sliced across tasks. The settled markup is byte-identical to a
direct `highlight()` call.

---

## A finished code fence never highlights and shows no Copy button

**Cause.** The stream was never finalized. With `useBrookMarkdownString` /
`brookMarkdownString` / `useBrookMarkdown`-string helpers, omitting `streaming`
(or leaving it `true`) keeps the stream OPEN forever.

**Fix.** Pass `streaming: false` when the content is final — or call
`client.finalize()` / `client.setContent(text, { done: true })` directly.

---

## Math is not typeset while streaming

**Cause.** By design. An open block holds partial LaTeX, and KaTeX throws on it
on essentially every patch.

**Fix.** Skip anything inside `.brook-open` / `.brook-streaming` in your typeset
pass, mark what you have typeset (`data-tex`) so the pass is idempotent, and
re-run it from a `MutationObserver`. Same rule for Mermaid: gate strictly on
`!props.open`. See [recipes.md](recipes.md#katex).

---

## `componentTags` / `blockData` / `gfmMath` silently stop working mid-session

**Cause.** The stream's config was latched and not resent when the parser was
rebound to a new worker. Fixed in 0.24.0 / 0.25.0.

**Fix.** Upgrade. Remember that `ParserConfig` is applied once and is
**immutable** for a stream's lifetime — `reset()` keeps it; use a new client for
different flags.

---

## Duplicate React keys, or the document shrinks after an error

**Cause.** Two parser generations merged under colliding block ids after a
worker restart. Fixed: a restart now starts a clean generation and warns.

**Fix.** Upgrade. In development you will see "the parser was rebuilt on a new
worker … document restarted".

---

## A missed final render, or a frame-late "done"

**Cause.** rAF coalescing (`coalesce: true` on the React hooks' internal client,
`batch: true` on the DOM mount).

**Fix.** Nothing — the finalize patch always flushes **synchronously**, and
`reset()` cancels the pending frame. If you own the client and need every patch
synchronously, construct it with `coalesce: false` (the constructor default).

---

## First-token latency spike

**Cause.** WASM init is on the critical path for the first stream.

**Fix.** Warm the pool on route entry:

```tsx
useEffect(() => { getDefaultPool().warm(); }, []);
```

---

## Content Security Policy

Inferred from the loading mechanism — nothing in the repo states these
directives, so treat them as a starting point:

- The worker is a **same-origin ES module worker**, so you need
  `worker-src 'self'` and `script-src 'self'`.
- Chromium with a restrictive `script-src` may additionally require
  `'wasm-unsafe-eval'` to instantiate the module.
- **No `blob:` and no `eval` are needed** — brookmd creates neither a blob
  worker nor inlined base64 WASM. The package's own build asserts this.

---

## React Native: "use the brookmd-react-native package"

**Cause.** Metro resolved `brookmd`'s `react-native` field, which maps the asset
resolver to a shim that throws — the Web Worker path cannot work on Hermes.

**Fix.** Install **`brookmd-react-native`**, which runs the same Rust core
natively over JSI (RN ≥ 0.76, new architecture).

---

## Memory grows on very long streams

- `retainCommittedHtml` is **off** on the worker path by default, which is what
  you want: the client receives each committed block once and stores it itself.
  Turn it on only if you need the parser to still hold the whole document.
  The server renderers pin it on regardless.
- `virtualize` applies `content-visibility: auto` to **closed** blocks (hundreds
  of blocks and up). It never defers the tail. Beware `flex`/`grid` parents.
- `stickToBottom` is CSS-only: it emits a snap sentinel, and you must add
  `scroll-snap-type: y proximity` to your scroll container. Safari re-snap is
  best-effort.
- Read `getMetrics().retainedBytes` / `wasmMemoryBytes` to confirm — but note
  worker-level numbers are shared by every stream multiplexed onto that worker.