@seriousgaming/sdk-tools 1.3.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 (176) hide show
  1. package/dist/cli.js +4055 -2646
  2. package/dist/client.js +807 -172
  3. package/dist/core/session-host.d.ts +4 -2
  4. package/dist/core/settings-locks.d.ts +27 -2
  5. package/dist/dev/console/assets/{index-DEV8N0na.js → index-BVF8exas.js} +22 -22
  6. package/dist/dev/console/index.html +1 -1
  7. package/dist/dev/public-origins.d.ts +61 -0
  8. package/dist/dev/routes.d.ts +4 -0
  9. package/dist/dev/shell.d.ts +32 -4
  10. package/dist/dev/view/batch.d.ts +7 -1
  11. package/dist/docs/ai-agents.md +5 -0
  12. package/dist/docs/api/index.md +1 -1
  13. package/dist/docs/api/sdk-tools-client.md +1 -0
  14. package/dist/docs/api/sdk.md +79 -2
  15. package/dist/docs/changelog-0.x.md +2 -2
  16. package/dist/docs/changelog.md +62 -4
  17. package/dist/docs/cli-and-dev-server.md +58 -0
  18. package/dist/docs/cli-error-codes.md +39 -36
  19. package/dist/docs/cli-reference.md +68 -21
  20. package/dist/docs/concepts/terminology.md +1 -1
  21. package/dist/docs/environment-variables.md +10 -5
  22. package/dist/docs/guides/ai-facilitation.md +2 -0
  23. package/dist/docs/guides/capabilities.md +4 -0
  24. package/dist/docs/guides/designing-a-game.md +2 -0
  25. package/dist/docs/guides/designing-screens.md +133 -0
  26. package/dist/docs/guides/endpoints.md +4 -2
  27. package/dist/docs/guides/engine-testing.md +6 -2
  28. package/dist/docs/guides/engine.md +2 -0
  29. package/dist/docs/guides/file-handling.md +116 -22
  30. package/dist/docs/guides/games.md +3 -1
  31. package/dist/docs/guides/global-settings.md +2 -0
  32. package/dist/docs/guides/guide.md +2 -0
  33. package/dist/docs/guides/hooks.md +2 -0
  34. package/dist/docs/guides/index.md +9 -0
  35. package/dist/docs/guides/internationalization.md +2 -0
  36. package/dist/docs/guides/llm-integration.md +5 -3
  37. package/dist/docs/guides/multi-team-games.md +3 -1
  38. package/dist/docs/guides/patterns.md +2 -0
  39. package/dist/docs/guides/presentation.md +1 -1
  40. package/dist/docs/guides/production-constraints.md +2 -0
  41. package/dist/docs/guides/scenario-editor.md +3 -1
  42. package/dist/docs/guides/scenarios.md +15 -3
  43. package/dist/docs/guides/session-game-flow.md +365 -0
  44. package/dist/docs/guides/session-hooks.md +205 -0
  45. package/dist/docs/guides/session.md +27 -565
  46. package/dist/docs/guides/settings.md +64 -2
  47. package/dist/docs/guides/setup.md +3 -1
  48. package/dist/docs/guides/speech-generation.md +2 -0
  49. package/dist/docs/guides/starter-game.md +61 -21
  50. package/dist/docs/guides/testing.md +2 -0
  51. package/dist/docs/guides/tick-controller.md +3 -1
  52. package/dist/docs/guides/type-safety.md +2 -0
  53. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  54. package/dist/docs/guides/ui-participants.md +281 -0
  55. package/dist/docs/guides/ui-styling.md +263 -0
  56. package/dist/docs/guides/ui-ticks.md +247 -0
  57. package/dist/docs/guides/ui.md +11 -1092
  58. package/dist/docs/guides/upgrading.md +2 -0
  59. package/dist/docs/guides/validators.md +64 -4
  60. package/dist/docs/guides/waiting-room.md +1 -1
  61. package/dist/docs/index.md +2 -1
  62. package/dist/docs/page-index.md +145 -0
  63. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  64. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  65. package/dist/docs/recipes/create-presentation.md +11 -0
  66. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  67. package/dist/docs/recipes/create-session-ui.md +2 -1
  68. package/dist/docs/recipes/create-setup.md +1 -0
  69. package/dist/docs/recipes/create-user-interface.md +1 -0
  70. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  71. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  72. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  73. package/dist/docs/recipes/index.md +3 -0
  74. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  75. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  76. package/dist/docs/recipes/upload-and-display-files.md +7 -7
  77. package/dist/docs/recipes/use-request-tick.md +2 -2
  78. package/dist/docs/recipes/validate-scenarios.md +4 -1
  79. package/dist/execution/config-resolver.d.ts +4 -1
  80. package/dist/execution/endpoint-runner.d.ts +6 -0
  81. package/dist/execution/logic-calls.d.ts +7 -2
  82. package/dist/execution/scenario-gates.d.ts +21 -1
  83. package/dist/guide/settings.d.ts +1 -1
  84. package/dist/host.js +64 -2
  85. package/dist/runtime/manifest-version.d.ts +1 -1
  86. package/dist/runtime.js +7 -2
  87. package/dist/storage/asset-resolver.d.ts +24 -1
  88. package/dist/storage/blob-store.d.ts +7 -0
  89. package/dist/templates/package/CLAUDE.md.template +14 -5
  90. package/dist/templates/package/DESIGN.md.liquid +39 -7
  91. package/dist/templates/package/README.md.liquid +1 -1
  92. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  93. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  94. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  95. package/dist/templates/starter-game/package.json +2 -0
  96. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  97. package/dist/templates/starter-game/presentation/index.html +20 -0
  98. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  99. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  100. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  101. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  102. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  103. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  104. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  105. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  106. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  107. package/dist/templates/starter-game/presentation/types.ts +94 -0
  108. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  109. package/dist/templates/starter-game/session/defaults.ts +6 -0
  110. package/dist/templates/starter-game/session/index.html +1 -1
  111. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  112. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  113. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  114. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  115. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  116. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  117. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  118. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  119. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  120. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  121. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  122. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  123. package/dist/templates/starter-game/session/src/status.ts +28 -0
  124. package/dist/templates/starter-game/session/types.ts +8 -2
  125. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  126. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  127. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  128. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  129. package/dist/templates/starter-game/shared/days.ts +11 -0
  130. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  131. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  132. package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
  133. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  134. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  135. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  136. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  137. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  138. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  139. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  140. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  141. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  142. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  143. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  144. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  145. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  146. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  147. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  148. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  149. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  150. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  151. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  152. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  153. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  154. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  155. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  156. package/dist/templates/starter-game/ui/types.ts +6 -0
  157. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  158. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  159. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  160. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  161. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  162. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  163. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  164. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  165. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  166. package/dist/utils/error-codes.d.ts +12 -0
  167. package/dist/utils/local-refs.d.ts +40 -0
  168. package/dist/utils/schema-members.d.ts +19 -0
  169. package/package.json +11 -4
  170. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  171. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  172. package/dist/templates/starter-game/session/src/format.ts +0 -8
  173. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  174. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  175. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  176. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
