@cplieger/web-terminal-ui 7.3.1 → 8.0.0

package/src/kernel/realm.ts

@@ -0,0 +1,11 @@
+/** The window of a document that has one, with that realm's constructors
+ *  (`win.Node`, `win.ResizeObserver`), so a value from another document is
+ *  checked against its own realm; a document with no browsing context (a parsed
+ *  or created document) cannot lay out or focus a terminal. */
+export function windowOf(doc: Document): Window & typeof globalThis {
+  const win = doc.defaultView;
+  if (win === null) {
+    throw new Error("web-terminal-ui: the mount target's document has no window");
+  }
+  return win;
+}

package/src/kernel/regions.ts

@@ -1,12 +1,8 @@
-// Layout regions (design section 22.13).
-//
-// The kernel owns a small layout skeleton: named regions with fixed geometry,
-// stacking, and keyboard-inset behavior. Features contribute chrome into a
-// region via ctx.region(name, slot); the region owns position, spacing, stack
-// direction, z-order, and the keyboard lift, so features cannot invent their own
-// placement or collide. DOM order within a region always equals visual order, so
-// focus order never diverges from reading order (WCAG 2.4.3): each slot is a
-// wrapper inserted in a declared order, and a feature appends into its slot.
+// Layout regions: named containers with fixed geometry, stacking and the
+// keyboard-inset lift. A feature appends its chrome into a slot of one region
+// and decides nothing about placement, so features cannot collide. DOM order
+// within a region equals visual order (WCAG 2.4.3): slots are inserted in a
+// declared order.
 
 import type { RegionName, RegionSlot } from "./types.js";
 
