flux-md 0.16.2 → 0.18.0

package/README.md

@@ -12,19 +12,23 @@ Parsing runs entirely **off the main thread** — each stream gets its own poole
 bun add flux-md     # or: npm i flux-md / pnpm add flux-md
 ```
 
-flux-md ships as **source** (TypeScript + the compiled WASM). The worker and
-WASM asset are referenced with the **web-standard `new URL(asset,
+flux-md ships **compiled, non-minified ESM** (`dist/*.js` + `.d.ts` types) plus
+the compiled WASM — no raw `.ts`/`.tsx` source. The worker and WASM asset are
+referenced with the **web-standard `new URL(asset,
 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
+**verified on Next.js 16**, see the [Next.js callout](#nextjs) below).
+
 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.
+need the one whose binding you import. The framework-free entries
+(`flux-md/client`, `flux-md/dom`, `flux-md/element`, and `flux-md/server`) need
+none. (The bare `flux-md` entry re-exports the React component surface, so it
+pulls `react` — import from `flux-md/client` if you want a framework-free core.)
 
 > **Vite — one-line config.** Vite's dependency pre-bundling (esbuild) hoists
 > the wasm-bindgen glue into `.vite/deps/`, which breaks the relative
@@ -42,43 +46,35 @@ need the one whose binding you import. The core (`flux-md`, `flux-md/client`,
 
 <a id="nextjs"></a>
 
-> **Next.js (App Router) — two requirements.** Verified on **Next.js 16** with
-> **Turbopack** (the default for both `next dev` and `next build`). The same two
-> requirements apply under webpack. Because flux-md ships TypeScript source:
->
-> 1. **Transpile the package.** Next does not compile `node_modules` TypeScript
->    by default — without this, Turbopack errors with *"Unknown module type"* on
->    `react.tsx`. Add flux-md to `transpilePackages`:
->
->    ```ts
->    // next.config.ts
->    import type { NextConfig } from "next";
->    const nextConfig: NextConfig = { transpilePackages: ["flux-md"] };
->    export default nextConfig;
->    ```
+> **Next.js (App Router) — one requirement.** Works on **Next.js** with
+> **Turbopack** (the default for both `next dev` and `next build`) or webpack.
+> Since 0.17.0 flux-md ships **compiled ESM**, so **no `transpilePackages` or
+> other build config is needed** — earlier versions required it only because the
+> package shipped raw TypeScript, which Next does not compile inside
+> `node_modules`. That no longer applies.
 >
-> 2. **Use it from a Client Component.** `<FluxMarkdown>` uses React hooks (and
->    spawns a Web Worker on mount), so it must carry `"use client"` — it can't be
->    a Server Component. (It is still SSR-safe: on the server it renders an empty
->    shell and only starts streaming after hydration, so there's no SSR crash —
->    the constraint is hooks, not the worker.)
+> **Use it from a Client Component.** `<FluxMarkdown>` uses React hooks (and
+> spawns a Web Worker on mount), so it must carry `"use client"` — it can't be
+> a Server Component. (It is still SSR-safe: on the server it renders an empty
+> shell and only starts streaming after hydration, so there's no SSR crash —
+> the constraint is hooks, not the worker.)
 >
->    ```tsx
->    "use client";
->    import { FluxMarkdown } from "flux-md/react";
+> ```tsx
+> "use client";
+> import { FluxMarkdown } from "flux-md/react";
 >
->    export default function Answer({ stream }: { stream: AsyncIterable<string> }) {
->      return <FluxMarkdown stream={stream} />;
->    }
->    ```
+> export default function Answer({ stream }: { stream: AsyncIterable<string> }) {
+>   return <FluxMarkdown stream={stream} />;
+> }
+> ```
 >
->    **Create the `stream` in Client Component code, not in a Server Component.**
->    A `Response` / `ReadableStream` / `AsyncIterable` isn't serializable, so it
->    can't be passed as a prop from a Server Component (e.g. `page.tsx`) — that
->    throws *"Only plain objects can be passed to Client Components."* Pass a
->    serializable prop (a URL, the chat messages) from the server and open the
->    stream on the client — e.g. `stream={await fetch("/api/chat")}` from a client
->    effect, or the `useFluxStream` hook (see [Quick start](#quick-start)).
+> **Create the `stream` in Client Component code, not in a Server Component.**
+> A `Response` / `ReadableStream` / `AsyncIterable` isn't serializable, so it
+> can't be passed as a prop from a Server Component (e.g. `page.tsx`) — that
+> throws *"Only plain objects can be passed to Client Components."* Pass a
+> serializable prop (a URL, the chat messages) from the server and open the
+> stream on the client — e.g. `stream={await fetch("/api/chat")}` from a client
+> effect, or the `useFluxStream` hook (see [Quick start](#quick-start)).
 >
 > That's it — Turbopack bundles the worker and emits the `.wasm` to
 > `_next/static/media` itself, so no extra asset/loader config is needed (and the
@@ -425,12 +421,15 @@ const html = renderToString("# Hello\n\n**world**");   // sync HTML string, no w
 ```
 
 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):
