@danxbot/ui 3.6.1 → 3.8.0

package/dist/types/components/Menu.d.ts

@@ -55,3 +55,36 @@ export declare function MenuGroup({ label, children }: MenuGroupProps): import("
 export declare function MenuSeparator({ className }: {
     className?: string;
 }): import("react").JSX.Element;
+export interface MenuSubProps {
+    /** The row that opens it — reads like a MenuItem and carries a trailing caret. */
+    label: ReactNode;
+    /** Optional leading icon, matching `MenuItem`'s own slot. */
+    icon?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * A nested menu that flies out beside its parent.
+ *
+ * WHY THIS IS A COMPONENT AND NOT A FLAT GROUP. `MenuGroup` renders its items
+ * inline under a label, which is right for two or three related actions and
+ * wrong the moment the group is a SET YOU PICK FROM — teams, workspaces,
+ * projects. Inline, that set pushes every other item down the menu, grows
+ * without bound as the account gains members, and puts a one-of-many choice at
+ * the same visual weight as "Sign out". A submenu keeps the parent menu a fixed
+ * size and says, correctly, that the thing behind this row is a list.
+ *
+ * OPENING IS HOVER *AND* KEYBOARD, which Base UI gives us: pointer-over opens
+ * after its own small delay, ArrowRight/Enter opens from the keyboard, and
+ * ArrowLeft/Escape closes back to the parent. Building this from a nested
+ * `Menu` would lose all of it — an inner Root gets its own trigger semantics
+ * and its own focus scope, so keyboard users end up in a popup the parent does
+ * not know it owns.
+ *
+ * It is positioned `side="right"` with a small negative `alignOffset` so the
+ * first child row sits level with the row that opened it; Base UI flips it to
+ * the left edge on its own when there is no room, which is the case a hard
+ * `left` would get wrong on a narrow window.
+ */
+export declare function MenuSub({ label, icon, disabled, className, children }: MenuSubProps): import("react").JSX.Element;

package/dist/types/components/kanban/KanbanBoard.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import type { DragSessionCallbacks } from "../../lib/dnd";
+import { type DragDropProps } from "../DragDrop";
 import type { KanbanLane, KanbanMove, KanbanRefusal } from "./types";
 export type { KanbanLane, KanbanMove, KanbanRefusal };
 export interface KanbanBoardProps<T> extends Omit<DragSessionCallbacks, "onDragEnd"> {
@@ -40,6 +41,51 @@ export interface KanbanBoardProps<T> extends Omit<DragSessionCallbacks, "onDragE
     onRefuse?: (refusal: KanbanRefusal) => void;
     /** Shown in a lane with no cards. */
     emptyLane?: ReactNode;
+    /**
+     * Override any part of the announcement grammar — `DragDrop.strings`, reached
+     * through the board.
+     *
+     * IT WAS UNREACHABLE, and the omission had a symptom. The default sentence is
+     * `… Position 1 of 4 in ${containerLabel}`, which reads correctly right up
+     * until a lane is called "In review" and a screen reader says "in In review".
+     * That is a property of the lane's NAME rather than of the template, so there
+     * is no template this component could ship that is right for every board —
+     * which is precisely why the engine exposes the grammar, and precisely why a
+     * board that swallowed the prop left its consumer with no way out of a
+     * sentence they could hear was wrong. Rename the lane, or write the sentence:
+     *
+     * ```tsx
+     * strings={{ picked: (c) => `Picked up ${c.label}, ${c.containerLabel} column.` }}
+     * ```
+     */
+    strings?: DragDropProps["strings"];
+    /**
+     * Fill the space between the board's own top and the bottom of whatever
+     * scrolls it, so the lanes are the only thing that scrolls down.
+     *
+     * `true` — the default, and what a board IS. It was not the default until
+     * 3.7.0, and the reason is worth keeping: the height was expressed purely as
+     * a `flex-1 min-h-0` chain, which is correct and is correct only while every
+     * ancestor cooperates. One ordinary page wrapper above the board — a bare
+     * `<div className="flex flex-col gap-10">`, which is this package's own demo
+     * layout — makes `flex-1` inert, the board sizes to its tallest lane, and the
+     * PAGE takes the scrollbar that was supposed to belong to a column. Reported
+     * from a running board: "the columns should fill to the full remaining height
+     * of the page. No scroll bar vertically. Only scroll vertically per column."
+     *
+     * The height is MEASURED (`lib/use-fill-height`), not computed from a token,
+     * and re-measured whenever anything above the board changes size. It is
+     * paired with `max-h-full`, so an ancestor that genuinely does bound the board
+     * still wins and a board in a short box does not overflow it.
+     *
+     * `false` — the board is as tall as the box it is given, or as its tallest
+     * lane if nothing gives it one. For a board deliberately sized by its
+     * container (`h-[60dvh]`, a fixed-height card) or embedded in a page that is
+     * meant to scroll as a document.
+     *
+     * @default true
+     */
+    fill?: boolean;
     className?: string;
 }
-export declare function KanbanBoard<T>({ label, lanes, getItemId, itemLabel, renderItem, renderDragging, onMove, onRefuse, emptyLane, className, ...callbacks }: KanbanBoardProps<T>): import("react").JSX.Element;
+export declare function KanbanBoard<T>({ label, lanes, getItemId, itemLabel, renderItem, renderDragging, onMove, onRefuse, emptyLane, strings, fill, className, ...callbacks }: KanbanBoardProps<T>): import("react").JSX.Element;

package/dist/types/components/kanban/recipe.d.ts

@@ -5,6 +5,14 @@ export declare const kanban: import("tailwind-variants").TVReturnType<{
         };
         false: {};
     };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
 }, {
     root: string;
     lane: string;
@@ -22,6 +30,14 @@ export declare const kanban: import("tailwind-variants").TVReturnType<{
         };
         false: {};
     };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
 }, {
     root: string;
     lane: string;
@@ -39,6 +55,14 @@ export declare const kanban: import("tailwind-variants").TVReturnType<{
         };
         false: {};
     };
