@cplieger/web-terminal-ui 5.2.2 → 5.3.0

package/src/kernel/scrollback-storage.ts

@@ -0,0 +1,316 @@
+// A ready-made localStorage implementation of the scrollback-persistence seam.
+//
+// `persistScrollback` takes the storage rather than a switch, for reasons that
+// belong to the library (see ScrollbackPersistence). That is the right boundary
+// and it stays. But every consumer that wants the feature then writes the same
+// forty lines, and four of them writing it four times is four places for the
+// orphan sweep to be forgotten — which is the one part a consumer is most likely
+// to skip, because nothing breaks when it is missing until the quota fills.
+//
+// So this is a supplied implementation, never a default: a consumer still has to
+// pass it, which is what keeps the feature off unless someone decided it should
+// be on.
+//
+// The stored value is NOT bare JSON: it is the timestamp on its own line, then
+// the snapshot JSON. That is what lets the orphan sweep read one number per entry
+// without parsing hundreds of kilobytes of payload on the boot path, and it keeps
+// one source of truth per field. This module writes and reads that format and
+// nothing else touches it; an unrecognised value is treated as expired, which is
+// the same handling an entry from an older release would get anyway.
+//
+// localStorage rather than IndexedDB, deliberately. It is SYNCHRONOUS, which is
+// exactly what the seam needs — hydration has to complete before the resume
+// announces what the client holds — so a consumer using this needs no async
+// bootstrap at all, and the kernel's boot path is unchanged. It also holds no
+// connection open, so it costs nothing in bfcache eligibility, which is the
+// reason the library declined to own a database in the first place. The cost is
+// the origin quota (~5 MB in Safari), which is why this implementation sweeps and
+// caps rather than only writing.
+
+import type { ScrollbackPersistence } from "./types.js";
+import type { StoreSnapshot } from "@cplieger/web-terminal-engine";
+import { DEFAULT_MAX_AGE_MS } from "./scrollback.js";
+import { positiveIntOption } from "./options.js";
+
+/** Key prefix, so a snapshot cannot collide with the host application's own
+ *  localStorage keys (a consumer that already persists UI state has some). */
+const DEFAULT_PREFIX = "wt.scrollback.";
+
+/**
+ * Total budget for everything this store owns, in CHARACTERS.
+ *
+ * A count cap was the first answer and it was wrong, because it does not bound
+ * what actually runs out. Measured on the real stored envelope at the 200-line
+ * default: a plain 80-column session is ~24 K characters, a coloured one (a
+ * prompt, `ls`, any TUI — several runs per line) ~60 K, and a wide coloured one
+ * ~112 K. Both WebKit and Blink account localStorage in UTF-16 code units, so the
+ * quota cost is roughly double the character count, and the floor to design
+ * against is Safari's ~5 MiB per origin (Chrome and Firefox are commonly ~10 MB).
+ *
+ * 512 KiB of characters is therefore about 1 MiB of quota, a fifth of that floor,
+ * which leaves the host application the rest — and holds roughly eight typical
+ * coloured sessions or four wide ones. The earlier 20-entry cap allowed 20 x 112 K
+ * = 2.2 M characters, over 4 MiB of quota, so the cap itself guaranteed the
+ * refusal it was meant to prevent.
+ */
+const DEFAULT_MAX_BYTES = 512 * 1024;
+
+export interface LocalScrollbackStorageOptions {
+  /** Key prefix (default `"wt.scrollback."`). */
+  prefix?: string;
+  /** Maximum age of a stored entry. Applied BOTH by this store's sweep and,
+   *  because it is passed straight through on the returned object, by the kernel
+   *  when it decides whether to load one — so the two cannot disagree. */
+  maxAgeMs?: number;
+  /** Total budget for everything this store owns, in CHARACTERS (default 512 KiB,
+   *  about 1 MiB of localStorage quota since it is accounted in UTF-16). Enforced
+   *  by the construction-time sweep AND after every write, oldest entry first. */
+  maxBytes?: number;
+  /** Newest lines persisted per session; passed through to the kernel. */
+  lines?: number;
+  /** Background save cadence; passed through to the kernel. */
+  saveIntervalMs?: number;
+}
+
+/** Read localStorage, or null when it is unavailable.
+ *
+ *  Not a one-time capability check, and the two failures are not the same one: a
+ *  browser set to block site data throws on ACCESS to `window.localStorage`
+ *  (Chrome and Firefox), while Safari historically let access succeed in private
+ *  browsing and threw on the WRITE instead. Storage can also be revoked
+ *  mid-session (a user clearing site data, an ITP eviction), so every operation
+ *  asks again and a refusal on the READ side degrades to "nothing stored" rather
+ *  than to an exception crossing back into the kernel. */
+function store(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/** The `savedAt` of a stored value, without parsing the payload.
+ *
+ *  The sweep needs one number from each entry and the payloads are hundreds of
+ *  kilobytes, so parsing every one of them would put tens of milliseconds on the
+ *  boot path to produce a timestamp comparison. Hence the stored format below:
+ *  the timestamp on its own line, then the snapshot JSON. Reading it is a scan to
+ *  the first newline whatever the payload's size or shape.
+ *
+ *  An unreadable head reads as expired, which is the safe direction: an entry
+ *  this module cannot recognise is one the kernel would reject anyway. */
+function savedAtOf(value: string): number | null {
+  const nl = value.indexOf("\n");
+  if (nl <= 0) {
+    return null;
+  }
+  const at = Number(value.slice(0, nl));
+  return Number.isFinite(at) ? at : null;
+}
+
+/**
+ * A `ScrollbackPersistence` backed by `localStorage`, complete with the orphan
+ * collection the kernel cannot do for itself.
+ *
+ * The kernel enforces the age bound on the entries it LOADS, which collects a
+ * session the user comes back to. It can do nothing about a session nobody ever
+ * opens again — and the case this feature exists for, a browser discarding a tab,
+ * is precisely the case where no close handler ran to drop it. Only the store can
+ * enumerate, so only the store can sweep, and it does so once at construction:
+ * anything past the age bound goes, then the oldest go until the count fits.
+ *
+ * Pass it straight through:
+ *
+ * ```ts
+ * createTerminal("#terminal", {
+ *   features: presetTabbed,
+ *   persistScrollback: localScrollbackStorage(),
+ * });
+ * ```
+ */
+export function localScrollbackStorage(
+  options: LocalScrollbackStorageOptions = {},
+): ScrollbackPersistence {
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  // Resolved once and used for BOTH the sweep below and the kernel's load-time
+  // check, by handing the same number back on the returned object.
+  // Through the shared validator, so an invalid value is REPORTED here exactly as
+  // it is on the keeper's own options. These two inline ternaries used to swallow
+  // it, which made the same typo loud or silent depending only on which of the two
+  // option bags the consumer happened to write it in.
+  const maxAgeMs = positiveIntOption(
+    options.maxAgeMs,
+    DEFAULT_MAX_AGE_MS,
+    "localScrollbackStorage.maxAgeMs",
+  );
+  const maxBytes = positiveIntOption(
+    options.maxBytes,
+    DEFAULT_MAX_BYTES,
+    "localScrollbackStorage.maxBytes",
+  );
+
+  const keyFor = (sessionId: string): string => prefix + sessionId;
+
+  function remove(key: string): void {
+    const ls = store();
+    if (!ls) {
+      return;
+    }
+    try {
+      ls.removeItem(key);
+    } catch {
+      /* storage refused the write; nothing useful to do about it */
+    }
+  }
+
+  /** Every key this store owns, with its timestamp and its size in characters.
+   *  Collected by index rather than by `Object.keys`, because localStorage's own
+   *  keys are the only authoritative list and an entry written by an older release
+   *  may not parse. */
+  function ownEntries(): { key: string; savedAt: number | null; chars: number }[] {
+    const ls = store();
+    if (!ls) {
+      return [];
+    }
+    const found: { key: string; savedAt: number | null; chars: number }[] = [];
+    try {
+      for (let i = 0; i < ls.length; i++) {
+        const key = ls.key(i);
+        if (!key?.startsWith(prefix)) {
+          continue;
+        }
+        const value = ls.getItem(key);
+        found.push({
+          key,
+          savedAt: value === null ? null : savedAtOf(value),
+          chars: (value?.length ?? 0) + key.length,
+        });
+      }
+    } catch {
+      return found;
+    }
+    return found;
+  }
+
+  /** Bring the store within its budgets: expired entries go first (they are dead
+   *  weight whatever the total), then the oldest survivors until the character
+   *  budget fits.
+   *
+   *  Run at construction AND after every successful write, because a sweep that
+   *  only runs at construction bounds nothing on a long-lived page: a session
+   *  opened after boot is a new key nothing has audited, and the case this store
+   *  exists for is precisely the page that stays open for days. */
+  function sweep(): void {
+    const now = Date.now();
+    const live: { key: string; savedAt: number; chars: number }[] = [];
+    let total = 0;
+    for (const entry of ownEntries()) {
+      // An unreadable timestamp is treated as expired: the kernel would refuse
+      // the entry anyway, so keeping it only consumes quota.
+      if (entry.savedAt === null || Math.abs(now - entry.savedAt) > maxAgeMs) {
+        remove(entry.key);
+        continue;
+      }
+      live.push({ key: entry.key, savedAt: entry.savedAt, chars: entry.chars });
+      total += entry.chars;
+    }
+    if (total <= maxBytes) {
+      return;
+    }
+    // Newest first, then keep entries while they fit and drop the rest: an entry
+    // the user last saw a minute ago is worth more than one from this morning.
+    // Written as "keep what fits" rather than "remove until it fits" because the
+    // latter, walking a newest-first list, evicts the newest — which is what the
+    // first version did.
+    live.sort((a, b) => b.savedAt - a.savedAt);
+    let kept = 0;
+    for (const entry of live) {
+      if (kept + entry.chars <= maxBytes) {
+        kept += entry.chars;
+        continue;
+      }
+      remove(entry.key);
+    }
+  }
+
+  sweep();
+
+  return {
+    maxAgeMs,
+    ...(options.lines !== undefined ? { lines: options.lines } : {}),
+    ...(options.saveIntervalMs !== undefined ? { saveIntervalMs: options.saveIntervalMs } : {}),
+    load(sessionId) {
+      const ls = store();
+      if (!ls) {
+        return null;
+      }
+      let raw: string | null;
+      try {
+        raw = ls.getItem(keyFor(sessionId));
+      } catch {
+        return null;
+      }
+      if (raw === null) {
+        return null;
+      }
+      const savedAt = savedAtOf(raw);
+      if (savedAt === null) {
+        remove(keyFor(sessionId));
+        return null;
+      }
+      try {
+        // The snapshot is returned unvalidated on purpose: the kernel validates
+        // every field against the engine's snapshot contract, and duplicating that
+        // here would give two places to disagree about what a usable entry is. A
+        // parse failure is the one thing this layer must handle, since it throws.
+        return { savedAt, snapshot: JSON.parse(raw.slice(raw.indexOf("\n") + 1)) as StoreSnapshot };
+      } catch {
+        remove(keyFor(sessionId));
+        return null;
+      }
+    },
+    save(sessionId, entry) {
+      const ls = store();
+      if (!ls) {
+        // Storage is unavailable, not merely full. Throwing lets the keeper see
+        // that nothing was persisted; returning normally made it record a
+        // watermark for a write that never happened, after which its background
+        // pass skipped the session until output advanced again.
+        throw new Error("web-terminal-ui: localStorage is unavailable");
+      }
+      // The timestamp on its own line, then the snapshot: one source of truth per
+      // field, and the sweep above reads the head without parsing the payload.
+      const key = keyFor(sessionId);
+      const value = `${String(entry.savedAt)}\n${JSON.stringify(entry.snapshot)}`;
+      if (value.length + key.length > maxBytes) {
+        // One entry larger than the whole budget cannot be stored without evicting
+        // everything, and would still not fit. Refuse it and KEEP whatever is
+        // already there: a smaller, older snapshot of this session restores
+        // something, where an eviction spiral restores nothing.
+        throw new Error("web-terminal-ui: scrollback snapshot exceeds the storage budget");
+      }
+      try {
+        ls.setItem(key, value);
+      } catch (err) {
+        // Over quota, or storage revoked mid-session. Deliberately does NOT delete
+        // the previous value: a refused replacement does not invalidate what is
+        // already stored, and deleting it turned a transient quota failure into
+        // permanent loss of this session's history. Sweep (an expired neighbour may
+        // be all that is in the way), retry once, and rethrow if it still will not
+        // land, so the keeper does not record a phantom save.
+        sweep();
+        try {
+          ls.setItem(key, value);
+        } catch {
+          throw err instanceof Error ? err : new Error(String(err));
+        }
+        return;
+      }
+      // Enforce the budget against what is now stored, including this write.
+      sweep();
+    },
+    drop(sessionId) {
+      remove(keyFor(sessionId));
+    },
+  };
+}

package/src/kernel/scrollback.ts

@@ -0,0 +1,333 @@
+// Scrollback persistence: the kernel's half of CreateTerminalOptions.
+// persistScrollback.
+//
+// The split is mechanism here, storage in the consumer. The engine supplies the
+// data (LineStore.snapshot / LineStore.fromSnapshot, plain structuredClone-safe
+// objects) and the identity of the server process it belongs to
+// (connection.serverEpochOf / adoptPersistedEpoch); this module owns WHEN a
+// snapshot is taken, WHETHER a stored one may be trusted, and the age bound. The
+// consumer owns where the bytes live, because a library that opened its own
+// IndexedDB would hold a connection that costs bfcache eligibility — which this
+// kernel depends on — and because how long a terminal's output may sit on disk
+// is an application decision.
+//
+// It serves both compositions through one object: the kernel hydrates its
+// implicit store for a single unmanaged terminal, and a session-owning feature
+// gets a hydrated store per session from ctx.newLineStore(sessionId). Anything
+// tracked here is saved; nothing else is.
+
+import { LineStore, connection } from "@cplieger/web-terminal-engine";
+import { positiveIntOption } from "./options.js";
+import type { PersistedScrollback, ScrollbackPersistence } from "./types.js";
+
+/**
+ * Newest lines persisted per session when the consumer names no bound.
+ *
+ * 200, not the store's own cap. The closest precedent is VS Code's
+ * `terminal.integrated.persistentSessionScrollback`, which restores 100 lines by
+ * default — evidence that the screen plus recent history is what a returning user
+ * needs, and that a full buffer is not. 200 gives headroom over that while keeping
+ * the cost honest: measured on the real stored envelope, 200 lines is ~24 K
+ * characters plain and ~60 K coloured, serialising in under a millisecond, against
+ * ~122 K / ~298 K and up to 4 ms at 1000. Since a write happens on every
+ * backgrounding and on a timer while output advances, that difference is paid
+ * repeatedly on the device this feature exists for.
+ */
+const DEFAULT_PERSIST_LINES = 200;
+/** How long a stored entry may be used. A week covers "back to it on Monday"
+ *  while keeping an abandoned session's output from living indefinitely.
+ *
+ *  Exported within the kernel so a storage implementation that must SWEEP its own
+ *  orphans (scrollback-storage.ts) bounds them by the same number the keeper
+ *  refuses to load past. Two constants here would drift into a store that keeps
+ *  entries nothing will ever read, or deletes ones still in use. */
+export const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Background save cadence while content is advancing. */
+const DEFAULT_SAVE_INTERVAL_MS = 10_000;
+
+/** What the kernel drives. Every method is safe to call at any point in the
+ *  terminal's life, including after stop(). */
+export interface ScrollbackKeeper {
+  /** The store for a session: hydrated from storage when a usable entry exists,
+   *  otherwise a fresh one. Either way the store is tracked for saving. Seeds
+   *  the persisted server epoch, so this MUST be called before that session
+   *  connects. */
+  storeFor(sessionId: string): LineStore;
+  /** Track a store this module did not create (the kernel's implicit store when
+   *  nothing was restored for it), so it is saved like any other. It reads as
+   *  needing a save, whatever it already holds. */
+  track(sessionId: string, store: LineStore): void;
+  /** Stop tracking a session and delete its stored entry (a closed tab). */
+  forget(sessionId: string): void;
+  /** Save every tracked session whose content has advanced since its last
+   *  recorded save. For the page-lifecycle callbacks, which are the last chance
+   *  rather than an optimisation. */
+  flush(): void;
+  /** Report that a session withheld its id, so persistence could not apply. */
+  noteMissingSessionId(): void;
+  /** Release the background timer. */
+  stop(): void;
+}
+
+/** Read a stored entry's timestamp defensively. The value has been outside this
+ *  program's memory, so its type is an assumption until checked. */
+function savedAtOf(entry: unknown): number | null {
+  if (typeof entry !== "object" || entry === null) {
+    return null;
+  }
+  const at = (entry as Record<string, unknown>)["savedAt"];
+  return typeof at === "number" && Number.isFinite(at) ? at : null;
+}
+
+/** Read a stored snapshot's server epoch defensively, or 0 for "unknown".
+ *
+ *  Stricter than "a finite number", because this value is adopted as a session's
+ *  IDENTITY: the server reports a process-start timestamp in nanoseconds, so a
+ *  negative or fractional value cannot have come from one and is a corrupt or
+ *  hand-edited entry wearing the shape of a real one. 0 is the library's existing
+ *  "unknown", and every rejection lands there. */
+function epochOf(entry: unknown): number {
+  if (typeof entry !== "object" || entry === null) {
+    return 0;
+  }
+  const snap = (entry as Record<string, unknown>)["snapshot"];
+  if (typeof snap !== "object" || snap === null) {
+    return 0;
+  }
+  const epoch = (snap as Record<string, unknown>)["serverEpoch"];
+  return typeof epoch === "number" && Number.isSafeInteger(epoch) && epoch > 0 ? epoch : 0;
+}
+
+export function createScrollbackKeeper(
+  cfg: ScrollbackPersistence,
+  storeCap: number | undefined,
+): ScrollbackKeeper {
+  const lines = positiveIntOption(cfg.lines, DEFAULT_PERSIST_LINES, "persistScrollback.lines");
+  const maxAgeMs = positiveIntOption(
+    cfg.maxAgeMs,
+    DEFAULT_MAX_AGE_MS,
+    "persistScrollback.maxAgeMs",
+  );
+  const saveIntervalMs = positiveIntOption(
+    cfg.saveIntervalMs,
+    DEFAULT_SAVE_INTERVAL_MS,
+    "persistScrollback.saveIntervalMs",
+  );
+
+  /** Every store that should be saved, by session id. */
+  const tracked = new Map<string, LineStore>();
+  /** The highest absolute index each session's last save contained, so the
+   *  background pass can skip a session whose content has not advanced. Absent
+   *  means never saved, which always reads as needing a save. */
+  const savedThrough = new Map<string, number>();
+  let warnedMissingId = false;
+  let warnedNoEpoch = false;
+  let warnedSaveFailed = false;
+  let stopped = false;
+
+  function newStore(): LineStore {
+    return new LineStore(storeCap);
+  }
+
+  function drop(sessionId: string): void {
+    try {
+      cfg.drop(sessionId);
+    } catch {
+      /* storage unavailable, or the consumer threw: nothing to do about it */
+    }
+  }
+
+  /** Load and validate a stored entry, dropping it when it cannot be used.
+   *  Returns the hydrated store, or null to start empty and take a full resume.
+   *
+   *  Every rejection below has that same correct handling, which is why none of
+   *  them throws or reports: the worst outcome of starting empty is one slow
+   *  restore, and the worst outcome of hydrating something unsound is a terminal
+   *  that shows content from a session that no longer exists. */
+  function hydrate(sessionId: string): LineStore | null {
+    let entry: PersistedScrollback | null | undefined;
+    try {
+      entry = cfg.load(sessionId);
+    } catch {
+      return null;
+    }
+    if (entry === null || entry === undefined) {
+      return null;
+    }
+
+    const savedAt = savedAtOf(entry);
+    // Distance in either direction: a clock that moved backwards would otherwise
+    // leave an entry whose age never reaches the bound.
+    if (savedAt === null || Math.abs(Date.now() - savedAt) > maxAgeMs) {
+      drop(sessionId);
+      return null;
+    }
+
+    const store = LineStore.fromSnapshot(entry.snapshot, storeCap);
+    if (store === null) {
+      drop(sessionId);
+      return null;
+    }
+
+    // Structure checked; now the one rejection that is a real decision rather
+    // than a validation. An entry with no server epoch cannot be verified
+    // against the server it is about to be shown next to, and absolute line
+    // indices only mean anything within one server process: a restarted server
+    // begins again near 0, so a hydrated store whose epoch cannot be compared
+    // would present old content as live AND then refuse the new session's
+    // output, because those low indices fall below what the hydrated store
+    // believes it evicted. A terminal that fills in slowly is a far better
+    // failure than one that is wrong and then permanently blank, so an
+    // unverifiable entry is discarded. In practice this never fires: an epoch is
+    // missing only from a server that reports none at all, in which case restart
+    // detection was never available to anyone.
+    const epoch = epochOf(entry);
+    if (epoch === 0) {
+      if (!warnedNoEpoch) {
+        warnedNoEpoch = true;
+        console.warn(
+          "web-terminal-ui: discarding persisted scrollback with no server epoch (this server does not report one, so a restart cannot be detected)",
+        );
+      }
+      drop(sessionId);
+      return null;
+    }
+
+    // The epoch must reach the connection layer BEFORE this session's resume, or
+    // the first resumeAck records it with nothing to compare against and a
+    // restart goes undetected for exactly the content that needed checking.
+    connection.adoptPersistedEpoch(sessionId, epoch);
+    return store;
+  }
+
+  function saveOne(sessionId: string, store: LineStore): void {
+    // Save under the epoch this session is CURRENTLY known to belong to. A
+    // session that has not resumed yet reports 0, and a snapshot that cannot be
+    // verified on the way back in is not worth writing on the way out.
+    const epoch = connection.serverEpochOf(sessionId);
+    if (epoch === 0) {
+      return;
+    }
+    const snapshot = store.snapshot(epoch, lines);
+    // null means the store holds nothing. Skipping rather than writing an empty
+    // entry is the engine's contract, and it matters here: it is what stops a
+    // just-reset store from erasing a good snapshot. The stale entry that
+    // survives instead is self-invalidating, because its epoch no longer
+    // matches — which is the whole reason the epoch is persisted.
+    if (snapshot === null) {
+      return;
+    }
+    try {
+      cfg.save(sessionId, { savedAt: Date.now(), snapshot });
+    } catch {
+      // Nothing was persisted (over quota, storage revoked, an entry too large).
+      // Do NOT record a watermark: the whole point of the watermark is "this is on
+      // disk", and recording one here made the background pass skip the session
+      // until its output advanced again, which is how a full store stopped
+      // persisting silently. Warned once, because a feature that quietly does
+      // nothing is worse than one that says why.
+      if (!warnedSaveFailed) {
+        warnedSaveFailed = true;
+        console.warn(
+          "web-terminal-ui: could not persist scrollback (storage full or unavailable); the terminal is unaffected and will keep retrying",
+        );
+      }
+      return;
+    }
+    savedThrough.set(sessionId, snapshot.highest);
+  }
+
+  /** Save a session whose content has advanced since its last recorded save.
+   *
+   *  Absent from `savedThrough` means never saved, which always counts as
+   *  advanced. */
+  function saveIfAdvanced(sessionId: string, store: LineStore): void {
+    if (store.highestIndex() !== savedThrough.get(sessionId)) {
+      saveOne(sessionId, store);
+    }
+  }
+
+  /** The background pass.
+   *
+   *  "Advanced" is the highest absolute index, so it misses a redraw that rewrote
+   *  rows already on screen without printing new ones. That is a deliberate trade,
+   *  not a free one, and the residue is worth naming: usually the re-sent window
+   *  corrects a stale row on the next resume, but not when the session kept
+   *  printing while the page was gone — the window has moved past that row by then,
+   *  and the replay only covers lines above `haveThrough`, so a stale in-place
+   *  rewrite (a spinner, a progress line) can sit in restored scrollback until it is
+   *  evicted. Bounded by one screen height, and it needs the discard path where no
+   *  lifecycle callback ran. Closing it would mean re-serialising the tail on every
+   *  screen update, a continuous cost on the device least able to afford it, to fix
+   *  at most a screenful of cosmetically stale history. */
+  function saveAdvanced(): void {
+    for (const [sessionId, store] of tracked) {
+      saveIfAdvanced(sessionId, store);
+    }
+  }
+
+  const timer = setInterval(saveAdvanced, saveIntervalMs);
+
+  return {
+    storeFor(sessionId) {
+      const restored = hydrate(sessionId);
+      const store = restored ?? newStore();
+      tracked.set(sessionId, store);
+      if (restored !== null) {
+        // A restored store's content IS the entry that was just read, so seed the
+        // watermark to stop the first background pass from rewriting a
+        // byte-identical entry. Nothing else may seed it: an unsaved store must
+        // read as needing a save, whatever it already holds.
+        savedThrough.set(sessionId, restored.highestIndex());
+      }
+      return store;
+    },
+    track(sessionId, store) {
+      tracked.set(sessionId, store);
+      savedThrough.delete(sessionId);
+    },
+    forget(sessionId) {
+      tracked.delete(sessionId);
+      savedThrough.delete(sessionId);
+      drop(sessionId);
+    },
+    flush() {
+      if (stopped) {
+        return;
+      }
+      // Same predicate as the background pass, and NOT an unconditional write.
+      // Under the tabs feature every tab gets a store and every one is hydrated at
+      // load, but only the ACTIVE session's store advances, because there is one
+      // socket. So a page holding another session's store frozen at its load-time
+      // content would, on being backgrounded, write that frozen content over a
+      // second page's newer entry — with a fresh timestamp, which also made the
+      // stale copy the one the sweep preferred. The next discard then restored the
+      // rolled-back entry and replayed thousands of lines, which is the exact
+      // symptom this feature exists to remove.
+      //
+      // A store that has not advanced since its last recorded save has nothing new
+      // to write, so skipping it loses nothing. What it gives up is refreshing
+      // `savedAt` on a long-idle open session, costing one full replay after the
+      // age bound expires — the right trade against silently discarding another
+      // page's history.
+      for (const [sessionId, store] of tracked) {
+        saveIfAdvanced(sessionId, store);
+      }
+    },
+    noteMissingSessionId() {
+      if (warnedMissingId) {
+        return;
+      }
+      warnedMissingId = true;
+      console.warn(
+        "web-terminal-ui: persistScrollback is enabled but a feature called ctx.newLineStore() without a session id, so that session's scrollback is not persisted",
+      );
+    },
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+      tracked.clear();
+      savedThrough.clear();
+    },
+  };
+}