versioncam 0.1.1

package/dist/core/motion-defaults.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The numbers that decide whether a clip looks human or looks generated.
+ *
+ * Each one is a judgement, not a constant of nature, so each carries the
+ * reason it is what it is. Tune them with the render page's scrubber, then
+ * write down what was wrong before.
+ */
+export declare const MOTION: {
+    /**
+     * Pause after arriving somewhere before doing anything. Without it the
+     * click lands on the same frame the cursor stops, which reads as a machine
+     * hitting a coordinate rather than a person deciding.
+     */
+    readonly hoverDwellMs: 220;
+    /** Dwell before a click, drawn from this range so it is never metronomic. */
+    readonly clickDwellMinMs: 80;
+    readonly clickDwellMaxMs: 150;
+    /** How long the button stays down. Below ~60 ms the press is invisible. */
+    readonly pressMinMs: 70;
+    readonly pressMaxMs: 100;
+    /**
+     * A lasso stroke. Much faster and the shape reads as a scribble; much
+     * slower and the clip has no room for anything else.
+     */
+    readonly lassoDurationMs: 1400;
+    /**
+     * Camera moves. Longer than a cursor move on purpose: the camera carries the
+     * whole frame, so at 700ms it reads as a snap even with min-jerk easing and
+     * geometric interpolation. Around a second is where it stops calling
+     * attention to itself.
+     */
+    readonly zoomDurationMs: 1100;
+    /**
+     * Default magnification, and the point past which a zoom stops being free.
+     *
+     * A 1440-wide viewport captured at DPR 2 is 2880 real pixels. The app frame
+     * inside a 1920-wide output is about 1750. Reading 2880/Z source pixels into
+     * 1750 output pixels stays 1:1 only while Z <= 2880/1750, so 1.65 is where
+     * upscaling begins — not 1.85, which was arithmetic done backwards.
+     *
+     * Deep zooms are therefore not the way to make small UI readable. Use the
+     * app's own affordances instead: the chat panel has a "Full view".
+     */
+    readonly defaultZoom: 1.5;
+    readonly maxZoom: 1.65;
+    /** Padding around a zoom target, as a fraction of its size. */
+    readonly zoomPad: 0.12;
+    /** How long a highlight stays up if the script does not say. */
+    readonly highlightMs: 1800;
+    /** Click ripple, in the renderer. */
+    readonly rippleMs: 400;
+    /** How far the ripple grows, in output pixels. */
+    readonly rippleRadius: 34;
+    /** Cursor glyph scale while pressed, and how long it takes to get there. */
+    readonly pressScale: 0.9;
+    readonly pressScaleMs: 120;
+    /** Frames a post-settle crossfade lasts. Six at 60 fps is 100 ms. */
+    readonly crossfadeFrames: 6;
+    /** Caption fade, in seconds. */
+    readonly captionFadeS: 0.3;
+};

package/dist/core/motion-defaults.js

@@ -0,0 +1,62 @@
+/**
+ * The numbers that decide whether a clip looks human or looks generated.
+ *
+ * Each one is a judgement, not a constant of nature, so each carries the
+ * reason it is what it is. Tune them with the render page's scrubber, then
+ * write down what was wrong before.
+ */
+export const MOTION = {
+    /**
+     * Pause after arriving somewhere before doing anything. Without it the
+     * click lands on the same frame the cursor stops, which reads as a machine
+     * hitting a coordinate rather than a person deciding.
+     */
+    hoverDwellMs: 220,
+    /** Dwell before a click, drawn from this range so it is never metronomic. */
+    clickDwellMinMs: 80,
+    clickDwellMaxMs: 150,
+    /** How long the button stays down. Below ~60 ms the press is invisible. */
+    pressMinMs: 70,
+    pressMaxMs: 100,
+    /**
+     * A lasso stroke. Much faster and the shape reads as a scribble; much
+     * slower and the clip has no room for anything else.
+     */
+    lassoDurationMs: 1400,
+    /**
+     * Camera moves. Longer than a cursor move on purpose: the camera carries the
+     * whole frame, so at 700ms it reads as a snap even with min-jerk easing and
+     * geometric interpolation. Around a second is where it stops calling
+     * attention to itself.
+     */
+    zoomDurationMs: 1100,
+    /**
+     * Default magnification, and the point past which a zoom stops being free.
+     *
+     * A 1440-wide viewport captured at DPR 2 is 2880 real pixels. The app frame
+     * inside a 1920-wide output is about 1750. Reading 2880/Z source pixels into
+     * 1750 output pixels stays 1:1 only while Z <= 2880/1750, so 1.65 is where
+     * upscaling begins — not 1.85, which was arithmetic done backwards.
+     *
+     * Deep zooms are therefore not the way to make small UI readable. Use the
+     * app's own affordances instead: the chat panel has a "Full view".
+     */
+    defaultZoom: 1.5,
+    maxZoom: 1.65,
+    /** Padding around a zoom target, as a fraction of its size. */
+    zoomPad: 0.12,
+    /** How long a highlight stays up if the script does not say. */
+    highlightMs: 1800,
+    /** Click ripple, in the renderer. */
+    rippleMs: 400,
+    /** How far the ripple grows, in output pixels. */
+    rippleRadius: 34,
+    /** Cursor glyph scale while pressed, and how long it takes to get there. */
+    pressScale: 0.9,
+    pressScaleMs: 120,
+    /** Frames a post-settle crossfade lasts. Six at 60 fps is 100 ms. */
+    crossfadeFrames: 6,
+    /** Caption fade, in seconds. */
+    captionFadeS: 0.3,
+};
+//# sourceMappingURL=motion-defaults.js.map

