@danxbot/ui 1.0.0

package/dist/types/lib/markdown/history.d.ts

@@ -0,0 +1,47 @@
+import type { SourceSelection } from "./position";
+export interface HistoryEntry {
+    source: string;
+    selection: SourceSelection | null;
+}
+/** What produced an edit, for deciding whether two of them belong together. */
+export type EditKind = "type" | "delete" | "compose" | "other";
+export interface HistoryOptions {
+    /** Quiet time after which the next edit starts a new group. */
+    groupMs?: number;
+    /** Entries kept. Beyond this the oldest are dropped. */
+    limit?: number;
+    /** Injected so tests are deterministic; never read a clock directly. */
+    now?: () => number;
+}
+export declare class History {
+    private readonly entries;
+    private index;
+    private readonly groupMs;
+    private readonly limit;
+    private readonly now;
+    /** State of the group currently open for merging. */
+    private lastAt;
+    private lastKind;
+    private lastEnd;
+    constructor(initial: HistoryEntry, options?: HistoryOptions);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** Entry count, for tests that assert coalescing rather than behaviour. */
+    get size(): number;
+    /**
+     * Records a state.
+     *
+     * `at` is where the edit happened; adjacency to the previous edit is what
+     * separates "still typing" from "went somewhere else and typed". Passing the
+     * position rather than deriving it from the diff is deliberate — a diff of
+     * two strings finds the shortest edit, which is not always the edit that
+     * happened, and coalescing decisions made from the wrong position are worse
+     * than none.
+     */
+    record(entry: HistoryEntry, kind: EditKind, at: number): void;
+    private shouldMerge;
+    /** Forces the next edit to open a new group — a selection change, a blur. */
+    break(): void;
+    undo(): HistoryEntry | null;
+    redo(): HistoryEntry | null;
+}

package/dist/types/lib/markdown/hotkeys.d.ts

@@ -0,0 +1,39 @@
+import { type Command } from "./commands";
+export type HotkeyGroup = "formatting" | "headings" | "lists" | "blocks" | "tables";
+export interface Hotkey {
+    /**
+     * The chord this matches: lower-case, modifiers first, in the order ctrl,
+     * alt, shift.
+     *
+     * PUNCTUATION IS SPELLED BY PHYSICAL KEY (`bracketleft`, `comma`), not by the
+     * character it produces. The browser probe found why: with Shift held, the
+     * `[` key reports `event.key === "{"`, so a table keyed on `[` never matched
+     * and Ctrl+Shift+[ was silently inert. `event.code` is the same regardless of
+     * which character the modifier produced.
+     */
+    key: string;
+    /** What the help surface shows, which is the chord as a person types it. */
+    label: string;
+    description: string;
+    group: HotkeyGroup;
+    command: Command;
+}
+export declare const HOTKEYS: readonly Hotkey[];
+/**
+ * The chords a key event could be, most specific first.
+ *
+ * TWO SPELLINGS, because neither alone is enough. The CHARACTER spelling is
+ * what a letter or digit chord needs — Ctrl+B is the letter B whatever key
+ * produced it. The PHYSICAL spelling is what punctuation needs: with Shift
+ * held, the `[` key reports `event.key === "{"`, so a table keyed on the
+ * character never matches and the chord is silently inert. The browser probe
+ * found exactly that: Ctrl+Shift+[ did nothing at all, and nothing in the unit
+ * suite could have seen it, because the commands themselves were correct.
+ *
+ * Modifiers in a FIXED order, because `ctrl+shift+s` and `shift+ctrl+s` are the
+ * same chord and a table keyed on free-form strings silently misses one of
+ * them. `metaKey` folds into `ctrl` so one table serves macOS, where the
+ * platform convention is Command for every one of these.
+ */
+export declare function chordsOf(event: KeyboardEvent): string[];
+export declare function hotkeyFor(event: KeyboardEvent): Hotkey | null;

package/dist/types/lib/markdown/input.d.ts

@@ -0,0 +1,15 @@
+import type { MarkdownSurface } from "./surface";
+export interface InputOptions {
+    /**
+     * Called for an intent this layer cancelled but did not act on.
+     *
+     * Not a warning to be silenced — it is the list of what phase 4 owes. An
+     * editor that quietly ignores `formatBold` looks like one where Ctrl+B is
+     * broken, and this is how that gets noticed before a user reports it.
+     */
+    onUnhandled?: (inputType: string) => void;
+}
+/**
+ * Binds the input layer to a surface. Returns the unbind function.
+ */
+export declare function attachInput(surface: MarkdownSurface, options?: InputOptions): () => void;

