flux-md 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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.5.0 — 2026-05-27
+
+### Fixed
+
+- **Streaming GFM tables now render incrementally.** A table no longer waits for
+  the whole block to arrive: the header renders the moment the delimiter row
+  (`|---|`) streams in, and each body row appends as it arrives. Previously the
+  incremental paragraph fast-path kept extending the header line as a paragraph
+  and only formed the table on a full reparse, so a streaming table appeared all
+  at once. The fast-path now bails (like it does for a setext underline) when a
+  delimiter row forms a table with its preceding header. Output is unchanged for
+  one-shot parsing; streamed output now matches one-shot at every prefix.
+
+### Added
+
+- **`<FluxMarkdown sanitize={fn} />`** — an optional HTML sanitizer hook. When
+  provided, flux-md runs every block's HTML through it before injecting via
+  `innerHTML`, **including the streaming (open/speculative) tail** that the raw
+  fast path would otherwise expose. Bring your own sanitizer (e.g.
+  `DOMPurify.sanitize`) to render untrusted / LLM HTML with `unsafeHtml` on;
+  flux-md stays zero-dep. Built-in code/math renderers (already-escaped content)
+  are not run through it, so highlighting and math markup are preserved. Omitting
+  the prop is byte-identical and zero-cost.
+
+## 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

package/README.md

@@ -105,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)
   },
 });
 ```
@@ -211,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
@@ -302,6 +345,28 @@ flux-md is XSS-safe by default — its HTML output is meant to be injected via
   third-party HTML, these guards are your only line of defense — prefer a
   dedicated HTML sanitizer for genuinely hostile input.
 
+### Rendering untrusted / LLM HTML safely
+
+If you enable `unsafeHtml` to render HTML from an untrusted source (e.g. an LLM
+that returns raw HTML), **bring a real sanitizer** and pass it via
+`<FluxMarkdown sanitize={…} />`. flux-md applies it to every block's HTML before
+injection — **including the streaming (open) tail**, which the raw-`innerHTML`
+fast path would otherwise expose. flux-md stays zero-dep; you choose the
+sanitizer:
+
+```tsx
+import DOMPurify from "dompurify";
+
+<FluxMarkdown client={client} sanitize={(html) => DOMPurify.sanitize(html)} />
+```
+
+The built-in code/math renderers operate on already-escaped content and are not
+run through `sanitize`, so syntax highlighting and math markup are preserved.
+With no `sanitize` prop, rendering is byte-identical and zero-cost. For
+genuinely hostile content where CSS-overlay/clickjacking matters, render inside
+a sandboxed `<iframe>` instead — sanitization stops injection, not every
+visual-overlay trick.
+
 ## Scaling
 
 `FluxClient`s share a **worker pool** (`getDefaultPool()`), so concurrency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.3.2",
+  "version": "0.5.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/react.tsx

@@ -65,9 +65,19 @@ interface FluxMarkdownProps {
    * up (and re-locks when they scroll back near the bottom). Off by default.
    */
   stickToBottom?: boolean;
+  /**
+   * Optional HTML sanitizer applied to every block's HTML before it is injected
+   * via `innerHTML` — **including the streaming (open/speculative) tail**, the
+   * path that raw `innerHTML` would otherwise expose. Pass a real sanitizer
+   * (e.g. DOMPurify's `sanitize`) when rendering untrusted / LLM HTML with
+   * `unsafeHtml` on. flux-md stays zero-dep — you bring the sanitizer. The
+   * built-in code/math renderers operate on already-escaped content and are not
+   * run through it. When omitted, rendering is byte-identical and zero-cost.
+   */
+  sanitize?: (html: string) => string;
 }
 
-function FluxMarkdownImpl({ client, components, virtualize, stickToBottom }: FluxMarkdownProps) {
+function FluxMarkdownImpl({ client, components, virtualize, stickToBottom, sanitize }: FluxMarkdownProps) {
   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.
@@ -75,7 +85,7 @@ function FluxMarkdownImpl({ client, components, virtualize, stickToBottom }: Flu
   return (
     <div className="flux-md">
       {blocks.map((b) => (
-        <BlockView key={b.id} block={b} components={comps} virtualize={virtualize} />
+        <BlockView key={b.id} block={b} components={comps} virtualize={virtualize} sanitize={sanitize} />
       ))}
       {stickToBottom && <div aria-hidden="true" style={{ scrollSnapAlign: "end" }} className="flux-bottom-anchor" />}
     </div>
@@ -117,16 +127,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,9 +181,15 @@ 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 }) {
+function BlockViewImpl(props: {
+  block: Block;
+  components?: Components;
+  virtualize?: boolean;
+  sanitize?: (html: string) => string;
+}) {
   const { block, virtualize } = props;
   const content = renderBlockContent(props);
   // Virtualize only *closed* blocks: the streaming tail (open/speculative) is
@@ -158,11 +207,28 @@ function BlockViewImpl(props: { block: Block; components?: Components; virtualiz
   return content;
 }
 
-function renderBlockContent({ block, components }: { block: Block; components?: Components }) {
+function renderBlockContent({
+  block,
+  components,
+  sanitize,
+}: {
+  block: Block;
+  components?: Components;
+  sanitize?: (html: string) => string;
+}) {
   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));
@@ -199,7 +265,12 @@ function renderBlockContent({ block, components }: { block: Block; components?:
     );
   }
 
-  return <div className={className} dangerouslySetInnerHTML={{ __html: block.html }} />;
+  return (
+    <div
+      className={className}
+      dangerouslySetInnerHTML={{ __html: sanitize ? sanitize(block.html) : block.html }}
+    />
+  );
 }
 
 // A block is the same render when its identity, HTML, open-state, and the
@@ -207,8 +278,8 @@ function renderBlockContent({ block, components }: { block: Block; components?:
 // is what stops a committed block from re-rendering (and thus re-parsing) on
 // every streaming patch.
 export function blocksEqual(
-  prev: { block: Block; components?: Components; virtualize?: boolean },
-  next: { block: Block; components?: Components; virtualize?: boolean },
+  prev: { block: Block; components?: Components; virtualize?: boolean; sanitize?: (html: string) => string },
+  next: { block: Block; components?: Components; virtualize?: boolean; sanitize?: (html: string) => string },
 ): boolean {
   return (
     prev.block.id === next.block.id &&
@@ -216,7 +287,8 @@ export function blocksEqual(
     prev.block.open === next.block.open &&
     prev.block.speculative === next.block.speculative &&
     prev.components === next.components &&
-    prev.virtualize === next.virtualize
+    prev.virtualize === next.virtualize &&
+    prev.sanitize === next.sanitize
   );
 }
 

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;