@seriousgaming/sdk-tools 1.0.0-alpha.3 → 1.0.0
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.
- package/README.md +5 -5
- package/dist/cli.js +30 -12
- package/dist/client/index.d.ts +2 -2
- package/dist/client/test-session.d.ts +12 -15
- package/dist/client.js +20 -11
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +40 -32
- package/dist/docs/api/sdk-ui-testing.md +4 -4
- package/dist/docs/api/sdk-ui.md +80 -20
- package/dist/docs/api/sdk.md +37 -21
- package/dist/docs/changelog.md +119 -74
- package/dist/docs/cli-and-dev-server.md +16 -15
- package/dist/docs/concepts/index.md +1 -1
- package/dist/docs/concepts/terminology.md +6 -6
- package/dist/docs/getting-started.md +4 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/engine.md +13 -0
- package/dist/docs/guides/file-handling.md +4 -4
- package/dist/docs/guides/internationalization.md +15 -1
- package/dist/docs/guides/llm-integration.md +2 -0
- package/dist/docs/guides/patterns.md +33 -5
- package/dist/docs/guides/presentation.md +9 -9
- package/dist/docs/guides/session.md +22 -19
- package/dist/docs/guides/testing.md +1 -1
- package/dist/docs/guides/tick-controller.md +5 -3
- package/dist/docs/guides/ui.md +5 -1
- package/dist/docs/guides/upgrading.md +40 -5
- package/dist/docs/recipes/create-endpoint.md +1 -1
- package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
- package/dist/docs/recipes/use-request-tick.md +1 -1
- package/dist/docs/troubleshooting.md +6 -4
- package/dist/schema.json +6 -6
- package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
- package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
- package/dist/templates/engine/logic.test.ts.liquid +22 -34
- package/dist/templates/hook/logic.test.ts.liquid +28 -32
- package/dist/templates/package/CLAUDE.md.template +1 -1
- package/dist/templates/package/README.md.liquid +3 -3
- package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
- package/dist/templates/presentation/src/App.tsx.liquid +1 -1
- package/dist/templates/session/src/main.tsx.liquid +3 -3
- package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
- package/dist/templates/starter-game/engine/logic.test.ts +37 -47
- package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
- package/dist/templates/starter-game/session/src/main.tsx +3 -3
- package/dist/templates/starter-game/ui/src/main.tsx +3 -3
- package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
- package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
- package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
- package/dist/templates/ui/src/App.tsx.liquid +22 -11
- package/dist/templates/ui/src/i18n.ts.liquid +3 -0
- package/dist/templates/ui/src/main.tsx.liquid +3 -3
- package/dist/templates/validator/logic.test.ts.liquid +21 -30
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
- package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
- package/package.json +3 -3
package/dist/docs/changelog.md
CHANGED
|
@@ -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).
|
|
@@ -24,11 +27,13 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
24
27
|
|
|
25
28
|
## [Unreleased]
|
|
26
29
|
|
|
30
|
+
## [1.0.0] — 2026-10-18
|
|
31
|
+
|
|
27
32
|
### Breaking Changes
|
|
28
33
|
|
|
29
34
|
#### Packages
|
|
30
35
|
|
|
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
|
|
36
|
+
- **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
37
|
- **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
38
|
|
|
34
39
|
#### Settings
|
|
@@ -36,8 +41,8 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
36
41
|
- **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
42
|
- **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
43
|
- **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)
|
|
44
|
+
- **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)
|
|
45
|
+
- **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
46
|
|
|
42
47
|
#### Logic
|
|
43
48
|
|
|
@@ -45,44 +50,49 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
45
50
|
- **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
51
|
- **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
52
|
- **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
|
|
53
|
+
- **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)
|
|
54
|
+
- **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
55
|
- **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
56
|
- **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
|
|
57
|
+
- **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)
|
|
58
|
+
- **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
59
|
- **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)
|
|
60
|
+
- **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
61
|
|
|
55
62
|
#### Endpoints
|
|
56
63
|
|
|
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)
|
|
64
|
+
- **`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
65
|
- **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
|
|
66
|
+
- **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
67
|
- **`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
68
|
- **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
|
|
69
|
+
- **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
70
|
|
|
64
71
|
#### Surfaces
|
|
65
72
|
|
|
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
|
|
73
|
+
- **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)
|
|
74
|
+
- **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)
|
|
75
|
+
- **`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)
|
|
76
|
+
- **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)
|
|
77
|
+
- **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)
|
|
78
|
+
- **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`. See [step 10d](guides/upgrading.md#10d-update-ui-component-tests)
|
|
70
79
|
|
|
71
80
|
#### CLI
|
|
72
81
|
|
|
73
82
|
- **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
|
|
83
|
+
- **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)
|
|
84
|
+
- **`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)
|
|
85
|
+
- **`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)
|
|
86
|
+
- **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)
|
|
87
|
+
- **`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)
|
|
88
|
+
- **`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
89
|
|
|
81
90
|
### Added
|
|
82
91
|
|
|
83
92
|
#### Logic and testing
|
|
84
93
|
|
|
85
94
|
- **`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)
|
|
95
|
+
- **An endpoint that lists settings gets a generated `defaultSettings`** in its `defaults.ts`, ready to pass to `logicArgs.endpoint`
|
|
86
96
|
- **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
97
|
- **`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
98
|
- **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 +114,13 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
104
114
|
- **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
115
|
- **`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
116
|
- **`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
|
|
117
|
+
- **`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
118
|
|
|
109
119
|
#### Endpoints
|
|
110
120
|
|
|
111
121
|
- **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
|
|
122
|
+
- **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
|
|
123
|
+
- **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
124
|
- **A session-scoped endpoint can write individual teams**, returning `teams: { 'team-1': { ... } }`: every team's patch lands, or none does
|
|
115
125
|
- **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
126
|
- **`EndpointError`** and the `EffectStep`, `EndpointFailure`, `EndpointFailureOutcome` and `EndpointCallResult` types
|
|
@@ -120,9 +130,10 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
120
130
|
#### User interfaces
|
|
121
131
|
|
|
122
132
|
- **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)
|
|
133
|
+
- **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
134
|
- **`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
135
|
- **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
|
|
136
|
+
- **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
137
|
- **`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
138
|
- **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
|
|
128
139
|
- **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,52 +150,73 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
139
150
|
- **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
151
|
- **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
152
|
- **`SERIOUSGAMING_DEV_STATE_DIR`** keeps the dev server's lock file outside the package
|
|
142
|
-
- **
|
|
153
|
+
- **`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
154
|
- **The SDK has a README** saying which subpaths carry semver guarantees (the root, `./ui` and `./ui/testing`)
|
|
144
155
|
- **`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
156
|
|
|
157
|
+
#### For runtimes
|
|
158
|
+
|
|
159
|
+
- **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
|
|
160
|
+
- **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
|
|
161
|
+
|
|
146
162
|
### Changed
|
|
147
163
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
- **The
|
|
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)
|
|
164
|
+
#### Logic and testing
|
|
165
|
+
|
|
166
|
+
- **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
167
|
- **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
168
|
- **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
|
-
- **
|
|
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`
|
|
169
|
+
- **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
170
|
- **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)
|
|
171
|
+
- **`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
|
|
172
|
+
|
|
173
|
+
#### Settings and scenarios
|
|
174
|
+
|
|
175
|
+
- **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
176
|
- **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
|
|
177
|
+
|
|
178
|
+
#### User interfaces
|
|
179
|
+
|
|
180
|
+
- **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
|
|
181
|
+
- **Surfaces never retry a `conflict` themselves**; a runtime with optimistic concurrency retries a losing write before reporting it
|
|
182
|
+
- **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
|
|
183
|
+
- **The UI library no longer logs every host ping to the browser console**
|
|
184
|
+
|
|
185
|
+
#### CLI and dev server
|
|
186
|
+
|
|
187
|
+
- **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)
|
|
188
|
+
- **`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
189
|
- **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
190
|
- **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
191
|
- **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
192
|
- **A schema error the SDK cannot explain points at the upgrading guide**, and a refused shared write from a session UI says why
|
|
166
193
|
- **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
194
|
- **`sdk init` reports the scenario it started on** as `scenario` in its output, `null` when there is none
|
|
171
195
|
- **`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
|
|
196
|
+
- **A manifest failure names `seriousgaming.sdk.json`, not its absolute path**
|
|
197
|
+
|
|
198
|
+
#### Scaffold
|
|
199
|
+
|
|
200
|
+
- **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
|
|
201
|
+
- **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
202
|
- **The scaffold's `pnpm run lint` fails on a warning** (`oxlint --max-warnings=0`)
|
|
174
203
|
- **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
204
|
- **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,
|
|
205
|
+
- **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
206
|
- **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
|
-
- **
|
|
179
|
-
- **
|
|
180
|
-
- **
|
|
207
|
+
- **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
|
|
208
|
+
- **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`
|
|
209
|
+
- **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
|
|
181
210
|
- **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)
|
|
182
|
-
- **The conformance suite's self-navigation checks run under a production content security policy.** The probe frame navigated itself to a `data:` URL, which a host page's `frame-src` refuses, so both checks failed against a host with a real policy. It now navigates to a path on the host page's own origin that the suite answers in the browser. The runtime specification now says a host's `frame-src` on the page embedding a game confines a bundle's self-navigation, and that a host should send one listing every origin it serves bundles from
|
|
183
|
-
- **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
|
|
184
211
|
|
|
185
|
-
|
|
212
|
+
#### Packages and docs
|
|
213
|
+
|
|
214
|
+
- **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
|
|
215
|
+
- **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/`
|
|
216
|
+
- **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`
|
|
217
|
+
- **`@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
|
|
218
|
+
- **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
|
|
186
219
|
- **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
|
|
187
|
-
- **The conformance suite reaches every endpoint check through a surface.** Ten 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. The two that check an endpoint's `readAsset` and `generateText` call internal endpoints from a session UI added to the `logic-callbacks` fixture. 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
|
|
188
220
|
|
|
189
221
|
### Removed
|
|
190
222
|
|
|
@@ -193,52 +225,65 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
193
225
|
|
|
194
226
|
### Fixed
|
|
195
227
|
|
|
228
|
+
#### Logic
|
|
229
|
+
|
|
196
230
|
- **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
|
|
197
|
-
- **`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
|
|
198
231
|
- **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
|
|
199
|
-
- **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
|
|
200
|
-
- **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
|
|
201
|
-
- **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
|
|
202
|
-
- **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
|
|
203
|
-
- **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
|
|
204
|
-
- **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
|
|
205
232
|
- **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`
|
|
206
233
|
- **`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
|
|
207
|
-
- **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
|
|
208
234
|
- **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
|
|
235
|
+
|
|
236
|
+
#### Settings, setup and scenarios
|
|
237
|
+
|
|
238
|
+
- **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
|
|
239
|
+
- **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
|
|
240
|
+
- **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
|
|
241
|
+
- **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`
|
|
242
|
+
- **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
|
|
243
|
+
|
|
244
|
+
#### Surfaces
|
|
245
|
+
|
|
209
246
|
- **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
|
|
247
|
+
- **A waiting room that declares cross-team reads receives cross-team data**, so `useUserInterfaceCrossTeamData()` is no longer empty there
|
|
248
|
+
- **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
|
|
249
|
+
- **`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
|
|
250
|
+
- **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
|
|
251
|
+
- **`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'
|
|
252
|
+
|
|
253
|
+
#### Endpoints and uploads
|
|
254
|
+
|
|
255
|
+
- **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
|
|
256
|
+
- **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
|
|
257
|
+
- **A `blob:` reference whose id is not a stored blob's is refused as not found wherever it is resolved**
|
|
258
|
+
- **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
|
|
259
|
+
|
|
260
|
+
#### CLI and dev server
|
|
261
|
+
|
|
210
262
|
- **`-j, --json` and `-w, --working-dir` work before the command**, so `sdk --json view` no longer fails with `USAGE_BAD_FLAG`
|
|
211
263
|
- **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
|
|
212
264
|
- **`--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`
|
|
213
265
|
- **`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
|
|
214
266
|
- **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`
|
|
215
|
-
- **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
|
|
216
|
-
- **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
|
|
217
267
|
- **`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
|
|
218
268
|
- **`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`
|
|
219
269
|
- **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
|
|
220
|
-
- **An uploaded file's name survives a space**, and uploads from setup and the scenario editor are kept across a reset
|
|
221
|
-
- **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
|
|
222
|
-
- **`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
|
|
223
|
-
- **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
|
|
224
|
-
- **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
|
|
225
|
-
- **`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'
|
|
226
270
|
- **`sdk dev` no longer reports itself as already running after a restore** when a lock's pid had been reused
|
|
227
|
-
- **
|
|
228
|
-
- **A waiting room that declares cross-team reads receives cross-team data**, so `useUserInterfaceCrossTeamData()` is no longer empty there
|
|
229
|
-
- **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
|
|
230
|
-
- **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'
|
|
231
|
-
- **An endpoint's `extendTick` action may pull the deadline in** with a negative `byMs`, as a session UI's can
|
|
232
|
-
- **A `blob:` reference whose id is not a stored blob's is refused as not found wherever it is resolved**
|
|
271
|
+
- **Interactive `sdk update engine` works**, and `sdk new endpoint` asks for settings rather than 'configuration fields'
|
|
233
272
|
- **`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`
|
|
234
|
-
- **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
|
|
235
|
-
- **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
|
|
236
|
-
- **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
|
|
237
273
|
- **Resetting the walkthrough through the command channel follows the session's current scenario, locale and settings**
|
|
238
274
|
- **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
|
|
239
|
-
|
|
240
|
-
|
|
275
|
+
|
|
276
|
+
#### Build and generated files
|
|
277
|
+
|
|
278
|
+
- **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
|
|
279
|
+
- **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
|
|
280
|
+
|
|
281
|
+
#### Scaffold
|
|
282
|
+
|
|
283
|
+
- **`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
|
|
284
|
+
- **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
|
|
285
|
+
- **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
|
|
241
286
|
|
|
242
287
|
### Security
|
|
243
288
|
|
|
244
|
-
-
|
|
289
|
+
- **Six advisories are cleared**, one of them critical (`proxy-addr`), with `source-map-js`, `fast-uri` and `sharp`. `image-size`, reached through `@seriousgaming/deck`'s PowerPoint export, is held to `>=2.0.3` by a new override (GHSA-5p2g-fcmc-qvqq, GHSA-w3rx-r6r6-pgpr). A scaffolded package carries the same override in its `pnpm-workspace.yaml`: copy that block into an existing package's file, then run `pnpm update -r` and `pnpm audit`
|
|
@@ -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
|
|
31
|
-
|
|
|
32
|
-
| `/`
|
|
33
|
-
| `/team/2/player/1`
|
|
34
|
-
| `/team/2/observe`
|
|
35
|
-
| `/team/2/waiting-room`
|
|
36
|
-
| `/team/2/join`
|
|
37
|
-
| `/setup`
|
|
38
|
-
| `/
|
|
39
|
-
| `/
|
|
40
|
-
| `/
|
|
41
|
-
| `/
|
|
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
|
|
46
|
-
|
|
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
|
|
@@ -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,
|
|
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
|
-
"
|
|
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`, `
|
|
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
|
|
|
@@ -156,6 +156,19 @@ Never assign to `context`: build a new object with spreads and return it. See [I
|
|
|
156
156
|
|
|
157
157
|
`Init` and `Run` return what they write, named by kind: capabilities go under `capabilities`, as a patch merged into the team's context, and paths to remove go under `deletes` (see [Removing a key](#removing-a-key)). Hooks and aggregate engines follow the same rule, and a writing endpoint returns `{ response, capabilities, deletes? }`. The runtime refuses a top-level key it does not recognise, so a result that returns capabilities flat (`{ inventory: { ... } }`) fails the call rather than losing its writes.
|
|
158
158
|
|
|
159
|
+
### Ending the game
|
|
160
|
+
|
|
161
|
+
`Run` may also return `complete: true` to end the game for the team it ran for, with no tick controller needed. In an independent game each team finishes on its own; in a shared-state game one team's completion ends it for every team, because they share one clock. `complete: false`, or leaving it out, carries on: completion cannot be withdrawn this way, and an undo of the completing tick clears it.
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
return {
|
|
165
|
+
capabilities: next,
|
|
166
|
+
complete: next.financials.Profit >= settings.engine.ProfitTarget,
|
|
167
|
+
};
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
An aggregate engine's `RunAggregate` reports it per level: `complete` under `shared` ends the game for every team, and `complete` on a `teams` entry ends it for that team alone. `Init` and `InitAggregate` cannot end the game. See [Game completion](./tick-controller.md#game-completion) for how this sits beside `maxTicks` and a tick controller's own `complete`.
|
|
171
|
+
|
|
159
172
|
### How a result folds into the context
|
|
160
173
|
|
|
161
174
|
What you return under `capabilities` is folded into the team's context one level deep:
|