@kitlangton/knobs 0.3.0 → 0.4.0-next.1

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

@@ -1 +1 @@
-export declare const bentoCss = "\n.knobs-ui.knobs-bento{--ku-bento-radius:var(--k-ui-bento-radius,max(0px,calc(var(--ku-radius) - 5px)));\n  position:relative;width:100%;height:100%;overflow:hidden auto;outline:none;background:var(--k-ui-bento-bg,var(--ku-page));\n  scrollbar-width:thin;scrollbar-gutter:stable;overscroll-behavior:contain;touch-action:pan-y;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.knobs-bento[data-frame=\"flat\"]{--ku-bento-radius:var(--k-ui-bento-radius,0px)}\n.knobs-bento[data-pending] .knobs-bento-space{visibility:hidden}\n:where(.knobs-bento-space,.knobs-bento-space *){box-sizing:border-box}\n.knobs-bento-space{position:relative;width:100%}\n.knobs-bento-tile{position:absolute;left:0;top:0;transform-origin:0 0;overflow:hidden;border-radius:var(--ku-bento-radius);\n  background:var(--ku-surface);contain:strict;cursor:zoom-in}\n.knobs-bento-tile[data-focus]{z-index:2;cursor:zoom-out}\n.knobs-bento-tile[data-focus][data-live]{cursor:auto}\n.knobs-bento-img{display:block;width:100%;height:100%;object-fit:cover;opacity:0;transition:opacity .18s cubic-bezier(.2,.8,.2,1);-webkit-user-drag:none}\n.knobs-bento-tile[data-ready] .knobs-bento-img{opacity:1}\n.knobs-bento-tile[data-instant] .knobs-bento-img{transition:none}\n.knobs-bento-body{position:absolute;inset:0;pointer-events:none}\n.knobs-bento-tile[data-focus] .knobs-bento-body{pointer-events:auto}\n.knobs-bento-label{position:absolute;left:9px;right:9px;bottom:7px;color:#fff;font-size:var(--ku-text-meta);line-height:1.3;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;\n  text-shadow:0 0 6px rgba(0,0,0,.55),0 0 1px rgba(0,0,0,.5);opacity:0;pointer-events:none;transition:opacity calc(var(--ku-hover-out) * 1ms)}\n.knobs-bento:not([data-keyboard]) .knobs-bento-tile:hover .knobs-bento-label,\n.knobs-bento[data-keyboard]:focus .knobs-bento-tile[data-active] .knobs-bento-label,\n.knobs-bento-tile[data-focus] .knobs-bento-label{opacity:1;transition-duration:calc(var(--ku-hover-in) * 1ms)}\n/* A pick: a small dot in the accent, ringed in the page so it reads on any picture. */\n.knobs-bento-tile::after{content:\"\";position:absolute;top:8px;right:8px;width:8px;height:8px;border-radius:50%;background:var(--ku-accent);\n  box-shadow:0 0 0 1.5px color-mix(in srgb,var(--ku-page) 70%,transparent);opacity:0;scale:.4;pointer-events:none;\n  transition:opacity .11s cubic-bezier(.4,0,1,1),scale var(--ku-ease-ms) var(--ku-ease)}\n.knobs-bento-tile[aria-selected=\"true\"]::after{opacity:1;scale:1;transition:opacity .15s cubic-bezier(.2,.8,.2,1),scale var(--ku-ease-ms) var(--ku-ease)}\n.knobs-bento-wash{position:absolute;left:0;top:0;width:100px;height:100px;transform-origin:0 0;z-index:3;pointer-events:none;border-radius:var(--ku-bento-radius);\n  background:color-mix(in srgb,var(--ku-accent) 12%,transparent);box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--ku-accent) 45%,transparent);\n  opacity:0;transition:opacity .15s}\n.knobs-bento[data-keyboard]:focus:not([data-zoomed]) .knobs-bento-wash[data-on]{opacity:1}\n.knobs-bento-scrim{position:absolute;left:0;top:0;width:100%;z-index:1;background:var(--k-ui-scrim,var(--k-ui-bento-bg,var(--ku-page)));opacity:0;pointer-events:none;cursor:zoom-out}\n.knobs-bento[data-zoomed] .knobs-bento-scrim{pointer-events:auto}\n.knobs-bento-head{position:absolute;left:0;top:0;display:flex;align-items:flex-end;padding:0 0 6px 2px;color:var(--ku-label);font-weight:var(--ku-label-weight);\n  font-size:var(--ku-text-meta);white-space:nowrap;pointer-events:none}\n";
+export declare const bentoCss = "\n.knobs-ui.knobs-bento{--_ku-bento-radius:var(--k-ui-bento-radius,max(0px,calc(var(--_k-radius) - 5px)));\n  position:relative;width:100%;height:100%;overflow:hidden auto;outline:none;background:var(--k-ui-bento-bg,var(--_k-bg-page));\n  scrollbar-width:thin;scrollbar-gutter:stable;overscroll-behavior:contain;touch-action:pan-y;user-select:none;-webkit-user-select:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n.knobs-bento[data-frame=\"flat\"]{--_ku-bento-radius:var(--k-ui-bento-radius,0px)}\n.knobs-bento[data-pending] .knobs-bento-space{visibility:hidden}\n:where(.knobs-bento-space,.knobs-bento-space *){box-sizing:border-box}\n.knobs-bento-space{position:relative;width:100%}\n.knobs-bento-tile{position:absolute;left:0;top:0;transform-origin:0 0;overflow:hidden;border-radius:var(--_ku-bento-radius);\n  background:var(--_k-fill);contain:strict;cursor:zoom-in}\n.knobs-bento-tile[data-focus]{z-index:2;cursor:zoom-out}\n.knobs-bento-tile[data-focus][data-live]{cursor:auto}\n.knobs-bento-img{display:block;width:100%;height:100%;object-fit:cover;opacity:0;transition:opacity .18s cubic-bezier(.2,.8,.2,1);-webkit-user-drag:none}\n.knobs-bento-tile[data-ready] .knobs-bento-img{opacity:1}\n.knobs-bento-tile[data-instant] .knobs-bento-img{transition:none}\n.knobs-bento-body{position:absolute;inset:0;pointer-events:none}\n.knobs-bento-tile[data-focus] .knobs-bento-body{pointer-events:auto}\n.knobs-bento-label{position:absolute;left:9px;right:9px;bottom:7px;color:#fff;font-size:var(--_k-text-meta);line-height:1.3;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;\n  text-shadow:0 0 6px rgba(0,0,0,.55),0 0 1px rgba(0,0,0,.5);opacity:0;pointer-events:none;transition:opacity calc(var(--_k-hover-out) * 1ms)}\n.knobs-bento:not([data-keyboard]) .knobs-bento-tile:hover .knobs-bento-label,\n.knobs-bento[data-keyboard]:focus .knobs-bento-tile[data-active] .knobs-bento-label,\n.knobs-bento-tile[data-focus] .knobs-bento-label{opacity:1;transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* A pick: a small dot in the accent, ringed in the page so it reads on any picture. */\n.knobs-bento-tile::after{content:\"\";position:absolute;top:8px;right:8px;width:8px;height:8px;border-radius:50%;background:var(--_k-accent);\n  box-shadow:0 0 0 1.5px color-mix(in srgb,var(--_k-bg-page) 70%,transparent);opacity:0;scale:.4;pointer-events:none;\n  transition:opacity .11s cubic-bezier(.4,0,1,1),scale var(--_ku-ease-ms) var(--_ku-ease)}\n.knobs-bento-tile[aria-selected=\"true\"]::after{opacity:1;scale:1;transition:opacity .15s cubic-bezier(.2,.8,.2,1),scale var(--_ku-ease-ms) var(--_ku-ease)}\n.knobs-bento-wash{position:absolute;left:0;top:0;width:100px;height:100px;transform-origin:0 0;z-index:3;pointer-events:none;border-radius:var(--_ku-bento-radius);\n  background:color-mix(in srgb,var(--_k-accent) 12%,transparent);box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--_k-accent) 45%,transparent);\n  opacity:0;transition:opacity .15s}\n.knobs-bento[data-keyboard]:focus:not([data-zoomed]) .knobs-bento-wash[data-on]{opacity:1}\n.knobs-bento-scrim{position:absolute;left:0;top:0;width:100%;z-index:1;background:var(--k-ui-scrim,var(--k-ui-bento-bg,var(--_k-bg-page)));opacity:0;pointer-events:none;cursor:zoom-out}\n.knobs-bento[data-zoomed] .knobs-bento-scrim{pointer-events:auto}\n.knobs-bento-head{position:absolute;left:0;top:0;display:flex;align-items:flex-end;padding:0 0 6px 2px;color:var(--_k-fg-2);font-weight:var(--_k-weight-label);\n  font-size:var(--_k-text-meta);white-space:nowrap;pointer-events:none}\n";

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,var(--_k-ok));--_ku-cmp-line:var(--_k-compare-divider);\n  --_ku-cmp-stage:var(--_k-compare-stage);\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(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg);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(--_k-radius) - 2px));color:var(--_k-fg-3);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(--_k-fg);background:var(--_ku-wash)}\n.knobs-ui .knobs-cmp-mode[aria-checked=\"true\"],.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--_k-fg);font-weight:var(--_k-weight-label)}\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(--_k-radius-panel);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(--_k-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(--_k-border),inset 0 1px 0 var(--_k-rim),0 2px 10px rgba(0,0,0,calc(.18 * var(--_k-shadow-k,1)))}\n.knobs-cmp-label{position:absolute;left:0;top:0;padding:1px 7px;border-radius:999px;font-size:var(--_k-text-meta);line-height:16px;color:var(--_k-fg-2);white-space:nowrap;pointer-events:none;will-change:transform;transition:color .15s}\n.knobs-cmp-label[data-lit]{color:var(--_k-fg)}\n.knobs-cmp-label[data-dim]{color:var(--_k-fg-3)}\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(--_k-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(--_k-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(--_k-fg);font-size:var(--_k-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(--_k-fg-2);cursor:pointer;transition:color .15s,background .15s}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){color:var(--_k-fg);background:color-mix(in srgb,var(--_k-fg) 12%,transparent)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);font-size:var(--_k-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,var(--_k-ok));position:relative;width:100%;height:100%;min-height:40px;overflow:hidden;cursor:col-resize;touch-action:none;\n  font:var(--_k-weight) var(--_k-font-size)/1.35 var(--_k-font);color:var(--_k-fg)}\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;

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;