versioncam 0.1.1

package/dist/render/sequence.js.map

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

package/dist/render/serve.d.ts

@@ -0,0 +1,35 @@
+import type { Page } from "playwright";
+import type { RenderConfig } from "../config.js";
+/**
+ * Serves the render page, the recording and the app's scenes from memory.
+ *
+ * Rendering deliberately does not need the app's dev server running. It needs
+ * a recording on disk and a browser; anything else is a dependency on the
+ * customer's environment for no benefit — and in the prototype it was worse
+ * than neutral, because a dev server pushed a reload into the page mid-render
+ * whenever a file changed.
+ *
+ * The origin is fake. Nothing resolves it; every request for it is answered
+ * here.
+ */
+export declare const RENDER_ORIGIN = "http://versioncam.local";
+export type ServeOptions = {
+    /** The built render page: `dist/render`. */
+    distDir: string;
+    renderConfig: RenderConfig;
+    /** A recording directory, when rendering one. */
+    recordingDir?: string;
+    /** A browser-format ESM bundle of the app's scenes, when it has any. */
+    scenesBundle?: string;
+};
+export declare function installRenderRoutes(page: Page, options: ServeOptions): Promise<void>;
+/**
+ * Where the built render page lives.
+ *
+ * Found by walking up to the package root rather than by counting `..`
+ * segments, because this module runs from two places: `dist/render/serve.js`
+ * when a consumer uses the CLI, and `src/render/serve.ts` when the package's
+ * own tests import it directly. A relative guess is right in one and silently
+ * 404s in the other.
+ */
+export declare function distPageDir(): string;

package/dist/render/serve.js

@@ -0,0 +1,124 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, extname, join, normalize, resolve, sep } from "node:path";
+/**
+ * Serves the render page, the recording and the app's scenes from memory.
+ *
+ * Rendering deliberately does not need the app's dev server running. It needs
+ * a recording on disk and a browser; anything else is a dependency on the
+ * customer's environment for no benefit — and in the prototype it was worse
+ * than neutral, because a dev server pushed a reload into the page mid-render
+ * whenever a file changed.
+ *
+ * The origin is fake. Nothing resolves it; every request for it is answered
+ * here.
+ */
+export const RENDER_ORIGIN = "http://versioncam.local";
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2",
+};
+function contentType(path) {
+    return (CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream");
+}
+/**
+ * Join a URL path onto a directory without letting it escape.
+ *
+ * The paths come from our own page, but a route handler that can read any file
+ * by URL is the kind of thing that later grows into a hosted service.
+ */
+function safeJoin(root, urlPath) {
+    const relative = normalize(decodeURIComponent(urlPath)).replace(/^([/\\])+/, "");
+    const full = resolve(root, relative);
+    const rootWithSep = resolve(root) + sep;
+    return full === resolve(root) || full.startsWith(rootWithSep) ? full : null;
+}
+export async function installRenderRoutes(page, options) {
+    await page.route(`${RENDER_ORIGIN}/**`, async (route) => {
+        const url = new URL(route.request().url());
+        const path = url.pathname;
+        if (path === "/render-config.json") {
+            await route.fulfill({
+                status: 200,
+                contentType: CONTENT_TYPES[".json"],
+                body: JSON.stringify(options.renderConfig),
+            });
+            return;
+        }
+        if (path === "/scenes.js") {
+            if (!options.scenesBundle) {
+                await route.fulfill({ status: 404, body: "no scenes configured" });
+                return;
+            }
+            await route.fulfill({
+                status: 200,
+                contentType: CONTENT_TYPES[".js"],
+                body: await readFile(options.scenesBundle, "utf8"),
+            });
+            return;
+        }
+        if (path.startsWith("/recording/")) {
+            if (!options.recordingDir) {
+                await route.fulfill({ status: 404, body: "no recording loaded" });
+                return;
+            }
+            const file = safeJoin(options.recordingDir, path.slice("/recording".length));
+            if (!file) {
+                await route.fulfill({
+                    status: 403,
+                    body: "path escapes the recording",
+                });
+                return;
+            }
+            await fulfillFile(route, file);
+            return;
+        }
+        // Everything else is the built page: "/" and its hashed assets.
+        const relative = path === "/" ? "index.html" : path;
+        const file = safeJoin(options.distDir, relative);
+        if (!file) {
+            await route.fulfill({ status: 403, body: "path escapes the bundle" });
+            return;
+        }
+        await fulfillFile(route, file);
+    });
+}
+async function fulfillFile(route, file) {
+    try {
+        await route.fulfill({
+            status: 200,
+            contentType: contentType(file),
+            body: await readFile(file),
+        });
+    }
+    catch {
+        await route.fulfill({ status: 404, body: `not found: ${file}` });
+    }
+}
+/**
+ * Where the built render page lives.
+ *
+ * Found by walking up to the package root rather than by counting `..`
+ * segments, because this module runs from two places: `dist/render/serve.js`
+ * when a consumer uses the CLI, and `src/render/serve.ts` when the package's
+ * own tests import it directly. A relative guess is right in one and silently
+ * 404s in the other.
+ */
+export function distPageDir() {
+    let dir = import.meta.dirname;
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, "package.json")))
+            return join(dir, "dist", "page");
+        dir = dirname(dir);
+    }
+    throw new Error("Could not locate the recorder package root from " + import.meta.dirname);
+}
+//# sourceMappingURL=serve.js.map

