@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.
- package/dist/cli.js +366 -296
- package/dist/client.js +458 -388
- package/dist/core/participant-registry.d.ts +6 -0
- package/dist/core/session-roster.d.ts +4 -1
- package/dist/dev/console/assets/{index-BNLEVOQA.js → index-DEV8N0na.js} +47 -47
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/view/batch.d.ts +17 -9
- package/dist/dev/view/view.d.ts +2 -1
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-commands.md +4 -0
- package/dist/docs/api/sdk-e2e.md +4 -0
- package/dist/docs/api/sdk-tools-client.md +4 -0
- package/dist/docs/api/sdk-ui-testing.md +1 -0
- package/dist/docs/api/sdk-ui.md +33 -1
- package/dist/docs/api/sdk.md +3 -1
- package/dist/docs/changelog.md +16 -0
- package/dist/docs/guides/presentation.md +23 -9
- package/dist/docs/guides/session.md +47 -8
- package/dist/docs/guides/testing.md +9 -0
- package/dist/docs/guides/ui.md +33 -0
- package/dist/docs/guides/upgrading.md +11 -0
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/host/protocol.d.ts +27 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +4 -2
- 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-
|
|
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>
|
package/dist/dev/view/batch.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
61
|
-
|
|
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
|
-
*
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
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(
|
|
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
|
*
|
package/dist/dev/view/view.d.ts
CHANGED
|
@@ -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
|
-
|
|
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. */
|
package/dist/docs/api/index.md
CHANGED
|
@@ -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) |
|
|
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 |
|
package/dist/docs/api/sdk-e2e.md
CHANGED
|
@@ -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;
|
package/dist/docs/api/sdk-ui.md
CHANGED
|
@@ -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
|
|
package/dist/docs/api/sdk.md
CHANGED
|
@@ -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
|
package/dist/docs/changelog.md
CHANGED
|
@@ -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 `
|
|
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,
|
|
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 } =
|
|
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`:
|
package/dist/docs/guides/ui.md
CHANGED
|
@@ -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:
|
package/dist/host/protocol.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
102
|
+
"@seriousgaming/sdk": "^1.3.0"
|
|
103
103
|
},
|
|
104
104
|
"engines": {
|
|
105
105
|
"node": ">=24"
|