@kitlangton/knobs 0.3.0 → 0.4.0-next.0

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

@@ -0,0 +1,169 @@
+import type { TimeView } from "./timeline-model.js";
+export type CompareMode = "side" | "wipe" | "difference" | "flicker";
+export type MediaKind = "video" | "image";
+/** A source's kind: as given, else by its extension (a video's, or an image). */
+export declare function mediaKind(src: string, kind?: MediaKind): MediaKind;
+/** The frame showing at time `t` (whole frames, never negative). */
+export declare const frameOf: (t: number, fps: number) => number;
+/** The last whole frame of `duration` seconds. */
+export declare const lastFrame: (duration: number, fps: number) => number;
+/**
+ * The time a video seeks to for frame `f`: its midpoint, `(f + 0.5) / fps`, which never lands on a
+ * frame boundary, so two decoders can't round to different frames. Clamped to the last frame.
+ */
+export declare function frameMidpoint(f: number, fps: number, duration?: number): number;
+/** Where both videos seek to show time `t`: the midpoint of the frame it falls in. */
+export declare const seekTime: (t: number, fps: number, duration?: number) => number;
+/** Whether two times show the same frame (a seek between them presents nothing new). */
+export declare const sameFrame: (a: number, b: number, fps: number) => boolean;
+export interface SyncAction {
+    /** Hard-seek the follower here (seconds), or leave it playing. */
+    readonly seekTo: number | null;
+    readonly rate: number;
+}
+/**
+ * Keeps a playing follower on its master: past `hard` seconds of drift (90 ms) it seeks; otherwise
+ * its rate leans against the drift, proportionally (`gain` per second of drift), by at most `max`
+ * (±25%), and inside `dead` (1/120 s) it plays at the base rate.
+ */
+export declare function syncAction(master: number, follower: number, o?: {
+    rate?: number;
+    hard?: number;
+    gain?: number;
+    max?: number;
+    dead?: number;
+}): SyncAction;
+/**
+ * One video's seeks, coalesced: while one is in flight only the latest target is kept, applied when
+ * it lands; holding a step key walks frames instead of queueing seeks.
+ */
+export interface SeekState {
+    readonly seeking: boolean;
+    /** The latest target asked for while a seek was in flight. */
+    readonly pending: number | null;
+}
+export declare const SEEK_IDLE: SeekState;
+export interface SeekStep {
+    readonly state: SeekState;
+    /** Set `currentTime` to this now, or nothing. */
+    readonly apply: number | null;
+    /** The frame asked for is already showing: no seek, and no frame callback will come. */
+    readonly settled: boolean;
+}
+/** A seek to `t` asked for while the video shows `current`. */
+export declare function requestSeek(s: SeekState, t: number, current: number, fps: number): SeekStep;
+/** The seek in flight landed on `current`: apply what's pending, if it's another frame. */
+export declare function seeked(s: SeekState, current: number, fps: number): SeekStep;
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface Size {
+    readonly w: number;
+    readonly h: number;
+}
+/** `media` fitted inside `box`, centred: the whole of it shows, letterboxed, never cropped. */
+export declare function letterbox(media: Size, box: Rect): Rect;
+export interface CompareLayout {
+    /**
+     * Side by side: a split screen down the middle, the pair fitted as a whole (After's shape, two
+     * up), each side in its half; `split` is the middle's x.
+     */
+    readonly side: {
+        readonly before: Rect;
+        readonly after: Rect;
+        readonly split: number;
+    };
+    /** Overlaid (wipe, difference, flicker): both in the same place. */
+    readonly overlay: {
+        readonly before: Rect;
+        readonly after: Rect;
+    };
+}
+/** Where the two sides sit inside `box`, side by side and overlaid. */
+export declare function compareLayout(box: Rect, before: Size, after: Size): CompareLayout;
+/** The height a split screen of `w` needs so neither side has margins: half its width, in shape. */
+export declare const splitHeight: (w: number, media: Size) => number;
+/**
+ * The part of each side shown, in that side's own 0–1 coordinates: `w` and `h` are equal (1 is
+ * the whole picture, 0.25 is 400%). Both sides show the same part.
+ */
+export interface ZoomRegion {
+    readonly u: number;
+    readonly v: number;
+    readonly w: number;
+    readonly h: number;
+}
+export declare const ZOOM_FIT: ZoomRegion;
+/** 1600% at most. */
+export declare const ZOOM_MAX = 16;
+/** Kept inside the picture, between the whole of it and `ZOOM_MAX`. */
+export declare function clampZoom(r: {
+    u: number;
+    v: number;
+    w: number;
+}): ZoomRegion;
+/** Zoomed by `factor` (above 1 in) about a point at `pu`, `pv` (0–1 across the shown part). */
+export declare function zoomAbout(r: ZoomRegion, factor: number, pu: number, pv: number): ZoomRegion;
+/** Panned by a hand's move of `dx`, `dy` px over a side drawn `base` big: the picture follows it. */
+export declare const panBy: (r: ZoomRegion, dx: number, dy: number, base: Rect) => ZoomRegion;
+/** Where a side drawn in `base` lands when zoomed to `r` (clipped to `base` when drawn). */
+export declare const zoomedRect: (base: Rect, r: ZoomRegion) => Rect;
+/** A point's place across `base` (0–1 each way). */
+export declare const pointIn: (base: Rect, x: number, y: number) => {
+    pu: number;
+    pv: number;
+};
+/** A loop's window around `time`: a fifth of the length, 1–4 s, inside it. */
+export declare function loopAround(time: number, duration: number): {
+    start: number;
+    end: number;
+};
+export declare const lerpRect: (a: Rect, b: Rect, k: number) => Rect;
+/** The wipe's line across `rect`: Before shows left of it, After right. */
+export declare const wipeX: (rect: Rect, wipe: number) => number;
+/** The wipe a pointer at `x` (less the grab's offset) puts it at. */
+export declare const wipeAt: (x: number, rect: Rect, offset?: number) => number;
+/**
+ * A press at `x`: on the line (within `slop` px) it takes hold where it is, so the line doesn't
+ * jump under the hand; elsewhere the line comes to the pointer.
+ */
+export declare function wipeGrab(x: number, rect: Rect, wipe: number, slop?: number): {
+    onLine: boolean;
+    offset: number;
+};
+/** The wipe moved by a key: 1% a press, 10% with Shift. */
+export declare const wipeKey: (wipe: number, dir: -1 | 1, big?: boolean) => number;
+export interface StripColumn {
+    /** The frame it samples: its first, so zooming in by two keeps every other sample. */
+    readonly frame: number;
+    /** Seconds: that frame's midpoint. */
+    readonly time: number;
+    /** Its first frame and the one after its last. */
+    readonly from: number;
+    readonly to: number;
+    readonly x: number;
+    readonly w: number;
+}
+/**
+ * The frame strip's columns across `width` px of the timeline's view: each spans a power-of-two
+ * number of frames, at least `minWidth` px wide, on a grid fixed to frame 0, sampling its first
+ * frame, so panning reuses the samples it has and zooming in by two keeps half of them.
+ */
+export declare function stripColumns(view: TimeView, width: number, o: {
+    duration: number;
+    fps: number;
+    minWidth: number;
+}): StripColumn[];
+/** Mean absolute difference of two RGBA buffers' colour, 0 (same) to 1. */
+export declare function meanAbsDiff(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * The columns worth a marker: where the difference peaks (no less than either neighbour), above
+ * `threshold` and at least `ratio` of the largest.
+ */
+export declare function stripPeaks(diffs: readonly (number | undefined)[], o?: {
+    threshold?: number;
+    ratio?: number;
+}): number[];

package/dist/types/ui/compare-mp4.d.ts

@@ -0,0 +1,29 @@
+export interface Mp4Sample {
+    readonly offset: number;
+    readonly size: number;
+    /** Seconds, after the edit list: when it shows. */
+    readonly pts: number;
+    readonly duration: number;
+    readonly key: boolean;
+}
+export interface Mp4Track {
+    /** A WebCodecs codec string (`avc1.64001f`, `hvc1.1.6.L93.B0`). */
+    readonly codec: string;
+    readonly description: Uint8Array | undefined;
+    readonly width: number;
+    readonly height: number;
+    /** In decode order. */
+    readonly samples: readonly Mp4Sample[];
+}
+/** Parses `buf` (a whole file); null when it isn't a plain MP4 with a video track it knows. */
+export declare function demuxMp4(buf: ArrayBuffer): Mp4Track | null;
+/**
+ * The runs to decode for some frames: for each keyframe group (decode order, from a keyframe to
+ * the next) holding a wanted presentation index, its sample range. `frameOf` maps a sample's
+ * time to the frame it is.
+ */
+export declare function decodeRuns(samples: readonly Mp4Sample[], wanted: ReadonlySet<number>, frameOf: (pts: number) => number): {
+    from: number;
+    to: number;
+    frames: number[];
+}[];

package/dist/types/ui/compare-strip.d.ts

@@ -0,0 +1,28 @@
+import type { CompareSource } from "./compare.js";
+import { type UiLook } from "./look.js";
+import type { Timeline } from "./timeline.js";
+export interface CompareStripOptions extends UiLook {
+    readonly before: CompareSource;
+    readonly after: CompareSource;
+    /** The time axis: its view, time and duration; a press here seeks it. */
+    readonly timeline: Timeline;
+    /** The timeline's by default. */
+    readonly fps?: number;
+    /** Columns under the timeline's track (`"track"`, the default) or across the strip's own width. */
+    readonly align?: "track" | "self";
+    /** Differences below this (0–1) never peak. */
+    readonly threshold?: number;
+    /** A press or drag picked a time. */
+    onPick?(time: number): void;
+}
+export interface CompareStrip {
+    readonly element: HTMLElement;
+    /** Each column's difference (by the frame it samples), 0 (same) to 1. */
+    readonly diffs: ReadonlyMap<number, number>;
+    update(next: {
+        before?: CompareSource;
+        after?: CompareSource;
+    }): void;
+    dispose(): void;
+}
+export declare function compareStrip(container: HTMLElement, options: CompareStripOptions): CompareStrip;

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

@@ -0,0 +1,103 @@
+import { type CompareMode, type MediaKind, type ZoomRegion } from "./compare-model.js";
+import { type CompareStrip } from "./compare-strip.js";
+import { type UiLook } from "./look.js";
+import { type Timeline } from "./timeline.js";
+export type { CompareMode, MediaKind, ZoomRegion } from "./compare-model.js";
+/** A loop's in and out (seconds). */
+export interface CompareLoop {
+    readonly start: number;
+    readonly end: number;
+}
+/** What's in view: the zoomed part (both sides) and the loop, for a log or a note. */
+export interface CompareView {
+    readonly zoom: ZoomRegion;
+    readonly loop: CompareLoop | null;
+}
+/**
+ * How to encode recordings for review: constant frame rate and a keyframe every 15 frames, so a
+ * seek lands on the exact frame almost at once. Raw screen recordings often have one keyframe in
+ * 8–18 s; the viewer copes (it shows decoded frames while seeks land), but this makes it exact.
+ */
+export declare const COMPARE_FFMPEG = "ffmpeg -i in.mov -vf fps=30 -fps_mode cfr -c:v libx264 -preset slow -crf 18 -g 15 -keyint_min 15 -pix_fmt yuv420p -movflags +faststart -an out.mp4";
+export interface CompareSource {
+    readonly src: string;
+    /** From the extension when left out (`.mp4`, `.webm`, `.mov`… are videos). */
+    readonly kind?: MediaKind;
+    /** "Before" and "After" by default. */
+    readonly label?: string;
+}
+export interface CompareOptions extends UiLook {
+    readonly before: CompareSource;
+    readonly after: CompareSource;
+    /** `"side"` (side by side) by default. */
+    readonly mode?: CompareMode;
+    /** Where the wipe's line sits, 0 (all After) to 1 (all Before); 0.5. */
+    readonly wipe?: number;
+    /** Frames per second (the bound timeline's, else 30): steps, and where paused videos land. */
+    readonly fps?: number;
+    /** The loupe under the pointer (`Z` held shows it too). */
+    readonly loupe?: boolean;
+    /** Difference mode hides changes below this (0–1, 4/255): codec noise. */
+    readonly threshold?: number;
+    /**
+     * The clock: an existing `timeline()` (its time drives both sides; while playing it follows
+     * After), or `true` for one of its own under the viewer. Without one, `seek`, `play` and keys
+     * still work.
+     */
+    readonly timeline?: Timeline | boolean;
+    /** The frame strip over the timeline (off; one timeline is made if there's none). */
+    readonly strip?: boolean;
+    /**
+     * The sources' width over height before they load (16/9). In a container without a height of
+     * its own, the viewer takes the height its sides need: a split screen with no margins.
+     */
+    readonly aspect?: number;
+    /** Load sources only near the screen and let them go well off it (true). */
+    readonly lazy?: boolean;
+    /** `"gpu"` (the default, where WebGPU is there) or `"dom"`. */
+    readonly renderer?: "gpu" | "dom";
+    readonly label?: string;
+    /** The modes, the loupe and the wipe take codes in the page's hint mode (`s`); on by default. */
+    readonly hints?: boolean;
+    onMode?(mode: CompareMode): void;
+    /** The wipe moved: dragged, keyed or set. */
+    onWipe?(wipe: number): void;
+    /** The zoom or the loop changed (at most once a frame). */
+    onView?(view: CompareView): void;
+}
+export interface Compare {
+    readonly element: HTMLElement;
+    readonly mode: CompareMode;
+    readonly wipe: number;
+    readonly loupe: boolean;
+    /** Seconds. */
+    readonly time: number;
+    readonly playing: boolean;
+    /** The longer video's, in seconds (0 for two images). */
+    readonly duration: number;
+    readonly renderer: "gpu" | "dom";
+    /** The bound timeline, or the one it made. */
+    readonly timeline: Timeline | null;
+    readonly strip: CompareStrip | null;
+    /** The part of each side in view (`{ u: 0, v: 0, w: 1, h: 1 }` is all of it). */
+    readonly zoom: ZoomRegion;
+    /** The timeline's loop, or null. */
+    readonly loop: CompareLoop | null;
+    /** New sources, mode, wipe, loupe, threshold or fps. A new mode glides in. */
+    update(next: Partial<Pick<CompareOptions, "before" | "after" | "mode" | "wipe" | "loupe" | "threshold" | "fps">>): void;
+    seek(time: number): void;
+    /** Moves by `seconds`, the timeline's playhead gliding there (playing carries on). */
+    seekBy(seconds: number): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Steps whole frames (pausing first). */
+    step(frames: number): void;
+    /** Zooms both sides to `region` (null: all of it), gliding there unless `animate` is false. */
+    setZoom(region: ZoomRegion | null, animate?: boolean): void;
+    /** A loop around the playhead (`true`), a given one, or none; playback stays inside it. */
+    setLoop(loop: CompareLoop | boolean): void;
+    focus(): void;
+    dispose(): void;
+}
+export declare function compare(container: HTMLElement, options: CompareOptions): Compare;

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

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

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

@@ -0,0 +1,128 @@
+/** A file as before and after text. */
+export interface DiffSource {
+    /** Its path, which is its id. */
+    readonly name: string;
+    readonly before: string;
+    readonly after: string;
+    /** A Shiki language id, when the extension doesn't say. */
+    readonly lang?: string;
+}
+/** What a diff takes: a unified patch (`git diff`, `git show`, one file or many) or pairs. */
+export interface DiffInput {
+    readonly patch?: string;
+    readonly files?: readonly DiffSource[];
+}
+export type DiffChange = "change" | "new" | "deleted" | "rename";
+export interface DiffFile {
+    /** Its path after the change (before it, for a deleted file): the file's id. */
+    readonly name: string;
+    /** Its path before a rename. */
+    readonly prevName?: string;
+    readonly change: DiffChange;
+    readonly additions: number;
+    readonly deletions: number;
+    readonly binary?: boolean;
+    /** Its own part of the patch, headers and hunks. */
+    readonly patch?: string;
+    readonly before?: string;
+    readonly after?: string;
+    readonly lang?: string;
+    /** The rows its diff takes once drawn (see `DiffRows`). */
+    readonly rows?: DiffRows;
+}
+/**
+ * How tall a file's diff is once drawn, in rows: each layout's lines (`split` pairs a removed
+ * line with an added one) and the separators that stand for unchanged lines between hunks. A
+ * card reserves this much before the renderer has loaded, so nothing jumps when it does.
+ */
+export interface DiffRows {
+    readonly unified: number;
+    readonly split: number;
+    readonly separators: number;
+}
+/** The context lines a patch made from before and after text keeps around each change. */
+export declare const DIFF_CONTEXT = 3;
+/**
+ * The files in a unified patch, in its order, with lines added and removed counted from the
+ * hunks. Takes `git diff`, `git show` and `format-patch` output (anything before the first
+ * file, a commit's header and message, is skipped) and plain `diff -u` output.
+ */
+export declare function parsePatch(patch: string): DiffFile[];
+/** Lines one side has that the other doesn't, by a shortest edit (Myers), as a patch counts them. */
+export declare function countChanges(before: string, after: string): {
+    additions: number;
+    deletions: number;
+};
+/** What a patch made from before and after text would show: its counts and its rows. */
+export declare function compareText(before: string, after: string, context?: number): {
+    additions: number;
+    deletions: number;
+    rows: DiffRows;
+};
+/**
+ * The rows of a patch over whole files: changes with `context` unchanged lines around them,
+ * changes no more than twice that apart in one hunk, and a separator for each run of
+ * unchanged lines left out (before, between and after the hunks).
+ */
+export declare function hunkRows(ops: ArrayLike<number>, context?: number): DiffRows;
+/**
+ * A fingerprint of a file's change (its part of the patch, or its before and after text), so a
+ * file marked viewed comes back unviewed once its diff changes.
+ */
+export declare function fileKey(file: DiffFile): string;
+/**
+ * Orders paths as a file tree shows them: at each level folders first, then files, each by
+ * name (natural order, so `file2` comes before `file10`).
+ */
+export declare function comparePaths(a: string, b: string): number;
+/** A diff's files in tree order, counted: from the patch, or from each pair's text. */
+export declare function diffFiles(input: DiffInput): DiffFile[];
+/** Lines added and removed across the files. */
+export declare function diffStats(files: readonly DiffFile[]): {
+    files: number;
+    additions: number;
+    deletions: number;
+};
+/** A path as the folder it's in and its own name. */
+export declare function splitPath(name: string): {
+    dir: string;
+    base: string;
+};
+/** A row of a diff's file tree: a folder (one or more path segments) or a file. */
+export interface DiffTreeItem {
+    /** A file's name, or `dir:` and a folder's path. */
+    readonly id: string;
+    readonly label: string;
+    /** The folder's path, or the file's. */
+    readonly path: string;
+    readonly file?: DiffFile;
+    readonly children?: readonly DiffTreeItem[];
+}
+/**
+ * The files as tree items: folders hold what's in them, and a folder whose only child is a
+ * folder joins it (`src` › `ui` is one row, `src/ui`), so short trees stay flat.
+ */
+export declare function diffTree(files: readonly DiffFile[]): DiffTreeItem[];
+/** Every folder's id in a diff tree (to open them all). */
+export declare function diffFolders(items: readonly DiffTreeItem[]): string[];
+/**
+ * Which file to show once the list changes: the same one if it's still there; else the one now
+ * where it was (the next, or the last); else the first. Null with no files.
+ */
+export declare function keepFile(prev: readonly DiffFile[], next: readonly DiffFile[], current: string | null | undefined): string | null;
+/** The file before or after `current`, stopping at the ends. */
+export declare function stepFile(files: readonly DiffFile[], current: string | null | undefined, dir: -1 | 1): string | null;
+/**
+ * A change as a bar of `cells` squares, as GitHub draws one: how many show added, how many
+ * removed and how many neither. A change smaller than the bar fills one square a line; each side
+ * that has lines keeps at least one.
+ */
+export declare function diffBar(additions: number, deletions: number, cells?: number): [number, number, number];
+/** Whether a path has every word of a query in it, any case: `ui diff` finds `src/ui/diff.ts`. */
+export declare function matchPath(path: string, query: string): boolean;
+/** The files still viewed: those saved viewed whose change is the one saved (see `fileKey`). */
+export declare function stillViewed(saved: Readonly<Record<string, string>>, files: readonly DiffFile[]): Set<string>;
+/** What to save for the files viewed: each one's name and the key of its change. */
+export declare function saveViewed(viewed: Iterable<string>, files: readonly DiffFile[]): Record<string, string>;
+/** The files under a tree item (itself, for a file). */
+export declare function filesUnder(item: DiffTreeItem): string[];

package/dist/types/ui/diff-scroll.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The CSS to hand the renderer: its code columns' native scrollbars hidden (`codeBars` draws
+ * thin ones), and every corner its stylesheet rounds by 6px rounded by `--kd-inner` instead, so
+ * a hunk separator inset in the card is concentric with it. Read once from its stylesheet.
+ */
+export declare function rendererCss(coreCss: () => string): string;
+export interface CodeBars {
+    /** Looks for the code columns again (after a render) and places their bars. */
+    rescan(): void;
+    place(): void;
+    dispose(): void;
+}
+/**
+ * Thin bars for the code columns' sideways scroll (one per column; two when split), drawn in
+ * `layer` (a positioned element inside the scroller) at the bottom of what shows of each
+ * column, so the bar is in view however far down a long file you are. Hidden until the pointer
+ * is over the diff, or while you scroll the code sideways or drag a bar, as `overlayScrollbar`'s.
+ */
+export declare function codeBars(scroller: HTMLElement, layer: HTMLElement, root: () => ShadowRoot | null | undefined): CodeBars;
+export interface EdgeFades {
+    update(): void;
+    dispose(): void;
+}
+/**
+ * Marks a scroller `data-fade-top` once it's scrolled and `data-fade-bottom` while there's more
+ * below, for the CSS that fades its content out at that edge (a mask, its stops on registered
+ * properties so they ease in and out).
+ */
+export declare function edgeFades(scroller: HTMLElement, content: Element): EdgeFades;

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

