flux-md 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.4.0 — 2026-05-27
+
+### Added
+
+- **`componentTags`** — opt-in custom component tags. List tag names (e.g.
+  `componentTags: ['Thinking', 'Callout']`) and a `<Thinking>…</Thinking>` in the
+  stream renders as a component whose **inner content is parsed as markdown** —
+  safely, **without `unsafeHtml`**: the tag is allowlisted and its attributes are
+  sanitized (event handlers dropped, dangerous URL schemes neutralized). The
+  container spans blank lines (unlike a raw HTML block) up to its matching close
+  tag, supports nesting, and ignores a `</Tag>` inside a code fence. Each renders
+  as a `Component` block dispatched on the React side via `components[tag]` (e.g.
+  `components.Thinking`) or the generic `components.Component`, receiving `{ tag,
+  attrs, … }`. Off unless configured; tag names match case-sensitively.
+
+### Performance
+
+- Streaming a long open display-math block (`$$…$$` / `\[…\]`) is now O(n)
+  instead of O(n²). The incremental fence cache that already covered code fences
+  was generalized to math fences: an append only escapes the newly arrived lines
+  instead of re-scanning and re-escaping the whole growing body. Measured on a
+  200 KB `$$…$$` block at 16-byte chunks: **16,271 ms → ~93 ms** (~174×). Output
+  is byte-identical (gated by `tests/math_fence_cache.rs`).
+- A long trailing run of link-reference / footnote definitions now commits
+  incrementally instead of being re-scanned on every append. Previously such a
+  run produced no renderable blocks, so the committed offset never advanced. A
+  document ending in a large reference section streams ~10× faster (235 KB at
+  16-byte chunks: **13,799 ms → ~1,380 ms**). Output is byte-identical (gated by
+  `tests/ref_defs_streaming.rs`).
+
+## 0.3.2 — 2026-05-27
+
+### Documentation
+
+- Rewrote the README to describe flux-md on its own terms and removed all
+  references to and comparisons with other libraries. No code changes — the
+  published API and behavior are identical to 0.3.1.
+- Fixed the React quick-start example: import `useEffect` and guard the async
+  append loop so it can't run after unmount or a stream change.
+
 ## 0.3.1 — 2026-05-27
 
 ### Performance
@@ -34,12 +74,11 @@ Notable changes to flux-md. Format based on
   `<div class="math math-display">`) carrying the LaTeX as text content — bring
   your own KaTeX (flux-md stays zero-dep) or override `components.MathBlock`
   (which receives the LaTeX as `text`). Display fences are blank-line tolerant
