flux-md 0.18.3 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,79 @@ 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.19.0 — 2026-06-30
+
+### Added
+
+- **`decorators` — wrap/replace matched inline text while streaming.** A
+  declarative matcher list (`{ match: RegExp | string, replace: (text, groups) =>
+  node, skipInside?: string[] }`) on `<FluxMarkdown>` (React) and the DOM mount
+  options, applied to inline **text nodes only** after parsing — so it never sees
+  link URLs, code, or markup (no avoidance rules to hand-roll), and it runs once
+  per committed block, staying linear over a stream. Wrapping matched figures
+  (e.g. `$2.5B`, `10-15%`) is a one-liner. Decorator output is a **trusted**
+  surface (like `components`); `safeUrl` is now exported and `wrapLink(text, {
+  href })` ships as the safe link path. The `decorators` prop must be
+  referentially stable (hoist/memoize) — a dev-mode warning fires if it isn't,
+  since an unstable prop would re-decorate every committed block each tick.
+- **`urlTransform`** — rewrite `href`/`src`/`poster` URLs (image proxy, allowlist,
+  relative resolution). The output is re-sanitized through the same scheme filter,
+  so a transform can't introduce a dangerous URL.
+
+### Performance
+
+- **Nested lists now stream in O(n) instead of O(n²).** A loose outer list with
+  indented sub-bullets — and any list whose items have multi-line or nested-block
+  bodies — used to make the incremental list cache bail to a full reparse on every
+  appended chunk (re-scanning the whole growing list). It now renders each item's
+  full body, nested sub-lists included, through the shared item renderer, so it
+  stays linear. Streamed and one-shot output are byte-identical. (WASM −0.3 KB.)
+
+## 0.18.5 — 2026-06-30
+
+### Performance
+
+- **Blockquotes and GFM alerts with structured bodies now stream in O(n) instead
+  of O(n²).** When a `>` blockquote or `> [!NOTE]` alert contains a list, table,
+  nested quote, heading, or code block, the incremental container cache used to
+  bail to a full reparse on every appended chunk — re-scanning and re-rendering
+  the whole growing block, so a long quoted list or alert-with-list went
+  quadratic (a 256 KB body streamed in small chunks did ~250× the parse work of a
+  16 KB one). It now renders the `>`-stripped inner through a recursive nested
+  parser, committing settled inner blocks and re-rendering only the open tail, so
+  the work is linear in document size. Streamed and one-shot output stay
+  byte-identical. (WASM +3.8 KB.)
+
+### Internal
+
+- A deterministic complexity-scaling gate (`cargo test --features perf_counters
+  --test scaling`), a proptest chunk-independence parity suite, and a cargo-fuzz
+  parity target now run in CI to catch O(n²) streaming regressions and chunk-
+  boundary divergences before they ship. The container regression above was
+  surfaced by the new gate on its first run.
+
+## 0.18.4 — 2026-06-29
+
+### Fixed
+
+- **Blockquote / alert inner content flattened mid-stream (same flicker class as
+  0.18.3's nested lists).** The container (blockquote / GFM alert) cache rendered
+  ALL inner content as plain paragraph text while streaming, so a list, nested
+  blockquote, heading, setext heading, fenced or indented code, table, thematic
+  break, HTML block, ordered list (incl. `start ≠ 1`), or link-reference
+  definition inside a `>` block showed as escaped paragraph text until finalize,
+  then snapped into its real structure. The cache now bails to the full reparse
+  whenever an inner line is anything other than plain paragraph prose. Found by
+  fuzzing the streaming prefix-parity invariant (the streamed view must equal a
+  one-shot parse at **every** prefix) over ~15k construct interactions plus an
+  adversarial corpus; streamed output now matches one-shot at every prefix for
+  these shapes.
+
+### Internal
+
+- Removed a dead struct field and an unnecessary `mut` left by recent changes
+  (clean build, no warnings).
+
 ## 0.18.3 — 2026-06-29
 
 ### Fixed

package/README.md

@@ -723,6 +723,46 @@ Rules worth knowing:
   (so your override wins) when you pass `components.CodeBlock`, `components.pre`,
   or `components.code`.
 
+#### Inline text decorators
+
+Wrap or replace matched inline **text** while streaming — e.g. bold financial
+figures — without writing your own HTML re-parser. A `decorators` entry runs
+POST-parse on real inline **text nodes only** (never URLs, code, or markup), once
+per committed block, so a long document stays **O(n)**.
+
+```tsx
+import { FluxMarkdown, wrapLink } from "flux-md";
+
+// HOIST it (module scope) or memoize — a fresh identity each render busts the
+// per-block memo and re-decorates every block on every patch (a dev warning fires).
+const decorators = [
+  { match: /\$[\d.]+[BMK]|FY\d{4}|\d+(?:[-–]\d+)?%/g, replace: (t) => <mark>{t}</mark> },
+  // Linkify a ticker — route the href through the safe helper (see below):
+  { match: /\$[A-Z]{1,5}\b/g, replace: (t) => wrapLink(t, { href: `/sym/${t.slice(1)}` }) },
+];
+
+<FluxMarkdown client={client} decorators={decorators} />;
+```
+
+- **Trusted surface — not sanitized.** A decorator's `replace` output is spliced
+  straight into the tree and does **not** pass through flux's attribute sanitizer
+  (React renders a `javascript:` href without complaint). Treat `decorators`
+  exactly like `components`: build only trusted nodes, and route any link href
+  through `wrapLink` or the exported `safeUrl`.
+- **`skipInside`** defaults to `['a','code','pre','kbd']`; override per decorator.
+- **Per-text-node.** A value split by inline markup (e.g. `$2.<em>5</em>B`) is two
+  text nodes and won't match across them — match against settled, contiguous text.
+- Matching is pure and stateless, so a value streamed char-by-char decorates
+  **identically** to a one-shot render. Same API on `flux-md/dom`
+  (`mountFluxMarkdown(client, el, { decorators })`); a decorator there returns a
+  `Node` or string.
+
+`urlTransform?: (url, { tag, attr }) => string` rewrites `href`/`src`/`poster`
+URLs as blocks render (proxy images, add UTM params). Its output is re-sanitized
+(`safeUrl(urlTransform(safeUrl(value)))`), so a buggy transform can never emit a
+`javascript:` / `data:text/html` URL. Hoist/memoize it for the same reason as
+`decorators`.
+
 ### Structured block data (`setBlockData`)
 
 Set `blockData: true` in the per-stream config and each block carries typed

package/dist/decorate.d.ts

@@ -0,0 +1,24 @@
+import type { Decorator } from "./types-core.js";
+/** Ancestor tags inside which decoration is skipped by default. */
+export declare const DEFAULT_SKIP: readonly string[];
+/** A run of the original text, or one matched span the caller turns into a node. */
+export type DecorateSegment = {
+    type: "text";
+    text: string;
+} | {
+    type: "match";
+    decorator: Decorator;
+    matchText: string;
+    groups: string[];
+};
+/**
+ * Split one inline text node's string into segments per the active decorators.
+ * Decorators apply in order; each one only re-scans the still-TEXT segments left
+ * by the previous ones (so a match is never decorated twice). `ancestors` is the
+ * chain of enclosing tag names — a decorator whose `skipInside` (default
+ * {@link DEFAULT_SKIP}) intersects it is not applied here.
+ *
+ * Returns `null` when nothing matched at all, so the caller can take the
+ * zero-allocation fast path of emitting the original text node unchanged.
+ */
+export declare function decorateSegments(text: string, decorators: Decorator[], ancestors: string[]): DecorateSegment[] | null;

package/dist/decorate.js

@@ -0,0 +1,71 @@
+const DEFAULT_SKIP = ["a", "code", "pre", "kbd"];
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toGlobalRegExp(match) {
+  if (typeof match === "string") return new RegExp(escapeRegExp(match), "g");
+  let flags = match.flags.replace("y", "");
+  if (!flags.includes("g")) flags += "g";
+  return new RegExp(match.source, flags);
+}
+function skippedByAncestor(ancestors, skip) {
+  for (let i = 0; i < ancestors.length; i++) {
+    const a = ancestors[i].toLowerCase();
+    for (let j = 0; j < skip.length; j++) {
+      if (a === skip[j].toLowerCase()) return true;
+    }
+  }
+  return false;
+}
+function splitOne(text, dec, out) {
+  const re = toGlobalRegExp(dec.match);
+  let last = 0;
+  let matched = false;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const matchText = m[0];
+    if (matchText.length === 0) {
+      re.lastIndex++;
+      continue;
+    }
+    matched = true;
+    if (m.index > last) out.push({ type: "text", text: text.slice(last, m.index) });
+    const groups = [];
+    for (let i = 1; i < m.length; i++) groups.push(m[i] ?? "");
+    out.push({ type: "match", decorator: dec, matchText, groups });
+    last = m.index + matchText.length;
+  }
+  if (!matched) return false;
+  if (last < text.length) out.push({ type: "text", text: text.slice(last) });
+  return true;
+}
+function decorateSegments(text, decorators, ancestors) {
+  let segments = null;
+  for (let d = 0; d < decorators.length; d++) {
+    const dec = decorators[d];
+    if (skippedByAncestor(ancestors, dec.skipInside ?? DEFAULT_SKIP)) continue;
+    const source = segments ?? [{ type: "text", text }];
+    let changedThisDecorator = false;
+    const next = [];
+    for (let i = 0; i < source.length; i++) {
+      const seg = source[i];
+      if (seg.type !== "text") {
+        next.push(seg);
+        continue;
+      }
+      const before = next.length;
+      if (splitOne(seg.text, dec, next)) {
+        changedThisDecorator = true;
+      } else {
+        next.length = before;
+        next.push(seg);
+      }
+    }
+    if (changedThisDecorator) segments = next;
+  }
+  return segments;
+}
+export {
+  DEFAULT_SKIP,
+  decorateSegments
+};

