@seriousgaming/sdk-tools 1.0.0 → 1.1.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 (165) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20003 -5523
  17. package/dist/client.js +15534 -1134
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +60 -4
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +64 -3
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +2 -9
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +29 -35
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +194 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +5 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +2 -2
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -0,0 +1,194 @@
1
+ # Theming and branding
2
+
3
+ Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
4
+
5
+ **Keywords:** theme, branding, white-label, brand, logo, fonts, colours, dark mode, createSurfaceTheme, useBrand, useBrandLogo, brandFromTheme, SurfaceLoading, loading screen, --brand, brand file
6
+
7
+ ## What the host sends
8
+
9
+ Every surface receives a theme from the host, and receives it again whenever it changes. A theme has:
10
+
11
+ - **A mode**: `'light'` or `'dark'`, the scheme the surface should paint in now
12
+ - **Six colour roles for each mode**: `primary`, `secondary`, `success`, `error`, `warning` and `info`, each with a `contrastText` the host guarantees meets WCAG AA (4.5:1) against it
13
+ - **Page colours for each mode**: `background` (the page), `surface` (cards and panels) and `text`, with `text` readable on both
14
+ - **A brand**: always its `name`, and, where the brand has them, a `logo` for each background (`onLight` and `onDark`), a square `icon`, and the `fonts` its headings and body text are set in
15
+
16
+ A brand with no logo, icon or fonts is normal, and your game must look right with just a name. The SDK never invents a logo of its own: a white-label host never shows anybody else's.
17
+
18
+ A host that predates brands sends neither a brand nor page colours. The wrapper fills them in, with a brand whose name is empty and a plain white or near-black page, so your game never has to check for them.
19
+
20
+ Read the theme with your surface's hook: `useUserInterfaceTheme()` in a game or waiting room UI, `useSessionUserInterfaceTheme()` in a session UI, `useSettingsEditorTheme()` in a setup screen or scenario editor, and `usePresentation().theme` in a presentation.
21
+
22
+ ## Apply the theme with createSurfaceTheme
23
+
24
+ `createSurfaceTheme` turns the host's theme into Material-UI theme options: every role with its `contrastText`, the page colours, and the brand's fonts. Pass it to `createTheme` first, then your own shape and component overrides:
25
+
26
+ ```typescript
27
+ // ui/src/theme.ts
28
+ import { createTheme } from '@mui/material/styles';
29
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
30
+ import { useMemo } from 'react';
31
+
32
+ export const useAppTheme = () => {
33
+ const theme = useUserInterfaceTheme();
34
+ return useMemo(
35
+ () =>
36
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
37
+ shape: { borderRadius: 10 },
38
+ components: {
39
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
40
+ },
41
+ }),
42
+ [theme]
43
+ );
44
+ };
45
+ ```
46
+
47
+ `fonts.body` (and `fonts.heading`) name the fonts your game bundles itself, used whenever the host's brand names none. The family must be the one your font package registers: `@fontsource-variable/work-sans` registers `Work Sans Variable`, not `Work Sans`.
48
+
49
+ `createSurfaceTheme` returns plain data, so the SDK does not depend on Material-UI. A game built on another component library can read the same fields from the theme itself.
50
+
51
+ ## Show the host's logo and name
52
+
53
+ `useBrandLogo()` picks the logo drawn for the mode the surface is painting in, falls back to the other one when the host sent only one, and returns `undefined` when the brand has no logo:
54
+
55
+ ```tsx
56
+ import { useBrandLogo } from '@seriousgaming/sdk/ui';
57
+
58
+ export function HostLogo() {
59
+ const logo = useBrandLogo();
60
+ return logo ? <img src={logo.src} alt={logo.alt} height={28} /> : null;
61
+ }
62
+ ```
63
+
64
+ `logo.drawnFor` says which background the artwork was made for. It differs from the current mode only when the host sent a single variant, which you can meet by drawing the logo on a panel of that colour.
65
+
66
+ `useBrand()` returns the whole brand. Use its `name` in copy rather than naming a platform, allowing for the empty name a host that predates brands leaves:
67
+
68
+ ```tsx
69
+ const { name } = useBrand();
70
+ const title = name ? t('welcomeTo', { name }) : t('welcome');
71
+ ```
72
+
73
+ Both hooks work on every surface. Keep a scenario's own logo, such as a fictional company in the case study, as content in a setting or an asset. The host's brand is for the interface around the game.
74
+
75
+ ## Fonts
76
+
77
+ When the host's brand names fonts, the wrapper loads them before your surface first paints, so the text does not visibly change font as they arrive. It waits at most 1.5 seconds; on a slow connection the surface paints in the fallback fonts and swaps when the brand's arrive. `createSurfaceTheme` puts the brand's body font on all text and its heading font on `h1` to `h6`.
78
+
79
+ Fonts have to come from the host, on the surface's own origin, because the content security policy a game runs under admits fonts from nowhere else. Bundle your own fallback font with the game, as the starter game does.
80
+
81
+ ## Presentations
82
+
83
+ A slide deck takes the host's theme through the deck library's `brandFromTheme`, which maps the accents and their text colours, the page colours and the fonts onto a deck brand:
84
+
85
+ ```tsx
86
+ import { brandFromTheme, Deck } from '@seriousgaming/deck';
87
+ import { usePresentation } from '@seriousgaming/sdk/ui';
88
+ import { useMemo } from 'react';
89
+
90
+ export default function App() {
91
+ const { theme, game } = usePresentation();
92
+ const brand = useMemo(() => brandFromTheme(theme), [theme]);
93
+ return (
94
+ <Deck brand={brand} title={game.name}>
95
+ {/* slides */}
96
+ </Deck>
97
+ );
98
+ }
99
+ ```
100
+
101
+ It uses the light palette whatever mode the facilitator's screen is in, because slides are projected and a projector washes out a dark slide. Pass `{ mode: 'dark' }` to use the dark one. A deck given no brand uses the Serious Gaming colours and fonts.
102
+
103
+ ## The loading screen
104
+
105
+ Until the host has sent everything a surface needs, and the brand's fonts have loaded, the wrapper shows its `fallback`. The default is `SurfaceLoading`: a small spinner in the browser's own light or dark scheme, with no text to translate. Pass your own to replace it:
106
+
107
+ ```tsx
108
+ <UserInterfaceWrapper fallback={<MySplash />}>
109
+ <App />
110
+ </UserInterfaceWrapper>
111
+ ```
112
+
113
+ Once the host's theme has arrived, the default spinner paints in the theme's mode, its page colour and its primary colour, so a dark session does not flash white while the brand's fonts load. Before then it can only follow the browser's own scheme.
114
+
115
+ Most viewers never see the fallback. The wrapper tells the host when your surface's first paint is on screen, and a host that listens keeps its own branded loading screen over the frame until then. The dev server does, showing the picked brand's loading animation, or its logo over a spinner in its primary colour, so you see what a facilitator sees.
116
+
117
+ To look at either loading screen for longer than a moment, use the **Loading** menu in the dev drawer. **Hold the host's loading screen** keeps the dev server's cover over every surface. **Hold the game's loading screen** lifts the cover and sends each surface its theme and nothing else it waits for, so your fallback stays up in the host's colours. Switching reloads the surfaces, and the choice lasts for the browser tab only.
118
+
119
+ ## Should a game honour the brand?
120
+
121
+ A game may ignore the host's brand and paint in its own identity: nothing checks. But a white-label host sends its brand because its clients expect to see it, so use `createSurfaceTheme` and show the logo unless your game has a strong reason not to.
122
+
123
+ ## Preview your game in another brand
124
+
125
+ The dev server dresses every surface in a brand you pick from the **Brand** menu in the dev drawer, next to the colour scheme. Switching sends the new theme to every open surface without reloading it, which also shows whether your game follows a theme change. It offers:
126
+
127
+ - **Serious Gaming**, the default
128
+ - **Plain brand**: MUI's own colours, a plain page, and a brand that is a name and nothing else, the least a host sends
129
+ - **Awkward Test Brand**: a pale yellow primary, a very wide logo drawn only for light backgrounds, and no fonts or loader, to show up hard-coded colours and layouts that assume a short logo
130
+
131
+ To preview a client's brand, write a brand file and pass it to `sdk dev`:
132
+
133
+ ```bash
134
+ pnpm run sdk dev --brand ../brands/acme/brand.json
135
+ ```
136
+
137
+ The brand joins the menu and is selected. Repeat `--brand` for more than one; the first is selected. A brand file is JSON, with every file it names relative to it:
138
+
139
+ ```json
140
+ {
141
+ "name": "Acme",
142
+ "light": {
143
+ "primary": "#21244F",
144
+ "secondary": "#17D1C7",
145
+ "background": "#FFFFFF",
146
+ "surface": "#F5F5F7",
147
+ "text": "#1B1F2A"
148
+ },
149
+ "dark": { "primary": "#8C8FE0", "secondary": "#17D1C7" },
150
+ "logo": { "onLight": "logo-on-light.svg", "onDark": "logo-on-dark.svg" },
151
+ "loader": { "onLight": "loader-on-light.svg", "onDark": "loader-on-dark.svg" },
152
+ "icon": "icon.svg",
153
+ "fonts": {
154
+ "body": {
155
+ "family": "Acme Sans",
156
+ "sources": [{ "url": "fonts/acme-sans.woff2", "weight": "100 900" }]
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ - `name` is required, and everything else is optional
163
+ - `loader` is an animation for the dev server's own loading screen, as a host would show its own: an animated SVG, WebP or GIF. It is never sent to your game
164
+ - A colour role a mode leaves out keeps the Serious Gaming one. Page colours a mode leaves out are a plain page's, never another brand's
165
+ - The dev server works out every `contrastText`, and a `text` that is not readable on both `background` and `surface` is replaced with black or white, or the page with a plain one where neither reads
166
+ - Files are served from the dev server's asset origin, as a real host serves them. A path must stay inside the brand file's directory, and a remote URL is refused, because no game could load it. A `data:` URL is used as it is
167
+ - The file is read again whenever the page loads, so an edit shows on refresh
168
+
169
+ Keep brand files beside the games that use them, not inside a game package: a brand belongs to a host, and the host sends it.
170
+
171
+ ## Testing
172
+
173
+ `createMockBrand()` from `@seriousgaming/sdk/ui/testing` gives a name and a logo for each background, as `data:` URLs. Pass it in a mock theme to test a component that reads the brand:
174
+
175
+ ```tsx
176
+ import {
177
+ createMockBrand,
178
+ createMockUserInterfaceTheme,
179
+ renderUserInterface,
180
+ } from '@seriousgaming/sdk/ui/testing';
181
+
182
+ renderUserInterface(<Header />, {
183
+ theme: createMockUserInterfaceTheme({ brand: createMockBrand({ name: 'Acme' }) }),
184
+ });
185
+ expect(screen.getByRole('img', { name: 'Acme' })).toBeInTheDocument();
186
+ ```
187
+
188
+ Test without a logo too: `createMockUserInterfaceTheme()` sends a brand that is only a name, the least a host sends.
189
+
190
+ ## Related
191
+
192
+ - [Building user interfaces](./ui.md): the theme object and the theme preference
193
+ - [Building presentations](./presentation.md): the deck library
194
+ - [Production security constraints](./production-constraints.md): why fonts and images come from the surface's own origin
@@ -1,6 +1,8 @@
1
1
  # Tick controllers
2
2
 
3
- A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished. This guide explains the model, then is the reference for writing one.
3
+ A tick controller makes ticks happen on their own, on a schedule your logic decides, and can say when the game is finished.
4
+
5
+ This guide explains the model, then is the reference for writing one.
4
6
 
5
7
  ## The model
6
8
 
@@ -27,6 +29,8 @@ Use a tick controller when:
27
29
 
28
30
  You do not need one for a game where participants advance each tick themselves, and you do not need one just to end a game on a goal: the engine can do that alone.
29
31
 
32
+ Automatic or facilitator-led pacing is also a learning-design choice: a timer adds time pressure, while manual ticks leave the room time to discuss each decision.
33
+
30
34
  ## The result
31
35
 
32
36
  `GetTickController` returns a [`TickControllerResult`](../api/sdk.md#tickcontrollerresult):
@@ -84,7 +88,7 @@ export const GetTickController: GetTickControllerFunction<Context, Settings> = a
84
88
 
85
89
  ### Interval bounds
86
90
 
87
- The effective interval (the gap until the next automatic tick) is bounded: a minimum of 30 seconds and a maximum of 7 days. `intervalTick()` rejects anything outside that range, as well as fractional, zero, negative, `NaN`, and `Infinity` values, with a message that names the limit and points you back at the helper. A value written in seconds fails loudly: `intervalTick(60)` is 60 milliseconds, and is refused with 'Effective tick cadence of 60 ms (under a second) is below the 30-second minimum (30000 ms)'. The same bounds apply to `scheduledTick()` (see [Scheduling at fixed times](#scheduling-at-fixed-times)), measured against the real gap to `nextTickAt`. If a game needs to tick less often than once a week, set `enabled: false` and drive ticks by another means.
91
+ The effective interval (the gap until the next automatic tick) is bounded: a minimum of 30 seconds and a maximum of seven days. `intervalTick()` rejects anything outside that range, as well as fractional, zero, negative, `NaN`, and `Infinity` values, with a message that names the limit and points you back at the helper. A value written in seconds fails loudly: `intervalTick(60)` is 60 milliseconds, and is refused with 'Effective tick cadence of 60 ms (under a second) is below the 30-second minimum (30000 ms)'. The same bounds apply to `scheduledTick()` (see [Scheduling at fixed times](#scheduling-at-fixed-times)), measured against the real gap to `nextTickAt`. If a game needs to tick less often than once a week, set `enabled: false` and drive ticks by another means.
88
92
 
89
93
  ### Cadence cookbook
90
94
 
@@ -383,7 +387,7 @@ Each call has a time limit, like an engine call (see [Time limits](./engine.md#t
383
387
 
384
388
  ### Results outside the bounds
385
389
 
386
- A result the helpers would refuse, such as a hand-written `intervalMs: 10_000`, is not honoured as it stands. The dev server clamps it to the nearest bound, 30 seconds or 7 days, and reports the clamp as an error so you see it, which is what a production runtime does too. Build your results with `intervalTick()` and `scheduledTick()` to catch this while you write the controller rather than while it runs.
390
+ A result the helpers would refuse, such as a hand-written `intervalMs: 10_000`, is not honoured as it stands. The dev server clamps it to the nearest bound, 30 seconds or seven days, and reports the clamp as an error so you see it, which is what a production runtime does too. Build your results with `intervalTick()` and `scheduledTick()` to catch this while you write the controller rather than while it runs.
387
391
 
388
392
  A result holds only `enabled`, `intervalMs`, `nextTickAt` and `complete`, and `enabled` and `complete` are booleans. A result with any other key, or with `complete: 'no'`, is not clamped: the evaluation fails, the failure is reported naming the key, and the timer stops, as it does when the controller throws.
389
393
 
@@ -507,7 +511,7 @@ Put the timezone in the tick controller's settings to make it configurable per g
507
511
 
508
512
  The `intervalMs` field is computed for you, so a UI drawing a progress bar has the window's full length to draw against.
509
513
 
510
- `scheduledTick()` validates the effective cadence (the real gap to `nextTickAt`) against the same 30-second floor and 7-day ceiling as `intervalTick()`. A schedule that would tick sooner than 30 seconds out, or further than 7 days out, is rejected with a clear message rather than honoured. A `nextTickAt` already in the past is exempt: it fires one immediate catch-up tick (see [Missed ticks](#missed-ticks)).
514
+ `scheduledTick()` validates the effective cadence (the real gap to `nextTickAt`) against the same 30-second floor and seven-day ceiling as `intervalTick()`. A schedule that would tick sooner than 30 seconds out, or further than seven days out, is rejected with a clear message rather than honoured. A `nextTickAt` already in the past is exempt: it fires one immediate catch-up tick (see [Missed ticks](#missed-ticks)).
511
515
 
512
516
  ### Missed ticks
513
517
 
@@ -1,6 +1,8 @@
1
1
  # Type safety best practices
2
2
 
3
- This guide ensures you create proper types and avoid common type safety pitfalls when building Serious Gaming games.
3
+ The SDK generates TypeScript types from your schemas, so a misspelt variable fails when you build rather than in front of a room.
4
+
5
+ This guide covers the rules that keep that guarantee, and the shortcuts that quietly break it.
4
6
 
5
7
  ## Core principle
6
8
 
@@ -496,11 +498,11 @@ export interface Context {
496
498
 
497
499
  Type safety in Serious Gaming:
498
500
 
499
- 1. **Catches mistakes at build time** - not runtime
500
- 2. **IDE assistance** - autocomplete, rename refactoring
501
- 3. **Self-documenting code** - types are documentation
502
- 4. **Prevents silent failures** - schema enforces constraints
503
- 5. **Easier debugging** - stack traces point to real issues, not parsing errors
501
+ 1. **Catches mistakes at build time**: not runtime
502
+ 2. **IDE assistance**: autocomplete, rename refactoring
503
+ 3. **Self-documenting code**: types are documentation
504
+ 4. **Prevents silent failures**: schema enforces constraints
505
+ 5. **Easier debugging**: stack traces point to real issues, not parsing errors
504
506
 
505
507
  When you skip proper typing, you:
506
508
 
@@ -1,15 +1,8 @@
1
1
  # Building user interfaces
2
2
 
3
- This guide shows you how to create and develop custom user interfaces for your games.
3
+ The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
4
4
 
5
- ## What you'll learn
6
-
7
- - How to create a new user interface
8
- - How to read game context and settings
9
- - How to write to context and request a tick
10
- - How to work with participants, teams, observers, and walkthroughs
11
- - How to show the tick timer, localise, theme, and upload files
12
- - How to reach an LLM from a UI, through an endpoint
5
+ This guide covers creating it, reading the game's state and settings, writing decisions back, and styling, testing, and building it.
13
6
 
14
7
  ## Creating a user interface
15
8
 
@@ -80,6 +73,7 @@ The `useUserInterfaceData` hook provides:
80
73
 
81
74
  - **`data`**: The game context (read-only by default)
82
75
  - **`settings`**: The settings resources this UI lists in `settings`, keyed by identifier (`settings.ui.RefreshRate`). Read-only, and fixed when play starts
76
+ - **`scenarioName`**: The name of the scenario the session is running, in the session's language, or `null` with none. For display only: show it, never branch on it, because a facilitator's own copy of a scenario has a name of its own (see [Showing the scenario](./engine.md#showing-the-scenario))
83
77
  - **`completedTicks`**: The number of ticks this team has completed: `0` until the first tick commits, `N - 1` while round N is played. Use it to bound a review scrubber (see below)
84
78
  - **`isRoundProcessing`**: Whether the host is running a tick right now (see below)
85
79
  - **`setData`**: Function to update context (available only for capabilities in `writes`)
@@ -212,11 +206,11 @@ Because arrays replace wholesale, a shared array that participants read, modify,
212
206
 
213
207
  Understanding when `setData` changes become visible is critical for designing your game loop correctly.
214
208
 
215
- 1. **Immediate in context**: When a UI calls `setData`, the change is merged into the game context right away. Other UIs reading the same capability will see the updated value immediately (via WebSocket sync in the dev server).
209
+ 1. **Immediate in context**: When a UI calls `setData`, the change is merged into the game context right away. Other UIs reading the same capability will see the updated value immediately (via WebSocket sync in the dev server)
216
210
 
217
- 2. **Engines process on next tick**: Engine `Run` functions only execute when a tick advances. They see whatever context exists at that point, including any `setData` changes made since the last tick.
211
+ 2. **Engines process on next tick**: Engine `Run` functions only execute when a tick advances. They see whatever context exists at that point, including any `setData` changes made since the last tick
218
212
 
219
- 3. **Multiple `setData` calls accumulate**: If a participant changes Price to 50, then to 75 before the next tick, the engine will see 75. Only the final state matters.
213
+ 3. **Multiple `setData` calls accumulate**: If a participant changes Price to 50, then to 75 before the next tick, the engine will see 75. Only the final state matters
220
214
 
221
215
  **Design implication**: Use `setData` for participant input within a tick (decisions, adjustments, form entries). Use tick advancement to trigger computation (the engine runs, state updates cascade). Don't try to run game logic inside `setData` handlers: that bypasses the tick mechanism and breaks the reactive spreadsheet model.
222
216
 
@@ -265,10 +259,10 @@ const handleStart = () => {
265
259
 
266
260
  This works correctly: the `setData` change is merged into context immediately, and the tick that follows will see `Started: true` when the engine runs. However, there is a brief intermediate state that is worth understanding:
267
261
 
268
- 1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away.
269
- 2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds.
270
- 3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results.
271
- 4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values.
262
+ 1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away
263
+ 2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds
264
+ 3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results
265
+ 4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values
272
266
 
273
267
  In most cases this intermediate state is invisible to the participant, because the tick completes in milliseconds. But if your UI derives display values from both `setData` fields and engine-computed fields, you may see a brief flicker. Two strategies to handle this:
274
268
 
@@ -656,8 +650,8 @@ This pattern is deliberate: by keeping the per-frame state inside one leaf compo
656
650
 
657
651
  `nextTickAt` is an absolute timestamp in the **same clock-space as `Date.now()`**, so consumer code never needs to compute clock offsets: just subtract. The host is responsible for stamping it in a clock the consumer will recognise:
658
652
 
659
- - For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is.
660
- - For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown.
653
+ - For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is
654
+ - For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown
661
655
 
662
656
  The wrapper does not attempt to re-translate `nextTickAt` on receipt. With only the value and the receiver's `Date.now()` it cannot distinguish 'the host's clock is N ms ahead of mine' from 'this message has been sitting around for N ms', and getting that wrong is exactly how a stored timer state replayed to a remounted iframe would drift. Trusting the timestamp verbatim is what makes the countdown stay accurate when the iframe is remounted.
663
657
 
@@ -996,10 +990,10 @@ type UserInterfaceModeColors = {
996
990
  };
997
991
  ```
