@specific.dev/spectest 0.87.0 → 0.88.1

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/emulate/entry.mjs

@@ -17,13 +17,11 @@
 //     origin. Real providers spread them over several hosts. We merge the
 //     real URLs in.
 //   * JWKS — we serve one RSA public key, for every provider.
-//   * id_token — we re-issue it: same claims, RS256, our key, and a
-//     corrected `iss` where the emulator cannot know it. This is one step
-//     that fixes three faults. The Google emulator signs HS256 and serves
-//     an empty JWKS, so no client can verify its token. The Microsoft one
-//     cannot put the tenant in the issuer, because it does not know it.
-//     And any future provider whose issuer does not match its base URL is
-//     covered in advance. No signature check is needed on the way in: the
+//   * id_token — we re-issue it: same claims, RS256, our key, and an
+//     explicit `iss` where the provider declares one. The Google emulator
+//     signs HS256 and serves an empty JWKS, so no client can verify its
+//     token. Providers whose issuer differs from their base URL can
+//     declare it explicitly. No signature check is needed on the way in: the
 //     token comes from an in-process function call, not from the network.
 //   * the account picker page — each button gets a `data-testid`, so a
 //     browser test has a stable locator.

package/src/components/emulate/service.ts

@@ -26,11 +26,10 @@
 // `entry.mjs` routes by Host header, applies the per-provider path table,
 // and corrects the discovery document. It also re-issues every id_token
 // with one RSA key it generates at boot, and serves that key at the
-// provider's real JWKS URL. That single step covers three separate faults:
+// provider's real JWKS URL. This normalizes signing and issuer handling:
 // the Google emulator signs HS256 and publishes an empty JWKS (so nothing
-// can verify its token), the Microsoft one cannot put the tenant in its
-// issuer, and any future provider whose issuer is not its base URL is
-// handled in advance.
+// can verify its token), and providers whose issuer differs from their
+// base URL can declare it explicitly.
 //
 // The Dockerfile is deliberately CONSTANT — every provider package is
 // installed whether or not this component is the one using it. Two reasons:

package/src/components/index.ts

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

package/src/components/microsoft.ts

