@kitlangton/knobs 0.4.0-next.10 → 0.4.0-next.12

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>>;
+    /** 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`). */
     readonly groupPresets?: Readonly<Record<string, readonly GroupPreset[]>>;
     /** Display labels by group id, section id and preset id (see `ControlsOptions.groupLabels`). */

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

@@ -50,6 +50,12 @@ export interface FieldMeta {
      * Fields without a tab show on every tab.
      */
     readonly tab?: string;
+    /**
+     * Pins the field's group to the top of a panel, under the header and above the tab strip, on
+     * every tab (the first field of a group that says wins; a field without a group pins itself).
+     * Panel presets and saved variants leave pinned fields alone. See `ControlsOptions.pinned`.
+     */
+    readonly pinned?: boolean;
     /**
      * 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.
@@ -57,7 +63,7 @@ export interface FieldMeta {
     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"];
+export declare const META_KEYS: readonly ["label", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "pinned", "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. */
@@ -95,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";
@@ -209,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
@@ -239,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). */
@@ -329,7 +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>>;
-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 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 | 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;
@@ -360,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
@@ -449,6 +493,7 @@ export declare function range(value: readonly [number, number], options: FieldMe
     folded?: boolean;
     sectionFolded?: boolean;
     tab?: string;
+    pinned?: boolean;
     subsection?: string;
 };
 /** Degrees on a dial (0–360 and wrapping by default): `angle(45)`, `angle(30, { min: -90, max: 90 })`. */
