@seriousgaming/sdk-tools 1.1.0 → 1.2.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 +200 -14
- package/dist/client.js +199 -13
- package/dist/dev/brands.d.ts +20 -3
- package/dist/dev/console/assets/{index-qxHcu9fJ.js → index-BNLEVOQA.js} +9 -9
- package/dist/dev/console/index.html +1 -1
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-ui-testing.md +1 -1
- package/dist/docs/api/sdk-ui.md +21 -2
- package/dist/docs/changelog.md +25 -0
- package/dist/docs/guides/guide.md +35 -4
- package/dist/docs/guides/production-constraints.md +1 -1
- package/dist/docs/guides/session.md +3 -1
- package/dist/docs/guides/theming-and-branding.md +18 -4
- package/dist/docs/guides/upgrading.md +8 -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.js +131 -0
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +1 -1
- 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-BNLEVOQA.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
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) | 48 functions, 3 classes, 38 constants, 25 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 |
|
|
@@ -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;
|
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.
|
|
@@ -619,7 +627,7 @@ const SettingsEditorThemePreferenceContext: import('react').Context<ThemePrefere
|
|
|
619
627
|
|
|
620
628
|
### SurfaceThemeContext
|
|
621
629
|
|
|
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 `
|
|
630
|
+
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
631
|
|
|
624
632
|
```ts
|
|
625
633
|
const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
|
|
@@ -791,7 +799,10 @@ interface Brand {
|
|
|
791
799
|
onLight?: string;
|
|
792
800
|
onDark?: string;
|
|
793
801
|
};
|
|
794
|
-
icon?:
|
|
802
|
+
icon?: {
|
|
803
|
+
onLight?: string;
|
|
804
|
+
onDark?: string;
|
|
805
|
+
};
|
|
795
806
|
fonts?: {
|
|
796
807
|
heading?: BrandFont;
|
|
797
808
|
body?: BrandFont;
|
|
@@ -1097,6 +1108,14 @@ How `useAsset` reads the response body.
|
|
|
1097
1108
|
type AssetFormat = 'json' | 'text' | 'blob';
|
|
1098
1109
|
```
|
|
1099
1110
|
|
|
1111
|
+
### BrandIcon
|
|
1112
|
+
|
|
1113
|
+
The icon `useBrandIcon` picked, and the background it was drawn for.
|
|
1114
|
+
|
|
1115
|
+
```ts
|
|
1116
|
+
type BrandIcon = BrandLogo;
|
|
1117
|
+
```
|
|
1118
|
+
|
|
1100
1119
|
### ContextDeletePath
|
|
1101
1120
|
|
|
1102
1121
|
Where to remove a key, as a path from the root of the context.
|
package/dist/docs/changelog.md
CHANGED
|
@@ -31,6 +31,31 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
31
31
|
|
|
32
32
|
## [Unreleased]
|
|
33
33
|
|
|
34
|
+
## [1.2.0] — 2026-10-25
|
|
35
|
+
|
|
36
|
+
### Breaking Changes
|
|
37
|
+
|
|
38
|
+
- **`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
|
|
39
|
+
|
|
40
|
+
### Added
|
|
41
|
+
|
|
42
|
+
- **`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
|
|
43
|
+
- **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
|
|
44
|
+
- **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
|
|
45
|
+
- **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)
|
|
46
|
+
- **`@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
|
|
47
|
+
- **The `workflow-create-guide.md` rule describes `file` videos.** Merge it into your game's `.claude/rules/`
|
|
48
|
+
- **`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`
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
|
|
52
|
+
- **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()`
|
|
53
|
+
|
|
54
|
+
### Fixed
|
|
55
|
+
|
|
56
|
+
- **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
|
|
57
|
+
- **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` … `::::`
|
|
58
|
+
|
|
34
59
|
## [1.1.0] — 2026-10-24
|
|
35
60
|
|
|
36
61
|
### 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
|
|
|
@@ -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
|
|
@@ -466,6 +466,8 @@ The second argument narrows the overlay:
|
|
|
466
466
|
|
|
467
467
|
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
468
|
|
|
469
|
+
**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
|
+
|
|
469
471
|
### Undoing and resetting
|
|
470
472
|
|
|
471
473
|
Facilitators can revert the last tick or reset games, targeted at a specific team or all teams:
|
|
@@ -815,7 +817,7 @@ const { sessionId, name, readOnly, waitingRoomOpen, joinPin } = useSessionUserIn
|
|
|
815
817
|
|
|
816
818
|
### useSessionUserInterfaceTeamLinks
|
|
817
819
|
|
|
818
|
-
Get each team's facilitator-only URLs, so a game draws its own QR codes and join sheets:
|
|
820
|
+
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
821
|
|
|
820
822
|
```typescript
|
|
821
823
|
import { useSessionUserInterfaceTeamLinks } from '@seriousgaming/sdk/ui';
|
|
@@ -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 {
|
|
@@ -663,6 +663,14 @@ 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
|
+
|
|
666
674
|
## Before you publish
|
|
667
675
|
|
|
668
676
|
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.
|
|
@@ -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.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.2";
|
|
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.2";
|
|
306
306
|
function isLaterSpecRevision(revision, than) {
|
|
307
307
|
const [major, minor] = revision.split(".").map(Number);
|
|
308
308
|
const [thanMajor, thanMinor] = than.split(".").map(Number);
|
|
@@ -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
|