brookmd 0.27.0 → 0.29.0

package/dist/client.js

@@ -1,8 +1,23 @@
 import { warnOnce } from "./warn.js";
 import { createWorker } from "./asset-urls.js";
+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();
 }
@@ -18,7 +33,9 @@ function applyPatch(store, patch) {
       const { html_delta, ...rest } = entry;
       const prev = store.active.find((b) => b.id === entry.id);
       if (!prev) throw new Error(`brookmd: html_delta for block ${entry.id} without a base`);
-      active[i] = { ...rest, html: prev.html.slice(0, html_delta.keep_units) + html_delta.append };
+      const next2 = { ...rest, html: prev.html.slice(0, html_delta.keep_units) + html_delta.append };
+      active[i] = next2;
+      noteSplice(next2, prev, html_delta.keep_units);
     } else {
       active[i] = entry;
     }
@@ -341,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
@@ -385,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;
@@ -489,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.
    *
@@ -505,6 +553,7 @@ class BrookClient {
     return this.failedError;
   }
   whenReady() {
+    if (this.hydrationPending) return Promise.resolve();
     const pw = this.ensureAcquired();
     return this.pool.whenWorkerReady(pw);
   }
@@ -517,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) {
@@ -529,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;
@@ -630,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;
@@ -646,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;
@@ -654,6 +900,7 @@ class BrookClient {
     this.failedError = null;
     this.recoveryAttempted = false;
     this.pendingRebind = false;
+    this.clearHydration();
     this.resetParser();
     if (hadContent) this.emit(true);
   }
@@ -709,6 +956,7 @@ class BrookClient {
     this.firstAppendMs = 0;
     this.retainedBytes = 0;
     this.wasmMemoryBytes = 0;
+    this.appendedAny = false;
     this.lastContent = "";
     this.contentDone = false;
     this.recoveryBuffer = "";
@@ -1032,5 +1280,6 @@ export {
   __resetDefaultPool,
   applyPatch,
   emptyBlockStore,
-  getDefaultPool
+  getDefaultPool,
+  sourceFingerprint
 };

package/dist/dom.d.ts

@@ -129,7 +129,24 @@ export interface MountOptions {
      * `client.getMetrics().rebuildCount`.
      */
     onRenderMetrics?: RenderMetricsHook;
+    /**
+     * @internal TEST-ONLY. Turn off the incremental apply fast paths — the open
+     * code block's frozen/tail mirror and the delta-driven child splice — so every
+     * changed open block rebuilds its whole node, exactly as it did before those
+     * existed. The DOM-parity fuzz mounts one renderer with this on and one with it
+     * off over the same patch stream and asserts their `innerHTML` matches after
+     * every sync: correctness must never depend on a fast path firing. Not part of
+     * the supported API and never useful in an app.
+     */
+    __fullRebuild?: boolean;
 }
+/** @internal Test-only. */
+export declare function __keyedStats(): {
+    attempts: number;
+    hits: number;
+};
+/** @internal Test-only. */
+export declare function __resetKeyedStats(): void;
 export declare function mountBrookMarkdown(client: BrookClient, container: HTMLElement, options?: MountOptions): MountHandle;
 /**
  * Derive the streaming tail's block id from an ordered snapshot: the id of the