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

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;