@seriousgaming/sdk-tools 1.4.0 → 1.6.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 (302) hide show
  1. package/dist/bundling/ui-bundler.d.ts +12 -0
  2. package/dist/cli-25RWY5BQ.js +41 -0
  3. package/dist/cli-272KBNJH.js +97 -0
  4. package/dist/cli-2BH7FX27.js +52 -0
  5. package/dist/cli-2GOFEW26.js +81 -0
  6. package/dist/cli-3E3MD5U4.js +21 -0
  7. package/dist/cli-3HE4AVZG.js +115 -0
  8. package/dist/cli-4AKVLEC4.js +1387 -0
  9. package/dist/cli-4BV45LBH.js +126 -0
  10. package/dist/cli-4LKXZQ2B.js +48 -0
  11. package/dist/cli-4UWFQNGF.js +54 -0
  12. package/dist/cli-4YB3ROVR.js +78 -0
  13. package/dist/cli-57RXC3HQ.js +36 -0
  14. package/dist/cli-5JEGTVTG.js +96 -0
  15. package/dist/cli-6AMT3BUO.js +97 -0
  16. package/dist/cli-6RRVEGFB.js +80 -0
  17. package/dist/cli-6WXLXJVX.js +36 -0
  18. package/dist/cli-7OGYADZ3.js +97 -0
  19. package/dist/cli-AK7OIPWY.js +229 -0
  20. package/dist/cli-B4TN6PJP.js +124 -0
  21. package/dist/cli-B6YHEKIJ.js +248 -0
  22. package/dist/cli-BPYMTOUL.js +89 -0
  23. package/dist/cli-BWX5E7TQ.js +23 -0
  24. package/dist/cli-BYJWFFCF.js +37 -0
  25. package/dist/cli-C3NVCKO6.js +43 -0
  26. package/dist/cli-C47GJATR.js +42 -0
  27. package/dist/cli-C5QOJJWX.js +46 -0
  28. package/dist/cli-C6TH5S7K.js +6417 -0
  29. package/dist/cli-DL2CVMRF.js +89 -0
  30. package/dist/cli-DMW2OQIJ.js +76 -0
  31. package/dist/cli-DZW3XD5F.js +143 -0
  32. package/dist/cli-E2NLWIFE.js +1331 -0
  33. package/dist/cli-E33CJRRQ.js +36 -0
  34. package/dist/cli-E6DJIMYD.js +142 -0
  35. package/dist/cli-EEFJKIGL.js +151 -0
  36. package/dist/cli-EVFS55WN.js +185 -0
  37. package/dist/cli-F2D4GGUA.js +549 -0
  38. package/dist/cli-FBTRTIZJ.js +226 -0
  39. package/dist/cli-FWFRKQNE.js +11 -0
  40. package/dist/cli-FYINNRML.js +760 -0
  41. package/dist/cli-G522CPRL.js +88 -0
  42. package/dist/cli-G6KELFSX.js +2847 -0
  43. package/dist/cli-G6UE5NL4.js +90 -0
  44. package/dist/cli-GBFM76BF.js +16 -0
  45. package/dist/cli-GDQ6ILJY.js +101 -0
  46. package/dist/cli-GFBGYFYD.js +50 -0
  47. package/dist/cli-GGPDQNM3.js +35 -0
  48. package/dist/cli-GTSGLN3Z.js +307 -0
  49. package/dist/cli-GUXKQMJ7.js +13641 -0
  50. package/dist/cli-GXD36NF2.js +60 -0
  51. package/dist/cli-HCRTYQQS.js +16 -0
  52. package/dist/cli-HYY64SUD.js +185 -0
  53. package/dist/cli-I355WTAF.js +463 -0
  54. package/dist/cli-IDKYF5XB.js +59 -0
  55. package/dist/cli-ILKCQNM6.js +8 -0
  56. package/dist/cli-IRZ5KB7D.js +36 -0
  57. package/dist/cli-IUS2YCD3.js +31 -0
  58. package/dist/cli-J4DKUUTK.js +138 -0
  59. package/dist/cli-JFU22EJ2.js +187 -0
  60. package/dist/cli-JMZLT65J.js +226 -0
  61. package/dist/cli-JZM7XTNV.js +89 -0
  62. package/dist/cli-K2B6WHKA.js +81 -0
  63. package/dist/cli-KL3756X6.js +126 -0
  64. package/dist/cli-KNOOKGYW.js +88 -0
  65. package/dist/cli-LFGRFIEO.js +226 -0
  66. package/dist/cli-LFM7GJHI.js +0 -0
  67. package/dist/cli-LMDJCHHD.js +304 -0
  68. package/dist/cli-LXYPE3L5.js +99 -0
  69. package/dist/cli-M6BCQRID.js +153 -0
  70. package/dist/cli-MBNMPVDC.js +367 -0
  71. package/dist/cli-MJUYJIEP.js +13 -0
  72. package/dist/cli-MMN4BPO4.js +145 -0
  73. package/dist/cli-MYJGMA6U.js +40 -0
  74. package/dist/cli-N6H6T2E2.js +616 -0
  75. package/dist/cli-O5KP4OVN.js +61 -0
  76. package/dist/cli-O6PWMJTZ.js +25 -0
  77. package/dist/cli-ORIG557O.js +141 -0
  78. package/dist/cli-PFFCNGHI.js +243 -0
  79. package/dist/cli-PNLYX6R6.js +131 -0
  80. package/dist/cli-PQBXVLEU.js +649 -0
  81. package/dist/cli-PTT5RGKO.js +62 -0
  82. package/dist/cli-Q2XJF5AS.js +127 -0
  83. package/dist/cli-QEVDDBNO.js +60 -0
  84. package/dist/cli-QEVE5HUM.js +167 -0
  85. package/dist/cli-QUIJCBYB.js +391 -0
  86. package/dist/cli-QUNIRH7A.js +57 -0
  87. package/dist/cli-QVASWX2A.js +187 -0
  88. package/dist/cli-QWQMPCL6.js +253 -0
  89. package/dist/cli-R4PCG5YX.js +131 -0
  90. package/dist/cli-RA673NGF.js +53 -0
  91. package/dist/cli-RN6IWTL2.js +36 -0
  92. package/dist/cli-ROT3DRKU.js +145 -0
  93. package/dist/cli-RZITKPJX.js +367 -0
  94. package/dist/cli-S5IVGDDD.js +32 -0
  95. package/dist/cli-S5QDONIQ.js +218 -0
  96. package/dist/cli-SIPDUBFL.js +36 -0
  97. package/dist/cli-SMFSZF2G.js +4009 -0
  98. package/dist/cli-SRHBXZCN.js +159 -0
  99. package/dist/cli-TCY5LJ7E.js +88 -0
  100. package/dist/cli-TDSQSCX4.js +131 -0
  101. package/dist/cli-TIDQ4WUE.js +257 -0
  102. package/dist/cli-TLLA6KAP.js +79 -0
  103. package/dist/cli-TPU4TUR6.js +132 -0
  104. package/dist/cli-U2UE7I7J.js +30 -0
  105. package/dist/cli-UELGBQG7.js +101 -0
  106. package/dist/cli-UHSZBKYO.js +97 -0
  107. package/dist/cli-UJ4UCL2Z.js +38 -0
  108. package/dist/cli-UKQYZYFK.js +31 -0
  109. package/dist/cli-UMFFURZ7.js +81 -0
  110. package/dist/cli-UNAJ2OTE.js +15 -0
  111. package/dist/cli-UNJ5X6BU.js +89 -0
  112. package/dist/cli-UTJU4IYG.js +117 -0
  113. package/dist/cli-V4GHRWOV.js +1837 -0
  114. package/dist/cli-VCI3CG36.js +73 -0
  115. package/dist/cli-VCKOC2EV.js +256 -0
  116. package/dist/cli-VL2P354N.js +46 -0
  117. package/dist/cli-WAE26SVW.js +72 -0
  118. package/dist/cli-WOGIAU2E.js +100 -0
  119. package/dist/cli-WU43JT4T.js +52 -0
  120. package/dist/cli-XCO2VQOH.js +122 -0
  121. package/dist/cli-XSVGKI3R.js +39 -0
  122. package/dist/cli-YOTGR3NB.js +82 -0
  123. package/dist/cli-YVVXUD2G.js +197 -0
  124. package/dist/cli-ZISJ36MM.js +89 -0
  125. package/dist/cli-ZTWOE3ZT.js +65 -0
  126. package/dist/cli-ZVSFYDPQ.js +205 -0
  127. package/dist/cli-ZWPYIXNI.js +68 -0
  128. package/dist/cli.js +171 -42385
  129. package/dist/client/build-surfaces.d.ts +33 -0
  130. package/dist/client/dev-server.d.ts +6 -0
  131. package/dist/client/index.d.ts +1 -0
  132. package/dist/client/playwright.d.ts +62 -0
  133. package/dist/client.js +339 -56
  134. package/dist/core/session.d.ts +15 -1
  135. package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-CuMOOH9m.js} +21 -21
  136. package/dist/dev/console/index.html +1 -1
  137. package/dist/dev/public-origins.d.ts +61 -0
  138. package/dist/dev/shell.d.ts +51 -4
  139. package/dist/dev/surfaces.d.ts +7 -0
  140. package/dist/docs/ai-agents.md +5 -0
  141. package/dist/docs/api/index.md +14 -12
  142. package/dist/docs/api/sdk-tools-client.md +29 -0
  143. package/dist/docs/api/sdk-tools-playwright.md +104 -0
  144. package/dist/docs/changelog-0.x.md +2 -2
  145. package/dist/docs/changelog.md +56 -4
  146. package/dist/docs/cli-and-dev-server.md +79 -0
  147. package/dist/docs/cli-error-codes.md +39 -36
  148. package/dist/docs/cli-reference.md +93 -32
  149. package/dist/docs/environment-variables.md +16 -5
  150. package/dist/docs/guides/ai-facilitation.md +2 -0
  151. package/dist/docs/guides/capabilities.md +2 -0
  152. package/dist/docs/guides/designing-a-game.md +31 -4
  153. package/dist/docs/guides/designing-screens.md +133 -0
  154. package/dist/docs/guides/endpoints.md +2 -0
  155. package/dist/docs/guides/engine-testing.md +5 -1
  156. package/dist/docs/guides/engine.md +2 -0
  157. package/dist/docs/guides/file-handling.md +3 -1
  158. package/dist/docs/guides/games.md +3 -1
  159. package/dist/docs/guides/global-settings.md +2 -0
  160. package/dist/docs/guides/guide.md +2 -0
  161. package/dist/docs/guides/hooks.md +2 -0
  162. package/dist/docs/guides/index.md +9 -0
  163. package/dist/docs/guides/internationalization.md +2 -0
  164. package/dist/docs/guides/llm-integration.md +4 -2
  165. package/dist/docs/guides/multi-team-games.md +3 -1
  166. package/dist/docs/guides/patterns.md +2 -0
  167. package/dist/docs/guides/presentation.md +1 -1
  168. package/dist/docs/guides/production-constraints.md +2 -0
  169. package/dist/docs/guides/scenario-editor.md +2 -0
  170. package/dist/docs/guides/scenarios.md +6 -2
  171. package/dist/docs/guides/session-game-flow.md +365 -0
  172. package/dist/docs/guides/session-hooks.md +205 -0
  173. package/dist/docs/guides/session.md +27 -565
  174. package/dist/docs/guides/settings.md +2 -0
  175. package/dist/docs/guides/setup.md +3 -1
  176. package/dist/docs/guides/speech-generation.md +2 -0
  177. package/dist/docs/guides/starter-game.md +63 -23
  178. package/dist/docs/guides/testing.md +35 -18
  179. package/dist/docs/guides/tick-controller.md +3 -1
  180. package/dist/docs/guides/type-safety.md +2 -0
  181. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  182. package/dist/docs/guides/ui-participants.md +281 -0
  183. package/dist/docs/guides/ui-styling.md +263 -0
  184. package/dist/docs/guides/ui-ticks.md +247 -0
  185. package/dist/docs/guides/ui.md +11 -1092
  186. package/dist/docs/guides/upgrading.md +2 -0
  187. package/dist/docs/guides/validators.md +2 -0
  188. package/dist/docs/guides/waiting-room.md +1 -1
  189. package/dist/docs/index.md +2 -1
  190. package/dist/docs/page-index.md +146 -0
  191. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  192. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  193. package/dist/docs/recipes/create-presentation.md +11 -0
  194. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  195. package/dist/docs/recipes/create-session-ui.md +2 -1
  196. package/dist/docs/recipes/create-setup.md +1 -0
  197. package/dist/docs/recipes/create-user-interface.md +1 -0
  198. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  199. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  200. package/dist/docs/recipes/e2e-testing.md +19 -20
  201. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  202. package/dist/docs/recipes/index.md +3 -0
  203. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  204. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  205. package/dist/docs/recipes/use-request-tick.md +2 -2
  206. package/dist/execution/config-resolver.d.ts +4 -1
  207. package/dist/playwright.js +32232 -0
  208. package/dist/runtime/manifest-version.d.ts +1 -1
  209. package/dist/runtime.js +1 -1
  210. package/dist/templates/package/CLAUDE.md.template +14 -5
  211. package/dist/templates/package/DESIGN.md.liquid +39 -7
  212. package/dist/templates/package/README.md.liquid +1 -1
  213. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  214. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  215. package/dist/templates/package/global-setup.ts.template +7 -18
  216. package/dist/templates/package/playwright.config.ts.liquid +8 -11
  217. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  218. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  219. package/dist/templates/starter-game/package.json +2 -0
  220. package/dist/templates/starter-game/playwright.config.ts +8 -11
  221. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  222. package/dist/templates/starter-game/presentation/index.html +20 -0
  223. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  224. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  225. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  226. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  227. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  228. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  229. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  230. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  231. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  232. package/dist/templates/starter-game/presentation/types.ts +94 -0
  233. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  234. package/dist/templates/starter-game/session/defaults.ts +6 -0
  235. package/dist/templates/starter-game/session/index.html +1 -1
  236. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  237. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  238. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  239. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  240. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  241. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  242. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  243. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  244. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  245. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  246. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  247. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  248. package/dist/templates/starter-game/session/src/status.ts +28 -0
  249. package/dist/templates/starter-game/session/types.ts +8 -2
  250. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  251. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  252. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  253. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  254. package/dist/templates/starter-game/shared/days.ts +11 -0
  255. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  256. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  257. package/dist/templates/starter-game/testing/e2e/game.spec.ts +43 -9
  258. package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
  259. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  260. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  261. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  262. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  263. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  264. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  265. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  266. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  267. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  268. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  269. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  270. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  271. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  272. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  273. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  274. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  275. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  276. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  277. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  278. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  279. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  280. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  281. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  282. package/dist/templates/starter-game/ui/types.ts +6 -0
  283. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  284. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  285. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  286. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  287. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  288. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  289. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  290. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  291. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  292. package/dist/utils/error-codes.d.ts +12 -0
  293. package/dist/utils/prompt.d.ts +5 -5
  294. package/dist/utils/resource-scan.d.ts +39 -0
  295. package/package.json +15 -4
  296. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  297. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  298. package/dist/templates/starter-game/session/src/format.ts +0 -8
  299. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  300. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  301. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  302. 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.
