flux-md 0.8.0 → 0.10.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.10.0 — 2026-05-30
+
+Server-side rendering safety, plus an opt-in structured-data channel so consumers
+build toolbars / tables of contents / charts from **data** instead of re-parsing
+rendered HTML (no hast tree, no rehype).
+
+### Added
+
+- **SSR-safe.** `new FluxClient()` and `renderToString(<FluxMarkdown …/>)` no
+  longer touch a Web Worker during construction or server render — worker
+  creation is deferred to the first `append`/`pipeFrom` (client-side) — so the
+  library imports and server-renders cleanly across React / Vue / Solid / Svelte.
+  A fresh-process SSR cold-import check guards it in CI.
+- **Structured block data — `blockData: true`** (per-stream config; opt-in,
+  default off — output and CommonMark/GFM conformance are **byte-identical** when
+  off). When on, `block.kind.data` carries typed structured data per kind, also
+  surfaced as typed `BlockComponentProps` fields, and it **streams** in lock-step
+  with the HTML:
+  - **Table** → `{ headers, rows, aligns }`, cells `{ text, html }` (`props.table`)
+    — sort / filter / transpose / CSV / chart.
+  - **Heading** → `{ level, text, id }` (`props.heading`) — TOC with anchors.
+  - **CodeBlock** → `{ lang, code }` (`props.code`) — decoded source.
+  - **MathBlock** → `{ latex }` (`props.math`) — LaTeX source.
+  - **List** → `{ ordered, start }` (`props.list`).
+
+### Fixed
+
+- Packaging: the published tarball ships the WASM deterministically on every npm
+  version (build removes wasm-pack's nested `.gitignore`), with a tarball tripwire
+  in CI and the publish workflow.
+
+## 0.9.0 — 2026-05-29
+
+Kills the React streaming boilerplate. The common case — render an LLM stream —
+goes from ~17 lines of hand-rolled lifecycle to one:
+
+```tsx
+<FluxMarkdown stream={stream} />
+```
+
+### Added
+
+- **`stream` prop on React `<FluxMarkdown>`** — pass an `AsyncIterable<string>`
+  (SSE deltas), a `Response`, or a `ReadableStream<Uint8Array>` and the
+  component owns an internal client, pipes the stream, supersedes it on change,
+  and destroys it on unmount. The `client` prop is unchanged (now optional);
+  passing a `client` keeps the existing caller-owned behavior.
+- **`useFluxStream(stream, options?)` hook (React)** — same lifecycle, returns
+  the owned `FluxClient` (so you can read `outline()` / `getMetrics()` or pass it
+  to `<FluxMarkdown client={…} />`).
+- **`pipeFrom` now also accepts an `AsyncIterable<string>`** and an optional
+  `{ signal }` — the signal is checked every iteration, so an aborted stream
+  appends no further chunks and is **not** finalized (and a byte reader is
+  `cancel()`'d). Existing `pipeFrom(Response | ReadableStream)` calls are
+  unchanged.
+
+### Notes
+
+- A stream is single-use, so React StrictMode's dev-only double-mount may
+  truncate it in development; production mounts once and is unaffected (the
+  prior manual `useEffect` form had the same caveat).
+- Rules of Hooks are respected — `<FluxMarkdown>` dispatches to one of two
+  sibling components, never a conditional hook.
+
 ## 0.8.0 — 2026-05-29
 
 A self-review of 0.7.0 (adversarial multi-agent pass) fixed two robustness gaps

package/README.md

@@ -52,33 +52,61 @@ for await (const delta of streamFromAi()) {
 client.finalize();
 ```
 
-In React:
+In React — pass the stream straight to `<FluxMarkdown>`. It owns the client,
+pipes the stream, supersedes it if it changes, and cleans up on unmount:
+
+```tsx
+import { FluxMarkdown } from "flux-md/react";
+
+export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
+  return <FluxMarkdown stream={stream} />;
+}
+```
+
+`stream` accepts an `AsyncIterable<string>` (e.g. SSE deltas), a `Response`, or
+a `ReadableStream<Uint8Array>` — so `<FluxMarkdown stream={await fetch("/api/chat")} />`
+works too.
+
+Need the client handle (for `outline()` / `getMetrics()` / a shared client)? Use
+the `useFluxStream` hook — same lifecycle, returns the owned client:
+
+```tsx
+import { FluxMarkdown, useFluxStream } from "flux-md/react";
+
+export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
+  const client = useFluxStream(stream);
+  return <FluxMarkdown client={client} />;
+}
+```
+
+<details>
+<summary>Full manual control (caller-owned client)</summary>
+
+When you want to drive the stream yourself, pass a `client` you own — the
+component never destroys it:
 
 ```tsx
 import { useEffect, useState } from "react";
 import { FluxClient, FluxMarkdown } from "flux-md";
 
 export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
-  // 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;
-    (async () => {
-      for await (const chunk of stream) {
-        if (cancelled) return; // stream changed / unmounted mid-flight
-        client.append(chunk);
-      }
-      if (!cancelled) client.finalize();
-    })();
-    return () => { cancelled = true; };
+    const ac = new AbortController();
+    client.pipeFrom(stream, { signal: ac.signal }); // pipeFrom also accepts AsyncIterable
+    return () => ac.abort();
   }, [client, stream]);
