@kitlangton/knobs 0.2.0 → 0.4.0-next.0

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

@@ -19,3 +19,5 @@ export declare function matchesCombo(combo: string, event: KeyboardEvent): boole
  */
 export declare function comboParts(combo: string, apple?: boolean): string[];
 export declare function comboLabel(combo: string, apple?: boolean): string;
+/** Whether a key goes to what has focus: a text field, a select or editable text. */
+export declare function isTypingTarget(target: EventTarget | null): boolean;

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

@@ -118,6 +118,8 @@ export interface RemoteControlsOptions {
     readonly enabled?: boolean | (() => boolean);
     /** Ships the panel as product UI, live in production: `() => import("knobs/panel")` (see `ControlsOptions.ship`). */
     readonly ship?: () => Promise<PanelModule>;
+    /** The key that shows and hides its panels with the page's others (see `ControlsOptions.toggleKey`). */
+    readonly toggleKey?: string | false;
     /** How long (ms) a key changed here outranks incoming values for it; 600 by default. */
     readonly echo?: number;
     /**

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

@@ -78,6 +78,11 @@ export interface Knob extends FieldMeta {
     /** Digits after the point in the readout; the step's own by default. */
     readonly decimals?: number;
     readonly spring?: SpringPart;
+    /**
+     * Whether a drag sticks for a moment at the default, the active preset's value and the middle
+     * (and zero); `false` lets it glide straight through.
+     */
+    readonly detents?: boolean;
 }
 export interface Choice<T extends string = string> extends FieldMeta {
     readonly kind: "choice";

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

@@ -15,7 +15,8 @@ export interface ChipOptions {
     /**
      * When the chip shows. `"hover"`: while the element is hovered or focused. `"shortcut"`: hidden
      * until `shortcut` turns on knobs mode (remembered for the tab), then on hover. `"always"`:
-     * whenever its panel is closed. `"hover"` in development, `"shortcut"` in production builds.
+     * whenever its panel is closed. `"hover"` in development (and on a page someone unlocked),
+     * `"shortcut"` for a shipped store in production builds.
      */
     readonly reveal?: RevealMode;
     /** The key that toggles knobs mode for `"shortcut"` chips: `"Alt+Shift+D"` (⌥⇧D) by default. */
@@ -96,7 +97,7 @@ export type PanelCommand = "random" | "mutate" | "reset" | "resetAll" | "compare
 export type PanelKeys = {
     readonly [C in PanelCommand]?: string | boolean;
 } & {
-    /** `false` drops the j/k and h/l aliases: only the arrows move and adjust; the letters reach the page. */
+    /** `false` drops the j/k aliases: only the arrows move; the letters reach the page. */
     readonly vim?: boolean;
     /**
      * `false` stops digits, `.`, `-` and Enter from opening a slider's inline number editor (they
@@ -144,6 +145,12 @@ export interface MountPanelOptions extends LabelOptions {
      * don't join the page's. `keys: { hint: false }` turns hint mode off here either way.
      */
     readonly hints?: "page" | "panel";
+    /**
+     * The key that shows and hides every panel and chip on the page that listens for it, outside
+     * text fields and without modifiers; remembered per store. The store's `toggleKey` by default
+     * (a backtick), `false` on a full page (`mountPage`). `false`: this panel always shows.
+     */
+    readonly toggleKey?: string | false;
     /**
      * `false` hides what says a value differs from its default: modified dots and readout marks,
      * group reset icons and the header's Reset. For panels whose values belong to someone else
@@ -159,6 +166,11 @@ export interface MountPanelOptions extends LabelOptions {
      * list, every button but `help` shows (see `HeaderOptions`).
      */
     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.
+     */
+    readonly crumbs?: boolean;
     /**
      * `false`: no per-tab session, so a rebuilt panel doesn't take focus back to the row it last
      * had or reopen editors and folded groups. On while the store has storage.
@@ -203,6 +215,11 @@ export interface MountPanelOptions extends LabelOptions {
      * Reduced motion turns them off too.
      */
     readonly haptics?: boolean;
+    /**
+     * Magnetic detents on slider drags and pans (the default, the active preset's value, the middle
+     * and zero); on by default, `false` turns them off for the whole panel.
+     */
+    readonly detents?: boolean;
     /**
      * Sound effects: quiet, short ticks and clicks synthesized live for the panel's moments (a
      * slider's detents, a switch, Random, Copy…). Off by default; `true` turns them on, or
@@ -280,6 +297,8 @@ export interface PanelHandle {
 export interface PanelModule {
     mountPanel(controls: Controls<any>, container: HTMLElement, options?: MountPanelOptions): PanelHandle;
     attach(controls: Controls<any>, element: HTMLElement, chip?: ChipOptions): () => void;
+    /** A brief status at the bottom of the page ("knobs unlocked"). */
+    status?(text: string): void;
 }
 export interface ControlsOptions<S extends Schema> extends LabelOptions {
     enabled?: boolean | (() => boolean);
@@ -292,6 +311,12 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
     ship?: () => Promise<PanelModule>;
     /** The chip `attach` shows: its label, when it shows and the knobs-mode key (see `ChipOptions`). */
     chip?: ChipOptions;
+    /**
+     * The key that shows and hides this store's panels and chips, with every other panel on the
+     * page that listens for it (see `MountPanelOptions.toggleKey`). A backtick by default; `false`
+     * for a shipped store (`ship`), whose panels are product UI. `false`: always shown.
+     */
+    toggleKey?: string | false;
     /**
      * The longest (ms) a key changed here outranks incoming values for it (see `sync`), so an echo
      * of an older value still in flight can't pull it back. The hold ends early once the remote
@@ -370,6 +395,8 @@ export interface Controls<S extends Schema = Schema> {
         readonly reveal: RevealMode;
         readonly shortcut: string;
     };
+    /** The key that shows and hides its panels and chips, or `false` (see `ControlsOptions.toggleKey`). */
+    readonly toggleKey: string | false;
     /** How page cards show group presets (`groupPresetDisplay`, `auto` by default). */
     readonly groupPresetDisplay: GroupPresetDisplay;
     /** A group's display label (`groupLabels`, else its fields' `groupLabel`), if it has one. */

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

@@ -0,0 +1,77 @@
+import type { PanelModule } from "./store.js";
+/** The Konami code: ↑ ↑ ↓ ↓ ← → ← → B A, as key names for `unlock({ sequence })`. */
+export declare const KONAMI: readonly string[];
+export type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export interface UnlockOptions {
+    /**
+     * The panel code, loaded only once someone unlocks: `() => import("knobs/panel")`. Your bundler
+     * splits it into its own chunk, so visitors who never unlock download none of it.
+     */
+    readonly panel: () => Promise<PanelModule>;
+    /**
+     * Typed anywhere outside a text field: a word (`"knobs"` by default) or a list of key names
+     * (`KONAMI`). Typing it again locks. `false`: none.
+     */
+    readonly sequence?: string | readonly string[] | false;
+    /** `?knobs` in the URL unlocks and `?knobs=off` locks (`"knobs"` by default). `false`: none. */
+    readonly query?: string | false;
+    /**
+     * Three quick taps or clicks in this corner of the window (`"top-right"` by default), for
+     * phones. Three more lock. `false`: none.
+     */
+    readonly corner?: Corner | false;
+    /** Remember being unlocked in localStorage until it's locked again (default true). */
+    readonly persist?: boolean;
+}
+/** A page's secret unlock (see `unlock`). */
+export interface Unlock {
+    readonly unlocked: boolean;
+    unlock(): void;
+    lock(): void;
+    /** Stops listening for the sequence and the corner; the state stays as it is. */
+    dispose(): void;
+}
+/** Whether this page has been unlocked (see `unlock`). */
+export declare const isUnlocked: () => boolean;
+/** The panel module an unlocked page mounts from, if `unlock` named one. */
+export declare const unlockedPanel: () => (() => Promise<PanelModule>) | undefined;
+/** Calls `listener` whenever the page locks or unlocks. */
+export declare function onUnlock(listener: () => void): () => void;
+export declare const UNLOCK_KEY = "knobs:unlocked";
+/** The keys a sequence is typed with: a word's letters, or key names as given. */
+export declare function sequenceKeys(sequence: string | readonly string[]): string[];
+/**
+ * Watches keys go by for `sequence`: true on the key that completes it. Letters match in either
+ * case, a wrong key starts over (keeping what it could begin), and a pause longer than `gap` ms
+ * forgets what was typed.
+ */
+export declare function sequenceMatcher(sequence: string | readonly string[], gap?: number): (key: string, at: number) => boolean;
+/**
+ * What the URL says: `?knobs` (or `=1`, `=on`, `=true`) unlocks, `?knobs=off` (or `=0`, `=false`,
+ * `=lock`) locks, and without it, undefined.
+ */
+export declare function queryUnlock(search: string, name: string): boolean | undefined;
+/**
+ * Whether a page view starts unlocked: the URL decides when it says, else what was remembered
+ * (only when `persist`). `remember` is what to keep afterwards (undefined: leave it).
+ */
+export declare function resolveUnlock(input: {
+    readonly query: boolean | undefined;
+    readonly stored: boolean;
+    readonly persist: boolean;
+}): {
+    readonly unlocked: boolean;
+    readonly remember: boolean | undefined;
+};
+/** Whether a point is in `corner` of a `width` × `height` window, within `size` px. */
+export declare function inCorner(x: number, y: number, width: number, height: number, corner: Corner, size?: number): boolean;
+/** Counts quick taps: true on the `count`th, each within `within` ms of the last. */
+export declare function tapCounter(count?: number, within?: number): (at: number) => boolean;
+/**
+ * Lets this deploy be unlocked: stores stay locked to their shipped values and mount nothing
+ * until someone types the sequence, opens the page with `?knobs`, or taps the corner three
+ * times. Then they come alive (values from this browser's storage) and the panel code loads.
+ * The same again locks, back to the shipped values. In development it changes nothing: stores
+ * are live there anyway.
+ */
+export declare function unlock(options: UnlockOptions): Unlock;

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource,
 export { createRemoteControls, descriptorToField, formatSwift, fromDescriptors, fromSettings, type SettingsGroup, type SettingsItem, type ActionDescriptor, type ChoiceOption, type ControlDescriptor, type SpringBindingDescriptor, type ToolbarDescriptor, type ReadoutDescriptor, type ValueDescriptor, type RemoteControls, type RemoteControlsOptions, } from "./core/remote.js";
 export type { LogEntry, LogLevel, TableRows, WatchValue } from "./core/readout.js";
 export { memoryStorage, urlFlag, type StoragePort } from "./core/storage.js";
+export { KONAMI, unlock, type Corner, type Unlock, type UnlockOptions } from "./core/unlock.js";
 export type { TokenPreset } from "./core/theme.js";
 export { formatCode, type CodeFormat } from "./core/code.js";
 export { comboFromEvent, letterOf, comboLabel, comboParts, matchesCombo, normalizeCombo, } from "./core/keys.js";

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

@@ -3,3 +3,5 @@ import type { Schema } from "../core/schema.js";
 export declare function attach<S extends Schema>(controls: Controls<S>, element: HTMLElement, options?: ChipOptions): () => void;
 /** Parses `"Alt+Shift+D"` into a test for keydown events. Letters and digits match by key position. */
 export declare function matchShortcut(shortcut: string): (event: KeyboardEvent) => boolean;
+/** A brief status at the bottom of the page, as knobs mode's "knobs on" ("knobs unlocked"). */
+export declare function status(text: string, doc?: Document): void;

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

@@ -0,0 +1,19 @@
+import { type Crumb, type CrumbLevel } from "./scope.js";
+export declare const CRUMB_GLIDE: string;
+export interface CrumbsView {
+    readonly element: HTMLElement;
+    /** The trail for where focus is, and where Esc goes from there (none at the panel). */
+    set(trail: readonly Crumb[], esc?: string): void;
+    /** Shows or quiets the Esc hint. */
+    hint(on: boolean): void;
+    /** Re-place it after the header's layout changed. */
+    layout(): void;
+    dispose(): void;
+}
+export declare function createCrumbs(o: {
+    header: HTMLElement;
+    title: HTMLElement;
+    jump: (level: CrumbLevel | "panel") => void;
+    reduced: () => boolean;
+    wake: () => void;
+}): CrumbsView;

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

@@ -165,6 +165,15 @@ export declare function panPresets(c: RowContext<unknown>, head: HTMLElement, nu
     at(): number;
     choose(i: number, coalesce: boolean): void;
 }): void;
+/** Named presets as chips in a radiogroup (the easing editor's look); ←/→ cycle them. */
+export declare function presetChips(c: RowContext<unknown>, names: readonly string[], choose: (i: number) => void, cls?: string): {
+    el: HTMLDivElement;
+    buttons: HTMLButtonElement[];
+    cycle: (dir: number) => void;
+    check(i: number): void;
+};
+/** ←/→ on `target` itself cycle the presets (a row's head, the chips). */
+export declare function cycleKeys(targets: readonly HTMLElement[], row: HTMLElement, cycle: (dir: number) => void): void;
 /** A mini curve in the head; an editor with two handles and named chips in the body. */
 export declare function easingRow(c: RowContext<EasingField>): EditorRow;
 export {};

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/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,6 +3,7 @@ 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 { LensShape } from "../lens.js";
 import { type PresetStrip } from "../presets.js";
 import type { DigitPlace, Slider } from "../slider.js";
 import type { TabStrip } from "../tabs.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;
@@ -425,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). */
@@ -545,6 +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;
+    /** 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;
@@ -632,6 +647,17 @@ declare class GpuOverlayManager {
     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. */
@@ -722,6 +748,12 @@ declare class GpuOverlayManager {
      * 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. */

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

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

@@ -1,5 +1,5 @@
 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, RowContext } from "./editors.js";
+import { type EditorRow, type RowContext } from "./editors.js";
 type Vec = Point & {
     readonly z?: number;
 };

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/page-hints.d.ts

@@ -1,3 +1,4 @@
+import { isTypingTarget } from "../core/keys.js";
 import { type HintSpot } from "./hints.js";
 /** Code letters, home row first: groups take the first letters, their targets the second. */
 export declare const HINT_LETTERS = "asdfghjkleruiowtyqpcvnmxzb";
@@ -79,4 +80,4 @@ export declare const hints: {
  * type-ahead): it's the hint key and something on the page has turned hint mode on.
  */
 export declare function claimsHintKey(doc: Document, key: string): boolean;
-export declare const isTyping: (target: EventTarget | null) => boolean;
+export declare const isTyping: typeof isTypingTarget;