@seriousgaming/sdk-tools 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/dist/cli.js +830 -99
  2. package/dist/client.js +114 -11
  3. package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-BVF8exas.js} +21 -21
  4. package/dist/dev/console/index.html +1 -1
  5. package/dist/dev/public-origins.d.ts +61 -0
  6. package/dist/dev/shell.d.ts +32 -4
  7. package/dist/docs/ai-agents.md +5 -0
  8. package/dist/docs/changelog-0.x.md +2 -2
  9. package/dist/docs/changelog.md +37 -4
  10. package/dist/docs/cli-and-dev-server.md +58 -0
  11. package/dist/docs/cli-error-codes.md +39 -36
  12. package/dist/docs/cli-reference.md +68 -21
  13. package/dist/docs/environment-variables.md +10 -5
  14. package/dist/docs/guides/ai-facilitation.md +2 -0
  15. package/dist/docs/guides/capabilities.md +2 -0
  16. package/dist/docs/guides/designing-a-game.md +2 -0
  17. package/dist/docs/guides/designing-screens.md +133 -0
  18. package/dist/docs/guides/endpoints.md +2 -0
  19. package/dist/docs/guides/engine-testing.md +5 -1
  20. package/dist/docs/guides/engine.md +2 -0
  21. package/dist/docs/guides/file-handling.md +3 -1
  22. package/dist/docs/guides/games.md +3 -1
  23. package/dist/docs/guides/global-settings.md +2 -0
  24. package/dist/docs/guides/guide.md +2 -0
  25. package/dist/docs/guides/hooks.md +2 -0
  26. package/dist/docs/guides/index.md +9 -0
  27. package/dist/docs/guides/internationalization.md +2 -0
  28. package/dist/docs/guides/llm-integration.md +4 -2
  29. package/dist/docs/guides/multi-team-games.md +3 -1
  30. package/dist/docs/guides/patterns.md +2 -0
  31. package/dist/docs/guides/presentation.md +1 -1
  32. package/dist/docs/guides/production-constraints.md +2 -0
  33. package/dist/docs/guides/scenario-editor.md +2 -0
  34. package/dist/docs/guides/scenarios.md +6 -2
  35. package/dist/docs/guides/session-game-flow.md +365 -0
  36. package/dist/docs/guides/session-hooks.md +205 -0
  37. package/dist/docs/guides/session.md +27 -565
  38. package/dist/docs/guides/settings.md +2 -0
  39. package/dist/docs/guides/setup.md +3 -1
  40. package/dist/docs/guides/speech-generation.md +2 -0
  41. package/dist/docs/guides/starter-game.md +61 -21
  42. package/dist/docs/guides/testing.md +2 -0
  43. package/dist/docs/guides/tick-controller.md +3 -1
  44. package/dist/docs/guides/type-safety.md +2 -0
  45. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  46. package/dist/docs/guides/ui-participants.md +281 -0
  47. package/dist/docs/guides/ui-styling.md +263 -0
  48. package/dist/docs/guides/ui-ticks.md +247 -0
  49. package/dist/docs/guides/ui.md +11 -1092
  50. package/dist/docs/guides/upgrading.md +2 -0
  51. package/dist/docs/guides/validators.md +2 -0
  52. package/dist/docs/guides/waiting-room.md +1 -1
  53. package/dist/docs/index.md +2 -1
  54. package/dist/docs/page-index.md +145 -0
  55. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  56. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  57. package/dist/docs/recipes/create-presentation.md +11 -0
  58. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  59. package/dist/docs/recipes/create-session-ui.md +2 -1
  60. package/dist/docs/recipes/create-setup.md +1 -0
  61. package/dist/docs/recipes/create-user-interface.md +1 -0
  62. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  63. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  64. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  65. package/dist/docs/recipes/index.md +3 -0
  66. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  67. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  68. package/dist/docs/recipes/use-request-tick.md +2 -2
  69. package/dist/execution/config-resolver.d.ts +4 -1
  70. package/dist/runtime/manifest-version.d.ts +1 -1
  71. package/dist/runtime.js +1 -1
  72. package/dist/templates/package/CLAUDE.md.template +14 -5
  73. package/dist/templates/package/DESIGN.md.liquid +39 -7
  74. package/dist/templates/package/README.md.liquid +1 -1
  75. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  76. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  77. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  78. package/dist/templates/starter-game/package.json +2 -0
  79. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  80. package/dist/templates/starter-game/presentation/index.html +20 -0
  81. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  82. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  83. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  84. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  85. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  86. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  87. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  88. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  89. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  90. package/dist/templates/starter-game/presentation/types.ts +94 -0
  91. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  92. package/dist/templates/starter-game/session/defaults.ts +6 -0
  93. package/dist/templates/starter-game/session/index.html +1 -1
  94. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  95. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  96. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  97. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  98. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  99. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  100. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  101. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  102. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  103. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  104. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  105. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  106. package/dist/templates/starter-game/session/src/status.ts +28 -0
  107. package/dist/templates/starter-game/session/types.ts +8 -2
  108. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  109. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  110. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  111. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  112. package/dist/templates/starter-game/shared/days.ts +11 -0
  113. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  114. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  115. package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
  116. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  117. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  118. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  119. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  120. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  121. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  122. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  123. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  124. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  125. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  126. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  127. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  128. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  129. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  130. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  131. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  132. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  133. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  134. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  135. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  136. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  137. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  138. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  139. package/dist/templates/starter-game/ui/types.ts +6 -0
  140. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  141. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  142. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  143. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  144. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  145. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  146. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  147. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  148. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  149. package/dist/utils/error-codes.d.ts +12 -0
  150. package/package.json +11 -4
  151. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  152. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  153. package/dist/templates/starter-game/session/src/format.ts +0 -8
  154. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  155. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  156. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  157. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
