@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
@@ -26,7 +26,7 @@ export declare const MANIFEST_VERSION = 3;
26
26
  * section is stamped, it is the revision at the top of the appendix.
27
27
  * `spec-revision.test.ts` holds the two together.
28
28
  */
29
- export declare const SPEC_REVISION = "1.4";
29
+ export declare const SPEC_REVISION = "1.5";
30
30
  /**
31
31
  * Whether specification revision `revision` is later than `than`, both as
32
32
  * `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
package/dist/runtime.js CHANGED
@@ -305,7 +305,7 @@ function readTickControllerResult(label, result) {
305
305
 
306
306
  // cli/runtime/manifest-version.ts
307
307
  var MANIFEST_VERSION = 3;
308
- var SPEC_REVISION = "1.4";
308
+ var SPEC_REVISION = "1.5";
309
309
  function isLaterSpecRevision(revision, than) {
310
310
  const [major, minor] = revision.split(".").map(Number);
311
311
  const [thanMajor, thanMinor] = than.split(".").map(Number);
@@ -33,11 +33,16 @@ The SDK's documentation ships inside it, so it describes the version installed h
33
33
 
34
34
  ```bash
35
35
  pnpm run --silent sdk docs view # the documentation tree
36
+ pnpm run --silent sdk docs view page-index.md # every page: summary and length
36
37
  pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
37
38
  pnpm run --silent sdk docs view recipes/create-hook.md # one document
39
+ pnpm run --silent sdk docs view guides/session.md --outline # the headings of a page, with section lengths
40
+ pnpm run --silent sdk docs view guides/session.md --section 'Building the session UI' # one section
38
41
  pnpm run --silent sdk docs view cli-reference.md # every command and flag
39
42
  ```
40
43
 
44
+ Some guides run past 50,000 characters, more than one read may show you. Before reading a long page whole, find it in `page-index.md`, list its headings with `--outline`, and read the section you need with `--section`.
45
+
41
46
  The same files are on disk in `node_modules/@seriousgaming/sdk-tools/dist/docs/`, so you can search them with `grep -rn`. Start from `recipes/` for a task, `guides/` for a whole subject, and `concepts/` for the model.
42
47
 
43
48
  `pnpm run sdk docs export` copies them into the package, for a tool that cannot read `node_modules`. The same docs for the newest release are at https://sdk.seriousgaming.com/llms.txt; prefer the installed copy, which matches the version this package runs.
@@ -81,7 +86,7 @@ Data flows: surfaces write decisions with `setData`, a tick runs the engine, and
81
86
  ├── waiting_room/ # THE holding screen
82
87
  ├── setup/ # THE settings form at session creation (sdk new setup)
83
88
  ├── scenario_editor/ # THE scenario authoring screen (sdk new scenario_editor)
84
- ├── presentation/ # THE slide deck (sdk new presentation)
89
+ ├── presentation/ # THE slide deck the facilitator projects
85
90
  ├── tick_controller/ # THE timer, for timed rounds (sdk new tick_controller)
86
91
  ├── guide/ # THE facilitator guide (markdown per locale, plus assets)
87
92
  ├── capabilities/<name>/ # Data definitions
@@ -147,7 +152,7 @@ pnpm run generate # regenerate types after a hand edit (
147
152
  pnpm run build # validate, generate and bundle into dist/
148
153
  ```
149
154
 
150
- A slot command takes no identifier. The starter game fills every slot but `setup`, `scenario_editor`, `presentation` and `tick_controller`, and `new` refuses a filled slot. `update package` changes the manifest, which takes no identifier either.
155
+ A slot command takes no identifier. The starter game fills every slot but `setup`, `scenario_editor` and `tick_controller`, and `new` refuses a filled slot. `update package` changes the manifest, which takes no identifier either.
151
156
 
152
157
  ### Playing the game from the CLI
153
158
 
@@ -297,15 +302,16 @@ expect(session.team(0).context.results.Day).toBe(1);
297
302
 
298
303
  ### Testing a surface
299
304
 
300
- Every surface but the presentation scaffolds an `App.test.tsx`; the starter game's own tests are worked examples, and `pnpm run --silent sdk docs view guides/testing.md` is the reference.
305
+ Every surface but the presentation scaffolds an `App.test.tsx`; the starter game's own tests are worked examples, and `pnpm run --silent sdk docs view guides/testing.md` is the reference. A deck is tested through what its slides show, kept in plain functions (`presentation/src/stalls.test.ts`), and a Playwright spec that it opens.
301
306
 
302
307
  - **Render through the helper**: `renderUserInterface()` from `@seriousgaming/sdk/ui/testing` (or `renderSessionUserInterface<SessionData>()`, or `renderSettingsEditor()` for setup and the scenario editor). It supplies every provider the host does; pass `data`, `settings`, `callbacks` and the rest as options
303
308
  - **Never `vi.mock` the SDK, and never wire its providers by hand**
304
309
  - **Use `fireEvent.change` on controlled inputs**: the mock `setData` does not update the value between `userEvent.type` keystrokes
310
+ - **Look at every screen you change**, at phone and desktop size: `pnpm run --silent sdk screenshot /team/1/player/1 --width 390 --height 844 --json`, then again with `--width 1280 --height 800`. Open each PNG, fix text that is cut off, overlaps or is hard to read, and clear the `consoleErrors`, `failedRequests` and `uncaughtExceptions` it lists. Reach the state first with `sdk tick` (`recipes/screenshot-a-surface.md`)
305
311
 
306
312
  ## Presentations
307
313
 
308
- The `presentation/` slot holds the facilitator's slide deck, built with `@seriousgaming/deck` at the SDK's version. It reads every team's state and writes nothing. A facilitator exports it to PDF or PowerPoint and edits the copy, so:
314
+ The `presentation/` slot holds the facilitator's slide deck, built with `@seriousgaming/deck` at the SDK's version. It reads every team's state and writes nothing. The starter game's deck is a worked example: a title, a slide a day, and the results. A facilitator exports it to PDF or PowerPoint and edits the copy, so:
309
315
 
310
316
  - **Use the building blocks** (`Heading`, `Text`, `Bullets`, `Table`) for anything a facilitator might edit; anything else exports as a picture
311
317
  - **Render with `session === null`**, showing labelled sample figures where results would go
@@ -338,4 +344,7 @@ Upgrade only when the user asks, or when the changelog has a fix the task needs,
338
344
  | A hook reads empty data in a surface | Two copies of a package with React context: add it to `resolve.dedupe` in `vite.config.ts` |
339
345
  | Anything else | `pnpm run --silent sdk docs view troubleshooting.md` |
340
346
 
341
- Keep `DESIGN.md` up to date as the game changes.
347
+ Keep `DESIGN.md` up to date as the game changes, and hold to two habits for every surface:
348
+
349
+ - **Brief first.** Before you build or redesign a screen, write its brief under 'User interfaces' in `DESIGN.md`: who uses it and on what device, its one main action, its layout, the states it must handle, and the game's identity
350
+ - **Check, then go round once more.** Once it is built, check every screen at phone and desktop size against `pnpm run --silent sdk docs view guides/designing-screens.md`, fix what you find, and check again
@@ -100,17 +100,49 @@ What the model simplifies, and what it deliberately leaves out.
100
100
 
101
101
  ## User interfaces
102
102
 
103
- **`ui/`**: the participant surface. A game holds one, so several views are components inside it rather than separate resources.
103
+ Write each screen's brief here before you build it, then check the built screen against it. `pnpm run --silent sdk docs view guides/designing-screens.md` explains each prompt, and what to check afterwards.
104
104
 
105
- - **Reads / writes:** the capabilities it renders and the ones players change through it
106
- - **Views:** the tabs or panels, and what each is for
107
- - **How a player submits:** what they change, and what tells them a write did not land
105
+ ### Who plays, and on what
108
106
 
109
- **`session/`**: the facilitator surface. What the facilitator watches, and what they can change mid-session.
107
+ Who uses each screen, where they are, and the device in their hand.
110
108
 
111
- **`waiting_room/`**: what players see before the session opens, if the game has one.
109
+ **Example:** 'Participants on their own phones, standing in teams of three; the facilitator on a laptop that is also on the projector.'
112
110
 
113
- **`setup/`** and **`scenario_editor/`**: the form a facilitator fills in at session creation, and the screen for authoring lasting scenarios, if the game has them, and which settings resources each `configures`.
111
+ ### Tone
112
+
113
+ How the game should feel to play.
114
+
115
+ **Example:** 'Quick and light. A market stall, not a spreadsheet.'
116
+
117
+ ### Key screens
118
+
119
+ Each screen, the one main action on it, and what the person needs to see to take it. A game holds one participant surface, so several views are components inside `ui/` rather than separate resources. For `setup/` and `scenario_editor/`, if the game has them, also name the settings resources each `configures`.
120
+
121
+ **Example:**
122
+
123
+ - **`ui/`, today:** set how many of each item to make. Needs the forecast and what is left of capacity
124
+ - **`ui/`, history:** compare past days. No action; the profit for each day comes first
125
+ - **`session/`:** spot the stall that has stopped changing its numbers, and step in
126
+ - **`waiting_room/`:** name the team while everyone arrives
127
+ - **`presentation/`:** the briefing, a slide a round, and the results for the debrief
128
+
129
+ ### Layout
130
+
131
+ The pattern each screen follows, and how it changes between a phone and a laptop.
132
+
133
+ **Example:** 'One column on a phone, with the decision first and the open button pinned to the bottom. Two columns from tablet width, with today beside yesterday.'
134
+
135
+ ### States
136
+
137
+ What each screen shows before play, mid-round, while a round is processed, after the last round, when a write is refused, and to an observer.
138
+
139
+ **Example:** 'Before the first day, the results panel says when results will appear. A refused plan shows the validator's reason under the slider that was moved.'
140
+
141
+ ### Identity
142
+
143
+ What makes this game look like itself on top of the host's theme: the accent layer, iconography and imagery from the game's world, and the words it uses for things.
144
+
145
+ **Example:** 'Rounded, card-like panels; illustrated weather icons; "stall" for team and "open up" for submit.'
114
146
 
115
147
  ---
116
148
 
@@ -73,7 +73,7 @@ pnpm run build
73
73
  ├── session/ # THE session interface: the facilitator's screen
74
74
  ├── waiting_room/ # THE holding screen, shown before and between
75
75
  ├── guide/ # THE facilitator guide, as markdown chapters
76
- ├── presentation/ # THE slide deck the facilitator projects (add with `new presentation`)
76
+ ├── presentation/ # THE slide deck the facilitator projects
77
77
  ├── setup/ # THE form a facilitator fills in at session creation (`new setup`)
78
78
  ├── scenario_editor/ # THE editor for authoring lasting scenarios (`new scenario_editor`)
79
79
  ├── capabilities/ # The shape of the game's state
@@ -15,7 +15,7 @@ A user interface is a React app that reads game state and (optionally) sends dec
15
15
  ```
16
16
  2. **Confirm the capabilities exist.** A UI reads (and optionally writes) capabilities by their short names. Create any that are missing first.
17
17
  3. **Change or create the bundle.** The starter game already has a `ui/`, so change it with `pnpm run sdk update ui --patch '[...]'`; `new ui` refuses while `ui/` exists. In an empty package, `pnpm run sdk new ui '{ ... }'`. Declare every capability the UI shows in `reads`, and add `writes` only for the ones it sends back via `setData`. A UI receives exactly what it declares.
18
- 4. **Implement the components** under `ui/src/` (the entry component is `App.tsx`), with `useUserInterfaceData()` for `data`, `settings`, `setData` and `completedTicks`. Default to MUI; another library must integrate with `useUserInterfaceTheme` so dark mode and colour palettes work, and text on a theme colour uses that colour's `contrastText`. Remember a viewer's own choices with `useViewerStorage`, never `localStorage`. Put every string in `src/i18n.ts`. `pnpm run --silent sdk docs view guides/ui.md` is the reference for every hook.
18
+ 4. **Implement the components** under `ui/src/` (the entry component is `App.tsx`), with `useUserInterfaceData()` for `data`, `settings`, `setData` and `completedTicks`. Default to MUI; another library must integrate with `useUserInterfaceTheme` so dark mode and colour palettes work, and text on a theme colour uses that colour's `contrastText`. Remember a viewer's own choices with `useViewerStorage`, never `localStorage`. Put every string in `src/i18n.ts`. `pnpm run --silent sdk docs view guides/ui.md` is the reference for every hook, with the topic pages it links.
19
19
  5. **Await every write.** `setData` returns a promise that rejects when the host refuses the write. Route writes through `useMutationReporter`, as the starter game's `ui/src/writes.ts` does, so the participant sees the refusal. Never retry a write automatically: on a `conflict` the host has already retried and given up, so offer `failure.retry` behind a 'Try again' button instead.
20
20
  6. **Add a test** beside the component (`App.test.tsx`), rendered with `renderUserInterface()` (or `renderSessionUserInterface<SessionData>()`, `renderSettingsEditor()`) from `@seriousgaming/sdk/ui/testing`, as the starter game's tests do. `pnpm run --silent sdk docs view guides/testing.md` has the harness.
21
21
  7. **Verify**: `pnpm run build` and `pnpm test:run`. A running dev server hot-reloads the UI. The user starts the dev server (`pnpm run sdk dev`) when they want to see it; never start it yourself.
@@ -18,7 +18,7 @@ Unit and component tests live next to the source they cover: the engine's `engin
18
18
  2. **For logic**, call `Init`, `Run`, a hook, an endpoint or a validator directly with arguments built by `logicArgs` from `@seriousgaming/sdk/testing` (`logicArgs.run({ context, settings: defaultSettings })`), and assert on the returned `capabilities`. For behaviour across several ticks, hooks, validators, endpoints, participants, undo or automatic ticks, use `createTestSession<Context, SharedContext>` in `testing/engine/`: it runs the session the dev server runs, in-process, with offline stubs for `generateText`, `generateSpeech` and `extractText`. The references are `pnpm run --silent sdk docs view guides/testing.md` and `guides/engine-testing.md`.
19
19
  3. **For UI components**, render with `renderUserInterface()` (or `renderSessionUserInterface()`, or `renderSettingsEditor()` for setup and the scenario editor) from `@seriousgaming/sdk/ui/testing`, which supplies every provider the host does. Never `vi.mock` the SDK contexts, and never wire the providers by hand. For a session UI, pass the generated types: `renderSessionUserInterface<SessionData>()`, with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()`, so a shared capability left on a team fixture fails to compile.
20
20
  4. **Cover the branches.** One test per code path: the happy path plus each failure mode, each option flag, each conditional in `Run`.
21
- 5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server of its own on free ports (`testing/e2e/global-setup.ts`), beside any the user has running.
21
+ 5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server for each Playwright worker on free ports, beside any the user has running, and serves them surfaces built once by `testing/e2e/global-setup.ts`. Import `test` from `@seriousgaming/sdk-tools/playwright` in a spec, not from `@playwright/test`.
22
22
 
23
23
  ## Things that almost always go wrong
24
24
 
@@ -1,21 +1,10 @@
1
- import { dirname } from 'path';
2
-
3
- import type { FullConfig } from '@playwright/test';
4
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
5
-
6
1
  /**
7
- * Start the dev server the browser tests run against, and stop it after them.
2
+ * Build the game's surfaces once, before any test runs, and remove the build
3
+ * after the last.
8
4
  *
9
- * It is the server `sdk dev --isolated --port auto` runs: on free ports, with
10
- * no lock file, and configured from the package alone, so it starts beside
11
- * your own dev server and every run begins from the same place. Running it in
12
- * this process rather than spawning `sdk dev` means stopping it is a call,
13
- * which a run cannot hang on.
5
+ * Every worker's dev server then serves the build as files, so a page loads at
6
+ * once instead of each server compiling the same surfaces through Vite. Set
7
+ * SERIOUSGAMING_BUILT_SURFACES=dist to serve the output of your own
8
+ * `pnpm run sdk build` instead, and build nothing here.
14
9
  */