+`<FluxMarkdownStatic>` from **`flux-md/server/react`** — a hookless, RSC-safe
+component that renders finished content with the same `components` overrides
+(inline/block component tags dispatch on the server too). It lives in its own
+subpath so the core `flux-md/server` above stays importable with no `react`
+installed:
 
 ```tsx
-import { initFlux, FluxMarkdownStatic } from "flux-md/server";
+import { initFlux } from "flux-md/server";
+import { FluxMarkdownStatic } from "flux-md/server/react";
 
 await initFlux();
 export default function Doc({ md }: { md: string }) {
@@ -449,10 +448,11 @@ export default function Doc({ md }: { md: string }) {
   bundler-resolved asset. On edge runtimes pass bytes yourself:
   `initFluxSync(wasmBytes)`.
 - **`renderToString(md, { config })`** — synchronous HTML string, **zero React
-  dependency**.
+  dependency** (imports cleanly with no `react` installed).
 - **`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
+- **`<FluxMarkdownStatic content config components />`** (from
+  `flux-md/server/react`) — 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
@@ -999,42 +999,71 @@ genuinely hostile content where CSS-overlay/clickjacking matters, render inside
 a sandboxed `<iframe>` instead — sanitization stops injection, not every
 visual-overlay trick.
 
-### Supply-chain transparency
-
-flux-md is **zero runtime dependency** — no third-party packages are pulled in
-at runtime. The parsing core is Rust compiled to WebAssembly, reproducibly
-buildable from `crates/flux-md-core/` via `bun run build:wasm`.
-
-**Native code (WebAssembly).** The shipped `flux_md_core_bg.wasm` (~200 KB) is
-first-party, built from the Rust source in this repo, and runs inside a sandboxed
-Web Worker (browser) or Node worker thread. Supply-chain scanners such as
-[Socket.dev](https://socket.dev) will flag it as `nativeCode` — this is accurate
-and expected. The WASM is not a vendored third-party binary; it is reproducible
-from source.
-
-**Network access.** flux-md performs network I/O in exactly two scenarios, both
-caller-driven:
-
-- `<flux-markdown src="URL">` — the Web Component fetches the URL you supply and
-  streams the response. No URL is ever chosen by flux-md itself.
-- The wasm-bindgen glue (`wasm/flux_md_core.js`) loads the co-located `.wasm`
-  asset via `fetch(new URL("…_bg.wasm", import.meta.url))` — bundlers resolve
-  this to a local build artifact, not a remote endpoint.
-
-flux-md has no telemetry, no analytics, and no first-party remote endpoints.
-Socket will flag the `networkAccess` signal — it is accurate and expected. In
-privileged contexts (browser extensions, Electron, environments where the
-same-origin policy may not apply), treat the `src` attribute value as you would
-any external URL and allowlist it in your CSP / security policy.
-
-**Filesystem access (Node/SSR only).** `flux-md/server` reads the package's
-own `.wasm` file off disk on Node.js (Node's `fetch` cannot load `file://`
-URLs). This is a Node-only path; it reads only the package-internal asset and
-never touches caller-supplied paths. Socket will flag `filesystemAccess` — also
-accurate and expected.
-
-The `socket.yml` at the repository root documents these signals with their
-justifications for Socket's GitHub app.
+### Supply chain & security posture
+
+flux-md ships **zero runtime dependencies** — `dependencies` and
+`optionalDependencies` in `package.json` are both empty. The parsing core is Rust
+compiled to WebAssembly, reproducibly buildable from `crates/flux-md-core/` via
+`bun run build:wasm`. The package publishes **compiled, non-minified ESM**
+(`dist/*.js` + `.d.ts`); it does not ship raw `.ts`/`.tsx` source.
+
+**Frameworks are optional peers, by design.** `react`, `vue`, `svelte`, and
+`solid-js` are declared as `peerDependencies` with
+`peerDependenciesMeta.optional: true`. You install only the one you use — or none
+(the `flux-md/dom` and `flux-md/element` entries need no framework at all). This
+is the most important supply-chain property of the package: **a React-only
+consumer never installs `vue` or `solid-js`, so those frameworks' transitive
+internals never enter that consumer's lockfile.** `npm i flux-md` on its own pulls
+in nothing else.
+
+**Why a registry scan may flag `seroval` and `@vue/compiler-*`.** When a scanner
+resolves *all* declared peers, it surfaces alerts on framework internals reachable
+only through the optional peers — **none of which is flux-md code, and none of
+which is installed unless you opt into that framework:**
+
+- `seroval` (transitive of **solid-js**) — its `deserialize()` uses
+  `(0, eval)(source)` and touches the network. This is Solid's SSR serialization
+  layer; it is also the package some scanners label a "potential vulnerability".
+- `@vue/compiler-core` (transitive of **vue**) — uses the `Function` constructor
+  for template codegen.
+- `@vue/compiler-sfc` (transitive of **vue**) — references `globalThis["fetch"]`.
+- minified esm-bundler builds of those compilers read as "obfuscated code".
+
+flux-md's own source contains **no `eval` and no `Function(...)` constructor**
+(`grep -rnE '\beval\s*\(|\bnew Function\b|\bFunction\s*\(' packages/flux-md/src`
+returns nothing). The
+repository's [`socket.yml`](https://github.com/siinghd/flux-md/blob/main/socket.yml)
+documents this and disables those upstream-framework alert types for flux-md's own
+CI (which installs every framework as a devDependency for cross-framework tests).
+If you prefer surgical handling, ignore the specific transitive packages instead
+(e.g. `@SocketSecurity ignore seroval@<version>`).
+
+**flux-md is browser-oriented (Web Worker + WASM).** The default path runs the
+WASM parser inside a Web Worker — ideal for browsers and modern Node
+(`worker_threads`), but **not** intended for non-browser or older environments
+that lack Workers/WASM. If you need a worker-free, synchronous path (Node SSR /
+React Server Components), use **`flux-md/server`** — it loads the same WASM
+synchronously off disk and renders to a string without spawning a worker.
+
+**First-party signals a scanner will (correctly) show.** These describe flux-md
+itself and are kept *visible* rather than silenced:
+
+- **Native code (`hasNativeCode`).** The first-party `dist/wasm/flux_md_core_bg.wasm`
+  (~180 KB) is built from the Rust source in this repo and runs inside a sandboxed
+  Web Worker (browser) or Node worker thread. It is reproducible from source, not a
+  vendored third-party binary.
+- **Network access (`networkAccess`).** Only `<flux-markdown src="URL">` (the URL
+  *you* supply) and the wasm-bindgen glue loading the co-located `.wasm` via
+  `fetch(new URL("…_bg.wasm", import.meta.url))` — which bundlers resolve to a
+  local build artifact. No telemetry, no analytics, no first-party remote
+  endpoints. In privileged contexts (browser extensions, Electron) treat the `src`
+  value as any external URL and allowlist it in your CSP.
+- **Filesystem access (`filesystemAccess`).** Node/SSR only: `flux-md/server` reads
+  the package's own `.wasm` off disk (Node's `fetch` cannot load `file://` URLs).
+  It reads only the package-internal asset, never a caller-supplied path.
+
+The `socket.yml` at the repository root documents every signal with its
+justification for Socket's GitHub app.
 
 ## Scaling
 
