@kitlangton/knobs 0.3.0 → 0.4.0-next.1

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

@@ -29,8 +29,8 @@ export interface TreeOptions<T> extends UiLook {
     readonly getLabel?: (item: T) => string;
     /** A glyph, SVG markup or node before the label. */
     readonly icon?: (item: T) => string | Node | undefined;
-    /** Dimmed text after the label (a count, a kind). */
-    readonly detail?: (item: T) => string | undefined;
+    /** Dimmed text (or a node of your own) after the label: a count, a kind. */
+    readonly detail?: (item: T) => string | Node | undefined;
     /** Your own content in place of the label. */
     readonly render?: (item: T, row: TreeRowContext) => Node | string | undefined | void;
     readonly selection?: Iterable<string>;
@@ -63,6 +63,11 @@ export interface TreeOptions<T> extends UiLook {
      * row as a click does. While the page has hint mode, `s` goes to it rather than type-ahead.
      */
     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.
+     */
+    readonly glide?: boolean;
 }
 export interface Tree<T> {
     readonly element: HTMLElement;

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

@@ -0,0 +1 @@
+export declare const walkthroughCss: string;

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

@@ -0,0 +1,29 @@
+import { type UiLook } from "./look.js";
+import { type ContextEvent, type MediaContext, type WalkthroughMedia } from "./walkthrough-model.js";
+export interface MediaSlotOptions extends UiLook {
+    readonly media: WalkthroughMedia;
+    /** Mount heavy kinds near the view and let them go far from it (on by default). */
+    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;
+}
+export interface MediaSlot {
+    readonly element: HTMLElement;
+    /** Whether its content is mounted (heavy kinds wait until they're near the view). */
+    readonly mounted: boolean;
+    /** Pauses any video in it. */
+    pause(): void;
+    /** Moves its video (or compare) by `seconds`; false when there's none mounted. */
+    seekBy(seconds: number): boolean;
+    /** What it's showing now: a video's time, a compare's loop, zoom and mode, a diff's file. */
+    context(): MediaContext | null;
+    /** A zoomed compare back to the whole picture; false when nothing was zoomed. */
+    unzoom(): boolean;
+    /** Fills the slot's height (its step full window) or goes back: a diff switches its height. */
+    fill(on: boolean): void;
+    dispose(): void;
+}
+/** Adds the walkthrough's stylesheet once per document. */
+export declare function injectWalkthroughStyles(doc: Document): void;
+export declare function mediaSlot(container: HTMLElement, options: MediaSlotOptions): MediaSlot;
+export declare const CHECK: string;

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

@@ -0,0 +1,447 @@
+import type { CompareMode } from "./compare-model.js";
+import type { DiffSource } from "./diff-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. */
+export interface WalkthroughSource {
+    readonly src: string;
+    readonly label?: string;
+}
+/**
+ * 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.
+ */
+export type WalkthroughMedia = string | {
+    readonly kind: "compare";
+    readonly before: string | WalkthroughSource;
+    readonly after: string | WalkthroughSource;
+    /** `"side"` by default (`"wipe"` where the slot is narrow). */
+    readonly mode?: CompareMode;
+    /** Width over height (`16 / 9`, or `"1100/900"`); read from the video when left out. */
+    readonly aspect?: number | string;
+    /** The frame strip over the timeline. */
+    readonly strip?: boolean;
+} | {
+    readonly kind: "video";
+    readonly src: string;
+    readonly label?: string;
+    readonly aspect?: number | string;
+    readonly poster?: string;
+} | {
+    readonly kind: "image";
+    readonly src: string;
+    readonly label?: string;
+    readonly alt?: string;
+} | {
+    readonly kind: "diff";
+    /** `git diff` / `git show` output. */
+    readonly patch?: string;
+    readonly files?: readonly DiffSource[];
+    readonly file?: string;
+    readonly layout?: "split" | "unified";
+    /** With the file list beside it (`diffReview`), for many files. */
+    readonly review?: boolean;
+    /** Pixels: the diff grows to its file up to this (640), or the review's height (480). */
+    readonly height?: number;
+} | {
+    readonly kind: "code" | "terminal";
+    readonly code: string;
+    readonly label?: string;
+    readonly lang?: string;
+} | {
+    readonly kind: "metric";
+    readonly label: string;
+    readonly before: number | string;
+    readonly after: number | string;
+    /** Out of: "315 → 345 of 345". */
+    readonly of?: number | string;
+    readonly unit?: string;
+    /** Which way is better (`"up"`): colours the change. */
+    readonly better?: "up" | "down";
+} | {
+    readonly kind: "callout";
+    readonly text: string;
+    readonly tone?: CalloutTone;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "mount";
+    readonly mount: (element: HTMLElement) => (() => void) | void;
+    /** Pixels held for it before it mounts. */
+    readonly height?: number;
+};
+export type CalloutTone = "info" | "good" | "warn" | "bad";
+/** One option in a taste test. */
+export interface WalkthroughOption {
+    /** "a", "b"… by position when left out. */
+    readonly id?: string;
+    readonly label: string;
+    readonly caption?: string;
+    readonly media?: WalkthroughMedia;
+    /** The agent's own pick, marked "Suggested". */
+    readonly suggested?: boolean;
+}
+export interface WalkthroughStep {
+    /** From the title when left out. */
+    readonly id?: string;
+    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. */
+    readonly media?: WalkthroughMedia | readonly WalkthroughMedia[];
+    /** A taste test: Kit picks one. */
+    readonly options?: readonly WalkthroughOption[];
+    /**
+     * What Kit is asked for: a note (the default), a pick (with options), or nothing. `"verdict"`,
+     * from older documents, reads as `"note"`.
+     */
+    readonly ask?: "note" | "pick" | "none" | "verdict";
+    /** The question, over the step's media or options. */
+    readonly question?: string;
+}
+export interface WalkthroughSection {
+    readonly id?: string;
+    readonly title: string;
+    /** A PR or issue: its URL (labelled `#123` from a GitHub URL), or a label and URL. */
+    readonly link?: string | {
+        readonly href: string;
+        readonly label?: string;
+    };
+    readonly status?: WalkthroughStatus;
+    readonly summary?: string;
+    readonly steps: readonly WalkthroughStep[];
+}
+export interface WalkthroughMeta {
+    readonly label: string;
+    readonly value: string;
+    readonly href?: string;
+}
+/** Something the agent did since Kit last looked: newest first at the top of the page. */
+export interface WalkthroughUpdate {
+    /** When: an ISO time (`2026-10-19T14:05:00-07:00`). */
+    readonly at: string;
+    readonly text: string;
+    /** The step it's about: its key, id or number ("1.2"). */
+    readonly step?: string;
+}
+/** A question Kit asked and the agent's answer. */
+export interface WalkthroughQA {
+    /** When it was answered: an ISO time. */
+    readonly at?: string;
+    readonly q: string;
+    readonly a: string;
+    readonly step?: string;
+}
+/** The document an agent writes: plain data, JSON but for `mount` media. */
+export interface WalkthroughDoc {
+    /** Kit's feedback is kept under this id; a new id starts fresh. */
+    readonly id: string;
+    readonly title: string;
+    readonly summary?: string;
+    /** Facts beside the title: branch, commit, date… */
+    readonly meta?: Readonly<Record<string, string>> | readonly WalkthroughMeta[];
+    /** Relative media URLs resolve against this. */
+    readonly base?: string;
+    /** Older documents' verdicts, kept in the data and the export (no buttons draw them). */
+    readonly verdicts?: readonly string[];
+    /** What the agent has done since, newest shown first. */
+    readonly updates?: readonly WalkthroughUpdate[];
+    /** Kit's questions and the agent's answers. */
+    readonly qa?: readonly WalkthroughQA[];
+    readonly sections: readonly WalkthroughSection[];
+}
+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"> & {
+    readonly before: WalkthroughSource;
+    readonly after: WalkthroughSource;
+});
+export interface WalkOption {
+    readonly id: string;
+    readonly label: string;
+    /** "A", "B"… */
+    readonly letter: string;
+    readonly caption?: string;
+    readonly media?: WalkMedia;
+    readonly suggested: boolean;
+}
+export interface WalkStep {
+    /** `section/step`: where its feedback is kept. */
+    readonly key: string;
+    readonly id: string;
+    readonly section: string;
+    /** "1.2": section, then step. */
+    readonly number: string;
+    readonly title: string;
+    readonly caption?: string;
+    readonly question?: string;
+    readonly media: readonly WalkMedia[];
+    readonly options: readonly WalkOption[];
+    readonly ask: "note" | "pick" | "none";
+}
+export interface WalkSection {
+    readonly id: string;
+    readonly title: string;
+    readonly link?: {
+        readonly href: string;
+        readonly label: string;
+    };
+    readonly status?: WalkthroughStatus;
+    readonly summary?: string;
+    readonly steps: readonly WalkStep[];
+}
+export interface WalkVerdict {
+    readonly id: string;
+    readonly label: string;
+}
+/** One line of the feed: an update, or a question and its answer. */
+export interface FeedItem {
+    readonly kind: "update" | "qa";
+    /** Epoch ms, or null when `at` isn't a time. */
+    readonly at: number | null;
+    readonly text: string;
+    /** The question, for `qa`. */
+    readonly q?: string;
+    /** The step's key, when it names one that's there. */
+    readonly step: string | null;
+}
+export interface WalkPage {
+    readonly id: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly meta: readonly WalkthroughMeta[];
+    readonly verdicts: readonly WalkVerdict[];
+    readonly sections: readonly WalkSection[];
+    /** Every step, in reading order. */
+    readonly steps: readonly WalkStep[];
+    /** Updates and answers, newest first. */
+    readonly feed: readonly FeedItem[];
+}
+export declare const DEFAULT_VERDICTS: readonly ["ship", "change", "unsure"];
+/** A URL-safe id from a title: "Retired model (HTTP 410)" → "retired-model-http-410". */
+export declare function slug(text: string): string;
+/** A relative URL against `base` (none: as written). Absolute URLs, data: and blob: stay. */
+export declare function resolveSrc(src: string, base?: string): string;
+/** A bare URL as media: a video by its extension, else an image. */
+export declare const mediaOf: (src: string) => WalkMedia;
+/** Width over height from `16/9`, `"1100/900"`, `"1100x900"` or `1.5`; undefined if unreadable. */
+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;
+/** A GitHub PR or issue URL's number as `#123`; else the URL's last part. */
+export declare function linkLabel(href: string): string;
+/**
+ * The document filled in: ids from titles where left out (unique), each step's key, number and
+ * ask, options lettered, media URLs resolved against `base`, and the verdicts labelled.
+ */
+export declare function normalizeWalkthrough(doc: WalkthroughDoc): WalkPage;
+/** 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. */
+export declare function sortFeed(items: readonly FeedItem[]): FeedItem[];
+/** "just now", "5m ago", "3h ago", "2d ago", else the date. */
+export declare function ago(at: number, now: number): string;
+/** A status chip's words and tone: "needs-taste" → "Needs taste", in the warn colour. */
+export declare function statusLook(status: WalkthroughStatus): {
+    label: string;
+    tone: "good" | "warn" | "bad" | "dim" | "info";
+};
+/** A verdict's tone: the first is the good one, a "change"/"no" the warning, the rest dim. */
+export declare function verdictTone(id: string, index: number): "good" | "warn" | "bad" | "dim";
+/** A taste test's pick, and what older documents kept per step. */
+export interface StepFeedback {
+    readonly pick?: string;
+    /** Older documents' verdict buttons. */
+    readonly verdict?: string;
+    /** Older documents' per-step note field. */
+    readonly note?: string;
+}
+/** Ink drawn over a step's media: SVG paths in 0–1 coordinates of the media's box. */
+export interface WalkInk {
+    readonly paths: readonly string[];
+    /** The box's width over height when drawn, to map the paths back. */
+    readonly aspect: number;
+}
+/** A voice note, recorded in the page: a blob URL that lives as long as the page. */
+export interface WalkVoice {
+    readonly url: string;
+    /** Seconds. */
+    readonly duration: number;
+    readonly mime?: string;
+}
+/** What the media on show was doing when Kit wrote. */
+export interface MediaContext {
+    /** "compare", "video", "diff"… */
+    readonly kind: string;
+    /** Seconds. */
+    readonly time?: number;
+    readonly duration?: number;
+    readonly playing?: boolean;
+    /** The loop range, in seconds. */
+    readonly loop?: {
+        readonly start: number;
+        readonly end: number;
+    };
+    /** A compare's mode. */
+    readonly mode?: string;
+    /** The part of the picture zoomed into, 0–1 of each side (`u`, `v` its top-left). */
+    readonly zoom?: {
+        readonly u: number;
+        readonly v: number;
+        readonly w: number;
+        readonly h: number;
+    };
+    /** The diff's file on show. */
+    readonly file?: string;
+    /** It was full-window. */
+    readonly full?: boolean;
+}
+/** One thing Kit did, in the rolling log a note carries. */
+export interface ContextEvent {
+    /** Epoch ms. */
+    readonly at: number;
+    readonly what: "step" | "seek" | "play" | "pause" | "file" | "mode" | "zoom" | "loop" | "full" | "pick" | "ink";
+    readonly step?: string;
+    /** Seconds, for seeks, plays and pauses. */
+    readonly time?: number;
+    readonly detail?: string;
+}
+export interface NoteContext {
+    /** The step in view. */
+    readonly step: string | null;
+    readonly media?: MediaContext;
+    /** What led up to it, oldest first. */
+    readonly log: readonly ContextEvent[];
+}
+/** A note Kit sent: words, a voice note, ink, or any mix, with what he was looking at. */
+export interface WalkNote {
+    readonly id: string;
+    readonly step: string | null;
+    /** Epoch ms. */
+    readonly at: number;
+    readonly text?: string;
+    readonly voice?: WalkVoice;
+    readonly ink?: WalkInk;
+    readonly context: NoteContext;
+}
+/** Everything Kit has said: picks by step, his notes in the order sent, a note on the whole. */
+export interface WalkthroughState {
+    readonly steps: Readonly<Record<string, StepFeedback>>;
+    readonly notes?: readonly WalkNote[];
+    readonly note?: string;
+}
+export declare const EMPTY_STATE: WalkthroughState;
+/** A step's pick (or older fields) changed: blanks drop, and a step with nothing left goes. */
+export declare function setFeedback(state: WalkthroughState, key: string, patch: Partial<Record<keyof StepFeedback, string | null>>): WalkthroughState;
+/** The whole page's note. */
+export declare function setNote(state: WalkthroughState, note: string): WalkthroughState;
+/** Whether a note has anything in it. */
+export declare const hasContent: (n: Pick<WalkNote, "text" | "voice" | "ink">) => boolean;
+export declare function addNote(state: WalkthroughState, note: WalkNote): WalkthroughState;
+export declare function removeNote(state: WalkthroughState, id: string): WalkthroughState;
+/** A step's notes, in the order sent. */
+export declare const notesOn: (state: WalkthroughState, key: string) => WalkNote[];
+/** Whether Kit has answered a step: picked, written, or (older documents) given a verdict. */
+export declare function isAnswered(step: WalkStep, state: WalkthroughState): boolean;
+/**
+ * A digit's pick on a taste test (1 the first option): the id it sets, or null when it's the one
+ * already picked (pressing it again clears it); undefined when there's none.
+ */
+export declare function digitChoice(step: WalkStep, fb: StepFeedback | undefined, key: string): string | null | undefined;
+/** Steps that ask for something, how many are answered, and the first still open. */
+export declare function walkthroughProgress(w: WalkPage, state: WalkthroughState): {
+    done: number;
+    total: number;
+    next: string | null;
+};
+/** The step before or after `current` (stopping at the ends); the first when there's none. */
+export declare function adjacentStep(keys: readonly string[], current: string | null, dir: -1 | 1): string | undefined;
+/** How many events the log keeps. */
+export declare const LOG_MAX = 40;
+/**
+ * The log with `event` on the end: a seek straight after another on the same step replaces it
+ * (a scrub is one entry), and only the last `max` stay.
+ */
+export declare function pushContext(log: readonly ContextEvent[], event: ContextEvent, max?: number): ContextEvent[];
+/** What a note carries of the log: the last `windowMs`, at least the last `min` events. */
+export declare function recentContext(log: readonly ContextEvent[], now: number, windowMs?: number, min?: number): ContextEvent[];
+/** Seconds as `m:ss.s`. */
+export declare function formatTime(seconds: number): string;
+/**
+ * A stroke as an SVG path in 0–1 coordinates of a `w`×`h` box (three decimals), dropping points
+ * closer than a pixel to the last kept one.
+ */
+export declare function inkPath(points: readonly {
+    x: number;
+    y: number;
+}[], w: number, h: number): string;
+/** A zoom region in words: "2× at 25%, 10%" (its top-left, as a share of the picture). */
+export declare function zoomWords(z: {
+    u: number;
+    v: number;
+    w: number;
+    h: number;
+}): string;
+/** A media context in a few words: "compare at 0:04.2 (loop 0:02.0–0:06.0), wipe". */
+export declare function describeMedia(m: MediaContext | undefined): string;
+/**
+ * Saved feedback read back: anything malformed is dropped rather than trusted, and steps the
+ * document no longer has are kept (an agent's next draft may bring them back).
+ */
+export declare function readState(raw: string | null | undefined): WalkthroughState;
+/** A note as the agent reads it. */
+export interface FeedbackNote {
+    /** ISO time. */
+    readonly at: string;
+    readonly text?: string;
+    readonly voice?: WalkVoice;
+    readonly ink?: WalkInk;
+    readonly media?: MediaContext;
+    /** What led up to it: seconds before the note, oldest first. */
+    readonly log: readonly (Omit<ContextEvent, "at"> & {
+        readonly ago: number;
+    })[];
+}
+/** One step's line in the feedback. */
+export interface FeedbackItem {
+    readonly key: string;
+    readonly number: string;
+    readonly section: string;
+    readonly title: string;
+    readonly ask: "note" | "pick" | "none";
+    readonly pick?: string;
+    readonly pickLabel?: string;
+    /** The option the agent suggested, when Kit picked another. */
+    readonly suggested?: string;
+    readonly notes: readonly FeedbackNote[];
+    /** Older documents' verdict and note, when there are any. */
+    readonly verdict?: string;
+    readonly note?: string;
+}
+/** What a page hands back to the agent: every asked step (open ones with nothing in them). */
+export interface WalkthroughFeedback {
+    readonly id: string;
+    readonly title: string;
+    readonly reviewed: number;
+    readonly total: number;
+    readonly note?: string;
+    readonly steps: readonly FeedbackItem[];
+    /** Notes sent with no step in view. */
+    readonly general: readonly FeedbackNote[];
+}
+/** Kit's feedback on `w`, step by step in reading order. */
+export declare function collectFeedback(w: WalkPage, state: WalkthroughState): WalkthroughFeedback;
+/**
+ * The feedback as Markdown to paste back to the agent: a heading per section, a line per step
+ * (its pick in bold, open ones marked), its notes under it with what Kit was looking at.
+ */
+export declare function feedbackMarkdown(fb: WalkthroughFeedback, verdicts?: readonly WalkVerdict[]): string;
+/**
+ * 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.
+ */
+export declare function inlineMarkdown(text: string): string;
+export {};

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

