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

package/dist/core/asset-reference-translator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Translator for blob references in a configuration tree.
+ *
+ * `blob:*` → `asset:*`: read runtime blob bytes and materialise them as a
+ * file under the package scenario assets directory. Used when saving a
+ * runtime configuration as a package scenario bundle (issue #101).
+ *
+ * The walker is shape-agnostic: it traverses any nested record / array
+ * structure and replaces string values that match a known reference prefix.
+ * Other primitives pass through unchanged.
+ */
+/**
+ * Translate a single reference string. Returns the new reference, or the
+ * original string when the reference does not apply.
+ */
+export type ReferenceTranslator = (reference: string) => Promise<string>;
+/**
+ * Build the blob-to-asset translator used by the author-time save flow. Reads
+ * each `blob:*` reference from the dev server's blob store, writes the bytes
+ * as a file under the target scenario's assets directory, and returns the
+ * resulting `asset:<relative-path>` reference.
+ *
+ * `asset:*` references are returned unchanged when
+ * `copyExistingAssets === false` (default). When true, the bytes are read
+ * from the source scenario root and re-materialised under the target assets
+ * directory — used for save-as-new flows that need a fully self-contained
+ * copy of a different scenario's assets.
+ *
+ * Materialised files are written under `<assetsSubdirectory>/` (default
+ * `shared`) inside the target assets directory, matching the layout that
+ * `createScenarioFiles` scaffolds for hand-authored scenarios.
+ */
+export declare function createBlobToAssetTranslator(opts: {
+    packagePath: string;
+    sourceScenarioRootDirectory: string | null;
+    targetAssetsDirectory: string;
+    assetsSubdirectory?: string;
+    copyExistingAssets?: boolean;
+}): ReferenceTranslator;
+/**
+ * Walk a configuration tree and translate every asset-reference string in
+ * place using the supplied translator. Returns a new value; the input is not
+ * mutated. Strings that are not asset references (per `isAssetReference`) are
+ * passed through unchanged.
+ */
+export declare function translateAssetReferences<T>(value: T, translate: ReferenceTranslator): Promise<T>;

package/dist/core/clock.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Time, as a port.
+ *
+ * Every timing decision the runtime makes reads the clock through this
+ * interface: the automatic tick schedule (§11.2), the 30-second floor and
+ * 7-day ceiling on the effective cadence (§11.8), the per-tick execution bound
+ * (§11.10), and pause and resume.
+ *
+ * The point is testability. A 7-day ceiling asserted against the real clock is
+ * either untestable or a test that lies by shortening the bound it claims to
+ * check; against {@link FakeClock} it is exact and takes microseconds. It is
+ * also the difference between a suite that is slow and flaky on a loaded
+ * machine and one that is neither, which is most of why the current
+ * `tick-timer.ts` needs 566 lines to express a small amount of behaviour.
+ */
+/** Cancels a scheduled callback. Idempotent. */
+export interface Cancellable {
+    cancel(): void;
+}
+export interface Clock {
+    /** Milliseconds since the epoch. */
+    now(): number;
+    /** Run `fn` after at least `ms`. */
+    schedule(fn: () => void, ms: number): Cancellable;
+}
+/** The real clock. The only implementation that reaches a host timer. */
+export declare const systemClock: Clock;
+/**
+ * A clock a test drives by hand.
+ *
+ * Time only moves when {@link advance} or {@link set} is called, so a test
+ * states the passage of time it means rather than waiting for it.
+ */
+export declare class FakeClock implements Clock {
+    private current;
+    private nextId;
+    private scheduled;
+    constructor(startAt?: number);
+    now(): number;
+    schedule(fn: () => void, ms: number): Cancellable;
+    /** How many callbacks are waiting. */
+    get pending(): number;
+    /** When the soonest waiting callback is due, or null when none is. */
+    get nextDueAt(): number | null;
+    /**
+     * Move time forward by `ms`, running everything that comes due.
+     *
+     * Callbacks run in due order, and time is set to each one's due instant
+     * before it runs, so a callback that reschedules measures from when it
+     * actually fired rather than from the end of the whole advance.
+     */
+    advance(ms: number): void;
+    /** Move time to `timestamp`, running everything that comes due. */
+    set(timestamp: number): void;
+    /** Drop every scheduled callback without running any. */
+    clear(): void;
+}

package/dist/core/faults.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deliberately reproducing the failures this runtime cannot otherwise produce.
+ *
+ * §9.7 names two conformant serialisation strategies. This runtime uses the
+ * first, full serialisation, and the platform uses the second, optimistic
+ * concurrency. Both are correct, and §12.5.1 spells out what follows: *'a
+ * runtime that fully serialises writes against ticks will never emit
+ * `conflict`'*.
+ *
+ * So an author's UI will never receive a `conflict` outcome in development and
+ * will in production. The retry path they were told to write is the one path
+ * development structurally cannot exercise, and the same is true of a hook chain
+ * throwing (§14.5), an LLM call failing (§17), and a write denied after a
+ * participant move (§13.2).
+ *
+ * Arming a fault is the design rule of the redesign applied to failures: every
+ * runtime state is reachable by an explicit control, and none only by
+ * re-enacting the circumstances that produce it. Faults are armed by name, fire
+ * once, and are reproducible, so an agent can verify a game's error handling
+ * without having to manufacture a race.
+ */
+import type { ArmedFault, FaultKind } from '@seriousgaming/sdk/projection';
+export type { ArmedFault, FaultKind };
+export declare const FAULT_KINDS: readonly FaultKind[];
+export declare function isFaultKind(value: unknown): value is FaultKind;
+/**
+ * The armed faults for one session.
+ *
+ * Deliberately not random. A fault fires a stated number of times and is then
+ * spent, so the same sequence of operations produces the same failures, which
+ * is what makes a failure reproducible enough to fix.
+ */
+export declare class FaultInjector {
+    private armed;
+    /**
+     * Arm a fault to fire the next `times` occasions it is consulted.
+     *
+     * Arming a kind that is already armed replaces it rather than adding to it:
+     * an operator who clicks twice means 'do it', not 'do it twice'.
+     */
+    arm(kind: FaultKind, options?: {
+        times?: number;
+        reason?: string;
+    }): ArmedFault;
+    /** Disarm one kind. Returns true when something was armed. */
+    disarm(kind: FaultKind): boolean;
+    /** Disarm everything. */
+    disarmAll(): void;
+    /** What is armed, for the state projection. */
+    list(): ArmedFault[];
+    /** Whether `kind` would fire, without consuming it. */
+    isArmed(kind: FaultKind): boolean;
+    /**
+     * Consume one occasion of `kind`, reporting whether it fires.
+     *
+     * Call this at the point the real failure would occur, so an armed fault
+     * exercises the same code path the genuine one would.
+     */
+    shouldFire(kind: FaultKind): boolean;
+    /**
+     * {@link shouldFire}, returning the fault that fired, so the failure it
+     * stands in for can carry the operator's `reason`.
+     */
+    fire(kind: FaultKind): ArmedFault | undefined;
+}

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

@@ -0,0 +1,65 @@
+import type { GameSettingConstraint, GameSettings, GameSettingsConstraints, PackageManifest, SDKSettings } from '@seriousgaming/sdk';
+/**
+ * The game-level settings: the built-in settings resource every game has.
+ *
+ * The number of rounds, the team bounds and names, and whether the waiting
+ * room opens with the session used to be a closed set of manifest fields a
+ * scenario could vary and a session could not. They are an ordinary settings
+ * resource now, under the reserved identifier `game`: the SDK owns its schema,
+ * the manifest's values are its defaults, and a scenario or a session
+ * overrides it by identifier, through the one resolver every setting goes
+ * through (SPECIFICATION.md §6.10, §8.2). A new game-level setting is a new
+ * property of that schema, and needs nothing else.
+ *
+ * `teams.mode` is deliberately not in it: §5.2 fixes the interaction mode at
+ * authoring time, because a game that needs both topologies ships as two.
+ */
+export declare const GAME_SETTINGS = "game";
+type DeepRequired<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+} : T;
+/** The `game` settings as they resolve: every property present. */
+export type ResolvedGameSettings = DeepRequired<GameSettings>;
+/** The manifest fields whose values are the `game` settings' defaults. */
+export type GameSettingsSource = Pick<PackageManifest, 'maxTicks' | 'teams' | 'waitingRoom' | 'gameSettingsConstraints'>;
+/** The game's own values for its `game` settings, from its manifest. */
+export declare function gameSettingsDefaults(manifest: GameSettingsSource): ResolvedGameSettings;
+/**
+ * The built-in `game` settings resource for a game: the SDK's schema with the
+ * game's values as its defaults, at every level, so a resolved value is
+ * complete however little of it an override names, and with the game's
+ * `gameSettingsConstraints` merged in, so a runtime sees one ordinary schema.
+ */
+export declare function gameSettingsResource(manifest: GameSettingsSource): SDKSettings;
+/** The constraint on each `game` setting a game narrows, by dotted path. */
+export declare function gameSettingConstraints(constraints: GameSettingsConstraints | undefined): Map<string, GameSettingConstraint>;
+/**
+ * Whether a game is single-team (§5.3): its `game` settings fix `teams.max`
+ * at 1, the default 1 and the value read-only. A maximum of 1 that a scenario
+ * or session could raise is no more single-team than an omitted one.
+ */
+export declare function teamsMaxOf(schema: unknown): {
+    max: number | null;
+    locked: boolean;
+};
+/**
+ * The `game` settings out of a resolution. A resolution always carries them,
+ * since every package has the resource; the neutral values stand in only for
+ * a configuration built by hand, as some tests build one.
+ */
+export declare function gameSettingsOf(resolved: Record<string, Record<string, unknown>>): ResolvedGameSettings;
+/**
+ * The game's own values for its `game` settings, as the package declares them:
+ * the defaults of its built-in resource. What a build checks scenarios
+ * against, having no session.
+ */
+export declare function declaredGameSettings(schema: unknown): ResolvedGameSettings;
+/**
+ * Why a session-layer override of the `game` settings is refused, or null
+ * when it is not. `waitingRoom.openOnStart` seeds the waiting-room flag as
+ * the session is created, before any setup step runs, so a session-layer
+ * value would be read by nothing; refusing it says so where an inert override
+ * would read as applied (§6.14.4, §8.2).
+ */
+export declare function gameOverrideRefusal(overrides: unknown): string | null;
+export {};

