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

package/dist/core/session-ticks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Running a tick (§9.3, §5.3): whether one may run, which teams it moves, and
+ * what each team's board and history hold afterwards.
+ *
+ * The mode decides the shape. A shared-state cohort has one clock and moves
+ * as one; an independent team moves from its own tick, so a cohort tick is
+ * each team's tick in turn and never pulls a lagging team forwards. The board
+ * a tick was submitted with is recorded as the round it closes, after the
+ * engine has run, so a tick that throws leaves neither a changed board nor a
+ * round behind. A participant's request passes the validator gate first, and
+ * the timers are re-evaluated for exactly the teams that moved.
+ */
+import type { Actor, TeamScope } from './protocol';
+import type { SessionHost } from './session-host';
+type TickHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'timers' | 'mode' | 'tickLimit' | 'positionOf' | 'emit'>;
+/** Run one tick for `scope`. Returns the tick it committed. */
+export declare function tick(host: TickHost, scope: TeamScope & Actor): Promise<number>;
+export {};

package/dist/core/session-timers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The session's automatic tick timers (§11): which teams share one, when the
+ * tick controller is asked again, and what a timer firing does.
+ *
+ * A timer is armed from the controller's answer and nothing else, so the
+ * whole of this module is deciding when to ask: after a tick, after a write
+ * that changed what the controller reads (§11.1a), after the cohort changes
+ * shape, and after an automatic tick was refused. Each team has its own timer
+ * in a multi-team independent session and the cohort shares one otherwise,
+ * and that grouping is decided here once, so a pause, a resume or an extension
+ * addressed to a team reaches the timer that actually serves it.
+ */
+import type { TimerState } from '@seriousgaming/sdk';
+import type { MutationCommand, TeamScope } from './protocol';
+import type { SessionHost } from './session-host';
+type TimerHost = Pick<SessionHost, 'clock' | 'executor' | 'state' | 'mode' | 'teamBounds' | 'inSetup' | 'tickLimit' | 'positionOf' | 'report' | 'submit' | 'enqueue' | 'emitState'>;
+export declare class SessionTimers {
+    private readonly host;
+    /** True while a tick runs, so a timer firing then is dropped (§11.1). */
+    ticking: boolean;
+    /** Automatic tick timers, keyed by team index, or {@link COHORT} (§11). */
+    private readonly timers;
+    constructor(host: TimerHost);
+    /** Cancel every timer, for a session that is stopping. */
+    stop(): void;
+    /** The timer serving the team at `position`, idle when it has none. */
+    stateAt(position: number): TimerState;
+    /** The projection's session-wide timer: the cohort's, absent per-team timers. */
+    cohort(): TimerState | null;
+    pause(scope: TeamScope): void;
+    resume(scope: TeamScope): Promise<void>;
+    extend(command: Extract<MutationCommand, {
+        type: 'extendTick';
+    }>): undefined;
+    /**
+     * Evaluate every group serving one of `positions`. A `reevaluation` is
+     * the §11.1a kind, which keeps the schedule when the answer is unchanged.
+     */
+    evaluateFor(positions: number[], reevaluation?: boolean): Promise<void>;
+    /** Evaluate every group afresh, dropping timers for teams that have gone. */
+    refresh(): Promise<void>;
+    /**
+     * What the tick controller reads before `command` runs, for {@link retime}
+     * to compare against: null for a command that writes no context.
+     */
+    readsBefore(command: MutationCommand): string[] | null;
+    /** What a settled mutation means for the automatic tick timers. */
+    retime(command: MutationCommand, readsBefore: string[] | null): Promise<void>;
+    /**
+     * Which teams share a timer. Each team has its own in a multi-team
+     * independent session, because each keeps its own clock (§9.4a); every
+     * other session has one, for the cohort.
+     */
+    private groups;
+    private timerFor;
+    /** The groups a timer command addresses: one team's, or every group when none is named. */
+    private groupsIn;
+    /** Whether a group can still tick at all: not complete, not at the limit. */
+    private canAutoTick;
+    /**
+     * Ask the tick controller about one group and act on the answer (§11.1).
+     *
+     * Judged against the group's first team's own context, with `teams`
+     * carrying the group's entries: every team's in shared-state mode, the one
+     * team's in independent mode or a single-team game. A controller that
+     * throws must not take a committed tick with it, so it is reported and the
+     * timer stops, and nothing else changes.
+     */
+    private evaluate;
+    /**
+     * Each team's value of what the tick controller reads, to tell whether a
+     * write changed any of it (§11.1a). Null when it declares no reads, which
+     * means every write counts.
+     */
+    private controllerReads;
+    /**
+     * An automatic tick. Dropped when a tick is already running (§11.1): that
+     * tick re-evaluates the controller when it settles, which reschedules.
+     * One that is refused or fails is followed by a fresh evaluation, so the
+     * timer is re-armed, or stopped when the group can no longer tick.
+     */
+    private onFired;
+}
+export {};

