@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/reads/index.d.ts

@@ -0,0 +1,5 @@
+export { useRecordRead, useRecordListRead, applyMutationResult, useRecordStoreSweep } from "./hooks";
+export { acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotDescriptor, type SlotSnapshot, } from "./slots";
+export { optimisticWrite, beginOptimisticWrite, resetOptimisticWrites, type OptimisticHandle, type OptimisticWriteOptions, type OptimisticWriteSpec, } from "./optimistic";
+export { RefetchRunner, reissueMountedReads, registerActiveRead, resetActiveReads, type ActiveRead, type RunnerOptions, } from "./refetch";
+export type { ListFetch, ListFetchResult, ListReadOptions, ListReadResult, ReadError, RecordFetch, RecordReadOptions, RecordReadResult, } from "./types";

package/dist/types/lib/reads/optimistic.d.ts

@@ -0,0 +1,119 @@
+import { type RecordTypeToken, type WriteResult } from "../records";
+import { type SlotDescriptor } from "./slots";
+/** Which records to change, and how. */
+export type OptimisticWriteSpec<T> = {
+    readonly kind: "update";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+    /** Only the fields that change. A present `null` clears; an `undefined` value is ignored. */
+    readonly patch: Partial<T>;
+    readonly at?: undefined;
+} | {
+    readonly kind: "update";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+    /**
+     * A field holding a keyed map (`data_points`, `attributes`): `patch` then names KEYS OF
+     * THAT MAP, merged over whatever it holds. Use it whenever a write changes one entry of a
+     * map — patching the whole field instead would pin every other entry at its value as of
+     * the click, and undoing one of two concurrent writes would undo both.
+     */
+    readonly at: Extract<keyof T, string>;
+    readonly patch: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "create";
+    readonly type: RecordTypeToken<T>;
+    /** The record as the reader will see it until the server answers. Its `id` is assigned. */
+    readonly fields: Partial<T>;
+    /**
+     * Which live list reads show the pending row. Default: every list of this record type —
+     * the library cannot evaluate a server-side filter, so narrow it when a list is filtered.
+     */
+    readonly lists?: (slot: SlotDescriptor) => boolean;
+    /** Above the fetched page (default) or below it. */
+    readonly position?: "start" | "end";
+} | {
+    readonly kind: "delete";
+    readonly type: RecordTypeToken<T>;
+    readonly id: string | number;
+};
+/**
+ * Who stores the answer and what orders it. The two options exclude each other: `answerStored`
+ * says the library never sees the store's verdict on the answer, and `revOrdered` needs it.
+ */
+type AnswerHandling = {
+    /**
+     * The request stores its own answer — an API layer that writes every response into the store,
+     * or a caller that normalizes the answer before storing it. Commit then only retires the belief:
+     * nothing is written, so the stored answer is exactly what shows.
+     */
+    readonly answerStored?: boolean;
+    readonly revOrdered?: undefined;
+} | {
+    readonly answerStored?: undefined;
+    /**
+     * DXUI-96: the server orders every save of this record strictly by version, and every save,
+     * this option or not, answers a versioned row: the record as that save left it, never built
+     * from the record as held. Guarantee 3 is then wrong: a later-sent write can run first, so its
+     * answer can be the older one, and the version alone decides. An update's answer is stored
+     * whole by the store's comparison, whatever a crossing write settled. One refused as older
+     * gives up every field the record holds at or above its version, and the rest of its belief
+     * stays on screen until a read. A later-sent write's answer has already retired an older
+     * belief about its fields, so that older write can have nothing left to keep: if a partial
+     * event then raises the version past its answer, the later write's value shows until a read.
+     * An answer that is not this record's, or carries no version, cannot be ordered: the write is
+     * put back and rejects. A create or a delete has no fields to order and ignores this.
+     */
+    readonly revOrdered: true;
+};
+export type OptimisticWriteOptions<A = unknown> = AnswerHandling & {
+    /**
+     * The field-set tag the server's answer satisfies, as `applyMutationResult` takes it. A
+     * create's answer ALSO satisfies the tag of every list it was shown in, or the real row would
+     * be held but not rendered the moment it replaced the pending one.
+     */
+    readonly tag?: string;
+    /** The tenant the request is issued under. Captured now, never when the answer lands. */
+    readonly tenant?: string | number;
+    /**
+     * Pick the record out of the request's result, when the result is an envelope rather than the
+     * record itself. Default: the result, if it carries `__type` and `id`.
+     */
+    readonly answer?: (result: A) => unknown;
+};
+/** An applied write whose request the caller runs itself — `beginOptimisticWrite`'s handle. */
+export interface OptimisticHandle {
+    /** The record's id — for a create, the temporary one the pending row carries. */
+    readonly id: string | number;
+    /** `Type:id`, as the store keys it. */
+    readonly key: string;
+    /**
+     * The request succeeded. `answer` is the server's record, if it sent one. Idempotent.
+     * `stored` is the result of the `write()` that stored the answer, for a caller that stored it
+     * itself (`answerStored`): a `dropped-older` one keeps the written value on screen.
+     * Under `revOrdered`, an update's `answer` must be its own record's with a version: anything
+     * else puts the write back, as `rollback` does, and throws.
+     */
+    commit(answer?: unknown, stored?: WriteResult): void;
+    /** The request failed: put back exactly what was there before. Idempotent. */
+    rollback(): void;
+}
+/**
+ * Apply an optimistic write and run its request.
+ *
+ * Applies synchronously — before `request` is even called — so the reader sees the change in
+ * the same tick as their click, hidden page or not. On success the server's answer replaces the
+ * belief and the request's own result is returned untouched. On failure the belief is removed
+ * and the error is rethrown for the caller's refusal handling.
+ */
+export declare function optimisticWrite<T, A>(spec: OptimisticWriteSpec<T>, request: () => Promise<A>, options?: OptimisticWriteOptions<A>): Promise<A>;
+/** Every option but `answer`: this caller picks the record out of the result itself. */
+type BeginOptions = AnswerHandling & Pick<OptimisticWriteOptions, "tag" | "tenant">;
+/**
+ * The same write, for a caller that owns its request lifecycle — apply now, and call `commit`
+ * or `rollback` on the handle when the request settles.
+ */
+export declare function beginOptimisticWrite<T>(spec: OptimisticWriteSpec<T>, options?: BeginOptions): OptimisticHandle;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetOptimisticWrites(): void;
+export {};