998
992
 
999
- - `mode`: Indicates whether the current theme is `'light'` or `'dark'`.
1000
- - `light`: An object containing the colour palette for the light theme.
1001
- - `dark`: An object containing the colour palette for the dark theme.
1002
- - `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.
993
+ - `mode`: Indicates whether the current theme is `'light'` or `'dark'`
994
+ - `light`: An object containing the colour palette for the light theme
995
+ - `dark`: An object containing the colour palette for the dark theme
996
+ - `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
1003
997
 
1004
998
  ```tsx
1005
999
  const colors = theme.mode === 'light' ? theme.light : theme.dark;
@@ -1041,48 +1035,33 @@ function ThemeSwitcher() {
1041
1035
  }
1042
1036
  ```
1043
1037
 
1044
- `setThemePreference` is available on every UI surface (game, waiting room, session, configuration). No `uses` declaration is needed, because theme preference is not gated.
1038
+ `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.
1045
1039
 
1046
1040
  ### Integrating with Material-UI
1047
1041
 
1048
- The default user interface template uses [Material-UI](https://mui.com/) for its component library.
1049
-
1050
- Here's how to create a dynamic theme in your `App.tsx`:
1042
+ 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:
1051
1043
 
1052
1044
  ```typescript
1053
- // src/App.tsx
1054
- import React, { useMemo } from 'react';
1055
- import { createTheme, ThemeProvider } from '@mui/material';
1056
- import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
1057
- import MyComponent from './MyComponent';
1045
+ // src/theme.ts
1046
+ import { createTheme } from '@mui/material/styles';
1047
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
1048
+ import { useMemo } from 'react';
1058
1049
 