package/dist/core/history.d.ts

@@ -0,0 +1,89 @@
+/**
+ * HistoryManager - the closed rounds of one team, or of one session.
+ *
+ * A snapshot is the board as it stood **when a tick was submitted**, captured
+ * before that tick's engine run consumed it. Snapshot `k` is therefore the
+ * close of round `k + 1`: it carries tick `k`'s outcomes and everything the
+ * team then did with them. Written post-`Run`, it would carry the outcomes and
+ * none of the decisions, and any value the next tick cleared would never be
+ * observable in any snapshot at all.
+ *
+ * The head is never in here. A team at tick `N` has snapshots 0 to `N - 1` and
+ * holds round `N + 1`'s board in live state, which is where every surface reads
+ * it from. So history holds exactly the reviewable rounds, and the tick a
+ * snapshot is labelled with is its position in the array.
+ */
+export interface ContextSnapshot {
+    tick: number;
+    context: Record<string, unknown>;
+    /** All team contexts when running in multi-team mode */
+    teamContexts?: Record<string, unknown>[];
+    /**
+     * Stable team index for each entry of `teamContexts`. Indexes survive
+     * removals (positions shift, indexes do not), so snapshots written after
+     * a removal can have gaps. Absent in snapshots from older SDK versions,
+     * where the index is the array position.
+     */
+    teamIndexes?: number[];
+    recordedAt: number;
+}
+export declare class HistoryManager {
+    private snapshots;
+    /**
+     * Position of the newest snapshot, or -1 when there is none. Equal to the
+     * owner's tick minus one, because a tick writes the round it closed.
+     *
+     * Undo walks it down without truncating, so the entries above it are ticks
+     * that have been rewound: still present, so a later push can reuse the
+     * array, and reviewable by nobody.
+     */
+    private currentIndex;
+    /**
+     * Where this team started, before any round. Not a snapshot: the post-`Init`
+     * board closed no round, and putting it in the array would give tick 0 two
+     * meanings. A per-team reset is the only reader.
+     */
+    private initial;
+    /**
+     * Record the round a tick closed. `tick` is the tick being left behind
+     * (`next - 1`), so the entry lands at its own position in the array.
+     */
+    push(context: Record<string, unknown>, tick: number, teamContexts?: Record<string, unknown>[], teamIndexes?: number[]): void;
+    /**
+     * Step back one tick, returning the board to restore.
+     *
+     * The newest snapshot is the one to go back to, not the one before it: it
+     * holds the round that the tick being undone consumed, so restoring it
+     * leaves the team where it was the moment somebody pressed tick, decisions
+     * and all. Undo is for a tick triggered by accident, and a team that has to
+     * re-enter a round it already entered has not had anything undone.
+     */
+    undo(): ContextSnapshot | null;
+    /** Drop every snapshot. The initial board is not one, and survives. */
+    clear(): void;
+    /** Remember where this team started, for a per-team reset to return to. */
+    setInitial(context: Record<string, unknown>): void;
+    /** Where this team started, or null before it has been initialised. */
+    getInitial(): Record<string, unknown> | null;
+    /**
+     * Position of the newest snapshot, which is also its tick. -1 when empty.
+     */
+    getCursor(): number;
+    /**
+     * The snapshot for `tick` if that tick is reviewable, else null.
+     *
+     * Reviewable means recorded and not since rewound, which the cursor answers
+     * on its own: everything at or below it is a closed round, everything above
+     * it is a tick an undo took back. The head needs no special case, because a
+     * team at tick `N` has no snapshot `N` to exclude.
+     */
+    reviewable(tick: number): ContextSnapshot | null;
+    /**
+     * Every snapshot, in record order. Returns a fresh array so callers cannot
+     * push into or splice the manager's internal history; the snapshot objects
+     * themselves are shared and must be treated as read-only.
+     */
+    getAllSnapshots(): ContextSnapshot[];
+    /** Whether there is a round to step back into. */
+    canUndo(): boolean;
+}

