Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

35.5 KB
Raw Blame
/**
 * An in-memory `chrome` for the Recorder's tests. It implements exactly the APIs the extension calls and
 * exposes drivers and recorders on the returned `ChromeFake`. Install it per test and uninstall it after.
 * IndexedDB is not part of it: tests import `fake-indexeddb/auto`.
 *
 * Each extension context sees its own `chrome`, as in Chrome. The service worker (and the extension's pages) see every
 * API below; an offscreen document sees only what Chrome gives one: chrome.runtime with messaging, getURL and id.
 * `globalThis.chrome` is the surface of the context the running code belongs to: code started inside `runAs` keeps
 * that context through everything it awaits or schedules, and a listener runs in the context it was added in.
 *
 * And of the browser it belongs to. Code a fake's listener ran, or `runAs` started, keeps that fake through everything
 * it awaits or schedules, after the fake is uninstalled and another installed too: a service worker or a document of
 * one test that still finishes its work (a Stop's drain, which closes its document) does it in its own browser, as in
 * Chrome, where one browser's extension never reaches another's. Code that belongs to none (a test's own) sees the fake
 * installed last.
 */

import { AsyncLocalStorage, AsyncResource } from "node:async_hooks";
import { isDeepStrictEqual } from "node:util";

type Listener = (...args: unknown[]) => unknown;
type Json = Record<string, unknown>;

/** The extension contexts whose `chrome` differs. */
export type ChromeContext = "service-worker" | "offscreen-document";

export type FakePort = {
  postMessage(message: unknown): void;
  messages: unknown[];
  disconnect(): void;
  onDisconnect: { called: boolean };
};

export type ChromeFake = {
  uninstall(): void;
  /** Each context's `chrome`, whatever context the caller runs in: a test playing the service worker in a file whose
   * default is the offscreen document reaches the worker's events here. */
  apis: Record<ChromeContext, typeof chrome>;
  /** Runs `work` as code of `context`: `globalThis.chrome` is that context's surface in it, in everything it awaits or
   * schedules, and in every listener it adds. */
  runAs<T>(context: ChromeContext, work: () => T): T;
  /**
   * Every chrome.* call and every port message in either direction, in order: "offscreen.createDocument",
   * "runtime.onMessage.addListener", "port:recorder:offscreen offscreen.start".
   */
  calls: string[];
  storage: {
    local: Map<string, unknown>;
    session: Map<string, unknown>;
    managed: Map<string, unknown>;
    accessLevel: string | null;
    sessionAccessLevel: string | null;
    setManaged(values: Record<string, unknown>): void;
  };
  /** Simulates a port opened by another context; returns the far end. */
  connectFrom(name: string, sender: chrome.runtime.MessageSender): FakePort;
  sendExternal(
    message: unknown,
    sender: chrome.runtime.MessageSender,
  ): Promise<unknown>;
  sendFromPage(
    message: unknown,
    sender?: Partial<chrome.runtime.MessageSender>,
  ): Promise<unknown>;
  permissions: {
    granted: Set<string>;
    requests: chrome.permissions.Permissions[];
    answer: boolean;
  };
  scripting: {
    registered: chrome.scripting.RegisteredContentScript[];
    executed: chrome.scripting.ScriptInjection<unknown[], unknown>[];
    refuseFrames?: number[];
  };
  offscreen: {
    /** Whether the document exists: true from createDocument until closeDocument, across restartServiceWorker. */
    open: boolean;
    created: chrome.offscreen.CreateParameters[];
    /**
     * Test hooks, not part of chrome.offscreen: they run when createDocument opened a document or closeDocument closed
     * it, with `open` already updated and before the call resolves, so a test can play the document's own side (its
     * port connecting, then going down). Like the document, they survive restartServiceWorker.
     */
    onDocumentCreated: FakeHook<
      [parameters: chrome.offscreen.CreateParameters]
    >;
    onDocumentClosed: FakeHook<[]>;
  };
  debugger: {
    attached: chrome.debugger.Debuggee[];
    commands: {
      target: chrome.debugger.Debuggee;
      method: string;
      params?: object;
    }[];
    respond(
      method: string,
      result: object | ((params: object) => object),
    ): void;
    emit(
      target: chrome.debugger.Debuggee,
      method: string,
      params: object,
    ): void;
    detach(
      target: chrome.debugger.Debuggee,
      reason: "target_closed" | "canceled_by_user",
    ): void;
    refuseAttach?: string;
    targets(): chrome.debugger.TargetInfo[];
  };
  webNavigation: {
    commit(
      details: Partial<chrome.webNavigation.WebNavigationTransitionCallbackDetails>,
    ): void;
    historyUpdate(
      details: Partial<chrome.webNavigation.WebNavigationTransitionCallbackDetails>,
    ): void;
    createdTarget(details: {
      sourceTabId: number;
      tabId: number;
      url: string;
    }): void;
  };
  native: { reply: ((message: object) => object) | null; sent: object[] };
  badge: { text: string; color: string };
  alarms: {
    created: Map<string, chrome.alarms.AlarmCreateInfo>;
    fire(name: string): void;
  };
  tabs: Map<number, chrome.tabs.Tab>;
  /**
   * What the person does with tabs and windows, as Chrome reports it to the extension (measured on Playwright's
   * Chromium 151, headless, 2026-10-22): a tab they open fires tabs.onCreated and then tabs.onActivated; a tab they
   * switch to fires tabs.onActivated; a window they bring to the front fires windows.onFocusChanged, and no tab event,
   * since its active tab was active already.
   */
  person: {
    /** The new-tab button: a tab on the new tab page (whose address Chrome withholds), active in its window. */
    openTab(tab?: Partial<chrome.tabs.Tab>): chrome.tabs.Tab;
    /** A tab clicked in the tab strip: it becomes its window's active tab. */
    switchTo(tabId: number): void;
    focusWindow(windowId: number): void;
  };
  opened: string[];
  updated: { tabId: number; props: chrome.tabs.UpdateProperties }[];
  /** The tab ids chrome.tabs.remove closed, in order. */
  removed: number[];
  /**
   * Simulates the service worker being torn down and started again: its listeners and the ports other contexts
   * hold to it are gone (the test re-registers them), while storage.session, storage.local, tabs, the offscreen
   * document, alarms and attached debuggers stay. onStartup and onInstalled run only when asked.
   */
  restartServiceWorker(): void;
  fireStartup(): void;
  fireInstalled(reason: string): void;
};

