@kitlangton/knobs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,14 @@
+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 (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
+ * selected stop's colour strips and any presets in the body.
+ */
+export declare function gradientRow(c: RowContext<GradientField>): EditorRow;
+/**
+ * A curve: its name (when it's a preset) and a mini curve in the head; a graph with a grid,
+ * draggable points and a hover crosshair, and shape chips, in the body.
+ */
+export declare function curveRow(c: RowContext<CurveField>): EditorRow;

package/dist/types/panel/readout-row.d.ts

@@ -0,0 +1,21 @@
+import type { ReadoutState } from "../core/readout.js";
+import type { ReadoutField } from "../core/schema.js";
+import { type ReadoutView } from "../ui/readouts.js";
+import type { EditorRow } from "./editors.js";
+import type { RowWave } from "./gpu/renderer.js";
+export interface ReadoutRow extends EditorRow {
+    readonly view: ReadoutView;
+    /** Something new arrived for this key. */
+    notify(): void;
+    swap(field: ReadoutField, display: string): void;
+}
+export declare function readoutRow(c: {
+    doc: Document;
+    key: string;
+    display: string;
+    field: ReadoutField;
+    state: ReadoutState;
+    wave: RowWave;
+    wake(): void;
+    gpu(): boolean;
+}): ReadoutRow;

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/reveal.d.ts

@@ -0,0 +1,15 @@
+export declare const isAnyRevealing: () => boolean;
+export declare const isRevealingIn: (root: HTMLElement) => boolean;
+export declare const getRevealVersion: () => number;
+export declare const isRevealing: (node: HTMLElement) => boolean;
+/**
+ * Eases an in-flow element from height `from` to the height it has now, after its content
+ * changed, so what's below glides. Read `from` before the change (mid-flight is fine).
+ */
+export declare function resize(node: HTMLElement, from: number): void;
+/**
+ * Shows or hides an in-flow element by animating its height (and margins/padding) open or shut,
+ * so the content below glides instead of jumping. Interruptible: reversing mid-flight continues
+ * from the current height.
+ */
+export declare function reveal(node: HTMLElement, show: boolean, after?: () => void, delay?: number): void;

package/dist/types/panel/rolling-css.d.ts

@@ -0,0 +1,2 @@
+declare const _default: ".rn-root {\n  display: inline-block;\n  position: relative;\n  white-space: pre;\n  unicode-bidi: isolate;\n  vertical-align: baseline;\n}\n.rn-root > .rn-measure,\n.rn-root > .rn-visual { display: none; }\n.rn-root[data-rn-measuring] > .rn-measure {\n  display: inline-flex;\n  position: relative;\n  visibility: hidden;\n  white-space: pre;\n  padding: 0;\n  border: 0;\n}\n.rn-token { display: inline-block; padding: 0; border: 0; }\n.rn-root[data-rn-measuring] > .rn-value,\n.rn-react[data-rn-hydrated] > .rn-semantic,\n.rn-solid[data-rn-hydrated] > .rn-semantic {\n  position: absolute;\n  inset: 0;\n  padding: 0;\n  margin: 0;\n  color: transparent;\n  z-index: 1;\n}\n/* A single native text layer is selectable; decorative reels never enter a copy. */\n.rn-value::selection, .rn-semantic::selection {\n  color: HighlightText;\n  background: Highlight;\n}\n.rn-root[data-rn-ready] > .rn-visual {\n  display: block;\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  user-select: none;\n}\n.rn-slot {\n  position: absolute;\n  left: 0;\n  overflow: hidden;\n  /* Space for italic overhang without changing the measured advance width. */\n  box-sizing: content-box;\n  padding-inline: 0.15em;\n  margin-inline-start: -0.15em;\n  -webkit-mask-image: var(--rn-mask, linear-gradient(\n    to bottom,\n    transparent,\n    #000 var(--rn-edge-fade, 0.12em),\n    #000 calc(100% - var(--rn-edge-fade, 0.12em)),\n    transparent\n  ));\n  mask-image: var(--rn-mask, linear-gradient(\n    to bottom,\n    transparent,\n    #000 var(--rn-edge-fade, 0.12em),\n    #000 calc(100% - var(--rn-edge-fade, 0.12em)),\n    transparent\n  ));\n  -webkit-mask-repeat: no-repeat;\n  mask-repeat: no-repeat;\n}\n@supports (overflow: clip) {\n  .rn-slot { overflow-x: visible; overflow-y: clip; }\n}\n.rn-slot:not([data-rn-wheel]) {\n  overflow: visible;\n  -webkit-mask-image: none;\n  mask-image: none;\n}\n.rn-enter, .rn-reel, .rn-face { display: block; }\n.rn-reel { position: relative; }\n.rn-ink { display: block; position: absolute; inset: 0; will-change: transform; }\n/* Safari's SVG filter must rasterize the smear's descendants into its input. */\n.rn-smear .rn-ink { will-change: auto; }\n/* Each turning half carries its own perspective transform, not a shared 3D scene. */\n/* The slot acts as the bezel: the card stays vertically framed while it hinges. */\n.rn-slot[data-rn-flap] { -webkit-mask-image: none; mask-image: none; }\n/* Hinged faces must occlude the cards behind them, including with default CSS. */\n:where(.rn-slot[data-rn-flap]) .rn-face { background: var(--rn-flap-background, Canvas); }\n.rn-flap { position: absolute; inset: 0; transform-origin: 50% 50%; backface-visibility: hidden; }\n/* --rn-crease is the visible hinge gap between the two halves. */\n.rn-flap-top { clip-path: inset(0 0 calc(50% + var(--rn-crease, 1px) / 2) 0); }\n.rn-flap-bottom { clip-path: inset(calc(50% + var(--rn-crease, 1px) / 2) 0 0 0); }\n.rn-sharp, .rn-smear { display: block; }\n.rn-smear { position: absolute; inset: 0; pointer-events: none; }\n.rn-blur-defs { position: absolute; width: 0; height: 0; overflow: hidden; }\n.rn-face { text-align: center; white-space: pre; }\n.rn-react, .rn-solid { display: inline-block; position: relative; white-space: pre; unicode-bidi: isolate; }\n.rn-mount { display: inline-block; user-select: none; }\n.rn-mount .rn-value { pointer-events: none; }\n.rn-react:not([data-rn-hydrated]) > .rn-mount,\n.rn-solid:not([data-rn-hydrated]) > .rn-mount { display: none; }\n";
+export default _default;

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

@@ -0,0 +1,19 @@
+/** 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;
+/**
+ * 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/search.d.ts

@@ -0,0 +1,36 @@
+export interface SearchChipSpec {
+    readonly id: string;
+    readonly label: string;
+    readonly count?: boolean;
+}
+/**
+ * A panel's search field: a text field that filters rows as you type, and filter chips beside it
+ * ("Modified 3") that narrow them further. It's drawn by the DOM in both renderers.
+ */
+export interface SearchBar {
+    readonly element: HTMLElement;
+    readonly input: HTMLInputElement;
+    readonly chips: readonly HTMLButtonElement[];
+    /** The trimmed query, lower-cased. */
+    query(): string;
+    /** The chips that are on. */
+    active(): ReadonlySet<string>;
+    /** Whether anything narrows the rows (a query or a chip). */
+    filtering(): boolean;
+    /** Shows each counted chip's number. */
+    counts(counts: ReadonlyMap<string, number>): void;
+    /** Empties the query and turns the chips off. */
+    clear(): void;
+    /** Sets the query as typed, and (when given) exactly which chips are on. */
+    set(query: string | undefined, chips?: readonly string[]): void;
+    focus(): void;
+}
+export declare function createSearch(doc: Document, options: {
+    placeholder: string;
+    chips: readonly SearchChipSpec[];
+    change(): void;
+}): SearchBar;
+/** Where `query` matches in `text` (case-insensitive), as [start, end), or undefined. */
+export declare function matchSpan(text: string, query: string): [number, number] | undefined;
+/** Writes `text` into `label`, with the matched span wrapped in `<mark class="knobs-match">`. */
+export declare function markLabel(label: HTMLElement, text: string, span: [number, number] | undefined): void;

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

@@ -0,0 +1,15 @@
+/**
+ * Places a segmented control's selected pill (`.knobs-seg-pill`) under the button whose
+ * `data-value` is `value`. The pill is placed by its edges so the edge facing the move can lead
+ * (see .knobs-seg-pill); a resize (a token gliding) carries it with its option instead of
+ * animating it, and the first placement doesn't animate. With no matching button the pill fades.
+ * While a pan holds the pill (see `panOptions`), it stays with the fingers. Showing the value it
+ * already shows reads no layout (a resize, `resized`, re-places it).
+ */
+export declare function placeSegPill(seg: HTMLElement, buttons: readonly HTMLButtonElement[], value: string, resized?: boolean): void;
+/**
+ * Reads where each option sits ahead of a batch's writes (see measure.ts), while layout is still
+ * clean: choosing an option doesn't move any, so the pill then places without reading layout
+ * after the batch has dirtied it.
+ */
+export declare function primeSegPill(seg: HTMLElement, buttons: readonly HTMLElement[]): void;

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

@@ -0,0 +1,21 @@
+/** What a reload should bring back, per tab: open panels, open editors and the focused stop. */
+export interface PanelSession {
+    readonly open?: boolean;
+    readonly expanded?: readonly string[];
+    readonly focus?: {
+        readonly inline: boolean;
+        readonly stop: number;
+    };
+    /** A page's collapsible custom cards, by title: whether each is folded. */
+    readonly folded?: Readonly<Record<string, boolean>>;
+    /** A panel's foldable groups, by id: whether each is folded. */
+    readonly groups?: Readonly<Record<string, boolean>>;
+    /** A panel's sub-headings, by group and name: whether each is folded. */
+    readonly subsections?: Readonly<Record<string, boolean>>;
+    /** The tab a panel showed. */
+    readonly tab?: string;
+}
+/** The tab's sessionStorage, where there is one. */
+export declare const tabStorage: () => Storage | null;
+export declare function readSession(id: string): PanelSession;
+export declare function writeSession(id: string, patch: Partial<PanelSession>): void;

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

@@ -0,0 +1,92 @@
+import type { Knob as KnobField } from "../core/schema.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. */
+    readonly wheel: Roll;
+    /** 1 while shown, 0 once gone: new places fade in and rise, leaving places fade out. */
+    readonly presence: Roll;
+    /** When this place started entering, and how long the entrance lasts (ms). */
+    enterAt: number;
+    enterMs: number;
+    exiting: boolean;
+}
+export interface Slider {
+    element: HTMLElement;
+    /** The focusable, keyboard-driven surface. */
+    track: HTMLElement;
+    /** The visible label element. */
+    label: HTMLElement;
+    /** The value button element. */
+    valueButton: HTMLButtonElement;
+    /** The inline number editor (hidden until the value is clicked). */
+    number: HTMLInputElement;
+    /**
+     * Spring driving the fill's edge [0..1]: the value, or while a stepped slider is in hand, the
+     * value pulled part way toward the pointer (--k-step-resist).
+     */
+    fillSpring: Spring;
+    /** Spring driving handle visibility/scale [0..1] (the GPU renderer sets its target). */
+    handleSpring: Spring;
+    /** Per-character springs for GPU rolling number digits. */
+    /** Readout characters keyed by place from the right, so 99 → 100 keeps the 9s in place. */
+    digitPlaces: DigitPlace[];
+    /** Velocity tracker on normalized fill ratio for drag motion blur. */
+    velocity: VelocityTracker;
+    /** Number of tick marks along the track. */
+    readonly tickCount: number;
+    /** Where the default value sits along the track [0..1]. */
+    readonly notchRatio: number;
+    /** Whether a drag is currently held on the default by the notch's magnet. */
+    isMagnetized(): boolean;
+    /** 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"). */
+    getDigitsText(): string;
+    /** Optional unit string (e.g. "px", "s"). */
+    getUnitText(): string;
+    /** Whether pointer drag is currently active. */
+    isDragging(): boolean;
+    /** Whether the inline number input is open. */
+    isEditing(): boolean;
+    /**
+     * `delay` (ms) holds this row's motion for its turn in a preset cascade; `instant` places the
+     * value without springing or rolling (a different item arrived).
+     */
+    update(value: number, delay?: number, instant?: boolean): void;
+    /**
+     * Reads its design tokens now. A batch (a preset) primes every row it will move before writing
+     * any, so no row's read lands after another's writes and forces a style pass.
+     */
+    prime(): void;
+    /** Takes a new range, step, label or unit in place, keeping the DOM (see `RemoteControls.update`). */
+    retune(field: KnobField): void;
+    /** The field it currently draws. */
+    readonly field: KnobField;
+    /** Open the inline editor, with `initial` in place of the value (a digit typed on the track). */
+    edit(initial?: string): void;
+    /** Puts a row accessory just after the label; the ticks and handle keep clear of it too. */
+    slot(node: HTMLElement): void;
+    dispose(): void;
+}
+export declare const decimals: (step: number) => number;
+/**
+ * `steps` grid steps from `value` (negative goes down), on the slider's grid counted from `min`.
+ * From a value between grid points (a declared default like 0.4 on a 0.02 grid from 0.15) the
+ * first step lands on the next grid point that way, not past it.
+ */
+export declare function stepValue(field: {
+    min: number;
+    max: number;
+    step: number;
+}, value: number, steps: number): number;
+/**
+ * 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.
+ */
+export declare function createSlider(doc: Document, key: string, initialField: KnobField, set: (value: number, options?: {
+    coalesce?: boolean;
+}) => void, onMotionWake?: () => void): Slider;

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

@@ -0,0 +1,7 @@
+/** Smears `pill` by its speed while it glides: `cap` is the widest smear (px), as on the GPU. */
+export declare function smearPill(pill: HTMLElement, cap: number): void;
+/**
+ * How wide a range band's end smears (px) at `speed` px/s, by `strength` (--k-range-blur, 0 to 1):
+ * the slider fill's edge ramp, so both read alike. 0 under a quarter pixel, so it rests crisp.
+ */
+export declare function rangeSmear(speed: number, strength: number): number;

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/spin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One more turn for the ↺ in `button` (its first `.knobs-icon`), from wherever it is now; `rest`
+ * runs once it has stopped.
+ */
+export declare function spin(button: HTMLElement, wake?: () => void, rest?: () => void): void;
+/** Whether `button`'s ↺ is turning (or blinking). */
+export declare const spinning: (button: Element) => boolean;
+/** Where `button`'s ↺ is now, for the GPU renderer: its turn (radians, clockwise) and opacity. */
+export declare function spinOf(button: Element, now: number): {
+    angle: number;
+    alpha: number;
+    moving: boolean;
+};

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

@@ -0,0 +1,11 @@
+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-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). */
+export declare const withoutHas: (css: string) => string;
+export declare function injectStyles(doc: Document): void;