autokap 1.3.15 → 1.3.17

package/dist/browser.d.ts

@@ -99,6 +99,20 @@ export declare class Browser {
     private elementMap;
     private akNodeIndex;
     private poolContext;
+    /**
+     * Xvfb instance backing the headed Chromium used by clip capture on Cloud
+     * Run with NVIDIA L4. Set when forClipCapture spawns Xvfb; null otherwise
+     * (Mac/Win and local Linux use headless Playwright). Lifetime matches the
+     * browser process — closeContext() leaves it alone, close() tears it down.
+     */
+    private xvfb;
+    /** Public read access for the clip recorder (needs the DISPLAY string). */
+    get xvfbDisplay(): string | null;
+    /** Viewport size used for clip capture region (matches Xvfb screen). */
+    get viewport(): {
+        width: number;
+        height: number;
+    };
     constructor(options: BrowserOptions);
     /**
      * Create a Browser using the shared pool (server/web API mode).

package/dist/browser.js

@@ -99,6 +99,7 @@ function resolveEffectivePadding(config, bbox) {
 import { CAPTURE_HIDE_STYLE_ID, dismissCookiesAndWidgets, ensureCaptureHideStyles, getCaptureHideCSS, } from './cookie-dismiss.js';
 import { CHROMIUM_ARGS, browserPool } from './browser-pool.js';
 import { isDebugEnabled, logger } from './logger.js';
+import { XvfbProcess } from './xvfb-process.js';
 async function withHelperTimeout(label, timeoutMs, work) {
     if (!timeoutMs || timeoutMs <= 0) {
         return work();
@@ -775,6 +776,17 @@ export class Browser {
     elementMap = new Map();
     akNodeIndex = new Map();
     poolContext = false;
+    /**
+     * Xvfb instance backing the headed Chromium used by clip capture on Cloud
+     * Run with NVIDIA L4. Set when forClipCapture spawns Xvfb; null otherwise
+     * (Mac/Win and local Linux use headless Playwright). Lifetime matches the
+     * browser process — closeContext() leaves it alone, close() tears it down.
+     */
+    xvfb = null;
+    /** Public read access for the clip recorder (needs the DISPLAY string). */
+    get xvfbDisplay() { return this.xvfb?.display ?? null; }
+    /** Viewport size used for clip capture region (matches Xvfb screen). */
+    get viewport() { return this.options.viewport; }
     constructor(options) {
         this.options = options;
     }
@@ -850,17 +862,49 @@ export class Browser {
                 '--enable-zero-copy',
             ]
             : [];
+        // Cloud Run Linux + GPU: spawn Xvfb so headed Chromium has a display to
+        // render into, and ffmpeg x11grab can capture that framebuffer directly
+        // (the FfmpegX11Recorder + h264_nvenc encoding path used by clip recording).
+        // The CDP Page.captureScreenshot path on cloud topped out at 9 fps even
+        // with the GPU compositor active because libjpeg-turbo CPU encode + CDP
+        // transport overhead pinned per-frame cost at ~85 ms. Capturing the X
+        // framebuffer with NVENC bypasses both costs.
+        const xvfbWidth = Math.round(options.viewport.width);
+        const xvfbHeight = Math.round(options.viewport.height);
+        if (isLinuxWithGpu) {
+            instance.xvfb = new XvfbProcess({
+                displayNumber: 99,
+                width: xvfbWidth,
+                height: xvfbHeight,
+            });
+            await instance.xvfb.start();
+            // Chromium picks up DISPLAY from the parent process env. ffmpeg will
+            // read the same display via FfmpegX11RecorderOptions.
+            process.env.DISPLAY = instance.xvfb.display;
+            logger.info(`[capture] Cloud clip capture: Chromium → Xvfb ${instance.xvfb.display} → ffmpeg x11grab + h264_nvenc path enabled`);
+        }
+        // Kiosk + zero-position anchor for Xvfb: Chromium normally renders its
+        // own toolbar/tabbar in headed mode, which would appear at the top of
+        // every clip. `--kiosk` removes all UI; `--window-position=0,0` and
+        // `--window-size` make the page fill the Xvfb screen exactly.
+        const xvfbWindowArgs = isLinuxWithGpu ? [
+            '--kiosk',
+            '--window-position=0,0',
+        ] : [];
         const clipArgs = [
             ...baseArgs,
             `--force-device-scale-factor=${deviceScaleFactor}`,
-            `--window-size=${Math.round(options.viewport.width)},${Math.round(options.viewport.height)}`,
+            `--window-size=${xvfbWidth},${xvfbHeight}`,
             ...(angleArg ? [angleArg] : []),
             ...cloudGpuArgs,
+            ...xvfbWindowArgs,
         ];
         // Dedicated browser process for clip capture. Not pooled because clip
         // capture installs context-level init scripts (cursor overlay).
+        // Cloud Run with Xvfb: launch headed (headless: false) so Chromium
+        // renders to the Xvfb framebuffer that ffmpeg captures.
         instance.browser = await chromium.launch({
-            headless: !options.headed,
+            headless: isLinuxWithGpu ? false : !options.headed,
             args: clipArgs,
         });
         const contextOptions = {
@@ -1096,6 +1140,17 @@ export class Browser {
             this.context = null;
             this.page = null;
         }
+        // Tear down Xvfb only after Chromium is fully gone — Chromium needs the
+        // X display for its own teardown (releasing GL contexts, X resources).
+        if (this.xvfb) {
+            try {
+                await this.xvfb.stop();
+            }
+            catch (err) {
+                logger.warn(`[xvfb] stop failed: ${err.message}`);
+            }
+            this.xvfb = null;
+        }
     }
     async navigateTo(url) {
         const page = this.ensurePage();

package/dist/clip-capture-loop.js

@@ -45,7 +45,13 @@ export class ClipCaptureLoop {
         const targetFps = Math.max(1, Math.min(30, opts.targetFps ?? platformDefault));
         this.targetFps = targetFps;
         this.targetFrameIntervalMs = 1000 / targetFps;
-        const linuxMinRest = isCloudRunner ? 16 : 50;
+        // minRestMs adds a forced sleep after each frame, intended to yield the
+        // event loop on slow runners. With Cloud Run + L4 GPU, CDP capture itself
+        // takes ~85ms, so ANY non-zero minRestMs caps observed FPS below the
+        // already-low CDP ceiling (16ms forced rest = 9.9 fps cap, matched the
+        // 1.3.15 plateau exactly). Drop to 0 on cloud — the await on the next
+        // CDP send already yields the loop.
+        const linuxMinRest = isCloudRunner ? 0 : 50;
         const platformMinRest = process.platform === 'linux' ? linuxMinRest : 16;
         this.minRestMs = Math.max(0, Math.min(250, opts.minRestMs ?? platformMinRest));
     }

package/dist/ffmpeg-x11-recorder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ffmpeg x11grab recorder with NVIDIA NVENC hardware encoder.
+ *
+ * Captures the Xvfb virtual display directly with `ffmpeg -f x11grab` at a
+ * fixed framerate, encoded straight to MP4 via `h264_nvenc` running on the
+ * Cloud Run NVIDIA L4 GPU. Decouples clip recording from Chromium's
+ * compositor speed AND from the CPU JPEG encoder that capped the previous
+ * CDP `Page.captureScreenshot` path at ~9 fps.
+ *
+ * Why this works on Cloud Run when v1.3.10 (libx264) didn't:
+ *   - v1.3.10 used CPU encoder (libx264) which competed with Chromium for
+ *     vCPU on the same machine, giving 1.83 fps.
+ *   - h264_nvenc offloads the entire encode to dedicated NVIDIA NVENC silicon
+ *     on the L4 (separate from CUDA cores). Encode is essentially free CPU-side.
+ *   - The L4 has 2× NVENC blocks and can sustain multiple 4K streams in
+ *     parallel, so 1440x900@30fps is trivial.
+ *
+ * Lifecycle: one recorder instance per BEGIN_CLIP/END_CLIP. Xvfb itself
+ * runs for the whole browser process lifetime.
+ *
+ * Refs:
+ *   - https://docs.cloud.google.com/run/docs/tutorials/video-encoding
+ *   - https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/ffmpeg-with-nvidia-gpu/index.html
+ */
+export interface FfmpegX11RecorderOptions {
+    /** DISPLAY string (e.g. `:99`). */
+    display: string;
+    /** Capture region width in pixels. Should match Xvfb screen width. */
+    width: number;
+    /** Capture region height in pixels. Should match Xvfb screen height. */
+    height: number;
+    /** Target framerate. */
+    fps: number;
+    /** Absolute path to the output .mp4 file. */
+    outputPath: string;
+}
+export interface FfmpegX11RecorderResult {
+    outputPath: string;
+    trimStartMs: number;
+    durationMs: number;
+}
+export declare class FfmpegX11Recorder {
+    private readonly opts;
+    private process;
+    private startedAt;
+    private firstFrameAt;
+    private lastReportedFrameLine;
+    private stderrTail;
+    constructor(opts: FfmpegX11RecorderOptions);
+    start(): Promise<void>;
+    stop(): Promise<FfmpegX11RecorderResult>;
+}

package/dist/ffmpeg-x11-recorder.js

@@ -0,0 +1,193 @@
+/**
+ * ffmpeg x11grab recorder with NVIDIA NVENC hardware encoder.
+ *
+ * Captures the Xvfb virtual display directly with `ffmpeg -f x11grab` at a
+ * fixed framerate, encoded straight to MP4 via `h264_nvenc` running on the
+ * Cloud Run NVIDIA L4 GPU. Decouples clip recording from Chromium's
+ * compositor speed AND from the CPU JPEG encoder that capped the previous
+ * CDP `Page.captureScreenshot` path at ~9 fps.
+ *
+ * Why this works on Cloud Run when v1.3.10 (libx264) didn't:
+ *   - v1.3.10 used CPU encoder (libx264) which competed with Chromium for
+ *     vCPU on the same machine, giving 1.83 fps.
+ *   - h264_nvenc offloads the entire encode to dedicated NVIDIA NVENC silicon
+ *     on the L4 (separate from CUDA cores). Encode is essentially free CPU-side.
+ *   - The L4 has 2× NVENC blocks and can sustain multiple 4K streams in
+ *     parallel, so 1440x900@30fps is trivial.
+ *
+ * Lifecycle: one recorder instance per BEGIN_CLIP/END_CLIP. Xvfb itself
+ * runs for the whole browser process lifetime.
+ *
+ * Refs:
+ *   - https://docs.cloud.google.com/run/docs/tutorials/video-encoding
+ *   - https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/ffmpeg-with-nvidia-gpu/index.html
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import { logger } from './logger.js';
+const FFMPEG_FIRST_FRAME_TIMEOUT_MS = 5_000;
+const FFMPEG_FIRST_FRAME_POLL_MS = 50;
+const FFMPEG_GRACEFUL_STOP_MS = 3_000;
+const FFMPEG_FORCE_STOP_MS = 2_000;
+export class FfmpegX11Recorder {
+    opts;
+    process = null;
+    startedAt = 0;
+    firstFrameAt = 0;
+    lastReportedFrameLine = null;
+    stderrTail = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async start() {
+        if (this.process)
+            throw new Error('ffmpeg x11grab already running');
+        const { display, width, height, fps, outputPath } = this.opts;
+        // -draw_mouse 0: hide the X cursor — the cursor overlay script paints a
+        //   fake cursor in the DOM that's already captured via the page.
+        // -c:v h264_nvenc: NVIDIA hardware encoder. Eliminates CPU contention
+        //   with Chromium that pinned v1.3.10 (libx264) at 1.83 fps.
+        // -preset p4 + -tune ll: NVENC preset 4 (balanced) with low-latency
+        //   tuning. p1 is fastest but lower quality, p7 is highest quality but
+        //   slower. p4 is the standard real-time recording preset per NVIDIA's
+        //   FFmpeg+GPU guide. -tune ll skips B-frames and sets LL-friendly
+        //   reference patterns so each frame can be encoded independently.
+        // -rc cbr -b:v 5M: constant bitrate 5 Mbps — produces smooth quality
+        //   for screen content at 1440x900. CRF/CQ modes are CPU-side only;
+        //   NVENC supports CBR/VBR/cqp.
+        // -pix_fmt yuv420p + +faststart: maximum playback compatibility (Safari,
+        //   QuickTime, browser <video>). NVENC ingests RGBA from x11grab and
+        //   converts internally.
+        const args = [
+            '-y',
+            '-loglevel', 'warning',
+            '-stats',
+            '-f', 'x11grab',
+            '-draw_mouse', '0',
+            '-framerate', String(fps),
+            '-video_size', `${width}x${height}`,
+            '-i', `${display}.0+0,0`,
+            '-c:v', 'h264_nvenc',
+            '-preset', 'p4',
+            '-tune', 'll',
+            '-rc', 'cbr',
+            '-b:v', '5M',
+            '-pix_fmt', 'yuv420p',
+            '-movflags', '+faststart',
+            outputPath,
+        ];
+        // The cloud-runner image ships ONE ffmpeg binary at /usr/local/bin built
+        // from BtbN/FFmpeg-Builds with both x11grab AND h264_nvenc enabled.
+        // AUTOKAP_FFMPEG_X11_BIN can override for local testing or alternate
+        // builds. Falls back to PATH ffmpeg.
+        const ffmpegBin = process.env.AUTOKAP_FFMPEG_X11_BIN || 'ffmpeg';
+        logger.info(`[ffmpeg-x11] starting capture on ${display} → ${outputPath} (${width}×${height} @ ${fps}fps, encoder=h264_nvenc, bin=${ffmpegBin})`);
+        this.startedAt = performance.now();
+        // stdin is `pipe` so we can send 'q' for graceful shutdown (writes the
+        // moov atom; SIGTERM produces an unplayable file).
+        this.process = spawn(ffmpegBin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let exited = false;
+        let exitError = null;
+        this.process.stderr?.on('data', (chunk) => {
+            const text = String(chunk);
+            this.stderrTail.push(text);
+            // Cap retained stderr at ~10 KB to avoid unbounded memory growth on
+            // long recordings.
+            while (this.stderrTail.join('').length > 10_000) {
+                this.stderrTail.shift();
+            }
+            // ffmpeg's progress lines look like: `frame=   42 fps=30 q=23 size= ...`
+            // First non-zero `frame=` value signals capture is actually streaming.
+            if (this.firstFrameAt === 0 && /frame=\s*[1-9]/.test(text)) {
+                this.firstFrameAt = performance.now();
+            }
+            // Track the latest progress line for the final summary log.
+            const match = text.match(/frame=\s*\d+\s+fps=[\d.]+\s+[^\n]+/);
+            if (match)
+                this.lastReportedFrameLine = match[0].trim();
+        });
+        this.process.on('exit', (code, signal) => {
+            exited = true;
+            const wasGracefulStop = signal === 'SIGTERM' || signal === 'SIGINT' || code === 0;
+            if (!wasGracefulStop && code !== null) {
+                exitError = new Error(`ffmpeg exited unexpectedly: code=${code} signal=${signal}\n` +
+                    `Last stderr:\n${this.stderrTail.join('').slice(-2_000)}`);
+            }
+        });
+        this.process.on('error', (err) => {
+            exitError = new Error(`ffmpeg spawn error: ${err.message}`);
+        });
+        // Wait for the first frame to confirm x11grab connected to Xvfb and
+        // encoding has begun. If ffmpeg dies before this, propagate the error.
+        const waitStartedAt = Date.now();
+        while (Date.now() - waitStartedAt < FFMPEG_FIRST_FRAME_TIMEOUT_MS) {
+            if (exited) {
+                throw exitError ?? new Error(`ffmpeg exited before first frame:\n${this.stderrTail.join('').slice(-2_000)}`);
+            }
+            if (this.firstFrameAt > 0) {
+                logger.info(`[ffmpeg-x11] capturing — first frame after ${Math.round(this.firstFrameAt - this.startedAt)}ms`);
+                return;
+            }
+            await new Promise(r => setTimeout(r, FFMPEG_FIRST_FRAME_POLL_MS));
+        }
+        throw new Error(`ffmpeg did not produce first frame within ${FFMPEG_FIRST_FRAME_TIMEOUT_MS}ms\n` +
+            `Last stderr:\n${this.stderrTail.join('').slice(-2_000)}`);
+    }
+    async stop() {
+        if (!this.process)
+            throw new Error('ffmpeg x11grab not running');
+        const proc = this.process;
+        this.process = null;
+        // 'q' → ffmpeg writes the moov atom and exits cleanly. SIGTERM/SIGKILL
+        // would corrupt the MP4 (no moov, unplayable in browsers).
+        try {
+            proc.stdin?.write('q');
+            proc.stdin?.end();
+        }
+        catch { /* stdin may already be closed */ }
+        await new Promise(resolve => {
+            const sigtermTimer = setTimeout(() => {
+                logger.warn(`[ffmpeg-x11] did not exit within ${FFMPEG_GRACEFUL_STOP_MS}ms — sending SIGTERM`);
+                try {
+                    proc.kill('SIGTERM');
+                }
+                catch { /* already dead */ }
+                const sigkillTimer = setTimeout(() => {
+                    try {
+                        proc.kill('SIGKILL');
+                    }
+                    catch { /* already dead */ }
+                    resolve();
+                }, FFMPEG_FORCE_STOP_MS);
+                proc.on('exit', () => { clearTimeout(sigkillTimer); resolve(); });
+            }, FFMPEG_GRACEFUL_STOP_MS);
+            proc.on('exit', () => { clearTimeout(sigtermTimer); resolve(); });
+        });
+        const stoppedAt = performance.now();
+        const trimStartMs = this.firstFrameAt > 0
+            ? Math.max(0, this.firstFrameAt - this.startedAt)
+            : 0;
+        const durationMs = stoppedAt - this.startedAt;
+        let fileSize = 0;
+        try {
+            const stat = await fs.stat(this.opts.outputPath);
+            fileSize = stat.size;
+            if (fileSize === 0) {
+                throw new Error(`ffmpeg produced 0-byte file at ${this.opts.outputPath}`);
+            }
+        }
+        catch (err) {
+            throw new Error(`ffmpeg output unreadable: ${err.message}\n` +
+                `Last stderr:\n${this.stderrTail.join('').slice(-2_000)}`);
+        }
+        logger.info(`[ffmpeg-x11] finalized: ${(fileSize / 1024).toFixed(1)} KB, ` +
+            `${(durationMs / 1000).toFixed(2)}s wall, trim ${Math.round(trimStartMs)}ms` +
+            (this.lastReportedFrameLine ? ` (${this.lastReportedFrameLine})` : ''));
+        return {
+            outputPath: this.opts.outputPath,
+            trimStartMs,
+            durationMs,
+        };
+    }
+}
+//# sourceMappingURL=ffmpeg-x11-recorder.js.map

