@kitlangton/knobs 0.0.0-stage → 0.2.0

package/dist/types/core/store.d.ts

@@ -0,0 +1,536 @@
+import { type CodeFormat } from "./code.js";
+import type { TokenPreset } from "./theme.js";
+import { type ReadoutInput, type ReadoutKeys, type Schema, type State, type Values } from "./schema.js";
+import { type StoragePort } from "./storage.js";
+import { type Variants } from "./variants.js";
+export type ThemeMode = "dark" | "light" | "auto";
+export type DensityMode = "compact" | "default" | "comfortable";
+export type RendererMode = "gpu" | "dom" | "auto";
+/** When a store's chip shows; see `ChipOptions.reveal`. */
+export type RevealMode = "hover" | "shortcut" | "always";
+/** The floating chip `attach` puts on an element, which grows into its panel. */
+export interface ChipOptions {
+    /** Text beside the cog, e.g. `"knobs"`. Just the cog by default. */
+    readonly label?: string;
+    /**
+     * When the chip shows. `"hover"`: while the element is hovered or focused. `"shortcut"`: hidden
+     * until `shortcut` turns on knobs mode (remembered for the tab), then on hover. `"always"`:
+     * whenever its panel is closed. `"hover"` in development, `"shortcut"` in production builds.
+     */
+    readonly reveal?: RevealMode;
+    /** The key that toggles knobs mode for `"shortcut"` chips: `"Alt+Shift+D"` (⌥⇧D) by default. */
+    readonly shortcut?: string;
+}
+export type ChangeSource = "local" | "remote" | "reset" | "preset" | "variant" | "undo" | "redo" | "randomize" | "mutate" | "compare";
+/**
+ * A key going into the hand and out of it: a drag or a press on its row, an inline edit, or a
+ * burst of arrow keys. Changes between a key's `start` and `end` are one gesture, so a host can
+ * open one undo entry at `start` and close it at `end`.
+ */
+export interface GestureEvent {
+    readonly key: string;
+    readonly phase: "start" | "end";
+}
+export interface ChangeMeta {
+    readonly source: ChangeSource;
+    readonly coalesce?: boolean;
+    readonly key?: string;
+    readonly group?: string;
+    /** A reset that went back to the active preset (see `Controls.activePreset`), not the defaults. */
+    readonly base?: boolean;
+}
+/**
+ * The preset last applied from the strip: a schema preset (by id) or a saved variant. It's the
+ * base Reset returns to and Random explores around.
+ */
+export interface PresetRef {
+    readonly kind: "preset" | "variant";
+    readonly id: string;
+}
+export interface ControlAction<V = State> {
+    readonly id?: string;
+    readonly label: string;
+    readonly group?: string;
+    readonly shortcut?: string;
+    run(values: V, controls: Controls<any>): void | string | Promise<void | string>;
+}
+/** One of a group's numbered presets; keys it leaves out sit at their defaults (see `groupPresets`). */
+export interface GroupPreset<V = State> {
+    readonly name: string;
+    readonly values: Partial<V>;
+}
+/**
+ * How a page card shows its group presets: `names` as segments ("Native · Tight · Airy"), `menu`
+ * as a compact drop-down showing the selected one's name, `numbers` as 1, 2, 3…; `auto` (the
+ * default) shows names while they fit beside the title, else the menu.
+ */
+export type GroupPresetDisplay = "auto" | "names" | "numbers" | "menu";
+/** Display labels, kept apart from the ids that identify groups, sections and presets. */
+export interface LabelOptions {
+    /** By group id: what its header shows (verbatim). Ids stay identity everywhere else. */
+    readonly groupLabels?: Readonly<Record<string, string>>;
+    /** By section id: what its heading shows. */
+    readonly sectionLabels?: Readonly<Record<string, string>>;
+    /** By preset id: what the preset strip shows, e.g. `{ default: "Native" }`. */
+    readonly presetLabels?: Readonly<Record<string, string>>;
+    /** Shorthand for `presetLabels.default`. */
+    readonly defaultLabel?: string;
+    /** How a page card shows its group presets (see `GroupPresetDisplay`). */
+    readonly groupPresetDisplay?: GroupPresetDisplay;
+    /** By group id: one muted line under its card's title on a page, over fields' `groupDescription`. */
+    readonly groupDescriptions?: Readonly<Record<string, string>>;
+    /** By section id: one muted line under its heading on a page, over fields' `sectionDescription`. */
+    readonly sectionDescriptions?: Readonly<Record<string, string>>;
+}
+/**
+ * How a page's sections start: `true` folds every section to its heading, or by section id. A
+ * section neither names keeps its fields' `sectionFolded`, else starts open.
+ */
+export type SectionFolded = boolean | Readonly<Record<string, boolean>>;
+/** Panel commands with a key binding; see `MountPanelOptions.keys`. */
+export type PanelCommand = "random" | "mutate" | "reset" | "resetAll" | "compare" | "hint" | "undo" | "redo" | "copy" | "save" | "lock" | "presets" | "group" | "first" | "help" | "menu" | "leave";
+/**
+ * Remaps (a single character, or a key name such as `"F2"`) or turns off (`false`) a panel's key
+ * bindings. Unlisted commands keep their default key. `true` keeps the default.
+ */
+export type PanelKeys = {
+    readonly [C in PanelCommand]?: string | boolean;
+} & {
+    /** `false` drops the j/k and h/l aliases: only the arrows move and adjust; the letters reach the page. */
+    readonly vim?: boolean;
+    /**
+     * `false` stops digits, `.`, `-` and Enter from opening a slider's inline number editor (they
+     * reach the page); clicking the readout still edits.
+     */
+    readonly edit?: boolean;
+    /** What ⇧ multiplies an arrow's step by; 10 by default. */
+    readonly bigStep?: number;
+    /** `false` stops ↑/↓ at the first and last rows instead of wrapping around. */
+    readonly wrap?: boolean;
+};
+/** `glass` (the default): ticks with a faint ring. `mech`: drier, the rings all but gone. */
+export type SoundTheme = "glass" | "mech";
+/** A mount's `sound`, beyond `true`. */
+export interface SoundOptions {
+    /** This panel's level, 0–1 (times `sound.volume`). */
+    readonly volume?: number;
+    readonly theme?: SoundTheme;
+}
+/** A header button (see `MountPanelOptions.header`). */
+export type HeaderButton = "random" | "reset" | "copy" | "undo" | "redo" | "help" | "close";
+export interface HeaderOptions {
+    /** `false` hides the title; the buttons stay at the right. */
+    readonly title?: boolean;
+    /**
+     * Which buttons show (of those that are on). All but `help` by default: its `?` key opens the
+     * shortcuts either way, and the title's tooltip says so. List `"help"` to bring the button back.
+     */
+    readonly buttons?: readonly HeaderButton[];
+}
+export interface MountPanelOptions extends LabelOptions {
+    readonly title?: string | false;
+    /**
+     * Key bindings. An inline panel only ever hears keys while focus is inside it; pass this to remap
+     * or turn off commands so they don't shadow the host's own keys, e.g.
+     * `{ random: false, mutate: false, compare: false, hint: false, undo: false }` or `{ hint: "f" }`.
+     * The `?` popover and hint badges list only what's enabled.
+     */
+    readonly keys?: PanelKeys;
+    /**
+     * Hint mode's reach. `"page"` (the default): `s` labels every visible control in every panel
+     * and knobs/ui piece on the page (and the host's `data-hint` elements), so pressed here or
+     * anywhere outside a text field it jumps across all of them; with nothing else on the page it's
+     * this panel's alone, as always. `"panel"`: `s` here labels only this panel's controls, and they
+     * don't join the page's. `keys: { hint: false }` turns hint mode off here either way.
+     */
+    readonly hints?: "page" | "panel";
+    /**
+     * `false` hides what says a value differs from its default: modified dots and readout marks,
+     * group reset icons and the header's Reset. For panels whose values belong to someone else
+     * (a prototype's settings), where "default" means nothing. The store's `marks` by default.
+     */
+    readonly marks?: boolean;
+    /** Token values to style the panel with, e.g. `problemsPreset` (see `TokenPreset`). */
+    readonly preset?: TokenPreset;
+    /**
+     * `false` drops the header (title and buttons) for a host that draws its own. An object keeps
+     * it and chooses what shows: `{ title: false, buttons: ["random", "undo", "redo"] }`. A button
+     * left out keeps its key; a command that's off (`keys`) loses its button either way. Without a
+     * list, every button but `help` shows (see `HeaderOptions`).
+     */
+    readonly header?: boolean | HeaderOptions;
+    /**
+     * `false`: no per-tab session, so a rebuilt panel doesn't take focus back to the row it last
+     * had or reopen editors and folded groups. On while the store has storage.
+     */
+    readonly session?: boolean;
+    /** Groups folded (`true`) or open (`false`) at first, over their fields' `folded`. */
+    readonly groupFolded?: Readonly<Record<string, boolean>>;
+    /** Sub-headings (fields' `subsection`) that start folded (`true`), by name. */
+    readonly subsectionFolded?: Readonly<Record<string, boolean>>;
+    /**
+     * The tab strip's order and labels: tab ids, or `{ id, label }`. Tabs the fields name that
+     * aren't listed follow in the order they first appear.
+     */
+    readonly tabs?: readonly (string | {
+        readonly id: string;
+        readonly label?: string;
+    })[];
+    /** The tab shown first; otherwise the one last shown for these controls, else the first. */
+    readonly tab?: string;
+    /** Called when the shown tab changes (by a click, a key or `panel.tab()`). */
+    readonly onTab?: (tab: string) => void;
+    /**
+     * A search field under the header that filters rows by label, key or group as you type, with
+     * filter chips (`"modified"`, with its count, by default). `/` focuses it.
+     */
+    readonly search?: boolean | SearchOptions;
+    /**
+     * A group's Random (its die, `g`, ⌥ for Mutate) asks the host first: returning `true` means the
+     * host rolled the group itself (its own seeded "Randomize <group>"), and the panel only tumbles
+     * the die.
+     */
+    readonly groupRandom?: (group: string, mode: "random" | "mutate") => boolean | void;
+    /**
+     * A node for a row's accessory slot, just after its label (a pin, a marker), or null. Called
+     * with the row's key when the row is built; `panel.updateAccessories()` asks again. The node
+     * stays the host's: style it, listen on it. With the WebGPU renderer it stays DOM (see README).
+     */
+    readonly rowAccessory?: (key: string) => Node | null;
+    /**
+     * Light haptic ticks on phones (a stepped slider crossing a stop, the default's magnet, a
+     * choice changing mid-pan, a switch flipping); on by default, `false` turns them off.
+     * Reduced motion turns them off too.
+     */
+    readonly haptics?: boolean;
+    /**
+     * Sound effects: quiet, short ticks and clicks synthesized live for the panel's moments (a
+     * slider's detents, a switch, Random, Copy…). Off by default; `true` turns them on, or
+     * `{ volume, theme }`. The page's switch (`sound.enable(false)` from `knobs/panel`) mutes every
+     * panel, and the `?` popover offers it as Sounds, kept in the store's storage.
+     */
+    readonly sound?: boolean | SoundOptions;
+    /** Called once the panel is mounted, with a handle to focus it (a host's "Tune" key). */
+    readonly onReady?: (panel: PanelHandle) => void;
+    /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
+    readonly copy?: () => string;
+    readonly theme?: ThemeMode;
+    readonly density?: DensityMode;
+    readonly renderer?: RendererMode;
+    readonly variants?: boolean;
+    readonly history?: boolean;
+    readonly footer?: boolean;
+    readonly actions?: readonly ControlAction<any>[];
+    readonly onClose?: () => void;
+}
+/** A search field's filter chip: it narrows the rows to those `test` accepts. */
+export interface SearchChip {
+    readonly id: string;
+    readonly label: string;
+    /** Shows how many rows it would keep beside its label. */
+    readonly count?: boolean;
+    test(key: string, controls: Controls<any>): boolean;
+}
+export interface SearchOptions {
+    readonly placeholder?: string;
+    /** `"modified"` (rows off their defaults) or chips of your own; `["modified"]` by default. */
+    readonly chips?: readonly ("modified" | SearchChip)[];
+}
+/**
+ * An undo stack the host owns (an editor's ⌘Z that covers more than these values). The panel's
+ * undo and redo buttons and keys call it; compare (hold `\`) still previews knobs' own last entry.
+ */
+export interface HostHistory {
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Called when `canUndo` or `canRedo` may have changed; returns an unsubscribe. */
+    subscribe?(cb: () => void): () => void;
+}
+/**
+ * What `storage` keeps: `"all"` (values, locks and saved variants; the default), `"variants"`
+ * (only saved variants, for values the host owns) or `"none"`.
+ */
+export type PersistMode = "all" | "variants" | "none";
+export interface SyncOptions {
+    /** Keys missing from `values` return to their defaults. */
+    readonly replace?: boolean;
+    /**
+     * Keys whose values differ across what the host is showing (a multi-selection): they show an
+     * indeterminate "—" until edited. Replaces the store's mixed keys (see `Controls.setMixed`).
+     */
+    readonly mixed?: readonly string[];
+    /**
+     * A different item arrived: panels place the values without springing or rolling, and undo
+     * history starts over (it belonged to the previous item).
+     */
+    readonly land?: boolean;
+}
+/** A mounted panel: what `mount` hands `onReady`. */
+export interface PanelHandle {
+    readonly element: HTMLElement;
+    focus(): void;
+    dispose(): void;
+}
+/**
+ * The panel module a shipped store mounts with: `() => import("knobs/panel")`. Structural, so the
+ * core never imports the panel itself.
+ */
+export interface PanelModule {
+    mountPanel(controls: Controls<any>, container: HTMLElement, options?: MountPanelOptions): PanelHandle;
+    attach(controls: Controls<any>, element: HTMLElement, chip?: ChipOptions): () => void;
+}
+export interface ControlsOptions<S extends Schema> extends LabelOptions {
+    enabled?: boolean | (() => boolean);
+    /**
+     * Ships this store as product UI: it stays live in production builds (where stores are
+     * otherwise locked to their defaults) and mounts panels from the module this loads, e.g.
+     * `ship: () => import("knobs/panel")`. `enabled` defaults to true. Stores without it stay
+     * dev-only and ship constants.
+     */
+    ship?: () => Promise<PanelModule>;
+    /** The chip `attach` shows: its label, when it shows and the knobs-mode key (see `ChipOptions`). */
+    chip?: ChipOptions;
+    /**
+     * The longest (ms) a key changed here outranks incoming values for it (see `sync`), so an echo
+     * of an older value still in flight can't pull it back. The hold ends early once the remote
+     * reports the value that was sent (for numbers, within half a step). 0 by default; remote
+     * controls use 600. Raise it for peers that acknowledge slowly.
+     */
+    echo?: number;
+    storage?: StoragePort | null;
+    /** What `storage` keeps: everything, only saved variants, or nothing (see `PersistMode`). */
+    persist?: PersistMode;
+    /**
+     * The source Random and Mutate draw from, `[0, 1)` like `Math.random` (the default). Pass a
+     * seeded generator to make a roll reproducible.
+     */
+    random?: () => number;
+    /**
+     * Whether Random and Mutate may change a key, beside locks and each field's `random: false`
+     * (e.g. never seeds or structural pickers).
+     */
+    tunable?: (key: keyof S & string, values: Values<S>) => boolean;
+    /** An undo stack the host owns; undo and redo call it (see `HostHistory`). */
+    history?: HostHistory;
+    presets?: Readonly<Record<string, Partial<Values<S>>>>;
+    /**
+     * Numbered presets per group, shown as 1, 2, 3… on the group's card in a page. A group's
+     * presets cover every key any of them names; keys a preset leaves out are at their defaults,
+     * so `{ name: "Today", values: {} }` is the shipped look.
+     */
+    groupPresets?: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
+    actions?: readonly ControlAction<Values<S>>[];
+    theme?: ThemeMode;
+    density?: DensityMode;
+    renderer?: RendererMode;
+    /** Default key bindings for this store's panels (see `MountPanelOptions.keys`). */
+    keys?: PanelKeys;
+    /** `false`: its panels show no modified marks or resets (see `MountPanelOptions.marks`). */
+    marks?: boolean;
+    /** How its groups start, folded or open, under the mount's `groupFolded` (see there). */
+    groupFolded?: Readonly<Record<string, boolean>>;
+    /** How a page's sections start, under the mount's `sectionFolded` (see `SectionFolded`). */
+    sectionFolded?: SectionFolded;
+    onChange?: (patch: Partial<Values<S>>, values: Values<S>, meta: ChangeMeta) => void;
+    /** A key went into the hand or out of it (see `GestureEvent`). */
+    onGesture?: (event: GestureEvent) => void;
+    onReset?: (target: {
+        key?: keyof S & string;
+        group?: string;
+    }) => void;
+    /** An action row was pressed (after its own `run`), or a toolbar button (with its item's id). */
+    onAction?: (key: string) => void;
+    /** A group's numbered preset was applied (after its values are set). */
+    onPreset?: (target: {
+        group: string;
+        index: number;
+        name: string;
+    }) => void;
+}
+export interface Controls<S extends Schema = Schema> {
+    readonly id: string;
+    readonly schema: S;
+    readonly locked: Values<S>;
+    readonly enabled: boolean;
+    readonly storage: StoragePort | null;
+    /** What `storage` keeps (see `PersistMode`). */
+    readonly persist: PersistMode;
+    readonly presets: Readonly<Record<string, Values<S>>>;
+    readonly variants: Variants<Values<S>>;
+    readonly actions: readonly ControlAction<Values<S>>[];
+    readonly theme: ThemeMode;
+    readonly density: DensityMode;
+    readonly renderer: RendererMode;
+    readonly keys: PanelKeys | undefined;
+    readonly marks: boolean;
+    /** The chip's options, with `reveal` and `shortcut` resolved. */
+    readonly chip: ChipOptions & {
+        readonly reveal: RevealMode;
+        readonly shortcut: string;
+    };
+    /** How page cards show group presets (`groupPresetDisplay`, `auto` by default). */
+    readonly groupPresetDisplay: GroupPresetDisplay;
+    /** A group's display label (`groupLabels`, else its fields' `groupLabel`), if it has one. */
+    groupLabel(group: string): string | undefined;
+    /** A section's display label (`sectionLabels`, else its fields' `sectionLabel`), if it has one. */
+    sectionLabel(section: string): string | undefined;
+    /** A group's description (`groupDescriptions`, else its fields' `groupDescription`), if any. */
+    groupDescription(group: string): string | undefined;
+    /** A section's description (`sectionDescriptions`, else its fields' `sectionDescription`), if any. */
+    sectionDescription(section: string): string | undefined;
+    /** How groups start (`groupFolded`), as given; panels read it under their own `groupFolded`. */
+    readonly groupFolded: Readonly<Record<string, boolean>> | undefined;
+    /** How a page's sections start (`sectionFolded`), as given. */
+    readonly sectionFolded: SectionFolded | undefined;
+    /** A preset's display label (`presetLabels`, `defaultLabel`), else its id. */
+    presetLabel(id: string): string;
+    readonly error: string | null;
+    get(): Values<S>;
+    getServerSnapshot(): Values<S>;
+    /** Apply a change. `coalesce` folds it into the previous history entry (used while dragging). */
+    set(patch: Partial<Values<S>>, options?: {
+        coalesce?: boolean;
+        source?: ChangeSource;
+        key?: string;
+        group?: string;
+    }): void;
+    /**
+     * Apply external state (props, a server, a peer) without recording undo history or emitting a
+     * local change. A key that is held (in hand, or changed here within `echo` ms) keeps its value;
+     * the newest incoming value for it lands when the hold ends.
+     */
+    sync(values: Partial<Values<S>>, options?: SyncOptions): void;
+    /**
+     * Marks a key as in hand (a drag, an inline edit) or lets it go. While held, `sync` doesn't
+     * touch it; letting go applies the newest value that arrived meanwhile. Panels call this.
+     */
+    hold(key: string, held?: boolean): void;
+    /** Whether incoming values for `key` are held back right now (see `sync`). */
+    isHeld(key: string): boolean;
+    /**
+     * Presses an action row: its `run`, then `onAction(key)`. For a toolbar, `item` names the
+     * button (its id, else its label) and `onAction` gets the item's id.
+     */
+    action(key: keyof S & string, item?: string): void;
+    /**
+     * Shows a live value in a readout row (`watch`, `sparkline`, `graph`, `meter`, `table`, `log`):
+     * a number or text, a sample for a history, `{ [series]: number }` for a graph, rows for a
+     * table, an entry for a log. `null` clears it. Rows redraw at most once a frame and sleep
+     * when nothing arrives; nothing is recorded in the values, history or storage.
+     */
+    watch<K extends ReadoutKeys<S>>(key: K, value: ReadoutInput<S[K]>): void;
+    /** The latest value pushed to a readout (`undefined` before any). */
+    watched(key: ReadoutKeys<S>): unknown;
+    /** True while the change being notified landed (`sync(…, { land: true })`): place, don't animate. */
+    readonly landing: boolean;
+    undo(): void;
+    redo(): void;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    subscribe(cb: () => void): () => void;
+    /**
+     * Back to the active preset (see `activePreset`) while anything differs from it, else to the
+     * defaults: every field, or only `keys`. Reaching the defaults with every field also forgets
+     * the active preset. Locks don't apply; disabled and read-only fields keep their values.
+     */
+    reset(keys?: readonly (keyof S & string)[]): void;
+    /** One key, as `reset` does: to the active preset's value, else (already there) its default. */
+    resetKey(key: keyof S & string): void;
+    /**
+     * A group, as `reset` does: to its active group preset (or the panel's active preset) while it
+     * differs from it, else to its defaults, which forgets the group's preset.
+     */
+    resetGroup(group: string): void;
+    /** Whether the key (or anything) differs from the active preset; the defaults without one. */
+    isModified(key?: keyof S & string): boolean;
+    /** Whether `reset` (of every field, or `keys`) would change anything. */
+    canReset(keys?: readonly (keyof S & string)[]): boolean;
+    /** What differs from the defaults (the values `code()` and Swift export care about). */
+    modified(): Partial<Values<S>>;
+    /**
+     * Random values for every field that can roll (see `canRoll`), or those among `keys`, drawn
+     * from `random`. With an active preset, they land near its values (see `AROUND`) instead of
+     * anywhere in range. One undo step.
+     */
+    randomize(keys?: readonly (keyof S & string)[]): void;
+    /** Small changes around the current values instead of a re-roll; skips what can't roll. */
+    mutate(keys?: readonly (keyof S & string)[]): void;
+    /** Keeps fields out of Random and Mutate (or lets them back in). Saved with the values. */
+    lock(keys: (keyof S & string) | readonly (keyof S & string)[], locked?: boolean): void;
+    isLocked(key: keyof S & string): boolean;
+    /**
+     * The combination that presses an action row now, or a toolbar's button (`item`, its id or
+     * label): the user's rebinding, else the declared `shortcut`; `""` when cleared, undefined
+     * when there's none.
+     */
+    shortcut(key: keyof S & string, item?: string): string | undefined;
+    /**
+     * Rebinds an action row's shortcut (or a toolbar button's): a combination, `""` for none, or
+     * undefined to restore the declared one. Not undoable; saved with the values, as locks are.
+     */
+    rebind(key: keyof S & string, combo: string | undefined, item?: string): void;
+    /**
+     * Whether Random and Mutate may change `key`: it holds a value and isn't locked, `random:
+     * false`, refused by `tunable`, disabled or read-only.
+     */
+    canRoll(key: keyof S & string): boolean;
+    /** Whether the field is disabled now (`disabled`, static or from the values). */
+    isDisabled(key: keyof S & string): boolean;
+    /** Whether the field is read-only now (`readOnly`, static or from the values). */
+    isReadOnly(key: keyof S & string): boolean;
+    /**
+     * Asks panels to read again what they derive without new values: function `disabled` and
+     * `readOnly` flags (which may read state elsewhere, another store's say) and row accessories.
+     */
+    refresh(): void;
+    /**
+     * Marks keys as mixed (a multi-selection whose items differ): panels show "—" until the key is
+     * edited, and the first edit reaches `onChange` even when it picks the value shown.
+     */
+    setMixed(keys: (keyof S & string) | readonly (keyof S & string)[], mixed?: boolean): void;
+    isMixed(key: keyof S & string): boolean;
+    /**
+     * While held, `get()` shows the values from before the last change (the previous undo entry);
+     * releasing restores the current ones. Nothing is recorded or stored; `onChange` reports
+     * `source: "compare"` both ways.
+     */
+    compare(hold: boolean): void;
+    readonly comparing: boolean;
+    /**
+     * Applies a preset and makes it the active one (`"default"` clears it); one undo step, or
+     * folded into the last with `coalesce` (a pan across the strip).
+     */
+    preset(id: string, options?: {
+        coalesce?: boolean;
+    }): void;
+    matchingPreset(): string;
+    /**
+     * The preset (or saved variant) last applied, which Reset returns to and Random explores
+     * around, or null. Kept with the values; forgotten by a reset to the defaults.
+     */
+    activePreset(): PresetRef | null;
+    /** The group preset last applied to `group` (0-based), or -1. */
+    activeGroupPreset(group: string): number;
+    /** The values Reset returns to first: the active presets over the defaults. */
+    baseValues(): Values<S>;
+    /** Each group's numbered presets, complete over the keys they cover. */
+    readonly groupPresets: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
+    /**
+     * Applies a group's preset (0-based) and makes it the group's active one, one undo step;
+     * `coalesce` folds it into the previous one (a pan across a card's presets).
+     */
+    groupPreset(group: string, index: number, options?: {
+        coalesce?: boolean;
+    }): void;
+    /** The group preset the current values match, or -1. */
+    matchingGroupPreset(group: string): number;
+    code(format?: CodeFormat, values?: Values<S>): string;
+    /** Shows the floating chip on `element`; `chip` overrides the store's chip options. */
+    attach(element: HTMLElement, chip?: ChipOptions): () => void;
+    mount(container: HTMLElement, options?: MountPanelOptions): () => void;
+}
+/** Whether two fields draw and behave the same (a reshape keeps such a key's value). */
+export declare function sameField(a: unknown, b: unknown): boolean;
+export declare function defineControls<const S extends Schema>(id: string, input: S, options?: ControlsOptions<S>): Controls<S>;

