brookmd 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.29.0 — 2026-07-31
+
+**Sublinear resources.** Total parse work has an Ω(n) floor and stays exactly
+there — but retained memory and reopen latency don't have to be O(n), and now
+they aren't. Requires `brookmd-core` 0.26.0. Both features are **web-path**
+(WASM + TS client); the native bindings (React Native / Kotlin / Swift /
+Flutter) share every parser-core improvement but consume `allBlocks()` and so
+keep full retention — see the platform matrix in the root README.
+
+### Added
+
+- **Instant thread reopen — `getPersistable()` / `hydrate()` /
+  `sourceFingerprint()`.** A finished (or in-flight) stream can be persisted
+  as a small JSON envelope — the blocks `getSnapshot()` showed plus a source
+  length/hash and a `done` flag — and a fresh `BrookClient` hydrates from it
+  with **no worker, no WASM, no parsing**: 1 MB / 2,250 blocks re-streams in
+  ~110 ms, hydrates in **~5.5 ms** (and a real browser reopen also skips
+  worker spin-up and WASM init). To *continue* a non-finalized thread, pass
+  the original source to `beginResume()`: the UI keeps showing hydrated
+  blocks while a background re-parse catches up — reusing the existing
+  divergence/adoption machinery, so every hydrated block keeps its exact id
+  across the swap and nothing visible remounts; appends stream live once
+  caught up. The envelope is a versioned **package** format
+  (`hydrateVersion`), deliberately not the wire contract; the README's
+  "Instant thread reopen" section documents the persistence and invalidation
+  contract.
+- **`retainCommittedHtml` — the parser no longer hoards the rendered
+  document.** The core kept every committed block's HTML alive for
+  `allBlocks()` — which the web worker path never calls. The worker now
+  defaults the flag **off**: retained memory beyond the source buffer drops
+  to the open tail only (measured: **53–70% less total retention** on 1 MB
+  streams, with the flag-off overhead above the raw source staying under
+  300 bytes at every point). Patches are byte-identical either way — committed
+  blocks are emitted exactly once and never re-read. Rust-side default stays
+  ON, so native bindings and `allBlocks()` consumers are unaffected;
+  `renderToString` pins it on (it assembles from `allBlocks`). Set
+  `retainCommittedHtml: true` in `ParserConfig` if you drive the worker and
+  want `allBlocks` fidelity.
+
 ## 0.28.0 — 2026-07-31
 
 **Browser-side linearity.** The parser and wire have been O(new bytes) per

package/README.md

