autokap 1.8.5 → 1.8.7

package/dist/cli-runner.js

@@ -29,14 +29,17 @@ import { applyDeviceFrame, seedDeviceConfigs } from './mockup.js';
 import { transformBrowserUrl } from './transform-browser-url.js';
 import { localizeStatusBar } from './status-bar-l10n.js';
 import { logger } from './logger.js';
+import { buildPreconditionCookies } from './scenario-cookie.js';
 import { callLLM } from './llm-provider.js';
 import { APP_VERSION } from './version.js';
+import { ENGINE_VERSION, CURRENT_PROGRAM_SCHEMA_VERSION } from './engine-version.js';
+import { readOriginSchemaVersion } from './program-migrations.js';
+import { hashProgram } from './program-hash.js';
 import { normalizeAllowedOrigins, normalizeHttpOrigin, verifySignedExecutionProgramEnvelope, } from './program-signing.js';
 import { redactTelemetryText, redactUrl } from './telemetry-redaction.js';
 import { LogCollector } from './log-collector.js';
 const MAX_CLIP_CAPTURE_DEVICE_SCALE_FACTOR = 1;
 const DEFAULT_VIDEO_DELIVERY_RESOLUTION = { width: 1920, height: 1080 };
-const DEFAULT_VIDEO_CAPTURE_RESOLUTION = DEFAULT_VIDEO_DELIVERY_RESOLUTION;
 const FETCH_PROGRAM_MAX_ATTEMPTS = 4;
 const FETCH_PROGRAM_RETRY_DELAYS_MS = [1000, 3000, 5000];
 const DEFAULT_SCREENSHOT_ARTIFACT_UPLOAD_CONCURRENCY = 4;
@@ -60,55 +63,25 @@ export function resolveRecordableBrowserSettings(program, variant) {
         runtimeDeviceScaleFactor: 1,
     };
 }
-export function normalizeVideoCaptureProgram(program) {
-    if (program.mediaMode !== 'video')
-        return program;
-    const format = program.artifactPlan.format ?? {};
-    const deliveryResolution = DEFAULT_VIDEO_DELIVERY_RESOLUTION;
-    const captureResolution = format.captureResolution ?? DEFAULT_VIDEO_CAPTURE_RESOLUTION;
-    // Variants are normalized too so any code path that reads `variant.viewport`
-    // or `variant.deviceScaleFactor` directly (not just resolveRecordableBrowserSettings)
-    // sees consistent 1920×1080 @1× values. Legacy presets carrying
-    // viewport=2560×1440 or DPR=1.3333 would otherwise leak through.
-    const targetViewport = { width: deliveryResolution.width, height: deliveryResolution.height };
-    const variantsAlreadyNormalized = program.variants.every((v) => v.viewport.width === targetViewport.width &&
-        v.viewport.height === targetViewport.height &&
-        (v.deviceScaleFactor === undefined || v.deviceScaleFactor === 1));
-    const formatAlreadyNormalized = captureResolution.width === deliveryResolution.width &&
-        captureResolution.height === deliveryResolution.height &&
-        format.deliveryResolution?.width === deliveryResolution.width &&
-        format.deliveryResolution.height === deliveryResolution.height;
-    const outputScaleAlreadyNormalized = program.outputScale === undefined || program.outputScale === 1;
-    if (variantsAlreadyNormalized && formatAlreadyNormalized && outputScaleAlreadyNormalized) {
-        return program;
-    }
-    return {
-        ...program,
-        outputScale: 1,
-        variants: program.variants.map((v) => ({
-            ...v,
-            viewport: { ...targetViewport },
-            deviceScaleFactor: 1,
-        })),
-        artifactPlan: {
-            ...program.artifactPlan,
-            format: {
-                ...format,
-                captureResolution: {
-                    width: deliveryResolution.width,
-                    height: deliveryResolution.height,
-                },
-                deliveryResolution,
-            },
-        },
-    };
-}
+// Legacy video resolution normalization (2560×1440 → 1920×1080 @1×) moved into
+// migrate-on-read (program-migrations.ts, migrate_0→1). It now happens inside
+// parseProgram BEFORE strict validation, so the runner only ever sees the
+// canonical 1920×1080 video form — no runtime normalization pass is needed.
 function normalizeNumericScale(value) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
         return 1;
     }
     return value;
 }
