flux-md 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,109 @@ 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.14.0 — 2026-06-17
+
+### Added
+
+- **Inline custom component tags (`inlineComponentTags`)** — the headline gap for
+  rich apps. An allowlisted inline tag like `<tik symbol="AAPL">AAPL</tik>` (or
+  self-closing `<tik/>`) **anywhere inline** — paragraphs, headings, list items,
+  and **table cells** — renders as a real custom element with its inner parsed as
+  **inline markdown** and its attributes sanitized (event handlers dropped,
+  dangerous URL schemes → `#`). The React renderer dispatches it to
+  `components[tag]` with the inner markdown as `children` and the attributes as
+  props — **XSS-safe without `unsafeHtml`**. Independent of `componentTags`
+  (block containers): list a tag under either or both. Use lowercase tag names.
+- **`children` on `Component` block overrides** — a `Component` override now also
+  receives the inner content pre-parsed to a React tree (`children`), so you can
+  `return <Chip {...attrs}>{children}</Chip>` instead of
+  `dangerouslySetInnerHTML`-ing `html`. The html-vs-children contract is now loud
+  in the types and docs (an override that renders neither shows empty).
+- **`flux-md/server` — worker-free synchronous SSR / RSC rendering.** The Rust→
+  WASM core is a plain synchronous parser, so finished markdown renders on the
+  server with no worker: `initFlux()` (async, idempotent — reads the co-located
+  `.wasm` in Node, or `initFluxSync(bytes)` on edge), `renderToString(md, {
+  config })` (sync HTML string, zero React dep), `parseToBlocks(md, { config })`,
+  and `<FluxMarkdownStatic content config components />` — a hookless, RSC-safe
+  React component that emits the same `flux-md` tree a client `<FluxMarkdown>`
+  hydrates, with the same overrides (inline/block component tags dispatch on the
+  server too).
+- **`FluxParser.allBlocks()` (WASM)** — returns the whole parsed document as a
+  block array, the one-shot render primitive used by `flux-md/server`.
+
+### Fixed
+
+- **Data-loss: a block component tag used inline swallowed sibling blocks.** With
+  e.g. `componentTags: ["tik"]`, an inline occurrence such as
+  `<tik>AAPL</tik> is up.` on a line with following content opened a block
+  container that consumed the rest of the document (the paragraph and a following
+  table vanished). A block component open tag must now be the **whole line** (only
+  trailing whitespace after `>`); otherwise it's treated as inline and degrades
+  inertly — it never eats surrounding content.
+
+### Changed
+
+- The React HTML→tree converter (`htmlToReact` / `parseTrustedHtml`) now preserves
+  a tag's original **case** for component dispatch (so a capitalized inline tag
+  like `<Cite>` maps to `components.Cite`); HTML semantics (void elements, `input`,
+  close-tag matching) still compare case-insensitively, so standard output is
+  unchanged.
+
+Feature-off output is byte-identical (CommonMark 652 + GFM floors hold); both
+allowlists are empty by default.
+
+## 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

package/README.md

@@ -16,9 +16,12 @@ 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
+The streaming client (`<FluxMarkdown>` / `FluxClient`) is **browser-only** (it
+constructs Web Workers). For **server-side / static rendering of finished
+content** — SSR, React Server Components, build steps — use the worker-free,
+synchronous [`flux-md/server`](#server-side-rendering) entry. The framework packages — `react`,
 `vue`, `svelte`, `solid-js` — are all **optional** peer dependencies; you only
 need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
 `flux-md/dom`, `flux-md/element`) needs none.
@@ -37,6 +40,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 +130,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 +233,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 +297,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 +326,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 +358,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 +386,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
@@ -269,6 +406,55 @@ 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.
 
