@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
@@ -6,6 +6,8 @@ This guide covers declaring them, reading them from logic and surfaces, overridi
6
6
 
7
7
  Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
8
8
 
9
+ **Keywords:** settings, parameters, settingsSchema, defaults, read settings, override settings, configure, scenario settings, locked settings, game settings, hidden values, sdk configure
10
+
9
11
  ## Overview
10
12
 
11
13
  A settings resource is a schema and nothing else. It lives at `settings/<identifier>/settings.sdk.json`, and a package may hold any number of them, as it does capabilities.
@@ -4,6 +4,8 @@ The `setup` slot holds the small form a facilitator fills in when they create a
4
4
 
5
5
  This guide covers creating one, building its form, and how it behaves in the dev server.
6
6
 
7
+ **Keywords:** setup screen, setup form, session creation, configures, per-session settings, number of rounds, requestPlay, start play, facilitator form
8
+
7
9
  ## What setup is
8
10
 
9
11
  A game holds at most one setup screen, at `setup/`. It is a slot, like `session` or `waiting_room`, so it carries no name of its own: the slot is its identifier.
@@ -143,7 +145,7 @@ An endpoint called from setup sees `caller.role` as `'facilitator'`.
143
145
  Setup is embedded in the host's page, not a page of its own:
144
146
 
145
147
  - **Leave the ground to the host.** Do not paint a page background. MUI's `CssBaseline` paints the body, so override it with `<GlobalStyles styles={{ body: { backgroundColor: 'transparent' } }} />`
146
- - **Prefer full-screen dialogs.** A centred modal inside an iframe is centred within the frame
148
+ - **Avoid dialogs with a backdrop.** A modal inside an iframe darkens only the frame, not the host's bar above it. Use a side panel, a confirmation beside the button that asked, or full screen
147
149
  - **Do not reproduce host chrome.** The language picker, the theme control, and the Play action live outside your iframe
148
150
 
149
151
  The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
@@ -6,6 +6,8 @@ The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. E
6
6
 
7
7
  The dev server ships with one provider adapter (ElevenLabs). Additional providers (OpenAI, Google Cloud, Azure, AWS Polly) will land behind a future `TTS_PROVIDER` env var without breaking changes to game code.
8
8
 
9
+ **Keywords:** speech, text-to-speech, TTS, generateSpeech, voice, voice presets, audio, ElevenLabs, ELEVENLABS_API_KEY, narration
10
+
9
11
  ## Overview
10
12
 
