@kitlangton/knobs 0.4.0-next.1 → 0.4.0-next.10

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

@@ -0,0 +1,249 @@
+export type HistoryTone = "good" | "warn" | "bad" | "info" | "dim";
+export type HistoryProvenance = "verified" | "inferred";
+/** A small tag that backs a claim: a PR, a commit, a log, as a link or not. */
+export interface HistoryEvidence {
+    readonly label: string;
+    readonly href?: string;
+}
+/** A stretch of a lane in one state: "v1 works", "v2 broken". */
+export interface HistorySpan {
+    readonly id?: string;
+    /** ISO date (`2026-09-19`), or as a page writes it (`"Sep 19, 2026"`). */
+    readonly from: string;
+    /** Left out: still so today. */
+    readonly to?: string;
+    /** A key in `states`, or a word of its own. */
+    readonly state: string;
+    /** Its tag at the end, in place of the state's (`"31d broken"`). */
+    readonly label?: string;
+    /** Its detail's title, in place of "lane · state". */
+    readonly title?: string;
+    readonly detail?: string;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence?: readonly HistoryEvidence[];
+    /** A step it's about, for `onJump`. */
+    readonly step?: string;
+}
+/** A row of the chart: a channel or a track, with its spans. */
+export interface HistoryLane {
+    readonly id: string;
+    readonly label: string;
+    readonly spans?: readonly HistorySpan[];
+}
+/** A dated moment: a commit, a release, a deletion. */
+export interface HistoryEvent {
+    readonly id?: string;
+    /** ISO, or as written: "Apr 9, 2026", "Oct 14–16, 2026", "May 7–8". */
+    readonly date: string;
+    /** Where it ran over days: its last day. */
+    readonly to?: string;
+    /** The lane it sits on (`"code"` by default). */
+    readonly lane?: string;
+    readonly title: string;
+    readonly detail?: string;
+    /** Its mark: a commit a dot, a release a diamond, a deletion a cross, an audit a triangle. */
+    readonly type?: "commit" | "release" | "deletion" | "channel" | "audit" | (string & {});
+    readonly tone?: HistoryTone;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence?: readonly HistoryEvidence[];
+    readonly step?: string;
+}
+/** A faint labelled stretch behind every lane: a phase. */
+export interface HistoryBand {
+    readonly from: string;
+    readonly to?: string;
+    readonly label: string;
+}
+/** What a span's state means: its name in the legend, its colour and its tag (`{d}` the days). */
+export interface HistoryState {
+    readonly label?: string;
+    readonly tone?: HistoryTone;
+    /** `"{d}d"` (the default), words of its own (`"v1"`), or `""` for none. */
+    readonly tag?: string;
+}
+/** The walkthrough's older shape: events under headings. */
+export interface HistoryGroup {
+    readonly heading?: string;
+    readonly summary?: string;
+    readonly events?: readonly HistoryEvent[];
+    readonly rows?: readonly HistoryEvent[];
+}
+/** What `history()` draws: plain JSON. */
+export interface HistoryData {
+    readonly axis?: {
+        readonly from?: string;
+        readonly to?: string;
+        readonly today?: string;
+    };
+    readonly lanes?: readonly HistoryLane[];
+    readonly events?: readonly HistoryEvent[];
+    readonly bands?: readonly HistoryBand[];
+    readonly states?: Readonly<Record<string, HistoryState>>;
+    /** The walkthrough's older shape: each group's events go on the code lane under a band. */
+    readonly groups?: readonly HistoryGroup[];
+}
+/** Days since 1970-01-01 (UTC): every date in the model. */
+export type Day = number;
+export interface HyItem {
+    readonly id: string;
+    readonly kind: "event" | "span";
+    readonly lane: string;
+    readonly from: Day;
+    readonly to: Day;
+    /** A span still running today. */
+    readonly open: boolean;
+    readonly title: string;
+    readonly detail?: string;
+    readonly tone: HistoryTone;
+    readonly type?: string;
+    readonly inferred: boolean;
+    readonly provenance?: HistoryProvenance;
+    readonly source?: string;
+    readonly evidence: readonly HistoryEvidence[];
+    readonly step?: string;
+    /** A span's state key. */
+    readonly state?: string;
+    /** A span's end tags, longest first: its own or the state's, then the days alone. */
+    readonly tags: readonly string[];
+}
+export interface HyLane {
+    readonly id: string;
+    readonly label: string;
+    readonly spans: readonly HyItem[];
+    readonly events: readonly HyItem[];
+}
+export interface HyBand {
+    readonly from: Day;
+    readonly to: Day;
+    readonly label: string;
+}
+export interface HyState {
+    readonly key: string;
+    readonly label: string;
+    readonly tone: HistoryTone;
+}
+export interface HistoryModel {
+    readonly from: Day;
+    readonly to: Day;
+    readonly today: Day;
+    readonly lanes: readonly HyLane[];
+    /** Every event, in the order ←/→ walk them. */
+    readonly events: readonly HyItem[];
+    readonly bands: readonly HyBand[];
+    /** The states the spans use, in the order they first appear. */
+    readonly states: readonly HyState[];
+    /** The event types used, in the order they first appear. */
+    readonly types: readonly string[];
+    /** Whether anything is marked inferred, and anything verified: the legend needs both. */
+    readonly inferred: boolean;
+    readonly verified: boolean;
+    readonly items: ReadonlyMap<string, HyItem>;
+}
+export declare const dayOf: (y: number, m: number, d: number) => Day;
+export declare const todayDay: (now?: number) => Day;
+/**
+ * A date as written, as whole days: ISO (`2026-04-09`, a time after it ignored), or `"Apr 9, 2026"`,
+ * `"Oct 14–16, 2026"`, `"Jun 26 – Jul 2, 2026"`; with no year, `year`. Null when it's neither.
+ */
+export declare function parseDay(text: string, year?: number): {
+    from: Day;
+    to: Day;
+    year?: number;
+} | null;
+/** `"Jun 26, 2026"`. */
+export declare function formatDay(day: Day): string;
+/** One day, or a range as short as it reads: `"Oct 14–16, 2026"`, `"Sep 19, 2026 – today"`. */
+export declare function formatRange(from: Day, to: Day, open?: boolean): string;
+/** `"1 day"`, `"31 days"`. */
+export declare const formatDays: (n: number) => string;
+/** A state's colour from its name when `states` doesn't give one. */
+export declare function guessTone(state: string): HistoryTone;
+/** A group heading as a band's label: its number and a trailing "(Apr – May 2026)" go. */
+export declare const bandLabel: (heading: string) => string;
+/**
+ * The walkthrough's older shape in the new one: every group's events on the code lane, each group
+ * with a heading a faint band from its first event to its last. Dates with no year take the year
+ * of the event before (or the first one written).
+ */
+export declare function fromGroups(groups: readonly HistoryGroup[], today: Day): {
+    events: HistoryEvent[];
+    bands: HistoryBand[];
+};
+/** A day as ISO `2026-04-09`. */
+export declare function iso(day: Day): string;
+/** The document filled in: whole days, lanes with their spans and events, the axis and the order. */
+export declare function normalizeHistory(data: HistoryData, now?: Day): HistoryModel;
+/** The marks drawn from the start: the rest wait for the pointer or "Show …". */
+export declare const DEFAULT_MARKS: readonly string[];
+/**
+ * The events held back until asked for: those with a type that isn't in `marks`. Untyped events
+ * always show, and where holding back would leave no mark at all, none are.
+ */
+export declare function quietEvents(events: readonly HyItem[], marks: readonly string[] | "all"): Set<string>;
+/** What the toggle shows: `"commits"`, `"commits and findings"`. */
+export declare function quietLabel(events: readonly HyItem[], quiet: ReadonlySet<string>): string;
+/** The order ←/→ walk: by date, then lane (top first), then as written. */
+export declare function eventOrder(events: readonly {
+    item: HyItem;
+    index: number;
+    laneIndex: number;
+}[]): HyItem[];
+/**
+ * The event ←/→ land on from `current`: the next or the one before, stopping at the ends; from
+ * nothing (or a span), → the first and ← the last.
+ */
+export declare function stepEvent(order: readonly HyItem[], current: string | null, dir: 1 | -1, 
+/** Where the selection is when it isn't in `order` (a held-back mark): carry on from there. */
+at?: Day): HyItem | null;
+/** Where a day sits across `width` (pixels), and the day at an x. */
+export declare function dayScale(from: Day, to: Day, width: number): {
+    x: (day: number) => number;
+    day: (x: number) => number;
+    /** As a fraction of the width, for `left: n%`. */
+    f: (day: number) => number;
+};
+export interface MonthTick {
+    readonly day: Day;
+    /** `"Apr"`, or the year on January. */
+    readonly label: string;
+}
+/**
+ * A tick on the first of each month inside the axis, thinned to every 2, 3, 6 or 12 months until
+ * neighbours sit at least `minGap` pixels apart. January says its year.
+ */
+export declare function monthTicks(from: Day, to: Day, width: number, minGap?: number): MonthTick[];
+/**
+ * Which labels to draw, left to right: each starts at its `x` and is `w` wide, and one is left out
+ * where it would touch the one before (within `gap`), a reserved box (today's label), or run past
+ * `width`.
+ */
+export declare function fitLabels(labels: readonly {
+    x: number;
+    w: number;
+}[], width: number, reserved?: readonly {
+    x0: number;
+    x1: number;
+}[], gap?: number): boolean[];
+/** A span clipped to the axis, and which ends were cut; null when it's outside it. */
+export declare function clipSpan(from: Day, to: Day, axisFrom: Day, axisTo: Day): {
+    from: Day;
+    to: Day;
+    clipStart: boolean;
+    clipEnd: boolean;
+} | null;
+/**
+ * Where a span's tag goes: the longest of `widths` (pixels, longest first) that fits inside the
+ * bar with `pad` either side, else one that fits after it in `roomAfter`; else none.
+ */
+export declare function fitTag(widths: readonly number[], spanWidth: number, roomAfter: number, pad?: number): {
+    index: number;
+    place: "inside" | "after";
+} | null;
+/** Each band's label room: from its start to its end or the next band's start, if sooner. */
+export declare function bandRoom(bands: readonly HyBand[], x: (day: Day) => number): number[];
+/** The event nearest `day` within `tolerance` days, else null. */
+export declare function nearestEvent(events: readonly HyItem[], day: number, tolerance: number): HyItem | null;
+/** The first sentence of a detail: a tooltip's one line. */
+export declare function firstSentence(text: string | undefined): string;

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

@@ -0,0 +1,38 @@
+import { type HistoryData, type HistoryModel } from "./history-model.js";
+import { type UiLook } from "./look.js";
+export type { HistoryBand, HistoryData, HistoryEvent, HistoryEvidence, HistoryGroup, HistoryLane, HistoryProvenance, HistorySpan, HistoryState, HistoryTone, } from "./history-model.js";
+export interface HistoryOptions extends UiLook {
+    /** Lanes of spans and events (or the walkthrough's `groups` of events): plain JSON. */
+    readonly data: HistoryData;
+    /** The selected event or span's id. */
+    readonly selected?: string | null;
+    /** Clicks and keys moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string | null) => void;
+    /** Draws "Go to step" in the detail of anything with a `step`, and Enter on it. */
+    readonly onJump?: (step: string) => void;
+    /** Its accessible name. */
+    readonly label?: string;
+    /** Under this width (px) lane labels sit above their lanes instead of beside them (560). */
+    readonly narrow?: number;
+    /**
+     * The event types marked from the start (releases and deletions, or `"all"`); the rest show
+     * while the pointer is on their lane, and all of them behind a "Show commits" toggle.
+     */
+    readonly marks?: readonly string[] | "all";
+}
+export interface History {
+    readonly element: HTMLElement;
+    /** The data filled in: whole days, lanes, the axis and the order ←/→ walk. */
+    readonly model: HistoryModel;
+    readonly selected: string | null;
+    /** Selects an event or span (`null` clears); doesn't call `onSelect`. */
+    select(id: string | null): void;
+    set(data: HistoryData): void;
+    focus(): void;
+    dispose(): void;
+    /** The same as `dispose`. */
+    destroy(): void;
+}
+/** Adds the history's stylesheet once per document. */
+export declare function injectHistoryStyles(doc: Document): void;
+export declare function history(container: HTMLElement, options: HistoryOptions): History;

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

@@ -0,0 +1,40 @@
+declare const PATHS: {
+    readonly arrowLeft: "M224,128a8,8,0,0,1-8,8H59.31l58.35,58.34a8,8,0,0,1-11.32,11.32l-72-72a8,8,0,0,1,0-11.32l72-72a8,8,0,0,1,11.32,11.32L59.31,120H216A8,8,0,0,1,224,128Z";
+    readonly arrowUpRight: "M200,64V168a8,8,0,0,1-16,0V83.31L69.66,197.66a8,8,0,0,1-11.32-11.32L172.69,72H88a8,8,0,0,1,0-16H192A8,8,0,0,1,200,64Z";
+    readonly arrowSquareOut: "M224,104a8,8,0,0,1-16,0V59.32l-66.33,66.34a8,8,0,0,1-11.32-11.32L196.68,48H152a8,8,0,0,1,0-16h64a8,8,0,0,1,8,8Zm-40,24a8,8,0,0,0-8,8v72H48V80h72a8,8,0,0,0,0-16H48A16,16,0,0,0,32,80V208a16,16,0,0,0,16,16H176a16,16,0,0,0,16-16V136A8,8,0,0,0,184,128Z";
+    readonly arrowCounterClockwise: "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 arrowUDownLeft: "M232,112a64.07,64.07,0,0,1-64,64H51.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,11.32,11.32L51.31,160H168a48,48,0,0,0,0-96H80a8,8,0,0,1,0-16h88A64.07,64.07,0,0,1,232,112Z";
+    readonly arrowsHorizontal: "M136,40V216a8,8,0,0,1-16,0V40a8,8,0,0,1,16,0ZM96,120H35.31l18.35-18.34A8,8,0,0,0,42.34,90.34l-32,32a8,8,0,0,0,0,11.32l32,32a8,8,0,0,0,11.32-11.32L35.31,136H96a8,8,0,0,0,0-16Zm149.66,2.34-32-32a8,8,0,0,0-11.32,11.32L220.69,120H160a8,8,0,0,0,0,16h60.69l-18.35,18.34a8,8,0,0,0,11.32,11.32l32-32A8,8,0,0,0,245.66,122.34Z";
+    readonly caretDown: "M213.66,101.66l-80,80a8,8,0,0,1-11.32,0l-80-80A8,8,0,0,1,53.66,90.34L128,164.69l74.34-74.35a8,8,0,0,1,11.32,11.32Z";
+    readonly caretLeft: "M165.66,202.34a8,8,0,0,1-11.32,11.32l-80-80a8,8,0,0,1,0-11.32l80-80a8,8,0,0,1,11.32,11.32L91.31,128Z";
+    readonly caretRight: "M181.66,133.66l-80,80a8,8,0,0,1-11.32-11.32L164.69,128,90.34,53.66a8,8,0,0,1,11.32-11.32l80,80A8,8,0,0,1,181.66,133.66Z";
+    readonly caretUp: "M213.66,165.66a8,8,0,0,1-11.32,0L128,91.31,53.66,165.66a8,8,0,0,1-11.32-11.32l80-80a8,8,0,0,1,11.32,0l80,80A8,8,0,0,1,213.66,165.66Z";
+    readonly check: "M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l-56-56a8,8,0,0,1,11.32-11.32L96,188.69,218.34,66.34a8,8,0,0,1,11.32,11.32Z";
+    readonly checkCircle: "M173.66,98.34a8,8,0,0,1,0,11.32l-56,56a8,8,0,0,1-11.32,0l-24-24a8,8,0,0,1,11.32-11.32L112,148.69l50.34-50.35A8,8,0,0,1,173.66,98.34ZM232,128A104,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 circle: "M128,24A104,104,0,1,0,232,128,104.11,104.11,0,0,0,128,24Zm0,192a88,88,0,1,1,88-88A88.1,88.1,0,0,1,128,216Z";
+    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 cornersIn: "M152,96V48a8,8,0,0,1,16,0V88h40a8,8,0,0,1,0,16H160A8,8,0,0,1,152,96ZM96,152H48a8,8,0,0,0,0,16H88v40a8,8,0,0,0,16,0V160A8,8,0,0,0,96,152Zm112,0H160a8,8,0,0,0-8,8v48a8,8,0,0,0,16,0V168h40a8,8,0,0,0,0-16ZM96,40a8,8,0,0,0-8,8V88H48a8,8,0,0,0,0,16H96a8,8,0,0,0,8-8V48A8,8,0,0,0,96,40Z";
+    readonly cornersOut: "M216,48V88a8,8,0,0,1-16,0V56H168a8,8,0,0,1,0-16h40A8,8,0,0,1,216,48ZM88,200H56V168a8,8,0,0,0-16,0v40a8,8,0,0,0,8,8H88a8,8,0,0,0,0-16Zm120-40a8,8,0,0,0-8,8v32H168a8,8,0,0,0,0,16h40a8,8,0,0,0,8-8V168A8,8,0,0,0,208,160ZM88,40H48a8,8,0,0,0-8,8V88a8,8,0,0,0,16,0V56H88a8,8,0,0,0,0-16Z";
+    readonly folder: "M216,72H130.67L102.93,51.2a16.12,16.12,0,0,0-9.6-3.2H40A16,16,0,0,0,24,64V200a16,16,0,0,0,16,16H216.89A15.13,15.13,0,0,0,232,200.89V88A16,16,0,0,0,216,72Zm0,128H40V64H93.33L123.2,86.4A8,8,0,0,0,128,88h88Z";
+    readonly keyboard: "M224,48H32A16,16,0,0,0,16,64V192a16,16,0,0,0,16,16H224a16,16,0,0,0,16-16V64A16,16,0,0,0,224,48Zm0,144H32V64H224V192Zm-16-64a8,8,0,0,1-8,8H56a8,8,0,0,1,0-16H200A8,8,0,0,1,208,128Zm0-32a8,8,0,0,1-8,8H56a8,8,0,0,1,0-16H200A8,8,0,0,1,208,96ZM72,160a8,8,0,0,1-8,8H56a8,8,0,0,1,0-16h8A8,8,0,0,1,72,160Zm96,0a8,8,0,0,1-8,8H96a8,8,0,0,1,0-16h64A8,8,0,0,1,168,160Zm40,0a8,8,0,0,1-8,8h-8a8,8,0,0,1,0-16h8A8,8,0,0,1,208,160Z";
+    readonly magnifyingGlass: "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 magnifyingGlassMinus: "M152,112a8,8,0,0,1-8,8H80a8,8,0,0,1,0-16h64A8,8,0,0,1,152,112Zm77.66,117.66a8,8,0,0,1-11.32,0l-50.06-50.07a88.11,88.11,0,1,1,11.31-11.31l50.07,50.06A8,8,0,0,1,229.66,229.66ZM112,184a72,72,0,1,0-72-72A72.08,72.08,0,0,0,112,184Z";
+    readonly magnifyingGlassPlus: "M152,112a8,8,0,0,1-8,8H120v24a8,8,0,0,1-16,0V120H80a8,8,0,0,1,0-16h24V80a8,8,0,0,1,16,0v24h24A8,8,0,0,1,152,112Zm77.66,117.66a8,8,0,0,1-11.32,0l-50.06-50.07a88.11,88.11,0,1,1,11.31-11.31l50.07,50.06A8,8,0,0,1,229.66,229.66ZM112,184a72,72,0,1,0-72-72A72.08,72.08,0,0,0,112,184Z";
+    readonly microphone: "M128,176a48.05,48.05,0,0,0,48-48V64a48,48,0,0,0-96,0v64A48.05,48.05,0,0,0,128,176ZM96,64a32,32,0,0,1,64,0v64a32,32,0,0,1-64,0Zm40,143.6V240a8,8,0,0,1-16,0V207.6A80.11,80.11,0,0,1,48,128a8,8,0,0,1,16,0,64,64,0,0,0,128,0,8,8,0,0,1,16,0A80.11,80.11,0,0,1,136,207.6Z";
+    readonly paperPlaneRight: "M231.87,114l-168-95.89A16,16,0,0,0,40.92,37.34L71.55,128,40.92,218.67A16,16,0,0,0,56,240a16.15,16.15,0,0,0,7.93-2.1l167.92-96.05a16,16,0,0,0,.05-27.89ZM56,224a.56.56,0,0,0,0-.12L85.74,136H144a8,8,0,0,0,0-16H85.74L56.06,32.16A.46.46,0,0,0,56,32l168,95.83Z";
+    readonly pencilSimple: "M227.31,73.37,182.63,28.68a16,16,0,0,0-22.63,0L36.69,152A15.86,15.86,0,0,0,32,163.31V208a16,16,0,0,0,16,16H92.69A15.86,15.86,0,0,0,104,219.31L227.31,96a16,16,0,0,0,0-22.63ZM92.69,208H48V163.31l88-88L180.69,120ZM192,108.68,147.31,64l24-24L216,84.68Z";
+    readonly repeat: "M24,128A72.08,72.08,0,0,1,96,56H204.69L194.34,45.66a8,8,0,0,1,11.32-11.32l24,24a8,8,0,0,1,0,11.32l-24,24a8,8,0,0,1-11.32-11.32L204.69,72H96a56.06,56.06,0,0,0-56,56,8,8,0,0,1-16,0Zm200-8a8,8,0,0,0-8,8,56.06,56.06,0,0,1-56,56H51.31l10.35-10.34a8,8,0,0,0-11.32-11.32l-24,24a8,8,0,0,0,0,11.32l24,24a8,8,0,0,0,11.32-11.32L51.31,200H160a72.08,72.08,0,0,0,72-72A8,8,0,0,0,224,120Z";
+    readonly sidebar: "M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM40,56H80V200H40ZM216,200H96V56H216V200Z";
+    readonly x: "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";
+};
+export type IconName = keyof typeof PATHS;
+/** Every glyph's name. */
+export declare const ICON_NAMES: readonly IconName[];
+/**
+ * A Phosphor regular glyph as SVG markup, in `currentColor`: 16 px for controls, 12 px (`small`)
+ * inline. Decorative (`aria-hidden`); label the control it sits in.
+ */
+export declare function icon(name: IconName, options?: {
+    readonly small?: boolean;
+}): string;
+export {};

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

@@ -8,15 +8,19 @@ export { commandPalette, type Command, type CommandPalette, type CommandPaletteO
 export { contextMenu, menu, type ContextMenu, type ContextMenuOptions, type Menu, type MenuCloseReason, type MenuEntry, type MenuItem, type MenuOptions, } from "./menu.js";
 export { popover, type Popover, type PopoverCloseReason, type PopoverOptions } from "./popover.js";
 export { readout, type Readout } from "./readouts.js";
+export { icon, ICON_NAMES, type IconName } from "./icons.js";
+export { planPill, pillBoxOf, pillProgress, pillRadius, pillSpring, selectionPill, type PillBox, type PillPlan, type SelectionPill, type SelectionPillOptions, } from "./selection-pill.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 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 TimelineListener, 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";
+export { adjacentMarker, advance, CATCH_UP, clampView, currentMarker, followView, frameTime, magnet, moveHead, rulerTicks, scrubTime, minutes, timeLabel, toFrame, zoomView, type HeadPosition, type Tick, type Ticks, type TimeUnits, type TimeView, } from "./timeline-model.js";
 export { compare, COMPARE_FFMPEG, type Compare, type CompareLoop, type CompareMode, type CompareOptions, type CompareSource, type CompareView, type MediaKind, type ZoomRegion, } from "./compare.js";
 export { compareStrip, type CompareStrip, type CompareStripOptions } from "./compare-strip.js";
-export { compareLayout, frameMidpoint, frameOf, letterbox, mediaKind, meanAbsDiff, requestSeek, seeked, seekTime, stripColumns, stripPeaks, syncAction, wipeAt, wipeGrab, wipeKey, wipeX, zoomAbout, type CompareLayout, type SeekState, type StripColumn, type SyncAction, } from "./compare-model.js";
+export { player, type Player, type PlayerChapter, type PlayerOptions } from "./player.js";
+export { history, type History, type HistoryBand, type HistoryData, type HistoryEvent, type HistoryEvidence, type HistoryGroup, type HistoryLane, type HistoryOptions, type HistoryProvenance, type HistorySpan, type HistoryState, type HistoryTone, } from "./history.js";
+export { compareLayout, compareModes, frameMidpoint, frameOf, gripTop, letterbox, mediaKind, meanAbsDiff, modeForKey, requestSeek, seamLabels, seeked, seekTime, stripColumns, stripPeaks, syncAction, wipeAt, wipeGrab, wipeKey, wipeX, zoomAbout, type CompareLayout, type SeekState, type StripColumn, type SyncAction, } from "./compare-model.js";
 export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle } from "./tree.js";
 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 { codeDiff, diffCounts, diffReview, diffStatus, type CodeDiff, type CodeDiffOptions, type CodeDiffUpdate, type DiffLayout, type DiffLines, type DiffReview, type DiffReviewOptions, } from "./diff.js";
@@ -28,5 +32,5 @@ export { diffActivity, flattenActivity, formatDuration, indexActivity, keepSelec
 export { optionPicker, type OptionPicker, type OptionPickerOptions, type PickerOption, } from "./picker.js";
 export { claimsDigit, digitPick, keepPick, stepPick } from "./picker-model.js";
 export { tasteTest, walkthrough, type TasteTest, type TasteTestOptions, type Walkthrough, type WalkthroughOptions, } from "./walkthrough.js";
-export { mediaSlot, type MediaSlot, type MediaSlotOptions } from "./walkthrough-media.js";
-export { collectFeedback, feedbackMarkdown, inlineMarkdown, normalizeWalkthrough, readState as readWalkthroughState, walkthroughProgress, type ContextEvent, type FeedbackItem, type FeedbackNote, type FeedItem, type MediaContext, type NoteContext, type WalkInk, type WalkNote, type WalkVoice, type WalkthroughQA, type WalkthroughUpdate, type WalkPage, type WalkStep, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughMedia, type WalkthroughMeta, type WalkthroughOption, type WalkthroughSection, type WalkthroughSource, type WalkthroughState, type WalkthroughStatus, type WalkthroughStep, } from "./walkthrough-model.js";
+export { decision, facts, mediaSlot, type DecisionOptions, type FactsOptions, type MediaSlot, type MediaSlotOptions, type StepLinks, } from "./walkthrough-media.js";
+export { collectFeedback, feedbackMarkdown, inlineMarkdown, plainMarkdown, normalizeWalkthrough, readState as readWalkthroughState, stackLayout, walkthroughProgress, type ContextEvent, type FeedbackItem, type FeedbackNote, type FeedItem, type MediaContext, type NoteContext, type StackLayout, type StackRow, type WalkInk, type WalkNote, type WalkVoice, type WalkthroughQA, type WalkthroughUpdate, type WalkPage, type WalkStep, type WalkthroughChapter, type WalkthroughDecisionOption, type WalkthroughFact, type WalkthroughFactGroup, type WalkthroughFacts, type WalkthroughDoc, type WalkthroughEvidence, type WalkthroughFeedback, type WalkthroughHistoryEvent, type WalkthroughHistoryGroup, type WalkthroughMedia, type WalkthroughMeta, type WalkthroughOption, type WalkthroughSection, type WalkthroughSource, type WalkthroughStackItem, type WalkthroughState, type WalkthroughStatus, type WalkthroughStep, type WalkthroughTableCell, type WalkthroughTableColumn, type WalkthroughTableRow, type WalkthroughTone, type WalkthroughPR, type WalkthroughAnnotation, } from "./walkthrough-model.js";

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

@@ -0,0 +1 @@
+export declare const playerCss = "\n:where(.knobs-player,.knobs-player *){box-sizing:border-box}\n.knobs-ui.knobs-player{--_kp-stage:var(--_k-compare-stage);display:flex;flex-direction:column;gap:6px;width:100%;outline:none;\n  font:var(--_k-weight) var(--_k-type-small)/var(--_k-leading-small) var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-player,.knobs-ui.knobs-player[data-nested]{--_kp-stage:var(--k-compare-stage,transparent)}\n.knobs-player-frame{position:relative;width:100%;aspect-ratio:var(--kp-aspect,16/9);overflow:hidden;border-radius:var(--_k-radius-panel);background:var(--_kp-stage)}\n.knobs-player[data-frame=\"flat\"] .knobs-player-frame{border-radius:0}\n.knobs-player-media{position:absolute;inset:0;display:block;width:100%;height:100%;margin:0;padding:0;border:0;object-fit:contain;\n  opacity:0;filter:blur(4px);transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}\n.knobs-player[data-ready] .knobs-player-media{opacity:1;filter:none}\n.knobs-player-line{flex:none;min-height:0}\n/* The timeline's own stylesheet is look.ts's; what the player's row and every timeline share\n   about the hand is set here, after it. No hand cursor anywhere (the arrow, or a resize where it\n   resizes); hover is a quiet fill (fill-hover), in at once (hover-in, 0 ms), out easing. */\n.knobs-ui .knobs-tl-play,.knobs-ui.knobs-timeline :is(.knobs-tl-pin,.knobs-tl-rlabel),\n.knobs-ui.knobs-timeline[data-dragging] .knobs-tl-marker :is(.knobs-tl-pin,.knobs-tl-mlabel){cursor:default}\n.knobs-ui .knobs-tl-play:hover,.knobs-tl-edge:hover::after,.knobs-tl-rlabel:hover,.knobs-tl-track:hover .knobs-tl-hover,\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover .knobs-tl-segs{transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* The line's row: a minimal play/pause (the filled pair, a 28px target, no fill at rest), then\n   the line, centred on it. */\n.knobs-ui.knobs-timeline[data-variant=\"line\"]{gap:4px;align-items:center}\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-transport{display:flex}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play{width:28px;height:28px;min-width:28px;min-height:28px;border-radius:var(--_k-radius);background:transparent;color:var(--_k-fg-2);\n  transition:background calc(var(--_k-hover-out) * 1ms),transform .15s var(--_ku-ease)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"][data-playing] .knobs-tl-play{background:transparent;color:var(--_k-fg-2)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track{cursor:default;transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n";

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

@@ -0,0 +1,51 @@
+import { type UiLook } from "./look.js";
+import { type Timeline } from "./timeline.js";
+/** A chapter: where it starts (seconds) and its name. */
+export interface PlayerChapter {
+    readonly label: string;
+    readonly start: number;
+    readonly id?: string;
+}
+export interface PlayerOptions extends UiLook {
+    readonly src: string;
+    readonly poster?: string;
+    /** A WebVTT file, shown by default. */
+    readonly captions?: string;
+    /** One segment of the line each, named under the pointer. */
+    readonly chapters?: readonly PlayerChapter[];
+    /** Starts over at the end (true). */
+    readonly loop?: boolean;
+    /** True by default. */
+    readonly muted?: boolean;
+    /** Width over height before the video loads (16/9). */
+    readonly aspect?: number;
+    /** Frames per second, for stepping with `,` and `.` (30). */
+    readonly fps?: number;
+    readonly label?: string;
+    /** The line's play key and playhead take codes in the page's hint mode (on by default). */
+    readonly hints?: boolean;
+    /** Played or paused, at `time` (seconds). */
+    onPlay?(playing: boolean, time: number): void;
+    /** Sought by the hand (the line, a key, a chapter) or code, at rest. */
+    onSeek?(time: number): void;
+}
+export interface Player {
+    readonly element: HTMLElement;
+    readonly video: HTMLVideoElement;
+    readonly timeline: Timeline;
+    /** Seconds. */
+    readonly time: number;
+    readonly playing: boolean;
+    readonly duration: number;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** `glide`: a jump the hand didn't make; the line catches up while the video lands at once. */
+    seek(time: number, options?: {
+        readonly glide?: boolean;
+    }): void;
+    seekBy(seconds: number): void;
+    focus(): void;
+    dispose(): void;
+}
+export declare function player(container: HTMLElement, options: PlayerOptions): Player;

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

@@ -0,0 +1,6 @@
+import type { UiLook } from "./look.js";
+/**
+ * A review piece's look: the theme it's given, else the theme of the knobs element it sits in,
+ * else the review theme (quiet, true black, visible hairlines) rather than the panel's glass.
+ */
+export declare function reviewLook<T extends UiLook>(options: T, container?: Element): T;

package/dist/types/ui/review-options.d.ts

@@ -0,0 +1,28 @@
+import { type WalkFact, type WalkFactGroup } from "./walkthrough-model.js";
+/** Facts as a `<dl>` per group under its heading: terms in a gutter, values beside them. */
+export declare function renderFacts(doc: Document, groups: readonly WalkFactGroup[]): HTMLElement;
+export interface OptionView {
+    /** "Option 1". */
+    readonly number: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly recommended: boolean;
+    readonly facts?: readonly WalkFact[];
+}
+/**
+ * One option's column: its head (a `div`, or the `button` given for picking), its sentence, then
+ * `media(tile)` and its facts.
+ */
+export declare function optionTile(doc: Document, o: OptionView, options?: {
+    readonly head?: HTMLElement;
+    readonly media?: (tile: HTMLElement) => void;
+}): {
+    readonly tile: HTMLElement;
+    readonly head: HTMLElement;
+    readonly kicker: HTMLElement;
+};
+/**
+ * Lays `tiles` out in `root` as columns that fill whole rows, marking each with its column and
+ * row for the hairlines, again whenever `root`'s width changes. Returns the cleanup.
+ */
+export declare function layoutOptions(root: HTMLElement, tiles: readonly HTMLElement[]): () => void;

package/dist/types/ui/selection-pill-css.d.ts

@@ -0,0 +1 @@
+export declare const selectionPillCss = "\n.knobs-pick-pill,.knobs-pick-copy{position:absolute;left:0;top:0;width:0;height:0;pointer-events:none;transition:opacity .1s linear}\n.knobs-pick-pill{background:var(--_k-fill-selected);will-change:transform}\n.knobs-pick-copy{overflow:hidden;will-change:transform}\n.knobs-pick-copy-rows{position:absolute;left:0;top:0;width:0;height:0}\n:is(.knobs-pick-pill,.knobs-pick-copy)[data-off]{opacity:0}\n";

package/dist/types/ui/selection-pill.d.ts

@@ -0,0 +1,106 @@
+import { type SpringValue } from "../core/spring.js";
+/** A box in the container's coordinates (its padding box, scrolled content included). */
+export interface PillBox {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface SelectionPillOptions {
+    /** The selected row, or null for none. Read on `update()`. */
+    selected(): HTMLElement | null;
+    /**
+     * The rows the pill moves between, for the bright copy. The container's own children by
+     * default (the pill's parts left out).
+     */
+    rows?(): Iterable<HTMLElement>;
+    /** A row's corner radius (px); its computed `border-top-left-radius` by default. */
+    radius?(row: HTMLElement): number;
+    /** The bright copy of the rows clipped to the pill (true). */
+    copy?: boolean;
+    /**
+     * The copy's text colour (`var(--_k-fg)`), set on each copied row; a row's parts with colours
+     * of their own keep them unless you restyle them under `.knobs-pick-copy`.
+     */
+    color?: string;
+    /** The spring it travels on (`SPRINGS.default`, the state spring); 1.4× as long past 400 px. */
+    spring?: SpringValue;
+}
+export interface SelectionPill {
+    /** The fill. */
+    readonly element: HTMLElement;
+    /**
+     * Reads the selection and the rows again (after a click, a key, new content). The pill travels
+     * to a new row; `snap` lands it there instead (content swapped wholesale, a row that moved with
+     * its list).
+     */
+    update(options?: {
+        readonly snap?: boolean;
+    }): void;
+    dispose(): void;
+}
+/** The state spring for a trip of `distance` px, 1.4× as long past 400 px. */
+export declare function pillSpring(distance: number, base?: SpringValue): SpringValue;
+/** Where `row` sits in `container`'s coordinates, from their client rects and its scroll. */
+export declare function pillBoxOf(row: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, container: {
+    left: number;
+    top: number;
+    scrollLeft: number;
+    scrollTop: number;
+    clientLeft: number;
+    clientTop: number;
+}): PillBox;
+/**
+ * The radius on the way from one row to the next: it follows the height when the rows differ in
+ * height (so the pill keeps each row's proportion), else the trip's progress `k`.
+ */
+export declare function pillRadius(from: {
+    readonly h: number;
+    readonly r: number;
+}, to: {
+    readonly h: number;
+    readonly r: number;
+}, h: number, k: number): number;
+/** How far along a trip from `from` to `to` the box `at` is (1 when there's no trip). */
+export declare function pillProgress(from: PillBox, to: PillBox, at: PillBox): number;
+export type PillPlan = {
+    readonly kind: "hide";
+} | {
+    readonly kind: "stay";
+} | {
+    readonly kind: "land";
+    readonly box: PillBox;
+} | {
+    readonly kind: "travel";
+    readonly box: PillBox;
+    readonly spring: SpringValue;
+};
+/**
+ * What the pill does next. Nothing selected: it fades out in place. Shown for the first time, after
+ * a fade-out, on first paint, with reduced motion or asked to snap: it lands on the row. Otherwise
+ * it travels there from wherever it is (mid-trip included), on a spring for the distance.
+ */
+export declare function planPill(state: {
+    readonly shown: boolean;
+    readonly at: PillBox | null;
+    readonly target: PillBox | null;
+}, next: PillBox | null, flags?: {
+    readonly first?: boolean;
+    readonly reduced?: boolean;
+    readonly snap?: boolean;
+    readonly spring?: SpringValue;
+}): PillPlan;
+/** Whether two boxes overlap. */
+export declare const boxesMeet: (a: PillBox, b: PillBox) => boolean;
+/** The box around both. */
+export declare const boxUnion: (a: PillBox, b: PillBox) => PillBox;
+/**
+ * The selection pill over `container`'s rows. The container is positioned if it isn't; its rows
+ * may be anywhere in it (flex children, absolutely placed, scrolled), as the pill measures them.
+ */
+export declare function selectionPill(container: HTMLElement, options: SelectionPillOptions): SelectionPill;

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

@@ -81,3 +81,30 @@ export declare function advance(t: number, dt: number, o: {
     ended: boolean;
     wrapped: boolean;
 };
+/** A jump the hand didn't make catches up on this: quick, no bounce. */
+export declare const CATCH_UP: {
+    readonly duration: 0.15;
+    readonly bounce: 0;
+};
+/** Where the playhead is drawn (`x`) and where it's going (`target`), in seconds. */
+export interface HeadPosition {
+    readonly x: number;
+    readonly target: number;
+}
+/**
+ * The playhead's next move. A `jump` (a chapter or marker click, a loop's wrap, a press on the
+ * lane away from it, play from elsewhere, a glide from code) catches up from where it's drawn when
+ * it's more than `minGap` seconds away. A `follow` (a drag, the clock, a step) lands 1:1; during a
+ * catch-up it shifts both ends, so it follows the hand and the remaining offset settles on its own.
+ */
+export declare function moveHead(head: HeadPosition, t: number, motion: "jump" | "follow", catching: boolean, minGap?: number): HeadPosition & {
+    readonly catching: boolean;
+};
+/** The last marker at or before `t` (half a frame's leeway): the current chapter. */
+export declare function currentMarker<M extends {
+    readonly time: number;
+}>(markers: readonly M[], t: number, fps: number): M | null;
+/** A time as a player shows it: `m:ss` (`1:05`), `h:mm:ss` past an hour. */
+export declare function minutes(t: number): string;
+/** A line's segment bounds: 0, each chapter start inside the length (once each), the end. */
+export declare function chapterBounds(times: readonly number[], duration: number): number[];

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

@@ -45,6 +45,18 @@ export interface TimelineOptions extends UiLook {
         readonly step: number;
         readonly shift: number;
     };
+    /**
+     * `"editor"` (the default): a ruler with labels over a lane of markers to add, drag and name,
+     * zoomed and panned by the wheel. `"lane"`: one slim lane under a compare or a video, with ticks
+     * and no labels, markers as faint chapter ticks (the current one in text colour) and nothing to
+     * edit. A pinch, ⌘/ctrl-wheel or = and - zoom it around the pointer, a sideways scroll pans it,
+     * both following the hand 1:1; a double-click or 0 fits it again. An up-and-down wheel is left
+     * to the page. `"line"`: a player's row under a video or a compare: a minimal play/pause button,
+     * then a single thin progress line, one segment per chapter with a small gap between,
+     * each filling as the time passes it, thicker under the pointer; click or drag anywhere on it
+     * to seek, 1:1, and the chapter and time under the pointer show over it. Zooms as a lane does.
+     */
+    readonly variant?: "editor" | "lane" | "line";
     readonly label?: string;
     /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
     onSeek?(time: number, source: SeekSource): void;
@@ -82,7 +94,10 @@ export interface Timeline {
     readonly markers: readonly TimelineMarker[];
     readonly ranges: readonly TimelineRange[];
     readonly view: TimeView;
-    /** `glide`: the playhead springs there (the time, and what it drives, land at once). */
+    /**
+     * `glide`: a jump the hand didn't make (a chapter's click, say): the playhead catches up from
+     * where it is on a quick spring; the time, and what it drives, land at once.
+     */
     seek(time: number, options?: {
         readonly glide?: boolean;
     }): void;

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

@@ -64,8 +64,9 @@ export interface TreeOptions<T> extends UiLook {
      */
     readonly hints?: boolean;
     /**
-     * The selected row (one) shows as one highlight that glides to the next row selected, on the
-     * rows' own spring, instead of each row lighting in place. Several selected rows light in place.
+     * The selected row (one) shows as the selection pill (`selectionPill`): one highlight that slides
+     * to the next row selected on the state spring, the row's text sharp and bright under it, instead
+     * of each row lighting in place. Several selected rows light in place.
      */
     readonly glide?: boolean;
 }