flux-md 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,95 @@ 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.15.0 — 2026-06-17
+
+### Added
+
+- **Safe raw-HTML sanitizer (`htmlAllowlist` / `dropHtmlTags`)** — render a safe
+  subset of *inline* raw HTML (`<br>`, `<sub>`, `<sup>`, `<mark>`, …) **without**
+  `unsafeHtml`. Setting either list (even to `[]`) engages it: `htmlAllowlist`
+  non-empty renders only those tags (others escaped); **empty allows all tags
+  except a built-in, non-overridable dangerous set** (`script`, `style`,
+  `iframe`, `object`, `embed`, `form`, `svg`, `xmp`, `plaintext`, …);
+  `dropHtmlTags` removes tags entirely. Every rendered tag's attributes are
+  sanitized — `on*` handlers and `style` (a CSS beacon / clickjacking vector)
+  dropped, dangerous URL schemes (incl. multi-encoded) → `#`. Inline-scoped;
+  block-level raw HTML stays escaped. Matching is case-insensitive.
+
+### Fixed
+
+- **HTML comments are dropped instead of escaped to visible text.** `<!--mk:id-->`
+  (a common LLM marker) previously rendered as a literal `&lt;!--…--&gt;` run or a
+  `<pre><code>` block; it now has no visible representation, in every mode except
+  bare `unsafeHtml` pass-through (which keeps it verbatim for CommonMark fidelity —
+  the browser ignores it either way). A comment-led block with trailing content
+  keeps that content (only comment-*only* blocks are dropped).
+
+### Security
+
+- The dangerous-tag set is **non-overridable** (allowlisting `script`/`iframe`/`svg`
+  still drops them), `style` is stripped from every sanitized/component tag, and
+  raw-text elements (`xmp`/`plaintext`/`noembed`/`noframes`/`listing`) are blocked
+  in allow-all mode — closing CSS-exfiltration / clickjacking / DOM-corruption
+  vectors found in adversarial review. The React `htmlToReact` path mirrors the
+  `style` value-filter as defense-in-depth (safe declarations like `text-align`
+  still pass).
+
+Feature-off output is byte-identical except HTML comments now drop (the
+CommonMark/GFM suites run with `unsafeHtml` on, so the 652/GFM floors are
+unaffected).
+
+## 0.14.0 — 2026-06-17
+
+### Added
+
+- **Inline custom component tags (`inlineComponentTags`)** — the headline gap for
+  rich apps. An allowlisted inline tag like `<tik symbol="AAPL">AAPL</tik>` (or
+  self-closing `<tik/>`) **anywhere inline** — paragraphs, headings, list items,
+  and **table cells** — renders as a real custom element with its inner parsed as
+  **inline markdown** and its attributes sanitized (event handlers dropped,
+  dangerous URL schemes → `#`). The React renderer dispatches it to
+  `components[tag]` with the inner markdown as `children` and the attributes as
+  props — **XSS-safe without `unsafeHtml`**. Independent of `componentTags`
+  (block containers): list a tag under either or both. Use lowercase tag names.
+- **`children` on `Component` block overrides** — a `Component` override now also
+  receives the inner content pre-parsed to a React tree (`children`), so you can
+  `return <Chip {...attrs}>{children}</Chip>` instead of
+  `dangerouslySetInnerHTML`-ing `html`. The html-vs-children contract is now loud
+  in the types and docs (an override that renders neither shows empty).
+- **`flux-md/server` — worker-free synchronous SSR / RSC rendering.** The Rust→
+  WASM core is a plain synchronous parser, so finished markdown renders on the
+  server with no worker: `initFlux()` (async, idempotent — reads the co-located
+  `.wasm` in Node, or `initFluxSync(bytes)` on edge), `renderToString(md, {
+  config })` (sync HTML string, zero React dep), `parseToBlocks(md, { config })`,
+  and `<FluxMarkdownStatic content config components />` — a hookless, RSC-safe
+  React component that emits the same `flux-md` tree a client `<FluxMarkdown>`
+  hydrates, with the same overrides (inline/block component tags dispatch on the
+  server too).
+- **`FluxParser.allBlocks()` (WASM)** — returns the whole parsed document as a
+  block array, the one-shot render primitive used by `flux-md/server`.
+
+### Fixed
+
+- **Data-loss: a block component tag used inline swallowed sibling blocks.** With
+  e.g. `componentTags: ["tik"]`, an inline occurrence such as
+  `<tik>AAPL</tik> is up.` on a line with following content opened a block
+  container that consumed the rest of the document (the paragraph and a following
+  table vanished). A block component open tag must now be the **whole line** (only
+  trailing whitespace after `>`); otherwise it's treated as inline and degrades
+  inertly — it never eats surrounding content.
+
+### Changed
+
+- The React HTML→tree converter (`htmlToReact` / `parseTrustedHtml`) now preserves
+  a tag's original **case** for component dispatch (so a capitalized inline tag
+  like `<Cite>` maps to `components.Cite`); HTML semantics (void elements, `input`,
+  close-tag matching) still compare case-insensitively, so standard output is
+  unchanged.
+
+Feature-off output is byte-identical (CommonMark 652 + GFM floors hold); both
+allowlists are empty by default.
+
 ## 0.13.0 — 2026-06-04
 
 ### Added

package/README.md

