@50arms/ui 0.0.0-stage → 35.1.0

package/dist/types/lib/records/store.d.ts

@@ -0,0 +1,289 @@
+import type { RecordPayload, RecordState, StalenessEntry, WriteAllResult, WriteOptions, WriteResult } from "./types";
+/**
+ * Declare which tenant this store is holding records for.
+ *
+ * Changing it CLEARS the store. The keys are `Type:id` with no tenant in them,
+ * so team B's demand #7 would merge onto team A's demand #7 — in an app whose
+ * read key is deliberately team-scoped precisely to prevent that. Clearing
+ * handles what is already written; the `tenant` parameter on `write` handles
+ * what is still in the air.
+ */
+export declare function setRecordStoreTenant(tenant: string | number | undefined): void;
+/** DXUI-84: called when the store's tenant changes (and only then), for state kept outside the store. */
+export declare function subscribeToTenant(listener: () => void): () => void;
+export declare function getRecordStoreTenant(): string | number | undefined;
+/**
+ * Moves on every accepted change to what the store holds (a write, a layer, a clear). A listener that is called once per changed key in one
+ * flush compares it to the version it last looked at, so a burst of N changed keys costs it one look, not N (DXUI-77).
+ */
+export declare function recordStoreVersion(): number;
+/**
+ * The single writer. A fetch response, a mutation's returned item and a
+ * broadcast all arrive here, so fetch-versus-broadcast reconciliation lives in
+ * ONE place rather than split across two modules that would each hold half the
+ * rule.
+ */
+export declare function write(payload: RecordPayload, options: WriteOptions): WriteResult;
+/**
+ * The plural form — REQUIRED, not a convenience.
+ *
+ * A list page is fifty payloads, and fifty singular writes are fifty
+ * notification passes and fifty render passes for one page load. Every write
+ * in one call coalesces into a single notification.
+ */
+export declare function writeAll(payloads: readonly RecordPayload[], options: WriteOptions): WriteAllResult;
+/**
+ * One optimistic write, held ON TOP of a record's base rather than merged into it.
+ *
+ * ==== WHY A LAYER AND NOT A WRITE ====
+ *
+ * The first optimistic writes built on this store merged the belief into the base with a
+ * client-invented `__timestamp`, and each one then had to work around what that did:
+ *
+ *   - the rollback had to be stamped NEWER than the belief, or the out-of-order guard dropped
+ *     it — and a same-millisecond apply-then-revert is not newer, so a local monotonic clock
+ *     was needed to get it through;
+ *   - once a client timestamp was stored, the SERVER's own later answer could lose to it, since
+ *     a browser clock and a database column are not the same clock;
+ *   - the rollback snapshot came from a read, which strips the envelope, so `__type` had to be
+ *     patched back in before the store would take it.
+ *
+ * A layer has none of those problems by construction. The base — the only thing the ordering
+ * guard adjudicates — is never touched by the belief, so the belief can never outrank a server
+ * answer and removing it is a removal, not a write that has to win anything.
+ *
+ * ==== ORDER ====
+ *
+ * Layers apply oldest first, so the newest belief about a field is the one a reader sees — a
+ * set, clear, set, clear on one field shows the last clear the moment it is made, whatever
+ * order the four answers come back in. Removing a layer from the middle leaves every later one
+ * standing: undoing write 2 of 4 does not undo 3 and 4.
+ */
+export interface OptimisticLayer {
+    /** Global and strictly increasing — also the issue order of the writes that made them. */
+    readonly id: number;
+    /** Data fields, stored as given — never normalized, so a patch cannot mint records. */
+    fields: Record<string, unknown>;
+    /**
+     * When set, `fields` are KEYS OF THE MAP held in this one field (a record's `data_points`,
+     * say), merged over whatever that map holds beneath — never a replacement of the whole field.
+     * Two beliefs about two different keys of one map then stay independent: undoing one leaves the
+     * other standing, and a read that rewrites the map underneath still shows through every key no
+     * belief is about.
+     */
+    readonly at: string | undefined;
+    /** An ISO time when this layer is a delete. */
+    readonly tombstone: string | undefined;
+    /** True when this layer IS the record — an optimistic create with no server row yet. */
+    readonly created: boolean;
+    /**
+     * True when the write's answer was refused as older than the held version (DXUI-78). The layer
+     * is no longer a write in flight: it holds the value the screen keeps showing until a fetch that
+     * carries the field lands. It never pins a record against `sweepRecords` and never reads as saving.
+     */
+    kept: boolean;
+}
+/**
+ * Put an optimistic layer on top of `Type:id`, creating a base-less record for a create.
+ *
+ * Notification is QUEUED here, like every other store change; the optimistic-write primitive
+ * flushes synchronously afterwards, because a user-initiated write must never wait on an
+ * animation frame (a hidden page never gets one).
+ *
+ * @returns the layer id, for `removeOptimisticLayer` / `trimOptimisticLayers`
+ */
+export declare function pushOptimisticLayer(type: string, id: string | number, layer: {
+    fields?: Record<string, unknown>;
+    at?: string;
+    tombstone?: string;
+    created?: boolean;
+    kept?: boolean;
+}): number;
+/**
+ * A write's answer was refused as older than the held version, so the base cannot take it — but the
+ * screen must not fall back to the value from before the write (DXUI-78, DEC-285). The layer stays,
+ * becomes `kept`, and each field the answer carries replaces the client's guess (a server-set value
+ * such as `signed_off_at`). For an `at` layer the keys come from the answer's map field. Values are
+ * stored normalized (a nested record as `{__ref}`), the shape `write()` stores.
+ *
+ * @returns the layer's values now, which is what a later, older write's settling restores, or
+ *   `undefined` when it holds no field to keep: the layer is then the caller's to remove
+ */
+export declare function keepOptimisticLayer(key: string, layerId: number, answer: RecordPayload, tenant: string | number | undefined): Record<string, unknown> | undefined;
+/**
+ * A rev-ordered write's answer, at `version`, was refused as older (DXUI-96): the layer gives up
+ * every field the base holds at or above that version, as what the base holds there is the truth.
+ * A field nothing newer carried stays for `keepOptimisticLayer`: the base never took the write's
+ * value. For an `at` layer the map is the field.
+ */
+export declare function trimSupersededFields(key: string, layerId: number, version: number): void;
+/**
+ * A create's answer was refused as older than the real row already held: the row must not show
+ * empty. A kept layer on the real key holds the answer's data fields the row lacks, never one it
+ * holds, which may be newer than the answer (DXUI-78, DEC-285).
+ */
+export declare function pushKeptAnswerLayer(key: string, type: string, id: string | number, answer: RecordPayload, tenant: string | number | undefined): void;
+/**
+ * Take one layer off. A record that only ever existed as an optimistic create disappears with
+ * its last layer — it reads `unknown` again, exactly as before the create.
+ */
+export declare function removeOptimisticLayer(key: string, layerId: number): void;
+/**
+ * A later write's answer has landed: every OLDER layer's belief about the same fields is
+ * superseded, whether or not that older request has answered yet. A layer left with nothing to
+ * say is dropped. Without this, a set whose answer is still out would keep overlaying a field
+ * the server has already confirmed was cleared after it.
+ *
+ * `at` scopes the trim to beliefs about keys of that one map field — the same granularity the
+ * committing write had.
+ */
+export declare function trimOptimisticLayers(key: string, beforeLayerId: number, fields: readonly string[], at?: string): void;
+/**
+ * Whether the BASE is tombstoned — what a list slot prunes on. An optimistic delete hides the
+ * row from every read but must not cost the slot its key, or a rollback would bring the record
+ * back with no list left holding it.
+ */
+export declare function isBaseTombstoned(key: string): boolean;
+/**
+ * One field of the BASE, as stored (normalized: a nested record is a `{__ref}`). What a keyed
+ * belief is folded into when its write succeeds without an answer to replace it — writing it back
+ * through `write()` round-trips the refs untouched.
+ */
+export declare function readBaseField(key: string, field: string): unknown;
+/**
+ * DXUI-83: a counter that moves only when a write changes the BASE of `key` (0 for a key the store does not hold). A layer going moves
+ * `record.version`, not this, so a commit (the base is written, then the layer removed) and a refusal (the layer is only removed) differ.
+ */
+export declare function readBaseVersion(key: string): number;
+/** DXUI-83: does `key` carry a `kept` layer, a save that succeeded but whose answer was older than the held version (DXUI-78)? */
+export declare function hasKeptLayer(key: string): boolean;
+/**
+ * DXUI-83: what `key` reads as WITHOUT the writes in flight: the base, with `kept` layers on it (they are the value on screen). `no-base` is an
+ * optimistic create with no server row yet; `unknown` is a base no fetch has satisfied `needs` for. Hydrated fresh each call, never memoized: a
+ * window asks it only for a layered record that no page holds.
+ */
+export declare function readBaseState(key: string, needs: string): {
+    status: "present";
+    record: unknown;
+} | {
+    status: "no-base" | "deleted" | "unknown";
+};
+/** Does `key` carry a write in flight right now? A kept layer (DXUI-78) is not one. */
+export declare function hasOptimisticLayers(key: string): boolean;
+/**
+ * DXUI-77: the keys of `type` that carry at least one layer that is not `kept` - a write in flight, an optimistic create included. Read-only;
+ * a window that must find a record it does not hold (a card moved INTO it) asks here, because the store has no other way to list records by
+ * type.
+ */
+export declare function layeredKeys(type: string): readonly string[];
+/**
+ * DXUI-77: hear that a layer changed on a record of `type`: pushed, kept, trimmed, removed, or cleared by the fetch that settled it (a layer that
+ * IS the record, `created`, included). Delivered with the store's other notifications, once per flush however many layers moved; the listener
+ * asks `layeredKeys` what is layered now. Nothing is stored beyond the listener.
+ *
+ * @returns unsubscribe
+ */
+export declare function subscribeToLayers(type: string, listener: () => void): () => void;
+/**
+ * `value` in the shape `normalizeValue` stores it — a nested record as `{__ref: key}` — without
+ * writing anything, so a raw answer can be compared with what the base holds (DXUI-89).
+ */
+export declare function storedShape(value: unknown): unknown;
+/**
+ * The `unknown` state, as ONE module-level frozen constant.
+ *
+ * `getServerSnapshot` returns this. A fresh literal there throws under the only
+ * condition it exists for.
+ */
+export declare const UNKNOWN_STATE: RecordState<never>;
+export declare function getUnknownState(): RecordState<never>;
+/**
+ * What a reader is told about one key, gated on the field set it declared it
+ * needs.
+ *
+ * The gate is what stops a record seeded ONLY by a broadcast from reaching a
+ * projection function that assumes absent means empty — which renders a
+ * confident "0 documents" for a record with hundreds.
+ */
+export declare function readState(key: string, needs: string): RecordState<unknown>;
+/** Non-reactive read, for callers outside a component. */
+export declare function peekRecord(type: string, id: string | number, needs: string): RecordState<unknown>;
+/**
+ * NOTIFICATION IS COALESCED PER ANIMATION FRAME, and that is a requirement.
+ *
+ * A document transcoding page by page broadcasts once per row. Un-coalesced,
+ * every one of those is a separate notification, a separate dep scan per
+ * subscriber and a separate render pass. Coalescing collapses a burst into a
+ * handful.
+ *
+ * Exported so a caller that must observe the effect of a write synchronously —
+ * a test, or a measurement taken immediately after a write — can flush rather
+ * than wait for a frame. The optimistic write (`reads/optimistic.ts`) flushes
+ * after every step: a reader's own action is one change, not a burst, and it
+ * must reach the screen in the same tick even on a page that gets no frames.
+ */
+export declare function flushRecordNotifications(): void;
+export declare function subscribeToKey(key: string, listener: () => void): () => void;
+export declare function subscribeToStaleness(listener: () => void): () => void;
+/**
+ * Affected ROOTS and their now-stale field sets.
+ *
+ * The signal names ROOTS rather than the key that went stale, because the key
+ * that goes stale is often a nested one — a run under a demand — and a list of
+ * demands can never match a run's key. Roots come from the hydration memo's
+ * deps map, so a root is by definition something a mounted read or a list slot
+ * is already holding.
+ *
+ * The library names no type it understands and no endpoint: the layer that
+ * performed the original fetch re-issues it, because it is the only layer that
+ * knows which field set it asked for.
+ */
+export declare function readStaleness(): readonly StalenessEntry[];
+/**
+ * The roots reached by a stale event since the last call (each key itself, plus every memo root
+ * whose deps hold it), and the set emptied. A read holding one of them must run again even when
+ * the staleness snapshot did not move: an event during a read is otherwise lost (DXUI-78, DEC-284).
+ */
+export declare function takeStaleEvents(): ReadonlySet<string>;
+export declare function getEmptyStaleness(): readonly StalenessEntry[];
+/**
+ * Pin keys as ROOTS for the duration of the returned release.
+ *
+ * A key is retained if it is REACHABLE from a root, never if it is itself
+ * pinned: a file is never independently subscribed — it is reached only by
+ * hydrating its demand — so evicting by direct subscription would evict exactly
+ * what hydration walks and leave dangling refs everywhere.
+ *
+ * Release is IDEMPOTENT and exactly paired with acquire, which is what makes
+ * StrictMode's mount / unmount / mount survivable. A subscription whose
+ * teardown is not idempotent tears down the one it just created — and it
+ * misbehaves only in development, which is the worst place for that to live,
+ * because that is where it is being debugged.
+ */
+export declare function retainKeys(keys: readonly string[]): () => void;
+/**
+ * Mark from the roots, then sweep everything unreachable.
+ *
+ * AN IDENTITY MAP THAT ONLY GROWS IS A LEAK, and the failure mode is a tab that
+ * gets slower over an afternoon with nobody connecting it to this. Browsing ten
+ * documents at 435 rows each is roughly 4,000 entries nothing releases.
+ *
+ * WHEN TO CALL IT IS THE CALLER'S DECISION, and it needs to be more than a
+ * navigation boundary: a broadcast can CREATE a key no root reaches, and on a
+ * screen nobody navigates away from — a long extraction, say — those accumulate
+ * for as long as the tab is open. A navigation boundary AND a bounded schedule.
+ * This module deliberately installs no timer of its own; a design-system module
+ * that starts an interval on import is a worse defect than the leak.
+ *
+ * @returns how many keys were dropped
+ */
+export declare function sweepRecords(): number;
+/** Wipes everything, including listeners, roots and the tenant. */
+export declare function resetRecordStore(): void;
+/** What the store holds right now, for a devtools panel or a test. */
+export declare function recordStoreStats(): {
+    records: number;
+    memos: number;
+    roots: number;
+    listeners: number;
+};

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