@@ -13,23 +13,22 @@ import { emulatorService, oauthClients, resolveUsers } from "./emulate/service.j
 export interface MicrosoftOptions extends ProviderOptions {
   /**
    * Directory (tenant) the app signs in against — whatever its authority
-   * URL uses. It appears in the issuer and in every endpoint path, so a
-   * client that checks the issuer sees what it expects. Default `"common"`.
+   * URL uses. Sets the seeded users' and client's tenant as well as the
+   * issuer and endpoint paths. Default `"common"`.
    */
   tenantId?: string;
 }
 
 function spec(users: ProviderUser[], opts: MicrosoftOptions): ProviderSpec {
-  const authority = `https://login.microsoftonline.com/${opts.tenantId || "common"}`;
+  const tenantId = opts.tenantId || "common";
+  const authority = `https://login.microsoftonline.com/${tenantId}`;
   return {
     name: "microsoft",
     module: "@emulators/microsoft",
     pluginExport: "microsoftPlugin",
     baseUrl: "https://login.microsoftonline.com",
     hosts: ["login.microsoftonline.com", "graph.microsoft.com"],
-    // The emulator has no tenant, so its issuer is the bare host. A client
-    // that checks the issuer against the authority it configured would
-    // reject that; the re-issue step corrects it.
+    // Keep the re-issued token aligned with discovery and the seeded tenant.
     issuer: `${authority}/v2.0`,
     discovery: {
       issuer: `${authority}/v2.0`,
@@ -52,8 +51,8 @@ function spec(users: ProviderUser[], opts: MicrosoftOptions): ProviderSpec {
       scopes: ["openid", "email", "profile", "User.Read"],
     },
     seed: {
-      users: users.map((u) => ({ email: u.email, name: u.name })),
-      ...oauthClients(opts.client),
+      users: users.map((u) => ({ email: u.email, name: u.name, tenant_id: tenantId })),
+      ...oauthClients(opts.client, { tenant_id: tenantId }),
     },
   };
 }

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

@@ -0,0 +1,90 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { excludeAllBut, functionsReach, importMapLocalTargets, importSpecifiers } from "./supabase-functions-reach.js";
+
+let root: string;
+
+function file(rel: string, text: string): void {
+  mkdirSync(join(root, rel, ".."), { recursive: true });
+  writeFileSync(join(root, rel), text);
+}
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "sb-fn-reach-"));
+  file("supabase/functions/hello/index.ts", 'import { greet } from "../../../packages/shared/src/greet.ts";\nimport "npm:zod";\nDeno.serve(() => new Response(greet()));\n');
+  file("supabase/functions/bye/index.ts", 'import { db } from "@db/client.ts";\nexport default 1;\n');
+  file("supabase/functions/deno.json", JSON.stringify({ imports: { "@db/": "../../lib/db/", "zod": "npm:zod" } }));
+  file("packages/shared/src/greet.ts", 'import { fmt } from "./fmt.ts";\nimport { util } from "../../util/mod.ts";\nexport const greet = () => fmt(util());\n');
+  file("packages/shared/src/fmt.ts", "export const fmt = (s: string) => s;\n");
+  file("packages/util/mod.ts", "export const util = () => 'x';\n");
+  file("lib/db/client.ts", "export const db = 1;\n");
+  file("docs/guide.md", "# not code\n");
+  file("site/app/page.tsx", 'import x from "../../packages/shared/src/greet.ts";\n');
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+describe("functionsReach", () => {
+  test("follows relative imports and local import-map entries transitively, into directories", () => {
+    expect(functionsReach(root, "supabase/functions")).toEqual(["lib/db", "packages/shared/src", "packages/util", "supabase/functions"]);
+  });
+  test("a self-contained functions directory is the whole answer; a missing one is nothing", () => {
+    file("alone/functions/f/index.ts", 'import "https://deno.land/std/http/server.ts";\nimport("./helper.ts");\n');
+    expect(functionsReach(root, "alone/functions")).toEqual(["alone/functions"]);
+    expect(functionsReach(root, "nowhere/functions")).toEqual([]);
+  });
+  test("an import that leaves the project is ignored", () => {
+    file("escape/functions/f/index.ts", 'import "../../../../../../etc/passwd";\n');
+    expect(functionsReach(root, "escape/functions")).toEqual(["escape/functions"]);
+  });
+  test("the exclude list drops everything but the answer", () => {
+    expect(excludeAllBut(["lib/db", "supabase/functions"])).toEqual([
+      "**",
+      "!lib/db",
+      "!lib/db/**",
+      "!supabase/functions",
+      "!supabase/functions/**",
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/.spectest/**",
+      "**/__pycache__/**",
+      "**/.venv/**",
+    ]);
+    expect(excludeAllBut(["."])).toEqual([]);
+  });
+});
+
+describe("parsers", () => {
+  test("import specifiers of every shape", () => {
+    const t = 'import a from "./a.ts";\nexport * from "../b.ts";\nimport "./side.ts";\nconst m = await import("./dyn.ts");\nimport type { T } from "npm:x";\n';
+    expect(importSpecifiers(t)).toEqual(["./a.ts", "../b.ts", "./side.ts", "./dyn.ts", "npm:x"]);
+  });
+  test("import map local targets", () => {
+    expect(importMapLocalTargets('{"imports":{"@a/":"../../a/","b":"npm:b","c":"/c/mod.ts"}}')).toEqual(["../../a/", "/c/mod.ts"]);
+    expect(importMapLocalTargets("not json")).toEqual([]);
+  });
+});
+
+describe("supabase() wiring", () => {
+  test("the functions image context is the module graph, and the root mount is reach-exempt", async () => {
+    const prev = process.env.SPECTEST_WORKSPACE;
+    process.env.SPECTEST_WORKSPACE = root;
+    try {
+      const { supabase } = await import("./supabase.js");
+      const stack = supabase({ dir: "supabase" });
+      const parts = stack.group.services({ name: "sb", key: (part: string) => (part === "gateway" ? "sb" : `sb-${part}`) });
+      const fn = parts.functions as { image: { context?: string; exclude?: readonly string[] }; volumes?: readonly { source?: string; reachExempt?: boolean }[] };
+      expect(fn.image.context).toBe(".");
+      expect(fn.image.exclude?.slice(0, 9)).toEqual(["**", "!lib/db", "!lib/db/**", "!packages/shared/src", "!packages/shared/src/**", "!packages/util", "!packages/util/**", "!supabase/functions", "!supabase/functions/**"]);
+      expect(fn.image.exclude?.at(-1)).toBe("**/.venv/**");
+      expect(fn.volumes?.[0]).toMatchObject({ source: root, reachExempt: true });
+      expect((parts.db as { inputs?: readonly string[] }).inputs).toEqual(["supabase"]);
+    } finally {
+      if (prev === undefined) delete process.env.SPECTEST_WORKSPACE;
+      else process.env.SPECTEST_WORKSPACE = prev;
+    }
+  });
+});