use-everywhere 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
-export { BroadcastChannelTransport, BusEvent, BusObserver, BusWire, CID_PARAM, Channel, CommonOptions, ConnectToOpenerOptions, DEFAULT_NAME, DebugOptions, HandshakeTimeoutError, Leader, LeaderOptions, LeaderSnapshot, LeaderStrategy, MessageEventLike, MessageMap, MessageMeta, NoopTransport, OpenWindowOptions, OpenedWindow, OpenerConnection, Peer, PeerKind, PersistAdapter, PersistOptions, Persisted, Presence, PresenceOptions, SharedStore, SharedStoreOptions, StorageLike, StorageTransport, Transport, TransportKind, Version, WebStorageAdapterOptions, WindowClosedError, WindowEventTarget, WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, isBroadcastChannelAvailable, isStorageEventAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, ReplyMap, Channel, MessageMeta, ChannelOptions, PersistAdapter, RestoreError, Peer, LeaderSnapshot, Namespace, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
+export { AskOptions, BroadcastChannelTransport, BusEvent, BusObserver, BusWire, CID_PARAM, Channel, ChannelOptions, CommonOptions, ConnectToOpenerOptions, DEFAULT_NAME, DebugOptions, HandshakeTimeoutError, IndexedDbAdapterOptions, InvalidPayload, Leader, LeaderOptions, LeaderSnapshot, LeaderStrategy, MessageEventLike, MessageMap, MessageMeta, Namespace, NoopTransport, OnInvalid, OnOptions, OpenWindowOptions, OpenedWindow, OpenerConnection, Peer, PeerKind, PersistAdapter, PersistOptions, Persisted, PostOptions, Presence, PresenceOptions, ReplyMap, RestoreError, SchemaMap, SchemaOptions, Serializer, SharedReducer, SharedReducerOptions, SharedStore, SharedStoreOptions, StandardSchemaV1, StorageLike, StorageTransport, Transport, TransportKind, Version, WIRE_VERSION, WebStorageAdapterOptions, WindowClosedError, WindowEventTarget, WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter } from '@use-everywhere/core';
 
 /**
  * How far a shared value travels:
@@ -29,6 +29,92 @@ interface UseSharedStateOptions {
  */
 declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
 
+interface UseSharedReducerOptions {
+    /** Bus name. Default 'use-everywhere'. */
+    name?: string;
+    /** Which reducer this is, when several share a bus. Default 'default'. */
+    key?: string;
+}
+/**
+ * Like `useReducer`, but every tab, window, and worker on this origin applies
+ * the same actions in the same order.
+ *
+ * ```tsx
+ * const [count, dispatch] = useSharedReducer((n, action) => n + action.by, 0);
+ * <button onClick={() => dispatch({ by: 1 })}>{count}</button>;
+ * ```
+ *
+ * Reach for this instead of `useSharedState` whenever a write is *relative to
+ * what is already there* — a counter, a total, a list you append to. Shared
+ * state converges last-writer-wins on the value, so two tabs incrementing at
+ * once both write the same result and one increment vanishes. A reducer sends
+ * the action rather than the result, and two increments are two actions.
+ *
+ * For a plain register — a theme, a selection, a draft — `useSharedState` is
+ * still the right tool and the cheaper one.
+ *
+ * ## The rules
+ *
+ * **Actions must survive the wire.** They are structured-cloned to every peer,
+ * so no functions, no class instances, no DOM nodes.
+ *
+ * **The reducer must be pure**, and it must be the *same* reducer everywhere.
+ * Every client folds the same actions itself; a client whose fold differs gets
+ * a different answer, and nothing can detect that. The first caller's function
+ * is the one used for the life of the page — a re-render passes a new identity
+ * every time, and swapping the fold under a history already applied is exactly
+ * the divergence this exists to prevent.
+ *
+ * **Ordering needs a leader**, which this shares with `useLeader` on the same
+ * bus rather than electing a second one. Before a seat is filled — the first
+ * moments of the first tab — dispatches are held locally and ordered once it
+ * is. They are never lost, only pending.
+ */
+declare function useSharedReducer<S, A>(reducer: (state: S, action: A) => S, initial: S, options?: UseSharedReducerOptions): [S, (action: A) => void];
+
+interface UseSharedSelectorOptions extends UseSharedStateOptions {
+    /**
+     * Whether two selected values count as the same. Default `Object.is`.
+     *
+     * A selector returning an object or array builds a new one every time it
+     * runs, so `Object.is` never matches and the component re-renders on every
+     * write to the store. Pass a shallow comparison for those.
+     */
+    equal?: (a: unknown, b: unknown) => boolean;
+}
+/**
+ * Read a derived value from a shared store, re-rendering only when it changes.
+ *
+ * `useSharedState` subscribes to one key, which is the right shape for reading
+ * one thing. Reading *across* keys meant either one hook per key or a
+ * subscription to the whole store, and the latter re-renders on every write to
+ * anything in it.
+ *
+ * ```tsx
+ * const total = useSharedStore<Cart, number>(
+ *   (cart) => cart.items.length + cart.saved.length,
+ * );
+ * ```
+ *
+ * The selector runs on every store change; the component only re-renders when
+ * its result changes by `equal`.
+ *
+ * ## It reads, it does not declare
+ *
+ * `useSharedState(key, initial)` registers `key` with a default. A selector
+ * does not — it sees whatever is in the store, so a key nothing has registered
+ * or written yet is `undefined`. Write selectors that tolerate that, or declare
+ * the defaults with `useSharedState` (or a store initial) somewhere that
+ * mounts first.
+ *
+ * The same applies on a server, where the store is inert and empty: the
+ * selector runs against `{}`, and its result is what the server-rendered markup
+ * shows.
+ */
+declare function useSharedStore<S extends Record<string, unknown>, T>(selector: (state: S) => T, options?: UseSharedSelectorOptions): T;
+/** Shallow equality over an object or array, for selectors that build one. */
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+
 /** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
 type AnyStore = SharedStore<Record<string, unknown>>;
 
@@ -43,14 +129,41 @@ declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
 declare function getLeader(name: string, options?: LeaderOptions): Leader;
 
 /** Get the page-wide typed channel for `name` (one instance per name). */
-declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
+declare function useChannel<M extends MessageMap, R extends ReplyMap<M> = Record<never, never>>(name: string): Channel<M, R>;
+interface UseMessageOptions {
+    /**
+     * Subscribe at all. Default true.
+     *
+     * `false` unsubscribes rather than filtering inside the handler, so a
+     * component that is not interested costs nothing — and the alternative,
+     * calling the hook conditionally, is not allowed.
+     */
+    enabled?: boolean;
+    /** Unsubscribe after the first message. */
+    once?: boolean;
+}
 /**
  * Subscribe to one message type. The handler is kept fresh without
  * resubscribing, so it may close over render state.
  */
-declare function useMessage<M extends MessageMap, K extends keyof M & string>(channel: Channel<M>, type: K, handler: (payload: M[K], meta: MessageMeta) => void): void;
+declare function useMessage<M extends MessageMap, R extends ReplyMap<M>, K extends keyof M & string>(channel: Channel<M, R>, type: K, handler: (payload: M[K], meta: MessageMeta) => void, options?: UseMessageOptions): void;
+/**
+ * Answer `ask`s of one type for as long as this component is mounted.
+ *
+ * A hook rather than a bare `channel.answer` call because a responder is a
+ * subscription: registering one in a render would leave the last unmounted
+ * component answering for the page.
+ *
+ * One responder per type per channel — registering a second replaces the first,
+ * which is the same first-wins-then-replace rule `answer` has in core.
+ */
+declare function useAnswer<M extends MessageMap, R extends ReplyMap<M>, K extends keyof M & keyof R & string>(channel: Channel<M, R>, type: K, responder: (payload: M[K], meta: MessageMeta) => R[K], options?: {
+    enabled?: boolean;
+}): void;
 /** The channel's post function (stable identity per channel). */
-declare function useSend<M extends MessageMap>(channel: Channel<M>): Channel<M>['post'];
+declare function useSend<M extends MessageMap, R extends ReplyMap<M>>(channel: Channel<M, R>): Channel<M, R>['post'];
+/** The channel's ask function (stable identity per channel). */
+declare function useAsk<M extends MessageMap, R extends ReplyMap<M>>(channel: Channel<M, R>): Channel<M, R>['ask'];
 
 /** A channel bound to a name and message map: typed hooks with no per-call generics. */
 interface ChannelHooks<M extends MessageMap> {
@@ -70,8 +183,11 @@ interface ChannelHooks<M extends MessageMap> {
  * typed hooks back. Sugar over useChannel/useMessage/useSend — the same
  * page-wide channel singleton is shared, so mixing bound and standalone
  * hooks for one name is safe.
+ *
+ * Options are registered here and applied when the channel is first needed, so
+ * declaring a `schema` at module scope still constructs nothing on import.
  */
-declare function defineChannel<M extends MessageMap>(name: string): ChannelHooks<M>;
+declare function defineChannel<M extends MessageMap>(name: string, options?: ChannelOptions<M>): ChannelHooks<M>;
 
 interface DefineStoreOptions {
     /** Restore this store from disk on first use, and write it back as it changes. */
@@ -80,6 +196,16 @@ interface DefineStoreOptions {
     persistKeys?: string[];
     /** Coalesce disk writes for this long. Default 100. */
     persistDebounceMs?: number;
+    /**
+     * The version of your persisted state's shape. Bump it whenever a key changes
+     * meaning or type, and supply `migrate` to carry old data forward. Default 0,
+     * which is also what anything written before this existed reads as.
+     */
+    persistVersion?: number;
+    /** Bring persisted state written at an older `persistVersion` up to the current one. */
+    migrate?: (state: Record<string, unknown>, from: number) => Record<string, unknown>;
+    /** Called when persisted state is refused instead of restored. Defaults to a development warning. */
+    onRestoreError?: (error: RestoreError) => void;
     /** How far this store is shared. Default 'everywhere'. */
     scope?: ShareScope;
 }
@@ -106,10 +232,25 @@ interface StoreHooks<S extends Record<string, unknown>> {
  */
 declare function defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
 
-/** The other tabs/windows/workers currently alive on this origin. */
-declare function usePeers(options?: {
+interface UsePeersOptions {
+    /** Bus name. Default 'use-everywhere'. */
     name?: string;
-}): readonly Peer[];
+    /**
+     * Include this client in the list. 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;
+}
+/**
+ * The tabs/windows/workers currently alive on this origin.
+ *
+ * Each peer carries whatever it published about itself as `metadata` — see
+ * {@link usePresenceMetadata} for publishing this client's.
+ */
+declare function usePeers(options?: UsePeersOptions): readonly Peer[];
 /**
  * This client's own id on the presence bus (matches patch origin ids).
  *
@@ -123,6 +264,51 @@ declare function usePeers(options?: {
 declare function useClientId(options?: {
     name?: string;
 }): string;
+/**
+ * Publish what this client wants peers to know about it — a display name, a tab
+ * title, a cursor.
+ *
+ * Safe to call with a fresh object every render: the value is compared by
+ * contents, so an unchanged one announces nothing and re-renders nobody.
+ *
+ * ```tsx
+ * usePresenceMetadata({ name: user.name, editing: currentDocId });
+ * ```
+ *
+ * Published in an effect rather than during render, because announcing is a
+ * side effect on every other tab — and a render that React throws away must not
+ * be one other tabs already saw.
+ */
+declare function usePresenceMetadata(metadata: unknown, options?: UsePeersOptions): void;
+
+/**
+ * Whether a persisted store has finished restoring.
+ *
+ * `false` on the first render, then `true` once the restore lands — including
+ * the cases where there is nothing to restore, which settle immediately.
+ *
+ * Deliberately `false` first even for a synchronous adapter that has already
+ * finished. The alternative is a value that differs between the server render
+ * and the browser's hydrating render, which is a hydration mismatch on every
+ * app that uses it — the same reason `useClientId` reports `''` until the
+ * commit after hydration.
+ *
+ * The gap this closes only exists for **async** adapters, and it is one
+ * last-writer-wins makes invisible: a keystroke landing before the restore
+ * writes at counter 1, the restore arrives holding counter 5, and the newer
+ * keystroke is correctly discarded. The behaviour is right; the surprise is
+ * total. Gate the input and there is no gap:
+ *
+ * ```tsx
+ * const ready = useHydrated({ store: 'settings' });
+ * return <input disabled={!ready} value={draft} onChange={…} />;
+ * ```
+ *
+ * A synchronous adapter — `localStorageAdapter` and friends — has already
+ * restored by the time the store is handed back, so there is no gap to guard
+ * and this simply flips to `true` in the commit after mount.
+ */
+declare function useHydrated(options?: UseSharedStateOptions): boolean;
 
 interface UseLeaderOptions extends LeaderOptions {
     /** Which bus to elect on. Defaults to the shared default name. */
@@ -143,6 +329,52 @@ declare function useIsLeader(options?: UseLeaderOptions): boolean;
  */
 declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
 
+/**
+ * The React half of a namespace: the same hooks, with every bus name prefixed.
+ *
+ * Options keep their meaning — `store` and `name` are still relative names, and
+ * `scope` still says how far a value travels, which is a different axis from
+ * which namespace it lives in.
+ */
+interface ReactNamespace extends Namespace {
+    defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
+    defineChannel<M extends MessageMap>(name?: string, options?: ChannelOptions<M>): ChannelHooks<M>;
+    getSharedStore(name?: string, scope?: UseSharedStateOptions['scope']): AnyStore;
+    useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
+    useSharedStore<S extends Record<string, unknown>, T>(selector: (state: S) => T, options?: UseSharedSelectorOptions): T;
+    usePeers(options?: UsePeersOptions): readonly Peer[];
+    usePresenceMetadata(metadata: unknown, options?: UsePeersOptions): void;
+    useHydrated(options?: UseSharedStateOptions): boolean;
+    useClientId(options?: {
+        name?: string;
+    }): string;
+    useLeader(options?: UseLeaderOptions): LeaderSnapshot;
+    useIsLeader(options?: UseLeaderOptions): boolean;
+    useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
+}
+/**
+ * Namespaced hooks and factories, so two independently deployed apps on one
+ * origin cannot collide by both taking the defaults.
+ *
+ * ```ts
+ * // checkout/bus.ts
+ * export const checkout = createNamespace('checkout');
+ *
+ * // anywhere in the checkout app
+ * const [items, setItems] = checkout.useSharedState('items', []);
+ * ```
+ *
+ * Call it **at module scope**, like `defineStore` and `defineChannel`. It
+ * builds a small object of bound functions, and rebuilding that on every render
+ * would hand React a new `useSharedState` identity each time — harmless for the
+ * hooks themselves, which key off the bus name, but pointless work and a
+ * confusing thing to see in a profile.
+ *
+ * See the core `createNamespace` for what a namespace does and does not
+ * guarantee. In short: it prevents collision, not access.
+ */
+declare function createNamespace(namespace: string): ReactNamespace;
+
 type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
 /**
  * The flow's state as a discriminated union, so `status` narrows `result` and
@@ -199,4 +431,4 @@ type UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> = OpenedW
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ReactNamespace, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseMessageOptions, type UseOpenedWindow, type UsePeersOptions, type UseSharedReducerOptions, type UseSharedSelectorOptions, type UseSharedStateOptions, createNamespace, defineChannel, defineStore, getLeader, getSharedStore, shallowEqual, useAnswer, useAsk, useChannel, useClientId, useHydrated, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, usePresenceMetadata, useSend, useSharedReducer, useSharedState, useSharedStore };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { SharedStore, LeaderOptions, Leader, MessageMap, Channel, MessageMeta, PersistAdapter, Peer, LeaderSnapshot, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
-export { BroadcastChannelTransport, BusEvent, BusObserver, BusWire, CID_PARAM, Channel, CommonOptions, ConnectToOpenerOptions, DEFAULT_NAME, DebugOptions, HandshakeTimeoutError, Leader, LeaderOptions, LeaderSnapshot, LeaderStrategy, MessageEventLike, MessageMap, MessageMeta, NoopTransport, OpenWindowOptions, OpenedWindow, OpenerConnection, Peer, PeerKind, PersistAdapter, PersistOptions, Persisted, Presence, PresenceOptions, SharedStore, SharedStoreOptions, StorageLike, StorageTransport, Transport, TransportKind, Version, WebStorageAdapterOptions, WindowClosedError, WindowEventTarget, WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, isBroadcastChannelAvailable, isStorageEventAvailable, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter } from '@use-everywhere/core';
+import { SharedStore, LeaderOptions, Leader, MessageMap, ReplyMap, Channel, MessageMeta, ChannelOptions, PersistAdapter, RestoreError, Peer, LeaderSnapshot, Namespace, OpenedWindow, WindowClosedError } from '@use-everywhere/core';
+export { AskOptions, BroadcastChannelTransport, BusEvent, BusObserver, BusWire, CID_PARAM, Channel, ChannelOptions, CommonOptions, ConnectToOpenerOptions, DEFAULT_NAME, DebugOptions, HandshakeTimeoutError, IndexedDbAdapterOptions, InvalidPayload, Leader, LeaderOptions, LeaderSnapshot, LeaderStrategy, MessageEventLike, MessageMap, MessageMeta, Namespace, NoopTransport, OnInvalid, OnOptions, OpenWindowOptions, OpenedWindow, OpenerConnection, Peer, PeerKind, PersistAdapter, PersistOptions, Persisted, PostOptions, Presence, PresenceOptions, ReplyMap, RestoreError, SchemaMap, SchemaOptions, Serializer, SharedReducer, SharedReducerOptions, SharedStore, SharedStoreOptions, StandardSchemaV1, StorageLike, StorageTransport, Transport, TransportKind, Version, WIRE_VERSION, WebStorageAdapterOptions, WindowClosedError, WindowEventTarget, WindowLike, connectToOpener, createChannel, createLeader, createPresence, createSharedReducer, createSharedStore, defaultTransport, enableDebug, getBusNames, getTransportKind, getWireSkew, indexedDbAdapter, isBroadcastChannelAvailable, isStorageEventAvailable, jsonSerializer, localStorageAdapter, newer, observeBus, openWindow, sessionStorageAdapter, webStorageAdapter } from '@use-everywhere/core';
 
 /**
  * How far a shared value travels:
@@ -29,6 +29,92 @@ interface UseSharedStateOptions {
  */
 declare function useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
 
+interface UseSharedReducerOptions {
+    /** Bus name. Default 'use-everywhere'. */
+    name?: string;
+    /** Which reducer this is, when several share a bus. Default 'default'. */
+    key?: string;
+}
+/**
+ * Like `useReducer`, but every tab, window, and worker on this origin applies
+ * the same actions in the same order.
+ *
+ * ```tsx
+ * const [count, dispatch] = useSharedReducer((n, action) => n + action.by, 0);
+ * <button onClick={() => dispatch({ by: 1 })}>{count}</button>;
+ * ```
+ *
+ * Reach for this instead of `useSharedState` whenever a write is *relative to
+ * what is already there* — a counter, a total, a list you append to. Shared
+ * state converges last-writer-wins on the value, so two tabs incrementing at
+ * once both write the same result and one increment vanishes. A reducer sends
+ * the action rather than the result, and two increments are two actions.
+ *
+ * For a plain register — a theme, a selection, a draft — `useSharedState` is
+ * still the right tool and the cheaper one.
+ *
+ * ## The rules
+ *
+ * **Actions must survive the wire.** They are structured-cloned to every peer,
+ * so no functions, no class instances, no DOM nodes.
+ *
+ * **The reducer must be pure**, and it must be the *same* reducer everywhere.
+ * Every client folds the same actions itself; a client whose fold differs gets
+ * a different answer, and nothing can detect that. The first caller's function
+ * is the one used for the life of the page — a re-render passes a new identity
+ * every time, and swapping the fold under a history already applied is exactly
+ * the divergence this exists to prevent.
+ *
+ * **Ordering needs a leader**, which this shares with `useLeader` on the same
+ * bus rather than electing a second one. Before a seat is filled — the first
+ * moments of the first tab — dispatches are held locally and ordered once it
+ * is. They are never lost, only pending.
+ */
+declare function useSharedReducer<S, A>(reducer: (state: S, action: A) => S, initial: S, options?: UseSharedReducerOptions): [S, (action: A) => void];
+
+interface UseSharedSelectorOptions extends UseSharedStateOptions {
+    /**
+     * Whether two selected values count as the same. Default `Object.is`.
+     *
+     * A selector returning an object or array builds a new one every time it
+     * runs, so `Object.is` never matches and the component re-renders on every
+     * write to the store. Pass a shallow comparison for those.
+     */
+    equal?: (a: unknown, b: unknown) => boolean;
+}
+/**
+ * Read a derived value from a shared store, re-rendering only when it changes.
+ *
+ * `useSharedState` subscribes to one key, which is the right shape for reading
+ * one thing. Reading *across* keys meant either one hook per key or a
+ * subscription to the whole store, and the latter re-renders on every write to
+ * anything in it.
+ *
+ * ```tsx
+ * const total = useSharedStore<Cart, number>(
+ *   (cart) => cart.items.length + cart.saved.length,
+ * );
+ * ```
+ *
+ * The selector runs on every store change; the component only re-renders when
+ * its result changes by `equal`.
+ *
+ * ## It reads, it does not declare
+ *
+ * `useSharedState(key, initial)` registers `key` with a default. A selector
+ * does not — it sees whatever is in the store, so a key nothing has registered
+ * or written yet is `undefined`. Write selectors that tolerate that, or declare
+ * the defaults with `useSharedState` (or a store initial) somewhere that
+ * mounts first.
+ *
+ * The same applies on a server, where the store is inert and empty: the
+ * selector runs against `{}`, and its result is what the server-rendered markup
+ * shows.
+ */
+declare function useSharedStore<S extends Record<string, unknown>, T>(selector: (state: S) => T, options?: UseSharedSelectorOptions): T;
+/** Shallow equality over an object or array, for selectors that build one. */
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+
 /** Registry stores hold arbitrary keys — shape is decided by the hooks using them. */
 type AnyStore = SharedStore<Record<string, unknown>>;
 
@@ -43,14 +129,41 @@ declare function getSharedStore(name?: string, scope?: ShareScope): AnyStore;
 declare function getLeader(name: string, options?: LeaderOptions): Leader;
 
 /** Get the page-wide typed channel for `name` (one instance per name). */
-declare function useChannel<M extends MessageMap>(name: string): Channel<M>;
+declare function useChannel<M extends MessageMap, R extends ReplyMap<M> = Record<never, never>>(name: string): Channel<M, R>;
+interface UseMessageOptions {
+    /**
+     * Subscribe at all. Default true.
+     *
+     * `false` unsubscribes rather than filtering inside the handler, so a
+     * component that is not interested costs nothing — and the alternative,
+     * calling the hook conditionally, is not allowed.
+     */
+    enabled?: boolean;
+    /** Unsubscribe after the first message. */
+    once?: boolean;
+}
 /**
  * Subscribe to one message type. The handler is kept fresh without
  * resubscribing, so it may close over render state.
  */
-declare function useMessage<M extends MessageMap, K extends keyof M & string>(channel: Channel<M>, type: K, handler: (payload: M[K], meta: MessageMeta) => void): void;
+declare function useMessage<M extends MessageMap, R extends ReplyMap<M>, K extends keyof M & string>(channel: Channel<M, R>, type: K, handler: (payload: M[K], meta: MessageMeta) => void, options?: UseMessageOptions): void;
+/**
+ * Answer `ask`s of one type for as long as this component is mounted.
+ *
+ * A hook rather than a bare `channel.answer` call because a responder is a
+ * subscription: registering one in a render would leave the last unmounted
+ * component answering for the page.
+ *
+ * One responder per type per channel — registering a second replaces the first,
+ * which is the same first-wins-then-replace rule `answer` has in core.
+ */
+declare function useAnswer<M extends MessageMap, R extends ReplyMap<M>, K extends keyof M & keyof R & string>(channel: Channel<M, R>, type: K, responder: (payload: M[K], meta: MessageMeta) => R[K], options?: {
+    enabled?: boolean;
+}): void;
 /** The channel's post function (stable identity per channel). */
-declare function useSend<M extends MessageMap>(channel: Channel<M>): Channel<M>['post'];
+declare function useSend<M extends MessageMap, R extends ReplyMap<M>>(channel: Channel<M, R>): Channel<M, R>['post'];
+/** The channel's ask function (stable identity per channel). */
+declare function useAsk<M extends MessageMap, R extends ReplyMap<M>>(channel: Channel<M, R>): Channel<M, R>['ask'];
 
 /** A channel bound to a name and message map: typed hooks with no per-call generics. */
 interface ChannelHooks<M extends MessageMap> {
@@ -70,8 +183,11 @@ interface ChannelHooks<M extends MessageMap> {
  * typed hooks back. Sugar over useChannel/useMessage/useSend — the same
  * page-wide channel singleton is shared, so mixing bound and standalone
  * hooks for one name is safe.
+ *
+ * Options are registered here and applied when the channel is first needed, so
+ * declaring a `schema` at module scope still constructs nothing on import.
  */
-declare function defineChannel<M extends MessageMap>(name: string): ChannelHooks<M>;
+declare function defineChannel<M extends MessageMap>(name: string, options?: ChannelOptions<M>): ChannelHooks<M>;
 
 interface DefineStoreOptions {
     /** Restore this store from disk on first use, and write it back as it changes. */
@@ -80,6 +196,16 @@ interface DefineStoreOptions {
     persistKeys?: string[];
     /** Coalesce disk writes for this long. Default 100. */
     persistDebounceMs?: number;
+    /**
+     * The version of your persisted state's shape. Bump it whenever a key changes
+     * meaning or type, and supply `migrate` to carry old data forward. Default 0,
+     * which is also what anything written before this existed reads as.
+     */
+    persistVersion?: number;
+    /** Bring persisted state written at an older `persistVersion` up to the current one. */
+    migrate?: (state: Record<string, unknown>, from: number) => Record<string, unknown>;
+    /** Called when persisted state is refused instead of restored. Defaults to a development warning. */
+    onRestoreError?: (error: RestoreError) => void;
     /** How far this store is shared. Default 'everywhere'. */
     scope?: ShareScope;
 }
@@ -106,10 +232,25 @@ interface StoreHooks<S extends Record<string, unknown>> {
  */
 declare function defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
 
-/** The other tabs/windows/workers currently alive on this origin. */
-declare function usePeers(options?: {
+interface UsePeersOptions {
+    /** Bus name. Default 'use-everywhere'. */
     name?: string;
-}): readonly Peer[];
+    /**
+     * Include this client in the list. 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;
+}
+/**
+ * The tabs/windows/workers currently alive on this origin.
+ *
+ * Each peer carries whatever it published about itself as `metadata` — see
+ * {@link usePresenceMetadata} for publishing this client's.
+ */
+declare function usePeers(options?: UsePeersOptions): readonly Peer[];
 /**
  * This client's own id on the presence bus (matches patch origin ids).
  *
@@ -123,6 +264,51 @@ declare function usePeers(options?: {
 declare function useClientId(options?: {
     name?: string;
 }): string;
+/**
+ * Publish what this client wants peers to know about it — a display name, a tab
+ * title, a cursor.
+ *
+ * Safe to call with a fresh object every render: the value is compared by
+ * contents, so an unchanged one announces nothing and re-renders nobody.
+ *
+ * ```tsx
+ * usePresenceMetadata({ name: user.name, editing: currentDocId });
+ * ```
+ *
+ * Published in an effect rather than during render, because announcing is a
+ * side effect on every other tab — and a render that React throws away must not
+ * be one other tabs already saw.
+ */
+declare function usePresenceMetadata(metadata: unknown, options?: UsePeersOptions): void;
+
+/**
+ * Whether a persisted store has finished restoring.
+ *
+ * `false` on the first render, then `true` once the restore lands — including
+ * the cases where there is nothing to restore, which settle immediately.
+ *
+ * Deliberately `false` first even for a synchronous adapter that has already
+ * finished. The alternative is a value that differs between the server render
+ * and the browser's hydrating render, which is a hydration mismatch on every
+ * app that uses it — the same reason `useClientId` reports `''` until the
+ * commit after hydration.
+ *
+ * The gap this closes only exists for **async** adapters, and it is one
+ * last-writer-wins makes invisible: a keystroke landing before the restore
+ * writes at counter 1, the restore arrives holding counter 5, and the newer
+ * keystroke is correctly discarded. The behaviour is right; the surprise is
+ * total. Gate the input and there is no gap:
+ *
+ * ```tsx
+ * const ready = useHydrated({ store: 'settings' });
+ * return <input disabled={!ready} value={draft} onChange={…} />;
+ * ```
+ *
+ * A synchronous adapter — `localStorageAdapter` and friends — has already
+ * restored by the time the store is handed back, so there is no gap to guard
+ * and this simply flips to `true` in the commit after mount.
+ */
+declare function useHydrated(options?: UseSharedStateOptions): boolean;
 
 interface UseLeaderOptions extends LeaderOptions {
     /** Which bus to elect on. Defaults to the shared default name. */
@@ -143,6 +329,52 @@ declare function useIsLeader(options?: UseLeaderOptions): boolean;
  */
 declare function useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
 
+/**
+ * The React half of a namespace: the same hooks, with every bus name prefixed.
+ *
+ * Options keep their meaning — `store` and `name` are still relative names, and
+ * `scope` still says how far a value travels, which is a different axis from
+ * which namespace it lives in.
+ */
+interface ReactNamespace extends Namespace {
+    defineStore<S extends Record<string, unknown> = Record<string, unknown>>(name: string, options?: DefineStoreOptions): StoreHooks<S>;
+    defineChannel<M extends MessageMap>(name?: string, options?: ChannelOptions<M>): ChannelHooks<M>;
+    getSharedStore(name?: string, scope?: UseSharedStateOptions['scope']): AnyStore;
+    useSharedState<T>(key: string, initial: T, options?: UseSharedStateOptions): [T, (next: T | ((prev: T) => T)) => void];
+    useSharedStore<S extends Record<string, unknown>, T>(selector: (state: S) => T, options?: UseSharedSelectorOptions): T;
+    usePeers(options?: UsePeersOptions): readonly Peer[];
+    usePresenceMetadata(metadata: unknown, options?: UsePeersOptions): void;
+    useHydrated(options?: UseSharedStateOptions): boolean;
+    useClientId(options?: {
+        name?: string;
+    }): string;
+    useLeader(options?: UseLeaderOptions): LeaderSnapshot;
+    useIsLeader(options?: UseLeaderOptions): boolean;
+    useLeaderEffect(effect: () => void | (() => void), options?: UseLeaderOptions): void;
+}
+/**
+ * Namespaced hooks and factories, so two independently deployed apps on one
+ * origin cannot collide by both taking the defaults.
+ *
+ * ```ts
+ * // checkout/bus.ts
+ * export const checkout = createNamespace('checkout');
+ *
+ * // anywhere in the checkout app
+ * const [items, setItems] = checkout.useSharedState('items', []);
+ * ```
+ *
+ * Call it **at module scope**, like `defineStore` and `defineChannel`. It
+ * builds a small object of bound functions, and rebuilding that on every render
+ * would hand React a new `useSharedState` identity each time — harmless for the
+ * hooks themselves, which key off the bus name, but pointless work and a
+ * confusing thing to see in a profile.
+ *
+ * See the core `createNamespace` for what a namespace does and does not
+ * guarantee. In short: it prevents collision, not access.
+ */
+declare function createNamespace(namespace: string): ReactNamespace;
+
 type OpenedWindowStatus = 'idle' | 'opening' | 'connected' | 'done' | 'closed-early' | 'error';
 /**
  * The flow's state as a discriminated union, so `status` narrows `result` and
@@ -199,4 +431,4 @@ type UseOpenedWindow<Out extends MessageMap, In extends MessageMap, R> = OpenedW
  */
 declare function useOpenedWindow<Out extends MessageMap, In extends MessageMap, R = unknown>(factory: () => OpenedWindow<Out, In, R>): UseOpenedWindow<Out, In, R>;
 
-export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseOpenedWindow, type UseSharedStateOptions, defineChannel, defineStore, getLeader, getSharedStore, useChannel, useClientId, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, useSend, useSharedState };
+export { type AnyStore, type ChannelHooks, type DefineStoreOptions, type OpenedWindowControls, type OpenedWindowState, type OpenedWindowStatus, type ReactNamespace, type ShareScope, type StoreHooks, type UseLeaderOptions, type UseMessageOptions, type UseOpenedWindow, type UsePeersOptions, type UseSharedReducerOptions, type UseSharedSelectorOptions, type UseSharedStateOptions, createNamespace, defineChannel, defineStore, getLeader, getSharedStore, shallowEqual, useAnswer, useAsk, useChannel, useClientId, useHydrated, useIsLeader, useLeader, useLeaderEffect, useMessage, useOpenedWindow, usePeers, usePresenceMetadata, useSend, useSharedReducer, useSharedState, useSharedStore };