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

package/lib/build/timer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The host's automatic tick timer, as every reader sees it (§12.3).
+ *
+ * One shape wherever a timer appears: the `setTimer` payload a game surface
+ * receives, each team's entry in a session surface's `SessionData`, an
+ * endpoint's `session.teams[].timer`, and the state projection (§20).
+ * Durations are milliseconds and end in `Ms`; timestamps are milliseconds
+ * since the epoch and end in `At`.
+ *
+ * The host pushes a new value whenever the *schedule* changes (a new tick is
+ * scheduled, the timer pauses or resumes, the controller disables ticking).
+ * It does not push one every second: a surface that wants a live countdown
+ * computes it from `nextTickAt` in a local `requestAnimationFrame` (or
+ * `setInterval`) loop, which keeps React out of the per-frame path.
+ *
+ * `nextTickAt` is in the same clock-space as `Date.now()`, so the remaining
+ * time is `nextTickAt - Date.now()`. Hosts are responsible for stamping it in
+ * a clock the consumer recognises: automatic for a browser on the same machine
+ * as the host, NTP-synced clocks across machines. The wrapper does not
+ * estimate clock skew, since with only two timestamps it cannot be told apart
+ * from message staleness.
+ */
+export interface TimerState {
+    /**
+     * Whether the tick controller currently has automatic ticking enabled.
+     * When false, no countdown should be shown: the game is manual-tick only,
+     * or the controller has decided to stop scheduling.
+     */
+    enabled: boolean;
+    /** Whether the host has paused automatic ticking. */
+    paused: boolean;
+    /**
+     * When the next automatic tick is due (epoch milliseconds, in `Date.now()`
+     * space). Null when nothing is scheduled: paused, complete, or `enabled`
+     * is false.
+     */
+    nextTickAt: number | null;
+    /**
+     * The full length of the currently scheduled window in milliseconds, within
+     * the §11.8 bounds. Useful for progress bars (`elapsed / intervalMs`). Null
+     * when nothing is scheduled.
+     */
+    intervalMs: number | null;
+    /**
+     * When the current pause began (epoch milliseconds), or null when the timer
+     * is not paused.
+     */
+    pausedAt: number | null;
+    /**
+     * Total paused time in milliseconds since the schedule started, not
+     * counting the current pause. Combine with `pausedAt` for a live total:
+     *
+     * ```ts
+     * const livePausedMs = timer.pausedMs + (timer.pausedAt ? Date.now() - timer.pausedAt : 0);
+     * ```
+     */
+    pausedMs: number;
+    /**
+     * How far facilitator extensions have moved the *currently scheduled* tick,
+     * in milliseconds. Positive when the deadline was pushed out, negative when
+     * it was pulled in, and 0 for an unadjusted window. Resets with each newly
+     * scheduled tick, so it describes this window rather than the session.
+     *
+     * Read it to say what happened rather than inferring it from a moved
+     * `nextTickAt`: a deadline that jumped could equally be a fresh schedule,
+     * and 'extended by 2m' is worth showing the room.
+     */
+    extendedMs: number;
+    /**
+     * When the current schedule first started (epoch milliseconds), or null
+     * when no schedule has started yet.
+     */
+    scheduleStartedAt: number | null;
+}

package/lib/build/timer.js

@@ -0,0 +1 @@
+export {};

package/lib/build/validators.d.ts