11
13
  `generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
@@ -13,7 +13,8 @@ Most of the starter game is ordinary, but four decisions in it are the ones a fi
13
13
  - **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and a hook puts each participant in charge of one item, so two people changing two numbers write two different keys
14
14
  - **A validator on the one thing they share.** Two changes can each fit while the merged plan busts the stall's capacity. No shape of state prevents that, so `validators/capacity` checks the merged result
15
15
  - **Every write awaited.** The game UI reports a refused write to the participant who made it, instead of showing a decision the game never received
16
- - **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready, and the facilitator watches and can undo
16
+ - **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready. The facilitator does not run the day; they hold the room at a day with a limit a validator enforces, watch, and can undo
17
+ - **Screens designed for where they are used.** Each screen leads with its one decision, works at phone size, uses the host's colours and an icon set rather than drawn icons, and asks 'are you sure?' beside the button rather than in a dialog. See [Designing screens](./designing-screens.md)
17
18
 
18
19
  [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) explains the first two in full.
19
20
 
@@ -35,13 +36,14 @@ See [Shaping games](./games.md).
35
36
 
36
37
  Each directory is one capability, a named slice of the game's state with a JSON Schema for its variables. There is no logic here.
37
38
 
38
- | Capability | Holds |
39
- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
40
- | `plan` | How many of each item to make today, keyed by item. The one capability participants write |
41
- | `weather` | Today's forecast and roughly how many people will want each item |
42
- | `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar |
43
- | `roles` | Which item each participant looks after, keyed by participant id |
44
- | `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
39
+ | Capability | Holds |
40
+ | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `plan` | How many of each item to make today, keyed by item. The one capability participants write |
42
+ | `weather` | Today's forecast and roughly how many people will want each item |
43
+ | `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar |
44
+ | `roles` | Which item each participant looks after, keyed by participant id |
45
+ | `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
46
+ | `pacing` | `LastOpenDay`, the last day a stall may open. `shared` scope, written only by the facilitator's screen; the default opens all ten |
45
47
 
46
48
  See [Capabilities](./capabilities.md).
47
49
 
@@ -56,7 +58,7 @@ Each directory is one settings resource: read-only parameters, every one with a
56
58
  | `menu` | `Capacity` (120) and the `Menu`, each item's name, cost, and price | The engine, every surface, the hook, and the validator |
57
59
  | `engine` | `UsualDemand` for each item, `SunnyPull`, `RainyPull`, and `Variation`. Only the engine reads it, so no participant's browser ever holds the demand | The engine |
58
60
  | `ui` | `Step` and `CurrencySymbol` | The game UI |
59
- | `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI |
61
+ | `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI and the presentation |
60
62
 
61
63
  See [Settings](./settings.md).
62
64
 
@@ -84,39 +86,77 @@ See [Hooks](./hooks.md).
84
86
 
85
87
  A validator that sees every change a UI makes to the plan before it is applied. It reads the `menu` settings, and refuses a plan that asks for more than the stall's capacity, a negative or fractional count, or an item not on the menu. It never changes state; it only says no, with a message the game UI shows.
86
88
 
89
+ ### `validators/daylimit/`
90
+
91
+ A validator with a `RequestTick` gate and no `UpdateData`. It refuses a stall's request to open a day after `pacing.LastOpenDay`, so the facilitator's hold is enforced on the server rather than only by a disabled button. Only a participant's request reaches it; the facilitator's own actions are never held.
92
+
87
93
  See [Validators](./validators.md).
88
94
 
89
95
  ## User interfaces
90
96
 
91
- Each is a small React app built with Vite and MUI, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font), and `src/i18n.ts` (every string on the screen).
97
+ Each is a small React app built with Vite, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), and `src/i18n.ts` (every string on the screen). The three screens people use are built with MUI and add `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font); the presentation is built with the SDK's deck library instead.
98
+
99
+ ### `shared/`
100
+
101
+ Code every screen uses, imported by relative path. It is not a slot, so the build and the scaffold treat it as ordinary source.
102
+
103
+ - `Awning.tsx`: the scalloped edge under each top bar, in the host's primary colour. It is the game's one drawn motif; everything else comes from the icon set
104
+ - `HostLogo.tsx`: the host's logo, with the variant chosen for the coloured bar, or nothing when the host sends none
105
+ - `StallIcons.tsx`: the Material icon and tint for each menu item and each kind of weather
106
+ - `format.ts`: money from pence, and counts. `days.ts`: the length of the week, read from the manifest's `maxTicks`
92
107
 
93
108
  ### `ui/`
94
109
 
95
- The game UI: what each participant sees.
110
+ The game UI: what each participant sees. It leads with today's decision and keeps the button that opens the stall in a bar at the bottom of the layout, never floating over it.
96
111
 
97
- - `src/App.tsx`: the layout, the facilitator's notice, and the one place a refused write is reported
98
- - `src/TodayPanel.tsx` and `src/MakeRow.tsx`: the controls for today's plan, one row per item, with the participant's own item marked
99
- - `src/DayBar.tsx`: the **Open the stall** button, which calls `requestTick` to play the team's day
100
- - `src/YesterdayPanel.tsx` and `src/HistoryPanel.tsx`: how yesterday went, and every day so far. The history table asks the host for the earlier days with `getPastState` and adds today's from live context, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
101
- - `src/HostLogo.tsx`: the host's logo in the top bar, from `useBrandLogo()`, or nothing when the host sends none
102
- - `src/writes.ts`: one mutation reporter every write goes through
103
- - `src/menu.ts`, `src/format.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, money formatting, the card layout, and a light or dark switch
104
- - `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
112
+ - `src/App.tsx`: the layout and the state it is in: before day 1 (`src/FirstDay.tsx`), mid-week, looking back at a past day (`src/PastDay.tsx`), and the week over (`src/WeekOver.tsx`)
113
+ - `src/Header.tsx`: the stall's name, the item the participant looks after, and a timeline of the days, where a day already played opens that day
114
+ - `src/WeatherCard.tsx`, `src/TodayPanel.tsx` and `src/MakeRow.tsx`: today's forecast and the controls for the plan, one row per item, with the participant's own item marked
115
+ - `src/DayBar.tsx`: the bottom bar. **Open the stall for day N** calls `requestTick`; when the facilitator's limit holds the stall it is disabled and says so
116
+ - `src/YesterdayPanel.tsx`, `src/Lesson.tsx` and `src/DaysTable.tsx`: yesterday as one profit figure and one lesson, and every day so far. Earlier days come from the host with `usePastState`, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
117
+ - `src/Notices.tsx` and `src/writes.ts`: the facilitator's notice, and the one mutation reporter every write goes through, so a refusal reaches the person who made it
118
+ - `src/menu.ts`, `src/days.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, day helpers, the card layout, and a light or dark switch
119
+ - `ui.sdk.json`: reads every capability it shows, `pacing` included, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
105
120
 
106
121
  See [Building user interfaces](./ui.md).
107
122
 
108
123
  ### `session/`
109
124
 
110
- The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It shows what each stall is making and whether anyone has changed it today, links into any stall to observe or join it (`src/TeamDoor.tsx`), writes the shared `briefing`, and toggles the waiting room and the facilitator guide through the host. `ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
125
+ The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It follows what most facilitator screens need, and leaves out what only some games do:
126
+
127
+ - `src/SessionBar.tsx`: one line across the top. The day limit, which writes `pacing.LastOpenDay`, the waiting room, and the facilitator guide and slides when the host offers them
128
+ - `src/StallCard.tsx` and `src/status.ts`: a card per stall with the day it is on, who is connected, what is in the jar, and links to observe it or copy its join link
129
+ - `src/ManagePanel.tsx` and `src/SidePanel.tsx`: a panel beside the cards, with no backdrop, to rename a stall, move a person, or undo a day, confirmed in place
130
+ - `src/Results.tsx`: the room's averages and range above a sortable table, any day played so far, and full screen for the projector
131
+ - `src/JoinCodes.tsx`: each stall's join link in large type, one stall at a time, for the room to read
132
+ - `src/SessionPanels.tsx`: the notice to the room (the shared `briefing`) and starting the session again
133
+
134
+ `ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
111
135
 
112
136
  See [Building session UIs](./session.md).
113
137
 
114
138
  ### `waiting_room/`
115
139
 
116
- The screen participants see while the session is held. It tells a held start ('Nearly opening time') from a pause part-way through, shows who is on the team, and lets the team name its stall.
140
+ The screen participants see while the session is held. It tells a held start ('Your stall opens soon') from a pause part-way through, shows who is on the team, lets the team name its stall, and copies the join link for anyone else joining.
117
141
 
118
142
  See [Building waiting room UIs](./waiting-room.md).
119
143
 
144
+ ### `presentation/`
145
+
146
+ The facilitator's slide deck, which they project for the room. It is read-only, and it renders with or without a session, so a facilitator can rehearse it or export it before the day.
147
+
148
+ - `src/Slides.tsx`: a title slide, one slide a day with the forecast and how the room did the day before, and a results slide for the room. The projector shows the room, never a stall by name: each stall's figures are in the speaker notes
149
+ - `src/stalls.ts`: the room's figures, kept apart from the slides so `src/stalls.test.ts` can test them without a deck. The stalls run their own days, so a day's figures count only the stalls that have played it, read through `usePastState`
150
+ - `src/Band.tsx` and `src/WeatherIcon.tsx`: the awning and the weather icon in the deck's own colours, since a deck has no MUI theme
151
+ - `src/App.tsx`: the `Deck`, with the host's theme as its colours, and opening on the day the room has reached
152
+ - `presentation.sdk.json`: reads `plan`, `weather` and `results`, and the `session` settings for the currency symbol
153
+
154
+ The dev server shows it at `/presentation`, and at `/presentation?preview` with no session.
155
+
156
+ See [Building presentations](./presentation.md).
157
+
158
+ The starter has no `setup/` or `scenario_editor/`, to keep it a quick first read. `examples/factory` in the SDK repository has both, and [Building setup screens](./setup.md) and [Building scenario editors](./scenario-editor.md) cover them.
159
+
120
160
  ## Content
121
161
 
122
162
  ### `scenarios/`
@@ -142,7 +182,7 @@ Whole-game tests that play several days in-process with `createTestSession`: no
142
182
 
143
183
  ### `testing/e2e/`
144
184
 
145
- Playwright tests against a real dev server, which `testing/e2e/global-setup.ts` starts on free ports, beside any you have running. Run them with `pnpm test:e2e`. See [Test UIs end to end with Playwright](../recipes/e2e-testing.md).
185
+ Playwright tests against real dev servers, one for each worker, on free ports beside any you have running. `testing/e2e/global-setup.ts` builds the surfaces once for them all. Run them with `pnpm test:e2e`. See [Test UIs end to end with Playwright](../recipes/e2e-testing.md).
146
186
 
147
187
  The unit and component tests sit beside the code they test (`*.test.ts`, `*.test.tsx`) and run with `pnpm test:run`.
148
188
 
@@ -155,7 +195,7 @@ These are written by `new package` for every package, starter game or not:
155
195
  | `package.json` | Dependencies, and the scripts: `sdk`, `generate`, `build`, `test:run`, `test:engine`, `test:e2e`, `typecheck`, `lint` |
156
196
  | `tsconfig.json`, `globals.d.ts` | TypeScript settings, and declarations for the font imports |
157
197
  | `vite.config.ts`, `vitest.config.ts`, `test-setup.ts` | Build and component-test settings, including the single copy of React and the SDK every UI needs |
158
- | `vitest.engine.config.ts`, `playwright.config.ts` | Settings for the whole-game and browser test suites, and `testing/e2e/global-setup.ts`, which starts the browser suite's server |
198
+ | `vitest.engine.config.ts`, `playwright.config.ts` | Settings for the whole-game and browser test suites, and `testing/e2e/global-setup.ts`, which builds the browser suite's surfaces |
159
199
  | `pnpm-workspace.yaml` | Dependency overrides and install-script decisions the SDK tooling needs |
160
200
  | `.oxlintrc.json`, `.oxfmtrc.json` | Lint and format settings |
161
201
  | `README.md`, `DESIGN.md` | A readme, and prompts for writing down your game's design as you build it |
@@ -2,6 +2,8 @@
2
2
 
3
3
  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.
4
4
 
5
+ **Keywords:** testing, unit tests, UI tests, Vitest, React Testing Library, renderUserInterface, createMock, test Run, test Init, Playwright, jsdom, test hooks
6
+
5
7
  ## Testing engine logic
6
8
 
7
9
  ### Starting from the generated defaults
@@ -516,7 +518,7 @@ Unit and integration tests cover logic and components in isolation. Browser E2E
516
518
  The SDK provides selectors and helpers via a dedicated subpath export with no Playwright dependency of its own:
517
519
 
518
520
  ```typescript
519
- import { expect, test } from '@playwright/test';
521
+ import { expect, test } from '@seriousgaming/sdk-tools/playwright';
520
522
  import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
521
523
 
522
524
  test.beforeEach(async () => {
@@ -543,38 +545,53 @@ makes the 'Try again' path your UI offers reachable. `waitForState` waits for
543
545
  something that happens after its command answers, and `advanceClock` moves the
544
546
  time of a server started with a `FakeClock` on, so automatic ticks are tested without waiting.
545
547
 
546
- When you create a project with `sdk new package`, a `playwright.config.ts`, the global setup that starts its dev server (`testing/e2e/global-setup.ts`, below) and a `testing/e2e/game.spec.ts` starter are generated automatically.
548
+ When you create a project with `sdk new package`, a `playwright.config.ts`, the global setup that builds its surfaces (`testing/e2e/global-setup.ts`, below) and a `testing/e2e/game.spec.ts` starter are generated automatically.
547
549
 
548
550
  ### A dev server for browser tests
549
551
 
550
- `startDevServer` starts the dev server in your test runner's process, isolated from the one you are working in, and resolves once it answers. It is what `sdk dev --isolated --port auto` runs, without spawning the CLI and parsing its output:
552
+ A dev server holds one session, so tests sharing one server have to run one at a time. The `test` exported by `@seriousgaming/sdk-tools/playwright` starts an isolated dev server for each Playwright worker instead, so tests in different workers never share a session and the suite runs in parallel:
551
553
 
552
554
  - It takes free ports, so it starts beside your own dev server rather than asking you to stop it
553
555
  - It writes no lock file, so `sdk tick` in your terminal still reaches your own server
554
556
  - It reads configuration from the package alone, ignoring what you last ran `sdk configure` with
555
- - Uploads go to a temporary directory, removed by `stop()`
557
+ - Uploads go to a temporary directory, removed when the worker ends
558
+
559
+ It points `baseURL` and the `@seriousgaming/sdk/e2e` helpers at the worker's server, so a test passes them no options. Tests that land in the same worker share its server one after another, which is why each spec still calls `reinitialiseSession()` in `beforeEach`.
556
560
 
557
561
  ```typescript
558
- // testing/e2e/global-setup.ts, as the scaffold writes it
559
- import { dirname } from 'path';
562
+ // playwright.config.ts, as the scaffold writes it
563
+ import { defineConfig } from '@playwright/test';
560
564
 
561
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
562
- import type { FullConfig } from '@playwright/test';
565
+ export default defineConfig({
566
+ testDir: './testing/e2e',
567
+ globalSetup: './testing/e2e/global-setup.ts',
568
+ fullyParallel: true,
569
+ });
570
+ ```
563
571
 
564
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
565
- const server = await startDevServer({
566
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
567
- });
568
- process.env.SERIOUSGAMING_DEV_URL = server.url;
569
- return () => server.stop();
570
- }
572
+ ```typescript
573
+ // testing/e2e/global-setup.ts
574
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
571
575
  ```
572
576
 
573
- `playwright.config.ts` names it as `globalSetup` and sets `use.baseURL` to `process.env.SERIOUSGAMING_DEV_URL`, which each worker reads after the setup has run. Stopping the server is a call in Playwright's own process, so the run ends when its tests do; a `webServer` running `pnpm run sdk dev` is stopped through `pnpm`, never reaches the server, and hangs.
577
+ The global setup builds the package's surfaces once, before any test runs, and every worker's server serves that build as files. Without it, each server would compile the same surfaces through Vite the first time a page asks for them. The build is removed when the run ends, and a change you make to a surface during a run is not seen until the next one. To serve the output of your own `pnpm run sdk build` and build nothing, set `SERIOUSGAMING_BUILT_SURFACES=dist`.
578
+
579
+ Set the servers' options with `devServerOptions`, in the config's `use` for every test or with `test.use` for one file. It takes `teams`, `participants`, `scenarioId`, `locale`, `clock` (a `FakeClock`) and `callbacks`, as [`createTestSession`](./engine-testing.md) does:
580
+
581
+ ```typescript
582
+ import { FakeClock } from '@seriousgaming/sdk-tools/client';
583
+ import { test } from '@seriousgaming/sdk-tools/playwright';
584
+
585
+ test.use({ devServerOptions: { clock: new FakeClock(Date.now()) } });
586
+ ```
587
+
588
+ #### Starting a server yourself
589
+
590
+ `startDevServer` from `@seriousgaming/sdk-tools/client` is what the fixture runs, for a recording script or another test runner. It is what `sdk dev --isolated --port auto` runs, without spawning the CLI and parsing its output, and resolves once the server answers. It returns `{ url, assetUrl, stop() }`: `url` is the console and API, and `assetUrl` is where game surfaces are served from. Pass `{ url: server.url }` to the `@seriousgaming/sdk/e2e` helpers, or set `SERIOUSGAMING_DEV_URL` to it, which also sends CLI commands there. Always call `stop()`: the server holds its ports and a file watcher open until then.
574
591
 
575
- It returns `{ url, assetUrl, stop() }`: `url` is the console and API, and `assetUrl` is where game surfaces are served from. The `@seriousgaming/sdk/e2e` helpers address the server `SERIOUSGAMING_DEV_URL` names, so a test passes them no options; pass `{ url: server.url }` where you hold the server yourself. It also takes `teams`, `participants`, `scenarioId`, `locale`, `clock` (a `FakeClock`) and `callbacks`, as [`createTestSession`](./engine-testing.md) does. Always call `stop()`: the server holds its ports and a file watcher open until then.
592
+ `buildSurfaces({ packagePath })` builds the surfaces into a temporary directory and returns `{ directory, remove() }`; pass `directory` to `startDevServer` as `builtSurfaces`. `sdk dev --built-surfaces <DIR>` does the same from the command line.
576
593
 
577
- To drive it from the CLI as well, set `SERIOUSGAMING_DEV_URL` to its `url`.
594
+ Do not start the server with Playwright's `webServer` running `pnpm run sdk dev`: Playwright stops it through `pnpm`, which never reaches the server, and the run hangs.
578
595
 
579
596
  See [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) for the full setup guide, all available selectors, and common patterns.
580
597
 
@@ -4,6 +4,8 @@ A tick controller makes ticks happen on their own, on a schedule your logic deci
4
4
 
5
5
  This guide explains the model, then is the reference for writing one.
6
6
 
7
+ **Keywords:** tick controller, timer, automatic ticks, interval, schedule, timed rounds, nextTickAt, game completion, complete, enabled, pause, extend a tick, cron
8
+
7
9
  ## The model
8
10
 
9
11
  By default, ticks are manual: a participant or facilitator presses a control, or a command is sent, to advance the game. That suits a game that moves one decision at a time. Some games need time to move on its own, or at a pace that depends on what is happening in the simulation. Some also need to end when a goal is met rather than after a fixed number of ticks.
@@ -410,7 +412,7 @@ pnpm run sdk timer extend 120 # two more minutes (the CLI takes second
410
412
  pnpm run sdk timer resume --team 2 # one team, in an independent game
411
413
  ```
412
414
 
413
- The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui.md#displaying-the-tick-timer) in the user interfaces guide.
415
+ The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui-ticks.md#displaying-the-tick-timer) in the user interfaces guide.
414
416
 
415
417
  ## Testing without waiting
416
418
 
@@ -4,6 +4,8 @@ The SDK generates TypeScript types from your schemas, so a misspelt variable fai
4
4
 
5
5
  This guide covers the rules that keep that guarantee, and the shortcuts that quietly break it.
6
6
 
7
+ **Keywords:** type safety, TypeScript, generated types, types.ts, sdk generate, any, type casts, JSON Schema types, schema constraints, strict types
8
+
7
9
  ## Core principle
8
10
 
9
11
  The Serious Gaming SDK uses TypeScript and JSON Schema to provide **end-to-end type safety**. When you define a capability's `variablesSchema` or a settings resource's `settingsSchema`, the SDK generates precise TypeScript types. Shortcuts and workarounds (using `any`, string-based JSON, etc.) break this guarantee and lead to runtime errors.