package/dist/core/session-writes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Writes to the boards from outside logic (§9.5, §9.5.1, §8.2): a team's
+ * board, the shared store, and the session's settings layer.
+ *
+ * What makes a write legal is composition rather than the write itself. A
+ * team board is a view of its own capabilities with the shared store spread
+ * over it (§7.5), so a team-addressed write may not quietly change a shared
+ * value the other teams also read, and a shared write re-composes every view
+ * at once. Each surface is entitled by its own `writes`, checked from the
+ * bundle rather than taken on the frame's word, and the engine's private
+ * state is out of every caller's reach. Those rules, and the validator gate
+ * a participant's write passes through, are applied here before anything is
+ * stored.
+ */
+import type { MutationCommand } from './protocol';
+import type { ScenarioDrafts } from './scenario-drafts';
+import type { SessionHost } from './session-host';
+type WriteHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'mode' | 'positionOf' | 'emit' | 'declaredSurface' | 'pendingChanges'>;
+/** A team-addressed write (§9.5). Returns the tick it committed into. */
+export declare function updateContext(host: WriteHost, command: Extract<MutationCommand, {
+    type: 'updateContext';
+}>): Promise<number>;
+/** A write to the shared store (§9.5.1). Returns the tick it committed into. */
+export declare function updateSharedContext(host: WriteHost, command: Extract<MutationCommand, {
+    type: 'updateSharedContext';
+}>): Promise<number>;
+/** A change to the session's settings layer (§8.2). */
+export declare function updateSettings(host: Pick<SessionHost, 'executor' | 'declaredSurface'>, command: Extract<MutationCommand, {
+    type: 'updateSettings';
+}>): Promise<undefined>;
+/**
+ * An edit from the scenario editor, to its draft of the scenario it is open
+ * on (§6.5). Never to the session's layer: the draft belongs to no session.
+ * Reduced to what changed against the draft as it resolves now, as the
+ * session layer is, so an editor echoing back what it was sent stores nothing.
+ */
+export declare function updateScenarioDraft(host: Pick<SessionHost, 'executor' | 'declaredSurface'>, drafts: ScenarioDrafts, command: Extract<MutationCommand, {
+    type: 'updateScenarioDraft';
+}>): Promise<undefined>;
+export {};

package/dist/core/session.d.ts

