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

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

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

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

@@ -8,15 +8,17 @@ export { commandPalette, type Command, type CommandPalette, type CommandPaletteO
 export { contextMenu, menu, type ContextMenu, type ContextMenuOptions, type Menu, type MenuCloseReason, type MenuEntry, type MenuItem, type MenuOptions, } from "./menu.js";
 export { popover, type Popover, type PopoverCloseReason, type PopoverOptions } from "./popover.js";
 export { readout, type Readout } from "./readouts.js";
+export { icon, ICON_NAMES, type IconName } from "./icons.js";
+export { planPill, pillBoxOf, pillProgress, pillRadius, pillSpring, selectionPill, type PillBox, type PillPlan, type SelectionPill, type SelectionPillOptions, } from "./selection-pill.js";
 export { toast, type Toast, type ToastOptions } from "./toast.js";
 export { tooltip, tooltips, type TooltipContent, type TooltipOptions } from "./tooltip.js";
 export { split, type PaneAction, type PaneOptions, type Split, type SplitFold, type SplitOptions, type SplitPane, } from "./split.js";
 export { COLLAPSE_PAST, drag as dragDivider, parseLayout, softClamp, solve as solveSplit, type PaneSpec, type SplitDirection, type SplitLayout, } from "./split-model.js";
 export { timeline, type SeekSource, type Timeline, type TimelineMarker, type TimelineListener, type TimelineOptions, type TimelineRange, } from "./timeline.js";
-export { adjacentMarker, advance, clampView, followView, frameTime, magnet, rulerTicks, scrubTime, timeLabel, toFrame, zoomView, type Tick, type Ticks, type TimeUnits, type TimeView, } from "./timeline-model.js";
+export { adjacentMarker, advance, CATCH_UP, clampView, currentMarker, followView, frameTime, magnet, moveHead, rulerTicks, scrubTime, timeLabel, toFrame, zoomView, type HeadPosition, type Tick, type Ticks, type TimeUnits, type TimeView, } from "./timeline-model.js";
 export { compare, COMPARE_FFMPEG, type Compare, type CompareLoop, type CompareMode, type CompareOptions, type CompareSource, type CompareView, type MediaKind, type ZoomRegion, } from "./compare.js";
 export { compareStrip, type CompareStrip, type CompareStripOptions } from "./compare-strip.js";
-export { compareLayout, frameMidpoint, frameOf, letterbox, mediaKind, meanAbsDiff, requestSeek, seeked, seekTime, stripColumns, stripPeaks, syncAction, wipeAt, wipeGrab, wipeKey, wipeX, zoomAbout, type CompareLayout, type SeekState, type StripColumn, type SyncAction, } from "./compare-model.js";
+export { compareLayout, compareModes, frameMidpoint, frameOf, gripTop, letterbox, mediaKind, meanAbsDiff, modeForKey, requestSeek, seamLabels, seeked, seekTime, stripColumns, stripPeaks, syncAction, wipeAt, wipeGrab, wipeKey, wipeX, zoomAbout, type CompareLayout, type SeekState, type StripColumn, type SyncAction, } from "./compare-model.js";
 export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle } from "./tree.js";
 export { applyMove, plainAccess, dropTarget, flatten, indexTree, matchLabel, navigate, select, stepMove, topmost, typeahead, validMove, virtualWindow, type DropTarget, type FlatRow, type Selection, type TreeAccess, type TreeFilter, type TreeMove, } from "./tree-model.js";
 export { codeDiff, diffCounts, diffReview, diffStatus, type CodeDiff, type CodeDiffOptions, type CodeDiffUpdate, type DiffLayout, type DiffLines, type DiffReview, type DiffReviewOptions, } from "./diff.js";

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

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

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

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

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

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

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

@@ -45,6 +45,13 @@ export interface TimelineOptions extends UiLook {
         readonly step: number;
         readonly shift: number;
     };
+    /**
+     * `"editor"` (the default): a ruler with labels over a lane of markers to add, drag and name,
+     * zoomed and panned by the wheel. `"lane"`: one slim lane under a compare or a video, with ticks
+     * and no labels, markers as faint chapter ticks (the current one in text colour), nothing to
+     * edit, and the wheel left to the page.
+     */
+    readonly variant?: "editor" | "lane";
     readonly label?: string;
     /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
     onSeek?(time: number, source: SeekSource): void;
