versioncam 0.1.2 → 0.2.0

package/dist/cli/cwd.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * `--cwd <dir>`: run a command as if from `<dir>`.
+ *
+ * Every command works in the directory that holds `versioncam.config.ts`:
+ * the config, `.env.recording` and `.env`, `.versioncam/`, and any relative
+ * path a command is given or prints are that directory's. In a monorepo the
+ * app is one directory among many, and whatever runs versioncam may be
+ * somewhere else: a script at the repository root, or an agent whose session
+ * started inside the app, below its config, and which may not `cd` out of
+ * the directory it started in.
+ *
+ * Its own module so a test can reach it without running the CLI.
+ */
+/**
+ * `--cwd <dir>` or `--cwd=<dir>`, taken out of the arguments, from anywhere
+ * among them. If it is given twice, the last one counts.
+ *
+ * Anywhere, not only before the command's name, because what an agent may
+ * run is a prefix: the reviewer is allowed `npx versioncam frame *` and
+ * nothing else, so its flag has to be able to come after `frame`.
+ */
+export function takeCwd(argv) {
+    let cwd;
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg !== "--cwd" && !arg.startsWith("--cwd=")) {
+            rest.push(arg);
+            continue;
+        }
+        const value = arg === "--cwd" ? argv[++i] : arg.slice("--cwd=".length);
+        // A flag where the directory should be is a directory left out, not a
+        // directory called `--draft`.
+        if (!value || value.startsWith("-")) {
+            throw new Error("`--cwd` needs a directory: versioncam <command> --cwd <dir>");
+        }
+        cwd = value;
+    }
+    return { cwd, rest };
+}
+/**
+ * The versioncam a config in `dir` imports: the first `node_modules/versioncam`
+ * from `dir` up, which is where Node looks for a bare `import "versioncam"`.
+ * Null where there is none.
+ *
+ * Resolved through symlinks, so an `npm link` or a pnpm store compares as
+ * the directory it really is.
+ */
+export function versioncamFrom(dir) {
+    for (let at = resolve(dir);; at = dirname(at)) {
+        const candidate = join(at, "node_modules", "versioncam");
+        if (existsSync(join(candidate, "package.json"))) {
+            return realpathSync(candidate);
+        }
+        if (dirname(at) === at)
+            return null;
+    }
+}
+/** This package, where it really is: two levels above this file. */
+const RUNNING = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), "..", ".."));
+/** "versioncam 0.1.3 in <dir>", without the version if it cannot be read. */
+function nameOf(pkg) {
+    try {
+        const { version } = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
+        if (version)
+            return `versioncam ${version} in ${pkg}`;
+    }
+    catch {
+        // Named by its directory alone, which is the part that matters.
+    }
+    return `versioncam in ${pkg}`;
+}
+/**
+ * Move into `dir` for the rest of the command, or say why not.
+ *
+ * Only the directory moves, though, and not the versioncam running: `npx`
+ * finds the binary in the directory it runs in and in those above it, never
+ * below. Run from above an app that has versioncam in its own
+ * `node_modules`, it runs another copy, or downloads the latest one, and that
+ * copy would record with a Chromium the app never pinned, beside a config
+ * that imports the app's own. So a directory whose own versioncam is not the
+ * one running is refused, with how to run its own.
+ */
+export function enterCwd(dir) {
+    const target = resolve(dir);
+    if (!existsSync(target) || !statSync(target).isDirectory()) {
+        throw new Error(`\`--cwd ${dir}\`: there is no directory ${target}.`);
+    }
+    const theirs = versioncamFrom(target);
+    if (theirs !== null && theirs !== RUNNING) {
+        const shown = relative(process.cwd(), target) || ".";
+        throw new Error(`\`--cwd ${dir}\`: that directory has its own ${nameOf(theirs)}, ` +
+            `and this is ${nameOf(RUNNING)}.\n` +
+            "npx looks for versioncam in the directory it runs in and in those above it, never below.\n" +
+            `Run the directory's own instead: cd ${shown}, then the same command without --cwd.`);
+    }
+    process.chdir(target);
+}
+//# sourceMappingURL=cwd.js.map

package/dist/cli/cwd.js.map

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

package/dist/cli/main.js

@@ -16,6 +16,7 @@ import { review } from "./commands/review.js";
 import { sheet } from "./commands/sheet.js";
 import { stability } from "./commands/stability.js";
 import { loadEnvFiles } from "../env.js";
