brookmd 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ Notable changes to brookmd (formerly `flux-md`). Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## 0.24.0 — 2026-07-24
+
+### Added
+
+- **Worker load failures are now detected and self-heal.** A worker script
+  that fails to load (e.g. a stale hashed worker URL held by an already-open
+  tab after a redeploy) fires a DOM `error` event instead of ever posting a
+  message; previously nothing listened, so the client waited forever and the
+  container stayed permanently empty with no console output. The pool now
+  listens for `error`/`messageerror`, arms a per-worker boot deadline
+  (default 20s, configurable/disable-able via the `BrookPool` options), and
+  routes every fatal trigger — WASM init failure, load error, deserialization
+  error, deadline — through one idempotent failure path: pending waiters
+  reject, each affected client's `onError` fires, and the dead worker is
+  terminated and evicted so the pool capacity recovers.
+- **One-shot automatic recovery.** A client whose worker dies transiently
+  heals invisibly: the driven document accumulates in a recovery buffer (both
+  `setContent` and `append`/`pipeFrom` modes) and is re-fed once to a fresh
+  worker through the preserved-view swap path, so the rendered view never
+  blanks and in-flight chunks are folded in safely. Recovery re-arms only
+  when the caller advances the content, so a document that deterministically
+  crashes the parser surfaces an error after exactly one retry instead of
+  respawning workers. Opt out with `new BrookClient({ recovery: false })`
+  for memory-sensitive giant documents.
+- **`client.failed: Error | null`** — synchronous getter for terminal worker
+  failure (stays `null` through a successful invisible heal), for rendering a
+  degraded fallback.
+- **React hooks error surface.** `useBrookStream`'s `onError` now also
+  receives worker-level errors (with a `fatal` flag on the `Error`), and
+  `useBrookMarkdownString` gains an `onError` option; both default to
+  `console.error`.
+
+### Fixed
+
+- Fatally failed workers no longer leak their per-stream handler-map entries
+  in the pool.
+
 ## 0.23.2 — 2026-07-22
 
 ### Fixed

package/README.md

@@ -555,7 +555,9 @@ class BrookClient {
     config?: ParserConfig;
     onError?: (err: { message: string; fatal?: boolean }) => void; // worker/parse + WASM-init errors
     onBlock?: (block: Block) => void;                 // fires once per block as it commits
+    recovery?: boolean;                               // auto-heal a transient worker death (default true)
   });
