@seriousgaming/sdk-tools 1.2.0 → 1.4.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 (50) hide show
  1. package/dist/cli.js +3582 -2834
  2. package/dist/client.js +1145 -543
  3. package/dist/core/participant-registry.d.ts +6 -0
  4. package/dist/core/session-host.d.ts +4 -2
  5. package/dist/core/session-roster.d.ts +4 -1
  6. package/dist/core/settings-locks.d.ts +27 -2
  7. package/dist/dev/console/assets/{index-BNLEVOQA.js → index-BvB-LFQZ.js} +47 -47
  8. package/dist/dev/console/index.html +1 -1
  9. package/dist/dev/routes.d.ts +4 -0
  10. package/dist/dev/view/batch.d.ts +24 -10
  11. package/dist/dev/view/view.d.ts +2 -1
  12. package/dist/docs/api/index.md +2 -2
  13. package/dist/docs/api/sdk-commands.md +4 -0
  14. package/dist/docs/api/sdk-e2e.md +4 -0
  15. package/dist/docs/api/sdk-tools-client.md +5 -0
  16. package/dist/docs/api/sdk-ui-testing.md +1 -0
  17. package/dist/docs/api/sdk-ui.md +33 -1
  18. package/dist/docs/api/sdk.md +82 -3
  19. package/dist/docs/changelog.md +41 -0
  20. package/dist/docs/concepts/terminology.md +1 -1
  21. package/dist/docs/guides/capabilities.md +2 -0
  22. package/dist/docs/guides/endpoints.md +2 -2
  23. package/dist/docs/guides/engine-testing.md +1 -1
  24. package/dist/docs/guides/file-handling.md +113 -21
  25. package/dist/docs/guides/llm-integration.md +1 -1
  26. package/dist/docs/guides/presentation.md +23 -9
  27. package/dist/docs/guides/scenario-editor.md +1 -1
  28. package/dist/docs/guides/scenarios.md +9 -1
  29. package/dist/docs/guides/session.md +47 -8
  30. package/dist/docs/guides/settings.md +62 -2
  31. package/dist/docs/guides/testing.md +9 -0
  32. package/dist/docs/guides/ui.md +33 -0
  33. package/dist/docs/guides/upgrading.md +11 -0
  34. package/dist/docs/guides/validators.md +62 -4
  35. package/dist/docs/guides/waiting-room.md +2 -0
  36. package/dist/docs/recipes/upload-and-display-files.md +7 -7
  37. package/dist/docs/recipes/validate-scenarios.md +4 -1
  38. package/dist/execution/endpoint-runner.d.ts +6 -0
  39. package/dist/execution/logic-calls.d.ts +7 -2
  40. package/dist/execution/scenario-gates.d.ts +21 -1
  41. package/dist/guide/settings.d.ts +1 -1
  42. package/dist/host/protocol.d.ts +27 -2
  43. package/dist/host.js +64 -2
  44. package/dist/runtime/manifest-version.d.ts +1 -1
  45. package/dist/runtime.js +9 -2
  46. package/dist/storage/asset-resolver.d.ts +24 -1
  47. package/dist/storage/blob-store.d.ts +7 -0
  48. package/dist/utils/local-refs.d.ts +40 -0
  49. package/dist/utils/schema-members.d.ts +19 -0
  50. package/package.json +3 -3
@@ -30,6 +30,7 @@ Every callback that works on a file takes a reference:
30
30
 
31
31
  - **`getAssetUrl(reference)`** returns a URL the browser can fetch, for `<img>`, `<embed>`, `<video>` and the like. Synchronous, and in a UI only. In a hosted runtime the URL is on the runtime's asset host, cross-origin to the surface's iframe. `useAssetUrl` is the hook form
32
32
  - **`readAsset(reference)`** returns the bytes, MIME type, and display name. Asynchronous. In logic the runtime resolves the reference server-side; in a UI the SDK fetches the URL with `credentials: 'include'`. `useAsset` is the hook form that reads text, JSON, or a `Blob`
33
+ - **`describeAsset(reference)`** returns the MIME type and size of a file without reading it, or `undefined` when there is no such file. In logic only: a UI can ask its URL with a `HEAD` request
33
34
  - **`extractText(reference)`** returns plain text from a PDF. It is offered to the engine, hooks, tick controllers, and endpoints that declare it in `uses`; a UI reaches it through an endpoint
34
35
 
35
36
  In a UI, `getAssetUrl` strips the prefix and appends the rest to an absolute prefix the host supplies for each scheme. Under `sdk dev` those prefixes are on the asset origin (`--asset-port`), so `asset:shared/hero.jpg` becomes `http://localhost:<asset-port>/assets/scenario/shared/hero.jpg`; a hosted runtime points them at its own asset host. With no scenario active an `asset:` reference still produces a URL, which answers 404. A string with none of the three prefixes throws.
@@ -53,6 +54,44 @@ A scenario writes references with the prefix in place, usually as values of sett
53
54
 
