@kitlangton/knobs 0.1.0 → 0.3.0

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

@@ -0,0 +1,103 @@
+/**
+ * Where each halving of the rate happens (px off the row: from, to). ×1 within 24 px, ×½ around
+ * 60, ×¼ around 110, ×⅛ beyond 146.
+ */
+export declare const PRECISION: readonly (readonly [number, number])[];
+/** How far (px) a pointer at `y` is off a row spanning `top`..`bottom` (0 on it). */
+export declare const offRow: (y: number, top: number, bottom: number) => number;
+/** How many halvings a drag `off` px from its row moves at: 0 near it, up to 3, smoothly. */
+export declare const precisionDepth: (off: number) => number;
+/** The rate (value per px of the hand, relative to 1:1) a drag `off` px from its row moves at. */
+export declare const precisionRate: (off: number) => number;
+/** The ruler's levels: intervals across the track, tick height (px) and the accent's alpha. */
+export declare const RULER: readonly (readonly [number, number, number])[];
+/** The ruler shows in full within `RULER_NEAR` px of the handle, fading out by `RULER_FADE`. */
+export declare const RULER_NEAR = 36;
+export declare const RULER_FADE = 120;
+/** The ruler's finest level a slider of `steps` steps shows (each halves the last, from tenths). */
+export declare const rulerLevels: (steps: number) => number;
+/** How much of ruler level `level` (1–3) shows at `depth` halvings. */
+export declare const rulerAlpha: (depth: number, level: number) => number;
+/** The depth a ruler shows for a drag at `rate` (with ⌥'s tenth folded in), at most `levels`. */
+export declare const rulerDepth: (rate: number, levels: number) => number;
+/** How much a stretched control thins per unit of strain (a row ~300 px long, 14 px over: ~.92). */
+export declare const THIN = 1.7;
+/** The thinnest a stretched control gets. */
+export declare const THINNEST = 0.85;
+/** How thin a control stretched to `scale` times its length draws, across it. */
+export declare const thinOf: (scale: number) => number;
+/** Over how many px of give a control's stretching corners round off fully. */
+export declare const ROUND_IN = 4;
+/** How far (0–1) the corners at a stretching end have rounded off. */
+export declare const roundOf: (give: number) => number;
+/**
+ * A box `length` px long, stretched `give` px past one end (positive: past its far end, negative:
+ * past its start): its scale along it, about the end that stays put (0 its start, 1 its far end).
+ */
+export declare const stretchOf: (give: number, length: number) => {
+    scale: number;
+    anchor: number;
+};
+/**
+ * Where a point `at` px along a box `length` long draws while it's stretched `give` px: points near
+ * the anchored end barely move, the stretching end moves by the whole give.
+ */
+export declare const stretchAt: (at: number, give: number, length: number) => number;
+/**
+ * The most a control gives where it has `room` px before something clips it: `most`, or less so
+ * it never draws cut off (and a hair at least, so meeting the limit still ticks).
+ */
+export declare const giveRoom: (room: number, most: number) => number;
+export type DetentKind = "default" | "base" | "round";
+/** A detent's hold (px either side where the value sticks) and the ramp past it (px). */
+export declare const DETENTS: Readonly<Record<DetentKind, {
+    readonly hold: number;
+    readonly ramp: number;
+}>>;
+/** How strong detents are at a drag's rate: full at 1:1, weaker faster than the rate slows. */
+export declare const detentScale: (rate: number) => number;
+export interface Detent {
+    /** Where it sits along the track (px). */
+    readonly at: number;
+    /** The value it holds. */
+    readonly value: number;
+    readonly kind: DetentKind;
+}
+/**
+ * The detents of a track `width` px wide: its default first, then the active preset's value,
+ * then the round values given, each dropped where it would crowd one before it.
+ */
+export declare function detentsOf(width: number, min: number, max: number, o: {
+    readonly value: number;
+    readonly base?: number;
+    readonly round?: readonly number[];
+}): Detent[];
+/** A range's round values worth a detent: its middle, and zero when it lies inside. */
+export declare const roundValues: (min: number, max: number) => number[];
+/**
+ * Where the value shows for a hand at `x` (px): on a detent within its hold, catching up a little
+ * faster than the hand just past it, and the hand's own position beyond. `k` scales the detents.
+ */
+export declare function warp(x: number, list: readonly Detent[], k?: number): number;
+/**
+ * The hand position that shows `shown` with detents at strength `k` (`warp`'s inverse); on a
+ * detent, the one nearest `x`. Re-anchoring here when the strength changes keeps the value still.
+ */
+export declare function unwarp(shown: number, x: number, list: readonly Detent[], k?: number): number;
+/**
+ * A drag's detents: where the value shows, which detent holds it, and the moment one catches (to
+ * tick once). Once caught, a detent catches again only after the hand has left its reach, so a
+ * hand resting on its edge doesn't chatter.
+ */
+export declare class Notches {
+    readonly list: readonly Detent[];
+    /** The detent holding the value, or -1. */
+    held: number;
+    private readonly armed;
+    constructor(list: readonly Detent[], x: number);
+    /** The shown position for a hand at `x` with detents at strength `k`, and any detent caught now. */
+    move(x: number, k?: number): {
+        shown: number;
+        caught?: Detent;
+    };
+}

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

