@kitlangton/knobs 0.2.0 → 0.4.0-next.0

package/dist/types/panel/prefs.d.ts

@@ -1,7 +1,7 @@
 import type { PanelCommand, PanelKeys } from "../core/store.js";
 /** How a panel reads keys that aren't commands (see `PanelKeys`): resolved once per panel. */
 export interface KeyPrefs {
-    /** j/k and h/l as aliases for the arrows. */
+    /** j/k as aliases for ↑/↓ (l is Lock, so ←/→ have no letters). */
     readonly vim: boolean;
     /** Digits, `.`, `-` and Enter on a slider open its inline number editor. */
     readonly edit: boolean;
@@ -14,7 +14,7 @@ export declare const DEFAULT_PREFS: KeyPrefs;
 export declare const setKeyPrefs: (root: Element, prefs: KeyPrefs) => WeakMap<Element, KeyPrefs>;
 /** The preferences of the panel `node` sits in. */
 export declare function keyPrefs(node: EventTarget | null): KeyPrefs;
-/** -1, 1 or 0 for ←/→ (and h/l unless the panel turned the letter aliases off). */
+/** -1, 1 or 0 for ←/→. */
 export declare function arrowOf(event: KeyboardEvent): -1 | 0 | 1;
 /** ⇧'s multiplier for this event (1 without ⇧). */
 export declare const bigOf: (event: KeyboardEvent) => number;

package/dist/types/panel/presence.d.ts

@@ -0,0 +1,20 @@
+import type { MorphFrame } from "./morph.js";
+export interface Presence {
+    readonly shown: boolean;
+    /** Shows or hides the panel; `animate: false` puts it there at once (a reload, a first paint). */
+    set(shown: boolean, animate: boolean): void;
+    /** The shape the GPU overlay draws while it shows or hides (see `MorphFrame`), else undefined. */
+    frame(now: number): MorphFrame | undefined;
+    dispose(): void;
+}
+/** What the panel looks like at `x` (0 hidden, 1 shown) on the way in or out. */
+export declare function presenceLook(x: number, inline: boolean, reduced: boolean): {
+    opacity: number;
+    blur: number;
+    scale: number;
+    fold: number;
+};
+export declare function createPresence(root: HTMLElement, options: {
+    readonly inline: boolean;
+    readonly wake: () => void;
+}): Presence;

package/dist/types/panel/scope.d.ts

@@ -7,6 +7,35 @@ export type CommandScope = "selection" | "row" | "group" | "all";
 export declare function commandScope(level: FocusLevel, selection?: boolean): CommandScope;
 /** How a command reads from where it would land: "Random this", "Reset group", "Random all". */
 export declare function scopeLabel(verb: string, scope: CommandScope): string;
+/** A level below the panel that the header's crumbs name: a card, a row, an open editor's part. */
+export type CrumbLevel = "card" | "row" | "editor";
+export interface Crumb {
+    readonly level: CrumbLevel;
+    readonly label: string;
+}
+/**
+ * Where keys go, as the header reads after the panel's title: `Shape › Cohesion`. A level that
+ * isn't focused (or has no name) is left out; the last crumb is the deepest, the one focused.
+ */
+export declare function crumbTrail(path: {
+    readonly card?: string;
+    readonly row?: string;
+    readonly editor?: string;
+}): Crumb[];
+/**
+ * Where Esc goes from the deepest crumb: the crumb before it, else the panel (`title`). Nothing
+ * at the panel itself (no crumbs), where Esc leaves.
+ */
+export declare function escTarget(trail: readonly Crumb[], title: string): string | undefined;
+/**
+ * How much of a trail fits `room` px: crumbs from `from` on show (the ones before it fold into
+ * one "…"), and the Esc hint shows only when it fits too. The deepest crumb always shows.
+ * `widths` are the crumbs' own; `sep` a separator's (with its gaps), `more` the "…"'s.
+ */
+export declare function fitCrumbs(widths: readonly number[], room: number, sep: number, more: number, hint?: number): {
+    from: number;
+    hint: boolean;
+};
 /**
  * The option a digit picks among `count` (0-based), or undefined when it names none: 1–9 pick
  * the first nine, as they read.

package/dist/types/panel/slider.d.ts

@@ -1,4 +1,5 @@
 import type { Knob as KnobField } from "../core/schema.js";
+import { type DetentKind } from "./feel.js";
 import { type Roll, Spring, VelocityTracker } from "./motion.js";
 export interface DigitPlace {
     ch: string;
@@ -39,6 +40,17 @@ export interface Slider {
     readonly notchRatio: number;
     /** Whether a drag is currently held on the default by the notch's magnet. */
     isMagnetized(): boolean;
+    /** The detent holding a drag right now, if any. */
+    heldDetent(): DetentKind | undefined;
+    /** Where the active preset's value sits [0..1], when it differs from the default. */
+    readonly baseRatio: number | undefined;
+    /** When the handle last caught a detent (see `settleScale`). */
+    readonly settledAt: number;
+    /**
+     * How many halvings the drag in hand moves at, for its ruler (0 at 1:1 or at rest, up to 3; each
+     * level halves the tenths again). Each level shows `rulerAlpha(depth, level)` of the way.
+     */
+    rulerDepth(): number;
     /** When the readout last popped (a click landing on a decile, or the default's magnet). */
     poppedAt: number;
     /** Formatted numeric string without unit (e.g. "0.45" or "98"). */
@@ -83,10 +95,15 @@ export declare function stepValue(field: {
 /**
  * A DialKit-style slider: the whole row is the track, the fill is a full-height block,
  * the handle is a hairline that only shows on hover, and the label + value sit on the
- * track itself. Dragging follows the pointer exactly (⌥ for 1/10 speed) and the default's notch
- * pulls it in from a few px away; a click snaps to the nearest step (or nearest 10% when there
- * are many steps) with a short spring-like ease. A sideways trackpad pan moves it like a drag.
+ * track itself. Dragging follows the pointer exactly, slower the further the pointer strays off
+ * the row (and ⌥ for 1/10 speed); detents at the default, the active preset's value and round
+ * values hold it for a few px, and past an end the row stretches like rubber. A click snaps
+ * to the nearest step (or nearest 10% when there are many steps) with a short spring-like ease.
+ * A sideways trackpad pan moves it like a drag.
  */
 export declare function createSlider(doc: Document, key: string, initialField: KnobField, set: (value: number, options?: {
     coalesce?: boolean;
-}) => void, onMotionWake?: () => void): Slider;
+}) => void, onMotionWake?: () => void, options?: {
+    /** The active preset's value for this key (what Reset goes back to first). */
+    readonly base?: () => number | undefined;
+}): Slider;

