autokap 1.0.7 → 1.0.10

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

@@ -0,0 +1,63 @@
+import type { Page } from 'playwright';
+import type { RecordingResult } from './execution-types.js';
+import type { ClipOptions } from './types.js';
+interface ScrollOffset {
+    x: number;
+    y: number;
+}
+export declare function buildCdpViewportClip(viewport: {
+    width: number;
+    height: number;
+}, effectiveScale: number, scrollOffset: ScrollOffset): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+};
+export interface FrameSequenceClipRecorderOptions {
+    baseDir?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    requestedScale?: number;
+    effectiveScale: number;
+    clipOptions?: ClipOptions;
+    sourceFps?: number;
+    outputFps?: number;
+}
+export declare class FrameSequenceClipRecorder {
+    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;
+    private cdpCaptureDisabled;
+    constructor(page: Page, options: FrameSequenceClipRecorderOptions);
+    start(): Promise<void>;
+    stop(): Promise<RecordingResult>;
+    abort(): Promise<void>;
+    private runCaptureLoop;
+    private captureFrame;
+    private captureFrameBuffer;
+    private readScrollOffset;
+    private captureFrameViaCdp;
+    private getCdpSession;
+    private disableCdpCapture;
+    private queueFrameWrite;
+    private waitForPendingWriteCapacity;
+    private flushPendingWrites;
+}
+export {};

package/dist/clip-frame-recorder.js

