@kitlangton/knobs 0.0.0-stage → 0.1.0

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

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

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

@@ -0,0 +1,8 @@
+/** 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;
+/**
+ * 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
+ * there's no Vibration API (iPhone); returns whether it did, so the caller skips `tick` for taps.
+ */
+export declare function tapTick(target: HTMLElement): boolean;

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

@@ -0,0 +1,14 @@
+/**
+ * What the panel's rules would ask `:has()` for, kept as attributes on the panel's elements
+ * instead (styles.ts rewrites the rules to match them). Chrome re-checks a `:has()` subject on
+ * DOM changes below it, and a rolling readout adds and drops digit nodes every frame it rolls: with
+ * forty readouts rolling at once (a preset), most of each frame's style work was that.
+ *
+ * - `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)`).
+ */
+export declare function trackHas(root: HTMLElement): () => void;

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

@@ -0,0 +1,45 @@
+export interface HintCandidate {
+    readonly key: string;
+    readonly display: string;
+}
+export interface HintBadgeState {
+    readonly match: boolean;
+    readonly prefix: string;
+    readonly typed: string;
+    readonly rest: string;
+}
+export interface HintResolution {
+    readonly badges: readonly HintBadgeState[];
+    readonly matchIndices: readonly number[];
+    readonly uniqueMatchIndex: number;
+}
+/**
+ * Assigns stable, prefix-free 1–2 letter (max 3) lowercase codes (`[a-z]{1,3}`) to `items`.
+ * Multi-word labels prefer word initials ("Accent hue" -> "ah", "Accent chroma" -> "ac");
+ * single-word labels use 1 letter when unique, else 2-letter combinations ("count" -> "cn", "Copy" -> "cp").
+ */
+export declare function assignHintCodes(items: readonly HintCandidate[]): string[];
+export declare function computeHintPrefixes(items: readonly HintCandidate[], rawQuery?: string): HintResolution;
+/** How `codes` read with `rawQuery` typed: which still match, what's typed of each, a sole match. */
+export declare function resolveHintCodes(codes: readonly string[], rawQuery?: string): HintResolution;
+export interface HintTarget extends HintCandidate {
+    readonly el: HTMLElement;
+    readonly labelEl?: HTMLElement;
+    activate(): void;
+}
+/** Where a badge goes: just after its label, else at the element's top-left corner. */
+export interface HintSpot {
+    readonly el: HTMLElement;
+    readonly labelEl?: HTMLElement;
+}
+export interface HintController {
+    readonly isActive: boolean;
+    /** Hint mode inside this panel alone: its own codes, and it hears the keys (`handleKey`). */
+    start(targets: HintTarget[]): void;
+    /** Draws badges with codes the page's coordinator chose; it hears the keys and calls `narrow`. */
+    show(targets: readonly HintSpot[], codes: readonly string[]): void;
+    narrow(query: string): void;
+    stop(): void;
+    handleKey(event: KeyboardEvent): boolean;
+}
+export declare function createHintController(doc: Document, root: HTMLElement, wakeGpu: () => void): HintController;

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

