@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/paged-window/store.d.ts

@@ -0,0 +1,307 @@
+import { type PagedWindowRecordsOptions } from "./records-binding";
+export type { PagedWindowRecordsOptions, PlacementEdges } from "./records-binding";
+export interface PageResponse<T> {
+    /** This page's items, in order. Fewer than `pageSize` only for the last page. */
+    items: readonly T[];
+    /** The WHOLE list's length right now. Every response refreshes it. */
+    total: number;
+}
+export interface LoadPageContext {
+    /** Aborted when the page is dropped, re-requested or the window is reset. */
+    signal: AbortSignal;
+}
+export type LoadPage<T> = (page: number, context: LoadPageContext) => Promise<PageResponse<T>>;
+/** Answers the list's length alone — no items. What a hidden (`count` mode) lane asks. */
+export type LoadCount = (context: LoadPageContext) => Promise<number>;
+export type PagedWindowMode = "pages" | "count";
+/** How long the viewer's page must stay put before the window moves to it, in ms. */
+export declare const PAGED_WINDOW_SETTLE_MS = 200;
+export type PageStatus = "loading" | "ready" | "error";
+export interface PageSnapshot<T> {
+    page: number;
+    status: PageStatus;
+    /**
+     * Empty unless `ready`. A page being re-read keeps its old items and stays `ready`, less any row a page with current rows also holds: one
+     * key is never on two pages (DX-5521).
+     */
+    items: readonly T[];
+    /** True while a `ready` page is being re-read in place. */
+    refreshing: boolean;
+    /** What the load rejected with. Only on `error`. */
+    error: unknown;
+    /** Part of the loaded run — its items are in `items`. A ready page past a hole is not, until the hole closes. */
+    shown: boolean;
+}
+export interface PagedWindowSnapshot<T> {
+    mode: PagedWindowMode;
+    /** The list's length as the latest response reported it; null before the first. */
+    total: number | null;
+    pageSize: number;
+    /** 0 until `total` is known, then `ceil(total / pageSize)`. */
+    pageCount: number;
+    /** The page the viewer is looking at. */
+    anchorPage: number;
+    /** Counts resets, so a view can scroll back to the top when the query changed. */
+    epoch: number;
+    /** The resident pages (the window), ascending. At most `windowPages` of them; retained pages outside it are not listed. */
+    pages: readonly PageSnapshot<T>[];
+    /** The loaded run: the items of the shown pages, in list order. At most `windowPages * pageSize`. */
+    items: readonly T[];
+    /** The position in the whole list of `items[0]`; 0 when nothing is loaded. */
+    offset: number;
+    /** What the last `loadCount` rejected with; undefined otherwise. */
+    countError: unknown;
+}
+export interface PagedWindowOptions<T> {
+    pageSize: number;
+    /**
+     * A row's identity. One key is never on two pages of a snapshot (see ONE ROW KEY, ONE PAGE in the store's header). It is read once, when the
+     * store is created, and called on any row at any time: it must be a pure function of the row (the same row always gives the same key, with no
+     * state of its own or from the caller's render).
+     */
+    getKey: (row: T) => string | number;
+    /** How many pages are resident (rendered) at once; the rows of pages outside it are kept, see the store's header. @default 3 */
+    windowPages?: number;
+    loadPage: LoadPage<T>;
+    /** Required to use `count` mode. */
+    loadCount?: LoadCount;
+    /** @default "pages" */
+    mode?: PagedWindowMode;
+    /**
+     * How long the viewer's page must stay put before the window moves to it; 0
+     * moves it synchronously. A negative or fractional value throws.
+     * @default PAGED_WINDOW_SETTLE_MS
+     */
+    settleMs?: number;
+    /**
+     * DXUI-77: hold record keys, not row copies. Each page's rows are written into the record store and the window keeps only their keys; `items` and
+     * `pages[].items` are read back from the store, so an edit to a record shows with no page read (PLAN-32 R-1). See `records-binding.ts`. Without it
+     * the window holds its rows itself, as it always has.
+     */
+    records?: PagedWindowRecordsOptions<T>;
+}
+/**
+ * The pages to hold for an anchor: `windowPages` of them centred on it (the
+ * extra page of an even window goes after), clipped to `[0, pageCount)`. Pure,
+ * so the rule is testable without a store.
+ */
+export declare function windowPageNumbers(anchorPage: number, pageCount: number, windowPages: number): number[];
+export declare class PagedWindowStore<T> {
+    private readonly pageSize;
+    private readonly windowPages;
+    private readonly settleMs;
+    private readonly getKey;
+    private loadPage;
+    private loadCount;
+    /** The resident pages: the window around the applied anchor. */
+    private resident;
+    /** DX-5521: ready pages outside the window, rows kept (see the header). */
+    private retained;
+    private total;
+    /** Where the viewer is; moves the instant they do. */
+    private anchor;
+    /** The anchor the resident pages' READS were last synced to; differs from `anchor` while the viewer is still moving, or frozen. */
+    private appliedAnchor;
+    /** Moves the window to `anchor` once it has been still for `settleMs`; null when no move is waiting. */
+    private settleTimer;
+    private mode;
+    private frozen;
+    private epoch;
+    private nextToken;
+    private countRequest;
+    /** Answers that arrived while frozen, applied in arrival order on thaw. */
+    private heldAnswers;
+    /** Pages whose refresh was asked for while frozen. */
+    private queuedPages;
+    /** The length's refresh (count mode) was asked for while frozen. */
+    private queuedCount;
+    private countError;
+    /** DXUI-83: the token of the last count read that settled, answered or failed; a count window's placed rows wait on it like a page window's on its pages' `readSeq`. */
+    private countSettledSeq;
+    private snapshot;
+    private listeners;
+    /** DXUI-77: the record mode, or null when the window holds its rows itself. */
+    private readonly rec;
+    /** DXUI-77: a record changed while frozen; the thaw looks at it once. */
+    private recordsPending;
+    /** DXUI-77: the store tenant the pages were last requested under; a different one now means the store was cleared under them. */
+    private tenantSeen;
+    /** DXUI-77: the store version the window last looked at; one flush calls the handler once per changed key, and one look covers them all. */
+    private recordsVersion;
+    /** DXUI-77: a held key unknown to the store already sent the window to re-read; no answer has made every key known since. */
+    private unknownReread;
+    constructor({ pageSize, getKey, windowPages, loadPage, loadCount, mode, settleMs, records, }: PagedWindowOptions<T>);
+    /**
+     * Replace the loaders. The React binding calls this after every commit so a
+     * consumer's loaders can close over fresh state without the store being
+     * rebuilt (rebuilding drops every resident page). A change in WHAT is loaded is a
+     * `reset`, never this.
+     */
+    setLoaders(loadPage: LoadPage<T>, loadCount: LoadCount | undefined, records?: PagedWindowRecordsOptions<T>): void;
+    getSnapshot: () => PagedWindowSnapshot<T>;
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * The viewer moved to another page. The window follows once they have stayed
+     * there for `settleMs`; while frozen it follows on thaw.
+     */
+    setAnchorPage(page: number): void;
+    /**
+     * While true nothing about the window changes: it neither loads nor drops
+     * pages, starts no refresh and applies no answer, whatever the anchor or the
+     * total does (all of it waits for the thaw). A drag needs it: the carried card
+     * is mounted in its page, and dropping that page mid-drag would unmount the
+     * card and cancel the drag. Only `reset()` ignores it — a query change is a
+     * different list.
+     */
+    setFrozen(frozen: boolean): void;
+    /** `count` holds and requests no cards, only the length (see the file header). */
+    setMode(mode: PagedWindowMode): void;
+    /** The query changed: forget everything, return to the first page. */
+    reset(): void;
+    /** Re-read one resident page in place. A retained page is marked stale and re-read in place when it re-enters the window; a page never loaded loads fresh when it is next wanted. */
+    invalidatePage(page: number): void;
+    /**
+     * DX-5521: invalidate every page, resident or retained, that has a row passing `rowTest`: a resident one is re-read in place, a retained
+     * one is marked stale and re-read when it re-enters the window. Returns whether any page matched.
+     */
+    invalidateWhere(rowTest: (row: T) => boolean): boolean;
+    /**
+     * DX-5521: whether any CURRENT loaded row, resident or retained, passes `rowTest`. A stale page, in the window or kept, does not count:
+     * something already said its rows changed, so a row it shows may no longer be where it shows it (`invalidateWhere` still marks it). Changes
+     * nothing.
+     */
+    holdsRow(rowTest: (row: T) => boolean): boolean;
+    /** Re-read every resident page in place and mark every retained one stale; in `count` mode, re-ask the length. */
+    invalidateAll(): void;
+    /**
+     * A resident page's rows are out of date: read it again now, or at the thaw when frozen (a page that leaves the window by then is kept stale,
+     * see `release`). No notification: callers publish. A page drawn from memory by a move (`readDue`) is read at the settle already, so it is not
+     * read earlier. A page outside the drawing that is only finishing a read (`outside`) is nobody's to look at: the read, whose answer now
+     * predates the invalidation, is abandoned and the page is kept stale, to be re-read if the viewer returns. Whichever read follows answers an
+     * invalidation, so a loss re-read's damping is lifted (`lossRead`).
+     */
+    private refreshResident;
+    /** Nothing a view draws changes while frozen (the refreshes wait for the thaw), so nobody is told. */
+    private publishUnlessFrozen;
+    /** Load the first window (or the length). The binding calls it on mount, and again after a `stop`. */
+    start(): void;
+    /** Abort every request and release every page. The binding calls it on unmount. */
+    stop(): void;
+    private requireCountLoader;
+    private pageCount;
+    /**
+     * Pages to hold now. None in `count` mode. Page 0 alone before the first
+     * response (the count is unknown) and for an empty list: an empty page is
+     * still resident, because it is what `invalidateAll` re-reads when the list gets
+     * its first item — an empty lane that holds nothing could never find out it
+     * was no longer empty.
+     */
+    private wanted;
+    /** Bring the resident pages to the wanted ones — unless frozen, when that waits for the thaw. */
+    private sync;
+    /** The viewer has settled on `anchor`: the window moves to it, in one step. */
+    private applyAnchor;
+    private clearSettle;
+    /**
+     * Moves the resident pages to the window around `appliedAnchor` - which only
+     * `applyAnchor`, `thaw` and `reset` move, so a response arriving while the
+     * viewer is still moving brings in no READ for a page of the unsettled position
+     * (it only draws what memory already holds, `drawFromMemory`).
+     * `force` is `reset()`'s alone: it brings the window to its (new) list even
+     * while frozen.
+     */
+    private reconcile;
+    /**
+     * DX-5521: a move the viewer has not settled on draws what memory already holds for it: the retained pages of the destination window become
+     * resident (a stale one with its old rows and its read due at the settle) and the pages outside that window leave the drawing. No read starts
+     * and none is aborted, so a return before the settle costs nothing (DX-4614). When nothing of the destination is in memory the window stays
+     * where it is, so the old pages remain on screen until the settle.
+     */
+    private drawFromMemory;
+    /**
+     * Resident pages that fail `leaves` go: a ready one keeps its rows in `retained` (stale if they may be out of date); one never loaded has
+     * none to keep. A read in flight is aborted, unless `keepReads` (a move not yet settled): that page stays resident but `outside` the drawing,
+     * so the viewer coming back finds its read still running. Then the rows past the list's end (it shrank), and every row in count mode (no rows
+     * are tracked there), are dropped: they belong to no list anyone can scroll.
+     */
+    private release;
+    /**
+     * DX-5521: a resident page goes: a read in flight is aborted, a ready page keeps its rows in `retained`. They are stale if a read was cut short,
+     * if the page was already stale, if an invalidation was queued for it while frozen (the queue is dropped with the page, so the mark is the only
+     * trace), or if `stale` says an invalidation has just arrived. A page never loaded has no rows to keep. A loss re-read's damping goes with
+     * the rows unless one of those invalidations lifts it.
+     */
+    private leave;
+    /** DX-5521: a retained page back in the window: resident at once and `ready` with its old rows, never `loading`. Undefined when nothing is kept for it. */
+    private promote;
+    /** Everything the frozen window put off, in the order the header promises. */
+    private thaw;
+    /** Start (or restart) a page's request; whatever was in flight is abandoned. `forLoss`: it is sent because the page lost a row (DX-5521). */
+    private request;
+    private settle;
+    /**
+     * Record an answer on its page — no window change, no notification: callers
+     * sync once. Re-checks the token because a entry answer is replayed on thaw,
+     * after which its request may have been abandoned.
+     */
+    private applyPage;
+    private requestCount;
+    private settleCount;
+    private applyCount;
+    private abortCount;
+    private dropAll;
+    /** A held record changed, or a layer moved on a record of the type. */
+    private readonly onRecordsChanged;
+    private applyRecordsChange;
+    /**
+     * A tenant change or a clear leaves the window holding keys to nothing, and `reissueMountedReads` does not cover it (it runs on the realtime
+     * epoch, which neither bumps). So the window looks for itself: the store serves another tenant than the pages were requested under, or a page
+     * that is current (not being read) holds a key the store knows nothing of.
+     */
+    private storeWasCleared;
+    /** Every key a page holds, resident or retained. */
+    private heldKeys;
+    /** The rows a page draws from its own position: its held rows, or in record mode the held keys read from the store. */
+    private pageRows;
+    /** Every loaded row of a page, for a consumer's row test: whether or not it belongs here now. */
+    private loadedRows;
+    /** Every resident page (a count window: its length) has been answered by a read sent at or after `seq` (a read that failed has nothing to wait for). */
+    private answeredSince;
+    /** The list's length as the window shows it: the server's, less each held row that left its page, plus each arrived row no page holds yet (a count window holds no row: it adds arrivals only). */
+    private visibleTotal;
+    /** Placement and the store subscriptions follow the keys the window holds now. */
+    private syncRecords;
+    /** The resident pages the snapshot draws: the window, without the pages that only stay to finish a read (`outside`). */
+    private drawn;
+    /**
+     * The longest unbroken stretch of ready pages inside the list, lowest on a
+     * tie. Pages past the list's end (it shrank while the window was frozen) are
+     * not part of any run.
+     */
+    private loadedRun;
+    /**
+     * DX-5521: each drawn page's items with every row key on one page only (ONE ROW KEY, ONE PAGE in the header). Pages claim their rows in
+     * order of how current they are - a page with current rows before a stale or refreshing one, then the newer read first - and a row whose
+     * key an earlier claimant took is left out. A page that loses nothing keeps its own array.
+     */
+    private uniqueItems;
+    /**
+     * DX-5521: a drawn page whose rows are current but lost a row to another page is out of date, since two right pages cannot share a row:
+     * re-read it in place, so the page is not left one row short until some other event. One pass finds every such page: marking a page out of
+     * date only lowers its rank, so it never makes another page lose a row. A page whose latest read was already a loss re-read is not re-read
+     * again (ONE RE-READ PER LOSS in the header). Settled, the read starts now; while the viewer is still moving the page is marked stale and read
+     * at the settle (DX-4614). Frozen, it looks for nothing: every answer is held, so no page can lose a row until the thaw publishes again.
+     */
+    private rereadLosers;
+    /** Each drawn page's rows, before the one-key-one-page rule: its held rows, or its keys read from the store. */
+    private rowsByPage;
+    /**
+     * DXUI-77: the loaded run with the placed rows (arrived and moved) drawn at the place `placeIn` gives. Returns `items` itself when nothing
+     * moved, else the same map with each shown page's rows regrouped by the page a row now sits in.
+     */
+    private withPlacedRows;
+    /** DXUI-77: a page whose rows did not change keeps its items array, which `useSyncExternalStore` needs from a snapshot it did not change. */
+    private static sameRows;
+    private build;
+    private publish;
+}