package/dist/core/motion-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-defaults.js","sourceRoot":"","sources":["../../src/core/motion-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;;;OAIG;IACH,YAAY,EAAE,GAAG;IAEjB,6EAA6E;IAC7E,eAAe,EAAE,EAAE;IACnB,eAAe,EAAE,GAAG;IAEpB,2EAA2E;IAC3E,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,GAAG;IAEf;;;OAGG;IACH,eAAe,EAAE,IAAI;IAErB;;;;;OAKG;IACH,cAAc,EAAE,IAAI;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,GAAG;IAChB,OAAO,EAAE,IAAI;IAEb,+DAA+D;IAC/D,OAAO,EAAE,IAAI;IAEb,gEAAgE;IAChE,WAAW,EAAE,IAAI;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,GAAG;IACb,kDAAkD;IAClD,YAAY,EAAE,EAAE;IAEhB,4EAA4E;IAC5E,UAAU,EAAE,GAAG;IACf,YAAY,EAAE,GAAG;IAEjB,qEAAqE;IACrE,eAAe,EAAE,CAAC;IAElB,gCAAgC;IAChC,YAAY,EAAE,GAAG;CACT,CAAC"}

package/dist/core/rng.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A seeded PRNG, because "looks human" and "identical every run" have to hold
+ * at the same time. Every jittered decision in the recorder — arc direction,
+ * dwell length, where inside a button the cursor lands, typing cadence —
+ * draws from one of these, seeded per clip.
+ *
+ * mulberry32: small, fast, and good enough for motion jitter.
+ */
+export declare function seeded(seed: number): () => number;
+/** A value in [min, max) from `rng`. */
+export declare function between(rng: () => number, min: number, max: number): number;
+/** A symmetric jitter in [-magnitude, +magnitude). */
+export declare function jitter(rng: () => number, magnitude: number): number;

package/dist/core/rng.js

