flux-md 0.20.0 → 0.20.2

package/README.md

@@ -156,7 +156,12 @@ use it from any binding.
 > append-only so parsing stays incremental. Re-transforming the *whole* string
 > each token (so earlier bytes change) forces `setContent` to reparse every tick
 > (O(n²)); that's what render-time overrides avoid. `setContent`'s reset path is
-> for the **once**-at-the-end reprocess swap, not per-token rewrites.
+> for the **once**-at-the-end reprocess swap, not per-token rewrites. That swap
+> is seamless: the current view stays on screen while the new string reparses —
+> 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. (`setContent("")` is an explicit clear and resets
+> immediately.)
 
 <details>
 <summary>Full manual control (caller-owned client)</summary>
@@ -552,9 +557,9 @@ class FluxClient {
   ): Promise<void>;
   finalize(): void;                                 // mark stream complete
   setContent(                                       // drive from a controlled full string
-    full: string,                                   // diffs vs last: prefix → append delta; else reset+reparse
-    opts?: { done?: boolean },                      // done:true → finalize
-  ): void;
+    full: string,                                   // diffs vs last: prefix → append delta; else seamless
+    opts?: { done?: boolean },                      //   reset+reparse (view held, unchanged blocks keep identity)
+  ): void;                                          // done:true → finalize
   reset(): void;                                    // wipe and reuse
   destroy(): void;                                  // free this stream's parser
   whenReady(): Promise<void>;                       // resolves once WASM loaded; rejects on init failure

package/dist/client.d.ts