package/dist/types/lib/markdown/keys.d.ts

@@ -0,0 +1,34 @@
+import type { CaretMap } from "./caret-map";
+import { type Edit } from "./edit";
+import type { SourceSelection } from "./position";
+import type { Projection } from "./project";
+export type KeyIntent = {
+    kind: "insert";
+    text: string;
+} | {
+    kind: "backspace";
+} | {
+    kind: "delete";
+} | {
+    kind: "enter";
+} | {
+    kind: "lineBreak";
+} | {
+    kind: "tab";
+} | {
+    kind: "shiftTab";
+};
+/** Everything a decision needs, and nothing it does not. */
+export interface KeyContext {
+    source: string;
+    projection: Projection;
+    map: CaretMap;
+}
+/**
+ * The edit a keystroke produces, or null to let the caller decline the key.
+ *
+ * Null is a real answer and not a failure: Tab outside a list declines so focus
+ * can leave the editor, which is what makes the WCAG 2.1.2 keyboard trap not
+ * happen in the first place.
+ */
+export declare function resolveKey(ctx: KeyContext, selection: SourceSelection, intent: KeyIntent): Edit | null;

package/dist/types/lib/markdown/paste.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts one pasted HTML fragment to markdown.
+ *
+ * `parser` is injected so this stays testable and so it never reaches for a
+ * global — the editor passes its own document, and a test passes whatever it
+ * has. A module that grabs `window` is a module that cannot be tested without
+ * one.
+ */
+export declare function htmlFragmentToMarkdown(html: string, parse: (html: string) => Document): string;

package/dist/types/lib/markdown/position.d.ts

@@ -0,0 +1,43 @@
+export interface DomPoint {
+    /**
+     * Usually a text node. It is an ELEMENT when the position has no text of its
+     * own to sit in — beside a picture, say, where every character of the
+     * construct is markup and every markup node is zero-width. An element point
+     * names a place BETWEEN children, which is a position the browser renders a
+     * caret for and `sourceOffsetAt` already knows how to read back.
+     */
+    node: Node;
+    offset: number;
+}
+/** Which side of a boundary an offset belongs to when two runs meet there. */
+export type Association = "before" | "after";
+export declare function domPointAt(root: Node, offset: number, association?: Association): DomPoint | null;
+/**
+ * The source offset for a DOM point.
+ *
+ * Accepts an ELEMENT container as well as a text node, because that is what a
+ * browser hands back: a selection at the start of an empty paragraph, or one
+ * that landed between two children, is reported as `(element, childIndex)`.
+ * Resolving it here rather than at each call site is the difference between one
+ * correct conversion and six approximate ones.
+ *
+ * Returns null for a point in a subtree this module did not build, which is a
+ * REAL event — the browser creates nodes during composition and on paste — and
+ * the caller must handle it as one rather than substitute a plausible number.
+ */
+export declare function sourceOffsetAt(root: Node, node: Node, offset: number): number | null;
+export interface SourceSelection {
+    anchor: number;
+    head: number;
+}
+/** The current selection as source offsets, or null if it is not in `root`. */
+export declare function readSelection(root: HTMLElement): SourceSelection | null;
+/**
+ * Puts the selection at the given source offsets.
+ *
+ * DOES NOTHING IF IT ALREADY MATCHES. That is the first of the three rules both
+ * ProseMirror and CodeMirror carry verbatim: writing a selection that is already
+ * correct is itself a source of caret jumps, because some engines scroll,
+ * collapse or re-anchor on assignment even when nothing moved.
+ */
+export declare function writeSelection(root: HTMLElement, selection: SourceSelection, association?: Association): boolean;

package/dist/types/lib/markdown/project.d.ts

