@seriousgaming/sdk-tools 1.0.0-alpha.1 → 1.0.0-alpha.2

package/README.md

@@ -16,6 +16,8 @@ The scaffolded package installs this package beside `@seriousgaming/sdk`, which
 
 ## Stability
 
+A version with a prerelease suffix, such as `1.0.0-alpha.1`, carries none of these guarantees: it can change in any way before the release it leads to. Until 1.0.0 ships, npm's `latest` tag points at a prerelease, so a bare install gets one.
+
 From 1.0.0, these follow semantic versioning. A breaking change waits for a major release:
 
 | Surface                         | What it holds                                                                                         |

package/dist/cli.js

@@ -254,6 +254,10 @@ var ERROR_CODES = {
     category: "package",
     description: "A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it."
   },
+  SCENARIO_EDITOR_UNREACHABLE: {
+    category: "package",
+    description: "A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it."
+  },
   EDITOR_ENDPOINT_STATEFUL: {
     category: "package",
     description: "The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have."
@@ -6811,6 +6815,20 @@ function validateGame(game, config) {
       hint: "Set `maxTicks` in seriousgaming.sdk.json, add a tick controller, or make sure Run returns complete: true."
     });
   }
+  if (config.scenario_editor && game.definition.customScenarios?.supported !== true) {
+    const editorId = config.scenario_editor.definition.identifier;
+    const message = `Game "${game.definition.identifier}" ships a scenario_editor but does not set customScenarios.supported, so no host will ever open the editor.`;
+    warnings.push(message);
+    findings.push({
+      severity: "warning",
+      code: "SCENARIO_EDITOR_UNREACHABLE",
+      message,
+      file: MANIFEST_FILE,
+      pointer: "",
+      resource: { type: "scenario_editor", identifier: editorId },
+      hint: 'Set `"customScenarios": { "supported": true }` in seriousgaming.sdk.json, or delete the scenario_editor if the game should not offer custom scenarios.'
+    });
+  }
   const settingsReferences = collectUnknownSettingsReferences(config);
   errors.push(...settingsReferences.errors);
   findings.push(...settingsReferences.findings);
