flux-md 0.5.5 → 0.6.0

package/src/element.ts

@@ -0,0 +1,339 @@
+import { FluxClient } from "./client";
+import { mountFluxMarkdown, type DomComponents, type MountHandle } from "./dom";
+import type { ParserConfig } from "./types-core";
+
+/**
+ * `<flux-markdown>` custom element — thin lifecycle glue over
+ * {@link mountFluxMarkdown}. It owns no diffing: connect mounts the DOM
+ * renderer into the element itself (LIGHT DOM, so the host app's markdown CSS
+ * reaches the content), disconnect tears the mount down. It never reimplements
+ * subscribe/patch.
+ *
+ * Two usage modes:
+ *   - **Caller-owned client** (`el.client = myClient`): the element subscribes
+ *     and mounts but NEVER destroys the client — the caller owns the
+ *     worker/stream lifecycle.
+ *   - **Self-owned client** (`markdown`/`src`/`textContent` attrs, or
+ *     `el.append()`): the element lazily creates an internal client from its
+ *     config attributes and destroys it on disconnect.
+ *
+ * Not auto-registered (SSR-unsafe): call {@link defineFluxMarkdown} from
+ * browser code.
+ */
+
+// Tri-state attribute parse: absent => undefined (omit, library default);
+// ""/"true"/"1" => true; "false"/"0" => false. Tri-state is the only way to
+// turn OFF a flag whose library default is on (autolinks, alerts). Exported so
+// it is directly unit-testable.
+export function parseTriBool(value: string | null): boolean | undefined {
+  if (value === null) return undefined;
+  if (value === "" || value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  return undefined;
+}
+
+const CONFIG_ATTRS = [
+  "gfm-autolinks",
+  "gfm-alerts",
+  "gfm-footnotes",
+  "gfm-math",
+  "dir-auto",
+  "unsafe-html",
+];
+
+export function defineFluxMarkdown(tag = "flux-markdown"): void {
+  // SSR-safe: no custom-element registry => nothing to define.
+  if (typeof customElements === "undefined") return;
+  // Idempotent: a tag may only be defined once.
+  if (customElements.get(tag)) return;
+
+  // The class is defined lazily INSIDE the function: at module-evaluation time
+  // `HTMLElement` may not exist (SSR / pre-DOM). Referencing it only after the
+  // guards above keeps the module import side-effect-free.
+  class FluxMarkdownElement extends HTMLElement {
+    static get observedAttributes(): string[] {
+      return ["markdown", "src", "component-tags", ...CONFIG_ATTRS];
+    }
+
+    #client: FluxClient | null = null;
+    #ownsClient = false;
+    #components: DomComponents | undefined = undefined;
+    #sanitize: ((html: string) => string) | undefined = undefined;
+    #handle: MountHandle | null = null;
+    #connected = false;
+
+    // --- Accessor properties (objects/functions can't be attributes) ---------
+
+    get client(): FluxClient | null {
+      return this.#client;
+    }
+    set client(value: FluxClient | null) {
+      if (value === this.#client) return;
+      // Switching to a caller-owned client: tear down any internal client we own
+      // first, then adopt the new one without owning it.
+      this.#teardownClient();
+      this.#client = value;
+      this.#ownsClient = false;
+      if (this.#connected) this.#remount();
+    }
+
+    get components(): DomComponents | undefined {
+      return this.#components;
+    }
+    set components(value: DomComponents | undefined) {
+      this.#components = value;
+      if (this.#connected) this.#remount();
+    }
+
+    get sanitize(): ((html: string) => string) | undefined {
+      return this.#sanitize;
+    }
+    set sanitize(value: ((html: string) => string) | undefined) {
+      this.#sanitize = value;
+      if (this.#connected) this.#remount();
+    }
+
+    // --- Self-owned-client methods -------------------------------------------
+
+    append(chunk: string): void {
+      this.#ensureClient();
+      this.#client!.append(chunk);
+    }
+
+    finalize(): void {
+      // Only meaningful for a self-owned stream; a no-op if no client yet.
+      this.#client?.finalize();
+    }
+
+    reset(): void {
+      // Keep config; just clear the current stream's blocks.
+      this.#client?.reset();
+    }
+
+    getClient(): FluxClient | null {
+      return this.#client;
+    }
+
+    // --- Lifecycle -----------------------------------------------------------
+
+    connectedCallback(): void {
+      // Guard double-connect; allow reconnect-after-move.
+      if (this.#connected) return;
+      this.#connected = true;
+
+      // Property-upgrade dance: a framework may set `el.client`/`components`/
+      // `sanitize` BEFORE the element is upgraded, leaving an own data property
+      // that shadows the accessor. Capture, delete, re-assign through the setter.
+      this.#upgradeProperty("client");
+      this.#upgradeProperty("components");
+      this.#upgradeProperty("sanitize");
+
+      // Mount synchronously if we already have a client (caller-owned, or one a
+      // pre-connect append() created). append/finalize are postMessage and the
+      // config rides the first message FIFO, so no whenReady await is needed.
+      this.#mountIfReady();
+
+      // Resolve initial content for self-owned mode only (no caller client).
+      if (!this.#client || this.#ownsClient) {
+        this.#resolveInitialContent();
+      }
+    }
+
+    attributeChangedCallback(name: string, _old: string | null, _new: string | null): void {
+      // attributeChangedCallback fires before connectedCallback for attributes
+      // present at upgrade; ignore until connected so config reads happen once.
+      if (!this.#connected) return;
+
+      if (name === "markdown" || name === "src") {
+        // One-shot content source change — only for a self-owned client. A
+        // caller-owned client is driven by its owner, not by our attributes.
+        if (!this.#client || this.#ownsClient) {
+          this.#resolveInitialContent();
+        }
+        return;
+      }
+
+      // A config / component-tags change. ParserConfig is immutable per stream.
+      if (this.#client && !this.#ownsClient) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          "<flux-markdown>: config attributes are ignored while a caller-owned `client` is set (ParserConfig is immutable per stream).",
+        );
+        return;
+      }
+      // Self-owned: rebuild the client with fresh config, then re-render.
+      if (this.#ownsClient) {
+        this.#teardownClient();
+        this.#mountIfReady();
+        this.#resolveInitialContent();
+      }
+    }
+
+    disconnectedCallback(): void {
+      this.#connected = false;
+      // ALWAYS tear down the mount (the only teardown path for the renderer).
+      this.#handle?.destroy();
+      this.#handle = null;
+      // Destroy the client ONLY if we created it. A caller-owned client's
+      // worker/stream lifecycle belongs to the caller — never destroy it here.
+      if (this.#ownsClient) {
+        this.#client?.destroy();
+        this.#client = null;
+        this.#ownsClient = false;
+      }
+    }
+
+    // --- Internals -----------------------------------------------------------
+
+    #upgradeProperty(prop: "client" | "components" | "sanitize"): void {
+      if (Object.prototype.hasOwnProperty.call(this, prop)) {
+        const value = (this as unknown as Record<string, unknown>)[prop];
+        delete (this as unknown as Record<string, unknown>)[prop];
+        (this as unknown as Record<string, unknown>)[prop] = value;
+      }
+    }
+
+    // Build a ParserConfig from the current config attributes. Read ONCE, at
+    // client creation — config is immutable per stream.
+    #readConfig(): ParserConfig | undefined {
+      const cfg: ParserConfig = {};
+      let any = false;
+      const set = (attr: string, key: keyof ParserConfig): void => {
+        const v = parseTriBool(this.getAttribute(attr));
+        if (v !== undefined) {
+          (cfg as Record<string, unknown>)[key] = v;
+          any = true;
+        }
+      };
+      set("gfm-autolinks", "gfmAutolinks");
+      set("gfm-alerts", "gfmAlerts");
+      set("gfm-footnotes", "gfmFootnotes");
+      set("gfm-math", "gfmMath");
+      set("dir-auto", "dirAuto");
+      set("unsafe-html", "unsafeHtml");
+
+      const tags = this.getAttribute("component-tags");
+      if (tags !== null) {
+        const list = tags.split(/[\s,]+/).filter(Boolean);
+        if (list.length > 0) {
+          cfg.componentTags = list;
+          any = true;
+        }
+      }
+      return any ? cfg : undefined;
+    }
+
+    // Lazily create the internal client from config attributes (self-owned).
+    #ensureClient(): void {
+      if (this.#client) return;
+      this.#client = new FluxClient({ config: this.#readConfig() });
+      this.#ownsClient = true;
+      this.#mountIfReady();
+    }
+
+    // Mount once a client exists and we're connected. Idempotent.
+    #mountIfReady(): void {
+      if (!this.#connected || !this.#client || this.#handle) return;
+      this.#handle = mountFluxMarkdown(this.#client, this, {
+        components: this.#components,
+        sanitize: this.#sanitize,
+      });
+    }
+
+    // Destroy the current mount and remount against the current client+options.
+    // Used when a property changes while connected.
+    #remount(): void {
+      this.#handle?.destroy();
+      this.#handle = null;
+      this.#mountIfReady();
+    }
+
+    // Tear down only the client side (mount stays / is handled by the caller).
+    // Destroys the client only if self-owned, then clears it and the mount so
+    // the next mount targets a fresh client.
+    #teardownClient(): void {
+      this.#handle?.destroy();
+      this.#handle = null;
+      if (this.#ownsClient) this.#client?.destroy();
+      this.#client = null;
+      this.#ownsClient = false;
+    }
+
+    // Resolve the initial content of a self-owned stream from the attributes,
+    // in priority order: `src` (fetch+stream) > `markdown` (one-shot) >
+    // textContent (one-shot). A caller-owned client never reaches here.
+    #resolveInitialContent(): void {
+      const src = this.getAttribute("src");
+      if (src) {
+        void this.#streamFromSrc(src);
+        return;
+      }
+      const markdown = this.getAttribute("markdown");
+      if (markdown !== null) {
+        this.#oneShot(markdown);
+        return;
+      }
+      // textContent-as-initial-markdown: capture, clear, then feed. Capture
+      // BEFORE the mount appended its `.flux-md` root would pollute the text;
+      // mount happened in connectedCallback, so read only our own text nodes.
+      const text = this.#captureSourceText();
+      if (text.trim().length > 0) this.#oneShot(text);
+    }
+
+    // Read the raw markdown the host put between the tags, ignoring the
+    // renderer's `.flux-md` root (and any other element children).
+    #captureSourceText(): string {
+      let text = "";
+      for (const node of Array.from(this.childNodes)) {
+        if (node.nodeType === 3 /* Text */) {
+          text += node.textContent ?? "";
+          node.parentNode?.removeChild(node);
+        }
+      }
+      return text;
+    }
+
+    // One-shot: reset the stream (in case content changed), feed it, finalize.
+    #oneShot(markdown: string): void {
+      this.#ensureClient();
+      this.#client!.reset();
+      this.#client!.append(markdown);
+      this.#client!.finalize();
+    }
+
+    // Fetch a URL and stream its body. TextDecoder with {stream:true} carries a
+    // multibyte sequence that straddles a chunk boundary into the next decode.
+    async #streamFromSrc(src: string): Promise<void> {
+      this.#ensureClient();
+      this.#client!.reset();
+      const owned = this.#client!;
+      try {
+        const res = await fetch(src);
+        const body = res.body;
+        if (!body) {
+          owned.append(await res.text());
+          owned.finalize();
+          return;
+        }
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        for (;;) {
+          const { done, value } = await reader.read();
+          // The element may have been disconnected (and `owned` destroyed) or
+          // the client swapped mid-stream; stop feeding a stale client.
+          if (this.#client !== owned) return;
+          if (done) break;
+          if (value) owned.append(decoder.decode(value, { stream: true }));
+        }
+        if (this.#client !== owned) return;
+        owned.append(decoder.decode()); // flush any trailing partial sequence
+        owned.finalize();
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error("<flux-markdown>: failed to stream src", src, err);
+      }
+    }
+  }
+
+  customElements.define(tag, FluxMarkdownElement);
+}

