@seriousgaming/sdk-tools 1.1.0 → 1.3.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 (40) hide show
  1. package/dist/cli.js +565 -309
  2. package/dist/client.js +608 -352
  3. package/dist/core/participant-registry.d.ts +6 -0
  4. package/dist/core/session-roster.d.ts +4 -1
  5. package/dist/dev/brands.d.ts +20 -3
  6. package/dist/dev/console/assets/{index-qxHcu9fJ.js → index-DEV8N0na.js} +47 -47
  7. package/dist/dev/console/index.html +1 -1
  8. package/dist/dev/view/batch.d.ts +17 -9
  9. package/dist/dev/view/view.d.ts +2 -1
  10. package/dist/docs/api/index.md +1 -1
  11. package/dist/docs/api/sdk-commands.md +4 -0
  12. package/dist/docs/api/sdk-e2e.md +4 -0
  13. package/dist/docs/api/sdk-tools-client.md +4 -0
  14. package/dist/docs/api/sdk-ui-testing.md +2 -1
  15. package/dist/docs/api/sdk-ui.md +54 -3
  16. package/dist/docs/api/sdk.md +3 -1
  17. package/dist/docs/changelog.md +41 -0
  18. package/dist/docs/guides/guide.md +35 -4
  19. package/dist/docs/guides/presentation.md +23 -9
  20. package/dist/docs/guides/production-constraints.md +1 -1
  21. package/dist/docs/guides/session.md +50 -9
  22. package/dist/docs/guides/testing.md +9 -0
  23. package/dist/docs/guides/theming-and-branding.md +18 -4
  24. package/dist/docs/guides/ui.md +33 -0
  25. package/dist/docs/guides/upgrading.md +19 -0
  26. package/dist/docs/guides/waiting-room.md +2 -0
  27. package/dist/docs/recipes/create-guide.md +2 -2
  28. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +9 -9
  29. package/dist/guide/settings.d.ts +7 -0
  30. package/dist/guide/video-registry.d.ts +33 -1
  31. package/dist/host/index.d.ts +4 -2
  32. package/dist/host/protocol.d.ts +27 -2
  33. package/dist/host.js +131 -0
  34. package/dist/runtime/manifest-version.d.ts +1 -1
  35. package/dist/runtime.js +4 -2
  36. package/dist/templates/package/CLAUDE.md.template +1 -1
  37. package/dist/templates/package/claude/rules/workflow-create-guide.md +8 -2
  38. package/dist/validation/facilitator-guide-validator.d.ts +5 -1
  39. package/dist/validation/schema-validation.d.ts +12 -4
  40. package/package.json +3 -3
@@ -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-qxHcu9fJ.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-DEV8N0na.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -11,7 +11,7 @@
11
11
  * boundary, and a host that sends everything and lets the guest ignore the rest
12
12
  * has not projected at all.
13
13
  */
14
- import type { HostOverlay } from '@seriousgaming/sdk';
14
+ import type { HostOverlay, ResolvedPackageManifest } from '@seriousgaming/sdk';
15
15
  import type { StateProjection } from '@seriousgaming/sdk/projection';
16
16
  import type { CrossTeamData, SessionData, TeamConfiguration, TeamLinks, WalkthroughLink } from '@seriousgaming/sdk/ui';
17
17
  import type { ViewerRole } from '../../core/protocol';
