flux-md 0.16.2 → 0.18.0

package/dist/svelte.js

@@ -0,0 +1,59 @@
+import { readable } from "svelte/store";
+import { FluxClient } from "./client.js";
+import { mountFluxMarkdown, tailOpenBlockId } from "./dom.js";
+function fluxMarkdown(node, params) {
+  let { client, ...options } = params;
+  let handle = mountFluxMarkdown(client, node, options);
+  return {
+    update(next) {
+      if (next.client === client && next.components === options.components && next.sanitize === options.sanitize && next.virtualize === options.virtualize && next.stickToBottom === options.stickToBottom) {
+        return;
+      }
+      handle.destroy();
+      ({ client, ...options } = next);
+      handle = mountFluxMarkdown(client, node, options);
+    },
+    destroy() {
+      handle.destroy();
+    }
+  };
+}
+function tailBlockId(client) {
+  return readable(tailOpenBlockId(client.getSnapshot()), (set) => {
+    const unsubscribe = client.subscribe(() => set(tailOpenBlockId(client.getSnapshot())));
+    return unsubscribe;
+  });
+}
+function mountOptionsOf(p) {
+  const { content: _c, streaming: _s, config: _cfg, ...rest } = p;
+  void _c;
+  void _s;
+  void _cfg;
+  return rest;
+}
+function fluxMarkdownString(node, params) {
+  let options = mountOptionsOf(params);
+  const client = new FluxClient({ config: params.config });
+  let handle = mountFluxMarkdown(client, node, options);
+  client.setContent(params.content, { done: params.streaming === false });
+  return {
+    update(next) {
+      client.setContent(next.content, { done: next.streaming === false });
+      if (next.components === options.components && next.sanitize === options.sanitize && next.virtualize === options.virtualize && next.stickToBottom === options.stickToBottom) {
+        return;
+      }
+      handle.destroy();
+      options = mountOptionsOf(next);
+      handle = mountFluxMarkdown(client, node, options);
+    },
+    destroy() {
+      handle.destroy();
+      client.destroy();
+    }
+  };
+}
+export {
+  fluxMarkdown,
+  fluxMarkdownString,
+  tailBlockId
+};

package/dist/types-core.d.ts

