@tapcue/extension-sdk 0.1.0

package/src/reactive.ts

@@ -0,0 +1,374 @@
+/**
+ * The reactive core: signals, actions, and the bounded derivation vocabulary.
+ *
+ * This is Solid-shaped, not React-shaped (docs/architecture/extension-ui-interactive.md §3).
+ * A `view` handler runs start-to-finish to build a tree of bindings into a serializable
+ * model; it does not re-run per keystroke, and there is no hook state living in the isolate.
+ * The shell holds the model; the isolate is handed it back to run an action (§4).
+ *
+ * Signals are keyed positionally (`s0`, `s1`, …) in creation order, and actions likewise
+ * (`a0`, `a1`, …). The order must be stable across runs — create them unconditionally at the
+ * top of `view`, the same discipline React's rules-of-hooks enforce — because an action
+ * dispatch re-runs `view` to rebuild the graph before hydrating it from the handed-back model.
+ */
+
+import type { JsonValue } from "./json.js";
+import type { PermissionUnit } from "./manifest.js";
+import type { ActionContext } from "./types.js";
+import type { Bind, Derivation, PropValue } from "./view.js";
+
+// ── The active build ────────────────────────────────────────────────────────
+
+export interface RegisteredAction {
+  id: string;
+  run: (ctx: ActionContext, args: JsonValue[]) => void | Promise<void>;
+  requires?: PermissionUnit;
+  destructive?: boolean;
+}
+
+/** State shared by everything created during one `view` run. Re-created per run. */
+export class BuildContext {
+  readonly values = new Map<string, JsonValue>();
+  readonly order: string[] = [];
+  readonly actions = new Map<string, RegisteredAction>();
+  /** Setups registered by `whileVisible`, run once the first frame is out. */
+  readonly visibleSetups: VisibleSetup[] = [];
+  /**
+   * Notified with a cell path whenever a signal is written, while the view is being kept alive.
+   * The driver sets it to schedule a patch flush, so a `signal.set()` inside a `whileVisible`
+   * setup propagates on its own. Unset outside that, where an action's before/after diff is what
+   * reconciles a write instead.
+   */
+  onDirty: ((path: string) => void) | null = null;
+  /**
+   * Cells created by `ctx.settings.signal(key)`, keyed by the setting they follow.
+   *
+   * A settings cell is the one kind whose value can be written by something outside the build
+   * that owns it — the *other* build, the one running an action — so it is the one kind that has
+   * to be findable by name rather than by position. Everything else is positional and private.
+   */
+  readonly settingCells = new Map<string, string[]>();
+  private signalCount = 0;
+  private actionCount = 0;
+
+  nextSignalPath(): string {
+    return `s${this.signalCount++}`;
+  }
+  nextActionId(): string {
+    return `a${this.actionCount++}`;
+  }
+}
+
+let currentBuild: BuildContext | null = null;
+
+/**
+ * Run a view builder with `build` active so `signal`/`action` register into it. Async because a
+ * view may `await` its initial data (a forecast, a search) before describing itself — the `await`
+ * keeps `build` active across the suspension, and the isolate serializes calls so there is never a
+ * second build to clash with. Signal reads/writes after the build still work: a `Signal` closes
+ * over its own `BuildContext`, not over the global.
+ */
+export async function runInBuild<T>(build: BuildContext, fn: () => T | Promise<T>): Promise<T> {
+  const previous = currentBuild;
+  currentBuild = build;
+  try {
+    return await fn();
+  } finally {
+    currentBuild = previous;
+  }
+}
+
+function requireBuild(): BuildContext {
+  if (currentBuild === null) {
+    throw new Error(
+      "signal()/action() may only be called inside a view handler — not at module top level",
+    );
+  }
+  return currentBuild;
+}
+
+// ── Signals ─────────────────────────────────────────────────────────────────
+
+export interface Signal<T> {
+  /** Read the current value. Inside JSX it establishes a `$bind`; inside an action it reads. */
+  (): T;
+  /** Write the value. Produces a `set` patch when it changes during an action. */
+  set(next: T): void;
+  readonly path: string;
+  readonly __signal: true;
+}
+
+/**
+ * A serializable state cell. `T` must be JSON-serializable — that is what lets the shell
+ * hold the model and hand it back to a cold isolate (§3). The bound is not written into the
+ * type so authors can use plain interfaces without an index-signature dance; the wire layer
+ * treats every value as JSON.
+ */
+export function signal<T>(initial: T): Signal<T> {
+  const build = requireBuild();
+  const path = build.nextSignalPath();
+  build.values.set(path, initial as unknown as JsonValue);
+  build.order.push(path);
+  const read = (() => build.values.get(path) as unknown as T) as Signal<T>;
+  Object.defineProperty(read, "set", {
+    value: (next: T) => {
+      build.values.set(path, next as unknown as JsonValue);
+      // The write *is* the event while the view is being kept alive: this schedules one patch
+      // flush, so `set` alone propagates and there is no commit. Outside that, `onDirty` is unset
+      // and the action's before/after diff does the reconciling.
+      build.onDirty?.(path);
+    },
+  });
+  Object.defineProperty(read, "path", { value: path });
+  Object.defineProperty(read, "__signal", { value: true });
+  return read;
+}
+
+export function isSignal(value: unknown): value is Signal<unknown> {
+  return typeof value === "function" && (value as { __signal?: true }).__signal === true;
+}
+
+// ── Settings as state ───────────────────────────────────────────────────────
+//
+// A `whileVisible` setup and an action run in **different builds** (view-runtime.ts §driveView /
+// §applyAction) — which is what lets a cold isolate serve an action, and which means an action's
+// ordinary `signal.set()` is invisible to a setup that is still running. For most cells that is
+// exactly right. For a *setting* it is not: a poll interval, a page size, a unit is precisely the
+// kind of value a setup reads and an action changes, and "the running loop keeps the old one until
+// you leave and come back" is not a thing anyone would design on purpose.
+//
+// So a settings cell is registered by name, and a write reaches **every live build** that follows
+// that key. The registry is module-level because the two builds are in one isolate — the same SDK
+// module instance serves both — so this is a lookup, not a channel.
+
+/** A view that is currently being driven, and how to restart what it left running. */
+export interface LiveBuild {
+  readonly build: BuildContext;
+  /** Re-run the `whileVisible` setups, cleaning up the previous pass first. */
+  restartSetups(): Promise<void>;
+}
+
+const liveBuilds = new Set<LiveBuild>();
+
+export function registerLiveBuild(live: LiveBuild): () => void {
+  liveBuilds.add(live);
+  return () => liveBuilds.delete(live);
+}
+
+/**
+ * A signal that follows one of the extension's declared settings.
+ *
+ * Reached as `ctx.settings.signal(key)`. It is an ordinary signal in every other respect — bind it
+ * in the view and the shell re-renders locally, read it in a setup and you get the current value —
+ * with one addition: when anything writes that setting, the cell is written **and the view's
+ * `whileVisible` setups are restarted**.
+ *
+ * Restarting is what makes the value actually *govern* the loop rather than merely describe it. A
+ * `setInterval` already ticking at 5 s does not start ticking at 1 s because a variable changed; it
+ * has to be torn down and re-armed. `whileVisible` setups have always promised to be idempotent and
+ * re-runnable — that is what "each time the view becomes visible" means — so re-running them is
+ * within the contract they already sign, not a new obligation.
+ */
+export function settingSignal<T extends JsonValue>(key: string, initial: T): Signal<T> {
+  const build = requireBuild();
+  const cell = signal<T>(initial);
+  const paths = build.settingCells.get(key) ?? [];
+  paths.push(cell.path);
+  build.settingCells.set(key, paths);
+  return cell;
+}
+
+/**
+ * A setting changed: write it into every live build that follows it, and restart what those
+ * builds left running.
+ *
+ * Called by the host glue after `ctx.settings.set` — so it covers the extension's own write. A
+ * change made *outside* the isolate (the Preferences window) cannot reach here; the host answers
+ * that one by re-booting the isolate with the new snapshot, which restarts everything anyway.
+ */
+export function applySettingChange(key: string, value: JsonValue): void {
+  for (const live of liveBuilds) {
+    const paths = live.build.settingCells.get(key);
+    if (paths === undefined) continue;
+    for (const path of paths) {
+      live.build.values.set(path, value);
+      live.build.onDirty?.(path);
+    }
+    // Re-arm after the write, so a setup that reads the cell on its first tick reads the new one.
+    void live.restartSetups();
+  }
+}
+
+// ── Actions ─────────────────────────────────────────────────────────────────
+
+export interface ActionSpec {
+  readonly $action: string;
+  readonly requires?: PermissionUnit;
+  readonly destructive?: boolean;
+}
+
+/**
+ * Isolate-tier logic. The callback receives an `ActionContext` — the same capability-bearing
+ * context `invoke` gets — because it *is* an invoke: the view body runs at query tier (no
+ * ambient authority), and only firing an action reaches the machine (§6). `requires` gates it
+ * exactly as it gates a row action; `destructive` earns the shell's confirmation.
+ */
+export function action(
+  // The arguments are spread from what the shell dispatched. A pane action fired while a table
+  // row is selected receives that row's id, which is how one action serves every row without
+  // being declared per row. `never[]` used to sit here and made them undeclarable.
+  run: (ctx: ActionContext, ...args: JsonValue[]) => void | Promise<void>,
+  opts?: { requires?: PermissionUnit; destructive?: boolean },
+): ActionSpec {
+  const build = requireBuild();
+  const id = build.nextActionId();
+  build.actions.set(id, {
+    id,
+    run: (ctx, args) => run(ctx, ...args),
+    requires: opts?.requires,
+    destructive: opts?.destructive,
+  });
+  const spec: ActionSpec = { $action: id, requires: opts?.requires, destructive: opts?.destructive };
+  return spec;
+}
+
+export function isActionSpec(value: unknown): value is ActionSpec {
+  return typeof value === "object" && value !== null && "$action" in value;
+}
+
+// ── The visible window (work that outlives one render) ───────────────────────
+
+/**
+ * What a `whileVisible` setup returns to undo itself, if it has anything to undo.
+ */
+export type VisibleCleanup = void | (() => void);
+
+/** A setup, run each time the view becomes visible. */
+export type VisibleSetup = () => VisibleCleanup | Promise<VisibleCleanup>;
+
+/**
+ * Run `setup` each time the view becomes visible, and its returned cleanup when it stops being.
+ *
+ * This is where anything outliving a single render belongs — a timer, a subscription, a watcher:
+ *
+ * ```tsx
+ * whileVisible(() => {
+ *   const id = setInterval(() => rows.set(read()), 1500);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * **It must be a callback, not statements in the view body.** The body re-runs in full on every
+ * action dispatch — that is how a cold isolate rebuilds the signal graph before hydrating it — so
+ * a bare `setInterval` in the body would start a second timer on the first click and leak one per
+ * dispatch. A setup is exempt from that re-run: it fires once per visible period, however many
+ * actions happen inside it.
+ *
+ * Named for a duration rather than an event because that is what it is, and deliberately not
+ * `onMount`: that name promises once per lifetime, and this runs again on every reopen — which is
+ * also why **the setup has to be idempotent**. Starting a timer is; incrementing a counter is not.
+ *
+ * The setup runs at the same tier as the view body: it may read, not act. To act it fires an
+ * `action`, exactly as a button would.
+ */
+export function whileVisible(setup: VisibleSetup): void {
+  requireBuild().visibleSetups.push(setup);
+}
+
+// ── Derivations (the closed binding vocabulary the shell can evaluate) ────────
+
+export interface Derived {
+  readonly $derive: Derivation;
+}
+export type Bindable<T> = T | Signal<T> | Derived;
+
+export function not(of: Bindable<unknown>): Derived {
+  return { $derive: { op: "not", of: toWire(of) } };
+}
+export function isEmpty(of: Bindable<unknown>): Derived {
+  return { $derive: { op: "isEmpty", of: toWire(of) } };
+}
+export function notEmpty(of: Bindable<unknown>): Derived {
+  return { $derive: { op: "notEmpty", of: toWire(of) } };
+}
+export function format(of: Bindable<number>, as: "number" | "percent" | "date"): Derived {
+  return { $derive: { op: "format", of: toWire(of), as } };
+}
+
+/**
+ * Look `of` up in a table built when the view was described. The bar for a binding transform is
+ * higher than for a component (extension-ui-interactive §12): it must be pure, total, and recur
+ * across extensions rather than serve one. A lookup qualifies on all three — a translator naming
+ * the selected language's script, a unit converter naming the selected unit's symbol, and a font
+ * preview naming the selected family's classification are the same operation.
+ *
+ * If it needs to *think*, it is still an action. This only indexes.
+ */
+export function lookup<T>(of: Bindable<string>, table: Record<string, T>): Derived {
+  return { $derive: { op: "lookup", of: toWire(of), in: toWire(table) } } as Derived;
+}
+
+export function isDerived(value: unknown): value is Derived {
+  return typeof value === "object" && value !== null && "$derive" in value;
+}
+
+// ── `<For>` item scope ────────────────────────────────────────────────────────
+
+/** Symbol-keyed so it can never collide with a real model field name. */
+const ITEM = Symbol("tapcue.item");
+
+function itemBind(path: string): unknown {
+  return { [ITEM]: path };
+}
+
+function itemMarker(value: unknown): string | null {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return null;
+  const marker = (value as Record<symbol, unknown>)[ITEM];
+  return typeof marker === "string" ? marker : null;
+}
+
+/**
+ * A proxy standing in for one `<For>` element at build time. Used whole, it binds the element
+ * itself (`@item`, for a `string[]`); a field access binds that field (`@item.<field>`, for an
+ * object list). The shell resolves these per element — so a list renders and grows without
+ * waking the isolate. You may pass item fields straight into props; you may not compute on them
+ * (the shell cannot run extension code), which is why per-item formatting is a `format`
+ * derivation, not `item.value.toFixed(1)`.
+ */
+export function itemProxy<T>(base = "@item"): T {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === ITEM) return base;
+        if (typeof prop !== "string") return undefined;
+        return itemBind(`${base}.${prop}`);
+      },
+    },
+  ) as T;
+}
+
+/** The `@index` marker handed to a `<For>` callback's second parameter. */
+export const itemIndex: number = itemBind("@index") as number;
+
+// ── The compiler: author value → wire `PropValue` ─────────────────────────────
+
+export function toWire(value: unknown): PropValue {
+  if (value === null || value === undefined) return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "number" || kind === "boolean") return value as PropValue;
+  const marker = itemMarker(value);
+  if (marker !== null) return { $bind: marker } satisfies Bind;
+  if (isSignal(value)) return { $bind: value.path } satisfies Bind;
+  if (isDerived(value)) return { $derive: value.$derive };
+  if (isActionSpec(value)) return { $action: value.$action };
+  if (Array.isArray(value)) return value.map(toWire);
+  if (kind === "object") {
+    const out: Record<string, PropValue> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = toWire(entry);
+    }
+    return out;
+  }
+  return null;
+}

