@specific.dev/spectest 0.86.2 → 0.88.0

package/dist/harness/wrapper-rules.d.ts

@@ -1,3 +1,16 @@
+/**
+ * A test that opens a project file through `node:fs` (or `Bun.file`)
+ * instead of `ctx.readProjectFile`. **Advisory.** The subset selector
+ * learns which project files a test depends on from the reads the SDK
+ * serves (`project-files.ts`); a raw read is a dependence it never sees,
+ * so a change to that file can skip the test. The rule is textual — an
+ * import or `require` of the fs modules, or a `Bun.file(` call — and is
+ * applied to the test tree only, where the alternative exists. It turns
+ * blocking when the reach gate enforces (`SUBSET_RUNS.md`).
+ */
+export declare const CODE_RAW_FS = "SPECTEST2003";
+/** The raw-fs findings of one test file, from its text alone. */
+export declare function fsUsageDiagnostics(file: string, text: string): WrapperDiagnostic[];
 /** A finding, shaped like the `TypecheckError` the report already carries. */
 export interface WrapperDiagnostic {
     /** Path relative to the app dir, matching the advisory diagnostics. */

package/dist/harness/wrapper-rules.js

@@ -55,6 +55,43 @@
 // function over a string, which is what the tests below drive. A user type
 // that happens to be called `Carrier<T>` would also be flagged — and would
 // also be an object at runtime, so the finding stays true.
+/**
+ * A test that opens a project file through `node:fs` (or `Bun.file`)
+ * instead of `ctx.readProjectFile`. **Advisory.** The subset selector
+ * learns which project files a test depends on from the reads the SDK
+ * serves (`project-files.ts`); a raw read is a dependence it never sees,
+ * so a change to that file can skip the test. The rule is textual — an
+ * import or `require` of the fs modules, or a `Bun.file(` call — and is
+ * applied to the test tree only, where the alternative exists. It turns
+ * blocking when the reach gate enforces (`SUBSET_RUNS.md`).
+ */
+export const CODE_RAW_FS = "SPECTEST2003";
+const FS_MODULES = new Set(["fs", "node:fs", "fs/promises", "node:fs/promises"]);
+/** The raw-fs findings of one test file, from its text alone. */
+export function fsUsageDiagnostics(file, text) {
+    const out = [];
+    const push = (pos, what) => {
+        const { line, column } = lineColumnAt(text, pos);
+        out.push({
+            file,
+            line,
+            column,
+            code: CODE_RAW_FS,
+            message: `${what} reads project files behind the SDK's back; use ctx.readProjectFile (or ctx.readProjectFileBytes) ` +
+                "so the subset selector knows the test depends on the file",
+            blocking: false,
+        });
+    };
+    const importRe = /\b(?:import|export)\b[^;'"]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\brequire\(\s*['"]([^'"]+)['"]\s*\)|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+    for (const m of text.matchAll(importRe)) {
+        const spec = m[1] ?? m[2] ?? m[3] ?? m[4] ?? "";
+        if (FS_MODULES.has(spec))
+            push(m.index ?? 0, `an import of "${spec}"`);
+    }
+    for (const m of text.matchAll(/\bBun\.file\(/g))
+        push(m.index ?? 0, "Bun.file()");
+    return out;
+}
 /**
  * A condition on a wrapped value — always true. **Blocking**, but on different
  * grounds from {@link CODE_EQUALITY}, and the difference is worth knowing.

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
 export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
+export type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
+import type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
@@ -141,6 +143,13 @@ export interface ServiceConfig {
     tls?: readonly ServiceTls[];
     /** Bind-mounted volumes for state that survives snapshot/fork. */
     volumes?: readonly VolumeMount[];
+    /**
+     * @internal Spectest's own components only: project files or
+     * directories the service consumes outside its build context and
+     * volumes (a lambda's `source`, Supabase's folder). Project-relative; a
+     * directory covers its subtree. The reach counts them.
+     */
+    inputs?: readonly string[];
     /**
      * Opt this service in to **code coverage collection** (experimental).
      *
@@ -841,6 +850,13 @@ export interface VolumeMount {
      * so unlike a volume directory it is never created or wiped by spectest.
      */
     source?: string;
+    /**
+     * @internal Spectest's own components only. The mount does not count
+     * for the project's reach: what the service can load from it is stated
+     * some other way (a narrowed build context, `inputs`). Never set this
+     * for a mount the service reads freely.
+     */
+    reachExempt?: boolean;
     /** Container path. */
     target: string;
     readOnly?: boolean;
@@ -1295,6 +1311,16 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * like named desktop browsers.
      */
     mobile(app: MobileApp, name?: string): Promise<Mobile>;
+    /** Drive a real Electron renderer window through locators and user input.
+     * Acquires the app started by electron(); keeps its live state across forks.
+     * Each test gets a self-contained graphical replay. Selecting another window
+     * does not create a new app or isolate its storage from sibling windows.
+     *
+     * const app = await ctx.desktop(ctx.svc.app);
+     * await app.getByRole("textbox", { name: "New note" }).fill("Hello");
+     * await app.getByRole("button", { name: "Add note" }).click();
+     */
+    desktop(app: DesktopApp, options?: DesktopOptions): Promise<Desktop>;
     /** The test's display name. */
     readonly testName: string;
     /**

package/dist/index.js

@@ -322,6 +322,11 @@ function validateEnvironmentConfig(config) {
             }
         }
         validateCoverage(name, svc.coverage);
+        for (const input of svc.inputs ?? []) {
+            if (typeof input !== "string" || input.trim() === "" || input.startsWith("/") || input.split("/").includes("..")) {
+                throw new Error(`service "${name}" has an invalid \`inputs\` entry ${JSON.stringify(input)} — a project-relative file or directory path`);
+            }
+        }
         for (const raw of svc.hostnames ?? []) {
             const h = raw.toLowerCase();
             if (!HOSTNAME_RE.test(hostPatternBody(h))) {

package/dist/recorder.d.ts

@@ -464,6 +464,8 @@ export interface BrowserEvent extends BaseEvent {
      * bundle to look the session up in.
      */
     sessionName?: string;
+    /** Presentation kind; Electron and mobile share the browser event transport. */
+    frame?: "browser" | "mobile" | "desktop";
     /**
      * Wall-clock `Date.now()` captured at the moment this op *finished*.
      * Lives in the same time base as rrweb's `event.timestamp` fields,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.86.2",
+  "version": "0.88.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -1,8 +1,8 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
 // driving the guest's system Chromium (pipe transport — `chromium.launch`
-// with an explicit `executablePath`; `connectOverCDP` is off-limits, its
-// bundled `ws` client hangs under Bun). The wrapper keeps the public
-// surface stable (we swapped from Bun.WebView to Playwright without
+// with an explicit `executablePath`). Electron attaches to the app-owned
+// Chromium over CDP instead; its client also lives inside the VM. The wrapper
+// keeps the public surface stable (we swapped from Bun.WebView to Playwright without
 // changing tests) and routes every call through the recorder so browser
 // actions show up in a test's event log alongside exec/fetch/assertion
 // events. Playwright's client state (browser/context/page objects, the
@@ -34,6 +34,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { generateId } from "./ids.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
+import type { DesktopChrome } from "./desktop.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
@@ -150,6 +153,7 @@ export interface BrowserSessionRecorder {
    * from the persisted events alone, with no replay bundle).
    */
   readonly sessionName?: string;
+  readonly frame?: "browser" | "mobile" | "desktop";
   /** Called for each drained chunk of rrweb events. */
   recordStep(step: BrowserSessionStep): void;
   /** Optional: called whenever `Browser.goto(url)` is invoked. */
@@ -1144,7 +1148,7 @@ const PAGE_INIT_SCRIPT = RRWEB_BUNDLE
 // snapshot keeps steady-state steps (clicks/types on an unchanged page,
 // or navigations where `load` already fired) from bloating the stream
 // with redundant snapshots.
-function drainExpr(forceFullIfMissing: boolean): string {
+function drainExpr(forceFullIfMissing: boolean, timestamp = Date.now()): string {
   return `(function () {
   try {
     var rec = window.__spectestRec;
@@ -1159,6 +1163,9 @@ function drainExpr(forceFullIfMissing: boolean): string {
       if (!hasFull) rec.takeFullSnapshot();
     }
   } catch (e) { /* recording inactive or DOM detached — drain what's there. */ }
+  if (typeof window.__spectestSyncInputs === "function") {
+    window.__spectestSyncInputs(${timestamp});
+  }
   var buf = window.__spectestRrwebEvents;
   if (!buf || !buf.length) return [];
   window.__spectestRrwebEvents = [];
@@ -1551,6 +1558,92 @@ export async function acquirePersistentMobileBackend(
   return { browser: backend, attached: existing !== undefined, detach };
 }
 
+/** Live CDP clients and window identities ride the harness snapshot. */
+const ELECTRON_APPS = new Map<string, Promise<{
+  browser: PlaywrightBrowser;
+  context: BrowserContext;
+  windows: Page[];
+  holders: Map<Page, ViewHolder>;
+}>>();
+
+/** Attach the shared locator/recorder backend to an actual Electron window.
+ * Never navigate, reload, emulate a viewport, or replace its renderer. */
+export async function acquirePersistentDesktop(
+  endpoint: string,
+  windowIndex: number,
+  recorder: BrowserSessionRecorder | null,
+): Promise<PersistentBrowser & { desktopChrome?: DesktopChrome }> {
+  if (!Number.isInteger(windowIndex) || windowIndex < 0) {
+    throw new Error("ctx.desktop(): window must be a non-negative integer (creation order)");
+  }
+  let pending = ELECTRON_APPS.get(endpoint);
+  if (!pending) {
+    pending = (async () => {
+      const response = await rawFetch(new URL("/json/version", endpoint), {
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok) throw new Error(`Electron debugger discovery failed: HTTP ${response.status}`);
+      const info = await response.json() as { webSocketDebuggerUrl: string };
+      const websocket = new URL(info.webSocketDebuggerUrl);
+      websocket.host = new URL(endpoint).host;
+      const browser = await chromium.connectOverCDP(websocket.toString(), { timeout: 15_000 });
+      const context = browser.contexts()[0];
+      if (!context) { await browser.close(); throw new Error("Electron has no renderer context"); }
+      const windows = context.pages().filter(page => !page.url().startsWith("devtools:"));
+      context.on("page", page => { if (!page.url().startsWith("devtools:")) windows.push(page); });
+      browser.on("disconnected", () => { ELECTRON_APPS.delete(endpoint); });
+      return { browser, context, windows, holders: new Map<Page, ViewHolder>() };
+    })();
+    ELECTRON_APPS.set(endpoint, pending);
+    pending.catch(() => { if (ELECTRON_APPS.get(endpoint) === pending) ELECTRON_APPS.delete(endpoint); });
+  }
+  const app = await pending;
+  const deadline = Date.now() + 15_000;
+  while (!app.windows[windowIndex]) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error(`Electron window ${windowIndex} did not open`);
+    await app.context.waitForEvent("page", { timeout: remaining });
+  }
+  const page = app.windows[windowIndex];
+  if (page.isClosed()) throw new Error(`Electron window ${windowIndex} is closed; window indices retain creation order`);
+  await page.waitForLoadState("domcontentloaded");
+  // The main-process observer publishes only window presentation options.
+  // A popup created internally by Chromium might not pass through BrowserWindow.
+  await page.waitForFunction(() => Boolean((window as any).__spectestElectronChrome), null, { timeout: 3000 }).catch(() => {});
+  const desktopChrome = await page.evaluate(() => {
+    const chrome = (window as any).__spectestElectronChrome;
+    if (!chrome) return undefined;
+    const overlay = (navigator as any).windowControlsOverlay;
+    return { ...chrome, ...(overlay?.visible ? { titlebarArea: overlay.getTitlebarAreaRect().toJSON() } : {}) };
+  }) as DesktopChrome | undefined;
+  let holder = app.holders.get(page);
+  const attached = holder !== undefined;
+  if (!holder) {
+    const cdp = await app.context.newCDPSession(page);
+    await cdp.send("Page.enable");
+    if (!PAGE_INIT_SCRIPT) throw new Error("Electron replay recorder bundle is missing");
+    const init = `${PAGE_INIT_SCRIPT};\n${DESKTOP_INPUT_SYNC_SCRIPT}`;
+    await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: init });
+    // The app owns navigation and may already have loaded. Start on its live
+    // DOM, without losing drafts or replaying any application startup effects.
+    await page.evaluate(init);
+    const size = await page.evaluate(() => ({ width: innerWidth, height: innerHeight }));
+    holder = {
+      context: app.context, page, cdp, lastTitle: await page.title(),
+      recordingInstalled: true, device: null, width: size.width, height: size.height,
+      safeAreaInsets: null, initScripts: [],
+    };
+    app.holders.set(page, holder);
+    page.on("close", () => { app.holders.delete(page); });
+  }
+  await attachReset(holder);
+  const { backend, detach } = buildBackend(holder, recorder, {
+    persistent: false, ownsContext: false,
+    onDestroy: () => { app.holders.delete(page); },
+  });
+  return { browser: backend, attached, detach, desktopChrome };
+}
+
 /** True when a navigation failed on Chromium name resolution. */
 function isNameNotResolved(err: unknown): boolean {
   return String((err as Error)?.message ?? err).includes("ERR_NAME_NOT_RESOLVED");
@@ -1617,6 +1710,8 @@ interface BackendBuildOptions {
   /** Called when close() destroys the underlying view — the acquire
    *  functions use it to drop the holder from the shared registry. */
   onDestroy?: () => void;
+  /** Electron windows share an app context; closing one must leave siblings alive. */
+  ownsContext?: boolean;
 }
 
 function buildBackend(
@@ -1678,15 +1773,16 @@ function buildBackend(
     return {
       sessionId: recorder.sessionId,
       sessionTimestamp: endT,
+      ...(recorder.frame ? { frame: recorder.frame } : {}),
       ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
     };
   }
 
-  async function drain(action: BrowserAction | "close"): Promise<void> {
+  async function drain(action: BrowserAction | "close", timestamp = Date.now()): Promise<void> {
     if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
       const urlChanged = holder.page.url() !== lastDrainUrl;
-      const events = (await holder.page.evaluate(drainExpr(urlChanged))) as unknown[];
+      const events = (await holder.page.evaluate(drainExpr(urlChanged, timestamp))) as unknown[];
       lastDrainUrl = holder.page.url();
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
@@ -1731,7 +1827,7 @@ function buildBackend(
         ...sessionFields(endT),
         durationMs: endT - t,
       }, resv);
-      await drain(action);
+      await drain(action, endT);
       // Fold this page's V8 counters into the per-service totals now — a
       // navigation to another origin replaces the renderer and its
       // counters, so harvesting per op is what keeps them.
@@ -1766,7 +1862,7 @@ function buildBackend(
       }, resv);
       // Still try to drain — the failure itself may have produced
       // useful rrweb events (mutations from a half-loaded page, etc.).
-      await drain(action);
+      await drain(action, endT);
       throw err;
     }
   }
@@ -2067,7 +2163,7 @@ function buildBackend(
       // The context, not the page, holds the cookies and storage — closing
       // only the page would leave the next session signed in as this one.
       try {
-        await holder.context.close();
+        if (buildOpts.ownsContext !== false) await holder.context.close();
       } catch {
         /* context already gone (browser died) */
       }
@@ -2149,7 +2245,7 @@ function buildBackend(
       }, reserveBackdated(waitedMs));
       // Drain the rrweb the page buffered while the matcher waited into this
       // step's chunk, so `settledTarget` has bounds to seek into.
-      await drain(action);
+      await drain(action, endT);
       return seq;
     },
     pageOp<T>(

package/src/components/aws.ts

@@ -249,6 +249,12 @@ export function aws(opts: AwsOptions = {}) {
       LAMBDA_DOCKER_NETWORK: SPECTEST_NETWORK,
     },
     volumes: [{ source: DOCKER_SOCKET, target: DOCKER_SOCKET }],
+    // Each lambda's code is packaged from the project at setup: no build
+    // context or volume carries it, so it is declared as an input and a
+    // change to it is never taken as one that can affect no test.
+    ...(Object.keys(lambdas).length > 0
+      ? { inputs: Object.values(lambdas).map((l) => l.source).filter((s) => typeof s === "string" && s.trim() !== "") }
+      : {}),
     ports: [AWS_PORT],
     readyCheck: {
       type: "http" as const,

package/src/components/electron-chrome.ts

@@ -0,0 +1,76 @@
+// Runs before the application's main entry, like Playwright's Electron loader.
+// Observe constructor options; do not replace the app entry, preload, IPC, or OS.
+export const ELECTRON_CHROME_HOOK = String.raw`
+const electron = require('electron');
+const NativeBrowserWindow = electron.BrowserWindow;
+const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
+  construct(Target, args, NewTarget) {
+    const win = Reflect.construct(Target, args, NewTarget);
+    const options = args[0] || {};
+    const chrome = {
+      titleBarStyle: options.titleBarStyle || 'default',
+      frame: options.frame !== false,
+      trafficLightPosition: options.trafficLightPosition || null,
+      titleBarOverlay: options.titleBarOverlay || false,
+      roundedCorners: options.roundedCorners !== false,
+      buttonVisibility: null,
+    };
+    const publish = () => {
+      if (win.isDestroyed() || win.webContents.isDestroyed()) return;
+      void win.webContents.executeJavaScript(
+        'window.__spectestElectronChrome = ' + JSON.stringify(chrome)
+      ).catch(() => {}); // A document can be replaced while this is in flight.
+    };
+    win.webContents.on('dom-ready', publish);
+    // Capture supported native setters too, without adding macOS APIs on Linux.
+    for (const [method, key] of [
+      ['setWindowButtonVisibility', 'buttonVisibility'],
+      ['setWindowButtonPosition', 'trafficLightPosition'],
+      ['setTitleBarOverlay', 'titleBarOverlay'],
+    ]) {
+      if (typeof win[method] !== 'function') continue;
+      const original = win[method];
+      win[method] = function(value) {
+        const result = original.call(this, value);
+        chrome[key] = value;
+        publish();
+        return result;
+      };
+    }
+    return win;
+  },
+});
+// Electron's own exports are non-configurable. Wrap module resolution instead
+// of modifying them; all other exports retain their original descriptors.
+const Module = require('node:module');
+const originalLoad = Module._load;
+const facades = new Map();
+Module._load = function(request, ...args) {
+  const exports = originalLoad.call(this, request, ...args);
+  if (request !== 'electron' && request !== 'electron/main') return exports;
+  if (!facades.has(exports)) {
+    const descriptors = Object.getOwnPropertyDescriptors(exports);
+    descriptors.BrowserWindow = { value: WrappedBrowserWindow, enumerable: true };
+    facades.set(exports, Object.defineProperties({}, descriptors));
+  }
+  return facades.get(exports);
+};
+// Electron's native ESM translator bypasses Module._load. Route ESM imports
+// through the same facade using Node's synchronous loader hooks when available.
+if (typeof Module.registerHooks === 'function') {
+  const source = 'import { createRequire } from "node:module";\n' +
+    'const electron = createRequire(' + JSON.stringify(__filename) + ')("electron");\n' +
+    'export default electron;\n' + Object.keys(electron)
+      .filter(key => /^[A-Za-z_$][\w$]*$/.test(key))
+      .map(key => 'export const ' + key + ' = electron.' + key + ';').join('\n');
+  const url = 'data:text/javascript,' + encodeURIComponent(source);
+  Module.registerHooks({
+    resolve(specifier, context, next) {
+      if ((specifier === 'electron' || specifier === 'electron/main') && context.conditions.includes('import')) {
+        return { url, shortCircuit: true };
+      }
+      return next(specifier, context);
+    },
+  });
+}
+`;

package/src/components/electron.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { electron } from './electron.js';
+import { desktopApp, isDesktopApp } from '../desktop.js';
+
+function fixture(run: (directory: string) => void) {
+  const directory = mkdtempSync(join(tmpdir(), 'spectest-electron-'));
+  try {
+    writeFileSync(join(directory, 'package.json'), JSON.stringify({ devDependencies: { electron: '43.2.0' } }));
+    run(directory);
+  } finally { rmSync(directory, { recursive: true, force: true }); }
+}
+
+describe('Electron component contract', () => {
+  test('rejects apps without Electron before starting an expensive build', () => fixture(appDir => {
+    writeFileSync(join(appDir, 'package.json'), '{}');
+    expect(() => electron({ appDir })).toThrow('declare electron');
+  }));
+  test('honors locked installation, custom build commands, and app environment', () => fixture(appDir => {
+    writeFileSync(join(appDir, 'package-lock.json'), '{}');
+    const service = electron({ appDir, buildCommand: 'npm run compile', env: { API_URL: 'http://backend:4320' } });
+    expect(service.image).toMatchObject({ context: appDir });
+    expect((service.image as { content: string }).content).toContain('RUN npm ci\n');
+    expect((service.image as { content: string }).content).toContain('RUN npm run compile\n');
+    expect(service.env?.API_URL).toBe('http://backend:4320');
+  }));
+  test('rejects malformed image tags and multiline Dockerfile injection', () => fixture(appDir => {
+    expect(() => electron({ appDir, nodeVersion: '24\nRUN false' })).toThrow('image tag');
+    expect(() => electron({ appDir, buildCommand: 'npm run build\nUSER other' })).toThrow('single-line');
+  }));
+  test('desktop identity cannot be mistaken for a URL or browser/mobile handle', () => {
+    expect(isDesktopApp(desktopApp('http://app.internal:9223', 'app'))).toBe(true);
+    expect(isDesktopApp({ url: 'http://app.internal:8081' })).toBe(false);
+    expect(isDesktopApp(null)).toBe(false);
+  });
+});

package/src/components/electron.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "node:fs";
+import type { ServiceDefinition } from "../index.js";
+import { resolveProjectPath } from "../project-files.js";
+import { desktopApp, type DesktopApp } from "../desktop.js";
+import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
+
+export interface ElectronOptions {
+  /** Project-relative app directory; must contain package.json and Electron. */
+  appDir?: string;
+  /** Debian Node image tag, default 24-bookworm-slim. */
+  nodeVersion?: string;
+  /** Build the main/preload/renderer output; default npm run build. */
+  buildCommand?: string;
+  /** Dependency install command; defaults to npm ci when a lockfile exists. */
+  installCommand?: string;
+  /** App entry relative to /app, default . (package.json main). */
+  entry?: string;
+  env?: Record<string, string>;
+  dependsOn?: string[];
+}
+
+// Test-only debugger proxy: Electron binds its CDP socket to loopback. Forward
+// HTTP and WebSocket traffic from the VM to that socket, normalizing Host as
+// Chromium requires. It exposes no app-specific actions or state endpoints.
+export const ELECTRON_LAUNCHER = String.raw`
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+const require = createRequire('/app/package.json');
+const child = spawn(require('electron'), [
+  ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
+  '--disable-dev-shm-usage', '--remote-debugging-port=9222',
+  '-r', '/spectest-electron-chrome.cjs',
+  process.env.SPECTEST_ELECTRON_ENTRY || '.',
+], { cwd: '/app', stdio: 'inherit', env: process.env });
+const upstream = req => ({
+  host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
+  headers: { ...req.headers, host: '127.0.0.1:9222' },
+});
+const server = http.createServer((req, res) => {
+  const proxy = http.request(upstream(req), response => {
+    res.writeHead(response.statusCode, response.headers);
+    response.pipe(res);
+  });
+  proxy.on('error', () => { res.writeHead(503); res.end('Electron debugger starting'); });
+  req.pipe(proxy);
+});
+server.on('upgrade', (req, socket, head) => {
+  const proxy = http.request(upstream(req));
+  proxy.on('upgrade', (response, remote, remoteHead) => {
+    socket.write('HTTP/1.1 101 Switching Protocols\r\n' +
+      Object.entries(response.headers).map(([k, v]) => k + ': ' + v).join('\r\n') + '\r\n\r\n');
+    if (remoteHead.length) socket.write(remoteHead);
+    if (head.length) remote.write(head);
+    socket.pipe(remote); remote.pipe(socket);
+    socket.on('error', () => remote.destroy());
+    remote.on('error', () => socket.destroy());
+    socket.on('close', () => remote.destroy());
+    remote.on('close', () => socket.destroy());
+  });
+  proxy.on('response', () => socket.destroy());
+  proxy.on('error', () => socket.destroy());
+  proxy.end();
+});
+server.listen(9223, '0.0.0.0');
+child.on('error', error => { console.error(error); process.exit(1); });
+child.on('exit', code => process.exit(code ?? 1));
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
+`;
+
+/** Real Linux Electron under Xvfb, with a generated image and graphical replay.
+ * Like expo(), returns an app handle for the matching context method.
+ * Requires Linux-compatible application dependencies and binaries. */
+export function electron(options: ElectronOptions = {}) {
+  const appDir = options.appDir ?? ".";
+  const manifest = resolveProjectPath(`${appDir}/package.json`);
+  if (!existsSync(manifest)) throw new Error(`electron(): no package.json in ${appDir}`);
+  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+  if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
+    throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+  }
+  const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+  const node = options.nodeVersion ?? "24-bookworm-slim";
+  if (!/^[\w.-]+$/.test(node)) throw new Error("electron(): invalid Node image tag");
+  const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
+  const build = options.buildCommand ?? "npm run build";
+  if ([install, build].some(command => /[\r\n]/.test(command))) {
+    throw new Error("electron(): build/install commands must be single-line shell commands");
+  }
+  return {
+    image: {
+      type: "dockerfile",
+      context: appDir,
+      exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
+      content: `FROM node:${node}
+RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY . .
+RUN ${install}
+RUN node node_modules/electron/install.js
+RUN ${build}
+`,
+    },
+    files: [
+      { path: "/spectest-electron.mjs", content: ELECTRON_LAUNCHER },
+      { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
+    ],
+    command: "xvfb-run -a node /spectest-electron.mjs",
+    env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+    dependsOn: options.dependsOn,
+    ports: [9223],
+    readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }) => desktopApp(`http://${name}.internal:9223`, name),
+  } satisfies ServiceDefinition<DesktopApp>;
+}

package/src/components/index.ts

@@ -97,3 +97,4 @@ export {
   type CassetteResponse,
   type CassetteState,
 } from "./replayFake.js";
+export { electron, type ElectronOptions } from "./electron.js";