@kitlangton/knobs 0.4.0-next.0 → 0.4.0-next.10

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

@@ -1,6 +1,7 @@
 import type { ControlDescriptor } from "./remote.js";
 import type { Choice, Schema, State } from "./schema.js";
-import type { Controls, DensityMode, MountPanelOptions, ThemeMode } from "./store.js";
+import type { Controls, DensityMode, MountPanelOptions } from "./store.js";
+import { type LookOptions } from "./appearance.js";
 export type ChoiceKey<S extends Schema> = {
     [K in keyof S]: S[K] extends Choice ? K : never;
 }[keyof S] & string;
@@ -16,6 +17,9 @@ export type KnobsPanelProps<S extends Schema = Schema> = MountPanelOptions & {
     /** While true, a different item is arriving: values land without springing or rolling. */
     land?: boolean;
 };
-export declare function syncPanelLook<S extends Schema>(host: HTMLElement | null | undefined, controls: Controls<S>, theme?: ThemeMode, density?: DensityMode): void;
+/** The look a panel takes: its props' over its store's. */
+export declare const panelLook: <S extends Schema>(controls: Controls<S>, look?: LookOptions) => import("./appearance.js").Look;
+/** Restyles the mounted panel in place (theme, appearance, preset, density), so its tokens glide. */
+export declare function syncPanelLook<S extends Schema>(host: HTMLElement | null | undefined, controls: Controls<S>, look?: LookOptions, density?: DensityMode): void;
 export declare function syncPanelValues<S extends Schema>(controls: Controls<S>, descriptors?: readonly ControlDescriptor[], values?: State, land?: boolean): void;
 export declare function mountPanelAdapter<S extends Schema>(host: HTMLElement, controls: Controls<S>, getProps: () => KnobsPanelProps<S>): () => void;

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

@@ -0,0 +1,44 @@
+import type { Theme } from "../themes/define.js";
+import { type TokenPreset } from "./theme.js";
+/**
+ * Light or dark: `dark` and `light` fix it, `system` follows the OS, and `inherit` (the default)
+ * follows the page: a `color-scheme`, a `.dark`/`.light` class, `[data-theme]` or
+ * `[data-appearance]` on an ancestor, or an outer knobs element, else the OS.
+ */
+export type Appearance = "dark" | "light" | "system" | "inherit";
+/** @deprecated The old name for an appearance: `auto` is `system`. Use `appearance`. */
+export type ThemeMode = "dark" | "light" | "auto";
+/** How a panel, chip or knobs/ui piece looks: its theme, its appearance (and an old preset). */
+export interface LookOptions {
+    /**
+     * A theme from `defineTheme` (or `themes.knobs`, `themes.void`). Knobs' own when unset.
+     * `"dark" | "light" | "auto"` is the old spelling of `appearance` and still works.
+     */
+    readonly theme?: Theme | ThemeMode;
+    readonly appearance?: Appearance;
+    /** @deprecated A `TokenPreset` (`labPreset`): its tokens over the theme's. */
+    readonly preset?: TokenPreset;
+}
+/** A look with every part decided. */
+export interface Look {
+    readonly theme?: Theme;
+    readonly appearance: Appearance;
+    readonly preset?: TokenPreset;
+}
+/** `options` over `base`: a theme object, an appearance (or an old mode), a preset. */
+export declare function resolveLook(options?: LookOptions, base?: Partial<Look>): Look;
+/** The theme an element shows: the nearest themed knobs element's, else knobs' own (undefined). */
+export declare function themeOf(el: Element): Theme | undefined;
+/** The selector a theme's tokens sit under: any knobs element marked with its name. */
+export declare const themeSelector: (name: string) => string;
+/** Adds a theme's tokens once per document, under `[data-knobs-theme="<name>"]`. */
+export declare function injectTheme(doc: Document, theme: Theme): void;
+/** Adds a preset's tokens once per document, for any knobs element marked `data-preset`. */
+export declare function injectPreset(doc: Document, preset: TokenPreset): void;
+/** Marks `el` (a knobs root) with `look`: its theme's tokens, its appearance and its preset. */
+export declare function applyLook(el: HTMLElement, look: Look): void;
+/**
+ * The look `el` shows, fixed: its theme and preset, and the appearance it shows now. For something
+ * floated out of it (a drag ghost, a menu) to match it wherever it lands.
+ */
+export declare function lookAt(el: Element): Look;

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