@@ -133,6 +133,10 @@ export declare class FluxClient {
     private rafHandle;
     private finalizePending;
     private epoch;
+    private staleSnapshot;
+    private staleTrimmed;
+    private idNamespace;
+    private mergeCache;
     private appendedBytes;
     private patchCount;
     private totalParseMicros;
@@ -154,6 +158,10 @@ export declare class FluxClient {
      *   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
@@ -221,7 +229,12 @@ export declare class FluxClient {
      *   - **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.
+     *     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,
@@ -243,6 +256,27 @@ export declare class FluxClient {
         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
@@ -253,6 +287,28 @@ export declare class FluxClient {
     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, its id offset into this
+     *     generation's namespace (adopted old ids and raw new ids could collide);
+     *   - 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.

package/dist/client.js

@@ -162,6 +162,7 @@ class FluxPool {
     }
   }
 }
+const ID_NAMESPACE_STRIDE = 4294967296;
 function poolCap() {
   const hc = typeof navigator !== "undefined" ? navigator.hardwareConcurrency : 0;
   return Math.min(hc || 4, 8);
@@ -213,6 +214,29 @@ class FluxClient {
   // echoed back on each patch; a patch whose epoch is older than this is a
   // pre-reset straggler and is dropped before it can repopulate the cleared store.
   epoch = 0;
+  // --- Preserved-view divergence swap (setContent's reset+reparse path) ---
+  // The displayed snapshot captured by softReset(). While set, getSnapshot()
+  // returns a positional merge of this view over the rebuilding store, so the
+  // document never blanks out during a divergence reparse and unchanged blocks
+  // keep their object identity AND id (React key / DOM node key) across the
+  // swap. It persists after the reparse completes — dropping it would revert
+  // the adopted ids and remount every block one notify later.
+  staleSnapshot = null;
+  // Set when the reparse's terminal (final) patch lands: the merge stops
+  // padding with the old document's tail, so a shorter replacement trims to the
+  // new length on that very notify.
+  staleTrimmed = false;
+  // Id offset applied to non-adopted new blocks in a merged view. A divergence
+  // reparse restarts core block ids at 0 (fresh parser), and streamed ids are
+  // chunk-dependent (tail reparses burn ids) — so a changed block's new id can
+  // collide with a retained old block's id in the same merged snapshot.
+  // Bumped by ID_NAMESPACE_STRIDE per generation, which keeps every merged id
+  // provably unique: adopted ids are all below the current namespace.
+  idNamespace = 0;
+  // getSnapshot() cache: (store.snapshot ref, trimmed) → merged array. Repeated
+  // reads between notifies must return the SAME reference — the
+  // useSyncExternalStore cached-snapshot contract.
+  mergeCache = null;
   // Perf
   appendedBytes = 0;
   patchCount = 0;
@@ -238,6 +262,10 @@ class FluxClient {
    *   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
@@ -366,7 +394,12 @@ class FluxClient {
    *   - **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.
+   *     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,
@@ -387,9 +420,14 @@ class FluxClient {
   setContent(content, opts) {
     if (content !== this.lastContent) {
       if (!this.contentDone && content.startsWith(this.lastContent)) {
+        if (this.lastContent === "" && content.length > 0 && this.getSnapshot().length > 0) {
+          this.softReset(this.getSnapshot());
+        }
         this.append(content.slice(this.lastContent.length));
       } else {
-        this.reset();
+        const displayed = this.getSnapshot();
+        if (content.length > 0 && displayed.length > 0) this.softReset(displayed);
+        else this.reset();
         this.append(content);
       }
       this.lastContent = content;
@@ -401,7 +439,57 @@ class FluxClient {
     }
   }
   reset() {
-    const hadContent = this.store.snapshot.length > 0;
+    const hadContent = this.getSnapshot().length > 0;
+    this.staleSnapshot = null;
+    this.staleTrimmed = false;
+    this.mergeCache = null;
+    this.resetParser();
+    if (hadContent) this.emit(true);
+  }
+  /**
+   * 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.
+   */
+  softReset(preserve) {
+    this.staleSnapshot = preserve;
+    this.staleTrimmed = false;
+    this.idNamespace += ID_NAMESPACE_STRIDE;
+    this.resetParser();
+    this.mergeCache = { base: this.store.snapshot, trimmed: false, view: preserve };
+  }
+  /**
+   * 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).
+   */
+  collapseStale() {
+    if (this.store.active.length > 0) return;
+    const view = this.getSnapshot();
+    const committed = /* @__PURE__ */ new Map();
+    const committedOrder = new Array(view.length);
+    for (let i = 0; i < view.length; i++) {
+      committedOrder[i] = view[i].id;
+      committed.set(view[i].id, view[i]);
+    }
+    this.store = { committed, committedOrder, active: [], snapshot: view };
+    this.staleSnapshot = null;
+    this.staleTrimmed = false;
+    this.mergeCache = null;
+  }
+  // Shared generation teardown: swap in an empty store, zero the metrics and
+  // the setContent baseline, invalidate any coalesced frame, bump the epoch,
+  // and tell the worker to drop the parser. View concerns (stale preservation,
+  // subscriber notify) belong to the callers — reset() and softReset().
+  resetParser() {
     this.store = emptyBlockStore();
     this.appendedBytes = 0;
     this.patchCount = 0;
@@ -417,7 +505,6 @@ class FluxClient {
     this.epoch += 1;
     const pw = this.ensureAcquired();
     this.pool.send(pw, { type: "reset", streamId: this.streamId, epoch: this.epoch });
-    if (hadContent) this.emit(true);
   }
   destroy() {
     if (!this.attached) return;
@@ -449,7 +536,65 @@ class FluxClient {
     this.listeners.add(fn);
     return () => this.listeners.delete(fn);
   };
-  getSnapshot = () => this.store.snapshot;
+  getSnapshot = () => {
+    const base = this.store.snapshot;
+    if (!this.staleSnapshot) return base;
+    const cache = this.mergeCache;
+    if (cache && cache.base === base && cache.trimmed === this.staleTrimmed) return cache.view;
+    const view = this.mergeStale(base, cache && cache.trimmed === this.staleTrimmed ? cache : null);
+    this.mergeCache = { base, trimmed: this.staleTrimmed, view };
+    return view;
+  };
+  /**
+   * 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, its id offset into this
+   *     generation's namespace (adopted old ids and raw new ids could collide);
+   *   - 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.
+   */
+  mergeStale(base, prev) {
+    const stale = this.staleSnapshot;
+    const len = this.staleTrimmed ? base.length : Math.max(base.length, stale.length);
+    const view = new Array(len);
+    for (let i = 0; i < len; i++) {
+      const nb = i < base.length ? base[i] : void 0;
+      if (nb !== void 0 && prev !== null && i < prev.base.length && prev.base[i] === nb) {
+        view[i] = prev.view[i];
+        continue;
+      }
+      const ob = i < stale.length ? stale[i] : void 0;
+      if (!nb) {
+        view[i] = ob;
+        continue;
+      }
+      if (ob) {
+        if (nb.open && !this.staleTrimmed) {
+          view[i] = ob;
+          continue;
+        }
+        if (nb.html === ob.html && nb.kind.type === ob.kind.type && nb.open === ob.open && nb.speculative === ob.speculative) {
+          view[i] = ob;
+          continue;
+        }
+      }
+      view[i] = { ...nb, id: this.idNamespace + nb.id };
+    }
+    return view;
+  }
   /**
    * Internal: a renderer with an `onRenderMetrics` hook calls this once per
    * actual React block render so `getMetrics().renderCount` aggregates churn.
@@ -497,7 +642,7 @@ class FluxClient {
    */
   outline() {
     const out = [];
-    for (const b of this.store.snapshot) {
+    for (const b of this.getSnapshot()) {
       if (b.kind.type === "Heading") {
         const d = b.kind.data;
         const level = typeof d === "number" ? d : d?.level ?? 1;
@@ -515,7 +660,7 @@ class FluxClient {
    */
   toPlaintext() {
     const parts = [];
-    for (const b of this.store.snapshot) {
+    for (const b of this.getSnapshot()) {
       const t = htmlToText(b.html);
       if (t) parts.push(t);
     }
@@ -535,6 +680,11 @@ class FluxClient {
           break;
         }
         applyPatch(this.store, patch);
+        if (msg.final === true && this.staleSnapshot) {
+          this.staleTrimmed = true;
+          this.mergeCache = null;
+          this.collapseStale();
+        }
         this.appendedBytes = msg.appendedBytes;
         this.totalParseMicros += msg.parseMicros;
         this.retainedBytes = msg.retainedBytes;

package/dist/worker-core.js

@@ -125,8 +125,9 @@ class WorkerCore {
     try {
       const parser = this.getOrCreate(streamId);
       if (buffered && buffered.length > 0) {
-        parser.append(buffered);
+        const drained = parser.append(buffered);
         this.totalAppended.set(streamId, (this.totalAppended.get(streamId) ?? 0) + buffered.length);
+        this.emitPatch(streamId, drained, parser, 0, false);
       }
       const patch = parser.finalize();
       this.emitPatch(streamId, patch, parser, 0, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flux-md",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "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"],