package/dist/web-playwright-local.js

@@ -11,6 +11,7 @@ import { humanType, moveMouse, } from './mouse-animation.js';
 import { resolveTarget } from './semantic-resolver.js';
 import { logger } from './logger.js';
 import { ClipCaptureLoop } from './clip-capture-loop.js';
+import { FfmpegX11Recorder } from './ffmpeg-x11-recorder.js';
 import { assembleMp4FromFrames, getMediaDurationMs } from './clip-postprocess.js';
 export class WebPlaywrightLocal {
     browser;
@@ -352,23 +353,51 @@ export class WebPlaywrightLocal {
         const cloudClipFps = isCloudRunner ? 30 : defaultFps;
         const targetFps = options.captureFps
             ?? (options.mediaMode === 'video' ? 30 : cloudClipFps);
-        const loop = new ClipCaptureLoop({
-            page,
-            framesDir,
-            targetFps,
-            // Cloud runners have CPU headroom — drop the Linux 50 ms idle cushion
-            // (sized for tight CI runners) to let the loop stay close to its target.
-            minRestMs: process.platform === 'linux' && !isCloudRunner ? 50 : 16,
-        });
-        await loop.start();
-        this.recording = {
-            mediaMode: options.mediaMode,
-            startedAt: Date.now(),
-            framesDir,
-            mp4Path: path.join(baseDir, `${options.mediaMode}.mp4`),
-            loop,
-            finalized: false,
-        };
+        const mp4Path = path.join(baseDir, `${options.mediaMode}.mp4`);
+        // Cloud Run + NVIDIA L4: capture the Xvfb framebuffer with ffmpeg x11grab
+        // and encode via h264_nvenc on the GPU. Bypasses both the CDP transport
+        // overhead and the libjpeg-turbo CPU encode that capped CDP screenshot
+        // capture at 9 fps. The Browser instance spawns Xvfb in forClipCapture
+        // when AUTOKAP_CLOUD_RUNNER=1; xvfbDisplay is the gating signal.
+        const xvfbDisplay = this.browser.xvfbDisplay;
+        if (isCloudRunner && xvfbDisplay) {
+            const viewport = this.browser.viewport;
+            const ffmpegRecorder = new FfmpegX11Recorder({
+                display: xvfbDisplay,
+                width: Math.round(viewport.width),
+                height: Math.round(viewport.height),
+                fps: targetFps,
+                outputPath: mp4Path,
+            });
+            await ffmpegRecorder.start();
+            this.recording = {
+                mediaMode: options.mediaMode,
+                startedAt: Date.now(),
+                framesDir,
+                mp4Path,
+                ffmpegRecorder,
+                finalized: false,
+            };
+        }
+        else {
+            const loop = new ClipCaptureLoop({
+                page,
+                framesDir,
+                targetFps,
+                // Cloud runners have CPU headroom — drop the Linux 50 ms idle cushion
+                // (sized for tight CI runners) to let the loop stay close to its target.
+                minRestMs: process.platform === 'linux' && !isCloudRunner ? 50 : 16,
+            });
+            await loop.start();
+            this.recording = {
+                mediaMode: options.mediaMode,
+                startedAt: Date.now(),
+                framesDir,
+                mp4Path,
+                loop,
+                finalized: false,
+            };
+        }
         this.clipCursor = {
             currentPosition: null,
             pace: options.mediaMode === 'video' ? 'natural' : 'fast',
@@ -461,6 +490,32 @@ export class WebPlaywrightLocal {
             this.recordingNavWatcher.detach();
             this.recordingNavWatcher = null;
         }
+        // Cloud Run + NVENC path: ffmpeg has been recording the Xvfb framebuffer
+        // straight to MP4. stop() finalizes the moov atom; the file is already a
+        // playable H.264/AAC MP4. No JPEG concat needed.
+        if (this.recording.ffmpegRecorder) {
+            const ffmpegResult = await this.recording.ffmpegRecorder.stop();
+            logger.info(`[capture] Clip ffmpeg+nvenc capture: ${(ffmpegResult.durationMs / 1000).toFixed(2)}s wall, ` +
+                `trim ${Math.round(ffmpegResult.trimStartMs)}ms, output ${ffmpegResult.outputPath}`);
+            await this.browser.closeContext();
+            this.recording.finalized = true;
+            this.recording.ffmpegResult = ffmpegResult;
+            this.recording.sourcePath = ffmpegResult.outputPath;
+            this.recording.sourceMimeType = 'video/mp4';
+            this.recording.trimStartMs = ffmpegResult.trimStartMs;
+            this.recording.encodedDurationMs = await getMediaDurationMs(ffmpegResult.outputPath);
+            this.clipCursor = null;
+            const buffer = await fs.readFile(ffmpegResult.outputPath);
+            return {
+                buffer,
+                durationMs: this.recording.encodedDurationMs,
+                mimeType: 'video/mp4',
+                trimStartMs: ffmpegResult.trimStartMs,
+            };
+        }
+        if (!this.recording.loop) {
+            throw new Error('recording started without a loop or ffmpeg recorder');
+        }
         const result = await this.recording.loop.stop();
         logger.info(`[capture] Clip frame capture: ${result.frameCount} frame(s), ` +
             `${result.measuredFps.toFixed(1)} fps over ${(result.actualDurationMs / 1000).toFixed(2)}s ` +

package/dist/xvfb-process.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Xvfb (X virtual framebuffer) process wrapper.
+ *
+ * Spins up a virtual X display that headed Chromium can render to. Used by
+ * cloud clip capture so the recording surface is reachable by ffmpeg via
+ * `x11grab` — bypassing the slow `Page.captureScreenshot` CDP path that
+ * software-rasterized Linux compositors cap at ~6 fps on heavy React UIs.
+ *
+ * Lifecycle: Xvfb runs for the entire browser process lifetime. ffmpeg
+ * recording starts/stops per BEGIN_CLIP/END_CLIP and grabs from the same
+ * display.
+ */
+export interface XvfbProcessOptions {
+    /** Display number (without leading colon). E.g. 99 → DISPLAY=:99. */
+    displayNumber: number;
+    /** Screen width in pixels. Should match the Chromium window size. */
+    width: number;
+    /** Screen height in pixels. Should match the Chromium window size. */
+    height: number;
+}
+export declare class XvfbProcess {
+    private readonly opts;
+    private process;
+    private exited;
+    constructor(opts: XvfbProcessOptions);
+    /** DISPLAY string suitable for `process.env.DISPLAY` (e.g. `:99`). */
+    get display(): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/xvfb-process.js

@@ -0,0 +1,103 @@
+/**
+ * Xvfb (X virtual framebuffer) process wrapper.
+ *
+ * Spins up a virtual X display that headed Chromium can render to. Used by
+ * cloud clip capture so the recording surface is reachable by ffmpeg via
+ * `x11grab` — bypassing the slow `Page.captureScreenshot` CDP path that
+ * software-rasterized Linux compositors cap at ~6 fps on heavy React UIs.
+ *
+ * Lifecycle: Xvfb runs for the entire browser process lifetime. ffmpeg
+ * recording starts/stops per BEGIN_CLIP/END_CLIP and grabs from the same
+ * display.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import { logger } from './logger.js';
+const XVFB_READY_TIMEOUT_MS = 5_000;
+const XVFB_READY_POLL_MS = 50;
+const XVFB_STOP_GRACE_MS = 2_000;
+export class XvfbProcess {
+    opts;
+    process = null;
+    exited = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** DISPLAY string suitable for `process.env.DISPLAY` (e.g. `:99`). */
+    get display() {
+        return `:${this.opts.displayNumber}`;
+    }
+    async start() {
+        if (this.process)
+            throw new Error('xvfb already started');
+        // -ac: no access control (any local client can connect)
+        // -screen 0 WxHxDEPTH: screen 0 sized to W×H at 24-bit color
+        // -nolisten tcp: only listen on the Unix socket (no network exposure)
+        // -dpi 96: pin DPI so CSS pixel sizing matches a typical monitor
+        const args = [
+            this.display,
+            '-ac',
+            '-screen', '0', `${this.opts.width}x${this.opts.height}x24`,
+            '-nolisten', 'tcp',
+            '-dpi', '96',
+        ];
+        this.process = spawn('Xvfb', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: false,
+        });
+        this.process.stderr?.on('data', (chunk) => {
+            const text = String(chunk).trim();
+            if (text)
+                logger.warn(`[xvfb] ${text}`);
+        });
+        this.process.on('exit', (code, signal) => {
+            this.exited = true;
+            if (code !== 0 && code !== null) {
+                logger.error(`[xvfb] exited unexpectedly: code=${code} signal=${signal}`);
+            }
+        });
+        this.process.on('error', (err) => {
+            logger.error(`[xvfb] spawn error: ${err.message}`);
+        });
+        // Xvfb signals readiness by creating its Unix socket. Polling that socket
+        // is more reliable than `setTimeout(500)` because cold container starts
+        // are unpredictable.
+        const socketPath = `/tmp/.X11-unix/X${this.opts.displayNumber}`;
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < XVFB_READY_TIMEOUT_MS) {
+            if (this.exited) {
+                throw new Error('Xvfb exited before becoming ready — check stderr above');
+            }
+            try {
+                await fs.access(socketPath);
+                logger.info(`[xvfb] ready on display ${this.display} (${this.opts.width}×${this.opts.height}) ` +
+                    `after ${Date.now() - startedAt}ms`);
+                return;
+            }
+            catch {
+                // socket not yet created — keep polling
+            }
+            await new Promise(r => setTimeout(r, XVFB_READY_POLL_MS));
+        }
+        throw new Error(`Xvfb did not become ready within ${XVFB_READY_TIMEOUT_MS}ms`);
+    }
+    async stop() {
+        if (!this.process)
+            return;
+        const proc = this.process;
+        this.process = null;
+        proc.kill('SIGTERM');
+        await new Promise(resolve => {
+            const timer = setTimeout(() => {
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch { /* already dead */ }
+                resolve();
+            }, XVFB_STOP_GRACE_MS);
+            proc.on('exit', () => { clearTimeout(timer); resolve(); });
+        });
+        logger.info(`[xvfb] stopped (display ${this.display})`);
+    }
+}
+//# sourceMappingURL=xvfb-process.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.3.15",
+  "version": "1.3.17",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",