@specific.dev/spectest 0.87.0 → 0.88.1

package/src/components/supabase-functions-reach.ts

@@ -0,0 +1,153 @@
+// What the edge functions can load from the project — the pure part.
+//
+// The edge runtime serves each function from the project root, mounted
+// whole so that a monorepo function's `../../packages/shared/mod.ts`
+// resolves where it sits. Whole is right for the runtime and wrong for
+// the reach: with the root in a build context and a volume, every file of
+// the project could "reach" the functions, and a change to `docs/` could
+// never skip a run. So the component works out the **module graph** the
+// functions can load, statically, and hands the build context and the
+// reach exactly that: the functions directory, and every directory a
+// relative import or a local import-map entry leads to, followed
+// transitively. Directories rather than files, so a sibling module a
+// dynamic `import()` picks at run time comes along.
+//
+// What it cannot see: a computed specifier that leaves the directories
+// found (`import(\`../../${x}/mod.ts\`)`), and a `Deno.readTextFile` of a
+// path outside them. Both are rare in a function, and both are the same
+// class of hole as a test reading the workspace through `node:fs`. A tree
+// too large to walk within the budget is answered with the whole project,
+// the safe side.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** Files the walk parses for imports. */
+const SOURCE_EXT = /\.(?:[mc]?[jt]sx?)$/;
+/** Names never walked into. */
+const SKIP = new Set(["node_modules", ".git", ".spectest", "dist", "build", ".next"]);
+/** The walk gives up past this many files and answers with the root. */
+const FILE_BUDGET = 20_000;
+
+const IMPORT_RE =
+  /\b(?:import|export)\b[^;'"`]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** Specifiers a source text imports, as written. */
+export function importSpecifiers(text: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(IMPORT_RE)) out.push(m[1] ?? m[2] ?? m[3] ?? "");
+  return out.filter((s) => s.length > 0);
+}
+
+/** Local targets an import map (`deno.json` `imports`, `import_map.json`)
+ *  names, as written: relative values, and root-relative `/…` ones. */
+export function importMapLocalTargets(text: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [];
+  }
+  const imports = (parsed as { imports?: unknown })?.imports;
+  if (typeof imports !== "object" || imports === null) return [];
+  return Object.values(imports as Record<string, unknown>).filter(
+    (v): v is string => typeof v === "string" && (v.startsWith("./") || v.startsWith("../") || v.startsWith("/")),
+  );
+}
+
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+
+/**
+ * The directories, project-relative and sorted, that the functions under
+ * `fnRelPath` can load modules from: `fnRelPath` itself, and every
+ * directory a relative import or a local import-map entry leads to,
+ * transitively. `["."]` when the walk runs out of budget. A directory
+ * nested under another in the answer is dropped.
+ */
+export function functionsReach(root: string, fnRelPath: string): string[] {
+  const rootAbs = resolve(root);
+  const dirs = new Set<string>();
+  const queue: string[] = [resolve(rootAbs, fnRelPath)];
+  let budget = FILE_BUDGET;
+
+  const inRoot = (p: string): boolean => p === rootAbs || p.startsWith(rootAbs + sep);
+  const enqueue = (target: string): void => {
+    if (!inRoot(target) || !existsSync(target)) return;
+    let st;
+    try {
+      st = statSync(target);
+    } catch {
+      return;
+    }
+    const dir = st.isDirectory() ? target : dirname(target);
+    if (![...dirs].some((d) => dir === d || dir.startsWith(d + sep))) queue.push(dir);
+  };
+  const follow = (fromDir: string, spec: string): void => {
+    if (spec.startsWith("./") || spec.startsWith("../")) enqueue(resolve(fromDir, spec));
+    else if (spec.startsWith("/")) enqueue(resolve(rootAbs, spec.slice(1)));
+  };
+
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    if ([...dirs].some((d) => dir === d || dir.startsWith(d + sep))) continue;
+    if (!existsSync(dir)) continue;
+    dirs.add(dir);
+    // Every file below it, parsed for what it imports.
+    const stack: string[] = [dir];
+    while (stack.length > 0) {
+      const d = stack.pop()!;
+      let entries;
+      try {
+        entries = readdirSync(d, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const e of entries) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) {
+          if (!SKIP.has(e.name)) stack.push(p);
+          continue;
+        }
+        if (!e.isFile()) continue;
+        if (--budget < 0) return ["."];
+        if (e.name === "deno.json" || e.name === "import_map.json") {
+          for (const t of importMapLocalTargets(safeRead(p))) follow(d, t.endsWith("/") ? t.slice(0, -1) : t);
+          continue;
+        }
+        if (!SOURCE_EXT.test(e.name)) continue;
+        for (const spec of importSpecifiers(safeRead(p))) follow(d, spec);
+      }
+    }
+  }
+
+  // Minimal, project-relative, sorted.
+  const rel = [...dirs].map((d) => (d === rootAbs ? "." : toPosix(relative(rootAbs, d))));
+  const minimal = rel.filter((d) => !rel.some((o) => o !== d && (o === "." || d.startsWith(o + "/"))));
+  return [...new Set(minimal)].sort();
+}
+
+function safeRead(p: string): string {
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** The `exclude` list that narrows a root build context to `dirs`: drop
+ *  everything, then re-include each directory and its subtree, then drop
+ *  again what no context should carry (a re-included `packages/shared`
+ *  would otherwise bring its `node_modules` along). */
+export function excludeAllBut(dirs: readonly string[]): string[] {
+  if (dirs.includes(".")) return [];
+  return ["**", ...dirs.flatMap((d) => [`!${d}`, `!${d}/**`]), ...REEXCLUDE];
+}
+
+/** Re-excluded after the re-includes: the names the default ignore drops. */
+const REEXCLUDE = ["**/node_modules/**", "**/.git/**", "**/.spectest/**", "**/__pycache__/**", "**/.venv/**"];
+
+// Keep `isAbsolute` referenced for callers that pass absolute fnRelPath by
+// mistake: the walk resolves it against the root either way.
+void isAbsolute;

package/src/components/supabase.ts

@@ -51,6 +51,7 @@
 
 import { createHmac } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { excludeAllBut, functionsReach } from "./supabase-functions-reach.js";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
@@ -166,6 +167,9 @@ function providerCredentials(
  * cache rides into the image as a layer — so at run time the worker resolves
  * those URLs locally and never reaches for the network.
  *
+ * The context is the module graph the functions can load (the functions
+ * directory and what its imports lead to, `functionsReach`), copied whole
+ * so a monorepo function's `../../packages/…` resolves at bundle time too.
  * One synthetic entrypoint imports every function, so the whole set is one
  * graph rather than one per function. Bundling is best-effort: a function that
  * fails to bundle (a type error, an import that only resolves at run time)
@@ -175,13 +179,13 @@ function providerCredentials(
 function functionsDockerfile(fnRelPath: string): string {
   return `FROM ${IMAGES.functions}
 ENV DENO_DIR=${DENO_DIR}
-COPY ${fnRelPath} /warm/functions
+COPY . /warm/repo
 RUN set -eu; \
     : > /warm/all.ts; \
-    for d in /warm/functions/*/; do \
+    for d in /warm/repo/${fnRelPath}/*/; do \
       [ -f "$d/index.ts" ] || continue; \
       n=$(basename "$d"); \
-      printf 'import "./functions/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
+      printf 'import "./repo/${fnRelPath}/%s/index.ts";\\n' "$n" >> /warm/all.ts; \
     done; \
     edge-runtime bundle --entrypoint /warm/all.ts --output /tmp/warm.eszip --quiet || true; \
     rm -rf /tmp/warm.eszip /warm
@@ -1684,6 +1688,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
         ? `${REPO_MOUNT}/${fnDir.slice(root.length + 1)}`
         : `${REPO_MOUNT}/supabase/functions`;
   const migrationsPath = inDir("migrations");
+  // The directories the functions can load modules from: the functions
+  // directory and what its imports lead to (`supabase-functions-reach.ts`).
+  // The build context and the reach are narrowed to exactly these.
+  const fnReachDirs = withFunctions ? functionsReach(root, fnRelPath) : [];
 
   // ── config file (config.toml / config.json) ───────────────────────────
   // The CLI's own project config, mapped onto the stack. Read at build time:
@@ -1890,8 +1898,20 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
       const parts: ServicesMap = {};
 
       // ── db ──────────────────────────────────────────────────────────
+      // What the stack reads from the project: the Supabase folder
+      // (config.toml, migrations, seed, functions) and the mail templates,
+      // which may sit anywhere in the repo. Declared as inputs so a change
+      // to any of them is never taken as one that can affect no test; the
+      // migrations volume carries the folder too, but only when there is
+      // a migrations directory, and a config-only project must count as
+      // well.
+      const inputs: string[] = [
+        ...(opts.dir !== undefined && !opts.dir.startsWith("/") ? [opts.dir] : []),
+        ...templateBodies.map(([, spec]) => spec.path).filter((t) => !t.startsWith("/")),
+      ];
       const dbDef: ServiceDefinition = {
         image: { type: "registry", reference: opts.db?.image ?? IMAGES.db },
+        ...(inputs.length > 0 ? { inputs } : {}),
         // `args` (not `command`): keep the image's docker-entrypoint.sh so it
         // runs initdb + its baked init-scripts before starting.
         args: [
@@ -2211,6 +2231,12 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           image: {
             type: "dockerfile",
             content: functionsDockerfile(fnRelPath),
+            // The root, narrowed to the module graph: only the functions
+            // directory and what its imports lead to enter the context, so
+            // a change anywhere else neither uploads nor counts as reaching
+            // the functions.
+            context: ".",
+            exclude: excludeAllBut(fnReachDirs),
           },
           // The **project root**, mounted with the functions directory in its
           // real position underneath. Mounting only `supabase/functions`
@@ -2219,8 +2245,10 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
           // (`../../../../packages/…`), and that only resolves if the
           // directory sits where it sits in the repo. Read-only: the runtime
           // only reads sources, and a function writing into its own directory
-          // would be writing into the user's checkout.
-          volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true }],
+          // would be writing into the user's checkout. For the reach the
+          // mount is exempt: what the functions can load is the module graph
+          // above, which the build context already states.
+          volumes: [{ source: projectRootPath(), target: REPO_MOUNT, readOnly: true, reachExempt: true }],
           // Our router (see FUNCTIONS_MAIN_TS) sits outside that mount, so
           // the project never has to carry a `main/` function of ours.
           files: [{ path: "/home/deno/main/index.ts", content: FUNCTIONS_MAIN_TS }],

package/src/daemon.ts

@@ -67,8 +67,9 @@ import {
   type CoverageInventoryContext,
 } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
-import { acquirePersistentBrowser, mobileKey } from "./browser.js";
+import { acquirePersistentBrowser, acquirePersistentDesktop, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
+import { isDesktopApp, type Desktop, type DesktopApp, type DesktopOptions, type DesktopChrome } from "./desktop.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
@@ -4255,7 +4256,8 @@ async function computeProjectReachInner(all: NamedService[]): Promise<ReachRules
   for (const svc of all) {
     const src: ReachSource = {
       service: svc.name,
-      volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
+      volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source && !v.reachExempt ? [v.source] : [])),
+      ...(svc.inputs && svc.inputs.length > 0 ? { inputs: [...svc.inputs] } : {}),
     };
     if (svc.image.type === "dockerfile") {
       try {
@@ -4352,10 +4354,11 @@ interface BrowserSessionRecord {
   openedAtMs: number;
   closedAtMs?: number;
   initialUrl?: string;
-  /** Replay frame: `"browser"` (desktop window, default) or `"mobile"`
-   * (phone bezel). Drives the dashboard's chrome; the rrweb events are
+  /** Replay frame: `"browser"` (default), `"mobile"` (phone bezel), or
+   * `"desktop"` (native app window). Drives the dashboard's chrome; the rrweb events are
    * identical either way. */
-  frame?: "browser" | "mobile";
+  frame?: "browser" | "mobile" | "desktop";
+  desktopChrome?: DesktopChrome;
   /** Safe-area insets that were CDP-emulated during capture (mobile
    * sessions on a Chromium that supports the override). The dashboard
    * substitutes these for `env(safe-area-inset-*)` in the replayed CSS —
@@ -4463,7 +4466,7 @@ function browserArgs(
 function newBrowserSession(
   testStart: number,
   idScope: string,
-  frame: "browser" | "mobile" = "browser",
+  frame: "browser" | "mobile" | "desktop" = "browser",
   artifacts?: ReturnType<typeof newArtifactCollector>,
   name = "",
 ): {
@@ -4486,6 +4489,7 @@ function newBrowserSession(
     record,
     recorder: {
       sessionId: record.sessionId,
+      frame,
       ...(name ? { sessionName: name } : {}),
       recordStep(step) {
         if (closed) return;
@@ -4507,6 +4511,37 @@ function newBrowserSession(
   };
 }
 
+/** Same desktop recording path for test runs and interactive evals. */
+function desktopOpener(
+  start: number,
+  scope: string,
+  sessions: Array<ReturnType<typeof newBrowserSession>>,
+  detaches: Array<() => Promise<void>>,
+  artifacts?: ReturnType<typeof newArtifactCollector>,
+) {
+  const memo = new Map<string, Desktop>();
+  return async (app: DesktopApp, options: DesktopOptions = {}): Promise<Desktop> => {
+    if (!isDesktopApp(app)) throw new Error("ctx.desktop(app): pass ctx.svc.app from an electron() service");
+    const window = options.window ?? 0;
+    const key = JSON.stringify([app.endpoint, window]);
+    const existing = memo.get(key);
+    if (existing) return existing;
+    const session = newBrowserSession(start, scope, "desktop", artifacts, window === 0 ? app.name : `${app.name} · window ${window + 1}`);
+    const { browser, detach, desktopChrome } = await acquirePersistentDesktop(app.endpoint, window, session.recorder);
+    session.record.desktopChrome = desktopChrome;
+    session.record.initialUrl = browser.url();
+    sessions.push(session);
+    detaches.push(async () => { await detach(); session.markClosed(); });
+    const close = browser.close.bind(browser);
+    browser.close = async () => {
+      await close();
+      if (memo.get(key) === browser) memo.delete(key);
+    };
+    memo.set(key, browser);
+    return browser;
+  };
+}
+
 /** Per-Terminal asciicast session shipped to the control plane. */
 interface TerminalSessionRecord {
   sessionId: string;
@@ -5599,6 +5634,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
     mcp: openMcp,
     testName: testCase.name,
     parent,
@@ -6154,6 +6190,7 @@ async function evalCode(
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
     mcp: openMcp,
     testName: "eval",
     parent: undefined,

package/src/desktop-recorder.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from 'bun:test';
+import { runInNewContext } from 'node:vm';
+import { DESKTOP_INPUT_SYNC_SCRIPT } from './desktop-recorder.js';
+
+function recorder(type = 'textarea', blocked = false) {
+  const element = { type, value: 'draft', checked: false, hasAttribute: (_name: string) => false, closest: () => blocked ? {} : null };
+  const window: any = { __spectestRec: { mirror: { getId: () => 7 } }, __spectestRrwebEvents: [] };
+  runInNewContext(DESKTOP_INPUT_SYNC_SCRIPT, { window, document: { querySelectorAll: () => [element] } });
+  return { element, window, events: window.__spectestRrwebEvents as any[] };
+}
+
+test('late attachment captures a controlled input clearing without a DOM input event', () => {
+  const { element, window, events } = recorder();
+  expect(events).toHaveLength(0);
+  element.value = '';
+  window.__spectestSyncInputs(123);
+  expect(JSON.parse(JSON.stringify(events))).toEqual([
+    { type: 3, data: { source: 5, id: 7, text: '', isChecked: false }, timestamp: 123 },
+  ]);
+  window.__spectestSyncInputs(124);
+  expect(events).toHaveLength(1);
+});
+
+test('rrweb input events need no duplicate correction; a snapshot does not hide later changes', () => {
+  const { element, window, events } = recorder();
+  element.value = 'typed';
+  events.push({ type: 3, data: { source: 5, id: 7, text: 'typed', isChecked: false } });
+  window.__spectestSyncInputs();
+  expect(events).toHaveLength(1);
+  events.length = 0;
+  events.push({ type: 2, data: {} });
+  element.value = '';
+  window.__spectestSyncInputs();
+  expect(events).toHaveLength(2);
+  expect(events[1].data.text).toBe('');
+});
+
+test('correction respects password masking, blocked controls and file inputs', () => {
+  const password = recorder('password');
+  password.element.value = 'secret-value';
+  password.window.__spectestSyncInputs();
+  expect(password.events[0].data.text).toBe('************');
+  expect(JSON.stringify(password.events)).not.toContain('secret-value');
+  const revealed = recorder('text');
+  revealed.element.hasAttribute = name => name === 'data-rr-is-password';
+  revealed.element.value = 'revealed-secret';
+  revealed.window.__spectestSyncInputs();
+  expect(revealed.events[0].data.text).toBe('***************');
+  expect(JSON.stringify(revealed.events)).not.toContain('revealed-secret');
+  for (const fixture of [recorder('textarea', true), recorder('file')]) {
+    fixture.element.value = 'private';
+    fixture.window.__spectestSyncInputs();
+    expect(fixture.events).toHaveLength(0);
+  }
+});

package/src/desktop-recorder.ts

@@ -0,0 +1,30 @@
+// A late recorder cannot interpose on setters React cached during mounting.
+// Reconcile controls at action boundaries, without changing the app's DOM or
+// descriptors. Normal rrweb Input events win; synthesize only missing changes.
+export const DESKTOP_INPUT_SYNC_SCRIPT = String.raw`(() => {
+  if (window.__spectestSyncInputs) return;
+  const known = new WeakMap();
+  window.__spectestSyncInputs = (timestamp = Date.now()) => {
+    const rec = window.__spectestRec;
+    const events = window.__spectestRrwebEvents;
+    if (!rec?.mirror || !events) return;
+    const inputs = new Map();
+    for (const event of events) {
+      if (event.type === 3 && event.data?.source === 5) inputs.set(event.data.id, event.data);
+    }
+    for (const element of document.querySelectorAll('input, textarea, select')) {
+      const type = element.hasAttribute('data-rr-is-password') ? 'password' : element.type?.toLowerCase();
+      if (type === 'file' || element.closest('.rr-block, .rr-ignore')) continue;
+      const id = rec.mirror.getId(element);
+      if (!(id > 0)) continue;
+      const text = type === 'password' ? '*'.repeat(element.value.length) : element.value;
+      const isChecked = (type === 'checkbox' || type === 'radio') ? element.checked : false;
+      const current = { text, isChecked };
+      const previous = inputs.get(id) ?? known.get(element);
+      known.set(element, current);
+      if (!previous || (previous.text === text && previous.isChecked === isChecked)) continue;
+      events.push({ type: 3, data: { source: 5, id, text, isChecked }, timestamp });
+    }
+  };
+  window.__spectestSyncInputs();
+})();`;

package/src/desktop.ts

@@ -0,0 +1,43 @@
+import type { Browser } from "./browser.js";
+
+export const DESKTOP_APP: unique symbol = Symbol.for("spectest.desktopApp");
+
+/** An Electron service handle produced by electron(). */
+export interface DesktopApp {
+  readonly [DESKTOP_APP]: true;
+  readonly endpoint: string;
+  readonly name: string;
+}
+
+/** Real renderer window: user input, locators, assertions, and replay capture.
+ * close() closes this window only. Native OS dialogs are outside DOM replay. */
+export interface Desktop extends Browser {}
+
+/** Observed window configuration at the start of a replay session. */
+export interface DesktopChrome {
+  titleBarStyle: string;
+  frame: boolean;
+  trafficLightPosition: { x: number; y: number } | null;
+  titleBarOverlay: boolean | { height?: number; color?: string; symbolColor?: string };
+  roundedCorners: boolean;
+  buttonVisibility: boolean | null;
+  titlebarArea?: { x: number; y: number; width: number; height: number };
+}
+
+export interface DesktopOptions {
+  /** Zero-based window creation order. Defaults to the first window.
+   * Open additional windows using the app UI before selecting them.
+   * A closed window keeps its index; other windows never change identity. */
+  window?: number;
+}
+
+export function desktopApp(endpoint: string, name: string): DesktopApp {
+  return { [DESKTOP_APP]: true, endpoint, name };
+}
+
+export function isDesktopApp(value: unknown): value is DesktopApp {
+  return typeof value === "object" && value !== null &&
+    (value as DesktopApp)[DESKTOP_APP] === true &&
+    typeof (value as DesktopApp).endpoint === "string" &&
+    typeof (value as DesktopApp).name === "string";
+}

package/src/harness/reach.test.ts

@@ -128,6 +128,18 @@ describe("reach rules", () => {
     expect(reachContains({ version: 1, sources: [{ context: "packages/x", ignore: "**" }], prefixes: [] }, "packages/x/Dockerfile")).toBe(true);
   });
 
+  test("a service's declared inputs count: a lambda's source directory, a config file", () => {
+    const srcs = [{ service: "aws", inputs: ["lambda/add", "supabase/config.toml"] }];
+    expect(projectReach(["lambda/add/index.js", "lambda/other/index.js", "supabase/config.toml", "supabase/config.toml.bak"], srcs)).toEqual([
+      "lambda/add/index.js",
+      "supabase/config.toml",
+    ]);
+    const rules = { version: 1 as const, sources: srcs, prefixes: [] };
+    expect(reachContains(rules, "lambda/add/new.js")).toBe(true);
+    expect(sourceOf(srcs, "lambda/add/new.js")?.service).toBe("aws");
+    expect(reachContains(rules, "lambda/other/index.js")).toBe(false);
+  });
+
   test("the whole project as one prefix", () => {
     expect(reachContains({ version: 1, sources: [], prefixes: ["."] }, "anything/at/all")).toBe(true);
     expect(reachContains({ version: 1, sources: [], prefixes: [] }, "anything/at/all")).toBe(false);

package/src/harness/reach.ts

@@ -125,6 +125,10 @@ export interface ReachSource {
   /** Volume sources, project-relative; an absolute source is not a
    *  project path and is skipped. */
   volumeSources?: string[];
+  /** The service's declared `inputs`: project files or directories it
+   *  consumes some other way (packaged at setup, read at load). A
+   *  directory covers its subtree. */
+  inputs?: string[];
 }
 
 function normRel(p: string): string {
@@ -157,7 +161,7 @@ export function projectReach(files: readonly string[], sources: readonly ReachSo
       const rel = normRel(e);
       if (rel) out.add(rel);
     }
-    for (const v of s.volumeSources ?? []) {
+    for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
       if (v.startsWith("/")) continue;
       const src = normRel(v);
       for (const f of files) {
@@ -252,7 +256,7 @@ export function sourceOf(sources: readonly ReachSource[], path: string): ReachSo
       }
     }
     for (const e of s.extraFiles ?? []) if (normRel(e) === p) return s;
-    for (const v of s.volumeSources ?? []) {
+    for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
       if (v.startsWith("/")) continue;
       const src = normRel(v);
       if (p === src || p.startsWith(`${src}/`)) return s;

package/src/index.ts

@@ -141,6 +141,8 @@ import { describeUrlPattern, matchesUrl } from "./url-match.js";
 // `expo()` component.
 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";
 
@@ -308,6 +310,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).
    *
@@ -1245,7 +1254,7 @@ const BUILD_TARGET_RE = /^[^\s]+$/;
  * Runs in `defineEnvironment`, and in the daemon's runtime `startService`
  * twin, inside the VM, where the repo sits at the project root. Existence
  * checks go through the project-file resolver, so the same rules as
- * `ctx.readProjectFile` apply (a `spectest/.envignore`d path is refused
+ * `ctx.readProjectFile` apply (a `spectest/.specignore`d path is refused
  * instead of read stale).
  */
 export function validateServiceImage(serviceName: string, image: ServiceImage): ServiceImage {
@@ -1320,6 +1329,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;
@@ -1553,6 +1569,13 @@ function validateEnvironmentConfig<S extends ServicesMap>(
       }
     }
     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))) {
@@ -1928,6 +1951,16 @@ export interface TestContext<
    * 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/src/inputs.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment } from "./index.js";
+
+const image = { type: "registry" as const, reference: "busybox" };
+
+describe("service inputs", () => {
+  test("project-relative files and directories are accepted and kept on the config", () => {
+    const env = defineEnvironment({
+      name: "t",
+      services: { app: { image, inputs: ["lambda/add", "supabase/config.toml"] } },
+    });
+    expect(env.config.services.app!.inputs).toEqual(["lambda/add", "supabase/config.toml"]);
+  });
+
+  test("an absolute path, an empty entry and a parent reference are refused", () => {
+    for (const bad of ["/etc/passwd", "", "../outside"]) {
+      expect(() => defineEnvironment({ name: "t", services: { app: { image, inputs: [bad] } } })).toThrow(/invalid `inputs` entry/);
+    }
+  });
+});