+import { enterCwd, takeCwd } from "./cwd.js";
 import { USAGE } from "./usage.js";
 const COMMANDS = {
     record,
@@ -35,7 +36,9 @@ const COMMANDS = {
     init,
 };
 async function main() {
-    const argv = process.argv.slice(2);
+    // `--cwd` comes out first: it takes a value, which the parsing below would
+    // otherwise read as the command's name.
+    const { cwd, rest: argv } = takeCwd(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")) {
@@ -57,8 +60,14 @@ async function main() {
         process.stderr.write(`Unknown command "${name}".\n\n${USAGE}`);
         return 1;
     }
+    // Before the environment files, which are that directory's too.
+    if (cwd !== undefined)
+        enterCwd(cwd);
     loadEnvFiles(process.cwd());
-    return command(process.argv.slice(3));
+    // The command's own arguments: everything but its name, wherever the name
+    // was, which is first unless a flag came before it.
+    const at = argv.indexOf(name);
+    return command([...argv.slice(0, at), ...argv.slice(at + 1)]);
 }
 main().then((code) => {
     process.exitCode = code;

package/dist/cli/main.js.map

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

package/dist/cli/usage.d.ts

@@ -1,10 +1,15 @@
 /**
- * What `versioncam --help` prints, and the README's *Commands* block,
- * line for line.
+ * What `versioncam --help` prints, and the README's *Commands* section,
+ * group for group and 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.
+ * list. The DSL reference learned why, by promising an `s.drag` for months
+ * that did not exist.
+ *
+ * Grouped by the stage of the work each command belongs to, in the order a
+ * repository meets them. A flat list of seventeen commands left a newcomer to
+ * work out that `inspect` comes before `record` and `sheet` after it. The
+ * last group is not a stage but a way to run any of them.
  */
-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";
+export declare const USAGE = "versioncam: record and render demo clips of a real app\n\nSet up\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  versioncam doctor                  check this machine can record, and that the app starts\n  versioncam login                   sign in once and save the browser session\n\nWrite\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 a selector's matches are, and what they say\n  versioncam dsl                     the clip DSL: every method, its options and defaults\n\nRecord\n  versioncam record [id\u2026]            drive the app and capture frames\n      --draft                        15fps at CSS scale: cheap, for writing clips\n  versioncam check [id\u2026]             record every clip; exit 1 if any 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\nReview\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 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 and 11)\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\nOutput\n  versioncam render [id\u2026]            composite and encode recordings and scenes\n                                     no ids: every one, stale recordings included\n      --scene <id>                   and this scene, whatever the ids say (repeatable)\n      --sequence                     stitch the results into one piece\n\nFrom another directory\n  versioncam <command> --cwd <dir>   as if run in <dir>, which holds versioncam.config.ts\n\nRun from a directory containing versioncam.config.ts, or name it with --cwd.\n";

package/dist/cli/usage.js

@@ -1,46 +1,64 @@
 /**
- * What `versioncam --help` prints, and the README's *Commands* block,
- * line for line.
+ * What `versioncam --help` prints, and the README's *Commands* section,
+ * group for group and 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.
+ * list. The DSL reference learned why, by promising an `s.drag` for months
+ * that did not exist.
+ *
+ * Grouped by the stage of the work each command belongs to, in the order a
+ * repository meets them. A flat list of seventeen commands left a newcomer to
+ * work out that `inspect` comes before `record` and `sheet` after it. The
+ * last group is not a stage but a way to run any of them.
  */
-export const USAGE = `versioncam — record and render demo clips of a real app
+export const USAGE = `versioncam: record and render demo clips of a real app
 
+Set up
+  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
+  versioncam doctor                  check this machine can record, and that the app starts
+  versioncam login                   sign in once and save the browser session
+
+Write
+  versioncam inspect <path>          what a clip can click, and where each name came from
+      --json                         machine-readable
+  versioncam measure <path> <sel>    where a selector's matches are, and what they say
+  versioncam dsl                     the clip DSL: every method, its options and defaults
+
+Record
   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 check [id…]             record every clip; exit 1 if any 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
+
+Review
   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 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 and 11)
   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.
+Output
+  versioncam render [id…]            composite and encode recordings and scenes
+                                     no ids: every one, stale recordings included
+      --scene <id>                   and this scene, whatever the ids say (repeatable)
+      --sequence                     stitch the results into one piece
+
+From another directory
+  versioncam <command> --cwd <dir>   as if run in <dir>, which holds versioncam.config.ts
+
+Run from a directory containing versioncam.config.ts, or name it with --cwd.
 `;
 //# sourceMappingURL=usage.js.map

package/dist/cli/usage.js.map

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

package/dist/config.d.ts

@@ -31,6 +31,25 @@ export type Presentation = {
     padding?: number;
     /** "auto" puts it below the app when padded, and over it when not. */
     caption?: "auto" | "below" | "overlay" | "none";
+    /**
+     * Where a caption over the app sits: `{ left: n }` or `{ right: n }`,
+     * pixels of the video in from that side, which also picks the bottom
+     * corner. Default `{ left: 40 }`.
+     *
+     * An app keeps its own controls in a corner as often as not (an account
+     * menu at the foot of a sidebar, a map's legend), and a caption fixed over
+     * one hides what a clip may be pointing at. Ignored when the caption sits
+     * below the app, where there is nothing of the app to cover.
+     */
+    captionInset?: CaptionInset;
+};
+/** One side and a distance from it, as CSS's `left` and `right` say it. */
+export type CaptionInset = {
+    left: number;
+    right?: never;
+} | {
+    right: number;
+    left?: never;
 };
 export type AuthConfig = {
     storageState: string;
@@ -246,5 +265,10 @@ export type RenderConfig = {
         presentation: Presentation | null;
     };
     motion: Motion;
+    /**
+     * The scenes module's path. The page is served a bundle of it, and names
+     * the file it came from when it cannot read the scenes out of it.
+     */
+    scenes: string | null;
 };
 export declare function renderConfigOf(config: ResolvedConfig): RenderConfig;

package/dist/config.js

@@ -13,6 +13,27 @@ function positiveInt(value, field) {
     }
     return value;
 }
+/**
+ * A caption inset names one side, and a distance that keeps the caption on
+ * the video.
+ *
+ * Checked because a caption placed off the video fails the way nothing in
+ * the presentation layer should: without an error, and without a caption.
+ */
+function checkCaptionInset(inset, outputWidth) {
+    const field = "theme.presentation.captionInset";
+    const given = inset;
+    const sides = ["left", "right"].filter((side) => given?.[side] !== undefined);
+    if (given === null || sides.length !== 1) {
+        fail(field, "must be `{ left: n }` or `{ right: n }`, one side only");
+    }
+    const px = given[sides[0]];
+    if (typeof px !== "number" || !(px >= 0 && px < outputWidth)) {
+        // Quoted when it is a string, or `"40"` would read as the 40 it is not.
+        const got = typeof px === "string" ? JSON.stringify(px) : String(px);
+        fail(`${field}.${sides[0]}`, `must be pixels of the video, from 0 to under its width of ${outputWidth}, got ${got}`);
+    }
+}
 /**
  * Output dimensions follow the viewport's aspect.
  *
@@ -90,6 +111,9 @@ export function resolveConfig(config, root) {
     const outputWidth = config.output?.width ?? 1920;
     positiveInt(outputWidth, "output.width");
     const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    if (presentation?.captionInset !== undefined) {
+        checkCaptionInset(presentation.captionInset, outputWidth);
+    }
     return {
         root,
         baseUrl,
@@ -149,6 +173,7 @@ export function renderConfigOf(config) {
         output: config.output,
         theme: config.theme,
         motion: config.motion,
+        scenes: config.scenes,
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/core/camera-track.d.ts

@@ -0,0 +1,63 @@
+import type { Viewport } from "./camera.js";
+import type { FollowSpec } from "./follow.js";
+import type { CameraKey, CursorTrack, Rect, Vec2 } from "./timeline.js";
+/**
+ * What a clip asked the camera to do, and when: one per `s.camera.*` call.
+ *
+ * The session keeps these rather than writing camera keys as it goes,
+ * because a camera that follows the cursor depends on where the cursor goes
+ * *after* the write, and that is only known once the clip has run. The
+ * driver never needs the camera while it records: it captures the whole
+ * viewport, and the camera is a crop drawn afterwards.
+ */
+export type CameraWrite = 
+/** `zoom`, `to` and `reset`: glide to a framing and stay there. */
+{
+    t: number;
+    kind: "frame";
+    rect: Rect;
+    durationMs: number;
+}
+/** Follow the cursor, until the next write. */
+ | {
+    t: number;
+    kind: "follow";
+    spec: FollowSpec;
+    durationMs: number;
+}
+/** Stop following, and come to rest on the framing the follow was heading for. */
+ | {
+    t: number;
+    kind: "release";
+};
+export type TrackContext = {
+    viewport: Viewport;
+    fps: number;
+    durationFrames: number;
+    cursor: CursorTrack;
+    /** Where the cursor rests before the track's first step. */
+    cursorStart: Vec2;
+};
+/**
+ * Turn a clip's camera writes into the keys the renderer interpolates.
+ *
+ * Every write starts from where the camera is, moving or not, and blends
+ * from there to where it is going:
+ *
+ *     camera(t) = interpolateRect(before(t), destination(t), minjerk(u))
+ *
+ * where `before` is the camera as it would have gone on without this write,
+ * and `u` runs from 0 to 1 over the write's duration. Min-jerk has no slope
+ * at either end, so the camera's velocity is continuous where a blend starts
+ * and where it ends: entering a follow from a keyed zoom, leaving it for a
+ * reset, or a zoom written while another is still under way. That last one
+ * used to wait for the move before it to finish and then run short, because
+ * each glide set off from the previous glide's target.
+ *
+ * A clip that never follows and never writes a move while another is under
+ * way gets exactly the keys it always got: a hold where each write starts and
+ * a min-jerk key where it ends. Every other clip gets the camera sampled at
+ * each frame (the `"linear"` keys), since a blend between two moving framings
+ * is no longer a glide between two keys.
+ */
+export declare function cameraTrack(writes: readonly CameraWrite[], context: TrackContext): CameraKey[];