@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
@@ -0,0 +1,263 @@
1
+ # Styling and building user interfaces
2
+
3
+ How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** i18n, internationalisation, theme, styling, dark mode, Material-UI, MUI, contrastText, mobile, viewport, dvh, Vite, vite.config.ts
8
+
9
+ ## Using internationalisation
10
+
11
+ The wrapper sets `lang` and `dir` on the document root from the locale (`dir="rtl"` for Arabic, Hebrew, Persian, Urdu and any other right-to-left script) and keeps them in step when the facilitator changes language, so a surface does not set them itself. It also sets the root's `color-scheme` to the theme's mode, so scrollbars and native form controls follow a dark theme without MUI.
12
+
13
+ Use React i18next for multi-language support:
14
+
15
+ ```typescript
16
+ import { useTranslation } from 'react-i18next';
17
+ import { useUserInterfaceLocale } from '@seriousgaming/sdk/ui';
18
+
19
+ function Dashboard() {
20
+ const { t } = useTranslation();
21
+ const { locale } = useUserInterfaceLocale();
22
+
23
+ return (
24
+ <div>
25
+ <h1>{t('dashboard.title')}</h1>
26
+ <p>{t('dashboard.welcome')}</p>
27
+ <p>Current language: {locale}</p>
28
+ </div>
29
+ );
30
+ }
31
+ ```
32
+
33
+ Update your `src/i18n.ts`:
34
+
35
+ ```typescript
36
+ import i18n from 'i18next';
37
+ import { initReactI18next } from 'react-i18next';
38
+
39
+ const resources = {
40
+ en: {
41
+ translation: {
42
+ 'dashboard.title': 'Dashboard',
43
+ 'dashboard.welcome': 'Welcome',
44
+ 'inventory.label': 'Stock Level',
45
+ 'revenue.label': 'Revenue',
46
+ },
47
+ },
48
+ es: {
49
+ translation: {
50
+ 'dashboard.title': 'Panel de Control',
51
+ 'dashboard.welcome': 'Bienvenido',
52
+ 'inventory.label': 'Nivel de Stock',
53
+ 'revenue.label': 'Ingresos',
54
+ },
55
+ },
56
+ };
57
+
58
+ i18n.use(initReactI18next).init({
59
+ resources,
60
+ lng: 'en',
61
+ interpolation: { escapeValue: false },
62
+ });
63
+
64
+ export default i18n;
65
+ ```
66
+
67
+ ## Theming and styling
68
+
69
+ Serious Gaming provides a theming system that allows your user interfaces to adapt to the host environment's look and feel. This is handled through the `@seriousgaming/sdk` package.
70
+
71
+ ### Accessing theme information
72
+
73
+ You can access the current theme information within your components using the `useUserInterfaceTheme` hook.
74
+
75
+ ```typescript
76
+ import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
77
+
78
+ function MyComponent() {
79
+ const theme = useUserInterfaceTheme();
80
+ // theme.mode will be 'light' or 'dark'
81
+ // theme.light and theme.dark will contain color palettes
82
+
83
+ return (
84
+ <div style={% raw %}{{{% endraw %} background: theme.mode === 'light' ? theme.light.primary : theme.dark.primary {% raw %}}}{% endraw %}>
85
+ My Component
86
+ </div>
87
+ );
88
+ }
89
+ ```
90
+
91
+ ### Theme object structure
92
+
93
+ The `theme` object returned by `useUserInterfaceTheme` has the following structure:
94
+
95
+ ```typescript
96
+ type UserInterfaceTheme = {
97
+ mode: 'dark' | 'light';
98
+ dark: UserInterfaceModeColors;
99
+ light: UserInterfaceModeColors;
100
+ };
101
+
102
+ type UserInterfaceModeColors = {
103
+ primary: string;
104
+ secondary: string;
105
+ success: string;
106
+ error: string;
107
+ warning: string;
108
+ info: string;
109
+ contrastText: {
110
+ primary: string;
111
+ secondary: string;
112
+ success: string;
113
+ error: string;
114
+ warning: string;
115
+ info: string;
116
+ };
117
+ };
118
+ ```
119
+
120
+ - `mode`: Indicates whether the current theme is `'light'` or `'dark'`
121
+ - `light`: An object containing the colour palette for the light theme
122
+ - `dark`: An object containing the colour palette for the dark theme
123
+ - `contrastText`: The text colour to draw on each palette colour, an opaque `#rrggbb` the host guarantees meets WCAG AA (4.5:1) against it. Use it rather than computing your own: the theme's author may have chosen one, and the host keeps it when it passes
124
+
125
+ ```tsx
126
+ const colors = theme.mode === 'light' ? theme.light : theme.dark;
127
+
128
+ <span style={% raw %}{{{% endraw %} background: colors.primary, color: colors.contrastText.primary {% raw %}}}{% endraw %}>Live</span>
129
+ ```
130
+
131
+ Passing `contrastText` through to Material-UI, as the template's `theme.ts` does (below), means every contained button and chip already uses it.
132
+
133
+ ### Reading the host's theme preference
134
+
135
+ `useUserInterfaceTheme` gives you the resolved palette, but `theme.mode` only tells you the colours to paint right now. It cannot tell you whether the host is following the operating system or has been pinned to a specific scheme. When you need that distinction, read the host's preference with the `useUserInterfaceThemePreference()` hook. It returns `'light'`, `'dark'`, or `'system'` and re-renders when the preference changes, exactly like `useUserInterfaceTheme()`:
136
+
137
+ ```typescript
138
+ import { useUserInterfaceThemePreference } from '@seriousgaming/sdk/ui';
139
+
140
+ function ThemePreferenceBadge() {
141
+ const preference = useUserInterfaceThemePreference();
142
+ return <span>Following: {preference}</span>;
143
+ }
144
+ ```
145
+
146
+ Each UI surface has its own hook: `useUserInterfaceThemePreference`, `useSessionUserInterfaceThemePreference`, and `useSettingsEditorThemePreference`.
147
+
148
+ A UI can also change the preference with the `setThemePreference` callback. The host applies it, persists it, and broadcasts the change back, so every other UI (and every theme-preference hook) sees it:
149
+
150
+ ```typescript
151
+ import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
152
+
153
+ function ThemeSwitcher() {
154
+ const callbacks = useUserInterfaceCallbacks();
155
+ return (
156
+ <>
157
+ <button onClick={() => callbacks.setThemePreference('light')}>Light</button>
158
+ <button onClick={() => callbacks.setThemePreference('dark')}>Dark</button>
159
+ <button onClick={() => callbacks.setThemePreference('system')}>System</button>
160
+ </>
161
+ );
162
+ }
163
+ ```
164
+
165
+ `setThemePreference` is available on every UI surface but the presentation (game, waiting room, session, setup and scenario editor). No `uses` declaration is needed, because theme preference is not gated.
166
+
167
+ ### Integrating with Material-UI
168
+
169
+ The default user interface template uses [Material-UI](https://mui.com/) for its component library. `createSurfaceTheme` turns the host's theme into MUI theme options: every colour role with its `contrastText`, the page, surface and text colours when the host sends them, and the host brand's fonts. Pass it to `createTheme` first, with your own shape and component overrides after it:
170
+
171
+ ```typescript
172
+ // src/theme.ts
173
+ import { createTheme } from '@mui/material/styles';
174
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
175
+ import { useMemo } from 'react';
176
+
177
+ export const useAppTheme = () => {
178
+ const theme = useUserInterfaceTheme();
179
+ return useMemo(
180
+ () =>
181
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
182
+ shape: { borderRadius: 10 },
183
+ }),
184
+ [theme]
185
+ );
186
+ };
187
+ ```
188
+
189
+ `fonts.body` is the font your game bundles, used whenever the host's brand names none. By using `useMemo`, you ensure that the theme object is only recreated when the theme context from Serious Gaming changes, which is important for performance.
190
+
191
+ For the host's logo and name, its fonts, and how to preview a game in someone else's brand, see [Theming and branding](./theming-and-branding.md).
192
+
193
+ ## Sizing to the viewport on mobile
194
+
195
+ The host sizes your UI's iframe to the visible viewport, so size your UI to fill its container rather than the browser viewport: prefer `height: 100%` (down through `html`, `body`, and the root element) with flex or grid layouts over viewport units.
196
+
197
+ If you do reach for viewport units, use `dvh` with a `vh` fallback. On iOS WebKit `100vh` resolves to the tall (URL-bar-collapsed) viewport even while the bar is showing, so a `100vh` element runs off the bottom of the screen; `100dvh` tracks the live visible viewport:
198
+
199
+ ```css
200
+ min-height: 100vh; /* fallback for older browsers */
201
+ min-height: 100dvh; /* tracks the live viewport on iOS */
202
+ ```
203
+
204
+ In MUI `sx`, where you cannot repeat a key, express the fallback with `@supports`:
205
+
206
+ ```ts
207
+ sx={{ minHeight: '100vh', '@supports (height: 100dvh)': { minHeight: '100dvh' } }}
208
+ ```
209
+
210
+ Embedded in the host this rarely bites, because an iframe has no collapsing browser chrome and `vh` resolves to the iframe's own height. The `dvh` form keeps your UI correct if it is ever opened standalone in a mobile browser, and the scaffold templates already follow it.
211
+
212
+ ## Customising Vite (dev and build)
213
+
214
+ When the SDK starts Vite for your UI (whether for the dev server or a production build), you can customise Vite's behaviour by creating a `vite.config.ts` file. The SDK loads it and merges it with its own inline config.
215
+
216
+ ### Where to put `vite.config.ts`
217
+
218
+ **Put it at the project root** (alongside `seriousgaming.sdk.json`). This is the recommended location: one file applies to every UI in the package, and the same file is used by both `sdk dev` and `sdk build`.
219
+
220
+ ```
221
+ my-package/
222
+ ├── seriousgaming.sdk.json
223
+ ├── vite.config.ts ← recommended location
224
+ ├── ui/
225
+ │ ├── index.html
226
+ │ └── src/
227
+ └── session/
228
+ └── ...
229
+ ```
230
+
231
+ ### Per-UI overrides
232
+
233
+ You can also drop a `vite.config.ts` inside an individual `ui/` directory. The SDK loads it in addition to the project-root config and the per-UI file's values override the root's on conflicts. This is useful when one UI needs a specific alias or plugin that would break the others, but in practice the root config is almost always enough, and per-UI files multiply maintenance.
234
+
235
+ **Don't keep both a root config and a per-UI config for the same UI unless you really mean to.** If the SDK finds both while building a given UI it prints a warning and asks you to consolidate. Merging still happens so the build doesn't break, but the warning is telling you that the intent is unclear.
236
+
237
+ ### What merges and what doesn't
238
+
239
+ The merge order is:
240
+
241
+ ```
242
+ project-root vite.config.ts → ui/vite.config.ts → SDK inline config
243
+ (baseline) (overrides root) (SDK owns these)
244
+ ```
245
+
246
+ **Additive options merge cleanly.** `resolve.dedupe`, `resolve.alias`, `optimizeDeps.include`, `esbuild`, extra `plugins`, and similar fields are not set (or only partially set) by the SDK, so your entries are combined with the SDK's.
247
+
248
+ **The SDK wins on structural fields.** `root`, `base`, `build.outDir`, `build.rollupOptions.input`, and the dev-server `server.middlewareMode`/`appType`/`hmr` settings are owned by the SDK and cannot be overridden: trying to set them in `vite.config.ts` has no effect.
249
+
250
+ A common use case is preventing duplicate package instances when using third-party React libraries:
251
+
252
+ ```typescript
253
+ // vite.config.ts (project root)
254
+ import { defineConfig } from 'vite';
255
+
256
+ export default defineConfig({
257
+ resolve: {
258
+ dedupe: ['react', 'react-dom'],
259
+ },
260
+ });
261
+ ```
262
+
263
+ See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md) for a full explanation of when and why this is needed.
@@ -0,0 +1,247 @@
1
+ # Ticks and the timer in user interfaces
2
+
3
+ How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** requestTick, tick, end round, MutationError, MutationOutcome, await setData, tick timer, countdown, nextTickAt, pause, resume, simulated game time
8
+
9
+ ## Requesting a tick
10
+
11
+ User interfaces advance the game to the next tick using the `requestTick` callback. This is how games provide their 'Submit' control. There is no built-in next tick button, so every game that ticks manually needs one of these.
12
+
13
+ ```typescript
14
+ import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
15
+
16
+ function DecisionPanel() {
17
+ const callbacks = useUserInterfaceCallbacks();
18
+
19
+ const handleSubmit = () => {
20
+ callbacks.requestTick?.();
21
+ };
22
+
23
+ return (
24
+ <button onClick={handleSubmit}>
25
+ Submit Decision
26
+ </button>
27
+ );
28
+ }
29
+ ```
30
+
31
+ During development, the dev drawer (press the backtick key) also has a developer-only **Tick** button, so you can advance the game before your control exists.
32
+
33
+ See [Host controls](./games.md#host-controls) for what the host renders and what is left to your game.
34
+
35
+ ### Combining setData with requestTick
36
+
37
+ A common pattern is to update context and immediately request a tick: for example, a 'Start exercise' button that sets an initial value and advances the game:
38
+
39
+ ```typescript
40
+ const handleStart = () => {
41
+ setData({ exercise: { Started: true } });
42
+ callbacks.requestTick?.();
43
+ };
44
+ ```
45
+
46
+ This works correctly: the `setData` change is merged into context immediately, and the tick that follows will see `Started: true` when the engine runs. However, there is a brief intermediate state that is worth understanding:
47
+
48
+ 1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away
49
+ 2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds
50
+ 3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results
51
+ 4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values
52
+
53
+ In most cases this intermediate state is invisible to the participant, because the tick completes in milliseconds. But if your UI derives display values from both `setData` fields and engine-computed fields, you may see a brief flicker. Two strategies to handle this:
54
+
55
+ **Option A: UI-level loading state**: set a local loading flag before requesting the tick, and clear it when new context arrives:
56
+
57
+ ```typescript
58
+ const [ticking, setTicking] = useState(false);
59
+
60
+ const handleStart = () => {
61
+ setData({ exercise: { Started: true } });
62
+ setTicking(true);
63
+ callbacks.requestTick?.();
64
+ };
65
+
66
+ // Clear on next context push (setData from host resets the component)
67
+ useEffect(() => {
68
+ setTicking(false);
69
+ }, [data]);
70
+ ```
71
+
72
+ **Option B: Drive display from engine-computed values only**: if possible, have your UI read from the engine's output capability rather than from the raw `setData` input. The engine output is only updated after the tick, so there is no intermediate state.
73
+
74
+ ### Awaiting state changes
75
+
76
+ `setData` and `requestTick` each return a promise, as do a session UI's `undoTick` and `resetGame` and a setup screen or scenario editor's `updateSettings`. It resolves once the operation has committed (a `setData` once the write is persisted, a `requestTick` once that tick has finished and context is updated) and rejects with a `MutationError` when it fails. The error's `outcome` is a discriminated union you can branch on:
77
+
78
+ - `conflict`: the write lost a race with a tick, and the runtime retried it itself and gave up. A person may try again; your code never retries it on its own
79
+ - `superseded`: what the operation addressed has already moved on because somebody else did the same thing, such as a tick button pressed twice. Terminal but not a failure: the state is what the caller asked for
80
+ - `validation-rejected`: a validator rejected the write; `outcome.rejections` carries the same detail delivered to `useUserInterfaceValidationRejections`
81
+ - `denied`: the operation was not permitted (for example, a write of a capability this UI does not declare in `writes`)
82
+ - `tick-failed`: the tick could not run (tick limit reached, game complete, or the executor threw)
83
+ - `error`: anything else unexpected
84
+
85
+ The list is closed, so a `switch` over `outcome.kind` can be exhaustive. A kind a later release adds reaches only a game that declares the feature that adds it in `requires`; any other game is told `error`.
86
+
87
+ Reach for `useMutationReporter` rather than branching by hand. It awaits the write, tracks whether one is in flight, and hands you the failure to render:
88
+
89
+ ```tsx
90
+ import { useMutationReporter } from '@seriousgaming/sdk/ui';
91
+
92
+ const { run, pending, failure, dismiss } = useMutationReporter();
93
+
94
+ <Button disabled={pending} onClick={() => run(() => setData({ exercise: { Revenue: 100 } }))}>
95
+ {t('save')}
96
+ </Button>;
97
+ {
98
+ failure && (
99
+ <Alert
100
+ onClose={dismiss}
101
+ action={failure.retry && <Button onClick={failure.retry}>{t('tryAgain')}</Button>}
102
+ >
103
+ {t('saveFailed')}
104
+ </Alert>
105
+ );
106
+ }
107
+ ```
108
+
109
+ `setData` also resolves with which tick the write landed in. If a participant submits as the tick is being processed the write commits into the next one, and `reporter.late` says so, carrying both the tick composed against and the tick committed into. That is not a failure (the write is in), but nothing else on screen distinguishes it from a decision that arrived in time.
110
+
111
+ **The host retries; your surface never does.** A runtime using optimistic concurrency retries a losing write itself before it reports one, so a `conflict` reaching a surface is a write the host has already retried and given up on, and a surface must never retry it automatically. What a person can do is try again, so on a `conflict` (and only then) `failure.retry` is set: it runs the same operation again, resolving as `run` does. Put it behind a 'Try again' button, as the snippet above does, and never call it from an effect or a timer.
112
+
113
+ Ignoring the returned promise still compiles, but it is a hazard rather than a convenience: the local view merges the change the moment it is sent, so a refused write leaves the participant looking at a decision the game never received. A no-floating-promises lint rule may start flagging unawaited calls; route them through `run` rather than marking them with `void`.
114
+
115
+ > Note: against a hosted runtime that does not yet send the correlated acknowledgement, an awaited mutation stays pending until the connection resets. The dev server always responds, so promises settle promptly in local development.
116
+
117
+ ## Displaying the tick timer
118
+
119
+ When a game uses an automatic [tick controller](./tick-controller.md), the host pushes the current schedule to every UI via the `useUserInterfaceTimer` hook, as a `TimerState`. Use this when you want your UI to show its own countdown: for example, a circular progress bar in the corner of a Decisions panel, or a floating 'Next tick in 12s' badge on a results screen.
120
+
121
+ ```typescript
122
+ import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
123
+
124
+ function NextTickBadge() {
125
+ const { enabled, paused, nextTickAt, intervalMs } = useUserInterfaceTimer();
126
+
127
+ if (!enabled || nextTickAt === null) {
128
+ return null; // manual game, or no tick currently scheduled
129
+ }
130
+
131
+ const remainingMs = nextTickAt - Date.now();
132
+ return <span>Next tick in {Math.ceil(remainingMs / 1000)}s</span>;
133
+ }
134
+ ```
135
+
136
+ The fields are those of [`TimerState`](../api/sdk-ui.md#timerstate), the one timer shape every surface reads. Durations are milliseconds and end in `Ms`; timestamps are milliseconds since the epoch, in `Date.now()` space, and end in `At`. Which field to reach for:
137
+
138
+ - **`enabled`** is false for a manual-tick game, or once the controller stops scheduling: hide the countdown
139
+ - **`nextTickAt - Date.now()`** is the time left, and **`intervalMs`** the length of the window, for a progress bar. Both are `null` when nothing is scheduled
140
+ - **`paused`** and **`pausedAt`** say whether, and since when, the host has paused ticking
141
+ - **`extendedMs`** is how far a facilitator has moved the current deadline (negative when pulled in), reset with each new tick. Read it to say 'extended by 2m' rather than inferring that from a moved `nextTickAt`
142
+ - **`scheduleStartedAt`** and **`pausedMs`** drive a [simulated game clock](#simulated-game-time)
143
+
144
+ The hook always returns a value: there is no 'loading' state. Before any timer message has arrived, and for games that don't use a tick controller at all, it returns a disabled timer: `enabled` and `paused` false, every timestamp and `intervalMs` `null`, and `pausedMs` and `extendedMs` 0. The `enabled` check is enough to hide the countdown for manual games without any extra branching.
145
+
146
+ ### Driving the countdown
147
+
148
+ The hook only fires when the _schedule_ changes: typically once per tick (when the next interval is computed) plus pause/resume events. It does **not** push a new value every second. UIs that want a live ticking countdown must run their own loop locally:
149
+
150
+ ```typescript
151
+ import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
152
+ import { useEffect, useState } from 'react';
153
+
154
+ function NextTickCountdown() {
155
+ const { enabled, paused, nextTickAt, intervalMs } = useUserInterfaceTimer();
156
+ const [remainingMs, setRemainingMs] = useState(() =>
157
+ nextTickAt === null ? 0 : Math.max(0, nextTickAt - Date.now())
158
+ );
159
+
160
+ useEffect(() => {
161
+ if (!enabled || nextTickAt === null) {
162
+ setRemainingMs(0);
163
+ return;
164
+ }
165
+ if (paused) {
166
+ // Hold the displayed value steady while paused.
167
+ setRemainingMs(Math.max(0, nextTickAt - Date.now()));
168
+ return;
169
+ }
170
+ let raf = 0;
171
+ const loop = () => {
172
+ setRemainingMs(Math.max(0, nextTickAt - Date.now()));
173
+ raf = requestAnimationFrame(loop);
174
+ };
175
+ raf = requestAnimationFrame(loop);
176
+ return () => cancelAnimationFrame(raf);
177
+ }, [enabled, paused, nextTickAt]);
178
+
179
+ if (!enabled || nextTickAt === null) return null;
180
+
181
+ const seconds = Math.ceil(remainingMs / 1000);
182
+ const progress = intervalMs ? 1 - remainingMs / intervalMs : 0;
183
+ return (
184
+ <div>
185
+ <span>{seconds}s</span>
186
+ <progress value={progress} max={1} />
187
+ </div>
188
+ );
189
+ }
190
+ ```
191
+
192
+ This pattern is deliberate: by keeping the per-frame state inside one leaf component, only that component re-renders 60 times a second, and the rest of your UI is untouched. If you instead put the live remaining time into a context or shared state, every consumer of that context would re-render on every frame, which can quickly become expensive in a non-trivial UI.
193
+
194
+ ### How `nextTickAt` and clocks interact
195
+
196
+ `nextTickAt` is an absolute timestamp in the **same clock-space as `Date.now()`**, so consumer code never needs to compute clock offsets: just subtract. The host is responsible for stamping it in a clock the consumer will recognise:
197
+
198
+ - For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is
199
+ - For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown
200
+
201
+ The wrapper does not attempt to re-translate `nextTickAt` on receipt. With only the value and the receiver's `Date.now()` it cannot distinguish 'the host's clock is N ms ahead of mine' from 'this message has been sitting around for N ms', and getting that wrong is exactly how a stored timer state replayed to a remounted iframe would drift. Trusting the timestamp verbatim is what makes the countdown stay accurate when the iframe is remounted.
202
+
203
+ ### Pause and resume
204
+
205
+ When the host pauses the timer (e.g. via the dev server's pause button: see [Pausing, resuming and extending](./tick-controller.md#pausing-resuming-and-extending) in the tick controller guide), the hook returns `{ enabled: true, paused: true, nextTickAt: null, intervalMs: null }`. The `nextTickAt: null` tells you there is no scheduled fire-time to count down toward; freeze your displayed value rather than letting it tick to zero. When the host resumes, a new schedule is pushed and the countdown picks up from the new `nextTickAt`.
206
+
207
+ If you want the displayed value to _freeze_ at the moment of pause (rather than disappear), capture the last non-null `nextTickAt` in a ref:
208
+
209
+ ```typescript
210
+ const lastScheduledRef = useRef<number | null>(null);
211
+ useEffect(() => {
212
+ if (nextTickAt !== null) lastScheduledRef.current = nextTickAt;
213
+ }, [nextTickAt]);
214
+
215
+ const displayTick = nextTickAt ?? lastScheduledRef.current;
216
+ ```
217
+
218
+ ### Simulated game time
219
+
220
+ If your game compresses real time into simulated time (e.g. 1 real second = 1 simulated hour), you need a clock that advances with wall time but freezes during pauses. The `pausedAt`, `pausedMs`, and `scheduleStartedAt` fields make this possible without any client-side persistence:
221
+
222
+ ```typescript
223
+ import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
224
+
225
+ const COMPRESSION = 3600; // 1 real second = 1 simulated hour
226
+
227
+ function SimulatedClock() {
228
+ const { scheduleStartedAt, pausedMs, pausedAt } = useUserInterfaceTimer();
229
+
230
+ if (scheduleStartedAt === null) return null;
231
+
232
+ // Effective elapsed time = wall time minus all pauses (completed + current)
233
+ const effectiveElapsedMs =
234
+ (Date.now() - scheduleStartedAt)
235
+ - pausedMs
236
+ - (pausedAt ? Date.now() - pausedAt : 0);
237
+
238
+ const simMinutes = Math.floor((effectiveElapsedMs * COMPRESSION) / 60_000);
239
+ const hours = Math.floor(simMinutes / 60);
240
+ const mins = simMinutes % 60;
241
+ return <span>{hours}h {mins}m</span>;
242
+ }
243
+ ```
244
+
245
+ `pausedMs` accumulates the duration of all _completed_ pauses. It does not include the pause currently in progress, which is derived live from `pausedAt`. This avoids the host having to push updates during a pause while still giving clients a fully accurate value at any instant.
246
+
247
+ Both `pausedMs` and `scheduleStartedAt` reset when the tick controller disables ticking (returns `enabled: false` or `null`). They are **not** reset when the game reaches max ticks or is marked complete, so UIs can still display the final session time after the game ends.