package/dist/types/core/theme.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A named set of `--k-*` token values for dark and light, applied to panels mounted with
+ * `{ preset }` (or with `data-preset="<name>"` and `presetCss(preset)` in your own stylesheet).
+ * `css` adds rules for anything tokens don't cover; `&` stands for the panel.
+ */
+export interface TokenPreset {
+    readonly name: string;
+    readonly dark: Readonly<Record<string, string | number>>;
+    readonly light?: Readonly<Record<string, string | number>>;
+    readonly css?: string;
+}
+/** The stylesheet for a preset: its dark tokens, its light ones wherever a panel is light. */
+export declare function presetCss(preset: TokenPreset): string;
+/**
+ * A dense, square editor (Arcade's Lab): radius 0, compact 26 px rows, the flat frame (groups as
+ * plain sections split by hairlines, no cards, and no panel card when inline), the Lab's greys
+ * and one blue accent, small type with monospaced readouts, and no glass, glow or lift. Mount it
+ * inside the host's own card or column.
+ */
+export declare const labPreset: TokenPreset;
+/**
+ * The Problems viewer's parameter panel: separate 34 px bars 4 px apart, its blue fill and
+ * labels, a spring card that stacks its curve over two sliders, washes that arrive at once and
+ * leave over 100 ms, and Problems' own slider spring (ω 34, ζ 0.86). An inline panel sheds its
+ * chrome to sit in the host's column. Every difference from the defaults is a token.
+ */
+export declare const problemsPreset: TokenPreset;

package/dist/types/core/variants.d.ts

@@ -0,0 +1,25 @@
+import { type Schema, type Values } from "./schema.js";
+import type { StoragePort } from "./storage.js";
+export interface Variant<V> {
+    readonly id: string;
+    readonly name?: string;
+    readonly values: V;
+}
+export interface Variants<V> {
+    readonly ready: boolean;
+    list(): readonly Variant<V>[];
+    save(name?: string): Variant<V>;
+    /**
+     * Applies a saved variant, making it the active preset (see `Controls.activePreset`); one undo
+     * step, or folded into the last with `coalesce` (a pan across the strip).
+     */
+    load(id: string, options?: {
+        coalesce?: boolean;
+    }): void;
+    /** Renames a saved variant (an empty name clears it); kept in storage with the variants. */
+    rename(id: string, name: string): void;
+    remove(id: string): void;
+    export(): string;
+    import(json: string): void;
+}
+export declare function createVariants<S extends Schema>(schema: () => S, id: string, key: string, storage: () => StoragePort | null, get: () => Values<S>, set: (v: Values<S>, id: string, coalesce: boolean) => void, notify: () => void, enabled: () => boolean): Variants<Values<S>>;

package/dist/types/index.d.ts

@@ -0,0 +1,14 @@
+export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, actionShortcut, watch, sparkline, graph, meter, table, log, hasValue, isReadout, wrapAngle, SPRING, type FieldMeta, type ActionField, type SpringPart, type ValueField, type Knob, type Choice, type Toggle, type SpringField, type ColorField, type PointField, type EasingField, type VecField, type Vec3, type RangeField, type AngleField, type SeedField, type KeybindField, type GradientField, type CurveField, type ToolbarField, type ToolbarItem, type ToolbarShortcut, type WatchField, type SparklineField, type GraphField, type GraphSeries, type GraphThreshold, type MeterField, type TableField, type LogField, type ReadoutField, type ReadoutKeys, type ReadoutInput, type Point, type Field, type Schema, type Values, type Value, type State, } from "./core/schema.js";
+export { springCss, springMotion, type SpringValue } from "./core/spring.js";
+export { colorHex, parseColor, type Oklch } from "./core/color.js";
+export { sampleGradient, sampleCurve, gradientCss, CURVE_SHAPES, type GradientStop, type GradientSpace, type CurvePoint, type CurveInterp, type SampleGradientOptions, type SampleCurveOptions, } from "./core/ramp.js";
+export { bezierCss, bezierPoint, EASINGS, type Bezier, type EasingName } from "./core/easing.js";
+export { AROUND } from "./core/random.js";
+export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, } from "./core/store.js";
+export { createRemoteControls, descriptorToField, formatSwift, fromDescriptors, fromSettings, type SettingsGroup, type SettingsItem, type ActionDescriptor, type ChoiceOption, type ControlDescriptor, type SpringBindingDescriptor, type ToolbarDescriptor, type ReadoutDescriptor, type ValueDescriptor, type RemoteControls, type RemoteControlsOptions, } from "./core/remote.js";
+export type { LogEntry, LogLevel, TableRows, WatchValue } from "./core/readout.js";
+export { memoryStorage, urlFlag, type StoragePort } from "./core/storage.js";
+export type { TokenPreset } from "./core/theme.js";
+export { formatCode, type CodeFormat } from "./core/code.js";
+export { comboFromEvent, letterOf, comboLabel, comboParts, matchesCombo, normalizeCombo, } from "./core/keys.js";
+export type { Variant, Variants } from "./core/variants.js";

package/dist/types/panel/attach.d.ts

@@ -0,0 +1,5 @@
+import type { ChipOptions, Controls } from "../core/store.js";
+import type { Schema } from "../core/schema.js";
+export declare function attach<S extends Schema>(controls: Controls<S>, element: HTMLElement, options?: ChipOptions): () => void;
+/** Parses `"Alt+Shift+D"` into a test for keydown events. Letters and digits match by key position. */
+export declare function matchShortcut(shortcut: string): (event: KeyboardEvent) => boolean;