@@ -0,0 +1,385 @@
+/**
+ * One live session, with no transport in it.
+ *
+ * This is the whole of what the old dev server called `server.ts` and
+ * `command-handlers.ts` minus the HTTP, the WebSocket, the Vite servers, the
+ * file watchers, and the persistence: 4,366 lines of fused concerns, of which
+ * the part that is actually about running a game is this.
+ *
+ * Everything that changes state goes through one queue, in submission order
+ * (§9.7 strategy 1, which the specification assigns to this runtime by name).
+ * Everything that reads bypasses it, because §9.7 requires that a read is never
+ * blocked behind a mutation. Those two sentences are the entire concurrency
+ * model, and they are enforced in one place rather than approximated by a lock
+ * here and a debounce there.
+ *
+ * Time arrives through {@link Clock}, so the tick schedule and its §11.8 bounds
+ * are testable without waiting for them. Nothing here touches the filesystem
+ * for session state: a session lives as long as its process, by design.
+ *
+ * The concerns a session is made of live beside it, each given the slice of
+ * the session it needs through {@link SessionHost}: the timers
+ * (`session-timers`), endpoint calls (`session-endpoints`), the validator
+ * gates (`session-gates`), writes to the boards (`session-writes`), the
+ * roster (`session-roster`), ticks (`session-ticks`) and rewinds
+ * (`session-rewind`). What stays here is the queue, the dispatch, the
+ * lifecycle and the projection.
+ */
+import type { ResolvedPackageManifest, RunKind, SDKFacilitatorGuide, SDKScenario, SignatureCallbacks } from '@seriousgaming/sdk';
+import { type EndpointAuditEntry, type MutationResult, type ResolvedSettings, type StateProjection } from '@seriousgaming/sdk/projection';
+import { type Clock } from './clock';
+import { type PendingChanges } from './pending-changes';
+import { type Command, type Event, type MutationCommand, type QueryCommand, type QueryResult } from './protocol';
+import { type ParticipantCounts } from './session-roster';
+export { participantCountsError, type ParticipantCounts } from './session-roster';
+export type { WithLogicError, WithStale } from './session-refusals';
+export interface SessionOptions {
+    packagePath: string;
+    /** Teams to start with. The manifest's bounds still apply (§5.4). */
+    teams?: number;
+    /** Participants each team is seeded with: one count for all, or one per team. */
+    participants?: ParticipantCounts;
+    /** Scenario to activate at initialisation; `null` opts out of the default. */
+    scenarioId?: string | null;
+    locale?: string;
+    seriousGamingApiKey?: string;
+    seriousGamingApiHost?: string;
+    elevenLabsApiKey?: string;
+    /** Injected so tick timing is testable. Defaults to the real clock. */
+    clock?: Clock;
+    /**
+     * Replace callbacks logic receives, such as `generateText`, so a test needs
+     * no platform key and gets the same answer every time.
+     */
+    callbacks?: Partial<SignatureCallbacks>;
+    /**
+     * Neither read nor write `.seriousgaming-sdk/configuration.json`: resolve
+     * configuration from the package alone. For a test, which must not depend
+     * on what somebody last ran `sdk configure` with, nor leave a file behind.
+     */
+    inMemory?: boolean;
+    /**
+     * Which kind of run this is (§5.7). Defaults to `'session'`: the game being
+     * played. A `'walkthrough'` session is the disposable run beside it, and
+     * differs only in what it reports to logic and surfaces — it holds one
+     * team, starts at tick 0, and never opens the waiting room, but every
+     * operation on it is the ordinary one.
+     */
+    runKind?: RunKind;
+    /**
+     * The run's surface storage key (§12.2), where it must outlive this
+     * session object: a walkthrough rebuilt by a reset is the same walkthrough
+     * to its viewers. Generated when omitted.
+     */
+    sessionKey?: string;
+    /**
+     * Re-initialise whenever an edit on disk applies only at initialisation,
+     * however far play has gone, rather than keeping the session on what it
+     * started with and recording the change as pending (#640). For a host that
+     * restarts the game on every edit, such as the hosted builder.
+     */
+    reinitOnChange?: boolean;
+}
+/** The cause a state event carries when an edit on disk restarted the game. */
+export declare const REINITIALISED_ON_CHANGE = "reinitialised-on-change";
+/** What a reload of the package did to the session. */
+export interface ReloadOutcome {
+    /**
+     * `live`: adopted with play kept where it was. `pending`: adopted in part,
+     * with the rest waiting for a re-initialisation. `reinitialised`: started
+     * over from the package. `failed`: nothing adopted, reported as an error.
+     */
+    kind: 'live' | 'pending' | 'reinitialised' | 'failed';
+    /** What is waiting now, or what a re-initialisation just applied. */
+    pending: PendingChanges;
+    /** Capabilities adopted live, seeded with their schema defaults. */
+    added: string[];
+}
+export declare class Session {
+    private readonly queue;
+    private readonly faults;
+    private readonly participants;
+    private readonly executor;
+    private readonly state;
+    private readonly clock;
+    private options;
+    private readonly listeners;
+    /** Operator-facing failures, oldest first (§14.5, and tick failures). */
+    private readonly errors;
+    private seed;
+    /**
+     * The key every surface of this run is sent on `init` (§12.2). Random and
+     * independent of anything else the session holds, so it names nothing a
+     * host would act on.
+     */
+    private readonly sessionKey;
+    /**
+     * Which kind of run this is (§5.7). Fixed at construction: `runKind` is a
+     * promise that every surface of one run reports the same value for its
+     * whole life, so there is no setter.
+     */
+    private readonly runKind;
+    private locale;
+    private waitingRoomOpen;
+    /**
+     * The scenario asked for, which is not the one that ends up active.
+     * `undefined` takes the game's default; `null` deliberately opts out of it
+     * (§6.7). Collapsing the two leaves every game running with no scenario.
+     */
+    private requestedScenarioId;
+    /** The scenario actually in force, resolved after initialisation. */
+    private scenarioId;
+    private started;
+    /** True while the game's `setup` slot still owes us a Play (§8.3). */
+    private holdingAtSetup;
+    /** Edits on disk that apply only at the next initialisation (#640). */
+    private pending;
+    /** The scenario editor's drafts, which belong to no session (§6.5). */
+    private readonly drafts;
+    /** What the parts below are handed of the session. */
+    private readonly host;
+    private readonly timers;
+    private readonly endpoints;
+    private readonly roster;
+    constructor(options: SessionOptions);
+    /**
+     * Load the package and bring the session to its first renderable state.
+     *
+     * For a game with a `setup` slot that is the configuration step,
+     * with no context built yet; for every other game it is tick 0 (§8.3).
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Submit a state-changing command. Queued, in order, one at a time. */
+    submit(command: MutationCommand): Promise<MutationResult>;
+    /**
+     * Queue `work` as one operation: every logic call it makes reads the same
+     * `meta.now`, taken as it starts rather than as it was submitted (§10.2).
+     */
+    private enqueue;
+    /**
+     * Move a fake clock forward by `byMs`, one due instant at a time.
+     *
+     * The clock runs everything due in one call, but an automatic tick is
+     * submitted rather than run, and the next one is scheduled only once it
+     * settles. Advancing straight to the target would run the first tick and
+     * then find nothing else due, so three minutes on a one-minute timer would
+     * tick once. Stepping to each due instant and settling there ticks three
+     * times, which is what three minutes means.
+     */
+    private advanceClock;
+    /**
+     * Submit a command the runtime issues on its own behalf, which is dropped
+     * rather than queued when anything is in flight (§11.1).
+     */
+    submitIfIdle(command: MutationCommand): Promise<MutationResult | null>;
+    /**
+     * Resolves once everything queued has run, including a tick an automatic
+     * timer submitted. For a caller that must observe a timer's effects.
+     */
+    settled(): Promise<void>;
+    /** Answer a read. Never queued (§9.7). */
+    query(command: QueryCommand): Promise<QueryResult>;
+    /** Convenience for a caller that does not care which kind it is holding. */
+    run(command: Command): Promise<MutationResult | QueryResult>;
+    /** The §20.1 projection: one shape, recomputed on demand. */
+    project(): StateProjection;
+    /**
+     * The stored session-override layer (§8.2), as distinct from the resolved
+     * configuration on the projection. Sparse: it holds what was overridden.
+     */
+    sessionOverrides(): ResolvedSettings;
+    /**
+     * The scenario editor's draft of a scenario, resolved (§6.5): what
+     * save-as-scenario captures from the editor. Null when no editor is open
+     * on it.
+     */
+    scenarioDraft(scenarioId: string | null): ResolvedSettings | null;
+    /** A draft has been saved as its scenario, which now holds its edits. */
+    scenarioDraftSaved(scenarioId: string | null): void;
+    /**
+     * Every open draft, resolved, for the projection; nothing while none is.
+     * A draft of a scenario since deleted on disk is left out rather than
+     * resolved against nothing.
+     */
+    private projectedDrafts;
+    /** Endpoint calls that changed something, oldest first (§6.12). */
+    endpointAuditLog(): readonly EndpointAuditEntry[];
+    /** Operator-facing failures since the session started, oldest first. */
+    diagnostics(): readonly string[];
+    /**
+     * Mark exactly these participants connected, and every other one not
+     * (§13.2).
+     *
+     * Presence is the host's to observe, not a command anybody sends: the host
+     * knows which surfaces are open, and a participant is connected while at
+     * least one surface bound to them is. Given the whole set rather than a
+     * change, so a re-initialisation that replaces every participant record
+     * is put right by the next call, with nothing to reconcile.
+     */
+    syncPresence(connected: ReadonlySet<string>): void;
+    /** Edits on disk this session has not applied, each list empty when none is. */
+    pendingChanges(): PendingChanges;
+    /** True while the session is in its setup state, still owed a Play (§8.3, §9.0). */
+    get inSetup(): boolean;
+    /** The resolved package, for a shell that has to serve what it declares. */
+    packageConfiguration(): ResolvedPackageManifest | null;
+    /** The scenario in force, for resolving `asset:` references (§6.7). */
+    activeScenario(): SDKScenario | null;
+    /**
+     * Re-read the package's scenarios, after one has been written to disk.
+     *
+     * An author-time affordance (§6.7.1): saving a scenario changes the package,
+     * and the picker should show it without a restart.
+     */
+    reloadScenarios(): Promise<void>;
+    /**
+     * Pick up edited logic from its next run. Queued, so a tick in flight
+     * finishes on the code it started with. Nothing already played is re-run.
+     */
+    reloadLogic(): Promise<void>;
+    /**
+     * Re-resolve configuration from edited bundle files and the manifest.
+     *
+     * What a running session can adopt, it adopts, keeping play where it is. An
+     * edit that applies only at initialisation (a setting, a manifest field
+     * read at session creation, a capability removed or moved to another
+     * scope) re-initialises the session while nothing has been played, or
+     * always under {@link SessionOptions.reinitOnChange}. Otherwise the session
+     * keeps running on what it started with and records the edit as pending,
+     * which refuses what would advance play until somebody re-initialises
+     * (#640). A bundle that does not load or validate is reported, and the
+     * last good configuration stays in force.
+     */
+    reloadBundles(): Promise<ReloadOutcome>;
+    /**
+     * Whether anything has been played: a tick committed and not since
+     * rewound. A session at its configuration step has played nothing.
+     */
+    private hasPlayed;
+    /**
+     * Start the session over from the package as it is on disk, keeping the
+     * team count, the scenario and the locale, and returning play to tick 0.
+     * A session at its configuration step stays at it when the game still has
+     * one (§8.3).
+     */
+    private applyPendingChanges;
+    /** The facilitator guide this package declares, or null (§6.9). */
+    guide(): SDKFacilitatorGuide | null;
+    subscribe(listener: (event: Event) => void): () => void;
+    private apply;
+    /** Returns the tick a write committed into, where that is meaningful. */
+    private dispatch;
+    private play;
+    /**
+     * Return to the configuration step (§8.3).
+     *
+     * Refused for a game with no `setup` slot: there would be nothing to show
+     * and no way back, which is a session you have to restart the process to
+     * recover.
+     *
+     * The session resets with it, because a configuration change reaches logic
+     * through `Init`. Leaving the teams where they were would show a
+     * configuration screen over a game already in progress, and then quietly
+     * discard the round they were in when somebody pressed Play.
+     */
+    private reconfigure;
+    /**
+     * Start the session over from the package (§8.3).
+     *
+     * `reset` returns the session to its own tick 0; this rebuilds it. The
+     * scenario is resolved afresh, so omitting one goes back to the package's
+     * default rather than keeping whatever is active, and the team count and
+     * locale are resolved again too. What it does not do is restart the
+     * process: a browser attached to this session stays attached.
+     */
+    private reinitialise;
+    private setWaitingRoom;
+    /**
+     * Activate a scenario, from the start (§6.7).
+     *
+     * A scenario is a different set of starting conditions, so switching one is
+     * a new session rather than an adjustment to the one in progress: its
+     * overrides reach the game through `Init`, and a session already several
+     * ticks in has passed the only moment they mean anything. Every team
+     * returns to tick 0, and a game with a configuration step returns to it.
+     *
+     * This is why a client should confirm before sending it. The runtime does
+     * not ask — a runtime that second-guessed a command it was given would be
+     * unusable from a script — but it does say plainly what it did.
+     */
+    /** Open the scenario editor's draft of a scenario the package declares (§6.5). */
+    private editScenario;
+    private declaredScenarioIds;
+    private selectScenario;
+    /**
+     * Delete this run's blobs of the given retentions (§16.2).
+     *
+     * A walkthrough keeps its blobs in the package's store with the session's,
+     * and nothing records which run made one, so it deletes none: clearing on
+     * its behalf would clear the session's uploads too.
+     */
+    private clearBlobs;
+    private setLocale;
+    /**
+     * Build tick-0 state for every team, and seed the histories.
+     *
+     * @param preserveShared Store captured before a re-initialisation, to put
+     * back afterwards (§7.5 rule 4). Omitted where re-seeding the store from
+     * capability defaults is the point, as it is for a reset.
+     */
+    private buildInitialState;
+    private resolveMode;
+    /**
+     * The mode the game declared (§5.2).
+     *
+     * The team count is not consulted. Reporting a one-team session as a third
+     * `single` mode read as harmless, because with one team the two modes reach
+     * the same state, but it decided this session's ticks, undo and history
+     * from a quantity that was free to change, and it governed the `addTeam`
+     * guard from the very number that guard exists to hold still (#533).
+     */
+    private mode;
+    /** What a surface reads of another team, which only shared state allows (§6.1). */
+    private crossTeamReadsOf;
+    /**
+     * The bounds as this host will actually enforce them (§5.4).
+     *
+     * A game declaring no maximum is capped at the number of teams it has,
+     * because an unbounded control on a local authoring host offers a facilitator
+     * a session it cannot usefully drive.
+     */
+    private effectiveTeamBounds;
+    private teamBounds;
+    private tickLimit;
+    /** A game holds a configuration step exactly when it fills the `setup` slot (§8.3). */
+    private hasSetup;
+    /** Whether any tick has been committed and not since rewound. */
+    private hasTicked;
+    /** The team at a position, as an endpoint is told it (§6.12). */
+    private teamAt;
+    /** A team's display name as it reads now, a rename included (§5.4). */
+    private teamNameAt;
+    private sharedEngineState;
+    private sharedStore;
+    /** The stable index behind a team id, or undefined when it names no team. */
+    private indexOfTeamId;
+    private positionOf;
+    /**
+     * The `game` settings through every layer (§6.10, §8.2). Every runtime read
+     * of the tick limit, the team bounds and names, and `openOnStart` goes
+     * through here, so a scenario or the session can vary them.
+     */
+    private settings;
+    private game;
+    private scenarioBeingEdited;
+    /**
+     * The game's name in the session locale, falling back through what the
+     * package declares (§18.2) rather than showing an identifier to a
+     * facilitator.
+     */
+    private gameName;
+    private report;
+    private emitState;
+    private emit;
+}