@@ -18,7 +18,10 @@ import.meta.url)`** pattern, so any bundler with asset-module support resolves
 them: **Vite** (the reference setup), **webpack 5**, **Rollup** (with asset
 modules), **Parcel**, and **Next.js** (App Router — Turbopack *and* webpack;
 **verified on Next.js 16**, see the [Next.js callout](#nextjs) below). It is
-**browser-only** (it constructs Web Workers); it does not run under SSR/RSC. The framework packages — `react`,
+The streaming client (`<FluxMarkdown>` / `FluxClient`) is **browser-only** (it
+constructs Web Workers). For **server-side / static rendering of finished
+content** — SSR, React Server Components, build steps — use the worker-free,
+synchronous [`flux-md/server`](#server-side-rendering) entry. The framework packages — `react`,
 `vue`, `svelte`, `solid-js` — are all **optional** peer dependencies; you only
 need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
 `flux-md/dom`, `flux-md/element`) needs none.
@@ -403,6 +406,55 @@ issue if your Solid setup trips on it. The component is a thin `ref`'d `<div>`;
 if you hit a transform edge, `mountFluxMarkdown` from `flux-md/dom` inside
 `onMount`/`onCleanup` is the zero-surprise fallback.
 
+## Server-side rendering
+
+`<FluxMarkdown>` / `FluxClient` are browser-only (they spawn a Web Worker), but
+the Rust→WASM core is a plain **synchronous** parser. So `flux-md/server` renders
+**finished** markdown on the server with no worker and no async ceremony — Node
+SSR, React Server Components, or a build step:
+
+```ts
+import { initFlux, renderToString } from "flux-md/server";
+
+await initFlux();                                       // once at startup (loads the WASM)
+const html = renderToString("# Hello\n\n**world**");   // sync HTML string, no worker
+```
+
+For React server rendering (RSC, static generation, or SSR), use
+`<FluxMarkdownStatic>` — a hookless, RSC-safe component that renders finished
+content with the same `components` overrides (inline/block component tags
+dispatch on the server too):
+
+```tsx
+import { initFlux, FluxMarkdownStatic } from "flux-md/server";
+
+await initFlux();
+export default function Doc({ md }: { md: string }) {
+  return (
+    <FluxMarkdownStatic
+      content={md}
+      config={{ inlineComponentTags: ["tik"] }}
+      components={{ tik: ({ symbol }) => <span className="ticker">{symbol}</span> }}
+    />
+  );
+}
+```
+
+- **`initFlux()`** — async, idempotent. In Node it reads the package's `.wasm` off
+  disk (Node's `fetch` can't load `file://`); on the web it fetches the
+  bundler-resolved asset. On edge runtimes pass bytes yourself:
+  `initFluxSync(wasmBytes)`.
+- **`renderToString(md, { config })`** — synchronous HTML string, **zero React
+  dependency**.
+- **`parseToBlocks(md, { config })`** — the block array, for custom rendering.
+- **`<FluxMarkdownStatic content config components />`** — synchronous React tree
+  for **render-once** contexts; render it with your framework's server renderer
+  (`renderToStaticMarkup`, RSC, …). For live streaming, client-side code
+  highlighting, or Mermaid, render `<FluxMarkdown>` on the client instead — it's a
+  separate component. (If you SSR-then-hydrate, use the *same* component on both
+  sides; the dedicated client renderers in `<FluxMarkdown>` don't hydrate
+  `<FluxMarkdownStatic>`'s plainer markup.)
+
 ## What it does
 
 | Concern | flux-md | conventional main-thread renderer |
@@ -428,6 +480,11 @@ highlighter's colors** (without any CSS, `highlight()` renders uncolored). The
 theme is scoped to `.flux-md`, zero-runtime, and **does not change the rendered
 HTML** — skip the import and nothing is styled.
 
+> **Next.js Pages Router:** `flux-md/styles.css` is global CSS, which the Pages
+> Router only allows importing from `pages/_app`. Import it there (App Router and
+> other bundlers can import it from any component). Or skip it and bring your own
+> `.flux-md` styles.
+
 Re-theme by overriding a few CSS variables; it's light by default and switches to
 dark automatically via `prefers-color-scheme` (force a mode with
 `class="flux-md flux-dark"` or `flux-light`):
@@ -499,7 +556,10 @@ const client = new FluxClient({
     dirAuto: true,        // per-block dir="auto" for RTL/bidi text (default false)
     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)
+    componentTags: ["Thinking", "Callout"], // BLOCK custom tags w/ markdown inside (default none)
+    inlineComponentTags: ["tik", "cite"],   // INLINE custom tags (chips/citations) w/ markdown inside (default none)
+    htmlAllowlist: ["br", "sub", "sup"],    // safe raw-HTML sanitizer: [] = allow all but dangerous; list = only those (default off)
+    dropHtmlTags: [],                        // tags removed entirely (comments always dropped when sanitizing; default off)
     blockData: true,      // opt-in structured kind.data per block (default false — see "Structured block data")
   },
 });