package/src/scene.ts

@@ -0,0 +1,297 @@
+/**
+ * The declarative UI vocabulary. Extensions describe scenes; the native shell
+ * renders them. No HTML, CSS, or platform layout code crosses this boundary.
+ *
+ * See docs/architecture/extension-ui.md for the rendering contract, the
+ * sanitization rules, and what the shell owns.
+ */
+
+import type { PermissionUnit } from "./manifest.js";
+
+/**
+ * Icon reference grammar. The shell resolves it; an unresolvable reference
+ * degrades to the extension's own icon rather than failing the scene.
+ *
+ * - `asset:<path>`   — a file inside the installed package (`asset:icons/rain.svg`)
+ * - `symbol:<name>`  — a Tapcue semantic symbol, mapped per platform
+ * - `color:<hex>`    — a solid colour chip, `color:#RRGGBB`
+ * - `font:<family>`  — a specimen tile drawn in that family, `font:Helvetica Neue`
+ * - `process:<pid>`  — the running process's app icon, resolved by the shell from the pid
+ * - `favicon:<host>` — the site's own icon, fetched and cached by the shell (`favicon:github.com`)
+ * - `extension`      — the extension's own icon
+ *
+ * `process:` is the icon sibling of `font:` and `color:`: the *shell* owns the pixels. An extension
+ * that lists processes has their pids but no way — and no permission — to read an app's icon off
+ * disk; it names the process (`process:1234`), and the shell resolves the running app's icon itself
+ * (`NSRunningApplication`), degrading to a generic executable glyph for a daemon that is not an app.
+ * No icon bytes ever cross into the extension.
+ *
+ * `favicon:` is the same bargain one step further out: a row whose *subject is a website* — a saved
+ * login, a bookmark — has no packaged asset that could stand for it, and a list where every row
+ * wears the extension's own glyph is a column of identical marks where picking the right one is
+ * reading rather than seeing. The extension names the host; the shell fetches, caches, and draws.
+ * **It is not `imageURL` with a nicer name**: an image URL is a download on the drawing path, while
+ * a favicon is resolved off it, which is what makes a hundred of them affordable. Until it lands —
+ * and forever, for a site that publishes none — the row wears the extension's own icon, so nothing
+ * ever paints as a blank. No icon bytes cross into the extension, and no permission is involved:
+ * the extension names a host it already knows, and never learns whether the fetch succeeded.
+ *
+ * `font:` is the colour chip's sibling and exists for the same reason: a row whose *subject is a
+ * typeface* has no other way to show it — the family is known only at runtime, so no packaged
+ * asset can carry it, and the shell is the only thing that can draw it. **The shell picks the
+ * sample glyph**, not the extension: a Latin face gets "Ag", a Japanese one "あ", chosen from what
+ * the family actually supports and the user's locale. An unresolvable family degrades to the
+ * extension's own icon, exactly as an unresolvable `asset:` does.
+ */
+export type IconRef =
+  | `asset:${string}`
+  | `symbol:${string}`
+  | `color:${string}`
+  | `font:${string}`
+  | `process:${string}`
+  | `favicon:${string}`
+  | "extension";
+
+/** `#RRGGBB`, the one colour literal the vocabulary accepts. */
+export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * How a scope's body is laid out. The shell owns everything else.
+ *
+ * `list` / `grid` / `twoColumn` / `table` are row layouts: the scope's `items` produce rows and the
+ * shell searches, ranks, and renders them.
+ *
+ * - **`table`** is a multi-column grid — a process list, a downloads table. Each column is declared
+ *   in `columns`, and a row fills a cell with `cell(id, value)` (a numeric column also takes a sort
+ *   value so `"9 MB"` sorts below `"10 MB"`). The shell draws the header, the sorting, and the row
+ *   icon; the extension supplies only text. Rows that move come from an `items` generator that
+ *   keeps yielding — nothing about a table declares that, because "these rows change" is a fact
+ *   about the rows and not about the layout drawing them.
+ *
+ * `pane` and `canvas` both have **no rows**, and the difference between them is the whole point.
+ *
+ * - **`pane`** is a single *semantic* pane: the scope's `view` (or `detail`) handler fills the
+ *   panel body, and the shell draws it from the same vocabulary a two-column detail uses. It
+ *   exists for the class of small tools that take an input, a choice, and show a result — a
+ *   translator (text, language, translation), a text transform, a hash, a unit conversion, a font
+ *   specimen. None of them have a list, and before this they had to invent one: a row column with
+ *   nothing meaningful in it, or the WebView. Two independent cases (`fonts`' preview and a
+ *   translator) is what carried it over extension-ui §9's bar; one would not have.
+ * - **`canvas`** renders the extension's own HTML in a WebView (architecture §12.1) because the
+ *   semantic vocabulary genuinely cannot reach it — freehand ink is the canonical case. It costs a
+ *   higher trust tier. Reach for `pane` first; `canvas` is for what `pane` cannot describe.
+ *
+ * A scope declares exactly one source for its body: `items` for a row layout, `surface` for
+ * `canvas`, `view`/`detail` for `pane`. The host rejects the mismatches — a handler the shell will
+ * never call is a handler an author will believe in.
+ */
+export interface SceneScheme {
+  layout: "list" | "grid" | "twoColumn" | "table" | "canvas" | "pane";
+  /** Show the facet chip row (filter chips built from row `facetId`s). Row layouts only. */
+  facetBar?: boolean;
+  /**
+   * Which of the shell's two row shapes a `list` / `twoColumn` scope draws (default `"inline"`).
+   *
+   * - **`"inline"`** — one line: the subtitle continues the title on the same line. Right when the
+   *   subtitle is a short qualifier of the row's name, which is most rows.
+   * - **`"twoLine"`** — the title on its own line with the subtitle beneath it in smaller type, and
+   *   a larger icon. Right when the subtitle is *metadata about the subject* rather than more of
+   *   its name — "10 styles · Menlo.ttc · OpenType (TrueType)" is a description of a font, and
+   *   inline it reads as an over-long name and truncates before it says anything.
+   *
+   * This is a **closed choice from the shell's own vocabulary**, the same kind `layout` is, and it
+   * is the only thing about a row an extension picks: the fonts, the metrics, the truncation, and
+   * the spacing stay the shell's, and it is what makes an extension's two-line rows identical to
+   * the ones Clipboard and Files draw. There is no way to set a size, a colour, or a third shape.
+   */
+  rowLayout?: "inline" | "twoLine";
+  /** For `twoColumn`: stay single-column until a row actually resolves a detail. */
+  collapsesDetailPaneUntilAvailable?: boolean;
+  /** Required for `layout: "table"`: the ordered columns. Ignored by other layouts. */
+  columns?: TableColumn[];
+  /** For `layout: "table"`: the column id to sort by on entry (default: the first). */
+  defaultSortColumn?: string;
+  /** For `layout: "table"`: sort descending on entry (default ascending). */
+  defaultSortDescending?: boolean;
+  /**
+   * For `layout: "table"`: moving the pointer over a row makes it the selection (default `true`,
+   * matching every other row layout). Set `false` when the rows re-sort while the cursor sits
+   * still — a refreshing process table slides new rows under the pointer, and hover selection would
+   * make the highlight twitch through them on its own. With it off only a click selects, so the
+   * highlight moves only when the user moves it.
+   */
+  hoverSelects?: boolean;
+}
+
+/**
+ * A `table` row's value for one column: a display string, or — for a `numeric` column — a string
+ * plus the number the shell sorts by, so `{ value: "9 MB", sort: 9_000_000 }` sorts below `"10 MB"`.
+ */
+export type TableCell = string | { value: string; sort?: number };
+
+/** A column of a `table` scope. The shell renders the header and sorting; the row fills the cell. */
+export interface TableColumn {
+  /** Stable id. A row fills this column with `cell(id, value)`; the header sorts by it. */
+  id: string;
+  /** Header text. */
+  title: string;
+  /** Fixed width in points. The one column with no `width` stretches to fill. */
+  width?: number;
+  minWidth?: number;
+  /** Cell text alignment. Numbers usually want `"trailing"`. */
+  align?: "leading" | "trailing" | "center";
+  /** Clicking the header sorts by this column. Defaults to `true`. */
+  sortable?: boolean;
+  /** Sort by the row's numeric side-value for this column (`cell`'s second arg), not the text — so
+   *  `"9 MB"` sorts below `"10 MB"`. */
+  numeric?: boolean;
+  /** The leading column that carries the row's icon. At most one column should set this. */
+  showsIcon?: boolean;
+}
+
+export interface MetadataRow {
+  label: string;
+  value: string;
+  icon?: IconRef;
+}
+
+export interface MetadataSection {
+  title?: string;
+  rows: MetadataRow[];
+}
+
+/**
+ * A typed chart. Series in one chart share one axis and one unit — put values
+ * with different units in separate charts rather than asking for a second axis.
+ */
+export interface Chart {
+  type: "line" | "bar" | "area";
+  /** Categorical x labels, one per value index. */
+  labels: string[];
+  series: ChartSeries[];
+  /** Unit suffix shown by the shell on the value axis, e.g. "°C", "%". */
+  unit?: string;
+  /** Optional fixed value range; omit to let the shell fit the data. */
+  min?: number;
+  max?: number;
+  /** Highlighted x positions, e.g. "now" or the selected hour. */
+  markers?: ChartMarker[];
+}
+
+export interface ChartSeries {
+  id: string;
+  name?: string;
+  /** One value per `labels` entry; `null` renders a gap. */
+  values: (number | null)[];
+}
+
+export interface ChartMarker {
+  /** Index into `labels`. */
+  at: number;
+  label?: string;
+}
+
+export type SceneBlock =
+  | { kind: "markdown"; text: string }
+  | { kind: "chart"; chart: Chart }
+  | { kind: "metadata"; sections: MetadataSection[] };
+
+export interface SceneAction {
+  actionId: string;
+  title: string;
+  icon?: IconRef;
+  /** The unit this action needs. Tapcue drops it if that was not granted — see `CommandItem`. */
+  requires?: PermissionUnit;
+  /** The shell requires confirmation before running a destructive action. */
+  destructive?: boolean;
+}
+
+/** The detail pane of a `twoColumn` scope, or a command's detail scene. */
+export interface DetailScene {
+  kind: "detail";
+  title?: string;
+  subtitle?: string;
+  /** Large leading icon for the pane header. */
+  icon?: IconRef;
+  /** Ordered content blocks rendered top to bottom. */
+  body?: SceneBlock[];
+  actions?: SceneAction[];
+}
+
+/**
+ * A WebView surface — the one place an extension renders instead of describes.
+ *
+ * The rest of this file is the semantic vocabulary: an extension says "a chart with this
+ * data", never "a rectangle here", and the shell owns type, colour, and layout across three
+ * platforms (extension-ui §1). A `WebViewScene` is the deliberate exception (architecture
+ * §12.1) — for the long tail the vocabulary cannot reach, of which a drawing canvas is the
+ * canonical case. It runs the extension's own HTML/JS from `entry`, so it costs a higher
+ * trust tier (`ui.webview`) and it is the only scene the shell does not draw itself.
+ *
+ * What the shell still owns, and the extension cannot touch: the surrounding chrome — the
+ * titlebar above and the footer below are native, drawn from `title` and `actions` — the
+ * identity badge, and every permission dialog, none of which the WebView can cover. The
+ * surface has no network of its own (`connect-src 'none'`); everything it does that leaves
+ * the sandbox flows back through the extension isolate over `ctx.bridge` (capabilities.ts).
+ */
+export interface WebViewScene {
+  kind: "webview";
+  /**
+   * A package asset, resolved and loaded through the host's custom scheme handler — the
+   * same package-relative, non-traversing grammar as an `asset:` icon, without the prefix.
+   * Remote URLs never load: the surface's only inputs are package bytes and bridge messages.
+   */
+  entry: string;
+  /**
+   * The native titlebar text, shown only under `titlebar: "shell"`. The shell renders it; the
+   * WebView cannot draw over it. A `"none"` titlebar has nowhere to put it, so it is ignored.
+   */
+  title?: string;
+  /**
+   * How the shell frames the surface above it. The footer below and the scope's identity are
+   * the shell's either way; this is only about the bar between the panel's top and the canvas.
+   *
+   * - `"shell"` (default) — the shell's own titlebar (the search field, with the scope pill and
+   *   the ⋯ menu) sits above the surface, exactly as on a row scope. The canvas fills the body
+   *   below it.
+   * - `"none"` — no titlebar. The canvas runs from the panel's top edge down to the footer, and
+   *   the scope pill (left) and the ⋯ menu (right) float over its top corners instead of riding
+   *   a bar. For a surface that *is* the whole UI — a blank drawing sheet — a titlebar is a strip
+   *   of chrome with nothing to say; this reclaims it while keeping the two controls that must
+   *   never be the extension's (leaving the scope, and the menu) native and uncoverable.
+   *
+   * It is the panel-surface analogue of an overlay's `frame` (architecture §9.4): frameless buys
+   * a clean surface, never anonymity — the scope pill and menu stay, and the WebView cannot cover
+   * them.
+   */
+  titlebar?: "shell" | "none";
+  /**
+   * The native footer, in priority order. The shell binds the first action to Enter, a
+   * second to ⌘Enter, and the rest to the ⌘K panel — because keyboard shortcuts are the
+   * shell's to own (extension-ui §1), the extension orders the actions and never names a key.
+   * An action whose `requires` unit was not granted is dropped, exactly as on a row.
+   */
+  actions?: SceneAction[];
+}
+
+export interface LoadingScene {
+  kind: "loading";
+  title?: string;
+}
+
+export interface EmptyScene {
+  kind: "empty";
+  title: string;
+  description?: string;
+  icon?: IconRef;
+}
+
+export interface ErrorScene {
+  kind: "error";
+  title: string;
+  description?: string;
+  /** Recovery affordance, e.g. "Grant location access". */
+  actions?: SceneAction[];
+}
+
+export type Scene = DetailScene | WebViewScene | LoadingScene | EmptyScene | ErrorScene;