const DEFAULT_EXTENSION_ID = "abcdefghijklmnopabcdefghijklmnop";

type FakeHook<Args extends unknown[]> = {
  addListener(listener: (...args: Args) => void): void;
  removeListener(listener: (...args: Args) => void): void;
};

/** A test-side hook: unlike a chrome event it is typed, unrecorded in `calls`, and kept across restartServiceWorker. */
function createHook<Args extends unknown[]>(): FakeHook<Args> & {
  dispatch(...args: Args): void;
} {
  const listeners = new Set<(...args: Args) => void>();
  return {
    addListener: (listener) => {
      listeners.add(listener);
    },
    removeListener: (listener) => {
      listeners.delete(listener);
    },
    dispatch: (...args) => {
      for (const listener of [...listeners]) listener(...args);
    },
  };
}

type FakeEvent = {
  addListener(listener: Listener): void;
  removeListener(listener: Listener): void;
  hasListener(listener: Listener): boolean;
  hasListeners(): boolean;
  dispatch(...args: unknown[]): unknown[];
  clear(): void;
};

/** One installed fake: the `chrome` its code sees. */
type Installation = { chrome(): typeof chrome };
/** The fake the running code belongs to (see the file's header). */
const belongsTo = new AsyncLocalStorage<Installation>();

/** A listener runs in the context it was added in, whoever dispatches: the service worker posting on a port does not
 * make the document's listener service-worker code. It runs as code of the fake whose event it is (`owner`). */
function createEvent(
  name: string | null,
  calls: string[],
  owner: Installation,
): FakeEvent {
  const listeners = new Map<Listener, Listener>();
  return {
    addListener(listener) {
      if (name) calls.push(`${name}.addListener`);
      if (!listeners.has(listener))
        listeners.set(
          listener,
          belongsTo.run(owner, () => AsyncResource.bind(listener)),
        );
    },
    removeListener(listener) {
      if (name) calls.push(`${name}.removeListener`);
      listeners.delete(listener);
    },
    hasListener: (listener) => listeners.has(listener),
    hasListeners: () => listeners.size > 0,
    dispatch: (...args) =>
      [...listeners.values()].map((listener) => listener(...args)),
    clear: () => listeners.clear(),
  };
}

/** Chrome's message passing serializes as JSON: Sets, Maps and functions do not survive, and the sender cannot mutate the copy. */
function jsonCopy(value: unknown): unknown {
  if (value === undefined) return undefined;
  const text = JSON.stringify(value);
  return text === undefined ? undefined : JSON.parse(text);
}

/**
 * Runs onMessage-style listeners in a microtask, as Chrome does, handing them a JSON copy of the message, and
 * resolves with the first response (also a JSON copy), or undefined when none answers.
 */
function deliver(
  event: FakeEvent,
  message: unknown,
  sender: chrome.runtime.MessageSender,
): Promise<unknown> {
  return new Promise((resolve) => {
    queueMicrotask(() => {
      let answered = false;
      const sendResponse = (response: unknown) => {
        if (answered) return;
        answered = true;
        resolve(jsonCopy(response));
      };
      const results = event.dispatch(jsonCopy(message), sender, sendResponse);
      if (!answered && !results.includes(true)) resolve(undefined);
    });
  });
}

function messageType(message: unknown): string {
  if (typeof message === "object" && message !== null && "type" in message)
    return String((message as Json).type);
  return "message";
}

type PortEnd = {
  name: string;
  sender?: chrome.runtime.MessageSender;
  messages: unknown[];
  onMessage: FakeEvent;
  onDisconnect: FakeEvent;
  disconnected: boolean;
  disconnectFired: boolean;
  postMessage(message: unknown): void;
  disconnect(): void;
};

function createPortPair(
  name: string,
  sender: chrome.runtime.MessageSender,
  calls: string[],
  owner: Installation,
) {
  const makeEnd = (): PortEnd => ({
    name,
    messages: [],
    onMessage: createEvent(null, calls, owner),
    onDisconnect: createEvent(null, calls, owner),
    disconnected: false,
    disconnectFired: false,
    postMessage() {},
    disconnect() {},
  });
  const near = makeEnd();
  const far = makeEnd();
  near.sender = sender;
  const wire = (from: PortEnd, to: PortEnd) => {
    from.postMessage = (message) => {
      if (from.disconnected)
        throw new Error("Attempting to use a disconnected port object");
      calls.push(`port:${name} ${messageType(message)}`);
      const copy = jsonCopy(message);
      queueMicrotask(() => {
        to.messages.push(copy);
        to.onMessage.dispatch(copy, to);
      });
    };
    from.disconnect = () => {
      if (from.disconnected) return;
      from.disconnected = true;
      queueMicrotask(() => {
        to.disconnected = true;
        to.disconnectFired = true;
        to.onDisconnect.dispatch(to);
      });
    };
  };
  wire(near, far);
  wire(far, near);
  return { near, far };
}

function matches(value: unknown, wanted: unknown): boolean {
  return wanted === undefined || value === wanted;
}

export function installChromeFake(
  options: {
    extensionId?: string;
    manifestVersion?: string;
    /** The context of code that runs outside `runAs`: a test file of one context's code names it here. */
    context?: ChromeContext;
  } = {},
): ChromeFake {
  const extensionId = options.extensionId ?? DEFAULT_EXTENSION_ID;
  const manifestVersion = options.manifestVersion ?? "0.0.0";
  const defaultContext = options.context ?? "service-worker";
  const contextOf = new AsyncLocalStorage<ChromeContext>();
  const installation: Installation = {
    chrome: () => surfaces[contextOf.getStore() ?? defaultContext],
  };
  const calls: string[] = [];
  const events: FakeEvent[] = [];
  const event = (name: string): FakeEvent => {
    const created = createEvent(name, calls, installation);
    events.push(created);
    return created;
  };

  const runtimeEvents = {
    onMessage: event("runtime.onMessage"),
    onMessageExternal: event("runtime.onMessageExternal"),
    onConnect: event("runtime.onConnect"),
    onInstalled: event("runtime.onInstalled"),
    onStartup: event("runtime.onStartup"),
  };
  const serviceWorkerPorts: PortEnd[] = [];
  const notifyStorage: Partial<
    Record<
      "local" | "session" | "managed",
      (changes: Record<string, chrome.storage.StorageChange>) => void
    >
  > = {};

  const extensionPageSender = (): chrome.runtime.MessageSender => ({
    id: extensionId,
    url: `chrome-extension://${extensionId}/popup.html`,
    origin: `chrome-extension://${extensionId}`,
  });

  const openPort = (name: string, sender: chrome.runtime.MessageSender) => {
    const pair = createPortPair(name, sender, calls, installation);
    if (!runtimeEvents.onConnect.hasListeners()) {
      // Nobody is listening for connections: Chrome disconnects the connecting end.
      queueMicrotask(() => {
        pair.near.disconnected = true;
        pair.far.disconnected = true;
        pair.far.disconnectFired = true;
        pair.far.onDisconnect.dispatch(pair.far);
      });
      return pair;
    }
    serviceWorkerPorts.push(pair.near);
    runtimeEvents.onConnect.dispatch(pair.near);
    return pair;
  };

  const documentCreated =
    createHook<[parameters: chrome.offscreen.CreateParameters]>();
  const documentClosed = createHook<[]>();

  const fake: ChromeFake = {
    uninstall() {
      Reflect.deleteProperty(globalThis, "chrome");
    },
    // Filled in below, once both surfaces exist.
    apis: {} as Record<ChromeContext, typeof chrome>,
    runAs: (context, work) =>
      belongsTo.run(installation, () => contextOf.run(context, work)),
    calls,
    storage: {
      local: new Map(),
      session: new Map(),
      managed: new Map(),
      accessLevel: null,
      sessionAccessLevel: null,
      setManaged(values) {
        const managed = fake.storage.managed;
        const before = new Map(managed);
        managed.clear();
        for (const [key, value] of Object.entries(values))
          managed.set(key, jsonCopy(value));
        const changes: Record<string, chrome.storage.StorageChange> = {};
        for (const [key, value] of managed)
          if (!before.has(key) || !isDeepStrictEqual(before.get(key), value))
            changes[key] = { oldValue: before.get(key), newValue: value };
        for (const [key, oldValue] of before)
          if (!managed.has(key)) changes[key] = { oldValue };
        notifyStorage.managed?.(changes);
      },
    },
    connectFrom(name, sender) {
      const { far } = openPort(name, sender);
      return {
        postMessage: far.postMessage,
        messages: far.messages,
        disconnect: far.disconnect,
        onDisconnect: {
          get called() {
            return far.disconnectFired;
          },
        },
      };
    },
    sendExternal: (message, sender) =>
      deliver(runtimeEvents.onMessageExternal, message, sender),
    sendFromPage: (message, sender) => sendMessageFrom(message, sender),
    permissions: { granted: new Set(), requests: [], answer: true },
    scripting: { registered: [], executed: [] },
    offscreen: {
      open: false,
      created: [],
      onDocumentCreated: documentCreated,
      onDocumentClosed: documentClosed,
    },
    debugger: {
      attached: [],
      commands: [],
      respond(method, result) {
        responders.set(method, result);
      },
      emit(target, method, params) {
        debuggerEvents.onEvent.dispatch(target, method, params);
      },
      detach(target, reason) {
        removeAttached(target);
        debuggerEvents.onDetach.dispatch(target, reason);
      },
      targets: () =>
        [...fake.tabs.values()].map((tab) => {
          const attached = fake.debugger.attached.some(
            (debuggee) => debuggee.tabId === tab.id,
          );
          return {
            id: `target-${tab.id}`,
            type: "page",
            title: tab.title ?? "",
            url: tab.url ?? "",
            attached,
            tabId: tab.id,
            ...(attached ? { extensionId } : {}),
          } as chrome.debugger.TargetInfo;
        }),
    },
    webNavigation: {
      commit: (details) =>
        webNavigationEvents.onCommitted.dispatch(navigationDetails(details)),
      historyUpdate: (details) =>
        webNavigationEvents.onHistoryStateUpdated.dispatch(
          navigationDetails(details),
        ),
      createdTarget: (details) =>
        webNavigationEvents.onCreatedNavigationTarget.dispatch({
          sourceFrameId: 0,
          timeStamp: Date.now(),
          ...details,
        }),
    },
    native: { reply: null, sent: [] },
    badge: { text: "", color: "" },
    alarms: {
      created: new Map(),
      fire(name) {
        alarmEvents.onAlarm.dispatch({ name, scheduledTime: Date.now() });
      },
    },
    tabs: new Map(),
    person: {
      openTab(tab = {}) {
        const opened = {
          id: nextTabId++,
          index: fake.tabs.size,
          windowId: 1,
          active: true,
          pinned: false,
          highlighted: false,
          incognito: false,
          discarded: false,
          autoDiscardable: true,
          groupId: -1,
          ...tab,
        } as chrome.tabs.Tab;
        created(opened);
        return opened;
      },
      switchTo(tabId) {
        const tab = fake.tabs.get(tabId);
        if (!tab) throw new Error(`No tab with id: ${tabId}.`);
        activate(tab);
      },
      focusWindow(windowId) {
        windowEvents.onFocusChanged.dispatch(windowId);
      },
    },
    opened: [],
    updated: [],
    removed: [],
    restartServiceWorker() {
      calls.push("serviceWorker.restart");
      for (const created of events) created.clear();
      for (const port of serviceWorkerPorts.splice(0)) port.disconnect();
    },
    fireStartup() {
      runtimeEvents.onStartup.dispatch();
    },
    fireInstalled(reason) {
      runtimeEvents.onInstalled.dispatch({ reason });
    },
  };

  const responders = new Map<string, object | ((params: object) => object)>();
  const debuggerEvents = {
    onEvent: event("debugger.onEvent"),
    onDetach: event("debugger.onDetach"),
  };
  const webNavigationEvents = {
    onCommitted: event("webNavigation.onCommitted"),
    onHistoryStateUpdated: event("webNavigation.onHistoryStateUpdated"),
    onCreatedNavigationTarget: event("webNavigation.onCreatedNavigationTarget"),
  };
  const alarmEvents = { onAlarm: event("alarms.onAlarm") };
  const tabEvents = {
    onRemoved: event("tabs.onRemoved"),
    onCreated: event("tabs.onCreated"),
    onActivated: event("tabs.onActivated"),
  };
  const windowEvents = { onFocusChanged: event("windows.onFocusChanged") };
  /** As Chrome makes a tab active: the one active before it in its window no longer is, and onActivated says so. */
  const activate = (tab: chrome.tabs.Tab) => {
    for (const other of fake.tabs.values())
      if (other.windowId === tab.windowId && other !== tab)
        other.active = false;
    tab.active = true;
    tabEvents.onActivated.dispatch({ tabId: tab.id, windowId: tab.windowId });
  };
  /** As Chrome reports a new tab: created, then activated when it opened in front. */
  const created = (tab: chrome.tabs.Tab) => {
    fake.tabs.set(tab.id as number, tab);
    tabEvents.onCreated.dispatch({ ...tab, active: tab.active });
    if (tab.active) activate(tab);
  };
  const storageChanged = event("storage.onChanged");
  let nextTabId = 1000;

  const navigationDetails = (
    details: Partial<chrome.webNavigation.WebNavigationTransitionCallbackDetails>,
  ) => ({
    tabId: 1,
    frameId: 0,
    parentFrameId: -1,
    url: "about:blank",
    processId: 0,
    timeStamp: Date.now(),
    transitionType: "link",
    transitionQualifiers: [],
    ...details,
  });

  const removeAttached = (target: chrome.debugger.Debuggee) => {
    const index = fake.debugger.attached.findIndex(
      (debuggee) => debuggee.tabId === target.tabId,
    );
    if (index >= 0) fake.debugger.attached.splice(index, 1);
  };

  const storageArea = (areaName: "local" | "session" | "managed") => {
    const map = fake.storage[areaName];
    const changed = event(`storage.${areaName}.onChanged`);
    const notify = (changes: Record<string, chrome.storage.StorageChange>) => {
      if (Object.keys(changes).length === 0) return;
      changed.dispatch(changes);
      storageChanged.dispatch(changes, areaName);
    };
    notifyStorage[areaName] = notify;
    const area: Record<string, unknown> = {
      async get(keys?: string | string[] | Json | null) {
        calls.push(`storage.${areaName}.get`);
        const result: Json = {};
        if (keys === null || keys === undefined) {
          for (const [key, value] of map) result[key] = structuredClone(value);
        } else if (typeof keys === "string" || Array.isArray(keys)) {
          for (const key of typeof keys === "string" ? [keys] : keys)
            if (map.has(key)) result[key] = structuredClone(map.get(key));
        } else {
          for (const [key, fallback] of Object.entries(keys))
            result[key] = structuredClone(
              map.has(key) ? map.get(key) : fallback,
            );
        }
        return result;
      },
      onChanged: changed,
    };
    if (areaName !== "managed") {
      area.set = async (items: Json) => {
        calls.push(`storage.${areaName}.set`);
        const changes: Record<string, chrome.storage.StorageChange> = {};
        for (const [key, value] of Object.entries(items)) {
          const next = jsonCopy(value);
          if (map.has(key) && isDeepStrictEqual(map.get(key), next)) continue;
          changes[key] = map.has(key)
            ? { oldValue: map.get(key), newValue: next }
            : { newValue: next };
          map.set(key, next);
        }
        notify(changes);
      };
      area.remove = async (keys: string | string[]) => {
        calls.push(`storage.${areaName}.remove`);
        const changes: Record<string, chrome.storage.StorageChange> = {};
        for (const key of typeof keys === "string" ? [keys] : keys) {
          if (!map.has(key)) continue;
          changes[key] = { oldValue: map.get(key) };
          map.delete(key);
        }
        notify(changes);
      };
    }
    if (areaName === "local" || areaName === "session") {
      area.setAccessLevel = async (access: { accessLevel: string }) => {
        calls.push(`storage.${areaName}.setAccessLevel`);
        if (areaName === "local") fake.storage.accessLevel = access.accessLevel;
        else fake.storage.sessionAccessLevel = access.accessLevel;
      };
    }
    return area;
  };

  const originGranted = (origin: string) =>
    fake.permissions.granted.has(origin) ||
    fake.permissions.granted.has("<all_urls>");

  /** Test-only path: delivers as an extension page unless the sender is overridden. Never part of chrome.runtime. */
  const sendMessageFrom = async (
    message: unknown,
    senderOverride?: Partial<chrome.runtime.MessageSender>,
  ): Promise<unknown> => {
    calls.push("runtime.sendMessage");
    if (!runtimeEvents.onMessage.hasListeners())
      throw new Error(
        "Could not establish connection. Receiving end does not exist.",
      );
    return deliver(runtimeEvents.onMessage, message, {
      ...extensionPageSender(),
      ...senderOverride,
    });
  };

  const chromeApi = {
    runtime: {
      lastError: undefined as { message: string } | undefined,
      id: extensionId,
      getURL: (path: string) => {
        calls.push("runtime.getURL");
        return `chrome-extension://${extensionId}/${path.replace(/^\//, "")}`;
      },
      getManifest: () => {
        calls.push("runtime.getManifest");
        return {
          manifest_version: 3,
          name: "OpenBot Recorder",
          version: manifestVersion,
        };
      },
      async getContexts(filter: { contextTypes?: string[] } = {}) {
        calls.push("runtime.getContexts");
        const open =
          fake.offscreen.open &&
          (!filter.contextTypes ||
            filter.contextTypes.includes("OFFSCREEN_DOCUMENT"));
        return open
          ? [
              {
                contextType: "OFFSCREEN_DOCUMENT",
                contextId: "offscreen",
                tabId: -1,
                windowId: -1,
                frameId: -1,
                incognito: false,
              },
            ]
          : [];
      },
      sendMessage(
        message: unknown,
        optionsOrCallback?: unknown,
        maybeCallback?: unknown,
      ) {
        const callback = [optionsOrCallback, maybeCallback].find(
          (arg): arg is (response?: unknown) => void =>
            typeof arg === "function",
        );
        const result = sendMessageFrom(message);
        if (!callback) return result;
        result.then(
          (response) => callback(response),
          (error: Error) => {
            chromeApi.runtime.lastError = { message: error.message };
            try {
              callback();
            } finally {
              chromeApi.runtime.lastError = undefined;
            }
          },
        );
      },
      async sendNativeMessage(_host: string, message: object) {
        calls.push("runtime.sendNativeMessage");
        fake.native.sent.push(message);
        if (!fake.native.reply)
          throw new Error("Specified native messaging host not found.");
        return fake.native.reply(message);
      },
      connect(info: { name?: string } = {}) {
        calls.push("runtime.connect");
        return openPort(info.name ?? "", extensionPageSender()).far;
      },
      ...runtimeEvents,
    },
    storage: {
      local: storageArea("local"),
      session: storageArea("session"),
      managed: storageArea("managed"),
      onChanged: storageChanged,
    },
    permissions: {
      async request(permissions: chrome.permissions.Permissions) {
        calls.push("permissions.request");
        fake.permissions.requests.push(permissions);
        if (fake.permissions.answer) {
          for (const name of permissions.permissions ?? [])
            fake.permissions.granted.add(name);
          for (const origin of permissions.origins ?? [])
            fake.permissions.granted.add(origin);
        }
        return fake.permissions.answer;
      },
      async contains(permissions: chrome.permissions.Permissions) {
        calls.push("permissions.contains");
        return (
          (permissions.permissions ?? []).every((name) =>
            fake.permissions.granted.has(name),
          ) && (permissions.origins ?? []).every(originGranted)
        );
      },
    },
    scripting: {
      async executeScript(
        injection: chrome.scripting.ScriptInjection<unknown[], unknown>,
      ) {
        calls.push("scripting.executeScript");
        fake.scripting.executed.push(injection);
        const refused = fake.scripting.refuseFrames;
        if (
          refused &&
          injection.target.frameIds?.some((id) => refused.includes(id))
        )
          throw new Error("Cannot access contents of the frame");
        return [];
      },
      async registerContentScripts(
        scripts: chrome.scripting.RegisteredContentScript[],
      ) {
        calls.push("scripting.registerContentScripts");
        for (const script of scripts) {
          if (
            fake.scripting.registered.some(
              (existing) => existing.id === script.id,
            )
          )
            throw new Error(`Duplicate script ID '${script.id}'`);
          fake.scripting.registered.push(script);
        }
      },
      async unregisterContentScripts(filter: { ids?: string[] } = {}) {
        calls.push("scripting.unregisterContentScripts");
        fake.scripting.registered = fake.scripting.registered.filter(
          (script) =>
            filter.ids !== undefined && !filter.ids.includes(script.id),
        );
      },
    },
    // Chrome's errors, word for word: OffscreenCreateDocumentFunction::Run and OffscreenCloseDocumentFunction::Run in
    // Chromium's extensions/browser/api/offscreen/offscreen_api.cc.
    offscreen: {
      async createDocument(parameters: chrome.offscreen.CreateParameters) {
        calls.push("offscreen.createDocument");
        if (fake.offscreen.open)
          throw new Error("Only a single offscreen document may be created.");
        fake.offscreen.open = true;
        fake.offscreen.created.push(parameters);
        documentCreated.dispatch(parameters);
      },
      async closeDocument() {
        calls.push("offscreen.closeDocument");
        if (!fake.offscreen.open)
          throw new Error("No current offscreen document.");
        fake.offscreen.open = false;
        documentClosed.dispatch();
      },
      async hasDocument() {
        calls.push("offscreen.hasDocument");
        return fake.offscreen.open;
      },
    },
    debugger: {
      async attach(target: chrome.debugger.Debuggee, _version: string) {
        calls.push("debugger.attach");
        if (fake.debugger.refuseAttach)
          throw new Error(fake.debugger.refuseAttach);
        if (
          fake.debugger.attached.some(
            (debuggee) => debuggee.tabId === target.tabId,
          )
        )
          throw new Error(
            "Another debugger is already attached to the tab with id: " +
              target.tabId,
          );
        fake.debugger.attached.push(target);
      },
      async detach(target: chrome.debugger.Debuggee) {
        calls.push("debugger.detach");
        removeAttached(target);
      },
      async sendCommand(
        target: chrome.debugger.Debuggee,
        method: string,
        params?: object,
      ) {
        calls.push("debugger.sendCommand");
        if (
          !fake.debugger.attached.some(
            (debuggee) => debuggee.tabId === target.tabId,
          )
        )
          throw new Error(
            `Debugger is not attached to the tab with id: ${target.tabId}`,
          );
        fake.debugger.commands.push({ target, method, params });
        const responder = responders.get(method);
        return typeof responder === "function"
          ? responder(params ?? {})
          : (responder ?? {});
      },
      async getTargets() {
        calls.push("debugger.getTargets");
        return fake.debugger.targets();
      },
      ...debuggerEvents,
    },
    webNavigation: webNavigationEvents,
    tabs: {
      async get(tabId: number) {
        calls.push("tabs.get");
        const tab = fake.tabs.get(tabId);
        if (!tab) throw new Error(`No tab with id: ${tabId}.`);
        return tab;
      },
      async query(query: chrome.tabs.QueryInfo = {}) {
        calls.push("tabs.query");
        return [...fake.tabs.values()].filter(
          (tab) =>
            matches(tab.active, query.active) &&
            matches(tab.windowId, query.windowId) &&
            (typeof query.url !== "string" || tab.url === query.url),
        );
      },
      async create(props: chrome.tabs.CreateProperties) {
        calls.push("tabs.create");
        if (props.url) fake.opened.push(props.url);
        const tab = {
          id: nextTabId++,
          index: fake.tabs.size,
          windowId: 1,
          active: props.active ?? true,
          url: props.url,
          pinned: false,
          highlighted: false,
          incognito: false,
          discarded: false,
          autoDiscardable: true,
          groupId: -1,
        } as chrome.tabs.Tab;
        created(tab);
        return tab;
      },
      async update(tabId: number, props: chrome.tabs.UpdateProperties) {
        calls.push("tabs.update");
        const tab = fake.tabs.get(tabId);
        if (!tab) throw new Error(`No tab with id: ${tabId}.`);
        fake.updated.push({ tabId, props });
        if (props.active === true) {
          if (!tab.active) activate(tab);
        } else if (props.active === false) tab.active = false;
        if (props.url !== undefined) tab.url = props.url;
        return tab;
      },
      /** As Chrome does: closes each id in turn and rejects at the first unknown one, leaving the earlier ones closed. */
      async remove(tabIds: number | number[]) {
        calls.push("tabs.remove");
        for (const tabId of typeof tabIds === "number" ? [tabIds] : tabIds) {
          const tab = fake.tabs.get(tabId);
          if (!tab) throw new Error(`No tab with id: ${tabId}.`);
          fake.tabs.delete(tabId);
          fake.removed.push(tabId);
          tabEvents.onRemoved.dispatch(tabId, {
            windowId: tab.windowId,
            isWindowClosing: false,
          });
        }
      },
      ...tabEvents,
    },
    windows: { WINDOW_ID_NONE: -1, ...windowEvents },
    action: {
      async setBadgeText(details: { text: string }) {
        calls.push("action.setBadgeText");
        fake.badge.text = details.text;
      },
      async setBadgeBackgroundColor(details: {
        color: string | [number, number, number, number];
      }) {
        calls.push("action.setBadgeBackgroundColor");
        fake.badge.color = String(details.color);
      },
    },
    alarms: {
      async create(
        nameOrInfo: string | chrome.alarms.AlarmCreateInfo,
        info?: chrome.alarms.AlarmCreateInfo,
      ) {
        calls.push("alarms.create");
        if (typeof nameOrInfo === "string")
          fake.alarms.created.set(
            nameOrInfo,
            info ?? ({} as chrome.alarms.AlarmCreateInfo),
          );
        else fake.alarms.created.set("", nameOrInfo);
      },
      async get(name = "") {
        calls.push("alarms.get");
        return fake.alarms.created.has(name)
          ? { name, scheduledTime: Date.now() }
          : undefined;
      },
      async clear(name = "") {
        calls.push("alarms.clear");
        return fake.alarms.created.delete(name);
      },
      ...alarmEvents,
    },
  };

  // What Chrome gives an offscreen document: "The runtime API is the only extensions API supported by offscreen
  // documents", and of it only messaging, getURL and id (the rest of the keys a real document lists are enums). Its own
  // onMessage and onConnect hear nothing in this fake: the Recorder's document only talks over the port it opens.
  const documentSender = (): chrome.runtime.MessageSender => ({
    id: extensionId,
    url: `chrome-extension://${extensionId}/offscreen.html`,
    origin: `chrome-extension://${extensionId}`,
  });
  const offscreenApi = {
    runtime: {
      id: extensionId,
      getURL: chromeApi.runtime.getURL,
      connect(info: { name?: string } = {}) {
        calls.push("runtime.connect");
        return openPort(info.name ?? "", documentSender()).far;
      },
      sendMessage: (message: unknown) =>
        sendMessageFrom(message, documentSender()),
      onMessage: createEvent(
        "offscreen.runtime.onMessage",
        calls,
        installation,
      ),
      onConnect: createEvent(
        "offscreen.runtime.onConnect",
        calls,
        installation,
      ),
    },
  };
  const surfaces: Record<ChromeContext, typeof chrome> = {
    "service-worker": chromeApi as unknown as typeof chrome,
    "offscreen-document": offscreenApi as unknown as typeof chrome,
  };
  fake.apis = surfaces;

  Object.defineProperty(globalThis, "chrome", {
    configurable: true,
    enumerable: true,
    get: () => (belongsTo.getStore() ?? installation).chrome(),
    // A test that sets its own `chrome` replaces the fake.
    set(value: unknown) {
      Object.defineProperty(globalThis, "chrome", {
        configurable: true,
        enumerable: true,
        writable: true,
        value,
      });
    },
  });
  return fake;
}