@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
@@ -6,6 +6,8 @@ This guide covers declaring them, reading them from logic and surfaces, overridi
6
6
 
7
7
  Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
8
8
 
9
+ **Keywords:** settings, parameters, settingsSchema, defaults, read settings, override settings, configure, scenario settings, locked settings, game settings, hidden values, sdk configure
10
+
9
11
  ## Overview
10
12
 
11
13
  A settings resource is a schema and nothing else. It lives at `settings/<identifier>/settings.sdk.json`, and a package may hold any number of them, as it does capabilities.
@@ -4,6 +4,8 @@ The `setup` slot holds the small form a facilitator fills in when they create a
4
4
 
5
5
  This guide covers creating one, building its form, and how it behaves in the dev server.
6
6
 
7
+ **Keywords:** setup screen, setup form, session creation, configures, per-session settings, number of rounds, requestPlay, start play, facilitator form
8
+
7
9
  ## What setup is
8
10
 
9
11
  A game holds at most one setup screen, at `setup/`. It is a slot, like `session` or `waiting_room`, so it carries no name of its own: the slot is its identifier.
@@ -143,7 +145,7 @@ An endpoint called from setup sees `caller.role` as `'facilitator'`.
143
145
  Setup is embedded in the host's page, not a page of its own:
144
146
 
145
147
  - **Leave the ground to the host.** Do not paint a page background. MUI's `CssBaseline` paints the body, so override it with `<GlobalStyles styles={{ body: { backgroundColor: 'transparent' } }} />`
146
- - **Prefer full-screen dialogs.** A centred modal inside an iframe is centred within the frame
148
+ - **Avoid dialogs with a backdrop.** A modal inside an iframe darkens only the frame, not the host's bar above it. Use a side panel, a confirmation beside the button that asked, or full screen
147
149
  - **Do not reproduce host chrome.** The language picker, the theme control, and the Play action live outside your iframe
148
150
 
149
151
  The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
@@ -6,6 +6,8 @@ The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. E
6
6
 
7
7
  The dev server ships with one provider adapter (ElevenLabs). Additional providers (OpenAI, Google Cloud, Azure, AWS Polly) will land behind a future `TTS_PROVIDER` env var without breaking changes to game code.
8
8
 
9
+ **Keywords:** speech, text-to-speech, TTS, generateSpeech, voice, voice presets, audio, ElevenLabs, ELEVENLABS_API_KEY, narration
10
+
9
11
  ## Overview
10
12
 
11
13
  `generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
@@ -13,7 +13,8 @@ Most of the starter game is ordinary, but four decisions in it are the ones a fi
13
13
  - **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and a hook puts each participant in charge of one item, so two people changing two numbers write two different keys
14
14
  - **A validator on the one thing they share.** Two changes can each fit while the merged plan busts the stall's capacity. No shape of state prevents that, so `validators/capacity` checks the merged result
15
15
  - **Every write awaited.** The game UI reports a refused write to the participant who made it, instead of showing a decision the game never received
16
- - **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready, and the facilitator watches and can undo
16
+ - **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready. The facilitator does not run the day; they hold the room at a day with a limit a validator enforces, watch, and can undo
17
+ - **Screens designed for where they are used.** Each screen leads with its one decision, works at phone size, uses the host's colours and an icon set rather than drawn icons, and asks 'are you sure?' beside the button rather than in a dialog. See [Designing screens](./designing-screens.md)
17
18
 
18
19
  [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) explains the first two in full.
19
20
 
@@ -35,13 +36,14 @@ See [Shaping games](./games.md).
35
36
 
36
37
  Each directory is one capability, a named slice of the game's state with a JSON Schema for its variables. There is no logic here.
37
38
 
38
- | Capability | Holds |
39
- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
40
- | `plan` | How many of each item to make today, keyed by item. The one capability participants write |
41
- | `weather` | Today's forecast and roughly how many people will want each item |
42
- | `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar |
43
- | `roles` | Which item each participant looks after, keyed by participant id |
44
- | `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
39
+ | Capability | Holds |
40
+ | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `plan` | How many of each item to make today, keyed by item. The one capability participants write |
42
+ | `weather` | Today's forecast and roughly how many people will want each item |
43
+ | `results` | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar |
44
+ | `roles` | Which item each participant looks after, keyed by participant id |
45
+ | `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
46
+ | `pacing` | `LastOpenDay`, the last day a stall may open. `shared` scope, written only by the facilitator's screen; the default opens all ten |
45
47
 
