versioncam 0.1.1

package/dist/cli/commands/stability.js

@@ -0,0 +1,110 @@
+import { copyFileSync, mkdirSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+import { parseArgs } from "node:util";
+import { runClip } from "../../driver/clip.js";
+import { compareRecordings, stateFileAt } from "../../driver/compare.js";
+import { launchBrowser } from "../../driver/launch.js";
+import { loadClips, loadConfig } from "../../loader.js";
+import { drivingApp } from "../app.js";
+/**
+ * Does this app record the same way twice?
+ *
+ * The README's rule — when a clip will not reproduce, record it twice the same
+ * way first — as a command, and as the first thing done in a repository before
+ * anything is authored for it. A clip is only as deterministic as the app it
+ * films: a page that renders the wall-clock time, or animates something the
+ * recorder's clock does not drive, gives a different video every run, and
+ * every clip written against it will fail CI for reasons nobody wrote.
+ *
+ * Draft by default, because the question is about the app and not the pixels:
+ * a draft is the same page at the same size, a quarter of the frames.
+ */
+export async function stability(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            runs: { type: "string", default: "2" },
+            // Accepted for saying so explicitly; drafting is the default.
+            draft: { type: "boolean" },
+            full: { type: "boolean" },
+        },
+        strict: false,
+        allowPositionals: true,
+    });
+    const runs = Number(values.runs);
+    if (!Number.isInteger(runs) || runs < 2) {
+        process.stderr.write(`--runs must be a whole number of 2 or more, got ${values.runs}.\n`);
+        return 1;
+    }
+    const draft = values.full !== true;
+    const config = await loadConfig(process.cwd());
+    const clips = await loadClips(config, positionals);
+    if (clips.length === 0) {
+        process.stderr.write(positionals.length > 0
+            ? `No clip matched ${positionals.join(", ")}.\n`
+            : `No clips found. The config looks for ${config.clips.join(", ")} under ${config.root}.\n`);
+        return 1;
+    }
+    return drivingApp(config, () => compareRuns(config, clips, runs, draft));
+}
+async function compareRuns(config, clips, runs, draft) {
+    const browser = await launchBrowser();
+    let stable = true;
+    try {
+        for (const clip of clips) {
+            const recordings = [];
+            for (let run = 1; run <= runs; run += 1) {
+                // Each run in its own directory, beside the real recordings and never
+                // over one: the clip's own recording is what `render` and `sheet`
+                // read, and a stability check must not replace it.
+                const into = join(config.recordingsDir, "__stability", `run-${run}`);
+                try {
+                    const { dir, timeline } = await runClip(browser, { ...config, recordingsDir: into }, clip, { draft });
+                    recordings.push({ dir, timeline });
+                }
+                catch (error) {
+                    process.stdout.write(`${clip.id}: run ${run} did not record — ${error.message}\n`);
+                    return 1;
+                }
+            }
+            for (let run = 1; run < runs; run += 1) {
+                const [a, b] = [recordings[run - 1], recordings[run]];
+                const result = compareRecordings(a, b);
+                const pair = `${clip.id}: run ${run} vs run ${run + 1}`;
+                if (result.firstDifference === null) {
+                    process.stdout.write(`${pair} — ${result.frames} frames, ${result.identical} identical\n`);
+                    continue;
+                }
+                stable = false;
+                const frame = result.firstDifference;
+                process.stdout.write(`${pair} — ${result.frames} frames, ${result.identical} identical, ` +
+                    `first difference at frame ${frame}\n`);
+                // The two pictures behind that frame, side by side on disk: what
+                // differs is almost always obvious once seen, and never from a hash.
+                const out = join(config.outDir, "stability", clip.id);
+                mkdirSync(out, { recursive: true });
+                for (const [index, recording] of [
+                    [run, a],
+                    [run + 1, b],
+                ]) {
+                    const state = stateFileAt(recording, frame);
+                    if (!state) {
+                        process.stdout.write(`  run ${index} has no frame ${frame}\n`);
+                        continue;
+                    }
+                    const copy = join(out, `frame-${frame}-run${index}${extname(state)}`);
+                    copyFileSync(state, copy);
+                    process.stdout.write(`  ${relative(process.cwd(), copy)}\n`);
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    process.stdout.write(stable
+        ? "stable\n"
+        : "unstable — something on this page does not run on authored time\n");
+    return stable ? 0 : 1;
+}
+//# sourceMappingURL=stability.js.map

package/dist/cli/commands/stability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability.js","sourceRoot":"","sources":["../../../src/cli/commands/stability.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { check } from "./commands/check.js";
+import { doctor } from "./commands/doctor.js";
+import { dsl } from "./commands/dsl.js";
+import { frame } from "./commands/frame.js";
+import { init } from "./commands/init.js";
+import { inspect } from "./commands/inspect.js";
+import { install } from "./commands/install.js";
+import { login } from "./commands/login.js";
+import { measure } from "./commands/measure.js";
+import { preview } from "./commands/preview.js";
+import { record } from "./commands/record.js";
+import { render } from "./commands/render.js";
+import { review } from "./commands/review.js";
+import { sheet } from "./commands/sheet.js";
+import { stability } from "./commands/stability.js";
+import { loadEnvFiles } from "../env.js";
+import { USAGE } from "./usage.js";
+const COMMANDS = {
+    record,
+    render,
+    check,
+    stability,
+    sheet,
+    frame,
+    preview,
+    review,
+    inspect,
+    measure,
+    dsl,
+    login,
+    doctor,
+    install,
+    init,
+};
+async function main() {
+    const argv = process.argv.slice(2);
+    // `--help` is a flag, not a positional, so it never reaches `positionals`.
+    // Asking for help is a success; being given nothing is not.
+    if (argv.some((a) => a === "--help" || a === "-h" || a === "help")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    const { positionals } = parseArgs({
+        args: argv,
+        strict: false,
+        allowPositionals: true,
+    });
+    const name = positionals[0];
+    if (!name) {
+        process.stdout.write(USAGE);
+        return 1;
+    }
+    const command = COMMANDS[name];
+    if (!command) {
+        process.stderr.write(`Unknown command "${name}".\n\n${USAGE}`);
+        return 1;
+    }
+    loadEnvFiles(process.cwd());
+    return command(process.argv.slice(3));
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`\n${error.message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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"}

package/dist/cli/usage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What `versioncam --help` prints, and the README's *Commands* block,
+ * line for line.
+ *
+ * Its own module so a test can read it without running the CLI: the README
+ * is also the website's documentation, and a test holds the two to the same
+ * list — the DSL reference learned why, promising an `s.drag` for months that
+ * did not exist.
+ */
+export declare const USAGE = "versioncam \u2014 record and render demo clips of a real app\n\n  versioncam record [id\u2026]            drive the app and capture frames\n      --draft                        15fps at CSS scale: cheap, for writing clips\n  versioncam render [id\u2026]            composite and encode what has been recorded\n      --scene <id>                   render a designed scene (repeatable)\n      --sequence                     stitch the results into one piece\n  versioncam check [id\u2026]             record everything; non-zero if any clip breaks\n  versioncam stability [id\u2026]         record each clip twice the same way; stable or not\n      --runs <n>                     how many times (default 2)\n      --full                         at full quality rather than draft\n  versioncam sheet <id>              an eight-frame contact sheet\n      --at-marks                     sample the beats instead of even spacing\n  versioncam frame <id> <n>          one frame at output size, to a png\n      --t <seconds>                  pick the frame by time instead\n      --at <label>                   or by the beat it shows\n  versioncam preview <id>            open the scrubber in a real browser\n      --scene <id>                   preview a scene instead\n      --frame <n>                    start at this frame\n  versioncam review <id>             the checks that need no eyes; PASS/FAIL, exit 0/1\n      --beats <file>                 [{ label, expect }] the clip promised\n      --min <s> --max <s>            duration bounds (default 9\u201311)\n  versioncam inspect <path>          what a clip can click, and where each name came from\n      --json                         machine-readable\n  versioncam measure <path> <sel>    where the matches of a selector are, and what they say\n  versioncam dsl                     the clip DSL, every method, one line each\n  versioncam login                   sign in once and save the browser session\n  versioncam doctor                  check this machine can record, and that the app starts\n  versioncam install                 the Chromium this version of versioncam records with\n      --with-deps                    and its system libraries (Linux CI)\n  versioncam init                    install the authoring skill into .claude/\n      --into <dir>                   into <dir>/versioncam/ instead, for another host\n      --force                        overwrite files that are already there\n\nRun from a directory containing versioncam.config.ts.\n";

package/dist/cli/usage.js

@@ -0,0 +1,46 @@
+/**
+ * What `versioncam --help` prints, and the README's *Commands* block,
+ * line for line.
+ *
+ * Its own module so a test can read it without running the CLI: the README
+ * is also the website's documentation, and a test holds the two to the same
+ * list — the DSL reference learned why, promising an `s.drag` for months that
+ * did not exist.
+ */
+export const USAGE = `versioncam — record and render demo clips of a real app
+
+  versioncam record [id…]            drive the app and capture frames
+      --draft                        15fps at CSS scale: cheap, for writing clips
+  versioncam render [id…]            composite and encode what has been recorded
+      --scene <id>                   render a designed scene (repeatable)
+      --sequence                     stitch the results into one piece
+  versioncam check [id…]             record everything; non-zero if any clip breaks
+  versioncam stability [id…]         record each clip twice the same way; stable or not
+      --runs <n>                     how many times (default 2)
+      --full                         at full quality rather than draft
+  versioncam sheet <id>              an eight-frame contact sheet
+      --at-marks                     sample the beats instead of even spacing
+  versioncam frame <id> <n>          one frame at output size, to a png
+      --t <seconds>                  pick the frame by time instead
+      --at <label>                   or by the beat it shows
+  versioncam preview <id>            open the scrubber in a real browser
+      --scene <id>                   preview a scene instead
+      --frame <n>                    start at this frame
+  versioncam review <id>             the checks that need no eyes; PASS/FAIL, exit 0/1
+      --beats <file>                 [{ label, expect }] the clip promised
+      --min <s> --max <s>            duration bounds (default 9–11)
+  versioncam inspect <path>          what a clip can click, and where each name came from
+      --json                         machine-readable
+  versioncam measure <path> <sel>    where the matches of a selector are, and what they say
+  versioncam dsl                     the clip DSL, every method, one line each
+  versioncam login                   sign in once and save the browser session
+  versioncam doctor                  check this machine can record, and that the app starts
+  versioncam install                 the Chromium this version of versioncam records with
+      --with-deps                    and its system libraries (Linux CI)
+  versioncam init                    install the authoring skill into .claude/
+      --into <dir>                   into <dir>/versioncam/ instead, for another host
+      --force                        overwrite files that are already there
+
+Run from a directory containing versioncam.config.ts.
+`;
+//# sourceMappingURL=usage.js.map

package/dist/cli/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/cli/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCpB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,250 @@
+import type { Page } from "playwright";
+import { MOTION } from "./core/motion-defaults.js";
+/**
+ * The one place an app describes itself to the recorder.
+ *
+ * Everything app-specific goes through this object. If the recorder ever needs
+ * to know something about an app that this cannot express, the boundary is in
+ * the wrong place and the fix is a field here, not a special case inside.
+ */
+/**
+ * `MOTION` is declared `as const` so each constant reads as its own documented
+ * value, which also makes its type the literal. Widen it here: an app
+ * overriding `zoomDurationMs` should be able to pass 2000, not only 1100.
+ */
+export type Motion = {
+    -readonly [K in keyof typeof MOTION]: number;
+};
+/**
+ * The surround: a backdrop, a device frame, padding, where the caption sits.
+ *
+ * Absent by default, because the product should record the product. It exists
+ * for the case where a clip is going on a landing page and wants to look like
+ * a product shot rather than a screen capture.
+ */
+export type Presentation = {
+    /** Two stops for a diagonal gradient, or one flat colour. */
+    backdrop?: [string, string] | string;
+    /** Rounded corners, hairline and drop shadow around the app. */
+    frame?: boolean;
+    /** Inset as a fraction of the smaller canvas dimension. 0 disables it. */
+    padding?: number;
+    /** "auto" puts it below the app when padded, and over it when not. */
+    caption?: "auto" | "below" | "overlay" | "none";
+};
+export type AuthConfig = {
+    storageState: string;
+    login?: never;
+} | {
+    login: (page: Page) => Promise<void>;
+    storageState?: never;
+};
+export type SettleConfig = {
+    /** How long the page must be quiet before it counts as settled. */
+    quietMs?: number;
+    /** Real-time cap. Exceeding it warns rather than failing the clip. */
+    timeoutMs?: number;
+    /** Real milliseconds yielded per tick, so the page can actually do work. */
+    yieldMs?: number;
+    /**
+     * Whatever the generic checks cannot see: a WebGL map that has finished its
+     * tiles, a stream that has delivered its first frame.
+     */
+    ready?: (page: Page) => Promise<boolean>;
+};
+export type CaptureConfig = {
+    /**
+     * Skip the screenshot when nothing observable changed since the last one.
+     * On by default: a clip is mostly frames where nothing moved, and the
+     * screenshot is by far the most expensive thing a frame does.
+     */
+    gate?: boolean;
+    /**
+     * Capture regardless every N frames, however still the page looks.
+     *
+     * The gate watches the DOM, the element under the cursor and the running
+     * animations, which covers everything a page built from elements can do. It
+     * does not cover a canvas, a WebGL view or a video, which redraw themselves
+     * without any of those changing. This is the floor under that blind spot:
+     * at 60 fps the default catches such a change within half a second. A clip
+     * whose subject *is* a canvas should set it to 1 and pay full price.
+     */
+    forceCaptureEvery?: number;
+};
+export type ReviewConfig = {
+    /**
+     * How long a clip of this app should run, in seconds.
+     *
+     * Ten seconds is the shape of a feature clip and the default, but it is a
+     * house style rather than a law: an app whose clips are one crisp
+     * interaction each should say five, and an app demonstrating a workflow may
+     * want twenty. `versioncam review` enforces whatever is here, the authoring
+     * loop aims at it, and `--min`/`--max` override it for one run.
+     */
+    minSeconds?: number;
+    maxSeconds?: number;
+};
+export type CursorStart = {
+    /** Fractions of the viewport: `{ x: 0.72, y: 0.28 }` is up and to the right. */
+    x: number;
+    y: number;
+};
+/**
+ * How to start the app when nothing is serving it yet.
+ *
+ * Playwright's `webServer`, field for field where Playwright has one, because
+ * everyone who would use this has already learned it. Without it the app has
+ * to be running before any command that drives it — which is a thing a person
+ * remembers and an agent working in a repository it has never seen does not.
+ */
+export type WebServerConfig = {
+    /** Run through a shell. Relative paths resolve against `cwd`. */
+    command: string;
+    /** What to wait for. Defaults to `baseUrl`. */
+    url?: string;
+    /** Defaults to the config file's directory. */
+    cwd?: string;
+    /** Default 120 000 — a map app's cold start, not a static page's. */
+    timeoutMs?: number;
+    /**
+     * Use a server that is already answering instead of starting one.
+     *
+     * Default `true`, and `false` when `process.env.CI` is set: on a developer's
+     * machine the server that is up is almost always theirs and the right one,
+     * and in CI one that is up before the job started it is something else.
+     */
+    reuseExistingServer?: boolean;
+    /** Merged over `process.env` for the child only. */
+    env?: Record<string, string>;
+};
+export type ResolvedWebServer = Required<WebServerConfig>;
+export type RecorderConfig = {
+    /** Where the app is served. */
+    baseUrl: string;
+    /** How to start it when it is not being served. Absent: it must already be. */
+    webServer?: WebServerConfig;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Device pixel ratio to capture at. 2 means a zoom reads real pixels rather
+     * than upscaled ones.
+     */
+    dpr?: number;
+    fps?: number;
+    /** Glob(s) for clip files, relative to the config. */
+    clips?: string | string[];
+    /** Everything the recorder writes. Gitignore it. */
+    outDir?: string;
+    auth?: AuthConfig;
+    settle?: SettleConfig;
+    capture?: CaptureConfig;
+    review?: ReviewConfig;
+    /**
+     * Where the cursor rests in the first captured frame, in fractions of the
+     * viewport. Default `{ x: 0.72, y: 0.28 }`.
+     *
+     * There is no good default, which is the point of the field. The original
+     * was picked to sit over open map and clear of the toolbars of the first app
+     * this recorded, and a reviewer has since failed a clip's opening frame on
+     * two different apps for landing on something: a list row in one, a
+     * "Select metrics" input in the other. `open()` captures frame 0 before a
+     * clip body's first line runs, so
+     * no `moveTo` can reach it — an app whose layout puts a control there has to
+     * say so here.
+     */
+    cursorStart?: CursorStart;
+    clock?: {
+        /** The instant the app's fake clock starts at. */
+        time?: string | Date;
+        timezoneId?: string;
+        locale?: string;
+    };
+    theme?: {
+        /** Click ripple and highlight ring. */
+        accent?: string;
+        cursorScale?: number;
+        presentation?: Presentation;
+    };
+    /** Output width; the height follows the viewport's aspect. */
+    output?: {
+        width?: number;
+    };
+    motion?: Partial<Motion>;
+    /** Module whose default export is `Record<string, Scene>`. */
+    scenes?: string;
+    /** Clip ids, in order, for `versioncam render --sequence`. */
+    sequence?: string[];
+};
+export type ResolvedConfig = {
+    root: string;
+    baseUrl: string;
+    webServer: ResolvedWebServer | null;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    dpr: number;
+    fps: number;
+    clips: string[];
+    outDir: string;
+    recordingsDir: string;
+    outputDir: string;
+    cacheDir: string;
+    auth: AuthConfig | null;
+    settle: Required<Omit<SettleConfig, "ready">> & {
+        ready: ((page: Page) => Promise<boolean>) | null;
+    };
+    capture: Required<CaptureConfig>;
+    review: Required<ReviewConfig>;
+    cursorStart: CursorStart;
+    clock: {
+        time: Date;
+        timezoneId: string;
+        locale: string;
+    };
+    theme: {
+        accent: string;
+        cursorScale: number;
+        presentation: Presentation | null;
+    };
+    output: {
+        width: number;
+        height: number;
+    };
+    motion: Motion;
+    scenes: string | null;
+    sequence: string[] | null;
+};
+/** Typed identity, so a config file gets completion and checking. */
+export declare function defineRecorder(config: RecorderConfig): RecorderConfig;
+/**
+ * Output dimensions follow the viewport's aspect.
+ *
+ * Nothing is letterboxed and nothing is cropped: record at 1440x900 and the
+ * video is 16:10; want 16:9, record at 1600x900. Heights are rounded to even
+ * because H.264 with yuv420p cannot encode an odd dimension.
+ */
+export declare function outputSize(viewport: {
+    width: number;
+    height: number;
+}, width: number): {
+    width: number;
+    height: number;
+};
+export declare function resolveConfig(config: RecorderConfig, root: string): ResolvedConfig;
+/** The subset the render page needs, serialised to `/render-config.json`. */
+export type RenderConfig = {
+    output: {
+        width: number;
+        height: number;
+    };
+    theme: {
+        accent: string;
+        cursorScale: number;
+        presentation: Presentation | null;
+    };
+    motion: Motion;
+};
+export declare function renderConfigOf(config: ResolvedConfig): RenderConfig;

package/dist/config.js

@@ -0,0 +1,154 @@
+import { isAbsolute, resolve } from "node:path";
+import { MOTION } from "./core/motion-defaults.js";
+/** Typed identity, so a config file gets completion and checking. */
+export function defineRecorder(config) {
+    return config;
+}
+function fail(field, why) {
+    throw new Error(`versioncam config: \`${field}\` ${why}`);
+}
+function positiveInt(value, field) {
+    if (!Number.isInteger(value) || value <= 0) {
+        fail(field, `must be a positive integer, got ${value}`);
+    }
+    return value;
+}
+/**
+ * Output dimensions follow the viewport's aspect.
+ *
+ * Nothing is letterboxed and nothing is cropped: record at 1440x900 and the
+ * video is 16:10; want 16:9, record at 1600x900. Heights are rounded to even
+ * because H.264 with yuv420p cannot encode an odd dimension.
+ */
+export function outputSize(viewport, width) {
+    const exact = (width * viewport.height) / viewport.width;
+    return { width, height: 2 * Math.round(exact / 2) };
+}
+/**
+ * Every field filled, so the code that starts the server never has to know a
+ * default.
+ *
+ * `reuseExistingServer` reads `CI` here, once, rather than at the moment of
+ * starting: a config is resolved per command, so this is the same moment, and
+ * a resolved config that says what it will do is easier to reason about than
+ * one that looks at the environment again later.
+ */
+function resolveWebServer(server, baseUrl, root) {
+    if (typeof server.command !== "string" || server.command.trim() === "") {
+        fail("webServer.command", "must be a non-empty string");
+    }
+    const url = server.url ?? baseUrl;
+    // `URL.canParse("localhost:5174")` is true — a scheme called `localhost` —
+    // and that is exactly the string someone types, so ask for the protocol.
+    if (!/^https?:$/.test(URL.canParse(url) ? new URL(url).protocol : "")) {
+        fail("webServer.url", `must be an http(s) URL, got ${url}`);
+    }
+    const timeoutMs = positiveInt(server.timeoutMs ?? 120_000, "webServer.timeoutMs");
+    return {
+        command: server.command,
+        url,
+        cwd: server.cwd === undefined ? root : resolve(root, server.cwd),
+        timeoutMs,
+        reuseExistingServer: server.reuseExistingServer ?? !process.env.CI,
+        env: server.env ?? {},
+    };
+}
+export function resolveConfig(config, root) {
+    if (typeof config.baseUrl !== "string" || config.baseUrl.length === 0) {
+        fail("baseUrl", "is required");
+    }
+    const viewport = config.viewport ?? { width: 1440, height: 900 };
+    positiveInt(viewport.width, "viewport.width");
+    positiveInt(viewport.height, "viewport.height");
+    const dpr = config.dpr ?? 2;
+    if (!(dpr >= 1 && dpr <= 3))
+        fail("dpr", `must be between 1 and 3, got ${dpr}`);
+    const fps = config.fps ?? 60;
+    if (!Number.isInteger(fps) || fps < 10 || fps > 120) {
+        fail("fps", `must be an integer between 10 and 120, got ${fps}`);
+    }
+    const forceCaptureEvery = config.capture?.forceCaptureEvery ?? 30;
+    if (!Number.isInteger(forceCaptureEvery) || forceCaptureEvery < 1) {
+        fail("capture.forceCaptureEvery", `must be an integer of 1 or more, got ${forceCaptureEvery}`);
+    }
+    if (config.auth) {
+        const hasState = typeof config.auth.storageState === "string";
+        const hasLogin = typeof config.auth.login === "function";
+        if (hasState === hasLogin) {
+            fail("auth", "must have exactly one of `storageState` or `login`");
+        }
+    }
+    const presentation = config.theme?.presentation;
+    if (presentation?.padding !== undefined) {
+        const p = presentation.padding;
+        if (!(p >= 0 && p <= 0.3)) {
+            fail("theme.presentation.padding", `must be between 0 and 0.3, got ${p}`);
+        }
+    }
+    const abs = (p) => (isAbsolute(p) ? p : resolve(root, p));
+    const outDir = abs(config.outDir ?? ".versioncam");
+    const outputWidth = config.output?.width ?? 1920;
+    positiveInt(outputWidth, "output.width");
+    const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    return {
+        root,
+        baseUrl,
+        webServer: config.webServer
+            ? resolveWebServer(config.webServer, baseUrl, root)
+            : null,
+        viewport,
+        dpr,
+        fps,
+        clips: config.clips === undefined
+            ? ["demos/**/*.clip.ts"]
+            : Array.isArray(config.clips)
+                ? config.clips
+                : [config.clips],
+        outDir,
+        recordingsDir: resolve(outDir, "recordings"),
+        outputDir: resolve(outDir, "out"),
+        cacheDir: resolve(outDir, ".cache"),
+        auth: config.auth ?? null,
+        settle: {
+            quietMs: config.settle?.quietMs ?? 150,
+            timeoutMs: config.settle?.timeoutMs ?? 15_000,
+            yieldMs: config.settle?.yieldMs ?? 20,
+            ready: config.settle?.ready ?? null,
+        },
+        capture: {
+            gate: config.capture?.gate ?? true,
+            forceCaptureEvery: forceCaptureEvery,
+        },
+        review: {
+            minSeconds: config.review?.minSeconds ?? 9,
+            maxSeconds: config.review?.maxSeconds ?? 11,
+        },
+        cursorStart: {
+            x: config.cursorStart?.x ?? 0.72,
+            y: config.cursorStart?.y ?? 0.28,
+        },
+        clock: {
+            time: new Date(config.clock?.time ?? "2026-09-01T09:00:00Z"),
+            timezoneId: config.clock?.timezoneId ?? "UTC",
+            locale: config.clock?.locale ?? "en-GB",
+        },
+        theme: {
+            // A neutral blue, not anyone's brand. An app says its own accent.
+            accent: config.theme?.accent ?? "#2f6fed",
+            cursorScale: config.theme?.cursorScale ?? 2.1,
+            presentation: presentation ?? null,
+        },
+        output: outputSize(viewport, outputWidth),
+        motion: { ...MOTION, ...config.motion },
+        scenes: config.scenes ? abs(config.scenes) : null,
+        sequence: config.sequence ?? null,
+    };
+}
+export function renderConfigOf(config) {
+    return {
+        output: config.output,
+        theme: config.theme,
+        motion: config.motion,
+    };
+}
+//# sourceMappingURL=config.js.map