@seriousgaming/sdk-tools 1.4.0 → 1.5.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 (157) hide show
  1. package/dist/cli.js +830 -99
  2. package/dist/client.js +114 -11
  3. package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-BVF8exas.js} +21 -21
  4. package/dist/dev/console/index.html +1 -1
  5. package/dist/dev/public-origins.d.ts +61 -0
  6. package/dist/dev/shell.d.ts +32 -4
  7. package/dist/docs/ai-agents.md +5 -0
  8. package/dist/docs/changelog-0.x.md +2 -2
  9. package/dist/docs/changelog.md +37 -4
  10. package/dist/docs/cli-and-dev-server.md +58 -0
  11. package/dist/docs/cli-error-codes.md +39 -36
  12. package/dist/docs/cli-reference.md +68 -21
  13. package/dist/docs/environment-variables.md +10 -5
  14. package/dist/docs/guides/ai-facilitation.md +2 -0
  15. package/dist/docs/guides/capabilities.md +2 -0
  16. package/dist/docs/guides/designing-a-game.md +2 -0
  17. package/dist/docs/guides/designing-screens.md +133 -0
  18. package/dist/docs/guides/endpoints.md +2 -0
  19. package/dist/docs/guides/engine-testing.md +5 -1
  20. package/dist/docs/guides/engine.md +2 -0
  21. package/dist/docs/guides/file-handling.md +3 -1
  22. package/dist/docs/guides/games.md +3 -1
  23. package/dist/docs/guides/global-settings.md +2 -0
  24. package/dist/docs/guides/guide.md +2 -0
  25. package/dist/docs/guides/hooks.md +2 -0
  26. package/dist/docs/guides/index.md +9 -0
  27. package/dist/docs/guides/internationalization.md +2 -0
  28. package/dist/docs/guides/llm-integration.md +4 -2
  29. package/dist/docs/guides/multi-team-games.md +3 -1
  30. package/dist/docs/guides/patterns.md +2 -0
  31. package/dist/docs/guides/presentation.md +1 -1
  32. package/dist/docs/guides/production-constraints.md +2 -0
  33. package/dist/docs/guides/scenario-editor.md +2 -0
  34. package/dist/docs/guides/scenarios.md +6 -2
  35. package/dist/docs/guides/session-game-flow.md +365 -0
  36. package/dist/docs/guides/session-hooks.md +205 -0
  37. package/dist/docs/guides/session.md +27 -565
  38. package/dist/docs/guides/settings.md +2 -0
  39. package/dist/docs/guides/setup.md +3 -1
  40. package/dist/docs/guides/speech-generation.md +2 -0
  41. package/dist/docs/guides/starter-game.md +61 -21
  42. package/dist/docs/guides/testing.md +2 -0
  43. package/dist/docs/guides/tick-controller.md +3 -1
  44. package/dist/docs/guides/type-safety.md +2 -0
  45. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  46. package/dist/docs/guides/ui-participants.md +281 -0
  47. package/dist/docs/guides/ui-styling.md +263 -0
  48. package/dist/docs/guides/ui-ticks.md +247 -0
  49. package/dist/docs/guides/ui.md +11 -1092
  50. package/dist/docs/guides/upgrading.md +2 -0
  51. package/dist/docs/guides/validators.md +2 -0
  52. package/dist/docs/guides/waiting-room.md +1 -1
  53. package/dist/docs/index.md +2 -1
  54. package/dist/docs/page-index.md +145 -0
  55. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  56. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  57. package/dist/docs/recipes/create-presentation.md +11 -0
  58. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  59. package/dist/docs/recipes/create-session-ui.md +2 -1
  60. package/dist/docs/recipes/create-setup.md +1 -0
  61. package/dist/docs/recipes/create-user-interface.md +1 -0
  62. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  63. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  64. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  65. package/dist/docs/recipes/index.md +3 -0
  66. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  67. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  68. package/dist/docs/recipes/use-request-tick.md +2 -2
  69. package/dist/execution/config-resolver.d.ts +4 -1
  70. package/dist/runtime/manifest-version.d.ts +1 -1
  71. package/dist/runtime.js +1 -1
  72. package/dist/templates/package/CLAUDE.md.template +14 -5
  73. package/dist/templates/package/DESIGN.md.liquid +39 -7
  74. package/dist/templates/package/README.md.liquid +1 -1
  75. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  76. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  77. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  78. package/dist/templates/starter-game/package.json +2 -0
  79. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  80. package/dist/templates/starter-game/presentation/index.html +20 -0
  81. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  82. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  83. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  84. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  85. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  86. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  87. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  88. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  89. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  90. package/dist/templates/starter-game/presentation/types.ts +94 -0
  91. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  92. package/dist/templates/starter-game/session/defaults.ts +6 -0
  93. package/dist/templates/starter-game/session/index.html +1 -1
  94. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  95. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  96. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  97. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  98. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  99. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  100. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  101. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  102. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  103. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  104. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  105. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  106. package/dist/templates/starter-game/session/src/status.ts +28 -0
  107. package/dist/templates/starter-game/session/types.ts +8 -2
  108. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  109. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  110. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  111. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  112. package/dist/templates/starter-game/shared/days.ts +11 -0
  113. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  114. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  115. package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
  116. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  117. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  118. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  119. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  120. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  121. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  122. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  123. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  124. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  125. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  126. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  127. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  128. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  129. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  130. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  131. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  132. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  133. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  134. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  135. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  136. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  137. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  138. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  139. package/dist/templates/starter-game/ui/types.ts +6 -0
  140. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  141. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  142. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  143. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  144. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  145. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  146. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  147. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  148. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  149. package/dist/utils/error-codes.d.ts +12 -0
  150. package/package.json +11 -4
  151. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  152. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  153. package/dist/templates/starter-game/session/src/format.ts +0 -8
  154. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  155. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  156. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  157. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
@@ -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`
@@ -0,0 +1,263 @@
1
+ # Styling and building user interfaces
2
+
3
+ How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** i18n, internationalisation, theme, styling, dark mode, Material-UI, MUI, contrastText, mobile, viewport, dvh, Vite, vite.config.ts
8
+
9
+ ## Using internationalisation
10
+
11
+ The wrapper sets `lang` and `dir` on the document root from the locale (`dir="rtl"` for Arabic, Hebrew, Persian, Urdu and any other right-to-left script) and keeps them in step when the facilitator changes language, so a surface does not set them itself. It also sets the root's `color-scheme` to the theme's mode, so scrollbars and native form controls follow a dark theme without MUI.
12
+
13
+ Use React i18next for multi-language support:
14
+
15
+ ```typescript
16
+ import { useTranslation } from 'react-i18next';
17
+ import { useUserInterfaceLocale } from '@seriousgaming/sdk/ui';
18
+
19
+ function Dashboard() {
20
+ const { t } = useTranslation();
21
+ const { locale } = useUserInterfaceLocale();
22
+
23
+ return (
24
+ <div>
25
+ <h1>{t('dashboard.title')}</h1>
26
+ <p>{t('dashboard.welcome')}</p>
27
+ <p>Current language: {locale}</p>
28
+ </div>
29
+ );
30
+ }
31
+ ```
32
+
33
+ Update your `src/i18n.ts`:
34
+
35
+ ```typescript
36
+ import i18n from 'i18next';
37
+ import { initReactI18next } from 'react-i18next';
38
+
39
+ const resources = {
40
+ en: {
41
+ translation: {
42
+ 'dashboard.title': 'Dashboard',
43
+ 'dashboard.welcome': 'Welcome',
44
+ 'inventory.label': 'Stock Level',
45
+ 'revenue.label': 'Revenue',
46
+ },
47
+ },
48
+ es: {
49
+ translation: {
50
+ 'dashboard.title': 'Panel de Control',
51
+ 'dashboard.welcome': 'Bienvenido',
52
+ 'inventory.label': 'Nivel de Stock',
53
+ 'revenue.label': 'Ingresos',
54
+ },
55
+ },
56
+ };
57
+
58
+ i18n.use(initReactI18next).init({
59
+ resources,
60
+ lng: 'en',
61
+ interpolation: { escapeValue: false },
62
+ });
63
+
64
+ export default i18n;
65
+ ```
66
+
67
+ ## Theming and styling
68
+
69
+ Serious Gaming provides a theming system that allows your user interfaces to adapt to the host environment's look and feel. This is handled through the `@seriousgaming/sdk` package.
70
+
71
+ ### Accessing theme information
72
+
73
+ You can access the current theme information within your components using the `useUserInterfaceTheme` hook.
74
+
75
+ ```typescript
76
+ import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
77
+
78
+ function MyComponent() {
79
+ const theme = useUserInterfaceTheme();
80
+ // theme.mode will be 'light' or 'dark'
81
+ // theme.light and theme.dark will contain color palettes
82
+
83
+ return (
84
+ <div style={% raw %}{{{% endraw %} background: theme.mode === 'light' ? theme.light.primary : theme.dark.primary {% raw %}}}{% endraw %}>
85
+ My Component
86
+ </div>
87
+ );
88
+ }
89
+ ```
90
+
91
+ ### Theme object structure
92
+
93
+ The `theme` object returned by `useUserInterfaceTheme` has the following structure:
94
+
95
+ ```typescript
96
+ type UserInterfaceTheme = {
97
+ mode: 'dark' | 'light';
98
+ dark: UserInterfaceModeColors;
99
+ light: UserInterfaceModeColors;
100
+ };
101
+
102
+ type UserInterfaceModeColors = {
103
+ primary: string;
104
+ secondary: string;
105
+ success: string;
106
+ error: string;
107
+ warning: string;
108
+ info: string;
109
+ contrastText: {
110
+ primary: string;
111
+ secondary: string;
112
+ success: string;
113
+ error: string;
114
+ warning: string;
115
+ info: string;
116
+ };
117
+ };
118
+ ```
119
+
120
+ - `mode`: Indicates whether the current theme is `'light'` or `'dark'`
121
+ - `light`: An object containing the colour palette for the light theme
122
+ - `dark`: An object containing the colour palette for the dark theme
123
+ - `contrastText`: The text colour to draw on each palette colour, an opaque `#rrggbb` the host guarantees meets WCAG AA (4.5:1) against it. Use it rather than computing your own: the theme's author may have chosen one, and the host keeps it when it passes
124
+
125
+ ```tsx
126
+ const colors = theme.mode === 'light' ? theme.light : theme.dark;
127
+
128
+ <span style={% raw %}{{{% endraw %} background: colors.primary, color: colors.contrastText.primary {% raw %}}}{% endraw %}>Live</span>
129
+ ```
130
+
131
+ Passing `contrastText` through to Material-UI, as the template's `theme.ts` does (below), means every contained button and chip already uses it.
132
+
133
+ ### Reading the host's theme preference
134
+
135
+ `useUserInterfaceTheme` gives you the resolved palette, but `theme.mode` only tells you the colours to paint right now. It cannot tell you whether the host is following the operating system or has been pinned to a specific scheme. When you need that distinction, read the host's preference with the `useUserInterfaceThemePreference()` hook. It returns `'light'`, `'dark'`, or `'system'` and re-renders when the preference changes, exactly like `useUserInterfaceTheme()`:
136
+
137
+ ```typescript
138
+ import { useUserInterfaceThemePreference } from '@seriousgaming/sdk/ui';
139
+
140
+ function ThemePreferenceBadge() {
141
+ const preference = useUserInterfaceThemePreference();
142
+ return <span>Following: {preference}</span>;
143
+ }
144
+ ```
145
+
146
+ Each UI surface has its own hook: `useUserInterfaceThemePreference`, `useSessionUserInterfaceThemePreference`, and `useSettingsEditorThemePreference`.
147
+
148
+ A UI can also change the preference with the `setThemePreference` callback. The host applies it, persists it, and broadcasts the change back, so every other UI (and every theme-preference hook) sees it:
149
+
150
+ ```typescript
151
+ import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
152
+
153
+ function ThemeSwitcher() {
154
+ const callbacks = useUserInterfaceCallbacks();
155
+ return (
156
+ <>
157
+ <button onClick={() => callbacks.setThemePreference('light')}>Light</button>
158
+ <button onClick={() => callbacks.setThemePreference('dark')}>Dark</button>
159
+ <button onClick={() => callbacks.setThemePreference('system')}>System</button>
160
+ </>
161
+ );
162
+ }
163
+ ```
164
+
165
+ `setThemePreference` is available on every UI surface but the presentation (game, waiting room, session, setup and scenario editor). No `uses` declaration is needed, because theme preference is not gated.
166
+
167
+ ### Integrating with Material-UI
168
+
169
+ The default user interface template uses [Material-UI](https://mui.com/) for its component library. `createSurfaceTheme` turns the host's theme into MUI theme options: every colour role with its `contrastText`, the page, surface and text colours when the host sends them, and the host brand's fonts. Pass it to `createTheme` first, with your own shape and component overrides after it:
170
+
171
+ ```typescript
172
+ // src/theme.ts
173
+ import { createTheme } from '@mui/material/styles';
174
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
175
+ import { useMemo } from 'react';
176
+
177
+ export const useAppTheme = () => {
178
+ const theme = useUserInterfaceTheme();
179
+ return useMemo(
180
+ () =>
181
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
182
+ shape: { borderRadius: 10 },
183
+ }),
184
+ [theme]
185
+ );
186
+ };
187
+ ```
188
+
189
+ `fonts.body` is the font your game bundles, used whenever the host's brand names none. By using `useMemo`, you ensure that the theme object is only recreated when the theme context from Serious Gaming changes, which is important for performance.
190
+
191
+ For the host's logo and name, its fonts, and how to preview a game in someone else's brand, see [Theming and branding](./theming-and-branding.md).
192
+
193
+ ## Sizing to the viewport on mobile
194
+
195
+ The host sizes your UI's iframe to the visible viewport, so size your UI to fill its container rather than the browser viewport: prefer `height: 100%` (down through `html`, `body`, and the root element) with flex or grid layouts over viewport units.
196
+
197
+ If you do reach for viewport units, use `dvh` with a `vh` fallback. On iOS WebKit `100vh` resolves to the tall (URL-bar-collapsed) viewport even while the bar is showing, so a `100vh` element runs off the bottom of the screen; `100dvh` tracks the live visible viewport:
198
+
199
+ ```css
200
+ min-height: 100vh; /* fallback for older browsers */
201
+ min-height: 100dvh; /* tracks the live viewport on iOS */
202
+ ```
203
+
204
+ In MUI `sx`, where you cannot repeat a key, express the fallback with `@supports`:
205
+
206
+ ```ts
207
+ sx={{ minHeight: '100vh', '@supports (height: 100dvh)': { minHeight: '100dvh' } }}
208
+ ```
209
+
210
+ Embedded in the host this rarely bites, because an iframe has no collapsing browser chrome and `vh` resolves to the iframe's own height. The `dvh` form keeps your UI correct if it is ever opened standalone in a mobile browser, and the scaffold templates already follow it.
211
+
212
+ ## Customising Vite (dev and build)
213
+
214
+ When the SDK starts Vite for your UI (whether for the dev server or a production build), you can customise Vite's behaviour by creating a `vite.config.ts` file. The SDK loads it and merges it with its own inline config.
215
+
216
+ ### Where to put `vite.config.ts`
217
+
218
+ **Put it at the project root** (alongside `seriousgaming.sdk.json`). This is the recommended location: one file applies to every UI in the package, and the same file is used by both `sdk dev` and `sdk build`.
219
+
220
+ ```
221
+ my-package/
222
+ ├── seriousgaming.sdk.json
223
+ ├── vite.config.ts ← recommended location
224
+ ├── ui/
225
+ │ ├── index.html
226
+ │ └── src/
227
+ └── session/
228
+ └── ...
229
+ ```
230
+
231
+ ### Per-UI overrides
232
+
233
+ You can also drop a `vite.config.ts` inside an individual `ui/` directory. The SDK loads it in addition to the project-root config and the per-UI file's values override the root's on conflicts. This is useful when one UI needs a specific alias or plugin that would break the others, but in practice the root config is almost always enough, and per-UI files multiply maintenance.
234
+
235
+ **Don't keep both a root config and a per-UI config for the same UI unless you really mean to.** If the SDK finds both while building a given UI it prints a warning and asks you to consolidate. Merging still happens so the build doesn't break, but the warning is telling you that the intent is unclear.
236
+
237
+ ### What merges and what doesn't
238
+
239
+ The merge order is:
240
+
241
+ ```
242
+ project-root vite.config.ts → ui/vite.config.ts → SDK inline config
243
+ (baseline) (overrides root) (SDK owns these)
244
+ ```
245
+
246
+ **Additive options merge cleanly.** `resolve.dedupe`, `resolve.alias`, `optimizeDeps.include`, `esbuild`, extra `plugins`, and similar fields are not set (or only partially set) by the SDK, so your entries are combined with the SDK's.
247
+
248
+ **The SDK wins on structural fields.** `root`, `base`, `build.outDir`, `build.rollupOptions.input`, and the dev-server `server.middlewareMode`/`appType`/`hmr` settings are owned by the SDK and cannot be overridden: trying to set them in `vite.config.ts` has no effect.
249
+
250
+ A common use case is preventing duplicate package instances when using third-party React libraries:
251
+
252
+ ```typescript
253
+ // vite.config.ts (project root)
254
+ import { defineConfig } from 'vite';
255
+
256
+ export default defineConfig({
257
+ resolve: {
258
+ dedupe: ['react', 'react-dom'],
259
+ },
260
+ });
261
+ ```
262
+
263
+ See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md) for a full explanation of when and why this is needed.