@@ -57,8 +57,8 @@ export interface BatchOptions {
57
57
  assetOrigin?: string;
58
58
  /** The game's own name, which a session surface renders as the session's. */
59
59
  gameName: string;
60
- /** Whether the package ships a facilitator guide, which is one overlay. */
61
- hasGuide?: boolean;
60
+ /** The host overlays a session surface is offered (§6.4); see {@link availableOverlays}. */
61
+ overlays?: HostOverlay[];
62
62
  /** Whether a tick is running over this viewer's team (§12.4.4). */
63
63
  roundProcessing?: boolean;
64
64
  /**
@@ -140,13 +140,21 @@ export declare function walkthroughLink(origin: string): WalkthroughLink;
140
140
  /**
141
141
  * The host-owned overlays a session surface may open (§6.4).
142
142
  *
143
- * Both of these are the console's own pages rather than anything the game
144
- * mounts, which is what makes them the host's to offer: a facilitator on a
145
- * surface that owns the whole canvas can reach the guide and the team sheets
146
- * without leaving it. A guide is offered only when the package ships one — a
147
- * control for an overlay the host does not have is a control that cannot work.
143
+ * Each is the console's own page rather than anything the game mounts, which
144
+ * is what makes them the host's to offer: a facilitator on a surface that owns
145
+ * the whole canvas can reach the guide, the team sheets and the deck without
146
+ * leaving it. A guide is offered only when the package ships one, and the deck
147
+ * only when it ships one and lists `presentation-overlay` (§2.6) — a control
148
+ * for an overlay the host does not have is a control that cannot work.
148
149
  */
149
- export declare function availableOverlays(hasGuide?: boolean): HostOverlay[];
150
+ export declare function availableOverlays(offered?: {
151
+ guide?: boolean;
152
+ presentation?: boolean;
153
+ }): HostOverlay[];
154
+ /** Whether a package is offered its deck as a host overlay (§6.4). */
155
+ export declare function offersPresentationOverlay(config: ResolvedPackageManifest | null): boolean;
156
+ /** The `requires` feature name behind the `'presentation'` overlay (§6.4). */
157
+ export declare const PRESENTATION_OVERLAY = "presentation-overlay";
150
158
  /**
151
159
  * One join and observe URL per team, for the facilitator surface.
152
160
  *
@@ -9,6 +9,7 @@
9
9
  * The operator console, which renders its own inspector in the same document
10
10
  * as the frame, keeps the whole projection and resolves the same rules itself.
11
11
  */
12
+ import type { HostOverlay } from '@seriousgaming/sdk';
12
13
  import type { StateProjection } from '@seriousgaming/sdk/projection';
13
14
  import type { HostMessage, SurfaceKind } from '../../host';
14
15
  import type { MountableSurface } from '../surfaces';
@@ -71,7 +72,7 @@ export interface ViewMessageOptions {
71
72
  origin: string;
72
73
  assetOrigin: string;
73
74
  gameName: string;
74
- hasGuide: boolean;
75
+ overlays: HostOverlay[];
75
76
  roundProcessing: boolean;
76
77
  }
77
78
  /** Every message a viewer page's surface is owed, less the theme the page adds. */
@@ -7,7 +7,7 @@ Every type, function, hook and component your game imports, one page per entry p
7
7
  | Entry point | Exports |
8
8
  | ---------------------------------------------------------- | -------------------------------------------------------------- |
9
9
  | [`@seriousgaming/sdk`](./sdk.md) | 10 functions, 2 classes, 97 interfaces, 48 types |
10
- | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 47 functions, 3 classes, 38 constants, 25 interfaces, 36 types |
10
+ | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
11
11
  | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
12
12
  | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
13
13
  | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
@@ -143,6 +143,10 @@ type MutationCommand =
143
143
  type: 'renameOwnTeam';
144
144
  name: string;
145
145
  } & Actor)
146
+ | ({
147
+ type: 'renameSelf';
148
+ name: string;
149
+ } & Actor)
146
150
  | {
147
151
  type: 'addParticipant';
148
152
  teamId: string;
@@ -283,6 +283,10 @@ type MutationCommand =
283
283
  type: 'renameOwnTeam';
284
284
  name: string;
285
285
  } & Actor)
286
+ | ({
287
+ type: 'renameSelf';
288
+ name: string;
289
+ } & Actor)
286
290
  | {
287
291
  type: 'addParticipant';
288
292
  teamId: string;
@@ -380,6 +380,10 @@ type MutationCommand =
380
380
  type: 'renameOwnTeam';
381
381
  name: string;
382
382
  } & Actor)
