@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/docs/api/sdk.md

@@ -0,0 +1,2140 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk`
+
+Every export of `@seriousgaming/sdk`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
+
+## Functions
+
+### decodeUtf8
+
+Decode a UTF-8 byte sequence to a string.
+
+```ts
+function decodeUtf8(bytes: Uint8Array): string;
+```
+
+### deriveSeed
+
+Derive a stable seed from a session seed and whatever identifies the thing being seeded.
+
+```ts
+function deriveSeed(...parts: (string | number)[]): string;
+```
+
+### encodeUtf8
+
+Encode a string to its UTF-8 byte sequence.
+
+```ts
+function encodeUtf8(input: string): Uint8Array;
+```
+
+### getText
+
+Helper for the common case where a caller just wants the assistant's text. Returns the concatenation of every `text` block in the response; `toolUse` blocks are skipped.
+
+```ts
+function getText(response: LLMResponse): string;
+```
+
+### intervalTick
+
+Convenience builder that creates a `TickControllerResult` for interval-based (cadence) ticking — the sanctioned way to return an interval result.
+
+```ts
+function intervalTick(
+    intervalMs: number,
+    options?: {
+        complete?: boolean;
+    }
+): TickControllerResult;
+```
+
+### nextDailyAt
+
+Compute the next occurrence of a daily time.
+
+```ts
+function nextDailyAt(hours: number, minutes: number, options?: ScheduleOptions): number;
+```
+
+### nextDailyFromSchedule
+
+Pick the soonest future time from a list of daily times.
+
+```ts
+function nextDailyFromSchedule(
+    times: Array<{
+        hours: number;
+        minutes: number;
+    }>,
+    options?: ScheduleOptions
+): number;
+```
+
+### nextWeeklyAt
+
+Compute the next occurrence of a weekly time.
+
+```ts
+function nextWeeklyAt(
+    dayOfWeek: number,
+    hours: number,
+    minutes: number,
+    options?: ScheduleOptions
+): number;
+```
+
+### scheduledTick
+
+Convenience builder that creates a `TickControllerResult` for scheduled (absolute-time) ticking.
+
+```ts
+function scheduledTick(
+    nextTickAt: number,
+    options?: {
+        complete?: boolean;
+    }
+): TickControllerResult;
+```
+
+### seededRandom
+
+A seeded pseudo-random generator: call it for the next value in `[0, 1)`, like `Math.random()`.
+
+```ts
+function seededRandom(seed: string): () => number;
+```
+
+## Classes
+
+### EndpointError
+
+Error a surface's endpoint call (`callbacks.endpoints.<id>(request)`) rejects with. Inspect `outcome` (or the shorthand `kind`) for why, and `applied` for what had already changed.
+
+```ts
+class EndpointError extends Error {
+    readonly outcome: EndpointFailureOutcome;
+    readonly applied: EffectStep[];
+    readonly failedStep?: EffectStep;
+    constructor(failure: EndpointFailure);
+    get kind(): EndpointFailureOutcome['kind'];
+    get failure(): EndpointFailure;
+}
+```
+
+### UndeclaredApiUseError
+
+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.
+
+```ts
+class UndeclaredApiUseError extends Error {
+    readonly resourceIdentifier: string;
+    readonly api: ApiUse;
+    constructor(resourceIdentifier: string, api: ApiUse);
+}
+```
+
+## Interfaces
+
+### AggregateFunctionShared
+
+The session's shared store, as an aggregate function sees it: one value per shared-scope capability the engine declared, whatever the number of teams.
+
+```ts
+interface AggregateFunctionShared<TSharedContext, TSharedState = never> {
+    context: TSharedContext;
+    state?: TSharedState;
+}
+```
+
+### AggregateFunctionTeam
+
+```ts
+interface AggregateFunctionTeam<TTeamContext, TTeamState = never> {
+    teamId: string;
+    index: number;
+    context: TTeamContext;
+    state?: TTeamState;
+}
+```
+
+### CapabilityDefinition
+
+Definition of a capability
+
+```ts
+interface CapabilityDefinition {
+    identifier: string;
+    variablesSchema: {
+        [k: string]: unknown;
+    };
+    scope?: 'team' | 'team-readable' | 'shared' | 'private';
+    lifetime?: 'tick' | 'session';
+}
+```
+
+### EndpointBaseArgs
+
+The arguments every endpoint receives, whatever its scope.
+
+```ts
+interface EndpointBaseArgs<
+    TRequest,
+    TContext,
+    TCallbacks = SignatureCallbacks,
+    TSettings = Record<string, never>,
+> {
+    request: TRequest;
+    context: TContext;
+    callbacks: TCallbacks;
+    caller: EndpointCaller;
+    settings: TSettings;
+    meta: LogicMeta;
+    participants: readonly Readonly<Participant>[];
+    session: EndpointSession;
+}
+```
+
+### EndpointCaller
+
+Host-issued identity of the caller invoking an endpoint. Every field is set by the host from session bookkeeping — iframe-supplied values are never part of the trust chain.
+
+```ts
+interface EndpointCaller {
+    sessionId?: string;
+    teamId?: string;
+    playerId?: string;
+    role: EndpointCallerRole;
+    userInterfaceIdentifier?: string;
+    principal?: EndpointPrincipal;
+}
+```
+
+### EndpointDefinition
+
+Definition of an endpoint — a named, server-side handler that user interfaces, and callers outside the game when its visibility is external, invoke by identifier. Endpoints validate structured requests and responses against declared schemas, and operate strictly within the bounds of their declared `reads`, `writes` and `uses`.
+
+```ts
+interface EndpointDefinition {
+    identifier: string;
+    displayName?: string;
+    description?: string;
+    scope?: 'session' | 'team';
+    requestSchema: {
+        [k: string]: unknown;
+    };
+    responseSchema: {
+        [k: string]: unknown;
+    };
+    reads?: string[];
+    settings?: string[];
+    writes?: string[];
+    uses?: ApiUse[];
+    actions?: EndpointActionType[];
+    responds?: boolean;
+    roster?: boolean;
+    visibility?: 'internal' | 'external';
+}
+```
+
+### EndpointFailure
+
+A failed endpoint call, itemised so a caller can tell 'nothing happened' from 'the writes landed, then an action failed'.
+
+```ts
+interface EndpointFailure {
+    outcome: EndpointFailureOutcome;
+    applied: EffectStep[];
+    failedStep?: EffectStep;
+}
+```
+
+### EndpointOutcome
+
+What one of `Plan`'s actions came to, for `Respond`.
+
+```ts
+interface EndpointOutcome {
+    type: EndpointActionType;
+    committedAtTick?: number;
+}
+```
+
+### EndpointPrincipal
+
+The host's account of who made an `external` call.
+
+```ts
+interface EndpointPrincipal {
+    kind: string;
+    id: string;
+    name?: string;
+}
+```
+
+### EndpointResult
+
+What an endpoint that declares `actions`, or a session-scoped endpoint that writes team capabilities, returns.
+
+```ts
+interface EndpointResult<
+    TResponse,
+    TWrites = never,
+    TAction extends EndpointAction = never,
+    TTeamWrites = never,
+> {
+    response: TResponse;
+    capabilities?: TWrites;
+    deletes?: ContextDeletePath[];
+    teams?: Record<string, TTeamWrites>;
+    actions?: TAction[];
+}
+```
+
+### EndpointSession
+
+Where the session stands when an endpoint is called.
+
+```ts
+interface EndpointSession {
+    mode: SessionMode;
+    completedTicks: number;
+    maxTicks: number | null;
+    waitingRoomOpen: boolean;
+    complete: boolean;
+    teams: EndpointTeamStatus[];
+}
+```
+
+### EndpointTeamEntry
+
+One team's values, for a session-scoped endpoint.
+
+```ts
+interface EndpointTeamEntry<TContext> extends TeamInfo {
+    context: TContext;
+}
+```
+
+### EndpointTeamStatus
+
+One team's standing, for `EndpointSession`.
+
+```ts
+interface EndpointTeamStatus extends TeamInfo {
+    completedTicks: number;
+    complete: boolean;
+    timer: TimerState | null;
+    participants?: Participant[];
+}
+```
+
+### EndpointWriteResult
+
+What an endpoint that declares `writes` returns: the response its caller receives, and the state it changes.
+
+```ts
+interface EndpointWriteResult<TResponse, TWrites> {
+    response: TResponse;
+    capabilities: TWrites;
+    deletes?: ContextDeletePath[];
+}
+```
+
+### EngineDefinition
+
+Definition of a game's engine: the logic that computes each tick
+
+```ts
+interface EngineDefinition {
+    identifier: string;
+    reads?: string[];
+    writes?: string[];
+    uses?: ApiUse[];
+    settings?: string[];
+    aggregate?: boolean;
+}
+```
+
+### EngineFunctionArgs
+
+The arguments of the engine's own functions: everything logic receives, plus the engine's private memory.
+
+```ts
+interface EngineFunctionArgs<
+    TContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+    TState = never,
+> extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
+    state?: TState;
+}
+```
+
+### EngineResult
+
+What the engine's `Init` and `Run` return: the capabilities they write and, optionally, the engine's private memory.
+
+```ts
+interface EngineResult<TContext, TState = never> extends LogicResult<TContext> {
+    state?: TState;
+}
+```
+
+### ExtractTextResponse
+
+Response from extracting text from a document
+
+```ts
+interface ExtractTextResponse {
+    content: string;
+    mimeType: string;
+}
+```
+
+### FacilitatorGuideDefinition
+
+Definition of a facilitator guide — bundled markdown content rendered natively by the host on the facilitator's page
+
+```ts
+interface FacilitatorGuideDefinition {
+    identifier: string;
+    locales: {
+        [k: string]: {
+            name: string;
+        };
+    };
+}
+```
+
+### GameDefinition
+
+Definition of a game with internationalization support
+
+```ts
+interface GameDefinition {
+    identifier: string;
+    supportedLocales: GameSupportedLocales;
+    locales: GameLocales;
+    customScenarios?: GameCustomScenarios;
+    teams?: {
+        mode?: GameTeamMode;
+    };
+}
+```
+
+### GameSettingConstraint
+
+How a game narrows one of its `game` settings. Each keyword may only narrow the SDK's schema: a `minimum` or `maximum` applies to a number and also rules out null, an `enum` lists values the SDK's schema accepts, and `readOnly` fixes the value at the game's own, so no scenario or session may change it.
+
+```ts
+interface GameSettingConstraint {
+    minimum?: number;
+    maximum?: number;
+    enum?: [unknown, ...unknown[]];
+    readOnly?: boolean;
+}
+```
+
+### GameSettings
+
+The values of the built-in `game` settings resource: the game-level settings every game has. Its schema is the SDK's, not the game's: a game sets its own values in its manifest, which become this resource's defaults, and a scenario or a session overrides them under the identifier `game` like any other settings resource. Null means 'no limit' or 'no guidance'. A new game-level setting joins as a new optional property with a default.
+
+```ts
+interface GameSettings {
+    maxTicks?: number | null;
+    teams?: {
+        min?: number | null;
+        max?: number | null;
+        perTeam?: {
+            minParticipants?: number | null;
+            maxParticipants?: number | null;
+        };
+        defaultNames?: {
+            [k: string]: {
+                name: string;
+            };
+        }[];
+    };
+    waitingRoom?: {
+        openOnStart?: boolean;
+    };
+}
+```
+
+### GameSettingsConstraints
+
+Narrowing for the built-in `game` settings, in their shape. The build merges each constraint into the `game` settings schema it emits, so a runtime sees one ordinary schema. Adding a constraint is a scenario-format change.
+
+```ts
+interface GameSettingsConstraints {
+    maxTicks?: GameSettingConstraint;
+    teams?: {
+        min?: GameSettingConstraint;
+        max?: GameSettingConstraint;
+        perTeam?: {
+            minParticipants?: GameSettingConstraint;
+            maxParticipants?: GameSettingConstraint;
+        };
+        defaultNames?: GameSettingConstraint;
+    };
+    waitingRoom?: {
+        openOnStart?: GameSettingConstraint;
+    };
+}
+```
+
+### GenerateSpeechRequest
+
+Options for synthesising speech.
+
+```ts
+interface GenerateSpeechRequest {
+    text: string;
+    voice?: GenerateSpeechVoice | string;
+    tier?: LLMTier;
+    format?: GenerateSpeechFormat;
+    languageHint?: string;
+    speed?: number;
+}
+```
+
+### GenerateSpeechResponse
+
+Response from a speech-synthesis call. The audio bytes are persisted as a blob; play them from a UI via `<audio src={callbacks.getAssetUrl(reference)} />` or read the raw bytes in the engine via `callbacks.readAsset(reference)`.
+
+```ts
+interface GenerateSpeechResponse {
+    reference: string;
+    mimeType: string;
+    durationMs?: number;
+    charactersBilled?: number;
+}
+```
+
+### GlobalSettings
+
+User-owned global settings file (~/.seriousgaming-sdk/config.json). Stores API keys and defaults once so every project picks them up. This is the lowest-priority configuration source: .env files, environment variables, and CLI flags all override it. The file is plaintext and must not be committed to git.
+
+```ts
+interface GlobalSettings {
+    elevenLabs?: {
+        apiKey?: string;
+    };
+    platform?: {
+        apiHost?: string;
+        apiKey?: string;
+        defaultPublisher?: string;
+    };
+}
+```
+
+### HookDefinition
+
+Definition of a hook — a single-signal handler that runs in response to an out-of-tick lifecycle event
+
+```ts
+interface HookDefinition {
+    identifier: string;
+    signal: 'participantJoin' | 'participantMove';
+    reads?: string[];
+    writes?: string[];
+    uses?: ApiUse[];
+    settings?: string[];
+}
+```
+
+### HookPayloadMap
+
+Maps each hook signal to its payload shape. Adding a new signal extends this map; the `HookFunction` type then surfaces the new payload fields automatically.
+
+```ts
+interface HookPayloadMap {
+    participantJoin: {
+        participant: Participant;
+    };
+    participantMove: {
+        participant: Participant;
+        fromTeamId: string;
+        toTeamId: string;
+        phase: 'departure' | 'arrival';
+    };
+}
+```
+
+### JSONSchema
+
+JSON Schema for requesting structured responses from the LLM Follows the JSON Schema specification
+
+```ts
+interface JSONSchema {
+    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    description?: string;
+    items?: JSONSchema;
+    enum?: unknown[];
+    default?: unknown;
+    [key: string]: unknown;
+}
+```
+
+### LLMGenerateOptions
+
+Options for generating text with an LLM
+
+```ts
+interface LLMGenerateOptions {
+    prompt?: string;
+    messages?: LLMMessage[];
+    systemPrompt?: string;
+    jsonSchema?: JSONSchema;
+    tier?: LLMTier;
+    tools?: LLMTool[];
+}
+```
+
+### LLMMessage
+
+A message in a conversation with an LLM.
+
+```ts
+interface LLMMessage {
+    role: 'user' | 'assistant';
+    content: string | ContentBlock[];
+}
+```
+
+### LLMResponse
+
+Response from the LLM.
+
+```ts
+interface LLMResponse {
+    content: ContentBlock[];
+    stopReason: LLMStopReason;
+    usage?: LLMUsage;
+}
+```
+
+### LLMTool
+
+A tool the model may invoke. The model never executes anything itself — when it emits a `toolUse` content block, the caller runs the tool in its own code and feeds the result back via a `toolResult` block on the next turn.
+
+```ts
+interface LLMTool {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+```
+
+### LLMUsage
+
+Token usage reported by the LLM provider for one generation call.
+
+```ts
+interface LLMUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+```
+
+### LogicFunctionArgs
+
+```ts
+interface LogicFunctionArgs<TContext, TSettings, TCallbacks = SignatureCallbacks> {
+    context: TContext;
+    settings: TSettings;
+    meta: TeamRunMeta;
+    participants: readonly Readonly<Participant>[];
+    callbacks: TCallbacks;
+}
+```
+
+### LogicLayout
+
+Where a logic-bearing resource keeps its code, and what its entrypoint is called
+
+```ts
+interface LogicLayout {
+    directory: string;
+    entrypoint: string;
+}
+```
+
+### LogicMeta
+
+The facts true of the whole run, delivered to every call into game logic whether it runs inside the tick loop or outside it.
+
+```ts
+interface LogicMeta {
+    locale: string;
+    seed: string;
+    runKind: RunKind;
+    now: number;
+}
+```
+
+### LogicResult
+
+What engine and hook logic returns: the state it writes, named by kind.
+
+```ts
+interface LogicResult<TContext> {
+    capabilities: TContext;
+    deletes?: ContextDeletePath[];
+}
+```
+
+### PackageDefinition
+
+Definition of a package
+
+```ts
+interface PackageDefinition {
+    identifier: string;
+    name: string;
+    version: string;
+}
+```
+
+### PackageManifest
+
+A package, which is a game: its identifier and the game's settings. What it declares are the resources on disk under the conventional directories beside this file. The version comes from package.json, and the game's identifier is the package identifier with `.game` appended.
+
+```ts
+interface PackageManifest {
+    identifier: string;
+    requires?: RequiredFeatures;
+    scenarioFormat?: ScenarioFormat;
+    supportedLocales: GameSupportedLocales;
+    locales: GameLocales;
+    maxTicks?: number;
+    teams?: GameTeams;
+    waitingRoom?: GameWaitingRoomSettings;
+    gameSettingsConstraints?: GameSettingsConstraints;
+    customScenarios?: GameCustomScenarios;
+}
+```
+
+### Participant
+
+A participant the platform tracks for some team in the session.
+
+```ts
+interface Participant {
+    id: string;
+    name: string;
+    index: number;
+    connected: boolean;
+    teamId: string;
+}
+```
+
+### PastStateEntry
+
+```ts
+interface PastStateEntry<T = Record<string, unknown>> extends TeamStateEntry<T> {
+    tick: number;
+    recordedAt: number;
+    complete: boolean;
+}
+```
+
+### PastStateQuery
+
+What to read from the past.
+
+```ts
+interface PastStateQuery<T = Record<string, unknown>> {
+    fromTick: number;
+    toTick?: number;
+    teams?: 'own' | 'all' | string;
+    capabilityIds?: (keyof T & string)[];
+}
+```
+
+### PresentationDefinition
+
+Definition of a presentation: the slides a facilitator shows the room, rendered from a UI bundle of the game's own. Read-only by construction: it declares no writes, no endpoints and no callback uses, and it may be shown with no session at all
+
+```ts
+interface PresentationDefinition {
+    identifier: string;
+    locales?: {
+        [k: string]: {
+            name: string;
+        };
+    };
+    reads?: string[];
+    settings?: string[];
+}
+```
+
+### ReadAssetResponse
+
+Shape returned by `readAsset` for both `asset:` and `blob:` references.
+
+```ts
+interface ReadAssetResponse {
+    data: Uint8Array;
+    mimeType: string;
+    name: string;
+}
+```
+
+### RequestTickFunctionArgs
+
+Arguments of a validator's `RequestTick` gate.
+
+```ts
+interface RequestTickFunctionArgs<TContext, TSettings> {
+    context: TContext;
+    requestedTick: number;
+    actor: ValidatorActor;
+    settings: TSettings;
+    meta: LogicMeta;
+    participants: readonly Readonly<Participant>[];
+}
+```
+
+### ResolvedPackageManifest
+
+Every resource a package holds: the shape the loader builds from disk and the shape the build writes to seriousgaming.json. A game holds one of nine kinds, each in its own field; everything a package may hold more than one of is an array.
+
+```ts
+interface ResolvedPackageManifest {
+    manifestVersion?: number;
+    requires?: RequiredFeatures;
+    scenarioFormat?: ScenarioFormat;
+    package: SDKPackage;
+    game: SDKGame;
+    engine?: SDKEngine;
+    ui?: SDKUserInterface;
+    session?: SDKSessionUserInterface;
+    waiting_room?: SDKWaitingRoomUserInterface;
+    presentation?: SDKPresentation;
+    setup?: SDKSetup;
+    scenario_editor?: SDKScenarioEditor;
+    tick_controller?: SDKTickController;
+    guide?: SDKFacilitatorGuide;
+    capabilities?: SDKCapability[];
+    settings?: SDKSettings[];
+    scenarios?: SDKScenario[];
+    hooks?: SDKHook[];
+    validators?: SDKValidator[];
+    endpoints?: SDKEndpoint[];
+}
+```
+
+### RunAggregateFunctionArgs
+
+```ts
+interface RunAggregateFunctionArgs<
+    TTeamContext,
+    TSharedContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+    TTeamState = never,
+    TSharedState = never,
+> {
+    shared: AggregateFunctionShared<TSharedContext, TSharedState>;
+    teams: AggregateFunctionTeam<TTeamContext, TTeamState>[];
+    settings: TSettings;
+    meta: RunMeta;
+    participants: readonly Readonly<Participant>[];
+    callbacks: TCallbacks;
+}
+```
+
+### RunAggregateResult
+
+An aggregate engine's result. Each level names what it writes the same way a team's `Run` does: every `teams` entry has the shape of a `Run` result, in the order the teams were passed, and `shared` carries the session's shared-scope capabilities. A shared capability is written through `shared` alone; one in a `teams` entry fails the call.
+
+```ts
+interface RunAggregateResult<
+    TTeamContext,
+    TSharedContext,
+    TTeamState = never,
+    TSharedState = never,
+> {
+    shared: EngineResult<Partial<TSharedContext>, TSharedState>;
+    teams: EngineResult<TTeamContext, TTeamState>[];
+}
+```
+
+### RunAggregateTickResult
+
+`RunAggregate`'s result: each level may also report completion, as `Run`'s `complete` does. A `teams` entry's ends the game for that team; `shared`'s for every team at once.
+
+```ts
+interface RunAggregateTickResult<
+    TTeamContext,
+    TSharedContext,
+    TTeamState = never,
+    TSharedState = never,
+> {
+    shared: RunResult<Partial<TSharedContext>, TSharedState>;
+    teams: RunResult<TTeamContext, TTeamState>[];
+}
+```
+
+### RunMeta
+
+`meta` for logic that runs as part of a tick: the engine's `Init` and `Run`, the aggregate forms of both, and tick-controller logic.
+
+```ts
+interface RunMeta extends LogicMeta {
+    tick: number;
+}
+```
+
+### RunResult
+
+What the engine's `Run` returns: an `EngineResult`, plus whether the game is now over for this team.
+
+```ts
+interface RunResult<TContext, TState = never> extends EngineResult<TContext, TState> {
+    complete?: boolean;
+}
+```
+
+### ScenarioDefinition
+
+Definition of a scenario — a named flavour of a game bundling settings overrides and static assets
+
+```ts
+interface ScenarioDefinition {
+    identifier: string;
+    locales: {
+        [k: string]: {
+            name: string;
+            description?: string;
+        };
+    };
+    default?: boolean;
+    restricted?: boolean;
+    settings?: {
+        [k: string]: {
+            [k: string]: unknown;
+        };
+    };
+}
+```
+
+### ScenarioEditorDefinition
+
+Definition of the game's scenario editor: an authoring screen, used at any time and with no session, whose output is a lasting scenario. Optional: `customScenarios.supported` is what switches custom scenarios on
+
+```ts
+interface ScenarioEditorDefinition {
+    identifier: string;
+    configures?: string[];
+    endpoints?: string[];
+}
+```
+
+### ScheduleOptions
+
+Options accepted by all schedule-computation helpers.
+
+```ts
+interface ScheduleOptions {
+    timezone?: string;
+    now?: number;
+}
+```
+
+### Schema
+
+```ts
+interface Schema {
+    PackageDefinition?: PackageDefinition;
+    EngineDefinition?: EngineDefinition;
+    CapabilityDefinition?: CapabilityDefinition;
+    SettingsDefinition?: SettingsDefinition;
+    SDKSettings?: SDKSettings;
+    SetupDefinition?: SetupDefinition;
+    ScenarioEditorDefinition?: ScenarioEditorDefinition;
+    ScenarioDefinition?: ScenarioDefinition;
+    UserInterfaceDefinition?: UserInterfaceDefinition;
+    GameDefinition?: GameDefinition;
+    SessionUserInterfaceDefinition?: SessionUserInterfaceDefinition;
+    SDKSessionUserInterface?: SDKSessionUserInterface;
+    WaitingRoomUserInterfaceDefinition?: WaitingRoomUserInterfaceDefinition;
+    SDKWaitingRoomUserInterface?: SDKWaitingRoomUserInterface;
+    PresentationDefinition?: PresentationDefinition;
+    SDKPresentation?: SDKPresentation;
+    GameSupportedLocales?: GameSupportedLocales;
+    GameLocales?: GameLocales;
+    GameCustomScenarios?: GameCustomScenarios;
+    GameTeams?: GameTeams;
+    GameTeamMode?: GameTeamMode;
+    GameSettings?: GameSettings;
+    GameSettingConstraint?: GameSettingConstraint;
+    GameSettingsConstraints?: GameSettingsConstraints;
+    GameWaitingRoomOpenOnStart?: GameWaitingRoomOpenOnStart;
+    GameWaitingRoomSettings?: GameWaitingRoomSettings;
+    FacilitatorGuideDefinition?: FacilitatorGuideDefinition;
+    SDKFacilitatorGuide?: SDKFacilitatorGuide;
+    ResolvedPackageManifest?: ResolvedPackageManifest;
+    LogicLayout?: LogicLayout;
+    SDKPackage?: SDKPackage;
+    SDKEngine?: SDKEngine;
+    SDKCapability?: SDKCapability;
+    SDKScenario?: SDKScenario;
+    SDKUserInterface?: SDKUserInterface;
+    SDKSetup?: SDKSetup;
+    SDKScenarioEditor?: SDKScenarioEditor;
+    SDKGame?: SDKGame;
+    PackageManifest?: PackageManifest;
+    TickControllerDefinition?: TickControllerDefinition;
+    SDKTickController?: SDKTickController;
+    ApiUse?: ApiUse;
+    EndpointActionType?: EndpointActionType;
+    GlobalSettings?: GlobalSettings;
+    HookSignal?: HookSignal;
+    HookDefinition?: HookDefinition;
+    SDKHook?: SDKHook;
+    ValidatorDefinition?: ValidatorDefinition;
+    SDKValidator?: SDKValidator;
+    EndpointDefinition?: EndpointDefinition;
+    SDKEndpoint?: SDKEndpoint;
+}
+```
+
+### SDKCapability
+
+Bundle containing a capability definition
+
+```ts
+interface SDKCapability {
+    definition: CapabilityDefinition;
+}
+```
+
+### SDKEndpoint
+
+Bundle containing an endpoint definition and its logic layout
+
+```ts
+interface SDKEndpoint {
+    definition: EndpointDefinition;
+    logic: LogicLayout;
+    rootDirectory: string;
+}
+```
+
+### SDKEngine
+
+Bundle containing an engine definition and its logic layout
+
+```ts
+interface SDKEngine {
+    definition: EngineDefinition;
+    logic: LogicLayout;
+    rootDirectory: string;
+}
+```
+
+### SDKFacilitatorGuide
+
+Bundle containing a facilitator guide definition and root directory for content and assets
+
+```ts
+interface SDKFacilitatorGuide {
+    definition: FacilitatorGuideDefinition;
+    rootDirectory: string;
+}
+```
+
+### SDKGame
+
+Bundle containing a game definition
+
+```ts
+interface SDKGame {
+    definition: GameDefinition;
+    rootDirectory: string;
+}
+```
+
+### SDKHook
+
+Bundle containing a hook definition and its logic layout
+
+```ts
+interface SDKHook {
+    definition: HookDefinition;
+    logic: LogicLayout;
+    rootDirectory: string;
+}
+```
+
+### SDKPackage
+
+Bundle containing a package definition
+
+```ts
+interface SDKPackage {
+    definition: PackageDefinition;
+}
+```
+
+### SDKPresentation
+
+Bundle containing a presentation definition and entrypoint
+
+```ts
+interface SDKPresentation {
+    definition: PresentationDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SDKScenario
+
+Bundle containing a scenario definition and root directory for assets
+
+```ts
+interface SDKScenario {
+    definition: ScenarioDefinition;
+    rootDirectory: string;
+}
+```
+
+### SDKScenarioEditor
+
+Bundle containing the scenario editor definition and entrypoint
+
+```ts
+interface SDKScenarioEditor {
+    definition: ScenarioEditorDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SDKSessionUserInterface
+
+Bundle containing a session user interface definition and entrypoint
+
+```ts
+interface SDKSessionUserInterface {
+    definition: SessionUserInterfaceDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SDKSettings
+
+Bundle containing a settings definition
+
+```ts
+interface SDKSettings {
+    definition: SettingsDefinition;
+}
+```
+
+### SDKSetup
+
+Bundle containing the setup user interface definition and entrypoint
+
+```ts
+interface SDKSetup {
+    definition: SetupDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SDKTickController
+
+Bundle containing a tick controller definition and its logic layout
+
+```ts
+interface SDKTickController {
+    definition: TickControllerDefinition;
+    logic: LogicLayout;
+    rootDirectory: string;
+}
+```
+
+### SDKUserInterface
+
+Bundle containing a user interface definition and entrypoint
+
+```ts
+interface SDKUserInterface {
+    definition: UserInterfaceDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SDKValidator
+
+Bundle containing a validator definition and its logic layout
+
+```ts
+interface SDKValidator {
+    definition: ValidatorDefinition;
+    logic: LogicLayout;
+    rootDirectory: string;
+}
+```
+
+### SDKWaitingRoomUserInterface
+
+Bundle containing a waiting room user interface definition and entrypoint
+
+```ts
+interface SDKWaitingRoomUserInterface {
+    definition: WaitingRoomUserInterfaceDefinition;
+    rootDirectory: string;
+    ui: {
+        entrypoint: string;
+    };
+}
+```
+
+### SessionEndpointArgs
+
+What a session-scoped endpoint receives beyond the base arguments.
+
+```ts
+interface SessionEndpointArgs<TTeamContext> {
+    teams?: EndpointTeamEntry<TTeamContext>[];
+}
+```
+
+### SessionUserInterfaceCallbacks
+
+Callbacks available to session user interface components.
+
+```ts
+interface SessionUserInterfaceCallbacks {
+    uploadBlob: (file: File) => Promise<string>;
+    getAssetUrl: (reference: string) => string;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    getPastState: <T = Record<string, unknown>>(
+        query: PastStateQuery<T>
+    ) => Promise<PastStateEntry<T>[]>;
+    requestTick: (teamId?: string) => Promise<void>;
+    pauseTimer: (teamId?: string) => Promise<void>;
+    resumeTimer: (teamId?: string) => Promise<void>;
+    resetGame: (teamId?: string) => Promise<void>;
+    undoTick: (teamId?: string) => Promise<void>;
+    extendTick: (byMs: number, teamId?: string) => Promise<void>;
+    openHostOverlay: (overlay: HostOverlay, target?: string) => Promise<void>;
+    setWaitingRoom: (open: boolean) => Promise<void>;
+    resetWalkthrough: () => Promise<void>;
+    createTeam: (name?: string) => Promise<void>;
+    renameTeam: (teamId: string, name: string) => Promise<void>;
+    renameParticipant: (participantId: string, name: string) => Promise<void>;
+    moveParticipant: (participantId: string, teamId: string) => Promise<void>;
+    deleteTeam: (teamId: string) => Promise<void>;
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    setThemePreference: (preference: ThemePreference) => void;
+}
+```
+
+### SessionUserInterfaceDefinition
+
+Definition of a session user interface with internationalization support
+
+```ts
+interface SessionUserInterfaceDefinition {
+    identifier: string;
+    reads?: string[];
+    writes?: string[];
+    endpoints?: string[];
+    settings?: string[];
+}
+```
+
+### SettingsDefinition
+
+Definition of a settings resource: named, read-only parameters a game declares once and any resource may read by listing it in its settings. Overridden only by the active scenario and by the session's setup step, and fixed when play starts.
+
+```ts
+interface SettingsDefinition {
+    identifier: string;
+    settingsSchema: {
+        [k: string]: unknown;
+    };
+}
+```
+
+### SettingsEditorCallbacks
+
+Callbacks available to a settings editor: the `setup` and `scenario_editor` slots, which share one wrapper.
+
+```ts
+interface SettingsEditorCallbacks {
+    uploadBlob: (file: File) => Promise<string>;
+    getAssetUrl: (reference: string) => string;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    requestPlay: () => void;
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    setThemePreference: (preference: ThemePreference) => void;
+}
+```
+
+### SetupDefinition
+
+Definition of the game's setup user interface: a small form shown at session creation, whose changes become session overrides for that session only. Its presence is what gives a session its configuration step
+
+```ts
+interface SetupDefinition {
+    identifier: string;
+    configures?: string[];
+    endpoints?: string[];
+}
+```
+
+### SignatureCallbacks
+
+Every callback a runtime may offer logic: the engine, hooks, tick controllers and endpoints.
+
+```ts
+interface SignatureCallbacks {
+    generateText: LLMGenerateFunction;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    getPastState: <T = Record<string, unknown>>(
+        query: PastStateQuery<T>
+    ) => Promise<PastStateEntry<T>[]>;
+    extractText?: ExtractTextFunction;
+    generateSpeech?: GenerateSpeechFunction;
+    writeBlob?: (
+        data: Uint8Array | ArrayBuffer,
+        options: {
+            name: string;
+            mimeType: string;
+            retention?: 'settings' | 'game';
+        }
+    ) => Promise<string>;
+}
+```
+
+### TeamEndpointArgs
+
+What a team-scoped endpoint receives beyond the base arguments.
+
+```ts
+interface TeamEndpointArgs {
+    team: TeamInfo;
+}
+```
+
+### TeamInfo
+
+Who a team is: the fields every team entry in the SDK carries.
+
+```ts
+interface TeamInfo {
+    teamId: string;
+    index: number;
+    name: string;
+}
+```
+
+### TeamRunMeta
+
+`meta` for a function that runs against one team's context: `Init`, `Run`, and tick-controller logic.
+
+```ts
+interface TeamRunMeta extends RunMeta {
+    teamId: string;
+    index: number;
+}
+```
+
+### TeamStateEntry
+
+One team's state at one committed past tick, as returned by `getPastState`.
+
+```ts
+interface TeamStateEntry<T = Record<string, unknown>> extends TeamInfo {
+    context: T;
+}
+```
+
+### TickControllerDefinition
+
+Definition of a tick controller that determines automatic tick timing
+
+```ts
+interface TickControllerDefinition {
+    identifier: string;
+    reads?: string[];
+    uses?: ApiUse[];
+    settings?: string[];
+}
+```
+
+### TickControllerFunctionArgs
+
+```ts
+interface TickControllerFunctionArgs<
+    TContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+> extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
+    teams: AggregateFunctionTeam<TContext>[];
+    waitingRoomOpen: boolean;
+}
+```
+
+### TickControllerResult
+
+```ts
+interface TickControllerResult {
+    enabled: boolean;
+    intervalMs?: number;
+    nextTickAt?: number;
+    complete?: boolean;
+}
+```
+
+### TimerState
+
+The host's automatic tick timer, as every reader sees it.
+
+```ts
+interface TimerState {
+    enabled: boolean;
+    paused: boolean;
+    nextTickAt: number | null;
+    intervalMs: number | null;
+    pausedAt: number | null;
+    pausedMs: number;
+    extendedMs: number;
+    scheduleStartedAt: number | null;
+}
+```
+
+### UserInterfaceCallbacks
+
+Callbacks available to user interface components
+
+```ts
+interface UserInterfaceCallbacks {
+    requestTick: () => Promise<void>;
+    renameOwnTeam: (name: string) => Promise<void>;
+    uploadBlob: (file: File) => Promise<string>;
+    getAssetUrl: (reference: string) => string;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    getPastState: <T = Record<string, unknown>>(
+        query: PastStateQuery<T>
+    ) => Promise<PastStateEntry<T>[]>;
+    getAllTeamsParticipants: () => Promise<Participant[]>;
+    endpoints: Record<string, (request: unknown) => Promise<unknown>>;
+    setThemePreference: (preference: ThemePreference) => void;
+}
+```
+
+### UserInterfaceDefinition
+
+Definition of a user interface with internationalization support
+
+```ts
+interface UserInterfaceDefinition {
+    identifier: string;
+    reads?: string[];
+    crossTeamReads?: string[];
+    writes?: string[];
+    endpoints?: string[];
+    crossTeamParticipants?: boolean;
+    settings?: string[];
+}
+```
+
+### ValidationRejection
+
+A single validator rejection returned to the caller. The runtime collects every rejection (form-style UX) rather than short-circuiting on the first.
+
+```ts
+interface ValidationRejection {
+    validatorIdentifier: string;
+    message: string;
+}
+```
+
+### ValidatorDefinition
+
+Definition of a validator — a standalone, read-only gate on what a participant does from a player surface: a context write, or a request for the next tick. Reject-only; never modifies state.
+
+```ts
+interface ValidatorDefinition {
+    identifier: string;
+    reads?: string[];
+    gates?: ValidatorGate[];
+    settings?: string[];
+}
+```
+
+### ValidatorFunctionArgs
+
+Arguments of a validator's `UpdateData` gate, which judges a participant's context write. `previous` is the state before the write; `next` is the proposed state after it. Validators are read-only: they return a verdict, never modify the proposed state.
+
+```ts
+interface ValidatorFunctionArgs<TContext, TSettings> {
+    previous: TContext;
+    next: TContext;
+    actor: ValidatorActor;
+    settings: TSettings;
+    meta: LogicMeta;
+    participants: readonly Readonly<Participant>[];
+}
+```
+
+### WaitingRoomUserInterfaceDefinition
+
+Definition of a waiting room user interface (the holding screen shown to players while the session's waiting room is open)
+
+```ts
+interface WaitingRoomUserInterfaceDefinition {
+    identifier: string;
+    reads?: string[];
+    crossTeamReads?: string[];
+    writes?: string[];
+    endpoints?: string[];
+    crossTeamParticipants?: boolean;
+    settings?: string[];
+}
+```
+
+## Types
+
+### ApiUse
+
+Runtime callback API (a service) a logic-bearing resource is permitted to invoke. A declared API is always present for that resource, and a runtime that cannot provide one a package declares refuses the package at load. Calling an undeclared API throws at runtime, in both dev and production. Resources that omit `uses` (or declare an empty array) cannot call any callbacks.
+
+```ts
+type ApiUse = 'generateText' | 'extractText' | 'generateSpeech' | 'writeBlob';
+```
+
+### ContentBlock
+
+A content block inside an LLM message or response.
+
+```ts
+type ContentBlock =
+    | {
+          type: 'text';
+          text: string;
+      }
+    | {
+          type: 'toolUse';
+          id: string;
+          name: string;
+          input: unknown;
+      }
+    | {
+          type: 'toolResult';
+          toolUseId: string;
+          content: string;
+          isError?: boolean;
+      };
+```
+
+### ContextDeletePath
+
+Where to remove a key, as a path from the root of the context.
+
+```ts
+type ContextDeletePath = string | readonly string[];
+```
+
+### ContextUpdate
+
+A partial update accepted by `setData` and merged with `deepMergeContext`. Mirrors the merge semantics at the type level: object values may be given partially (they merge), while arrays and scalars must be given whole (they replace).
+
+```ts
+type ContextUpdate<T> = {
+    [K in keyof T]?: T[K] extends ReadonlyArray<unknown>
+        ? T[K]
+        : T[K] extends Record<string, unknown>
+          ? ContextUpdate<T[K]>
+          : T[K];
+};
+```
+
+### EffectfulEndpointHandler
+
+Function signature for an endpoint that returns an `EndpointResult`: one that declares `actions`, or a session-scoped one that writes team capabilities.
+
+```ts
+type EffectfulEndpointHandler<
+    TRequest = unknown,
+    TResponse = unknown,
+    TContext = unknown,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+    TWrites = never,
+    TAction extends EndpointAction = never,
+    TTeamWrites = never,
+> = (
+    args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>
+) => Promise<EndpointResult<TResponse, TWrites, TAction, TTeamWrites>>;
+```
+
+### EffectStep
+
+One effect of an endpoint's result, in the order the runtime applies them: the endpoint's own `capabilities`, then each team's patch under `teams`, then each action by its position in `actions`.
+
+```ts
+type EffectStep =
+    | {
+          kind: 'capabilities';
+      }
+    | {
+          kind: 'teams';
+          teamId: string;
+      }
+    | {
+          kind: 'action';
+          index: number;
+          type: EndpointActionType;
+      };
+```
+
+### EndpointAction
+
+A session action an endpoint returns for the runtime to carry out.
+
+```ts
+type EndpointAction =
+    | {
+          type: 'tick';
+          teamId?: string;
+      }
+    | {
+          type: 'setWaitingRoom';
+          open: boolean;
+      }
+    | {
+          type: 'pauseTimer';
+          teamId?: string;
+      }
+    | {
+          type: 'resumeTimer';
+          teamId?: string;
+      }
+    | {
+          type: 'extendTick';
+          byMs: number;
+          teamId?: string;
+      }
+    | {
+          type: 'renameTeam';
+          name: string;
+          teamId?: string;
+      }
+    | {
+          type: 'moveParticipant';
+          participantId: string;
+          teamId: string;
+      }
+    | {
+          type: 'addTeam';
+          name?: string;
+      }
+    | {
+          type: 'setLocale';
+          locale: string;
+      };
+```
+
+### EndpointActionType
+
+A session action an endpoint may return for the runtime to carry out after its write. Each is the operation a facilitator's session surface can perform, held to the same rules; an endpoint may return only the actions it declares.
+
+```ts
+type EndpointActionType =
+    | 'tick'
+    | 'setWaitingRoom'
+    | 'pauseTimer'
+    | 'resumeTimer'
+    | 'extendTick'
+    | 'renameTeam'
+    | 'moveParticipant'
+    | 'addTeam'
+    | 'setLocale';
+```
+
+### EndpointCallerRole
+
+Who is calling an endpoint.
+
+```ts
+type EndpointCallerRole = ViewerRole | 'facilitator' | 'author' | 'external';
+```
+
+### EndpointCallResult
+
+How an endpoint call settled: its response, or an `EndpointFailure`.
+
+```ts
+type EndpointCallResult =
+    | {
+          ok: true;
+          response: unknown;
+      }
+    | ({
+          ok: false;
+      } & EndpointFailure);
+```
+
+### EndpointFailureOutcome
+
+Why an endpoint call failed.
+
+```ts
+type EndpointFailureOutcome =
+    | MutationOutcome
+    | {
+          kind: 'invalid-request';
+          message: string;
+      }
+    | {
+          kind: 'handler-error';
+          message: string;
+      }
+    | {
+          kind: 'invalid-response';
+          message: string;
+      };
+```
+
+### EndpointHandler
+
+Function signature for an endpoint that declares no `writes`. The runtime never persists anything on its behalf: the returned value is validated against the endpoint's `responseSchema` and surfaced to the caller as-is.
+
+```ts
+type EndpointHandler<
+    TRequest = unknown,
+    TResponse = unknown,
+    TContext = unknown,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+> = (
+    args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>
+) => Promise<TResponse>;
+```
+
+### EndpointHandlerArgs
+
+Argument shape passed to an endpoint handler. The handler's input is the entire surface: nothing else leaks in — no headers, no cookies, no fetch.
+
+```ts
+type EndpointHandlerArgs<
+    TRequest,
+    TContext,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+> = EndpointBaseArgs<TRequest, TContext, TCallbacks, TSettings> &
+    (TScope extends 'session' ? SessionEndpointArgs<TTeamContext> : TeamEndpointArgs);
+```
+
+### EndpointPlan
+
+What `Plan` returns, for an endpoint that answers in two phases: its effects alone. The response is `Respond`'s to write, once they have landed.
+
+```ts
+type EndpointPlan<
+    TWrites = never,
+    TAction extends EndpointAction = never,
+    TTeamWrites = never,
+> = Omit<EndpointResult<never, TWrites, TAction, TTeamWrites>, 'response'>;
+```
+
+### EndpointPlanner
+
+`Plan`: the first phase of an endpoint that answers in two. It decides what happens and returns no response; `Respond` writes that once the effects have landed. An endpoint that answers in one exports `Handle` instead.
+
+```ts
+type EndpointPlanner<
+    TRequest = unknown,
+    TContext = unknown,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+    TWrites = never,
+    TAction extends EndpointAction = never,
+    TTeamWrites = never,
+> = (
+    args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>
+) => Promise<EndpointPlan<TWrites, TAction, TTeamWrites>>;
+```
+
+### EndpointResponder
+
+`Respond`: the second phase, called once `Plan`'s effects have landed. It receives every argument `Plan` did, read afresh, plus what `Plan` returned and what each action came to. Its return is the response, validated against `responseSchema`. It changes nothing.
+
+```ts
+type EndpointResponder<
+    TRequest = unknown,
+    TResponse = unknown,
+    TContext = unknown,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+    TWrites = never,
+    TAction extends EndpointAction = never,
+    TTeamWrites = never,
+> = (
+    args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings> & {
+        plan: EndpointPlan<TWrites, TAction, TTeamWrites>;
+        outcomes: EndpointOutcome[];
+    }
+) => Promise<TResponse>;
+```
+
+### EndpointScope
+
+What an endpoint call acts on. Absent in a bundle means `team`.
+
+```ts
+type EndpointScope = NonNullable<EndpointDefinition['scope']>;
+```
+
+### ExtractTextFunction
+
+Function for extracting text from a document referenced under the unified asset URI scheme.
+
+```ts
+type ExtractTextFunction = (reference: string) => Promise<ExtractTextResponse>;
+```
+
+### GenerateSpeechFormat
+
+Audio container format for synthesised speech.
+
+```ts
+type GenerateSpeechFormat = 'mp3' | 'wav' | 'opus';
+```
+
+### GenerateSpeechFunction
+
+Function for synthesising speech.
+
+```ts
+type GenerateSpeechFunction = (
+    request: GenerateSpeechRequest | string
+) => Promise<GenerateSpeechResponse>;
+```
+
+### GenerateSpeechVoice
+
+Role-based voice preset. The runtime maps the preset to a concrete provider voice. Game code only ever passes the preset name. The five values below are the recommended starting set; runtimes may accept additional preset names.
+
+```ts
+type GenerateSpeechVoice = 'neutral' | 'narrator' | 'announcer' | 'executive' | 'coach';
+```
+
+### GetTickControllerFunction
+
+```ts
+type GetTickControllerFunction<TContext, TSettings, TCallbacks = SignatureCallbacks> = (
+    args: TickControllerFunctionArgs<TContext, TSettings, TCallbacks>
+) => Promise<TickControllerResult>;
+```
+
+### HookFunction
+
+Function signature for a hook. Returns its writes under `capabilities`, the same shape an engine returns: hooks fire after the runtime applies the lifecycle change, then the runtime merges and persists what they return.
+
+```ts
+type HookFunction<
+    S extends HookSignal = HookSignal,
+    TContext = unknown,
+    TSettings = unknown,
+    TCallbacks = SignatureCallbacks,
+> = (args: HookFunctionArgs<S, TContext, TSettings, TCallbacks>) => Promise<LogicResult<TContext>>;
+```
+
+### HookFunctionArgs
+
+Argument shape passed to a hook function. The signal-specific payload fields are spread alongside `context`, `settings`, and `callbacks` so consumers can destructure them directly (e.g. `({ context, participant }) => ...`).
+
+```ts
+type HookFunctionArgs<
+    S extends HookSignal,
+    TContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+> = HookPayload<S> & {
+    context: TContext;
+    settings: TSettings;
+    callbacks: TCallbacks;
+    meta: LogicMeta;
+    participants: readonly Readonly<Participant>[];
+};
+```
+
+### HookPayload
+
+Payload for a hook subscribed to signal `S`. Defaults to the union across all signals so callers that haven't pinned a signal still get a valid type.
+
+```ts
+type HookPayload<S extends HookSignal = HookSignal> = HookPayloadMap[S];
+```
+
+### HookSignal
+
+Lifecycle signal a hook subscribes to. Hooks fire on out-of-tick events emitted by the runtime, after the runtime applies the change.
+
+```ts
+type HookSignal = 'participantJoin' | 'participantMove';
+```
+
+### HostOverlay
+
+A host-rendered overlay a session surface may ask the host to open.
+
+```ts
+type HostOverlay = 'facilitator-guide' | 'print-sheets';
+```
+
+### InitAggregateFunction
+
+```ts
+type InitAggregateFunction<
+    TTeamContext,
+    TSharedContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+    TTeamState = never,
+    TSharedState = never,
+> = (
+    args: RunAggregateFunctionArgs<
+        TTeamContext,
+        TSharedContext,
+        TSettings,
+        TCallbacks,
+        TTeamState,
+        TSharedState
+    >
+) => Promise<RunAggregateResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;
+```
+
+### InitializationFunction
+
+```ts
+type InitializationFunction<
+    TContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+    TState = never,
+> = (
+    args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
+) => Promise<EngineResult<TContext, TState>>;
+```
+
+### LLMGenerateFunction
+
+Function for generating text with an LLM The actual endpoint and model are determined by the platform
+
+```ts
+type LLMGenerateFunction = (options: LLMGenerateOptions | string) => Promise<LLMResponse>;
+```
+
+### LLMStopReason
+
+Why the LLM stopped generating.
+
+```ts
+type LLMStopReason = 'endTurn' | 'toolUse' | 'maxTokens' | 'refusal';
+```
+
+### LLMTier
+
+LLM capability tier for a generateText call.
+
+```ts
+type LLMTier = 'quick' | 'standard' | 'expert';
+```
+
+### LogicCallbacks
+
+The callbacks a logic-bearing resource actually receives: the gated ones it declared in `uses`, plus the ungated ones it gets regardless.
+
+```ts
+type LogicCallbacks<Uses extends ApiUse = never> = Required<Pick<SignatureCallbacks, Uses>> &
+    UngatedSignatureCallbacks;
+```
+
+### RequestTickFunction
+
+A validator's `RequestTick` export: the gate on a participant's request for the next tick. Only a player surface's request reaches it; the facilitator's ticks, the timer's and every system-trusted caller's pass straight through.
+
+```ts
+type RequestTickFunction<TContext = unknown, TSettings = unknown> = (
+    args: RequestTickFunctionArgs<TContext, TSettings>
+) => Promise<ValidationResult>;
+```
+
+### RunAggregateFunction
+
+```ts
+type RunAggregateFunction<
+    TTeamContext,
+    TSharedContext,
+    TSettings,
+    TCallbacks = SignatureCallbacks,
+    TTeamState = never,
+    TSharedState = never,
+> = (
+    args: RunAggregateFunctionArgs<
+        TTeamContext,
+        TSharedContext,
+        TSettings,
+        TCallbacks,
+        TTeamState,
+        TSharedState
+    >
+) => Promise<RunAggregateTickResult<TTeamContext, TSharedContext, TTeamState, TSharedState>>;
+```
+
+### RunFunction
+
+```ts
+type RunFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = never> = (
+    args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
+) => Promise<RunResult<TContext, TState>>;
+```
+
+### RunKind
+
+Which kind of run a function is executing in.
+
+```ts
+type RunKind = 'session' | 'walkthrough';
+```
+
+### StepFunction
+
+One step of an engine that splits its `Init` or `Run` into several functions.
+
+```ts
+type StepFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = unknown> = (
+    args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
+) => Promise<TContext>;
+```
+
+### ThemePreference
+
+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.
+
+```ts
+type ThemePreference = 'light' | 'dark' | 'system';
+```
+
+### UngatedSignatureCallbacks
+
+The `SignatureCallbacks` members that `uses` does not gate.
+
+```ts
+type UngatedSignatureCallbacks = Pick<SignatureCallbacks, 'readAsset' | 'getPastState'>;
+```
+
+### ValidationResult
+
+Verdict returned by a validator. `ok: true` means the proposed state passes this check; `ok: false` rejects it and the runtime returns the message to the caller. The message is free-form — games encode structured data (locale key, JSON blob, etc.) inside it if they need to.
+
+```ts
+type ValidationResult =
+    | {
+          ok: true;
+      }
+    | {
+          ok: false;
+          message: string;
+      };
+```
+
+### ValidatorActor
+
+Who submitted the mutation a validator is gating.
+
+```ts
+type ValidatorActor =
+    | {
+          role: 'participant';
+          participant: Participant;
+      }
+    | {
+          role: 'observer';
+          teamId: string;
+      };
+```
+
+### ValidatorFunction
+
+A validator's `UpdateData` export: the gate on a participant's context write. Engines, hooks, endpoints and a session surface bypass it (system-trusted).
+
+```ts
+type ValidatorFunction<TContext = unknown, TSettings = unknown> = (
+    args: ValidatorFunctionArgs<TContext, TSettings>
+) => Promise<ValidationResult>;
+```
+
+### ValidatorGate
+
+A participant action a validator can gate, named after the surface message it gates: a context write, or a request for the next tick
+
+```ts
+type ValidatorGate = 'updateData' | 'requestTick';
+```
+
+### WaitingRoomUserInterfaceCallbacks
+
+Callbacks available to waiting room user interface components.
+
+```ts
+type WaitingRoomUserInterfaceCallbacks = UserInterfaceCallbacks;
+```
+
+### WritingEndpointHandler
+
+Function signature for an endpoint that declares `writes`.
+
+```ts
+type WritingEndpointHandler<
+    TRequest = unknown,
+    TResponse = unknown,
+    TWrites = unknown,
+    TContext = unknown,
+    TCallbacks = SignatureCallbacks,
+    TTeamContext = never,
+    TScope extends EndpointScope = 'team',
+    TSettings = Record<string, never>,
+> = (
+    args: EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>
+) => Promise<EndpointWriteResult<TResponse, TWrites>>;
+```