package/dist/core/settings-locks.d.ts

@@ -0,0 +1,22 @@
+import type { JSONSchema7 } from 'json-schema';
+/**
+ * Locked settings (SPECIFICATION.md §6.1a): a property its schema marks
+ * `readOnly: true` keeps the game's own value. The lock is enforced where a
+ * value is written, a scenario or the session layer, and never where layers
+ * resolve: an override naming a locked value is refused, so none ever reaches
+ * the resolver. A locked object locks everything under it.
+ */
+/** The paths a settings schema locks, each as its keys below the resource. */
+export declare function lockedPaths(schema: JSONSchema7 | undefined): string[][];
+/** The locked paths an override of one settings resource names. */
+export declare function lockedPathsNamed(override: unknown, schema: JSONSchema7 | undefined): string[][];
+/** A locked value as a facilitator or an author reads it: `engine.Rate`. */
+export declare function lockedSettingName(identifier: string, path: readonly string[]): string;
+export declare function lockedSettingMessage(identifier: string, path: readonly string[]): string;
+/**
+ * `settings` without the locked values that still hold the game's own, as a
+ * resolved snapshot always carries them. What a save-as-scenario writes, so
+ * the scenario never names a locked value; one that differs from the game's
+ * is left in place for validation to refuse.
+ */
+export declare function withoutLockedDefaults<T extends Record<string, unknown>>(settings: T, schemas: Record<string, JSONSchema7>): T;