1059
- function App() {
1050
+ export const useAppTheme = () => {
1060
1051
  const theme = useUserInterfaceTheme();
1061
-
1062
- const customTheme = useMemo(() => {
1063
- const themeColors = theme.mode === 'light' ? theme.light : theme.dark;
1064
- return createTheme({
1065
- palette: {
1066
- mode: theme.mode,
1067
- primary: { main: themeColors.primary, contrastText: themeColors.contrastText.primary },
1068
- secondary: { main: themeColors.secondary, contrastText: themeColors.contrastText.secondary },
1069
- success: { main: themeColors.success, contrastText: themeColors.contrastText.success },
1070
- error: { main: themeColors.error, contrastText: themeColors.contrastText.error },
1071
- warning: { main: themeColors.warning, contrastText: themeColors.contrastText.warning },
1072
- info: { main: themeColors.info, contrastText: themeColors.contrastText.info },
1073
- }
1074
- });
1075
- }, [theme]);
1076
-
1077
- return (
1078
- <ThemeProvider theme={customTheme}>
1079
- <MyComponent />
1080
- </ThemeProvider>
1052
+ return useMemo(
1053
+ () =>
1054
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
1055
+ shape: { borderRadius: 10 },
1056
+ }),
1057
+ [theme]
1081
1058
  );
1082
- }
1059
+ };
1083
1060
  ```
1084
1061
 
1085
- 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.
1062
+ `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.
1063
+
1064
+ 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).
1086
1065
 
1087
1066
  ## Sizing to the viewport on mobile
1088
1067
 
@@ -1294,27 +1273,27 @@ The sections above are the parts of a complete chat surface. Beyond them, a chat
1294
1273
 
1295
1274
  ## Best practices
1296
1275
 
1297
- 1. **Use type safety** - Import generated types from `./types`
1276
+ 1. **Use type safety**: import generated types from `./types`
1298
1277
  - ✅ `useUserInterfaceData<Context, Settings>()`
1299
1278
  - ❌ `useUserInterfaceData<any, any>()`
1300
1279
 
1301
- 2. **Access data via destructuring** - Get data, settings, and setData from the hook
1280
+ 2. **Access data via destructuring**: get data, settings, and setData from the hook
1302
1281
  - ✅ `const { data, settings, setData } = useUserInterfaceData<Context, Settings>()`
1303
1282
  - ❌ Trying to access missing hooks like `useUserInterfaceContext`
1304
1283
 
1305
- 3. **Declare every capability you render** - `data` carries exactly what the bundle declares
1284
+ 3. **Declare every capability you render**: `data` carries exactly what the bundle declares
1306
1285
  - ✅ Add the capability to `reads` (or `writes`) and read `data.inventory.Stock` directly
1307
1286
  - ❌ Render a capability the bundle never declared and guard the `undefined` with `?.`
1308
1287
 
1309
- 4. **Respect write boundaries** - Only update capabilities in `writes`
1288
+ 4. **Respect write boundaries**: only update capabilities in `writes`
1310
1289
  - ✅ Use `setData` for capabilities in `writes`
1311
1290
  - ❌ Try to update read-only capabilities
1312
1291
 
1313
- 5. **Responsive design** - Ensure UIs work on different screen sizes
1292
+ 5. **Responsive design**: ensure UIs work on different screen sizes
1314
1293
  - ✅ Use flexbox/grid, size to the container, test on mobile
1315
1294
  - ❌ Fixed widths, desktop-only design, `100vh` without a `dvh` fallback
1316
1295
 
1317
- 6. **Performance** - Use React hooks efficiently
1296
+ 6. **Performance**: use React hooks efficiently
1318
1297
  - ✅ `useEffect` for side effects, memoisation for expensive renders
1319
1298
  - ❌ Recalculate everything on every render
1320
1299
 
@@ -1389,5 +1368,5 @@ See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md)
1389
1368
 
1390
1369
  ## Next steps
1391
1370
 
1392
- - [Internationalisation guide](./internationalization.md) - Add multi-language support
1393
- - [Getting started](../getting-started.md) - Run the dev server
1371
+ - [Internationalisation guide](./internationalization.md): add multi-language support
1372
+ - [Getting started](../getting-started.md): run the dev server
@@ -500,9 +500,11 @@ Every handler receives `session` (where the session stands: `completedTicks`, `m
500
500
  grep -rn "caller.teamId" endpoints
501
501
  ```
502
502
 
503
- ### 7e. Give the scenario editor endpoints that need no session
503
+ ### 7e. Give the scenario editor scenario-scoped endpoints
504
504
 
505
- The scenario editor edits a scenario, not a session, so the build refuses one that lists an endpoint declaring any `reads`, `writes` or `actions` (`EDITOR_ENDPOINT_STATEFUL`). A 0.6 scenario builder could list one, because the dev server answered it from whatever session was running. For each endpoint the build names, either delete the `reads`, `writes` and `actions` it does not need, or give the editor an endpoint of its own without them. An endpoint the editor calls receives its declared `settings` as the scenario being edited resolves them, the editor's unsaved changes included, so declare `settings` rather than passing the values in the request. Its `context` is empty, `participants` is empty, `session` has played nothing and holds no teams, and `caller` carries `role: 'author'` rather than `'facilitator'` and no `sessionId`, which is now optional: a handler that used it as a `string` needs a fallback, and one that checked for `'facilitator'` to accept the editor's calls checks for `'author'`.
505
+ The scenario editor edits a scenario, not a session, so it lists only endpoints declaring `"scope": "scenario"`, and the build refuses any other (`EDITOR_ENDPOINT_NOT_SCENARIO`). A 0.6 scenario builder could list any endpoint, because the dev server answered it from whatever session was running. For each endpoint the build names, set `"scope": "scenario"` and delete the `reads`, `writes`, `actions` and `roster` it declares (`SCENARIO_ENDPOINT_STATEFUL`), or give the editor an endpoint of its own. Then run `pnpm run sdk generate`. A scenario-scoped endpoint receives its declared `settings` as the scenario being edited resolves them, the editor's unsaved changes included, so declare `settings` rather than passing the values in the request. It receives no `context`, `participants` or `session`, which its generated `Handler` type no longer offers, and `caller` carries `role: 'author'` rather than `'facilitator'` and no `sessionId`, which is now optional: a handler that used it as a `string` needs a fallback, and one that checked for `'facilitator'` to accept the editor's calls checks for `'author'`. See [Scenario-scoped endpoints](./endpoints.md#scenario-scoped-endpoints).
506
+
507
+ **Already on 1.0?** This step is new in 1.1. 1.0 let the editor list a session-scoped endpoint that declared no `reads`, `writes` or `actions`, and 1.1 refuses it, so a package already on 1.0 with such an endpoint needs this step alone to move to 1.1. A production host that predates 1.1 refuses a scenario-scoped endpoint, so check the host supports it before you publish.
506
508
 
507
509
  ## Step 8: rename each validator's `Run` to `UpdateData`
508
510
 
@@ -631,7 +633,7 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
631
633
  - **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
632
634
  - **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
633
635
  - **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
634
- - **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium`
636
+ - **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium --only-shell` (drop `--only-shell` if you run tests with `--headed` or `--ui`)
635
637
 
636
638
  Nothing breaks if you skip the new features 1.0 adds, but several replace workarounds games carry: the engine's private `state` and `complete: true` (see [Engine](./engine.md#keeping-memory-between-ticks) and [Game completion](./tick-controller.md#game-completion)), capabilities with `"lifetime": "session"` that undo and reset leave alone ([Lifetime](./capabilities.md#lifetime)), a facilitator's slide deck in the `presentation/` slot ([Building presentations](./presentation.md)), endpoints that act on the session or take files ([Endpoints](./endpoints.md)), and the `useAsset`, `usePastState` and `useViewerStorage` hooks ([User interfaces](./ui.md)).
637
639
 
@@ -1,6 +1,6 @@
1
1
  # Validators
2
2
 
3
- A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it.
3
+ A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs. It returns a verdict and never modifies the proposed state. The runtime applies the write, or runs the tick, only when every validator that runs allows it. A validator can also gate a scenario, refusing one whose settings break your game's rules ([Gating scenarios](#gating-scenarios)).
4
4
 
5
5
  ## The model
6
6
 
@@ -17,7 +17,7 @@ A validator sits between a UI's submission and the runtime's apply step, on the
17
17
  type ValidationResult = { ok: true } | { ok: false; message: string };
18
18
  ```
19
19
 
20
- A validator's logic exports one function per action it gates. `UpdateData` gates a context write; `RequestTick` gates a request for the next tick ([Gating tick requests](#gating-tick-requests)). Export either or both: a validator is run only for the actions it has a gate for, and the build reads which from the exports, so there is nothing to declare in the bundle.
20
+ A validator's logic exports one function per thing it gates. `UpdateData` gates a context write; `RequestTick` gates a request for the next tick ([Gating tick requests](#gating-tick-requests)); `Scenario` gates a scenario ([Gating scenarios](#gating-scenarios)). Export any of them: a validator is run only for what it has a gate for, and the build reads which from the exports, so there is nothing to declare in the bundle.
21
21
 
22
22
  ### Why reject rather than modify
23
23
 
@@ -61,7 +61,7 @@ validators/decisionlimit/
61
61
  │ ├── logic.ts # UpdateData, and optionally RequestTick
62
62
  │ └── logic.test.ts
63
63
  ├── defaults.ts # Generated: the starting context and settings, for tests
64
- └── types.ts # Generated: Context, Settings, ValidatorFunction, RequestTickFunction
64
+ └── types.ts # Generated: Context, Settings, ValidatorFunction, RequestTickFunction, ScenarioFunction
65
65
  ```
66
66
 
67
67
  `identifier` names the directory; it is not written into `validator.sdk.json`. The capabilities in `reads` must already exist (here, a `decisions` capability).
@@ -96,6 +96,8 @@ The validator receives:
96
96
 
97
97
  The `message` string is free-form. The SDK does not prescribe a format, so games encode whatever structure they need (a locale key, a JSON blob) inside it.
98
98
 
99
+ A refusal is feedback to the participant, so make the message say why the decision was refused, not just that it was.
100
+
99
101
  ### Reads only
100
102
 
101
103
  Validators declare `reads` but no `writes`. They are pure verdicts and cannot mutate state. The generated `Context` type reflects only the capabilities they read from.
@@ -187,6 +189,64 @@ It runs on every request, before the tick starts. The rule that a validator runs
187
189
 
188
190
  A refusal stops the tick, and the participant's `requestTick()` rejects with the validator's message, as a refused write does. Only a request from a player surface (a participant's or an observer's) is gated. The facilitator's own tick, from the session surface or the console, and a timer's tick are never gated, which is what lets the facilitator run a round the room is not allowed to yet. Undo and reset are never validated. The `pacing` capability in the example above is a shared one the facilitator raises from the session UI as each round opens.
189
191
 
192
+ ## Gating scenarios
193
+
194
+ A settings schema checks each value on its own. It cannot say that two values conflict, such as a lowest price above the highest, or that a value has no sensible default and every scenario must supply its own, such as the name of the client an edition is built for. A `Scenario` gate says both.
195
+
196
+ Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about as a dotted `path`; an empty array passes:
197
+
198
+ ```typescript
199
+ import type { ScenarioFunction } from '../types';
200
+
201
+ export const Scenario: ScenarioFunction = async ({ settings }) => {
202
+ const { MinPrice, MaxPrice } = settings.pricing;
203
+ const problems = [];
204
+ if (MinPrice > MaxPrice) {
205
+ problems.push({
206
+ path: 'pricing.MinPrice',
207
+ message: `The lowest price (£${MinPrice}) must be at or below the highest price (£${MaxPrice})`,
208
+ });
209
+ }
210
+ if (settings.edition.ClientName === '') {
211
+ problems.push({
212
+ path: 'edition.ClientName',
213
+ message: 'Every scenario names the client it is built for',
214
+ });
215
+ }
216
+ return problems;
217
+ };
218
+ ```
219
+
220
+ A game whose validator exports `Scenario` lists the feature in `seriousgaming.sdk.json`, and the build refuses it otherwise (`FEATURE_UNDECLARED`). A runtime that cannot run the gate then refuses the game, rather than saving scenarios your rules would refuse:
221
+
222
+ ```json
223
+ {
224
+ "requires": ["scenario-validation"]
225
+ }
226
+ ```
227
+
228
+ ### When it runs
229
+
230
+ - **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
231
+ - **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed
232
+ - **Never when a session starts.** By then its scenario has passed
233
+
234
+ ### It judges values, not where they came from
235
+
236
+ A saved scenario holds every setting, not only the ones its author changed, so the gate cannot tell a value the scenario supplied from one left at its default. Give a setting every scenario must replace an obviously empty default (`""`, `[]` or `{}`) and have the gate refuse that. Avoid a placeholder that could be a real choice, such as `0` for a price.
237
+
238
+ ### Write problems a person or an agent can act on
239
+
240
+ A problem's message is shown as it is, to whoever is editing the scenario, and an AI agent editing one has nothing else to go on. Say what is allowed, not only what is wrong ('must be at or below the highest price', not 'invalid'), and give the `path` of the setting to change.
241
+
242
+ ### Show the same problems while editing
243
+
244
+ The gate is the last word, and it runs on save. A [scenario editor](./scenario-editor.md) can show the same problems as the author types by importing the rules the gate uses. Put the rules in a file both can reach, such as `shared/scenario-rules.ts`, call it from the gate, and call it from the editor to mark each field. Rules shared with logic run in the logic environment too, so keep them to plain functions with no browser or Node APIs.
245
+
246
+ The gate reads no game state and receives no `actor`, `meta` or callbacks: there is no session or participant behind a scenario. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
247
+
248
+ The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
249
+
190
250
  ## Settings
191
251
 
192
252
  A validator reads [settings](./settings.md) the way every other resource does: list the settings resources in the bundle's `settings`, and it receives exactly those as `settings`, keyed by identifier. They resolve through the same layers as the engine's, so a scenario or the facilitator's setup screen can change a limit without touching the logic.
@@ -214,4 +274,5 @@ if (selected > settings.decisionlimit.MaxSelected) {
214
274
  ## Related
215
275
 
216
276
  - [Create a validator recipe](../recipes/create-validator.md): step-by-step scaffolding
277
+ - [Validate a game's scenarios recipe](../recipes/validate-scenarios.md): add a `Scenario` gate
217
278
  - [Hooks guide](hooks.md): for out-of-tick reactions
@@ -1,22 +1,15 @@
1
1
  # Building waiting room UIs
2
2
 
3
- Own the holding screen participants see while a session is parked, instead of accepting the host's stock panel.
3
+ The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
4
4
 
5
5
  **Keywords:** waiting room, holding screen, lobby, waiting to begin, session paused, park a session, break, waitingRoom, setWaitingRoom
6
6
 
7
- ## What you'll learn
8
-
9
- - What the waiting room is and who controls it
10
- - Why a waiting room UI is a game UI rather than a new kind of surface
11
- - How to tell 'not started yet' from 'parked mid-play'
12
- - How to start every session with the room already open
13
- - How to stop the tick clock while participants wait
14
- - How to let your own session UI open and close the room
15
-
16
7
  ## What is the waiting room?
17
8
 
18
9
  The waiting room is a single per-session flag. While it is open, every participant in the session sees a holding screen instead of the game UIs; while it is closed, they see the game. The facilitator toggles it, and the change reaches every team at once.
19
10
 
11
+ Holding participants here gives a facilitator space for a discussion or a briefing, between rounds or before play starts.
12
+
20
13
  ```
21
14
  Waiting room closed Waiting room open
22
15
  +---------------------+ +---------------------+