package/src/renderers/CodeBlock.tsx

@@ -1,4 +1,4 @@
-import { memo, useMemo } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { highlight } from "../hi";
 
 /**
@@ -31,18 +31,75 @@ interface Props {
 
 function CodeBlockImpl({ html, open }: Props) {
   const lang = extractLang(html) || "text";
+  // Decode once: highlighter and copy handler share the same source.
+  const text = useMemo(() => (open ? "" : decodeText(html)), [html, open]);
   const highlighted = useMemo(() => {
-    if (open) return null;
-    const text = decodeText(html);
     if (!text) return null;
     return highlight(text, lang);
-  }, [html, open, lang]);
+  }, [text, lang]);
+
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Reset "Copied" if the block re-opens or its content changes underneath us.
+  useEffect(() => {
+    if (open) setCopied(false);
+  }, [open, html]);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const onCopy = useCallback(() => {
+    const write = (typeof navigator !== "undefined" && navigator.clipboard && navigator.clipboard.writeText)
+      ? navigator.clipboard.writeText.bind(navigator.clipboard)
+      : null;
+    if (!write || !text) return;
+    write(text).then(
+      () => {
+        setCopied(true);
+        if (timerRef.current !== null) clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => setCopied(false), 1500);
+      },
+      // Permission denied / blocked: stay silent, leave button usable.
+      () => {},
+    );
+  }, [text]);
 
   return (
     <div className={"flux-code-block" + (open ? " flux-streaming" : "")}>
       <div className="flux-code-header">
         <span className="flux-code-lang">{lang}</span>
-        {open && <span className="flux-code-streaming-pill">streaming</span>}
+        {open ? (
+          <span className="flux-code-streaming-pill">streaming</span>
+        ) : (
+          <button
+            type="button"
+            className="flux-code-copy"
+            onClick={onCopy}
+            aria-label={copied ? "Copied" : "Copy code"}
+            aria-live="polite"
+          >
+            {copied ? (
+              <>
+                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                  <path d="M20 6 9 17l-5-5" />
+                </svg>
+                <span>Copied</span>
+              </>
+            ) : (
+              <>
+                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+                  <rect x="9" y="9" width="11" height="11" rx="2" />
+                  <path d="M5 15V5a2 2 0 0 1 2-2h10" />
+                </svg>
+                <span>Copy</span>
+              </>
+            )}
+          </button>
+        )}
       </div>
       <div className="flux-code-body">
         {highlighted ? (

package/src/solid.tsx

@@ -0,0 +1,70 @@
+import { onCleanup, onMount, type JSX } from "solid-js";
+import type { FluxClient } from "./client";
+import { mountFluxMarkdown, type MountHandle, type MountOptions } from "./dom";
+
+/**
+ * Solid binding for the framework-neutral DOM renderer ({@link mountFluxMarkdown}).
+ *
+ * Deliberately thin lifecycle glue: it mounts the renderer once on `onMount` and
+ * tears it down on `onCleanup`. There is **no** `createEffect` — the DOM renderer
+ * owns its own `client.subscribe` loop and patches the container directly, so
+ * re-running mount on signal changes would thrash (double-subscribe, rebuild the
+ * tree). Props are read once as a non-reactive snapshot at mount time.
+ *
+ * Ownership: unmount calls `handle.destroy()` (unsubscribe + remove the renderer
+ * root) and never `client.destroy()`. The caller owns the worker/stream.
+ */
+
+export interface FluxMarkdownProps extends MountOptions {
+  client: FluxClient;
+  class?: string;
+  style?: JSX.CSSProperties | string;
+}
+
+/**
+ * Mount the DOM renderer and register its teardown — the testable core, free of
+ * JSX so it runs under any toolchain. `getProps` is read once (snapshot), the
+ * handle is returned so callers/tests can observe `destroy`, and the teardown is
+ * handed to `registerCleanup` (Solid's `onCleanup` at the call site).
+ */
+export function mountSolid(
+  getProps: () => FluxMarkdownProps,
+  container: HTMLElement,
+  registerCleanup: (fn: () => void) => void,
+): MountHandle {
+  const p = getProps();
+  // Explicit field copy (not rest-spread): keeps `client`/`class`/`style` out of
+  // MountOptions and threads `batch`/`highlightCode` straight through.
+  const handle = mountFluxMarkdown(p.client, container, {
+    components: p.components,
+    sanitize: p.sanitize,
+    virtualize: p.virtualize,
+    stickToBottom: p.stickToBottom,
+    highlightCode: p.highlightCode,
+    batch: p.batch,
+  });
+  registerCleanup(() => handle.destroy());
+  return handle;
+}
+
+/**
+ * The container `<div>` the DOM renderer mounts into. We do not set
+ * `class="flux-md"`: the renderer appends its own `.flux-md` root inside it.
+ *
+ * Authored imperatively rather than with a JSX literal: a JSX literal makes
+ * bun's transform inject an automatic-runtime import (`jsxDEV` from
+ * `solid-js/jsx-dev-runtime`) that Solid does not provide (Solid compiles JSX
+ * via dom-expressions, not a runtime), which breaks importing this module under
+ * bun. A real DOM node is a valid Solid `JSX.Element`; under a Solid build this
+ * is equivalent to `<div ref={container} class={props.class} style={props.style} />`.
+ */
+export function FluxMarkdown(props: FluxMarkdownProps): JSX.Element {
+  const container = document.createElement("div");
+  if (props.class) container.className = props.class;
+  if (typeof props.style === "string") container.setAttribute("style", props.style);
+  else if (props.style)
+    for (const [k, v] of Object.entries(props.style)) container.style.setProperty(k, String(v));
+  // Snapshot props once on mount; the renderer drives itself from here on.
+  onMount(() => mountSolid(() => props, container, onCleanup));
+  return container;
+}

