@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/shared/lib/ui/toolbar-overflow.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which toolbar clusters fit on ONE row, and which go into the `⋯` menu.
+ *
+ * The editor and diff toolbars carry ten-plus controls and the editor panel is
+ * 320px wide on a 1440px screen. WRAPPING was the previous answer and it is the
+ * wrong one: a second row moves the document down by the toolbar's own height
+ * and reads as a second toolbar. A horizontal scroll is worse still — a clipped
+ * control is invisible and reads as "there is nothing more here".
+ *
+ * So: the clusters that do not fit move into a `⋯` menu, and a cluster can be
+ * PINNED to stay on the row at every width. Pinning is what keeps this from
+ * being a priority guess — the toolbar's visual order is not its priority order
+ * (Save is drawn first because that is where a reader looks for it, while the
+ * width modes sit last and are the reason the panel exists).
+ *
+ * Pure, and measured widths in: the caller lays the clusters out once and hands
+ * their rendered widths here. A table of guessed pixel widths drifts the moment
+ * a label, an icon or a font changes.
+ */
+
+/** Width the `⋯` trigger needs, including the gap before it. */
+export const TOOLBAR_OVERFLOW_TRIGGER_PX = 30;
+
+/** Gap between two clusters (`gap-x-1`). */
+export const TOOLBAR_ITEM_GAP_PX = 4;
+
+export interface ToolbarOverflowArgs {
+  /** Rendered width of each cluster, in row order. */
+  widths: number[];
+  /** Which clusters never leave the row. Same length as `widths`. */
+  pinned: boolean[];
+  /** Width the row actually has, or 0 before it is measured. */
+  available: number;
+}
+
+/**
+ * Which clusters to render on the row, in row order.
+ *
+ * An unmeasured row (available 0) keeps everything: hiding controls before the
+ * width is known flashes a menu on every mount, and the row is measured a
+ * layout effect later.
+ */
+export function toolbarVisibleClusters({ widths, pinned, available }: ToolbarOverflowArgs): boolean[] {
+  if (!(available > 0) || widths.length === 0) return widths.map(() => true);
+
+  const total = widths.reduce((sum, width) => sum + width, 0) + TOOLBAR_ITEM_GAP_PX * (widths.length - 1);
+  if (total <= available) return widths.map(() => true);
+
+  // Pinned clusters are placed FIRST and in full, because whether the row is
+  // wide enough for them is not a question — they stay and the row clips if it
+  // must. The unpinned ones then take whatever is left, in row order, once the
+  // `⋯` trigger's own width is set aside. Filling in one pass over row order
+  // instead would let an early unpinned control consume the space a pinned one
+  // later needs.
+  const shown = widths.map(() => false);
+  let used = 0;
+  let rendered = 0;
+  widths.forEach((width, index) => {
+    if (!pinned[index]) return;
+    used += width + (rendered > 0 ? TOOLBAR_ITEM_GAP_PX : 0);
+    rendered += 1;
+    shown[index] = true;
+  });
+
+  let budget = available - used - TOOLBAR_OVERFLOW_TRIGGER_PX - TOOLBAR_ITEM_GAP_PX;
+  widths.forEach((width, index) => {
+    if (pinned[index]) return;
+    const cost = width + (rendered > 0 ? TOOLBAR_ITEM_GAP_PX : 0);
+    if (cost > budget) return;
+    budget -= cost;
+    rendered += 1;
+    shown[index] = true;
+  });
+
+  return shown;
+}
+
+/** True when at least one cluster is going into the menu. */
+export function toolbarHasOverflow(visible: boolean[]): boolean {
+  return visible.some((shown) => !shown);
+}