@@ -0,0 +1,305 @@
+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_CLIP_SOURCE_FPS = 30;
+const DEFAULT_CLIP_OUTPUT_FPS = 30;
+const INTERMEDIATE_FRAME_FORMAT = 'jpeg';
+const INTERMEDIATE_FRAME_QUALITY = 80;
+const MAX_PENDING_FRAME_WRITES = 4;
+export function buildCdpViewportClip(viewport, effectiveScale, scrollOffset) {
+    return {
+        x: Math.max(0, scrollOffset.x),
+        y: Math.max(0, scrollOffset.y),
+        width: Math.max(1, Math.round(viewport.width)),
+        height: Math.max(1, Math.round(viewport.height)),
+        scale: Math.max(0.1, effectiveScale),
+    };
+}
+export class FrameSequenceClipRecorder {
+    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;
+    cdpCaptureDisabled = false;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+        this.sourceFps = Math.max(1, Math.round(options.sourceFps ?? DEFAULT_CLIP_SOURCE_FPS));
+        this.outputFps = Math.max(1, Math.round(options.outputFps ?? DEFAULT_CLIP_OUTPUT_FPS));
+        this.workingDirPromise = options.baseDir
+            ? Promise.resolve(options.baseDir)
+            : fs.mkdtemp(path.join(os.tmpdir(), 'autokap-clip-frames-'));
+        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,
+            });
+            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: 'frame_sequence',
+                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')}.jpg`);
+            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] frame capture skipped: ${captureError.message}`);
+        }
+    }
+    async captureFrameBuffer() {
+        const scrollOffset = await this.readScrollOffset();
+        const cdpBuffer = await this.captureFrameViaCdp(scrollOffset);
+        if (cdpBuffer) {
+            return cdpBuffer;
+        }
+        return this.page.screenshot({
+            type: INTERMEDIATE_FRAME_FORMAT,
+            quality: INTERMEDIATE_FRAME_QUALITY,
+            fullPage: false,
+            scale: 'device',
+        });
+    }
+    async readScrollOffset() {
+        try {
+            return await this.page.evaluate(() => ({
+                x: window.scrollX || window.pageXOffset || 0,
+                y: window.scrollY || window.pageYOffset || 0,
+            }));
+        }
+        catch {
+            return { x: 0, y: 0 };
+        }
+    }
+    async captureFrameViaCdp(scrollOffset) {
+        const session = await this.getCdpSession();
+        if (!session) {
+            return null;
+        }
+        try {
+            const screenshot = await session.send('Page.captureScreenshot', {
+                format: INTERMEDIATE_FRAME_FORMAT,
+                quality: INTERMEDIATE_FRAME_QUALITY,
+                optimizeForSpeed: true,
+                clip: buildCdpViewportClip(this.options.viewport, this.options.effectiveScale, scrollOffset),
+            });
+            return Buffer.from(screenshot.data, 'base64');
+        }
+        catch (error) {
+            this.disableCdpCapture(error);
+            return null;
+        }
+    }
+    async getCdpSession() {
+        if (this.cdpCaptureDisabled) {
+            return null;
+        }
+        if (this.cdpSession) {
+            return this.cdpSession;
+        }
+        if (!this.cdpSessionPromise) {
+            this.cdpSessionPromise = (async () => {
+                try {
+                    const context = this.page.context();
+                    if (typeof context.newCDPSession !== 'function') {
+                        this.cdpCaptureDisabled = true;
+                        return null;
+                    }
+                    this.cdpSession = await context.newCDPSession(this.page);
+                    return this.cdpSession;
+                }
+                catch (error) {
+                    this.disableCdpCapture(error);
+                    return null;
+                }
+            })();
+        }
+        return this.cdpSessionPromise;
+    }
+    disableCdpCapture(error) {
+        if (!this.cdpCaptureDisabled) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.debug(`[clip] CDP frame capture unavailable, falling back to Playwright screenshot: ${message}`);
+        }
+        this.cdpCaptureDisabled = true;
+        this.cdpSessionPromise = Promise.resolve(null);
+    }
+    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-frame-recorder.js.map

package/dist/clip-orchestrator.js

@@ -1,4 +1,4 @@
-import { mkdtemp } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { logger } from './logger.js';
@@ -891,8 +891,9 @@ async function runClipVariantAttempt(clip, target, lang, theme, navResult, confi
         clipOptions,
         parentSignal: config.abortSignal,
         run: async (_signal, _attempt, _phaseContext) => {
+            let outputDir = null;
             try {
-                const outputDir = await mkdtemp(path.join(os.tmpdir(), `clip-${clip.id}-`));
+                outputDir = await mkdtemp(path.join(os.tmpdir(), `clip-${clip.id}-`));
                 const outputScale = config.outputScale ?? 1;
                 const postResult = await postProcessClipRecording(recordResult.videoPath, outputDir, `${clip.id}_${variantId.replace(/:/g, '_')}`, {
                     ...clipOptions,
@@ -906,6 +907,12 @@ async function runClipVariantAttempt(clip, target, lang, theme, navResult, confi
                 logger.error(`Post-processing failed for clip "${clip.name}" variant ${variantId}: ${err.message}`);
                 return { ok: false, reason: `Post-processing failed: ${err.message}` };
             }
+            finally {
+                // Clean up temp directory to avoid orphaned files
+                if (outputDir) {
+                    rm(outputDir, { recursive: true, force: true }).catch(() => { });
+                }
+            }
         },
     });
     if (!postprocessPhase.ok) {

package/dist/clip-postprocess.d.ts

@@ -15,11 +15,40 @@ export declare function convertToGif(webmPath: string, outputPath: string, opts?
 /**
  * Convert a WebM recording to an MP4 with web-optimized settings.
  */
-export declare function convertToMp4(webmPath: string, outputPath: string): Promise<void>;
+export declare function convertToMp4(webmPath: string, outputPath: string, opts?: {
+    width?: number;
+    height?: number;
+    trimStartSec?: number;
+    maxDurationSec?: number;
+    holdLastFrameSec?: number;
+    fps?: number;
+}): Promise<void>;
 /**
  * Extract the first frame of a WebM as a PNG thumbnail.
  */
 export declare function extractThumbnail(webmPath: string, outputPath: string): Promise<void>;
+/**
+ * Assemble a sequence of JPEG frames into an H.264 MP4.
+ * Expects frames named `frame_000000.jpg`, `frame_000001.jpg`, ... in framesDir.
+ *
+ * When `frameOffsetsMs` is provided (one offset per frame, ms from first
+ * frame), uses ffmpeg's concat demuxer to preserve the actual capture timing
+ * (VFR). This matters when the compositor is CPU-bound on heavy React UIs:
+ * frames arrive in bursts during idle periods and gaps during paint-heavy
+ * periods. Encoding those at uniform CFR would stretch bursts and compress
+ * gaps — viewers see temporally-distorted playback even though the average
+ * rate is correct. VFR lets each frame hold the screen for its true wall-
+ * clock duration.
+ *
+ * When `frameOffsetsMs` is absent, falls back to CFR at `fps` (useful for
+ * uniform-cadence captures like the synthetic smoke tests).
+ */
+export declare function assembleMp4FromFrames(opts: {
+    framesDir: string;
+    outputPath: string;
+    fps: number;
+    frameOffsetsMs?: number[];
+}): Promise<void>;
 /**
  * Trim a recording: skip dead frames at the start and cap duration.
  */
@@ -37,6 +66,6 @@ export interface ClipPostProcessResult {
 }
 /**
  * Full post-processing pipeline for a single clip recording:
- * trim → GIF and/or MP4 → thumbnail → measure.
+ * encode a normalized master MP4 → derive GIF + thumbnail → measure.
  */
 export declare function postProcessClipRecording(webmPath: string, outputDir: string, clipId: string, options?: ClipOptions): Promise<ClipPostProcessResult>;