@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.
Files changed (58) hide show
  1. package/README.md +5 -5
  2. package/dist/cli.js +30 -12
  3. package/dist/client/index.d.ts +2 -2
  4. package/dist/client/test-session.d.ts +12 -15
  5. package/dist/client.js +20 -11
  6. package/dist/docs/api/index.md +1 -1
  7. package/dist/docs/api/sdk-tools-client.md +40 -32
  8. package/dist/docs/api/sdk-ui-testing.md +4 -4
  9. package/dist/docs/api/sdk-ui.md +80 -20
  10. package/dist/docs/api/sdk.md +37 -21
  11. package/dist/docs/changelog.md +119 -74
  12. package/dist/docs/cli-and-dev-server.md +16 -15
  13. package/dist/docs/concepts/index.md +1 -1
  14. package/dist/docs/concepts/terminology.md +6 -6
  15. package/dist/docs/getting-started.md +4 -2
  16. package/dist/docs/guides/engine-testing.md +1 -1
  17. package/dist/docs/guides/engine.md +13 -0
  18. package/dist/docs/guides/file-handling.md +4 -4
  19. package/dist/docs/guides/internationalization.md +15 -1
  20. package/dist/docs/guides/llm-integration.md +2 -0
  21. package/dist/docs/guides/patterns.md +33 -5
  22. package/dist/docs/guides/presentation.md +9 -9
  23. package/dist/docs/guides/session.md +22 -19
  24. package/dist/docs/guides/testing.md +1 -1
  25. package/dist/docs/guides/tick-controller.md +5 -3
  26. package/dist/docs/guides/ui.md +5 -1
  27. package/dist/docs/guides/upgrading.md +40 -5
  28. package/dist/docs/recipes/create-endpoint.md +1 -1
  29. package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
  30. package/dist/docs/recipes/use-request-tick.md +1 -1
  31. package/dist/docs/troubleshooting.md +6 -4
  32. package/dist/schema.json +6 -6
  33. package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
  34. package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
  35. package/dist/templates/engine/logic.test.ts.liquid +22 -34
  36. package/dist/templates/hook/logic.test.ts.liquid +28 -32
  37. package/dist/templates/package/CLAUDE.md.template +1 -1
  38. package/dist/templates/package/README.md.liquid +3 -3
  39. package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
  40. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
  41. package/dist/templates/presentation/src/App.tsx.liquid +1 -1
  42. package/dist/templates/session/src/main.tsx.liquid +3 -3
  43. package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
  44. package/dist/templates/starter-game/engine/logic.test.ts +37 -47
  45. package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
  46. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
  47. package/dist/templates/starter-game/session/src/main.tsx +3 -3
  48. package/dist/templates/starter-game/ui/src/main.tsx +3 -3
  49. package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
  50. package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
  51. package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
  52. package/dist/templates/ui/src/App.tsx.liquid +22 -11
  53. package/dist/templates/ui/src/i18n.ts.liquid +3 -0
  54. package/dist/templates/ui/src/main.tsx.liquid +3 -3
  55. package/dist/templates/validator/logic.test.ts.liquid +21 -30
  56. package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
  57. package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
  58. package/package.json +3 -3
@@ -300,10 +300,10 @@ See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
300
300
 
301
301
  Every blob is stored with a retention that controls its lifetime:
302
302
 
303
- | Retention | Lifetime | When to use |
304
- | ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
305
- | `"game"` | Cleared on a session reset or a re-initialise | Participant-uploaded content for a specific game session |
306
- | `"settings"` | Survives a session reset, cleared on a re-initialise | Documents set up before the game starts (e.g. a scenario brief uploaded from a setup screen or scenario editor) |
303
+ | Retention | Lifetime | When to use |
304
+ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
305
+ | `"game"` | Cleared on a session reset or a re-initialise | Participant-uploaded content for a specific game session |
306
+ | `"settings"` | Survives a session reset and the automatic re-initialise after a package edit; cleared on a manual re-initialise, a reconfigure or a scenario change | Documents set up before the game starts (e.g. a scenario brief uploaded from a setup screen or scenario editor) |
307
307
 
308
308
  Retention is a deletion-lifecycle bucket only: it is not an access or visibility control. It is set at upload time, and who sets it depends on the surface:
309
309
 
@@ -22,6 +22,18 @@ pnpm run sdk update package --patch '[
22
22
 
23
23
  The `supportedLocales` array defines which languages the game supports. The `locales` object holds the game's name in each of them, and the name in the first supported locale is the package's name.
24
24
 
