flux-md 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ 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.11.0 — 2026-05-30
+
+### Added
+
+- **Opt-in live region + root attributes** on `<FluxMarkdown>` and
+  `mountFluxMarkdown`. The root accepts `className` (appended to `flux-md`),
+  `id`, `role`, and `aria-live` / `aria-atomic`. Set `aria-live="polite"` to
+  announce streamed content to screen readers — `polite` coalesces rapid updates
+  and does **not** read every token. Off by default; covers React and the DOM
+  mount (so the Web Component and the Vue/Svelte/Solid adapters too).
+
+### Docs
+
+- A repository root README, a "Structured block data" guide in the package
+  README, and a runnable **Data Studio** demo in the playground — a
+  sort/filter/CSV table and a live table of contents built entirely from
+  `block.data`, mid-stream.
+
+## 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 —

package/README.md

@@ -336,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")
   },
 });
 ```
@@ -411,6 +412,13 @@ Subscribes to a `FluxClient`, renders each block keyed by its stable parser-assi
 <FluxMarkdown client={client} />
 ```
 
+The root element accepts opt-in `className` (appended to `flux-md`), `id`,
+`role`, and `aria-live` / `aria-atomic`. Set `aria-live="polite"` to make the
+output a live region so screen readers announce streamed content as it settles —
+`polite` coalesces rapid updates and does **not** read every token. The same
+options exist on the DOM mount (`mountFluxMarkdown(client, el, { ariaLive: "polite" })`),
+covering the Web Component and the Vue/Svelte/Solid adapters.
+
 #### Custom components / overrides
 
 Pass a `components` map to replace how elements render. Keys come in **two
@@ -463,8 +471,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
@@ -474,6 +485,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.9.0",
+  "version": "0.11.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"],
@@ -30,12 +30,21 @@
     "solid-js": "^1.8.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "vue": { "optional": true },
-    "svelte": { "optional": true },
-    "solid-js": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@types/bun": "^1.3.14",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "happy-dom": "^15.11.6",
@@ -48,6 +57,8 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:ssr-cold": "bun test/ssr-cold.mjs",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "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

@@ -277,8 +277,8 @@ 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>();
@@ -321,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
@@ -344,12 +365,14 @@ 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() });
   }
 
   /**
@@ -433,14 +456,19 @@ 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;
   }
@@ -453,6 +481,14 @@ export class FluxClient {
    */
   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`,
@@ -496,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/dom.ts

@@ -61,6 +61,19 @@ export interface MountOptions {
   highlightCode?: boolean;
   /** Coalesce patches into one DOM write per animation frame. Default true. */
   batch?: boolean;
+  /** Appended to the root's `className` (the `flux-md` class is always present). */
+  className?: string;
+  /** Set on the root element. */
+  id?: string;
+  /** Set on the root element (e.g. `"article"`, `"log"`). */
+  role?: string;
+  /**
+   * Make the root a live region so screen readers announce streamed content.
+   * `"polite"` coalesces rapid updates (does not read every token). Off by default.
+   */
+  ariaLive?: "off" | "polite" | "assertive";
+  /** Live-region atomicity; pair with `ariaLive`. Off by default. */
+  ariaAtomic?: boolean;
 }
 
 // Per-kind off-screen size estimate for `contain-intrinsic-size`. Duplicated
@@ -99,7 +112,11 @@ export function mountFluxMarkdown(
   const batch = options.batch !== false && typeof requestAnimationFrame === "function";
 
   const root = document.createElement("div");
-  root.className = "flux-md";
+  root.className = options.className ? `flux-md ${options.className}` : "flux-md";
+  if (options.id) root.id = options.id;
+  if (options.role) root.setAttribute("role", options.role);
+  if (options.ariaLive) root.setAttribute("aria-live", options.ariaLive);
+  if (options.ariaAtomic !== undefined) root.setAttribute("aria-atomic", String(options.ariaAtomic));
   container.appendChild(root);
 
   // CSS-only stick-to-bottom: a permanent sentinel pinned as the last child.

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

@@ -8,7 +8,7 @@ import {
   useSyncExternalStore,
   type CSSProperties,
 } from "react";
-import type { Block, BlockComponentProps, Components } from "./types";
+import type { Block, BlockComponentProps, Components, HeadingData, TableData } from "./types";
 import { FluxClient } from "./client";
 import type { ParserConfig } from "./types-core";
 import { CodeBlock } from "./renderers/CodeBlock";
@@ -101,6 +101,20 @@ interface FluxMarkdownProps {
    * run through it. When omitted, rendering is byte-identical and zero-cost.
    */
   sanitize?: (html: string) => string;
+  /** Appended to the root's `className` (the `flux-md` class is always present). */
+  className?: string;
+  /** Set on the root element. */
+  id?: string;
+  /** Set on the root element (e.g. `"article"`, `"log"`). */
+  role?: string;
+  /**
+   * Make the root a live region so screen readers announce streamed content.
+   * `"polite"` (recommended) coalesces rapid updates and announces when the
+   * reader is idle — it does **not** read every token. Off by default.
+   */
+  "aria-live"?: "off" | "polite" | "assertive";
+  /** Live-region atomicity; pair with `aria-live`. Off by default. */
+  "aria-atomic"?: boolean;
 }
 
 // The original render path: subscribe to a (required, caller- or hook-owned)
@@ -111,13 +125,24 @@ function FluxMarkdownFromClient({
   virtualize,
   stickToBottom,
   sanitize,
+  className,
+  id,
+  role,
+  "aria-live": ariaLive,
+  "aria-atomic": ariaAtomic,
 }: 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.
   const comps = components && Object.keys(components).length > 0 ? components : undefined;
   return (
-    <div className="flux-md">
+    <div
+      className={className ? `flux-md ${className}` : "flux-md"}
+      id={id}
+      role={role}
+      aria-live={ariaLive}
+      aria-atomic={ariaAtomic}
+    >
       {blocks.map((b) => (
         <BlockView key={b.id} block={b} components={comps} virtualize={virtualize} sanitize={sanitize} />
       ))}
@@ -244,13 +269,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
@@ -259,6 +296,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/renderers/CodeBlock.tsx

@@ -1,5 +1,6 @@
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { highlight } from "../hi";
+import { extractLang } from "../block-props";
 
 /**
  * Deferred-highlighting code block. Open (streaming) blocks render plain;
@@ -19,10 +20,6 @@ function decodeText(html: string): string {
     .replace(/&/g, "&");
 }
 
-function extractLang(html: string): string {
-  const m = html.match(/data-lang="([^"]+)"/);
-  return m ? m[1] : "";
-}
 
 interface Props {
   html: string;

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.9.0",
+  "version": "0.11.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;