@tapcue/extension-sdk 0.1.0

package/src/components.ts

@@ -0,0 +1,277 @@
+/**
+ * The closed component vocabulary, as JSX components (docs/architecture/extension-ui-interactive.md §5).
+ *
+ * Each component is an inert tag: the JSX factory reads its `__tag` and builds a `ViewNode`;
+ * the function body is never run (except that `<For>`'s child render function and `<Show>`'s
+ * structure are read by the factory). You cannot emit a lowercase intrinsic (`<div>`) — the
+ * `JSX.IntrinsicElements` set is empty on purpose. The shell renders these natively; an
+ * unknown tag is dropped, never guessed at.
+ */
+
+import type { JsonValue } from "./json.js";
+import type { PermissionUnit } from "./manifest.js";
+import type { ActionSpec, Bindable, Signal } from "./reactive.js";
+import type { Chart, IconRef } from "./scene.js";
+import type { CommandItem } from "./types.js";
+import type { ViewNode } from "./view.js";
+
+type Node = ViewNode;
+type Children = Node | Node[] | boolean | null | undefined;
+type Str = Bindable<string>;
+
+interface Tag<P> {
+  (props: P): ViewNode;
+  readonly __tag: string;
+}
+
+function tag<P>(type: string): Tag<P> {
+  const component = ((_props: P) => undefined as unknown as ViewNode) as Tag<P> & { __tag: string };
+  component.__tag = type;
+  return component as Tag<P>;
+}
+
+// ── Surfaces ──────────────────────────────────────────────────────────────────
+
+// The interactive row-scope roots — `<List>` / `<Grid>` / `<TwoColumn>` and their `.Item` /
+// `.Section` — are planned but **not shipped**: the shell renders a `<Detail>` pane, not an
+// interactive row list (extension-ui-interactive.md §5). They return with the shell rendering that
+// draws them and the first extension that needs them, per the grow-on-evidence discipline — a tag
+// the shell would silently drop is the "believe in a handler the shell never calls" trap.
+
+export interface DetailProps {
+  title?: Str;
+  subtitle?: Str;
+  icon?: Bindable<IconRef>;
+  children?: Children;
+}
+export const Detail = tag<DetailProps>("detail");
+
+// ── Content blocks ────────────────────────────────────────────────────────────
+
+export interface MarkdownProps {
+  text: Str;
+}
+export const Markdown = tag<MarkdownProps>("markdown");
+
+export interface ChartProps {
+  chart: Chart;
+}
+export const ChartView = tag<ChartProps>("chart");
+
+export interface MetadataRowProps {
+  label: Str;
+  value: Str;
+  icon?: Bindable<IconRef>;
+}
+export interface MetadataSectionProps {
+  title?: Str;
+  children?: Children;
+}
+export const Metadata = Object.assign(tag<{ children?: Children }>("metadata"), {
+  Section: tag<MetadataSectionProps>("metadata.section"),
+  Row: tag<MetadataRowProps>("metadata.row"),
+});
+
+// ── Inputs ────────────────────────────────────────────────────────────────────
+//
+// These are the first two input widgets, and they ship on evidence: the `fonts` extension needs
+// exactly them — a text field to type a specimen into, and a picker to choose the family. The
+// wider form vocabulary (`TextField`, `Checkbox`, `DatePicker`, `TagPicker`) still waits for an
+// extension that needs it.
+//
+// **Two-way binding costs no IPC.** Bind a `signal` to `value` and the *shell* writes the user's
+// edits straight back into its own copy of the model — the isolate is not woken per keystroke, and
+// is very likely evicted while the user types. That is what makes a live preview affordable: the
+// text and the chosen family are both model cells the shell already holds, so re-rendering as you
+// type is a local operation. An `onChange` action exists for when the extension genuinely needs to
+// *react* (persist a choice, refetch); binding alone needs no action at all.
+
+export interface TextAreaProps {
+  /** Bind a `signal` for two-way editing; a plain string renders read-only text. */
+  value: Bindable<string>;
+  placeholder?: Str;
+  /** Visible lines. The shell owns the real metrics, this is a hint. */
+  rows?: number;
+  /**
+   * **Render the text in this font family** — the one place the contract lets an extension
+   * influence typography, and a deliberate, narrow exception to "the shell owns type"
+   * (extension-ui §1).
+   *
+   * It is content, not styling, in the same sense `color:` is: the family *is* the thing being
+   * shown, known only at runtime, and no packaged asset could carry it. The rule that keeps it on
+   * the content side of that line: **the family must be one the host reported from
+   * `ctx.fonts.list()`.** A family the host never listed is not a styling escape hatch, it is a
+   * value the shell refuses. Size, colour, spacing, and accessibility scaling stay the shell's.
+   */
+  font?: Bindable<string>;
+  fontSize?: Bindable<number>;
+  /** 100–900, matching `FontFace.weight`. */
+  fontWeight?: Bindable<number>;
+  italic?: Bindable<boolean>;
+  /**
+   * Fired once an edit settles — not per keystroke. The shell coalesces a burst of typing and
+   * sends the value it ended on; the bound cell was already written locally, long before this
+   * runs, so the preview never waits on it. Omit it for a pure live preview.
+   */
+  onChange?: ActionSpec;
+}
+export const TextArea = tag<TextAreaProps>("textarea");
+
+export interface SelectOptionProps {
+  /** The value written back into the bound cell when this option is chosen. */
+  value: Str;
+  /** Defaults to `value`. */
+  title?: Str;
+  icon?: Bindable<IconRef>;
+}
+export interface SelectProps {
+  /** Bind a `signal`; the shell writes the chosen option's `value` into it. */
+  value: Bindable<string>;
+  placeholder?: Str;
+  /** Fired after the choice settles. The bound cell is written locally either way. */
+  onChange?: ActionSpec;
+  children?: Children;
+}
+/**
+ * A single-choice picker. Pair it with `<For>` to build the options from a list the extension
+ * fetched — a font picker is `<For each={families}>` emitting one `<Select.Option>` each, and the
+ * shell expands it without waking the isolate.
+ */
+export const Select = Object.assign(tag<SelectProps>("select"), {
+  Option: tag<SelectOptionProps>("select.option"),
+});
+
+// ── Actions ───────────────────────────────────────────────────────────────────
+
+export interface ActionProps {
+  title: Str;
+  onAction: ActionSpec;
+  icon?: Bindable<IconRef>;
+  /** Overrides the unit inferred from the action; usually omit. */
+  requires?: PermissionUnit;
+  destructive?: boolean;
+  /**
+   * **Which menu this action belongs to.** `row` (the default) is ⌘K — the actions menu, which
+   * speaks for whatever is selected. `scope` is ⇧⌘K, the scope handle's menu, which speaks for
+   * the surface you are *in*.
+   *
+   * The split is the one the two keystrokes already promise, and it is about the action's
+   * subject, not its importance: "Quit Process" acts on the row under the cursor and belongs in
+   * ⌘K; "Refresh Every 5 Seconds" acts on the whole table and belongs in ⇧⌘K, next to "Exit
+   * Processes". Putting a surface-wide setting in the row menu makes it read as something that
+   * happens to the selected row.
+   *
+   * Only a rowless surface (`pane`) has both menus, so this is where it applies. Elsewhere it is
+   * ignored rather than honoured into a menu the shell does not draw.
+   */
+  placement?: "row" | "scope";
+}
+export const Action = tag<ActionProps>("action");
+
+// ── Non-content states ────────────────────────────────────────────────────────
+// `<Empty>` / `<Error>` are shipped (the shell renders them as pane states). `<Loading>` is planned
+// — the shell has no loading-root render yet, so it waits, like the other unshipped roots above.
+
+export interface EmptyProps {
+  title: Str;
+  description?: Str;
+  icon?: Bindable<IconRef>;
+}
+export const Empty = tag<EmptyProps>("empty");
+export interface ErrorProps {
+  title: Str;
+  description?: Str;
+  children?: Children;
+}
+export const ErrorView = tag<ErrorProps>("error");
+
+/**
+ * A multi-column table of rows the view describes, rather than rows the scope hands back.
+ *
+ * The scope-level `table` layout (extension-ui §5) is the other way to draw one, and the two are
+ * for different things. That one's rows are `CommandItem`s: Tapcue fuzzy-matches them, ranks them,
+ * drops actions whose permission was denied, and drives keyboard navigation through them. This one
+ * is a view node — the shell draws exactly what is described and searches none of it — so it is for
+ * a table that is *part of a pane*, beside other blocks, whose contents the extension owns.
+ *
+ * `rows` binds a signal, so a `whileVisible` setup writing to it re-renders the table in the shell
+ * with no isolate involved. Each row is an object keyed by column id.
+ */
+export interface TableColumnSpec {
+  id: string;
+  title: Str;
+  /** Character-ish width hint; the shell resolves it against the pane. */
+  width?: number;
+  align?: "leading" | "trailing";
+  /** Right-align and sort by value rather than by text, so `9 MB` sorts below `10 MB`. */
+  numeric?: boolean;
+  /**
+   * Draw each row's `icon` before this column's text — for the leading name column. The icon is
+   * the row's (`CommandItem.icon`, e.g. `process:<pid>`), resolved and drawn by the shell; the
+   * same key the scope-level `table` scheme's columns use.
+   */
+  showsIcon?: boolean;
+}
+
+export interface TableProps {
+  columns: TableColumnSpec[];
+  /**
+   * The rows, as the same `CommandItem`s a scope's `items` returns.
+   *
+   * A row is a row on both paths: `id` gives it identity, `cells` fill the columns, `aliases` add
+   * search keys no column shows, and `defaultActionId`/`defaultActionTitle`/`requires` give it an
+   * action the shell runs on Return, labels in the footer, and drops when the permission was not
+   * granted. None of that is re-invented here — it is the vocabulary rows already had.
+   *
+   * `undefined` and `[]` are different claims. A signal whose value is still `undefined` is a
+   * table whose first data has not arrived — the shell draws it as loading. An empty array is a
+   * table with genuinely nothing in it — the shell shows `empty`. A live table (a `whileVisible`
+   * setup filling the signal) should start from `undefined`, or its first frame asserts an
+   * emptiness nobody has measured yet.
+   */
+  rows: Signal<CommandItem[] | undefined> | Signal<CommandItem[]> | CommandItem[];
+  /** Column id to sort by when the table first appears; omit to keep the order given. */
+  defaultSortColumn?: string;
+  /** Sort descending on first appearance. */
+  defaultSortDescending?: boolean;
+  /** Shown in place of the table when `rows` is empty — genuinely empty, not merely unloaded. */
+  empty?: Str;
+  /**
+   * Filter the rows against what the person typed, matching across every cell.
+   *
+   * The filtering is the shell's and happens on the model it already holds, so typing costs no
+   * round trip and the extension is not woken to answer a keystroke. It is opt-in because a table
+   * is not always a list to search — a summary of four figures is not improved by hiding three of
+   * them — and because a scope that also declares rows already has search over those.
+   *
+   * In a `pane`, this is also what puts the query field in the band above it: a pane is otherwise
+   * drawn with a titlebar, having nothing to filter. So the one word asks for the filtering and
+   * for the thing to type into, and the scope's `placeholder` describes it.
+   */
+  search?: boolean;
+}
+export const Table = tag<TableProps>("table");
+
+// ── Control flow (compiles to bindings; resolved by the shell, no isolate) ─────
+
+export interface ForProps<T> {
+  each: Signal<T[]> | T[];
+  children: (item: T, index: number) => ViewNode;
+}
+export function For<T>(_props: ForProps<T>): ViewNode {
+  return undefined as unknown as ViewNode;
+}
+(For as unknown as { __tag: string }).__tag = "for";
+
+export interface ShowProps {
+  when: Bindable<boolean>;
+  fallback?: ViewNode;
+  children?: Children;
+}
+export function Show(_props: ShowProps): ViewNode {
+  return undefined as unknown as ViewNode;
+}
+(Show as unknown as { __tag: string }).__tag = "show";
+
+/** Grouping with no wrapper node; the factory splices its children into the parent. */
+export const Fragment = tag<{ children?: Children }>("fragment");

