@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
@@ -5,7 +5,7 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
7
7
  <title>Serious Gaming</title>
8
- <script type="module" crossorigin src="/assets/index-BvB-LFQZ.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-CuMOOH9m.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -0,0 +1,61 @@
1
+ /**
2
+ * The addresses a dev server behind a proxy is reached at (#788).
3
+ *
4
+ * The server otherwise names itself from the request: `http://`, the `Host`
5
+ * the browser sent, and the asset or hot-reload port in place of its own. A
6
+ * gateway that serves each origin on its own HTTPS hostname breaks every one
7
+ * of those guesses, so a server behind one is told its addresses instead.
8
+ */
9
+ export declare const PUBLIC_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_URL";
10
+ export declare const PUBLIC_ASSET_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_ASSET_URL";
11
+ export declare const PUBLIC_HMR_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_HMR_URL";
12
+ /** The origins as given, each already parsed by {@link parsePublicOrigin}. */
13
+ export interface PublicOrigins {
14
+ /** The console, its API and every link a participant is handed. */
15
+ publicUrl?: string;
16
+ /** Game bundles and the files a frame reads. */
17
+ publicAssetUrl?: string;
18
+ /** Vite's hot-reload socket, as `ws:` or `wss:`. */
19
+ publicHmrUrl?: string;
20
+ }
21
+ /**
22
+ * An origin from a flag or an environment variable, normalised.
23
+ *
24
+ * Only an origin: a path would suggest the server can be mounted under one,
25
+ * and it cannot, since every route it serves is absolute.
26
+ *
27
+ * @throws {CliError} when the value is not an origin of the kind `flag` takes.
28
+ */
29
+ export declare function parsePublicOrigin(value: string, flag: string, kind: 'http' | 'ws'): string;
30
+ /**
31
+ * The public origins for `sdk dev`: each flag, else its environment variable,
32
+ * parsed. Unset where neither gives one.
33
+ *
34
+ * @throws {CliError} when a value is not an origin.
35
+ */
36
+ export declare function resolvePublicOrigins(flags: {
37
+ publicUrl?: string;
38
+ publicAssetUrl?: string;
39
+ publicHmrUrl?: string;
40
+ }, env?: NodeJS.ProcessEnv): PublicOrigins;
41
+ /**
42
+ * The asset origin: as given, else the public console's scheme and host on
43
+ * the asset port, which is what a proxy forwarding each port as it is serves.
44
+ * Null when neither is given, so the server goes on naming it from the request.
45
+ */
46
+ export declare function publicAssetOrigin(origins: PublicOrigins, assetPort: number): string | null;
47
+ /**
48
+ * Where a frame's hot-reload client connects: as given, else the asset
49
+ * origin's host on the Vite port, over `wss:` when the asset origin is HTTPS.
50
+ * That default is where Vite's client connects when told nothing, so it
51
+ * changes only the scheme and the name. Null when no public origin is given.
52
+ */
53
+ export declare function publicHmrOrigin(origins: PublicOrigins, assetPort: number, vitePort: number): string | null;
54
+ /** What Vite's client is told to connect to, from a `ws:` or `wss:` origin. */
55
+ export declare function hmrClientTarget(origin: string): {
56
+ protocol: 'ws' | 'wss';
57
+ host: string;
58
+ clientPort: number;
59
+ };
60
+ /** The hostnames a public origin names, which Vite must accept in a `Host` header. */
61
+ export declare function publicHostnames(origins: (string | null | undefined)[]): string[];
@@ -18,7 +18,14 @@ import type { RunKind } from '@seriousgaming/sdk';
18
18
  import type { MutationResult } from '@seriousgaming/sdk/projection';
19
19
  import type { Command } from '../core/protocol';
20
20
  import { Session, type SessionOptions } from '../core/session';
21
- export interface ShellOptions extends SessionOptions {
21
+ import { type PublicOrigins } from './public-origins';
22
+ /**
23
+ * `publicUrl`, `publicAssetUrl` and `publicHmrUrl` are the addresses a server
24
+ * behind a proxy is reached at (#788), each an origin as
25
+ * `parsePublicOrigin` leaves it. Unset, every address is named from the
26
+ * request that asked for it.
27
+ */
28
+ export interface ShellOptions extends SessionOptions, PublicOrigins {
22
29
  port?: number;
23
30
  /** Port the Vite HMR socket binds to. Defaults to `port + 1`. */
24
31
  vitePort?: number;
@@ -53,6 +60,19 @@ export interface ShellOptions extends SessionOptions {
53
60
  * starts, so a broken one fails the start rather than the page.
54
61
  */
55
62
  brandFiles?: string[];
63
+ /**
64
+ * Whether surfaces show Vite's full-screen error overlay. Unset leaves it
65
+ * to the package's own Vite config, which shows it by default (#807).
66
+ */
67
+ errorOverlay?: boolean;
68
+ /**
69
+ * A directory of surfaces already built, laid out as `sdk build` lays out
70
+ * `dist/` (`ui/`, `session/`, ...). Surfaces are served from it as static
71
+ * files and Vite is never started, so a page loads at once and an edit to
72
+ * a surface's source is not seen. For browser test runs, where every
73
+ * worker's server would otherwise compile the same surfaces again.
74
+ */
75
+ builtSurfaces?: string;
56
76
  }
57
77
  /**
58
78
  * Something the server could not apply live, kept until it no longer holds so
@@ -108,6 +128,8 @@ export declare class DevShell {
108
128
  private viteFailure;
109
129
  /** Serialises the first requests for a surface so they share one Vite. */
110
130
  private viteStarting;
131
+ /** The hot-reload socket's own listener, when a public origin moves its client. */
132
+ private hmrServer;
111
133
  private port;
112
134
  private vitePort;
113
135
  private assetPort;
@@ -171,14 +193,23 @@ export declare class DevShell {
171
193
  get url(): string;
172
194
  /** Where bundles are served from, once listening. */
173
195
  get assetUrl(): string;
196
+ /** Where people reach the console, when a proxy stands in front of it. */
197
+ get publicUrl(): string | null;
198
+ /** Where people's browsers load bundles from, when a proxy stands in front. */
199
+ get publicAssetUrl(): string | null;
174
200
  /**
175
- * The asset origin as a client that reached `host` must name it: the same
176
- * host, the asset port. A browser on another machine reached us by an
177
- * address `localhost` would not resolve to on its side.
201
+ * The asset origin as a client that reached `host` must name it: the
202
+ * public one where given, else the same host on the asset port. A browser
203
+ * on another machine reached us by an address `localhost` would not
204
+ * resolve to on its side.
178
205
  */
179
206
  assetOrigin(host: string | undefined): string;
180
207
  /** The console's own origin, as a client that reached `host` names it. */
181
208
  private consoleOrigin;
209
+ /** Where a frame's hot-reload client connects, when a public origin decides it. */
210
+ private get publicHmrUrl();
211
+ /** What the bundle policy's `connect-src` admits for hot reload. */
212
+ private hmrSources;
182
213
  /** The session this shell wraps, for tests and for the CLI in-process path. */
183
214
  get runtime(): Session;
184
215
  /**
@@ -212,6 +243,12 @@ export declare class DevShell {
212
243
  * reads, all under the bundle policy and nothing under `/api`.
213
244
  */
214
245
  private configureAssets;
246
+ /**
247
+ * Each surface from its built directory, which `sdk build` gives relative
248
+ * asset paths, so the document and everything it loads resolve under the
249
+ * route the console already mounts it at.
250
+ */
251
+ private serveBuiltSurfaces;
215
252
  /**
216
253
  * Vite, started the first time something asks for a surface (#320).
217
254
  *
@@ -222,6 +259,16 @@ export declare class DevShell {
222
259
  */
223
260
  private ensureVite;
224
261
  private createVite;
262
+ /**
263
+ * Vite's server options: its own hot-reload socket on the Vite port, as
264
+ * before, unless a public origin says where the client connects.
265
+ *
266
+ * Vite takes one `host` for both where its socket listens and where its
267
+ * client connects, and a public hostname is no address to listen on. So
268
+ * behind a proxy the socket's listener is opened here, on the Vite port
269
+ * as usual, and Vite only attaches to it.
270
+ */
271
+ private viteServerOptions;
225
272
  private attachSockets;
226
273
  private receive;
227
274
  /** What one viewer page is owed, now. */
@@ -37,5 +37,12 @@ export interface MountableSurface {
37
37
  */
38
38
  settings: string[];
39
39
  }
40
+ /** URL prefix each surface kind is served under. */
41
+ export declare const SURFACE_PREFIX: Record<SurfaceKind, string>;
42
+ /**
43
+ * The slot each surface kind fills, which is both its identifier and where
44
+ * `sdk build` writes it inside `dist/`.
45
+ */
46
+ export declare const SURFACE_SLOT: Record<SurfaceKind, string>;
40
47
  /** Every surface this package can mount: one per slot it fills. */
41
48
  export declare function mountableSurfaces(config: ResolvedPackageManifest | null): MountableSurface[];
@@ -14,10 +14,15 @@ The site describes the newest release. Inside a package, read the docs that ship
14
14
 
15
15
  ```bash
16
16
  pnpm run --silent sdk docs view # the documentation tree
17
+ pnpm run --silent sdk docs view page-index.md # every page: summary and length
17
18
  pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
19
+ pnpm run --silent sdk docs view guides/ui.md --outline # the headings of a page, with section lengths
20
+ pnpm run --silent sdk docs view guides/ui.md --section 'Writing to context' # one section
18
21
  pnpm run sdk docs export # copy every page into the package, to search with grep
19
22
  ```
20
23
 
24
+ Some guides run past 50,000 characters. Rather than reading one whole, find it in the [page index](./page-index.md), list its headings with `--outline`, and read the section you need with `--section`, which takes a heading's text or the slug the outline prints. Every guide and recipe carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right page.
25
+
21
26
  On the site, [llms.txt](https://sdk.seriousgaming.com/llms.txt) lists every page, [llms-small.txt](https://sdk.seriousgaming.com/llms-small.txt) holds the core pages in one file, and [llms-full.txt](https://sdk.seriousgaming.com/llms-full.txt) holds them all. Start from a recipe for a task and from a guide for a whole subject.
22
27
 
23
28
  ## 1. Scaffold without a prompt
@@ -4,17 +4,18 @@
4
4
 
5
5
  Every type, function, hook and component your game imports, one page per entry point. Each page is generated from the published declarations and their documentation, so it always matches the release it ships in.
6
6
 
7
- | Entry point | Exports |
8
- | ---------------------------------------------------------- | -------------------------------------------------------------- |
9
- | [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
10
- | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
11
- | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
12
- | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
13
- | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
14
- | [`@seriousgaming/sdk/commands`](./sdk-commands.md) | 3 interfaces, 5 types |
15
- | [`@seriousgaming/sdk/e2e`](./sdk-e2e.md) | 6 functions, 1 constant, 4 interfaces, 5 types |
16
- | [`@seriousgaming/deck`](./deck.md) | 16 functions, 5 constants, 15 interfaces, 4 types |
17
- | [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 4 functions, 1 class, 10 interfaces, 11 types |
7
+ | Entry point | Exports |
8
+ | ------------------------------------------------------------------ | -------------------------------------------------------------- |
9
+ | [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
10
+ | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
11
+ | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
12
+ | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
13
+ | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
14
+ | [`@seriousgaming/sdk/commands`](./sdk-commands.md) | 3 interfaces, 5 types |
15
+ | [`@seriousgaming/sdk/e2e`](./sdk-e2e.md) | 6 functions, 1 constant, 4 interfaces, 5 types |
16
+ | [`@seriousgaming/deck`](./deck.md) | 16 functions, 5 constants, 15 interfaces, 4 types |
17
+ | [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 5 functions, 1 class, 12 interfaces, 11 types |
18
+ | [`@seriousgaming/sdk-tools/playwright`](./sdk-tools-playwright.md) | 1 function, 3 constants, 2 interfaces, 1 type |
18
19
 
19
20
  ## Which entry point to import from
20
21
 
@@ -24,7 +25,8 @@ Every type, function, hook and component your game imports, one page per entry p
24
25
  - **`@seriousgaming/sdk/ui/testing`**: the harness for component-testing a surface
25
26
  - **`@seriousgaming/sdk/e2e`**: the browser-test driver for a running dev server
26
27
  - **`@seriousgaming/sdk/commands`** and **`@seriousgaming/sdk/projection`**: the commands a client may send a session, and the shape of the state it reads back (`sdk view --json` and the dev server's `/api/state`)
27
- - **`@seriousgaming/sdk-tools/client`**: `createTestSession`, which plays a whole game in-process, and `startDevServer`, which starts an isolated dev server for browser tests
28
+ - **`@seriousgaming/sdk-tools/client`**: `createTestSession`, which plays a whole game in-process, `startDevServer`, which starts an isolated dev server for browser tests, and `buildSurfaces`, which builds a game's surfaces for those servers to serve
29
+ - **`@seriousgaming/sdk-tools/playwright`**: the Playwright `test` that starts a dev server for each worker, and the `globalSetup` that builds the surfaces they serve
28
30
  - **`@seriousgaming/deck`**: the slide components and layout primitives a presentation is built from
29
31
 
30
32
  `@seriousgaming/sdk-tools` also exports `/host` and `/runtime`. They are for people building a runtime that hosts games, not for game authors, their shapes may change in a minor release, and they are not documented here.
@@ -26,6 +26,14 @@ Every export of `@seriousgaming/sdk-tools/client`, with the declaration it is pu
26
26
 
27
27
  ## Functions
28
28
 
29
+ ### buildSurfaces
30
+
31
+ Build every surface the package has, as `sdk build` builds them, and nothing else: no logic, no guide, no archive.
32
+
33
+ ```ts
34
+ function buildSurfaces(options: BuildSurfacesOptions): Promise<BuiltSurfaces>;
35
+ ```
36
+
29
37
  ### createStubServices
30
38
 
31
39
  The stubbed service callbacks: `generateText`, `generateSpeech` and `extractText`. Blob storage stays real, because it is local.
@@ -86,6 +94,26 @@ class FakeClock implements Clock {
86
94
 
87
95
  ## Interfaces
88
96
 
97
+ ### BuildSurfacesOptions
98
+
99
+ A package's surfaces built once, for every dev server of a test run (#808).
100
+
101
+ ```ts
102
+ interface BuildSurfacesOptions {
103
+ packagePath: string;
104
+ outDir?: string;
105
+ }
106
+ ```
107
+
108
+ ### BuiltSurfaces
109
+
110
+ ```ts
111
+ interface BuiltSurfaces {
112
+ directory: string;
113
+ remove(): Promise<void>;
114
+ }
115
+ ```
116
+
89
117
  ### Clock
90
118
 
91
119
  ```ts
@@ -118,6 +146,7 @@ interface DevServerOptions {
118
146
  clock?: Clock;
119
147
  callbacks?: Partial<SignatureCallbacks>;
120
148
  reinitOnChange?: boolean;
149
+ builtSurfaces?: string;
121
150
  }
122
151
  ```
123
152
 
@@ -0,0 +1,104 @@
1
+ <!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk-tools/playwright`. Edit those, not this file. -->
2
+
3
+ # `@seriousgaming/sdk-tools/playwright`
4
+
5
+ Playwright for a game's browser tests: a dev server for each worker.
6
+
7
+ A dev server holds one session, so a run against one server has to take its
8
+ tests one at a time. Each worker here starts its own isolated server, so the
9
+ tests of different workers never share a session and the run can be
10
+ parallel. Tests in one worker still share its server, one after another, so
11
+ each still states its own starting point (`reinitialiseSession()`).
12
+
13
+ @example
14
+
15
+ ```ts
16
+ // playwright.config.ts
17
+ export default defineConfig({
18
+ testDir: './testing/e2e',
19
+ globalSetup: './testing/e2e/global-setup.ts',
20
+ fullyParallel: true,
21
+ });
22
+
23
+ // testing/e2e/global-setup.ts
24
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
25
+
26
+ // testing/e2e/game.spec.ts
27
+ import { expect, test } from '@seriousgaming/sdk-tools/playwright';
28
+ ```
29
+
30
+ Every export of `@seriousgaming/sdk-tools/playwright`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
31
+
32
+ ## Functions
33
+
34
+ ### globalSetup
35
+
36
+ A Playwright `globalSetup` that builds the package's surfaces once for the whole run, so every worker's server serves them as files rather than each compiling them through Vite. Removes the build when the run ends.
37
+
38
+ ```ts
39
+ function globalSetup(config: FullConfig): Promise<() => Promise<void>>;
40
+ ```
41
+
42
+ ## Constants
43
+
44
+ ### BUILT_SURFACES_ENV_VAR
45
+
46
+ Where `globalSetup` tells the workers it built the surfaces.
47
+
48
+ ```ts
49
+ const BUILT_SURFACES_ENV_VAR = 'SERIOUSGAMING_BUILT_SURFACES';
50
+ ```
51
+
52
+ ### expect
53
+
54
+ ```ts
55
+ const expect: Expect<{}>;
56
+ ```
57
+
58
+ ### test
59
+
60
+ Playwright's `test`, with an isolated dev server started for each worker.
61
+
62
+ ```ts
63
+ const test: import('@playwright/test').TestType<
64
+ import('@playwright/test').PlaywrightTestArgs &
65
+ import('@playwright/test').PlaywrightTestOptions &
66
+ object,
67
+ import('@playwright/test').PlaywrightWorkerArgs &
68
+ import('@playwright/test').PlaywrightWorkerOptions &
69
+ DevServerWorkerFixtures
70
+ >;
71
+ ```
72
+
73
+ ## Interfaces
74
+
75
+ ### DevServer
76
+
77
+ ```ts
78
+ interface DevServer {
79
+ url: string;
80
+ assetUrl: string;
81
+ stop(): Promise<void>;
82
+ }
83
+ ```
84
+
85
+ ### DevServerWorkerFixtures
86
+
87
+ ```ts
88
+ interface DevServerWorkerFixtures {
89
+ devServerOptions: DevServerFixtureOptions;
90
+ devServer: DevServer;
91
+ }
92
+ ```
93
+
94
+ ## Types
95
+
96
+ ### DevServerFixtureOptions
97
+
98
+ How each worker's server starts. The package is the config file's directory unless named.
99
+
100
+ ```ts
101
+ type DevServerFixtureOptions = Omit<DevServerOptions, 'packagePath' | 'builtSurfaces'> & {
102
+ packagePath?: string;
103
+ };
104
+ ```
@@ -563,8 +563,8 @@ Work through step 5 of the upgrade guide: it gives the five in order, with the e
563
563
  ### Added
564
564
 
565
565
  - A scenario can configure the session user interface, through a `sessionUserInterfaces` bucket in its `configuration` alongside `modules` and `userInterfaces`. The surface's configuration now resolves through all four layers like any other resource: schema defaults, the game's `sessionUserInterface` reference, the active scenario, then the centralized layer. Session UIs get their own bucket rather than sharing `userInterfaces`, so a player UI and a session UI may carry the same identifier without crossing. See the [session UI guide](guides/session.md#configuring-the-surface)
566
- - A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session.md#opening-host-overlays)
567
- - `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session.md#extending-a-tick)
566
+ - A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session-game-flow.md#opening-host-overlays)
567
+ - `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session-game-flow.md#extending-a-tick)
568
568
  - The dev server serves team print sheets at `/print-sheets`, one card per team with its join and observe URLs behind a print stylesheet. Print every team from the session menu, or one team from its card's own menu; a session UI reaches both through `openHostOverlay('print-sheets', teamId?)`. The sheets carry no QR code and no PIN, because the dev server has neither; a production host prints both
569
569
  - A game can start its sessions with the waiting room already open, by setting `"openOnStart": true` on its `waitingRoom` reference. Without it the room is closed at the start, so the first player to follow a join link lands in the game rather than the holding screen unless the facilitator opened the room first. It seeds the session and nothing more: the facilitator owns the flag from then on, a reset does not re-park the session, and a dev server restart restores the flag the session was left with. Available to a game that authors its own waiting room UI. See the [waiting room guide](guides/waiting-room.md#starting-held)
570
570
  - `new`, `update` and `delete` accept `-j, --json`, matching every other command in the CLI. The envelope names the command, the resource type, the identifier, and every file, reference and directory the operation touched; a failure reports the same shape with `"success": false` and an `error`, and exits non-zero. Because prompts cannot produce JSON, `new` and `update` need a definition or a `--patch` under the flag, and `delete` needs `--force`. See the [CLI reference](cli-reference.md#json-output)
@@ -31,6 +31,58 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.6.0] — 2026-11-02
35
+
36
+ ### Added
37
+
38
+ - **Browser tests run in parallel.** Import `test` from the new `@seriousgaming/sdk-tools/playwright` and each Playwright worker starts its own isolated dev server, so a suite no longer needs `workers: 1`. Its `globalSetup` builds the game's surfaces once for the run, and every worker's server serves that build instead of compiling the surfaces through Vite. New packages are set up this way, and an existing suite keeps working as it is. See [A dev server for browser tests](guides/testing.md#a-dev-server-for-browser-tests)
39
+ - **`sdk dev --built-surfaces <DIR>`** serves surfaces from a build, such as `dist/` after `sdk build`, instead of compiling them through Vite. `startDevServer` takes the same as `builtSurfaces`, and `buildSurfaces` from `@seriousgaming/sdk-tools/client` builds them into a temporary directory. See [Serve built surfaces](cli-reference.md#serve-built-surfaces)
40
+ - **`sdk dev --no-error-overlay`** hides Vite's full-screen error overlay over a surface that fails to build, for a preview watched by people who are not developers. `SERIOUSGAMING_DEV_ERROR_OVERLAY=false` does the same for a server a command starts. The error still reaches the server's log and the browser console. See [Hide the error overlay](cli-and-dev-server.md#hide-the-error-overlay)
41
+
42
+ ### Changed
43
+
44
+ - **A capability added to a running game gets its `Init` when nothing has been played yet.** At tick 0, or under `sdk dev --reinit-on-change`, the dev server now re-initialises the session so `Init` runs for the new capability, instead of seeding it with its schema defaults. Once play is under way it is still seeded, and the console now says so as well as the terminal. See [What reloads](cli-reference.md#what-reloads)
45
+ - **Designing a serious game covers more of the design.** The guide now suggests finding the one tension a game is built around, scoring the behaviour the aim teaches, keeping stuck and trailing teams in play, and recording what the debrief needs. It also suggests getting a game playing before balancing it, then balancing against outcomes written while designing
46
+ - **The CLI starts faster.** Each command now loads only what it uses, so a call such as `pnpm run sdk version` or `view` no longer loads Vite, Express and the template engine first, which cut its start-up time by about two thirds
47
+
48
+ ### Fixed
49
+
50
+ - **The dev server no longer exits when `Init` throws while an edit re-initialises the session.** It reports the error in its log and on the console and keeps serving, and the edit stays pending until the next edit or `sdk init` applies it. It used to stop, losing the session and leaving the preview unreachable
51
+ - **A dev server a command started in the background stops when its package is removed.** It used to run on with nothing to serve, holding its ports, after a scratch game or a test's temporary copy was deleted. A server you start yourself with `sdk dev` is unchanged
52
+
53
+ ## [1.5.0] — 2026-10-29
54
+
55
+ ### Added
56
+
57
+ - **`sdk dev` can run behind a proxy or gateway.** `--public-url`, `--public-asset-url` and `--public-hmr-url` (or `SERIOUSGAMING_DEV_PUBLIC_URL`, `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` and `SERIOUSGAMING_DEV_PUBLIC_HMR_URL`) name the addresses people reach it at, and every link and origin the server hands out uses them, where join links used to read `http://localhost:<port>`. With none set, nothing changes. See [Embedding the dev server](cli-and-dev-server.md#embedding-the-dev-server)
58
+ - **A page framing the dev console can set its colour scheme and brand.** Open it with `?scheme=light|dark|system` or `?brand=<id>`, or post `{ type: 'sg-dev-scheme', scheme }` to the frame to change the scheme without a reload. Neither overwrites the viewer's own stored choice, and the scheme reaches the game's surfaces as the dev drawer's does
59
+ - **The starter game has a presentation.** `new package` now writes Lemonade Stand with a `presentation/` slot: a title slide, a slide for each day with the forecast and how the room did the day before, and a results slide for the room. It shows the room rather than any stall by name, with each stall's figures in the speaker notes, renders with no session, and tests its figures as plain functions. See [A tour of the starter game](guides/starter-game.md#presentation)
60
+ - **A guide to designing screens.** [Designing screens](guides/designing-screens.md) sets out what a good simulation screen looks like whatever the brand: one main action, a spacing and type scale, a design for the phone, laptop or projector it is used on, every state from empty to end of game, feedback on a refused write, accessibility, and an identity of the game's own over the host's theme. New packages put it to work: `DESIGN.md.liquid` replaces the 'User interfaces' prompts with a screen brief (who plays and on what, tone, key screens and each one's main action, layout, states and identity), and `CLAUDE.md.template` asks for the brief before a surface is built and a check at phone and desktop size after. An existing package can copy both sections from the templates shipped in `@seriousgaming/sdk-tools`
61
+ - **Read a long page a section at a time.** `pnpm run sdk docs view <page> --outline` lists a page's headings, each with its slug and its section's length in characters, and `--section <heading>` prints only that section, named by its text or its slug. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the ones the page has. The installed docs gain `page-index.md`, every page with a one-sentence summary and its length, and every guide now carries a `**Keywords:**` line for `grep`. A new package's `CLAUDE.md` (`CLAUDE.md.template`) points to all three; merge its Documentation section into an existing package's. See [Read the docs for the installed version](ai-agents.md#read-the-docs-for-the-installed-version)
62
+ - **`pnpm run sdk screenshot <path>` captures a surface as a PNG**, as a participant sees it, once the surface reports its first paint rather than after a fixed delay. `--width` and `--height` set the viewport, `--scheme`, `--brand` and `--locale` what it shows, and `--full-page` its whole height; `--json` also lists the page's console errors, failed requests and uncaught exceptions, from inside the surface's frame too. It uses the running dev server, or starts one for the capture and stops it after. It drives the game's own Playwright, an optional peer of `@seriousgaming/sdk-tools` that every scaffolded game already has: without it, or without its Chromium, it fails with `BROWSER_MISSING`, and a surface that never renders fails with `SURFACE_NOT_RENDERED`. The starter's `CLAUDE.md.template` now tells agents to screenshot each screen at phone and desktop size. See [Screenshot a surface](recipes/screenshot-a-surface.md)
63
+
64
+ ### Changed
65
+
66
+ - **A new game installs under a seven-day release-age policy.** `pnpm run sdk new package` writes `minimumReleaseAge: 10080` into the game's `pnpm-workspace.yaml`, the policy the SDK itself builds under, so pnpm refuses any dependency published in the last week and picks the newest older release in its range instead. The SDK's own packages (`@seriousgaming/*`) are exempt, so a game scaffolded on the day of an SDK release still installs. An existing game is unchanged: to opt in, copy `minimumReleaseAge` and `minimumReleaseAgeExclude`, with their comment, from the scaffold template `templates/package/pnpm-workspace.yaml.template` in the installed `@seriousgaming/sdk-tools` into your `pnpm-workspace.yaml`
67
+ - **A game with a default scenario always runs on a scenario.** Asking for none, with `pnpm run sdk scenario none`, `createTestSession({ scenarioId: null })` or a hosted runtime's equivalent, is refused with an error naming the default, where it used to run the game on its settings defaults alone, and the dev drawer's **Scenario** tab offers **None** only to a game with no default. If an engine test passes `scenarioId: null` to a game with a default, pin one of its scenarios instead. A game with no default runs on none as before. See [Scenarios](guides/scenarios.md)
68
+ - **The user interface and session UI guides are split into topic pages.** [Building user interfaces](guides/ui.md) and [Building session UIs](guides/session.md) keep their paths as entry pages that link to the rest: participants, ticks and the timer, styling, and files and LLMs for a game UI; running the game and the hooks reference for a session UI. A link to a section that moved needs its new page. The `docs view --section` examples in `CLAUDE.md.template` and the hook pointer in `workflow-create-user-interface.md` follow the new pages
69
+
70
+ - **The starter game's screens are redesigned to the [Designing screens](guides/designing-screens.md) guide.** A game made with `new package` now:
71
+ - Leads each participant screen with the day's decision, with the button that opens the stall in a bar at the foot of the layout and a timeline for looking back at earlier days
72
+ - Gives the facilitator one line of session controls, a card per stall, a side panel with no backdrop for managing one, results for the room, and join links in large type for the room to read
73
+ - Lets the facilitator hold the room at a day: a shared `pacing` capability, enforced by a `RequestTick` gate in `validators/daylimit`
74
+ - Takes its icons from `@mui/icons-material`, keeps its one drawn motif (the awning) and the host's logo in a new `shared/` folder, and lists `presentation-overlay` in `requires`, so the facilitator can open the slides from their screen
75
+
76
+ An existing game is unchanged. See [A tour of the starter game](guides/starter-game.md)
77
+
78
+ ### Fixed
79
+
80
+ - **The starter game's facilitator screen shows the purse in pounds.** Lemonade Stand holds money in pence, and its session screen showed a purse of 2,200 pence as '£2,200' where the player's screen showed '£22.00'. A game made from an earlier starter can copy `money` from `ui/src/format.ts` into `session/src/format.ts`; the new starter keeps one copy, in `shared/format.ts`
81
+
82
+ ### Security
83
+
84
+ - **The `fast-uri` advisories are cleared.** The SDK's lockfile now takes `fast-uri` 3.1.9 through `ajv`. `body-parser` 2.4.0, through `express` in the dev server, clears the seven-day gate later on 29 October and is taken by the next release; a game's own install already resolves it once it is old enough
85
+
34
86
  ## [1.4.0] — 2026-10-26
35
87
 
36
88
  ### Added
@@ -60,9 +112,9 @@ are in the [0.x changelog](changelog-0.x.md).
60
112
 
61
113
  ### Added
62
114
 
63
- - **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session.md#opening-host-overlays)
64
- - **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session.md#changing-the-language)
65
- - **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui.md#letting-a-participant-fix-their-own-name)
115
+ - **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session-game-flow.md#opening-host-overlays)
116
+ - **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session-game-flow.md#changing-the-language)
117
+ - **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui-participants.md#letting-a-participant-fix-their-own-name)
66
118
  - **A deck can show the room how to join.** A presentation's `session` carries every team's `participants`, a `joinLinks` entry per team and the session's `joinPin`, so a slide can put the join links on the projector and count who has arrived. See [Showing the room how to join](guides/presentation.md#showing-the-room-how-to-join)
67
119
  - **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
68
120
 
@@ -260,7 +312,7 @@ are in the [0.x changelog](changelog-0.x.md).
260
312
  - **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
261
313
  - **Typed session writes and test fixtures.** A session UI's generated `types.ts` adds `TeamWrites`, the team-scope capabilities in its `writes`, and `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` types the per-team `setData(teamId, update)` with it, so a team write naming a shared capability fails to compile. `createMockTeamState<TeamContext>`, `createMockSharedState<SharedContext>` and `renderSessionUserInterface<SessionData>` type a test's fixtures the same way. Every parameter defaults to today's untyped form, so existing code compiles unchanged. See [Session UIs](guides/testing.md#session-uis)
262
314
  - **A session UI can delete keys.** Both forms of a session surface's `setData` take `{ deletes }` last, as a player surface's does: `setData(teamId, {}, { deletes })` removes from one team and `setData({}, { deletes })` from the shared store. Each path must fall under a capability the surface writes, of the form's scope, or the write is refused as `denied`. `mergingSetData` in `@seriousgaming/sdk/ui/testing` takes the same options and applies them after the merge, as the host does. See [Removing a key](guides/session.md#removing-a-key)
263
- - **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session.md#deleting-a-team)
315
+ - **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session-game-flow.md#deleting-a-team)
264
316
  - **`pauseTimer` and `resumeTimer` are awaitable**, resolving once the host has applied the change and rejecting with a `MutationError` when it refuses
265
317
  - **Every past-state entry carries `index` and `name`**, and the mode-colour theme types (`UserInterfaceModeColors` and siblings) are exported
266
318
 
@@ -80,6 +80,81 @@ can move it to any corner (remembered per browser).
80
80
  Everything the drawer does, the CLI does too, because both send the same
81
81
  commands.
82
82
 
83
+ ## Embedding the dev server
84
+
85
+ On your own machine, the server works out every address it hands out from the
86
+ request: the host your browser used, `http://`, and its own ports. Behind a
87
+ proxy or gateway, such as a sandbox that serves the console on an HTTPS
88
+ hostname and shows it in a frame, those addresses come out wrong, and join
89
+ links read `http://localhost:47100/team/1/join`. Tell the server where it is
90
+ reached instead:
91
+
92
+ ```bash
93
+ pnpm run sdk dev --no-open \
94
+ --public-url https://console.example.com \
95
+ --public-asset-url https://assets.example.com \
96
+ --public-hmr-url wss://hmr.example.com
97
+ ```
98
+
99
+ | Option | Environment variable | What it names | Default when unset |
100
+ | -------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
101
+ | `--public-url` | `SERIOUSGAMING_DEV_PUBLIC_URL` | The console, its API, and every link it hands out | The request's host |
102
+ | `--public-asset-url` | `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | Where browsers load game surfaces and their files | The `--public-url` host on the asset port, else the request's host |
103
+ | `--public-hmr-url` | `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | Where a surface's hot-reload client connects | The public asset host on the Vite port, `wss://` when that host is HTTPS |
104
+
105
+ Each takes an origin only: a scheme, a host and, where it is not the default,
106
+ a port, with no path. The asset origin must differ from the console's, as it
107
+ does in production, so a game's code cannot call the console's API. A gateway
108
+ that serves each port on its own hostname needs all three set; one that keeps
109
+ the ports and adds TLS needs only `--public-url`. With none set, nothing
110
+ changes.
111
+
112
+ The server still listens on the ports it prints, so point the gateway at those:
113
+ the console's port, the asset port, and the Vite port for hot reload.
114
+
115
+ ### Colour scheme and brand
116
+
117
+ The console keeps its colour scheme and brand in its own browser storage,
118
+ which a page on another origin cannot write. So the framing page says what it
119
+ wants in the console's URL:
120
+
121
+ - `?scheme=light`, `?scheme=dark` or `?scheme=system`: the colour scheme
122
+ - `?brand=<id>`: one of the brands the server offers, by the identifier its
123
+ **Brand** menu shows
124
+
125
+ Both apply from the first paint, last for the rest of that tab as the console
126
+ moves between its own pages, and never overwrite the viewer's stored choice.
127
+ Picking a scheme or brand in the dev drawer takes over from them. The scheme
128
+ reaches the game's surfaces exactly as the drawer's own scheme menu does.
129
+
130
+ To change the scheme later without a reload, post a message to the frame:
131
+
132
+ ```ts
133
+ frame.contentWindow?.postMessage({ type: 'sg-dev-scheme', scheme: 'dark' }, consoleOrigin);
134
+ ```
135
+
136
+ The console acts on it only when it is framed, and only from the page directly
137
+ around it. It does not check that page's origin, so any page that frames the
138
+ console can change its scheme: harmless for a colour scheme, and the reason the
139
+ message carries nothing else.
140
+
141
+ ### Hide the error overlay
142
+
143
+ When a surface fails to build, Vite draws a full-screen error overlay over it.
144
+ In a preview watched by people who are not developers, that reads as the game
145
+ being broken, and it is often a passing state: part way through an edit, one
146
+ file can import another that is not written yet. Turn the overlay off:
147
+
148
+ ```bash
149
+ pnpm run sdk dev --no-error-overlay
150
+ ```
151
+
152
+ Or set `SERIOUSGAMING_DEV_ERROR_OVERLAY=false`, which also reaches a server a
153
+ command starts in the background. The error still appears in the server's log
154
+ and the browser console, and `sdk screenshot` still reports the failure with the
155
+ page's other problems. Without either, the package's own Vite config decides, and
156
+ Vite shows the overlay by default.
157
+
83
158
  ## How a command finds the session
84
159
 
85
160
  `.seriousgaming-sdk/session.json` is a **lock file**, not state:
@@ -124,6 +199,10 @@ the thing to know before a test fixture calls a session command: whatever runs
124
199
  first starts the session, and in Vitest a `describe` body runs at collection
125
200
  time, before any `beforeAll`.
126
201
 
202
+ It runs until `sdk dev stop`, or until its package directory is removed: a
203
+ background server whose package has gone stops itself within a second or so,
204
+ so deleting a scratch game, or a test's temporary copy, leaves nothing running.
205
+
127
206
  A server started this way has no flag to take a port from, so it reads
128
207
  `SERIOUSGAMING_DEV_PORT` (from the environment or `.env`), and falls back to 3000. Either way it steps up to the first free port from there.
129
208