@kitlangton/knobs 0.4.0-next.15 → 0.4.0-next.17

package/dist/themes.js

@@ -520,6 +520,14 @@ var TOKENS = [
     doc: "Panel and card radius, concentric with controls.",
     deprecated: ["--k-panel-radius", "--ku-panel-radius"]
   },
+  {
+    name: "radius-frame",
+    tier: "semantic",
+    type: "length",
+    group: "Shape",
+    source: css("calc(var(--k-radius) + min(var(--k-radius) * 999, var(--_k-pad) + 1px))"),
+    doc: "A tuning panel's outer corners: its cards' radius plus its padding and border, so the cards, the preset strip and the focus lens inside run concentric. Squares when --k-radius is 0."
+  },
   {
     name: "round",
     tier: "semantic",

package/dist/types/core/schema.d.ts

@@ -5,6 +5,11 @@ import { CURVE_SHAPES, type CurveInterp, type CurvePoint, type GradientSpace, ty
 import type { SpringValue } from "./spring.js";
 export interface FieldMeta {
     readonly label?: string;
+    /**
+     * What the knob does, in a sentence: a tooltip over its row (after a pause, or on keyboard
+     * focus) and its control's accessible description. Search matches it.
+     */
+    readonly description?: string;
     readonly group?: string;
     /**
      * What the group's header shows when it isn't the `group` id itself (the first field that
@@ -15,7 +20,10 @@ export interface FieldMeta {
     readonly section?: string;
     /** What the section's heading shows (the first field that gives one wins); `section` by default. */
     readonly sectionLabel?: string;
-    /** One muted line under the group's card title on a page (the first field that gives one wins). */
+    /**
+     * One muted line under the group's card title, in a panel or a page (the first field that gives
+     * one wins).
+     */
     readonly groupDescription?: string;
     /** One muted line under the section's heading on a page (the first field that gives one wins). */
     readonly sectionDescription?: string;
@@ -68,7 +76,7 @@ export interface FieldMeta {
     readonly subsection?: string;
 }
 /** Meta keys copied from a field's options or a descriptor onto the field. */
-export declare const META_KEYS: readonly ["label", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "pinned", "inPresets", "subsection"];
+export declare const META_KEYS: readonly ["label", "description", "group", "groupLabel", "section", "sectionLabel", "groupDescription", "sectionDescription", "shortcut", "random", "disabled", "readOnly", "folded", "sectionFolded", "tab", "pinned", "inPresets", "subsection"];
 /** The meta `source` gives, without undefined keys. */
 export declare function pickMeta(source: FieldMeta | undefined, skip?: readonly string[]): FieldMeta;
 /** Marks a knob as half of a flat spring: two number keys drawn as one spring card. */
@@ -490,6 +498,7 @@ export declare function range(value: readonly [number, number], options: FieldMe
     unit?: string;
     decimals?: number;
     label?: string;
+    description?: string;
     group?: string;
     groupLabel?: string;
     section?: string;

package/dist/types/core/store.d.ts

@@ -96,7 +96,7 @@ export interface LabelOptions {
     readonly defaultLabel?: string | Readonly<Record<string, string>>;
     /** How a page card shows its group presets (see `GroupPresetDisplay`). */
     readonly groupPresetDisplay?: GroupPresetDisplay;
-    /** By group id: one muted line under its card's title on a page, over fields' `groupDescription`. */
+    /** By group id: one muted line under its card's title, over fields' `groupDescription`. */
     readonly groupDescriptions?: Readonly<Record<string, string>>;
     /** By section id: one muted line under its heading on a page, over fields' `sectionDescription`. */
     readonly sectionDescriptions?: Readonly<Record<string, string>>;
@@ -146,6 +146,20 @@ export interface HeaderOptions {
      */
     readonly buttons?: readonly HeaderButton[];
 }
+/** What's active in a panel (see `MountPanelOptions.onActive`): a card, or one of its rows. */
+export interface PanelActive {
+    readonly group: string;
+    readonly key?: string;
+}
+/** What a folded card's or section's summary is made of (see `MountPanelOptions.groupSummary`). */
+export interface FoldSummaryInfo {
+    /** The group preset its values match (its name), "Custom" when none does; null without any. */
+    readonly preset: string | null;
+    /** How many of its rows differ from their defaults (a spring's two keys count once). */
+    readonly changed: number;
+    /** Its value keys. */
+    readonly keys: readonly string[];
+}
 export interface MountPanelOptions extends LabelOptions {
     readonly title?: string | false;
     /**
@@ -253,6 +267,20 @@ export interface MountPanelOptions extends LabelOptions {
     readonly sound?: boolean | SoundOptions;
     /** Called once the panel is mounted, with a handle to focus it (a host's "Tune" key). */
     readonly onReady?: (panel: PanelHandle) => void;
+    /**
+     * Called when the card or row under the pointer or focus changes: `{ group }` for a card's
+     * header or body, `{ group, key }` for one of its rows, `null` for nothing (and once more when
+     * the panel goes). Whichever of pointer and focus moved last wins; at most once a frame, never
+     * the same value twice. For outlining the part of the app a card changes.
+     */
+    readonly onActive?: (at: PanelActive | null) => void;
+    /**
+     * What a folded group card's header says on its right. In a panel, by default, a one-row card's
+     * value ("CSS orb"); otherwise its matching group preset, else its first changed value, else
+     * its first choice, then "· N changed". On a page, "<matching preset, or Custom> · N changed".
+     * Each part shows only where it applies; `null` shows nothing.
+     */
+    readonly groupSummary?: (group: string, info: FoldSummaryInfo) => string | Node | null;
     /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
     readonly copy?: () => string;
     /**

package/dist/types/index.d.ts

@@ -5,7 +5,7 @@ export { colorHex, parseColor, type Oklch } from "./core/color.js";
 export { sampleGradient, sampleCurve, gradientCss, CURVE_SHAPES, type GradientStop, type GradientSpace, type CurvePoint, type CurveInterp, type SampleGradientOptions, type SampleCurveOptions, } from "./core/ramp.js";
 export { bezierCss, bezierPoint, EASINGS, type Bezier, type EasingName } from "./core/easing.js";
 export { AROUND } from "./core/random.js";
-export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, type Appearance, } from "./core/store.js";
+export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type FoldSummaryInfo, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelActive, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, type Appearance, } from "./core/store.js";
 export { createRemoteControls, descriptorToField, formatSwift, fromDescriptors, fromSettings, type SettingsGroup, type SettingsItem, type ActionDescriptor, type ChoiceOption, type ControlDescriptor, type SpringBindingDescriptor, type ToolbarDescriptor, type ReadoutDescriptor, type ValueDescriptor, type RemoteControls, type RemoteControlsOptions, } from "./core/remote.js";
 export type { LogEntry, LogLevel, TableRows, WatchValue } from "./core/readout.js";
 export { memoryStorage, urlFlag, type StoragePort } from "./core/storage.js";

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

@@ -0,0 +1,53 @@
+import type { PanelActive } from "../core/store.js";
+/**
+ * What's active in a panel, from where the pointer is and where focus is, each told as it moves.
+ * Whichever last moved onto something leads; while it's on nothing (or off the panel), the
+ * other's target stands. `report` hears the result at most once a frame (`schedule`), and never
+ * the same value twice in a row.
+ */
+export declare function activeReporter<T>(resolve: (target: T | null) => PanelActive | null, report: (at: PanelActive | null) => void, schedule: (flush: () => void) => () => void): {
+    pointer(target: T | null): void;
+    focus(target: T | null): void;
+    /** Stops listening; what was active is no longer, so a last `null` is reported. */
+    dispose(): void;
+};
+/** Where an event's node is: in the panel, in one of its menus (on the body), or elsewhere. */
+export type ActiveWhere = "inside" | "menu" | "outside";
+/**
+ * The panel's pointer and focus events, told to `reporter` (see `activeReporter`). Focus that
+ * moves into one of the panel's menus keeps the row that opened it until it comes back, moves
+ * elsewhere, or leaves the menu for nowhere (a blur, the menu closing without handing it back).
+ * A pointer that moves (not just one the page scrolled under) takes the lead back from focus.
+ */
+export declare function activeEvents<T>(reporter: {
+    pointer(target: T | null): void;
+    focus(target: T | null): void;
+}, where: (node: T | null) => ActiveWhere): {
+    over(e: {
+        readonly target: T | null;
+    }): void;
+    move(e: {
+        readonly target: T | null;
+        readonly movementX: number;
+        readonly movementY: number;
+    }): void;
+    out(e: {
+        readonly relatedTarget: T | null;
+    }): void;
+    /** On the document: focus arriving anywhere. */
+    focusIn(e: {
+        readonly target: T | null;
+    }): void;
+    /** On the document: focus going nowhere (the window losing it, a blur) fires no focusin. */
+    focusOut(e: {
+        readonly target: T | null;
+        readonly relatedTarget: T | null;
+    }): void;
+};
+/**
+ * Tells `report` what the pointer or focus is on in `root` (see `activeReporter` and
+ * `activeEvents`), resolving the element under them with `resolve`. Returns a cleanup.
+ */
+export declare function watchActive(root: HTMLElement, resolve: (node: Element | null) => PanelActive | null, report: (at: PanelActive | null) => void): {
+    dispose(): void;
+};

package/dist/types/panel/description-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Ids for one panel's row descriptions (`aria-describedby`), unique in the page: each panel gets
+ * its own number, so a store mounted twice doesn't repeat them, and the store's id is cut to the
+ * characters an id reference list can carry.
+ */
+export declare function descriptionIds(storeId: string): () => string;

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

@@ -1,14 +1,17 @@
 import { type StoragePort } from "../core/storage.js";
-/** What a page remembers folded or open: its sections and its group cards. */
-export type FoldKind = "sections" | "groups";
+/**
+ * What a page or panel remembers folded or open: a page's sections, group cards, and a panel's
+ * sub-headings.
+ */
+export type FoldKind = "sections" | "groups" | "subsections";
 export interface FoldMemory {
     /** What the user last chose for it, if anything. */
     get(kind: FoldKind, id: string): boolean | undefined;
     set(kind: FoldKind, id: string, folded: boolean): void;
 }
 /**
- * A page's folds, kept under `knobs:<id>:folds:v1` in `storage` as
- * `{ sections: Record<string, boolean>, groups: Record<string, boolean> }`, and nothing else (no
+ * A page's or panel's folds, kept under `knobs:<id>:folds:v1` in `storage` as
+ * `{ sections, groups, subsections? }` (each a `Record<string, boolean>`), and nothing else (no
  * values, locks or variants). `null` storage remembers nothing.
  */
 export declare function foldMemory(id: string, storage: () => StoragePort | null): FoldMemory;

package/dist/types/panel/gpu/color.d.ts

@@ -70,6 +70,8 @@ export interface PanelThemeTokens {
     readonly trayPad: number;
     readonly radius: number;
     readonly panelRadius: number;
+    /** A tuning panel's own outer corners, concentric with its cards (`--k-radius-frame`). */
+    readonly frameRadius: number;
     readonly radiusMd: number;
     readonly radiusSm: number;
     readonly fontSize: number;

package/dist/types/panel/gpu/renderer.d.ts

@@ -399,9 +399,9 @@ export interface GpuGroupBinding {
     readonly peek?: HTMLElement;
     /** On a page: the header's controls (presets, reset, die), hidden while the card is folded. */
     readonly controls?: HTMLElement;
-    /** On a page: what a folded card's header says in place of its controls. */
+    /** What a folded card's header says (on a page, in place of its controls). */
     readonly summary?: HTMLElement;
-    /** On a page: the muted line under the card's title. */
+    /** The muted line under the card's title. */
     readonly desc?: HTMLElement;
     /** On a page: the group's presets, as named or numbered segments, or a compact menu. */
     readonly presets?: {
@@ -732,6 +732,12 @@ declare class GpuOverlayManager {
     private clipCache;
     /** Whether the DOM lays `el`'s text out wider than its box (so text-overflow shows "…"). */
     private domClipped;
+    private lineCache;
+    /**
+     * The lines the DOM wraps `el`'s text into, each with its middle's offset from `el`'s top, read
+     * back word by word (kept until the text or the width changes).
+     */
+    private linesOf;
     private curReduced;
     private curLocks;
     /** The current row's selection wash (0…1), which its hover wash gives way to. */

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

@@ -5,6 +5,7 @@ export { computeHintPrefixes, type HintBadgeState, type HintCandidate, type Hint
 export { assignPageCodes, hints, pageHints, type HintPainter, type HintSourceOptions, type PageHints, type PageHintTarget, } from "./page-hints.js";
 export { Spring, VelocityTracker } from "./motion.js";
 export { createPanel, mountPage, mountPanel, type Panel, type PanelSearch } from "./panel.js";
+export type { PanelActive } from "../core/store.js";
 export { balancedRuns, type FoldSummaryInfo, type MountPageOptions, type Page, type PageAction, type PageCard, type PageCardOptions, type PageControl, type PageFoldOptions, type PageFoldSource, type PageGroupInfo, type PageHighlight, type PageSectionInfo, } from "./page.js";
 export { createPresetStrip, nextPresetIndex, resolveActivePresetEntry, type ActivePresetState, type PresetEntry, type PresetStrip, } from "./presets.js";
 export { sound, type CueDetail, type Sound, type SoundCue, type SoundLayer, type SoundOptions, type SoundTheme, } from "./sound.js";

package/dist/types/panel/page-hints.d.ts

@@ -56,8 +56,9 @@ export interface PageHints {
     stop(): void;
     readonly active: boolean;
     /**
-     * Whether `s` anywhere on the page starts hint mode: a panel or host has registered, and there's
-     * something else on the page to label too.
+     * Whether `s` in a knobs/ui piece starts hint mode: a panel or host has registered, and there's
+     * something else on the page to label too. On the page itself it does only when the host asked
+     * (targets of its own, or `[data-hint]` elements).
      */
     readonly listening: boolean;
 }

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

@@ -1,15 +1,7 @@
 import type { StoragePort } from "../core/storage.js";
-import type { MountPanelOptions, SectionFolded } from "../core/store.js";
+import type { FoldSummaryInfo, MountPanelOptions, SectionFolded } from "../core/store.js";
 import type { Panel } from "./panel.js";
-/** What a folded card's or section's summary is made of (see `MountPageOptions.groupSummary`). */
-export interface FoldSummaryInfo {
-    /** The group preset its values match (its name), "Custom" when none does; null without any. */
-    readonly preset: string | null;
-    /** How many of its rows differ from their defaults (a spring's two keys count once). */
-    readonly changed: number;
-    /** Its value keys. */
-    readonly keys: readonly string[];
-}
+export type { FoldSummaryInfo };
 export interface MountPageOptions extends MountPanelOptions {
     /** Section order; sections not listed follow in the order they first appear. */
     readonly sections?: readonly string[];
@@ -39,11 +31,6 @@ export interface MountPageOptions extends MountPanelOptions {
      * opening it if it's folded.
      */
     readonly nav?: boolean;
-    /**
-     * What a folded group card's header says. By default "<matching preset, or Custom> · N
-     * changed", leaving out what doesn't apply. `null` shows nothing.
-     */
-    readonly groupSummary?: (group: string, info: FoldSummaryInfo) => string | Node | null;
     /** What a folded section's heading says ("N changed · M cards" by default; `preset` is null). */
     readonly sectionSummary?: (section: string, info: FoldSummaryInfo) => string | Node | null;
 }

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

@@ -1,4 +1,27 @@
 import { type StoragePort } from "../core/storage.js";
+/** Where a floating panel was left: `x` from the left edge, or from the right with `right`. */
+export interface SavedPosition {
+    readonly x: number;
+    readonly y: number;
+    readonly right?: boolean;
+}
+/**
+ * The position to keep for a panel dropped at `left`, `top`: a panel on the right half keeps its
+ * distance from the right edge, so a wider or narrower window leaves it by the same edge.
+ */
+export declare function savedPosition(left: number, top: number, width: number, view: number): {
+    x: number;
+    y: number;
+    right: true;
+} | {
+    x: number;
+    y: number;
+    right?: undefined;
+};
+/** The left edge a saved position asks for in a `view` px wide window. */
+export declare const leftOf: (saved: SavedPosition, width: number, view: number) => number;
+/** Reads a saved position, or `undefined` for none (or one that isn't a position). */
+export declare function readPosition(raw: string | null | undefined): SavedPosition | undefined;
 export declare function positionPanel(panel: HTMLElement, header: HTMLElement, anchor: HTMLElement, id: string, storage: () => StoragePort | null): {
     constrain: () => void;
     dispose(): void;

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

@@ -0,0 +1,22 @@
+import type { Controls } from "../core/store.js";
+/** A row of a folded panel card, as its summary reads it. */
+export interface SummaryRow {
+    /** Its value as text ("CSS orb", "12 px"), or "" where it has no short form. */
+    readonly value: string;
+    /** Whether it differs from its default. */
+    readonly changed: boolean;
+    /** Whether it's a choice (the likeliest to say what the card is set to). */
+    readonly choice: boolean;
+}
+/**
+ * A folded panel card's summary, by default: a one-row card's value; otherwise the most telling
+ * value (its matching group preset, else its first changed value, else its first choice) and
+ * "N changed", each only where it applies. `preset` is null for a card without group presets.
+ */
+export declare function panelFoldSummary(rows: readonly SummaryRow[], preset: string | null): string;
+/**
+ * Which presets the values are measured against (the panel's, each scope's and each group's).
+ * It changes when one is chosen or saved even if no value moves, which still changes what counts
+ * as changed: marks, resets and folded summaries follow it.
+ */
+export declare const baseSignature: (controls: Pick<Controls<any>, "activePreset" | "activeGroupPreset" | "scopes" | "groupPresets">) => string;

package/dist/types/tokens/schema.d.ts

@@ -491,6 +491,15 @@ export declare const TOKENS: readonly [{
     };
     readonly doc: "Panel and card radius, concentric with controls.";
     readonly deprecated: readonly ["--k-panel-radius", "--ku-panel-radius"];
+}, {
+    readonly name: "radius-frame";
+    readonly tier: "semantic";
+    readonly type: "length";
+    readonly group: "Shape";
+    readonly source: {
+        readonly css: "calc(var(--k-radius) + min(var(--k-radius) * 999, var(--_k-pad) + 1px))";
+    };
+    readonly doc: "A tuning panel's outer corners: its cards' radius plus its padding and border, so the cards, the preset strip and the focus lens inside run concentric. Squares when --k-radius is 0.";
 }, {
     readonly name: "round";
     readonly tier: "semantic";

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

@@ -1 +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-type-small)/var(--_k-leading-small) 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:var(--_k-gap);height:var(--_k-control-h)}\n/* The modes: one fill, the selection pill on the one picked; a mode isn't brighter for being\n   picked: the pill's bright copy is. */\n.knobs-cmp-modes{position:relative;display:inline-flex;height:var(--_k-control-h);border-radius:var(--_k-radius);background:var(--_k-fill)}\n.knobs-cmp-modes[hidden]{display:none}\n/* Hover is a quiet fill under the arrow cursor (no hand, no brightening), there at once. */\n.knobs-ui .knobs-cmp-mode{display:inline-flex;align-items:center;height:100%;padding:0 8px;border-radius:var(--_k-radius);color:var(--_k-fg-2);cursor:default;white-space:nowrap;\n  transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-mode:not([aria-checked=\"true\"]):is(:hover,:focus-visible){background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* Toggles: icon buttons, the accent's wash when on. */\n.knobs-ui .knobs-cmp-toggle{display:inline-flex;align-items:center;justify-content:center;width:var(--_k-control-h);height:var(--_k-control-h);border-radius:var(--_k-radius);color:var(--_k-fg-2);cursor:default;\n  transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-toggle:is(:hover,:focus-visible){background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--_k-accent-fg);background:var(--_k-accent-soft)}\n.knobs-cmp-toggle svg{display:block}\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/* Zoomed, it pans: a move cursor, never a hand. */\n.knobs-compare[data-zoomed] .knobs-cmp-stage{cursor:move;touch-action:none}\n.knobs-compare[data-panning],.knobs-compare[data-panning] *{cursor:move!important}\n/* Wiping, the grip stands in for the cursor. */\n.knobs-compare[data-dragging],.knobs-compare[data-dragging] *{cursor:none!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/* The media comes in with its first frames: a fade and a 4px blur on the default spring. */\n.knobs-cmp-canvas,.knobs-compare[data-renderer=\"dom\"] .knobs-cmp-media{transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}\n.knobs-compare:not([data-ready]) :is(.knobs-cmp-canvas,.knobs-cmp-media){opacity:0;filter:blur(4px)}\n/* Over the pictures: a quiet scrim, dark in either appearance, blurred, with no ring. */\n.knobs-cmp-label,.knobs-cmp-zoom,.knobs-cmp-grip{background:var(--_ku-media-scrim);-webkit-backdrop-filter:blur(12px);backdrop-filter:blur(12px)}\n/* \u2717 Before \u00B7 \u2713 After: Before quieter, After in full. Neutral: no colour of its own. */\n.knobs-cmp-label{position:absolute;left:0;top:0;display:flex;align-items:center;gap:4px;padding:1px 7px 1px 5px;border-radius:999px;font-weight:var(--_k-weight-label);\n  white-space:nowrap;pointer-events:none;will-change:transform}\n.knobs-cmp-label[data-side=\"before\"]{color:var(--_ku-on-media-2)}\n.knobs-cmp-label[data-side=\"after\"]{color:var(--_ku-on-media)}\n/* Fusing, the mark folds away and the label is its name. */\n.knobs-cmp-mark{flex:none;display:flex;justify-content:flex-end;overflow:hidden}\n.knobs-cmp-mark svg{display:block;flex:none;width:12px;height:12px}\n/* The fuse's seam: a blurred strip over where the sides meet, soft at both sides. */\n.knobs-cmp-seam{position:absolute;left:0;top:0;width:8px;height:0;opacity:0;pointer-events:none;will-change:transform,opacity;\n  -webkit-mask-image:linear-gradient(to right,transparent,#000 35%,#000 65%,transparent);mask-image:linear-gradient(to right,transparent,#000 35%,#000 65%,transparent)}\n/* The wipe: a hairline down the line with a raised grip in its middle (at the pointer's height\n   while dragged); a wider strip takes the hand and the keys (a slider). It fades in with the\n   fuse; wiping, line and grip brighten. */\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,opacity}\n.knobs-cmp-handle[data-on]{pointer-events:auto}\n.knobs-cmp-handle::before{content:\"\";position:absolute;top:0;bottom:0;left:11.5px;width:1px;background:color-mix(in srgb,var(--_ku-cmp-line) 72%,transparent);box-shadow:0 0 6px var(--_ku-media-scrim)}\n.knobs-compare[data-dragging] .knobs-cmp-handle::before{background:var(--_ku-cmp-line)}\n.knobs-cmp-grip{position:absolute;top:0;left:4px;width:16px;height:28px;border-radius:min(8px,calc(var(--_k-radius) * 999));will-change:transform}\n.knobs-cmp-grip::before,.knobs-cmp-grip::after{content:\"\";position:absolute;top:10px;width:1px;height:8px;background:var(--_ku-on-media-2);transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-cmp-grip::before{left:6px}\n.knobs-cmp-grip::after{left:9px}\n.knobs-compare[data-dragging] .knobs-cmp-grip::before,.knobs-compare[data-dragging] .knobs-cmp-grip::after{background:var(--_ku-on-media)}\n.knobs-cmp-handle:focus-visible .knobs-cmp-grip,.knobs-compare[data-keyboard] .knobs-cmp-handle:focus .knobs-cmp-grip{box-shadow:0 0 0 2px var(--_k-accent)}\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(--_ku-on-media);font-variant-numeric:tabular-nums;font-feature-settings:var(--_kr-data,\"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  display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;padding:0;border-radius:999px;background:transparent;color:var(--_ku-on-media-2);cursor:default;transition:background calc(var(--_k-hover-out) * 1ms),color calc(var(--_k-hover-out) * 1ms)}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){background:color-mix(in srgb,var(--_ku-on-media) 16%,transparent);color:var(--_ku-on-media);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);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;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-type-small)/var(--_k-leading-small) 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";
+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-type-small)/var(--_k-leading-small) 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:var(--_k-gap);height:var(--_k-control-h)}\n/* The modes: one fill, the selection pill on the one picked; a mode isn't brighter for being\n   picked: the pill's bright copy is. */\n.knobs-cmp-modes{position:relative;display:inline-flex;height:var(--_k-control-h);border-radius:var(--_k-radius);background:var(--_k-fill)}\n.knobs-cmp-modes[hidden]{display:none}\n/* Hover is a quiet fill under the arrow cursor (no hand, no brightening), there at once. */\n.knobs-ui .knobs-cmp-mode{display:inline-flex;align-items:center;height:100%;padding:0 8px;border-radius:var(--_k-radius);color:var(--_k-fg-2);cursor:default;white-space:nowrap;\n  transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-mode:not([aria-checked=\"true\"]):is(:hover,:focus-visible){background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* Toggles: icon buttons, the accent's wash when on. */\n.knobs-ui .knobs-cmp-toggle{display:inline-flex;align-items:center;justify-content:center;width:var(--_k-control-h);height:var(--_k-control-h);border-radius:var(--_k-radius);color:var(--_k-fg-2);cursor:default;\n  transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui .knobs-cmp-toggle:is(:hover,:focus-visible){background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui .knobs-cmp-toggle[aria-pressed=\"true\"]{color:var(--_k-accent-fg);background:var(--_k-accent-soft)}\n.knobs-cmp-toggle svg{display:block}\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/* Zoomed, it pans: a move cursor, never a hand. */\n.knobs-compare[data-zoomed] .knobs-cmp-stage{cursor:move;touch-action:none}\n.knobs-compare[data-panning],.knobs-compare[data-panning] *{cursor:move!important}\n/* Wiping, the grip stands in for the cursor. */\n.knobs-compare[data-dragging],.knobs-compare[data-dragging] *{cursor:none!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/* The media comes in with its first frames: a fade and a 4px blur on the default spring. */\n.knobs-cmp-canvas,.knobs-compare[data-renderer=\"dom\"] .knobs-cmp-media{transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}\n.knobs-compare:not([data-ready]) :is(.knobs-cmp-canvas,.knobs-cmp-media){opacity:0;filter:blur(4px)}\n/* Over the pictures: a quiet scrim, dark in either appearance, blurred, with no ring. */\n.knobs-cmp-label,.knobs-cmp-zoom,.knobs-cmp-grip{background:var(--_ku-media-scrim);-webkit-backdrop-filter:blur(12px);backdrop-filter:blur(12px)}\n/* \u2717 Before \u00B7 \u2713 After: Before quieter, After in full. Neutral: no colour of its own. */\n.knobs-cmp-label{position:absolute;left:0;top:0;display:flex;align-items:center;gap:4px;padding:1px 7px 1px 5px;border-radius:999px;font-weight:var(--_k-weight-label);\n  white-space:nowrap;pointer-events:none;will-change:transform}\n.knobs-cmp-label[data-side=\"before\"]{color:var(--_ku-on-media-2)}\n.knobs-cmp-label[data-side=\"after\"]{color:var(--_ku-on-media)}\n/* Fusing, the mark folds away and the label is its name. */\n.knobs-cmp-mark{flex:none;display:flex;justify-content:flex-end;overflow:hidden}\n.knobs-cmp-mark svg{display:block;flex:none;width:12px;height:12px}\n/* The fuse's seam: a blurred strip over where the sides meet, soft at both sides. */\n.knobs-cmp-seam{position:absolute;left:0;top:0;width:8px;height:0;opacity:0;pointer-events:none;will-change:transform,opacity;\n  -webkit-mask-image:linear-gradient(to right,transparent,#000 35%,#000 65%,transparent);mask-image:linear-gradient(to right,transparent,#000 35%,#000 65%,transparent)}\n/* The wipe: a hairline down the line with a raised grip in its middle (at the pointer's height\n   while dragged); a wider strip takes the hand and the keys (a slider). It fades in with the\n   fuse; wiping, line and grip brighten. */\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,opacity}\n.knobs-cmp-handle[data-on]{pointer-events:auto}\n.knobs-cmp-handle::before{content:\"\";position:absolute;top:0;bottom:0;left:11.5px;width:1px;background:color-mix(in srgb,var(--_ku-cmp-line) 72%,transparent);box-shadow:0 0 6px var(--_ku-media-scrim)}\n.knobs-compare[data-dragging] .knobs-cmp-handle::before{background:var(--_ku-cmp-line)}\n.knobs-cmp-grip{position:absolute;top:0;left:4px;width:16px;height:28px;border-radius:min(8px,calc(var(--_k-radius) * 999));will-change:transform}\n.knobs-cmp-grip::before,.knobs-cmp-grip::after{content:\"\";position:absolute;top:10px;width:1px;height:8px;background:var(--_ku-on-media-2);transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-cmp-grip::before{left:6px}\n.knobs-cmp-grip::after{left:9px}\n.knobs-compare[data-dragging] .knobs-cmp-grip::before,.knobs-compare[data-dragging] .knobs-cmp-grip::after{background:var(--_ku-on-media)}\n.knobs-cmp-handle:focus-visible .knobs-cmp-grip,.knobs-compare[data-keyboard] .knobs-cmp-handle:focus .knobs-cmp-grip{box-shadow:0 0 0 2px var(--_k-accent)}\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(--_ku-on-media);font-variant-numeric:tabular-nums;font-feature-settings:var(--_kr-data,\"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  display:inline-flex;align-items:center;justify-content:center;width:20px;height:20px;padding:0;border-radius:999px;background:transparent;color:var(--_ku-on-media-2);cursor:default;transition:background calc(var(--_k-hover-out) * 1ms),color calc(var(--_k-hover-out) * 1ms)}\n:where(.knobs-ui) .knobs-cmp-zoom-reset:is(:hover,:focus-visible){background:color-mix(in srgb,var(--_ku-on-media) 16%,transparent);color:var(--_ku-on-media);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-cmp-note{position:absolute;left:50%;top:50%;translate:-50% -50%;color:var(--_k-fg-3);pointer-events:none}\n.knobs-cmp-note:empty{display:none}\n.knobs-cmp-timeline-host{flex:none;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-type-small)/var(--_k-leading-small) 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

@@ -15,10 +15,23 @@ export interface FrameCache {
     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;
+    /** Scrub proxies held now, and every how many frames they are. */
+    readonly proxies: {
+        readonly count: number;
+        readonly stride: number;
+        readonly bytes: number;
+    };
+    /**
+     * The cached frame nearest `frame`, no further than `within` frames. `decode`: a nearer scrub
+     * proxy that's stored but not decoded starts decoding (listeners hear when it's in).
+     */
+    nearest(frame: number, within?: number, decode?: boolean): CachedFrame | null;
+    /** Whether a frame this close to `frame` is held, decoded or as a proxy (within its stride). */
+    covers(frame: number): boolean;
     /** The playhead of the viewer being used: full-size frames around it decode first. */
     focus(frame: number): void;
+    /** The playhead of a viewer being scrubbed: this cache goes first, nothing full-size is asked. */
+    follow(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). */
@@ -31,11 +44,60 @@ export interface FrameCache {
 }
 /** Frames either side of the focus decoded at full size. */
 export declare const FOCUS_RADIUS = 6;
+/** A scrub proxy's longest side, JPEG quality, the bytes a source's proxies may hold, how many stay decoded. */
+export declare const PROXY: {
+    readonly size: 960;
+    readonly quality: 0.8;
+    readonly budget: number;
+    readonly decoded: 8;
+    /** Proxies a unit makes before another cache takes its turn. */
+    readonly turn: 90;
+};
+/** What `scrubCaching` reads of a window. */
+export interface DataSaver {
+    readonly matchMedia?: (query: string) => {
+        readonly matches: boolean;
+    };
+    readonly navigator?: object;
+}
+/**
+ * Whether a viewer caches its frames in the background (it fetches the whole file and decodes
+ * it): unless its `scrubCache` option is false, the reader prefers reduced data, or the
+ * connection is saving data. Without it, scrubbing seeks the video as it goes.
+ */
+export declare function scrubCaching(option: boolean | undefined, win: DataSaver | null | undefined): boolean;
+/** The stride a set of proxies needs to stay in `budget`: the smallest power of two that does. */
+export declare function proxyStride(bytes: number, count: number, total: number, budget: number): number;
+/** Where a hand moving from `last` to `frame` is likely to be next (within 0 and `total`). */
+export declare const aheadOf: (frame: number, last: number | null, total: number) => number | null;
 /** 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;
+/** What the encoder pool needs of a window (a stand-in in tests). */
+export interface EncoderHost {
+    readonly Worker?: new (url: string) => Worker;
+    readonly OffscreenCanvas?: unknown;
+    readonly URL: Pick<typeof URL, "createObjectURL" | "revokeObjectURL">;
+    readonly Blob: typeof Blob;
+}
+export interface Encoders {
+    readonly workers: Worker[];
+    readonly waiting: Map<number, {
+        done(b: Blob): void;
+        fail(e: unknown): void;
+    }>;
+    next: number;
+}
+/** A cache uses the pool: it's made the first time a proxy is encoded. */
+export declare function holdEncoders(): void;
+/** A cache is done with the pool: the last one ends its workers, and the next starts afresh. */
+export declare function dropEncoders(): void;
+/** The page's encoder pool, made on first use; null where workers can't run. */
+export declare function encodersOf(host: EncoderHost): Encoders | null;
+/** `bitmap` as a JPEG on one of the pool's workers (it takes the bitmap). */
+export declare function encodeOn(pool: Encoders, bitmap: ImageBitmap, quality: number): Promise<Blob>;
 /** 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-model.d.ts

@@ -67,6 +67,29 @@ export interface SeekStep {
 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;
+/**
+ * Where a video showing `current` seeks once a scrub lets go at `t`: the midpoint of `t`'s frame,
+ * or null when that frame already shows. Frames, not seconds: 1.030 and 1.040 are 1/100 s apart
+ * and two frames at 30 fps.
+ */
+export declare function releaseSeek(current: number, t: number, fps: number, duration?: number): number | null;
+/** How long a seek may take to land before the preview over it gives way (ms). */
+export declare const SEEK_STALL_MS = 2500;
+/** What `stallGuard` reads of a window. */
+export interface Timers {
+    setTimeout(f: () => void, ms: number): number;
+    clearTimeout(id: number): void;
+}
+/**
+ * A seek that never lands (a decoder that gave up, a network that went away) mustn't leave a
+ * preview over the video forever: `arm` when a seek goes out, `clear` when it lands, and
+ * `onStall` runs if it doesn't within `ms`.
+ */
+export declare function stallGuard(timers: Timers, onStall: () => void, ms?: number): {
+    arm(): void;
+    clear: () => void;
+    readonly armed: boolean;
+};
 export interface Rect {
     readonly x: number;
     readonly y: number;

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

@@ -1,5 +1,4 @@
 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";
@@ -51,8 +50,6 @@ export interface CompareOptions extends UiLook {
      * `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.
@@ -62,6 +59,12 @@ export interface CompareOptions extends UiLook {
     readonly lazy?: boolean;
     /** `"gpu"` (the default, where WebGPU is there) or `"dom"`. */
     readonly renderer?: "gpu" | "dom";
+    /**
+     * Decode the videos' frames in the background, so a step or a scrub shows its frame at once (it
+     * fetches each whole file). On unless the reader prefers reduced data or saves data; false
+     * never, true always. Without it, the videos seek as the playhead moves.
+     */
+    readonly scrubCache?: boolean;
     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;
@@ -86,7 +89,6 @@ export interface Compare {
     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. */

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

@@ -1 +1 @@
-export declare const playerCss = "\n:where(.knobs-player,.knobs-player *){box-sizing:border-box}\n.knobs-ui.knobs-player{--_kp-stage:var(--_k-compare-stage);display:flex;flex-direction:column;gap:6px;width:100%;outline:none;\n  font:var(--_k-weight) var(--_k-type-small)/var(--_k-leading-small) var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-player,.knobs-ui.knobs-player[data-nested]{--_kp-stage:var(--k-compare-stage,transparent)}\n.knobs-player-frame{position:relative;width:100%;aspect-ratio:var(--kp-aspect,16/9);overflow:hidden;border-radius:var(--_k-radius-panel);background:var(--_kp-stage)}\n.knobs-player[data-frame=\"flat\"] .knobs-player-frame{border-radius:0}\n.knobs-player-media{position:absolute;inset:0;display:block;width:100%;height:100%;margin:0;padding:0;border:0;object-fit:contain;\n  opacity:0;filter:blur(4px);transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}\n.knobs-player[data-ready] .knobs-player-media{opacity:1;filter:none}\n.knobs-player-line{flex:none;min-height:0}\n/* The timeline's own stylesheet is look.ts's; what the player's row and every timeline share\n   about the hand is set here, after it. No hand cursor anywhere (the arrow, or a resize where it\n   resizes); hover is a quiet fill (fill-hover), in at once (hover-in, 0 ms), out easing. */\n.knobs-ui .knobs-tl-play,.knobs-ui.knobs-timeline :is(.knobs-tl-pin,.knobs-tl-rlabel),\n.knobs-ui.knobs-timeline[data-dragging] .knobs-tl-marker :is(.knobs-tl-pin,.knobs-tl-mlabel){cursor:default}\n.knobs-ui .knobs-tl-play:hover,.knobs-tl-edge:hover::after,.knobs-tl-rlabel:hover,.knobs-tl-track:hover .knobs-tl-hover,\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover .knobs-tl-segs{transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* The line's row: a minimal play/pause (the filled pair, a 28px target, no fill at rest), then\n   the line, centred on it. */\n.knobs-ui.knobs-timeline[data-variant=\"line\"]{gap:4px;align-items:center}\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-transport{display:flex}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play{width:28px;height:28px;min-width:28px;min-height:28px;border-radius:var(--_k-radius);background:transparent;color:var(--_k-fg-2);\n  transition:background calc(var(--_k-hover-out) * 1ms),transform .15s var(--_ku-ease)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"][data-playing] .knobs-tl-play{background:transparent;color:var(--_k-fg-2)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track{cursor:default;transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n";
+export declare const playerCss = "\n:where(.knobs-player,.knobs-player *){box-sizing:border-box}\n.knobs-ui.knobs-player{--_kp-stage:var(--_k-compare-stage);display:flex;flex-direction:column;gap:6px;width:100%;outline:none;\n  font:var(--_k-weight) var(--_k-type-small)/var(--_k-leading-small) var(--_k-font);color:var(--_k-fg);letter-spacing:normal;text-align:left}\n:where(.knobs-surface,.knobs-pane:not([data-nested])>.knobs-pane-clip) .knobs-ui.knobs-player,.knobs-ui.knobs-player[data-nested]{--_kp-stage:var(--k-compare-stage,transparent)}\n.knobs-player-frame{position:relative;width:100%;aspect-ratio:var(--kp-aspect,16/9);overflow:hidden;border-radius:var(--_k-radius-panel);background:var(--_kp-stage)}\n.knobs-player[data-frame=\"flat\"] .knobs-player-frame{border-radius:0}\n.knobs-player-media{position:absolute;inset:0;display:block;width:100%;height:100%;margin:0;padding:0;border:0;object-fit:contain;\n  opacity:0;filter:blur(4px);transition:opacity calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default),filter calc(var(--_k-motion-default-ms) * 1ms) var(--_k-motion-default)}\n.knobs-player[data-ready] .knobs-player-media{opacity:1;filter:none}\n/* Mid-scrub, the cached frame under the hand, over the video until it lands. */\n.knobs-player-preview{position:absolute;inset:0;display:block;width:100%;height:100%;object-fit:contain;pointer-events:none}\n.knobs-player-preview[hidden]{display:none}\n.knobs-player-line{flex:none;min-height:0}\n/* The timeline's own stylesheet is look.ts's; what the player's row and every timeline share\n   about the hand is set here, after it. No hand cursor anywhere (the arrow, or a resize where it\n   resizes); hover is a quiet fill (fill-hover), in at once (hover-in, 0 ms), out easing. */\n.knobs-ui .knobs-tl-play,.knobs-ui.knobs-timeline :is(.knobs-tl-pin,.knobs-tl-rlabel),\n.knobs-ui.knobs-timeline[data-dragging] .knobs-tl-marker :is(.knobs-tl-pin,.knobs-tl-mlabel){cursor:default}\n.knobs-ui .knobs-tl-play:hover,.knobs-tl-edge:hover::after,.knobs-tl-rlabel:hover,.knobs-tl-track:hover .knobs-tl-hover,\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover .knobs-tl-segs{transition-duration:calc(var(--_k-hover-in) * 1ms)}\n/* The line's row: a minimal play/pause (the filled pair, a 28px target, no fill at rest), then\n   the line, centred on it. */\n.knobs-ui.knobs-timeline[data-variant=\"line\"]{gap:4px;align-items:center}\n.knobs-timeline[data-variant=\"line\"] .knobs-tl-transport{display:flex}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play{width:28px;height:28px;min-width:28px;min-height:28px;border-radius:var(--_k-radius);background:transparent;color:var(--_k-fg-2);\n  transition:background calc(var(--_k-hover-out) * 1ms),transform .15s var(--_ku-ease)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"][data-playing] .knobs-tl-play{background:transparent;color:var(--_k-fg-2)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-play:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track{cursor:default;transition:background calc(var(--_k-hover-out) * 1ms)}\n.knobs-ui.knobs-timeline[data-variant=\"line\"] .knobs-tl-track:hover{background:var(--_k-fill-hover);transition-duration:calc(var(--_k-hover-in) * 1ms)}\n";

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

@@ -24,6 +24,12 @@ export interface PlayerOptions extends UiLook {
     readonly label?: string;
     /** The line's play key and playhead take codes in the page's hint mode (on by default). */
     readonly hints?: boolean;
+    /**
+     * Decode its frames in the background once the pointer comes near, so a scrub shows the frame
+     * under the hand (it fetches the whole file). On unless the reader prefers reduced data or saves
+     * data; false never, true always.
+     */
+    readonly scrubCache?: boolean;
     /** Played or paused, at `time` (seconds). */
     onPlay?(playing: boolean, time: number): void;
     /** Sought by the hand (the line, a key, a chapter) or code, at rest. */

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

@@ -66,7 +66,7 @@ export type CompareProps = CompareOptions & {
 };
 /**
  * `compare()` as a component. `before`, `after` (by `src`), `mode`, `wipe`, `loupe`, `threshold`
- * and `fps` follow their props; a new `timeline` handle, `strip` or `renderer` makes it afresh;
+ * and `fps` follow their props; a new `timeline` handle, `renderer` or `scrubCache` makes it afresh;
  * callbacks always call the latest props.
  */
 export declare function Compare(props: CompareProps): import("react").JSX.Element;

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

@@ -56,7 +56,7 @@ export type CompareProps = CompareOptions & {
     onReady?: (compare: CompareHandle) => void;
 };
 /**
- * `compare()` as a component, made once (with the `timeline`, `strip` and `renderer` it starts
+ * `compare()` as a component, made once (with the `timeline` and `renderer` it starts
  * with). `before`, `after` (by `src`), `mode`, `wipe`, `loupe`, `threshold` and `fps` follow
  * their props; callbacks always call the latest props.
  */