@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.
@@ -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-qxHcu9fJ.js"></script>
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>
@@ -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) | 47 functions, 3 classes, 38 constants, 25 interfaces, 36 types |
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 `useBrandLogo()` has something to render. It names no fonts, so nothing waits on a load.
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;
@@ -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 `useBrandLogo`.
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?: string;
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.
@@ -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 (YouTube only in v1):
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. Unknown providers or malformed blocks render as an inert error block, never a passthrough. The dev server renders the embed from `youtube-nocookie.com` in a sandboxed iframe.
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`. 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.
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`), a square `icon`, and the `fonts` its headings and body text are set in
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
- Both 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.
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` and the id an 11-character YouTube id |
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
- | Text after an admonition escapes the block | The outer block closed early. 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 |
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
 
@@ -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. Unknown providers or malformed blocks must
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
@@ -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, and how settings in its markdown evaluate, so a
16
- * platform shows exactly the guide the dev server shows.
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.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.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