@seriousgaming/sdk-tools 1.0.0-alpha.4 → 1.1.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 (165) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20003 -5523
  17. package/dist/client.js +15534 -1134
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +64 -6
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +64 -3
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +2 -9
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +29 -35
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +194 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +28 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +2 -2
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -1,22 +1,15 @@
1
1
  # Building waiting room UIs
2
2
 
3
- Own the holding screen participants see while a session is parked, instead of accepting the host's stock panel.
3
+ The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
4
4
 
5
5
  **Keywords:** waiting room, holding screen, lobby, waiting to begin, session paused, park a session, break, waitingRoom, setWaitingRoom
6
6
 
7
- ## What you'll learn
8
-
9
- - What the waiting room is and who controls it
10
- - Why a waiting room UI is a game UI rather than a new kind of surface
11
- - How to tell 'not started yet' from 'parked mid-play'
12
- - How to start every session with the room already open
13
- - How to stop the tick clock while participants wait
14
- - How to let your own session UI open and close the room
15
-
16
7
  ## What is the waiting room?
17
8
 
18
9
  The waiting room is a single per-session flag. While it is open, every participant in the session sees a holding screen instead of the game UIs; while it is closed, they see the game. The facilitator toggles it, and the change reaches every team at once.
19
10
 
11
+ Holding participants here gives a facilitator space for a discussion or a briefing, between rounds or before play starts.
12
+
20
13
  ```
21
14
  Waiting room closed Waiting room open
22
15
  +---------------------+ +---------------------+
@@ -1,19 +1,46 @@
1
1
  # Serious Gaming SDK documentation
2
2
 
3
- The Serious Gaming SDK is for building business simulations: live, in-person learning interventions that a facilitator runs for a room of teams. You write a game as a package of TypeScript logic and React UIs, run it locally in the dev server, and publish it to the Serious Gaming platform.
3
+ The Serious Gaming SDK is for building serious games: facilitated learning experiences, such as business simulations and experiential learning, in which teams make decisions and see the consequences.
4
+
5
+ You write the rules and the screens in TypeScript and React, play the game on your own machine in the dev server, and publish it to the Serious Gaming platform, which runs it for real groups. Participants play on their own devices, in one room, remote, or hybrid, while a facilitator steers the session and leads the debrief.
6
+
7
+ ## What the SDK does for you
8
+
9
+ A serious game is more than a web app with a score. Everything a live session needs beyond your game's own rules and screens is already built, in the dev server on your machine and on the platform in production:
10
+
11
+ - **Teams and joining**: participants join a session on their own devices, are placed in teams, and can rejoin after losing their connection
12
+ - **Live state**: every device on a team sees the same state, kept in step as teammates make decisions
13
+ - **Rounds**: your engine plays one round at a time, by hand or on a timer, with undo and a snapshot of every round to look back on
14
+ - **The facilitator's controls**: a session screen for the whole room, a waiting room to hold participants in, and a setup form for each session
15
+ - **Variants**: scenarios and settings, so one game serves different audiences without code changes
16
+ - **The debrief**: a slide deck built from the session's own results, and a facilitator guide in markdown
17
+ - **AI**: generated text and speech from your logic, and endpoints a facilitator's AI agent can call
18
+ - **Testing**: unit tests, whole games played in-process, and browser tests, with the starter game as a worked example
4
19
 
5
20
  ## How a session runs
6
21
 
7
- 1. A facilitator starts a live session of your game and runs it from the session UI
8
- 2. Participants join on their own devices, in teams, and each sees your game UI
9
- 3. Teams make decisions: each change is a write to their team's state, checked by any validators you wrote
10
- 4. Each tick runs your engine on every team's state, and the game UIs show the result
11
- 5. After the last tick the game is complete, and the facilitator leads the debrief
22
+ 1. A facilitator creates a session of your game, choosing a scenario and filling in its setup form if it has one
23
+ 2. Participants join on their own devices, in teams, and each sees your game's screen
24
+ 3. In each round, teams make decisions, which your game can check and refuse
25
+ 4. The facilitator, or a timer, ends the round: your engine works out what the decisions caused, and every screen shows the result
26
+ 5. After the last round the game is complete, and the facilitator leads the debrief
27
+
28
+ [Core concepts](./concepts/index.md) tells the same story in terms of the code you write.
29
+
30
+ ## What you need
31
+
32
+ To build and play a game locally, you need Node.js 24 or later and pnpm 12, and nothing else: the packages are on the public npm registry, and no account is needed.
33
+
34
+ To publish a game, you need an account on the Serious Gaming platform with publishing access, which Business Simulations grants: see [Publish a package](./recipes/publish-a-package.md). Generated text needs a platform API key, the same one publishing uses (see [LLM integration](./guides/llm-integration.md)), and generated speech in the dev server needs an ElevenLabs API key (see [Speech generation](./guides/speech-generation.md)).
35
+
36
+ The SDK and the deck library are Apache-2.0. The CLI and the dev server are under the Serious Gaming SDK Tools Licence, in their package's `LICENSE` file: you may use them to build games for the platform, you own the games you build, and what the tools generate or copy into your project is yours under Apache-2.0.
12
37
 
13
38
  ## Start here
14
39
 
15
- - **[Getting started](./getting-started.md)**: scaffold the starter game, play it, and change it
40
+ - **[Getting started](./getting-started.md)**: scaffold the starter game, play it, and change it, in about 15 minutes
41
+ - **[Designing a serious game](./guides/designing-a-game.md)**: from a learning outcome to the decisions, rounds, feedback, and debrief that teach it
16
42
  - **[A tour of the starter game](./guides/starter-game.md)**: every file in the game you are given, and what it does
43
+ - **[For AI agents](./ai-agents.md)**: the commands to scaffold, check, and play a game without a browser or a prompt
17
44
  - **[Terminology](./concepts/terminology.md)**: the words these docs use, each with one meaning
18
45
 
19
46
  ## The documentation
@@ -31,11 +58,14 @@ The Serious Gaming SDK is for building business simulations: live, in-person lea
31
58
  - **[CLI error codes](./cli-error-codes.md)**: every code a failed command reports, and its exit code
32
59
  - **[Environment variables](./environment-variables.md)**: every variable the dev server and CLI read
33
60
 
34
- ## When something changes or goes wrong
61
+ ## When something goes wrong
35
62
 
36
- - **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
63
+ - **[Troubleshooting](./troubleshooting.md)**: symptoms, causes, and fixes
37
64
  - **[Changelog](./changelog.md)**: what changed in each release from 1.0, and what to do about it
65
+
66
+ ## Upgrading from an earlier release
67
+
68
+ - **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
38
69
  - **[Changelog for 0.x](./changelog-0.x.md)**: every release before 1.0
39
- - **[Troubleshooting](./troubleshooting.md)**: symptoms, causes, and fixes
40
70
 
41
71
  The docs at sdk.seriousgaming.com describe the newest release. The docs for the version you have installed ship inside it: `pnpm run sdk docs view` lists them and prints any page, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.
@@ -53,7 +53,7 @@ An observer is a facilitator watching one team's live game UI without joining as
53
53
  }
54
54
  ```
