@farmslot/recipe-runner 0.23.0

package/dist/recording/cdp-video-recorder.js

@@ -0,0 +1,319 @@
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CdpSession, selectCdpTarget, sleep } from '../runtime/cdp.js';
+import { errorMessage } from './capture-helper.js';
+import { RecordingFrameSampler } from './frame-sampler.js';
+import { optionalVideoTiming } from './timeline.js';
+export function createCdpVideoRecorder(options) {
+    return new CdpVideoRecorder(options);
+}
+class CdpVideoRecorder {
+    #cdpPort;
+    #cdpHost;
+    #urlIncludes;
+    #ffmpegPath;
+    constructor(options) {
+        this.name = 'cdp-screencast';
+        this.platform = 'web';
+        this.#cdpPort = options.cdpPort;
+        this.#cdpHost = options.cdpHost ?? '127.0.0.1';
+        this.#urlIncludes = options.urlIncludes;
+        this.#ffmpegPath = options.ffmpegPath ?? process.env.FFMPEG_PATH ?? 'ffmpeg';
+    }
+    async doctor() {
+        try {
+            const bytes = await probeCdpScreenshot(this.#cdpHost, this.#cdpPort, this.#urlIncludes);
+            if (bytes < 64) {
+                return {
+                    ok: false,
+                    code: 'cdp_screenshot_empty',
+                    message: 'CDP Page.captureScreenshot returned no image data.',
+                    suggestedFix: 'Ensure CDP Chrome is open on the recipe UI route.',
+                };
+            }
+            return {
+                ok: true,
+                code: 'ok',
+                message: `CDP Page.captureScreenshot ready (${bytes} bytes probe; browser capture).`,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: 'cdp_unavailable',
+                message: `CDP screenshot probe failed: ${errorMessage(error)}`,
+                suggestedFix: 'Launch debug-chrome on the slot UI port before --record-video.',
+            };
+        }
+    }
+    async start(request) {
+        const maxFps = request.maxFps ?? 30;
+        if (!Number.isFinite(maxFps) || maxFps <= 0)
+            throw new Error('Recording maxFps must be positive.');
+        const target = await selectCdpTarget({
+            host: this.#cdpHost,
+            port: this.#cdpPort,
+            type: 'page',
+            urlIncludes: this.#urlIncludes,
+        });
+        if (!target.webSocketDebuggerUrl)
+            throw new Error('Selected CDP target has no debugger URL.');
+        const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+        let framesDir;
+        try {
+            framesDir = await mkdtemp(path.join(path.dirname(request.outputPath), '.cdp-frames-'));
+        }
+        catch (error) {
+            session.close();
+            throw error;
+        }
+        const timestamps = [];
+        let lastReceivedAt = 0;
+        const pendingAcks = new Set();
+        let captureError;
+        let receivedFrames = 0;
+        const sampler = new RecordingFrameSampler(maxFps);
+        let writeChain = Promise.resolve();
+        let clock;
+        let clockError;
+        try {
+            clock = await measureBrowserClock(session);
+        }
+        catch (error) {
+            clockError = `Recording clock unavailable: ${errorMessage(error)}`;
+        }
+        const retain = async (frame) => {
+            const index = timestamps.length;
+            timestamps.push(frame.timestampMs);
+            lastReceivedAt = frame.receivedAtUnixMs;
+            await writeFile(path.join(framesDir, `frame_${String(index).padStart(6, '0')}.png`), Buffer.from(frame.data, 'base64'));
+        };
+        const unsubscribe = session.on('Page.screencastFrame', (params) => {
+            const timestamp = params.metadata?.timestamp;
+            const data = params.data;
+            const receivedAtUnixMs = Date.now();
+            const ack = session
+                .call('Page.screencastFrameAck', { sessionId: params.sessionId })
+                .catch((error) => {
+                captureError = error;
+            })
+                .finally(() => pendingAcks.delete(ack));
+            pendingAcks.add(ack);
+            writeChain = writeChain
+                .then(async () => {
+                if (typeof timestamp !== 'number' ||
+                    !Number.isFinite(timestamp) ||
+                    typeof data !== 'string')
+                    throw new Error('CDP frame is missing its source timestamp or image.');
+                const ready = sampler.accept({ timestampMs: timestamp * 1000, receivedAtUnixMs, data });
+                if (ready)
+                    await retain(ready);
+                receivedFrames++;
+            })
+                .catch((error) => {
+                captureError = error;
+            });
+        });
+        try {
+            await session.call('Page.enable');
+            await session.call('Page.startScreencast', {
+                format: 'png',
+                everyNthFrame: 1,
+                ...(screencastMaxBounds(request.maxSize) ?? {}),
+            });
+            const deadline = Date.now() + 10_000;
+            while (!receivedFrames && !captureError && Date.now() < deadline)
+                await sleep(20);
+            if (captureError)
+                throw captureError;
+            if (!receivedFrames)
+                throw new Error('CDP recorder did not produce its first frame.');
+        }
+        catch (error) {
+            unsubscribe();
+            session.close();
+            await writeChain;
+            await rm(framesDir, { recursive: true, force: true });
+            throw error;
+        }
+        const ffmpegPath = this.#ffmpegPath;
+        let stopped = false;
+        return {
+            async stop() {
+                if (stopped)
+                    throw new Error('CDP recording was already stopped.');
+                stopped = true;
+                const stoppedAtUnixMs = Date.now();
+                unsubscribe();
+                try {
+                    await Promise.all(pendingAcks);
+                    await session.call('Page.stopScreencast');
+                    await writeChain;
+                    if (captureError)
+                        throw captureError;
+                    const finalFrame = sampler.finish();
+                    if (finalFrame)
+                        await retain(finalFrame);
+                    if (clock) {
+                        try {
+                            const endClock = await measureBrowserClock(session);
+                            clock.minOffsetMs = Math.min(clock.minOffsetMs, endClock.minOffsetMs);
+                            clock.maxOffsetMs = Math.max(clock.maxOffsetMs, endClock.maxOffsetMs);
+                        }
+                        catch (error) {
+                            clockError = `Recording end clock unavailable: ${errorMessage(error)}`;
+                            clock = undefined;
+                        }
+                    }
+                    await encodePngSequenceToMp4({
+                        ffmpegPath,
+                        framesDir,
+                        outputPath: request.outputPath,
+                        timestamps,
+                        lastFrameDurationMs: Math.max(1, clock
+                            ? stoppedAtUnixMs + (clock.minOffsetMs + clock.maxOffsetMs) / 2 - timestamps.at(-1)
+                            : stoppedAtUnixMs - lastReceivedAt),
+                    });
+                    const stats = await stat(request.outputPath);
+                    if (stats.size <= 0)
+                        throw new Error(`Recording output is empty: ${request.outputPath}`);
+                    // A CDP first frame can predate startScreencast. Use its source clock,
+                    // calibrated through an isolated world, rather than process lifetime.
+                    const timing = clock
+                        ? await optionalVideoTiming(request.outputPath, {
+                            clock: {
+                                source: 'cdp-source-clock',
+                                earliestZeroUnixMs: timestamps[0] - clock.maxOffsetMs,
+                                latestZeroUnixMs: timestamps[0] - clock.minOffsetMs,
+                            },
+                        })
+                        : { timingUnavailableReason: clockError };
+                    return {
+                        ...timing,
+                        recorder: {
+                            name: 'cdp-screencast',
+                            platform: 'web',
+                            target: { selector: 'cdp-page', value: target.url ?? `cdp:${request.nodeId}` },
+                        },
+                    };
+                }
+                finally {
+                    session.close();
+                    await rm(framesDir, { recursive: true, force: true });
+                }
+            },
+        };
+    }
+}
+async function measureBrowserClock(session) {
+    const tree = await session.call('Page.getFrameTree');
+    const world = await session.call('Page.createIsolatedWorld', {
+        frameId: tree.frameTree.frame.id,
+        worldName: 'recipe-recording-clock',
+    });
+    const before = Date.now();
+    const result = await session.call('Runtime.evaluate', {
+        expression: 'Date.now()',
+        contextId: world.executionContextId,
+        returnByValue: true,
+    });
+    const after = Date.now();
+    const remote = result.result.value;
+    if (typeof remote !== 'number' || !Number.isFinite(remote))
+        throw new Error('Browser clock sample is unavailable.');
+    // Millisecond clock quantization contributes one millisecond at each bound.
+    return { minOffsetMs: remote - after - 1, maxOffsetMs: remote - before + 1 };
+}
+function screencastMaxBounds(maxSize) {
+    if (maxSize == null || !Number.isFinite(maxSize) || maxSize <= 0)
+        return undefined;
+    const edge = Math.round(maxSize);
+    return { maxWidth: edge, maxHeight: edge };
+}
+async function probeCdpScreenshot(host, port, urlIncludes) {
+    const target = await selectCdpTarget({
+        host,
+        port,
+        type: 'page',
+        urlIncludes,
+    });
+    if (!target.webSocketDebuggerUrl) {
+        throw new Error('CDP target missing webSocketDebuggerUrl.');
+    }
+    const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+    try {
+        await session.call('Page.enable');
+        const shot = await session.call('Page.captureScreenshot', {
+            format: 'png',
+        });
+        return shot.data ? Buffer.from(shot.data, 'base64').length : 0;
+    }
+    finally {
+        session.close();
+    }
+}
+async function encodePngSequenceToMp4({ ffmpegPath, framesDir, outputPath, timestamps, lastFrameDurationMs, }) {
+    if (!timestamps.length)
+        throw new Error('No CDP frames captured.');
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    // ffconcat preserves variable capture intervals. The last repeated image
+    // holds the final captured state through stop; it is not another observation.
+    const file = (index) => `frame_${String(index).padStart(6, '0')}.png`;
+    const rows = timestamps.map((timestamp, index) => {
+        const durationMs = index + 1 < timestamps.length ? timestamps[index + 1] - timestamp : lastFrameDurationMs;
+        return `file '${file(index)}'\noption framerate 1000\nduration ${(durationMs / 1000).toFixed(6)}`;
+    });
+    rows.push(`file '${file(timestamps.length - 1)}'\noption framerate 1000`);
+    const listPath = path.join(framesDir, 'frames.ffconcat');
+    await writeFile(listPath, `ffconcat version 1.0\n${rows.join('\n')}\n`);
+    await runCommand(ffmpegPath, [
+        '-y',
+        '-hide_banner',
+        '-loglevel',
+        'error',
+        '-f',
+        'concat',
+        '-safe',
+        '0',
+        '-i',
+        listPath,
+        '-fps_mode',
+        'vfr',
+        '-c:v',
+        'libx264',
+        '-pix_fmt',
+        'yuv420p',
+        '-vf',
+        'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+        '-video_track_timescale',
+        '1000000',
+        '-movflags',
+        '+faststart',
+        outputPath,
+    ], { timeoutMs: 120_000 });
+}
+function runCommand(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stderr = '';
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error(`${command} timed out after ${options.timeoutMs}ms`));
+        }, options.timeoutMs);
+        child.stderr.setEncoding('utf-8');
+        child.stderr.on('data', (chunk) => (stderr += chunk));
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('exit', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} failed (exit ${code}): ${stderr.trim()}`));
+        });
+    });
+}
+//# sourceMappingURL=cdp-video-recorder.js.map

package/dist/recording/cdp-video-recorder.js.map

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

package/dist/recording/frame-sampler.d.ts

@@ -0,0 +1,19 @@
+export interface CapturedFrame {
+    timestampMs: number;
+    receivedAtUnixMs: number;
+    data: string;
+}
+/** Keep the last observed repaint in each source-clock sampling window.
+ * Dropping every frame too close to the preceding one can lose the final
+ * repaint of an otherwise idle page indefinitely. */
+export declare class RecordingFrameSampler {
+    private readonly maxFps;
+    private originMs;
+    private bucket;
+    private pending;
+    private lastTimestampMs;
+    constructor(maxFps: number);
+    accept(frame: CapturedFrame): CapturedFrame | undefined;
+    finish(): CapturedFrame | undefined;
+}
+//# sourceMappingURL=frame-sampler.d.ts.map

package/dist/recording/frame-sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-sampler.d.ts","sourceRoot":"","sources":["../../src/recording/frame-sampler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;qDAEqD;AACrD,qBAAa,qBAAqB;IAMpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,eAAe,CAAa;gBAEP,MAAM,EAAE,MAAM;IAK3C,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS;IAYvD,MAAM,IAAI,aAAa,GAAG,SAAS;CAKpC"}

package/dist/recording/frame-sampler.js

@@ -0,0 +1,29 @@
+/** Keep the last observed repaint in each source-clock sampling window.
+ * Dropping every frame too close to the preceding one can lose the final
+ * repaint of an otherwise idle page indefinitely. */
+export class RecordingFrameSampler {
+    constructor(maxFps) {
+        this.maxFps = maxFps;
+        this.bucket = -1;
+        this.lastTimestampMs = -Infinity;
+        if (!Number.isFinite(maxFps) || maxFps <= 0)
+            throw new Error('Recording maxFps must be positive.');
+    }
+    accept(frame) {
+        if (!Number.isFinite(frame.timestampMs) || frame.timestampMs < this.lastTimestampMs)
+            throw new Error('Recording frame timestamp is invalid or moved backwards.');
+        this.lastTimestampMs = frame.timestampMs;
+        this.originMs ??= frame.timestampMs;
+        const bucket = Math.floor(((frame.timestampMs - this.originMs) * this.maxFps) / 1000);
+        const ready = bucket !== this.bucket ? this.pending : undefined;
+        this.bucket = bucket;
+        this.pending = frame;
+        return ready;
+    }
+    finish() {
+        const frame = this.pending;
+        this.pending = undefined;
+        return frame;
+    }
+}
+//# sourceMappingURL=frame-sampler.js.map

package/dist/recording/frame-sampler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-sampler.js","sourceRoot":"","sources":["../../src/recording/frame-sampler.ts"],"names":[],"mappings":"AAMA;;qDAEqD;AACrD,MAAM,OAAO,qBAAqB;IAMhC,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;QAJnC,WAAM,GAAG,CAAC,CAAC,CAAC;QAEZ,oBAAe,GAAG,CAAC,QAAQ,CAAC;QAGlC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,KAAoB;QACzB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,eAAe;YACjF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC;QACzC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,WAAW,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QACtF,MAAM,KAAK,GAAG,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/recording/timeline.d.ts

@@ -0,0 +1,15 @@
+import { type RecipeRecordingTimelineDocument, type RecipeVideoTiming } from '@farmslot/protocol';
+import type { TraceEntry, VideoRecordingResult } from '../core/types.js';
+/** For continuous, real-time recordings: capture happened within these host
+ * lifecycle bounds. This is deliberately a range, never a process-start guess. */
+export declare function probeVideoTiming(file: string, bounds: {
+    startedAtUnixMs: number;
+    stoppedAtUnixMs: number;
+} | {
+    clock: RecipeVideoTiming['clock'];
+}, ffprobePath?: string): Promise<RecipeVideoTiming>;
+/** Optional observability failure stays explicit without discarding a valid video. */
+export declare function optionalVideoTiming(...args: Parameters<typeof probeVideoTiming>): Promise<Pick<VideoRecordingResult, 'timing' | 'timingUnavailableReason'>>;
+export declare function createRecordingTimeline(videoPath: string, videoDigest: string, timing: RecipeVideoTiming, trace: TraceEntry[]): RecipeRecordingTimelineDocument;
+export declare function writeRecordingTimeline(artifactsDir: string, videoPath: string, timing: RecipeVideoTiming, trace: TraceEntry[]): Promise<string>;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/recording/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/recording/timeline.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,iBAAiB,EAEvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAIzE;kFACkF;AAClF,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EACF;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAA;CAAE,EACzC,WAAW,SAAwC,GAClD,OAAO,CAAC,iBAAiB,CAAC,CAwD5B;AAED,sFAAsF;AACtF,wBAAsB,mBAAmB,CACvC,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,yBAAyB,CAAC,CAAC,CAM3E;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,UAAU,EAAE,GAClB,+BAA+B,CAuBjC;AAED,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/recording/timeline.js

@@ -0,0 +1,88 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { digestRecipeDocument, validateRecipeRecordingTimelineDocument, } from '@farmslot/protocol';
+import { digestFileWithinRoot, writeFileWithinRoot } from '../core/path.js';
+const exec = promisify(execFile);
+/** For continuous, real-time recordings: capture happened within these host
+ * lifecycle bounds. This is deliberately a range, never a process-start guess. */
+export async function probeVideoTiming(file, bounds, ffprobePath = process.env.FFPROBE_PATH ?? 'ffprobe') {
+    const { stdout } = await exec(ffprobePath, [
+        '-v',
+        'error',
+        '-select_streams',
+        'v:0',
+        '-show_frames',
+        '-show_entries',
+        'frame=best_effort_timestamp_time,pkt_duration_time:format=duration',
+        '-of',
+        'json',
+        file,
+    ], { timeout: 120_000, maxBuffer: 32 * 1024 * 1024 });
+    const probe = JSON.parse(stdout);
+    const framesMs = (probe.frames ?? []).map((frame) => Number(frame.best_effort_timestamp_time) * 1000);
+    const first = framesMs[0];
+    const last = framesMs.at(-1);
+    if (first === undefined ||
+        last === undefined ||
+        framesMs.some((time, i) => !Number.isFinite(time) || time < 0 || (i > 0 && time <= framesMs[i - 1])))
+        throw new Error('Video has no strictly ordered presentation timestamps.');
+    const durationMs = Number(probe.format?.duration) * 1000;
+    if (!Number.isFinite(durationMs) || durationMs <= last)
+        throw new Error('Video duration does not contain its measured frames.');
+    const earliestZeroUnixMs = 'clock' in bounds ? bounds.clock.earliestZeroUnixMs : bounds.startedAtUnixMs - first;
+    const latestZeroUnixMs = 'clock' in bounds ? bounds.clock.latestZeroUnixMs : bounds.stoppedAtUnixMs - last;
+    if (!Number.isFinite(earliestZeroUnixMs) ||
+        !Number.isFinite(latestZeroUnixMs) ||
+        latestZeroUnixMs < earliestZeroUnixMs)
+        throw new Error('Video timestamps do not fit the observed recorder lifetime.');
+    return {
+        framesMs,
+        durationMs,
+        clock: {
+            source: 'clock' in bounds ? bounds.clock.source : 'recorder-lifetime-bound',
+            earliestZeroUnixMs,
+            latestZeroUnixMs,
+        },
+    };
+}
+/** Optional observability failure stays explicit without discarding a valid video. */
+export async function optionalVideoTiming(...args) {
+    try {
+        return { timing: await probeVideoTiming(...args) };
+    }
+    catch (error) {
+        return { timingUnavailableReason: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function createRecordingTimeline(videoPath, videoDigest, timing, trace) {
+    const { earliestZeroUnixMs: earliest, latestZeroUnixMs: latest } = timing.clock;
+    const document = {
+        ...timing,
+        version: 1,
+        videoPath,
+        videoDigest,
+        traceDigest: digestRecipeDocument(trace),
+        markers: trace.map((entry, traceIndex) => ({
+            traceIndex,
+            nodeId: entry.nodeId,
+            action: entry.action,
+            ok: entry.ok,
+            ...(entry.intent ? { intent: entry.intent } : {}),
+            ...(entry.proves ? { proves: entry.proves } : {}),
+            startRangeMs: [Date.parse(entry.startedAt) - latest, Date.parse(entry.startedAt) - earliest],
+            endRangeMs: [Date.parse(entry.endedAt) - latest, Date.parse(entry.endedAt) - earliest],
+        })),
+    };
+    const result = validateRecipeRecordingTimelineDocument(document);
+    if (result.status === 'invalid')
+        throw new Error(`Invalid recording timeline: ${JSON.stringify(result.findings)}`);
+    return document;
+}
+export async function writeRecordingTimeline(artifactsDir, videoPath, timing, trace) {
+    const videoDigest = await digestFileWithinRoot(artifactsDir, videoPath);
+    const document = createRecordingTimeline(videoPath, videoDigest, timing, trace);
+    const timelinePath = `${videoPath}.timeline.json`;
+    await writeFileWithinRoot(artifactsDir, timelinePath, `${JSON.stringify(document)}\n`);
+    return timelinePath;
+}
+//# sourceMappingURL=timeline.js.map

package/dist/recording/timeline.js.map

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

package/dist/runtime/browser-extension.d.ts

@@ -0,0 +1,17 @@
+import { type CdpTargetInfo } from './cdp.js';
+export interface SelectBrowserExtensionPageTargetOptions {
+    host?: string;
+    port: number;
+    extensionId?: string;
+    pathIncludes?: string;
+    titleIncludes?: string;
+}
+export declare function extensionIdFromTarget(target: Pick<CdpTargetInfo, 'url'>): string | undefined;
+export declare function selectBrowserExtensionPageTarget(options: SelectBrowserExtensionPageTargetOptions): Promise<CdpTargetInfo>;
+export declare function openBrowserExtensionPage(options: {
+    host?: string;
+    port: number;
+    extensionId: string;
+    path?: string;
+}): Promise<CdpTargetInfo>;
+//# sourceMappingURL=browser-extension.d.ts.map

package/dist/runtime/browser-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-extension.d.ts","sourceRoot":"","sources":["../../src/runtime/browser-extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAiC,MAAM,UAAU,CAAC;AAE7E,MAAM,WAAW,uCAAuC;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,MAAM,GAAG,SAAS,CAG5F;AAED,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBzB"}

package/dist/runtime/browser-extension.js

@@ -0,0 +1,42 @@
+import { retryJsonGet, selectCdpTarget } from './cdp.js';
+export function extensionIdFromTarget(target) {
+    const match = target.url?.match(/^chrome-extension:\/\/([^/]+)/);
+    return match?.[1];
+}
+export async function selectBrowserExtensionPageTarget(options) {
+    return selectCdpTarget({
+        host: options.host,
+        port: options.port,
+        type: 'page',
+        titleIncludes: options.titleIncludes,
+        predicate(target) {
+            const extensionId = extensionIdFromTarget(target);
+            if (!extensionId)
+                return false;
+            if (options.extensionId && extensionId !== options.extensionId)
+                return false;
+            if (options.pathIncludes && !target.url?.includes(options.pathIncludes))
+                return false;
+            return true;
+        },
+    });
+}
+export async function openBrowserExtensionPage(options) {
+    const host = options.host ?? '127.0.0.1';
+    const extensionPath = options.path?.startsWith('/')
+        ? options.path.slice(1)
+        : (options.path ?? '');
+    const url = `chrome-extension://${options.extensionId}/${extensionPath}`;
+    const response = await fetch(`http://${host}:${options.port}/json/new?${encodeURIComponent(url)}`, {
+        method: 'PUT',
+    });
+    if (!response.ok) {
+        throw new Error(`Opening extension page ${url} failed with HTTP ${response.status}.`);
+    }
+    const targets = await retryJsonGet(`http://${host}:${options.port}/json`);
+    const target = targets.find((candidate) => candidate.url === url);
+    if (!target)
+        throw new Error(`Opened extension page ${url}, but no CDP target appeared.`);
+    return target;
+}
+//# sourceMappingURL=browser-extension.js.map

