brookmd 0.22.0

package/dist/types-core.d.ts

@@ -0,0 +1,436 @@
+export type BlockKindTag = "Paragraph" | "Heading" | "CodeBlock" | "MathBlock" | "Mermaid" | "List" | "Blockquote" | "Alert" | "Table" | "Rule" | "Html" | "Component";
+export interface BlockKind {
+    type: BlockKindTag;
+    data?: unknown;
+}
+/**
+ * The node type a {@link Decorator} (or `wrapLink`) builds. Kept `unknown` here
+ * so this framework-neutral types module stays React-free: the React binding
+ * treats it as `ReactNode`, the DOM binding (`brookmd/dom`) as `Node | string`.
+ */
+export type BrookNode = unknown;
+/**
+ * Wrap or replace matched inline **text** while streaming, in O(n). A decorator
+ * runs POST-PARSE on real inline TEXT nodes only (after the core renders a block
+ * to HTML and the walker parses it), once per committed block — so it never sees
+ * URLs, code, or markup, and a value split by inline markup (e.g.
+ * `$2.<em>5</em>B`) is two text nodes and won't match across them.
+ *
+ * **Trusted surface (read this).** A decorator's `replace` output is spliced
+ * directly into the render tree and 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. Treat `decorators` exactly
+ * like `components`: only build trusted nodes, and route any link href through
+ * the exported `safeUrl` (or use the `wrapLink` helper, which does it for you).
+ *
+ * **Stability matters (the #1 footgun).** Pass a HOISTED / memoized array — a
+ * fresh `decorators` identity every render busts the per-block memo, so every
+ * committed block re-parses and re-decorates on every patch (O(n²)). The React
+ * binding emits a one-time dev warning if the identity changes.
+ */
+export interface Decorator {
+    /** Tested against each inline TEXT node's string only (never URLs/code/markup). */
+    match: RegExp | string;
+    /** PURE fn building the replacement for ONE match. Returns framework nodes. */
+    replace: (matchText: string, groups: string[]) => BrookNode;
+    /** Ancestor tags to skip. Default `['a','code','pre','kbd']`. */
+    skipInside?: string[];
+}
+/**
+ * Rewrite a URL attribute (`href`/`src`/`poster`) as a block renders — e.g. to
+ * proxy images or add UTM params. Applied O(1) per attribute. The renderer
+ * re-sanitizes the OUTPUT (`safeUrl(urlTransform(safeUrl(value)))`), so a buggy
+ * or hostile transform can never emit a `javascript:` / `data:text/html` URL
+ * that reaches the DOM. Like `decorators`, pass a HOISTED / memoized function so
+ * the per-block memo holds.
+ */
+export type UrlTransform = (url: string, ctx: {
+    tag: string;
+    attr: "href" | "src" | "poster";
+}) => string;
+/** Column alignment from the `|:--|:-:|--:|` delimiter row; `null` = unset. */
+export type Align = "left" | "center" | "right" | null;
+/**
+ * One table cell as STRUCTURED DATA (opt-in via {@link ParserConfig.blockData}).
+ * `text` is the inline-stripped plaintext — sort/filter/CSV/chart from DATA,
+ * with no HTML re-parse. `html` is the inline-rendered display markup, byte-for-
+ * byte the inline content inside the matching `<td>`/`<th>` of `block.html`.
+ */
+export interface TableCell {
+    text: string;
+    html: string;
+}
+/**
+ * A Table block's `kind.data` when {@link ParserConfig.blockData} is on. Lets a
+ * consumer build a sort/filter/transpose/chart/CSV toolbar from DATA alone —
+ * no HAST tree, no HTML re-parse. `aligns[i]` is column `i`'s alignment.
+ */
+export interface TableData {
+    headers: TableCell[];
+    rows: TableCell[][];
+    aligns: Align[];
+}
+/**
+ * A Heading block's `kind.data` when {@link ParserConfig.blockData} is on. Lets a
+ * consumer build a table of contents — nested by `level`, anchored by `id` — from
+ * DATA alone, with no HTML re-parse. `text` is the inline-stripped plaintext (the
+ * heading rendered to plain text, e.g. `## **Bold** & x` → `"Bold & x"`); `id` is
+ * a GitHub-style anchor slug of that text (`"bold-x"`) for `#`-links. When
+ * `blockData` is off, a Heading's `kind.data` is instead the bare level `number`
+ * (byte-identical to before), so consumers reading `kind.data` must accept the
+ * `number | HeadingData` union.
+ *
+ * v1: duplicate heading texts produce identical slugs (no document-wide dedup
+ * counter yet) — give same-named headings distinct text if unique anchors matter.
+ */
+export interface HeadingData {
+    level: number;
+    text: string;
+    id: string;
+}
+/**
+ * A CodeBlock's `kind.data` when {@link ParserConfig.blockData} is on. `lang` is
+ * the always-on info-string language (`null` for none); `code` is the opt-in
+ * DECODED source inside `<pre><code>…</code></pre>` (only present when `blockData`
+ * is on). Build a copy-to-clipboard string / re-highlight from `code` alone — no
+ * HTML re-parse, no entity-decode. When `blockData` is off, `code` is absent and
+ * `kind.data` is just `{ lang }`, byte-identical to before.
+ */
+export interface CodeBlockData {
+    lang: string | null;
+    code?: string;
+}
+/**
+ * A MathBlock's `kind.data` when {@link ParserConfig.blockData} is on. `latex` is
+ * the DECODED LaTeX source (the display-math body, entity-decoded). Re-render with
+ * KaTeX from `latex` alone — no HTML re-parse. When `blockData` is off, a
+ * MathBlock has no `kind.data` at all (byte-identical to before).
+ */
+export interface MathBlockData {
+    latex: string;
+}
+/**
+ * One list item in {@link ListData.items}. `html` is the inline-rendered inner
+ * HTML of the item's `<li>` (byte-identical to the content between the matching
+ * `<li…>`/`</li>` in `block.html`), so a keyed renderer can stamp one node per
+ * item and reuse the unchanged items while the list streams.
+ */
+export interface ListItemData {
+    html: string;
+}
+/**
+ * A List's `kind.data` when {@link ParserConfig.blockData} is on. `ordered` is the
+ * always-on flag; `start` is the opt-in ordered-list start number (the `start="N"`
+ * HTML attribute; `1` for an unordered list), only present when `blockData` is on.
+ * `items` carries each item's inner `<li>` HTML — present (and non-empty) only when
+ * `blockData` is on — so a keyed renderer can re-render only the items that changed
+ * since the last patch instead of the whole list's HTML. Renumber / continue a
+ * split list from `start` alone — no HTML re-parse. When `blockData` is off, `start`
+ * and `items` are absent and `kind.data` is just `{ ordered }`, byte-identical.
+ */
+export interface ListData {
+    ordered: boolean;
+    start?: number;
+    items?: ListItemData[];
+}
+/**
+ * One inner sub-block of a `Blockquote` / `Alert` as STRUCTURED DATA (opt-in via
+ * {@link ParserConfig.blockData}). `html` is that sub-block's pre-rendered display
+ * markup (e.g. `<p>…</p>`), byte-for-byte the matching fragment inside the
+ * container's `block.html` wrapper.
+ */
+export interface NestedBlock {
+    html: string;
+}
+/**
+ * A `Blockquote`'s `kind.data` (and the `nested` carrier inside an `Alert`'s data)
+ * when {@link ParserConfig.blockData} is on. `nested` is the ordered list of the
+ * container's inner sub-blocks, each as its own pre-rendered HTML. A
+ * `components.Blockquote` / `components.Alert` override can render these KEYED (one
+ * node per entry) so that while the container streams only its last (open) inner
+ * block re-renders each tick — committed inner blocks have stable HTML and memoize.
+ * When `blockData` is off, a Blockquote has no `kind.data` and an Alert's is just
+ * `{ kind }` (byte-identical to before).
+ */
+export interface ContainerData {
+    nested: NestedBlock[];
+}
+export interface Block {
+    id: number;
+    kind: BlockKind;
+    start: number;
+    end: number;
+    html: string;
+    open: boolean;
+    speculative: boolean;
+}
+export interface Patch {
+    newly_committed: Block[];
+    active: Block[];
+}
+/**
+ * Per-block render-churn sample passed to an {@link RenderMetricsHook}. Lets you
+ * measure how often each block actually re-renders / rebuilds (committed blocks
+ * memo-skip, so they fire exactly once; the streaming tail fires per patch).
+ */
+export interface RenderMetrics {
+    /** How many times THIS block has actually rendered/rebuilt so far (≥ 1). */
+    renderCount: number;
+    /** How many times this block's `speculative` flag flipped between renders. */
+    speculativeToggleCount: number;
+    /** Wall-clock duration of this render's body in ms (0 if `performance` absent). */
+    lastRenderMs: number;
+    /** The block's kind (`"Paragraph"`, `"CodeBlock"`, …). */
+    kind: string;
+}
+/**
+ * Optional observability probe. When supplied to the React renderer (the
+ * `onRenderMetrics` prop) or the DOM renderer ({@link MountOptions.onRenderMetrics}),
+ * it fires once per ACTUAL render/rebuild of a block — never for a committed
+ * block that memo-skips. Zero overhead when absent (no counters advance, the hook
+ * path is never entered).
+ */
+export type RenderMetricsHook = (blockId: number, m: RenderMetrics) => void;
+/** Props passed to a block-kind override (e.g. `components.CodeBlock`). */
+export interface BlockComponentProps {
+    /** The full parsed block, including `kind` (with `kind.data`) and offsets. */
+    block: Block;
+    /**
+     * Rendered, XSS-safe HTML for this block. For `Component` blocks this is the
+     * **inner** rendered-markdown HTML (not the `<tag>…</tag>` wrapper). NOTE: a
+     * `Component` override that ignores both `html` and `children` renders empty —
+     * use {@link children} (the easy path) or `dangerouslySetInnerHTML={{__html:
+     * html}}`.
+     */
+    html: string;
+    /**
+     * React only: this block's inner content already parsed to a React node tree
+     * (markdown rendered, nested tag/inline-component overrides applied). For a
+     * `Component` block it is the inner markdown — render it directly
+     * (`return <Chip {...attrs}>{children}</Chip>`) instead of dangerously setting
+     * `html`. Populated by `<BrookMarkdown>` / `<BrookMarkdownStatic>` when a
+     * `components` map is supplied; DOM and other bindings leave it `undefined`
+     * (they consume `html`). Typed `unknown` to keep this surface framework-neutral
+     * — cast to `ReactNode` in a React override.
+     */
+    children?: unknown;
+    /** True while the block is still streaming (its HTML may still change). */
+    open: boolean;
+    /** True if the block was closed speculatively and may yet be revised. */
+    speculative: boolean;
+    /** Decoded source text — present for `CodeBlock` / `MathBlock`. */
+    text?: string;
+    /** Info-string language — present for `CodeBlock` (from `kind.data.lang`). */
+    language?: string;
+    /** Component tag name — present for `Component` blocks (from `kind.data.tag`). */
+    tag?: string;
+    /**
+     * Sanitized attributes — present for `Component` blocks. The name-form depends
+     * on the consumer: the JSX renderer maps `class`→`className`/`for`→`htmlFor`
+     * so `{...attrs}` spreads cleanly onto an element; the DOM renderer keeps the
+     * literal HTML names (`class`/`for`) because it applies them via
+     * `setAttribute`. For `Component` blocks, `html` is the **inner**
+     * rendered-markdown HTML (not the `<tag>…</tag>` wrapper), so an override can
+     * wrap it itself.
+     */
+    attrs?: Record<string, string>;
+    /**
+     * Structured table data — present for `Table` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). Equivalent to
+     * `block.kind.data`, given a typed, documented name. `{ headers, rows, aligns }`
+     * with each cell carrying `text` (plaintext, for sort/filter/CSV/chart) and
+     * `html` (display). Build a sort/filter/transpose/chart/CSV toolbar from DATA —
+     * no HTML re-parse, no HAST tree.
+     */
+    table?: TableData;
+    /**
+     * Structured heading data — present for `Heading` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ level, text,
+     * id }` with `text` the inline-stripped plaintext and `id` a GitHub-style anchor
+     * slug. Build a table of contents (nested by `level`, anchored by `id`) from
+     * DATA — no HTML re-parse.
+     */
+    heading?: HeadingData;
+    /**
+     * Structured code data — present for `CodeBlock` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ lang, code }`
+     * with `code` the DECODED source. Build a copy-to-clipboard string / re-highlight
+     * from `code` — no HTML re-parse, no entity-decode. (`props.text` / `props.language`
+     * carry the same source / lang and stay populated even when off, via the HTML
+     * regex fallback.)
+     */
+    code?: CodeBlockData;
+    /**
+     * Structured math data — present for `MathBlock` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ latex }` — the
+     * DECODED LaTeX source. Re-render with KaTeX from `latex` — no HTML re-parse.
+     * (`props.text` carries the same source and stays populated even when off, via
+     * the HTML regex fallback.)
+     */
+    math?: MathBlockData;
+    /**
+     * Structured list data — present for `List` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ ordered,
+     * start }` — renumber / continue a split list from `start` (the ordered-list
+     * start number) without re-parsing the `<ol start=…>` attribute.
+     */
+    list?: ListData;
+    /**
+     * Structured container data — present for `Blockquote` / `Alert` blocks when
+     * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ nested }` —
+     * the ordered pre-rendered HTML of each inner sub-block. The default renderers
+     * use this to render the children KEYED (one node per entry) so that while the
+     * container streams, only its open last inner block re-renders each tick.
+     */
+    container?: ContainerData;
+}
+/**
+ * Per-stream parser configuration. Omitted fields use the library defaults
+ * (autolinks + alerts on, raw HTML escaped, footnotes off) — so the default
+ * `new BrookClient()` behaves exactly as before. Config is applied when the
+ * stream's parser is created and is **immutable** for that stream's lifetime
+ * (a `reset()` keeps it; use a new client for different flags).
+ */
+export interface ParserConfig {
+    /** GFM extended autolinks (bare www./http(s)://ftp:// + emails). Default true. */
+    gfmAutolinks?: boolean;
+    /** GitHub alerts (`> [!NOTE]` → callouts). Default true. */
+    gfmAlerts?: boolean;
+    /**
+     * GFM "Disallowed Raw HTML" (tagfilter): with `unsafeHtml` on, 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. Default
+     * false (strict CommonMark passes them through under `unsafeHtml`); no
+     * effect while raw HTML is escaped (default) or sanitized — already inert.
+     */
+    gfmTagfilter?: boolean;
+    /** GFM footnotes (`[^1]` + `[^1]:` → footnote section). Default false. */
+    gfmFootnotes?: boolean;
+    /**
+     * Math: `$…$` / `\(…\)` inline and `$$…$$` / `\[…\]` display. Default false
+     * (so `$` in prose / currency stays literal). Emits KaTeX-ready markup
+     * (`<span class="math math-inline">` / `<div class="math math-display">`)
+     * carrying the LaTeX — bring your own KaTeX pass (brookmd stays zero-dep).
+     */
+    gfmMath?: boolean;
+    /**
+     * Emit `dir="auto"` on block-level text elements (`p`, `h1`–`h6`,
+     * `blockquote`, `ul`/`ol`/`li`, `table`) so the browser detects each block's
+     * direction independently — correct for documents mixing English with
+     * Arabic/Hebrew. Default false; code blocks always stay LTR. Recommended for
+     * apps that render RTL or mixed-direction content.
+     */
+    dirAuto?: boolean;
+    /**
+     * Opt-in accessibility markup that deviates from strict GFM byte-output:
+     * wraps a task-list checkbox + its text in a `<label>` (programmatic
+     * association for screen readers) and adds `scope="col"` to table header
+     * cells. Default false (so CommonMark/GFM conformance output is unchanged).
+     */
+    a11y?: boolean;
+    /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
+    unsafeHtml?: boolean;
+    /**
+     * Opt-in allowlist of custom component tag names (e.g. `["Thinking",
+     * "Callout"]`). A `<Tag>…</Tag>` whose name is listed renders as a component
+     * whose inner content is parsed as **markdown** — safely, without `unsafeHtml`
+     * (the tag is allowlisted and its attributes are sanitized: event handlers
+     * dropped, dangerous URL schemes neutralized). The block is dispatched by the
+     * renderer via `components[tag]` (or `components.Component`). Empty/omitted =
+     * off. Names match case-sensitively.
+     */
+    componentTags?: string[];
+    /**
+     * Opt-in allowlist of INLINE component tag names (e.g. `["tik", "cite"]`). An
+     * allowlisted `<tik>…</tik>` (or self-closing `<tik/>`) anywhere in inline
+     * content — paragraphs, headings, table cells, list items — renders as a real
+     * custom element with **markdown** inner content and sanitized attributes
+     * (event handlers dropped, dangerous URL schemes neutralized) — XSS-safe
+     * without `unsafeHtml`. The React renderer dispatches it via `components[tag]`,
+     * with the inner markdown as the component's `children` and the sanitized
+     * attributes as props. Separate from `componentTags` (block containers): list a
+     * tag here for inline chips (tickers, citations, @mentions), or in both lists
+     * to allow both positions. Names match **case-sensitively** and dispatch
+     * verbatim to `components[tag]` (e.g. `"Cite"` → `components.Cite`), same as
+     * `componentTags`. Empty/omitted = off.
+     */
+    inlineComponentTags?: string[];
+    /**
+     * Opt-in **safe raw-HTML allowlist**. Setting this (even to `[]`) engages a
+     * sanitizer that renders a safe subset of *inline* raw HTML **without**
+     * `unsafeHtml`: an **empty** array means "allow all tags except a built-in
+     * dangerous set" (`script`, `style`, `iframe`, `object`, `embed`, `form`,
+     * `input`, `svg`, …); a **non-empty** array renders only those tags (e.g.
+     * `["br","sub","sup"]`) and escapes the rest. Every rendered tag's attributes
+     * are sanitized (event handlers dropped, dangerous URL schemes → `#`), and HTML
+     * comments are dropped. Block-level raw HTML stays escaped (sanitize is
+     * inline-scoped for now). Unset/omitted = off (raw HTML handling unchanged).
+     * Matching is case-insensitive. See also {@link dropHtmlTags}.
+     */
+    htmlAllowlist?: string[];
+    /**
+     * Tags removed entirely (markup dropped; any text between an open/close pair
+     * stays as inert text) — e.g. app marker tags, or belt-and-suspenders
+     * `["script","style"]`. Setting this (even to `[]`) also engages the safe
+     * raw-HTML sanitizer (see {@link htmlAllowlist}). Case-insensitive.
+     */
+    dropHtmlTags?: string[];
+    /**
+     * Opt-in structured table data. When on, a `Table` block's `kind.data` is
+     * populated with `{ headers, rows, aligns }` (each cell `{ text, html }`) so a
+     * consumer can build a sort/filter/transpose/chart/CSV toolbar from DATA — no
+     * HTML re-parse, no HAST tree. Default false (non-users pay zero allocation /
+     * serde bytes; output and the `kind` serde shape stay byte-identical when off).
+     */
+    blockData?: boolean;
+}
+export type ToWorker = {
+    type: "append";
+    streamId: number;
+    chunk: string;
+    config?: ParserConfig;
+    epoch?: number;
+} | {
+    type: "finalize";
+    streamId: number;
+    config?: ParserConfig;
+    epoch?: number;
+} | {
+    type: "reset";
+    streamId: number;
+    epoch?: number;
+} | {
+    type: "dispose";
+    streamId: number;
+};
+export type FromWorker = {
+    type: "ready";
+} | {
+    type: "patch";
+    streamId: number;
+    patch: string;
+    appendedBytes: number;
+    parseMicros: number;
+    retainedBytes: number;
+    wasmMemoryBytes: number;
+    final?: boolean;
+    epoch?: number;
+} | {
+    type: "error";
+    streamId: number;
+    message: string;
+    fatal?: boolean;
+};
+/**
+ * Minimal structural interface satisfied by the DOM `Worker`. Injectable so the
+ * pool's routing/lifecycle logic can be unit-tested with a fake worker — no
+ * real Worker or WASM required.
+ */
+export interface WorkerLike {
+    postMessage(msg: ToWorker): void;
+    addEventListener(type: "message", listener: (ev: {
+        data: FromWorker;
+    }) => void): void;
+    terminate(): void;
+}