383
+ | ({
384
+ type: 'renameSelf';
385
+ name: string;
386
+ } & Actor)
383
387
  | {
384
388
  type: 'addParticipant';
385
389
  teamId: string;
@@ -8,7 +8,7 @@ Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is publ
8
8
 
9
9
  ### createMockBrand
10
10
 
11
- A host brand for tests: a name and a logo for each background, as `data:` URLs, so a component reading `useBrand()` or `useBrandLogo()` has something to render. It names no fonts, so nothing waits on a load.
11
+ A host brand for tests: a name, and a logo and an icon for each background, as `data:` URLs, so a component reading `useBrand()`, `useBrandLogo()` or `useBrandIcon()` has something to render. It names no fonts, so nothing waits on a load.
12
12
 
13
13
  ```ts
14
14
  function createMockBrand(overrides?: Partial<Brand>): Brand;
@@ -237,6 +237,7 @@ type RenderUserInterfaceOptions = {
237
237
  teams?: TeamInfo[];
238
238
  ownTeam?: TeamInfo | null;
239
239
  ownTeamJoinLink?: OwnTeamJoinLink | null;
240
+ canRenameSelf?: boolean;
240
241
  timer?: TimerState;
241
242
  validationRejections?: ValidationRejection[];
242
243
  clearRejections?: () => void;
@@ -84,6 +84,14 @@ The host's brand: always a name, empty only on a host that predates brands, and
84
84
  function useBrand(): Brand;
85
85
  ```
86
86
 
87
+ ### useBrandIcon
88
+
89
+ The host's square mark for the mode the surface is painting in, falling back to the other variant when the host sent only one, as `useBrandLogo` does. Undefined when the brand has no icon.
90
+
91
+ ```ts
92
+ function useBrandIcon(): BrandIcon | undefined;
93
+ ```
94
+
87
95
  ### useBrandLogo
88
96
 
89
97
  The host's logo for the mode the surface is painting in, falling back to the other variant when the host sent only one. Undefined when the brand has no logo: the SDK never supplies one of its own, so a white-label host never shows someone else's.
@@ -279,6 +287,14 @@ const useSettingsEditorThemePreference: () => ThemePreference;
279
287
  const useUserInterfaceCallbacks: () => UserInterfaceCallbacks;
280
288
  ```
281
289
 
290
+ ### useUserInterfaceCanRenameSelf
291
+
292
+ Whether the participant using this surface may change their own name with `renameSelf`.
293
+
294
+ ```ts
295
+ const useUserInterfaceCanRenameSelf: () => boolean;
296
+ ```
297
+
282
298
  ### useUserInterfaceCrossTeamData
283
299
 
284
300
  Observe every team's live cross-team state, including the calling team's own. Entries update as teams change their pending state, without waiting for a tick.
@@ -619,7 +635,7 @@ const SettingsEditorThemePreferenceContext: import('react').Context<ThemePrefere
619
635
 
620
636
  ### SurfaceThemeContext
621
637
 
622
- The theme of whichever surface is rendering, for the hooks every surface shares. Provided by every wrapper; game code reads it through `useBrand` and `useBrandLogo`.
638
+ The theme of whichever surface is rendering, for the hooks every surface shares. Provided by every wrapper; game code reads it through `useBrand`, `useBrandLogo` and `useBrandIcon`.
623
639
 
624
640
  ```ts
625
641
  const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
@@ -633,6 +649,14 @@ The React context behind `useUserInterfaceCallbacks`.
633
649
  const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
634
650
  ```
635
651
 
652
+ ### UserInterfaceCanRenameSelfContext
653
+
654
+ The React context behind `useUserInterfaceCanRenameSelf`.
655
+
656
+ ```ts
657
+ const UserInterfaceCanRenameSelfContext: import('react').Context<boolean>;
658
+ ```
659
+
636
660
  ### UserInterfaceCrossTeamDataContext
637
661
 
638
662
  The React context behind `useUserInterfaceCrossTeamData`.
@@ -791,7 +815,10 @@ interface Brand {
791
815
  onLight?: string;
792
816
  onDark?: string;
793
817
  };
794
- icon?: string;
818
+ icon?: {
819
+ onLight?: string;
820
+ onDark?: string;
821
+ };
795
822
  fonts?: {
796
823
  heading?: BrandFont;
797
824
  body?: BrandFont;
@@ -920,6 +947,18 @@ interface PresentationGame {
920
947
  }
921
948
  ```
922
949
 
950
+ ### PresentationJoinLink
951
+
952
+ How participants join one team, as a deck shows it to the room: the join links a session surface is given, without the facilitator's observe URL.
953
+
954
+ ```ts
955
+ interface PresentationJoinLink {
956
+ teamId: string;
957
+ joinUrl: string;
958
+ fallbackJoinUrl?: string;
959
+ }
960
+ ```
961
+
923
962
  ### PresentationSession
924
963
 
925
964
  The session a presentation is shown during: the shared store and every team, narrowed to what the presentation `reads`.
@@ -934,6 +973,9 @@ interface PresentationSession<
934
973
  completedTicks: number;
935
974
  data: SessionData<TTeamContext, TSharedContext>;
936
975
  teams: TeamInfo[];
976
+ participants?: Participant[];
977
+ joinLinks?: PresentationJoinLink[];
978
+ joinPin?: string | null;
937
979
  }
