flux-md 0.12.0 → 0.14.0

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:") ||
@@ -106,7 +115,11 @@ 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 +206,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 +229,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;
@@ -242,7 +255,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 +275,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/index.ts

@@ -16,7 +16,7 @@
  *     client.finalize();
  */
 export { FluxClient, FluxPool, getDefaultPool } from "./client";
-export { FluxMarkdown } from "./react";
+export { FluxMarkdown, useFluxStream, useFluxMarkdownString } from "./react";
 export { highlight, supportedLangs } from "./hi";
 export { htmlToReact, parseTrustedHtml } from "./html-to-react";
 export type {

package/src/react.tsx

@@ -7,6 +7,7 @@ import {
   useState,
   useSyncExternalStore,
   type CSSProperties,
+  type ReactElement,
 } from "react";
 import type { Block, BlockComponentProps, Components, HeadingData, TableData } from "./types";
 import { FluxClient } from "./client";
@@ -209,6 +210,52 @@ export function useFluxStream(
   return client;
 }
 
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the bridge for
+ * UIs that hold a streaming message as a single growing string prop (the common
+ * React shape) rather than as a stream. Pass the whole document-so-far on each
+ * render and {@link FluxClient.setContent} diffs it: a prefix-extension appends
+ * only the delta; any divergence (e.g. the finished text swapped for a
+ * re-processed final string) resets and reparses. Returns the owned client —
+ * pass it to `<FluxMarkdown client={…} />` (and read `outline()` etc.).
+ *
+ * Pass `streaming: false` once the content is final to finalize the stream and
+ * commit its last block (only then does a finished code fence highlight + show
+ * its copy button). If `streaming` is omitted or `true` the stream is left OPEN
+ * — right for a still-growing string, but a *complete static* string rendered as
+ * `useFluxMarkdownString(md)` keeps its last block in the streaming state until
+ * you pass `{ streaming: false }`. (Inferring "done" from an absent flag is
+ * deliberately avoided: it would re-finalize on every token for callers that
+ * grow the string without the flag — an O(n²) reparse trap.) The client is
+ * created once and destroyed on unmount; StrictMode's dev double-mount is handled
+ * (reattach re-feeds the document). For a true stream source
+ * (`Response` / `ReadableStream` / SSE generator) use {@link useFluxStream}
+ * instead — it avoids buffering the whole document as a string.
+ */
+export function useFluxMarkdownString(
+  content: string,
+  options?: { config?: ParserConfig; streaming?: boolean },
+): FluxClient {
+  const [client] = useState(() => new FluxClient({ config: options?.config }));
+
+  // Own the client's pool attachment (StrictMode dev double-mount destroys on the
+  // simulated unmount then remounts the SAME instance; reattach re-registers and
+  // clears setContent's diff baseline so the document is re-fed). Destroy on the
+  // real unmount.
+  useEffect(() => {
+    client.reattach();
+    return () => client.destroy();
+  }, [client]);
+
+  // Reconcile the parser to the controlled string. setContent diffs internally,
+  // so this stays correct whether `content` grows by a token or is swapped wholesale.
+  useEffect(() => {
+    client.setContent(content, { done: options?.streaming === false });
+  }, [client, content, options?.streaming]);
+
+  return client;
+}
+
 // Stream mode: own a client via the hook, then render the normal client path.
 function FluxMarkdownFromStream(props: FluxMarkdownProps) {
   const client = useFluxStream(props.stream, {
@@ -261,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,
@@ -296,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
@@ -336,7 +387,10 @@ function componentInnerHtml(html: string, tag: string): string {
 
 /** 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;
+  // `ReactElement` (not the global `JSX.Element`) so the source type-checks under
+  // both @types/react 18 and 19 — React 19 removed the global `JSX` namespace,
+  // and a consumer's `next build` type-checks this shipped source.
+  return useMemo(() => htmlToReact(html, components), [html, components]) as ReactElement;
 }
 
 // Per-kind off-screen size estimate for `contain-intrinsic-size` — keeps the
@@ -390,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));
     }
   }
 
@@ -419,12 +473,20 @@ function renderBlockContent({
     (block.open ? " flux-open" : "") +
     (block.speculative ? " flux-speculative" : "");
 
-  // Tag-level overrides only apply to a settled block (open/speculative blocks
-  // have partial HTML we must not feed to the parser).
-  if (components && !block.open && !block.speculative) {
+  // Tag-level / inline overrides apply to OPEN and speculative blocks too, not
+  // just settled ones: the streaming tail's HTML is always well-formed (the
+  // parser speculatively closes it), so a design-system renderer (Tailwind
+  // classes on p/ul/li, inline <a>/<code> overrides) stays styled mid-stream
+  // instead of only after a block commits. A supplied `sanitize` runs FIRST
+  // (same as the innerHTML path below), so overrides compose with sanitization on
+  // every block — closing the gap where a component-rendered block previously
+  // bypassed the user sanitizer. The no-`components` fast path is untouched
+  // (byte-identical innerHTML).
+  if (components) {
+    const safe = sanitize ? sanitize(block.html) : block.html;
     return (
       <div className={className}>
-        <SafeHtml html={block.html} components={components} />
+        <SafeHtml html={safe} components={components} />
       </div>
     );
   }

package/src/server.tsx

@@ -0,0 +1,209 @@
+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 ?? []);
+  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/solid.tsx

@@ -1,5 +1,6 @@
-import { onCleanup, onMount, type JSX } from "solid-js";
-import type { FluxClient } from "./client";
+import { createEffect, onCleanup, onMount, type JSX } from "solid-js";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { mountFluxMarkdown, type MountHandle, type MountOptions } from "./dom";
 
 /**
@@ -73,3 +74,72 @@ export function FluxMarkdown(props: FluxMarkdownProps): JSX.Element {
   onMount(() => mountSolid(() => props, container, onCleanup));
   return container;
 }
+
+/**
+ * Wire a controlled string to a freshly-constructed {@link FluxClient}, free of
+ * Solid's reactive runtime so it runs (and is tested) under any toolchain. The
+ * registrars are injected: the public {@link createFluxMarkdownString} passes
+ * Solid's real `createEffect` / `onCleanup`; tests pass hand-rolled stand-ins
+ * (mirroring how {@link mountSolid} takes `registerCleanup`).
+ *
+ * Ownership DIFFERS from {@link mountSolid}: this constructs the client and so
+ * `registerCleanup`s `client.destroy()` — it OWNS the worker/stream. `config` is
+ * read ONCE here (the constructor treats it as immutable); `getContent()` and
+ * `streaming` are read INSIDE the effect so the effect tracks them reactively.
+ */
+export function setupFluxMarkdownString(
+  getContent: () => string,
+  getOptions: (() => { config?: ParserConfig; streaming?: boolean }) | undefined,
+  registerEffect: (fn: () => void) => void,
+  registerCleanup: (fn: () => void) => void,
+): FluxClient {
+  // One client per helper instance. Constructor is worker-free → SSR-safe; the
+  // worker is spawned lazily by the first setContent → append, which only runs
+  // inside the effect below. config is read once and is immutable thereafter.
+  const client = new FluxClient({ config: getOptions?.()?.config });
+
+  // Reconcile the parser to the controlled string. setContent diffs internally,
+  // so this is correct whether `content` grows by a token or is swapped wholesale.
+  // `streaming === false` (never `!streaming`) → only an explicit false finalizes;
+  // an absent/true flag leaves the stream open (inferring "done" from an absent
+  // flag would re-finalize on every token — an O(n²) reparse trap).
+  registerEffect(() => {
+    client.setContent(getContent(), { done: getOptions?.()?.streaming === false });
+  });
+
+  // This helper OWNS the client (unlike the client-based bindings above), so it
+  // destroys it on cleanup — freeing its pool slot.
+  registerCleanup(() => client.destroy());
+
+  return client;
+}
+
+/**
+ * Own a {@link FluxClient} driven by a CONTROLLED full string — the Solid
+ * analogue of React's `useFluxMarkdownString`, for UIs that hold a streaming
+ * message as a single growing string (a signal/memo) rather than as a stream.
+ * Pass an accessor for the whole document-so-far; on every change
+ * {@link FluxClient.setContent} diffs it and does the minimal work (a
+ * prefix-extension appends only the delta; any divergence resets and reparses).
+ *
+ * Pass `streaming: false` (via `getOptions`) once the content is final to
+ * finalize the stream and commit its last block (only then does a finished code
+ * fence highlight + show its copy button). If `streaming` is omitted or `true`
+ * the stream is left OPEN. `config` is read once at construction and is
+ * immutable, so it is not a change trigger.
+ *
+ * **Returns the owned client** — pass it to `<FluxMarkdown client={client} />`
+ * (and read `outline()` / `getMetrics()` off it). The client is constructed in
+ * the body (constructor is worker-free → SSR-safe) and destroyed on cleanup.
+ *
+ * SSR-safety: `setContent` is what spawns a Worker (via `append`), so it runs
+ * ONLY inside a `createEffect` — Solid does not run user effects during
+ * `renderToString`, so nothing touches a Worker on the server render path (the
+ * body only constructs the worker-free client).
+ */
+export function createFluxMarkdownString(
+  getContent: () => string,
+  getOptions?: () => { config?: ParserConfig; streaming?: boolean },
+): FluxClient {
+  return setupFluxMarkdownString(getContent, getOptions, createEffect, onCleanup);
+}

package/src/svelte.ts

@@ -1,5 +1,6 @@
 import type { ActionReturn } from "svelte/action";
-import type { FluxClient } from "./client";
+import { FluxClient } from "./client";
+import type { ParserConfig } from "./types-core";
 import { mountFluxMarkdown, type DomComponents, type MountOptions } from "./dom";
 
 /**
@@ -53,3 +54,101 @@ export function fluxMarkdown(
     },
   };
 }
+
+/**
+ * Controlled-string sibling of {@link fluxMarkdown}: instead of taking a
+ * caller-owned client, this action OWNS a single {@link FluxClient} (constructed
+ * from `config`) and drives it from a CONTROLLED full string — the bridge for
+ * Svelte UIs that hold a streaming message as one growing `content` prop rather
+ * than feeding the client by hand. Each update passes the whole document-so-far
+ * and {@link FluxClient.setContent} diffs it: a prefix-extension appends only the
+ * delta; any divergence resets and reparses.
+ *
+ * ```svelte
+ * <div use:fluxMarkdownString={{ content, streaming: !done }} />
+ * ```
+ *
+ * Pass `streaming: false` once the content is final to finalize the stream and
+ * commit its last block (only then does a finished code fence highlight + show
+ * its copy button). When `streaming` is omitted or `true` the stream is left
+ * OPEN — right for a still-growing string, but a *complete static* string keeps
+ * its last block in the streaming state until you pass `{ streaming: false }`.
+ * (Inferring "done" from an absent flag is deliberately avoided — it would
+ * re-finalize on every token and trip an O(n²) reparse.)
+ *
+ * SSR-safe by construction: a Svelte action runs ONLY in the browser, and the
+ * `FluxClient` constructor is worker-free — the first worker is spawned lazily by
+ * `setContent`, which only runs here (never during a server render).
+ *
+ * Lifecycle differs from {@link fluxMarkdown}: this action constructs the client
+ * once (a later `config` change is ignored, like a created-once instance) and
+ * `destroy()`s it on teardown — it OWNS the client. The mount-option reconcile
+ * (`components`/`sanitize`/`virtualize`/`stickToBottom`) matches `fluxMarkdown`,
+ * but the remount reuses the SAME client so its `setContent` diff baseline
+ * survives.
+ */
+export interface FluxMarkdownStringParams extends Omit<FluxMarkdownParams, "client"> {
+  /** The full document-so-far. Diffed against the prior value on every update. */
+  content: string;
+  /** Leave the stream open while true/omitted; `false` finalizes (commits the tail). */
+  streaming?: boolean;
+  /** Per-stream parser flags. Applied once at construction; later changes are ignored. */
+  config?: ParserConfig;
+}
+
+/** Strip the action-only inputs (`content`/`streaming`/`config`), leaving the
+ *  fields {@link mountFluxMarkdown} reads — so they never leak into the mount. */
+function mountOptionsOf(p: FluxMarkdownStringParams): Omit<FluxMarkdownParams, "client"> {
+  const { content: _c, streaming: _s, config: _cfg, ...rest } = p;
+  void _c;
+  void _s;
+  void _cfg;
+  return rest;
+}
+
+export function fluxMarkdownString(
+  node: HTMLElement,
+  params: FluxMarkdownStringParams,
+): ActionReturn<FluxMarkdownStringParams> {
+  // This action OWNS the client — construct it once from `config` (a later
+  // `config` change is ignored, mirroring the created-once React hook). The
+  // content/streaming diff baseline lives INSIDE the client (setContent), so we
+  // keep no outer copy; only the mount-option fields are tracked for the remount
+  // comparison.
+  let options = mountOptionsOf(params);
+  const client = new FluxClient({ config: params.config });
+  let handle = mountFluxMarkdown(client, node, options as MountOptions);
+  // First worker-bound op: spawns the lazy Worker — browser-only, never SSR.
+  client.setContent(params.content, { done: params.streaming === false });
+
+  return {
+    update(next: FluxMarkdownStringParams) {
+      // Content/streaming are the primary changing inputs, so reconcile them on
+      // EVERY update — setContent self-no-ops when the string is unchanged, so
+      // this is cheap. (Unlike fluxMarkdown, we cannot early-return: that would
+      // swallow content updates.)
+      client.setContent(next.content, { done: next.streaming === false });
+
+      // Then reconcile mount options exactly like fluxMarkdown: remount only when
+      // a field the renderer reads actually changed identity, and reuse the SAME
+      // client so its setContent diff baseline (lastContent) survives the remount.
+      if (
+        next.components === options.components &&
+        next.sanitize === options.sanitize &&
+        next.virtualize === options.virtualize &&
+        next.stickToBottom === options.stickToBottom
+      ) {
+        return;
+      }
+      handle.destroy();
+      options = mountOptionsOf(next);
+      handle = mountFluxMarkdown(client, node, options as MountOptions);
+    },
+    destroy() {
+      // This action OWNS the client (unlike fluxMarkdown) — tear down the mount
+      // AND destroy the client so its pool slot is freed.
+      handle.destroy();
+      client.destroy();
+    },
+  };
+}

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,21 @@ 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 structured table data. When on, a `Table` block's `kind.data` is
    * populated with `{ headers, rows, aligns }` (each cell `{ text, html }`) so a