flux-md 0.5.5 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,149 @@ Notable changes to flux-md. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.7.0 — 2026-05-29
+
+DX, robustness, and accessibility round — the streaming core (perf, CommonMark
+652/652, GFM) was already comprehensive, so this release sharpens the surface
+around it.
+
+### Added
+
+- **`onError` on `FluxClient`** — `new FluxClient({ onError })` receives worker
+  and parse errors (previously only `console.error`'d). A **WASM-init failure**
+  now also surfaces: `whenReady()` **rejects** instead of hanging forever, and
+  `onError` fires with `{ fatal: true }`.
+- **`a11y` parser option** (`ParserConfig.a11y` / `setA11y` / `<flux-markdown
+  a11y>`) — opt-in accessibility markup that intentionally deviates from strict
+  GFM byte-output: wraps a task-list checkbox + its text in a `<label>` (so the
+  box is programmatically associated for screen readers), and adds
+  `scope="col"` to table header cells. **Off by default** (conformance output
+  unchanged). Streaming output stays byte-identical to one-shot.
+- **`FluxClient.outline()`** — a heading table-of-contents (level / text /
+  stable id) from the current snapshot, in document order; works mid-stream.
+- **`FluxClient.toPlaintext()`** — the rendered document as plain text (tags
+  stripped, entities decoded, blocks blank-line separated) for search indexing
+  / summaries.
+
+### Fixed
+
+- **`<flux-markdown>` `src` race** — rapidly changing `src` (or switching
+  between a `src` URL and inline `markdown`/`textContent`) could interleave two
+  fetch streams into one parser, corrupting the parse tree. The element now
+  supersedes any in-flight fetch (monotonic token + `AbortController`) at a
+  single chokepoint.
+
+### Docs / packaging
+
+- README documents the one-line Vite `optimizeDeps.exclude` requirement.
+- `"sideEffects": ["./src/worker.ts"]` so bundlers can drop unused framework
+  adapters from the export surface.
+- CI now publishes via a tag-triggered workflow with `npm publish --provenance`,
+  and asserts every published tarball ships a non-empty WASM artifact.
+
+## 0.6.0 — 2026-05-28
+
+### Added — flux-md is no longer React-only
+
+The core (`FluxClient` + the WASM worker) was always framework-neutral; only
+the renderer was React-bound. This release adds five new entry points, each
+**thin lifecycle glue** over one new framework-agnostic DOM renderer — none
+re-implements the subscribe/diff loop, and none destroys your client (you own
+the worker/stream).
+
+- **`flux-md/dom`** — the foundation. `mountFluxMarkdown(client, container,
+  options?) → { destroy(), refresh() }` incrementally patches a DOM subtree
+  using the parser's stable block IDs: a committed block's node is never
+  recreated (so one-shot work like syntax highlighting and the copy-button
+  listener runs exactly once), only the streaming tail re-renders. Reuses the
+  in-house highlighter for deferred code, applies your `sanitize` hook to the
+  open/speculative tail, and batches patches per `requestAnimationFrame`.
+  Block-kind overrides via `components` (`(props) => HTMLElement | string`);
+  tag-level overrides remain React-only.
+- **`flux-md/element`** — `defineFluxMarkdown(tag = "flux-markdown")` defines a
+  `<flux-markdown>` custom element. Light DOM (your markdown CSS applies),
+  SSR-safe (no auto-register), and usable three ways: a caller-owned `client`
+  property, a self-owned client driven by `append()`/`finalize()`, or zero-JS
+  via a `src` URL it fetch-streams / inline text / a `markdown` attribute.
+  Config flags map to tri-state attributes (`gfm-math`, `dir-auto`, …). Covers
+  **Angular** with `CUSTOM_ELEMENTS_SCHEMA` — no separate package.
+- **`flux-md/vue`** — a `<FluxMarkdown>` component + `useFluxMarkdown`
+  composable (Vue 3, optional peer dep).
+- **`flux-md/svelte`** — a `fluxMarkdown` action, `use:fluxMarkdown={{ client }}`
+  (Svelte 4 and 5, optional peer dep).
+- **`flux-md/solid`** — a `<FluxMarkdown>` component (Solid, optional peer dep).
+  Newest binding: its mount/teardown glue is tested, but the JSX component shell
+  has only been exercised via a real `vite-plugin-solid` build, not in CI — the
+  `flux-md/dom` mount inside `onMount`/`onCleanup` is the fallback if your Solid
+  toolchain trips on it.
+
+Purely additive — existing `flux-md` / `flux-md/react` / `flux-md/client` users
+are unaffected (the React renderer and core are byte-identical; the only change
+to existing code was a type-only import repoint so the neutral entry points
+typecheck without React). `vue`, `svelte`, and `solid-js` join `react` as
+optional peer dependencies — import only the binding you need. See the new
+"Framework bindings" section in the README. 65 → 85 tests.
+
+## 0.5.6 — 2026-05-28
+
+### Performance
+
+- **`ContainerCache` now handles multi-paragraph inner content.** A blockquote
+  or GitHub alert with blank `>` lines inside (`> [!NOTE]\n> Para one.\n>\n>
+  Para two.\n`) used to drop the cache and fall back to the O(n²) full path
+  the moment the first blank arrived. The cache now closes the current
+  paragraph on a blank `>` and starts a new one, preserving the
+  streaming-O(new bytes) shape across multi-paragraph inner content. Each
+  completed inner paragraph is pre-rendered into a growing
+  `committed_paras_html` string; the single-paragraph fast path (the bench's
+  `big_blockquote` / `big_alert`) is unchanged within noise.
+
+- **`ListCache` now handles loose lists.** A flat list with blank lines
+  between siblings (`- one\n\n- two\n\n- three\n`) is a CommonMark "loose"
+  list — every item body gets wrapped in `<p>…</p>` — and the cache used to
+  bail on the first blank. The cache now flips to loose on the first
+  blank-then-marker sequence, re-renders prior cached items with `<p>`
+  wrappers from stored source spans (one-time O(items)), and continues the
+  streaming-O(new bytes) shape from there. Tight→loose is sticky.
+
+  50 KB loose-list bench, before-fix → after-fix:
+
+  | chunk |  before  |  after  | speedup |
+  |------:|---------:|--------:|--------:|
+  |  16   | 5593 ms  | 21 ms   | ~272×   |
+  | 256   |  355 ms  |  7 ms   | ~49×    |
+
+  Tight `big_list` perf is unchanged within bench noise.
+
+### Added
+
+- **React `CodeBlock` default renderer ships a copy-to-clipboard button.**
+  Closed code blocks now show an icon + "Copy" in their header (the existing
+  "streaming" pill takes that slot until close, so streaming code is never
+  copy-clickable mid-arrival). Click → copies the decoded source via
+  `navigator.clipboard.writeText` → swaps to a checkmark + "Copied" for
+  1.5 s → reverts. Native `<button>` (keyboard-reachable), `aria-label`
+  toggles between "Copy code" and "Copied" with `aria-live="polite"`,
+  guards against `navigator.clipboard` being absent (SSR / insecure context)
+  and rejected `writeText` promises (permission denied) — both leave the
+  button silently usable. No new dependency.
+
+### Documentation
+
+- README quickstart now uses `useState(() => new FluxClient())` + an
+  unmount-only destroy effect instead of `useMemo(() => new FluxClient(),
+  [])` + cleanup-on-stream-change (which destroyed the client when the
+  `stream` prop changed, leaking a freed parser on the next append).
+- New "when to enable each flag" guide for `ParserConfig` with concrete
+  LLM-output triggers (`gfmMath` when `$…$` arrives, `componentTags` for
+  `<Thinking>` blocks, etc.) — so a reader picks flags without reading the
+  full reference further down.
+- `Alert` block-kind override example added to the `components` docs.
+- `sanitize` example mirrors the realistic memoize-at-module-scope pattern
+  from the live demo (a fresh arrow each render busts the per-block memo).
+- New "Performance" section pointing to CHANGELOG / `examples/bench.rs` for
+  numbers (no numbers baked into the README — those rot).
+
 ## 0.5.5 — 2026-05-28
 
 ### Performance

package/README.md

@@ -2,6 +2,8 @@
 
 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 `<flux-markdown>` Web Component, or the vanilla DOM mount** — wire each LLM stream to a `FluxClient`, 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, and heavy renderers (syntax highlighting, math, mermaid) are **deferred until a block closes**. The result is low retained memory and a main thread that stays responsive while streaming. See [the live demo](https://md.hsingh.app/).
 
 ## Install
@@ -16,8 +18,24 @@ import.meta.url)`** pattern, so any bundler with asset-module support resolves
 them: **Vite** (the reference setup), **webpack 5**, **Rollup** (with asset
 modules), and **Parcel**. Next.js (webpack/turbopack) should work but is
 untested — file an issue if it doesn't. It is **browser-only** (it constructs
-Web Workers); it does not run under SSR/RSC. `react` is an optional peer
-dependency — only needed if you import `flux-md/react`.
+Web Workers); it does not run under SSR/RSC. The framework packages — `react`,
+`vue`, `svelte`, `solid-js` — are all **optional** peer dependencies; you only
+need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
+`flux-md/dom`, `flux-md/element`) needs none.
+
+> **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 flux-md from pre-bundling:
+>
+> ```ts
+> // vite.config.ts
+> export default defineConfig({
+>   optimizeDeps: { exclude: ["flux-md"] },
+> });
+> ```
+>
+> No other bundler needs this — it's specific to Vite's optimizer.
 
 ## Quick start
 
@@ -37,11 +55,13 @@ client.finalize();
 In React:
 
 ```tsx
-import { useEffect, useMemo } from "react";
+import { useEffect, useState } from "react";
 import { FluxClient, FluxMarkdown } from "flux-md";
 
 export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
-  const client = useMemo(() => new FluxClient(), []);
+  // One client per component instance. Destroy on unmount, not on stream change.
+  const [client] = useState(() => new FluxClient());
+  useEffect(() => () => client.destroy(), [client]);
 
   useEffect(() => {
     let cancelled = false;
@@ -52,11 +72,8 @@ export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
       }
       if (!cancelled) client.finalize();
     })();