25
+ ### Locale codes
26
+
27
+ A locale code is a short BCP 47 language tag: a language, then optionally a script, then optionally a region, separated by hyphens.
28
+
29
+ | Part | Form | Examples |
30
+ | -------- | ------------------------------------ | ----------------- |
31
+ | Language | Two or three lowercase letters | `en`, `zh`, `fil` |
32
+ | Script | Four letters, first capitalised | `Hant`, `Latn` |
33
+ | Region | Two capital letters, or three digits | `GB`, `TW`, `419` |
34
+
35
+ So `en`, `en-GB`, `es-419`, `zh-Hant`, `zh-Hant-TW` and `fil` are all valid. The case matters: `en-gb`, `zh-hant` and `en_GB` are refused when the package is built, as is anything with more parts (a variant or a private-use tag).
36
+
25
37
  Use `--patch` rather than a JSON definition here. A definition passed as an argument or with `--file` replaces the whole manifest, so anything it leaves out (`maxTicks`, `teams`, `waitingRoom` and the rest) is dropped. An RFC 6902 patch changes only the paths it names.
26
38
 
27
39
  ## User interface localisation
@@ -121,6 +133,8 @@ In the dev server, change the session language with the locale select in the con
121
133
 
122
134
  The choice holds for the rest of the session. No additional code is needed: just use `t()` in your components.
123
135
 
136
+ A scaffolded `main.tsx` hands i18next the whole locale code, which falls back through it on its own: `zh-Hant-TW` looks for `zh-Hant-TW` translations, then `zh-Hant`, then `zh`, then the fallback language. Translations keyed by language alone (`fr`) therefore still serve `fr-CA`, and a script you key separately (`zh-Hant` beside `zh-Hans`) is found too.
137
+
124
138
  ## Localising scenario content
125
139
 
126
140
  The i18next setup above localises UI chrome: the buttons, labels, and other text that ships inside the user interface. Scenario-authored content is different. This is the prose a scenario carries but a UI renders: inbox documents, narrative emails, briefings, and transcripts. It needs its own approach.
@@ -141,7 +155,7 @@ assets/
141
155
  it/documents.json
142
156
  ```
143
157
 
144
- Read it with `useAsset`, which tries the surface's locale first (then its language, so `fr-CA` finds `fr/`) and falls back to the file as given:
158
+ Read it with `useAsset`, which tries the surface's locale first, then the locale with its last part dropped, down to its language (so `fr-CA` finds `fr/`, and `zh-Hant-TW` tries `zh-Hant/` before `zh/`), and falls back to the file as given:
145
159
 
146
160
  ```typescript
147
161
  import { useAsset } from '@seriousgaming/sdk/ui';