package/src/shared/lib/updates/shell-arch.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The architecture a DESKTOP shell runs as, and the artifact it installs itself
+ * from.
+ *
+ * ## Why this exists at all
+ *
+ * Every desktop artifact is per-architecture (`Kabmo-0.2.0-mac-arm64.zip`,
+ * `Kabmo-0.2.0-win-x64-setup.exe`), and the console used to answer a desktop
+ * probe with the RELEASE PAGE precisely because it could not know which
+ * architecture the window asking was running on. That is correct for a link and
+ * useless for a self-update: handing an arm64 reader an x64 installer produces
+ * an app that does not launch, and on Windows an installer that refuses with
+ * "this installation package could not be opened".
+ *
+ * So a desktop shell reports its own architecture over the bridge, and the
+ * server names the ONE artifact. This module is the vocabulary both ends share,
+ * which is what stops the shell, the route and the asset table from spelling
+ * `x86_64`, `x64` and `amd64` for the same machine.
+ *
+ * ## Two spellings, one canonical token
+ *
+ * A shell reports the CANONICAL token (`arm64` / `x64`) because that is what the
+ * client and the route pass around. Each platform's release assets spell its
+ * architecture differently — Linux says `x86_64`, macOS and Windows say `x64` —
+ * and that mapping lives in ONE table (`SHELL_ASSETS`), on the server, next to
+ * the names it has to match. A shell that mapped its own spelling to the asset's
+ * would be a second copy of the same fact.
+ */
+
+/** A desktop architecture, in the vocabulary the console and the shells share. */
+export type ShellArch = 'arm64' | 'x64';
+
+/**
+ * Read a canonical arch out of a string, or null.
+ *
+ * Lenient about the spellings a shell might report (a shell that read
+ * `std::env::consts::ARCH` says `x86_64`; one that read
+ * `RuntimeInformation.ProcessArchitecture` says `X64`), because a refused arch
+ * costs the reader the self-update and buys nothing: the value only chooses
+ * between two artifacts of the same product, and the artifact is then verified
+ * by the shell before it is installed.
+ */
+export function parseShellArch(value: string | null | undefined): ShellArch | null {
+  if (!value) return null;
+  const folded = value.trim().toLowerCase();
+  if (folded === 'arm64' || folded === 'aarch64') return 'arm64';
+  if (folded === 'x64' || folded === 'x86_64' || folded === 'amd64') return 'x64';
+  return null;
+}

package/src/shared/lib/updates/shell-ua.ts

@@ -23,10 +23,10 @@ export type MobileShellKind = 'android' | 'ios';
 
 /**
  * The desktop shells. They carry NO User-Agent token — a desktop app is not
- * downloaded from the console, so the server has nothing to parse per request.
- * They report their version over the shell bridge instead (`__kabmoDesktop`),
- * which is why they are a separate family: the version exists, the UA channel
- * does not.
+ * downloaded from a page, so the server has nothing to parse per request. They
+ * report their version and their ARCHITECTURE over the shell bridge instead
+ * (`__kabmoDesktop`), which is why they are a separate family: both facts exist,
+ * the UA channel does not.
  */
 export type DesktopShellKind = 'macos' | 'windows' | 'linux';
 

package/src/shared/lib/workspace/editor-view-mode.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The three width modes' table, asserted as data.
+ *
+ * Each case is a rule the layout depends on and that no component test would
+ * catch: `compact` must NOT hide the sidebar (that is `full`'s job, and the
+ * two buttons would be the same button if it did), the right panel is hidden
+ * by neither, and clicking an active mode returns to `normal` rather than
+ * doing nothing.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEFAULT_EDITOR_VIEW_MODE,
+  isEditorViewMode,
+  editorViewHides,
+  toggledEditorViewMode,
+} from '@/shared/lib/workspace/editor-view-mode';
+
+describe('editorViewHides', () => {
+  test('compact hides the chat only', () => {
+    expect(editorViewHides('compact', 'chat')).toBe(true);
+    expect(editorViewHides('compact', 'sidebar')).toBe(false);
+  });
+
+  test('full hides the chat AND the sidebar', () => {
+    expect(editorViewHides('full', 'chat')).toBe(true);
+    expect(editorViewHides('full', 'sidebar')).toBe(true);
+  });
+
+  test('normal hides nothing', () => {
+    expect(editorViewHides('normal', 'chat')).toBe(false);
+    expect(editorViewHides('normal', 'sidebar')).toBe(false);
+  });
+});
+
+describe('toggledEditorViewMode', () => {
+  test('a mode button enters its mode', () => {
+    expect(toggledEditorViewMode('normal', 'compact')).toBe('compact');
+    expect(toggledEditorViewMode('normal', 'full')).toBe('full');
+  });
+
+  test('the OTHER mode switches rather than toggling off', () => {
+    expect(toggledEditorViewMode('compact', 'full')).toBe('full');
+    expect(toggledEditorViewMode('full', 'compact')).toBe('compact');
+  });
+
+  test('clicking the active mode returns to normal', () => {
+    expect(toggledEditorViewMode('compact', 'compact')).toBe('normal');
+    expect(toggledEditorViewMode('full', 'full')).toBe('normal');
+  });
+});
+
+describe('isEditorViewMode', () => {
+  test('accepts the three modes and nothing else', () => {
+    expect(['normal', 'compact', 'full'].every(isEditorViewMode)).toBe(true);
+    expect(isEditorViewMode('fullscreen')).toBe(false);
+    expect(isEditorViewMode(undefined)).toBe(false);
+    expect(isEditorViewMode(null)).toBe(false);
+  });
+
+  test('the fallback is the ordinary layout', () => {
+    expect(DEFAULT_EDITOR_VIEW_MODE).toBe('normal');
+  });
+});