+  get failed(): Error | null;                       // terminal worker failure, else null (null through heals)
   append(chunk: string): void;                      // queue text for parsing
   pipeFrom(                                         // read → append → finalize
     src: ReadableStream<Uint8Array> | Response | AsyncIterable<string>,
@@ -591,6 +593,16 @@ failure (`{ fatal: true }`); without it, errors are only `console.error`'d and a
 load failure surfaces as a rejected `whenReady()`. Pass `onBlock` to run a side
 effect each time a block commits (e.g. lazy-highlight a finished code block).
 
+A **transient worker death** heals invisibly by default: if a worker dies
+mid-stream (e.g. a stale hashed worker URL 404s after a redeploy), the client
+buffers the driven document, re-acquires a fresh worker, and re-feeds it once —
+the view stays on screen and `onError` does **not** fire. Only if the replacement
+also dies is the failure terminal (`onError` with `{ fatal: true }`, and
+`client.failed` becomes the `Error`; it is `null` while healthy and through a
+successful heal). Set `recovery: false` to disable the buffer and auto-recovery
+(a fatal death is then immediately terminal) — worth it for memory-sensitive,
+very large documents where retaining the full source is undesirable.
+
 #### Per-stream config
 
 ```ts

package/dist/client.d.ts

@@ -30,7 +30,9 @@ 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. */
+    /** Set once the worker fails fatally (WASM init, a DOM load `error`, a
+     *  `messageerror`, or the boot deadline); whenWorkerReady rejects with this
+     *  thereafter. */
     failed: Error | null;
     streamCount: number;
     /** Live stream ids on this worker — so a fatal failure can notify each one. */
@@ -39,6 +41,10 @@ interface PoolWorker {
         resolve: () => void;
         reject: (e: Error) => void;
     }>;
+    /** Handle for the boot deadline that fails a worker which never reports ready.
+     *  Opaque (a `number` in the browser, a `Timeout` in Node/bun, or a test
+     *  fake's id) — cleared on ready, on failure, and on pool disposal. */
+    bootTimer: unknown;
 }
 /**
  * A pool of Web Workers, each multiplexing many `BrookParser`s keyed by stream
@@ -59,7 +65,14 @@ export declare class BrookPool {
     private workers;
     private handlers;
     private nextStreamId;
-    constructor(factory: () => WorkerLike, cap: number);
+    private bootTimeoutMs;
+    private startTimer;
+    private cancelTimer;
+    constructor(factory: () => WorkerLike, cap: number, options?: {
+        bootTimeoutMs?: number;
+        setTimeout?: (fn: () => void, ms: number) => unknown;
+        clearTimeout?: (handle: unknown) => void;
+    });
     /** Reserve a stream id and assign a worker, registering its message handler. */
     acquire(handler: (msg: FromWorker) => void): {
         streamId: number;
@@ -88,9 +101,30 @@ export declare class BrookPool {
     /** Terminate every worker (test teardown / full shutdown). */
     disposeAll(): void;
     get workerCount(): number;
+    /** Live stream→handler registrations. Introspection for tests/diagnostics —
+     *  a fatal failure reaps the dead worker's entries, so this must not grow
+     *  across a worker death + recovery cycle. */
+    get handlerCount(): number;
     private pick;
     private create;
+    private startBootTimer;
+    private clearBootTimer;
     private onMessage;
+    /**
+     * Idempotent fatal-failure handler shared by every trigger: an in-band
+     * `{type:"error",fatal:true}` (WASM init), a DOM load `error`, a
+     * `messageerror`, and the boot deadline. First cause wins; later calls no-op.
+     *
+     * A fatally failed worker dooms every stream on it. Reject anyone awaiting
+     * readiness, then dispatch a synthetic fatal error to each live stream so its
+     * client's `onError` fires exactly as for a WASM-init fatal (the message
+     * carries no real streamId to route by). Finally evict the worker: terminate
+     * it and drop it from the pool — a dead worker can never parse again, so
+     * retaining it would leak an OS thread per failure and keep counting against
+     * `cap` until pick()'s cap branch dies and spawns workers unbounded. Reaping
+     * restores the cap and lets a fresh worker be made.
+     */
+    private fail;
     private dispatch;
 }
 /** The process-wide default pool every `BrookClient` shares unless given one. */
@@ -129,6 +163,11 @@ export declare class BrookClient {
     private attached;
     private lastContent;
     private contentDone;
+    private failedError;
+    private recovery;
+    private recoveryBuffer;
+    private recoveredLen;
+    private recoveryAttempted;
     private coalesce;
     private rafHandle;
     private finalizePending;
@@ -170,6 +209,14 @@ export declare class BrookClient {
      *   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.
+     * @param options.recovery opt-out (default `true`): transparently heal a
+     *   TRANSIENT worker death. The client buffers the full driven document and, on
+     *   a fatal worker failure, re-acquires a fresh worker and re-feeds it exactly
+     *   once — the displayed view stays on screen, so a worker that 404s after a
+     *   redeploy (or otherwise dies mid-stream) recovers invisibly instead of
+     *   freezing the render. If the replacement ALSO dies the error surfaces
+     *   (`failed` / `onError`). Set `false` to disable both the buffering and the
+     *   auto-recovery — a fatal failure then goes straight to terminal.
      */
     constructor(options?: {
         pool?: BrookPool;
@@ -180,6 +227,7 @@ export declare class BrookClient {
         }) => void;
         onBlock?: (block: Block) => void;
         coalesce?: boolean;
+        recovery?: boolean;
     });
     /**
      * Lazily reserve this client's stream id and bind it to a pool worker. The
@@ -198,6 +246,17 @@ export declare class BrookClient {
      */
     private ensureAcquired;
     get ready(): boolean;
+    /**
+     * The fatal error that killed this client's worker, or `null` if healthy.
+     *
+     * Non-null only once a failure is TERMINAL: a worker that died with recovery
+     * off or nothing buffered to re-feed, or a client (either mode) whose one-shot
+     * auto-recovery re-feed ALSO hit a dying worker. It stays `null` throughout a
+     * successful transient recovery (the death heals invisibly) and is cleared
+     * again by {@link reset}. Pairs with `onError`, which fires on the same
+     * terminal failure.
+     */
+    get failed(): Error | null;
     whenReady(): Promise<void>;
     private firstConfig;
     append(chunk: string): void;
@@ -354,6 +413,29 @@ export declare class BrookClient {
      */
     toPlaintext(): string;
     private onMessage;
+    private reportError;
+    /**
+     * One-shot self-heal after a transient worker death, for BOTH drive modes.
+     * The dead worker was already evicted, so redriving the buffered document
+     * re-acquires a FRESH worker (ensureAcquired re-acquires because the old
+     * `pw.failed` is set). Reads the buffer at EXECUTION time, so a chunk that
+     * interleaved ahead of this microtask is included. Deliberately does NOT route
+     * through setContent(): that would stamp `lastContent`, flipping an append-mode
+     * client into setContent mode, and a second death would then re-feed a stale
+     * `lastContent` missing post-recovery chunks. `recoveryAttempted` is NOT reset
+     * here — if the replacement also dies before healing, the fatal path sees the
+     * flag still set and surfaces the error instead of looping.
+     */
+    private recover;
+    /**
+     * Rebuild the parser onto a fresh worker and re-feed `doc` as one atomic
+     * append (re-accumulating recoveryBuffer). Keeps the displayed view on screen
+     * across the swap by softReset-ing when something is rendered, so the document
+     * never blanks; falls back to a bare resetParser when the store is empty.
+     * Uses resetParser / softReset (NOT reset(), which would clear the one-shot
+     * recovery guards mid-heal). Re-finalizes when the buffered doc was finalized.
+     */
+    private refeed;
     /**
      * Notify subscribers of a new snapshot.
      *

package/dist/client.js

@@ -33,15 +33,27 @@ function applyPatch(store, patch) {
   store.snapshot = next;
 }
 class BrookPool {
-  constructor(factory, cap) {
+  constructor(factory, cap, options = {}) {
     this.factory = factory;
     this.cap = cap;
+    this.bootTimeoutMs = options.bootTimeoutMs ?? 2e4;
+    this.startTimer = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    this.cancelTimer = options.clearTimeout ?? ((h) => clearTimeout(h));
   }
   factory;
   cap;
   workers = [];
   handlers = /* @__PURE__ */ new Map();
   nextStreamId = 1;
+  // Per-worker boot deadline: if a worker reports neither ready nor a fatal
+  // failure within this window it is failed with a clear message — the miss that
+  // otherwise leaves `<div class="brook-md">` permanently empty (a stale hashed
+  // worker URL 404s after a redeploy: the DOM fires `error`, but a browser that
+  // somehow swallowed it would hang forever). `0` / non-finite disables it.
+  bootTimeoutMs;
+  // Timer machinery, injectable so the deadline is testable with fake timers.
+  startTimer;
+  cancelTimer;
   /** Reserve a stream id and assign a worker, registering its message handler. */
   acquire(handler) {
     const streamId = this.nextStreamId++;
@@ -98,6 +110,7 @@ class BrookPool {
   /** Terminate every worker (test teardown / full shutdown). */
   disposeAll() {
     for (const pw of this.workers) {
+      this.clearBootTimer(pw);
       try {
         pw.worker.terminate();
       } catch {
@@ -109,6 +122,12 @@ class BrookPool {
   get workerCount() {
     return this.workers.length;
   }
+  /** Live stream→handler registrations. Introspection for tests/diagnostics —
+   *  a fatal failure reaps the dead worker's entries, so this must not grow
+   *  across a worker death + recovery cycle. */
+  get handlerCount() {
+    return this.handlers.size;
+  }
   // 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
@@ -128,41 +147,96 @@ class BrookPool {
       failed: null,
       streamCount: 0,
       streamIds: /* @__PURE__ */ new Set(),
-      readyWaiters: []
+      readyWaiters: [],
+      bootTimer: null
     };
+    try {
+      pw.worker.addEventListener("error", (ev) => {
+        const detail = ev.message;
+        this.fail(pw, new Error(`brookmd worker failed to load${detail ? `: ${detail}` : ""}`));
+      });
+    } catch {
+    }
+    try {
+      pw.worker.addEventListener("messageerror", () => {
+        this.fail(pw, new Error("brookmd worker message could not be deserialized"));
+      });
+    } catch {
+    }
     pw.worker.addEventListener("message", (ev) => this.onMessage(pw, ev.data));
     this.workers.push(pw);
+    this.startBootTimer(pw);
     return pw;
   }
+  // Arm the per-worker boot deadline (no-op when disabled). Uses the injected
+  // timer so tests drive it deterministically, and `.unref()`s the handle (when
+  // present) so a pending deadline never keeps a Node/bun process alive.
+  startBootTimer(pw) {
+    if (!(this.bootTimeoutMs > 0) || !Number.isFinite(this.bootTimeoutMs)) return;
+    const timer = this.startTimer(() => {
+      if (!pw.ready && !pw.failed) {
+        this.fail(pw, new Error(`brookmd worker did not become ready within ${this.bootTimeoutMs}ms`));
+      }
+    }, this.bootTimeoutMs);
+    timer?.unref?.();
+    pw.bootTimer = timer;
+  }
+  clearBootTimer(pw) {
+    if (pw.bootTimer !== null) {
+      this.cancelTimer(pw.bootTimer);
+      pw.bootTimer = null;
+    }
+  }
   onMessage(pw, msg) {
     if (msg.type === "ready") {
       pw.ready = true;
+      this.clearBootTimer(pw);
       const waiters = pw.readyWaiters;
       pw.readyWaiters = [];
       for (const w of waiters) w.resolve();
       return;
     }
     if (msg.type === "error" && msg.fatal) {
-      const err = new Error(msg.message);
-      pw.failed = err;
-      const waiters = pw.readyWaiters;
-      pw.readyWaiters = [];
-      for (const w of waiters) {
-        try {
-          w.reject(err);
-        } catch {
-        }
-      }
-      for (const sid of pw.streamIds) this.dispatch(sid, msg);
+      this.fail(pw, new Error(msg.message));
+      return;
+    }
+    this.dispatch(msg.streamId, msg);
+  }
+  /**
+   * Idempotent fatal-failure handler shared by every trigger: an in-band
+   * `{type:"error",fatal:true}` (WASM init), a DOM load `error`, a
+   * `messageerror`, and the boot deadline. First cause wins; later calls no-op.
+   *
+   * A fatally failed worker dooms every stream on it. Reject anyone awaiting
+   * readiness, then dispatch a synthetic fatal error to each live stream so its
+   * client's `onError` fires exactly as for a WASM-init fatal (the message
+   * carries no real streamId to route by). Finally evict the worker: terminate
+   * it and drop it from the pool — a dead worker can never parse again, so
+   * retaining it would leak an OS thread per failure and keep counting against
+   * `cap` until pick()'s cap branch dies and spawns workers unbounded. Reaping
+   * restores the cap and lets a fresh worker be made.
+   */
+  fail(pw, err) {
+    if (pw.failed) return;
+    pw.failed = err;
+    this.clearBootTimer(pw);
+    const waiters = pw.readyWaiters;
+    pw.readyWaiters = [];
+    for (const w of waiters) {
       try {
-        pw.worker.terminate();
+        w.reject(err);
       } catch {
       }
-      const idx = this.workers.indexOf(pw);
-      if (idx !== -1) this.workers.splice(idx, 1);
-      return;
     }
-    this.dispatch(msg.streamId, msg);
+    const msg = { type: "error", streamId: -1, message: err.message, fatal: true };
+    for (const sid of pw.streamIds) this.dispatch(sid, msg);
+    for (const sid of pw.streamIds) this.handlers.delete(sid);
+    try {
+      pw.worker.terminate();
+    } catch {
+    }
+    const idx = this.workers.indexOf(pw);
+    if (idx !== -1) this.workers.splice(idx, 1);
   }
   // 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
@@ -209,6 +283,41 @@ class BrookClient {
   // parser there, so the baseline is stale and the document must be re-fed).
   lastContent = "";
   contentDone = false;
+  // --- Worker-failure recovery ---
+  // The terminal fatal error for this client's stream: non-null once its worker
+  // failed AND (if a recovery was attempted) the replacement also failed. Null
+  // while a recovery is in flight / succeeded, and reset by reset(). Surfaced by
+  // the `failed` getter.
+  failedError = null;
+  // Whether auto-recovery (and the buffer that feeds it) is enabled — off by the
+  // `recovery: false` constructor option. When off, nothing is buffered and a
+  // fatal worker death is immediately terminal in BOTH modes.
+  recovery = true;
+  // The full document driven into this stream so far — accumulated in append()
+  // (so it captures BOTH manual append/pipeFrom AND setContent, which drives via
+  // append(delta)). It is the baseline re-fed after a transient worker death.
+  // resetParser() clears it and the ensuing re-feed rebuilds it, so it stays
+  // exactly equal to the live document on every path.
+  recoveryBuffer = "";
+  // Buffer length captured at the last completed re-feed. append()'s growth
+  // re-arm compares against it: once the caller drives the buffer PAST this, a
+  // future death may heal again. Set to Infinity while a recovery is pending
+  // (fatal → microtask) so a stray chunk arriving before recover() runs can't
+  // spuriously re-arm; set to the re-fed length once recover() completes. Its
+  // "!== Infinity" also stands in for "a recovery is outstanding" in the
+  // setContent divergence re-arm below.
+  recoveredLen = Infinity;
+  // One-shot guard: set when a fatal failure schedules an auto-recovery re-feed
+  // so a replacement worker that also dies is NOT retried a second time. Re-armed
+  // (cleared) only when the caller drives NEW content — never on a mere
+  // successful patch, because a finalize()-that-traps document emits an append
+  // patch before it re-traps, and re-arming there would loop the same poison doc
+  // through workers forever. Two complementary re-arm rules clear it: append()'s
+  // buffer-GROWTH check (streaming past the recovered length) and setContent()'s
+  // DIVERGENCE check (content differs from the re-fed buffer — catches a
+  // same-length-or-shorter replacement the growth check misses). Also cleared on
+  // an explicit caller reset().
+  recoveryAttempted = 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
@@ -287,6 +396,14 @@ class BrookClient {
    *   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.
+   * @param options.recovery opt-out (default `true`): transparently heal a
+   *   TRANSIENT worker death. The client buffers the full driven document and, on
+   *   a fatal worker failure, re-acquires a fresh worker and re-feeds it exactly
+   *   once — the displayed view stays on screen, so a worker that 404s after a
+   *   redeploy (or otherwise dies mid-stream) recovers invisibly instead of
+   *   freezing the render. If the replacement ALSO dies the error surfaces
+   *   (`failed` / `onError`). Set `false` to disable both the buffering and the
+   *   auto-recovery — a fatal failure then goes straight to terminal.
    */
   constructor(options = {}) {
     this.pool = options.pool ?? getDefaultPool();
@@ -294,6 +411,7 @@ class BrookClient {
     this.onError = options.onError;
     this.onBlock = options.onBlock;
     this.coalesce = options.coalesce ?? false;
+    this.recovery = options.recovery ?? true;
   }
   /**
    * Lazily reserve this client's stream id and bind it to a pool worker. The
@@ -321,6 +439,19 @@ class BrookClient {
   get ready() {
     return this.pw?.ready ?? false;
   }
+  /**
+   * The fatal error that killed this client's worker, or `null` if healthy.
+   *
+   * Non-null only once a failure is TERMINAL: a worker that died with recovery
+   * off or nothing buffered to re-feed, or a client (either mode) whose one-shot
+   * auto-recovery re-feed ALSO hit a dying worker. It stays `null` throughout a
+   * successful transient recovery (the death heals invisibly) and is cleared
+   * again by {@link reset}. Pairs with `onError`, which fires on the same
+   * terminal failure.
+   */
+  get failed() {
+    return this.failedError;
+  }
   whenReady() {
     const pw = this.ensureAcquired();
     return this.pool.whenWorkerReady(pw);
@@ -336,11 +467,18 @@ class BrookClient {
   append(chunk) {
     const pw = this.ensureAcquired();
     if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
+    if (this.recovery) {
+      this.recoveryBuffer += chunk;
+      if (this.recoveryAttempted && this.recoveryBuffer.length > this.recoveredLen) {
+        this.recoveryAttempted = false;
+      }
+    }
     this.pool.send(pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig(), epoch: this.epoch });
   }
   finalize() {
     const pw = this.ensureAcquired();
     this.finalizePending = true;
+    this.contentDone = true;
     this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig(), epoch: this.epoch });
   }
   /**
@@ -431,6 +569,9 @@ class BrookClient {
    * `components` instead, keeping the source append-only.
    */
   setContent(content, opts) {
+    if (this.recoveryAttempted && this.recoveredLen !== Infinity && content !== this.recoveryBuffer) {
+      this.recoveryAttempted = false;
+    }
     if (content !== this.lastContent) {
       if (!this.contentDone && content.startsWith(this.lastContent)) {
         if (this.lastContent === "" && content.length > 0 && this.getSnapshot().length > 0) {
@@ -456,6 +597,8 @@ class BrookClient {
     this.staleSnapshot = null;
     this.staleTrimmed = false;
     this.mergeCache = null;
+    this.failedError = null;
+    this.recoveryAttempted = false;
     this.resetParser();
     if (hadContent) this.emit(true);
   }
@@ -513,6 +656,8 @@ class BrookClient {
     this.wasmMemoryBytes = 0;
     this.lastContent = "";
     this.contentDone = false;
+    this.recoveryBuffer = "";
+    this.recoveredLen = Infinity;
     this.cancelFrame();
     this.finalizePending = false;
     this.epoch += 1;
@@ -717,15 +862,66 @@ class BrookClient {
         }
         break;
       }
-      case "error":
-        if (this.onError) {
-          this.onError({ message: msg.message, fatal: msg.fatal });
-        } else {
-          console.error("brookmd worker error:", msg.message);
+      case "error": {
+        if (!msg.fatal) {
+          this.reportError(msg.message, msg.fatal);
+          break;
         }
+        if (this.recovery && this.recoveryBuffer.length > 0 && !this.recoveryAttempted) {
+          this.recoveryAttempted = true;
+          this.recoveredLen = Infinity;
+          queueMicrotask(() => this.recover());
+          break;
+        }
+        this.failedError = new Error(msg.message);
+        this.reportError(msg.message, msg.fatal);
         break;
+      }
+    }
+  }
+  // Surface a worker error to the caller's onError, falling back to console.
+  reportError(message, fatal) {
+    if (this.onError) {
+      this.onError({ message, fatal });
+    } else {
+      console.error("brookmd worker error:", message);
     }
   }
+  /**
+   * One-shot self-heal after a transient worker death, for BOTH drive modes.
+   * The dead worker was already evicted, so redriving the buffered document
+   * re-acquires a FRESH worker (ensureAcquired re-acquires because the old
+   * `pw.failed` is set). Reads the buffer at EXECUTION time, so a chunk that
+   * interleaved ahead of this microtask is included. Deliberately does NOT route
+   * through setContent(): that would stamp `lastContent`, flipping an append-mode
+   * client into setContent mode, and a second death would then re-feed a stale
+   * `lastContent` missing post-recovery chunks. `recoveryAttempted` is NOT reset
+   * here — if the replacement also dies before healing, the fatal path sees the
+   * flag still set and surfaces the error instead of looping.
+   */
+  recover() {
+    if (!this.attached) return;
+    const doc = this.recoveryBuffer;
+    const done = this.contentDone;
+    this.refeed(doc, done);
+    this.recoveredLen = doc.length;
+    this.lastContent = doc;
+  }
+  /**
+   * Rebuild the parser onto a fresh worker and re-feed `doc` as one atomic
+   * append (re-accumulating recoveryBuffer). Keeps the displayed view on screen
+   * across the swap by softReset-ing when something is rendered, so the document
+   * never blanks; falls back to a bare resetParser when the store is empty.
+   * Uses resetParser / softReset (NOT reset(), which would clear the one-shot
+   * recovery guards mid-heal). Re-finalizes when the buffered doc was finalized.
+   */
+  refeed(doc, done) {
+    const displayed = this.getSnapshot();
+    if (displayed.length > 0) this.softReset(displayed);
+    else this.resetParser();
+    this.append(doc);
+    if (done) this.finalize();
+  }
   /**
    * Notify subscribers of a new snapshot.
    *

package/dist/react.d.ts

@@ -183,7 +183,9 @@ export declare function __resetUnstableWarnings(): void;
  */
 export declare function useBrookStream(stream: AsyncIterable<string> | ReadableStream<Uint8Array> | Response | null | undefined, options?: {
     config?: ParserConfig;
-    onError?: (err: Error) => void;
+    onError?: (err: Error & {
+        fatal?: boolean;
+    }) => void;
 }): BrookClient;
 /**
  * Own a {@link BrookClient} driven by a CONTROLLED full string — the bridge for
@@ -206,10 +208,17 @@ export declare function useBrookStream(stream: AsyncIterable<string> | ReadableS
  * (reattach re-feeds the document). For a true stream source
  * (`Response` / `ReadableStream` / SSE generator) use {@link useBrookStream}
  * instead — it avoids buffering the whole document as a string.
+ *
+ * Pass `onError` to be notified of a terminal worker failure (`err.fatal` set) or
+ * a parse error; defaults to `console.error`. A transient worker death heals
+ * invisibly (see the client's `recovery` option) and does not fire it.
  */
 export declare function useBrookMarkdownString(content: string, options?: {
     config?: ParserConfig;
     streaming?: boolean;
+    onError?: (err: Error & {
+        fatal?: boolean;
+    }) => void;
 }): BrookClient;
 declare function BrookMarkdownImpl(props: BrookMarkdownProps): import("react/jsx-runtime").JSX.Element;
 export declare const BrookMarkdown: import("react").MemoExoticComponent<typeof BrookMarkdownImpl>;

package/dist/react.js

@@ -98,9 +98,19 @@ function BrookMarkdownFromClient({
   );
 }
 function useBrookStream(stream, options) {
-  const [client] = useState(() => new BrookClient({ config: options?.config, coalesce: true }));
   const onErrorRef = useRef(options?.onError);
   onErrorRef.current = options?.onError;
+  const [client] = useState(
+    () => new BrookClient({
+      config: options?.config,
+      coalesce: true,
+      onError: (err) => {
+        const e = Object.assign(new Error(err.message), { fatal: err.fatal });
+        if (onErrorRef.current) onErrorRef.current(e);
+        else console.error(e);
+      }
+    })
+  );
   const prevStream = useRef(void 0);
   useEffect(() => {
     client.reattach();
@@ -123,7 +133,19 @@ function useBrookStream(stream, options) {
   return client;
 }
 function useBrookMarkdownString(content, options) {
-  const [client] = useState(() => new BrookClient({ config: options?.config, coalesce: true }));
+  const onErrorRef = useRef(options?.onError);
+  onErrorRef.current = options?.onError;
+  const [client] = useState(
+    () => new BrookClient({
+      config: options?.config,
+      coalesce: true,
+      onError: (err) => {
+        const e = Object.assign(new Error(err.message), { fatal: err.fatal });
+        if (onErrorRef.current) onErrorRef.current(e);
+        else console.error(e);
+      }
+    })
+  );
   useEffect(() => {
     client.reattach();
     return () => client.destroy();

package/dist/types-core.d.ts

@@ -450,8 +450,19 @@ export type FromWorker = {
  */
 export interface WorkerLike {
     postMessage(msg: ToWorker): void;
-    addEventListener(type: "message", listener: (ev: {
+    /**
+     * Structural superset of DOM `Worker.addEventListener` for the three channels
+     * the pool listens on: `message` (patches / ready / in-band errors — read via
+     * `ev.data`) plus the out-of-band failure channels `error` (a script that
+     * 404s or throws at load — `ev.message`) and `messageerror` (an
+     * undeserializable posted message). One widened signature keeps the unit-test
+     * fakes that declare only `"message"` compiling — method parameters are
+     * checked bivariantly — while letting the pool attach all three without a
+     * structural cast.
+     */
+    addEventListener(type: "message" | "error" | "messageerror", listener: (ev: {
         data: FromWorker;
+        message?: string;
     }) => void): void;
     terminate(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brookmd",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Zero-dep streaming markdown for the browser. Rust→WASM core, Web Worker per stream, incremental parse with speculative closure.",
   "type": "module",
   "sideEffects": ["./dist/worker.js", "./dist/styles.css"],