package/dist/types-react.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType } from "react";
+/**
+ * Override map for {@link BrookMarkdown}. Keys are either lowercase HTML tag
+ * names (`table`, `a`, `code`, `h1`… — react-markdown style, applied inside a
+ * block's HTML) or capitalized block-kind names (`BlockKindTag`, e.g.
+ * `CodeBlock`, `Table` — replace the whole block renderer). Values are a React
+ * component or an HTML tag string.
+ *
+ * Tag-level components receive the element's parsed attributes (with
+ * `class`→`className`, `style` as an object) plus `children`. Block-kind
+ * components receive `BlockComponentProps`. There is no `node` prop.
+ */
+export type Components = Record<string, ComponentType<any> | string>;

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export * from "./types-core.js";
+export * from "./types-react.js";

package/dist/types.js

@@ -0,0 +1,2 @@
+export * from "./types-core.js";
+export * from "./types-react.js";

package/dist/url-safety.d.ts

@@ -0,0 +1,12 @@
+/** Decode the (small, known) set of entities the core emits, plus numeric refs. */
+export declare function decodeEntities(s: string): string;
+/** Replace a dangerous-scheme URL with "#". Mirrors the Rust `is_dangerous_scheme`:
+ *  strip control chars (C0, DEL, C1 — matching Rust char::is_control),
+ *  lowercase, then match. The strip affects only the probe, never output.
+ *
+ *  Exported as the SAFE URL path for user `decorators` / `urlTransform`: their
+ *  output is a TRUSTED surface that does NOT pass through the attribute
+ *  sanitizer, and React/the DOM happily render a `javascript:` href, so a
+ *  decorator that builds a link must route its href through this (see
+ *  `wrapLink`), and `urlTransform` output is re-run through it by the renderer. */
+export declare function safeUrl(value: string): string;