+    fill: {
+        true: {
+            root: string;
+        };
+        false: {
+            root: string;
+        };
+    };
 }, {
     root: string;
     lane: string;

package/dist/types/index.d.ts

@@ -28,7 +28,7 @@ export { Checkbox, Switch, Radio, RadioGroup, CheckboxField, SwitchField, RadioF
 export { Dialog, DialogClose, AlertDialog, type DialogProps, type AlertDialogProps, } from "./components/Dialog";
 export { Popover, PopoverClose, Tooltip, TooltipProvider, type PopoverProps, type TooltipProps, } from "./components/Popover";
 export { Toaster, ToastProvider, useToast, type ToasterProps, type ToastProviderProps, type ToastOptions, type ToastTone, } from "./components/Toast";
-export { Menu, MenuItem, MenuGroup, MenuRadioGroup, MenuRadioItem, MenuSeparator, type MenuProps, type MenuItemProps, type MenuGroupProps, type MenuRadioGroupProps, type MenuRadioItemProps, } from "./components/Menu";
+export { Menu, MenuItem, MenuGroup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSub, type MenuProps, type MenuItemProps, type MenuGroupProps, type MenuRadioGroupProps, type MenuRadioItemProps, type MenuSubProps, } from "./components/Menu";
 export { ThemeMenu, type ThemeMenuProps } from "./components/ThemeMenu";
 export { AppShell, type AppShellProps, type NavItem, type NavSection, } from "./components/AppShell";
 export { FileUpload, type FileUploadProps, type UploadFile } from "./components/FileUpload";
@@ -90,6 +90,7 @@ export { ModelSelector, type ModelSelectorProps, type ChatModel, } from "./compo
 export { EffortControl, DEFAULT_EFFORT_LEVELS, type EffortControlProps, type EffortLevel, } from "./components/chat/EffortControl";
 export { ContextMeter, ChatStatus, formatTokens, type ContextMeterProps, type ContextSegment, type UsageLimit, type ChatStatusProps, } from "./components/chat/ContextMeter";
 export { cn } from "./lib/cn";
+export { useFillHeight } from "./lib/use-fill-height";
 export { useTheme, useUiScale, useContrast, useMotionPreference, type Theme, type UiScale, type ContrastPreference, type MotionPreference, } from "./lib/preferences";
 export { usePersistedState, readStored, writeStored, clearStored, storageKey, type PersistedStateOptions, } from "./lib/persist";
 export { CalendarMonth, type CalendarMonthProps } from "./components/calendar/CalendarMonth";
@@ -109,3 +110,6 @@ export { UseCaseCard, RoadmapItemCard, RoadmapSwimlaneBoard, UseCaseLedgerPage,
 export { ProvenanceDisclosure, ProvenanceBadge, ConfidenceMeter, provenanceStateLabel, confidenceBand, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ProvenanceDisclosureProps, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
 export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
+export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
+export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
+export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

package/dist/types/lib/dnd/geometry.d.ts

@@ -21,6 +21,37 @@ export declare function measure(items: Iterable<ItemRegistration>, containers: I
  * the innermost one.
  */
 export declare function containerAt(snapshot: LayoutSnapshot, point: Point): ContainerRect | null;
+/**
+ * The container CLOSEST to the pointer, for a pointer that is inside none of
+ * them.
+ *
+ * THE DEAD ZONE IS THE BUG THIS EXISTS FOR, AND IT IS MOST OF A BOARD. The
+ * registered container is the SCROLLER — it has to be, so auto-scroll can find
+ * its edges — and on a kanban lane the scroller is only the card list. The lane
+ * header above it, the lane's own border, the gutter between two lanes and the
+ * board's bottom padding are all outside every registered rect, so a pointer
+ * there is "over no container" while being unmistakably over a lane to the
+ * person holding the card.
+ *
+ * What used to happen there was `resolveTarget` returning null and the session
+ * keeping the PREVIOUS target — so a card dragged from lane 1 and released on
+ * lane 3's header landed in lane 2, the lane the pointer had last crossed on
+ * its way. Measured in the demo before this change: released at (1022, 419),
+ * visually the middle of "Review" whose lane box is 878–1166 × 407–939, the
+ * card landed in "Building". Not an edge case — the header is 60px of every
+ * lane's top, and a person aiming at an empty lane aims at its label.
+ *
+ * SCOPED, so "nearest" cannot mean "somewhere else entirely": the snapshot
+ * holds one `DragDrop` root's own containers and nothing else — every root
+ * builds its own `DragSession` (`use-drag.ts`) with its own registry. The
+ * nearest container to a point over the sidebar is still a lane of the board
+ * being dragged, which is the only answer a release can sensibly have.
+ *
+ * TIES GO TO THE SMALLER BOX, matching `containerAt` — a point in the gutter
+ * between two lanes is equidistant from both, and a nested container is the
+ * more specific answer for the same reason it is there.
+ */
+export declare function nearestContainer(snapshot: LayoutSnapshot, point: Point): ContainerRect | null;
 /** A container's items in reading order, excluding the one being carried. */
 export declare function remainingItems(snapshot: LayoutSnapshot, container: string, dragged: DragId | null): ItemRect[];
 /**
@@ -41,12 +72,29 @@ export declare function indexAt(snapshot: LayoutSnapshot, container: ContainerRe
 /**
  * Where the dragged item would land if released at `point`.
  *
- * Returns null when the pointer is over no container at all. The session keeps
- * the PREVIOUS target in that case rather than clearing it — dragging a card
- * briefly outside the board should not make the insertion marker vanish, and a
- * release outside every container should still land where the marker last
- * showed. That is the behaviour every board people already use has, and the
- * alternative reads as the drag having silently failed.
+ * THE POINTER IS OVER THE CONTAINER IT IS NEAREST TO, not only the one whose
+ * rectangle happens to hold it. Both halves of that matter and the second one
+ * is the fix:
+ *
+ * The goal has always been that dragging a card briefly outside the board must
+ * not make the insertion marker vanish, and that a release outside every
+ * container still lands somewhere rather than reading as a silently failed
+ * drag. That was served by returning null here and having the session keep the
+ * PREVIOUS target — which achieves "the marker does not blink out" and gets
+ * "lands where you are pointing" exactly backwards. The gap between two lanes,
+ * a lane's header, a lane's border and the board's own bottom padding are all
+ * outside every registered rect; a release in any of them landed the card in
+ * the last lane the pointer had crossed, which for a drag from lane 1 to lane 3
+ * is lane 2. See `nearestContainer` for the measurement.
+ *
+ * Nearest keeps the marker alive for the same reason last-target did, and puts
+ * it where the person is aiming rather than where they have been.
+ *
+ * STILL NULL FOR A BOARD WITH NO CONTAINERS AT ALL — there is no nearest one,
+ * and the session's `?? s.over` remains the guard for that.
+ *
+ * The index then falls out of `indexAt` without a special case: a point above a
+ * lane is before every card in it, a point below is after all of them.
  */
 export declare function resolveTarget(snapshot: LayoutSnapshot, point: Point, dragged: DragId | null): DropTarget | null;
 /** Value equality — targets are recreated on every move, so `===` is useless. */

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

@@ -7,7 +7,7 @@
  * empty icon registry (CAV-11).
  */
 export type { ContainerId, ContainerRect, ContainerRegistration, DragAxis, DragCancelEvent, DragEndEvent, DragId, DragMode, DragPhase, DragSessionCallbacks, DragStartEvent, DragState, DropTarget, ItemRect, ItemRegistration, LayoutSnapshot, Point, } from "./types";
-export { applyMove, containerAt, indexAt, isNoOp, measure, remainingItems, resolveTarget, sameTarget, } from "./geometry";
+export { applyMove, containerAt, indexAt, isNoOp, measure, nearestContainer, remainingItems, resolveTarget, sameTarget, } from "./geometry";
 export { DragSession, type StartArgs } from "./session";
 export { attachPointerSensor, attachSessionWindowListeners, type PointerActivation, type PointerSensorOptions, } from "./sensors/pointer";
 export { attachKeyboardSensor, type KeyboardSensorOptions, } from "./sensors/keyboard";

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

@@ -0,0 +1,49 @@
+import { type RecordPayload, type RecordTypeToken, type WriteResult } from "../records";
+import type { ListReadOptions, ListReadResult, RecordReadOptions, RecordReadResult } from "./types";
+/**
+ * Read one record: fetch it, write it into the store tagged with the field set
+ * it asked for, and return the store's answer.
+ *
+ * `id` may be null for a conditional read — the hook then fetches nothing and
+ * reports `unknown`, rather than forcing a caller around a rule of hooks.
+ */
+export declare function useRecordRead<T>(token: RecordTypeToken<T>, id: string | number | null | undefined, options: RecordReadOptions): RecordReadResult<T>;
+/**
+ * Read a page: fetch it, write every row into the store, and record which keys
+ * answered the query in a LIST SLOT.
+ *
+ * The slot is what makes a `created` broadcast visible and a tombstone
+ * removable without a fetch — and it is where `meta` lives, because pagination
+ * has no identity and can never be a record.
+ */
+export declare function useRecordListRead<T, TMeta = unknown>(token: RecordTypeToken<T>, options: ListReadOptions<TMeta>): ListReadResult<T, TMeta>;
+/**
+ * Write a mutation's returned item into the store.
+ *
+ * A MUTATION RESPONSE IS A FETCH, and this exists because that is a question an
+ * implementer will otherwise answer by coin flip. It is a full server answer to
+ * a request this client made: it may satisfy a field-set tag, it clears
+ * staleness on every field it carries, and it must NEVER be dropped by the
+ * self-echo filter — that filter applies to broadcasts, and dropping a
+ * mutation's own response would discard the server-computed fields the caller
+ * asked for. Structurally it cannot be dropped, because the filter lives on the
+ * broadcast path and this does not go through it.
+ */
+export declare function applyMutationResult(payload: RecordPayload, options: {
+    tag: string;
+    tenant?: string | number;
+}): WriteResult;
+/**
+ * Sweep unreachable records on a bounded schedule, for as long as this is
+ * mounted.
+ *
+ * IT IS A HOOK, NOT AN INTERVAL STARTED ON IMPORT. A design-system module that
+ * schedules work because somebody imported it is a worse defect than the leak
+ * it prevents — it runs in every consumer, including ones with no store at all.
+ * So the library exports the sweep and the CONSUMER decides when: this hook at
+ * an app root, a call at a navigation boundary, or both. A navigation boundary
+ * alone is not enough, because a broadcast can create a key no root reaches and
+ * a screen nobody navigates away from accumulates those for as long as the tab
+ * is open.
+ */
+export declare function useRecordStoreSweep(intervalMs?: number): void;

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

@@ -0,0 +1,4 @@
+export { useRecordRead, useRecordListRead, applyMutationResult, useRecordStoreSweep } from "./hooks";
+export { acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotSnapshot, } from "./slots";
+export { RefetchRunner, 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/refetch.d.ts

@@ -0,0 +1,52 @@
+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 lastFinishedAt;
+    private timer;
+    private disposed;
+    private readonly minIntervalMs;
+    private readonly now;
+    constructor(run: () => Promise<void>, options?: RunnerOptions);
+    /** 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;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetActiveReads(): void;

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

@@ -0,0 +1,52 @@
+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;
+/**
+ * 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;
+    acceptsCreated: boolean;
+}): () => 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.
+ */
+export declare function writeSlot(id: string, keys: readonly string[], meta: unknown): void;
+/**
+ * Append a record that entered the set elsewhere.
+ *
+ * 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.
+ */
+export declare function appendCreatedKey(type: string, key: string): 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,139 @@
+import type { RecordPayload, RecordState } from "../records";
+/**
+ * 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;
+}
+/** 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>;
+    /**
+     * Whether a `created` broadcast for this type may append to this slot.
+     * Default `true`.
+     *
+     * SET IT FALSE FOR A SLOT WHOSE MEMBERSHIP THIS CLIENT CANNOT VERIFY. The
+     * backend evaluates a filter subscription server-side per save, so a
+     * `created` event arriving on such a subscription IS authoritative that the
+     * record matches — but the library cannot tell WHICH of several slots of the
+     * same type it matches when a screen holds more than one differently-filtered
+     * list. Appending to all of them would be a guess; this flag is where the app
+     * says which one owns the event.
+     */
+    readonly acceptsCreated?: boolean;
+}
+/** 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, 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;