brookmd 0.22.2 → 0.23.1

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.23.1 — 2026-07-21
+
+### Changed
+
+- Documentation only: the README now covers wire delta mode (the 0.23.0
+  headline) — measured numbers, the automatic worker↔client behavior, and the
+  raw-boundary opt-in — plus refreshed platform-status notes across the
+  repository. No code changes; behavior identical to 0.23.0.
+
+## 0.23.0 — 2026-07-21
+
+### Added
+
+- **Wire delta mode — the streaming re-emit floor is retired** (wire contract
+  **v1.2.0**, additive). Previously, every `append` re-emitted each open
+  block's full HTML across the WASM→worker→main-thread boundary, making total
+  emitted bytes O(n²/chunk) for a block that grows across many chunks — the
+  documented "re-emit floor". Now the parser can emit a **verified splice**
+  (`html_delta: { keep_bytes, keep_units, append }`) against the block's
+  previous emit instead; splices are established by byte comparison, never by
+  structural inference, so reconstruction is byte-exact by construction.
+
+  Measured at 200 KB / 256-byte chunks: a streaming list's total patch JSON
+  drops **119.6 MB → 0.78 MB (153× less)** with **2.8× faster** end-to-end
+  parse+serialize; an unclosed code fence **80.1 MB → 0.58 MB (137×, 4.9×
+  faster)**. Fast-committing shapes are unchanged (no regression). The curve
+  is now linear, so the gap keeps widening with document size.
+
+  - The npm package enables this **automatically and invisibly** — the worker
+    opts in, and the client reconstructs full blocks before anything else sees
+    them. No API change; `Block.html` is always complete.
+  - `brookmd-react-native` does the same across the JSI boundary.
+  - Raw-boundary consumers (`BrookParser`, native `BrookSession`, C ABI): the
+    mode is **opt-in** (`setWireDelta(true)` / `wire_delta: true`) and the
+    default wire is byte-identical to contract v1.1.0. Enabling it obliges you
+    to reconstruct per [WIRE.md §11](../../crates/brookmd-core/WIRE.md).
+  - Pinned by: reconstruction-parity suites (Rust corpus × chunkings, dual
+    UTF-8/UTF-16 offset verification), wire goldens in all five language
+    surfaces (core, FFI, C-ABI, Kotlin, Swift), a fuzzer extension asserting
+    per-patch reconstruction on arbitrary inputs, and a new scaling-gate test
+    that *fails CI* if delta-mode emitted bytes regress from linear.
+
 ## 0.22.2 — 2026-07-21
 
 ### Performance

package/README.md

@@ -4,7 +4,7 @@ Zero-dep streaming markdown for the browser. Rust→WASM core, one Web Worker pe
 
 Drop in a streaming-aware renderer — **React, Vue, Svelte, Solid, a framework-agnostic `<brook-markdown>` Web Component, or the vanilla DOM mount** — wire each LLM stream to a `BrookClient`, and the markdown renders incrementally off the main thread, block by block, with stable identities so unchanged blocks never re-reconcile.
 
