@kitlangton/knobs 0.4.0-next.11 → 0.4.0-next.13

package/dist/review-react.js

@@ -2965,13 +2965,17 @@ var css2 = `
 .knobs-tree-row[aria-expanded="true"]>.knobs-tree-caret{transform:rotate(90deg)}
 .knobs-tree-row:not([aria-expanded])>.knobs-tree-caret{visibility:hidden}
 .knobs-tree-icon{flex:none;display:flex;align-items:center;justify-content:center;width:14px;margin-right:6px;color:var(--_k-fg-3);font-size:calc(var(--_k-font-size) - 1px)}
-.knobs-tree-label{position:relative;flex:1;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+/* The label wins the room: it keeps its width while the detail (which only takes what's left)
+   fades out at its end, and gives way only once the detail is gone. Each fades where it's cut. */
+.knobs-tree-label{position:relative;flex:0 1 auto;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+.knobs-tree-row[data-editing]>.knobs-tree-label{flex-grow:1}
 .knobs-tree-row[data-ancestor] .knobs-tree-label{color:var(--_k-fg-2)}
 .knobs-tree-label .knobs-tree-mark{color:var(--_k-accent)}
 .knobs-tree-row[data-off~="visible"] :is(.knobs-tree-label,.knobs-tree-icon){opacity:.45}
 .knobs-tree-row[data-off~="locked"] .knobs-tree-label{color:var(--_k-fg-2)}
-.knobs-tree-detail{flex:none;margin-left:6px;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
-.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:4px}
+.knobs-tree-detail{flex:1 1 0;min-width:0;overflow:hidden;padding-left:6px;text-align:right;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
+.knobs-tree-row[data-editing]>.knobs-tree-detail{flex-grow:0;visibility:hidden}
+.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:auto;padding-left:4px}
 .knobs-ui .knobs-tree-toggle{display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;border-radius:calc(var(--_k-radius) * 999);color:var(--_k-fg-3);cursor:pointer;opacity:0;transition:opacity .12s,color .12s,background .12s}
 .knobs-ui .knobs-tree-toggle svg{width:12px;height:12px}
 .knobs-tree-row:is(:hover,[data-active],[aria-selected="true"]) .knobs-tree-toggle,.knobs-ui .knobs-tree-toggle[aria-pressed="false"]{opacity:1}
@@ -5327,7 +5331,7 @@ function tree(container, options) {
     text.className = "knobs-tree-text";
     label.append(text);
     const detail = doc.createElement("span");
-    detail.className = "knobs-tree-detail";
+    detail.className = "knobs-tree-detail knobs-scroll-fade-x";
     const tools = doc.createElement("span");
     tools.className = "knobs-tree-tools";
     el.append(caret, icon, label, detail, tools);

package/dist/review-solid.js

@@ -2964,13 +2964,17 @@ var css2 = `
 .knobs-tree-row[aria-expanded="true"]>.knobs-tree-caret{transform:rotate(90deg)}
 .knobs-tree-row:not([aria-expanded])>.knobs-tree-caret{visibility:hidden}
 .knobs-tree-icon{flex:none;display:flex;align-items:center;justify-content:center;width:14px;margin-right:6px;color:var(--_k-fg-3);font-size:calc(var(--_k-font-size) - 1px)}
