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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +5 -5
  2. package/dist/cli.js +30 -12
  3. package/dist/client/index.d.ts +2 -2
  4. package/dist/client/test-session.d.ts +12 -15
  5. package/dist/client.js +20 -11
  6. package/dist/docs/api/index.md +1 -1
  7. package/dist/docs/api/sdk-tools-client.md +40 -32
  8. package/dist/docs/api/sdk-ui-testing.md +4 -4
  9. package/dist/docs/api/sdk-ui.md +80 -20
  10. package/dist/docs/api/sdk.md +37 -21
  11. package/dist/docs/changelog.md +117 -71
  12. package/dist/docs/cli-and-dev-server.md +16 -15
  13. package/dist/docs/cli-reference.md +10 -0
  14. package/dist/docs/concepts/index.md +1 -1
  15. package/dist/docs/concepts/terminology.md +6 -6
  16. package/dist/docs/getting-started.md +4 -2
  17. package/dist/docs/guides/engine-testing.md +1 -1
  18. package/dist/docs/guides/engine.md +13 -0
  19. package/dist/docs/guides/file-handling.md +4 -4
  20. package/dist/docs/guides/internationalization.md +15 -1
  21. package/dist/docs/guides/llm-integration.md +2 -0
  22. package/dist/docs/guides/patterns.md +33 -5
  23. package/dist/docs/guides/presentation.md +9 -9
  24. package/dist/docs/guides/session.md +22 -19
  25. package/dist/docs/guides/testing.md +3 -3
  26. package/dist/docs/guides/tick-controller.md +5 -3
  27. package/dist/docs/guides/ui.md +5 -1
  28. package/dist/docs/guides/upgrading.md +21 -6
  29. package/dist/docs/recipes/create-endpoint.md +1 -1
  30. package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
  31. package/dist/docs/recipes/use-request-tick.md +1 -1
  32. package/dist/docs/troubleshooting.md +6 -4
  33. package/dist/schema.json +6 -6
  34. package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
  35. package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
  36. package/dist/templates/engine/logic.test.ts.liquid +22 -34
  37. package/dist/templates/hook/logic.test.ts.liquid +28 -32
  38. package/dist/templates/package/CLAUDE.md.template +1 -1
  39. package/dist/templates/package/README.md.liquid +3 -3
  40. package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
  41. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
  42. package/dist/templates/package/vitest.config.ts.liquid +18 -2
  43. package/dist/templates/presentation/src/App.tsx.liquid +1 -1
  44. package/dist/templates/session/src/main.tsx.liquid +3 -3
  45. package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
  46. package/dist/templates/starter-game/engine/logic.test.ts +37 -47
  47. package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
  48. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
  49. package/dist/templates/starter-game/session/src/main.tsx +3 -3
  50. package/dist/templates/starter-game/ui/src/main.tsx +3 -3
  51. package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
  52. package/dist/templates/starter-game/vitest.config.ts +18 -2
  53. package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
  54. package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
  55. package/dist/templates/ui/src/App.tsx.liquid +22 -11
  56. package/dist/templates/ui/src/i18n.ts.liquid +3 -0
  57. package/dist/templates/ui/src/main.tsx.liquid +3 -3
  58. package/dist/templates/validator/logic.test.ts.liquid +21 -30
  59. package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
  60. package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
  61. package/package.json +3 -3
