@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.
Files changed (40) hide show
  1. package/dist/cli.js +565 -309
  2. package/dist/client.js +608 -352
  3. package/dist/core/participant-registry.d.ts +6 -0
  4. package/dist/core/session-roster.d.ts +4 -1
  5. package/dist/dev/brands.d.ts +20 -3
  6. package/dist/dev/console/assets/{index-qxHcu9fJ.js → index-DEV8N0na.js} +47 -47
  7. package/dist/dev/console/index.html +1 -1
  8. package/dist/dev/view/batch.d.ts +17 -9
  9. package/dist/dev/view/view.d.ts +2 -1
  10. package/dist/docs/api/index.md +1 -1
  11. package/dist/docs/api/sdk-commands.md +4 -0
  12. package/dist/docs/api/sdk-e2e.md +4 -0
  13. package/dist/docs/api/sdk-tools-client.md +4 -0
  14. package/dist/docs/api/sdk-ui-testing.md +2 -1
  15. package/dist/docs/api/sdk-ui.md +54 -3
  16. package/dist/docs/api/sdk.md +3 -1
  17. package/dist/docs/changelog.md +41 -0
  18. package/dist/docs/guides/guide.md +35 -4
  19. package/dist/docs/guides/presentation.md +23 -9
  20. package/dist/docs/guides/production-constraints.md +1 -1
  21. package/dist/docs/guides/session.md +50 -9
  22. package/dist/docs/guides/testing.md +9 -0
  23. package/dist/docs/guides/theming-and-branding.md +18 -4
  24. package/dist/docs/guides/ui.md +33 -0
  25. package/dist/docs/guides/upgrading.md +19 -0
  26. package/dist/docs/guides/waiting-room.md +2 -0
  27. package/dist/docs/recipes/create-guide.md +2 -2
  28. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +9 -9
  29. package/dist/guide/settings.d.ts +7 -0
  30. package/dist/guide/video-registry.d.ts +33 -1
  31. package/dist/host/index.d.ts +4 -2
  32. package/dist/host/protocol.d.ts +27 -2
  33. package/dist/host.js +131 -0
  34. package/dist/runtime/manifest-version.d.ts +1 -1
  35. package/dist/runtime.js +4 -2
  36. package/dist/templates/package/CLAUDE.md.template +1 -1
  37. package/dist/templates/package/claude/rules/workflow-create-guide.md +8 -2
  38. package/dist/validation/facilitator-guide-validator.d.ts +5 -1
  39. package/dist/validation/schema-validation.d.ts +12 -4
  40. 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`), 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 {
@@ -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` 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';
@@ -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
- * takes none: a game holds one guide, and a `target` is ignored. An overlay
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.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.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 (YouTube only):
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. `additionalProperties` (false
112
- * by convention) still rejects undeclared keys, and type and value checks
113
- * still apply to the keys that are present.
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.1.0",
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.1.0",
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.1.0"
102
+ "@seriousgaming/sdk": "^1.3.0"
103
103
  },
104
104
  "engines": {
105
105
  "node": ">=24"