@seriousgaming/sdk-tools 1.0.0-alpha.4 → 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 +64 -6
  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 +28 -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
@@ -1,16 +1,10 @@
1
1
  # Building session UIs
2
2
 
3
- Build facilitator-only UIs that operate across all teams in a session at once: session-wide dashboards, cross-team comparisons, and global game controls.
3
+ The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
4
4
 
5
- **Keywords:** manage session, session UI, facilitator UI, session-level, cross-team, multi-team dashboard, facilitator controls, session dashboard, all teams, independent mode, shared-state mode
6
-
7
- ## What you'll learn
5
+ It is facilitator-only and works across all teams at once, for session-wide dashboards, cross-team comparisons, and global game controls.
8
6
 
9
- - How to create a session UI
10
- - How to read and write per-team state from a single session-level view
11
- - How to target game flow controls at individual teams or all teams at once
12
- - How to handle both independent and shared-state interaction modes
13
- - How to configure the session UI per game and per scenario
7
+ **Keywords:** manage session, session UI, facilitator UI, session-level, cross-team, multi-team dashboard, facilitator controls, session dashboard, all teams, independent mode, shared-state mode
14
8
 
15
9
  ## What are session UIs?
16
10
 
@@ -29,6 +23,8 @@ The session UI is the facilitator's whole-session screen. The host renders it fu
29
23
 
30
24
  Capability is inferred, not declared: shipping a session UI claims the whole canvas. There is no partial takeover and no per-capability negotiation.
31
25
 
26
+ Put the numbers that matter side by side: a facilitator who can spot a struggling team early can prompt reflection between rounds rather than after the game.
27
+
32
28
  ## Creating a session UI
33
29
 
34
30
  The starter game already fills this slot, and `new` refuses a filled one with `RESOURCE_EXISTS`. In a package made by `new package`, change it with `update session` instead, or start from `new package --empty`.
@@ -197,6 +193,8 @@ function App() {
197
193
  export default App;
198
194
  ```
199
195
 
196
+ `useSessionUserInterfaceData` also returns `scenarioName`: the name of the scenario the session is running, in the session's language, or `null` with none. It tells a facilitator with several copies of a scenario which one this session is on. Show it, never branch on it (see [Showing the scenario](./engine.md#showing-the-scenario)).
197
+
200
198
  ### Writing per-team overrides
201
199
 
202
200
  The session-level `setData` requires a `teamId` parameter to specify which team to update, since the session UI is not scoped to one team:
@@ -457,16 +455,16 @@ function OverlayControls() {
457
455
  }
458
456
  ```
459
457
 
460
- **Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change mid-session when a scenario switch changes which guides the game declares.
458
+ **Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change when the game is reloaded, for example when a guide is added or removed.
461
459
 
462
460
  The second argument narrows the overlay:
463
461
 
464
- | Overlay | Second argument | Omitted means |
465
- | --------------------- | ------------------------------------- | ------------------------------- |
466
- | `'facilitator-guide'` | A guide identifier your game declares | The game's first declared guide |
467
- | `'print-sheets'` | A team id | Every team |
462
+ | Overlay | Second argument | Omitted means |
463
+ | --------------------- | ------------------------------------------------ | ---------------- |
464
+ | `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
465
+ | `'print-sheets'` | A team id | Every team |
468
466
 
469
- It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for an argument that does not resolve.
467
+ It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
470
468
 
471
469
  ### Undoing and resetting
472
470
 
@@ -492,8 +490,10 @@ function GameControls() {
492
490
  }
493
491
  ```
494
492
 
495
- - **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`.
496
- - **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved.
493
+ - **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`
494
+ - **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved
495
+
496
+ Undo lets a team try a round again without penalty, which supports psychological safety: people experiment more freely when a mistake can be taken back.
497
497
 
498
498
  ### Opening and closing the waiting room
499
499
 
@@ -703,30 +703,24 @@ Read colours from the theme hook below rather than hard-coding them, so your ses
703
703
 
704
704
  ## Using the theme
705
705
 
706
- Edit `src/theme.ts` to use the session theme hook:
706
+ Edit `src/theme.ts` to use the session theme hook, and turn it into MUI theme options with `createSurfaceTheme`:
707
707
 
708
708
  ```typescript
709
- import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
709
+ import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
710
710
  import { createTheme } from '@mui/material/styles';
711
711
  import { useMemo } from 'react';
712
712
 
713
713
  export function useAppTheme() {
714
714
  const sdkTheme = useSessionUserInterfaceTheme();
715
715
  return useMemo(
716
- () =>
717
- createTheme({
718
- palette: {
719
- mode: sdkTheme.mode,
720
- primary: {
721
- main: (sdkTheme.mode === 'light' ? sdkTheme.light : sdkTheme.dark).primary,
722
- },
723
- },
724
- }),
716
+ () => createTheme(createSurfaceTheme(sdkTheme, { fonts: { body: 'Work Sans Variable' } })),
725
717
  [sdkTheme]
726
718
  );
727
719
  }
728
720
  ```
729
721
 
722
+ The host's logo, name and fonts reach a session UI exactly as they reach a game UI: see [Theming and branding](./theming-and-branding.md).
723
+
730
724
  ## Dev server behaviour
731
725
 
732
726
  When you run `pnpm run sdk dev` for a game with session UIs:
@@ -966,10 +960,10 @@ The session UI follows the same file structure conventions as other UI resource
966
960
 
967
961
  ## See also
968
962
 
969
- - [Multi-team games](./multi-team-games.md) - Independent and shared-state interaction modes
970
- - [Building user interfaces](./ui.md) - Building participant-facing game UIs
971
- - [Building a setup screen](./setup.md) - The form at session creation
972
- - [Building a scenario editor](./scenario-editor.md) - Authoring lasting scenarios
973
- - [Tick controllers](./tick-controller.md) - Automatic tick timing
974
- - [Testing](./testing.md) - Writing UI tests
975
- - [CLI reference](../cli-reference.md) - `new`, `update`, and `delete session` commands
963
+ - [Multi-team games](./multi-team-games.md): independent and shared-state interaction modes
964
+ - [Building user interfaces](./ui.md): building participant-facing game UIs
965
+ - [Building a setup screen](./setup.md): the form at session creation
966
+ - [Building a scenario editor](./scenario-editor.md): authoring lasting scenarios
967
+ - [Tick controllers](./tick-controller.md): automatic tick timing
968
+ - [Testing](./testing.md): writing UI tests
969
+ - [CLI reference](../cli-reference.md): `new`, `update`, and `delete session` commands
@@ -1,6 +1,8 @@
1
1
  # Settings
2
2
 
3
- Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key. This guide covers declaring them, reading them from logic and surfaces, overriding them per scenario and per session, and setting them from the CLI.
3
+ Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
4
+
5
+ This guide covers declaring them, reading them from logic and surfaces, overriding them per scenario and per session, and setting them from the CLI.
4
6
 
5
7
  Not to be confused with [global settings](./global-settings.md), the file in your home directory that holds API keys for every project.
6
8
 
@@ -64,7 +66,7 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
64
66
 
65
67
  - Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
66
68
  - Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
67
- - A top-level `required` is refused, because every property always has a value. For a value that may be absent, use `"type": ["string", "null"]` with `"default": null`
69
+ - A top-level `required` is refused, because every property always has a value. For a value with no sensible default, such as one every scenario must supply, default to an empty value (`""`, `[]` or `{}`) and have a validator's `Scenario` gate refuse a scenario that leaves it empty (see [Gating scenarios](./validators.md#gating-scenarios)). Widen a type to allow `null` only when your game genuinely handles a missing value, since every reader then has to
68
70
 
69
71
  A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
70
72
 
@@ -76,6 +78,9 @@ A settings schema is read by more than the build. A hosted runtime's generic set
76
78
  - Its units, in the description or title ('in pounds', 'per tick', 'as a fraction of revenue')
77
79
  - A range, with `minimum` and `maximum`, wherever one exists
78
80
  - An `enum` where the choices are closed
81
+ - A `blob` declaration on every value that holds a file (see [Settings that hold a file](#settings-that-hold-a-file))
82
+
83
+ **What an agent can change is what your settings hold.** An agent writing a scenario changes settings and nothing else. Content you want written per scenario, such as a briefing's text, a client's logo or a product list, belongs in a settings resource, not in code or a package file, or nothing short of a new release can change it. When a scenario needs an answer no schema can give, such as what a round would come to at a price, offer a [scenario-scoped endpoint](./endpoints.md#scenario-scoped-endpoints) an agent can call on its draft.
79
84
 
80
85
  A `title` on a value is safe to write: the generated `types.ts` ignores it, so any wording works, 'Settings' and 'Context' included. Only a `title` on an object names a type there.
81
86
 
@@ -111,6 +116,27 @@ Some values are part of the game's design rather than something to tune: a const
111
116
  - **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
112
117
  - **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
113
118
 
119
+ ### Settings that hold a file
120
+
121
+ A setting can hold a file, such as a client's logo or a briefing document. Mark the string property with `blob`, the keyword an endpoint request uses for a file, saying what file it takes:
122
+
123
+ ```json
124
+ "BrandingLogo": {
125
+ "type": "string",
126
+ "title": "Branding logo",
127
+ "description": "The workshop's logo, shown beside the Decisions heading. Empty shows none",
128
+ "default": "",
129
+ "blob": { "accept": ["image/svg+xml", "image/png", "image/jpeg"], "maxBytes": 524288 }
130
+ }
131
+ ```
132
+
133
+ `accept` lists media types, `image/*` style wildcards included, and takes any type when absent; `maxBytes` bounds the file. The value is an asset reference, `asset:`, `shared:` or `blob:` (see [Asset references](./file-handling.md#asset-references)), or empty for no file. Read it with `getAssetUrl` or `readAsset` as any reference.
134
+
135
+ - **The default is no file, or a shared one.** A default resolves with no scenario active, so it must be empty or a `shared:` reference
136
+ - **The build checks your files.** Every file a package scenario or a default names must be shipped, within `maxBytes`, and of a type `accept` lists, judged from its extension. A `blob:` reference in a package scenario fails the build: it is an upload, which no package can carry
137
+ - **Every write is checked against it.** A setup screen, the scenario editor or an agent sets a file by uploading it first and writing the `blob:` reference it gets back. A reference to a file nobody uploaded, or one too large or of the wrong type, is refused as `denied`, naming the setting. So is anything that is not a reference, a `data:` URI or a URL included
138
+ - **It tells an agent what to upload.** A schema alone says only that the value is a string; `blob` says it is a PNG of up to 512 KB
139
+
114
140
  ### How to divide settings
115
141
 
116
142
  Split settings by who reads them rather than keeping one per resource. A package may hold one `engine` settings resource read only by the engine, or several named by topic (`pricing`, `documents`, `answers`) that several resources share. The starter game does both: its `menu` settings, the prices and the stall's capacity, are read by the engine, every surface, a hook and a validator, while each item's usual demand sits in an `engine` resource only the engine reads. Several resources may declare the same settings resource, and each receives the same values, so a surface never needs a copy of a value the engine already has.
@@ -1,13 +1,8 @@
1
1
  # Building a setup screen
2
2
 
3
- The `setup` slot holds the small form a facilitator fills in when they create a session. What it writes applies to that session only. This guide covers creating one, building its form, and how it behaves in the dev server.
3
+ The `setup` slot holds the small form a facilitator fills in when they create a session. What it writes applies to that session only.
4
4
 
5
- ## What you'll learn
6
-
7
- - What the setup slot is for, and how it differs from the scenario editor
8
- - How to create a setup screen and choose the settings it edits
9
- - How to read and write settings with `useSettingsEditor`
10
- - How to start play from your own control with `requestPlay`
5
+ This guide covers creating one, building its form, and how it behaves in the dev server.
11
6
 
12
7
  ## What setup is
13
8
 
@@ -1,20 +1,11 @@
1
1
  # Speech generation guide
2
2
 
3
+ Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
4
+
3
5
  The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. Engines, hooks, tick controllers, and endpoints can synthesise audio without knowing which provider executes the call. User interfaces reach it through an endpoint. The audio is persisted as a blob, so the same artefact can be played from a UI or analysed in an engine.
4
6
 
5
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.
6
8
 
7
- ## Table of contents
8
-
9
- - [Overview](#overview)
10
- - [Configuration](#configuration)
11
- - [Voice presets](#voice-presets)
12
- - [Tiers](#tiers)
13
- - [Using generateSpeech in the engine, hooks, and tick controllers](#using-generatespeech-in-the-engine-hooks-and-tick-controllers)
14
- - [Using generateSpeech in user interfaces](#using-generatespeech-in-user-interfaces)
15
- - [Request and response shape](#request-and-response-shape)
16
- - [Limitations](#limitations)
17
-
18
9
  ## Overview
19
10
 
20
11
  `generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
@@ -125,7 +116,7 @@ For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5
125
116
  }
126
117
  ```
127
118
 
128
- 2. Run `pnpm run sdk generate` so the per-resource `types.ts` narrows the `Callbacks` alias.
119
+ 2. Run `pnpm run sdk generate` so the per-resource `types.ts` narrows the `Callbacks` alias
129
120
  3. Call the callback from `Init` or `Run`:
130
121
 
131
122
  ```typescript
@@ -226,8 +217,8 @@ v1 is intentionally minimal so the API stays stable as providers come and go. Th
226
217
 
227
218
  ## Related
228
219
 
229
- - [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses) - the safety boundary mental model
230
- - [Declare API uses](../recipes/declare-api-uses.md) - step-by-step declaration recipe
231
- - [LLM integration](llm-integration.md) - the companion `generateText` callback
232
- - [File handling](file-handling.md) - the unified `asset:` / `blob:` scheme for files
233
- - [Environment variables](../environment-variables.md) - full env-var reference
220
+ - [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses): the safety boundary mental model
221
+ - [Declare API uses](../recipes/declare-api-uses.md): step-by-step declaration recipe
222
+ - [LLM integration](llm-integration.md): the companion `generateText` callback
223
+ - [File handling](file-handling.md): the unified `asset:` / `blob:` scheme for files
224
+ - [Environment variables](../environment-variables.md): full env-var reference
@@ -88,7 +88,7 @@ See [Validators](./validators.md).
88
88
 
89
89
  ## User interfaces
90
90
 
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` (typography over the host's palette), and `src/i18n.ts` (every string on the screen).
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).
92
92
 
93
93
  ### `ui/`
94
94
 
@@ -98,6 +98,7 @@ The game UI: what each participant sees.
98
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
99
  - `src/DayBar.tsx`: the **Open the stall** button, which calls `requestTick` to play the team's day
100
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
101
102
  - `src/writes.ts`: one mutation reporter every write goes through
102
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
103
104
  - `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
@@ -1,12 +1,6 @@
1
1
  # Testing
2
2
 
3
- This guide shows you how to write and run tests for your engine and user interfaces.
4
-
5
- ## What you'll learn
6
-
7
- - How to write unit tests for the engine
8
- - How to test React user interface components
9
- - How to run tests locally
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.
10
4
 
11
5
  ## Testing engine logic
12
6
 
@@ -155,13 +149,14 @@ For `InitAggregate`, pass `meta: { tick: 0 }`. A shared capability belongs in `r
155
149
 
156
150
  Each kind of logic has its own builder, typed from the function it is passed to:
157
151
 
158
- | Builder | For | Fills, beyond `meta`, `participants` and `callbacks` |
159
- | -------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
160
- | `logicArgs.hook` | A hook's `Run` | The roster is the payload's `participant`. The signal defaults to `participantJoin`; name `signal: 'participantMove'` for a move, whose payload it then requires |
161
- | `logicArgs.endpoint` | An endpoint's `Handle` or `Plan` | `team` (`team-1`), `session` (independent, no ticks completed) and `caller`: the team's first participant through `ui`, or pass `caller: { role: 'facilitator' }` (from `session`) or `caller: { role: 'author' }` (from `scenario_editor`, with no `sessionId`) |
162
- | `logicArgs.validator` | A validator's `UpdateData` | `actor`: the roster's first participant |
163
- | `logicArgs.requestTick` | A validator's `RequestTick` | `actor`, and `requestedTick: 1` |
164
- | `logicArgs.tickController` | `GetTickController` | `teams`: the one team `meta` names, with `context`. `waitingRoomOpen: false` |
152
+ | Builder | For | Fills, beyond `meta`, `participants` and `callbacks` |
153
+ | ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
+ | `logicArgs.hook` | A hook's `Run` | The roster is the payload's `participant`. The signal defaults to `participantJoin`; name `signal: 'participantMove'` for a move, whose payload it then requires |
155
+ | `logicArgs.endpoint` | An endpoint's `Handle` or `Plan` | `team` (`team-1`), `session` (independent, no ticks completed) and `caller`: the team's first participant through `ui`, or pass `caller: { role: 'facilitator' }` (from `session`) |
156
+ | `logicArgs.scenarioEndpoint` | A scenario-scoped endpoint's `Handle` | `caller`: an author through `scenario_editor`. It takes `request` and `settings` (the draft's values) and builds no `context`, `participants` or `session` |
157
+ | `logicArgs.validator` | A validator's `UpdateData` | `actor`: the roster's first participant |
158
+ | `logicArgs.requestTick` | A validator's `RequestTick` | `actor`, and `requestedTick: 1` |
159
+ | `logicArgs.tickController` | `GetTickController` | `teams`: the one team `meta` names, with `context`. `waitingRoomOpen: false` |
165
160
 
166
161
  ```typescript
167
162
  const result = await Handle(
@@ -184,6 +179,8 @@ await Run(
184
179
  );
185
180
  ```
186
181
 
182
+ To act on a team other than `team-1`, pass `team: createMockTeam({ index: 1 })`, and for a hook's or a validator's participant, `createMockParticipant({ name: 'Ada' })`, both imported from `@seriousgaming/sdk/testing` with `logicArgs`. Build teams and participants with `createMockTeam`, `createMockParticipant` and their plurals rather than by hand: a field later added to either then reaches your test with a value, rather than failing to compile in every file that spelt one out.
183
+
187
184
  ### Testing with LLM callbacks
188
185
 
189
186
  The callbacks `logicArgs` fills are offline stubs, the same a test session uses; pass one in `callbacks` to choose its answer. See [Service callbacks are stubbed](./engine-testing.md#service-callbacks-are-stubbed) for what each stub answers and how to override it.
@@ -262,18 +259,20 @@ describe('Dashboard', () => {
262
259
 
263
260
  Default values when you omit an option:
264
261
 
265
- | Option | Default |
266
- | ---------------- | --------------------------------------------------------------------------------- |
267
- | `data` | `{}` |
268
- | `settings` | `{}` |
269
- | `completedTicks` | `0` |
270
- | `setData` | no-op |
271
- | `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette) |
272
- | `locale` | `{ locale: 'en' }` |
273
- | `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
274
- | `participants` | `[]` (`createMockParticipants(n)` builds a roster) |
275
- | `timer` | Disabled (no auto-tick) |
276
- | `callbacks` | All present as no-ops |
262
+ | Option | Default |
263
+ | ---------------- | ------------------------------------------------------------------------------------- |
264
+ | `data` | `{}` |
265
+ | `settings` | `{}` |
266
+ | `completedTicks` | `0` |
267
+ | `setData` | no-op |
268
+ | `theme` | `createMockUserInterfaceTheme()` (light mode, MUI palette) |
269
+ | `locale` | `{ locale: 'en' }` |
270
+ | `participant` | `{ id: '1', name: 'Participant 1', index: 0, connected: true, teamId: 'team-1' }` |
271
+ | `participants` | `[]` (`createMockParticipants(n)` builds a roster) |
272
+ | `ownTeam` | The participant's team, found in `teams`, else `null` (`createMockTeam()` builds one) |
273
+ | `timer` | Disabled (no auto-tick) |
274
+ | `scenarioName` | `null` |
275
+ | `callbacks` | All present as no-ops |
277
276
 
278
277
  Every option, and those of the other two helpers, is listed in the [UI testing API reference](../api/sdk-ui-testing.md#renderuserinterfaceoptions).
279
278
 
@@ -301,11 +300,14 @@ it('calls updateSettings when a value changes', () => {
301
300
 
302
301
  #### Session UIs
303
302
 
304
- Type the helpers with the surface's generated types: `renderSessionUserInterface<SessionData>`, `createMockTeamState<TeamContext>` and `createMockSharedState<SharedContext>`. Each fixture's context then accepts only capabilities of its own scope, any of them optional, so a shared capability left on a team's fixture fails to compile, as reading one through a team does in the surface. Left untyped, the helpers accept any context.
303
+ Type the helpers with the surface's generated types: `renderSessionUserInterface<SessionData>`, `createMockTeamState<TeamContext>` and `createMockSharedState<SharedContext>`. Build the `teams` list with `createMockTeams(n)`, or `createMockTeam({ name })` for a team you name: `teamId` and `name` follow `index` unless you give them. Each fixture's context then accepts only capabilities of its own scope, any of them optional, so a shared capability left on a team's fixture fails to compile, as reading one through a team does in the surface. Left untyped, the helpers accept any context.
304
+
305
+ `sessionMeta` and `teamConfiguration` are merged over the defaults, so name only the field the test is about: `sessionMeta: { readOnly: true }` renders a frozen session, and `teamConfiguration: { max: 2 }` an independent one capped at two teams.
305
306
 
306
307
  ```typescript
307
308
  import {
308
309
  createMockSharedState,
310
+ createMockTeam,
309
311
  createMockTeamState,
310
312
  renderSessionUserInterface,
311
313
  } from '@seriousgaming/sdk/ui/testing';
@@ -325,8 +327,8 @@ it('resets all teams', () => {
325
327
  'team-1': createMockTeamState<TeamContext>({ completedTicks: 3 }),
326
328
  },
327
329
  },
328
- teams: [{ teamId: 'team-1', index: 0, name: 'Alpha' }],
329
- teamConfiguration: { mode: 'independent', max: 6 },
330
+ teams: [createMockTeam({ name: 'Alpha' })],
331
+ teamConfiguration: { max: 6 },
330
332
  callbacks: { resetGame },
331
333
  });
332
334
 
@@ -342,7 +344,7 @@ it('writes a per-team override', () => {
342
344
  'team-1': createMockTeamState<TeamContext>({ context: { price: { Price: 10 } } }),
343
345
  },
344
346
  },
345
- teams: [{ teamId: 'team-1', index: 0, name: 'Alpha' }],
347
+ teams: [createMockTeam({ name: 'Alpha' })],
346
348
  setData,
347
349
  });
348
350
 
@@ -392,7 +394,7 @@ setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not
392
394
 
393
395
  ### Troubleshooting
394
396
 
395
- **"Invalid hook call" or "Cannot read properties of null (reading 'useContext')"**
397
+ **'Invalid hook call' or 'Cannot read properties of null (reading "useContext")'**
396
398
 
397
399
  Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
398
400
 
@@ -414,7 +416,7 @@ export default defineConfig({
414
416
 
415
417
  This is already included in the scaffold-generated `vitest.config.ts`.
416
418
 
417
- **"Found multiple elements with the text: X" / DOM accumulation between tests**
419
+ **'Found multiple elements with the text: X' or DOM accumulation between tests**
418
420
 
419
421
  React Testing Library cannot auto-detect Vitest's test lifecycle unless `globals: true` is set. Without it, the DOM is not cleaned up between tests. The scaffold-generated `test-setup.ts` handles this explicitly:
420
422
 
@@ -478,15 +480,15 @@ So drive every code path that writes through the runtime: an [engine test](#engi
478
480
 
479
481
  ## Best practices
480
482
 
481
- 1. **Test what the user sees**: assert on rendered text, input values, and visible state rather than internal component state.
483
+ 1. **Test what the user sees**: assert on rendered text, input values, and visible state rather than internal component state
482
484
 
483
- 2. **Use `fireEvent.change` for controlled inputs**: `userEvent.type` won't work correctly when the mock `setData`/`updateSettings` doesn't update the displayed value between keystrokes.
485
+ 2. **Use `fireEvent.change` for controlled inputs**: `userEvent.type` won't work correctly when the mock `setData`/`updateSettings` doesn't update the displayed value between keystrokes
484
486
 
485
- 3. **Keep context data close to realistic**: populate `mockData` with values that reflect a real game state. Tests that rely on fallback/undefined values hide bugs.
487
+ 3. **Keep context data close to realistic**: populate `mockData` with values that reflect a real game state. Tests that rely on fallback/undefined values hide bugs
486
488
 
487
- 4. **Test edge cases**: zero values, maximum values, empty arrays, and missing optional capabilities.
489
+ 4. **Test edge cases**: zero values, maximum values, empty arrays, and missing optional capabilities
488
490
 
489
- 5. **One `renderApp` helper per test file**: accept `dataOverrides` and `configOverrides` parameters so individual tests can vary only the data they care about.
491
+ 5. **One `renderApp` helper per test file**: accept `dataOverrides` and `configOverrides` parameters so individual tests can vary only the data they care about
490
492
 
491
493
  ## Engine tests
492
494
 
@@ -569,9 +571,9 @@ See [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) for
569
571
 
570
572
  ## Next steps
571
573
 
572
- - [Building user interfaces](./ui.md) - Build and develop custom UIs
573
- - [Creating engines](./engine.md) - Write a testable engine
574
- - [Engine testing](./engine-testing.md) - Whole-game tests with `createTestSession`
575
- - [Recipe: Test a user interface](../recipes/test-user-interface.md) - Step-by-step testing walkthrough
576
- - [Recipe: Test a whole game in-process](../recipes/test-with-engine.md) - In-process engine test setup
577
- - [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md) - Browser-based end-to-end tests
574
+ - [Building user interfaces](./ui.md): build and develop custom UIs
575
+ - [Creating engines](./engine.md): write a testable engine
576
+ - [Engine testing](./engine-testing.md): whole-game tests with `createTestSession`
577
+ - [Recipe: Test a user interface](../recipes/test-user-interface.md): step-by-step testing walkthrough
578
+ - [Recipe: Test a whole game in-process](../recipes/test-with-engine.md): in-process engine test setup
579
+ - [Recipe: Test UIs end to end with Playwright](../recipes/e2e-testing.md): browser-based end-to-end tests