@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,137 @@
+import type { Ring } from "../core/readout.js";
+import { type Rgba } from "./rgba.js";
+export type PlotOp = {
+    readonly t: "line";
+    readonly pts: readonly number[];
+    readonly color: Rgba;
+    readonly width: number;
+}
+/** The area between a line and `base` (a y), fading to `fade` × its alpha at the base. */
+ | {
+    readonly t: "area";
+    readonly pts: readonly number[];
+    readonly base: number;
+    readonly color: Rgba;
+    readonly fade: number;
+} | {
+    readonly t: "rect";
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly color: Rgba;
+    readonly r?: number;
+} | {
+    readonly t: "dot";
+    readonly x: number;
+    readonly y: number;
+    readonly r: number;
+    readonly color: Rgba;
+};
+/** The colours readouts draw with, read from the tokens. */
+export interface Palette {
+    readonly accent: Rgba;
+    readonly text: Rgba;
+    readonly label: Rgba;
+    readonly dim: Rgba;
+    readonly line: Rgba;
+    readonly surfaceHi: Rgba;
+    readonly warn: Rgba;
+    readonly critical: Rgba;
+    /** Corner radius (px); 0 squares the bars. */
+    readonly radius: number;
+}
+/** Series colours after the first (the accent). */
+export declare const SERIES: string[];
+/** A number as text: `decimals` places, else fewer as it grows (2 under 10, 1 under 100, 0 past). */
+export declare function formatNumber(v: number, decimals?: number): string;
+/** A step of 1, 2 or 5 × 10ⁿ near `span / 4`: a scale snaps to these, so it moves rarely. */
+export declare function niceStep(span: number): number;
+/**
+ * The range a history is drawn on: its samples' extent (and `keep`, such as thresholds), snapped
+ * out to a nice step, with fixed bounds where given. A flat history gets room around it.
+ */
+export declare function fitRange(lo: number, hi: number, fixed?: {
+    min?: number;
+    max?: number;
+}, keep?: readonly number[]): [number, number];
+/**
+ * A scale that eases to each new range on a spring, interruptibly, instead of jumping. The span
+ * eases in log space, so a line rescaling by 5× moves at an even pace rather than mostly at once.
+ */
+export declare class EasedRange {
+    private readonly lo;
+    private readonly span;
+    private placed;
+    private goal;
+    /** Sets where it's headed; `snap` places it there at once (the first range, reduced motion). */
+    to(lo: number, hi: number, snap?: boolean): void;
+    /** Steps both bounds; true while they're still moving. */
+    step(dt: number): boolean;
+    get value(): [number, number];
+    get target(): [number, number];
+}
+/**
+ * A history's samples as points across `w`, newest at the right edge; a history that isn't full
+ * yet starts part way across. NaN samples break the line: each run is its own list.
+ */
+export declare function historyRuns(ring: Ring, capacity: number, range: readonly [number, number], w: number, top: number, bottom: number): number[][];
+/** The sample index under `x` (local px), or -1. */
+export declare function sampleAt(x: number, w: number, capacity: number, length: number): number;
+export interface SparkScene {
+    readonly ops: PlotOp[];
+}
+/** A sparkline: a soft area under its line, the newest sample dotted; hovered, its min and max. */
+export declare function sparkScene(o: {
+    ring: Ring;
+    capacity: number;
+    range: readonly [number, number];
+    w: number;
+    h: number;
+    color: Rgba;
+    palette: Palette;
+    hover: boolean;
+}): PlotOp[];
+/** Dashes along a horizontal line at `y`: 4 px on, 3 off. */
+export declare function dashes(y: number, x0: number, x1: number, color: Rgba, on?: number, off?: number): PlotOp[];
+export interface GraphLine {
+    readonly ring: Ring;
+    readonly color: Rgba;
+    readonly area: boolean;
+}
+/** A graph: thresholds dashed, each series' area and line, a baseline; hovered, a crosshair. */
+export declare function graphScene(o: {
+    lines: readonly GraphLine[];
+    capacity: number;
+    range: readonly [number, number];
+    thresholds: readonly {
+        value: number;
+        color: Rgba;
+    }[];
+    w: number;
+    h: number;
+    palette: Palette;
+    hover: number;
+}): PlotOp[];
+/** The colour a meter's value takes: the accent, the warning colour from `warn`, critical past `critical`. */
+export declare function levelOf(v: number, warn?: number, critical?: number, prev?: number, band?: number): 0 | 1 | 2;
+export declare function levelColor(p: Palette, level: number): Rgba;
+/** A meter: a slim track with its fill (eased), or cells; indeterminate, a band that sweeps across. */
+export declare function meterScene(o: {
+    /** 0–1, as eased. */
+    fraction: number;
+    /** 0 (ok) to 2 (critical), as eased, for a continuous bar's colour. */
+    level: number;
+    min: number;
+    max: number;
+    warn?: number;
+    critical?: number;
+    segments?: number;
+    /** 0–1 through the sweep, or undefined when the value is known. */
+    sweep?: number;
+    w: number;
+    h: number;
+    palette: Palette;
+}): PlotOp[];
+/** Paints ops on a 2D canvas (already scaled to CSS px). */
+export declare function paintOps(ctx: CanvasRenderingContext2D, ops: readonly PlotOp[]): void;

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

@@ -0,0 +1,85 @@
+import type { ReadoutState, Ring } from "../core/readout.js";
+import type { ReadoutField } from "../core/schema.js";
+import { type UiLook } from "./look.js";
+import { type Palette, type PlotOp } from "./readout-model.js";
+import { type Rgba } from "./rgba.js";
+export type ReadoutFont = "value" | "mono" | "meta";
+/** A piece of text the GPU overlay draws in place of the DOM's (which it hides). */
+export interface TextItem {
+    readonly el: HTMLElement;
+    /** Drawn left to right from the element's left edge, or right-aligned at its right edge. */
+    readonly parts: readonly {
+        readonly text: string;
+        readonly color: Rgba;
+    }[];
+    readonly font: ReadoutFont;
+    readonly align: "left" | "right";
+    /** Clipped to this element (a scroller). */
+    readonly clip?: HTMLElement;
+}
+/** Ops in px from `el`'s top-left corner. */
+export interface PlotLayer {
+    readonly el: HTMLElement;
+    readonly ops: readonly PlotOp[];
+}
+export interface ButtonItem {
+    readonly el: HTMLButtonElement;
+    /** `chip`: a filter chip (pressed shows a wash); `pill`: a filled pill (jump to latest). */
+    readonly look: "chip" | "plain" | "pill";
+    readonly alpha: number;
+}
+export interface ReadoutView {
+    readonly element: HTMLElement;
+    readonly field: ReadoutField;
+    /** Where the row's ↑↓ stop lands. */
+    readonly focusTarget: HTMLElement;
+    /** Graphics, text and buttons as the last frame drew them (the GPU overlay draws these). */
+    layers(): readonly PlotLayer[];
+    texts(): readonly TextItem[];
+    buttons(): readonly ButtonItem[];
+    /** Something arrived in the readout's state. */
+    notify(): void;
+    /** A new field of the same kind (a descriptor swap). */
+    retune(field: ReadoutField): void;
+    /** Paints its canvas again (after a GPU overlay stopped drawing it). */
+    refresh(): void;
+    dispose(): void;
+}
+export interface ReadoutEnv {
+    readonly doc: Document;
+    readonly field: ReadoutField;
+    readonly state: ReadoutState;
+    /** The row's label; block readouts (graph, table, log) put it in their head. */
+    readonly label?: HTMLElement;
+    /** True while a GPU overlay draws this readout: the canvas stays blank. */
+    gpu?(): boolean;
+    /** Called after a frame changed what the readout shows. */
+    wake?(): void;
+}
+export declare function paletteOf(el: HTMLElement, now?: number): Palette;
+/** A value's text and unit, as the field formats it. */
+export declare function readoutText(field: ReadoutField, v: unknown): {
+    num: string;
+    unit: string;
+};
+/** A time as the log shows it: a clock for epoch times, else seconds (a `performance.now()`). */
+export declare function logTime(t: number): string;
+/** Builds the view for a readout field. */
+export declare function createReadout(env: ReadoutEnv): ReadoutView;
+export type { Ring };
+export interface Readout {
+    readonly element: HTMLElement;
+    /** A value, a sample or rows, as `controls.watch` takes them; `null` clears it. */
+    push(value: unknown): void;
+    /** The latest value pushed. */
+    readonly value: unknown;
+    dispose(): void;
+}
+/**
+ * A readout on its own, outside a panel: `readout(sparkline({ unit: "ms" }))`, put its element
+ * anywhere and `push` values to it. It sleeps when nothing arrives, as it does in a panel.
+ */
+export declare function readout(field: ReadoutField, options?: UiLook & {
+    readonly doc?: Document;
+    readonly label?: string;
+}): Readout;

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

@@ -0,0 +1,6 @@
+export type Rgba = readonly [number, number, number, number];
+/** Any CSS colour (hex, rgb(), oklch(), color-mix(), calc() inside) as RGBA; `fallback` if not one. */
+export declare function parseCssColor(raw: string, fallback?: Rgba): Rgba;
+export declare const withAlpha: (c: Rgba, k: number) => Rgba;
+export declare const mixRgba: (a: Rgba, b: Rgba, t: number) => Rgba;
+export declare const rgbaCss: (c: Rgba) => string;

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

@@ -0,0 +1,40 @@
+import { type JSX } from "solid-js";
+import { type Bento as BentoHandle, type BentoOptions } from "./bento.js";
+import { type Split as SplitHandle, type SplitOptions } from "./split.js";
+import { type Timeline as TimelineHandle, type TimelineOptions } from "./timeline.js";
+import { type Tree as TreeHandle, type TreeOptions } from "./tree.js";
+export type SplitProps = SplitOptions & {
+    /** One element per pane, in the panes' order; each goes into its pane's body. */
+    children?: JSX.Element;
+    onReady?: (split: SplitHandle) => void;
+};
+/**
+ * `split()` as a component: each child goes into its pane. The split is made once; children
+ * that change move into their panes.
+ */
+export declare function Split(props: SplitProps): JSX.Element;
+export type TreeProps<T> = TreeOptions<T> & {
+    onReady?: (tree: TreeHandle<T>) => void;
+};
+/**
+ * `tree()` as a component. New `items` update it in place (rows glide); `selection` and
+ * `filter` follow their props; callbacks always call the latest props.
+ */
+export declare function Tree<T>(props: TreeProps<T>): JSX.Element;
+export type TimelineProps = TimelineOptions & {
+    onReady?: (timeline: TimelineHandle) => void;
+};
+/**
+ * `timeline()` as a component. `time`, `playing`, `markers`, `ranges`, `duration`, `fps`,
+ * `units` and `speed` follow their props (a `time` it reported itself is left alone); callbacks
+ * always call the latest props.
+ */
+export declare function Timeline(props: TimelineProps): JSX.Element;
+export type BentoProps = BentoOptions & {
+    onReady?: (bento: BentoHandle) => void;
+};
+/**
+ * `bento()` as a component. New `items` update it in place (tiles glide); `picks` follows its
+ * prop; callbacks always call the latest props.
+ */
+export declare function Bento(props: BentoProps): JSX.Element;

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

@@ -0,0 +1,81 @@
+export type SplitDirection = "row" | "column";
+export interface PaneSpec {
+    readonly id: string;
+    /** Pixels. Panes without one share what the sized panes leave, by their last sizes. */
+    readonly size?: number;
+    /** Pixels; 48 unless set. */
+    readonly min?: number;
+    readonly max?: number;
+    /** Collapses to its rail (or header) from its divider, header or `collapse()`. */
+    readonly collapsible?: boolean;
+    /** Starts collapsed (a saved layout wins). */
+    readonly collapsed?: boolean;
+}
+/** What a split saves and reports: each pane's size and whether it's collapsed. */
+export interface SplitLayout {
+    readonly sizes: Readonly<Record<string, number>>;
+    readonly collapsed: Readonly<Record<string, boolean>>;
+}
+export declare const DEFAULT_MIN = 48;
+/** How far past its minimum a collapsible pane is dragged before it collapses. */
+export declare const COLLAPSE_PAST = 40;
+export declare const paneMin: (p: PaneSpec) => number;
+export declare const paneMax: (p: PaneSpec) => number;
+/** Panes that fill: those without a `size`, or else the last one. */
+export declare function flexible(panes: readonly PaneSpec[]): Set<string>;
+/**
+ * Approaches a bound without passing it: 1:1 until `knee` px short of it, then easing in, so a
+ * drag slows into its limit instead of stopping dead (and never bands past it).
+ */
+export declare function softClamp(x: number, min: number, max: number, knee?: number): number;
+export interface SolveInput {
+    readonly panes: readonly PaneSpec[];
+    /** Last sizes (px); flexible panes use theirs as shares. */
+    readonly sizes: Readonly<Record<string, number>>;
+    readonly collapsed: Readonly<Record<string, boolean>>;
+    /** The container's length along the split, dividers included. */
+    readonly total: number;
+    /** Room each divider takes. */
+    readonly divider?: number;
+    /** A collapsed pane's length (its rail or header). */
+    readonly rail?: (id: string) => number;
+    /** Sizes held exactly, whatever else is true (a pane mid-collapse). */
+    readonly fixed?: Readonly<Record<string, number>>;
+}
+/**
+ * Lays panes out along the split. Sized panes keep their size (clamped to min and max) and
+ * flexible ones share the rest by their last sizes; when there isn't room for every flexible
+ * pane's minimum, sized panes give way, the largest first, down to their own minimums.
+ */
+export declare function solve(input: SolveInput): Record<string, number>;
+export interface DragResult {
+    /** New sizes for the two panes beside the divider. */
+    readonly sizes: Record<string, number>;
+    /** A collapsible pane dragged well past its minimum collapses; dragged back, it opens. */
+    readonly collapse?: {
+        readonly id: string;
+        readonly collapsed: boolean;
+    };
+}
+/**
+ * Moves the divider after pane `index` by `delta` px from where the drag began (`start` holds
+ * every pane's size then). The panes on either side trade the distance, each slowing into its
+ * own bounds.
+ */
+export declare function drag(panes: readonly PaneSpec[], start: Readonly<Record<string, number>>, index: number, delta: number, collapsed?: Readonly<Record<string, boolean>>): DragResult;
+/** Steps a divider by keys: the pane before it grows by `delta`, within both panes' bounds. */
+export declare function nudge(panes: readonly PaneSpec[], sizes: Readonly<Record<string, number>>, index: number, delta: number): Record<string, number>;
+/**
+ * Which pane a divider collapses (Enter, its button): the sized one beside it, else the
+ * collapsible one, preferring the pane at the edge.
+ */
+export declare function collapsibleSide(panes: readonly PaneSpec[], index: number): string | undefined;
+/**
+ * Which edge a pane collapses toward: panes before the first flexible pane go to the start,
+ * the rest to the end.
+ */
+export declare function edgeOf(panes: readonly PaneSpec[], id: string): "start" | "end";
+/** A saved layout, kept only where it names known panes with sane values. */
+export declare function parseLayout(raw: unknown, panes: readonly PaneSpec[]): SplitLayout | undefined;
+/** A layout as saved: sizes rounded to a tenth of a pixel. */
+export declare function serializeLayout(layout: SplitLayout): string;

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

@@ -0,0 +1,75 @@
+import { type StoragePort } from "../core/storage.js";
+import { type UiLook } from "./look.js";
+import { type PaneSpec, type SplitDirection, type SplitLayout } from "./split-model.js";
+export interface PaneAction {
+    readonly id?: string;
+    readonly label: string;
+    /** SVG markup, text, or a node of your own. */
+    readonly icon?: string | Node;
+    readonly pressed?: boolean;
+    /** Shown in its tooltip as key chips (the split doesn't bind it). */
+    readonly shortcut?: string;
+    run(event: MouseEvent): void;
+}
+export interface PaneOptions extends PaneSpec {
+    /** A header with this title (a dock); collapsed, it's the rail's label too. */
+    readonly title?: string;
+    /** The collapsed rail's label, when it isn't the title. */
+    readonly rail?: string;
+    /** Beside the title, dimmed: a count or a word. */
+    readonly count?: string | number;
+    /** Icon buttons at the header's end. */
+    readonly actions?: readonly PaneAction[];
+    /** The body scrolls (on by default for panes with a header). */
+    readonly scroll?: boolean;
+    /** Content for the body (or fill `split.pane(id).body` yourself). */
+    readonly element?: Node;
+}
+export interface SplitOptions extends UiLook {
+    readonly direction?: SplitDirection;
+    readonly panes: readonly PaneOptions[];
+    /** Saves sizes and collapsed panes under this id (with `storage`). */
+    readonly id?: string;
+    /** Where layouts are saved: localStorage unless set; `null` saves nothing. */
+    readonly storage?: StoragePort | null;
+    /** After every change of size or collapse, drag frames and springs included. */
+    readonly onLayout?: (layout: SplitLayout) => void;
+    /**
+     * Header actions, collapse buttons and the rails of collapsed panes take codes in the page's
+     * hint mode (`s`), on by default; a code presses its button.
+     */
+    readonly hints?: boolean;
+}
+export interface SplitPane {
+    readonly id: string;
+    /** The pane itself. */
+    readonly element: HTMLElement;
+    /** Where content goes. */
+    readonly body: HTMLElement;
+    readonly header: HTMLElement | undefined;
+    /** Its size along the split (px), as shown now. */
+    readonly size: number;
+    readonly collapsed: boolean;
+    collapse(collapsed?: boolean): void;
+    resize(size: number): void;
+    title(text: string, count?: string | number): void;
+}
+export interface Split {
+    readonly element: HTMLElement;
+    pane(id: string): SplitPane;
+    layout(): SplitLayout;
+    /** Collapses or opens a pane (springing, interruptibly); no argument toggles. */
+    collapse(id: string, collapsed?: boolean): void;
+    resize(id: string, size: number): void;
+    /** Back to the panes' own sizes, one pane or all. */
+    reset(id?: string): void;
+    dispose(): void;
+}
+/**
+ * Resizable panes along a row or a column, divided by hairlines with a wider grip. Drag a divider
+ * to resize (each pane slows into its min and max), double-click it to reset, or focus it and use
+ * the arrow keys (⇧ for bigger steps) and Enter to collapse. Collapsing springs the pane down to a
+ * slim rail, or to its header in a column, which opens it again. Sizes persist and restore before
+ * the first paint. Splits nest: call `split` on another split's pane body.
+ */
+export declare function split(container: HTMLElement, options: SplitOptions): Split;

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

@@ -0,0 +1,83 @@
+/** The visible window: `start` seconds at the left edge, `span` seconds across. */
+export interface TimeView {
+    readonly start: number;
+    readonly span: number;
+}
+export type TimeUnits = "seconds" | "frames";
+export interface Tick {
+    readonly t: number;
+    readonly label: string;
+}
+export interface Ticks {
+    readonly major: readonly Tick[];
+    readonly minor: readonly number[];
+    /** Seconds between major ticks. */
+    readonly step: number;
+}
+/** A frame's time, rounded to the nearest frame. */
+export declare const toFrame: (t: number, fps: number) => number;
+export declare const frameTime: (t: number, fps: number) => number;
+/** "1.5s", "12s", "1:05", "1:02:05" for seconds; the frame number for frames. */
+export declare function timeLabel(t: number, units: TimeUnits, fps: number, step?: number): string;
+/**
+ * Ticks for a view `width` px wide: major ticks at least `minGap` px apart on a nice step (whole
+ * frames in frame units), labelled; minor ones between them, down to single frames once a frame
+ * is `frameGap` px wide.
+ */
+export declare function rulerTicks(view: TimeView, width: number, o: {
+    fps: number;
+    units?: TimeUnits;
+    minGap?: number;
+    frameGap?: number;
+}): Ticks;
+/** Clamps a view to `[0, duration]` with a little room (`pad` of the span) at either end. */
+export declare function clampView(view: TimeView, duration: number, o?: {
+    minSpan?: number;
+    pad?: number;
+}): TimeView;
+/** Zooms by `factor` (above 1 zooms in) keeping time `at` under the same point. */
+export declare function zoomView(view: TimeView, factor: number, at: number): TimeView;
+/** The view panned so `t` sits at least `margin` (of the span) inside it, or unchanged. */
+export declare function followView(view: TimeView, t: number, margin?: number): TimeView;
+/**
+ * The playhead's soft pull toward a marker while it's scrubbed: within `radius` px it follows the
+ * pointer by a curve that's flat at the marker (it sticks there) and meets the pointer at the
+ * edge, with no jump. Returns the time to show and the marker it rests on, if any.
+ */
+export declare function magnet(raw: number, stops: readonly number[], pxPerSec: number, radius?: number, stick?: number): {
+    t: number;
+    stop: number | null;
+};
+/**
+ * Where a scrub lands: on a marker it's resting on, else on the nearest frame (with `frames`),
+ * clamped to `[0, duration]`.
+ */
+export declare function scrubTime(raw: number, o: {
+    duration: number;
+    fps: number;
+    pxPerSec: number;
+    stops?: readonly number[];
+    frames?: boolean;
+    radius?: number;
+}): {
+    t: number;
+    shown: number;
+    stop: number | null;
+};
+/** The marker before (`-1`) or after (`1`) time `t`, by a frame's margin, or null. */
+export declare function adjacentMarker<M extends {
+    readonly time: number;
+}>(markers: readonly M[], t: number, dir: 1 | -1, fps: number): M | null;
+/** Advances playing time by `dt`, looping inside `loop` (or the whole) when asked. */
+export declare function advance(t: number, dt: number, o: {
+    duration: number;
+    loop?: {
+        start: number;
+        end: number;
+    } | null;
+    repeat?: boolean;
+}): {
+    t: number;
+    ended: boolean;
+    wrapped: boolean;
+};

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

