brookmd 0.23.2 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,110 @@ 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.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
+
+- **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
@@ -754,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` /
@@ -916,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
@@ -1257,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

@@ -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. */
@@ -122,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?;
@@ -129,6 +166,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;
@@ -137,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;
@@ -170,6 +215,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 +233,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
@@ -197,7 +251,27 @@ 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.
+     *
+     * 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 +428,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.
      *