@seriousgaming/sdk-tools 1.3.0 → 1.5.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 (176) hide show
  1. package/dist/cli.js +4055 -2646
  2. package/dist/client.js +807 -172
  3. package/dist/core/session-host.d.ts +4 -2
  4. package/dist/core/settings-locks.d.ts +27 -2
  5. package/dist/dev/console/assets/{index-DEV8N0na.js → index-BVF8exas.js} +22 -22
  6. package/dist/dev/console/index.html +1 -1
  7. package/dist/dev/public-origins.d.ts +61 -0
  8. package/dist/dev/routes.d.ts +4 -0
  9. package/dist/dev/shell.d.ts +32 -4
  10. package/dist/dev/view/batch.d.ts +7 -1
  11. package/dist/docs/ai-agents.md +5 -0
  12. package/dist/docs/api/index.md +1 -1
  13. package/dist/docs/api/sdk-tools-client.md +1 -0
  14. package/dist/docs/api/sdk.md +79 -2
  15. package/dist/docs/changelog-0.x.md +2 -2
  16. package/dist/docs/changelog.md +62 -4
  17. package/dist/docs/cli-and-dev-server.md +58 -0
  18. package/dist/docs/cli-error-codes.md +39 -36
  19. package/dist/docs/cli-reference.md +68 -21
  20. package/dist/docs/concepts/terminology.md +1 -1
  21. package/dist/docs/environment-variables.md +10 -5
  22. package/dist/docs/guides/ai-facilitation.md +2 -0
  23. package/dist/docs/guides/capabilities.md +4 -0
  24. package/dist/docs/guides/designing-a-game.md +2 -0
  25. package/dist/docs/guides/designing-screens.md +133 -0
  26. package/dist/docs/guides/endpoints.md +4 -2
  27. package/dist/docs/guides/engine-testing.md +6 -2
  28. package/dist/docs/guides/engine.md +2 -0
  29. package/dist/docs/guides/file-handling.md +116 -22
  30. package/dist/docs/guides/games.md +3 -1
  31. package/dist/docs/guides/global-settings.md +2 -0
  32. package/dist/docs/guides/guide.md +2 -0
  33. package/dist/docs/guides/hooks.md +2 -0
  34. package/dist/docs/guides/index.md +9 -0
  35. package/dist/docs/guides/internationalization.md +2 -0
  36. package/dist/docs/guides/llm-integration.md +5 -3
  37. package/dist/docs/guides/multi-team-games.md +3 -1
  38. package/dist/docs/guides/patterns.md +2 -0
  39. package/dist/docs/guides/presentation.md +1 -1
  40. package/dist/docs/guides/production-constraints.md +2 -0
  41. package/dist/docs/guides/scenario-editor.md +3 -1
  42. package/dist/docs/guides/scenarios.md +15 -3
  43. package/dist/docs/guides/session-game-flow.md +365 -0
  44. package/dist/docs/guides/session-hooks.md +205 -0
  45. package/dist/docs/guides/session.md +27 -565
  46. package/dist/docs/guides/settings.md +64 -2
  47. package/dist/docs/guides/setup.md +3 -1
  48. package/dist/docs/guides/speech-generation.md +2 -0
  49. package/dist/docs/guides/starter-game.md +61 -21
  50. package/dist/docs/guides/testing.md +2 -0
  51. package/dist/docs/guides/tick-controller.md +3 -1
  52. package/dist/docs/guides/type-safety.md +2 -0
  53. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  54. package/dist/docs/guides/ui-participants.md +281 -0
  55. package/dist/docs/guides/ui-styling.md +263 -0
  56. package/dist/docs/guides/ui-ticks.md +247 -0
  57. package/dist/docs/guides/ui.md +11 -1092
  58. package/dist/docs/guides/upgrading.md +2 -0
  59. package/dist/docs/guides/validators.md +64 -4
  60. package/dist/docs/guides/waiting-room.md +1 -1
  61. package/dist/docs/index.md +2 -1
  62. package/dist/docs/page-index.md +145 -0
  63. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  64. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  65. package/dist/docs/recipes/create-presentation.md +11 -0
  66. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  67. package/dist/docs/recipes/create-session-ui.md +2 -1
  68. package/dist/docs/recipes/create-setup.md +1 -0
  69. package/dist/docs/recipes/create-user-interface.md +1 -0
  70. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  71. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  72. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  73. package/dist/docs/recipes/index.md +3 -0
  74. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  75. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  76. package/dist/docs/recipes/upload-and-display-files.md +7 -7
  77. package/dist/docs/recipes/use-request-tick.md +2 -2
  78. package/dist/docs/recipes/validate-scenarios.md +4 -1
  79. package/dist/execution/config-resolver.d.ts +4 -1
  80. package/dist/execution/endpoint-runner.d.ts +6 -0
  81. package/dist/execution/logic-calls.d.ts +7 -2
  82. package/dist/execution/scenario-gates.d.ts +21 -1
  83. package/dist/guide/settings.d.ts +1 -1
  84. package/dist/host.js +64 -2
  85. package/dist/runtime/manifest-version.d.ts +1 -1
  86. package/dist/runtime.js +7 -2
  87. package/dist/storage/asset-resolver.d.ts +24 -1
  88. package/dist/storage/blob-store.d.ts +7 -0
  89. package/dist/templates/package/CLAUDE.md.template +14 -5
  90. package/dist/templates/package/DESIGN.md.liquid +39 -7
  91. package/dist/templates/package/README.md.liquid +1 -1
  92. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  93. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  94. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  95. package/dist/templates/starter-game/package.json +2 -0
  96. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  97. package/dist/templates/starter-game/presentation/index.html +20 -0
  98. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  99. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  100. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  101. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  102. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  103. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  104. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  105. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  106. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  107. package/dist/templates/starter-game/presentation/types.ts +94 -0
  108. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  109. package/dist/templates/starter-game/session/defaults.ts +6 -0
  110. package/dist/templates/starter-game/session/index.html +1 -1
  111. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  112. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  113. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  114. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  115. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  116. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  117. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  118. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  119. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  120. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  121. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  122. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  123. package/dist/templates/starter-game/session/src/status.ts +28 -0
  124. package/dist/templates/starter-game/session/types.ts +8 -2
  125. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  126. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  127. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  128. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  129. package/dist/templates/starter-game/shared/days.ts +11 -0
  130. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  131. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  132. package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
  133. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  134. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  135. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  136. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  137. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  138. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  139. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  140. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  141. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  142. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  143. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  144. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  145. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  146. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  147. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  148. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  149. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  150. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  151. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  152. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  153. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  154. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  155. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  156. package/dist/templates/starter-game/ui/types.ts +6 -0
  157. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  158. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  159. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  160. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  161. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  162. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  163. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  164. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  165. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  166. package/dist/utils/error-codes.d.ts +12 -0
  167. package/dist/utils/local-refs.d.ts +40 -0
  168. package/dist/utils/schema-members.d.ts +19 -0
  169. package/package.json +11 -4
  170. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  171. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  172. package/dist/templates/starter-game/session/src/format.ts +0 -8
  173. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  174. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  175. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  176. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