package/dist/types/lib/paged-window/use-measured-pitch.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How tall one item really is — measured, not guessed. DX-4540.
+ *
+ * A page that is not resident is drawn as a placeholder of `items x pitch`, so the
+ * scrollbar is only as true as the pitch. `estimated` stands in until pages
+ * have been seen; after that the pitch is the MEAN over every item measured,
+ * which is a ResizeObserver over the page blocks.
+ *
+ * EVERY block is observed, because a block turns from placeholder to cards (and
+ * back) without its element being replaced: only a block that currently holds
+ * cards (`data-count`) is a measurement of what a card costs; a placeholder's
+ * own size is the estimate drawn back at us. A block that stops holding cards,
+ * or is removed, leaves its LAST reading in the mean (`departed`), so dropping
+ * a page does not make the estimate lurch and every placeholder above the
+ * viewer resize with it.
+ *
+ * A change under half a pixel is not published: re-laying-out every placeholder
+ * in a long list for sub-pixel drift is cost with no picture.
+ *
+ * NOTHING IS EVER RESET, AND THAT IS DELIBERATE. A new query (another sort, a
+ * different time range) lists the same kind of card, so what was learned about
+ * its height still holds; clearing it would snap every placeholder back to the
+ * estimate and make the first screen of the new query jump. The measurement is
+ * only a sizing aid for space no card occupies, and the mean keeps correcting
+ * itself from every page that is shown.
+ *
+ * A block whose size does not change when it turns from placeholder to cards
+ * (or back) fires no resize, so its reading is picked up at the next size change;
+ * a placeholder is sized from the estimate in the first place.
+ */
+export declare function useMeasuredPitch(estimated: number): {
+    pitch: number;
+    observe: (el: HTMLElement) => () => void;
+};

