@kitlangton/knobs 0.1.0 → 0.2.0

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

@@ -7,19 +7,27 @@ export interface PresetEntry<V = Record<string, unknown>> {
     readonly rawId: string;
     readonly label: string;
     readonly values: V;
-    apply(): void;
+    /** Applies it (making it the active preset); `coalesce` folds it into the last undo step. */
+    apply(coalesce?: boolean): void;
 }
 export interface ActivePresetState {
     readonly activeId: string;
     readonly activeIndex: number;
     readonly isCustom: boolean;
+    /** The active preset's chip, while the values have moved off it (its modified mark). */
+    readonly drifted?: boolean;
 }
+/** How strong the selection pill stays on the active preset once the values drift off it. */
+export declare const DRIFTED_PILL = 0.5;
+/** The strip's id for the store's active preset (`p:` a preset, `v:` a saved variant), if any. */
+export declare function activeEntryId(controls: Controls<any>): string | null;
 /**
  * Resolves which preset or variant is currently active.
- * Honors `lastAppliedId` when its values still match `currentValues`, so cycling never gets
- * stuck when a saved variant has the exact same values as a built-in preset.
+ * The store's active preset (`baseId`) holds the selection however far the values drift from it.
+ * Without one, `lastAppliedId` is honoured when its values still match `currentValues`, so
+ * cycling never gets stuck when a saved variant has the exact same values as a built-in preset.
  */
