@seriousgaming/sdk-tools 1.2.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.
@@ -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-BNLEVOQA.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) | 48 functions, 3 classes, 38 constants, 25 interfaces, 37 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;
@@ -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;
@@ -287,6 +287,14 @@ const useSettingsEditorThemePreference: () => ThemePreference;
287
287
  const useUserInterfaceCallbacks: () => UserInterfaceCallbacks;
288
288
  ```
289
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
+
290
298
  ### useUserInterfaceCrossTeamData
291
299
 
292
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.
@@ -641,6 +649,14 @@ The React context behind `useUserInterfaceCallbacks`.
641
649
  const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
642
650
  ```
643
651
 
652
+ ### UserInterfaceCanRenameSelfContext
653
+
654
+ The React context behind `useUserInterfaceCanRenameSelf`.
655
+
656
+ ```ts
657
+ const UserInterfaceCanRenameSelfContext: import('react').Context<boolean>;
658
+ ```
659
+
644
660
  ### UserInterfaceCrossTeamDataContext
645
661
 
646
662
  The React context behind `useUserInterfaceCrossTeamData`.
@@ -931,6 +947,18 @@ interface PresentationGame {
931
947
  }
932
948
  ```
933
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
+
934
962
  ### PresentationSession
935
963
 
936
964
  The session a presentation is shown during: the shared store and every team, narrowed to what the presentation `reads`.
@@ -945,6 +973,9 @@ interface PresentationSession<
945
973
  completedTicks: number;
946
974
  data: SessionData<TTeamContext, TSharedContext>;
947
975
  teams: TeamInfo[];
976
+ participants?: Participant[];
977
+ joinLinks?: PresentationJoinLink[];
978
+ joinPin?: string | null;
948
979
  }
949
980
  ```
950
981
 
@@ -1192,7 +1223,7 @@ type EndpointFailureOutcome =
1192
1223
  A host-rendered overlay a session surface may ask the host to open.
1193
1224
 
1194
1225
  ```ts
1195
- type HostOverlay = 'facilitator-guide' | 'print-sheets';
1226
+ type HostOverlay = 'facilitator-guide' | 'print-sheets' | 'presentation';
1196
1227
  ```
1197
1228
 
1198
1229
  ### MutationFailure
@@ -1307,6 +1338,7 @@ type SessionMeta = {
1307
1338
  readOnly: boolean;
1308
1339
  waitingRoomOpen: boolean;
1309
1340
  joinPin: string | null;
1341
+ canSetLocale?: boolean;
1310
1342
  };