@@ -0,0 +1,13 @@
+/**
+ * A button's press flash: its wash brightens at once and eases out, so a command fired from a key
+ * shows on the button it belongs to (Undo, Redo, Reset, Copy, Random, a group's die and reset).
+ * The DOM runs it as a CSS animation (`data-k-flash`, see the styles); the GPU renderer draws the
+ * same curve from `flashOf`.
+ */
+export declare const FLASH_MS = 320;
+export declare function flash(button: HTMLElement | undefined, wake?: () => void): void;
+/**
+ * How much of `button`'s flash is left at `now` (1 to 0): ease-out cubic, as the DOM's
+ * `cubic-bezier(.33,1,.68,1)` from the flash back to the button's own wash.
+ */
+export declare function flashOf(button: Element, now: number): number;

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

@@ -1,5 +1,10 @@
 /** The most a control gives past an end (px). */
 export declare const GIVE = 6;
+/** The most a slider's row stretches past an end (px), dragged or panned alike. */
+export declare const STRETCH = 14;
+/** How long (s) a give takes to spring home, with no bounce: a readout's, and a stretch's. */
+export declare const HOME_S = 0.25;
+export declare const STRETCH_HOME_S = 0.35;
 /** The give `over` px of push past an end makes: 1:1 at first, never reaching `max`. */
 export declare const rubber: (over: number, max?: number) => number;
 /** The push (px) that makes `give` (`rubber`'s inverse). */
@@ -62,7 +67,12 @@ export declare const giveOf: (el: Element) => number;
  * pan puts it; let go, it springs home on one loop that both renderers read: the DOM as a
  * `translate`, the GPU through `giveOf`.
  */
