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

package/dist/docs/api/sdk-ui.md

@@ -0,0 +1,1269 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk/ui`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk/ui`
+
+Every export of `@seriousgaming/sdk/ui`, 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
+
+### localisedReferences
+
+The references `useAsset` tries, most specific first: the locale as a directory immediately before the file name, then its language alone, then the reference as given. `asset:documents/intro.md` in `fr-CA` tries `asset:documents/fr-CA/intro.md`, `asset:documents/fr/intro.md` and `asset:documents/intro.md`.
+
+```ts
+function localisedReferences(reference: string, locale: string | false): string[];
+```
+
+### PresentationWrapper
+
+Wrap a presentation bundle. Read-only: there is nothing here to write with, and the host would refuse it if there were.
+
+```ts
+function PresentationWrapper(props: PresentationWrapperProps): import('react').JSX.Element;
+```
+
+### SessionUserInterfaceWrapper
+
+```ts
+function SessionUserInterfaceWrapper(
+    props: SessionUserInterfaceWrapperProps
+): import('react').JSX.Element;
+```
+
+### SettingsEditorWrapper
+
+The wrapper for both settings editors, the `setup` slot and the `scenario_editor` slot. Each slot is its own bundle, so a screen knows which it is without being told: the host sends the same batch to both.
+
+```ts
+function SettingsEditorWrapper(props: SettingsEditorWrapperProps): import('react').JSX.Element;
+```
+
+### useAsset
+
+Fetch an asset and read its body, preferring a copy in the surface's locale.
+
+```ts
+function useAsset<T = unknown>(
+    reference: string | null | undefined,
+    options: UseAssetOptions<'json'>
+): AssetState<T>;
+function useAsset(
+    reference: string | null | undefined,
+    options: UseAssetOptions<'text'>
+): AssetState<string>;
+function useAsset(
+    reference: string | null | undefined,
+    options: UseAssetOptions<'blob'>
+): AssetState<Blob>;
+```
+
+### useAssetUrl
+
+The URL an `asset:`, `shared:` or `blob:` reference resolves to, for an `<img>`, `<video>` or link.
+
+```ts
+function useAssetUrl(reference: string | null | undefined): string | undefined;
+```
+
+### useMutationReporter
+
+Runs a fallible mutation (`setData`, `requestTick`, and the rest) so that a failure reaches the participant instead of vanishing.
+
+```ts
+function useMutationReporter(): MutationReporter;
+```
+
+### usePastState
+
+Read committed past state (`getPastState`) and keep it in step with the query.
+
+```ts
+function usePastState<T = Record<string, unknown>>(
+    query: PastStateQuery<T> | null | undefined
+): PastStateResult<T>;
+```
+
+### usePresentation
+
+Everything a presentation can see: the session (or `null`), its settings, the host's theme, and the locale.
+
+```ts
+function usePresentation<
+    TSettings = Record<string, Record<string, unknown>>,
+    TTeamContext = Record<string, unknown>,
+    TSharedContext = Record<string, unknown>,
+>(): PresentationValue<TSettings, TTeamContext, TSharedContext>;
+```
+
+### UserInterfaceWrapper
+
+```ts
+function UserInterfaceWrapper(props: UserInterfaceWrapperProps): import('react').JSX.Element;
+```
+
+### useRunKind
+
+Hook returning whether this surface belongs to the game being played or to a walkthrough beside it.
+
+```ts
+const useRunKind: () => RunKind;
+```
+
+### useSessionUserInterfaceCallbacks
+
+```ts
+const useSessionUserInterfaceCallbacks: () => SessionUserInterfaceCallbacks;
+```
+
+### useSessionUserInterfaceData
+
+The session's data and the session surface's `setData`.
+
+```ts
+function useSessionUserInterfaceData<
+    T extends SessionData<object, object> = SessionData,
+    A = unknown,
+    S extends Record<string, unknown> = Record<string, unknown>,
+    W extends Record<string, unknown> = Record<string, unknown>,
+>(): SessionUserInterfaceDataContextValue<T, A, S, W>;
+```
+
+### useSessionUserInterfaceHookFailures
+
+Subscribe to hook chains that threw anywhere in the session.
+
+```ts
+const useSessionUserInterfaceHookFailures: () => SessionUserInterfaceHookFailuresValue;
+```
+
+### useSessionUserInterfaceHostOverlays
+
+Hook listing the host overlays this host offers for this session.
+
+```ts
+const useSessionUserInterfaceHostOverlays: () => HostOverlay[];
+```
+
+### useSessionUserInterfaceLocale
+
+Hook to access the current locale in a manage session user interface component.
+
+```ts
+const useSessionUserInterfaceLocale: () => SessionUserInterfaceLocale;
+```
+
+### useSessionUserInterfaceMeta
+
+Hook to access the session's identity and lifecycle state.
+
+```ts
+const useSessionUserInterfaceMeta: () => SessionMeta;
+```
+
+### useSessionUserInterfaceParticipants
+
+Hook to access all participants across all teams in the session.
+
+```ts
+const useSessionUserInterfaceParticipants: () => Participant[];
+```
+
+### useSessionUserInterfaceTeamConfiguration
+
+Hook to access the session's interaction mode and team bounds.
+
+```ts
+const useSessionUserInterfaceTeamConfiguration: () => TeamConfiguration;
+```
+
+### useSessionUserInterfaceTeamLinks
+
+Hook to access each team's join and observe links.
+
+```ts
+const useSessionUserInterfaceTeamLinks: () => TeamLinks[];
+```
+
+### useSessionUserInterfaceTeams
+
+Hook to access the session's teams, sorted by stable index.
+
+```ts
+const useSessionUserInterfaceTeams: () => TeamInfo[];
+```
+
+### useSessionUserInterfaceTheme
+
+```ts
+const useSessionUserInterfaceTheme: () => SessionUserInterfaceTheme;
+```
+
+### useSessionUserInterfaceThemePreference
+
+```ts
+const useSessionUserInterfaceThemePreference: () => ThemePreference;
+```
+
+### useSessionUserInterfaceWalkthroughLink
+
+Hook returning where to open the walkthrough, or `null` until the host has said.
+
+```ts
+const useSessionUserInterfaceWalkthroughLink: () => WalkthroughLink | null;
+```
+
+### useSettingsEditor
+
+The settings a `setup` or `scenario_editor` slot edits, and the way to change them. Pass the generated `Settings` type from the slot's `types.ts`.
+
+```ts
+function useSettingsEditor<T>(): SettingsEditorValue<T>;
+```
+
+### useSettingsEditorCallbacks
+
+```ts
+const useSettingsEditorCallbacks: () => SettingsEditorCallbacks;
+```
+
+### useSettingsEditorLocale
+
+Hook to access the current locale in a settings editor (the `setup` or `scenario_editor` slot). The host picks it from the game's supported locales.
+
+```ts
+const useSettingsEditorLocale: () => SettingsEditorLocale;
+```
+
+### useSettingsEditorTheme
+
+```ts
+const useSettingsEditorTheme: () => SettingsEditorTheme;
+```
+
+### useSettingsEditorThemePreference
+
+```ts
+const useSettingsEditorThemePreference: () => ThemePreference;
+```
+
+### useUserInterfaceCallbacks
+
+```ts
+const useUserInterfaceCallbacks: () => UserInterfaceCallbacks;
+```
+
+### useUserInterfaceCrossTeamData
+
+Observe every team's live cross-team state, including the calling team's own. Entries update as teams change their pending state, without waiting for a tick.
+
+```ts
+function useUserInterfaceCrossTeamData<T = Record<string, unknown>>(): TeamStateEntry<T>[];
+```
+
+### useUserInterfaceData
+
+```ts
+function useUserInterfaceData<T, A>(): UserInterfaceDataContextValue<T, A>;
+```
+
+### useUserInterfaceLocale
+
+Hook to access the current locale in a user interface component. The locale is provided by the dev server based on the game's supported locales.
+
+```ts
+const useUserInterfaceLocale: () => UserInterfaceLocale;
+```
+
+### useUserInterfaceOwnTeam
+
+Hook returning the team whose surface this user interface is rendering.
+
+```ts
+const useUserInterfaceOwnTeam: () => TeamInfo | null;
+```
+
+### useUserInterfaceOwnTeamJoinLink
+
+Hook returning how to join this surface's own team.
+
+```ts
+const useUserInterfaceOwnTeamJoinLink: () => OwnTeamJoinLink | null;
+```
+
+### useUserInterfaceParticipant
+
+Hook to access the current participant in a user interface component. The participant is provided by the platform and contains information about the person currently viewing this UI.
+
+```ts
+const useUserInterfaceParticipant: () => Participant | null;
+```
+
+### useUserInterfaceParticipants
+
+Hook to access the list of participants currently known for this team.
+
+```ts
+const useUserInterfaceParticipants: () => Participant[];
+```
+
+### useUserInterfaceTeams
+
+Hook to access basic metadata about all teams in the session.
+
+```ts
+const useUserInterfaceTeams: () => TeamInfo[];
+```
+
+### useUserInterfaceTheme
+
+```ts
+const useUserInterfaceTheme: () => UserInterfaceTheme;
+```
+
+### useUserInterfaceThemePreference
+
+```ts
+const useUserInterfaceThemePreference: () => ThemePreference;
+```
+
+### useUserInterfaceTimer
+
+Hook to access the host's automatic tick timer state from inside a user interface component. Always returns a value — when `enabled` is false, no countdown should be displayed.
+
+```ts
+const useUserInterfaceTimer: () => TimerState;
+```
+
+### useUserInterfaceValidationRejections
+
+Subscribe to validator rejections from the host. Rejections are surfaced when a UI-submitted mutation (via `setData`) violates one or more validators declared in the game. They are delivered as a single batch per submission; the runtime collects every failing validator's verdict and returns them together.
+
+```ts
+const useUserInterfaceValidationRejections: () => UserInterfaceValidationContextValue;
+```
+
+### useUserInterfaceViewerRole
+
+Hook returning whether the current viewer is a `'participant'` or an `'observer'`. Use it to adapt a player or shell UI for observation — for example to show a debrief overlay, reveal otherwise-hidden state, or gate a genuinely read-only view. When it returns `'observer'`, `./UserInterfaceParticipantContext.useUserInterfaceParticipant` returns `null`.
+
+```ts
+const useUserInterfaceViewerRole: () => ViewerRole;
+```
+
+### useViewerStorage
+
+State that this browser remembers for this viewer, like `useState` but kept across a reload.
+
+```ts
+function useViewerStorage<T>(
+    key: string,
+    initial: T | (() => T)
+): [T, (value: T | ((previous: T) => T)) => void];
+```
+
+## 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;
+}
+```
+
+### MutationError
+
+Error a fallible mutation promise rejects with. Inspect `outcome` (or the shorthand `kind`) to branch on the failure reason.
+
+```ts
+class MutationError extends Error {
+    readonly outcome: MutationOutcome;
+    constructor(outcome: MutationOutcome);
+    get kind(): MutationOutcome['kind'];
+}
+```
+
+### TickSnapshotError
+
+Error a `getPastState` call rejects with on a genuine read fault.
+
+```ts
+class TickSnapshotError extends Error {
+    constructor(message: string);
+}
+```
+
+## Constants
+
+### AssetContext
+
+Provided by every surface wrapper. Exported for the test helpers, which provide it without a host; game code reads it through `useAssetUrl` and `useAsset`.
+
+```ts
+const AssetContext: import('react').Context<AssetScope | undefined>;
+```
+
+### CrossTeamDataContext
+
+```ts
+const CrossTeamDataContext: import('react').Context<CrossTeamData | undefined>;
+```
+
+### PastStateContext
+
+Provided by the wrappers whose surfaces can read past state: the player, session and presentation wrappers. Exported for the test helpers, which provide it without a host; game code reads it through `usePastState`.
+
+```ts
+const PastStateContext: import('react').Context<PastStateReader | undefined>;
+```
+
+### PresentationContext
+
+```ts
+const PresentationContext: import('react').Context<
+    PresentationValue<unknown, unknown, unknown> | undefined
+>;
+```
+
+### SessionUserInterfaceCallbacksContext
+
+```ts
+const SessionUserInterfaceCallbacksContext: import('react').Context<
+    SessionUserInterfaceCallbacks | undefined
+>;
+```
+
+### SessionUserInterfaceDataContext
+
+```ts
+const SessionUserInterfaceDataContext: import('react').Context<
+    | SessionUserInterfaceDataContextValue<
+          SessionData<object, object>,
+          unknown,
+          Record<string, unknown>,
+          Record<string, unknown>
+      >
+    | undefined
+>;
+```
+
+### SessionUserInterfaceHookFailuresContext
+
+```ts
+const SessionUserInterfaceHookFailuresContext: import('react').Context<
+    SessionUserInterfaceHookFailuresValue | undefined
+>;
+```
+
+### SessionUserInterfaceHostOverlaysContext
+
+```ts
+const SessionUserInterfaceHostOverlaysContext: import('react').Context<HostOverlay[]>;
+```
+
+### SessionUserInterfaceLocaleContext
+
+```ts
+const SessionUserInterfaceLocaleContext: import('react').Context<
+    SessionUserInterfaceLocale | undefined
+>;
+```
+
+### SessionUserInterfaceMetaContext
+
+```ts
+const SessionUserInterfaceMetaContext: import('react').Context<SessionMeta | undefined>;
+```
+
+### SessionUserInterfaceParticipantsContext
+
+```ts
+const SessionUserInterfaceParticipantsContext: import('react').Context<Participant[] | undefined>;
+```
+
+### SessionUserInterfaceTeamConfigurationContext
+
+```ts
+const SessionUserInterfaceTeamConfigurationContext: import('react').Context<TeamConfiguration>;
+```
+
+### SessionUserInterfaceTeamLinksContext
+
+```ts
+const SessionUserInterfaceTeamLinksContext: import('react').Context<TeamLinks[]>;
+```
+
+### SessionUserInterfaceTeamsContext
+
+```ts
+const SessionUserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
+```
+
+### SessionUserInterfaceThemeContext
+
+```ts
+const SessionUserInterfaceThemeContext: import('react').Context<
+    SessionUserInterfaceTheme | undefined
+>;
+```
+
+### SessionUserInterfaceThemePreferenceContext
+
+```ts
+const SessionUserInterfaceThemePreferenceContext: import('react').Context<
+    ThemePreference | undefined
+>;
+```
+
+### SessionUserInterfaceWalkthroughLinkContext
+
+```ts
+const SessionUserInterfaceWalkthroughLinkContext: import('react').Context<WalkthroughLink | null>;
+```
+
+### SettingsEditorCallbacksContext
+
+```ts
+const SettingsEditorCallbacksContext: import('react').Context<SettingsEditorCallbacks | undefined>;
+```
+
+### SettingsEditorContext
+
+```ts
+const SettingsEditorContext: import('react').Context<SettingsEditorValue<unknown> | undefined>;
+```
+
+### SettingsEditorLocaleContext
+
+```ts
+const SettingsEditorLocaleContext: import('react').Context<SettingsEditorLocale | undefined>;
+```
+
+### SettingsEditorThemeContext
+
+```ts
+const SettingsEditorThemeContext: import('react').Context<SettingsEditorTheme | undefined>;
+```
+
+### SettingsEditorThemePreferenceContext
+
+```ts
+const SettingsEditorThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
+```
+
+### UserInterfaceCallbacksContext
+
+```ts
+const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
+```
+
+### UserInterfaceDataContext
+
+```ts
+const UserInterfaceDataContext: import('react').Context<
+    UserInterfaceDataContextValue<unknown, unknown> | undefined
+>;
+```
+
+### UserInterfaceLocaleContext
+
+```ts
+const UserInterfaceLocaleContext: import('react').Context<UserInterfaceLocale | undefined>;
+```
+
+### UserInterfaceOwnTeamContext
+
+```ts
+const UserInterfaceOwnTeamContext: import('react').Context<TeamInfo | null>;
+```
+
+### UserInterfaceOwnTeamJoinLinkContext
+
+```ts
+const UserInterfaceOwnTeamJoinLinkContext: import('react').Context<OwnTeamJoinLink | null>;
+```
+
+### UserInterfaceParticipantContext
+
+```ts
+const UserInterfaceParticipantContext: import('react').Context<Participant | null | undefined>;
+```
+
+### UserInterfaceParticipantsContext
+
+```ts
+const UserInterfaceParticipantsContext: import('react').Context<Participant[]>;
+```
+
+### UserInterfaceRunKindContext
+
+```ts
+const UserInterfaceRunKindContext: import('react').Context<RunKind>;
+```
+
+### UserInterfaceTeamsContext
+
+```ts
+const UserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
+```
+
+### UserInterfaceThemeContext
+
+```ts
+const UserInterfaceThemeContext: import('react').Context<UserInterfaceTheme | undefined>;
+```
+
+### UserInterfaceThemePreferenceContext
+
+```ts
+const UserInterfaceThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
+```
+
+### UserInterfaceTimerContext
+
+```ts
+const UserInterfaceTimerContext: import('react').Context<TimerState>;
+```
+
+### UserInterfaceValidationContext
+
+```ts
+const UserInterfaceValidationContext: import('react').Context<
+    UserInterfaceValidationContextValue | undefined
+>;
+```
+
+### UserInterfaceViewerRoleContext
+
+```ts
+const UserInterfaceViewerRoleContext: import('react').Context<ViewerRole>;
+```
+
+### ViewerStorageContext
+
+Provided by every surface wrapper. Exported for the test helpers, which provide it without a host; game code reads it through `useViewerStorage`.
+
+```ts
+const ViewerStorageContext: import('react').Context<ViewerStorageScope | undefined>;
+```
+
+## Interfaces
+
+### AssetScope
+
+What a wrapper tells `useAssetUrl` and `useAsset` about its surface.
+
+```ts
+interface AssetScope {
+    getAssetUrl: ((reference: string) => string) | undefined;
+    locale: string | undefined;
+}
+```
+
+### AssetState
+
+```ts
+interface AssetState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    loading: boolean;
+}
+```
+
+### 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;
+}
+```
+
+### 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)[];
+}
+```
+
+### PastStateResult
+
+```ts
+interface PastStateResult<T> {
+    entries: PastStateEntry<T>[];
+    error: Error | undefined;
+    loading: boolean;
+    refetch: () => void;
+}
+```
+
+### PresentationGame
+
+The game a presentation belongs to, as the active scenario resolves it. Known with or without a session.
+
+```ts
+interface PresentationGame {
+    name: string;
+    maxTicks: number | null;
+    mode: SessionMode;
+    scenarioName: string | null;
+}
+```
+
+### PresentationSession
+
+The session a presentation is shown during: the shared store and every team, narrowed to what the presentation `reads`.
+
+```ts
+interface PresentationSession<
+    TTeamContext = Record<string, unknown>,
+    TSharedContext = Record<string, unknown>,
+> {
+    id: string;
+    name: string;
+    completedTicks: number;
+    data: SessionData<TTeamContext, TSharedContext>;
+    teams: TeamInfo[];
+}
+```
+
+### PresentationValue
+
+```ts
+interface PresentationValue<TSettings, TTeamContext, TSharedContext> {
+    game: PresentationGame;
+    session: PresentationSession<TTeamContext, TSharedContext> | null;
+    settings: TSettings;
+    theme: SessionUserInterfaceTheme;
+    locale: UserInterfaceLocale;
+    getPastState: <T = Record<string, unknown>>(
+        query: PastStateQuery<T>
+    ) => Promise<PastStateEntry<T>[]>;
+    getAssetUrl: (reference: string) => string;
+}
+```
+
+### SessionHookFailure
+
+A hook chain that threw, reported to the session surface after the fact.
+
+```ts
+interface SessionHookFailure {
+    signal: HookSignal;
+    teamId: string;
+    message: string;
+}
+```
+
+### SessionUserInterfaceHookFailuresValue
+
+Value exposed to consumers of `useSessionUserInterfaceHookFailures`.
+
+```ts
+interface SessionUserInterfaceHookFailuresValue {
+    failures: SessionHookFailure[];
+    clearFailures: () => void;
+}
+```
+
+### TeamInfo
+
+Who a team is: the fields every team entry in the SDK carries.
+
+```ts
+interface TeamInfo {
+    teamId: string;
+    index: number;
+    name: string;
+}
+```
+
+### 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;
+}
+```
+
+### 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;
+}
+```
+
+### UseAssetOptions
+
+```ts
+interface UseAssetOptions<F extends AssetFormat = AssetFormat> {
+    as: F;
+    locale?: string | false;
+}
+```
+
+### UserInterfaceValidationContextValue
+
+Value exposed to consumers of `useUserInterfaceValidationRejections`.
+
+```ts
+interface UserInterfaceValidationContextValue {
+    rejections: ValidationRejection[];
+    clearRejections: () => void;
+}
+```
+
+### ViewerStorageScope
+
+What a wrapper tells `useViewerStorage` about where it is.
+
+```ts
+interface ViewerStorageScope {
+    sessionKey: string | undefined;
+    surface: ViewerStorageSurface;
+    viewer: string;
+}
+```
+
+## Types
+
+### AssetFormat
+
+How `useAsset` reads the response body.
+
+```ts
+type AssetFormat = 'json' | 'text' | 'blob';
+```
+
+### 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];
+};
+```
+
+### CrossTeamData
+
+Every team's live cross-team state, one entry per team, sorted by stable team index and including the calling team's own.
+
+```ts
+type CrossTeamData = TeamStateEntry[];
+```
+
+### 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;
+      };
+```
+
+### 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;
+      };
+```
+
+### HostOverlay
+
+A host-rendered overlay a session surface may ask the host to open.
+
+```ts
+type HostOverlay = 'facilitator-guide' | 'print-sheets';
+```
+
+### MutationFailure
+
+A mutation that failed in a way the participant needs to know about.
+
+```ts
+type MutationFailure = {
+    outcome: MutationOutcome;
+    action?: string;
+    retry?: () => Promise<boolean>;
+};
+```
+
+### MutationOutcome
+
+The reason a mutation failed.
+
+```ts
+type MutationOutcome =
+    | {
+          kind: 'conflict';
+          message?: string;
+      }
+    | {
+          kind: 'superseded';
+          message: string;
+          committedAtTick?: number;
+      }
+    | {
+          kind: 'validation-rejected';
+          rejections: ValidationRejection[];
+          message?: string;
+      }
+    | {
+          kind: 'denied';
+          message: string;
+      }
+    | {
+          kind: 'tick-failed';
+          message: string;
+      }
+    | {
+          kind: 'error';
+          message: string;
+      };
+```
+
+### MutationReporter
+
+```ts
+type MutationReporter = {
+    run: (mutate: () => Promise<unknown>, action?: string) => Promise<boolean>;
+    pending: boolean;
+    late: MutationCommit | null;
+    failure: MutationFailure | null;
+    dismiss: () => void;
+};
+```
+
+### OwnTeamJoinLink
+
+How to join _this_ surface's team.
+
+```ts
+type OwnTeamJoinLink = {
+    joinUrl: string;
+    fallbackJoinUrl?: string;
+};
+```
+
+### PastStateReader
+
+The surface's `getPastState` callback, as `usePastState` calls it.
+
+```ts
+type PastStateReader = <T = Record<string, unknown>>(
+    query: PastStateQuery<T>
+) => Promise<PastStateEntry<T>[]>;
+```
+
+### RunKind
+
+Which kind of run a function is executing in.
+
+```ts
+type RunKind = 'session' | 'walkthrough';
+```
+
+### SessionData
+
+Everything a session surface is shown of the session's state.
+
+```ts
+type SessionData<
+    TTeamContext = Record<string, unknown>,
+    TSharedContext = Record<string, unknown>,
+> = {
+    shared: SharedState<TSharedContext>;
+    teams: Record<string, TeamState<TTeamContext>>;
+};
+```
+
+### SessionMeta
+
+The session's identity and lifecycle state, pushed on connect and again whenever any of it changes.
+
+```ts
+type SessionMeta = {
+    sessionId: string;
+    name: string;
+    readOnly: boolean;
+    waitingRoomOpen: boolean;
+    joinPin: string | null;
+};
+```
+
+### SessionUserInterfaceLocale
+
+```ts
+type SessionUserInterfaceLocale = {
+    locale: string;
+};
+```
+
+### SessionUserInterfaceModeColors
+
+```ts
+type SessionUserInterfaceModeColors = SurfaceModeColors;
+```
+
+### SessionUserInterfaceTheme
+
+```ts
+type SessionUserInterfaceTheme = {
+    mode: 'dark' | 'light';
+    dark: SessionUserInterfaceModeColors;
+    light: SessionUserInterfaceModeColors;
+};
+```
+
+### SetDataOptions
+
+What a write can do beyond merging fields.
+
+```ts
+type SetDataOptions = {
+    deletes?: ContextDeletePath[];
+};
+```
+
+### SettingsEditorLocale
+
+```ts
+type SettingsEditorLocale = {
+    locale: string;
+};
+```
+
+### SettingsEditorModeColors
+
+```ts
+type SettingsEditorModeColors = SurfaceModeColors;
+```
+
+### SettingsEditorTheme
+
+```ts
+type SettingsEditorTheme = {
+    mode: 'dark' | 'light';
+    dark: SettingsEditorModeColors;
+    light: SettingsEditorModeColors;
+};
+```
+
+### SettingsEditorValue
+
+What a settings editor edits: the `setup` slot and the `scenario_editor` slot share it.
+
+```ts
+type SettingsEditorValue<T> = {
+    settings: T;
+    updateSettings: (update: Partial<T>) => Promise<void>;
+    configures: string[];
+};
+```
+
+### SharedState
+
+```ts
+type SharedState<TSharedContext = Record<string, unknown>> = {
+    context: TSharedContext;
+    revision: number;
+};
+```
+
+### TeamConfiguration
+
+How teams work in this session: the interaction mode, and the bounds the host will hold the surface to.
+
+```ts
+type TeamConfiguration = {
+    mode: SessionMode;
+    min?: number;
+    max: number;
+    perTeam?: {
+        minParticipants?: number;
+        maxParticipants?: number;
+    };
+};
+```
+
+### TeamLinks
+
+A team's facilitator-only links: how participants join it, and how to watch it without joining.
+
+```ts
+type TeamLinks = {
+    teamId: string;
+    joinUrl: string;
+    fallbackJoinUrl?: string;
+    observeUrl: string;
+};
+```
+
+### TeamState
+
+Session-level data context for session user interfaces.
+
+```ts
+type TeamState<TTeamContext = Record<string, unknown>> = {
+    context: TTeamContext;
+    completedTicks: number;
+    timer: TimerState;
+    revision: number;
+};
+```
+
+### ThemeColorRole
+
+The palette roles a theme sends, each a colour a surface may paint with.
+
+```ts
+type ThemeColorRole = 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
+```
+
+### ThemeContrastText
+
+One text colour per palette role, for text drawn on that role's colour.
+
+```ts
+type ThemeContrastText = Record<ThemeColorRole, string>;
+```
+
+### UserInterfaceLocale
+
+```ts
+type UserInterfaceLocale = {
+    locale: string;
+};
+```
+
+### UserInterfaceModeColors
+
+```ts
+type UserInterfaceModeColors = SurfaceModeColors;
+```
+
+### UserInterfaceTheme
+
+```ts
+type UserInterfaceTheme = {
+    mode: 'dark' | 'light';
+    dark: UserInterfaceModeColors;
+    light: UserInterfaceModeColors;
+};
+```
+
+### ViewerRole
+
+Which viewer a player surface is being rendered for.
+
+```ts
+type ViewerRole = 'participant' | 'observer';
+```
+
+### ViewerStorageSurface
+
+Which surface a wrapper renders, as far as storage is concerned.
+
+```ts
+type ViewerStorageSurface = 'player' | 'session' | 'settings-editor' | 'presentation';
+```
+
+### WalkthroughLink
+
+Where to open the walkthrough run.
+
+```ts
+type WalkthroughLink = {
+    url: string;
+};
+```