@@ -153,6 +153,8 @@ interface LLMResponse {
153
153
 
154
154
  The blocks let one response carry text and one or more tool-use intents. The stop reason distinguishes normal completion (`'endTurn'`), tool use (`'toolUse'`), truncation (`'maxTokens'`), and refusal (`'refusal'`). When the provider reports token counts, `usage` carries the input and output token totals for the call.
155
155
 
156
+ Both sets are closed, so a `switch` over them can be exhaustive. A runtime never returns a stop reason your game was not built to know: one a later release adds reaches only a game that declares the feature that adds it in `requires`, and any other game is told `'endTurn'`. A new kind of content block reaches only a call that asks for it with an option on `generateText`, and is dropped from every other response.
157
+
156
158
  For the common case where you just want the assistant's text, use `getText`:
157
159
 
158
160
  ```typescript
@@ -279,17 +279,46 @@ pnpm run sdk new capability '{
279
279
  "variablesSchema": {
280
280
  "type": "object",
281
281
  "properties": {
282
- "ProductionCost": { "type": "number", "default": 5 },
283
282
  "TotalCosts": { "type": "number", "default": 0 }
284
283
  },
285
- "required": ["ProductionCost", "TotalCosts"],
284
+ "required": ["TotalCosts"],
286
285
  "additionalProperties": false
287
286
  }
288
287
  }
289
288
  }'
290
289
  ```
291
290
 
292
- The steps below read `BaseDemand`, `DemandVariance`, and `ProductionCost` from `settings/engine/`.
291
+ **Settings:**
292
+
293
+ The steps read their parameters from a settings resource rather than from context, because they are fixed when play starts and no step writes them:
294
+
295
+ ```bash
296
+ pnpm run sdk new settings '{
297
+ "definition": {
298
+ "identifier": "engine",
299
+ "settingsSchema": {
300
+ "type": "object",
301
+ "properties": {
302
+ "BaseDemand": { "type": "number", "default": 100 },
303
+ "DemandVariance": { "type": "number", "default": 20 },
304
+ "ProductionCost": { "type": "number", "default": 5 }
305
+ },
306
+ "additionalProperties": false
307
+ }
308
+ }
309
+ }'
310
+ ```
311
+
312
+ The engine lists it in `settings` beside the capabilities it writes:
313
+
314
+ ```bash
315
+ pnpm run sdk update engine --patch '[
316
+ { "op": "replace", "path": "/definition/writes", "value": ["demand", "production", "costs"] },
317
+ { "op": "add", "path": "/definition/settings", "value": ["engine"] }
318
+ ]'
319
+ ```
320
+
321
+ The steps below read `BaseDemand`, `DemandVariance`, and `ProductionCost` as `settings.engine.*`.
293
322
 
294
323
  **Demand step** (`engine/demand.ts`)**:**
295
324
 
@@ -316,7 +345,7 @@ export const runDemand: StepFunction<Context, Settings> = async ({ context, sett
316
345
  **Production step** (`engine/production.ts`)**:**
317
346
 
318
347
  ```typescript
319
- export const runProduction: StepFunction<Context, Settings> = async ({ context, settings }) => {
348
+ export const runProduction: StepFunction<Context, Settings> = async ({ context }) => {
320
349
  const { CurrentDemand } = context.demand;
321
350
  const { ProductionRate, TotalProduced } = context.production;
322
351
 
@@ -350,7 +379,6 @@ export const runCosts: StepFunction<Context, Settings> = async ({ context, setti
350
379
  ...context,
351
380
  costs: {
352
381
  ...context.costs,
353
- ProductionCost: settings.engine.ProductionCost,
354
382
  TotalCosts: TotalCosts + costThisTick,
355
383
  },
356
384
  };
@@ -57,15 +57,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
57
57
  >();
58
58
  ```
59
59
 
60
- | Field | What it holds |
61
- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
63
- | `session` | `null` with no session. Otherwise its `id`, `name`, `tick` (the highest any team has reached), `data` (the shared store and every team, narrowed to `reads`) and `teams` |
64
- | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
65
- | `theme` | The host's theme, to map onto the deck's colours |
66
- | `locale` | The locale to render in |
67
- | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
68
- | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
60
+ | Field | What it holds |
61
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
62
+ | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
63
+ | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`) and `teams` |
64
+ | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
65
+ | `theme` | The host's theme, to map onto the deck's colours |
66
+ | `locale` | The locale to render in |
67
+ | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
68
+ | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
69
69
 
70
70
  A presentation sees every team: it is the facilitator's view of the room.
71
71
 
@@ -908,25 +908,28 @@ const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
908
908
  useSessionUserInterfaceCallbacks();
909
909
  ```
910
910
 
911
- | Callback | Signature | Description |
912
- | ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
913
- | `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
914
- | `pauseTimer` | `(teamId?: string) => void` | Pause automatic ticking; omit `teamId` to pause all teams |
915
- | `resumeTimer` | `(teamId?: string) => void` | Resume automatic ticking; omit `teamId` to resume all teams |
916
- | `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
917
- | `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
918
- | `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
919
- | `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
920
- | `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
921
- | `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
922
- | `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
923
- | `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
924
- | `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
925
- | `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
926
- | `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
927
- | `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
928
- | `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
929
- | `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
911
+ | Callback | Signature | Description |
912
+ | -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
913
+ | `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
914
+ | `pauseTimer` | `(teamId?: string) => Promise<void>` | Pause automatic ticking; omit `teamId` to pause all teams |
915
+ | `resumeTimer` | `(teamId?: string) => Promise<void>` | Resume automatic ticking; omit `teamId` to resume all teams |
916
+ | `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
917
+ | `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
918
+ | `getPastState` | `(query) => Promise<PastStateEntry[]>` | Read committed past rounds; `teams` defaults to every team, or name one team by id |
919
+ | `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
920
+ | `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
921
+ | `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
922
+ | `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
923
+ | `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
924
+ | `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
925
+ | `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
926
+ | `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
927
+ | `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
928
+ | `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
929
+ | `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
930
+ | `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
931
+ | `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
932
+ | `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
930
933
 
931
934
  The promise-returning callbacks resolve and reject as described in [Controlling game flow](#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
932
935
 
@@ -268,7 +268,7 @@ Default values when you omit an option:
268
268
  | `settings` | `{}` |
269
269
  | `completedTicks` | `0` |
270
270
  | `setData` | no-op |
271
- | `theme` | `createMockTheme()` (light mode, MUI palette) |
271
+ | `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette) |
272
272
  | `locale` | `{ locale: 'en' }` |
273
273
  | `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
274
274
  | `participants` | `[]` (`createMockParticipants(n)` builds a roster) |
@@ -308,8 +308,10 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
308
308
  context,
309
309
  settings,
310
310
  }) => {
311
- const profit = context.financials?.Profit ?? 0;
312
- return { enabled: false, complete: profit >= settings.tick_controller.ProfitTarget };
311
+ return {
312
+ enabled: false,
313
+ complete: context.financials.Profit >= settings.tick_controller.ProfitTarget,
314
+ };
313
315
  };
314
316
  ```
315
317
 
@@ -359,7 +361,7 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
359
361
  }) => {
360
362
  // The game ends when every team hits the target
361
363
  const allDone = teams.every(
362
- (t) => (t.context.financials?.Profit ?? 0) >= settings.tick_controller.ProfitTarget
364
+ (t) => t.context.financials.Profit >= settings.tick_controller.ProfitTarget
363
365
  );
364
366
  return { enabled: false, complete: allDone };
365
367
  };
@@ -302,6 +302,8 @@ useEffect(() => {
302
302
  - `tick-failed`: the tick could not run (tick limit reached, game complete, or the executor threw)
303
303
  - `error`: anything else unexpected
304
304
 
305
+ The list is closed, so a `switch` over `outcome.kind` can be exhaustive. A kind a later release adds reaches only a game that declares the feature that adds it in `requires`; any other game is told `error`.
306
+
305
307
  Reach for `useMutationReporter` rather than branching by hand. It awaits the write, tracks whether one is in flight, and hands you the failure to render:
306
308
 
307
309
  ```tsx
@@ -444,6 +446,8 @@ function Decisions() {
444
446
 
445
447
  Most UIs need no changes: an observer sees the live game UI exactly as a participant does, and can still drive it. Any change an observer makes goes to the game's validators, as a participant's would, with `actor.role` set to `'observer'` so a validator can treat it differently (see [Validators](./validators.md)). Reach for `useUserInterfaceViewerRole()` only when you want to adapt: hide a participant-only control (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a deliberately read-only debrief view.
446
448
 
449
+ The two roles are the only ones your UI is ever told. A kind of viewer a later release adds reaches only a game that declares the feature that adds it in `requires`, and every other game is shown to that viewer as to an observer, so code that treats anything but `'participant'` as observing is always right.
450
+
447
451
  One read does need attention. To find out **which team** your UI is rendering, use `useUserInterfaceOwnTeam()`, not `useUserInterfaceParticipant()?.teamId`:
448
452
 
449
453
  ```typescript
@@ -927,7 +931,7 @@ function Briefing() {
927
931
  }
928
932
  ```
929
933
 
930
- It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md`:
934
+ It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md` (a locale with a script, such as `zh-Hant-TW`, tries `zh-Hant` before `zh`):
931
935
 
932
936
  ```
933
937
  shared-assets/
@@ -4,7 +4,7 @@ This guide takes a game package on 0.6 to 1.0, in 13 steps. Each step names what
4
4
 
5
5
  The steps are grouped by topic, not in the quickest order. Until the package loads, every CLI command reports what later steps have not fixed yet, so most games go fastest like this:
6
6
 
7
- 1. Make every edit that gets the package loading, in one pass: step 1, the bundle files and directories in step 2 (2a, 2b, 2c, 2e and 2g), step 3's moves, 7a and step 8
7
+ 1. Make every edit that gets the package loading, in one pass: step 1, the bundle files and directories in step 2 (2a, 2b, 2c, 2e and 2g), step 3's moves, 7a, 7e, step 8, and step 9's bullets on `uses`, demo mode and Node built-ins (`LOGIC_NODE_BUILTIN`). Each of these is a build refusal, and any one of them stops the package loading
8
8
  2. Run `pnpm run sdk generate`
9
9
  3. Let `pnpm run typecheck` drive the rest: 2d and steps 4, 5, 6 and 10. One or two runs list everything
10
10
  4. Search by hand for the changes no tool sees (below), then verify with step 13
@@ -27,6 +27,9 @@ Most steps are mechanical and the compiler finds what they break. **These change
27
27
  - A surface retrying a `conflict` on its own ([step 9](#step-9-meet-what-the-build-and-runtime-now-enforce))
28
28
  - A test calling an endpoint with `uiIdentifier: ''`, which is now refused ([step 10a](#10a-move-off-gamerunner))
29
29
  - Code that reads scenario files itself and still looks for `configuration` ([step 2c](#2c-rename-scenario-configuration-to-settings))
30
+ - A scenario's `teams.defaultNames` replacing the game's list whole, rather than falling back to the game's names past its end ([step 2g](#2g-rename-ticks-to-maxticks-and-move-a-scenarios-game-fields-into-settingsgame))
31
+ - `complete` now being `true` once a team has played its last round, not only when something ended the game early ([step 6d](#6d-completion-record-times-blob-retention-and-the-manifest-types))
32
+ - An endpoint checking `caller.userInterfaceIdentifier === 'cli'`, which never matches now that the field is absent for the CLI ([step 7b](#7b-handle-the-new-arguments))
30
33
 
31
34
  The [changelog](../changelog.md) carries the detail behind every step.
32
35
 
@@ -40,7 +43,7 @@ The three public packages move to the `@seriousgaming` scope on the public npm r
40
43
  | `@businesssimulations/seriousgaming-sdk` | `@seriousgaming/sdk` |
41
44
  | `@businesssimulations/seriousgaming-deck` | `@seriousgaming/deck` |
42
45
 
43
- 1. In `package.json`, rename the dependencies and set each to the 1.0 version. Keep the SDK, the tools and the deck at one version. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency at the same version
46
+ 1. In `package.json`, rename the dependencies and set each to the 1.0 version. Keep the SDK, the tools and the deck at one version. `@seriousgaming/sdk-tools` declares `@seriousgaming/sdk` as a peer dependency with a compatible `^` range on its own version (`^1.0.0` for 1.0.0)
44
47
  2. Replace the names everywhere else, in the order of the table so the SDK's name does not rewrite the start of the tools' name: every import (logic, surfaces, tests), `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`, `oxlintrc.json`, `testing/e2e/global-setup.ts` if you have one, `CLAUDE.md`, `.claude/rules/` and `README.md`. Then run your formatter: the new names sort differently, so every `package.json` and sorted import block changes
45
48
  3. Remove the `@businesssimulations:registry=https://npm.pkg.github.com` line, and the token beside it, from `.npmrc` and from CI, unless something else you install still comes from there
46
49
  4. In `pnpm-workspace.yaml`, delete the `sharp` and `protobufjs` overrides. They held back dependencies of `@xenova/transformers`, which left with `docs ask` (step 11), so nothing installs either package any more. Delete anything else you added for it too, such as `minimumReleaseAgeExclude` or `allowBuilds` entries for `@xenova/transformers` or `onnxruntime-node`
@@ -217,7 +220,8 @@ Three things behave differently once you have:
217
220
  - **A scenario's `teams.defaultNames` replaces the game's list whole.** It used to fall back to the game's name for a team past the end of the scenario's list. List every name the scenario needs
218
221
  - **A presentation reads `game.maxTicks`**, where it read `game.ticks`
219
222
  - **A settings resource called `game` is refused** (`SETTINGS_RESERVED`), since the name is the built-in one's. Rename yours, along with every `settings` and `configures` entry that names it
220
- - **A single-team game locks `teams.max`.** `teams.max: 1` alone no longer makes a game single-team, because a scenario or setup could raise it. An independent game whose engine writes a shared capability fails the build until it adds `"gameSettingsConstraints": { "teams": { "max": { "readOnly": true } } }` beside `teams.max: 1` (see [Narrow or lock the game settings](./settings.md#narrow-or-lock-the-game-settings))
223
+
224
+ **Lock `teams.max` in a single-team game.** `teams.max: 1` alone no longer makes a game single-team, because a scenario or setup could raise it. An independent game whose engine writes a shared capability fails the build until it adds `"gameSettingsConstraints": { "teams": { "max": { "readOnly": true } } }` beside `teams.max: 1` (see [Narrow or lock the game settings](./settings.md#narrow-or-lock-the-game-settings)).
221
225
 
222
226
  A setup UI or scenario editor can now set the number of rounds: list `game` in its `configures`, and write `updateSettings({ game: { ...settings.game, maxTicks: 6 } })`. A setup cannot set `waitingRoom.openOnStart`, which takes effect before setup runs. See [The game settings](./settings.md#the-game-settings).
223
227
 
@@ -430,7 +434,6 @@ One `TimerState` type replaces `SurfaceTimer`, `UserInterfaceTimer` and the proj
430
434
  | `scheduledTick(at, { isComplete })` | `scheduledTick(at, { complete })` |
431
435
  | `intervalTick(seconds)` | `intervalTick(intervalMs)` (**milliseconds**) |
432
436
  | `extendTick(seconds, teamId?)` on a session UI | `extendTick(byMs, teamId?)` (**milliseconds**) |
433
- | `MIN_EFFECTIVE_TICK_INTERVAL_SECONDS`, `MAX_…` | `MIN_EFFECTIVE_TICK_INTERVAL_MS`, `MAX_…` |
434
437
 
435
438
  The unit changes compile unchanged, so search for each by hand:
436
439
 
@@ -462,7 +465,13 @@ grep -rnE "intervalTick\(|extendTick\(|interval:|timerEnabled|isPaused" tick_con
462
465
  A `writeBlob` call still passing `'config'` is refused, naming the new value. A test fixture that builds past-state entries by hand needs the new names too:
463
466
 
464
467
  ```bash
465
- grep -rnE "isComplete|timestamp|retention: 'config'|SDKConfiguration|LogicConfiguration" engine endpoints hooks ui session testing
468
+ grep -rnE "isComplete|timestamp|retention: 'config'|SDKConfiguration|LogicConfiguration|needsConfiguration" engine endpoints hooks ui session testing
469
+ ```
470
+
471
+ **`complete` now counts the tick limit, and the compiler cannot see it.** On an endpoint's `session` and its team statuses, and in the state `sdk view` prints, a team is `complete` once it can tick no more: its engine or tick controller ended the game, or it has played `maxTicks`. The session is `complete` once every team is. Under 0.6 a game that ended by its limit read `complete: false` after its last round, so code that took `complete` to mean 'ended early', such as a 'target reached' banner, now shows it after every final round. Undoing that round clears it again. A `getPastState` entry's `complete` still reports only an engine or tick controller ending the game:
472
+
473
+ ```bash
474
+ grep -rnw "complete" endpoints session ui presentation testing
466
475
  ```
467
476
 
468
477
  ## Step 7: update endpoints
@@ -560,6 +569,29 @@ Two builders need more than their names suggest:
560
569
 
561
570
  ### 10d. Update UI component tests
562
571
 
572
+ Four names in `@seriousgaming/sdk/ui` and `@seriousgaming/sdk/ui/testing` are renamed to pair with their hook or theme type, with no alias for the old ones, so code using them fails to compile until it is renamed:
573
+
574
+ | Before | After |
575
+ | ------------------------------------- | ------------------------------------------ |
576
+ | `createMockTheme` | `createMockUserInterfaceTheme` |
577
+ | `createMockSessionTheme` | `createMockSessionUserInterfaceTheme` |
578
+ | `CrossTeamDataContext` | `UserInterfaceCrossTeamDataContext` |
579
+ | `UserInterfaceValidationContext` | `UserInterfaceValidationRejectionsContext` |
580
+ | `UserInterfaceValidationContextValue` | `UserInterfaceValidationRejectionsValue` |
581
+
582
+ The renames are name-only, so one command makes them across a package. Run it from the package root, in a clean working tree so you can review the result with `git diff`:
583
+
584
+ ```bash
585
+ git grep -lzE 'createMockTheme|createMockSessionTheme|CrossTeamDataContext|UserInterfaceValidationContext' -- '*.ts' '*.tsx' \
586
+ | xargs -0 perl -pi -e '
587
+ s/\bcreateMockTheme\b/createMockUserInterfaceTheme/g;
588
+ s/\bcreateMockSessionTheme\b/createMockSessionUserInterfaceTheme/g;
589
+ s/\bCrossTeamDataContext\b/UserInterfaceCrossTeamDataContext/g;
590
+ s/\bUserInterfaceValidationContextValue\b/UserInterfaceValidationRejectionsValue/g;
591
+ s/\bUserInterfaceValidationContext\b/UserInterfaceValidationRejectionsContext/g;
592
+ '
593
+ ```
594
+
563
595
  The helpers in `@seriousgaming/sdk/ui/testing` build each piece; see [Testing](./testing.md):
564
596
 
565
597
  - **`createMockTeamState` and `createMockSharedState`** build a team's and the shared store's state for a session UI test. Pass the generated types, `createMockTeamState<TeamContext>({ context })` and `createMockSharedState<SharedContext>({ context })`, and a shared capability left on a team fixture fails to compile. Render with `renderSessionUserInterface<SessionData>(...)` so the whole fixture is checked. Typing a fixture this way tends to turn up stale test data: fields the game renamed long ago, and tests that were passing while checking nothing. Treat each failure as a find, not a regression, and fix the test
@@ -594,6 +626,9 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
594
626
  - **The agent's pre-approved commands match its guidance.** Replace `.claude/settings.json`: it allows only read and check commands, never `dev`, `publish` or `pnpm add`
595
627
  - **Unit tests stop building a DOM they do not use.** Replace `vitest.config.ts`: it runs `*.test.ts` in plain Node and `*.test.tsx` in jsdom on the `vmThreads` pool. Rename any `.ts` test that renders, `renderHook` included, to `.tsx`
596
628
  - **Lint fails on a warning.** Set the `lint` script to `oxlint --max-warnings=0`
629
+ - **Lint refuses `any` and non-null assertions (`!`)** outside tests, `testing/` and each UI's `src/main.tsx`. Merge `oxlintrc.json.template` into `oxlintrc.json`, then fix or justify what it reports
630
+ - **Playwright's output stays out of git.** Merge `gitignore.template` into `.gitignore`: it ignores `test-results/` and `playwright-report/`
631
+ - **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
597
632
  - **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
598
633
  - **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
599
634
  - **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium`
@@ -56,7 +56,7 @@
56
56
  };
57
57
  ```
58
58
 
59
- The signature is `({ request, context, callbacks, caller, team, meta }) => Promise<Response>`, where `team` is the team a team-scoped call runs for. A session-scoped handler has no `team`. An endpoint that declares no `writes` cannot change state: return only what fits the declared `responseSchema`.
59
+ The handler takes `{ request, context, callbacks, caller, settings, meta, participants, session }` and returns `Promise<Response>`. A team-scoped handler also takes `team` (`{ teamId, index, name }`), the team the call runs for. A session-scoped handler has no `team`; it takes `teams`, every team's values, when it declares a capability that is not shared. An endpoint that declares no `writes` cannot change state: return only what fits the declared `responseSchema`.
60
60
 
61
61
  To change state, declare the capabilities you may write and return the change alongside the response. `scope`, `writes`, and `visibility` can go straight into the `definition` you pass to `new endpoint`, which then scaffolds a handler of the writing shape:
62
62
 
@@ -128,7 +128,7 @@ This writes `ui/`, the game UI each participant sees. Edit `ui/src/App.tsx` to s
128
128
  ### 6. Set how long the game runs
129
129
 
130
130
  ```bash
131
- pnpm run sdk update package --patch '[{"op":"add","path":"/ticks","value":5}]'
131
+ pnpm run sdk update package --patch '[{"op":"add","path":"/maxTicks","value":5}]'
132
132
  ```
133
133
 
134
134
  `seriousgaming.sdk.json` now ends the game after five ticks.
@@ -151,12 +151,11 @@ pnpm test:run
151
151
 
152
152
  ## Troubleshooting
153
153
 
154
- | Problem | Solution |
155
- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
156
- | `new engine` refuses because one already exists | The package was not made with `--empty`. Change the existing engine with `update engine` instead |
157
- | `context.bakery` is a type error | The engine does not declare `bakery` in `reads` or `writes`. Add it with `update engine`, which regenerates `types.ts` |
158
- | `logic.test.ts` fails to typecheck | Keep the `Callbacks` type argument on `Init` and `Run`: the generated test passes `Callbacks`, not the default callback set |
159
- | The tick changes nothing | Check `Run` returns the new capability object rather than the context it received |
154
+ | Problem | Solution |
155
+ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
156
+ | `new engine` refuses because one already exists | The package was not made with `--empty`. Change the existing engine with `update engine` instead |
157
+ | `context.bakery` is a type error | The engine does not declare `bakery` in `reads` or `writes`. Add it with `update engine`, which regenerates `types.ts` |
158
+ | The tick changes nothing | Check `Run` returns the new capability object rather than the context it received |
160
159
 
161
160
  ## Related
162
161
 
@@ -68,7 +68,7 @@ The hook must be called inside a component rendered within `UserInterfaceWrapper
68
68
 
69
69
  **UI shows a brief flicker after calling `setData` then `requestTick`**
70
70
 
71
- When you call `setData({ ... }); callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
71
+ When you call `await setData({ ... }); await callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
72
72
 
73
73
  ## Related
74
74
 
@@ -166,7 +166,7 @@ pnpm run sdk dev
166
166
  **Fix:**
167
167
 
168
168
  1. This is the expected end of the game. Use undo or reset to keep playing, or raise `maxTicks` in `seriousgaming.sdk.json` if the game should run longer
169
- 2. Your UI does not need to gate its advance control on `latestTick < maxTicks` for correctness, because the runtime enforces the limit. Disabling the control remains good UX
169
+ 2. Your UI does not need to gate its advance control on `completedTicks < maxTicks` for correctness, because the runtime enforces the limit. Disabling the control remains good UX
170
170
 
171
171
  ### A tick is refused with 'Team is already complete'
172
172
 
@@ -488,11 +488,11 @@ Demo mode has been removed, so `demo` is read by nothing. To show a game to a ro
488
488
 
489
489
  **Fix:** re-key the override by the settings resource that declares the property, or create one with that name. A value in `.seriousgaming-sdk/configuration.json` can be corrected in place, or the file deleted to start again from the defaults. See [Overriding settings](./guides/settings.md#overriding-settings).
490
490
 
491
- ### An aggregate engine fails the build with 'must export Init and Run'
491
+ ### An aggregate engine fails the build with 'does not export "Run"'
492
492
 
493
- **Symptom:** an engine you intended as aggregate fails `pnpm run sdk build` with errors saying it must export `Init` and `Run`.
493
+ **Symptom:** an engine you intended as aggregate fails `pnpm run sdk build` with `LOGIC_EXPORT_MISSING`: _'Engine "engine": Logic file ".../engine/logic.ts" does not export "Run". A per-team engine must export `Run`; `Init` is optional.'_
494
494
 
495
- **Cause:** its logic exports neither `InitAggregate` nor `RunAggregate`, so the build reads it as a per-team engine and applies the per-team export contract. Merging several files into one engine makes this easy to do: the aggregate functions end up in a file nothing re-exports.
495
+ **Cause:** its logic exports neither `InitAggregate` nor `RunAggregate`, so the build reads it as a per-team engine and applies the per-team export contract, which needs only `Run`. Merging several files into one engine makes this easy to do: the aggregate functions end up in a file nothing re-exports.
496
496
 
497
497
  **Fix:**
498
498
 
@@ -510,6 +510,8 @@ Demo mode has been removed, so `demo` is read by nothing. To show a game to a ro
510
510
 
511
511
  3. `sdk new engine --aggregate` scaffolds all three exports for a fresh engine
512
512
 
513
+ Exporting only one of the pair fails the same way, naming the other: _'does not export "RunAggregate". This engine is aggregate because its logic exports the other of "InitAggregate" / "RunAggregate"...'_. Export both.
514
+
513
515
  ### The build rejects a teamless surface calling a team-scoped endpoint
514
516
 
515
517
  **Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI, setup screen, or scenario editor.
package/dist/schema.json CHANGED
@@ -460,7 +460,7 @@
460
460
  "type": "object",
461
461
  "description": "Localized scenario fields with one entry per supported locale",
462
462
  "patternProperties": {
463
- "^[a-z]{2}(-[A-Z]{2})?$": {
463
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
464
464
  "type": "object",
465
465
  "description": "Localized fields for this locale",
466
466
  "properties": {
@@ -514,7 +514,7 @@
514
514
  "type": "object",
515
515
  "description": "Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.",
516
516
  "patternProperties": {
517
- "^[a-z]{2}(-[A-Z]{2})?$": {
517
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
518
518
  "type": "object",
519
519
  "description": "Localized fields for this locale",
520
520
  "properties": {
@@ -563,7 +563,7 @@
563
563
  "description": "List of locales supported by this game (e.g., ['en', 'es', 'fr'])",
564
564
  "items": {
565
565
  "type": "string",
566
- "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
566
+ "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
567
567
  },
568
568
  "minItems": 1,
569
569
  "uniqueItems": true
@@ -572,7 +572,7 @@
572
572
  "type": "object",
573
573
  "description": "Localized game fields with one entry per supported locale",
574
574
  "patternProperties": {
575
- "^[a-z]{2}(-[A-Z]{2})?$": {
575
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
576
576
  "type": "object",
577
577
  "description": "Localized fields for this locale",
578
578
  "properties": {
@@ -639,7 +639,7 @@
639
639
  "type": "object",
640
640
  "description": "Localised default name for one team, with one entry per supported locale",
641
641
  "patternProperties": {
642
- "^[a-z]{2}(-[A-Z]{2})?$": {
642
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
643
643
  "type": "object",
644
644
  "description": "Localised fields for this locale",
645
645
  "properties": {
@@ -768,7 +768,7 @@
768
768
  "type": "object",
769
769
  "description": "Localised default name for one team, with one entry per supported locale",
770
770
  "patternProperties": {
771
- "^[a-z]{2}(-[A-Z]{2})?$": {
771
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
772
772
  "type": "object",
773
773
  "description": "Localised fields for this locale",
774
774
  "properties": {