versioncam 0.1.1

package/dist/driver/reports.js

@@ -0,0 +1,42 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 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 const SETTLES_FILE = "settles.json";
+export const FAILURE_JSON = "failure.json";
+export const FAILURE_PNG = "failure.png";
+export function writeSettles(dir, reports) {
+    writeFileSync(join(dir, SETTLES_FILE), `${JSON.stringify(reports, null, 2)}\n`);
+}
+/**
+ * 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 async function writeFailure(page, dir, failure, options = {}) {
+    try {
+        writeFileSync(join(dir, FAILURE_JSON), `${JSON.stringify(failure, null, 2)}\n`);
+        writeFileSync(join(dir, FAILURE_PNG), await page.screenshot({
+            type: "png",
+            caret: "initial",
+            // At the same scale the clip's own frames were captured at, so a
+            // draft's evidence is as cheap to look at as its states are.
+            scale: options.draft ? "css" : "device",
+        }));
+    }
+    catch {
+        // Nothing to do about it here, and the original failure is on its way up.
+    }
+}
+//# sourceMappingURL=reports.js.map

package/dist/driver/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","sourceRoot":"","sources":["../../src/driver/reports.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC;;;;;;;GAOG;AAEH,iDAAiD;AACjD,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,OAAuB;IAC/D,aAAa,CACX,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,EACvB,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC;AACJ,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAU,EACV,GAAW,EACX,OAAgB,EAChB,UAA+B,EAAE;IAEjC,IAAI,CAAC;QACH,aAAa,CACX,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,EACvB,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC;QACF,aAAa,CACX,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,EACtB,MAAM,IAAI,CAAC,UAAU,CAAC;YACpB,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,SAAS;YAChB,iEAAiE;YACjE,6DAA6D;YAC7D,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ;SACxC,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;AACH,CAAC"}

package/dist/driver/session.d.ts

@@ -0,0 +1,285 @@
+import type { Locator, Page } from "playwright";
+import { loop as planLoop } from "../core/loop.js";
+import type { LoopPlanner } from "../core/loop.js";
+import type { HighlightStyle, Rect, Timeline, Vec2 } from "../core/timeline.js";
+import type { RecordingTiming } from "../core/timing.js";
+import type { SettleOptions, SettleReport } from "./settle.js";
+import type { CaptureConfig, ResolvedConfig } from "../config.js";
+export type SessionOptions = {
+    clipId: string;
+    title: string;
+    /** Resolved for this clip: the config's values with the clip's overrides. */
+    fps: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    dpr: number;
+    seed: number;
+    outputDir: string;
+    appCommit: string;
+    capture: Required<CaptureConfig>;
+    /**
+     * Capture at CSS scale rather than device scale, for a cheap look at a clip
+     * while writing it. The page is not told: same viewport, same device pixel
+     * ratio, same layout, same code paths — only the screenshot is smaller.
+     */
+    draft: boolean;
+    config: ResolvedConfig;
+};
+/**
+ * Drives the app through an authored timeline and captures one image per
+ * output frame.
+ *
+ * The central idea: the clip's time is declared by the script, not measured
+ * from the wall clock. Each frame we apply that frame's input, advance the
+ * page's fake clock by exactly 1/fps, and capture. Real latency — a DuckDB
+ * query, a tile fetch, WebGL under software rendering — is absorbed by
+ * `settle()`, which advances the clock without capturing. Two runs of the
+ * same script therefore produce the same frames on any machine.
+ */
+export declare class RecordingSession {
+    readonly page: Page;
+    private readonly options;
+    private readonly timeline;
+    private readonly rng;
+    private readonly motion;
+    private readonly statesDir;
+    private readonly stateIndexByHash;
+    private readonly queue;
+    private readonly settleReports;
+    /** Authored time, in seconds. */
+    private t;
+    /** Index of the last captured frame; -1 before frame 0 exists. */
+    private frame;
+    private cursor;
+    private inFlight;
+    private lastSettleFrame;
+    private readonly timing;
+    /**
+     * Where the real mouse actually is. The planned cursor holds still for most
+     * of a clip, and telling Chromium to move a pointer to where it already is
+     * costs 8 ms and achieves nothing.
+     */
+    private lastMouse;
+    /** What the page looked like to the probe when it was last photographed. */
+    private lastCaptured;
+    private lastCapturedFrame;
+    /**
+     * Set whenever the driver sends the page real input, and cleared by the next
+     * frame's capture decision.
+     *
+     * Input can change what the page looks like without changing anything the
+     * probe watches: `:active` while a button is held is pure CSS, driven by a
+     * pointer event, touching neither the DOM nor the element under the cursor.
+     * The gate would skip those frames and the clip would show a button that is
+     * never pressed.
+     */
+    private inputPending;
+    constructor(page: Page, options: SessionOptions);
+    byTestId(testId: string): Locator;
+    byRole(role: Parameters<Page["getByRole"]>[0], options?: Parameters<Page["getByRole"]>[1]): Locator;
+    byLabel(text: string): Locator;
+    byPlaceholder(text: string): Locator;
+    byText(text: string | RegExp): Locator;
+    css(selector: string): Locator;
+    /** Hold still for `ms`, capturing frames. */
+    hold(ms: number): Promise<void>;
+    /**
+     * Run raw Playwright without capturing or advancing authored time. For
+     * setup that should not appear in the clip: seeding cohorts, warming tiles,
+     * priming a chat conversation.
+     *
+     * The page's clock does not move either, however long `fn` takes: time the
+     * app needs to finish what `fn` started is what the next `settle()` is for.
+     */
+    offCamera<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+    /**
+     * Wait for the page to stop working. Advances the page's clock but captures
+     * nothing, so the wait never reaches the timeline.
+     */
+    settle(options?: SettleOptions): Promise<void>;
+    private defaultHook;
+    /**
+     * Open a path, sign in if the app needs it, wait for the page to be
+     * genuinely finished, and capture frame 0.
+     *
+     * Signing in is the app's own business: how it knows it is signed out, which
+     * fields, which button, what counts as done. The config supplies either a
+     * saved browser session — in which case there is nothing to do here — or a
+     * hook, which is called unconditionally after the navigation and decides for
+     * itself whether anything is needed.
+     */
+    open(path: string, options?: {
+        settleTimeoutMs?: number;
+    }): Promise<void>;
+    /** Glide to a target without pressing anything. */
+    moveTo(target: Locator | Vec2, options?: {
+        duration?: number;
+    }): Promise<void>;
+    /** Move to a target and pause on it, the way a person does before clicking. */
+    hover(target: Locator | Vec2, options?: {
+        dwell?: number;
+        duration?: number;
+    }): Promise<void>;
+    /**
+     * A full click: approach, a short dwell on the target, press, release.
+     *
+     * Implemented on `page.mouse` rather than `locator.click()`, which would
+     * teleport the pointer to the element — the approach *is* the thing being
+     * recorded.
+     */
+    click(target?: Locator | Vec2, options?: {
+        dwell?: number;
+    }): Promise<void>;
+    /**
+     * Draw a lasso: press, follow a smoothed closed loop at constant speed,
+     * release. `planner` comes from `loop([...])` and is expressed in fractions
+     * of the target's box, so the stroke survives a layout change.
+     */
+    /**
+     * Drag across a target, in fractions of its own box.
+     *
+     * A brush, a slider, a range handle: controls that respond to a stroke and
+     * ignore a click. The README promised this method for months before it
+     * existed, and the gap was not academic — a date-histogram clip on the
+     * first app this recorded clicked a bar to filter by month, which sets a
+     * zero-width d3 brush, which *clears* the filter rather than applying one.
+     * That clip never showed the thing its caption claimed, and nothing said
+     * so: the click lands, the page changes enough for a pixel diff, and the
+     * recording looks fine.
+     *
+     * Fractions rather than pixels for the same reason `lasso` uses them: a
+     * stroke authored against a real box survives the next padding change.
+     * `{ x1: 0.18, y1: 0.5, x2: 0.36, y2: 0.5 }` drags left-to-right across the
+     * middle. Beware the edges — a chart's axis labels live inside its own box,
+     * and a drag starting at x 0.08 selects that text instead of the control.
+     */
+    drag(target: Locator | Rect, from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }, options?: {
+        duration?: number;
+        modifiers?: ("Shift" | "Alt")[];
+    }): Promise<void>;
+    lasso(target: Locator, planner: LoopPlanner, options?: {
+        duration?: number;
+        modifiers?: ("Shift" | "Alt")[];
+    }): Promise<void>;
+    /**
+     * Type at a human cadence into `target`, clicking it first so the keystrokes
+     * have somewhere to land. Without the click the text goes to whatever had
+     * focus — usually nothing — and the clip shows an empty field being
+     * "typed" into.
+     */
+    typeInto(target: Locator, text: string): Promise<void>;
+    /** Type at a human cadence. The cursor stays where it is. */
+    type(text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    readonly camera: {
+        zoom: (target: Locator | Rect, scale?: number, options?: {
+            duration?: number;
+        }) => Promise<void>;
+        to: (rect: Rect, options?: {
+            duration?: number;
+        }) => void;
+        reset: (options?: {
+            duration?: number;
+        }) => void;
+    };
+    private pushCameraKey;
+    highlight(target: Locator | Rect, style: HighlightStyle, options?: {
+        for?: number;
+    }): Promise<void>;
+    /**
+     * Put a line of text on the clip, from now until the next caption or the end.
+     *
+     * `from` defaults to the moment it is written, not to zero. Defaulting to
+     * zero meant a second caption covered the whole clip on top of the first, so
+     * every frame carried both lines drawn over each other — which reads on a
+     * contact sheet as ghosted text rather than as a caption bug, and cost a
+     * pilot most of a round to diagnose.
+     */
+    caption(text: string, options?: {
+        from?: number;
+        to?: number;
+    }): void;
+    private pushHold;
+    /**
+     * Bounded on purpose. `boundingBox()` waits indefinitely by default, so a
+     * clip that reaches for a control the app did not render — a button that
+     * only appears once something is selected, say — hangs forever with no clue
+     * as to which step it was on. Fifteen seconds and a named failure instead.
+     */
+    private boxOf;
+    /**
+     * Wait for a target to be on screen, advancing the page's clock a tick at a
+     * time while it is not.
+     *
+     * The clock is paused, so a target the app shows from its own timer — a menu
+     * that opens after a delay, results behind a debounce — would never arrive
+     * if this only waited. Ticking as `settle()` does brings it in the same
+     * number of ticks every run, and costs nothing in the usual case: a target
+     * already on screen is one round trip and no page time at all.
+     */
+    private untilVisible;
+    /**
+     * Run `fn` with the page's clock ticking alongside real time, the way it
+     * runs in a browser nobody is driving.
+     *
+     * Only for code the recorder hands the page to and cannot see into, and
+     * never while a frame is being made: the ticks land wherever the machine's
+     * speed puts them, which is exactly what the frames must not depend on.
+     */
+    private whileTicking;
+    /**
+     * Which kind of locator failure this was.
+     *
+     * Playwright reports both of them as a rejected wait, and they call for
+     * opposite repairs. Nothing matched means the clip reached for something the
+     * app never rendered — look at the page again. Several matched is a
+     * strict-mode violation: the locator found the text, on more than one
+     * element, and the beat is fine as long as the locator names one of them.
+     * Saying "nothing matched" for the second sent a pilot hunting a control
+     * that was on screen the whole time.
+     */
+    private whyLocatorFailed;
+    private resolvePoint;
+    private resolveSize;
+    /**
+     * The frame loop. Everything that advances authored time comes through here.
+     */
+    private advanceTo;
+    /**
+     * Does this frame need its own screenshot?
+     *
+     * Every clause errs towards capturing, because the two mistakes are not
+     * equal: capturing a frame that did not change wastes 25 ms, and skipping
+     * one that did puts a wrong picture in the video.
+     */
+    private shouldCapture;
+    /** Press or release, recording it and flagging the frame as changed. */
+    private pressMouse;
+    /** Move the real pointer, unless it is already there. */
+    private moveMouse;
+    private captureFrame;
+    /** What this recording cost in real time. Diagnostics, never content. */
+    get cost(): RecordingTiming;
+    /** Every settle that happened, in order: what each waited for, and for how long. */
+    get settles(): SettleReport[];
+    /**
+     * How far the clip had got. Meaningless as content — it is where a failure
+     * happened, which is the first thing a repair needs and the one thing the
+     * script cannot be read to find out.
+     */
+    get at(): {
+        frame: number;
+        t: number;
+    };
+    /** Write the timeline out. Called by `clip()` once the script has run. */
+    finish(): Timeline;
+}
+export { planLoop as loop };