versioncam 0.1.1

package/dist/driver/clip.js

@@ -0,0 +1,120 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { FREEZE_CSS_SCRIPT, MUTATION_COUNTER_SCRIPT } from "./page-hooks.js";
+import { writeFailure, writeSettles } from "./reports.js";
+import { RecordingSession } from "./session.js";
+/**
+ * Declare a clip.
+ *
+ * This only describes one — running it is `runClip`, which the CLI does. The
+ * prototype registered a Playwright test here instead, which worked but meant
+ * every way of recording had to go through a test runner.
+ */
+export function clip(id, options, body) {
+    return { id, options, body };
+}
+/** The app's commit, for the recording's provenance. Best effort. */
+function appCommit(cwd) {
+    try {
+        return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+export async function runClip(browser, config, definition, runOptions = {}) {
+    const { id, options, body } = definition;
+    const draft = runOptions.draft ?? false;
+    const viewport = options.viewport ?? config.viewport;
+    const dpr = options.dpr ?? config.dpr;
+    // A draft ignores a clip's own frame rate: the point is to be cheap, and a
+    // clip asking for 60 would quietly cost four times what the flag promises.
+    const fps = draft ? 15 : (options.fps ?? config.fps);
+    const capture = { ...config.capture, ...options.capture };
+    const context = await browser.newContext({
+        viewport,
+        deviceScaleFactor: dpr,
+        // The app should render its normal motion design; the freeze script is
+        // narrower than reduced-motion and does not change layout.
+        reducedMotion: "no-preference",
+        // A fixed timezone and locale keep any rendered date identical run to run.
+        timezoneId: config.clock.timezoneId,
+        locale: config.clock.locale,
+        storageState: config.auth?.storageState,
+    });
+    const page = await context.newPage();
+    await page.addInitScript(MUTATION_COUNTER_SCRIPT);
+    await page.addInitScript(FREEZE_CSS_SCRIPT);
+    // Paused, not just installed. `clock.install()` leaves Playwright's fake
+    // clock running on real time between the driver's own `runFor` calls, so
+    // every screenshot, every probe and every stall of the machine reached the
+    // page as time: on the Linux runner one slow frame moved the page's clock
+    // 840 ms instead of 67, and the example app's 800 ms timer fired seven
+    // frames early. Paused, it moves only when the driver moves it — 1/fps a
+    // frame, a tick at a time while it waits — and it starts at exactly
+    // `clock.time` instead of that plus however long the navigation took.
+    await page.clock.pauseAt(config.clock.time);
+    // A dev server broadcasts a full page reload to every connected client when
+    // it cannot hot-update a changed module, including a page being recorded.
+    // Editing any file mid-run therefore replaces the document, which otherwise
+    // surfaces as an inscrutable "Execution context was destroyed" from
+    // whichever evaluate lost the race.
+    //
+    // Counted from "load" rather than "framenavigated": the latter also fires
+    // for History API pushes, and an app that routes client-side would report
+    // navigations that never replaced anything.
+    let documentLoads = 0;
+    page.on("load", () => {
+        documentLoads += 1;
+    });
+    const dir = join(config.recordingsDir, id);
+    const session = new RecordingSession(page, {
+        clipId: id,
+        title: options.title,
+        fps,
+        viewport,
+        dpr,
+        seed: options.seed ?? 1,
+        outputDir: dir,
+        appCommit: appCommit(config.root),
+        capture,
+        draft,
+        config,
+    });
+    try {
+        await body(session);
+        if (documentLoads > 1) {
+            throw new Error(`The document reloaded ${documentLoads - 1} time(s) during "${id}". ` +
+                "The usual cause is editing a file while recording: a dev server " +
+                "pushes a full reload to every open client. Re-record without " +
+                "touching the working tree.");
+        }
+        const timeline = session.finish();
+        writeSettles(dir, session.settles);
+        return { timeline, dir, cost: session.cost, settles: session.settles };
+    }
+    catch (error) {
+        // Here rather than in the caller, because the context closes below and the
+        // page is the one piece of evidence that cannot be recovered afterwards:
+        // by the time an error reaches `record`, the app it failed on is gone.
+        //
+        // Nothing in this block may throw, or it would replace the failure it
+        // exists to report — a disk error standing in for the locator that broke.
+        try {
+            writeSettles(dir, session.settles);
+        }
+        catch {
+            // Said by the error on its way up, which is the more useful of the two.
+        }
+        await writeFailure(page, dir, { message: error.message, ...session.at }, { draft });
+        throw error;
+    }
+    finally {
+        await context.close();
+    }
+}
+//# sourceMappingURL=clip.js.map

package/dist/driver/clip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clip.js","sourceRoot":"","sources":["../../src/driver/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA0BhD;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAClB,EAAU,EACV,OAAoB,EACpB,IAAc;IAEd,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED,qEAAqE;AACrE,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;YAC3D,GAAG;YACH,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAoCD,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAgB,EAChB,MAAsB,EACtB,UAA0B,EAC1B,aAA6B,EAAE;IAE/B,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,KAAK,CAAC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC;IACtC,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAE1D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QACvC,QAAQ;QACR,iBAAiB,EAAE,GAAG;QACtB,uEAAuE;QACvE,2DAA2D;QAC3D,aAAa,EAAE,eAAe;QAC9B,2EAA2E;QAC3E,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU;QACnC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;QAC3B,YAAY,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY;KACxC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAErC,MAAM,IAAI,CAAC,aAAa,CAAC,uBAAuB,CAAC,CAAC;IAClD,MAAM,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAC5C,yEAAyE;IACzE,yEAAyE;IACzE,2EAA2E;IAC3E,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,oEAAoE;IACpE,sEAAsE;IACtE,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,0EAA0E;IAC1E,4EAA4E;IAC5E,oEAAoE;IACpE,oCAAoC;IACpC,EAAE;IACF,0EAA0E;IAC1E,0EAA0E;IAC1E,4CAA4C;IAC5C,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACnB,aAAa,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,IAAI,EAAE;QACzC,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG;QACH,QAAQ;QACR,GAAG;QACH,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC;QACvB,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;QACjC,OAAO;QACP,KAAK;QACL,MAAM;KACP,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,yBAAyB,aAAa,GAAG,CAAC,oBAAoB,EAAE,KAAK;gBACnE,kEAAkE;gBAClE,+DAA+D;gBAC/D,4BAA4B,CAC/B,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAClC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACnC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,2EAA2E;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,EAAE;QACF,sEAAsE;QACtE,0EAA0E;QAC1E,IAAI,CAAC;YACH,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;QACD,MAAM,YAAY,CAChB,IAAI,EACJ,GAAG,EACH,EAAE,OAAO,EAAG,KAAe,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,EAAE,EAAE,EACpD,EAAE,KAAK,EAAE,CACV,CAAC;QACF,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/driver/compare.d.ts

@@ -0,0 +1,34 @@
+import type { Timeline } from "../core/timeline.js";
+/**
+ * Are two recordings of the same clip the same video?
+ *
+ * The README's rule — when a clip will not reproduce, record it twice the
+ * same way first — as a function, because two places need the answer: the
+ * `stability` command, which asks it of an app before anything is authored
+ * for it, and the example app's gate test, which asks it of the recorder.
+ *
+ * Frame by frame, by what each frame shows: the state image behind it,
+ * hashed. Not by state index or state count, which differ between a gated and
+ * an ungated recording of an identical video; and not by the timeline, whose
+ * cursor, camera and captions are the driver's own decisions and identical by
+ * construction. The pixels are what the app drew, so they are what can vary.
+ */
+/** A recording on disk: the directory and the timeline it holds. */
+export type RecordingRef = {
+    dir: string;
+    timeline: Timeline;
+};
+export type Comparison = {
+    /** The longer of the two, so a recording that stops early differs. */
+    frames: number;
+    identical: number;
+    firstDifference: number | null;
+    differing: number[];
+};
+/** Read the recording `runClip` wrote into `dir`. */
+export declare function readRecording(dir: string): RecordingRef;
+/** What each frame shows, as a hash of the state image behind it. */
+export declare function frameHashes(recording: RecordingRef): string[];
+/** The state image a frame shows, or null past the recording's end. */
+export declare function stateFileAt(recording: RecordingRef, frame: number): string | null;
+export declare function compareRecordings(a: RecordingRef, b: RecordingRef): Comparison;

package/dist/driver/compare.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Read the recording `runClip` wrote into `dir`. */
+export function readRecording(dir) {
+    const timeline = JSON.parse(readFileSync(join(dir, "timeline.json"), "utf8"));
+    return { dir, timeline };
+}
+/** What each frame shows, as a hash of the state image behind it. */
+export function frameHashes(recording) {
+    const states = recording.timeline.states.map((name) => createHash("sha1")
+        .update(readFileSync(join(recording.dir, "states", name)))
+        .digest("hex"));
+    return recording.timeline.frames.map((index) => states[index]);
+}
+/** The state image a frame shows, or null past the recording's end. */
+export function stateFileAt(recording, frame) {
+    const index = recording.timeline.frames[frame];
+    if (index === undefined)
+        return null;
+    return join(recording.dir, "states", recording.timeline.states[index]);
+}
+export function compareRecordings(a, b) {
+    const left = frameHashes(a);
+    const right = frameHashes(b);
+    const frames = Math.max(left.length, right.length);
+    const differing = [];
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (left[frame] === undefined || left[frame] !== right[frame]) {
+            differing.push(frame);
+        }
+    }
+    return {
+        frames,
+        identical: frames - differing.length,
+        firstDifference: differing[0] ?? null,
+        differing,
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/driver/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/driver/compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA6BjC,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CACrC,CAAC;IACd,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,WAAW,CAAC,SAAuB;IACjD,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACpD,UAAU,CAAC,MAAM,CAAC;SACf,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;SACzD,MAAM,CAAC,KAAK,CAAC,CACjB,CAAC;IACF,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CACzB,SAAuB,EACvB,KAAa;IAEb,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,CAAe,EACf,CAAe;IAEf,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9D,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,MAAM;QACN,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM;QACpC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI;QACrC,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/driver/gate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A latch the clip opens when it is ready for something to arrive.
+ *
+ * Apps that stream a response — an assistant answering, a job reporting
+ * progress — look wrong in a clip if the reply lands in the frame after the
+ * request: it reads as a lookup rather than as work. The clip wants to hold on
+ * the app's own pending state for a beat first.
+ *
+ * That beat has to be measured in *clip* time, not real time. A sleep inside
+ * the route handler would resolve after however many frames the machine
+ * happened to capture in that interval, which differs per machine and defeats
+ * the whole design. So a mocked route waits on the gate, and the clip holds
+ * for an authored duration — capturing the pending state while it does — and
+ * then opens it.
+ *
+ *   const gate = createGate();
+ *   await page.route(url, async (route) => {
+ *     await gate.wait();
+ *     await route.fulfill({ ... });
+ *   });
+ *   // in the clip:
+ *   await s.press("Enter");
+ *   await s.hold(1500);   // the app's spinner, on screen, for 1.5s of clip
+ *   gate.open();
+ */
+export type Gate = {
+    /** Resolves once the gate is open. Resolves immediately if it already is. */
+    wait(): Promise<void>;
+    /** Let whatever is waiting through. */
+    open(): void;
+    /** Close it again, for a clip with more than one turn. */
+    close(): void;
+    /** Whether something is currently waiting. */
+    isHolding(): boolean;
+};
+export declare function createGate(startOpen?: boolean): Gate;

package/dist/driver/gate.js

@@ -0,0 +1,27 @@
+export function createGate(startOpen = false) {
+    let open = startOpen;
+    let waiting = [];
+    return {
+        wait() {
+            if (open)
+                return Promise.resolve();
+            return new Promise((resolve) => {
+                waiting.push(resolve);
+            });
+        },
+        open() {
+            open = true;
+            const pending = waiting;
+            waiting = [];
+            for (const resolve of pending)
+                resolve();
+        },
+        close() {
+            open = false;
+        },
+        isHolding() {
+            return waiting.length > 0;
+        },
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/driver/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/driver/gate.ts"],"names":[],"mappings":"AAoCA,MAAM,UAAU,UAAU,CAAC,SAAS,GAAG,KAAK;IAC1C,IAAI,IAAI,GAAG,SAAS,CAAC;IACrB,IAAI,OAAO,GAAmB,EAAE,CAAC;IAEjC,OAAO;QACL,IAAI;YACF,IAAI,IAAI;gBAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;YACnC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACnC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI;YACF,IAAI,GAAG,IAAI,CAAC;YACZ,MAAM,OAAO,GAAG,OAAO,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC;YACb,KAAK,MAAM,OAAO,IAAI,OAAO;gBAAE,OAAO,EAAE,CAAC;QAC3C,CAAC;QACD,KAAK;YACH,IAAI,GAAG,KAAK,CAAC;QACf,CAAC;QACD,SAAS;YACP,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/driver/launch.d.ts

@@ -0,0 +1,43 @@
+import type { Browser } from "playwright";
+/**
+ * How the recorder launches Chromium, everywhere.
+ *
+ * One flag, and it is here because of a measurement.
+ *
+ * `--disable-partial-raster` makes Chromium repaint the whole tile when part
+ * of it changes, instead of only the rectangle the page reported as changed.
+ * A full recording does not need it: every frame of the example app's clips
+ * is byte-identical with and without it, on macOS and on Linux. A draft does.
+ * Its CSS-scale screenshot of a page at device pixel ratio 2 has Chromium
+ * paint the page a second time, at half the scale, for every shot, and when it
+ * can, repaint only what changed since the last one — from rectangles measured
+ * at the page's own scale. At half the scale a glyph's antialiased edge can
+ * land a pixel outside its rectangle, and whether that pixel was repainted
+ * then depends on which tiles Chromium happened to keep, which depends on
+ * timing. On the Linux runner, where text has LCD antialiasing, the example
+ * app's draft differed at frame 23 in 19 of 32 pairs of runs, by one pixel:
+ * the red fringe at the right edge of the "r" just typed into "Mir", drawn or
+ * still white. With this flag, 28 pairs of 28 matched on the same runner.
+ *
+ * The list was empty before that, and the emptiness was a finding too. Chasing
+ * a six-pixel difference between two runs of one clip, the obvious suspect was
+ * font rasterisation, so these three went in:
+ *
+ *     --disable-lcd-text  --disable-font-subpixel-positioning
+ *     --force-color-profile=srgb
+ *
+ * They made no difference, because the cause was elsewhere: the screenshot was
+ * being taken with Playwright's `animations: "disabled"`, which cancelled the
+ * spinner to rotation zero and raced the recorder's own scrub. Once that was
+ * fixed, six consecutive runs came out byte-identical with no flags at all.
+ *
+ * A flag that changes how a correct page looks would change every captured
+ * pixel, so the bar for adding one is a measurement showing it fixes
+ * something. Keeping this function as the single launch site is the point:
+ * there is one place to put such a flag, and one place to explain it.
+ */
+export declare const DETERMINISTIC_ARGS: string[];
+/** Launch Chromium the way every recorder command should. */
+export declare function launchBrowser(options?: {
+    headless?: boolean;
+}): Promise<Browser>;

package/dist/driver/launch.js

@@ -0,0 +1,47 @@
+import { chromium } from "playwright";
+/**
+ * How the recorder launches Chromium, everywhere.
+ *
+ * One flag, and it is here because of a measurement.
+ *
+ * `--disable-partial-raster` makes Chromium repaint the whole tile when part
+ * of it changes, instead of only the rectangle the page reported as changed.
+ * A full recording does not need it: every frame of the example app's clips
+ * is byte-identical with and without it, on macOS and on Linux. A draft does.
+ * Its CSS-scale screenshot of a page at device pixel ratio 2 has Chromium
+ * paint the page a second time, at half the scale, for every shot, and when it
+ * can, repaint only what changed since the last one — from rectangles measured
+ * at the page's own scale. At half the scale a glyph's antialiased edge can
+ * land a pixel outside its rectangle, and whether that pixel was repainted
+ * then depends on which tiles Chromium happened to keep, which depends on
+ * timing. On the Linux runner, where text has LCD antialiasing, the example
+ * app's draft differed at frame 23 in 19 of 32 pairs of runs, by one pixel:
+ * the red fringe at the right edge of the "r" just typed into "Mir", drawn or
+ * still white. With this flag, 28 pairs of 28 matched on the same runner.
+ *
+ * The list was empty before that, and the emptiness was a finding too. Chasing
+ * a six-pixel difference between two runs of one clip, the obvious suspect was
+ * font rasterisation, so these three went in:
+ *
+ *     --disable-lcd-text  --disable-font-subpixel-positioning
+ *     --force-color-profile=srgb
+ *
+ * They made no difference, because the cause was elsewhere: the screenshot was
+ * being taken with Playwright's `animations: "disabled"`, which cancelled the
+ * spinner to rotation zero and raced the recorder's own scrub. Once that was
+ * fixed, six consecutive runs came out byte-identical with no flags at all.
+ *
+ * A flag that changes how a correct page looks would change every captured
+ * pixel, so the bar for adding one is a measurement showing it fixes
+ * something. Keeping this function as the single launch site is the point:
+ * there is one place to put such a flag, and one place to explain it.
+ */
+export const DETERMINISTIC_ARGS = ["--disable-partial-raster"];
+/** Launch Chromium the way every recorder command should. */
+export function launchBrowser(options = {}) {
+    return chromium.launch({
+        headless: options.headless ?? true,
+        args: DETERMINISTIC_ARGS,
+    });
+}
+//# sourceMappingURL=launch.js.map

package/dist/driver/launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../src/driver/launch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAa,CAAC,0BAA0B,CAAC,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,UAAU,aAAa,CAC3B,UAAkC,EAAE;IAEpC,OAAO,QAAQ,CAAC,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,IAAI,EAAE,kBAAkB;KACzB,CAAC,CAAC;AACL,CAAC"}

package/dist/driver/page-hooks.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Scripts injected into every document the recorder drives.
+ *
+ * These run at document start, before any app code, and must be
+ * self-contained strings — they are evaluated in the page, not here.
+ */
+/**
+ * Counts DOM mutations so `settle()` can tell "the page is still working"
+ * from "the page has finished". Counting is far cheaper than diffing and
+ * needs no cooperation from the app.
+ */
+export declare const MUTATION_COUNTER_SCRIPT = "(() => {\n  const state = {\n    mutations: 0,\n    ids: new WeakMap(),\n    nextId: 1,\n    idOf(el) {\n      if (!el) return 0;\n      let id = state.ids.get(el);\n      if (!id) { id = state.nextId++; state.ids.set(el, id); }\n      return id;\n    },\n    probe(t, x, y) {\n      document.documentElement.style.setProperty(\"--recorder-t\", t);\n      return {\n        mutations: state.mutations,\n        hovered: state.idOf(document.elementFromPoint(x, y)),\n        animations: document.getAnimations().length,\n      };\n    },\n  };\n  window.__recorder = state;\n\n  // The driver writes --recorder-t to <html style> on every single frame. Left\n  // alone that write is a mutation like any other, so the counter would move\n  // every frame and anything built on it \u2014 a settle that waits for quiet, a\n  // gate that skips an unchanged frame \u2014 would be reading its own footprint.\n  // Anything else that touches <html style>, a scroll lock or a theme switch,\n  // still counts.\n  const withoutScrub = (value) =>\n    (value || \"\").replace(/--recorder-t\\s*:[^;]*;?/g, \"\").trim();\n\n  const start = () => {\n    const root = document.documentElement;\n    const isOurScrub = (record) =>\n      record.type === \"attributes\" &&\n      record.target === root &&\n      record.attributeName === \"style\" &&\n      withoutScrub(record.oldValue) === withoutScrub(root.getAttribute(\"style\"));\n\n    new MutationObserver((records) => {\n      for (const record of records) {\n        if (!isOurScrub(record)) state.mutations += 1;\n      }\n    }).observe(root || document, {\n      childList: true,\n      attributes: true,\n      attributeOldValue: true,\n      characterData: true,\n      subtree: true,\n    });\n  };\n  if (document.documentElement) start();\n  else document.addEventListener(\"DOMContentLoaded\", start, { once: true });\n})();";
+/**
+ * Puts the page's CSS motion under the recorder's control.
+ *
+ * `page.clock` drives timers and requestAnimationFrame, but CSS transitions
+ * and animations run on the compositor's own clock, which the fake clock does
+ * not touch. Left alone they produce half-finished frames whose content
+ * depends on how busy the machine was — the exact non-determinism this
+ * recorder exists to remove.
+ *
+ * Transitions are simply zeroed: a state change should land in the frame that
+ * caused it, and the renderer puts a uniform crossfade back in post.
+ *
+ * Animations are handled differently, because zeroing them is wrong. A
+ * loading spinner with `animation-duration: 0s` is a dead spinner, and a clip
+ * that pauses on a dead spinner looks broken rather than thoughtful. So every
+ * animation is *paused* and then scrubbed to a chosen offset by a negative
+ * delay: a paused animation renders the state it would have been in at
+ * `-animation-delay`. The driver sets that offset from authored time, once per
+ * frame, which makes the page's own animations advance with the clip —
+ * deterministically, at exactly the rate the timeline says.
+ *
+ * `scroll-behavior: auto` is here for the same reason: a smooth-scrolling
+ * container animates outside our control.
+ */
+export declare const FREEZE_CSS = "*, *::before, *::after {\n  transition-duration: 0s !important;\n  transition-delay: 0s !important;\n  animation-play-state: paused !important;\n  animation-delay: calc(-1s * var(--recorder-t, 0)) !important;\n  scroll-behavior: auto !important;\n  caret-color: transparent !important;\n}";
+export declare const FREEZE_CSS_SCRIPT: string;
+/**
+ * What the driver learns from the page once per frame.
+ *
+ * One round trip does three jobs: it advances the page's CSS animations to
+ * this frame's authored time, and reports the two things that decide whether
+ * this frame needs a screenshot.
+ *
+ * `hovered` is the identity of the element under the cursor, as a number. The
+ * cursor glyph is drawn in post, so the pointer moving changes no pixel by
+ * itself — what changes pixels is the pointer moving *onto something else*.
+ * `elementFromPoint` runs the same hit test a real pointer event does, so when
+ * it returns the same element as last frame, the `:hover` chain is the same
+ * chain and no hover styling can have changed.
+ *
+ * `animations` is how many animations are running. A scrubbed animation
+ * repaints on every frame without touching the DOM, so while any is on screen
+ * — a spinner, a progress bar — every frame is genuinely different and none
+ * may be skipped.
+ */
+export declare const FRAME_PROBE: (seconds: number, x: number, y: number) => string;
+export type FrameProbe = {
+    mutations: number;
+    /** Identity of the element under the cursor; 0 when there is none. */
+    hovered: number;
+    animations: number;
+};
+declare global {
+    interface Window {
+        __recorder?: {
+            mutations: number;
+            probe(t: string, x: number, y: number): FrameProbe;
+        };
+    }
+}

package/dist/driver/page-hooks.js

@@ -0,0 +1,129 @@
+/**
+ * Scripts injected into every document the recorder drives.
+ *
+ * These run at document start, before any app code, and must be
+ * self-contained strings — they are evaluated in the page, not here.
+ */
+/**
+ * Counts DOM mutations so `settle()` can tell "the page is still working"
+ * from "the page has finished". Counting is far cheaper than diffing and
+ * needs no cooperation from the app.
+ */
+export const MUTATION_COUNTER_SCRIPT = `(() => {
+  const state = {
+    mutations: 0,
+    ids: new WeakMap(),
+    nextId: 1,
+    idOf(el) {
+      if (!el) return 0;
+      let id = state.ids.get(el);
+      if (!id) { id = state.nextId++; state.ids.set(el, id); }
+      return id;
+    },
+    probe(t, x, y) {
+      document.documentElement.style.setProperty("--recorder-t", t);
+      return {
+        mutations: state.mutations,
+        hovered: state.idOf(document.elementFromPoint(x, y)),
+        animations: document.getAnimations().length,
+      };
+    },
+  };
+  window.__recorder = state;
+
+  // The driver writes --recorder-t to <html style> on every single frame. Left
+  // alone that write is a mutation like any other, so the counter would move
+  // every frame and anything built on it — a settle that waits for quiet, a
+  // gate that skips an unchanged frame — would be reading its own footprint.
+  // Anything else that touches <html style>, a scroll lock or a theme switch,
+  // still counts.
+  const withoutScrub = (value) =>
+    (value || "").replace(/--recorder-t\\s*:[^;]*;?/g, "").trim();
+
+  const start = () => {
+    const root = document.documentElement;
+    const isOurScrub = (record) =>
+      record.type === "attributes" &&
+      record.target === root &&
+      record.attributeName === "style" &&
+      withoutScrub(record.oldValue) === withoutScrub(root.getAttribute("style"));
+
+    new MutationObserver((records) => {
+      for (const record of records) {
+        if (!isOurScrub(record)) state.mutations += 1;
+      }
+    }).observe(root || document, {
+      childList: true,
+      attributes: true,
+      attributeOldValue: true,
+      characterData: true,
+      subtree: true,
+    });
+  };
+  if (document.documentElement) start();
+  else document.addEventListener("DOMContentLoaded", start, { once: true });
+})();`;
+/**
+ * Puts the page's CSS motion under the recorder's control.
+ *
+ * `page.clock` drives timers and requestAnimationFrame, but CSS transitions
+ * and animations run on the compositor's own clock, which the fake clock does
+ * not touch. Left alone they produce half-finished frames whose content
+ * depends on how busy the machine was — the exact non-determinism this
+ * recorder exists to remove.
+ *
+ * Transitions are simply zeroed: a state change should land in the frame that
+ * caused it, and the renderer puts a uniform crossfade back in post.
+ *
+ * Animations are handled differently, because zeroing them is wrong. A
+ * loading spinner with `animation-duration: 0s` is a dead spinner, and a clip
+ * that pauses on a dead spinner looks broken rather than thoughtful. So every
+ * animation is *paused* and then scrubbed to a chosen offset by a negative
+ * delay: a paused animation renders the state it would have been in at
+ * `-animation-delay`. The driver sets that offset from authored time, once per
+ * frame, which makes the page's own animations advance with the clip —
+ * deterministically, at exactly the rate the timeline says.
+ *
+ * `scroll-behavior: auto` is here for the same reason: a smooth-scrolling
+ * container animates outside our control.
+ */
+export const FREEZE_CSS = `*, *::before, *::after {
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  animation-play-state: paused !important;
+  animation-delay: calc(-1s * var(--recorder-t, 0)) !important;
+  scroll-behavior: auto !important;
+  caret-color: transparent !important;
+}`;
+export const FREEZE_CSS_SCRIPT = `(() => {
+  const css = ${JSON.stringify(FREEZE_CSS)};
+  const inject = () => {
+    const style = document.createElement("style");
+    style.id = "__recorder_freeze";
+    style.textContent = css;
+    (document.head || document.documentElement).appendChild(style);
+  };
+  if (document.head || document.documentElement) inject();
+  else document.addEventListener("DOMContentLoaded", inject, { once: true });
+})();`;
+/**
+ * What the driver learns from the page once per frame.
+ *
+ * One round trip does three jobs: it advances the page's CSS animations to
+ * this frame's authored time, and reports the two things that decide whether
+ * this frame needs a screenshot.
+ *
+ * `hovered` is the identity of the element under the cursor, as a number. The
+ * cursor glyph is drawn in post, so the pointer moving changes no pixel by
+ * itself — what changes pixels is the pointer moving *onto something else*.
+ * `elementFromPoint` runs the same hit test a real pointer event does, so when
+ * it returns the same element as last frame, the `:hover` chain is the same
+ * chain and no hover styling can have changed.
+ *
+ * `animations` is how many animations are running. A scrubbed animation
+ * repaints on every frame without touching the DOM, so while any is on screen
+ * — a spinner, a progress bar — every frame is genuinely different and none
+ * may be skipped.
+ */
+export const FRAME_PROBE = (seconds, x, y) => `window.__recorder.probe("${seconds.toFixed(4)}", ${x.toFixed(2)}, ${y.toFixed(2)})`;
+//# sourceMappingURL=page-hooks.js.map

package/dist/driver/page-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-hooks.js","sourceRoot":"","sources":["../../src/driver/page-hooks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAqDjC,CAAC;AAEP;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;EAOxB,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG;gBACjB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;;;;;;;;;MASpC,CAAC;AAEP;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,CAAS,EAAE,CAAS,EAAU,EAAE,CAC3E,4BAA4B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC"}

package/dist/driver/reports.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from "playwright";
+import type { SettleReport } from "./settle.js";
+/**
+ * What a recording leaves behind besides its frames.
+ *
+ * A clip is written by someone who was not watching it run — increasingly,
+ * by something that cannot watch at all — so everything that would have been
+ * on screen has to be on disk. Two files: what the waits waited for, and, if
+ * it ended badly, the page at the moment it gave up.
+ */
+/** The name a reader looks for, in one place. */
+export declare const SETTLES_FILE = "settles.json";
+export declare const FAILURE_JSON = "failure.json";
+export declare const FAILURE_PNG = "failure.png";
+export declare function writeSettles(dir: string, reports: SettleReport[]): void;
+export type Failure = {
+    message: string;
+    /** The last frame captured before it gave up; -1 if none was. */
+    frame: number;
+    /** Authored seconds, which is where in the script to look. */
+    t: number;
+};
+/**
+ * The failure, then the picture of it.
+ *
+ * In that order deliberately: the message, the frame and the time can be
+ * reconstructed from nothing else, while a screenshot needs a live page and
+ * may not be available — a crashed browser, a context already gone. Losing the
+ * picture must not lose the rest, and neither may mask the error that caused
+ * this to be called in the first place.
+ */
+export declare function writeFailure(page: Page, dir: string, failure: Failure, options?: {
+    draft?: boolean;
+}): Promise<void>;