@@ -0,0 +1,63 @@
+import { type StoragePort } from "../core/storage.js";
+import { type UiLook } from "./look.js";
+import { type MediaSlot } 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)[];
+    readonly picked?: string | null;
+    /** A click picked an option (or, on the picked one, cleared it). */
+    readonly onPick?: (id: string | null) => void;
+    /** Mount each option's media when near the view (on by default). */
+    readonly lazy?: boolean;
+}
+export interface TasteTest {
+    readonly element: HTMLElement;
+    readonly picked: string | null;
+    /** The options' media, in order (those with any). */
+    readonly slots: readonly MediaSlot[];
+    pick(id: string | null): void;
+    /** Pauses the options' videos. */
+    pause(): void;
+    dispose(): void;
+}
+/**
+ * A vs B (or more): each option's letter, label and media side by side (stacking where it's
+ * narrow). The picked one takes a check and a wash; the others step back.
+ */
+export declare function tasteTest(container: HTMLElement, options: TasteTestOptions): TasteTest;
+export interface WalkthroughOptions extends UiLook {
+    readonly doc: WalkthroughDoc;
+    /** Where Kit's answers are kept (localStorage by default; `null` keeps none). */
+    readonly storage?: StoragePort | null;
+    /** Every change to Kit's answers, as the agent reads them. */
+    readonly onFeedback?: (feedback: WalkthroughFeedback) => void;
+    /** The page's keys (on by default). */
+    readonly keys?: boolean;
+    /** The contents and progress rail (on by default). */
+    readonly rail?: boolean;
+    /** Sending a note moves on to the next step (on by default). */
+    readonly advance?: boolean;
+}
+export interface Walkthrough {
+    readonly element: HTMLElement;
+    /** The document, filled in. */
+    readonly page: WalkPage;
+    readonly state: WalkthroughState;
+    readonly feedback: WalkthroughFeedback;
+    /** The step Kit is on (its key); null above the first. */
+    readonly current: string | null;
+    /** The feedback as Markdown, for the agent. */
+    markdown(): string;
+    /** Goes to a step (its key), the page gliding to it. */
+    go(key: string): void;
+    /** The current step full-window (`true`), back in the page (`false`), or the other way. */
+    full(on?: boolean): void;
+    /** Sends a note from the page's code, as the bar would: on the current step, with its context. */
+    send(text: string): void;
+    /** A new draft of the document: answers carry over by step key. */
+    set(doc: WalkthroughDoc): void;
+    /** Forgets every answer. */
+    reset(): void;
+    dispose(): void;
+}
+export declare function walkthrough(container: HTMLElement, options: WalkthroughOptions): Walkthrough;