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

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

@@ -0,0 +1,286 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk/commands`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk/commands`
+
+What a client may ask a session to do.
+
+One closed command set, shared by every client of the dev server: the
+browser console, the CLI, a Playwright suite through `runCommand`, and an
+agent posting to `/api/command`. Published from the SDK rather than declared
+inside the runtime so a test is type-checked against the commands the
+runtime actually accepts, and a misspelled field fails to compile rather
+than coming back as a 400.
+
+The runtime that validates these at its boundary lives in the tools
+package. This module is types only.
+
+Every export of `@seriousgaming/sdk/commands`, 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.
+
+## Interfaces
+
+### Actor
+
+Who is asking, where the operation is one a participant can perform.
+
+```ts
+interface Actor {
+    participantId?: string;
+    teamId?: string;
+    viewerRole?: ViewerRole;
+}
+```
+
+### EndpointListing
+
+One endpoint, as `listEndpoints` describes it.
+
+```ts
+interface EndpointListing {
+    identifier: string;
+    displayName?: string;
+    description?: string;
+    scope: 'session' | 'team';
+    visibility: 'internal' | 'external';
+    requestSchema: Record<string, unknown>;
+    responseSchema: Record<string, unknown>;
+    writes: string[];
+    actions: string[];
+}
+```
+
+### TeamScope
+
+Addresses one team by its stable index, or the session when absent.
+
+```ts
+interface TeamScope {
+    teamIndex?: number;
+}
+```
+
+## Types
+
+### Command
+
+```ts
+type Command = MutationCommand | QueryCommand;
+```
+
+### MutationCommand
+
+Every state-changing operation. Each one goes through the session's single queue, in submission order.
+
+```ts
+type MutationCommand =
+    | ({
+          type: 'tick';
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'undo';
+      } & TeamScope)
+    | ({
+          type: 'reset';
+      } & TeamScope)
+    | {
+          type: 'play';
+      }
+    | {
+          type: 'reconfigure';
+      }
+    | {
+          type: 'reinitialise';
+          teams?: number;
+          scenarioId?: string | null;
+          locale?: string;
+          participants?: number | number[];
+      }
+    | ({
+          type: 'updateContext';
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+          uiIdentifier?: string;
+          sessionUiIdentifier?: string;
+      } & TeamScope &
+          Actor)
+    | {
+          type: 'updateSharedContext';
+          uiIdentifier?: string;
+          endpointIdentifier?: string;
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+      }
+    | {
+          type: 'updateSettings';
+          uiIdentifier?: string;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'editScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'updateScenarioDraft';
+          uiIdentifier?: string;
+          scenarioId: string | null;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'addTeam';
+          name?: string;
+          participants?: number;
+      }
+    | {
+          type: 'removeTeam';
+          teamIndex: number;
+      }
+    | {
+          type: 'renameTeam';
+          teamId: string;
+          name: string;
+      }
+    | ({
+          type: 'renameOwnTeam';
+          name: string;
+      } & Actor)
+    | {
+          type: 'addParticipant';
+          teamId: string;
+          name?: string;
+      }
+    | {
+          type: 'renameParticipant';
+          participantId: string;
+          name: string;
+      }
+    | {
+          type: 'moveParticipant';
+          participantId: string;
+          teamId: string;
+      }
+    | {
+          type: 'setWaitingRoom';
+          open: boolean;
+      }
+    | {
+          type: 'resetWalkthrough';
+      }
+    | {
+          type: 'selectScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'setLocale';
+          locale: string;
+      }
+    | ({
+          type: 'pauseTimer';
+      } & TeamScope)
+    | ({
+          type: 'resumeTimer';
+      } & TeamScope)
+    | ({
+          type: 'extendTick';
+          byMs: number;
+      } & TeamScope)
+    | {
+          type: 'advanceClock';
+          byMs: number;
+      }
+    | {
+          type: 'armFault';
+          fault: FaultKind;
+          times?: number;
+          reason?: string;
+      }
+    | {
+          type: 'disarmFault';
+          fault: FaultKind;
+      };
+```
+
+### QueryCommand
+
+Every read. None of these enters the queue: a read is never blocked behind a mutation, so a tick in flight must not delay one.
+
+```ts
+type QueryCommand =
+    | {
+          type: 'getState';
+      }
+    | ({
+          type: 'callEndpoint';
+          endpointIdentifier: string;
+          request: unknown;
+          uiIdentifier?: string;
+          external?: boolean;
+          principal?: {
+              kind: string;
+              id: string;
+              name?: string;
+          };
+          scenarioId?: string | null;
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'getPastState';
+          query: PastStateQuery;
+          uiIdentifier?: string;
+      } & Actor)
+    | ({
+          type: 'getAllTeamsParticipants';
+          uiIdentifier?: string;
+      } & Actor)
+    | {
+          type: 'getEndpointAudit';
+      }
+    | {
+          type: 'listEndpoints';
+          external?: boolean;
+      };
+```
+
+### QueryResult
+
+What a query answered with.
+
+```ts
+type QueryResult =
+    | {
+          type: 'state';
+          state: StateProjection;
+      }
+    | {
+          type: 'endpoint';
+          response: unknown;
+          blobs?: Record<string, string>;
+      }
+    | {
+          type: 'endpointFailure';
+          failure: EndpointFailure;
+      }
+    | {
+          type: 'pastState';
+          entries: PastStateEntry[];
+      }
+    | {
+          type: 'participants';
+          participants: unknown[];
+      }
+    | {
+          type: 'endpointAudit';
+          entries: EndpointAuditEntry[];
+      }
+    | {
+          type: 'endpoints';
+          endpoints: EndpointListing[];
+      };
+```
+
+### ViewerRole
+
+Which viewer a player surface is being rendered for.
+
+```ts
+type ViewerRole = 'participant' | 'observer';
+```

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