938
980
  ```
939
981
 
@@ -1097,6 +1139,14 @@ How `useAsset` reads the response body.
1097
1139
  type AssetFormat = 'json' | 'text' | 'blob';
1098
1140
  ```
1099
1141
 
1142
+ ### BrandIcon
1143
+
1144
+ The icon `useBrandIcon` picked, and the background it was drawn for.
1145
+
1146
+ ```ts
1147
+ type BrandIcon = BrandLogo;
1148
+ ```
1149
+
1100
1150
  ### ContextDeletePath
1101
1151
 
1102
1152
  Where to remove a key, as a path from the root of the context.
@@ -1173,7 +1223,7 @@ type EndpointFailureOutcome =
1173
1223
  A host-rendered overlay a session surface may ask the host to open.
1174
1224
 
1175
1225
  ```ts
1176
- type HostOverlay = 'facilitator-guide' | 'print-sheets';
1226
+ type HostOverlay = 'facilitator-guide' | 'print-sheets' | 'presentation';
1177
1227
  ```
1178
1228
 
1179
1229
  ### MutationFailure
@@ -1288,6 +1338,7 @@ type SessionMeta = {
1288
1338
  readOnly: boolean;
1289
1339
  waitingRoomOpen: boolean;
1290
1340
  joinPin: string | null;
1341
+ canSetLocale?: boolean;
1291
1342
  };
1292
1343
  ```
1293
1344
 
@@ -1290,6 +1290,7 @@ interface SessionUserInterfaceCallbacks {
1290
1290
  extendTick: (byMs: number, teamId?: string) => Promise<void>;
1291
1291
  openHostOverlay: (overlay: HostOverlay, target?: string) => Promise<void>;
1292
1292
  setWaitingRoom: (open: boolean) => Promise<void>;
1293
+ setLocale: (locale: string) => Promise<void>;
1293
1294
  resetWalkthrough: () => Promise<void>;
1294
1295
  createTeam: (name?: string) => Promise<void>;
1295
1296
  renameTeam: (teamId: string, name: string) => Promise<void>;
@@ -1484,6 +1485,7 @@ Callbacks available to user interface components
1484
1485
  interface UserInterfaceCallbacks {
1485
1486
  requestTick: () => Promise<void>;
1486
1487
  renameOwnTeam: (name: string) => Promise<void>;
1488
+ renameSelf: (name: string) => Promise<void>;
1487
1489
  uploadBlob: (file: File) => Promise<string>;
1488
1490
  getAssetUrl: (reference: string) => string;
1489
1491
  readAsset: (reference: string) => Promise<ReadAssetResponse>;
@@ -1969,7 +1971,7 @@ type HookSignal = 'participantJoin' | 'participantMove';
1969
1971
  A host-rendered overlay a session surface may ask the host to open.
1970
1972
 
1971
1973
  ```ts