-    return () => {
-      cancelled = true;
-      client.destroy();
-    };
-  }, [stream]);
+    return () => { cancelled = true; };
+  }, [client, stream]);
 
   return <FluxMarkdown client={client} />;
 }
@@ -64,6 +81,166 @@ export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
 
 Multiple concurrent streams just need multiple clients — each runs in its own worker, so they don't share main-thread budget.
 
+## Framework bindings
+
+`FluxClient` 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 `<FluxMarkdown>`,
+documented [below](#fluxmarkdown-react), is the same.)
+
+### Vanilla / any framework — `flux-md/dom`
+
+```ts
+import { FluxClient } from "flux-md/client";
+import { mountFluxMarkdown } from "flux-md/dom";
+
+const client = new FluxClient();
+const handle = mountFluxMarkdown(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();
+```
+
+`mountFluxMarkdown(client, container, options?)` returns `{ destroy(), refresh() }`.
+Options: `components`, `sanitize`, `virtualize`, `stickToBottom`, `highlightCode`
+(default true), `batch` (default true — one DOM write per `requestAnimationFrame`).
+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 `<flux-markdown>` — `flux-md/element`
+
+The universal binding — plain HTML, Angular, or any framework that renders DOM.
+Register once, then use the element:
+
+```ts
+import { defineFluxMarkdown } from "flux-md/element";
+defineFluxMarkdown(); // defines <flux-markdown>; pass a custom tag name if you like
+```
+
+```html
+<!-- zero-JS streaming straight from a URL -->
+<flux-markdown src="/api/post.md" gfm-math stick-to-bottom></flux-markdown>
+
+<!-- one-shot from inline text -->
+<flux-markdown># Hello **world**</flux-markdown>
+```
+
+```js
+// or caller-owned streaming — drive your own client:
+const el = document.querySelector("flux-markdown");
+el.client = myFluxClient;             // element subscribes; never destroys it
+el.components = { Thinking: (p) => myNode(p) };
+myFluxClient.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 `defineFluxMarkdown` 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.
+
+**Angular** consumes the same element — no separate package:
+
+```ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+import { defineFluxMarkdown } from "flux-md/element";
+defineFluxMarkdown(); // once at bootstrap
+
+@Component({
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<flux-markdown [attr.src]="url" stick-to-bottom></flux-markdown>`,
+})
+export class Answer { url = "/api/post.md"; }
+```
+
+### Vue 3 — `flux-md/vue`
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount } from "vue";
+import { FluxClient } from "flux-md/client";
+import { FluxMarkdown } from "flux-md/vue";
+
+const client = new FluxClient();
+// feed client.append(delta) from your stream, then client.finalize()
+onBeforeUnmount(() => client.destroy());
+</script>
+
+<template>
+  <FluxMarkdown :client="client" stick-to-bottom />
+</template>
+```
+
+Props: `client` (required), `components`, `sanitize`, `virtualize`,
+`stickToBottom`. There's also a `useFluxMarkdown` composable returning a
+`container` ref if you'd rather mount into your own element.
+
+### Svelte (4 & 5) — `flux-md/svelte`
+
+A Svelte action — works in both v4 and v5, no `.svelte` build step:
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from "svelte";
+  import { FluxClient } from "flux-md/client";
+  import { fluxMarkdown } from "flux-md/svelte";
+
+  const client = new FluxClient();
+  // feed client.append(delta) then client.finalize()
+  onDestroy(() => client.destroy());
+</script>
+
+<div use:fluxMarkdown={{ client, stickToBottom: true }} />
+```
+
+### Solid — `flux-md/solid`
+
+```tsx
+import { onCleanup } from "solid-js";
+import { FluxClient } from "flux-md/client";
+import { FluxMarkdown } from "flux-md/solid";
+
+const client = new FluxClient();
+// feed client.append(delta) then client.finalize()
+onCleanup(() => client.destroy());
+
+<FluxMarkdown client={client} stickToBottom />;
+```
+
+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, `mountFluxMarkdown` from `flux-md/dom` inside
+`onMount`/`onCleanup` is the zero-surprise fallback.
+
 ## What it does
 
 | Concern | flux-md | conventional main-thread renderer |
@@ -73,7 +250,7 @@ Multiple concurrent streams just need multiple clients — each runs in its own
 | 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 |
 | Heavy renderers (syntax, math, mermaid) | Deferred until block close | Re-run per chunk |
-| XSS sanitization | Allowlist in Rust + URL scheme check | rehype-sanitize on JS thread |
+| XSS sanitization | Allowlist in Rust + URL scheme check | Downstream sanitizer pass on the JS thread |
 
 ## Public API
 
@@ -81,19 +258,29 @@ Multiple concurrent streams just need multiple clients — each runs in its own
 
 ```ts
 class FluxClient {
-  constructor(options?: { pool?: FluxPool; config?: ParserConfig });
+  constructor(options?: {
+    pool?: FluxPool;
+    config?: ParserConfig;
+    onError?: (err: { message: string; fatal?: boolean }) => void; // worker/parse + WASM-init errors
+  });
   append(chunk: string): void;                      // queue text for parsing
   finalize(): void;                                 // mark stream complete
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser
-  whenReady(): Promise<void>;                       // resolves once WASM loaded
+  whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure
   subscribe(listener: () => void): () => void;      // React-friendly store
   getSnapshot(): Block[];                           // ordered current blocks
+  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, ... };
 }
 ```
 
+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()`.
+
 #### Per-stream config
 
 ```ts
@@ -104,6 +291,7 @@ const client = new FluxClient({
     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)
+    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"], // custom tags with markdown inside (default none)
   },
@@ -114,6 +302,29 @@ Omitted fields use the defaults above, so `new FluxClient()` 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 `\(…\)` /
+  `\[…\]`). flux-md 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.
+- `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 `<FluxMarkdown sanitize={…} />` (DOMPurify or
+  similar — see [Security](#security)).
+- `componentTags: ["Thinking", …]` — when your LLM emits custom tags like
+  `<Thinking>…</Thinking>` and you want their inner content parsed as markdown
+  and dispatched to a React component. Safe without `unsafeHtml` (attributes are
+  sanitized; allowlisted tags only).
+
 **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
@@ -160,15 +371,15 @@ Subscribes to a `FluxClient`, renders each block keyed by its stable parser-assi
 
 #### Custom components / overrides
 
-Pass a `components` map to replace how elements render — the same idea as
-react-markdown's `components` prop, but the keys come in **two namespaces**:
+Pass a `components` map to replace how elements render. Keys come in **two
+namespaces**:
 
 ```tsx
 import { useMemo } from "react";
 import { FluxClient, FluxMarkdown, type Components } from "flux-md";
 
 function Message({ client }: { client: FluxClient }) {
-  // ⚠️ Memoize (or hoist to module scope). A fresh object every render busts
+  // Memoize (or hoist to module scope). A fresh object every render busts
   // FluxMarkdown's block memo, so every block re-parses on every patch.
   const components: Components = useMemo(
     () => ({
@@ -181,6 +392,15 @@ function Message({ client }: { client: FluxClient }) {
       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>
+      ),
     }),
     [],
   );
@@ -313,8 +533,8 @@ styles them, and they're overridable as a block kind via `components.Alert`.
 By design, not yet, or only partially:
 
 - **Raw HTML in markdown** — escaped by default, not passed through. (Security
-  default. A `setUnsafeHtml(true)` opt-in exists but must never be enabled for
-  untrusted input.)
+  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.
@@ -326,13 +546,28 @@ By design, not yet, or only partially:
 - **Syntax highlighting on open code blocks** — deferred until close. This is a
   deliberate perf choice.
 
+## 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/flux-md-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.
+
 ## Security
 
 flux-md is XSS-safe by default — its HTML output is meant to be injected via
 `innerHTML` without a downstream sanitizer:
 
-- **Raw HTML is escaped** (the `unsafe_html` / `setUnsafeHtml(true)` opt-in
-  disables this; **never enable it for untrusted input**).
+- **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` become
   `#`. The check runs on the *decoded* URL and strips characters browsers
@@ -352,12 +587,17 @@ that returns raw HTML), **bring a real sanitizer** and pass it via
 `<FluxMarkdown sanitize={…} />`. flux-md applies it to every block's HTML before
 injection — **including the streaming (open) tail**, which the raw-`innerHTML`
 fast path would otherwise expose. flux-md stays zero-dep; you choose the
-sanitizer:
+sanitizer. The realistic pattern (matches the live demo):
 
 ```tsx
 import DOMPurify from "dompurify";
 
-<FluxMarkdown client={client} sanitize={(html) => DOMPurify.sanitize(html)} />
+// Hoist to module scope (or wrap in useCallback). A fresh arrow each render
+// busts FluxMarkdown's per-block memo and re-runs every block through sanitize.
+const sanitize = (html: string) => DOMPurify.sanitize(html);
+
+// …then in your component:
+<FluxMarkdown client={client} sanitize={sanitize} />
 ```
 
 The built-in code/math renderers operate on already-escaped content and are not

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "flux-md",
-  "version": "0.5.5",
+  "version": "0.7.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
+  "sideEffects": ["./src/worker.ts"],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client.ts",
     "./react": "./src/react.tsx",
+    "./dom": "./src/dom.ts",
+    "./element": "./src/element.ts",
+    "./vue": "./src/vue.ts",
+    "./svelte": "./src/svelte.ts",
+    "./solid": "./src/solid.tsx",
     "./highlight": "./src/hi.ts",
     "./types": "./src/types.ts"
   },
@@ -18,23 +24,33 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "vue": ">=3",
+    "svelte": ">=4",
+    "solid-js": "^1.8.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true }
+    "react": { "optional": true },
+    "vue": { "optional": true },
+    "svelte": { "optional": true },
+    "solid-js": { "optional": true }
   },
   "devDependencies": {
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
+    "happy-dom": "^15.11.6",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "typescript": "^5.6.3"
+    "solid-js": "^1.8.0",
+    "svelte": "^4.2.0",
+    "typescript": "^5.6.3",
+    "vue": "^3.4.0"
   },
   "scripts": {
     "test": "bun test",
     "prepublishOnly": "cd ../.. && bun run build:wasm"
   },
-  "keywords": ["markdown", "streaming", "wasm", "rust", "react", "incremental", "llm", "ai", "math", "katex", "latex", "bidi", "rtl"],
+  "keywords": ["markdown", "streaming", "wasm", "rust", "react", "vue", "svelte", "solid", "web-component", "custom-element", "incremental", "llm", "ai", "math", "katex", "latex", "bidi", "rtl"],
   "license": "MIT",
   "publishConfig": {
     "access": "public"