autokap 1.0.8 → 1.1.0

package/dist/cli-runner.js

@@ -21,31 +21,51 @@ import { executeProgram } from './opcode-runner.js';
 import { RecoveryChainImpl } from './recovery-chain.js';
 import { parseProgram } from './execution-schema.js';
 import { buildCursorOverlayScript } from './cursor-overlay-script.js';
+import { CLI_VERSION_HEADER } from './cli-contract.js';
 import { logger } from './logger.js';
 import { callLLM } from './llm-provider.js';
+import { APP_VERSION } from './version.js';
+import { normalizeAllowedOrigins, normalizeHttpOrigin, verifySignedExecutionProgramEnvelope, } from './program-signing.js';
 const HEALER_SYSTEM_PROMPT = 'You repair failed deterministic browser opcodes. Respond only with JSON.';
 // ── Main entry point ────────────────────────────────────────────────
 export async function runCapture(options) {
     const config = await requireConfig();
     // Step 1: Get the compiled program
-    let program;
+    let resolvedProgram;
     if (options.program) {
-        program = options.program;
+        let parsedProgram;
+        try {
+            parsedProgram = parseProgram(options.program);
+        }
+        catch (err) {
+            return { success: false, error: `program validation failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        resolvedProgram = {
+            program: parsedProgram,
+            security: deriveUnsignedProgramSecurity(parsedProgram, config.apiBaseUrl),
+        };
     }
     else {
         const fetched = await fetchProgram(config, options.presetId);
         if (!fetched.success) {
             return { success: false, error: fetched.error };
         }
-        program = fetched.program;
-    }
-    // Step 2: Validate the program
-    try {
-        program = parseProgram(program);
-    }
-    catch (err) {
-        return { success: false, error: `program validation failed: ${err instanceof Error ? err.message : String(err)}` };
+        resolvedProgram = {
+            program: fetched.program,
+            security: fetched.security,
+        };
+        try {
+            // Step 2: Validate the program fetched from the server.
+            resolvedProgram = {
+                ...resolvedProgram,
+                program: parseProgram(resolvedProgram.program),
+            };
+        }
+        catch (err) {
+            return { success: false, error: `program validation failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
     }
+    let { program } = resolvedProgram;
     // Persist against the canonical preset identifier selected by the CLI,
     // even if the compiled program carries a human-readable preset slug/name.
     if (program.presetId !== options.presetId) {
@@ -54,8 +74,15 @@ export async function runCapture(options) {
             presetId: options.presetId,
         };
     }
+    try {
+        assertProgramNavigationScope(program, resolvedProgram.security);
+    }
+    catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
     logger.info(`[capture] Running preset "${options.presetId}" — ${program.steps.length} opcodes, ${program.variants.length} variant(s)`);
-    const llmConfig = resolveCliLLMConfig();
+    logger.info(`[capture] Resolved API origin ${resolvedProgram.security.expectedApiOrigin}; navigation scope: ${resolvedProgram.security.allowedNavigationOrigins.join(', ')}`);
+    const llmConfig = resolveCliLLMConfig(resolvedProgram.security);
     // Step 3: Set up recovery chain
     const recoveryChain = new RecoveryChainImpl({
         selectorMemory: options.selectorMemory,
@@ -96,7 +123,7 @@ export async function runCapture(options) {
         logger.info(`[capture] Launching browser${browserOptions.headed ? ' (headed)' : ''}…`);
         if (recordable) {
             recordingDir = await fs.mkdtemp(path.join(os.tmpdir(), `autokap-${program.mediaMode}-`));
-            browser = await Browser.forVideoRecording(browserOptions, recordingDir, buildCursorOverlayScript(program.artifactPlan.cursorTheme ?? 'minimal'));
+            browser = await Browser.forClipCapture(browserOptions, buildCursorOverlayScript(program.artifactPlan.cursorTheme ?? 'minimal'));
         }
         else if (browserOptions.headed) {
             // Headed mode: standalone browser (pool is always headless)
@@ -136,16 +163,22 @@ async function fetchProgram(config, presetId) {
             headers: {
                 'Authorization': `Bearer ${config.apiKey}`,
                 'Content-Type': 'application/json',
+                [CLI_VERSION_HEADER]: APP_VERSION,
             },
         });
         if (!response.ok) {
             return { success: false, error: await formatServerError(response, url) };
         }
         const data = await response.json();
-        if (data?._meta?.stale) {
+        const envelope = verifySignedExecutionProgramEnvelope({
+            apiKey: config.apiKey,
+            envelope: data,
+            expectedApiOrigin: safeOrigin(config.apiBaseUrl),
+        });
+        if (envelope.meta?.stale) {
             logger.warn('[capture] Program is stale — langs/themes changed since last compilation. Recompile to apply changes.');
         }
-        return { success: true, program: data };
+        return { success: true, program: envelope.program, security: envelope.security };
     }
     catch (err) {
         return { success: false, error: `failed to fetch program: ${err instanceof Error ? err.message : String(err)}` };
@@ -181,6 +214,10 @@ async function uploadResults(config, program, result) {
             if (variantSpec?.deviceFrame) {
                 formData.append('deviceFrame', variantSpec.deviceFrame);
             }
+            const deviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale;
+            if (Number.isFinite(deviceScaleFactor)) {
+                formData.append('deviceScaleFactor', String(deviceScaleFactor));
+            }
             formData.append('viewport', JSON.stringify(variantSpec?.viewport ?? null));
             formData.append('artifactPlan', JSON.stringify(program.artifactPlan));
             if (artifact.altText) {
@@ -266,10 +303,17 @@ async function uploadResults(config, program, result) {
             ...variant,
             artifacts: variant.artifacts.map((artifact) => {
                 const { buffer: _buffer, tabIconData: _tabIconData, ...rest } = artifact;
-                return rest;
+                const sanitizedArtifact = sanitizeArtifactForTelemetry(rest);
+                return sanitizedArtifact;
             }),
+            error: redactTelemetryText(variant.error),
+            opcodeResults: variant.opcodeResults.map((opcodeResult) => ({
+                ...opcodeResult,
+                error: redactTelemetryText(opcodeResult.error),
+            })),
         })),
     };
+    const sanitizedHealerPatches = sanitizeHealerPatches(result.healerPatches);
     // Upload telemetry + healer patches
     const telemetryResponse = await fetch(`${config.apiBaseUrl}/api/cli/telemetry`, {
         method: 'POST',
@@ -285,7 +329,7 @@ async function uploadResults(config, program, result) {
             success: result.success,
             mediaMode: program.mediaMode,
             telemetry: result.telemetry,
-            healerPatches: result.healerPatches,
+            healerPatches: sanitizedHealerPatches,
             runResult: strippedRunResult,
             totalDurationMs: result.totalDurationMs,
             variantSummaries: result.variantResults.map(v => ({
@@ -362,7 +406,14 @@ async function applyPreconditions(browser, program) {
         await browser.prepareSessionStorage(preconditions.sessionStorage, { replace: false });
     }
 }
-function resolveCliLLMConfig() {
+function resolveCliLLMConfig(security) {
+    if (!security.runtimeLlmAllowed) {
+        return undefined;
+    }
+    const enabled = process.env.AUTOKAP_ENABLE_RUNTIME_LLM?.trim().toLowerCase();
+    if (enabled !== '1' && enabled !== 'true') {
+        return undefined;
+    }
     const apiKey = process.env.OPENROUTER_API_KEY?.trim();
     if (!apiKey)
         return undefined;
@@ -399,7 +450,103 @@ function buildArtifactFilename(presetId, variantId, artifact) {
                         ? 'mp4'
                         : 'webm';
     const stepToken = typeof artifact.stepIndex === 'number' ? `-${artifact.stepIndex}` : '';
-    return `${presetId}-${variantId}${stepToken}.${ext}`;
+    return `${sanitizeArtifactToken(presetId)}-${sanitizeArtifactToken(variantId)}${stepToken}.${ext}`;
+}
+function sanitizeArtifactToken(value) {
+    const cleaned = value.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/-+/g, '-');
+    return cleaned.length > 0 ? cleaned.slice(0, 80) : 'artifact';
+}
+function deriveUnsignedProgramSecurity(program, apiBaseUrl) {
+    return {
+        expectedApiOrigin: safeOrigin(apiBaseUrl),
+        allowedNavigationOrigins: collectAllowedNavigationOrigins(program),
+        runtimeLlmAllowed: true,
+    };
+}
+function collectAllowedNavigationOrigins(program) {
+    const candidates = [program.baseUrl];
+    if (program.preconditions.credentials?.loginUrl) {
+        candidates.push(program.preconditions.credentials.loginUrl);
+    }
+    for (const step of program.steps) {
+        if (step.kind === 'NAVIGATE') {
+            candidates.push(step.url);
+        }
+    }
+    return normalizeAllowedOrigins(candidates
+        .map((value) => normalizeHttpOrigin(value))
+        .filter((value) => Boolean(value)));
+}
+function assertProgramNavigationScope(program, security) {
+    const allowedOrigins = new Set(normalizeAllowedOrigins(security.allowedNavigationOrigins));
+    if (allowedOrigins.size === 0) {
+        throw new Error('program security metadata does not declare any navigation origins');
+    }
+    for (const step of program.steps) {
+        if (step.kind !== 'NAVIGATE')
+            continue;
+        const origin = normalizeHttpOrigin(step.url);
+        if (!origin || !allowedOrigins.has(origin)) {
+            throw new Error(`program navigation target ${step.url} is outside the signed scope (${Array.from(allowedOrigins).join(', ')})`);
+        }
+    }
+}
+function sanitizeArtifactForTelemetry(artifact) {
+    return {
+        ...artifact,
+        altText: redactTelemetryText(artifact.altText),
+        captureUrl: redactUrl(artifact.captureUrl),
+        elementSelector: undefined,
+        domAssetUrls: artifact.domAssetUrls
+            ?.map((entry) => redactUrl(entry))
+            .filter((entry) => Boolean(entry)),
+    };
+}
+function sanitizeHealerPatches(patches) {
+    return patches.map((patch) => ({
+        ...patch,
+        reason: redactTelemetryText(patch.reason) ?? patch.reason,
+        originalOpcode: redactOpcodeForTelemetry(patch.originalOpcode),
+        replacementOpcodes: patch.replacementOpcodes.map((opcode) => redactOpcodeForTelemetry(opcode)),
+    }));
+}
+function redactOpcodeForTelemetry(opcode) {
+    const base = {
+        ...opcode,
+        description: redactTelemetryText(opcode.description) ?? opcode.description,
+    };
+    if ('selector' in base) {
+        return {
+            ...base,
+            selector: '<redacted-selector>',
+            ...('selectorAlternates' in base ? { selectorAlternates: [] } : {}),
+        };
+    }
+    return base;
+}
+function redactTelemetryText(value) {
+    if (!value)
+        return value;
+    return value
+        .replace(/\{\{(email|password|loginUrl)\}\}/g, '<credential-placeholder>')
+        .replace(/https?:\/\/[^\s"'<>]+/gi, (match) => redactUrl(match) ?? '<redacted-url>')
+        .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '<redacted-email>')
+        .slice(0, 512);
+}
+function redactUrl(value) {
+    if (!value)
+        return value;
+    try {
+        const parsed = new URL(value);
+        parsed.username = '';
+        parsed.password = '';
+        parsed.search = parsed.search ? '?<redacted>' : '';
+        parsed.hash = parsed.hash ? '#<redacted>' : '';
+        return parsed.toString();
+    }
+    catch {
+        return value.slice(0, 256);
+    }
 }
 // ── Progress logging ────────────────────────────────────────────────
 function logProgress(event) {

package/dist/cli.js

@@ -308,6 +308,16 @@ async function readJsonInput(filePath) {
     const raw = await fs.readFile(filePath, 'utf8');
     return JSON.parse(raw);
 }
+async function readSecretFromStdin(label) {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const value = Buffer.concat(chunks).toString('utf8').trim();
+    if (!value) {
+        fatal(`${label} is empty on stdin.`);
+    }
+    return value;
+}
 const presetCmd = program
     .command('preset')
     .description('Manage capture presets');
@@ -636,15 +646,17 @@ authAccountCmd
     .requiredOption('--name <name>', 'Account name')
     .option('--type <type>', 'Account type: credentials or session', 'credentials')
     .option('--email <email>', 'Email for credentials accounts')
-    .option('--password <password>', 'Password for credentials accounts')
-    .option('--login-url <url>', 'Login URL for credentials accounts')
+    .option('--password-stdin', 'Read the password for credentials accounts from stdin', false)
     .action(async (projectId, opts) => {
     const type = opts.type === 'session' ? 'session' : opts.type === 'credentials' ? 'credentials' : null;
     if (!type) {
         fatal('Invalid --type. Use "credentials" or "session".');
     }
-    if (type === 'session' && (opts.email || opts.password || opts.loginUrl)) {
-        fatal('Session accounts do not accept --email, --password, or --login-url.');
+    const password = opts.passwordStdin
+        ? await readSecretFromStdin('Password')
+        : undefined;
+    if (type === 'session' && (opts.email || password)) {
+        fatal('Session accounts do not accept --email or --password-stdin.');
     }
     const config = await requireConfig();
     const data = await requestJson(config, `/api/cli/projects/${projectId}/credentials`, {
@@ -654,8 +666,7 @@ authAccountCmd
             name: opts.name,
             type,
             email: opts.email,
-            password: opts.password,
-            loginUrl: opts.loginUrl,
+            password,
         }),
     }, 'Failed to create account');
     console.log(data.account.id);
@@ -667,18 +678,17 @@ authAccountCmd
     .requiredOption('--account <name-or-id>', 'Account name or ID')
     .option('--name <name>', 'New account name')
     .option('--email <email>', 'Replace the email on a credentials account')
-    .option('--password <password>', 'Replace the password on a credentials account')
-    .option('--login-url <url>', 'Replace the login URL on a credentials account')
+    .option('--password-stdin', 'Read the replacement password from stdin', false)
     .option('--clear-email', 'Remove the stored email from a credentials account', false)
     .option('--clear-password', 'Remove the stored password from a credentials account', false)
-    .option('--clear-login-url', 'Remove the stored login URL from a credentials account', false)
     .action(async (projectId, opts) => {
     if (opts.email && opts.clearEmail)
         fatal('Cannot use --email and --clear-email together.');
-    if (opts.password && opts.clearPassword)
-        fatal('Cannot use --password and --clear-password together.');
-    if (opts.loginUrl && opts.clearLoginUrl)
-        fatal('Cannot use --login-url and --clear-login-url together.');
+    if (opts.passwordStdin && opts.clearPassword)
+        fatal('Cannot use --password-stdin and --clear-password together.');
+    const password = opts.passwordStdin
+        ? await readSecretFromStdin('Password')
+        : undefined;
     const config = await requireConfig();
     const account = await resolveProjectAccount(config, projectId, opts.account);
     const payload = {};
@@ -686,16 +696,12 @@ authAccountCmd
         payload.name = opts.name;
     if (opts.email !== undefined)
         payload.email = opts.email;
-    if (opts.password !== undefined)
-        payload.password = opts.password;
-    if (opts.loginUrl !== undefined)
-        payload.loginUrl = opts.loginUrl;
+    if (password !== undefined)
+        payload.password = password;
     if (opts.clearEmail)
         payload.email = null;
     if (opts.clearPassword)
         payload.password = null;
-    if (opts.clearLoginUrl)
-        payload.loginUrl = null;
     if (Object.keys(payload).length === 0) {
         fatal('No changes provided. Pass at least one update option.');
     }

package/dist/clip-begin-frame-recorder.d.ts

@@ -0,0 +1,44 @@
+import type { Page } from 'playwright';
+import type { RecordingResult } from './execution-types.js';
+import type { ClipOptions } from './types.js';
+export interface BeginFrameClipRecorderOptions {
+    baseDir?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    requestedScale?: number;
+    effectiveScale: number;
+    clipOptions?: ClipOptions;
+    sourceFps?: number;
+    outputFps?: number;
+}
+export declare class BeginFrameClipRecorder {
+    private readonly page;
+    private readonly options;
+    private readonly sourceFps;
+    private readonly outputFps;
+    private readonly workingDirPromise;
+    private readonly startedAt;
+    private readonly frames;
+    private stopRequested;
+    private loopPromise;
+    private finalResult;
+    private frameDimensions;
+    private lastCaptureError;
+    private readonly pendingWrites;
+    private pendingWriteError;
+    private cdpSession;
+    private cdpSessionPromise;
+    constructor(page: Page, options: BeginFrameClipRecorderOptions);
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    abort(): Promise<void>;
+    private runCaptureLoop;
+    private captureFrame;
+    private captureFrameBuffer;
+    private getCdpSession;
+    private queueFrameWrite;
+    private waitForPendingWriteCapacity;
+    private flushPendingWrites;
+}

package/dist/clip-begin-frame-recorder.js

@@ -0,0 +1,250 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { postProcessClipFrames } from './clip-postprocess.js';
+import { resolvePhysicalCaptureSize } from './clip-scale.js';
+import { logger } from './logger.js';
+const DEFAULT_BEGIN_FRAME_SOURCE_FPS = 24;
+const DEFAULT_BEGIN_FRAME_OUTPUT_FPS = 24;
+const BEGIN_FRAME_SCREENSHOT_FORMAT = 'png';
+const MAX_PENDING_FRAME_WRITES = 4;
+export class BeginFrameClipRecorder {
+    page;
+    options;
+    sourceFps;
+    outputFps;
+    workingDirPromise;
+    startedAt = Date.now();
+    frames = [];
+    stopRequested = false;
+    loopPromise = null;
+    finalResult = null;
+    frameDimensions = null;
+    lastCaptureError = null;
+    pendingWrites = new Set();
+    pendingWriteError = null;
+    cdpSession = null;
+    cdpSessionPromise = null;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+        this.sourceFps = Math.max(1, Math.round(options.sourceFps ?? DEFAULT_BEGIN_FRAME_SOURCE_FPS));
+        this.outputFps = Math.max(1, Math.round(options.outputFps ?? DEFAULT_BEGIN_FRAME_OUTPUT_FPS));
+        this.workingDirPromise = options.baseDir
+            ? Promise.resolve(options.baseDir)
+            : fs.mkdtemp(path.join(os.tmpdir(), 'autokap-clip-begin-frame-'));
+        this.frameDimensions = resolvePhysicalCaptureSize(options.viewport, options.effectiveScale)
+            ?? {
+                width: Math.max(2, Math.round(options.viewport.width)) & ~1,
+                height: Math.max(2, Math.round(options.viewport.height)) & ~1,
+            };
+    }
+    async start() {
+        const workingDir = await this.workingDirPromise;
+        await fs.mkdir(path.join(workingDir, 'frames'), { recursive: true });
+        await this.captureFrame(Date.now(), false);
+        this.loopPromise = this.runCaptureLoop();
+    }
+    async stop() {
+        if (this.finalResult) {
+            return this.finalResult;
+        }
+        this.stopRequested = true;
+        await this.loopPromise;
+        const stopAt = Date.now();
+        await this.captureFrame(stopAt, true);
+        await this.flushPendingWrites();
+        if (this.frames.length === 0) {
+            throw this.lastCaptureError ?? new Error('clip capture failed before any frame could be recorded');
+        }
+        if (this.pendingWriteError) {
+            throw this.pendingWriteError;
+        }
+        const workingDir = await this.workingDirPromise;
+        const outputDimensions = this.frameDimensions
+            ?? resolvePhysicalCaptureSize(this.options.viewport, this.options.effectiveScale)
+            ?? this.options.viewport;
+        const frameEntries = buildFrameEntries(this.frames, stopAt, this.sourceFps, this.outputFps);
+        const actualSourceFps = resolveActualSourceFps(this.frames, stopAt);
+        try {
+            const result = await postProcessClipFrames(frameEntries, workingDir, 'clip', {
+                ...this.options.clipOptions,
+                mp4Width: outputDimensions.width,
+                mp4Height: outputDimensions.height,
+                outputFps: this.outputFps,
+            });
+            if (!result.mp4Path || !result.thumbnailPath) {
+                throw new Error('clip packaging failed: missing MP4 or thumbnail output');
+            }
+            const [mp4Buffer, gifBuffer, thumbnailBuffer] = await Promise.all([
+                fs.readFile(result.mp4Path),
+                result.gifPath ? fs.readFile(result.gifPath) : Promise.resolve(null),
+                fs.readFile(result.thumbnailPath),
+            ]);
+            const clipPackage = {
+                mp4: {
+                    buffer: mp4Buffer,
+                    mimeType: 'video/mp4',
+                },
+                ...(gifBuffer
+                    ? {
+                        gif: {
+                            buffer: gifBuffer,
+                            mimeType: 'image/gif',
+                        },
+                    }
+                    : {}),
+                thumbnail: {
+                    buffer: thumbnailBuffer,
+                    mimeType: 'image/png',
+                },
+                captureMethod: 'begin_frame',
+                requestedScale: this.options.requestedScale,
+                effectiveScale: this.options.effectiveScale,
+                sourceFps: this.sourceFps,
+                actualSourceFps,
+                outputFps: this.outputFps,
+                frameCount: this.frames.length,
+                dimensions: outputDimensions,
+            };
+            this.finalResult = {
+                buffer: mp4Buffer,
+                mimeType: 'video/mp4',
+                durationMs: result.durationMs,
+                trimStartMs: 0,
+                clipPackage,
+            };
+            return this.finalResult;
+        }
+        finally {
+            await this.cdpSession?.detach().catch(() => undefined);
+            await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async abort() {
+        this.stopRequested = true;
+        await this.loopPromise?.catch(() => undefined);
+        await this.cdpSession?.detach().catch(() => undefined);
+        const workingDir = await this.workingDirPromise;
+        await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    async runCaptureLoop() {
+        const frameIntervalMs = Math.max(1, Math.round(1000 / this.sourceFps));
+        let nextCaptureAt = this.startedAt + frameIntervalMs;
+        while (!this.stopRequested) {
+            const waitMs = nextCaptureAt - Date.now();
+            if (waitMs > 0) {
+                await sleep(waitMs);
+            }
+            if (this.stopRequested) {
+                return;
+            }
+            await this.captureFrame(Date.now(), true);
+            nextCaptureAt += frameIntervalMs;
+        }
+    }
+    async captureFrame(capturedAt, allowFailure) {
+        try {
+            const workingDir = await this.workingDirPromise;
+            const frameIndex = this.frames.length;
+            const framePath = path.join(workingDir, 'frames', `frame-${String(frameIndex).padStart(6, '0')}.png`);
+            const frameBuffer = await this.captureFrameBuffer();
+            await this.queueFrameWrite(framePath, frameBuffer);
+            this.frames.push({ path: framePath, capturedAt });
+        }
+        catch (error) {
+            const captureError = error instanceof Error ? error : new Error(String(error));
+            this.lastCaptureError = captureError;
+            if (!allowFailure) {
+                throw captureError;
+            }
+            logger.debug(`[clip] begin_frame capture skipped: ${captureError.message}`);
+        }
+    }
+    async captureFrameBuffer() {
+        const session = await this.getCdpSession();
+        const result = await session.send('HeadlessExperimental.beginFrame', {
+            interval: 1000 / this.sourceFps,
+            noDisplayUpdates: false,
+            screenshot: {
+                format: BEGIN_FRAME_SCREENSHOT_FORMAT,
+                optimizeForSpeed: true,
+            },
+        });
+        if (!result.screenshotData) {
+            throw new Error('HeadlessExperimental.beginFrame returned no screenshot data');
+        }
+        return Buffer.from(result.screenshotData, 'base64');
+    }
+    async getCdpSession() {
+        if (this.cdpSession) {
+            return this.cdpSession;
+        }
+        if (!this.cdpSessionPromise) {
+            this.cdpSessionPromise = (async () => {
+                const context = this.page.context();
+                if (typeof context.newCDPSession !== 'function') {
+                    throw new Error('CDP sessions are unavailable in this Playwright runtime');
+                }
+                const session = await context.newCDPSession(this.page);
+                this.cdpSession = session;
+                return session;
+            })();
+        }
+        return this.cdpSessionPromise;
+    }
+    async queueFrameWrite(framePath, frameBuffer) {
+        await this.waitForPendingWriteCapacity();
+        if (this.pendingWriteError) {
+            throw this.pendingWriteError;
+        }
+        let writePromise;
+        writePromise = fs.writeFile(framePath, frameBuffer)
+            .catch((error) => {
+            this.pendingWriteError = error instanceof Error ? error : new Error(String(error));
+            throw this.pendingWriteError;
+        })
+            .finally(() => {
+            this.pendingWrites.delete(writePromise);
+        });
+        this.pendingWrites.add(writePromise);
+    }
+    async waitForPendingWriteCapacity() {
+        while (this.pendingWrites.size >= MAX_PENDING_FRAME_WRITES) {
+            await Promise.race(this.pendingWrites);
+            if (this.pendingWriteError) {
+                throw this.pendingWriteError;
+            }
+        }
+    }
+    async flushPendingWrites() {
+        while (this.pendingWrites.size > 0) {
+            await Promise.allSettled(Array.from(this.pendingWrites));
+        }
+    }
+}
+function buildFrameEntries(frames, stopAt, sourceFps, outputFps) {
+    const entries = [];
+    const minFrameDurationMs = Math.max(1, Math.min(Math.round(1000 / sourceFps), Math.round(1000 / outputFps)));
+    for (let index = 0; index < frames.length; index += 1) {
+        const frame = frames[index];
+        const nextTimestamp = frames[index + 1]?.capturedAt ?? stopAt;
+        entries.push({
+            path: frame.path,
+            durationMs: Math.max(minFrameDurationMs, nextTimestamp - frame.capturedAt),
+        });
+    }
+    return entries;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveActualSourceFps(frames, stopAt) {
+    if (frames.length <= 1) {
+        return frames.length;
+    }
+    const firstTimestamp = frames[0].capturedAt;
+    const durationSec = Math.max(0.001, (stopAt - firstTimestamp) / 1000);
+    return Math.round((frames.length / durationSec) * 100) / 100;
+}
+//# sourceMappingURL=clip-begin-frame-recorder.js.map

package/dist/clip-capture-backend.d.ts

@@ -0,0 +1,25 @@
+import type { Page } from 'playwright';
+import type { Browser } from './browser.js';
+import type { ClipCaptureMethod, RecordingResult } from './execution-types.js';
+import type { ClipOptions } from './types.js';
+export interface ClipCaptureBackendFactoryOptions {
+    browser: Browser;
+    page: Page;
+    recordingDir?: string;
+    captureMethod: ClipCaptureMethod;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    requestedScale?: number;
+    effectiveScale: number;
+    clipOptions?: ClipOptions;
+    fallbackReason?: string;
+}
+export interface ClipCaptureBackend {
+    readonly captureMethod: ClipCaptureMethod;
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    abort(): Promise<void>;
+}
+export declare function createClipCaptureBackend(options: ClipCaptureBackendFactoryOptions): ClipCaptureBackend;