@@ -0,0 +1,27 @@
+/**
+ * A seeded PRNG, because "looks human" and "identical every run" have to hold
+ * at the same time. Every jittered decision in the recorder — arc direction,
+ * dwell length, where inside a button the cursor lands, typing cadence —
+ * draws from one of these, seeded per clip.
+ *
+ * mulberry32: small, fast, and good enough for motion jitter.
+ */
+export function seeded(seed) {
+    let state = seed >>> 0;
+    return function next() {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** A value in [min, max) from `rng`. */
+export function between(rng, min, max) {
+    return min + rng() * (max - min);
+}
+/** A symmetric jitter in [-magnitude, +magnitude). */
+export function jitter(rng, magnitude) {
+    return (rng() * 2 - 1) * magnitude;
+}
+//# sourceMappingURL=rng.js.map

package/dist/core/rng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.js","sourceRoot":"","sources":["../../src/core/rng.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC;IACvB,OAAO,SAAS,IAAI;QAClB,KAAK,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,KAAK,CAAC;QACd,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAC1C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,OAAO,CAAC,GAAiB,EAAE,GAAW,EAAE,GAAW;IACjE,OAAO,GAAG,GAAG,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,MAAM,CAAC,GAAiB,EAAE,SAAiB;IACzD,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC;AACrC,CAAC"}

package/dist/core/sse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Server-sent-event bodies, for replaying a streamed response.
+ *
+ * An app that streams — an assistant answering, a job reporting progress —
+ * cannot be part of a regenerable recording while it is live: the response
+ * would differ every run. The driver intercepts the route and replays a
+ * fixture instead. This builds the body; the shape of each event's payload
+ * belongs to the app, so it stays in the app's own clip support code, along
+ * with a contract test feeding this output back through the app's parser.
+ */
+export type SseFixtureEvent = {
+    event: string;
+    data: unknown;
+};
+export declare function sseBody(events: readonly SseFixtureEvent[]): string;

package/dist/core/sse.js

@@ -0,0 +1,16 @@
+/**
+ * Server-sent-event bodies, for replaying a streamed response.
+ *
+ * An app that streams — an assistant answering, a job reporting progress —
+ * cannot be part of a regenerable recording while it is live: the response
+ * would differ every run. The driver intercepts the route and replays a
+ * fixture instead. This builds the body; the shape of each event's payload
+ * belongs to the app, so it stays in the app's own clip support code, along
+ * with a contract test feeding this output back through the app's parser.
+ */
+export function sseBody(events) {
+    return events
+        .map((e) => `event: ${e.event}\ndata: ${JSON.stringify(e.data)}\n\n`)
+        .join("");
+}
+//# sourceMappingURL=sse.js.map

package/dist/core/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/core/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,OAAO,CAAC,MAAkC;IACxD,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,KAAK,WAAW,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;SACpE,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/core/timeline.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The contract between the driver (which captures) and the renderer (which
+ * composites). A recording is a directory of state PNGs plus one of these.
+ *
+ * Coordinates are CSS pixels in viewport space — the same space
+ * `locator.boundingBox()` reports — so a timeline is independent of the
+ * device pixel ratio it was captured at. The renderer multiplies by
+ * `viewport.dpr` when it needs to address pixels inside a state image.
+ *
+ * Times are seconds from the start of the clip. Durations elsewhere in the
+ * recorder are milliseconds, because that is the unit a person authoring a
+ * clip thinks in; conversions happen at the boundary.
+ */
+export type Vec2 = readonly [number, number];
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type CursorSegment = {
+    kind: "move";
+    t0: number;
+    t1: number;
+    from: Vec2;
+    to: Vec2;
+    /** Quadratic Bézier control point: the slight arc that reads as human. */
+    ctrl: Vec2;
+    ease: "minjerk";
+};
+export type CursorHold = {
+    kind: "hold";
+    t0: number;
+    t1: number;
+    at: Vec2;
+};
+export type CursorStep = CursorSegment | CursorHold;
+export type CursorTrack = CursorStep[];
+export type PointerAction = {
+    t: number;
+    kind: "down" | "up";
+    at: Vec2;
+    button: "left";
+};
+export type CameraKey = {
+    t: number;
+    rect: Rect;
+    /** How to reach this key from the previous one. */
+    ease: "minjerk" | "hold";
+};
+export type HighlightStyle = "ring" | "spotlight";
+export type Highlight = {
+    t0: number;
+    t1: number;
+    rect: Rect;
+    style: HighlightStyle;
+};
+export type Caption = {
+    t0: number;
+    t1: number;
+    text: string;
+};
+/**
+ * A beat, as a frame number: where a labelled `settle()` left the page.
+ *
+ * The frame recorded is the first one *after* the settle, because a settle
+ * captures nothing — so the earliest picture of what a beat produced is the
+ * next frame, and that is the frame a reviewer should be shown.
+ * `versioncam review` checks a clip's beats against these and
+ * `versioncam sheet --at-marks` samples them, which is how the moments a clip
+ * was written around reach a reader instead of eight frames spread evenly
+ * through it.
+ */
+export type Mark = {
+    frame: number;
+    label: string;
+};
+export type Timeline = {
+    version: 1;
+    clipId: string;
+    fps: number;
+    durationFrames: number;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    /** State file names, relative to the recording's `states/` directory. */
+    states: string[];
+    /** Length `durationFrames`; `frames[f]` indexes into `states`. */
+    frames: number[];
+    /**
+     * Frames where a settle happened, i.e. where the page may have changed a
+     * lot at once. The renderer crossfades only here — everywhere else a state
+     * change is a real one-frame change and should stay crisp.
+     */
+    cuts: number[];
+    /** Labelled settles, in the order they happened. */
+    marks: Mark[];
+    cursor: CursorTrack;
+    pointer: PointerAction[];
+    camera: CameraKey[];
+    highlights: Highlight[];
+    captions: Caption[];
+    meta: {
+        title: string;
+        recordedAt: string;
+        appCommit: string;
+        baseUrl: string;
+        /**
+         * How many frames were screenshotted, as opposed to reusing the previous
+         * frame's state. A property of the recording, not of the machine — the
+         * same script against the same app skips the same frames — so it belongs
+         * here, where wall-clock timings deliberately do not.
+         */
+        captured?: number;
+        /**
+         * Recorded in draft: fewer frames, captured at CSS scale. A draft is for
+         * looking at while writing a clip, never for publishing.
+         */
+        draft?: boolean;
+    };
+};
+export type TimelineInit = {
+    clipId: string;
+    fps: number;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    title: string;
+    appCommit: string;
+    baseUrl: string;
+    recordedAt: string;
+};
+export declare function emptyTimeline(init: TimelineInit): Timeline;
+/** The frame a given time falls in. Frame f covers [f/fps, (f+1)/fps). */
+export declare function frameAt(t: number, fps: number): number;
+/** The time a frame starts at. */
+export declare function timeAt(frame: number, fps: number): number;
+/**
+ * Structural checks that must hold for any timeline the renderer accepts.
+ * Returns the problems found so a caller can report all of them at once.
+ */
+export declare function validateTimeline(timeline: Timeline): string[];

package/dist/core/timeline.js

@@ -0,0 +1,81 @@
+/**
+ * The contract between the driver (which captures) and the renderer (which
+ * composites). A recording is a directory of state PNGs plus one of these.
+ *
+ * Coordinates are CSS pixels in viewport space — the same space
+ * `locator.boundingBox()` reports — so a timeline is independent of the
+ * device pixel ratio it was captured at. The renderer multiplies by
+ * `viewport.dpr` when it needs to address pixels inside a state image.
+ *
+ * Times are seconds from the start of the clip. Durations elsewhere in the
+ * recorder are milliseconds, because that is the unit a person authoring a
+ * clip thinks in; conversions happen at the boundary.
+ */
+export function emptyTimeline(init) {
+    return {
+        version: 1,
+        clipId: init.clipId,
+        fps: init.fps,
+        durationFrames: 0,
+        viewport: init.viewport,
+        states: [],
+        frames: [],
+        cuts: [],
+        marks: [],
+        cursor: [],
+        pointer: [],
+        camera: [
+            {
+                t: 0,
+                rect: { x: 0, y: 0, w: init.viewport.width, h: init.viewport.height },
+                ease: "hold",
+            },
+        ],
+        highlights: [],
+        captions: [],
+        meta: {
+            title: init.title,
+            recordedAt: init.recordedAt,
+            appCommit: init.appCommit,
+            baseUrl: init.baseUrl,
+        },
+    };
+}
+/** The frame a given time falls in. Frame f covers [f/fps, (f+1)/fps). */
+export function frameAt(t, fps) {
+    return Math.round(t * fps);
+}
+/** The time a frame starts at. */
+export function timeAt(frame, fps) {
+    return frame / fps;
+}
+/**
+ * Structural checks that must hold for any timeline the renderer accepts.
+ * Returns the problems found so a caller can report all of them at once.
+ */
+export function validateTimeline(timeline) {
+    const problems = [];
+    if (timeline.frames.length !== timeline.durationFrames) {
+        problems.push(`frames has ${timeline.frames.length} entries but durationFrames is ${timeline.durationFrames}`);
+    }
+    for (const [index, state] of timeline.frames.entries()) {
+        if (state < 0 || state >= timeline.states.length) {
+            problems.push(`frames[${index}] = ${state} is not a valid state index`);
+            break;
+        }
+    }
+    if (timeline.camera.length === 0) {
+        problems.push("camera has no keys");
+    }
+    else if (timeline.camera[0].t !== 0) {
+        problems.push("camera must open with a key at t=0");
+    }
+    const cameraOutOfOrder = timeline.camera.some((key, index) => index > 0 && key.t < timeline.camera[index - 1].t);
+    if (cameraOutOfOrder)
+        problems.push("camera keys are not sorted by time");
+    const cursorOutOfOrder = timeline.cursor.some((step, index) => index > 0 && step.t0 < timeline.cursor[index - 1].t0);
+    if (cursorOutOfOrder)
+        problems.push("cursor steps are not sorted by time");
+    return problems;
+}
+//# sourceMappingURL=timeline.js.map

package/dist/core/timeline.js.map

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

package/dist/core/timing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a recording's real time went.
+ *
+ * Deliberately not written into the timeline: two recordings of one script
+ * must differ in no byte, which is why `recordedAt` is fixed to the epoch. A
+ * measurement of how busy this machine was is the opposite of that, so it is
+ * reported to whoever asked for the recording and not stored beside it.
+ *
+ * The buckets do not overlap. `settle()` is called by the clip script between
+ * advances, never inside one, so no millisecond is counted twice.
+ */
+export type RecordingTiming = {
+    /** Navigation and sign-in. */
+    openMs: number;
+    /** Every `settle()`, including the one inside `open()`. */
+    settleMs: number;
+    /** The frame loop, captures included. */
+    framesMs: number;
+    /** Validating and writing the timeline. */
+    writeMs: number;
+    captured: number;
+    skipped: number;
+};
+export declare function emptyTiming(): RecordingTiming;
+/**
+ * One line saying where the next second would have to come from.
+ *
+ * The capture counts ride along with the frame bucket because they explain it:
+ * a frame loop is expensive in proportion to how many screenshots it took.
+ */
+export declare function formatTiming(timing: RecordingTiming): string;

package/dist/core/timing.js

@@ -0,0 +1,29 @@
+export function emptyTiming() {
+    return {
+        openMs: 0,
+        settleMs: 0,
+        framesMs: 0,
+        writeMs: 0,
+        captured: 0,
+        skipped: 0,
+    };
+}
+const secs = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/**
+ * One line saying where the next second would have to come from.
+ *
+ * The capture counts ride along with the frame bucket because they explain it:
+ * a frame loop is expensive in proportion to how many screenshots it took.
+ */
+export function formatTiming(timing) {
+    const frames = timing.skipped > 0
+        ? `frames ${secs(timing.framesMs)} (${timing.captured} captured, ${timing.skipped} skipped)`
+        : `frames ${secs(timing.framesMs)} (${timing.captured} captured)`;
+    return [
+        `open ${secs(timing.openMs)}`,
+        `settles ${secs(timing.settleMs)}`,
+        frames,
+        `write ${secs(timing.writeMs)}`,
+    ].join(" · ");
+}
+//# sourceMappingURL=timing.js.map

package/dist/core/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/core/timing.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,MAAM,EAAE,CAAC;QACT,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AAElE;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,MAAM,MAAM,GACV,MAAM,CAAC,OAAO,GAAG,CAAC;QAChB,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,QAAQ,cAAc,MAAM,CAAC,OAAO,WAAW;QAC5F,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,QAAQ,YAAY,CAAC;IACtE,OAAO;QACL,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE;QAC7B,WAAW,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;QAClC,MAAM;QACN,SAAS,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE;KAChC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChB,CAAC"}

package/dist/core/typing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * When each character of `text` gets typed, in milliseconds from the start.
+ *
+ * Constant-rate typing is one of the strongest tells that a demo is scripted.
+ * Real typing varies per keystroke and pauses at word and clause boundaries,
+ * so the pause goes *after* a space or a comma, where a person's hands
+ * actually hesitate. No fake typos: they read as a gimmick on second viewing
+ * and make the clip impossible to re-cut.
+ */
+export declare function typingSchedule(text: string, rng: () => number): number[];
+/** Total time `typingSchedule` spans, in milliseconds. */
+export declare function typingDuration(times: number[]): number;

package/dist/core/typing.js

@@ -0,0 +1,35 @@
+import { jitter } from "./rng.js";
+const BASE_MS = 55;
+const SPREAD_MS = 25;
+const AFTER_SPACE_MS = 80;
+const AFTER_PUNCTUATION_MS = 160;
+const PUNCTUATION = new Set([".", ",", "?", "!", ":", ";"]);
+/**
+ * When each character of `text` gets typed, in milliseconds from the start.
+ *
+ * Constant-rate typing is one of the strongest tells that a demo is scripted.
+ * Real typing varies per keystroke and pauses at word and clause boundaries,
+ * so the pause goes *after* a space or a comma, where a person's hands
+ * actually hesitate. No fake typos: they read as a gimmick on second viewing
+ * and make the clip impossible to re-cut.
+ */
+export function typingSchedule(text, rng) {
+    const times = [];
+    let t = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const previous = i > 0 ? text[i - 1] : "";
+        let extra = 0;
+        if (previous === " ")
+            extra = AFTER_SPACE_MS;
+        else if (PUNCTUATION.has(previous))
+            extra = AFTER_PUNCTUATION_MS;
+        t += Math.max(10, BASE_MS + jitter(rng, SPREAD_MS)) + extra;
+        times.push(t);
+    }
+    return times;
+}
+/** Total time `typingSchedule` spans, in milliseconds. */
+export function typingDuration(times) {
+    return times.length === 0 ? 0 : times[times.length - 1];
+}
+//# sourceMappingURL=typing.js.map

package/dist/core/typing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typing.js","sourceRoot":"","sources":["../../src/core/typing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,OAAO,GAAG,EAAE,CAAC;AACnB,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAiB;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,QAAQ,KAAK,GAAG;YAAE,KAAK,GAAG,cAAc,CAAC;aACxC,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,KAAK,GAAG,oBAAoB,CAAC;QAEjE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC;QAC5D,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/driver/clip.d.ts

@@ -0,0 +1,71 @@
+import type { Browser } from "playwright";
+import type { CaptureConfig, ResolvedConfig } from "../config.js";
+import type { Timeline } from "../core/timeline.js";
+import type { RecordingTiming } from "../core/timing.js";
+import type { SettleReport } from "./settle.js";
+import { RecordingSession } from "./session.js";
+export type ClipOptions = {
+    /** Shown as the clip's caption, unless the body sets its own. */
+    title: string;
+    /** Per-clip overrides of the config, for a clip that needs a different shape. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    dpr?: number;
+    fps?: number;
+    /** Seeds the jitter in cursor paths, dwells and typing. */
+    seed?: number;
+    /**
+     * Per-clip capture overrides. A clip that films a canvas sets
+     * `forceCaptureEvery: 1` here rather than making every other clip pay.
+     */
+    capture?: CaptureConfig;
+};
+export type ClipBody = (session: RecordingSession) => Promise<void>;
+export type ClipDefinition = {
+    id: string;
+    options: ClipOptions;
+    body: ClipBody;
+};
+/**
+ * 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 declare function clip(id: string, options: ClipOptions, body: ClipBody): ClipDefinition;
+export type RunClipResult = {
+    timeline: Timeline;
+    dir: string;
+    /** What it cost in real time. Diagnostics; never part of the recording. */
+    cost: RecordingTiming;
+    /**
+     * Every settle, in order. The same list `settles.json` holds, for a caller
+     * that would otherwise read back the file it just caused to be written.
+     */
+    settles: SettleReport[];
+};
+/**
+ * Record one clip.
+ *
+ * A fresh context each time, with the fake clock paused before any navigation
+ * so the app's own boot timers are fake from the first tick.
+ */
+export type RunClipOptions = {
+    /**
+     * Record cheaply, for looking at while writing the clip.
+     *
+     * Fifteen frames a second instead of sixty, captured at CSS scale instead of
+     * device scale — at 1440×900 on a retina context that is 25 ms a frame
+     * rather than 67 ms, for a quarter as many frames.
+     *
+     * What it deliberately does *not* change is the page. The context keeps its
+     * device pixel ratio and its viewport, so the app lays out identically and
+     * runs the same code; a draft that reduced the DPR could pass while the full
+     * capture it stands in for fails on a media query.
+     */
+    draft?: boolean;
+};
+export declare function runClip(browser: Browser, config: ResolvedConfig, definition: ClipDefinition, runOptions?: RunClipOptions): Promise<RunClipResult>;