@@ -0,0 +1,88 @@
+import type { Frame, FrameRecord } from "../syntax/markdown/frames";
+/**
+ * A run of literal source characters.
+ *
+ * `syntax` is what the view collapses. It is not a rendering hint — it is the
+ * parser's own answer to "did any frame claim this as its text", so a run that
+ * says `syntax: false` is genuinely editable prose and one that says true is
+ * genuinely markup.
+ */
+export interface PText {
+    type: "text";
+    start: number;
+    end: number;
+    text: string;
+    syntax: boolean;
+    /**
+     * The highlight class this run carries, inside a fenced block.
+     *
+     * Only ever set for code, and only when a tokenizer was supplied. Prose stays
+     * untyped so it stays a BARE text node — see ../markdown/dom.ts, constraint 3:
+     * every wrapper around prose is another reason to replace a node, and a
+     * replaced node is a cancelled composition.
+     */
+    token?: string;
+}
+/** How a fenced block's body is highlighted, if the caller wants it. */
+export interface ProjectOptions {
+    /**
+     * Returns tokens with ABSOLUTE offsets into `source`, exactly as
+     * `lib/syntax`'s `tokenize` does.
+     *
+     * Injected rather than imported, and the reason is the same one the module
+     * header gives for not tokenizing at all before: reaching for the grammar
+     * REGISTRY from here would make a pure function's output depend on which
+     * languages happened to be registered when it ran. Passing it in keeps the
+     * projection reproducible and keeps this module's tests grammar-free.
+     */
+    highlight?: (code: string, language: string | null, at: number) => Array<{
+        start: number;
+        end: number;
+        type: string;
+    }>;
+}
+/** A frame with its projected children, in source order. */
+export interface PElement {
+    type: "element";
+    frame: Frame;
+    start: number;
+    end: number;
+    children: PNode[];
+}
+export type PNode = PText | PElement;
+/** The document root. `source` is kept so consumers never re-derive it. */
+export interface Projection {
+    source: string;
+    children: PNode[];
+    /** Every frame, in the order the parser opened them. */
+    frames: readonly FrameRecord[];
+}
+/**
+ * Thrown when the parser's frames do not nest, which would make the projection
+ * ambiguous.
+ *
+ * This is a FAIL-LOUD, not a repair. A projector that silently reordered
+ * overlapping frames would produce a tree that reads correctly and maps the
+ * caret to the wrong character — the exact defect this whole design exists to
+ * make impossible, reintroduced by the code meant to prevent it.
+ */
+export declare class ProjectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Projects a markdown string.
+ *
+ * The walk is linear over the SOURCE, descending into a frame when it starts
+ * and leaving when it ends. Every character is emitted exactly once, by
+ * exactly one of the two paths — inside a frame or at the document level —
+ * which is the invariant stated as an algorithm rather than as a test.
+ */
+export declare function project(source: string, options?: ProjectOptions): Projection;
+/**
+ * Reads a projection's text back, in document order.
+ *
+ * Deliberately dumb — no knowledge of frames, no special cases. The moment this
+ * function needs to know what a table is, the invariant has stopped being an
+ * invariant.
+ */
+export declare function projectedText(nodes: readonly PNode[]): string;

package/dist/types/lib/markdown/reconcile.d.ts

@@ -0,0 +1,63 @@
+import type { PNode } from "./project";
+/**
+ * Thrown when a patch would have had to disturb the node the browser is
+ * composing into.
+ *
+ * Loud rather than silent because the caller's contract is to DEFER the patch
+ * until `compositionend`, and a reconciler that quietly skipped the change
+ * would leave the DOM disagreeing with the model — which is the same corruption
+ * one step later, with nothing pointing at the cause.
+ */
+export declare class CompositionConflictError extends Error {
+    constructor(message: string);
+}
+export interface PatchOptions {
+    /**
+     * The text node the browser is composing into. Never written, moved or
+     * removed; a patch that would need to do any of those throws.
+     */
+    protect?: Text | null;
+}
+export interface PatchStats {
+    /** Text nodes whose `data` was assigned. */
+    textUpdated: number;
+    /** Text nodes left alone because their data already matched. */
+    textUntouched: number;
+    /** Elements reused in place. */
+    elementsReused: number;
+    /** Nodes created, which is the number the caret can be disturbed by. */
+    created: number;
+    removed: number;
+}
+/**
+ * Brings `parent`'s children into agreement with `nodes`.
+ *
+ * Positional rather than keyed, deliberately. A keyed diff by source offset
+ * looks more sophisticated and is worse here: every offset after an edit shifts
+ * by the length of that edit, so keys change for the whole rest of the document
+ * on every keystroke and the diff replaces everything the user has not touched.
+ * Position is stable under exactly the edits that matter — a change in the
+ * middle of a paragraph leaves the paragraph at the same index.
+ */
+export declare function patch(parent: HTMLElement, nodes: readonly PNode[], options?: PatchOptions): PatchStats;
+/**
+ * The source range a text node carries, or null if it was not built here.
+ *
+ * The range is stamped on the node rather than looked up in a side table on
+ * purpose: a WeakMap keyed by node is the same information one indirection
+ * away, and the indirection is where a stale entry hides. A node that has no
+ * stamp is a node the browser created — which is a real event during
+ * composition, and the caller must treat it as one rather than guess.
+ */
+export declare function rangeOf(node: Node): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Reads every text node under `root` in document order and joins it.
+ *
+ * This is the projection invariant, asserted against the REAL DOM rather than
+ * against the projection tree — which is a different claim and the one that
+ * actually matters. The tree can be right while the reconciler drops a node.
+ */
+export declare function domText(root: Node): string;