@@ -33,6 +33,8 @@ Most steps are mechanical and the compiler finds what they break. **These change
33
33
 
34
34
  The [changelog](../changelog.md) carries the detail behind every step.
35
35
 
36
+ **Keywords:** upgrade, migrate, migration, 0.6 to 1.0, breaking changes, configurationSchema, settings resources, @seriousgaming, rename packages, upgrade steps
37
+
36
38
  ## Step 1: rename the packages
37
39
 
38
40
  The three public packages move to the `@seriousgaming` scope on the public npm registry, and install without a token. Their subpaths are unchanged, and so is the `seriousgaming-sdk` command, so `pnpm run sdk` keeps working.
@@ -2,6 +2,8 @@
2
2
 
3
3
  A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it. A validator can also gate a scenario, refusing one whose settings break your game's rules ([Gating scenarios](#gating-scenarios)).
4
4
 
5
+ **Keywords:** validator, validation, reject, gate, UpdateData, RequestTick, Scenario gate, actor, business rules, refuse a write, check a tick request, validate scenarios
6
+
5
7
  ## The model
6
8
 
7
9
  Some rules cannot be written in `variablesSchema`. JSON Schema handles the shape of the data ('Price must be a non-negative number'), but not a rule across fields, such as 'only three of these ten booleans may be true at once' or 'the budget across these fields must not exceed N'. The engine cannot gate such a rule either, because it runs on the tick rather than when a UI submits. That leaves the front end, which is the wrong layer for an integrity rule: devtools bypass it, and so do test scripts and future non-web clients.
@@ -193,9 +195,11 @@ A refusal stops the tick, and the participant's `requestTick()` rejects with the
193
195
 
194
196
  A settings schema checks each value on its own. It cannot say that two values conflict, such as a lowest price above the highest, or that a value has no sensible default and every scenario must supply its own, such as the name of the client an edition is built for. A `Scenario` gate says both.
195
197
 
196
- Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about as a dotted `path`; an empty array passes:
198
+ Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about by its `path`; an empty array passes:
197
199
 
198
200
  ```typescript
201
+ import { settingPath } from '@seriousgaming/sdk';
202
+
199
203
  import type { ScenarioFunction } from '../types';
200
204
 
201
205
  export const Scenario: ScenarioFunction = async ({ settings }) => {
@@ -203,13 +207,13 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
203
207
  const problems = [];
204
208
  if (MinPrice > MaxPrice) {
205
209
  problems.push({
206
- path: 'pricing.MinPrice',
210
+ path: settingPath('pricing', 'MinPrice'),
207
211
  message: `The lowest price (£${MinPrice}) must be at or below the highest price (£${MaxPrice})`,
208
212
  });
209
213
  }
210
214
  if (settings.edition.ClientName === '') {
211
215
  problems.push({
212
- path: 'edition.ClientName',
216
+ path: settingPath('edition', 'ClientName'),
213
217
  message: 'Every scenario names the client it is built for',
214
218
  });
215
219
  }
@@ -217,6 +221,8 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
217
221
  };
218
222
  ```
219
223
 