package/dist/types/panel/tab-transition.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A tab change, as one layout animation: what leaves fades out where it stood (lifted out of the
+ * flow, so it takes no room), what arrives fades in block by block with a small rise, what stays
+ * glides to its new place, and the surface (and any card whose rows change) springs to its new
+ * height. Every spring keeps its position and velocity when another tab is picked mid-flight.
+ *
+ * While the pointer stays on the panel the surface never shrinks: a panel anchored at its foot
+ * (or centred) would otherwise move its tabs out from under the pointer between two clicks. It
+ * settles to its size once the pointer leaves.
+ */
+export declare function tabTransition(body: HTMLElement, root: HTMLElement, wake: () => void): {
+    readonly running: boolean;
+    finish: () => void;
+    to(want: Map<HTMLElement, boolean>): void;
+};

package/dist/types/panel/tabs.d.ts

@@ -28,4 +28,4 @@ export interface TabStrip {
     focus(options?: FocusOptions): void;
     dispose(): void;
 }
-export declare function createTabStrip(doc: Document, choose: (id: string) => void): TabStrip;
+export declare function createTabStrip(doc: Document, choose: (id: string, animate?: boolean) => void): TabStrip;

package/dist/types/panel/toggle.d.ts

@@ -0,0 +1,27 @@
+import { type StoragePort } from "../core/storage.js";
+type KeyEventLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "altKey" | "shiftKey" | "repeat" | "isComposing" | "defaultPrevented" | "target">;
+/** Whether a keydown is `key` for the toggle: outside a text field, with no modifier held. */
+export declare function isToggleKey(event: KeyEventLike, key: string): boolean;
+/** A panel or chip that comes and goes with the toggle key. */
+export interface ToggleSurface {
+    /** Its store's id: what's remembered. */
+    readonly id: string;
+    readonly key: string;
+    readonly storage: () => StoragePort | null;
+    /** Where focus may be when it hides, to give back when it shows. */
+    readonly root: HTMLElement;
+    /** Shows or hides it; `animate: false` puts it there at once. */
+    show(shown: boolean, animate: boolean): void;
+}
+export interface ToggleLayer {
+    /** Joins the layer; `shown` is how it should start (what its store remembers). */
+    register(surface: ToggleSurface): {
+        readonly shown: boolean;
+        dispose(): void;
+    };
+    /** Shows or hides everything listening for `key`; false when nothing does. */
+    toggle(key: string): boolean;
+}
+/** The page's toggle layer, for `doc`. */
+export declare function toggleLayer(doc: Document): ToggleLayer;
+export {};

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