package/dist/types/lib/markdown/surface.d.ts

@@ -0,0 +1,177 @@
+import { type CaretMap } from "./caret-map";
+import { type Projection, type ProjectOptions } from "./project";
+import { type SourceSelection } from "./position";
+import { type EditKind, type HistoryOptions } from "./history";
+export interface SurfaceOptions {
+    /** Called after every committed change, with the new source. */
+    onChange?: (source: string) => void;
+    /** Undo tuning. The defaults are the constants the mature editors landed on. */
+    history?: HistoryOptions;
+    /**
+     * Highlights a fenced block. Injected, never imported: reaching for the
+     * grammar registry from the pure layer would make a projection depend on
+     * which languages happened to be registered when it ran. The component
+     * passes the real tokenizer; a test can pass none and get plain text.
+     */
+    highlight?: ProjectOptions["highlight"];
+    /**
+     * Called when the DOM stopped agreeing with the model and could not be
+     * repaired from it. Loud by default: this is the one failure that silently
+     * eats the user's text if it is swallowed.
+     */
+    onDesync?: (detail: string) => void;
+}
+export interface Splice {
+    start: number;
+    end: number;
+    text: string;
+}
+export declare class MarkdownSurface {
+    readonly root: HTMLElement;
+    private source;
+    private readonly options;
+    /** The text node the browser is composing into, if any. */
+    private composing;
+    /** A projection that arrived while composing, applied at `compositionend`. */
+    private deferred;
+    private observer;
+    /** Depth of "this mutation is ours, ignore it". */
+    private writing;
+    private readonly history;
+    /** True while applying an undo, so the undo is not itself recorded. */
+    private restoring;
+    /**
+     * Where the caret is allowed to be, rebuilt with every projection.
+     *
+     * Held rather than recomputed per keystroke because every deletion and every
+     * arrow key needs it, and it is a pure function of the projection that was
+     * just built anyway. It is never mutated — a new projection replaces it
+     * whole, which is the same "nothing is kept in step so nothing can drift"
+     * argument the projection itself rests on.
+     */
+    private caretStops;
+    /**
+     * The projection those stops were built from.
+     *
+     * Held for the same reason and handed to callers rather than re-derived: a
+     * deletion has to know which characters are markup and which construct owns
+     * them, and re-projecting to ask would parse the document twice per keypress.
+     */
+    private projection;
+    constructor(root: HTMLElement, source: string, options?: SurfaceOptions);
+    getSource(): string;
+    /** The projection the DOM currently shows, for callers that must read it. */
+    getProjection(): Projection;
+    /** Where the caret may legally be, for callers that have to reason about it. */
+    getCaretMap(): CaretMap;
+    /**
+     * The selection, snapped to positions that exist.
+     *
+     * SNAPPED RATHER THAN RETURNED RAW, because a click can land anywhere — the
+     * browser will happily put the caret at the edge of a zero-width marker, and
+     * every offset inside markup is now a place with no geometry. Normalising on
+     * the way IN means no caller downstream has to remember to.
+     */
+    getSelection(): SourceSelection | null;
+    /**
+     * Applies one splice and puts the caret where the inserted text ends.
+     *
+     * The caret is computed from the MODEL, never preserved from the DOM. That is
+     * the whole point of the design and also why it must be tested with a real
+     * caret in a real browser rather than asserted: a model-derived caret is
+     * exactly right or exactly wrong, with nothing in between.
+     */
+    apply(splice: Splice, select?: SourceSelection, kind?: EditKind): void;
+    /** Replaces the whole document, e.g. when the consumer's value prop changes. */
+    setSource(source: string): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    /**
+     * Ends the current undo group.
+     *
+     * Called when the user moves the caret deliberately, because an edit after a
+     * selection change is a different thought however soon it arrives — one of
+     * the three coalescing rules, and the one a timer alone cannot express.
+     */
+    breakUndoGroup(): void;
+    private restore;
+    /**
+     * Re-projects and patches, then restores the caret.
+     *
+     * Refuses outright while composing. The deferral is recorded rather than
+     * dropped, so `compositionend` knows it owes a render — a skipped render that
+     * nobody remembers is a DOM that disagrees with the model forever.
+     */
+    private render;
+    /**
+     * Puts the caret back on a legal position after the USER moved it.
+     *
+     * A click, a drag or a vertical arrow key can leave the browser's selection
+     * at the edge of a collapsed marker, which is a place with no geometry and no
+     * meaning. Snapping costs one write and no re-projection — re-rendering here
+     * would be wasted work AND a risk, since every patch is a chance to disturb a
+     * caret that was already where it belonged.
+     *
+     * Replaces `refreshActive`, which existed only to move the reveal.
+     */
+    snapCaret(): void;
+    /**
+     * Moves the caret one VISIBLE character, in the model, and writes the result.
+     *
+     * Returns false when there is no selection to move, so the caller can let the
+     * browser have the key rather than swallowing it.
+     *
+     * One press crosses a whole marker, however many characters it holds, because
+     * the positions inside it are not positions. That is the difference between
+     * this and the grapheme step it replaces: `stepOffset` counted source
+     * characters, and under a contract where markup is never shown, counting
+     * source characters makes the caret appear to stall.
+     */
+    moveCaret(direction: 1 | -1, extend: boolean): boolean;
+    /**
+     * Detects the third caret rule's failure: our own write left the browser's
+     * selection somewhere that is no longer a position in this document.
+     *
+     * Both mature codebases carry a detector for this because Chrome does it, and
+     * because the symptom — a caret that has silently moved to the top of the
+     * document — is indistinguishable from a bug in the edit itself.
+     */
+    private verifySelection;
+    /**
+     * Binds the composition lifecycle. Returns the unbind function.
+     *
+     * `compositionstart` captures the node the browser will mutate — read from
+     * the live selection, because that is the only place the browser says which
+     * one it chose.
+     */
+    bind(): () => void;
+    /**
+     * Reads a finished composition back into the model.
+     *
+     * A composition is confined to ONE text node inside one inline element, and
+     * that node carries the source range it came from — so reconciling is
+     * "replace source characters a..b with this node's current text". A handful
+     * of lines against a known range, rather than the 407-line document-wide
+     * DOM-to-markdown serialiser this design exists to avoid.
+     */
+    private reconcileComposed;
+    /**
+     * Everything `preventDefault` could not cancel arrives here.
+     *
+     * This path is not a safety net, it is a REQUIREMENT: Chrome on Android
+     * reports `cancelable: true` on `deleteContentBackward` and deletes anyway,
+     * `insertCompositionText` is non-cancelable by spec, and iOS dictation fires
+     * no composition events at all. An editor with no observation path is simply
+     * broken on those inputs, and cannot be told that it is.
+     *
+     * The repair is deliberately narrow: a character-data change to a stamped
+     * node is read back into its range. Anything structural means the browser
+     * built nodes we cannot map, and the honest response is to re-project from
+     * the model we still trust, not to guess at what it did.
+     */
+    private onMutations;
+    /** Runs `fn` with our own mutations invisible to the observer. */
+    private write;
+}

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