package/dist/core/team-names.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Team name resolution.
+ *
+ * Author intent layers over the runtime default: the resolved `game`
+ * settings' `teams.defaultNames`, which a scenario or the session may set like
+ * any other setting, wins over the positional `Team N` fallback. Names are
+ * localised, so the active locale is tried first, then any locale the entry
+ * declares (an authored name in another language still beats `Team N`),
+ * before the fallback.
+ *
+ * Resolved names are advisory defaults: operators may rename teams at session
+ * setup.
+ */
+type LocalisedTeamName = Record<string, {
+    name: string;
+}>;
+/**
+ * Resolve the default name for a single team (zero-based index).
+ */
+export declare function resolveTeamName(index: number, defaultNames: readonly LocalisedTeamName[], locale: string): string;
+/**
+ * Longest team name the host will accept.
+ *
+ * A team name is rendered in the host's own chrome and on print sheets, neither
+ * of which the game controls, so the ceiling is the host's to set. Players can
+ * rename their own team (#494) and no game code sees the name on its way
+ * through, so this is the only thing standing between a text field and a
+ * session header.
+ */
+export declare const MAX_TEAM_NAME_LENGTH = 60;
+/**
+ * Per-session team name overrides, keyed by stable team index.
+ *
+ * A team's default name is resolved from the `game` settings, so
+ * a facilitator rename has nowhere to live in either. It is session state, not
+ * authored content: it lasts as long as the dev server process and is
+ * deliberately not written back to any `.sdk.json`.
+ */
+export declare const teamNameOverrides: Map<number, string>;
+/**
+ * Discard every rename, restoring the authored defaults.
+ *
+ * Intended for tests. The overrides are module state, so they outlive the
+ * `DevServer` that collected them: an in-process test that starts a second
+ * server sees the first one's renames, the way `clearOwnWriteHistory` exists
+ * for the same reason in `atomic-write.ts`. A real dev server hosts one session
+ * per process, so nothing in normal use needs this.
+ */
+export declare function clearTeamNameOverrides(): void;
+/** Resolve a team's display name, preferring a rename over the authored default. */
+export declare function resolveTeamDisplayName(index: number, defaultNames: readonly LocalisedTeamName[], locale: string): string;
+export {};