package/dist/dom.d.ts

@@ -1,5 +1,5 @@
 import type { FluxClient } from "./client.js";
-import type { Block, BlockComponentProps, RenderMetricsHook } from "./types-core.js";
+import type { Block, BlockComponentProps, Decorator, RenderMetricsHook, UrlTransform } from "./types-core.js";
 /**
  * Framework-neutral DOM renderer for a {@link FluxClient}. Mounts the streaming
  * document into a container and keeps it in sync via direct DOM mutation,
@@ -76,6 +76,26 @@ export interface MountOptions {
      * fast path (not code/math/mermaid/component overrides). The morphed subtree is
      * equivalent to the rebuilt one. */
     morphOpenBlocks?: boolean;
+    /**
+     * Wrap or replace matched inline **text** while streaming (parity with the
+     * React `decorators` prop). Each {@link Decorator} runs POST-render over the
+     * block's real TEXT nodes via a `TreeWalker` (after `innerHTML`), once per
+     * committed block, honoring `skipInside` (default `a`/`code`/`pre`/`kbd`).
+     *
+     * **Trusted surface.** A decorator's `replace` may return a `Node` or a string;
+     * a returned Node is inserted as-is and is NOT sanitized (a `javascript:` href
+     * on a user-built `<a>` reaches the DOM). Route hrefs through the exported
+     * {@link safeUrl}. Enabling decorators moves a block onto the walk path (off the
+     * `innerHTML`/prefix-append/morph fast paths) — still O(n) per block.
+     */
+    decorators?: Decorator[];
+    /**
+     * Rewrite `href`/`src`/`poster` URLs as blocks render (parity with the React
+     * `urlTransform` prop). The output is re-sanitized
+     * (`safeUrl(urlTransform(safeUrl(v)))`) so it can never introduce a dangerous
+     * scheme. O(1) per attribute.
+     */
+    urlTransform?: UrlTransform;
     /** Appended to the root's `className` (the `flux-md` class is always present). */
     className?: string;
     /** Set on the root element. */