@@ -11,10 +11,10 @@ The codes are the contract: branch on the code, never on the message. A code is
11
11
  | Exit code | Category | Meaning | Codes |
12
12
  | --------- | ------------- | ------------------- | ----- |
13
13
  | 1 | `internal` | Internal error | 1 |
14
- | 2 | `usage` | Usage error | 15 |
14
+ | 2 | `usage` | Usage error | 16 |
15
15
  | 3 | `package` | Invalid package | 32 |
16
- | 4 | `refused` | Refused by the game | 11 |
17
- | 5 | `environment` | Environment | 18 |
16
+ | 4 | `refused` | Refused by the game | 12 |
17
+ | 5 | `environment` | Environment | 19 |
18
18
 
19
19
  ## Codes
20
20
 
@@ -40,6 +40,7 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
40
40
  | `PROMPT_REQUIRED` | The command would have to ask a question, and prompts are off: there is no terminal, --json or SERIOUSGAMING_JSON is set, or CI is set. | |
41
41
  | `INPUT_INVALID` | Input given to the command is not valid JSON, or does not match the shape it must have. | |
42
42
  | `FILE_NOT_FOUND` | A file named on the command line does not exist or cannot be read. | |
43
+ | `DOCS_SECTION_NOT_FOUND` | The page `docs view --section` reads has no heading by that name; the details list the ones it has. | |
43
44
  | `RESOURCE_TYPE_UNKNOWN` | The resource type does not exist, or does not support this operation. | |
44
45
  | `RESOURCE_NOT_FOUND` | The package has no resource of that type with that identifier. | |
45
46
  | `RESOURCE_EXISTS` | A resource with that identifier, or in that slot, already exists. | |
@@ -85,42 +86,44 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
85
86
 
86
87
  ### Exit 4: refused by the game
87
88
 
88
- | Code | When | Also a diagnostic |
89
- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
90
- | `REFUSED_DENIED` | The session refused the command (the 'denied' outcome). | |
91
- | `REFUSED_VALIDATION` | A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why. | |
92
- | `REFUSED_CONFLICT` | The write conflicted with a concurrent tick (the 'conflict' outcome). | |
93
- | `REFUSED_SUPERSEDED` | The write arrived after the tick it was for (the 'superseded' outcome). | |
94
- | `TICK_FAILED` | The tick failed, usually because game logic threw (the 'tick-failed' outcome). | |
95
- | `SESSION_ERROR` | The session failed the command unexpectedly (the 'error' outcome). | |
96
- | `INVALID_REQUEST` | The endpoint request failed its requestSchema, so the handler did not run. | |
97
- | `HANDLER_ERROR` | The endpoint's handler threw, or ran past its execution bound. | |
98
- | `INVALID_RESPONSE` | What the endpoint's handler returned broke its declaration. | |
99
- | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. | Yes |
100
- | `SETTINGS_STALE` | The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`. | |
89
+ | Code | When | Also a diagnostic |
90
+ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
91
+ | `REFUSED_DENIED` | The session refused the command (the 'denied' outcome). | |
92
+ | `REFUSED_VALIDATION` | A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why. | |
93
+ | `REFUSED_CONFLICT` | The write conflicted with a concurrent tick (the 'conflict' outcome). | |
94
+ | `REFUSED_SUPERSEDED` | The write arrived after the tick it was for (the 'superseded' outcome). | |
95
+ | `TICK_FAILED` | The tick failed, usually because game logic threw (the 'tick-failed' outcome). | |
96
+ | `SESSION_ERROR` | The session failed the command unexpectedly (the 'error' outcome). | |
97
+ | `INVALID_REQUEST` | The endpoint request failed its requestSchema, so the handler did not run. | |
98
+ | `HANDLER_ERROR` | The endpoint's handler threw, or ran past its execution bound. | |
99
+ | `INVALID_RESPONSE` | What the endpoint's handler returned broke its declaration. | |
100
+ | `LOGIC_ERROR` | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. | Yes |
101
+ | `SURFACE_NOT_RENDERED` | `sdk screenshot` gave up on the page: its surface did not connect, or did not report its first paint before the timeout. error.details carries the page's console errors, failed requests and uncaught exceptions. | |
102
+ | `SETTINGS_STALE` | The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`. | |
101
103
 
102
104
  ### Exit 5: environment
103
105
 