@@ -13562,14 +13580,15 @@ var SessionEndpoints = class {
   session(roster2) {
     const { executor, state: state2, participants } = this.host;
     const ticks = state2.getTeamTicks();
-    const complete = state2.getTeamComplete();
+    const limit = this.host.tickLimit();
+    const complete = state2.teamsFinished(limit);
     const hasController = Boolean(executor.getConfig()?.tick_controller);
     return {
       mode: this.host.mode(),
       completedTicks: state2.getCurrentTick(),
       maxTicks: this.host.settings().maxTicks,
       waitingRoomOpen: this.host.waitingRoomOpen(),
-      complete: state2.isSessionComplete(),
+      complete: state2.isSessionFinished(limit),
       teams: state2.getTeamIndexes().map((_, position) => {
         const team = this.host.teamAt(position);
         return {
@@ -15038,6 +15057,23 @@ var TeamStateStore = class {
   isSessionComplete() {
     return this.teamComplete.length > 0 && this.teamComplete.every(Boolean);
   }
+  /**
+   * Whether each team can tick no more, which is what `complete` reports
+   * (§9.0, §20.1): it signalled completion (§11.1) or played the tick limit
+   * (§9.6). The stored flags stay the signal alone, because undo and past
+   * state read the signal, not the limit.
+   */
+  teamsFinished(limit) {
+    return Array.from(
+      { length: this.teamCount },
+      (_, position) => this.isTeamComplete(position) || limit !== null && (this.teamTicks[position] ?? this.currentTick) >= limit
+    );
+  }
+  /** Whether no team can tick again: every team is finished. */
+  isSessionFinished(limit) {
+    const finished = this.teamsFinished(limit);
+    return finished.length > 0 && finished.every(Boolean);
+  }
   // -- Stable index ↔ array position translation --------------------------
   getTeamIndexes() {
     return this.teamIndexes;
@@ -15540,7 +15576,7 @@ var Session = class {
     const indexes = this.state.getTeamIndexes();
     const contexts = this.state.getTeamContexts();
     const ticks = this.state.getTeamTicks();
-    const complete = this.state.getTeamComplete();
+    const complete = this.state.teamsFinished(this.tickLimit());
     const canUndo = this.state.teamCanUndo();
     const game = this.game();
     const { defaultNames } = this.settings().teams;
@@ -15576,7 +15612,7 @@ var Session = class {
         completedTicks: this.state.getCurrentTick(),
         mode: this.mode(),
         waitingRoomOpen: this.waitingRoomOpen,
-        complete: this.state.isSessionComplete(),
+        complete: this.state.isSessionFinished(this.tickLimit()),
         seed: this.seed,
         sessionKey: this.sessionKey,
         locale: this.locale,

package/dist/client.js

@@ -473,6 +473,10 @@ var ERROR_CODES = {
     category: "package",
     description: "A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it."
   },
+  SCENARIO_EDITOR_UNREACHABLE: {
+    category: "package",
+    description: "A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it."
+  },
   EDITOR_ENDPOINT_STATEFUL: {
     category: "package",
     description: "The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have."
@@ -9655,14 +9659,15 @@ var SessionEndpoints = class {
   session(roster) {
     const { executor, state: state2, participants } = this.host;
     const ticks = state2.getTeamTicks();
-    const complete = state2.getTeamComplete();
+    const limit = this.host.tickLimit();
+    const complete = state2.teamsFinished(limit);
     const hasController = Boolean(executor.getConfig()?.tick_controller);
     return {
       mode: this.host.mode(),
       completedTicks: state2.getCurrentTick(),
       maxTicks: this.host.settings().maxTicks,
       waitingRoomOpen: this.host.waitingRoomOpen(),
-      complete: state2.isSessionComplete(),
+      complete: state2.isSessionFinished(limit),
       teams: state2.getTeamIndexes().map((_, position) => {
         const team = this.host.teamAt(position);
         return {
@@ -11174,6 +11179,23 @@ var TeamStateStore = class {
   isSessionComplete() {
     return this.teamComplete.length > 0 && this.teamComplete.every(Boolean);
   }
+  /**
+   * Whether each team can tick no more, which is what `complete` reports
+   * (§9.0, §20.1): it signalled completion (§11.1) or played the tick limit
+   * (§9.6). The stored flags stay the signal alone, because undo and past
+   * state read the signal, not the limit.
+   */
+  teamsFinished(limit) {
+    return Array.from(
+      { length: this.teamCount },
+      (_, position) => this.isTeamComplete(position) || limit !== null && (this.teamTicks[position] ?? this.currentTick) >= limit
+    );
+  }
+  /** Whether no team can tick again: every team is finished. */
+  isSessionFinished(limit) {
+    const finished = this.teamsFinished(limit);
+    return finished.length > 0 && finished.every(Boolean);
+  }
   // -- Stable index ↔ array position translation --------------------------
   getTeamIndexes() {
     return this.teamIndexes;
@@ -11676,7 +11698,7 @@ var Session = class {
     const indexes = this.state.getTeamIndexes();
     const contexts = this.state.getTeamContexts();
     const ticks = this.state.getTeamTicks();
-    const complete = this.state.getTeamComplete();
+    const complete = this.state.teamsFinished(this.tickLimit());
     const canUndo = this.state.teamCanUndo();
     const game = this.game();
     const { defaultNames } = this.settings().teams;
@@ -11712,7 +11734,7 @@ var Session = class {
         completedTicks: this.state.getCurrentTick(),
         mode: this.mode(),
         waitingRoomOpen: this.waitingRoomOpen,
-        complete: this.state.isSessionComplete(),
+        complete: this.state.isSessionFinished(this.tickLimit()),
         seed: this.seed,
         sessionKey: this.sessionKey,
         locale: this.locale,
@@ -13410,6 +13432,20 @@ function validateGame(game, config) {
       hint: "Set `maxTicks` in seriousgaming.sdk.json, add a tick controller, or make sure Run returns complete: true."
     });
   }
+  if (config.scenario_editor && game.definition.customScenarios?.supported !== true) {
+    const editorId = config.scenario_editor.definition.identifier;
+    const message = `Game "${game.definition.identifier}" ships a scenario_editor but does not set customScenarios.supported, so no host will ever open the editor.`;
+    warnings.push(message);
+    findings.push({
+      severity: "warning",
+      code: "SCENARIO_EDITOR_UNREACHABLE",
+      message,
+      file: MANIFEST_FILE,
+      pointer: "",
+      resource: { type: "scenario_editor", identifier: editorId },
+      hint: 'Set `"customScenarios": { "supported": true }` in seriousgaming.sdk.json, or delete the scenario_editor if the game should not offer custom scenarios.'
+    });
+  }
   const settingsReferences = collectUnknownSettingsReferences(config);
   errors.push(...settingsReferences.errors);
   findings.push(...settingsReferences.findings);

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

@@ -17,7 +17,7 @@ import type { SessionHost } from './session-host';
 type CallEndpoint = Extract<QueryCommand, {
     type: 'callEndpoint';
 }>;
-type EndpointHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'clock' | 'timers' | 'pendingChanges' | 'mode' | 'settings' | 'scenarioBeingEdited' | 'waitingRoomOpen' | 'positionOf' | 'indexOfTeamId' | 'teamAt' | 'roster' | 'declaredSurface' | 'enqueue' | 'apply'>;
+type EndpointHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'clock' | 'timers' | 'pendingChanges' | 'mode' | 'settings' | 'tickLimit' | 'scenarioBeingEdited' | 'waitingRoomOpen' | 'positionOf' | 'indexOfTeamId' | 'teamAt' | 'roster' | 'declaredSurface' | 'enqueue' | 'apply'>;
 export declare class SessionEndpoints {
     private readonly host;
     private readonly audit;

package/dist/core/team-state-store.d.ts

@@ -118,6 +118,15 @@ export declare class TeamStateStore {
      * others still tick.
      */
     isSessionComplete(): boolean;
+    /**
+     * Whether each team can tick no more, which is what `complete` reports
+     * (§9.0, §20.1): it signalled completion (§11.1) or played the tick limit
+     * (§9.6). The stored flags stay the signal alone, because undo and past
+     * state read the signal, not the limit.
+     */
+    teamsFinished(limit: number | null): boolean[];
+    /** Whether no team can tick again: every team is finished. */
+    isSessionFinished(limit: number | null): boolean;
     getTeamIndexes(): number[];
     setTeamIndexes(indexes: number[]): void;
     /** Stable index for the team at array position `position`. */

package/dist/docs/changelog.md

@@ -141,6 +141,7 @@ are in the [0.x changelog](changelog-0.x.md).
 - **`SERIOUSGAMING_DEV_STATE_DIR`** keeps the dev server's lock file outside the package
 - **For runtimes: the manifest schema and the logic-result checks.** `@seriousgaming/sdk-tools/schema.json` is the JSON Schema of this release's manifest version, its `ResolvedPackageManifest` the built `seriousgaming.json`, and `@seriousgaming/sdk-tools/runtime` adds `assertJsonSerialisable`, `readEngineResult`, `readAggregateResult` and `readTickControllerResult`. A game needs none of them
 - **The SDK has a README** saying which subpaths carry semver guarantees (the root, `./ui` and `./ui/testing`)
+- **`SCENARIO_EDITOR_UNREACHABLE`, a build warning** for a game that ships a `scenario_editor` without `customScenarios.supported`, which no host ever opens. Set the flag, or delete the editor
 
 ### Changed
 
@@ -178,6 +179,10 @@ are in the [0.x changelog](changelog-0.x.md).
 - **The conformance suite reports more of a production host fairly.** Checks that call an endpoint from outside the game require the new `external-callers` driver capability and checks that hold a session at setup require `setup-state`, so a host without either reports them unsupported. REQ-014 and REQ-020 check the outcome rather than a message or the host page's own traffic, each built fixture variant has its own package identifier, a new check holds a participant's `getPastState` to its own surface's rights whatever surface it claims, and the moved-participant check waits for the remount instead of racing it
 - **Three doc pages have new names**: `guides/game-configuration.md` is [`guides/settings.md`](guides/settings.md), `guides/examples.md` is [`guides/patterns.md`](guides/patterns.md), and `recipes/share-logic-between-module-and-ui.md` is [`recipes/share-logic-between-engine-and-ui.md`](recipes/share-logic-between-engine-and-ui.md). The docs no longer point at example packages you cannot see, the publishing and LLM guides say an account needs access Business Simulations grants (as the 403 messages from `package publish` and `generateText` now do, and the scaffold's `workflow-publish-package.md`), and `llms.txt` and `llms-full.txt` on the docs site link by absolute URL
 
+- **`complete` counts the tick limit.** On an endpoint's `session`, its team statuses and the state projection `sdk view` prints, a team is `complete` once it can tick no more: its tick controller or engine ended it, or it has played `maxTicks`. The session is `complete` once every team is. A game that ends by its limit used to read `complete: false` after its last round. Undoing that round clears it again; a `getPastState` entry's `complete` still reports only a controller or engine ending the game
+- **The SDK's `react` and `react-dom` peers are optional.** Only `@seriousgaming/sdk/ui` needs them, so a project that imports the SDK without React, such as a runtime running the conformance suite, no longer gets peer warnings
+- **The conformance suite reaches every endpoint check through a surface.** Eight checks called with no surface, a caller only an authoring host offers; they now call from the participant or session UI, so a host with no outside route runs them. A runtime may treat a resource's `rootDirectory` as empty when the archive holds no directory there, which an asset-less scenario packed by npm or a zip tool does not
+
 ### Removed
 
 - **`sdk docs ask` and `sdk docs search`**, with the `@xenova/transformers` dependency behind them (about 230MB less to install) and `HF_HOME` and `HUGGINGFACE_HUB_CACHE`. Read the shipped docs with `sdk docs view <path>`, search `node_modules/@seriousgaming/sdk-tools/dist/docs`, or copy them out with `sdk docs export`. Both commands stay as hidden pointers that say so and fail with `USAGE_REMOVED_COMMAND` (exit 2), so agent guidance that still names them finds its way. Delete the `sharp` and `protobufjs` overrides from your `pnpm-workspace.yaml`

package/dist/docs/cli-error-codes.md

@@ -12,7 +12,7 @@ The codes are the contract: branch on the code, never on the message. A code is
 | --------- | ------------- | ------------------- | ----- |
 | 1         | `internal`    | Internal error      | 1     |
 | 2         | `usage`       | Usage error         | 15    |
-| 3         | `package`     | Invalid package     | 28    |
+| 3         | `package`     | Invalid package     | 29    |
 | 4         | `refused`     | Refused by the game | 11    |
 | 5         | `environment` | Environment         | 18    |
 
@@ -73,6 +73,7 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
 | `LOGIC_EXPORT_MISSING`        | A logic file is missing, or does not export the functions its resource needs.                                                                         | Yes               |
 | `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                           | Yes               |
 | `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                 | Yes               |
+| `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.                                   | Yes               |
 | `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                    | Yes               |
 | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes               |
 | `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                           | Yes               |
@@ -144,6 +145,7 @@ The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits
 | `LOGIC_BUNDLE_FAILED`         | A logic file does not bundle: a syntax error, or an import that does not resolve.                                                                                                                                                                  |
 | `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                                                                                                                        |
 | `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                                                                                                              |
+| `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.                                                                                                                                |
 | `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                                                                                                                 |
 | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments.                                                                                              |
 | `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                                                                                                                        |

package/dist/docs/cli-reference.md

@@ -232,6 +232,7 @@ Without `--json`, each diagnostic that names a file is printed under the error a
 | `LOGIC_BUNDLE_FAILED`         | A logic file does not bundle: a syntax error, or an import that does not resolve.                                                                                                                                                                  |
 | `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                                                                                                                        |
 | `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                                                                                                              |
+| `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.                                                                                                                                |
 | `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                                                                                                                 |
 | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments.                                                                                              |
 | `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                                                                                                                        |

package/dist/docs/guides/testing.md

@@ -440,6 +440,8 @@ pnpm run test -- --watch
 pnpm run test -- ui/src/App.test.tsx
 ```
 
+In a repository holding many games, running every package's tests back to back can load a laptop heavily. Vitest starts a worker per core by default; cap it with `--maxWorkers`, for example `pnpm run test -- --maxWorkers=1`, when you sweep the whole repository.
+
 ## The runtime your tests do not reproduce
 
 An engine test imports `logic.ts` straight into Vitest, which runs under **Node**, with Node's full set of globals. Your game's production runtime is a **bare V8 isolate** with only the ECMAScript intrinsics (see [the language environment your logic runs in](./engine.md#the-language-environment-your-logic-runs-in)).

package/dist/utils/error-codes.d.ts

@@ -185,6 +185,10 @@ export declare const ERROR_CODES: {
         readonly category: "package";
         readonly description: "A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.";
     };
+    readonly SCENARIO_EDITOR_UNREACHABLE: {
+        readonly category: "package";
+        readonly description: "A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.";
+    };
     readonly EDITOR_ENDPOINT_STATEFUL: {
         readonly category: "package";
         readonly description: "The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.";
@@ -328,7 +332,7 @@ export type ErrorCode = keyof typeof ERROR_CODES;
  * failure's `error.code` says what kind of failure it was; its diagnostics say
  * what was found and where. LOGIC_ERROR is only ever a diagnostic.
  */
-export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "EDITOR_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
+export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "SCENARIO_EDITOR_UNREACHABLE", "EDITOR_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
 export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 export declare function categoryOf(code: ErrorCode): ErrorCategory;
 export declare function exitCodeOf(code: ErrorCode): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousgaming/sdk-tools",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "SDK tooling for building Serious Gaming games",
   "homepage": "https://sdk.seriousgaming.com/",
   "license": "SEE LICENSE IN LICENSE",
@@ -68,7 +68,7 @@
     "@mui/icons-material": "^9.4.0",
     "@mui/material": "^9.4.0",
     "@playwright/test": "^1.64.0",
-    "@seriousgaming/sdk": "1.0.0-alpha.1",
+    "@seriousgaming/sdk": "1.0.0-alpha.2",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@types/adm-zip": "^0.5.8",
@@ -98,7 +98,7 @@
     "vitest": "^5.0.3"
   },
   "peerDependencies": {
-    "@seriousgaming/sdk": "^1.0.0-alpha.1"
+    "@seriousgaming/sdk": "^1.0.0-alpha.2"
   },
   "engines": {
     "node": ">=24"
@@ -115,6 +115,7 @@
     "test": "vitest",
     "test:run": "vitest run && vitest run --config cli/dev/console/vitest.config.ts",
     "test:coverage": "vitest run --coverage",
+    "test:run:coverage": "vitest run --coverage && vitest run --config cli/dev/console/vitest.config.ts",
     "test:e2e": "pnpm run test:e2e:cli && pnpm run test:integration && pnpm run test:e2e:ui",
     "test:e2e:cli": "vitest run --config e2e/vitest.e2e.config.ts",
     "test:integration": "vitest run --config integration/vitest.integration.config.ts",