@@ -0,0 +1,195 @@
+/**
+ * A payload as it arrives off the wire — from a fetch response, from a
+ * mutation's returned item, or from a broadcast.
+ *
+ * DELIBERATELY LOOSE. The store requires exactly two things of it (`__type`
+ * and `id`) and interprets five more (`__timestamp`, `__deleted_at`,
+ * `deleted_at`, `__stale`, `__model`). Everything else is data it carries
+ * without understanding — which is the whole of this module's claim to being
+ * domain-agnostic.
+ */
+export interface RecordPayload {
+    readonly [field: string]: unknown;
+}
+/**
+ * How a payload arrived. NOT telemetry — each value changes real behaviour:
+ *
+ * - `"fetch"` may SATISFY a field-set tag and CLEARS staleness on every field
+ *   it carries. A broadcast can never do either, because a broadcast is
+ *   partial by whitelist and can never complete a record.
+ * - `"broadcast"` is the only source that MARKS a field stale, using the
+ *   `staleFields` its type declared. Saying so out loud prevents the obvious
+ *   wrong reading, in which a fetch that omits a stale-declared field re-marks
+ *   it and the refetch loop never settles.
+ *
+ * A mutation's returned item is a `"fetch"`: it is a full server answer to a
+ * request this client made, so it may satisfy a tag.
+ */
+export type WriteSource = "fetch" | "broadcast";
+/** Options every write carries. */
+export interface WriteOptions {
+    readonly source: WriteSource;
+    /**
+     * The tenant the REQUEST was issued under — stamped by the caller at request
+     * time, never read from module state inside `write`.
+     *
+     * Reading it inside `write` would read the tenant as it is NOW, which is
+     * precisely the bug this parameter exists to prevent: a team-A response that
+     * resolves after a switch to team B would write team A's records into a
+     * store now being read as team B's. A broadcast is stamped with the tenant
+     * whose channel delivered it, which the subscription already knows. So both
+     * sources carry it and neither infers it.
+     */
+    readonly tenant?: string | number;
+    /**
+     * An OPAQUE field-set name — `"card"`, `"detail"`, whatever the caller's own
+     * api layer already calls the selector it asked for. The store never
+     * interprets it; it records which tags a key has satisfied and compares them
+     * for equality, so the library still knows nothing about any type's fields.
+     *
+     * Only a `"fetch"` may satisfy a tag. It is what makes `useRecord(…,
+     * {needs:"card"})` report `unknown` for a record seeded only by a broadcast,
+     * rather than handing a projection function a record with no `files` and no
+     * `workflow_runs` — which renders a confident "0 documents" card for a
+     * 434-page demand.
+     */
+    readonly tag?: string;
+}
+/**
+ * What a write did. Every value is observable so a refusal leaves a trace: the
+ * prior art in this codebase records nothing at all on rejection, which is why
+ * its out-of-order guard was inert for years without anyone noticing.
+ *
+ * - `applied` — accepted, and something a reader can observe changed.
+ * - `unchanged` — accepted, and nothing changed. NOBODY IS NOTIFIED. A
+ *   redelivered duplicate must not invalidate every hydration memo that
+ *   touched the key and re-render every subscriber.
+ * - `dropped-older` — strictly older than the record's own stored timestamp.
+ * - `dropped-tenant` — stamped for a tenant this store is no longer serving.
+ * - `rejected-shape` — not a record at all: no `__type`, no `id`, or a
+ *   `{__stale:true}` ping, which carries neither.
+ */
+export type WriteVerdict = "applied" | "unchanged" | "dropped-older" | "dropped-tenant" | "rejected-shape";
+/** The result of one `write`. */
+export interface WriteResult {
+    readonly verdict: WriteVerdict;
+    /**
+     * Every key this write touched, INCLUDING nested ones — a demand payload
+     * carrying 434 files returns 435 keys.
+     *
+     * The caller that issued a refetch to clear a staleness signal needs this to
+     * decide whether the write it just made actually satisfied what it was
+     * issued for. Empty for every dropped or rejected verdict.
+     */
+    readonly keys: readonly string[];
+    /**
+     * The keys of nested records this write refused as strictly older than the version the store
+     * holds (DXUI-90). The write's own `verdict` judges only the record it was handed, so an
+     * `applied` parent can still carry a nested row the store kept at its newer version: the answer
+     * predates a change an event already brought. Empty when none was refused.
+     */
+    readonly refusedNested: readonly string[];
+    /** Why, for the verdicts that are refusals. Present only when it helps. */
+    readonly reason?: string;
+}
+/** The result of one `writeAll`. */
+export interface WriteAllResult {
+    /** One entry per payload, in the order they were given. */
+    readonly results: readonly WriteResult[];
+    /** The union of every payload's touched keys, de-duplicated. */
+    readonly keys: readonly string[];
+}
+/**
+ * What a reader is told about one key.
+ *
+ * FOUR ABSENCES, NOT ONE. Never-fetched, deleted and broadcast-partial are
+ * different answers and a screen renders each of them differently. The fourth —
+ * a 404 — is deliberately NOT a member: a refusal carries a message and a
+ * remedy that the store has no way to build, so it belongs to whatever layer
+ * performed the request.
+ *
+ * `stale` is part of the state rather than a side channel because a write that
+ * changes no value but marks a field stale must still notify — and notifying
+ * for something no reader can observe is worse than not notifying at all.
+ */
+export type RecordState<T> = {
+    readonly status: "unknown";
+} | {
+    readonly status: "present";
+    readonly record: T;
+    /** Bumps on every accepted write that changed something observable. */
+    readonly version: number;
+    /**
+     * Fields the last broadcast could not carry. Sorted, so two structurally
+     * equal stale sets compare equal.
+     *
+     * A held stale value can only be stale-LOW for a monotonic high-water
+     * mark, never stale-high, so holding the last number on screen while the
+     * refetch lands is honest. Dimming it is available, not mandatory.
+     */
+    readonly stale: readonly string[];
+} | {
+    readonly status: "deleted";
+    readonly at: string;
+};
+/** What `useRecord`/`useRecords` require of their caller. */
+export interface ReadOptions {
+    /**
+     * REQUIRED, not optional. The tag a `"fetch"` must have satisfied before
+     * this key reports `present`.
+     *
+     * The tag mechanism existed once as an optional parameter and nothing forced
+     * a caller to use it, which reopened the exact hole it was introduced to
+     * close. One word in the signature is the whole fix.
+     */
+    readonly needs: string;
+}
+/**
+ * A registered record type: the runtime string and the compile-time type, so
+ * the two can never drift.
+ *
+ * `_record` is a phantom — it carries `T` through inference and holds no value
+ * at runtime.
+ */
+export interface RecordTypeToken<T> {
+    /** The NORMALIZED model name. Never carries a `Resource` suffix. */
+    readonly type: string;
+    /** @see RecordTypeOptions.staleFields */
+    readonly staleFields: readonly string[] | "*";
+    /** Phantom. Never read. */
+    readonly _record?: T;
+}
+/** What a type may declare at registration. */
+export interface RecordTypeOptions {
+    /**
+     * The fields this type's BROADCAST cannot carry — because they are computed,
+     * or deliberately withheld from the whitelist. Everything else in a
+     * broadcast merges normally.
+     *
+     * Staleness is PER FIELD and never a whole-type on/off switch. A per-type
+     * binary discards the twelve real fields a broadcast does carry in order to
+     * signal the two it does not.
+     *
+     * `"*"` means every data field — the case where a type's broadcast carries
+     * identity and nothing else, and where the field set is not knowable at
+     * registration because it is a bag of dynamic attributes. It resolves at
+     * write time against the keys the record actually holds; see
+     * `resolveStaleFields` in `store.ts` for what that buys and what it costs.
+     */
+    readonly staleFields?: readonly string[] | "*";
+}
+/**
+ * One root affected by a staleness mark, and the fields under it that are now
+ * suspect.
+ *
+ * `key` is a ROOT, not the key that went stale. For a queue, the key that goes
+ * stale is a run while the list holds demands; naming the raw key would match
+ * no list slot and nothing would ever refetch. Roots are resolved through the
+ * hydration memo's deps map, which is safe in a way a maintained reverse index
+ * is not: it is rebuilt by the same walk that reads it, so there is no separate
+ * maintenance step to get wrong.
+ */
+export interface StalenessEntry {
+    readonly key: string;
+    readonly fields: readonly string[];
+}

package/dist/types/lib/records/wire.d.ts

@@ -0,0 +1,96 @@
+import type { RecordPayload } from "./types";
+/** A relation, once normalized: a pointer to another record's key. */
+export interface RecordRef {
+    readonly __ref: string;
+}
+export declare function isRecordRef(value: unknown): value is RecordRef;
+/**
+ * Strip a trailing `Resource` so a delete and the record it deletes land on
+ * the same key.
+ *
+ * CREATED AND DELETED PAYLOADS DISAGREE ABOUT `__type`, verified in the
+ * backend twice: created/updated take it from a resource class name that no
+ * resource overrides, so it keeps the suffix (`"WorkflowRunResource"`), while
+ * deletes take it from a helper that strips the suffix (`"WorkflowRun"`).
+ *
+ * A store keyed on the raw string files a delete under a different key than
+ * the record it is deleting, so the tombstone never lands and the row stays on
+ * screen forever. One line, and without it a whole class of update silently
+ * does nothing.
+ */
+export declare function normalizeTypeName(raw: string): string;
+/**
+ * `Type:id`, with the id COERCED TO A STRING.
+ *
+ * Ids are not uniformly numeric — a file's id is a UUID while a run's is an
+ * integer — and a Map keyed on the raw value would file `7` and `"7"`
+ * separately. There is deliberately NO `id || name` fallback: that is a quirk
+ * of one prior implementation, not part of any contract, and a record keyed on
+ * a name silently merges two different rows the day two of them share one.
+ */
+export declare function recordKey(type: string, id: string | number): string;
+/** The identity a payload carries, or `undefined` if it is not a record. */
+export interface PayloadIdentity {
+    readonly key: string;
+    readonly type: string;
+    readonly id: string;
+}
+export declare function payloadIdentity(payload: RecordPayload): PayloadIdentity | undefined;
+/**
+ * A `{__stale:true, id, __model}` ping: an invalidation the backend sends
+ * under the normal event name with NO `__type` at all.
+ *
+ * Recognised by name and dropped, because keying it would need a type it does
+ * not have — and guessing one from `__model` (a PHP class name) is exactly the
+ * sort of inference that produces a store full of records nothing reads.
+ */
+export declare function isStalePing(payload: RecordPayload): boolean;
+/**
+ * The tombstone marker, or `undefined`.
+ *
+ * BOTH SPELLINGS, deliberately. A `deleted` event carries `deleted_at`; a
+ * soft-delete arriving as an `updated` event carries `__deleted_at`. The prior
+ * art in this codebase checks only the second, so its delete handling has never
+ * run once — the payload says `deleted_at` and the store asks for
+ * `__deleted_at`.
+ */
+export declare function tombstoneAt(payload: RecordPayload): string | undefined;
+/**
+ * True when the payload says, in so many words, that the record is NOT
+ * deleted — which is what un-deletes a tombstoned record.
+ *
+ * Needed because absent keeps the previous value: without this, a record that
+ * was tombstoned could never come back, even when the server says it has.
+ */
+export declare function explicitlyUndeleted(payload: RecordPayload): boolean;
+/**
+ * Normalize `__timestamp` to milliseconds.
+ *
+ * IT ARRIVES IN TWO UNITS, 1000x APART, and this is verified rather than
+ * theoretical: the backend reads the model's `updated_at` in MILLISECONDS when
+ * the model has that column, and falls back to a SECONDS-resolution wall clock
+ * when it does not. At least one real model has no `updated_at` column at all.
+ *
+ * A comparison across the two units is not merely wrong, it is CONSISTENTLY
+ * wrong in one direction: a seconds value is ~1000x smaller, so it always
+ * loses to a milliseconds value and such a record would never update again.
+ *
+ * An implausible magnitude — below either window — is a contract violation,
+ * and it is surfaced rather than coerced. It returns `undefined`, which means
+ * "cannot adjudicate": the write is still ACCEPTED (a bogus tiny number must
+ * not be allowed to make a record permanently un-writable), it just cannot
+ * refuse anything.
+ */
+export declare function normalizeTimestamp(raw: unknown): number | undefined;
+/**
+ * Keys the store INTERPRETS rather than stores.
+ *
+ * Everything `__`-prefixed is envelope by this wire format's own convention,
+ * and two of them would actively break the store if kept as data:
+ * `__broadcasted_at` moves on every delivery, so storing it would make an
+ * identical redelivered payload look like a change and re-render the world —
+ * which is the exact cost the notify-only-if-changed rule exists to avoid.
+ *
+ * `deleted_at` is here because it is the tombstone marker, not a field.
+ */
+export declare function isEnvelopeKey(key: string): boolean;