package/src/svelte.ts

@@ -0,0 +1,55 @@
+import type { ActionReturn } from "svelte/action";
+import type { FluxClient } from "./client";
+import { mountFluxMarkdown, type DomComponents, type MountOptions } from "./dom";
+
+/**
+ * Svelte action that mounts a streaming {@link FluxClient} into the host node.
+ * Plain `.ts` — no `.svelte` compile step — so `use:` works unchanged in
+ * Svelte 4 and 5. The action owns only lifecycle: it mounts on creation and
+ * tears the mount down on destroy. The caller keeps ownership of the client
+ * (the worker/stream); the action never calls `client.destroy()`.
+ *
+ * ```svelte
+ * <div use:fluxMarkdown={{ client, stickToBottom: true }} />
+ * ```
+ */
+export interface FluxMarkdownParams {
+  client: FluxClient;
+  components?: DomComponents;
+  sanitize?: (h: string) => string;
+  virtualize?: boolean;
+  stickToBottom?: boolean;
+}
+
+export function fluxMarkdown(
+  node: HTMLElement,
+  params: FluxMarkdownParams,
+): ActionReturn<FluxMarkdownParams> {
+  let { client, ...options } = params;
+  let handle = mountFluxMarkdown(client, node, options as MountOptions);
+
+  return {
+    update(next: FluxMarkdownParams) {
+      // Svelte fires update on every params change, even when nothing the mount
+      // depends on moved (a fresh object literal with identical field values).
+      // Remount only when an input the renderer reads actually changed identity;
+      // otherwise the live mount keeps streaming untouched.
+      if (
+        next.client === client &&
+        next.components === options.components &&
+        next.sanitize === options.sanitize &&
+        next.virtualize === options.virtualize &&
+        next.stickToBottom === options.stickToBottom
+      ) {
+        return;
+      }
+      handle.destroy();
+      ({ client, ...options } = next);
+      handle = mountFluxMarkdown(client, node, options as MountOptions);
+    },
+    destroy() {
+      // Only the mount is torn down. The caller owns the client.
+      handle.destroy();
+    },
+  };
+}