package/dist/core/listen-with-fallback.d.ts

@@ -0,0 +1,30 @@
+import type { Server } from 'http';
+export interface ListenWithPortFallbackOptions {
+    /** The address to bind. Every interface when absent. */
+    host?: string;
+    maxAttempts?: number;
+    onPortInUse?: (port: number) => void;
+}
+/**
+ * Bind `server` to the first free port at or above `startPort`, stepping up one
+ * port at a time when a port is already in use. Resolves with the port actually
+ * bound.
+ *
+ * Each attempt settles fully before the next begins and its `error`/`listening`
+ * listeners are detached the moment it settles. This keeps the search linear and
+ * leaves no residual `error` listener on the server: attaching a persistent
+ * `.on('error')` per attempt (as an earlier version did) meant every `EADDRINUSE`
+ * re-fired every accumulated handler, fanning retries out exponentially and
+ * pegging a CPU under port contention.
+ */
+export declare function listenWithPortFallback(server: Server, startPort: number, options?: ListenWithPortFallbackOptions): Promise<number>;
+/**
+ * The first free port at or above `startPort`, found by binding and letting go.
+ *
+ * For a port something else will bind — Vite's hot-reload socket, which opens
+ * its own listener rather than sharing the HTTP server's. There is a race
+ * between letting go and the real listener binding, and it is the right trade:
+ * the alternative is handing Vite a port that is already taken, which is not a
+ * race but a certainty whenever a second dev server is running.
+ */
+export declare function findFreePort(startPort: number, maxAttempts?: number): Promise<number>;