@@ -0,0 +1,116 @@
+import { Participant } from './hooks.js';
+import { LogicMeta } from './signatures.js';
+/**
+ * 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.
+ */
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Who submitted the mutation a validator is gating.
+ *
+ * A union rather than an optional participant, because the two cases are not
+ * 'identity, or the absence of it'. They are two different callers, and a rule
+ * that means something different for each has to say which it is handling. The
+ * shape makes that unavoidable: `participant` is unreachable until `role` has
+ * been narrowed, so a validator cannot read an identity it has not first
+ * decided it has.
+ *
+ * An observer is a facilitator watching one team on that team's own play
+ * surface (§13.3). They are rendered the same user interface a participant is,
+ * with the same controls, so their writes are put to validators on the same
+ * terms. A game that wants a facilitator to be able to do what a participant
+ * cannot says so here, deliberately, rather than the runtime deciding it for
+ * every game at once.
+ */
+export type ValidatorActor = {
+    role: 'participant';
+    participant: Participant;
+}
+/** An observer holds no participant record, so the team is all there is. */
+ | {
+    role: 'observer';
+    teamId: string;
+};
+/**
+ * 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.
+ */
+export interface ValidatorFunctionArgs<TContext, TSettings> {
+    previous: TContext;
+    next: TContext;
+    actor: ValidatorActor;
+    /**
+     * The settings resources this resource declared in `settings`, keyed by
+     * identifier: resolved from their defaults, the active scenario and the
+     * session's overrides, and fixed when play starts (§8). Read-only.
+     */
+    settings: TSettings;
+    /**
+     * The facts true of the whole run: its locale, its seed, whether it is the
+     * game being played or a walkthrough beside it, and when this run of the
+     * validators started (`now`).
+     *
+     * A validator gates a participant's action rather than running as part of
+     * a tick, so this is {@link LogicMeta} rather than the `RunMeta` an engine
+     * receives. Use `locale` to phrase a rejection in the session's language.
+     */
+    meta: LogicMeta;
+    /**
+     * The participants on the actor's team, taken when the validators started
+     * (§15.3). Read-only, and a copy per call.
+     */
+    participants: readonly Readonly<Participant>[];
+}
+/**
+ * A validator's `UpdateData` export: the gate on a participant's context
+ * write. Engines, hooks, endpoints and a session surface bypass it
+ * (system-trusted).
+ */
+export type ValidatorFunction<TContext = unknown, TSettings = unknown> = (args: ValidatorFunctionArgs<TContext, TSettings>) => Promise<ValidationResult>;
+/** Arguments of a validator's `RequestTick` gate. */
+export interface RequestTickFunctionArgs<TContext, TSettings> {
+    /**
+     * The requesting team's board as it stands. A request changes nothing
+     * until the tick runs, so there is no `previous` and `next`: gate on the
+     * board, such as a pacing capability the facilitator sets.
+     */
+    context: TContext;
+    /**
+     * The tick the request would run: the requesting team's head tick plus
+     * one, so a first request asks for tick 1.
+     */
+    requestedTick: number;
+    actor: ValidatorActor;
+    /**
+     * The settings resources this resource declared in `settings`, keyed by
+     * identifier: resolved from their defaults, the active scenario and the
+     * session's overrides, and fixed when play starts (§8). Read-only.
+     */
+    settings: TSettings;
+    meta: LogicMeta;
+    /** The participants on the requesting team, as `UpdateData` receives them. */
+    participants: readonly Readonly<Participant>[];
+}
+/**
+ * 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.
+ */
+export type RequestTickFunction<TContext = unknown, TSettings = unknown> = (args: RequestTickFunctionArgs<TContext, TSettings>) => Promise<ValidationResult>;
+/**
+ * A single validator rejection returned to the caller. The runtime collects
+ * every rejection (form-style UX) rather than short-circuiting on the first.
+ */
+export interface ValidationRejection {
+    validatorIdentifier: string;
+    message: string;
+}

package/lib/build/validators.js

@@ -0,0 +1 @@
+export {};

package/lib/commands.d.ts

