autokap 1.3.22 → 1.3.23

package/dist/xvfb-process.d.ts

@@ -1,14 +1,25 @@
 /**
- * Xvfb (X virtual framebuffer) process wrapper.
+ * Xvfb (X virtual framebuffer) process wrapper, plus a minimal window
+ * manager (matchbox) so headed Chromium's --kiosk flag actually takes
+ * effect.
  *
  * 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.
+ * Why matchbox: Chromium's --kiosk / --start-fullscreen flags request
+ * fullscreen mode from the WM via _NET_WM_STATE_FULLSCREEN. Without a WM
+ * to honor that request, Chromium silently falls back to a normal
+ * decorated window with the full chrome (tab bar, address bar, infobars)
+ * visible — and ffmpeg x11grab captures all of it, ruining clips.
+ * matchbox-window-manager (~100KB, designed for embedded kiosks)
+ * auto-fullscreens every window with no decorations. With matchbox,
+ * --kiosk takes effect and the page fills the whole framebuffer cleanly.
+ *
+ * Lifecycle: Xvfb + matchbox both run 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. */
@@ -21,10 +32,23 @@ export interface XvfbProcessOptions {
 export declare class XvfbProcess {
     private readonly opts;
     private process;
+    private wmProcess;
     private exited;
     constructor(opts: XvfbProcessOptions);
     /** DISPLAY string suitable for `process.env.DISPLAY` (e.g. `:99`). */
     get display(): string;
     start(): Promise<void>;
+    /**
+     * Start matchbox-window-manager. Required for Chromium's --kiosk to
+     * actually take effect: kiosk requests fullscreen via the WM, and
+     * without a WM Chromium falls back to a normal decorated window with
+     * the full chrome leaking into x11grab captures. matchbox is tiny
+     * (~100KB), auto-fullscreens every window, and removes decorations.
+     * `-use_titlebar no` and `-use_cursor no` are belt-and-suspenders;
+     * matchbox already defaults to no decorations, but the explicit flags
+     * also stop it from drawing its own cursor (which would superimpose
+     * on Chromium's cursor and confuse the cursor overlay script).
+     */
+    private startWindowManager;
     stop(): Promise<void>;
 }

package/dist/xvfb-process.js

@@ -1,14 +1,25 @@
 /**
- * Xvfb (X virtual framebuffer) process wrapper.
+ * Xvfb (X virtual framebuffer) process wrapper, plus a minimal window
+ * manager (matchbox) so headed Chromium's --kiosk flag actually takes
+ * effect.
  *
  * 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.
+ * Why matchbox: Chromium's --kiosk / --start-fullscreen flags request
+ * fullscreen mode from the WM via _NET_WM_STATE_FULLSCREEN. Without a WM
+ * to honor that request, Chromium silently falls back to a normal
+ * decorated window with the full chrome (tab bar, address bar, infobars)
+ * visible — and ffmpeg x11grab captures all of it, ruining clips.
+ * matchbox-window-manager (~100KB, designed for embedded kiosks)
+ * auto-fullscreens every window with no decorations. With matchbox,
+ * --kiosk takes effect and the page fills the whole framebuffer cleanly.
+ *
+ * Lifecycle: Xvfb + matchbox both run 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';
@@ -16,9 +27,11 @@ 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;
+const WM_STARTUP_GRACE_MS = 200;
 export class XvfbProcess {
     opts;
     process = null;
+    wmProcess = null;
     exited = false;
     constructor(opts) {
         this.opts = opts;
@@ -72,6 +85,7 @@ export class XvfbProcess {
                 await fs.access(socketPath);
                 logger.info(`[xvfb] ready on display ${this.display} (${this.opts.width}×${this.opts.height}) ` +
                     `after ${Date.now() - startedAt}ms`);
+                await this.startWindowManager();
                 return;
             }
             catch {
@@ -81,11 +95,58 @@ export class XvfbProcess {
         }
         throw new Error(`Xvfb did not become ready within ${XVFB_READY_TIMEOUT_MS}ms`);
     }
+    /**
+     * Start matchbox-window-manager. Required for Chromium's --kiosk to
+     * actually take effect: kiosk requests fullscreen via the WM, and
+     * without a WM Chromium falls back to a normal decorated window with
+     * the full chrome leaking into x11grab captures. matchbox is tiny
+     * (~100KB), auto-fullscreens every window, and removes decorations.
+     * `-use_titlebar no` and `-use_cursor no` are belt-and-suspenders;
+     * matchbox already defaults to no decorations, but the explicit flags
+     * also stop it from drawing its own cursor (which would superimpose
+     * on Chromium's cursor and confuse the cursor overlay script).
+     */
+    async startWindowManager() {
+        this.wmProcess = spawn('matchbox-window-manager', ['-use_titlebar', 'no', '-use_cursor', 'no'], {
+            env: { ...process.env, DISPLAY: this.display },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: false,
+        });
+        this.wmProcess.stderr?.on('data', (chunk) => {
+            const text = String(chunk).trim();
+            if (text)
+                logger.warn(`[matchbox-wm] ${text}`);
+        });
+        this.wmProcess.on('exit', (code, signal) => {
+            // Don't mark this.exited — Xvfb is still alive. Just log if abnormal.
+            if (code !== 0 && code !== null) {
+                logger.warn(`[matchbox-wm] exited unexpectedly: code=${code} signal=${signal}`);
+            }
+        });
+        this.wmProcess.on('error', (err) => {
+            logger.error(`[matchbox-wm] spawn error: ${err.message}`);
+        });
+        // Brief grace so matchbox can register as the WM with the X server
+        // before Chromium opens its first window.
+        await new Promise(r => setTimeout(r, WM_STARTUP_GRACE_MS));
+        logger.info(`[matchbox-wm] started on display ${this.display}`);
+    }
     async stop() {
         if (!this.process)
             return;
         const proc = this.process;
         this.process = null;
+        const wmProc = this.wmProcess;
+        this.wmProcess = null;
+        // Tear down matchbox first — it would die when Xvfb goes anyway, but
+        // killing it explicitly avoids a SIGPIPE / "X connection lost" warning
+        // in the logs.
+        if (wmProc) {
+            try {
+                wmProc.kill('SIGTERM');
+            }
+            catch { /* already dead */ }
+        }
         proc.kill('SIGTERM');
         await new Promise(resolve => {
             const timer = setTimeout(() => {

package/package.json

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