@@ -1130,7 +1159,7 @@ re-snapping during streaming, so treat smooth following there as best-effort.
 │              microtask, calls WASM   │
 └──┬──── ffi ───────────────────────────┘
    ▼
-┌── Rust → WASM (~150 KB after opt) ────┐
+┌── Rust → WASM (~170 KB after opt) ────┐
 │  StreamParser:                        │
 │    buffer: append-only                │
 │    committed_offset                   │

package/dist/block-props.d.ts

@@ -0,0 +1,18 @@
+import type { Block, BlockComponentProps } from "./types-core.js";
+/** Info-string language from a code block's `data-lang="…"`. */
+export declare function extractLang(html: string): string;
+/**
+ * Convert sanitized HTML attribute pairs into a spreadable object, keeping the
+ * HTML-form names (`class`, `for`) verbatim. This is the deliberate divergence
+ * from the JSX renderer (which renames to `className`/`htmlFor` for a prop
+ * spread): the DOM renderer applies them via `el.setAttribute(name, value)`,
+ * which wants the literal HTML names.
+ */
+export declare function htmlAttrs(pairs: [string, string][]): Record<string, string>;
+/**
+ * Build the props a block-kind / component-tag override receives — the same
+ * shape the JSX renderer's block-kind props carry, with ONE deliberate
+ * divergence: for `Component` blocks `attrs` stay in HTML form (`class`/`for`)
+ * because DOM overrides apply them via `setAttribute` (see {@link htmlAttrs}).
+ */
+export declare function blockProps(block: Block): BlockComponentProps;

