brookmd 0.22.0

package/dist/block-props.d.ts

@@ -0,0 +1,18 @@
+import type { Block, BlockComponentProps } from "./types-core.js";
+/** Info-string language from a code block's `data-lang="…"`. */
+export declare function extractLang(html: string): string;
+/**
+ * Convert sanitized HTML attribute pairs into a spreadable object, keeping the
+ * HTML-form names (`class`, `for`) verbatim. This is the deliberate divergence
+ * from the JSX renderer (which renames to `className`/`htmlFor` for a prop
+ * spread): the DOM renderer applies them via `el.setAttribute(name, value)`,
+ * which wants the literal HTML names.
+ */
+export declare function htmlAttrs(pairs: [string, string][]): Record<string, string>;
+/**
+ * Build the props a block-kind / component-tag override receives — the same
+ * shape the JSX renderer's block-kind props carry, with ONE deliberate
+ * divergence: for `Component` blocks `attrs` stay in HTML form (`class`/`for`)
+ * because DOM overrides apply them via `setAttribute` (see {@link htmlAttrs}).
+ */
+export declare function blockProps(block: Block): BlockComponentProps;

package/dist/block-props.js

@@ -0,0 +1,75 @@
+function decodeEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+function decodeCodeText(html) {
+  const m = html.match(/<pre><code[^>]*>([\s\S]*?)<\/code><\/pre>/);
+  return m ? decodeEntities(m[1]) : "";
+}
+function decodeMathText(html) {
+  const d = html.match(/<div class="math math-display">([\s\S]*?)<\/div>/);
+  if (d) return decodeEntities(d[1]);
+  return decodeCodeText(html);
+}
+function extractLang(html) {
+  const m = html.match(/data-lang="([^"]+)"/);
+  return m ? m[1] : "";
+}
+function componentInnerHtml(html, tag) {
+  const gt = html.indexOf(">");
+  if (gt < 0) return "";
+  let inner = html.slice(gt + 1);
+  const close = `</${tag}>`;
+  if (inner.endsWith(close)) inner = inner.slice(0, -close.length);
+  return inner.replace(/^\n/, "").replace(/\n$/, "");
+}
+function htmlAttrs(pairs) {
+  const out = {};
+  for (const [k, v] of pairs) out[k] = v;
+  return out;
+}
+function blockProps(block) {
+  const props = {
+    block,
+    html: block.html,
+    open: block.open,
+    speculative: block.speculative
+  };
+  const data = block.kind.data;
+  if (block.kind.type === "CodeBlock") {
+    props.text = data?.code ?? decodeCodeText(block.html);
+    props.language = data?.lang ?? "";
+    if (typeof data?.code === "string") {
+      props.code = { lang: data.lang ?? null, code: data.code };
+    }
+  } else if (block.kind.type === "MathBlock") {
+    props.text = data?.latex ?? decodeMathText(block.html);
+    if (typeof data?.latex === "string") {
+      props.math = { latex: data.latex };
+    }
+  } else if (block.kind.type === "List") {
+    if (data && typeof data.start === "number") {
+      props.list = { ordered: !!data.ordered, start: data.start, items: data.items };
+    }
+  } else if (block.kind.type === "Component") {
+    props.tag = data?.tag ?? "";
+    props.attrs = htmlAttrs(data?.attrs ?? []);
+    props.html = componentInnerHtml(block.html, props.tag);
+  } else if (block.kind.type === "Table") {
+    props.table = block.kind.data;
+  } else if (block.kind.type === "Heading") {
+    if (typeof block.kind.data === "object" && block.kind.data !== null) {
+      props.heading = block.kind.data;
+    }
+  } else if (block.kind.type === "Blockquote" || block.kind.type === "Alert") {
+    const cd = block.kind.data;
+    if (cd && Array.isArray(cd.nested)) {
+      props.container = { nested: cd.nested };
+    }
+  }
+  return props;
+}
+export {
+  blockProps,
+  extractLang,
+  htmlAttrs
+};

package/dist/client.d.ts

