tweakit 0.5.2 → 0.6.0

package/dist/types/tweaks/types.d.ts

@@ -1,10 +1,10 @@
-/** An option for a select / radio grid: a bare string, or `{ value, label }`. */
-export type Option = string | {
-    value: string;
+/** An option for a select / radio grid: a bare string or number, or `{ value, label }`; the param is the value as written. */
+export type Option = string | number | {
+    value: string | number;
     label?: string;
     color?: string;
 };
-/** A colour stop in a gradient. */
+/** A color stop in a gradient. */
 export type GradientStop = {
     color: string;
     pos: number;
@@ -15,10 +15,11 @@ export type GradientStop = {
 export type GradientInterpolation = "srgb" | "hsl" | "hwb" | "oklch" | "oklab" | "lch" | "lab" | "display-p3" | "rec2020";
 /** What a sides control accepts: one number for all four; `[vertical, horizontal]`,
  *  `[top, horizontal, bottom]` or `[top, right, bottom, left]` (CSS order); a CSS shorthand
- *  string like `"8px 16px"` (the numbers are read in the control's unit); or any subset of
+ *  string like `"1rem 2rem"` (its unit becomes the control's when `unit` isn't given; mixed
+ *  units warn and read as px); or any subset of
  *  the four as an object. With `corners: true` the four are the corners from top-left round,
  *  the same CSS order, under the same keys, and they floor at 0 unless `min` says otherwise. */
-export type SidesInput = number | number[] | string | {
+export type SidesInput = number | readonly number[] | string | {
     top?: number;
     right?: number;
     bottom?: number;
@@ -33,9 +34,9 @@ export interface SidesValue {
     left: number;
     css: string;
 }
-/** What a shadow control accepts — any subset of its fields (px, `color` any colour the kit
+/** What a shadow control accepts — any subset of its fields (px, `color` any color the kit
  *  parses); or, as `value`, a `box-shadow` string: optional `inset`, two to four px lengths,
- *  one colour, one layer. */
+ *  one color, one layer. */
 export interface ShadowInput {
     inset?: boolean;
     x?: number;
@@ -45,7 +46,7 @@ export interface ShadowInput {
     color?: string;
 }
 /** A shadow control's value — the fields, plus the `box-shadow` CSS they resolve to (`css`),
- *  built from the numbers and the picker's own colour notation, so `el.style.boxShadow = css`. */
+ *  built from the numbers and the picker's own color notation, so `el.style.boxShadow = css`. */
 export interface ShadowValue {
     inset: boolean;
     x: number;
@@ -60,7 +61,7 @@ export interface ShadowValue {
  *  the easing's, in ms. Spring keys select the spring mode unless `mode` says otherwise. */
 export interface MotionInput {
     mode?: "easing" | "spring";
-    curve?: [number, number, number, number] | string;
+    curve?: readonly [number, number, number, number] | string;
     duration?: number;
     stiffness?: number;
     damping?: number;
@@ -87,7 +88,7 @@ export type MotionValue = {
     duration: number;
     easing: string;
 };
-/** How a gradient blends between neighbouring stops: `"linear"` (CSS's own straight blend,
+/** How a gradient blends between neighboring stops: `"linear"` (CSS's own straight blend,
  *  the default) or a CSS easing — `ease`, `ease-in`, `ease-out`, `ease-in-out`, or any
  *  `cubic-bezier(x1, y1, x2, y2)`. No browser eases a gradient natively, so `gradientCss()`
  *  samples the curve into stops; template through it rather than by hand. */
@@ -109,7 +110,7 @@ export interface ControlOptions {
     label?: string;
     /** Show/hide this control based on other values. */
     render?: (get: Get) => boolean;
-    /** Grey-out + lock this control (static, or derived from other values). */
+    /** Gray-out + lock this control (static, or derived from other values). */
     disabled?: boolean | ((get: Get) => boolean);
     /** A tooltip revealed by an ⓘ marker beside the label. */
     hint?: string;
@@ -147,12 +148,12 @@ export type SchemaObject = {
     value?: boolean;
 } | {
     type: "list";
-    options: Option[];
-    value?: string;
+    options: readonly Option[];
+    value?: string | number;
 } | {
     type: "radiogrid" | "segmented";
-    options: Option[];
-    value?: string;
+    options: readonly Option[];
+    value?: string | number;
     cols?: number;
 } | {
     type: "color";
@@ -164,7 +165,7 @@ export type SchemaObject = {
     placeholder?: string;
 } | {
     type: "interval";
-    value?: [number, number];
+    value?: readonly [number, number];
     min?: number;
     max?: number;
     step?: number;
@@ -186,7 +187,7 @@ export type SchemaObject = {
     };
 } | {
     type: "cubicbezier";
-    value?: [number, number, number, number];
+    value?: readonly [number, number, number, number];
 } | ({
     type: "shadow";
     value?: ShadowInput | string;
@@ -207,7 +208,7 @@ export type SchemaObject = {
     value?: MotionInput;
 } & MotionInput) | {
     type: "point";
-    components: Array<{
+    components: ReadonlyArray<{
         key: string;
         label?: string;
         value?: number;
@@ -215,12 +216,25 @@ export type SchemaObject = {
         max?: number;
         step?: number;
     }>;
+    value?: {
+        readonly [key: string]: number;
+    };
+    pad?: boolean;
+    invertY?: boolean;
+} | {
+    type: "point";
+    value: {
+        readonly [key: string]: number;
+    };
+    components?: undefined;
     pad?: boolean;
     invertY?: boolean;
 } | {
     type: "gradient";
-    value?: GradientValue | Array<GradientStop | [string, number]>;
-    stops?: Array<GradientStop | [string, number]>;
+    value?: GradientValue | ReadonlyArray<GradientStop | readonly [string, number]>;
+    stops?: ReadonlyArray<GradientStop | readonly [string, number]>;
+    interpolation?: GradientInterpolation;
+    easing?: GradientEasing;
 } | {
     type: "plot";
     expr?: string;
@@ -251,7 +265,10 @@ export type SchemaObject = {
     value?: string;
     /** Supplied images to pick from, as URLs or `{ value, label }`. The control becomes a row naming the chosen
      *  image that opens a pane of tiles with the upload below them, and the param is the chosen URL or the upload's data URL. */
-    options?: Option[];
+    options?: ReadonlyArray<string | {
+        value: string;
+        label?: string;
+    }>;
     /** Tiles per row in the gallery, 1 to 6 (by default one per option for two or three, 2 for one or four, then 3). */
     cols?: number;
     /** The largest upload taken, in bytes (10 MB unless set); a bigger file is refused with a note. */
@@ -260,7 +277,7 @@ export type SchemaObject = {
      *  heavier than 1.5 MB is redrawn at its size, so a phone photo can't fill storage (2560 unless set; `false` takes
      *  uploads as they are). A JPEG comes out as a JPEG at
      *  `quality`; anything else as a PNG when that is 1.5 MB or less (a screenshot, not a photo), else as a JPEG, or a WebP
-     *  when it has transparency. A GIF, an SVG, a light picture within `fit` or one the redraw wouldn't make smaller is kept as it is. */
+     *  when it has transparency. A GIF, an SVG, an animated WebP or APNG, a light picture within `fit`, or one the redraw wouldn't make smaller is kept as it is. */
     fit?: number | false;
     /** The JPEG or WebP quality of a shrunk upload, 0 to 1 (0.85 unless set). */
     quality?: number;
@@ -274,7 +291,7 @@ export type SchemaObject = {
     label?: string;
 } | {
     type: "buttongroup";
-    buttons: Record<string, () => void> | Array<{
+    buttons: Record<string, () => void> | ReadonlyArray<{
         label: string;
         action: () => void;
     }>;
@@ -282,63 +299,214 @@ export type SchemaObject = {
     type: "separator";
 } | {
     type: "tabs";
-    pages: Record<string, Schema>;
+    pages: {
+        readonly [title: string]: Schema;
+    };
 };
 /** A schema value — a shorthand, a verbose `{ type }` object, or a nested folder. */
-export type SchemaValue = number | boolean | string | [number] | [number, number] | [number, number, number] | [number, number, number, number] | [[number, number], number, number] | [[number, number], number, number, number] | Option[] | (SchemaObject & ControlOptions) | Schema;
-/** The object you hand to `tweaks(name, schema, opts?)`. */
+export type SchemaValue = SchemaValueOf<SchemaNest>;
+type SchemaValueOf<F> = number | boolean | string | readonly [number] | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] | readonly [readonly [number, number], number, number] | readonly [readonly [number, number], number, number, number] | readonly number[] | readonly (number | readonly number[])[] | readonly Option[] | {
+    options: readonly Option[];
+    value?: string | number;
+} | {
+    action: () => void;
+    label?: string;
+} | (SchemaObject & ControlOptions) | F | SchemaFolder;
+/** The object you hand to `tweaks(name, schema, opts?)`. No value is a function, so a verbose
+ *  form's callbacks (`format`, `fn`) take their parameter types from that form alone. */
 export interface Schema {
-    [key: string]: SchemaValue;
+    readonly [key: string]: SchemaValue;
+}
+type SchemaNest = Schema & {
+    readonly type?: SchemaObject["type"] | Exclude<SchemaValue, string>;
+};
+/** What tweaks() and mountControl() infer from: `Schema` with a folder's `type` left open, since a schema held in a
+ *  variable widens a verbose form's `type` to `string`; their own check then rules on the names it can still see. */
+export interface HeldSchema {
+    readonly [key: string]: HeldValue;
+}
+/** A single value as mountControl() infers it; see `HeldSchema`. */
+export type HeldValue = SchemaValueOf<HeldSchema>;
+/** A nested folder that carries its own `render` / `disabled` predicate or `hint`: chrome, not
+ *  children. Its index admits the predicate, so it gives up a child named `type`: that sets it
+ *  apart from a verbose form, whose callbacks would otherwise be typed against the predicate too. */
+export interface SchemaFolder {
+    readonly type?: undefined;
+    readonly render?: (get: Get) => boolean;
+    readonly disabled?: boolean | ((get: Get) => boolean);
+    readonly hint?: string;
+    readonly [key: string]: SchemaValue | ((get: Get) => boolean) | undefined;
+}
+/** A spring control's value: the physics, plus the time pair and mode when tuned by feel. */
+export interface SpringValue {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    visualDuration?: number;
+    bounce?: number;
+    mode?: "time" | "physics";
 }
+type OptionValue<O> = O extends string | number ? O : O extends {
+    readonly value: infer V extends string | number;
+} ? V : never;
+type ChoiceValue<V> = (V extends {
+    readonly options: readonly (infer O)[];
+} ? OptionValue<O> : never) | (V extends {
+    readonly value: infer D extends string | number;
+} ? D : never);
+type Alnum = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type Dashed<S extends string, Acc extends string = "", Run = false> = S extends `${infer C}${infer R}` ? C extends Alnum ? Dashed<R, `${Acc}${C}`, false> : Run extends true ? Dashed<R, Acc, true> : Dashed<R, `${Acc}-`, true> : Acc;
+type TrimDash<S extends string> = S extends `-${infer R}` ? TrimDash<R> : S extends `${infer R}-` ? TrimDash<R> : S;
+/** A tab title's key under `params`: lower-case, each run of other characters a `-`, trimmed
+ *  (`"Layout & Grid"` → `"layout-grid"`). Two titles that slug alike are told apart at runtime only. */
+export type TabKey<T extends string> = string extends T ? string : TrimDash<Dashed<Lowercase<T>>> extends infer K extends string ? (K extends "" ? "tab" : K) : never;
+type TabClash<P> = true extends {
+    [T in keyof P & string]: TabKey<T> extends {
+        [U in Exclude<keyof P & string, T>]: TabKey<U>;
+    }[Exclude<keyof P & string, T>] ? true : false;
+}[keyof P & string] ? true : false;
+type Valueless = "button" | "buttongroup" | "separator" | "fpsgraph" | "monitor";
+type Hinge = {
+    list: "options";
+    radiogrid: "options";
+    segmented: "options";
+    point: "components" | "value";
+    tabs: "pages";
+};
+type TypedValue<V> = V extends {
+    readonly type: "slider" | "number";
+} ? number : V extends {
+    readonly type: "checkbox";
+} ? boolean : V extends {
+    readonly type: "list" | "radiogrid" | "segmented";
+} ? (V extends {
+    readonly options: readonly unknown[];
+} ? ChoiceValue<V> : never) : V extends {
+    readonly type: "color" | "text" | "image" | "plot";
+} ? string : V extends {
+    readonly type: "interval";
+} ? [number, number] : V extends {
+    readonly type: "cubicbezier";
+} ? [number, number, number, number] : V extends {
+    readonly type: "spring";
+} ? SpringValue : V extends {
+    readonly type: "motion";
+} ? MotionValue : V extends {
+    readonly type: "shadow";
+} ? ShadowValue : V extends {
+    readonly type: "sides";
+} ? SidesValue : V extends {
+    readonly type: "gradient";
+} ? GradientValue : V extends {
+    readonly type: "point";
+} ? (V extends {
+    readonly components: readonly [];
+} ? never : V extends {
+    readonly components: readonly (infer C)[];
+} ? {
+    [K in C extends {
+        readonly key: infer Key extends string;
+    } ? Key : never]: number;
+} : V extends {
+    readonly value: infer P extends object;
+} ? (keyof P extends never ? never : {
+    -readonly [K in keyof P & string]: number;
+}) : never) : V extends {
+    readonly type: "tabs";
+} ? (V extends {
+    readonly pages: infer P extends object;
+} ? (keyof P extends never ? never : TabClash<P> extends true ? Record<string, Params> : {
+    [T in keyof P & string as TabKey<T>]: ParamsOf<P[T]>;
+}) : never) : unknown;
+/** The value a schema entry puts on `params`. */
+export type ValueOf<V> = V extends {
+    readonly type: infer T;
+} ? (string extends T ? any : T extends SchemaObject["type"] ? (T extends keyof Hinge ? ([Extract<Hinge[T], keyof V>] extends [never] ? ShorthandValue<V> : VerboseValue<V, T>) : VerboseValue<V, T>) : ShorthandValue<V>) : ShorthandValue<V>;
+type VerboseValue<V, T> = T extends Valueless ? never : TypedValue<V>;
+type ShorthandValue<V> = V extends readonly [readonly [number, number], ...unknown[]] ? [number, number] : V extends readonly [number] | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] ? number : V extends readonly [number, ...number[]] ? V[number] : V extends readonly [] ? undefined : V extends readonly number[] ? number : V extends readonly (number | readonly number[])[] ? [number, number] : V extends number ? number : V extends boolean ? boolean : V extends string ? string : V extends readonly (infer O)[] ? OptionValue<O> : V extends {
+    readonly action: (...a: any[]) => any;
+} ? never : V extends {
+    readonly options: readonly unknown[];
+} ? ChoiceValue<V> : V extends object ? Entries<V, true> : unknown;
+type Reserved = "__proto__" | "constructor" | "prototype";
+type FolderChrome<V, K> = K extends "disabled" | "hint" ? true : K extends "render" ? (V extends (...a: any[]) => any ? true : false) : false;
+type Entries<S, Nested extends boolean> = string extends keyof S ? Params : {
+    -readonly [K in keyof S & string as K extends Reserved ? never : ValueOf<S[K]> extends never ? never : Nested extends true ? (FolderChrome<S[K], K> extends true ? never : K) : K]: ValueOf<S[K]>;
+};
+/** The live values a schema builds, nested like the schema; a plain `Schema` gives the loose `Params`. */
+export type ParamsOf<S> = Entries<S, false>;
+type CheckValue<V> = V extends {
+    readonly type: infer T;
+} ? (string extends T ? V : T extends SchemaObject["type"] ? (V extends {
+    readonly type: "tabs";
+    readonly pages: infer P;
+} ? {
+    readonly pages: {
+        [K in keyof P]: KnownTypes<P[K]>;
+    };
+} : T extends keyof Hinge ? ([Extract<Hinge[T], keyof V>] extends [never] ? unknown : FitsForm<V, T>) : FitsForm<V, T>) : {
+    readonly type: NotAControlType;
+}) : V extends readonly unknown[] | ((...a: any[]) => any) ? unknown : V extends object ? KnownTypes<V> : unknown;
+type FormOf<O, T> = O extends {
+    readonly type: infer N;
+} ? (T extends N ? O & ControlOptions : never) : never;
+type FitsForm<V, T> = V extends FormOf<SchemaObject, T> ? unknown : FormOf<SchemaObject, T>;
+type NotAControlType = {
+    readonly "names no control: see the type list in AGENTS.md": true;
+};
+/** A schema whose every `type` names a control (`tweaks()` checks it; `{ type: "slidr" }` is an error). */
+export type KnownTypes<S> = {
+    [K in keyof S]: CheckValue<S[K]>;
+};
+/** One schema value whose `type` names a control (`mountControl()` checks it). */
+export type KnownType<V> = CheckValue<V>;
 /** A theme — token overrides applied over the default monochrome look. Every key is
  *  optional, so a partial theme only moves what it names; unset tokens keep their default.
- *  Use the friendly names here, or any raw `--tw-*` custom property. Apply at build via
+ *  Keys are the `--tw-*` custom properties themselves. Apply at build via
  *  `tweaks(name, schema, { theme })`, or live via `panel.setTheme(theme)`. The kit's whole
  *  appearance runs on these custom properties — this is the public theming surface. */
 export interface Theme {
     /** Brand accent — slider fills, focus rings, active highlights (default: neutral, no accent). */
-    accent?: string;
-    /** Text drawn on the accent (active segment / radio label). Auto-derived from the accent's luminance if unset. */
-    onAccent?: string;
+    "--tw-accent"?: string;
+    /** Text drawn on the accent (active segment / radio label); the primary text tone unless set, so set it with a light accent. */
+    "--tw-on-accent"?: string;
     /** Panel background, reused for recessed wells. */
-    base?: string;
+    "--tw-base"?: string;
     /** Popover / dropdown background. */
-    dropdownBg?: string;
+    "--tw-dropdown-bg"?: string;
     /** Control surface and its hover / active steps. */
-    surface?: string;
-    surfaceHover?: string;
-    surfaceActive?: string;
+    "--tw-surface"?: string;
+    "--tw-surface-hover"?: string;
+    "--tw-surface-active"?: string;
     /** Hairline border and its hover step. */
-    border?: string;
-    borderHover?: string;
+    "--tw-border"?: string;
+    "--tw-border-hover"?: string;
     /** Text-selection highlight wash. */
-    selection?: string;
+    "--tw-selection"?: string;
     /** Text tones — panel title, section heading, primary value text, control label, and the muted / faint / focus tones. */
-    title?: string;
-    section?: string;
-    text?: string;
-    label?: string;
-    textMuted?: string;
-    textFaint?: string;
-    focus?: string;
-    /** Copy-confirmation accent. */
-    success?: string;
-    /** Invalid-state accent (the plot's bad-expression cue). */
-    danger?: string;
+    "--tw-text-root"?: string;
+    "--tw-text-section"?: string;
+    "--tw-text-primary"?: string;
+    "--tw-text-label"?: string;
+    "--tw-text-secondary"?: string;
+    "--tw-text-tertiary"?: string;
+    "--tw-text-focus"?: string;
+    /** Copy-confirmation accent, and the invalid-state accent (the plot's bad-expression cue). */
+    "--tw-success"?: string;
+    "--tw-danger"?: string;
     /** Popover shadow, the panel's container elevation, and its lifted (floating / dragging) variant. */
-    shadow?: string;
-    shadowPanel?: string;
-    shadowPanelLifted?: string;
+    "--tw-shadow-dropdown"?: string;
+    "--tw-shadow-panel"?: string;
+    "--tw-shadow-panel-lifted"?: string;
     /** Font stack, and the monospace stack (the plot's expression field). */
-    font?: string;
-    fontMono?: string;
-    /** Control corner radius and row height — a bare number is treated as px. */
-    radius?: number | string;
-    density?: number | string;
-    /** The panel's width (256px by default) — a bare number is treated as px. */
-    width?: number | string;
-    /** Escape hatch — any raw token, e.g. `"--tw-accent": "#6c8cff"`. */
-    [token: string]: string | number | undefined;
+    "--tw-font-sans"?: string;
+    "--tw-font-mono"?: string;
+    /** Control corner radius, row height and the panel's width (256px by default), as CSS lengths. */
+    "--tw-radius"?: string;
+    "--tw-row-height"?: string;
+    "--tw-width"?: string;
+    /** Any other token. */
+    [token: `--${string}`]: string | undefined;
 }
 /** Options for a programmatic write — `set()`, `setMany()`, `fromJSON()`. */
 export interface SetOptions {
@@ -347,29 +515,25 @@ export interface SetOptions {
      *  controls, persistence and undo still follow it: it's an undo step like any other. */
     silent?: boolean;
 }
-/** Panel options (third arg to `tweaks()`). */
-/** The corner a floating panel anchors to. */
-export type FloatingCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
-/** Where a floating panel starts: `x` / `y` are its insets in px (16 by default) from the two
- *  edges of `corner` (top-left by default), and it keeps that corner as the window resizes.
- *  The far edge keeps a gap of `y` when the height caps; CSS `--tw-float-gap` overrides it. */
+/** Where a floating panel starts: `x` / `y` are its insets in px (16 by default) from the
+ *  viewport's top-left. The far edge keeps a gap of `y` when the height caps; CSS
+ *  `--tw-float-gap` overrides it. */
 export interface FloatingPlacement {
     x?: number;
     y?: number;
-    corner?: FloatingCorner;
 }
+/** Panel options (third arg to `tweaks()`). */
 export interface TweaksOptions {
-    /** Theme overrides (friendly names or raw `--tw-*`); `null` / omitted = default monochrome. */
+    /** Theme overrides as `--tw-*` tokens; `null` / omitted = default monochrome. */
     theme?: Theme | null;
-    /** Persist values to localStorage + enable presets — a key, or `true` to key by name. */
+    /** Persist values to localStorage + enable presets — a key, or `true` to key by name. Uploaded images go to
+     *  IndexedDB under the same key, and come back by `ready`. */
     persist?: string | boolean;
     /** With `persist`, `false` keeps saving values but leaves the Presets menu out of the
      *  toolbar (the presets API still works). On by default. */
     presets?: boolean;
-    /** Add a filter/search field to the toolbar. */
-    filter?: boolean;
     /** Start the panel already floated (fixed-positioned): `true` → 16px from the top-left, or a
-     *  placement `{ x, y, corner }`. Its height caps at the window and it scrolls, header and all. */
+     *  placement `{ x, y }`. Its height caps at the window and it scrolls, header and all. */
     floating?: boolean | FloatingPlacement;
     /** Drag the header to reposition the panel — on by default. An inline panel lifts into a
      *  floating layer on first drag; set `false` to pin it in place. */
@@ -380,15 +544,18 @@ export interface TweaksOptions {
     undo?: boolean;
     /** Custom reset handler (e.g. restore real app defaults + rebuild). */
     onReset?: () => void;
-    /** Fired when a drag/scrub on any control begins. */
-    onEditStart?: () => void;
-    /** Fired when a drag/scrub ends. */
-    onEditEnd?: () => void;
 }
-/** The live values bag — `params[key]` for each control; `_last` is the last-changed key. */
-export type Params = Record<string, any> & {
-    _last?: string;
-};
+/** The live values bag, loosely typed — `params[key]` for each control. A schema literal passed
+ *  to `tweaks()` gets its exact shape instead (`ParamsOf`). */
+export type Params = Record<string, any>;
+/** The keys `set()` and `setMany()` take: a typed panel's controls by dotted path (`size`, `card.size`), so a typo is a
+ *  compile error; any string for a panel built from a plain `Schema`. An object-valued control's own fields read as
+ *  paths too (`drop.blur`): the types can't tell its value from a folder, so they allow what the runtime refuses. Past ten
+ *  folders deep the rest of a path is any string, since spelling every one out overran tsc's depth limit. */
+export type PanelPath<P> = PathsOf<P, []>;
+type PathsOf<P, D extends unknown[]> = string extends keyof P ? string : D["length"] extends 10 ? string : {
+    [K in keyof P & string]: K | (P[K] extends readonly unknown[] ? never : P[K] extends object ? `${K}.${PathsOf<P[K], [...D, 0]>}` : never);
+}[keyof P & string];
 /** The whole-panel state `toJSON()` returns / `fromJSON()` accepts: every control value
  *  (nested to mirror folders/tabs) plus UI state — which folders are collapsed and which
  *  tab is active. JSON-safe; persist it however you like. Both `values` and `ui` are
@@ -410,25 +577,31 @@ export interface PanelState {
         tabs?: Record<string, string | null>;
     };
 }
-/** The panel object `tweaks()` returns. */
-export interface Panel {
+/** The panel object `tweaks()` returns; `P` is its values' shape. A bare `Panel` takes any panel, typed or not (its
+ *  default is `any`, not `Params`: `set()`'s typed paths would make a typed panel unassignable to `Panel<Params>`). */
+export interface Panel<P = any> {
     /** The panel root element — append it to the DOM. */
     el: HTMLElement;
     /** Live values, updated in place as controls change. */
-    params: Params;
-    /** Resolves once any lazily-loaded controls have hydrated (resolves immediately when none). */
-    ready: Promise<Panel>;
-    /** Subscribe to changes; returns an unsubscribe fn. */
-    on(fn: (params: Params, last?: string) => void): () => void;
+    params: P;
+    /** Resolves once any lazily-loaded controls have hydrated and, for a panel that persists an image control, its
+     *  stored images have loaded (resolves immediately when there's neither). */
+    ready: Promise<Panel<P>>;
+    /** Subscribe to changes; `last` is the changed control's dotted path (`size`, `card.size`), as `set()` and `changes()`
+     *  name it, or undefined when many changed at once (a restore, `reset()`, `fromJSON`, `setMany`). */
+    on(fn: (params: P, last?: string) => void): () => void;
     /** Set a control's value programmatically. Nested controls take a dotted path
-     *  ("folder.child", "tabs.page.child"); a bare key also reaches a nested control
-     *  when it's unambiguous. A key matching no control is stored on `params` as-is. */
-    set(key: string, value: unknown, options?: SetOptions): void;
+     *  ("folder.child", "tabs.page.child"); at runtime a bare key also reaches a nested control
+     *  when it's unambiguous, though a typed panel's types take the full path. A key matching
+     *  no control, or a folder or tab, is refused with a console warning. */
+    set(key: PanelPath<P>, value: unknown, options?: SetOptions): void;
     /** Set several controls at once — a flat map of keys (dotted for nested controls), e.g.
      *  `setMany({ "shadow.radius": 28, blur: 48 })`. Resolves each key like `set()`, then fires
      *  listeners + persists ONCE for the whole batch, where N separate `set()` calls would fire
      *  N times. Unknown / ambiguous / reserved keys warn and are skipped. */
-    setMany(values: Record<string, unknown>, options?: SetOptions): void;
+    setMany(values: {
+        readonly [K in PanelPath<P>]?: unknown;
+    }, options?: SetOptions): void;
     /** Reset every control to its default (or run `opts.onReset`). */
     reset(): void;
     /** Serialize the whole panel — every control value plus UI state (collapsed folders,
@@ -479,6 +652,9 @@ export interface Control {
     /** Show a short message on the control for a moment. Only the image control supplies it; the panel calls it when
      *  storage refuses the control's value. */
     note?(message: string): void;
+    /** The hard range set() fits a number into, as the control resolved it (derived bounds too); a point's per component.
+     *  Only the numeric controls supply it; the panel's clamp notice reads it. */
+    range?: [number, number] | Record<string, [number, number]>;
 }
 /** Options for `mountControl(host, value, opts?)` — one control, no panel. */
 export interface MountOptions {
@@ -507,16 +683,16 @@ export interface MountedControl {
     /** Resolves with this handle once the control has built — immediately on the single-file build. */
     ready: Promise<MountedControl>;
 }
-/** The notations the colour picker edits in (its mode dropdown). The emitted value follows
- *  the mode: `hex` gives `#rrggbb`, the wide-gamut modes give a CSS colour like `oklch(…)`. */
+/** The notations the color picker edits in (its mode dropdown). The emitted value follows
+ *  the mode: `hex` gives `#RRGGBB`, the wide-gamut modes give a CSS color like `oklch(…)`. */
 export type ColorMode = "hex" | "srgb" | "css" | "hsl" | "hwb" | "oklch" | "oklab" | "lch" | "lab" | "p3" | "rec2020";
 /** Options for `createColorPicker(opts?)` — the picker body alone, no trigger row. */
 export interface ColorPickerOptions {
-    /** The colour it opens on — any CSS colour string (default `#7c5cff`). */
+    /** The color it opens on — any CSS color string (default `#7c5cff`). */
     value?: string;
     /** The notation it opens in (default `oklch`). */
     mode?: ColorMode;
-    /** Fired with the new colour string whenever it changes — by hand or through `set()`. */
+    /** Fired with the new color string whenever it changes — by hand or through `set()`. */
     onChange?: (value: string) => void;
 }
 /** The handle `createColorPicker()` returns. Bring your own trigger: append `el` to a popover
@@ -524,11 +700,11 @@ export interface ColorPickerOptions {
 export interface ColorPicker {
     /** The picker's root (`.tw-color-picker`), stable from creation; it carries the kit's tokens,
      *  so the picker renders anywhere. On the code-split build the editor fills it in once the
-     *  colour chunk has loaded. */
+     *  color chunk has loaded. */
     el: HTMLElement;
-    /** Apply a colour — the picker updates AND `onChange` fires (when the colour actually changed). */
+    /** Apply a color — the picker updates AND `onChange` fires (when the color actually changed). */
     set(value: string): void;
-    /** The current colour, serialized in the picker's mode. */
+    /** The current color, serialized in the picker's mode. */
     get(): string;
     /** The current notation. */
     mode(): ColorMode;
@@ -554,3 +730,4 @@ declare global {
         "tw:change": CustomEvent<TwChangeDetail>;
     }
 }
+export {};