package/dist/block-props.js

@@ -0,0 +1,75 @@
+function decodeEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+function decodeCodeText(html) {
+  const m = html.match(/<pre><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
+  return m ? decodeEntities(m[1]) : "";
+}
+function decodeMathText(html) {
+  const d = html.match(/<div class="math math-display">([\s\S]*?)<\/div>/);
+  if (d) return decodeEntities(d[1]);
+  return decodeCodeText(html);
+}
+function extractLang(html) {
+  const m = html.match(/data-lang="([^"]+)"/);
+  return m ? m[1] : "";
+}
+function componentInnerHtml(html, tag) {
+  const gt = html.indexOf(">");
+  if (gt < 0) return "";
+  let inner = html.slice(gt + 1);
+  const close = `</${tag}>`;
+  if (inner.endsWith(close)) inner = inner.slice(0, -close.length);
+  return inner.replace(/^\n/, "").replace(/\n$/, "");
+}
+function htmlAttrs(pairs) {
+  const out = {};
+  for (const [k, v] of pairs) out[k] = v;
+  return out;
+}
+function blockProps(block) {
+  const props = {
+    block,
+    html: block.html,
+    open: block.open,
+    speculative: block.speculative
+  };
+  const data = block.kind.data;
+  if (block.kind.type === "CodeBlock") {
+    props.text = data?.code ?? decodeCodeText(block.html);
+    props.language = data?.lang ?? "";
+    if (typeof data?.code === "string") {
+      props.code = { lang: data.lang ?? null, code: data.code };
+    }
+  } else if (block.kind.type === "MathBlock") {
+    props.text = data?.latex ?? decodeMathText(block.html);
+    if (typeof data?.latex === "string") {
+      props.math = { latex: data.latex };
+    }
+  } else if (block.kind.type === "List") {
+    if (data && typeof data.start === "number") {
+      props.list = { ordered: !!data.ordered, start: data.start, items: data.items };
+    }
+  } else if (block.kind.type === "Component") {
+    props.tag = data?.tag ?? "";
+    props.attrs = htmlAttrs(data?.attrs ?? []);
+    props.html = componentInnerHtml(block.html, props.tag);
+  } else if (block.kind.type === "Table") {
+    props.table = block.kind.data;
+  } else if (block.kind.type === "Heading") {
+    if (typeof block.kind.data === "object" && block.kind.data !== null) {
+      props.heading = block.kind.data;
+    }
+  } else if (block.kind.type === "Blockquote" || block.kind.type === "Alert") {
+    const cd = block.kind.data;
+    if (cd && Array.isArray(cd.nested)) {
+      props.container = { nested: cd.nested };
+    }
+  }
+  return props;
+}
+export {
+  blockProps,
+  extractLang,
+  htmlAttrs
+};

