flux-md 0.16.2 → 0.18.0

package/{src/client.ts → dist/client.js}

@@ -1,113 +1,36 @@
-import type { Block, FromWorker, ParserConfig, Patch, ToWorker, WorkerLike } from "./types-core";
-
-/**
- * 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[];
+function emptyBlockStore() {
+  return { committed: /* @__PURE__ */ new Map(), committedOrder: [], active: [], snapshot: [] };
 }
-
-export function emptyBlockStore(): BlockStore {
-  return { committed: new Map(), committedOrder: [], active: [], snapshot: [] };
+function htmlToText(html) {
+  return html.replace(/<[^>]*>/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&").replace(/\s+/g, " ").trim();
 }
-
-/** 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;
-}
-
-/** Strip tags (→ space) and decode the small entity set the core emits, then
- *  collapse whitespace. INVARIANT: the simple `<[^>]*>` strip is only safe
- *  because every input here is HTML the Rust core produced via escape_html /
- *  escape_attr — which escape `>` inside attribute values, so no `>` ever
- *  appears except as a real tag close. This must NOT be fed externally-authored
- *  HTML. `&amp;` decodes last so `&amp;lt;` → `&lt;`, not `<`. */
-function htmlToText(html: string): string {
-  return html
-    .replace(/<[^>]*>/g, " ")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&amp;/g, "&")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-export function applyPatch(store: BlockStore, patch: Patch): void {
+function applyPatch(store, patch) {
   for (const b of patch.newly_committed) {
     if (!store.committed.has(b.id)) store.committedOrder.push(b.id);
     store.committed.set(b.id, b);
   }
   store.active = patch.active;
-  // Fresh array each patch (immutable for React reference checks), but the
-  // committed entries inside it are the same object references as before.
-  const next: Block[] = new Array(store.committedOrder.length + store.active.length);
+  const next = new Array(store.committedOrder.length + store.active.length);
   for (let i = 0; i < store.committedOrder.length; i++) {
-    next[i] = store.committed.get(store.committedOrder[i])!;
+    next[i] = store.committed.get(store.committedOrder[i]);
   }
   for (let i = 0; i < store.active.length; i++) {
     next[store.committedOrder.length + i] = store.active[i];
   }
   store.snapshot = next;
 }
-
-// --------------------------------------------------------------------------
-// Worker pool
-// --------------------------------------------------------------------------
-
-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 class FluxPool {
-  private workers: PoolWorker[] = [];
-  private handlers = new Map<number, (msg: FromWorker) => void>();
-  private nextStreamId = 1;
-
-  constructor(
-    private factory: () => WorkerLike,
-    private cap: number,
-  ) {}
-
+class FluxPool {
+  constructor(factory, cap) {
+    this.factory = factory;
+    this.cap = cap;
+  }
+  factory;
+  cap;
+  workers = [];
+  handlers = /* @__PURE__ */ new Map();
+  nextStreamId = 1;
   /** Reserve a stream id and assign a worker, registering its message handler. */
-  acquire(handler: (msg: FromWorker) => void): { streamId: number; pw: PoolWorker } {
+  acquire(handler) {
     const streamId = this.nextStreamId++;
     const pw = this.pick();
     pw.streamCount++;
@@ -115,42 +38,36 @@ export class FluxPool {
     this.handlers.set(streamId, handler);
     return { streamId, pw };
   }
-
   /** Free a stream's parser in its worker; keep the worker warm for siblings. */
-  release(streamId: number, pw: PoolWorker): void {
+  release(streamId, pw) {
     this.handlers.delete(streamId);
     pw.streamIds.delete(streamId);
     pw.streamCount = Math.max(0, pw.streamCount - 1);
     try {
       pw.worker.postMessage({ type: "dispose", streamId });
     } catch {
-      /* worker already gone */
     }
   }
-
   /** 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 {
+  reattach(streamId, pw, handler) {
     if (!this.handlers.has(streamId)) {
       pw.streamCount++;
       pw.streamIds.add(streamId);
     }
     this.handlers.set(streamId, handler);
   }
-
-  send(pw: PoolWorker, msg: ToWorker): void {
+  send(pw, msg) {
     pw.worker.postMessage(msg);
   }
-
   /** Resolves when the given worker has finished WASM init; rejects if it failed. */
-  whenWorkerReady(pw: PoolWorker): Promise<void> {
+  whenWorkerReady(pw) {
     if (pw.ready) return Promise.resolve();
     if (pw.failed) return Promise.reject(pw.failed);
     return new Promise((resolve, reject) => pw.readyWaiters.push({ resolve, reject }));
   }
-
   /**
    * 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
@@ -160,57 +77,51 @@ export class FluxPool {
    * finished initializing WASM; rejects if init fails fatally. Browser-only (it
    * constructs a `Worker`).
    */
-  warm(): Promise<void> {
+  warm() {
     const live = this.workers.filter((w) => !w.failed);
     const pw = live[0] ?? this.create();
     return this.whenWorkerReady(pw);
   }
-
   /** Terminate every worker (test teardown / full shutdown). */
-  disposeAll(): void {
+  disposeAll() {
     for (const pw of this.workers) {
       try {
         pw.worker.terminate();
       } catch {
-        /* ignore */
       }
     }
     this.workers = [];
     this.handlers.clear();
   }
-
-  get workerCount(): number {
+  get workerCount() {
     return this.workers.length;
   }
-
   // Create a new worker while under cap and every live worker is busy; otherwise
   // attach to the least-loaded LIVE worker. A fatally-failed worker is never
   // handed out (a stream on it would post into a dead worker and hang) — it is
   // retained only to reject outstanding whenWorkerReady waiters.
-  private pick(): PoolWorker {
+  pick() {
     const live = this.workers.filter((w) => !w.failed);
     if (this.workers.length < this.cap && live.every((w) => w.streamCount > 0)) {
       return this.create();
     }
     if (live.length === 0) return this.create();
-    return live.reduce((a, b) => (b.streamCount < a.streamCount ? b : a));
+    return live.reduce((a, b) => b.streamCount < a.streamCount ? b : a);
   }
-
-  private create(): PoolWorker {
-    const pw: PoolWorker = {
+  create() {
+    const pw = {
       worker: this.factory(),
       ready: false,
       failed: null,
       streamCount: 0,
-      streamIds: new Set(),
-      readyWaiters: [],
+      streamIds: /* @__PURE__ */ new Set(),
+      readyWaiters: []
     };
     pw.worker.addEventListener("message", (ev) => this.onMessage(pw, ev.data));
     this.workers.push(pw);
     return pw;
   }
-
-  private onMessage(pw: PoolWorker, msg: FromWorker): void {
+  onMessage(pw, msg) {
     if (msg.type === "ready") {
       pw.ready = true;
       const waiters = pw.readyWaiters;
@@ -219,10 +130,6 @@ export class FluxPool {
       return;
     }
     if (msg.type === "error" && msg.fatal) {
-      // A fatal (WASM-init) failure dooms every stream on this worker. Reject
-      // anyone awaiting readiness, then notify each live stream's client so its
-      // onError fires — the message carries no real streamId to route by. The
-      // worker is kept only to reject those waiters; pick() never reuses it.
       const err = new Error(msg.message);
       pw.failed = err;
       const waiters = pw.readyWaiters;
@@ -231,91 +138,63 @@ export class FluxPool {
         try {
           w.reject(err);
         } catch {
-          /* a waiter's rejection handler is the caller's problem, not ours */
         }
       }
       for (const sid of pw.streamIds) this.dispatch(sid, msg);
+      try {
+        pw.worker.terminate();
+      } catch {
+      }
+      const idx = this.workers.indexOf(pw);
+      if (idx !== -1) this.workers.splice(idx, 1);
       return;
     }
     this.dispatch(msg.streamId, msg);
   }
-
   // Route a message to a stream's handler, isolating a throwing client callback
   // (e.g. a user-supplied onError) so it can neither break the worker message
   // loop nor starve sibling streams sharing this worker.
-  private dispatch(streamId: number, msg: FromWorker): void {
+  dispatch(streamId, msg) {
     try {
       this.handlers.get(streamId)?.(msg);
     } catch (e) {
-      // eslint-disable-next-line no-console
       console.error("flux: stream message handler threw", e);
     }
   }
 }
-
-function poolCap(): number {
+function poolCap() {
   const hc = typeof navigator !== "undefined" ? navigator.hardwareConcurrency : 0;
   return Math.min(hc || 4, 8);
 }
-
-let defaultPool: FluxPool | null = null;
-
-/** The process-wide default pool every `FluxClient` shares unless given one. */
-export function getDefaultPool(): FluxPool {
+let defaultPool = null;
+function getDefaultPool() {
   if (!defaultPool) {
     defaultPool = new FluxPool(
-      () => new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }) as unknown as WorkerLike,
-      poolCap(),
+      () => new Worker(new URL("./worker.js", import.meta.url), { type: "module" }),
+      poolCap()
     );
   }
   return defaultPool;
 }
-
-/** 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 function __resetDefaultPool(): void {
+function __resetDefaultPool() {
   defaultPool = null;
 }
-
-// --------------------------------------------------------------------------
-// Client
-// --------------------------------------------------------------------------
-
-/**
- * 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 class FluxClient {
-  private pool: FluxPool;
-  private pw: PoolWorker | null = null;
-  private streamId = 0;
-  private config?: ParserConfig;
-  private configSent = false;
-  private listeners = new Set<() => void>();
-  private store: BlockStore = emptyBlockStore();
-  private onError?: (err: { message: string; fatal?: boolean }) => void;
-  private onBlock?: (block: Block) => void;
-  private attached = true;
+class FluxClient {
+  pool;
+  pw = null;
+  streamId = 0;
+  config;
+  configSent = false;
+  listeners = /* @__PURE__ */ new Set();
+  store = emptyBlockStore();
+  onError;
+  onBlock;
+  attached = true;
   // Diff baseline for setContent(): the full string fed in so far, and whether
   // it has been finalized. Cleared by reset()/reattach() (the worker drops the
   // parser there, so the baseline is stale and the document must be re-fed).
-  private lastContent = "";
-  private contentDone = false;
-
+  lastContent = "";
+  contentDone = false;
   // Opt-in rAF coalescing (see constructor `coalesce`). When on AND
   // requestAnimationFrame exists, intra-frame emit()s collapse into ONE
   // rAF-scheduled flush to listeners — the React useSyncExternalStore path then
@@ -324,26 +203,29 @@ export class FluxClient {
   // reference-stable, so a dropped intermediate notify only skips a tail-only
   // render that the next flush supersedes. The finalize/done patch is exempt and
   // flushes synchronously, never deferred to the next frame.
-  private coalesce = false;
-  private rafHandle: number | null = null;
+  coalesce = false;
+  rafHandle = null;
   // Set by finalize(); the next patch's emit flushes synchronously (a 'done'
-  // notification must not be deferred a frame) and clears it.
-  private finalizePending = false;
-
+  // notification must not be deferred a frame) and clears it. Belt-and-suspenders
+  // alongside the per-patch `final` flag, which is the authoritative signal.
+  finalizePending = false;
+  // Stream generation, bumped on reset(). Stamped on every worker message and
+  // echoed back on each patch; a patch whose epoch is older than this is a
+  // pre-reset straggler and is dropped before it can repopulate the cleared store.
+  epoch = 0;
   // Perf
-  private appendedBytes = 0;
-  private patchCount = 0;
-  private totalParseMicros = 0;
-  private lastPatchMs = 0;
-  private firstAppendMs = 0;
-  private retainedBytes = 0;
-  private wasmMemoryBytes = 0;
+  appendedBytes = 0;
+  patchCount = 0;
+  totalParseMicros = 0;
+  lastPatchMs = 0;
+  firstAppendMs = 0;
+  retainedBytes = 0;
+  wasmMemoryBytes = 0;
   // Render-path observability (advanced ONLY when an onRenderMetrics hook is
   // wired into a renderer; zero-cost otherwise). renderCount = React BlockView
   // body renders; rebuildCount = DOM node rebuilds.
-  private renderCount = 0;
-  private rebuildCount = 0;
-
+  renderCount = 0;
+  rebuildCount = 0;
   /**
    * @param options.pool   worker pool to join (defaults to the shared
    *   process-wide pool — pass a dedicated `FluxPool` only for isolation).
@@ -365,22 +247,13 @@ export class FluxClient {
    *   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;
-    } = {},
-  ) {
+  constructor(options = {}) {
     this.pool = options.pool ?? getDefaultPool();
     this.config = options.config;
     this.onError = options.onError;
     this.onBlock = options.onBlock;
     this.coalesce = options.coalesce ?? false;
   }
-
   /**
    * 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
@@ -396,46 +269,39 @@ export class FluxClient {
    * 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(): PoolWorker {
-    if (this.pw) return this.pw;
+  ensureAcquired() {
+    if (this.pw && !this.pw.failed) return this.pw;
+    this.pw = null;
     const { streamId, pw } = this.pool.acquire((msg) => this.onMessage(msg));
     this.streamId = streamId;
     this.pw = pw;
     return pw;
   }
-
-  get ready(): boolean {
+  get ready() {
     return this.pw?.ready ?? false;
   }
-
-  whenReady(): Promise<void> {
+  whenReady() {
     const pw = this.ensureAcquired();
     return this.pool.whenWorkerReady(pw);
   }
-
   // The config rides on the first message a stream sends; the worker applies it
   // when it creates the parser. postMessage is FIFO per worker, so it always
   // lands before any append is processed. Returns undefined after the first use.
-  private firstConfig(): ParserConfig | undefined {
-    if (this.configSent || !this.config) return undefined;
+  firstConfig() {
+    if (this.configSent || !this.config) return void 0;
     this.configSent = true;
     return this.config;
   }
-
-  append(chunk: string) {
+  append(chunk) {
     const pw = this.ensureAcquired();
     if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
-    this.pool.send(pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig() });
+    this.pool.send(pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig(), epoch: this.epoch });
   }
-
   finalize() {
     const pw = this.ensureAcquired();
-    // The terminal patch this triggers must reach subscribers synchronously, not
-    // a frame late — mark it so the next emit flushes now even under coalescing.
     this.finalizePending = true;
-    this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig() });
+    this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig(), epoch: this.epoch });
   }
-
   /**
    * Pipe a source straight in: read it to completion, `append()` each chunk,
    * then `finalize()`. The LLM-native path — e.g.
@@ -453,60 +319,46 @@ export class FluxClient {
    * finalized (or cleanly on abort); rejects if the source itself errors.
    * Browser-only for byte sources (uses `TextDecoder`).
    */
-  async pipeFrom(
-    source: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
-    opts?: { signal?: AbortSignal },
-  ): Promise<void> {
+  async pipeFrom(source, opts) {
     const signal = opts?.signal;
-
-    if (signal?.aborted) return; // already superseded before we started
-
-    // AsyncIterable<string> (SSE deltas, generators). Detected by elimination:
-    // a ReadableStream has `getReader`, a Response has `body` — neither here.
+    if (signal?.aborted) return;
     if (!("getReader" in source) && !("body" in source)) {
-      for await (const chunk of source as AsyncIterable<string>) {
-        if (signal?.aborted) return; // superseded/unmounted: drop late chunks, no finalize
+      for await (const chunk of source) {
+        if (signal?.aborted) return;
         this.append(chunk);
       }
       if (!signal?.aborted) this.finalize();
       return;
     }
-
-    // Byte source: a Response (use its body) or a ReadableStream directly.
     const body = "body" in source ? source.body : source;
     if (!body) {
-      // An empty Response body (e.g. 204) is a completed, empty stream.
       this.finalize();
       return;
     }
     const reader = body.getReader();
-    // A pending read() can't observe `aborted` until the next chunk; cancel()
-    // on abort tears down the upstream and resolves the pending read so the
-    // loop's post-read check fires and bails without finalizing.
     const onAbort = () => {
-      reader.cancel().catch(() => {});
+      reader.cancel().catch(() => {
+      });
     };
     signal?.addEventListener("abort", onAbort, { once: true });
     const decoder = new TextDecoder();
     try {
-      for (;;) {
+      for (; ; ) {
         const { done, value } = await reader.read();
-        if (signal?.aborted) return; // superseded: no finalize (cancel already fired)
+        if (signal?.aborted) return;
         if (done) break;
         if (value) this.append(decoder.decode(value, { stream: true }));
       }
-      this.append(decoder.decode()); // flush any trailing partial sequence
+      this.append(decoder.decode());
       this.finalize();
     } finally {
       signal?.removeEventListener("abort", onAbort);
       try {
         reader.releaseLock();
       } catch {
-        /* already released (e.g. by cancel) */
       }
     }
   }
-
   /**
    * 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
@@ -532,17 +384,12 @@ export class FluxClient {
    * 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 }) {
+  setContent(content, opts) {
     if (content !== this.lastContent) {
-      // Fast path appends the delta into the EXISTING parser — but a parser that
-      // was already finalized ({ done: true }) is terminal: the core drops any
-      // further append. So gate the fast path on !contentDone; reopening a
-      // finalized stream (or any divergence) falls through to reset()+reparse,
-      // which frees the dead parser and rebuilds a fresh one.
       if (!this.contentDone && content.startsWith(this.lastContent)) {
         this.append(content.slice(this.lastContent.length));
       } else {
-        this.reset(); // diverged, or reopening a finalized stream — rebuild
+        this.reset();
         this.append(content);
       }
       this.lastContent = content;
@@ -553,12 +400,7 @@ export class FluxClient {
       this.contentDone = true;
     }
   }
-
   reset() {
-    // Only notify subscribers if there was content to clear: resetting an
-    // already-empty store leaves the view empty either way, so skip the no-op
-    // emit (which would otherwise drive every subscriber through a wasted,
-    // output-identical render pass).
     const hadContent = this.store.snapshot.length > 0;
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
@@ -568,33 +410,23 @@ export class FluxClient {
     this.firstAppendMs = 0;
     this.retainedBytes = 0;
     this.wasmMemoryBytes = 0;
-    this.lastContent = ""; // setContent baseline: the worker drops the parser here
+    this.lastContent = "";
     this.contentDone = false;
-    // A frame coalesced from the just-cleared stream is now stale — cancel it so
-    // it can't fire a notify referencing content reset() just dropped.
     this.cancelFrame();
     this.finalizePending = false;
-    // Same streamId + worker — the worker frees and lazily recreates the parser.
+    this.epoch += 1;
     const pw = this.ensureAcquired();
-    this.pool.send(pw, { type: "reset", streamId: this.streamId });
-    if (hadContent) this.emit(true); // clear-the-view notify is synchronous
+    this.pool.send(pw, { type: "reset", streamId: this.streamId, epoch: this.epoch });
+    if (hadContent) this.emit(true);
   }
-
   destroy() {
-    if (!this.attached) return; // idempotent
-    // Free this stream's parser; the shared worker stays warm for siblings.
-    // Only release a real slot — a never-acquired client (constructed during an
-    // SSR render then unmounted) has no pool slot to free, so skip the call.
-    // We deliberately do NOT null this.pw here: StrictMode's destroy()→reattach()
-    // on the SAME instance needs the same pw/streamId to re-register.
+    if (!this.attached) return;
     if (this.pw) this.pool.release(this.streamId, this.pw);
-    // Drop any pending coalesced frame so it can't fire into cleared listeners.
     this.cancelFrame();
     this.finalizePending = false;
     this.listeners.clear();
     this.attached = false;
   }
-
   /**
    * Re-register with the pool after {@link destroy} so the client receives
    * patches again. Needed only for React StrictMode's dev double-mount, where
@@ -603,61 +435,46 @@ export class FluxClient {
    */
   reattach() {
     if (this.attached) return;
-    // The prior destroy()→dispose dropped this stream's parser, so setContent's
-    // diff baseline is stale — clear it so the next setContent re-feeds the whole
-    // document (StrictMode dev double-mount on the SAME instance).
     this.lastContent = "";
     this.contentDone = false;
     if (!this.pw) {
-      // Never acquired (e.g. constructed during SSR, first real mount on client).
-      // No prior pool slot to re-register; just mark attached. The next
-      // worker-bound op acquires lazily. configSent is already false, so the
-      // first append will carry config exactly as a brand-new client would.
       this.attached = true;
       return;
     }
     this.pool.reattach(this.streamId, this.pw, (msg) => this.onMessage(msg));
     this.attached = true;
-    // The worker discarded this stream's config on `dispose` (unlike `reset`,
-    // which keeps it), so re-send it on the next message — otherwise the parser
-    // would be rebuilt with library defaults (gfmMath / componentTags / … lost).
     this.configSent = false;
   }
-
-  subscribe = (fn: () => void) => {
+  subscribe = (fn) => {
     this.listeners.add(fn);
     return () => this.listeners.delete(fn);
   };
-
-  getSnapshot = (): Block[] => this.store.snapshot;
-
+  getSnapshot = () => this.store.snapshot;
   /**
    * 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 {
+  __noteRender() {
     this.renderCount++;
   }
-
   /**
    * 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 {
+  __noteRebuild() {
     this.rebuildCount++;
   }
-
   getMetrics() {
     const elapsed = this.firstAppendMs ? Math.max(1, performance.now() - this.firstAppendMs) : 1;
     return {
       bytes: this.appendedBytes,
       patches: this.patchCount,
       meanParseMicros: this.patchCount > 0 ? this.totalParseMicros / this.patchCount : 0,
-      totalParseMs: this.totalParseMicros / 1000,
-      throughputKBs: (this.appendedBytes / 1024) / (elapsed / 1000),
+      totalParseMs: this.totalParseMicros / 1e3,
+      throughputKBs: this.appendedBytes / 1024 / (elapsed / 1e3),
       committedBlocks: this.store.committed.size,
       activeBlocks: this.store.active.length,
       lastPatchAgoMs: this.lastPatchMs === 0 ? 0 : performance.now() - this.lastPatchMs,
@@ -670,31 +487,25 @@ export class FluxClient {
       // renderer): renderCount = React block-body renders, rebuildCount = DOM
       // node rebuilds. Committed blocks memo-skip, so they contribute once.
       renderCount: this.renderCount,
-      rebuildCount: this.rebuildCount,
+      rebuildCount: this.rebuildCount
     };
   }
-
   /**
    * 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[] {
-    const out: OutlineEntry[] = [];
+  outline() {
+    const out = [];
     for (const b of this.store.snapshot) {
       if (b.kind.type === "Heading") {
-        // `kind.data` is the bare level `number` when `blockData` is off, or the
-        // `{ level, text, id }` object when on — accept both. `OutlineEntry.id`
-        // stays the numeric block id (stable, non-breaking); the anchor slug is
-        // reachable additively via `kind.data.id` for consumers who want it.
-        const d = b.kind.data as number | { level?: number } | undefined;
+        const d = b.kind.data;
         const level = typeof d === "number" ? d : d?.level ?? 1;
         out.push({ level, text: htmlToText(b.html), id: b.id });
       }
     }
     return out;
   }
-
   /**
    * The rendered document as plain text — tags stripped, entities decoded,
    * blocks separated by blank lines. Derived from the rendered HTML (the source
@@ -702,48 +513,51 @@ export class FluxClient {
    * readable approximation for search indexing / summaries, not a round-trip of
    * the original source.
    */
-  toPlaintext(): string {
-    const parts: string[] = [];
+  toPlaintext() {
+    const parts = [];
     for (const b of this.store.snapshot) {
       const t = htmlToText(b.html);
       if (t) parts.push(t);
     }
     return parts.join("\n\n");
   }
-
-  private onMessage(msg: FromWorker) {
+  onMessage(msg) {
     switch (msg.type) {
-      case "patch":
-        applyPatch(this.store, msg.patch);
+      case "patch": {
+        if (msg.epoch !== void 0 && msg.epoch < this.epoch) break;
+        let patch;
+        try {
+          patch = JSON.parse(msg.patch);
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          if (this.onError) this.onError({ message: `flux: malformed patch (${message})` });
+          else console.error("flux: malformed patch:", message);
+          break;
+        }
+        applyPatch(this.store, patch);
         this.appendedBytes = msg.appendedBytes;
         this.totalParseMicros += msg.parseMicros;
         this.retainedBytes = msg.retainedBytes;
         this.wasmMemoryBytes = msg.wasmMemoryBytes;
         this.patchCount += 1;
         this.lastPatchMs = performance.now();
-        // The post-finalize (done) patch must notify synchronously — never defer
-        // stream completion to the next frame. One-shot: cleared after use.
-        const sync = this.finalizePending;
+        const sync = this.finalizePending || msg.final === true;
         this.finalizePending = false;
         this.emit(sync);
-        // After subscribers see the new snapshot, fire the per-block hook for
-        // anything that just committed (document order). A throw here is
-        // isolated by the pool's dispatch boundary and won't skip emit().
         if (this.onBlock) {
-          for (const b of msg.patch.newly_committed) this.onBlock(b);
+          for (const b of patch.newly_committed) this.onBlock(b);
         }
         break;
+      }
       case "error":
         if (this.onError) {
           this.onError({ message: msg.message, fatal: msg.fatal });
         } else {
-          // eslint-disable-next-line no-console
           console.error("flux worker error:", msg.message);
         }
         break;
     }
   }
-
   /**
    * Notify subscribers of a new snapshot.
    *
@@ -753,29 +567,33 @@ export class FluxClient {
    * 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(sync = false) {
+  emit(sync = false) {
     if (this.coalesce && !sync && typeof requestAnimationFrame === "function") {
-      if (this.rafHandle !== null) return; // a flush is already scheduled this frame
+      if (this.rafHandle !== null) return;
       this.rafHandle = requestAnimationFrame(() => {
         this.rafHandle = null;
         this.flushNow();
       });
       return;
     }
-    // Synchronous path: drop any pending frame so its notify can't double-fire
-    // after this one, then flush immediately.
     this.cancelFrame();
     this.flushNow();
   }
-
-  private flushNow() {
+  flushNow() {
     for (const fn of this.listeners) fn();
   }
-
-  private cancelFrame() {
+  cancelFrame() {
     if (this.rafHandle !== null) {
       if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(this.rafHandle);
       this.rafHandle = null;
     }
   }
 }
+export {
+  FluxClient,
+  FluxPool,
+  __resetDefaultPool,
+  applyPatch,
+  emptyBlockStore,
+  getDefaultPool
+};