55
55
 
56
- 5. Open the observer view at `/team/<n>/observe`. It renders the same game UI with no participant identity and no presence.
56
+ 5. Open the observer view at `/team/<n>/observe`. It renders the same game UI with no participant identity and no presence
57
57
 
58
58
  ## Verify
59
59
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  **Keywords:** call endpoint, invoke endpoint, callbacks.endpoints, UI endpoint, request response, EndpointError, endpoint failure
4
4
 
5
+ Call a server-side endpoint from any of your game's screens and handle its response or its failure.
6
+
5
7
  ## Prerequisites
6
8
 
7
9
  - An [endpoint](create-endpoint.md) already scaffolded in the same package (or installed via another package)
@@ -31,7 +31,7 @@ Define a named slice of the game's state that the engine and screens read and wr
31
31
 
32
32
  This writes `capabilities/pricing/capability.sdk.json`. For nested objects, arrays, and keyed collections, see [Variable types](../guides/capabilities.md#variable-types).
33
33
 
34
- 2. Optional: give it a `scope` other than the default `team`, by adding `"scope"` to the `definition` above: `shared` for one value across all teams, `team-readable` for a per-team value other teams may watch, or `private` for engine bookkeeping no screen receives. See [Scope](../guides/capabilities.md#scope).
34
+ 2. Optional: give it a `scope` other than the default `team`, by adding `"scope"` to the `definition` above: `shared` for one value across all teams, `team-readable` for a per-team value other teams may watch, or `private` for engine bookkeeping no screen receives. See [Scope](../guides/capabilities.md#scope)
35
35
 
36
36
  3. Declare it on each resource that uses it, in `reads` or `writes`. For the engine:
37
37
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  **Keywords:** create endpoint, new endpoint, server handler, callable handler, scaffold endpoint
4
4
 
5
+ Add a server-side handler your screens, or callers outside the game, can invoke by name with a validated request and response.
6
+
5
7
  ## Prerequisites
6
8
 
7
9
  - A package with a valid `seriousgaming.sdk.json`
@@ -79,7 +81,9 @@
79
81
  { "scope": "session" }
80
82
  ```
81
83
 
82
- `scope` defaults to `'team'`, which gives the handler that team's board and a `team` naming it: `team.teamId`, `team.index` and `team.name`. Use `team`, not `caller`, to find the team's own row in anything keyed by team: `caller` says who is calling, and a facilitator's agent or the CLI calls on a team's behalf without being on it, so its `caller.teamId` is absent. `caller.teamId` is set only for a participant or an observer, and names their own team. A session UI, a setup screen, or a scenario editor has no team of its own, so calling a team-scoped endpoint from one fails the build.
84
+ `scope` defaults to `'team'`, which gives the handler that team's board and a `team` naming it: `team.teamId`, `team.index` and `team.name`. Use `team`, not `caller`, to find the team's own row in anything keyed by team: `caller` says who is calling, and a facilitator's agent or the CLI calls on a team's behalf without being on it, so its `caller.teamId` is absent. `caller.teamId` is set only for a participant or an observer, and names their own team. A session UI or a setup screen has no team of its own, so calling a team-scoped endpoint from one fails the build.
85
+
86
+ An endpoint for the scenario editor, or for an agent writing a scenario, is `{ "scope": "scenario" }`: it runs on a scenario draft, with the draft's settings and no game state (see [Scenario-scoped endpoints](../guides/endpoints.md#scenario-scoped-endpoints)).
83
87
 
84
88
  4. Declare the endpoint on every UI that should be allowed to call it:
85
89
 
@@ -115,7 +119,8 @@
115
119
  - _'Endpoint "X" rejected the request: \<path\> must have required property ...'_: the iframe sent a payload that does not match `requestSchema`. Check that the UI's call matches the declared request shape
116
120
  - _'"ui" does not list endpoint "X" in its endpoints'_: add the endpoint identifier to the UI's `endpoints` array
117
121
  - _'Resource "X" attempted to call callback "Y" but did not declare it in its bundle's "uses" array'_: add the `ApiUse` value to the endpoint bundle's `uses` array
118
- - _'which is team-scoped, but this surface has no team of its own'_: a session UI, setup screen, or scenario editor is calling it; set `"scope": "session"` on the endpoint
122
+ - _'which is team-scoped, but this surface has no team of its own'_: a session UI or setup screen is calling it; set `"scope": "session"` on the endpoint
123
+ - `EDITOR_ENDPOINT_NOT_SCENARIO`: the scenario editor lists it; an endpoint for the editor is `"scope": "scenario"` (see [Scenario-scoped endpoints](../guides/endpoints.md#scenario-scoped-endpoints))
119
124
  - _'wrote X, which it does not declare in writes'_: the handler returned a capability outside its `writes`; add it, or stop returning it
120
125
  - _'The game moved on while the endpoint was running'_: a tick committed mid-call, so the patch was computed against a board that no longer exists. Make the handler faster, or move the work into the engine
121
126
 
@@ -70,7 +70,7 @@ Write the engine that moves the game on each tick: here, one that reads a price
70
70
  });
71
71
  ```
72
72
 
73
- 3. If you replaced the starter game's engine, replace or delete `engine/logic.test.ts` and the starter's other engine files, which test the old logic.
73
+ 3. If you replaced the starter game's engine, replace or delete `engine/logic.test.ts` and the starter's other engine files, which test the old logic
74
74
 
75
75
  4. In a package made with `--empty`, set how long the game runs (the starter already sets `maxTicks`):
76
76
 
@@ -32,7 +32,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
32
32
  }'
33
33
  ```
34
34
 
35
- 2. Write the chapters as markdown files in `guide/content/<locale>/`, ordered by file name, with the same file names in every locale (`01-at-a-glance.md`, `02-preparation.md`, and so on).
35
+ 2. Write the chapters as markdown files in `guide/content/<locale>/`, ordered by file name, with the same file names in every locale (`01-at-a-glance.md`, `02-preparation.md`, and so on)
36
36
 
37
37
  3. Mark the live script with admonitions:
38
38
 
@@ -48,7 +48,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
48
48
 
49
49
  `timing`, `note`, `warning`, and `tip` work the same way. See [Content rules](../guides/guide.md#content-rules) for headings, images, and video blocks.
50
50
 
51
- 4. Put images in `guide/assets/` and reference them relatively from a chapter: `![Market diagram](../../assets/market-diagram.png)`.
51
+ 4. Put images in `guide/assets/` and reference them relatively from a chapter: `![Market diagram](../../assets/market-diagram.png)`
52
52
 
53
53
  ## Verify
54
54
 
@@ -47,7 +47,7 @@ React to a lifecycle signal, such as a participant joining a team, outside the t
47
47
  });
48
48
  ```
49
49
 
50
- 3. If several hooks subscribe to the same signal and order matters, number their directories: they run in directory-name order.
50
+ 3. If several hooks subscribe to the same signal and order matters, number their directories: they run in directory-name order
51
51
 
52
52
  4. Build:
53
53
 
@@ -83,7 +83,7 @@ Build the facilitator's screen: every team's state side by side, with controls t
83
83
 
84
84
  A `scope: 'shared'` capability arrives once, in `sessionData.shared.context`, and is written with the one-argument `setData(update)`. See [Writing shared capabilities](../guides/multi-team-games.md#facilitator-writable-shared-capabilities) and the [session UI hooks reference](../guides/session.md#hooks-reference) for roster control, timers, undo, and reset.
85
85
 
86
- 3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares.
86
+ 3. If you replaced the starter's session UI, delete its other components and tests under `session/src/`, which read capabilities this one no longer declares
87
87
 
88
88
  4. Build:
89
89
 
@@ -59,7 +59,7 @@ Give a game a read-only parameter, such as a price, a difficulty, or an answer k
59
59
  return <p>Typical demand: {settings.demand.BaseDemand}</p>;
60
60
  ```
61
61
 
62
- 5. Optional: override it in a scenario, keyed by settings identifier (see [Create a scenario](create-scenario.md)). To change it for every session, edit its `default`.
62
+ 5. Optional: override it in a scenario, keyed by settings identifier (see [Create a scenario](create-scenario.md)). To change it for every session, edit its `default`
63
63
 
64
64
  ## Verify
65
65
 
@@ -21,7 +21,7 @@ Make ticks fire automatically, on an interval or a schedule your game's logic de
21
21
  }'
22
22
  ```
23
23
 
24
- 2. Write `GetTickController` in `tick_controller/logic.ts`. Return a cadence with `intervalTick`, which takes milliseconds and refuses anything outside 30 seconds to 7 days:
24
+ 2. Write `GetTickController` in `tick_controller/logic.ts`. Return a cadence with `intervalTick`, which takes milliseconds and refuses anything outside 30 seconds to seven days:
25
25
 
26
26
  ```typescript
27
27
  import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
@@ -62,7 +62,7 @@ Build the game UI: the screen each participant sees, showing the game's state an
62
62
 
63
63
  Never spread `data` (or a whole capability) back into `setData`: a write naming a capability outside `writes` is refused, and re-sending untouched fields overwrites a team-mate's concurrent write. See [Writing to context](../guides/ui.md#writing-to-context).
64
64
 
65
- 3. If you replaced the starter game's UI, delete the starter's other components and their tests under `ui/src/`: they read capabilities this UI no longer declares, so they stop type-checking.
65
+ 3. If you replaced the starter game's UI, delete the starter's other components and their tests under `ui/src/`: they read capabilities this UI no longer declares, so they stop type-checking
66
66
 
67
67
  4. Build:
68
68
 
@@ -39,7 +39,7 @@ Reject a participant's write that breaks the game's rules, before the runtime ap
39
39
 
40
40
  A validator never changes state. To read who wrote it, narrow on `actor.role` (see [The actor](../guides/validators.md#the-actor)).
41
41
 
42
- 3. Optional: gate a participant's request for the next tick by exporting `RequestTick` as well (see [Gating tick requests](../guides/validators.md#gating-tick-requests)).
42
+ 3. Optional: gate a participant's request for the next tick by exporting `RequestTick` as well (see [Gating tick requests](../guides/validators.md#gating-tick-requests))
43
43
 
44
44
  4. Build:
45
45
 
@@ -10,7 +10,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
10
10
 
11
11
  ## Steps
12
12
 
13
- 1. Open the resource's bundle file (for example `engine/engine.sdk.json`).
13
+ 1. Open the resource's bundle file (for example `engine/engine.sdk.json`)
14
14
  2. Add a `uses` array to the `definition`, listing the callback names you intend to call. The values are `generateText`, `extractText`, `generateSpeech`, and `writeBlob`; see [The closed enum](../guides/llm-integration.md#the-apis-it-gates) for what each does:
15
15
 
16
16
  ```json
@@ -25,7 +25,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
25
25
  }
26
26
  ```
27
27
 
28
- 3. Run `pnpm run sdk generate` to regenerate `types.ts`. The `Callbacks` type alias is narrowed to the callbacks you declared, each one present rather than optional, so undeclared calls fail at type-check before they fail at runtime and declared ones need no `?.` check.
28
+ 3. Run `pnpm run sdk generate` to regenerate `types.ts`. The `Callbacks` type alias is narrowed to the callbacks you declared, each one present rather than optional, so undeclared calls fail at type-check before they fail at runtime and declared ones need no `?.` check
29
29
  4. In your logic file, type the function signature with the `Callbacks` generic so calls are narrowed:
30
30
 
31
31
  ```typescript
@@ -60,9 +60,9 @@ Shape capabilities and `setData` calls so that several participants writing at o
60
60
  if (participant) setData({ votes: { Votes: { [participant.id]: 'yes' } } });
61
61
  ```
62
62
 
63
- 5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes).
63
+ 5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes)
64
64
 
65
- 6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead.
65
+ 6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead
66
66
 
67
67
  7. In component tests, merge as the host does with `mergingSetData`, or a minimal write that is correct in production fails the test. It applies `deletes` after the merge too:
68
68
 
@@ -70,9 +70,9 @@ unzip -l dist/com.example.pkg-1.2.0.zip | head
70
70
 
71
71
  ## Troubleshooting
72
72
 
73
- - **'Build directory not found'** - run `pnpm run sdk build` before `pnpm run sdk package bundle`. The bundle command does not build
74
- - **'Manifest not found'** - the build directory exists but has no `seriousgaming.json`. Re-run the build; check that it completed without errors
75
- - **Wrong identifier or version in the filename** - both are read from `dist/seriousgaming.json`, but they are authored in different places: the identifier in `seriousgaming.sdk.json`, the version in `package.json` (the manifest carries no version field). Fix whichever is wrong and rebuild
73
+ - **'Build directory not found'**: run `pnpm run sdk build` before `pnpm run sdk package bundle`. The bundle command does not build
74
+ - **'Manifest not found'**: the build directory exists but has no `seriousgaming.json`. Re-run the build; check that it completed without errors
75
+ - **Wrong identifier or version in the filename**: both are read from `dist/seriousgaming.json`, but they are authored in different places: the identifier in `seriousgaming.sdk.json`, the version in `package.json` (the manifest carries no version field). Fix whichever is wrong and rebuild
76
76
 
77
77
  ## Related
78
78
 
@@ -15,9 +15,11 @@ Test your game's screens in a real browser against an isolated dev server.
15
15
 
16
16
  ```bash
17
17
  pnpm add -D @playwright/test
18
- pnpm exec playwright install chromium
18
+ pnpm exec playwright install chromium --only-shell
19
19
  ```
20
20
 
21
+ `--only-shell` installs only the headless shell, which is all a headless run needs. `--headed`, `--debug` and `--ui` open a real browser window, so to use them run the command again without the flag to install full Chromium.
22
+
21
23
  2. Create `testing/e2e/global-setup.ts`, which starts an isolated dev server in Playwright's own process and stops it when the run ends:
22
24
 
23
25
  ```typescript
@@ -89,7 +91,7 @@ Test your game's screens in a real browser against an isolated dev server.
89
91
 
90
92
  The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
91
93
 
92
- 7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)`.
94
+ 7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)`
93
95
 
94
96
  ## Verify
95
97
 
@@ -101,13 +103,13 @@ Every spec passes. Add `--headed` to watch, or `--debug` to step through.
101
103
 
102
104
  ## Troubleshooting
103
105
 
104
- | Problem | Solution |
105
- | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
106
- | The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
107
- | Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
108
- | Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
109
- | The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |
110
- | Every spec fails on a missing browser | Run `pnpm exec playwright install chromium` after a Playwright upgrade |
106
+ | Problem | Solution |
107
+ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
108
+ | The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
109
+ | Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
110
+ | Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
111
+ | The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |
112
+ | Every spec fails on a missing browser | Run `pnpm exec playwright install chromium --only-shell` after a Playwright upgrade (drop `--only-shell` to run headed) |
111
113
 
112
114
  ## Related
113
115
 
@@ -4,11 +4,13 @@ Each recipe is one task, start to finish: prerequisites, numbered steps, a way t
4
4
 
5
5
  ## Getting started
6
6
 
7
- - [Start a game from an empty package](start-from-an-empty-package.md): build a game from nothing, with a capability, an engine, and a game UI
8
- - [Create an engine](create-engine.md): an engine that reads one capability and writes another
7
+ New to the SDK? Start with [Getting started](../getting-started.md), which plays and changes the starter game, then come back here for one task at a time.
8
+
9
9
  - [Create a capability](create-capability.md): a new slice of the game's state
10
+ - [Create an engine](create-engine.md): an engine that reads one capability and writes another
10
11
  - [Create settings](create-settings.md): a read-only parameter logic and screens read, which scenarios and facilitators can change before play
11
12
  - [Shape your game](create-game.md): set ticks, teams, and locales
13
+ - [Start a game from an empty package](start-from-an-empty-package.md): build a game from nothing, with a capability, an engine, and a game UI, once you know what the starter game does
12
14
 
13
15
  ## Scenarios
14
16
 
@@ -18,6 +20,7 @@ Each recipe is one task, start to finish: prerequisites, numbered steps, a way t
18
20
  ## Facilitation
19
21
 
20
22
  - [Create a facilitator guide](create-guide.md): markdown facilitation content shown on the facilitator's page
23
+ - [Make a guide follow the scenario](make-a-guide-follow-the-scenario.md): show settings values in the guide, and content only some scenarios need
21
24
  - [Create a presentation](create-presentation.md): the facilitator's slide deck, live with the session's results and exportable to PDF and PowerPoint
22
25
 
23
26
  ## User interfaces
@@ -58,6 +61,7 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
58
61
  ## Validation
59
62
 
60
63
  - [Create a validator](create-validator.md): reject UI mutations that break the game's rules
64
+ - [Validate a game's scenarios](validate-scenarios.md): refuse a scenario whose settings break the game's rules, at build and on save
61
65
 
62
66
  ## Runtime callbacks
63
67
 
@@ -0,0 +1,89 @@
1
+ # Make a guide follow the scenario
2
+
3
+ Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
4
+
5
+ **Keywords:** scenario-specific guide, conditional content, guide settings, show setting value, hide chapter, per-scenario facilitator notes, when directive
6
+
7
+ ## Prerequisites
8
+
9
+ - A package with a facilitator guide (see [Create a facilitator guide](create-guide.md))
10
+ - The settings you want to show or test, in a settings resource (see [Create settings](create-settings.md))
11
+
12
+ ## Steps
13
+
14
+ 1. List the settings resources the guide reads:
15
+
16
+ ```bash
17
+ pnpm run sdk update guide --patch '[
18
+ { "op": "add", "path": "/definition/settings", "value": ["engine"] }
19
+ ]'
20
+ ```
21
+
22
+ 2. Replace a vague sentence with the value, naming the settings resource and the property:
23
+
24
+ ```markdown
25
+ The game runs for :setting[engine.totalWeeks] weeks.
26
+ ```
27
+
28
+ 3. Wrap text only some scenarios need in a `:::when`. A true-or-false setting needs no more:
29
+
30
+ ```markdown
31
+ :::when{setting="engine.observers"}
32
+ Seat an observer in each team before the first round.
33
+ :::
34
+ ```
35
+
36
+ For any other setting, compare it with `is`, and add `not` to turn the result round:
37
+
38
+ ```markdown
39
+ :::when{setting="engine.mode" is="sandbox" not}
40
+ Tools unlock one round at a time.
41
+ :::
42
+ ```
43
+
44
+ 4. To show a whole chapter in one scenario only, add a setting that scenario sets, such as `Edition` in a settings resource only the guide reads, with a default for every other scenario:
45
+
46
+ ```bash
47
+ pnpm run sdk update scenario northwind --patch '[
48
+ { "op": "add", "path": "/definition/settings/guide", "value": { "Edition": "northwind" } }
49
+ ]'
50
+ ```
51
+
52
+ Then wrap the chapter, its title included, in one block. Give the block four colons when the chapter has admonitions inside it:
53
+
54
+ ```markdown
55
+ ::::when{setting="guide.Edition" is="northwind"}
56
+
57
+ # Northwind edition
58
+
59
+ :::say
60
+ Northwind runs its plants on tighter margins than the standard market.
61
+ :::
62
+ ::::
63
+ ```
64
+
65
+ ## Verify
66
+
67
+ ```bash
68
+ pnpm run sdk build --validate-only
69
+ ```
70
+
71
+ Then open `/guide` in the dev server and switch scenario: the values change and the conditioned content comes and goes.
72
+
73
+ ## Troubleshooting
74
+
75
+ | Problem | Solution |
76
+ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
77
+ | 'reads settings "…", which the guide does not list' | Add the settings resource to the guide's `settings` |
78
+ | 'can show only a number or text' | `:setting` cannot show a true-or-false value or a list. Use a `:::when` for a true-or-false setting |
79
+ | 'needs is="…", since it is not true or false' | Compare the setting with `is="value"` |
80
+ | 'sits inside another :::when' | Conditions do not nest. Give the inner block its own condition |
81
+ | Text after an admonition escapes the block | The outer block closed early. Give the `:::when` more colons than the admonitions inside it (`::::when` … `::::`) |
82
+ | 'is empty under the defaults and every scenario' | No scenario turns the condition on. Check the `is` value, or the scenario's settings |
83
+ | A red error shows in the guide in place of a value | The setting could not be read for this session. Run the build validation, which names the cause |
84
+
85
+ ## Related
86
+
87
+ - [Facilitator guides](../guides/guide.md#following-the-scenarios-settings): the full rules
88
+ - [Create a scenario](create-scenario.md)
89
+ - [Create settings](create-settings.md)
@@ -90,7 +90,7 @@ Publish one of your endpoints to callers outside the game, such as a facilitator
90
90
  - _'is external, so its requestSchema must declare `"type": "object"`'_ (`EXTERNAL_REQUEST_NOT_OBJECT`): Wrap the request in an object with a named property for each value, such as `{ "price": 3.53 }` rather than `3.53`
91
91
  - _'is internal, so a caller outside the game cannot call it'_: Set `"visibility": "external"` on the endpoint
92
92
  - _'`agentCallable` has been replaced by `visibility`'_: Replace `"agentCallable": true` with `"visibility": "external"`
93
- - _'which is team-scoped, but this surface has no team of its own'_: A session UI, setup screen, or scenario editor also lists this endpoint; give it `"scope": "session"` or stop listing it there
93
+ - _'which is team-scoped, but this surface has no team of its own'_: A session UI or setup screen also lists this endpoint; give it `"scope": "session"` or stop listing it there
94
94
  - _Two endpoints get confused for each other_: Run `endpoint list --external` and read the descriptions together. If they do not say when to pick one over the other, the agent has nothing to go on
95
95
  - _No user interface requests it_: That warning is suppressed for external endpoints, whose caller no bundle names. If you see it, `visibility` is not `external`
96
96
 
@@ -126,7 +126,7 @@ pnpm run --silent sdk package publish --json | tee publish.json
126
126
  - **'No API key configured'**: set `SERIOUSGAMING_API_KEY` in your environment or pass `--api-key`
127
127
  - **'No publisher configured'**: set `SERIOUSGAMING_PUBLISHER`, pass `--publisher <slug>`, or run `pnpm run sdk config set platform.defaultPublisher <slug>`
128
128
  - **'Invalid API key'** (401): the token is malformed or has been revoked. Issue a new one
129
- - **'The account that created this API key does not have publishing access'** (403): the key is valid, but its account cannot publish. Ask Business Simulations to grant publishing access to that account, or use a key from an account that has it
129
+ - **'The account that created this API key does not have publishing access'** (403): the key is valid, but its account cannot publish. Ask Serious Gaming support to grant publishing access to that account, or use a key from an account that has it
130
130
  - **An identifier error mentioning a publisher** (400): the package is already bound to a different publisher. Upload later versions under the same publisher it was first published with
131
131
  - **'Version X.Y.Z of <identifier> already exists'** (409): bump the version (`pnpm run sdk package version patch`) and retry. The CLI deliberately does not auto-bump, so an agent can decide whether to bump or abort
132
132
  - **'Bundle not found at dist/...'**: run `pnpm run sdk build` first, or drop `--no-auto-bundle` and let the command bundle for you
@@ -26,7 +26,7 @@ A viewer's own choices, such as the tab they had open, a panel they collapsed, o
26
26
  <Tabs value={tab} onChange={(_, value: number) => setTab(value)}>
27
27
  ```
28
28
 
29
- 3. Keep the key short and specific to the surface: it only has to be unique among the values one surface stores. The hook adds the session key, the surface and the viewer itself.
29
+ 3. Keep the key short and specific to the surface: it only has to be unique among the values one surface stores. The hook adds the session key, the surface and the viewer itself
30
30
 
31
31
  ## What it is keyed by
32
32
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  Let participants scrub back through their team's committed ticks, or chart a value across every tick, with `usePastState` and `getPastState`.
4
4
 
5
+ Revisiting a round supports reflection: a team can see what it decided and what followed before it decides again.
6
+
5
7
  **Keywords:** getPastState, usePastState, PastStateQuery, PastStateEntry, tick snapshot, review past day, history, scrubber, timeline, replay, previous tick, completedTicks, cross-team history, TickSnapshotError, results table, history chart, round_history growing
6
8
 
7
9
  ## Prerequisites
@@ -44,9 +46,9 @@ Let participants scrub back through their team's committed ticks, or chart a val
44
46
 
45
47
  This is what lets you drop a `round_history` capability that grows every tick.
46
48
 
47
- 4. In a shared-state game, review every team at that tick with `teams: 'all'`, typed by the generated `CrossTeamContext`. Other teams' rows arrive only for capabilities the surface lists in `crossTeamReads` (see [Observe other teams' state](observe-other-teams-state.md)). A session UI calls the same `getPastState` from `useSessionUserInterfaceCallbacks()`, and its default is the whole session.
49
+ 4. In a shared-state game, review every team at that tick with `teams: 'all'`, typed by the generated `CrossTeamContext`. Other teams' rows arrive only for capabilities the surface lists in `crossTeamReads` (see [Observe other teams' state](observe-other-teams-state.md)). A session UI calls the same `getPastState` from `useSessionUserInterfaceCallbacks()`, and its default is the whole session
48
50
 
49
- 5. Optional: for a slider dragged quickly, debounce the query, and cache entries by tick. Evict cached ticks at or above `completedTicks` when it drops, so an undo never shows a stale board.
51
+ 5. Optional: for a slider dragged quickly, debounce the query, and cache entries by tick. Evict cached ticks at or above `completedTicks` when it drops, so an undo never shows a stale board
50
52
 
51
53
  ## Verify
52
54
 
@@ -108,9 +108,9 @@ Start the dev server and confirm the file is served at `/api/shared/assets/story
108
108
 
109
109
  ## Troubleshooting
110
110
 
111
- - **404 from the shared asset URL** - the path inside `shared:<path>` is relative to `shared-assets/`, not to a scenario's `assets/`. Check the file exists under `shared-assets/<path>` and that you ran `build` so it was copied into `dist/`
112
- - **The wrong file resolves** - `shared:` and `asset:` never shadow each other. If you meant the scenario's own copy, use `asset:<path>`; if you meant the shared copy, use `shared:<path>`
113
- - **`getAssetUrl` or `useAssetUrl` throws** - the reference must start with `asset:`, `shared:`, or `blob:`. A bare path is not a valid reference
111
+ - **404 from the shared asset URL**: the path inside `shared:<path>` is relative to `shared-assets/`, not to a scenario's `assets/`. Check the file exists under `shared-assets/<path>` and that you ran `build` so it was copied into `dist/`
112
+ - **The wrong file resolves**: `shared:` and `asset:` never shadow each other. If you meant the scenario's own copy, use `asset:<path>`; if you meant the shared copy, use `shared:<path>`
113
+ - **`getAssetUrl` or `useAssetUrl` throws**: the reference must start with `asset:`, `shared:`, or `blob:`. A bare path is not a valid reference
114
114
 
115
115
  ## Related
116
116
 
@@ -58,7 +58,7 @@ Writing the formula twice works right up until someone changes one copy. Then th
58
58
  }
59
59
  ```
60
60
 
61
- 3. Import it from your engine's logic. The engine stays the authority: it computes the value that is written to state.
61
+ 3. Import it from your engine's logic. The engine stays the authority: it computes the value that is written to state
62
62
 
63
63
  ```typescript
64
64
  // engine/logic.ts
@@ -23,7 +23,7 @@ A fresh team starts with one participant, at `/team/<n>/player/1`. Participants
23
23
 
24
24
  Use **Add participant** on the team's row in the dev drawer to create each role, or `pnpm run sdk participant add Buyer --team 1` from the CLI, which names it too. To rename one later, use `pnpm run sdk participant rename <participantId> <name>`; `pnpm run sdk view` lists the ids. Creating a participant fires the `participantJoin` hook, exactly as it would in production, so any join-driven setup runs.
25
25
 
26
- If the game declares `teams.perTeam.minParticipants` / `maxParticipants`, the roster shows an advisory caption (for example '2–5 recommended for this scenario'). It is guidance only and never blocks adding or removing.
26
+ If the game declares `teams.perTeam.minParticipants` / `maxParticipants`, the roster shows an advisory caption (for example '2 to 5 recommended for this scenario'). It is guidance only and never blocks adding or removing.
27
27
 
28
28
  ### 3. Open each participant in its own tab
29
29
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Write and run component tests for a user interface with Vitest, React Testing Library, and the SDK's render helpers.
4
4
 
5
- **Keywords:** test UI, unit test, React testing, App.test.tsx, vitest, testing library, mock context, setData, controlled input, renderUserInterface, renderSessionUserInterface, renderSettingsEditor, mock participant, participant roster, sessionKey
5
+ **Keywords:** test UI, unit test, React testing, App.test.tsx, vitest, testing library, mock context, setData, controlled input, renderUserInterface, renderSessionUserInterface, renderSettingsEditor, mock participant, participant roster, mock team, sessionKey
6
6
 
7
7
  ## Prerequisites
8
8
 
@@ -10,7 +10,7 @@ Write and run component tests for a user interface with Vitest, React Testing Li
10
10
 
11
11
  ## Steps
12
12
 
13
- 1. Open the test beside the component: `ui/src/App.test.tsx` for the game UI (`session/src/`, `waiting_room/src/`, `setup/src/` and the others for theirs).
13
+ 1. Open the test beside the component: `ui/src/App.test.tsx` for the game UI (`session/src/`, `waiting_room/src/`, `setup/src/` and the others for theirs)
14
14
 
15
15
  2. Render through the helper for the surface, giving it only what the test cares about. Every other context value has a complete default, so never build the providers by hand:
16
16
 
@@ -68,6 +68,17 @@ Write and run component tests for a user interface with Vitest, React Testing Li
68
68
  renderUserInterface(<App />, { data: defaultContext, participants: createMockParticipants(3) });
69
69
  ```
70
70
 
71
+ The participant's team (`ownTeam`) is found in `teams` by its `teamId`. Build either with `createMockTeam` and `createMockTeams` rather than by hand, so a field later added to a team reaches the test with a value:
72
+
73
+ ```tsx
74
+ import { createMockTeam } from '@seriousgaming/sdk/ui/testing';
75
+
76
+ renderUserInterface(<App />, {
77
+ data: defaultContext,
78
+ ownTeam: createMockTeam({ name: 'North' }),
79
+ });
80
+ ```
81
+
71
82
  6. Run the tests:
72
83
 
73
84
  ```bash