224
+ A `path` is a setting path: `pricing.MinPrice`, the settings identifier and each key below it (see [How a setting is named](./settings.md#how-a-setting-is-named)). An editor reads it back to show the problem beside its field. Build it with `settingPath` rather than joining keys with dots, so a map entry whose key holds a dot is still named one way: `settingPath('cast', 'Portraits', 'a.b')` is `cast.Portraits["a.b"]`.
225
+
220
226
  A game whose validator exports `Scenario` lists the feature in `seriousgaming.sdk.json`, and the build refuses it otherwise (`FEATURE_UNDECLARED`). A runtime that cannot run the gate then refuses the game, rather than saving scenarios your rules would refuse:
221
227
 
222
228
  ```json
@@ -225,6 +231,60 @@ A game whose validator exports `Scenario` lists the feature in `seriousgaming.sd
225
231
  }
226
232
  ```
227
233
 
234
+ ### Checking the files a scenario names
235
+
236
+ A rule about a file setting is often a rule about the file: that the portrait is there, or that the briefing is not empty. List `scenario-files` in `requires` beside `scenario-validation`, and the gate receives `callbacks` with two file reads, `readAsset` and `describeAsset`:
237
+
238
+ ```json
239
+ {
240
+ "requires": ["scenario-validation", "scenario-files"]
241
+ }
242
+ ```
243
+
244
+ ```typescript
245
+ import type { ScenarioFunction } from '../types';
246
+
247
+ export const Scenario: ScenarioFunction = async ({ settings, callbacks }) => {
248
+ const portrait = settings.cast.CeoPortrait;
249
+ if (portrait !== '' && (await callbacks.describeAsset(portrait)) === undefined) {
250
+ return [
251
+ {
252
+ path: 'cast.CeoPortrait',
253
+ message: `The CEO's portrait (${portrait}) is not a file this scenario has. Upload it again`,
254
+ },
255
+ ];
256
+ }
257
+ return [];
258
+ };
259
+ ```
260
+
261
+ - **They read the scenario being judged.** At build, `asset:` resolves against that scenario's own `assets/` and `shared:` against `shared-assets/`; a package scenario cannot name a blob, so a `blob:` reference finds nothing. On save, a draft's files resolve as the draft reads them: the built-in scenario it descends from, which for a draft of a package scenario is that scenario, and the files uploaded to it
262
+ - **`describeAsset`** answers `{ mimeType, size }`, or `undefined` for a file that is not there, without reading it. Prefer it when you only need to know the file exists or fits. **`readAsset`** returns the bytes, and rejects for a file that is not there
263
+ - **Nothing else.** No `generateText` and no `extractText`: the gate stays quick and gives the same answer every time. A rule that needs either belongs in an endpoint the scenario editor calls
264
+ - **Reads count against the gate's time limit**, so a gate reading every video whole may run out of time and refuse the scenario. Use `describeAsset` for those
265
+ - **`readAsset` reads nothing over 10 MB.** For a larger file it rejects with a `ScenarioAssetTooLargeError`, before reading any of it, and unless you catch it the gate counts as refusing the scenario: the build fails, or the save is refused, naming the file, its size and the limit. The limit is `SCENARIO_GATE_READ_LIMIT_BYTES` from `@seriousgaming/sdk` (10,485,760 bytes), the same in every runtime, so the gate gives the same answer at build and on save. To check that a video is there, or how big it is, call `describeAsset`, which works on a file of any size. To catch the error, test its `name`, not `instanceof`: the gate may run apart from the SDK that defines the class
266
+ - **Without `scenario-files`**, each call throws, naming the feature, and the gate counts as refusing the scenario. The build cannot tell in advance whether your gate reads a file, so this is where you find out
267
+ - **Your generated `ScenarioFunction` requires `callbacks`** once the package lists the feature, so a test calls the gate with them. Build them from plain functions:
268
+
269
+ ```typescript
270
+ const judge = (ui: Partial<Settings['ui']>) =>
271
+ Scenario({
272
+ settings: { ui: { ...defaultSettings.ui, ...ui } },
273
+ locale: 'en',
274
+ callbacks: {
275
+ describeAsset: async (reference) =>
276
+ reference === 'shared:branding/logo.svg'
277
+ ? { mimeType: 'image/svg+xml', size: 2048 }
278
+ : undefined,
279
+ readAsset: async (reference) => {
280
+ throw new Error(`${reference} is not read in this test`);
281
+ },
282
+ },
283
+ });
284
+ ```
285
+
286
+ `examples/factory`'s `scenariocheck` validator refuses a scenario whose branding logo is not a file it has.
287
+
228
288
  ### When it runs
229
289
 
230
290
  - **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
@@ -243,7 +303,7 @@ A problem's message is shown as it is, to whoever is editing the scenario, and a
243
303
 
244
304
  The gate is the last word, and it runs on save. A [scenario editor](./scenario-editor.md) can show the same problems as the author types by importing the rules the gate uses. Put the rules in a file both can reach, such as `shared/scenario-rules.ts`, call it from the gate, and call it from the editor to mark each field. Rules shared with logic run in the logic environment too, so keep them to plain functions with no browser or Node APIs.
245
305
 
246
- The gate reads no game state and receives no `actor`, `meta` or callbacks: there is no session or participant behind a scenario. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
306
+ The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
247
307
 
248
308
  The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
249
309
 
@@ -174,7 +174,7 @@ await renameOwnTeam('The Cartographers');
174
174
 
175
175
  It names no team: the host resolves the caller's, so a surface can only rename its own. Render `useUserInterfaceOwnTeam()?.name` rather than what you sent, because a facilitator may rename the same team at the same moment and the last write wins. A blank or over-long name is refused as a terminal `MutationError`. See [Letting a team name itself](./ui.md) for the full contract.
176
176
 
177
- The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui.md#letting-a-participant-fix-their-own-name).
177
+ The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui-participants.md#letting-a-participant-fix-their-own-name).
178
178
 
179
179
  ## Stopping the clock
180
180
 
@@ -49,6 +49,7 @@ The SDK and the deck library are Apache-2.0. The CLI and the dev server are unde
49
49
  - **[Guides](./guides/index.md)**: one page per resource kind or topic, explaining it and serving as its reference
50
50
  - **[Recipes](./recipes/index.md)**: one task each, step by step
51
51
  - **[API reference](./api/index.md)**: every export of the SDK, the deck library and the test client, one page per entry point
52
+ - **[Page index](./page-index.md)**: every page with a one-sentence summary and its length, to find the page for a fact
52
53
 
53
54
  ## The CLI and the dev server
54
55
 
@@ -68,4 +69,4 @@ The SDK and the deck library are Apache-2.0. The CLI and the dev server are unde
68
69
  - **[Upgrading](./guides/upgrading.md)**: the steps from 0.6 to 1.0
69
70
  - **[Changelog for 0.x](./changelog-0.x.md)**: every release before 1.0
70
71
 
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.
72
+ 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, or one section of it with `--section`, and `pnpm run sdk docs export` copies them into your package for an editor or agent to search.
@@ -0,0 +1,145 @@
1
+ <!-- Generated by `pnpm docs:generate` from every page under `sdk-tools/docs` and `sdk-tools/docs-partials/page-index/`. Edit those, not this file. -->
2
+
3
+ # Page index
4
+
5
+ Every page of the documentation, with a one-sentence summary and its length, so you can find the page that holds a fact before you read anything long.
6
+
7
+ **Keywords:** index, page index, table of contents, sitemap, find a page, outline, sections, page length, search the docs
8
+
9
+ Many guides are long: the longest run past 60,000 characters. Rather than reading one whole, find it here, list its sections with `--outline`, and read the one you need with `--section`:
10
+
11
+ ```bash
12
+ pnpm run --silent sdk docs view page-index.md
13
+ pnpm run --silent sdk docs view guides/session.md --outline
14
+ pnpm run --silent sdk docs view guides/session.md --section 'Building the session UI'
15
+ ```
16
+
17
+ `--section` takes a heading's text or its slug, the anchor the outline prints beside it, and returns the heading and everything under it up to the next heading of the same or a higher level. Add `--json` to either for the result as data. Each page also carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right one.
18
+
19
+ This index lists pages; `--outline` lists a page's sections, each with its slug and its exact length. Lengths here are rounded to the nearest thousand characters, and the changelogs, which grow with every release, are listed without one.
20
+
21
+ ## Start here and reference
22
+
23
+ - [`index.md`](index.md), about 6k characters: 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.
24
+ - [`ai-agents.md`](ai-agents.md), about 5k characters: An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer.
25
+ - [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
26
+ - [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
27
+ - [`cli-and-dev-server.md`](cli-and-dev-server.md), about 14k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
28
+ - [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
29
+ - [`cli-reference.md`](cli-reference.md), about 158k characters: Every `seriousgaming-sdk` command and flag, in one place.
30
+ - [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
31
+ - [`environment-variables.md`](environment-variables.md), about 9k characters: A single reference for every environment variable the dev server and CLI read.
32
+ - [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
33
+ - [`troubleshooting.md`](troubleshooting.md), about 34k characters: Find the symptom you are seeing, then read its cause and fix.
34
+
35
+ ## Concepts
36
+
37
+ - [`concepts/index.md`](concepts/index.md), about 9k characters: The model behind the SDK on one page, and how its parts fit together.
38
+ - [`concepts/terminology.md`](concepts/terminology.md), about 26k characters: Definitions of the terms used across the SDK, the CLI, the dev server, and these docs.
39
+
40
+ ## Guides
41
+
42
+ - [`guides/index.md`](guides/index.md), about 5k characters: Each guide is the one page for a resource kind or a topic: it explains the model, then serves as the reference, with every field, every option, and the rules behind them.
43
+ - [`guides/ai-facilitation.md`](guides/ai-facilitation.md), about 14k characters: A facilitator running your game may have an AI agent beside them: something they can ask 'how is Team B doing', 'why has their profit fallen', or 'set their unit price to 3.53'.
44
+ - [`guides/capabilities.md`](guides/capabilities.md), about 20k characters: Capabilities hold your game's state: named groups of variables that the engine and screens read and write.
45
+ - [`guides/designing-a-game.md`](guides/designing-a-game.md), about 9k characters: A serious game teaches by letting people act and then see what their actions caused.
46
+ - [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
47
+ - [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
48
+ - [`guides/engine-testing.md`](guides/engine-testing.md), about 28k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
49
+ - [`guides/engine.md`](guides/engine.md), about 33k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
50
+ - [`guides/file-handling.md`](guides/file-handling.md), about 28k characters: Ship files with your game or let participants upload them, then show them in any UI and read them in logic, all through one reference scheme.
51
+ - [`guides/games.md`](guides/games.md), about 7k characters: Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
52
+ - [`guides/global-settings.md`](guides/global-settings.md), about 4k characters: The global settings file lets you store API keys and defaults once, in a single user-owned file, so every project picks them up.
53
+ - [`guides/guide.md`](guides/guide.md), about 10k characters: A facilitator guide bundles the run-sheet for a simulation into the package itself: markdown chapters and images that the host renders natively on the facilitator's page.
54
+ - [`guides/hooks.md`](guides/hooks.md), about 10k characters: A hook is logic that runs when the runtime emits a lifecycle signal, such as a participant joining a team.
55
+ - [`guides/internationalization.md`](guides/internationalization.md), about 11k characters: Run your game in more than one language: declare the locales it supports, then translate its screens, scenario content, dates, and numbers.
56
+ - [`guides/llm-integration.md`](guides/llm-integration.md), about 26k characters: Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
57
+ - [`guides/multi-team-games.md`](guides/multi-team-games.md), about 35k characters: Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
58
+ - [`guides/patterns.md`](guides/patterns.md), about 12k characters: Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern.
59
+ - [`guides/presentation.md`](guides/presentation.md), about 16k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
60
+ - [`guides/production-constraints.md`](guides/production-constraints.md), about 10k characters: In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
61
+ - [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
62
+ - [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
63
+ - [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
64
+ - [`guides/session-hooks.md`](guides/session-hooks.md), about 14k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
65
+ - [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
66
+ - [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
67
+ - [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
68
+ - [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
69
+ - [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
70
+ - [`guides/testing.md`](guides/testing.md), about 32k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
71
+ - [`guides/theming-and-branding.md`](guides/theming-and-branding.md), about 11k characters: Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
72
+ - [`guides/tick-controller.md`](guides/tick-controller.md), about 30k characters: A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
73
+ - [`guides/type-safety.md`](guides/type-safety.md), about 16k characters: The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
74
+ - [`guides/ui-files-and-llms.md`](guides/ui-files-and-llms.md), about 13k characters: How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
75
+ - [`guides/ui-participants.md`](guides/ui-participants.md), about 15k characters: How a game UI reads who is playing: the current participant, their team, observers and walkthroughs, and the controls that let a team join, name itself, and fix a participant's name.
76
+ - [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
77
+ - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
+ - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
+ - [`guides/upgrading.md`](guides/upgrading.md), about 66k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
+ - [`guides/validators.md`](guides/validators.md), about 23k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
+ - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: 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.
82
+
83
+ ## Recipes
84
+
85
+ - [`recipes/index.md`](recipes/index.md), about 7k characters: Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong.
86
+ - [`recipes/act-on-the-session-from-an-endpoint.md`](recipes/act-on-the-session-from-an-endpoint.md), about 4k characters: Let one endpoint call do what a facilitator would otherwise do in several steps, such as posting a notice, closing the waiting room and starting the next round, under your game's own rules.
87
+ - [`recipes/adapt-a-game-for-walkthroughs.md`](recipes/adapt-a-game-for-walkthroughs.md), about 6k characters: A walkthrough is a disposable second run of your game beside the session, for demonstrating it: one team, one participant, always from tick 0, and isolated from the session in both directions.
88
+ - [`recipes/adapt-ui-for-observers.md`](recipes/adapt-ui-for-observers.md), about 4k characters: An observer is a facilitator watching one team's live game UI without joining as a team member.
89
+ - [`recipes/call-endpoint-from-ui.md`](recipes/call-endpoint-from-ui.md), about 6k characters: Call a server-side endpoint from any of your game's screens and handle its response or its failure.
90
+ - [`recipes/check-a-package-from-a-script.md`](recipes/check-a-package-from-a-script.md), about 5k characters: Validate a package and play a few ticks from CI or an AI agent, and turn each failure into the file and line to fix.
91
+ - [`recipes/create-capability.md`](recipes/create-capability.md), about 3k characters: Define a named slice of the game's state that the engine and screens read and write.
92
+ - [`recipes/create-endpoint.md`](recipes/create-endpoint.md), about 7k characters: Add a server-side handler your screens, or callers outside the game, can invoke by name with a validated request and response.
93
+ - [`recipes/create-engine.md`](recipes/create-engine.md), about 4k characters: Write the engine that moves the game on each tick: here, one that reads a price and writes the day's revenue.
94
+ - [`recipes/create-game.md`](recipes/create-game.md), about 3k characters: Set what your package's game is: its name in each locale, how long it runs, and its teams.
95
+ - [`recipes/create-guide.md`](recipes/create-guide.md), about 3k characters: Bundle a facilitator guide with your game: markdown chapters shown on the facilitator's page.
96
+ - [`recipes/create-hook.md`](recipes/create-hook.md), about 3k characters: React to a lifecycle signal, such as a participant joining a team, outside the tick loop.
97
+ - [`recipes/create-presentation.md`](recipes/create-presentation.md), about 7k characters: Ship the facilitator's slide deck with the game, so the briefing, the round dividers, the debriefs and the results travel with the package rather than in an email after train the trainer.
98
+ - [`recipes/create-scenario-editor.md`](recipes/create-scenario-editor.md), about 3k characters: Give people a screen for building new scenarios for your released game, without rebuilding it.
99
+ - [`recipes/create-scenario.md`](recipes/create-scenario.md), about 3k characters: Bundle a game flavour with settings overrides and static assets.
100
+ - [`recipes/create-session-ui.md`](recipes/create-session-ui.md), about 5k characters: Build the facilitator's screen: every team's state side by side, with controls to change values and run the session.
101
+ - [`recipes/create-settings.md`](recipes/create-settings.md), about 4k characters: Give a game a read-only parameter, such as a price, a difficulty, or an answer key, that its logic and screens read and that scenarios and facilitators can change before play starts.
102
+ - [`recipes/create-setup.md`](recipes/create-setup.md), about 3k characters: Give facilitators a short form at session creation that sets a few of your game's settings for that session only.
103
+ - [`recipes/create-tick-controller.md`](recipes/create-tick-controller.md), about 3k characters: Make ticks fire automatically, on an interval or a schedule your game's logic decides.
104
+ - [`recipes/create-user-interface.md`](recipes/create-user-interface.md), about 4k characters: Build the game UI: the screen each participant sees, showing the game's state and taking their decisions.
105
+ - [`recipes/create-validator.md`](recipes/create-validator.md), about 4k characters: Reject a participant's write that breaks the game's rules, before the runtime applies it.
106
+ - [`recipes/create-waiting-room-ui.md`](recipes/create-waiting-room-ui.md), about 5k characters: Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
107
+ - [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
108
+ - [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
109
+ - [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
110
+ - [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 5k characters: Test your game's screens in a real browser against an isolated dev server.
111
+ - [`recipes/end-game-on-condition.md`](recipes/end-game-on-condition.md), about 5k characters: Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
112
+ - [`recipes/fix-duplicate-packages.md`](recipes/fix-duplicate-packages.md), about 4k characters: Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package being loaded by the dev server.
113
+ - [`recipes/make-a-guide-follow-the-scenario.md`](recipes/make-a-guide-follow-the-scenario.md), about 5k characters: Show the session's settings in the facilitator guide, and show content only to the scenarios that need it.
114
+ - [`recipes/make-an-endpoint-external.md`](recipes/make-an-endpoint-external.md), about 5k characters: Publish one of your endpoints to callers outside the game, such as a facilitator's AI agent or a platform API, so it can be invoked by asking or by another system rather than by clicking.
115
+ - [`recipes/negotiate-across-teams.md`](recipes/negotiate-across-teams.md), about 8k characters: Build a game where two teams propose, agree, and settle an exchange with each other, using a team-readable ledger and authoritative settlement at tick time.
116
+ - [`recipes/observe-other-teams-state.md`](recipes/observe-other-teams-state.md), about 8k characters: Let one team's user interface watch another team's pending decisions live, without waiting for a tick.
117
+ - [`recipes/publish-a-package.md`](recipes/publish-a-package.md), about 7k characters: Build, bundle, and upload a package to the Serious Gaming platform in a single command.
118
+ - [`recipes/remember-a-viewers-choice.md`](recipes/remember-a-viewers-choice.md), about 3k characters: A viewer's own choices, such as the tab they had open, a panel they collapsed, or a sort order, should survive a reload.
119
+ - [`recipes/review-a-past-day.md`](recipes/review-a-past-day.md), about 5k characters: Let participants scrub back through their team's committed ticks, or chart a value across every tick, with `usePastState` and `getPastState`.
120
+ - [`recipes/screenshot-a-surface.md`](recipes/screenshot-a-surface.md), about 5k characters: Capture one of your game's screens as a PNG from the command line, at the size and in the scheme you choose, with the errors the page reported.
121
+ - [`recipes/share-assets-across-scenarios.md`](recipes/share-assets-across-scenarios.md), about 5k characters: Reference one file from several scenarios without copying it, using a package-level `shared:` reference.
122
+ - [`recipes/share-logic-between-engine-and-ui.md`](recipes/share-logic-between-engine-and-ui.md), about 6k characters: Put a calculation in one file and use it from both your engine logic and your user interface, so a live preview cannot drift from the result the engine actually computes.
123
+ - [`recipes/show-all-teams-participants.md`](recipes/show-all-teams-participants.md), about 4k characters: Let a game UI read the participant roster of every team in a shared-state session, so it can render a directory of who is on each competing team.
124
+ - [`recipes/start-from-an-empty-package.md`](recipes/start-from-an-empty-package.md), about 6k characters: Build a game from nothing: a capability for its state, an engine that changes it each tick, and a game UI to show it.
125
+ - [`recipes/take-a-file-in-an-endpoint.md`](recipes/take-a-file-in-an-endpoint.md), about 4k characters: Let an endpoint accept a file, such as a team photo or a research PDF, from a game UI, a script calling the API, or an AI agent.
126
+ - [`recipes/test-a-multi-role-game.md`](recipes/test-a-multi-role-game.md), about 4k characters: Drive a game that needs several participants per team (for example a buyer and a seller who each act before a tick advances) from a single dev-server session, using the per-team participant roster.
127
+ - [`recipes/test-user-interface.md`](recipes/test-user-interface.md), about 5k characters: Write and run component tests for a user interface with Vitest, React Testing Library, and the SDK's render helpers.
128
+ - [`recipes/test-with-engine.md`](recipes/test-with-engine.md), about 5k characters: Test your whole game (engine, hooks, validators, endpoints, and completion) in one Node.js process, with no dev server, browser, or subprocess.
129
+ - [`recipes/upload-and-display-files.md`](recipes/upload-and-display-files.md), about 6k characters: Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
130
+ - [`recipes/use-request-play.md`](recipes/use-request-play.md), about 2k characters: Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
131
+ - [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
132
+ - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 4k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
133
+
134
+ ## API reference
135
+
136
+ - [`api/index.md`](api/index.md), about 7k characters: Every type, function, hook and component your game imports, one page per entry point.
137
+ - [`api/deck.md`](api/deck.md), about 8k characters: Every export of `@seriousgaming/deck`, with the declaration it is published with.
138
+ - [`api/sdk-commands.md`](api/sdk-commands.md), about 7k characters: What a client may ask a session to do.
139
+ - [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
140
+ - [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
141
+ - [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
142
+ - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
143
+ - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
144
+ - [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
145
+ - [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
@@ -129,5 +129,5 @@ Hold one line throughout: fill in the social context a solo run lacks, and suppr
129
129
  ## Related
130
130
 
131
131
  - [Engines guide, walkthroughs](../guides/engine.md#walkthroughs)
132
- - [Building user interfaces guide, walkthroughs](../guides/ui.md#walkthroughs)
132
+ - [Building user interfaces guide, walkthroughs](../guides/ui-participants.md#walkthroughs)
133
133
  - [Adapt a UI for observers](adapt-ui-for-observers.md)
@@ -70,5 +70,5 @@ An observer is a facilitator watching one team's live game UI without joining as
70
70
 
71
71
  ## Related
72
72
 
73
- - [User interfaces guide: observers](../guides/ui.md#observers)
73
+ - [User interfaces guide: observers](../guides/ui-participants.md#observers)
74
74
  - [Observe other teams' state](observe-other-teams-state.md)
@@ -28,6 +28,16 @@ A game holds at most one presentation. It is read-only: it reads every team's st
28
28
 
29
29
  ### 1. Create the presentation
30
30
 
31
+ The starter game already fills the slot, so in a package made with `new package` change its `reads` and `settings` instead, then rewrite its slides in step 2:
32
+
33
+ ```bash
34
+ pnpm run sdk update presentation --patch '[
35
+ { "op": "replace", "path": "/definition/reads", "value": ["results"] }
36
+ ]'
37
+ ```
38
+
39
+ In a package without one, create it:
40
+
31
41
  ```bash