54
55
  Here `briefing` is a settings resource (`settings/briefing/`) declaring `Logo` and `ScenarioBrief` as strings with an empty default, which the engine and UI examples below list in their `settings`. The runtime takes these strings as they are: nothing checks at scenario load that the file exists, and a reference that does not resolve fails when something calls `getAssetUrl`, `readAsset`, or `extractText` with it. See [Scenarios](./scenarios.md#2-add-assets-optional) for where the files go.
55
56
 
57
+ ### A file per language
58
+
59
+ A file setting (see [Settings that hold a file](./settings.md#settings-that-hold-a-file)) holds one file. For a document translated per language, key a map by locale and let its entries hold the files: the `blob` declaration goes on the map's `additionalProperties`, so every entry is checked as a file setting of its own:
60
+
61
+ ```json
62
+ "Brief": {
63
+ "title": "Briefing document",
64
+ "description": "The briefing as a PDF, one per language, keyed by locale. A language with no entry reads English",
65
+ "type": "object",
66
+ "default": {},
67
+ "propertyNames": { "enum": ["en", "fr"] },
68
+ "additionalProperties": {
69
+ "type": "string",
70
+ "blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
71
+ }
72
+ }
73
+ ```
74
+
75
+ A scenario sets one entry per language it ships:
76
+
77
+ ```json
78
+ "briefing": {
79
+ "Brief": { "en": "asset:brief.pdf", "fr": "asset:brief-fr.pdf" }
80
+ }
81
+ ```
82
+
83
+ The build checks every entry, as it checks a single file setting: each file must be shipped, within `maxBytes`, and of a type `accept` lists, and the error names the entry (`briefing.Brief.fr`). A setup screen, the scenario editor or an agent writing one entry is held to the same declaration, and a scenario may set one language and leave the others to the layer beneath, since a map merges key by key.
84
+
85
+ The game picks the entry for its locale, falling back to the one it always ships:
86
+
87
+ ```tsx
88
+ const { settings } = useUserInterfaceData<Context, Settings>();
89
+ const { locale } = useUserInterfaceLocale();
90
+ const src = useAssetUrl(settings.briefing.Brief[locale] ?? settings.briefing.Brief.en);
91
+ ```
92
+
93
+ Use this when a scenario chooses the files. A file the package ships for every scenario alike can instead sit in a directory named for its locale, which `useAsset` finds on its own (see [Internationalization](./internationalization.md)).
94
+
56
95
  ### How a file moves through a game
57
96
 
58
97
  ```
@@ -193,6 +232,28 @@ export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }
193
232
  - `data` is a `Uint8Array`. Use `decodeUtf8` for text formats; pass binary directly to downstream APIs
194
233
  - The same callback resolves `asset:shared/brief.pdf` and `blob:abc123`: there is no separate API for bundled and uploaded files
195
234
 
235
+ ## Checking a file without reading it
236
+
237
+ `readAsset` returns every byte, which is waste when you only need to know a file is there, or how big it is: a scenario's videos, say. `describeAsset` resolves a reference exactly as `readAsset` does and answers `{ mimeType, size }`, or `undefined` when there is no such file:
238
+
239
+ ```typescript
240
+ const video = await callbacks.describeAsset?.('asset:videos/intro.mp4');
241
+
242
+ if (video === undefined) {
243
+ // the scenario ships no intro video
244
+ } else if (video.size > 50_000_000) {
245
+ // too large to play in the room
246
+ }
247
+ ```
248
+
249
+ **Notes:**
250
+
251
+ - Like `readAsset`, it needs no `uses` entry: every engine, hook, tick controller, and endpoint has it
252
+ - It is optional in the type, so call it with `?.`: a runtime built before SDK 1.4 does not provide it, and a test that builds its callbacks by hand need not either. Pass your own `describeAsset` in such a test to exercise the code that uses it
253
+ - `mimeType` is what `readAsset` would report: the type a blob was stored with, or the type of a bundled file judged from its extension
254
+ - A reference with none of the three prefixes still throws: that is a mistake rather than a missing file
255
+ - A validator's `Scenario` gate can have it too, with `readAsset`, to check the files a scenario names. There `readAsset` reads no file over 10 MB, so use `describeAsset` to check a large file. See [Checking the files a scenario names](./validators.md#checking-the-files-a-scenario-names)
256
+
196
257
  ## Extracting text from a document
197
258
 
198
259
  Use the `extractText` callback to convert a document into plain text suitable for passing to an LLM. Available in the engine, hooks, tick controllers, and endpoints that declare `"extractText"` in `uses`. UIs reach it through an endpoint. Currently supports **PDF** files.
@@ -294,7 +355,7 @@ The field accepts two kinds of string, so the same endpoint serves every caller:
294
355
  - **A `blob:` reference** to a file already stored. A UI passes the reference `uploadBlob` returned, as in the example above; a script or an agent uploads first (locally, `POST /api/blobs` or `pnpm run sdk blob upload`)
295
356
  - **A `data:` URI** carrying the file inline, for a caller with no upload of its own: `data:application/pdf;name=brief.pdf;base64,...`. Up to 5 MB
296
357
 
297
- Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
358
+ A file field may also be the entries of a map, with `blob` on its `additionalProperties` or a `patternProperties` schema, and each entry is checked as a field of its own. Either way the handler receives a `blob:` reference, typed `` `blob:${string}` ``, that names a file of an accepted type, judged by its bytes, within the size. A URL, a wrong type or an oversized file is refused before the handler runs. Without `blob`, a field is a plain string the handler must check itself.
298
359
 
299
360
  See [Take a file in an endpoint](../recipes/take-a-file-in-an-endpoint.md).
300
361
 
@@ -358,26 +419,57 @@ pnpm run sdk patch \
358
419
  "[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
359
420
  ```
360
421
 
361
- ## Supported file types
362
-
363
- MIME types are detected from the file extension:
364
-
365
- | Extension | MIME type |
366
- | --------------- | -------------------------- |
367
- | `.pdf` | `application/pdf` |
368
- | `.png` | `image/png` |
369
- | `.jpg`, `.jpeg` | `image/jpeg` |
370
- | `.gif` | `image/gif` |
371
- | `.webp` | `image/webp` |
372
- | `.svg` | `image/svg+xml` |
373
- | `.mp4` | `video/mp4` |
374
- | `.webm` | `video/webm` |
375
- | `.mp3` | `audio/mpeg` |
376
- | `.wav` | `audio/wav` |
377
- | `.json` | `application/json` |
378
- | `.csv` | `text/csv` |
379
- | `.txt` | `text/plain` |
380
- | Other | `application/octet-stream` |
422
+ ## Media types
423
+
424
+ A package file's media type comes from its extension, compared without regard to case, by the table below. The build checks a file setting's `accept` against it, the dev server serves scenario and shared files under it, `readAsset` reports it, and so does every runtime, so a file the build accepted arrives as the type it was accepted as. An extension the table does not list is `application/octet-stream` everywhere: rename a file to a listed extension if a game or an `accept` depends on its type. A blob keeps the type it was uploaded with, whatever its name, and `sdk blob upload` takes it from the same table.
425
+
426
+ | Extension | Media type |
427
+ | ------------------ | --------------------------------------------------------------------------- |
428
+ | `.aac` | `audio/aac` |
429
+ | `.avif` | `image/avif` |
430
+ | `.bmp` | `image/bmp` |
431
+ | `.css` | `text/css` |
432
+ | `.csv` | `text/csv` |
433
+ | `.doc` | `application/msword` |
434
+ | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
435
+ | `.flac` | `audio/flac` |
436
+ | `.gif` | `image/gif` |
437
+ | `.htm`, `.html` | `text/html` |
438
+ | `.ico` | `image/x-icon` |
439
+ | `.jpeg`, `.jpg` | `image/jpeg` |
440
+ | `.js`, `.mjs` | `text/javascript` |
441
+ | `.json` | `application/json` |
442
+ | `.m4a` | `audio/mp4` |
443
+ | `.m4v`, `.mp4` | `video/mp4` |
444
+ | `.md` | `text/markdown` |
445
+ | `.mov` | `video/quicktime` |
446
+ | `.mp3` | `audio/mpeg` |
447
+ | `.odp` | `application/vnd.oasis.opendocument.presentation` |
448
+ | `.ods` | `application/vnd.oasis.opendocument.spreadsheet` |
449
+ | `.odt` | `application/vnd.oasis.opendocument.text` |
450
+ | `.ogg`, `.opus` | `audio/ogg` |
451
+ | `.otf` | `font/otf` |
452
+ | `.pdf` | `application/pdf` |
453
+ | `.png` | `image/png` |
454
+ | `.ppt` | `application/vnd.ms-powerpoint` |
455
+ | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
456
+ | `.rtf` | `application/rtf` |
457
+ | `.svg` | `image/svg+xml` |
458
+ | `.tif`, `.tiff` | `image/tiff` |
459
+ | `.ttf` | `font/ttf` |
460
+ | `.txt` | `text/plain` |
461
+ | `.vtt` | `text/vtt` |
462
+ | `.wav` | `audio/wav` |
463
+ | `.webm` | `video/webm` |
464
+ | `.webp` | `image/webp` |
465
+ | `.woff` | `font/woff` |
466
+ | `.woff2` | `font/woff2` |
467
+ | `.xls` | `application/vnd.ms-excel` |
468
+ | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
469
+ | `.xml` | `application/xml` |
470
+ | `.yaml`, `.yml` | `application/yaml` |
471
+ | `.zip` | `application/zip` |
472
+ | Any other, or none | `application/octet-stream` |
381
473
 
382
474
  ## Capability design
383
475
 
@@ -438,7 +438,7 @@ The mental model is a phone app's permissions: a static declaration, enforced at
438
438
  | `generateSpeech` | Text-to-speech, returning an audio blob; see [Speech generation](./speech-generation.md) |
439
439
  | `writeBlob` | Writes raw bytes to the blob store and returns a `blob:<id>` reference; most useful in an endpoint that returns a file |
440
440
 
441
- The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
441
+ The list is closed and fixed by the SDK (see [`ApiUse`](../api/sdk.md#apiuse)). Every other callback is runtime plumbing and is never gated: logic always has `readAsset`, `describeAsset` and `getPastState`, and a UI's `getAssetUrl`, `uploadBlob`, `requestTick` and the rest are always there when the surface exposes them.
442
442
 
443
443
  ### What happens when a resource calls one it did not declare
444
444
 
@@ -53,15 +53,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
53
53
  >();
54
54
  ```
55
55
 
56
- | Field | What it holds |
57
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
58
- | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
- | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`) and `teams` |
60
- | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
- | `theme` | The host's theme, to map onto the deck's colours |
62
- | `locale` | The locale to render in |
63
- | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
- | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
56
+ | Field | What it holds |
57
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
58
+ | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
+ | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
60
+ | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
+ | `theme` | The host's theme, to map onto the deck's colours |
62
+ | `locale` | The locale to render in |
63
+ | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
+ | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
65
65
 
66
66
  A presentation sees every team: it is the facilitator's view of the room.
67
67
 
@@ -85,6 +85,16 @@ export function useResults(): Results {
85
85
  }
86
86
  ```
87
87
 
88
+ ### Showing the room how to join
89
+
90
+ The first slides are often on the projector while the room arrives, so a session carries what a join slide needs:
91
+
92
+ - **`joinLinks`**: one entry per team, in index order, each `{ teamId, joinUrl, fallbackJoinUrl? }`. Encode `joinUrl` in a QR code; offer `fallbackJoinUrl` only on request. There is no observe URL: watching a team is the facilitator's tool, not the room's
93
+ - **`joinPin`**: the code to enter alongside the link, or `null` when joining needs none. Show it beside the link, never inside it
94
+ - **`participants`**: every team's participants, `connected` or not, for a count of who has arrived
95
+
96
+ All three are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
97
+
88
98
  ### Varying by scenario
89
99
 
90
100
  Branch on settings, scenario assets and `game.maxTicks`, never on `game.scenarioName`. A facilitator who saves their own scenario from one of yours gets a new identity, so a deck that branched on the name would show the wrong slides to exactly the facilitators who customised. `scenarioName` is for display, as it is everywhere else a game is told it (see [Showing the scenario](./engine.md#showing-the-scenario)).
@@ -150,6 +160,10 @@ const brand = {
150
160
 
151
161
  Use the light palette whatever mode the facilitator's screen is in: slides are made to be projected, and a projector washes out a dark slide. `useBrand()` gives a custom component the resolved colours, and the CSS variables `--deck-primary`, `--deck-secondary` and `--deck-muted` reach anything inside a slide.
152
162
 
163
+ ## Opening from the session UI
164
+
165
+ A session UI that owns the whole canvas can open the deck for the facilitator with `openHostOverlay('presentation')`, once the game lists `presentation-overlay` in `requires`. The host opens it in its own chrome, usually in a window of its own that the facilitator can put on the projector. See [Opening host overlays](./session.md#opening-host-overlays).
166
+
153
167
  ## Coming back to where you were
154
168
 
155
169
  `rememberAs` keeps the facilitator's place in the browser's own storage, so a reload, a closed laptop lid or a break comes back to the same slide and step:
@@ -49,7 +49,7 @@ An agent writing a scenario changes settings and nothing else, so anything you w
49
49
  }
50
50
  ```
51
51
 
52
- Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means, or change how the game loads scenario assets, bump `scenarioFormat` in `seriousgaming.sdk.json` (it starts at 1), and a runtime refuses the older scenarios rather than applying them wrongly. A new setting with a default needs no bump. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
52
+ Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means, change how the game loads scenario assets, or move or remove a built-in scenario's files, bump `scenarioFormat` in `seriousgaming.sdk.json` (it starts at 1), and a runtime refuses the older scenarios rather than applying them wrongly. A new setting with a default needs no bump. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
53
53
 
54
54
  Build an editor when a form is not enough: values that only make sense together, uploaded assets, a preview of what participants will see, or guidance a facilitator needs while choosing.
55
55
 
@@ -123,11 +123,12 @@ The flag says the scenario is for a particular audience. It never says who they
123
123
 
124
124
  What a production runtime does with the flag is its own business, but it must not offer a restricted scenario for selection, list it, resolve it by identifier, or serve its assets to a caller it has not granted it to.
125
125
 
126
- Three things are worth knowing before you rely on it:
126
+ Four things are worth knowing before you rely on it:
127
127
 
128
128
  - **The dev server ignores it.** There are no organisations locally and the package is yours, so restricted scenarios are offered exactly like any other. You cannot test the restriction from here
129
129
  - **A restricted scenario cannot also be the default.** A default is what a caller gets when it picks nothing, so it has to be one every caller can be offered. The build refuses a scenario that sets both
130
130
  - **It does not cover `shared:` assets.** Files under the package-level `shared-assets/` directory resolve whatever scenario is active, so anything belonging to one client goes under that scenario's own `assets/`, not in `shared-assets/`
131
+ - **Copies of it are restricted too.** A custom scenario copied from a restricted one reads its files, so a runtime offers the copy only to callers it has granted the original to. A client that loses the grant loses the copies built on it
131
132
 
132
133
  The flag protects the scenario only on a runtime that implements grants: one that does not recognise the field offers the scenario normally. What it always does is record the intent in the package, reviewed alongside the content it describes, rather than leaving it to a setting somebody remembers to tick after the upload.
133
134
 
@@ -454,6 +455,12 @@ The editor is optional. `customScenarios.supported` is what switches custom scen
454
455
 
455
456
  A saved scenario keeps every file it references for as long as it exists, whichever route uploaded it.
456
457
 
458
+ ### Files a custom scenario reads
459
+
460
+ A custom scenario has no `assets/` directory of its own. Copying a scenario converts the `asset:` references in its settings, but not the ones your code builds, such as `` `asset:documents/${locale}/${id}.json` ``. Those resolve against the **built-in scenario the custom one descends from**: the scenario under `scenarios/` it was copied from, followed back through any copies of copies, as the package version the session runs ships it. A scenario draft does the same, so an editor or an agent working on a copy of `northwind` reads `northwind`'s files. A custom scenario begun from the defaults, with no built-in scenario behind it, resolves no `asset:` reference at all.
461
+
462
+ A runtime remembers which built-in scenario each custom scenario descends from, and refuses to apply one whose ancestor your current release no longer ships, naming it. So removing or renaming a built-in scenario retires every custom scenario copied from it, and moving its files breaks those your code reads: bump `scenarioFormat` when you do either (see below).
463
+
457
464
  ### Writing scenarios with an agent
458
465
 
459
466
  A platform that lets an agent write scenarios gives it four things, and your game decides what each holds:
@@ -486,6 +493,7 @@ Bump it when a scenario saved against the previous release may no longer be corr
486
493
  - A setting removed, renamed, or reshaped (an object split in two, a number that becomes an enum)
487
494
  - A change in what a value means (a percentage that becomes a fraction, a per-round amount that becomes a total)
488
495
  - A change in how the game loads scenario assets (a reference resolved from a different path)
496
+ - A built-in scenario's files moved or removed, or the scenario itself removed or renamed. A custom scenario reads the files your code names from the built-in scenario it was copied from (see [Files a custom scenario reads](#files-a-custom-scenario-reads))
489
497
  - A lock or a narrower range on a setting a saved scenario may already set: a new `readOnly` in a settings schema, or a new or tighter entry in `gameSettingsConstraints` (see [Lock a setting](./settings.md#lock-a-setting)). A lock is enforced when a value is written, so the format is what stops an older scenario that carries the value from applying
490
498
  - A new or stricter `Scenario` gate on a validator (see [Gating scenarios](./validators.md#gating-scenarios)). The gate runs when a scenario is saved, so the format is what stops one saved before the rule from applying
491
499
 
@@ -427,9 +427,9 @@ Deliberately, the [tick interval bounds](./tick-controller.md) do not apply. The
427
427
 
428
428
  ### Opening host overlays
429
429
 
430
- Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet. Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
430
+ Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet, your [presentation](./presentation.md). Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
431
431
 
432
- `openHostOverlay` asks. The host renders the overlay in its own chrome, above your session UI, where you can neither restyle nor suppress it:
432
+ `openHostOverlay` asks. The host renders the overlay in its own chrome, over your session UI or in a window of its own, where you can neither restyle nor suppress it. Which is the host's choice: a deck usually gets a window, so the facilitator can put it on the projector and keep your session UI on their own screen:
433
433
 
434
434
  ```typescript
435
435
  import {
@@ -450,6 +450,9 @@ function OverlayControls() {
450
450
  {overlays.includes('print-sheets') && (
451
451
  <Button onClick={() => void openHostOverlay('print-sheets')}>Print sheets</Button>
452
452
  )}
453
+ {overlays.includes('presentation') && (
454
+ <Button onClick={() => void openHostOverlay('presentation')}>Presentation</Button>
455
+ )}
453
456
  </Stack>
454
457
  );
455
458
  }
@@ -459,13 +462,24 @@ function OverlayControls() {
459
462
 
460
463
  The second argument narrows the overlay:
461
464
 
462
- | Overlay | Second argument | Omitted means |
463
- | --------------------- | ------------------------------------------------ | ---------------- |
464
- | `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
465
- | `'print-sheets'` | A team id | Every team |
465
+ | Overlay | Second argument | Omitted means |
466
+ | --------------------- | ------------------------------------------------ | --------------------------------- |
467
+ | `'facilitator-guide'` | None: a game holds one guide, and one is ignored | The game's guide |
468
+ | `'print-sheets'` | A team id | Every team |
469
+ | `'presentation'` | None: a game holds one deck, and one is ignored | The game's deck, for this session |
466
470
 
467
471
  It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for a team id that is not in the session.
468
472
 
473
+ **The presentation needs `presentation-overlay` in `requires`.** A host offers `'presentation'` only to a game that ships a `presentation/` slot and lists the feature in `seriousgaming.sdk.json`:
474
+
475
+ ```json
476
+ {
477
+ "requires": ["presentation-overlay"]
478
+ }
479
+ ```
480
+
481
+ Listing it means a host that cannot open the deck this way refuses the game rather than running it without the button, so list it only if your session UI offers the control. The deck opens for the current session, on the slide the facilitator left it on.
482
+
469
483
  **Prefer the host's print sheets to your own.** A host's sheet carries the brand of the organisation running the session, with its join details in the form the host chose, so offer `'print-sheets'` wherever the host does. Draw your own sheet only where it does not, from [`useSessionUserInterfaceTeamLinks`](#usesessionuserinterfaceteamlinks), and put the host's logo on it with `useBrandLogo()` (see [Theming and branding](./theming-and-branding.md)), so a white-label session never prints your game's identity, or nobody's.
470
484
 
471
485
  ### Undoing and resetting
@@ -516,6 +530,28 @@ const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
516
530
 
517
531
  The host provides its own toggle too, so building one is optional. Reach for this when you want the control to sit inside your own facilitator layout, or to pair it with a note you set on a shared capability at the same moment.
518
532
 
533
+ ### Changing the language
534
+
535
+ `setLocale` changes the session's language: the locale every surface is sent, and your logic reads, from then on. It is the change the host's own language picker makes, for a session UI that owns the whole canvas:
536
+
537
+ ```typescript
538
+ const meta = useSessionUserInterfaceMeta();
539
+ const { locale } = useSessionUserInterfaceLocale();
540
+ const { setLocale } = useSessionUserInterfaceCallbacks();
541
+
542
+ {meta.canSetLocale && (
543
+ <Select value={locale} onChange={(event) => void setLocale(event.target.value)}>
544
+ <MenuItem value="en">English</MenuItem>
545
+ <MenuItem value="it">Italiano</MenuItem>
546
+ </Select>
547
+ )}
548
+ ```
549
+
550
+ - **Gate it on `meta.canSetLocale`.** A host that predates `setLocale` leaves it out, and may never answer the call, so a control shown there would hang
551
+ - **Offer only your `supportedLocales`.** Anything else is refused as `denied`, rather than swapped for the nearest language you do support
552
+ - **Render the locale you are sent**, not the one you asked for. The host's picker changes it too, and the last change wins
553
+ - It takes no `teamId`: the language is the session's
554
+
519
555
  ### Controlling the roster
520
556
 
521
557
  The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
@@ -810,9 +846,12 @@ Read the session itself:
810
846
  ```typescript
811
847
  import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
812
848
 
813
- const { sessionId, name, readOnly, waitingRoomOpen, joinPin } = useSessionUserInterfaceMeta();
849
+ const { sessionId, name, readOnly, waitingRoomOpen, joinPin, canSetLocale } =
850
+ useSessionUserInterfaceMeta();
814
851
  ```
815
852
 
853
+ `canSetLocale` is `true` where the host accepts [`setLocale`](#changing-the-language), and absent on a host that predates it.
854
+
816
855
  `joinPin` is the code participants enter to join, or `null` when joining needs none. How joining is secured is up to the runtime, so it need not be a PIN and some runtimes never set it: render it as an opaque string, and hide the panel when it is `null`. `readOnly` marks a frozen session, so a surface can disable its own controls and explain why rather than offering affordances that will be denied. `waitingRoomOpen` is the current value of a flag the session UI can also write through `setWaitingRoom`; since the host usually renders its own waiting-room control too, read the result back rather than assuming your write won.
817
856
 
818
857
  ### useSessionUserInterfaceTeamLinks
@@ -836,7 +875,7 @@ Find out which host overlays this host offers, before rendering a control for on
836
875
  import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
837
876
 
838
877
  const overlays = useSessionUserInterfaceHostOverlays();
839
- // HostOverlay[]: 'facilitator-guide' | 'print-sheets'
878
+ // HostOverlay[]: 'facilitator-guide' | 'print-sheets' | 'presentation'
840
879
  ```
841
880
 
842
881
  Empty until the host answers, and empty is also the correct answer for a host that delegates none. It can change mid-session. See [Opening host overlays](#opening-host-overlays).
@@ -62,7 +62,7 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
62
62
  }
63
63
  ```
64
64
 
65
- `settingsSchema` is a full JSON Schema Draft 7 object. Two rules are stricter than for a capability's `variablesSchema`:
65
+ `settingsSchema` is a full JSON Schema Draft 7 object, as every schema a game writes is, read the same way whatever `$schema` it names. Two features of later drafts also work: `$defs` beside `definitions`, and keywords written beside a `$ref` (see [Reuse a shape](#reuse-a-shape-or-nest-it-to-any-depth)). Two rules are stricter than for a capability's `variablesSchema`:
66
66
 
67
67
  - Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
68
68
  - Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
@@ -70,6 +70,43 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
70
70
 
71
71
  A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
72
72
 
73
+ ### Reuse a shape, or nest it to any depth
74
+
75
+ Declare a shape once under `$defs` (or `definitions`) and use it with a `$ref`. A shape may contain itself, which is how recursive data, such as a running order whose items hold items or a rule whose branches are rules, is checked to every depth rather than left as a bare object below the first level:
76
+
77
+ ```json
78
+ "settingsSchema": {
79
+ "type": "object",
80
+ "properties": {
81
+ "Agenda": {
82
+ "title": "Agenda",
83
+ "$ref": "#/$defs/agendaItem",
84
+ "default": { "title": "Workshop", "children": [] }
85
+ }
86
+ },
87
+ "$defs": {
88
+ "agendaItem": {
89
+ "type": "object",
90
+ "properties": {
91
+ "title": { "type": "string" },
92
+ "children": { "type": "array", "items": { "$ref": "#/$defs/agendaItem" } }
93
+ },
94
+ "required": ["title", "children"],
95
+ "additionalProperties": false
96
+ }
97
+ },
98
+ "additionalProperties": false
99
+ }
100
+ ```
101
+
102
+ - **A reference stays inside its own schema.** It names a part of the settings resource that holds it, as `#/$defs/<name>`. The build refuses one that names nothing, another file, a URL or another resource's schema, pointing at it
103
+ - **Write the `default` beside the `$ref`.** Keywords beside a reference apply with it, so the property's `default`, `title` and `description` go there, and so does a constraint for this use alone, such as a `maximum`
104
+ - **Every check follows it.** The defaults, scenarios, setup and scenario editor writes, [file settings](#settings-that-hold-a-file), [locks](#lock-a-setting) and [guide conditions](./guide.md) all reach through a reference, at every depth
105
+ - **Each use keeps its own rule.** Where the shape is an object setting, a scenario may set one key of it and leave the rest; where it is an array's item, each item must be complete
106
+ - **The generated types name it.** `Agenda` is typed `AgendaItem`, one interface whose `children` are `AgendaItem[]`, exported from `types.ts` for your own code. When two resources a file reads both define the same name, the second is prefixed with its identifier (`EngineRule`)
107
+
108
+ A capability's `variablesSchema` takes `$defs` and `$ref` the same way.
109
+
73
110
  ### Describe every setting
74
111
 
75
112
  A settings schema is read by more than the build. A hosted runtime's generic settings form, a [scenario editor](./scenario-editor.md), and an AI agent authoring a scenario for your released game all work from it, and an agent can edit a game with no editor UI at all if the schema says what each value means. Give every property:
@@ -112,6 +149,8 @@ Some values are part of the game's design rather than something to tune: a const
112
149
  - **Nothing can change a locked value.** The build refuses a scenario that sets it, with `SETTINGS_LOCKED` pointing at the value, even when it sets the same value as your default. A setup screen or scenario editor that changes it is refused as `denied`, with a message naming the setting (`"engine.LowProductionThreshold" is read-only`), and none of that write applies
113
150
  - **Sending it back unchanged is fine.** An editor that spreads the settings it was given sends the locked value back as it was, and only what changed is applied, so spreading is still safe
114
151
  - **Locking an object locks everything in it.** `readOnly` on an object-valued property fixes every key inside it, at any depth
152
+ - **Lock named properties, or a whole list or map.** A list's items and a map's entries come and go as scenarios add and remove them, so there is no single value of yours for a lock inside one to keep. The build refuses `readOnly` beneath `items`, `additionalProperties` or `patternProperties`; put it on the list or map itself instead
153
+ - **A lock reached through a `$ref` counts.** `readOnly` on a shape under `$defs` locks every named property that uses it (see [Reuse a shape, or nest it to any depth](#reuse-a-shape-or-nest-it-to-any-depth))
115
154
  - **Saving a scenario leaves locked values out.** The dev console's Save writes every other setting and drops the locked ones, so the scenario still builds
116
155
  - **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
117
156
  - **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
@@ -136,6 +175,27 @@ A setting can hold a file, such as a client's logo or a briefing document. Mark
136
175
  - **The build checks your files.** Every file a package scenario or a default names must be shipped, within `maxBytes`, and of a type `accept` lists, judged from its extension. A `blob:` reference in a package scenario fails the build: it is an upload, which no package can carry
137
176
  - **Every write is checked against it.** A setup screen, the scenario editor or an agent sets a file by uploading it first and writing the `blob:` reference it gets back. A reference to a file nobody uploaded, or one too large or of the wrong type, is refused as `denied`, naming the setting. So is anything that is not a reference, a `data:` URI or a URL included
138
177
  - **It tells an agent what to upload.** A schema alone says only that the value is a string; `blob` says it is a PNG of up to 512 KB
178
+ - **A map can hold a file per key.** Put `blob` on a map's `additionalProperties` (or a `patternProperties` schema), and every entry is a file setting of its own, checked and named by its key (`brand.Cast.ada`, see [How a setting is named](#how-a-setting-is-named)). A file per language is one such map (see [A file per language](./file-handling.md#a-file-per-language))
179
+
180
+ ### How a setting is named
181
+
182
+ A refusal, a lock's message, a `Scenario` gate's problem and a guide's `:setting` all name one value by its setting path: the settings identifier, then each key down to the value.
183
+
184
+ ```text
185
+ ui.MinPrice
186
+ brand.Cast.ada.portrait
187
+ engine.Rounds.0.Price
188
+ brand.Cast["a.b"].portrait
189
+ ```
190
+
191
+ A plain key, one that is not empty and holds no `.`, `[`, `]`, `"` or space, follows a dot, and so does a list's position. Any other key, such as a map entry named `a.b`, goes in brackets as a JSON string, so the path reads back one way only. Build and read paths with `settingPath` and `parseSettingPath` from `@seriousgaming/sdk` rather than joining keys yourself:
192
+
193
+ ```typescript
194
+ import { parseSettingPath, settingPath } from '@seriousgaming/sdk';
195
+
196
+ settingPath('brand', 'Cast', 'a.b', 'portrait'); // 'brand.Cast["a.b"].portrait'
197
+ parseSettingPath('brand.Cast["a.b"].portrait'); // { identifier: 'brand', keys: ['Cast', 'a.b', 'portrait'] }
198
+ ```
139
199
 
140
200
  ### How to divide settings
141
201
 
@@ -402,7 +462,7 @@ Options:
402
462
  Every override source is validated against the `settingsSchema` of the settings resource it names, scenario overrides and session overrides alike. Neither has to name every property, but both are refused for:
403
463
 
404
464
  - A key naming no settings resource the package declares
405
- - A property the schema does not declare, such as a misspelling
465
+ - A property the schema does not declare, such as a misspelling. An object that lists `properties` and says nothing else of its keys refuses any key it does not list, whether or not it sets `additionalProperties: false`. A bare `{ "type": "object" }`, or an object with `patternProperties`, an `additionalProperties` schema or `allOf`/`anyOf`/`oneOf`, takes whatever its schema admits, so an object meant to hold any keys, such as a map of triggers, is written that way
406
466
  - A value of the wrong type, or outside a `minimum`, `maximum` or `enum`
407
467
  - A value the schema locks with `readOnly` (see [Lock a setting](#lock-a-setting))
408
468
 
@@ -359,6 +359,15 @@ A session UI's `setData` takes the team id first for a team's own capabilities,
359
359
 
360
360
  Always render through these helpers. They supply every context a surface reads, with complete defaults, and each option overrides one value, so a test that needs a particular theme, locale, callback or viewer role passes it as an option. A hand-built provider tree has to supply every callback and every field itself, and it silently stops matching the runtime when the SDK adds one.
361
361
 
362
+ ### What a minor release may change
363
+
364
+ A minor release never breaks a type you build yourself: a logic result, a settings value, a `TeamState` or `SessionMeta` you pass as test data, or the options of a `render*` helper. It may add required members to what the runtime implements for you, and these are outside semantic versioning:
365
+
366
+ - The callbacks a surface is handed: `UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and `SettingsEditorCallbacks`
367
+ - The React contexts the SDK exports, such as `UserInterfaceCallbacksContext`
368
+
369
+ Read both through their hooks, and test through the helpers above, which fill in anything new. A test that builds either by hand may stop compiling on a minor upgrade.
370
+
362
371
  ### Testing controlled inputs
363
372
 
364
373
  For inputs that call `setData` on change, use `fireEvent.change` rather than `userEvent.type`. Because `setData` is mocked, the component's displayed value won't update between keystrokes. `fireEvent.change` fires a single synthetic event with the exact target value, which correctly triggers `onChange`:
@@ -569,6 +569,39 @@ Points worth knowing:
569
569
  - **`teams.defaultNames` becomes a starting point**, not a fixed label, in any
570
570
  game that offers this
571
571
 
572
+ ## Letting a participant fix their own name
573
+
574
+ A participant who mistyped their name on joining can change it with `renameSelf`,
575
+ where the host lets them. Whose names are theirs to change is the host's call: a
576
+ guest who typed one usually may, and one whose name comes from a sign-in may not.
577
+ `useUserInterfaceCanRenameSelf()` gives the host's answer for the participant
578
+ using this surface:
579
+
580
+ ```typescript
581
+ import {
582
+ useUserInterfaceCallbacks,
583
+ useUserInterfaceCanRenameSelf,
584
+ } from '@seriousgaming/sdk/ui';
585
+
586
+ const canRenameSelf = useUserInterfaceCanRenameSelf();
587
+ const { renameSelf } = useUserInterfaceCallbacks();
588
+
589
+ {canRenameSelf && (
590
+ <Button onClick={() => void renameSelf(draftName)}>Change my name</Button>
591
+ )}
592
+ ```
593
+
594
+ - **Show the control only where `canRenameSelf` is `true`.** It is `false` for an
595
+ observer, for a participant whose name the host keeps, and on a host that
596
+ predates `renameSelf`, which may never answer the call
597
+ - **It names nobody.** The host works out who is asking, so a surface can only
598
+ rename its own participant
599
+ - **Render the result, not the request.** A facilitator can rename the same
600
+ participant at the same moment. Read the name back from
601
+ `useUserInterfaceParticipant()`
602
+ - **The host owns the limits**, as for a team name: it trims the name and refuses
603
+ a blank or over-long one as a terminal `denied`
604
+
572
605
  ## Displaying the tick timer
573
606
 
574
607
  When a game uses an automatic [tick controller](./tick-controller.md), the host pushes the current schedule to every UI via the `useUserInterfaceTimer` hook, as a `TimerState`. Use this when you want your UI to show its own countdown: for example, a circular progress bar in the corner of a Decisions panel, or a floating 'Next tick in 12s' badge on a results screen.
@@ -671,6 +671,17 @@ A minor release that changes a public type a test may build by hand lists it her
671
671
 
672
672
  `Brand.icon` is `{ onLight?, onDark? }`, the shape of `logo`, rather than one URL. Only a `Brand` you build yourself, in a test or a mock, needs the change: replace `icon: 'icon.svg'` with `icon: { onLight: 'icon.svg', onDark: 'icon.svg' }`, or a file for each. The wrapper turns a single icon from an older host into both variants, so a game reading the brand through `useBrandIcon()` needs nothing.
673
673
 
674
+ ### 1.3: let the render helpers build your callbacks
675
+
676
+ `UserInterfaceCallbacks` and `SessionUserInterfaceCallbacks` gain `renameSelf` and `setLocale`. A game reading them through `useUserInterfaceCallbacks()` or `useSessionUserInterfaceCallbacks()` needs nothing. A test that builds a callbacks object by hand and passes it to `UserInterfaceCallbacksContext.Provider` or `SessionUserInterfaceCallbacksContext.Provider` stops compiling. Render the surface with `renderUserInterface` or `renderSessionUserInterface` instead, passing only the callbacks the test checks:
677
+
678
+ ```tsx
679
+ const requestTick = vi.fn();
680
+ renderUserInterface(<App />, { callbacks: { requestTick } });
681
+ ```
682
+
683
+ These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
684
+
674
685
  ## Before you publish
675
686
 
676
687
  A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.