package/dist/render/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/render/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAI5E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,yBAAyB,CAAC;AAEvD,MAAM,aAAa,GAA2B;IAC5C,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,gCAAgC;IACxC,MAAM,EAAE,yBAAyB;IACjC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,eAAe;IACvB,QAAQ,EAAE,YAAY;CACvB,CAAC;AAEF,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,CACL,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,0BAA0B,CACzE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAe;IAC7C,MAAM,QAAQ,GAAG,SAAS,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAC7D,WAAW,EACX,EAAE,CACH,CAAC;IACF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IACxC,OAAO,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9E,CAAC;AAYD,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAU,EACV,OAAqB;IAErB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,aAAa,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QACtD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;QAE1B,IAAI,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACnC,MAAM,KAAK,CAAC,OAAO,CAAC;gBAClB,MAAM,EAAE,GAAG;gBACX,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC;gBACnC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC;aAC3C,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;gBAC1B,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,CAAC;gBACnE,OAAO;YACT,CAAC;YACD,MAAM,KAAK,CAAC,OAAO,CAAC;gBAClB,MAAM,EAAE,GAAG;gBACX,WAAW,EAAE,aAAa,CAAC,KAAK,CAAC;gBACjC,IAAI,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC;aACnD,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;gBAC1B,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC,CAAC;gBAClE,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CACnB,OAAO,CAAC,YAAY,EACpB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAChC,CAAC;YACF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,KAAK,CAAC,OAAO,CAAC;oBAClB,MAAM,EAAE,GAAG;oBACX,IAAI,EAAE,4BAA4B;iBACnC,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QAED,gEAAgE;QAChE,MAAM,QAAQ,GAAG,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;QACpD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC,CAAC;YACtE,OAAO;QACT,CAAC;QACD,MAAM,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,KAAkD,EAClD,IAAY;IAEZ,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC;YAClB,MAAM,EAAE,GAAG;YACX,WAAW,EAAE,WAAW,CAAC,IAAI,CAAC;YAC9B,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,IAAI,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;IAC9B,OAAO,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5E,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,kDAAkD,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CACzE,CAAC;AACJ,CAAC"}

package/dist/review/review.d.ts

@@ -0,0 +1,54 @@
+import type { Timeline } from "../core/timeline.js";
+import type { SettleReport } from "../driver/settle.js";
+/**
+ * The half of reviewing a clip that needs no eyes.
+ *
+ * Whether the beats happened, whether anything changed between them, whether a
+ * wait gave up, whether a track was written somewhere no frame will ever show
+ * it — all of that is in the recording, and none of it needs a picture. What
+ * does need a picture (is the thing legible, is the cursor in the way, does
+ * the frame show what the beat claimed) is left to a reviewer with eyes.
+ *
+ * A pure function over a recording, so every clause can be tested on a
+ * timeline written by hand rather than by driving a browser.
+ */
+/** Nine to eleven seconds: what the clips this was built for are written to. */
+export declare const DEFAULT_BOUNDS: {
+    minSeconds: number;
+    maxSeconds: number;
+};
+export type Beat = {
+    /** Matches a `settle({ label })` in the clip, exactly. */
+    label: string;
+    /** What should be visible by then. For the reviewer with eyes; unused here. */
+    expect?: string;
+};
+export type ReviewBounds = {
+    minSeconds?: number;
+    maxSeconds?: number;
+};
+export type ReviewItem = {
+    check: "duration" | "settles" | "beats" | "progress" | "rendered" | "onscreen";
+    pass: boolean;
+    /**
+     * A finding worth printing that is not worth failing over: `pass` is false,
+     * and the review's own `pass` is not affected.
+     */
+    warning?: boolean;
+    detail: string;
+};
+export type ReviewResult = {
+    pass: boolean;
+    items: ReviewItem[];
+};
+export type ReviewInput = {
+    timeline: Timeline;
+    /** From the recording's `settles.json`. Empty for a recording made without one. */
+    settles?: SettleReport[];
+    /** The clip's beat sheet. Empty when none was given. */
+    beats?: Beat[];
+    bounds?: ReviewBounds;
+};
+export declare function reviewRecording(input: ReviewInput): ReviewResult;
+/** The result as a person reads it, one line a clause. */
+export declare function formatReview(id: string, result: ReviewResult): string;