@@ -0,0 +1,30 @@
+export declare const ICONS: {
+    readonly undo: "M232,144a64.07,64.07,0,0,1-64,64H80a8,8,0,0,1,0-16h88a48,48,0,0,0,0-96H51.31l34.35,34.34a8,8,0,0,1-11.32,11.32l-48-48a8,8,0,0,1,0-11.32l48-48A8,8,0,0,1,85.66,45.66L51.31,80H168A64.07,64.07,0,0,1,232,144Z";
+    readonly redo: "M170.34,130.34,204.69,96H88a48,48,0,0,0,0,96h88a8,8,0,0,1,0,16H88A64,64,0,0,1,88,80H204.69L170.34,45.66a8,8,0,0,1,11.32-11.32l48,48a8,8,0,0,1,0,11.32l-48,48a8,8,0,0,1-11.32-11.32Z";
+    readonly help: "M140,180a12,12,0,1,1-12-12A12,12,0,0,1,140,180ZM128,72c-22.06,0-40,16.15-40,36v4a8,8,0,0,0,16,0v-4c0-11,10.77-20,24-20s24,9,24,20-10.77,20-24,20a8,8,0,0,0-8,8v8a8,8,0,0,0,16,0v-.72c18.24-3.35,32-17.9,32-35.28C168,88.15,150.06,72,128,72Zm104,56A104,104,0,1,1,128,24,104.11,104.11,0,0,1,232,128Zm-16,0a88,88,0,1,0-88,88A88.1,88.1,0,0,0,216,128Z";
+    readonly close: "M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z";
+    readonly random: "M192,32H64A32,32,0,0,0,32,64V192a32,32,0,0,0,32,32H192a32,32,0,0,0,32-32V64A32,32,0,0,0,192,32Zm16,160a16,16,0,0,1-16,16H64a16,16,0,0,1-16-16V64A16,16,0,0,1,64,48H192a16,16,0,0,1,16,16ZM104,92A12,12,0,1,1,92,80,12,12,0,0,1,104,92Zm72,0a12,12,0,1,1-12-12A12,12,0,0,1,176,92Zm-72,72a12,12,0,1,1-12-12A12,12,0,0,1,104,164Zm36-36a12,12,0,1,1-12-12A12,12,0,0,1,140,128Zm36,36a12,12,0,1,1-12-12A12,12,0,0,1,176,164Z";
+    readonly reset: "M224,128a96,96,0,0,1-94.71,96H128A95.38,95.38,0,0,1,62.1,197.8a8,8,0,0,1,11-11.63A80,80,0,1,0,71.43,71.39a3.07,3.07,0,0,1-.26.25L44.59,96H72a8,8,0,0,1,0,16H24a8,8,0,0,1-8-8V56a8,8,0,0,1,16,0V85.8L60.25,60A96,96,0,0,1,224,128Z";
+    readonly lock: "M208,80H176V56a48,48,0,0,0-96,0V80H48A16,16,0,0,0,32,96V208a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V96A16,16,0,0,0,208,80ZM96,56a32,32,0,0,1,64,0V80H96ZM208,208H48V96H208V208Z";
+    readonly copy: "M216,32H88a8,8,0,0,0-8,8V80H40a8,8,0,0,0-8,8V216a8,8,0,0,0,8,8H168a8,8,0,0,0,8-8V176h40a8,8,0,0,0,8-8V40A8,8,0,0,0,216,32ZM160,208H48V96H160Zm48-48H176V88a8,8,0,0,0-8-8H96V48H208Z";
+    readonly caret: "M181.66,170.34a8,8,0,0,1,0,11.32l-48,48a8,8,0,0,1-11.32,0l-48-48a8,8,0,0,1,11.32-11.32L128,212.69l42.34-42.35A8,8,0,0,1,181.66,170.34Zm-96-84.68L128,43.31l42.34,42.35a8,8,0,0,0,11.32-11.32l-48-48a8,8,0,0,0-11.32,0l-48,48A8,8,0,0,0,85.66,85.66Z";
+    readonly gear: "M128,80a48,48,0,1,0,48,48A48.05,48.05,0,0,0,128,80Zm0,80a32,32,0,1,1,32-32A32,32,0,0,1,128,160Zm109.94-52.79a8,8,0,0,0-3.89-5.4l-29.83-17-.12-33.62a8,8,0,0,0-2.83-6.08,111.91,111.91,0,0,0-36.72-20.67,8,8,0,0,0-6.46.59L128,41.85,97.88,25a8,8,0,0,0-6.47-.6A112.1,112.1,0,0,0,54.73,45.15a8,8,0,0,0-2.83,6.07l-.15,33.65-29.83,17a8,8,0,0,0-3.89,5.4,106.47,106.47,0,0,0,0,41.56,8,8,0,0,0,3.89,5.4l29.83,17,.12,33.62a8,8,0,0,0,2.83,6.08,111.91,111.91,0,0,0,36.72,20.67,8,8,0,0,0,6.46-.59L128,214.15,158.12,231a7.91,7.91,0,0,0,3.9,1,8.09,8.09,0,0,0,2.57-.42,112.1,112.1,0,0,0,36.68-20.73,8,8,0,0,0,2.83-6.07l.15-33.65,29.83-17a8,8,0,0,0,3.89-5.4A106.47,106.47,0,0,0,237.94,107.21Zm-15,34.91-28.57,16.25a8,8,0,0,0-3,3c-.58,1-1.19,2.06-1.81,3.06a7.94,7.94,0,0,0-1.22,4.21l-.15,32.25a95.89,95.89,0,0,1-25.37,14.3L134,199.13a8,8,0,0,0-3.91-1h-.19c-1.21,0-2.43,0-3.64,0a8.08,8.08,0,0,0-4.1,1l-28.84,16.1A96,96,0,0,1,67.88,201l-.11-32.2a8,8,0,0,0-1.22-4.22c-.62-1-1.23-2-1.8-3.06a8.09,8.09,0,0,0-3-3.06l-28.6-16.29a90.49,90.49,0,0,1,0-28.26L61.67,97.63a8,8,0,0,0,3-3c.58-1,1.19-2.06,1.81-3.06a7.94,7.94,0,0,0,1.22-4.21l.15-32.25a95.89,95.89,0,0,1,25.37-14.3L122,56.87a8,8,0,0,0,4.1,1c1.21,0,2.43,0,3.64,0a8.08,8.08,0,0,0,4.1-1l28.84-16.1A96,96,0,0,1,188.12,55l.11,32.2a8,8,0,0,0,1.22,4.22c.62,1,1.23,2,1.8,3.06a8.09,8.09,0,0,0,3,3.06l28.6,16.29A90.49,90.49,0,0,1,222.9,142.12Z";
+    readonly search: "M229.66,218.34l-50.07-50.06a88.11,88.11,0,1,0-11.31,11.31l50.06,50.07a8,8,0,0,0,11.32-11.32ZM40,112a72,72,0,1,1,72,72A72.08,72.08,0,0,1,40,112Z";
+    readonly link: "M165.66,90.34a8,8,0,0,1,0,11.32l-64,64a8,8,0,0,1-11.32-11.32l64-64A8,8,0,0,1,165.66,90.34ZM215.6,40.4a56,56,0,0,0-79.2,0L106.34,70.45a8,8,0,0,0,11.32,11.32l30.06-30a40,40,0,0,1,56.57,56.56l-30.07,30.06a8,8,0,0,0,11.31,11.32L215.6,119.6a56,56,0,0,0,0-79.2ZM138.34,174.22l-30.06,30.06a40,40,0,1,1-56.56-56.57l30.05-30.05a8,8,0,0,0-11.32-11.32L40.4,136.4a56,56,0,0,0,79.2,79.2l30.06-30.07a8,8,0,0,0-11.32-11.31Z";
+    readonly unlink: "M232,80a55.67,55.67,0,0,1-16.4,39.6l-30.07,30.06a8,8,0,0,1-11.31-11.32l30.07-30.06a40,40,0,1,0-56.57-56.56L117.66,81.77a8,8,0,0,1-11.32-11.32L136.4,40.4A56,56,0,0,1,232,80Zm-93.66,94.22-30.06,30.06a40,40,0,1,1-56.56-56.57l30.05-30.05a8,8,0,0,0-11.32-11.32L40.4,136.4a56,56,0,0,0,79.2,79.2l30.06-30.07a8,8,0,0,0-11.32-11.31Z";
+    readonly play: "M232.4,114.49,88.32,26.35a16,16,0,0,0-16.2-.3A15.86,15.86,0,0,0,64,39.87V216.13A15.94,15.94,0,0,0,80,232a16.07,16.07,0,0,0,8.36-2.35L232.4,141.51a15.81,15.81,0,0,0,0-27ZM80,215.94V40l143.83,88Z";
+    readonly pause: "M200,32H160a16,16,0,0,0-16,16V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,200,32Zm0,176H160V48h40ZM96,32H56A16,16,0,0,0,40,48V208a16,16,0,0,0,16,16H96a16,16,0,0,0,16-16V48A16,16,0,0,0,96,32Zm0,176H56V48H96Z";
+    readonly frame: "M200,80v32a8,8,0,0,1-16,0V88H160a8,8,0,0,1,0-16h32A8,8,0,0,1,200,80ZM96,168H72V144a8,8,0,0,0-16,0v32a8,8,0,0,0,8,8H96a8,8,0,0,0,0-16ZM232,56V200a16,16,0,0,1-16,16H40a16,16,0,0,1-16-16V56A16,16,0,0,1,40,40H216A16,16,0,0,1,232,56ZM216,200V56H40V200H216Z";
+    readonly retrigger: "M240,56v48a8,8,0,0,1-8,8H184a8,8,0,0,1,0-16H211.4L184.81,71.64l-.25-.24a80,80,0,1,0-1.67,114.78,8,8,0,0,1,11,11.63A95.44,95.44,0,0,1,128,224h-1.32A96,96,0,1,1,195.75,60L224,85.8V56a8,8,0,1,1,16,0Z";
+    readonly clear: "M225,80.4,183.6,39a24,24,0,0,0-33.94,0L31,157.66a24,24,0,0,0,0,33.94l30.06,30.06A8,8,0,0,0,66.74,224H216a8,8,0,0,0,0-16h-84.7L225,114.34A24,24,0,0,0,225,80.4ZM108.68,208H70.05L42.33,180.28a8,8,0,0,1,0-11.31L96,115.31,148.69,168Zm105-105L160,156.69,107.31,104,161,50.34a8,8,0,0,1,11.32,0l41.38,41.38a8,8,0,0,1,0,11.31Z";
+    readonly target: "M232,120h-8.34A96.14,96.14,0,0,0,136,32.34V24a8,8,0,0,0-16,0v8.34A96.14,96.14,0,0,0,32.34,120H24a8,8,0,0,0,0,16h8.34A96.14,96.14,0,0,0,120,223.66V232a8,8,0,0,0,16,0v-8.34A96.14,96.14,0,0,0,223.66,136H232a8,8,0,0,0,0-16Zm-96,87.6V200a8,8,0,0,0-16,0v7.6A80.15,80.15,0,0,1,48.4,136H56a8,8,0,0,0,0-16H48.4A80.15,80.15,0,0,1,120,48.4V56a8,8,0,0,0,16,0V48.4A80.15,80.15,0,0,1,207.6,120H200a8,8,0,0,0,0,16h7.6A80.15,80.15,0,0,1,136,207.6ZM128,88a40,40,0,1,0,40,40A40,40,0,0,0,128,88Zm0,64a24,24,0,1,1,24-24A24,24,0,0,1,128,152Z";
+    readonly camera: "M208,56H180.28L166.65,35.56A8,8,0,0,0,160,32H96a8,8,0,0,0-6.65,3.56L75.71,56H48A24,24,0,0,0,24,80V192a24,24,0,0,0,24,24H208a24,24,0,0,0,24-24V80A24,24,0,0,0,208,56Zm8,136a8,8,0,0,1-8,8H48a8,8,0,0,1-8-8V80a8,8,0,0,1,8-8H80a8,8,0,0,0,6.66-3.56L100.28,48h55.43l13.63,20.44A8,8,0,0,0,176,72h32a8,8,0,0,1,8,8ZM128,88a44,44,0,1,0,44,44A44.05,44.05,0,0,0,128,88Zm0,72a28,28,0,1,1,28-28A28,28,0,0,1,128,160Z";
+    readonly sparkle: "M197.58,129.06,146,110l-19-51.62a15.92,15.92,0,0,0-29.88,0L78,110l-51.62,19a15.92,15.92,0,0,0,0,29.88L78,178l19,51.62a15.92,15.92,0,0,0,29.88,0L146,178l51.62-19a15.92,15.92,0,0,0,0-29.88ZM137,164.22a8,8,0,0,0-4.74,4.74L112,223.85,91.78,169A8,8,0,0,0,87,164.22L32.15,144,87,123.78A8,8,0,0,0,91.78,119L112,64.15,132.22,119a8,8,0,0,0,4.74,4.74L191.85,144ZM144,40a8,8,0,0,1,8-8h16V16a8,8,0,0,1,16,0V32h16a8,8,0,0,1,0,16H184V64a8,8,0,0,1-16,0V48H152A8,8,0,0,1,144,40ZM248,88a8,8,0,0,1-8,8h-8v8a8,8,0,0,1-16,0V96h-8a8,8,0,0,1,0-16h8V72a8,8,0,0,1,16,0v8h8A8,8,0,0,1,248,88Z";
+};
+export type IconName = keyof typeof ICONS;
+/** The copy button's check: a 16-wide round stroke (Phosphor's weight) that draws itself in. */
+export declare const CHECK_POINTS: readonly [44, 132, 100, 188, 212, 76];
+export declare const CHECK_PATH: string;
+/** A built-in icon's path, else `icon` itself as SVG path data on a 256 grid. */
+export declare const iconPath: (icon: string) => string;
+export declare function iconSvg(doc: Document, name: IconName | (string & {})): SVGSVGElement;

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