package/src/types-core.ts

@@ -0,0 +1,138 @@
+export type BlockKindTag =
+  | "Paragraph"
+  | "Heading"
+  | "CodeBlock"
+  | "MathBlock"
+  | "Mermaid"
+  | "List"
+  | "Blockquote"
+  | "Alert"
+  | "Table"
+  | "Rule"
+  | "Html"
+  | "Component";
+
+export interface BlockKind {
+  type: BlockKindTag;
+  data?: unknown;
+}
+
+export interface Block {
+  id: number;
+  kind: BlockKind;
+  start: number;
+  end: number;
+  html: string;
+  open: boolean;
+  speculative: boolean;
+}
+
+export interface Patch {
+  newly_committed: Block[];
+  active: Block[];
+}
+
+/** Props passed to a block-kind override (e.g. `components.CodeBlock`). */
+export interface BlockComponentProps {
+  /** The full parsed block, including `kind` (with `kind.data`) and offsets. */
+  block: Block;
+  /** Rendered, XSS-safe HTML for this block. */
+  html: string;
+  /** 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. */
+  speculative: boolean;
+  /** Decoded source text — present for `CodeBlock` / `MathBlock`. */
+  text?: string;
+  /** Info-string language — present for `CodeBlock` (from `kind.data.lang`). */
+  language?: string;
+  /** Component tag name — present for `Component` blocks (from `kind.data.tag`). */
+  tag?: string;
+  /**
+   * Sanitized attributes — present for `Component` blocks. The name-form depends
+   * on the consumer: the JSX renderer maps `class`→`className`/`for`→`htmlFor`
+   * so `{...attrs}` spreads cleanly onto an element; the DOM renderer keeps the
+   * literal HTML names (`class`/`for`) because it applies them via
+   * `setAttribute`. For `Component` blocks, `html` is the **inner**
+   * rendered-markdown HTML (not the `<tag>…</tag>` wrapper), so an override can
+   * wrap it itself.
+   */
+  attrs?: Record<string, string>;
+}
+
+/**
+ * Per-stream parser configuration. Omitted fields use the library defaults
+ * (autolinks + alerts on, raw HTML escaped, footnotes off) — so the default
+ * `new FluxClient()` behaves exactly as before. Config is applied when the
+ * stream's parser is created and is **immutable** for that stream's lifetime
+ * (a `reset()` keeps it; use a new client for different flags).
+ */
+export interface ParserConfig {
+  /** GFM extended autolinks (bare www./http(s)://ftp:// + emails). Default true. */
+  gfmAutolinks?: boolean;
+  /** GitHub alerts (`> [!NOTE]` → callouts). Default true. */
+  gfmAlerts?: boolean;
+  /** GFM footnotes (`[^1]` + `[^1]:` → footnote section). Default false. */
+  gfmFootnotes?: boolean;
+  /**
+   * Math: `$…$` / `\(…\)` inline and `$$…$$` / `\[…\]` display. Default false
+   * (so `$` in prose / currency stays literal). Emits KaTeX-ready markup
+   * (`<span class="math math-inline">` / `<div class="math math-display">`)
+   * carrying the LaTeX — bring your own KaTeX pass (flux-md stays zero-dep).
+   */
+  gfmMath?: boolean;
+  /**
+   * Emit `dir="auto"` on block-level text elements (`p`, `h1`–`h6`,
+   * `blockquote`, `ul`/`ol`/`li`, `table`) so the browser detects each block's
+   * direction independently — correct for documents mixing English with
+   * Arabic/Hebrew. Default false; code blocks always stay LTR. Recommended for
+   * apps that render RTL or mixed-direction content.
+   */
+  dirAuto?: boolean;
+  /** Pass raw HTML through unescaped. Default false. **Never enable for untrusted input.** */
+  unsafeHtml?: boolean;
+  /**
+   * Opt-in allowlist of custom component tag names (e.g. `["Thinking",
+   * "Callout"]`). A `<Tag>…</Tag>` whose name is listed renders as a component
+   * whose inner content is parsed as **markdown** — safely, without `unsafeHtml`
+   * (the tag is allowlisted and its attributes are sanitized: event handlers
+   * dropped, dangerous URL schemes neutralized). The block is dispatched by the
+   * renderer via `components[tag]` (or `components.Component`). Empty/omitted =
+   * off. Names match case-sensitively.
+   */
+  componentTags?: string[];
+}
+
+// Each message carries a `streamId` so one worker can multiplex many parsers
+// (the worker pool). `ready` is the exception — it's worker-level (WASM loaded),
+// not stream-level. The first message for a stream may carry `config`, applied
+// when that stream's parser is created.
+export type ToWorker =
+  | { type: "append"; streamId: number; chunk: string; config?: ParserConfig }
+  | { type: "finalize"; streamId: number; config?: ParserConfig }
+  | { type: "reset"; streamId: number }
+  | { type: "dispose"; streamId: number };
+
+export type FromWorker =
+  | { type: "ready" }
+  | {
+      type: "patch";
+      streamId: number;
+      patch: Patch;
+      appendedBytes: number;
+      parseMicros: number;
+      retainedBytes: number;
+      wasmMemoryBytes: number;
+    }
+  | { type: "error"; streamId: number; message: string };
+
+/**
+ * Minimal structural interface satisfied by the DOM `Worker`. Injectable so the
+ * pool's routing/lifecycle logic can be unit-tested with a fake worker — no
+ * real Worker or WASM required.
+ */
+export interface WorkerLike {
+  postMessage(msg: ToWorker): void;
+  addEventListener(type: "message", listener: (ev: { data: FromWorker }) => void): void;
+  terminate(): void;
+}