32
42
  pnpm run sdk new presentation '{
33
43
  "definition": {
@@ -137,6 +147,7 @@ Open http://localhost:3000/presentation for the deck during the session, or http
137
147
 
138
148
  ## Related
139
149
 
150
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
140
151
  - [Presentation guide](../guides/presentation.md): the slot, the deck library, resume and export
141
152
  - [Create a facilitator guide](create-guide.md): the run sheet beside the deck
142
153
  - [Create a scenario](create-scenario.md): vary the deck through settings and assets
@@ -97,6 +97,7 @@ Describe every property in the settings schema: `title`, `description` with unit
97
97
 
98
98
  ## Related
99
99
 
100
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
100
101
  - [Create a setup screen](create-setup.md)
101
102
  - [Create a scenario](create-scenario.md)
102
103
  - [Scenarios guide](../guides/scenarios.md)
@@ -81,7 +81,7 @@ Build the facilitator's screen: every team's state side by side, with controls t
81
81
  }
82
82
  ```
83
83
 
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.
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-hooks.md) for roster control, timers, undo, and reset.
85
85
 
86
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
 
@@ -111,6 +111,7 @@ The session UI is the console at http://localhost:3000. Change a price on one te
111
111
 
112
112
  ## Related
113
113
 
114
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
114
115
  - [Session UI guide](../guides/session.md)
115
116
  - [Create a user interface](create-user-interface.md)
116
117
  - [Test a user interface](test-user-interface.md)
@@ -110,6 +110,7 @@ The configuration step exists only when the package has a `setup/setup.sdk.json`
110
110
 
111
111
  ## Related
112
112
 
113
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
113
114
  - [Create a scenario editor](create-scenario-editor.md)
114
115
  - [Use requestPlay in a setup screen](use-request-play.md)
115
116
  - [Create a settings resource](create-settings.md)
@@ -90,6 +90,7 @@ Open a team's participant view. It shows the current price and revenue, and **Ra
90
90
 
91
91
  ## Related
92
92
 
93
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
93
94
  - [User interfaces guide](../guides/ui.md): reading and writing state, ticks, participants, timers and theming
94
95
  - [Design state for concurrent writes](design-state-for-concurrent-writes.md)
95
96
  - [Use requestTick in a UI](use-request-tick.md)
@@ -104,6 +104,7 @@ Open http://localhost:3000, press the backtick key for the dev drawer, switch on
104
104
 
105
105
  ## Related
106
106
 
107
+ - [Designing screens](../guides/designing-screens.md): the brief to write before you build, and the check to run after
107
108
  - [Waiting room guide](../guides/waiting-room.md): held starts, join codes, roster, and layout
108
109
  - [Create a tick controller](create-tick-controller.md)
109
110
  - [Test a user interface](test-user-interface.md)
@@ -60,7 +60,7 @@ 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-ticks.md#awaiting-state-changes)
64
64
 
65
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
 
@@ -92,10 +92,10 @@ build is clean too.
92
92
  | Problem | Solution |
93
93
  | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
94
  | The error persists after the restart | Add the library that bundles React itself (for example `@react-three/fiber`) to `dedupe` |
95
- | The SDK warns about two Vite configs | Remove the `vite.config.ts` inside `ui/` and keep one at the project root; see [Customising Vite](../guides/ui.md#customising-vite-dev-and-build) |
95
+ | The SDK warns about two Vite configs | Remove the `vite.config.ts` inside `ui/` and keep one at the project root; see [Customising Vite](../guides/ui-styling.md#customising-vite-dev-and-build) |
96
96
  | A Vite option in your file has no effect | The SDK owns structural fields (`root`, `base`, build output, entry points); additive options such as `resolve.dedupe`, `resolve.alias`, `optimizeDeps`, and `plugins` merge in |
97
97
 
98
98
  ## Related
99
99
 
100
- - [Customising Vite](../guides/ui.md#customising-vite-dev-and-build): where the file goes and what merges
100
+ - [Customising Vite](../guides/ui-styling.md#customising-vite-dev-and-build): where the file goes and what merges
101
101
  - [User interfaces guide](../guides/ui.md)
@@ -2,6 +2,8 @@
2
2
 
3
3
  Each recipe is one task, start to finish: prerequisites, numbered steps, a way to check it worked, and fixes for what usually goes wrong. For the full reference on a resource type, see the [guides](../guides/index.md).
4
4
 
5
+ **Keywords:** recipes, how to, tasks, step by step, all recipes, recipe list
6
+
5
7
  ## Getting started
6
8
 
7
9
  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.
@@ -86,5 +88,6 @@ The full reference is the [Multi-team games](../guides/multi-team-games.md) guid
86
88
  - [Drive a game from the CLI](../cli-simulation-testing.md): configure, tick, patch, and read a session from the terminal
87
89
  - [Test a user interface](test-user-interface.md): write and run React component tests
88
90
  - [Test UIs end to end with Playwright](e2e-testing.md): browser tests against the dev server
91
+ - [Screenshot a surface](screenshot-a-surface.md): capture a screen at phone and desktop size, with the errors the page reported
89
92
  - [Test a whole game in-process](test-with-engine.md): whole games with `createTestSession`, for rules, flow, hooks, validators and completion
90
93
  - [Fix duplicate package errors in a UI](fix-duplicate-packages.md): resolve 'Invalid hook call' errors caused by two copies of React
@@ -0,0 +1,80 @@
1
+ # Screenshot a surface
2
+
3
+ Capture one of your game's screens as a PNG from the command line, at the size and in the scheme you choose, with the errors the page reported.
4
+
5
+ **Keywords:** screenshot, capture, PNG, image, phone, mobile, desktop, viewport, dark mode, colour scheme, brand, locale, visual check, layout, cut off, overflow, console errors, failed requests, Playwright, Chromium, BROWSER_MISSING, SURFACE_NOT_RENDERED
6
+
7
+ ## Prerequisites
8
+
9
+ - A game package with the surface you want to see, such as `ui/` for the participant's screen
10
+ - `@playwright/test` in the package's `devDependencies` and its Chromium installed. A package made with `sdk new package` has the dependency; install the browser once:
11
+
12
+ ```bash
13
+ pnpm exec playwright install chromium
14
+ ```
15
+
16
+ ## Steps
17
+
18
+ 1. Bring the session to the state you want to see. The capture shows the session as it stands, so tick, patch or configure it first:
19
+
20
+ ```bash
21
+ pnpm run sdk tick
22
+ ```
23
+
24
+ 2. Capture the screen at phone size. The path is the surface's URL path on the dev server: `/team/1/player/1` is the first participant of the first team, `/` the facilitator's session surface, and `/team/1/observe`, `/team/1/waiting-room`, `/setup`, `/presentation` and `/walkthrough` the others:
25
+
26
+ ```bash
27
+ pnpm run --silent sdk screenshot /team/1/player/1 --width 390 --height 844 --out phone.png --json
28
+ ```
29
+
30
+ 3. Capture it again at desktop size, and in dark mode if the screen supports it:
31
+
32
+ ```bash
33
+ pnpm run --silent sdk screenshot /team/1/player/1 --width 1280 --height 800 --scheme dark --out desktop.png --json
34
+ ```
35
+
36
+ 4. Open each PNG and look for text that is cut off, controls that overlap, and colours that are hard to read. Pass `--full-page` to capture the whole height of a screen that scrolls, rather than one viewport of it
37
+
38
+ 5. Read the lists in the result. `consoleErrors`, `failedRequests` and `uncaughtExceptions` hold what the page reported while it loaded, the surface's own frame included, so a missing image or a thrown error shows up even when the picture looks right:
39
+
40
+ ```json
41
+ {
42
+ "ok": true,
43
+ "command": "screenshot",
44
+ "data": {
45
+ "path": "/home/me/my-game/phone.png",
46
+ "url": "http://localhost:3000/team/1/player/1?bare",
47
+ "width": 390,
48
+ "height": 844,
49
+ "fullPage": false,
50
+ "server": "running",
51
+ "consoleErrors": [],
52
+ "failedRequests": [],
53
+ "uncaughtExceptions": []
54
+ },
55
+ "diagnostics": [],
56
+ "warnings": []
57
+ }
58
+ ```
59
+
60
+ 6. To see the screen in another language or brand, add `--locale <code>` (one of the game's `supportedLocales`) or `--brand <id>` (one the dev server offers). The locale is the session's, so a running dev server is switched to it for the capture and back afterwards
61
+
62
+ ## Verify
63
+
64
+ The command exits 0 and the PNG at `path` is `--width` pixels wide and `--height` pixels tall, or taller with `--full-page`. The capture waits for the surface to report its first paint, so it never shows the loading screen.
65
+
66
+ ## Troubleshooting
67
+
68
+ | Problem | Solution |
69
+ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
+ | `BROWSER_MISSING` (exit 5) | The package has no Playwright, or no Chromium for it. Run `pnpm add -D @playwright/test`, then `pnpm exec playwright install chromium` |
71
+ | `SURFACE_NOT_RENDERED` (exit 4) | The surface did not connect, or did not report its first paint before `--timeout` (30 seconds by default). Read `uncaughtExceptions` and `consoleErrors` in `error.details`: most often the UI threw while it first rendered |
72
+ | The screenshot shows the setup screen | The game has a `setup` slot and the session is still at its configuration step. Run `pnpm run sdk play`, then capture again |
73
+ | The screen shows an earlier state | No dev server was running, so the capture started a fresh session. Run `pnpm run sdk tick` (which leaves a server running) before capturing |
74
+ | `USAGE_BAD_FLAG` naming `--locale`/`--brand` | The game does not ship that locale, or the dev server offers no such brand: the message lists the ones it has |
75
+
76
+ ## Related
77
+
78
+ - [Test UIs end to end with Playwright](e2e-testing.md): assert on a screen rather than look at it
79
+ - [Drive a game from the CLI](../cli-simulation-testing.md): reach the state you want to capture
80
+ - [CLI reference](../cli-reference.md#screenshot-a-surface): every flag
@@ -47,5 +47,5 @@ Act as each role in its tab. Because each tab carries its own participant identi
47
47
 
48
48
  ## Related
49
49
 
50
- - [Accessing participant info](../guides/ui.md#accessing-participant-info)
50
+ - [Accessing participant info](../guides/ui-participants.md#accessing-participant-info)
51
51
  - [Test UIs end to end with Playwright](e2e-testing.md): drive several participants from a test
@@ -133,13 +133,13 @@ pnpm run sdk view
133
133
 
134
134
  ## Troubleshooting
135
135
 
136
- | Problem | Solution |
137
- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
138
- | `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts` |
139
- | `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4) |
140
- | The engine never sees the reference | Add `upload` to the engine's `reads` |
141
- | The PDF does not render | Match the `<embed>` type to the file; see [Supported file types](../guides/file-handling.md#supported-file-types) |
142
- | `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md) |
136
+ | Problem | Solution |
137
+ | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
138
+ | `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts` |
139
+ | `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4) |
140
+ | The engine never sees the reference | Add `upload` to the engine's `reads` |
141
+ | The PDF does not render | Match the `<embed>` type to the file; see [Media types](../guides/file-handling.md#media-types) |
142
+ | `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md) |
143
143
 
144
144
  ## Related
145
145
 
@@ -68,8 +68,8 @@ 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 `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.
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-ticks.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
72
72
 
73
73
  ## Related
74
74
 
75
- - [User interfaces guide: requesting a tick](../guides/ui.md#requesting-a-tick)
75
+ - [User interfaces guide: requesting a tick](../guides/ui-ticks.md#requesting-a-tick)