@@ -5,7 +5,7 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
7
7
  <title>Serious Gaming</title>
8
- <script type="module" crossorigin src="/assets/index-BvB-LFQZ.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-BVF8exas.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -0,0 +1,61 @@
1
+ /**
2
+ * The addresses a dev server behind a proxy is reached at (#788).
3
+ *
4
+ * The server otherwise names itself from the request: `http://`, the `Host`
5
+ * the browser sent, and the asset or hot-reload port in place of its own. A
6
+ * gateway that serves each origin on its own HTTPS hostname breaks every one
7
+ * of those guesses, so a server behind one is told its addresses instead.
8
+ */
9
+ export declare const PUBLIC_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_URL";
10
+ export declare const PUBLIC_ASSET_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_ASSET_URL";
11
+ export declare const PUBLIC_HMR_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_HMR_URL";
12
+ /** The origins as given, each already parsed by {@link parsePublicOrigin}. */
13
+ export interface PublicOrigins {
14
+ /** The console, its API and every link a participant is handed. */
15
+ publicUrl?: string;
16
+ /** Game bundles and the files a frame reads. */
17
+ publicAssetUrl?: string;
18
+ /** Vite's hot-reload socket, as `ws:` or `wss:`. */
19
+ publicHmrUrl?: string;
20
+ }
21
+ /**
22
+ * An origin from a flag or an environment variable, normalised.
23
+ *
24
+ * Only an origin: a path would suggest the server can be mounted under one,
25
+ * and it cannot, since every route it serves is absolute.
26
+ *
27
+ * @throws {CliError} when the value is not an origin of the kind `flag` takes.
28
+ */
29
+ export declare function parsePublicOrigin(value: string, flag: string, kind: 'http' | 'ws'): string;
30
+ /**
31
+ * The public origins for `sdk dev`: each flag, else its environment variable,
32
+ * parsed. Unset where neither gives one.
33
+ *
34
+ * @throws {CliError} when a value is not an origin.
35
+ */
36
+ export declare function resolvePublicOrigins(flags: {
37
+ publicUrl?: string;
38
+ publicAssetUrl?: string;
39
+ publicHmrUrl?: string;
40
+ }, env?: NodeJS.ProcessEnv): PublicOrigins;
41
+ /**
42
+ * The asset origin: as given, else the public console's scheme and host on
43
+ * the asset port, which is what a proxy forwarding each port as it is serves.
44
+ * Null when neither is given, so the server goes on naming it from the request.
45
+ */
46
+ export declare function publicAssetOrigin(origins: PublicOrigins, assetPort: number): string | null;
47
+ /**
48
+ * Where a frame's hot-reload client connects: as given, else the asset
49
+ * origin's host on the Vite port, over `wss:` when the asset origin is HTTPS.
50
+ * That default is where Vite's client connects when told nothing, so it
51
+ * changes only the scheme and the name. Null when no public origin is given.
52
+ */
53
+ export declare function publicHmrOrigin(origins: PublicOrigins, assetPort: number, vitePort: number): string | null;
54
+ /** What Vite's client is told to connect to, from a `ws:` or `wss:` origin. */
55
+ export declare function hmrClientTarget(origin: string): {
56
+ protocol: 'ws' | 'wss';
57
+ host: string;
58
+ clientPort: number;
59
+ };
60
+ /** The hostnames a public origin names, which Vite must accept in a `Host` header. */
61
+ export declare function publicHostnames(origins: (string | null | undefined)[]): string[];
@@ -18,7 +18,14 @@ import type { RunKind } from '@seriousgaming/sdk';
18
18
  import type { MutationResult } from '@seriousgaming/sdk/projection';