@@ -82,7 +89,10 @@ export interface Timeline {
     readonly markers: readonly TimelineMarker[];
     readonly ranges: readonly TimelineRange[];
     readonly view: TimeView;
-    /** `glide`: the playhead springs there (the time, and what it drives, land at once). */
+    /**
+     * `glide`: a jump the hand didn't make (a chapter's click, say): the playhead catches up from
+     * where it is on a quick spring; the time, and what it drives, land at once.
+     */
     seek(time: number, options?: {
         readonly glide?: boolean;
     }): void;

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

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

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

@@ -1,4 +1,9 @@
 import { type ContextEvent, type WalkChapter, type WalkMedia } from "./walkthrough-model.js";
+/** The glyphs the blocks draw. */
+export declare const GLYPH: {
+    go: string;
+    caret: string;
+};
 /** 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. */
@@ -17,6 +22,8 @@ export interface Block {
         kind: string;
     };
 }
+/** A small arrow that goes to the step a ref names; null when it names none. */
+export declare function stepButton(doc: Document, ref: string | undefined, steps: StepLinks | undefined): HTMLButtonElement | null;
 export declare function mountHistory(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "history";
 }>, steps: StepLinks | undefined): Block;
@@ -27,7 +34,7 @@ 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. */
+    /** The chapter the time is in (call as it plays or seeks): the pill slides to it. */
     sync(): void;
     /** The chapter playing, or null. */
     readonly current: WalkChapter | null;
@@ -40,4 +47,16 @@ export declare function chapterPills(host: HTMLElement, chapters: readonly WalkC
     seek(time: number): void;
     onEvent: OnEvent;
 }): ChapterPills;
+export interface Disclosure {
+    readonly element: HTMLElement;
+    readonly open: boolean;
+    toggle(open?: boolean): void;
+    dispose(): void;
+}
+export declare function disclosure(host: HTMLElement, options: {
+    label: string;
+    count?: number;
+    open?: boolean;
+    content: HTMLElement;
+}): Disclosure;
 export {};

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

@@ -144,6 +144,14 @@ export type WalkthroughMedia = string | {
     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;
@@ -205,8 +213,12 @@ 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 media after the first fold away under a quiet toggle with these words ("More clips"). */
+    readonly more?: string;
     /** A taste test: Kit picks one. */
     readonly options?: readonly WalkthroughOption[];
     /**
@@ -225,6 +237,11 @@ 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;
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
     readonly steps: readonly WalkthroughStep[];
@@ -241,6 +258,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 {
@@ -249,6 +270,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 {
@@ -266,6 +291,15 @@ 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;
     readonly sections: readonly WalkthroughSection[];
 }
 type CompareMedia = Extract<WalkthroughMedia, {
@@ -342,6 +376,9 @@ export type WalkMedia = Exclude<WalkthroughMedia, string | {
     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;
@@ -363,6 +400,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";
 }
@@ -373,6 +413,8 @@ 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 steps: readonly WalkStep[];
@@ -391,6 +433,8 @@ 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;
@@ -470,6 +514,18 @@ 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;
+/** 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. */
@@ -677,5 +733,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 {};

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

@@ -35,8 +35,16 @@ export interface WalkthroughOptions extends UiLook {
     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;
+    /** The contents and progress rail (on by default), beside the column on the right or left. */
+    readonly rail?: boolean | "right" | "left";
+    /** Each step on a card of its own (off by default: steps sit on the page, hairlines between). */
+    readonly cards?: boolean;
+    /**
+     * The note bar: a small launcher in the column's corner that opens into the bar on a click, n,
+     * a recording or ink, and folds back when it's empty (`"collapsed"`, the default); the bar
+     * always there (`"docked"`); or none (`"hidden"`; `send()` still works).
+     */
+    readonly noteBar?: "collapsed" | "docked" | "hidden";
     /** Sending a note moves on to the next step (on by default). */
     readonly advance?: boolean;
 }