+## Server-side rendering
+
+`<FluxMarkdown>` / `FluxClient` are browser-only (they spawn a Web Worker), but
+the Rust→WASM core is a plain **synchronous** parser. So `flux-md/server` renders
+**finished** markdown on the server with no worker and no async ceremony — Node
+SSR, React Server Components, or a build step:
+
+```ts
+import { initFlux, renderToString } from "flux-md/server";
+
+await initFlux();                                       // once at startup (loads the WASM)
+const html = renderToString("# Hello\n\n**world**");   // sync HTML string, no worker
+```
+
+For React server rendering (RSC, static generation, or SSR), use
+`<FluxMarkdownStatic>` — a hookless, RSC-safe component that renders finished
+content with the same `components` overrides (inline/block component tags
+dispatch on the server too):
+
+```tsx
+import { initFlux, FluxMarkdownStatic } from "flux-md/server";
+
+await initFlux();
+export default function Doc({ md }: { md: string }) {
+  return (
+    <FluxMarkdownStatic
+      content={md}
+      config={{ inlineComponentTags: ["tik"] }}
+      components={{ tik: ({ symbol }) => <span className="ticker">{symbol}</span> }}
+    />
+  );
+}
+```
+
+- **`initFlux()`** — async, idempotent. In Node it reads the package's `.wasm` off
+  disk (Node's `fetch` can't load `file://`); on the web it fetches the
+  bundler-resolved asset. On edge runtimes pass bytes yourself:
+  `initFluxSync(wasmBytes)`.
+- **`renderToString(md, { config })`** — synchronous HTML string, **zero React
+  dependency**.
+- **`parseToBlocks(md, { config })`** — the block array, for custom rendering.
+- **`<FluxMarkdownStatic content config components />`** — synchronous React tree
+  for **render-once** contexts; render it with your framework's server renderer
+  (`renderToStaticMarkup`, RSC, …). For live streaming, client-side code
+  highlighting, or Mermaid, render `<FluxMarkdown>` on the client instead — it's a
+  separate component. (If you SSR-then-hydrate, use the *same* component on both
+  sides; the dedicated client renderers in `<FluxMarkdown>` don't hydrate
+  `<FluxMarkdownStatic>`'s plainer markup.)
+
 ## What it does
 
 | Concern | flux-md | conventional main-thread renderer |
@@ -294,6 +480,11 @@ 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.
 
+> **Next.js Pages Router:** `flux-md/styles.css` is global CSS, which the Pages
+> Router only allows importing from `pages/_app`. Import it there (App Router and
+> other bundlers can import it from any component). Or skip it and bring your own
+> `.flux-md` styles.
+
 Re-theme by overriding a few CSS variables; it's light by default and switches to
 dark automatically via `prefers-color-scheme` (force a mode with
 `class="flux-md flux-dark"` or `flux-light`):
@@ -324,6 +515,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
@@ -361,7 +556,8 @@ const client = new FluxClient({
     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)
+    componentTags: ["Thinking", "Callout"], // BLOCK custom tags w/ markdown inside (default none)
+    inlineComponentTags: ["tik", "cite"],   // INLINE custom tags (chips/citations) w/ markdown inside (default none)
     blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
   },
 });
@@ -389,10 +585,13 @@ When to enable each flag:
 - `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).
+- `componentTags: ["Thinking", …]` — when your LLM emits **block** custom tags
+  like `<Thinking>…</Thinking>` (on their own line) and you want their inner
+  content parsed as markdown and dispatched to a React component. Safe without
+  `unsafeHtml` (attributes are sanitized; allowlisted tags only).
+- `inlineComponentTags: ["tik", …]` — same idea for **inline** custom elements
+  that sit inside a paragraph, heading, list item, or **table cell** (ticker
+  chips, citations, `@mentions`). See [Inline component tags](#inline-component-tags).
 
 **Footnotes** (`gfmFootnotes`) work in streaming with one honest caveat: a
 `[^1]` reference renders speculatively the moment it's seen (committed blocks
@@ -502,11 +701,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`.
@@ -558,29 +761,70 @@ sanitized (event handlers dropped, dangerous URL schemes → `#`).
 
 Each renders as a `Component` block. Override it in React by tag name (or with
 the generic `Component` fallback). The override receives `tag`, the sanitized