-
   return <FluxMarkdown client={client} />;
 }
 ```
 
+</details>
+
+> **StrictMode note:** a stream (SSE generator / `Response`) can be consumed only
+> once, so React StrictMode's dev-only double-mount may truncate it in
+> development. Production mounts once and is unaffected.
+
 Multiple concurrent streams just need multiple clients — each runs in its own worker, so they don't share main-thread budget.
 
 ## Framework bindings
@@ -265,7 +293,10 @@ class FluxClient {
     onBlock?: (block: Block) => void;                 // fires once per block as it commits
   });
   append(chunk: string): void;                      // queue text for parsing
-  pipeFrom(src: ReadableStream<Uint8Array> | Response): Promise<void>; // read → append → finalize
+  pipeFrom(                                         // read → append → finalize
+    src: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
+    opts?: { signal?: AbortSignal },                // abort to supersede (no finalize)
+  ): Promise<void>;
   finalize(): void;                                 // mark stream complete
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser
@@ -305,6 +336,7 @@ const client = new FluxClient({
     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)
+    blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
   },
 });
 ```
@@ -432,8 +464,11 @@ type is at `block.kind.data.kind`).
 
 Rules worth knowing:
 
-- **There is no `node` prop.** flux-md has no hast tree; introspect via
-  `className` / `data-*` instead.
+- **There is no `node` prop / no hast tree.** Introspect via `className` /
+  `data-*`, or — better — opt into the typed **[structured-data
+  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.
 - **No `components` prop ⇒ the original fast path** (`innerHTML`, byte-identical
@@ -443,6 +478,35 @@ Rules worth knowing:
   (so your override wins) when you pass `components.CodeBlock`, `components.pre`,
   or `components.code`.
 
+### Structured block data (`setBlockData`)
+
+Set `blockData: true` in the per-stream config and each block carries typed
+structured data on `block.kind.data`, also surfaced as typed fields on the
+component props — so you build toolbars, tables of contents, charts, copy
+buttons, etc. from **data**, never by re-parsing the rendered HTML (no hast tree,
+no rehype). Off by default; when off, output and CommonMark/GFM conformance are
+byte-identical, so non-users pay nothing.
+
+| Kind | `block.kind.data` | prop | use |
+|------|-------------------|------|-----|
+| `Table` | `{ headers, rows, aligns }`, cells `{ text, html }` | `props.table` | sort / filter / transpose / CSV / chart |
+| `Heading` | `{ level, text, id }` | `props.heading` | table of contents with anchors |
+| `CodeBlock` | `{ lang, code }` | `props.code` | decoded source (copy / run) |
+| `MathBlock` | `{ latex }` | `props.math` | LaTeX source (re-render) |
+| `List` | `{ ordered, start }` | `props.list` | ordered-list numbering |
+
+Each cell's `text` is inline-stripped plaintext (for sort/filter/CSV/logic);
+`html` is the inline-rendered display HTML. The data **streams** with the
+document — a growing table or a heading carries its structured data on every
+patch, in lock-step with the HTML — something a batch HTML-AST cannot do.
+
+```tsx
+// Table of contents from heading data — no DOM, works mid-stream:
+const toc = client.getSnapshot()
+  .filter((b) => b.kind.type === "Heading" && b.kind.data)
+  .map((b) => b.kind.data as { level: number; text: string; id: string });
+```
+
 ### Component tags
 
 LLMs increasingly emit custom component tags like `<Thinking>…</Thinking>`. By

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.8.0",
+  "version": "0.10.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"],
@@ -48,6 +48,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:ssr-cold": "bun test/ssr-cold.mjs",
     "prepublishOnly": "cd ../.. && bun run build:wasm"
   },
   "keywords": ["markdown", "streaming", "wasm", "rust", "react", "vue", "svelte", "solid", "web-component", "custom-element", "incremental", "llm", "ai", "math", "katex", "latex", "bidi", "rtl"],

package/src/block-props.ts

@@ -1,4 +1,12 @@
-import type { Block, BlockComponentProps } from "./types-core";
+import type {
+  Block,
+  BlockComponentProps,
+  CodeBlockData,
+  HeadingData,
+  ListData,
+  MathBlockData,
+  TableData,
+} from "./types-core";
 
 // Pure helpers duplicated from the JSX renderer / its CodeBlock so the
 // framework-neutral DOM renderer carries no framework dependency. The JSX
@@ -78,19 +86,46 @@ export function blockProps(block: Block): BlockComponentProps {
     speculative: block.speculative,
   };
   const data = block.kind.data as