@@ -0,0 +1 @@
+export declare const compareCss = "\n:where(.knobs-compare,.knobs-compare *,.knobs-cmp-strip,.knobs-cmp-strip *){box-sizing:border-box}\n.knobs-ui.knobs-compare{--ku-cmp-diff:var(--k-compare-diff,#7dcf9c);--ku-cmp-line:var(--k-compare-line,#fff);\n  --ku-cmp-stage:var(--k-compare-stage,var(--ku-surface));\n  display:flex;flex-direction:column;gap:6px;width:100%;height:100%;min-height:160px;outline:none;user-select:none;-webkit-user-select:none;\n  font:var(--ku-font-weight) var(--ku-font-size)/1.35 var(--ku-font);color:var(--ku-text);letter-spacing:normal;text-align:left}\n:where(.knobs-ui) :is(.knobs-cmp-mode,.knobs-cmp-toggle){all:revert;box-sizing:border-box;font:inherit;color:inherit;letter-spacing:inherit;background:transparent;border:0;margin:0;padding:0;outline:none;box-shadow:none}\n.knobs-cmp-bar{flex:none;display:flex;align-items:center;gap:2px;height:24px;padding:0 2px}\n.knobs-cmp-modes{display:flex;align-items:center;gap:2px}\n.knobs-ui .knobs-cmp-mode,.knobs-ui .knobs-cmp-toggle{height:22px;padding:0 7px;border-radius:max(0px,calc(var(--ku-radius) - 2px));color:var(--ku-dim);cursor:pointer;white-space:nowrap;\n  transition:color .15s,background .15s}\n.knobs-ui .knobs-cmp-mode:is(:hover,:focus-visible),.knobs-ui .knobs-cmp-toggle:is(:hover,:focus-visible){color:var(--ku-text);background:var(--ku-wash)}\n.knobs-ui .knobs-cmp-mode[aria-checked=\"true\"],.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--ku-text);font-weight:var(--ku-label-weight)}\n.knobs-cmp-fill{flex:1}\n.knobs-cmp-toggle[hidden]{display:none}\n/* One surface: on a card (a walkthrough's step, a split's pane, anything .knobs-surface) or marked\n   data-nested, the stage drops its fill and the sides sit on that card. */\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-compare,.knobs-ui.knobs-compare[data-nested]{--ku-cmp-stage:var(--k-compare-stage,transparent)}\n/* In a page's flow (a container with no height), it takes the height its sides need. */\n.knobs-ui.knobs-compare[data-auto]{height:auto}\n.knobs-compare[data-auto] .knobs-cmp-stage{flex:none;min-height:0}\n.knobs-cmp-stage{position:relative;flex:1;min-height:96px;overflow:hidden;border-radius:var(--ku-panel-radius);background:var(--ku-cmp-stage);touch-action:pan-y;outline:none}\n.knobs-compare[data-frame=\"flat\"] .knobs-cmp-stage{border-radius:0}\n.knobs-compare[data-mode=\"wipe\"] .knobs-cmp-stage{cursor:ew-resize}\n/* Unzoomed, a finger still scrolls the page up and down; zoomed, the stage takes every gesture. */\n.knobs-compare[data-zoomed] .knobs-cmp-stage{cursor:grab;touch-action:none}\n.knobs-compare[data-panning],.knobs-compare[data-panning] *{cursor:grabbing!important}\n.knobs-compare[data-dragging],.knobs-compare[data-dragging] *{cursor:ew-resize!important}\n.knobs-cmp-sizer{position:absolute;left:0;right:0;top:0;height:0;visibility:hidden;pointer-events:none}\n.knobs-cmp-canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n.knobs-cmp-media{position:absolute;left:0;top:0;display:block;max-width:none;margin:0;padding:0;border:0;object-fit:fill;transform-origin:0 0;pointer-events:none;will-change:transform}\n.knobs-compare[data-renderer=\"gpu\"] .knobs-cmp-media{opacity:0}\n/* Glass: what's behind shows through, blurred, on the knobs tokens. */\n.knobs-cmp-label,.knobs-cmp-zoom{background:color-mix(in srgb,var(--ku-bg) 52%,transparent);-webkit-backdrop-filter:blur(14px) saturate(1.6);backdrop-filter:blur(14px) saturate(1.6);\n  box-shadow:inset 0 0 0 .5px var(--ku-line),inset 0 1px 0 var(--ku-rim),0 2px 10px rgba(0,0,0,.18)}\n.knobs-cmp-label{position:absolute;left:0;top:0;padding:1px 7px;border-radius:999px;font-size:var(--ku-text-meta);line-height:16px;color:var(--ku-label);white-space:nowrap;pointer-events:none;will-change:transform;transition:color .15s}\n.knobs-cmp-label[data-lit]{color:var(--ku-text)}\n.knobs-cmp-label[data-dim]{color:var(--ku-dim)}\n/* The wipe: a hairline down the line with a grip at its middle; a wider strip takes the hand and\n   the keys (a slider). It fades with the mode. */\n.knobs-cmp-handle{cursor:ew-resize;position:absolute;left:-12px;top:0;width:24px;height:0;opacity:0;pointer-events:none;outline:none;will-change:transform;transition:opacity .18s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-handle[data-on]{opacity:1;pointer-events:auto;transition:opacity .22s cubic-bezier(.2,.8,.2,1)}\n.knobs-cmp-handle::before{content:\"\";position:absolute;top:0;bottom:0;left:11.5px;width:1px;background:var(--ku-cmp-line);box-shadow:0 0 0 .5px rgba(0,0,0,.28),0 0 6px rgba(0,0,0,.25)}\n.knobs-cmp-handle::after{content:\"\";position:absolute;top:50%;left:9px;width:6px;height:28px;margin-top:-14px;border-radius:3px;background:var(--ku-cmp-line);\n  box-shadow:0 1px 3px rgba(0,0,0,.35),0 0 0 .5px rgba(0,0,0,.2);transition:scale .18s var(--ku-ease),box-shadow .15s}\n.knobs-compare[data-dragging] .knobs-cmp-handle::after{scale:1.12}\n.knobs-cmp-handle:focus-visible::after,.knobs-compare[data-keyboard] .knobs-cmp-handle:focus::after{box-shadow:0 1px 3px rgba(0,0,0,.35),0 0 0 3px color-mix(in srgb,var(--ku-accent) 40%,transparent)}\n/* The split's hairline, down the middle side by side. */\n.knobs-cmp-split{position:absolute;left:0;top:0;width:1px;height:0;margin-left:-.5px;background:color-mix(in srgb,var(--ku-bg) 72%,transparent);pointer-events:none;will-change:transform,opacity}\n/* Zoomed: how far, and a way back, in the stage's corner; it fades in and out, nothing shifts. */\n.knobs-cmp-zoom{position:absolute;right:8px;bottom:8px;display:flex;align-items:center;gap:4px;height:26px;padding:0 3px 0 10px;border-radius:999px;\n  color:var(--ku-text);font-size:var(--ku-text-meta);font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";white-space:nowrap;\n  opacity:0;scale:.96;pointer-events:none;transition:opacity .16s cubic-bezier(.4,0,1,1),scale .16s cubic-bezier(.4,0,1,1)}\n.knobs-cmp-zoom[data-on]{opacity:1;scale:1;pointer-events:auto;transition:opacity .2s cubic-bezier(.2,.8,.2,1),scale .2s cubic-bezier(.2,.8,.2,1)}\n:where(.knobs-ui) .knobs-cmp-zoom-reset{all:revert;box-sizing:border-box;font:inherit;letter-spacing:inherit;margin:0;border:0;outline:none;box-shadow:none;\n  height:20px;padding:0 8px;border-radius:999px;background:transparent;color:var(--ku-label);cursor:pointer;transition:color .15s,background .15s}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){color:var(--ku-text);background:color-mix(in srgb,var(--ku-text) 12%,transparent)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--ku-dim);font-size:var(--ku-text-meta);pointer-events:none}\n.knobs-cmp-note:empty{display:none}\n.knobs-cmp-strip-host{flex:none;height:60px;min-height:0}\n.knobs-cmp-timeline-host{flex:none;height:56px;min-height:0}\n/* The frame strip: Before over After per column, a difference bar under them, a dot where it peaks. */\n.knobs-ui.knobs-cmp-strip{--ku-cmp-diff:var(--k-compare-diff,#7dcf9c);position:relative;width:100%;height:100%;min-height:40px;overflow:hidden;cursor:col-resize;touch-action:none;\n  font:var(--ku-font-weight) var(--ku-font-size)/1.35 var(--ku-font);color:var(--ku-text)}\n.knobs-cmp-strip>canvas{position:absolute;left:0;top:0;width:100%;height:100%;pointer-events:none}\n@media(prefers-reduced-motion:reduce){:is(.knobs-compare,.knobs-cmp-strip) :where(*,::before,::after){transition-duration:.12s!important}}\n";

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

@@ -0,0 +1,41 @@
+export interface CachedFrame {
+    readonly frame: number;
+    readonly bitmap: ImageBitmap;
+    /** Full size (else a small grid frame). */
+    readonly full: boolean;
+}
+export interface FramePoint {
+    readonly frame: number;
+    /** Any cached frame this close (frames) will do. */
+    readonly tolerance: number;
+}
+export interface FrameCache {
+    readonly src: string;
+    /** How it decodes, once it knows. */
+    readonly backend: "webcodecs" | "video" | "pending";
+    /** Frames held now. */
+    readonly size: number;
+    /** The cached frame nearest `frame`, no further than `within` frames. */
+    nearest(frame: number, within?: number): CachedFrame | null;
+    /** The playhead of the viewer being used: full-size frames around it decode first. */
+    focus(frame: number): void;
+    /** Frames a strip shows (small, with a tolerance each). */
+    want(points: readonly FramePoint[]): void;
+    /** A frame the viewer has decoded exactly (paused on it). */
+    keep(frame: number, source: CanvasImageSource, width: number, height: number): void;
+    /** Whether a viewer of it is near the screen: only then does it decode. */
+    visible(on: boolean): void;
+    /** New frames arrived. */
+    listen(f: () => void): () => void;
+    release(): void;
+}
+/** Frames either side of the focus decoded at full size. */
+export declare const FOCUS_RADIUS = 6;
+/** The grid's frames: `count` evenly across `total`, as points with half a step's tolerance. */
+export declare function gridPoints(total: number, count?: number): FramePoint[];
+/** The full-size frames wanted around `focus`, nearest first. */
+export declare function focusWindow(focus: number, total: number, radius?: number): number[];
+/** The key in `keys` nearest `frame` within `within` (ties go to the later frame). */
+export declare function nearestKey(keys: Iterable<number>, frame: number, within?: number): number | null;
+/** The shared cache for `src` at `fps`; `release()` it when done. */
+export declare function acquireFrames(doc: Document, src: string, fps: number): FrameCache;

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

@@ -0,0 +1,58 @@
+import type { Rect } from "./compare-model.js";
+export declare const MODE_INDEX: {
+    readonly side: 0;
+    readonly wipe: 1;
+    readonly difference: 2;
+    readonly flicker: 3;
+};
+export interface CompareDraw {
+    /** Device px: where each side's picture lands (zoomed, it's larger than its clip). */
+    readonly before: Rect;
+    readonly after: Rect;
+    /** Device px: the part of the stage each side may draw in. */
+    readonly beforeClip: Rect;
+    readonly afterClip: Rect;
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+    /** The wipe's line (device px) and its soft edge (device px). */
+    readonly wipeX: number;
+    readonly soft: number;
+    readonly from: number;
+    readonly to: number;
+    /** 0 shows `from`, 1 shows `to`. */
+    readonly mix: number;
+    /** Before in After's place (X held). */
+    readonly flick: boolean;
+    /** Flicker mode's phase: Before showing. */
+    readonly phase: boolean;
+    readonly threshold: number;
+    readonly gain: number;
+    readonly accent: readonly [number, number, number];
+    /** Device px centre and radius, and zoom; null for none. */
+    readonly loupe: {
+        readonly x: number;
+        readonly y: number;
+        readonly r: number;
+        readonly zoom: number;
+    } | null;
+    /** Each side shows its preview texture (a cached frame) instead of its video's. */
+    readonly preview: readonly [boolean, boolean];
+}
+export interface CompareGpu {
+    /**
+     * Copies a frame in (0 Before, 1 After; 2 and 3 their previews); false if it couldn't (no data
+     * yet, or a tainted source).
+     */
+    upload(slot: 0 | 1 | 2 | 3, source: CanvasImageSource, w: number, h: number): boolean;
+    /** Forgets a side's frame (a new source is loading). */
+    clear(side: 0 | 1): void;
+    /** Frees the textures and shrinks the canvas (off screen); uploads bring them back. */
+    shrink(): void;
+    draw(frame: CompareDraw): void;
+    dispose(): void;
+}
+/** A renderer on `canvas`, or null where WebGPU isn't there. `onLost` hears a lost device. */
+export declare function createCompareGpu(canvas: HTMLCanvasElement, onLost: () => void): Promise<CompareGpu | null>;
+/** The shared device once made (null before it is, or without WebGPU): for checks. */
+export declare const sharedDevice: () => Promise<unknown>;

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;