@use-everywhere/core 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { T as Transport } from './transport.types-tQ1cu6Xm.js';
+import { T as Transport, a as TransportKind } from './transport.types-CV1WZOhy.js';
 
 type MessageMap = Record<string, unknown>;
 type PeerKind = 'tab' | 'worker' | (string & {});
@@ -8,6 +8,8 @@ interface Peer {
     id: string;
     kind: PeerKind;
     lastSeen: number;
+    /** What that client published about itself, if anything. */
+    metadata?: unknown;
 }
 interface MessageMeta {
     clientId: string;
@@ -21,17 +23,142 @@ interface CommonOptions {
     kind?: PeerKind;
 }
 
-interface Channel<M extends MessageMap> {
+/**
+ * The [Standard Schema](https://standardschema.dev) v1 interface, inlined.
+ *
+ * Inlined rather than depended on, which is the whole point of the spec: it is
+ * a shape, not a package. Zod, Valibot and ArkType all expose `~standard`, so
+ * accepting this type means accepting any of them — and any hand-written
+ * validator — without this library taking a dependency on, or a position about,
+ * which one you use.
+ *
+ * Only the parts that are read here are declared. The full spec has more.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+    }>;
+};
+/** Why a payload was refused, for {@link OnInvalid}. */
+interface InvalidPayload {
+    /** The bus this happened on. */
+    readonly name: string;
+    /** Message type for a channel, key for a store. */
+    readonly key: string;
+    /** `'in'` — a peer sent it; `'out'` — this client tried to send it. */
+    readonly direction: 'in' | 'out';
+    /** The value as it arrived. Not validated, so genuinely `unknown`. */
+    readonly payload: unknown;
+    /** One line per issue the schema reported, or a single line explaining a schema that could not be used. */
+    readonly issues: readonly string[];
+}
+/**
+ * Called when a payload fails its schema, instead of the default development
+ * warning. Report it, count it, sample it — but it does not change the outcome:
+ * an inbound payload is dropped and an outbound one throws either way.
+ */
+type OnInvalid = (info: InvalidPayload) => void;
+/**
+ * Per-key validators. A key with no entry is not validated, so adopting this
+ * one message or one store key at a time is the expected way to use it.
+ */
+type SchemaMap<M> = {
+    readonly [K in keyof M & string]?: StandardSchemaV1<unknown, M[K]>;
+};
+interface SchemaOptions<M> {
+    /**
+     * Validate payloads against a [Standard Schema](https://standardschema.dev)
+     * before trusting them — any Zod, Valibot or ArkType schema, or anything else
+     * exposing `~standard`.
+     *
+     * Without this, an inbound payload is **cast, not checked**: a peer running
+     * last week's deploy sends whatever that build thought the shape was, and the
+     * receiving code reads it as whatever this build's types say. That is the one
+     * place in this library where a type is a hope rather than a guarantee, and
+     * a rolling deploy is what turns it into a bug.
+     *
+     * Validation runs in both directions. Inbound, a failure drops the payload —
+     * the same choice the envelope makes for a wire it cannot read. Outbound, it
+     * **throws**, because a value your own code just produced and cannot describe
+     * is a bug in this tab, and finding it here beats finding it in someone
+     * else's.
+     */
+    readonly schema?: SchemaMap<M>;
+    /** Observe validation failures instead of the default development warning. */
+    readonly onInvalid?: OnInvalid;
+}
+
+interface ChannelOptions<M extends MessageMap> extends CommonOptions, SchemaOptions<M> {
+}
+/**
+ * What each message type answers with, for `ask`/`answer`.
+ *
+ * A separate map from the request types, and empty by default, so
+ * request/response is opt-in and typed rather than `unknown` everywhere.
+ *
+ * ```ts
+ * type Requests = { 'config:get': void };
+ * type Replies = { 'config:get': { theme: string } };
+ * const channel = createChannel<Requests, Replies>('app');
+ * ```
+ */
+type ReplyMap<M extends MessageMap> = Partial<Record<keyof M, unknown>>;
+interface PostOptions {
+    /**
+     * Also deliver to this client's own handlers.
+     *
+     * A post is not echoed by default, which matches `BroadcastChannel` and is
+     * usually right. It is wrong for the case the README kept demonstrating: a
+     * component that has to update local state *and* tell everyone else ends up
+     * writing the same effect twice, in two places, which then drift.
+     */
+    echo?: boolean;
+}
+interface OnOptions {
+    /** Unsubscribe after the first message. The returned function is still safe to call. */
+    once?: boolean;
+}
+interface AskOptions {
+    /** Give up after this long. Default 5000. */
+    timeoutMs?: number;
+}
+interface Channel<M extends MessageMap, R extends ReplyMap<M> = Record<never, never>> {
     readonly name: string;
     readonly clientId: string;
-    /** Fire-and-forget to every other tab/window/worker on this origin. Not echoed to self. */
-    post<K extends keyof M & string>(type: K, payload: M[K]): void;
-    on<K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void): () => void;
+    /** Fire-and-forget to every other tab/window/worker on this origin. */
+    post<K extends keyof M & string>(type: K, payload: M[K], options?: PostOptions): void;
+    on<K extends keyof M & string>(type: K, handler: (payload: M[K], meta: MessageMeta) => void, options?: OnOptions): () => void;
+    /**
+     * Ask the origin a question and wait for the first answer.
+     *
+     * Rejects if nobody answers before the timeout — an unanswered question is a
+     * fact worth having rather than a promise that hangs. If several clients
+     * registered an `answer` for this type, the first reply to arrive wins and
+     * the rest are dropped; gate the responder on leadership when you need the
+     * answer to come from a particular tab.
+     */
+    ask<K extends keyof M & keyof R & string>(type: K, payload: M[K], options?: AskOptions): Promise<R[K]>;
+    /** Answer `ask`s of this type. Returns an unsubscribe. */
+    answer<K extends keyof M & keyof R & string>(type: K, responder: (payload: M[K], meta: MessageMeta) => R[K]): () => void;
     close(): void;
 }
 
 /** Typed pub/sub over the same-origin bus. */
-declare function createChannel<M extends MessageMap>(name: string, options?: CommonOptions): Channel<M>;
+declare function createChannel<M extends MessageMap, R extends ReplyMap<M> = Record<never, never>>(name: string, options?: ChannelOptions<M>): Channel<M, R>;
 
 /**
  * What goes to disk. The version clocks travel *with* the values — that is the
@@ -40,7 +167,18 @@ declare function createChannel<M extends MessageMap>(name: string, options?: Com
  * legitimately lose to, whatever the live tabs are holding.
  */
 interface Persisted {
+    /**
+     * The *envelope* version — the shape of this record, owned by the library.
+     * Not to be confused with `schema`, which is the shape of your state and is
+     * owned by you.
+     */
     v: 1;
+    /**
+     * The app's state-shape version at the time of writing, from
+     * {@link PersistOptions.version}. Absent on anything written before
+     * versioning existed, which reads as 0.
+     */
+    schema?: number;
     state: Record<string, unknown>;
     versions: Record<string, Version>;
 }
@@ -53,15 +191,56 @@ interface PersistAdapter {
     write(snapshot: Persisted): void | Promise<void>;
     remove?(): void | Promise<void>;
 }
+/** Why a restore was refused, for {@link PersistOptions.onRestoreError}. */
+interface RestoreError {
+    /** `'ahead'` — written by a newer build; `'no-migrate'` — older, with no way forward; `'migrate-threw'`. */
+    readonly reason: 'ahead' | 'no-migrate' | 'migrate-threw';
+    /** The schema version on disk. */
+    readonly found: number;
+    /** The schema version this build expects. */
+    readonly expected: number;
+    /** Present only for `'migrate-threw'`. */
+    readonly cause?: unknown;
+}
 interface PersistOptions {
     adapter: PersistAdapter;
     /** Persist only these keys. Default: every key that has been written. */
     keys?: string[];
     /** Coalesce writes for this long. Default 100. */
     debounceMs?: number;
+    /**
+     * The version of *your* state's shape. Bump it whenever a key changes meaning
+     * or type, and supply {@link migrate} to carry old data forward.
+     *
+     * Disk is where version skew has its longest fuse. A wire from another deploy
+     * is gone in a second; a value written by last month's build sits there until
+     * someone reopens the tab, and then restores with a clock that beats every
+     * live tab. Without a version there is no way to even notice.
+     *
+     * Default 0, which is also what anything written before this existed reads as
+     * — so adding `version: 1` and a `migrate` is enough to adopt it.
+     */
+    version?: number;
+    /**
+     * Bring persisted state written at an older `version` up to the current one.
+     * Return the migrated state; the version clocks are carried over untouched,
+     * so a migrated value keeps its place in the last-writer-wins order.
+     *
+     * Only called when `from` is *older*. Newer data — an older build reading what
+     * a newer one wrote — is refused instead, because a build cannot be asked to
+     * understand a shape that postdates it. That is the same call the wire makes
+     * for a protocol version it does not know.
+     */
+    migrate?: (state: Record<string, unknown>, from: number) => Record<string, unknown>;
+    /**
+     * Called when persisted state is refused instead of restored. The store keeps
+     * its initial values and carries on either way — this is how you find out,
+     * and the default is a development warning.
+     */
+    onRestoreError?: (error: RestoreError) => void;
 }
 
-interface SharedStoreOptions extends CommonOptions {
+interface SharedStoreOptions<S = Record<string, unknown>> extends CommonOptions, SchemaOptions<S> {
     /**
      * Gatekeeper for incoming remote writes (patches and snapshot merges):
      * return false to ignore them. Lets callers delimit how much is shared —
@@ -70,9 +249,35 @@ interface SharedStoreOptions extends CommonOptions {
     accept?: (meta: MessageMeta) => boolean;
     /** Restore this store on creation and write it back as it changes. */
     persist?: PersistOptions;
+    /**
+     * Longest pause before answering a late joiner's request for state, in ms.
+     * Default 40. The actual wait is random within it, so peers do not all
+     * answer at once and the first reply cancels the rest.
+     */
+    snapshotDelayMs?: number;
 }
 interface SharedStore<S extends Record<string, unknown>> {
     readonly clientId: string;
+    /**
+     * Resolves once persisted state has been restored — or refused, or found
+     * absent. Already resolved when there is no `persist` option at all.
+     *
+     * Exists because an async adapter cannot hydrate before the store is handed
+     * back, and until now that gap was *unobservable*: a keystroke landing in it
+     * writes at counter 1, the restore arrives holding counter 5, and
+     * last-writer-wins correctly discards the newer keystroke. The behaviour is
+     * right and the surprise is total. Gate first paint or first input on this
+     * and the gap closes:
+     *
+     * ```ts
+     * await store.hydrated;
+     * ```
+     *
+     * Never rejects. A refused restore is reported through
+     * `persist.onRestoreError` and still settles, because a store that kept its
+     * initial values is usable and a promise nobody can await is not.
+     */
+    readonly hydrated: Promise<void>;
     /** Live proxy for imperative use: `store.state.count++` syncs everywhere. */
     readonly state: S;
     /** Immutable snapshot, replaced whenever a change is applied. Safe for useSyncExternalStore. */
@@ -80,6 +285,26 @@ interface SharedStore<S extends Record<string, unknown>> {
     /** The per-key version clocks behind the snapshot. Referentially stable, like getSnapshot. */
     getVersions(): Readonly<Record<string, Version>>;
     set<K extends keyof S & string>(key: K, value: S[K] | ((prev: S[K]) => S[K])): void;
+    /**
+     * Apply several writes, then notify subscribers once with the settled state.
+     *
+     * ```ts
+     * store.transaction(() => {
+     *   store.set('firstName', 'Ada');
+     *   store.set('lastName', 'Lovelace');
+     * });
+     * ```
+     *
+     * **Local batching, not a distributed transaction.** Each write is still its
+     * own patch on the wire, so a peer may see them arrive separately — making
+     * them atomic across tabs would need a wire type older builds would silently
+     * ignore, which is worse than the problem. What this buys is one re-render
+     * instead of N, and subscribers that never observe a half-applied group.
+     *
+     * Nests: only the outermost call flushes. Returns whatever `fn` returns, and
+     * flushes even if `fn` throws — the writes that did land are already real.
+     */
+    transaction<T>(fn: () => T): T;
     subscribe(fn: (key: keyof S & string, value: unknown, meta: MessageMeta) => void): () => void;
     subscribeKey(key: keyof S & string, fn: () => void): () => void;
     /**
@@ -96,9 +321,161 @@ interface SharedStore<S extends Record<string, unknown>> {
  * last-writer-wins version clocks and a hello/snapshot late-joiner handshake.
  * Create at most one store per name per tab (the React package memoizes).
  */
-declare function createSharedStore<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions): SharedStore<S>;
+declare function createSharedStore<S extends Record<string, unknown>>(name: string, initial: S, options?: SharedStoreOptions<S>): SharedStore<S>;
 
-/** Everything on the same-origin bus, multiplexed by scope over one BroadcastChannel per name. */
+/**
+ * Deliberately extends CommonOptions, not BusOptions: `heartbeatMs` here means
+ * 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. Heartbeat strategy only. */
+    heartbeatMs?: number;
+    /** 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. */
+    readonly leaderId: string | null;
+    readonly isLeader: boolean;
+}
+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. */
+    setEligible(eligible: boolean): void;
+    close(): void;
+}
+
+interface SharedReducerOptions extends CommonOptions {
+    /**
+     * Which reducer this is, when several share a bus name. Default `'default'`.
+     *
+     * The same axis as a store key: one bus, many reducers, each ordered
+     * independently of the others.
+     */
+    key?: string;
+    /**
+     * Reuse an existing leader rather than electing another. A reducer needs a
+     * sequencer, and a page that already has a `Leader` for this bus should not
+     * run a second election to get one.
+     */
+    leader?: Leader;
+    /** Election settings, when this reducer elects its own leader. Ignored if `leader` is passed. */
+    leaderOptions?: LeaderOptions;
+}
+interface SharedReducer<S, A> {
+    readonly clientId: string;
+    /** Immutable, replaced whenever the value changes. Safe for useSyncExternalStore. */
+    getSnapshot(): S;
+    /**
+     * Apply an action everywhere.
+     *
+     * Applied locally first so the UI does not wait for a round trip, then
+     * proposed to the leader for ordering. If the committed order turns out to
+     * differ from the optimistic one, the local value is rebuilt from the
+     * committed state — so a dispatch can be *seen* out of order for a moment,
+     * but never *settle* out of order.
+     */
+    dispatch(action: A): void;
+    subscribe(fn: () => void): () => void;
+    /**
+     * Number of dispatches from this client that have not yet come back
+     * committed. Zero means this client's view is entirely confirmed.
+     */
+    pendingCount(): number;
+    close(): void;
+}
+
+/**
+ * State that converges by *replaying actions in one order*, rather than by
+ * last-writer-wins on a value.
+ *
+ * ## Why this exists
+ *
+ * `useSharedState`'s convergence rule is last-writer-wins per key, and for a
+ * register — a theme, a selected row, a draft — that is exactly right. For an
+ * *accumulating* write it is exactly wrong, and the README's own counter
+ * example was the proof: two tabs running `set('n', n => n + 1)` at the same
+ * moment both read 4, both write 5, and one increment is silently gone. Nothing
+ * is broken, no error is raised, and the number is simply too small.
+ *
+ * A reducer fixes it by moving what travels. LWW ships the *result* of the
+ * increment, so concurrent results overwrite each other; this ships the
+ * *increment*, and results are computed by every client from the same ordered
+ * list. Two increments are two entries in that list.
+ *
+ * ## How the order is decided
+ *
+ * The leader is the sequencer. A dispatch is broadcast as a `propose`; the
+ * leader stamps it with the next number and broadcasts a `commit`; every client
+ * — the leader included — applies commits strictly in that order. One list, one
+ * order, one answer, for *any* reducer.
+ *
+ * Deliberately not "op-log CRDT for commutative operations", which is cheaper
+ * and needs no leader. That design converges only if the reducer happens to be
+ * commutative, and nothing in a function's type says whether it is. A library
+ * whose rule is that silent divergence is the worst failure mode cannot ship a
+ * primitive whose correctness depends on a property it cannot check.
+ *
+ * ## What it costs
+ *
+ * A dispatch is applied locally at once and reconciled when its commit arrives,
+ * so typing is never gated on the network. If the committed order differs from
+ * the optimistic one, the value is rebuilt from committed state plus whatever
+ * is still pending — visible as a brief correction, never as a wrong result.
+ *
+ * Leadership here inherits leadership's own caveat: it is advisory. In the
+ * moment two tabs both believe they hold the seat, two commits can carry the
+ * same number. The second one to arrive is dropped, and the client asks for a
+ * fresh snapshot rather than guessing — so the outcome is a re-sync, not a
+ * divergence. Anything that must happen exactly once still needs a server.
+ */
+declare function createSharedReducer<S, A>(name: string, reducer: (state: S, action: A) => S, initial: S, options?: SharedReducerOptions): SharedReducer<S, A>;
+
+/**
+ * Everything on the same-origin bus, multiplexed by scope over one
+ * BroadcastChannel per name.
+ *
+ * `v` is the wire protocol version, and changing it is a decision with rules —
+ * see `wire.ts` for what may be added within a version and what must bump it.
+ */
 type BusWire = {
     v: 1;
     scope: 'state';
@@ -128,6 +505,16 @@ type BusWire = {
     type: 'hello' | 'ping' | 'bye';
     clientId: string;
     kind: PeerKind;
+    /**
+     * Whatever this client wants peers to know about it — a display name, a
+     * tab title, a cursor.
+     *
+     * Carried on `hello` only, never on a ping. A ping is a heartbeat and
+     * arrives constantly; attaching metadata to it would re-announce
+     * unchanged data forever and churn every subscriber's roster. Additive
+     * within wire v1: a build that predates it neither sets nor reads it.
+     */
+    metadata?: unknown;
 } | {
     v: 1;
     scope: 'leader';
@@ -142,6 +529,43 @@ type BusWire = {
     term: Version;
     clientId: string;
     kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'op';
+    type: 'hello';
+    key: string;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'op';
+    type: 'propose';
+    key: string;
+    action: unknown;
+    /** Identifies this dispatch across its proposal and its commit, so a commit can be recognised as one's own and applied once. */
+    opId: string;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'op';
+    type: 'commit';
+    key: string;
+    action: unknown;
+    opId: string;
+    /** The leader's ordering decision: a gapless counter every client replays in the same order. */
+    seq: number;
+    clientId: string;
+    kind: PeerKind;
+} | {
+    v: 1;
+    scope: 'op';
+    type: 'snapshot';
+    key: string;
+    state: unknown;
+    seq: number;
+    clientId: string;
+    kind: PeerKind;
 } | {
     v: 1;
     scope: 'event';
@@ -150,6 +574,14 @@ type BusWire = {
     clientId: string;
     kind: PeerKind;
     msgId: string;
+    /**
+     * The `msgId` this is an answer to, when it is one.
+     *
+     * Additive within wire v1: a build that predates `ask` never sets it and
+     * never reads it, so the field is simply absent both ways — which is the
+     * rule for new optional fields (see wire.ts).
+     */
+    replyTo?: string;
 };
 interface BusOptions extends CommonOptions {
     /** Presence heartbeat interval in ms. Default 2000. */
@@ -157,13 +589,40 @@ 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;
+    /**
+     * What to tell peers about this client — a display name, a tab title, a
+     * cursor. Must survive the wire (structured clone), like any payload.
+     */
+    metadata?: unknown;
+    /**
+     * Put this client in its own roster. Default false.
+     *
+     * The default answers "who *else* is here", which is what a presence strip
+     * asks. Turn it on for an avatar list, where leaving yourself out means
+     * every tab renders a different list of the same room.
+     */
+    includeSelf?: boolean;
 }
 interface Presence {
     readonly clientId: string;
     /** Stable array snapshot (replaced on change) — safe for useSyncExternalStore. */
     getPeers(): readonly Peer[];
+    /**
+     * Publish new metadata for this client, announcing it to peers.
+     *
+     * A no-op when the value has not actually changed, so calling it on every
+     * render — which is what a hook does — costs nothing and announces nothing.
+     */
+    setMetadata(metadata: unknown): void;
     subscribe(fn: () => void): () => void;
     close(): void;
 }
@@ -171,40 +630,22 @@ 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;
 
-/**
- * Deliberately extends CommonOptions, not BusOptions: `heartbeatMs` here means
- * 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.
- */
-interface LeaderOptions extends CommonOptions {
-    /** How often the leader re-announces itself, in ms. Default 1000. */
-    heartbeatMs?: number;
-    /** How long a follower tolerates silence before calling the seat empty, in ms. Default 3000. */
-    leaseMs?: number;
-    /** May this client hold the leadership? Default true. */
-    eligible?: boolean;
-}
-interface LeaderSnapshot {
-    /** The current leader's clientId, or null while the seat is empty. */
-    readonly leaderId: string | null;
-    readonly isLeader: boolean;
-}
-interface Leader {
-    readonly clientId: string;
-    /** Frozen; a new object only when the leader actually changes. */
-    getSnapshot(): LeaderSnapshot;
-    subscribe(fn: () => void): () => 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. */
-    setEligible(eligible: boolean): void;
-    close(): void;
-}
-
 /**
  * Elects exactly one client on the bus to hold a seat: the tab that owns the
  * WebSocket, polls, or refreshes the token, while the others stand by.
@@ -220,6 +661,48 @@ interface Leader {
  */
 declare function createLeader(name: string, options?: LeaderOptions): Leader;
 
+/**
+ * How a value becomes text, for the two paths that cannot use structured clone.
+ *
+ * `BroadcastChannel` carries structured clone, so a `Date` arrives a `Date` and
+ * a `Map` a `Map`. The storage-event transport and disk persistence carry
+ * *text*, and JSON is a strictly poorer format: a `Date` comes back a string, a
+ * `Map` comes back `{}`, an `undefined` property is simply gone. Same library,
+ * same call, different answer depending on which transport happened to be
+ * available — which is the kind of difference that is discovered in production.
+ *
+ * The seam exists so the two can be made to agree. It is deliberately *not* a
+ * bundled dependency: `devalue` costs 3.4 kB brotlied and `superjson` 3.6 kB,
+ * against a whole-library budget of 7.3 kB. Charging every user 47% for a
+ * fidelity most of them do not need would be the wrong default. So the default
+ * is JSON — free, and now loud — and anything better is one line away.
+ *
+ * ```ts
+ * import * as devalue from 'devalue';
+ *
+ * localStorageAdapter('settings', {
+ *   serializer: { stringify: devalue.stringify, parse: devalue.parse },
+ * });
+ * ```
+ */
+interface Serializer {
+    stringify(value: unknown): string;
+    parse(text: string): unknown;
+}
+/**
+ * JSON, with silent losses turned into errors.
+ *
+ * Every type below survives `BroadcastChannel` and does not survive JSON, so
+ * without this a value's fate depends on which transport a browser happened to
+ * give you. Refusing is the same call `store.set()` already makes for a value
+ * structured clone rejects: better one actionable error naming the key than two
+ * replicas that quietly disagree.
+ *
+ * `BigInt` and circular references need no check here — `JSON.stringify` throws
+ * on both already. Only the *silent* losses are worth code.
+ */
+declare const jsonSerializer: Serializer;
+
 type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
 interface WebStorageAdapterOptions {
     /**
@@ -229,6 +712,16 @@ interface WebStorageAdapterOptions {
      * not a recovery path. Errors thrown by the callback itself are swallowed.
      */
     onError?: (error: unknown, operation: 'read' | 'write' | 'remove') => void;
+    /**
+     * How values become text. Defaults to JSON, which refuses anything it would
+     * silently change — a `Date`, a `Map`, an `undefined` — rather than write a
+     * value that reads back different.
+     *
+     * Pass devalue or superjson to carry those instead. Not bundled: they cost
+     * 3.4-3.6 kB brotlied against a whole-library budget of 7.3 kB, and most
+     * state is JSON-shaped.
+     */
+    serializer?: Serializer;
 }
 /**
  * Persist to any Storage-shaped thing.
@@ -249,6 +742,47 @@ declare function localStorageAdapter(key: string, options?: WebStorageAdapterOpt
 /** Survives reloads, but dies with the tab. */
 declare function sessionStorageAdapter(key: string, options?: WebStorageAdapterOptions): PersistAdapter;
 
+interface IndexedDbAdapterOptions {
+    /** Database name. Default 'use-everywhere'. */
+    database?: string;
+    /**
+     * Called when an operation fails: blocked storage, a version conflict, a
+     * quota. Persistence stays best-effort either way — this is the
+     * observability seam, not a recovery path.
+     */
+    onError?: (error: unknown, operation: 'read' | 'write' | 'remove') => void;
+}
+/**
+ * Persist to IndexedDB.
+ *
+ * Two things this has that `localStorage` does not.
+ *
+ * **Real fidelity, with no serializer.** IndexedDB stores values with the
+ * structured clone algorithm — the same one `BroadcastChannel` uses — so a
+ * `Date` comes back a `Date` and a `Map` a `Map`, for free. The whole
+ * JSON-degrades-your-types problem the {@link Serializer} seam exists to solve
+ * simply is not present here, and passing a serializer would only reintroduce
+ * it. That makes this the right home for state that is not JSON-shaped.
+ *
+ * **Room.** `localStorage` is a few megabytes per origin and shared with
+ * everything else on it; IndexedDB is orders of magnitude larger.
+ *
+ * And one thing it does not have.
+ *
+ * **A synchronous flush.** `read` is asynchronous, so the store is handed back
+ * before its state arrives — which is exactly the window `store.hydrated` and
+ * `useHydrated` exist to close. Gate first input on one of them, or a keystroke
+ * landing in that window is discarded by last-writer-wins when the restore
+ * lands holding an older but higher-counter value.
+ *
+ * The same asymmetry applies on the way out: a `pagehide` flush cannot be
+ * awaited, so the last debounced write before a tab closes may not land. The
+ * debounce (`persist.debounceMs`, default 100) is the real protection — keep it
+ * short for state you would mind losing, or keep that state in
+ * `localStorageAdapter`, which writes synchronously, and the bulk here.
+ */
+declare function indexedDbAdapter(key: string, options?: IndexedDbAdapterOptions): PersistAdapter;
+
 interface MessageEventLike {
     data: unknown;
     origin: string;
@@ -354,6 +888,55 @@ declare function newer(a: Version, b: Version | undefined): boolean;
  */
 declare const DEFAULT_NAME = "use-everywhere";
 
+/**
+ * Everything a namespace makes, with the prefix already applied.
+ *
+ * The same signatures as the bare factories, minus nothing — a namespace is a
+ * naming decision, not a reduced API.
+ */
+interface Namespace {
+    /** The prefix every name from this namespace carries. */
+    readonly name: string;
+    /** What a bare name becomes here. Exposed so devtools, `observeBus` and tests can name the same bus. */
+    busName(name?: string): string;
+    createSharedStore<S extends Record<string, unknown>>(name: string | undefined, initial: S, options?: SharedStoreOptions<S>): SharedStore<S>;
+    createChannel<M extends MessageMap>(name?: string, options?: ChannelOptions<M>): Channel<M>;
+    createPresence(name?: string, options?: PresenceOptions): Presence;
+    createLeader(name?: string, options?: LeaderOptions): Leader;
+}
+/**
+ * Namespaced factories, so two independently deployed apps on one origin cannot
+ * collide by both taking the defaults.
+ *
+ * Bare names are the problem this solves. A `BroadcastChannel` is global to the
+ * origin, so a name *is* an identity — and two micro-frontends that each call
+ * `createSharedStore('cart', …)`, or each omit the name and land on
+ * {@link DEFAULT_NAME}, are not two carts. They are one cart, with two teams
+ * writing to it, one leader seat contended between them, and one presence roster
+ * counting both. Nothing warns, because from the library's side it looks exactly
+ * like the intended case of two tabs sharing state.
+ *
+ * "Prefix your names" is the workaround, and it fails the way conventions fail:
+ * silently, once, in whichever app forgot.
+ *
+ * ```ts
+ * const checkout = createNamespace('checkout');
+ * const cart = checkout.createSharedStore('cart', { items: [] }); // bus "checkout:cart"
+ * const events = checkout.createChannel('events');               // bus "checkout:events"
+ * ```
+ *
+ * ## What it is not
+ *
+ * Not a security boundary. Everything here is same-origin and a namespace is a
+ * string, so anything on the page can construct the same one deliberately. It
+ * prevents collision, not access — see the security model docs.
+ *
+ * Not related to `wire.scope`, which says *which engine* a wire belongs to, or
+ * to the React package's share scope, which says *how far* a value travels.
+ * Three different axes; this is the one about names.
+ */
+declare function createNamespace(namespace: string): Namespace;
+
 /** One wire crossing the bus, in either direction. */
 interface BusEvent {
     /** The bus name the wire crossed. */
@@ -382,18 +965,71 @@ declare function observeBus(name: string, fn: BusObserver): () => void;
 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.
+ * The wire protocol this build speaks. Stamped as `v` on everything posted, and
+ * required to match on everything received.
+ *
+ * ## The compatibility contract
+ *
+ * Every rolling deploy produces version skew: a tab opened this morning is
+ * still running last week's bundle while the tab opened after lunch is running
+ * today's, and both are on the same origin talking over the same bus. The
+ * contract that makes that safe has two halves.
+ *
+ * **Across versions, partition — loudly.** A wire whose `v` is not this one is
+ * dropped rather than guessed at, because the only thing a build knows about
+ * another protocol version is that it does not know it. Dropping alone would be
+ * the silent-degradation failure this library exists to avoid, so a foreign
+ * version is also recorded on the page ({@link getWireSkew}) and warned about
+ * once in development. The two builds still each work, still each sync with
+ * their own generation, and the fact that they cannot see each other is
+ * *observable* rather than something to be discovered from a bug report.
+ *
+ * **Within a version, evolve additively.** A new `type` on an existing `scope`
+ * may be added without bumping `v`, on one condition: every engine dispatches
+ * on the types it knows and ignores the rest. A build that has never heard of
+ * `state`/`remove` must treat it as nothing, not as a malformed something —
+ * which is why no dispatch here ends in a bare `else`. New *fields* on an
+ * existing type follow the same rule: readers must tolerate their absence,
+ * because half the tabs on the origin were built before the field existed.
+ *
+ * Bump `v` only for a change that breaks those rules — a field whose meaning
+ * changes, a type that stops being sent, a value that stops being comparable.
+ * Bumping is not a failure; it is the honest signal, and it is cheap because
+ * the generations partition cleanly instead of corrupting each other.
  */
+declare const WIRE_VERSION = 1;
+/**
+ * Which foreign wire protocol versions have been heard on a bus, ascending.
+ *
+ * Empty means every peer seen so far speaks {@link WIRE_VERSION} — the normal
+ * case, and the one a deploy should return to once the last stale tab is gone.
+ * A non-empty result means this page is mid-skew and is partitioned from those
+ * peers by design: gate a "reload for the latest version" prompt on it rather
+ * than letting users work in a tab that silently sees half the picture.
+ *
+ * Page-wide and cumulative, like the skew it reports. It counts what was heard,
+ * not what is still out there, so it never un-reports a version — a stale tab
+ * that closes leaves its mark, because the deploy that produced it happened.
+ */
+declare function getWireSkew(name: string): number[];
+
 /**
  * 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);
@@ -407,13 +1043,66 @@ 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;
 }
 
+/**
+ * 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.
+ *    The default serializer therefore *rejects* every value JSON would quietly
+ *    change — a `Date`, a `Map`, a function — rather than let a write appear to
+ *    succeed while peers receive something else. Pass a `Serializer` (devalue,
+ *    superjson) to carry those instead.
+ * 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 onStorage;
+    private seq;
+    private serializer;
+    constructor(name: string, storage?: Storage, serializer?: Serializer);
+    post(data: unknown): void;
+    subscribe(listener: (data: unknown) => void): () => void;
+    close(): void;
+}
+
 declare function isBroadcastChannelAvailable(): boolean;
-/** Default factory: real BroadcastChannel when available, otherwise a local no-op. */
+/**
+ * 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 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, 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, 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 { type AskOptions, BroadcastChannelTransport, type BusEvent, type BusObserver, type BusWire, CID_PARAM, type Channel, type ChannelOptions, type CommonOptions, type ConnectToOpenerOptions, DEFAULT_NAME, type DebugOptions, HandshakeTimeoutError, type IndexedDbAdapterOptions, type InvalidPayload, type Leader, type LeaderOptions, type LeaderSnapshot, type LeaderStrategy, type MessageEventLike, type MessageMap, type MessageMeta, type Namespace, NoopTransport, type OnInvalid, type OnOptions, type OpenWindowOptions, type OpenedWindow, type OpenerConnection, type Peer, type PeerKind, type PersistAdapter, type PersistOptions, type Persisted, type PostOptions, type Presence, type PresenceOptions, type ReplyMap, type RestoreError, type SchemaMap, type SchemaOptions, type Serializer, type SharedReducer, type SharedReducerOptions, type SharedStore, type SharedStoreOptions, type StandardSchemaV1, type StorageLike, StorageTransport, Transport, TransportKind, type Version, WIRE_VERSION, type WebStorageAdapterOptions, WindowClosedError, type WindowEventTarget, type WindowLike, connectToOpener, createChannel, createLeader, createNamespace, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter };