@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,328 @@
1
+ # Files and LLMs in user interfaces
2
+
3
+ How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** static assets, assetUrl, file upload, uploadFile, blob, read asset, LLM, generateText, chat UI, callEndpoint, EndpointError, markdown
8
+
9
+ ## Linking to static assets
10
+
11
+ User interfaces run inside an iframe served at a nested path (e.g.,
12
+ `/user-interfaces/ui/`). Because of this, **absolute URLs
13
+ like `/my-file.pdf` will not resolve to your assets**: they escape the iframe
14
+ and hit the shell app's origin instead.
15
+
16
+ Always use **relative paths** when linking to files in your UI's directory:
17
+
18
+ ```typescript
19
+ // Wrong: escapes the iframe, loads the shell app's index.html
20
+ window.open('/Briefing.pdf');
21
+
22
+ // Correct: resolves relative to your UI's index.html
23
+ window.open('./Briefing.pdf');
24
+ ```
25
+
26
+ This applies to any reference from your UI code to static files: `<a href>`,
27
+ `<img src>`, `<embed src>`, `window.open()`, `fetch()`, etc. The same rule
28
+ holds in both the dev server and production builds.
29
+
30
+ In production your UI also runs under a strict content security policy: every
31
+ asset must be bundled into your build (no external CDNs, no Google Fonts, no
32
+ blob-URL workers), and outbound network calls go through an engine, an endpoint,
33
+ or a host capability. The dev server mirrors this policy, so violations
34
+ surface locally. See [Production security constraints](./production-constraints.md)
35
+ for the full policy and the do's and don'ts.
36
+
37
+ **Where to put static files:** Place them in your UI's directory alongside
38
+ `index.html` (or in a subdirectory). For the default scaffold structure, that
39
+ means inside `ui/`:
40
+
41
+ ```
42
+ ui/
43
+ ├── index.html
44
+ ├── Briefing.pdf ← ./Briefing.pdf
45
+ ├── public/
46
+ │ └── logo.png ← ./public/logo.png
47
+ └── src/
48
+ └── App.tsx
49
+ ```
50
+
51
+ ## File uploads
52
+
53
+ User interfaces can upload files (PDFs, images, CSV, etc.) using the `uploadBlob` callback and display them using `getAssetUrl`. Uploaded files and scenario-bundled files share a single asset reference scheme (see [Asset references](../guides/file-handling.md#asset-references) for the full picture).
54
+
55
+ ### Uploading a file
56
+
57
+ ```typescript
58
+ import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
59
+ import type { Context, Settings } from '../types';
60
+
61
+ function DocumentUpload() {
62
+ const callbacks = useUserInterfaceCallbacks();
63
+ const { setData } = useUserInterfaceData<Context, Settings>();
64
+ const [isUploading, setIsUploading] = useState(false);
65
+
66
+ const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
67
+ const file = e.target.files?.[0];
68
+ if (!file || !callbacks.uploadBlob) return;
69
+
70
+ try {
71
+ setIsUploading(true);
72
+ const reference = await callbacks.uploadBlob(file);
73
+ setData({ 'upload': { DocumentRef: reference } });
74
+ } finally {
75
+ setIsUploading(false);
76
+ e.target.value = '';
77
+ }
78
+ };
79
+
80
+ return (
81
+ <input type="file" accept=".pdf,.csv,.txt" onChange={handleUpload} disabled={isUploading} />
82
+ );
83
+ }
84
+ ```
85
+
86
+ The capability holding the reference must be listed in the UI's `writes`. The maximum file size is **20 MB**.
87
+
88
+ ### Displaying a file
89
+
90
+ Use `useAssetUrl` to get a URL suitable for `<img>`, `<embed>`, or `<video>`. It resolves uploaded blobs and scenario-bundled assets alike, and returns `undefined` for an absent reference, so there is nothing to guard:
91
+
92
+ ```typescript
93
+ import { useAssetUrl } from '@seriousgaming/sdk/ui';
94
+
95
+ function DocumentViewer() {
96
+ const { data } = useUserInterfaceData<Context, Settings>();
97
+ const src = useAssetUrl(data.upload?.DocumentRef);
98
+ if (!src) return null;
99
+
100
+ return (
101
+ <embed
102
+ src={src}
103
+ type="application/pdf"
104
+ style={{ width: '100%', height: '500px', border: 'none' }}
105
+ />
106
+ );
107
+ }
108
+ ```
109
+
110
+ The capability holding the reference must be listed in the UI's `reads`. `useAssetUrl` works on every surface; the `getAssetUrl` callback does the same job outside a component.
111
+
112
+ For the full reference, including engine access via `readAsset`, blob scopes, CLI upload, and supported file types, see [File handling](./file-handling.md).
113
+
114
+ ## Reading an asset's contents
115
+
116
+ To render what is in a file rather than link to it, such as a briefing, a JSON table of scenario prose, or a CSV, use `useAsset`. It fetches the asset, reads the body `as` `'json'`, `'text'` or `'blob'`, and returns `{ data, error, loading }`:
117
+
118
+ ```tsx
119
+ import { useAsset } from '@seriousgaming/sdk/ui';
120
+
121
+ function Briefing() {
122
+ const { data, error, loading } = useAsset('shared:briefing/briefing.md', { as: 'text' });
123
+ if (loading) return <Spinner />;
124
+ if (error) return <Alert>{error.message}</Alert>;
125
+ return <Markdown>{data}</Markdown>;
126
+ }
127
+ ```
128
+
129
+ It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md` (a locale with a script, such as `zh-Hant-TW`, tries `zh-Hant` before `zh`):
130
+
131
+ ```
132
+ shared-assets/
133
+ briefing/
134
+ briefing.md ← the untranslated text, and the fallback
135
+ fr/briefing.md
136
+ ar/briefing.md
137
+ ```
138
+
139
+ Pass `locale` to look in a different one, or `locale: false` to read the reference alone. A `blob:` reference is always read as given. The hook refetches when the reference or the locale changes, so it follows a mid-session language switch, and an answer to a reference that has since changed is discarded. For JSON, give the type: `useAsset<Briefing>(reference, { as: 'json' })`.
140
+
141
+ ## Using LLMs in user interfaces
142
+
143
+ User interfaces cannot call `generateText` (or `extractText` or `generateSpeech`) directly. A UI reaches these services through an [endpoint](./endpoints.md): the endpoint wraps the callback and runs server-side, and the UI invokes it through `callbacks.endpoints['<endpoint-id>']`. This keeps credential-holding calls off the untrusted iframe. To create one, follow [Create an endpoint](../recipes/create-endpoint.md). See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) and the [LLM integration guide](llm-integration.md) for the full pattern.
144
+
145
+ ### The endpoint
146
+
147
+ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
148
+
149
+ ```typescript
150
+ // endpoints/chat/logic/logic.ts
151
+ import { getText } from '@seriousgaming/sdk';
152
+ import type { Handler } from '../types';
153
+
154
+ export const Handle: Handler = async ({ request, callbacks }) => {
155
+ const response = await callbacks.generateText({
156
+ messages: request.messages,
157
+ systemPrompt:
158
+ request.systemPrompt ?? 'You are a helpful business advisor. Provide concise guidance.',
159
+ });
160
+ return { reply: getText(response) };
161
+ };
162
+ ```
163
+
164
+ The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no `uses` field, and the build refuses one.
165
+
166
+ ```json
167
+ {
168
+ "definition": {
169
+ "endpoints": ["chat"]
170
+ },
171
+ "rootDirectory": ".",
172
+ "ui": { "entrypoint": "index.html" }
173
+ }
174
+ ```
175
+
176
+ ### Calling the endpoint from a component
177
+
178
+ Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
179
+
180
+ ```tsx
181
+ import { useState } from 'react';
182
+ import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
183
+ import type { Context, Settings } from '../types';
184
+ import type { Callbacks } from '../types';
185
+
186
+ function ChatAssistant() {
187
+ const { data, setData } = useUserInterfaceData<Context, Settings>();
188
+ const callbacks = useUserInterfaceCallbacks() as Callbacks;
189
+ const [isLoading, setIsLoading] = useState(false);
190
+
191
+ const messages = data.chathistory.Messages;
192
+
193
+ const handleSendMessage = async (userMessage: string) => {
194
+ if (!userMessage.trim()) return;
195
+ setIsLoading(true);
196
+ try {
197
+ const newMessages = [...messages, { role: 'user' as const, content: userMessage }];
198
+ const { reply } = await callbacks.endpoints['chat']({
199
+ messages: newMessages,
200
+ });
201
+ await setData({
202
+ chathistory: {
203
+ Messages: [...newMessages, { role: 'assistant' as const, content: reply }],
204
+ },
205
+ });
206
+ } finally {
207
+ setIsLoading(false);
208
+ }
209
+ };
210
+
211
+ return (
212
+ <div>
213
+ {messages.map((msg, idx) => (
214
+ <div key={idx} className={msg.role}>
215
+ {msg.content}
216
+ </div>
217
+ ))}
218
+ <input
219
+ type="text"
220
+ placeholder="Type your message..."
221
+ onKeyPress={(e) => {
222
+ if (e.key === 'Enter' && !isLoading) {
223
+ handleSendMessage(e.currentTarget.value);
224
+ e.currentTarget.value = '';
225
+ }
226
+ }}
227
+ disabled={isLoading}
228
+ />
229
+ {isLoading && <p>Loading...</p>}
230
+ </div>
231
+ );
232
+ }
233
+ ```
234
+
235
+ ### Localising prompts
236
+
237
+ Translate the system prompt in the UI with i18n and pass it to the endpoint in the request. The endpoint forwards it to `generateText`:
238
+
239
+ ```tsx
240
+ import { useTranslation } from 'react-i18next';
241
+
242
+ const { t } = useTranslation();
243
+ const { reply } = await callbacks.endpoints['chat']({
244
+ messages: newMessages,
245
+ systemPrompt: t('chatSystemPrompt'),
246
+ });
247
+ ```
248
+
249
+ Update `src/i18n.ts`:
250
+
251
+ ```typescript
252
+ const resources = {
253
+ en: {
254
+ translation: {
255
+ chatSystemPrompt: 'You are a helpful assistant for a business game.',
256
+ askForAdvice: 'Ask for advice...',
257
+ },
258
+ },
259
+ es: {
260
+ translation: {
261
+ chatSystemPrompt: 'Eres un asistente útil para un juego de simulación empresarial.',
262
+ askForAdvice: 'Pedir consejo...',
263
+ },
264
+ },
265
+ };
266
+ ```
267
+
268
+ ### Markdown rendering in chat
269
+
270
+ Render markdown replies with `react-markdown`:
271
+
272
+ ```typescript
273
+ import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
274
+ import ReactMarkdown from 'react-markdown';
275
+ import { Box, styled } from '@mui/material';
276
+
277
+ const StyledMarkdown = styled(Box)(({ theme }) => ({
278
+ '& code': {
279
+ backgroundColor: theme.palette.action.hover,
280
+ padding: '2px 6px',
281
+ borderRadius: '4px',
282
+ fontFamily: 'monospace'
283
+ },
284
+ '& pre': {
285
+ backgroundColor: theme.palette.action.hover,
286
+ padding: theme.spacing(1),
287
+ borderRadius: '4px',
288
+ overflow: 'auto'
289
+ }
290
+ }));
291
+
292
+ function ChatMessage({ content }: { content: string }) {
293
+ return (
294
+ <StyledMarkdown>
295
+ <ReactMarkdown>{content}</ReactMarkdown>
296
+ </StyledMarkdown>
297
+ );
298
+ }
299
+ ```
300
+
301
+ ### Error handling
302
+
303
+ A failed endpoint call rejects with an `EndpointError`, the endpoint counterpart of `MutationError`. `error.kind` (shorthand for `error.outcome.kind`) says why: the [`MutationOutcome` kinds](./ui-ticks.md#awaiting-state-changes), plus `invalid-request` (the request failed `requestSchema` and the handler never ran), `handler-error` (the handler threw or overran its time limit) and `invalid-response` (it returned something its declaration forbids). `error.applied` lists the endpoint's effects that had already landed, and `error.failedStep` names the one that failed, so you can tell a call that changed nothing from one that saved its write and then failed on an action:
304
+
305
+ ```typescript
306
+ import { EndpointError } from '@seriousgaming/sdk/ui';
307
+
308
+ try {
309
+ const { reply } = await callbacks.endpoints['chat']({ messages });
310
+ setResponse(reply);
311
+ } catch (error) {
312
+ if (error instanceof EndpointError && error.kind === 'handler-error') {
313
+ setError(t('chatUnavailable'));
314
+ } else {
315
+ setError(error instanceof Error ? error.message : String(error));
316
+ }
317
+ }
318
+ ```
319
+
320
+ An empty `applied` means nothing changed. As with a mutation, never retry an endpoint call automatically: a `conflict` means a person may try again. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md#steps) for every kind.
321
+
322
+ ### Putting a chat UI together
323
+
324
+ The sections above are the parts of a complete chat surface. Beyond them, a chat that feels finished usually adds:
325
+
326
+ - Message history kept in the component's state, or in a capability when it must survive a reload, and sent with each call
327
+ - A loading state while the call is in flight, with the send button disabled
328
+ - Scrolling to the latest message when one arrives
@@ -0,0 +1,281 @@
1
+ # Participants and teams in user interfaces
2
+
3
+ How a game UI reads who is playing: the current participant, their team, observers and walkthroughs, and the controls that let a team join, name itself, and fix a participant's name.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** participants, useUserInterfaceParticipant, team members, presence, observers, walkthroughs, join link, team name, rename participant, renameSelf
8
+
9
+ ## Accessing participant info
10
+
11
+ Use the `useUserInterfaceParticipant` hook to read the current participant's identity:
12
+
13
+ ```typescript
14
+ import { useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
15
+
16
+ function Dashboard() {
17
+ const participant = useUserInterfaceParticipant();
18
+
19
+ // null when the surface is being observed rather than played (see 'Observers')
20
+ if (!participant) return <p>Observing this team</p>;
21
+
22
+ return (
23
+ <div>
24
+ <p>Hello, {participant.name}!</p> {/* e.g. "Participant 1" */}
25
+ <p>Participant #{participant.index}</p> {/* sequential index */}
26
+ <p>Team: {participant.teamId}</p> {/* e.g. "team-1" */}
27
+ </div>
28
+ );
29
+ }
30
+ ```
31
+
32
+ | Field | Type | Description |
33
+ | -------- | -------- | ------------------------------------------------------ |
34
+ | `id` | `string` | Platform-assigned participant ID |
35
+ | `name` | `string` | Display name (e.g. `"Participant 1"`) |
36
+ | `index` | `number` | Zero-based join order within the team |
37
+ | `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
38
+
39
+ For a participant the wrapper does not render children until the platform sends participant info, so all fields are guaranteed to be present. The one case where the hook returns `null` is an observer (see [Observers](#observers) below); guard for it. In the dev server, identity comes from a session cookie (so different browser sessions are different participants).
40
+
41
+ ### Seeing the whole team
42
+
43
+ `useUserInterfaceParticipant()` returns the caller; `useUserInterfaceParticipants()` returns the full roster for the caller's team, including the caller's own entry. Each entry adds a `connected` flag to the identity fields:
44
+
45
+ ```typescript
46
+ import { useUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
47
+
48
+ function Roster() {
49
+ const participants = useUserInterfaceParticipants();
50
+
51
+ if (participants.length === 0) return <p>Waiting for teammates…</p>;
52
+
53
+ return (
54
+ <ul>
55
+ {participants.map((p) => (
56
+ <li key={p.id}>
57
+ {p.name} {p.connected ? '🟢' : '⚪'}
58
+ </li>
59
+ ))}
60
+ </ul>
61
+ );
62
+ }
63
+ ```
64
+
65
+ | Field | Type | Description |
66
+ | ----------- | --------- | ------------------------------------------------------ |
67
+ | `id` | `string` | Platform-assigned participant ID |
68
+ | `name` | `string` | Display name (e.g. `"Participant 1"`) |
69
+ | `index` | `number` | Zero-based join order within the team |
70
+ | `connected` | `boolean` | `true` while the participant has a live connection |
71
+ | `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
72
+
73
+ ### Participant presence lifecycle
74
+
75
+ The presence guarantees are firm, so design against them rather than defensively:
76
+
77
+ - **The caller is always present.** `useUserInterfaceParticipant()` never returns a partial value. The wrapper gates rendering on the participant message, so `id`, `name`, `index`, and `teamId` are populated before your first render
78
+ - **The roster may be empty on first render.** `useUserInterfaceParticipants()` is not gated, so it starts as `[]` and fills in reactively as the platform sends the list. Render an empty-roster state rather than assuming at least one entry
79
+ - **The caller is included in the roster.** Once populated, the list always contains the caller's own entry alongside every other participant on the team
80
+ - **A disconnect keeps the entry.** When a participant drops their connection their entry stays in the roster with `connected` flipped to `false`, so you can still show who was here. Participants do not leave: an entry lasts for the whole session, keeping its `id` and `index`
81
+
82
+ Because the caller is guaranteed and the roster fills in reactively, there is no separate loading flag to check: branch on `participants.length === 0` for the brief pre-population window, and on `connected` to distinguish live from dropped teammates.
83
+
84
+ **Under `sdk dev`**, a participant is connected while a page addressed to them is open, at `/team/N/player/M` with or without `?bare`. Several tabs on the same participant count once, and they stay connected until the last one closes. An observer page and the console's session surface are nobody's, so they connect nobody. To see a teammate drop out, open two participants' pages and close one.
85
+
86
+ ### Seeing every team's participants
87
+
88
+ `useUserInterfaceParticipants()` covers your own team. In a shared-state game where teams deal with each other, a UI can also read the roster of every team through the `getAllTeamsParticipants()` callback, for a directory of who is on each competing team. Declare `crossTeamParticipants: true` in the UI bundle to authorise it (an undeclared UI receives an empty array), then call it and group the flat result by `teamId`:
89
+
90
+ ```tsx
91
+ const { getAllTeamsParticipants } = useUserInterfaceCallbacks();
92
+ const everyone = await getAllTeamsParticipants(); // Participant[]
93
+ ```
94
+
95
+ Unlike the own-team hook, this is a point-in-time snapshot rather than a live subscription: call it again to refresh. See [Show all teams' participants in a UI](../recipes/show-all-teams-participants.md) for the full pattern.
96
+
97
+ ### Observers
98
+
99
+ Your UI can be rendered for an **observer** as well as a participant. An observer is a facilitator watching one team's live game UI without joining as a team member, for seeing how a team is playing, troubleshooting, or running a debrief. An observer is not in the roster and has no participant identity, so `useUserInterfaceParticipant()` returns `null` in that mode.
100
+
101
+ Read the viewer role with `useUserInterfaceViewerRole()`:
102
+
103
+ ```tsx
104
+ import { useUserInterfaceViewerRole, useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
105
+
106
+ function Decisions() {
107
+ const isObserver = useUserInterfaceViewerRole() === 'observer';
108
+ const participant = useUserInterfaceParticipant(); // null when observing
109
+
110
+ return (
111
+ <>
112
+ {isObserver && <Banner>Observing: you are watching this team, not playing</Banner>}
113
+ <PriceInput readOnly={isObserver} />
114
+ </>
115
+ );
116
+ }
117
+ ```
118
+
119
+ Most UIs need no changes: an observer sees the live game UI exactly as a participant does, and can still drive it. Any change an observer makes goes to the game's validators, as a participant's would, with `actor.role` set to `'observer'` so a validator can treat it differently (see [Validators](./validators.md)). Reach for `useUserInterfaceViewerRole()` only when you want to adapt: hide a participant-only control (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a deliberately read-only debrief view.
120
+
121
+ The two roles are the only ones your UI is ever told. A kind of viewer a later release adds reaches only a game that declares the feature that adds it in `requires`, and every other game is shown to that viewer as to an observer, so code that treats anything but `'participant'` as observing is always right.
122
+
123
+ One read does need attention. To find out **which team** your UI is rendering, use `useUserInterfaceOwnTeam()`, not `useUserInterfaceParticipant()?.teamId`:
124
+
125
+ ```typescript
126
+ import { useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
127
+
128
+ const ownTeam = useUserInterfaceOwnTeam(); // { teamId, index, name }, populated when observing too
129
+ ```
130
+
131
+ The participant route is the obvious one and it is `null` under observation, so anything derived from it (marking your row in a cross-team list, labelling a board, keying a write) works when played and breaks when observed. `useUserInterfaceOwnTeam()` comes from the host, which always knows which surface it mounted. Do not confuse it with the plural `useUserInterfaceTeams()`, which lists every team in the session without marking yours.
132
+
133
+ ### Walkthroughs
134
+
135
+ Your UI can also be rendered in a **walkthrough**: a disposable second run of the game beside the session, for demonstrating it. One team, one participant, always from tick 0, touching nothing real. It is what a facilitator puts on a projector while talking a room through the game.
136
+
137
+ Read it with `useRunKind()`:
138
+
139
+ ```tsx
140
+ import { useRunKind } from '@seriousgaming/sdk/ui';
141
+
142
+ function Leaderboard() {
143
+ const runKind = useRunKind();
144
+ const data = useUserInterfaceData();
145
+
146
+ // A walkthrough has one team, so the board has one row. Fill it in rather
147
+ // than showing a room an empty board they will never see again.
148
+ const rows = runKind === 'walkthrough' ? demonstrationRows : data.market.Standings;
149
+
150
+ return <Board rows={rows} />;
151
+ }
152
+ ```
153
+
154
+ Most UIs need no changes, and one that ignores this renders exactly as it always has: every session reports `'session'`, and only the walkthrough beside it differs. Reach for it to fill in what a solo run genuinely lacks (rival teams, teammates in a presence list), or to hide something you would rather not spoil before play.
155
+
156
+ **The line to hold:** do not change how the game UI plays. The walkthrough exists to show the room this game, and one that behaves differently shows them a different one.
157
+
158
+ The value is the host's, it is the same one your engine reads as `meta.runKind`, and it does not change for the life of the run, so a decision taken here and one taken in logic cannot disagree.
159
+
160
+ A session UI gets two more pieces. `useSessionUserInterfaceWalkthroughLink()` returns where to open the walkthrough, or `null` until the host has said (every host offers one), and `callbacks.resetWalkthrough()` throws it away and starts it again at tick 0. Gate the control on the link, the way a guide button gates on `useSessionUserInterfaceHostOverlays()`:
161
+
162
+ ```tsx
163
+ const walkthrough = useSessionUserInterfaceWalkthroughLink();
164
+ const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
165
+
166
+ {
167
+ walkthrough && (
168
+ <>
169
+ <Button href={walkthrough.url} target="_blank" rel="noreferrer">
170
+ Walkthrough
171
+ </Button>
172
+ <Button onClick={() => void resetWalkthrough()}>Start it again</Button>
173
+ </>
174
+ );
175
+ }
176
+ ```
177
+
178
+ ## Showing how to join this team
179
+
180
+ Every game UI is told how to join the team it is rendering. Use it to put
181
+ a join code on the screen the participants are actually looking at, rather than having
182
+ the facilitator read a URL out.
183
+
184
+ ```typescript
185
+ import { useUserInterfaceOwnTeamJoinLink } from '@seriousgaming/sdk/ui';
186
+
187
+ function JoinCode() {
188
+ const joinLink = useUserInterfaceOwnTeamJoinLink();
189
+ // `null` until the host delivers it, so render nothing for that first frame
190
+ if (!joinLink) return null;
191
+ return <QrCode value={joinLink.joinUrl} />;
192
+ }
193
+ ```
194
+
195
+ Points worth knowing:
196
+
197
+ - You always get your own team and only your own team. There is no list, and no
198
+ way to reach another team's link from a game UI
199
+ - Observers get it too, and that is the case the feature exists for. A tablet
200
+ parked on a table showing a team's game UI has no participant of its own, so
201
+ it is opened as an observer: exactly the screen a walk-up join code belongs on
202
+ - Encode `joinUrl` in a QR code, not any longer form you build yourself. The host
203
+ picks which form of the link to send, and it picks the short one because a
204
+ denser code is harder to scan across a table
205
+ - `fallbackJoinUrl` is there for one failure only, a network that blocks the
206
+ shortened link. Offer it on request (a 'link not working?' control), not beside
207
+ the main one with equal weight
208
+ - The session PIN never reaches a game UI. In a session that requires one,
209
+ the code on screen is not enough to join on its own, which is what bounds how
210
+ much a visible code gives away. An operator who wants a self-sufficient walk-up
211
+ code runs the session without a PIN
212
+
213
+ ## Letting a team name itself
214
+
215
+ A game UI can rename the team it belongs to. The name it sets is the
216
+ team's real name everywhere, including the host's own chrome and print sheets, so
217
+ a game that offers this keeps no display name of its own alongside it.
218
+
219
+ ```typescript
220
+ import { MutationError, useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
221
+
222
+ const { renameOwnTeam } = useUserInterfaceCallbacks();
223
+
224
+ try {
225
+ await renameOwnTeam(draftName);
226
+ } catch (error) {
227
+ // A refusal is terminal: explain it rather than retrying
228
+ if (error instanceof MutationError) setRefused(true);
229
+ }
230
+ ```
231
+
232
+ Points worth knowing:
233
+
234
+ - **It names no team.** The host works out which team the caller is on, so a
235
+ surface can only ever rename its own. There is no `teamId` argument to get
236
+ wrong
237
+ - **Available everywhere, with nothing to declare.** Game UIs and waiting room
238
+ UIs, participants and observers alike. A game that does not want its teams
239
+ renamed simply does not offer the control
240
+ - **Render the result, not the request.** A facilitator can rename the same team
241
+ from the session UI at the same moment. There is one name per team and the
242
+ last write wins, so read it back from `useUserInterfaceOwnTeam()` rather than trusting what
243
+ you just sent
244
+ - **The host owns the limits.** It trims the name, refuses a blank one, and
245
+ refuses one longer than its cap (60 characters on the reference platform). Each
246
+ arrives as a terminal `denied`, so surface it rather than looping
247
+ - **`teams.defaultNames` becomes a starting point**, not a fixed label, in any
248
+ game that offers this
249
+
250
+ ## Letting a participant fix their own name
251
+
252
+ A participant who mistyped their name on joining can change it with `renameSelf`,
253
+ where the host lets them. Whose names are theirs to change is the host's call: a
254
+ guest who typed one usually may, and one whose name comes from a sign-in may not.
255
+ `useUserInterfaceCanRenameSelf()` gives the host's answer for the participant
256
+ using this surface:
257
+
258
+ ```typescript
259
+ import {
260
+ useUserInterfaceCallbacks,
261
+ useUserInterfaceCanRenameSelf,
262
+ } from '@seriousgaming/sdk/ui';
263
+
264
+ const canRenameSelf = useUserInterfaceCanRenameSelf();
265
+ const { renameSelf } = useUserInterfaceCallbacks();
266
+
267
+ {canRenameSelf && (
268
+ <Button onClick={() => void renameSelf(draftName)}>Change my name</Button>
269
+ )}
270
+ ```
271
+
272
+ - **Show the control only where `canRenameSelf` is `true`.** It is `false` for an
273
+ observer, for a participant whose name the host keeps, and on a host that
274
+ predates `renameSelf`, which may never answer the call
275
+ - **It names nobody.** The host works out who is asking, so a surface can only
276
+ rename its own participant
277
+ - **Render the result, not the request.** A facilitator can rename the same
278
+ participant at the same moment. Read the name back from
279
+ `useUserInterfaceParticipant()`
280
+ - **The host owns the limits**, as for a team name: it trims the name and refuses
281
+ a blank or over-long one as a terminal `denied`