@tapcue/extension-sdk 0.1.0

package/src/testing/test-host.ts

@@ -0,0 +1,2330 @@
+/**
+ * A deterministic, in-process stand-in for the Tapcue extension host.
+ *
+ * It is not a simulator of V8: it is a faithful implementation of the *policy*
+ * the real host enforces at the op boundary — effective grants, result
+ * validation, scope-type namespacing, subject round-tripping, batch
+ * reconciliation, cancellation and stale generations, quotas. Anything the real
+ * host would reject, this rejects.
+ *
+ * Nothing here is a security boundary. It exists so an extension's tests can
+ * prove it behaves correctly when a permission is denied, a query is cancelled,
+ * or a service misbehaves.
+ */
+
+import type {
+  BridgeCapability,
+  BridgeValue,
+  CacheCapability,
+  ClipboardCapability,
+  ClipboardImage,
+  ExecCapability,
+  ExecResult,
+  FileEntry,
+  FilesCapability,
+  QueriesCapability,
+  QueryRow,
+  QueryValue,
+  McpSession,
+  McpTool,
+  Color,
+  EnvironmentSnapshot,
+  HttpCapability,
+  LocationSnapshot,
+  NativeActionsCapability,
+  ImageHandle,
+  Layer,
+  OverlayEvent,
+  OverlaySession,
+  OverlaySpec,
+  Point,
+  Rect,
+  SaveFile,
+  ScreenCapability,
+  SvgNode,
+  FontFamily,
+  InvocationContextCapability,
+  ProcessInfo,
+  SettingsSnapshot,
+  StorageCapability,
+  StorageHandle,
+  WritableProcessManager,
+  WritableSettings,
+} from "../capabilities.js";
+import type {
+  DefinedScope,
+  ExtensionDefinition,
+  ProvisionHandlers,
+  WorkspaceRoot,
+} from "../define-extension.js";
+import { ExtensionError, cancelledError } from "../errors.js";
+import {
+  type LocaleCatalogs,
+  type Translate,
+  createTranslator,
+  resolveCatalog,
+} from "../i18n.js";
+import type { JsonValue } from "../json.js";
+import {
+  DEFAULT_ACTION_ID,
+  SLOT_TYPES,
+  type ExtensionManifest,
+  type ExecGrant,
+  type QueryGrant,
+  type FileReadGrant,
+  type ManifestCommand,
+  type ManifestContribution,
+  type ManifestProvision,
+  type ManifestPermissions,
+  coerceSetting,
+  effectiveGrants,
+  iconProblem,
+  namespacedItemId,
+  permissionUnits,
+  scopeTypePrefix,
+  settingsDefaults,
+  validateManifest,
+} from "../manifest.js";
+import { PERMISSION_UNITS } from "../permission-units.js";
+import type { Chart, Scene, SceneAction, SceneBlock, WebViewScene } from "../scene.js";
+import { applyAction, driveView, renderView } from "../view-runtime.js";
+import { type Signal, applySettingChange, settingSignal } from "../reactive.js";
+import type { ActionPatch, DataModel, PatchOp, ViewResult } from "../view.js";
+import {
+  CONTRIBUTABLE_SCOPE_TYPES,
+  CONTRIBUTION_MATCH_FIELDS,
+  NATIVE_SCOPE_TYPES,
+  type ActionResult,
+  type ContributableScopeType,
+  type ContributionHandlers,
+  type NativeSubjects,
+  type CommandItem,
+  type ActionContext,
+  type ItemScope,
+  type NavigationCapability,
+  type QueryResult,
+  type RecentsCapability,
+} from "../types.js";
+import { colorHex } from "../capabilities.js";
+import { FakeHttpBroker, type HttpRoute, type RecordedRequest, redact } from "./http-fake.js";
+
+/**
+ * Every field of the subject Tapcue projects for a contributable native scope — the shape
+ * `NativeSubjects` declares, as data, so the fake can check a test's fixture against it.
+ *
+ * Wider than `CONTRIBUTION_MATCH_FIELDS`: an extension *receives* the whole subject (a file's
+ * `path` included, which is what a contribution is usually for) while a `when` predicate may only
+ * match on a field naming a *kind* of subject. Reading a path you were handed and declaring
+ * interest in every path there is are different asks.
+ */
+const NATIVE_SUBJECT_FIELDS: Readonly<Record<ContributableScopeType, readonly string[]>> =
+  Object.freeze({
+    application: ["bundleId", "name"],
+    file: ["path", "name", "extension", "isDirectory"],
+    "file.folder": ["path", "name", "extension", "isDirectory"],
+  });
+
+export interface HostLimits {
+  /**
+   * Rows in one batch (architecture §14). A `query` that returns an array returns one batch, so
+   * this is also the cap on the simple case.
+   */
+  maxItemsPerBatch: number;
+  /**
+   * Rows across every batch of one invocation (architecture §14) — **five times the batch cap**,
+   * and it used to be equal to it. That made the deterministic host stricter than the host it
+   * stands in for: a catalog bigger than one batch (a design system's 242 swatches) was rejected
+   * here and accepted in production, which is the wrong direction for a policy fake to be wrong in.
+   */
+  maxItemsPerInvocation: number;
+  maxResultBytes: number;
+  maxScopeSubjectBytes: number;
+  maxRedirects: number;
+  maxConcurrentRequests: number;
+  maxResponseBytes: number;
+  /** Query and detail wall time (architecture §14). */
+  defaultDeadlineMs: number;
+  /** User-action wall time: an action waits on a person, a query waits on nobody. */
+  defaultActionDeadlineMs: number;
+}
+
+export const DEFAULT_LIMITS: HostLimits = {
+  maxItemsPerBatch: 200,
+  maxItemsPerInvocation: 1_000,
+  maxResultBytes: 8 * 1024 * 1024,
+  maxScopeSubjectBytes: 4 * 1024,
+  maxRedirects: 4,
+  maxConcurrentRequests: 4,
+  maxResponseBytes: 8 * 1024 * 1024,
+  defaultDeadlineMs: 2_000,
+  defaultActionDeadlineMs: 30_000,
+};
+
+/** A file the host would find under one `files.read` grant. */
+export interface FakeFile {
+  name: string;
+  content: string;
+  modifiedAt?: number;
+}
+
+/**
+ * What a declared `queries` entry returns when it is run.
+ *
+ * A function rather than only rows, because the values that fill the `?` holes are the half of a
+ * stored query a test most needs to pin: a statement whose `LIMIT ?` is ignored looks identical to
+ * one that honours it until a fixture can see the binding.
+ */
+export type FakeQuery = QueryRow[] | ((values: QueryValue[]) => QueryRow[]);
+
+/** What a declared `exec` entry does when it is run. */
+export interface FakeExec {
+  /**
+   * For an argv entry: given the *filled* argv, what it writes.
+   *
+   * Return a string for the ordinary case, or `{ stderr, exitCode }` to model a program that ran
+   * and *refused* — a CLI that is installed but not signed in, say. **Throwing is a different
+   * thing**: it models the binary not being runnable at all, which is what `run` rejects on.
+   */
+  run?(argv: string[]): string | { stdout?: string; stderr?: string; exitCode?: number };
+  /** For a `protocol: "mcp"` entry: the tools it offers and what each returns. */
+  tools?: McpTool[];
+  call?(name: string, args: Record<string, JsonValue>): JsonValue;
+}
+
+export interface TestHostOptions {
+  manifest: ExtensionManifest;
+  extension: ExtensionDefinition;
+  /**
+   * The files each `files.read` grant finds, keyed by the grant's index in the manifest.
+   *
+   * Keyed by index rather than by path on purpose: the index is the whole of what the guest can
+   * name, so a test that had to invent a path would be testing an interface the extension does not
+   * have.
+   */
+  files?: Record<number, FakeFile[]>;
+  /** What each declared `exec` id does, keyed by its id. */
+  exec?: Record<string, FakeExec>;
+  /** What each declared `queries` id returns, keyed by its id. */
+  queries?: Record<string, FakeQuery>;
+  /**
+   * Which of the manifest's *optional* permissions the user approved. Defaults to
+   * all of them. Required permissions are always granted: denying one means the
+   * extension is not enabled, which is an install-time outcome, not a runtime one.
+   */
+  approvedOptional?: ManifestPermissions;
+  locales?: LocaleCatalogs;
+  http?: readonly HttpRoute[];
+  location?: LocationSnapshot | null;
+  /**
+   * The machine's installed fonts, as the host would report them. The fake sorts them the way the
+   * real host must (§ Local Font Access): install order is not something a guest may observe.
+   */
+  fonts?: readonly FontFamily[];
+  /**
+   * The processes running on the machine, as the host would report them. The fake sorts them by
+   * pid (launch order must not leak) and strips each `command` (argv) unless `process.command` is
+   * granted — the same policy the real host enforces. A test that wants a live list re-reads
+   * `list()` after mutating this via `advanceTime`-style fixtures; here it is a fixed snapshot.
+   */
+  processes?: readonly ProcessInfo[];
+  /**
+   * The fake desktop an overlay is drawn over, and what the user does on it.
+   *
+   * `colorAt` is the screen's contents — a function, so a test can paint whatever it
+   * needs (a gradient, one flat colour, a checkerboard). `events` is what the user does,
+   * in order; the stream ends with `cancelled` after the last one, because a user who
+   * walks away is a case an overlay must survive.
+   */
+  screen?: {
+    bounds?: Rect;
+    colorAt?: (point: Point) => Color;
+    events?: readonly OverlayEvent[];
+    /**
+     * The user closing a `coach` card. Without it a card stays up until the extension closes it,
+     * which is what one does on a real screen.
+     */
+    dismissCoach?: boolean;
+  };
+  /**
+   * The live WebView surface a `canvas` scope presents. `respond` is what the WebView's own
+   * code replies when the isolate asks it something over `ctx.bridge` — a test scripts it (a
+   * PNG for an "export" request, say). It is deliberately a separate, untrusted-looking
+   * object: the fake returns exactly what `respond` gives back, so a test proves the isolate
+   * validates the reply rather than trusting it.
+   */
+  surface?: {
+    respond?(message: BridgeValue): BridgeValue | Promise<BridgeValue>;
+  };
+  settings?: Record<string, JsonValue>;
+  /** How Tapcue writes a `Color` to the clipboard — the *user's* preference, not the extension's. */
+  colorFormat?: "hex" | "rgb" | "hsl";
+  environment?: Partial<EnvironmentSnapshot>;
+  limits?: Partial<HostLimits>;
+  /** Deterministic clock, in ms. Advance it with `host.advanceTime`. */
+  now?: number;
+}
+
+/**
+ * Which handler is running. Interactive capabilities — ones that take over the
+ * screen or the keyboard — exist only in `invoke`: a `query` runs on a keystroke,
+ * and a keystroke must never be able to hand an extension the whole display.
+ */
+export type InvocationKind = "query" | "detail" | "invoke";
+
+export interface Diagnostic {
+  level: "info" | "warn" | "error";
+  message: string;
+}
+
+export interface QueryOptions {
+  query?: string;
+  arguments?: Record<string, string>;
+  limit?: number;
+}
+
+export interface ScopeSession {
+  type: string;
+  scopeId: string;
+  items(options?: { query?: string; limit?: number }): Promise<CommandItem[]>;
+  detail(itemId: string): Promise<Scene | null>;
+  invoke(itemId: string, actionId: string): Promise<ActionResult>;
+  /**
+   * Present a `canvas` scope's WebView surface, exactly as entering the scope does. Returns
+   * the `WebViewScene` (or a loading/error scene). While it is up, `ctx.bridge` is reachable
+   * from the footer actions — so call this before `act`, as the shell would.
+   */
+  surface(): Promise<Scene>;
+  /** Run a `canvas` scope's footer action. No row, so no itemId — that is the whole point. */
+  act(actionId: string): Promise<ActionResult>;
+  /**
+   * Render a scope's interactive `view` detail for the selected row, exactly as selecting it
+   * does (docs/architecture/extension-ui-interactive.md). Returns the initial
+   * `{view, model, actions}`; drive interaction with `viewAction`.
+   */
+  view(itemId: string): Promise<ViewResult>;
+  /**
+   * Fire one of the view's declared actions with the model the shell would hand back — the
+   * initial model with any two-way-bound field (a `Form` value) updated to what the user chose.
+   * Returns the model patch the action produced.
+   */
+  viewAction(
+    itemId: string,
+    actionId: string,
+    args: JsonValue[],
+    model: DataModel,
+  ): Promise<ActionPatch>;
+  /**
+   * Present a view and keep it alive, as showing its surface does. Renders the initial frame and
+   * starts whatever its `whileVisible` setups registered; each signal write those make streams a
+   * patch into `patches`. `stop()` ends the visible period as hiding the surface does, running the
+   * cleanups. A view with no setups is finished the moment it returns.
+   */
+  liveView(itemId: string): Promise<LiveViewSession>;
+}
+
+/** A presented view: its initial render, and the patches its signal writes have streamed. */
+export interface LiveViewSession {
+  readonly initial: ViewResult;
+  /** Every streamed patch, in order — one entry per microtask batch of signal writes. */
+  readonly patches: PatchOp[][];
+  /** End the visible period, as hiding the surface does; the setups' cleanups run. */
+  stop(): Promise<void>;
+}
+
+/**
+ * **Standing inside a native scope, the way the user does** — and asking what this extension
+ * adds to it (architecture §11.3).
+ *
+ * The subject is Tapcue's here, not the extension's: the fake projects and validates it exactly
+ * as the shell does, then applies each `contributes[].when` predicate *before* calling anything.
+ * That order is the policy, not an optimization — a contribution that did not match is never told
+ * the subject exists, so a test can prove an extension learns nothing about apps it never named.
+ */
+export interface NativeScopeSession {
+  type: ContributableScopeType;
+  scopeId: string;
+  /**
+   * The contribution ids whose `when` admits this subject — the gate, readable. Empty means the
+   * extension is not called at all for this scope, which is the normal case for most subjects.
+   */
+  readonly contributions: string[];
+  /** Rows this contribution adds. Throws if its `when` does not admit the session's subject. */
+  items(
+    contributionId: string,
+    options?: { query?: string; limit?: number },
+  ): Promise<CommandItem[]>;
+  invoke(contributionId: string, itemId: string, actionId: string): Promise<ActionResult>;
+}
+
+/** What `enterNative` needs to stand somewhere: which scope, and what it is about. */
+export interface NativeScopeEntry {
+  type: ContributableScopeType;
+  /** The scope's subject — `NativeSubjects[type]`. Validated against the declared shape. */
+  subject: Record<string, JsonValue>;
+  /**
+   * What the scope's **owner** does with the rows a contributor returns, which is the owner's
+   * decision and not the contributor's. Defaults to `remote`, because that is what every
+   * contributable native scope is today: their own sources take the query and narrow on it, so
+   * the query is forwarded and the rows are shown as returned. Pass `catalog` to prove an
+   * extension still behaves when it lands in a scope that filters locally — there the query
+   * arrives **empty**, which is the trap worth having a test for.
+   */
+  queryMode?: "catalog" | "remote";
+  /** Override the scope id the shell would assign. Rarely needed; it is only a cache key. */
+  scopeId?: string;
+}
+
+export interface TestHost {
+  query(commandId: string, options?: QueryOptions): Promise<CommandItem[]>;
+  invoke(commandId: string, itemId: string, actionId: string): Promise<ActionResult>;
+  /**
+   * Run a `no-view` command's own row, as pressing Enter on it does: no item, and
+   * the reserved `default` action id.
+   */
+  run(commandId: string): Promise<ActionResult>;
+  /** Enter an item's scope, exactly as pressing Enter on it would. */
+  enter(item: CommandItem): ScopeSession;
+  /**
+   * Stand inside a **native** scope — an app's, a file's — as the user does when they Tab into
+   * it, and exercise whatever this extension contributes there (architecture §11.3).
+   *
+   * The counterpart to `enter`, which refuses a native scope for a good reason: entering one
+   * *as a subject you produced* is Tapcue's business to render. This is the other direction —
+   * the scope already exists, the user is already in it, and the only thing under test is the
+   * extension's own rows.
+   */
+  enterNative(scope: NativeScopeEntry): NativeScopeSession;
+  /** Abort the in-flight invocation (user typed again, panel closed, revocation). */
+  cancel(): void;
+  /** Revoke an optional permission while the extension is installed and running. */
+  revoke(unit: string): void;
+  advanceTime(ms: number): void;
+  /** Replace the process table `ctx.process.list()` reads, so a test can move the world between
+   *  two `list()` calls and assert what the extension made of the change. */
+  setProcesses(processes: readonly ProcessInfo[]): void;
+  /** Every batch the last query yielded, in order. One entry for an array return. */
+  readonly batches: CommandItem[][];
+  readonly requests: RecordedRequest[];
+  readonly diagnostics: Diagnostic[];
+  readonly clipboard: string[];
+  /** Every image the extension wrote to the clipboard (text/colour writes stay in `clipboard`). */
+  readonly clipboardImages: ClipboardImage[];
+  /**
+   * Every secret the extension wrote — deliberately *not* in `clipboard`. A secret carries the
+   * "do not remember this" pasteboard markers, and Tapcue's own clipboard history honours them,
+   * so the value never enters the history `clipboard` stands for.
+   */
+  readonly clipboardSecrets: string[];
+  readonly opened: string[];
+  /** Every binary run, as the *filled* argv the host would have spawned. No shell, so no string. */
+  readonly ran: { id: string; argv: string[] }[];
+  /** Every stored query run, with the values bound to its `?` holes, in order. */
+  readonly queried: { id: string; values: QueryValue[] }[];
+  /**
+   * **Ask the `workspace.roots` slot**, as Tapcue does when the launcher opens.
+   *
+   * Models the gate as well as the call: without the `workspace.roots` grant the host never asks,
+   * so this answers empty *without running the handler* — the absence of a capability is the check
+   * (§7.1), and a test that only saw an empty array could not tell a denied slot from an extension
+   * that found no projects.
+   */
+  workspaceRoots(options?: { provisionId?: string; limit?: number }): Promise<WorkspaceRoot[]>;
+  readonly notifications: { title: string; body?: string }[];
+  /** Every file the extension asked the host to save. The host owns where it lands. */
+  readonly saves: RecordedSave[];
+  /** Every WebView surface a `canvas` scope presented, in order. */
+  readonly surfaces: RecordedSurface[];
+  /** Every message the extension sent a live surface over `ctx.bridge`. */
+  readonly bridgeMessages: BridgeValue[];
+  /** Every overlay the extension opened, with every frame it drew on it. */
+  readonly overlays: RecordedOverlay[];
+  /**
+   * Every pid the extension asked the host to kill / to bring to the front, in order. Both are
+   * fire-and-forget effects, so a test asserts what was *requested* — the host owns the confirm.
+   */
+  readonly kills: number[];
+  readonly activated: number[];
+  /**
+   * Every scope the extension asked the host to enter, in order — the items it handed
+   * `ctx.navigate.enter`. Fire-and-forget like the two above: the *host* pushes the scope, so a
+   * test asserts what was asked for, then `host.enter(...)` that item to walk into it.
+   */
+  readonly navigations: CommandItem[];
+  /**
+   * Every setting write, in order, as `[key, value]`. The value has already landed in
+   * `settingsValues` — read it back with `ctx.settings.get` or assert the trail here.
+   */
+  readonly settingsWrites: [string, JsonValue][];
+  readonly generation: number;
+}
+
+/** A file the extension asked the host to save. The host sanitizes `name` and owns the path. */
+export interface RecordedSave {
+  name: string;
+  type: string;
+  data: Uint8Array;
+}
+
+/** A WebView surface a `canvas` scope presented. */
+export interface RecordedSurface {
+  entry: string;
+  title?: string;
+  actions: SceneAction[];
+}
+
+export function createTestHost(options: TestHostOptions): TestHost {
+  const problems = validateManifest(options.manifest);
+  if (problems.length > 0) {
+    const detail = problems.map((p) => `${p.path || "<root>"}: ${p.message}`).join("; ");
+    throw new Error(`invalid manifest: ${detail}`);
+  }
+
+  const manifest = options.manifest;
+  const limits: HostLimits = { ...DEFAULT_LIMITS, ...options.limits };
+  let grants = effectiveGrants(manifest, options.approvedOptional);
+  const requests: RecordedRequest[] = [];
+  const diagnostics: Diagnostic[] = [];
+  const clipboard: string[] = [];
+  const clipboardImages: ClipboardImage[] = [];
+  const clipboardSecrets: string[] = [];
+  /** This extension's recents, newest first — the fake for Tapcue's unified Recents. */
+  const recentsStore: CommandItem[] = [];
+  const opened: string[] = [];
+  const ran: { id: string; argv: string[] }[] = [];
+  /** Every stored query the extension ran, with the values it bound, in order. */
+  const queried: { id: string; values: QueryValue[] }[] = [];
+  const notifications: { title: string; body?: string }[] = [];
+  const saves: RecordedSave[] = [];
+  const surfaces: RecordedSurface[] = [];
+  const bridgeMessages: BridgeValue[] = [];
+  const overlays: RecordedOverlay[] = [];
+  /**
+   * Every pid the extension asked the host to kill / to bring to the front, in order. `kill` is
+   * fire-and-forget: the host would coalesce these into one confirm dialog and decide the signal
+   * with the user, and the extension never learns the outcome — so a test can only assert what it
+   * *requested*, which is exactly what these record.
+   */
+  const kills: number[] = [];
+  const activated: number[] = [];
+  /** Scopes the extension asked to enter, and settings it asked to change. Both are requests the
+   *  host carries out, so the fake records the ask — the same shape `kills` takes. */
+  const navigations: CommandItem[] = [];
+  const settingsWrites: [string, JsonValue][] = [];
+  /** The process table `ctx.process.list()` reads, mutable so a test can change the world between
+   *  two `list()` calls and assert what the extension made of the change. */
+  let processesFixture: readonly ProcessInfo[] = options.processes ?? [];
+  /**
+   * The WebView surface currently up, and the isolate's only handle to it. It is set when a
+   * `canvas` scope presents its surface and stays until another scope is entered — modelling
+   * the shell owning the surface, not the isolate: `ctx.bridge` reconnects to this rather than
+   * the isolate holding it across the eviction that almost certainly happened while drawing.
+   */
+  let liveSurface: { respond(m: BridgeValue): BridgeValue | Promise<BridgeValue> } | null = null;
+  /** The user's colour format, as the native Color provider would supply it. */
+  const colorFormat = options.colorFormat ?? "hex";
+  let batches: CommandItem[][] = [];
+  let currentKind: InvocationKind = "query";
+
+  /** Guest item id → the command whose query produced it. See `enter`. */
+  const itemOrigin = new Map<string, string>();
+  /**
+   * **Manifest contributions and their handlers, checked against each other at load.**
+   *
+   * Both directions fail, because both directions are half a contribution: a manifest entry with
+   * no handler promises the user rows nobody wrote, and a handler with no manifest entry is code
+   * the host will never call — and a handler that is never called is exactly the kind of silence
+   * this project has paid for before.
+   */
+  const contributions = new Map<
+    string,
+    { manifest: ManifestContribution; handlers: ContributionHandlers }
+  >();
+  {
+    const declared = manifest.contributes ?? [];
+    const handlers = options.extension.contributions ?? {};
+    for (const entry of declared) {
+      const handler = handlers[entry.id];
+      if (!handler) {
+        throw new Error(
+          `contributes["${entry.id}"] is declared in the manifest but has no handler in defineExtension({ contributions })`,
+        );
+      }
+      if (typeof handler.items !== "function") {
+        throw new Error(`contribution "${entry.id}" must declare an items handler`);
+      }
+      if (!(CONTRIBUTABLE_SCOPE_TYPES as readonly string[]).includes(entry.scope)) {
+        throw new Error(
+          `contribution "${entry.id}" targets "${entry.scope}", which is not a contributable native scope`,
+        );
+      }
+      contributions.set(entry.id, { manifest: entry, handlers: handler });
+    }
+    for (const id of Object.keys(handlers)) {
+      if (!contributions.has(id)) {
+        throw new Error(
+          `contributions["${id}"] has no matching contributes[] entry in the manifest — nothing would ever call it`,
+        );
+      }
+    }
+  }
+
+  /**
+   * **Manifest provisions and their handlers**, checked both directions like contributions, and
+   * for the same reason: half a provision is a slot Tapcue will ask about and nothing will answer,
+   * or an answer nothing will ever ask for.
+   */
+  const provisions = new Map<string, { manifest: ManifestProvision; handlers: ProvisionHandlers }>();
+  {
+    const declared = manifest.provides ?? [];
+    const handlers = options.extension.provisions ?? {};
+    for (const entry of declared) {
+      const handler = handlers[entry.id];
+      if (!handler) {
+        throw new Error(
+          `provides["${entry.id}"] is declared in the manifest but has no handler in defineExtension({ provisions })`,
+        );
+      }
+      if (!(SLOT_TYPES as readonly string[]).includes(entry.slot)) {
+        throw new Error(`provision "${entry.id}" fills "${entry.slot}", which is not a slot`);
+      }
+      if (entry.slot === "workspace.roots" && typeof handler.roots !== "function") {
+        throw new Error(`provision "${entry.id}" fills workspace.roots and must declare a roots handler`);
+      }
+      provisions.set(entry.id, { manifest: entry, handlers: handler });
+    }
+    for (const id of Object.keys(handlers)) {
+      if (!provisions.has(id)) {
+        throw new Error(
+          `provisions["${id}"] has no matching provides[] entry in the manifest — nothing would ever ask it`,
+        );
+      }
+    }
+  }
+
+  const scopes = new Map<string, DefinedScope<JsonValue>>();
+  for (const scope of options.extension.scopes) {
+    const prefix = scopeTypePrefix(manifest.id);
+    if (!scope.type.startsWith(prefix)) {
+      throw new Error(
+        `scope type "${scope.type}" must be namespaced "${prefix}…" — an extension cannot own a native subject type`,
+      );
+    }
+    // A layout and its source have to agree: a `canvas` scope draws a surface and has no rows,
+    // every other layout draws rows and has no surface. A handler the shell will never call is
+    // a handler an author will believe in, so the host rejects the mismatch rather than ignore it.
+    const layout = scope.spec.scheme.layout;
+    const isCanvas = layout === "canvas";
+    // A `pane` scope is the third rowless shape: one semantic pane, drawn from `view`/`detail`.
+    const isPane = layout === "pane";
+    if (isCanvas && !scope.spec.surface) {
+      throw new Error(`canvas scope "${scope.type}" must declare a surface handler`);
+    }
+    if (isCanvas && scope.spec.items) {
+      throw new Error(`canvas scope "${scope.type}" has no rows — declare surface, not items`);
+    }
+    if (isPane && scope.spec.items) {
+      throw new Error(`pane scope "${scope.type}" has no rows — declare view or detail, not items`);
+    }
+    if (isPane && scope.spec.surface) {
+      throw new Error(`surface is for a canvas scope; "${scope.type}" is a pane`);
+    }
+    if (isPane && !scope.spec.view && !scope.spec.detail) {
+      throw new Error(`pane scope "${scope.type}" must declare a view or detail handler`);
+    }
+    if (!isCanvas && !isPane && !scope.spec.items) {
+      throw new Error(`scope "${scope.type}" (${layout}) must declare an items handler`);
+    }
+    if (!isCanvas && scope.spec.surface) {
+      throw new Error(`surface is for a canvas scope; "${scope.type}" is ${layout}`);
+    }
+    scopes.set(scope.type, scope as DefinedScope<JsonValue>);
+  }
+
+  let nowMs = options.now ?? 0;
+  let generation = 0;
+  let controller = new AbortController();
+  let window = new AbortController();
+
+  const cacheStore = new Map<string, { value: string; expiresAt: number | null }>();
+  const storageStore = new Map<string, Map<string, string>>();
+  const settingsValues: Record<string, JsonValue> = {
+    ...settingsDefaults(manifest),
+    ...(options.settings ?? {}),
+  };
+  const declaredSettingKeys = new Set((manifest.settings ?? []).map((s) => s.key));
+
+  const broker = new FakeHttpBroker({
+    // Read through a getter so a revocation lands on the very next request.
+    get allowedHosts() {
+      return grants.http?.hosts ?? [];
+    },
+    routes: options.http ?? [],
+    limits,
+    record: (request) => requests.push(request),
+  });
+
+  const environment: EnvironmentSnapshot = {
+    locale: "en-US",
+    timeZone: "Europe/Berlin",
+    appearance: "light",
+    platform: "macos",
+    // Defaults to everything the manifest declared, because the common case a test is written for
+    // is "the integration is installed". A test about a *missing* app names the subset it wants.
+    installedApps: manifest.integratesWith ?? [],
+    ...options.environment,
+  };
+  const translate: Translate = createTranslator(
+    resolveCatalog(options.locales ?? {}, environment.locale, manifest.defaultLocale ?? "en"),
+    (key) => diagnostics.push({ level: "warn", message: `missing message catalog key "${key}"` }),
+  );
+
+  /**
+   * The two contexts, and the reason there are two: a `query` runs on a keystroke, so nothing
+   * that acts on the machine may be reachable from one. That used to be a runtime check. It
+   * is a type now — and the fake builds exactly the type the real host would hand over, or a
+   * test would prove something the compiler already forbids.
+   */
+  function makeContext(deadlineMs: number, kind: InvocationKind): ActionContext {
+    // The run window, not the invocation. A streaming handler observes `ctx.signal` to know it was
+    // told to stop, and `collect` ends a generator by aborting the *window* (`endRunWindow`);
+    // cancelling the invocation aborts the window too, so this sees both. Wired to
+    // `controller.signal` this used to see only a cancel, and the window machinery was inert.
+    const signal = window.signal;
+
+    const settings: WritableSettings = {
+      get<T extends JsonValue = JsonValue>(key: string): T {
+        if (!declaredSettingKeys.has(key)) {
+          throw new ExtensionError({
+            code: "invalid-request",
+            message: `setting "${key}" is not declared in the manifest`,
+          });
+        }
+        return settingsValues[key] as T;
+      },
+      all: () => Object.freeze({ ...settingsValues }),
+      // The watchable form. Same declaration check as `get` — a signal following a key the
+      // manifest does not name would be a cell nothing can ever write.
+      signal<T extends JsonValue = JsonValue>(key: string): Signal<T> {
+        if (!declaredSettingKeys.has(key)) {
+          throw new ExtensionError({
+            code: "invalid-request",
+            message: `setting "${key}" is not declared in the manifest`,
+          });
+        }
+        return settingSignal<T>(key, settingsValues[key] as T);
+      },
+      // The write is action-tier, so a `query` gets a snapshot whose `set` refuses — mirroring
+      // the real host, where the method is simply absent from a query's context. Throwing rather
+      // than silently dropping is the fake's job: a test that reaches for it from a keystroke
+      // should fail loudly, not pass with nothing written.
+      set(key: string, value: JsonValue): void {
+        if (kind !== "invoke") {
+          throw new ExtensionError({
+            code: "permission-denied",
+            message: "ctx.settings.set is only available while running an action",
+          });
+        }
+        // The manifest decides. An undeclared key is not a new setting and a `select` value that
+        // is not one of its options is not a new option — both are dropped, as the host drops them.
+        const coerced = coerceSetting(manifest, key, value);
+        if (coerced === undefined) {
+          diagnostics.push({
+            level: "warn",
+            message: `settings.set("${key}") ignored: not a declared setting, or the value is not its declared type`,
+          });
+          return;
+        }
+        settingsValues[key] = coerced;
+        settingsWrites.push([key, coerced]);
+        // What the real host's glue does after the op: the value is the isolate's now, so every
+        // live view following this key is written and re-armed without a round trip.
+        applySettingChange(key, coerced);
+      },
+    };
+
+    const http: HttpCapability | undefined = grants.http
+      ? {
+          fetch: (url, init) => broker.fetch(url, init, signal, {}),
+          client: (clientOptions) => ({
+            fetch: (url, init) => broker.fetch(url, init, signal, clientOptions?.headers ?? {}),
+          }),
+        }
+      : undefined;
+
+    const cache: CacheCapability | undefined = grants.cache
+      ? {
+          async get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined> {
+            const entry = cacheStore.get(key);
+            if (!entry) return undefined;
+            if (entry.expiresAt !== null && entry.expiresAt <= nowMs) {
+              cacheStore.delete(key);
+              return undefined;
+            }
+            return JSON.parse(entry.value) as T;
+          },
+          async set(key, value, setOptions) {
+            const encoded = JSON.stringify(value);
+            const quota = grants.cache?.maxBytes ?? 0;
+            const used = [...cacheStore.entries()]
+              .filter(([existing]) => existing !== key)
+              .reduce((total, [, entry]) => total + entry.value.length, 0);
+            if (used + encoded.length > quota) {
+              throw new ExtensionError({
+                code: "quota-exceeded",
+                message: `cache quota of ${quota} bytes exceeded`,
+              });
+            }
+            cacheStore.set(key, {
+              value: encoded,
+              expiresAt: setOptions?.ttlMs === undefined ? null : nowMs + setOptions.ttlMs,
+            });
+          },
+          async delete(key) {
+            cacheStore.delete(key);
+          },
+        }
+      : undefined;
+
+    const storage: StorageCapability | undefined = grants.storage
+      ? {
+          open(namespace: string): StorageHandle {
+            const bucket = storageStore.get(namespace) ?? new Map<string, string>();
+            storageStore.set(namespace, bucket);
+            return {
+              async get<T extends JsonValue = JsonValue>(key: string) {
+                const raw = bucket.get(key);
+                return raw === undefined ? undefined : (JSON.parse(raw) as T);
+              },
+              async set(key, value) {
+                const encoded = JSON.stringify(value);
+                const quota = grants.storage?.maxBytes ?? 0;
+                let used = 0;
+                for (const entries of storageStore.values()) {
+                  for (const [existingKey, existing] of entries) {
+                    if (entries === bucket && existingKey === key) continue;
+                    used += existing.length;
+                  }
+                }
+                if (used + encoded.length > quota) {
+                  throw new ExtensionError({
+                    code: "quota-exceeded",
+                    message: `storage quota of ${quota} bytes exceeded`,
+                  });
+                }
+                bucket.set(key, encoded);
+              },
+              async delete(key) {
+                bucket.delete(key);
+              },
+              async keys() {
+                return [...bucket.keys()];
+              },
+            };
+          },
+        }
+      : undefined;
+
+    // Each method exists only when its own permission unit is granted: the
+    // capability surface *is* the grant, so an extension never has to ask.
+    let context: InvocationContextCapability | undefined;
+    if (grants.context) {
+      context = {};
+      if (grants.context.frontmostApp) context.frontmostApp = async () => null;
+      if (grants.context.selectedText) context.selectedText = async () => null;
+      if (grants.context.selectedFiles) context.selectedFiles = async () => [];
+    }
+
+    // Machine-wide queries. Separate grants from the invocation trio above, because they answer a
+    // different question and a user approves them separately.
+    const fonts = grants.fonts
+      ? {
+          list: async () => {
+            if (signal.aborted) throw cancelledError();
+            // Sorted, always. The real host must not let install order leak, so neither does the
+            // fake — a test that relied on insertion order would be proving the wrong thing.
+            return [...(options.fonts ?? [])].sort((a, b) => a.family.localeCompare(b.family));
+          },
+        }
+      : undefined;
+
+    const location = grants.location
+      ? {
+          current: async () => {
+            if (signal.aborted) throw cancelledError();
+            return options.location ?? null;
+          },
+        }
+      : undefined;
+
+    // The processes on this machine. The read (`list`) is a machine fact like `fonts`, present on
+    // every context; the effects (`kill`, `activate`) sit on an action only, exactly as
+    // `clipboard.write` and `native.*` do. The whole object is keyed on the read being granted,
+    // which the manifest validator guarantees whenever `command`/`kill` are — so the type's
+    // `WritableProcessManager extends ReadonlyProcessManager` (list always present) holds.
+    let process: WritableProcessManager | undefined;
+    if (grants.process?.list) {
+      const withCommand = Boolean(grants.process.command);
+      process = {
+        list: async () => {
+          if (signal.aborted) throw cancelledError();
+          // Host-sorted by pid so launch order never leaks, and argv (`command`) stripped unless
+          // the separate `process.command` unit is granted — the sensitive half is its own denial.
+          return [...processesFixture]
+            .sort((a, b) => a.pid - b.pid)
+            .map((p) => (withCommand ? { ...p } : stripCommand(p)));
+        },
+      };
+      // Fire-and-forget: the op re-checks the phase, and the fake mirrors that by attaching the
+      // effects only in an action. The extension gets no outcome — the host coalesces and confirms
+      // these, and the next `list()` is how a list learns a process is gone.
+      if (grants.process.kill && kind === "invoke") {
+        process.kill = (pid: number) => {
+          kills.push(pid);
+        };
+        process.activate = (pid: number) => {
+          activated.push(pid);
+        };
+      }
+    }
+
+    /**
+     * **`files` — the grant index is the whole interface.**
+     *
+     * The fake refuses a grant the manifest did not declare and a name the listing did not return,
+     * which together are the real host's guarantee: the guest never composes a path, so there is
+     * nothing for it to escape with. `readText` is the same read, decoded.
+     */
+    let filesCapability: FilesCapability | undefined;
+    const declaredReads: FileReadGrant[] = grants.files?.read ?? [];
+    if (declaredReads.length > 0) {
+      const listing = (grant: number): FakeFile[] => {
+        if (!Number.isInteger(grant) || grant < 0 || grant >= declaredReads.length) {
+          throw new ExtensionError({
+            code: "permission-denied",
+            message: `files.read grant ${grant} was not declared`,
+          });
+        }
+        return options.files?.[grant] ?? [];
+      };
+      const bytesOf = (grant: number, name: string): Uint8Array => {
+        const file = listing(grant).find((candidate) => candidate.name === name);
+        if (!file) {
+          // Not "missing file": the guest may only name what the host listed, so an unknown name is
+          // an attempt to reach outside the grant, whether or not it meant to be.
+          throw new ExtensionError({
+            code: "permission-denied",
+            message: `"${name}" is not a file this grant matches`,
+          });
+        }
+        return new TextEncoder().encode(file.content);
+      };
+      filesCapability = {
+        async list(grant) {
+          return listing(grant).map(
+            (file): FileEntry => ({
+              name: file.name,
+              size: new TextEncoder().encode(file.content).length,
+              modifiedAt: file.modifiedAt ?? 0,
+            }),
+          );
+        },
+        async read(grant, name) {
+          return bytesOf(grant, name);
+        },
+        async readText(grant, name) {
+          return new TextDecoder().decode(bytesOf(grant, name));
+        },
+      };
+    }
+
+    /**
+     * **`queries` — the statement is fixed, the values are not.**
+     *
+     * The fake refuses an id the manifest did not declare and counts the `?` holes against the
+     * values supplied, which is the whole of what a guest could otherwise reshape. It cannot check
+     * the SQL itself — that is the real host's job, against a real read-only connection — so a test
+     * that wants to model a moved schema throws from its fixture.
+     */
+    let queriesCapability: QueriesCapability | undefined;
+    const declaredQueries: QueryGrant[] = grants.queries ?? [];
+    if (declaredQueries.length > 0) {
+      queriesCapability = {
+        async run(id, values = []) {
+          const grant = declaredQueries.find((candidate) => candidate.id === id);
+          if (!grant) {
+            throw new ExtensionError({
+              code: "permission-denied",
+              message: `query "${id}" was not declared`,
+            });
+          }
+          const holes = (grant.sql.match(/\?/g) ?? []).length;
+          if (values.length !== holes) {
+            throw new ExtensionError({
+              code: "invalid-argument",
+              message: `query "${id}" takes ${holes} value(s), got ${values.length}`,
+            });
+          }
+          const supplied = [...values];
+          queried.push({ id, values: supplied });
+          const fake = options.queries?.[id];
+          const rows = typeof fake === "function" ? fake(supplied) : (fake ?? []);
+          return rows.slice(0, limits.maxItemsPerBatch);
+        },
+      };
+    }
+
+    /**
+     * **`exec` — the template is the interface.**
+     *
+     * The fake fills the declared `{}` holes positionally and refuses a call whose argument count
+     * does not match, because that mismatch is the only way a guest could otherwise reshape argv.
+     * It records the *filled* argv, so a test asserts what would actually have been spawned.
+     */
+    let execCapability: ExecCapability | undefined;
+    const declaredExec: ExecGrant[] = grants.exec ?? [];
+    if (declaredExec.length > 0) {
+      const declaration = (id: string): ExecGrant => {
+        const found = declaredExec.find((grant) => grant.id === id);
+        if (!found) {
+          throw new ExtensionError({
+            code: "permission-denied",
+            message: `exec "${id}" was not declared`,
+          });
+        }
+        return found;
+      };
+      execCapability = {
+        async run(id, args = []) {
+          const grant = declaration(id);
+          if (grant.protocol === "mcp") {
+            throw new ExtensionError({
+              code: "invalid-argument",
+              message: `exec "${id}" speaks mcp — use ctx.exec.mcp(), not run()`,
+            });
+          }
+          const template = grant.args ?? [];
+          const holes = template.filter((part) => part === "{}").length;
+          if (args.length !== holes) {
+            throw new ExtensionError({
+              code: "invalid-argument",
+              message: `exec "${id}" takes ${holes} argument(s), got ${args.length}`,
+            });
+          }
+          let next = 0;
+          const argv = template.map((part) => (part === "{}" ? args[next++] : part));
+          ran.push({ id, argv });
+          const fake = options.exec?.[id];
+          const produced = fake?.run?.(argv) ?? "";
+          const result: ExecResult =
+            typeof produced === "string"
+              ? { stdout: produced, stderr: "", exitCode: 0, truncated: false }
+              : {
+                  stdout: produced.stdout ?? "",
+                  stderr: produced.stderr ?? "",
+                  exitCode: produced.exitCode ?? 0,
+                  truncated: false,
+                };
+          if (result.stdout.length > limits.maxResultBytes) {
+            return { ...result, stdout: result.stdout.slice(0, limits.maxResultBytes), truncated: true };
+          }
+          return result;
+        },
+        async mcp(id) {
+          const grant = declaration(id);
+          if (grant.protocol !== "mcp") {
+            throw new ExtensionError({
+              code: "invalid-argument",
+              message: `exec "${id}" is argv-invoked — use ctx.exec.run(), not mcp()`,
+            });
+          }
+          const fake = options.exec?.[id];
+          const session: McpSession = {
+            async listTools() {
+              return fake?.tools ?? [];
+            },
+            async callTool(name, args = {}) {
+              const tools = fake?.tools ?? [];
+              if (!tools.some((tool) => tool.name === name)) {
+                // The server's own refusal, modelled: a tool it does not offer is not callable, and
+                // `listTools` is how an extension is supposed to find that out.
+                throw new ExtensionError({
+                  code: "invalid-argument",
+                  message: `mcp server "${id}" offers no tool "${name}"`,
+                });
+              }
+              ran.push({ id, argv: ["mcp", name] });
+              return fake?.call?.(name, args) ?? null;
+            },
+          };
+          return session;
+        },
+      };
+    }
+
+    let clipboardCapability: ClipboardCapability | undefined;
+    if (grants.clipboard) {
+      clipboardCapability = {};
+      if (grants.clipboard.read) clipboardCapability.read = async () => clipboard.at(-1) ?? null;
+      // The write is an effect, so it exists only where effects are allowed.
+      if (grants.clipboard.write && kind === "invoke") {
+        clipboardCapability.write = async (value) => {
+          if (typeof value === "string") {
+            clipboard.push(value);
+          } else if ("secret" in value) {
+            // **The policy, not a convenience.** A secret is written with the markers that ask
+            // every clipboard manager — Tapcue's own history first — not to remember it, so it
+            // must not appear in `clipboard`, which is what stands in for that history here. A
+            // test asserting a password manager copied a password should be able to assert the
+            // password is *not* in the history, and that only works if the fake keeps them apart.
+            clipboardSecrets.push(value.secret);
+          } else if ("png" in value) {
+            // An image says *what*, not *how*: the host owns which pasteboard flavours a PNG
+            // becomes, exactly as it owns a colour's format. The fake just records the bytes.
+            clipboardImages.push(value);
+          } else {
+            // Tapcue formats a Color by the user's preference, not the extension's. The fake
+            // honours the same rule so a test cannot accidentally prove the wrong thing.
+            clipboard.push(formatColor(value, colorFormat));
+          }
+        };
+      }
+    }
+
+    // Recents: `list` reads this extension's own records (a read, on every context); `record`
+    // and `remove` are effects, so action-only. The store is in-memory and per-host, so a test
+    // can pick a colour and read it straight back.
+    let recentsCapability: RecentsCapability | undefined;
+    if (grants.recents) {
+      recentsCapability = {};
+      if (grants.recents.list) {
+        recentsCapability.list = async () => recentsStore.slice();
+      }
+      if (kind === "invoke") {
+        if (grants.recents.record) {
+          recentsCapability.record = async (item) => {
+            const rest = recentsStore.filter((existing) => existing.id !== item.id);
+            recentsStore.length = 0;
+            recentsStore.push(item, ...rest);
+          };
+        }
+        if (grants.recents.remove) {
+          recentsCapability.remove = async (id) => {
+            const kept = recentsStore.filter((existing) => existing.id !== id);
+            recentsStore.length = 0;
+            recentsStore.push(...kept);
+          };
+        }
+      }
+    }
+
+    // Native effects. `open` and `reveal` are **ambient** — action-only, no grant — so any action
+    // has them; the host restricts `open` to http/https, and the fake records the URL. `notify` and
+    // `save` still need their units.
+    let native: NativeActionsCapability | undefined;
+    if (kind === "invoke") {
+      native = {
+        open: async (url) => {
+          opened.push(url);
+        },
+        reveal: async () => {},
+      };
+      if (grants.native?.notify) {
+        native.notify = async (notification) => {
+          notifications.push(notification);
+        };
+      }
+      if (grants.native?.save) {
+        native.save = async (file) => {
+          // The host names and places the file; the fake records what it was handed. A real
+          // host strips any directory part of `name` — the fake keeps it verbatim so a test
+          // can prove the extension did not smuggle a path in, which is the host's to reject.
+          saves.push({ name: file.name, type: file.type, data: file.data });
+        };
+      }
+    }
+
+    // Pickers are their own group, not a fourth `native.*` verb: they take the
+    // screen, wait on a person, and return a value — none of which `open`, `reveal`,
+    // or `notify` do. The whole group is absent outside an action, and the ops
+    // re-check the invocation kind on every call rather than trusting that absence:
+    // a guest that stashed one from an earlier action gets `permission-denied`.
+    // The screen is an *action's* capability. A query runs on a keystroke, and a
+    // keystroke must never be able to cover the display. The ops re-check the invocation
+    // kind on every call rather than trusting that absence: a guest that stashed the
+    // function from an earlier action and calls it during a query gets permission-denied.
+    let screen: ScreenCapability | undefined;
+    if (grants.screen?.overlay && kind === "invoke") {
+      screen = {
+        createOverlay: async (spec?: OverlaySpec) => {
+          if (!grants.screen?.overlay) {
+            throw new ExtensionError({
+              code: "permission-denied",
+              message: "screen.overlay is not granted",
+            });
+          }
+          if (currentKind !== "invoke") {
+            throw new ExtensionError({
+              code: "permission-denied",
+              message: "screen.overlay is only available while running an action",
+            });
+          }
+          if (signal.aborted) throw cancelledError();
+          return openOverlay(spec, signal);
+        },
+      };
+    }
+
+    // The bridge to a live WebView surface. Present only in an action, only with `ui.webview`,
+    // and only while a surface is actually up (`liveSurface`) — the isolate that presented the
+    // surface was very likely evicted while the user drew, so a fresh action reconnects to the
+    // shell-owned surface. The reply is whatever the surface's own code returned: untrusted, so
+    // the extension validates it. The op would re-check the kind on every call; the fake mirrors
+    // that by rebuilding the capability per invocation rather than trusting a stashed reference.
+    let bridge: BridgeCapability | undefined;
+    if (grants.ui?.webview && kind === "invoke" && liveSurface) {
+      bridge = {
+        request: async (message) => {
+          if (currentKind !== "invoke") {
+            throw new ExtensionError({
+              code: "permission-denied",
+              message: "ctx.bridge is only available while running an action",
+            });
+          }
+          if (!liveSurface) {
+            throw new ExtensionError({
+              code: "invalid-request",
+              message: "no WebView surface is up to receive a bridge message",
+            });
+          }
+          if (signal.aborted) throw cancelledError();
+          bridgeMessages.push(message);
+          return liveSurface.respond(message);
+        },
+      };
+    }
+
+    /**
+     * Entering a scope is the host's move, so the fake records the ask and performs nothing —
+     * `host.navigations` is what a test asserts, and `host.enter(item)` is how it walks in. The
+     * guard mirrors the host's: an item that enters a scope outside this extension's namespace,
+     * or no scope at all, is refused rather than quietly followed.
+     */
+    const navigate: NavigationCapability | undefined =
+      kind === "invoke"
+        ? {
+            enter(item: CommandItem): void {
+              const type = item.scope?.type;
+              if (type === undefined || !type.startsWith(scopeTypePrefix(manifest.id))) {
+                throw new ExtensionError({
+                  code: "invalid-request",
+                  message: "navigate.enter takes an item produced by this extension's scope.entry()",
+                });
+              }
+              navigations.push(item);
+            },
+          }
+        : undefined;
+
+    return {
+      signal,
+      deadlineMs,
+      settings,
+      environment,
+      t: translate,
+      http,
+      cache,
+      storage,
+      context,
+      fonts,
+      location,
+      process,
+      clipboard: clipboardCapability,
+      files: filesCapability,
+      exec: execCapability,
+      queries: queriesCapability,
+      recents: recentsCapability,
+      native,
+      screen: kind === "invoke" ? screen : undefined,
+      bridge: kind === "invoke" ? bridge : undefined,
+      navigate,
+    };
+  }
+
+  /**
+   * Every invocation runs against the generation that started it. A result that
+   * lands after the generation moved on is dropped, exactly as the shell drops a
+   * late scene update — including a batch from a stream that is still running.
+   */
+  async function run<T>(
+    deadlineMs: number,
+    kind: InvocationKind,
+    body: (ctx: ActionContext) => T | Promise<T>,
+  ): Promise<T> {
+    const startedAt = generation;
+    // The handler sees the run window; the checks below see the invocation. Cancelling the
+    // invocation ends the window with it.
+    const invocation = controller.signal;
+    const signal = window.signal;
+    const endWindow = () => window.abort();
+    invocation.addEventListener("abort", endWindow, { once: true });
+    currentKind = kind;
+    const ctx = makeContext(deadlineMs, kind);
+    const aborted = new Promise<never>((_resolve, reject) => {
+      if (invocation.aborted) reject(cancelledError());
+      invocation.addEventListener("abort", () => reject(cancelledError()), { once: true });
+    });
+    const result = await Promise.race([body(ctx), aborted]);
+    if (generation !== startedAt || invocation.aborted) throw cancelledError();
+    return result;
+  }
+
+  function startInvocation(): void {
+    generation += 1;
+    controller = new AbortController();
+    window = new AbortController();
+    batches = [];
+  }
+
+  /// Ending a stream is not cancelling the call.
+  ///
+  /// A generator that keeps yielding has to be told to stop, and what a handler observes when it
+  /// is told is `ctx.signal` — the same thing it observes when the user cancels. The difference is
+  /// what the *caller* sees: a cancelled invocation throws, while a stream that was asked to stop
+  /// returns the rows it produced. So the window aborts on its own, and cancelling the invocation
+  /// aborts it too.
+  function endRunWindow(): void {
+    window.abort();
+  }
+
+  /**
+   * Collect a possibly-streamed result. Each batch is validated on arrival, then
+   * reconciled into the accumulated list by item id — same id updates in place,
+   * a new id appends — which is exactly what core does with a provider's stream.
+   *
+   * A generator that keeps yielding needs a stopping rule, because the real shell's is "the scope
+   * stopped being shown" and a test has no scope on a screen. The rule here is **take what is
+   * ready**: batches are collected while they arrive without the generator waiting on anything,
+   * and the first time it awaits — a timer, a socket — the run window is aborted, which is exactly
+   * what the shell does on teardown and what runs the generator's `finally`. A `top` that refreshes
+   * on a clock therefore yields its first snapshot to a test and stops, rather than hanging it.
+   */
+  async function collect(
+    result: QueryResult,
+    commandId: string,
+    limit: number,
+    startedAt: number,
+  ): Promise<CommandItem[]> {
+    if (Array.isArray(result)) {
+      const validated = validateItems(result, commandId, limit);
+      batches.push(validated);
+      return validated;
+    }
+
+    let merged: CommandItem[] = [];
+    let index = new Map<string, number>();
+    const iterator = result[Symbol.asyncIterator]();
+    const pending = Symbol("pending");
+    while (true) {
+      // Race the next batch against a turn of the event loop: a generator with a batch in hand
+      // wins it, one that has settled into `await sleep(…)` does not.
+      const next = await Promise.race([
+        iterator.next(),
+        new Promise<typeof pending>((resolve) => setTimeout(() => resolve(pending), 0)),
+      ]);
+      if (next === pending) {
+        endRunWindow();
+        await iterator.return?.(undefined);
+        break;
+      }
+      if (next.done) break;
+      const batch = next.value;
+      if (generation !== startedAt || controller.signal.aborted) throw cancelledError();
+      const replaces = !Array.isArray(batch);
+      const validated = validateItems(replaces ? batch.replace : batch, commandId, limit);
+      batches.push(validated);
+      // `{ replace }` states the whole set: ids missing from it are gone, which upserting alone
+      // can never say. A bare array adds to what is already shown.
+      if (replaces) {
+        merged = [];
+        index = new Map();
+      }
+      for (const item of validated) {
+        const at = index.get(item.id);
+        if (at === undefined) {
+          index.set(item.id, merged.length);
+          merged.push(item);
+        } else {
+          merged[at] = item;
+        }
+      }
+      if (merged.length > limits.maxItemsPerInvocation) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: `more than ${limits.maxItemsPerInvocation} items across batches`,
+        });
+      }
+    }
+    return merged;
+  }
+
+  function commandOf(commandId: string): ManifestCommand {
+    const command = manifest.commands.find((c) => c.id === commandId);
+    if (!command) throw new Error(`command "${commandId}" is not declared in the manifest`);
+    return command;
+  }
+
+  /** A command may narrow the host's deadline, never widen it. */
+  function deadlineOf(command: ManifestCommand, kind: InvocationKind): number {
+    const host = kind === "invoke" ? limits.defaultActionDeadlineMs : limits.defaultDeadlineMs;
+    const asked = command.activation?.deadlineMs;
+    return asked === undefined ? host : Math.min(asked, host);
+  }
+
+  function validateItems(items: CommandItem[], commandId: string, limit: number): CommandItem[] {
+    const encoded = JSON.stringify(items);
+    if (encoded.length > limits.maxResultBytes) {
+      throw new ExtensionError({
+        code: "invalid-result",
+        message: `result exceeds ${limits.maxResultBytes} encoded bytes`,
+      });
+    }
+    const seen = new Set<string>();
+    const facetTitles = new Map<string, string>();
+    const kept: CommandItem[] = [];
+    for (let item of items) {
+      if (!item.id || !item.title) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: "every item needs a non-empty id and title",
+        });
+      }
+      if (seen.has(item.id)) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: `duplicate item id "${item.id}"`,
+        });
+      }
+      seen.add(item.id);
+      if (item.facet) {
+        const known = facetTitles.get(item.facet.id);
+        if (known !== undefined && known !== item.facet.title) {
+          throw new ExtensionError({
+            code: "invalid-result",
+            message: `facet "${item.facet.id}" has conflicting titles "${known}" and "${item.facet.title}"`,
+          });
+        }
+        facetTitles.set(item.facet.id, item.facet.title);
+      }
+      // Core's decision, not the extension's good manners: an action whose unit was not
+      // granted is not offered. The extension declared the dependency; this honours it.
+      if (item.requires && !permissionUnits(grants).has(item.requires)) {
+        item = { ...item, defaultActionId: undefined };
+      }
+      if (item.icon) validateIcon(item.icon);
+      if (item.scope) validateScope(item.scope);
+      // The host namespaces the guest id before it reaches core state.
+      namespacedItemId(manifest.id, commandId, item.id);
+      itemOrigin.set(item.id, commandId);
+      kept.push(item);
+    }
+    const capped = Math.min(limit, limits.maxItemsPerBatch);
+    if (kept.length > capped) {
+      diagnostics.push({ level: "warn", message: `truncated ${kept.length} items to ${capped}` });
+      return kept.slice(0, capped);
+    }
+    return kept;
+  }
+
+  function validateScope(scope: ItemScope<JsonValue>): void {
+    // A native subject type is Tapcue's to own and anyone's to produce. The host still
+    // checks the subject really *is* one — a row claiming to be a colour and carrying a
+    // string would enter the colour scope and render nothing.
+    if (isNativeScopeType(scope.type)) {
+      if (!isColor(scope.subject)) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: `item enters native scope "${scope.type}" with a subject that is not a Color`,
+        });
+      }
+      return;
+    }
+    if (!scopes.has(scope.type)) {
+      throw new ExtensionError({
+        code: "invalid-result",
+        message: `item enters unregistered scope "${scope.type}"`,
+      });
+    }
+    const encoded = JSON.stringify(scope.subject ?? null);
+    if (encoded.length > limits.maxScopeSubjectBytes) {
+      throw new ExtensionError({
+        code: "invalid-result",
+        message: `scope subject exceeds ${limits.maxScopeSubjectBytes} bytes`,
+      });
+    }
+  }
+
+  /** The same grammar the manifest validator applies — one rule, one place. */
+  function validateIcon(icon: string): void {
+    const problem = iconProblem(icon);
+    if (problem) {
+      throw new ExtensionError({
+        code: "invalid-result",
+        message: `icon "${icon}": ${problem}`,
+      });
+    }
+  }
+
+  function validateScene(scene: Scene | null): Scene | null {
+    if (!scene) return scene;
+    const granted = permissionUnits(grants);
+    if (scene.kind === "error" || scene.kind === "detail" || scene.kind === "webview") {
+      for (const action of scene.actions ?? []) {
+        if (action.icon) validateIcon(action.icon);
+      }
+    }
+    if (scene.kind === "webview") {
+      // Presenting a WebView is the one place an extension renders rather than describes, so it
+      // is the one scene that needs a grant to exist at all. A surface without `ui.webview` is
+      // not a degraded scene, it is a scene the extension was never allowed to return.
+      if (!granted.has("ui.webview")) {
+        throw new ExtensionError({
+          code: "permission-denied",
+          message: "a webview scene requires the ui.webview permission",
+        });
+      }
+      const problem = assetPathProblem(scene.entry);
+      if (problem) {
+        throw new ExtensionError({ code: "invalid-result", message: `webview entry ${problem}` });
+      }
+      // Same footer rule as a row's actions: an action Tapcue knows it cannot run is not drawn.
+      return {
+        ...scene,
+        actions: (scene.actions ?? []).filter((a) => !a.requires || granted.has(a.requires)),
+      };
+    }
+    if (scene.kind !== "detail") return scene;
+    if (scene.icon) validateIcon(scene.icon);
+    for (const block of scene.body ?? []) validateBlock(block);
+    // Same rule in the detail pane: an action Tapcue knows will fail is not drawn.
+    return {
+      ...scene,
+      actions: (scene.actions ?? []).filter((a) => !a.requires || granted.has(a.requires)),
+    };
+  }
+
+  /** A WebView `entry`, like an `asset:` icon minus the prefix: package-relative, no traversal. */
+  function assetPathProblem(path: string): string | undefined {
+    if (typeof path !== "string" || path === "") return "must be a non-empty package-relative path";
+    if (path.startsWith("/") || path.split("/").includes("..")) {
+      return "must be package-relative and must not traverse";
+    }
+    return undefined;
+  }
+
+  function validateBlock(block: SceneBlock): void {
+    if (block.kind !== "chart") return;
+    const chart: Chart = block.chart;
+    for (const series of chart.series) {
+      if (series.values.length !== chart.labels.length) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: `chart series "${series.id}" has ${series.values.length} values for ${chart.labels.length} labels`,
+        });
+      }
+    }
+    for (const marker of chart.markers ?? []) {
+      if (marker.at < 0 || marker.at >= chart.labels.length) {
+        throw new ExtensionError({
+          code: "invalid-result",
+          message: `chart marker at ${marker.at} is out of range`,
+        });
+      }
+    }
+  }
+
+  const DEFAULT_BOUNDS: Rect = { x: 0, y: 0, width: 1920, height: 1080 };
+  const BLACK: Color = { red: 0, green: 0, blue: 0, colorSpace: "srgb" };
+
+  /**
+   * A faithful stand-in for the real overlay: the same lifecycle, the same rules. It
+   * hands out the scripted events, records every frame, and dies on cancellation with
+   * the same finality the shell's Esc has.
+   */
+  /** `ScreenOverlayService.Session.cardSize`, less the chrome the host draws around it. */
+  const CARD_BOUNDS: Rect = { x: 0, y: 0, width: 428, height: 86 };
+
+  function openOverlay(spec: OverlaySpec | undefined, signal: AbortSignal): OverlaySession {
+    const coach = spec?.mode === "coach";
+    // A card is told how much room it has and nothing about where that room is, so the fake hands
+    // back the host's card size rather than the desktop — a test that asserts a card fits its
+    // contents must fail here for the same reason it would fail on screen.
+    const bounds = coach ? CARD_BOUNDS : (options.screen?.bounds ?? DEFAULT_BOUNDS);
+    const colorAt = options.screen?.colorAt ?? (() => BLACK);
+    const recorded: RecordedOverlay = { spec, frames: [], captures: [], closed: false };
+    overlays.push(recorded);
+    let open = true;
+    /** Resolves when the card goes away, so a coach card's stream ends when it really ends. */
+    let closed: () => void = () => {};
+    const untilClosed = new Promise<void>((resolve) => {
+      closed = resolve;
+    });
+
+    const die = (): never => {
+      open = false;
+      recorded.closed = true;
+      throw new ExtensionError({
+        code: "invalid-request",
+        message: "the overlay is closed",
+      });
+    };
+    const alive = () => {
+      if (!open || signal.aborted) die();
+    };
+
+    function layerFor(nodes: SvgNode[]): Layer {
+      const index = recorded.frames.push(nodes) - 1;
+      return {
+        move(to: Point) {
+          alive();
+          // `move` re-transforms what is already drawn rather than re-serializing it —
+          // the reason a ruler that follows the cursor costs nothing.
+          recorded.frames.push(
+            recorded.frames[index].map((node) =>
+              node.tag === "g"
+                ? { ...node, transform: `translate(${to.x} ${to.y})` }
+                : node,
+            ),
+          );
+        },
+        update(next: SvgNode[]) {
+          alive();
+          recorded.frames.push(next);
+        },
+        remove() {
+          alive();
+          recorded.frames.push([]);
+        },
+      };
+    }
+
+    return {
+      bounds,
+      draw(nodes) {
+        alive();
+        return layerFor(nodes);
+      },
+      capture: grants.screen?.capture
+        ? async (rect: Rect) => {
+            alive();
+            if (!grants.screen?.capture) {
+              throw new ExtensionError({
+                code: "permission-denied",
+                message: "screen.capture is not granted",
+              });
+            }
+            recorded.captures.push(rect);
+            return makeImage(rect, colorAt);
+          }
+        : undefined,
+      async *events() {
+        if (coach) {
+          // A coach card receives no pointer events at all — whatever the fake desktop was
+          // scripted to do, the user was doing it in *another app*, which is the whole point.
+          //
+          // And its stream ends when the card does, not one tick after it opens. An extension
+          // watching for the user to give up races that stream against its own work, so a fake
+          // that cancels immediately would make every such race a foregone conclusion.
+          if (!options.screen?.dismissCoach) await untilClosed;
+          yield { kind: "cancelled" } as OverlayEvent;
+          return;
+        }
+        for (const event of options.screen?.events ?? []) {
+          if (!open || signal.aborted) {
+            yield { kind: "cancelled" } as OverlayEvent;
+            return;
+          }
+          yield event;
+        }
+        // The user walked away. An overlay must survive it, so the fake always says so
+        // rather than leaving the stream hanging.
+        yield { kind: "cancelled" } as OverlayEvent;
+      },
+      close() {
+        open = false;
+        recorded.closed = true;
+        closed();
+      },
+    };
+  }
+
+  /**
+   * The subject shape check the shell performs before a contribution is ever called.
+   *
+   * `NativeSubjects` is the shape both directions travel: an extension producing an item that
+   * *enters* `application` is validated against it, and a contribution receiving one is handed
+   * exactly it. A test that hands over `{ bundle: "..." }` would otherwise be testing an
+   * extension against a subject Tapcue never produces.
+   */
+  function validateNativeSubject(
+    type: ContributableScopeType,
+    subject: Record<string, JsonValue>,
+  ): NativeSubjects[ContributableScopeType] & Record<string, JsonValue> {
+    const fields = NATIVE_SUBJECT_FIELDS[type];
+    // Unknown fields first: the common mistake is a misspelling, and reporting `bundleId` as
+    // *missing* when the fixture plainly wrote `bundle` names the wrong half of the problem.
+    for (const field of Object.keys(subject)) {
+      if (!fields.includes(field)) {
+        throw new Error(`a "${type}" subject has no "${field}"; it carries ${fields.join(", ")}`);
+      }
+    }
+    for (const field of fields) {
+      if (!(field in subject)) {
+        throw new Error(`a "${type}" subject needs ${fields.join(", ")}; "${field}" is missing`);
+      }
+    }
+    // The loops above are the check the cast rests on: every declared field present, nothing
+    // else. A fixture that failed either one threw before reaching here.
+    return subject as NativeSubjects[ContributableScopeType] & Record<string, JsonValue>;
+  }
+
+  /**
+   * `when` — every named field must match one of its values, compared case-insensitively as whole
+   * strings. Several fields is an AND, several values in one field is an OR.
+   *
+   * An unknown field cannot get here: the manifest validator rejects it. That order matters —
+   * treated as "no opinion" instead, an unknown field would make the predicate match *everything*,
+   * which is the failure mode this whole mechanism has to be built to refuse.
+   */
+  function whenAdmits(entry: ManifestContribution, subject: Record<string, JsonValue>): boolean {
+    const matchable = CONTRIBUTION_MATCH_FIELDS[entry.scope];
+    for (const [field, values] of Object.entries(entry.when)) {
+      if (!matchable.includes(field)) return false;
+      const actual = subject[field];
+      if (typeof actual !== "string") return false;
+      const lowered = actual.toLowerCase();
+      if (!values.some((value) => value.toLowerCase() === lowered)) return false;
+    }
+    return true;
+  }
+
+  let invocationCounter = 0;
+  const nextInvocationId = () => `inv-${(invocationCounter += 1)}`;
+
+  function runAction(
+    commandId: string,
+    actionId: string,
+    itemId: string | undefined,
+  ): Promise<ActionResult> {
+    const command = commandOf(commandId);
+    const handlers = options.extension.commands[commandId];
+    if (!handlers?.invoke) throw new Error(`command "${commandId}" has no invoke handler`);
+    startInvocation();
+    const startedAt = generation;
+    const invocationId = nextInvocationId();
+    return run(deadlineOf(command, "invoke"), "invoke", (ctx) =>
+      handlers.invoke!(
+        {
+          invocationId,
+          sessionId: "session-1",
+          generation: startedAt,
+          commandId,
+          actionId,
+          itemId,
+        },
+        ctx,
+      ),
+    );
+  }
+
+  const host: TestHost = {
+    async query(commandId, queryOptions) {
+      const command = commandOf(commandId);
+      const handlers = options.extension.commands[commandId];
+      if (!handlers?.query) throw new Error(`command "${commandId}" has no query handler`);
+      startInvocation();
+      const startedAt = generation;
+      const limit = Math.min(
+        queryOptions?.limit ?? command.activation?.maxResults ?? 50,
+        limits.maxItemsPerInvocation,
+      );
+      const invocationId = nextInvocationId();
+      return run(deadlineOf(command, "query"), "query", async (ctx) => {
+        const result = await handlers.query!(
+          {
+            invocationId,
+            sessionId: "session-1",
+            generation: startedAt,
+            commandId,
+            query: queryOptions?.query ?? "",
+            arguments: Object.freeze({ ...(queryOptions?.arguments ?? {}) }),
+            limit,
+          },
+          ctx,
+        );
+        return collect(result, commandId, limit, startedAt);
+      });
+    },
+
+    invoke(commandId, itemId, actionId) {
+      return runAction(commandId, actionId, itemId);
+    },
+
+    /**
+     * A `no-view` command's row carries no item, so there is no
+     * `CommandItem.defaultActionId` to name the action: core routes Enter on the
+     * manifest row to the reserved `default` id.
+     */
+    run(commandId) {
+      const command = commandOf(commandId);
+      if (command.mode !== "no-view") {
+        throw new Error(
+          `"${commandId}" is a view command: run its query and invoke an item, not the command`,
+        );
+      }
+      return runAction(commandId, DEFAULT_ACTION_ID, undefined);
+    },
+
+    enterNative(entry) {
+      if (!(CONTRIBUTABLE_SCOPE_TYPES as readonly string[]).includes(entry.type)) {
+        throw new Error(
+          `"${entry.type}" is not a contributable native scope — one of ${CONTRIBUTABLE_SCOPE_TYPES.join(", ")}`,
+        );
+      }
+      const subject = validateNativeSubject(entry.type, entry.subject);
+      const queryMode = entry.queryMode ?? "remote";
+      // The native scope-id forms the shell uses. Only ever a cache key to the extension, but a
+      // fake that invented a shape would let a test depend on one Tapcue does not produce.
+      const scopeId =
+        entry.scopeId ??
+        (entry.type === "application"
+          ? `app:${String(subject.bundleId)}`
+          : `file:${String(subject.path)}`);
+      // Leaving a scope tears down whatever surface the last one had up — same rule as `enter`.
+      liveSurface = null;
+
+      const admitted = [...contributions.values()]
+        .filter((c) => c.manifest.scope === entry.type && whenAdmits(c.manifest, subject))
+        .map((c) => c.manifest.id);
+
+      const resolve = (contributionId: string) => {
+        const found = contributions.get(contributionId);
+        if (!found) {
+          throw new Error(`"${contributionId}" is not a declared contribution`);
+        }
+        if (found.manifest.scope !== entry.type) {
+          throw new Error(
+            `contribution "${contributionId}" targets "${found.manifest.scope}", not "${entry.type}"`,
+          );
+        }
+        if (!admitted.includes(contributionId)) {
+          // The gate, stated as the shell states it: not "returned nothing", but "was never
+          // asked". The extension does not learn the subject exists.
+          throw new Error(
+            `contribution "${contributionId}" does not apply to this subject — its when predicate did not match, so Tapcue would never call it`,
+          );
+        }
+        return found;
+      };
+
+      return {
+        type: entry.type,
+        scopeId,
+        contributions: admitted,
+        async items(contributionId, sessionOptions) {
+          const { manifest: declared, handlers } = resolve(contributionId);
+          startInvocation();
+          const startedAt = generation;
+          const limit = Math.min(
+            sessionOptions?.limit ?? limits.maxItemsPerInvocation,
+            limits.maxItemsPerInvocation,
+          );
+          const invocationId = nextInvocationId();
+          // **A catalog scope hands its contributors an empty query**, exactly as
+          // `ScopeController` does (`pullQuery = isCatalog ? "" : query`) — so an extension that
+          // only filters when it is given something to filter on shows everything there, and a
+          // test can see it happen instead of discovering it in the launcher.
+          const query = queryMode === "catalog" ? "" : (sessionOptions?.query ?? "");
+          return run(limits.defaultDeadlineMs, "query", async (ctx) => {
+            const result = await handlers.items(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                contributionId: declared.id,
+                scopeType: entry.type,
+                scopeId,
+                subject,
+                queryMode,
+                query,
+                limit,
+              },
+              ctx,
+            );
+            return collect(result, declared.id, limit, startedAt);
+          });
+        },
+        async invoke(contributionId, itemId, actionId) {
+          const { manifest: declared, handlers } = resolve(contributionId);
+          if (!handlers.invoke) {
+            throw new Error(`contribution "${contributionId}" has no invoke handler`);
+          }
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          return run(limits.defaultActionDeadlineMs, "invoke", (ctx) =>
+            handlers.invoke!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                contributionId: declared.id,
+                scopeType: entry.type,
+                scopeId,
+                subject,
+                itemId,
+                actionId,
+              },
+              ctx,
+            ),
+          );
+        },
+      };
+    },
+
+    enter(item) {
+      if (!item.scope) throw new Error(`item "${item.id}" carries no scope to enter`);
+      if (isNativeScopeType(item.scope.type)) {
+        // Deliberately not simulatable. Tapcue renders a native scope — its rows, its
+        // formats, its actions are core's, and an extension test that asserted them
+        // would be asserting code the extension does not own. Assert the subject you
+        // handed over; what Tapcue does with a colour is Tapcue's test to write.
+        throw new Error(
+          `"${item.scope.type}" is a native scope: Tapcue renders it, not your extension. ` +
+            `Assert item.scope.subject instead.`,
+        );
+      }
+      const scope = scopes.get(item.scope.type);
+      if (!scope) throw new Error(`no registered scope "${item.scope.type}"`);
+      // The adapter keeps the subject on the native Scope's payload and hands it
+      // back on every call into the scope — the isolate may have been evicted in
+      // between, so guest memory is never where this lives.
+      const subject = (item.scope.subject ?? null) as JsonValue;
+      const scopeId = `extension:${manifest.id}:${item.scope.type}:${item.id}`;
+      // The command whose query produced this item — not `commands[0]`. An action
+      // inside the scope is still routed to (extension, command, item, action), and
+      // an extension with two commands would otherwise be told the wrong one.
+      const commandId = itemOrigin.get(item.id) ?? manifest.commands[0].id;
+      // Entering a scope tears down whatever surface the previous one had up. The isolate does
+      // not own the surface, the shell does, and leaving one scope ends it — so the bridge from
+      // a stale surface is gone before the next scope's actions can reach for it.
+      liveSurface = null;
+
+      return {
+        type: scope.type,
+        scopeId,
+        async items(sessionOptions) {
+          if (!scope.spec.items) {
+            throw new Error(`rowless scope "${scope.type}" has no rows — call surface()/view(), not items()`);
+          }
+          startInvocation();
+          const startedAt = generation;
+          const limit = Math.min(
+            sessionOptions?.limit ?? limits.maxItemsPerInvocation,
+            limits.maxItemsPerInvocation,
+          );
+          const invocationId = nextInvocationId();
+          return run(limits.defaultDeadlineMs, "query", async (ctx) => {
+            const result = await scope.spec.items!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                scopeType: scope.type,
+                scopeId,
+                subject,
+                query: sessionOptions?.query ?? "",
+                limit,
+              },
+              ctx,
+            );
+            return collect(result, commandId, limit, startedAt);
+          });
+        },
+        async surface() {
+          if (!scope.spec.surface) {
+            throw new Error(`scope "${scope.type}" is not a canvas scope — it has no surface()`);
+          }
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          const scene = await run(limits.defaultDeadlineMs, "detail", (ctx) =>
+            scope.spec.surface!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                scopeType: scope.type,
+                scopeId,
+                subject,
+              },
+              ctx,
+            ),
+          );
+          const validated = validateScene(scene);
+          // The shell now owns a live surface; the isolate's only handle to it is `ctx.bridge`.
+          if (validated?.kind === "webview") {
+            surfaces.push({
+              entry: validated.entry,
+              title: validated.title,
+              actions: validated.actions ?? [],
+            });
+            liveSurface = { respond: options.surface?.respond ?? ((m) => m) };
+          }
+          return validated as Scene;
+        },
+        async act(actionId) {
+          if (!scope.spec.invoke) throw new Error(`scope "${scope.type}" has no invoke handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          return run(limits.defaultActionDeadlineMs, "invoke", (ctx) =>
+            scope.spec.invoke!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                commandId,
+                actionId,
+                scopeType: scope.type,
+                subject,
+              },
+              ctx,
+            ),
+          );
+        },
+        async view(itemId) {
+          if (!scope.spec.view) throw new Error(`scope "${scope.type}" has no view handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          return run(limits.defaultDeadlineMs, "detail", (ctx) =>
+            renderView(
+              scope.spec.view!,
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                scopeType: scope.type,
+                scopeId,
+                subject,
+                itemId,
+              },
+              ctx,
+            ),
+          );
+        },
+        async liveView(itemId): Promise<LiveViewSession> {
+          if (!scope.spec.view) throw new Error(`scope "${scope.type}" has no view handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          const abort = new AbortController();
+          const patches: PatchOp[][] = [];
+          let initial: ViewResult | undefined;
+          let markReady: () => void = () => {};
+          const ready = new Promise<void>((resolve) => (markReady = resolve));
+
+          currentKind = "detail";
+          const ctx = makeContext(limits.defaultDeadlineMs, "detail");
+          const finished = driveView(
+            scope.spec.view,
+            {
+              invocationId,
+              sessionId: "session-1",
+              generation: startedAt,
+              scopeType: scope.type,
+              scopeId,
+              subject,
+              itemId,
+            },
+            ctx,
+            (result) => {
+              initial = result;
+            },
+            { signal: abort.signal, onPatch: (ops) => patches.push(ops), onReady: () => markReady() },
+          );
+
+          // `driveView` emits before it signals ready on both of its paths, so past this point
+          // the initial frame is always in hand.
+          await ready;
+          return {
+            initial: initial as ViewResult,
+            patches,
+            async stop() {
+              abort.abort();
+              await finished;
+            },
+          };
+        },
+        async viewAction(itemId, actionId, args, model) {
+          if (!scope.spec.view) throw new Error(`scope "${scope.type}" has no view handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          return run(limits.defaultActionDeadlineMs, "invoke", (ctx) =>
+            applyAction(
+              scope.spec.view!,
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                scopeType: scope.type,
+                scopeId,
+                subject,
+                itemId,
+              },
+              ctx,
+              actionId,
+              args,
+              model,
+            ),
+          );
+        },
+        async detail(itemId) {
+          if (!scope.spec.detail) throw new Error(`scope "${scope.type}" has no detail handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          const scene = await run(limits.defaultDeadlineMs, "detail", (ctx) =>
+            scope.spec.detail!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                scopeType: scope.type,
+                scopeId,
+                subject,
+                itemId,
+              },
+              ctx,
+            ),
+          );
+          return validateScene(scene);
+        },
+        async invoke(itemId, actionId) {
+          if (!scope.spec.invoke) throw new Error(`scope "${scope.type}" has no invoke handler`);
+          startInvocation();
+          const startedAt = generation;
+          const invocationId = nextInvocationId();
+          return run(limits.defaultActionDeadlineMs, "invoke", (ctx) =>
+            scope.spec.invoke!(
+              {
+                invocationId,
+                sessionId: "session-1",
+                generation: startedAt,
+                commandId,
+                actionId,
+                itemId,
+                scopeType: scope.type,
+                subject,
+              },
+              ctx,
+            ),
+          );
+        },
+      };
+    },
+
+    cancel() {
+      generation += 1;
+      controller.abort();
+    },
+
+    revoke(unit) {
+      if (permissionUnits(manifest.permissions).has(unit)) {
+        throw new Error(
+          `"${unit}" is a required permission: revoking it disables the extension, it does not degrade it`,
+        );
+      }
+      const spec = PERMISSION_UNITS.find((candidate) => candidate.unit === unit);
+      if (!spec) throw new Error(`unknown permission unit "${unit}"`);
+
+      // Walked off the unit table rather than switched over by hand, which is how this last
+      // managed to omit `native.save`, `ui.webview` and `background` — three units a manifest can
+      // declare optional and no test could then take away.
+      const remaining = { ...(manifest.optionalPermissions ?? {}) } as Record<string, any>;
+      const listValued = spec.kind === "paths" || spec.kind === "binaries";
+      if (spec.key !== null && !listValued) {
+        remaining[spec.group] = { ...remaining[spec.group], [spec.key]: false };
+      } else if (spec.kind === "boolean") {
+        remaining[spec.group] = false;
+      } else {
+        // The value-carrying units (hosts, quotas, secret names, precision, and the two lists
+        // spec 016 added) are revoked by removing the block: there is no "false" to write into a
+        // list, and writing one would leave `files: { read: false }` for the resolver to trip on.
+        delete remaining[spec.group];
+      }
+      grants = effectiveGrants(manifest, remaining as ManifestPermissions);
+    },
+
+    advanceTime(ms) {
+      nowMs += ms;
+    },
+
+    setProcesses(next) {
+      processesFixture = next;
+    },
+
+    get batches() {
+      return batches;
+    },
+    requests,
+    diagnostics,
+    clipboard,
+    clipboardSecrets,
+    clipboardImages,
+    opened,
+    ran,
+    queried,
+    async workspaceRoots(ask = {}) {
+      // The gate first, and it is the same gate the host applies: a slot nobody granted is a slot
+      // nobody is asked about, so the handler must not run.
+      if (grants.workspace?.roots !== true) return [];
+      const limit = ask.limit ?? limits.maxItemsPerBatch;
+      const chosen = ask.provisionId
+        ? [provisions.get(ask.provisionId)].filter(Boolean)
+        : [...provisions.values()].filter((entry) => entry!.manifest.slot === "workspace.roots");
+      if (ask.provisionId && chosen.length === 0) {
+        throw new Error(`"${ask.provisionId}" is not a declared provision`);
+      }
+      const out: WorkspaceRoot[] = [];
+      for (const entry of chosen) {
+        const answered = await entry!.handlers.roots!(
+          { provisionId: entry!.manifest.id, slot: entry!.manifest.slot, limit },
+          makeContext(limits.defaultDeadlineMs, "query"),
+        );
+        // Absolute paths only. The real host also checks each one exists, is a directory and sits
+        // under the user's home — facts a deterministic host has no filesystem to know — but the
+        // shape rule is pure and belongs on both sides.
+        out.push(...answered.filter((root) => typeof root.path === "string" && root.path.startsWith("/")));
+      }
+      return out.slice(0, limit);
+    },
+    notifications,
+    saves,
+    surfaces,
+    bridgeMessages,
+    overlays,
+    kills,
+    activated,
+    navigations,
+    settingsWrites,
+    get generation() {
+      return generation;
+    },
+  };
+
+  return host;
+}
+
+/** Drop `command` (argv) from a `ProcessInfo` — the sensitive read the host withholds without
+ *  the `process.command` grant, exactly as the real host does. */
+function stripCommand(process: ProcessInfo): ProcessInfo {
+  const { command: _command, ...rest } = process;
+  return rest;
+}
+
+export { redact };
+export type { HttpRoute, RecordedRequest };
+
+function isNativeScopeType(type: string): boolean {
+  return (NATIVE_SCOPE_TYPES as readonly string[]).includes(type);
+}
+
+/** A row claiming to be a colour and carrying a string would enter the colour scope and
+ * render nothing. The host checks the subject really is what the type says it is. */
+function isColor(value: unknown): value is Color {
+  if (typeof value !== "object" || value === null) return false;
+  const color = value as Record<string, unknown>;
+  return (
+    typeof color.red === "number" &&
+    typeof color.green === "number" &&
+    typeof color.blue === "number" &&
+    (color.colorSpace === "srgb" || color.colorSpace === "display-p3")
+  );
+}
+
+/** Every frame an extension drew on an overlay, for a test to look at. */
+export interface RecordedOverlay {
+  spec: OverlaySpec | undefined;
+  frames: SvgNode[][];
+  captures: Rect[];
+  closed: boolean;
+}
+
+/**
+ * A capture. The bytes are synthesized from the fake desktop, so a test can assert on
+ * the colour an extension read without ever owning a bitmap.
+ */
+function makeImage(rect: Rect, colorAt: (point: Point) => Color): ImageHandle {
+  return {
+    width: rect.width,
+    height: rect.height,
+    __brand: "tapcue.image",
+    async colorAt(point: Point) {
+      // Image coordinates, not screen coordinates — the same trap the real one has.
+      return colorAt({ x: rect.x + point.x, y: rect.y + point.y });
+    },
+    async bytes() {
+      const out = new Uint8Array(rect.width * rect.height * 4);
+      for (let y = 0; y < rect.height; y += 1) {
+        for (let x = 0; x < rect.width; x += 1) {
+          const color = colorAt({ x: rect.x + x, y: rect.y + y });
+          const at = (y * rect.width + x) * 4;
+          out[at] = Math.round(color.red * 255);
+          out[at + 1] = Math.round(color.green * 255);
+          out[at + 2] = Math.round(color.blue * 255);
+          out[at + 3] = 255;
+        }
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * The colour formats Tapcue writes. This is the *host's* job, and the fake does it the
+ * host's way — an extension that formatted its own would be overriding a preference that
+ * was never its to make.
+ */
+function formatColor(color: Color, format: "hex" | "rgb" | "hsl"): string {
+  const { red, green, blue } = toSrgb8(color);
+  switch (format) {
+    case "rgb":
+      return `rgb(${red}, ${green}, ${blue})`;
+    case "hsl": {
+      const [r, g, b] = [red / 255, green / 255, blue / 255];
+      const max = Math.max(r, g, b);
+      const min = Math.min(r, g, b);
+      const span = max - min;
+      const lightness = (max + min) / 2;
+      if (span === 0) return `hsl(0, 0%, ${Math.round(lightness * 100)}%)`;
+      const saturation = span / (1 - Math.abs(2 * lightness - 1));
+      const sector =
+        max === r ? ((g - b) / span) % 6 : max === g ? (b - r) / span + 2 : (r - g) / span + 4;
+      const hue = ((sector * 60) % 360 + 360) % 360;
+      return `hsl(${Math.round(hue)}, ${Math.round(saturation * 100)}%, ${Math.round(lightness * 100)}%)`;
+    }
+    default:
+      return colorHex(color).toUpperCase();
+  }
+}
+
+function toSrgb8(color: Color): { red: number; green: number; blue: number } {
+  const hex = colorHex(color);
+  return {
+    red: Number.parseInt(hex.slice(1, 3), 16),
+    green: Number.parseInt(hex.slice(3, 5), 16),
+    blue: Number.parseInt(hex.slice(5, 7), 16),
+  };
+}