-export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null): ActivePresetState;
+export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null, baseId?: string | null): ActivePresetState;
 export declare function nextPresetIndex(count: number, activeIndex: number, direction: number): number;
 export interface PresetStrip {
     readonly element: HTMLElement;
@@ -36,8 +44,12 @@ export interface PresetStrip {
     getActiveState(): ActivePresetState;
     cycle(direction: -1 | 1): void;
     selectById(id: string): void;
-    /** Saves the current values as "Variant N"; returns a status message. */
+    /** Saves the current values as "Variant N" and opens its name to typing; returns a status message. */
     save(): string;
+    /** Opens the active chip's name to typing, when it's a saved variant; returns a status message. */
+    rename(): string | undefined;
+    /** The name field while a chip's name is being typed. */
+    readonly nameField: () => HTMLInputElement | null;
     /** Deletes the selected chip when it's a saved variant; returns a status message. */
     deleteActive(): string | undefined;
     update(): void;

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

@@ -0,0 +1,117 @@
+import { type SpringValue } from "../core/spring.js";
+import type { RowContext } from "./editors.js";
+export interface Pt {
+    readonly x: number;
+    readonly y: number;
+}
+export interface MorphPlan {
+    /** For each new point, the old point it travels from, or -1: it buds. */
+    readonly from: readonly number[];
+    /** Each old point without a partner, and the new point it merges into (-1: none, it shrinks). */
+    readonly merges: readonly {
+        readonly old: number;
+        readonly into: number;
+    }[];
+}
+/**
+ * Pairs `prev`'s points with `next`'s. The first stays the first and the last the last; the inner
+ * ones pair in order, as many as both have, choosing the pairing that travels least (in the 0…1
+ * box). Only the surplus is left over: merging when there are fewer, budding when more.
+ */
+export declare function matchPoints(prev: readonly Pt[], next: readonly Pt[]): MorphPlan;
+/** `flat` (`stride` numbers per sample) resampled to `n` samples evenly along its index. */
+export declare function resample(flat: readonly number[], stride: number, n: number): number[];
+/** The y of an x, y polyline (x not decreasing) at `x`, holding its ends past them. */
+export declare function sampleAt(flat: readonly number[], x: number): number;
+/** A point on its way: its channels (x, y, then any extras, then its size), their speeds and goals. */
+export interface MorphDot {
+    readonly id: number;
+    readonly at: number[];
+    readonly vel: number[];
+    readonly to: number[];
+    /** Merging: the dot it shrinks into (-1 shrinks where it is); undefined while it's one of the points. */
+    into?: number;
+}
+/** The default travel: .3 s with no bounce. */
+export declare const MORPH_SPRING: SpringValue;
+/** How long a point merging into its neighbour takes to shrink away (s). */
+export declare const MERGE_SPRING: SpringValue;
+export interface MorphSet {
+    /** Snap there: nothing moves (a drag, a different item, reduced motion). */
+    readonly instant?: boolean;
+    /** Hold the current motion this long (ms) first, as a cascade of rows does. */
+    readonly delay?: number;
+    readonly now: number;
+}
+/**
+ * The shown samples and points of a ramp between shapes: `stride` numbers per sample, `dims`
+ * channels per point (x, y and any extras; the dot's size is kept after them). Every number has
+ * its own spring, so a change mid-flight keeps each one's speed.
+ */
+export declare class RampMorph {
+    readonly stride: number;
+    readonly dims: number;
+    /** Where a new point buds from: on the line under it as it's shown now (no size channel). */
+    private readonly origin;
+    samples: number[];
+    private sampleVel;
+    private sampleTo;
+    /** The points, in order. */
+    live: MorphDot[];
+    /** Points merging away into others. */
+    gone: MorphDot[];
+    private ids;
+    private last;
+    private pending;
+    private resting;
+    omega: number;
+    zeta: number;
+    private readonly shrink;
+    constructor(stride: number, dims: number, spring?: SpringValue, 
+    /** Where a new point buds from: on the line under it as it's shown now (no size channel). */
+    origin?: (to: readonly number[], samples: readonly number[]) => number[]);
+    get moving(): boolean;
+    /** The points' channels as the shape stands (where the live dots are going). */
+    private points;
+    private dot;
+    /** Moves toward `samples` and `points` (each `dims` channels, without the size). */
+    set(samples: readonly number[], points: readonly (readonly number[])[], o: MorphSet): void;
+    private snap;
+    private retarget;
+    /** Where a merging dot is headed: the dot it merges into, followed if that one is merging too. */
+    private target;
+    /** Advances to `now` (ms); whether anything still moves. A time already reached is a no-op. */
+    step(now: number): boolean;
+    /** The line's fastest sample (px/s), given px per unit across and up. */
+    sampleSpeed(sx: number, sy: number): number;
+}
+/**
+ * How wide (px) a moving line or point smears at `speed` px/s, by `strength` (--k-curve-blur, 0
+ * to 1): at 1, about what a half-open shutter catches in a 60 Hz frame. Under a quarter pixel it
+ * is 0, so it rests crisp.
+ */
+export declare function curveSmear(speed: number, strength: number, cap?: number): number;
+/** The widest a moving curve's line smears (px): it's thin, so less than a point does. */
+export declare const LINE_SMEAR = 4;
+/** How strongly a ramp's moving line and points smear (--k-curve-blur, 0 off to 1). */
+export declare const curveBlur: (row: HTMLElement) => number;
+/**
+ * Runs a morph on one frame loop while it moves, drawing each frame; `wake` asks the GPU for a
+ * frame too, which reads the same morph (stepping it to its own frame time first: a time already
+ * reached is a no-op, so the two never step it twice).
+ */
+export declare function morphLoop(c: RowContext<unknown>, morph: RampMorph, draw: () => void): {
+    kick(): void;
+    dispose(): void;
+};
+/**
+ * The DOM's motion blur for a ramp's line and points: an SVG Gaussian per element, its deviation
+ * the GPU smear's box width over √12 (the same spread). Off (no filter at all) at rest.
+ */
+export declare function smearFilters(doc: Document, plot: SVGSVGElement): {
+    /** The line's smear: `set(px)` blurs `path` across (0 takes the filter off). */
+    line(path: SVGPathElement): (px: number) => void;
+    /** A point's smear along its travel (px across, px down); 0, 0 takes it off. */
+    dot(node: HTMLElement, sx: number, sy: number): void;
+    drop(node: HTMLElement): void;
+};

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

@@ -1,6 +1,6 @@
 import type { CurveField, GradientField } from "../core/schema.js";
 import { type EditorRow, type RowContext } from "./editors.js";
-/** The custom properties a gradient strip's samples ride on (registered, so they transition). */
+/** The custom properties a gradient strip's samples ride on (written each frame of a morph). */
 export declare const GRADIENT_VARS: string[];
 /**
  * A gradient: a swatch strip with stop ticks in the head; a wide strip with a handle per stop, the

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

@@ -0,0 +1,43 @@
+import type { DigitPlace } from "./slider.js";
+/**
+ * Brings a readout's places to `text` (a place per character, ones first), as rolling-number
+ * does: each digit a wheel rolling through every face in the value's direction (98 → 108 rolls
+ * the tens 9 → 0 forwards), new places rising in after a short hold, cascading outward, and
+ * leaving places fading over ~65% of `ms`. `ms` 0 places it.
+ */
+export declare function syncPlaces(places: DigitPlace[], text: string, trend: number, ms: number, delay: number, entering?: boolean): void;
+/** How long a readout rolls (ms): the panel's --k-roll, 320 by default. */
+export declare function rollMs(el: Element): number;
+/** A readout's parts: text, or a number shown to `decimals` places. */
+export type ReadoutPart = string | {
+    readonly value: number;
+    readonly decimals: number;
+};
+/** A part as laid out: its element, its text, and a number's places for the canvas. */
+export interface ReelSegment {
+    readonly el: HTMLElement;
+    text: string;
+    readonly places?: DigitPlace[];
+}
+export interface RollingReadout {
+    readonly host: HTMLElement;
+    readonly segments: readonly ReelSegment[];
+    /** Everything it shows, as one string. */
+    readonly text: string;
+    /**
+     * Shows `parts`. Numbers roll over `ms` (0 places them: the first paint, the user's own hand,
+     * a landing), after `delay` ms for the row's turn in a cascade.
+     */
+    show(parts: readonly ReadoutPart[], ms: number, delay?: number): void;
+    dispose(): void;
+}
+/** The rolling readout an element holds, if it holds one (the canvas draws its segments). */
+export declare const rollingReadoutOf: (el: Element) => RollingReadout | undefined;
+/** Makes `host`'s content a rolling readout (its children are the readout's from now on). */
+export declare function rollingReadout(host: HTMLElement): RollingReadout;
+/**
+ * Sets a name-like readout (an easing's or curve's name, a hex colour). `fade` crossfades the old
+ * text out over the new, where it was; without it (the user's own hand) the text just changes.
+ * The canvas does the same, reading `data-text` and `data-fade`.
+ */
+export declare function fadeText(el: HTMLElement, text: string, fade: boolean): void;

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

@@ -0,0 +1,19 @@
+/** How deep focus sits in the panel. */
+export type FocusLevel = "row" | "card" | "panel" | "none";
+/** Where Esc takes focus from `level`: up one, past a card when the row isn't in one. */
+export declare function escapeTo(level: FocusLevel, inCard?: boolean): FocusLevel;
+/** What R and ⇧R act on: a selection always wins, then the level focused. */
+export type CommandScope = "selection" | "row" | "group" | "all";
+export declare function commandScope(level: FocusLevel, selection?: boolean): CommandScope;
+/** How a command reads from where it would land: "Random this", "Reset group", "Random all". */
+export declare function scopeLabel(verb: string, scope: CommandScope): string;
+/**
+ * The option a digit picks among `count` (0-based), or undefined when it names none: 1–9 pick
+ * the first nine, as they read.
+ */
+export declare function digitOption(key: string, count: number): number | undefined;
+/**
+ * The digit hints for a row's options: one per option that shows (up to nine), or, while they
+ * don't (a menu, a folded editor), one standing for them all ("1–5").
+ */
+export declare function digitHints(count: number, showing: boolean): string[];

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

@@ -1,5 +1,5 @@
 import type { Knob as KnobField } from "../core/schema.js";
-import { Roll, Spring, VelocityTracker } from "./motion.js";
+import { type Roll, Spring, VelocityTracker } from "./motion.js";
 export interface DigitPlace {
     ch: string;
     /** Unbounded wheel position for digits (… 9, 10, 11 …); face = position mod 10. */

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

@@ -0,0 +1,137 @@
+import type { SoundOptions, SoundTheme } from "../core/store.js";
+export type { SoundOptions, SoundTheme };
+/** A cue knobs plays for a moment in a panel (see README, Sound). */
+export type SoundCue = "step" | "limit" | "toggle" | "select" | "preset" | "random" | "mutate" | "reset" | "copy" | "undo" | "redo" | "open" | "close" | "hint" | "type" | "press" | "capture";
+/** What a play knows about its moment. */
+export interface CueDetail {
+    /** Where the value now sits in its range, 0–1: a step's pitch. */
+    readonly position?: number;
+    /** Forwards or on (1), back or off (-1). */
+    readonly direction?: number;
+    /** A firmer play: the default's notch catching. */
+    readonly strong?: boolean;
+    readonly volume?: number;
+    readonly theme?: SoundTheme;
+}
+/**
+ * One layer of a sound: a tone (`wave`) or a burst of noise through a filter. Times are seconds;
+ * `d` is how long it takes to die away by 60 dB.
+ */
+export interface SoundLayer {
+    readonly wave?: OscillatorType;
+    /** The noise's filter; `bandpass` by default. */
+    readonly filter?: BiquadFilterType;
+    /** The tone's pitch, or the noise filter's frequency (Hz). */
+    readonly f: number;
+    /** Glides `f` here over `glide` seconds. */
+    readonly to?: number;
+    readonly glide?: number;
+    readonly q?: number;
+    /** Starts this long after the play. */
+    readonly at?: number;
+    readonly a: number;
+    readonly d: number;
+    readonly p: number;
+}
+interface Recipe {
+    readonly layers: readonly SoundLayer[];
+    /** The play's level, matched across cues by ear and by loudness (1 by default). */
+    readonly gain?: number;
+    /** How much rings into the shared room (0 by default: dry). */
+    readonly room?: number;
+}
+/** 0 (unhurried) to 1 (as fast as it goes), from the time since the cue last played. */
+export declare const cadence: (sinceMs: number) => number;
+/**
+ * A cue's layers for this play: `speed` from `cadence`, `random` for its small variations (a die's
+ * clicks, a key's pitch). Pure, so tests and an offline render read the same sound.
+ */
+export declare function recipe(cue: SoundCue, detail?: CueDetail, speed?: number, random?: () => number): Recipe;
+/** The `mech` theme: the same cues with the rings all but gone and the clicks tighter. */
+export declare const themed: (layers: readonly SoundLayer[], theme: SoundTheme) => SoundLayer[];
+/** The shortest gap (ms) between two plays of a cue: closer ones are dropped. */
+export declare const GAPS: Readonly<Record<SoundCue, number>>;
+/** How a cue's plays are let through: too close are dropped; the rest report their cadence. */
+export declare function createLimiter(gaps?: Readonly<Record<string, number>>): (cue: string, now: number) => number | null;
+/** A change this long (ms) after the last one on its slider is a fresh one (a key, a click). */
+export declare const FRESH_MS = 150;
+/** A continuous slider ticks this many times across its range while it's dragged. */
+export declare const DETENTS = 24;
+/**
+ * Whether a slider's change (positions 0–1) earns a tick: a fresh change always does; within a
+ * drag, only crossing into another of its `detents` (each stop of a stepped slider, else
+ * DETENTS), so a slow drag ratchets evenly instead of ticking every pixel.
+ */
+export declare function createDetents(): (key: string, before: number, after: number, detents: number, now: number) => boolean;
+/** The parts of a field a change's cue reads. */
+interface CueField {
+    readonly kind: string;
+    readonly value?: unknown;
+    readonly min?: unknown;
+    readonly max?: unknown;
+    readonly step?: unknown;
+    readonly options?: readonly unknown[];
+}
+/**
+ * The cue for a row's value changing by hand from `before` to `after`: a step for numbers (pitched
+ * by position, firmer landing on the default), a switch's throw, a choice's detent (by direction),
+ * a captured key. `detents` is how many ticks a drag across the whole range may make.
+ */
+export declare function changeCue(field: CueField, before: unknown, after: unknown): {
+    cue: SoundCue;
+    detail: CueDetail;
+    detents: number;
+    at: number;
+    was: number;
+} | null;
+/** A mount's `sound` option as what the panel plays with, or null for silence. */
+export declare function resolveSound(option: boolean | SoundOptions | undefined): SoundOptions | null;
+/** At most this many plays sound at once; the oldest fades for a new one. */
+export declare const MAX_VOICES = 10;
+/** What the engine needs from the page, so tests can hand it a fake. */
+export interface SoundEnv {
+    readonly AudioContext?: {
+        new (): AudioContext;
+    };
+    /** Whether the page has had a user gesture yet (no context is made before one). */
+    readonly activated?: () => boolean;
+    readonly now?: () => number;
+    readonly random?: () => number;
+}
+export interface Sound {
+    /** The page's switch: on unless turned off. Panels only play with `sound` on their mount. */
+    readonly enabled: boolean;
+    enable(on?: boolean): void;
+    /** 0–1, 1 by default. */
+    readonly volume: number;
+    setVolume(volume: number): void;
+    readonly theme: SoundTheme;
+    setTheme(theme: SoundTheme): void;
+    /** Plays a cue, or layers of your own, unless sound is off or the page hasn't been touched. */
+    play(cue: SoundCue | readonly SoundLayer[], detail?: CueDetail): void;
+    /**
+     * The shared context and the bus to connect your own nodes to (volume, mute and the compressor
+     * apply), once there is one: after the first user gesture with sound wanted.
+     */
+    output(): {
+        readonly context: AudioContext;
+        readonly destination: AudioNode;
+    } | null;
+    /** Makes the context on the page's next gesture, so the first cue sounds at once. */
+    prime(doc?: Document): void;
+    /** Called when `enabled`, `volume` or `theme` change; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createSound(env?: SoundEnv): Sound;
+/** The page's sound: one switch, volume and theme for every panel (and the host's own cues). */
+export declare const sound: Sound;
+/** Where the page keeps the user's choice, in a store's storage. */
+export declare const SOUND_PREF = "knobs:sound:v1";
+/** Marks `root` as a panel that plays (a mount's resolved `sound`). */
+export declare function soundPanel(root: Element, options: SoundOptions): void;
+/** Whether the panel `from` sits in plays sounds. */
+export declare const sounds: (from: Element | null | undefined) => boolean;
+/** A row's value changing by hand in the panel `from` sits in (see `changeCue`). */
+export declare function changed(from: Element | null | undefined, key: string, field: CueField, before: unknown, after: unknown): void;
+/** Plays `cue` for a moment in the panel `from` sits in, if that panel plays sounds. */
+export declare function cue(from: Element | null | undefined, name: SoundCue, detail?: CueDetail): void;

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

@@ -3,7 +3,7 @@ import { type TokenPreset } from "../core/theme.js";
  * What DELAY times: a row's turn in a preset's cascade is set on these (see `showValues` in
  * panel.ts) rather than on the row, where the custom property would restyle all of the row.
  */
-export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
+export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-track,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
 /** Adds a token preset's stylesheet once per document. */
 export declare function injectPreset(doc: Document, preset: TokenPreset): void;
 /** The rules' `:has()` as the attributes has.ts keeps (see there for why). */

package/dist/types/panel/toolbar-grid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How many equal columns a toolbar's buttons take in `avail` px: as many as fit at the widest
+ * button's width, then balanced so the rows hold counts as even as they can (four buttons wrap as
+ * two and two, never three and one; five as three and two).
+ */
+export declare function toolbarColumns(count: number, widest: number, avail: number, gap: number): number;

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

@@ -0,0 +1 @@
+export declare const activityCss: string;

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

@@ -0,0 +1,122 @@
+/** The built-in kinds, each with its icon and tint. */
+export type ActivityKind = "you" | "agent" | "proposal" | "review" | "pr" | "build" | "blocked" | "shipped";
+export interface ActivityEvent {
+    /** Unique, and the same across `set()`: rows keep their identity and glide. */
+    readonly id: string;
+    /** A built-in kind (its icon and tint), or a name of your own with `icon` and `tint`. */
+    readonly kind?: ActivityKind | (string & {});
+    /** Who: "You", "Agent", "Ryan". */
+    readonly actor?: string;
+    /** One line; it fades at its end when cut off. A group without one says "3 updates". */
+    readonly title?: string;
+    /** Trailing, already formatted ("2m", "9:41"); it rolls when it changes. */
+    readonly time?: string;
+    /** A duration chip, "▶ 0:32": seconds, or text as it should read. */
+    readonly duration?: number | string;
+    /** Small thumbnails before the time (image URLs; four at most show). */
+    readonly thumbs?: readonly string[];
+    /** SVG markup, a glyph or a node in place of the kind's icon. */
+    readonly icon?: string | Node;
+    /** A CSS colour in place of the kind's tint. */
+    readonly tint?: string;
+    /** Makes a group that opens in place ("Agent · 3 updates"). One level deep. */
+    readonly children?: readonly ActivityEvent[];
+    /** The live or latest step: its node takes a ring. */
+    readonly current?: boolean;
+    /** Quieter: past steps, minor updates. */
+    readonly dimmed?: boolean;
+}
+export interface ActivityRow {
+    readonly id: string;
+    readonly event: ActivityEvent;
+    /** 0 for an event, 1 for one inside an open group. */
+    readonly depth: 0 | 1;
+    readonly parent: string | null;
+    /** Has children: it opens and closes. */
+    readonly group: boolean;
+    readonly expanded: boolean;
+}
+/** The rows on show: every event, and the children of open groups right after their group. */
+export declare function flattenActivity(events: readonly ActivityEvent[], expanded: ReadonlySet<string>): ActivityRow[];
+/** Every event by id, children included, with its group. */
+export declare function indexActivity(events: readonly ActivityEvent[]): Map<string, {
+    event: ActivityEvent;
+    parent: string | null;
+}>;
+export type ActivityKey = "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End";
+export declare const isActivityKey: (key: string) => key is ActivityKey;
+/**
+ * What a key does from the selected row: ↑/↓ move (from nothing, to the first or the last),
+ * Home/End go to the ends, → opens a closed group and steps into an open one, ← closes an open
+ * group and steps out of a child to its group.
+ */
+export declare function navigateActivity(rows: readonly ActivityRow[], selected: string | null, key: ActivityKey): {
+    select?: string;
+    toggle?: {
+        id: string;
+        expanded: boolean;
+    };
+};
+/**
+ * Whether the rail takes a key it navigated: ↑/↓ and Home/End whenever there are rows (at an end
+ * they hold the selection), ← and → only when they open, close or step. A ← or → that does
+ * nothing is left to the page (a review stage stepping frames, say).
+ */
+export declare function takesActivityKey(key: ActivityKey, result: {
+    select?: string;
+    toggle?: unknown;
+}, rows: number): boolean;
+/**
+ * Where the selection goes when its row leaves the rows on show: to its group when that closed
+ * over it, else nowhere.
+ */
+export declare function keepSelection(rows: readonly ActivityRow[], selected: string | null, parentOf: (id: string) => string | null | undefined): string | null;
+/** What last moved the selection: keys show it as a tint, a pointer hides it. */
+export type ActivityInput = "key" | "pointer" | "blur" | "code";
+/**
+ * Whether the selection's tint shows: keys turn it on, a pointer turns it off (a click selects
+ * with no ring), losing focus turns it off unless the page's keys drive it, and a host's
+ * `select()` leaves it as it was.
+ */
+export declare function showsSelection(showing: boolean, input: ActivityInput, keys?: "focus" | "page"): boolean;
+/** Which ids came, went and stayed between two orders of rows. */
+export declare function diffActivity(before: readonly string[], after: readonly string[]): {
+    entered: string[];
+    left: string[];
+    kept: string[];
+};
+/** Rows stacked top to bottom from `top`: each one's y, and the bottom of the last. */
+export declare function stackRows(heights: readonly number[], top?: number, gap?: number): {
+    y: number[];
+    bottom: number;
+};
+export interface RailNode {
+    /** The node's centre. */
+    readonly y: number;
+    /** How far the line keeps clear of it on each side. */
+    readonly r: number;
+}
+/**
+ * The line through the nodes, as segments between neighbours that stop clear of each node, and
+ * only within `[from, to]` (the line's ends, which glide as rows come and go). One continuous
+ * thread at rest: nothing past the last node, nothing before the first.
+ */
+export declare function railSegments(nodes: readonly RailNode[], from: number, to: number): [number, number][];
+/**
+ * The scroll while a change takes the content from height `h0` to `h1` (now at `height`): it goes
+ * from `from` to where it has to end (no further down than the shorter content allows) in step
+ * with the height, and the space stays tall enough for it meanwhile. Closing a group at the
+ * scroll's end, the rows above glide down with the drawer instead of dropping in a frame.
+ */
+export declare function holdScroll(hold: {
+    readonly from: number;
+    readonly h0: number;
+    readonly h1: number;
+}, height: number, view: number): {
+    scroll: number;
+    space: number;
+};
+/** "0:32", "4:05", "1:02:03"; text passes through as it is. */
+export declare function formatDuration(duration: number | string): string;
+/** A group's title when it has none of its own: "1 update", "3 updates". */
+export declare function groupTitle(count: number): string;

package/dist/types/ui/activity.d.ts

@@ -0,0 +1,67 @@
+import { type ActivityEvent } from "./activity-model.js";
+import { type UiLook } from "./look.js";
+export interface ActivityOptions extends UiLook {
+    readonly events: readonly ActivityEvent[];
+    /** The selected event's id. */
+    readonly selected?: string | null;
+    /** Groups open from the start. */
+    readonly expanded?: Iterable<string>;
+    /** Keys and clicks moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string, event: ActivityEvent, source: "key" | "pointer") => void;
+    /** Enter on the selected row (on a group with no `onActivate`, Enter opens or closes it). */
+    readonly onActivate?: (id: string, event: ActivityEvent) => void;
+    readonly onToggle?: (id: string, expanded: boolean) => void;
+    /** Makes the duration chip a button. */
+    readonly onPlay?: (id: string, event: ActivityEvent) => void;
+    /**
+     * Where the newest events are: `"bottom"` (the default; oldest first) or `"top"`. `add()` puts
+     * an event there, and new events slide in from that side.
+     */
+    readonly newest?: "top" | "bottom";
+    /** Stay pinned to the newest end when it was in view as events arrive (default true). */
+    readonly follow?: boolean;
+    /**
+     * Where the keys come from: `"focus"` (the default) while the rail has focus, or `"page"` from
+     * anywhere a focused field or widget doesn't take them.
+     */
+    readonly keys?: "focus" | "page";
+    /** Icons (SVG markup or a glyph) for your own kinds, or in place of built-in ones. */
+    readonly icons?: Readonly<Record<string, string>>;
+    /** Tints (CSS colours) for your own kinds, or in place of built-in ones. */
+    readonly tints?: Readonly<Record<string, string>>;
+    /** The rail's accessible name. */
+    readonly label?: string;
+    /** Shown with no events. */
+    readonly empty?: string;
+}
+export interface Activity {
+    readonly element: HTMLElement;
+    /** New events: those that stay glide to their places, new ones bloom in, gone ones soften out. */
+    set(events: readonly ActivityEvent[]): void;
+    /** One more event at the newest end. */
+    add(event: ActivityEvent): void;
+    /**
+     * New events and where the newest are, in one change: rows glide to their new places, as with
+     * `set` (flipping `newest` with the events reversed reverses the rail in place).
+     */
+    update(next: {
+        events?: readonly ActivityEvent[];
+        newest?: "top" | "bottom";
+    }): void;
+    /** Selects (opening its group); `null` clears. Doesn't call `onSelect`. */
+    select(id: string | null): void;
+    readonly selected: string | null;
+    expand(id: string, expanded?: boolean): void;
+    isExpanded(id: string): boolean;
+    focus(): void;
+    destroy(): void;
+    /** The same as `destroy`, as the other pieces name it. */
+    dispose(): void;
+}
+/**
+ * A vertical rail of events: who did what, one line each, with a kind's icon on one continuous
+ * line. Groups open in place with their children on the same line. ↑/↓, Home/End move the
+ * selection (a tint that shows only once keys move it), ←/→ close and open groups, Enter
+ * activates. New events bloom in while the rest glide; every move is an interruptible spring.
+ */
+export declare function activity(container: HTMLElement, options: ActivityOptions): Activity;

package/dist/types/ui/follow.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A diff for each set of prop values, given the values the piece was made with: the props that
+ * differ from the last values seen (at first, those at creation).
+ */
+export declare function propChanges<P extends object>(initial: P, same?: (a: unknown, b: unknown) => boolean): (next: P) => Partial<P>;
+/** Whether a diff from `propChanges` has anything in it. */
+export declare const anyChanged: (changed: object) => boolean;
+/**
+ * A timeline's changed props as one `update()`: unset ones dropped, and so are values it already
+ * has (a `time` or `playing` it reported itself, markers it handed out).
+ */
+export declare function timelineChanges<C extends Record<string, unknown>>(now: {
+    readonly time: number;
+    readonly playing: boolean;
+    readonly markers: unknown;
+    readonly ranges: unknown;
+}, changed: C): Partial<C>;

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

@@ -10,7 +10,7 @@ export { popover, type Popover, type PopoverCloseReason, type PopoverOptions } f
 export { readout, type Readout } from "./readouts.js";
 export { toast, type Toast, type ToastOptions } from "./toast.js";
 export { tooltip, tooltips, type TooltipContent, type TooltipOptions } from "./tooltip.js";
-export { split, type PaneAction, type PaneOptions, type Split, type SplitOptions, type SplitPane, } from "./split.js";
+export { split, type PaneAction, type PaneOptions, type Split, type SplitFold, type SplitOptions, type SplitPane, } from "./split.js";
 export { COLLAPSE_PAST, drag as dragDivider, parseLayout, softClamp, solve as solveSplit, type PaneSpec, type SplitDirection, type SplitLayout, } from "./split-model.js";
 export { timeline, type SeekSource, type Timeline, type TimelineMarker, type TimelineOptions, type TimelineRange, } from "./timeline.js";
 export { adjacentMarker, advance, clampView, followView, frameTime, magnet, rulerTicks, scrubTime, timeLabel, toFrame, zoomView, type Tick, type Ticks, type TimeUnits, type TimeView, } from "./timeline-model.js";
@@ -18,3 +18,7 @@ export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle
 export { applyMove, plainAccess, dropTarget, flatten, indexTree, matchLabel, navigate, select, stepMove, topmost, typeahead, validMove, virtualWindow, type DropTarget, type FlatRow, type Selection, type TreeAccess, type TreeFilter, type TreeMove, } from "./tree-model.js";
 export { bento, type Bento, type BentoItem, type BentoOptions } from "./bento.js";
 export { fitRect, FIT_MAX, motionBlur, neighbour as bentoNeighbour, planBento, rowTarget, windowOf as bentoWindow, type BentoDirection, type BentoLayout, type BentoMode, type BentoPlan, type BentoRect, } from "./bento-model.js";
+export { activity, type Activity, type ActivityOptions, } from "./activity.js";
+export { diffActivity, flattenActivity, formatDuration, indexActivity, keepSelection as keepActivitySelection, navigateActivity, railSegments, showsSelection, stackRows, type ActivityEvent, type ActivityInput, type ActivityKey, type ActivityKind, type ActivityRow, type RailNode, } from "./activity-model.js";
+export { optionPicker, type OptionPicker, type OptionPickerOptions, type PickerOption, } from "./picker.js";
+export { claimsDigit, digitPick, keepPick, stepPick } from "./picker-model.js";

package/dist/types/ui/look.d.ts

@@ -31,6 +31,15 @@ export declare const lookDefaults: {
     current: UiLook;
 };
 export declare const reducedMotion: (win: Window | null) => boolean;
+export declare const tune: <T extends {
+    omega: number;
+    zeta: number;
+}>(s: T, m: {
+    readonly omega: number;
+    readonly zeta: number;
+}) => T;
+/** Whether `target` is an editable field or select that takes typed keys. */
+export declare const isTypingTarget: (t: EventTarget | null) => boolean;
 /**
  * Tells the page's GPU overlay that layout moved (a pane resizing, collapsing or sliding): it
  * reads rects afresh on its next frame, so a panel inside a pane keeps up.

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

@@ -0,0 +1 @@
+export declare const pickerCss: string;