46
48
  See [Capabilities](./capabilities.md).
47
49
 
@@ -56,7 +58,7 @@ Each directory is one settings resource: read-only parameters, every one with a
56
58
  | `menu` | `Capacity` (120) and the `Menu`, each item's name, cost, and price | The engine, every surface, the hook, and the validator |
57
59
  | `engine` | `UsualDemand` for each item, `SunnyPull`, `RainyPull`, and `Variation`. Only the engine reads it, so no participant's browser ever holds the demand | The engine |
58
60
  | `ui` | `Step` and `CurrencySymbol` | The game UI |
59
- | `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI |
61
+ | `session` | `ShowJoinLinks` and `CurrencySymbol` | The session UI and the presentation |
60
62
 
61
63
  See [Settings](./settings.md).
62
64
 
@@ -84,39 +86,77 @@ See [Hooks](./hooks.md).
84
86
 
85
87
  A validator that sees every change a UI makes to the plan before it is applied. It reads the `menu` settings, and refuses a plan that asks for more than the stall's capacity, a negative or fractional count, or an item not on the menu. It never changes state; it only says no, with a message the game UI shows.
86
88
 
89
+ ### `validators/daylimit/`
90
+
91
+ A validator with a `RequestTick` gate and no `UpdateData`. It refuses a stall's request to open a day after `pacing.LastOpenDay`, so the facilitator's hold is enforced on the server rather than only by a disabled button. Only a participant's request reaches it; the facilitator's own actions are never held.
92
+
87
93
  See [Validators](./validators.md).
88
94
 
89
95
  ## User interfaces
90
96
 
91
- Each is a small React app built with Vite and MUI, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font), and `src/i18n.ts` (every string on the screen).
97
+ Each is a small React app built with Vite, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), and `src/i18n.ts` (every string on the screen). The three screens people use are built with MUI and add `src/theme.ts` (`createSurfaceTheme` over the host's theme, with Work Sans as the font); the presentation is built with the SDK's deck library instead.
98
+
99
+ ### `shared/`
100
+
101
+ Code every screen uses, imported by relative path. It is not a slot, so the build and the scaffold treat it as ordinary source.
102
+
103
+ - `Awning.tsx`: the scalloped edge under each top bar, in the host's primary colour. It is the game's one drawn motif; everything else comes from the icon set
104
+ - `HostLogo.tsx`: the host's logo, with the variant chosen for the coloured bar, or nothing when the host sends none
105
+ - `StallIcons.tsx`: the Material icon and tint for each menu item and each kind of weather
106
+ - `format.ts`: money from pence, and counts. `days.ts`: the length of the week, read from the manifest's `maxTicks`
92
107
 
93
108
  ### `ui/`
94
109
 
95
- The game UI: what each participant sees.
110
+ The game UI: what each participant sees. It leads with today's decision and keeps the button that opens the stall in a bar at the bottom of the layout, never floating over it.
96
111
 
97
- - `src/App.tsx`: the layout, the facilitator's notice, and the one place a refused write is reported
98
- - `src/TodayPanel.tsx` and `src/MakeRow.tsx`: the controls for today's plan, one row per item, with the participant's own item marked
99
- - `src/DayBar.tsx`: the **Open the stall** button, which calls `requestTick` to play the team's day
100
- - `src/YesterdayPanel.tsx` and `src/HistoryPanel.tsx`: how yesterday went, and every day so far. The history table asks the host for the earlier days with `getPastState` and adds today's from live context, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
101
- - `src/HostLogo.tsx`: the host's logo in the top bar, from `useBrandLogo()`, or nothing when the host sends none
102
- - `src/writes.ts`: one mutation reporter every write goes through
103
- - `src/menu.ts`, `src/format.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, money formatting, the card layout, and a light or dark switch
104
- - `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
112
+ - `src/App.tsx`: the layout and the state it is in: before day 1 (`src/FirstDay.tsx`), mid-week, looking back at a past day (`src/PastDay.tsx`), and the week over (`src/WeekOver.tsx`)
113
+ - `src/Header.tsx`: the stall's name, the item the participant looks after, and a timeline of the days, where a day already played opens that day
114
+ - `src/WeatherCard.tsx`, `src/TodayPanel.tsx` and `src/MakeRow.tsx`: today's forecast and the controls for the plan, one row per item, with the participant's own item marked
115
+ - `src/DayBar.tsx`: the bottom bar. **Open the stall for day N** calls `requestTick`; when the facilitator's limit holds the stall it is disabled and says so
116
+ - `src/YesterdayPanel.tsx`, `src/Lesson.tsx` and `src/DaysTable.tsx`: yesterday as one profit figure and one lesson, and every day so far. Earlier days come from the host with `usePastState`, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
117
+ - `src/Notices.tsx` and `src/writes.ts`: the facilitator's notice, and the one mutation reporter every write goes through, so a refusal reaches the person who made it
118
+ - `src/menu.ts`, `src/days.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, day helpers, the card layout, and a light or dark switch
119
+ - `ui.sdk.json`: reads every capability it shows, `pacing` included, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
105
120
 
106
121
  See [Building user interfaces](./ui.md).
107
122
 
108
123
  ### `session/`
109
124
 
110
- The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It shows what each stall is making and whether anyone has changed it today, links into any stall to observe or join it (`src/TeamDoor.tsx`), writes the shared `briefing`, and toggles the waiting room and the facilitator guide through the host. `ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
125
+ The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It follows what most facilitator screens need, and leaves out what only some games do:
126
+
127
+ - `src/SessionBar.tsx`: one line across the top. The day limit, which writes `pacing.LastOpenDay`, the waiting room, and the facilitator guide and slides when the host offers them
128
+ - `src/StallCard.tsx` and `src/status.ts`: a card per stall with the day it is on, who is connected, what is in the jar, and links to observe it or copy its join link
129
+ - `src/ManagePanel.tsx` and `src/SidePanel.tsx`: a panel beside the cards, with no backdrop, to rename a stall, move a person, or undo a day, confirmed in place
130
+ - `src/Results.tsx`: the room's averages and range above a sortable table, any day played so far, and full screen for the projector
131
+ - `src/JoinCodes.tsx`: each stall's join link in large type, one stall at a time, for the room to read
132
+ - `src/SessionPanels.tsx`: the notice to the room (the shared `briefing`) and starting the session again
133
+
134
+ `ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
111
135
 
112
136
  See [Building session UIs](./session.md).
113
137
 
114
138
  ### `waiting_room/`
115
139
 
116
- The screen participants see while the session is held. It tells a held start ('Nearly opening time') from a pause part-way through, shows who is on the team, and lets the team name its stall.
140
+ The screen participants see while the session is held. It tells a held start ('Your stall opens soon') from a pause part-way through, shows who is on the team, lets the team name its stall, and copies the join link for anyone else joining.
117
141
 
118
142
  See [Building waiting room UIs](./waiting-room.md).
119
143
 
144
+ ### `presentation/`
145
+
146
+ The facilitator's slide deck, which they project for the room. It is read-only, and it renders with or without a session, so a facilitator can rehearse it or export it before the day.
147
+
148
+ - `src/Slides.tsx`: a title slide, one slide a day with the forecast and how the room did the day before, and a results slide for the room. The projector shows the room, never a stall by name: each stall's figures are in the speaker notes
149
+ - `src/stalls.ts`: the room's figures, kept apart from the slides so `src/stalls.test.ts` can test them without a deck. The stalls run their own days, so a day's figures count only the stalls that have played it, read through `usePastState`
150
+ - `src/Band.tsx` and `src/WeatherIcon.tsx`: the awning and the weather icon in the deck's own colours, since a deck has no MUI theme
151
+ - `src/App.tsx`: the `Deck`, with the host's theme as its colours, and opening on the day the room has reached
152
+ - `presentation.sdk.json`: reads `plan`, `weather` and `results`, and the `session` settings for the currency symbol
153
+
154
+ The dev server shows it at `/presentation`, and at `/presentation?preview` with no session.
155
+
156
+ See [Building presentations](./presentation.md).
157
+
158
+ The starter has no `setup/` or `scenario_editor/`, to keep it a quick first read. `examples/factory` in the SDK repository has both, and [Building setup screens](./setup.md) and [Building scenario editors](./scenario-editor.md) cover them.
159
+
120
160
  ## Content
121
161
 
122
162
  ### `scenarios/`
@@ -2,6 +2,8 @@
2
2
 
3
3
  Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
4
4
 
5
+ **Keywords:** testing, unit tests, UI tests, Vitest, React Testing Library, renderUserInterface, createMock, test Run, test Init, Playwright, jsdom, test hooks
6
+
5
7
  ## Testing engine logic
6
8
 
7
9
  ### Starting from the generated defaults
@@ -4,6 +4,8 @@ A tick controller makes ticks happen on their own, on a schedule your logic deci
4
4
 
5
5
  This guide explains the model, then is the reference for writing one.
6
6
 
7
+ **Keywords:** tick controller, timer, automatic ticks, interval, schedule, timed rounds, nextTickAt, game completion, complete, enabled, pause, extend a tick, cron
8
+
7
9
  ## The model
8
10
 
9
11
  By default, ticks are manual: a participant or facilitator presses a control, or a command is sent, to advance the game. That suits a game that moves one decision at a time. Some games need time to move on its own, or at a pace that depends on what is happening in the simulation. Some also need to end when a goal is met rather than after a fixed number of ticks.
@@ -410,7 +412,7 @@ pnpm run sdk timer extend 120 # two more minutes (the CLI takes second
410
412
  pnpm run sdk timer resume --team 2 # one team, in an independent game