package/dist/url-safety.js

@@ -0,0 +1,45 @@
+const NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  copy: "\xA9",
+  reg: "\xAE",
+  hellip: "\u2026",
+  mdash: "\u2014",
+  ndash: "\u2013"
+};
+function decodeEntities(s) {
+  if (s.indexOf("&") === -1) return s;
+  return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      if (Number.isNaN(code) || code < 0 || code > 1114111) return m;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return m;
+      }
+    }
+    const named = NAMED_ENTITIES[body];
+    return named === void 0 ? m : named;
+  });
+}
+function safeUrl(value) {
+  let decoded = value;
+  for (let i = 0, prev = ""; i < 8 && decoded !== prev; i++) {
+    prev = decoded;
+    decoded = decodeEntities(decoded);
+  }
+  const probe = decoded.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
+  if (probe.startsWith("javascript:") || probe.startsWith("vbscript:") || probe.startsWith("data:text/html") || probe.startsWith("data:text/javascript")) {
+    return "#";
+  }
+  return value;
+}
+export {
+  decodeEntities,
+  safeUrl
+};

package/dist/vue.d.ts

@@ -0,0 +1,94 @@
+import type { DefineComponent, Ref } from "vue";
+import { BrookClient } from "./client.js";
+import type { ParserConfig } from "./types-core.js";
+import { type DomComponents, type MountOptions } from "./dom.js";
+/**
+ * Vue 3 bindings for {@link mountBrookMarkdown}. Thin lifecycle glue: mount the
+ * framework-neutral DOM renderer on `onMounted`, tear it down on `onUnmounted`.
+ *
+ * The renderer owns all subscribe/diffing; this layer never re-implements it
+ * and — per the renderer's contract — never calls `client.destroy()` (the
+ * caller owns the worker/stream). Shipped as plain `.ts` (no SFC compiler in
+ * the pipeline) via `defineComponent` + `h()`.
+ */
+/** Everything `mountBrookMarkdown` accepts, plus the client to subscribe to. */
+export type UseBrookMarkdownOptions = {
+    client: BrookClient;
+} & MountOptions;
+/**
+ * Composable that mounts the renderer into a container ref. Returns
+ * `{ container }` — bind it as the `ref` of the element you want filled.
+ *
+ * `getOpts` must read its fields lazily (e.g. `() => ({ client: props.client,
+ * ... })`) so the watcher sees live prop identities. We watch the five
+ * identities individually — `[client, components, sanitize, virtualize,
+ * stickToBottom]` — rather than a freshly-composed object, which would change
+ * identity every call and remount on every patch. On any of those changing we
+ * destroy and remount; `batch`/`highlightCode` still flow through to the mount
+ * but are intentionally not remount triggers.
+ */
+export declare function useBrookMarkdown(getOpts: () => UseBrookMarkdownOptions): {
+    container: Ref<HTMLElement | null>;
+};
+/**
+ * A fine-grained `Ref` to the streaming **tail** block id — the one block that
+ * may still re-render — driven by Vue's reactivity. Subscribes to the client
+ * once and writes a `shallowRef` only when the tail id changes, so a `computed`
+ * or `watch` keyed off it re-evaluates *only* for the tail, never for the
+ * committed body. Reading it renders nothing: {@link useBrookMarkdown} draws the
+ * document; this mirrors {@link MountHandle.openBlockId} through Vue's primitive
+ * for any extra tail-scoped work the caller schedules. Auto-unsubscribes on the
+ * owning component's unmount.
+ */
+export declare function useTailBlockId(client: BrookClient): Ref<number | null>;
+/** Public props of the {@link BrookMarkdown} Vue component. */
+export interface BrookMarkdownVueProps {
+    client: BrookClient;
+    components?: DomComponents;
+    sanitize?: (html: string) => string;
+    virtualize?: boolean;
+    stickToBottom?: boolean;
+}
+/**
+ * Component wrapper around {@link useBrookMarkdown}. Renders a single `<div>`
+ * whose ref is the mount container.
+ *
+ * The return type is annotated with an explicit, single-type-argument
+ * `DefineComponent<BrookMarkdownVueProps>` instead of letting `tsc` inline
+ * `defineComponent`'s inferred type. The inferred form bakes the *build-time*
+ * Vue version's `DefineComponent` arity into the emitted `.d.ts`, which breaks
+ * consumers on an older Vue within the declared `vue >=3` peer range (TS2707).
+ * A single explicit type arg is portable across all of Vue 3.x.
+ */
+export declare const BrookMarkdown: DefineComponent<BrookMarkdownVueProps>;
+/**
+ * Own a {@link BrookClient} driven by a CONTROLLED full string — the Vue analogue
+ * of React's `useBrookMarkdownString`, for UIs that hold a streaming message as a
+ * single growing string (a `ref`/computed) rather than as a stream. Pass a getter
+ * for the whole document-so-far; on every change {@link BrookClient.setContent}
+ * diffs it and does the minimal work (prefix-extension appends only the delta;
+ * any divergence resets and reparses).
+ *
+ * Pass `streaming: false` (via `getOptions`) once the content is final to
+ * finalize the stream and commit its last block. If `streaming` is omitted or
+ * `true` the stream is left OPEN — inferring "done" from an absent flag is
+ * deliberately avoided (it would re-finalize on every token for callers that
+ * grow the string without the flag — an O(n²) reparse trap). `config` is read
+ * once at construction and is immutable thereafter, so it is not a change
+ * trigger.
+ *
+ * **Returns the owned client** — a deliberate divergence from {@link useBrookMarkdown}
+ * (which returns `{ container }`). Mirroring React's hook, this composes with the
+ * component as `<BrookMarkdown :client="client" />` (and lets you read
+ * `outline()` / `getMetrics()` off it). The client is created in the composable
+ * body (constructor is worker-free → SSR-safe) and destroyed on unmount.
+ *
+ * SSR-safety: `setContent` is what spawns a Worker (via `append`), so it is
+ * called ONLY in `onMounted` and a NON-immediate `watch` — never during the
+ * server render path (`setup` constructs the client but neither lifecycle hook
+ * nor the non-immediate watch fires on the server).
+ */
+export declare function useBrookMarkdownString(getContent: () => string, getOptions?: () => {
+    config?: ParserConfig;
+    streaming?: boolean;
+}): BrookClient;