autokap 1.0.8 → 1.1.0

package/dist/clip-capture-backend.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { BeginFrameClipRecorder } from './clip-begin-frame-recorder.js';
+import { FrameSequenceClipRecorder } from './clip-frame-recorder.js';
+import { postProcessClipRecording, } from './clip-postprocess.js';
+import { resolvePhysicalCaptureSize } from './clip-scale.js';
+const DEFAULT_PLAYWRIGHT_VIDEO_FPS = 30;
+function applyFallbackReason(result, fallbackReason) {
+    if (!fallbackReason || !result.clipPackage) {
+        return result;
+    }
+    return {
+        ...result,
+        clipPackage: {
+            ...result.clipPackage,
+            fallbackReason,
+        },
+    };
+}
+async function loadPackagedClipResult(output, packagedClip) {
+    if (!output.mp4Path || !output.thumbnailPath) {
+        throw new Error('clip packaging failed: missing MP4 or thumbnail output');
+    }
+    const [mp4Buffer, gifBuffer, thumbnailBuffer] = await Promise.all([
+        fs.readFile(output.mp4Path),
+        output.gifPath ? fs.readFile(output.gifPath) : Promise.resolve(null),
+        fs.readFile(output.thumbnailPath),
+    ]);
+    return {
+        buffer: mp4Buffer,
+        mimeType: 'video/mp4',
+        durationMs: output.durationMs,
+        trimStartMs: 0,
+        clipPackage: {
+            ...packagedClip,
+            mp4: {
+                buffer: mp4Buffer,
+                mimeType: 'video/mp4',
+            },
+            ...(gifBuffer
+                ? {
+                    gif: {
+                        buffer: gifBuffer,
+                        mimeType: 'image/gif',
+                    },
+                }
+                : {}),
+            thumbnail: {
+                buffer: thumbnailBuffer,
+                mimeType: 'image/png',
+            },
+        },
+    };
+}
+async function waitForFile(filePath, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await fs.stat(filePath);
+            return;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, 150));
+        }
+    }
+    throw new Error(`timed out waiting for clip artifact ${filePath}`);
+}
+class FrameSequenceClipCaptureBackend {
+    options;
+    captureMethod = 'frame_sequence';
+    recorder;
+    constructor(options) {
+        this.options = options;
+        this.recorder = new FrameSequenceClipRecorder(options.page, {
+            baseDir: options.recordingDir,
+            viewport: options.viewport,
+            requestedScale: options.requestedScale,
+            effectiveScale: options.effectiveScale,
+            clipOptions: options.clipOptions,
+        });
+    }
+    async start() {
+        await this.recorder.start();
+    }
+    async stop() {
+        const result = await this.recorder.stop();
+        return applyFallbackReason(result, this.options.fallbackReason);
+    }
+    async abort() {
+        await this.recorder.abort();
+    }
+}
+class BeginFrameClipCaptureBackend {
+    options;
+    captureMethod = 'begin_frame';
+    recorder;
+    constructor(options) {
+        this.options = options;
+        this.recorder = new BeginFrameClipRecorder(options.page, {
+            baseDir: options.recordingDir,
+            viewport: options.viewport,
+            requestedScale: options.requestedScale,
+            effectiveScale: options.effectiveScale,
+            clipOptions: options.clipOptions,
+        });
+    }
+    async start() {
+        await this.recorder.start();
+    }
+    async stop() {
+        const result = await this.recorder.stop();
+        return applyFallbackReason(result, this.options.fallbackReason);
+    }
+    async abort() {
+        await this.recorder.abort();
+    }
+}
+class PlaywrightVideoClipCaptureBackend {
+    options;
+    captureMethod = 'playwright_video';
+    startedAtMs = null;
+    workingDirPromise;
+    outputDimensions;
+    constructor(options) {
+        this.options = options;
+        this.workingDirPromise = options.recordingDir
+            ? Promise.resolve(options.recordingDir)
+            : fs.mkdtemp(path.join(os.tmpdir(), 'autokap-clip-webm-'));
+        this.outputDimensions = resolvePhysicalCaptureSize(options.viewport, options.effectiveScale)
+            ?? options.viewport;
+    }
+    async start() {
+        this.startedAtMs = Date.now();
+    }
+    async stop() {
+        const page = this.options.browser.currentPage;
+        const video = page.video();
+        if (!video) {
+            throw new Error('playwright video recording is not available on this browser context');
+        }
+        const workingDir = await this.workingDirPromise;
+        await fs.mkdir(workingDir, { recursive: true });
+        const browserStartedAtMs = this.options.browser.launchedAtMs ?? this.startedAtMs ?? Date.now();
+        const trimStartSec = this.startedAtMs
+            ? Math.max(0, (this.startedAtMs - browserStartedAtMs) / 1000)
+            : 0;
+        try {
+            await this.options.browser.closeContext();
+            const webmPath = await video.path();
+            await waitForFile(webmPath);
+            const packaged = await postProcessClipRecording(webmPath, workingDir, 'clip', {
+                ...this.options.clipOptions,
+                trimStartSec,
+                mp4Width: this.outputDimensions.width,
+                mp4Height: this.outputDimensions.height,
+            });
+            const result = await loadPackagedClipResult(packaged, {
+                captureMethod: 'playwright_video',
+                requestedScale: this.options.requestedScale,
+                effectiveScale: this.options.effectiveScale,
+                sourceFps: DEFAULT_PLAYWRIGHT_VIDEO_FPS,
+                outputFps: DEFAULT_PLAYWRIGHT_VIDEO_FPS,
+                dimensions: this.outputDimensions,
+                fallbackReason: this.options.fallbackReason,
+            });
+            return applyFallbackReason(result, this.options.fallbackReason);
+        }
+        finally {
+            await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async abort() {
+        const workingDir = await this.workingDirPromise;
+        await fs.rm(workingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export function createClipCaptureBackend(options) {
+    switch (options.captureMethod) {
+        case 'begin_frame':
+            return new BeginFrameClipCaptureBackend(options);
+        case 'playwright_video':
+            return new PlaywrightVideoClipCaptureBackend(options);
+        case 'frame_sequence':
+        default:
+            return new FrameSequenceClipCaptureBackend(options);
+    }
+}
+//# sourceMappingURL=clip-capture-backend.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * ClipCaptureLoop — custom CDP Page.captureScreenshot loop.
+ *
+ * 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).
+ *
+ * Frames are buffered in memory during capture (raw base64), then 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
+ * React UIs (frames arrive in bursts + gaps, not uniformly).
+ */
+import type { Page } from 'playwright';
+export interface ClipCaptureLoopOptions {
+    /** Playwright page used to derive the CDP session. */
+    page: Page;
+    /** Absolute path to an existing directory where frames will be written. */
+    framesDir: string;
+    /**
+     * JPEG quality (0-100). Default 80. On 2880×1800, q=80 sustains ~40 FPS on
+     * a modern Mac (vs 30 FPS at q=90) — the quality drop is invisible on screen
+     * content (high-contrast text, flat colors) but unlocks a 33% fluidity gain.
+     */
+    jpegQuality?: number;
+}
+export interface ClipCaptureLoopResult {
+    framesDir: string;
+    frameCount: number;
+    /** (frameCount - 1) * 1000 / (lastTs - firstTs); 0 if < 2 frames. */
+    measuredFps: number;
+    actualDurationMs: number;
+    /** Delay between start() returning and the first frame being written. */
+    trimStartMs: number;
+    /**
+     * Wall-clock offset in milliseconds from the first frame, one entry per
+     * captured frame. Used by assembleMp4FromFrames to preserve real timing
+     * (VFR) instead of encoding at a uniform CFR — critical when capture
+     * throughput varies (heavy page renders pause the compositor while the
+     * loop keeps trying, producing bursts and gaps).
+     */
+    frameOffsetsMs: number[];
+}
+export declare class ClipCaptureLoop {
+    private readonly page;
+    private readonly framesDir;
+    private readonly jpegQuality;
+    private cdp;
+    private running;
+    private loopPromise;
+    private frames;
+    private frameTimestamps;
+    private startedAt;
+    private firstFrameAt;
+    private lastFrameAt;
+    constructor(opts: ClipCaptureLoopOptions);
+    start(): Promise<void>;
+    stop(): Promise<ClipCaptureLoopResult>;
+    private loop;
+}

package/dist/clip-capture-loop.js

@@ -0,0 +1,111 @@
+/**
+ * ClipCaptureLoop — custom CDP Page.captureScreenshot loop.
+ *
+ * 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).
+ *
+ * Frames are buffered in memory during capture (raw base64), then 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
+ * React UIs (frames arrive in bursts + gaps, not uniformly).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export class ClipCaptureLoop {
+    page;
+    framesDir;
+    jpegQuality;
+    cdp = null;
+    running = false;
+    loopPromise = null;
+    frames = [];
+    frameTimestamps = [];
+    startedAt = 0;
+    firstFrameAt = 0;
+    lastFrameAt = 0;
+    constructor(opts) {
+        this.page = opts.page;
+        this.framesDir = opts.framesDir;
+        this.jpegQuality = opts.jpegQuality ?? 80;
+    }
+    async start() {
+        this.cdp = await this.page.context().newCDPSession(this.page);
+        this.startedAt = performance.now();
+        this.running = true;
+        this.loopPromise = this.loop();
+    }
+    async stop() {
+        this.running = false;
+        if (this.loopPromise) {
+            await this.loopPromise;
+            this.loopPromise = null;
+        }
+        if (this.cdp) {
+            try {
+                await this.cdp.detach();
+            }
+            catch {
+                // page/context may already be closed
+            }
+            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'));
+        await Promise.all(writes);
+        const frameCount = this.frames.length;
+        const span = this.lastFrameAt - this.firstFrameAt;
+        const measuredFps = frameCount > 1 && span > 0 ? ((frameCount - 1) * 1000) / span : 0;
+        const actualDurationMs = span > 0 ? span : 0;
+        const trimStartMs = this.firstFrameAt > 0 ? Math.max(0, this.firstFrameAt - this.startedAt) : 0;
+        // Snapshot offsets (ms from first frame) for VFR encoding downstream.
+        const frameOffsetsMs = this.frameTimestamps.map(ts => ts - this.firstFrameAt);
+        // Release memory — the caller owns framesDir from here on.
+        this.frames = [];
+        this.frameTimestamps = [];
+        return {
+            framesDir: this.framesDir,
+            frameCount,
+            measuredFps,
+            actualDurationMs,
+            trimStartMs,
+            frameOffsetsMs,
+        };
+    }
+    async loop() {
+        while (this.running) {
+            if (!this.cdp)
+                return;
+            let data;
+            try {
+                const r = await this.cdp.send('Page.captureScreenshot', {
+                    format: 'jpeg',
+                    quality: this.jpegQuality,
+                    fromSurface: true,
+                    optimizeForSpeed: true,
+                });
+                data = r.data;
+            }
+            catch {
+                // Page may have navigated or context closing. If we're still running,
+                // skip this iteration and retry on next tick. If we're stopping, exit.
+                if (!this.running)
+                    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);
+        }
+    }
+}
+//# sourceMappingURL=clip-capture-loop.js.map

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 {};