@@ -0,0 +1,433 @@
+<!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk/e2e`. Edit those, not this file. -->
+
+# `@seriousgaming/sdk/e2e`
+
+End-to-end testing helpers for Serious Gaming SDK consumers.
+
+Selectors and API helpers for writing Playwright tests against a game running
+on the dev server. No dependency on Playwright itself — pass the selectors to
+your own `page.locator()` / `page.frameLocator()` calls.
+
+What you drive is your own game's surface inside the iframe; the console
+around it is a handful of URLs and one drawer, which is why this module is
+mostly URLs. Three things are worth knowing before writing a test:
+
+- Every surface is directly addressable. `/team/2/player/1` is the first
+  participant of the second team, with no lookup and no redirect.
+- `?bare` removes the dev chrome entirely, so a change to the console cannot
+  fail a test about your game. {@link DEV_SERVER.bare} adds it to any URL.
+- The helpers address the server `SERIOUSGAMING_DEV_URL` names, which is
+  what a Playwright `globalSetup` running `startDevServer` sets, so a test
+  on free ports passes no options. `{ url }` or `{ port }` picks another.
+
+@example
+
+```typescript
+import { DEV_SERVER, runCommand, getState } from '@seriousgaming/sdk/e2e';
+
+test('the dashboard shows the tick', async ({ page }) => {
+    await runCommand({ type: 'reset' });
+    await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+
+    const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+    await expect(frame.locator('#tick')).toHaveText('0');
+
+    await runCommand({ type: 'tick' });
+    await expect(frame.locator('#tick')).toHaveText('1');
+});
+```
+
+Every export of `@seriousgaming/sdk/e2e`, 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
+
+### advanceClock
+
+Move the clock of a dev server started with `--fake-clock` forward, running every automatic tick that falls due on the way. Resolves once they have run.
+
+```ts
+function advanceClock(ms: number, options?: DevServerOptions): Promise<void>;
+```
+
+### getState
+
+The whole session, as one projection: teams, contexts, participants, the resolved configuration, the timer, and anything the runtime has gone wrong about. Assert on state without going through a surface.
+
+```ts
+function getState(options?: DevServerOptions): Promise<StateProjection>;
+```
+
+### reinitialiseSession
+
+Start the session again from the package, as a test's known starting point.
+
+```ts
+function reinitialiseSession(options?: ReinitialiseOptions): Promise<void>;
+```
+
+### resetSession
+
+Return the session to tick 0, so one test does not inherit another's state. Call it in `test.beforeEach`.
+
+```ts
+function resetSession(options?: DevServerOptions): Promise<void>;
+```
+
+### runCommand
+
+Run one command against the running session.
+
+```ts
+function runCommand(command: MutationCommand, options?: DevServerOptions): Promise<MutationResult>;
+function runCommand(command: QueryCommand, options?: DevServerOptions): Promise<QueryResult>;
+```
+
+### waitForState
+
+Wait until the session satisfies `predicate`, and return the state that did.
+
+```ts
+function waitForState(
+    predicate: (state: StateProjection) => boolean,
+    options?: WaitOptions
+): Promise<StateProjection>;
+```
+
+## Constants
+
+### DEV_SERVER
+
+Selectors and URLs for the dev console.
+
+```ts
+const DEV_SERVER: {
+    readonly DEFAULT_PORT: 3000;
+    readonly selectors: {
+        readonly devDrawerHandle: '[data-testid="dev-drawer-handle"]';
+        readonly devDrawer: '[data-testid="dev-drawer"]';
+        readonly localeSelect: '[data-testid="locale"]';
+        readonly play: '[data-testid="play"]';
+        readonly guideContent: '[data-testid="guide-content"]';
+        readonly printSheets: '[data-testid="print-sheets"]';
+    };
+    readonly consoleUrl: () => string;
+    readonly playerUrl: (team: number, participant?: number) => string;
+    readonly observeUrl: (team: number) => string;
+    readonly waitingRoomUrl: (team: number) => string;
+    readonly joinUrl: (team: number) => string;
+    readonly setupUrl: () => string;
+    readonly scenarioEditorUrl: (scenario: string) => string;
+    readonly guideUrl: () => string;
+    readonly printUrl: () => string;
+    readonly bare: (url: string) => string;
+    readonly iframeSelector: (identifier: string) => string;
+    readonly apiUrl: (path: string, port?: number) => string;
+};
+```
+
+## Interfaces
+
+### DevServerOptions
+
+Which dev server a helper talks to. With neither field set, the server `SERIOUSGAMING_DEV_URL` names (as `startDevServer` in a Playwright `globalSetup` sets it), or else `localhost` on `DEV_SERVER_DEFAULT_PORT`.
+
+```ts
+interface DevServerOptions {
+    url?: string;
+    port?: number;
+    run?: RunKind;
+}
+```
+
+### ReinitialiseOptions
+
+```ts
+interface ReinitialiseOptions extends DevServerOptions {
+    teams?: number;
+    participants?: number | number[];
+    scenarioId?: string | null;
+    locale?: string;
+    play?: boolean;
+}
+```
+
+### 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[];
+}
+```
+
+### WaitOptions
+
+```ts
+interface WaitOptions extends DevServerOptions {
+    timeout?: number;
+    interval?: number;
+}
+```
+
+## Types
+
+### Command
+
+```ts
+type Command = MutationCommand | QueryCommand;
+```
+
+### MutationCommand
+
+Every state-changing operation. Each one goes through the session's single queue, in submission order.
+
+```ts
+type MutationCommand =
+    | ({
+          type: 'tick';
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'undo';
+      } & TeamScope)
+    | ({
+          type: 'reset';
+      } & TeamScope)
+    | {
+          type: 'play';
+      }
+    | {
+          type: 'reconfigure';
+      }
+    | {
+          type: 'reinitialise';
+          teams?: number;
+          scenarioId?: string | null;
+          locale?: string;
+          participants?: number | number[];
+      }
+    | ({
+          type: 'updateContext';
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+          uiIdentifier?: string;
+          sessionUiIdentifier?: string;
+      } & TeamScope &
+          Actor)
+    | {
+          type: 'updateSharedContext';
+          uiIdentifier?: string;
+          endpointIdentifier?: string;
+          payload: Record<string, unknown>;
+          deletes?: (string | string[])[];
+      }
+    | {
+          type: 'updateSettings';
+          uiIdentifier?: string;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'editScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'updateScenarioDraft';
+          uiIdentifier?: string;
+          scenarioId: string | null;
+          payload: Record<string, unknown>;
+      }
+    | {
+          type: 'addTeam';
+          name?: string;
+          participants?: number;
+      }
+    | {
+          type: 'removeTeam';
+          teamIndex: number;
+      }
+    | {
+          type: 'renameTeam';
+          teamId: string;
+          name: string;
+      }
+    | ({
+          type: 'renameOwnTeam';
+          name: string;
+      } & Actor)
+    | {
+          type: 'addParticipant';
+          teamId: string;
+          name?: string;
+      }
+    | {
+          type: 'renameParticipant';
+          participantId: string;
+          name: string;
+      }
+    | {
+          type: 'moveParticipant';
+          participantId: string;
+          teamId: string;
+      }
+    | {
+          type: 'setWaitingRoom';
+          open: boolean;
+      }
+    | {
+          type: 'resetWalkthrough';
+      }
+    | {
+          type: 'selectScenario';
+          scenarioId: string | null;
+      }
+    | {
+          type: 'setLocale';
+          locale: string;
+      }
+    | ({
+          type: 'pauseTimer';
+      } & TeamScope)
+    | ({
+          type: 'resumeTimer';
+      } & TeamScope)
+    | ({
+          type: 'extendTick';
+          byMs: number;
+      } & TeamScope)
+    | {
+          type: 'advanceClock';
+          byMs: number;
+      }
+    | {
+          type: 'armFault';
+          fault: FaultKind;
+          times?: number;
+          reason?: string;
+      }
+    | {
+          type: 'disarmFault';
+          fault: FaultKind;
+      };
+```
+
+### MutationResult
+
+What a mutation settled as.
+
+```ts
+type MutationResult =
+    | {
+          ok: true;
+          committedAtTick?: number;
+      }
+    | {
+          ok: false;
+          outcome: MutationOutcome;
+      };
+```
+
+### QueryCommand
+
+Every read. None of these enters the queue: a read is never blocked behind a mutation, so a tick in flight must not delay one.
+
+```ts
+type QueryCommand =
+    | {
+          type: 'getState';
+      }
+    | ({
+          type: 'callEndpoint';
+          endpointIdentifier: string;
+          request: unknown;
+          uiIdentifier?: string;
+          external?: boolean;
+          principal?: {
+              kind: string;
+              id: string;
+              name?: string;
+          };
+          scenarioId?: string | null;
+      } & TeamScope &
+          Actor)
+    | ({
+          type: 'getPastState';
+          query: PastStateQuery;
+          uiIdentifier?: string;
+      } & Actor)
+    | ({
+          type: 'getAllTeamsParticipants';
+          uiIdentifier?: string;
+      } & Actor)
+    | {
+          type: 'getEndpointAudit';
+      }
+    | {
+          type: 'listEndpoints';
+          external?: boolean;
+      };
+```
+
+### QueryResult
+
+What a query answered with.
+
+```ts
+type QueryResult =
+    | {
+          type: 'state';
+          state: StateProjection;
+      }
+    | {
+          type: 'endpoint';
+          response: unknown;
+          blobs?: Record<string, string>;
+      }
+    | {
+          type: 'endpointFailure';
+          failure: EndpointFailure;
+      }
+    | {
+          type: 'pastState';
+          entries: PastStateEntry[];
+      }
+    | {
+          type: 'participants';
+          participants: unknown[];
+      }
+    | {
+          type: 'endpointAudit';
+          entries: EndpointAuditEntry[];
+      }
+    | {
+          type: 'endpoints';
+          endpoints: EndpointListing[];
+      };
+```