@@ -0,0 +1,7 @@
+/** The transitions that glide every driver, for a root that also transitions its own properties. */
+export declare const TOKEN_TRANSITIONS: string;
+/** Elements whose tokens glide: each declares the drivers. */
+export declare const GLIDING = ".knobs-panel,.knobs-chip,.knobs-notice,.knobs-ui";
+export declare const DRIVERS: string;
+/** Rules read the gliding aliases of what glides, and what the knobs root resolved otherwise. */
+export declare const aliased: (css: string) => string;

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

@@ -0,0 +1,66 @@
+import { type SpringValue } from "./spring.js";
+/**
+ * The five named springs (SwiftUI duration and bounce), all without bounce. Every motion in knobs
+ * uses one of these unless it's tuned for one feature.
+ */
+export declare const SPRINGS: {
+    /** Press feedback, focus, selection, pointer-tied moves. */
+    readonly instant: {
+        readonly duration: 0.1;
+        readonly bounce: 0;
+    };
+    /** Value fills, thumbs, toggles, small controls, menus, exits. */
+    readonly snappy: {
+        readonly duration: 0.25;
+        readonly bounce: 0;
+    };
+    /** Most state changes: popovers, panel open and close, restyle glides (`--k-spring`). */
+    readonly default: {
+        readonly duration: 0.3;
+        readonly bounce: 0;
+    };
+    /** Layout reflow, split panes, list reorders. */
+    readonly calm: {
+        readonly duration: 0.4;
+        readonly bounce: 0;
+    };
+    /** Appearance and theme changes, drawers, page-scale moves. */
+    readonly smooth: {
+        readonly duration: 0.45;
+        readonly bounce: 0;
+    };
+};
+export type SpringName = keyof typeof SPRINGS;
+/** A quick fade that isn't travel (and what any fade becomes under reduced motion). */
+export declare const FADE: SpringValue;
+/** A popover or menu closing: a little shorter than snappy. */
+export declare const CLOSE: SpringValue;
+/** The named springs as ω/ζ, for `new Spring(x, omega, zeta)`. */
+export declare const MOTION: { readonly [K in SpringName]: {
+    readonly omega: number;
+    readonly zeta: number;
+}; };
+export declare const reducedMotion: (win: Window | null | undefined) => boolean;
+/**
+ * The reduced-motion policy: movement doesn't travel (`null`: go straight to the end), and a fade
+ * keeps a short fade (at most `FADE`).
+ */
+export declare function reducedSpring(spring: SpringValue, kind: "move" | "fade", reduced: boolean): SpringValue | null;
+/** A spring as a CSS `linear()` easing and its settle time (ms). */
+export declare const springLinear: (spring: SpringValue) => {
+    easing: string;
+    ms: number;
+};
+/** `--k-spring`'s default: the default spring as "duration bounce". */
+export declare const SPRING_TOKEN: string;
+/** The default spring as CSS, for `--k-fill-ease` and `--k-fill-ms`. */
+export declare const DEFAULT_LINEAR: {
+    easing: string;
+    ms: number;
+};
+/**
+ * Each named spring as CSS on :root: `--_k-motion-<name>` (a `linear()` easing) and
+ * `--_k-motion-<name>-ms` (its settle time, a number of ms). Under reduced motion they take 0 ms:
+ * movement doesn't travel.
+ */
+export declare const motionCss: string;

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

@@ -0,0 +1,13 @@
+/**
+ * The class every knobs top-level element carries: panels, chips, menus, the status notice, and
+ * every knobs/ui piece's root. Each resolves the design tokens for itself (see tokens/css.ts), so
+ * a theme, an appearance or a host's token on any ancestor reaches what's derived from it.
+ */
+export declare const ROOT_CLASS = "knobs-root";
+/**
+ * The token sheet: the Knobs theme's defaults, every root's resolution and appearance, the
+ * drivers that make tokens glide, and the motion tokens.
+ */
+export declare const rootCss: string;
+/** Adds the token sheet once per document. */
+export declare function injectTokens(doc: Document): void;

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