15
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
16
- const server = await startDevServer({
17
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
18
- });
19
- process.env.SERIOUSGAMING_DEV_URL = server.url;
20
- return () => server.stop();
21
- }
10
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
2
2
 
3
3
  export default defineConfig({
4
4
  testDir: './testing/e2e',
5
- // Starts an isolated dev server on free ports, beside any `sdk dev` you
6
- // have running, and stops it when the run ends. It names the server in
7
- // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
5
+ // Builds the game's surfaces once for the run, so every worker's dev
6
+ // server serves them as files rather than compiling them again.
8
7
  globalSetup: './testing/e2e/global-setup.ts',
9
- // One worker: these tests share a session, so a tick in one is visible to
10
- // the next. Running them in parallel makes each test's starting state
11
- // depend on what another happened to be doing.
12
- workers: 1,
8
+ // Every worker starts its own isolated dev server (the `test` the specs
9
+ // import from `@seriousgaming/sdk-tools/playwright`), so tests in
10
+ // different workers never share a session and can run side by side. Tests
11
+ // that land in the same worker share its server one after another, which
12
+ // is why each spec starts the session again in `beforeEach`.
13
+ fullyParallel: true,
13
14
  // A stray `test.only` passes locally and silently skips the rest on CI.
14
15
  forbidOnly: !!process.env.CI,
15
- use: {
16
- // Read again in each worker, after the global setup has set it.
17
- baseURL: process.env.SERIOUSGAMING_DEV_URL,
18
- },
19
16
  });
@@ -1,3 +1,16 @@
1
+ # Refuse any version published less than seven days ago, so a compromised
2
+ # release is not pulled in before anyone has had time to catch it. pnpm's own
3
+ # default is one day. Given a range, pnpm picks the newest release in it that is
4
+ # old enough, so this steps a dependency down rather than failing your install.
5
+ #
6
+ # The SDK's own packages are exempt. You chose them by running `new package`,
7
+ # and a game scaffolded on the day of an SDK release would otherwise refuse the
8
+ # very version that scaffolded it. Everything they depend on is still held to
9
+ # the seven days.
10
+ minimumReleaseAge: 10080
11
+ minimumReleaseAgeExclude:
12
+ - '@seriousgaming/*'
13
+
1
14
  # A transitive dependency of the SDK packages whose parent pins it to a range
2
15
  # that only reaches a version with a security advisory against it. Your package
3
16
  # does not depend on it directly, and nothing you change in package.json moves
@@ -0,0 +1,18 @@
1
+ {
2
+ "definition": {
3
+ "scope": "shared",
4
+ "variablesSchema": {
5
+ "type": "object",
6
+ "properties": {
7
+ "LastOpenDay": {
8
+ "type": "integer",
9
+ "description": "The last day a stall may open. The facilitator lowers it to hold the room at a day, and raises it to let them on; the default opens all ten",
10
+ "default": 10,
11
+ "minimum": 0
12
+ }
13
+ },
14
+ "required": ["LastOpenDay"],
15
+ "additionalProperties": false
16
+ }
17
+ }
18
+ }
@@ -32,8 +32,10 @@
32
32
  "@emotion/styled": "^11.14.1",
33
33
  "@fontsource-variable/roboto-mono": "^5.3.0",
34
34
  "@fontsource-variable/work-sans": "^5.3.0",
35
+ "@mui/icons-material": "^9.4.0",
35
36
  "@mui/material": "^9.4.0",
36
37
  "@mui/stylis-plugin-rtl": "^9.4.0",
38
+ "@seriousgaming/deck": "workspace:*",
37
39
  "i18next": "^26.4.2",
38
40
  "react": "^19.3.0",
39
41
  "react-dom": "^19.3.0",
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
2
2
 
3
3
  export default defineConfig({
4
4
  testDir: './testing/e2e',
5
- // Starts an isolated dev server on free ports, beside any `sdk dev` you
6
- // have running, and stops it when the run ends. It names the server in
7
- // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
5
+ // Builds the game's surfaces once for the run, so every worker's dev
6
+ // server serves them as files rather than compiling them again.
8
7
  globalSetup: './testing/e2e/global-setup.ts',
9
- // One worker: these tests share a session, so a tick in one is visible to
10
- // the next. Running them in parallel makes each test's starting state
11
- // depend on what another happened to be doing.
12
- workers: 1,
8
+ // Every worker starts its own isolated dev server (the `test` the specs
9
+ // import from `@seriousgaming/sdk-tools/playwright`), so tests in
10
+ // different workers never share a session and can run side by side. Tests
11
+ // that land in the same worker share its server one after another, which
12
+ // is why each spec starts the session again in `beforeEach`.
13
+ fullyParallel: true,
13
14
  // A stray `test.only` passes locally and silently skips the rest on CI.
14
15
  forbidOnly: !!process.env.CI,
15
- use: {
16
- // Read again in each worker, after the global setup has set it.
17
- baseURL: process.env.SERIOUSGAMING_DEV_URL,
18
- },
19
16
  });
@@ -0,0 +1,52 @@
1
+ // This file is auto-generated from the schemas the resource declares: the values
2
+ // a session starts with, for use as test fixtures.
3
+ // Do not edit this file directly. It will be regenerated on build.
4
+
5
+ import type { Context, TeamContext, SharedContext, Settings } from './types';
6
+
7
+ export const defaultContext: Context = {
8
+ plan: {
9
+ Make: {},
10
+ },
11
+ weather: {
12
+ Today: 'sunny',
13
+ Expected: {},
14
+ },
15
+ results: {
16
+ Day: 0,
17
+ Weather: 'sunny',
18
+ Lines: {},
19
+ Takings: 0,
20
+ Spent: 0,
21
+ Profit: 0,
22
+ Purse: 0,
23
+ },
24
+ };
25
+
26
+ export const defaultTeamContext: TeamContext = {
27
+ plan: {
28
+ Make: {},
29
+ },
30
+ weather: {
31
+ Today: 'sunny',
32
+ Expected: {},
33
+ },
34
+ results: {
35
+ Day: 0,
36
+ Weather: 'sunny',
37
+ Lines: {},
38
+ Takings: 0,
39
+ Spent: 0,
40
+ Profit: 0,
41
+ Purse: 0,
42
+ },
43
+ };
44
+
45
+ export const defaultSharedContext: SharedContext = {};
46
+
47
+ export const defaultSettings: Settings = {
48
+ session: {
49
+ ShowJoinLinks: true,
50
+ CurrencySymbol: '£',
51
+ },
52
+ };
@@ -0,0 +1,20 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>Lemonade Stand</title>
7
+ <style>
8
+ html,
9
+ body,
10
+ #root {
11
+ height: 100%;
12
+ margin: 0;
13
+ }
14
+ </style>
15
+ </head>
16
+ <body>
17
+ <div id="root"></div>
18
+ <script type="module" src="./src/main.tsx"></script>
19
+ </body>
20
+ </html>
@@ -0,0 +1,10 @@
1
+ {
2
+ "definition": {
3
+ "reads": ["plan", "weather", "results"],
4
+ "settings": ["session"]
5
+ },
6
+ "ui": {
7
+ "entrypoint": "index.html"
8
+ },
9
+ "rootDirectory": "."
10
+ }
@@ -0,0 +1,55 @@
1
+ import { brandFromTheme, Deck } from '@seriousgaming/deck';
2
+ import { usePresentation } from '@seriousgaming/sdk/ui';
3
+ import { useEffect, useMemo } from 'react';
4
+ import { useTranslation } from 'react-i18next';
5
+
6
+ import type { Settings, SharedContext, TeamContext } from '../types';
7
+ import { useSlides } from './Slides';
8
+
9
+ /*
10
+ A presentation is the facilitator's slide deck. It is read-only, and it renders
11
+ with or without a session: in a game's library, while rehearsing or to export
12
+ it beforehand, `session` is null, so every slide must make sense without
13
+ results.
14
+
15
+ The host's theme becomes the deck's brand here, so the slides pick up the same
16
+ colours as every other surface.
17
+ */
18
+
19
+ /** Where to open when nothing is remembered: wherever the room has got to. */
20
+ function startFor(rounds: number, played: number | null): string {
21
+ if (!played) return 'title';
22
+ return played >= rounds ? 'results' : `day-${played + 1}`;
23
+ }
24
+
25
+ export default function App() {
26
+ const { game, session, theme, locale } = usePresentation<
27
+ Settings,
28
+ TeamContext,
29
+ SharedContext
30
+ >();
31
+ const { i18n } = useTranslation();
32
+ const language = locale.locale;
33
+
34
+ useEffect(() => {
35
+ void i18n.changeLanguage(language);
36
+ }, [i18n, language]);
37
+
38
+ const brand = useMemo(() => brandFromTheme(theme), [theme]);
39
+ const slides = useSlides();
40
+
41
+ return (
42
+ <Deck
43
+ brand={brand}
44
+ title={game.name}
45
+ dir={i18n.dir(language)}
46
+ lang={language}
47
+ // Come back to the same slide after a reload or a break. Each session
48
+ // keeps its own place; rehearsing without one has one of its own.
49
+ rememberAs={session ? `session:${session.id}` : 'com.example.lemonade'}
50
+ startAt={startFor(game.maxTicks ?? 10, session?.completedTicks ?? null)}
51
+ >
52
+ {slides}
53
+ </Deck>
54
+ );
55
+ }
@@ -0,0 +1,40 @@
1
+ import { useId } from 'react';
2
+
3
+ const BAND = 60;
4
+ const DEPTH = 30;
5
+ const SCALLOP = 96;
6
+
7
+ /**
8
+ * The awning across the top of every slide: a band of the host's primary
9
+ * colour with the game's scalloped edge under it, the same motif as
10
+ * `shared/Awning.tsx` on the player screens.
11
+ *
12
+ * It is drawn again here rather than imported because a deck has no MUI
13
+ * theme to read the colour from: the deck's own brand reaches every slide as
14
+ * `--deck-primary`, so the shape fills with that.
15
+ */
16
+ export function Band() {
17
+ const id = useId();
18
+
19
+ return (
20
+ <div aria-hidden style={{ lineHeight: 0 }}>
21
+ <div style={{ height: BAND, background: 'var(--deck-primary)' }} />
22
+ <svg
23
+ width="100%"
24
+ height={DEPTH}
25
+ preserveAspectRatio="none"
26
+ style={{ display: 'block', marginTop: -1 }}
27
+ >
28
+ <defs>
29
+ <pattern id={id} width={SCALLOP} height={DEPTH} patternUnits="userSpaceOnUse">
30
+ <path
31
+ d={`M0 0 H${SCALLOP} V2 Q${SCALLOP / 2} ${DEPTH} 0 2 Z`}
32
+ style={{ fill: 'var(--deck-primary)' }}
33
+ />
34
+ </pattern>
35
+ </defs>
36
+ <rect width="100%" height={DEPTH} fill={`url(#${id})`} />
37
+ </svg>
38
+ </div>
39
+ );
40
+ }