package/src/define-extension.ts

@@ -0,0 +1,205 @@
+/**
+ * `defineExtension` — the entry point an extension's `main.js` default-exports.
+ *
+ * Top-level code must do nothing but define the extension: the host evaluates
+ * the module under a load deadline and expects no I/O, no side effects, and no
+ * capability use before the first invocation.
+ */
+
+import { ExtensionError } from "./errors.js";
+import type { JsonValue } from "./json.js";
+import type {
+  CommandHandlers,
+  CommandItem,
+  ContributionHandlers,
+  ExtensionContext,
+  ItemScope,
+  ScopeSpec,
+} from "./types.js";
+import { applySettingChange, settingSignal } from "./reactive.js";
+import { applyAction, driveView, renderView } from "./view-runtime.js";
+
+/**
+ * Narrow a capability the manifest declares as **required**.
+ *
+ * A required capability cannot be missing at runtime — denying it means the
+ * extension was never enabled — but the SDK's types cannot read your manifest, so
+ * they hand you `ctx.http | undefined` regardless. This asserts the manifest's
+ * promise. If it ever throws, the host is broken, not your extension.
+ *
+ * Do not use it on an *optional* capability: there, absence is a state you must
+ * handle, and `if (!ctx.clipboard?.write)` is the whole check.
+ */
+export function requireCapability<T>(capability: T | undefined, name: string): T {
+  if (capability === undefined) {
+    throw new ExtensionError({
+      code: "permission-denied",
+      message: `${name} is declared required but was not granted`,
+    });
+  }
+  return capability;
+}
+
+/**
+ * A registered scope plus the type-safe way to build items that enter it.
+ *
+ * The `type` string and the subject type `S` are linked here, so an item built
+ * with `scope.entry(...)` can never carry a subject the scope's handlers cannot
+ * read — which a bare `scope: { type, subject }` object literal could.
+ */
+export interface DefinedScope<S extends JsonValue> {
+  readonly spec: ScopeSpec<S>;
+  readonly type: string;
+  /** Build a scope-face item: no `defaultActionId`, so Enter enters the scope. */
+  entry(
+    item: Omit<CommandItem<S>, "scope" | "defaultActionId">,
+    subject: S,
+    options?: Omit<ItemScope<S>, "type" | "subject">,
+  ): CommandItem<S>;
+}
+
+export function defineScope<S extends JsonValue>(spec: ScopeSpec<S>): DefinedScope<S> {
+  return {
+    spec,
+    type: spec.type,
+    entry(item, subject, options) {
+      return {
+        ...item,
+        // The scheme travels with the row: an extension declares its scopes in code, so the
+        // shell only learns a scope's layout from an item that enters it. A `canvas` scope must
+        // reach the shell as `canvas`, or it is rendered as the wrong thing; a `table` scope must
+        // carry its `columns` and `live` flag the same way. `queryMode` travels for the same reason
+        // — the shell only knows whether to filter the scope's rows locally (`catalog`, the default)
+        // or forward the query to the scope (`remote`) from the row that enters it, since the scope
+        // is declared in code, not the manifest.
+        scope: {
+          type: spec.type,
+          subject,
+          scheme: spec.scheme,
+          queryMode: spec.queryMode ?? "catalog",
+          ...options,
+        },
+      };
+    },
+  };
+}
+
+export interface ExtensionSpec {
+  /**
+   * `CommandHandlers<any>`, not a union of `CommandHandlers<never> | CommandHandlers<JsonValue>`:
+   * TypeScript gives no contextual types to a parameter whose target is a union, so a
+   * union here would silently turn every inline `query(request, ctx)` into
+   * `query(request: any, ctx: any)` and stop checking the return type — under
+   * `strict`, it does not even compile. Commands are keyed by id and each carries its
+   * own subject type, so there is nothing for one shared type parameter to say.
+   */
+  commands: Record<string, CommandHandlers<any>>;
+  /** Scopes this extension's items can enter. Declared in code, not in the manifest. */
+  scopes?: DefinedScope<any>[];
+  /**
+   * **Rows this extension adds to scopes it does not own**, keyed by the `contributes[].id` the
+   * manifest declared (architecture §11.3).
+   *
+   * Keyed like `commands` rather than listed like `scopes`, because that is what a contribution
+   * is: declared in the manifest — the user enters the scope, so Tapcue has to know who to ask
+   * without running anything — and implemented here. **Both halves are required and the host
+   * checks them against each other at load:** a manifest entry with no handler promises rows
+   * nobody wrote, and a handler with no manifest entry is code that will never be called. Either
+   * way somebody wrote half a contribution, and half of one failing loudly beats it failing in
+   * silence.
+   *
+   * `ContributionHandlers<any>` for the reason `commands` is `CommandHandlers<any>`: a union
+   * target gives inline handler parameters no contextual type, so each entry carries its own
+   * scope type instead of one shared parameter.
+   */
+  contributions?: Record<string, ContributionHandlers<any>>;
+  /**
+   * **Slots this extension fills**, keyed by the `provides[].id` the manifest declared.
+   *
+   * The mirror image of `contributions`: there, Tapcue owns a place and the extension adds rows to
+   * it; here, Tapcue owns a *question* and the extension adds an answer to it. Both halves are
+   * required and checked against each other at load, for the same reason.
+   *
+   * A slot handler is a **query, never an effect** — it is handed an `ExtensionContext`, not an
+   * `ActionContext`, because nobody pressed anything. Tapcue asks when the launcher opens and
+   * caches the answer; a slow one is late, not felt.
+   */
+  provisions?: Record<string, ProvisionHandlers>;
+  /** Called before the isolate is dropped. Best-effort: a forced termination skips it. */
+  dispose?(reason: string): void | Promise<void>;
+}
+
+/** What Tapcue asks when it needs a slot filled. */
+export interface SlotRequest {
+  provisionId: string;
+  slot: string;
+  /** The most answers Tapcue will keep. Returning more is not an error; the tail is dropped. */
+  limit: number;
+}
+
+/**
+ * One project folder the user works in.
+ *
+ * `path` is absolute, and the host still checks it: it must exist, be a directory, and sit under
+ * the user's home. An extension that names a folder is making a claim about where the user's files
+ * are, not being handed the right to read them — nothing here opens anything, and every row Tapcue
+ * builds from one shows the full path it landed on.
+ */
+export interface WorkspaceRoot {
+  path: string;
+  /** What to call it, when the tool knows a better name than the folder's own. */
+  name?: string;
+  /** Seconds since the epoch, for ordering. Freshest first is the useful order. */
+  usedAt?: number;
+}
+
+/**
+ * The handler shape per slot. A union of one today; adding a slot adds a member, and the manifest's
+ * `slot` field is what selects between them.
+ */
+export interface ProvisionHandlers {
+  roots?(request: SlotRequest, ctx: ExtensionContext): Promise<WorkspaceRoot[]> | WorkspaceRoot[];
+}
+
+export interface ExtensionDefinition {
+  commands: Record<string, CommandHandlers<any>>;
+  scopes: DefinedScope<any>[];
+  /**
+   * Optional on the *definition*, required in nothing: a bundle built against an SDK that
+   * predates §11.3 has no contributions at all, and the glue that reads this must load it
+   * anyway — the manifest's `api` range is a compatibility promise, so an absent key here has
+   * to mean "declares none" rather than "malformed".
+   */
+  contributions?: Record<string, ContributionHandlers<any>>;
+  /** Absent means "declares none", for the reason `contributions` is optional here. */
+  provisions?: Record<string, ProvisionHandlers>;
+  dispose?(reason: string): void | Promise<void>;
+  /**
+   * The interactive-view reactive loop (view-runtime.ts), attached here so the host glue
+   * (bootstrap.js) can drive a `view` handler without importing the SDK: the SDK is bundled
+   * into the extension, so this is how the two meet. Not part of the authored surface.
+   */
+  runtime: {
+    renderView: typeof renderView;
+    applyAction: typeof applyAction;
+    driveView: typeof driveView;
+    /**
+     * The settings-as-state pair (reactive.ts). The host glue builds `ctx.settings`, so it is the
+     * glue that has to create a settings-following cell and to announce a write — and the glue
+     * cannot import the SDK. Same reason `driveView` is here.
+     */
+    settingSignal: typeof settingSignal;
+    applySettingChange: typeof applySettingChange;
+  };
+}
+
+export function defineExtension(spec: ExtensionSpec): ExtensionDefinition {
+  return {
+    commands: spec.commands as Record<string, CommandHandlers<any>>,
+    scopes: (spec.scopes ?? []) as DefinedScope<any>[],
+    contributions: (spec.contributions ?? {}) as Record<string, ContributionHandlers<any>>,
+    provisions: spec.provisions ?? {},
+    dispose: spec.dispose,
+    runtime: { renderView, applyAction, driveView, settingSignal, applySettingChange },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,90 @@
+/**
+ * Structured, user-safe errors. Never put secrets, authorization headers, host
+ * paths, or raw service responses in `message` — the shell shows it to the user
+ * and the host records it in diagnostics.
+ */
+
+/**
+ * Closed vocabulary for the codes the host itself raises. Extensions may add
+ * their own namespaced codes (`weather.no-such-place`), so the type stays open.
+ */
+export type ErrorCode =
+  | "permission-denied"
+  | "cancelled"
+  | "deadline-exceeded"
+  | "quota-exceeded"
+  | "invalid-request"
+  | "invalid-result"
+  | "network"
+  | "unavailable"
+  | "not-found"
+  | (string & {});
+
+export interface ExtensionErrorInit {
+  code: ErrorCode;
+  message: string;
+  /** Whether retrying the same invocation could plausibly succeed. */
+  retryable?: boolean;
+  /** Optional recovery the shell may offer. */
+  recovery?: ExtensionErrorRecovery;
+}
+
+/**
+ * A recovery is always **a command of this same package, run again** — either the
+ * same command with different arguments, or a sibling command. An extension
+ * cannot name a host action: it must not be able to put Tapcue's own permission
+ * or settings UI behind a title it wrote.
+ *
+ * Permission recovery therefore has no place here by design. A required
+ * permission cannot be denied at runtime (the extension would not be enabled),
+ * and a denied *optional* permission is something the extension degrades around
+ * — turning it back on is the shell's and settings' business, not an error's.
+ */
+export interface ExtensionErrorRecovery {
+  title: string;
+  /** Must be a command declared in this extension's manifest. */
+  commandId: string;
+  arguments?: Record<string, string>;
+}
+
+export class ExtensionError extends Error {
+  readonly code: ErrorCode;
+  readonly retryable: boolean;
+  readonly recovery?: ExtensionErrorRecovery;
+
+  constructor(init: ExtensionErrorInit) {
+    super(init.message);
+    this.name = "ExtensionError";
+    this.code = init.code;
+    this.retryable = init.retryable ?? false;
+    this.recovery = init.recovery;
+  }
+}
+
+export function isExtensionError(value: unknown): value is ExtensionError {
+  return value instanceof ExtensionError;
+}
+
+/** The host raises this (and rejects pending capability calls) on cancellation. */
+export function cancelledError(reason = "Invocation was cancelled"): ExtensionError {
+  return new ExtensionError({ code: "cancelled", message: reason, retryable: false });
+}
+
+/**
+ * **The code behind a rejection, without reading the prose.**
+ *
+ * The host tags what it refuses — `deadline-exceeded: exec "op-item-list" ran past its deadline` —
+ * and an extension that has to tell those apart by matching English will get it wrong. The wrong
+ * answer is rarely harmless: a *timeout* read as a missing binary is how somebody with the tool
+ * installed gets told to install it, while the dialog they were meant to answer is still on screen.
+ *
+ * Returns `undefined` for an error that carries no code, which is not the same as a code you do
+ * not recognise: an unknown code should degrade to the generic path, never to the wrong one.
+ */
+export function errorCode(error: unknown): ErrorCode | undefined {
+  if (error instanceof ExtensionError) return error.code;
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  // `<code>: <message>`, the shape every coded host refusal has.
+  const match = /^([a-z][a-z-]*[a-z]):\s/.exec(message);
+  return match?.[1];
+}

package/src/i18n.ts

@@ -0,0 +1,64 @@
+/**
+ * Message catalogs.
+ *
+ * Tapcue's own UI is localized; extension rows sitting next to it in English are
+ * not the extension author's fault, they are a missing platform mechanism. So the
+ * package ships catalogs as data:
+ *
+ *   locales/en.json        { "command.title": "Weather", … }
+ *   locales/zh-CN.json     { "command.title": "天气", … }
+ *
+ * Manifest strings reference a key with a leading `@` (`"title": "@command.title"`);
+ * a string without one is a literal. Runtime strings go through `ctx.t("key")`.
+ * Catalogs are data files covered by `checksums.json`, so they are reviewable and
+ * translatable without touching the bundle.
+ *
+ * Numbers, dates, and plurals are `Intl`'s job — it is available in the isolate.
+ */
+
+export type LocaleCatalog = Record<string, string>;
+export type LocaleCatalogs = Record<string, LocaleCatalog>;
+
+export type Translate = (key: string, params?: Record<string, string | number>) => string;
+
+/**
+ * Fallback chain: exact tag (`zh-CN`) → language (`zh`) → the package's
+ * `defaultLocale` → the key itself. A missing key never throws: a scene with a
+ * raw key in it is bad, a scene that fails to render is worse.
+ */
+export function resolveCatalog(
+  catalogs: LocaleCatalogs,
+  locale: string,
+  defaultLocale: string,
+): LocaleCatalog {
+  const language = locale.split("-")[0];
+  return {
+    ...(catalogs[defaultLocale] ?? {}),
+    ...(catalogs[language] ?? {}),
+    ...(catalogs[locale] ?? {}),
+  };
+}
+
+export function createTranslator(catalog: LocaleCatalog, onMissing?: (key: string) => void): Translate {
+  return (key, params) => {
+    const template = catalog[key];
+    if (template === undefined) {
+      onMissing?.(key);
+      return key;
+    }
+    if (!params) return template;
+    return template.replace(/\{(\w+)\}/g, (whole, name: string) =>
+      name in params ? String(params[name]) : whole,
+    );
+  };
+}
+
+/** `"@command.title"` → `"command.title"`; a literal string → `undefined`. */
+export function catalogKey(value: string): string | undefined {
+  return value.startsWith("@") ? value.slice(1) : undefined;
+}
+
+export function localizeString(value: string, translate: Translate): string {
+  const key = catalogKey(value);
+  return key === undefined ? value : translate(key);
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./json.js";
+export * from "./errors.js";
+export * from "./i18n.js";
+export * from "./scene.js";
+export * from "./capabilities.js";
+export * from "./types.js";
+export * from "./define-extension.js";
+export * from "./manifest.js";
+export * from "./permission-units.js";
+export * from "./view.js";
+export * from "./reactive.js";
+export * from "./components.js";
+export * from "./view-runtime.js";

package/src/json.ts

@@ -0,0 +1,24 @@
+/**
+ * The value vocabulary that may cross the guest ↔ host boundary.
+ *
+ * Everything an extension hands back to Tapcue — items, scenes, scope subjects,
+ * settings — must be structurally clonable JSON. Host paths, native pointers and
+ * other extensions' handles never cross the boundary.
+ *
+ * Two TypeScript notes for extension authors:
+ *
+ * - An `interface` is NOT assignable to `JsonValue` (interfaces get no implicit
+ *   index signature). Declare payload shapes with `type X = { … }`.
+ * - Optional properties are allowed and are dropped on serialization, which is
+ *   why the object branch admits `undefined` — otherwise `{ region?: string }`
+ *   would not satisfy `JsonValue`.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | JsonObject;
+
+export type JsonObject = { [key: string]: JsonValue | undefined };