@@ -0,0 +1,357 @@
+/**
+ * What a client may ask a session to do (§20).
+ *
+ * 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.
+ */
+import type { PastStateEntry, PastStateQuery } from './build/callbacks.js';
+import type { EndpointFailure } from './build/endpoints.js';
+import type { ViewerRole } from './build/signatures.js';
+import type { EndpointAuditEntry, FaultKind, StateProjection } from './projection.js';
+/** Addresses one team by its stable index, or the session when absent. */
+export interface TeamScope {
+    /** Stable team index (§5.6), not an array position. */
+    teamIndex?: number;
+}
+/** Who is asking, where the operation is one a participant can perform. */
+export interface Actor {
+    participantId?: string;
+    teamId?: string;
+    /**
+     * What the host holds the sending surface as, where it holds it as
+     * anything (§13.3).
+     *
+     * Absence of `participantId` is not on its own a statement that nobody is
+     * asking: the CLI, a session surface and an observer all write without
+     * one, and so did a player surface whose slot the console had failed to
+     * resolve. The first three are deliberately identity-free and system
+     * trusted; the fourth was a participant's write being taken as one. The
+     * role separates them, so the session can refuse what it cannot attribute
+     * instead of trusting it.
+     *
+     * Host bookkeeping, never a claim the guest makes: the console resolves it
+     * from the route and the roster, exactly as it resolves `participantId`.
+     */
+    viewerRole?: ViewerRole;
+}
+export type { ViewerRole };
+/**
+ * Every state-changing operation. Each one goes through the session's single
+ * queue, in submission order (§9.7).
+ */
+export type MutationCommand = 
+/**
+ * A tick. `Actor` is present when a participant's or observer's surface
+ * asked for it (§15), which puts it to the validators gating
+ * `requestTick`; a facilitator's, the CLI's or a timer's carries none.
+ */
+({
+    type: 'tick';
+} & TeamScope & Actor) | ({
+    type: 'undo';
+} & TeamScope) | ({
+    type: 'reset';
+} & TeamScope)
+/** Leave the configuration stage and initialise (§8.3). */
+ | {
+    type: 'play';
+}
+/**
+ * Go back to the configuration stage, for a game that has one.
+ *
+ * The inverse of `play`, and a reset with it: configuration is resolved
+ * when the session initialises (§8.2), so changing it after the fact only
+ * means anything if the session starts again on the new values.
+ */
+ | {
+    type: 'reconfigure';
+}
+/**
+ * Reinitialise the session from the package, as if it had just started.
+ *
+ * Distinct from `reset`, which returns the session to its own tick 0 with
+ * the scenario, team count and locale it has. This re-resolves all three,
+ * so an omitted `scenarioId` goes back to the package's default rather than
+ * staying on whatever is active.
+ */
+ | {
+    type: 'reinitialise';
+    teams?: number;
+    scenarioId?: string | null;
+    locale?: string;
+    /**
+     * Participants to seed each team with: one count for every team, or
+     * one per team. Zero is allowed. Kept for later re-initialisations,
+     * like `teams`, until a new team count leaves a per-team list behind.
+     */
+    participants?: number | number[];
+} | ({
+    type: 'updateContext';
+    payload: Record<string, unknown>;
+    /** Paths to remove after the payload merges (§9.5). */
+    deletes?: (string | string[])[];
+    /**
+     * The player surface the write came from, supplied by the host from
+     * what it mounted and never by the page. The write is held to that
+     * surface's `writes` (§9.5). Absent for a system-trusted caller: the
+     * session surface, the CLI, or logic.
+     */
+    uiIdentifier?: string;
+    /**
+     * The session surface a facilitator's team write came from, supplied
+     * by the host like `uiIdentifier`. The payload may change only
+     * capabilities that surface declares in `writes`, and may carry
+     * another capability unchanged; every path in `deletes` must name a
+     * team-scope capability it writes (§9.5.1). Absent for every other
+     * caller.
+     */
+    sessionUiIdentifier?: string;
+} & TeamScope & Actor)
+/**
+ * A shared-store write (§9.5.1). Exactly one of the two identifiers is
+ * present, and it names what authorised the write: a session surface's
+ * `writes` array for a facilitator write, or a session-scoped endpoint's
+ * for one of its patches (§6.12). An endpoint has no surface to borrow an
+ * identifier from, and a facilitator agent calling one has no bundle at all.
+ */
+ | {
+    type: 'updateSharedContext';
+    uiIdentifier?: string;
+    endpointIdentifier?: string;
+    payload: Record<string, unknown>;
+    /**
+     * Paths to remove from the store after the payload merges (§9.5), each
+     * under a shared capability the writer declares. Set by a
+     * session-scoped endpoint's `deletes` (§6.12).
+     */
+    deletes?: (string | string[])[];
+}
+/**
+ * Write into the session-override layer (§8.2). `uiIdentifier` names the
+ * settings editor that sent it, which may change only what it
+ * `configures` (§6.5); a caller naming none is system-trusted.
+ */
+ | {
+    type: 'updateSettings';
+    uiIdentifier?: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * Open the scenario editor's draft of a scenario (§6.5), or of none for
+ * one started from the package's own settings. A draft already open on
+ * it is kept. The draft belongs to no session: it is resolved from the
+ * scenario, never from the session's override layer, and reaches a
+ * session only once it is saved as a scenario.
+ */
+ | {
+    type: 'editScenario';
+    scenarioId: string | null;
+}
+/** What the scenario editor sends in `updateSettings`: an edit to its draft (§6.5). */
+ | {
+    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;
+}
+/** From a player surface; the host resolves the team (§12.5). */
+ | ({
+    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;
+}
+/**
+ * Throw the walkthrough away and start it again at tick 0 (§5.7).
+ *
+ * Handled by the host rather than by a session: it replaces the run a
+ * command would otherwise be addressed to, so the run cannot settle it.
+ */
+ | {
+    type: 'resetWalkthrough';
+} | {
+    type: 'selectScenario';
+    scenarioId: string | null;
+} | {
+    type: 'setLocale';
+    locale: string;
+} | ({
+    type: 'pauseTimer';
+} & TeamScope) | ({
+    type: 'resumeTimer';
+} & TeamScope) | ({
+    type: 'extendTick';
+    byMs: number;
+} & TeamScope)
+/**
+ * Move a fake clock forward, running every automatic tick that comes due.
+ * Refused on the real clock: only `sdk dev --fake-clock` starts a session
+ * whose time can be moved by hand.
+ */
+ | {
+    type: 'advanceClock';
+    byMs: number;
+}
+/**
+ * Arm a failure this runtime cannot otherwise produce (§3.3 of the design).
+ *
+ * @internal The SDK dev server's fault injection; see `FaultKind`.
+ */
+ | {
+    type: 'armFault';
+    fault: FaultKind;
+    times?: number;
+    reason?: string;
+}
+/** @internal The SDK dev server's fault injection; see `FaultKind`. */
+ | {
+    type: 'disarmFault';
+    fault: FaultKind;
+};
+/**
+ * Every read. None of these enters the queue: a read is never blocked behind a
+ * mutation (§9.7), so a tick in flight must not delay one.
+ */
+export type QueryCommand = {
+    type: 'getState';
+}
+/**
+ * `uiIdentifier` names the calling surface, whose `endpoints` allowlist
+ * bounds what it may call (§6.12). `external` marks a caller outside the
+ * game, such as a facilitator's AI agent, which names no surface and
+ * reaches only an endpoint whose `visibility` is `external`.
+ */
+ | ({
+    type: 'callEndpoint';
+    endpointIdentifier: string;
+    request: unknown;
+    uiIdentifier?: string;
+    external?: boolean;
+    /**
+     * Who is behind an external call, as the host authenticated them.
+     * Accepted only with `external`, and passed to the endpoint as
+     * `caller.principal`.
+     */
+    principal?: {
+        kind: string;
+        id: string;
+        name?: string;
+    };
+    /**
+     * The scenario a call from the scenario editor is editing, whose
+     * draft the endpoint's settings resolve from (§6.5, §6.12). Null for
+     * an editor opened on no scenario; absent for the one in force.
+     */
+    scenarioId?: string | null;
+} & TeamScope & Actor)
+/**
+ * `uiIdentifier` names the asking surface, whose declarations bound what
+ * it may read (§12.5). Omitted for a caller with no surface, such as the
+ * CLI, which is system-trusted.
+ */
+ | ({
+    type: 'getPastState';
+    query: PastStateQuery;
+    uiIdentifier?: string;
+} & Actor) | ({
+    type: 'getAllTeamsParticipants';
+    uiIdentifier?: string;
+} & Actor)
+/** Endpoint calls that changed something, oldest first (§6.12). */
+ | {
+    type: 'getEndpointAudit';
+}
+/**
+ * The package's endpoints, as a caller outside the game discovers them:
+ * what each is for, what it takes and returns, and what it may change.
+ * `external` narrows the list to the ones such a caller may call.
+ */
+ | {
+    type: 'listEndpoints';
+    external?: boolean;
+};
+/** One endpoint, as `listEndpoints` describes it. */
+export interface EndpointListing {
+    identifier: string;
+    displayName?: string;
+    description?: string;
+    scope: 'session' | 'team';
+    visibility: 'internal' | 'external';
+    requestSchema: Record<string, unknown>;
+    responseSchema: Record<string, unknown>;
+    /**
+     * Capabilities it may change, and session actions it may carry out. An
+     * agent host deciding whether a call needs a person's approval reads these:
+     * an endpoint that only reads is a different request from one that ticks.
+     */
+    writes: string[];
+    actions: string[];
+}
+export type Command = MutationCommand | QueryCommand;
+/** What a query answered with. */
+export type QueryResult = {
+    type: 'state';
+    state: StateProjection;
+}
+/**
+ * `blobs` is present on an external call whose response carries `blob:`
+ * references: each one resolved to a URL the caller can fetch it from,
+ * because a caller outside the game has no `getAssetUrl` of its own.
+ */
+ | {
+    type: 'endpoint';
+    response: unknown;
+    blobs?: Record<string, string>;
+}
+/**
+ * A `callEndpoint` that failed (§6.12): why, and which of its effects had
+ * already landed. An answer rather than a throw, so every transport
+ * carries it unchanged.
+ */
+ | {
+    type: 'endpointFailure';
+    failure: EndpointFailure;
+} | {
+    type: 'pastState';
+    entries: PastStateEntry[];
+} | {
+    type: 'participants';
+    participants: unknown[];
+} | {
+    type: 'endpointAudit';
+    entries: EndpointAuditEntry[];
+} | {
+    type: 'endpoints';
+    endpoints: EndpointListing[];
+};

package/lib/commands.js

@@ -0,0 +1,14 @@
+/**
+ * What a client may ask a session to do (§20).
+ *
+ * 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.
+ */
+export {};