@@ -0,0 +1,370 @@
+import type { Block, FromWorker, ParserConfig, Patch, ToWorker, WorkerLike } from "./types-core.js";
+/**
+ * The ordered-block store backing a stream, extracted as a pure function so
+ * its reference-stability contract is testable without a Worker.
+ *
+ * **The contract that prevents extra React re-renders:** a block, once
+ * committed, is never re-sent by the parser, so `applyPatch` never replaces it
+ * in the map. Its object reference stays identical across every later patch —
+ * which is exactly what `blocksEqual` (the BlockView memo) checks, so committed
+ * blocks never re-render (and never re-parse) as the stream grows. Only the
+ * `active` tail gets fresh references each patch, and only it re-renders.
+ */
+export interface BlockStore {
+    committed: Map<number, Block>;
+    committedOrder: number[];
+    active: Block[];
+    snapshot: Block[];
+}
+export declare function emptyBlockStore(): BlockStore;
+/** A heading entry for building a table of contents — see {@link BrookClient.outline}. */
+export interface OutlineEntry {
+    /** Heading level 1–6. */
+    level: number;
+    /** Plain-text heading content (tags stripped, entities decoded). */
+    text: string;
+    /** Stable block id — usable as a scroll target / React key. */
+    id: number;
+}
+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. */
+    failed: Error | null;
+    streamCount: number;
+    /** Live stream ids on this worker — so a fatal failure can notify each one. */
+    streamIds: Set<number>;
+    readyWaiters: Array<{
+        resolve: () => void;
+        reject: (e: Error) => void;
+    }>;
+}
+/**
+ * A pool of Web Workers, each multiplexing many `BrookParser`s keyed by stream
+ * id. This is what lets brookmd scale past `hardwareConcurrency` concurrent
+ * streams without oversubscribing OS threads: 50 streams share (at most) the
+ * cap's worth of workers instead of spawning 50.
+ *
+ * Worker creation is **lazy and load-aware**: while under the cap, each new
+ * stream gets its own worker (so 1 stream = 1 worker, identical to the old
+ * behavior); once at the cap, new streams attach to the least-loaded worker.
+ *
+ * The constructor injects a `WorkerLike` factory so the routing and lifecycle
+ * logic is unit-testable with a fake worker — no real Worker or WASM needed.
+ */
+export declare class BrookPool {
+    private factory;
+    private cap;
+    private workers;
+    private handlers;
+    private nextStreamId;
+    constructor(factory: () => WorkerLike, cap: number);
+    /** Reserve a stream id and assign a worker, registering its message handler. */
+    acquire(handler: (msg: FromWorker) => void): {
+        streamId: number;
+        pw: PoolWorker;
+    };
+    /** Free a stream's parser in its worker; keep the worker warm for siblings. */
+    release(streamId: number, pw: PoolWorker): void;
+    /** Inverse of {@link release}: re-register a stream's handler so it receives
+     *  patches again. For React StrictMode's dev double-mount, which destroys a
+     *  client on the simulated unmount and remounts the SAME instance. The worker
+     *  lazily recreates the disposed parser on the next append. */
+    reattach(streamId: number, pw: PoolWorker, handler: (msg: FromWorker) => void): void;
+    send(pw: PoolWorker, msg: ToWorker): void;
+    /** Resolves when the given worker has finished WASM init; rejects if it failed. */
+    whenWorkerReady(pw: PoolWorker): Promise<void>;
+    /**
+     * Eagerly spin up one worker so WASM init starts BEFORE the first stream —
+     * taking the one-time init off the first-token critical path (e.g. call
+     * `getDefaultPool().warm()` on app load / route entry). Reuses a live worker
+     * if one exists; the warm worker is the one the first stream attaches to (it
+     * has spare capacity), so the work is not wasted. Resolves when that worker has
+     * finished initializing WASM; rejects if init fails fatally. Browser-only (it
+     * constructs a `Worker`).
+     */
+    warm(): Promise<void>;
+    /** Terminate every worker (test teardown / full shutdown). */
+    disposeAll(): void;
+    get workerCount(): number;
+    private pick;
+    private create;
+    private onMessage;
+    private dispatch;
+}
+/** The process-wide default pool every `BrookClient` shares unless given one. */
+export declare function getDefaultPool(): BrookPool;
+/** TEST-ONLY: drop the process-wide default pool so the next {@link getDefaultPool}
+ *  rebuilds it (lazily, with the current global `Worker`). Lets a test file that
+ *  drives the default pool start from a clean, deterministic state regardless of
+ *  which other file warmed it first in bun's shared test process. Not part of the
+ *  public API and a no-op for normal runtime use. */
+export declare function __resetDefaultPool(): void;
+/**
+ * Subscriber-driven store backing a single streaming parser. Each client owns
+ * one stream within a shared {@link BrookPool}; many clients multiplex over a
+ * small set of workers (see the pool for the scaling story).
+ *
+ * The store exposes:
+ *   - subscribe(listener): for React's useSyncExternalStore
+ *   - getSnapshot(): the current ordered list of blocks
+ *   - getMetrics(): per-stream perf metrics
+ *
+ * Mutation methods:
+ *   - append(chunk): forward to the worker
+ *   - finalize(): mark the stream done
+ *   - reset(): start fresh
+ */
+export declare class BrookClient {
+    private pool;
+    private pw;
+    private streamId;
+    private config?;
+    private configSent;
+    private listeners;
+    private store;
+    private onError?;
+    private onBlock?;
+    private attached;
+    private lastContent;
+    private contentDone;
+    private coalesce;
+    private rafHandle;
+    private finalizePending;
+    private epoch;
+    private staleSnapshot;
+    private staleTrimmed;
+    private idNamespace;
+    private mergeCache;
+    private appendedBytes;
+    private patchCount;
+    private totalParseMicros;
+    private lastPatchMs;
+    private firstAppendMs;
+    private retainedBytes;
+    private wasmMemoryBytes;
+    private renderCount;
+    private rebuildCount;
+    /**
+     * @param options.pool   worker pool to join (defaults to the shared
+     *   process-wide pool — pass a dedicated `BrookPool` only for isolation).
+     * @param options.config per-stream parser flags (see {@link ParserConfig});
+     *   omitted fields use library defaults. Applied once, immutable thereafter.
+     * @param options.onError invoked on a worker/parse error or a fatal WASM-init
+     *   failure (`fatal: true`). Without it, errors are only `console.error`d and
+     *   a load failure surfaces solely as a rejected {@link BrookClient.whenReady}.
+     * @param options.onBlock invoked once per block as it commits (in document
+     *   order, after the store updates) — for side effects like lazily
+     *   highlighting a finished code block or analytics. A committed block never
+     *   re-fires; the streaming tail does not (subscribe for live tail updates).
+     *   NOTE: this is a PARSER-commit hook — the block carries the parser's raw
+     *   id. During a setContent divergence swap the rendered view may show that
+     *   block under a different id (an adopted old id, or a namespaced one), so
+     *   correlate with rendered blocks via subscribe()+getSnapshot(), not this id.
+     * @param options.coalesce opt-in (default `false`): collapse multiple
+     *   intra-frame patch notifications into ONE `requestAnimationFrame`-scheduled
+     *   flush to subscribers, so a React `useSyncExternalStore` consumer renders at
+     *   most once per frame instead of once per patch. Lossless — committed blocks
+     *   are reference-stable, so only superseded tail-only renders are skipped. The
+     *   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.
+     */
+    constructor(options?: {
+        pool?: BrookPool;
+        config?: ParserConfig;
+        onError?: (err: {
+            message: string;
+            fatal?: boolean;
+        }) => void;
+        onBlock?: (block: Block) => void;
+        coalesce?: boolean;
+    });
+    /**
+     * Lazily reserve this client's stream id and bind it to a pool worker. The
+     * SOLE place that calls pool.acquire() — so the worker is created on the FIRST
+     * worker-bound operation (append/finalize/reset/pipeFrom/whenReady), never at
+     * construct time. This is what makes `new BrookClient()` SSR-safe: nothing here
+     * runs during an SSR render (which only subscribes + reads the snapshot).
+     *
+     * Idempotent: once this.pw is set it returns it immediately and never
+     * re-acquires — this.pw is never nulled (destroy() deliberately keeps it so
+     * StrictMode's destroy()→reattach() on the SAME instance re-registers the same
+     * slot). Note: streamId/worker assignment now follows first-worker-bound-op
+     * order, not construction order — a client constructed first no longer
+     * necessarily owns the lowest streamId. This affects neither the pool cap nor
+     * multiplexing (pick() is unchanged and remains the only path to create()).
+     */
+    private ensureAcquired;
+    get ready(): boolean;
+    whenReady(): Promise<void>;
+    private firstConfig;
+    append(chunk: string): void;
+    finalize(): void;
+    /**
+     * Pipe a source straight in: read it to completion, `append()` each chunk,
+     * then `finalize()`. The LLM-native path — e.g.
+     * `await client.pipeFrom(await fetch("/api/chat"))`. Accepts:
+     *   - a `Response` or its `ReadableStream<Uint8Array>` body (bytes; decoded
+     *     with `TextDecoder({ stream: true })` so a multibyte sequence straddling
+     *     a chunk boundary carries into the next read), or
+     *   - an `AsyncIterable<string>` (e.g. an SSE delta generator) — string chunks
+     *     appended verbatim.
+     *
+     * Pass `opts.signal` to supersede/cancel: the signal is checked on every
+     * iteration, so once aborted no further chunk is appended and **finalize is
+     * skipped** (a superseded stream must not finalize). For a byte source the
+     * reader is also `cancel()`'d to tear down the upstream. Resolves once
+     * finalized (or cleanly on abort); rejects if the source itself errors.
+     * Browser-only for byte sources (uses `TextDecoder`).
+     */
+    pipeFrom(source: ReadableStream<Uint8Array> | Response | AsyncIterable<string>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Drive the parser from a CONTROLLED full string instead of manual appends.
+     * Pass the whole document-so-far each time; setContent diffs it against the
+     * last value and does the minimal work:
+     *   - **prefix-extension** (the streaming-growth case) → append only the new
+     *     suffix, so committed blocks stay put and only the active tail re-parses;
+     *   - **any other change** (e.g. a finished stream swapped for a re-processed
+     *     final string) → reset + reparse the whole new string, keeping the
+     *     current view on screen until the reparse lands: the document never
+     *     blanks, scroll never moves, and blocks whose rendered content is
+     *     unchanged keep their identity (and React keys) so only genuinely
+     *     changed blocks re-render. An empty new string is an explicit clear and
+     *     hard-resets immediately.
+     *
+     * This is the first-class bridge for UIs that hold a streaming message as a
+     * single growing string prop (the common React shape) — no hand-rolled diff,
+     * no readiness gate (appends before WASM is ready are buffered). Pass
+     * `{ done: true }` once the content is final to `finalize()` (idempotent within
+     * a generation; a content change *after* done reopens the stream via a fresh
+     * reparse, since a finalized parser is terminal and can't be appended to).
+     * Drive a given client with `setContent` *or* manual `append()`/`finalize()`,
+     * not both — they share the internal diff baseline.
+     *
+     * v1 note: the non-prefix path is a full reparse, not a partial rewind —
+     * committed blocks are frozen, so there is no truncate-to-offset. For the
+     * common case (append-growth + one end-of-stream swap) that is optimal. A
+     * transform that rewrites *earlier* bytes on every update is an anti-pattern
+     * here (it forces a reparse each tick); do that enrichment at render time via
+     * `components` instead, keeping the source append-only.
+     */
+    setContent(content: string, opts?: {
+        done?: boolean;
+    }): void;
+    reset(): void;
+    /**
+     * setContent's divergence reset: rebuild the parser exactly like {@link reset},
+     * but keep `preserve` (the currently displayed view) on screen while the new
+     * content reparses. No notify fires here — subscribers keep reading the same
+     * snapshot reference until the first new-generation patch merges over it, so
+     * the swap is seamless: no empty frame, no container collapse, no scroll
+     * clamp, and blocks whose content survives the reprocess never re-render.
+     */
+    private softReset;
+    /**
+     * Finish a preserved-view divergence swap by making the merged view THE
+     * store: adopted ids become the committed keys, the merged array becomes the
+     * snapshot, and every scrap of merge state drops. From here getSnapshot() is
+     * a plain field read again (zero steady-state overhead) and the superseded
+     * generation's blocks are garbage — only one document stays in memory.
+     * Runs on the terminal (final) patch, which commits everything — if anything
+     * is somehow still open, the lazy merge simply stays live instead (the
+     * incremental reuse keeps it linear).
+     */
+    private collapseStale;
+    private resetParser;
+    destroy(): void;
+    /**
+     * Re-register with the pool after {@link destroy} so the client receives
+     * patches again. Needed only for React StrictMode's dev double-mount, where
+     * the renderer destroys on the simulated unmount then remounts the SAME
+     * client instance; apps don't normally call this. No-op if still attached.
+     */
+    reattach(): void;
+    subscribe: (fn: () => void) => () => boolean;
+    getSnapshot: () => Block[];
+    /**
+     * Positional merge of the preserved pre-divergence view over the rebuilding
+     * store (see {@link softReset}). Per position:
+     *   - identical committed block (html + kind + open + speculative) → the OLD
+     *     block object, so its id and reference survive the swap and the block
+     *     never re-renders (blocksEqual / the DOM keyed reconcile hold);
+     *   - changed committed block → the new block CARRYING THE OLD BLOCK'S id, so
+     *     the same keyed component re-renders in place and its state (pagination,
+     *     expansion…) survives the swap; only a NET-NEW position (past the old
+     *     document's end) takes a namespace-offset id, where a raw parser id
+     *     could genuinely collide with a retained old id;
+     *   - still-open block over old content → the old block (never a shrinking
+     *     partial where complete content was already on screen); past the old
+     *     document's end the live tail streams in as-is;
+     *   - position the reparse hasn't reached → the old block, until the terminal
+     *     patch sets `staleTrimmed` and the view clamps to the new length.
+     *
+     * LINEARITY: committed blocks are reference-stable across patches (the store
+     * contract), so a base entry pointer-equal to the previous merge's reproduces
+     * its previous decision without re-running the O(html) equality compare. Each
+     * block is string-compared exactly once — when it first commits — keeping a
+     * long post-divergence stream linear instead of quadratic. Only the active
+     * tail (fresh references each patch, small by design) re-compares per patch.
+     */
+    private mergeStale;
+    /**
+     * Internal: a renderer with an `onRenderMetrics` hook calls this once per
+     * actual React block render so `getMetrics().renderCount` aggregates churn.
+     * No-op cost when no hook is wired (it is simply never called). Not part of
+     * the public API surface — the underscore marks it renderer-internal.
+     */
+    __noteRender(): void;
+    /**
+     * Internal: the DOM renderer calls this once per actual node rebuild (the
+     * changed-block branch) when an `onRenderMetrics` hook is wired, so
+     * `getMetrics().rebuildCount` aggregates churn. Never called without a hook.
+     */
+    __noteRebuild(): void;
+    getMetrics(): {
+        bytes: number;
+        patches: number;
+        meanParseMicros: number;
+        totalParseMs: number;
+        throughputKBs: number;
+        committedBlocks: number;
+        activeBlocks: number;
+        lastPatchAgoMs: number;
+        retainedBytes: number;
+        wasmMemoryBytes: number;
+        renderCount: number;
+        rebuildCount: number;
+    };
+    /**
+     * A heading outline of the current snapshot (committed + active), in document
+     * order — for a table of contents. Works mid-stream; entries appear as their
+     * headings stream in. The `id` is stable, so a built ToC won't re-key.
+     */
+    outline(): OutlineEntry[];
+    /**
+     * The rendered document as plain text — tags stripped, entities decoded,
+     * blocks separated by blank lines. Derived from the rendered HTML (the source
+     * markdown is parsed away in WASM and not retained client-side), so it is a
+     * readable approximation for search indexing / summaries, not a round-trip of
+     * the original source.
+     */
+    toPlaintext(): string;
+    private onMessage;
+    /**
+     * Notify subscribers of a new snapshot.
+     *
+     * With `coalesce` off (default) this is fully synchronous, exactly as before.
+     * With it on and `requestAnimationFrame` available, a normal emit only
+     * *schedules* a single per-frame flush — repeated intra-frame emits collapse
+     * into one notify. `sync` forces an immediate flush (stream completion / reset)
+     * and cancels any frame already pending so the snapshot is delivered once.
+     */
+    private emit;
+    private flushNow;
+    private cancelFrame;
+}
+export {};