@@ -16,6 +16,9 @@ and the SDK adheres to [Semantic Versioning](https://semver.org/).
16
16
  Coming from 0.6, follow the [upgrading guide](guides/upgrading.md), which
17
17
  turns every breaking change below into an ordered step.
18
18
 
19
+ If you installed a 1.0.0 alpha, read the whole 1.0.0 section: its entries
20
+ describe the changes since 0.6.0, not since each alpha.
21
+
19
22
  Entries are grouped into: **Breaking Changes**, **Added**, **Changed**,
20
23
  **Deprecated**, **Removed**, **Fixed** and **Security**. Releases before 1.0
21
24
  are in the [0.x changelog](changelog-0.x.md).
@@ -28,7 +31,7 @@ are in the [0.x changelog](changelog-0.x.md).
28
31
 
29
32
  #### Packages
30
33
 
31
- - **The packages are renamed and move to the public npm registry.** `@businesssimulations/seriousgaming-sdk` is `@seriousgaming/sdk`, `@businesssimulations/seriousgaming-deck` is `@seriousgaming/deck`, and `@businesssimulations/seriousgaming-sdk-tools` is `@seriousgaming/sdk-tools`, each with the same subpaths. They install from npmjs.com with no token. The `seriousgaming-sdk` command keeps its name. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency at the same version. Scaffolded files carry the new names: `package.json.liquid`, `vite.config.ts.liquid`, `vitest.config.ts.liquid`, `oxlintrc.json.template`, `global-setup.ts.template`, `README.md.liquid`, `CLAUDE.md.template` and the `workflow-create-presentation.md`, `workflow-create-user-interface.md`, `workflow-test-engine-or-ui.md` and `workflow-update-sdk-version.md` rules. See [step 1 of the upgrading guide](guides/upgrading.md#step-1-rename-the-packages)
34
+ - **The packages are renamed and move to the public npm registry.** `@businesssimulations/seriousgaming-sdk` is `@seriousgaming/sdk`, `@businesssimulations/seriousgaming-deck` is `@seriousgaming/deck`, and `@businesssimulations/seriousgaming-sdk-tools` is `@seriousgaming/sdk-tools`, each with the same subpaths. They install from npmjs.com with no token. The `seriousgaming-sdk` command keeps its name. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency with a compatible `^` range. Scaffolded files carry the new names: `package.json.liquid`, `vite.config.ts.liquid`, `vitest.config.ts.liquid`, `oxlintrc.json.template`, `global-setup.ts.template`, `README.md.liquid`, `CLAUDE.md.template` and the `workflow-create-presentation.md`, `workflow-create-user-interface.md`, `workflow-test-engine-or-ui.md` and `workflow-update-sdk-version.md` rules. See [step 1 of the upgrading guide](guides/upgrading.md#step-1-rename-the-packages)
32
35
  - **Runtime plumbing leaves the SDK.** The host library moves from the SDK's `./host` to `@seriousgaming/sdk-tools/host`, with the host-side wire types `./ui` used to export, and the runtime helpers (`createGuardedCallbacks`, `deepMergeContext`, `projectContext`, `validateTickControllerResult`, `MANIFEST_VERSION` and others) move from the SDK root to `@seriousgaming/sdk-tools/runtime`. `isApiUseDeclared`, `isDeliverableToSurfaces`, `withheldCapabilityIds`, `resolveManifestVersion`, `removedSharedFlagError` and `tickControllerResultSchema` are removed, and `sdk-tools/client` no longer re-exports `ExecutionHistory`, `JsonPatchOperation`, `LLMGenerateOptions` or `GameContext`. No game needs them; a test harness that merged with `deepMergeContext` uses `mergingSetData` from `./ui/testing`. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
33
36
 
34
37
  #### Settings
@@ -36,8 +39,8 @@ are in the [0.x changelog](changelog-0.x.md).
36
39
  - **Settings resources replace `configurationSchema`.** A game's parameters live in `settings/<name>/settings.sdk.json`, holding `{ "definition": { "settingsSchema": {...} } }`, and a package may hold any number. Every property declares a default, and a top-level `required` is refused. The engine, UIs, the tick controller, hooks, validators and endpoints list the settings they read in `"settings": [...]` and receive exactly those, keyed by identifier, as `settings` (where logic received `config`, and `useUserInterfaceData()` and `useSessionUserInterfaceData()` returned `config`). Settings are fixed when play starts. The build refuses a `configurationSchema` on any bundle, an empty one included. Generated `types.ts` exports `Settings` and `defaults.ts` `defaultSettings`, in place of `Config` and `defaultConfig`, and `ModuleFunctionArgs` is `LogicFunctionArgs`. The `CLAUDE.md.template`, `DESIGN.md.liquid`, `workflow-create-engine.md`, `workflow-create-user-interface.md` and `workflow-test-engine-or-ui.md` guidance and every logic and UI scaffold are updated. See [step 2 of the upgrading guide](guides/upgrading.md#step-2-move-configuration-into-settings-resources)
37
40
  - **The game-level settings are the built-in `game` settings, and `ticks` is `maxTicks`.** Rename `ticks` in `seriousgaming.sdk.json` to `maxTicks`, and move a scenario's `ticks`, `teams` and `waitingRoom` into its `settings.game` (`ticks` again as `maxTicks`); the build refuses the old fields, naming what replaced each. `teams.min`, `teams.max` and the `perTeam` counts must be whole numbers. A presentation reads `game.maxTicks` (was `game.ticks`). A scenario's `teams.defaultNames` replaces the game's list whole, rather than falling back to the game's name past its end. A settings resource named `game` is refused with `SETTINGS_RESERVED`. In the dev server, an edit to the manifest's `maxTicks` or team bounds waits for the next initialisation, as every settings edit does. The `CLAUDE.md.template`, `DESIGN.md.liquid` and `README.md.liquid` scaffolds say `maxTicks`. See [step 2g](guides/upgrading.md#2g-rename-ticks-to-maxticks-and-move-a-scenarios-game-fields-into-settingsgame)
38
41
  - **A single-team game locks `teams.max`.** A game is single-team only when it declares `teams.max: 1` and locks it with `gameSettingsConstraints: { "teams": { "max": { "readOnly": true } } }`. A `teams.max` of 1 left unlocked is treated as possibly multi-team, as an omitted one is, so an independent game whose engine writes a shared capability fails the build until it adds the lock, and its message says so. The rule that a scenario or setup could not widen a `teams.max` of 1 is gone: the lock is what does that now. See [step 2g](guides/upgrading.md#2g-rename-ticks-to-maxticks-and-move-a-scenarios-game-fields-into-settingsgame)
39
- - **The game-level `configuration` block is removed, and a scenario's `configuration` is `settings`.** A game sets its own values as its settings' defaults, and the build refuses both old fields. Scenario overrides, `sdk configure` overrides and `configures` are keyed by settings identifier. `sdk update package` no longer accepts a `configuration` block
40
- - **Setup and the scenario editor are slots.** `configuration-user-interfaces/` and `configurationSurfaces` are removed, and the build refuses both: a quick-config UI moves to `setup/setup.sdk.json`, a scenario builder to `scenario_editor/scenario_editor.sdk.json`. Both use `SettingsEditorWrapper` and `useSettingsEditor()` (`{ settings, updateSettings, configures }`), replacing the `useConfigurationUserInterface*` hooks and types, and `renderSettingsEditor` replaces `renderConfigurationUserInterface`. `sdk new setup` and `sdk new scenario_editor` take no name. The configuration step exists exactly when a game has `setup`, and the host refuses `requestPlay` from the scenario editor. `CLAUDE.md.template`, `DESIGN.md.liquid`, `README.md.liquid`, `workflow-create-endpoint.md` and `workflow-test-engine-or-ui.md` are updated. See [step 3](guides/upgrading.md#step-3-move-configuration-uis-into-the-setup-and-scenario-editor-slots)
42
+ - **The game-level `configuration` block is removed, and a scenario's `configuration` is `settings`.** A game sets its own values as its settings' defaults, and the build refuses both old fields. Scenario overrides, `sdk configure` overrides and `configures` are keyed by settings identifier. `sdk update package` no longer accepts a `configuration` block. See [steps 2b and 2c](guides/upgrading.md#2b-fold-the-game-level-configuration-block-into-the-defaults)
43
+ - **Setup and the scenario editor are slots.** `configuration-user-interfaces/` and `configurationSurfaces` are removed, and the build refuses both: a quick-config UI moves to `setup/setup.sdk.json`, a scenario builder to `scenario_editor/scenario_editor.sdk.json`. Both use `SettingsEditorWrapper` and `useSettingsEditor()` (`{ settings, updateSettings, configures }`), replacing the `useConfigurationUserInterface*` hooks and types, and `renderSettingsEditor` replaces `renderConfigurationUserInterface`. `sdk new setup` and `sdk new scenario_editor` take no name. The configuration step exists exactly when a game has `setup`, and the host refuses `requestPlay` from the scenario editor. `CLAUDE.md.template`, `DESIGN.md.liquid`, `README.md.liquid`, `workflow-create-endpoint.md` and `workflow-test-engine-or-ui.md` are updated. In `@seriousgaming/sdk/e2e`, `DEV_SERVER.configureUrl()` and `scenarioBuilderUrl()` are `setupUrl()` and `scenarioEditorUrl()`. See [step 3](guides/upgrading.md#step-3-move-configuration-uis-into-the-setup-and-scenario-editor-slots)
41
44
 
42
45
  #### Logic
43
46
 
@@ -45,44 +48,49 @@ are in the [0.x changelog](changelog-0.x.md).
45
48
  - **Shared state has its own channel.** `InitAggregate` and `RunAggregate` receive the shared store once, as `shared.context`, and each `teams[i].context` carries that team's own capabilities only; a shared capability returned in a `teams` entry fails the init or tick. Type aggregates as `RunAggregateFunction<TeamContext, SharedContext, Settings>`. A session UI's `SessionData` is `{ shared, teams }`, and its generated `types.ts` adds `TeamContext`, `SharedWrites` and `SessionData`, with `SharedContext` now covering shared reads too. `createMockSharedState` joins the UI testing helpers. The aggregate engine and session UI templates, `DESIGN.md` and the starter game are updated. See [step 5](guides/upgrading.md#step-5-read-shared-state-from-its-own-channel)
46
49
  - **One name for each thing.** `meta.currentTick` is `meta.tick`; every count of completed ticks (`useUserInterfaceData().currentTick`, session and presentation team `tick`, endpoint `session.tick`, CLI JSON `currentTick`) is `completedTicks`; one `TimerState` replaces five timer types, with `enabled`, `paused`, `intervalMs` and `pausedMs`; a tick controller returns `enabled`, `intervalMs` and `complete` and always receives `teams` as `{ teamId, index, context }`; `teamName` is `name`; `Participant` replaces `SessionParticipant`, `UserInterfaceTeamParticipant` and `UserInterfaceParticipant`; `TeamInfo` replaces `EndpointTeam`; and the player-surface hooks are `useUserInterfaceViewerRole`, `useUserInterfaceOwnTeam`, `useUserInterfaceOwnTeamJoinLink` and `useUserInterfaceCrossTeamData`. See [step 6](guides/upgrading.md#step-6-one-name-for-each-thing)
47
50
  - **Completion is `complete` and a record's time is `recordedAt`.** `isComplete` is `complete` on an endpoint's `session` and team statuses, past-state entries and the state projection, and a past-state entry's `timestamp` is `recordedAt`. See [step 6d](guides/upgrading.md#6d-completion-record-times-blob-retention-and-the-manifest-types)
48
- - **The settings-editor blob retention is `settings`.** `writeBlob(data, { retention: 'config' })` is refused; pass `retention: 'settings'`, which is also what a setup or scenario editor upload is stored with
49
- - **The manifest types take manifest names.** `SDKConfiguration`, the authored `seriousgaming.sdk.json`, is `PackageManifest`; `Configuration`, the built `seriousgaming.json`, is `ResolvedPackageManifest`; and `LogicConfiguration` is `LogicLayout`
51
+ - **The settings-editor blob retention is `settings`.** `writeBlob(data, { retention: 'config' })` is refused; pass `retention: 'settings'`, which is also what a setup or scenario editor upload is stored with. See [step 6d](guides/upgrading.md#6d-completion-record-times-blob-retention-and-the-manifest-types)
52
+ - **The manifest types take manifest names.** `SDKConfiguration`, the authored `seriousgaming.sdk.json`, is `PackageManifest`; `Configuration`, the built `seriousgaming.json`, is `ResolvedPackageManifest`; and `LogicConfiguration` is `LogicLayout`. See [step 6d](guides/upgrading.md#6d-completion-record-times-blob-retention-and-the-manifest-types)
50
53
  - **Timer durations are milliseconds, which the compiler cannot catch.** `intervalTick(intervalMs)`, a tick controller's `intervalMs`, a settings `intervalMs` default and a session UI's `extendTick(byMs, teamId?)` take milliseconds where they took seconds: `intervalTick(60)` is refused as below the 30-second minimum, and `extendTick(120)` extends by 120 ms. See [step 6c](guides/upgrading.md#6c-timers-in-milliseconds)
51
54
  - **A validator names what it gates.** Rename `Run` to `UpdateData`; the build refuses a validator exporting `Run`, or neither gate. The `validator/logic.ts.liquid` scaffold and its test export `UpdateData`. See [step 8](guides/upgrading.md#step-8-rename-each-validators-run-to-updatedata)
52
- - **Logic may not import Node built-ins.** `sdk build`, `dev` and `tick` refuse one with `LOGIC_NODE_BUILTIN`, and the dev server no longer gives logic `require`, matching production
55
+ - **Logic may not import Node built-ins.** `sdk build`, `dev` and `tick` refuse one with `LOGIC_NODE_BUILTIN`, and the dev server no longer gives logic `require`, matching production. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
56
+ - **Logic that changes a capability outside its `writes` fails, and so does a per-team `Init` or `Run` that changes a shared one.** That covers an engine's `Init` and `Run`, both halves of an aggregate result (`shared` and each `teams` entry), and hooks, whether the capability is one the resource only reads or one it never declared; 0.6 kept the change. The call fails naming the capability, and nothing of its result is applied. A capability returned unchanged, as the `{ ...context }` spread returns it, still passes. Add the capability to `writes`, and move a shared write into `InitAggregate` or `RunAggregate`. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
53
57
  - **Logic argument types require `meta.now` and `participants`**, so a test that builds arguments by hand passes both, or uses `logicArgs` (see Added). A test double typed as a generated `Callbacks` must supply every declared service, and `LogicCallbacks` takes `ApiUse` values. See [step 10](guides/upgrading.md#step-10-update-the-tests)
58
+ - **Test sessions and the state projection take 1.0 names.** A `createTestSession` endpoint call with `uiIdentifier: ''` is refused as `denied`; leave `uiIdentifier` out for a system call. `runCommand({ type: 'updateConfig' })` is `updateSettings`, keyed by settings identifier. The state projection `sdk view` and `sdk play` print is version 4: `settings`, `completedTicks`, `complete`, a full `TimerState` and participants with `teamId`. See [step 10a](guides/upgrading.md#10a-move-off-gamerunner) and [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
54
59
 
55
60
  #### Endpoints
56
61
 
57
- - **`agentCallable` is replaced by `visibility`.** Replace `"agentCallable": true` with `"visibility": "external"`, and delete `"agentCallable": false`; the build refuses the old field. `sdk endpoint list --agent` is `--external`, and `caller.userInterfaceIdentifier` is optional. See [step 7](guides/upgrading.md#step-7-update-endpoints)
62
+ - **`agentCallable` is replaced by `visibility`.** Replace `"agentCallable": true` with `"visibility": "external"`, and delete `"agentCallable": false`; the build refuses the old field. `sdk endpoint list --agent` is `--external`, and `caller.userInterfaceIdentifier` is optional: `sdk endpoint call` leaves it out, where it sent `'cli'`. `EndpointCaller.role` is the `EndpointCallerRole` union rather than `string`. See [step 7](guides/upgrading.md#step-7-update-endpoints)
58
63
  - **An external endpoint's request is an object.** The build refuses an endpoint with `"visibility": "external"` whose `requestSchema` is not `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`), since an outside caller, such as an AI agent, passes named arguments. Internal endpoints are unaffected. See [step 7a](guides/upgrading.md#7a-replace-agentcallable-with-visibility)
59
- - **Handlers receive `settings`, `session` and, team-scoped, `team`.** The generated `Handler` type requires them, so a unit test building arguments by hand passes them, or uses `logicArgs.endpoint`. A session-scoped handler's type has no `team`
64
+ - **Handlers receive `settings`, `session` and, team-scoped, `team`.** The generated `Handler` type requires them, so a unit test building arguments by hand passes them, or uses `logicArgs.endpoint`. A session-scoped handler's type has no `team`. See [step 7b](guides/upgrading.md#7b-handle-the-new-arguments)
60
65
  - **`caller.teamId` is the caller's own team**, absent for a facilitator or a caller outside the game, where it held the endpoint's target team. Read the target from `team`. See [step 7d](guides/upgrading.md#7d-read-the-target-team-from-team)
61
66
  - **The scenario editor calls only endpoints that need no session.** The build refuses a `scenario_editor` listing an endpoint that declares `reads`, `writes` or `actions` (`EDITOR_ENDPOINT_STATEFUL`), and the dev server answers a call from the editor with no session: the endpoint's `settings` resolved from the scenario being edited and the editor's unsaved changes, an empty `context`, no participants, a `session` of nothing played, and a `caller` of the new role `'author'`, not `'facilitator'`, since whoever creates a scenario may not be a facilitator, with no `sessionId`, which is now optional on `EndpointCaller`. The `workflow-create-endpoint.md` rule says so. See [step 7e](guides/upgrading.md#7e-give-the-scenario-editor-endpoints-that-need-no-session)
62
- - **Endpoint failures are typed.** A surface's endpoint call rejects with `EndpointError` (`kind`, `outcome`, `applied`, `failedStep`), `callEndpoint:response` carries those fields in place of `error`, and `Session.query` and `createTestSession().send` answer `{ type: 'endpointFailure', failure }` instead of throwing
67
+ - **Endpoint failures are typed.** A surface's endpoint call rejects with `EndpointError` (`kind`, `outcome`, `applied`, `failedStep`), `callEndpoint:response` carries those fields in place of `error`, and `Session.query` and `createTestSession().send` answer `{ type: 'endpointFailure', failure }` instead of throwing. See [step 7c](guides/upgrading.md#7c-branch-on-an-endpoint-failures-kind)
63
68
 
64
69
  #### Surfaces
65
70
 
66
- - **A player surface writes only what it declares.** A game UI or waiting room write (or `deletes` path) naming a capability outside its `writes`, or any key that is not a capability, is refused as `denied`
67
- - **A session UI's team write changes only what it declares.** A write through `setData(teamId, update)` that changes a capability outside the session UI's `writes`, or names a key that is not a capability, is refused as `denied`, where 0.6 applied it. A capability carried back unchanged is still accepted, so a surface that returns a team's whole context with one field edited keeps working. Add the capability to the session UI's `writes`
68
- - **`uses` on user interfaces is removed**, and the build refuses it. It never had an effect; a surface reaches a service through an endpoint that declares it
69
- - **Demo mode is removed.** `demo` in the manifest and scenarios, `GameDemo` and `sdk dev --demo` are gone, and the build refuses the field. Use a walkthrough run to show a game
71
+ - **A player surface writes only what it declares.** A game UI or waiting room write (or `deletes` path) naming a capability outside its `writes`, or any key that is not a capability, is refused as `denied`. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
72
+ - **A session UI's team write changes only what it declares.** A write through `setData(teamId, update)` that changes a capability outside the session UI's `writes`, or names a key that is not a capability, is refused as `denied`, where 0.6 applied it. A capability carried back unchanged is still accepted, so a surface that returns a team's whole context with one field edited keeps working. Add the capability to the session UI's `writes`. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
73
+ - **`uses` on user interfaces is removed**, and the build refuses it. It never had an effect; a surface reaches a service through an endpoint that declares it. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
74
+ - **Demo mode is removed.** `demo` in the manifest and scenarios, `GameDemo` and `sdk dev --demo` are gone, and the build refuses the field. Use a walkthrough run to show a game. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
75
+ - **A session UI's callbacks include `deleteTeam`**, so a hand-built callbacks object in a test must supply it. See [step 10d](guides/upgrading.md#10d-update-ui-component-tests)
76
+ - **Four `./ui` names pair with their hook or theme type.** `CrossTeamDataContext` is `UserInterfaceCrossTeamDataContext`, `UserInterfaceValidationContext` is `UserInterfaceValidationRejectionsContext` (its value type `UserInterfaceValidationRejectionsValue`), and in `./ui/testing` `createMockTheme` is `createMockUserInterfaceTheme` and `createMockSessionTheme` is `createMockSessionUserInterfaceTheme`
70
77
 
71
78
  #### CLI
72
79
 
73
80
  - **The CLI's results are a contract.** With `--json`, every command writes one envelope: `{ "ok": true, "command", "data", "diagnostics", "warnings" }` on success and `{ "ok": false, "command", "error": { "code", "message", "hint", "details" }, "diagnostics", "warnings" }` on failure. `new`, `update` and `delete` used to print `{ "success", ... }`; `build --validate-only --json` puts its summary in `data` and each finding in `diagnostics`; `package bundle`, `package version`, `package publish`, `configure`, `blob upload`, `endpoint list`, `endpoint audit` and `dev status` put their result in `data`; and a failing `endpoint call` reports in `error.details`. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
74
- - **Exit codes say what kind of failure it was.** 1 is a bug in the CLI, 2 a usage error, 3 an invalid package, 4 a refusal by the game (including a failed tick) and 5 the environment, where every failure used to exit 1
75
- - **`delete --force` is `delete --yes`**, which also answers an interactive `update`'s confirmation
76
- - **`blob upload --config` is `blob upload --settings`**, and its `retention` reads `settings`. `tick --json` and `view` report `complete` in place of `isComplete`, and `view --tick N` entries carry `recordedAt` in place of `timestamp`
77
- - **The CLI never waits on a prompt without a terminal.** Without a terminal on both stdin and stdout, with `--json` or `SERIOUSGAMING_JSON`, or with `CI` set, a command that would ask fails with exit 2 and `PROMPT_REQUIRED`. Stdin is read to its end rather than for 100ms
78
- - **`new package` fails when `pnpm install` fails** in the new package (exit 5, `INSTALL_FAILED`). The files are written; run `pnpm install` to finish
79
- - **`session.needsConfiguration` is `session.inSetup`** on session state (`createTestSession().state()`, `@seriousgaming/sdk/e2e`, the dev server's `/api/session`) and in `sdk reconfigure --json`, matching the spec's name for the setup state
81
+ - **Exit codes say what kind of failure it was.** 1 is a bug in the CLI, 2 a usage error, 3 an invalid package, 4 a refusal by the game (including a failed tick) and 5 the environment, where every failure used to exit 1. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
82
+ - **`delete --force` is `delete --yes`**, which also answers an interactive `update`'s confirmation. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
83
+ - **`blob upload --config` is `blob upload --settings`**, and its `retention` reads `settings`. `tick --json` and `view` report `complete` in place of `isComplete`, and `view --tick N` entries carry `recordedAt` in place of `timestamp`. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
84
+ - **The CLI never waits on a prompt without a terminal.** Without a terminal on both stdin and stdout, with `--json` or `SERIOUSGAMING_JSON`, or with `CI` set, a command that would ask fails with exit 2 and `PROMPT_REQUIRED`. Stdin is read to its end rather than for 100ms. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
85
+ - **`new package` fails when `pnpm install` fails** in the new package (exit 5, `INSTALL_FAILED`). The files are written; run `pnpm install` to finish. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
86
+ - **`session.needsConfiguration` is `session.inSetup`** on session state (`createTestSession().state()`, `@seriousgaming/sdk/e2e`, the dev server's `/api/session`) and in `sdk reconfigure --json`, matching the spec's name for the setup state. `sdk timer --json` reports a whole `TimerState`, so its interval is `intervalMs`. See [step 11](guides/upgrading.md#step-11-update-scripts-and-agents-that-drive-the-cli)
80
87
 
81
88
  ### Added
82
89
 
83
90
  #### Logic and testing
84
91
 
85
92
  - **`logicArgs` in `@seriousgaming/sdk/testing`.** `logicArgs.run({ context, settings: defaultSettings })` builds the arguments a logic function takes, filling `meta` (a fixed `seed` and `now`), the roster and offline stub callbacks around what the test names, typed from the function it is passed to. There are builders for `init`, `run`, `aggregate`, `hook`, `endpoint`, `tickController`, `validator` and `requestTick`, and the stubs are exported as `createStubCallbacks()`. See [Testing](guides/testing.md#testing-the-run-function)
93
+ - **An endpoint that lists settings gets a generated `defaultSettings`** in its `defaults.ts`, ready to pass to `logicArgs.endpoint`
86
94
  - **Typed test sessions.** `createTestSession<Context, SharedContext>(options)` types what a test reads back and writes, and adds `tick({ team })`, `requestTick(team)`, `setData(team, patch, { deletes, as })`, `setSharedData(patch)`, `team(index)` and `shared`, which holds the shared store under `context` as a session surface's `sessionData.shared` does. `createStubServices`, `stubGenerateText` and `TestServices` are exported from `sdk-tools/client`. See [Engine testing](guides/engine-testing.md#injecting-decisions)
87
95
  - **`meta.now` on every logic call**, the operation's time in milliseconds, the same for every team in one tick and controlled by the session clock in tests, and **a read-only `participants` roster**: per-team logic sees its team; aggregates, the tick controller and session-scoped endpoints see everyone
88
96
  - **Logic can delete keys.** `Init`, `Run`, a hook's `Run`, each level of an aggregate result and a writing endpoint may return `deletes` beside `capabilities`, with the same paths and rules as a UI's `setData` deletes. See [Removing a key](guides/engine.md#removing-a-key)
@@ -104,13 +112,13 @@ are in the [0.x changelog](changelog-0.x.md).
104
112
  - **Capabilities that undo and reset leave alone.** `"lifetime": "session"` keeps a value exactly as it was across an undo, a per-team reset and a session reset, for facilitator state such as a pacing gate or an announcement. The build refuses one in the engine's `reads` or `writes`. See [Lifetime](guides/capabilities.md#lifetime)
105
113
  - **`tsType` on a capability schema property** names the TypeScript type the generated `types.ts` uses, so reads of a loose object need no cast. See [A TypeScript type of your own](guides/capabilities.md#a-typescript-type-of-your-own)
106
114
  - **`scenarioFormat` in `seriousgaming.sdk.json`**, an integer from 1. Bump it when a release would make a saved custom scenario wrong, and a runtime refuses scenarios saved under another format. See [Scenario format: when to bump it](guides/scenarios.md#scenario-format-when-to-bump-it)
107
- - **`requires` in `seriousgaming.sdk.json`**: an optional list of the runtime features a game depends on. A runtime without one refuses the package at load and names it, and `sdk build` does the same for a feature the installed SDK does not support. No optional features exist yet
115
+ - **`requires` in `seriousgaming.sdk.json`**: an optional list of the runtime features a game depends on. A runtime without one refuses the package at load and names it, and `sdk build` does the same for a feature the installed SDK does not support. No optional features exist yet. `sdk build` refuses a feature the installed SDK does not support with a `FEATURE_UNSUPPORTED` diagnostic pointing at the entry
108
116
 
109
117
  #### Endpoints
110
118
 
111
119
  - **External endpoints.** `"visibility": "external"` publishes an endpoint to any caller outside the game (a facilitator's AI agent, a platform API or another integration), whose handler sees `caller.role` as `'external'`. `sdk endpoint call --external` makes a call the way an outside caller does
112
- - **Endpoints know their team and where the session stands.** A team-scoped handler receives `team: { teamId, index, name }`, and every handler `session`: the ticks completed, the tick limit, the waiting room, completion, and each team's standing. Declare `roster: true` to list each team's participants too
113
- - **Endpoints can act on the session.** An endpoint that declares `actions` may return `actions: [{ type: 'setWaitingRoom', open: false }, { type: 'tick' }]` beside its response, carried out after its write in one step: tick, the timer controls, the waiting room, renaming and adding teams, moving participants and the locale. Export `Plan` and `Respond` in place of `Handle` to answer after the actions land
120
+ - **Endpoints know their team and where the session stands.** A team-scoped handler receives `team: { teamId, index, name }`, and every handler `session`: the ticks completed, the tick limit, the waiting room, completion, and each team's standing. Declare `roster: true` to list each team's participants too. A call from the CLI or `createTestSession` passes the team too, and one naming a team id and index that disagree, or no team in a session of several, is refused
121
+ - **Endpoints can act on the session.** An endpoint that declares `actions` may return `actions: [{ type: 'setWaitingRoom', open: false }, { type: 'tick' }]` beside its response, carried out after its write in one step: tick, the timer controls, the waiting room, renaming and adding teams, moving participants and the locale. Export `Plan` and `Respond` in place of `Handle` to answer after the actions land. An `extendTick` action may pull the deadline in with a negative `byMs`
114
122
  - **A session-scoped endpoint can write individual teams**, returning `teams: { 'team-1': { ... } }`: every team's patch lands, or none does
115
123
  - **Endpoints can take files.** Mark a request property with `"blob": { "accept": [...], "maxBytes": ... }` and the handler receives a checked `blob:` reference, whether the caller uploaded first or sent the bytes inline as a `data:` URI
116
124
  - **`EndpointError`** and the `EffectStep`, `EndpointFailure`, `EndpointFailureOutcome` and `EndpointCallResult` types
@@ -120,9 +128,10 @@ are in the [0.x changelog](changelog-0.x.md).
120
128
  #### User interfaces
121
129
 
122
130
  - **A game can ship a presentation.** A UI bundle in the `presentation/` slot becomes the facilitator's slide deck: read-only, shown during a session with every team's results or with no session at all. Every runtime offers it. Build it with the new `@seriousgaming/deck` package, published in lockstep with the SDK, which gives slides, click-to-reveal steps, transitions, building blocks in the theme's colours, and export to PDF, editable PowerPoint and PNG. `sdk new presentation` scaffolds a starter deck, the dev console shows it at `/presentation`, new packages depend on the deck, and the scaffold gains a `workflow-create-presentation.md` rule and a 'Presentations' section in `CLAUDE.md.template`. See [Building presentations](guides/presentation.md)
123
- - **UI hooks for assets and past state.** `useAssetUrl(ref)` returns an asset's URL, or `undefined` until the host has sent them; `useAsset(ref, { as, locale? })` fetches and reads an asset, trying the locale's copy first; `usePastState(query)` wraps `getPastState` and drops overtaken answers. See [Reviewing past ticks](guides/ui.md#reviewing-past-ticks)
131
+ - **UI hooks for assets and past state.** `useAssetUrl(ref)` returns an asset's URL, or `undefined` until the host has sent them; `useAsset(ref, { as, locale? })` fetches and reads an asset, trying the locale's copy first, then each shorter form of its code (`zh-Hant-TW`, `zh-Hant`, `zh`); `usePastState(query)` wraps `getPastState` and drops overtaken answers. See [Reviewing past ticks](guides/ui.md#reviewing-past-ticks)
124
132
  - **`useViewerStorage(key, initial)`** on every surface: browser storage namespaced by session, viewer and surface, falling back to memory where storage is blocked. The handshake carries an opaque `sessionKey` for it, and the `render*` test helpers take a `sessionKey` option
125
133
  - **The wrappers set `lang`, `dir` and `color-scheme` on the document**, in step with the locale and the theme. The scaffolded `main.tsx` files no longer set `lang` and `dir` themselves
134
+ - **Locale codes take scripts, three-letter languages and numeric regions**, such as `es-419`, `zh-Hant`, `zh-Hant-TW` and `fil`, wherever the manifest and scenarios name a locale
126
135
  - **`contrastText` on every theme colour**, meeting WCAG AA against it (`ThemeColorRole`, `ThemeContrastText`). The `theme.ts` templates, `CLAUDE.md.template`, `workflow-create-user-interface.md`, `workflow-create-engine.md` and `workflow-test-engine-or-ui.md` are updated
127
136
  - **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
128
137
  - **Typed session writes and test fixtures.** A session UI's generated `types.ts` adds `TeamWrites`, the team-scope capabilities in its `writes`, and `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` types the per-team `setData(teamId, update)` with it, so a team write naming a shared capability fails to compile. `createMockTeamState<TeamContext>`, `createMockSharedState<SharedContext>` and `renderSessionUserInterface<SessionData>` type a test's fixtures the same way. Every parameter defaults to today's untyped form, so existing code compiles unchanged. See [Session UIs](guides/testing.md#session-uis)
@@ -139,49 +148,73 @@ are in the [0.x changelog](changelog-0.x.md).
139
148
  - **A dev server for tests and recordings, beside your own.** `sdk dev --isolated` keeps no lock file, ignores saved configuration and keeps uploads in a temporary directory; `--port auto` takes free ports; `SERIOUSGAMING_DEV_URL` points session commands at a server; and `startDevServer(options)` from `@seriousgaming/sdk-tools/client` starts one in a test runner. See [Run a second server beside your own](cli-reference.md#run-a-second-server-beside-your-own)
140
149
  - **The dev server picks up more without a restart**: edits to `seriousgaming.sdk.json`, a surface added while it runs, and a capability added while it runs, seeded from its defaults. `sdk dev --reinit-on-change` restarts the game at tick 0 on every edit that applies only at initialisation
141
150
  - **`SERIOUSGAMING_DEV_STATE_DIR`** keeps the dev server's lock file outside the package
142
- - **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
151
+ - **`LLM_NOT_CONFIGURED` (exit 5)** for a tick or endpoint call whose logic called `generateText` with no platform API key configured, with a one-line message and a hint saying how to set the key, in place of the multi-line banner
143
152
  - **The SDK has a README** saying which subpaths carry semver guarantees (the root, `./ui` and `./ui/testing`)
144
153
  - **`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
145
154
 
155
+ #### For runtimes
156
+
157
+ - **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
158
+ - **A conformance suite, `@businesssimulations/seriousgaming-conformance-v3`**, runs the specification's conformance checklist against a runtime through a driver. A check that needs a driver capability the host does not offer is reported unsupported rather than failed: `external-callers` and `setup-state`, and the test affordances `held-tick`, `ordered-submission`, `scenario-selection` and `override-inspection`, which a production host may leave unsupported. Its endpoint checks call through a surface, and its self-navigation checks run under a production content security policy. A game needs none of it
159
+
146
160
  ### Changed
147
161
 
148
- - **The session scaffold uses the generated types throughout.** `sdk new session` writes an `App.tsx` that passes `SharedWrites` and `TeamWrites` to `useSessionUserInterfaceData`, so both forms of `setData` are typed, and an `App.test.tsx` that renders through `renderSessionUserInterface<SessionData>()` with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()` in place of a hand-built provider tree, so a shared capability on a team fixture fails to compile. The guidance names the type argument too: merge the changes to `CLAUDE.md.template`, `claude/rules/workflow-create-user-interface.md` and `claude/rules/workflow-test-engine-or-ui.md`, and the session templates `session/src/App.tsx.liquid` and `session/src/App.test.tsx.liquid`, into a game you scaffolded earlier
149
- - **Docs restructured: one guide per resource kind, steps-only recipes, and generated CLI, API and error-code reference.** Each concept page is folded into its guide, recipes are cut to their steps and link to the guide, the CLI reference, the API reference (`api/`) and [CLI error codes](cli-error-codes.md) are generated from the code, the upgrading guide covers 0.6 to 1.0 only, and releases before 1.0 move to [changelog-0.x.md](changelog-0.x.md). The scaffold's `CLAUDE.md.template` and the `workflow-test-engine-or-ui.md`, `workflow-create-user-interface.md` and `workflow-create-presentation.md` rules now link to the shipped guides for settings resolution, the UI test harness and presentation habits rather than restating them; merge them from `dist/templates/package/`. The same pages are published as a versioned docs site, one directory per release plus `latest/`, with an `llms.txt` index and an `llms-full.txt` holding the whole documentation as one file for agents
150
- - **The published packages declare Node 24 or later** in `engines`, and link to the docs site at https://sdk.seriousgaming.com/ rather than to the source repository. The scaffold's `workflow-update-sdk-version.md` rule names all three packages it bumps; merge it from `dist/templates/package/`
151
- - **The packages carry licences.** `@seriousgaming/sdk` and `@seriousgaming/deck` are Apache-2.0. `@seriousgaming/sdk-tools` is under the Serious Gaming SDK Tools Licence in its `LICENSE` file: use it to build, test and publish games for the Serious Gaming platform; files it generates or copies into your project are yours under Apache-2.0. All three were `UNLICENSED`
152
- - **A settings edit no longer applies mid-session.** At tick 0 the dev server re-initialises on the edit; once a tick is played it keeps the settings the session started with, the console offers a Re-initialise button, and `sdk tick`, `sdk undo`, a context patch and a writing endpoint call are refused with `SETTINGS_STALE` until `sdk init`. The same applies to `teams`, `waitingRoom.openOnStart` and `identifier`, adding or removing `setup`, and removing a capability or changing its `scope`. See [What reloads](cli-reference.md#what-reloads)
153
- - **The dev server listens on `localhost` only.** It used to accept connections from any machine on the network. To test on a phone or tablet, start it with `pnpm run sdk dev --lan`. See [Start the dev server](cli-reference.md#start-the-dev-server)
162
+ #### Logic and testing
163
+
164
+ - **The engine function types compile without type arguments.** A bare `RunFunction`, `InitializationFunction`, `StepFunction`, `GetTickControllerFunction`, `InitAggregateFunction` or `RunAggregateFunction` defaults its context and settings, where every type argument was required
154
165
  - **Test sessions are offline by default.** `createTestSession` stubs `generateText`, `generateSpeech` and `extractText` with deterministic answers; pass `services: 'platform'` to reach the real services. A hand-built theme object needs `contrastText`
155
- - **Surfaces never retry a `conflict` themselves**; a runtime with optimistic concurrency retries a losing write before reporting it
156
166
  - **A tick whose logic throws is `tick-failed`**, where the dev server reported it as `error`. A surface's `requestTick` rejects with `kind: 'tick-failed'`, and `sdk tick` fails with `TICK_FAILED`
157
- - **Every runtime offers walkthrough runs**, so `setWalkthroughLink` always carries a link and `useSessionUserInterfaceWalkthroughLink()` is `null` only until the host sends it. `callbacks.resetWalkthrough()` is refused as `denied` while the session has no walkthrough, and for a named team
158
- - **`sdk team remove` refuses a team with participants, and any team in a shared-state session.** Move participants out with `sdk participant move` first. A team added later at the freed index is a new team
159
- - **A tick controller's `intervalMs` is optional when its timer is off**, and a game with neither `maxTicks` nor a tick controller builds with a warning, since its engine can end it with `complete: true`
167
+ - **A tick controller may leave out its interval when its timer is off**, where 0.6 required `interval`, and a game with neither `maxTicks` nor a tick controller builds with a warning, since its engine can end it with `complete: true`
160
168
  - **A returned capability merges one level deep.** Each variable an engine, hook or endpoint returns replaces its old value whole, objects included, so `PendingJunction: {}` empties it. The dev server and `createTestSession` already did this; it is now the rule for every runtime. See [How a result folds into the context](guides/engine.md#how-a-result-folds-into-the-context)
169
+ - **`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
170
+
171
+ #### Settings and scenarios
172
+
173
+ - **A settings edit no longer applies mid-session.** At tick 0 the dev server re-initialises on the edit; once a tick is played it keeps the settings the session started with, the console offers a Re-initialise button, and `sdk tick`, `sdk undo`, a context patch and a writing endpoint call are refused with `SETTINGS_STALE` until `sdk init`. The same applies to `teams`, `waitingRoom.openOnStart` and `identifier`, adding or removing `setup`, and removing a capability or changing its `scope`. See [What reloads](cli-reference.md#what-reloads)
161
174
  - **A saved custom scenario is validated against the package each time it is used**, and refused with the offending keys named rather than opened on defaults
175
+
176
+ #### User interfaces
177
+
178
+ - **Every value the runtime reports to a game is a fixed set**: the viewer role, the run kind, host overlays, mutation and endpoint failure kinds, and the LLM `stopReason` and content block types. A value added in a later release reaches only a game that lists the feature adding it in `requires`; any other game sees the nearest existing value (an observer, `'session'`, `'error'` or `'endTurn'`), so a `switch` over these can be exhaustive. The SDK's wrappers and LLM client apply the same fallbacks should a host ever send an unknown value, so a surface opens as an observer rather than staying blank, and an unknown `stopReason` reads as `'endTurn'` rather than failing the call
179
+ - **Surfaces never retry a `conflict` themselves**; a runtime with optimistic concurrency retries a losing write before reporting it
180
+ - **Every runtime offers walkthrough runs**, so `setWalkthroughLink` always carries a link and `useSessionUserInterfaceWalkthroughLink()` is `null` only until the host sends it. `callbacks.resetWalkthrough()` is refused as `denied` while the session has no walkthrough, and for a named team
181
+ - **The UI library no longer logs every host ping to the browser console**
182
+
183
+ #### CLI and dev server
184
+
185
+ - **The dev server listens on `localhost` only.** It used to accept connections from any machine on the network. To test on a phone or tablet, start it with `pnpm run sdk dev --lan`. See [Start the dev server](cli-reference.md#start-the-dev-server)
186
+ - **`sdk team remove` refuses a team with participants, and any team in a shared-state session.** Move participants out with `sdk participant move` first. A team added later at the freed index is a new team
162
187
  - **A CLI command notices a dev server started by other tools.** After an upgrade or rebuild, a command replaces a server it started in the background, and fails with `SESSION_STALE` (exit 5) for one you started with `sdk dev`
163
188
  - **Every session command repeats what the dev server could not apply live** (`SETTINGS_STALE`, `RELOAD_FAILED`, `CAPABILITY_SEEDED`) on stderr and in `warnings`, and `GET /api/session` reports them
164
189
  - **The dev server runs the checks `sdk build` runs**, at start and after every edit. A package `build` would refuse still runs, so you can fix it while you watch, but each error is printed on stderr, shown in a banner on the console, and listed in `GET /api/session` `warnings` with its diagnostic code (for example `REFERENCE_UNKNOWN`) and `build: true`, so every session command repeats it. See [Where the session lives](cli-reference.md#where-the-session-lives)
165
190
  - **A schema error the SDK cannot explain points at the upgrading guide**, and a refused shared write from a session UI says why
166
191
  - **The `@seriousgaming/sdk/e2e` helpers find the dev server through `SERIOUSGAMING_DEV_URL`** and take `{ url }` beside `{ port }`
167
- - **The UI library no longer logs every host ping to the browser console**
168
- - **The scaffolded `CLAUDE.md` is half the length and leads with what not to do.** It opens with 'Non-negotiables' and an index of `.claude/rules/`, points at the docs shipped inside `@seriousgaming/sdk-tools` (`sdk docs view`), teaches the CLI's result contract (envelope, exit codes, `--yes`, `diagnostics`), no longer runs `init` after `sdk configure`, and bumps `@seriousgaming/deck` with the SDK. `CLAUDE.md.template`, `workflow-create-engine.md`, `workflow-create-endpoint.md` and `workflow-create-user-interface.md` cover declared writes, typed endpoint failures, retries and the Node rule. `workflow-create-endpoint.md`, `workflow-create-engine.md`, `workflow-update-sdk-version.md`, `DESIGN.md.liquid`, `README.md.liquid` and `oxlintrc.json.template` catch up with manifest version 3. `new package --empty` writes `CLAUDE.md` and `.claude/` too. Merge them from `dist/templates/package/`
169
- - **A missing platform API key is an environment failure.** A tick or endpoint call whose logic called `generateText` with no key configured fails with `LLM_NOT_CONFIGURED` (exit 5), where it was `TICK_FAILED` or `HANDLER_ERROR` (exit 4), with a one-line message and a hint saying how to set the key, in place of the multi-line banner
170
192
  - **`sdk init` reports the scenario it started on** as `scenario` in its output, `null` when there is none
171
193
  - **`new`, `update` and `delete` report paths relative to the package root** in `filesCreated`, `filesUpdated`, `filesDeleted` and `directoriesRenamed`, where they were absolute
172
- - **A manifest failure names `seriousgaming.sdk.json`, not its absolute path**, and an unsupported `requires` carries a `FEATURE_UNSUPPORTED` diagnostic pointing at the entry
194
+ - **A manifest failure names `seriousgaming.sdk.json`, not its absolute path**
195
+
196
+ #### Scaffold
197
+
198
+ - **The session scaffold uses the generated types throughout.** `sdk new session` writes an `App.tsx` that passes `SharedWrites` and `TeamWrites` to `useSessionUserInterfaceData`, so both forms of `setData` are typed, and an `App.test.tsx` that renders through `renderSessionUserInterface<SessionData>()` with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()` in place of a hand-built provider tree, so a shared capability on a team fixture fails to compile. The guidance names the type argument too: merge the changes to `CLAUDE.md.template`, `claude/rules/workflow-create-user-interface.md` and `claude/rules/workflow-test-engine-or-ui.md`, and the session templates `session/src/App.tsx.liquid` and `session/src/App.test.tsx.liquid`, into a game you scaffolded earlier
199
+ - **The scaffolded `CLAUDE.md` is half the length and leads with what not to do.** It opens with 'Non-negotiables' and an index of `.claude/rules/`, points at the docs shipped inside `@seriousgaming/sdk-tools` (`sdk docs view`), teaches the CLI's result contract (envelope, exit codes, `--yes`, `diagnostics`), no longer runs `init` after `sdk configure`, and bumps `@seriousgaming/deck` with the SDK. `CLAUDE.md.template`, `workflow-create-engine.md`, `workflow-create-endpoint.md` and `workflow-create-user-interface.md` cover declared writes, typed endpoint failures, retries and the Node rule. `workflow-create-endpoint.md`, `workflow-create-engine.md`, `workflow-update-sdk-version.md`, `DESIGN.md.liquid`, `README.md.liquid` and `oxlintrc.json.template` catch up with manifest version 3. `new package --empty` writes `CLAUDE.md` and `.claude/` too. Merge them from `dist/templates/package/`
173
200
  - **The scaffold's `pnpm run lint` fails on a warning** (`oxlint --max-warnings=0`)
174
201
  - **The starter game declares its scenario format and describes its settings for scenario authors.** `new package` writes `scenarioFormat: 1` into `seriousgaming.sdk.json`, leaves `customScenarios` out so a new game opts into facilitator-saved scenarios deliberately, and every settings property carries a `title`, a `description` with its units, a range and, for `CurrencySymbol`, an `enum`. Whole-number settings are typed `integer`, so a scenario that sets one to a fraction is refused. The generated `types.ts` names `Menu` and `UsualDemand` and narrows `CurrencySymbol` to its three symbols
175
202
  - **The scaffold's lint refuses `any` and non-null assertions (`!`)** outside tests, `testing/` and each UI's `src/main.tsx`, and its `.gitignore` ignores Playwright's `test-results/` and `playwright-report/`. Merge `oxlintrc.json.template` and `gitignore.template` from `dist/templates/package/`
176
- - **The scaffold's dependencies are refreshed**: `@playwright/test` 1.64, `@types/node` 24.19, `@vitejs/plugin-react` 6.1.2, `jsdom` 30.1, `oxlint` 1.87, `react-i18next` 17.0.16, `vite` 8.3.4 and `vitest` 5.0.3. Merge them from `package.json.liquid`, then run `pnpm exec playwright install chromium`
203
+ - **The scaffold's dependencies are refreshed**: `@playwright/test` 1.64, `@types/node` 24.19, `jsdom` 30.1, `oxlint` 1.87, `react-i18next` 17.0.16, `vite` 8.3.4 and `vitest` 5.0.3. Merge them from `package.json.liquid`, then run `pnpm exec playwright install chromium`
177
204
  - **The scaffold's `playwright.config.ts` sets `forbidOnly` on CI**, so a stray `test.only` fails the run rather than skipping every other test. Merge it from `playwright.config.ts.liquid`
178
- - **The runtime specification settles readings implementers had to choose**: an endpoint's effects take their own `meta.now`; how a cohort tick states the boards it decided on is the runtime's choice; work outside play state may follow an endpoint's effects; a session UI's unchanged capability is compared deeply after the merge; a clamped tick-controller result is reported to operators at every evaluation; and settings the host enforces use the values frozen at play start
179
- - **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
180
- - **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
205
+ - **Scaffolded logic tests build their arguments with `logicArgs`.** The tests `new engine`, `new engine --aggregate`, `new hook`, `new endpoint` and `new validator` write use `logicArgs` from `@seriousgaming/sdk/testing` and the generated `defaultSettings`, with no casts, and a hook's test passes the payload its signal needs. The starter game's engine, hook and validator tests do the same. Existing tests keep working; copy the pattern from a freshly scaffolded resource
206
+ - **Scaffolded surfaces hand i18next the whole locale code**, so script-specific translations and right-to-left scripts such as `pa-Arab` work. Merge `i18n.changeLanguage(locale)` and `i18n.dir(locale)` from the `main.tsx.liquid` templates of `ui`, `session`, `waiting-room` and `settings-editor`, and `presentation/src/App.tsx.liquid`, into your own `main.tsx` and presentation `App.tsx`. `i18n.language` now reads `fr-CA` rather than `fr`
207
+ - **Scaffold guidance corrections.** `CLAUDE.md.template`'s game-length example patches `/maxTicks`, which the build accepts, not `/ticks`; `workflow-create-endpoint.md` lists `participants`, and `teams` on a session-scoped endpoint, among a handler's arguments; `workflow-create-capability.md` explains `scope` more plainly and mentions `lifetime: "session"`; `README.md.liquid` says a settings change waits because settings are fixed when play starts; and the UI template's commented `setData` example awaits the write through `useMutationReporter` and shows a notice when it fails (`ui/src/App.tsx.liquid`, `ui/src/i18n.ts.liquid`). Merge them from `dist/templates/package/` and the resource templates
208
+ - **The scaffold's unit tests run logic in Node and components in jsdom.** `vitest.config.ts.liquid` declares two Vitest projects: `*.test.ts` in plain Node and `*.test.tsx` in jsdom on the `vmThreads` pool, which can halve unit-test time on a game with many logic tests. A `.ts` test that renders, `renderHook` included, moves to `.tsx`. See [step 12](guides/upgrading.md#step-12-refresh-the-scaffolds-furniture)
181
209
 
182
- - **`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
210
+ #### Packages and docs
211
+
212
+ - **Docs restructured: one guide per resource kind, steps-only recipes, and generated CLI, API and error-code reference.** Each concept page is folded into its guide, recipes are cut to their steps and link to the guide, the CLI reference, the API reference (`api/`) and [CLI error codes](cli-error-codes.md) are generated from the code, the upgrading guide covers 0.6 to 1.0 only, and releases before 1.0 move to [changelog-0.x.md](changelog-0.x.md). The scaffold's `CLAUDE.md.template` and the `workflow-test-engine-or-ui.md`, `workflow-create-user-interface.md` and `workflow-create-presentation.md` rules now link to the shipped guides for settings resolution, the UI test harness and presentation habits rather than restating them; merge them from `dist/templates/package/`. The same pages are published as a versioned docs site, one directory per release plus `latest/`, with an `llms.txt` index and an `llms-full.txt` holding the whole documentation as one file for agents
213
+ - **The published packages declare Node 24 or later** in `engines`, and link to the docs site at https://sdk.seriousgaming.com/ rather than to the source repository. The scaffold's `workflow-update-sdk-version.md` rule names all three packages it bumps; merge it from `dist/templates/package/`
214
+ - **The packages carry licences.** `@seriousgaming/sdk` and `@seriousgaming/deck` are Apache-2.0. `@seriousgaming/sdk-tools` is under the Serious Gaming SDK Tools Licence in its `LICENSE` file: use it to build, test and publish games for the Serious Gaming platform; files it generates or copies into your project are yours under Apache-2.0. All three were `UNLICENSED`
215
+ - **`@seriousgaming/sdk/commands` and `@seriousgaming/sdk/projection` follow semantic versioning**, apart from members tagged `@internal`, since `createTestSession` is typed through them. The React context objects `./ui` exports are outside the guarantee: provide them through the `render*` helpers in `./ui/testing` rather than by hand
216
+ - **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
183
217
  - **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
184
- - **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
185
218
 
186
219
  ### Removed
187
220
 
@@ -190,51 +223,64 @@ are in the [0.x changelog](changelog-0.x.md).
190
223
 
191
224
  ### Fixed
192
225
 
226
+ #### Logic
227
+
193
228
  - **A write to what the tick controller reads no longer restarts the countdown.** The dev server re-armed the timer every time the controller was re-run after a write, even when it gave the same answer, so a team writing all round pushed its own automatic tick back indefinitely, a facilitator's `extendTick` was undone, and a paused timer lost the time it had left. A re-run that returns the same answer now leaves the countdown alone; only a different answer starts a new window
194
- - **`sdk build` checks settings defaults against their schema.** A settings default that broke its own schema, such as a string on a number property or an object default missing a key its `required` lists, passed the build and reached logic as the value every session played with. Defaults in capabilities, endpoints and UIs were already checked; settings resources were missed. The build now refuses one, naming the settings resource and the path, and lists settings resources in its report
195
229
  - **Team ids are documented as opaque.** The `TeamRunMeta.teamId` and `PastStateQuery.teams` docs said a team id is always `team-${index + 1}`. It is an opaque, stable id: take it from `SessionData` or `setTeamList` and never build one from an index, since a runtime may assign other ids. A runtime never assigns `'own'` or `'all'`, so a `getPastState` query cannot mistake a team for either
196
- - **A setup UI or scenario editor that spreads an object-valued setting is no longer refused.** A `required` inside an object property was enforced on every override, so `updateSettings({ engine: { ...settings.engine, Execs: { ...settings.engine.Execs, AA: true } } })` was denied for the keys the change left out, and a scenario overriding one key of such an object failed `sdk build`. Overrides are now partial at every depth, as they already were at the top, and a value of the wrong type or an undeclared key at any depth is still refused. An item of an array an override supplies is still held to its `required`, since an array replaces the one beneath whole
197
- - **The scenario editor no longer changes the session running beside it.** The dev server stored the editor's edits in its session's settings, so editing a scenario reconfigured the session, opening the editor restarted the session on that scenario, and an endpoint the editor called read the setup step's edits as the draft. The editor now edits a draft of its scenario that belongs to no session: its `setSettings` and its endpoints read the draft, **Save** writes it into the scenario, and a session sees the values once it is started on that scenario
198
- - **A setup UI or scenario editor changes only the settings it lists in `configures`.** The dev server accepted an `updateSettings` naming any settings resource, the built-in `game` settings included, so a settings editor that did not configure `game` could still change the number of rounds. A payload naming a settings resource outside `configures` is now refused as `denied`, naming it, and none of it is applied. List `game` in `configures` to edit the game settings
199
- - **Saving a scenario keeps every field it does not edit.** The dev server's **Save** rebuilt the scenario's `scenario.sdk.json` from scratch, so saving over one dropped every locale but English and every description, renamed it to its identifier, and dropped `default` and every other field it did not write. It now replaces the settings alone, the number of rounds and team settings under `settings.game` among them. **Add scenario** from a copy now carries the source's locales, descriptions and other fields under the new scenario's name, and is never the default
200
- - **An engine or hook that changes a capability outside its `writes` fails, aggregate engines included.** The dev server checked only the capabilities a resource declared in `reads`, and only after a per-team `Init` or `Run` or a hook, so `InitAggregate` and `RunAggregate` could change a read-only capability under `shared` or in a `teams` entry, and any of them could write a capability it never declared. A changed capability that is not in `writes` now fails the call, naming it, and nothing of the result is applied. A capability returned unchanged, as the `{ ...context }` spread returns it, still passes. Add a capability to the resource's `writes` if it is meant to write it
201
- - **A per-team `Init` that changes a shared capability fails, as one from `Run` does.** The dev server checked only `Run`, so a team's `Init` could write a value every team reads. It now fails with _'modified shared capability "market" in Init. Shared capabilities may only be written in InitAggregate'_, and a team added to a shared-state game whose `Init` fails leaves the session as it was
202
230
  - **An aggregate engine in an independent game initialises each team on its own.** The dev server handed `InitAggregate` every team at once; it now calls it once per team with a one-element `teams`, as it already called `RunAggregate`
203
231
  - **`participantJoin` fires once per participant when play starts.** A game with a setup step ran the hook twice for each participant seated at Play, so a join counter or role assignment ran double. A reset still replays it once
204
- - **A session reset keeps the settings the setup step chose.** The dev server went back to the settings last saved by `sdk configure`, so a reset session ran on different values from the ones it started with. Going back to the setup step keeps them too, so the form opens on what was chosen
205
232
  - **A tick controller result with an unknown key, or a non-boolean `enabled` or `complete`, fails the evaluation.** The dev server ignored the extra key and treated `complete: 'no'` as true, ending the game. It now reports the failure, naming the key, and stops the timer, as for a controller that throws
233
+
234
+ #### Settings, setup and scenarios
235
+
236
+ - **A setup UI or scenario editor that spreads an object-valued setting is no longer refused.** A `required` inside an object property was enforced on every override, so `updateSettings({ engine: { ...settings.engine, Execs: { ...settings.engine.Execs, AA: true } } })` was denied for the keys the change left out, and a scenario overriding one key of such an object failed `sdk build`. Overrides are now partial at every depth, as they already were at the top, and a value of the wrong type or an undeclared key at any depth is still refused. An item of an array an override supplies is still held to its `required`, since an array replaces the one beneath whole
237
+ - **The scenario editor no longer changes the session running beside it.** The dev server stored the editor's edits in its session's settings, so editing a scenario reconfigured the session, opening the editor restarted the session on that scenario, and an endpoint the editor called read the setup step's edits as the draft. The editor now edits a draft of its scenario that belongs to no session: its `setSettings` and its endpoints read the draft, **Save** writes it into the scenario, and a session sees the values once it is started on that scenario
238
+ - **A setup UI or scenario editor changes only the settings it lists in `configures`.** The dev server accepted an `updateSettings` naming settings the editor did not list in `configures`. A payload naming a settings resource outside `configures` is now refused as `denied`, naming it, and none of it is applied. List `game` in `configures` to edit the game settings
239
+ - **Saving a scenario keeps every field it does not edit.** The dev server's **Save** rebuilt the scenario's `scenario.sdk.json` from scratch, so saving over one dropped every locale but English and every description, renamed it to its identifier, and dropped `default` and every other field it did not write. It now replaces the settings alone, the number of rounds and team settings under `settings.game` among them. **Add scenario** from a copy now carries the source's locales, descriptions and other fields under the new scenario's name, and is never the default. It keeps every settings resource, where it kept only those named `engine`, `ui` or `session`
240
+ - **A session reset keeps the settings the setup step chose.** The dev server went back to the settings last saved by `sdk configure`, so a reset session ran on different values from the ones it started with. Going back to the setup step keeps them too, so the form opens on what was chosen
241
+
242
+ #### Surfaces
243
+
206
244
  - **A surface that replaces its own document after connecting is torn down.** The dev server bounded only a frame's first load, so a UI that navigated itself to another page stayed on screen in the session's chrome. `HostChannel` in `@seriousgaming/sdk-tools/host` now bounds every load of a frame whose element offers a `load` event, and falls back to the platform view when no handshake follows
245
+ - **A waiting room that declares cross-team reads receives cross-team data**, so `useUserInterfaceCrossTeamData()` is no longer empty there
246
+ - **A session UI's `pauseTimer`, `resumeTimer` and `extendTick` honour their `teamId`**, and a message naming a team the session does not hold is refused rather than acting on another team
247
+ - **`getPastState` from a game UI honours `teams: 'all'` and a team id**, returning another team's rows narrowed to the UI's `crossTeamReads`. It always answered with the caller's own team
248
+ - **A participant moved to another team in the dev server sees their new team's board**, rather than keeping the old team's until the surface showed as disconnected
249
+ - **`renderUserInterface`'s `setData` resolves a `MutationCommit`** as the real one does, and its default `uploadBlob` and `readAsset` resolve empty values. CLI messages and the generated `engine/types.ts` header say 'engine' where they said 'module'
250
+
251
+ #### Endpoints and uploads
252
+
253
+ - **An uploaded file's name survives a space**, and uploads from a configuration UI (now setup and the scenario editor) are kept across a reset
254
+ - **The dev server now clears a game's uploads on a reset, as the platform does.** A session reset deletes `game`-retention blobs, including what `writeBlob` and `generateSpeech` stored. `sdk init`, the console's Re-initialise and Reconfigure, and selecting a scenario also delete setup and scenario-editor uploads. The automatic re-initialise after a package edit keeps those, and a per-team reset and the walkthrough clear nothing
255
+ - **A `blob:` reference whose id is not a stored blob's is refused as not found wherever it is resolved**
256
+ - **The dev server's `POST /api/blobs` takes an upload with no `Content-Type`**, and refuses an empty one with a 400 that says so
257
+
258
+ #### CLI and dev server
259
+
207
260
  - **`-j, --json` and `-w, --working-dir` work before the command**, so `sdk --json view` no longer fails with `USAGE_BAD_FLAG`
208
261
  - **A bad number to `--teams`, `--team` or `fault --times` is a usage error (exit 2)**, where `--teams abc` reached the session and failed with `SESSION_ERROR`, and `--team 2abc` was read as team 2
209
262
  - **`--scenario` naming a scenario the package does not hold fails with `RESOURCE_NOT_FOUND` (exit 2)**, listing the scenarios it has, on `init`, `tick` and `dev`
210
263
  - **`sdk update package` leaves `package.json` alone.** Every update set its `name` to the package identifier and its `description` to the game's name, and reformatted the file, so an npm name such as `@acme/game` was lost. `update package` now writes `seriousgaming.sdk.json` only; `package.json` owns its name, description and version. An update that changes nothing no longer rewrites `seriousgaming.sdk.json` either, so it keeps its formatting
211
264
  - **Logic stuck in a loop no longer wedges the command line.** A synchronous loop that never returns blocks the dev server, and its time limit with it. A command that finds the server taking connections but not answering now fails with `DEV_SERVER_UNRESPONSIVE` (exit 5) rather than hanging, and `sdk dev stop` kills a server that does not exit within five seconds and clears its lock. `sdk dev status` reports such a server with `responding: false`, and `sdk dev status` and `sdk dev stop` now honour `-w`
212
- - **A `title` on a setting, a variable or an endpoint field no longer becomes a type name in the generated `types.ts`.** A title of 'Context' broke the file with a duplicate identifier and one of 'Settings' renamed the settings type `Settings1`. Titles on values are now ignored by type generation and kept everywhere else; a title on an object still names its type. Run `pnpm run generate` to pick it up
213
- - **A built `seriousgaming.json` now passes the SDK's own manifest schema.** Each user interface's `ui` block recorded a `directory` the schema does not allow, so a platform checking uploads against the schema would refuse every package. The block now carries only `entrypoint`; rebuild to pick it up
214
265
  - **`sdk fault --reason` now reaches the outcome for every fault.** Only `llm-failure` used it; `conflict`, `denied`, `tick-failure` and `endpoint-timeout` now carry your `--reason` as the outcome's message, and `hook-throw` adds it to the reported failure. Without `--reason`, the message is unchanged
215
266
  - **`sdk fault llm-failure` now fails LLM calls.** It was accepted and reported armed but never fired. While armed, each call logic makes to `generateText`, `extractText` or `generateSpeech` fails as a platform failure would, carrying the `--reason` you gave, and uses up one of its `--times`
216
267
  - **A resource copied into a running package is picked up**, and an edit made just as `sdk dev` starts is no longer missed on macOS
217
- - **An uploaded file's name survives a space**, and uploads from setup and the scenario editor are kept across a reset
218
- - **The dev server now clears a game's uploads on a reset, as the platform does.** A session reset deletes `game`-retention blobs, including what `writeBlob` and `generateSpeech` stored. `sdk init`, the console's Re-initialise and Reconfigure, and selecting a scenario also delete setup and scenario-editor uploads. The automatic re-initialise after a package edit keeps those, and a per-team reset and the walkthrough clear nothing
219
- - **`pnpm test:e2e` in a scaffolded package no longer hangs after its last test.** The scaffold starts an isolated server with `startDevServer` in `testing/e2e/global-setup.ts`. To adopt it, copy `global-setup.ts.template`, replace `playwright.config.ts` and drop `{ port }` from your helper calls
220
- - **A shared package of yours can import the SDK's UI entry.** The scaffold's `vite.config.ts` and `vitest.config.ts` dedupe `@seriousgaming/sdk` and `@seriousgaming/deck`, so a second copy no longer leaves every hook reading empty data
221
- - **The scaffold's `.claude/settings.json` pre-approves only read and check commands**, never `dev`, watch-mode tests or `package publish`. Replace the file to adopt it
222
- - **`renderUserInterface`'s `setData` resolves a `MutationCommit`** as the real one does, and its default `uploadBlob` and `readAsset` resolve empty values. CLI messages and the generated `engine/types.ts` header say 'engine' where they said 'module'
223
268
  - **`sdk dev` no longer reports itself as already running after a restore** when a lock's pid had been reused
224
- - **Saving a scenario keeps every settings resource**, not only those named `engine`, `ui` or `session`
225
- - **A waiting room that declares cross-team reads receives cross-team data**, so `useUserInterfaceCrossTeamData()` is no longer empty there
226
- - **A session UI's `pauseTimer`, `resumeTimer` and `extendTick` honour their `teamId`**, and a message naming a team the session does not hold is refused rather than acting on another team
227
- - **Interactive `sdk update engine` works**, and `sdk new settings`, `sdk update settings` and `sdk new endpoint` ask for settings and properties rather than 'configuration fields'
228
- - **An endpoint's `extendTick` action may pull the deadline in** with a negative `byMs`, as a session UI's can
229
- - **A `blob:` reference whose id is not a stored blob's is refused as not found wherever it is resolved**
269
+ - **Interactive `sdk update engine` works**, and `sdk new endpoint` asks for settings rather than 'configuration fields'
230
270
  - **`sdk new` and `sdk delete` tell you to run `pnpm run generate` and `pnpm run build`, not npm**, and the dependency comment in the UI, waiting room, setup and scenario editor templates says `pnpm add`
231
- - **The dev server's `POST /api/blobs` takes an upload with no `Content-Type`**, and refuses an empty one with a 400 that says so
232
- - **A team-scoped endpoint called by the CLI or `createTestSession` receives its team**, and a call naming a team id and index that disagree, or no team in a session of several, is refused
233
- - **An endpoint called by `sdk endpoint call` no longer sees `caller.userInterfaceIdentifier: 'cli'`**; the field is absent. The dev server refuses a past-state read or endpoint call naming a surface the package does not declare
234
271
  - **Resetting the walkthrough through the command channel follows the session's current scenario, locale and settings**
235
272
  - **pnpm's `--` before a command's flags works in a game.** Given `pnpm run sdk tick` with a `--` ahead of `--no-server`, the CLI read every flag after it as a stray argument and failed with 'too many arguments'. It now drops a `--` that stands before the command's own flags, and the docs no longer show one
236
- - **`getPastState` from a game UI honours `teams: 'all'` and a team id**, returning another team's rows narrowed to the UI's `crossTeamReads`. It always answered with the caller's own team
237
- - **A participant moved to another team in the dev server sees their new team's board**, rather than keeping the old team's until the surface showed as disconnected
273
+
274
+ #### Build and generated files
275
+
276
+ - **A `title` on a setting, a variable or an endpoint field no longer becomes a type name in the generated `types.ts`.** A title of 'Context' broke the file with a duplicate identifier and one of 'Settings' renamed the settings type `Settings1`. Titles on values are now ignored by type generation and kept everywhere else; a title on an object still names its type. Run `pnpm run generate` to pick it up
277
+ - **A built `seriousgaming.json` now passes the SDK's own manifest schema.** Each user interface's `ui` block recorded a `directory` the schema does not allow, so a platform checking uploads against the schema would refuse every package. The block now carries only `entrypoint`; rebuild to pick it up
278
+
279
+ #### Scaffold
280
+
281
+ - **`pnpm test:e2e` in a scaffolded package no longer hangs after its last test.** The scaffold starts an isolated server with `startDevServer` in `testing/e2e/global-setup.ts`. To adopt it, copy `global-setup.ts.template`, replace `playwright.config.ts` and drop `{ port }` from your helper calls
282
+ - **A shared package of yours can import the SDK's UI entry.** The scaffold's `vite.config.ts` and `vitest.config.ts` dedupe `@seriousgaming/sdk` and `@seriousgaming/deck`, so a second copy no longer leaves every hook reading empty data
283
+ - **The scaffold's `.claude/settings.json` pre-approves only read and check commands**, never `dev`, watch-mode tests or `package publish`. Replace the file to adopt it
238
284
 
239
285
  ### Security
240
286
 
@@ -27,24 +27,25 @@ platform.
27
27
  Every surface has its own URL, and nothing redirects, so a URL can be typed,
28
28
  bookmarked or scripted without asking the server what the link is.
29
29
 
30
- | URL | What it shows |
31
- | ---------------------- | -------------------------------------------------------------------- |
32
- | `/` | The console: your game's session UI, with the dev drawer |
33
- | `/team/2/player/1` | The first participant of the second team |
34
- | `/team/2/observe` | That team's game UI with no participant identity |
35
- | `/team/2/waiting-room` | That team's waiting room UI |
36
- | `/team/2/join` | The link a facilitator hands out: it asks which participant you are |
37
- | `/setup` | The setup screen, for a game with a `setup` slot |
38
- | `/guide` | The facilitator guide |
39
- | `/print` | One printable sheet per team |
40
- | `/presentation` | The facilitator's deck (`?preview` shows it with no session) |
41
- | `/walkthrough` | The [walkthrough run](./cli-reference.md#walkthrough-runs)'s game UI |
30
+ | URL | What it shows |
31
+ | -------------------------------- | -------------------------------------------------------------------- |
32
+ | `/` | The console: your game's session UI, with the dev drawer |
33
+ | `/team/2/player/1` | The first participant of the second team |
34
+ | `/team/2/observe` | That team's game UI with no participant identity |
35
+ | `/team/2/waiting-room` | That team's waiting room UI |
36
+ | `/team/2/join` | The link a facilitator hands out: it asks which participant you are |
37
+ | `/setup` | The setup screen, for a game with a `setup` slot |
38
+ | `/scenario-editor?scenario=<id>` | The scenario editor, opened on that scenario |
39
+ | `/guide` | The facilitator guide |
40
+ | `/print` | One printable sheet per team |
41
+ | `/presentation` | The facilitator's deck (`?preview` shows it with no session) |
42
+ | `/walkthrough` | The [walkthrough run](./cli-reference.md#walkthrough-runs)'s game UI |
42
43
 
43
44
  `/team/<n>/join` is the one URL that resolves rather than names, because a link
44
45
  a facilitator hands out cannot know who will open it. A team holding one
45
- participant opens straight into their surface. The scenario editor has no URL of
46
- its own to type: it is always opened on one scenario, from the dev drawer's
47
- **Scenario** tab.
46
+ participant opens straight into their surface. The scenario editor is always
47
+ opened on one scenario, so its URL names it in `?scenario=`; the dev drawer's
48
+ **Scenario** tab links there.
48
49
 
49
50
  Add `?bare` to any URL to remove the dev chrome entirely. That is what a
50
51
  participant sees, what you screenshot, and what a browser test should drive, so
@@ -2118,6 +2118,16 @@ pnpm dlx @seriousgaming/sdk-tools new package
2118
2118
 
2119
2119
  Scaffolds the package structure and `seriousgaming.sdk.json`. It runs interactively by default, and also accepts a JSON definition as an argument, via `--file`, or on stdin. The `pnpm run sdk` script exists only once a package has been scaffolded, so this first command goes through `pnpm dlx`.
2120
2120
 
2121
+ The definition is three strings, at the top level rather than under `definition` as every other resource's is: the package `identifier`, the `name` the game takes in its first locale, and the `version` that `package.json` carries. All three are required.
2122
+
2123
+ ```bash
2124
+ pnpm dlx @seriousgaming/sdk-tools new package '{
2125
+ "identifier": "com.example.bakery",
2126
+ "name": "Bakery",
2127
+ "version": "0.1.0"
2128
+ }'
2129
+ ```
2130
+
2121
2131
  What it writes is a complete, playable game, not an empty shell: an engine, a game UI, a session UI, a waiting room UI, a validator, a `participantJoin` hook, a facilitator guide, five capabilities, four settings resources, two scenarios, and tests at every level. It is the game the SDK's own test suites play, copied out verbatim apart from the game's name. See [A tour of the starter game](./guides/starter-game.md) for what it is and why.
2122
2132
 
2123
2133
  `--empty` writes the package files and the agent guidance (`CLAUDE.md`, `.claude/`) alone: no game resources or tests.
@@ -4,7 +4,7 @@ The model behind the SDK on one page. Each resource kind has one guide that expl
4
4
 
5
5
  ## A package is a game
6
6
 
7
- A game is a package: a directory with a `seriousgaming.sdk.json` (the game's identifier, locales, ticks, teams and waiting room) and one directory per resource. The CLI finds resources by scanning the directories beside the manifest, so there is no list to keep in step.
7
+ A game is a package: a directory with a `seriousgaming.sdk.json` (the game's identifier, locales, `maxTicks`, teams and waiting room) and one directory per resource. The CLI finds resources by scanning the directories beside the manifest, so there is no list to keep in step.
8
8
 
9
9
  A game holds exactly one of some kinds, each in a fixed **slot** named for it, and any number of the others, each under a plural directory and named by its directory:
10
10
 
@@ -113,7 +113,7 @@ A read-only check on every mutation a UI submits, run before the mutation is app
113
113
 
114
114
  ### Endpoint
115
115
 
116
- A server-side handler, exported as `Handle`, that a UI calls by identifier with `callEndpoint`. It validates its request and response against schemas. An endpoint is **team**-scoped (the default: it acts on the calling team's context) or **session**-scoped (it acts on the session as a whole), and one that declares `writes` can change state. An endpoint is also how a UI reaches callbacks such as `generateText`, and one whose `visibility` is `external` can be called from outside the game, for example by a facilitator's AI agent or a platform API. See [Endpoints](../guides/endpoints.md).
116
+ A server-side handler, exported as `Handle` (or as `Plan` and `Respond`, for one that answers in two phases), that a UI calls by identifier with `callEndpoint`. It validates its request and response against schemas. An endpoint is **team**-scoped (the default: it acts on the calling team's context) or **session**-scoped (it acts on the session as a whole), and one that declares `writes` can change state. An endpoint is also how a UI reaches callbacks such as `generateText`, and one whose `visibility` is `external` can be called from outside the game, for example by a facilitator's AI agent or a platform API. See [Endpoints](../guides/endpoints.md).
117
117
 
118
118
  ### Context
119
119
 
@@ -254,7 +254,7 @@ The SDK component around each kind of UI (`UserInterfaceWrapper`, which the wait
254
254
 
255
255
  ### Settings resource
256
256
 
257
- A named, read-only set of parameters: a price, a difficulty, a round length, an answer key. Authored at `settings/<name>/settings.sdk.json` as a `settingsSchema` (JSON Schema) whose every property declares a default. A package may hold any number. A resource (the engine, a UI, the session UI, the waiting room UI, the tick controller, a hook, a validator, or an endpoint) lists the ones it reads in its `settings`, exactly as `reads` names capabilities, and receives exactly those, keyed by identifier: `settings.engine.BaseDemand`. No logic or surface writes one, and settings are not part of the context. See [Settings](../guides/settings.md).
257
+ A named, read-only set of parameters: a price, a difficulty, a round length, an answer key. Authored at `settings/<name>/settings.sdk.json` as a `settingsSchema` (JSON Schema) whose every property declares a default. A package may hold any number. A resource (the engine, a UI, the session UI, the waiting room UI, the presentation, the tick controller, a hook, a validator, or an endpoint) lists the ones it reads in its `settings`, exactly as `reads` names capabilities, and receives exactly those, keyed by identifier: `settings.engine.BaseDemand`. No logic or surface writes one, and settings are not part of the context. See [Settings](../guides/settings.md).
258
258
 
259
259
  **Not to be confused with** the global settings file, `~/.seriousgaming-sdk/config.json`, which holds your API keys (see [Global settings](../guides/global-settings.md)).
260
260
 
@@ -302,10 +302,10 @@ A file (an image, a PDF, a spreadsheet) uploaded during a session and stored by
302
302
 
303
303
  How long a blob lasts:
304
304
 
305
- | Scope | Survives a game reset? | Cleared when? |
306
- | ---------- | ---------------------- | ---------------------------------- |
307
- | `game` | No | On a game reset or a re-initialise |
308
- | `settings` | Yes | On a re-initialise |
305
+ | Scope | Survives a game reset? | Cleared when? |
306
+ | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
307
+ | `game` | No | On a game reset or a re-initialise |
308
+ | `settings` | Yes | On a manual re-initialise, a reconfigure or a scenario change, not the automatic re-initialise after a package edit |
309
309
 
310
310
  ## Development
311
311
 
@@ -55,10 +55,12 @@ A game's numbers live in settings rather than in code, so the first change needs
55
55
 
56
56
  ```json
57
57
  "Capacity": {
58
- "type": "number",
58
+ "title": "Daily capacity",
59
59
  "description": "How many items the stall can make in a day, across the whole menu",
60
+ "type": "integer",
60
61
  "default": 120,
61
- "minimum": 1
62
+ "minimum": 1,
63
+ "maximum": 1000
62
64
  }
63
65
  ```
64
66
 
@@ -436,7 +436,7 @@ Run Playwright tests in a separate job or stage, since they need a browser and t
436
436
  | `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
437
437
  | `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
438
438
 
439
- `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `ContextPatch`, `SetDataOptions`, `SetSharedDataOptions`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
439
+ `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
440
440
 
441
441
  To call one logic function directly instead, with no session, build its arguments with `logicArgs` from `@seriousgaming/sdk/testing` (see [Testing](./testing.md#testing-the-run-function)).
442
442