flux-md 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ 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.13.0 — 2026-06-04
+
+### Added
+
+- **`FluxClient.setContent(content, { done })` + controlled-string helpers for
+  every binding** — a first-class bridge for UIs that hold a streaming message as
+  a single growing/controlled string prop (rather than a stream). setContent diffs
+  against the last value: a **prefix-extension** appends only the delta (committed
+  blocks stay put); any **divergence** (e.g. a finished message swapped for a
+  re-processed final string) resets and reparses. No hand-rolled diff, no
+  readiness gate. Pass `{ done: true }` / `streaming: false` to finalize. The
+  framework-neutral `setContent` is wrapped by an idiomatic, client-owning helper
+  per framework — React `useFluxMarkdownString`, Vue `useFluxMarkdownString`
+  (composable), Solid `createFluxMarkdownString`, Svelte `fluxMarkdownString`
+  (action) — each SSR-safe (feeds only in the client-only lifecycle hook). Vanilla
+  / `<flux-markdown>` use a caller-owned client + `setContent` directly.
+- **`FluxPool.warm()`** — eagerly initialize one worker (`getDefaultPool().warm()`
+  on app load) so the one-time WASM init is off the first-token critical path; the
+  warm worker is the one the first stream attaches to, so the work isn't wasted.
+- **Custom-component & `sanitize` overrides now apply to the OPEN (streaming)
+  block**, not just settled ones — a design-system renderer (Tailwind classes on
+  `p`/`ul`/`li`, inline `<a>`/`<code>` overrides) stays styled mid-stream instead
+  of only after a block commits. This also closes a gap where a supplied
+  `sanitize` previously bypassed component-rendered blocks; it now runs on every
+  block. The no-`components` path is unchanged (byte-identical `innerHTML`).
+
+### Fixed
+
+- **Worker no longer drops the first chunk(s) under a slow WASM load.** The
+  worker buffered appends but did not gate parser creation on WASM readiness, so
+  an append that arrived before `init()` resolved would call `new FluxParser()`
+  against an uninitialized module — throwing `fluxparser_new of undefined` and
+  silently losing that chunk. Appends now accumulate (and `finalize` defers)
+  until init completes, then drain in order. Surfaced on a fresh Next.js /
+  Turbopack production load, where the worker+WASM fetch is slow enough to lose
+  the race; the fix is bundler-agnostic. The worker's message/readiness state
+  machine was extracted to `worker-core.ts` (dependency-injected, like
+  `FluxPool`'s worker factory) and now has a unit test (`worker-core.test.ts`)
+  covering the gate — buffer-until-ready, drain order, finalize/reset before
+  ready — so the regression can't silently return.
+- **React 19 / Next.js type compatibility.** The shipped source used the global
+  `JSX.Element`, which React 19's `@types/react` removed — a consumer's
+  `next build` type-checks flux-md's source (it ships as `.tsx`) and failed with
+  *"Cannot find namespace 'JSX'"*. Now uses `ReactElement`, which type-checks
+  under `@types/react` 18 **and** 19.
+
+### Docs
+
+- **Next.js (App Router) is now documented and verified** (Turbopack + webpack,
+  Next.js 16, `next dev` and `next build`): add flux-md to `transpilePackages`
+  and use it from a `"use client"` component. See the README's Next.js callout.
+
+## 0.12.0 — 2026-05-30
+
+### Added
+
+- **Optional default theme — `import "flux-md/styles.css"`.** A drop-in stylesheet
+  for good-looking output out of the box, **including the built-in syntax
+  highlighter's colors** (without any CSS, `highlight()` output is uncolored).
+  Scoped to `.flux-md`, driven by `--flux-*` CSS variables (re-theme by overriding
+  a few), light by default with automatic dark via `prefers-color-scheme` (force
+  with `class="flux-md flux-dark"` / `flux-light`). Opt-in and zero-runtime — the
+  rendered HTML is unchanged; skip the import to bring your own CSS.
+
 ## 0.11.0 — 2026-05-30
 
 ### Added

package/README.md

@@ -16,9 +16,9 @@ flux-md ships as **source** (TypeScript + the compiled WASM). 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), 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. The framework packages — `react`,
+modules), **Parcel**, and **Next.js** (App Router — Turbopack *and* webpack;
+**verified on Next.js 16**, see the [Next.js callout](#nextjs) below). It is
+**browser-only** (it constructs 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.
@@ -37,6 +37,54 @@ need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
 >
 > No other bundler needs this — it's specific to Vite's optimizer.
 
+<a id="nextjs"></a>
+
+> **Next.js (App Router) — two requirements.** Verified on **Next.js 16** with
+> **Turbopack** (the default for both `next dev` and `next build`). The same two
+> requirements apply under webpack. Because flux-md ships TypeScript source:
+>
+> 1. **Transpile the package.** Next does not compile `node_modules` TypeScript
+>    by default — without this, Turbopack errors with *"Unknown module type"* on
+>    `react.tsx`. Add flux-md to `transpilePackages`:
+>
+>    ```ts
+>    // next.config.ts
+>    import type { NextConfig } from "next";
+>    const nextConfig: NextConfig = { transpilePackages: ["flux-md"] };
+>    export default nextConfig;
+>    ```
+>
+> 2. **Use it from a Client Component.** `<FluxMarkdown>` 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 { FluxMarkdown } from "flux-md/react";
+>
+>    export default function Answer({ stream }: { stream: AsyncIterable<string> }) {
+>      return <FluxMarkdown 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 `useFluxStream` 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
@@ -79,6 +127,38 @@ export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
 }
 ```
 
+### Already holding a growing string? — `useFluxMarkdownString`
+
+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 — `useFluxMarkdownString` diffs it for you and forwards only
+the delta, so you don't hand-roll an append/reset bridge:
+
+```tsx
+import { FluxMarkdown, useFluxMarkdownString } from "flux-md/react";
+
+export function ChatMessage({ text, streaming }: { text: string; streaming: boolean }) {
+  const client = useFluxMarkdownString(text, { streaming });
+  return <FluxMarkdown 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.
+
 <details>
 <summary>Full manual control (caller-owned client)</summary>
 
@@ -150,6 +230,12 @@ 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.
+
 `mountFluxMarkdown(client, container, options?)` returns `{ destroy(), refresh() }`.
 Options: `components`, `sanitize`, `virtualize`, `stickToBottom`, `highlightCode`
 (default true), `batch` (default true — one DOM write per `requestAnimationFrame`).
@@ -208,6 +294,13 @@ defineFluxMarkdown(); // once at bootstrap
 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 — `flux-md/vue`
 
 ```vue
@@ -230,6 +323,20 @@ 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.
 
+**Already holding a growing string?** `useFluxMarkdownString` owns a client and
+diffs the string for you (the Vue analogue of the React hook — see
+[Controlled strings](#already-holding-a-growing-string--usefluxmarkdownstring)):
+
+```vue
+<script setup lang="ts">
+import { FluxMarkdown, useFluxMarkdownString } from "flux-md/vue";
+const props = defineProps<{ text: string; streaming: boolean }>();
+// Pass getters so the composable tracks the live values; it owns + destroys the client.
+const client = useFluxMarkdownString(() => props.text, () => ({ streaming: props.streaming }));
+</script>
+<template><FluxMarkdown :client="client" /></template>
+```
+
 ### Svelte (4 & 5) — `flux-md/svelte`
 
 A Svelte action — works in both v4 and v5, no `.svelte` build step:
@@ -248,6 +355,20 @@ A Svelte action — works in both v4 and v5, no `.svelte` build step:
 <div use:fluxMarkdown={{ client, stickToBottom: true }} />
 ```
 
+**Growing string?** The `fluxMarkdownString` action owns a client and diffs the
+string — `use:fluxMarkdownString={{ content, streaming }}` (it destroys its
+client on `destroy`, so no manual cleanup):
+
+```svelte
+<script lang="ts">
+  import { fluxMarkdownString } from "flux-md/svelte";
+  export let content: string;     // the growing message
+  export let streaming: boolean;  // false once complete → finalizes
+</script>
+
+<div use:fluxMarkdownString={{ content, streaming, stickToBottom: true }} />
+```
+
 ### Solid — `flux-md/solid`
 
 ```tsx
@@ -262,6 +383,19 @@ onCleanup(() => client.destroy());
 <FluxMarkdown client={client} stickToBottom />;
 ```
 
+**Growing string?** `createFluxMarkdownString` 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 { FluxMarkdown, createFluxMarkdownString } from "flux-md/solid";
+
+function Message(props: { text: string; streaming: boolean }) {
+  const client = createFluxMarkdownString(() => props.text, () => ({ streaming: props.streaming }));
+  return <FluxMarkdown 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
@@ -280,6 +414,32 @@ if you hit a transform edge, `mountFluxMarkdown` from `flux-md/dom` inside
 | 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 |
 
+## Styling
+
+flux-md emits semantic HTML under a `.flux-md` root and **ships no CSS by
+default** — bring your own design system, or opt into the bundled theme:
+
+```ts
+import "flux-md/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 `.flux-md`, zero-runtime, and **does not change the rendered
+HTML** — skip the import and nothing is styled.
+
+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="flux-md flux-dark"` or `flux-light`):
+
+```css
+.flux-md {
+  --flux-accent: #7c3aed;   /* links */
+  --flux-bg-code: #faf7ff;  /* code background */
+  --flux-t-kw: #c026d3;     /* syntax: keywords (also --flux-t-str/num/com/fn/ty/…) */
+}
+```
+
 ## Public API
 
 ### `FluxClient`
@@ -298,6 +458,10 @@ class FluxClient {
     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 reset+reparse
+    opts?: { done?: boolean },                      // done:true → finalize
+  ): void;
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser
   whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure
@@ -476,11 +640,15 @@ Rules worth knowing:
   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.
-- **Open (streaming) blocks render via `innerHTML`** — their HTML is still
-  partial, so a tag-level override takes effect the moment the block commits.
+- **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 only runs for closed blocks when you
-  actually supply overrides, and is memoized per `(block id, html)`.
+  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`.
@@ -710,6 +878,16 @@ teardown? Construct your own `new FluxPool(factory, cap)` and pass it to
 **per-page singleton** — don't rely on it in SSR/RSC. For isolation between
 independent feature areas, give each its own `new FluxPool()`.
 
+**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 "flux-md";
+useEffect(() => { getDefaultPool().warm(); }, []); // (or your framework's mount hook)
+```
+
 ### Long documents — `virtualize`
 
 For very long documents (hundreds+ of blocks), pass `virtualize` to apply CSS

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "flux-md",
-  "version": "0.11.0",
+  "version": "0.13.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"],
+  "sideEffects": ["./src/worker.ts", "./src/styles.css"],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -16,7 +16,8 @@
     "./svelte": "./src/svelte.ts",
     "./solid": "./src/solid.tsx",
     "./highlight": "./src/hi.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./styles.css": "./src/styles.css"
   },
   "files": [
     "src",

package/src/client.ts

@@ -151,6 +151,21 @@ export class FluxPool {
     return new Promise((resolve, reject) => pw.readyWaiters.push({ resolve, reject }));
   }
 
+  /**
+   * Eagerly spin up one worker so WASM init starts BEFORE the first stream —
+   * taking the one-time init off the first-token critical path (e.g. call
+   * `getDefaultPool().warm()` on app load / route entry). Reuses a live worker
+   * if one exists; the warm worker is the one the first stream attaches to (it
+   * has spare capacity), so the work is not wasted. Resolves when that worker has
+   * finished initializing WASM; rejects if init fails fatally. Browser-only (it
+   * constructs a `Worker`).
+   */
+  warm(): Promise<void> {
+    const live = this.workers.filter((w) => !w.failed);
+    const pw = live[0] ?? this.create();
+    return this.whenWorkerReady(pw);
+  }
+
   /** Terminate every worker (test teardown / full shutdown). */
   disposeAll(): void {
     for (const pw of this.workers) {
@@ -286,6 +301,11 @@ export class FluxClient {
   private onError?: (err: { message: string; fatal?: boolean }) => void;
   private onBlock?: (block: Block) => void;
   private attached = true;
+  // Diff baseline for setContent(): the full string fed in so far, and whether
+  // it has been finalized. Cleared by reset()/reattach() (the worker drops the
+  // parser there, so the baseline is stale and the document must be re-fed).
+  private lastContent = "";
+  private contentDone = false;
 
   // Perf
   private appendedBytes = 0;
@@ -446,6 +466,53 @@ export class FluxClient {
     }
   }
 
+  /**
+   * Drive the parser from a CONTROLLED full string instead of manual appends.
+   * Pass the whole document-so-far each time; setContent diffs it against the
+   * last value and does the minimal work:
+   *   - **prefix-extension** (the streaming-growth case) → append only the new
+   *     suffix, so committed blocks stay put and only the active tail re-parses;
+   *   - **any other change** (e.g. a finished stream swapped for a re-processed
+   *     final string) → `reset()` + reparse the whole new string.
+   *
+   * This is the first-class bridge for UIs that hold a streaming message as a
+   * single growing string prop (the common React shape) — no hand-rolled diff,
+   * no readiness gate (appends before WASM is ready are buffered). Pass
+   * `{ done: true }` once the content is final to `finalize()` (idempotent within
+   * a generation; a content change *after* done reopens the stream via a fresh
+   * reparse, since a finalized parser is terminal and can't be appended to).
+   * Drive a given client with `setContent` *or* manual `append()`/`finalize()`,
+   * not both — they share the internal diff baseline.
+   *
+   * v1 note: the non-prefix path is a full reparse, not a partial rewind —
+   * committed blocks are frozen, so there is no truncate-to-offset. For the
+   * common case (append-growth + one end-of-stream swap) that is optimal. A
+   * transform that rewrites *earlier* bytes on every update is an anti-pattern
+   * here (it forces a reparse each tick); do that enrichment at render time via
+   * `components` instead, keeping the source append-only.
+   */
+  setContent(content: string, opts?: { done?: boolean }) {
+    if (content !== this.lastContent) {
+      // Fast path appends the delta into the EXISTING parser — but a parser that
+      // was already finalized ({ done: true }) is terminal: the core drops any
+      // further append. So gate the fast path on !contentDone; reopening a
+      // finalized stream (or any divergence) falls through to reset()+reparse,
+      // which frees the dead parser and rebuilds a fresh one.
+      if (!this.contentDone && content.startsWith(this.lastContent)) {
+        this.append(content.slice(this.lastContent.length));
+      } else {
+        this.reset(); // diverged, or reopening a finalized stream — rebuild
+        this.append(content);
+      }
+      this.lastContent = content;
+      this.contentDone = false;
+    }
+    if (opts?.done && !this.contentDone) {
+      this.finalize();
+      this.contentDone = true;
+    }
+  }
+
   reset() {
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
@@ -455,6 +522,8 @@ export class FluxClient {
     this.firstAppendMs = 0;
     this.retainedBytes = 0;
     this.wasmMemoryBytes = 0;
+    this.lastContent = ""; // setContent baseline: the worker drops the parser here
+    this.contentDone = false;
     // Same streamId + worker — the worker frees and lazily recreates the parser.
     const pw = this.ensureAcquired();
     this.pool.send(pw, { type: "reset", streamId: this.streamId });
@@ -481,6 +550,11 @@ export class FluxClient {
    */
   reattach() {
     if (this.attached) return;
+    // The prior destroy()→dispose dropped this stream's parser, so setContent's
+    // diff baseline is stale — clear it so the next setContent re-feeds the whole
+    // document (StrictMode dev double-mount on the SAME instance).
+    this.lastContent = "";
+    this.contentDone = false;
     if (!this.pw) {
       // Never acquired (e.g. constructed during SSR, first real mount on client).
       // No prior pool slot to re-register; just mark attached. The next

package/src/index.ts

@@ -16,7 +16,7 @@
  *     client.finalize();
  */
 export { FluxClient, FluxPool, getDefaultPool } from "./client";
-export { FluxMarkdown } from "./react";
+export { FluxMarkdown, useFluxStream, useFluxMarkdownString } from "./react";
 export { highlight, supportedLangs } from "./hi";
 export { htmlToReact, parseTrustedHtml } from "./html-to-react";
 export type {

package/src/react.tsx

@@ -7,6 +7,7 @@ import {
   useState,
   useSyncExternalStore,
   type CSSProperties,
+  type ReactElement,
 } from "react";
 import type { Block, BlockComponentProps, Components, HeadingData, TableData } from "./types";
 import { FluxClient } from "./client";
@@ -209,6 +210,52 @@ export function useFluxStream(
   return client;
 }
 
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the bridge for
+ * UIs that hold a streaming message as a single growing string prop (the common
+ * React shape) rather than as a stream. Pass the whole document-so-far on each
+ * render and {@link FluxClient.setContent} diffs it: a prefix-extension appends
+ * only the delta; any divergence (e.g. the finished text swapped for a
+ * re-processed final string) resets and reparses. Returns the owned client —
+ * pass it to `<FluxMarkdown client={…} />` (and read `outline()` etc.).
+ *
+ * Pass `streaming: false` once the content is final to finalize the stream and
+ * commit its last block (only then does a finished code fence highlight + show
+ * its copy button). If `streaming` is omitted or `true` the stream is left OPEN
+ * — right for a still-growing string, but a *complete static* string rendered as
+ * `useFluxMarkdownString(md)` keeps its last block in the streaming state until
+ * you pass `{ streaming: false }`. (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.) The client is
+ * created once and destroyed on unmount; StrictMode's dev double-mount is handled
+ * (reattach re-feeds the document). For a true stream source
+ * (`Response` / `ReadableStream` / SSE generator) use {@link useFluxStream}
+ * instead — it avoids buffering the whole document as a string.
+ */
+export function useFluxMarkdownString(
+  content: string,
+  options?: { config?: ParserConfig; streaming?: boolean },
+): FluxClient {
+  const [client] = useState(() => new FluxClient({ config: options?.config }));
+
+  // Own the client's pool attachment (StrictMode dev double-mount destroys on the
+  // simulated unmount then remounts the SAME instance; reattach re-registers and
+  // clears setContent's diff baseline so the document is re-fed). Destroy on the
+  // real unmount.
+  useEffect(() => {
+    client.reattach();
+    return () => client.destroy();
+  }, [client]);
+
+  // Reconcile the parser to the controlled string. setContent diffs internally,
+  // so this stays correct whether `content` grows by a token or is swapped wholesale.
+  useEffect(() => {
+    client.setContent(content, { done: options?.streaming === false });
+  }, [client, content, options?.streaming]);
+
+  return client;
+}
+
 // Stream mode: own a client via the hook, then render the normal client path.
 function FluxMarkdownFromStream(props: FluxMarkdownProps) {
   const client = useFluxStream(props.stream, {
@@ -336,7 +383,10 @@ function componentInnerHtml(html: string, tag: string): string {
 
 /** Convert a closed block's HTML to a React tree, memoized on html+components. */
 function SafeHtml({ html, components }: { html: string; components: Components }) {
-  return useMemo(() => htmlToReact(html, components), [html, components]) as JSX.Element;
+  // `ReactElement` (not the global `JSX.Element`) so the source type-checks under
+  // both @types/react 18 and 19 — React 19 removed the global `JSX` namespace,
+  // and a consumer's `next build` type-checks this shipped source.
+  return useMemo(() => htmlToReact(html, components), [html, components]) as ReactElement;
 }
 
 // Per-kind off-screen size estimate for `contain-intrinsic-size` — keeps the
@@ -419,12 +469,20 @@ function renderBlockContent({
     (block.open ? " flux-open" : "") +
     (block.speculative ? " flux-speculative" : "");
 
-  // Tag-level overrides only apply to a settled block (open/speculative blocks
-  // have partial HTML we must not feed to the parser).
-  if (components && !block.open && !block.speculative) {
+  // Tag-level / inline overrides apply to OPEN and speculative blocks too, not
+  // just settled ones: the streaming tail's HTML is always well-formed (the
+  // parser speculatively closes it), so a design-system renderer (Tailwind
+  // classes on p/ul/li, inline <a>/<code> overrides) stays styled mid-stream
+  // instead of only after a block commits. A supplied `sanitize` runs FIRST
+  // (same as the innerHTML path below), so overrides compose with sanitization on
+  // every block — closing the gap where a component-rendered block previously
+  // bypassed the user sanitizer. The no-`components` fast path is untouched
+  // (byte-identical innerHTML).
+  if (components) {
+    const safe = sanitize ? sanitize(block.html) : block.html;
     return (
       <div className={className}>
-        <SafeHtml html={block.html} components={components} />
+        <SafeHtml html={safe} components={components} />
       </div>
     );
   }

package/src/solid.tsx

@@ -1,5 +1,6 @@
-import { onCleanup, onMount, type JSX } from "solid-js";
-import type { FluxClient } from "./client";
+import { createEffect, onCleanup, onMount, type JSX } from "solid-js";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { mountFluxMarkdown, type MountHandle, type MountOptions } from "./dom";
 
 /**
@@ -73,3 +74,72 @@ export function FluxMarkdown(props: FluxMarkdownProps): JSX.Element {
   onMount(() => mountSolid(() => props, container, onCleanup));
   return container;
 }
+
+/**
+ * Wire a controlled string to a freshly-constructed {@link FluxClient}, free of
+ * Solid's reactive runtime so it runs (and is tested) under any toolchain. The
+ * registrars are injected: the public {@link createFluxMarkdownString} passes
+ * Solid's real `createEffect` / `onCleanup`; tests pass hand-rolled stand-ins
+ * (mirroring how {@link mountSolid} takes `registerCleanup`).
+ *
+ * Ownership DIFFERS from {@link mountSolid}: this constructs the client and so
+ * `registerCleanup`s `client.destroy()` — it OWNS the worker/stream. `config` is
+ * read ONCE here (the constructor treats it as immutable); `getContent()` and
+ * `streaming` are read INSIDE the effect so the effect tracks them reactively.
+ */
+export function setupFluxMarkdownString(
+  getContent: () => string,
+  getOptions: (() => { config?: ParserConfig; streaming?: boolean }) | undefined,
+  registerEffect: (fn: () => void) => void,
+  registerCleanup: (fn: () => void) => void,
+): FluxClient {
+  // One client per helper instance. Constructor is worker-free → SSR-safe; the
+  // worker is spawned lazily by the first setContent → append, which only runs
+  // inside the effect below. config is read once and is immutable thereafter.
+  const client = new FluxClient({ config: getOptions?.()?.config });
+
+  // Reconcile the parser to the controlled string. setContent diffs internally,
+  // so this is correct whether `content` grows by a token or is swapped wholesale.
+  // `streaming === false` (never `!streaming`) → only an explicit false finalizes;
+  // an absent/true flag leaves the stream open (inferring "done" from an absent
+  // flag would re-finalize on every token — an O(n²) reparse trap).
+  registerEffect(() => {
+    client.setContent(getContent(), { done: getOptions?.()?.streaming === false });
+  });
+
+  // This helper OWNS the client (unlike the client-based bindings above), so it
+  // destroys it on cleanup — freeing its pool slot.
+  registerCleanup(() => client.destroy());
+
+  return client;
+}
+
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the Solid
+ * analogue of React's `useFluxMarkdownString`, for UIs that hold a streaming
+ * message as a single growing string (a signal/memo) rather than as a stream.
+ * Pass an accessor for the whole document-so-far; on every change
+ * {@link FluxClient.setContent} diffs it and does the minimal work (a
+ * 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 (only then does a finished code
+ * fence highlight + show its copy button). If `streaming` is omitted or `true`
+ * the stream is left OPEN. `config` is read once at construction and is
+ * immutable, so it is not a change trigger.
+ *
+ * **Returns the owned client** — pass it to `<FluxMarkdown client={client} />`
+ * (and read `outline()` / `getMetrics()` off it). The client is constructed in
+ * the body (constructor is worker-free → SSR-safe) and destroyed on cleanup.
+ *
+ * SSR-safety: `setContent` is what spawns a Worker (via `append`), so it runs
+ * ONLY inside a `createEffect` — Solid does not run user effects during
+ * `renderToString`, so nothing touches a Worker on the server render path (the
+ * body only constructs the worker-free client).
+ */
+export function createFluxMarkdownString(
+  getContent: () => string,
+  getOptions?: () => { config?: ParserConfig; streaming?: boolean },
+): FluxClient {
+  return setupFluxMarkdownString(getContent, getOptions, createEffect, onCleanup);
+}