@@ -0,0 +1,10 @@
+export { attach } from "./attach.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";
+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 { injectStyles } from "./styles.js";
+export { attachVariantSwitcher, getSwitcherOptions, type ChoiceKey, type SwitcherOptions, } from "./switcher.js";

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

@@ -0,0 +1,20 @@
+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";
+type Vec = Point & {
+    readonly z?: number;
+};
+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 declare function keybindRow(c: RowContext<KeybindField>): 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). */
+    match(event: KeyboardEvent, global: boolean): ToolbarItem | undefined;
+    press(item: ToolbarItem): void;
+    swap(field: ToolbarField): void;
+}
+export declare function toolbarRow(c: RowContext<ToolbarField>, press: (item: ToolbarItem) => void): ToolbarRow;
+/** The value a vector shows, as `{ x, y }` or `{ x, y, z }`. */
+export type { Vec, Vec3 };

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

@@ -0,0 +1,6 @@
+export declare function measure<T>(read: () => T, write: (value: T) => void): void;
+export declare function batchMeasures(run: () => void): void;
+/** Whether a batch is running: reads taken now, before its writes, find layout clean. */
+export declare const inBatch: () => boolean;
+/** Runs `end` when the running batch has written everything (to drop what was read for it). */
+export declare function afterBatch(end: () => void): void;

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