1972
- type HostOverlay = 'facilitator-guide' | 'print-sheets';
1974
+ type HostOverlay = 'facilitator-guide' | 'print-sheets' | 'presentation';
1973
1975
  ```
1974
1976
 
1975
1977
  ### InitAggregateFunction
@@ -31,6 +31,47 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.3.0] — 2026-10-26
35
+
36
+ ### Added
37
+
38
+ - **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)
39
+ - **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)
40
+ - **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)
41
+ - **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)
42
+ - **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
43
+
44
+ ### Changed
45
+
46
+ - **A host may open an overlay in a window of its own** as well as over your session UI. Nothing to change: `openHostOverlay` still only asks
47
+ - **The callbacks a surface is handed may gain required members in a minor release.** `UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and `SettingsEditorCallbacks` are implemented by the runtime, so they are now outside semantic versioning, as their contexts already were. This release adds `renameSelf` and `setLocale` to them, so a test that builds a callbacks object by hand and passes it to a context provider stops compiling. Render through the `render*` helpers instead, which fill in every callback you do not pass. See [1.3: let the render helpers build your callbacks](guides/upgrading.md#13-let-the-render-helpers-build-your-callbacks) and [What a minor release may change](guides/testing.md#what-a-minor-release-may-change)
48
+ - **The dev server refuses a session locale the game does not declare**, from `pnpm run sdk locale`, the console's picker or an endpoint's `setLocale` action, rather than switching to it
49
+
50
+ ## [1.2.0] — 2026-10-25
51
+
52
+ ### Breaking Changes
53
+
54
+ - **`Brand.icon` is `{ onLight?, onDark? }`, like `logo`**, because a host sends its light and dark modes together and could not pick one icon for your surface. Only a `Brand` built by hand with a string `icon`, in a test or a mock, stops compiling; no game we know of builds one. See [1.2: give `Brand.icon` a variant for each background](guides/upgrading.md#12-give-brandicon-a-variant-for-each-background). A host built for 1.1 still sends one URL, and the wrapper gives it to you as both variants. `createMockBrand()` now includes an icon for each background
55
+
56
+ ### Added
57
+
58
+ - **`useBrandIcon()` gives the host's square icon for the mode your surface paints in**, falling back to the other variant as `useBrandLogo()` does. Use it where the logo will not fit. `examples/factory` shows it in place of the logo on a phone. A dev server `--brand` file may now give `icon` as `{ "onLight": …, "onDark": … }`, and a single file still serves for both
59
+ - **The build warns about a settings schema that leaves an object open**: one that lists `properties` without `"additionalProperties": false`. A key such an object does not declare is now refused anyway (see Fixed), and the warning asks the schema to say so
60
+ - **The build warns about a `:::` in a guide chapter that closes nothing**, which is what a `:::when` holding an admonition leaves behind when it has only three colons
61
+ - **A facilitator guide can play a video it ships.** Put an `.mp4` or `.webm` in `guide/assets/` and embed it with a `video` block of `provider: file`, giving its `src` and optionally a `title`, a `poster` image and WebVTT `captions`. It plays with controls and never autoplays, and a printed guide shows the poster or title in its place. The build fails on a file that is missing, outside `assets/` or of the wrong type, and warns about a video over 25 MB. `examples/factory`'s guide shows one. See [Video embeds](guides/guide.md#video-embeds)
62
+ - **`@seriousgaming/sdk-tools/host` exports `parseVideoBlock`**, with `guideAssetPath`, `VIDEO_PROVIDERS` and `FILE_VIDEO_EXTENSIONS`, so a platform renders a guide's video blocks by the dev server's rules
63
+ - **The `workflow-create-guide.md` rule describes `file` videos.** Merge it into your game's `.claude/rules/`
64
+ - **`CLAUDE.md.template` mentions `useBrandIcon()` and the host's print sheets** under 'Honour the host's brand'. Merge the line into your game's `CLAUDE.md`
65
+
66
+ ### Changed
67
+
68
+ - **The session UI guide recommends the host's print sheets.** Open `openHostOverlay('print-sheets')` where the host offers it, so the sheet carries the brand of whoever runs the session. Draw your own only where it does not, with `useBrandLogo()`
69
+
70
+ ### Fixed
71
+
72
+ - **A misspelt settings key is refused, not silently ignored, when the schema leaves its object open.** `min` for `Min`, in a setup UI's write, a scenario draft edit, a scenario you save or `sdk configure`, used to be accepted and change nothing on an object without `"additionalProperties": false`. It is now refused with the key it meant suggested. A map (`additionalProperties` set to a schema or `true`) and an object built from `oneOf` or `anyOf` branches are unchanged
73
+ - **The guide docs no longer suggest wrapping a chapter with admonitions in a three-colon `:::when`.** The admonition's closing `:::` closed the condition too, so everything after it showed in every scenario. Use `::::when` … `::::`
74
+
34
75
  ## [1.1.0] — 2026-10-24
35
76
 
36
77
  ### Added
@@ -79,7 +79,9 @@ Unknown admonition types render as an inert error block so typos surface immedia
79
79
 
80
80
  ## Video embeds
81
81
 
82
- A video embed is a fenced code block with language `video`, validated against a closed provider registry (YouTube only in v1):
82
+ A video embed is a fenced code block with language `video`, validated against a closed provider registry: `youtube` embeds a YouTube video, and `file` plays one the guide ships.
83
+
84
+ ### YouTube
83
85
 
84
86
  ````markdown
85
87
  ```video
@@ -88,7 +90,36 @@ id: dQw4w9WgXcQ
88
90
  ```
89
91
  ````
90
92
 
91
- The id must match YouTube's 11-character format. Unknown providers or malformed blocks render as an inert error block, never a passthrough. The dev server renders the embed from `youtube-nocookie.com` in a sandboxed iframe.
93
+ The id must match YouTube's 11-character format. The dev server renders the embed from `youtube-nocookie.com` in a sandboxed iframe.
94
+
95
+ ### A video file
96
+
97
+ Put the video in `guide/assets/` and point a `file` block at it, relative to the chapter as an image is:
98
+
99
+ ````markdown
100
+ ```video
101
+ provider: file
102
+ src: ../../assets/intro.mp4
103
+ title: How a round runs
104
+ poster: ../../assets/intro-poster.jpg
105
+ captions: ../../assets/intro.en.vtt
106
+ ```
107
+ ````
108
+
109
+ | Key | Required | What it is |
110
+ | ---------- | -------- | --------------------------------------------------------------------------------------- |
111
+ | `src` | Yes | The video, an `.mp4` or `.webm` file |
112
+ | `title` | No | Text shown wherever the video cannot play: in print, or to an agent reading the guide |
113
+ | `poster` | No | An image (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` or `.avif`) shown before it plays |
114
+ | `captions` | No | A WebVTT (`.vtt`) captions file. A localised chapter can point at its own captions file |
115
+
116
+ The video plays with controls and never starts by itself or loops. A printed guide shows the poster, or the title, in its place. Every file must be in the guide's `assets/` directory, and the build fails on one that is missing, outside it, or of the wrong type. It warns about a video larger than 25 MB, since every upload of the package carries it: compress it, or put it on YouTube.
117
+
118
+ A host built before SDK 1.2 shows a `file` block as an error block, and the rest of the guide and the game are unaffected.
119
+
120
+ ### Errors
121
+
122
+ Unknown providers, unknown keys or malformed blocks render as an inert error block, never a passthrough.
92
123
 
93
124
  ## Following the scenario's settings
94
125
 
@@ -142,7 +173,7 @@ Brief your observers before the first round.
142
173
  ::::
143
174
  ```
144
175
 
145
- **Show a chapter only sometimes.** Wrap a whole chapter, its title included, in one `:::when`. A chapter that has nothing left to show is left out of the guide and its table of contents. If every chapter is left out, the session has no guide.
176
+ **Show a chapter only sometimes.** Wrap a whole chapter, its title included, in one `:::when`, with four colons (`::::when`) when the chapter holds an admonition. With three, the admonition's closing `:::` closes the condition too, and everything after it shows in every scenario; the build warns about the `:::` left over. A chapter that has nothing left to show is left out of the guide and its table of contents. If every chapter is left out, the session has no guide.
146
177
 
147
178
  **What decides the values.** The same settings the game itself runs on: the defaults, then the scenario, then anything changed at setup. Read from a game's page before a session, the guide uses the defaults and the scenario chosen to look at.
148
179
 
@@ -166,7 +197,7 @@ The guide gets its own locale picker on the facilitator's page, defaulting to th
166
197
 
167
198
  Chapters fall back per file: a chapter missing from the selected locale is served from the reference locale ('en' when declared, otherwise the first declared locale) with a visible 'not yet translated' notice. Translate chapter by chapter and the guide stays usable throughout.
168
199
 
169
- `pnpm run sdk build --validate-only` warns when a declared locale is missing chapters present in the reference locale, and fails on malformed video blocks or unresolvable image references.
200
+ `pnpm run sdk build --validate-only` warns when a declared locale is missing chapters present in the reference locale, and fails on malformed video blocks, video files that are not in `assets/`, or unresolvable image references.
170
201
 
171
202
  ## Printing
172
203
 
@@ -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:
@@ -82,7 +82,7 @@ Alongside the policy, the asset host sends `X-Content-Type-Options: nosniff` on
82
82
  - Bundle every asset into your build so it resolves to `'self'`: fonts, icons, CSS, images, and scripts
83
83
  - Self-host fonts: import an `@fontsource` package, or drop `.woff2` files in your UI directory and reference them with a relative path. The example games use `@fontsource-variable/work-sans` and `@fontsource-variable/roboto-mono`, both bundled at build time
84
84
  - Use the `asset:`, `shared:`, and `blob:` scheme for files: it resolves to runtime-served URLs on the asset host (see [File handling](./file-handling.md))
85
- - Embed video through YouTube (standard or no-cookie); other frame sources are blocked
85
+ - Embed video in a UI through YouTube (standard or no-cookie); other frame sources are blocked. A facilitator guide can also play a video file it ships
86
86
  - Route any outbound network call through an engine, an endpoint, or a host capability rather than fetching from the UI (see [LLM integration](./llm-integration.md) and [Endpoints](./endpoints.md))
87
87
 
88
88
  ## What to avoid
@@ -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,26 @@ 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
+
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.
484
+
469
485
  ### Undoing and resetting
470
486
 
471
487
  Facilitators can revert the last tick or reset games, targeted at a specific team or all teams:
@@ -514,6 +530,28 @@ const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
514
530
 
515
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.
516
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
+
517
555
  ### Controlling the roster
518
556
 
519
557
  The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
@@ -808,14 +846,17 @@ Read the session itself:
808
846
  ```typescript
809
847
  import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
810
848
 
811
- const { sessionId, name, readOnly, waitingRoomOpen, joinPin } = useSessionUserInterfaceMeta();
849
+ const { sessionId, name, readOnly, waitingRoomOpen, joinPin, canSetLocale } =
850
+ useSessionUserInterfaceMeta();
812
851
  ```
813
852
 
853
+ `canSetLocale` is `true` where the host accepts [`setLocale`](#changing-the-language), and absent on a host that predates it.
854
+
814
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.
815
856
 
816
857
  ### useSessionUserInterfaceTeamLinks
817
858
 
818
- Get each team's facilitator-only URLs, so a game draws its own QR codes and join sheets:
859
+ Get each team's facilitator-only URLs, so a game draws its own QR codes, and its own join sheets where the host offers no `'print-sheets'` overlay (see [Opening host overlays](#opening-host-overlays)):
819
860
 
820
861
  ```typescript
821
862
  import { useSessionUserInterfaceTeamLinks } from '@seriousgaming/sdk/ui';
@@ -834,7 +875,7 @@ Find out which host overlays this host offers, before rendering a control for on
834
875
  import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
835
876
 
836
877
  const overlays = useSessionUserInterfaceHostOverlays();
837
- // HostOverlay[]: 'facilitator-guide' | 'print-sheets'
878
+ // HostOverlay[]: 'facilitator-guide' | 'print-sheets' | 'presentation'
838
879
  ```
839
880
 
840
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).
@@ -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`: