@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.2

package/lib/build/callbacks.d.ts

@@ -0,0 +1,998 @@
+/**
+ * Callback interfaces for SDK components
+ *
+ * Defines the callbacks available to the engine, user interfaces, and configuration
+ * user interfaces. LLM-specific types are imported from ./llm.
+ *
+ * Asset references — every callback below that takes or returns a file
+ * identifier uses the unified asset URI scheme:
+ *
+ *   `asset:<path>` — package-bundled file. The path is relative to the
+ *                    active scenario's `assets/` directory.
+ *   `blob:<id>`    — runtime-uploaded file. The id is whatever the runtime
+ *                    assigns when the blob was stored.
+ *
+ * Any string starting with `asset:` or `blob:` is unambiguously an asset
+ * reference. No other strings are.
+ */
+import { ExtractTextFunction } from './document.js';
+import { LLMGenerateFunction } from './llm.js';
+import { ApiUse } from './resource-schema.js';
+import { GenerateSpeechFunction } from './speech.js';
+/**
+ * Shape returned by `readAsset` for both `asset:` and `blob:` references.
+ */
+export interface ReadAssetResponse {
+    /** Raw bytes of the referenced file. */
+    data: Uint8Array;
+    /** MIME type of the referenced file (e.g. `application/pdf`, `image/png`). */
+    mimeType: string;
+    /**
+     * Display name of the referenced file. For `blob:` references this is the
+     * original name supplied at upload time. For `asset:` references this is
+     * the basename of the path.
+     */
+    name: string;
+}
+/**
+ * Who a team is: the fields every team entry in the SDK carries (§5.6).
+ *
+ * One shape wherever a team is listed or addressed, so a renderer written for
+ * one list serves every other: the team lists a surface receives, a cross-team
+ * or past-state row, an endpoint's `team` and `session.teams`, the state
+ * projection and a presentation's teams all extend it.
+ */
+export interface TeamInfo {
+    /** Stable `team-N` id (§5.6). */
+    teamId: string;
+    /**
+     * Platform-assigned, session-stable team index. Assigned at team creation
+     * (dense 0..N-1 at session start) and never reassigned: removals leave a
+     * gap, later-added teams take the lowest unused index. The same team has
+     * the same index everywhere it appears. `teams.defaultNames` entries are
+     * applied by this index.
+     */
+    index: number;
+    /** The team's display name, resolved per §5.4 (a facilitator rename included). */
+    name: string;
+}
+/**
+ * One team's state, live. Returned per team by the `useUserInterfaceCrossTeamData` hook.
+ *
+ * {@link PastStateEntry} is this plus *when*, which is the only thing that
+ * actually differs between watching a team now and reviewing it later. Sharing
+ * the base is what lets one cell renderer serve both: `entry.name` and
+ * `entry.context.ledger` read the same either way.
+ */
+/**
+ * One team's state at one committed past tick, as returned by `getPastState`.
+ *
+ * One entry per (tick, team) pair, which is what lets a single call answer
+ * every historical question the surfaces used to need four for: one round for
+ * one team, a range for one team, one round across every team, a range across
+ * every team. Group by `tick` for a results table, filter by `teamId` for a
+ * trend line.
+ *
+ * `context` is composed exactly like the live `data` a surface receives — the
+ * team's own context with the shared store as it stood at that tick folded in
+ * — so a review screen renders a historical board through the surface's
+ * *current* config, and is then narrowed to `capabilityIds` when the query
+ * named any.
+ *
+ * Entries are point-in-time and immutable: the value for a given tick never
+ * changes within a session (an undo or reset removes it, it does not rewrite
+ * it), so a consumer can cache what it has fetched.
+ */
+export interface TeamStateEntry<T = Record<string, unknown>> extends TeamInfo {
+    /**
+     * The team's context, composed like the live `data` a surface receives and
+     * narrowed to what this surface may see: its declared `crossTeam` reads for
+     * another team, its whole declared set for its own.
+     */
+    context: T;
+}
+export interface PastStateEntry<T = Record<string, unknown>> extends TeamStateEntry<T> {
+    /**
+     * The snapshot's number: snapshot N is the state after tick N (after
+     * `Init`, for snapshot 0), with the decisions round N + 1 entered on it.
+     */
+    tick: number;
+    /** When the snapshot was taken (epoch milliseconds). */
+    recordedAt: number;
+    /** Whether the tick controller had signalled game complete at that tick. */
+    complete: boolean;
+}
+/**
+ * What to read from the past.
+ *
+ * Both tick bounds are inclusive and `toTick` is clamped to the last committed
+ * past tick, so `{ fromTick: 0, toTick: completedTicks }` means 'everything
+ * reviewable' with no head arithmetic. Omitting `toTick` reads the single tick
+ * `fromTick`.
+ */
+export interface PastStateQuery<T = Record<string, unknown>> {
+    /** First tick to read, inclusive. */
+    fromTick: number;
+    /**
+     * Last tick to read, inclusive; clamped to the last committed past tick.
+     * Omit to read only `fromTick`.
+     */
+    toTick?: number;
+    /**
+     * Which teams to read.
+     *
+     * `'own'` (the default) is the caller's own team on a game surface. `'all'`
+     * is every team. A team id reads that one team, which is how a session
+     * surface addresses a team it is not scoped to. Team ids are opaque and
+     * stable: take one from `SessionData` or `setTeamList`, never build one
+     * from an index. A runtime never assigns `'own'` or `'all'` as a team id
+     * (§5.6), so the sentinels cannot collide with one.
+     */
+    teams?: 'own' | 'all' | string;
+    /**
+     * Capabilities to include in each returned `context`. Omit for the
+     * surface's whole declared set.
+     *
+     * This is what makes a range read cheap: a results chart over sixty rounds
+     * wants one field per round, not sixty whole boards, and a growing log kept
+     * in context to avoid the round trips is delivered to every surface on
+     * every push for the rest of the session.
+     */
+    capabilityIds?: (keyof T & string)[];
+}
+/**
+ * A participant the platform tracks for some team in the session (§13.1).
+ *
+ * The one participant type, wherever a participant appears: the caller's own
+ * identity (`useUserInterfaceParticipant`), the live roster for the caller's
+ * team (`useUserInterfaceParticipants`) and for every team
+ * (`useSessionUserInterfaceParticipants`), the `getAllTeamsParticipants`
+ * callback, hook payloads, a validator's `actor`, an endpoint's roster and
+ * the state projection. The `teamId` groups a flat list by team; join it
+ * against the team list for each team's display name and index.
+ *
+ * `connected` is separate from existence: a participant record lives for the
+ * whole session once created, so an absent participant is `connected: false`
+ * rather than a missing entry.
+ */
+export interface Participant {
+    /** Stable participant id, unique within its team. */
+    id: string;
+    /** The participant's display name. */
+    name: string;
+    /** Zero-based join order within the team. */
+    index: number;
+    /**
+     * True while the participant has a live connection to the platform.
+     *
+     * Informative wherever it appears, including in a hook payload: a
+     * facilitator can move a participant who is offline, so a `participantMove`
+     * hook sees `false` there and can act on it.
+     */
+    connected: boolean;
+    /** The team this participant belongs to (e.g. `team-1`). */
+    teamId: string;
+}
+/**
+ * The host's theme preference. `'system'` means the host follows the
+ * operating system's colour scheme; `'light'` and `'dark'` are explicit
+ * choices. Distinct from the resolved palette delivered to UIs through the
+ * theme channel — a UI reading `'system'` knows the host has not overridden
+ * the OS, which the resolved light/dark mode alone cannot tell it.
+ */
+export type ThemePreference = 'light' | 'dark' | 'system';
+/**
+ * A host-rendered overlay a session surface may ask the host to open
+ * (SPECIFICATION.md §6.4).
+ *
+ * These stay host-owned: the host renders them in its own chrome, above the
+ * surface, where the surface can neither restyle nor suppress them. Only the
+ * trigger is delegated, so a facilitator in front of a surface that owns the
+ * whole canvas does not have to leave it to reach the guide or a print sheet.
+ *
+ * The enum is extensible. Treat an unknown member as an overlay you cannot
+ * offer rather than an error, and render a control only for a member the host
+ * actually reports (see `openHostOverlay`).
+ */
+export type HostOverlay = 'facilitator-guide' | 'print-sheets';
+/**
+ * Every callback a runtime may offer logic: the engine, hooks, tick
+ * controllers and endpoints.
+ *
+ * The four `ApiUse` callbacks (`generateText`, `extractText`,
+ * `generateSpeech`, `writeBlob`) are services, gated by the resource's `uses`
+ * (§6.11). This interface is the superset, which is why three of them carry a
+ * `?`: whether one is there depends on what the resource declared. Type a
+ * resource's callbacks with its generated `Callbacks` ({@link LogicCallbacks})
+ * instead, where a declared service is present, so it is called without `?.`
+ * or `!`, and an undeclared one is absent from the type (and throws
+ * {@link UndeclaredApiUseError} if reached anyway). A runtime that cannot
+ * provide a service a package declares refuses the package at load.
+ */
+export interface SignatureCallbacks {
+    /**
+     * Generate text using an LLM
+     *
+     * Examples:
+     * ```typescript
+     * // Simple string prompt
+     * const response = await callbacks.generateText("Summarize this: " + text);
+     *
+     * // Options object with prompt
+     * const response = await callbacks.generateText({
+     *   prompt: "Summarize this: " + text
+     * });
+     *
+     * // With conversation history
+     * const response = await callbacks.generateText({
+     *   messages: [
+     *     { role: 'user', content: 'What is 2+2?' },
+     *     { role: 'assistant', content: '4' },
+     *     { role: 'user', content: 'What about 3+3?' }
+     *   ]
+     * });
+     *
+     * // Structured output with JSON Schema
+     * const response = await callbacks.generateText({
+     *   prompt: "Extract the name and age from: John is 30 years old",
+     *   jsonSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       name: { type: 'string' },
+     *       age: { type: 'integer' }
+     *     },
+     *     required: ['name', 'age']
+     *   }
+     * });
+     *
+     * // With custom system prompt
+     * const response = await callbacks.generateText({
+     *   prompt: "Translate to Spanish: Hello",
+     *   systemPrompt: "You are a professional translator. Respond only with the translation."
+     * });
+     * ```
+     */
+    generateText: LLMGenerateFunction;
+    /**
+     * Read the bytes of an asset by reference. Accepts either an
+     * `asset:<path>` reference (resolved against the active scenario's
+     * `assets/` directory) or a `blob:<id>` reference (resolved against the
+     * runtime's blob store).
+     *
+     * Example:
+     * ```typescript
+     * const file = await callbacks.readAsset("blob:abc123");
+     * const briefing = await callbacks.readAsset("asset:briefing.pdf");
+     * ```
+     */
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    /**
+     * Read a committed past tick, without keeping a copy of it in context.
+     *
+     * The same history a surface reads through its own `getPastState` (§12.5),
+     * offered to logic on the same terms. An endpoint answering a facilitator's
+     * 'how has this team's profit moved' has no other route to it: unlike a
+     * surface, it cannot ask a UI to fetch the rounds and pass them in, because
+     * the caller it exists for may be an agent with no surface at all.
+     *
+     * It is also what lets an engine stop carrying a round-keyed ledger. A
+     * value the next round needs had to live in context, where it rides every
+     * push to every participant for the rest of the session (§12.4.2); read it
+     * back from here instead and it rides nothing.
+     *
+     * **What is reachable.** Every round committed before this call into logic
+     * began. For an engine that is every round strictly before the one its tick
+     * is closing — the round being closed is the board in `context`, and it is
+     * not recorded until the tick commits. A hook or endpoint runs outside a
+     * tick and reaches the head. Ticks outside that are omitted rather than
+     * returned as holes, exactly as for a surface, so a short result is normal.
+     *
+     * **Whose rounds.** `teams: 'own'` (the default) is the team this call is
+     * scoped to. A session-scoped endpoint (§6.12) has no team of its own, so
+     * `'own'` reads as the whole session there, which is the rule a session
+     * surface already follows. Entries carry the capabilities this resource
+     * declared in `reads` and `writes`, projected exactly as its live context
+     * is (§7.4).
+     *
+     * Not gated by `uses`: it reads state this resource is already entitled to
+     * see, one tick further back.
+     *
+     * Always present, like `readAsset`, the other callback `uses` does not
+     * gate.
+     *
+     * Example:
+     * ```typescript
+     * // what this team submitted last round
+     * const [previous] = await callbacks.getPastState<Context>({
+     *     fromTick: meta.tick - 1,
+     * });
+     *
+     * // one field across every completed round, rather than a ledger in context
+     * const trend = await callbacks.getPastState<Context>({
+     *     fromTick: 0,
+     *     toTick: meta.tick - 1,
+     *     capabilityIds: ['profit'],
+     * });
+     * ```
+     */
+    getPastState: <T = Record<string, unknown>>(query: PastStateQuery<T>) => Promise<PastStateEntry<T>[]>;
+    /**
+     * Extract text content from a document referenced under the unified
+     * asset URI scheme. Accepts either an `asset:` or `blob:` reference.
+     * Returns the extracted text, suitable for passing to an LLM.
+     *
+     * Currently supports PDF files.
+     *
+     * Example:
+     * ```typescript
+     * const result = await callbacks.extractText("blob:abc123");
+     * const summary = await callbacks.generateText("Summarize: " + result.content);
+     * ```
+     */
+    extractText?: ExtractTextFunction;
+    /**
+     * Synthesise speech from text. Returns a `blob:`-prefixed reference for
+     * the generated audio, which can be played in a UI via `getAssetUrl` or
+     * read in the engine via `readAsset`.
+     *
+     * Example:
+     * ```typescript
+     * const audio = await callbacks.generateSpeech({
+     *   text: 'Welcome to the simulation.',
+     *   voice: 'narrator',
+     * });
+     * // audio.reference can be passed to a UI for playback
+     * ```
+     */
+    generateSpeech?: GenerateSpeechFunction;
+    /**
+     * Write raw bytes to the runtime blob store. Returns a `blob:`-prefixed
+     * reference that can be returned to a caller (e.g. an endpoint response)
+     * and later resolved via `getAssetUrl`, `readAsset`, or `extractText`.
+     *
+     * The optional `options.retention` controls when the blob is deleted: `'game'`
+     * (default) blobs are wiped on game reset; `'settings'` blobs survive resets
+     * and are wiped only when the session is re-initialised.
+     *
+     * Example:
+     * ```typescript
+     * const reference = await callbacks.writeBlob(buffer, {
+     *   name: 'summary.pdf',
+     *   mimeType: 'application/pdf',
+     * });
+     * return { reportRef: reference };
+     * ```
+     */
+    writeBlob?: (data: Uint8Array | ArrayBuffer, options: {
+        name: string;
+        mimeType: string;
+        retention?: 'settings' | 'game';
+    }) => Promise<string>;
+}
+/**
+ * Callbacks available to user interface components
+ */
+export interface UserInterfaceCallbacks {
+    /**
+     * Request the game to advance to the next tick.
+     * Equivalent to the player clicking the next-tick button.
+     *
+     * Note this does not submit anything: writes reach the team's context when
+     * `setData` is called, not when a tick is requested. Advancing the tick
+     * runs the engine over what is already there.
+     *
+     * Returns a promise that resolves once the tick has finished and context is
+     * updated, and rejects with a `MutationError` when the tick cannot run (e.g.
+     * the tick limit is reached). Safe to ignore for fire-and-forget.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.requestTick();
+     * ```
+     */
+    requestTick: () => Promise<void>;
+    /**
+     * Rename the team this surface belongs to.
+     *
+     * Names no team, because there is nothing to name: the host resolves which
+     * team the caller is on from its own bookkeeping, so a surface can only ever
+     * rename its own. The new name is the team's real name everywhere, reaching
+     * the host's own chrome and print sheets as well as every game surface, so a
+     * game has no reason to keep a display name of its own alongside it.
+     *
+     * Available on every player surface, participants and observers alike, with
+     * nothing to declare. The facilitator can rename the same team at the same
+     * moment from the session surface, so read the result back from
+     * `useUserInterfaceOwnTeam()` rather than trusting the write: the last change wins and the
+     * pushed value is the only authority.
+     *
+     * Resolves once the new roster is persisted and broadcast. Rejects with a
+     * `MutationError` when the host refuses: `denied` for a frozen session or a
+     * name it will not accept (blank, or past the host's length cap), which is
+     * terminal, and `error` for anything transient.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.renameOwnTeam('The Cartographers');
+     * ```
+     */
+    renameOwnTeam: (name: string) => Promise<void>;
+    /**
+     * Upload a file as a blob. Returns a `blob:`-prefixed reference that can
+     * be stored in context/config and later resolved via `getAssetUrl`,
+     * `readAsset`, or `extractText`.
+     *
+     * The blob's deletion lifecycle is assigned by the host from the UI type,
+     * not chosen by the bundle: uploads from the setup UI or the scenario
+     * editor survive game resets and are wiped only when the session is
+     * re-initialised; uploads from every other UI surface are wiped on game
+     * reset.
+     *
+     * Example:
+     * ```typescript
+     * const reference = await callbacks.uploadBlob(file);
+     * // Store in context: setData({ attachment: reference })
+     * ```
+     */
+    uploadBlob: (file: File) => Promise<string>;
+    /**
+     * Resolve an asset reference to a URL that can be used directly in HTML
+     * elements. Accepts either an `asset:<path>` or `blob:<id>` reference.
+     *
+     * Example:
+     * ```typescript
+     * const url = callbacks.getAssetUrl("blob:abc123");
+     * const logo = callbacks.getAssetUrl("asset:shared/logo.svg");
+     * // <img src={url} />
+     * ```
+     */
+    getAssetUrl: (reference: string) => string;
+    /**
+     * Read the bytes of an asset by reference. Accepts either an
+     * `asset:<path>` reference (resolved against the active scenario's
+     * `assets/` directory) or a `blob:<id>` reference.
+     *
+     * Example:
+     * ```typescript
+     * const file = await callbacks.readAsset("blob:abc123");
+     * ```
+     */
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    /**
+     * Read committed past state: one round or a range, this team or every
+     * team, whole boards or named capabilities.
+     *
+     * Always resolves to a list, ordered by `tick` then by stable team index,
+     * with one {@link PastStateEntry} per (tick, team) pair. A single round is
+     * a list of one, and an empty list means nothing in that range is
+     * reviewable — the same answer for a range past the head, an undone range,
+     * and a reset session. There is no separate `null`: 'nothing here' has one
+     * spelling.
+     *
+     * Reviewable history is scoped to the session. A reset bulk-deletes the
+     * snapshots, so every past round a player could scrub to disappears.
+     *
+     * Ticks that are not committed past ticks are **omitted** rather than
+     * returned as holes: a tick at or above the current head (read it from
+     * `useUserInterfaceData`'s `completedTicks`), an undone or reset tick, and any
+     * negative, non-integer or out-of-range tick. A host MAY return fewer
+     * entries than the range implies, so treat a short result as normal and
+     * read on from the last tick you received. It rejects with a
+     * {@link TickSnapshotError} only on a genuine transport or host fault.
+     *
+     * **Authorisation.** Not gated by the bundle's `uses`. Own-team entries
+     * carry the capabilities this surface declared in `reads` and `writes`.
+     * `teams: 'all'` additionally requires `crossTeam: true` on a capability
+     * for it to appear in *another* team's entry (§6.2), which is the same
+     * boundary the live `useUserInterfaceCrossTeamData` hook enforces: reading another
+     * team's history grants nothing reading it live would not.
+     *
+     * Debounce scrubbing and cache what you fetch: an entry is immutable until
+     * the head decreases, so re-visiting a round is free.
+     *
+     * Example:
+     * ```typescript
+     * // this round, this team
+     * const [board] = await callbacks.getPastState<Context>({ fromTick: day });
+     * if (board) renderBoard(board.context);
+     *
+     * // a profit trend over every completed round, one field per round
+     * const trend = await callbacks.getPastState<Context>({
+     *     fromTick: 0,
+     *     toTick: completedTicks,
+     *     capabilityIds: ['profit'],
+     * });
+     *
+     * // every team's ledger at one past round
+     * const settlement = await callbacks.getPastState<Context>({
+     *     fromTick: day,
+     *     teams: 'all',
+     *     capabilityIds: ['ledger'],
+     * });
+     * ```
+     */
+    getPastState: <T = Record<string, unknown>>(query: PastStateQuery<T>) => Promise<PastStateEntry<T>[]>;
+    /**
+     * Read the current participant roster of every team in the session, for
+     * building a cross-team directory (who is on each team) in a negotiation or
+     * trading game. Returns one flat entry per participant across all teams,
+     * each tagged with its `teamId`; join against {@link useUserInterfaceTeams}
+     * for team names and indexes.
+     *
+     * The result is a point-in-time snapshot, not a live subscription: it does
+     * not update as participants join or leave, so re-call it to refresh. The
+     * caller's own team stays live through the {@link useUserInterfaceParticipants}
+     * hook.
+     *
+     * Only meaningful in shared-state games, and gated by the bundle's
+     * `crossTeamParticipants` declaration: a UI that did not declare it resolves
+     * to an empty array. Rejects only on a genuine transport or host fault.
+     *
+     * Example:
+     * ```typescript
+     * const everyone = await callbacks.getAllTeamsParticipants();
+     * const byTeam = Map.groupBy(everyone, (p) => p.teamId);
+     * ```
+     */
+    getAllTeamsParticipants: () => Promise<Participant[]>;
+    /**
+     * Server-side endpoints declared by this UI's bundle. Each entry calls a
+     * named, author-written handler; the host validates the request against
+     * the endpoint's `requestSchema`, invokes the handler, and validates the
+     * response before returning it.
+     *
+     * Generated `types.ts` narrows this to a strongly-typed map of the
+     * endpoints the UI declared in its `endpoints` array.
+     *
+     * Example:
+     * ```typescript
+     * const { summary } = await callbacks.endpoints['com.example.summarise']({ text });
+     * ```
+     */
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    /**
+     * Set the host's theme preference. The host applies the new preference,
+     * persists it, and broadcasts the change back to every UI, so the value
+     * returned by {@link useUserInterfaceThemePreference} updates everywhere.
+     * Pass `'system'` to follow the operating system.
+     *
+     * Read the current preference reactively with
+     * {@link useUserInterfaceThemePreference}; this callback only sets it.
+     *
+     * Example:
+     * ```typescript
+     * callbacks.setThemePreference('dark');
+     * ```
+     */
+    setThemePreference: (preference: ThemePreference) => void;
+}
+/**
+ * Callbacks available to waiting room user interface components.
+ *
+ * A waiting room UI is a game UI shown in a different display context, so it
+ * receives the player callback surface unchanged rather than a reduced one.
+ * The alias exists so generated `types.ts` files name the surface they consume.
+ */
+export type WaitingRoomUserInterfaceCallbacks = UserInterfaceCallbacks;
+/**
+ * Callbacks available to session user interface components.
+ *
+ * This is the game's whole-session facilitator surface, so the callbacks are
+ * session-level across every team rather than scoped to one. Game flow
+ * callbacks accept an optional `teamId` to target a specific team; omitting
+ * it applies the action to all teams (or is ignored in shared-state mode).
+ */
+export interface SessionUserInterfaceCallbacks {
+    /**
+     * Upload a file as a blob. Returns a `blob:`-prefixed reference. The host
+     * assigns the blob's deletion lifecycle from the UI type (see
+     * `UserInterfaceCallbacks.uploadBlob`).
+     *
+     * Example:
+     * ```typescript
+     * const reference = await callbacks.uploadBlob(file);
+     * ```
+     */
+    uploadBlob: (file: File) => Promise<string>;
+    /**
+     * Resolve an asset reference to a URL. Accepts either an
+     * `asset:<path>` or `blob:<id>` reference.
+     *
+     * Example:
+     * ```typescript
+     * const url = callbacks.getAssetUrl("blob:abc123");
+     * ```
+     */
+    getAssetUrl: (reference: string) => string;
+    /**
+     * Read the bytes of an asset by reference.
+     *
+     * Example:
+     * ```typescript
+     * const file = await callbacks.readAsset("blob:abc123");
+     * ```
+     */
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    /**
+     * Read committed past state, the same call the player surface has, with
+     * two differences that follow from a session UI not being scoped to a
+     * team.
+     *
+     * `teams` defaults to `'all'` here rather than `'own'`, because a
+     * facilitator surface has no own team, and it accepts a `team-N` id to
+     * read one named team. And there is no `crossTeam` gate: a session UI
+     * already receives every team's declared context live through
+     * `SessionData`, so reading the same declared fields shifted in time
+     * grants it nothing it did not have. It is bounded by this surface's own
+     * declared `reads` and `writes`, and never returns a `private` capability
+     * (§6.1).
+     *
+     * Everything else matches: a list ordered by `tick` then stable team
+     * index, one entry per (tick, team) pair, unreviewable ticks omitted, an
+     * empty list for a range holding nothing, and a rejection only on a
+     * genuine fault.
+     *
+     * Example:
+     * ```typescript
+     * // a results table: rows are rounds, entries are teams
+     * const rows = await callbacks.getPastState<Context>({
+     *     fromTick: 0,
+     *     toTick: head,
+     *     capabilityIds: ['profit'],
+     * });
+     *
+     * // one team's board at one past round
+     * const [board] = await callbacks.getPastState<Context>({
+     *     fromTick: day,
+     *     teams: 'team-1',
+     * });
+     * ```
+     */
+    getPastState: <T = Record<string, unknown>>(query: PastStateQuery<T>) => Promise<PastStateEntry<T>[]>;
+    /**
+     * Request a tick. Pass a `teamId` to tick a specific team (independent
+     * mode) or omit to tick all teams.
+     *
+     * Returns a promise that resolves once the tick(s) have finished and rejects
+     * with a `MutationError` when the tick cannot run. Safe to ignore.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.requestTick();           // all teams
+     * await callbacks.requestTick("team-1");   // specific team
+     * ```
+     */
+    requestTick: (teamId?: string) => Promise<void>;
+    /**
+     * Pause automatic ticking. Pass a `teamId` to pause a specific team
+     * or omit to pause all teams. Resolves once the host has applied it, and
+     * rejects with a `MutationError` when the host refuses it.
+     */
+    pauseTimer: (teamId?: string) => Promise<void>;
+    /**
+     * Resume automatic ticking after a pause. Pass a `teamId` to resume a
+     * specific team or omit to resume all teams. Resolves once the host has
+     * applied it, and rejects with a `MutationError` when the host refuses it.
+     */
+    resumeTimer: (teamId?: string) => Promise<void>;
+    /**
+     * Reset the game back to its initial state. Pass a `teamId` to reset a
+     * specific team or omit to reset the entire session. Returns a promise that
+     * resolves once the reset has completed and rejects with a `MutationError`
+     * on failure.
+     */
+    resetGame: (teamId?: string) => Promise<void>;
+    /**
+     * Undo the last tick. Pass a `teamId` to undo for a specific team or
+     * omit to undo for all teams. Returns a promise that resolves once the undo
+     * has completed and rejects with a `MutationError` on failure.
+     */
+    undoTick: (teamId?: string) => Promise<void>;
+    /**
+     * Move the deadline of the currently scheduled tick by `byMs`
+     * milliseconds. Positive buys the room more time; negative brings the deadline forward, clamped at
+     * now rather than firing retroactively. Pass a `teamId` to adjust one team
+     * or omit to adjust every team.
+     *
+     * This moves *this* tick only. The interval the tick controller returns for
+     * the ticks after it is untouched, so a session does not drift because a
+     * facilitator gave one round an extra two minutes. Read the result back
+     * from `useUserInterfaceTimer().extendedMs` rather than assuming the call
+     * won.
+     *
+     * Deliberately not bounded by the §11.8 tick floor and ceiling: those bound
+     * the cadence a tick controller may schedule, and a facilitator already
+     * reaches outside both with `requestTick` (immediate) and `pauseTimer`
+     * (indefinite).
+     *
+     * Rejects with a `MutationError` carrying `{ kind: 'denied' }` when there is
+     * no tick to move — automatic ticking is disabled, the game is complete, or
+     * the timer is paused — and when the host cannot schedule the result. A
+     * denial is terminal.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.extendTick(120_000);            // two more minutes, every team
+     * await callbacks.extendTick(120_000, 'team-1');  // just this team
+     * await callbacks.extendTick(-30_000);            // pull the deadline in 30 seconds
+     * ```
+     */
+    extendTick: (byMs: number, teamId?: string) => Promise<void>;
+    /**
+     * Ask the host to open one of its own overlays: the facilitator guide, a
+     * team's print sheet. The host renders it in its own chrome, above the
+     * surface, so this delegates the trigger and nothing else.
+     *
+     * `target` is the overlay's argument. A guide identifier for
+     * `'facilitator-guide'`, a team id for `'print-sheets'`; omitting it means
+     * the whole thing — the game's first declared guide, every team.
+     *
+     * Render a control only for an overlay in
+     * `useSessionUserInterfaceHostOverlays()`. Which overlays exist is the
+     * host's answer: a production host and the SDK's dev server do not offer
+     * the same set, and a button for one the host does not have is a button
+     * that cannot work.
+     *
+     * Rejects with a `MutationError` carrying `{ kind: 'denied' }` for an
+     * overlay this host does not offer, and for a `target` the active game does
+     * not declare. A denial is terminal.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.openHostOverlay('facilitator-guide');
+     * await callbacks.openHostOverlay('print-sheets', 'team-1');
+     * ```
+     */
+    openHostOverlay: (overlay: HostOverlay, target?: string) => Promise<void>;
+    /**
+     * Open or close the session's waiting room. While it is open, every player
+     * sees the game's waiting room UI instead of its game UIs; closing it swaps
+     * them back with no reload. Game state is untouched in both directions —
+     * per-team context, current tick, and timers all survive the toggle, which
+     * is the point: a facilitator can park a live session for a discussion and
+     * resume exactly where teams were.
+     *
+     * Alone among the session callbacks it takes no `teamId`: the waiting room
+     * is one flag for the whole session, so there is no per-team variant to
+     * target. Opening it does not stop the tick clock (see
+     * `TickControllerFunctionArgs.waitingRoomOpen` for how to do that).
+     *
+     * The host usually renders a waiting-room control in its own chrome too, so
+     * both writers exist by design. Read the resulting flag back from
+     * `useSessionUserInterfaceMeta().waitingRoomOpen` rather than assuming this
+     * call won.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.setWaitingRoom(true);   // park the session
+     * ```
+     */
+    setWaitingRoom: (open: boolean) => Promise<void>;
+    /**
+     * Throw the walkthrough away and start it again at tick 0 (§5.7).
+     *
+     * The walkthrough is a disposable second run of the game, used to
+     * demonstrate it: one team, one participant, isolated from this session in
+     * both directions. Resetting it is how a facilitator clears the decisions
+     * they entered while talking the room through, and since it always begins
+     * at tick 0 there is nothing else to undo.
+     *
+     * Rejects with a `MutationError` carrying `{ kind: 'denied' }` while the
+     * session has no walkthrough yet, since opening its link is what creates
+     * one and there is nothing to reset before then.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.resetWalkthrough();
+     * ```
+     */
+    resetWalkthrough: () => Promise<void>;
+    /**
+     * Add a team to the session. The host assigns the lowest unused team index
+     * and resolves the default name for that index when `name` is omitted.
+     *
+     * Rejects with a `MutationError` carrying `{ kind: 'denied' }` when the
+     * session is already at its maximum team count, when the session is
+     * shared-state (whose team count is fixed at creation), or when the
+     * session is read-only. The SDK's dev server relaxes the shared-state rule
+     * before the first tick as an authoring convenience; do not rely on it.
+     * A denial is terminal: retrying cannot succeed. Read
+     * `useSessionUserInterfaceTeamConfiguration()` to disable the control before
+     * the facilitator reaches it.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.createTeam('Marketing');
+     * ```
+     */
+    createTeam: (name?: string) => Promise<void>;
+    /**
+     * Rename a team. The new name reaches every surface through the team list.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.renameTeam('team-1', 'Marketing');
+     * ```
+     */
+    renameTeam: (teamId: string, name: string) => Promise<void>;
+    /**
+     * Rename a participant. The new name reaches every surface through the
+     * participant list.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.renameParticipant('participant-3', 'Sam');
+     * ```
+     */
+    renameParticipant: (participantId: string, name: string) => Promise<void>;
+    /**
+     * Reassign a participant to another team.
+     *
+     * The participant keeps their id but takes a fresh index within the
+     * destination team, and their open surfaces are remounted against that team
+     * (§13.2). Two consequences, which are easy to confuse:
+     *
+     * - **Their browser loses local component state**, because the surface
+     *   re-renders from scratch: a half-typed field, an uncommitted slider.
+     *   Ordinary remount behaviour, and rarely worth warning anyone about.
+     * - **Their earlier writes stay with the source team.** Anything they wrote
+     *   through `setData` is in that team's context and does not travel, so
+     *   they arrive with none of their own state and the source team keeps work
+     *   done by someone no longer on it.
+     *
+     * The second is what a game has to handle, and the mechanism is the
+     * `participantMove` hook: seed the destination on `phase: 'arrival'` the
+     * way `participantJoin` seeds a new participant. Note there is no transfer
+     * channel — a hook returns one team's context, so the departure hook's
+     * return value is invisible to arrival. A shared-state game carries state
+     * across through the shared store; an independent-mode game re-derives it
+     * from the payload and its own configuration. Where it genuinely cannot be
+     * re-derived, that is the case worth telling a facilitator about.
+     *
+     * A move does not reset either team: the source team's context, including
+     * every pending pre-tick decision in it, is untouched.
+     *
+     * Any write of theirs already in flight against the old team fails as
+     * denied rather than landing on either team.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.moveParticipant('participant-3', 'team-2');
+     * ```
+     */
+    moveParticipant: (participantId: string, teamId: string) => Promise<void>;
+    /**
+     * Delete a team from an independent-mode session. No other team's index or
+     * id changes, and the deleted team's index is left as a gap that the next
+     * `createTeam` takes back as a new team.
+     *
+     * Only an empty team can go: move every participant out with
+     * `moveParticipant` first, connected or not, because a participant is
+     * never erased. Rejects with a `MutationError` carrying `{ kind: 'denied' }`
+     * while the team has participants, in a shared-state session (whose
+     * cohort is fixed for the session), for the last team, for a team the
+     * session does not hold, and when the session is read-only. A denial is
+     * terminal: retrying cannot succeed. Read
+     * `useSessionUserInterfaceTeamConfiguration().mode` to offer the control
+     * only in independent mode.
+     *
+     * Example:
+     * ```typescript
+     * await callbacks.deleteTeam('team-3');
+     * ```
+     */
+    deleteTeam: (teamId: string) => Promise<void>;
+    /**
+     * Server-side endpoints declared by this UI's bundle. See
+     * {@link UserInterfaceCallbacks.endpoints} for details.
+     */
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    /**
+     * Set the host's theme preference. See
+     * {@link UserInterfaceCallbacks.setThemePreference} for details. Read the
+     * current value reactively with the matching theme-preference hook.
+     */
+    setThemePreference: (preference: ThemePreference) => void;
+}
+/**
+ * Error thrown when a resource invokes a callback it did not declare in its
+ * bundle's `uses` array. Carries the offending resource identifier and the
+ * callback name so a runtime can surface both to the operator.
+ */
+export declare class UndeclaredApiUseError extends Error {
+    readonly resourceIdentifier: string;
+    readonly api: ApiUse;
+    constructor(resourceIdentifier: string, api: ApiUse);
+}
+/**
+ * The {@link SignatureCallbacks} members that `uses` does not gate (§6.11).
+ *
+ * Runtime plumbing, and reads of state the resource already declared, rather
+ * than externally-visible APIs an operator gates access to. They are always
+ * present, so a generated `Callbacks` type has to carry them: without this the
+ * runtime passed them and no author could see them, which is how `readAsset`
+ * came to be reachable in principle and used nowhere.
+ */
+export type UngatedSignatureCallbacks = Pick<SignatureCallbacks, 'readAsset' | 'getPastState'>;
+/**
+ * The callbacks a logic-bearing resource actually receives: the gated ones it
+ * declared in `uses`, plus the ungated ones it gets regardless.
+ *
+ * Every declared service is required here, never optional: a runtime that
+ * cannot provide one refuses the package at load (§6.11), so a resource that
+ * declared `generateText` calls `callbacks.generateText(...)` directly. A
+ * service it did not declare is not in the type at all.
+ *
+ * This is what each resource's generated `types.ts` aliases its `Callbacks` to.
+ * It exists as a named helper rather than being spelled out as an intersection
+ * at every call site because the spelled-out form is what an author reads first
+ * when asking what their handler is handed, and 'a Pick intersected with a
+ * Required Pick' answers that question badly.
+ */
+export type LogicCallbacks<Uses extends ApiUse = never> = Required<Pick<SignatureCallbacks, Uses>> & UngatedSignatureCallbacks;
+/**
+ * Callbacks available to a settings editor: the `setup` and `scenario_editor`
+ * slots, which share one wrapper (§6.5).
+ */
+export interface SettingsEditorCallbacks {
+    /**
+     * Upload a file as a blob. Returns a `blob:`-prefixed reference that can
+     * be stored in a setting and later resolved via `getAssetUrl` or
+     * `readAsset`. Uploads from a settings editor survive game resets and are
+     * wiped only when the session is re-initialised; the host assigns this
+     * lifecycle from the UI type.
+     *
+     * Example:
+     * ```typescript
+     * const reference = await callbacks.uploadBlob(file);
+     * ```
+     */
+    uploadBlob: (file: File) => Promise<string>;
+    /**
+     * Resolve an asset reference to a URL. Accepts either an
+     * `asset:<path>` or `blob:<id>` reference.
+     *
+     * Example:
+     * ```typescript
+     * const url = callbacks.getAssetUrl("blob:abc123");
+     * // <img src={url} />
+     * ```
+     */
+    getAssetUrl: (reference: string) => string;
+    /**
+     * Read the bytes of an asset by reference.
+     *
+     * Example:
+     * ```typescript
+     * const file = await callbacks.readAsset("blob:abc123");
+     * ```
+     */
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    /**
+     * Request the game to leave the configuration step and start play.
+     * Equivalent to the operator clicking the host-side Play button, which is
+     * always rendered (SPECIFICATION.md §8.3). Send this from a finish control
+     * of your own when the form wants one; it is never the only way out, so a
+     * bug here cannot strand a facilitator on the configuration step.
+     *
+     * Meaningful in the `setup` slot only. A scenario editor has no session
+     * to start, so the host refuses it from there (§6.5).
+     *
+     * Example:
+     * ```typescript
+     * callbacks.requestPlay();
+     * ```
+     */
+    requestPlay: () => void;
+    /**
+     * Server-side endpoints declared by this UI's bundle. See
+     * {@link UserInterfaceCallbacks.endpoints} for details.
+     */
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    /**
+     * Set the host's theme preference. See
+     * {@link UserInterfaceCallbacks.setThemePreference} for details. Read the
+     * current value reactively with the matching theme-preference hook.
+     */
+    setThemePreference: (preference: ThemePreference) => void;
+}