package/dist/dom.js

@@ -1,6 +1,8 @@
 import { highlight } from "./hi.js";
 import { morph } from "./morph.js";
 import { blockProps, extractLang } from "./block-props.js";
+import { decorateSegments } from "./decorate.js";
+import { safeUrl } from "./url-safety.js";
 const INTRINSIC_PX = {
   Paragraph: 80,
   Heading: 44,
@@ -21,6 +23,9 @@ function mountFluxMarkdown(client, container, options = {}) {
   }
   const components = options.components && Object.keys(options.components).length > 0 ? options.components : void 0;
   const { sanitize, virtualize, stickToBottom, onRenderMetrics } = options;
+  const decorators = options.decorators && options.decorators.length > 0 ? options.decorators : void 0;
+  const urlTransform = options.urlTransform;
+  const hasInlineTransforms = !!decorators || !!urlTransform;
   const hasPerf = typeof performance !== "undefined";
   const highlightCode = options.highlightCode !== false && !components?.CodeBlock;
   const batch = options.batch !== false && typeof requestAnimationFrame === "function";
@@ -184,17 +189,17 @@ function mountFluxMarkdown(client, container, options = {}) {
       case "Mermaid":
         return renderMermaid(b);
     }
-    if (kind === "Table" && b.open) {
+    if (kind === "Table" && b.open && !hasInlineTransforms) {
       const data = tableData(b);
       if (data) return buildKeyedTable(b, data, mb);
     }
-    if (b.open && kind === "List") {
+    if (b.open && kind === "List" && !hasInlineTransforms) {
       const keyed = renderKeyedList(b);
       if (keyed) return keyed;
     }
     const node = document.createElement("div");
     node.className = genericClassName(b);
-    if (b.open && !sanitize && (kind === "Blockquote" || kind === "Alert")) {
+    if (b.open && !sanitize && !hasInlineTransforms && (kind === "Blockquote" || kind === "Alert")) {
       const wrapper = renderKeyedContainer(b);
       if (wrapper) {
         node.appendChild(wrapper);
@@ -202,7 +207,9 @@ function mountFluxMarkdown(client, container, options = {}) {
       }
     }
     node.innerHTML = sanitize ? sanitize(b.html) : b.html;
-    lastRenderGeneric = !sanitize;
+    if (decorators) decorateDomSubtree(node, decorators);
+    if (urlTransform) applyUrlTransformDom(node, urlTransform);
+    lastRenderGeneric = !sanitize && !hasInlineTransforms;
     return node;
   }
   function renderKeyedList(b) {
@@ -570,6 +577,50 @@ function alertTitleHtml(html) {
   const m = html.match(/<p class="markdown-alert-title"[^>]*>[\s\S]*?<\/p>/);
   return m ? m[0] : "";
 }
+function ancestorTags(node, root) {
+  const out = [];
+  let p = node.parentNode;
+  while (p && p !== root) {
+    if (p.tagName) out.push(p.tagName.toLowerCase());
+    p = p.parentNode;
+  }
+  return out;
+}
+const SHOW_ALL = 4294967295;
+function decorateDomSubtree(root, decorators) {
+  const walker = document.createTreeWalker(root, SHOW_ALL);
+  const texts = [];
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+    if (n.nodeType === 3) texts.push(n);
+  }
+  for (const t of texts) {
+    const segs = decorateSegments(t.data, decorators, ancestorTags(t, root));
+    if (segs === null) continue;
+    const frag = document.createDocumentFragment();
+    for (const s of segs) {
+      if (s.type === "text") {
+        frag.appendChild(document.createTextNode(s.text));
+        continue;
+      }
+      const replacement = s.decorator.replace(s.matchText, s.groups);
+      if (replacement == null) continue;
+      frag.appendChild(typeof replacement === "string" ? document.createTextNode(replacement) : replacement);
+    }
+    t.parentNode?.replaceChild(frag, t);
+  }
+}
+function applyUrlTransformDom(root, urlTransform) {
+  const els = root.querySelectorAll("[href],[src],[poster]");
+  const attrs = ["href", "src", "poster"];
+  els.forEach((el) => {
+    for (const attr of attrs) {
+      if (!el.hasAttribute(attr)) continue;
+      const cur = el.getAttribute(attr) ?? "";
+      const next = safeUrl(urlTransform(safeUrl(cur), { tag: el.tagName.toLowerCase(), attr }));
+      el.setAttribute(attr, next);
+    }
+  });
+}
 export {
   mountFluxMarkdown,
   tailOpenBlockId

package/dist/html-to-react.d.ts

@@ -1,5 +1,8 @@
-import { type ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { Components } from "./types.js";
+import type { Decorator, UrlTransform } from "./types-core.js";
+import { decodeEntities, safeUrl } from "./url-safety.js";
+export { decodeEntities, safeUrl };
 type HNode = {
     kind: "text";
     text: string;
@@ -9,8 +12,6 @@ type HNode = {
     attrs: Record<string, string | true>;
     children: HNode[];
 };
-/** Decode the (small, known) set of entities the core emits, plus numeric refs. */
-export declare function decodeEntities(s: string): string;
 /**
  * Parse an inline CSS string (`"text-align:left;color:red"`) into the object
  * React's `style` prop requires, camelCasing property names. Custom properties
@@ -36,5 +37,25 @@ export declare function parseTrustedHtml(html: string): HNode[];
  * carries the React node built under the previous components map). Segment keys
  * carry their original document order via `keyOffset` so React keys stay stable.
  */
-export declare function htmlToReact(html: string, components: Components, childMemoMap?: Map<string, ReactNode>): ReactNode;
-export {};
+export declare function htmlToReact(html: string, components: Components, childMemoMap?: Map<string, ReactNode>, opts?: {
+    decorators?: Decorator[];
+    urlTransform?: UrlTransform;
+}): ReactNode;
+/**
+ * Build a SAFE `<a>` for use inside a {@link Decorator}'s `replace`. Decorator
+ * output is a TRUSTED surface that does NOT pass through flux's attribute
+ * sanitizer, and React renders a `javascript:` href without complaint — so this
+ * runs `href` through {@link safeUrl} (the same scheme filter the core uses) and
+ * spreads the remaining attributes verbatim. Prefer this over a hand-built
+ * `<a>` whenever the href can come from model output.
+ *
+ * ```tsx
+ * const decorators = [{
+ *   match: /\$[\d.]+[BMK]/g,
+ *   replace: (t) => wrapLink(t, { href: "/figures/" + t, className: "fig" }),
+ * }];
+ * ```
+ */
+export declare function wrapLink(text: ReactNode, attrs: {
+    href: string;
+} & Record<string, unknown>): ReactElement;

package/dist/html-to-react.js

@@ -1,4 +1,6 @@
-import { createElement } from "react";
+import { createElement, Fragment } from "react";
+import { decorateSegments } from "./decorate.js";
+import { decodeEntities, safeUrl } from "./url-safety.js";
 const VOID = /* @__PURE__ */ new Set([
   "area",
   "base",
@@ -43,47 +45,6 @@ const PROP_DENY = /* @__PURE__ */ new Set([
   "suppresscontenteditablewarning"
 ]);
 const SAFE_ATTR_NAME = /^[a-z][a-z0-9-]*$/i;
-function safeUrl(value) {
-  let decoded = value;
-  for (let i = 0, prev = ""; i < 8 && decoded !== prev; i++) {
-    prev = decoded;
-    decoded = decodeEntities(decoded);
-  }
-  const probe = decoded.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
-  if (probe.startsWith("javascript:") || probe.startsWith("vbscript:") || probe.startsWith("data:text/html") || probe.startsWith("data:text/javascript")) {
-    return "#";
-  }
-  return value;
-}
-const NAMED_ENTITIES = {
-  amp: "&",
-  lt: "<",
-  gt: ">",
-  quot: '"',
-  apos: "'",
-  nbsp: "\xA0",
-  copy: "\xA9",
-  reg: "\xAE",
-  hellip: "\u2026",
-  mdash: "\u2014",
-  ndash: "\u2013"
-};
-function decodeEntities(s) {
-  if (s.indexOf("&") === -1) return s;
-  return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body) => {
-    if (body[0] === "#") {
-      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
-      if (Number.isNaN(code) || code < 0 || code > 1114111) return m;
-      try {
-        return String.fromCodePoint(code);
-      } catch {
-        return m;
-      }
-    }
-    const named = NAMED_ENTITIES[body];
-    return named === void 0 ? m : named;
-  });
-}
 function parseStyle(css) {
   const out = {};
   for (const decl of css.split(";")) {
@@ -215,7 +176,7 @@ function parseTrustedHtml(html) {
   }
   return root;
 }
-function attrsToProps(tag, attrs, key) {
+function attrsToProps(tag, attrs, key, urlTransform) {
   const props = { key };
   for (const name in attrs) {
     const value = attrs[name];
@@ -227,7 +188,11 @@ function attrsToProps(tag, attrs, key) {
       continue;
     }
     if (URL_ATTRS.has(lower) && typeof value === "string") {
-      props[ATTR_MAP[lower] ?? name] = safeUrl(value);
+      let url = safeUrl(value);
+      if (urlTransform && (lower === "href" || lower === "src" || lower === "poster")) {
+        url = safeUrl(urlTransform(url, { tag: tag.toLowerCase(), attr: lower }));
+      }
+      props[ATTR_MAP[lower] ?? name] = url;
       continue;
     }
     if (tag.toLowerCase() === "input" && lower === "checked") {
@@ -239,21 +204,43 @@ function attrsToProps(tag, attrs, key) {
   }
   return props;
 }
-function nodesToReact(nodes, components, keyPrefix) {
+function pushDecoratedText(out, text, decorators, ancestors, keyBase) {
+  const segs = decorateSegments(text, decorators, ancestors);
+  if (segs === null) {
+    out.push(text);
+    return;
+  }
+  for (let i = 0; i < segs.length; i++) {
+    const s = segs[i];
+    if (s.type === "text") {
+      out.push(s.text);
+      continue;
+    }
+    const replacement = s.decorator.replace(s.matchText, s.groups);
+    out.push(createElement(Fragment, { key: keyBase + ":" + i }, replacement));
+  }
+}
+function nodesToReact(nodes, components, keyPrefix, ctx, ancestors) {
   const out = [];
   for (let idx = 0; idx < nodes.length; idx++) {
     const n = nodes[idx];
     if (n.kind === "text") {
-      out.push(n.text);
+      if (ctx && ctx.decorators) {
+        pushDecoratedText(out, n.text, ctx.decorators, ancestors, keyPrefix + idx);
+      } else {
+        out.push(n.text);
+      }
       continue;
     }
     const key = keyPrefix + idx;
     const type = components[n.tag] ?? n.tag;
-    const props = attrsToProps(n.tag, n.attrs, key);
+    const props = attrsToProps(n.tag, n.attrs, key, ctx?.urlTransform);
     if (VOID.has(n.tag.toLowerCase())) {
       out.push(createElement(type, props));
     } else {
-      out.push(createElement(type, props, nodesToReact(n.children, components, key + ".")));
+      ancestors.push(n.tag);
+      out.push(createElement(type, props, nodesToReact(n.children, components, key + ".", ctx, ancestors)));
+      ancestors.pop();
     }
   }
   return out.length === 0 ? null : out.length === 1 ? out[0] : out;
@@ -316,8 +303,9 @@ function topLevelSegments(html) {
   if (segStart < html.length) segs.push(html.slice(segStart));
   return segs;
 }
-function htmlToReact(html, components, childMemoMap) {
-  if (!childMemoMap) return nodesToReact(parseTrustedHtml(html), components, "");
+function htmlToReact(html, components, childMemoMap, opts) {
+  const ctx = opts && (opts.decorators || opts.urlTransform) ? { decorators: opts.decorators, urlTransform: opts.urlTransform } : void 0;
+  if (!childMemoMap) return nodesToReact(parseTrustedHtml(html), components, "", ctx, []);
   const segs = topLevelSegments(html);
   const out = [];
   for (let idx = 0; idx < segs.length; idx++) {
@@ -328,17 +316,23 @@ function htmlToReact(html, components, childMemoMap) {
       out.push(hit);
       continue;
     }
-    const node = nodesToReact(parseTrustedHtml(seg), components, idx + ".");
+    const node = nodesToReact(parseTrustedHtml(seg), components, idx + ".", ctx, []);
     childMemoMap.set(cacheKey, node);
     out.push(node);
   }
   return out.length === 0 ? null : out.length === 1 ? out[0] : out;
 }
+function wrapLink(text, attrs) {
+  const { href, ...rest } = attrs;
+  return createElement("a", { ...rest, href: safeUrl(String(href)) }, text);
+}
 export {
   decodeEntities,
   getParseCount,
   htmlToReact,
   parseStyle,
   parseTrustedHtml,
-  resetParseCount
+  resetParseCount,
+  safeUrl,
+  wrapLink
 };

package/dist/index.d.ts

@@ -18,5 +18,5 @@
 export { FluxClient, FluxPool, getDefaultPool } from "./client.js";
 export { FluxMarkdown, useFluxStream, useFluxMarkdownString } from "./react.js";
 export { highlight, supportedLangs } from "./hi.js";
-export { htmlToReact, parseTrustedHtml } from "./html-to-react.js";
-export type { Block, BlockKind, BlockKindTag, BlockComponentProps, Components, Patch, FromWorker, ToWorker, WorkerLike, ParserConfig, Align, TableCell, TableData, HeadingData, CodeBlockData, MathBlockData, ListData, NestedBlock, ContainerData, } from "./types.js";
+export { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";
+export type { Block, BlockKind, BlockKindTag, BlockComponentProps, Components, Patch, FromWorker, ToWorker, WorkerLike, ParserConfig, Align, TableCell, TableData, HeadingData, CodeBlockData, MathBlockData, ListData, NestedBlock, ContainerData, Decorator, UrlTransform, FluxNode, } from "./types.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 import { FluxClient, FluxPool, getDefaultPool } from "./client.js";
 import { FluxMarkdown, useFluxStream, useFluxMarkdownString } from "./react.js";
 import { highlight, supportedLangs } from "./hi.js";
-import { htmlToReact, parseTrustedHtml } from "./html-to-react.js";
+import { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";
 export {
   FluxClient,
   FluxMarkdown,
@@ -10,7 +10,9 @@ export {
   highlight,
   htmlToReact,
   parseTrustedHtml,
+  safeUrl,
   supportedLangs,
   useFluxMarkdownString,
-  useFluxStream
+  useFluxStream,
+  wrapLink
 };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import type { Block, BlockComponentProps, Components } from "./types.js";
 import { FluxClient } from "./client.js";
-import type { ParserConfig, RenderMetricsHook } from "./types-core.js";
+import type { Decorator, ParserConfig, RenderMetricsHook, UrlTransform } from "./types-core.js";
 /**
  * Render a streaming markdown document from a FluxClient. Each block is its
  * own memoized React node keyed by its stable parser-assigned ID, so React
@@ -89,6 +89,33 @@ interface FluxMarkdownProps {
      * on every patch instead of only the streaming tail.
      */
     sanitize?: (html: string) => string;
+    /**
+     * Wrap or replace matched inline **text** while streaming, in O(n) — e.g. to
+     * bold financial figures (`$2.5B`, `10-15%`, `FY2024`) or linkify tickers. Each
+     * {@link Decorator} runs POST-PARSE on real inline TEXT nodes only (never URLs,
+     * code, or markup), once per committed block, so a long document stays linear.
+     *
+     * **Trusted surface.** A decorator's `replace` output is spliced straight into
+     * the tree and is **NOT** sanitized (React renders a `javascript:` href without
+     * complaint). Treat this exactly like `components`: build only trusted nodes,
+     * and route any link href through the exported `safeUrl` / the `wrapLink`
+     * helper. Matching is per-text-node — a value split by inline markup like
+     * `$2.<em>5</em>B` is two text nodes and won't match across them.
+     *
+     * **HOIST / memoize this array.** A fresh identity each render busts the block
+     * memo, forcing every committed block to re-parse + re-decorate every patch
+     * (O(n²)); a one-time dev warning fires if the identity changes. Enabling
+     * decorators routes a block through the walk path (off the `innerHTML` fast
+     * path) — expected, and still O(n) per block.
+     */
+    decorators?: Decorator[];
+    /**
+     * Rewrite `href`/`src`/`poster` URLs as blocks render — proxy images, add UTM
+     * params, etc. The output is re-sanitized (`safeUrl(urlTransform(safeUrl(v)))`)
+     * so it can never introduce a `javascript:` / `data:text/html` URL. **HOIST /
+     * memoize** for the same reason as `decorators`.
+     */
+    urlTransform?: UrlTransform;
     /**
      * Opt-in: when an OPEN (streaming) block re-renders each patch, reuse the
      * React nodes of its top-level children whose HTML is unchanged and re-parse
@@ -139,6 +166,7 @@ interface FluxMarkdownProps {
      */
     deferTail?: boolean;
 }
+export declare function __resetUnstableWarnings(): void;
 /**
  * Own a {@link FluxClient} for the lifetime of a component and drive it from a
  * `stream` (a `Response`, `ReadableStream<Uint8Array>`, or
@@ -193,6 +221,8 @@ export declare function blocksEqual(prev: {
     sanitize?: (html: string) => string;
     childMemo?: boolean;
     onRenderMetrics?: RenderMetricsHook;
+    decorators?: Decorator[];
+    urlTransform?: UrlTransform;
 }, next: {
     block: Block;
     components?: Components;
@@ -200,5 +230,7 @@ export declare function blocksEqual(prev: {
     sanitize?: (html: string) => string;
     childMemo?: boolean;
     onRenderMetrics?: RenderMetricsHook;
+    decorators?: Decorator[];
+    urlTransform?: UrlTransform;
 }): boolean;
 export {};

package/dist/react.js

@@ -15,6 +15,25 @@ import { MathBlock } from "./renderers/Math.js";
 import { Mermaid } from "./renderers/Mermaid.js";
 import { htmlToReact } from "./html-to-react.js";
 const NO_DEFER_BLOCKS = [];
+const warnedUnstable = /* @__PURE__ */ new Set();
+function useUnstablePropWarning(name, value) {
+  const ref = useRef(value);
+  if (ref.current !== value) {
+    const prevDefined = ref.current !== void 0 && ref.current !== null;
+    const nextDefined = value !== void 0 && value !== null;
+    ref.current = value;
+    const env = globalThis.process?.env;
+    if (prevDefined && nextDefined && !warnedUnstable.has(name) && (!env || env.NODE_ENV !== "production")) {
+      warnedUnstable.add(name);
+      console.warn(
+        `<FluxMarkdown>: the \`${name}\` prop changed identity between renders. Hoist it to module scope or wrap it in useMemo \u2014 a fresh identity each render busts the per-block memo and re-parses every block on every patch.`
+      );
+    }
+  }
+}
+function __resetUnstableWarnings() {
+  warnedUnstable.clear();
+}
 function FluxMarkdownFromClient({
   client,
   components,
@@ -28,9 +47,13 @@ function FluxMarkdownFromClient({
   "aria-live": ariaLive,
   "aria-atomic": ariaAtomic,
   onRenderMetrics,
-  deferTail
+  deferTail,
+  decorators,
+  urlTransform
 }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+  useUnstablePropWarning("decorators", decorators);
+  useUnstablePropWarning("urlTransform", urlTransform);
   const deferred = useDeferredValue(deferTail ? blocks : NO_DEFER_BLOCKS);
   const rendered = deferTail ? deferred : blocks;
   const isDeferring = deferTail ? rendered !== blocks : false;
@@ -63,7 +86,9 @@ function FluxMarkdownFromClient({
             virtualize,
             sanitize,
             childMemo,
-            onRenderMetrics: onMetrics
+            onRenderMetrics: onMetrics,
+            decorators,
+            urlTransform
           },
           b.id
         )),
@@ -217,23 +242,30 @@ const CHILD_MEMO_CAP = 4096;
 function SafeHtml({
   html,
   components,
-  childMemo
+  childMemo,
+  decorators,
+  urlTransform
 }) {
   const memoRef = useRef(null);
   const compRef = useRef(null);
+  const decoRef = useRef(void 0);
+  const urlRef = useRef(void 0);
   return useMemo(() => {
+    const opts = { decorators, urlTransform };
     if (!childMemo) {
       memoRef.current = null;
-      return htmlToReact(html, components);
+      return htmlToReact(html, components, void 0, opts);
     }
-    if (memoRef.current === null || compRef.current !== components) {
+    if (memoRef.current === null || compRef.current !== components || decoRef.current !== decorators || urlRef.current !== urlTransform) {
       memoRef.current = /* @__PURE__ */ new Map();
       compRef.current = components;
+      decoRef.current = decorators;
+      urlRef.current = urlTransform;
     }
     const map = memoRef.current;
     if (map.size > CHILD_MEMO_CAP) map.clear();
-    return htmlToReact(html, components, map);
-  }, [html, components, childMemo]);
+    return htmlToReact(html, components, map, opts);
+  }, [html, components, childMemo, decorators, urlTransform]);
 }
 function KeyedListItemImpl({
   html,
@@ -408,9 +440,12 @@ function renderBlockContent({
   block,
   components,
   sanitize,
-  childMemo
+  childMemo,
+  decorators,
+  urlTransform
 }) {
   const kind = block.kind.type;
+  const hasInlineTransforms = !!decorators || !!urlTransform;
   if (components) {
     if (kind === "Component") {
       const tag = block.kind.data?.tag;
@@ -436,13 +471,13 @@ function renderBlockContent({
       return /* @__PURE__ */ jsx(Mermaid, { html: block.html, open: block.open });
   }
   const className = "flux-block flux-block-" + kind.toLowerCase() + (block.open ? " flux-open" : "") + (block.speculative ? " flux-speculative" : "");
-  if (kind === "Table" && block.open) {
+  if (kind === "Table" && block.open && !hasInlineTransforms) {
     const data = block.kind.data;
     if (data && Array.isArray(data.rows)) {
       return /* @__PURE__ */ jsx("div", { className, children: /* @__PURE__ */ jsx(KeyedTable, { data, html: block.html, components, sanitize }) });
     }
   }
-  if (block.open && kind === "List") {
+  if (block.open && kind === "List" && !hasInlineTransforms) {
     const ld = block.kind.data;
     const items = ld?.items;
     const tagOverride = !!components && (!!components.ul || !!components.ol || !!components.li);
@@ -460,15 +495,24 @@ function renderBlockContent({
       );
     }
   }
-  if (components) {
-    if (block.open && !sanitize && (kind === "Blockquote" || kind === "Alert")) {
+  if (components || hasInlineTransforms) {
+    if (components && !hasInlineTransforms && block.open && !sanitize && (kind === "Blockquote" || kind === "Alert")) {
       const nested = block.kind.data?.nested;
       if (Array.isArray(nested)) {
         return /* @__PURE__ */ jsx("div", { className, children: /* @__PURE__ */ jsx(KeyedContainer, { block, nested, components }) });
       }
     }
     const safe = sanitize ? sanitize(block.html) : block.html;
-    return /* @__PURE__ */ jsx("div", { className, children: /* @__PURE__ */ jsx(SafeHtml, { html: safe, components, childMemo: childMemo && block.open }) });
+    return /* @__PURE__ */ jsx("div", { className, children: /* @__PURE__ */ jsx(
+      SafeHtml,
+      {
+        html: safe,
+        components: components ?? NO_COMPONENTS,
+        childMemo: childMemo && block.open,
+        decorators,
+        urlTransform
+      }
+    ) });
   }
   return /* @__PURE__ */ jsx(
     "div",
@@ -479,11 +523,15 @@ function renderBlockContent({
   );
 }
 function blocksEqual(prev, next) {
-  return prev.block.id === next.block.id && prev.block.html === next.block.html && prev.block.open === next.block.open && prev.block.speculative === next.block.speculative && prev.components === next.components && prev.virtualize === next.virtualize && prev.sanitize === next.sanitize && prev.childMemo === next.childMemo && prev.onRenderMetrics === next.onRenderMetrics;
+  return prev.block.id === next.block.id && prev.block.html === next.block.html && prev.block.open === next.block.open && prev.block.speculative === next.block.speculative && prev.components === next.components && prev.virtualize === next.virtualize && prev.sanitize === next.sanitize && prev.childMemo === next.childMemo && prev.onRenderMetrics === next.onRenderMetrics && // Identity compare: an unstable decorators/urlTransform (fresh each render)
+  // busts the memo so every committed block re-decorates — the O(n²) footgun
+  // the dev warning calls out. A hoisted/memoized value keeps the memo holding.
+  prev.decorators === next.decorators && prev.urlTransform === next.urlTransform;
 }
 const BlockView = memo(BlockViewImpl, blocksEqual);
 export {
   FluxMarkdown,
+  __resetUnstableWarnings,
   blockKindProps,
   blocksEqual,
   useFluxMarkdownString,

package/dist/types-core.d.ts

@@ -3,6 +3,51 @@ export interface BlockKind {
     type: BlockKindTag;
     data?: unknown;
 }
+/**
+ * The node type a {@link Decorator} (or `wrapLink`) builds. Kept `unknown` here
+ * so this framework-neutral types module stays React-free: the React binding
+ * treats it as `ReactNode`, the DOM binding (`flux-md/dom`) as `Node | string`.
+ */
+export type FluxNode = unknown;
+/**
+ * Wrap or replace matched inline **text** while streaming, in O(n). A decorator
+ * runs POST-PARSE on real inline TEXT nodes only (after the core renders a block
+ * to HTML and the walker parses it), once per committed block — so it never sees
+ * URLs, code, or markup, and a value split by inline markup (e.g.
+ * `$2.<em>5</em>B`) is two text nodes and won't match across them.
+ *
+ * **Trusted surface (read this).** A decorator's `replace` output is spliced
+ * directly into the render tree and does **NOT** pass through flux's attribute
+ * sanitizer (that only runs on attributes the trusted core emitted). React and
+ * the DOM both happily render a `javascript:` href. Treat `decorators` exactly
+ * like `components`: only build trusted nodes, and route any link href through
+ * the exported `safeUrl` (or use the `wrapLink` helper, which does it for you).
+ *
+ * **Stability matters (the #1 footgun).** Pass a HOISTED / memoized array — a
+ * fresh `decorators` identity every render busts the per-block memo, so every
+ * committed block re-parses and re-decorates on every patch (O(n²)). The React
+ * binding emits a one-time dev warning if the identity changes.
+ */
+export interface Decorator {
+    /** Tested against each inline TEXT node's string only (never URLs/code/markup). */
+    match: RegExp | string;
+    /** PURE fn building the replacement for ONE match. Returns framework nodes. */
+    replace: (matchText: string, groups: string[]) => FluxNode;
+    /** Ancestor tags to skip. Default `['a','code','pre','kbd']`. */
+    skipInside?: string[];
+}
+/**
+ * Rewrite a URL attribute (`href`/`src`/`poster`) as a block renders — e.g. to
+ * proxy images or add UTM params. Applied O(1) per attribute. The renderer
+ * re-sanitizes the OUTPUT (`safeUrl(urlTransform(safeUrl(value)))`), so a buggy
+ * or hostile transform can never emit a `javascript:` / `data:text/html` URL
+ * that reaches the DOM. Like `decorators`, pass a HOISTED / memoized function so
+ * the per-block memo holds.
+ */
+export type UrlTransform = (url: string, ctx: {
+    tag: string;
+    attr: "href" | "src" | "poster";
+}) => string;
 /** Column alignment from the `|:--|:-:|--:|` delimiter row; `null` = unset. */
 export type Align = "left" | "center" | "right" | null;
 /**

package/dist/url-safety.d.ts

@@ -0,0 +1,12 @@
+/** Decode the (small, known) set of entities the core emits, plus numeric refs. */
+export declare function decodeEntities(s: string): string;
+/** Replace a dangerous-scheme URL with "#". Mirrors the Rust `is_dangerous_scheme`:
+ *  strip control chars (C0, DEL, C1 — matching Rust char::is_control),
+ *  lowercase, then match. The strip affects only the probe, never output.
+ *
+ *  Exported as the SAFE URL path for user `decorators` / `urlTransform`: their
+ *  output is a TRUSTED surface that does NOT pass through the attribute
+ *  sanitizer, and React/the DOM happily render a `javascript:` href, so a
+ *  decorator that builds a link must route its href through this (see
+ *  `wrapLink`), and `urlTransform` output is re-run through it by the renderer. */
+export declare function safeUrl(value: string): string;

package/dist/url-safety.js

@@ -0,0 +1,45 @@
+const NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  copy: "\xA9",
+  reg: "\xAE",
+  hellip: "\u2026",
+  mdash: "\u2014",
+  ndash: "\u2013"
+};
+function decodeEntities(s) {
+  if (s.indexOf("&") === -1) return s;
+  return s.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      if (Number.isNaN(code) || code < 0 || code > 1114111) return m;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return m;
+      }
+    }
+    const named = NAMED_ENTITIES[body];
+    return named === void 0 ? m : named;
+  });
+}
+function safeUrl(value) {
+  let decoded = value;
+  for (let i = 0, prev = ""; i < 8 && decoded !== prev; i++) {
+    prev = decoded;
+    decoded = decodeEntities(decoded);
+  }
+  const probe = decoded.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
+  if (probe.startsWith("javascript:") || probe.startsWith("vbscript:") || probe.startsWith("data:text/html") || probe.startsWith("data:text/javascript")) {
+    return "#";
+  }
+  return value;
+}
+export {
+  decodeEntities,
+  safeUrl
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
   "sideEffects": ["./dist/worker.js", "./dist/styles.css"],