package/dist/review/review.js

@@ -0,0 +1,229 @@
+import { frameAt } from "../core/timeline.js";
+import { evalCamera } from "../core/camera.js";
+/**
+ * The half of reviewing a clip that needs no eyes.
+ *
+ * Whether the beats happened, whether anything changed between them, whether a
+ * wait gave up, whether a track was written somewhere no frame will ever show
+ * it — all of that is in the recording, and none of it needs a picture. What
+ * does need a picture (is the thing legible, is the cursor in the way, does
+ * the frame show what the beat claimed) is left to a reviewer with eyes.
+ *
+ * A pure function over a recording, so every clause can be tested on a
+ * timeline written by hand rather than by driving a browser.
+ */
+/** Nine to eleven seconds: what the clips this was built for are written to. */
+export const DEFAULT_BOUNDS = { minSeconds: 9, maxSeconds: 11 };
+const seconds = (value) => `${value.toFixed(1)}s`;
+function checkDuration(timeline, bounds) {
+    const min = bounds?.minSeconds ?? DEFAULT_BOUNDS.minSeconds;
+    const max = bounds?.maxSeconds ?? DEFAULT_BOUNDS.maxSeconds;
+    const length = timeline.durationFrames / timeline.fps;
+    const within = length >= min && length <= max;
+    return {
+        check: "duration",
+        pass: within,
+        detail: within
+            ? `${seconds(length)}, within ${min}–${max}s`
+            : `${seconds(length)} is outside ${min}–${max}s`,
+    };
+}
+function checkSettles(settles) {
+    if (settles.length === 0) {
+        // Not a pass to be proud of, and said plainly: a recording made before
+        // `settles.json` existed has nothing here to be right or wrong about.
+        return {
+            check: "settles",
+            pass: true,
+            detail: "no settles recorded; nothing to check",
+        };
+    }
+    const late = settles.filter((s) => s.timedOut);
+    return {
+        check: "settles",
+        pass: late.length === 0,
+        detail: late.length === 0
+            ? `${settles.length} settled, none timed out`
+            : late
+                .map((s) => `"${s.label}" timed out waiting on ${s.lastBlocker}`)
+                .join("; "),
+    };
+}
+function checkBeats(timeline, beats) {
+    const labels = new Set(timeline.marks.map((m) => m.label));
+    if (beats.length === 0) {
+        return { check: "beats", pass: true, detail: "no beat sheet given" };
+    }
+    const missing = beats.filter((beat) => !labels.has(beat.label));
+    return {
+        check: "beats",
+        pass: missing.length === 0,
+        detail: missing.length === 0
+            ? `${beats.length} beats, each with a mark`
+            : `no settle labelled ${missing.map((b) => `"${b.label}"`).join(", ")}` +
+                ` — the clip has ${[...labels].map((l) => `"${l}"`).join(", ") || "none"}`,
+    };
+}
+/**
+ * Did anything happen between one beat and the next?
+ *
+ * A beat that produced no new state is the classic authoring failure: the
+ * script clicked something, waited for it, and the page it waited for looked
+ * exactly like the page before. The clip runs, the review reads fine, and the
+ * video shows a cursor moving over a screen that never answers.
+ */
+function checkProgress(timeline) {
+    const marks = timeline.marks;
+    if (marks.length < 2) {
+        return {
+            check: "progress",
+            pass: true,
+            detail: `${marks.length} beat(s): nothing to compare`,
+        };
+    }
+    const still = [];
+    for (let i = 1; i < marks.length; i += 1) {
+        const from = marks[i - 1];
+        const to = marks[i];
+        const span = timeline.frames.slice(from.frame, to.frame + 1);
+        if (new Set(span).size <= 1) {
+            still.push(`nothing changed between "${from.label}" (frame ${from.frame}) and ` +
+                `"${to.label}" (frame ${to.frame})`);
+        }
+    }
+    return {
+        check: "progress",
+        pass: still.length === 0,
+        detail: still.length === 0
+            ? `the screen changed across all ${marks.length - 1} beat gaps`
+            : still.join("; "),
+    };
+}
+/**
+ * Anything written past the last frame, which nothing will ever show.
+ *
+ * A camera key, a highlight and a caption all cost no time — they are track
+ * writes at the current instant — so a clip that ends on one ends on an
+ * instruction with no frames left to obey it. A pilot's clip closed with a
+ * bare `camera.reset()` and the reset was never seen. A warning rather than a
+ * failure: the clip is fine, one line of it is wasted, and the author is the
+ * one who knows whether it mattered.
+ */
+function checkRendered(timeline) {
+    const lastFrame = timeline.durationFrames - 1;
+    const late = (t) => frameAt(t, timeline.fps) > lastFrame;
+    const unseen = [];
+    for (const key of timeline.camera) {
+        if (late(key.t))
+            unseen.push(`a camera key at ${seconds(key.t)}`);
+    }
+    for (const highlight of timeline.highlights) {
+        if (late(highlight.t0)) {
+            unseen.push(`a highlight at ${seconds(highlight.t0)}`);
+        }
+    }
+    for (const caption of timeline.captions) {
+        if (late(caption.t0)) {
+            unseen.push(`the caption "${caption.text}" at ${seconds(caption.t0)}`);
+        }
+    }
+    if (unseen.length === 0) {
+        return {
+            check: "rendered",
+            pass: true,
+            detail: "every camera, highlight and caption has frames after it",
+        };
+    }
+    return {
+        check: "rendered",
+        pass: false,
+        warning: true,
+        detail: `${unseen.join(", ")} — the clip ends at frame ${lastFrame} ` +
+            `(${seconds(timeline.durationFrames / timeline.fps)}), so nothing renders them. ` +
+            "A track write costs no time; give it a `hold` to be seen in.",
+    };
+}
+/**
+ * Is what the clip points at actually on screen?
+ *
+ * A highlight is drawn at the rectangle the driver measured, and a locator
+ * below the fold measures perfectly well: `versioncam measure` reported the
+ * example app's status line at y 928 in an 800-pixel viewport without comment,
+ * and the clip that rings it has been drawing that ring off the bottom of the
+ * frame since it was written. Nothing said so — not `record`, which succeeded,
+ * not `review`, which had no clause for it, and not the video, which simply
+ * lacks the ring it was supposed to end on.
+ *
+ * A warning rather than a failure: the camera can legitimately be somewhere
+ * else entirely by the time a highlight runs, and only the renderer knows for
+ * certain. But a highlight wholly outside the viewport is almost always a
+ * mistake, and it is invisible in every other way.
+ */
+function checkOnScreen(timeline) {
+    const { width, height } = timeline.viewport;
+    const full = { x: 0, y: 0, w: width, h: height };
+    // Against the camera, not the viewport.
+    //
+    // The first version of this clause compared a highlight to the whole page,
+    // which is a true statement that does not add up to the thing anyone cares
+    // about. An authoring agent hit the difference: its closing ring sat at
+    // y 16–167, comfortably inside a 900-pixel viewport and comfortably *above*
+    // a camera cropped to y 99 and down. The clause passed and the top of the
+    // card — the chip naming the filter, the whole point of the shot — was not
+    // in the frame.
+    //
+    // Sampled at both ends of the highlight because the camera can be moving
+    // through it: a ring that starts cropped and ends visible is still a ring
+    // someone can read.
+    const visible = (h) => {
+        const rects = timeline.camera.length > 0
+            ? [evalCamera(timeline.camera, h.t0), evalCamera(timeline.camera, h.t1)]
+            : [full];
+        return rects.some((r) => h.rect.x + h.rect.w > r.x &&
+            h.rect.y + h.rect.h > r.y &&
+            h.rect.x < r.x + r.w &&
+            h.rect.y < r.y + r.h);
+    };
+    const offscreen = timeline.highlights.filter((h) => !visible(h));
+    if (offscreen.length === 0) {
+        return {
+            check: "onscreen",
+            pass: true,
+            detail: `${timeline.highlights.length} highlight(s), all inside the viewport`,
+        };
+    }
+    const where = offscreen
+        .map((h) => `y ${Math.round(h.rect.y)}–${Math.round(h.rect.y + h.rect.h)}`)
+        .join(", ");
+    return {
+        check: "onscreen",
+        pass: false,
+        warning: true,
+        detail: `${offscreen.length} highlight(s) outside what the camera is showing ` +
+            `(${where}) — drawn where no frame can show them`,
+    };
+}
+export function reviewRecording(input) {
+    const items = [
+        checkDuration(input.timeline, input.bounds),
+        checkSettles(input.settles ?? []),
+        checkBeats(input.timeline, input.beats ?? []),
+        checkProgress(input.timeline),
+        checkRendered(input.timeline),
+        checkOnScreen(input.timeline),
+    ];
+    return {
+        pass: items.every((item) => item.pass || item.warning === true),
+        items,
+    };
+}
+/** The result as a person reads it, one line a clause. */
+export function formatReview(id, result) {
+    const lines = [`${id}: ${result.pass ? "PASS" : "FAIL"}`];
+    for (const item of result.items) {
+        const mark = item.pass ? "✓" : item.warning ? "!" : "✗";
+        lines.push(`  ${mark} ${item.check.padEnd(9)} ${item.detail}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=review.js.map

package/dist/review/review.js.map

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

package/dist/scene.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A designed panel: frames that are drawn rather than captured.
+ *
+ * Some things an app does have no screen to point a camera at — work that
+ * happens before the UI exists, or a claim about where data goes. Mocking up a
+ * screen for those is a worse lie than an honest diagram, so the renderer
+ * accepts a composition that draws instead.
+ *
+ * A scene is a pure function of its frame number, exactly like a recording, so
+ * both go through the same renderer, the same scrubber and the same encoder.
+ * The package ships no scenes; the artwork belongs to the app.
+ */
+export type Scene = {
+    id: string;
+    title: string;
+    durationFrames: number;
+    fps: number;
+    draw(ctx: CanvasRenderingContext2D, frame: number, canvas: Size): void;
+};
+export type Size = {
+    width: number;
+    height: number;
+};

package/dist/scene.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scene.js.map

package/dist/scene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene.js","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":""}

package/dsl.md

@@ -0,0 +1,119 @@
+# The clip DSL
+
+Everything a clip body can call on its session, `s`. `test/dsl.spec.ts`
+asserts that this list and `RecordingSession` name exactly the same members, so
+a method here exists and a method that exists is here. The README promised an
+`s.drag` for months while there was none; there is one now, because a clip that
+needed it had been silently doing nothing instead.
+
+Three rules the whole surface follows:
+
+- **Every `await` spends clip time and captures frames.** `hold`, `click`,
+  `type` and the rest advance the authored clock.
+- **A track write spends none.** `camera.*`, `highlight` and `caption` write at
+  the current instant and return immediately, so each one needs frames after it
+  — a `hold` or the next action — or it is never seen.
+- **Target by role or test id, never by coordinates.** A clip built from
+  locators survives a layout change; one built from points does not.
+
+## Locators
+
+They resolve when used, not when written, and wait up to 15 seconds for the
+element to be visible. A locator that matches several elements is an error
+naming the count — narrow it rather than reaching for the first match.
+
+- `byTestId(testId)` → `Locator` — first choice: `data-testid` is the only
+  handle an app can promise a clip.
+- `byRole(role, options?)` → `Locator` — second choice: `byRole("button", { name: "Save" })`
+  is how a person would describe it.
+- `byLabel(text)` → `Locator` — a form field, by its label.
+- `byPlaceholder(text)` → `Locator` — a field with no label but a placeholder.
+- `byText(text)` → `Locator` — content, not controls, and the one most likely
+  to match twice.
+- `css(selector)` → `Locator` — the escape hatch; a CSS selector is a claim
+  about markup, which is the thing most likely to change.
+
+## Time
+
+- `hold(ms)` — stay still and keep capturing. The pause that makes a beat
+  readable, and what a track write needs after it.
+- `settle(options?)` — wait for the page to stop working: DOM quiet, no
+  requests in flight, fonts loaded, and whatever `settle.ready` adds. Advances
+  the page's clock without capturing, so the wait never reaches the video.
+  `{ label }` is what `versioncam review` checks a beat sheet against, and what
+  `--at-marks` samples, so give every beat one. Also takes `{ quietMs,
+  timeoutMs, yieldMs, hook }`.
+- `offCamera(fn)` — run raw Playwright with nothing captured and no time spent:
+  mocking an API, seeding data, priming a conversation. `fn` is given the
+  Playwright `Page`, which is also `s.page` if you need it directly. No time
+  on the page's clock either: what the app needs time to finish after `fn`,
+  a `settle` gives it.
+
+## Navigation
+
+- `open(path, options?)` — go to `baseUrl + path`, sign in if the config says
+  how, settle, and capture frame 0. Every clip starts here. `{ settleTimeoutMs }`
+  for an app that boots slowly; the default is 90 seconds.
+
+## Pointer
+
+- `moveTo(target, options?)` — glide to a locator or a point without pressing.
+  `{ duration }` overrides the Fitts-law timing.
+- `hover(target, options?)` — move there and stay, the way a person does before
+  reading a tooltip. `{ dwell, duration }`.
+- `click(target?, options?)` — approach, dwell, press, release. Called with no
+  target it clicks where the cursor already is. `{ dwell }`.
+- `drag(target, from, to, options?)` — press, draw a straight stroke, release.
+  `from` and `to` are fractions of the target's own box, so the drag survives a
+  layout change: `{ x: 0.18, y: 0.5 }` to `{ x: 0.36, y: 0.5 }` crosses the
+  middle. For a control that answers a stroke and ignores a click — a brush, a
+  slider, a range handle. Mind 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. `{ duration, modifiers }`.
+- `lasso(target, planner, options?)` — press, follow a smoothed closed loop,
+  release. The planner comes from `loop([[0.3, 0.3], …])`, exported beside the
+  session, and is written in fractions of the target's box, so the stroke
+  survives a layout change. Measure first: `versioncam measure <path> <selector>`.
+  `{ duration, modifiers }`.
+  A frame taken partway through the stroke looks wrong, and is not: the
+  smoothing curves outside the points it passes through, so a half-drawn loop
+  swings wide of the thing it is about to enclose before coming back. Judge the
+  selection from a frame after the loop closes, not from the middle of it.
+
+## Keyboard
+
+- `typeInto(target, text)` — click the field, then type. What you want almost
+  always: without the click the keystrokes go wherever focus happens to be.
+- `type(text)` — type at a human cadence into whatever has focus.
+- `press(key)` — one key, immediately. `"Enter"`, `"Escape"`, `"Meta+a"`.
+
+## Camera, highlight, caption
+
+None of these spends clip time. Each needs frames after it.
+
+- `camera.zoom(target, scale?, options?)` — frame a locator or a rect, padded,
+  keeping the target inside the frame even at the edge of the page.
+  `scale` is a **ceiling, not a multiplier**: it caps how far in the camera may
+  go (the frame is never narrower than `viewport.width / scale`), and the
+  default cap of 1.65 exists so a captured pixel is never upscaled. A small
+  target does not fill the frame as a result — at 1440 wide, `zoom(x, 1.7)`
+  still shows about 850 pixels of page, which for a 310-pixel card reads as
+  barely zoomed at all. If you want the target to dominate the shot, pass a
+  rect from `versioncam measure` to `camera.to` instead.
+- `camera.to(rect, options?)` — frame an exact rectangle in viewport pixels.
+- `camera.reset(options?)` — back to the whole viewport. Ending a clip on this
+  and nothing else is the classic mistake: `versioncam review` warns about it.
+- `highlight(target, style, options?)` — `"ring"` around it or `"spotlight"` on
+  it, drawn in post at output resolution. `{ for }` in milliseconds.
+- `caption(text, options?)` — a line of text from now until the next caption or
+  the end of the clip. It starts where it is written, so a second caption
+  mid-clip replaces the first rather than doubling over it. `{ from, to }` in
+  seconds to place it by hand.
+
+## What the runner reads
+
+Not for clips; the CLI reports them.
+
+- `cost` — where the wall-clock time of this recording went.
+- `settles` — every settle so far, as written to `settles.json`.
+- `at` — how far the clip has got, as `{ frame, t }`.