@@ -0,0 +1,38 @@
+export interface MenuItem {
+    readonly label: string;
+    /** Shown right-aligned, as macOS menus show key equivalents. */
+    readonly shortcut?: string;
+    readonly disabled?: boolean;
+    /** Draws a hairline above the item. */
+    readonly separated?: boolean;
+    /** Marks the current option, as a pop-up menu's check mark does. */
+    readonly checked?: boolean;
+    run(): void;
+}
+export interface Menu {
+    readonly element: HTMLElement;
+    /** `restore` returns focus to where it was before the menu opened (or `returnTo`). */
+    close(restore?: boolean): void;
+}
+/**
+ * A context menu over everything at (`x`, `y`): it scales and fades out of that corner and back
+ * into it. It holds focus itself and marks the active item, so it's driven entirely from the
+ * keyboard (↑↓, Home/End, Enter, Esc, a letter to jump) as well as the pointer.
+ */
+export declare function openMenu(doc: Document, panel: HTMLElement, items: readonly MenuItem[], at: {
+    x: number;
+    y: number;
+}, options?: {
+    keyboard?: boolean;
+    returnTo?: HTMLElement;
+    onClose?: () => void;
+    /** The item marked active on open (a pop-up menu starts on its current option). */
+    active?: number;
+    /** At least this wide (px), e.g. the button it drops from. */
+    minWidth?: number;
+    /**
+     * A search field over the items: typing filters them (by any part of their label), ↑↓
+     * move through what's left, Enter picks, Esc closes. For long choice lists.
+     */
+    search?: boolean;
+}): Menu;

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