@@ -0,0 +1,158 @@
+import { type StoragePort } from "../core/storage.js";
+import { type DiffFile, type DiffSource, type DiffTreeItem } from "./diff-model.js";
+import { type UiLook } from "./look.js";
+import { type Tree } from "./tree.js";
+export type DiffLayout = "split" | "unified";
+/** Lines picked in a diff (`onLines`): a range on one side, or across both. */
+export interface DiffLines {
+    readonly start: number;
+    readonly end: number;
+    readonly side?: "deletions" | "additions";
+    readonly endSide?: "deletions" | "additions";
+}
+export interface CodeDiffOptions extends UiLook {
+    /** A unified patch: `git diff` or `git show` output, one file or many. */
+    readonly patch?: string;
+    /** Or files as before and after text (`patch` wins when both are set). */
+    readonly files?: readonly DiffSource[];
+    /** The file on show (its path); the first unless set. */
+    readonly file?: string | null;
+    /** Side by side (default) or one column. */
+    readonly layout?: DiffLayout;
+    /** Long lines wrap instead of scrolling sideways. */
+    readonly wrap?: boolean;
+    /**
+     * `"fill"` (default): the card fills its container and the diff scrolls inside it. `"auto"`:
+     * the card is as tall as the file's diff, up to `maxHeight`, and springs to each new height;
+     * it holds the height the diff will take from the start, so a page doesn't jump as it loads.
+     */
+    readonly height?: "fill" | "auto";
+    /** Pixels, for `height: "auto"` (640, or 70% of the window when that's less); it scrolls past. */
+    readonly maxHeight?: number;
+    /**
+     * Draws only near the viewport (a screen ahead) and lets go of a diff far behind, keeping its
+     * height; on by default with `height: "auto"`, for a long page of them. `ready` waits for it.
+     */
+    readonly lazy?: boolean;
+    /**
+     * Every file down one scroller, each under its own header (status, path, counts, Viewed)
+     * that sticks to the top until the next file's pushes it off; ‹ › and `show()` glide to a
+     * file, and the file on show follows the scroll. Each file draws when it's near the view.
+     */
+    readonly stack?: boolean;
+    /** The files marked viewed; with this or `onViewed`, a Viewed check in the header. */
+    readonly viewed?: readonly string[];
+    /** The header's Viewed check marked or cleared the file on show. */
+    readonly onViewed?: (viewed: readonly string[], file: string) => void;
+    /** ‹ 2 of 5 › in the header when there are several files (on by default). */
+    readonly nav?: boolean;
+    /** Shiki themes for the code, dark and light (Pierre's own unless set). */
+    readonly syntax?: {
+        readonly dark: string;
+        readonly light: string;
+    };
+    /** Its own controls changed the file (‹ ›); `show()` doesn't call it. */
+    readonly onFile?: (name: string) => void;
+    readonly onLayout?: (layout: DiffLayout) => void;
+    readonly onWrap?: (wrap: boolean) => void;
+    /** Lines picked by dragging over line numbers; turns line selection on. */
+    readonly onLines?: (lines: DiffLines | null, file: string) => void;
+    /** Shown with no files. */
+    readonly empty?: string;
+    /** An element of your own at the start of the header (diffReview puts its list's toggle here). */
+    readonly lead?: HTMLElement;
+}
+export interface CodeDiffUpdate {
+    readonly patch?: string;
+    readonly files?: readonly DiffSource[];
+    readonly file?: string | null;
+    readonly layout?: DiffLayout;
+    readonly wrap?: boolean;
+    readonly viewed?: readonly string[];
+    /**
+     * Switches between filling the container and its diff's own height, in place: the views and
+     * their scroll stay. The new height is taken as it is, not sprung, so a container whose size
+     * is moving (a card going full window) is followed rather than fought.
+     */
+    readonly height?: "fill" | "auto";
+    readonly maxHeight?: number;
+}
+export interface CodeDiff {
+    readonly element: HTMLElement;
+    /** The diff's files, counted, in tree order. */
+    readonly files: readonly DiffFile[];
+    readonly file: string | null;
+    readonly layout: DiffLayout;
+    readonly wrap: boolean;
+    readonly viewed: readonly string[];
+    /** Shows a file: the new one fades in over the last, in place. */
+    show(name: string): void;
+    /** The file before or after the one on show. */
+    step(dir: -1 | 1): void;
+    /** New input or settings; a new patch keeps the file on show if it's still there. */
+    update(next: CodeDiffUpdate): void;
+    /** Settles once the first file is drawn. */
+    readonly ready: Promise<void>;
+    dispose(): void;
+}
+/**
+ * A file's `+12 −3`, coloured, for a row of your own (a tree's `detail`); `bar` adds five
+ * squares that show the share added and removed, as GitHub does.
+ */
+export declare function diffCounts(file: DiffFile, doc?: Document, options?: {
+    readonly bar?: boolean;
+}): HTMLElement;
+/** A file's change as a letter (M, A, D, R), for a tree's `icon`. */
+export declare function diffStatus(file: DiffFile, doc?: Document): HTMLElement;
+/**
+ * A code diff in a knobs card: a header with the file's path, its counts and Split | Unified
+ * over the diff, drawn by `@pierre/diffs` (Shiki highlighting, word-level changes, hunks that
+ * expand when the whole files are known). Takes a unified patch or before and after pairs.
+ * Changing the file or the layout fades the new view in over the old, in place; each file
+ * keeps its scroll. On another surface (a card, a split's pane, a walkthrough's step) it draws
+ * no card of its own. Needs `@pierre/diffs` installed; it loads on first use.
+ */
+export declare function codeDiff(container: HTMLElement, options: CodeDiffOptions): CodeDiff;
+export interface DiffReviewOptions extends CodeDiffOptions {
+    /**
+     * Saves whether the file list is open and the files marked viewed, under this id. A viewed
+     * file whose change moves on comes back unviewed.
+     */
+    readonly id?: string;
+    readonly storage?: StoragePort | null;
+    /** The file list's title ("Files"). */
+    readonly title?: string;
+    /** The file list's width in pixels when open (256). */
+    readonly listSize?: number;
+    /** The file list starts open (the default) or closed; what was last chosen wins, with an id. */
+    readonly listOpen?: boolean;
+    /** A field over the file list that narrows it by path (on by default). */
+    readonly search?: boolean;
+}
+export interface DiffReview {
+    readonly element: HTMLElement;
+    readonly tree: Tree<DiffTreeItem>;
+    readonly diff: CodeDiff;
+    /** The files marked viewed. */
+    readonly viewed: readonly string[];
+    /** Marks files viewed or not (a folder's id marks what's in it). */
+    setViewed(names: readonly string[], viewed: boolean): void;
+    /** Narrows the file list to paths with every word of `query`. */
+    filter(query: string): void;
+    /** Whether the file list is open. */
+    readonly listOpen: boolean;
+    /** Springs the file list open or closed (toggles without an argument). */
+    toggleList(open?: boolean): void;
+    update(next: CodeDiffUpdate): void;
+    dispose(): void;
+}
+/**
+ * A diff beside its file list, as a review, in one card: the list is a drawer at its left that
+ * springs open and shut (0 to 256px, .4 s, no bounce; the diff reflows as it moves) from a
+ * button at the start of the diff's header, or ⌘B / Ctrl+B. In it, a field that narrows the list
+ * by path, then the changed files as a compact tree (folders folded into paths), each with its
+ * change as a letter (M, A, D, R, coloured), its +/− counts and their bar, and a tick to mark it
+ * viewed; one highlight glides to the file on show. Viewed files dim, count in the list's title
+ * and, with an `id`, are remembered until their change moves on. `tree` and `diff` are the pieces.
+ */
+export declare function diffReview(container: HTMLElement, options: DiffReviewOptions): DiffReview;