@kitlangton/knobs 0.1.0 → 0.2.0

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

@@ -1,2 +1,62 @@
-import { type Schema, type Values } from "./schema.js";
+import { type CurvePoint, type GradientStop } from "./ramp.js";
+import { type Schema, type ValueField, type Values } from "./schema.js";
+/** One field's roll across its whole range (see `randomValues`). */
+export declare function pick(field: ValueField, random: () => number): string | number | boolean | number[] | readonly [0.25, 0.1, 0.25, 1] | readonly [0.42, 0, 1, 1] | readonly [0, 0, 0.58, 1] | readonly [0.42, 0, 0.58, 1] | readonly [0, 0, 1, 1] | readonly [0.65, 0, 0.35, 1] | readonly [0.32, 0.72, 0, 1] | readonly [0.34, 1.56, 0.64, 1] | GradientStop[] | CurvePoint[] | {
+    duration: number;
+    bounce: number;
+    l?: undefined;
+    c?: undefined;
+    h?: undefined;
+    x?: undefined;
+    y?: undefined;
+    z?: undefined;
+} | {
+    l: number;
+    c: number;
+    h: number;
+    duration?: undefined;
+    bounce?: undefined;
+    x?: undefined;
+    y?: undefined;
+    z?: undefined;
+} | {
+    x: number;
+    y: number;
+    duration?: undefined;
+    bounce?: undefined;
+    l?: undefined;
+    c?: undefined;
+    h?: undefined;
+    z?: undefined;
+} | {
+    x: number;
+    y: number;
+    z: number;
+    duration?: undefined;
+    bounce?: undefined;
+    l?: undefined;
+    c?: undefined;
+    h?: undefined;
+};
+/**
+ * How far Random strays from an active preset. A number lands in a window 35% of its range wide,
+ * centred on the preset's value and slid inward at an end so it keeps its width: far enough to
+ * be a new take, near enough to stay recognisably that preset (Mutate moves 8–12% from the
+ * current values; a free roll covers 100%). Choices and opted-in switches keep the preset's
+ * pick, changing `switch` of the time. Colours keep their family: hue within ±`hue`°,
+ * lightness ±`lightness`, chroma ±`chroma` of what that hue can hold. Seeds roll freely: a new
+ * pattern is what a seed is for.
+ */
+export declare const AROUND: {
+    readonly spread: 0.35;
+    readonly switch: 0.3;
+    readonly hue: 20;
+    readonly lightness: 0.06;
+    readonly chroma: 0.15;
+};
+/**
+ * One field's roll around `base` (an active preset's value): see `AROUND`. Fields with nothing
+ * to vary around (keys, seeds) roll as `pick` does.
+ */
+export declare function around(field: ValueField, base: unknown, random: () => number): unknown;
 export declare function randomValues<S extends Schema>(schema: S, random?: () => number): Values<S>;

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

@@ -26,9 +26,11 @@ export interface SpringBindingDescriptor extends DescriptorMeta {
     };
     readonly default?: SpringValue;
 }
-/** A button row: pressing it calls `onAction(key)`. */
+/** A button row: pressing it calls `onAction(key)`. `shortcut` takes a combination here. */
 export interface ActionDescriptor extends DescriptorMeta {
     readonly kind: "action";
+    readonly global?: boolean;
+    readonly rebind?: boolean;
     readonly default?: undefined;
     readonly bind?: undefined;
 }

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

@@ -20,7 +20,10 @@ export interface FieldMeta {
     /** One muted line under the section's heading on a page (the first field that gives one wins). */
     readonly sectionDescription?: string;
     readonly shortcut?: string;
-    /** `false` keeps the field out of Random and Mutate, as a lock does, but by declaration. */
+    /**
+     * `false` keeps the field out of Random and Mutate, as a lock does, but by declaration. Switches,
+     * seeds and key combinations start out; `true` brings them in.
+     */
     readonly random?: boolean;
     /**
      * The row dims and takes no edits from the pointer or keys (focus can still reach it, to read
@@ -141,6 +144,12 @@ export interface CurveField extends FieldMeta {
 export interface ActionField extends FieldMeta {
     readonly kind: "action";
     readonly run?: () => void;
+    /** The combination that presses it (`"Shift+K"`), shown as a key cap at the row's end. */
+    readonly shortcut?: string;
+    /** Where `shortcut` works, as a toolbar button's (see `ToolbarShortcut`); `"panel"` by default. */
+    readonly scope?: "page" | "panel" | "none";
+    /** The user can rebind it in place: a click or Enter on the key cap listens for a new one. */
+    readonly rebind?: boolean;
 }
 export interface Vec3 {
     readonly x: number;
@@ -350,9 +359,17 @@ export declare function choice<const T extends readonly [string, ...string[]]>(v
     readonly labels?: Readonly<Partial<Record<T[number], string>>>;
     readonly display?: "menu" | "segmented";
 }): Choice<T[number]>;