@@ -0,0 +1,38 @@
+/**
+ * How long the press takes to squeeze the chip, and how far (the chip's CSS matches). It eases in
+ * and out, so the glass sets off from rest without a kink.
+ */
+export declare const ANTICIPATION_MS = 50;
+export declare const SQUEEZE = 0.94;
+export interface MorphFrame {
+    /** The shape, in viewport px. */
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly radius: number;
+    /** 0 at the chip, 1 at the panel (by size); overshoots a little on the bounce. */
+    readonly progress: number;
+    /** Content is fully shown above `fadeTop` and hidden below `fadeBottom` (viewport y). */
+    readonly fadeTop: number;
+    readonly fadeBottom: number;
+    /** The content's blur (px), opacity and scale about (originX, originY), in viewport px. */
+    readonly blur: number;
+    readonly opacity: number;
+    readonly scale: number;
+    readonly originX: number;
+    readonly originY: number;
+    /** Alpha of the glass's specular ring. */
+    readonly specular: number;
+}
+export interface PanelMorph {
+    /** The shape at `now` (a frame time), or undefined while the panel rests open. */
+    frame(now: number): MorphFrame | undefined;
+    /** Grows out of the chip, or reverses a collapse from wherever it is. */
+    open(): void;
+    /** Collapses into the chip, then calls `done`. */
+    close(done: () => void): void;
+    readonly closing: boolean;
+    dispose(): void;
+}
+export declare function morphFromChip(chip: HTMLElement, root: HTMLElement, wake: () => void, restored: boolean): PanelMorph;

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