411
413
  ```
412
414
 
413
- The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui.md#displaying-the-tick-timer) in the user interfaces guide.
415
+ The current schedule, a [`TimerState`](../api/sdk-ui.md#timerstate) with every duration and timestamp in milliseconds, is pushed to every game UI. UIs subscribe with `useUserInterfaceTimer` and render their own countdown or progress bar. See [Displaying the tick timer](./ui-ticks.md#displaying-the-tick-timer) in the user interfaces guide.
414
416
 
415
417
  ## Testing without waiting
416
418
 
@@ -4,6 +4,8 @@ The SDK generates TypeScript types from your schemas, so a misspelt variable fai
4
4
 
5
5
  This guide covers the rules that keep that guarantee, and the shortcuts that quietly break it.
6
6
 
7
+ **Keywords:** type safety, TypeScript, generated types, types.ts, sdk generate, any, type casts, JSON Schema types, schema constraints, strict types
8
+
7
9
  ## Core principle
8
10
 
9
11
  The Serious Gaming SDK uses TypeScript and JSON Schema to provide **end-to-end type safety**. When you define a capability's `variablesSchema` or a settings resource's `settingsSchema`, the SDK generates precise TypeScript types. Shortcuts and workarounds (using `any`, string-based JSON, etc.) break this guarantee and lead to runtime errors.
@@ -0,0 +1,328 @@
1
+ # Files and LLMs in user interfaces
2
+
3
+ How a game UI links to static assets, uploads and shows files, reads an asset's contents, and reaches an LLM through an endpoint to build a chat.
4
+
5
+ It is part of [Building user interfaces](./ui.md), which covers creating the surface and reading and writing context.
6
+
7
+ **Keywords:** static assets, assetUrl, file upload, uploadFile, blob, read asset, LLM, generateText, chat UI, callEndpoint, EndpointError, markdown
8
+
9
+ ## Linking to static assets
10
+
11
+ User interfaces run inside an iframe served at a nested path (e.g.,
12
+ `/user-interfaces/ui/`). Because of this, **absolute URLs
13
+ like `/my-file.pdf` will not resolve to your assets**: they escape the iframe
14
+ and hit the shell app's origin instead.
15
+
16
+ Always use **relative paths** when linking to files in your UI's directory:
17
+
18
+ ```typescript
19
+ // Wrong: escapes the iframe, loads the shell app's index.html
20
+ window.open('/Briefing.pdf');
21
+
22
+ // Correct: resolves relative to your UI's index.html
23
+ window.open('./Briefing.pdf');
24
+ ```
25
+
26
+ This applies to any reference from your UI code to static files: `<a href>`,
27
+ `<img src>`, `<embed src>`, `window.open()`, `fetch()`, etc. The same rule
28
+ holds in both the dev server and production builds.
29
+
30
+ In production your UI also runs under a strict content security policy: every
31
+ asset must be bundled into your build (no external CDNs, no Google Fonts, no
32
+ blob-URL workers), and outbound network calls go through an engine, an endpoint,
33
+ or a host capability. The dev server mirrors this policy, so violations
34
+ surface locally. See [Production security constraints](./production-constraints.md)
35
+ for the full policy and the do's and don'ts.
36
+
37
+ **Where to put static files:** Place them in your UI's directory alongside
38
+ `index.html` (or in a subdirectory). For the default scaffold structure, that
39
+ means inside `ui/`:
40
+
41
+ ```
42
+ ui/
43
+ ├── index.html
44
+ ├── Briefing.pdf ← ./Briefing.pdf
45
+ ├── public/
46
+ │ └── logo.png ← ./public/logo.png
47
+ └── src/
48
+ └── App.tsx
49
+ ```
50
+
51
+ ## File uploads
52
+
53
+ User interfaces can upload files (PDFs, images, CSV, etc.) using the `uploadBlob` callback and display them using `getAssetUrl`. Uploaded files and scenario-bundled files share a single asset reference scheme (see [Asset references](../guides/file-handling.md#asset-references) for the full picture).
54
+
55
+ ### Uploading a file
56
+
57
+ ```typescript
58
+ import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
59
+ import type { Context, Settings } from '../types';
60
+
61
+ function DocumentUpload() {
62
+ const callbacks = useUserInterfaceCallbacks();
63
+ const { setData } = useUserInterfaceData<Context, Settings>();
64
+ const [isUploading, setIsUploading] = useState(false);
65
+
66
+ const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
67
+ const file = e.target.files?.[0];
68
+ if (!file || !callbacks.uploadBlob) return;
69
+
70
+ try {
71
+ setIsUploading(true);
72
+ const reference = await callbacks.uploadBlob(file);
73
+ setData({ 'upload': { DocumentRef: reference } });
74
+ } finally {
75
+ setIsUploading(false);
76
+ e.target.value = '';
77
+ }
78
+ };
79
+
80
+ return (
81
+ <input type="file" accept=".pdf,.csv,.txt" onChange={handleUpload} disabled={isUploading} />
82
+ );
83
+ }
84
+ ```
85
+
86
+ The capability holding the reference must be listed in the UI's `writes`. The maximum file size is **20 MB**.
87
+
88
+ ### Displaying a file
89
+
90
+ Use `useAssetUrl` to get a URL suitable for `<img>`, `<embed>`, or `<video>`. It resolves uploaded blobs and scenario-bundled assets alike, and returns `undefined` for an absent reference, so there is nothing to guard:
91
+
92
+ ```typescript
93
+ import { useAssetUrl } from '@seriousgaming/sdk/ui';
94
+
95
+ function DocumentViewer() {
96
+ const { data } = useUserInterfaceData<Context, Settings>();
97
+ const src = useAssetUrl(data.upload?.DocumentRef);
98
+ if (!src) return null;
99
+
100
+ return (
101
+ <embed
102
+ src={src}
103
+ type="application/pdf"
104
+ style={{ width: '100%', height: '500px', border: 'none' }}
105
+ />
106
+ );
107
+ }
108
+ ```
109
+
110
+ The capability holding the reference must be listed in the UI's `reads`. `useAssetUrl` works on every surface; the `getAssetUrl` callback does the same job outside a component.
111
+
112
+ For the full reference, including engine access via `readAsset`, blob scopes, CLI upload, and supported file types, see [File handling](./file-handling.md).
113
+
114
+ ## Reading an asset's contents
115
+
116
+ To render what is in a file rather than link to it, such as a briefing, a JSON table of scenario prose, or a CSV, use `useAsset`. It fetches the asset, reads the body `as` `'json'`, `'text'` or `'blob'`, and returns `{ data, error, loading }`:
117
+
118
+ ```tsx
119
+ import { useAsset } from '@seriousgaming/sdk/ui';
120
+
121
+ function Briefing() {
122
+ const { data, error, loading } = useAsset('shared:briefing/briefing.md', { as: 'text' });
123
+ if (loading) return <Spinner />;
124
+ if (error) return <Alert>{error.message}</Alert>;
125
+ return <Markdown>{data}</Markdown>;
126
+ }
127
+ ```
128
+
129
+ It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md` (a locale with a script, such as `zh-Hant-TW`, tries `zh-Hant` before `zh`):
130
+
131
+ ```
132
+ shared-assets/
133
+ briefing/
134
+ briefing.md ← the untranslated text, and the fallback
135
+ fr/briefing.md
136
+ ar/briefing.md
137
+ ```
138
+
139
+ Pass `locale` to look in a different one, or `locale: false` to read the reference alone. A `blob:` reference is always read as given. The hook refetches when the reference or the locale changes, so it follows a mid-session language switch, and an answer to a reference that has since changed is discarded. For JSON, give the type: `useAsset<Briefing>(reference, { as: 'json' })`.
140
+
141
+ ## Using LLMs in user interfaces
142
+
143
+ User interfaces cannot call `generateText` (or `extractText` or `generateSpeech`) directly. A UI reaches these services through an [endpoint](./endpoints.md): the endpoint wraps the callback and runs server-side, and the UI invokes it through `callbacks.endpoints['<endpoint-id>']`. This keeps credential-holding calls off the untrusted iframe. To create one, follow [Create an endpoint](../recipes/create-endpoint.md). See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) and the [LLM integration guide](llm-integration.md) for the full pattern.
144
+
145
+ ### The endpoint
146
+
147
+ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
148
+
149
+ ```typescript
150
+ // endpoints/chat/logic/logic.ts
151
+ import { getText } from '@seriousgaming/sdk';
152
+ import type { Handler } from '../types';
153
+
154
+ export const Handle: Handler = async ({ request, callbacks }) => {
155
+ const response = await callbacks.generateText({
156
+ messages: request.messages,
157
+ systemPrompt:
158
+ request.systemPrompt ?? 'You are a helpful business advisor. Provide concise guidance.',
159
+ });
160
+ return { reply: getText(response) };
161
+ };
162
+ ```
163
+
164
+ The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no `uses` field, and the build refuses one.
165
+
166
+ ```json
167
+ {
168
+ "definition": {
169
+ "endpoints": ["chat"]
170
+ },
171
+ "rootDirectory": ".",
172
+ "ui": { "entrypoint": "index.html" }
173
+ }
174
+ ```
175
+
176
+ ### Calling the endpoint from a component
177
+
178
+ Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
179
+
180
+ ```tsx
181
+ import { useState } from 'react';
182
+ import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
183
+ import type { Context, Settings } from '../types';
184
+ import type { Callbacks } from '../types';
185
+
186
+ function ChatAssistant() {
187
+ const { data, setData } = useUserInterfaceData<Context, Settings>();
188
+ const callbacks = useUserInterfaceCallbacks() as Callbacks;
189
+ const [isLoading, setIsLoading] = useState(false);
190
+
191
+ const messages = data.chathistory.Messages;
192
+
193
+ const handleSendMessage = async (userMessage: string) => {
194
+ if (!userMessage.trim()) return;
195
+ setIsLoading(true);
196
+ try {
197
+ const newMessages = [...messages, { role: 'user' as const, content: userMessage }];
198
+ const { reply } = await callbacks.endpoints['chat']({
199
+ messages: newMessages,
200
+ });
201
+ await setData({
202
+ chathistory: {
203
+ Messages: [...newMessages, { role: 'assistant' as const, content: reply }],
204
+ },
205
+ });
206
+ } finally {
207
+ setIsLoading(false);
208
+ }
209
+ };
210
+
211
+ return (
212
+ <div>
213
+ {messages.map((msg, idx) => (
214
+ <div key={idx} className={msg.role}>
215
+ {msg.content}
216
+ </div>
217
+ ))}
218
+ <input
219
+ type="text"
220
+ placeholder="Type your message..."
221
+ onKeyPress={(e) => {
222
+ if (e.key === 'Enter' && !isLoading) {
223
+ handleSendMessage(e.currentTarget.value);
224
+ e.currentTarget.value = '';
225
+ }
226
+ }}
227
+ disabled={isLoading}
228
+ />
229
+ {isLoading && <p>Loading...</p>}
230
+ </div>
231
+ );
232
+ }
233
+ ```
234
+
235
+ ### Localising prompts
236
+
237
+ Translate the system prompt in the UI with i18n and pass it to the endpoint in the request. The endpoint forwards it to `generateText`:
238
+
239
+ ```tsx
240
+ import { useTranslation } from 'react-i18next';
241
+
242
+ const { t } = useTranslation();
243
+ const { reply } = await callbacks.endpoints['chat']({
244
+ messages: newMessages,
245
+ systemPrompt: t('chatSystemPrompt'),
246
+ });
247
+ ```
248
+
249
+ Update `src/i18n.ts`:
250
+
251
+ ```typescript
252
+ const resources = {
253
+ en: {
254
+ translation: {
255
+ chatSystemPrompt: 'You are a helpful assistant for a business game.',
256
+ askForAdvice: 'Ask for advice...',
257
+ },
258
+ },
259
+ es: {
260
+ translation: {
261
+ chatSystemPrompt: 'Eres un asistente útil para un juego de simulación empresarial.',
262
+ askForAdvice: 'Pedir consejo...',
263
+ },
264
+ },
265
+ };
266
+ ```
267
+
268
+ ### Markdown rendering in chat
269
+
270
+ Render markdown replies with `react-markdown`:
271
+
272
+ ```typescript
273
+ import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
274
+ import ReactMarkdown from 'react-markdown';
275
+ import { Box, styled } from '@mui/material';
276
+
277
+ const StyledMarkdown = styled(Box)(({ theme }) => ({
278
+ '& code': {
279
+ backgroundColor: theme.palette.action.hover,
280
+ padding: '2px 6px',
281
+ borderRadius: '4px',
282
+ fontFamily: 'monospace'
283
+ },
284
+ '& pre': {
285
+ backgroundColor: theme.palette.action.hover,
286
+ padding: theme.spacing(1),
287
+ borderRadius: '4px',
288
+ overflow: 'auto'
289
+ }
290
+ }));
291
+
292
+ function ChatMessage({ content }: { content: string }) {
293
+ return (
294
+ <StyledMarkdown>
295
+ <ReactMarkdown>{content}</ReactMarkdown>
296
+ </StyledMarkdown>
297
+ );
298
+ }
299
+ ```
300
+
301
+ ### Error handling
302
+
303
+ A failed endpoint call rejects with an `EndpointError`, the endpoint counterpart of `MutationError`. `error.kind` (shorthand for `error.outcome.kind`) says why: the [`MutationOutcome` kinds](./ui-ticks.md#awaiting-state-changes), plus `invalid-request` (the request failed `requestSchema` and the handler never ran), `handler-error` (the handler threw or overran its time limit) and `invalid-response` (it returned something its declaration forbids). `error.applied` lists the endpoint's effects that had already landed, and `error.failedStep` names the one that failed, so you can tell a call that changed nothing from one that saved its write and then failed on an action:
304
+
305
+ ```typescript
306
+ import { EndpointError } from '@seriousgaming/sdk/ui';
307
+
308
+ try {
309
+ const { reply } = await callbacks.endpoints['chat']({ messages });
310
+ setResponse(reply);
311
+ } catch (error) {
312
+ if (error instanceof EndpointError && error.kind === 'handler-error') {
313
+ setError(t('chatUnavailable'));
314
+ } else {
315
+ setError(error instanceof Error ? error.message : String(error));
316
+ }
317
+ }
318
+ ```
319
+
320
+ An empty `applied` means nothing changed. As with a mutation, never retry an endpoint call automatically: a `conflict` means a person may try again. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md#steps) for every kind.
321
+
322
+ ### Putting a chat UI together
323
+
324
+ The sections above are the parts of a complete chat surface. Beyond them, a chat that feels finished usually adds:
325
+
326
+ - Message history kept in the component's state, or in a capability when it must survive a reload, and sent with each call
327
+ - A loading state while the call is in flight, with the send button disabled
328
+ - Scrolling to the latest message when one arrives