package/dist/types/lib/reads/refetch.d.ts

@@ -0,0 +1,83 @@
+/**
+ * How many times in a row a read runs again because its answer was refused as older.
+ *
+ * ONE RACE IS SETTLED BY ONE RE-RUN, so a few cover a busy record. A BOUND IS REQUIRED: a server
+ * whose answer stays older than the stored stamp (a clock that disagrees, a wrong stamp) would
+ * otherwise re-run forever, which is polling by accident.
+ */
+export declare const MAX_DROPPED_RERUNS = 3;
+export interface RunnerOptions {
+    readonly minIntervalMs?: number;
+    /** Test seam. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * One read's refetch discipline: a floor between runs, and one request in
+ * flight at a time.
+ *
+ * A SECOND SIGNAL ARRIVING MID-FLIGHT SETS A RE-RUN FLAG rather than issuing a
+ * second request. Two overlapping refetches of the same target are not twice as
+ * fresh; they are two answers racing to write, and the loser can be the newer
+ * one.
+ */
+export declare class RefetchRunner {
+    private readonly run;
+    private inFlight;
+    private rerun;
+    private droppedReruns;
+    private lastFinishedAt;
+    private timer;
+    private disposed;
+    private readonly minIntervalMs;
+    private readonly now;
+    constructor(run: () => Promise<void>, options?: RunnerOptions);
+    /**
+     * Report how the store took this run's answer. A refused one runs again, up to
+     * `MAX_DROPPED_RERUNS` in a row; an accepted one clears the count.
+     *
+     * @returns true when the re-runs are spent and this answer was refused anyway: the caller owes
+     * its reader a loud failure, since the runner will not ask again until the next signal.
+     */
+    answered(droppedOlder: boolean): boolean;
+    /** Ask for a refetch. Respects the floor and the in-flight request. */
+    request(): void;
+    /**
+     * Run now, floor and all.
+     *
+     * For the FIRST fetch and for a key change — neither is a refetch, and making
+     * a fresh screen wait out an interval that exists to damp a broadcast stream
+     * would be the floor working against its own purpose.
+     */
+    runNow(): void;
+    private execute;
+    dispose(): void;
+}
+/** One mounted read, as the driver sees it. */
+export interface ActiveRead {
+    /** The keys this read is responsible for. Re-read per signal: a list's move. */
+    roots(): readonly string[];
+    /** Ask this read to re-issue the request it already made. */
+    request(): void;
+}
+/**
+ * Register a read so staleness and liveness recovery can reach it.
+ *
+ * @returns unregister
+ */
+export declare function registerActiveRead(read: ActiveRead): () => void;
+/**
+ * Events were missed during a window nobody can enumerate: re-issue every
+ * mounted read.
+ *
+ * EVERY MOUNTED READ RE-ISSUES, because "which records changed while we were
+ * not listening" has no answer — the server stopped enqueueing broadcasts and
+ * said nothing about what it dropped. It goes through each read's own runner,
+ * so the floor and the in-flight dedup still apply.
+ *
+ * The library calls this on its realtime epoch. An app with its own transport
+ * (its own stream feeding `write()`) has no epoch to move, so it calls this
+ * itself after its connection drops and comes back.
+ */
+export declare function reissueMountedReads(): void;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetActiveReads(): void;

package/dist/types/lib/reads/slots.d.ts

@@ -0,0 +1,137 @@
+import type { RealtimeEvent, RealtimeScope } from "../realtime";
+export interface SlotSnapshot<T = unknown, TMeta = unknown> {
+    readonly items: readonly T[];
+    readonly pending: readonly T[];
+    readonly pendingCount: number;
+    readonly meta: TMeta | undefined;
+    /** Every key the slot holds, fetched and pending. The refetch roots. */
+    readonly keys: readonly string[];
+}
+/** `getServerSnapshot`, and the answer for a slot nothing has written yet. */
+export declare function emptySlotSnapshot(): SlotSnapshot;
+/** The mark a read takes BEFORE its request goes out; `writeSlot` receives it with the page. */
+export declare function slotAnswerMark(): number;
+/**
+ * Claim a slot for the duration of the returned release.
+ *
+ * REFCOUNTED AND IDEMPOTENT, which is what makes StrictMode's mount / unmount /
+ * mount leave the slot — and its retained keys — exactly as it found them.
+ */
+export declare function acquireSlot(id: string, options: {
+    type: string;
+    tag: string;
+    createdScope?: RealtimeScope;
+}): () => void;
+/**
+ * Replace a slot's membership with a fetch's answer.
+ *
+ * A key that arrived through a `created` event and is now in the fetched page
+ * stops being pending — the fetch has placed it, which is the only thing that
+ * ever could.
+ *
+ * @param settled  the keys that were pending when this fetch was ISSUED
+ *   (`slotPendingKeys`, read before the request). The answer covers them even
+ *   when it does not hold them: a row that sorted onto another page is not
+ *   "new" any more, it is placed — elsewhere. Without this a counted row that
+ *   lands on page 2 stays "1 new" after Show, forever. A key appended after
+ *   the request went out is not in this list, and stays pending.
+ * @param mark  `slotAnswerMark()` read before the request went out. An optimistic create answered
+ *   after it keeps its row though this page lacks it; a call without a mark counts as current.
+ */
+export declare function writeSlot(id: string, keys: readonly string[], meta: unknown, settled?: readonly string[], mark?: number): void;
+/**
+ * Forget what a slot's last answer said about the set (DXUI-87): its `meta`. A team switch empties
+ * the store but not the slot, and a reader that takes `meta` as "this query was answered" would
+ * otherwise draw the old team's totals, or an empty state, over a new team whose read failed.
+ */
+export declare function clearSlotMeta(id: string): void;
+/** The keys a slot is holding as pending right now — what a fetch issued now will settle. */
+export declare function slotPendingKeys(id: string): readonly string[];
+/**
+ * Append a record that entered the set elsewhere, to every slot it belongs to.
+ *
+ * WITH NO POSITION. The server owns sort order and page boundary; a client that
+ * inserts at a guessed index renders a list that is subtly, confidently wrong.
+ *
+ * AND ONLY WHERE IT BELONGS — see `belongsTo`.
+ *
+ * ==== HELD BACK WHILE AN OPTIMISTIC CREATE OF THIS TYPE IS OUTSTANDING (SG-982) ====
+ *
+ * A row the reader just created optimistically has a TEMPORARY key here — the request that will
+ * tell this slot the real one is still in flight. If the server's own `created` broadcast for
+ * that same row reaches this client before that request answers (observed: the broadcast can
+ * easily win the race against the reader's own round trip), it names the REAL key, which this
+ * function cannot recognise as "the row already shown" — the two keys share no characters. Adding
+ * it to `pending` right away would render it as a second row beside the optimistic one for
+ * however long the request takes to settle, which is exactly the transient duplicate this guards
+ * against.
+ *
+ * So while ANY optimistic create for this slot's type is outstanding (`optimisticHead` /
+ * `optimisticTail` non-empty), an incoming `created` key is parked in `awaitingSettle` instead —
+ * neither rendered nor counted — and `settleOptimisticMember` flushes it into `pending` the
+ * instant the slot has no outstanding optimistic create left. If the parked key turns out to BE
+ * the reader's own row, `settleOptimisticMember` already removes it before the flush ever runs
+ * (see its own doc); if it turns out to be someone else's genuinely new row, it reaches `pending`
+ * moments later, no worse than it would have anyway.
+ *
+ * This never suppresses a `created` broadcast outright, and it applies only during a real,
+ * in-progress race — not a guess about which rows might collide, and not a fixed delay.
+ */
+export declare function appendCreated(event: RealtimeEvent): void;
+/** What a create's `lists` predicate is shown about each live slot. */
+export interface SlotDescriptor {
+    /** The list read's own `key`. */
+    readonly id: string;
+    readonly type: string;
+    readonly tag: string;
+}
+/**
+ * Show an optimistic create in every slot that should list it, before the server has answered.
+ *
+ * AN OPTIMISTIC CREATE IS NOT A `created` EVENT, and it does not go into `pending`. `pending` is
+ * the server telling a list "this entered your set, position unknown" and a screen may render it
+ * as a "1 new" affordance; a create is the reader's OWN action, shown inline as a row the moment
+ * it is made. It sits beside the fetched page — above it by default, where a new row is looked
+ * for — in its own list, so a fetch landing while the create is in flight rewrites the page and
+ * leaves the pending row standing. A page row the slot was not already showing is held out of the
+ * render until the create settles (`writeSlot`), since it may be this create's own row.
+ *
+ * WHICH SLOTS is the caller's to say when it can: the library cannot evaluate a server-side
+ * filter, so the default is every live slot of the record's type, and `lists` narrows it.
+ *
+ * @returns the slots the key joined — their tags are what the server's answer must satisfy for
+ *   the real row to render in them.
+ */
+export declare function addOptimisticMember(key: string, type: string, lists: ((slot: SlotDescriptor) => boolean) | undefined, position: "start" | "end"): SlotDescriptor[];
+/**
+ * An optimistic create has settled. With `realKey` (the server answered), the real row takes
+ * the pending row's place — in the fetched page, so it stays put until the server next orders
+ * the list. With `null` (the create failed), the pending row simply goes.
+ *
+ * THE ANSWER IS REMEMBERED (DXUI-82): `answered` keeps `realKey`, so a read issued before this
+ * answer and landing after it cannot take the row away; and `held` page rows show once no create
+ * here is unanswered, whether this one succeeded or failed.
+ *
+ * ALSO THE FLUSH POINT FOR `awaitingSettle` (SG-982): once this slot has no outstanding
+ * optimistic create left, any `created` broadcasts `appendCreated` held back while this one was
+ * in flight are released into `pending` — the race they were parked for is over. `realKey` itself
+ * is removed from that queue first: if it is the reader's own echo, it has just been folded
+ * straight into `keys` above and must never also reach `pending` as a second copy.
+ */
+export declare function settleOptimisticMember(tempKey: string, realKey: string | null): void;
+export declare function subscribeToSlot(id: string, listener: () => void): () => void;
+/** The keys a slot holds right now — the roots a targeted refetch matches on. */
+export declare function slotKeys(id: string): readonly string[];
+/**
+ * The slot's projection, memoized to a stable reference.
+ *
+ * IT RECOMPUTES AND THEN COMPARES rather than trusting its dirty flag, because
+ * a member notification does not always change what this slot renders — a
+ * record whose field-set tag is still unsatisfied moves nothing here — and
+ * handing back a fresh array for an unchanged list re-renders every consumer
+ * for nothing. The elements themselves are the store's own reference-stable
+ * snapshots, so comparing them is one identity check each.
+ */
+export declare function readSlot(id: string): SlotSnapshot;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetSlots(): void;

package/dist/types/lib/reads/types.d.ts

@@ -0,0 +1,155 @@
+import type { RecordPayload, RecordState } from "../records";
+import type { RealtimeScopeInput } from "../realtime";
+/**
+ * A refusal.
+ *
+ * IT LIVES HERE AND NOT IN THE STORE, deliberately. A 404 is not one of the
+ * store's record states, because a refusal carries a message and a remedy the
+ * store has no way to build — so a `404` member there would be permanently
+ * unreachable. It belongs to the layer that performed the request, which is
+ * this one.
+ */
+export interface ReadError {
+    readonly message: string;
+    /** Whatever was thrown. The app's own error wrapper reads it. */
+    readonly cause: unknown;
+    /**
+     * The keys of nested records the store refused as older than a change it already holds, when the
+     * read gave up for that reason (its re-runs spent, DXUI-90); empty for every other failure.
+     */
+    readonly refused: readonly string[];
+}
+/** What a fetch of one record must resolve to: the payload itself. */
+export type RecordFetch = (signal?: AbortSignal) => Promise<RecordPayload>;
+/** What a fetch of a page must resolve to. */
+export interface ListFetchResult<TMeta = unknown> {
+    readonly items: readonly RecordPayload[];
+    /**
+     * Pagination, totals, anything the page carries that is NOT a record.
+     *
+     * IT LIVES IN THE SLOT BECAUSE IT CANNOT LIVE ANYWHERE ELSE. `meta.total` has
+     * no `__type` and no `id`, so it can never be a record — and a normalized
+     * store without a place for it is the half of this design that gets omitted
+     * and then discovered from a screen that cannot render its own page count.
+     */
+    readonly meta?: TMeta;
+}
+export type ListFetch<TMeta = unknown> = (signal?: AbortSignal) => Promise<ListFetchResult<TMeta>>;
+/** Options common to both reads. */
+interface CommonReadOptions {
+    /**
+     * The opaque field-set name this request asks for — `"card"`, `"detail"`,
+     * whatever the app's own api layer already calls its selector.
+     *
+     * The library never interprets it. It is compared for equality and nothing
+     * else, which is what lets `needs` gate a read on a completion the library
+     * cannot compute.
+     */
+    readonly tag: string;
+    /**
+     * The tenant to stamp writes with. Defaults to the store's current tenant,
+     * READ AT REQUEST TIME.
+     *
+     * Request time is the whole point: stamping on ARRIVAL reads the tenant as it
+     * is now, which defeats the check entirely — a team-A response that resolves
+     * after a switch to team B would be stamped B and merged into B's store.
+     */
+    readonly tenant?: string | number;
+    /** Skip the fetch entirely. The read reports `loading: false`. */
+    readonly enabled?: boolean;
+    /**
+     * The floor between two refetches of THIS read. Default 1000ms.
+     *
+     * A TIME FLOOR IS NOT OPTIONAL, and breadth-coalescing alone is not enough:
+     * at least one real broadcast source has no change guard at all and fires on
+     * every related save, so during a long job it is a continuous STREAM rather
+     * than a burst. Without a floor that is one refetch per frame, of whatever
+     * the heaviest read on the screen happens to be.
+     */
+    readonly minRefetchIntervalMs?: number;
+}
+export interface RecordReadOptions extends CommonReadOptions {
+    readonly fetch: RecordFetch;
+}
+export interface ListReadOptions<TMeta = unknown> extends CommonReadOptions {
+    /**
+     * The serialized query — the slot's identity.
+     *
+     * Two components asking the same question share one slot; two different
+     * questions never collide. It is the caller's serialization because only the
+     * caller knows which of its parameters are part of the question.
+     */
+    readonly key: string;
+    readonly fetch: ListFetch<TMeta>;
+    /**
+     * The realtime scope whose `created` events enter this list — normally the
+     * very scope the screen passes to `useRealtime` for this type. Omit it and no
+     * `created` ever appends here.
+     *
+     * WHY A LIST HAS TO SAY THIS. The channel carries every record of the type
+     * for the whole tenant, and the server sends an event there when ANY
+     * subscription on the tenant matched. So "a `created` arrived" never meant
+     * "it matches this list": a queue filtered to schema A counted a demand of
+     * no schema at all because a teammate had an unfiltered list open — observed,
+     * and the reason this replaced a boolean that appended every `created` of the
+     * type to every list that accepted one.
+     *
+     * How membership is decided per scope:
+     *   - `"all"`  — every `created` of the type belongs.
+     *   - ids      — a `created` whose id the list names belongs.
+     *   - `{filter}` — only a `created` the server ATTRIBUTED to this scope
+     *     (`RealtimeEvent.subscriptions`). The transport must implement
+     *     `subscriptionsOf`, and this scope must also be subscribed with
+     *     `useRealtime` — the attribution names this client's own subscriptions,
+     *     so a filter nobody here subscribed to is never named.
+     */
+    readonly createdScope?: RealtimeScopeInput;
+}
+/** The loading / refreshing / error triple, shared by both reads. */
+interface ReadStatus {
+    /** No answer yet AND a fetch is in flight. This is the skeleton. */
+    readonly loading: boolean;
+    /**
+     * An answer is on screen AND a fetch is in flight.
+     *
+     * SEPARATE FROM `loading` ON PURPOSE. Collapsing the two blanks a populated
+     * screen every time anything invalidates — which is exactly what recovering
+     * from staleness by blanking the screen would do, and it is a worse
+     * experience than the staleness.
+     */
+    readonly refreshing: boolean;
+    readonly error: ReadError | undefined;
+    /** Re-issue the request now, subject to the refetch floor. */
+    readonly refetch: () => void;
+}
+export interface RecordReadResult<T> extends ReadStatus {
+    /** The store's answer: `unknown`, `present` or `deleted`. Never a maybe. */
+    readonly state: RecordState<T>;
+    /** `state.record` when present, for the common case. */
+    readonly data: T | undefined;
+}
+export interface ListReadResult<T, TMeta = unknown> extends ReadStatus {
+    /** The fetched page, in the server's order, tombstoned rows removed. */
+    readonly items: readonly T[];
+    /**
+     * Rows that entered the set through a `created` broadcast, in arrival order.
+     *
+     * THEY ARE NOT SPLICED INTO `items`, and that is the honest form of the rule
+     * rather than a limitation: sort position and page boundary are decided by
+     * the server, so guessing where a new row goes is precisely the lie the rule
+     * exists to prevent. A screen renders "N new" and the next fetch places them.
+     */
+    readonly pending: readonly T[];
+    /**
+     * How many rows are waiting, INCLUDING ones not yet renderable.
+     *
+     * THIS IS NOT `pending.length`, and the difference is the whole reason it
+     * exists. A `created` broadcast is partial by whitelist, so it can never
+     * satisfy the field-set tag — meaning the appended record is countable but
+     * not renderable until a fetch fills it in. Reading "N new" off `pending`
+     * would print zero for exactly the case the marker was added to cover.
+     */
+    readonly pendingCount: number;
+    readonly meta: TMeta | undefined;
+}
+export {};

package/dist/types/lib/realtime/hooks.d.ts

@@ -0,0 +1,38 @@
+import type { RecordTypeToken } from "../records";
+import type { RealtimeHealth, RealtimeScopeInput } from "./types";
+/**
+ * Declare that this component is looking at these records and wants these
+ * events.
+ *
+ * COALESCED. Twenty-five components asking for the same scope produce ONE
+ * server-side registration, and the union of everyone's event names is bound —
+ * never the first caller's only, which is the live defect this module was
+ * written against.
+ *
+ * NO-OP WITHOUT A PROVIDER. An application with realtime switched off keeps
+ * fetching and keeps rendering; nothing here throws.
+ *
+ * @param token   the record type, from `defineRecordType`
+ * @param scope   `"all"`, an id list, or `{filter}` the server evaluates
+ * @param events  event names to bind, e.g. `["created", "updated", "deleted"]`
+ */
+export declare function useRealtime<T>(token: RecordTypeToken<T>, scope: RealtimeScopeInput, events: readonly string[]): void;
+/**
+ * The renderable liveness state.
+ *
+ * IT IS RENDERABLE ON PURPOSE. A dead subscription is indistinguishable from a
+ * quiet one, and the prior art's answer — a console panel behind a keyboard
+ * shortcut — is why two real bugs in it went unnoticed for years. This is the
+ * equivalent of `refreshing`: a word the reader can see, not a log line.
+ */
+export declare function useRealtimeHealth(): RealtimeHealth;
+/**
+ * The "you may have missed events" counter, for a consumer that wants to fold
+ * it into its own invalidation rather than use the read binding.
+ *
+ * IT IS A REVISION, NEVER A READ KEY. A key change blanks the screen to a
+ * skeleton; a revision keeps the answer on screen and marks it refreshing. This
+ * signal exists because a subscription went dead and came back — recovering
+ * from that by blanking the screen is a worse experience than the staleness.
+ */
+export declare function useRealtimeEpoch(): number;

package/dist/types/lib/realtime/index.d.ts

@@ -0,0 +1,4 @@
+export { RealtimeProvider, useRealtimeRegistry, type RealtimeProviderProps } from "./provider";
+export { useRealtime, useRealtimeEpoch, useRealtimeHealth } from "./hooks";
+export { SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RegistryOptions, } from "./registry";
+export type { RealtimeChannel, RealtimeConnectionState, RealtimeDiagnostic, RealtimeEvent, RealtimeHealth, RealtimeScope, RealtimeScopeInput, RealtimeStatus, RealtimeTransport, SubscriptionHealth, SubscriptionLease, SubscriptionRequest, } from "./types";

package/dist/types/lib/realtime/provider.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { SubscriptionRegistry, type RegistryOptions } from "./registry";
+export interface RealtimeProviderProps extends Omit<RegistryOptions, "transport" | "tenant" | "now"> {
+    /**
+     * Everything environment-specific in one object: socket, endpoints,
+     * connection observer. INJECTED, never imported — see `types.ts` for why, and
+     * for the one constraint on its implementation that a type cannot express.
+     */
+    readonly transport: RegistryOptions["transport"];
+    /**
+     * The team, org or account these records belong to.
+     *
+     * CHANGING IT IS A REAL EVENT, not a re-render: every server-side
+     * registration is dropped, every channel is left, the record store is
+     * cleared, and everything still mounted re-subscribes under the new tenant.
+     */
+    readonly tenant?: string | number;
+    /**
+     * Whether this provider owns the record store's tenant. Default `true`.
+     *
+     * Set it false only when something else already calls
+     * `setRecordStoreTenant` — two writers of one value is how they disagree.
+     */
+    readonly ownsStoreTenant?: boolean;
+    readonly children: ReactNode;
+}
+export declare function RealtimeProvider({ transport, tenant, ownsStoreTenant, children, ...options }: RealtimeProviderProps): import("react").JSX.Element;
+/**
+ * The registry, or `null` when no provider is mounted.
+ *
+ * THIS PACKAGE'S USUAL CONVENTION IS INVERTED HERE, DELIBERATELY. Every other
+ * provider in this library throws when its hook is used outside it, and that is
+ * right for a capability a component cannot work without. Realtime is not one:
+ * an application with no transport configured must degrade to plain fetching,
+ * never crash. A design system that hard-fails because an OPTIONAL capability
+ * is absent is not offering an optional capability.
+ */
+export declare function useRealtimeRegistry(): SubscriptionRegistry | null;