@@ -465,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`
@@ -503,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

@@ -243,6 +243,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 +355,12 @@ 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>>>>;
+    /**
+     * 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
+     * one keeps their values, saving one keeps them out, and they're modified against their defaults.
+     */
+    pinned?: readonly string[];
     /**
      * Numbered presets per group, shown as 1, 2, 3… on the group's card in a page. A group's
      * presets cover every key any of them names; keys a preset leaves out are at their defaults,
@@ -426,6 +439,8 @@ export interface Controls<S extends Schema = Schema> {
     readonly sectionFolded: SectionFolded | undefined;
     /** A preset's display label (`presetLabels`, `defaultLabel`), else its id. */
     presetLabel(id: string): string;
+    /** Whether `key` is pinned (its group is, see `ControlsOptions.pinned`), outside the presets. */
+    isPinned(key: string): boolean;
     readonly error: string | null;
     get(): Values<S>;
     getServerSnapshot(): 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;
@@ -407,6 +417,8 @@ export interface GpuPanelBinding {
     readonly id: string;
     readonly root: HTMLElement;
     readonly body: HTMLElement;
+    /** The pinned groups' cards, above the tab strip (empty while none are pinned). */
+    readonly pinned?: HTMLElement;
     readonly inline: boolean;
     readonly header: HTMLElement;
     readonly titleEl: 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

@@ -28,7 +28,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;
@@ -43,6 +55,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;
@@ -52,9 +68,13 @@ export interface PresetStrip {
     readonly nameField: () => HTMLInputElement | null;
     /** Deletes the selected chip when it's a saved variant; returns a status message. */
     deleteActive(): string | undefined;
+    /** Whether the strip should show: presets to pick (or saving on) that touch what's shown. */
+    shows(): boolean;
     update(): void;
     dispose(): void;
 }
 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): PresetStrip;
+presetLabel?: (id: 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;

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";

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

@@ -0,0 +1,116 @@
+/** The camera: a world point `p` is drawn at `p * scale + (x, y)` in the canvas's own px. */
+export interface CanvasView {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+}
+export interface CanvasRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface CanvasPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+/**
+ * Tiles in rows, in order: each row takes tiles until the next would pass `width`, rows sit `gap`
+ * apart and tiles top-align in them. Rects land on whole px, so at 100% they're on the pixel grid.
+ */
+export declare function packRows(sizes: readonly {
+    readonly w: number;
+    readonly h: number;
+}[], opts: {
+    readonly gap: number;
+    readonly width: number;
+    readonly x?: number;
+    readonly y?: number;
+}): CanvasRect[];
+/**
+ * How wide rows run so the packed set comes out about `aspect` (width / height): a bisection
+ * between the widest tile and one long row, on how the packing actually comes out.
+ */
+export declare function rowWidth(sizes: readonly {
+    readonly w: number;
+    readonly h: number;
+}[], gap: number, aspect: number): number;
+/**
+ * Where every item goes: one with an `x` and `y` stays there; the rest pack in rows (`packRows`),
+ * under the placed ones if there are any.
+ */
+export declare function layoutCanvas(items: readonly {
+    readonly x?: number;
+    readonly y?: number;
+    readonly w: number;
+    readonly h: number;
+}[], opts: {
+    readonly gap: number;
+    readonly width?: number;
+    readonly aspect?: number;
+}): {
+    rects: CanvasRect[];
+    width: number;
+};
+/** The rect around `rects`, or null for none. */
+export declare function boundsOf(rects: readonly CanvasRect[]): CanvasRect | null;
+/** Screen (canvas px) to world, and back. */
+export declare const toWorld: (v: CanvasView, p: CanvasPoint) => CanvasPoint;
+export declare const toScreen: (v: CanvasView, p: CanvasPoint) => CanvasPoint;
+/** The view at `scale` (clamped to `min`…`max`), with the world point under `at` still under it. */
+export declare function zoomAround(v: CanvasView, scale: number, at: CanvasPoint, min?: number, max?: number): CanvasView;
+/**
+ * Two fingers moved: the world point under their old midpoint `from` lands under the new one
+ * `to`, with the zoom times `ratio` (zoom around `from`, then follow the midpoint).
+ */
+export declare function pinchView(v: CanvasView, from: CanvasPoint, to: CanvasPoint, ratio: number, min?: number, max?: number): CanvasView;
+/** The most one wheel event zooms (a mouse wheel's notch under ⌘ or ctrl). */
+export declare const WHEEL_ZOOM_MAX = 1.25;
+/**
+ * One ⌘/ctrl-wheel event's zoom factor, applied directly: a trackpad pinch (ctrl) at 1% per px,
+ * ⌘-scroll at .25%, and never more than `WHEEL_ZOOM_MAX` either way per event, so a mouse
+ * wheel's big notches step evenly without springing.
+ */
+export declare function wheelZoom(deltaY: number, pinch: boolean): number;
+/** The view that shows `r` whole and centred in a `w` × `h` canvas, `pad` px in from its edges. */
+export declare function fitView(r: CanvasRect, w: number, h: number, opts?: {
+    readonly pad?: number;
+    readonly min?: number;
+    readonly max?: number;
+}): CanvasView;
+/**
+ * A path between two views, `t` 0 → 1. It zooms around the one canvas point both views agree on,
+ * at an even rate in log scale, so every point on screen travels one straight line in one
+ * direction (no curve from springing x, y and scale apart). Views at the same scale pan straight.
+ */
+export declare function viewPath(from: CanvasView, to: CanvasView): (t: number) => CanvasView;
+/** The translate on the device-pixel grid, so a resting view draws crisp. */
+export declare const snapView: (v: CanvasView, dpr: number) => CanvasView;
+/**
+ * The background's dots: `step` world px apart, drawn `size` canvas px apart, and how strongly
+ * (0…1): they fade out as they crowd together zooming out and as they spread apart zooming in.
+ */
+export declare function dotGrid(scale: number, step?: number): {
+    size: number;
+    alpha: number;
+};
+/** What a key does to the view: 0 fits, 1 is 100%, = and - zoom in and out. */
+export type CanvasKey = "fit" | "actual" | "in" | "out";
+export declare function keyAction(e: {
+    readonly key: string;
+    readonly altKey?: boolean;
+}): CanvasKey | null;
+/** How far each zoom key steps. */
+export declare const KEY_ZOOM = 1.5;
+/**
+ * The hand's velocity at release (px/s) from recent samples `{ x, y, t (ms) }`: the travel over
+ * the last `window` ms. Zero if the hand had already stopped.
+ */
+export declare function releaseVelocity(samples: readonly {
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+}[], now: number, window?: number): CanvasPoint;
+/** Momentum's time constant (s): the coast slows as iOS's scroll does (0.998 per ms). */
+export declare const COAST_TAU: number;