-.knobs-tree-label{position:relative;flex:1;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+/* The label wins the room: it keeps its width while the detail (which only takes what's left)
+   fades out at its end, and gives way only once the detail is gone. Each fades where it's cut. */
+.knobs-tree-label{position:relative;flex:0 1 auto;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+.knobs-tree-row[data-editing]>.knobs-tree-label{flex-grow:1}
 .knobs-tree-row[data-ancestor] .knobs-tree-label{color:var(--_k-fg-2)}
 .knobs-tree-label .knobs-tree-mark{color:var(--_k-accent)}
 .knobs-tree-row[data-off~="visible"] :is(.knobs-tree-label,.knobs-tree-icon){opacity:.45}
 .knobs-tree-row[data-off~="locked"] .knobs-tree-label{color:var(--_k-fg-2)}
-.knobs-tree-detail{flex:none;margin-left:6px;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
-.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:4px}
+.knobs-tree-detail{flex:1 1 0;min-width:0;overflow:hidden;padding-left:6px;text-align:right;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
+.knobs-tree-row[data-editing]>.knobs-tree-detail{flex-grow:0;visibility:hidden}
+.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:auto;padding-left:4px}
 .knobs-ui .knobs-tree-toggle{display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;border-radius:calc(var(--_k-radius) * 999);color:var(--_k-fg-3);cursor:pointer;opacity:0;transition:opacity .12s,color .12s,background .12s}
 .knobs-ui .knobs-tree-toggle svg{width:12px;height:12px}
 .knobs-tree-row:is(:hover,[data-active],[aria-selected="true"]) .knobs-tree-toggle,.knobs-ui .knobs-tree-toggle[aria-pressed="false"]{opacity:1}
@@ -5326,7 +5330,7 @@ function tree(container, options) {
     text.className = "knobs-tree-text";
     label.append(text);
     const detail = doc.createElement("span");
-    detail.className = "knobs-tree-detail";
+    detail.className = "knobs-tree-detail knobs-scroll-fade-x";
     const tools = doc.createElement("span");
     tools.className = "knobs-tree-tools";
     el.append(caret, icon, label, detail, tools);
@@ -12702,11 +12706,12 @@ var init_player = __esm(() => {
 
 // src/ui/solid.ts
 import {
-  children,
   createEffect,
+  createMemo,
   createRoot,
   getOwner,
   onCleanup,
+  splitProps,
   untrack
 } from "solid-js";
 import { insert } from "solid-js/web";

package/dist/review.js

@@ -3006,13 +3006,17 @@ var css2 = `
 .knobs-tree-row[aria-expanded="true"]>.knobs-tree-caret{transform:rotate(90deg)}
 .knobs-tree-row:not([aria-expanded])>.knobs-tree-caret{visibility:hidden}
 .knobs-tree-icon{flex:none;display:flex;align-items:center;justify-content:center;width:14px;margin-right:6px;color:var(--_k-fg-3);font-size:calc(var(--_k-font-size) - 1px)}
-.knobs-tree-label{position:relative;flex:1;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+/* The label wins the room: it keeps its width while the detail (which only takes what's left)
+   fades out at its end, and gives way only once the detail is gone. Each fades where it's cut. */
+.knobs-tree-label{position:relative;flex:0 1 auto;min-width:0;overflow:hidden;font-weight:var(--_k-weight)}
+.knobs-tree-row[data-editing]>.knobs-tree-label{flex-grow:1}
 .knobs-tree-row[data-ancestor] .knobs-tree-label{color:var(--_k-fg-2)}
 .knobs-tree-label .knobs-tree-mark{color:var(--_k-accent)}
 .knobs-tree-row[data-off~="visible"] :is(.knobs-tree-label,.knobs-tree-icon){opacity:.45}
 .knobs-tree-row[data-off~="locked"] .knobs-tree-label{color:var(--_k-fg-2)}
-.knobs-tree-detail{flex:none;margin-left:6px;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
-.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:4px}
+.knobs-tree-detail{flex:1 1 0;min-width:0;overflow:hidden;padding-left:6px;text-align:right;color:var(--_k-fg-3);font-variant-numeric:tabular-nums}
+.knobs-tree-row[data-editing]>.knobs-tree-detail{flex-grow:0;visibility:hidden}
+.knobs-tree-tools{flex:none;display:flex;align-items:center;gap:1px;margin-left:auto;padding-left:4px}
 .knobs-ui .knobs-tree-toggle{display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;border-radius:calc(var(--_k-radius) * 999);color:var(--_k-fg-3);cursor:pointer;opacity:0;transition:opacity .12s,color .12s,background .12s}
 .knobs-ui .knobs-tree-toggle svg{width:12px;height:12px}
 .knobs-tree-row:is(:hover,[data-active],[aria-selected="true"]) .knobs-tree-toggle,.knobs-ui .knobs-tree-toggle[aria-pressed="false"]{opacity:1}
@@ -10484,7 +10488,7 @@ function tree(container, options) {
     text.className = "knobs-tree-text";
     label.append(text);
     const detail = doc.createElement("span");
-    detail.className = "knobs-tree-detail";
+    detail.className = "knobs-tree-detail knobs-scroll-fade-x";
     const tools = doc.createElement("span");
     tools.className = "knobs-tree-tools";
     el.append(caret, icon, label, detail, tools);

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

@@ -45,6 +45,8 @@ export interface ToolbarDescriptor extends DescriptorMeta {
         readonly global?: boolean;
         readonly disabled?: boolean;
     }[];
+    /** `false`: icons only (see `toolbar`). */
+    readonly labels?: boolean;
     readonly default?: undefined;
     readonly bind?: undefined;
 }
@@ -77,11 +79,11 @@ export interface ReadoutDescriptor extends DescriptorMeta {
 export type ControlDescriptor = ValueDescriptor | SpringBindingDescriptor | ActionDescriptor | ToolbarDescriptor | ReadoutDescriptor;
 export interface ValueDescriptor extends DescriptorMeta {
     readonly bind?: undefined;
-    readonly kind: "knob" | "number" | "choice" | "toggle" | "bool" | "spring" | "color" | "point" | "easing" | "vec2" | "vec3" | "range" | "angle" | "seed" | "keybind" | "gradient" | "curve";
+    readonly kind: "knob" | "number" | "choice" | "toggle" | "bool" | "spring" | "color" | "point" | "easing" | "vec2" | "vec3" | "range" | "angle" | "seed" | "keybind" | "text" | "gradient" | "curve";
     /**
      * Springs take `{ duration, bounce }`, colours a CSS string, points and vec2 `{ x, y }`, vec3
      * `{ x, y, z }`, easings `[x1, y1, x2, y2]`, ranges `[low, high]`, keybinds a combination
-     * string (`"Meta+K"`), gradients `[{ at, color }]` and curves `[{ x, y }]`.
+     * string (`"Meta+K"`), text a string, gradients `[{ at, color }]` and curves `[{ x, y }]`.
      */
     readonly default: Value;
     readonly min?: number;
@@ -103,6 +105,10 @@ export interface ValueDescriptor extends DescriptorMeta {
     readonly axes?: readonly string[];
     /** Angles: carry past the ends a whole turn (on for a full turn by default). */
     readonly wrap?: boolean;
+    /** Text: lines in a box that grows with them (see `text`). */
+    readonly multiline?: boolean;
+    /** Text: shown in the empty field. */
+    readonly placeholder?: string;
     /** Gradients: blend in `oklab` (default) or `srgb`. */
     readonly space?: GradientSpace;
     /** Curves: the y range, `[0, 1]` by default (`min` and `max` work too). */
@@ -130,6 +136,8 @@ export interface RemoteControlsOptions {
     readonly nullDefaults?: boolean;
     readonly values?: State;
     readonly presets?: Readonly<Record<string, State>>;
+    /** Presets that belong to one tab or group (see `ControlsOptions.scopedPresets`). */
+    readonly scopedPresets?: Readonly<Record<string, Readonly<Record<string, State>>>>;
     /** Groups pinned above the tab strip, outside the presets (see `ControlsOptions.pinned`). */
     readonly pinned?: readonly string[];
     /** Numbered presets per group, e.g. the phone's preset sets (see `ControlsOptions.groupPresets`). */

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

@@ -101,6 +101,12 @@ export interface Choice<T extends string = string> extends FieldMeta {
      * spare and there are at most four options, and a menu otherwise, switching as the width changes.
      */
     readonly display?: "menu" | "segmented";
+    /**
+     * The options are versions of the design: each is a preset in the panel's top strip (the
+     * default option is the default preset), which is where you switch them, and the choice gets no
+     * row of its own. See `choice`.
+     */
+    readonly variants?: true;
 }
 export interface Toggle extends FieldMeta {
     readonly kind: "toggle";
@@ -215,6 +221,15 @@ export interface KeybindField extends FieldMeta {
     readonly kind: "keybind";
     readonly value: string;
 }
+/** Words: a name, a caption, a prompt. Typed into a field; `multiline` for a box of lines. */
+export interface TextField extends FieldMeta {
+    readonly kind: "text";
+    readonly value: string;
+    /** Lines (Enter starts a new one) in a box that grows with them; one line otherwise. */
+    readonly multiline?: boolean;
+    /** Shown in the empty field. */
+    readonly placeholder?: 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
@@ -245,8 +260,10 @@ export interface ToolbarItem {
 export interface ToolbarField extends FieldMeta {
     readonly kind: "toolbar";
     readonly items: readonly ToolbarItem[];
+    /** `false`: icons only, each label in its tooltip (see `toolbar`). */
+    readonly labels?: boolean;
 }
-export type ValueField = Knob | Choice | Toggle | SpringField | ColorField | PointField | EasingField | VecField | RangeField | AngleField | SeedField | KeybindField | GradientField | CurveField;
+export type ValueField = Knob | Choice | Toggle | SpringField | ColorField | PointField | EasingField | VecField | RangeField | AngleField | SeedField | KeybindField | TextField | 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). */
@@ -335,12 +352,20 @@ export declare const isReadout: (field: {
 /** 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>>;
+/**
+ * The schema's variants choice (`choice(…, { variants: true })`), if it has one. A pinned choice
+ * (`isPinned`) is never the variants choice: pinned wins, and it stays an ordinary choice.
+ */
+export declare function variantsOf(schema: Schema, isPinned?: (key: string) => boolean): {
+    key: string;
+    field: Choice;
+} | undefined;
 /**
  * The schema's pinned keys (values, actions and readouts alike): every key of a group in `groups`,
  * or whose first field that gives `pinned` says `true`, and ungrouped fields that say so themselves.
  */
 export declare function pinnedKeys(schema: Schema, groups?: readonly string[]): ReadonlySet<string>;
-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;
+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 | TextField ? 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;
@@ -371,9 +396,17 @@ export declare function valueKeys(schema: Schema): string[];
 export declare function knob(value: number, options: Omit<Knob, "kind" | "value" | "step"> & {
     step?: number;
 }): Knob;
+/**
+ * `choice("glass", ["glass", "solid", "flat"])`: one of a set of options, as segments or a menu.
+ * With `variants: true` the options are versions of the design instead: each becomes a preset in
+ * the panel's top strip (the default option is the default preset, the others follow in order),
+ * the choice has no row, and Random leaves it be. The store's `presets` add values to a variant
+ * by its option (`{ Roll: { speed: 0.8 } }`).
+ */
 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";
+    readonly variants?: boolean;
 }): Choice<T[number]>;
 /**
  * `action("Replay", { run, shortcut: "Shift+K", global: true, rebind: true })`: a button row. Its
@@ -477,6 +510,15 @@ export declare function seed(value: number, options?: FieldMeta & {
 }): SeedField;
 /** A key combination captured by pressing it (`"Meta+Shift+K"`, `""` for none). */
 export declare function keybind(value?: string, meta?: FieldMeta): KeybindField;
+/**
+ * Words typed into a field: `text("Hello")`, `text("", { multiline: true, placeholder: "Notes" })`.
+ * One line unless `multiline` (a line break typed or set there becomes a space). Out of Random
+ * and Mutate.
+ */
+export declare function text(value?: string, options?: FieldMeta & {
+    multiline?: boolean;
+    placeholder?: string;
+}): TextField;
 /**
  * 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`
@@ -515,8 +557,14 @@ type ResolvedShortcut = {
 export declare function toolbarShortcut(item: ToolbarItem): ResolvedShortcut | undefined;
 /** An action row's shortcut as `{ key, scope }`, or undefined without one. */
 export declare function actionShortcut(field: ActionField): ResolvedShortcut | undefined;
-/** A wrapping row of buttons with icons and shortcut chips; holds no value. */
-export declare function toolbar(items: readonly ToolbarItem[], meta?: FieldMeta): ToolbarField;
+/**
+ * A wrapping row of buttons with icons and shortcut chips; holds no value. When every item has an
+ * icon and the labels don't fit on one row, it's one row of icons, each label in its tooltip;
+ * `labels: false` always shows icons only, `labels: true` always shows the labels.
+ */
+export declare function toolbar(items: readonly ToolbarItem[], meta?: FieldMeta & {
+    readonly labels?: boolean;
+}): 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;

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

@@ -50,6 +50,19 @@ export interface PresetRef {
     readonly kind: "preset" | "variant";
     readonly id: string;
 }
+/**
+ * A preset strip that belongs to one tab or group (see `ControlsOptions.scopedPresets`): its
+ * presets and saved variants move only its own keys, and it keeps its own active preset.
+ */
+export interface PresetScope<V = State> {
+    /** The tab or group it's named for. */
+    readonly id: string;
+    /** The keys it moves: the tab's or group's, pinned ones aside. */
+    readonly keys: readonly string[];
+    /** By id, `default` first; keys outside the scope sit at their defaults. */
+    readonly presets: Readonly<Record<string, V>>;
+    readonly variants: Variants<V>;
+}
 export interface ControlAction<V = State> {
     readonly id?: string;
     readonly label: string;
@@ -169,8 +182,9 @@ export interface MountPanelOptions extends LabelOptions {
      */
     readonly header?: boolean | HeaderOptions;
     /**
-     * `false` drops the scope line beside the title (`Shape › Cohesion`, where keys go, and a faint
-     * `esc ↑ Shape` for where Esc goes). The focus lens and the armed frame stay.
+     * `true` shows a scope line beside the title (`Shape › Cohesion`, where keys go, and a faint
+     * `esc ↑ Shape` for where Esc goes). Off by default; the focus lens and the armed frame show
+     * either way.
      */
     readonly crumbs?: boolean;
     /**
@@ -243,6 +257,13 @@ export interface MountPanelOptions extends LabelOptions {
     readonly density?: DensityMode;
     readonly renderer?: RendererMode;
     readonly variants?: boolean;
+    /**
+     * The presets as chips in a tray (`"chips"`) or as rows like a menu's (`"list"`). `"auto"` (the
+     * default) shows chips while they fit on two lines and the list once they'd take more.
+     */
+    readonly presetDisplay?: "auto" | "list" | "chips";
+    /** Shown in the panel's quiet style while it has no rows (`"This story has no controls"`). */
+    readonly empty?: string;
     readonly history?: boolean;
     readonly footer?: boolean;
     readonly actions?: readonly ControlAction<any>[];
@@ -348,6 +369,14 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
     /** An undo stack the host owns; undo and redo call it (see `HostHistory`). */
     history?: HostHistory;
     presets?: Readonly<Record<string, Partial<Values<S>>>>;
+    /**
+     * Presets that belong to one tab or group, keyed by its id: `{ Sidebars: { snappy: {…} } }`.
+     * Each shows its own strip on that tab (a tab without any shows none), moves only that tab's
+     * or group's keys, and has its own active preset, modified mark and saved variants. A variants
+     * choice on a tab adds its options to that tab's. `presets` then covers only the keys no scope
+     * holds; leave it out and only the scoped strips show.
+     */
+    scopedPresets?: Readonly<Record<string, Readonly<Record<string, Partial<Values<S>>>>>>;
     /**
      * Groups pinned to the top of a panel, under the header and above the tab strip, on every tab
      * (as fields' `pinned: true` pins theirs). Presets and saved variants leave them alone: applying
@@ -401,6 +430,10 @@ export interface Controls<S extends Schema = Schema> {
     readonly persist: PersistMode;
     readonly presets: Readonly<Record<string, Values<S>>>;
     readonly variants: Variants<Values<S>>;
+    /** The tabs and groups with presets of their own, by id (see `ControlsOptions.scopedPresets`). */
+    readonly scopes: Readonly<Record<string, PresetScope<Values<S>>>>;
+    /** The scope `key`'s presets come from: a tab or group's id, `""` for `presets`, or undefined when pinned. */
+    scopeOf(key: string): string | undefined;
     readonly actions: readonly ControlAction<Values<S>>[];
     /** Its panels' theme, as given (see `ControlsOptions.theme`). */
     readonly theme: Theme | ThemeMode | undefined;
@@ -430,8 +463,8 @@ export interface Controls<S extends Schema = Schema> {
     readonly groupFolded: Readonly<Record<string, boolean>> | undefined;
     /** How a page's sections start (`sectionFolded`), as given. */
     readonly sectionFolded: SectionFolded | undefined;
-    /** A preset's display label (`presetLabels`, `defaultLabel`), else its id. */
-    presetLabel(id: string): string;
+    /** A preset's display label (`presetLabels`, `defaultLabel`), else its id; `scope` as in `preset`. */
+    presetLabel(id: string, scope?: string): string;
     /** Whether `key` is pinned (its group is, see `ControlsOptions.pinned`), outside the presets. */
     isPinned(key: string): boolean;
     readonly error: string | null;
@@ -548,17 +581,21 @@ export interface Controls<S extends Schema = Schema> {
     readonly comparing: boolean;
     /**
      * Applies a preset and makes it the active one (`"default"` clears it); one undo step, or
-     * folded into the last with `coalesce` (a pan across the strip).
+     * folded into the last with `coalesce` (a pan across the strip). With `scope`, one of that tab
+     * or group's presets, which moves only its keys.
      */
     preset(id: string, options?: {
         coalesce?: boolean;
+        scope?: string;
     }): void;
-    matchingPreset(): string;
+    /** The preset the current values match (in `scope`, over its keys), else `"custom"`. */
+    matchingPreset(scope?: string): string;
     /**
      * The preset (or saved variant) last applied, which Reset returns to and Random explores
-     * around, or null. Kept with the values; forgotten by a reset to the defaults.
+     * around, or null. Kept with the values; forgotten by a reset to the defaults. With `scope`,
+     * that tab or group's.
      */
-    activePreset(): PresetRef | null;
+    activePreset(scope?: string): PresetRef | null;
     /** The group preset last applied to `group` (0-based), or -1. */
     activeGroupPreset(group: string): number;
     /** The values Reset returns to first: the active presets over the defaults. */

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

@@ -22,4 +22,6 @@ export interface Variants<V> {
     export(): string;
     import(json: string): void;
 }
-export declare function createVariants<S extends Schema>(schema: () => S, id: string, key: string, storage: () => StoragePort | null, get: () => Values<S>, set: (v: Values<S>, id: string, coalesce: boolean) => void, notify: () => void, enabled: () => boolean): Variants<Values<S>>;
+export declare function createVariants<S extends Schema>(schema: () => S, id: string, key: string, storage: () => StoragePort | null, get: () => Values<S>, set: (v: Values<S>, id: string, coalesce: boolean) => void, notify: () => void, enabled: () => boolean, 
+/** What the list starts as while storage holds none yet (it's kept once something's saved). */
+seed?: () => readonly Variant<Values<S>>[]): Variants<Values<S>>;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, actionShortcut, watch, sparkline, graph, meter, table, log, hasValue, isReadout, wrapAngle, SPRING, type FieldMeta, type ActionField, type SpringPart, type ValueField, type Knob, type Choice, type Toggle, type SpringField, type ColorField, type PointField, type EasingField, type VecField, type Vec3, type RangeField, type AngleField, type SeedField, type KeybindField, type GradientField, type CurveField, type ToolbarField, type ToolbarItem, type ToolbarShortcut, type WatchField, type SparklineField, type GraphField, type GraphSeries, type GraphThreshold, type MeterField, type TableField, type LogField, type ReadoutField, type ReadoutKeys, type ReadoutInput, type Point, type Field, type Schema, type Values, type Value, type State, } from "./core/schema.js";
+export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, text, gradient, curve, toolbar, toolbarShortcut, actionShortcut, watch, sparkline, graph, meter, table, log, hasValue, isReadout, wrapAngle, SPRING, type FieldMeta, type ActionField, type SpringPart, type ValueField, type Knob, type Choice, type Toggle, type SpringField, type ColorField, type PointField, type EasingField, type VecField, type Vec3, type RangeField, type AngleField, type SeedField, type KeybindField, type TextField, type GradientField, type CurveField, type ToolbarField, type ToolbarItem, type ToolbarShortcut, type WatchField, type SparklineField, type GraphField, type GraphSeries, type GraphThreshold, type MeterField, type TableField, type LogField, type ReadoutField, type ReadoutKeys, type ReadoutInput, type Point, type Field, type Schema, type Values, type Value, type State, } from "./core/schema.js";
 export { springCss, springMotion, type SpringValue } from "./core/spring.js";
 export { reducedSpring, SPRINGS, type SpringName } from "./core/motion.js";
 export { colorHex, parseColor, type Oklch } from "./core/color.js";

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

@@ -0,0 +1,9 @@
+/**
+ * The header of the knobs/ui split pane `host` sits in, when the pane has one (a title) and no
+ * panel's buttons have joined it yet. A panel there with no title of its own puts its buttons in
+ * it (after the pane's actions, before its collapse button) rather than drawing a header row
+ * that would hold only them: one header per surface.
+ */
+export declare function paneHeadOf(host: HTMLElement): HTMLElement | undefined;
+/** Moves `actions` into the pane header `head`; the returned function takes them back out. */
+export declare function dock(actions: HTMLElement, head: HTMLElement): () => void;

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

@@ -333,6 +333,16 @@ export interface GpuKeybindRow {
     readonly wave: RowWave;
     isModified(): boolean;
 }
+/** A text row: the canvas draws its label; the field itself is the DOM's, above the canvas. */
+export interface GpuTextRow {
+    readonly kind: "text";
+    readonly key: string;
+    readonly display: string;
+    readonly row: HTMLElement;
+    readonly labelEl: HTMLElement;
+    readonly wave: RowWave;
+    isModified(): boolean;
+}
 export interface GpuToolbarRow {
     readonly kind: "toolbar";
     readonly key: string;
@@ -370,7 +380,7 @@ export interface GpuSubheadRow {
     readonly wave: RowWave;
     isModified(): boolean;
 }
-export type GpuRowBinding = GpuReadoutRow | GpuVecRow | GpuRangeRow | GpuAngleRow | GpuSeedRow | GpuKeybindRow | GpuToolbarRow | GpuSubheadRow | GpuActionRow | GpuKnobRow | GpuChoiceRow | GpuToggleRow | GpuSpringRow | GpuColorRow | GpuPointRow | GpuEasingRow | GpuGradientRow | GpuCurveRow;
+export type GpuRowBinding = GpuReadoutRow | GpuVecRow | GpuRangeRow | GpuAngleRow | GpuSeedRow | GpuKeybindRow | GpuTextRow | GpuToolbarRow | GpuSubheadRow | GpuActionRow | GpuKnobRow | GpuChoiceRow | GpuToggleRow | GpuSpringRow | GpuColorRow | GpuPointRow | GpuEasingRow | GpuGradientRow | GpuCurveRow;
 export interface GpuGroupBinding {
     readonly element: HTMLElement;
     readonly labelEl: HTMLElement;

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

@@ -1,4 +1,4 @@
-import { toolbarShortcut, type AngleField, type KeybindField, type Point, type RangeField, type SeedField, type ToolbarField, type ToolbarItem, type Vec3, type VecField } from "../core/schema.js";
+import { toolbarShortcut, type AngleField, type KeybindField, type Point, type TextField, type RangeField, type SeedField, type ToolbarField, type ToolbarItem, type Vec3, type VecField } from "../core/schema.js";
 import { type EditorRow, type RowContext } from "./editors.js";
 type Vec = Point & {
     readonly z?: number;
@@ -30,6 +30,12 @@ export declare function keyCap(o: {
     wake(): void;
 }): KeyCap;
 export declare function keybindRow(c: RowContext<KeybindField>): EditorRow;
+/**
+ * Words in a field: one line beside the label, or (`multiline`) a box under it that grows with
+ * its lines. Each keystroke sets the value; one focus's typing is one undo step. Enter (⌘Enter in
+ * a box) or Esc lets go of it.
+ */
+export declare function textRow(c: RowContext<TextField>): EditorRow;
 export interface ToolbarRow extends EditorRow {
     readonly field: ToolbarField;
     /** The item a keydown presses, if any (`global` says whether it's a page-wide shortcut). */
@@ -42,8 +48,10 @@ export interface ToolbarRow extends EditorRow {
 type Shortcut = ReturnType<typeof toolbarShortcut>;
 /**
  * A toolbar: its buttons in equal columns, as many as fit and balanced across the rows (see
- * `toolbarColumns`), each with its icon and label at the start and its shortcut at the end.
- * `keyOf` is each item's shortcut as it is now (the store's rebinding, else its own).
+ * `toolbarColumns`), each with its icon and label at the start and its shortcut at the end. When
+ * every button has an icon and the labels don't fit on one row (or `labels: false`), it's one row
+ * of icons, each label and shortcut in its tooltip. `keyOf` is each item's shortcut as it is now
+ * (the store's rebinding, else its own).
  */
 export declare function toolbarRow(c: RowContext<ToolbarField>, press: (item: ToolbarItem) => void, keyOf?: (item: ToolbarItem) => Shortcut): ToolbarRow;
 /** The value a vector shows, as `{ x, y }` or `{ x, y, z }`. */

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

@@ -19,8 +19,11 @@ export interface ActivePresetState {
 }
 /** 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;
+/**
+ * The strip's id for the store's active preset (`p:` a preset, `v:` a saved variant), if any;
+ * `scope` as in `Controls.preset`.
+ */
+export declare function activeEntryId(controls: Controls<any>, scope?: string): string | null;
 /**
  * Resolves which preset or variant is currently active.
  * The store's active preset (`baseId`) holds the selection however far the values drift from it.
@@ -28,9 +31,19 @@ export declare function activeEntryId(controls: Controls<any>): string | null;
  * 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, baseId?: string | null): ActivePresetState;
+/**
+ * How many lines `count` chips take in `avail` px, at least `min` px each with `gap` between (as
+ * the strip's auto-fit grid lays them); 1 before there's room to measure.
+ */
+export declare function presetLines(count: number, min: number, avail: number, gap: number): number;
 /** Whether any entry but the defaults gives one of `keys` a value other than its default. */
 export declare function presetsTouch(entries: readonly PresetEntry<any>[], keys: readonly string[], defaults: Readonly<Record<string, unknown>>): boolean;
 export declare function nextPresetIndex(count: number, activeIndex: number, direction: number): number;
+/**
+ * How the strip lays out its presets: `"chips"` in a tray of equal columns, `"list"` as rows like a
+ * menu's, or `"auto"` (the default): chips while they fit on two lines, else the list.
+ */
+export type PresetDisplay = "auto" | "list" | "chips";
 export interface PresetStrip {
     readonly element: HTMLElement;
     readonly track: HTMLElement;
@@ -45,6 +58,10 @@ export interface PresetStrip {
     getButtons(): readonly HTMLButtonElement[];
     getActiveState(): ActivePresetState;
     cycle(direction: -1 | 1): void;
+    /** Applies the nth chip (0-based), as a click on it does. */
+    select(index: number): void;
+    /** Lays the presets out as chips or a list (see `PresetDisplay`). */
+    display(mode: PresetDisplay): void;
     selectById(id: string): void;
     /** Saves the current values as "Variant N" and opens its name to typing; returns a status message. */
     save(): string;
@@ -61,6 +78,11 @@ export interface PresetStrip {
 }
 export declare function createPresetStrip<S extends Schema>(doc: Document, controls: Controls<S>, showVariants: boolean, run: (action: () => unknown) => void, onAfterChange?: () => void, 
 /** What a preset's chip says (its id stays its identity); `controls.presetLabel` by default. */
-presetLabel?: (id: string) => string, 
+presetLabel?: (id: string, scope: string) => string, 
 /** Whether these entries matter where the strip is shown (a tab they don't touch hides it). */
-relevant?: (entries: readonly PresetEntry<any>[]) => boolean): PresetStrip;
+relevant?: (entries: readonly PresetEntry<any>[]) => boolean, 
+/**
+ * Whose presets it shows: a tab or group's (see `ControlsOptions.scopedPresets`), `""` for the
+ * panel's own, or null for none (the strip hides).
+ */
+scopeOf?: () => string | null): PresetStrip;

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

@@ -28,11 +28,12 @@ export declare function crumbTrail(path: {
  */
 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.
+ * How much of a trail fits `room` px: crumbs from `from` on show, the ones before it dropped, and
+ * the Esc hint shows only when it fits too. Without room for the deepest crumb, none show
+ * (`from` is the trail's length): the line never runs past the title's room into the buttons.
+ * `widths` are the crumbs' own; `sep` a separator's (with its gaps).
  */
-export declare function fitCrumbs(widths: readonly number[], room: number, sep: number, more: number, hint?: number): {
+export declare function fitCrumbs(widths: readonly number[], room: number, sep: number, hint?: number): {
     from: number;
     hint: boolean;
 };
@@ -41,6 +42,16 @@ export declare function fitCrumbs(widths: readonly number[], room: number, sep:
  * the first nine, as they read.
  */
 export declare function digitOption(key: string, count: number): number | undefined;
+/**
+ * Where a digit goes in a panel: a focused row's options take 1–9 (even past the last), a number
+ * row and a page card's numbered presets keep theirs, and anywhere else 1–9 pick the preset
+ * strip's chips (the design's variants) while the strip has that many. Undefined leaves the key.
+ */
+export declare function digitRoute(key: string, at: {
+    options: boolean;
+    keeps: boolean;
+    presets: number;
+}): "options" | "presets" | 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").

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

@@ -0,0 +1 @@
+export declare const canvasCss = "\n.knobs-ui.knobs-canvas{--_kc-radius:var(--k-ui-canvas-radius,var(--_k-radius-panel));--_kc-fade:var(--k-ui-canvas-fade,16px);\n  position:relative;width:100%;height:100%;overflow:hidden;outline:none;background:var(--k-ui-canvas-bg,var(--_k-bg-page));contain:strict;\n  touch-action:none;overscroll-behavior:none;user-select:none;-webkit-user-select:none;cursor:default;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-canvas-stage,.knobs-canvas-stage *,.knobs-canvas-zoom,.knobs-canvas-zoom *){box-sizing:border-box}\n/* No hard edges: what slides out of view fades over the last few px. */\n.knobs-canvas-stage{position:absolute;inset:0;overflow:hidden;\n  -webkit-mask-image:linear-gradient(to right,transparent,#000 var(--_kc-fade),#000 calc(100% - var(--_kc-fade)),transparent),linear-gradient(to bottom,transparent,#000 var(--_kc-fade),#000 calc(100% - var(--_kc-fade)),transparent);\n  -webkit-mask-composite:source-in;mask-image:linear-gradient(to right,transparent,#000 var(--_kc-fade),#000 calc(100% - var(--_kc-fade)),transparent),linear-gradient(to bottom,transparent,#000 var(--_kc-fade),#000 calc(100% - var(--_kc-fade)),transparent);mask-composite:intersect}\n.knobs-canvas-dots{position:absolute;left:-128px;top:-128px;right:-128px;bottom:-128px;pointer-events:none;will-change:transform;\n  background-image:radial-gradient(circle,var(--k-ui-canvas-dot,color-mix(in srgb,var(--_k-fg) 22%,transparent)) 1px,transparent 1.25px)}\n.knobs-canvas-world{position:absolute;left:0;top:0;width:0;height:0;transform-origin:0 0}\n.knobs-canvas[data-moving] .knobs-canvas-world{will-change:transform}\n.knobs-canvas:is([data-panning],[data-space]) .knobs-canvas-world{pointer-events:none}\n.knobs-canvas[data-space]{cursor:grab}\n.knobs-canvas[data-grabbing]{cursor:grabbing}\n.knobs-canvas-tile{position:absolute;left:0;top:0;display:flex;flex-direction:column;width:max-content;transform-origin:50% 50%}\n.knobs-canvas-title{flex:none;contain:inline-size;height:24px;padding:0 2px 8px;overflow:hidden;white-space:nowrap;color:var(--_k-fg-2);\n  font-size:var(--_k-type-small,12px);line-height:16px;-webkit-mask-image:linear-gradient(to right,#000 calc(100% - 16px),transparent);mask-image:linear-gradient(to right,#000 calc(100% - 16px),transparent)}\n.knobs-canvas-card{position:relative;flex:none;padding:var(--k-ui-canvas-pad,16px);border-radius:var(--_kc-radius);background:var(--k-ui-canvas-card,var(--_k-bg));\n  overflow:hidden;user-select:text;-webkit-user-select:text}\n.knobs-canvas-card::after{content:\"\";position:absolute;inset:0;border-radius:inherit;box-shadow:inset 0 0 0 1px var(--_k-border);pointer-events:none}\n/* The readout: how far, and the way back to the whole set or 100%. */\n.knobs-canvas-zoom{position:absolute;right:10px;bottom:10px;z-index:1;display:flex;align-items:center;gap:2px;height:28px;padding:0 4px;border-radius:999px;\n  background:var(--_k-bg);box-shadow:inset 0 0 0 1px var(--_k-border);color:var(--_k-fg-2);font-size:var(--_k-type-small,12px);\n  font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";white-space:nowrap}\n:where(.knobs-ui) .knobs-canvas-btn{all:revert;box-sizing:border-box;font:inherit;letter-spacing:inherit;margin:0;border:0;outline:none;box-shadow:none;\n  display:inline-flex;align-items:center;justify-content:center;height:20px;min-width:20px;padding:0 6px;border-radius:999px;background:transparent;color:inherit;cursor:default;\n  transition:background calc(var(--_k-hover-out) * 1ms),color calc(var(--_k-hover-out) * 1ms)}\n:where(.knobs-ui) .knobs-canvas-btn:is(:hover,:focus-visible){background:var(--_k-fill-hover);color:var(--_k-fg);transition-duration:0ms}\n:where(.knobs-ui) .knobs-canvas-btn:focus-visible{box-shadow:0 0 0 1.5px var(--_k-accent)}\n.knobs-canvas-pct{min-width:46px}\n.knobs-canvas-btn svg{width:13px;height:13px}\n";