-  and stream incrementally. Addresses [Streamdown #522]. Off by default.
+  and stream incrementally. Off by default.
 - **`dirAuto`** — opt-in per-block `dir="auto"` on block-level text elements
   (`p`, `h1`–`h6`, `blockquote`, `ul`/`ol`/`li`, `table`, alerts, footnotes), so
   the browser detects each block's direction (RTL/LTR) independently in
-  mixed-language documents. Code blocks stay LTR. Addresses [Streamdown #509].
-  Off by default.
+  mixed-language documents. Code blocks stay LTR. Off by default.
 
 ### Performance
 
@@ -67,6 +106,3 @@ Notable changes to flux-md. Format based on
 - Initial public release: zero-dep streaming markdown, Rust→WASM core, one Web
   Worker per stream, CommonMark 0.31 (652/652) + GFM (tables, strikethrough,
   task lists, extended autolinks, GitHub alerts, footnotes).
-
-[Streamdown #522]: https://github.com/vercel/streamdown/issues/522
-[Streamdown #509]: https://github.com/vercel/streamdown/issues/509

package/README.md

@@ -2,7 +2,7 @@
 
 Zero-dep streaming markdown for the browser. Rust→WASM core, one Web Worker per stream, incremental parse with speculative closure for mid-stream constructs.
 
-Built because [Streamdown](https://streamdown.ai) crashes the main thread when you run 5 concurrent LLM calls. Same input, this library uses **~8× less peak heap, ~6× less retained memory, and ~2× less main-thread blocking** — measured in-browser with `performance.memory`. See [the live demo](https://md.hsingh.app/) for an A/B comparison.
+Parsing runs entirely **off the main thread** — each stream gets its own pooled Web Worker, so many concurrent LLM responses render without contending for the UI thread. On each token the parser re-parses only the **active tail**, not the whole document, and heavy renderers (syntax highlighting, math, mermaid) are **deferred until a block closes**. The result is low retained memory and a main thread that stays responsive while streaming. See [the live demo](https://md.hsingh.app/).
 
 ## Install
 
@@ -37,18 +37,27 @@ client.finalize();
 In React:
 
 ```tsx
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { FluxClient, FluxMarkdown } from "flux-md";
 
 export function ChatMessage({ stream }: { stream: AsyncIterable<string> }) {
   const client = useMemo(() => new FluxClient(), []);
+
   useEffect(() => {
+    let cancelled = false;
     (async () => {
-      for await (const chunk of stream) client.append(chunk);
-      client.finalize();
+      for await (const chunk of stream) {
+        if (cancelled) return; // stream changed / unmounted mid-flight
+        client.append(chunk);
+      }
+      if (!cancelled) client.finalize();
     })();
-    return () => client.destroy();
+    return () => {
+      cancelled = true;
+      client.destroy();
+    };
   }, [stream]);
+
   return <FluxMarkdown client={client} />;
 }
 ```
@@ -57,7 +66,7 @@ Multiple concurrent streams just need multiple clients — each runs in its own
 
 ## What it does
 
-| Concern | flux-md | typical react-markdown / Streamdown |
+| Concern | flux-md | conventional main-thread renderer |
 |---|---|---|
 | Re-parse on each token | No — only the active tail | Yes, full string |
 | Where parse runs | Web Worker (off main thread) | Main thread |
@@ -96,6 +105,7 @@ const client = new FluxClient({
     gfmMath: true,        // $…$ / \(…\) inline + $$…$$ / \[…\] display math (default false)
     dirAuto: true,        // per-block dir="auto" for RTL/bidi text (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)
   },
 });
 ```
@@ -202,6 +212,48 @@ Rules worth knowing:
   (so your override wins) when you pass `components.CodeBlock`, `components.pre`,
   or `components.code`.
 
+### Component tags
+
+LLMs increasingly emit custom component tags like `<Thinking>…</Thinking>`. By
+default these are inert (escaped, or — with `unsafeHtml` — raw HTML whose body
+is *not* markdown). Opt in by allowlisting the tag names:
+
+```tsx
+const client = new FluxClient({ config: { componentTags: ["Thinking", "Callout"] } });
+```
+
+Now a listed tag is a **markdown container**: its inner content is parsed as
+markdown, it spans blank lines up to its matching close tag (not split like a
+raw HTML block), it nests, and a `</Tag>` inside a code fence stays content. It's
+**safe without `unsafeHtml`** — the tag is allowlisted and its attributes are
+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:
+
+```tsx
+<FluxMarkdown
+  client={client}
+  components={{
+    Thinking: ({ html }) => (
+      <details className="thinking">
+        <summary>Reasoning</summary>
+        <div dangerouslySetInnerHTML={{ __html: html }} />
+      </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.
+
 ### Types
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
   "main": "./src/index.ts",

package/src/hi.ts

@@ -5,8 +5,8 @@
  * languages fall through to plain escaped text. ~6KB minified.
  *
  * Highlighting is per-block, runs once when the block closes. We never
- * highlight an open (streaming) block — that's what gives us the big perf
- * win vs Streamdown's per-chunk Shiki invocation.
+ * highlight an open (streaming) block, which avoids re-highlighting the same
+ * code on every chunk — the main perf win for streaming code.
  */
 
 const KEYWORDS_JS = new Set(

package/src/react.tsx

@@ -117,16 +117,49 @@ function blockKindProps(block: Block): BlockComponentProps {
     open: block.open,
     speculative: block.speculative,
   };
-  const data = block.kind.data as { lang?: string | null } | undefined;
+  const data = block.kind.data as
+    | { lang?: string | null; tag?: string; attrs?: [string, string][] }
+    | undefined;
   if (block.kind.type === "CodeBlock") {
     props.text = decodeCodeText(block.html);
     props.language = data?.lang ?? "";
   } else if (block.kind.type === "MathBlock") {
     props.text = decodeMathText(block.html);
+  } else if (block.kind.type === "Component") {
+    props.tag = data?.tag ?? "";
+    // React-form attribute names, so `{...attrs}` spreads cleanly onto an element
+    // (HTML `class`/`for` → React `className`/`htmlFor`).
+    props.attrs = reactAttrs(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);
   }
   return props;
 }
 
+const REACT_ATTR_NAME: Record<string, string> = { class: "className", for: "htmlFor" };
+
+/** Convert sanitized HTML attribute pairs into a React-spreadable object,
+ *  renaming the two names React requires (`class`→`className`, `for`→`htmlFor`).
+ *  Other names (including `data-*` / `aria-*`) pass through unchanged. */
+function reactAttrs(pairs: [string, string][]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of pairs) out[REACT_ATTR_NAME[k] ?? k] = v;
+  return out;
+}
+
+/** Strip the `<tag …>` open and trailing `</tag>` from a component block's HTML,
+ *  leaving the inner (already-rendered markdown) HTML. Handles open (unclosed)
+ *  blocks, where there is no close tag yet. */
+function componentInnerHtml(html: string, tag: string): string {
+  const gt = html.indexOf(">");
+  if (gt < 0) return "";
+  let inner = html.slice(gt + 1);
+  const close = `</${tag}>`;
+  if (inner.endsWith(close)) inner = inner.slice(0, -close.length);
+  return inner.replace(/^\n/, "").replace(/\n$/, "");
+}
+
 /** Convert a closed block's HTML to a React tree, memoized on html+components. */
 function SafeHtml({ html, components }: { html: string; components: Components }) {
   return useMemo(() => htmlToReact(html, components), [html, components]) as JSX.Element;
@@ -138,6 +171,7 @@ function SafeHtml({ html, components }: { html: string; components: Components }
 const INTRINSIC_PX: Record<string, number> = {
   Paragraph: 80, Heading: 44, CodeBlock: 300, MathBlock: 140, Mermaid: 220,
   List: 120, Blockquote: 100, Alert: 120, Table: 200, Rule: 24, Html: 80,
+  Component: 120,
 };
 
 function BlockViewImpl(props: { block: Block; components?: Components; virtualize?: boolean }) {
@@ -161,8 +195,17 @@ function BlockViewImpl(props: { block: Block; components?: Components; virtualiz
 function renderBlockContent({ block, components }: { block: Block; components?: Components }) {
   const kind = block.kind.type;
 
-  // Block-kind override replaces the entire renderer for this block.
+  // Block-kind override replaces the entire renderer for this block. A
+  // `Component` block also dispatches on its tag name, so `components.Thinking`
+  // (the specific tag) wins over `components.Component` (the generic fallback).
   if (components) {
+    if (kind === "Component") {
+      const tag = (block.kind.data as { tag?: string } | undefined)?.tag;
+      const override = (tag && components[tag]) || components.Component;
+      if (override) {
+        return createElement(override, blockKindProps(block));
+      }
+    }
     const blockOverride = components[kind];
     if (blockOverride) {
       return createElement(blockOverride, blockKindProps(block));

package/src/types.ts

@@ -9,7 +9,8 @@ export type BlockKindTag =
   | "Alert"
   | "Table"
   | "Rule"
-  | "Html";
+  | "Html"
+  | "Component";
 
 export interface BlockKind {
   type: BlockKindTag;
@@ -60,6 +61,15 @@ export interface BlockComponentProps {
   text?: string;
   /** Info-string language — present for `CodeBlock` (from `kind.data.lang`). */
   language?: string;
+  /** Component tag name — present for `Component` blocks (from `kind.data.tag`). */
+  tag?: string;
+  /**
+   * Sanitized attributes — present for `Component` blocks. Names are React-form
+   * (`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly onto
+   * an element. For `Component` blocks, `html` is the **inner** rendered-markdown
+   * HTML (not the `<tag>…</tag>` wrapper), so an override can wrap it itself.
+   */
+  attrs?: Record<string, string>;
 }
 
 /**
@@ -93,6 +103,16 @@ export interface ParserConfig {
   dirAuto?: boolean;
   /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
   unsafeHtml?: boolean;
+  /**
+   * Opt-in allowlist of custom component tag names (e.g. `["Thinking",
+   * "Callout"]`). A `<Tag>…</Tag>` whose name is listed renders as a component
+   * whose inner content is parsed as **markdown** — safely, without `unsafeHtml`
+   * (the tag is allowlisted and its attributes are sanitized: event handlers
+   * dropped, dangerous URL schemes neutralized). The block is dispatched on the
+   * React side via `components[tag]` (or `components.Component`). Empty/omitted =
+   * off. Names match case-sensitively.
+   */
+  componentTags?: string[];
 }
 
 // Each message carries a `streamId` so one worker can multiplex many parsers

package/src/wasm/flux_md_core.d.ts

@@ -14,6 +14,13 @@ export class FluxParser {
      * memory cost against alternatives.
      */
     retainedBytes(): number;
+    /**
+     * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
+     * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner
+     * content is markdown — safely, without unsafe HTML (the tag is allowlisted
+     * and its attributes are sanitized). Empty by default (feature off).
+     */
+    setComponentTags(tags: string[]): void;
     /**
      * Emit `dir="auto"` on block-level text elements so the browser detects
      * each block's direction (LTR/RTL) independently — correct rendering for
@@ -60,6 +67,7 @@ export interface InitOutput {
     readonly fluxparser_finalize: (a: number, b: number) => void;
     readonly fluxparser_new: () => number;
     readonly fluxparser_retainedBytes: (a: number) => number;
+    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;
     readonly fluxparser_setGfmAutolinks: (a: number, b: number) => void;

package/src/wasm/flux_md_core.js

@@ -73,6 +73,18 @@ export class FluxParser {
         const ret = wasm.fluxparser_retainedBytes(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Set the opt-in component-tag allowlist (e.g. `["Thinking", "Callout"]`).
+     * A `<Tag>…</Tag>` whose name is listed renders as a component whose inner
+     * content is markdown — safely, without unsafe HTML (the tag is allowlisted
+     * and its attributes are sanitized). Empty by default (feature off).
+     * @param {string[]} tags
+     */
+    setComponentTags(tags) {
+        const ptr0 = passArrayJsValueToWasm0(tags, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.fluxparser_setComponentTags(this.__wbg_ptr, ptr0, len0);
+    }
     /**
      * Emit `dir="auto"` on block-level text elements so the browser detects
      * each block's direction (LTR/RTL) independently — correct rendering for
@@ -141,6 +153,14 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg___wbindgen_string_get_72bdf95d3ae505b1: function(arg0, arg1) {
+            const obj = getObject(arg1);
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
         __wbg___wbindgen_throw_1506f2235d1bdba0: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
@@ -233,6 +253,20 @@ heap.push(undefined, null, true, false);
 
 let heap_next = heap.length;
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    const mem = getDataViewMemory0();
+    for (let i = 0; i < array.length; i++) {
+        mem.setUint32(ptr + 4 * i, addHeapObject(array[i]), true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

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

@@ -7,6 +7,7 @@ export const fluxparser_bufferLen: (a: number) => number;
 export const fluxparser_finalize: (a: number, b: number) => void;
 export const fluxparser_new: () => number;
 export const fluxparser_retainedBytes: (a: number) => number;
+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;
 export const fluxparser_setGfmAutolinks: (a: number, b: number) => void;

package/src/worker.ts

@@ -45,6 +45,7 @@ function getOrCreate(streamId: number): FluxParser {
     p.setGfmMath(c?.gfmMath ?? false);
     p.setDirAuto(c?.dirAuto ?? false);
     p.setUnsafeHtml(c?.unsafeHtml ?? false);
+    p.setComponentTags(c?.componentTags ?? []);
     parsers.set(streamId, p);
   }
   return p;