package/dist/types/lib/paged-window/use-page-visibility.d.ts

@@ -0,0 +1,20 @@
+import type { ScrollRoot } from "./use-scroll-root";
+/**
+ * The page the window should centre on: the middle one (lower middle when
+ * even) of the pages whose blocks intersect the root. A viewport shorter than
+ * a page sees one or two; the window of three covers either. Null when nothing
+ * is in view (a hidden scroller), so the window keeps where it was.
+ */
+export declare function centrePage(visible: ReadonlySet<Element>): number | null;
+/**
+ * Which pages are in view, from one IntersectionObserver over every page block,
+ * rooted at the scroller — no scroll listener, no polling. DX-4540.
+ *
+ * `observe(el)` is what a block's ref calls; it returns the cleanup. It is
+ * stable, and blocks that mount before the observer exists (it needs the
+ * resolved scroller) are picked up when it does. Whenever the set in view
+ * changes, `onCentre` is told the page to centre on.
+ */
+export declare function usePageVisibility(scroller: ScrollRoot | null, onCentre: (page: number) => void): {
+    observe: (el: HTMLElement) => () => void;
+};

package/dist/types/lib/paged-window/use-paged-window.d.ts

@@ -0,0 +1,61 @@
+import { type PagedWindowMode, type PagedWindowOptions, type PagedWindowSnapshot } from "./store";
+export interface UsePagedWindowOptions<T> extends PagedWindowOptions<T> {
+    /**
+     * Names WHAT is being listed: the filter, the sort, the time range. When it
+     * changes the window forgets every page, returns to the first and the list
+     * scrolls back to the top. A change in a loader's identity alone does not:
+     * a loader closing over fresh state must not throw away what is resident.
+     */
+    queryKey: string;
+    /**
+     * `"count"` loads no cards, only the list's length (through `loadCount`), and
+     * keeps it live: a hidden lane that still needs a true badge. Back to
+     * `"pages"`, the window loads again.
+     * @default "pages"
+     */
+    mode?: PagedWindowMode;
+}
+export interface PagedWindow<T> extends PagedWindowSnapshot<T> {
+    /** The viewer moved to this page. `PagedWindowList` reports it; a custom view may too. */
+    setAnchorPage: (page: number) => void;
+    /** Re-read one resident page in place — a card on it changed. A retained page (rows kept, outside the window) is marked stale and re-read in place when it re-enters the window. */
+    invalidatePage: (page: number) => void;
+    /**
+     * Invalidate every page (resident or retained) that has a row passing `rowTest` - a card changed and the page that shows it may be outside the
+     * window, which `invalidatePage` cannot name. A resident page is re-read in place now; a retained one when it re-enters the window. Returns
+     * whether any page matched.
+     */
+    invalidateWhere: (rowTest: (row: T) => boolean) => boolean;
+    /**
+     * Whether any CURRENT loaded row, resident or retained, passes `rowTest`. The rows of a stale page are known to be out of date and do not
+     * count, whether it is kept outside the window or drawn in it (drawn back from memory before its re-read, or marked by a changed total).
+     * Reads the store as it is now; changes nothing.
+     */
+    holdsRow: (rowTest: (row: T) => boolean) => boolean;
+    /** Re-read every resident page in place and mark every retained page stale — a card was created, moved or removed. In `count` mode, re-ask the length. */
+    invalidateAll: () => void;
+    /**
+     * While true the window neither loads nor drops pages. `PagedWindowList`
+     * sets it for the length of a drag: the carried card is mounted in its page,
+     * and dropping that page mid-drag would unmount the card and cancel the drag.
+     */
+    setFrozen: (frozen: boolean) => void;
+}
+/**
+ * Keeps the rows of every page it has loaded (DX-5521) and tells a view which
+ * `windowPages` (default 3) of them to render. `loadPage` answers one page AND the list's current
+ * length, so the scrollbar can span `total` before most of it is loaded.
+ *
+ * The window moves to the viewer's page only after it has stayed put for
+ * `settleMs` (200 ms by default), so a fast scroll loads the pages it lands
+ * on, never the ones it passes (DX-4614); a read for a page that leaves the
+ * window is aborted through its `signal`, and an aborted read is never an error.
+ *
+ * `pageSize` and `windowPages` are fixed for the life of the hook: changing one
+ * means every resident page is cut differently, which is a different list — give it
+ * a new `queryKey` and a new mount instead. `settleMs` is fixed too: the store
+ * reads it once. All three throw rather than guess. `getKey` is read once as well
+ * (a different function passed on a later render is ignored), so it must be a pure
+ * function of the row: the same row always gives the same key.
+ */
+export declare function usePagedWindow<T>({ pageSize, getKey, windowPages, loadPage, loadCount, queryKey, mode, settleMs, records, }: UsePagedWindowOptions<T>): PagedWindow<T>;