-export declare function textGive(el: HTMLElement | SVGElement, wake: () => void): {
+export declare function textGive(el: HTMLElement | SVGElement, wake: () => void, o?: {
+    /** Seconds to spring home (`HOME_S` by default). */
+    readonly home?: number;
+    /** Draws the give in the DOM (a `translate` by default; not called while the GPU draws). */
+    readonly draw?: (px: number) => void;
+}): {
     /** The give as last held (0 once let go). */
     readonly give: number;
     /** Holds the give at `px` (signed), ticking as it starts. */
@@ -71,3 +81,26 @@ export declare function textGive(el: HTMLElement | SVGElement, wake: () => void)
     release(): void;
 };
 export type TextGive = ReturnType<typeof textGive>;
+/**
+ * Draws `el` stretched like rubber, `x` px past an end along it (and `y` px down or up, for a pad):
+ * scaled about the end that stays put, thinner across it as it lengthens (`thin`), its stretching
+ * corners rounding off. CSS reads the vars (.knobs-stretching); `unclip` is a parent whose clip it
+ * may draw past meanwhile (its card).
+ */
+export declare function drawStretch(el: HTMLElement, x: number, y: number, size: {
+    readonly w: number;
+    readonly h: number;
+}, o?: {
+    readonly thin?: boolean;
+    readonly unclip?: Element | null;
+}): void;
+/**
+ * How far (px) `el` can stretch each way before an ancestor clips it (its overflow isn't
+ * visible), passing over `skip` (a card it unclips while it stretches).
+ */
+export declare function roomOf(el: Element, skip?: Element | null): {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};

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

@@ -1,7 +1,5 @@
-export type Rgba = readonly [number, number, number, number];
-export declare function parseCssColor(raw: string, fallback?: Rgba): Rgba;
-export declare function withAlpha(c: Rgba, alphaFactor: number): Rgba;
-export declare function mixColor(a: Rgba, b: Rgba, t: number): Rgba;
+import { mixRgba as mixColor, parseCssColor, type Rgba, withAlpha } from "../../ui/rgba.js";
+export { mixColor, parseCssColor, type Rgba, withAlpha };
 /** CSS `color-mix(in srgb, a p, b)`, interpolated with premultiplied alpha like the browser. */
 export declare function cssMix(a: Rgba, b: Rgba, p: number): Rgba;
 export interface PanelThemeTokens {
@@ -124,5 +122,7 @@ export interface PanelThemeTokens {
     readonly thumb: Rgba;
     /** How strongly small drop shadows show under thumbs and pills (--k-lift). */
     readonly lift: number;
+    /** How dark the panel's drop shadow is (--k-shadow-strength): .48 on dark panels, .16 on light. */
+    readonly shadowStrength: number;
 }
 export declare function readPanelTokens(panel: HTMLElement, version?: number): PanelThemeTokens;

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

@@ -3,7 +3,8 @@ import { type HeaderDie } from "../die.js";
 import { type IconName } from "../icons.js";
 import { Edges } from "../motion.js";
 import type { MorphFrame } from "../morph.js";
-import type { PresetStrip } from "../presets.js";
+import type { LensShape } from "../lens.js";
+import { type PresetStrip } from "../presets.js";
 import type { DigitPlace, Slider } from "../slider.js";
 import type { TabStrip } from "../tabs.js";
 import type { ReadoutView } from "../../ui/readouts.js";
@@ -111,8 +112,11 @@ export interface GpuPointRow {
     readonly x: GpuExpander;
     readonly read: HTMLElement;
     readonly pad: HTMLElement;
+    /** Where the puck and the default sit at rest (px in the pad); a stretch moves them with it. */
     puck(): readonly [number, number];
     home(): readonly [number, number];
+    /** How far (px) the pad stretches past an edge across and down (see drawStretch). */
+    stretch(): readonly [number, number];
     dragging(): boolean;
     readonly wave: RowWave;
     isModified(): boolean;
@@ -130,6 +134,11 @@ export interface GpuEasingRow {
     curve(): readonly number[];
     /** P0, P1, P3, P2: the two arms from the ends to their handles. */
     arms(): readonly number[];
+    /** Steps the row's morph (curve, arms, handles) to this frame; whether it still moves. */
+    advance(now: number): boolean;
+    /** The line's motion blur (px), and each handle's (px across, px down): 0 at rest. */
+    blur(): number;
+    smear(i: number): readonly [number, number];
     /** (0,0) and (1,1) in the box. */
     guides(): readonly number[];
     readonly handles: readonly HTMLElement[];
@@ -148,6 +157,13 @@ export interface GpuRampHandle {
     readonly selected: boolean;
     /** Dragged off the strip or graph: it goes when let go. */
     readonly leaving: boolean;
+    /**
+     * How grown it is (0…1), when its row's morph sizes it: budding out of the line or merging
+     * into a neighbour. Its position is then already the morph's, so it isn't eased again.
+     */
+    readonly grow?: number;
+    /** Its motion blur (px along its travel, across and down), 0, 0 at rest. */
+    readonly smear?: readonly [number, number];
 }
 export interface GpuGradientRow {
     readonly kind: "gradient";
@@ -156,12 +172,15 @@ export interface GpuGradientRow {
     readonly row: HTMLElement;
     readonly x: GpuExpander;
     readonly read: HTMLElement;
-    /** The head's swatch strip, and its stop ticks (x in the strip). */
+    /** The head's swatch strip, and its stop ticks (x in the strip; grown 0…1 as its stop is). */
     readonly mini: HTMLElement;
     ticks(): readonly {
         readonly el: HTMLElement;
         readonly x: number;
+        readonly grow?: number;
     }[];
+    /** Steps the row's morph to this frame (samples, stops and ticks); whether it still moves. */
+    advance(now: number): boolean;
     /** Evenly spaced samples as gamma sRGB triples, flat (see `gradientSamples`). */
     samples(): readonly number[];
     /** The editor's strip and how far in from each end its ramp starts (the handles' radius). */
@@ -192,7 +211,12 @@ export interface GpuCurveRow {
     readonly graph: HTMLElement;
     /** Grid lines as x0, y0, x1, y1 quadruples in the graph. */
     grid(): readonly number[];
+    /** The line and mini curve as the row's morph shows them now (stepped to `now`, ms). */
     curve(): readonly number[];
+    /** Steps the row's morph to this frame; whether it still moves. */
+    advance(now: number): boolean;
+    /** The line's motion blur (px), 0 at rest. */
+    blur(): number;
     handles(): readonly GpuRampHandle[];
     /** The hover crosshair: its x, the curve's y there, and the readout's element. */
     hover(): {
@@ -212,9 +236,17 @@ export interface GpuActionRow {
     readonly display: string;
     readonly row: HTMLElement;
     readonly button: HTMLButtonElement;
+    /** Its shortcut's key cap, at the row's end: a rebindable one listens while `capturing`. */
+    readonly keys?: GpuKeyCap;
     readonly wave: RowWave;
     isModified(): boolean;
 }
+/** A key cap (a keybind's, an action's shortcut): its text, and whether it's listening for keys. */
+export interface GpuKeyCap {
+    readonly chip: HTMLElement;
+    readonly text: HTMLElement;
+    capturing(): boolean;
+}
 /** A vector's number cell: its axis letter and readout (DOM-placed text). */
 export interface GpuCell {
     readonly el: HTMLElement;
@@ -397,6 +429,13 @@ export interface GpuPanelBinding {
     readonly rows: readonly GpuRowBinding[];
     readonly actionButtons: readonly HTMLButtonElement[];
     isPopoverOpen(): boolean;
+    /** The focus lens (lens.ts): its shapes each frame, drawn as the DOM's `.knobs-lens`. */
+    readonly lens?: {
+        frame(now: number): readonly LensShape[];
+        moving(now: number): boolean;
+    };
+    /** The scope line beside the title (crumbs.ts): its spans are drawn where they sit. */
+    readonly crumbs?: HTMLElement;
     /** While the panel grows out of (or into) its chip: the shape at a frame time. */
     readonly morph?: (now: number) => MorphFrame | undefined;
     /** True while rows, cards or group heads arrive or leave (a descriptor swap). */
@@ -517,7 +556,10 @@ declare class GpuOverlayManager {
     private curSubHovered;
     /** Whether the pointer has one of the panel's rows (and keys haven't taken over since). */
     private curPointerRow;
-    private readonly hotRows;
+    /** The panel being drawn marks focus with its lens: the per-level washes step aside. */
+    private curLens;
+    /** Each panel's armed look (--k-armed-*, --k-title-rest), read again when styles change. */
+    private readonly armedLooks;
     private curPanelRect;
     private curPanelScrollTop;
     private curLayoutKey;
@@ -601,11 +643,21 @@ declare class GpuOverlayManager {
      * their hover twins, at --k-button-radius.
      */
     private drawButtonBox;
-    private isHot;
     /** Square inside its card, except the card's own rounded corners on the first and last rows. */
     private rowCorners;
     /** A row's hover wash, drawn beneath its control like the DOM row background. */
     private drawRowHover;
+    /**
+     * A row stretched `give` px past an end, as drawStretch scales it in the DOM: its rect (about
+     * the end that stays put, thinner across), its scale along, its corners rounding off at the
+     * stretching end, and its clip let out to the panel's on that side (past its card).
+     */
+    /**
+     * A box stretched `x` px past an end across and `y` px down or up, about the far ends, and
+     * (`thin`, stretched along x) thinner down, as drawStretch scales it in the DOM.
+     */
+    private stretchRect;
+    private stretch;
     /** The hairline above every row but a card's first, and the focus wash. */
     private drawRowOverlay;
     /** Whether `el` shows its focus wash: one wash at a time, the pointer's row's while it has one. */
@@ -613,6 +665,11 @@ declare class GpuOverlayManager {
     private drawSeparator;
     /** The focus wash, matching the row's corners inside its card. */
     private drawFocus;
+    /**
+     * A header or group button that blooms in and out of its slot (`data-shown`): its opacity, scale
+     * and blur (σ, px) from the DOM's transition while one runs, else simply there or not.
+     */
+    private bloomOf;
     private drawIcon;
     /**
      * Copy, and the check it turns into once copied, from the DOM's transitions while they run
@@ -621,6 +678,18 @@ declare class GpuOverlayManager {
     private drawCopy;
     /** The die is always traced, at rest too, exactly as the DOM canvas does: nothing swaps. */
     private drawDie;
+    /** Panels whose DOM overlays `cutUnderHead` has cut, to restore once nothing is under. */
+    private readonly headCuts;
+    /**
+     * The DOM pieces the GPU leaves above its canvas (a row's accessory, the number being typed,
+     * the search field) are cut at a pinned header's foot (`foot`, viewport y), as the rows are.
+     */
+    private cutUnderHead;
+    /**
+     * A button's press flash (flash.ts) over its wash: the wash brightened toward the text colour,
+     * easing out. Returns `ink` brightened toward the text colour while the flash lasts.
+     */
+    private drawFlash;
     /** A circular icon button's hover/focus wash. */
     private drawRoundWash;
     /**
@@ -648,6 +717,7 @@ declare class GpuOverlayManager {
     /** The current row's selection wash (0…1), which its hover wash gives way to. */
     private curSelected;
     /** A stroke through `pts` (x,y pairs in viewport px), round-capped like SVG's. */
+    /** `blur` (px) softens it across, as a moving line's smear (the DOM's Gaussian over √12). */
     private pushLine;
     /**
      * Eases a list of numbers toward `target` on the fill spring, the way the DOM transitions the
@@ -660,6 +730,32 @@ declare class GpuOverlayManager {
     private shape;
     /** An outline like CSS `outline: 1.5px` at `offset`, following `radius`; drawn while focus-visible. */
     private readout;
+    /** Each name-like readout's text and the one before it, for their crossfade (see `fadeText`). */
+    private readonly fades;
+    /** Text that crossfades from what it said before when its element says `data-fade`, as the DOM's. */
+    private fadeText;
+    /**
+     * A rolling readout (reel.ts), right-aligned where its element ends: each number a wheel per
+     * place, as the slider's readout draws its digits, and the text between them still. Laid out
+     * here from the glyphs' advances (tabular digits), not from the DOM's spans, which may not
+     * have caught up yet.
+     */
+    private drawRolling;
+    private advanceOf;
+    /**
+     * A number's places, right-aligned at `right`: each digit a wheel seen through a feathered
+     * slot (faces 2.1em apart, as the DOM's reel), blurring with speed; punctuation keeps its own
+     * advance, and a place on its way out keeps its last spot. True while any place moves.
+     */
+    private drawPlaces;
+    /** The armed look's tokens for a panel (see the styles' --k-armed-*). */
+    private armedLook;
+    /** The focus lens's shapes (lens.ts), as the DOM's `.knobs-lens`: a wash and a hairline. */
+    private drawLens;
+    /** The scope line's spans (crumbs.ts) where the DOM placed them, at their opacity. */
+    private drawCrumbs;
+    /** The soft wash on the card focus is on (`data-k-scope`), as the DOM's ::after. */
+    private drawScope;
     /** A disclosure head (hover, label and changed dot, caret, focus); returns the body's clip, if open. */
     private drawHead;
     /** A disclosure chevron, turning a quarter on the lead spring as it opens. */
@@ -674,8 +770,6 @@ declare class GpuOverlayManager {
     private drawEasing;
     /** A gradient strip from its samples (see shader kind 13), `inset` in from each end. */
     private pushRamp;
-    /** How far a handle that arrived mid-life has grown in (`data-born`), like the DOM's keyframes. */
-    private appear;
     private drawGradient;
     private drawCurve;
     private readonly lastHover;
@@ -694,6 +788,16 @@ declare class GpuOverlayManager {
     private drawRange;
     private drawAngle;
     private drawKeybind;
+    /** When each listening key cap started, so its breathing starts from full strength. */
+    private readonly capSince;
+    /** Each key cap's text and the one before it, for their crossfade. */
+    private readonly capTexts;
+    /**
+     * A key cap, as the DOM's: its tray's width glides to fit new text (snappy, no bounce) with its
+     * right edge still, while the old text fades out and the new in. Listening, it takes a soft
+     * accent wash and its text breathes; no ring.
+     */
+    private drawKeyCap;
     /** A readout's clip: the card's, narrowed to `el` when given. */
     private clipTo;
     /** Paints a readout's ops (local px from `r`'s corner), clipped to it, as its canvas does. */

package/dist/types/panel/gpu/shader.wgsl.d.ts

@@ -1,2 +1,2 @@
-export declare const FLOATS_PER_PRIM = 40;
+export declare const FLOATS_PER_PRIM = 44;
 export declare const panelWgsl: string;

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

@@ -1,5 +1,9 @@
-/** One light tick for a change made by `from`'s control, unless ticks are off or too close. */
-export declare function tick(from: Element): void;
+import { type SoundCue } from "./sound.js";
+/**
+ * One light tick for a change made by `from`'s control, unless ticks are off or too close. With
+ * `sound`, a panel that plays sounds plays that cue at the same moment (see sound.ts).
+ */
+export declare function tick(from: Element, sound?: SoundCue): void;
 /**
  * Lays a label for the hidden switch over `target` (a positioned button), so a tap on it is the
  * user's own tap on a switch: the only tick iOS 26.5+ plays. Only where Safari's switch exists and

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

@@ -7,7 +7,6 @@
  * - `data-k-fv` on each ancestor of the focused element while it's `:focus-visible`
  *   (`:has(:focus-visible)`); `"track"` when that's a slider track, `"head"` an editor's header.
  * - `data-k-active` on each ancestor of a `.knobs-active` element (`:has(.knobs-active)`).
- * - `data-k-head-hover` on an editor row whose header is hovered (`:has(>.knobs-x-head:hover)`).
  * - `data-k-row-hover` on the root while the pointer is on one of its rows
  *   (`:has(.knobs-card>:hover)`).
  */

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

@@ -1,4 +1,5 @@
-export { attach } from "./attach.js";
+export { attach, status } from "./attach.js";
+export { toggleLayer, type ToggleLayer, type ToggleSurface } from "./toggle.js";
 export { getGpuOverlayManager, resolveRendererMode, type KnobsGpuDiagnostics, } from "./gpu/renderer.js";
 export { computeHintPrefixes, type HintBadgeState, type HintCandidate, type HintResolution, } from "./hints.js";
 export { assignPageCodes, hints, pageHints, type HintPainter, type HintSourceOptions, type PageHints, type PageHintTarget, } from "./page-hints.js";
@@ -6,5 +7,6 @@ export { Spring, VelocityTracker } from "./motion.js";
 export { createPanel, mountPage, mountPanel, type Panel, type PanelSearch } from "./panel.js";
 export { balancedRuns, type FoldSummaryInfo, type MountPageOptions, type Page, type PageAction, type PageCard, type PageCardOptions, type PageControl, type PageFoldOptions, type PageFoldSource, type PageGroupInfo, type PageHighlight, type PageSectionInfo, } from "./page.js";
 export { createPresetStrip, nextPresetIndex, resolveActivePresetEntry, type ActivePresetState, type PresetEntry, type PresetStrip, } from "./presets.js";
+export { sound, type CueDetail, type Sound, type SoundCue, type SoundLayer, type SoundOptions, type SoundTheme, } from "./sound.js";
 export { injectStyles } from "./styles.js";
 export { attachVariantSwitcher, getSwitcherOptions, type ChoiceKey, type SwitcherOptions, } from "./switcher.js";

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

@@ -1,5 +1,5 @@
-import { type AngleField, type KeybindField, type Point, type RangeField, type SeedField, type ToolbarField, type ToolbarItem, type Vec3, type VecField } from "../core/schema.js";
-import type { EditorRow, RowContext } from "./editors.js";
+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 { type EditorRow, type RowContext } from "./editors.js";
 type Vec = Point & {
     readonly z?: number;
 };
@@ -7,6 +7,28 @@ export declare function vecRow(c: RowContext<VecField>): EditorRow;
 export declare function rangeRow(c: RowContext<RangeField>): EditorRow;
 export declare function angleRow(c: RowContext<AngleField>): EditorRow;
 export declare function seedRow(c: RowContext<SeedField>): EditorRow;
+export interface KeyCap {
+    readonly chip: HTMLButtonElement;
+    readonly text: HTMLElement;
+    capturing(): boolean;
+    /** The combination it shows: `""` for none, undefined for mixed ("—"). */
+    show(combo: string | undefined): void;
+}
+/**
+ * A key cap that records a combination: a click, Enter or Space listens, the next combination is
+ * the value, Esc cancels and ⌫ clears. While it listens its row takes the active wash and the cap
+ * breathes, "Type keys…" (or the modifiers held so far) in its place; its width follows its text
+ * on a spring, its right edge still. Keybind rows and rebindable action rows use it.
+ */
+export declare function keyCap(o: {
+    readonly doc: Document;
+    readonly row: HTMLElement;
+    /** What the cap reads with no combination. */
+    readonly empty: string;
+    name(): string;
+    set(combo: string): void;
+    wake(): void;
+}): KeyCap;
 export declare function keybindRow(c: RowContext<KeybindField>): EditorRow;
 export interface ToolbarRow extends EditorRow {
     readonly field: ToolbarField;
@@ -14,7 +36,15 @@ export interface ToolbarRow extends EditorRow {
     match(event: KeyboardEvent, global: boolean): ToolbarItem | undefined;
     press(item: ToolbarItem): void;
     swap(field: ToolbarField): void;
+    /** Shows the shortcuts as they are now (after a rebinding). */
+    refresh(): void;
 }
-export declare function toolbarRow(c: RowContext<ToolbarField>, press: (item: ToolbarItem) => void): ToolbarRow;
+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).
+ */
+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 }`. */
 export type { Vec, Vec3 };

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

@@ -0,0 +1,113 @@
+/** Corner radii: top left, top right, bottom right, bottom left. */
+export type LensCorners = [number, number, number, number];
+/** A box with its corners, in viewport px. */
+export interface LensBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    r: LensCorners;
+}
+export type LensLevel = "editor" | "row" | "card" | "panel";
+/**
+ * One shape to draw: its box, how present it is (0–1), and its wash and edge (shares of
+ * --k-surface-hi and --k-line-hi).
+ */
+export interface LensShape extends LensBox {
+    alpha: number;
+    wash: number;
+    line: number;
+}
+/** The look, from the panel's `--k-lens-*` tokens (see the README). */
+export interface LensTune {
+    /** The morph's duration (ms), a spring with no bounce. */
+    ms: number;
+    /** How much quicker the size settles than the position (1: together). */
+    lead: number;
+    /** The wash: a share of --k-surface-hi. */
+    wash: number;
+    /** The hairline edge: a share of --k-line-hi. */
+    line: number;
+    /** The wash at the panel's level, where the shape covers everything (a share of `wash`). */
+    panelWash: number;
+    /** A row's (or an editor part's) shape sits this far inside it (px). */
+    inset: number;
+    /** The panel's shape sits this far inside its edge (px). */
+    panelInset: number;
+}
+export declare const LENS_DEFAULTS: LensTune;
+export declare function readLensTune(style: CSSStyleDeclaration): LensTune;
+/**
+ * Offsets that decay to zero on a critically damped spring (ω = 2π / duration), sampled by time:
+ * x(t) = (x₀ + (v₀ + ωx₀)t)·e^(−ωt). Each channel has its own ω.
+ */
+export declare class Glide {
+    omegas: readonly number[];
+    private readonly eps;
+    private x0;
+    private v0;
+    private t0;
+    constructor(omegas: readonly number[], eps?: number);
+    sample(now: number): {
+        x: number[];
+        v: number[];
+    };
+    /** From `now`, the offsets are `x` moving at `v` (px/s). */
+    set(x: readonly number[], v: readonly number[], now: number, omegas?: readonly number[]): void;
+    zero(): void;
+    resting(now: number): boolean;
+}
+/** The ω for a spring that settles in `ms` with no bounce (knobs' mapping: ω = 2π / duration). */
+export declare const omegaOf: (ms: number) => number;
+/** A box as glide channels (x, y, w, h, then the four radii), and back. */
+export declare const boxChannels: (b: LensBox) => number[];
+export declare const boxPlus: (b: LensBox, d: readonly number[]) => LensBox;
+/**
+ * The corners a box inside a rounded container shows: where one of its corners sits on the
+ * container's (within half a pixel), the container's radius there, else its own. A row in a card
+ * is square but for the card's corners it reaches; so is an editor's part.
+ */
+export declare function cornersWithin(box: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}, own: LensCorners, outer?: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    r: LensCorners;
+}): LensCorners;
+export interface LensTarget {
+    readonly el: HTMLElement;
+    readonly level: LensLevel;
+}
+export interface LensOptions {
+    readonly root: HTMLElement;
+    /** A page: the panel's level is what shows of it under its header. */
+    readonly header?: HTMLElement;
+    readonly page?: boolean;
+    /** Whether a target shows now (a row's only while keys are in use, say). */
+    readonly shown: (target: LensTarget) => boolean;
+    readonly reduced: () => boolean;
+    /** Asks the GPU overlay for a frame. */
+    readonly wake: () => void;
+    /** While the layout glides (a page's cards): the DOM shape is re-placed every frame. */
+    readonly follow?: () => boolean;
+}
+export interface Lens {
+    /** The element the DOM draws it with. */
+    readonly element: HTMLElement;
+    /** Where focus is: a target, `null` to fade where it is, or "out" to grow out and fade. */
+    set(target: LensTarget | null | "out"): void;
+    readonly target: LensTarget | null;
+    /** The shapes to draw at `now` (viewport px). */
+    frame(now: number): LensShape[];
+    moving(now: number): boolean;
+    tune(): LensTune;
+    /** Re-place it (a scroll, a resize, a change in what shows). */
+    poke(followMs?: number): void;
+    dispose(): void;
+}
+export declare function createLens(o: LensOptions): Lens;

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

@@ -40,6 +40,8 @@ export declare class Edges {
 export declare const POP_MS = 360;
 /** Decile pop: a critically damped kick that swells to `peak` at 55 ms and settles (t in ms). */
 export declare function popScale(t: number, peak?: number): number;
+/** A slider's handle settling on a detent: its height swells like the pop, a little more (t in ms). */
+export declare const settleScale: (t: number) => number;
 export declare class VelocityTracker {
     private samples;
     add(x: number, y: number, t?: number): void;

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

@@ -0,0 +1,7 @@
+import type { RowOptions } from "./editors.js";
+export declare function createOptionKeys(doc: Document, root: HTMLElement, wake: () => void): {
+    /** Shows `options`' digits (undefined hides them); the same ones again just re-place. */
+    show(options: RowOptions | undefined): void;
+    dispose(): void;
+};
+export type OptionKeys = ReturnType<typeof createOptionKeys>;