@@ -0,0 +1,77 @@
+import { Spring } from "../core/spring.js";
+export { Spring, springEasing } from "../core/spring.js";
+/** The slider fill, and its rubber band springing back from past an end. */
+export declare const FILL: {
+    omega: number;
+    zeta: number;
+};
+export declare const RELEASE: {
+    omega: number;
+    zeta: number;
+};
+export declare const LEAD: {
+    omega: number;
+    zeta: number;
+};
+export declare const TRAIL: {
+    omega: number;
+    zeta: number;
+};
+/** How far the trailing edge lags at a `--k-blur` strength (0 keeps both edges together). */
+export declare const trailScale: (blur: number) => number;
+/**
+ * A sliding shape's two edges (like iOS's page-dot thumb): the edge facing the motion leads on a
+ * snappy spring and the other trails on a softer one, so the shape stretches toward its
+ * destination and settles back to size.
+ */
+export declare class Edges {
+    readonly start: Spring;
+    readonly end: Spring;
+    constructor(start?: number, end?: number);
+    to(start: number, end: number, delay?: number, trail?: number): this;
+    /** Moves both edges and their targets by the same distance, keeping any motion in flight. */
+    shift(ds: number, de: number): this;
+    snap(start: number, end: number): this;
+    step(dt: number): this;
+    get resting(): boolean;
+    /** Signed travel speed (px/s) of the shape's centre. */
+    get velocity(): number;
+}
+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;
+export declare class VelocityTracker {
+    private samples;
+    add(x: number, y: number, t?: number): void;
+    reset(): void;
+    get velocity(): [number, number];
+}
+export declare const clamp: (x: number, a: number, b: number) => number;
+/**
+ * Time-based critically damped motion, the same curve @kitlangton/rolling-number samples for
+ * its reels: settles in `duration`, carries velocity across retargets, and never overshoots.
+ */
+export declare class Roll {
+    private from;
+    private to;
+    private inherited;
+    private start;
+    private duration;
+    constructor(position: number);
+    get target(): number;
+    sample(now: number): {
+        position: number;
+        velocity: number;
+    };
+    /** Retarget from wherever the motion is now; `delay` holds the current position first. */
+    set(target: number, duration: number, now: number, delay?: number): this;
+    snap(position: number): this;
+    resting(now: number): boolean;
+    /** Positions the current motion covers, like rolling-number's reel: faces outside never show. */
+    span(now: number): [number, number];
+}
+/** Nearest wheel position showing `digit`, honoring the trend (from rolling-number). */
+export declare function rollTarget(position: number, digit: number, trend: number): number;
+export declare const numeral: (position: number) => string;
+/** New glyphs hold briefly, then rise into their slot (rolling-number's `entrance`). Returns 0..1 of a face height. */
+export declare function entranceOffset(elapsed: number, duration: number, hold?: number): number;

