@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
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Dress every surface of your game in the host's colours, logo and fonts, so a game run by a white-label host looks like that host's product.
|
|
4
4
|
|
|
5
|
-
**Keywords:** theme, branding, white-label, brand, logo, fonts, colours, dark mode, createSurfaceTheme, useBrand, useBrandLogo, brandFromTheme, SurfaceLoading, loading screen, --brand, brand file
|
|
5
|
+
**Keywords:** theme, branding, white-label, brand, logo, fonts, colours, dark mode, createSurfaceTheme, useBrand, useBrandLogo, useBrandIcon, icon, brandFromTheme, SurfaceLoading, loading screen, --brand, brand file
|
|
6
6
|
|
|
7
7
|
## What the host sends
|
|
8
8
|
|
|
@@ -11,7 +11,7 @@ Every surface receives a theme from the host, and receives it again whenever it
|
|
|
11
11
|
- **A mode**: `'light'` or `'dark'`, the scheme the surface should paint in now
|
|
12
12
|
- **Six colour roles for each mode**: `primary`, `secondary`, `success`, `error`, `warning` and `info`, each with a `contrastText` the host guarantees meets WCAG AA (4.5:1) against it
|
|
13
13
|
- **Page colours for each mode**: `background` (the page), `surface` (cards and panels) and `text`, with `text` readable on both
|
|
14
|
-
- **A brand**: always its `name`, and, where the brand has them, a `logo` for each background (`onLight` and `onDark`),
|
|
14
|
+
- **A brand**: always its `name`, and, where the brand has them, a `logo` and a square `icon` for each background (`onLight` and `onDark`), and the `fonts` its headings and body text are set in
|
|
15
15
|
|
|
16
16
|
A brand with no logo, icon or fonts is normal, and your game must look right with just a name. The SDK never invents a logo of its own: a white-label host never shows anybody else's.
|
|
17
17
|
|
|
@@ -63,6 +63,19 @@ export function HostLogo() {
|
|
|
63
63
|
|
|
64
64
|
`logo.drawnFor` says which background the artwork was made for. It differs from the current mode only when the host sent a single variant, which you can meet by drawing the logo on a panel of that colour.
|
|
65
65
|
|
|
66
|
+
`useBrandIcon()` does the same for the square mark, for a space too small for the logo, such as a compact header or a tab:
|
|
67
|
+
|
|
68
|
+
```tsx
|
|
69
|
+
import { useBrandIcon } from '@seriousgaming/sdk/ui';
|
|
70
|
+
|
|
71
|
+
export function HostIcon() {
|
|
72
|
+
const icon = useBrandIcon();
|
|
73
|
+
return icon ? <img src={icon.src} alt={icon.alt} width={24} height={24} /> : null;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A host built for an earlier version sends one icon for both backgrounds, and the hook returns it in either mode.
|
|
78
|
+
|
|
66
79
|
`useBrand()` returns the whole brand. Use its `name` in copy rather than naming a platform, allowing for the empty name a host that predates brands leaves:
|
|
67
80
|
|
|
68
81
|
```tsx
|
|
@@ -70,7 +83,7 @@ const { name } = useBrand();
|
|
|
70
83
|
const title = name ? t('welcomeTo', { name }) : t('welcome');
|
|
71
84
|
```
|
|
72
85
|
|
|
73
|
-
|
|
86
|
+
All three hooks work on every surface. Keep a scenario's own logo, such as a fictional company in the case study, as content in a setting or an asset. The host's brand is for the interface around the game.
|
|
74
87
|
|
|
75
88
|
## Fonts
|
|
76
89
|
|
|
@@ -160,6 +173,7 @@ The brand joins the menu and is selected. Repeat `--brand` for more than one; th
|
|
|
160
173
|
```
|
|
161
174
|
|
|
162
175
|
- `name` is required, and everything else is optional
|
|
176
|
+
- `icon` is one file for both backgrounds, or `{ "onLight": …, "onDark": … }` like `logo`
|
|
163
177
|
- `loader` is an animation for the dev server's own loading screen, as a host would show its own: an animated SVG, WebP or GIF. It is never sent to your game
|
|
164
178
|
- A colour role a mode leaves out keeps the Serious Gaming one. Page colours a mode leaves out are a plain page's, never another brand's
|
|
165
179
|
- The dev server works out every `contrastText`, and a `text` that is not readable on both `background` and `surface` is replaced with black or white, or the page with a plain one where neither reads
|
|
@@ -170,7 +184,7 @@ Keep brand files beside the games that use them, not inside a game package: a br
|
|
|
170
184
|
|
|
171
185
|
## Testing
|
|
172
186
|
|
|
173
|
-
`createMockBrand()` from `@seriousgaming/sdk/ui/testing` gives a name and a logo for each background, as `data:` URLs. Pass it in a mock theme to test a component that reads the brand:
|
|
187
|
+
`createMockBrand()` from `@seriousgaming/sdk/ui/testing` gives a name, and a logo and an icon for each background, as `data:` URLs. Pass it in a mock theme to test a component that reads the brand:
|
|
174
188
|
|
|
175
189
|
```tsx
|
|
176
190
|
import {
|
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.
|
|
@@ -663,6 +663,25 @@ pnpm run test:e2e
|
|
|
663
663
|
- Then search by hand for the changes no tool sees, listed at the top of this guide
|
|
664
664
|
- Finally, play a round in the dev server and check each surface, the timer and completion
|
|
665
665
|
|
|
666
|
+
## After 1.0
|
|
667
|
+
|
|
668
|
+
A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md).
|
|
669
|
+
|
|
670
|
+
### 1.2: give `Brand.icon` a variant for each background
|
|
671
|
+
|
|
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
|
+
|
|
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
|
+
|
|
666
685
|
## Before you publish
|
|
667
686
|
|
|
668
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:
|
|
@@ -56,7 +56,7 @@ Bundle a facilitator guide with your game: markdown chapters shown on the facili
|
|
|
56
56
|
pnpm run sdk build --validate-only
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Validation warns when a locale is missing a chapter the reference locale has, and fails on a malformed video block or an image that does not resolve. Then open `/guide` in the dev server: the page has its own locale picker and a print button.
|
|
59
|
+
Validation warns when a locale is missing a chapter the reference locale has, and fails on a malformed video block, or an image or video file that does not resolve. Then open `/guide` in the dev server: the page has its own locale picker and a print button.
|
|
60
60
|
|
|
61
61
|
## Troubleshooting
|
|
62
62
|
|
|
@@ -64,7 +64,7 @@ Validation warns when a locale is missing a chapter the reference locale has, an
|
|
|
64
64
|
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
65
65
|
| `new guide` fails with `RESOURCE_EXISTS` | The slot is filled: use `update guide` and edit the chapters, or `pnpm run sdk delete guide --yes` first |
|
|
66
66
|
| A chapter shows a 'not yet translated' note | That file is missing from the selected locale's directory; content falls back per file to the reference locale |
|
|
67
|
-
| A video renders an error block | The provider must be `youtube`
|
|
67
|
+
| A video renders an error block | The provider must be `youtube` with an 11-character YouTube id, or `file` with a `src` in `assets/` |
|
|
68
68
|
| An image does not display | The path must resolve inside `guide/`, for example `../../assets/diagram.png` from a chapter |
|
|
69
69
|
| Raw HTML appears as text | By design: the renderer escapes HTML. Use markdown, admonitions, and video blocks |
|
|
70
70
|
|
|
@@ -72,15 +72,15 @@ Then open `/guide` in the dev server and switch scenario: the values change and
|
|
|
72
72
|
|
|
73
73
|
## Troubleshooting
|
|
74
74
|
|
|
75
|
-
| Problem | Solution
|
|
76
|
-
| --------------------------------------------------- |
|
|
77
|
-
| 'reads settings "…", which the guide does not list' | Add the settings resource to the guide's `settings`
|
|
78
|
-
| 'can show only a number or text' | `:setting` cannot show a true-or-false value or a list. Use a `:::when` for a true-or-false setting
|
|
79
|
-
| 'needs is="…", since it is not true or false' | Compare the setting with `is="value"`
|
|
80
|
-
| 'sits inside another :::when' | Conditions do not nest. Give the inner block its own condition
|
|
81
|
-
|
|
|
82
|
-
| 'is empty under the defaults and every scenario' | No scenario turns the condition on. Check the `is` value, or the scenario's settings
|
|
83
|
-
| A red error shows in the guide in place of a value | The setting could not be read for this session. Run the build validation, which names the cause
|
|
75
|
+
| Problem | Solution |
|
|
76
|
+
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| 'reads settings "…", which the guide does not list' | Add the settings resource to the guide's `settings` |
|
|
78
|
+
| 'can show only a number or text' | `:setting` cannot show a true-or-false value or a list. Use a `:::when` for a true-or-false setting |
|
|
79
|
+
| 'needs is="…", since it is not true or false' | Compare the setting with `is="value"` |
|
|
80
|
+
| 'sits inside another :::when' | Conditions do not nest. Give the inner block its own condition |
|
|
81
|
+
| 'this ::: closes nothing' | The outer block closed early, at an admonition's `:::`, so the text after it shows in every scenario. Give the `:::when` more colons than the admonitions inside it (`::::when` … `::::`) |
|
|
82
|
+
| 'is empty under the defaults and every scenario' | No scenario turns the condition on. Check the `is` value, or the scenario's settings |
|
|
83
|
+
| A red error shows in the guide in place of a value | The setting could not be read for this session. Run the build validation, which names the cause |
|
|
84
84
|
|
|
85
85
|
## Related
|
|
86
86
|
|
package/dist/guide/settings.d.ts
CHANGED
|
@@ -64,4 +64,11 @@ export declare function evaluateChapter(markdown: string, settings: GuideSetting
|
|
|
64
64
|
export declare function isChapterEmpty(markdown: string, settings: GuideSettings): boolean;
|
|
65
65
|
/** Every setting a chapter names, for the build to check against the declared schemas. */
|
|
66
66
|
export declare function settingReferences(markdown: string): SettingReference[];
|
|
67
|
+
/**
|
|
68
|
+
* The lines holding a container fence that closes nothing. A fence closes the
|
|
69
|
+
* innermost open container whatever its name, so a `:::when` holding a
|
|
70
|
+
* `:::say` ends at the say's closing fence and leaves its own as text: what
|
|
71
|
+
* follows the say then shows in every scenario.
|
|
72
|
+
*/
|
|
73
|
+
export declare function strayFences(markdown: string): number[];
|
|
67
74
|
export {};
|
|
@@ -9,8 +9,16 @@
|
|
|
9
9
|
* id: dQw4w9WgXcQ
|
|
10
10
|
* ```
|
|
11
11
|
*
|
|
12
|
+
* ```video
|
|
13
|
+
* provider: file
|
|
14
|
+
* src: ../../assets/intro.mp4
|
|
15
|
+
* title: How a round runs
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
12
18
|
* IDs are validated against a strict per-provider regex and never
|
|
13
|
-
* interpolated raw into a URL.
|
|
19
|
+
* interpolated raw into a URL. A `file` video names files in the guide's
|
|
20
|
+
* `assets/`, and is returned as paths relative to it, so each renderer maps
|
|
21
|
+
* them onto its own asset route. Unknown providers or malformed blocks must
|
|
14
22
|
* render as an inert error block, never a passthrough.
|
|
15
23
|
*
|
|
16
24
|
* This module is browser-safe: it is imported by both the CLI content
|
|
@@ -24,16 +32,40 @@ export interface VideoProvider {
|
|
|
24
32
|
/** Hosts the embed iframe may load from (for frame-src CSP) */
|
|
25
33
|
embedHosts: string[];
|
|
26
34
|
}
|
|
35
|
+
/** The providers a guide embeds in an iframe. `file` plays in a `<video>` instead. */
|
|
27
36
|
export declare const VIDEO_PROVIDERS: Record<string, VideoProvider>;
|
|
37
|
+
export declare const FILE_VIDEO_PROVIDER = "file";
|
|
38
|
+
/** What each file a `file` video names may be, by extension. */
|
|
39
|
+
export declare const FILE_VIDEO_EXTENSIONS: {
|
|
40
|
+
readonly src: readonly ["mp4", "webm"];
|
|
41
|
+
readonly poster: readonly ["png", "jpg", "jpeg", "gif", "webp", "avif"];
|
|
42
|
+
readonly captions: readonly ["vtt"];
|
|
43
|
+
};
|
|
28
44
|
export type ParsedVideoBlock = {
|
|
29
45
|
ok: true;
|
|
46
|
+
kind: 'embed';
|
|
30
47
|
provider: string;
|
|
31
48
|
id: string;
|
|
32
49
|
embedUrl: string;
|
|
50
|
+
} | {
|
|
51
|
+
ok: true;
|
|
52
|
+
kind: 'file';
|
|
53
|
+
provider: typeof FILE_VIDEO_PROVIDER;
|
|
54
|
+
/** Paths relative to the guide's `assets/`, decoded */
|
|
55
|
+
src: string;
|
|
56
|
+
poster?: string;
|
|
57
|
+
captions?: string;
|
|
58
|
+
/** Shown wherever the video cannot play, as an image's alt text is */
|
|
59
|
+
title?: string;
|
|
33
60
|
} | {
|
|
34
61
|
ok: false;
|
|
35
62
|
error: string;
|
|
36
63
|
};
|
|
64
|
+
/**
|
|
65
|
+
* The path inside the guide's `assets/` that a chapter-relative reference
|
|
66
|
+
* names, decoded, or undefined when it is absolute or lands anywhere else.
|
|
67
|
+
*/
|
|
68
|
+
export declare function guideAssetPath(reference: string): string | undefined;
|
|
37
69
|
/**
|
|
38
70
|
* Parse and validate the body of a `video` fenced block. Returns a typed
|
|
39
71
|
* error (never throws) so renderers can show an inert error block and
|
package/dist/host/index.d.ts
CHANGED
|
@@ -12,8 +12,9 @@
|
|
|
12
12
|
* may change in a minor release.
|
|
13
13
|
*
|
|
14
14
|
* It also carries how the host reads a facilitator guide (§6.13): which locale
|
|
15
|
-
* each chapter is read from,
|
|
16
|
-
* platform shows exactly the guide the dev
|
|
15
|
+
* each chapter is read from, how settings in its markdown evaluate, and what a
|
|
16
|
+
* `video` block embeds or plays, so a platform shows exactly the guide the dev
|
|
17
|
+
* server shows.
|
|
17
18
|
*/
|
|
18
19
|
export { HostChannel } from './host-channel.js';
|
|
19
20
|
export type { FrameLike, GuestMessage, HostChannelOptions, HostMessage, TeardownReason, WindowLike, } from './host-channel.js';
|
|
@@ -24,3 +25,4 @@ export type { AssetUrls, HostSettingsEditorPortMessage, HostPortMessage, HostPre
|
|
|
24
25
|
export { contrastTextFor, neutralsFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
|
|
25
26
|
export { chapterSources, referenceLocale, type ChapterSource } from '../guide/locale.js';
|
|
26
27
|
export { evaluateChapter, evaluateWhen, formatSettingValue, isChapterEmpty, lookupSetting, remarkGuideSettings, type GuideSettings, } from '../guide/settings.js';
|
|
28
|
+
export { FILE_VIDEO_EXTENSIONS, guideAssetPath, parseVideoBlock, VIDEO_PROVIDERS, type ParsedVideoBlock, type VideoProvider, } from '../guide/video-registry.js';
|
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
|
*/
|
package/dist/host.js
CHANGED
|
@@ -12037,20 +12037,151 @@ function evaluateChapter(markdown, settings, locale) {
|
|
|
12037
12037
|
function isChapterEmpty(markdown, settings) {
|
|
12038
12038
|
return evaluateChapter(markdown, settings, "en").children.length === 0;
|
|
12039
12039
|
}
|
|
12040
|
+
|
|
12041
|
+
// cli/guide/video-registry.ts
|
|
12042
|
+
var VIDEO_PROVIDERS = {
|
|
12043
|
+
youtube: {
|
|
12044
|
+
idPattern: /^[A-Za-z0-9_-]{11}$/,
|
|
12045
|
+
embedUrl: (id) => `https://www.youtube-nocookie.com/embed/${id}`,
|
|
12046
|
+
embedHosts: ["www.youtube-nocookie.com"]
|
|
12047
|
+
}
|
|
12048
|
+
};
|
|
12049
|
+
var FILE_VIDEO_PROVIDER = "file";
|
|
12050
|
+
var FILE_VIDEO_EXTENSIONS = {
|
|
12051
|
+
src: ["mp4", "webm"],
|
|
12052
|
+
poster: ["png", "jpg", "jpeg", "gif", "webp", "avif"],
|
|
12053
|
+
captions: ["vtt"]
|
|
12054
|
+
};
|
|
12055
|
+
var ALLOWED_KEYS = {
|
|
12056
|
+
youtube: /* @__PURE__ */ new Set(["provider", "id"]),
|
|
12057
|
+
[FILE_VIDEO_PROVIDER]: /* @__PURE__ */ new Set(["provider", "src", "title", "poster", "captions"])
|
|
12058
|
+
};
|
|
12059
|
+
var SUPPORTED_PROVIDERS = [...Object.keys(VIDEO_PROVIDERS), FILE_VIDEO_PROVIDER];
|
|
12060
|
+
var CHAPTER_BASE = "https://guide.invalid/content/locale/chapter.md";
|
|
12061
|
+
function guideAssetPath(reference) {
|
|
12062
|
+
if (/^[a-z][a-z0-9+.-]*:/i.test(reference) || reference.startsWith("/")) return void 0;
|
|
12063
|
+
if (reference.includes("\\") || /[?#]/.test(reference)) return void 0;
|
|
12064
|
+
let resolved;
|
|
12065
|
+
try {
|
|
12066
|
+
resolved = new URL(reference, CHAPTER_BASE);
|
|
12067
|
+
} catch {
|
|
12068
|
+
return void 0;
|
|
12069
|
+
}
|
|
12070
|
+
if (resolved.origin !== "https://guide.invalid" || !resolved.pathname.startsWith("/assets/")) {
|
|
12071
|
+
return void 0;
|
|
12072
|
+
}
|
|
12073
|
+
try {
|
|
12074
|
+
const path2 = decodeURIComponent(resolved.pathname.slice("/assets/".length));
|
|
12075
|
+
const segments = path2.split("/");
|
|
12076
|
+
return segments.some((s) => s === "" || s === "." || s === ".." || s.includes("\\")) ? void 0 : path2;
|
|
12077
|
+
} catch {
|
|
12078
|
+
return void 0;
|
|
12079
|
+
}
|
|
12080
|
+
}
|
|
12081
|
+
function extensionOf(path2) {
|
|
12082
|
+
const dot = path2.lastIndexOf(".");
|
|
12083
|
+
return dot === -1 ? "" : path2.slice(dot + 1).toLowerCase();
|
|
12084
|
+
}
|
|
12085
|
+
function parseVideoBlock(body) {
|
|
12086
|
+
const entries = {};
|
|
12087
|
+
for (const rawLine of body.split("\n")) {
|
|
12088
|
+
const line = rawLine.trim();
|
|
12089
|
+
if (line.length === 0) continue;
|
|
12090
|
+
const match = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
|
|
12091
|
+
if (!match) {
|
|
12092
|
+
return { ok: false, error: `Malformed line in video block: "${line}"` };
|
|
12093
|
+
}
|
|
12094
|
+
const key = match[1];
|
|
12095
|
+
const value = match[2].trim();
|
|
12096
|
+
if (key in entries) {
|
|
12097
|
+
return { ok: false, error: `Duplicate key "${key}" in video block` };
|
|
12098
|
+
}
|
|
12099
|
+
entries[key] = value;
|
|
12100
|
+
}
|
|
12101
|
+
const provider = entries.provider;
|
|
12102
|
+
if (!provider) {
|
|
12103
|
+
return { ok: false, error: 'Video block is missing "provider"' };
|
|
12104
|
+
}
|
|
12105
|
+
const allowed = ALLOWED_KEYS[provider];
|
|
12106
|
+
if (!allowed) {
|
|
12107
|
+
return {
|
|
12108
|
+
ok: false,
|
|
12109
|
+
error: `Unknown video provider "${provider}". Supported providers: ${SUPPORTED_PROVIDERS.join(", ")}`
|
|
12110
|
+
};
|
|
12111
|
+
}
|
|
12112
|
+
for (const key of Object.keys(entries)) {
|
|
12113
|
+
if (!allowed.has(key)) {
|
|
12114
|
+
return { ok: false, error: `Unknown key "${key}" in video block` };
|
|
12115
|
+
}
|
|
12116
|
+
}
|
|
12117
|
+
if (provider === FILE_VIDEO_PROVIDER) return parseFileVideo(entries);
|
|
12118
|
+
const registered = VIDEO_PROVIDERS[provider];
|
|
12119
|
+
const id = entries.id;
|
|
12120
|
+
if (!id) {
|
|
12121
|
+
return { ok: false, error: 'Video block is missing "id"' };
|
|
12122
|
+
}
|
|
12123
|
+
if (!registered.idPattern.test(id)) {
|
|
12124
|
+
return {
|
|
12125
|
+
ok: false,
|
|
12126
|
+
error: `Video id "${id}" is not a valid ${provider} id`
|
|
12127
|
+
};
|
|
12128
|
+
}
|
|
12129
|
+
return { ok: true, kind: "embed", provider, id, embedUrl: registered.embedUrl(id) };
|
|
12130
|
+
}
|
|
12131
|
+
function parseFileVideo(entries) {
|
|
12132
|
+
if (!entries.src) {
|
|
12133
|
+
return { ok: false, error: 'Video block is missing "src"' };
|
|
12134
|
+
}
|
|
12135
|
+
const files = {};
|
|
12136
|
+
for (const key of Object.keys(
|
|
12137
|
+
FILE_VIDEO_EXTENSIONS
|
|
12138
|
+
)) {
|
|
12139
|
+
const reference = entries[key];
|
|
12140
|
+
if (reference === void 0) continue;
|
|
12141
|
+
const path2 = guideAssetPath(reference);
|
|
12142
|
+
if (!path2) {
|
|
12143
|
+
return {
|
|
12144
|
+
ok: false,
|
|
12145
|
+
error: `Video ${key} "${reference}" must be a file in the guide's assets/ directory`
|
|
12146
|
+
};
|
|
12147
|
+
}
|
|
12148
|
+
const extensions = FILE_VIDEO_EXTENSIONS[key];
|
|
12149
|
+
if (!extensions.includes(extensionOf(path2))) {
|
|
12150
|
+
return {
|
|
12151
|
+
ok: false,
|
|
12152
|
+
error: `Video ${key} "${reference}" must be a ${extensions.map((e) => `.${e}`).join(", ")} file`
|
|
12153
|
+
};
|
|
12154
|
+
}
|
|
12155
|
+
files[key] = path2;
|
|
12156
|
+
}
|
|
12157
|
+
return {
|
|
12158
|
+
ok: true,
|
|
12159
|
+
kind: "file",
|
|
12160
|
+
provider: FILE_VIDEO_PROVIDER,
|
|
12161
|
+
src: files.src,
|
|
12162
|
+
...files.poster ? { poster: files.poster } : {},
|
|
12163
|
+
...files.captions ? { captions: files.captions } : {},
|
|
12164
|
+
...entries.title ? { title: entries.title } : {}
|
|
12165
|
+
};
|
|
12166
|
+
}
|
|
12040
12167
|
export {
|
|
12168
|
+
FILE_VIDEO_EXTENSIONS,
|
|
12041
12169
|
HostChannel,
|
|
12042
12170
|
SURFACES,
|
|
12043
12171
|
THEME_COLOR_ROLES,
|
|
12044
12172
|
UI_PROTOCOL_VERSION,
|
|
12173
|
+
VIDEO_PROVIDERS,
|
|
12045
12174
|
chapterSources,
|
|
12046
12175
|
contrastTextFor,
|
|
12047
12176
|
evaluateChapter,
|
|
12048
12177
|
evaluateWhen,
|
|
12049
12178
|
formatSettingValue,
|
|
12179
|
+
guideAssetPath,
|
|
12050
12180
|
isChapterEmpty,
|
|
12051
12181
|
isPlayerSurface,
|
|
12052
12182
|
lookupSetting,
|
|
12053
12183
|
neutralsFor,
|
|
12184
|
+
parseVideoBlock,
|
|
12054
12185
|
referenceLocale,
|
|
12055
12186
|
remarkGuideSettings,
|
|
12056
12187
|
requiredMessagesFor,
|
|
@@ -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));
|
|
@@ -287,7 +287,7 @@ expect(session.team(0).context.results.Day).toBe(1);
|
|
|
287
287
|
## User interfaces
|
|
288
288
|
|
|
289
289
|
- **Default to MUI** (`@mui/material`), as the starter game does. Build each surface's theme with `createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), { ...your shapes })`, as `ui/src/theme.ts` does: it applies the host's colours, their `contrastText`, and the brand's fonts. Another library must integrate with `useUserInterfaceTheme` the same way, so colours and dark mode work, and text on a theme colour uses that colour's `contrastText` (`colors.contrastText.primary`)
|
|
290
|
-
- **Honour the host's brand.** A white-label host may send a logo and fonts; `useBrandLogo()` gives the logo for the current mode, or nothing, as `ui/src/HostLogo.tsx` shows. Do not hard-code a platform's logo in its place: the host's brand is the host's to send
|
|
290
|
+
- **Honour the host's brand.** A white-label host may send a logo and fonts; `useBrandLogo()` gives the logo for the current mode, or nothing, as `ui/src/HostLogo.tsx` shows, and `useBrandIcon()` the square mark. Do not hard-code a platform's logo in its place: the host's brand is the host's to send. For join sheets, open the host's `'print-sheets'` overlay where it offers one rather than drawing your own
|
|
291
291
|
- **Await writes.** `setData` rejects when the host refuses the write. Route writes through `useMutationReporter`, as `ui/src/writes.ts` does; on a `conflict`, offer `failure.retry` behind a 'Try again' button
|
|
292
292
|
- **Endpoint calls fail typed.** `callbacks.endpoints['<name>'](request)` rejects with an `EndpointError` whose `kind` says why; a non-empty `applied` means some effects landed. Never retry one automatically
|
|
293
293
|
- **A viewer's own choices** (a tab, a collapsed panel) go in `useViewerStorage(key, initial)`, never `localStorage`, which collides across sessions
|
|
@@ -15,19 +15,25 @@ Facilitator guides are content, not code: per-locale markdown chapters plus shar
|
|
|
15
15
|
```
|
|
16
16
|
2. **Create or change the guide.** The starter game already has one, so edit its chapters directly and change its bundle with `pnpm run sdk update guide`; `new guide` refuses while `guide/` exists. In an empty package, `pnpm run sdk new guide '{ ... }'`. Declare every locale up front: the scaffold creates a chapter skeleton per declared locale, and the per-locale `name` is the title the host renders.
|
|
17
17
|
3. **Write the chapters** in `guide/content/<locale>/`. Chapters are ordered by file name (number them `01-`, `02-`, …) and file names must be identical across locales.
|
|
18
|
-
4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks or image references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
|
|
18
|
+
4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks, or image or video references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
|
|
19
19
|
|
|
20
20
|
## Content format
|
|
21
21
|
|
|
22
22
|
- Admonitions are container directives: `:::note`, `:::warning`, `:::tip`, plus the facilitation-specific `:::say`, `:::do`, and `:::timing`. Unknown types render as error blocks
|
|
23
23
|
- Headings build the table of contents (chapter H1 plus H2 to H3); end a heading with `{-}` to omit it
|
|
24
24
|
- Images go in the shared `assets/` directory, referenced relatively (`../../assets/diagram.png` from a chapter)
|
|
25
|
-
- Video embeds are fenced `video` blocks validated against a closed registry (
|
|
25
|
+
- Video embeds are fenced `video` blocks validated against a closed registry: `youtube` with an `id`, or `file` with a `src` in `assets/` (and optionally `title`, `poster` and `captions`):
|
|
26
26
|
````markdown
|
|
27
27
|
```video
|
|
28
28
|
provider: youtube
|
|
29
29
|
id: dQw4w9WgXcQ
|
|
30
30
|
```
|
|
31
|
+
|
|
32
|
+
```video
|
|
33
|
+
provider: file
|
|
34
|
+
src: ../../assets/intro.mp4
|
|
35
|
+
title: How a round runs
|
|
36
|
+
```
|
|
31
37
|
````
|
|
32
38
|
- A chapter can follow the session's settings: list the settings resources the guide reads in `guide.sdk.json`'s `settings`, show a value with `:setting[engine.totalWeeks]`, and show a block only in some scenarios with `:::when{setting="engine.observers"}` (`is="…"` to compare, `not` to invert). The build checks every name and value. See `recipes/make-a-guide-follow-the-scenario.md`
|
|
33
39
|
- Raw HTML never renders: it is escaped to visible text. Use markdown, admonitions, and video blocks only
|
|
@@ -8,7 +8,9 @@ import { type GuideSettingsContext } from './guide-settings-validator.js';
|
|
|
8
8
|
* - Locale completeness: each declared locale should mirror the reference
|
|
9
9
|
* locale's chapter file set (warnings — fallback handles gaps at runtime)
|
|
10
10
|
* - Video blocks: provider and parameters must validate against the closed
|
|
11
|
-
* provider registry (errors — these render as inert error blocks)
|
|
11
|
+
* provider registry (errors — these render as inert error blocks), and each
|
|
12
|
+
* file a `file` video names must exist in `assets/` (errors), warning above
|
|
13
|
+
* a size threshold
|
|
12
14
|
* - Referenced assets: relative image references must resolve to a file
|
|
13
15
|
* inside the guide directory (errors)
|
|
14
16
|
* - Settings: every `:setting` and `:::when` names a value the guide declares
|
|
@@ -23,6 +25,8 @@ export interface GuideContentValidationResult {
|
|
|
23
25
|
errors: string[];
|
|
24
26
|
warnings: string[];
|
|
25
27
|
}
|
|
28
|
+
/** Above this a video file slows every upload of the package enough to say so. */
|
|
29
|
+
export declare const LARGE_VIDEO_FILE_BYTES: number;
|
|
26
30
|
export { referenceLocale };
|
|
27
31
|
export declare function validateFacilitatorGuideContent(options: {
|
|
28
32
|
definition: FacilitatorGuideDefinition;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ErrorObject } from 'ajv';
|
|
2
|
-
import type { JSONSchema7 } from 'json-schema';
|
|
2
|
+
import type { JSONSchema7, JSONSchema7Definition } from 'json-schema';
|
|
3
3
|
import { type Finding } from './findings.js';
|
|
4
4
|
/**
|
|
5
5
|
* Validation result
|
|
@@ -108,8 +108,16 @@ export declare function validateSettingsOverrides(overrides: Record<string, unkn
|
|
|
108
108
|
* through (see {@link withoutRequired}), even against a schema still carrying
|
|
109
109
|
* the top-level `required` that `sdk build` rejects: faulting partial
|
|
110
110
|
* overrides on it is how #389 broke every scenario, and on a nested one how
|
|
111
|
-
* #682 broke a setup UI that spread an object.
|
|
112
|
-
*
|
|
113
|
-
* still apply to the keys that
|
|
111
|
+
* #682 broke a setup UI that spread an object. An undeclared key is
|
|
112
|
+
* refused even where the schema leaves its object open (see
|
|
113
|
+
* {@link closed}), and type and value checks still apply to the keys that
|
|
114
|
+
* are present.
|
|
114
115
|
*/
|
|
115
116
|
export declare function validatePartialOverride(override: unknown, settingsSchema: JSONSchema7): ErrorObject[] | null;
|
|
117
|
+
/**
|
|
118
|
+
* Where a settings schema leaves a plain object open, as JSON pointers into
|
|
119
|
+
* the schema (`''` for the top level), for the build to warn about. Each is
|
|
120
|
+
* closed all the same when an override is checked (see {@link closed}), but a
|
|
121
|
+
* runtime or an agent reading the schema would not know it.
|
|
122
|
+
*/
|
|
123
|
+
export declare function openSettingsObjects(schema: JSONSchema7Definition, at?: string): string[];
|
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"
|