-`attrs`, and `html` — the **inner** (already-rendered markdown) HTML, so you can
-wrap it in your own element:
+`attrs`, the inner content as ready-to-render **`children`** (the easy path), and
+also `html` (the inner already-rendered markdown string, for
+`dangerouslySetInnerHTML`):
 
 ```tsx
 <FluxMarkdown
   client={client}
   components={{
-    Thinking: ({ html }) => (
+    Thinking: ({ children }) => (
       <details className="thinking">
         <summary>Reasoning</summary>
-        <div dangerouslySetInnerHTML={{ __html: html }} />
+        {children}
       </details>
     ),
   }}
 />
 ```
 
-With no override, the component renders as `<thinking …>…</thinking>` HTML. The
-override's `html` is the inner content only; `attrs` keys are React-form
-(`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly. While the
-component is still streaming, `html` is the partial inner content and re-renders
-as more arrives. Tag names match case-sensitively; the feature is off unless
-`componentTags` is set.
+> **`children` vs `html`.** A `Component` override that renders *neither* shows
+> **empty** (a common first-try gotcha). Prefer **`children`** — a parsed React
+> tree with nested overrides applied; reach for `dangerouslySetInnerHTML={{ __html:
+> html }}` only when you need the raw string. `attrs` keys are React-form
+> (`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly. While
+> streaming, both reflect the partial inner content and re-render as more arrives.
+> With no override the block renders as `<thinking …>…</thinking>`. Tag names
+> match case-sensitively; off unless `componentTags` is set.
+
+<a id="inline-component-tags"></a>
+
+#### Inline component tags
+
+`componentTags` handles **block** containers (a `<Thinking>` on its own line). For
+**inline** custom elements — ticker chips, citations, `@mentions`, inline tooltips
+that sit *inside* a paragraph, heading, list item, or **table cell** — use
+`inlineComponentTags`:
+
+```tsx
+const client = new FluxClient({ config: { inlineComponentTags: ["tik"] } });
+
+<FluxMarkdown
+  client={client}
+  components={{
+    tik: ({ symbol, children }) => <span className="ticker">{children ?? symbol}</span>,
+  }}
+/>;
+```
+
+Now `Apple <tik symbol="AAPL">AAPL</tik> rose 2%` (or self-closing
+`<tik symbol="AAPL"/>`) dispatches the inline `<tik>` to `components.tik`: its
+inner is parsed as **inline markdown** (the `children`), its attributes become
+props, and it's **safe without `unsafeHtml`** (attributes sanitized, allowlisted
+tags only). It works everywhere inline content does — **including table cells**.
+Tag names match **case-sensitively** and dispatch verbatim to `components[tag]`
+(`<tik>`→`components.tik`, `<Cite>`→`components.Cite`). The
+two lists are independent: list a tag under `componentTags` for blocks,
+`inlineComponentTags` for inline, or both for both. An allowlisted tag used in an
+unsupported position degrades **inertly** (escaped) — it never consumes
+surrounding content.
+
+> **Link-bridge alternative.** Before `inlineComponentTags`, the way to get an
+> inline custom element was the link bridge: emit `[$AAPL](tik://AAPL)` and
+> override `a` to render a chip when the href scheme matches. It's XSS-safe and
+> renders inline-in-cells too — `inlineComponentTags` simply replaces that
+> workaround with first-class inline elements.
 
 ### Types
 
@@ -736,6 +980,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,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.12.0",
+  "version": "0.14.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", "./src/styles.css"],
@@ -10,6 +10,7 @@
     ".": "./src/index.ts",
     "./client": "./src/client.ts",
     "./react": "./src/react.tsx",
+    "./server": "./src/server.tsx",
     "./dom": "./src/dom.ts",
     "./element": "./src/element.ts",
     "./vue": "./src/vue.ts",

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