package/dist/runtime/browser-extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-extension.js","sourceRoot":"","sources":["../../src/runtime/browser-extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAU7E,MAAM,UAAU,qBAAqB,CAAC,MAAkC;IACtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACjE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,OAAgD;IAEhD,OAAO,eAAe,CAAC;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,MAAM;QACZ,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,SAAS,CAAC,MAAM;YACd,MAAM,WAAW,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;YAClD,IAAI,CAAC,WAAW;gBAAE,OAAO,KAAK,CAAC;YAC/B,IAAI,OAAO,CAAC,WAAW,IAAI,WAAW,KAAK,OAAO,CAAC,WAAW;gBAAE,OAAO,KAAK,CAAC;YAC7E,IAAI,OAAO,CAAC,YAAY,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtF,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAK9C;IACC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC;QACjD,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,sBAAsB,OAAO,CAAC,WAAW,IAAI,aAAa,EAAE,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,UAAU,IAAI,IAAI,OAAO,CAAC,IAAI,aAAa,kBAAkB,CAAC,GAAG,CAAC,EAAE,EACpE;QACE,MAAM,EAAE,KAAK;KACd,CACF,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,qBAAqB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAkB,UAAU,IAAI,IAAI,OAAO,CAAC,IAAI,OAAO,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,+BAA+B,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC;AAChB,CAAC"}