package/src/shared/lib/workspace/editor-view-mode.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * How wide the editor column is allowed to be, as ONE of three modes.
+ *
+ * `compact` and `full` both hide the chat timeline and let the editor take the
+ * width the chat had; `full` also hides the session sidebar. Neither touches
+ * the right panel: the point of the two modes is a wider DOCUMENT, and the
+ * right column is where the outline, search hits and the diff list live while
+ * it is being read. The third width — the existing `fixed inset-0` full
+ * SCREEN — is a different thing entirely (it covers the right panel too) and
+ * stays where it is, on its own button.
+ *
+ * The rules are pure so the layout, both toolbars and the tests read the same
+ * table: which columns a mode hides is data, never a condition at a call site.
+ */
+
+export type EditorViewMode = 'normal' | 'compact' | 'full';
+
+/** The two modes a toolbar button can name. */
+export type EditorViewModeTarget = 'compact' | 'full';
+
+/** Session-state slot. Per session, like every other layout choice. */
+export const EDITOR_VIEW_MODE_KEY = 'layout.editorViewMode';
+
+export const DEFAULT_EDITOR_VIEW_MODE: EditorViewMode = 'normal';
+
+/** A stored value written by another build is not a mode this one can draw. */
+export function isEditorViewMode(value: unknown): value is EditorViewMode {
+  return value === 'normal' || value === 'compact' || value === 'full';
+}
+
+/**
+ * What a mode HIDES. `full` hides everything `compact` does plus the sidebar,
+ * so it is strictly wider — the two are ordered, not alternatives.
+ */
+export function editorViewHides(mode: EditorViewMode, column: 'chat' | 'sidebar'): boolean {
+  if (column === 'chat') return mode === 'compact' || mode === 'full';
+  return mode === 'full';
+}
+
+/** Clicking the mode a button already names returns to `normal`. */
+export function toggledEditorViewMode(current: EditorViewMode, next: EditorViewModeTarget): EditorViewMode {
+  return current === next ? 'normal' : next;
+}

package/src/shared/lib/workspace/panel-widths.test.ts

@@ -124,6 +124,27 @@ describe('resolvePanelWidth', () => {
     // panel keeps its minimum and the row clips, rather than collapsing.
     expect(resolvePanelWidth({ ...base, available: 400, siblingWidth: 320, handleCount: 2 })).toBe(320);
   });
