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

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

@@ -0,0 +1,207 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk/projection`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk/projection`
+
+The one documented shape of a session's observable state.
+
+Served three ways and declared once: `sdk view --json`, `GET /api/state`, and
+the payload the console renders. It is a projection, not any runtime's
+internal state, so internals can change without breaking an agent that
+learned to read it, and it is versioned so one that has learned can tell when
+they have not.
+
+Everything a runtime exposes about a session belongs here, because a check
+made from outside a runtime can only read what the runtime exposes.
+
+Published from the SDK rather than declared inside a runtime, because a
+second runtime implementing it needs the shape, and a type it has to copy is
+a type the two halves are free to drift apart on.
+
+Every export of `@seriousgaming/sdk/projection`, 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.
+
+## Constants
+
+### PROJECTION_VERSION
+
+Bumped when a field changes meaning or leaves.
+
+```ts
+const PROJECTION_VERSION = 4;
+```
+
+## Interfaces
+
+### EndpointAuditEntry
+
+One endpoint call that changed something: who made it, and what it changed. Names only, never values, so the log does not become a second copy of the boards.
+
+```ts
+interface EndpointAuditEntry {
+    at: number;
+    endpoint: string;
+    role: EndpointCallerRole;
+    principal?: {
+        kind: string;
+        id: string;
+        name?: string;
+    };
+    teamId?: string;
+    wrote: string[];
+    teams?: Record<string, string[]>;
+    actions: string[];
+    stoppedAt?: string;
+}
+```
+
+### 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;
+}
+```
+
+### PendingChanges
+
+What changed on disk that a running session applies only when it next initialises. Each list is empty when nothing of its kind is waiting.
+
+```ts
+interface PendingChanges {
+    settings: string[];
+    manifest: string[];
+    capabilities: string[];
+}
+```
+
+### ProjectedTeam
+
+One team's observable state.
+
+```ts
+interface ProjectedTeam extends TeamInfo {
+    completedTicks: number;
+    complete: boolean;
+    canUndo: boolean;
+    context: Record<string, Record<string, unknown>>;
+    participants: Participant[];
+    timer?: TimerState;
+    state?: unknown;
+}
+```
+
+### ScenarioDraft
+
+The scenario editor's draft of one scenario, resolved.
+
+```ts
+interface ScenarioDraft {
+    scenarioId: string | null;
+    settings: ResolvedSettings;
+}
+```
+
+### StateProjection
+
+```ts
+interface StateProjection {
+    projectionVersion: number;
+    game: {
+        identifier: string;
+        name: string;
+        scenarioId: string | null;
+    };
+    session: {
+        completedTicks: number;
+        mode: SessionMode;
+        waitingRoomOpen: boolean;
+        complete: boolean;
+        seed: string;
+        sessionKey: string;
+        locale: string;
+        runKind: RunKind;
+        maxTicks: number | null;
+        teamBounds: {
+            min?: number;
+            max: number;
+        };
+        inSetup: boolean;
+        pending?: PendingChanges;
+    };
+    teams: ProjectedTeam[];
+    shared: Record<string, Record<string, unknown>>;
+    sharedState?: unknown;
+    timer: TimerState | null;
+    settings: ResolvedSettings;
+    settingsWithoutSession: ResolvedSettings;
+    scenarioDrafts?: ScenarioDraft[];
+}
+```
+
+### TeamInfo
+
+Who a team is: the fields every team entry in the SDK carries.
+
+```ts
+interface TeamInfo {
+    teamId: string;
+    index: number;
+    name: string;
+}
+```
+
+### 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;
+}
+```
+
+## Types
+
+### MutationResult
+
+What a mutation settled as.
+
+```ts
+type MutationResult =
+    | {
+          ok: true;
+          committedAtTick?: number;
+      }
+    | {
+          ok: false;
+          outcome: MutationOutcome;
+      };
+```
+
+### ResolvedSettings
+
+Resolved settings, keyed by settings identifier.
+
+```ts
+type ResolvedSettings = Record<string, Record<string, unknown>>;
+```
+
+### SessionMode
+
+How a session runs its teams: the game's `teams.mode`.
+
+```ts
+type SessionMode = GameTeamMode;
+```

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