package/dist/types/panel/page-hints.d.ts

@@ -0,0 +1,82 @@
+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";
+/**
+ * Codes for groups of targets (a panel's controls, a tree's rows…), in order: each group takes a
+ * letter of its own (home row first) and its targets a second letter, home row first; a group of
+ * one is just its letter. While letters are spare, big groups take more of them so their second
+ * letters stay on the home row. With more groups than letters, they share letters in order. Codes
+ * are prefix-free and at most two letters; a target past 676 gets `""` (no code).
+ */
+export declare function assignPageCodes(counts: readonly number[]): string[][];
+/** Where a group sits: the top-left of its targets, and how it ranks (panels first). */
+export interface HintGroupPlace {
+    readonly rank: number;
+    readonly left: number;
+    readonly top: number;
+}
+/** The order groups take letters in: by rank, then down each column, left to right. */
+export declare function orderHintGroups(groups: readonly HintGroupPlace[]): number[];
+/** A target: an element and what pressing its code does (focus, or click, by default). */
+export interface PageHintTarget {
+    readonly el: HTMLElement;
+    /** For codes when it's the only group on the page; its aria-label or text by default. */
+    readonly label?: string;
+    /** The badge goes just after this (a row's label), else at the element's left edge. */
+    readonly labelEl?: HTMLElement;
+    readonly activate?: () => void;
+}
+/** Draws a group's badges itself (a panel, in its renderer); the coordinator hears the keys. */
+export interface HintPainter {
+    show(targets: readonly HintSpot[], codes: readonly string[]): void;
+    narrow(query: string): void;
+    clear(): void;
+}
+export interface HintSourceOptions {
+    /**
+     * Whether `s` anywhere on the page starts hint mode while this is registered (`true`, the
+     * default). knobs/ui pieces pass `false`: they join hint mode without turning it on.
+     */
+    readonly listen?: boolean;
+    /** Draws the badges itself. */
+    readonly paint?: HintPainter;
+    /** Lower ranks take letters first: panels 0, knobs/ui pieces 1, the host's own 2 (the default). */
+    readonly rank?: number;
+}
+export interface PageHints {
+    /**
+     * Adds a group of targets: `targets()` is read each time hint mode starts and may list elements
+     * or `PageHintTarget`s; hidden, disabled and scrolled-away ones are skipped. Returns a function
+     * that removes it.
+     */
+    register(root: HTMLElement, targets: () => Iterable<HTMLElement | PageHintTarget>, options?: HintSourceOptions): () => void;
+    /** Starts hint mode across the page; `false` when there was nothing to label. */
+    start(): boolean;
+    stop(): void;
+    readonly active: boolean;
+    /**
+     * Whether `s` anywhere on the page starts hint mode: a panel or host has registered, and there's
+     * something else on the page to label too.
+     */
+    readonly listening: boolean;
+}
+/** The page's hint key. */
+export declare const PAGE_HINT_KEY = "s";
+/** The page's hint registry (one per document). */
+export declare function pageHints(doc?: Document): PageHints;
+/**
+ * The page's hint registry, for `document`: `hints.register(root, () => targets)`. Elements with a
+ * `data-hint` attribute (its value is the label; empty uses the aria-label or text) join without
+ * registering, grouped by their nearest `[data-hint-group]`.
+ */
+export declare const hints: {
+    register(root: HTMLElement, targets: () => Iterable<HTMLElement | PageHintTarget>, options?: HintSourceOptions): () => void;
+    start: (doc?: Document) => boolean;
+    stop: (doc?: Document) => void;
+};
+/**
+ * Whether a key belongs to the page's hint mode rather than a piece's own letters (a tree's
+ * 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;