+
+  test('a collapsed chat removes the floor AND the pair caps', () => {
+    const available = 2000;
+    // The ordinary layout would cap this at 0.6 × 2000 = 1200 (own cap) and at
+    // 0.7 × 2000 − 320 = 1080 (pair cap, a sibling reserving its floor), and the
+    // chat's 400 floor would bind at 1280. With no chat on screen there is no
+    // conversation to leave room for, so only the group's own width limits it.
+    const wanted = { fraction: 0.9 };
+    expect(resolvePanelWidth({ ...base, available, siblingWidth: 320, handleCount: 1, stored: wanted })).toBe(
+      Math.round(PAIR_MAX_FRACTION * available),
+    );
+    expect(resolvePanelWidth({ ...base, available, siblingWidth: 320, handleCount: 1, stored: wanted, chatHidden: true })).toBe(
+      available - 320 - 1 * 3,
+    );
+  });
+
+  test('the floor still wins with the chat collapsed', () => {
+    // A group narrower than the sibling and this panel's floor: the panel keeps
+    // its minimum rather than collapsing into nothing.
+    expect(resolvePanelWidth({ ...base, available: 400, siblingWidth: 320, handleCount: 1, chatHidden: true })).toBe(320);
+  });
 });
 
 describe('the editor/right-panel pair', () => {
@@ -273,4 +294,13 @@ describe('pairMaxSize (the drag cap)', () => {
   test('no measured area means no cap', () => {
     expect(pairMaxSize({ available: null, siblingMin: editorMin, siblingOpen: true })).toBeUndefined();
   });
+
+  test('a collapsed chat lets a drag reach the whole row', () => {
+    // Two panels and nothing else: the editor may be dragged up to the group's
+    // width minus the right panel's floor. The 0.6 own-cap would have frozen the
+    // separator at 2400 of 4000 with 1600px of empty row behind it.
+    expect(pairMaxSize({ available, siblingMin: rightMin, siblingOpen: true, chatHidden: true })).toBe(available - rightMin);
+    // The sibling closed means nothing to reserve at all.
+    expect(pairMaxSize({ available, siblingMin: 0, siblingOpen: false, chatHidden: true })).toBe(available);
+  });
 });

package/src/shared/lib/workspace/panel-widths.ts

@@ -149,6 +149,13 @@ export interface ResolveWidthArgs {
   siblingWidth: number;
   /** Separators in the group, which also consume width. */
   handleCount: number;
+  /**
+   * The CHAT column is collapsed (`compact`/`full` editor views), so it holds no
+   * floor and the pair caps do not apply — both exist to leave the conversation
+   * a share of the group, and neither has anything to reserve once it is off
+   * screen. Keeping them would cap a two-panel layout at 70% of its width.
+   */
+  chatHidden?: boolean;
 }
 
 /**
@@ -172,7 +179,7 @@ export interface ResolveWidthArgs {
  * default pixel width is used unchanged.
  */
 export function resolvePanelWidth(args: ResolveWidthArgs): number {
-  const { stored, defaultFraction, defaultPx, available, min, pairReservePx = 0, siblingWidth, handleCount } = args;
+  const { stored, defaultFraction, defaultPx, available, min, pairReservePx = 0, siblingWidth, handleCount, chatHidden = false } = args;
 
   if (available === null || available <= 0) return Math.max(min, Math.round(stored?.px ?? defaultPx));
 
@@ -182,14 +189,20 @@ export function resolvePanelWidth(args: ResolveWidthArgs): number {
   // `total × available − the sibling's reserved px` — and ROUNDED, because
   // `0.7 × 4000` is `2799.9999…` in binary floating point and flooring it lands
   // a pixel short of the intended share.
-  const ownCap = Math.round(PAIR_MAX_FRACTION * available);
-  const pairCap = Math.round(PAIR_MAX_TOTAL_FRACTION * available) - pairReservePx;
+  //
+  // With the chat COLLAPSED neither cap means anything: the pair's 70% share
+  // and the chat floor are both about leaving the conversation room, and there
+  // is no conversation on screen. Only the group's own width remains a limit,
+  // which is what lets the editor take the width the chat had.
+  const ownCap = chatHidden ? Number.MAX_SAFE_INTEGER : Math.round(PAIR_MAX_FRACTION * available);
+  const pairCap = chatHidden ? Number.MAX_SAFE_INTEGER : Math.round(PAIR_MAX_TOTAL_FRACTION * available) - pairReservePx;
+  const chatFloor = chatHidden ? 0 : MIN_CHAT_PANEL_WIDTH;
   const ceiling = Math.max(
     min,
     Math.min(
       ownCap,
       pairCap,
-      Math.floor(available - MIN_CHAT_PANEL_WIDTH - siblingWidth - handleCount * HANDLE_WIDTH),
+      Math.floor(available - chatFloor - siblingWidth - handleCount * HANDLE_WIDTH),
     ),
   );
 
@@ -263,9 +276,16 @@ export function pairMaxSize(args: {
   siblingMin: number;
   /** The sibling is open and therefore reserves its floor from the pair total. */
   siblingOpen: boolean;
+  /** The chat column is collapsed, so the pair's shared share is the whole group. */
+  chatHidden?: boolean;
 }): number | undefined {
-  const { available, siblingMin, siblingOpen } = args;
+  const { available, siblingMin, siblingOpen, chatHidden = false } = args;
   if (available === null || available <= 0) return undefined;
+  // No chat on screen means nothing to reserve a share FOR: the pair is the
+  // whole row, so each side may be dragged up to the group's width minus the
+  // sibling's floor. The 60% own-cap would freeze a separator halfway across a
+  // layout whose only two panels are the ones being dragged.
+  if (chatHidden) return Math.max(0, Math.floor(available - (siblingOpen ? siblingMin : 0)));
   const ownCap = Math.round(PAIR_MAX_FRACTION * available);
   if (!siblingOpen) return ownCap;
   const pairCap = Math.round(PAIR_MAX_TOTAL_FRACTION * available) - siblingMin;

package/src/shared/lib/workspace/session-state/cache.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The session-state cache: which entries are held, and for how long.
+ *
+ * Split out of `store.ts` for the file-size ceiling, and it is the natural seam
+ * rather than an arbitrary cut. `store.ts` owns the PUBLIC API (read, write,
+ * load, migrate) and the decisions about what a write means; this owns the
+ * STORAGE — the maps, the LRU order, the idle TTL, and the dirty flag that says
+ * an entry holds writes no persist has carried yet.
+ *
+ * The maps live here and nowhere else, so "is this session dirty" and "drop this
+ * session" cannot be answered from two places that disagree.
+ */
+
+type SessionState = Record<string, unknown>;
+
+const entries = new Map<string, SessionState>();
+/** Epoch ms of the last user-driven access per session (get/set/hydrate). */
+const lastTouched = new Map<string, number>();
+/** A session with writes no persist has carried yet. */
+const dirty = new Map<string, boolean>();
+const persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+// Bounded LRU cache: cap the number of sessions kept in memory so the tab
+// doesn't grow unboundedly as the user visits more sessions.
+const MAX_CACHED_SESSIONS = 10;
+/** A session whose last user access is older than this is evicted regardless
+ *  of the size cap, so stale per-session UI state (drafts, panel layouts)
+ *  stops occupying memory 10 minutes after the user last opened it. */
+const SESSION_IDLE_TTL_MS = 10 * 60 * 1000;
+
+/** The cached entry, as read-only — write through the store's own setters. */
+export function readEntry(sessionId: string): Readonly<SessionState> | undefined {
+  return entries.get(sessionId);
+}
+
+/**
+ * Reorder a cache entry to the end of the Map's iteration order (the
+ * most-recently-used position) via delete-then-set. Map.set on an existing
+ * key updates the value but keeps its original position, so the explicit
+ * delete is required for true LRU semantics.
+ */
+export function touchEntry(sessionId: string): void {
+  const value = entries.get(sessionId);
+  if (value !== undefined) {
+    entries.delete(sessionId);
+    entries.set(sessionId, value);
+  }
+  lastTouched.set(sessionId, Date.now());
+}
+
+/** Stamp the entry as most-recently-used without reordering it. */
+export function stampAccess(sessionId: string): void {
+  lastTouched.set(sessionId, Date.now());
+}
+
+export function lastAccess(sessionId: string): number | undefined {
+  return lastTouched.get(sessionId);
+}
+
+/** Replace an entry outright (a blob arriving, a migrate, a hydrate). */
+export function writeEntry(sessionId: string, state: SessionState): void {
+  entries.set(sessionId, state);
+}
+
+/**
+ * The MUTABLE entry for a write, created on demand.
+ *
+ * `setSessionKey` and `clearSessionKey` mutate the cached object in place, as
+ * they always have: a copy per write would give every reader a different object
+ * for the same slot, and `useSessionState` compares the store's entry against
+ * its own copy by IDENTITY to decide whether a fresher write exists.
+ */
+export function entryForWrite(sessionId: string): SessionState {
+  const existing = entries.get(sessionId);
+  if (existing) return existing;
+  const created: SessionState = {};
+  entries.set(sessionId, created);
+  return created;
+}
+
+/** Mark a session as holding writes no persist has carried yet. */
+export function markDirty(sessionId: string): void {
+  dirty.set(sessionId, true);
+}
+
+export function clearDirty(sessionId: string): void {
+  dirty.set(sessionId, false);
+}
+
+export function isDirty(sessionId: string): boolean {
+  return dirty.get(sessionId) === true;
+}
+
+export function setPersistTimer(sessionId: string, timer: ReturnType<typeof setTimeout>): void {
+  persistTimers.set(sessionId, timer);
+}
+
+export function persistTimer(sessionId: string): ReturnType<typeof setTimeout> | undefined {
+  return persistTimers.get(sessionId);
+}
+
+export function dropPersistTimer(sessionId: string): void {
+  const timer = persistTimers.get(sessionId);
+  if (timer) {
+    clearTimeout(timer);
+    persistTimers.delete(sessionId);
+  }
+}
+
+/** Remove an entry and everything recorded about it. */
+export function dropEntry(sessionId: string): void {
+  entries.delete(sessionId);
+  dirty.delete(sessionId);
+  lastTouched.delete(sessionId);
+  dropPersistTimer(sessionId);
+}
+
+/**
+ * Evict the oldest clean sessions until the cache is within bounds.
+ *
+ * Dirty-safety rule: a session with unsaved writes (`isDirty`) must never be
+ * evicted, or the user's drafts and editor state would be silently lost. If
+ * every candidate is dirty (or is the protected id currently being written),
+ * stop evicting rather than lose data.
+ *
+ * Entries idle past SESSION_IDLE_TTL_MS are evicted first — even when the
+ * cache is under the size cap — so long-unused sessions drop out on schedule.
+ */
+export function evictIfNeeded(protectedId: string | null, onEvict: (sessionId: string) => void): void {
+  const now = Date.now();
+  const evict = (id: string): void => {
+    dropEntry(id);
+    onEvict(id);
+  };
+  // TTL pass: safe to skip only while the timer still holds the unsaved state
+  // or the session is the one currently being written.
+  for (const [id, touched] of lastTouched) {
+    if (now - touched <= SESSION_IDLE_TTL_MS) continue;
+    if (id === protectedId) continue;
+    if (isDirty(id)) continue;
+    evict(id);
+  }
+  while (entries.size > MAX_CACHED_SESSIONS) {
+    let evicted = false;
+    for (const id of entries.keys()) {
+      if (id === protectedId) continue;
+      if (isDirty(id)) continue;
+      evict(id);
+      evicted = true;
+      break;
+    }
+    if (!evicted) break;
+  }
+}

package/src/shared/lib/workspace/session-state/harness.test-util.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared harness for the session-state store's suites.
+ *
+ * Split out when `store.test.ts` passed the per-file ceiling. Every case in
+ * every suite needs the same three things — an id that teardown forgets, a
+ * subscription that teardown cancels, and a counter — and a per-file copy is how
+ * two suites end up disagreeing about what teardown restores.
+ */
+
+import { afterEach, setSystemTime } from 'bun:test';
+
+import { subscribeSessionKey } from '@/shared/lib/workspace/session-state/listeners';
+import { forgetSession } from '@/shared/lib/workspace/session-state/store';
+
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+export const originalFetch = Bun.fetch;
+export const originalWindow = Reflect.get(globalThis, 'window');
+
+const touched: string[] = [];
+const unsubs: Array<() => void> = [];
+
+/** Register a session id so teardown forgets it. */
+export function use(id: string): string {
+  touched.push(id);
+  return id;
+}
+
+/** Subscribe and auto-unsubscribe at teardown. */
+export function follow(sessionId: string | null, key: string | null, listener: () => void): () => void {
+  const unsubscribe = subscribeSessionKey(sessionId, key, listener);
+  unsubs.push(unsubscribe);
+  return unsubscribe;
+}
+
+/** Count how many times a notification reaches a listener. */
+export function counter(): { calls: number; listener: () => void } {
+  const state = { calls: 0, listener: () => { state.calls += 1; } };
+  return state;
+}
+
+/** Install the suite's teardown. Called once per test file. */
+export function installStoreTeardown(): void {
+  afterEach(() => {
+    for (const unsubscribe of unsubs.splice(0)) unsubscribe();
+    for (const id of touched.splice(0)) forgetSession(id);
+    Reflect.set(globalThis, 'window', originalWindow);
+    Reflect.set(globalThis, 'fetch', originalFetch);
+    setSystemTime();
+  });
+}