package/dist/core/mutation-queue.d.ts

@@ -0,0 +1,61 @@
+/**
+ * §9.7 strategy 1, in one place.
+ *
+ * The specification names two conformant ways to keep a session's committed
+ * state equivalent to a single total order of its mutating operations, and
+ * assigns the first to this runtime by name: *'Run mutating operations one at a
+ * time through a single queue … This is the model the SDK dev server
+ * implements.'*
+ *
+ * Holding that as one object, rather than as a lock here and a debounce there,
+ * is what makes the guarantee checkable. Three rules, and nothing else:
+ *
+ * 1. **Mutations run one at a time, in submission order.** A tick is therefore
+ *    atomic for free: nothing else runs while it does.
+ * 2. **Reads never enter the queue.** §9.7 makes that a MUST, so this object
+ *    has no read path at all — a caller that wants current state reads it.
+ * 3. **An automatic tick that fires while anything is in flight is dropped,
+ *    not queued** (§11.1). Queueing it would let a slow tick accumulate a
+ *    backlog of ticks nobody asked for.
+ */
+/** What {@link MutationQueue.submitIfIdle} returns when it declines to run. */
+export declare const DROPPED: unique symbol;
+export type Dropped = typeof DROPPED;
+export declare class MutationQueue {
+    /**
+     * The tail of the chain. Every submission appends to it, which is what
+     * imposes the total order.
+     */
+    private tail;
+    /** Submitted but not yet settled, the running one included. */
+    private inFlight;
+    /** True while any mutation is queued or running. */
+    get busy(): boolean;
+    /** How many mutations are queued or running. */
+    get depth(): number;
+    /**
+     * Run `work` after everything already submitted, and report its result.
+     *
+     * A rejection settles the caller's promise and nothing else: the chain
+     * continues, because one failed operation must not wedge the session for
+     * every operation after it.
+     */
+    submit<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Run `work` only if nothing is in flight; otherwise decline (§11.1).
+     *
+     * For timer-driven ticks, which are the one mutation the runtime issues on
+     * its own behalf. A participant's write is queued because they asked for it
+     * and are waiting; a tick the clock fired while the previous one is still
+     * running is simply late, and running it afterwards would advance the game
+     * twice for one interval.
+     */
+    submitIfIdle<T>(work: () => Promise<T>): Promise<T | Dropped>;
+    /**
+     * Resolve once everything currently queued has settled.
+     *
+     * For shutdown and for tests. Not a lock: work submitted after this is
+     * called is not waited for.
+     */
+    drain(): Promise<void>;
+}