104
- | Code | When | Also a diagnostic |
105
- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
106
- | `NO_SESSION` | No dev server is running for this package, and the command will not start one. | |
107
- | `SESSION_STALE` | The running session was started from an out-of-date package and must restart. | |
108
- | `LOCK_HELD` | A dev server is already running for this package. | |
109
- | `PORT_IN_USE` | No free port was found to listen on. | |
110
- | `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it. | |
111
- | `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer. | |
112
- | `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`. | |
113
- | `DEV_SERVER_START_FAILED` | A dev server could not be started. | |
114
- | `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped. | |
115
- | `LLM_NOT_CONFIGURED` | Logic called generateText, and the dev server or in-process session running it has no platform API key configured. | |
116
- | `PLATFORM_UNREACHABLE` | The Serious Gaming platform could not be reached. | |
117
- | `PLATFORM_UNAUTHORISED` | The platform refused the API key, or its holder lacks the role the call needs. | |
118
- | `PLATFORM_ERROR` | The platform failed the request. | |
119
- | `API_KEY_MISSING` | No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key. | |
120
- | `INSTALL_FAILED` | Installing a new package's dependencies failed. | |
121
- | `SDK_INCOMPLETE` | This install of the SDK tools is missing files it ships with, such as its docs. | |
122
- | `SETTINGS_FILE_INVALID` | The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed. | |
123
- | `WRITE_FAILED` | A file or directory could not be written, moved or removed. | |
106
+ | Code | When | Also a diagnostic |
107
+ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
108
+ | `NO_SESSION` | No dev server is running for this package, and the command will not start one. | |
109
+ | `SESSION_STALE` | The running session was started from an out-of-date package and must restart. | |
110
+ | `LOCK_HELD` | A dev server is already running for this package. | |
111
+ | `PORT_IN_USE` | No free port was found to listen on. | |
112
+ | `DEV_SERVER_OUTDATED` | The running dev server does not understand the command: it is older than this CLI. Restart it. | |
113
+ | `DEV_SERVER_UNREACHABLE` | The dev server the lock file names does not answer. | |
114
+ | `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`. | |
115
+ | `DEV_SERVER_START_FAILED` | A dev server could not be started. | |
116
+ | `DEV_SERVER_STOP_FAILED` | The dev server could not be stopped. | |
117
+ | `BROWSER_MISSING` | `sdk screenshot` found no Playwright in the package's dependencies, or no Chromium installed for it. Add `@playwright/test` and run `pnpm exec playwright install chromium`. | |
118
+ | `LLM_NOT_CONFIGURED` | Logic called generateText, and the dev server or in-process session running it has no platform API key configured. | |
119
+ | `PLATFORM_UNREACHABLE` | The Serious Gaming platform could not be reached. | |
120
+ | `PLATFORM_UNAUTHORISED` | The platform refused the API key, or its holder lacks the role the call needs. | |
121
+ | `PLATFORM_ERROR` | The platform failed the request. | |
122
+ | `API_KEY_MISSING` | No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key. | |
123
+ | `INSTALL_FAILED` | Installing a new package's dependencies failed. | |
124
+ | `SDK_INCOMPLETE` | This install of the SDK tools is missing files it ships with, such as its docs. | |
125
+ | `SETTINGS_FILE_INVALID` | The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed. | |
126
+ | `WRITE_FAILED` | A file or directory could not be written, moved or removed. | |
124
127
 
125
128
  ## Diagnostic codes
126
129
 
@@ -1641,7 +1641,7 @@ Open or close the session waiting room.
1641
1641
  pnpm run sdk scenario [identifier] [options]
1642
1642
  ```
1643
1643
 
1644
- Activate a scenario, or `none` to run on the settings defaults.
1644
+ Activate a scenario, or `none` to run on the settings defaults when no scenario is the default.
1645
1645
 
1646
1646
  | Option | Default | Description |
1647
1647
  | -------------------------- | --------------------- | ----------------------------------------------------- |
@@ -1740,7 +1740,7 @@ pnpm run sdk reset --walkthrough # back to tick 0
1740
1740
 
1741
1741
  The run is built the first time something asks for it, so there is nothing to create. In `sdk dev` it is also a surface, at `/walkthrough`, listed in the drawer's Surfaces tab.
1742
1742
 