-Parsing runs entirely **off the main thread** — each stream gets its own pooled Web Worker, so many concurrent LLM responses render without contending for the UI thread. On each token the parser re-parses only the **active tail**, not the whole document, and heavy renderers (syntax highlighting, math, mermaid) are **deferred until a block closes**. The result is low retained memory and a main thread that stays responsive while streaming. See [the live demo](https://md.hsingh.app/).
+Parsing runs entirely **off the main thread** — each stream gets its own pooled Web Worker, so many concurrent LLM responses render without contending for the UI thread. On each token the parser re-parses only the **active tail**, not the whole document; patches cross the worker boundary as **verified splices** (not full re-sends, so emitted bytes stay O(n) even for one giant growing block); and heavy renderers (syntax highlighting, math, mermaid) are **deferred until a block closes**. The result is low retained memory and a main thread that stays responsive while streaming. See [the live demo](https://md.hsingh.app/).
 
 > **Beyond the browser:** the same Rust core also powers experimental React
 > Native, Swift (iOS/macOS), Kotlin/Android, Flutter, and C-ABI bindings —
@@ -1044,6 +1044,26 @@ Headline numbers are not durable across machines, but the curve is: chunk size
 shouldn't change the order of magnitude for any shape. If you hit one that does,
 file an issue with the input and chunking — that's the next bench scenario.
 
+### Wire delta mode (automatic)
+
+Parse work was already O(n), but until 0.23.0 the **bytes crossing the
+worker→main-thread boundary** were not: every append re-emitted the open
+block's full HTML, O(n²/chunk) total for one block that grows across many
+chunks (a long streaming list, a big code fence). Since 0.23.0 the parser
+emits **verified splices** instead — `{keep, append}` deltas against the
+block's previous emit, established by byte comparison so reconstruction is
+byte-exact by construction — and the client reassembles full blocks before
+anything else sees them. Zero API change; `Block.html` is always complete.
+
+Measured at a 200 KB document in 256-byte chunks, a streaming list's total
+patch traffic drops from **119.6 MB to 0.78 MB (153× less, 2.8× faster
+end-to-end)**; an unclosed code fence from **80.1 MB to 0.58 MB (137×, 4.9×
+faster)**. Fast-committing prose is unchanged. Emitted bytes are now gated
+linear in CI alongside the parse-work counters. Raw-boundary consumers (the
+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).
+
 ## Security
 
 brookmd is XSS-safe by default — its HTML output is meant to be injected via

package/dist/client.js

@@ -10,7 +10,19 @@ function applyPatch(store, patch) {
     if (!store.committed.has(b.id)) store.committedOrder.push(b.id);
     store.committed.set(b.id, b);
   }
-  store.active = patch.active;
+  const active = new Array(patch.active.length);
+  for (let i = 0; i < patch.active.length; i++) {
+    const entry = patch.active[i];
+    if ("html_delta" in entry) {
+      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 };
+    } else {
+      active[i] = entry;
+    }
+  }
+  store.active = active;
   const next = new Array(store.committedOrder.length + store.active.length);
   for (let i = 0; i < store.committedOrder.length; i++) {
     next[i] = store.committed.get(store.committedOrder[i]);
@@ -679,13 +691,13 @@ class BrookClient {
         let patch;
         try {
           patch = JSON.parse(msg.patch);
+          applyPatch(this.store, patch);
         } catch (e) {
           const message = e instanceof Error ? e.message : String(e);
           if (this.onError) this.onError({ message: `brookmd: malformed patch (${message})` });
           else console.error("brookmd: malformed patch:", message);
           break;
         }
-        applyPatch(this.store, patch);
         if (msg.final === true && this.staleSnapshot) {
           this.staleTrimmed = true;
           this.mergeCache = null;

package/dist/types-core.d.ts

@@ -164,9 +164,30 @@ export interface Block {
     open: boolean;
     speculative: boolean;
 }
+/**
+ * Wire delta mode (WIRE.md §11): the splice an active block carries in place
+ * of `html` when it was already emitted in the previous patch. Reconstruct
+ * with `prev.slice(0, keep_units) + append` (JS strings are UTF-16, so
+ * `keep_units` is the right offset here; `keep_bytes` is the same prefix for
+ * byte-oriented consumers).
+ */
+export interface WireHtmlDelta {
+    keep_bytes: number;
+    keep_units: number;
+    append: string;
+}
+/**
+ * An `active` array entry as serialized: a full {@link Block}, or (wire delta
+ * mode only) every Block field except `html` plus an `html_delta` splice.
+ * {@link applyPatch} reconstructs deltas into full Blocks — nothing past the
+ * store ever sees this union.
+ */
+export type WireActiveBlock = Block | (Omit<Block, "html"> & {
+    html_delta: WireHtmlDelta;
+});
 export interface Patch {
     newly_committed: Block[];
-    active: Block[];
+    active: WireActiveBlock[];
 }
 /**
  * Per-block render-churn sample passed to an {@link RenderMetricsHook}. Lets you

package/dist/wasm/README.md

@@ -52,15 +52,24 @@ entirely:
 
 ```toml
 [dependencies]
-brookmd-core = { version = "0.20", default-features = false }
+brookmd-core = { version = "0.23", default-features = false }
 ```
 
 ## Wire format
 
 Blocks and patches serialize to a stable, language-agnostic JSON wire format —
-see [WIRE.md](WIRE.md) (wire contract v1.1.0). Native consumers can produce the
+see [WIRE.md](WIRE.md) (wire contract v1.2.0). Native consumers can produce the
 same bytes as the WASM/JS boundary via `wire::patch_to_json` / `wire::blocks_to_json`.
 
+Contract v1.2.0 adds the opt-in **wire delta mode**
+(`StreamParser::set_wire_delta`): active blocks re-emitted across appends
+serialize as verified `html_delta` splices against their previous emit instead
+of full `html`, making total emitted bytes O(n) for a block that grows across
+many appends (WIRE.md §11). Off by default — the default wire stays
+byte-identical to v1.1.0. A consumer that enables it reconstructs
+`prev[..keep] + append` per patch; the npm and React Native packages do this
+transparently.
+
 ## Links
 
 - npm package: <https://www.npmjs.com/package/brookmd>

package/dist/wasm/brook_md_core.d.ts

@@ -112,6 +112,15 @@ export class BrookParser {
      * when rendering untrusted input — bypasses XSS protection.
      */
     setUnsafeHtml(on: boolean): void;
+    /**
+     * Opt-in wire delta mode (WIRE.md §11): active blocks re-emitted across
+     * appends serialize as verified `html_delta` splices against their previous
+     * emit instead of full `html`, making total emitted bytes O(n) for a block
+     * that grows across many appends. Off by default (wire byte-identical to
+     * pre-delta releases). A consumer that enables this must reconstruct
+     * active `html` per WIRE.md §11 — the npm package's client does.
+     */
+    setWireDelta(on: boolean): void;
 }
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
@@ -137,6 +146,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_setUnsafeHtml: (a: number, b: number) => void;
+    readonly brookparser_setWireDelta: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;

package/dist/wasm/brook_md_core.js

@@ -255,6 +255,18 @@ export class BrookParser {
     setUnsafeHtml(on) {
         wasm.brookparser_setUnsafeHtml(this.__wbg_ptr, on);
     }
+    /**
+     * Opt-in wire delta mode (WIRE.md §11): active blocks re-emitted across
+     * appends serialize as verified `html_delta` splices against their previous
+     * emit instead of full `html`, making total emitted bytes O(n) for a block
+     * that grows across many appends. Off by default (wire byte-identical to
+     * pre-delta releases). A consumer that enables this must reconstruct
+     * active `html` per WIRE.md §11 — the npm package's client does.
+     * @param {boolean} on
+     */
+    setWireDelta(on) {
+        wasm.brookparser_setWireDelta(this.__wbg_ptr, on);
+    }
 }
 if (Symbol.dispose) BrookParser.prototype[Symbol.dispose] = BrookParser.prototype.free;
 function __wbg_get_imports() {

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

@@ -20,6 +20,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_setUnsafeHtml: (a: number, b: number) => void;
+export const brookparser_setWireDelta: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_add_to_stack_pointer: (a: number) => number;

package/dist/worker.js

@@ -25,6 +25,7 @@ const core = new WorkerCore({
       c?.dropHtmlTags ?? []
     );
     p.setBlockData(c?.blockData ?? false);
+    p.setWireDelta(true);
     return p;
   },
   post: (msg) => ctx.postMessage(msg),

package/package.json

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