brookmd 0.24.0 → 0.25.1

package/CHANGELOG.md

@@ -4,6 +4,144 @@ 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.25.1 — 2026-07-27
+
+A correction release. 0.25.0 shipped one user-visible regression and a dev-gate
+that failed open in production; both are fixed here, along with a pre-existing
+memory leak on the opt-in `childMemo` path. Upgrade from 0.25.0.
+
+### Fixed
+
+- **WITHDRAWN: the streaming component-tag deferral from 0.25.0.** That change
+  gated component rendering on `open_tail`, which a container propagates
+  UNCHANGED to every sub-block of every list item. A component tag alone in a
+  **non-last list item** — whose one-line body carries no trailing newline of its
+  own — therefore never satisfied the gate again, and rendered as the literal
+  text `<Thinking>` for the entire rest of the stream instead of mounting the
+  consumer's component. Measured 201/201 ticks affected in a 200-item list, and
+  the deferral bought exactly one tick across the three shapes it was written
+  for. `brookmd-core` is reverted to its pre-0.24.0 behavior here (0.24.1); the
+  convergence property 0.25.0 claimed is withdrawn with it. The one-tick issue it
+  was chasing is already contained by the per-block error boundary.
+- **Dev-only warnings ran in production.** The gate read `globalThis.process?.env`,
+  which is a different member path from the `process.env.NODE_ENV` free
+  identifier that esbuild / Vite / Next substitute — so in every bundled browser
+  production build it evaluated to "development", printed to real users, and
+  prevented dead-code elimination of the message strings. Every gate is now at
+  the call site in the literal form bundlers fold. Verified against a real Vite
+  build: 11 dev-warning strings survived a production bundle before, 0 now.
+  (Note the trade: in a realm with no `process` at all — an unbundled CDN
+  consumer — these six development warnings no longer fire. Error reporting via
+  `onBlockError` / `console.error` is NOT gated and is unaffected.)
+- **`childMemo` retained every intermediate tree on a single-element block**
+  (pre-existing, opt-in path). The cache key embeds the segment text, so a block
+  whose HTML is ONE top-level element — which is every core-emitted block kind —
+  could never hit: each patch wrote an entry that was never read again, and
+  `CHILD_MEMO_CAP` bounds entry count, not bytes. Peak RSS grew 154 MB → 1.65 GB
+  over 800 patches of a streaming table. Such blocks now take the ordinary
+  whole-block walk.
+
+### Changed
+
+- Shipped bundles are smaller than 0.25.0: gzipped, minified, production —
+  `index` 14,232 → 13,407 B, `react` 14,185 → 13,365 B, `client` 4,651 → 4,283 B.
+  The boundary's `console.error` keeps everything actionable in production (block
+  id, kind, override keys, HTML excerpt, the error) and moves only the
+  explanatory prose behind the dev gate.
+
+## brookmd-react-native 0.1.5 — 2026-07-27
+
+### Fixed
+
+- Vendored native binaries rebuilt against `brookmd-core` 0.24.1, so the on-device
+  parser no longer carries the component-tag deferral regression withdrawn in
+  brookmd 0.25.1 (a component tag alone in a non-last list item rendered as
+  literal text for the rest of the stream). No JS changes.
+
+## brookmd-react-native 0.1.4 — 2026-07-26
+
+### Fixed
+
+- **The native transport shim routes worker listeners by event type.** brookmd
+  0.24.0 taught `BrookPool` to listen on `error` / `messageerror` (the browser's
+  out-of-band worker-failure channels). `NativeWorker.addEventListener` ignored
+  its `type` argument and registered every listener in one set, so the pool's
+  fatal handler received the ordinary `ready` / `patch` envelopes and read the
+  first as `brookmd worker failed to load`, killing every stream before it
+  started. Neither channel can fire for an in-process shim — there is no script
+  URL to fetch and no structured-clone step — so they are now accepted and never
+  fired. This was latent: the package pinned `brookmd` to `^0.23.0`, which
+  predates those listeners, so it only surfaced when the range moved.
+- `brookmd` dependency range corrected `^0.23.0` → `^0.25.0`; vendored native
+  binaries rebuilt against `brookmd-core` 0.24.0.
+
+## 0.25.0 — 2026-07-26
+
+Fixes a crash class where a `components` override could be invoked with the
+wrong prop shape and take the entire document down with it. If you pass
+`components` and read `props.block` in any of them, upgrade.
+
+### Fixed
+
+- **A `components` override no longer receives two incompatible prop shapes
+  without warning.** The map is consulted by two dispatchers: the block-kind
+  dispatcher (which supplies `BlockComponentProps`, including `block`) and the
+  element-name walker that powers `a`/`code`/`table` overrides (which supplies
+  attributes + `children` and **no `block`**). The same key reaches both — an
+  `inlineComponentTags` chip, or a `componentTags` tag nested inside a list item
+  or blockquote — so an override reading `props.block.…` threw
+  `can't access property "kind", block is undefined`, intermittently, depending
+  on where the model put the tag. Three defenses now apply: block-kind keys are
+  typed to `BlockComponentProps` (a mismatched override is a compile error), a
+  raw element whose name collides with a block-kind key is never dispatched to
+  that override, and every block renders inside its own error boundary.
+- **A throwing override costs one block, not the document.** React unmounts the
+  whole tree on an uncaught render error, so a single bad override blanked the
+  page. Each block now has its own boundary; the failed block is skipped and
+  retried as soon as its HTML changes, so a streaming-tail failure heals itself
+  when the block settles.
+- **The parser no longer emits a component tag it will retract.** A component
+  open tag was recognized as soon as it looked whole-line, but during streaming
+  end-of-buffer is not end-of-line — so `> <Thinking>x</Thinking>` rendered a
+  raw `<Thinking>` element for one tick before settling to escaped text. That
+  transient raw element is what reached overrides with the wrong props. A
+  component tag now opens a block only once its line is known to be complete.
+- **Recovery no longer loses the parser config.** The worker keeps config per
+  stream id, so the one-shot recovery re-feed landed on a worker that had never
+  seen it while `configSent` stayed latched — the healed parser was silently
+  rebuilt with library defaults, dropping `componentTags`, `blockData`,
+  `gfmMath` and the whole `kind.data` structured channel for the rest of the
+  session.
+- **A terminal worker failure no longer corrupts the document.** The store kept
+  the dead generation's blocks while the fresh parser renumbered from zero, so
+  the next append merged two generations under colliding ids (duplicate React
+  keys, silently overwritten blocks, a shrinking document). The generation now
+  restarts cleanly, with a one-time warning. Transient failures still heal
+  invisibly through recovery, unchanged.
+- **Per-block error containment is free for committed blocks.** The boundary
+  lives inside the per-block memo, so a settled document re-renders no
+  boundaries when the streaming tail patches — a new React-side complexity gate
+  (`test/boundary-linearity.test.tsx`) pins this, counting work rather than
+  timing it, mirroring the Rust `scaling` gate.
+- `applyPatch` and the stale-view merge now drop a malformed entry rather than
+  publishing a hole into the snapshot, and both renderers skip a block with no
+  `kind` instead of dereferencing it.
+
+### Added
+
+- **`onBlockError`** on `<BrookMarkdown>` — fires when a block's render throws,
+  with `{ blockId, kind, componentKeys, html }`. Without it the same detail goes
+  to `console.error`.
+
+### Changed
+
+- `Components` is now a mapped type: block-kind keys (`CodeBlock`, `Table`,
+  `Alert`, …) are typed to `BlockComponentProps`; every other key stays
+  permissive. Type-only, but it will surface existing mismatches at compile time.
+- Requires `brookmd-core` 0.24.0 (the streaming component-tag fix above).
+- `onBlockError` is identity-sensitive like `components` / `onRenderMetrics` —
+  hoist or memoize it, or every block re-renders on every patch.
+
 ## 0.24.0 — 2026-07-24
 
 ### Added

package/README.md

@@ -766,6 +766,33 @@ block. The component receives [`BlockComponentProps`](#types): `{ block, html,
 open, speculative }`, plus `text`/`language` for code/math blocks (the alert
 type is at `block.kind.data.kind`).
 
+> **One map, two prop contracts — the single biggest footgun.** The keys above
+> are looked up by TWO dispatchers. The block-kind dispatcher passes
+> `BlockComponentProps` (with `block`); the element dispatcher, which is what
+> makes `a` / `code` / `table` overrides work, passes **the element's attributes
+> and `children` only — no `block`**. The same name can hit both: an
+> `inlineComponentTags` chip, or a `componentTags` tag that lands inside a list
+> item or blockquote (where it is a real *nested* Component block, rendered as an
+> element inside its container's HTML), takes the element path. So an override
+> that reads `props.block.…` throws `can't access property "kind", block is
+> undefined` for those occurrences — intermittently, because it depends on where
+> the model happened to put the tag.
+>
+> Write any override for a name that can appear in both positions defensively:
+>
+> ```tsx
+> const Thinking = ({ block, children }) =>
+>   block ? <Panel data={block.kind.data}>{children}</Panel> : <span>{children}</span>;
+> ```
+>
+> Three things make this survivable rather than fatal: block-kind keys are typed
+> to `BlockComponentProps`, so a mismatched override is a **compile** error; a raw
+> element whose name collides with a block-kind key (`<Table>`, `<Alert>`… — only
+> reachable with raw-HTML passthrough on) is never dispatched to that override;
+> and every block renders inside its own **error boundary**, so a throwing
+> override costs that one block instead of unmounting the document. Wire
+> [`onBlockError`](#onblockerror) to see them.
+
 Rules worth knowing:
 
 - **There is no `node` prop / no hast tree.** Introspect via `className` /
@@ -928,9 +955,23 @@ tags only). It works everywhere inline content does — **including table cells*
 Tag names match **case-sensitively** and dispatch verbatim to `components[tag]`
 (`<tik>`→`components.tik`, `<Cite>`→`components.Cite`). The
 two lists are independent: list a tag under `componentTags` for blocks,
-`inlineComponentTags` for inline, or both for both. An allowlisted tag used in an
-unsupported position degrades **inertly** (escaped) — it never consumes
-surrounding content.
+`inlineComponentTags` for inline, or both for both.
+
+Where an allowlisted tag actually lands:
+
+| Position | Result |
+| --- | --- |
+| Own line, top level | block `Component` — override gets `BlockComponentProps` |
+| Own line inside a list item / blockquote | real **nested** Component block, emitted as an element inside the container's HTML — the override is dispatched by **element name**, so it gets attributes + `children` and **no `block`** |
+| Mid-paragraph, listed in `inlineComponentTags` | inline element — attributes + `children`, no `block` |
+| Mid-paragraph, NOT listed in `inlineComponentTags` | escaped text |
+| Inside a table cell | escaped text (cells are inline-only) |
+
+An allowlisted tag in a position that is not supported degrades **inertly**
+(escaped) — it never consumes surrounding content. But note rows 2 and 3: those
+DO render, through the element path, which is why an override that reads
+`props.block` must guard for its absence (see [the two prop
+contracts](#custom-components--overrides)).
 
 > **Link-bridge alternative.** Before `inlineComponentTags`, the way to get an
 > inline custom element was the link bridge: emit `[$AAPL](tik://AAPL)` and
@@ -1269,6 +1310,33 @@ re-snapping during streaming, so treat smooth following there as best-effort.
 > is the *shared* worker's heap — clients on the same worker report the same
 > value. Aggregate with `Math.max`, not a sum.
 
+<a id="onblockerror"></a>
+
+### When a block fails to render — `onBlockError`
+
+Every block renders inside its own error boundary. React's default response to
+an uncaught render error is to unmount the **entire** tree, so before this a
+single throwing `components` override blanked the whole document. Now the
+failure costs that one block: the rest of the stream keeps rendering, and the
+block is retried as soon as its HTML changes (so a streaming-tail failure heals
+itself when the block settles).
+
+```tsx
+<BrookMarkdown
+  client={client}
+  components={components}
+  onBlockError={(err, { blockId, kind, componentKeys, html }) => {
+    reportToSentry(err, { blockId, kind, componentKeys, html });
+  }}
+/>
+```
+
+`componentKeys` is the override map's keys — the shortlist of suspects — and
+`html` is the first 200 chars of the block that failed. Without the hook the same
+detail goes to `console.error`. The overwhelmingly common cause is an override
+reading `props.block.…` on the element path, where there is no `block`; see [the
+two prop contracts](#custom-components--overrides).
+
 ## Architecture
 
 ```

package/dist/client.d.ts

@@ -156,6 +156,9 @@ export declare class BrookClient {
     private streamId;
     private config?;
     private configSent;
+    /** Set when ensureAcquired rebound this stream onto a fresh worker+parser
+     *  after a fatal failure; consumed by the next content-bearing op. */
+    private pendingRebind;
     private listeners;
     private store;
     private onError?;
@@ -176,6 +179,9 @@ export declare class BrookClient {
     private staleTrimmed;
     private idNamespace;
     private mergeCache;
+    /** 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`. */
+    private mergeDropped;
     private appendedBytes;
     private patchCount;
     private totalParseMicros;
@@ -245,6 +251,15 @@ export declare class BrookClient {
      * multiplexing (pick() is unchanged and remains the only path to create()).
      */
     private ensureAcquired;
+    /**
+     * 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.
+     */
+    private settleRebind;
     get ready(): boolean;
     /**
      * The fatal error that killed this client's worker, or `null` if healthy.

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,12 +25,31 @@ 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) {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        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) {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        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 {
@@ -273,6 +293,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;
@@ -359,6 +382,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;
@@ -430,12 +456,38 @@ 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;
+    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+      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;
   }
@@ -466,6 +518,7 @@ class BrookClient {
   }
   append(chunk) {
     const pw = this.ensureAcquired();
+    this.settleRebind();
     if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
     if (this.recovery) {
       this.recoveryBuffer += chunk;
@@ -477,6 +530,7 @@ class BrookClient {
   }
   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 });
@@ -599,6 +653,7 @@ class BrookClient {
     this.mergeCache = null;
     this.failedError = null;
     this.recoveryAttempted = false;
+    this.pendingRebind = false;
     this.resetParser();
     if (hadContent) this.emit(true);
   }
@@ -700,7 +755,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;
   };
   /**
@@ -731,6 +791,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) {
@@ -739,6 +800,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;
       }
@@ -756,6 +821,13 @@ class BrookClient {
       }
       view[i] = { ...nb, id: this.idNamespace + nb.id };
     }
+    if (dropped) {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        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;
   }
   /**
@@ -919,6 +991,7 @@ class BrookClient {
     const displayed = this.getSnapshot();
     if (displayed.length > 0) this.softReset(displayed);
     else this.resetParser();
+    this.pendingRebind = false;
     this.append(doc);
     if (done) this.finalize();
   }

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 && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+      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));
@@ -307,6 +335,7 @@ function htmlToReact(html, components, childMemoMap, opts) {
   const ctx = opts && (opts.decorators || opts.urlTransform) ? { decorators: opts.decorators, urlTransform: opts.urlTransform } : void 0;
   if (!childMemoMap) return nodesToReact(parseTrustedHtml(html), components, "", ctx, []);
   const segs = topLevelSegments(html);
+  if (segs.length < 2) return nodesToReact(parseTrustedHtml(html), components, "", ctx, []);
   const out = [];
   for (let idx = 0; idx < segs.length; idx++) {
     const seg = segs[idx];

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;
 /**
@@ -223,16 +258,7 @@ export declare function useBrookMarkdownString(content: string, options?: {
 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: {
-    block: Block;
-    components?: Components;
-    virtualize?: boolean;
-    sanitize?: (html: string) => string;
-    childMemo?: boolean;
-    onRenderMetrics?: RenderMetricsHook;
-    decorators?: Decorator[];
-    urlTransform?: UrlTransform;
-}, next: {
+interface BlockViewProps {
     block: Block;
     components?: Components;
     virtualize?: boolean;
@@ -241,5 +267,12 @@ export declare function blocksEqual(prev: {
     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 {};

package/dist/react.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import {
+  Component,
   createElement,
   memo,
   useEffect,
@@ -14,7 +15,18 @@ import { CodeBlock } from "./renderers/CodeBlock.js";
 import { MathBlock } from "./renderers/Math.js";
 import { Mermaid } from "./renderers/Mermaid.js";
 import { htmlToReact } from "./html-to-react.js";
+import { warnOnce } from "./warn.js";
 const NO_DEFER_BLOCKS = [];
+const EMPTY_KEYS = [];
+function skipBadBlock(index) {
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+    warnOnce(
+      "bad-block",
+      `brookmd: snapshot position ${index} has no block kind and was skipped. This indicates a corrupted block store \u2014 please report it.`
+    );
+  }
+  return null;
+}
 const warnedUnstable = /* @__PURE__ */ new Set();
 function useUnstablePropWarning(name, value) {
   const ref = useRef(value);
@@ -22,8 +34,7 @@ function useUnstablePropWarning(name, value) {
     const prevDefined = ref.current !== void 0 && ref.current !== null;
     const nextDefined = value !== void 0 && value !== null;
     ref.current = value;
-    const env = globalThis.process?.env;
-    if (prevDefined && nextDefined && !warnedUnstable.has(name) && (!env || env.NODE_ENV !== "production")) {
+    if (prevDefined && nextDefined && !warnedUnstable.has(name) && typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
       warnedUnstable.add(name);
       console.warn(
         `<BrookMarkdown>: the \`${name}\` prop changed identity between renders. Hoist it to module scope or wrap it in useMemo \u2014 a fresh identity each render busts the per-block memo and re-parses every block on every patch.`
@@ -49,7 +60,8 @@ function BrookMarkdownFromClient({
   onRenderMetrics,
   deferTail,
   decorators,
-  urlTransform
+  urlTransform,
+  onBlockError
 }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   useUnstablePropWarning("decorators", decorators);
@@ -61,6 +73,7 @@ function BrookMarkdownFromClient({
     () => components && Object.keys(components).length > 0 ? components : void 0,
     [components]
   );
+  const componentKeys = useMemo(() => comps ? Object.keys(comps) : EMPTY_KEYS, [comps]);
   const onMetrics = useMemo(
     () => onRenderMetrics ? (id2, m) => {
       client.__noteRender();
@@ -78,20 +91,29 @@ function BrookMarkdownFromClient({
       "aria-live": ariaLive,
       "aria-atomic": ariaAtomic,
       children: [
-        rendered.map((b) => /* @__PURE__ */ jsx(
-          BlockView,
-          {
-            block: b,
-            components: comps,
-            virtualize,
-            sanitize,
-            childMemo,
-            onRenderMetrics: onMetrics,
-            decorators,
-            urlTransform
-          },
-          b.id
-        )),
+        rendered.map(
+          (b, i) => (
+            // The guard runs BEFORE `key={b.id}` is evaluated: a malformed entry
+            // must not throw here (it would take the whole document down), and the
+            // store's density invariant is not something a renderer should bet on.
+            b == null || b.kind == null ? skipBadBlock(i) : /* @__PURE__ */ jsx(
+              BlockView,
+              {
+                block: b,
+                components: comps,
+                virtualize,
+                sanitize,
+                childMemo,
+                onRenderMetrics: onMetrics,
+                decorators,
+                urlTransform,
+                componentKeys,
+                onBlockError
+              },
+              b.id
+            )
+          )
+        ),
         stickToBottom && /* @__PURE__ */ jsx("div", { "aria-hidden": "true", style: { scrollSnapAlign: "end" }, className: "brook-bottom-anchor" })
       ]
     }
@@ -466,7 +488,8 @@ function renderBlockContent({
   decorators,
   urlTransform
 }) {
-  const kind = block.kind.type;
+  const kind = block?.kind?.type;
+  if (kind === void 0) return null;
   const hasInlineTransforms = !!decorators || !!urlTransform;
   if (components) {
     if (kind === "Component") {
@@ -545,14 +568,80 @@ function renderBlockContent({
   );
 }
 function blocksEqual(prev, next) {
+  if (prev.block == null || next.block == null) return prev.block === next.block;
   return prev.block.id === next.block.id && prev.block.html === next.block.html && prev.block.open === next.block.open && prev.block.speculative === next.block.speculative && prev.components === next.components && prev.virtualize === next.virtualize && prev.sanitize === next.sanitize && prev.childMemo === next.childMemo && prev.onRenderMetrics === next.onRenderMetrics && // Identity compare: an unstable decorators/urlTransform (fresh each render)
   // busts the memo so every committed block re-decorates — the O(n²) footgun
   // the dev warning calls out. A hoisted/memoized value keeps the memo holding.
-  prev.decorators === next.decorators && prev.urlTransform === next.urlTransform;
+  prev.decorators === next.decorators && prev.urlTransform === next.urlTransform && // Same identity rule as onRenderMetrics: an inline `onBlockError={() => …}`
+  // is a fresh closure per render and would re-render every block on every
+  // patch. Hoist or memoize it (documented alongside the other hooks).
+  prev.onBlockError === next.onBlockError && prev.componentKeys === next.componentKeys;
+}
+let boundaryRenders = 0;
+function __getBoundaryRenders() {
+  return boundaryRenders;
+}
+function __resetBoundaryRenders() {
+  boundaryRenders = 0;
+}
+function BlockViewOuter(props) {
+  const { block, componentKeys, onBlockError } = props;
+  return /* @__PURE__ */ jsx(
+    BlockBoundary,
+    {
+      blockId: block.id,
+      kind: block.kind.type,
+      html: block.html,
+      componentKeys: componentKeys ?? EMPTY_KEYS,
+      onBlockError,
+      children: /* @__PURE__ */ jsx(BlockViewImpl, { ...props })
+    }
+  );
+}
+const BlockView = memo(BlockViewOuter, blocksEqual);
+class BlockBoundary extends Component {
+  state = { caught: false, failedHtml: null };
+  static getDerivedStateFromError() {
+    return { caught: true };
+  }
+  /** Retry once the block's HTML moves on. A streaming-tail failure — a
+   *  speculatively-closed tag, a prop that is only transiently absent — then
+   *  heals itself when the block settles, instead of leaving a hole for the rest
+   *  of the session. */
+  static getDerivedStateFromProps(props, state) {
+    if (state.caught && state.failedHtml !== null && state.failedHtml !== props.html) {
+      return { caught: false, failedHtml: null };
+    }
+    return null;
+  }
+  componentDidCatch(error) {
+    const info = {
+      blockId: this.props.blockId,
+      kind: this.props.kind,
+      componentKeys: this.props.componentKeys,
+      html: this.props.html.slice(0, 200)
+    };
+    this.setState({ failedHtml: this.props.html });
+    if (this.props.onBlockError) {
+      this.props.onBlockError(error, info);
+      return;
+    }
+    const hint = typeof process !== "undefined" && process.env.NODE_ENV !== "production" ? ` This is almost always a \`components\` override throwing. If it is registered for a block-kind or component-tag key, note that the SAME key is also dispatched for a matching element nested inside a block's HTML \u2014 that call gets attributes + children only, with no \`block\` prop. Guard with \`if (!block) return <>{children}</>\`.` : "";
+    console.error(
+      `brookmd: block ${info.blockId} (${info.kind}) failed to render and was skipped.${hint}`,
+      { componentKeys: info.componentKeys, html: info.html },
+      error
+    );
+  }
+  render() {
+    boundaryRenders++;
+    return this.state.caught ? null : this.props.children;
+  }
 }
-const BlockView = memo(BlockViewImpl, blocksEqual);
 export {
   BrookMarkdown,
+  __getBoundaryRenders,
+  __resetBoundaryRenders,
   __resetUnstableWarnings,
   blockKindProps,
   blocksEqual,

package/dist/server-react.js

@@ -3,7 +3,8 @@ import { htmlToReact } from "./html-to-react.js";
 import { blockKindProps } from "./react.js";
 import { parseToBlocks } from "./server.js";
 function renderStaticBlock(block, components) {
-  const kind = block.kind.type;
+  const kind = block?.kind?.type;
+  if (kind === void 0) return null;
   if (components) {
     if (kind === "Component") {
       const tag = block.kind.data?.tag;

package/dist/types-react.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentType } from "react";
+import type { BlockComponentProps, BlockKindTag } from "./types-core.js";
 /**
  * Override map for {@link BrookMarkdown}. Keys are either lowercase HTML tag
  * names (`table`, `a`, `code`, `h1`… — react-markdown style, applied inside a
@@ -6,8 +7,35 @@ import type { ComponentType } from "react";
  * `CodeBlock`, `Table` — replace the whole block renderer). Values are a React
  * component or an HTML tag string.
  *
- * Tag-level components receive the element's parsed attributes (with
- * `class`→`className`, `style` as an object) plus `children`. Block-kind
- * components receive `BlockComponentProps`. There is no `node` prop.
+ * ## Two prop contracts — read this before writing an override
+ *
+ * The same map is consulted by two dispatchers, and they pass different props:
+ *
+ * - **Block contract.** A block-kind key, or a `componentTags` tag matched at
+ *   block level, receives {@link BlockComponentProps} — `block`, `html`, `open`,
+ *   `speculative` (plus `tag`/`attrs`/`children` for component tags).
+ * - **Tag contract.** The SAME key is also matched by *element name* while
+ *   converting a block's HTML to React — which is how `a`/`code`/`table`
+ *   overrides work, and also how an `inlineComponentTags` chip, or a component
+ *   tag nested inside a list item / blockquote, is rendered. That call passes
+ *   the element's attributes and `children` only: **there is no `block` prop.**
+ *
+ * So a component registered for a tag that can appear in both positions must not
+ * assume `block` exists:
+ *
+ * ```tsx
+ * const Thinking = ({ block, children }: any) =>
+ *   block ? <Panel data={block.kind.data}>{children}</Panel> : <span>{children}</span>;
+ * ```
+ *
+ * Block-kind keys are typed to {@link BlockComponentProps} below so the mismatch
+ * is a compile error rather than a runtime `undefined` deref; brookmd also
+ * refuses to dispatch a raw element whose name collides with a block-kind key,
+ * and wraps every block in an error boundary so a throwing override costs one
+ * block instead of the document.
  */
-export type Components = Record<string, ComponentType<any> | string>;
+export type Components = {
+    [K in BlockKindTag]?: ComponentType<BlockComponentProps> | string;
+} & {
+    [tag: string]: ComponentType<any> | string | undefined;
+};

package/dist/warn.d.ts

@@ -0,0 +1,4 @@
+/** Warn once per `id`. Callers own the production gate — see the contract above. */
+export declare function warnOnce(id: string, message: string): boolean;
+/** Test-only: clear the latch so a test can assert a warning fires. */
+export declare function __resetWarnOnce(): void;

package/dist/warn.js

@@ -0,0 +1,14 @@
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(id, message) {
+  if (warned.has(id)) return false;
+  warned.add(id);
+  console.warn(message);
+  return true;
+}
+function __resetWarnOnce() {
+  warned.clear();
+}
+export {
+  __resetWarnOnce,
+  warnOnce
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brookmd",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "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"],