1743
- Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui.md#walkthroughs).
1743
+ Your logic reads `meta.runKind` and your surfaces read `useRunKind()` to tell the two apart. See [Engines](./guides/engine.md#walkthroughs) and [User interfaces](./guides/ui-participants.md#walkthroughs).
1744
1744
 
1745
1745
  ### Upload a blob
1746
1746
 
@@ -1973,23 +1973,26 @@ pnpm run sdk dev [options]
1973
1973
 
1974
1974
  Start the Serious Gaming development server with hot reload.
1975
1975
 
1976
- | Option | Default | Description |
1977
- | --------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1978
- | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1979
- | `-p, --port [PORT]` | `3000` | Port to run the dev server on, or auto for any free port (can also be set via SERIOUSGAMING_DEV_PORT env var or .env file). |
1980
- | `--vite-port [VITE_PORT]` | | Port to run the Vite dev server on (defaults to PORT + 1). |
1981
- | `--asset-port [ASSET_PORT]` | | Port game UI bundles and their assets are served from, which is a separate origin from the console (defaults to the next free port after the Vite port). |
1982
- | `--no-open` | | Do not automatically open browser. |
1983
- | `--api-key [KEY]` | | Serious Gaming platform API key for LLM calls (can also be set via SERIOUSGAMING_API_KEY env var or .env file). |
1984
- | `--host [URL]` | | Serious Gaming platform origin for LLM calls (can also be set via SERIOUSGAMING_API_HOST env var or .env file). |
1985
- | `--lan` | | Listen on every network interface, so phones and tablets on the same network can connect (localhost only by default). |
1986
- | `--teams [NUMBER]` | | Number of teams to simulate (each accessible at `/team/<n>);` omit to use the game's teams.min. |
1987
- | `--participants [COUNT]` | | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1). |
1988
- | `--scenario [ID]` | | Scenario identifier to activate (uses default scenario if omitted). |
1989
- | `--fake-clock` | | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting. |
1990
- | `--reinit-on-change` | | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability removed or rescoped), rather than recording it as pending once play is under way. |
1991
- | `--isolated` | | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
1992
- | `--brand <FILE>` | | A brand file to preview the game in, added to the brand picker and selected; repeat for more than one. |
1976
+ | Option | Default | Description |
1977
+ | ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1978
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1979
+ | `-p, --port [PORT]` | `3000` | Port to run the dev server on, or auto for any free port (can also be set via SERIOUSGAMING_DEV_PORT env var or .env file). |
1980
+ | `--vite-port [VITE_PORT]` | | Port to run the Vite dev server on (defaults to PORT + 1). |
1981
+ | `--asset-port [ASSET_PORT]` | | Port game UI bundles and their assets are served from, which is a separate origin from the console (defaults to the next free port after the Vite port). |
1982
+ | `--no-open` | | Do not automatically open browser. |
1983
+ | `--api-key [KEY]` | | Serious Gaming platform API key for LLM calls (can also be set via SERIOUSGAMING_API_KEY env var or .env file). |
1984
+ | `--host [URL]` | | Serious Gaming platform origin for LLM calls (can also be set via SERIOUSGAMING_API_HOST env var or .env file). |
1985
+ | `--lan` | | Listen on every network interface, so phones and tablets on the same network can connect (localhost only by default). |
1986
+ | `--teams [NUMBER]` | | Number of teams to simulate (each accessible at `/team/<n>);` omit to use the game's teams.min. |
1987
+ | `--participants [COUNT]` | | Participants to seed each team with, zero or more, or one per team as 3,0,2 (defaults to 1). |
1988
+ | `--scenario [ID]` | | Scenario identifier to activate (uses default scenario if omitted). |
1989
+ | `--fake-clock` | | Run on a clock that moves only when `sdk clock advance` moves it, to test automatic ticks without waiting. |
1990
+ | `--reinit-on-change` | | Restart the game at tick 0 whenever an edit applies only at initialisation (a setting, a manifest field such as teams, a capability removed or rescoped), rather than recording it as pending once play is under way. |
1991
+ | `--isolated` | | Run beside any dev server already running for this package, for tests and recordings: no lock file (CLI commands reach it through SERIOUSGAMING_DEV_URL), configuration from the package alone, and uploads in a temporary directory. |
1992
+ | `--brand <FILE>` | | A brand file to preview the game in, added to the brand picker and selected; repeat for more than one. |
1993
+ | `--public-url <ORIGIN>` | | The origin people reach the console at, when a proxy or gateway stands in front of the server; used for every link the server prints or hands out (can also be set via SERIOUSGAMING_DEV_PUBLIC_URL). |
1994
+ | `--public-asset-url <ORIGIN>` | | The origin browsers load game surfaces from behind that proxy, which must differ from the console's (defaults to the --public-url host on the asset port; can also be set via SERIOUSGAMING_DEV_PUBLIC_ASSET_URL). |
1995
+ | `--public-hmr-url <ORIGIN>` | | The origin a surface's hot-reload client connects to behind that proxy, as wss:// or ws:// (defaults to the public asset host on the Vite port; can also be set via SERIOUSGAMING_DEV_PUBLIC_HMR_URL). |
1993
1996
 
1994
1997
  In more detail:
1995
1998
 
@@ -2003,10 +2006,11 @@ In more detail:
2003
2006
  - `--reinit-on-change`: however far play has gone, rather than holding the edit as pending (see [What reloads](#what-reloads)). The console shows a short 'Settings changed, game restarted' notice each time. The hosted builder starts the dev server this way
2004
2007
  - `--brand`: a brand file to preview the game in, added to the console's **Brand** menu and selected. Repeat it for more than one; the first is selected. See [Preview your game in another brand](./guides/theming-and-branding.md#preview-your-game-in-another-brand)
2005
2008
  - `--isolated`: for a test run or a recording (see below)
2009
+ - `--public-url`, `--public-asset-url` and `--public-hmr-url`: the addresses people reach the server at when a proxy or gateway stands in front of it. Each defaults to its `SERIOUSGAMING_DEV_PUBLIC_*` environment variable. See [Embedding the dev server](./cli-and-dev-server.md#embedding-the-dev-server)
2006
2010
 
2007
2011
  A package holds one session, so a second `sdk dev` for the same package is refused whatever port it asks for, and names the one already running. Stop that one with `sdk dev stop` to move it elsewhere, or start the second with `--isolated`.
2008
2012
 
2009
- The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated`.
2013
+ The server prints the console's address and the address game surfaces are served from. With `-j, --json`, the envelope it writes when it stops carries `url`, `assetUrl`, `port`, `assetPort` and `isolated`, and `publicUrl` and `publicAssetUrl` when a public origin is set.
2010
2014
 
2011
2015
  ### Run a second server beside your own
2012
2016
 
@@ -2087,6 +2091,36 @@ Stop the dev server running for this package.
2087
2091
 
2088
2092
  `dev status` and `dev stop` report through the [envelope](#json-output) with `-j, --json`, like every command.
2089
2093
 
2094
+ ### Screenshot a surface
2095
+
2096
+ ```text
2097
+ pnpm run sdk screenshot <path> [options]
2098
+ ```
2099
+
2100
+ Capture a surface as a PNG, as a participant sees it.
2101
+
2102
+ | Option | Default | Description |
2103
+ | -------------------------- | --------------------- | ------------------------------------------------------------------------------------- |
2104
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
2105
+ | `--width <PIXELS>` | `1280` | Viewport width. |
2106
+ | `--height <PIXELS>` | `800` | Viewport height. |
2107
+ | `--scheme <SCHEME>` | | Colour scheme: light, dark or system. |
2108
+ | `--brand <ID>` | | Brand to show, from those the dev server offers. |
2109
+ | `--locale <CODE>` | | Session locale for the capture; a running server's is switched back after. |
2110
+ | `--full-page` | | Capture the surface's whole height, not just the viewport. |
2111
+ | `--out <FILE>` | | PNG to write (default: `.seriousgaming-sdk/screenshots/<path>-<width>x<height>.png).` |
2112
+ | `--timeout <SECONDS>` | `30` | How long to wait for the surface to render. |
2113
+
2114
+ ```bash
2115
+ pnpm run sdk screenshot /team/1/player/1 --width 390 --height 844 --scheme dark --out plan.png --json
2116
+ ```
2117
+
2118
+ The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
2119
+
2120
+ It drives the game's own Playwright (`@playwright/test`, which every scaffolded game has), and fails with `BROWSER_MISSING` (exit 5) without it or its Chromium. A surface that does not connect, or does not report its first paint within `--timeout`, fails with `SURFACE_NOT_RENDERED` (exit 4), carrying the same three lists in `error.details`.
2121
+
2122
+ The locale is the session's, not a viewer's, so `--locale` switches the session for the capture, and switches a running dev server back afterwards. See [Screenshot a surface](./recipes/screenshot-a-surface.md).
2123
+
2090
2124
  ### Dev server features
2091
2125
 
2092
2126
  - **Hot reloading**: edit logic, bundles, the manifest or UIs and see the change without a restart (see [What reloads](#what-reloads))
@@ -2510,11 +2544,16 @@ Prints the installed SDK version to stdout.
2510
2544
  ### Browse the documentation
2511
2545
 
2512
2546
  ```text
2513
- pnpm run sdk docs view [file]
2547
+ pnpm run sdk docs view [file] [options]
2514
2548
  ```
2515
2549
 
2516
2550
  View Serious Gaming SDK documentation.
2517
2551
 
2552
+ | Option | Default | Description |
2553
+ | --------------------- | ------- | ------------------------------------------------------------------------- |
2554
+ | `--outline` | | List the page's headings, with each section's length in characters. |
2555
+ | `--section <heading>` | | Print only the section under this heading, named by its slug or its text. |
2556
+
2518
2557
  ```text
2519
2558
  pnpm run sdk docs export [dir]
2520
2559
  ```
@@ -2524,6 +2563,14 @@ Export SDK documentation to your project.
2524
2563
  The docs ship inside the package at `node_modules/@seriousgaming/sdk-tools/dist/docs`, so they match the installed version and need no network. Search them with your editor or `grep`.
2525
2564
 
2526
2565
  - `docs view` with no argument prints the tree of documents; with a path (for example `guides/engine.md`) it prints that document
2566
+ - `docs view page-index.md` lists every page with a one-sentence summary and its length: the place to find the page for a subject
2567
+ - `docs view <path> --outline` lists a page's headings, each with its level, its slug and its section's length in characters; `--section <heading>` prints only that section, named by its slug or its text, up to the next heading of the same or a higher level. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the slugs the page has in `details.available`
2568
+
2569
+ ```bash
2570
+ pnpm run --silent sdk docs view guides/session.md --outline
2571
+ pnpm run --silent sdk docs view guides/session.md --section building-the-session-ui
2572
+ ```
2573
+
2527
2574
  - `docs export` copies every document to `dir`, or `.seriousgaming-sdk/docs` by default, so an editor or agent can search them locally
2528
2575
 
2529
2576
  ## Environment variables
@@ -298,7 +298,7 @@ The quality and cost level of an LLM call. The platform maps each tier to a mode
298
298
 
299
299
  ### Asset reference
300
300
 
301
- A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
301
+ A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `describeAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
302
302
 
303
303
  ### Blob
304
304
 
@@ -57,11 +57,14 @@ A relative path is an error. See the [global settings guide](./guides/global-set
57
57
 
58
58
  A session command starts a dev server when none is running, and has no `--port` of its own to pass it. This is how to tell that server where to start looking. See [The CLI and the dev server](./cli-and-dev-server.md).
59
59
 
60
- | Variable | Required | Default | Purpose |
61
- | ----------------------------- | -------- | ----------------------------------- | ------------------------------------------------------------------------------- |
62
- | `SERIOUSGAMING_DEV_PORT` | No | `3000` | Where the dev server starts looking for a free port, or `auto` for any free one |
63
- | `SERIOUSGAMING_DEV_URL` | No | Unset | The server every session command targets, in place of the one the lock names |
64
- | `SERIOUSGAMING_DEV_STATE_DIR` | No | The package's `.seriousgaming-sdk/` | Where the lock file naming the running server is kept |
60
+ | Variable | Required | Default | Purpose |
61
+ | ------------------------------------ | -------- | --------------------------------------- | ------------------------------------------------------------------------------- |
62
+ | `SERIOUSGAMING_DEV_PORT` | No | `3000` | Where the dev server starts looking for a free port, or `auto` for any free one |
63
+ | `SERIOUSGAMING_DEV_URL` | No | Unset | The server every session command targets, in place of the one the lock names |
64
+ | `SERIOUSGAMING_DEV_STATE_DIR` | No | The package's `.seriousgaming-sdk/` | Where the lock file naming the running server is kept |
65
+ | `SERIOUSGAMING_DEV_PUBLIC_URL` | No | Unset | The origin people reach the console at, behind a proxy |
66
+ | `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | No | The public URL's host on the asset port | The origin browsers load game surfaces from, behind a proxy |
67
+ | `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | No | The public asset host on the Vite port | The origin a surface's hot-reload client connects to, behind a proxy |
65
68
 
66
69
  `SERIOUSGAMING_DEV_PORT` is a starting point, not a binding: the server steps up to the first free port from there, and prints the one it lands on. Equivalent CLI flag on `pnpm run sdk dev`: `--port`.
67
70
 
@@ -69,6 +72,8 @@ A session command starts a dev server when none is running, and has no `--port`
69
72
 
70
73
  `SERIOUSGAMING_DEV_STATE_DIR` moves the lock out of the project, since it is runtime state rather than project content: a container whose project directory is restored from a snapshot otherwise brings back a lock naming a process from before it. Each package gets its own entry inside it, so one directory can serve several. Saved configuration and uploads stay in the package. See [Where the session lives](./cli-reference.md#where-the-session-lives).
71
74
 
75
+ The three `SERIOUSGAMING_DEV_PUBLIC_*` variables are for a server behind a proxy or gateway, such as one shown in another page's frame, and change every address the server prints or hands out. Equivalent CLI flags on `pnpm run sdk dev`: `--public-url`, `--public-asset-url` and `--public-hmr-url`. See [Embedding the dev server](./cli-and-dev-server.md#embedding-the-dev-server).
76
+
72
77
  ## Output and prompts
73
78
 
74
79
  | Variable | Required | Default | Purpose |
@@ -8,6 +8,8 @@ Most of it is not new machinery. An agent acting for a facilitator is close to a
8
8
 
9
9
  Write for an agent that supports the facilitator's judgement rather than replacing it: the facilitator still reads the room and decides what happens next.
10
10
 
11
+ **Keywords:** AI facilitation, facilitator's AI agent, AI assistant, agent tools, external endpoint, endpoint visibility, describe data for a model, schema descriptions, what an agent can see
12
+
11
13
  ## What the agent can see
12
14
 
13
15
  A game's data lives in named capabilities. Every screen declares which ones it needs, and receives exactly those. The agent is handed data the same way, so nothing you have not declared reaches it.
@@ -4,6 +4,8 @@ Capabilities hold your game's state: named groups of variables that the engine a
4
4
 
5
5
  This guide explains the state model, who sees and writes each capability, and how long its values last, then covers creating capabilities and every kind of variable they hold.
6
6
 
7
+ **Keywords:** capability, game state, variables, variablesSchema, context, reads and writes, private capability, scope, lifetime, keyed collection, variable types, new capability
8
+
7
9
  ## The state model
8
10
 
9
11
  A capability is a named collection of related variables, declared by a schema. For example:
@@ -14,6 +16,8 @@ A capability is a named collection of related variables, declared by a schema. F
14
16
 
15
17
  Each capability declares its variables in a `variablesSchema`: a full JSON Schema 7 object whose properties are the variables, each with a type, a `default`, and any constraints. Every capability starts from those defaults, so its variables exist from the first tick for anything that declares it.
16
18
 
19
+ A shape used in several places, or one that contains itself, is declared once under `$defs` and used with a `$ref`, as in a settings schema (see [Reuse a shape, or nest it to any depth](./settings.md#reuse-a-shape-or-nest-it-to-any-depth)). The variable's `default` goes beside the `$ref`.
20
+
17
21
  ### Context is scoped by capability
18
22
 
19
23
  A team's state, the context, is one object keyed by capability identifier, each value holding that capability's variables:
@@ -4,6 +4,8 @@ A serious game teaches by letting people act and then see what their actions cau
4
4
 
5
5
  The rest of the docs explain how to build each part. This page is about what to build, so read it before you replace the lemonade stand with your own game.
6
6
 
7
+ **Keywords:** game design, design a serious game, learning outcome, decisions, rounds, feedback, debrief, pacing, facilitator, brief to game, plan a simulation
8
+
7
9
  ## Start from what people should take away
8
10
 
9
11
  Write down the one or two things a participant should understand, or do differently, by the end. Everything else in the design serves them.
@@ -0,0 +1,133 @@
1
+ # Designing screens
2
+
3
+ What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
4
+
5
+ **Keywords:** UI design, UX, screen design, dialog, backdrop, side panel, icons, Material Symbols, screen brief, layout, visual hierarchy, primary action, spacing, type scale, density, mobile, phone, projector, empty state, loading state, error state, feedback, accessibility, contrast, focus, keyboard, right-to-left, identity, look and feel, design review
6
+
7
+ This page is about standards and habits, not a house style. Publishers build for their own brands, so nothing here asks a game to look a particular way. It asks each screen to be clear about what it is for, to work on the device it is used on, and to handle every state it can be in. For the mechanics of building a surface, see [Building user interfaces](./ui.md); for the host's colours, logo and fonts, see [Theming and branding](./theming-and-branding.md).
8
+
9
+ ## Start with a brief
10
+
11
+ Write the screen's brief before you write its code. A few lines in `DESIGN.md` are enough:
12
+
13
+ - **Who uses it, and on what:** a participant on their own phone, a team round one laptop, a facilitator on a laptop that is also on the projector
14
+ - **Its one main action:** the thing the person came to the screen to do
15
+ - **What they need to see to do it:** the two or three numbers or facts the action depends on
16
+ - **Its states:** before play, mid-round, waiting for a tick, after the last round, and when something goes wrong
17
+ - **Its tone:** calm and focused, playful, urgent against a clock
18
+
19
+ A screen without a brief tends to become a dump of every variable the surface reads, laid out in the order the schema lists them. That is the most common reason two games built with the SDK look the same.
20
+
21
+ **Good:** 'Participant, own phone, standing at a stall. Main action: set how many of each item to make. Needs: the forecast and what is left of capacity. Tone: quick and light.'
22
+
23
+ **Weak:** 'Shows the plan, the weather and the results.'
24
+
25
+ ## Design for the room
26
+
27
+ Simulations are played in workshops, so design for the devices the brief names, not the monitor you build on.
28
+
29
+ - **A participant's phone:** one column, the main action reachable with a thumb, nothing that needs hovering. Expect a narrow screen (360 CSS pixels wide is common), patchy attention, and someone talking to them while they use it
30
+ - **A team's shared laptop:** room for two columns, but several people read it at once from further away, so keep text larger than you would for one reader
31
+ - **The facilitator's laptop:** dense is fine, because they are fluent in it by the second round. Group by what they do (watch, intervene, move the session on) rather than by data source
32
+ - **A projector:** large type, high contrast, little on screen at once. Assume the back of the room is five metres away and the projector washes out pale colours. A presentation is always projected; a session screen often is
33
+
34
+ Every surface also runs inside the host's frame, under the host's own bar. A dialog with a backdrop darkens only the frame and looks broken, so show detail in a side panel, ask 'are you sure?' beside the button that asked, and go full screen for what the room looks at. See [Avoid dialogs with a backdrop](./session.md#avoid-dialogs-with-a-backdrop).
35
+
36
+ Size to the container rather than the viewport, as [Sizing to the viewport on mobile](./ui-styling.md#sizing-to-the-viewport-on-mobile) explains, and never rely on a fixed width.
37
+
38
+ ## Hierarchy
39
+
40
+ Each screen has one primary action, and the most important number or decision sits where the eye lands first.
41
+
42
+ - **One primary button.** Style the main action as the primary button and everything else as secondary or text. Two filled buttons side by side make the person choose which one matters
43
+ - **Lead with the decision or the outcome.** On a decision screen, the inputs and what limits them come first. On a results screen, the one figure that tells the team how they did comes first, with the breakdown underneath
44
+ - **Group, then label.** Put related things together and give the group a heading, rather than labelling every field
45
+ - **Cut before you shrink.** If a screen will not fit a phone, move the secondary detail behind a tab or a disclosure rather than making everything smaller
46
+
47
+ **Good:** a large 'Profit today' figure, then a short table of what sold, then a link to every past day.
48
+
49
+ **Weak:** six cards of equal size and weight, one per capability.
50
+
51
+ ## Rhythm
52
+
53
+ Consistent spacing and type make a screen feel finished, whatever the colours.
54
+
55
+ - **A spacing scale.** Pick a base unit (8px is common, and MUI's `theme.spacing` is built on it) and use multiples of it. Tight spacing inside a group, more between groups
56
+ - **A type scale.** Three or four sizes are enough: a heading, a sub-heading, body, and small print. Use weight and colour for emphasis before adding a size
57
+ - **Density suited to the device.** Generous padding and large touch targets on a phone; tighter tables on the facilitator's laptop
58
+ - **Numbers that line up.** Right-align numbers in a table and use tabular figures (`font-variant-numeric: tabular-nums`), so a column reads at a glance and values do not jump as they change
59
+
60
+ ## Every state, designed
61
+
62
+ A simulation screen spends much of its life somewhere other than mid-game. Design each of these on purpose:
63
+
64
+ | State | What the person should see |
65
+ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
66
+ | Empty | What will appear here and when, such as 'Your results appear after the first round', never a blank card or a table of zeros |
67
+ | Loading | A short, quiet indicator in the space the content will fill, so the layout does not jump when it arrives |
68
+ | Before play | What the game is and what to do first. `completedTicks` is 0 |
69
+ | Mid-game | The decision for this round, and what last round caused |
70
+ | Waiting | That a round is being processed, and that nothing is broken. See [Saying a tick is processing](./ui.md#saying-a-tick-is-processing) |
71
+ | End of game | That play is over, the final result, and what to look at for the debrief, rather than live controls that no longer do anything |
72
+ | Error | What went wrong in plain words, and what the person can do about it |
73
+ | Being observed | A facilitator watching a team sees what the team sees. See [Adapt a UI for observers](../recipes/adapt-ui-for-observers.md) |
74
+
75
+ Test each one: a component test can render a surface with `completedTicks` at 0, mid-game and at the last round (see [Testing](./testing.md)).
76
+
77
+ ## Feedback
78
+
79
+ After every action, the person should know whether it worked.
80
+
81
+ - **Show the change where it happened.** The value they changed updates in place; a separate 'saved' message is rarely needed
82
+ - **Report a refused write to the person who made it.** Every `setData` returns a promise that rejects when the host or a validator refuses the write. Route writes through `useMutationReporter` and show the reason beside the control, in the validator's own words. A write that fails silently is a decision the team thinks they made and the game never received
83
+ - **Say what a tick will do before it happens.** A button that ends the round says so ('Open the stall', 'Submit for round 3'), and disables itself while the request is in flight
84
+ - **Never punish a slow network.** Keep the person's input while a write is pending, and offer to try again on a conflict rather than discarding what they typed
85
+
86
+ **Good:** 'The stall can only make 120 things a day. Take some off another item first.' beside the slider that was moved.
87
+
88
+ **Weak:** a red toast reading 'Error 409' that disappears after two seconds.
89
+
90
+ ## Accessibility
91
+
92
+ Workshops include people with low vision, colour blindness, a keyboard instead of a mouse, and a right-to-left language. Building for them makes the screen clearer for everyone.
93
+
94
+ - **Contrast.** Body text at least 4.5:1 against its background, large text 3:1. The host's colour roles come with a `contrastText` that meets this, so put text on a role colour in its `contrastText`
95
+ - **Colour is never the only signal.** Pair red and green with a word, a sign or an icon: 'Down 12%' rather than a red number
96
+ - **Focus order follows reading order.** Tab through the screen and check the focus visits controls in the order a person reads them, and is always visible
97
+ - **Everything works from the keyboard.** Every control reachable and usable without a mouse, including sliders and custom toggles
98
+ - **Touch targets.** At least 44 by 44 CSS pixels on a phone, with space between them
99
+ - **Labels.** Every input has a visible label, and every icon-only button has an accessible name
100
+ - **Right-to-left.** In a right-to-left locale the layout mirrors. Use logical CSS properties (`margin-inline-start`, `inset-inline-end`) rather than left and right, and let the wrapper set `dir`. See [Internationalisation](./internationalization.md)
101
+ - **Motion.** Keep animation short and purposeful, and respect `prefers-reduced-motion`
102
+
103
+ ## Identity
104
+
105
+ Two games on one host share its colours, logo and fonts, so the host's theme alone will make them look alike. Give each game an identity of its own on top of the host's theme, without replacing it.
106
+
107
+ - **Keep the host's layer.** Use `createSurfaceTheme` for the palette and fonts, and show the host's logo where your layout has room (see [Theming and branding](./theming-and-branding.md)). A white-label host's clients expect to see their brand
108
+ - **Add an accent layer.** Shape, corner radius, borders, the weight of headings, and the way cards and tables are drawn are the game's to choose, and they change the feel more than colour does
109
+ - **Draw from the game's world.** Iconography, illustration and imagery from the setting: a weather icon on a stall's forecast, a floor plan in a factory game, a map in a logistics game. One strong motif used consistently beats many small decorations
110
+ - **Take icons from an icon set.** Material Symbols, through `@mui/icons-material` (a dependency of every new game), covers weather, food, money, people and most actions. Icons drawn one at a time rarely match each other in weight and size; keep your own drawing for the one motif that makes the game recognisable
111
+ - **Name things in the game's language.** 'Open the stall' rather than 'Submit', 'Stall' rather than 'Team' where the setting supports it
112
+
113
+ **Good:** the host's primary colour on the main button, weather icons from the icon set on each forecast, and rounded, card-like panels that suit a market stall.
114
+
115
+ **Weak:** the default component library look, unchanged, with the game's name in the top bar as the only sign of which game it is.
116
+
117
+ ## Check it, then go round once more
118
+
119
+ When a screen is built, check it against its brief and this page before calling it done.
120
+
121
+ 1. Open it at phone size (360 by 740) and at laptop size (1280 by 800), and on a projector-sized window for anything the room will see. The browser's device toolbar gives each size; open the surface with `?bare` so the dev console's chrome does not take up the room
122
+ 2. Walk through every state in the table above: before play, mid-game, waiting, end of game, and a refused write
123
+ 3. Tab through it with the keyboard, and switch the dev drawer to dark mode and to another brand
124
+ 4. Ask of each screen: is the main action obvious within two seconds? Is the most important number where the eye lands first? Would two games on this host look different?
125
+ 5. Fix what you found, then go round once more. The second pass catches what the first fix moved
126
+
127
+ ## Related
128
+
129
+ - [Designing a serious game](./designing-a-game.md): what each round should teach and show, before what each screen looks like
130
+ - [Building user interfaces](./ui.md): building the game UI
131
+ - [Building session UIs](./session.md): the facilitator's screen
132
+ - [Theming and branding](./theming-and-branding.md): the host's colours, logo and fonts
133
+ - [Testing](./testing.md): component tests for each state
@@ -2,6 +2,8 @@
2
2
 
3
3
  An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it. It is how a caller runs code you wrote: you own the request and response shapes, the runtime validates both, and the handler works strictly within the bounds it declares.
4
4
 
5
+ **Keywords:** endpoint, server-side handler, call from UI, callEndpoint, Handle, Plan, Respond, requestSchema, responseSchema, actions, visibility, external endpoint, scope, LLM from a UI
6
+
5
7
  ## The model
6
8
 
7
9
  ### Why endpoints exist
@@ -120,7 +122,7 @@ The handler receives:
120
122
  - `context`: the capabilities listed in `reads` and `writes`, and nothing else. On a session-scoped endpoint, only the shared ones (see above)
121
123
  - `team`: on a team-scoped endpoint, the team the call acts on. `teams`: on a session-scoped one, every team's declared values
122
124
  - `settings`: exactly the settings resources listed in `settings`, keyed by identifier, read-only
123
- - `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset` and `getPastState`. An undeclared gated callback throws
125
+ - `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset`, `describeAsset` and `getPastState`. An undeclared gated callback throws
124
126
  - `caller`: who is calling, issued by the host and never by the iframe (see below)
125
127
  - `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind`, `meta.now`, the instant the call started, and `meta.scenarioName`, the active scenario's name for display
126
128
  - `participants`: a read-only copy of the roster the call covers, the addressed team's on a team-scoped endpoint and every participant on a session-scoped one
@@ -284,7 +286,7 @@ A request field can be a file. Mark a string property with `blob`, saying which
284
286
  }
285
287
  ```
286
288
 
287
- The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
289
+ The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, asks its size with `callbacks.describeAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
288
290
 
289
291
  The caller sends one of two things:
290
292
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
4
4
 
5
+ **Keywords:** engine testing, createTestSession, in-process test, test a whole game, Vitest, stubbed callbacks, ticks in tests, test endpoints, test hooks, GameRunner, CI
6
+
5
7
  ## What is createTestSession?
6
8
 
7
9
  `createTestSession` starts the session the dev server runs, inside your test process. Everything a game does is there: `Init` and `Run`, hooks when somebody joins, validators on a participant's write, endpoints, undo, independent teams ticking on their own, the configuration step, and automatic ticks. You drive it with the same commands the console, the CLI and your surfaces send, and read it with the same state `sdk view --full` prints.
@@ -270,10 +272,12 @@ By default the session resolves the game's default scenario when one is declared
270
272
  // A specific scenario (it must be listed in the game's `scenarios`)
271
273
  await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: 'easy_mode' });
272
274
 
273
- // Or opt out of the default scenario and test the settings defaults
275
+ // Or, in a game with no default scenario, test the settings defaults
274
276
  await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: null });
275
277
  ```
276
278
 
279
+ A game that marks a default scenario never runs on none, so `scenarioId: null` is refused for it, naming the default. Pin one of its scenarios instead.
280
+
277
281
  ### The configuration step
278
282
 
279
283
  A game with a `setup` slot starts at its configuration step. `createTestSession` presses Play for you, so a tick has a game to run. Pass `play: false` to test the step itself, then send `updateSettings` (keyed by settings identifier, for example `{ type: 'updateSettings', payload: { engine: { BaseDemand: 200 } } }`) and `play` as the setup screen would. Settings are fixed from Play onwards, so `state().settings` after `play` is what every tick reads.
@@ -286,7 +290,7 @@ Tests are offline by default, whether they run a whole session or call one logic
286
290
  - **`generateSpeech`** stores 100ms of silence as a WAV blob and returns `{ reference: 'blob:<id>', mimeType: 'audio/wav', durationMs: 100, charactersBilled: 0 }`, so `readAsset` resolves it as it would real audio
287
291
  - **`extractText`** answers `{ content: '[stub] text of <reference>', mimeType: 'text/plain' }`, without reading the file
288
292
 
289
- With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), and `getPastState` answers `[]`.
293
+ With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), `describeAsset` describes only such a blob (and answers `undefined` for anything else), and `getPastState` answers `[]`.
290
294
 
291
295
  | Export | From | Use it to |
292
296
  | --------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
@@ -4,6 +4,8 @@ The engine is the logic that moves your game forward: it sets up the board, then
4
4
 
5
5
  This guide explains how an engine is shaped and why, then covers everything you write in one.
6
6
 
7
+ **Keywords:** engine, game logic, simulation, Init, Run, tick, reads, writes, settings, return capabilities, deletes, end the game, aggregate engine, randomness, language environment
8
+
7
9
  ## The model
8
10
 
9
11
  A game holds one engine, in the `engine/` slot. It: