@tapcue/extension-sdk 0.1.0

package/src/capabilities.ts

@@ -0,0 +1,1037 @@
+/**
+ * Capability objects reachable from the invocation context.
+ *
+ * **The capability surface is the grant.** A permission declared `required` in the
+ * manifest is guaranteed at runtime — denying it means the extension is never
+ * enabled — so extension code does not check for it. A permission declared
+ * `optional` may be absent, and then the capability, or the individual method
+ * where the permission table names methods separately (`clipboard.read` vs
+ * `clipboard.write`), is simply `undefined`. There is no permission-query API:
+ * asking whether you may do a thing is the same as looking at whether you can.
+ *
+ * Every underlying host op still re-checks the effective grant on every call, so a
+ * revocation lands immediately — even mid-invocation, after your check passed.
+ *
+ * **Capability methods are bound.** Pulling one off its object keeps it working —
+ * `requireCapability(ctx.screen?.overlay, "screen.overlay")` is the only way to
+ * narrow a *method*-level unit in one expression, and it would be a trap if the
+ * result then lost its receiver. Detaching one does not detach it from the grant
+ * check either: the op re-checks on call, not on capture.
+ */
+
+import type { JsonValue } from "./json.js";
+import type { Signal } from "./reactive.js";
+
+/* ------------------------------------------------------------------ http --- */
+
+export interface HttpCapability {
+  /** Shorthand for `client().fetch(...)`. */
+  fetch(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+  /**
+   * A client handle with pinned options. The handle lives in the host's resource
+   * table; a secret attached here is applied by the broker after the destination
+   * is approved, so its plaintext never enters the isolate.
+   */
+  client(options?: HttpClientOptions): HttpClient;
+}
+
+export interface HttpClient {
+  fetch(url: string, init?: HttpRequestInit): Promise<HttpResponse>;
+}
+
+export interface HttpClientOptions {
+  headers?: Record<string, string>;
+  /** Attach a secret to every request this client makes. */
+  authorization?: { secret: SecretReference; header?: string; scheme?: string };
+}
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+
+export interface HttpRequestInit {
+  method?: HttpMethod;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array;
+  /** Always pass `ctx.signal` so cancellation reaches the in-flight request. */
+  signal?: AbortSignal;
+  /** Lower than the host limit only; the host cap always wins. */
+  maxResponseBytes?: number;
+}
+
+export interface HttpResponse {
+  status: number;
+  ok: boolean;
+  /** Lowercased header names. Hop-by-hop and cookie headers are stripped. */
+  headers: Readonly<Record<string, string>>;
+  /** Final URL after redirects (every hop is re-checked against the grant). */
+  url: string;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  bytes(): Promise<Uint8Array>;
+}
+
+/* --------------------------------------------------------------- storage --- */
+
+export interface StorageCapability {
+  /** Namespaces are private to the extension; another extension's is unreachable. */
+  open(namespace: string): StorageHandle;
+}
+
+export interface StorageHandle {
+  get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined>;
+  set(key: string, value: JsonValue): Promise<void>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+/* ----------------------------------------------------------------- cache --- */
+
+/** Evictable at any time. Never store anything you cannot recompute. */
+export interface CacheCapability {
+  get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined>;
+  set(key: string, value: JsonValue, options?: { ttlMs?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/* --------------------------------------------------------------- secrets --- */
+
+export interface SecretsCapability {
+  /** An opaque handle. Reading plaintext requires a separate, stronger grant. */
+  reference(name: string): SecretReference;
+}
+
+export interface SecretReference {
+  readonly name: string;
+  readonly __brand: "tapcue.secret";
+}
+
+/* ---------------------------------------------------- invocation context --- */
+
+/**
+ * **The situation that summoned Tapcue**, and nothing else.
+ *
+ * Every method here answers the same question: *what was true at the moment the user
+ * pressed the hotkey?* Which app was in front, what they had selected, which files were
+ * highlighted in the file manager. These facts are invocation-scoped — they are
+ * meaningless outside the call that observed them, and an extension that cached one is
+ * holding a stale answer to a question nobody asked again.
+ *
+ * This is deliberately **not** where machine-wide queries live. "Which fonts are
+ * installed" and "where am I" are facts about the *machine*, true whether or not
+ * anyone opened the launcher, and they sit on their own capabilities (`ctx.fonts`,
+ * `ctx.location`). The tell is the consent
+ * string: "read the text you had selected when you opened Tapcue" and "see the fonts
+ * installed on this Mac" are not the same kind of permission, so they are not the same
+ * kind of capability.
+ *
+ * Each method is present only when its own permission unit is granted.
+ */
+export interface InvocationContextCapability {
+  frontmostApp?(): Promise<FrontmostAppSnapshot | null>;
+  selectedText?(): Promise<string | null>;
+  selectedFiles?(): Promise<FileHandle[]>;
+}
+
+export interface FrontmostAppSnapshot {
+  id: string;
+  name: string;
+}
+
+/* ------------------------------------------------- machine-wide queries --- */
+
+/**
+ * **The fonts installed on this machine.**
+ *
+ * Enumeration is a platform API — `CTFontManagerCopyAvailableFontFamilyNames` on macOS,
+ * DirectWrite on Windows, fontconfig on Linux — and emphatically *not* a directory read:
+ * families span multiple files, one `.ttc` holds several families, and a font can be
+ * deactivated without moving. So the host resolves it and hands back a normalized list;
+ * the guest never touches a platform API and never needs a filesystem grant to see a font.
+ *
+ * One constraint is borrowed from the web's Local Font Access API and is load-bearing: the result
+ * is **sorted**, so install order leaks no entropy about the machine. The other borrowed rule —
+ * withhold file paths — was deliberately reversed, and `FontFamily.path` says why.
+ */
+export interface FontsCapability {
+  list(): Promise<FontFamily[]>;
+}
+
+/**
+ * A font family — the unit a person actually searches for ("Helvetica Neue"), not a file.
+ * The mapping between families and files is many-to-many, which is why this models the family
+ * and treats a file as one of its attributes rather than its identity.
+ */
+export type FontFamily = {
+  /** Localized display name. This is the row title, and the value a `font:` icon names. */
+  family: string;
+  /** What kind of typeface it is, from the font's own OS/2 family class. */
+  classification: FontClassification;
+  faces: FontFace[];
+  /**
+   * The rest comes from the font file's `name` table, so it is present only when the designer
+   * filled it in — most system fonts carry a copyright and a version, far fewer carry a
+   * description. Absent means "the file does not say", never "the host would not tell you".
+   */
+  description?: string;
+  designer?: string;
+  manufacturer?: string;
+  version?: string;
+  copyright?: string;
+  /** e.g. `"OpenType (TrueType)"`, `"OpenType (PostScript)"`, `"TrueType Collection"`. */
+  format?: string;
+  /**
+   * Where the family's primary face lives on disk.
+   *
+   * This is a deliberate, reversible decision and it was made the other way first. The original
+   * shape withheld paths on the grounds that `CTFontManagerCopyAvailableFontURLs()` is macOS-only
+   * — but that is the *enumeration* API; per-face file access exists on all three platforms
+   * (DirectWrite's `IDWriteFontFace::GetFiles`, fontconfig's `FC_FILE`), so portability was never
+   * the real objection. The real cost is that `~/Library/Fonts/…` names the user, and it is
+   * accepted here because "where does this font live" is what a font browser is *for*, and it is
+   * what makes revealing the file possible at all.
+   */
+  path?: string;
+};
+
+/**
+ * The typeface's own classification, read from its OS/2 family class rather than guessed from
+ * the name. `unknown` is common and honest: plenty of fonts leave the field unset.
+ */
+export type FontClassification =
+  | "serif"
+  | "sans-serif"
+  | "monospace"
+  | "script"
+  | "display"
+  | "symbol"
+  | "unknown";
+
+/** One face within a family. */
+export type FontFace = {
+  /** Stable machine identity for this face. */
+  postscriptName: string;
+  fullName: string;
+  /** "Regular", "Bold Italic", … */
+  style: string;
+  /** Normalized 100–900, when the platform reports it. */
+  weight?: number;
+  italic?: boolean;
+  /** From the platform's symbolic traits. Worth having: "monospaced" is a real filter. */
+  monospaced?: boolean;
+};
+
+/**
+ * **Where this machine is.**
+ *
+ * Promoted out of `context.*` because it is not about the invocation: your position is true
+ * whether or not you opened the launcher. Denying it stays a first-class outcome — an
+ * extension must remain useful when this capability is absent (a weather extension takes a
+ * city name instead).
+ */
+export interface LocationCapability {
+  current(options?: { maxAgeMs?: number }): Promise<LocationSnapshot | null>;
+}
+
+export interface FileHandle {
+  readonly id: string;
+  readonly name: string;
+  readonly __brand: "tapcue.file";
+}
+
+/* --------------------------------------------------------------- process --- */
+
+/**
+ * **The processes running on this machine.**
+ *
+ * Enumeration is a platform API — `libproc`/`sysctl` on macOS, `/proc` on Linux, the
+ * ToolHelp/NT query on Windows — and emphatically *not* something a sandboxed guest can
+ * reach: it has no child process to shell out to `ps`, no socket, no `/proc` read. So the
+ * host resolves it and hands back a normalized, host-sorted list, exactly as `fonts.list()`
+ * does — the guest never touches a platform API.
+ *
+ * The read and the effect are split across the two contexts, and the split is the whole
+ * security argument, mirroring `clipboard.read` vs `clipboard.write`:
+ *
+ * - **read** (`list`) is on `ReadonlyProcessManager`, reachable from a `query` — a keystroke
+ *   may ask "what is running" to render rows, but a keystroke must never *act* on a process.
+ * - **the effect** (`kill`, `activate`) is on `WritableProcessManager`, reachable only from an
+ *   `ActionContext`. An extension that reaches for `kill` from a `query` fails to compile.
+ *
+ * The manage grant is `process.kill`. It carries no manifest-time scope — a pid is assigned at
+ * runtime and recycled, so a manifest cannot name which processes may be killed — and that is
+ * deliberate: the confirm dialog, built by the host from its *own* process table, is the whole
+ * boundary. See `WritableProcessManager.kill`.
+ */
+export interface ReadonlyProcessManager {
+  /**
+   * Every running process, **host-sorted** (by pid) so launch order — which is entropy about
+   * the machine — never leaks, the same rule `fonts.list()` follows. `ProcessInfo.command`
+   * (argv) is present only when the separate `process.command` unit is granted.
+   */
+  list(): Promise<ProcessInfo[]>;
+}
+
+/** Reading, plus the effects. Only an `ActionContext` has one, and only with `process.kill`. */
+export interface WritableProcessManager extends ReadonlyProcessManager {
+  /**
+   * Ask Tapcue to end a process.
+   *
+   * **Fire-and-forget, and the extension does not decide how it dies.** This returns
+   * immediately — the isolate may be dropped the instant the action completes — and Tapcue
+   * shows a confirm it builds from its *own* process table (naming the process, never a string
+   * the extension supplied): **Cancel / Quit (⏎, SIGTERM) / Force Quit (⌘⏎, SIGKILL)**. The
+   * *user* picks the signal; the extension never learns the outcome. Its list simply shows the
+   * process gone on the next `list()`. The extension says *which*, Tapcue and the user say
+   * *whether* and *how* — the same shape as `clipboard.write` handing over a value the host
+   * decides how to land.
+   *
+   * The host coalesces every `kill` from one action into a single confirm (Cancel / Quit N /
+   * Force Quit N) and caps the batch, so an action that loops over the list cannot spray
+   * dialogs. It refuses to end its own process, the window server, or the init process
+   * whatever the pid, and the OS refuses another user's processes regardless.
+   *
+   * Present only with `process.kill`, and only in an action.
+   */
+  kill?(pid: number): void;
+  /**
+   * Bring the process's application to the front — "jump to it". Benign, so no confirm; the
+   * host performs it (`NSRunningApplication.activate` and its cross-platform siblings), the
+   * extension cannot. A pid with no visible application is a no-op. The `process.kill` grant
+   * carries it too.
+   */
+  activate?(pid: number): void;
+}
+
+/**
+ * One running process. A `type`, not an `interface`, so it is assignable to `JsonValue` — it
+ * rides as a scope subject and must round-trip.
+ */
+export type ProcessInfo = {
+  pid: number;
+  ppid: number;
+  /** Executable / display name, e.g. "node", "Google Chrome". */
+  name: string;
+  /**
+   * Instantaneous CPU share, as a percentage the platform reports (may exceed 100 across
+   * cores). It is a snapshot: a fresh `list()` re-reads it, so a view keeps it current by
+   * re-fetching on the events it cares about, not by the host polling behind its back.
+   */
+  cpuPercent: number;
+  /** Resident memory in bytes. */
+  memoryBytes: number;
+  /** The owning user's login name, when the platform reports it. */
+  user?: string;
+  startedAtMs?: number;
+  /** TCP ports this process is listening on, folded in from the same platform enumeration. */
+  ports?: number[];
+  /**
+   * The full command line (argv, joined). Present **only when `process.command` is granted** —
+   * a separate, off-by-default unit, because argv routinely carries secrets (`mysql -p…`,
+   * `--token=…`, `ssh -i …`) that the benign `process.list` read must never leak. Splitting it
+   * out is the same move that separates `clipboard.read` from `clipboard.write`: the sensitive
+   * half is its own approval.
+   */
+  command?: string;
+};
+
+/**
+ * Coarse by default: roughly city-level, resolved and reverse-geocoded by the
+ * native app so the extension needs no additional network host to name a place.
+ */
+export interface LocationSnapshot {
+  latitude: number;
+  longitude: number;
+  accuracyMeters: number;
+  /** Reverse-geocoded place name, when the platform can supply one. */
+  name?: string;
+  region?: string;
+  countryCode?: string;
+  /** IANA time zone id, e.g. "Asia/Shanghai". */
+  timeZone?: string;
+  capturedAtMs: number;
+}
+
+/* ------------------------------------------------------------- clipboard --- */
+
+/**
+ * Reading a clipboard can lift the password you copied a moment ago. Writing cannot. They
+ * are separate permissions, and — since they are also a read and an *effect* — they now sit
+ * on separate contexts: `read` is on every context, `write` only on an action's.
+ */
+export interface ClipboardReadCapability {
+  read?(): Promise<string | null>;
+}
+
+/** Reading, plus the effect. Only an `ActionContext` has one. */
+export interface ClipboardCapability extends ClipboardReadCapability {
+  /**
+   * Text, or a value Tapcue knows how to write.
+   *
+   * Handing over a `Color` rather than a string is not a convenience — it is the only way
+   * to be *correct*. "Which format do I want colours in" is a preference of the person
+   * using the launcher, not of the extension that happened to produce one; an extension
+   * that formatted its own would be overriding a choice that was never its to make, and
+   * two colour extensions would disagree about what `hsl()` rounds to. So the extension
+   * says *what*, Tapcue says *how*, and every colour anything copies comes out the same.
+   *
+   * The same argument is why an image is a typed `ClipboardImage`, not a byte blob with a
+   * flavour string the extension picked: the extension supplies the pixels, and which
+   * pasteboard flavours a PNG becomes (`public.png`, plus an `NSImage` on macOS) is the
+   * host's call. §23.5 recorded that the clipboard was never text-only — Tapcue just had
+   * nothing but text and colours to put on it. A drawing is the first image that needs it.
+   */
+  write?(value: string | Color | ClipboardImage | ClipboardSecret): Promise<void>;
+}
+
+/** A raster image to place on the clipboard. The host owns which flavours it becomes. */
+export type ClipboardImage = { png: Uint8Array };
+
+/**
+ * **A secret on the clipboard** — a password, a one-time code, a token.
+ *
+ * The same argument as `Color` and `ClipboardImage`: the extension says *what*, the host says
+ * *how*. What "a secret" means on macOS is the `org.nspasteboard.org` Concealed and Transient
+ * markers, which every well-behaved clipboard manager reads as "do not remember this" —
+ * **Tapcue's own clipboard history among them.** That is the whole point: without a way to say
+ * this, a password manager extension copying a password files the password into the launcher's
+ * searchable history in plain text, and the extension has no way to stop it.
+ *
+ * It is not a flag on a string, because it is not a formatting choice: it is a different kind of
+ * value, and which markers a platform writes for it is the host's business. The bytes are still
+ * plain text on the pasteboard — a marker asks, it does not encrypt — so this is a request that
+ * the machine forget, not a promise that it cannot read.
+ */
+export type ClipboardSecret = { secret: string };
+
+/* ----------------------------------------------------------------- files --- */
+
+/**
+ * **Reading the places the manifest declared** (spec 016 §2). Read-only, and it is not a filesystem:
+ * there is no path here at all.
+ *
+ * The extension declared *where* at install time and the host resolved it, so what crosses at
+ * runtime is a **grant index and a leaf name** — never a path the guest composed. That is what makes
+ * escaping impossible rather than merely checked: there is nothing to escape *with*. The host
+ * re-validates the resolved real path on every read anyway, because a symlink inside the tree leads
+ * out of it.
+ *
+ * A read, so it is on every context: an extension whose rows come from a file needs them while a
+ * person is typing.
+ */
+export interface FilesCapability {
+  /**
+   * The files one `files.read` grant currently matches, freshest first. `grant` is the index of the
+   * entry in the manifest's `files.read` array — the extension declared the order, so it knows it.
+   */
+  list(grant: number): Promise<FileEntry[]>;
+  /** The bytes of one of those files, by the `name` `list()` returned. */
+  read(grant: number, name: string): Promise<Uint8Array>;
+  /** The same, decoded as UTF-8 — what a JSON sidecar or a `.env` actually is. */
+  readText(grant: number, name: string): Promise<string>;
+}
+
+/* --------------------------------------------------------------- queries --- */
+
+/**
+ * **Running the statements the manifest declared**, and getting rows back.
+ *
+ * Exactly `exec`'s shape, applied to a database instead of a program: the extension declared *what
+ * to ask* at install time and supplies only the values that fill the `?` holes. There is no SQL
+ * here for the same reason there is no path in `files` and no argv in `exec` — a runtime string
+ * cannot widen a template that was fixed before anything ran.
+ *
+ * It exists because a whole class of integration keeps its state in SQLite and nowhere else, and
+ * neither neighbour reaches it. `files.read` hands over bytes an extension would need a database
+ * engine to interpret, and the sandbox has no WebAssembly to bring one. `exec` needs the app to
+ * have shipped a CLI that answers the question — Codex, the integration that prompted this, ships
+ * one that can start a session and cannot list them. Handing over rows keeps the engine, the
+ * connection and every write path on Tapcue's side of the boundary.
+ *
+ * On every context, like `exec` and for the same reason: a `query` that lists a tool's sessions has
+ * to read something while a person is typing.
+ */
+export interface QueriesCapability {
+  /**
+   * Run a declared statement, filling its `?` holes in order. Rejects if the database is missing
+   * or the statement no longer prepares against it — a schema that moved is a fact the extension
+   * has to be told, not one to paper over with an empty list.
+   */
+  run(id: string, values?: readonly QueryValue[]): Promise<QueryRow[]>;
+}
+
+/** What may fill a `?` hole. JSON's scalars, which is what SQLite binds without ceremony. */
+export type QueryValue = string | number | boolean | null;
+
+/**
+ * One row, keyed by the column names the statement selected.
+ *
+ * Blobs are absent rather than encoded: a query grant exists to read a tool's *state*, and a
+ * column an extension cannot interpret without a second parser is one this was not built for.
+ */
+export type QueryRow = Record<string, string | number | null>;
+
+export interface FileEntry {
+  /** The leaf name, the only identity the guest ever sees. */
+  name: string;
+  /** Bytes. Present so an extension can skip a file it has no budget to parse. */
+  size: number;
+  /** Seconds since the epoch. */
+  modifiedAt: number;
+}
+
+/* ------------------------------------------------------------------ exec --- */
+
+/**
+ * **Running the binaries the manifest declared** (spec 016 §3).
+ *
+ * Same shape as `files`: the extension names an `id` it declared, never a path, and the host
+ * resolves and verifies the binary's identity — a code signature for an external one, the app
+ * bundle for an `inApp` one. Arguments fill the `{}` holes of the declared template positionally;
+ * a hole is always exactly one argv element, and nothing is ever handed to a shell.
+ *
+ * On every context, not just an action's: a `query` that lists a vault has to run something. The
+ * costs are paid elsewhere — one child at a time per extension, killed at the invocation's
+ * deadline, with a cap on how much it may write back.
+ */
+export interface ExecCapability {
+  /** Run a declared argv template, filling its holes. Rejects on a non-zero exit. */
+  run(id: string, args?: string[]): Promise<ExecResult>;
+  /**
+   * Talk to a binary declared `protocol: "mcp"` as a long-lived stdio MCP server.
+   *
+   * MCP is JSON-RPC over stdin/stdout and involves **no model** — it is a calling convention, not a
+   * dependency. What it buys over `run` is that the surface is self-describing (so no argv template
+   * has to be designed), enumerable (so the install sheet can list the tools by name), and served by
+   * one reused process instead of a spawn per keystroke.
+   */
+  mcp(id: string): Promise<McpSession>;
+}
+
+export interface ExecResult {
+  /** Decoded as UTF-8 and capped by the host; `truncated` says the cap was hit. */
+  stdout: string;
+  stderr: string;
+  /**
+   * **What the program said about itself.** A non-zero exit is a result, not an error — `run` only
+   * *rejects* when the binary could not be run at all (no such binary, wrong signature, past the
+   * deadline), which is a different thing to tell somebody than "the tool refused".
+   *
+   * A CLI that is installed but not signed in exits non-zero with a perfectly clear `stderr`, and
+   * an extension that cannot see the difference will send that person to install what they have.
+   */
+  exitCode: number;
+  truncated: boolean;
+}
+
+/** A connected MCP server. The host owns the process; this is the conversation. */
+export interface McpSession {
+  /** The tools it offers, each with the JSON Schema for its arguments. */
+  listTools(): Promise<McpTool[]>;
+  /** Call one. The result is whatever the server returned, as JSON. */
+  callTool(name: string, args?: Record<string, JsonValue>): Promise<JsonValue>;
+}
+
+export interface McpTool {
+  name: string;
+  description?: string;
+  inputSchema?: JsonValue;
+}
+
+/* ---------------------------------------------------------------- native --- */
+
+export interface NativeActionsCapability {
+  /**
+   * Open a URL in the user's default handler. **Needs no permission** — it is an action-only
+   * effect (a keystroke cannot reach it), and the host restricts it to `http`/`https`, so it
+   * launches nothing and only opens a visible, reversible browser tab. Present on every
+   * `ActionContext`; the extension never gets a browser back.
+   */
+  open?(url: string): Promise<void>;
+  /**
+   * Reveal a user-selected file in the platform file manager. **Needs no permission**: the
+   * `FileHandle` came from `context.selected-files`, so this only shows a file the user already
+   * handed over. Action-only. (Not yet built in the host — see architecture §23.3.)
+   */
+  reveal?(file: FileHandle): Promise<void>;
+  /** Post a notification. Needs the `native.notify` unit — a notification is unsolicited. */
+  notify?(notification: { title: string; body?: string }): Promise<void>;
+  /**
+   * Write one file to a user-visible location. **The extension names the file and supplies
+   * the bytes; the host decides where it lands and sanitizes the name** — it never returns
+   * a path, and the extension can never target an arbitrary directory. On macOS the file
+   * goes to `~/Downloads`, the same place a browser download does.
+   *
+   * This is `native.*` and not a filesystem: like `open` and `reveal`, the host performs an
+   * effect the extension cannot perform itself. It is the only `native` verb that leaves
+   * bytes on disk, which is why it is its own permission unit (`native.save`).
+   */
+  save?(file: SaveFile): Promise<void>;
+}
+
+export interface SaveFile {
+  /** A file name, not a path. The host strips any directory part and sanitizes the rest. */
+  name: string;
+  data: Uint8Array;
+  /** A MIME type the host maps to the platform's own file typing, e.g. `image/png`. */
+  type: string;
+}
+
+/* ---------------------------------------------------------------- bridge --- */
+
+/**
+ * **The message bridge to a live WebView surface** (architecture §12.1).
+ *
+ * A `WebViewScene` runs the extension's own HTML/JS with no network of its own. Everything
+ * it does that leaves the sandbox — read the pixels it drew, hand them to `native.save` —
+ * flows through the extension isolate, and this is the channel. `request` sends a message
+ * to the surface currently up and awaits its reply.
+ *
+ * **The reply is untrusted input**, exactly like an HTTP body: the WebView is the
+ * extension's own code, but it is code the shell does not audit at each keystroke, so the
+ * isolate validates what comes back rather than trusting its shape.
+ *
+ * It is on `ActionContext` and nowhere else, and it needs `ui.webview`. The surface it talks
+ * to is **owned by the shell, not the isolate** — the isolate that presented the surface was
+ * very likely evicted while the user drew (§10.5), so a fresh `invoke` reconnects to the
+ * live surface through this capability rather than holding it across the call. Present only
+ * while a surface this extension declared is actually up; absent otherwise.
+ */
+export interface BridgeCapability {
+  request(message: BridgeValue): Promise<BridgeValue>;
+}
+
+/**
+ * What crosses the bridge: the same boundary vocabulary as everywhere else (§8) — JSON, plus
+ * `Uint8Array` for binary. A drawing comes back as `{ png: <Uint8Array> }`, so the isolate
+ * can hand it straight to `native.save` or `clipboard.write` without a base64 detour.
+ */
+export type BridgeValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Uint8Array
+  | BridgeValue[]
+  | { [key: string]: BridgeValue | undefined };
+
+/* ---------------------------------------------------------------- screen --- */
+
+/**
+ * **The screen.** An overlay the extension draws on top of everything, the pointer
+ * events on it, and — separately granted — the pixels under it.
+ *
+ * This is not a colour-picker API. A colour picker is one program you can write with it;
+ * a ruler, alignment guides, a region selector, a window inspector, an annotation tool
+ * are others, and not one of them needs a new host verb. The host supplies the surface,
+ * the input, and the renderer; what appears on it is the extension's program.
+ *
+ * Two units, and the split is the whole security argument:
+ *
+ * - `screen.overlay` — draw, and receive pointer input. **No pixel access whatsoever.**
+ *   A ruler asks for this and nothing else, and can never read your screen.
+ * - `screen.capture` — read pixels. On macOS this is the Screen Recording permission, and
+ *   it should be: it is the same power.
+ *
+ * The host keeps what it must never hand over: the identity badge naming the extension
+ * (which an overlay cannot cover), the Esc that always closes (an extension never sees it
+ * and cannot suppress it), the deadline, and the rule that an overlay can never cover
+ * Tapcue's own permission UI.
+ *
+ * **The overlay receives no keyboard at all.** Pointer events, with their modifiers, and
+ * nothing else — arrow keys warp the cursor and arrive as pointer moves (see `OverlayEvent`).
+ * Nothing in this class of tool needs text entry, and without it, an overlay that paints a
+ * convincing fake password prompt still cannot collect what is typed into it.
+ */
+export interface ScreenCapability {
+  /**
+   * Ask Tapcue to put an overlay on the screen. Resolves once it is up.
+   *
+   * `create`, not `open`, and not `overlay()`: the extension is *asking for one to be made*.
+   * It cannot make one — a sandbox with a window-server connection is a sandbox with windows,
+   * and then the badge, the Esc, and the rule that an overlay may never cover Tapcue's own
+   * permission UI all stop being enforceable.
+   *
+   * It is on `ActionContext` and nowhere else, which is the type system saying what §9.4 used
+   * to say at runtime: a query runs on a keystroke, and a keystroke must never be able to
+   * cover the display.
+   */
+  createOverlay?(spec?: OverlaySpec): Promise<OverlaySession>;
+}
+
+export interface OverlaySpec {
+  /**
+   * **What kind of thing is on the screen** — and from that, who holds focus, who gets the
+   * pointer, and how it ends. Not a styling choice: the two modes are opposites on every one.
+   *
+   * - `"tool"` (the default) — the ruler, the eyedropper, the region selector. It spans every
+   *   display, it *is* what you are working in, so it takes focus and keeps it, it receives the
+   *   pointer, and a watchdog closes it if you stop interacting. The user is using the overlay.
+   *
+   * - `"coach"` — a card that says what to do **somewhere else**. Turn on a setting in the app
+   *   this extension integrates with, grant a permission in System Settings, install a browser
+   *   extension. The user is using *the other app*, and every property flips to serve that: it
+   *   is card-sized rather than screen-sized (so every click outside it reaches the app
+   *   underneath, because outside it there is no window of ours at all), it never activates
+   *   Tapcue or takes key, and it receives **no pointer events whatsoever** — the extension
+   *   learns nothing about where you clicked while it is up.
+   *
+   * A coach card cannot trap anybody — it covers a few hundred points and swallows nothing — so
+   * it is not on the tool's 30-second leash. It lives until the extension closes it, the user
+   * clicks its close button, or a long deadline expires.
+   */
+  mode?: "tool" | "coach";
+
+  /**
+   * **Put the card where the work is.** `coach` only.
+   *
+   * The bundle id of an app in the manifest's `integratesWith` — the same list `when.bundleId`,
+   * an `exec` grant's `inApp`, and a custom-scheme `native.open` resolve against. The host finds
+   * that app's frontmost window and places the card against it; if the app is not running or has
+   * no window, the card goes to the bottom of the main display, which is where the user is
+   * looking anyway once the app they were sent to opens.
+   *
+   * The extension names an app and gets a coordinate space back — never the window's position.
+   * Where somebody's windows are is a fact about their screen, and reading the screen is
+   * `screen.capture`, a unit this is deliberately not.
+   */
+  anchor?: { app: string };
+
+  /**
+   * Which chrome Tapcue puts around it.
+   *
+   * - `"tapcue"` (the default) — Tapcue's own frame: a window that names the extension and
+   *   carries a close button. What a ruler or an annotation tool wants: it is a *tool*, and
+   *   it should look like one.
+   * - `"none"` — full-bleed, no chrome. What an eyedropper wants, because a frame around the
+   *   screen you are sampling is a frame over the thing you are trying to see.
+   *
+   * The choice is the extension's; what the choice cannot change is Tapcue's. **Esc closes
+   * either one**, the extension never sees the key, and a frameless overlay still carries the
+   * badge naming it. Frameless buys a clean screen, never anonymity.
+   *
+   * Ignored in `coach` mode, which has exactly one chrome: the card. A card that could take its
+   * frame off would be a rectangle of unattributed instructions floating over somebody else's
+   * app, which is the shape of every phishing overlay ever written — so the name and the close
+   * button are not the extension's to remove.
+   */
+  frame?: "tapcue" | "none";
+  /** The pointer over the overlay. `none` for a picker drawing its own loupe. */
+  cursor?: "crosshair" | "none" | "default";
+  /** Dim the desktop behind, 0–1. The shell owns what "dimmed" looks like. */
+  dim?: number;
+}
+
+/**
+ * A live overlay. Ends when the user dismisses it, the invocation is cancelled, or
+ * `close()` is called. Every method is dead after that.
+ */
+export interface OverlaySession {
+  /**
+   * What there is to draw on. For a `tool`, the whole desktop in points — one rect spanning every
+   * display. For a `coach` card, the card's content area at the origin: the extension is told how
+   * much room it has, and nothing about where on the screen that room is.
+   */
+  readonly bounds: Rect;
+
+  /**
+   * Pointer and non-printable key events, in order, until the overlay closes. The stream
+   * ends with `cancelled` if the user dismissed it — Esc is the host's, not yours.
+   *
+   * A `coach` card produces no pointer events at all: the whole point is that the user is
+   * working in another app, and an extension that could watch the clicks that land there has
+   * been handed something no card needs. The stream yields exactly one `cancelled`, when it ends.
+   */
+  events(): AsyncIterable<OverlayEvent>;
+
+  /**
+   * Draw a **retained** layer. It stays until you update or remove it — an overlay is not
+   * an immediate-mode canvas, and most tools draw once and then only `move()`.
+   */
+  draw(nodes: SvgNode[]): Layer;
+
+  /**
+   * Capture a region of the screen. Requires `screen.capture`.
+   *
+   * The pixels stay in the host: you get a handle, an `<image>` node can draw it, and
+   * `colorAt` reads one pixel out of it. A magnifier therefore costs no pixel traffic at
+   * all — the shell captured it and the shell draws it.
+   */
+  capture?(rect: Rect): Promise<ImageHandle>;
+
+  /** Idempotent. `finally` is the right place. */
+  close(): void;
+}
+
+/**
+ * A retained layer. `move` is the cheap one: it re-transforms what is already there
+ * rather than re-serializing it, which is what makes a ruler that follows the cursor
+ * cost nothing.
+ */
+export interface Layer {
+  move(to: Point): void;
+  update(nodes: SvgNode[]): void;
+  remove(): void;
+}
+
+/** Host-side pixels. The bytes cross into the isolate only if you ask for them. */
+export interface ImageHandle {
+  readonly width: number;
+  readonly height: number;
+  /** One pixel, in the image's own coordinates. */
+  colorAt(point: Point): Promise<Color>;
+  /** The whole thing, RGBA8. A screenshot tool pays this; a colour picker never does. */
+  bytes(): Promise<Uint8Array>;
+  readonly __brand: "tapcue.image";
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * **There is no key event, and writing the colour picker is what proved there must not be.**
+ *
+ * A picker needs pixel-precise aim, so the obvious move is to hand the extension arrow
+ * keys. But the loupe is glued to the pointer by `translate($pointer)`, and a *logical*
+ * cursor the extension moves with arrow keys is a cursor `$pointer` no longer agrees with —
+ * the 60 fps binding breaks the moment the feature is used.
+ *
+ * So the host warps the **real** cursor instead, one point per press and ten with shift,
+ * which is what the platform's own picker does. `$pointer` stays the single source of truth,
+ * the extension receives an ordinary `pointer-move`, and the key event it would have needed
+ * does not have to exist. Modifiers ride on the pointer events, for the tools that constrain
+ * with them — a ruler holding shift to snap to 45°.
+ *
+ * The security note survives it: no printable key ever reaches an overlay, so one that paints
+ * a convincing fake password prompt still cannot collect what is typed into it.
+ */
+export type OverlayEvent =
+  | { kind: "pointer-move"; at: Point; shift: boolean; alt: boolean }
+  | { kind: "pointer-down"; at: Point; shift: boolean; alt: boolean }
+  | { kind: "pointer-up"; at: Point; shift: boolean; alt: boolean }
+  /** Esc, focus lost, deadline, revocation. Always the last event. */
+  | { kind: "cancelled" };
+
+/* ------------------------------------------------------------ svg subset --- */
+
+/**
+ * What an overlay draws: **the core of SVG, as JSON**.
+ *
+ * Not invented here. SVG is a specified, mature, declaratively-rendered 2D model with
+ * implementations on every platform, and its dangerous parts are exactly the ones that
+ * are absent below: no `script`, no `foreignObject`, no external or remote `href`, no CSS,
+ * no filters. What remains draws every tool in this class — a magnifier, a ruler, a
+ * marquee, an arrow, a freehand stroke — and needs no new node the next time.
+ *
+ * JSON rather than XML because an overlay re-draws while the pointer moves; parsing XML at
+ * frame rate would be a waste and would inherit XML's attack surface for nothing.
+ *
+ * Author it in JSX: `@tapcue/extension-sdk/overlay` ships the **primitives** — `<G>`, `<Rect>`,
+ * `<Circle>`, `<Line>`, `<Path>`, `<Text>`, `<OverlayImage>`, and the live bindings
+ * (`translate(pointer)`, `pointerColor`, `livePointer`) — compiling to exactly these nodes. It
+ * does **not** ship `Magnifier` / `Ruler` components: an SDK betting on what extensions draw is the
+ * `pick.color`-verb mistake one layer up. A magnifier is thirty JSX lines that live in the
+ * extension that wants one; the host knows only the nodes, so it costs nothing to audit or port.
+ *
+ * **The live colour binding.** A `fill`, a `stroke`, or the body of a `text` may be the
+ * literal string `$pointerColor` instead of a colour. The shell fills it, every frame, with
+ * the pixel under the cursor — the same pixel `translate($pointer)` centres a loupe on — and
+ * substitutes it as `#RRGGBB`. It is to colour what `$pointer` is to position: a colour
+ * picker's swatch and hex readout track the cursor with **zero IPC**, so they never lag the
+ * loupe the way a colour the extension read and drew a few frames earlier does. And like
+ * `$pointer`, it hands the extension nothing — an extension that needs the committed colour
+ * still reads one pixel with `screen.capture` on click.
+ */
+export type SvgNode =
+  | { tag: "g"; transform?: Transform; opacity?: number; clip?: CircleClip; children: SvgNode[] }
+  | { tag: "rect"; x: number; y: number; width: number; height: number; rx?: number; fill?: string; stroke?: string; strokeWidth?: number }
+  | { tag: "circle"; cx: number; cy: number; r: number; fill?: string; stroke?: string; strokeWidth?: number }
+  | { tag: "line"; x1: number; y1: number; x2: number; y2: number; stroke?: string; strokeWidth?: number; dash?: number[] }
+  | { tag: "path"; d: string; fill?: string; stroke?: string; strokeWidth?: number; dash?: number[] }
+  | { tag: "text"; x: number; y: number; text: string; fill?: string; fontSize?: number; anchor?: "start" | "middle" | "end" }
+  | { tag: "image"; href: ImageSource; x: number; y: number; width: number; height: number; rendering?: "pixelated" | "smooth" };
+
+/**
+ * A circular clip on a `g`, in the group's own coordinates: its children draw only inside the
+ * circle. The vocabulary grew here on evidence — a magnifier is a *round* lens over square pixels,
+ * so the square `live: pointer` capture and its grid are clipped to the circle, while the crosshair
+ * and the rim are drawn as siblings on top, unclipped. `rotate`/`scale` on the same group compose
+ * with it, and `translate($pointer)` carries the whole lens along with no IPC.
+ */
+export type CircleClip = { cx: number; cy: number; r: number };
+
+/**
+ * `translate(x y)` / `scale(k)` / `rotate(deg)`, or the one **live binding**:
+ * `translate($pointer)`.
+ *
+ * The binding exists because **the extension cannot be in the 60 fps loop**. A round trip
+ * to the isolate is microseconds, but a loupe that trails the cursor by a frame is a loupe
+ * nobody can aim. So a subtree that must track the pointer says so, and the shell moves it
+ * locally, every frame, with no IPC at all.
+ *
+ * It hands the extension nothing: `$pointer` is a coordinate the *shell* substitutes. An
+ * extension that wants to know where the cursor is still has to subscribe to `pointer-move`
+ * like everyone else. There is a colour counterpart for `fill`/`stroke`/`text` bodies,
+ * `$pointerColor` — see the `SvgNode` docs.
+ */
+export type Transform = string;
+
+/**
+ * `<image href>`: either a capture you took, or the screen around the cursor resolved by
+ * the shell every frame. The second is how a magnifier stays glued to the pointer — and
+ * either way the pixels never enter the isolate.
+ */
+export type ImageSource = ImageHandle | { live: "pointer"; width: number; height: number };
+
+/**
+ * A colour — the same value Tapcue itself understands (`color` is a native subject type,
+ * like `file`). The extension formats none of it: hex, RGB, HSL and the swatch are the
+ * shell's, and they are the same for every colour whoever produced it.
+ *
+ * A `type`, not an `interface`: an interface gets no implicit index signature and so is not
+ * assignable to `JsonValue` — which this must be, because it is a scope subject and it goes
+ * into `storage`.
+ *
+ * **Components in their own colour space, not 8-bit.** Displays are wide-gamut: an orange
+ * sampled off a P3 screen has no sRGB byte triple, and rounding it into one is a loss a
+ * designer can see. The host reports what it measured and converts nothing.
+ */
+export type Color = {
+  /** 0–1, in `colorSpace`. May exceed sRGB's gamut when `colorSpace` is `display-p3`. */
+  red: number;
+  green: number;
+  blue: number;
+  /** The space `red`/`green`/`blue` are in. Widen this union, never silently convert. */
+  colorSpace: "srgb" | "display-p3";
+};
+
+/* -------------------------------------------------- settings & environment --- */
+
+/** A validated snapshot of the extension's own manifest-declared settings. */
+export interface SettingsSnapshot {
+  /** Declared keys always resolve (the host fills manifest defaults). */
+  get<T extends JsonValue = JsonValue>(key: string): T;
+  all(): Readonly<Record<string, JsonValue>>;
+  /**
+   * **The same setting, as a signal you can watch.**
+   *
+   * `get` is a snapshot — right at the moment it is called, and wrong from the moment anything
+   * changes it. That is fine for a value the view merely renders, and wrong for one the view is
+   * *governed by*: a refresh interval read once by a `whileVisible` setup keeps a `setInterval`
+   * ticking at the old rate no matter what anyone chooses afterwards.
+   *
+   * So this returns a real `Signal`, with two things bolted to it:
+   *
+   * - **Bind it** anywhere a signal goes (a title, an `<Action icon>` through `lookup`) and the
+   *   shell re-renders locally when the value changes, with no isolate wake.
+   * - **Read it in a `whileVisible` setup** and the setup is *restarted* when the value changes,
+   *   so whatever it armed is re-armed against the new one. A setup has always had to be
+   *   idempotent — it re-runs on every reopen — so this asks nothing new of it.
+   *
+   * Only inside a `view` handler (it creates a cell), and only for a key the manifest declares.
+   * Create it unconditionally at the top of the view, like every other `signal` — the cells are
+   * positional and the order has to be stable across a render and an action dispatch.
+   */
+  signal<T extends JsonValue = JsonValue>(key: string): Signal<T>;
+}
+
+/**
+ * Reading, plus writing the extension's **own** declared keys.
+ *
+ * Only an `ActionContext` has one, for the reason every effect is action-tier: a `query` runs
+ * on a keystroke, and a keystroke must not change a preference. The write itself needs no
+ * permission unit — a setting is the extension's own configuration, not a host resource — but
+ * it is not unbounded either: the host accepts only keys the manifest declares, coerces the
+ * value to that key's declared type, and rejects a `select` value that is not one of its
+ * options. An undeclared key is a no-op, not a new setting.
+ *
+ * **There is one value, and Settings owns it.** The same key the Preferences window renders as
+ * a field is the key this writes, so a scope command that changes a preference and the field
+ * that changes it are two ways to move one number — never two numbers that drift. That is the
+ * whole reason this exists: without it an extension that wants both has to keep its own copy in
+ * `storage`, and the copy in Settings becomes a lie.
+ *
+ * Fire-and-forget, like `clipboard.write`: the extension says *what*, the host says *whether* it
+ * is persisted. What happens *inside* the isolate is immediate and local — the value lands in
+ * this isolate's own copy, and every `settings.signal` following the key is written and its
+ * view's `whileVisible` setups re-armed — so a table already on screen changes cadence rather
+ * than finishing the session on the old one. No round trip, no re-boot, nothing torn down.
+ */
+export interface WritableSettings extends SettingsSnapshot {
+  set(key: string, value: JsonValue): void;
+}
+
+
+export interface EnvironmentSnapshot {
+  /** BCP-47 tag, e.g. "en-US". */
+  locale: string;
+  /**
+   * IANA time zone id, e.g. "Asia/Shanghai".
+   *
+   * An environment fact, not a location: it needs no permission, it is not a fix, and
+   * it must not be treated as one. What an extension *does* with it is the extension's
+   * decision — a weather extension can reasonably guess a city from it when location is
+   * denied; a "restaurants near me" extension must not.
+   */
+  timeZone: string;
+  appearance: "light" | "dark";
+  platform: "macos" | "windows" | "linux";
+  /**
+   * **Which of the apps you declared in `integratesWith` are actually installed**, in the order you
+   * declared them.
+   *
+   * It carries no new authority and needs no permission: these are apps the extension *named*, and
+   * the host is already resolving them to run an `inApp` binary, read a container, or check who owns
+   * a custom scheme. What it adds is the ability to ask before doing — which matters whenever an
+   * extension supports more than one version of the same product, because the alternative is
+   * *guessing by trying*: spawn the CLI and see if it fails, read a directory and see if it is
+   * empty. That reports "the tool is missing" to somebody whose actual problem is that they have a
+   * different version.
+   *
+   * Empty when nothing was declared, or when none of it is here.
+   */
+  installedApps: string[];
+}
+
+/**
+ * A colour's canonical `#rrggbb` — its identity, and the only string an extension needs
+ * to make of it: a row title, a `color:` chip, a clipboard write.
+ *
+ * Every *other* way of writing a colour — `rgb()`, `hsl()`, `color(display-p3 …)`, its
+ * nearest name — belongs to the `color` scope, which Tapcue owns. An extension that
+ * produces a colour inherits all of them and implements none of them.
+ *
+ * Wide-gamut components are projected into sRGB and clamped, because a hex string has
+ * no other option. The `Color` itself keeps its space, so nothing is lost downstream.
+ */
+export function colorHex(color: Color): string {
+  const { red, green, blue } = toSrgb(color);
+  const byte = (channel: number) =>
+    Math.min(255, Math.max(0, Math.round(channel * 255)))
+      .toString(16)
+      .padStart(2, "0");
+  return `#${byte(red)}${byte(green)}${byte(blue)}`;
+}
+
+function toSrgb(color: Color): { red: number; green: number; blue: number } {
+  if (color.colorSpace !== "display-p3") return color;
+  const linear = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  const gamma = (c: number) => {
+    const v = Math.min(1, Math.max(0, c));
+    return v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+  };
+  const r = linear(color.red), g = linear(color.green), b = linear(color.blue);
+  // Linear Display-P3 → linear sRGB (CSS Color 4).
+  return {
+    red: gamma(1.2249401762805 * r - 0.2249401762805 * g),
+    green: gamma(-0.0420569547896 * r + 1.0420569547896 * g),
+    blue: gamma(-0.0196375546626 * r - 0.0786360179164 * g + 1.0982735725791 * b),
+  };
+}