@use-everywhere/test-utils 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonatan Kruszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @use-everywhere/test-utils
+
+Test seams for [use-everywhere](https://github.com/rxova/use-everywhere): run
+several simulated tabs in one process, with no browser and no globals.
+
+```sh
+pnpm add -D @use-everywhere/test-utils
+```
+
+```ts
+import { createScenario } from '@use-everywhere/test-utils';
+
+it('two tabs converge', async () => {
+  const browser = createScenario();
+  const cartA = browser.tab().store('cart', { items: 0 });
+  const cartB = browser.tab().store('cart', { items: 0 });
+
+  cartA.set('items', 3);
+  await browser.settle();
+
+  expect(cartB.getSnapshot().items).toBe(3);
+  browser.dispose();
+});
+```
+
+## Close is not crash
+
+The reason multi-tab code is hard is that a tab can leave in two ways, and only
+one of them says goodbye. Both are one call here:
+
+```ts
+const browser = createScenario();
+const a = browser.tab();
+const b = browser.tab();
+const first = a.leader('app');
+const second = b.leader('app');
+
+a.crash(); // the wire is cut mid-sentence: no goodbye, no resignation
+await browser.settle();
+
+expect(second.getSnapshot().isLeader).toBe(true); // the platform reclaimed the seat
+```
+
+`close()` closes the primitives and then the wire, so peers are _told_.
+`crash()` closes the wire first and reclaims the tab's Web Locks, so peers have
+to _notice_ — which is the path that finds the bugs.
+
+## What's in the box
+
+| Export                         | What it is                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| `createScenario(options?)`     | One simulated browser: a shared hub, shared Web Locks, and tabs                  |
+| `FakeLockManager`              | `navigator.locks` with FIFO queueing and reclamation on crash                    |
+| `FakeWindow`, `fakeWindowPair` | Enough `Window` for `openWindow` / `connectToOpener`, including hostile messages |
+| `tick`, `snapshotWindow`       | The two waits that matter: delivery, and the late-joiner snapshot window         |
+| `MemoryHub`, `MemoryTransport` | Re-exported from `@use-everywhere/core/testing` — same classes, one import       |
+
+`createScenario({ election: 'heartbeat' })` runs the election that plain-http
+origins get, where Web Locks does not exist. Test both if you ship to one.
+
+## One primitive per name per tab
+
+A `Tab` is a lifecycle group. Each primitive created through it gets its own
+connection to the hub — the same shape a real tab has when it uses several bus
+names — so a presence and a store created on _one_ name in one tab announce
+themselves as two clients. Keep one primitive per name per tab and the
+simulation matches a browser exactly.
+
+## Docs
+
+[Testing guide](https://rxova.org/packages/use-everywhere/guides/testing/)
+
+## License
+
+MIT © [Jonatan Kruszewski](https://github.com/rxova)

package/dist/index.cjs

@@ -0,0 +1,306 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  FakeLockManager: () => FakeLockManager,
+  FakeWindow: () => FakeWindow,
+  MemoryHub: () => import_testing2.MemoryHub,
+  MemoryTransport: () => import_testing2.MemoryTransport,
+  createScenario: () => createScenario,
+  fakeWindowPair: () => fakeWindowPair,
+  snapshotWindow: () => snapshotWindow,
+  tick: () => tick
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/scenario.ts
+var import_core = require("@use-everywhere/core");
+var import_testing = require("@use-everywhere/core/testing");
+
+// src/fake-locks.ts
+var abortError = () => new DOMException("The operation was aborted.", "AbortError");
+var FakeLockManager = class {
+  constructor() {
+    this.holds = /* @__PURE__ */ new Map();
+    this.queues = /* @__PURE__ */ new Map();
+    this.nextHoldId = 1;
+  }
+  request(name, options, callback) {
+    return this.requestAs(void 0, name, options, callback);
+  }
+  /**
+   * A view of this manager tagged with an owner, so `reclaim(owner)` can take
+   * the lock back the way a browser does when the tab holding it disappears.
+   */
+  forOwner(owner) {
+    return {
+      request: (name, options, callback) => this.requestAs(owner, name, options, callback)
+    };
+  }
+  /**
+   * The tab named `owner` is gone: free every lock it holds and forget every
+   * lock it was waiting on.
+   *
+   * Its callbacks are never settled — that is the point. A crashed tab's code
+   * does not get to run again, and a test that asserts the *next* tab took the
+   * seat is asserting exactly what the browser guarantees.
+   */
+  reclaim(owner) {
+    for (const [name, hold] of [...this.holds]) {
+      if (hold.owner !== owner) continue;
+      this.holds.delete(name);
+      this.queues.get(name)?.shift()?.grant();
+    }
+    for (const queue of this.queues.values()) {
+      for (let at = queue.length - 1; at >= 0; at -= 1) {
+        if (queue[at].owner === owner) queue.splice(at, 1);
+      }
+    }
+  }
+  /** Is this lock held by anyone? */
+  isHeld(name) {
+    return this.holds.has(name);
+  }
+  /** Which owner holds it, if the request was tagged with one. */
+  holder(name) {
+    return this.holds.get(name)?.owner;
+  }
+  /** How many callers are waiting behind the holder. */
+  queued(name) {
+    return this.queues.get(name)?.length ?? 0;
+  }
+  requestAs(owner, name, options, callback) {
+    return new Promise((resolve, reject) => {
+      const grant = () => {
+        const hold = { owner, id: this.nextHoldId++ };
+        this.holds.set(name, hold);
+        void callback().catch(() => {
+        }).then(() => {
+          if (this.holds.get(name)?.id !== hold.id) {
+            resolve();
+            return;
+          }
+          this.holds.delete(name);
+          const next = this.queues.get(name)?.shift();
+          resolve();
+          next?.grant();
+        });
+      };
+      if (options.signal?.aborted) {
+        reject(abortError());
+        return;
+      }
+      if (!this.holds.has(name)) {
+        grant();
+        return;
+      }
+      const waiter = { owner, grant };
+      const queue = this.queues.get(name) ?? [];
+      queue.push(waiter);
+      this.queues.set(name, queue);
+      options.signal?.addEventListener("abort", () => {
+        const at = queue.indexOf(waiter);
+        if (at >= 0) {
+          queue.splice(at, 1);
+          reject(abortError());
+        }
+      });
+    });
+  }
+};
+
+// src/timing.ts
+var tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+var snapshotWindow = (ms = 80) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/scenario.ts
+var SimulatedTab = class {
+  constructor(id, hub, locks, election, kind) {
+    this.id = id;
+    this.hub = hub;
+    this.locks = locks;
+    this.election = election;
+    this.kind = kind;
+    this.wires = [];
+    this.created = [];
+    this.state = "open";
+  }
+  get gone() {
+    return this.state !== "open";
+  }
+  store(name, initial, options = {}) {
+    return this.track((0, import_core.createSharedStore)(name, initial, { ...this.common(), ...options }));
+  }
+  reducer(name, reducer, initial, options = {}) {
+    return this.track(
+      (0, import_core.createSharedReducer)(name, reducer, initial, { ...this.common(), ...options })
+    );
+  }
+  channel(name, options = {}) {
+    return this.track((0, import_core.createChannel)(name, { ...this.common(), ...options }));
+  }
+  presence(name, options = {}) {
+    return this.track((0, import_core.createPresence)(name, { ...this.common(), ...options }));
+  }
+  leader(name, options = {}) {
+    const election = this.election === "web-locks" ? { strategy: "web-locks", locks: this.locks.forOwner(this.id) } : { strategy: "heartbeat" };
+    return this.track((0, import_core.createLeader)(name, { ...this.common(), ...election, ...options }));
+  }
+  /**
+   * The difference between closing and crashing is the *order* these two lines
+   * run in, which is exactly the difference in a browser: a tab that closes
+   * gets its goodbye out before the wire goes, and a tab that crashes does not.
+   */
+  close() {
+    if (this.gone) return;
+    this.state = "closed";
+    for (const closeable of this.created) closeable.close();
+    for (const wire of this.wires) wire.close();
+  }
+  crash() {
+    if (this.gone) return;
+    this.state = "crashed";
+    for (const wire of this.wires) wire.close();
+    this.locks.reclaim(this.id);
+  }
+  /** Options every primitive in this tab shares: its own wire, its own kind. */
+  common() {
+    return {
+      transport: () => {
+        const wire = this.hub.connect();
+        this.wires.push(wire);
+        return wire;
+      },
+      // Spread-friendly: exactOptionalPropertyTypes rejects an explicit undefined.
+      ...this.kind ? { kind: this.kind } : {}
+    };
+  }
+  track(primitive) {
+    this.created.push(primitive);
+    return primitive;
+  }
+};
+function createScenario(options = {}) {
+  const hub = new import_testing.MemoryHub();
+  const locks = new FakeLockManager();
+  const election = options.election ?? "web-locks";
+  const tabs = [];
+  return {
+    hub,
+    locks,
+    tabs,
+    tab(tabOptions = {}) {
+      const tab = new SimulatedTab(
+        tabOptions.id ?? `tab-${tabs.length + 1}`,
+        hub,
+        locks,
+        election,
+        tabOptions.kind
+      );
+      tabs.push(tab);
+      return tab;
+    },
+    settle(ms) {
+      return ms === void 0 ? tick() : new Promise((resolve) => setTimeout(resolve, ms));
+    },
+    dispose() {
+      for (const tab of tabs) tab.close();
+    }
+  };
+}
+
+// src/fake-window.ts
+var FakeWindow = class {
+  constructor(origin) {
+    this.closed = false;
+    this.peer = null;
+    /** Messages wait here until `flush()` — a child that has not loaded yet. */
+    this.pending = [];
+    this.autoFlush = true;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.origin = origin;
+  }
+  addEventListener(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+  removeEventListener(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  /** Called by the peer: deliver a message event to this window's listeners. */
+  postMessage(data, targetOrigin) {
+    if (targetOrigin !== "*" && targetOrigin !== this.origin) return;
+    const from = this.peer;
+    const deliver = () => {
+      if (this.closed) return;
+      for (const fn of this.listeners.get("message") ?? []) {
+        fn({ data, origin: from?.origin ?? this.origin, source: from });
+      }
+    };
+    if (this.autoFlush) queueMicrotask(deliver);
+    else this.pending.push(deliver);
+  }
+  /**
+   * Deliver a message that did not come from the peer — an attacker page, or an
+   * unrelated widget on the same origin. The handshake must ignore it.
+   */
+  injectMessage(data, origin, source = {}) {
+    for (const fn of this.listeners.get("message") ?? []) {
+      fn({ data, origin, source });
+    }
+  }
+  /** Deliver everything held back while `autoFlush` was off. */
+  flush() {
+    for (const deliver of this.pending.splice(0)) deliver();
+  }
+  /** Close this window, firing `pagehide` the way a real one does. */
+  close() {
+    this.closed = true;
+    for (const fn of this.listeners.get("pagehide") ?? []) {
+      fn({ data: void 0, origin: this.origin, source: this });
+    }
+  }
+};
+function fakeWindowPair(openerOrigin, childOrigin) {
+  const opener = new FakeWindow(openerOrigin);
+  const child = new FakeWindow(childOrigin);
+  opener.peer = child;
+  child.peer = opener;
+  return { opener, child };
+}
+
+// src/index.ts
+var import_testing2 = require("@use-everywhere/core/testing");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FakeLockManager,
+  FakeWindow,
+  MemoryHub,
+  MemoryTransport,
+  createScenario,
+  fakeWindowPair,
+  snapshotWindow,
+  tick
+});

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+import { LockManagerLike, SharedStoreOptions, SharedStore, SharedReducerOptions, SharedReducer, MessageMap, ChannelOptions, Channel, PresenceOptions, Presence, LeaderOptions, Leader, PeerKind, WindowEventTarget, WindowLike } from '@use-everywhere/core';
+import { MemoryHub } from '@use-everywhere/core/testing';
+export { MemoryHub, MemoryTransport } from '@use-everywhere/core/testing';
+
+/**
+ * A stand-in for `navigator.locks` with the three behaviours leadership rests
+ * on: exactly one holder per name, a FIFO queue that hands the lock on the
+ * instant the holder lets go, and — the one a fake usually misses — reclamation
+ * when the holder dies without releasing.
+ *
+ * One instance stands for "the browser", so every simulated tab queues against
+ * the others exactly as real ones would.
+ *
+ * ```ts
+ * const locks = new FakeLockManager();
+ * const leader = createLeader('cart', { locks, transport: () => hub.connect() });
+ * ```
+ */
+declare class FakeLockManager {
+    private holds;
+    private queues;
+    private nextHoldId;
+    request(name: string, options: {
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
+    /**
+     * A view of this manager tagged with an owner, so `reclaim(owner)` can take
+     * the lock back the way a browser does when the tab holding it disappears.
+     */
+    forOwner(owner: string): LockManagerLike;
+    /**
+     * The tab named `owner` is gone: free every lock it holds and forget every
+     * lock it was waiting on.
+     *
+     * Its callbacks are never settled — that is the point. A crashed tab's code
+     * does not get to run again, and a test that asserts the *next* tab took the
+     * seat is asserting exactly what the browser guarantees.
+     */
+    reclaim(owner: string): void;
+    /** Is this lock held by anyone? */
+    isHeld(name: string): boolean;
+    /** Which owner holds it, if the request was tagged with one. */
+    holder(name: string): string | undefined;
+    /** How many callers are waiting behind the holder. */
+    queued(name: string): number;
+    private requestAs;
+}
+
+interface ScenarioOptions {
+    /**
+     * How leadership is arbitrated in this simulated browser. Default
+     * `'web-locks'`, matching every browser that has the API — and the only
+     * strategy where a crashed tab's seat is reclaimed by the platform rather
+     * than by a lease expiring.
+     *
+     * `'heartbeat'` runs the election that plain-http origins get. Test both if
+     * your app ships to one.
+     */
+    election?: 'web-locks' | 'heartbeat';
+}
+interface TabOptions {
+    /** A label for this tab. Defaults to `tab-1`, `tab-2`, … */
+    id?: string;
+    /** What this client announces itself as. Defaults to `'tab'`. */
+    kind?: PeerKind;
+}
+/**
+ * A simulated tab: a lifecycle group over the primitives created through it.
+ *
+ * Each primitive gets its own connection to the hub — the same shape a real tab
+ * has when it uses several bus names — so a presence and a store created on
+ * *one* name in one tab announce themselves as two clients. One primitive per
+ * name per tab, and the simulation matches a browser exactly.
+ */
+interface Tab {
+    readonly id: string;
+    /** True once this tab has been closed or crashed. */
+    readonly gone: boolean;
+    store<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions<S>): SharedStore<S>;
+    reducer<S, A>(name: string, reducer: (state: S, action: A) => S, initial: S, options?: SharedReducerOptions): SharedReducer<S, A>;
+    channel<M extends MessageMap>(name: string, options?: ChannelOptions<M>): Channel<M>;
+    presence(name: string, options?: PresenceOptions): Presence;
+    leader(name: string, options?: LeaderOptions): Leader;
+    /**
+     * Close this tab the way a user closes one: every primitive says goodbye,
+     * peers drop it from the roster at once, and any lock it held is released.
+     */
+    close(): void;
+    /**
+     * Kill this tab the way a crash does: the wire is cut mid-sentence, no
+     * goodbye is sent, and the locks it held are reclaimed by the platform.
+     *
+     * The difference from `close()` is the whole reason multi-tab code is hard —
+     * peers have to *notice*, rather than being told.
+     */
+    crash(): void;
+}
+interface Scenario {
+    /** The in-memory bus every tab in this scenario is connected to. */
+    readonly hub: MemoryHub;
+    /** The Web Locks stand-in shared by every tab. */
+    readonly locks: FakeLockManager;
+    /** Every tab created, in order, including the ones that are gone. */
+    readonly tabs: readonly Tab[];
+    /** Open another tab. */
+    tab(options?: TabOptions): Tab;
+    /**
+     * Let the wire catch up: drains microtasks, or waits `ms` when the thing you
+     * are waiting for is on a timer (a snapshot window, a lease, a probe).
+     */
+    settle(ms?: number): Promise<void>;
+    /** Close every tab that is still open. Safe to call twice. */
+    dispose(): void;
+}
+
+/**
+ * One simulated browser: a hub every tab shares, a Web Locks stand-in every tab
+ * queues on, and tabs that can be closed *or* crashed.
+ *
+ * ```ts
+ * const browser = createScenario();
+ * const a = browser.tab();
+ * const b = browser.tab();
+ *
+ * const cartA = a.store('cart', { items: 0 });
+ * const cartB = b.store('cart', { items: 0 });
+ *
+ * cartA.set('items', 3);
+ * await browser.settle();
+ * expect(cartB.getSnapshot().items).toBe(3);
+ * ```
+ *
+ * Nothing here touches globals: no `BroadcastChannel`, no `navigator.locks`, no
+ * timers you did not ask for. Several scenarios can run in one file, in
+ * parallel, without seeing each other.
+ */
+declare function createScenario(options?: ScenarioOptions): Scenario;
+
+type Listener = (event: {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}) => void;
+/**
+ * One side of a fake window pair: listens like a `Window`, posts to its peer.
+ *
+ * Enough of the object model for `openWindow` and `connectToOpener` to run in a
+ * plain test process — including the parts the cross-origin handshake exists to
+ * defend: a message from the wrong origin, a message from an unrelated source,
+ * a child that closes mid-flow, and a child that loads too late to hear the
+ * first hello.
+ */
+declare class FakeWindow implements WindowEventTarget, WindowLike {
+    closed: boolean;
+    origin: string;
+    peer: FakeWindow | null;
+    /** Messages wait here until `flush()` — a child that has not loaded yet. */
+    pending: Array<() => void>;
+    autoFlush: boolean;
+    private listeners;
+    constructor(origin: string);
+    addEventListener(type: string, listener: Listener): void;
+    removeEventListener(type: string, listener: Listener): void;
+    /** Called by the peer: deliver a message event to this window's listeners. */
+    postMessage(data: unknown, targetOrigin: string): void;
+    /**
+     * Deliver a message that did not come from the peer — an attacker page, or an
+     * unrelated widget on the same origin. The handshake must ignore it.
+     */
+    injectMessage(data: unknown, origin: string, source?: unknown): void;
+    /** Deliver everything held back while `autoFlush` was off. */
+    flush(): void;
+    /** Close this window, firing `pagehide` the way a real one does. */
+    close(): void;
+}
+/** Two fake windows wired to each other: the opener, and the window it opened. */
+declare function fakeWindowPair(openerOrigin: string, childOrigin: string): {
+    opener: FakeWindow;
+    child: FakeWindow;
+};
+
+/**
+ * Drain pending microtasks — and the microtasks they queue.
+ *
+ * Delivery on a `BroadcastChannel`, and on the MemoryHub that stands in for it,
+ * is asynchronous. `await tick()` is the line between "this tab wrote" and
+ * "every other tab has seen it".
+ */
+declare const tick: () => Promise<void>;
+/**
+ * Wait out the late-joiner snapshot window.
+ *
+ * A peer answers a newcomer's `hello` after a jittered pause, and only if
+ * nobody else already did — which is what turns N replies into one. Hydration
+ * is therefore not a microtask away: it costs up to `snapshotDelayMs`, 40 by
+ * default. One `tick()` is not enough, on purpose.
+ */
+declare const snapshotWindow: (ms?: number) => Promise<void>;
+
+export { FakeLockManager, FakeWindow, type Scenario, type ScenarioOptions, type Tab, type TabOptions, createScenario, fakeWindowPair, snapshotWindow, tick };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { LockManagerLike, SharedStoreOptions, SharedStore, SharedReducerOptions, SharedReducer, MessageMap, ChannelOptions, Channel, PresenceOptions, Presence, LeaderOptions, Leader, PeerKind, WindowEventTarget, WindowLike } from '@use-everywhere/core';
+import { MemoryHub } from '@use-everywhere/core/testing';
+export { MemoryHub, MemoryTransport } from '@use-everywhere/core/testing';
+
+/**
+ * A stand-in for `navigator.locks` with the three behaviours leadership rests
+ * on: exactly one holder per name, a FIFO queue that hands the lock on the
+ * instant the holder lets go, and — the one a fake usually misses — reclamation
+ * when the holder dies without releasing.
+ *
+ * One instance stands for "the browser", so every simulated tab queues against
+ * the others exactly as real ones would.
+ *
+ * ```ts
+ * const locks = new FakeLockManager();
+ * const leader = createLeader('cart', { locks, transport: () => hub.connect() });
+ * ```
+ */
+declare class FakeLockManager {
+    private holds;
+    private queues;
+    private nextHoldId;
+    request(name: string, options: {
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
+    /**
+     * A view of this manager tagged with an owner, so `reclaim(owner)` can take
+     * the lock back the way a browser does when the tab holding it disappears.
+     */
+    forOwner(owner: string): LockManagerLike;
+    /**
+     * The tab named `owner` is gone: free every lock it holds and forget every
+     * lock it was waiting on.
+     *
+     * Its callbacks are never settled — that is the point. A crashed tab's code
+     * does not get to run again, and a test that asserts the *next* tab took the
+     * seat is asserting exactly what the browser guarantees.
+     */
+    reclaim(owner: string): void;
+    /** Is this lock held by anyone? */
+    isHeld(name: string): boolean;
+    /** Which owner holds it, if the request was tagged with one. */
+    holder(name: string): string | undefined;
+    /** How many callers are waiting behind the holder. */
+    queued(name: string): number;
+    private requestAs;
+}
+
+interface ScenarioOptions {
+    /**
+     * How leadership is arbitrated in this simulated browser. Default
+     * `'web-locks'`, matching every browser that has the API — and the only
+     * strategy where a crashed tab's seat is reclaimed by the platform rather
+     * than by a lease expiring.
+     *
+     * `'heartbeat'` runs the election that plain-http origins get. Test both if
+     * your app ships to one.
+     */
+    election?: 'web-locks' | 'heartbeat';
+}
+interface TabOptions {
+    /** A label for this tab. Defaults to `tab-1`, `tab-2`, … */
+    id?: string;
+    /** What this client announces itself as. Defaults to `'tab'`. */
+    kind?: PeerKind;
+}
+/**
+ * A simulated tab: a lifecycle group over the primitives created through it.
+ *
+ * Each primitive gets its own connection to the hub — the same shape a real tab
+ * has when it uses several bus names — so a presence and a store created on
+ * *one* name in one tab announce themselves as two clients. One primitive per
+ * name per tab, and the simulation matches a browser exactly.
+ */
+interface Tab {
+    readonly id: string;
+    /** True once this tab has been closed or crashed. */
+    readonly gone: boolean;
+    store<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions<S>): SharedStore<S>;
+    reducer<S, A>(name: string, reducer: (state: S, action: A) => S, initial: S, options?: SharedReducerOptions): SharedReducer<S, A>;
+    channel<M extends MessageMap>(name: string, options?: ChannelOptions<M>): Channel<M>;
+    presence(name: string, options?: PresenceOptions): Presence;
+    leader(name: string, options?: LeaderOptions): Leader;
+    /**
+     * Close this tab the way a user closes one: every primitive says goodbye,
+     * peers drop it from the roster at once, and any lock it held is released.
+     */
+    close(): void;
+    /**
+     * Kill this tab the way a crash does: the wire is cut mid-sentence, no
+     * goodbye is sent, and the locks it held are reclaimed by the platform.
+     *
+     * The difference from `close()` is the whole reason multi-tab code is hard —
+     * peers have to *notice*, rather than being told.
+     */
+    crash(): void;
+}
+interface Scenario {
+    /** The in-memory bus every tab in this scenario is connected to. */
+    readonly hub: MemoryHub;
+    /** The Web Locks stand-in shared by every tab. */
+    readonly locks: FakeLockManager;
+    /** Every tab created, in order, including the ones that are gone. */
+    readonly tabs: readonly Tab[];
+    /** Open another tab. */
+    tab(options?: TabOptions): Tab;
+    /**
+     * Let the wire catch up: drains microtasks, or waits `ms` when the thing you
+     * are waiting for is on a timer (a snapshot window, a lease, a probe).
+     */
+    settle(ms?: number): Promise<void>;
+    /** Close every tab that is still open. Safe to call twice. */
+    dispose(): void;
+}
+
+/**
+ * One simulated browser: a hub every tab shares, a Web Locks stand-in every tab
+ * queues on, and tabs that can be closed *or* crashed.
+ *
+ * ```ts
+ * const browser = createScenario();
+ * const a = browser.tab();
+ * const b = browser.tab();
+ *
+ * const cartA = a.store('cart', { items: 0 });
+ * const cartB = b.store('cart', { items: 0 });
+ *
+ * cartA.set('items', 3);
+ * await browser.settle();
+ * expect(cartB.getSnapshot().items).toBe(3);
+ * ```
+ *
+ * Nothing here touches globals: no `BroadcastChannel`, no `navigator.locks`, no
+ * timers you did not ask for. Several scenarios can run in one file, in
+ * parallel, without seeing each other.
+ */
+declare function createScenario(options?: ScenarioOptions): Scenario;
+
+type Listener = (event: {
+    data: unknown;
+    origin: string;
+    source: unknown;
+}) => void;
+/**
+ * One side of a fake window pair: listens like a `Window`, posts to its peer.
+ *
+ * Enough of the object model for `openWindow` and `connectToOpener` to run in a
+ * plain test process — including the parts the cross-origin handshake exists to
+ * defend: a message from the wrong origin, a message from an unrelated source,
+ * a child that closes mid-flow, and a child that loads too late to hear the
+ * first hello.
+ */
+declare class FakeWindow implements WindowEventTarget, WindowLike {
+    closed: boolean;
+    origin: string;
+    peer: FakeWindow | null;
+    /** Messages wait here until `flush()` — a child that has not loaded yet. */
+    pending: Array<() => void>;
+    autoFlush: boolean;
+    private listeners;
+    constructor(origin: string);
+    addEventListener(type: string, listener: Listener): void;
+    removeEventListener(type: string, listener: Listener): void;
+    /** Called by the peer: deliver a message event to this window's listeners. */
+    postMessage(data: unknown, targetOrigin: string): void;
+    /**
+     * Deliver a message that did not come from the peer — an attacker page, or an
+     * unrelated widget on the same origin. The handshake must ignore it.
+     */
+    injectMessage(data: unknown, origin: string, source?: unknown): void;
+    /** Deliver everything held back while `autoFlush` was off. */
+    flush(): void;
+    /** Close this window, firing `pagehide` the way a real one does. */
+    close(): void;
+}
+/** Two fake windows wired to each other: the opener, and the window it opened. */
+declare function fakeWindowPair(openerOrigin: string, childOrigin: string): {
+    opener: FakeWindow;
+    child: FakeWindow;
+};
+
+/**
+ * Drain pending microtasks — and the microtasks they queue.
+ *
+ * Delivery on a `BroadcastChannel`, and on the MemoryHub that stands in for it,
+ * is asynchronous. `await tick()` is the line between "this tab wrote" and
+ * "every other tab has seen it".
+ */
+declare const tick: () => Promise<void>;
+/**
+ * Wait out the late-joiner snapshot window.
+ *
+ * A peer answers a newcomer's `hello` after a jittered pause, and only if
+ * nobody else already did — which is what turns N replies into one. Hydration
+ * is therefore not a microtask away: it costs up to `snapshotDelayMs`, 40 by
+ * default. One `tick()` is not enough, on purpose.
+ */
+declare const snapshotWindow: (ms?: number) => Promise<void>;
+
+export { FakeLockManager, FakeWindow, type Scenario, type ScenarioOptions, type Tab, type TabOptions, createScenario, fakeWindowPair, snapshotWindow, tick };

package/dist/index.js

@@ -0,0 +1,278 @@
+// src/scenario.ts
+import {
+  createChannel,
+  createLeader,
+  createPresence,
+  createSharedReducer,
+  createSharedStore
+} from "@use-everywhere/core";
+import { MemoryHub } from "@use-everywhere/core/testing";
+
+// src/fake-locks.ts
+var abortError = () => new DOMException("The operation was aborted.", "AbortError");
+var FakeLockManager = class {
+  constructor() {
+    this.holds = /* @__PURE__ */ new Map();
+    this.queues = /* @__PURE__ */ new Map();
+    this.nextHoldId = 1;
+  }
+  request(name, options, callback) {
+    return this.requestAs(void 0, name, options, callback);
+  }
+  /**
+   * A view of this manager tagged with an owner, so `reclaim(owner)` can take
+   * the lock back the way a browser does when the tab holding it disappears.
+   */
+  forOwner(owner) {
+    return {
+      request: (name, options, callback) => this.requestAs(owner, name, options, callback)
+    };
+  }
+  /**
+   * The tab named `owner` is gone: free every lock it holds and forget every
+   * lock it was waiting on.
+   *
+   * Its callbacks are never settled — that is the point. A crashed tab's code
+   * does not get to run again, and a test that asserts the *next* tab took the
+   * seat is asserting exactly what the browser guarantees.
+   */
+  reclaim(owner) {
+    for (const [name, hold] of [...this.holds]) {
+      if (hold.owner !== owner) continue;
+      this.holds.delete(name);
+      this.queues.get(name)?.shift()?.grant();
+    }
+    for (const queue of this.queues.values()) {
+      for (let at = queue.length - 1; at >= 0; at -= 1) {
+        if (queue[at].owner === owner) queue.splice(at, 1);
+      }
+    }
+  }
+  /** Is this lock held by anyone? */
+  isHeld(name) {
+    return this.holds.has(name);
+  }
+  /** Which owner holds it, if the request was tagged with one. */
+  holder(name) {
+    return this.holds.get(name)?.owner;
+  }
+  /** How many callers are waiting behind the holder. */
+  queued(name) {
+    return this.queues.get(name)?.length ?? 0;
+  }
+  requestAs(owner, name, options, callback) {
+    return new Promise((resolve, reject) => {
+      const grant = () => {
+        const hold = { owner, id: this.nextHoldId++ };
+        this.holds.set(name, hold);
+        void callback().catch(() => {
+        }).then(() => {
+          if (this.holds.get(name)?.id !== hold.id) {
+            resolve();
+            return;
+          }
+          this.holds.delete(name);
+          const next = this.queues.get(name)?.shift();
+          resolve();
+          next?.grant();
+        });
+      };
+      if (options.signal?.aborted) {
+        reject(abortError());
+        return;
+      }
+      if (!this.holds.has(name)) {
+        grant();
+        return;
+      }
+      const waiter = { owner, grant };
+      const queue = this.queues.get(name) ?? [];
+      queue.push(waiter);
+      this.queues.set(name, queue);
+      options.signal?.addEventListener("abort", () => {
+        const at = queue.indexOf(waiter);
+        if (at >= 0) {
+          queue.splice(at, 1);
+          reject(abortError());
+        }
+      });
+    });
+  }
+};
+
+// src/timing.ts
+var tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+var snapshotWindow = (ms = 80) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/scenario.ts
+var SimulatedTab = class {
+  constructor(id, hub, locks, election, kind) {
+    this.id = id;
+    this.hub = hub;
+    this.locks = locks;
+    this.election = election;
+    this.kind = kind;
+    this.wires = [];
+    this.created = [];
+    this.state = "open";
+  }
+  get gone() {
+    return this.state !== "open";
+  }
+  store(name, initial, options = {}) {
+    return this.track(createSharedStore(name, initial, { ...this.common(), ...options }));
+  }
+  reducer(name, reducer, initial, options = {}) {
+    return this.track(
+      createSharedReducer(name, reducer, initial, { ...this.common(), ...options })
+    );
+  }
+  channel(name, options = {}) {
+    return this.track(createChannel(name, { ...this.common(), ...options }));
+  }
+  presence(name, options = {}) {
+    return this.track(createPresence(name, { ...this.common(), ...options }));
+  }
+  leader(name, options = {}) {
+    const election = this.election === "web-locks" ? { strategy: "web-locks", locks: this.locks.forOwner(this.id) } : { strategy: "heartbeat" };
+    return this.track(createLeader(name, { ...this.common(), ...election, ...options }));
+  }
+  /**
+   * The difference between closing and crashing is the *order* these two lines
+   * run in, which is exactly the difference in a browser: a tab that closes
+   * gets its goodbye out before the wire goes, and a tab that crashes does not.
+   */
+  close() {
+    if (this.gone) return;
+    this.state = "closed";
+    for (const closeable of this.created) closeable.close();
+    for (const wire of this.wires) wire.close();
+  }
+  crash() {
+    if (this.gone) return;
+    this.state = "crashed";
+    for (const wire of this.wires) wire.close();
+    this.locks.reclaim(this.id);
+  }
+  /** Options every primitive in this tab shares: its own wire, its own kind. */
+  common() {
+    return {
+      transport: () => {
+        const wire = this.hub.connect();
+        this.wires.push(wire);
+        return wire;
+      },
+      // Spread-friendly: exactOptionalPropertyTypes rejects an explicit undefined.
+      ...this.kind ? { kind: this.kind } : {}
+    };
+  }
+  track(primitive) {
+    this.created.push(primitive);
+    return primitive;
+  }
+};
+function createScenario(options = {}) {
+  const hub = new MemoryHub();
+  const locks = new FakeLockManager();
+  const election = options.election ?? "web-locks";
+  const tabs = [];
+  return {
+    hub,
+    locks,
+    tabs,
+    tab(tabOptions = {}) {
+      const tab = new SimulatedTab(
+        tabOptions.id ?? `tab-${tabs.length + 1}`,
+        hub,
+        locks,
+        election,
+        tabOptions.kind
+      );
+      tabs.push(tab);
+      return tab;
+    },
+    settle(ms) {
+      return ms === void 0 ? tick() : new Promise((resolve) => setTimeout(resolve, ms));
+    },
+    dispose() {
+      for (const tab of tabs) tab.close();
+    }
+  };
+}
+
+// src/fake-window.ts
+var FakeWindow = class {
+  constructor(origin) {
+    this.closed = false;
+    this.peer = null;
+    /** Messages wait here until `flush()` — a child that has not loaded yet. */
+    this.pending = [];
+    this.autoFlush = true;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.origin = origin;
+  }
+  addEventListener(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+  removeEventListener(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  /** Called by the peer: deliver a message event to this window's listeners. */
+  postMessage(data, targetOrigin) {
+    if (targetOrigin !== "*" && targetOrigin !== this.origin) return;
+    const from = this.peer;
+    const deliver = () => {
+      if (this.closed) return;
+      for (const fn of this.listeners.get("message") ?? []) {
+        fn({ data, origin: from?.origin ?? this.origin, source: from });
+      }
+    };
+    if (this.autoFlush) queueMicrotask(deliver);
+    else this.pending.push(deliver);
+  }
+  /**
+   * Deliver a message that did not come from the peer — an attacker page, or an
+   * unrelated widget on the same origin. The handshake must ignore it.
+   */
+  injectMessage(data, origin, source = {}) {
+    for (const fn of this.listeners.get("message") ?? []) {
+      fn({ data, origin, source });
+    }
+  }
+  /** Deliver everything held back while `autoFlush` was off. */
+  flush() {
+    for (const deliver of this.pending.splice(0)) deliver();
+  }
+  /** Close this window, firing `pagehide` the way a real one does. */
+  close() {
+    this.closed = true;
+    for (const fn of this.listeners.get("pagehide") ?? []) {
+      fn({ data: void 0, origin: this.origin, source: this });
+    }
+  }
+};
+function fakeWindowPair(openerOrigin, childOrigin) {
+  const opener = new FakeWindow(openerOrigin);
+  const child = new FakeWindow(childOrigin);
+  opener.peer = child;
+  child.peer = opener;
+  return { opener, child };
+}
+
+// src/index.ts
+import { MemoryHub as MemoryHub2, MemoryTransport } from "@use-everywhere/core/testing";
+export {
+  FakeLockManager,
+  FakeWindow,
+  MemoryHub2 as MemoryHub,
+  MemoryTransport,
+  createScenario,
+  fakeWindowPair,
+  snapshotWindow,
+  tick
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@use-everywhere/test-utils",
+  "version": "0.0.0",
+  "description": "Simulate several tabs in one process: a scenario DSL, an in-memory bus, fake windows and fake Web Locks",
+  "license": "MIT",
+  "author": "Jonatan Kruszewski <jonakrusze@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rxova/use-everywhere.git",
+    "directory": "packages/test-utils"
+  },
+  "homepage": "https://github.com/rxova/use-everywhere#readme",
+  "bugs": "https://github.com/rxova/use-everywhere/issues",
+  "keywords": [
+    "testing",
+    "cross-tab",
+    "broadcastchannel",
+    "shared-state",
+    "use-everywhere"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@use-everywhere/core": "0.8.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@vitest/coverage-v8": "^4.1.10",
+    "publint": "^0.3.21",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "check:exports": "publint --strict && attw --pack .",
+    "pack:smoke": "node --import tsx ../tooling/pack-smoke.ts"
+  }
+}