@@ -0,0 +1,40 @@
+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;
+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/preferences.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Document-level display preferences.
+ *
+ * All three of theme, size scale and motion work the same way: a value lives on
+ * `<html data-*>`, CSS reads it, and localStorage remembers it. Writing that
+ * three times would be three chances to diverge — so it is written once and
+ * specialised below.
+ *
+ * WHY `<html>` AND NOT REACT CONTEXT: the value has to reach plain CSS, not
+ * just components. Portalled content (dialogs, popovers, toasts) renders
+ * outside the React tree that would hold the context, and a preference that
+ * fails on exactly the overlay layers is worse than no preference at all.
+ */
+/**
+ * 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.
+ */
+export declare function applyPreference(attribute: string, value: string): void;
+export type Theme = "light" | "dark";
+export declare function useTheme(): {
+    theme: Theme;
+    setTheme: import("react").Dispatch<import("react").SetStateAction<Theme>>;
+    toggle: () => void;
+};
+export type UiScale = "sm" | "md" | "lg";
+export declare function useUiScale(): {
+    scale: UiScale;
+    setScale: import("react").Dispatch<import("react").SetStateAction<UiScale>>;
+    cycle: () => void;
+};
+/**
+ * `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 function useContrast(): {
+    contrast: ContrastPreference;
+    setContrast: import("react").Dispatch<import("react").SetStateAction<ContrastPreference>>;
+    toggle: () => void;
+};
+/**
+ * `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 function useMotionPreference(): {
+    motion: MotionPreference;
+    setMotion: import("react").Dispatch<import("react").SetStateAction<MotionPreference>>;
+    cycle: () => 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";