package/dist/types/lib/paged-window/use-scroll-root.d.ts

@@ -0,0 +1,18 @@
+/** The element a list scrolls in: `el` is null when the page itself scrolls (the viewport). */
+export interface ScrollRoot {
+    el: HTMLElement | null;
+}
+/**
+ * Finds the box a list scrolls in, once the list is in the DOM. DX-4540.
+ *
+ * Returns a ref callback for the list's root and the root it resolved (null
+ * until mounted). The list's OWN element counts: a list whose class sets
+ * `overflow-y-auto` is its own scroller, and one dropped into a board lane
+ * finds the lane's container above it. Resolved on mount only — a list does
+ * not change scroller during its life, and re-walking on every render would
+ * make the IntersectionObserver rooted at it be torn down and rebuilt.
+ */
+export declare function useScrollRoot(): {
+    ref: (el: HTMLElement | null) => void;
+    scroller: ScrollRoot | null;
+};

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

@@ -0,0 +1,57 @@
+export declare function storageKey(name: string): string;
+/**
+ * Read and parse, returning undefined for every failure mode.
+ *
+ * localStorage throws rather than returning null in two real situations —
+ * Safari private browsing, and any embedding where storage is blocked by
+ * policy. An unhandled throw here happens during the useState initializer,
+ * which unmounts the tree: the whole app disappears because a panel wanted to
+ * remember its width. Persistence is a convenience and must degrade to "use
+ * the default", never to a blank page.
+ */
+export declare function readStored<T>(name: string, isValid: (value: unknown) => value is T): T | undefined;
+export declare function writeStored(name: string, value: unknown): void;
+/**
+ * The same guarded read and write, for a value that is stored as a PLAIN
+ * STRING rather than as JSON — `preferences.ts`'s three, whose values are one
+ * of a few known words and are validated by membership rather than by a
+ * predicate. JSON-encoding them would put quotes in storage for no reason and
+ * break every entry a person already has.
+ *
+ * These exist because the guard did not reach that module and the failure was
+ * total: all three preferences read in a `useState` INITIALIZER, so the throw
+ * propagated out of render and React unmounted the tree — a blank page,
+ * because the app wanted to remember a colour scheme. The header above has
+ * claimed since it was written that "the namespace and the guarded read/write"
+ * were shared with `preferences.ts`; they were not, in either direction, and
+ * that sentence is only true now.
+ */
+export declare function readStoredString(name: string): string | null;
+export declare function writeStoredString(name: string, value: string): void;
+export declare function clearStored(name: string): void;
+/** Accepts anything — for callers whose stored shape needs no narrowing. */
+export declare const anyValue: (value: unknown) => value is unknown;
+export type PersistedStateOptions<T> = {
+    /**
+     * Rejects a stored value that no longer fits. REQUIRED thinking, not
+     * boilerplate: stored state outlives the code that wrote it, so a layout
+     * saved against three panels will be read back by a two-panel group after a
+     * refactor. Spreading it produces a broken layout that persists forever
+     * because it keeps being written back. Returning false throws it away and
+     * falls back to the default — the only recovery a user can't perform for
+     * themselves.
+     */
+    isValid: (value: unknown) => value is T;
+    /** Set false to stop persisting without changing any call site. */
+    enabled?: boolean;
+};
+/**
+ * `useState`, plus localStorage.
+ *
+ * The stored value is read in the INITIALIZER, not in an effect. Reading it in
+ * an effect paints the default first and then jumps — the panel visibly snaps
+ * from 50% to the 30% you left it at, on every single load. That flash is the
+ * entire reason people call persisted layouts janky, and it is avoidable by
+ * reading one frame earlier.
+ */
+export declare function usePersistedState<T>(name: string | undefined, initial: T | (() => T), { isValid, enabled }: PersistedStateOptions<T>): readonly [T, import("react").Dispatch<import("react").SetStateAction<T>>, () => void];