@@ -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,146 @@
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 15k 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 161k 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 10k 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 13k 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 34k 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 6k 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 8k 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-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
144
+ - [`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.
145
+ - [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
146
+ - [`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
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Test your game's screens in a real browser against an isolated dev server.
4
4
 
5
- **Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer
5
+ **Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer, fullyParallel, workers, buildSurfaces
6
6
 
7
7
  ## Prerequisites
8
8
 
@@ -20,21 +20,10 @@ Test your game's screens in a real browser against an isolated dev server.
20
20
 
21
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
22
 
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:
23
+ 2. Create `testing/e2e/global-setup.ts`, which builds your surfaces once for the whole run and removes the build when it ends:
24
24
 
25
25
  ```typescript
26
- import { dirname } from 'path';
27
-
28
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
29
- import type { FullConfig } from '@playwright/test';
30
-
31
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
32
- const server = await startDevServer({
33
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
34
- });
35
- process.env.SERIOUSGAMING_DEV_URL = server.url;
36
- return () => server.stop();
37
- }
26
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
38
27
  ```
39
28
 
40
29
  3. Create `playwright.config.ts`, and add `"test:e2e": "playwright test"` to `package.json`:
@@ -45,17 +34,16 @@ Test your game's screens in a real browser against an isolated dev server.
45
34
  export default defineConfig({
46
35
  testDir: './testing/e2e',
47
36
  globalSetup: './testing/e2e/global-setup.ts',
48
- workers: 1,
49
- use: { baseURL: process.env.SERIOUSGAMING_DEV_URL },
37
+ fullyParallel: true,
50
38
  });
51
39
  ```
52
40
 
53
- One worker, because the tests share one session. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
41
+ Each Playwright worker starts its own isolated dev server, on free ports, and serves the surfaces the global setup built. Tests in different workers never share a session, so they run side by side. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
54
42
 
55
43
  4. Start each test from a fresh session, and open a surface with `?bare` so the page holds your game and none of the console:
56
44
 
57
45
  ```typescript
58
- import { expect, test } from '@playwright/test';
46
+ import { expect, test } from '@seriousgaming/sdk-tools/playwright';
59
47
  import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
60
48
 
61
49
  test.beforeEach(async () => {
@@ -70,6 +58,8 @@ Test your game's screens in a real browser against an isolated dev server.
70
58
  });
71
59
  ```
72
60
 
61
+ Import `test` from `@seriousgaming/sdk-tools/playwright`, not `@playwright/test`: it is what starts the worker's server and points `baseURL` and the `/e2e` helpers at it. Tests that land in the same worker share its session one after another, so `reinitialiseSession()` is still needed.
62
+
73
63
  `playerUrl(team, participant?)` is 1-based. `observeUrl`, `waitingRoomUrl`, `setupUrl`, and the other builders are in the [e2e API reference](../api/sdk-e2e.md#dev_server).
74
64
 
75
65
  5. Act through the game's own controls, or as the facilitator with `runCommand`, and read the result with `getState`:
@@ -91,7 +81,15 @@ Test your game's screens in a real browser against an isolated dev server.
91
81
 
92
82
  The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
93
83
 
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)`
84
+ 7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, give the spec's servers a fake clock and move time with `advanceClock(ms)`:
85
+
86
+ ```typescript
87
+ import { FakeClock } from '@seriousgaming/sdk-tools/client';
88
+
89
+ test.use({ devServerOptions: { clock: new FakeClock(Date.now()) } });
90
+ ```
91
+
92
+ `devServerOptions` takes what `startDevServer` does (`teams`, `participants`, `scenarioId`, `locale`, `callbacks`), for every server the file's workers start
95
93
 
96
94
  ## Verify
97
95
 
@@ -105,7 +103,8 @@ Every spec passes. Add `--headed` to watch, or `--debug` to step through.
105
103
 
106
104
  | Problem | Solution |
107
105
  | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
108
- | The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
106
+ | The run hangs after the last test | The server was started with `webServer`; use the `test` from `@seriousgaming/sdk-tools/playwright` instead (step 4) |
107
+ | A change to a surface does not show | The run serves the build its global setup made at the start; run the suite again |
109
108
  | Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
110
109
  | Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
111
110
  | The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |
@@ -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
@@ -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)
@@ -50,7 +50,10 @@ export declare class ConfigResolver {
50
50
  /**
51
51
  * Resolve the active scenario from a provided ID or the game's default.
52
52
  * Returns null if the game declares no scenarios, or when null is passed
53
- * to explicitly opt out of the default scenario (the settings defaults).
53
+ * for a game with no default scenario (the settings defaults).
54
+ *
55
+ * A game that declares a default never runs on none (§6.7), so null is
56
+ * refused for it, naming the default.
54
57
  */
55
58
  resolveScenario(scenarioId?: string | null): SDKScenario | null;
56
59
  /**