-/** `action("Replay", { run })`: a button row. Its key also reaches the store's `onAction`. */
-export declare function action(label?: string, meta?: Omit<FieldMeta, "label"> & {
+/**
+ * `action("Replay", { run, shortcut: "Shift+K", global: true, rebind: true })`: a button row. Its
+ * key also reaches the store's `onAction`. `shortcut` presses it as a toolbar button's does (a
+ * combination, or `{ key, scope }`), and `rebind` lets the user change it from its key cap.
+ */
+export declare function action(label?: string, meta?: Omit<FieldMeta, "label" | "shortcut"> & {
     run?: () => void;
+    shortcut?: string | ToolbarShortcut;
+    /** A plain-string shortcut works anywhere on the page (as `scope: "page"`). */
+    global?: boolean;
+    rebind?: boolean;
 }): ActionField;
 type SpringHalf = number | Knob;
 /**
@@ -369,6 +386,10 @@ export declare function flatSpring(parts?: {
     readonly duration: Knob;
     readonly bounce: Knob;
 };
+/**
+ * A switch. Switches usually show or hide things (a view, a scene's parts), so Random and Mutate
+ * leave them alone unless `random: true`.
+ */
 export declare function toggle(value: boolean, meta?: FieldMeta): Toggle;
 /** `spring({ duration: 0.4, bounce: 0.2 })`, like SwiftUI's `.spring(duration:bounce:)`. */
 export declare function spring(value?: Partial<SpringValue>, meta?: FieldMeta): SpringField;
@@ -469,11 +490,14 @@ export declare function curve(points: readonly CurvePoint[] | keyof typeof CURVE
     readonly presets?: Readonly<Record<string, readonly CurvePoint[]>>;
     readonly shapes?: boolean;
 }): CurveField;
-/** A toolbar item's shortcut as `{ key, scope }`, or undefined without one. */
-export declare function toolbarShortcut(item: ToolbarItem): {
+type ResolvedShortcut = {
     readonly key: string;
     readonly scope: "page" | "panel" | "none";
-} | undefined;
+};
+/** A toolbar item's shortcut as `{ key, scope }`, or undefined without one. */
+export declare function toolbarShortcut(item: ToolbarItem): ResolvedShortcut | undefined;
+/** An action row's shortcut as `{ key, scope }`, or undefined without one. */
+export declare function actionShortcut(field: ActionField): ResolvedShortcut | undefined;
 /** A wrapping row of buttons with icons and shortcut chips; holds no value. */
 export declare function toolbar(items: readonly ToolbarItem[], meta?: FieldMeta): ToolbarField;
 type ReadoutOptions = Omit<ReadoutMeta, "shortcut" | "random" | "readOnly">;

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

@@ -36,6 +36,16 @@ export interface ChangeMeta {
     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;
@@ -98,6 +108,14 @@ export type PanelKeys = {
     /** `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 {
@@ -185,6 +203,13 @@ export interface MountPanelOptions extends LabelOptions {
      * 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. */
@@ -406,17 +431,28 @@ export interface Controls<S extends Schema = Schema> {
     readonly canRedo: boolean;
     subscribe(cb: () => void): () => void;
     /**
-     * Back to the defaults: every field, or only `keys`. Locks don't apply; disabled and read-only
-     * fields keep their values.
+     * 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`. One undo step.
+     * 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. */
@@ -424,6 +460,17 @@ export interface Controls<S extends Schema = Schema> {
     /** 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.
@@ -451,13 +498,28 @@ export interface Controls<S extends Schema = Schema> {
      */
     compare(hold: boolean): void;
     readonly comparing: boolean;
-    preset(id: string): void;
+    /**
+     * 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), one undo step; `coalesce` folds it into the previous
-     * one (a pan across a card's presets).
+     * 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;

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

@@ -9,9 +9,17 @@ export interface Variants<V> {
     readonly ready: boolean;
     list(): readonly Variant<V>[];
     save(name?: string): Variant<V>;
-    load(id: string): void;
+    /**
+     * 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>) => void, notify: () => void, enabled: () => boolean): Variants<Values<S>>;
+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

@@ -1,9 +1,10 @@
-export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, 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 { 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 { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, 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 ThemeMode, } from "./core/store.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";

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

@@ -54,6 +54,17 @@ export interface EditorRow {
     dispose(): void;
     readonly tracks: readonly SubTrack[];
     readonly gpu: readonly GpuRowBinding[];
+    /** Named options the digits pick while the row is focused (a ramp's or easing's presets). */
+    readonly options?: RowOptions;
+}
+/** A row's options as the digits 1–9 pick them (see scope.ts). */
+export interface RowOptions {
+    readonly count: number;
+    choose(i: number): void;
+    /** The options while they show (segments, chips), for a digit on each; empty while hidden. */
+    shown(): readonly HTMLElement[];
+    /** What stands for them while they're hidden (a menu's button, a head's mini curve). */
+    readonly anchor: Element;
 }
 export declare const reducedMotion: (doc: Document) => boolean;
 export declare const rgbCss: (rgb: readonly number[]) => string;

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

@@ -0,0 +1,13 @@
+/**
+ * A button's press flash: its wash brightens at once and eases out, so a command fired from a key
+ * shows on the button it belongs to (Undo, Redo, Reset, Copy, Random, a group's die and reset).
+ * The DOM runs it as a CSS animation (`data-k-flash`, see the styles); the GPU renderer draws the
+ * same curve from `flashOf`.
+ */
+export declare const FLASH_MS = 320;
+export declare function flash(button: HTMLElement | undefined, wake?: () => void): void;
+/**
+ * How much of `button`'s flash is left at `now` (1 to 0): ease-out cubic, as the DOM's
+ * `cubic-bezier(.33,1,.68,1)` from the flash back to the button's own wash.
+ */
+export declare function flashOf(button: Element, now: number): number;

package/dist/types/panel/gpu/renderer.d.ts

@@ -3,7 +3,7 @@ import { type HeaderDie } from "../die.js";
 import { type IconName } from "../icons.js";
 import { Edges } from "../motion.js";
 import type { MorphFrame } from "../morph.js";
-import type { PresetStrip } from "../presets.js";
+import { type PresetStrip } from "../presets.js";
 import type { DigitPlace, Slider } from "../slider.js";
 import type { TabStrip } from "../tabs.js";
 import type { ReadoutView } from "../../ui/readouts.js";
@@ -130,6 +130,11 @@ export interface GpuEasingRow {
     curve(): readonly number[];
     /** P0, P1, P3, P2: the two arms from the ends to their handles. */
     arms(): readonly number[];
+    /** Steps the row's morph (curve, arms, handles) to this frame; whether it still moves. */
+    advance(now: number): boolean;
+    /** The line's motion blur (px), and each handle's (px across, px down): 0 at rest. */
+    blur(): number;
+    smear(i: number): readonly [number, number];
     /** (0,0) and (1,1) in the box. */
     guides(): readonly number[];
     readonly handles: readonly HTMLElement[];
@@ -148,6 +153,13 @@ export interface GpuRampHandle {
     readonly selected: boolean;
     /** Dragged off the strip or graph: it goes when let go. */
     readonly leaving: boolean;
+    /**
+     * How grown it is (0…1), when its row's morph sizes it: budding out of the line or merging
+     * into a neighbour. Its position is then already the morph's, so it isn't eased again.
+     */
+    readonly grow?: number;
+    /** Its motion blur (px along its travel, across and down), 0, 0 at rest. */
+    readonly smear?: readonly [number, number];
 }
 export interface GpuGradientRow {
     readonly kind: "gradient";
@@ -156,12 +168,15 @@ export interface GpuGradientRow {
     readonly row: HTMLElement;
     readonly x: GpuExpander;
     readonly read: HTMLElement;
-    /** The head's swatch strip, and its stop ticks (x in the strip). */
+    /** The head's swatch strip, and its stop ticks (x in the strip; grown 0…1 as its stop is). */
     readonly mini: HTMLElement;
     ticks(): readonly {
         readonly el: HTMLElement;
         readonly x: number;
+        readonly grow?: number;
     }[];
+    /** Steps the row's morph to this frame (samples, stops and ticks); whether it still moves. */
+    advance(now: number): boolean;
     /** Evenly spaced samples as gamma sRGB triples, flat (see `gradientSamples`). */
     samples(): readonly number[];
     /** The editor's strip and how far in from each end its ramp starts (the handles' radius). */
@@ -192,7 +207,12 @@ export interface GpuCurveRow {
     readonly graph: HTMLElement;
     /** Grid lines as x0, y0, x1, y1 quadruples in the graph. */
     grid(): readonly number[];
+    /** The line and mini curve as the row's morph shows them now (stepped to `now`, ms). */
     curve(): readonly number[];
+    /** Steps the row's morph to this frame; whether it still moves. */
+    advance(now: number): boolean;
+    /** The line's motion blur (px), 0 at rest. */
+    blur(): number;
     handles(): readonly GpuRampHandle[];
     /** The hover crosshair: its x, the curve's y there, and the readout's element. */
     hover(): {
@@ -212,9 +232,17 @@ export interface GpuActionRow {
     readonly display: string;
     readonly row: HTMLElement;
     readonly button: HTMLButtonElement;
+    /** Its shortcut's key cap, at the row's end: a rebindable one listens while `capturing`. */
+    readonly keys?: GpuKeyCap;
     readonly wave: RowWave;
     isModified(): boolean;
 }
+/** A key cap (a keybind's, an action's shortcut): its text, and whether it's listening for keys. */
+export interface GpuKeyCap {
+    readonly chip: HTMLElement;
+    readonly text: HTMLElement;
+    capturing(): boolean;
+}
 /** A vector's number cell: its axis letter and readout (DOM-placed text). */
 export interface GpuCell {
     readonly el: HTMLElement;
@@ -517,7 +545,6 @@ declare class GpuOverlayManager {
     private curSubHovered;
     /** Whether the pointer has one of the panel's rows (and keys haven't taken over since). */
     private curPointerRow;
-    private readonly hotRows;
     private curPanelRect;
     private curPanelScrollTop;
     private curLayoutKey;
@@ -601,7 +628,6 @@ declare class GpuOverlayManager {
      * their hover twins, at --k-button-radius.
      */
     private drawButtonBox;
-    private isHot;
     /** Square inside its card, except the card's own rounded corners on the first and last rows. */
     private rowCorners;
     /** A row's hover wash, drawn beneath its control like the DOM row background. */
@@ -613,6 +639,11 @@ declare class GpuOverlayManager {
     private drawSeparator;
     /** The focus wash, matching the row's corners inside its card. */
     private drawFocus;
+    /**
+     * A header or group button that blooms in and out of its slot (`data-shown`): its opacity, scale
+     * and blur (σ, px) from the DOM's transition while one runs, else simply there or not.
+     */
+    private bloomOf;
     private drawIcon;
     /**
      * Copy, and the check it turns into once copied, from the DOM's transitions while they run
@@ -621,6 +652,18 @@ declare class GpuOverlayManager {
     private drawCopy;
     /** The die is always traced, at rest too, exactly as the DOM canvas does: nothing swaps. */
     private drawDie;
+    /** Panels whose DOM overlays `cutUnderHead` has cut, to restore once nothing is under. */
+    private readonly headCuts;
+    /**
+     * The DOM pieces the GPU leaves above its canvas (a row's accessory, the number being typed,
+     * the search field) are cut at a pinned header's foot (`foot`, viewport y), as the rows are.
+     */
+    private cutUnderHead;
+    /**
+     * A button's press flash (flash.ts) over its wash: the wash brightened toward the text colour,
+     * easing out. Returns `ink` brightened toward the text colour while the flash lasts.
+     */
+    private drawFlash;
     /** A circular icon button's hover/focus wash. */
     private drawRoundWash;
     /**
@@ -648,6 +691,7 @@ declare class GpuOverlayManager {
     /** The current row's selection wash (0…1), which its hover wash gives way to. */
     private curSelected;
     /** A stroke through `pts` (x,y pairs in viewport px), round-capped like SVG's. */
+    /** `blur` (px) softens it across, as a moving line's smear (the DOM's Gaussian over √12). */
     private pushLine;
     /**
      * Eases a list of numbers toward `target` on the fill spring, the way the DOM transitions the
@@ -660,6 +704,26 @@ declare class GpuOverlayManager {
     private shape;
     /** An outline like CSS `outline: 1.5px` at `offset`, following `radius`; drawn while focus-visible. */
     private readout;
+    /** Each name-like readout's text and the one before it, for their crossfade (see `fadeText`). */
+    private readonly fades;
+    /** Text that crossfades from what it said before when its element says `data-fade`, as the DOM's. */
+    private fadeText;
+    /**
+     * A rolling readout (reel.ts), right-aligned where its element ends: each number a wheel per
+     * place, as the slider's readout draws its digits, and the text between them still. Laid out
+     * here from the glyphs' advances (tabular digits), not from the DOM's spans, which may not
+     * have caught up yet.
+     */
+    private drawRolling;
+    private advanceOf;
+    /**
+     * A number's places, right-aligned at `right`: each digit a wheel seen through a feathered
+     * slot (faces 2.1em apart, as the DOM's reel), blurring with speed; punctuation keeps its own
+     * advance, and a place on its way out keeps its last spot. True while any place moves.
+     */
+    private drawPlaces;
+    /** The soft wash on the card focus is on (`data-k-scope`), as the DOM's ::after. */
+    private drawScope;
     /** A disclosure head (hover, label and changed dot, caret, focus); returns the body's clip, if open. */
     private drawHead;
     /** A disclosure chevron, turning a quarter on the lead spring as it opens. */
@@ -674,8 +738,6 @@ declare class GpuOverlayManager {
     private drawEasing;
     /** A gradient strip from its samples (see shader kind 13), `inset` in from each end. */
     private pushRamp;
-    /** How far a handle that arrived mid-life has grown in (`data-born`), like the DOM's keyframes. */
-    private appear;
     private drawGradient;
     private drawCurve;
     private readonly lastHover;
@@ -694,6 +756,16 @@ declare class GpuOverlayManager {
     private drawRange;
     private drawAngle;
     private drawKeybind;
+    /** When each listening key cap started, so its breathing starts from full strength. */
+    private readonly capSince;
+    /** Each key cap's text and the one before it, for their crossfade. */
+    private readonly capTexts;
+    /**
+     * A key cap, as the DOM's: its tray's width glides to fit new text (snappy, no bounce) with its
+     * right edge still, while the old text fades out and the new in. Listening, it takes a soft
+     * accent wash and its text breathes; no ring.
+     */
+    private drawKeyCap;
     /** A readout's clip: the card's, narrowed to `el` when given. */
     private clipTo;
     /** Paints a readout's ops (local px from `r`'s corner), clipped to it, as its canvas does. */

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

@@ -1,5 +1,9 @@
-/** One light tick for a change made by `from`'s control, unless ticks are off or too close. */
-export declare function tick(from: Element): void;
+import { type SoundCue } from "./sound.js";
+/**
+ * One light tick for a change made by `from`'s control, unless ticks are off or too close. With
+ * `sound`, a panel that plays sounds plays that cue at the same moment (see sound.ts).
+ */
+export declare function tick(from: Element, sound?: SoundCue): void;
 /**
  * Lays a label for the hidden switch over `target` (a positioned button), so a tap on it is the
  * user's own tap on a switch: the only tick iOS 26.5+ plays. Only where Safari's switch exists and

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

@@ -7,7 +7,6 @@
  * - `data-k-fv` on each ancestor of the focused element while it's `:focus-visible`
  *   (`:has(:focus-visible)`); `"track"` when that's a slider track, `"head"` an editor's header.
  * - `data-k-active` on each ancestor of a `.knobs-active` element (`:has(.knobs-active)`).
- * - `data-k-head-hover` on an editor row whose header is hovered (`:has(>.knobs-x-head:hover)`).
  * - `data-k-row-hover` on the root while the pointer is on one of its rows
  *   (`:has(.knobs-card>:hover)`).
  */

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

@@ -6,5 +6,6 @@ export { Spring, VelocityTracker } from "./motion.js";
 export { createPanel, mountPage, mountPanel, type Panel, type PanelSearch } from "./panel.js";
 export { balancedRuns, type FoldSummaryInfo, type MountPageOptions, type Page, type PageAction, type PageCard, type PageCardOptions, type PageControl, type PageFoldOptions, type PageFoldSource, type PageGroupInfo, type PageHighlight, type PageSectionInfo, } from "./page.js";
 export { createPresetStrip, nextPresetIndex, resolveActivePresetEntry, type ActivePresetState, type PresetEntry, type PresetStrip, } from "./presets.js";
+export { sound, type CueDetail, type Sound, type SoundCue, type SoundLayer, type SoundOptions, type SoundTheme, } from "./sound.js";
 export { injectStyles } from "./styles.js";
 export { attachVariantSwitcher, getSwitcherOptions, type ChoiceKey, type SwitcherOptions, } from "./switcher.js";

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

@@ -1,4 +1,4 @@
-import { type AngleField, type KeybindField, type Point, type RangeField, type SeedField, type ToolbarField, type ToolbarItem, type Vec3, type VecField } from "../core/schema.js";
+import { toolbarShortcut, type AngleField, type KeybindField, type Point, type RangeField, type SeedField, type ToolbarField, type ToolbarItem, type Vec3, type VecField } from "../core/schema.js";
 import type { EditorRow, RowContext } from "./editors.js";
 type Vec = Point & {
     readonly z?: number;
@@ -7,6 +7,28 @@ export declare function vecRow(c: RowContext<VecField>): EditorRow;
 export declare function rangeRow(c: RowContext<RangeField>): EditorRow;
 export declare function angleRow(c: RowContext<AngleField>): EditorRow;
 export declare function seedRow(c: RowContext<SeedField>): EditorRow;
+export interface KeyCap {
+    readonly chip: HTMLButtonElement;
+    readonly text: HTMLElement;
+    capturing(): boolean;
+    /** The combination it shows: `""` for none, undefined for mixed ("—"). */
+    show(combo: string | undefined): void;
+}
+/**
+ * A key cap that records a combination: a click, Enter or Space listens, the next combination is
+ * the value, Esc cancels and ⌫ clears. While it listens its row takes the active wash and the cap
+ * breathes, "Type keys…" (or the modifiers held so far) in its place; its width follows its text
+ * on a spring, its right edge still. Keybind rows and rebindable action rows use it.
+ */
+export declare function keyCap(o: {
+    readonly doc: Document;
+    readonly row: HTMLElement;
+    /** What the cap reads with no combination. */
+    readonly empty: string;
+    name(): string;
+    set(combo: string): void;
+    wake(): void;
+}): KeyCap;
 export declare function keybindRow(c: RowContext<KeybindField>): EditorRow;
 export interface ToolbarRow extends EditorRow {
     readonly field: ToolbarField;
@@ -14,7 +36,15 @@ export interface ToolbarRow extends EditorRow {
     match(event: KeyboardEvent, global: boolean): ToolbarItem | undefined;
     press(item: ToolbarItem): void;
     swap(field: ToolbarField): void;
+    /** Shows the shortcuts as they are now (after a rebinding). */
+    refresh(): void;
 }
-export declare function toolbarRow(c: RowContext<ToolbarField>, press: (item: ToolbarItem) => void): ToolbarRow;
+type Shortcut = ReturnType<typeof toolbarShortcut>;
+/**
+ * A toolbar: its buttons in equal columns, as many as fit and balanced across the rows (see
+ * `toolbarColumns`), each with its icon and label at the start and its shortcut at the end.
+ * `keyOf` is each item's shortcut as it is now (the store's rebinding, else its own).
+ */
+export declare function toolbarRow(c: RowContext<ToolbarField>, press: (item: ToolbarItem) => void, keyOf?: (item: ToolbarItem) => Shortcut): ToolbarRow;
 /** The value a vector shows, as `{ x, y }` or `{ x, y, z }`. */
 export type { Vec, Vec3 };

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

@@ -0,0 +1,7 @@
+import type { RowOptions } from "./editors.js";
+export declare function createOptionKeys(doc: Document, root: HTMLElement, wake: () => void): {
+    /** Shows `options`' digits (undefined hides them); the same ones again just re-place. */
+    show(options: RowOptions | undefined): void;
+    dispose(): void;
+};
+export type OptionKeys = ReturnType<typeof createOptionKeys>;