@@ -0,0 +1,382 @@
+export type BlockKindTag = "Paragraph" | "Heading" | "CodeBlock" | "MathBlock" | "Mermaid" | "List" | "Blockquote" | "Alert" | "Table" | "Rule" | "Html" | "Component";
+export interface BlockKind {
+    type: BlockKindTag;
+    data?: unknown;
+}
+/** 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 `<FluxMarkdown>` / `<FluxMarkdownStatic>` 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 FluxClient()` 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 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 (flux-md 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/{src/types-react.ts → dist/types-react.d.ts}

@@ -1,5 +1,4 @@
 import type { ComponentType } from "react";
-
 /**
  * Override map for {@link FluxMarkdown}. Keys are either lowercase HTML tag
  * names (`table`, `a`, `code`, `h1`… — react-markdown style, applied inside a

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/vue.d.ts

@@ -0,0 +1,94 @@
+import type { DefineComponent, Ref } from "vue";
+import { FluxClient } from "./client.js";
+import type { ParserConfig } from "./types-core.js";
+import { type DomComponents, type MountOptions } from "./dom.js";
+/**
+ * Vue 3 bindings for {@link mountFluxMarkdown}. 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 `mountFluxMarkdown` accepts, plus the client to subscribe to. */
+export type UseFluxMarkdownOptions = {
+    client: FluxClient;
+} & 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 useFluxMarkdown(getOpts: () => UseFluxMarkdownOptions): {
+    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 useFluxMarkdown} 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: FluxClient): Ref<number | null>;
+/** Public props of the {@link FluxMarkdown} Vue component. */
+export interface FluxMarkdownVueProps {
+    client: FluxClient;
+    components?: DomComponents;
+    sanitize?: (html: string) => string;
+    virtualize?: boolean;
+    stickToBottom?: boolean;
+}
+/**
+ * Component wrapper around {@link useFluxMarkdown}. Renders a single `<div>`
+ * whose ref is the mount container.
+ *
+ * The return type is annotated with an explicit, single-type-argument
+ * `DefineComponent<FluxMarkdownVueProps>` 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 FluxMarkdown: DefineComponent<FluxMarkdownVueProps>;
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the Vue analogue
+ * of React's `useFluxMarkdownString`, 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 FluxClient.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 useFluxMarkdown}
+ * (which returns `{ container }`). Mirroring React's hook, this composes with the
+ * component as `<FluxMarkdown :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 useFluxMarkdownString(getContent: () => string, getOptions?: () => {
+    config?: ParserConfig;
+    streaming?: boolean;
+}): FluxClient;

package/dist/vue.js

@@ -0,0 +1,79 @@
+import { defineComponent, h, onMounted, onUnmounted, ref, shallowRef, watch } from "vue";
+import { FluxClient } from "./client.js";
+import {
+  mountFluxMarkdown,
+  tailOpenBlockId
+} from "./dom.js";
+function useFluxMarkdown(getOpts) {
+  const container = ref(null);
+  let handle = null;
+  function mount() {
+    if (!container.value) return;
+    const { client, ...mountOptions } = getOpts();
+    handle = mountFluxMarkdown(client, container.value, mountOptions);
+  }
+  function teardown() {
+    handle?.destroy();
+    handle = null;
+  }
+  onMounted(mount);
+  watch(
+    [
+      () => getOpts().client,
+      () => getOpts().components,
+      () => getOpts().sanitize,
+      () => getOpts().virtualize,
+      () => getOpts().stickToBottom
+    ],
+    () => {
+      teardown();
+      mount();
+    }
+  );
+  onUnmounted(teardown);
+  return { container };
+}
+function useTailBlockId(client) {
+  const tail = shallowRef(tailOpenBlockId(client.getSnapshot()));
+  const unsubscribe = client.subscribe(() => {
+    tail.value = tailOpenBlockId(client.getSnapshot());
+  });
+  onUnmounted(unsubscribe);
+  return tail;
+}
+const FluxMarkdown = defineComponent({
+  name: "FluxMarkdown",
+  props: {
+    client: { type: Object, required: true },
+    components: { type: Object, default: void 0 },
+    sanitize: { type: Function, default: void 0 },
+    virtualize: { type: Boolean, default: void 0 },
+    stickToBottom: { type: Boolean, default: void 0 }
+  },
+  setup(props) {
+    const { container } = useFluxMarkdown(() => ({
+      client: props.client,
+      components: props.components,
+      sanitize: props.sanitize,
+      virtualize: props.virtualize,
+      stickToBottom: props.stickToBottom
+    }));
+    return () => h("div", { ref: container });
+  }
+});
+function useFluxMarkdownString(getContent, getOptions) {
+  const client = new FluxClient({ config: getOptions?.()?.config });
+  const apply = () => {
+    client.setContent(getContent(), { done: getOptions?.()?.streaming === false });
+  };
+  onMounted(apply);
+  watch([getContent, () => getOptions?.()?.streaming], apply);
+  onUnmounted(() => client.destroy());
+  return client;
+}
+export {
+  FluxMarkdown,
+  useFluxMarkdown,
+  useFluxMarkdownString,
+  useTailBlockId
+};

package/{src → dist}/wasm/flux_md_core.d.ts

@@ -6,14 +6,25 @@ export class FluxParser {
     [Symbol.dispose](): void;
     /**
      * All blocks currently parsed (committed + active), in document order — the
-     * whole rendered document as a JS array of `Block`. The one-shot /
-     * server-side render primitive: feed the full markdown via `append`, call
-     * `finalize`, then read `allBlocks()` (no worker, no patch accumulation).
+     * whole rendered document as a **JSON string** of a `Block[]` (parse with
+     * `JSON.parse`). The one-shot / server-side render primitive: feed the full
+     * markdown via `append`, call `finalize`, then read `allBlocks()` (no worker,
+     * no patch accumulation).
      */
-    allBlocks(): any;
-    append(chunk: string): any;
+    allBlocks(): string;
+    /**
+     * Returns the patch as a **JSON string** (parsed with `JSON.parse` on the
+     * main thread), not a live JS object. This is deliberate: serializing once to
+     * a string in Rust avoids serde-wasm-bindgen's per-node boundary calls, and a
+     * string is far cheaper than an object graph to `structuredClone` across the
+     * worker→main `postMessage` (the worker forwards the string verbatim).
+     */
+    append(chunk: string): string;
     bufferLen(): number;
-    finalize(): any;
+    /**
+     * JSON-string patch — see [`FluxParser::append`].
+     */
+    finalize(): string;
     constructor();
     /**
      * Total bytes the parser is retaining: source buffer + all rendered
@@ -120,6 +131,7 @@ export interface InitOutput {
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
 }
 
 export type SyncInitInput = BufferSource | WebAssembly.Module;