19
19
  import type { Command } from '../core/protocol';
20
20
  import { Session, type SessionOptions } from '../core/session';
21
- export interface ShellOptions extends SessionOptions {
21
+ import { type PublicOrigins } from './public-origins';
22
+ /**
23
+ * `publicUrl`, `publicAssetUrl` and `publicHmrUrl` are the addresses a server
24
+ * behind a proxy is reached at (#788), each an origin as
25
+ * `parsePublicOrigin` leaves it. Unset, every address is named from the
26
+ * request that asked for it.
27
+ */
28
+ export interface ShellOptions extends SessionOptions, PublicOrigins {
22
29
  port?: number;
23
30
  /** Port the Vite HMR socket binds to. Defaults to `port + 1`. */
24
31
  vitePort?: number;
@@ -108,6 +115,8 @@ export declare class DevShell {
108
115
  private viteFailure;
109
116
  /** Serialises the first requests for a surface so they share one Vite. */
110
117
  private viteStarting;
118
+ /** The hot-reload socket's own listener, when a public origin moves its client. */
119
+ private hmrServer;
111
120
  private port;
112
121
  private vitePort;
113
122
  private assetPort;
@@ -171,14 +180,23 @@ export declare class DevShell {
171
180
  get url(): string;
172
181
  /** Where bundles are served from, once listening. */
173
182
  get assetUrl(): string;
183
+ /** Where people reach the console, when a proxy stands in front of it. */
184
+ get publicUrl(): string | null;
185
+ /** Where people's browsers load bundles from, when a proxy stands in front. */
186
+ get publicAssetUrl(): string | null;
174
187
  /**
175
- * The asset origin as a client that reached `host` must name it: the same
176
- * host, the asset port. A browser on another machine reached us by an
177
- * address `localhost` would not resolve to on its side.
188
+ * The asset origin as a client that reached `host` must name it: the
189
+ * public one where given, else the same host on the asset port. A browser
190
+ * on another machine reached us by an address `localhost` would not
191
+ * resolve to on its side.
178
192
  */
179
193
  assetOrigin(host: string | undefined): string;
180
194
  /** The console's own origin, as a client that reached `host` names it. */
181
195
  private consoleOrigin;
196
+ /** Where a frame's hot-reload client connects, when a public origin decides it. */
197
+ private get publicHmrUrl();
198
+ /** What the bundle policy's `connect-src` admits for hot reload. */
199
+ private hmrSources;
182
200
  /** The session this shell wraps, for tests and for the CLI in-process path. */
183
201
  get runtime(): Session;
184
202
  /**
@@ -222,6 +240,16 @@ export declare class DevShell {
222
240
  */
223
241
  private ensureVite;
224
242
  private createVite;
243
+ /**
244
+ * Vite's server options: its own hot-reload socket on the Vite port, as
245
+ * before, unless a public origin says where the client connects.
246
+ *
247
+ * Vite takes one `host` for both where its socket listens and where its
248
+ * client connects, and a public hostname is no address to listen on. So
249
+ * behind a proxy the socket's listener is opened here, on the Vite port
250
+ * as usual, and Vite only attaches to it.
251
+ */
252
+ private viteServerOptions;
225
253
  private attachSockets;
226
254
  private receive;
227
255
  /** What one viewer page is owed, now. */
@@ -14,10 +14,15 @@ The site describes the newest release. Inside a package, read the docs that ship
14
14
 
15
15
  ```bash
16
16
  pnpm run --silent sdk docs view # the documentation tree
17
+ pnpm run --silent sdk docs view page-index.md # every page: summary and length
17
18
  pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
19
+ pnpm run --silent sdk docs view guides/ui.md --outline # the headings of a page, with section lengths
20
+ pnpm run --silent sdk docs view guides/ui.md --section 'Writing to context' # one section
18
21
  pnpm run sdk docs export # copy every page into the package, to search with grep
19
22
  ```
20
23
 
24
+ Some guides run past 50,000 characters. Rather than reading one whole, find it in the [page index](./page-index.md), list its headings with `--outline`, and read the section you need with `--section`, which takes a heading's text or the slug the outline prints. Every guide and recipe carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right page.
25
+
21
26
  On the site, [llms.txt](https://sdk.seriousgaming.com/llms.txt) lists every page, [llms-small.txt](https://sdk.seriousgaming.com/llms-small.txt) holds the core pages in one file, and [llms-full.txt](https://sdk.seriousgaming.com/llms-full.txt) holds them all. Start from a recipe for a task and from a guide for a whole subject.
22
27
 
23
28
  ## 1. Scaffold without a prompt
@@ -563,8 +563,8 @@ Work through step 5 of the upgrade guide: it gives the five in order, with the e
563
563
  ### Added
564
564
 
565
565
  - A scenario can configure the session user interface, through a `sessionUserInterfaces` bucket in its `configuration` alongside `modules` and `userInterfaces`. The surface's configuration now resolves through all four layers like any other resource: schema defaults, the game's `sessionUserInterface` reference, the active scenario, then the centralized layer. Session UIs get their own bucket rather than sharing `userInterfaces`, so a player UI and a session UI may carry the same identifier without crossing. See the [session UI guide](guides/session.md#configuring-the-surface)
566
- - A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session.md#opening-host-overlays)
567
- - `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session.md#extending-a-tick)
566
+ - A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session-game-flow.md#opening-host-overlays)
567
+ - `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session-game-flow.md#extending-a-tick)
568
568
  - The dev server serves team print sheets at `/print-sheets`, one card per team with its join and observe URLs behind a print stylesheet. Print every team from the session menu, or one team from its card's own menu; a session UI reaches both through `openHostOverlay('print-sheets', teamId?)`. The sheets carry no QR code and no PIN, because the dev server has neither; a production host prints both
569
569
  - A game can start its sessions with the waiting room already open, by setting `"openOnStart": true` on its `waitingRoom` reference. Without it the room is closed at the start, so the first player to follow a join link lands in the game rather than the holding screen unless the facilitator opened the room first. It seeds the session and nothing more: the facilitator owns the flag from then on, a reset does not re-park the session, and a dev server restart restores the flag the session was left with. Available to a game that authors its own waiting room UI. See the [waiting room guide](guides/waiting-room.md#starting-held)
570
570
  - `new`, `update` and `delete` accept `-j, --json`, matching every other command in the CLI. The envelope names the command, the resource type, the identifier, and every file, reference and directory the operation touched; a failure reports the same shape with `"success": false` and an `error`, and exits non-zero. Because prompts cannot produce JSON, `new` and `update` need a definition or a `--patch` under the flag, and `delete` needs `--force`. See the [CLI reference](cli-reference.md#json-output)
@@ -31,6 +31,39 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.5.0] — 2026-10-29
35
+
36
+ ### Added
37
+
38
+ - **`sdk dev` can run behind a proxy or gateway.** `--public-url`, `--public-asset-url` and `--public-hmr-url` (or `SERIOUSGAMING_DEV_PUBLIC_URL`, `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` and `SERIOUSGAMING_DEV_PUBLIC_HMR_URL`) name the addresses people reach it at, and every link and origin the server hands out uses them, where join links used to read `http://localhost:<port>`. With none set, nothing changes. See [Embedding the dev server](cli-and-dev-server.md#embedding-the-dev-server)
39
+ - **A page framing the dev console can set its colour scheme and brand.** Open it with `?scheme=light|dark|system` or `?brand=<id>`, or post `{ type: 'sg-dev-scheme', scheme }` to the frame to change the scheme without a reload. Neither overwrites the viewer's own stored choice, and the scheme reaches the game's surfaces as the dev drawer's does
40
+ - **The starter game has a presentation.** `new package` now writes Lemonade Stand with a `presentation/` slot: a title slide, a slide for each day with the forecast and how the room did the day before, and a results slide for the room. It shows the room rather than any stall by name, with each stall's figures in the speaker notes, renders with no session, and tests its figures as plain functions. See [A tour of the starter game](guides/starter-game.md#presentation)
41
+ - **A guide to designing screens.** [Designing screens](guides/designing-screens.md) sets out what a good simulation screen looks like whatever the brand: one main action, a spacing and type scale, a design for the phone, laptop or projector it is used on, every state from empty to end of game, feedback on a refused write, accessibility, and an identity of the game's own over the host's theme. New packages put it to work: `DESIGN.md.liquid` replaces the 'User interfaces' prompts with a screen brief (who plays and on what, tone, key screens and each one's main action, layout, states and identity), and `CLAUDE.md.template` asks for the brief before a surface is built and a check at phone and desktop size after. An existing package can copy both sections from the templates shipped in `@seriousgaming/sdk-tools`
42
+ - **Read a long page a section at a time.** `pnpm run sdk docs view <page> --outline` lists a page's headings, each with its slug and its section's length in characters, and `--section <heading>` prints only that section, named by its text or its slug. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the ones the page has. The installed docs gain `page-index.md`, every page with a one-sentence summary and its length, and every guide now carries a `**Keywords:**` line for `grep`. A new package's `CLAUDE.md` (`CLAUDE.md.template`) points to all three; merge its Documentation section into an existing package's. See [Read the docs for the installed version](ai-agents.md#read-the-docs-for-the-installed-version)
43
+ - **`pnpm run sdk screenshot <path>` captures a surface as a PNG**, as a participant sees it, once the surface reports its first paint rather than after a fixed delay. `--width` and `--height` set the viewport, `--scheme`, `--brand` and `--locale` what it shows, and `--full-page` its whole height; `--json` also lists the page's console errors, failed requests and uncaught exceptions, from inside the surface's frame too. It uses the running dev server, or starts one for the capture and stops it after. It drives the game's own Playwright, an optional peer of `@seriousgaming/sdk-tools` that every scaffolded game already has: without it, or without its Chromium, it fails with `BROWSER_MISSING`, and a surface that never renders fails with `SURFACE_NOT_RENDERED`. The starter's `CLAUDE.md.template` now tells agents to screenshot each screen at phone and desktop size. See [Screenshot a surface](recipes/screenshot-a-surface.md)
44
+
45
+ ### Changed
46
+
47
+ - **A new game installs under a seven-day release-age policy.** `pnpm run sdk new package` writes `minimumReleaseAge: 10080` into the game's `pnpm-workspace.yaml`, the policy the SDK itself builds under, so pnpm refuses any dependency published in the last week and picks the newest older release in its range instead. The SDK's own packages (`@seriousgaming/*`) are exempt, so a game scaffolded on the day of an SDK release still installs. An existing game is unchanged: to opt in, copy `minimumReleaseAge` and `minimumReleaseAgeExclude`, with their comment, from the scaffold template `templates/package/pnpm-workspace.yaml.template` in the installed `@seriousgaming/sdk-tools` into your `pnpm-workspace.yaml`
48
+ - **A game with a default scenario always runs on a scenario.** Asking for none, with `pnpm run sdk scenario none`, `createTestSession({ scenarioId: null })` or a hosted runtime's equivalent, is refused with an error naming the default, where it used to run the game on its settings defaults alone, and the dev drawer's **Scenario** tab offers **None** only to a game with no default. If an engine test passes `scenarioId: null` to a game with a default, pin one of its scenarios instead. A game with no default runs on none as before. See [Scenarios](guides/scenarios.md)
49
+ - **The user interface and session UI guides are split into topic pages.** [Building user interfaces](guides/ui.md) and [Building session UIs](guides/session.md) keep their paths as entry pages that link to the rest: participants, ticks and the timer, styling, and files and LLMs for a game UI; running the game and the hooks reference for a session UI. A link to a section that moved needs its new page. The `docs view --section` examples in `CLAUDE.md.template` and the hook pointer in `workflow-create-user-interface.md` follow the new pages
50
+
51
+ - **The starter game's screens are redesigned to the [Designing screens](guides/designing-screens.md) guide.** A game made with `new package` now:
52
+ - Leads each participant screen with the day's decision, with the button that opens the stall in a bar at the foot of the layout and a timeline for looking back at earlier days
53
+ - Gives the facilitator one line of session controls, a card per stall, a side panel with no backdrop for managing one, results for the room, and join links in large type for the room to read
54
+ - Lets the facilitator hold the room at a day: a shared `pacing` capability, enforced by a `RequestTick` gate in `validators/daylimit`
55
+ - Takes its icons from `@mui/icons-material`, keeps its one drawn motif (the awning) and the host's logo in a new `shared/` folder, and lists `presentation-overlay` in `requires`, so the facilitator can open the slides from their screen
56
+
57
+ An existing game is unchanged. See [A tour of the starter game](guides/starter-game.md)
58
+
59
+ ### Fixed
60
+
61
+ - **The starter game's facilitator screen shows the purse in pounds.** Lemonade Stand holds money in pence, and its session screen showed a purse of 2,200 pence as '£2,200' where the player's screen showed '£22.00'. A game made from an earlier starter can copy `money` from `ui/src/format.ts` into `session/src/format.ts`; the new starter keeps one copy, in `shared/format.ts`
62
+
63
+ ### Security
64
+
65
+ - **The `fast-uri` advisories are cleared.** The SDK's lockfile now takes `fast-uri` 3.1.9 through `ajv`. `body-parser` 2.4.0, through `express` in the dev server, clears the seven-day gate later on 29 October and is taken by the next release; a game's own install already resolves it once it is old enough
66
+
34
67
  ## [1.4.0] — 2026-10-26
35
68
 
36
69
  ### Added
@@ -60,9 +93,9 @@ are in the [0.x changelog](changelog-0.x.md).
60
93
 
61
94
  ### Added
62
95
 
63
- - **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session.md#opening-host-overlays)
64
- - **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session.md#changing-the-language)
65
- - **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui.md#letting-a-participant-fix-their-own-name)
96
+ - **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session-game-flow.md#opening-host-overlays)
97
+ - **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session-game-flow.md#changing-the-language)
98
+ - **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui-participants.md#letting-a-participant-fix-their-own-name)
66
99
  - **A deck can show the room how to join.** A presentation's `session` carries every team's `participants`, a `joinLinks` entry per team and the session's `joinPin`, so a slide can put the join links on the projector and count who has arrived. See [Showing the room how to join](guides/presentation.md#showing-the-room-how-to-join)
67
100
  - **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
68
101
 
@@ -260,7 +293,7 @@ are in the [0.x changelog](changelog-0.x.md).
260
293
  - **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
261
294
  - **Typed session writes and test fixtures.** A session UI's generated `types.ts` adds `TeamWrites`, the team-scope capabilities in its `writes`, and `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` types the per-team `setData(teamId, update)` with it, so a team write naming a shared capability fails to compile. `createMockTeamState<TeamContext>`, `createMockSharedState<SharedContext>` and `renderSessionUserInterface<SessionData>` type a test's fixtures the same way. Every parameter defaults to today's untyped form, so existing code compiles unchanged. See [Session UIs](guides/testing.md#session-uis)
262
295
  - **A session UI can delete keys.** Both forms of a session surface's `setData` take `{ deletes }` last, as a player surface's does: `setData(teamId, {}, { deletes })` removes from one team and `setData({}, { deletes })` from the shared store. Each path must fall under a capability the surface writes, of the form's scope, or the write is refused as `denied`. `mergingSetData` in `@seriousgaming/sdk/ui/testing` takes the same options and applies them after the merge, as the host does. See [Removing a key](guides/session.md#removing-a-key)
263
- - **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session.md#deleting-a-team)
296
+ - **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session-game-flow.md#deleting-a-team)
264
297
  - **`pauseTimer` and `resumeTimer` are awaitable**, resolving once the host has applied the change and rejecting with a `MutationError` when it refuses
265
298
  - **Every past-state entry carries `index` and `name`**, and the mode-colour theme types (`UserInterfaceModeColors` and siblings) are exported
266
299
 
@@ -80,6 +80,64 @@ can move it to any corner (remembered per browser).
80
80
  Everything the drawer does, the CLI does too, because both send the same
81
81
  commands.
82
82
 
83
+ ## Embedding the dev server
84
+
85
+ On your own machine, the server works out every address it hands out from the
86
+ request: the host your browser used, `http://`, and its own ports. Behind a
87
+ proxy or gateway, such as a sandbox that serves the console on an HTTPS
88
+ hostname and shows it in a frame, those addresses come out wrong, and join
89
+ links read `http://localhost:47100/team/1/join`. Tell the server where it is
90
+ reached instead:
91
+
92
+ ```bash
93
+ pnpm run sdk dev --no-open \
94
+ --public-url https://console.example.com \
95
+ --public-asset-url https://assets.example.com \
96
+ --public-hmr-url wss://hmr.example.com
97
+ ```
98
+
99
+ | Option | Environment variable | What it names | Default when unset |
100
+ | -------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
101
+ | `--public-url` | `SERIOUSGAMING_DEV_PUBLIC_URL` | The console, its API, and every link it hands out | The request's host |
102
+ | `--public-asset-url` | `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | Where browsers load game surfaces and their files | The `--public-url` host on the asset port, else the request's host |
103
+ | `--public-hmr-url` | `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | Where a surface's hot-reload client connects | The public asset host on the Vite port, `wss://` when that host is HTTPS |
104
+
105
+ Each takes an origin only: a scheme, a host and, where it is not the default,
106
+ a port, with no path. The asset origin must differ from the console's, as it
107
+ does in production, so a game's code cannot call the console's API. A gateway
108
+ that serves each port on its own hostname needs all three set; one that keeps
109
+ the ports and adds TLS needs only `--public-url`. With none set, nothing
110
+ changes.
111
+
112
+ The server still listens on the ports it prints, so point the gateway at those:
113
+ the console's port, the asset port, and the Vite port for hot reload.
114
+
115
+ ### Colour scheme and brand
116
+
117
+ The console keeps its colour scheme and brand in its own browser storage,
118
+ which a page on another origin cannot write. So the framing page says what it
119
+ wants in the console's URL:
120
+
121
+ - `?scheme=light`, `?scheme=dark` or `?scheme=system`: the colour scheme
122
+ - `?brand=<id>`: one of the brands the server offers, by the identifier its
123
+ **Brand** menu shows
124
+
125
+ Both apply from the first paint, last for the rest of that tab as the console
126
+ moves between its own pages, and never overwrite the viewer's stored choice.
127
+ Picking a scheme or brand in the dev drawer takes over from them. The scheme
128
+ reaches the game's surfaces exactly as the drawer's own scheme menu does.
129
+
130
+ To change the scheme later without a reload, post a message to the frame:
131
+
132
+ ```ts
133
+ frame.contentWindow?.postMessage({ type: 'sg-dev-scheme', scheme: 'dark' }, consoleOrigin);
134
+ ```
135
+
136
+ The console acts on it only when it is framed, and only from the page directly
137
+ around it. It does not check that page's origin, so any page that frames the
138
+ console can change its scheme: harmless for a colour scheme, and the reason the
139
+ message carries nothing else.
140
+
83
141
  ## How a command finds the session
84
142
 
85
143
  `.seriousgaming-sdk/session.json` is a **lock file**, not state:
@@ -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