@@ -1,9 +1,11 @@
 import { type CodeFormat } from "./code.js";
 import type { TokenPreset } from "./theme.js";
+import type { Appearance, ThemeMode } from "./appearance.js";
+import type { Theme } from "../themes/define.js";
 import { type ReadoutInput, type ReadoutKeys, type Schema, type State, type Values } from "./schema.js";
 import { type StoragePort } from "./storage.js";
 import { type Variants } from "./variants.js";
-export type ThemeMode = "dark" | "light" | "auto";
+export type { Appearance, ThemeMode } from "./appearance.js";
 export type DensityMode = "compact" | "default" | "comfortable";
 export type RendererMode = "gpu" | "dom" | "auto";
 /** When a store's chip shows; see `ChipOptions.reveal`. */
@@ -157,7 +159,7 @@ export interface MountPanelOptions extends LabelOptions {
      * (a prototype's settings), where "default" means nothing. The store's `marks` by default.
      */
     readonly marks?: boolean;
-    /** Token values to style the panel with, e.g. `problemsPreset` (see `TokenPreset`). */
+    /** @deprecated Token values to style the panel with (see `TokenPreset`); use `theme`. */
     readonly preset?: TokenPreset;
     /**
      * `false` drops the header (title and buttons) for a host that draws its own. An object keeps
@@ -231,7 +233,13 @@ export interface MountPanelOptions extends LabelOptions {
     readonly onReady?: (panel: PanelHandle) => void;
     /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
     readonly copy?: () => string;
-    readonly theme?: ThemeMode;
+    /**
+     * A theme from `defineTheme` (`themes.knobs`, `themes.void`); the store's by default. The old
+     * `"dark" | "light" | "auto"` still sets the appearance.
+     */
+    readonly theme?: Theme | ThemeMode;
+    /** dark | light | system | inherit (the default: follow the page, else the OS). */
+    readonly appearance?: Appearance;
     readonly density?: DensityMode;
     readonly renderer?: RendererMode;
     readonly variants?: boolean;
@@ -347,7 +355,10 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
      */
     groupPresets?: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
     actions?: readonly ControlAction<Values<S>>[];
-    theme?: ThemeMode;
+    /** Its panels' theme (see `MountPanelOptions.theme`). */
+    theme?: Theme | ThemeMode;
+    /** Its panels' appearance (see `MountPanelOptions.appearance`). */
+    appearance?: Appearance;
     density?: DensityMode;
     renderer?: RendererMode;
     /** Default key bindings for this store's panels (see `MountPanelOptions.keys`). */
@@ -385,7 +396,9 @@ export interface Controls<S extends Schema = Schema> {
     readonly presets: Readonly<Record<string, Values<S>>>;
     readonly variants: Variants<Values<S>>;
     readonly actions: readonly ControlAction<Values<S>>[];
-    readonly theme: ThemeMode;
+    /** Its panels' theme, as given (see `ControlsOptions.theme`). */
+    readonly theme: Theme | ThemeMode | undefined;
+    readonly appearance: Appearance | undefined;
     readonly density: DensityMode;
     readonly renderer: RendererMode;
     readonly keys: PanelKeys | undefined;

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

@@ -1,7 +1,10 @@
 /**
- * A named set of `--k-*` token values for dark and light, applied to panels mounted with
+ * A named set of `--k-*` token values for dark and light, applied to knobs elements mounted with
  * `{ preset }` (or with `data-preset="<name>"` and `presetCss(preset)` in your own stylesheet).
- * `css` adds rules for anything tokens don't cover; `&` stands for the panel.
+ * `css` adds rules for anything tokens don't cover; `&` stands for the element.
+ *
+ * @deprecated Use `defineTheme` (from `knobs/themes`), which generates both appearances from a
+ * few dials. Presets keep working; their token names go through the deprecated aliases.
  */
 export interface TokenPreset {
     readonly name: string;
@@ -9,7 +12,11 @@ export interface TokenPreset {
     readonly light?: Readonly<Record<string, string | number>>;
     readonly css?: string;
 }
-/** The stylesheet for a preset: its dark tokens, its light ones wherever a panel is light. */
+/**
+ * The stylesheet for a preset. A token it gives for both appearances becomes `light-dark(light,
+ * dark)`, so it follows the element's appearance (its `color-scheme`) like the theme's colours
+ * do; anything else holds in both.
+ */
 export declare function presetCss(preset: TokenPreset): string;
 /**
  * A dense, square editor (Arcade's Lab): radius 0, compact 26 px rows, the flat frame (groups as

package/dist/types/index.d.ts

@@ -1,10 +1,11 @@
 export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, actionShortcut, watch, sparkline, graph, meter, table, log, hasValue, isReadout, wrapAngle, SPRING, type FieldMeta, type ActionField, type SpringPart, type ValueField, type Knob, type Choice, type Toggle, type SpringField, type ColorField, type PointField, type EasingField, type VecField, type Vec3, type RangeField, type AngleField, type SeedField, type KeybindField, type GradientField, type CurveField, type ToolbarField, type ToolbarItem, type ToolbarShortcut, type WatchField, type SparklineField, type GraphField, type GraphSeries, type GraphThreshold, type MeterField, type TableField, type LogField, type ReadoutField, type ReadoutKeys, type ReadoutInput, type Point, type Field, type Schema, type Values, type Value, type State, } from "./core/schema.js";
 export { springCss, springMotion, type SpringValue } from "./core/spring.js";
+export { reducedSpring, SPRINGS, type SpringName } from "./core/motion.js";
 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, } from "./core/store.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 { 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/gpu/color.d.ts

@@ -1,4 +1,5 @@
 import { mixRgba as mixColor, parseCssColor, type Rgba, withAlpha } from "../../ui/rgba.js";
+import type { GpuColors, Theme } from "../../themes/define.js";
 export { mixColor, parseCssColor, type Rgba, withAlpha };
 /** CSS `color-mix(in srgb, a p, b)`, interpolated with premultiplied alpha like the browser. */
 export declare function cssMix(a: Rgba, b: Rgba, p: number): Rgba;
@@ -126,3 +127,8 @@ export interface PanelThemeTokens {
     readonly shadowStrength: number;
 }
 export declare function readPanelTokens(panel: HTMLElement, version?: number): PanelThemeTokens;
+/**
+ * A theme's colours for one appearance, as the renderer draws them (sRGB, straight alpha): what
+ * the panel shows where no CSS (a host's override, a preset, a glide) says otherwise.
+ */
+export declare function gpuDefaults(theme: Theme | undefined, light: boolean): GpuColors;

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

@@ -1,6 +1,6 @@
 import { Spring } from "../core/spring.js";
 export { Spring, springEasing } from "../core/spring.js";
-/** The slider fill, and its rubber band springing back from past an end. */
+/** The slider fill (the default spring, as --k-spring), and its rubber band springing back from past an end. */
 export declare const FILL: {
     omega: number;
     zeta: number;

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

@@ -1,11 +1,10 @@
-import { type TokenPreset } from "../core/theme.js";
 /**
  * What DELAY times: a row's turn in a preset's cascade is set on these (see `showValues` in
  * panel.ts) rather than on the row, where the custom property would restyle all of the row.
  */
 export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-track,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
-/** Adds a token preset's stylesheet once per document. */
-export declare function injectPreset(doc: Document, preset: TokenPreset): void;
 /** The rules' `:has()` as the attributes has.ts keeps (see there for why). */
 export declare const withoutHas: (css: string) => string;
+/** The panel stylesheet, as `injectStyles` writes it (after the token sheet). */
+export declare const panelCss: () => string;
 export declare function injectStyles(doc: Document): void;

package/dist/types/review/font.d.ts

@@ -0,0 +1,13 @@
+import { type Theme } from "../themes/define.js";
+export interface ReviewFontOptions {
+    /** A stylesheet that declares the face (Google Fonts, rsms.me/inter, your own). */
+    readonly href?: string;
+    /** The family, first in the stack: `"Inter"`, `"Geist"`. The platform's face follows it. */
+    readonly sans?: string;
+    readonly mono?: string;
+}
+/**
+ * The review look in a webfont: loads `href` once per document and returns the review theme with
+ * `sans` (and `mono`) first in its stacks. Pass it as `theme`.
+ */
+export declare function reviewFont(doc: Document, options: ReviewFontOptions): Theme;

package/dist/types/review/foundations.d.ts

@@ -0,0 +1,175 @@
+/** The five sizes. Two weights: 400, and 500 for titles and emphasis. */
+export declare const TYPE: readonly [{
+    readonly role: "heading";
+    readonly size: 20;
+    readonly leading: 28;
+    readonly weight: 500;
+    readonly use: "A page's title";
+}, {
+    readonly role: "title";
+    readonly size: 16;
+    readonly leading: 24;
+    readonly weight: 500;
+    readonly use: "A section's title, under its kicker";
+}, {
+    readonly role: "body";
+    readonly size: 13;
+    readonly leading: 20;
+    readonly weight: 400;
+    readonly use: "Prose, step and option titles (500), rows, values";
+}, {
+    readonly role: "label";
+    readonly size: 12;
+    readonly leading: 16;
+    readonly weight: 400;
+    readonly use: "Mono inside body text: code, paths, evidence chips";
+}, {
+    readonly role: "small";
+    readonly size: 11;
+    readonly leading: 16;
+    readonly weight: 400;
+    readonly use: "Meta, terms, kickers, controls, keys, times";
+}];
+export type TypeRole = (typeof TYPE)[number]["role"];
+/**
+ * Tracking follows size, one rule for every element: (body − size) × 0.03, so 20 px closes up by
+ * 0.21 px, 16 px by 0.09, 13 px sits at 0 and 11 px opens by 0.06. Mono never tracks.
+ */
+export declare const TRACKING = 0.03;
+export declare const trackingAt: (size: number, body?: number) => number;
+/** Prose stops here: 45–75 characters, centred on 66. */
+export declare const MEASURE = "66ch";
+/**
+ * The type stack: the platform's own UI face (SF Pro with its optical sizes on Apple, Segoe UI
+ * Variable on Windows), so nothing downloads, nothing swaps in, and the pages read like the native
+ * apps beside them. A webfont goes in through `reviewFont`.
+ */
+export declare const FONT: {
+    readonly sans: "system-ui,-apple-system,BlinkMacSystemFont,\"Segoe UI Variable Text\",\"Segoe UI\",Roboto,\"Helvetica Neue\",Arial,sans-serif";
+    readonly mono: "ui-monospace,\"SF Mono\",SFMono-Regular,\"Cascadia Mono\",\"JetBrains Mono\",Menlo,Consolas,monospace";
+};
+/**
+ * OpenType: tabular figures everywhere (times and counts never jitter); in data, `ss01` too
+ * (straight-sided 6 and 9 in SF, open digits in Inter: figures that can't be misread); code with
+ * no ligatures (`=>` stays two characters).
+ */
+export declare const FEATURES: {
+    readonly figures: "tabular-nums";
+    readonly data: "\"tnum\" 1,\"ss01\" 1";
+    readonly code: "none";
+};
+/** The space roles (px, on the 4 px unit); each from `title` up at least doubles the one below. */
+export declare const SPACE: readonly [{
+    readonly role: "inside";
+    readonly px: 4;
+    readonly use: "Parts of one thing: an icon and its label, a term and its value";
+}, {
+    readonly role: "sibling";
+    readonly px: 8;
+    readonly use: "Siblings in a group: rows, buttons, a list's lines";
+}, {
+    readonly role: "title";
+    readonly px: 12;
+    readonly use: "A heading and what it heads";
+}, {
+    readonly role: "block";
+    readonly px: 24;
+    readonly use: "Blocks inside one piece: fact groups, columns, media and its caption";
+}, {
+    readonly role: "group";
+    readonly px: 48;
+    readonly use: "Steps and options, a hairline in the middle";
+}, {
+    readonly role: "section";
+    readonly px: 96;
+    readonly use: "Sections of a page, a hairline in the middle";
+}];
+/** Hairlines and fills: alpha of the text colour, held to an APCA target on the page. */
+export declare const HAIRLINES: readonly [{
+    readonly token: "border-subtle";
+    readonly lc: 9;
+    readonly use: "Dividers between rows, steps and sections";
+}, {
+    readonly token: "border";
+    readonly lc: 12;
+    readonly use: "Rings round frames and wells";
+}, {
+    readonly token: "border-strong";
+    readonly lc: 17;
+    readonly use: "Interactive edges, a focus that isn't the accent";
+}];
+export declare const FILLS: readonly [{
+    readonly token: "fill";
+    readonly use: "A well at rest: code, a chip, a frame loading";
+}, {
+    readonly token: "fill-hover";
+    readonly use: "Under the pointer, at once";
+}, {
+    readonly token: "fill-selected";
+    readonly use: "The selection pill, a pressed toggle";
+}];
+/** Radii, concentric: what sits inside a frame takes the frame's radius less the gap between. */
+export declare const RADII: readonly [{
+    readonly token: "radius";
+    readonly px: 8;
+    readonly use: "Controls and rows 28–32 px high";
+}, {
+    readonly token: "radius-panel";
+    readonly px: 12;
+    readonly use: "Frames, wells, cards";
+}, {
+    readonly token: "radius / 2";
+    readonly px: 4;
+    readonly use: "Inline code, chips, rows 20 px high";
+}];
+/**
+ * The motion set. Springs are a duration and no bounce; nothing moves on load; hovers land at once
+ * and ease out; a whole thing replaced in place fades with a 3 px blur.
+ */
+export declare const MOTION: readonly [{
+    readonly name: "hover";
+    readonly spring: null;
+    readonly ms: "0 in, 120 out";
+    readonly use: "A hover's fill: on at once, off softly";
+}, {
+    readonly name: "quick";
+    readonly spring: import("../index.js").SpringValue;
+    readonly use: "Replacing a whole thing in place: fade, scale .98, blur 3 px";
+}, {
+    readonly name: "close";
+    readonly spring: import("../index.js").SpringValue;
+    readonly use: "A popover closing";
+}, {
+    readonly name: "snappy";
+    readonly spring: {
+        readonly duration: 0.25;
+        readonly bounce: 0;
+    };
+    readonly use: "Controls: a toggle, a pick, a chapter row";
+}, {
+    readonly name: "state";
+    readonly spring: {
+        readonly duration: 0.3;
+        readonly bounce: 0;
+    };
+    readonly use: "The selection pill, a disclosure opening";
+}, {
+    readonly name: "calm";
+    readonly spring: {
+        readonly duration: 0.4;
+        readonly bounce: 0;
+    };
+    readonly use: "Layout: a compare's height, the page scrolling to a step";
+}, {
+    readonly name: "smooth";
+    readonly spring: {
+        readonly duration: 0.45;
+        readonly bounce: 0;
+    };
+    readonly use: "A step opening to the full window";
+}];
+/**
+ * The foundations as private tokens on every review root; the review stylesheet reads them.
+ * Tracking is a calc in em, so it resolves on each element at its own size.
+ */
+export declare const foundationCss: string;

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

@@ -0,0 +1,13 @@
+export { FEATURES, FILLS, FONT, HAIRLINES, MEASURE, MOTION, RADII, SPACE, TRACKING, TYPE, trackingAt, type TypeRole, } from "./foundations.js";
+export { reviewFont, type ReviewFontOptions } from "./font.js";
+export { reviewTheme } from "../themes/review.js";
+export { injectUiStyles, restyle, type RestyleLook, type UiLook } from "../ui/look.js";
+export { tasteTest, walkthrough, type TasteTest, type TasteTestOptions, type Walkthrough, type WalkthroughOptions, } from "../ui/walkthrough.js";
+export { decision, facts, mediaSlot, type DecisionOptions, type FactsOptions, type MediaSlot, type MediaSlotOptions, type StepLinks, } from "../ui/walkthrough-media.js";
+export { compare, type Compare, type CompareLoop, type CompareMode, type CompareOptions, type CompareSource, type CompareView, type ZoomRegion, } from "../ui/compare.js";
+export { compareStrip, type CompareStrip, type CompareStripOptions } from "../ui/compare-strip.js";
+export { player, type Player, type PlayerChapter, type PlayerOptions } from "../ui/player.js";
+export { codeDiff, diffReview, type CodeDiff, type CodeDiffOptions, type CodeDiffUpdate, type DiffLayout, type DiffReview, type DiffReviewOptions, } from "../ui/diff.js";
+export type { DiffSource } from "../ui/diff-model.js";
+export { history, type History, type HistoryBand, type HistoryData, type HistoryEvent, type HistoryEvidence, type HistoryGroup, type HistoryLane, type HistoryOptions, type HistoryProvenance, type HistorySpan, type HistoryState, type HistoryTone, } from "../ui/history.js";
+export { collectFeedback, feedbackMarkdown, inlineMarkdown, normalizeWalkthrough, plainMarkdown, readState as readWalkthroughState, walkthroughProgress, type FeedbackItem, type FeedbackNote, type WalkPage, type WalkStep, type WalkthroughAnnotation, type WalkthroughChapter, type WalkthroughDecisionOption, type WalkthroughFact, type WalkthroughFactGroup, type WalkthroughFacts, type WalkthroughDoc, type WalkthroughEvidence, type WalkthroughFeedback, type WalkthroughHistoryEvent, type WalkthroughHistoryGroup, type WalkthroughMedia, type WalkthroughMeta, type WalkthroughOption, type WalkthroughPR, type WalkthroughQA, type WalkthroughSection, type WalkthroughSource, type WalkthroughStackItem, type WalkthroughState, type WalkthroughStatus, type WalkthroughStep, type WalkthroughTableCell, type WalkthroughTableColumn, type WalkthroughTableRow, type WalkthroughTone, type WalkthroughUpdate, } from "../ui/walkthrough-model.js";

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

@@ -0,0 +1 @@
+export { CodeDiff, Compare, CompareStrip, DiffReview, MediaSlot, TasteTest, Walkthrough, type CodeDiffProps, type CompareProps, type CompareStripProps, type DiffReviewProps, type MediaSlotProps, type TasteTestProps, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughProps, } from "../ui/react.js";

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

@@ -0,0 +1 @@
+export { CodeDiff, Compare, CompareStrip, DiffReview, MediaSlot, TasteTest, Walkthrough, type CodeDiffProps, type CompareProps, type CompareStripProps, type DiffReviewProps, type MediaSlotProps, type TasteTestProps, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughProps, } from "../ui/solid.js";

package/dist/types/themes/define.d.ts

@@ -0,0 +1,104 @@
+import { type Rgba } from "../tokens/color.js";
+import { type ColorTokenName, type TokenName } from "../tokens/schema.js";
+export type Appearance = "dark" | "light";
+export type Density = "compact" | "default" | "comfortable";
+export type Material = "glass" | "solid" | "flat";
+export type TokenOverrides = Partial<Record<TokenName, string>>;
+/** What `defineTheme` takes. Everything but `name` is optional and deep-merges over `extends`. */
+export interface ThemeSpec {
+    readonly name: string;
+    readonly extends?: Theme;
+    /** Tint of the neutral ladder. Chroma 0–0.02; 0.004 reads as neutral with a hint of hue. */
+    readonly gray?: {
+        readonly hue?: number;
+        readonly chroma?: number;
+    };
+    /** The accent: one colour (its dark-appearance value; light is derived) or one per appearance. */
+    readonly accent?: string | {
+        readonly dark: string;
+        readonly light: string;
+    };
+    /** 0–100, 50 by default: spreads the surface ladder and text tiers, scales fills and borders. */
+    readonly contrast?: number;
+    /** Control radius in px. */
+    readonly radius?: number;
+    readonly density?: Density;
+    readonly material?: Material;
+    readonly font?: {
+        readonly sans?: string;
+        readonly mono?: string;
+    };
+    /** Escape hatch: any token's value, per appearance. Applied after generation. */
+    readonly tokens?: {
+        readonly dark?: TokenOverrides;
+        readonly light?: TokenOverrides;
+    };
+}
+/** A spec with every dial filled in. */
+export interface ThemeInputs {
+    readonly gray: {
+        readonly hue: number;
+        readonly chroma: number;
+    };
+    readonly accent: string | {
+        readonly dark: string;
+        readonly light: string;
+    };
+    readonly contrast: number;
+    readonly radius: number;
+    readonly density: Density;
+    readonly material: Material;
+    readonly font: {
+        readonly sans: string;
+        readonly mono: string;
+    };
+    readonly tokens: {
+        readonly dark: TokenOverrides;
+        readonly light: TokenOverrides;
+    };
+}
+export type ResolvedTokens = Readonly<Record<TokenName, string>>;
+export type GpuColors = Readonly<Record<ColorTokenName, Rgba>>;
+export interface Theme {
+    readonly name: string;
+    readonly inputs: ThemeInputs;
+    /**
+     * Every token for each appearance. Colours are fully resolved hex (`#rrggbb` or `#rrggbbaa`);
+     * other tokens carry their CSS value or derivation.
+     */
+    readonly dark: ResolvedTokens;
+    readonly light: ResolvedTokens;
+    /** What the theme itself declares (generated values plus overrides); the CSS is built from it. */
+    readonly declared: {
+        readonly dark: TokenOverrides;
+        readonly light: TokenOverrides;
+    };
+    /** Every colour token as linear-light sRGB floats `[r, g, b, a]` (straight alpha), for WebGPU. */
+    readonly gpu: {
+        readonly dark: GpuColors;
+        readonly light: GpuColors;
+    };
+    /**
+     * The theme's CSS in `@layer knobs.tokens`. With no selector, the full default sheet (its values
+     * on `:root`, every token resolved on `.knobs-root`, appearance rules). With a selector, one
+     * block of what this theme declares, to scope it to part of a page.
+     */
+    css(options?: {
+        readonly selector?: string;
+    }): string;
+}
+/** The APCA budget each ink must meet on `bg`. */
+export declare const APCA_BUDGET: {
+    readonly fg: 90;
+    readonly "fg-2": 75;
+    readonly "fg-3": 45;
+    readonly "fg-4": 30;
+    readonly "accent-fg": 60;
+    readonly "border-strong": 15;
+};
+/**
+ * Builds a theme from a few dials: a neutral ladder generated in OKLCH and checked against the
+ * APCA budget, an accent with its text and on-accent colours, a shared status palette, chart
+ * series and material values, resolved for both appearances.
+ */
+export declare function defineTheme(spec: ThemeSpec): Theme;

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

@@ -1 +1,17 @@
+import { knobs } from "./knobs.js";
+import { reviewTheme } from "./review.js";
+import { voidTheme } from "./void.js";
+export { APCA_BUDGET, type Appearance as ThemeAppearance, type Density, defineTheme, type GpuColors, type Material, type ResolvedTokens, type Theme, type ThemeInputs, type ThemeSpec, type TokenOverrides, } from "./define.js";
+export { knobs, reviewTheme, voidTheme };
+export type { Appearance } from "../core/appearance.js";
+export type { PublicTokenName, TokenName, TokenProperty } from "../tokens/schema.js";
+/**
+ * The shipped themes: Knobs (the default), Void (true black, flat, for OLED and video) and Review
+ * (the review pieces' own default: Void with hairlines you can see).
+ */
+export declare const themes: {
+    readonly knobs: import("./define.js").Theme;
+    readonly void: import("./define.js").Theme;
+    readonly review: import("./define.js").Theme;
+};
 export { labPreset, presetCss, problemsPreset, type TokenPreset } from "../core/theme.js";

package/dist/types/themes/knobs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The main look: a `#1c1c1e`-class panel floating on a near-black page, glass, a white
+ * monochrome accent and alpha hairlines. Its light pair keeps `#f5f5f7` / `#1a1a1c` / `#1c1c1e`.
+ */
+export declare const knobs: import("./define.js").Theme;

package/dist/types/themes/review.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The review pieces' own look (walkthrough, compare, player, diff, facts, decision): Void's true
+ * black, flat and neutral, with hairlines you can see. Borders are alpha of the text colour, set
+ * by APCA on the page: subtle ≈ Lc 9, default ≈ Lc 12, strong ≈ Lc 17, in both appearances
+ * (Void's composited 6% and 10% read Lc 0 on black). Fills step 6 / 10 / 14% so a hover's
+ * background is plain to see. Light is white, page and surface alike. The platform's own face.
+ */
+export declare const reviewTheme: import("./define.js").Theme;