@@ -0,0 +1,214 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk/testing`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk/testing`
+
+Helpers for unit-testing a game's logic without a runtime.
+
+`logicArgs` builds the arguments object a logic function takes, filling
+everything the test does not name. `createStubCallbacks` is the offline,
+deterministic set of callbacks it uses, and the stubs behind it are the ones
+`createTestSession` answers service callbacks with.
+
+To test a game as a whole (hooks, validators, endpoints, undo, timers), use
+`createTestSession` from `@seriousgaming/sdk-tools/client`.
+
+Every export of `@seriousgaming/sdk/testing`, 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
+
+### createStubCallbacks
+
+Every callback logic can receive, stubbed, for calling a logic function directly in a unit test.
+
+```ts
+function createStubCallbacks(): Required<SignatureCallbacks>;
+```
+
+### stubExtractText
+
+What a stubbed `extractText` answers: `[stub] text of <reference>`, without reading the file.
+
+```ts
+function stubExtractText(reference: string): ExtractTextResponse;
+```
+
+### stubGenerateText
+
+What a stubbed `generateText` answers for `request`: `[stub <hash>] <excerpt>`, an eight-digit hex hash of the whole request, then the first 60 characters of its prompt (the `prompt`, or the last `user` message's text) with whitespace collapsed, ending in `...` when it was cut. A request with a `jsonSchema` is answered with JSON that satisfies it.
+
+```ts
+function stubGenerateText(request: LLMGenerateOptions | string): LLMResponse;
+```
+
+### stubSpeechAudio
+
+The clip a stubbed `generateSpeech` stores: 100ms of 8-bit mono silence, as a WAV file.
+
+```ts
+function stubSpeechAudio(): Uint8Array;
+```
+
+## Constants
+
+### logicArgs
+
+Builders for each logic function's arguments. Each takes what the test names and fills the rest:
+
+```ts
+const logicArgs: {
+    init: typeof init;
+    run: typeof run;
+    aggregate: typeof aggregate;
+    hook: typeof hook;
+    endpoint: typeof endpoint;
+    tickController: typeof tickController;
+    validator: typeof validator;
+    requestTick: typeof requestTick;
+};
+```
+
+### STUB_SPEECH_DURATION_MS
+
+How long the stubbed speech clip is, in milliseconds.
+
+```ts
+const STUB_SPEECH_DURATION_MS = 100;
+```
+
+### TEST_NOW
+
+The `meta.now` every builder uses unless told otherwise: 2026-01-01T00:00:00Z.
+
+```ts
+const TEST_NOW: number;
+```
+
+### TEST_SEED
+
+The `meta.seed` every builder uses unless told otherwise.
+
+```ts
+const TEST_SEED = 'test-seed';
+```
+
+## Types
+
+### AggregateArgsInput
+
+Input to `logicArgs.aggregate`.
+
+```ts
+type AggregateArgsInput<
+    TTeamContext,
+    TSharedContext,
+    TSettings,
+    TCallbacks,
+    TTeamState,
+    TSharedState,
+> = CommonInput<TCallbacks> &
+    SettingsInput<TSettings> &
+    (Empty extends TSharedContext
+        ? {
+              shared?: AggregateFunctionShared<TSharedContext, TSharedState>;
+          }
+        : {
+              shared: AggregateFunctionShared<TSharedContext, TSharedState>;
+          }) & {
+        teams: (Omit<AggregateFunctionTeam<TTeamContext, TTeamState>, 'teamId'> & {
+            teamId?: string;
+        })[];
+        meta?: Partial<RunMeta>;
+    };
+```
+
+### EndpointArgsInput
+
+Input to `logicArgs.endpoint`.
+
+```ts
+type EndpointArgsInput<TRequest, TContext, TCallbacks, TTeamContext, TSettings> =
+    CommonInput<TCallbacks> &
+        SettingsInput<TSettings> & {
+            request: TRequest;
+            context: TContext;
+            caller?: Partial<EndpointCaller>;
+            team?: Partial<TeamInfo>;
+            teams?: EndpointTeamEntry<TTeamContext>[];
+            session?: Partial<EndpointSession>;
+            meta?: Partial<LogicMeta>;
+        };
+```
+
+### EngineArgsInput
+
+Input to `logicArgs.init` and `logicArgs.run`.
+
+```ts
+type EngineArgsInput<TContext, TSettings, TCallbacks, TState> = CommonInput<TCallbacks> &
+    SettingsInput<TSettings> & {
+        context: TContext;
+        meta?: Partial<TeamRunMeta>;
+        state?: TState;
+    };
+```
+
+### HookArgsInput
+
+Input to `logicArgs.hook`.
+
+```ts
+type HookArgsInput<
+    S extends HookSignal,
+    TContext,
+    TSettings,
+    TCallbacks,
+> = CommonInput<TCallbacks> &
+    SettingsInput<TSettings> &
+    HookPayloadMap[S] & {
+        signal?: S;
+        context: TContext;
+        meta?: Partial<LogicMeta>;
+    };
+```
+
+### RequestTickArgsInput
+
+Input to `logicArgs.requestTick`.
+
+```ts
+type RequestTickArgsInput<TContext, TSettings> = SettingsInput<TSettings> & {
+    context: TContext;
+    requestedTick?: number;
+    actor?: ValidatorActor;
+    meta?: Partial<LogicMeta>;
+    participants?: readonly Readonly<Participant>[];
+};
+```
+
+### TickControllerArgsInput
+
+Input to `logicArgs.tickController`.
+
+```ts
+type TickControllerArgsInput<TContext, TSettings, TCallbacks> = CommonInput<TCallbacks> &
+    SettingsInput<TSettings> & {
+        context: TContext;
+        meta?: Partial<TeamRunMeta>;
+        teams?: AggregateFunctionTeam<TContext>[];
+        waitingRoomOpen?: boolean;
+    };
+```
+
+### ValidatorArgsInput
+
+Input to `logicArgs.validator`.
+
+```ts
+type ValidatorArgsInput<TContext, TSettings> = SettingsInput<TSettings> & {
+    previous: TContext;
+    next: TContext;
+    actor?: ValidatorActor;
+    meta?: Partial<LogicMeta>;
+    participants?: readonly Readonly<Participant>[];
+};
+```