brookmd 0.23.2 → 0.25.0

package/dist/react.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import {
+  Component,
   createElement,
   memo,
   useEffect,
@@ -14,7 +15,16 @@ 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) {
+  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);
@@ -49,7 +59,8 @@ function BrookMarkdownFromClient({
   onRenderMetrics,
   deferTail,
   decorators,
-  urlTransform
+  urlTransform,
+  onBlockError
 }) {
   const blocks = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
   useUnstablePropWarning("decorators", decorators);
@@ -61,6 +72,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,29 +90,48 @@ 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" })
       ]
     }
   );
 }
 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 +154,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();
@@ -444,7 +487,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") {
@@ -523,14 +567,79 @@ 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;
+    }
+    console.error(
+      `brookmd: block ${info.blockId} (${info.kind}) failed to render and was skipped. This is almost always a \`components\` override throwing. If the override 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}</>\`.`,
+      { 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-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/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,9 @@
+/** True unless the bundler/runtime says NODE_ENV === "production". Read off
+ *  `globalThis` so there is no @types/node dependency; bundlers inline
+ *  `process.env.NODE_ENV`, and absence is treated as dev (same rule as the
+ *  unstable-prop tripwire in react.tsx). */
+export declare function isDev(): boolean;
+/** Warn once per `id` (dev only). Returns true if it actually warned. */
+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,19 @@
+const warned = /* @__PURE__ */ new Set();
+function isDev() {
+  const env = globalThis.process?.env;
+  return !env || env.NODE_ENV !== "production";
+}
+function warnOnce(id, message) {
+  if (!isDev() || warned.has(id)) return false;
+  warned.add(id);
+  console.warn(message);
+  return true;
+}
+function __resetWarnOnce() {
+  warned.clear();
+}
+export {
+  __resetWarnOnce,
+  isDev,
+  warnOnce
+};

package/package.json

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