@@ -586,6 +586,11 @@ class BrookClient {
   whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure
   subscribe(listener: () => void): () => void;      // React-friendly store
   getSnapshot(): Block[];                           // ordered current blocks
+  getPersistable(source?: string): PersistableSnapshot;     // capture the rendered doc as JSON
+  hydrate(                                                  // restore it: no worker, no parse
+    snapshot: PersistableSnapshot,
+    opts?: { source?: string },                             // source ⇒ a live thread can resume
+  ): void;
   outline(): { level: number; text: string; id: number }[]; // heading table-of-contents (works mid-stream)
   toPlaintext(): string;                            // rendered document as plain text (search / summaries)
   getMetrics(): { bytes, patches, totalParseMs, throughputKBs,
@@ -1284,6 +1289,101 @@ WASM `BrookParser`, native bindings, C ABI) keep byte-identical v1 wire by
 default and can opt in with `setWireDelta(true)` — see
 [`WIRE.md` §11](https://github.com/siinghd/brookmd/blob/main/crates/brookmd-core/WIRE.md).
 
+## Instant thread reopen — persist and hydrate
+
+Reopening a long thread normally means re-feeding its whole source through the
+parser before the first paint: O(history) work between the click and the pixels,
+which is exactly when a chat UI feels frozen.
+
+It is also unnecessary. A committed block is emitted **once** and is **final**,
+so the blocks a stream already produced are a complete description of the
+document — there is nothing to re-derive. Capture them, store them, restore them:
+
+```ts
+// When the thread closes (or at any checkpoint):
+await db.put(threadId, JSON.stringify(client.getPersistable()));
+
+// When it reopens:
+const client = new BrookClient();
+client.hydrate(JSON.parse(await db.get(threadId))); // no worker, no WASM, no parse
+// <BrookMarkdown client={client} /> paints the whole thread on the first frame.
+```
+
+Measured on a 1 MB / ~2250-block thread: **~5 ms to hydrate vs ~110 ms to
+re-stream** it in 2 KB chunks (~51 ms even for a single-shot re-parse) — before
+counting the worker spin-up and WASM init a re-stream also pays. Hydration is
+O(blocks) of JSON handling; nothing parses.
+
+Hydrated blocks are **ordinary committed blocks**: both renderers mount them
+through the same path as live ones, so a reopened thread renders byte-identical
+to the one the user closed.
+
+### What to store, and when to throw it away
+
+```ts
+interface PersistableSnapshot {
+  hydrateVersion: number; // envelope version; hydrate() refuses what it can't read
+  blocks: Block[];        // exactly what getSnapshot() showed
+  sourceLength: number;   // UTF-16 length of the markdown behind them
+  sourceHash: string;     // fingerprint of that markdown — a staleness check
+  done: boolean;          // had the stream been finalized?
+}
+```
+
+Store it as JSON beside the thread. **Invalidate it when your source moves on**:
+hydrate deliberately does *not* verify the blocks against the source, so a stale
+snapshot would paint stale HTML. That is what `sourceHash` is for:
+
+```ts
+import { sourceFingerprint } from "brookmd";
+
+if (snapshot.sourceHash === sourceFingerprint(mySource)) {
+  client.hydrate(snapshot);                        // instant
+} else {
+  client.setContent(mySource, { done: true });     // the text changed — re-stream
+}
+```
+
+Discard a snapshot whose `hydrateVersion` your build doesn't read, too. Either
+way a failed hydrate is safe to fall back from: a malformed or unreadable
+snapshot is rejected **whole**, with nothing written until every block has
+validated.
+
+> This envelope is a brookmd **package** format, *not* the parser wire contract
+> ([`WIRE.md`](https://github.com/siinghd/brookmd/blob/main/crates/brookmd-core/WIRE.md)).
+> The two are versioned independently.
+
+### Resuming a thread that was still streaming
+
+A `done: false` snapshot was captured mid-stream. Pass the original markdown as
+`source` and the thread simply continues:
+
+```ts
+client.hydrate(snapshot, { source: markdownSoFar });
+client.append(nextDelta); // or client.pipeFrom(await fetch("/api/chat"))
+```
+
+The parser's internal state cannot be serialized (it is an `Rc` graph, not
+data), so continuing a document genuinely requires re-parsing what came before
+it — but that cost moves **off the critical path**. On the first `append`
+brookmd spins up the worker, re-feeds the source in the background, and keeps
+the hydrated blocks on screen throughout: the reader scrolls and reads while the
+parse catches up. New chunks need no buffering — they queue behind the re-feed
+and land the moment it completes (they arrive at model token speed; the parser
+catches up far faster). When the re-parse lands, unchanged blocks are adopted
+**by reference and by id**, so nothing re-renders and nothing remounts at the
+swap.
+
+A `done: true` snapshot is terminal: it needs no `source`, no worker is ever
+created for it, and `append()` throws — a finished thread cannot be extended
+(`reset()` to start a new one). A `done: false` snapshot hydrated *without*
+`source` is view-only: it paints, but appending throws, because a document
+cannot be continued correctly without the text preceding it.
+
+Nothing on the hydrate path touches a worker: `whenReady()` resolves immediately
+and `client.ready` is `true`, so a readiness gate never sits over a thread that
+is already on screen.
+
 ## Security
 
 brookmd is XSS-safe by default — its HTML output is meant to be injected via

package/dist/client.d.ts

@@ -26,6 +26,50 @@ export interface OutlineEntry {
     /** Stable block id — usable as a scroll target / React key. */
     id: number;
 }
+/**
+ * A self-contained, JSON-serializable capture of everything a stream currently
+ * renders — produced by {@link BrookClient.getPersistable}, restored by
+ * {@link BrookClient.hydrate}.
+ *
+ * Reopening a long thread normally re-feeds its whole source through the parser
+ * before the first paint (O(source), and it blocks the reopen). Persist this
+ * next to the thread instead and restoring it is pure JSON handling: the blocks
+ * go straight into the store and both renderers mount them as ordinary
+ * committed blocks — **no worker, no WASM, no parse**.
+ *
+ * NOT the wire contract. The parser↔renderer wire (WIRE.md) is a separate,
+ * separately-versioned boundary; this envelope is a brookmd *package* format
+ * that only {@link BrookClient.hydrate} consumes.
+ */
+export interface PersistableSnapshot {
+    /** Envelope version. {@link BrookClient.hydrate} refuses anything it does not
+     *  know how to read, so a stored snapshot never half-restores. */
+    hydrateVersion: number;
+    /**
+     * The blocks exactly as {@link BrookClient.getSnapshot} showed them at
+     * capture: the committed history plus whatever tail was on screen. Plain
+     * JSON — a `Block` carries no hidden state (the renderers' splice bookkeeping
+     * lives in a WeakMap, never on the block), so `JSON.stringify` round-trips it.
+     */
+    blocks: Block[];
+    /** UTF-16 length of the markdown that produced `blocks`. */
+    sourceLength: number;
+    /** {@link sourceFingerprint} of that markdown. A staleness check — "is the
+     *  source I stored still the one these blocks came from?" — and deliberately
+     *  nothing more: not a checksum, not security. */
+    sourceHash: string;
+    /** Whether the captured stream had been finalized. A `done` snapshot is a
+     *  terminal document: it needs no source and can never be resumed. */
+    done: boolean;
+}
+/**
+ * 32-bit FNV-1a over a string's UTF-16 code units, as 8 hex digits. Backs
+ * {@link PersistableSnapshot.sourceHash}: cheap enough to run over a megabyte
+ * of markdown, sharp enough to notice that a stored source changed. Exported so
+ * a caller can make the same staleness decision brookmd does —
+ * `snap.sourceHash === sourceFingerprint(mySource)`. Not a security primitive.
+ */
+export declare function sourceFingerprint(source: string): string;
 export declare function applyPatch(store: BlockStore, patch: Patch): void;
 interface PoolWorker {
     worker: WorkerLike;
@@ -171,6 +215,7 @@ export declare class BrookClient {
     private recoveryBuffer;
     private recoveredLen;
     private recoveryAttempted;
+    private appendedAny;
     private coalesce;
     private rafHandle;
     private finalizePending;
@@ -182,6 +227,12 @@ export declare class BrookClient {
     /** 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 hydrated;
+    private hydratedDone;
+    private hydratedLength;
+    private hydratedHash;
+    private hydratedSource;
+    private resumed;
     private appendedBytes;
     private patchCount;
     private totalParseMicros;
@@ -261,6 +312,10 @@ export declare class BrookClient {
      */
     private settleRebind;
     get ready(): boolean;
+    /** True while a hydrated document has never been handed to a parser: the
+     *  store holds restored blocks and no worker exists. Cleared once the resume
+     *  re-feed is issued (or the caller re-drives the whole document itself). */
+    private get hydrationPending();
     /**
      * The fatal error that killed this client's worker, or `null` if healthy.
      *
@@ -329,6 +384,90 @@ export declare class BrookClient {
     setContent(content: string, opts?: {
         done?: boolean;
     }): void;
+    /**
+     * Capture everything this client currently renders as a plain-JSON
+     * {@link PersistableSnapshot}: `JSON.stringify` it, store it beside the
+     * thread, and {@link hydrate} it back later to repaint with **no parse at
+     * all**. This is the persistence half of instant thread reopen.
+     *
+     * The committed wire is already a complete serialization — a committed block
+     * is emitted exactly once and is final (WIRE.md §2) — so there is nothing to
+     * re-derive: the snapshot IS the document. Cost here is one pass to
+     * fingerprint the source; cost on the way back in is a `Map` fill.
+     *
+     * @param source the markdown driven into this stream, used ONLY to compute
+     *   {@link PersistableSnapshot.sourceHash}. Optional, because a client with
+     *   `recovery` on (the default) already retains it, as does a
+     *   `setContent`-driven one; required in the single configuration that holds
+     *   neither — `recovery: false` plus manual `append()` — where omitting it
+     *   throws rather than persisting a snapshot no one can check for staleness.
+     */
+    getPersistable(source?: string): PersistableSnapshot;
+    /** The full driven document when this client happens to hold it: the recovery
+     *  buffer is exactly that whenever `recovery` is on (the default), and
+     *  setContent's baseline covers the recovery-off controlled-string mode.
+     *  `null` means genuinely unknown — reachable only with recovery off AND
+     *  manual appends. */
+    private retainedSource;
+    /**
+     * Restore a {@link PersistableSnapshot} into an untouched client. The blocks
+     * land in the store as ordinary committed blocks and `getSnapshot()` returns
+     * them immediately, so the first paint already has the whole document —
+     * **no worker is created, no WASM loads, nothing is parsed**. Reopening a
+     * thread costs O(blocks) of JSON handling instead of O(source) of parsing.
+     *
+     * Call it on a fresh client before anything is appended and, ideally, before
+     * the renderer mounts (hydrating an already-mounted client works — it
+     * notifies subscribers — but costs an extra render). Hydrating a client that
+     * already holds content throws.
+     *
+     * **Resuming a live thread.** A snapshot with `done: false` was still
+     * streaming. Pass `source` — the markdown behind the snapshot — and the first
+     * {@link append} rebuilds parser state in the background: the parser's
+     * internals are an `Rc` graph with no serialized form, so continuing a
+     * document genuinely requires re-parsing what came before it, but that cost
+     * moves OFF the critical path. The hydrated blocks stay on screen and the
+     * reader scrolls them while the worker catches up; new chunks queue behind the
+     * re-feed and land the moment it does. Without `source` the thread is
+     * view-only and appending throws — continuing a document correctly is not
+     * possible without the text that precedes it.
+     *
+     * **Hydration does not verify the blocks against the source.** The snapshot is
+     * trusted as produced; `sourceHash` exists so the CALLER can notice its stored
+     * source moved on and re-stream instead of painting stale HTML. The resume
+     * path re-checks it, lets the fresh parse win, and warns in dev.
+     *
+     * @throws if the envelope version is unknown, the snapshot is malformed, or
+     *   this client already holds content. Validation completes before anything is
+     *   written, so a rejected snapshot leaves the client exactly as it was.
+     */
+    hydrate(snapshot: PersistableSnapshot, opts?: {
+        source?: string;
+    }): void;
+    /**
+     * The first content-bearing op on a hydrated thread: give the parser back the
+     * state it could not be handed.
+     *
+     * There is no way around re-parsing — the core keeps `Rc` graphs with no
+     * `Deserialize` — but every part of that cost sits off the critical path. The
+     * hydrated blocks are already painted and STAY painted: `softReset` preserves
+     * them exactly as the setContent divergence swap does, so the reader keeps
+     * reading and scrolling while the worker chews through the history on its own
+     * thread. The caller's new chunks need no buffer of ours — `postMessage` is
+     * FIFO per worker, so they queue behind the re-feed and are parsed the instant
+     * it catches up. When the re-parse's patch lands, `mergeStale` adopts every
+     * unchanged block BY REFERENCE (same object, same id), so the swap re-renders
+     * and remounts nothing, and the live tail streams on from there.
+     */
+    private beginResume;
+    /** The resume re-feed is no longer wanted: either it has just been issued, or
+     *  the caller took over by driving the whole document itself. Releases the
+     *  retained source so one document, not two, stays in memory. */
+    private retireHydration;
+    /** Drop every trace of a hydrate. An explicit reset() is a brand-new
+     *  document, so a restored view must not keep intercepting appends or re-feed
+     *  a source that is no longer the one being streamed. */
+    private clearHydration;
     reset(): void;
     /**
      * setContent's divergence reset: rebuild the parser exactly like {@link reset},

package/dist/client.js

@@ -4,6 +4,20 @@ import { noteSplice } from "./splice.js";
 function emptyBlockStore() {
   return { committed: /* @__PURE__ */ new Map(), committedOrder: [], active: [], snapshot: [] };
 }
+const HYDRATE_VERSION = 1;
+function sourceFingerprint(source) {
+  let h = 2166136261;
+  for (let i = 0; i < source.length; i++) {
+    h ^= source.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function isPersistedBlock(b) {
+  if (typeof b !== "object" || b === null) return false;
+  const x = b;
+  return typeof x.id === "number" && Number.isFinite(x.id) && typeof x.html === "string" && typeof x.start === "number" && typeof x.end === "number" && typeof x.open === "boolean" && typeof x.speculative === "boolean" && typeof x.kind === "object" && x.kind !== null && typeof x.kind.type === "string";
+}
 function htmlToText(html) {
   return html.replace(/<[^>]*>/g, " ").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&").replace(/\s+/g, " ").trim();
 }
@@ -344,6 +358,12 @@ class BrookClient {
   // same-length-or-shorter replacement the growth check misses). Also cleared on
   // an explicit caller reset().
   recoveryAttempted = false;
+  // Whether any chunk has been appended in this generation. Read only by
+  // getPersistable's source fallback, to tell "nothing was ever driven" (whose
+  // source is the empty document) from "driven, but this client did not retain
+  // it" — the one configuration, recovery off plus manual appends, where the
+  // source is genuinely unknown and the caller must supply it.
+  appendedAny = false;
   // Opt-in rAF coalescing (see constructor `coalesce`). When on AND
   // requestAnimationFrame exists, intra-frame emit()s collapse into ONE
   // rAF-scheduled flush to listeners — the React useSyncExternalStore path then
@@ -388,6 +408,24 @@ class BrookClient {
   /** 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;
+  // --- Hydration (see getPersistable / hydrate) ---
+  // Set by hydrate(): this store was FILLED FROM JSON, never parsed, so no
+  // worker has ever seen this document. Sticky until reset() — a resumed client
+  // is still "a hydrated client" as far as getPersistable is concerned.
+  hydrated = false;
+  // The restored envelope's own fields, kept so the resume can re-check
+  // staleness and so getPersistable() can re-emit an untouched snapshot exactly.
+  hydratedDone = false;
+  hydratedLength = 0;
+  hydratedHash = "";
+  // The original markdown behind a hydrated snapshot (hydrate's `source`), held
+  // ONLY until the resume re-feed consumes it. Null for a `done` snapshot, which
+  // is terminal and needs none.
+  hydratedSource = null;
+  // Latch: the resume re-feed has been issued, or the caller took over by
+  // driving the whole document itself. From here append()/finalize() behave
+  // exactly as on any other client.
+  resumed = false;
   // Perf
   appendedBytes = 0;
   patchCount = 0;
@@ -492,8 +530,15 @@ class BrookClient {
     this.resetParser();
   }
   get ready() {
+    if (this.hydrationPending) return true;
     return this.pw?.ready ?? false;
   }
+  /** True while a hydrated document has never been handed to a parser: the
+   *  store holds restored blocks and no worker exists. Cleared once the resume
+   *  re-feed is issued (or the caller re-drives the whole document itself). */
+  get hydrationPending() {
+    return this.hydrated && !this.resumed;
+  }
   /**
    * The fatal error that killed this client's worker, or `null` if healthy.
    *
@@ -508,6 +553,7 @@ class BrookClient {
     return this.failedError;
   }
   whenReady() {
+    if (this.hydrationPending) return Promise.resolve();
     const pw = this.ensureAcquired();
     return this.pool.whenWorkerReady(pw);
   }
@@ -520,9 +566,11 @@ class BrookClient {
     return this.config;
   }
   append(chunk) {
+    if (this.hydrationPending) this.beginResume();
     const pw = this.ensureAcquired();
     this.settleRebind();
     if (this.firstAppendMs === 0) this.firstAppendMs = performance.now();
+    this.appendedAny = true;
     if (this.recovery) {
       this.recoveryBuffer += chunk;
       if (this.recoveryAttempted && this.recoveryBuffer.length > this.recoveredLen) {
@@ -532,6 +580,10 @@ class BrookClient {
     this.pool.send(pw, { type: "append", streamId: this.streamId, chunk, config: this.firstConfig(), epoch: this.epoch });
   }
   finalize() {
+    if (this.hydrationPending) {
+      if (this.hydratedDone) return;
+      this.beginResume();
+    }
     const pw = this.ensureAcquired();
     this.settleRebind();
     this.finalizePending = true;
@@ -633,12 +685,14 @@ class BrookClient {
       if (!this.contentDone && content.startsWith(this.lastContent)) {
         if (this.lastContent === "" && content.length > 0 && this.getSnapshot().length > 0) {
           this.softReset(this.getSnapshot());
+          this.retireHydration();
         }
         this.append(content.slice(this.lastContent.length));
       } else {
         const displayed = this.getSnapshot();
         if (content.length > 0 && displayed.length > 0) this.softReset(displayed);
         else this.reset();
+        this.retireHydration();
         this.append(content);
       }
       this.lastContent = content;
@@ -649,6 +703,195 @@ class BrookClient {
       this.contentDone = true;
     }
   }
+  /**
+   * Capture everything this client currently renders as a plain-JSON
+   * {@link PersistableSnapshot}: `JSON.stringify` it, store it beside the
+   * thread, and {@link hydrate} it back later to repaint with **no parse at
+   * all**. This is the persistence half of instant thread reopen.
+   *
+   * The committed wire is already a complete serialization — a committed block
+   * is emitted exactly once and is final (WIRE.md §2) — so there is nothing to
+   * re-derive: the snapshot IS the document. Cost here is one pass to
+   * fingerprint the source; cost on the way back in is a `Map` fill.
+   *
+   * @param source the markdown driven into this stream, used ONLY to compute
+   *   {@link PersistableSnapshot.sourceHash}. Optional, because a client with
+   *   `recovery` on (the default) already retains it, as does a
+   *   `setContent`-driven one; required in the single configuration that holds
+   *   neither — `recovery: false` plus manual `append()` — where omitting it
+   *   throws rather than persisting a snapshot no one can check for staleness.
+   */
+  getPersistable(source) {
+    const blocks = this.getSnapshot();
+    if (source === void 0 && this.hydrationPending) {
+      return {
+        hydrateVersion: HYDRATE_VERSION,
+        blocks,
+        sourceLength: this.hydratedLength,
+        sourceHash: this.hydratedHash,
+        done: this.hydratedDone
+      };
+    }
+    const src = source ?? this.retainedSource();
+    if (src === null) {
+      throw new Error(
+        "brookmd: getPersistable() needs the source markdown to fingerprint, and this client retains none (constructed with `recovery: false` and driven with append()). Pass it explicitly: client.getPersistable(source)."
+      );
+    }
+    return {
+      hydrateVersion: HYDRATE_VERSION,
+      blocks,
+      sourceLength: src.length,
+      sourceHash: sourceFingerprint(src),
+      done: this.contentDone
+    };
+  }
+  /** The full driven document when this client happens to hold it: the recovery
+   *  buffer is exactly that whenever `recovery` is on (the default), and
+   *  setContent's baseline covers the recovery-off controlled-string mode.
+   *  `null` means genuinely unknown — reachable only with recovery off AND
+   *  manual appends. */
+  retainedSource() {
+    if (this.recovery) return this.recoveryBuffer;
+    if (this.lastContent.length > 0) return this.lastContent;
+    if (!this.appendedAny) return "";
+    return null;
+  }
+  /**
+   * Restore a {@link PersistableSnapshot} into an untouched client. The blocks
+   * land in the store as ordinary committed blocks and `getSnapshot()` returns
+   * them immediately, so the first paint already has the whole document —
+   * **no worker is created, no WASM loads, nothing is parsed**. Reopening a
+   * thread costs O(blocks) of JSON handling instead of O(source) of parsing.
+   *
+   * Call it on a fresh client before anything is appended and, ideally, before
+   * the renderer mounts (hydrating an already-mounted client works — it
+   * notifies subscribers — but costs an extra render). Hydrating a client that
+   * already holds content throws.
+   *
+   * **Resuming a live thread.** A snapshot with `done: false` was still
+   * streaming. Pass `source` — the markdown behind the snapshot — and the first
+   * {@link append} rebuilds parser state in the background: the parser's
+   * internals are an `Rc` graph with no serialized form, so continuing a
+   * document genuinely requires re-parsing what came before it, but that cost
+   * moves OFF the critical path. The hydrated blocks stay on screen and the
+   * reader scrolls them while the worker catches up; new chunks queue behind the
+   * re-feed and land the moment it does. Without `source` the thread is
+   * view-only and appending throws — continuing a document correctly is not
+   * possible without the text that precedes it.
+   *
+   * **Hydration does not verify the blocks against the source.** The snapshot is
+   * trusted as produced; `sourceHash` exists so the CALLER can notice its stored
+   * source moved on and re-stream instead of painting stale HTML. The resume
+   * path re-checks it, lets the fresh parse win, and warns in dev.
+   *
+   * @throws if the envelope version is unknown, the snapshot is malformed, or
+   *   this client already holds content. Validation completes before anything is
+   *   written, so a rejected snapshot leaves the client exactly as it was.
+   */
+  hydrate(snapshot, opts) {
+    if (this.hydrated || this.pw !== null || this.getSnapshot().length > 0) {
+      throw new Error(
+        "brookmd: hydrate() must be called on an untouched client, before any append()/setContent()/finalize(). Construct a new BrookClient (or reset() this one)."
+      );
+    }
+    if (typeof snapshot !== "object" || snapshot === null) {
+      throw new Error("brookmd: hydrate() expects a PersistableSnapshot object.");
+    }
+    if (snapshot.hydrateVersion !== HYDRATE_VERSION) {
+      throw new Error(
+        `brookmd: cannot hydrate a version ${String(snapshot.hydrateVersion)} snapshot \u2014 this build reads version ${HYDRATE_VERSION}. Discard it and re-stream the source.`
+      );
+    }
+    if (!Array.isArray(snapshot.blocks) || typeof snapshot.done !== "boolean" || typeof snapshot.sourceHash !== "string" || typeof snapshot.sourceLength !== "number" || !Number.isFinite(snapshot.sourceLength) || snapshot.sourceLength < 0) {
+      throw new Error(
+        "brookmd: malformed PersistableSnapshot (bad blocks / done / sourceHash / sourceLength)."
+      );
+    }
+    const committed = /* @__PURE__ */ new Map();
+    const committedOrder = new Array(snapshot.blocks.length);
+    for (let i = 0; i < snapshot.blocks.length; i++) {
+      const b = snapshot.blocks[i];
+      if (!isPersistedBlock(b)) {
+        throw new Error(
+          `brookmd: malformed PersistableSnapshot \u2014 block at index ${i} is not a Block.`
+        );
+      }
+      if (committed.has(b.id)) {
+        throw new Error(`brookmd: malformed PersistableSnapshot \u2014 duplicate block id ${b.id}.`);
+      }
+      committedOrder[i] = b.id;
+      committed.set(b.id, b);
+    }
+    this.store = { committed, committedOrder, active: [], snapshot: snapshot.blocks.slice() };
+    this.hydrated = true;
+    this.hydratedDone = snapshot.done;
+    this.hydratedLength = snapshot.sourceLength;
+    this.hydratedHash = snapshot.sourceHash;
+    this.hydratedSource = snapshot.done ? null : opts?.source ?? null;
+    if (this.hydratedSource !== null) this.lastContent = this.hydratedSource;
+    this.contentDone = snapshot.done;
+    this.emit(true);
+  }
+  /**
+   * The first content-bearing op on a hydrated thread: give the parser back the
+   * state it could not be handed.
+   *
+   * There is no way around re-parsing — the core keeps `Rc` graphs with no
+   * `Deserialize` — but every part of that cost sits off the critical path. The
+   * hydrated blocks are already painted and STAY painted: `softReset` preserves
+   * them exactly as the setContent divergence swap does, so the reader keeps
+   * reading and scrolling while the worker chews through the history on its own
+   * thread. The caller's new chunks need no buffer of ours — `postMessage` is
+   * FIFO per worker, so they queue behind the re-feed and are parsed the instant
+   * it catches up. When the re-parse's patch lands, `mergeStale` adopts every
+   * unchanged block BY REFERENCE (same object, same id), so the swap re-renders
+   * and remounts nothing, and the live tail streams on from there.
+   */
+  beginResume() {
+    if (this.hydratedLength === 0 && this.store.snapshot.length === 0) {
+      this.retireHydration();
+      return;
+    }
+    if (this.hydratedDone) {
+      throw new Error(
+        "brookmd: this client was hydrated from a FINALIZED snapshot (done: true), and a completed thread cannot be appended to. Call reset() to start a new stream, or hydrate a `done: false` snapshot with its `source` to resume one."
+      );
+    }
+    const source = this.hydratedSource;
+    if (source === null) {
+      throw new Error(
+        "brookmd: cannot append to a hydrated client without its source. Continuing a document means re-parsing the text that came before it \u2014 pass it at hydrate time: client.hydrate(snapshot, { source })."
+      );
+    }
+    this.retireHydration();
+    if (typeof process !== "undefined" && process.env.NODE_ENV !== "production" && (source.length !== this.hydratedLength || sourceFingerprint(source) !== this.hydratedHash)) {
+      warnOnce(
+        "hydrate-stale",
+        "brookmd: the source passed to hydrate() does not match the snapshot's fingerprint, so the resume re-parse will replace the hydrated blocks. Compare `snapshot.sourceHash` with `sourceFingerprint(source)` before hydrating and re-stream when they differ."
+      );
+    }
+    this.softReset(this.getSnapshot());
+    this.append(source);
+  }
+  /** The resume re-feed is no longer wanted: either it has just been issued, or
+   *  the caller took over by driving the whole document itself. Releases the
+   *  retained source so one document, not two, stays in memory. */
+  retireHydration() {
+    this.resumed = true;
+    this.hydratedSource = null;
+  }
+  /** Drop every trace of a hydrate. An explicit reset() is a brand-new
+   *  document, so a restored view must not keep intercepting appends or re-feed
+   *  a source that is no longer the one being streamed. */
+  clearHydration() {
+    this.hydrated = false;
+    this.resumed = false;
+    this.hydratedDone = false;
+    this.hydratedSource = null;
+    this.hydratedLength = 0;
+    this.hydratedHash = "";
+  }
   reset() {
     const hadContent = this.getSnapshot().length > 0;
     this.staleSnapshot = null;
@@ -657,6 +900,7 @@ class BrookClient {
     this.failedError = null;
     this.recoveryAttempted = false;
     this.pendingRebind = false;
+    this.clearHydration();
     this.resetParser();
     if (hadContent) this.emit(true);
   }
@@ -712,6 +956,7 @@ class BrookClient {
     this.firstAppendMs = 0;
     this.retainedBytes = 0;
     this.wasmMemoryBytes = 0;
+    this.appendedAny = false;
     this.lastContent = "";
     this.contentDone = false;
     this.recoveryBuffer = "";
@@ -1035,5 +1280,6 @@ export {
   __resetDefaultPool,
   applyPatch,
   emptyBlockStore,
-  getDefaultPool
+  getDefaultPool,
+  sourceFingerprint
 };

package/dist/element.js

@@ -20,7 +20,8 @@ const CONFIG_ATTRS = [
   "soft-breaks",
   "a11y",
   "unsafe-html",
-  "block-html"
+  "block-html",
+  "retain-committed-html"
 ];
 function defineBrookMarkdown(tag = "brook-markdown") {
   if (typeof customElements === "undefined") return;
@@ -162,6 +163,7 @@ function defineBrookMarkdown(tag = "brook-markdown") {
       set("a11y", "a11y");
       set("unsafe-html", "unsafeHtml");
       set("block-html", "blockHtml");
+      set("retain-committed-html", "retainCommittedHtml");
       const tags = this.getAttribute("component-tags");
       if (tags !== null) {
         const list = tags.split(/[\s,]+/).filter(Boolean);

package/dist/index.d.ts

@@ -15,7 +15,8 @@
  *     // ... wherever your tokens land: client.append(deltaText);
  *     client.finalize();
  */
-export { BrookClient, BrookPool, getDefaultPool } from "./client.js";
+export { BrookClient, BrookPool, getDefaultPool, sourceFingerprint } from "./client.js";
+export type { PersistableSnapshot } from "./client.js";
 export { BrookMarkdown, useBrookStream, useBrookMarkdownString } from "./react.js";
 export { highlight, supportedLangs } from "./hi.js";
 export { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { BrookClient, BrookPool, getDefaultPool } from "./client.js";
+import { BrookClient, BrookPool, getDefaultPool, sourceFingerprint } from "./client.js";
 import { BrookMarkdown, useBrookStream, useBrookMarkdownString } from "./react.js";
 import { highlight, supportedLangs } from "./hi.js";
 import { htmlToReact, parseTrustedHtml, safeUrl, wrapLink } from "./html-to-react.js";
@@ -11,6 +11,7 @@ export {
   htmlToReact,
   parseTrustedHtml,
   safeUrl,
+  sourceFingerprint,
   supportedLangs,
   useBrookMarkdownString,
   useBrookStream,

package/dist/server.js

@@ -54,6 +54,7 @@ function makeParser(config) {
   p.setBlockHtml(config?.blockHtml ?? false);
   p.setAllowSchemes(config?.allowSchemes ?? []);
   p.setBlockData(config?.blockData ?? false);
+  p.setRetainCommittedHtml(true);
   return p;
 }
 function requireReady() {

package/dist/types-core.d.ts

@@ -513,6 +513,22 @@ export interface ParserConfig {
      * serde bytes; output and the `kind` serde shape stay byte-identical when off).
      */
     blockData?: boolean;
+    /**
+     * Keep every committed block's rendered HTML retained **inside the parser**.
+     *
+     * Defaults to **false on the streaming path** (the worker), which is what you
+     * want: the client receives each committed block exactly once, in the patch
+     * that commits it, and stores it itself — so a second copy sitting in WASM for
+     * the life of the stream serves nobody. Dropping it roughly halves a long
+     * stream's retained bytes (`onPatch`'s `retainedBytes`); the wire is
+     * byte-identical either way.
+     *
+     * Set `true` only if you need the parser itself to still hold the whole
+     * rendered document. The server one-shot renderers (`renderToString`,
+     * `parseToBlocks`) read the document back out of the parser and therefore pin
+     * this on regardless of what you pass.
+     */
+    retainCommittedHtml?: boolean;
 }
 export type ToWorker = {
     type: "append";

package/dist/wasm/brook_md_core.d.ts

@@ -139,6 +139,18 @@ export class BrookParser {
      * markers all stay strictly conformant.
      */
     setLenientLists(on: boolean): void;
+    /**
+     * Keep every committed block's rendered HTML retained inside the parser for
+     * `allBlocks()`. ON by default. Turn it OFF in a pure STREAMING consumer —
+     * one that reads each committed block exactly once out of its patch and
+     * never calls `allBlocks()` (the npm worker): the HTML is then released the
+     * moment the block is emitted, so a long stream retains the source buffer
+     * plus the open tail instead of the whole rendered document (`retainedBytes`
+     * reflects it). Patch bytes are identical either way; the only cost is that
+     * `allBlocks()` then reports committed blocks with an EMPTY `html` (id,
+     * kind, start, end, open, speculative all stay exact).
+     */
+    setRetainCommittedHtml(on: boolean): void;
     /**
      * Render a CommonMark SOFT line break (a bare `\n` in inline content) as a
      * `<br>` — the `remark-breaks` convention, where one Enter is one visual
@@ -188,6 +200,7 @@ export interface InitOutput {
     readonly brookparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly brookparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
     readonly brookparser_setLenientLists: (a: number, b: number) => void;
+    readonly brookparser_setRetainCommittedHtml: (a: number, b: number) => void;
     readonly brookparser_setSoftBreaks: (a: number, b: number) => void;
     readonly brookparser_setUnsafeHtml: (a: number, b: number) => void;
     readonly brookparser_setWireDelta: (a: number, b: number) => void;

package/dist/wasm/brook_md_core.js

@@ -290,6 +290,21 @@ export class BrookParser {
     setLenientLists(on) {
         wasm.brookparser_setLenientLists(this.__wbg_ptr, on);
     }
+    /**
+     * Keep every committed block's rendered HTML retained inside the parser for
+     * `allBlocks()`. ON by default. Turn it OFF in a pure STREAMING consumer —
+     * one that reads each committed block exactly once out of its patch and
+     * never calls `allBlocks()` (the npm worker): the HTML is then released the
+     * moment the block is emitted, so a long stream retains the source buffer
+     * plus the open tail instead of the whole rendered document (`retainedBytes`
+     * reflects it). Patch bytes are identical either way; the only cost is that
+     * `allBlocks()` then reports committed blocks with an EMPTY `html` (id,
+     * kind, start, end, open, speculative all stay exact).
+     * @param {boolean} on
+     */
+    setRetainCommittedHtml(on) {
+        wasm.brookparser_setRetainCommittedHtml(this.__wbg_ptr, on);
+    }
     /**
      * Render a CommonMark SOFT line break (a bare `\n` in inline content) as a
      * `<br>` — the `remark-breaks` convention, where one Enter is one visual

package/dist/wasm/brook_md_core_bg.wasm.d.ts

@@ -22,6 +22,7 @@ export const brookparser_setGfmTagfilter: (a: number, b: number) => void;
 export const brookparser_setHtmlSanitize: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const brookparser_setInlineComponentTags: (a: number, b: number, c: number) => void;
 export const brookparser_setLenientLists: (a: number, b: number) => void;
+export const brookparser_setRetainCommittedHtml: (a: number, b: number) => void;
 export const brookparser_setSoftBreaks: (a: number, b: number) => void;
 export const brookparser_setUnsafeHtml: (a: number, b: number) => void;
 export const brookparser_setWireDelta: (a: number, b: number) => void;

package/dist/worker.js

@@ -29,6 +29,7 @@ const core = new WorkerCore({
     p.setBlockHtml(c?.blockHtml ?? false);
     p.setAllowSchemes(c?.allowSchemes ?? []);
     p.setBlockData(c?.blockData ?? false);
+    p.setRetainCommittedHtml(c?.retainCommittedHtml ?? false);
     p.setWireDelta(true);
     return p;
   },

package/package.json

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