package/dist/types/lib/reduced-motion-help.d.ts

@@ -0,0 +1,23 @@
+export type HostPlatform = "windows" | "macos" | "ios" | "android" | "unknown";
+/** The parts of `navigator` the detection reads. `userAgentData` is Chromium-only; everything else has `userAgent`. */
+export interface PlatformSource {
+    userAgent: string;
+    maxTouchPoints?: number;
+    userAgentData?: {
+        platform?: string;
+    };
+}
+/**
+ * Which OS the page runs on: the client-hints platform where the browser has it, else the user-agent string.
+ * iPadOS reports a Mac user agent; a "Mac" with a touch screen is an iPad.
+ */
+export declare function detectPlatform(source: PlatformSource): HostPlatform;
+export interface ReducedMotionHelp {
+    platform: HostPlatform;
+    /** Where the setting is, in that OS's own words. */
+    steps: string;
+    /** A link that opens the setting directly, where the OS has one. */
+    href?: string;
+}
+/** `steps` is the wording per OS (the active `UiLocaleProvider`'s `themeMenu.osSteps`); this picks the one for `platform` and its settings link. */
+export declare function reducedMotionHelp(platform: HostPlatform, steps: Record<HostPlatform, string>): ReducedMotionHelp;

package/dist/types/lib/scroll-caret.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DXUI-33: scrolls `frame` just far enough that the caret is fully inside it. Does nothing when the frame does not
+ * scroll (the draft fits), when there is no caret, or when the caret is already in view. `getSelection` is passed in
+ * so a test can stub it.
+ */
+export declare function scrollCaretIntoView(frame: HTMLElement, selection?: Selection | null): void;

package/dist/types/lib/sim/createSimStore.d.ts

@@ -0,0 +1,18 @@
+import type { SimNamespace } from "./types";
+export interface SimStoreOptions {
+    /** @default "demo" */
+    namespace?: SimNamespace;
+}
+export interface SimStore<T> {
+    /** Reactive — re-renders on ANY write to this store, anywhere. */
+    useAll(): T[];
+    useById(id: string): T | undefined;
+    /** Non-reactive escape hatch — reading outside a component, e.g. a seeder. */
+    getAll(): T[];
+    create(item: T): Promise<T>;
+    update(id: string, patch: Partial<T>): Promise<T>;
+    remove(id: string): Promise<void>;
+    /** Back to `seed`. What "Regenerate demo data" calls, via `resetSimStores`. */
+    reset(): Promise<void>;
+}
+export declare function createSimStore<T>(key: string, seed: T[], getId: (item: T) => string, options?: SimStoreOptions): SimStore<T>;

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

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./createSimStore";
+export * from "./registry";
+export * from "./settings";
+export * from "./latency";

package/dist/types/lib/sim/latency.d.ts

@@ -0,0 +1,10 @@
+export declare class SimNetworkError extends Error {
+    constructor(message: string);
+}
+/**
+ * Awaits a delay scaled to `recordsTouched` and the Dev popover's current
+ * network-speed setting. `Instant` returns immediately rather than awaiting a
+ * zero-length timer — the difference between "no perceptible delay" and
+ * "every store call pays for a microtask it gets nothing from."
+ */
+export declare function simulateLatency(recordsTouched: number): Promise<void>;

package/dist/types/lib/sim/registry.d.ts

@@ -0,0 +1,14 @@
+import type { SimNamespace } from "./types";
+interface RegisteredStore {
+    namespace: SimNamespace;
+    reset: () => Promise<void>;
+}
+/** Called once by `createSimStore` itself — not a public store-authoring API. */
+export declare function registerSimStore(entry: RegisteredStore): () => void;
+/**
+ * Resets every registered store in `namespace`, or every store at all when
+ * omitted. Resolves once every reset has actually written back to
+ * LocalStorage and notified its subscribers.
+ */
+export declare function resetSimStores(namespace?: SimNamespace): Promise<void>;
+export {};