@kitlangton/knobs 0.1.0 → 0.3.0

package/dist/types/panel/page-hints.d.ts

@@ -1,3 +1,4 @@
+import { isTypingTarget } from "../core/keys.js";
 import { type HintSpot } from "./hints.js";
 /** Code letters, home row first: groups take the first letters, their targets the second. */
 export declare const HINT_LETTERS = "asdfghjkleruiowtyqpcvnmxzb";
@@ -79,4 +80,4 @@ export declare const hints: {
  * type-ahead): it's the hint key and something on the page has turned hint mode on.
  */
 export declare function claimsHintKey(doc: Document, key: string): boolean;
-export declare const isTyping: (target: EventTarget | null) => boolean;
+export declare const isTyping: typeof isTypingTarget;

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

@@ -1,7 +1,7 @@
 import type { PanelCommand, PanelKeys } from "../core/store.js";
 /** How a panel reads keys that aren't commands (see `PanelKeys`): resolved once per panel. */
 export interface KeyPrefs {
-    /** j/k and h/l as aliases for the arrows. */
+    /** j/k as aliases for ↑/↓ (l is Lock, so ←/→ have no letters). */
     readonly vim: boolean;
     /** Digits, `.`, `-` and Enter on a slider open its inline number editor. */
     readonly edit: boolean;
@@ -14,7 +14,7 @@ export declare const DEFAULT_PREFS: KeyPrefs;
 export declare const setKeyPrefs: (root: Element, prefs: KeyPrefs) => WeakMap<Element, KeyPrefs>;
 /** The preferences of the panel `node` sits in. */
 export declare function keyPrefs(node: EventTarget | null): KeyPrefs;
-/** -1, 1 or 0 for ←/→ (and h/l unless the panel turned the letter aliases off). */
+/** -1, 1 or 0 for ←/→. */
 export declare function arrowOf(event: KeyboardEvent): -1 | 0 | 1;
 /** ⇧'s multiplier for this event (1 without ⇧). */
 export declare const bigOf: (event: KeyboardEvent) => number;

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

@@ -0,0 +1,20 @@
+import type { MorphFrame } from "./morph.js";
+export interface Presence {
+    readonly shown: boolean;
+    /** Shows or hides the panel; `animate: false` puts it there at once (a reload, a first paint). */
+    set(shown: boolean, animate: boolean): void;
+    /** The shape the GPU overlay draws while it shows or hides (see `MorphFrame`), else undefined. */
+    frame(now: number): MorphFrame | undefined;
+    dispose(): void;
+}
+/** What the panel looks like at `x` (0 hidden, 1 shown) on the way in or out. */
+export declare function presenceLook(x: number, inline: boolean, reduced: boolean): {
+    opacity: number;
+    blur: number;
+    scale: number;
+    fold: number;
+};
+export declare function createPresence(root: HTMLElement, options: {
+    readonly inline: boolean;
+    readonly wake: () => void;
+}): Presence;

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

@@ -7,19 +7,27 @@ export interface PresetEntry<V = Record<string, unknown>> {
     readonly rawId: string;
     readonly label: string;
     readonly values: V;
-    apply(): void;
+    /** Applies it (making it the active preset); `coalesce` folds it into the last undo step. */
+    apply(coalesce?: boolean): void;
 }
 export interface ActivePresetState {
     readonly activeId: string;
     readonly activeIndex: number;
     readonly isCustom: boolean;
+    /** The active preset's chip, while the values have moved off it (its modified mark). */
+    readonly drifted?: boolean;
 }
+/** How strong the selection pill stays on the active preset once the values drift off it. */
+export declare const DRIFTED_PILL = 0.5;
+/** The strip's id for the store's active preset (`p:` a preset, `v:` a saved variant), if any. */
+export declare function activeEntryId(controls: Controls<any>): string | null;
 /**
  * Resolves which preset or variant is currently active.
- * Honors `lastAppliedId` when its values still match `currentValues`, so cycling never gets
- * stuck when a saved variant has the exact same values as a built-in preset.
+ * The store's active preset (`baseId`) holds the selection however far the values drift from it.
+ * Without one, `lastAppliedId` is honoured when its values still match `currentValues`, so
+ * cycling never gets stuck when a saved variant has the exact same values as a built-in preset.
  */
-export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null): ActivePresetState;
+export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null, baseId?: string | null): ActivePresetState;
 export declare function nextPresetIndex(count: number, activeIndex: number, direction: number): number;
 export interface PresetStrip {
     readonly element: HTMLElement;
@@ -36,8 +44,12 @@ export interface PresetStrip {
     getActiveState(): ActivePresetState;
     cycle(direction: -1 | 1): void;
     selectById(id: string): void;
-    /** Saves the current values as "Variant N"; returns a status message. */
+    /** Saves the current values as "Variant N" and opens its name to typing; returns a status message. */
     save(): string;
+    /** Opens the active chip's name to typing, when it's a saved variant; returns a status message. */
+    rename(): string | undefined;
+    /** The name field while a chip's name is being typed. */
+    readonly nameField: () => HTMLInputElement | null;
     /** Deletes the selected chip when it's a saved variant; returns a status message. */
     deleteActive(): string | undefined;
     update(): void;

package/dist/types/panel/ramp-morph.d.ts

@@ -0,0 +1,117 @@
+import { type SpringValue } from "../core/spring.js";
+import type { RowContext } from "./editors.js";
+export interface Pt {
+    readonly x: number;
+    readonly y: number;
+}
+export interface MorphPlan {
+    /** For each new point, the old point it travels from, or -1: it buds. */
+    readonly from: readonly number[];
+    /** Each old point without a partner, and the new point it merges into (-1: none, it shrinks). */
+    readonly merges: readonly {
+        readonly old: number;
+        readonly into: number;
+    }[];
+}
+/**
+ * Pairs `prev`'s points with `next`'s. The first stays the first and the last the last; the inner
+ * ones pair in order, as many as both have, choosing the pairing that travels least (in the 0…1
+ * box). Only the surplus is left over: merging when there are fewer, budding when more.
+ */
+export declare function matchPoints(prev: readonly Pt[], next: readonly Pt[]): MorphPlan;
+/** `flat` (`stride` numbers per sample) resampled to `n` samples evenly along its index. */
+export declare function resample(flat: readonly number[], stride: number, n: number): number[];
+/** The y of an x, y polyline (x not decreasing) at `x`, holding its ends past them. */
+export declare function sampleAt(flat: readonly number[], x: number): number;
+/** A point on its way: its channels (x, y, then any extras, then its size), their speeds and goals. */
+export interface MorphDot {
+    readonly id: number;
+    readonly at: number[];
+    readonly vel: number[];
+    readonly to: number[];
+    /** Merging: the dot it shrinks into (-1 shrinks where it is); undefined while it's one of the points. */
+    into?: number;
+}
+/** The default travel: .3 s with no bounce. */
+export declare const MORPH_SPRING: SpringValue;
+/** How long a point merging into its neighbour takes to shrink away (s). */
+export declare const MERGE_SPRING: SpringValue;
+export interface MorphSet {
+    /** Snap there: nothing moves (a drag, a different item, reduced motion). */
+    readonly instant?: boolean;
+    /** Hold the current motion this long (ms) first, as a cascade of rows does. */
+    readonly delay?: number;
+    readonly now: number;
+}
+/**
+ * The shown samples and points of a ramp between shapes: `stride` numbers per sample, `dims`
+ * channels per point (x, y and any extras; the dot's size is kept after them). Every number has
+ * its own spring, so a change mid-flight keeps each one's speed.
+ */
+export declare class RampMorph {
+    readonly stride: number;
+    readonly dims: number;
+    /** Where a new point buds from: on the line under it as it's shown now (no size channel). */
+    private readonly origin;
+    samples: number[];
+    private sampleVel;
+    private sampleTo;
+    /** The points, in order. */
+    live: MorphDot[];
+    /** Points merging away into others. */
+    gone: MorphDot[];
+    private ids;
+    private last;
+    private pending;
+    private resting;
+    omega: number;
+    zeta: number;
+    private readonly shrink;
+    constructor(stride: number, dims: number, spring?: SpringValue, 
+    /** Where a new point buds from: on the line under it as it's shown now (no size channel). */
+    origin?: (to: readonly number[], samples: readonly number[]) => number[]);
+    get moving(): boolean;
+    /** The points' channels as the shape stands (where the live dots are going). */
+    private points;
+    private dot;
+    /** Moves toward `samples` and `points` (each `dims` channels, without the size). */
+    set(samples: readonly number[], points: readonly (readonly number[])[], o: MorphSet): void;
+    private snap;
+    private retarget;
+    /** Where a merging dot is headed: the dot it merges into, followed if that one is merging too. */
+    private target;
+    /** Advances to `now` (ms); whether anything still moves. A time already reached is a no-op. */
+    step(now: number): boolean;
+    /** The line's fastest sample (px/s), given px per unit across and up. */
+    sampleSpeed(sx: number, sy: number): number;
+}
+/**
+ * How wide (px) a moving line or point smears at `speed` px/s, by `strength` (--k-curve-blur, 0
+ * to 1): at 1, about what a half-open shutter catches in a 60 Hz frame. Under a quarter pixel it
+ * is 0, so it rests crisp.
+ */
+export declare function curveSmear(speed: number, strength: number, cap?: number): number;
+/** The widest a moving curve's line smears (px): it's thin, so less than a point does. */
+export declare const LINE_SMEAR = 4;
+/** How strongly a ramp's moving line and points smear (--k-curve-blur, 0 off to 1). */
+export declare const curveBlur: (row: HTMLElement) => number;
+/**
+ * Runs a morph on one frame loop while it moves, drawing each frame; `wake` asks the GPU for a
+ * frame too, which reads the same morph (stepping it to its own frame time first: a time already
+ * reached is a no-op, so the two never step it twice).
+ */
+export declare function morphLoop(c: RowContext<unknown>, morph: RampMorph, draw: () => void): {
+    kick(): void;
+    dispose(): void;
+};
+/**
+ * The DOM's motion blur for a ramp's line and points: an SVG Gaussian per element, its deviation
+ * the GPU smear's box width over √12 (the same spread). Off (no filter at all) at rest.
+ */
+export declare function smearFilters(doc: Document, plot: SVGSVGElement): {
+    /** The line's smear: `set(px)` blurs `path` across (0 takes the filter off). */
+    line(path: SVGPathElement): (px: number) => void;
+    /** A point's smear along its travel (px across, px down); 0, 0 takes it off. */
+    dot(node: HTMLElement, sx: number, sy: number): void;
+    drop(node: HTMLElement): void;
+};

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

@@ -1,6 +1,6 @@
 import type { CurveField, GradientField } from "../core/schema.js";
 import { type EditorRow, type RowContext } from "./editors.js";
-/** The custom properties a gradient strip's samples ride on (registered, so they transition). */
+/** The custom properties a gradient strip's samples ride on (written each frame of a morph). */
 export declare const GRADIENT_VARS: string[];
 /**
  * A gradient: a swatch strip with stop ticks in the head; a wide strip with a handle per stop, the

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

@@ -0,0 +1,43 @@
+import type { DigitPlace } from "./slider.js";
+/**
+ * Brings a readout's places to `text` (a place per character, ones first), as rolling-number
+ * does: each digit a wheel rolling through every face in the value's direction (98 → 108 rolls
+ * the tens 9 → 0 forwards), new places rising in after a short hold, cascading outward, and
+ * leaving places fading over ~65% of `ms`. `ms` 0 places it.
+ */
+export declare function syncPlaces(places: DigitPlace[], text: string, trend: number, ms: number, delay: number, entering?: boolean): void;
+/** How long a readout rolls (ms): the panel's --k-roll, 320 by default. */
+export declare function rollMs(el: Element): number;
+/** A readout's parts: text, or a number shown to `decimals` places. */
+export type ReadoutPart = string | {
+    readonly value: number;
+    readonly decimals: number;
+};
+/** A part as laid out: its element, its text, and a number's places for the canvas. */
+export interface ReelSegment {
+    readonly el: HTMLElement;
+    text: string;
+    readonly places?: DigitPlace[];
+}
+export interface RollingReadout {
+    readonly host: HTMLElement;
+    readonly segments: readonly ReelSegment[];
+    /** Everything it shows, as one string. */
+    readonly text: string;
+    /**
+     * Shows `parts`. Numbers roll over `ms` (0 places them: the first paint, the user's own hand,
+     * a landing), after `delay` ms for the row's turn in a cascade.
+     */
+    show(parts: readonly ReadoutPart[], ms: number, delay?: number): void;
+    dispose(): void;
+}
+/** The rolling readout an element holds, if it holds one (the canvas draws its segments). */
+export declare const rollingReadoutOf: (el: Element) => RollingReadout | undefined;
+/** Makes `host`'s content a rolling readout (its children are the readout's from now on). */
+export declare function rollingReadout(host: HTMLElement): RollingReadout;
+/**
+ * Sets a name-like readout (an easing's or curve's name, a hex colour). `fade` crossfades the old
+ * text out over the new, where it was; without it (the user's own hand) the text just changes.
+ * The canvas does the same, reading `data-text` and `data-fade`.
+ */
+export declare function fadeText(el: HTMLElement, text: string, fade: boolean): void;

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

@@ -0,0 +1,48 @@
+/** How deep focus sits in the panel. */
+export type FocusLevel = "row" | "card" | "panel" | "none";
+/** Where Esc takes focus from `level`: up one, past a card when the row isn't in one. */
+export declare function escapeTo(level: FocusLevel, inCard?: boolean): FocusLevel;
+/** What R and ⇧R act on: a selection always wins, then the level focused. */
+export type CommandScope = "selection" | "row" | "group" | "all";
+export declare function commandScope(level: FocusLevel, selection?: boolean): CommandScope;
+/** How a command reads from where it would land: "Random this", "Reset group", "Random all". */
+export declare function scopeLabel(verb: string, scope: CommandScope): string;
+/** A level below the panel that the header's crumbs name: a card, a row, an open editor's part. */
+export type CrumbLevel = "card" | "row" | "editor";
+export interface Crumb {
+    readonly level: CrumbLevel;
+    readonly label: string;
+}
+/**
+ * Where keys go, as the header reads after the panel's title: `Shape › Cohesion`. A level that
+ * isn't focused (or has no name) is left out; the last crumb is the deepest, the one focused.
+ */
+export declare function crumbTrail(path: {
+    readonly card?: string;
+    readonly row?: string;
+    readonly editor?: string;
+}): Crumb[];
+/**
+ * Where Esc goes from the deepest crumb: the crumb before it, else the panel (`title`). Nothing
+ * at the panel itself (no crumbs), where Esc leaves.
+ */
+export declare function escTarget(trail: readonly Crumb[], title: string): string | undefined;
+/**
+ * How much of a trail fits `room` px: crumbs from `from` on show (the ones before it fold into
+ * one "…"), and the Esc hint shows only when it fits too. The deepest crumb always shows.
+ * `widths` are the crumbs' own; `sep` a separator's (with its gaps), `more` the "…"'s.
+ */
+export declare function fitCrumbs(widths: readonly number[], room: number, sep: number, more: number, hint?: number): {
+    from: number;
+    hint: boolean;
+};
+/**
+ * The option a digit picks among `count` (0-based), or undefined when it names none: 1–9 pick
+ * the first nine, as they read.
+ */
+export declare function digitOption(key: string, count: number): number | undefined;
+/**
+ * The digit hints for a row's options: one per option that shows (up to nine), or, while they
+ * don't (a menu, a folded editor), one standing for them all ("1–5").
+ */
+export declare function digitHints(count: number, showing: boolean): string[];

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

@@ -1,5 +1,6 @@
 import type { Knob as KnobField } from "../core/schema.js";
-import { Roll, Spring, VelocityTracker } from "./motion.js";
+import { type DetentKind } from "./feel.js";
+import { type Roll, Spring, VelocityTracker } from "./motion.js";
 export interface DigitPlace {
     ch: string;
     /** Unbounded wheel position for digits (… 9, 10, 11 …); face = position mod 10. */
@@ -39,6 +40,17 @@ export interface Slider {
     readonly notchRatio: number;
     /** Whether a drag is currently held on the default by the notch's magnet. */
     isMagnetized(): boolean;
+    /** The detent holding a drag right now, if any. */
+    heldDetent(): DetentKind | undefined;
+    /** Where the active preset's value sits [0..1], when it differs from the default. */
+    readonly baseRatio: number | undefined;
+    /** When the handle last caught a detent (see `settleScale`). */
+    readonly settledAt: number;
+    /**
+     * How many halvings the drag in hand moves at, for its ruler (0 at 1:1 or at rest, up to 3; each
+     * level halves the tenths again). Each level shows `rulerAlpha(depth, level)` of the way.
+     */
+    rulerDepth(): number;
     /** When the readout last popped (a click landing on a decile, or the default's magnet). */
     poppedAt: number;
     /** Formatted numeric string without unit (e.g. "0.45" or "98"). */
@@ -83,10 +95,15 @@ export declare function stepValue(field: {
 /**
  * A DialKit-style slider: the whole row is the track, the fill is a full-height block,
  * the handle is a hairline that only shows on hover, and the label + value sit on the
- * track itself. Dragging follows the pointer exactly (⌥ for 1/10 speed) and the default's notch
- * pulls it in from a few px away; a click snaps to the nearest step (or nearest 10% when there
- * are many steps) with a short spring-like ease. A sideways trackpad pan moves it like a drag.
+ * track itself. Dragging follows the pointer exactly, slower the further the pointer strays off
+ * the row (and ⌥ for 1/10 speed); detents at the default, the active preset's value and round
+ * values hold it for a few px, and past an end the row stretches like rubber. A click snaps
+ * to the nearest step (or nearest 10% when there are many steps) with a short spring-like ease.
+ * A sideways trackpad pan moves it like a drag.
  */
 export declare function createSlider(doc: Document, key: string, initialField: KnobField, set: (value: number, options?: {
     coalesce?: boolean;
-}) => void, onMotionWake?: () => void): Slider;
+}) => void, onMotionWake?: () => void, options?: {
+    /** The active preset's value for this key (what Reset goes back to first). */
+    readonly base?: () => number | undefined;
+}): Slider;

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

@@ -0,0 +1,137 @@
+import type { SoundOptions, SoundTheme } from "../core/store.js";
+export type { SoundOptions, SoundTheme };
+/** A cue knobs plays for a moment in a panel (see README, Sound). */
+export type SoundCue = "step" | "limit" | "toggle" | "select" | "preset" | "random" | "mutate" | "reset" | "copy" | "undo" | "redo" | "open" | "close" | "hint" | "type" | "press" | "capture";
+/** What a play knows about its moment. */
+export interface CueDetail {
+    /** Where the value now sits in its range, 0–1: a step's pitch. */
+    readonly position?: number;
+    /** Forwards or on (1), back or off (-1). */
+    readonly direction?: number;
+    /** A firmer play: the default's notch catching. */
+    readonly strong?: boolean;
+    readonly volume?: number;
+    readonly theme?: SoundTheme;
+}
+/**
+ * One layer of a sound: a tone (`wave`) or a burst of noise through a filter. Times are seconds;
+ * `d` is how long it takes to die away by 60 dB.
+ */
+export interface SoundLayer {
+    readonly wave?: OscillatorType;
+    /** The noise's filter; `bandpass` by default. */
+    readonly filter?: BiquadFilterType;
+    /** The tone's pitch, or the noise filter's frequency (Hz). */
+    readonly f: number;
+    /** Glides `f` here over `glide` seconds. */
+    readonly to?: number;
+    readonly glide?: number;
+    readonly q?: number;
+    /** Starts this long after the play. */
+    readonly at?: number;
+    readonly a: number;
+    readonly d: number;
+    readonly p: number;
+}
+interface Recipe {
+    readonly layers: readonly SoundLayer[];
+    /** The play's level, matched across cues by ear and by loudness (1 by default). */
+    readonly gain?: number;
+    /** How much rings into the shared room (0 by default: dry). */
+    readonly room?: number;
+}
+/** 0 (unhurried) to 1 (as fast as it goes), from the time since the cue last played. */
+export declare const cadence: (sinceMs: number) => number;
+/**
+ * A cue's layers for this play: `speed` from `cadence`, `random` for its small variations (a die's
+ * clicks, a key's pitch). Pure, so tests and an offline render read the same sound.
+ */
+export declare function recipe(cue: SoundCue, detail?: CueDetail, speed?: number, random?: () => number): Recipe;
+/** The `mech` theme: the same cues with the rings all but gone and the clicks tighter. */
+export declare const themed: (layers: readonly SoundLayer[], theme: SoundTheme) => SoundLayer[];
+/** The shortest gap (ms) between two plays of a cue: closer ones are dropped. */
+export declare const GAPS: Readonly<Record<SoundCue, number>>;
+/** How a cue's plays are let through: too close are dropped; the rest report their cadence. */
+export declare function createLimiter(gaps?: Readonly<Record<string, number>>): (cue: string, now: number) => number | null;
+/** A change this long (ms) after the last one on its slider is a fresh one (a key, a click). */
+export declare const FRESH_MS = 150;
+/** A continuous slider ticks this many times across its range while it's dragged. */
+export declare const DETENTS = 24;
+/**
+ * Whether a slider's change (positions 0–1) earns a tick: a fresh change always does; within a
+ * drag, only crossing into another of its `detents` (each stop of a stepped slider, else
+ * DETENTS), so a slow drag ratchets evenly instead of ticking every pixel.
+ */
+export declare function createDetents(): (key: string, before: number, after: number, detents: number, now: number) => boolean;
+/** The parts of a field a change's cue reads. */
+interface CueField {
+    readonly kind: string;
+    readonly value?: unknown;
+    readonly min?: unknown;
+    readonly max?: unknown;
+    readonly step?: unknown;
+    readonly options?: readonly unknown[];
+}
+/**
+ * The cue for a row's value changing by hand from `before` to `after`: a step for numbers (pitched
+ * by position, firmer landing on the default), a switch's throw, a choice's detent (by direction),
+ * a captured key. `detents` is how many ticks a drag across the whole range may make.
+ */
+export declare function changeCue(field: CueField, before: unknown, after: unknown): {
+    cue: SoundCue;
+    detail: CueDetail;
+    detents: number;
+    at: number;
+    was: number;
+} | null;
+/** A mount's `sound` option as what the panel plays with, or null for silence. */
+export declare function resolveSound(option: boolean | SoundOptions | undefined): SoundOptions | null;
+/** At most this many plays sound at once; the oldest fades for a new one. */
+export declare const MAX_VOICES = 10;
+/** What the engine needs from the page, so tests can hand it a fake. */
+export interface SoundEnv {
+    readonly AudioContext?: {
+        new (): AudioContext;
+    };
+    /** Whether the page has had a user gesture yet (no context is made before one). */
+    readonly activated?: () => boolean;
+    readonly now?: () => number;
+    readonly random?: () => number;
+}
+export interface Sound {
+    /** The page's switch: on unless turned off. Panels only play with `sound` on their mount. */
+    readonly enabled: boolean;
+    enable(on?: boolean): void;
+    /** 0–1, 1 by default. */
+    readonly volume: number;
+    setVolume(volume: number): void;
+    readonly theme: SoundTheme;
+    setTheme(theme: SoundTheme): void;
+    /** Plays a cue, or layers of your own, unless sound is off or the page hasn't been touched. */
+    play(cue: SoundCue | readonly SoundLayer[], detail?: CueDetail): void;
+    /**
+     * The shared context and the bus to connect your own nodes to (volume, mute and the compressor
+     * apply), once there is one: after the first user gesture with sound wanted.
+     */
+    output(): {
+        readonly context: AudioContext;
+        readonly destination: AudioNode;
+    } | null;
+    /** Makes the context on the page's next gesture, so the first cue sounds at once. */
+    prime(doc?: Document): void;
+    /** Called when `enabled`, `volume` or `theme` change; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createSound(env?: SoundEnv): Sound;
+/** The page's sound: one switch, volume and theme for every panel (and the host's own cues). */
+export declare const sound: Sound;
+/** Where the page keeps the user's choice, in a store's storage. */
+export declare const SOUND_PREF = "knobs:sound:v1";
+/** Marks `root` as a panel that plays (a mount's resolved `sound`). */
+export declare function soundPanel(root: Element, options: SoundOptions): void;
+/** Whether the panel `from` sits in plays sounds. */
+export declare const sounds: (from: Element | null | undefined) => boolean;
+/** A row's value changing by hand in the panel `from` sits in (see `changeCue`). */
+export declare function changed(from: Element | null | undefined, key: string, field: CueField, before: unknown, after: unknown): void;
+/** Plays `cue` for a moment in the panel `from` sits in, if that panel plays sounds. */
+export declare function cue(from: Element | null | undefined, name: SoundCue, detail?: CueDetail): void;

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

@@ -3,7 +3,7 @@ import { type TokenPreset } from "../core/theme.js";
  * What DELAY times: a row's turn in a preset's cascade is set on these (see `showValues` in
  * panel.ts) rather than on the row, where the custom property would restyle all of the row.
  */
-export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
+export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-track,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
 /** Adds a token preset's stylesheet once per document. */
 export declare function injectPreset(doc: Document, preset: TokenPreset): void;
 /** The rules' `:has()` as the attributes has.ts keeps (see there for why). */

package/dist/types/panel/tab-transition.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A tab change, as one layout animation: what leaves fades out where it stood (lifted out of the
+ * flow, so it takes no room), what arrives fades in block by block with a small rise, what stays
+ * glides to its new place, and the surface (and any card whose rows change) springs to its new
+ * height. Every spring keeps its position and velocity when another tab is picked mid-flight.
+ *
+ * While the pointer stays on the panel the surface never shrinks: a panel anchored at its foot
+ * (or centred) would otherwise move its tabs out from under the pointer between two clicks. It
+ * settles to its size once the pointer leaves.
+ */
+export declare function tabTransition(body: HTMLElement, root: HTMLElement, wake: () => void): {
+    readonly running: boolean;
+    finish: () => void;
+    to(want: Map<HTMLElement, boolean>): void;
+};

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

@@ -28,4 +28,4 @@ export interface TabStrip {
     focus(options?: FocusOptions): void;
     dispose(): void;
 }
-export declare function createTabStrip(doc: Document, choose: (id: string) => void): TabStrip;
+export declare function createTabStrip(doc: Document, choose: (id: string, animate?: boolean) => void): TabStrip;

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

@@ -0,0 +1,27 @@
+import { type StoragePort } from "../core/storage.js";
+type KeyEventLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "altKey" | "shiftKey" | "repeat" | "isComposing" | "defaultPrevented" | "target">;
+/** Whether a keydown is `key` for the toggle: outside a text field, with no modifier held. */
+export declare function isToggleKey(event: KeyEventLike, key: string): boolean;
+/** A panel or chip that comes and goes with the toggle key. */
+export interface ToggleSurface {
+    /** Its store's id: what's remembered. */
+    readonly id: string;
+    readonly key: string;
+    readonly storage: () => StoragePort | null;
+    /** Where focus may be when it hides, to give back when it shows. */
+    readonly root: HTMLElement;
+    /** Shows or hides it; `animate: false` puts it there at once. */
+    show(shown: boolean, animate: boolean): void;
+}
+export interface ToggleLayer {
+    /** Joins the layer; `shown` is how it should start (what its store remembers). */
+    register(surface: ToggleSurface): {
+        readonly shown: boolean;
+        dispose(): void;
+    };
+    /** Shows or hides everything listening for `key`; false when nothing does. */
+    toggle(key: string): boolean;
+}
+/** The page's toggle layer, for `doc`. */
+export declare function toggleLayer(doc: Document): ToggleLayer;
+export {};

package/dist/types/panel/toolbar-grid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How many equal columns a toolbar's buttons take in `avail` px: as many as fit at the widest
+ * button's width, then balanced so the rows hold counts as even as they can (four buttons wrap as
+ * two and two, never three and one; five as three and two).
+ */
+export declare function toolbarColumns(count: number, widest: number, avail: number, gap: number): number;

package/dist/types/ui/activity-css.d.ts

@@ -0,0 +1 @@
+export declare const activityCss: string;