package/dist/core/package-scenario.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Author-time scenario persistence for the dev server (issue #101).
+ *
+ * Takes a snapshot of the resolved settings in force, translates any
+ * `blob:*` references into materialised files under the target scenario's
+ * `assets/` directory, and writes the resulting scenario bundle to disk.
+ *
+ * One function, two flows:
+ *   - an overwrite re-saves a scenario in place, replacing its settings (and
+ *     its name, when one is given) and keeping every other field on disk
+ *   - a new scenario writes a fresh `scenarios/<id>/` bundle, a copy of its
+ *     source's definition when it has one. Nothing registers it: the
+ *     directory is the declaration (#431)
+ *
+ * Reference translation is delegated to `asset-reference-translator.ts` so
+ * the inverse direction (asset→blob) used by `selectScenario` and the
+ * runtime `customScenarios` fork operation stays a sibling, not a copy.
+ */
+import type { SessionSettingsOverrides } from '../execution/configuration-builder';
+export interface SavePackageScenarioBaseOptions {
+    packagePath: string;
+    settings: SessionSettingsOverrides;
+    activeScenarioRootDirectory: string | null;
+}
+export interface CreatePackageScenarioOptions extends SavePackageScenarioBaseOptions {
+    identifier: string;
+    /**
+     * The scenario's name. A new scenario carries it in every locale it has;
+     * an overwrite replaces it in `nameLocale` alone, and keeps the name on
+     * disk when none is given. A new scenario with no name is named by its
+     * identifier.
+     */
+    name?: string;
+    /** The locale an overwrite's `name` replaces. Defaults to `en`. */
+    nameLocale?: string;
+    /**
+     * The scenario a new one is a copy of, by identifier. The copy carries
+     * everything the source declares on disk apart from its settings, which
+     * are the save's, and `default`, which a copy is given only when asked.
+     */
+    source?: string;
+    default?: boolean;
+    /**
+     * Carried from the scenario the save started out from (§6.7). A copy that
+     * loses the flag is a scenario built for one audience that ships to every
+     * one of them in the next release, and nothing downstream can tell that it
+     * ever was restricted. Clearing it is an edit the author makes on purpose.
+     */
+    restricted?: boolean;
+    /**
+     * If true and the scenario already exists on disk, overwrite the bundle
+     * (preserving the existing `rootDirectory`) instead of throwing
+     * `identifier-exists`. Used by the modal flow when the author has
+     * explicitly confirmed they want to replace the existing bundle.
+     */
+    overwrite?: boolean;
+}
+export interface PackageScenarioResult {
+    identifier: string;
+    /** Path to the scenario bundle file, absolute. */
+    scenarioFilePath: string;
+}
+/**
+ * Reasons for a save attempt to be rejected without writing anything.
+ */
+export type PackageScenarioErrorCode = 'invalid-identifier' | 'identifier-exists' | 'scenario-not-found' | 'game-not-found' | 'package-manifest-missing' | 'no-game-loaded';
+export declare class PackageScenarioError extends Error {
+    readonly code: PackageScenarioErrorCode;
+    constructor(code: PackageScenarioErrorCode, message: string);
+}
+/**
+ * Persist the live settings into a brand-new package scenario. Writes
+ * the bundle file, materialises any `blob:*` references as assets under
+ * `scenarios/<id>/assets/shared/`, and patches the game and package
+ * manifests so the new scenario is picked up on the next dev-server
+ * reload.
+ */
+export declare function createPackageScenario(opts: CreatePackageScenarioOptions): Promise<PackageScenarioResult>;
+/**
+ * Remove a scenario from the package on disk.
+ *
+ * Author-time, like saving one: it deletes a directory in the author's own
+ * source tree. A production runtime removes a facilitator's scenario from its
+ * own store and never touches a package.
+ */
+export declare function deletePackageScenario(packagePath: string, identifier: string): Promise<void>;
+/** Every scenario bundle on disk, in directory-name order. */
+/** The scenarios a package holds on disk, by identifier. */
+export declare function packageScenarioIdentifiers(packagePath: string): string[];

package/dist/core/participant-registry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * ParticipantRegistry — who is on which team.
+ *
+ * Scoped per team: each team has its own counter and its own set of
+ * participants. A participant is identified by a stable id assigned at
+ * creation (`team.counter + 1`), which never changes for the life of the
+ * session. Identity is addressed explicitly in the URL — `/team/2/player/1` is
+ * the first participant of the second team — so there is no per-browser
+ * cookie and nothing to resolve server-side.
+ *
+ * The registry tracks connection state but deliberately does not auto-evict
+ * disconnected participants — facilitators often want to see 'who was here'
+ * during a session. Use `clearOffline(teamId)` to remove disconnected entries.
+ *
+ * Nothing here is persisted. The session is the process (design decision 3),
+ * so a restarted server is a new session with a new roster.
+ *
+ * Events:
+ *   - `change`: emitted with the affected `teamId` after every mutation
+ *     (including connect/disconnect), so subscribers (e.g. WebSocket handlers)
+ *     can broadcast updated lists.
+ *   - `rosterChange`: emitted with the affected `teamId` after a *structural*
+ *     mutation (create / rename / remove) — not on connect/disconnect.
+ *   - `participantJoin`: emitted with the newly created `ParticipantRecord`
+ *     when a participant is created. Drives the `participantJoin` hook signal
+ *     (§14).
+ */
+import { EventEmitter } from 'events';
+export interface ParticipantRecord {
+    id: string;
+    teamId: string;
+    index: number;
+    name: string;
+    connected: boolean;
+}
+export declare class ParticipantRegistry extends EventEmitter {
+    private teams;
+    /**
+     * Session-wide participant id counter. Ids are unique across the whole
+     * session rather than within a team, so a participant keeps its id across a
+     * move and the host can resolve which team holds an id.
+     */
+    private idCounter;
+    private getTeam;
+    /**
+     * Create a new participant on a team. When `name` is omitted, an
+     * auto-name (`Participant N`) is chosen, bumping N to avoid colliding with
+     * an existing (possibly renamed) participant. New participants start
+     * disconnected; call `markConnected` once a live channel is established.
+     */
+    create(teamId: string, name?: string): ParticipantRecord;
+    private autoName;
+    /**
+     * Rename a participant. A blank name is ignored (the previous name stands).
+     * Returns the updated record, or `undefined` if the participant is unknown.
+     */
+    rename(teamId: string, id: string, name: string): ParticipantRecord | undefined;
+    /**
+     * Reassign a participant to another team.
+     *
+     * The record keeps its `id` but takes a fresh index within the destination,
+     * because index is join order *within a team* and the destination has its
+     * own sequence. Returns the moved record, or `undefined` when the
+     * participant is unknown or already on the destination team.
+     *
+     * Emits no participant signal of its own: a move is not a join, and the
+     * caller drives the two-phase `participantMove` hook dispatch because only
+     * it can persist the departure context before the arrival runs.
+     */
+    move(fromTeamId: string, id: string, toTeamId: string): ParticipantRecord | undefined;
+    /**
+     * Remove a participant. Returns true if one was removed. Does not re-seed a
+     * default — the caller decides whether an emptied team needs one, so it can
+     * also drive the resulting hook dispatch and persistence.
+     */
+    remove(teamId: string, id: string): boolean;
+    /** Look up a participant by id. Never creates one; returns undefined on a miss. */
+    getById(teamId: string, id: string): ParticipantRecord | undefined;
+    /**
+     * The team's default participant — the lowest-index record — or undefined
+     * when the team has no participants. Drives the bare `/play/:n` route.
+     */
+    getDefault(teamId: string): ParticipantRecord | undefined;
+    /**
+     * Return the team's default participant, creating a seed participant first
+     * if the team is empty so a team is never at zero. Used at session start,
+     * when a team is added, and to resolve the bare `/play/:n` route.
+     */
+    ensureDefault(teamId: string): ParticipantRecord;
+    markConnected(teamId: string, id: string): void;
+    markDisconnected(teamId: string, id: string): void;
+    list(teamId: string): ParticipantRecord[];
+    /**
+     * Drop a team's participants entirely. Used when a team is removed at
+     * runtime; the remaining teams keep their ids, so no re-keying happens.
+     */
+    removeTeam(teamId: string): void;
+    /**
+     * Drop every team and participant — a full clean slate. Used by the
+     * dev server's 'reload everything' action; teams re-seed their default on
+     * the next play.
+     */
+    clear(): void;
+    /**
+     * Remove all disconnected participants from a team. The counter is not
+     * reset, so future participants still get fresh indices.
+     */
+    clearOffline(teamId: string): void;
+}

package/dist/core/pending-changes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Edits on disk a running session has not applied, said the same way wherever
+ * they are said: the console's banner, the dev server's log, and the CLI.
+ */
+import type { PendingChanges } from '@seriousgaming/sdk/projection';
+export type { PendingChanges };
+export declare const NO_PENDING_CHANGES: PendingChanges;
+export declare function hasPendingChanges(pending: PendingChanges | undefined): boolean;
+/** The banner's headline: settings first, since they are the common case. */
+export declare function pendingHeadline(pending: PendingChanges): string;
+/** What is waiting, as one sentence naming each part. */
+export declare function describePendingChanges(pending: PendingChanges): string;
+/** Where to go from here. */
+export declare const PENDING_CHANGES_HINT: string;