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

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

@@ -1,5 +1,6 @@
 import type { CompareMode } from "./compare-model.js";
 import type { DiffSource } from "./diff-model.js";
+import type { HistoryData, HistoryEvent } from "./history-model.js";
 /** Where a PR or topic stands, as the agent sees it: a chip beside its title. */
 export type WalkthroughStatus = "ready" | "needs-taste" | "draft" | "blocked" | "merged" | (string & {});
 /** A picture or video, by URL. */
@@ -7,6 +8,114 @@ 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 mark on a picture drawing the eye to what matters: a ring round a box, a dot or an arrow at a
+ * point, with a small label. In 0–1 of the picture (`x`, `y` the box's top-left or the point).
+ */
+export interface WalkthroughAnnotation {
+    readonly x: number;
+    readonly y: number;
+    /** A box's size; left out, it's a point. */
+    readonly w?: number;
+    readonly h?: number;
+    readonly label?: string;
+    /** Seconds it shows between, on a video or compare; always, left out. */
+    readonly at?: readonly [number, number];
+    /** `"box"` where it has a size, else `"dot"`. */
+    readonly shape?: "box" | "dot" | "arrow";
+}
+/** 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,17 +130,65 @@ 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[];
+    /** Marks on the pictures, on both sides (and under a zoom). */
+    readonly annotations?: readonly WalkthroughAnnotation[];
 } | {
     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;
+    /** Marks on the picture. */
+    readonly annotations?: readonly WalkthroughAnnotation[];
+} | {
+    readonly kind: "history";
+    /** Lanes of dated spans over one axis (`history()`'s shape)… */
+    readonly lanes?: HistoryData["lanes"];
+    readonly bands?: HistoryData["bands"];
+    readonly states?: HistoryData["states"];
+    readonly axis?: HistoryData["axis"];
+    /** …dated events (on the lanes, or one run of them in the older shape)… */
+    readonly events?: readonly (WalkthroughHistoryEvent | HistoryEvent)[];
+    /** …or the older groups of events under quiet headings. */
+    readonly groups?: readonly WalkthroughHistoryGroup[];
+    /** Its accessible name. */
+    readonly label?: string;
+    /** The event types marked from the start (releases and deletions), or `"all"`. */
+    readonly marks?: readonly string[] | "all";
+} | {
+    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;
+    /**
+     * Where the step is too narrow for its columns, each row becomes a block: its primary cell
+     * as a title over the rest as term and value (`"auto"`, the default); always; or never
+     * (the table scrolls sideways instead).
+     */
+    readonly stack?: "auto" | "always" | "never";
+    /** The column that titles a stacked row (its key); the first by default. */
+    readonly primary?: string;
 } | {
     readonly kind: "image";
     readonly src: string;
     readonly label?: string;
     readonly alt?: string;
+    /** Marks on the picture. */
+    readonly annotations?: readonly WalkthroughAnnotation[];
 } | {
     readonly kind: "diff";
     /** `git diff` / `git show` output. */
@@ -65,6 +222,20 @@ export type WalkthroughMedia = string | {
 } | {
     readonly kind: "text";
     readonly text: string;
+} | {
+    readonly kind: "facts";
+    /** A small faint label over it. */
+    readonly title?: string;
+    /** One run of term → value pairs… */
+    readonly facts?: WalkthroughFacts;
+    /** …or several, each under a heading, hairlines between. */
+    readonly groups?: readonly WalkthroughFactGroup[];
+} | {
+    readonly kind: "decision";
+    /** Side by side where there's room, one under another where there isn't. */
+    readonly options: readonly WalkthroughDecisionOption[];
+    /** The word before each option's number: "Option" by default. */
+    readonly noun?: string;
 } | {
     readonly kind: "mount";
     readonly mount: (element: HTMLElement) => (() => void) | void;
@@ -72,6 +243,35 @@ export type WalkthroughMedia = string | {
     readonly height?: number;
 };
 export type CalloutTone = "info" | "good" | "warn" | "bad";
+/** A term and its value. */
+export interface WalkthroughFact {
+    readonly term: string;
+    /** Markdown, where `code` reads as a small mono chip; several values sit one under another. */
+    readonly value: string | readonly string[];
+    /** Each value is code or evidence (a string splits at commas): small mono chips. */
+    readonly code?: boolean;
+}
+/** Facts as a list, or as `{ term: value }`. */
+export type WalkthroughFacts = readonly WalkthroughFact[] | Readonly<Record<string, string | readonly string[]>>;
+export interface WalkthroughFactGroup {
+    readonly title?: string;
+    readonly facts: WalkthroughFacts;
+}
+/** One way to go in a decision. */
+export interface WalkthroughDecisionOption {
+    readonly id?: string;
+    readonly title: string;
+    /** A sentence: what it does. Markdown. */
+    readonly summary?: string;
+    /** What it looks like: a picture, a compare, code. */
+    readonly media?: WalkthroughMedia;
+    /** What changes, as facts ("What the user sees", "Size"). */
+    readonly facts?: WalkthroughFacts;
+    readonly pros?: readonly string[];
+    readonly cons?: readonly string[];
+    /** The one to take: a quiet "Recommended" beside its number. */
+    readonly recommended?: boolean;
+}
 /** One option in a taste test. */
 export interface WalkthroughOption {
     /** "a", "b"… by position when left out. */
@@ -79,8 +279,12 @@ export interface WalkthroughOption {
     readonly label: string;
     readonly caption?: string;
     readonly media?: WalkthroughMedia;
-    /** The agent's own pick, marked "Suggested". */
+    /** What changes, as facts, under its caption. */
+    readonly facts?: WalkthroughFacts;
+    /** The agent's own pick, marked "Recommended". */
     readonly suggested?: boolean;
+    /** Another name for `suggested`. */
+    readonly recommended?: boolean;
 }
 export interface WalkthroughStep {
     /** From the title when left out. */
@@ -88,8 +292,15 @@ export interface WalkthroughStep {
     readonly title: string;
     /** A line or two: what it shows and how it was made. `code`, **bold** and [links](…) work. */
     readonly caption?: string;
-    /** One slot; two or more sit side by side, stacking where it's narrow. */
+    /** One slot, or several one under another (`columns` sets them side by side). */
     readonly media?: WalkthroughMedia | readonly WalkthroughMedia[];
+    /** Media side by side, this many to a row where there's room; one under another by default. */
+    readonly columns?: 1 | 2 | 3;
+    /**
+     * The rest, folded away under the caption behind "More" (Markdown; blank lines start new
+     * paragraphs). Keep the title the claim and the caption one sentence; everything else goes here.
+     */
+    readonly more?: string;
     /** A taste test: Kit picks one. */
     readonly options?: readonly WalkthroughOption[];
     /**
@@ -108,8 +319,16 @@ export interface WalkthroughSection {
         readonly href: string;
         readonly label?: string;
     };
+    /**
+     * The words that lead its meta line, in text colour: its count by default (`"PR 2 of 5"` where
+     * `link` is a pull request, or the doc's `kickers` noun), your own words, or `false` for none.
+     */
+    readonly kicker?: string | false;
+    /** A chip on its meta line ("needs-taste" → Needs taste), with `review: true` only. */
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
+    /** The rest, folded away under the summary behind "More" (Markdown). */
+    readonly more?: string;
     readonly steps: readonly WalkthroughStep[];
 }
 export interface WalkthroughMeta {
@@ -124,6 +343,10 @@ export interface WalkthroughUpdate {
     readonly text: string;
     /** The step it's about: its key, id or number ("1.2"). */
     readonly step?: string;
+    /** Its state in a word or two (`"shipped"`, `"changes"`), last on its meta line. */
+    readonly status?: string;
+    /** Context, folded away under the item: one line each, `"0:04 · Played the compare"`. */
+    readonly trail?: readonly string[];
 }
 /** A question Kit asked and the agent's answer. */
 export interface WalkthroughQA {
@@ -132,6 +355,10 @@ export interface WalkthroughQA {
     readonly q: string;
     readonly a: string;
     readonly step?: string;
+    /** `"shipped"` or `"changes"` (shown as "Changes queued"), or your own words. */
+    readonly status?: string;
+    /** What Kit did before asking, folded away under the answer: `"0:04 · Played the compare"`. */
+    readonly trail?: readonly string[];
 }
 /** The document an agent writes: plain data, JSON but for `mount` media. */
 export interface WalkthroughDoc {
@@ -139,6 +366,8 @@ export interface WalkthroughDoc {
     readonly id: string;
     readonly title: string;
     readonly summary?: string;
+    /** The rest, folded away under the summary behind "More" (Markdown). */
+    readonly more?: string;
     /** Facts beside the title: branch, commit, date… */
     readonly meta?: Readonly<Record<string, string>> | readonly WalkthroughMeta[];
     /** Relative media URLs resolve against this. */
@@ -149,16 +378,117 @@ export interface WalkthroughDoc {
     readonly updates?: readonly WalkthroughUpdate[];
     /** Kit's questions and the agent's answers. */
     readonly qa?: readonly WalkthroughQA[];
+    /**
+     * How sections are counted on their meta line: `"pr"` (the default) gives "PR i of N" to the
+     * sections that link a pull request, `{ noun: "Part" }` "Part i of N" to every section, and
+     * `false` none. A section's own `kicker` wins over its count, and `false` hides it, without
+     * renumbering the rest.
+     */
+    readonly kickers?: "pr" | {
+        readonly noun: string;
+    } | false;
+    /**
+     * The pull requests the page mentions, by number: their state and title. A `#57148` in a title,
+     * caption or summary, a link to a pull request, and a section's PR `link` read as a small chip
+     * (its state's icon and number; the title on hover).
+     */
+    readonly prs?: Readonly<Record<string, WalkthroughPR>>;
+    /** `owner/name` on GitHub, so a bare `#57148` links to its pull request. */
+    readonly repo?: string;
     readonly sections: readonly WalkthroughSection[];
 }
+export interface WalkthroughPR {
+    readonly state?: "merged" | "open" | "draft" | "closed";
+    /** An issue rather than a pull request (`issue:` refs and `/issues/` links are). */
+    readonly kind?: "pr" | "issue";
+    /** Its checks pass (a stack item's status saying green, passing or CI). */
+    readonly checks?: boolean;
+    readonly title?: string;
+    /** Its URL, when neither `repo` nor a link on the page gives it. */
+    readonly href?: string;
+}
 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;
+}
+/** 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" | "facts" | "decision";
+}> | (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 data: HistoryData;
+    readonly label?: string;
+    readonly marks?: readonly string[] | "all";
+} | {
+    readonly kind: "stack";
+    readonly base?: string;
+    readonly items: readonly WalkStackItem[];
+} | {
+    readonly kind: "facts";
+    readonly title?: string;
+    readonly groups: readonly WalkFactGroup[];
+} | {
+    readonly kind: "decision";
+    readonly options: readonly WalkDecisionOption[];
+} | {
+    readonly kind: "table";
+    readonly columns: readonly WalkTableColumn[];
+    readonly rows: readonly Readonly<Record<string, WalkTableCell>>[];
+    readonly caption?: string;
+    readonly stack: "auto" | "always" | "never";
+    /** The key of the column that titles a stacked row. */
+    readonly primary: string;
+};
 export interface WalkOption {
     readonly id: string;
     readonly label: string;
@@ -166,8 +496,30 @@ export interface WalkOption {
     readonly letter: string;
     readonly caption?: string;
     readonly media?: WalkMedia;
+    readonly facts?: readonly WalkFact[];
     readonly suggested: boolean;
 }
+/** A fact filled in: its values as a list. */
+export interface WalkFact {
+    readonly term: string;
+    readonly value: readonly string[];
+    readonly code: boolean;
+}
+export interface WalkFactGroup {
+    readonly title?: string;
+    readonly facts: readonly WalkFact[];
+}
+/** A decision's option filled in: its id, its number's words, pros and cons as facts. */
+export interface WalkDecisionOption {
+    readonly id: string;
+    /** "Option 1". */
+    readonly number: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly media?: WalkMedia;
+    readonly facts: readonly WalkFact[];
+    readonly recommended: boolean;
+}
 export interface WalkStep {
     /** `section/step`: where its feedback is kept. */
     readonly key: string;
@@ -179,6 +531,9 @@ export interface WalkStep {
     readonly caption?: string;
     readonly question?: string;
     readonly media: readonly WalkMedia[];
+    /** Media to a row: 1 (one under another) unless the step asked for more. */
+    readonly columns: number;
+    readonly more?: string;
     readonly options: readonly WalkOption[];
     readonly ask: "note" | "pick" | "none";
 }
@@ -189,8 +544,11 @@ export interface WalkSection {
         readonly href: string;
         readonly label: string;
     };
+    /** What leads its meta line ("PR 2 of 5"), when anything does. */
+    readonly kicker?: string;
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
+    readonly more?: string;
     readonly steps: readonly WalkStep[];
 }
 export interface WalkVerdict {
@@ -207,11 +565,14 @@ export interface FeedItem {
     readonly q?: string;
     /** The step's key, when it names one that's there. */
     readonly step: string | null;
+    readonly status?: string;
+    readonly trail: readonly string[];
 }
 export interface WalkPage {
     readonly id: string;
     readonly title: string;
     readonly summary?: string;
+    readonly more?: string;
     readonly meta: readonly WalkthroughMeta[];
     readonly verdicts: readonly WalkVerdict[];
     readonly sections: readonly WalkSection[];
@@ -219,6 +580,10 @@ export interface WalkPage {
     readonly steps: readonly WalkStep[];
     /** Updates and answers, newest first. */
     readonly feed: readonly FeedItem[];
+    /** The pull requests the page knows, by number, each with its URL when one is known. */
+    readonly prs: Readonly<Record<string, WalkthroughPR>>;
+    /** `owner/name`, when the doc gave one. */
+    readonly repo?: string;
 }
 export declare const DEFAULT_VERDICTS: readonly ["ship", "change", "unsure"];
 /** A URL-safe id from a title: "Retired model (HTTP 410)" → "retired-model-http-410". */
@@ -231,6 +596,70 @@ 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;
+/** Facts as a list of terms and their values (a code value split at its commas). */
+export declare function fillFacts(facts: WalkthroughFacts | readonly WalkFact[]): readonly WalkFact[];
+/**
+ * How many options sit side by side: as many as fit at `min` px each with `gap` between, up to 4,
+ * and always a count that fills whole rows (4 → 4, 2 or 1; 3 → 3 or 1; 5 → 1), so no row is short.
+ */
+export declare function optionColumns(count: number, width: number, min?: number, gap?: number): number;
+/** A decision's options filled in: ids, "Option 1"…, pros and cons as the last facts. */
+export declare function fillDecision(options: readonly (WalkthroughDecisionOption | WalkDecisionOption)[], noun?: string, base?: string): readonly WalkDecisionOption[];
+/**
+ * What `history()` draws: the lanes shape as written, or the older groups (`rows` read as
+ * `events`, bare `events` as one group first) for it to lay on the code lane.
+ */
+export declare function historyData(m: Extract<WalkthroughMedia, {
+    kind: "history";
+}>): HistoryData;
+/** `"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;
 /**
@@ -238,6 +667,37 @@ export declare function linkLabel(href: string): string;
  * ask, options lettered, media URLs resolved against `base`, and the verdicts labelled.
  */
 export declare function normalizeWalkthrough(doc: WalkthroughDoc): WalkPage;
+/** The number in a pull request's URL (`…/pull/57148`), or null. */
+export declare const prNumber: (href: string) => string | null;
+export type PRState = NonNullable<WalkthroughPR["state"]>;
+/**
+ * A pull request's state from some status words: the first word when it's merged, draft, open or
+ * closed (any case; shipped and done read as merged), and whether they say its checks pass
+ * ("green", "passing", "CI"). The state comes from the words, never a tone.
+ */
+export declare function prStatus(status: string | undefined): {
+    state: PRState | null;
+    checks: boolean;
+};
+/**
+ * A pull request (or an issue) by number: what the page knows, or (with a repo) its URL; null
+ * when it knows nothing. An issue takes only what `prs` says of it as an issue.
+ */
+export declare function findPR(prs: Readonly<Record<string, WalkthroughPR>>, n: string, repo?: string, kind?: "pr" | "issue"): WalkthroughPR | null;
+/** The number in an issue's URL (`…/issues/123`), or null. */
+export declare const issueNumber: (href: string) => string | null;
+/** Whether a link is a pull (or merge) request: GitHub's `/pull/123`, GitLab's merge requests. */
+export declare const isPullRequest: (href: string) => boolean;
+/**
+ * Whether a table stacks its rows into blocks: always, never, or (auto) when the room it has is
+ * less than its columns' natural width.
+ */
+export declare function tableStacks(stack: "auto" | "always" | "never", room: number, natural: number): boolean;
+/**
+ * The page's bottom reserve for the docked note bar: its height, the gap it floats above the
+ * page's edge, and a gap above it, so the last step and a step gone to never sit under it.
+ */
+export declare function noteBarReserve(bar: number, inset: number, gap: number): number;
 /** An ISO time as epoch ms; null when it isn't one. */
 export declare function parseAt(at: string | undefined): number | null;
 /** Newest first; items without a time after those with one, later-written first. */
@@ -280,6 +740,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;
@@ -443,5 +905,7 @@ export declare function feedbackMarkdown(fb: WalkthroughFeedback, verdicts?: rea
  * Inline Markdown as safe HTML: `code`, **bold**, *italic* and [links](https://…), the rest
  * escaped. Links take http(s), relative and # URLs only; blank lines make paragraphs' breaks.
  */
+/** Inline Markdown as plain words, for a contents row, a label or a title attribute. */
+export declare function plainMarkdown(text: string): string;
 export declare function inlineMarkdown(text: string): string;
 export {};