@tapcue/extension-sdk 0.1.0

package/src/types.ts

@@ -0,0 +1,614 @@
+/**
+ * Requests, items, and the invocation context — the data shapes that cross the
+ * guest ↔ host boundary on every call.
+ */
+
+import type {
+  BridgeCapability,
+  CacheCapability,
+  ClipboardCapability,
+  ClipboardReadCapability,
+  EnvironmentSnapshot,
+  ExecCapability,
+  FilesCapability,
+  FontsCapability,
+  HttpCapability,
+  InvocationContextCapability,
+  LocationCapability,
+  NativeActionsCapability,
+  QueriesCapability,
+  ReadonlyProcessManager,
+  ScreenCapability,
+  SecretsCapability,
+  SettingsSnapshot,
+  StorageCapability,
+  WritableProcessManager,
+  WritableSettings,
+} from "./capabilities.js";
+import type { ExtensionErrorInit } from "./errors.js";
+import type { PermissionUnit } from "./manifest.js";
+import type { Translate } from "./i18n.js";
+import type { JsonValue } from "./json.js";
+import type { Color } from "./capabilities.js";
+import type { IconRef, Scene, SceneScheme, TableCell } from "./scene.js";
+import type { ViewNode } from "./view.js";
+
+/**
+ * Open, dotted type vocabulary shared with native scopes (`file`, `file.pdf`).
+ * Extension-declared types MUST be namespaced `ext.<extension-id>.<name>` so an
+ * extension cannot squat a native subject type; the host rejects the rest.
+ */
+export type ScopeType = string;
+
+/**
+ * Subject types Tapcue owns. An extension may **produce** an item that enters one of
+ * these — a colour sampled off the screen enters the same colour scope a typed
+ * `#aaeeff` does — but it may never **own** one: `defineScope` requires `ext.<id>.*`,
+ * and the host refuses to load an extension that declares otherwise (§11.1).
+ *
+ * Owning is what gives a subject type one implementation of its formats, its actions,
+ * and its look. Producing is open to anyone, and that is the whole trade: hand Tapcue a
+ * colour and you inherit everything it already knows about colours, for free.
+ */
+export const NATIVE_SCOPE_TYPES = ["color", "application", "file", "file.folder"] as const;
+export type NativeScopeType = (typeof NATIVE_SCOPE_TYPES)[number];
+
+/** The subject shape each native type expects. The host validates against this. */
+export interface NativeSubjects {
+  color: Color;
+  application: ApplicationSubject;
+  file: FileSubject;
+  "file.folder": FileSubject;
+}
+
+/** An installed application, as the `application` scope names it. */
+export interface ApplicationSubject {
+  /** Reverse-domain bundle identifier, e.g. `com.1password.1password`. */
+  bundleId: string;
+  /** The app's localized display name. */
+  name: string;
+}
+
+/** A filesystem item, as the `file` / `file.folder` scopes name it. */
+export interface FileSubject {
+  path: string;
+  /** Last path component, extension included. */
+  name: string;
+  /** Lowercased, no leading dot. `""` for a name that has none. */
+  extension: string;
+  isDirectory: boolean;
+}
+
+/**
+ * **The native scopes an extension may contribute rows *into*** (architecture §11.3).
+ *
+ * A third right, next to owning a scope (`defineScope`, `ext.<id>.*` only) and producing an item
+ * that *enters* one (`CommandItem.scope`): standing inside a scope somebody else owns and adding
+ * rows to it. A 1Password extension belongs in 1Password's app scope; a PDF tool belongs in a
+ * PDF's file scope. Neither owns the scope, and neither is reached through a row it produced —
+ * the user got there on their own.
+ *
+ * Narrower than `NATIVE_SCOPE_TYPES` on purpose. A type is contributable when two things hold:
+ * the host can hand over a **subject** naming what the scope is about, and the scope shows a
+ * **list of rows** there is something to add to. `color` has a subject and no list — it is a
+ * value Tapcue formats, not a place — so it is not here.
+ */
+export const CONTRIBUTABLE_SCOPE_TYPES = ["application", "file", "file.folder"] as const;
+export type ContributableScopeType = (typeof CONTRIBUTABLE_SCOPE_TYPES)[number];
+
+/**
+ * The subject fields a `contributes[].when` predicate may match on, per scope type.
+ *
+ * **String fields only, matched as whole values.** `path` is deliberately absent: matching a path
+ * is a glob problem, and a predicate that could say "anything under /Users" would hand an
+ * extension every file you ever open a scope on. What a contribution may name is a *kind* of
+ * subject (this app, this file extension), never a location.
+ */
+export const CONTRIBUTION_MATCH_FIELDS: Readonly<
+  Record<ContributableScopeType, readonly string[]>
+> = Object.freeze({
+  application: ["bundleId", "name"],
+  file: ["extension", "name"],
+  "file.folder": ["name"],
+});
+
+export function isContributableScopeType(type: string): type is ContributableScopeType {
+  return (CONTRIBUTABLE_SCOPE_TYPES as readonly string[]).includes(type);
+}
+
+export type AliasKind = "keyword" | "name" | "romanized" | "abbreviation" | (string & {});
+
+export interface SearchAlias {
+  value: string;
+  kind: AliasKind;
+}
+
+/**
+ * Scope semantics carried by an item: entering the item opens the scope whose
+ * `type` matches, with `subject` handed back to the scope's handlers.
+ *
+ * The subject is opaque to Tapcue: it is round-tripped verbatim (JSON, size
+ * limited) and never interpreted, ranked, or indexed.
+ */
+export interface ItemScope<S extends JsonValue = JsonValue> {
+  type: ScopeType;
+  subject?: S;
+  /** Chip label for the scope breadcrumb. Defaults to the item title. */
+  displayName?: string;
+  /** Search-field placeholder inside the scope. */
+  placeholder?: string;
+  /**
+   * How the entered scope is laid out — layout, and a `table`'s `columns`/`live`. Stamped by
+   * `defineScope().entry` from the scope's own `scheme`, not set by hand: an extension declares its
+   * scopes in code, so the shell only learns a scope's layout from a row that enters it.
+   */
+  scheme?: SceneScheme;
+  /**
+   * Whether the shell filters the scope's rows locally (`catalog`) or forwards the query to the
+   * scope (`remote`). Stamped by `defineScope().entry` from the scope's own `queryMode`, not set
+   * by hand — declared in code, learned by the shell from the row that enters the scope.
+   */
+  queryMode?: "catalog" | "remote";
+}
+
+export interface CommandItem<S extends JsonValue = JsonValue> {
+  /**
+   * Stable for the same logical entity: used for selection stability, recents,
+   * and reconciliation. The host namespaces it before it enters core state.
+   *
+   * Returning an item whose id equals the command id updates that command's
+   * static manifest row in place instead of adding a second row.
+   */
+  id: string;
+  title: string;
+  subtitle?: string;
+  icon?: IconRef;
+  aliases?: SearchAlias[];
+  /**
+   * Grouping: rows sharing a facet id render as one section (and one chip when
+   * the scheme shows a facet bar). The title travels with the item because facets
+   * are usually dynamic — "Today", "Tomorrow" — and cannot be declared up front.
+   */
+  facet?: { id: string; title: string };
+  /** Omit to make Enter *enter* the item's scope rather than run an action. */
+  defaultActionId?: string;
+  /**
+   * What to call that action in the footer. Supply it whenever you supply `defaultActionId`.
+   *
+   * The shell draws a `⏎` keycap beside exactly one footer action, and that keycap is a promise
+   * about what Return does. With no title for the row's action the shell had to label the keycap
+   * with the *detail pane's* first action instead — so the footer read "Copy File Path ⏎" while
+   * Return copied the family name. Both reference extensions shipped that way before anyone
+   * pressed the key on a real screen.
+   *
+   * Dropped along with the action itself when `requires` was not granted.
+   */
+  defaultActionTitle?: string;
+  /**
+   * The unit `defaultActionId` needs. **Tapcue drops the action if it was not granted.**
+   *
+   * A query cannot check: `clipboard.write` is not on an `ExtensionContext`, because a
+   * keystroke may not change what your next paste produces. But the rule that an action a
+   * capability cannot perform is *not offered* still has to hold, and it should never have
+   * depended on an extension remembering to check. So the row declares what its action needs
+   * and core decides whether to show it — which is core's job, and it is now core's guarantee
+   * rather than the extension's good manners.
+   */
+  requires?: PermissionUnit;
+  /** Provider-local ordering hints only. Tapcue remains the ranking authority. */
+  metadata?: Record<string, string>;
+  /**
+   * A `table` scope row's cells, keyed by column id (`{ pid: "1234", cpu: "5.0%" }`). A `numeric`
+   * column takes `{ value, sort }` so the display text and the sort order can differ. Ignored
+   * outside a `table` layout; the shell reads `title`/`subtitle` for the other row layouts.
+   */
+  cells?: Record<string, TableCell>;
+  scope?: ItemScope<S>;
+}
+
+export interface RequestIdentity {
+  invocationId: string;
+  sessionId: string;
+  /** Bumped when the user types again; results from a stale generation are dropped. */
+  generation: number;
+}
+
+export interface QueryRequest extends RequestIdentity {
+  commandId: string;
+  /**
+   * Search text for the current surface. At root this is the text Tapcue could
+   * not attribute to the command's keyword or arguments.
+   */
+  query: string;
+  /**
+   * Named arguments parsed by Tapcue from the manifest's `arguments` declaration.
+   * Keyword stripping is the core's job — it owns aliases and user renames — so
+   * an extension never parses the raw query itself.
+   */
+  arguments: Readonly<Record<string, string>>;
+  limit: number;
+}
+
+export interface ScopeQueryRequest<S extends JsonValue = JsonValue> extends RequestIdentity {
+  scopeType: ScopeType;
+  /** Host-assigned scope identity (namespaced). Useful for cache keys. */
+  scopeId: string;
+  subject: S;
+  /** Scope-local search text. */
+  query: string;
+  limit: number;
+}
+
+export interface ScopeDetailRequest<S extends JsonValue = JsonValue> extends RequestIdentity {
+  scopeType: ScopeType;
+  scopeId: string;
+  subject: S;
+  /** Guest-facing id of the selected row. */
+  itemId: string;
+}
+
+/** What a `canvas`-layout scope's `surface` handler is asked for: no row, just the subject. */
+export interface ScopeSurfaceRequest<S extends JsonValue = JsonValue> extends RequestIdentity {
+  scopeType: ScopeType;
+  scopeId: string;
+  subject: S;
+}
+
+export interface InvokeRequest<S extends JsonValue = JsonValue> extends RequestIdentity {
+  commandId: string;
+  actionId: string;
+  itemId?: string;
+  /** Present when the action was invoked on a row inside one of the extension's scopes. */
+  scopeType?: ScopeType;
+  subject?: S;
+  payload?: Uint8Array;
+}
+
+export interface ActionResult {
+  status: "completed" | "failed";
+  /** A hint. Tapcue decides what actually happens to the panel. */
+  presentation?: "dismiss" | "keep-open" | "refresh";
+  /** Short, user-safe confirmation ("Copied forecast"). */
+  message?: string;
+  error?: ExtensionErrorInit;
+}
+
+/**
+ * **What an extension can always reach.**
+ *
+ * Handed to `query`, `detail`, and a scope's `items` — everything Tapcue calls to *find out
+ * something*. It can read the world and it can read its own state, and that is the whole of
+ * it: nothing on this context changes anything outside the extension.
+ *
+ * That is not a style rule. These handlers run **on a keystroke**: Tapcue calls `query` while
+ * a person is typing, possibly for every installed extension. A capability that acts on the
+ * user's machine — covering the screen, writing the clipboard, opening a URL — must not be
+ * reachable from a keystroke, so it is not on this type at all.
+ *
+ * Capabilities are present only when granted, so `ctx.http?` narrowing is how an extension
+ * detects a denied permission before calling. `settings` and `environment` are always there:
+ * they are the extension's own configuration, not privileged host resources.
+ */
+/**
+ * Reading this extension's own recents. Scoped to what *this* extension recorded — never
+ * what the user ran anywhere else. A read, so it sits on every context.
+ */
+export interface RecentsReadCapability {
+  /** This extension's recents, freshest first. */
+  list?(): Promise<CommandItem[]>;
+}
+
+/**
+ * Reading, plus the effects: `record` files a produced item, `remove` drops one. Effects,
+ * so only an `ActionContext` has them. A recorded item is honoured as a scope-entry — the
+ * host stamps the extension's own identity and drops any action.
+ */
+export interface RecentsCapability extends RecentsReadCapability {
+  record?(item: CommandItem): Promise<void>;
+  /** Drop a recent by the id it was recorded with. */
+  remove?(id: string): Promise<void>;
+}
+
+export interface ExtensionContext {
+  /** Aborts on cancellation, stale generation, revocation, and deadline. */
+  signal: AbortSignal;
+  /** Remaining wall-clock budget in milliseconds. */
+  deadlineMs: number;
+  settings: SettingsSnapshot;
+  environment: EnvironmentSnapshot;
+  /** Message-catalog lookup for the user's locale; see `i18n.ts`. */
+  t: Translate;
+  http?: HttpCapability;
+  storage?: StorageCapability;
+  cache?: CacheCapability;
+  secrets?: SecretsCapability;
+  /**
+   * **The situation that summoned Tapcue** — the frontmost app, the selection, the
+   * highlighted files. Invocation-scoped facts, and only those.
+   */
+  context?: InvocationContextCapability;
+  /**
+   * **Machine-wide queries.** Facts about the machine rather than about this invocation:
+   * true whether or not anyone opened the launcher, and queryable at any time. They are
+   * deliberately *not* folded into `context` — "what did you have selected" and "what fonts
+   * do you own" are different questions, ask for different consent, and revoke separately.
+   */
+  fonts?: FontsCapability;
+  location?: LocationCapability;
+  /**
+   * **The places the manifest declared it may read** (spec 016 §2). A read, so it is here rather
+   * than on `ActionContext`: an extension whose rows come from a file needs them on a keystroke.
+   */
+  files?: FilesCapability;
+  /**
+   * **The binaries the manifest declared it may run** (spec 016 §3). Also a read-tier capability,
+   * for the same reason — a `query` that lists a vault has to run something — with the costs paid
+   * in concurrency, deadline and output caps rather than by moving it to an action.
+   */
+  exec?: ExecCapability;
+  /**
+   * **The statements the manifest declared it may run** against a tool's own database. `exec`'s
+   * shape with rows instead of stdout, and read-tier for the same reason.
+   */
+  queries?: QueriesCapability;
+  /**
+   * **Read the running processes** — a machine fact, like `fonts`. The effect half — killing a
+   * process, bringing one to the front — is a `WritableProcessManager` on `ActionContext`,
+   * because a keystroke may ask what is running but must never act on it. `process.list`; argv
+   * (`ProcessInfo.command`) needs the separate `process.command` unit.
+   */
+  process?: ReadonlyProcessManager;
+  /** Reading only. The write is an effect, and effects are on `ActionContext`. */
+  clipboard?: ClipboardReadCapability;
+  /** Reading this extension's own recents. Recording/removing are on `ActionContext`. */
+  recents?: RecentsReadCapability;
+}
+
+/**
+ * **What an extension gets when Tapcue calls it to *do* something.**
+ *
+ * Handed to a command's `invoke` and a scope's `invoke` — and to nothing else. A person
+ * reached for a row and pressed Enter; that is the moment, and the only moment, at which an
+ * extension may act on the machine it is running inside.
+ *
+ * Everything on `ExtensionContext`, plus the three groups that leave a mark:
+ *
+ * - `screen` — cover the display (§9.4)
+ * - `clipboard.write` — change what the next paste produces
+ * - `native` — open a URL, reveal a file, post a notification
+ *
+ * The split used to be a runtime check ("interactive capabilities are actions-only"). It is a
+ * type now, which is strictly better: an extension that reaches for the screen from a `query`
+ * no longer discovers it in production — it fails to compile.
+ */
+/**
+ * **Go somewhere in Tapcue** — the one navigation an action can perform.
+ *
+ * A row that enters a scope has always been able to say so: `scope.entry(...)` stamps the row,
+ * and pressing Return on it pushes the scope. That covers everything reachable by *picking a
+ * row*, and nothing else — which left an action with no way to lead anywhere. An action that
+ * has produced something worth a screen of its own ("why is this process running") had to
+ * either fold the answer into the pane it was fired from or throw it away.
+ *
+ * So this takes the same currency: **an item produced by `scope.entry(...)`**, not a scope type
+ * and a bag of options. There is one description of "what it means to enter a scope" and both
+ * paths use it — the host materializes the item through the same mapper a row goes through, so
+ * a scope reached from an action and the same scope reached from a row are the same scope, with
+ * the same subject, scheme, and placeholder.
+ *
+ * **Needs no permission, and cannot be one.** Entering a scope the extension itself declared is
+ * movement inside the extension's own surface — it opens nothing, reads nothing, and leaves no
+ * mark; the host refuses an item that enters anything outside this extension's namespace. It is
+ * still action-tier, for the reason every effect is: a `query` runs while a person types, and
+ * typing must never navigate.
+ *
+ * Fire-and-forget. The host pushes the scope after the action settles, so an action that
+ * navigates and then returns a failure navigates nowhere.
+ */
+export interface NavigationCapability {
+  /** Enter the scope this item enters. Must be an item from `scope.entry(...)`. */
+  enter(item: CommandItem): void;
+}
+
+export interface ActionContext extends ExtensionContext {
+  /** Reading *and* writing. */
+  clipboard?: ClipboardCapability;
+  /**
+   * File a produced item into Tapcue's unified Recents. An effect, so `ActionContext`
+   * only. The item is honoured as a scope-entry: the host stamps it with the extension's
+   * own identity and drops any action, so a recorded recent can never forge an execution.
+   */
+  recents?: RecentsCapability;
+  /**
+   * Reading *and* the effects — `kill` (host-confirmed) and `activate`. Widens the
+   * `ReadonlyProcessManager` a query gets. Present only with `process.kill`, and only here:
+   * a keystroke must never be able to end a process.
+   */
+  process?: WritableProcessManager;
+  native?: NativeActionsCapability;
+  /** An overlay, its pointer events, and — separately granted — its pixels. */
+  screen?: ScreenCapability;
+  /**
+   * The message bridge to a live `WebViewScene` surface, when one this extension declared is
+   * up. `ui.webview`. Present only in an action, and only while the surface exists — the
+   * isolate that presented it may be long evicted, so the bridge reconnects to the
+   * shell-owned surface rather than being held across the call.
+   */
+  bridge?: BridgeCapability;
+  /**
+   * Reading *and* writing the extension's own declared settings. Widens the read-only snapshot
+   * every context gets; see `WritableSettings` for why the write is action-tier and why there
+   * is exactly one value behind it and the Preferences field.
+   */
+  settings: WritableSettings;
+  /** Enter a scope this extension declared. Ambient — see `NavigationCapability`. */
+  navigate?: NavigationCapability;
+}
+
+/**
+ * One batch of rows, and what it means for the rows already shown.
+ *
+ * A bare array **adds**: Tapcue upserts by item id and keeps everything shown so far, which is
+ * what progressive loading wants — yield the cheap rows first (cached, local, already known) and
+ * the expensive ones as they land.
+ *
+ * `{ replace }` **states the whole set as of now**, so ids missing from it are removed. Anything
+ * re-reading a world that changes needs this: upserting alone can say a row appeared or changed
+ * but never that it is gone, so a process that exits would keep its row forever.
+ *
+ * A generator may use both — page in what it has, then settle into refreshing.
+ */
+export type QueryBatch<S extends JsonValue = JsonValue> =
+  | CommandItem<S>[]
+  | { replace: CommandItem<S>[] };
+
+/**
+ * Everything at once, or a stream.
+ *
+ * An async iterable (an `async function*` is the natural way) may keep yielding for as long as
+ * the scope is shown: **the generator's own scope is the lifetime.** It is aborted when the scope
+ * stops being shown, at which point its `finally` runs — so a refresh loop needs no lifecycle
+ * hook and no flag, and `await sleep(n)` is only the most obvious trigger. A file watcher, a
+ * download's progress, or a socket message all work the same way, and none of them are
+ * expressible as a poll interval. A generator that yields once has simply finished.
+ *
+ * Batches from a superseded generation are dropped, so a stale stream can never overwrite fresh
+ * results.
+ */
+export type QueryResult<S extends JsonValue = JsonValue> =
+  | CommandItem<S>[]
+  | AsyncIterable<QueryBatch<S>>;
+
+export interface CommandHandlers<S extends JsonValue = JsonValue> {
+  query?(request: QueryRequest, ctx: ExtensionContext): QueryResult<S> | Promise<QueryResult<S>>;
+  /** The only handler that may act on the machine. See `ActionContext`. */
+  invoke?(request: InvokeRequest<S>, ctx: ActionContext): ActionResult | Promise<ActionResult>;
+  detail?(itemId: string, ctx: ExtensionContext): Scene | null | Promise<Scene | null>;
+  /**
+   * An interactive, data-bound view (docs/architecture/extension-ui-interactive.md). Builds a
+   * tree of `signal` bindings and declared `action`s; the shell drives the reactive loop. A
+   * synchronous, pure builder — the view body runs at query tier, only its actions may act.
+   */
+  view?(request: QueryRequest, ctx: ExtensionContext): ViewNode | Promise<ViewNode>;
+}
+
+export interface ScopeHandlers<S extends JsonValue = JsonValue> {
+  /**
+   * Rows of the scope. Same contract as a command's `query`. Required for every row layout
+   * (`list` / `grid` / `twoColumn`); a `canvas` scope has no rows and provides `surface`
+   * instead. The host rejects a scope that has neither, or one that has `items` under a
+   * `canvas` layout, or `surface` under a row layout — a handler the shell will never call
+   * is a handler an author will believe in.
+   */
+  items?(request: ScopeQueryRequest<S>, ctx: ExtensionContext): QueryResult | Promise<QueryResult>;
+  /**
+   * The body of a `canvas`-layout scope: a `WebViewScene` (or a `LoadingScene`/`ErrorScene`
+   * while it is coming up or if it cannot). Runs on entry, in the read phase — presenting a
+   * surface describes UI, it does not act. Talking to the surface once it is up is an action,
+   * over `ctx.bridge` (§12.1).
+   */
+  surface?(request: ScopeSurfaceRequest<S>, ctx: ExtensionContext): Scene | Promise<Scene>;
+  /** The detail pane of a `twoColumn` scope. */
+  detail?(request: ScopeDetailRequest<S>, ctx: ExtensionContext): Scene | null | Promise<Scene | null>;
+  /** Actions invoked on the scope's own rows — or on a `canvas` scope's footer. See `ActionContext`. */
+  invoke?(request: InvokeRequest<S>, ctx: ActionContext): ActionResult | Promise<ActionResult>;
+  /**
+   * An interactive, data-bound detail pane (docs/architecture/extension-ui-interactive.md): the
+   * live alternative to the static `detail`. Rooted at `<Detail>`, it builds a tree of `signal`
+   * bindings and declared `action`s over the selected row, and the shell drives the reactive
+   * loop — an `<Action>` toggling a unit or refetching — updating the pane by patch, with no full
+   * re-fetch. A scope provides `view` **or** the static `detail`, not both.
+   */
+  view?(request: ScopeDetailRequest<S>, ctx: ExtensionContext): ViewNode | Promise<ViewNode>;
+}
+
+/**
+ * **What a contribution is asked for** — the rows to add to a scope somebody else owns.
+ *
+ * The subject is Tapcue's, not the extension's: it is projected from the native scope the user
+ * entered and validated against `NativeSubjects` before the extension is called at all. And the
+ * extension only ever sees a subject its manifest's `when` already named, so entering an app it
+ * did not declare tells it nothing — the call is never made.
+ */
+export interface ContributionQueryRequest<
+  T extends ContributableScopeType = ContributableScopeType,
+> extends RequestIdentity {
+  /** The manifest `contributes[].id` whose handler this is. */
+  contributionId: string;
+  scopeType: T;
+  /** Host-assigned scope identity. Useful as a cache key. */
+  scopeId: string;
+  subject: NativeSubjects[T];
+  /**
+   * **What the scope does with the rows you return — and it is not your decision.**
+   *
+   * `queryMode` belongs to the scope, so a contributor inherits whatever its owner chose
+   * (architecture §11.3). `catalog`: `query` arrives empty, return everything, Tapcue filters and
+   * ranks. `remote`: `query` is the text the user typed and your rows are shown as returned,
+   * unfiltered and unranked — so if you do not narrow them, nothing will.
+   *
+   * The one rule that is right in both modes: filter by `request.query`, treating empty as
+   * "everything". Read this field when you want to know whether ordering is worth the work.
+   */
+  queryMode: "catalog" | "remote";
+  /** Scope-local search text. Empty in `catalog` mode. */
+  query: string;
+  limit: number;
+}
+
+export interface ContributionInvokeRequest<
+  T extends ContributableScopeType = ContributableScopeType,
+> extends RequestIdentity {
+  contributionId: string;
+  scopeType: T;
+  scopeId: string;
+  subject: NativeSubjects[T];
+  actionId: string;
+  itemId?: string;
+}
+
+/**
+ * **Handlers for one manifest `contributes[]` entry**, keyed in `defineExtension` by its id.
+ *
+ * The same shape a command has, and for the same reason: a contribution is *declared in the
+ * manifest and implemented in code*. It has to be declared, because the scope is entered by the
+ * user rather than reached through a row the extension produced — so Tapcue must know who to ask
+ * without executing anything, exactly as it knows a command's row without running its `query`.
+ * A scope the extension *owns* is the opposite case and stays in code (`defineScope`).
+ */
+export interface ContributionHandlers<
+  T extends ContributableScopeType = ContributableScopeType,
+> {
+  /**
+   * The rows to add. Required — a contribution with no rows contributes nothing.
+   *
+   * **There is no `detail` here, on purpose.** A scope's detail pane belongs to whoever owns the
+   * scope (`OwnedScope.detail` is one closure, one owner), so no contributor — native or
+   * extension — can supply a pane for its own rows; the native `Terminal Here` rows in a folder's
+   * scope have the same shape. Give a row a `scope` of its own instead and put the detail there:
+   * a screen the extension owns outright beats a pane it would be borrowing. See architecture §23.
+   */
+  items(
+    request: ContributionQueryRequest<T>,
+    ctx: ExtensionContext,
+  ): QueryResult | Promise<QueryResult>;
+  /** Actions on the contributed rows. See `ActionContext`. */
+  invoke?(
+    request: ContributionInvokeRequest<T>,
+    ctx: ActionContext,
+  ): ActionResult | Promise<ActionResult>;
+}
+
+export interface ScopeSpec<S extends JsonValue = JsonValue> extends ScopeHandlers<S> {
+  type: ScopeType;
+  scheme: SceneScheme;
+  /**
+   * `catalog` (the default): return every row and let Tapcue filter and rank them
+   * with the same fuzzy engine it uses everywhere — ignore `request.query`.
+   * `remote`: the backing service needs the query, so Tapcue debounces, passes it
+   * in, and cancels the previous generation.
+   */
+  queryMode?: "catalog" | "remote";
+}
+
+export type { Scene, SceneScheme };