@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,365 @@
1
+ # Running the game from a session UI
2
+
3
+ How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
4
+
5
+ It is part of [Building session UIs](./session.md), which covers creating the surface and reading and writing session data.
6
+
7
+ **Keywords:** session controls, requestTick, pauseTimer, resumeTimer, extendTick, host overlays, undoTick, resetGame, waiting room, setLocale, roster, delete team, move participant, participant list
8
+
9
+ ## Controlling game flow
10
+
11
+ Session UIs have full control over the game lifecycle via callbacks. Every game-flow callback accepts an optional `teamId`; when it is omitted the action applies to all teams.
12
+
13
+ Every game-flow callback except `pauseTimer` and `resumeTimer` returns a promise that resolves once the host has committed the change, and rejects with a `MutationError` when it will not. Await it when you want to report the outcome honestly; ignore it when you do not. Either way the resulting state arrives through the normal session data channel.
14
+
15
+ ### Triggering ticks
16
+
17
+ ```typescript
18
+ import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
19
+ import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
20
+ import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
21
+ import { Button, Stack } from '@mui/material';
22
+
23
+ function TickControls() {
24
+ const { requestTick } = useSessionUserInterfaceCallbacks();
25
+ const teams = useSessionUserInterfaceTeams();
26
+ const { mode } = useSessionUserInterfaceTeamConfiguration();
27
+
28
+ return (
29
+ <Stack spacing={1}>
30
+ <Button onClick={() => requestTick()} variant="contained">
31
+ Advance All Teams
32
+ </Button>
33
+ {mode === 'independent' &&
34
+ teams.map((team) => (
35
+ <Button
36
+ key={team.teamId}
37
+ onClick={() => requestTick(team.teamId)}
38
+ variant="outlined"
39
+ >
40
+ Advance {team.name}
41
+ </Button>
42
+ ))}
43
+ </Stack>
44
+ );
45
+ }
46
+ ```
47
+
48
+ The session UI's `requestTick` control is how facilitators advance the game: there is no built-in next tick button. The scaffolded session UI wires a session-wide tick button out of the box; during development the console's dev drawer also has a developer-only **Tick** button.
49
+
50
+ ### Pausing and resuming the timer
51
+
52
+ When a game uses a [tick controller](./tick-controller.md) with automatic ticking, facilitators can pause and resume per-team or globally:
53
+
54
+ ```typescript
55
+ import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
56
+ import { Button, Stack } from '@mui/material';
57
+
58
+ function TimerControls({ teamId }: { teamId?: string }) {
59
+ const { pauseTimer, resumeTimer } = useSessionUserInterfaceCallbacks();
60
+
61
+ return (
62
+ <Stack direction="row" spacing={1}>
63
+ <Button onClick={() => pauseTimer(teamId)} variant="outlined" color="warning">
64
+ {teamId ? `Pause ${teamId}` : 'Pause All'}
65
+ </Button>
66
+ <Button onClick={() => resumeTimer(teamId)} variant="contained" color="success">
67
+ {teamId ? `Resume ${teamId}` : 'Resume All'}
68
+ </Button>
69
+ </Stack>
70
+ );
71
+ }
72
+ ```
73
+
74
+ While paused, manual ticks via `requestTick` still work. Timer state for each team is available in `sessionData.teams[teamId].timer`.
75
+
76
+ ### Extending a tick
77
+
78
+ Pausing is the wrong tool for 'give them two more minutes'. It stops the clock until someone remembers to start it again, and it does not move the deadline your countdown is drawn from. `extendTick` moves the deadline instead. It takes milliseconds:
79
+
80
+ ```typescript
81
+ import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
82
+ import { Button, Stack } from '@mui/material';
83
+
84
+ function ExtendControls({ teamId }: { teamId?: string }) {
85
+ const { extendTick } = useSessionUserInterfaceCallbacks();
86
+
87
+ return (
88
+ <Stack direction="row" spacing={1}>
89
+ <Button onClick={() => void extendTick(120_000, teamId)}>+2 min</Button>
90
+ <Button onClick={() => void extendTick(-30_000, teamId)}>-30 sec</Button>
91
+ </Stack>
92
+ );
93
+ }
94
+ ```
95
+
96
+ Three things worth knowing:
97
+
98
+ - **It moves one window, not the cadence.** The interval your tick controller returns for later ticks is untouched, so a session does not run permanently late because one tick ran long
99
+ - **A negative value pulls the deadline in**, clamped at now. It never fires a tick retroactively
100
+ - **Read the result back from `extendedMs`** on the team's timer rather than inferring it from a moved `nextTickAt`. A deadline that jumped is equally the signature of a freshly scheduled tick, so `extendedMs` is the only honest source for 'extended by 2m'
101
+
102
+ ```typescript
103
+ const { extendedMs } = sessionData.teams[teamId].timer;
104
+ ```
105
+
106
+ It rejects with a `MutationError` carrying `{ kind: 'denied' }` when there is no tick to move: automatic ticking is off, the game is complete, or the timer is paused. Resume first, then extend.
107
+
108
+ Deliberately, the [tick interval bounds](./tick-controller.md) do not apply. They bound the cadence a tick controller may schedule; a facilitator in the room already reaches outside both with an immediate `requestTick` and an indefinite `pauseTimer`.
109
+
110
+ ### Opening host overlays
111
+
112
+ Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet, your [presentation](./presentation.md). Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
113
+
114
+ `openHostOverlay` asks. The host renders the overlay in its own chrome, over your session UI or in a window of its own, where you can neither restyle nor suppress it. Which is the host's choice: a deck usually gets a window, so the facilitator can put it on the projector and keep your session UI on their own screen:
115
+
116
+ ```typescript
117
+ import {
118
+ useSessionUserInterfaceCallbacks,
119
+ useSessionUserInterfaceHostOverlays,
120
+ } from '@seriousgaming/sdk/ui';
121
+ import { Button, Stack } from '@mui/material';
122
+
123
+ function OverlayControls() {
124
+ const overlays = useSessionUserInterfaceHostOverlays();
125
+ const { openHostOverlay } = useSessionUserInterfaceCallbacks();
126
+
127
+ return (
128
+ <Stack direction="row" spacing={1}>
129
+ {overlays.includes('facilitator-guide') && (
130
+ <Button onClick={() => void openHostOverlay('facilitator-guide')}>Guide</Button>
131
+ )}
132
+ {overlays.includes('print-sheets') && (
133
+ <Button onClick={() => void openHostOverlay('print-sheets')}>Print sheets</Button>
134
+ )}
135
+ {overlays.includes('presentation') && (
136
+ <Button onClick={() => void openHostOverlay('presentation')}>Presentation</Button>
137
+ )}
138
+ </Stack>
139
+ );
140
+ }
141
+ ```
142
+
143
+ **Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change when the game is reloaded, for example when a guide is added or removed.
144
+
145
+ The second argument narrows the overlay:
146
+
147
+ | Overlay | Second argument | Omitted means |
148
+ | --------------------- | ------------------------------------------------ | --------------------------------- |
149
+ | `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
150
+ | `'print-sheets'` | A team id | Every team |
151
+ | `'presentation'` | None: a game holds one deck, and one is ignored | The game's deck, for this session |
152
+
153
+ It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
154
+
155
+ **The presentation needs `presentation-overlay` in `requires`.** A host offers `'presentation'` only to a game that ships a `presentation/` slot and lists the feature in `seriousgaming.sdk.json`:
156
+
157
+ ```json
158
+ {
159
+ "requires": ["presentation-overlay"]
160
+ }
161
+ ```
162
+
163
+ Listing it means a host that cannot open the deck this way refuses the game rather than running it without the button, so list it only if your session UI offers the control. The deck opens for the current session, on the slide the facilitator left it on.
164
+
165
+ **Prefer the host's print sheets to your own.** A host's sheet carries the brand of the organisation running the session, with its join details in the form the host chose, so offer `'print-sheets'` wherever the host does. Draw your own sheet only where it does not, from [`useSessionUserInterfaceTeamLinks`](./session-hooks.md#usesessionuserinterfaceteamlinks), and put the host's logo on it with `useBrandLogo()` (see [Theming and branding](./theming-and-branding.md)), so a white-label session never prints your game's identity, or nobody's.
166
+
167
+ ### Undoing and resetting
168
+
169
+ Facilitators can revert the last tick or reset games, targeted at a specific team or all teams:
170
+
171
+ ```typescript
172
+ import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
173
+ import { Button, Stack } from '@mui/material';
174
+
175
+ function GameControls() {
176
+ const { undoTick, resetGame } = useSessionUserInterfaceCallbacks();
177
+
178
+ return (
179
+ <Stack direction="row" spacing={1}>
180
+ <Button onClick={() => undoTick()} variant="outlined">
181
+ Undo All Teams
182
+ </Button>
183
+ <Button onClick={() => resetGame()} variant="outlined" color="error">
184
+ Reset All Teams
185
+ </Button>
186
+ </Stack>
187
+ );
188
+ }
189
+ ```
190
+
191
+ - **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`
192
+ - **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved
193
+
194
+ Undo lets a team try a round again without penalty, which supports psychological safety: people experiment more freely when a mistake can be taken back.
195
+
196
+ ### Opening and closing the waiting room
197
+
198
+ `setWaitingRoom` parks the session: every participant's game UI is replaced with the game's [waiting room UI](./waiting-room.md) until you close it again.
199
+
200
+ ```typescript
201
+ const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
202
+
203
+ <Button onClick={() => setWaitingRoom(true)} variant="outlined">
204
+ Open waiting room
205
+ </Button>
206
+ ```
207
+
208
+ - **`setWaitingRoom(open)`** takes **no `teamId`**, unlike every other control above. The waiting room is one flag for the whole session, so there is no per-team variant to target
209
+ - Game state is untouched in both directions. Per-team context, the current tick, and timers all survive, which is the point: park a live session for a discussion and resume exactly where teams were
210
+ - It does not stop the clock. Automatic ticks keep firing while participants wait; halting play is the tick controller's decision, via `waitingRoomOpen`
211
+ - It resolves once the host confirms the change and rejects with a `MutationError` otherwise
212
+
213
+ The host provides its own toggle too, so building one is optional. Reach for this when you want the control to sit inside your own facilitator layout, or to pair it with a note you set on a shared capability at the same moment.
214
+
215
+ ### Changing the language
216
+
217
+ `setLocale` changes the session's language: the locale every surface is sent, and your logic reads, from then on. It is the change the host's own language picker makes, for a session UI that owns the whole canvas:
218
+
219
+ ```typescript
220
+ const meta = useSessionUserInterfaceMeta();
221
+ const { locale } = useSessionUserInterfaceLocale();
222
+ const { setLocale } = useSessionUserInterfaceCallbacks();
223
+
224
+ {meta.canSetLocale && (
225
+ <Select value={locale} onChange={(event) => void setLocale(event.target.value)}>
226
+ <MenuItem value="en">English</MenuItem>
227
+ <MenuItem value="it">Italiano</MenuItem>
228
+ </Select>
229
+ )}
230
+ ```
231
+
232
+ - **Gate it on `meta.canSetLocale`.** A host that predates `setLocale` leaves it out, and may never answer the call, so a control shown there would hang
233
+ - **Offer only your `supportedLocales`.** Anything else is refused as `denied`, rather than swapped for the nearest language you do support
234
+ - **Render the locale you are sent**, not the one you asked for. The host's picker changes it too, and the last change wins
235
+ - It takes no `teamId`: the language is the session's
236
+
237
+ ### Controlling the roster
238
+
239
+ The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
240
+
241
+ ```typescript
242
+ const { createTeam, renameTeam, deleteTeam, renameParticipant, moveParticipant } =
243
+ useSessionUserInterfaceCallbacks();
244
+
245
+ await createTeam('Marketing'); // name is optional
246
+ await renameTeam('team-1', 'Sales');
247
+ await renameParticipant('participant-3', 'Sam');
248
+ await moveParticipant('participant-3', 'team-2');
249
+ await deleteTeam('team-3'); // independent mode, empty teams only
250
+ ```
251
+
252
+ Each resolves on commit and rejects with a `MutationError`. Three refusals arrive as `{ kind: 'denied' }`: the team count is at the effective maximum, a team is being added to a shared-state session (whose team count is fixed at creation, though the dev server relaxes that before the first tick as an authoring convenience), or the session is read-only. **A denial is terminal**: unlike `conflict`, waiting and re-sending cannot change the outcome, so surface it rather than looping.
253
+
254
+ Creating or erasing a participant is deliberately not exposed.
255
+
256
+ #### Deleting a team
257
+
258
+ `deleteTeam(teamId)` removes a team from an **independent-mode** session. Every runtime supports it, unlike `createTeam`, which a runtime may refuse. It is refused with `{ kind: 'denied' }` when:
259
+
260
+ - The session is shared-state, at any point, before the first tick included. A shared-state engine initialised over the whole cohort, so its team count is fixed for the session
261
+ - The team still has participants, connected or not. A participant is never erased, so move every one out with `moveParticipant` first
262
+ - It is the last team in the session
263
+ - The session does not hold the team, or is read-only
264
+
265
+ A deleted team's index is left as a gap, and no other team's index or id changes. The next `createTeam` takes the lowest free index back, as a new team with the default name: nothing of the deleted team returns with it. Undo never brings a deleted team back, and no hook fires.
266
+
267
+ Offer the control only where it can succeed, so a facilitator is not shown a button the host will refuse:
268
+
269
+ ```tsx
270
+ const { mode } = useSessionUserInterfaceTeamConfiguration();
271
+ const participants = useSessionUserInterfaceParticipants();
272
+ const { deleteTeam } = useSessionUserInterfaceCallbacks();
273
+
274
+ {
275
+ mode === 'independent' && (
276
+ <Button
277
+ disabled={teams.length <= 1 || participants.some((p) => p.teamId === team.teamId)}
278
+ onClick={() => void deleteTeam(team.teamId).catch(showDenial)}
279
+ >
280
+ Delete team
281
+ </Button>
282
+ );
283
+ }
284
+ ```
285
+
286
+ The host enforces every rule itself, so the disabled state is a convenience, not a guard. In the dev server every team starts with a placeholder participant, so move it out first, or add the team with `pnpm run sdk team add --participants 0`.
287
+
288
+ `renameTeam` is not the only writer. A team's own participants can rename it from a game UI or waiting room UI, so a session UI should render the name from `setTeamList` rather than from its own optimistic state: there is one name per team, not one per writer, and the last write wins. A blank name and one past the host's cap (60 characters) are both refused as terminal denials, for either writer.
289
+
290
+ #### Moving a participant
291
+
292
+ A move has a consequence worth designing for, and one that is easy to confuse it with:
293
+
294
+ - The participant's **browser loses local component state**, because their game UI remounts against the destination team. Ordinary remount behaviour, and rarely worth warning anyone about
295
+ - Their **earlier writes stay with the source team**. Anything they wrote through `setData` is in that team's context and does not travel, so they arrive with none of their own state
296
+
297
+ A move does not reset either team. The source team's context, including every pending pre-tick decision in it, is untouched.
298
+
299
+ The second consequence is what a game handles, and the mechanism is the [`participantMove` hook](./hooks.md): seed the destination on `phase: 'arrival'` the way `participantJoin` seeds a new participant. There is no transfer channel: a hook returns one team's context, so the departure hook's return value is invisible to arrival. A shared-state game carries state across through the shared store; an independent-mode game re-derives it. Warning a facilitator is the fallback for the case where it genuinely cannot be re-derived, not the default: they cannot implement a hook mid-session, so the warning is only useful where you already know re-seeding is impossible.
300
+
301
+ ## Working with participants
302
+
303
+ Session UIs can enumerate participants across all teams in the session. The hook uses the `Participant` type, which includes a `teamId` field for grouping participants by team.
304
+
305
+ ### Reading the participant list
306
+
307
+ ```typescript
308
+ import {
309
+ useSessionUserInterfaceParticipants,
310
+ type Participant,
311
+ } from '@seriousgaming/sdk/ui';
312
+ import { List, ListItem, ListItemText, Chip, Typography, Stack } from '@mui/material';
313
+
314
+ function AllParticipantsPanel() {
315
+ const participants = useSessionUserInterfaceParticipants();
316
+
317
+ // Group by team
318
+ const byTeam = participants.reduce<Record<string, Participant[]>>(
319
+ (acc, p) => {
320
+ (acc[p.teamId] ??= []).push(p);
321
+ return acc;
322
+ },
323
+ {}
324
+ );
325
+
326
+ return (
327
+ <>
328
+ {Object.entries(byTeam).map(([teamId, members]) => (
329
+ <div key={teamId}>
330
+ <Typography variant="h6">{teamId}</Typography>
331
+ <List>
332
+ {members.map((p) => (
333
+ <ListItem key={p.id}>
334
+ <ListItemText
335
+ primary={p.name}
336
+ />
337
+ <Chip
338
+ size="small"
339
+ label={p.connected ? 'Online' : 'Offline'}
340
+ color={p.connected ? 'success' : 'default'}
341
+ />
342
+ </ListItem>
343
+ ))}
344
+ </List>
345
+ </div>
346
+ ))}
347
+ </>
348
+ );
349
+ }
350
+ ```
351
+
352
+ The hook updates reactively whenever:
353
+
354
+ - A new participant joins any team
355
+ - A participant disconnects (`connected` flips to `false`; the entry stays so you can see who was here)
356
+
357
+ `Participant` exposes:
358
+
359
+ | Field | Type | Notes |
360
+ | ----------- | --------- | ------------------------------------------------------- |
361
+ | `id` | `string` | Stable identifier; survives reconnects within a session |
362
+ | `name` | `string` | Display name (defaults to `Participant N`) |
363
+ | `index` | `number` | Zero-based join order within the team |
364
+ | `connected` | `boolean` | Whether the participant has a live platform connection |
365
+ | `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
@@ -0,0 +1,205 @@
1
+ # Session UI hooks reference
2
+
3
+ Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
4
+
5
+ It is part of [Building session UIs](./session.md), which covers creating the surface and how its parts fit together.
6
+
7
+ **Keywords:** session hooks, useSessionUserInterfaceData, useSessionUserInterfaceTeams, useSessionUserInterfaceCallbacks, useSessionUserInterfaceParticipants, useSessionUserInterfaceTheme, message protocol, hooks reference
8
+
9
+ ## useSessionUserInterfaceData
10
+
11
+ Read session-wide data and write per-team overrides:
12
+
13
+ ```typescript
14
+ import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
15
+
16
+ const { sessionData, settings, setData } = useSessionUserInterfaceData();
17
+ // sessionData: SessionData, the shared store once (shared.context), and a teams map with each team's own context, tick, and timer
18
+ // setData(partial): writes shared capabilities session-wide
19
+ // settings: the settings resources this surface lists in `settings`, keyed by identifier (see Configuring the surface)
20
+ // setData(teamId, partial): merges partial context into the specified team's state
21
+ // Both forms take { deletes } last: setData(teamId, {}, { deletes: ['pinboard.Notes.p1'] })
22
+ ```
23
+
24
+ ## useSessionUserInterfaceTeams
25
+
26
+ Get the team list:
27
+
28
+ ```typescript
29
+ import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
30
+
31
+ const teams = useSessionUserInterfaceTeams();
32
+ // TeamInfo[]: an array of { teamId, index, name }, sorted by index
33
+ ```
34
+
35
+ ## useSessionUserInterfaceTeamConfiguration
36
+
37
+ Get the interaction mode and the bounds the host will hold the session UI to:
38
+
39
+ ```typescript
40
+ import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
41
+
42
+ const { mode, min, max, perTeam } = useSessionUserInterfaceTeamConfiguration();
43
+ // mode: 'independent' | 'shared-state'
44
+ // max: the effective maximum team count, already resolved as the lower of the
45
+ // game's declared maximum and the platform's own ceiling
46
+ // min, perTeam: advisory guidance to display, not rules to block on
47
+ ```
48
+
49
+ Every bound here is for rendering honest affordances. The host enforces all of them itself, so a surface that disables 'add team' at the maximum is being polite, not authoritative, and must still handle a denial.
50
+
51
+ ## useSessionUserInterfaceMeta
52
+
53
+ Read the session itself:
54
+
55
+ ```typescript
56
+ import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
57
+
58
+ const { sessionId, name, readOnly, waitingRoomOpen, joinPin, canSetLocale } =
59
+ useSessionUserInterfaceMeta();
60
+ ```
61
+
62
+ `canSetLocale` is `true` where the host accepts [`setLocale`](./session-game-flow.md#changing-the-language), and absent on a host that predates it.
63
+
64
+ `joinPin` is the code participants enter to join, or `null` when joining needs none. How joining is secured is up to the runtime, so it need not be a PIN and some runtimes never set it: render it as an opaque string, and hide the panel when it is `null`. `readOnly` marks a frozen session, so a surface can disable its own controls and explain why rather than offering affordances that will be denied. `waitingRoomOpen` is the current value of a flag the session UI can also write through `setWaitingRoom`; since the host usually renders its own waiting-room control too, read the result back rather than assuming your write won.
65
+
66
+ ## useSessionUserInterfaceTeamLinks
67
+
68
+ Get each team's facilitator-only URLs, so a game draws its own QR codes, and its own join sheets where the host offers no `'print-sheets'` overlay (see [Opening host overlays](./session-game-flow.md#opening-host-overlays)):
69
+
70
+ ```typescript
71
+ import { useSessionUserInterfaceTeamLinks } from '@seriousgaming/sdk/ui';
72
+
73
+ const teamLinks = useSessionUserInterfaceTeamLinks();
74
+ // TeamLinks[]: each { teamId, joinUrl, fallbackJoinUrl?, observeUrl }
75
+ ```
76
+
77
+ Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
78
+
79
+ ## useSessionUserInterfaceHostOverlays
80
+
81
+ Find out which host overlays this host offers, before rendering a control for one:
82
+
83
+ ```typescript
84
+ import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
85
+
86
+ const overlays = useSessionUserInterfaceHostOverlays();
87
+ // HostOverlay[]: 'facilitator-guide' | 'print-sheets' | 'presentation'
88
+ ```
89
+
90
+ Empty until the host answers, and empty is also the correct answer for a host that delegates none. It can change mid-session. See [Opening host overlays](./session-game-flow.md#opening-host-overlays).
91
+
92
+ ## useSessionUserInterfaceHookFailures
93
+
94
+ Report hook chains that threw, on the surface the facilitator is actually looking at:
95
+
96
+ ```typescript
97
+ import { useSessionUserInterfaceHookFailures } from '@seriousgaming/sdk/ui';
98
+
99
+ const { failures, clearFailures } = useSessionUserInterfaceHookFailures();
100
+ // failures: { signal, teamId, message }[], kept until cleared
101
+ ```
102
+
103
+ A hook failure is deliberately not a failed mutation: hooks fire after the change they react to is applied, so the mutation that triggered them has already settled. Reporting it as failed would invite retrying an action that worked.
104
+
105
+ ## useSessionUserInterfaceLocale
106
+
107
+ Get the current locale:
108
+
109
+ ```typescript
110
+ import { useSessionUserInterfaceLocale } from '@seriousgaming/sdk/ui';
111
+
112
+ const { locale } = useSessionUserInterfaceLocale();
113
+ ```
114
+
115
+ ## useSessionUserInterfaceTheme
116
+
117
+ Read the host's colour scheme and palettes (`{ mode, light, dark }`, the same shape as the game UI's theme). See [Using the theme](./session.md#using-the-theme) for turning it into an MUI theme:
118
+
119
+ ```typescript
120
+ import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
121
+
122
+ function MyComponent() {
123
+ const theme = useSessionUserInterfaceTheme();
124
+ const colours = theme.mode === 'light' ? theme.light : theme.dark;
125
+ return <div style={{ color: colours.primary }}>Session Dashboard</div>;
126
+ }
127
+ ```
128
+
129
+ ## useSessionUserInterfaceParticipants
130
+
131
+ Reactive list of participants across all teams in the session:
132
+
133
+ ```typescript
134
+ import { useSessionUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
135
+
136
+ function Roster() {
137
+ const participants = useSessionUserInterfaceParticipants();
138
+ return <div>{participants.length} participants across all teams</div>;
139
+ }
140
+ ```
141
+
142
+ Use this to enumerate participants for facilitator workflows like cross-team comparisons or session-wide reporting. See [Working with participants](./session-game-flow.md#working-with-participants) above for the full field reference.
143
+
144
+ ## useSessionUserInterfaceCallbacks
145
+
146
+ Session-level facilitator callbacks. This is a standalone interface (`SessionUserInterfaceCallbacks`): it does not extend `UserInterfaceCallbacks`. All game-flow callbacks accept an optional `teamId` parameter; omitting it targets all teams.
147
+
148
+ ```typescript
149
+ import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
150
+
151
+ const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
152
+ useSessionUserInterfaceCallbacks();
153
+ ```
154
+
155
+ | Callback | Signature | Description |
156
+ | -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
157
+ | `requestTick` | `(teamId?: string) => Promise<void>` | Advance the game by one tick; omit `teamId` to advance all teams |
158
+ | `pauseTimer` | `(teamId?: string) => Promise<void>` | Pause automatic ticking; omit `teamId` to pause all teams |
159
+ | `resumeTimer` | `(teamId?: string) => Promise<void>` | Resume automatic ticking; omit `teamId` to resume all teams |
160
+ | `undoTick` | `(teamId?: string) => Promise<void>` | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
161
+ | `resetGame` | `(teamId?: string) => Promise<void>` | Re-initialise the game from scratch; omit `teamId` to reset all teams |
162
+ | `getPastState` | `(query) => Promise<PastStateEntry[]>` | Read committed past rounds; `teams` defaults to every team, or name one team by id |
163
+ | `extendTick` | `(byMs, teamId?) => Promise<void>` | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in |
164
+ | `openHostOverlay` | `(overlay, target?) => Promise<void>` | Ask the host to open the guide or a print sheet |
165
+ | `uploadBlob` | `(file: File) => Promise<string>` | Upload a file, returns a `blob:<id>` reference |
166
+ | `getAssetUrl` | `(reference: string) => string` | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL |
167
+ | `readAsset` | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference |
168
+ | `endpoints` | `Record<string, (request) => Promise<Response>>` | Call a declared endpoint by identifier |
169
+ | `setWaitingRoom` | `(open: boolean) => Promise<void>` | Open or close the session's waiting room; no `teamId` |
170
+ | `resetWalkthrough` | `() => Promise<void>` | Throw the walkthrough away and restart it at tick 0; rejects while the session has no walkthrough |
171
+ | `createTeam` | `(name?: string) => Promise<void>` | Add a team; the host assigns the index |
172
+ | `renameTeam` | `(teamId, name) => Promise<void>` | Rename a team |
173
+ | `renameParticipant` | `(participantId, name) => Promise<void>` | Rename a participant; the host resolves their team |
174
+ | `moveParticipant` | `(participantId, teamId) => Promise<void>` | Reassign a participant to another team |
175
+ | `deleteTeam` | `(teamId) => Promise<void>` | Delete an empty team; independent mode only, and never the last team |
176
+ | `setThemePreference` | `(preference: ThemePreference) => void` | Set the host's theme preference |
177
+
178
+ The promise-returning callbacks resolve and reject as described in [Controlling game flow](./session-game-flow.md#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
179
+
180
+ To generate text, extract document text, or synthesise speech, declare an [endpoint](../recipes/create-endpoint.md) that wraps `generateText`, `extractText`, or `generateSpeech`, then call it through `callbacks.endpoints['…']`. These callbacks are not exposed to UI iframes. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
181
+
182
+ ## Message protocol
183
+
184
+ The `SessionUserInterfaceWrapper` holds the fallback until every required message has arrived:
185
+
186
+ | Required message | Description |
187
+ | ---------------------- | ------------------------------------------------ |
188
+ | `setSessionData` | The shared store and all teams' state |
189
+ | `setSessionMeta` | Session identity and lifecycle state |
190
+ | `setSettings` | The settings this session UI declares, resolved |
191
+ | `setTheme` | Colour scheme and palettes |
192
+ | `setLocale` | Current locale string |
193
+ | `setAssetUrls` | Prefixes for resolving asset and blob references |
194
+ | `setTeamConfiguration` | Interaction mode and team bounds |
195
+
196
+ `setTeamConfiguration` gates first paint because its default cannot be rendered honestly: a surface painting before bounds arrive would hold a maximum of zero and disable the controls that read it.
197
+
198
+ Additional messages sent after initialisation:
199
+
200
+ | Additional message | Description |
201
+ | -------------------- | -------------------------------------------------------------------------------------------------------- |
202
+ | `setTeamList` | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
203
+ | `setTeamLinks` | Updates each team's facilitator-only join and observe URLs |
204
+ | `setParticipantList` | Updates the participant roster across all teams |
205
+ | `hookFailed` | Reports a hook chain that threw |