@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.
- package/dist/cli.js +565 -309
- package/dist/client.js +608 -352
- package/dist/core/participant-registry.d.ts +6 -0
- package/dist/core/session-roster.d.ts +4 -1
- package/dist/dev/brands.d.ts +20 -3
- package/dist/dev/console/assets/{index-qxHcu9fJ.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 +2 -1
- package/dist/docs/api/sdk-ui.md +54 -3
- package/dist/docs/api/sdk.md +3 -1
- package/dist/docs/changelog.md +41 -0
- package/dist/docs/guides/guide.md +35 -4
- package/dist/docs/guides/presentation.md +23 -9
- package/dist/docs/guides/production-constraints.md +1 -1
- package/dist/docs/guides/session.md +50 -9
- package/dist/docs/guides/testing.md +9 -0
- package/dist/docs/guides/theming-and-branding.md +18 -4
- package/dist/docs/guides/ui.md +33 -0
- package/dist/docs/guides/upgrading.md +19 -0
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/docs/recipes/create-guide.md +2 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +9 -9
- package/dist/guide/settings.d.ts +7 -0
- package/dist/guide/video-registry.d.ts +33 -1
- package/dist/host/index.d.ts +4 -2
- package/dist/host/protocol.d.ts +27 -2
- package/dist/host.js +131 -0
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +4 -2
- package/dist/templates/package/CLAUDE.md.template +1 -1
- package/dist/templates/package/claude/rules/workflow-create-guide.md +8 -2
- package/dist/validation/facilitator-guide-validator.d.ts +5 -1
- package/dist/validation/schema-validation.d.ts +12 -4
- 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
|
@@ -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 `
|
|
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;
|
package/dist/docs/api/sdk-ui.md
CHANGED
|
@@ -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 `
|
|
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?:
|
|
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
|
|
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,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
|
|
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.
|
|
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
|
|
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 `
|
|
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,
|
|
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 } =
|
|
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`:
|