@@ -66,9 +62,10 @@ export function createRegions(root: HTMLElement): Regions {
   const containers = new Map<RegionName, HTMLElement>();
   const slots = new Map<string, HTMLElement>(); // "region:slot" -> slot element
   const unlistedSeen = new Map<string, number>();
+  const doc = root.ownerDocument;
 
   for (const name of REGION_NAMES) {
-    const el = document.createElement("div");
+    const el = doc.createElement("div");
     el.className = `wt-region wt-region-${name}`;
     el.dataset["region"] = name;
     root.appendChild(el);
@@ -85,7 +82,7 @@ export function createRegions(root: HTMLElement): Regions {
     if (!container) {
       throw new Error(`web-terminal-ui: unknown region ${name}`);
     }
-    const el = document.createElement("div");
+    const el = doc.createElement("div");
     el.className = `wt-slot wt-slot-${slot}`;
     el.dataset["slot"] = slot;
     // Insert in declared slot order: before the first existing child whose rank

package/src/kernel/scrollback.ts

@@ -1,46 +1,43 @@
-// 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.
+// Scrollback persistence: the shell's half of CreateTerminalOptions.
+// persistScrollback. The engine supplies the data (LineStore snapshots) and the
+// shell supplies the identity of the server process it belongs to (the
+// SessionEpochs port); 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.
 
-import { LineStore, connection } from "@cplieger/web-terminal-engine";
+import { LineStore } from "@cplieger/web-terminal-engine";
 import { positiveIntOption } from "./options.js";
 import type { 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.
- */
+/** The connection facts the keeper needs, answered by the shell over every pane's
+ *  connection: a tab's store follows the tab into whichever pane shows it. */
+export interface SessionEpochs {
+  /** Seed the epoch a stored snapshot was taken under, before the session
+   *  connects, so the first resumeAck has a value to compare against. */
+  adoptPersistedEpoch(sessionId: string, epoch: number): void;
+  /** The server epoch the session is currently known to belong to; 0 when it
+   *  has not resumed yet. */
+  serverEpochOf(sessionId: string): number;
+}
+
+/** The timers and clock the keeper runs on: the mounted window's, so the save
+ *  cadence and the age check follow the terminal's own clock. */
+export interface ScrollbackClock {
+  setInterval(handler: () => void, ms: number): number;
+  clearInterval(id: number): void;
+  readonly Date: Pick<DateConstructor, "now">;
+}
+
+/** Newest lines persisted per session when the consumer names no bound. Not the
+ *  store's cap: a write happens on every backgrounding and on a timer while
+ *  output advances, and 200 lines serialise in under a millisecond (~24 K
+ *  characters plain, ~60 K coloured) against up to 4 ms at 1000. VS Code
+ *  restores 100 by default. */
 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. */
+/** How long a stored entry may be used. Exported so a storage implementation
+ *  that sweeps its own orphans bounds them by the same number the keeper refuses
+ *  to load past. */
 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;
@@ -76,61 +73,35 @@ interface StoredEntry {
   /** `Date.now()` at the write. Finite. */
   readonly savedAt: number;
   /** The snapshot's server epoch, or null when the entry names no server
-   *  process.
-   *
-   *  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.
-   *
-   *  NOT 0-for-unknown. The engine spells "unknown" as 0 on its own surface and
-   *  that is its contract, but inheriting the spelling here put the rejection
-   *  value inside the range of accepted values, so `epoch > 0` and `epoch >= 0`
-   *  could not differ: at `epoch === 0` both yielded 0 and both were rejected
-   *  downstream. Out-of-band restores the distinction, and 0 goes back to being
-   *  a value the boundary refuses rather than the way it says no. */
+   *  process. A positive integer only: the value is adopted as a session's
+   *  IDENTITY (a process-start timestamp in nanoseconds), so a negative or
+   *  fractional one is a corrupt entry. Null rather than the engine's
+   *  0-for-unknown, which would put the rejection value inside the accepted
+   *  range. */
   readonly serverEpoch: number | null;
-  /** Still the engine's to parse. `LineStore.fromSnapshot` takes `unknown` and
-   *  is the authority on a snapshot's contents (engine store.ts:1584), so a
-   *  shape check here would be a second owner of one obligation. */
+  /** Still the engine's to parse: `LineStore.fromSnapshot` takes `unknown` and
+   *  owns what a snapshot contains. */
   readonly snapshot: unknown;
 }
 
-/**
- * Read a stored entry, or null when it cannot be used.
- *
- * `unknown` in, because the value has been outside this program's memory and
- * `ScrollbackPersistence.load`'s declared return type is an assumption about a
- * consumer's storage rather than a fact about its contents — the library's own
- * implementation produces one by `JSON.parse`. A `StoredEntry` out, so every
- * later line reads fields instead of re-establishing them.
- *
- * The parameter type carries the caller's proof: `hydrate` must separate "no
- * entry" from "bad entry" before calling, because those two have different
- * handling, so non-nullishness is already established. That is why there is no
- * object test here and why there must not be one — a property read on any other
- * primitive yields undefined and the field checks below reject it, so a `typeof
- * entry !== "object"` test would be a second statement of a thing the signature
- * already guarantees. This function had two of them, one per field it read, and
- * neither could be observed: 15 of the file's 19 surviving mutants were those
- * two guards and their bodies.
- */
-// Spelled `{}` rather than `NonNullable<unknown>`: the two are the same type, and
-// only the second is a type OPERATION, which `no-generated-empty-object-type`
-// (typescript-eslint 8.70+) reports even where resolving to `{}` is the point.
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- "any non-nullish value" is the intended type; the paragraph above says why there is no object test here
+/** Read a stored entry, or null when it cannot be used. The value has been
+ *  outside this program's memory, so the declared `load` return type is an
+ *  assumption. The parameter type carries the caller's proof of non-nullishness,
+ *  and a property read on any other primitive yields undefined and fails the
+ *  field checks, so there is no object test here and must not be one. */
+// `{}` rather than `NonNullable<unknown>`: the same type, but only the second is
+// a type OPERATION, which `no-generated-empty-object-type` reports.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- "any non-nullish value" is the intended type
 function readStoredEntry(entry: {}): StoredEntry | null {
   const rec = entry as Record<string, unknown>;
   const savedAt = rec["savedAt"];
-  // Finite, not merely a number: the age comparison below is a subtraction, and
   // `Math.abs(Date.now() - NaN) > maxAgeMs` is false, so a NaN timestamp would
   // read as freshly written forever.
   if (typeof savedAt !== "number" || !Number.isFinite(savedAt)) {
     return null;
   }
-  // Read through a nullable cast rather than a typeof test: `?.` is safe on a
-  // primitive as well as on null, so one operator covers every shape a stored
-  // value can have, and `fromSnapshot` owns what a usable snapshot contains.
+  // `?.` is safe on a primitive as well as on null, so one operator covers every
+  // shape a stored value can have.
   const snapshot = rec["snapshot"] as Record<string, unknown> | null | undefined;
   const epoch = snapshot?.["serverEpoch"];
   return {
@@ -144,6 +115,8 @@ function readStoredEntry(entry: {}): StoredEntry | null {
 export function createScrollbackKeeper(
   cfg: ScrollbackPersistence,
   storeCap: number | undefined,
+  epochs: SessionEpochs,
+  clock: ScrollbackClock,
 ): ScrollbackKeeper {
   const lines = positiveIntOption(cfg.lines, DEFAULT_PERSIST_LINES, "persistScrollback.lines");
   const maxAgeMs = positiveIntOption(
@@ -180,34 +153,21 @@ export function createScrollbackKeeper(
     }
   }
 
-  /** 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.
-   *
-   *  This function owns exactly two decisions and delegates the rest, which is
-   *  the point of its shape. It decides whether there is an entry at all, and
-   *  whether an entry that parsed may be USED (age, and verifiability). What an
-   *  entry's envelope must look like is `readStoredEntry`'s; what a snapshot must
-   *  contain is `LineStore.fromSnapshot`'s. Three owners, three depths, no
-   *  overlap — the arrangement this module did not have when its two readers each
-   *  re-established that the entry was an object. */
+  /** Load a stored entry, dropping it when it cannot be used. Returns the
+   *  hydrated store, or null to start empty and take a full resume. No rejection
+   *  throws or reports: starting empty costs one slow restore, while hydrating
+   *  something unsound shows content from a session that no longer exists. This
+   *  decides whether an entry exists and whether it may be USED (age,
+   *  verifiability); the envelope is `readStoredEntry`'s and the snapshot's
+   *  contents are the engine's. */
   function hydrate(sessionId: string): LineStore | null {
     let raw: unknown;
     try {
       raw = cfg.load(sessionId);
     } catch {
-      // Deliberately empty: a seam that threw has told us there is no entry, and
-      // `raw` is still undefined, which is exactly what the check below concludes.
-      // A `return null` here would be a second owner of "there is no entry".
+      // A seam that threw has said there is no entry; `raw` is still undefined.
     }
-    // "No entry" is silent and is not a rejection: nothing is dropped, because
-    // there is nothing to drop. Every path below this line has an entry to
-    // account for. This is also what lets `readStoredEntry` take a non-nullish
-    // parameter and therefore need no object test.
+    // No entry is not a rejection: nothing is dropped.
     if (raw === null || raw === undefined) {
       return null;
     }
@@ -220,7 +180,7 @@ export function createScrollbackKeeper(
 
     // Distance in either direction: a clock that moved backwards would otherwise
     // leave an entry whose age never reaches the bound.
-    if (Math.abs(Date.now() - entry.savedAt) > maxAgeMs) {
+    if (Math.abs(clock.Date.now() - entry.savedAt) > maxAgeMs) {
       drop(sessionId);
       return null;
     }
@@ -231,22 +191,11 @@ export function createScrollbackKeeper(
       return null;
     }
 
-    // Structure checked; now the one rejection that is a real decision rather
-    // than a validation, and the reason the epoch is read at the boundary but
-    // JUDGED here. 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.
-    //
-    // AFTER fromSnapshot, deliberately: reading it earlier would fire the warning
-    // below for a snapshot the engine was going to reject anyway.
+    // Absolute line indices only mean anything within one server process: a
+    // restarted server begins near 0, so a store whose epoch cannot be compared
+    // would show old content as live AND refuse the new output as already
+    // evicted. Judged AFTER fromSnapshot so the warning never fires for a
+    // snapshot the engine was going to reject anyway.
     if (entry.serverEpoch === null) {
       if (!warnedNoEpoch) {
         warnedNoEpoch = true;
@@ -261,7 +210,7 @@ export function createScrollbackKeeper(
     // 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, entry.serverEpoch);
+    epochs.adoptPersistedEpoch(sessionId, entry.serverEpoch);
     return store;
   }
 
@@ -269,28 +218,21 @@ export function createScrollbackKeeper(
     // 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);
+    const epoch = epochs.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.
+    // An empty store writes nothing, so a just-reset store cannot erase a good
+    // snapshot; the stale entry's epoch no longer matches, which invalidates it.
     if (snapshot === null) {
       return;
     }
     try {
-      cfg.save(sessionId, { savedAt: Date.now(), snapshot });
+      cfg.save(sessionId, { savedAt: clock.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.
+      // No watermark: recording one here made the background pass skip a session
+      // whose store never reached disk until its output advanced again.
       if (!warnedSaveFailed) {
         warnedSaveFailed = true;
         console.warn(
@@ -302,36 +244,25 @@ export function createScrollbackKeeper(
     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. */
+  /** Save a session whose content has advanced since its last recorded save;
+   *  never saved 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. */
+  /** The background pass. "Advanced" is the highest absolute index, so an
+   *  in-place rewrite of rows already on screen (a spinner, a progress line) can
+   *  sit stale in restored scrollback until evicted, bounded by one screen height.
+   *  Closing that would re-serialise the tail on every screen update. */
   function saveAdvanced(): void {
     for (const [sessionId, store] of tracked) {
       saveIfAdvanced(sessionId, store);
     }
   }
 
-  const timer = setInterval(saveAdvanced, saveIntervalMs);
+  const timer = clock.setInterval(saveAdvanced, saveIntervalMs);
 
   return {
     storeFor(sessionId) {
@@ -360,21 +291,10 @@ export function createScrollbackKeeper(
       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.
+      // NOT an unconditional write: only a shown session's store advances, and a
+      // page writing another session's load-time content over a second page's
+      // newer entry (with a fresh timestamp) rolled that entry back. The cost is
+      // one full replay for a long-idle session after the age bound expires.
       for (const [sessionId, store] of tracked) {
         saveIfAdvanced(sessionId, store);
       }
@@ -390,7 +310,7 @@ export function createScrollbackKeeper(
     },
     stop() {
       stopped = true;
-      clearInterval(timer);
+      clock.clearInterval(timer);
       tracked.clear();
       savedThrough.clear();
     },

package/src/kernel/selection.ts

@@ -0,0 +1,25 @@
+/**
+ * The document selection's text when EVERY range has both ends inside
+ * `container`, else "". A range dragged out into the host page, a Firefox
+ * Ctrl+drag multi-range selection with one range outside, and a bare caret
+ * (no text) all answer "". Range ends are in document order whichever way the
+ * user dragged. Known limitation: a container inside a host's shadow root never
+ * matches, because getSelection() does not reach into shadow trees.
+ */
+export function selectionTextWithin(container: Element): string {
+  const sel = container.ownerDocument.defaultView?.getSelection() ?? null;
+  if (sel === null) {
+    return "";
+  }
+  const text = sel.toString();
+  if (text.length === 0) {
+    return "";
+  }
+  for (let i = 0; i < sel.rangeCount; i++) {
+    const range = sel.getRangeAt(i);
+    if (!container.contains(range.startContainer) || !container.contains(range.endContainer)) {
+      return "";
+    }
+  }
+  return text;
+}