package/dist/client.d.ts

@@ -0,0 +1,311 @@
+import type { Block, FromWorker, ParserConfig, Patch, ToWorker, WorkerLike } from "./types-core.js";
+/**
+ * The ordered-block store backing a stream, extracted as a pure function so
+ * its reference-stability contract is testable without a Worker.
+ *
+ * **The contract that prevents extra React re-renders:** a block, once
+ * committed, is never re-sent by the parser, so `applyPatch` never replaces it
+ * in the map. Its object reference stays identical across every later patch —
+ * which is exactly what `blocksEqual` (the BlockView memo) checks, so committed
+ * blocks never re-render (and never re-parse) as the stream grows. Only the
+ * `active` tail gets fresh references each patch, and only it re-renders.
+ */
+export interface BlockStore {
+    committed: Map<number, Block>;
+    committedOrder: number[];
+    active: Block[];
+    snapshot: Block[];
+}
+export declare function emptyBlockStore(): BlockStore;
+/** A heading entry for building a table of contents — see {@link FluxClient.outline}. */
+export interface OutlineEntry {
+    /** Heading level 1–6. */
+    level: number;
+    /** Plain-text heading content (tags stripped, entities decoded). */
+    text: string;
+    /** Stable block id — usable as a scroll target / React key. */
+    id: number;
+}
+export declare function applyPatch(store: BlockStore, patch: Patch): void;
+interface PoolWorker {
+    worker: WorkerLike;
+    ready: boolean;
+    /** Set once WASM init fails; whenWorkerReady rejects with this thereafter. */
+    failed: Error | null;
+    streamCount: number;
+    /** Live stream ids on this worker — so a fatal failure can notify each one. */
+    streamIds: Set<number>;
+    readyWaiters: Array<{
+        resolve: () => void;
+        reject: (e: Error) => void;
+    }>;
+}
+/**
+ * A pool of Web Workers, each multiplexing many `FluxParser`s keyed by stream
+ * id. This is what lets flux-md scale past `hardwareConcurrency` concurrent
+ * streams without oversubscribing OS threads: 50 streams share (at most) the
+ * cap's worth of workers instead of spawning 50.
+ *
+ * Worker creation is **lazy and load-aware**: while under the cap, each new
+ * stream gets its own worker (so 1 stream = 1 worker, identical to the old
+ * behavior); once at the cap, new streams attach to the least-loaded worker.
+ *
+ * The constructor injects a `WorkerLike` factory so the routing and lifecycle
+ * logic is unit-testable with a fake worker — no real Worker or WASM needed.
+ */
+export declare class FluxPool {
+    private factory;
+    private cap;
+    private workers;
+    private handlers;
+    private nextStreamId;
+    constructor(factory: () => WorkerLike, cap: number);
+    /** Reserve a stream id and assign a worker, registering its message handler. */
+    acquire(handler: (msg: FromWorker) => void): {
+        streamId: number;
+        pw: PoolWorker;
+    };
+    /** Free a stream's parser in its worker; keep the worker warm for siblings. */
+    release(streamId: number, pw: PoolWorker): void;
+    /** Inverse of {@link release}: re-register a stream's handler so it receives
+     *  patches again. For React StrictMode's dev double-mount, which destroys a
+     *  client on the simulated unmount and remounts the SAME instance. The worker
+     *  lazily recreates the disposed parser on the next append. */
+    reattach(streamId: number, pw: PoolWorker, handler: (msg: FromWorker) => void): void;
+    send(pw: PoolWorker, msg: ToWorker): void;
+    /** Resolves when the given worker has finished WASM init; rejects if it failed. */
+    whenWorkerReady(pw: PoolWorker): Promise<void>;
+    /**
+     * Eagerly spin up one worker so WASM init starts BEFORE the first stream —
+     * taking the one-time init off the first-token critical path (e.g. call
+     * `getDefaultPool().warm()` on app load / route entry). Reuses a live worker
+     * if one exists; the warm worker is the one the first stream attaches to (it
+     * has spare capacity), so the work is not wasted. Resolves when that worker has
+     * finished initializing WASM; rejects if init fails fatally. Browser-only (it
+     * constructs a `Worker`).
+     */
+    warm(): Promise<void>;
+    /** Terminate every worker (test teardown / full shutdown). */
+    disposeAll(): void;
+    get workerCount(): number;
+    private pick;
+    private create;
+    private onMessage;
+    private dispatch;
+}
+/** The process-wide default pool every `FluxClient` shares unless given one. */
+export declare function getDefaultPool(): FluxPool;
+/** TEST-ONLY: drop the process-wide default pool so the next {@link getDefaultPool}
+ *  rebuilds it (lazily, with the current global `Worker`). Lets a test file that
+ *  drives the default pool start from a clean, deterministic state regardless of
+ *  which other file warmed it first in bun's shared test process. Not part of the
+ *  public API and a no-op for normal runtime use. */
+export declare function __resetDefaultPool(): void;
+/**
+ * Subscriber-driven store backing a single streaming parser. Each client owns
+ * one stream within a shared {@link FluxPool}; many clients multiplex over a
+ * small set of workers (see the pool for the scaling story).
+ *
+ * The store exposes:
+ *   - subscribe(listener): for React's useSyncExternalStore
+ *   - getSnapshot(): the current ordered list of blocks
+ *   - getMetrics(): per-stream perf metrics
+ *
+ * Mutation methods:
+ *   - append(chunk): forward to the worker
+ *   - finalize(): mark the stream done
+ *   - reset(): start fresh
+ */
+export declare class FluxClient {
+    private pool;
+    private pw;
+    private streamId;
+    private config?;
+    private configSent;
+    private listeners;
+    private store;
+    private onError?;
+    private onBlock?;
+    private attached;
+    private lastContent;
+    private contentDone;
+    private coalesce;
+    private rafHandle;
+    private finalizePending;
+    private epoch;
+    private appendedBytes;
+    private patchCount;
+    private totalParseMicros;
+    private lastPatchMs;
+    private firstAppendMs;
+    private retainedBytes;
+    private wasmMemoryBytes;
+    private renderCount;
+    private rebuildCount;
+    /**
+     * @param options.pool   worker pool to join (defaults to the shared
+     *   process-wide pool — pass a dedicated `FluxPool` only for isolation).
+     * @param options.config per-stream parser flags (see {@link ParserConfig});
+     *   omitted fields use library defaults. Applied once, immutable thereafter.
+     * @param options.onError invoked on a worker/parse error or a fatal WASM-init
+     *   failure (`fatal: true`). Without it, errors are only `console.error`d and
+     *   a load failure surfaces solely as a rejected {@link FluxClient.whenReady}.
+     * @param options.onBlock invoked once per block as it commits (in document
+     *   order, after the store updates) — for side effects like lazily
+     *   highlighting a finished code block or analytics. A committed block never
+     *   re-fires; the streaming tail does not (subscribe for live tail updates).
+     * @param options.coalesce opt-in (default `false`): collapse multiple
+     *   intra-frame patch notifications into ONE `requestAnimationFrame`-scheduled
+     *   flush to subscribers, so a React `useSyncExternalStore` consumer renders at
+     *   most once per frame instead of once per patch. Lossless — committed blocks
+     *   are reference-stable, so only superseded tail-only renders are skipped. The
+     *   stream-completion (finalize) patch always flushes synchronously, and a
+     *   pending frame is cancelled on `reset()`/`destroy()`. No effect when
+     *   `requestAnimationFrame` is unavailable (e.g. SSR) — emits stay synchronous.
+     */
+    constructor(options?: {
+        pool?: FluxPool;
+        config?: ParserConfig;
+        onError?: (err: {
+            message: string;
+            fatal?: boolean;
+        }) => void;
+        onBlock?: (block: Block) => void;
+        coalesce?: boolean;
+    });
+    /**
+     * Lazily reserve this client's stream id and bind it to a pool worker. The
+     * SOLE place that calls pool.acquire() — so the worker is created on the FIRST
+     * worker-bound operation (append/finalize/reset/pipeFrom/whenReady), never at
+     * construct time. This is what makes `new FluxClient()` SSR-safe: nothing here
+     * runs during an SSR render (which only subscribes + reads the snapshot).
+     *
+     * Idempotent: once this.pw is set it returns it immediately and never
+     * re-acquires — this.pw is never nulled (destroy() deliberately keeps it so
+     * StrictMode's destroy()→reattach() on the SAME instance re-registers the same
+     * slot). Note: streamId/worker assignment now follows first-worker-bound-op
+     * order, not construction order — a client constructed first no longer
+     * necessarily owns the lowest streamId. This affects neither the pool cap nor
+     * multiplexing (pick() is unchanged and remains the only path to create()).
+     */
+    private ensureAcquired;
+    get ready(): boolean;
+    whenReady(): Promise<void>;
+    private firstConfig;
+    append(chunk: string): void;
+    finalize(): void;
+    /**
+     * Pipe a source straight in: read it to completion, `append()` each chunk,
+     * then `finalize()`. The LLM-native path — e.g.
+     * `await client.pipeFrom(await fetch("/api/chat"))`. Accepts:
+     *   - a `Response` or its `ReadableStream<Uint8Array>` body (bytes; decoded
+     *     with `TextDecoder({ stream: true })` so a multibyte sequence straddling
+     *     a chunk boundary carries into the next read), or
+     *   - an `AsyncIterable<string>` (e.g. an SSE delta generator) — string chunks
+     *     appended verbatim.
+     *
+     * Pass `opts.signal` to supersede/cancel: the signal is checked on every
+     * iteration, so once aborted no further chunk is appended and **finalize is
+     * skipped** (a superseded stream must not finalize). For a byte source the
+     * reader is also `cancel()`'d to tear down the upstream. Resolves once
+     * finalized (or cleanly on abort); rejects if the source itself errors.
+     * Browser-only for byte sources (uses `TextDecoder`).
+     */
+    pipeFrom(source: ReadableStream<Uint8Array> | Response | AsyncIterable<string>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Drive the parser from a CONTROLLED full string instead of manual appends.
+     * Pass the whole document-so-far each time; setContent diffs it against the
+     * last value and does the minimal work:
+     *   - **prefix-extension** (the streaming-growth case) → append only the new
+     *     suffix, so committed blocks stay put and only the active tail re-parses;
+     *   - **any other change** (e.g. a finished stream swapped for a re-processed
+     *     final string) → `reset()` + reparse the whole new string.
+     *
+     * This is the first-class bridge for UIs that hold a streaming message as a
+     * single growing string prop (the common React shape) — no hand-rolled diff,
+     * no readiness gate (appends before WASM is ready are buffered). Pass
+     * `{ done: true }` once the content is final to `finalize()` (idempotent within
+     * a generation; a content change *after* done reopens the stream via a fresh
+     * reparse, since a finalized parser is terminal and can't be appended to).
+     * Drive a given client with `setContent` *or* manual `append()`/`finalize()`,
+     * not both — they share the internal diff baseline.
+     *
+     * v1 note: the non-prefix path is a full reparse, not a partial rewind —
+     * committed blocks are frozen, so there is no truncate-to-offset. For the
+     * common case (append-growth + one end-of-stream swap) that is optimal. A
+     * transform that rewrites *earlier* bytes on every update is an anti-pattern
+     * here (it forces a reparse each tick); do that enrichment at render time via
+     * `components` instead, keeping the source append-only.
+     */
+    setContent(content: string, opts?: {
+        done?: boolean;
+    }): void;
+    reset(): void;
+    destroy(): void;
+    /**
+     * Re-register with the pool after {@link destroy} so the client receives
+     * patches again. Needed only for React StrictMode's dev double-mount, where
+     * the renderer destroys on the simulated unmount then remounts the SAME
+     * client instance; apps don't normally call this. No-op if still attached.
+     */
+    reattach(): void;
+    subscribe: (fn: () => void) => () => boolean;
+    getSnapshot: () => Block[];
+    /**
+     * Internal: a renderer with an `onRenderMetrics` hook calls this once per
+     * actual React block render so `getMetrics().renderCount` aggregates churn.
+     * No-op cost when no hook is wired (it is simply never called). Not part of
+     * the public API surface — the underscore marks it renderer-internal.
+     */
+    __noteRender(): void;
+    /**
+     * Internal: the DOM renderer calls this once per actual node rebuild (the
+     * changed-block branch) when an `onRenderMetrics` hook is wired, so
+     * `getMetrics().rebuildCount` aggregates churn. Never called without a hook.
+     */
+    __noteRebuild(): void;
+    getMetrics(): {
+        bytes: number;
+        patches: number;
+        meanParseMicros: number;
+        totalParseMs: number;
+        throughputKBs: number;
+        committedBlocks: number;
+        activeBlocks: number;
+        lastPatchAgoMs: number;
+        retainedBytes: number;
+        wasmMemoryBytes: number;
+        renderCount: number;
+        rebuildCount: number;
+    };
+    /**
+     * A heading outline of the current snapshot (committed + active), in document
+     * order — for a table of contents. Works mid-stream; entries appear as their
+     * headings stream in. The `id` is stable, so a built ToC won't re-key.
+     */
+    outline(): OutlineEntry[];
+    /**
+     * The rendered document as plain text — tags stripped, entities decoded,
+     * blocks separated by blank lines. Derived from the rendered HTML (the source
+     * markdown is parsed away in WASM and not retained client-side), so it is a
+     * readable approximation for search indexing / summaries, not a round-trip of
+     * the original source.
+     */
+    toPlaintext(): string;
+    private onMessage;
+    /**
+     * Notify subscribers of a new snapshot.
+     *
+     * With `coalesce` off (default) this is fully synchronous, exactly as before.
+     * With it on and `requestAnimationFrame` available, a normal emit only
+     * *schedules* a single per-frame flush — repeated intra-frame emits collapse
+     * into one notify. `sync` forces an immediate flush (stream completion / reset)
+     * and cancels any frame already pending so the snapshot is delivered once.
+     */
+    private emit;
+    private flushNow;
+    private cancelFrame;
+}
+export {};