+function buildRunProvenance(program, schemaVersionOrigin) {
+    return {
+        engineVersion: ENGINE_VERSION,
+        programSchemaVersion: program.programSchemaVersion ?? CURRENT_PROGRAM_SCHEMA_VERSION,
+        programSchemaVersionOrigin: schemaVersionOrigin,
+        cliVersion: APP_VERSION,
+        programHash: hashProgram(program),
+    };
+}
 const HEALER_SYSTEM_PROMPT = 'You repair failed deterministic browser opcodes. Respond only with JSON.';
 // ── Main entry point ────────────────────────────────────────────────
 export async function runCapture(options) {
@@ -125,12 +98,16 @@ export async function runCapture(options) {
         };
     }
     const config = await requireConfig();
-    // Step 1: Get the compiled program
+    // Step 1: Get the compiled program. Capture the stored FORM version BEFORE
+    // migrate-on-read (parseProgram) bumps it, so run provenance can record the
+    // origin schema version (0 = legacy / no version field).
     let resolvedProgram;
+    let schemaVersionOrigin = 0;
     if (options.program) {
         let parsedProgram;
         try {
-            parsedProgram = normalizeVideoCaptureProgram(parseProgram(options.program));
+            schemaVersionOrigin = readOriginSchemaVersion(options.program);
+            parsedProgram = parseProgram(options.program);
         }
         catch (err) {
             return { success: false, error: `program validation failed: ${err instanceof Error ? err.message : String(err)}` };
@@ -150,10 +127,14 @@ export async function runCapture(options) {
             security: fetched.security,
         };
         try {
-            // Step 2: Validate the program fetched from the server.
+            // Step 2: Validate the program fetched from the server. The server reports
+            // the TRUE pre-migration origin via the envelope meta (the fetched program
+            // is already server-migrated); fall back to reading it locally for older
+            // servers that don't send it.
+            schemaVersionOrigin = fetched.schemaVersionOrigin ?? readOriginSchemaVersion(resolvedProgram.program);
             resolvedProgram = {
                 ...resolvedProgram,
-                program: normalizeVideoCaptureProgram(parseProgram(resolvedProgram.program)),
+                program: parseProgram(resolvedProgram.program),
             };
         }
         catch (err) {
@@ -192,7 +173,7 @@ export async function runCapture(options) {
         videoAudioAssets = prepareResult.audioAssets;
         videoAudioAssetsByLocale = prepareResult.audioAssetsByLocale;
         try {
-            program = normalizeVideoCaptureProgram(parseProgram(program));
+            program = parseProgram(program);
         }
         catch (err) {
             return { success: false, runId, error: `prepared video program validation failed: ${err instanceof Error ? err.message : String(err)}` };
@@ -321,7 +302,8 @@ export async function runCapture(options) {
                     variantId: 'run',
                     message: 'saving captures',
                 });
-                const uploadOutcome = await uploadResults(config, program, runResult, runId);
+                const provenance = buildRunProvenance(program, schemaVersionOrigin);
+                const uploadOutcome = await uploadResults(config, program, runResult, runId, provenance);
                 if (program.mediaMode === 'video' && runResult.success) {
                     await signalVideoComplete(config, program, runResult, uploadOutcome.runId, videoAudioAssets, videoAudioAssetsByLocale);
                 }
@@ -434,7 +416,12 @@ async function fetchProgram(config, presetId, environmentName) {
         if (envelope.meta?.stale) {
             logger.warn('[capture] Program needs regeneration — preset settings require missing or outdated opcodes. Regenerate before relying on this capture.');
         }
-        return { success: true, program: envelope.program, security: envelope.security };
+        return {
+            success: true,
+            program: envelope.program,
+            security: envelope.security,
+            schemaVersionOrigin: envelope.meta?.programSchemaVersionOrigin,
+        };
     }
     return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
 }
@@ -694,7 +681,7 @@ async function postRunStart(config, runId, presetId, variantCount, env) {
         logger.warn(`[capture] Run registration error: ${message}`);
     }
 }
-async function uploadResults(config, program, result, runId = randomUUID()) {
+async function uploadResults(config, program, result, runId, provenance) {
     const artifactJobs = result.variantResults.flatMap((variant) => {
         const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);
         return variant.artifacts.map((artifact) => ({
@@ -709,7 +696,7 @@ async function uploadResults(config, program, result, runId = randomUUID()) {
         logger.info(`[capture] Uploading ${totalArtifacts} capture artifacts with concurrency ${artifactUploadConcurrency}`);
     }
     await runWithConcurrency(artifactJobs, artifactUploadConcurrency, async (job, index) => {
-        await uploadArtifact(config, program, runId, totalArtifacts, index + 1, job);
+        await uploadArtifact(config, program, runId, totalArtifacts, index + 1, job, provenance);
     });
     // Strip binary buffers from artifacts before sending. The raw PNG/video
     // buffers were already uploaded via /api/cli/artifacts above, and the
@@ -745,6 +732,12 @@ async function uploadResults(config, program, result, runId = randomUUID()) {
             presetId: program.presetId,
             programVersion: program.programVersion,
             compileFingerprint: program.compileFingerprint,
+            // AutoKap Engine provenance (AUT-242) — persisted on capture_runs for debug.
+            engineVersion: provenance.engineVersion,
+            programSchemaVersion: provenance.programSchemaVersion,
+            programSchemaVersionOrigin: provenance.programSchemaVersionOrigin,
+            cliVersion: provenance.cliVersion,
+            programHash: provenance.programHash,
             success: result.success,
             mediaMode: program.mediaMode,
             telemetry: result.telemetry,
@@ -864,13 +857,13 @@ function inferVariantLocale(variantId) {
 function inferVariantTheme(variantId) {
     return variantId.endsWith('-dark') ? 'dark' : 'light';
 }
-async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumber, job) {
+async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumber, job, provenance) {
     const { artifact, variant, variantSpec } = job;
     const filename = buildArtifactFilename(program.presetId, variant.variantId, artifact);
     const label = artifact.captureName ?? artifact.clipName ?? filename;
     logger.info(`[capture] Exporting capture ${uploadNumber}/${totalArtifacts}: ${label}`);
     if (process.env.AUTOKAP_USE_LEGACY_MULTIPART_UPLOADS === '1') {
-        await uploadArtifactMultipart(config, program, runId, job, filename);
+        await uploadArtifactMultipart(config, program, runId, job, filename, provenance);
         return;
     }
     const prepared = await prepareDirectArtifactUpload({
@@ -879,6 +872,7 @@ async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumb
         artifact,
         variant,
         variantSpec,
+        provenance,
     });
     const uploadsUrl = `${config.apiBaseUrl}/api/cli/artifacts/uploads`;
     const initResponse = await fetch(uploadsUrl, {
@@ -939,13 +933,19 @@ async function uploadArtifact(config, program, runId, totalArtifacts, uploadNumb
         throw new Error(`artifact completion failed for ${variant.variantId}: ${await formatServerError(completeResponse, completeUrl)}`);
     }
 }
-async function uploadArtifactMultipart(config, program, runId, job, filename) {
+async function uploadArtifactMultipart(config, program, runId, job, filename, provenance) {
     const { artifact, variant, variantSpec } = job;
     const formData = new FormData();
     formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
     formData.append('presetId', program.presetId);
     formData.append('programVersion', String(program.programVersion));
     formData.append('compileFingerprint', program.compileFingerprint);
+    // AutoKap Engine provenance (AUT-242).
+    formData.append('engineVersion', String(provenance.engineVersion));
+    formData.append('programSchemaVersion', String(provenance.programSchemaVersion));
+    formData.append('programSchemaVersionOrigin', String(provenance.programSchemaVersionOrigin));
+    formData.append('cliVersion', provenance.cliVersion);
+    formData.append('programHash', provenance.programHash);
     formData.append('runId', runId);
     formData.append('variantId', variant.variantId);
     formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
@@ -1015,7 +1015,7 @@ async function uploadArtifactMultipart(config, program, runId, job, filename) {
     }
 }
 async function prepareDirectArtifactUpload(params) {
-    const { program, runId, artifact, variant, variantSpec } = params;
+    const { program, runId, artifact, variant, variantSpec, provenance } = params;
     const requestedDeviceScaleFactor = variantSpec?.deviceScaleFactor ?? program.outputScale ?? 2;
     const isFrameCapture = artifact.mediaMode === 'clip' || artifact.mediaMode === 'video';
     const deviceScaleFactor = isFrameCapture && Number.isFinite(requestedDeviceScaleFactor)
@@ -1026,6 +1026,11 @@ async function prepareDirectArtifactUpload(params) {
         presetId: program.presetId,
         programVersion: program.programVersion,
         compileFingerprint: program.compileFingerprint,
+        engineVersion: provenance.engineVersion,
+        programSchemaVersion: provenance.programSchemaVersion,
+        programSchemaVersionOrigin: provenance.programSchemaVersionOrigin,
+        cliVersion: provenance.cliVersion,
+        programHash: provenance.programHash,
         runId,
         variantId: variant.variantId,
         targetId: variantSpec?.targetId ?? variant.variantId,
@@ -1332,8 +1337,18 @@ async function applyPreconditions(browser, program) {
     //   {{email}}/{{password}}/{{loginUrl}} placeholders inside opcodes by the
     //   opcode runner, and the program performs the UI login itself.
     // - If neither is set, the run is anonymous.
-    if (preconditions.cookies && preconditions.cookies.length > 0) {
-        await browser.addCookies(preconditions.cookies);
+    // Build seed cookies (+ the signed AUT-239 scenario switch). `secure` is
+    // derived from the target protocol so local http captures aren't silently
+    // stripped of their cookies (see buildPreconditionCookies).
+    const { cookies, warning } = buildPreconditionCookies(preconditions, program.baseUrl, process.env.AUTOKAP_SCENARIO_SECRET);
+    if (warning)
+        logger.warn(`[capture] ${warning}`);
+    if (preconditions.scenario && process.env.AUTOKAP_SCENARIO_SECRET) {
+        logger.info(`[capture] Injected scenario "${preconditions.scenario}" cookie — the target app must run with ` +
+            `AUTOKAP_SCENARIOS=1 (and the same AUTOKAP_SCENARIO_SECRET) or it will capture real data`);
+    }
+    if (cookies.length > 0) {
+        await browser.addCookies(cookies);
     }
     if (preconditions.sessionStorage && Object.keys(preconditions.sessionStorage).length > 0) {
         await browser.prepareSessionStorage(preconditions.sessionStorage, { replace: false });

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

@@ -1,12 +1,18 @@
 /**
- * ClipCaptureLoop — custom CDP Page.captureScreenshot loop.
+ * ClipCaptureLoop — frame source for local clip/video recording.
  *
- * Pulls HiDPI-fidel frames from the Chromium compositor via
- * `Page.captureScreenshot` with `optimizeForSpeed: true` and `fromSurface: true`.
- * Produces crisp screenshot-grade JPEGs (not the downsampled/compressed
- * `Page.startScreencast` stream that DevTools uses for remote debugging).
+ * Primary path (Playwright 1.59+): the official `page.screencast` API streams
+ * JPEG frames through Chromium's screencast pipeline via `onFrame`. Frames
+ * arrive on a more regular cadence than the previous pull-based
+ * `Page.captureScreenshot` loop, and start/stop is precise — frames are only
+ * delivered between `screencast.start()` and `screencast.stop()`, so an
+ * off-camera setup reload before recording is never filmed.
  *
- * Frames are buffered in memory during capture (raw base64), then flushed to
+ * Fallback path: if `page.screencast` is missing or fails to start (older
+ * Playwright, headless quirk), the recorder falls back to the legacy CDP
+ * `Page.captureScreenshot` loop (`optimizeForSpeed` + `fromSurface`).
+ *
+ * Either way, frames are buffered in memory (raw JPEG Buffers) and flushed to
  * disk in parallel at `stop()`. `assembleMp4FromFrames` reads the per-frame
  * timestamps and encodes VFR via the concat demuxer so playback matches the
  * real capture cadence — essential when the compositor is CPU-bound on heavy
@@ -52,12 +58,14 @@ export interface ClipCaptureLoopResult {
      * loop keeps trying, producing bursts and gaps).
      */
     frameOffsetsMs: number[];
-    /** CDP Page.captureScreenshot wall time in milliseconds. */
+    /** CDP Page.captureScreenshot wall time in milliseconds (empty on screencast path). */
     captureTimingMs: {
         p50: number;
         p95: number;
         max: number;
     };
+    /** True when frames came from the official page.screencast API; false on the CDP fallback. */
+    usedScreencast: boolean;
 }
 export declare class ClipCaptureLoop {
     private readonly page;
@@ -69,6 +77,8 @@ export declare class ClipCaptureLoop {
     private cdp;
     private running;
     private loopPromise;
+    private screencastActive;
+    private usedScreencast;
     private frames;
     private frameTimestamps;
     private frameCaptureDurationsMs;
@@ -78,5 +88,16 @@ export declare class ClipCaptureLoop {
     constructor(opts: ClipCaptureLoopOptions);
     start(): Promise<void>;
     stop(): Promise<ClipCaptureLoopResult>;
+    /**
+     * Common frame sink for both the screencast and CDP paths: stamps wall-clock
+     * timing for VFR and buffers the raw JPEG in memory.
+     */
+    private handleFrame;
+    /**
+     * Device-pixel dimensions of the current surface, so screencast frames keep
+     * the HiDPI fidelity the CDP `fromSurface` path produced. Returns undefined
+     * (let screencast pick its default) if the page can't be evaluated.
+     */
+    private resolveCaptureSize;
     private loop;
 }

package/dist/clip-capture-loop.js

@@ -1,12 +1,18 @@
 /**
- * ClipCaptureLoop — custom CDP Page.captureScreenshot loop.
+ * ClipCaptureLoop — frame source for local clip/video recording.
  *
- * Pulls HiDPI-fidel frames from the Chromium compositor via
- * `Page.captureScreenshot` with `optimizeForSpeed: true` and `fromSurface: true`.
- * Produces crisp screenshot-grade JPEGs (not the downsampled/compressed
- * `Page.startScreencast` stream that DevTools uses for remote debugging).
+ * Primary path (Playwright 1.59+): the official `page.screencast` API streams
+ * JPEG frames through Chromium's screencast pipeline via `onFrame`. Frames
+ * arrive on a more regular cadence than the previous pull-based
+ * `Page.captureScreenshot` loop, and start/stop is precise — frames are only
+ * delivered between `screencast.start()` and `screencast.stop()`, so an
+ * off-camera setup reload before recording is never filmed.
  *
- * Frames are buffered in memory during capture (raw base64), then flushed to
+ * Fallback path: if `page.screencast` is missing or fails to start (older
+ * Playwright, headless quirk), the recorder falls back to the legacy CDP
+ * `Page.captureScreenshot` loop (`optimizeForSpeed` + `fromSurface`).
+ *
+ * Either way, frames are buffered in memory (raw JPEG Buffers) and flushed to
  * disk in parallel at `stop()`. `assembleMp4FromFrames` reads the per-frame
  * timestamps and encodes VFR via the concat demuxer so playback matches the
  * real capture cadence — essential when the compositor is CPU-bound on heavy
@@ -14,6 +20,7 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { logger } from './logger.js';
 export class ClipCaptureLoop {
     page;
     framesDir;
@@ -24,6 +31,8 @@ export class ClipCaptureLoop {
     cdp = null;
     running = false;
     loopPromise = null;
+    screencastActive = false;
+    usedScreencast = false;
     frames = [];
     frameTimestamps = [];
     frameCaptureDurationsMs = [];
@@ -56,13 +65,53 @@ export class ClipCaptureLoop {
         this.minRestMs = Math.max(0, Math.min(250, opts.minRestMs ?? platformMinRest));
     }
     async start() {
-        this.cdp = await this.page.context().newCDPSession(this.page);
         this.startedAt = performance.now();
         this.running = true;
+        // Primary: official page.screencast (Playwright 1.59+). Chromium pushes
+        // JPEG frames as the page paints — more regular than pull-based capture,
+        // and start/stop bounds the window precisely.
+        //
+        // CRITICAL fidelity rule: the screencast stream downsamples to CSS
+        // resolution UNLESS `size` is the device-pixel surface. Without it we'd
+        // ship the blurry DevTools-grade stream the CDP `fromSurface` path was
+        // deliberately chosen to avoid. So we only take the screencast path when we
+        // could resolve that HiDPI size; if we can't (or screencast errors), we
+        // fall through to the full-surface CDP loop instead of capturing soft.
+        try {
+            const size = await this.resolveCaptureSize();
+            if (size) {
+                await this.page.screencast.start({
+                    quality: this.jpegQuality,
+                    size,
+                    onFrame: (frame) => {
+                        this.handleFrame(frame.data);
+                    },
+                });
+                this.screencastActive = true;
+                this.usedScreencast = true;
+                return;
+            }
+            logger.warn('[capture] could not resolve the HiDPI capture size; using the CDP capture loop to preserve fidelity');
+        }
+        catch (err) {
+            logger.warn(`[capture] page.screencast unavailable, falling back to CDP capture loop: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Fallback: legacy CDP Page.captureScreenshot loop. Captures the full
+        // device surface via `fromSurface` — full HiDPI fidelity, no size negotiation.
+        this.cdp = await this.page.context().newCDPSession(this.page);
         this.loopPromise = this.loop();
     }
     async stop() {
         this.running = false;
+        if (this.screencastActive) {
+            try {
+                await this.page.screencast.stop();
+            }
+            catch {
+                // page/context may already be closed.
+            }
+            this.screencastActive = false;
+        }
         if (this.loopPromise) {
             await this.loopPromise;
             this.loopPromise = null;
@@ -76,10 +125,10 @@ export class ClipCaptureLoop {
             }
             this.cdp = null;
         }
-        // Flush all captured base64 frames to disk in parallel now that the loop
-        // has stopped. Doing this during capture would bottleneck the loop on
-        // Buffer.from decoding; deferring gets us the full CDP throughput.
-        const writes = this.frames.map((data, i) => fs.writeFile(path.join(this.framesDir, `frame_${String(i).padStart(6, '0')}.jpg`), data, 'base64'));
+        // Flush all captured frames to disk in parallel now that the loop has
+        // stopped. Doing this during capture would bottleneck on disk I/O;
+        // deferring gets us the full capture throughput.
+        const writes = this.frames.map((data, i) => fs.writeFile(path.join(this.framesDir, `frame_${String(i).padStart(6, '0')}.jpg`), data));
         await Promise.all(writes);
         const frameCount = this.frames.length;
         const span = this.lastFrameAt - this.firstFrameAt;
@@ -89,6 +138,7 @@ export class ClipCaptureLoop {
         // Snapshot offsets (ms from first frame) for VFR encoding downstream.
         const frameOffsetsMs = this.frameTimestamps.map(ts => ts - this.firstFrameAt);
         const captureTimingMs = summarizeTiming(this.frameCaptureDurationsMs);
+        const usedScreencast = this.usedScreencast;
         // Release memory — the caller owns framesDir from here on.
         this.frames = [];
         this.frameTimestamps = [];
@@ -103,8 +153,46 @@ export class ClipCaptureLoop {
             trimStartMs,
             frameOffsetsMs,
             captureTimingMs,
+            usedScreencast,
         };
     }
+    /**
+     * Common frame sink for both the screencast and CDP paths: stamps wall-clock
+     * timing for VFR and buffers the raw JPEG in memory.
+     */
+    handleFrame(data) {
+        if (!this.running)
+            return;
+        const ts = performance.now();
+        if (this.firstFrameAt === 0)
+            this.firstFrameAt = ts;
+        this.lastFrameAt = ts;
+        this.frames.push(data);
+        this.frameTimestamps.push(ts);
+    }
+    /**
+     * Device-pixel dimensions of the current surface, so screencast frames keep
+     * the HiDPI fidelity the CDP `fromSurface` path produced. Returns undefined
+     * (let screencast pick its default) if the page can't be evaluated.
+     */
+    async resolveCaptureSize() {
+        // Bounded so a wedged page can never stall recording start — the CDP path
+        // had no such pre-flight evaluate, so cap it and fall back to the default
+        // surface size on timeout/error.
+        const evalDims = this.page
+            .evaluate(() => ({
+            w: Math.round(window.innerWidth * window.devicePixelRatio),
+            h: Math.round(window.innerHeight * window.devicePixelRatio),
+        }))
+            .catch(() => null);
+        const dims = await Promise.race([
+            evalDims,
+            new Promise((resolve) => setTimeout(() => resolve(null), 1000)),
+        ]);
+        if (dims && dims.w > 0 && dims.h > 0)
+            return { width: dims.w, height: dims.h };
+        return undefined;
+    }
     async loop() {
         while (this.running) {
             if (!this.cdp)
@@ -127,14 +215,9 @@ export class ClipCaptureLoop {
                     return;
                 continue;
             }
-            const ts = performance.now();
-            if (this.firstFrameAt === 0)
-                this.firstFrameAt = ts;
-            this.lastFrameAt = ts;
-            // Push raw base64 — no decode, no I/O. Keeps the capture loop tight.
-            // Decode+write happens in stop().
-            this.frames.push(data);
-            this.frameTimestamps.push(ts);
+            // Decode happens here (off the tight loop's hot path is the await above);
+            // store a Buffer so both paths share the same disk-flush in stop().
+            this.handleFrame(Buffer.from(data, 'base64'));
             const elapsed = performance.now() - frameStartedAt;
             this.frameCaptureDurationsMs.push(elapsed);
             const restMs = Math.max(this.minRestMs, this.targetFrameIntervalMs - elapsed);

package/dist/engine-version.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AutoKap Engine — version axes (pure constants, safe on any runtime).
+ *
+ * Kept free of Node-only imports (no `node:module`/`package.json` reads) so it
+ * can be pulled into the schema validation chain that the web app bundles. The
+ * npm package version lives separately in version.ts (`APP_VERSION`).
+ *
+ * Two axes, both decoupled from the npm package version and from each other:
+ *
+ * - `CURRENT_PROGRAM_SCHEMA_VERSION` (FORM): the shape of an `ExecutionProgram`.
+ *   Drives migrate-on-read (program-migrations.ts). A monotonic integer bumped
+ *   whenever the program FORM changes in a way that needs a `migrate_vN→vN+1`
+ *   function. Programs with no `programSchemaVersion` are treated as v0 (oldest).
+ * - `ENGINE_VERSION` (SEMANTICS / PROVENANCE): the version of the runtime engine.
+ *   A monotonic integer bumped by hand whenever the engine's runtime semantics
+ *   meaningfully change (e.g. a new wait model ships) — NOT a per-opcode switch:
+ *   the engine always applies the current semantics to every program. Stamped on
+ *   each run purely for debug ("which engine produced this screenshot").
+ *
+ * Both are orthogonal to `ExecutionProgram.programVersion`, which is a CONTENT
+ * revision counter bumped only by the healer (see program-patcher.ts).
+ */
+export declare const CURRENT_PROGRAM_SCHEMA_VERSION = 1;
+export declare const ENGINE_VERSION = 1;

package/dist/engine-version.js

@@ -0,0 +1,25 @@
+/**
+ * AutoKap Engine — version axes (pure constants, safe on any runtime).
+ *
+ * Kept free of Node-only imports (no `node:module`/`package.json` reads) so it
+ * can be pulled into the schema validation chain that the web app bundles. The
+ * npm package version lives separately in version.ts (`APP_VERSION`).
+ *
+ * Two axes, both decoupled from the npm package version and from each other:
+ *
+ * - `CURRENT_PROGRAM_SCHEMA_VERSION` (FORM): the shape of an `ExecutionProgram`.
+ *   Drives migrate-on-read (program-migrations.ts). A monotonic integer bumped
+ *   whenever the program FORM changes in a way that needs a `migrate_vN→vN+1`
+ *   function. Programs with no `programSchemaVersion` are treated as v0 (oldest).
+ * - `ENGINE_VERSION` (SEMANTICS / PROVENANCE): the version of the runtime engine.
+ *   A monotonic integer bumped by hand whenever the engine's runtime semantics
+ *   meaningfully change (e.g. a new wait model ships) — NOT a per-opcode switch:
+ *   the engine always applies the current semantics to every program. Stamped on
+ *   each run purely for debug ("which engine produced this screenshot").
+ *
+ * Both are orthogonal to `ExecutionProgram.programVersion`, which is a CONTENT
+ * revision counter bumped only by the healer (see program-patcher.ts).
+ */
+export const CURRENT_PROGRAM_SCHEMA_VERSION = 1;
+export const ENGINE_VERSION = 1;
+//# sourceMappingURL=engine-version.js.map

package/dist/execution-schema.d.ts

@@ -1092,6 +1092,7 @@ export declare const PreconditionSpecSchema: z.ZodObject<{
         domain: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    scenario: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const ArtifactSpecSchema: z.ZodObject<{
     mediaMode: z.ZodEnum<{
@@ -1131,6 +1132,8 @@ export declare const ArtifactSpecSchema: z.ZodObject<{
 export declare const ExecutionProgramSchema: z.ZodObject<{
     presetId: z.ZodString;
     programVersion: z.ZodNumber;
+    programSchemaVersion: z.ZodOptional<z.ZodNumber>;
+    engineVersion: z.ZodOptional<z.ZodNumber>;
     mediaMode: z.ZodEnum<{
         video: "video";
         clip: "clip";
@@ -1241,6 +1244,7 @@ export declare const ExecutionProgramSchema: z.ZodObject<{
             domain: z.ZodString;
             path: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
+        scenario: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         url: z.ZodString;
@@ -4202,6 +4206,7 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
             domain: string;
             path?: string | undefined;
         }[] | undefined;
+        scenario?: string | undefined;
     };
     steps: ({
         urlPattern: string;
@@ -4911,6 +4916,8 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
     };
     compileFingerprint: string;
     compiledAt: string;
+    programSchemaVersion?: number | undefined;
+    engineVersion?: number | undefined;
     maxParallelCaptures?: number | undefined;
     outputScale?: number | undefined;
     variantFingerprint?: string | undefined;
@@ -4930,3 +4937,18 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
     publicUrl?: string | undefined;
     environmentHttpHeaders?: Record<string, string> | undefined;
 }>;
+export interface ClipNavigationViolation {
+    /** Index of the offending NAVIGATE opcode in `program.steps`. */
+    stepIndex: number;
+    message: string;
+}
+/**
+ * Returns every NAVIGATE opcode located between a BEGIN_CLIP and its END_CLIP.
+ * Pure and mode-agnostic — mirrors the runtime clip window exactly.
+ */
+export declare function findNavigateInClipViolations(program: Pick<ExecutionProgram, 'steps'>): ClipNavigationViolation[];
+/**
+ * Hard-rejection variant for authoring boundaries (preset create/update).
+ * Throws with an actionable message if any NAVIGATE sits inside a clip.
+ */
+export declare function assertNoNavigateInClip(program: Pick<ExecutionProgram, 'steps'>): void;