@@ -527,10 +587,16 @@ When to enable each flag:
 - `unsafeHtml: true` — only when rendering trusted HTML. For untrusted /
   LLM-produced HTML, pair this with `<FluxMarkdown sanitize={…} />` (DOMPurify or
   similar — see [Security](#security)).
-- `componentTags: ["Thinking", …]` — when your LLM emits custom tags like
-  `<Thinking>…</Thinking>` and you want their inner content parsed as markdown
-  and dispatched to a React component. Safe without `unsafeHtml` (attributes are
-  sanitized; allowlisted tags only).
+- `componentTags: ["Thinking", …]` — when your LLM emits **block** custom tags
+  like `<Thinking>…</Thinking>` (on their own line) and you want their inner
+  content parsed as markdown and dispatched to a React component. Safe without
+  `unsafeHtml` (attributes are sanitized; allowlisted tags only).
+- `inlineComponentTags: ["tik", …]` — same idea for **inline** custom elements
+  that sit inside a paragraph, heading, list item, or **table cell** (ticker
+  chips, citations, `@mentions`). See [Inline component tags](#inline-component-tags).
+- `htmlAllowlist` / `dropHtmlTags` — render a **safe subset of raw HTML** (e.g.
+  `<br>`, `<sub>`, `<sup>`) natively without `unsafeHtml`, drop specific tags, and
+  drop HTML comments. See [Safe raw HTML](#safe-raw-html).
 
 **Footnotes** (`gfmFootnotes`) work in streaming with one honest caveat: a
 `[^1]` reference renders speculatively the moment it's seen (committed blocks
@@ -700,29 +766,101 @@ 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:
+`attrs`, the inner content as ready-to-render **`children`** (the easy path), and
+also `html` (the inner already-rendered markdown string, for
+`dangerouslySetInnerHTML`):
 
 ```tsx
 <FluxMarkdown
   client={client}
   components={{
-    Thinking: ({ html }) => (
+    Thinking: ({ children }) => (
       <details className="thinking">
         <summary>Reasoning</summary>
-        <div dangerouslySetInnerHTML={{ __html: html }} />
+        {children}
       </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.
+> **`children` vs `html`.** A `Component` override that renders *neither* shows
+> **empty** (a common first-try gotcha). Prefer **`children`** — a parsed React
+> tree with nested overrides applied; reach for `dangerouslySetInnerHTML={{ __html:
+> html }}` only when you need the raw string. `attrs` keys are React-form
+> (`class`→`className`, `for`→`htmlFor`) so `{...attrs}` spreads cleanly. While
+> streaming, both reflect the partial inner content and re-render as more arrives.
+> With no override the block renders as `<thinking …>…</thinking>`. Tag names
+> match case-sensitively; off unless `componentTags` is set.
+
+<a id="inline-component-tags"></a>
+
+#### Inline component tags
+
+`componentTags` handles **block** containers (a `<Thinking>` on its own line). For
+**inline** custom elements — ticker chips, citations, `@mentions`, inline tooltips
+that sit *inside* a paragraph, heading, list item, or **table cell** — use
+`inlineComponentTags`:
+
+```tsx
+const client = new FluxClient({ config: { inlineComponentTags: ["tik"] } });
+
+<FluxMarkdown
+  client={client}
+  components={{
+    tik: ({ symbol, children }) => <span className="ticker">{children ?? symbol}</span>,
+  }}
+/>;
+```
+
+Now `Apple <tik symbol="AAPL">AAPL</tik> rose 2%` (or self-closing
+`<tik symbol="AAPL"/>`) dispatches the inline `<tik>` to `components.tik`: its
+inner is parsed as **inline markdown** (the `children`), its attributes become
+props, and it's **safe without `unsafeHtml`** (attributes sanitized, allowlisted
+tags only). It works everywhere inline content does — **including table cells**.
+Tag names match **case-sensitively** and dispatch verbatim to `components[tag]`
+(`<tik>`→`components.tik`, `<Cite>`→`components.Cite`). The
+two lists are independent: list a tag under `componentTags` for blocks,
+`inlineComponentTags` for inline, or both for both. An allowlisted tag used in an
+unsupported position degrades **inertly** (escaped) — it never consumes
+surrounding content.
+
+> **Link-bridge alternative.** Before `inlineComponentTags`, the way to get an
+> inline custom element was the link bridge: emit `[$AAPL](tik://AAPL)` and
+> override `a` to render a chip when the href scheme matches. It's XSS-safe and
+> renders inline-in-cells too — `inlineComponentTags` simply replaces that
+> workaround with first-class inline elements.
+
+### Safe raw HTML
+
+LLMs emit a little raw HTML — `<br>`, `<sub>`/`<sup>`, `<mark>`, and HTML comments
+as markers (`<!--mk:id-->`). `unsafeHtml` is all-or-nothing; instead opt into a
+**sanitizer** that renders a safe subset natively. Setting `htmlAllowlist` and/or
+`dropHtmlTags` (even to `[]`) engages it:
+
+```ts
+// Render only these inline tags; escape everything else:
+new FluxClient({ config: { htmlAllowlist: ["br", "sub", "sup", "mark"] } });
+
+// Or allow everything except a built-in dangerous set:
+new FluxClient({ config: { htmlAllowlist: [] } });
+```
+
+- **HTML comments are dropped** — no more `<!--mk:id-->` surfacing as escaped text
+  — in every mode except bare `unsafeHtml` pass-through.
+- **`htmlAllowlist: ["br", …]`** renders only those inline tags; everything else is
+  escaped. **`htmlAllowlist: []`** (empty) allows *all* tags **except a built-in
+  dangerous set** (`script`, `style`, `iframe`, `object`, `embed`, `form`, `svg`,
+  `xmp`, `plaintext`, … — **non-overridable**: allowlisting one still drops it).
+- **`dropHtmlTags: ["mk", …]`** removes those tags entirely (markup gone; inner
+  text stays as inert text).
+- Every rendered tag's **attributes are sanitized**: `on*` handlers and `style`
+  (a CSS beacon / clickjacking vector) are dropped, and dangerous URL schemes
+  (`javascript:`, …, including multi-encoded) become `#`.
+- **Scope:** *inline* raw HTML. Block-level raw HTML stays escaped for now (use
+  `unsafeHtml` **without** the sanitizer to render block HTML — when the sanitizer
+  is engaged, block HTML stays escaped even if `unsafeHtml` is also on). Tag
+  matching is case-insensitive.
 
 ### Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.13.0",
+  "version": "0.15.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", "./src/styles.css"],
@@ -10,6 +10,7 @@
     ".": "./src/index.ts",
     "./client": "./src/client.ts",
     "./react": "./src/react.tsx",
+    "./server": "./src/server.tsx",
     "./dom": "./src/dom.ts",
     "./element": "./src/element.ts",
     "./vue": "./src/vue.ts",

package/src/html-to-react.ts

@@ -38,8 +38,17 @@ const URL_ATTRS = new Set(["href", "src", "xlink:href", "formaction", "action",
  *  strip control chars (C0, DEL, C1 — matching Rust char::is_control),
  *  lowercase, then match. The strip affects only the probe, never output. */
 function safeUrl(value: string): string {
+  // Decode-STABLE probe: a value can be entity-decoded more than once before it
+  // reaches the DOM, so peel layers to a fixpoint before the scheme check —
+  // catches `javascript:` and double-encoded `javascript:`. Only the
+  // probe is decoded; the returned value is untouched (safe URLs stay verbatim).
+  let decoded = value;
+  for (let prev = ""; decoded !== prev; ) {
+    prev = decoded;
+    decoded = decodeEntities(decoded);
+  }
   // eslint-disable-next-line no-control-regex
-  const probe = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
+  const probe = decoded.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/^\s+/, "").toLowerCase();
   if (
     probe.startsWith("javascript:") ||
     probe.startsWith("vbscript:") ||
@@ -101,12 +110,37 @@ export function parseStyle(css: string): Record<string, string> {
   return out;
 }
 
+// CSS values that beacon/exfiltrate (`url(`), execute (legacy `expression(`,
+// `-moz-binding`, `behavior:`), or pull external resources (`@import`,
+// `image-set(`). Defense-in-depth: the core sanitizer already drops `style`, but
+// `htmlToReact` is exported and may be handed untrusted HTML directly.
+const DANGEROUS_CSS_VALUE = /url\(|expression\(|image-set\(|-moz-binding|@import|behavior\s*:/i;
+
+/** Strip CSS declarations that can beacon/exfiltrate, execute, or overlay the
+ *  viewport (`position: fixed/sticky` → clickjacking). Safe declarations
+ *  (`text-align`, `color`, …) — including flux's own table-alignment style —
+ *  pass through untouched. */
+function safeStyle(style: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k in style) {
+    const v = style[k];
+    if (DANGEROUS_CSS_VALUE.test(v)) continue;
+    if (k.toLowerCase() === "position" && /\b(?:fixed|sticky)\b/i.test(v)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
 /** Parse one opening tag starting at `start` (the `<`). */
 function parseOpenTag(html: string, start: number) {
   let i = start + 1;
   let j = i;
   while (j < html.length && /[a-zA-Z0-9-]/.test(html[j])) j++;
-  const tag = html.slice(i, j).toLowerCase();
+  // Preserve the tag's ORIGINAL case so an inline custom-component element (e.g.
+  // `<Cite>`) dispatches to `components.Cite`. Standard elements the core emits
+  // are already lowercase; the semantic checks below (VOID, `input`, close-tag
+  // matching) lowercase as needed, so HTML behavior is unchanged.
+  const tag = html.slice(i, j);
   i = j;
   const attrs: Record<string, string | true> = {};
   while (i < html.length) {
@@ -193,9 +227,9 @@ export function parseTrustedHtml(html: string): HNode[] {
     }
     if (html[lt + 1] === "/") {
       const end = html.indexOf(">", lt);
-      const tag = html.slice(lt + 2, end === -1 ? html.length : end).trim().toLowerCase();
+      const closeLower = html.slice(lt + 2, end === -1 ? html.length : end).trim().toLowerCase();
       for (let s = stack.length - 1; s >= 0; s--) {
-        if (stack[s].tag === tag) {
+        if (stack[s].tag.toLowerCase() === closeLower) {
           stack.length = s;
           break;
         }
@@ -216,7 +250,7 @@ export function parseTrustedHtml(html: string): HNode[] {
     const { tag, attrs, selfClose, next } = parseOpenTag(html, lt);
     const el: Extract<HNode, { kind: "el" }> = { kind: "el", tag, attrs, children: [] };
     push(el);
-    if (!selfClose && !VOID.has(tag)) stack.push(el);
+    if (!selfClose && !VOID.has(tag.toLowerCase())) stack.push(el);
     i = next;
   }
   return root;
@@ -232,7 +266,7 @@ function attrsToProps(tag: string, attrs: Record<string, string | true>, key: st
     // future React behavior.
     if (lower.startsWith("on")) continue;
     if (lower === "style" && typeof value === "string") {
-      props.style = parseStyle(value);
+      props.style = safeStyle(parseStyle(value));
       continue;
     }
     // Neutralize dangerous-scheme URLs (javascript:, vbscript:, data:text/html).
@@ -242,7 +276,7 @@ function attrsToProps(tag: string, attrs: Record<string, string | true>, key: st
     }
     // A static checkbox carries `checked` with no handler; render it
     // uncontrolled so React doesn't warn about a missing onChange.
-    if (tag === "input" && lower === "checked") {
+    if (tag.toLowerCase() === "input" && lower === "checked") {
       props.defaultChecked = value === true ? true : value;
       continue;
     }
@@ -262,13 +296,15 @@ function nodesToReact(nodes: HNode[], components: Components, keyPrefix: string)
     const key = keyPrefix + idx;
     const type = components[n.tag] ?? n.tag;
     const props = attrsToProps(n.tag, n.attrs, key);
-    if (VOID.has(n.tag)) {
+    if (VOID.has(n.tag.toLowerCase())) {
       out.push(createElement(type, props));
     } else {
       out.push(createElement(type, props, nodesToReact(n.children, components, key + ".")));
     }
   }
-  return out.length === 1 ? out[0] : out;
+  // `null` (not an empty array) for no children, so a self-closing / empty inline
+  // component's `children` is nullish and a `{children ?? fallback}` override fires.
+  return out.length === 0 ? null : out.length === 1 ? out[0] : out;
 }
 
 /**

package/src/react.tsx

@@ -308,7 +308,7 @@ function decodeMathText(html: string): string {
   return decodeCodeText(html);
 }
 
-function blockKindProps(block: Block): BlockComponentProps {
+export function blockKindProps(block: Block, components?: Components): BlockComponentProps {
   const props: BlockComponentProps = {
     block,
     html: block.html,
@@ -343,6 +343,10 @@ 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);
+    // Convenience: the inner markdown pre-parsed to a React tree (with nested
+    // tag/inline-component overrides applied). Render `{children}` directly
+    // instead of dangerouslySetInnerHTML-ing `html` — the easy, correct path.
+    props.children = htmlToReact(props.html, components ?? {});
   } 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
@@ -440,12 +444,12 @@ function renderBlockContent({
       const tag = (block.kind.data as { tag?: string } | undefined)?.tag;
       const override = (tag && components[tag]) || components.Component;
       if (override) {
-        return createElement(override, blockKindProps(block));
+        return createElement(override, blockKindProps(block, components));
       }
     }
     const blockOverride = components[kind];
     if (blockOverride) {
-      return createElement(blockOverride, blockKindProps(block));
+      return createElement(blockOverride, blockKindProps(block, components));
     }
   }
 

package/src/server.tsx

@@ -0,0 +1,215 @@
+import { createElement, type ReactNode } from "react";
+import initWasmAsync, { FluxParser, initSync } from "./wasm/flux_md_core.js";
+import { htmlToReact } from "./html-to-react";
+import { blockKindProps } from "./react";
+import type { Block, Components, ParserConfig } from "./types";
+
+/**
+ * Synchronous, worker-free server / static rendering for flux-md.
+ *
+ * The browser path runs the Rust→WASM core in a Web Worker, but the very same
+ * `FluxParser` is a plain synchronous class — so on the server (Node, RSC, a
+ * build step) you can parse a finished markdown string with no worker and no
+ * async ceremony:
+ *
+ * ```ts
+ * import { initFlux, renderToString } from "flux-md/server";
+ * await initFlux();                       // once, at startup
+ * const html = renderToString(markdown);  // sync, no worker
+ * ```
+ *
+ * For React server rendering (RSC, static generation, SSR) use {@link
+ * FluxMarkdownStatic} — a hookless, RSC-safe component with the same `components`
+ * overrides. It targets **render-once** contexts; the streaming, interactive
+ * `<FluxMarkdown>` (client-side code highlighting, Mermaid, live updates) is a
+ * separate component. If you SSR-then-hydrate, use the *same* component on both
+ * sides.
+ */
+
+let ready = false;
+
+/** Has the sync WASM core been initialized in this process? */
+export function isFluxReady(): boolean {
+  return ready;
+}
+
+/** Initialize the sync core from compiled WASM bytes (or a `WebAssembly.Module`).
+ *  Idempotent. Use on runtimes without a filesystem (edge) or to control exactly
+ *  when init happens; otherwise {@link initFlux} auto-loads the co-located WASM. */
+export function initFluxSync(wasm: BufferSource | WebAssembly.Module): void {
+  if (ready) return;
+  initSync({ module: wasm });
+  ready = true;
+}
+
+let initPromise: Promise<void> | null = null;
+
+/** Initialize the sync core once. In Node it reads the package's co-located
+ *  `.wasm` off disk (Node's `fetch` can't load `file://`); on the web it fetches
+ *  the bundler-resolved asset URL. Pass `{ wasm }` to supply bytes yourself
+ *  (edge runtimes). Safe to call repeatedly / concurrently. */
+export function initFlux(opts?: { wasm?: BufferSource | WebAssembly.Module }): Promise<void> {
+  if (ready) return Promise.resolve();
+  if (opts?.wasm) {
+    initFluxSync(opts.wasm);
+    return Promise.resolve();
+  }
+  if (!initPromise) {
+    initPromise = (async () => {
+      const wasmUrl = new URL("./wasm/flux_md_core_bg.wasm", import.meta.url);
+      if (wasmUrl.protocol === "file:") {
+        // Node: read the bytes (Node's fetch can't load file://). A non-literal
+        // specifier keeps `node:fs` out of web bundles and off tsc's module graph
+        // (no @types/node needed to compile this source).
+        const nodeFs = "node:fs/promises";
+        const { readFile } = await import(nodeFs);
+        initFluxSync(await readFile(wasmUrl));
+      } else {
+        await initWasmAsync({ module_or_path: wasmUrl });
+        ready = true;
+      }
+    })();
+  }
+  return initPromise;
+}
+
+// Configure a one-shot parser exactly as the worker does, so server output is
+// byte-identical to the streamed/browser output (defaults: autolinks + alerts
+// on, raw HTML escaped, footnotes/math off).
+function makeParser(config?: ParserConfig): FluxParser {
+  const p = new FluxParser();
+  p.setGfmAutolinks(config?.gfmAutolinks ?? true);
+  p.setGfmAlerts(config?.gfmAlerts ?? true);
+  p.setGfmFootnotes(config?.gfmFootnotes ?? false);
+  p.setGfmMath(config?.gfmMath ?? false);
+  p.setDirAuto(config?.dirAuto ?? false);
+  p.setA11y(config?.a11y ?? false);
+  p.setUnsafeHtml(config?.unsafeHtml ?? false);
+  p.setComponentTags(config?.componentTags ?? []);
+  p.setInlineComponentTags(config?.inlineComponentTags ?? []);
+  // Engage the safe raw-HTML sanitizer when either list is provided (even []).
+  p.setHtmlSanitize(
+    config?.htmlAllowlist !== undefined || config?.dropHtmlTags !== undefined,
+    config?.htmlAllowlist ?? [],
+    config?.dropHtmlTags ?? [],
+  );
+  p.setBlockData(config?.blockData ?? false);
+  return p;
+}
+
+function requireReady(): void {
+  if (!ready) {
+    throw new Error(
+      "flux-md/server: WASM not initialized. Call `await initFlux()` (or `initFluxSync(bytes)`) once before rendering.",
+    );
+  }
+}
+
+/**
+ * Parse a complete markdown string to its block array synchronously (committed +
+ * any trailing block, in document order). Requires {@link initFlux} to have run.
+ */
+export function parseToBlocks(markdown: string, opts?: { config?: ParserConfig }): Block[] {
+  requireReady();
+  const p = makeParser(opts?.config);
+  try {
+    p.append(markdown);
+    p.finalize();
+    return p.allBlocks() as Block[];
+  } finally {
+    p.free();
+  }
+}
+
+/**
+ * Render a complete markdown string to an HTML string synchronously — no worker,
+ * no React. The concatenated per-block HTML (XSS-safe with `unsafeHtml` off).
+ * For component dispatch / a `<FluxMarkdown>`-matching React tree, use
+ * {@link FluxMarkdownStatic} with your framework's server renderer instead.
+ */
+export function renderToString(markdown: string, opts?: { config?: ParserConfig }): string {
+  return parseToBlocks(markdown, opts)
+    .map((b) => b.html)
+    .join("");
+}
+
+// Hookless block renderer (RSC-safe): mirrors the client renderer's dispatch
+// (block-kind overrides, a Component block dispatched by tag, tag-level overrides
+// via htmlToReact) but uses no hooks and skips the client-only interactive
+// renderers (Mermaid; client-side code highlighting) — those activate on the
+// client after hydration. Kept in step with react.tsx's renderBlockContent.
+function renderStaticBlock(block: Block, components?: Components): ReactNode {
+  const kind = block.kind.type;
+  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, { key: block.id, ...blockKindProps(block, components) });
+    }
+    const blockOverride = components[kind];
+    if (blockOverride) return createElement(blockOverride, { key: block.id, ...blockKindProps(block, components) });
+  }
+  const className =
+    "flux-block flux-block-" +
+    kind.toLowerCase() +
+    (block.open ? " flux-open" : "") +
+    (block.speculative ? " flux-speculative" : "");
+  if (components) {
+    return createElement("div", { key: block.id, className }, htmlToReact(block.html, components));
+  }
+  return createElement("div", { key: block.id, className, dangerouslySetInnerHTML: { __html: block.html } });
+}
+
+interface FluxMarkdownStaticProps {
+  /** The complete markdown to render (server/static use is for finished content). */
+  content: string;
+  /** Parser config (same shape as the streaming client's). */
+  config?: ParserConfig;
+  /** Tag-level / block-kind / component-tag overrides (see {@link Components}). */
+  components?: Components;
+  /** 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"`). */
+  role?: string;
+  /** Make the root a live region (parity with `<FluxMarkdown>` if you hydrate). */
+  "aria-live"?: "off" | "polite" | "assertive";
+  /** Live-region atomicity; pair with `aria-live`. */
+  "aria-atomic"?: boolean;
+}
+
+/**
+ * Synchronous, worker-free React rendering of finished markdown — a React Server
+ * Component, or any one-shot SSR / static render. Emits the `flux-md` root +
+ * per-block structure with the same `components` overrides (inline/block
+ * component tags dispatch here too). Requires {@link initFlux} (or
+ * {@link initFluxSync}) to have run. Uses no hooks (RSC-safe). A **render-once**
+ * component: for live streaming, client-side code highlighting, or Mermaid use
+ * the client `<FluxMarkdown>` instead (and if you SSR-then-hydrate, render the
+ * *same* component on both sides).
+ */
+export function FluxMarkdownStatic({
+  content,
+  config,
+  components,
+  className,
+  id,
+  role,
+  "aria-live": ariaLive,
+  "aria-atomic": ariaAtomic,
+}: FluxMarkdownStaticProps): ReactNode {
+  const blocks = parseToBlocks(content, { config });
+  const comps = components && Object.keys(components).length > 0 ? components : undefined;
+  return createElement(
+    "div",
+    {
+      className: className ? `flux-md ${className}` : "flux-md",
+      id,
+      role,
+      "aria-live": ariaLive,
+      "aria-atomic": ariaAtomic,
+    },
+    blocks.map((b) => renderStaticBlock(b, comps)),
+  );
+}

package/src/types-core.ts

@@ -116,8 +116,25 @@ export interface Patch {
 export interface BlockComponentProps {
   /** The full parsed block, including `kind` (with `kind.data`) and offsets. */
   block: Block;
-  /** Rendered, XSS-safe HTML for this block. */
+  /**
+   * Rendered, XSS-safe HTML for this block. For `Component` blocks this is the
+   * **inner** rendered-markdown HTML (not the `<tag>…</tag>` wrapper). NOTE: a
+   * `Component` override that ignores both `html` and `children` renders empty —
+   * use {@link children} (the easy path) or `dangerouslySetInnerHTML={{__html:
+   * html}}`.
+   */
   html: string;
+  /**
+   * React only: this block's inner content already parsed to a React node tree
+   * (markdown rendered, nested tag/inline-component overrides applied). For a
+   * `Component` block it is the inner markdown — render it directly
+   * (`return <Chip {...attrs}>{children}</Chip>`) instead of dangerously setting
+   * `html`. Populated by `<FluxMarkdown>` / `<FluxMarkdownStatic>` when a
+   * `components` map is supplied; DOM and other bindings leave it `undefined`
+   * (they consume `html`). Typed `unknown` to keep this surface framework-neutral
+   * — cast to `ReactNode` in a React override.
+   */
+  children?: unknown;
   /** True while the block is still streaming (its HTML may still change). */
   open: boolean;
   /** True if the block was closed speculatively and may yet be revised. */
@@ -229,6 +246,41 @@ export interface ParserConfig {
    * off. Names match case-sensitively.
    */
   componentTags?: string[];
+  /**
+   * Opt-in allowlist of INLINE component tag names (e.g. `["tik", "cite"]`). An
+   * allowlisted `<tik>…</tik>` (or self-closing `<tik/>`) anywhere in inline
+   * content — paragraphs, headings, table cells, list items — renders as a real
+   * custom element with **markdown** inner content and sanitized attributes
+   * (event handlers dropped, dangerous URL schemes neutralized) — XSS-safe
+   * without `unsafeHtml`. The React renderer dispatches it via `components[tag]`,
+   * with the inner markdown as the component's `children` and the sanitized
+   * attributes as props. Separate from `componentTags` (block containers): list a
+   * tag here for inline chips (tickers, citations, @mentions), or in both lists
+   * to allow both positions. Names match **case-sensitively** and dispatch
+   * verbatim to `components[tag]` (e.g. `"Cite"` → `components.Cite`), same as
+   * `componentTags`. Empty/omitted = off.
+   */
+  inlineComponentTags?: string[];
+  /**
+   * Opt-in **safe raw-HTML allowlist**. Setting this (even to `[]`) engages a
+   * sanitizer that renders a safe subset of *inline* raw HTML **without**
+   * `unsafeHtml`: an **empty** array means "allow all tags except a built-in
+   * dangerous set" (`script`, `style`, `iframe`, `object`, `embed`, `form`,
+   * `input`, `svg`, …); a **non-empty** array renders only those tags (e.g.
+   * `["br","sub","sup"]`) and escapes the rest. Every rendered tag's attributes
+   * are sanitized (event handlers dropped, dangerous URL schemes → `#`), and HTML
+   * comments are dropped. Block-level raw HTML stays escaped (sanitize is
+   * inline-scoped for now). Unset/omitted = off (raw HTML handling unchanged).
+   * Matching is case-insensitive. See also {@link dropHtmlTags}.
+   */
+  htmlAllowlist?: string[];
+  /**
+   * Tags removed entirely (markup dropped; any text between an open/close pair
+   * stays as inert text) — e.g. app marker tags, or belt-and-suspenders
+   * `["script","style"]`. Setting this (even to `[]`) also engages the safe
+   * raw-HTML sanitizer (see {@link htmlAllowlist}). Case-insensitive.
+   */
+  dropHtmlTags?: 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

package/src/wasm/flux_md_core.d.ts

@@ -4,6 +4,13 @@
 export class FluxParser {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * All blocks currently parsed (committed + active), in document order — the
+     * whole rendered document as a JS array of `Block`. The one-shot /
+     * server-side render primitive: feed the full markdown via `append`, call
+     * `finalize`, then read `allBlocks()` (no worker, no patch accumulation).
+     */
+    allBlocks(): any;
     append(chunk: string): any;
     bufferLen(): number;
     finalize(): any;
@@ -64,6 +71,23 @@ export class FluxParser {
      * `<div class="math math-display">` for a KaTeX pass on the JS side.
      */
     setGfmMath(on: boolean): void;
+    /**
+     * Engage the safe raw-HTML sanitizer. When `on`, inline raw HTML renders
+     * sanitized without full unsafe HTML: `allow` empty = allow all tags except
+     * a built-in dangerous set (`script`, `style`, `iframe`, …); `allow`
+     * non-empty = only those render (others escaped); `drop` tags are removed
+     * entirely; HTML comments are dropped; every rendered tag's attributes are
+     * sanitized. Off by default (raw-HTML handling unchanged).
+     */
+    setHtmlSanitize(on: boolean, allow: string[], drop: string[]): void;
+    /**
+     * Set the opt-in INLINE component-tag allowlist (e.g. `["tik", "cite"]`).
+     * An allowlisted inline `<tik>…</tik>` (or self-closing `<tik/>`) renders as
+     * a custom element (markdown inner, sanitized attributes) so a JSX/DOM layer
+     * can dispatch it via `components[tag]` — in paragraphs, headings, table
+     * cells, and list items. Empty by default (inline output unchanged).
+     */
+    setInlineComponentTags(tags: string[]): void;
     /**
      * Enable or disable raw-HTML pass-through. Default off. Do not enable
      * when rendering untrusted input — bypasses XSS protection.
@@ -76,6 +100,7 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_fluxparser_free: (a: number, b: number) => void;
+    readonly fluxparser_allBlocks: (a: number, b: number) => void;
     readonly fluxparser_append: (a: number, b: number, c: number, d: number) => void;
     readonly fluxparser_bufferLen: (a: number) => number;
     readonly fluxparser_finalize: (a: number, b: number) => void;
@@ -89,6 +114,8 @@ export interface InitOutput {
     readonly fluxparser_setGfmAutolinks: (a: number, b: number) => void;
     readonly fluxparser_setGfmFootnotes: (a: number, b: number) => void;
     readonly fluxparser_setGfmMath: (a: number, b: number) => void;
+    readonly fluxparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly fluxparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
     readonly fluxparser_setUnsafeHtml: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;

package/src/wasm/flux_md_core.js

@@ -11,6 +11,28 @@ export class FluxParser {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_fluxparser_free(ptr, 0);
     }
+    /**
+     * All blocks currently parsed (committed + active), in document order — the
+     * whole rendered document as a JS array of `Block`. The one-shot /
+     * server-side render primitive: feed the full markdown via `append`, call
+     * `finalize`, then read `allBlocks()` (no worker, no patch accumulation).
+     * @returns {any}
+     */
+    allBlocks() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.fluxparser_allBlocks(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * @param {string} chunk
      * @returns {any}
@@ -149,6 +171,37 @@ export class FluxParser {
     setGfmMath(on) {
         wasm.fluxparser_setGfmMath(this.__wbg_ptr, on);
     }
+    /**
+     * Engage the safe raw-HTML sanitizer. When `on`, inline raw HTML renders
+     * sanitized without full unsafe HTML: `allow` empty = allow all tags except
+     * a built-in dangerous set (`script`, `style`, `iframe`, …); `allow`
+     * non-empty = only those render (others escaped); `drop` tags are removed
+     * entirely; HTML comments are dropped; every rendered tag's attributes are
+     * sanitized. Off by default (raw-HTML handling unchanged).
+     * @param {boolean} on
+     * @param {string[]} allow
+     * @param {string[]} drop
+     */
+    setHtmlSanitize(on, allow, drop) {
+        const ptr0 = passArrayJsValueToWasm0(allow, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArrayJsValueToWasm0(drop, wasm.__wbindgen_export);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.fluxparser_setHtmlSanitize(this.__wbg_ptr, on, ptr0, len0, ptr1, len1);
+    }
+    /**
+     * Set the opt-in INLINE component-tag allowlist (e.g. `["tik", "cite"]`).
+     * An allowlisted inline `<tik>…</tik>` (or self-closing `<tik/>`) renders as
+     * a custom element (markdown inner, sanitized attributes) so a JSX/DOM layer
+     * can dispatch it via `components[tag]` — in paragraphs, headings, table
+     * cells, and list items. Empty by default (inline output unchanged).
+     * @param {string[]} tags
+     */
+    setInlineComponentTags(tags) {
+        const ptr0 = passArrayJsValueToWasm0(tags, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.fluxparser_setInlineComponentTags(this.__wbg_ptr, ptr0, len0);
+    }
     /**
      * Enable or disable raw-HTML pass-through. Default off. Do not enable
      * when rendering untrusted input — bypasses XSS protection.

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

@@ -2,6 +2,7 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_fluxparser_free: (a: number, b: number) => void;
+export const fluxparser_allBlocks: (a: number, b: number) => void;
 export const fluxparser_append: (a: number, b: number, c: number, d: number) => void;
 export const fluxparser_bufferLen: (a: number) => number;
 export const fluxparser_finalize: (a: number, b: number) => void;
@@ -15,6 +16,8 @@ export const fluxparser_setGfmAlerts: (a: number, b: number) => void;
 export const fluxparser_setGfmAutolinks: (a: number, b: number) => void;
 export const fluxparser_setGfmFootnotes: (a: number, b: number) => void;
 export const fluxparser_setGfmMath: (a: number, b: number) => void;
+export const fluxparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const fluxparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
 export const fluxparser_setUnsafeHtml: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;

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.13.0",
+  "version": "0.15.0",
   "license": "MIT",
   "files": [
     "flux_md_core_bg.wasm",

package/src/worker.ts

@@ -30,6 +30,13 @@ const core = new WorkerCore({
     p.setA11y(c?.a11y ?? false);
     p.setUnsafeHtml(c?.unsafeHtml ?? false);
     p.setComponentTags(c?.componentTags ?? []);
+    p.setInlineComponentTags(c?.inlineComponentTags ?? []);
+    // Engage the safe raw-HTML sanitizer when either list is provided (even []).
+    p.setHtmlSanitize(
+      c?.htmlAllowlist !== undefined || c?.dropHtmlTags !== undefined,
+      c?.htmlAllowlist ?? [],
+      c?.dropHtmlTags ?? [],
+    );
     p.setBlockData(c?.blockData ?? false);
     return p;
   },