-    | { lang?: string | null; tag?: string; attrs?: [string, string][] }
+    | { lang?: string | null; code?: string; latex?: string; start?: number; ordered?: boolean; tag?: string; attrs?: [string, string][] }
     | undefined;
   if (block.kind.type === "CodeBlock") {
-    props.text = decodeCodeText(block.html);
+    // Prefer the structured `code` (present when blockData is on) over the HTML
+    // regex — it is the lossless decoded source. Fall back to the regex when off.
+    props.text = data?.code ?? decodeCodeText(block.html);
     props.language = data?.lang ?? "";
+    // Surface the typed convenience field only when the opt-in `code` is present.
+    if (typeof data?.code === "string") {
+      props.code = { lang: data.lang ?? null, code: data.code } as CodeBlockData;
+    }
   } else if (block.kind.type === "MathBlock") {
-    props.text = decodeMathText(block.html);
+    // Prefer the structured `latex` (present when blockData is on) over the regex.
+    props.text = data?.latex ?? decodeMathText(block.html);
+    if (typeof data?.latex === "string") {
+      props.math = { latex: data.latex } as MathBlockData;
+    }
+  } else if (block.kind.type === "List") {
+    // Structured list data is present only when blockData is on (the `start` key
+    // rides the opt-in channel); surface it as the typed convenience field.
+    if (data && typeof data.start === "number") {
+      props.list = { ordered: !!data.ordered, start: data.start } as ListData;
+    }
   } else if (block.kind.type === "Component") {
     props.tag = data?.tag ?? "";
     props.attrs = htmlAttrs(data?.attrs ?? []);
     // An override replaces the `<tag>` wrapper, so it gets the *inner* HTML
     // (markdown already rendered) rather than the full wrapped block.
     props.html = componentInnerHtml(block.html, props.tag);
+  } else if (block.kind.type === "Table") {
+    // Structured data is present only when `blockData` is on (else `undefined`).
+    // Pure data — identical for the DOM and JSX renderers, no name-form divergence.
+    props.table = block.kind.data as TableData | undefined;
+  } else if (block.kind.type === "Heading") {
+    // When `blockData` is on, `kind.data` is the `{ level, text, id }` object;
+    // when off it is the bare level `number`. Surface the rich object only — the
+    // `typeof === "object"` guard keeps the off-path naked int out of `heading`.
+    if (typeof block.kind.data === "object" && block.kind.data !== null) {
+      props.heading = block.kind.data as HeadingData;
+    }
   }
   return props;
 }

package/src/client.ts

@@ -128,6 +128,18 @@ export class FluxPool {
     }
   }
 
+  /** Inverse of {@link release}: re-register a stream's handler so it receives
+   *  patches again. For React StrictMode's dev double-mount, which destroys a
+   *  client on the simulated unmount and remounts the SAME instance. The worker
+   *  lazily recreates the disposed parser on the next append. */
+  reattach(streamId: number, pw: PoolWorker, handler: (msg: FromWorker) => void): void {
+    if (!this.handlers.has(streamId)) {
+      pw.streamCount++;
+      pw.streamIds.add(streamId);
+    }
+    this.handlers.set(streamId, handler);
+  }
+
   send(pw: PoolWorker, msg: ToWorker): void {
     pw.worker.postMessage(msg);
   }
@@ -265,14 +277,15 @@ export function getDefaultPool(): FluxPool {
  */
 export class FluxClient {
   private pool: FluxPool;
-  private pw: PoolWorker;
-  private streamId: number;
+  private pw: PoolWorker | null = null;
+  private streamId = 0;
   private config?: ParserConfig;
   private configSent = false;
   private listeners = new Set<() => void>();
   private store: BlockStore = emptyBlockStore();
   private onError?: (err: { message: string; fatal?: boolean }) => void;
   private onBlock?: (block: Block) => void;
+  private attached = true;
 
   // Perf
   private appendedBytes = 0;
@@ -308,17 +321,38 @@ export class FluxClient {
     this.config = options.config;
     this.onError = options.onError;
     this.onBlock = options.onBlock;
+  }
+
+  /**
+   * Lazily reserve this client's stream id and bind it to a pool worker. The
+   * SOLE place that calls pool.acquire() — so the worker is created on the FIRST
+   * worker-bound operation (append/finalize/reset/pipeFrom/whenReady), never at
+   * construct time. This is what makes `new FluxClient()` SSR-safe: nothing here
+   * runs during an SSR render (which only subscribes + reads the snapshot).
+   *
+   * Idempotent: once this.pw is set it returns it immediately and never
+   * re-acquires — this.pw is never nulled (destroy() deliberately keeps it so
+   * StrictMode's destroy()→reattach() on the SAME instance re-registers the same
+   * slot). Note: streamId/worker assignment now follows first-worker-bound-op
+   * order, not construction order — a client constructed first no longer
+   * necessarily owns the lowest streamId. This affects neither the pool cap nor
+   * multiplexing (pick() is unchanged and remains the only path to create()).
+   */
+  private ensureAcquired(): PoolWorker {
+    if (this.pw) return this.pw;
     const { streamId, pw } = this.pool.acquire((msg) => this.onMessage(msg));
     this.streamId = streamId;
     this.pw = pw;
+    return pw;
   }
 
   get ready(): boolean {
-    return this.pw.ready;
+    return this.pw?.ready ?? false;
   }
 
   whenReady(): Promise<void> {
-    return this.pool.whenWorkerReady(this.pw);
+    const pw = this.ensureAcquired();
+    return this.pool.whenWorkerReady(pw);
   }
 
   // The config rides on the first message a stream sends; the worker applies it
@@ -331,24 +365,53 @@ export class FluxClient {
   }
 
   append(chunk: string) {
+    const pw = this.ensureAcquired();
     if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
-    this.pool.send(this.pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig() });
+    this.pool.send(pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig() });
   }
 
   finalize() {
-    this.pool.send(this.pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
+    const pw = this.ensureAcquired();
+    this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
   }
 
   /**
-   * Pipe a byte stream straight in: read it to completion, `append()` each
-   * decoded chunk, then `finalize()`. The LLM-native path — `await
-   * client.pipeFrom(await fetch("/api/chat"))` (pass a `Response` or its
-   * `ReadableStream` body). `TextDecoder({ stream: true })` carries a multibyte
-   * sequence that straddles a chunk boundary into the next read. Resolves once
-   * finalized; rejects (without finalizing) if the stream errors/aborts — abort
-   * the underlying fetch to cancel. Browser-only (uses `TextDecoder`).
+   * Pipe a source straight in: read it to completion, `append()` each chunk,
+   * then `finalize()`. The LLM-native path — e.g.
+   * `await client.pipeFrom(await fetch("/api/chat"))`. Accepts:
+   *   - a `Response` or its `ReadableStream<Uint8Array>` body (bytes; decoded
+   *     with `TextDecoder({ stream: true })` so a multibyte sequence straddling
+   *     a chunk boundary carries into the next read), or
+   *   - an `AsyncIterable<string>` (e.g. an SSE delta generator) — string chunks
+   *     appended verbatim.
+   *
+   * Pass `opts.signal` to supersede/cancel: the signal is checked on every
+   * iteration, so once aborted no further chunk is appended and **finalize is
+   * skipped** (a superseded stream must not finalize). For a byte source the
+   * reader is also `cancel()`'d to tear down the upstream. Resolves once
+   * finalized (or cleanly on abort); rejects if the source itself errors.
+   * Browser-only for byte sources (uses `TextDecoder`).
    */
-  async pipeFrom(source: ReadableStream<Uint8Array> | Response): Promise<void> {
+  async pipeFrom(
+    source: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
+    opts?: { signal?: AbortSignal },
+  ): Promise<void> {
+    const signal = opts?.signal;
+
+    if (signal?.aborted) return; // already superseded before we started
+
+    // AsyncIterable<string> (SSE deltas, generators). Detected by elimination:
+    // a ReadableStream has `getReader`, a Response has `body` — neither here.
+    if (!("getReader" in source) && !("body" in source)) {
+      for await (const chunk of source as AsyncIterable<string>) {
+        if (signal?.aborted) return; // superseded/unmounted: drop late chunks, no finalize
+        this.append(chunk);
+      }
+      if (!signal?.aborted) this.finalize();
+      return;
+    }
+
+    // Byte source: a Response (use its body) or a ReadableStream directly.
     const body = "body" in source ? source.body : source;
     if (!body) {
       // An empty Response body (e.g. 204) is a completed, empty stream.
@@ -356,17 +419,30 @@ export class FluxClient {
       return;
     }
     const reader = body.getReader();
+    // A pending read() can't observe `aborted` until the next chunk; cancel()
+    // on abort tears down the upstream and resolves the pending read so the
+    // loop's post-read check fires and bails without finalizing.
+    const onAbort = () => {
+      reader.cancel().catch(() => {});
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
     const decoder = new TextDecoder();
     try {
       for (;;) {
         const { done, value } = await reader.read();
+        if (signal?.aborted) return; // superseded: no finalize (cancel already fired)
         if (done) break;
         if (value) this.append(decoder.decode(value, { stream: true }));
       }
       this.append(decoder.decode()); // flush any trailing partial sequence
       this.finalize();
     } finally {
-      reader.releaseLock();
+      signal?.removeEventListener("abort", onAbort);
+      try {
+        reader.releaseLock();
+      } catch {
+        /* already released (e.g. by cancel) */
+      }
     }
   }
 
@@ -380,14 +456,45 @@ export class FluxClient {
     this.retainedBytes = 0;
     this.wasmMemoryBytes = 0;
     // Same streamId + worker — the worker frees and lazily recreates the parser.
-    this.pool.send(this.pw, { type: "reset", streamId: this.streamId });
+    const pw = this.ensureAcquired();
+    this.pool.send(pw, { type: "reset", streamId: this.streamId });
     this.emit();
   }
 
   destroy() {
+    if (!this.attached) return; // idempotent
     // Free this stream's parser; the shared worker stays warm for siblings.
-    this.pool.release(this.streamId, this.pw);
+    // Only release a real slot — a never-acquired client (constructed during an
+    // SSR render then unmounted) has no pool slot to free, so skip the call.
+    // We deliberately do NOT null this.pw here: StrictMode's destroy()→reattach()
+    // on the SAME instance needs the same pw/streamId to re-register.
+    if (this.pw) this.pool.release(this.streamId, this.pw);
     this.listeners.clear();
+    this.attached = false;
+  }
+
+  /**
+   * Re-register with the pool after {@link destroy} so the client receives
+   * patches again. Needed only for React StrictMode's dev double-mount, where
+   * the renderer destroys on the simulated unmount then remounts the SAME
+   * client instance; apps don't normally call this. No-op if still attached.
+   */
+  reattach() {
+    if (this.attached) return;
+    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
+      // worker-bound op acquires lazily. configSent is already false, so the
+      // first append will carry config exactly as a brand-new client would.
+      this.attached = true;
+      return;
+    }
+    this.pool.reattach(this.streamId, this.pw, (msg) => this.onMessage(msg));
+    this.attached = true;
+    // The worker discarded this stream's config on `dispose` (unlike `reset`,
+    // which keeps it), so re-send it on the next message — otherwise the parser
+    // would be rebuilt with library defaults (gfmMath / componentTags / … lost).
+    this.configSent = false;
   }
 
   subscribe = (fn: () => void) => {
@@ -425,7 +532,13 @@ export class FluxClient {
     const out: OutlineEntry[] = [];
     for (const b of this.store.snapshot) {
       if (b.kind.type === "Heading") {
-        out.push({ level: (b.kind.data as number) ?? 1, text: htmlToText(b.html), id: b.id });
+        // `kind.data` is the bare level `number` when `blockData` is off, or the
+        // `{ level, text, id }` object when on — accept both. `OutlineEntry.id`
+        // stays the numeric block id (stable, non-breaking); the anchor slug is
+        // reachable additively via `kind.data.id` for consumers who want it.
+        const d = b.kind.data as number | { level?: number } | undefined;
+        const level = typeof d === "number" ? d : d?.level ?? 1;
+        out.push({ level, text: htmlToText(b.html), id: b.id });
       }
     }
     return out;

package/src/index.ts

@@ -30,4 +30,11 @@ export type {
   ToWorker,
   WorkerLike,
   ParserConfig,
+  Align,
+  TableCell,
+  TableData,
+  HeadingData,
+  CodeBlockData,
+  MathBlockData,
+  ListData,
 } from "./types";

package/src/react.tsx

@@ -1,6 +1,16 @@
-import { createElement, memo, useMemo, useSyncExternalStore, type CSSProperties } from "react";
-import type { Block, BlockComponentProps, Components } from "./types";
-import type { FluxClient } from "./client";
+import {
+  createElement,
+  memo,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+} from "react";
+import type { Block, BlockComponentProps, Components, HeadingData, TableData } from "./types";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { CodeBlock } from "./renderers/CodeBlock";
 import { MathBlock } from "./renderers/Math";
 import { Mermaid } from "./renderers/Mermaid";
@@ -48,7 +58,23 @@ import { htmlToReact } from "./html-to-react";
  */
 
 interface FluxMarkdownProps {
-  client: FluxClient;
+  /**
+   * A caller-owned client (you drive `append`/`finalize` and own its lifecycle —
+   * the component never destroys it). Mutually exclusive with `stream`; if both
+   * are given, `client` wins (a dev warning fires).
+   */
+  client?: FluxClient;
+  /**
+   * A stream to render directly — the 1-line common case. Pass a `Response`, a
+   * `ReadableStream<Uint8Array>`, or an `AsyncIterable<string>` (e.g. SSE
+   * deltas) and the component owns an internal client, pipes the stream, and
+   * destroys it on unmount. A new `stream` identity supersedes the old.
+   */
+  stream?: AsyncIterable<string> | ReadableStream<Uint8Array> | Response;
+  /** Parser config for the internally-created client (stream mode only). */
+  streamConfig?: ParserConfig;
+  /** Called if piping the `stream` rejects (the source errored). Not the worker error channel. */
+  onStreamError?: (err: Error) => void;
   components?: Components;
   /**
    * Skip layout/paint for off-screen blocks via CSS `content-visibility: auto`
@@ -77,7 +103,15 @@ interface FluxMarkdownProps {
   sanitize?: (html: string) => string;
 }
 
-function FluxMarkdownImpl({ client, components, virtualize, stickToBottom, sanitize }: FluxMarkdownProps) {
+// The original render path: subscribe to a (required, caller- or hook-owned)
+// client and render its blocks. NEVER creates or destroys a client.
+function FluxMarkdownFromClient({
+  client,
+  components,
+  virtualize,
+  stickToBottom,
+  sanitize,
+}: FluxMarkdownProps & { client: FluxClient }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   // Normalize "no overrides" to a stable `undefined` so memo comparisons and
   // the fast path don't churn on an empty object identity.
@@ -92,6 +126,88 @@ function FluxMarkdownImpl({ client, components, virtualize, stickToBottom, sanit
   );
 }
 
+/**
+ * Own a {@link FluxClient} for the lifetime of a component and drive it from a
+ * `stream` (a `Response`, `ReadableStream<Uint8Array>`, or
+ * `AsyncIterable<string>`). Returns the client (read `outline()` / `getMetrics()`
+ * off it, or pass it to `<FluxMarkdown client={…} />`). The client is created
+ * once and destroyed on unmount; a new `stream` identity supersedes the old
+ * (the prior pipe is aborted, the parser is reset, the new stream is piped).
+ *
+ * Caveat (matches the manual `useEffect` form): a single-use stream — a
+ * `Response`/`ReadableStream`, or an async generator — can only be consumed
+ * once, so React **StrictMode**'s dev-only double-mount may truncate it in
+ * development. Production mounts once and is unaffected. If you need dev-exact
+ * streaming, drive a caller-owned client manually.
+ */
+export function useFluxStream(
+  stream: AsyncIterable<string> | ReadableStream<Uint8Array> | Response | null | undefined,
+  options?: { config?: ParserConfig; onError?: (err: Error) => void },
+): FluxClient {
+  // One client per hook instance. (React StrictMode double-invokes this
+  // initializer in DEV, constructing a throwaway second client whose worker
+  // slot isn't reclaimed — a minor dev-only artifact; production runs it once.
+  // The committed client is what's used, and its lifecycle below is correct.)
+  const [client] = useState(() => new FluxClient({ config: options?.config }));
+  // Read onError through a ref so its identity never re-subscribes the stream.
+  const onErrorRef = useRef(options?.onError);
+  onErrorRef.current = options?.onError;
+  // Track the last stream so we reset() only on a genuine source change — never
+  // on a StrictMode replay of the same stream (which would discard its head).
+  const prevStream = useRef<typeof stream>(undefined);
+
+  // Own the client's pool attachment. On (re)mount, reattach (StrictMode's
+  // dev double-mount destroys on the simulated unmount, then remounts the SAME
+  // instance — without reattach its patches would be dropped and it'd render
+  // blank); destroy on real unmount.
+  useEffect(() => {
+    client.reattach();
+    return () => client.destroy();
+  }, [client]);
+
+  // Consume the current stream; supersede (abort, no finalize) on change/unmount.
+  useEffect(() => {
+    if (stream == null) return;
+    const ac = new AbortController();
+    if (prevStream.current !== undefined && prevStream.current !== stream) {
+      client.reset(); // a different stream replaced a prior one
+    }
+    prevStream.current = stream;
+    client.pipeFrom(stream, { signal: ac.signal }).catch((e) => {
+      if (!ac.signal.aborted) {
+        onErrorRef.current?.(e instanceof Error ? e : new Error(String(e)));
+      }
+    });
+    return () => ac.abort();
+  }, [stream, client]);
+
+  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, {
+    config: props.streamConfig,
+    onError: props.onStreamError,
+  });
+  return <FluxMarkdownFromClient {...props} client={client} />;
+}
+
+// Dispatch by rendering one of two SIBLING components (never a hook in a branch,
+// which would violate the Rules of Hooks): `stream` mode owns a client, `client`
+// mode uses the caller's. `memo` skips re-render when props are unchanged. If
+// both are given `client` wins (it owns the lifecycle); passing neither is a
+// usage error and throws (rather than crashing cryptically downstream).
+function FluxMarkdownImpl(props: FluxMarkdownProps) {
+  if (props.stream != null && props.client == null) {
+    return <FluxMarkdownFromStream {...props} />;
+  }
+  if (props.client == null) {
+    throw new Error("<FluxMarkdown>: pass either a `client` or a `stream` prop.");
+  }
+  return <FluxMarkdownFromClient {...(props as FluxMarkdownProps & { client: FluxClient })} />;
+}
+
 export const FluxMarkdown = memo(FluxMarkdownImpl);
 
 function decodeEntities(s: string): string {
@@ -128,13 +244,25 @@ function blockKindProps(block: Block): BlockComponentProps {
     speculative: block.speculative,
   };
   const data = block.kind.data as
-    | { lang?: string | null; tag?: string; attrs?: [string, string][] }
+    | { lang?: string | null; code?: string; latex?: string; start?: number; ordered?: boolean; tag?: string; attrs?: [string, string][] }
     | undefined;
   if (block.kind.type === "CodeBlock") {
-    props.text = decodeCodeText(block.html);
+    // Prefer the structured `code` (present when blockData is on) over the HTML
+    // regex — the lossless decoded source. Fall back to the regex when off.
+    props.text = data?.code ?? decodeCodeText(block.html);
     props.language = data?.lang ?? "";
+    if (typeof data?.code === "string") {
+      props.code = { lang: data.lang ?? null, code: data.code };
+    }
   } else if (block.kind.type === "MathBlock") {
-    props.text = decodeMathText(block.html);
+    props.text = data?.latex ?? decodeMathText(block.html);
+    if (typeof data?.latex === "string") {
+      props.math = { latex: data.latex };
+    }
+  } else if (block.kind.type === "List") {
+    if (data && typeof data.start === "number") {
+      props.list = { ordered: !!data.ordered, start: data.start };
+    }
   } else if (block.kind.type === "Component") {
     props.tag = data?.tag ?? "";
     // React-form attribute names, so `{...attrs}` spreads cleanly onto an element
@@ -143,6 +271,17 @@ function blockKindProps(block: Block): BlockComponentProps {
     // An override replaces the `<tag>` wrapper, so it gets the *inner* HTML
     // (markdown already rendered) rather than the full wrapped block.
     props.html = componentInnerHtml(block.html, props.tag);
+  } else if (block.kind.type === "Table") {
+    // Pure structured data (present only when `blockData` is on) — unlike
+    // `attrs` there is no React/DOM name-form divergence, so this is the same
+    // line as block-props.ts's branch.
+    props.table = block.kind.data as TableData | undefined;
+  } else if (block.kind.type === "Heading") {
+    // When `blockData` is on, `kind.data` is `{ level, text, id }`; off, it is the
+    // bare level `number`. Surface the rich object only (mirrors block-props.ts).
+    if (typeof block.kind.data === "object" && block.kind.data !== null) {
+      props.heading = block.kind.data as HeadingData;
+    }
   }
   return props;
 }

package/src/solid.tsx

@@ -59,6 +59,11 @@ export function mountSolid(
  * is equivalent to `<div ref={container} class={props.class} style={props.style} />`.
  */
 export function FluxMarkdown(props: FluxMarkdownProps): JSX.Element {
+  // SSR: this renderer is client-only and imperative (creates/owns its own DOM
+  // node, no hydration expected). Solid runs component bodies on the server, so
+  // guard the document access; the browser path is byte-identical (document is
+  // always defined there). onMount never fires on the server anyway.
+  if (typeof document === "undefined") return undefined as unknown as JSX.Element;
   const container = document.createElement("div");
   if (props.class) container.className = props.class;
   if (typeof props.style === "string") container.setAttribute("style", props.style);

package/src/types-core.ts

@@ -17,6 +17,86 @@ export interface BlockKind {
   data?: unknown;
 }
 
+/** Column alignment from the `|:--|:-:|--:|` delimiter row; `null` = unset. */
+export type Align = "left" | "center" | "right" | null;
+
+/**
+ * One table cell as STRUCTURED DATA (opt-in via {@link ParserConfig.blockData}).
+ * `text` is the inline-stripped plaintext — sort/filter/CSV/chart from DATA,
+ * with no HTML re-parse. `html` is the inline-rendered display markup, byte-for-
+ * byte the inline content inside the matching `<td>`/`<th>` of `block.html`.
+ */
+export interface TableCell {
+  text: string;
+  html: string;
+}
+
+/**
+ * A Table block's `kind.data` when {@link ParserConfig.blockData} is on. Lets a
+ * consumer build a sort/filter/transpose/chart/CSV toolbar from DATA alone —
+ * no HAST tree, no HTML re-parse. `aligns[i]` is column `i`'s alignment.
+ */
+export interface TableData {
+  headers: TableCell[];
+  rows: TableCell[][];
+  aligns: Align[];
+}
+
+/**
+ * A Heading block's `kind.data` when {@link ParserConfig.blockData} is on. Lets a
+ * consumer build a table of contents — nested by `level`, anchored by `id` — from
+ * DATA alone, with no HTML re-parse. `text` is the inline-stripped plaintext (the
+ * heading rendered to plain text, e.g. `## **Bold** & x` → `"Bold & x"`); `id` is
+ * a GitHub-style anchor slug of that text (`"bold-x"`) for `#`-links. When
+ * `blockData` is off, a Heading's `kind.data` is instead the bare level `number`
+ * (byte-identical to before), so consumers reading `kind.data` must accept the
+ * `number | HeadingData` union.
+ *
+ * v1: duplicate heading texts produce identical slugs (no document-wide dedup
+ * counter yet) — give same-named headings distinct text if unique anchors matter.
+ */
+export interface HeadingData {
+  level: number;
+  text: string;
+  id: string;
+}
+
+/**
+ * A CodeBlock's `kind.data` when {@link ParserConfig.blockData} is on. `lang` is
+ * the always-on info-string language (`null` for none); `code` is the opt-in
+ * DECODED source inside `<pre><code>…</code></pre>` (only present when `blockData`
+ * is on). Build a copy-to-clipboard string / re-highlight from `code` alone — no
+ * HTML re-parse, no entity-decode. When `blockData` is off, `code` is absent and
+ * `kind.data` is just `{ lang }`, byte-identical to before.
+ */
+export interface CodeBlockData {
+  lang: string | null;
+  code?: string;
+}
+
+/**
+ * A MathBlock's `kind.data` when {@link ParserConfig.blockData} is on. `latex` is
+ * the DECODED LaTeX source (the display-math body, entity-decoded). Re-render with
+ * KaTeX from `latex` alone — no HTML re-parse. When `blockData` is off, a
+ * MathBlock has no `kind.data` at all (byte-identical to before).
+ */
+export interface MathBlockData {
+  latex: string;
+}
+
+/**
+ * A List's `kind.data` when {@link ParserConfig.blockData} is on. `ordered` is the
+ * always-on flag; `start` is the opt-in ordered-list start number (the `start="N"`
+ * HTML attribute; `1` for an unordered list), only present when `blockData` is on.
+ * Renumber / continue a split list from `start` alone — no HTML re-parse. When
+ * `blockData` is off, `start` is absent and `kind.data` is just `{ ordered }`,
+ * byte-identical to before.
+ */
+export interface ListData {
+  ordered: boolean;
+  start?: number;
+}
+
 export interface Block {
   id: number;
   kind: BlockKind;
@@ -58,6 +138,47 @@ export interface BlockComponentProps {
    * wrap it itself.
    */
   attrs?: Record<string, string>;
+  /**
+   * Structured table data — present for `Table` blocks when
+   * {@link ParserConfig.blockData} is on (otherwise `undefined`). Equivalent to
+   * `block.kind.data`, given a typed, documented name. `{ headers, rows, aligns }`
+   * with each cell carrying `text` (plaintext, for sort/filter/CSV/chart) and
+   * `html` (display). Build a sort/filter/transpose/chart/CSV toolbar from DATA —
+   * no HTML re-parse, no HAST tree.
+   */
+  table?: TableData;
+  /**
+   * Structured heading data — present for `Heading` blocks when
+   * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ level, text,
+   * id }` with `text` the inline-stripped plaintext and `id` a GitHub-style anchor
+   * slug. Build a table of contents (nested by `level`, anchored by `id`) from
+   * DATA — no HTML re-parse.
+   */
+  heading?: HeadingData;
+  /**
+   * Structured code data — present for `CodeBlock` blocks when
+   * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ lang, code }`
+   * with `code` the DECODED source. Build a copy-to-clipboard string / re-highlight
+   * from `code` — no HTML re-parse, no entity-decode. (`props.text` / `props.language`
+   * carry the same source / lang and stay populated even when off, via the HTML
+   * regex fallback.)
+   */
+  code?: CodeBlockData;
+  /**
+   * Structured math data — present for `MathBlock` blocks when
+   * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ latex }` — the
+   * DECODED LaTeX source. Re-render with KaTeX from `latex` — no HTML re-parse.
+   * (`props.text` carries the same source and stays populated even when off, via
+   * the HTML regex fallback.)
+   */
+  math?: MathBlockData;
+  /**
+   * Structured list data — present for `List` blocks when
+   * {@link ParserConfig.blockData} is on (otherwise `undefined`). `{ ordered,
+   * start }` — renumber / continue a split list from `start` (the ordered-list
+   * start number) without re-parsing the `<ol start=…>` attribute.
+   */
+  list?: ListData;
 }
 
 /**
@@ -108,6 +229,14 @@ export interface ParserConfig {
    * off. Names match case-sensitively.
    */
   componentTags?: string[];
+  /**
+   * Opt-in structured table data. When on, a `Table` block's `kind.data` is
+   * populated with `{ headers, rows, aligns }` (each cell `{ text, html }`) so a
+   * consumer can build a sort/filter/transpose/chart/CSV toolbar from DATA — no
+   * HTML re-parse, no HAST tree. Default false (non-users pay zero allocation /
+   * serde bytes; output and the `kind` serde shape stay byte-identical when off).
+   */
+  blockData?: boolean;
 }
 
 // Each message carries a `streamId` so one worker can multiplex many parsers

package/src/wasm/flux_md_core.d.ts

@@ -20,6 +20,14 @@ export class FluxParser {
      * to table header cells. Off by default (conformance output unchanged).
      */
     setA11y(on: boolean): void;
+    /**
+     * Opt-in structured `kind.data` channel for Table blocks: a Table then
+     * carries `{ headers, rows, aligns }` (per-cell `{ text, html }`) so a
+     * consumer can build a sort/filter/transpose/chart/CSV toolbar from DATA
+     * without re-parsing the HTML. Off by default — when off, Table serializes
+     * as `{"type":"Table"}` (no `data` key) and output is byte-identical.
+     */
+    setBlockData(on: boolean): void;
     /**
      * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
      * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner
@@ -74,6 +82,7 @@ export interface InitOutput {
     readonly fluxparser_new: () => number;
     readonly fluxparser_retainedBytes: (a: number) => number;
     readonly fluxparser_setA11y: (a: number, b: number) => void;
+    readonly fluxparser_setBlockData: (a: number, b: number) => void;
     readonly fluxparser_setComponentTags: (a: number, b: number, c: number) => void;
     readonly fluxparser_setDirAuto: (a: number, b: number) => void;
     readonly fluxparser_setGfmAlerts: (a: number, b: number) => void;

package/src/wasm/flux_md_core.js

@@ -82,6 +82,17 @@ export class FluxParser {
     setA11y(on) {
         wasm.fluxparser_setA11y(this.__wbg_ptr, on);
     }
+    /**
+     * Opt-in structured `kind.data` channel for Table blocks: a Table then
+     * carries `{ headers, rows, aligns }` (per-cell `{ text, html }`) so a
+     * consumer can build a sort/filter/transpose/chart/CSV toolbar from DATA
+     * without re-parsing the HTML. Off by default — when off, Table serializes
+     * as `{"type":"Table"}` (no `data` key) and output is byte-identical.
+     * @param {boolean} on
+     */
+    setBlockData(on) {
+        wasm.fluxparser_setBlockData(this.__wbg_ptr, on);
+    }
     /**
      * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
      * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner

package/src/wasm/flux_md_core_bg.wasm.d.ts

@@ -8,6 +8,7 @@ export const fluxparser_finalize: (a: number, b: number) => void;
 export const fluxparser_new: () => number;
 export const fluxparser_retainedBytes: (a: number) => number;
 export const fluxparser_setA11y: (a: number, b: number) => void;
+export const fluxparser_setBlockData: (a: number, b: number) => void;
 export const fluxparser_setComponentTags: (a: number, b: number, c: number) => void;
 export const fluxparser_setDirAuto: (a: number, b: number) => void;
 export const fluxparser_setGfmAlerts: (a: number, b: number) => void;

package/src/wasm/package.json

@@ -2,7 +2,7 @@
   "name": "flux-md-core",
   "type": "module",
   "description": "Incremental, streaming-aware markdown parser with speculative closure",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",

package/src/worker.ts

@@ -55,6 +55,7 @@ function getOrCreate(streamId: number): FluxParser {
     p.setA11y(c?.a11y ?? false);
     p.setUnsafeHtml(c?.unsafeHtml ?? false);
     p.setComponentTags(c?.componentTags ?? []);
+    p.setBlockData(c?.blockData ?? false);
     parsers.set(streamId, p);
   }
   return p;