package/dist/types/lib/preference-values.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The vocabulary of the document-level display preferences, and the one way a
+ * value is written onto `<html>`.
+ *
+ * DX-4075: REACT-FREE ON PURPOSE. `preferences.ts` holds the hooks, so it imports
+ * React; `@50arms/ui/pure` may not reach React (`pure-entry.test.ts`). The framed
+ * side of `SandboxedFrame` (the injected `window.danxMiniApp` script, built from these
+ * lists, which mirrors `applyPreference`) has to apply the host's
+ * appearance with the very same write the host used and accept exactly the same
+ * values, so the unions, the value lists and `applyPreference` live here, imported
+ * by both. Two copies would be two chances for the host and the frame to drift.
+ */
+/**
+ * Writes one preference onto `<html>` with document-wide motion suspended for
+ * the duration of the change.
+ *
+ * WHY THIS IS NOT JUST `setAttribute`. Colour transitions are a foundation in
+ * this system: every element has one. That is right for an interaction — a
+ * control easing as you hover it — and wrong for a preference, because
+ * switching theme changes the computed colour of EVERY element at once.
+ * Measured on this demo: 2,360 transitions started simultaneously and the page
+ * took **957ms** to settle, 1,560ms on the chat route, for a token whose
+ * duration is 110ms. A theme switch should be a cut, not a dissolve; what it
+ * actually looked like was the whole document struggling.
+ *
+ * `--motion-scale: 0` is how it is suspended, rather than a blanket
+ * `transition: none !important`. Every duration in the system is already
+ * pre-multiplied by that scalar, so zeroing it turns them all off through the
+ * layer that exists for the purpose, overrides nothing a component declared,
+ * and cannot be forgotten by a component author.
+ *
+ * THE FORCED READ IS LOAD-BEARING. Style is normally recalculated once, after
+ * this function has returned — by which time the attribute is gone and the
+ * durations are back. Reading a computed value flushes the recalculation
+ * synchronously, so the new colours are committed WHILE durations are still
+ * zero, and no transition is ever started. Delete that line and the suspension
+ * silently does nothing at all, which is why `audit:motion` measures the settle
+ * time rather than the presence of the attribute.
+ *
+ * DX-5526: A VALUE <html> ALREADY HOLDS WRITES NOTHING. Every preference hook
+ * applies its value once the page has hydrated, and a prerendered page has
+ * already written each value before first paint. The suspension and the forced
+ * read are not free: `--motion-scale` is inherited, so flipping it restyles
+ * every element, twice (on and off). For a write that changes nothing that was
+ * two full-document style recalculations on every load (~1.1 s of throttled
+ * main thread on the 50arms.ai homepage) to suppress transitions that could
+ * never start.
+ */
+export declare function applyPreference(attribute: string, value: string): void;
+export type Theme = "light" | "dark";
+export declare const THEMES: readonly ["light", "dark"];
+export type UiScale = "sm" | "md" | "lg";
+export declare const SCALES: readonly ["sm", "md", "lg"];
+/**
+ * `design` is the palette as drawn; `aa` raises every token to the 4.5:1 floor.
+ *
+ * Opt-IN, not enforced, because enforcing the floor everywhere flattens the
+ * hierarchy for everyone: de-emphasised text stops being de-emphasised, and in
+ * this palette light-theme tertiary collapsed onto the same ramp step as
+ * secondary. A floor is a floor — reachable in one click by anyone who needs
+ * it, not a target that drags the whole design up to meet it.
+ */
+export type ContrastPreference = "design" | "aa";
+export declare const CONTRAST: readonly ["design", "aa"];
+/**
+ * `system` is a real third state, not a synonym for "full": it means defer to
+ * the OS, which is what most people want and what the OS-level preference
+ * exists to express. Collapsing it into a boolean would make an app-level
+ * control that says "full" override a user who set reduced motion system-wide.
+ */
+export type MotionPreference = "system" | "full" | "reduced";
+export declare const MOTION: readonly ["system", "full", "reduced"];

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

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import { type ContrastPreference, type MotionPreference, type Theme, type UiScale } from "./preference-values";
+export declare function ThemeDefaultProvider({ theme, children }: {
+    theme: Theme;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Theme | null>>;
+export declare function useTheme(): {
+    theme: Theme;
+    setTheme: (next: Theme) => void;
+    toggle: () => void;
+};
+export declare function useUiScale(): {
+    scale: UiScale;
+    setScale: (next: UiScale) => void;
+    cycle: () => void;
+};
+export declare function useContrast(): {
+    contrast: ContrastPreference;
+    setContrast: (next: ContrastPreference) => void;
+    toggle: () => void;
+};
+export declare function useMotionPreference(): {
+    motion: MotionPreference;
+    setMotion: (next: MotionPreference) => void;
+    cycle: () => void;
+};

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;