autokap 1.3.8 → 1.3.9

package/dist/browser.d.ts

@@ -96,6 +96,7 @@ export declare class Browser {
     private browser;
     private context;
     private page;
+    private xvfb;
     private elementMap;
     private akNodeIndex;
     private poolContext;
@@ -334,6 +335,13 @@ export declare class Browser {
     resizeViewport(width: number, height: number): Promise<void>;
     get currentPage(): Page;
     get browserContext(): BrowserContext;
+    /**
+     * DISPLAY string of the Xvfb virtual screen, when this browser was launched
+     * with one (cloud clip capture path). `null` for headless / Mac / Windows
+     * launches that don't use Xvfb. Consumed by `FfmpegX11Recorder` so it knows
+     * which display to grab.
+     */
+    get xvfbDisplay(): string | null;
     /**
      * Observation pass for mock data generation.
      * Navigates to the given URL, waits for network idle, and records all JSON API responses.

package/dist/browser.js

@@ -98,6 +98,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 { XvfbProcess } from './xvfb-process.js';
 import { isDebugEnabled, logger } from './logger.js';
 async function withHelperTimeout(label, timeoutMs, work) {
     if (!timeoutMs || timeoutMs <= 0) {
@@ -772,6 +773,7 @@ export class Browser {
     browser = null;
     context = null;
     page = null;
+    xvfb = null;
     elementMap = new Map();
     akNodeIndex = new Map();
     poolContext = false;
@@ -810,50 +812,63 @@ export class Browser {
         const instance = new Browser(options);
         const deviceScaleFactor = normalizeDeviceScaleFactor(options.deviceScaleFactor);
         // Enable GPU compositor on non-Linux platforms so Chrome can render
-        // 2880×1800 without saturating the CPU. Linux cloud runners get
-        // SwiftShader (multi-threaded software ANGLE) instead of `--disable-gpu`
-        // because the default CPU rasterizer caps CDP screenshots at ~165 ms each
-        // → 6 fps clips on heavy React pages. SwiftShader's JIT'd SIMD raster
-        // paths use Fly's 8 vCPUs properly (measured: ~5× faster compositor).
-        // Non-cloud Linux (GitHub Actions free runners, 2 vCPU) stays on the
-        // legacy CPU path — SwiftShader has thread-pool overhead that hurts on
-        // tight CI machines.
-        const isCloudRunner = process.env.AUTOKAP_CLOUD_RUNNER === '1';
-        const isLinuxCloud = process.platform === 'linux' && isCloudRunner;
-        const baseArgs = isLinuxCloud || process.platform !== 'linux'
-            ? CHROMIUM_ARGS.filter(arg => arg !== '--disable-gpu' && arg !== '--disable-gpu-sandbox')
-            : CHROMIUM_ARGS;
-        // Pin ANGLE to the platform's fast graphics backend. Chrome's default
+        // 2880×1800 without saturating the CPU. Linux (Docker/CI) keeps
+        // `--disable-gpu` from CHROMIUM_ARGS because GPU is rarely available there.
+        // SwiftShader was attempted for cloud Linux (v1.3.8) but caused GPU
+        // process crashes mid-recording — Playwright's Jammy base lacks the GL
+        // libs SwiftShader expects. Reverted in v1.3.9.
+        const baseArgs = process.platform === 'linux'
+            ? CHROMIUM_ARGS
+            : CHROMIUM_ARGS.filter(arg => arg !== '--disable-gpu' && arg !== '--disable-gpu-sandbox');
+        // Pin ANGLE to the platform's native graphics API. Chrome's default
         // backend is OpenGL on macOS, which is far slower than Metal for the
         // compositor (measured 4 FPS vs 32 FPS at 2880×1800 on a heavy React UI).
-        // Same story on Windows where D3D11 is the native fast path. On Linux
-        // cloud, SwiftShader is the multi-threaded software backend.
+        // Same story on Windows where D3D11 is the native fast path.
         const angleArg = process.platform === 'darwin' ? '--use-angle=metal'
             : process.platform === 'win32' ? '--use-angle=d3d11'
-                : isLinuxCloud ? '--use-angle=swiftshader'
-                    : null;
-        // Cloud-Linux extras: route GL through ANGLE, opt in to SwiftShader
-        // explicitly (Chromium 124+ requires `--enable-unsafe-swiftshader` since
-        // SwiftShader was tagged unsafe for general WebGL — for our headless
-        // captures the security caveat is irrelevant), and bypass the GPU
-        // blocklist that otherwise refuses any GPU path on unrecognized headless
-        // hardware.
-        const linuxCloudGpuArgs = isLinuxCloud ? [
-            '--use-gl=angle',
-            '--enable-unsafe-swiftshader',
-            '--ignore-gpu-blocklist',
+                : null; // Linux: skip — GPU is rarely present in CI anyway
+        // Cloud Linux: spawn Xvfb and run Chromium headed against the virtual
+        // display. ffmpeg `x11grab` will then capture clips directly from Xvfb
+        // at a steady 30 fps, bypassing the slow CDP `Page.captureScreenshot`
+        // path that caps at ~6 fps under software rasterization. Headless
+        // Chromium on Mac/Windows local + Linux CI keeps using the CDP loop.
+        const useXvfb = process.platform === 'linux'
+            && process.env.AUTOKAP_CLOUD_RUNNER === '1'
+            && !options.headed;
+        if (useXvfb) {
+            instance.xvfb = new XvfbProcess({
+                displayNumber: 99,
+                width: Math.round(options.viewport.width),
+                height: Math.round(options.viewport.height),
+            });
+            await instance.xvfb.start();
+            // Chromium reads DISPLAY when launched non-headless — this directs
+            // rendering to the Xvfb framebuffer that ffmpeg will later capture.
+            process.env.DISPLAY = instance.xvfb.display;
+            logger.info(`[capture] Cloud clip capture: Chromium → Xvfb ${instance.xvfb.display} → ffmpeg x11grab path enabled`);
+        }
+        // Kiosk + zero-position anchor for Xvfb: Chromium normally renders its
+        // chrome (toolbar, address bar, tabs) above the page in headed mode.
+        // x11grab captures the whole screen, so the chrome would sit at the top
+        // of every clip. `--kiosk` removes all UI; `--window-position=0,0` and
+        // `--window-size` ensure the page fills the Xvfb screen exactly.
+        const xvfbWindowArgs = useXvfb ? [
+            '--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)}`,
             ...(angleArg ? [angleArg] : []),
-            ...linuxCloudGpuArgs,
+            ...xvfbWindowArgs,
         ];
         // Dedicated browser process for clip capture. Not pooled because clip
         // capture installs context-level init scripts (cursor overlay).
         instance.browser = await chromium.launch({
-            headless: !options.headed,
+            // Headless: false when Xvfb is in play so Chromium actually renders
+            // pixels to the display (headless mode skips that work entirely).
+            headless: useXvfb ? false : !options.headed,
             args: clipArgs,
         });
         const contextOptions = {
@@ -1059,6 +1074,12 @@ export class Browser {
             this.context = null;
             this.page = null;
         }
+        // Tear down Xvfb only after the browser process is gone — Chromium needs
+        // a live display until it exits or it'll spam X errors on shutdown.
+        if (this.xvfb) {
+            await this.xvfb.stop();
+            this.xvfb = null;
+        }
     }
     async navigateTo(url) {
         const page = this.ensurePage();
@@ -5068,6 +5089,15 @@ export class Browser {
     get browserContext() {
         return this.ensureContext();
     }
+    /**
+     * DISPLAY string of the Xvfb virtual screen, when this browser was launched
+     * with one (cloud clip capture path). `null` for headless / Mac / Windows
+     * launches that don't use Xvfb. Consumed by `FfmpegX11Recorder` so it knows
+     * which display to grab.
+     */
+    get xvfbDisplay() {
+        return this.xvfb?.display ?? null;
+    }
     /**
      * Observation pass for mock data generation.
      * Navigates to the given URL, waits for network idle, and records all JSON API responses.

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

@@ -0,0 +1,42 @@
+/**
+ * ffmpeg x11grab recorder.
+ *
+ * Captures the Xvfb virtual display directly with `ffmpeg -f x11grab` at a
+ * fixed framerate, encoded straight to MP4 (libx264). Decouples the clip
+ * recording rate from Chromium's compositor speed — software-rasterized
+ * Linux compositors cap CDP `Page.captureScreenshot` at ~6 fps on heavy
+ * React UIs, which produces choppy clips. With x11grab we get a steady 30
+ * fps; if Chromium is slow to render, ffmpeg simply records the same frame
+ * twice (matches what a user would see on screen).
+ *
+ * Lifecycle: one recorder instance per BEGIN_CLIP/END_CLIP. Xvfb itself
+ * runs for the whole browser process lifetime.
+ */
+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,167 @@
+/**
+ * ffmpeg x11grab recorder.
+ *
+ * Captures the Xvfb virtual display directly with `ffmpeg -f x11grab` at a
+ * fixed framerate, encoded straight to MP4 (libx264). Decouples the clip
+ * recording rate from Chromium's compositor speed — software-rasterized
+ * Linux compositors cap CDP `Page.captureScreenshot` at ~6 fps on heavy
+ * React UIs, which produces choppy clips. With x11grab we get a steady 30
+ * fps; if Chromium is slow to render, ffmpeg simply records the same frame
+ * twice (matches what a user would see on screen).
+ *
+ * Lifecycle: one recorder instance per BEGIN_CLIP/END_CLIP. Xvfb itself
+ * runs for the whole browser process lifetime.
+ */
+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.
+        // -preset ultrafast + -crf 20: encode in real time on 8 vCPU; CRF 20 is
+        //   high quality (clip artifacts are visible at 28+).
+        // -pix_fmt yuv420p + +faststart: maximum playback compatibility (Safari,
+        //   QuickTime, browser <video>).
+        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', 'libx264',
+            '-preset', 'ultrafast',
+            '-crf', '20',
+            '-pix_fmt', 'yuv420p',
+            '-movflags', '+faststart',
+            outputPath,
+        ];
+        logger.info(`[ffmpeg-x11] starting capture on ${display} → ${outputPath} (${width}×${height} @ ${fps}fps)`);
+        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('ffmpeg', 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

@@ -12,6 +12,7 @@ import { resolveTarget } from './semantic-resolver.js';
 import { logger } from './logger.js';
 import { ClipCaptureLoop } from './clip-capture-loop.js';
 import { assembleMp4FromFrames, getMediaDurationMs } from './clip-postprocess.js';
+import { FfmpegX11Recorder } from './ffmpeg-x11-recorder.js';
 export class WebPlaywrightLocal {
     browser;
     recordingDir;
@@ -352,21 +353,52 @@ 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();
+        // Cloud Linux clip recording goes through Xvfb + ffmpeg x11grab. The CDP
+        // `Page.captureScreenshot` loop caps at ~6 fps on heavy React UIs because
+        // each capture waits for a full compositor frame, and software-rasterized
+        // Linux compositors are slow. x11grab decouples capture rate from
+        // compositor speed: when Chromium is slow ffmpeg just records the same
+        // pixels twice (matches what a user would actually see). Other paths
+        // (Mac/Windows local, Linux CI) keep the CDP loop — it's faster there
+        // because Metal/D3D11/DRI compositors render at full rate.
+        const xvfbDisplay = this.browser.xvfbDisplay;
+        const useX11Capture = options.mediaMode === 'clip' && xvfbDisplay !== null;
+        let loop = null;
+        let x11Recorder = null;
+        const mp4Path = path.join(baseDir, `${options.mediaMode}.mp4`);
+        if (useX11Capture && xvfbDisplay) {
+            // Use the actual rendered surface size (CSS px × DPR) so x11grab and
+            // Chromium agree on dimensions. On cloud DPR is capped at 1 by
+            // cli-runner.ts, so this matches the viewport.
+            const surfaceW = Math.round(page.viewportSize()?.width ?? options.captureResolution?.width ?? 1440);
+            const surfaceH = Math.round(page.viewportSize()?.height ?? options.captureResolution?.height ?? 900);
+            x11Recorder = new FfmpegX11Recorder({
+                display: xvfbDisplay,
+                width: surfaceW,
+                height: surfaceH,
+                fps: targetFps,
+                outputPath: mp4Path,
+            });
+            await x11Recorder.start();
+        }
+        else {
+            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`),
+            mp4Path,
             loop,
+            x11Recorder,
             finalized: false,
         };
         this.clipCursor = {
@@ -461,6 +493,32 @@ export class WebPlaywrightLocal {
             this.recordingNavWatcher.detach();
             this.recordingNavWatcher = null;
         }
+        // Cloud Linux clip capture path: ffmpeg already wrote the final MP4
+        // directly from x11grab, no frame assembly needed. Stop ffmpeg cleanly
+        // (`q` on stdin → moov atom is finalized) and surface the output.
+        if (this.recording.x11Recorder) {
+            const x11Result = await this.recording.x11Recorder.stop();
+            // Tear down the browser context AFTER ffmpeg stops — closing it sooner
+            // would freeze Chromium's last frame mid-paint and the tail of the clip
+            // would show a partial render.
+            await this.browser.closeContext();
+            this.recording.finalized = true;
+            this.recording.sourcePath = x11Result.outputPath;
+            this.recording.sourceMimeType = 'video/mp4';
+            this.recording.trimStartMs = x11Result.trimStartMs;
+            this.recording.encodedDurationMs = await getMediaDurationMs(x11Result.outputPath);
+            this.clipCursor = null;
+            const buffer = await fs.readFile(x11Result.outputPath);
+            return {
+                buffer,
+                durationMs: this.recording.encodedDurationMs,
+                mimeType: 'video/mp4',
+                trimStartMs: x11Result.trimStartMs,
+            };
+        }
+        if (!this.recording.loop) {
+            throw new Error('recording loop was not initialized');
+        }
         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.8",
+  "version": "1.3.9",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",