@use-everywhere/core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,13 +1,4 @@
-/**
- * Minimal message bus. Implementations: BroadcastChannelTransport (same-origin),
- * NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never
- * echoes a client's own posts back to it.
- */
-interface Transport {
-    post(data: unknown): void;
-    subscribe(listener: (data: unknown) => void): () => void;
-    close(): void;
-}
+import { T as Transport, a as TransportKind } from './transport.types-CV1WZOhy.cjs';
 
 type MessageMap = Record<string, unknown>;
 type PeerKind = 'tab' | 'worker' | (string & {});
@@ -166,8 +157,15 @@ interface BusOptions extends CommonOptions {
 }
 
 interface PresenceOptions extends BusOptions {
-    /** Peers silent for longer than this are dropped. Default 5000ms. */
+    /** How much silence makes a peer suspect. Default 5000ms. It is then probed, not dropped. */
     pruneAfterMs?: number;
+    /**
+     * How long a probed peer has to answer before it is dropped. Default 1000ms.
+     *
+     * This is a round trip on a same-origin channel, not a heartbeat interval, so
+     * it can be short: a peer that is merely throttled still answers at once.
+     */
+    probeGraceMs?: number;
 }
 interface Presence {
     readonly clientId: string;
@@ -180,7 +178,19 @@ interface Presence {
 /**
  * Tracks the other tabs/windows/workers on this bus. Any message from a peer
  * counts as a liveness signal (state patches, events, and presence pings all
- * piggyback); explicit 'bye' or silence past pruneAfterMs removes them.
+ * piggyback); an explicit 'bye' removes them at once.
+ *
+ * Silence, though, is not proof of death — and treating it that way is what
+ * made the roster flap. Browsers clamp a hidden tab's timers to roughly one
+ * tick a minute, so a perfectly healthy backgrounded peer stops heartbeating,
+ * gets pruned, pings once, is re-added, and disappears again: a peer count
+ * oscillating once a minute for no reason. Waking a laptop does it to every
+ * peer at once.
+ *
+ * What saves it is that *message handlers are not throttled* — only timers are.
+ * A hidden tab still answers a hello the instant it arrives. So a peer that
+ * goes quiet is probed rather than dropped, and only silence that survives the
+ * probe counts as gone.
  */
 declare function createPresence(name: string, options?: PresenceOptions): Presence;
 
@@ -189,13 +199,35 @@ declare function createPresence(name: string, options?: PresenceOptions): Presen
  * the leader's re-announce interval, which is a different thing from the bus's
  * presence ping. See the note in leader.ts about forwarding to getBus.
  */
+/**
+ * How the seat is arbitrated.
+ *
+ * - `'web-locks'` — the browser's Web Locks API owns the queue. The lock is
+ *   released by the browser itself when a tab dies, and holding it does not
+ *   depend on a timer, so a backgrounded tab cannot be deposed for being
+ *   throttled. No heartbeat traffic at all.
+ * - `'heartbeat'` — lease-and-claim over the bus. Works anywhere, including
+ *   plain-http origins where `navigator.locks` does not exist.
+ * - `'auto'` (default) — Web Locks when available, heartbeat otherwise.
+ */
+type LeaderStrategy = 'auto' | 'web-locks' | 'heartbeat';
 interface LeaderOptions extends CommonOptions {
-    /** How often the leader re-announces itself, in ms. Default 1000. */
+    /** How often the leader re-announces itself, in ms. Default 1000. Heartbeat strategy only. */
     heartbeatMs?: number;
-    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. */
+    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. Heartbeat strategy only. */
     leaseMs?: number;
     /** May this client hold the leadership? Default true. */
     eligible?: boolean;
+    /** How to arbitrate the seat. Default 'auto'. */
+    strategy?: LeaderStrategy;
+    /** @internal Test seam for the Web Locks manager. Defaults to navigator.locks. */
+    locks?: LockManagerLike;
+}
+/** The slice of the Web Locks API this library uses. */
+interface LockManagerLike {
+    request(name: string, options: {
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
 }
 interface LeaderSnapshot {
     /** The current leader's clientId, or null while the seat is empty. */
@@ -204,9 +236,17 @@ interface LeaderSnapshot {
 }
 interface Leader {
     readonly clientId: string;
+    /** Which mechanism arbitrates this seat — useful in devtools and bug reports. */
+    readonly strategy: Exclude<LeaderStrategy, 'auto'>;
     /** Frozen; a new object only when the leader actually changes. */
     getSnapshot(): LeaderSnapshot;
     subscribe(fn: () => void): () => void;
+    /**
+     * Resolves the moment this client holds the seat, or immediately if it
+     * already does. Rejects if the leader is closed while still waiting — so an
+     * `await` in a torn-down tab does not hang forever.
+     */
+    waitForLeadership(): Promise<void>;
     /** Give up the seat now. Peers take over immediately rather than waiting for the lease. */
     resign(): void;
     /** Turn candidacy on or off. Eligibility is a property of the tab, not a component. */
@@ -390,19 +430,23 @@ declare function observeBus(name: string, fn: BusObserver): () => void;
 /** Log every wire on a bus to the console. Returns a function to stop. */
 declare function enableDebug(options?: DebugOptions): () => void;
 
-/**
- * Get the shared bus for `name`, creating it on first use. Callers must call
- * bus.release() exactly once when done. When a custom transport factory is
- * given (tests), every call creates an isolated bus — one call = one simulated client.
- */
 /**
  * Names of the buses currently alive on this page. Buses built with a custom
- * transport (tests) bypass the registry, so they are not listed.
+ * transport (tests) bypass the table, so they are not listed.
  */
 declare function getBusNames(): string[];
+/**
+ * What is actually carrying this bus's traffic, or null if it has no bus yet.
+ *
+ * Answers the question a developer asks when nothing is syncing and the code
+ * looks right: *is anything even connected?* `'none'` means no — writes are
+ * local and no peer will ever see them.
+ */
+declare function getTransportKind(name: string): TransportKind | null;
 
 /** Same-origin transport over a real BroadcastChannel. */
 declare class BroadcastChannelTransport implements Transport {
+    readonly kind: TransportKind;
     private bc;
     private listeners;
     constructor(name: string);
@@ -416,40 +460,65 @@ declare class BroadcastChannelTransport implements Transport {
  * Used for SSR and for state scoped to a single tab.
  */
 declare class NoopTransport implements Transport {
+    readonly kind: TransportKind;
     post(): void;
     subscribe(): () => void;
     close(): void;
 }
 
-declare function isBroadcastChannelAvailable(): boolean;
-/** Default factory: real BroadcastChannel when available, otherwise a local no-op. */
-declare function defaultTransport(name: string): Transport;
-
-/** One simulated client on a MemoryHub. Create via hub.connect(). */
-declare class MemoryTransport implements Transport {
-    private hub;
+/**
+ * Cross-tab delivery over the `storage` event, for browsers with no
+ * `BroadcastChannel`.
+ *
+ * The mechanism is a quirk turned to advantage: writing to `localStorage` fires
+ * a `storage` event in *every other* same-origin tab and never in the writer —
+ * exactly BroadcastChannel's no-self-echo semantics, for free.
+ *
+ * Two differences from the real thing, both deliberate and both documented:
+ *
+ * 1. **Fidelity is JSON, not structured clone.** `localStorage` holds strings.
+ *    A `Date` arrives as an ISO string and a `Map` as `{}`. Values that cannot
+ *    be represented at all — functions, symbols — are rejected rather than
+ *    silently dropped, so a write still cannot leave this tab holding something
+ *    its peers never received.
+ * 2. **The entry is removed immediately after writing.** Peers have already been
+ *    notified by then (the event carries the value), and leaving application
+ *    state sitting in `localStorage` would be both a quota cost and a privacy
+ *    one. The removal fires a second event with a null `newValue`, which
+ *    receivers ignore.
+ */
+declare class StorageTransport implements Transport {
+    readonly kind: TransportKind;
+    private key;
+    private storage;
     private listeners;
-    private closed;
-    constructor(hub: MemoryHub);
+    private onStorage;
+    private seq;
+    constructor(name: string, storage?: Storage);
     post(data: unknown): void;
     subscribe(listener: (data: unknown) => void): () => void;
     close(): void;
-    /** @internal */
-    deliver(data: unknown): void;
 }
 
+declare function isBroadcastChannelAvailable(): boolean;
 /**
- * In-memory hub for tests: N transports attached to one hub, each post is
- * delivered to every *other* transport on a microtask (mirrors BroadcastChannel's
- * async, no-self-echo delivery).
+ * Can we hear other tabs through the `storage` event?
+ *
+ * Reading `localStorage` is itself what throws when storage is blocked — a
+ * sandboxed iframe, third-party cookies off — so the check has to happen inside
+ * a try, not around a property test. Availability is also not writability:
+ * Safari's old private mode exposed the object and threw on every setItem.
  */
-declare class MemoryHub {
-    private transports;
-    connect(): MemoryTransport;
-    /** @internal */
-    broadcast(from: MemoryTransport, data: unknown): void;
-    /** @internal */
-    disconnect(transport: MemoryTransport): void;
-}
+declare function isStorageEventAvailable(): boolean;
+/**
+ * Pick the best wire this browser can offer, and say so when it is not the
+ * good one.
+ *
+ * The chain matters more than it looks. Before it existed, a context without
+ * `BroadcastChannel` got a silent no-op: every hook kept working, every write
+ * appeared to succeed, and nothing was ever shared with anybody. That is the
+ * worst failure this library can have, because it looks exactly like success.
+ */
+declare function defaultTransport(name: string): Transport;
 
-export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, type Transport, type Version, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, isBroadcastChannelAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };
+export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, StorageTransport, Transport, TransportKind, type Version, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, isBroadcastChannelAvailable, isStorageEventAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };

package/dist/index.d.ts

@@ -1,13 +1,4 @@
-/**
- * Minimal message bus. Implementations: BroadcastChannelTransport (same-origin),
- * NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never
- * echoes a client's own posts back to it.
- */
-interface Transport {
-    post(data: unknown): void;
-    subscribe(listener: (data: unknown) => void): () => void;
-    close(): void;
-}
+import { T as Transport, a as TransportKind } from './transport.types-CV1WZOhy.js';
 
 type MessageMap = Record<string, unknown>;
 type PeerKind = 'tab' | 'worker' | (string & {});
@@ -166,8 +157,15 @@ interface BusOptions extends CommonOptions {
 }
 
 interface PresenceOptions extends BusOptions {
-    /** Peers silent for longer than this are dropped. Default 5000ms. */
+    /** How much silence makes a peer suspect. Default 5000ms. It is then probed, not dropped. */
     pruneAfterMs?: number;
+    /**
+     * How long a probed peer has to answer before it is dropped. Default 1000ms.
+     *
+     * This is a round trip on a same-origin channel, not a heartbeat interval, so
+     * it can be short: a peer that is merely throttled still answers at once.
+     */
+    probeGraceMs?: number;
 }
 interface Presence {
     readonly clientId: string;
@@ -180,7 +178,19 @@ interface Presence {
 /**
  * Tracks the other tabs/windows/workers on this bus. Any message from a peer
  * counts as a liveness signal (state patches, events, and presence pings all
- * piggyback); explicit 'bye' or silence past pruneAfterMs removes them.
+ * piggyback); an explicit 'bye' removes them at once.
+ *
+ * Silence, though, is not proof of death — and treating it that way is what
+ * made the roster flap. Browsers clamp a hidden tab's timers to roughly one
+ * tick a minute, so a perfectly healthy backgrounded peer stops heartbeating,
+ * gets pruned, pings once, is re-added, and disappears again: a peer count
+ * oscillating once a minute for no reason. Waking a laptop does it to every
+ * peer at once.
+ *
+ * What saves it is that *message handlers are not throttled* — only timers are.
+ * A hidden tab still answers a hello the instant it arrives. So a peer that
+ * goes quiet is probed rather than dropped, and only silence that survives the
+ * probe counts as gone.
  */
 declare function createPresence(name: string, options?: PresenceOptions): Presence;
 
@@ -189,13 +199,35 @@ declare function createPresence(name: string, options?: PresenceOptions): Presen
  * the leader's re-announce interval, which is a different thing from the bus's
  * presence ping. See the note in leader.ts about forwarding to getBus.
  */
+/**
+ * How the seat is arbitrated.
+ *
+ * - `'web-locks'` — the browser's Web Locks API owns the queue. The lock is
+ *   released by the browser itself when a tab dies, and holding it does not
+ *   depend on a timer, so a backgrounded tab cannot be deposed for being
+ *   throttled. No heartbeat traffic at all.
+ * - `'heartbeat'` — lease-and-claim over the bus. Works anywhere, including
+ *   plain-http origins where `navigator.locks` does not exist.
+ * - `'auto'` (default) — Web Locks when available, heartbeat otherwise.
+ */
+type LeaderStrategy = 'auto' | 'web-locks' | 'heartbeat';
 interface LeaderOptions extends CommonOptions {
-    /** How often the leader re-announces itself, in ms. Default 1000. */
+    /** How often the leader re-announces itself, in ms. Default 1000. Heartbeat strategy only. */
     heartbeatMs?: number;
-    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. */
+    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. Heartbeat strategy only. */
     leaseMs?: number;
     /** May this client hold the leadership? Default true. */
     eligible?: boolean;
+    /** How to arbitrate the seat. Default 'auto'. */
+    strategy?: LeaderStrategy;
+    /** @internal Test seam for the Web Locks manager. Defaults to navigator.locks. */
+    locks?: LockManagerLike;
+}
+/** The slice of the Web Locks API this library uses. */
+interface LockManagerLike {
+    request(name: string, options: {
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
 }
 interface LeaderSnapshot {
     /** The current leader's clientId, or null while the seat is empty. */
@@ -204,9 +236,17 @@ interface LeaderSnapshot {
 }
 interface Leader {
     readonly clientId: string;
+    /** Which mechanism arbitrates this seat — useful in devtools and bug reports. */
+    readonly strategy: Exclude<LeaderStrategy, 'auto'>;
     /** Frozen; a new object only when the leader actually changes. */
     getSnapshot(): LeaderSnapshot;
     subscribe(fn: () => void): () => void;
+    /**
+     * Resolves the moment this client holds the seat, or immediately if it
+     * already does. Rejects if the leader is closed while still waiting — so an
+     * `await` in a torn-down tab does not hang forever.
+     */
+    waitForLeadership(): Promise<void>;
     /** Give up the seat now. Peers take over immediately rather than waiting for the lease. */
     resign(): void;
     /** Turn candidacy on or off. Eligibility is a property of the tab, not a component. */
@@ -390,19 +430,23 @@ declare function observeBus(name: string, fn: BusObserver): () => void;
 /** Log every wire on a bus to the console. Returns a function to stop. */
 declare function enableDebug(options?: DebugOptions): () => void;
 
-/**
- * Get the shared bus for `name`, creating it on first use. Callers must call
- * bus.release() exactly once when done. When a custom transport factory is
- * given (tests), every call creates an isolated bus — one call = one simulated client.
- */
 /**
  * Names of the buses currently alive on this page. Buses built with a custom
- * transport (tests) bypass the registry, so they are not listed.
+ * transport (tests) bypass the table, so they are not listed.
  */
 declare function getBusNames(): string[];
+/**
+ * What is actually carrying this bus's traffic, or null if it has no bus yet.
+ *
+ * Answers the question a developer asks when nothing is syncing and the code
+ * looks right: *is anything even connected?* `'none'` means no — writes are
+ * local and no peer will ever see them.
+ */
+declare function getTransportKind(name: string): TransportKind | null;
 
 /** Same-origin transport over a real BroadcastChannel. */
 declare class BroadcastChannelTransport implements Transport {
+    readonly kind: TransportKind;
     private bc;
     private listeners;
     constructor(name: string);
@@ -416,40 +460,65 @@ declare class BroadcastChannelTransport implements Transport {
  * Used for SSR and for state scoped to a single tab.
  */
 declare class NoopTransport implements Transport {
+    readonly kind: TransportKind;
     post(): void;
     subscribe(): () => void;
     close(): void;
 }
 
-declare function isBroadcastChannelAvailable(): boolean;
-/** Default factory: real BroadcastChannel when available, otherwise a local no-op. */
-declare function defaultTransport(name: string): Transport;
-
-/** One simulated client on a MemoryHub. Create via hub.connect(). */
-declare class MemoryTransport implements Transport {
-    private hub;
+/**
+ * Cross-tab delivery over the `storage` event, for browsers with no
+ * `BroadcastChannel`.
+ *
+ * The mechanism is a quirk turned to advantage: writing to `localStorage` fires
+ * a `storage` event in *every other* same-origin tab and never in the writer —
+ * exactly BroadcastChannel's no-self-echo semantics, for free.
+ *
+ * Two differences from the real thing, both deliberate and both documented:
+ *
+ * 1. **Fidelity is JSON, not structured clone.** `localStorage` holds strings.
+ *    A `Date` arrives as an ISO string and a `Map` as `{}`. Values that cannot
+ *    be represented at all — functions, symbols — are rejected rather than
+ *    silently dropped, so a write still cannot leave this tab holding something
+ *    its peers never received.
+ * 2. **The entry is removed immediately after writing.** Peers have already been
+ *    notified by then (the event carries the value), and leaving application
+ *    state sitting in `localStorage` would be both a quota cost and a privacy
+ *    one. The removal fires a second event with a null `newValue`, which
+ *    receivers ignore.
+ */
+declare class StorageTransport implements Transport {
+    readonly kind: TransportKind;
+    private key;
+    private storage;
     private listeners;
-    private closed;
-    constructor(hub: MemoryHub);
+    private onStorage;
+    private seq;
+    constructor(name: string, storage?: Storage);
     post(data: unknown): void;
     subscribe(listener: (data: unknown) => void): () => void;
     close(): void;
-    /** @internal */
-    deliver(data: unknown): void;
 }
 
+declare function isBroadcastChannelAvailable(): boolean;
 /**
- * In-memory hub for tests: N transports attached to one hub, each post is
- * delivered to every *other* transport on a microtask (mirrors BroadcastChannel's
- * async, no-self-echo delivery).
+ * Can we hear other tabs through the `storage` event?
+ *
+ * Reading `localStorage` is itself what throws when storage is blocked — a
+ * sandboxed iframe, third-party cookies off — so the check has to happen inside
+ * a try, not around a property test. Availability is also not writability:
+ * Safari's old private mode exposed the object and threw on every setItem.
  */
-declare class MemoryHub {
-    private transports;
-    connect(): MemoryTransport;
-    /** @internal */
-    broadcast(from: MemoryTransport, data: unknown): void;
-    /** @internal */
-    disconnect(transport: MemoryTransport): void;
-}
+declare function isStorageEventAvailable(): boolean;
+/**
+ * Pick the best wire this browser can offer, and say so when it is not the
+ * good one.
+ *
+ * The chain matters more than it looks. Before it existed, a context without
+ * `BroadcastChannel` got a silent no-op: every hook kept working, every write
+ * appeared to succeed, and nothing was ever shared with anybody. That is the
+ * worst failure this library can have, because it looks exactly like success.
+ */
+declare function defaultTransport(name: string): Transport;
 
-export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, MemoryHub, MemoryTransport, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, type Transport, type Version, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, isBroadcastChannelAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };
+export { BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type MessageEventLike, type MessageMap, type MessageMeta, NoopTransport, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type Presence, type PresenceOptions, type SharedStore, type SharedStoreOptions, type StorageLike, StorageTransport, Transport, TransportKind, type Version, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, isBroadcastChannelAvailable, isStorageEventAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };