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

package/README.md

@@ -1328,6 +1328,68 @@ Click or `Enter` zooms a tile to fill the view, aspect-fit and centred: one cont
 
 The handle has `update(items)`, `zoom(id | null)`, `zoomed`, `active`, `focus(id?)`, `picks`, `pick(ids)`, `plan`, `moving`, `stats()` (the frame loop's script time) and `dispose()`; `onZoom` and `onActive` report changes. It takes the pieces' tokens and `restyle`, in dark and light; tiles round at `--k-ui-bento-radius` (3px), square under `--k-frame: flat`; `--k-ui-bento-bg` and `--k-ui-scrim` set the page under the tiles and the zoom. `planBento(aspects, { width, height, … })` is the layout on its own, with `bentoNeighbour`, `bentoWindow` and `fitRect`. `Bento` in `knobs/ui/react` and `knobs/ui/solid` follows `items` and `picks`. The demo is `examples/ideas.html` (`?n=500` for a big set, `?groups`, `?hero=3`, `?perf` for a frame-time readout, `?bench` to scroll and zoom on its own and report).
 
+### Walkthrough
+
+```ts
+import { walkthrough, type WalkthroughDoc } from "knobs/ui"
+
+const doc: WalkthroughDoc = {
+  id: "2026-10-19-onboarding-prs",
+  title: "Onboarding audit: before / after",
+  sections: [
+    {
+      title: "Refresh models globally",
+      link: "https://github.com/anomalyco/opencode/pull/57148",
+      status: "ready",
+      steps: [{ title: "Desktop model picker", media: { kind: "compare", before: "a.mp4", after: "b.mp4" } }],
+    },
+  ],
+}
+const w = walkthrough(container, { doc, onFeedback: (fb) => send(fb) })
+```
+
+**`walkthrough(container, { doc })`** is the page an agent writes to show its work: a plain document (JSON) of sections and steps, each step one card holding a caption, its media and what it asks (a note, or a pick between options). Notes come from a bar docked at the bottom, typed, spoken or inked, each carrying what was on show (a video's time and chapter, a compare's loop and zoom, a diff's file) and a short log of what led up to it; `onFeedback`, `w.feedback` and `w.markdown()` hand it back. `j` / `k` move between steps, `←` / `→` seek, `f` goes full window, `n` writes a note, `1`–`9` pick. Media is a bare URL (a video or picture), or `compare`, `video`, `image`, `diff`, `code`, `terminal`, `metric`, `callout`, `text`, `history`, `stack`, `table`, or `mount` (your own, `(el) => cleanup`; the one that isn't JSON). A step's card is the surface, so media inside draw no card of their own. Wherever media name a step (`step` on a history event, a stack item or a table cell) they take its key, id or number (`"1.2"`), and clicking goes there as `j` / `k` do. The demo is `examples/walkthrough.html`.
+
+**`history`**: dated events down a spine, a tone dot each (`good`, `warn`, `bad`, `info`, `dim`), under quiet group headings. `provenance` says whether an event was seen in the record (`"verified"`) or worked out from behaviour (`"inferred"`, a ring for a dot and a dashed tag), and `source` where (`"verified · git"`). `evidence` is small tags, linked or not; `type: "release"` draws a diamond, `"audit"` a square. Groups take `events` or `rows`; a bare `events` list is one group. In a narrow card the date goes over the event.
+
+```json
+{ "kind": "history", "groups": [{ "heading": "v2 dropped it", "summary": "Jun 26 – Jul 30", "events": [
+  { "date": "Jun 26, 2026", "age": "116d ago", "title": "The v2 TUI rewrite leaves out DialogRetryAction",
+    "detail": "`session/index.tsx` replaced without the listener.", "tone": "bad",
+    "provenance": "verified", "source": "git", "evidence": [{ "label": "e6f660fecf" }] },
+  { "date": "Oct 20, 2026", "title": "/install still 307s to v1", "tone": "warn",
+    "provenance": "inferred", "source": "edge", "step": "4.8" } ] }] }
+```
+
+**`stack`**: PRs in merge order as a branch graph. `branch` is `"head → base"` (or `head` and `base`); an item whose base is another's head hangs under it, joined by a drawn rail, and the rest sit on the trunk (`base`, else the branch most items merge into), named at the top. An item on a branch that's neither shows it. `delta` is `"+164 / -18"` or `{ add, del }`, drawn green and red; `status` and `tone` make its chip; `step` (or `stepId`) makes its title go to that step; `href` links its PR number.
+
+```json
+{ "kind": "stack", "base": "dev", "items": [
+  { "order": "01", "pr": "#57146", "href": "https://github.com/anomalyco/opencode/pull/57146", "title": "Typed free-limit error",
+    "branch": "free-limit-card → dev", "delta": "+193 / -8", "status": "Stack base", "tone": "good", "step": "4.1" },
+  { "pr": "#57466", "title": "Restore the Desktop dialog", "branch": "free-limit-desktop → free-limit-card",
+    "delta": { "add": 446, "del": 47 }, "status": "Stacked on #57146", "tone": "good", "summary": "Modal, notice and prompt recall." } ] }
+```
+
+**`table`**: a real `<table>` for audits and matrices. Rows are cells by column key, bare or under `cells`; a cell is text, a number, or `{ text, href?, code?, badge?, tone?, step? }` (a `badge` is a tone chip). Columns take `mono` and `align` (number columns go right by themselves). Figures are tabular; a tall table keeps its head stuck, a wide one scrolls across, its edges fade where there's more, and its bars show thin on hover. `caption` goes under it.
+
+```json
+{ "kind": "table", "caption": "From a clean HOME, Oct 20", "columns": [
+    { "key": "channel", "label": "Entry point", "mono": true }, { "key": "days", "label": "Days on v2" },
+    { "key": "state", "label": "State", "align": "right" } ],
+  "rows": [ { "cells": { "channel": { "text": "npm i -g @opencode-ai/cli", "code": true }, "days": 39,
+                         "state": { "text": "Broken", "badge": "bad" } } },
+            { "channel": "brew install …/opencode-v2", "days": 31, "state": { "text": "Pending", "badge": "info", "step": "4.6" } } ] }
+```
+
+**`chapters`** on a `video` (or a `compare`): timestamp pills under it. A click seeks there and plays, and goes in the note's log; one highlight springs to the chapter playing as it plays (.4 s, no bounce), and a note's `media` names it (`chapter`). A chapter ends at `end`, else `start + duration`, else the next one's start. On a compare they're also its timeline's markers. A video's `captions` (or `captionsSrc`) is a WebVTT URL, shown by default.
+
+```json
+{ "kind": "video", "src": "journey.mp4", "poster": "journey.png", "captions": "captions.vtt", "chapters": [
+  { "id": "scorecard", "label": "Scorecard", "start": 0, "duration": 9.57 },
+  { "label": "Today (broken)", "start": 9.57 }, { "label": "After", "start": 35.38 } ] }
+```
+
 ## Theming, Density & WebGPU Renderer
 
 Panels take a `theme`, an `appearance`, `density: "compact" | "default" | "comfortable"` and `renderer: "gpu" | "dom" | "auto"` (or `?gpu` in the URL), on `defineControls`, `mountPanel` or `<KnobsPanel />`; every `knobs/ui` piece takes the same `theme` and `appearance`, and `restyle(target, look)` changes them on what's already on screen. The header title defaults to the controls id, written as words (`"synth-voice"` reads "Synth voice"); pass `title` to override it or `title: false` to hide it.
@@ -1818,6 +1880,7 @@ The package has two core exports selected through the standard `development` con
 | `optionPicker(container, { options, selected?, chosen?, onSelect?, onChoose?, body?, digits? })` | Options 1–n on a gliding card, the selected one's parameters (a panel) open under it. |
 | `bento(container, { items, gap?, tolerance?, rowHeight?, fit?, blur?, picks?, onPick?, onZoom?, onActive? })` | An ideas grid: a bento of images and live content that zooms an item to fill the view; picks with Space. |
 | `planBento(aspects, { width, height, gap?, tolerance?, rowHeight?, groups?, hero? })` | The bento's layout on its own: rects, mode, coverage and crop. |
+| `walkthrough(container, { doc, onFeedback?, storage?, keys?, rail?, advance? })` / `mediaSlot(container, { media, steps? })` | The review page an agent writes (sections, steps, media from compares to histories, stacks and tables, notes and picks handed back); one step's media on its own. |
 | `overlayLook({ preset?, theme? })` | The look every overlay takes. |
 | `hints.register(root, () => targets, { listen?, rank? })` / `data-hint` | Joins the page's hint mode (`s`); `hints.start()`, `hints.stop()`. |
 | `restyle(target, { preset?, theme?, density? })` | Re-themes the pieces and panels already on screen, live; on a document, later overlays too. |

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

@@ -28,5 +28,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 { mediaSlot, type MediaSlot, type MediaSlotOptions, type StepLinks, } from "./walkthrough-media.js";
+export { collectFeedback, feedbackMarkdown, inlineMarkdown, 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 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, } from "./walkthrough-model.js";

package/dist/types/ui/walkthrough-blocks.d.ts

@@ -0,0 +1,43 @@
+import { type ContextEvent, type WalkChapter, type WalkMedia } from "./walkthrough-model.js";
+/** How media reach the page's steps: `step` on a history event, a stack item or a table cell. */
+export interface StepLinks {
+    /** The step a ref names (its key, id or number), or null when there's none. */
+    find(ref: string): {
+        readonly key: string;
+        readonly number: string;
+        readonly title: string;
+    } | null;
+    /** Goes to the step, as j / k do. */
+    go(key: string): void;
+}
+type OnEvent = ((event: Omit<ContextEvent, "at" | "step">) => void) | undefined;
+export interface Block {
+    dispose(): void;
+    context?(): {
+        kind: string;
+    };
+}
+export declare function mountHistory(host: HTMLElement, m: Extract<WalkMedia, {
+    kind: "history";
+}>, steps: StepLinks | undefined): Block;
+export declare function mountStack(host: HTMLElement, m: Extract<WalkMedia, {
+    kind: "stack";
+}>, steps: StepLinks | undefined): Block;
+export declare function mountTable(host: HTMLElement, m: Extract<WalkMedia, {
+    kind: "table";
+}>, steps: StepLinks | undefined): Block;
+export interface ChapterPills {
+    /** The chapter the time is in (call as it plays or seeks): the highlight springs to it. */
+    sync(): void;
+    /** The chapter playing, or null. */
+    readonly current: WalkChapter | null;
+    dispose(): void;
+}
+export declare function chapterPills(host: HTMLElement, chapters: readonly WalkChapter[], io: {
+    /** Seconds. */
+    now(): number;
+    /** Seeks and plays. */
+    seek(time: number): void;
+    onEvent: OnEvent;
+}): ChapterPills;
+export {};

package/dist/types/ui/walkthrough-media.d.ts

@@ -1,4 +1,5 @@
 import { type UiLook } from "./look.js";
+import { type StepLinks } from "./walkthrough-blocks.js";
 import { type ContextEvent, type MediaContext, type WalkthroughMedia } from "./walkthrough-model.js";
 export interface MediaSlotOptions extends UiLook {
     readonly media: WalkthroughMedia;
@@ -6,7 +7,10 @@ export interface MediaSlotOptions extends UiLook {
     readonly lazy?: boolean;
     /** Kit played, paused or sought a video, or showed another diff file (for a note's log). */
     readonly onEvent?: (event: Omit<ContextEvent, "at" | "step">) => void;
+    /** The page's steps, for `step` on a history event, a stack item or a table cell. */
+    readonly steps?: StepLinks;
 }
+export type { StepLinks };
 export interface MediaSlot {
     readonly element: HTMLElement;
     /** Whether its content is mounted (heavy kinds wait until they're near the view). */

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

@@ -7,6 +7,98 @@ export interface WalkthroughSource {
     readonly src: string;
     readonly label?: string;
 }
+/** A status colour: a dot, a chip or a cell's badge. */
+export type WalkthroughTone = "good" | "warn" | "bad" | "info" | "dim";
+/** A small tag that backs a claim: a PR, a commit, a log, as a link or not. */
+export interface WalkthroughEvidence {
+    readonly label: string;
+    readonly href?: string;
+}
+/** One dated moment in a `history`. */
+export interface WalkthroughHistoryEvent {
+    /** As written: "Apr 9, 2026", "2026-04-09", "May 7–8". */
+    readonly date: string;
+    /** How long ago, or how long it lasted: "116d ago". */
+    readonly age?: string;
+    readonly title: string;
+    readonly detail?: string;
+    readonly tone?: WalkthroughTone;
+    /** Seen in the record (`"verified"`) or worked out from behaviour (`"inferred"`). */
+    readonly provenance?: "verified" | "inferred";
+    /** Where it was seen or inferred from: `"git"` shows as "verified · git". */
+    readonly source?: string;
+    readonly evidence?: readonly WalkthroughEvidence[];
+    /** A step it's about: its key, id or number ("1.2"). */
+    readonly step?: string;
+    /** What happened, which shapes its dot: a release a diamond, an audit a square. */
+    readonly type?: "commit" | "release" | "channel" | "audit" | (string & {});
+}
+export interface WalkthroughHistoryGroup {
+    readonly heading?: string;
+    readonly summary?: string;
+    readonly events?: readonly WalkthroughHistoryEvent[];
+    /** Another name for `events`. */
+    readonly rows?: readonly WalkthroughHistoryEvent[];
+}
+/** One PR in a `stack`. */
+export interface WalkthroughStackItem {
+    /** "#57148" (or 57148). */
+    readonly pr: string | number;
+    readonly href?: string;
+    readonly title: string;
+    /** Its branch: `"head → base"` (or `->`), or just the head (on `base`, else the trunk). */
+    readonly branch?: string;
+    /** The branch it merges into, when `branch` names only its head. */
+    readonly base?: string;
+    /** Lines changed: `"+164 / -18"`, or `{ add, del }`. */
+    readonly delta?: string | {
+        readonly add: number;
+        readonly del: number;
+    };
+    readonly status?: string;
+    readonly tone?: WalkthroughTone;
+    readonly summary?: string;
+    /** Its head branch, with `base`: another way to write `branch`. */
+    readonly head?: string;
+    /** The step that shows it: its key, id or number. */
+    readonly step?: string;
+    /** Another name for `step`. */
+    readonly stepId?: string;
+    /** Its place as written: "01", "06 · 1/4". */
+    readonly order?: string | number;
+}
+/** A table's cell: its text, or that with a link, code, a badge, a colour or a step. */
+export type WalkthroughTableCell = string | number | {
+    readonly text: string | number;
+    readonly href?: string;
+    readonly code?: boolean;
+    /** Drawn as a chip in this colour. */
+    readonly badge?: WalkthroughTone;
+    /** The text in this colour. */
+    readonly tone?: WalkthroughTone;
+    readonly step?: string;
+};
+export interface WalkthroughTableColumn {
+    readonly key: string;
+    readonly label: string;
+    readonly mono?: boolean;
+    /** Numbers go right by default. */
+    readonly align?: "left" | "right" | "center";
+}
+/** A row: its cells by column key, bare or under `cells`. */
+export type WalkthroughTableRow = Readonly<Record<string, WalkthroughTableCell>> | {
+    readonly cells: Readonly<Record<string, WalkthroughTableCell>>;
+};
+/** A stretch of a video: a pill under it, and a marker on its timeline. */
+export interface WalkthroughChapter {
+    readonly id?: string;
+    readonly label: string;
+    /** Seconds. */
+    readonly start: number;
+    /** Seconds; else `start + duration`, else the next chapter's start. */
+    readonly end?: number;
+    readonly duration?: number;
+}
 /**
  * What a step shows. A bare string is a video or image URL (by its extension). `mount` is the one
  * kind that isn't JSON: anything of your own, given its element, returning its cleanup.
@@ -21,12 +113,37 @@ export type WalkthroughMedia = string | {
     readonly aspect?: number | string;
     /** The frame strip over the timeline. */
     readonly strip?: boolean;
+    /** Pills under it that seek, and markers on its timeline. */
+    readonly chapters?: readonly WalkthroughChapter[];
 } | {
     readonly kind: "video";
     readonly src: string;
     readonly label?: string;
     readonly aspect?: number | string;
     readonly poster?: string;
+    /** Pills under it that seek; the one playing lit. */
+    readonly chapters?: readonly WalkthroughChapter[];
+    /** A WebVTT file's URL, shown by default. */
+    readonly captions?: string;
+    /** Another name for `captions`. */
+    readonly captionsSrc?: string;
+} | {
+    readonly kind: "history";
+    /** Dated events under quiet headings… */
+    readonly groups?: readonly WalkthroughHistoryGroup[];
+    /** …or one run of them. */
+    readonly events?: readonly WalkthroughHistoryEvent[];
+} | {
+    readonly kind: "stack";
+    /** The branch the stack lands on ("dev"); else the one most items merge into. */
+    readonly base?: string;
+    /** In merge order; an item on another's branch hangs under it. */
+    readonly items: readonly WalkthroughStackItem[];
+} | {
+    readonly kind: "table";
+    readonly columns: readonly WalkthroughTableColumn[];
+    readonly rows: readonly WalkthroughTableRow[];
+    readonly caption?: string;
 } | {
     readonly kind: "image";
     readonly src: string;
@@ -154,11 +271,78 @@ export interface WalkthroughDoc {
 type CompareMedia = Extract<WalkthroughMedia, {
     kind: "compare";
 }>;
-/** Media filled in: no bare URLs, and a compare's sides as sources. */
-export type WalkMedia = Exclude<WalkthroughMedia, string | CompareMedia> | (Omit<CompareMedia, "before" | "after"> & {
+type VideoMedia = Extract<WalkthroughMedia, {
+    kind: "video";
+}>;
+/** A chapter filled in: an id, and its end where one can be known. */
+export interface WalkChapter {
+    readonly id: string;
+    readonly label: string;
+    readonly start: number;
+    readonly end?: number;
+}
+export interface WalkHistoryGroup {
+    readonly heading?: string;
+    readonly summary?: string;
+    readonly events: readonly WalkthroughHistoryEvent[];
+}
+/** A stack's item filled in: its PR as `#123`, its branch split, `step` for `stepId`. */
+export interface WalkStackItem {
+    readonly pr: string;
+    readonly href?: string;
+    readonly title: string;
+    readonly head?: string;
+    readonly base?: string;
+    readonly delta?: string | {
+        readonly add: number;
+        readonly del: number;
+    };
+    readonly status?: string;
+    readonly tone?: WalkthroughTone;
+    readonly summary?: string;
+    readonly step?: string;
+    readonly order?: string;
+}
+export interface WalkTableCell {
+    readonly text: string;
+    readonly href?: string;
+    readonly code?: boolean;
+    readonly badge?: WalkthroughTone;
+    readonly tone?: WalkthroughTone;
+    readonly step?: string;
+}
+export interface WalkTableColumn {
+    readonly key: string;
+    readonly label: string;
+    readonly mono?: boolean;
+    readonly align: "left" | "right" | "center";
+}
+/**
+ * Media filled in: no bare URLs, a compare's sides as sources, chapters with their ends, history in
+ * groups, a stack's branches split and a table's cells as objects. Filling it again changes
+ * nothing.
+ */
+export type WalkMedia = Exclude<WalkthroughMedia, string | {
+    readonly kind: "compare" | "video" | "history" | "stack" | "table";
+}> | (Omit<CompareMedia, "before" | "after" | "chapters"> & {
     readonly before: WalkthroughSource;
     readonly after: WalkthroughSource;
-});
+    readonly chapters?: readonly WalkChapter[];
+}) | (Omit<VideoMedia, "chapters" | "captionsSrc"> & {
+    readonly chapters?: readonly WalkChapter[];
+}) | {
+    readonly kind: "history";
+    readonly groups: readonly WalkHistoryGroup[];
+} | {
+    readonly kind: "stack";
+    readonly base?: string;
+    readonly items: readonly WalkStackItem[];
+} | {
+    readonly kind: "table";
+    readonly columns: readonly WalkTableColumn[];
+    readonly rows: readonly Readonly<Record<string, WalkTableCell>>[];
+    readonly caption?: string;
+};
 export interface WalkOption {
     readonly id: string;
     readonly label: string;
@@ -231,6 +415,54 @@ export declare const mediaOf: (src: string) => WalkMedia;
 export declare function parseAspect(aspect: number | string | undefined): number | undefined;
 /** Media filled in: a bare URL as a video or image, sources resolved against `base`. */
 export declare function fillMedia(m: WalkthroughMedia, base?: string): WalkMedia;
+/** `"head → base"` (or `->`, `=>`, `⇒`) as its two branches; one name is the head alone. */
+export declare function parseBranch(branch: string | undefined): {
+    head?: string;
+    base?: string;
+};
+/** `"+164 / -18"`, `"+164 −18"` or `{ add, del }` as numbers; other text stays as written. */
+export declare function parseDelta(delta: WalkthroughStackItem["delta"]): {
+    add: number;
+    del: number;
+} | string | undefined;
+/** One row of a stack as drawn: where it hangs, and which rails pass beside it. */
+export interface StackRow {
+    readonly item: WalkStackItem;
+    /** Its place in `items`. */
+    readonly index: number;
+    /** 0 on the trunk; one more for each item it's stacked on. */
+    readonly depth: number;
+    /** The item it's stacked on (its place in `items`); null on the trunk. */
+    readonly parent: number | null;
+    /** The last of its siblings: its rail ends here (└) rather than going on (├). */
+    readonly last: boolean;
+    /** For each level above its own (0 the trunk's), whether that level's rail passes beside it. */
+    readonly rails: readonly boolean[];
+    readonly children: number;
+    /** The branch it merges into when that's neither the trunk nor another item's. */
+    readonly offBase?: string;
+}
+export interface StackLayout {
+    /** The branch it lands on: `base`, else the one most items merge into; null when none says. */
+    readonly trunk: string | null;
+    /** Depth-first in merge order: each item after the one it's stacked on. */
+    readonly rows: readonly StackRow[];
+    /** Nothing is stacked on anything, and there's no trunk: a plain list. */
+    readonly flat: boolean;
+}
+/** A stack's branch topology: which item each one is stacked on, in rows to draw as a graph. */
+export declare function stackLayout(m: {
+    readonly base?: string;
+    readonly items: readonly WalkStackItem[];
+}): StackLayout;
+/** Chapters with ids and, where it can be known, an end: given, `start + duration`, or the next. */
+export declare function fillChapters(chapters: readonly WalkthroughChapter[]): WalkChapter[];
+/** The chapter playing at `time` (seconds): the one it's in that started last; -1 for none. */
+export declare function chapterAt(chapters: readonly WalkChapter[], time: number): number;
+/** Seconds as a clock: `1:05`, `1:02:05` past the hour. */
+export declare function clock(seconds: number): string;
+/** A step named by its key, id or number ("1.2"), a leading `#` allowed; undefined if there's none. */
+export declare function findStep(steps: readonly WalkStep[], ref: string | undefined): WalkStep | undefined;
 /** A GitHub PR or issue URL's number as `#123`; else the URL's last part. */
 export declare function linkLabel(href: string): string;
 /**
@@ -280,6 +512,8 @@ export interface MediaContext {
     readonly time?: number;
     readonly duration?: number;
     readonly playing?: boolean;
+    /** The chapter the time is in, by its label. */
+    readonly chapter?: string;
     /** The loop range, in seconds. */
     readonly loop?: {
         readonly start: number;

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

@@ -1,6 +1,6 @@
 import { type StoragePort } from "../core/storage.js";
 import { type UiLook } from "./look.js";
-import { type MediaSlot } from "./walkthrough-media.js";
+import { type MediaSlot, type StepLinks } from "./walkthrough-media.js";
 import { type WalkOption, type WalkPage, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughOption, type WalkthroughState } from "./walkthrough-model.js";
 export interface TasteTestOptions extends UiLook {
     readonly options: readonly (WalkthroughOption | WalkOption)[];
@@ -9,6 +9,8 @@ export interface TasteTestOptions extends UiLook {
     readonly onPick?: (id: string | null) => void;
     /** Mount each option's media when near the view (on by default). */
     readonly lazy?: boolean;
+    /** The page's steps, for media that name one. */
+    readonly steps?: StepLinks;
 }
 export interface TasteTest {
     readonly element: HTMLElement;