1311
1343
  ```
1312
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,22 @@ 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
+
34
50
  ## [1.2.0] — 2026-10-25
35
51
 
36
52
  ### Breaking Changes
@@ -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:
@@ -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).
@@ -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.
@@ -174,6 +174,8 @@ await renameOwnTeam('The Cartographers');
174
174
 
175
175
  It names no team: the host resolves the caller's, so a surface can only rename its own. Render `useUserInterfaceOwnTeam()?.name` rather than what you sent, because a facilitator may rename the same team at the same moment and the last write wins. A blank or over-long name is refused as a terminal `MutationError`. See [Letting a team name itself](./ui.md) for the full contract.
176
176
 
177
+ The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui.md#letting-a-participant-fix-their-own-name).
178
+
177
179
  ## Stopping the clock
178
180
 
179
181
  Opening the room pauses nothing. The decision belongs to the game, because only the author knows whether the simulation should keep advancing in the background:
@@ -121,9 +121,15 @@ export type HostPortMessage = {
121
121
  } | {
122
122
  type: 'setLocale';
123
123
  payload: UserInterfaceLocale;
124
- } | {
124
+ }
125
+ /**
126
+ * `canRenameSelf`: whether this host accepts `renameSelf` from this
127
+ * participant (§12.3). Send `true` only where it will; absent reads as `false`.
128
+ */
129
+ | {
125
130
  type: 'setParticipant';
126
131
  payload: Participant;
132
+ canRenameSelf?: boolean;
127
133
  } | {
128
134
  type: 'setViewerRole';
129
135
  role: ViewerRole;
@@ -319,6 +325,15 @@ export type IFramePortMessage = {
319
325
  type: 'renameOwnTeam';
320
326
  requestId?: string;
321
327
  name: string;
328
+ }
329
+ /**
330
+ * Rename the sending participant (§12.5). Names nobody: resolve the caller
331
+ * yourself, and refuse it from anyone not reported `canRenameSelf: true`.
332
+ */
333
+ | {
334
+ type: 'renameSelf';
335
+ requestId?: string;
336
+ name: string;
322
337
  } | {
323
338
  type: 'uploadBlob';
324
339
  requestId: string;
@@ -604,6 +619,15 @@ export type IFrameSessionPortMessage = {
604
619
  requestId?: string;
605
620
  open: boolean;
606
621
  }
622
+ /**
623
+ * The session's locale (§12.5). Session-wide; deny a locale the game does
624
+ * not declare in `supportedLocales`, and report `SessionMeta.canSetLocale`.
625
+ */
626
+ | {
627
+ type: 'setLocale';
628
+ requestId?: string;
629
+ locale: string;
630
+ }
607
631
  /**
608
632
  * Throw the walkthrough away and start it again at tick 0 (§5.7). Session-
609
633
  * wide like `setWaitingRoom`, and settling the same way. Denied while
@@ -617,7 +641,8 @@ export type IFrameSessionPortMessage = {
617
641
  * Ask the host to open one of its own overlays (§6.4). The host renders it;
618
642
  * this delegates the trigger alone. `target` is a team id for
619
643
  * `print-sheets`, and omitting it means every team. `facilitator-guide`
620
- * takes none: a game holds one guide, and a `target` is ignored. An overlay
644
+ * and `presentation` take none: a game holds one of each, and a `target`
645
+ * is ignored. An overlay
621
646
  * the host does not offer, or a team id not in the session, settles as
622
647
  * denied.
623
648
  */
@@ -26,7 +26,7 @@ export declare const MANIFEST_VERSION = 3;
26
26
  * section is stamped, it is the revision at the top of the appendix.
27
27
  * `spec-revision.test.ts` holds the two together.
28
28
  */
29
- export declare const SPEC_REVISION = "1.2";
29
+ export declare const SPEC_REVISION = "1.3";
30
30
  /**
31
31
  * Whether specification revision `revision` is later than `than`, both as
32
32
  * `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
package/dist/runtime.js CHANGED
@@ -302,7 +302,7 @@ function readTickControllerResult(label, result) {
302
302
 
303
303
  // cli/runtime/manifest-version.ts
304
304
  var MANIFEST_VERSION = 3;
305
- var SPEC_REVISION = "1.2";
305
+ var SPEC_REVISION = "1.3";
306
306
  function isLaterSpecRevision(revision, than) {
307
307
  const [major, minor] = revision.split(".").map(Number);
308
308
  const [thanMajor, thanMinor] = than.split(".").map(Number);
@@ -310,7 +310,9 @@ function isLaterSpecRevision(revision, than) {
310
310
  }
311
311
  var SUPPORTED_FEATURES = [
312
312
  // A validator's `Scenario` gate (§15.8).
313
- "scenario-validation"
313
+ "scenario-validation",
314
+ // The presentation as a host overlay a session surface may open (§6.4).
315
+ "presentation-overlay"
314
316
  ];
315
317
  function unsupportedFeatures(manifest) {
316
318
  return (manifest.requires ?? []).filter((feature) => !SUPPORTED_FEATURES.includes(feature));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seriousgaming/sdk-tools",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "SDK tooling for building Serious Gaming games",
5
5
  "homepage": "https://sdk.seriousgaming.com/",
6
6
  "license": "SEE LICENSE IN LICENSE",
@@ -70,7 +70,7 @@
70
70
  "@mui/icons-material": "^9.4.0",
71
71
  "@mui/material": "^9.4.0",
72
72
  "@playwright/test": "^1.64.0",
73
- "@seriousgaming/sdk": "1.2.0",
73
+ "@seriousgaming/sdk": "1.3.0",
74
74
  "@testing-library/jest-dom": "^7.0.1",
75
75
  "@testing-library/react": "^16.3.3",
76
76
  "@types/adm-zip": "^0.5.8",
@@ -99,7 +99,7 @@
99
99
  "vitest": "^5.0.3"
100
100
  },
101
101
  "peerDependencies": {
102
- "@seriousgaming/sdk": "^1.2.0"
102
+ "@seriousgaming/sdk": "^1.3.0"
103
103
  },
104
104
  "engines": {
105
105
  "node": ">=24"