@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,526 @@
+import { type Oklch } from "./color.js";
+import { type Bezier, type EasingName } from "./easing.js";
+import type { LogEntry, TableRows } from "./readout.js";
+import { CURVE_SHAPES, type CurveInterp, type CurvePoint, type GradientSpace, type GradientStop } from "./ramp.js";
+import type { SpringValue } from "./spring.js";
+export interface FieldMeta {
+    readonly label?: string;
+    readonly group?: string;
+    /**
+     * What the group's header shows when it isn't the `group` id itself (the first field that
+     * gives one wins). The id stays the group's identity: presets, resets, highlights and code.
+     */
+    readonly groupLabel?: string;
+    /** A page region the field's group sits in (see `mountPage`); panels ignore it. */
+    readonly section?: string;
+    /** What the section's heading shows (the first field that gives one wins); `section` by default. */
+    readonly sectionLabel?: string;
+    /** One muted line under the group's card title on a page (the first field that gives one wins). */
+    readonly groupDescription?: string;
+    /** 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. */
+    readonly random?: boolean;
+    /**
+     * The row dims and takes no edits from the pointer or keys (focus can still reach it, to read
+     * it); Random, Mutate and Reset skip it. A function decides from the current values, e.g.
+     * `(v) => v.light !== "spot"`.
+     */
+    readonly disabled?: boolean | ((values: State) => boolean);
+    /** Shows the value at full strength but takes no edits; Random, Mutate and Reset skip it. */
+    readonly readOnly?: boolean | ((values: State) => boolean);
+    /**
+     * The group's card starts folded (the first field of a group that says wins), and its header
+     * folds and opens it, in a panel or a page. `groupFolded` (on the mount, then the store)
+     * overrides it, and on a page what the user last chose wins over both.
+     */
+    readonly folded?: boolean;
+    /**
+     * On a page, the field's section starts folded to its heading (the first field of a section
+     * that says wins), and the heading folds and opens it. `sectionFolded` (on the mount, then the
+     * store) overrides it, and what the user last chose wins over both.
+     */
+    readonly sectionFolded?: boolean;
+    /**
+     * The panel tab the field sits on (`mountPanel` draws a tab strip once any field names one).
+     * Fields without a tab show on every tab.
+     */
+    readonly tab?: string;
+    /**
+     * A collapsible sub-heading inside the field's group: a flat heading with a hairline, never a
+     * card inside the card. Consecutive fields that share it sit under one heading.
+     */
+    readonly subsection?: string;
+}
+/** Meta keys copied from a field's options or a descriptor onto the field. */
+export declare const META_KEYS: readonly ["label", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "subsection"];
+/** The meta `source` gives, without undefined keys. */
+export declare function pickMeta(source: FieldMeta | undefined, skip?: readonly string[]): FieldMeta;
+/** Marks a knob as half of a flat spring: two number keys drawn as one spring card. */
+export interface SpringPart {
+    /** Shared by both halves; the card sits where the first of them is. */
+    readonly id: string;
+    readonly part: "duration" | "bounce";
+    /** The card's title (taken from the duration half). */
+    readonly label?: string;
+}
+export interface Knob extends FieldMeta {
+    readonly kind: "knob";
+    readonly value: number;
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly unit?: string;
+    /** Digits after the point in the readout; the step's own by default. */
+    readonly decimals?: number;
+    readonly spring?: SpringPart;
+}
+export interface Choice<T extends string = string> extends FieldMeta {
+    readonly kind: "choice";
+    readonly value: T;
+    readonly options: readonly T[];
+    /** What each option reads as, when it isn't the option itself (`{ md: "Medium" }`). */
+    readonly labels?: Readonly<Record<string, string>>;
+    /**
+     * Segments or a drop-down menu. By default it's segmented while the labels fit with room to
+     * spare and there are at most four options, and a menu otherwise, switching as the width changes.
+     */
+    readonly display?: "menu" | "segmented";
+}
+export interface Toggle extends FieldMeta {
+    readonly kind: "toggle";
+    readonly value: boolean;
+}
+export interface SpringField extends FieldMeta {
+    readonly kind: "spring";
+    readonly value: SpringValue;
+}
+/** The value is an `oklch(L C H)` string, usable as-is in CSS and always inside sRGB. */
+export interface ColorField extends FieldMeta {
+    readonly kind: "color";
+    readonly value: string;
+}
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface PointField extends FieldMeta {
+    readonly kind: "point";
+    readonly value: Point;
+    readonly min: Point;
+    readonly max: Point;
+    readonly step: Point;
+}
+export interface EasingField extends FieldMeta {
+    readonly kind: "easing";
+    readonly value: Bezier;
+}
+/** Colour over a 0…1 parameter (over life, over the day): stops sorted by position. */
+export interface GradientField extends FieldMeta {
+    readonly kind: "gradient";
+    readonly value: readonly GradientStop[];
+    /** How the stops blend: `oklab` (perceptual, the default) or `srgb` (as CSS does). */
+    readonly space: GradientSpace;
+    /** Named ramps offered as chips in the editor. */
+    readonly presets?: Readonly<Record<string, readonly GradientStop[]>>;
+}
+/** A number over 0…1 (a falloff, a response): points sorted by x, the ends pinned at 0 and 1. */
+export interface CurveField extends FieldMeta {
+    readonly kind: "curve";
+    readonly value: readonly CurvePoint[];
+    /** The y range, 0…1 by default. */
+    readonly range: readonly [number, number];
+    readonly interp: CurveInterp;
+    /** Named shapes offered as chips (y in `range`), after the built-in ones unless `shapes: false`. */
+    readonly presets?: Readonly<Record<string, readonly CurvePoint[]>>;
+    /** The built-in shapes (linear, ease-out, inverse², smoothstep, bell) as chips; on by default. */
+    readonly shapes: boolean;
+}
+/** A button row. It holds no value: pressing it calls `run` and the store's `onAction(key)`. */
+export interface ActionField extends FieldMeta {
+    readonly kind: "action";
+    readonly run?: () => void;
+}
+export interface Vec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** `vec2` / `vec3`: inline x, y (and z) number cells, each scrubbed or typed. */
+export interface VecField<N extends 2 | 3 = 2 | 3> extends FieldMeta {
+    readonly kind: "vec";
+    readonly axes: N;
+    readonly value: N extends 3 ? Vec3 : Point;
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly unit?: string;
+    readonly decimals?: number;
+    /** Shows a link toggle: while linked, changing one cell scales the others with it. */
+    readonly link?: boolean;
+    /** Starts linked (implies `link`). */
+    readonly linked?: boolean;
+    /** The cells' names, in order (`["x", "z"]` for a ground-plane pair): their letters and labels. */
+    readonly axisLabels?: readonly string[];
+}
+/** A `[low, high]` pair on one slider with two thumbs that can't cross. */
+export interface RangeField extends FieldMeta {
+    readonly kind: "range";
+    readonly value: readonly [number, number];
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly unit?: string;
+    readonly decimals?: number;
+}
+/** Degrees on a dial; `wrap` (a full turn by default) carries 359° on to 0°. */
+export interface AngleField extends FieldMeta {
+    readonly kind: "angle";
+    readonly value: number;
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly wrap: boolean;
+}
+/** A whole number with a die that rolls a new one; out of Random and Mutate unless `random: true`. */
+export interface SeedField extends FieldMeta {
+    readonly kind: "seed";
+    readonly value: number;
+    readonly min: number;
+    readonly max: number;
+}
+/** A key combination such as `"Meta+Shift+K"` (`""` for none), captured by pressing it. */
+export interface KeybindField extends FieldMeta {
+    readonly kind: "keybind";
+    readonly value: string;
+}
+/**
+ * A toolbar button's key and where it presses the button: while the panel has focus (`"panel"`),
+ * anywhere on the page but a text field (`"page"`), or nowhere (`"none"`: the chip only, for a
+ * key the host binds itself).
+ */
+export interface ToolbarShortcut {
+    readonly key: string;
+    readonly scope?: "page" | "panel" | "none";
+}
+/** A toolbar button: an optional icon, a label and a shortcut chip. */
+export interface ToolbarItem {
+    /** Reported to `onAction`; the label by default. */
+    readonly id?: string;
+    readonly label: string;
+    /** A built-in icon name (`play`, `frame`, `retrigger`, …) or SVG path data on a 256 grid. */
+    readonly icon?: string;
+    /**
+     * A key or combination (`"Space"`, `"f"`, `"Shift+P"`) that presses the button while the panel
+     * has focus, or `{ key, scope }` to say where it works (see `ToolbarShortcut`).
+     */
+    readonly shortcut?: string | ToolbarShortcut;
+    /** A plain-string shortcut works anywhere on the page (as `scope: "page"`). */
+    readonly global?: boolean;
+    readonly disabled?: boolean;
+    readonly run?: () => void;
+}
+/** A row of buttons that wrap; holds no value. Each press calls its `run` and `onAction(id)`. */
+export interface ToolbarField extends FieldMeta {
+    readonly kind: "toolbar";
+    readonly items: readonly ToolbarItem[];
+}
+export type ValueField = Knob | Choice | Toggle | SpringField | ColorField | PointField | EasingField | VecField | RangeField | AngleField | SeedField | KeybindField | GradientField | CurveField;
+/** A readout's own: polled while its row shows, instead of pushed with `controls.watch`. */
+interface ReadoutMeta extends FieldMeta {
+    /** Read each frame while the row is on screen (pushing with `controls.watch` is the other way). */
+    readonly get?: () => unknown;
+    readonly unit?: string;
+    /** Digits after the point; by default fewer as the number grows (2 under 10, 1 under 100). */
+    readonly decimals?: number;
+    /** Text for a value, in place of the number and unit. */
+    readonly format?: (value: number) => string;
+    /** How often the text may change, per second (4 by default): readable, never a blur. */
+    readonly hz?: number;
+}
+/** A live number or text, with an optional unit; holds nothing in the store's values. */
+export interface WatchField extends ReadoutMeta {
+    readonly kind: "watch";
+}
+/** A watch with a small history graph in its row, auto-scaled. */
+export interface SparklineField extends ReadoutMeta {
+    readonly kind: "sparkline";
+    /** Samples kept (60 by default). */
+    readonly history: number;
+    /** A fixed floor or ceiling for the scale; it fits the samples otherwise. */
+    readonly min?: number;
+    readonly max?: number;
+    /** The line's colour (any CSS colour), the accent by default. */
+    readonly color?: string;
+}
+export interface GraphSeries {
+    readonly id: string;
+    readonly label?: string;
+    /** Any CSS colour; the accent, then a palette, by default. */
+    readonly color?: string;
+    /** Fills the area under the line. */
+    readonly area?: boolean;
+}
+export interface GraphThreshold {
+    readonly value: number;
+    readonly label?: string;
+    readonly color?: string;
+}
+/** A taller row: a multi-series line or area graph with thresholds and a hover crosshair. */
+export interface GraphField extends ReadoutMeta {
+    readonly kind: "graph";
+    readonly series: readonly GraphSeries[];
+    /** Samples kept per series (120 by default). */
+    readonly history: number;
+    /** The plot's height in px (64 by default). */
+    readonly height: number;
+    /** A fixed range; each bound left out fits the samples (with thresholds kept in view). */
+    readonly min?: number;
+    readonly max?: number;
+    readonly thresholds: readonly GraphThreshold[];
+}
+/** A bar for a value out of a maximum; `null` makes it indeterminate. */
+export interface MeterField extends ReadoutMeta {
+    readonly kind: "meter";
+    readonly min: number;
+    readonly max: number;
+    /** Splits the bar into this many cells. */
+    readonly segments?: number;
+    /** From this value on, the bar turns the warning colour (`--k-warn`). */
+    readonly warn?: number;
+    /** From this value on, the critical colour (`--k-critical`). */
+    readonly critical?: number;
+}
+/** A compact table of 2–4 columns: rows of cells, or a key-value record. */
+export interface TableField extends ReadoutMeta {
+    readonly kind: "table";
+    /** Column headings; the first sits under the row's label. */
+    readonly columns?: readonly string[];
+}
+/** A scrolling log with levels, a filter, follow-tail and copy. */
+export interface LogField extends ReadoutMeta {
+    readonly kind: "log";
+    /** Lines shown (8 by default). */
+    readonly lines: number;
+    /** Entries kept (1000 by default). */
+    readonly max: number;
+}
+export type ReadoutField = WatchField | SparklineField | GraphField | MeterField | TableField | LogField;
+export type Field = ValueField | ActionField | ToolbarField | ReadoutField;
+/** Whether a field is a readout (it shows pushed values and holds none). */
+export declare const isReadout: (field: {
+    readonly kind: string;
+}) => field is ReadoutField;
+/** Whether a field holds a value (actions, toolbars and readouts don't). */
+export declare const hasValue: (field: Field) => field is ValueField;
+export type Schema = Readonly<Record<string, Field>>;
+export type FieldValue<F extends Field> = F extends Knob ? number : F extends Choice<infer T> ? T : F extends Toggle ? boolean : F extends SpringField ? SpringValue : F extends ColorField ? string : F extends PointField ? Point : F extends EasingField ? Bezier : F extends VecField<3> ? Vec3 : F extends VecField<2> ? Point : F extends RangeField ? readonly [number, number] : F extends AngleField | SeedField ? number : F extends KeybindField ? string : F extends GradientField ? readonly GradientStop[] : F extends CurveField ? readonly CurvePoint[] : never;
+/** The keys of a schema's readouts (what `controls.watch` takes). */
+export type ReadoutKeys<S extends Schema> = {
+    [K in keyof S]: [S[K] & ReadoutField] extends [never] ? never : K;
+}[keyof S] & string;
+/** What a readout takes from `controls.watch` (`null` clears it). */
+export type ReadoutInput<F> = F extends WatchField ? number | string | null : F extends SparklineField ? number | readonly number[] | null : F extends GraphField ? number | Readonly<Record<string, number>> | null : F extends MeterField ? number | null : F extends TableField ? TableRows | null : F extends LogField ? string | LogEntry | readonly (string | LogEntry)[] | null : never;
+/** Action keys map to `never`: they hold no value and are absent at runtime. */
+export type Values<S extends Schema> = {
+    readonly [K in keyof S]: FieldValue<S[K]>;
+};
+export type Value = number | string | boolean | SpringValue | Point | Vec3 | Bezier | readonly [number, number] | readonly GradientStop[] | readonly CurvePoint[];
+export type State = Readonly<Record<string, Value>>;
+/** Ranges for spring fields: duration in seconds, and SwiftUI's bounce (below 0 is overdamped). */
+export declare const SPRING: {
+    readonly duration: {
+        readonly min: 0.05;
+        readonly max: 2;
+        readonly step: 0.01;
+    };
+    readonly bounce: {
+        readonly min: -0.5;
+        readonly max: 1;
+        readonly step: 0.01;
+    };
+};
+/** The keys that hold values (every field but actions). */
+export declare function valueKeys(schema: Schema): string[];
+export declare function knob(value: number, options: Omit<Knob, "kind" | "value" | "step"> & {
+    step?: number;
+}): Knob;
+export declare function choice<const T extends readonly [string, ...string[]]>(value: T[number], options: T, meta?: FieldMeta & {
+    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"> & {
+    run?: () => void;
+}): ActionField;
+type SpringHalf = number | Knob;
+/**
+ * A flat spring: two plain number fields (`{ duration, bounce }` as separate keys) drawn as one
+ * spring card with a curve and two sliders. Spread the result into a schema, or rename its halves:
+ * `defineControls("m", { ...flatSpring({ duration: 0.45, bounce: 0.3 }, { label: "Spring" }) })`.
+ */
+export declare function flatSpring(parts?: {
+    duration?: SpringHalf;
+    bounce?: SpringHalf;
+}, meta?: Omit<FieldMeta, "shortcut"> & {
+    id?: string;
+}): {
+    readonly duration: Knob;
+    readonly bounce: Knob;
+};
+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;
+/** `color("#4f8cff")`, `color("oklch(0.7 0.15 250)")` or `color({ l, c, h })`. */
+export declare function color(value: string | Oklch, meta?: FieldMeta): ColorField;
+type Axis = number | Point;
+/** A 2D pad: `point({ x: 0, y: 0 }, { min: -1, max: 1 })`; bounds and step take a number or `{ x, y }`. */
+export declare function point(value: Point, options: FieldMeta & {
+    min: Axis;
+    max: Axis;
+    step?: Axis;
+}): PointField;
+/** A cubic bezier `[x1, y1, x2, y2]` or a name: ease, ease-in, ease-out, ease-in-out, linear, smooth, snappy, back. */
+export declare function easing(value: Bezier | EasingName, meta?: FieldMeta): EasingField;
+interface NumberOptions {
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+    readonly unit?: string;
+    readonly decimals?: number;
+}
+type VecOptions = FieldMeta & NumberOptions & {
+    readonly link?: boolean;
+    readonly linked?: boolean;
+    /** What the cells are called (`["x", "z"]`): their letters and accessible names. */
+    readonly axes?: readonly string[];
+};
+/** Inline x and y cells: `vec2({ x: 0, y: 1 }, { min: -10, max: 10, step: 0.1 })`. */
+export declare function vec2(value: Point, options: VecOptions): VecField<2>;
+/** Inline x, y and z cells, with an optional link for uniform scaling (`link: true`). */
+export declare function vec3(value: Vec3, options: VecOptions): VecField<3>;
+/** A low–high pair on one slider: `range([0.2, 0.8], { min: 0, max: 1 })`. */
+export declare function range(value: readonly [number, number], options: FieldMeta & NumberOptions): {
+    value: readonly [number, number];
+    kind: "range";
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+    decimals?: number;
+    label?: string;
+    group?: string;
+    groupLabel?: string;
+    section?: string;
+    sectionLabel?: string;
+    groupDescription?: string;
+    sectionDescription?: string;
+    shortcut?: string;
+    random?: boolean;
+    disabled?: boolean | ((values: State) => boolean);
+    readOnly?: boolean | ((values: State) => boolean);
+    folded?: boolean;
+    sectionFolded?: boolean;
+    tab?: string;
+    subsection?: string;
+};
+/** Degrees on a dial (0–360 and wrapping by default): `angle(45)`, `angle(30, { min: -90, max: 90 })`. */
+export declare function angle(value: number, options?: FieldMeta & {
+    min?: number;
+    max?: number;
+    step?: number;
+    wrap?: boolean;
+}): AngleField;
+/** A seed with a die that rolls a new one; Random and Mutate leave it alone unless `random: true`. */
+export declare function seed(value: number, options?: FieldMeta & {
+    min?: number;
+    max?: number;
+}): SeedField;
+/** A key combination captured by pressing it (`"Meta+Shift+K"`, `""` for none). */
+export declare function keybind(value?: string, meta?: FieldMeta): KeybindField;
+/**
+ * Colour over a 0…1 parameter: `gradient([{ at: 0, color: "#fff4d6" }, { at: 1, color: "#20242c" }])`.
+ * Colours take what `color` takes and are kept as `oklch()` strings. `space` blends in `oklab`
+ * (default) or `srgb`; `presets` are named ramps offered as chips. Sample it with `sampleGradient`.
+ */
+export declare function gradient(stops: readonly {
+    readonly at: number;
+    readonly color: string | {
+        l: number;
+        c: number;
+        h: number;
+    };
+}[], options?: FieldMeta & {
+    readonly space?: GradientSpace;
+    readonly presets?: Readonly<Record<string, readonly {
+        at: number;
+        color: string;
+    }[]>>;
+}): GradientField;
+/**
+ * A number over 0…1: `curve([{ x: 0, y: 1 }, { x: 1, y: 0 }], { range: [0, 1], interp: "smooth" })`.
+ * The ends are pinned at x 0 and 1. `smooth` is a monotone cubic (no overshoot); `linear` and
+ * `step` join the points as they say. Sample it with `sampleCurve`.
+ */
+export declare function curve(points: readonly CurvePoint[] | keyof typeof CURVE_SHAPES, options?: FieldMeta & {
+    readonly range?: readonly [number, number];
+    readonly interp?: CurveInterp;
+    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): {
+    readonly key: string;
+    readonly scope: "page" | "panel" | "none";
+} | 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">;
+/** A live value: `watch({ label: "FPS", decimals: 0 })`, then `controls.watch("fps", 59.9)`. */
+export declare function watch(options?: ReadoutOptions): WatchField;
+/** A watch with a small history graph: `sparkline({ label: "Frame", unit: "ms", min: 0 })`. */
+export declare function sparkline(options?: ReadoutOptions & {
+    history?: number;
+    min?: number;
+    max?: number;
+    color?: string;
+}): SparklineField;
+/**
+ * A multi-series graph: `graph({ series: [{ id: "cpu" }, { id: "gpu" }], unit: "ms",
+ * thresholds: [{ value: 16.7, label: "60 fps" }] })`; push `{ cpu, gpu }` each frame.
+ */
+export declare function graph(options?: ReadoutOptions & {
+    series?: readonly (GraphSeries | string)[];
+    history?: number;
+    height?: number;
+    min?: number;
+    max?: number;
+    thresholds?: readonly (GraphThreshold | number)[];
+}): GraphField;
+/** A bar: `meter({ label: "Memory", max: 512, unit: "MB", warn: 384, critical: 480 })`. */
+export declare function meter(options?: ReadoutOptions & {
+    min?: number;
+    max?: number;
+    segments?: number;
+    warn?: number;
+    critical?: number;
+}): MeterField;
+/** A small table: `table({ label: "Passes", columns: ["Pass", "ms", "Draws"] })`. */
+export declare function table(options?: ReadoutOptions & {
+    columns?: readonly string[];
+}): TableField;
+/** A log: `log({ label: "Events", lines: 8 })`, then `controls.watch("events", { level, text })`. */
+export declare function log(options?: ReadoutOptions & {
+    lines?: number;
+    max?: number;
+}): LogField;
+/** An angle carried into `[min, max)` a whole turn at a time. */
+export declare const wrapAngle: (v: number, min: number, max: number) => number;
+export declare function normalizeField(field: ValueField, input: unknown): Value;
+export declare function normalize<S extends Schema>(schema: S, input: unknown): Values<S>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Value equality: springs, points, beziers, gradients and curves compare by their numbers. */
+export declare function same(a: unknown, b: unknown): boolean;
+export declare function equal(a: State, b: State): boolean;
+export {};

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

@@ -0,0 +1,38 @@
+export declare class Spring {
+    x: number;
+    omega: number;
+    zeta: number;
+    eps: number;
+    v: number;
+    target: number;
+    /** A retarget waiting for its turn in a cascade (performance.now() ms). */
+    private next;
+    constructor(x: number, omega?: number, zeta?: number, eps?: number);
+    /** With a `delay` (ms) the new target applies later; repeating the same target is a no-op. */
+    set(target: number, delay?: number): this;
+    snap(x: number): this;
+    step(dt: number): number;
+    get resting(): boolean;
+}
+/** A SwiftUI-style `.spring(duration:bounce:)`: perceptual duration in seconds, bounce -1…1. */
+export interface SpringValue {
+    readonly duration: number;
+    readonly bounce: number;
+}
+/** SwiftUI's mapping: ω = 2π / duration; ζ = 1 − bounce, or 1 / (1 + bounce) below zero. */
+export declare function springMotion({ duration, bounce }: SpringValue): {
+    omega: number;
+    zeta: number;
+};
+/** The step response (0 → 1) sampled every `dt` seconds for `seconds`. */
+export declare function springResponse(omega: number, zeta: number, seconds: number, dt?: number): number[];
+/** The step response as a CSS `linear()` easing plus its settle time (ms). */
+export declare function springEasing(omega: number, zeta: number): {
+    easing: string;
+    ms: number;
+};
+/** A spring field's value as CSS: `transition: transform ${duration}ms ${easing}`. */
+export declare function springCss(value: SpringValue): {
+    easing: string;
+    duration: number;
+};

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

@@ -0,0 +1,8 @@
+export interface StoragePort {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export declare function memoryStorage(): StoragePort;
+export declare function browserStorage(): StoragePort | null;
+export declare function urlFlag(name: string): () => boolean;
+export declare const storageKey: (id: string, part: string) => string;