@@ -0,0 +1,76 @@
+import { type UiLook } from "./look.js";
+import { type TimeUnits, type TimeView } from "./timeline-model.js";
+export interface TimelineMarker {
+    readonly id: string;
+    /** Seconds. */
+    readonly time: number;
+    readonly label?: string;
+    /** A colour of its own (CSS); the accent otherwise. */
+    readonly color?: string;
+}
+export interface TimelineRange {
+    readonly id: string;
+    readonly start: number;
+    readonly end: number;
+    readonly label?: string;
+    /** Playback loops inside it (`I` / `O` make the `"loop"` range, which loops). */
+    readonly loop?: boolean;
+}
+export type SeekSource = "scrub" | "key" | "marker" | "play" | "code";
+export interface TimelineOptions extends UiLook {
+    /** Seconds. */
+    readonly duration: number;
+    readonly time?: number;
+    readonly playing?: boolean;
+    /** Frames per second (30): frame steps, frame labels, and where scrubs land. */
+    readonly fps?: number;
+    /** What the ruler counts in (`"seconds"`). */
+    readonly units?: TimeUnits;
+    readonly markers?: readonly TimelineMarker[];
+    readonly ranges?: readonly TimelineRange[];
+    /** Scrubs land on frames and stick to markers (`true`); `{ frames, markers }` picks. */
+    readonly snap?: boolean | {
+        readonly frames?: boolean;
+        readonly markers?: boolean;
+    };
+    /** Playback speed (1). */
+    readonly speed?: number;
+    /** Playback starts over at the end when there's no loop range (`false`: it stops). */
+    readonly repeat?: boolean;
+    readonly label?: string;
+    /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
+    onSeek?(time: number, source: SeekSource): void;
+    onPlay?(playing: boolean): void;
+    /** Markers were added, moved, renamed or removed (the whole list). */
+    onMarkers?(markers: readonly TimelineMarker[]): void;
+    /** Ranges were set, moved or cleared (the whole list). */
+    onRanges?(ranges: readonly TimelineRange[]): void;
+    /** Playback passed a marker. */
+    onCross?(marker: TimelineMarker): void;
+    /**
+     * Play, each marker and the playhead take codes in the page's hint mode (`s`), on by default:
+     * a marker's code jumps to it, the playhead's focuses the timeline.
+     */
+    readonly hints?: boolean;
+}
+export interface Timeline {
+    readonly element: HTMLElement;
+    readonly time: number;
+    readonly playing: boolean;
+    readonly markers: readonly TimelineMarker[];
+    readonly ranges: readonly TimelineRange[];
+    readonly view: TimeView;
+    seek(time: number): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** New duration, markers, ranges, fps, units or speed; the time and view stay. */
+    update(next: Partial<Omit<TimelineOptions, "onSeek" | "onPlay" | "onMarkers" | "onRanges" | "onCross">>): void;
+    /** Shows the whole duration (animated). */
+    fit(): void;
+    /** Zooms by `factor` (above 1 zooms in) around a time (the playhead's by default). */
+    zoom(factor: number, at?: number): void;
+    focus(): void;
+    dispose(): void;
+}
+export declare function timeline(container: HTMLElement, options: TimelineOptions): Timeline;

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

@@ -0,0 +1,19 @@
+import { type UiLook } from "./look.js";
+export interface ToastOptions {
+    /** Ms it stays (3200; errors 6000). */
+    readonly linger?: number;
+    readonly tone?: "info" | "warn" | "error";
+    /** A button in the pill (Undo, say). */
+    readonly action?: {
+        readonly label: string;
+        run(): void;
+    };
+    readonly look?: UiLook;
+    /** Where it lives, to take that element's tokens (a page); the overlay layer by default. */
+    readonly within?: HTMLElement;
+    readonly doc?: Document;
+}
+export interface Toast {
+    dismiss(): void;
+}
+export declare function toast(message: string, options?: ToastOptions): Toast;

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

@@ -0,0 +1,19 @@
+import type { UiLook } from "./look.js";
+import { type Placement } from "./overlay-model.js";
+export interface TooltipOptions {
+    /** A key or combination (`"Mod+K"`, `"Space"`): shown as chips after the text. */
+    readonly shortcut?: string;
+    /** `top` by default. */
+    readonly placement?: Placement;
+    /** Ms over the target before it shows (500); a hand-off shows at once. */
+    readonly delay?: number;
+    readonly look?: UiLook;
+}
+/** Text, a function read each time it shows, or text with options. */
+export type TooltipContent = string | (() => string) | ({
+    readonly text: string | (() => string);
+} & TooltipOptions);
+/** Shows `content` over `el` after a pause (or on keyboard focus). Returns the remover. */
+export declare function tooltip(el: HTMLElement, content: TooltipContent, options?: TooltipOptions): () => void;
+/** Turns on `data-tip` (and `data-tip-shortcut`, `data-tip-placement`) tooltips in a document. */
+export declare function tooltips(doc?: Document): void;