brookmd 0.23.2 → 0.25.0

package/dist/client.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "./warn.js";
 import { createWorker } from "./asset-urls.js";
 function emptyBlockStore() {
   return { committed: /* @__PURE__ */ new Map(), committedOrder: [], active: [], snapshot: [] };
@@ -24,24 +25,51 @@ function applyPatch(store, patch) {
   }
   store.active = active;
   const next = new Array(store.committedOrder.length + store.active.length);
+  let w = 0;
   for (let i = 0; i < store.committedOrder.length; i++) {
-    next[i] = store.committed.get(store.committedOrder[i]);
+    const b = store.committed.get(store.committedOrder[i]);
+    if (b === void 0) {
+      warnOnce(
+        "orphan-committed",
+        `brookmd: committed block ${store.committedOrder[i]} is missing from the store and was dropped. This is a bug in brookmd \u2014 please report it.`
+      );
+      continue;
+    }
+    next[w++] = b;
   }
   for (let i = 0; i < store.active.length; i++) {
-    next[store.committedOrder.length + i] = store.active[i];
+    const b = store.active[i];
+    if (b === void 0) {
+      warnOnce("orphan-active", `brookmd: active block at index ${i} is undefined and was dropped.`);
+      continue;
+    }
+    next[w++] = b;
   }
+  if (w !== next.length) next.length = w;
   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 +126,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 +138,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 +163,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
@@ -199,6 +289,9 @@ class BrookClient {
   streamId = 0;
   config;
   configSent = false;
+  /** Set when ensureAcquired rebound this stream onto a fresh worker+parser
+   *  after a fatal failure; consumed by the next content-bearing op. */
+  pendingRebind = false;
   listeners = /* @__PURE__ */ new Set();
   store = emptyBlockStore();
   onError;
@@ -209,6 +302,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
@@ -250,6 +378,9 @@ class BrookClient {
   // reads between notifies must return the SAME reference — the
   // useSyncExternalStore cached-snapshot contract.
   mergeCache = null;
+  /** Set by mergeStale when it had to compact a hole out of the view, so
+   *  getSnapshot skips caching a view whose indices no longer track `base`. */
+  mergeDropped = false;
   // Perf
   appendedBytes = 0;
   patchCount = 0;
@@ -287,6 +418,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 +433,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
@@ -312,15 +452,52 @@ class BrookClient {
    */
   ensureAcquired() {
     if (this.pw && !this.pw.failed) return this.pw;
+    const rebinding = this.pw !== null;
     this.pw = null;
     const { streamId, pw } = this.pool.acquire((msg) => this.onMessage(msg));
     this.streamId = streamId;
     this.pw = pw;
+    if (rebinding) {
+      this.configSent = false;
+      this.pendingRebind = true;
+    }
     return pw;
   }
+  /**
+   * A worker rebind left the store holding a dead generation's blocks while the
+   * fresh parser restarts ids at 0. Called by the ops that actually feed the
+   * parser, before they do. Recovery's re-feed handles this itself (it re-parses
+   * the whole document over a preserved view) and clears the flag; this is the
+   * path where recovery is off or already spent, where the honest outcome is a
+   * clean restart rather than two generations interleaved under colliding ids.
+   */
+  settleRebind() {
+    if (!this.pendingRebind) return;
+    if (this.failedError === null) return;
+    this.pendingRebind = false;
+    if (this.store.snapshot.length === 0 && !this.staleSnapshot) return;
+    warnOnce(
+      "rebind-reset",
+      "brookmd: the parser was rebuilt on a new worker after a fatal failure, so the document restarted. Blocks rendered before the failure were dropped because the fresh parser renumbers from zero. Enable `recovery` (the default) to re-feed and heal invisibly instead."
+    );
+    this.resetParser();
+  }
   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);
@@ -335,12 +512,21 @@ class BrookClient {
   }
   append(chunk) {
     const pw = this.ensureAcquired();
+    this.settleRebind();
     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.settleRebind();
     this.finalizePending = true;
+    this.contentDone = true;
     this.pool.send(pw, { type: "finalize", streamId: this.streamId, config: this.firstConfig(), epoch: this.epoch });
   }
   /**
@@ -431,6 +617,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 +645,9 @@ class BrookClient {
     this.staleSnapshot = null;
     this.staleTrimmed = false;
     this.mergeCache = null;
+    this.failedError = null;
+    this.recoveryAttempted = false;
+    this.pendingRebind = false;
     this.resetParser();
     if (hadContent) this.emit(true);
   }
@@ -513,6 +705,8 @@ class BrookClient {
     this.wasmMemoryBytes = 0;
     this.lastContent = "";
     this.contentDone = false;
+    this.recoveryBuffer = "";
+    this.recoveredLen = Infinity;
     this.cancelFrame();
     this.finalizePending = false;
     this.epoch += 1;
@@ -555,7 +749,12 @@ class BrookClient {
     const cache = this.mergeCache;
     if (cache && cache.base === base && cache.trimmed === this.staleTrimmed) return cache.view;
     const view = this.mergeStale(base, cache && cache.trimmed === this.staleTrimmed ? cache : null);
-    this.mergeCache = { base, trimmed: this.staleTrimmed, view };
+    if (this.mergeDropped) {
+      this.mergeDropped = false;
+      this.mergeCache = null;
+    } else {
+      this.mergeCache = { base, trimmed: this.staleTrimmed, view };
+    }
     return view;
   };
   /**
@@ -586,6 +785,7 @@ class BrookClient {
     const stale = this.staleSnapshot;
     const len = this.staleTrimmed ? base.length : Math.max(base.length, stale.length);
     const view = new Array(len);
+    let dropped = false;
     for (let i = 0; i < len; i++) {
       const nb = i < base.length ? base[i] : void 0;
       if (nb !== void 0 && prev !== null && i < prev.base.length && prev.base[i] === nb) {
@@ -594,6 +794,10 @@ class BrookClient {
       }
       const ob = i < stale.length ? stale[i] : void 0;
       if (!nb) {
+        if (ob === void 0) {
+          dropped = true;
+          continue;
+        }
         view[i] = ob;
         continue;
       }
@@ -611,6 +815,11 @@ class BrookClient {
       }
       view[i] = { ...nb, id: this.idNamespace + nb.id };
     }
+    if (dropped) {
+      warnOnce("merge-hole", "brookmd: the stale-merge produced an empty position \u2014 compacting.");
+      this.mergeDropped = true;
+      return view.filter((b) => b !== void 0);
+    }
     return view;
   }
   /**
@@ -717,15 +926,67 @@ 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.pendingRebind = false;
+    this.append(doc);
+    if (done) this.finalize();
+  }
   /**
    * Notify subscribers of a new snapshot.
    *

package/dist/dom.js

@@ -55,9 +55,11 @@ function mountBrookMarkdown(client, container, options = {}) {
     const snapshot = client.getSnapshot();
     const nextOrder = new Array(snapshot.length);
     const seen = /* @__PURE__ */ new Set();
+    let w = 0;
     for (let i = 0; i < snapshot.length; i++) {
       const b = snapshot[i];
-      nextOrder[i] = b.id;
+      if (b == null || b.kind == null) continue;
+      nextOrder[w++] = b.id;
       seen.add(b.id);
       const existing = mounted.get(b.id);
       if (!existing) {
@@ -131,6 +133,7 @@ function mountBrookMarkdown(client, container, options = {}) {
         }
       }
     }
+    if (w !== nextOrder.length) nextOrder.length = w;
     order = nextOrder;
     reconcileChildren();
   }

package/dist/html-to-react.js

@@ -1,6 +1,21 @@
 import { createElement, Fragment } from "react";
 import { decorateSegments } from "./decorate.js";
 import { decodeEntities, safeUrl } from "./url-safety.js";
+import { warnOnce } from "./warn.js";
+const BLOCK_KIND_KEYS = /* @__PURE__ */ new Set([
+  "Paragraph",
+  "Heading",
+  "CodeBlock",
+  "MathBlock",
+  "Mermaid",
+  "List",
+  "Blockquote",
+  "Alert",
+  "Table",
+  "Rule",
+  "Html",
+  "Component"
+]);
 const VOID = /* @__PURE__ */ new Set([
   "area",
   "base",
@@ -220,6 +235,19 @@ function pushDecoratedText(out, text, decorators, ancestors, keyBase) {
     out.push(createElement(Fragment, { key: keyBase + ":" + i }, replacement));
   }
 }
+function resolveTagType(tag, components) {
+  const c = tag.charCodeAt(0);
+  if (c >= 65 && c <= 90 && BLOCK_KIND_KEYS.has(tag)) {
+    if (components[tag] !== void 0) {
+      warnOnce(
+        "kind-key-as-tag:" + tag,
+        `brookmd: raw <${tag}> in the rendered HTML collides with the block-kind override key "${tag}". A block-kind override receives \`BlockComponentProps\` (with \`block\`), which an inline element cannot supply, so the raw tag is rendered as a plain element instead. Rename the raw tag or the override key.`
+      );
+    }
+    return tag;
+  }
+  return components[tag] ?? tag;
+}
 function nodesToReact(nodes, components, keyPrefix, ctx, ancestors) {
   const out = [];
   for (let idx = 0; idx < nodes.length; idx++) {
@@ -233,7 +261,7 @@ function nodesToReact(nodes, components, keyPrefix, ctx, ancestors) {
       continue;
     }
     const key = keyPrefix + idx;
-    const type = components[n.tag] ?? n.tag;
+    const type = resolveTagType(n.tag, components);
     const props = attrsToProps(n.tag, n.attrs, key, ctx?.urlTransform);
     if (VOID.has(n.tag.toLowerCase())) {
       out.push(createElement(type, props));

package/dist/react.d.ts

@@ -165,6 +165,41 @@ interface BrookMarkdownProps {
      * concurrent deferral of the visible tail.
      */
     deferTail?: boolean;
+    /**
+     * Called when a single block's render THROWS — almost always from inside a
+     * `components` override, not from brookmd itself.
+     *
+     * Every block is wrapped in its own error boundary, so a throwing override
+     * costs you that one block instead of unmounting the whole document (React's
+     * default for an uncaught render error is to unmount the entire tree — a blank
+     * page). The failed block renders nothing; the rest of the stream keeps going,
+     * and later patches retry it.
+     *
+     * Without this hook the failure still goes to `console.error` with the block
+     * id, kind, override keys, and an HTML excerpt. Wire it to your error reporter
+     * to get the same detail in production.
+     *
+     * **HOIST / memoize this** (same trap as `components` / `onRenderMetrics`): a
+     * fresh closure each render busts every block's memo and re-renders the whole
+     * document on every patch.
+     *
+     * The most common cause by far: an override registered for a *block-kind* or
+     * *component-tag* key reading `props.block.…`, invoked on the tag path (the
+     * same tag nested inside another block, or used inline), where `block` is not
+     * supplied. Guard with `if (!block) return <>{children}</>`.
+     */
+    onBlockError?: (error: Error, info: BlockErrorInfo) => void;
+}
+/** Context handed to {@link BrookMarkdownProps.onBlockError}. */
+export interface BlockErrorInfo {
+    /** The block's stable parser-assigned id (also its React key). */
+    blockId: number;
+    /** The block kind that failed, e.g. `"Component"` / `"Table"`. */
+    kind: string;
+    /** The override keys in play — the shortlist of suspects. */
+    componentKeys: string[];
+    /** First 200 chars of the block's rendered HTML, to identify the content. */
+    html: string;
 }
 export declare function __resetUnstableWarnings(): void;
 /**
@@ -183,7 +218,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,15 +243,22 @@ 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>;
 export declare function blockKindProps(block: Block, components?: Components): BlockComponentProps;
-export declare function blocksEqual(prev: {
+interface BlockViewProps {
     block: Block;
     components?: Components;
     virtualize?: boolean;
@@ -223,14 +267,12 @@ export declare function blocksEqual(prev: {
     onRenderMetrics?: RenderMetricsHook;
     decorators?: Decorator[];
     urlTransform?: UrlTransform;
-}, next: {
-    block: Block;
-    components?: Components;
-    virtualize?: boolean;
-    sanitize?: (html: string) => string;
-    childMemo?: boolean;
-    onRenderMetrics?: RenderMetricsHook;
-    decorators?: Decorator[];
-    urlTransform?: UrlTransform;
-}): boolean;
+    /** Diagnostic passthrough for the boundary; derived from `components`, so its
+     *  identity is stable whenever `components` is. */
+    componentKeys?: string[];
+    onBlockError?: (error: Error, info: BlockErrorInfo) => void;
+}
+export declare function blocksEqual(prev: BlockViewProps, next: BlockViewProps): boolean;
+export declare function __getBoundaryRenders(): number;
+export declare function __resetBoundaryRenders(): void;
 export {};