@seriousgaming/sdk-tools 1.0.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.
Files changed (167) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20161 -5495
  17. package/dist/client.js +15737 -1151
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +230 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
  27. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +185 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +85 -4
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +98 -6
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +3 -10
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +32 -36
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +208 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +13 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +4 -4
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +74 -0
  124. package/dist/guide/video-registry.d.ts +33 -1
  125. package/dist/host/host-channel.d.ts +11 -2
  126. package/dist/host/index.d.ts +9 -1
  127. package/dist/host/protocol.d.ts +49 -5
  128. package/dist/host/theme.d.ts +28 -2
  129. package/dist/host.js +11621 -15
  130. package/dist/runtime/index.d.ts +1 -1
  131. package/dist/runtime/manifest-version.d.ts +17 -0
  132. package/dist/runtime.js +12 -1
  133. package/dist/schema.json +32 -4
  134. package/dist/storage/blob-store.d.ts +3 -2
  135. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  136. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  137. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  138. package/dist/templates/package/CLAUDE.md.template +5 -2
  139. package/dist/templates/package/README.md.liquid +2 -0
  140. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  141. package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
  142. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  143. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  144. package/dist/templates/session/src/theme.ts.liquid +26 -33
  145. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  146. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  147. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  148. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  149. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  151. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  152. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  153. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  154. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  155. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  156. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  157. package/dist/templates/validator/logic.ts.liquid +4 -0
  158. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  159. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  160. package/dist/utils/error-codes.d.ts +15 -3
  161. package/dist/validation/ajv.d.ts +9 -5
  162. package/dist/validation/facilitator-guide-validator.d.ts +11 -1
  163. package/dist/validation/file-settings.d.ts +49 -0
  164. package/dist/validation/guide-settings-validator.d.ts +26 -0
  165. package/dist/validation/schema-validation.d.ts +12 -4
  166. package/package.json +6 -5
  167. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -2,7 +2,7 @@
2
2
 
3
3
  Write and run component tests for a user interface with Vitest, React Testing Library, and the SDK's render helpers.
4
4
 
5
- **Keywords:** test UI, unit test, React testing, App.test.tsx, vitest, testing library, mock context, setData, controlled input, renderUserInterface, renderSessionUserInterface, renderSettingsEditor, mock participant, participant roster, sessionKey
5
+ **Keywords:** test UI, unit test, React testing, App.test.tsx, vitest, testing library, mock context, setData, controlled input, renderUserInterface, renderSessionUserInterface, renderSettingsEditor, mock participant, participant roster, mock team, sessionKey
6
6
 
7
7
  ## Prerequisites
8
8
 
@@ -10,7 +10,7 @@ Write and run component tests for a user interface with Vitest, React Testing Li
10
10
 
11
11
  ## Steps
12
12
 
13
- 1. Open the test beside the component: `ui/src/App.test.tsx` for the game UI (`session/src/`, `waiting_room/src/`, `setup/src/` and the others for theirs).
13
+ 1. Open the test beside the component: `ui/src/App.test.tsx` for the game UI (`session/src/`, `waiting_room/src/`, `setup/src/` and the others for theirs)
14
14
 
15
15
  2. Render through the helper for the surface, giving it only what the test cares about. Every other context value has a complete default, so never build the providers by hand:
16
16
 
@@ -68,6 +68,17 @@ Write and run component tests for a user interface with Vitest, React Testing Li
68
68
  renderUserInterface(<App />, { data: defaultContext, participants: createMockParticipants(3) });
69
69
  ```
70
70
 
71
+ The participant's team (`ownTeam`) is found in `teams` by its `teamId`. Build either with `createMockTeam` and `createMockTeams` rather than by hand, so a field later added to a team reaches the test with a value:
72
+
73
+ ```tsx
74
+ import { createMockTeam } from '@seriousgaming/sdk/ui/testing';
75
+
76
+ renderUserInterface(<App />, {
77
+ data: defaultContext,
78
+ ownTeam: createMockTeam({ name: 'North' }),
79
+ });
80
+ ```
81
+
71
82
  6. Run the tests:
72
83
 
73
84
  ```bash
@@ -0,0 +1,91 @@
1
+ # Validate a game's scenarios
2
+
3
+ Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
4
+
5
+ **Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, custom scenario check
6
+
7
+ ## Prerequisites
8
+
9
+ - A settings resource holding the values the rule is about (here `ui`, with `MinPrice` and `MaxPrice`); see [Create a settings resource](create-settings.md)
10
+ - `seriousgaming.sdk.json` in your working directory
11
+
12
+ ## Steps
13
+
14
+ 1. Put the rules in a file both the gate and your scenario editor can import, `shared/scenario-rules.ts`, as plain functions with no browser or Node APIs:
15
+
16
+ ```typescript
17
+ export interface ScenarioRuleProblem {
18
+ path: string;
19
+ message: string;
20
+ }
21
+
22
+ export function scenarioProblems(ui: {
23
+ MinPrice: number;
24
+ MaxPrice: number;
25
+ }): ScenarioRuleProblem[] {
26
+ const problems: ScenarioRuleProblem[] = [];
27
+ if (ui.MinPrice > ui.MaxPrice) {
28
+ problems.push({
29
+ path: 'ui.MinPrice',
30
+ message: `The lowest price (£${ui.MinPrice}) must be at or below the highest price (£${ui.MaxPrice})`,
31
+ });
32
+ }
33
+ return problems;
34
+ }
35
+ ```
36
+
37
+ Name the setting in `path` and say what is allowed in `message`: an agent editing a scenario has nothing else to go on. For a value every scenario must supply, default it to an empty one and refuse that here, as in `if (edition.ClientName === '')`.
38
+
39
+ 2. Create a validator that reads the settings and no capabilities:
40
+
41
+ ```bash
42
+ pnpm run sdk new validator '{
43
+ "definition": {
44
+ "identifier": "scenariocheck",
45
+ "settings": ["ui"]
46
+ },
47
+ "logic": { "directory": "logic", "entrypoint": "logic.ts" },
48
+ "rootDirectory": "."
49
+ }'
50
+ ```
51
+
52
+ 3. Replace the scaffolded `UpdateData` in `validators/scenariocheck/logic/logic.ts` with a `Scenario` gate:
53
+
54
+ ```typescript
55
+ import { scenarioProblems } from '../../../shared/scenario-rules';
56
+ import type { ScenarioFunction } from '../types';
57
+
58
+ export const Scenario: ScenarioFunction = async ({ settings }) => scenarioProblems(settings.ui);
59
+ ```
60
+
61
+ Update the scaffolded `logic.test.ts` to call `Scenario({ settings, locale: 'en' })` and check the problems it returns.
62
+
63
+ 4. List the feature in `seriousgaming.sdk.json`:
64
+
65
+ ```json
66
+ {
67
+ "requires": ["scenario-validation"]
68
+ }
69
+ ```
70
+
71
+ 5. If facilitators have already saved scenarios for a released version, bump `scenarioFormat` in the same file, so the runtime stops using scenarios saved before the rule
72
+
73
+ 6. Optionally, show the same problems in your scenario editor by calling `scenarioProblems(settings.ui)` and marking each field whose setting a problem names
74
+
75
+ ## Verify
76
+
77
+ - `pnpm run sdk build --validate-only` passes
78
+ - Set `"MinPrice": 600, "MaxPrice": 400` under `settings.ui` in one of your scenarios and run it again: it fails with `SCENARIO_REFUSED`, pointing at `MinPrice` in that scenario's file
79
+
80
+ ## Troubleshooting
81
+
82
+ - _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`
83
+ - _`SCENARIO_REFUSED` for 'The defaults'_: no scenario is the default, so a session can run on the defaults alone, and they break a rule. Mark a scenario `"default": true`, or change the defaults
84
+ - _A placeholder that is also a real choice_: the gate sees values, not where they came from, so it cannot tell a scenario that chose `0` from one that forgot. Use an obviously empty default (`""`, `[]` or `{}`)
85
+ - _'Validator scenariocheck threw'_: the gate threw, which counts as a problem so that a broken rule never lets a scenario through. Check the settings it reads are listed in `settings`
86
+
87
+ ## Related
88
+
89
+ - [Validators guide: gating scenarios](../guides/validators.md#gating-scenarios)
90
+ - [Create a validator](create-validator.md)
91
+ - [Building a scenario editor](../guides/scenario-editor.md)
@@ -2,6 +2,7 @@
2
2
 
3
3
  Find the symptom you are seeing, then read its cause and fix. Entries are grouped by where the problem shows up.
4
4
 
5
+ - [Scaffolding and install](#scaffolding-and-install)
5
6
  - [Dev server and sessions](#dev-server-and-sessions)
6
7
  - [Engine logic and endpoints](#engine-logic-and-endpoints)
7
8
  - [Build and validation](#build-and-validation)
@@ -9,6 +10,39 @@ Find the symptom you are seeing, then read its cause and fix. Entries are groupe
9
10
  - [Tests](#tests)
10
11
  - [Other error messages](#other-error-messages)
11
12
 
13
+ ## Scaffolding and install
14
+
15
+ ### `pnpm dlx @seriousgaming/sdk-tools new package` fails before it asks anything
16
+
17
+ **Symptom:** the command exits at once, or says `pnpm: command not found`.
18
+
19
+ **Cause:** usually an older Node.js or pnpm. The SDK needs Node.js 24 or later and pnpm 12.
20
+
21
+ **Fix:** check both, then run the command again:
22
+
23
+ ```bash
24
+ node --version
25
+ pnpm --version
26
+ ```
27
+
28
+ If pnpm is missing or older, run `corepack enable`, which ships with Node.js, or see [installing pnpm](https://pnpm.io/installation).
29
+
30
+ ### `new package` stops with `INSTALL_FAILED`
31
+
32
+ **Symptom:** the package is written, but the command exits with code 5 and `INSTALL_FAILED`.
33
+
34
+ **Cause:** `pnpm install` failed inside the new package, usually on the network or the pnpm version.
35
+
36
+ **Fix:** the files are all there. Fix the cause the install printed, then run `pnpm install` in the package yourself.
37
+
38
+ ### A command fails with `PROMPT_REQUIRED`
39
+
40
+ **Symptom:** in a script, a CI job, or an AI agent's terminal, a command exits with code 2 and `PROMPT_REQUIRED`.
41
+
42
+ **Cause:** the command would have asked a question, and there is no terminal to ask in.
43
+
44
+ **Fix:** pass the answer instead: a definition as an argument, with `--file`, or on stdin, and `--yes` to `delete`. [For AI agents](./ai-agents.md) shows each form.
45
+
12
46
  ## Dev server and sessions
13
47
 
14
48
  ### The dev server does not start
@@ -514,9 +548,9 @@ Exporting only one of the pair fails the same way, naming the other: _'does not
514
548
 
515
549
  ### The build rejects a teamless surface calling a team-scoped endpoint
516
550
 
517
- **Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI, setup screen, or scenario editor.
551
+ **Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI or setup screen.
518
552
 
519
- **Cause:** an endpoint declares whether it acts on one team or on the session, and `scope` is `'team'` when absent. A session UI, a setup screen, and a scenario editor have no team of their own, so there is nothing for a team-scoped call to act against.
553
+ **Cause:** an endpoint declares whether it acts on one team or on the session, and `scope` is `'team'` when absent. A session UI and a setup screen have no team of their own, so there is nothing for a team-scoped call to act against.
520
554
 
521
555
  **Fix:**
522
556
 
@@ -533,6 +567,14 @@ Exporting only one of the pair fails the same way, naming the other: _'does not
533
567
  pnpm run sdk endpoint list
534
568
  ```
535
569
 
570
+ ### The build rejects an endpoint on the scenario editor
571
+
572
+ **Symptom:** `pnpm run sdk build` fails with `EDITOR_ENDPOINT_NOT_SCENARIO`: _'Scenario Editor "scenario_editor" calls endpoint X, which is session-scoped'_. An editor that built under 1.0 now fails.
573
+
574
+ **Cause:** the scenario editor writes a scenario with no session, so it calls only scenario-scoped endpoints, which are handed the draft's settings and nothing of game state. A session-scoped endpoint there used to be answered with an empty, made-up session.
575
+
576
+ **Fix:** declare the endpoint `"scope": "scenario"`, regenerate its types with `pnpm run sdk generate`, and drop any use of `context`, `participants` or `session` from its handler, which the generated `Handler` type no longer offers. If it declares `reads`, `writes`, `actions` or `roster`, remove them too (`SCENARIO_ENDPOINT_STATEFUL`). See [Scenario-scoped endpoints](./guides/endpoints.md#scenario-scoped-endpoints).
577
+
536
578
  ### The build is slow
537
579
 
538
580
  **Symptom:** `pnpm run build` takes a long time.
@@ -18,6 +18,7 @@
18
18
  * translate the keyword rather than invent a second model.
19
19
  */
20
20
  import type { JSONSchema7 } from 'json-schema';
21
+ import type { BlobRetention } from '../storage/blob-store';
21
22
  export interface BlobFieldSpec {
22
23
  /** Media types, `type/*` wildcards allowed. Absent means any. */
23
24
  accept?: string[];
@@ -25,10 +26,11 @@ export interface BlobFieldSpec {
25
26
  }
26
27
  /** What the resolver needs from a blob store. */
27
28
  export interface BlobInputStore {
28
- /** The stored blob's type and size, or undefined when there is none. */
29
+ /** The stored blob's type, size and retention, or undefined when there is none. */
29
30
  describe(id: string): Promise<{
30
31
  mimeType: string;
31
32
  size: number;
33
+ retention: BlobRetention;
32
34
  } | undefined>;
33
35
  store(data: Uint8Array, name: string, mimeType: string): Promise<string>;
34
36
  }
@@ -38,6 +40,7 @@ export interface BlobInputStore {
38
40
  * doing it: past this, a caller uploads first and sends the reference.
39
41
  */
40
42
  export declare const MAX_INLINE_BYTES: number;
43
+ export declare function accepts(spec: BlobFieldSpec, mimeType: string): boolean;
41
44
  /**
42
45
  * The type the bytes say they are, for the handful of formats a game commonly
43
46
  * takes, or undefined for anything else. A caller's claimed type is checked
@@ -54,4 +57,6 @@ export declare function sniffMimeType(data: Uint8Array): string | undefined;
54
57
  * by the schema or by the handler, leaves its upload behind. That is the same
55
58
  * as a surface that uploads and then never submits, and retention clears both.
56
59
  */
57
- export declare function resolveBlobInputs(identifier: string, schema: JSONSchema7 | undefined, request: unknown, store: BlobInputStore): Promise<unknown>;
60
+ export declare function resolveBlobInputs(identifier: string, schema: JSONSchema7 | undefined, request: unknown, store: BlobInputStore, options?: {
61
+ draft?: boolean;
62
+ }): Promise<unknown>;
@@ -11,6 +11,7 @@
11
11
  * injected accessors, so it always sees current state without owning it.
12
12
  */
13
13
  import type { ResolvedPackageManifest, SDKGame, SDKScenario } from '@seriousgaming/sdk';
14
+ import type { JSONSchema7 } from 'json-schema';
14
15
  import type { ResolvedSettings } from './configuration-builder';
15
16
  import type { SessionSettingsOverrides, ExecutorDependencies } from './types';
16
17
  /** The layered-config state the resolver needs from the executor. */
@@ -125,3 +126,12 @@ export declare class ConfigResolver {
125
126
  */
126
127
  saveGameConfiguration(): Promise<void>;
127
128
  }
129
+ /**
130
+ * Extract default values declared in a settings schema's properties.
131
+ */
132
+ /**
133
+ * Layer the settings defaults, a scenario's overrides and a top layer (§8.2),
134
+ * with no session and no executor. What the build judges a scenario against.
135
+ */
136
+ export declare function resolveSettingsLayers(config: Pick<ResolvedPackageManifest, 'settings'>, scenarioSettings: SessionSettingsOverrides | null, overrides: SessionSettingsOverrides | null): Record<string, Record<string, unknown>>;
137
+ export declare function applySchemaDefaults(configSchema: JSONSchema7 | undefined): Record<string, unknown>;
@@ -31,7 +31,8 @@ export interface EndpointCallArgs {
31
31
  }[];
32
32
  team?: TeamInfo;
33
33
  scopedTeamIndex?: number;
34
- session: EndpointSession;
34
+ /** Where the session stands. Absent on a scenario-scoped call, which has none. */
35
+ session?: EndpointSession;
35
36
  /**
36
37
  * When the call started (`meta.now`, §10.2). The host takes it once, so
37
38
  * `Plan` and `Respond` read the same instant. Read from the executor's
@@ -50,6 +51,12 @@ export interface EndpointCallArgs {
50
51
  * declared ones. The session's when absent.
51
52
  */
52
53
  settings?: Record<string, Record<string, unknown>>;
54
+ /**
55
+ * `meta.scenarioName`, where the call is answered as a scenario other than
56
+ * the session's: the scenario editor's, which is the one being edited
57
+ * (§6.12). The session's when absent.
58
+ */
59
+ scenarioName?: string | null;
53
60
  }
54
61
  /**
55
62
  * One endpoint call's outcome: the response its caller receives, and, for an
@@ -8,6 +8,7 @@
8
8
  */
9
9
  import type { PastStateEntry, SDKGame, SignatureCallbacks } from '@seriousgaming/sdk';
10
10
  import { TtsClient } from '../services/tts/client';
11
+ import { type BlobRetention } from '../storage/blob-store';
11
12
  import { DocumentParserClient } from '../utils/document-parser-client';
12
13
  import { LLMClient } from '../utils/llm-client';
13
14
  export interface ExecutorCallbacksDeps {
@@ -48,6 +49,12 @@ export interface ExecutorCallbacksDeps {
48
49
  takePlatformFailure?: (() => {
49
50
  reason?: string;
50
51
  } | undefined) | null;
52
+ /**
53
+ * The retention every blob these callbacks store takes, whatever a
54
+ * `writeBlob` call asks for. Set on a scenario-scoped endpoint's calls,
55
+ * whose files belong to the draft rather than a session (§6.12, §16.2).
56
+ */
57
+ blobRetention?: BlobRetention;
51
58
  }
52
59
  /**
53
60
  * Build the raw callbacks object. Constructed fresh per resource invocation so
@@ -86,6 +86,17 @@ export declare class GameExecutor {
86
86
  */
87
87
  setRunKind(kind: RunKind): void;
88
88
  getRunKind(): RunKind;
89
+ /**
90
+ * The active scenario's name in the session locale, or null when the
91
+ * session runs on the game's own settings. Logic reads it as
92
+ * `meta.scenarioName`.
93
+ */
94
+ getScenarioName(): string | null;
95
+ /**
96
+ * A scenario's display name in the session locale, falling back through
97
+ * what it declares (§18.2), or null for none.
98
+ */
99
+ scenarioNameOf(scenario: SDKScenario | null | undefined): string | null;
89
100
  /**
90
101
  * Where the roster logic receives as `participants` comes from (§10.2).
91
102
  *
@@ -11,6 +11,7 @@
11
11
  * own copy and drifting.
12
12
  */
13
13
  import type { ApiUse, ResolvedPackageManifest, LogicMeta, Participant, RunKind, RunMeta, SignatureCallbacks } from '@seriousgaming/sdk';
14
+ import type { BlobRetention } from '../storage/blob-store';
14
15
  import { type ExecutorCallbacksDeps } from './executor-callbacks';
15
16
  import { type LogicOrigin, type SourceMapRegistry } from './logic-failure';
16
17
  import type { LogicKind, LogicResource } from './logic-loader';
@@ -54,6 +55,12 @@ export interface LogicCallsOptions {
54
55
  deps: Pick<ExecutorDependencies, 'logicExecutionBoundMs' | 'tickExecutionBoundMs'>;
55
56
  /** The loaded bundles' source maps, to read a thrown stack back to source. */
56
57
  sourceMaps: SourceMapRegistry;
58
+ /**
59
+ * The active scenario's name in the session locale, surfaced as
60
+ * `meta.scenarioName`. Read on every call rather than held, so it follows a
61
+ * locale change or a scenario switch without anybody remembering to set it.
62
+ */
63
+ scenarioName: () => string | null;
57
64
  /** What the raw callbacks are built from, less what this class supplies. */
58
65
  callbacks: Omit<ExecutorCallbacksDeps, 'readPastState' | 'getScopedTeamIndexes' | 'getAllTeamIndexes' | 'takePlatformFailure'>;
59
66
  }
@@ -153,7 +160,7 @@ export declare class LogicCalls {
153
160
  * fresh so they read the live game, with every one its `uses` does not
154
161
  * declare replaced by a throwing stub.
155
162
  */
156
- callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined): SignatureCallbacks;
163
+ callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined, blobRetention?: BlobRetention): SignatureCallbacks;
157
164
  /**
158
165
  * Bound one call into author logic that runs as part of a tick, or of the
159
166
  * initialisation a tick starts from (§11.10).
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The `Scenario` validator gate: every validator exporting it, put to one
3
+ * scenario, collecting every problem.
4
+ *
5
+ * Unlike the other two gates it needs no session. It judges settings, not a
6
+ * board, so the build can run it on a package's own scenarios and the dev
7
+ * server on a scenario about to be saved, with only the package and a loader.
8
+ */
9
+ import type { ResolvedPackageManifest, ScenarioProblem } from '@seriousgaming/sdk';
10
+ import { LogicLoader } from './logic-loader';
11
+ import type { SessionSettingsOverrides } from './types';
12
+ /** The `requires` feature name a package using the `Scenario` gate lists (§15.8). */
13
+ export declare const SCENARIO_VALIDATION = "scenario-validation";
14
+ /** A problem one validator found with a scenario. */
15
+ export interface ScenarioGateProblem extends ScenarioProblem {
16
+ validatorIdentifier: string;
17
+ }
18
+ /** Whether any validator in the package gates scenarios. */
19
+ export declare function hasScenarioGate(config: Pick<ResolvedPackageManifest, 'validators'>): boolean;
20
+ /**
21
+ * Put `scenarioSettings` (a scenario's own `settings`, or `null` for a session
22
+ * on no scenario) to every validator exporting `Scenario`, in manifest order.
23
+ * An empty array means the scenario passes.
24
+ */
25
+ export declare function runScenarioGates(options: {
26
+ packagePath: string;
27
+ config: ResolvedPackageManifest;
28
+ scenarioSettings: SessionSettingsOverrides | null;
29
+ locale?: string;
30
+ loader?: LogicLoader;
31
+ boundMs?: number;
32
+ }): Promise<ScenarioGateProblem[]>;
33
+ /** One line per problem, naming the validator and the setting. */
34
+ export declare function describeScenarioProblems(problems: ScenarioGateProblem[]): string[];
@@ -0,0 +1,20 @@
1
+ import type { SDKFacilitatorGuide } from '@seriousgaming/sdk';
2
+ import { type GuideSettings } from './settings.js';
3
+ /** The guide as one session reads it (§6.13.5). */
4
+ export interface EffectiveGuide {
5
+ identifier: string;
6
+ locales: Record<string, {
7
+ name?: string;
8
+ }>;
9
+ /** Each locale's chapter files, in filename order, without the chapters left empty. */
10
+ chapters: Record<string, string[]>;
11
+ /** The settings the guide declares, resolved for the session. */
12
+ settings: GuideSettings;
13
+ }
14
+ /**
15
+ * Read a guide from `root` as a session with `resolved` settings sees it, or
16
+ * null when no chapter is left to show. Whether a chapter is shown is decided
17
+ * on its reference-locale file, so a translation cannot show a chapter its
18
+ * original hides.
19
+ */
20
+ export declare function readEffectiveGuide(guide: SDKFacilitatorGuide, root: string, resolved: GuideSettings): EffectiveGuide | null;
@@ -10,3 +10,15 @@
10
10
  * locale).
11
11
  */
12
12
  export declare function referenceLocale(locales: Record<string, unknown>): string;
13
+ /** A chapter, and the locale its file is read from. */
14
+ export interface ChapterSource {
15
+ file: string;
16
+ locale: string;
17
+ }
18
+ /**
19
+ * The guide's chapters as a reader of `requested` sees them: the reference
20
+ * locale's chapter set, in its order, each read from the first locale in the
21
+ * §18.2 chain that has it (requested, then 'en', then the first declared).
22
+ * A chapter whose `locale` differs from `requested` is untranslated (§6.13.4).
23
+ */
24
+ export declare function chapterSources(locales: Record<string, unknown>, chapters: Record<string, string[]>, requested: string): ChapterSource[];
@@ -0,0 +1,74 @@
1
+ import type { Root } from 'mdast';
2
+ /**
3
+ * Settings in facilitator guide markdown (§6.13.5).
4
+ *
5
+ * A guide that declares `settings` may show a resolved value inline with
6
+ * `:setting[identifier.path]`, and show or hide a block with
7
+ * `:::when{setting="identifier.path" is="value" not}`. Both are evaluated on
8
+ * the parsed tree before anything renders, so a value can never introduce
9
+ * markup, and a chapter left with nothing to show is dropped from the guide.
10
+ *
11
+ * This module is browser-safe: the dev console renders with it, the build
12
+ * validates with it, and `@seriousgaming/sdk-tools/host` exports it so a
13
+ * platform evaluates exactly as the dev server does.
14
+ */
15
+ /** Resolved settings, keyed by settings identifier, as a resource receives them. */
16
+ export type GuideSettings = Record<string, Record<string, unknown>>;
17
+ /** The attributes `:::when` accepts. Anything else is refused by the build. */
18
+ export declare const WHEN_ATTRIBUTES: readonly ["setting", "is", "not"];
19
+ /** A setting a chapter names, where it names it, for the build to check. */
20
+ export interface SettingReference {
21
+ kind: 'value' | 'when';
22
+ /** `identifier.path`, as written. */
23
+ path: string;
24
+ line: number;
25
+ /** `when` only: the literal `is` compares against, if any. */
26
+ is?: string;
27
+ /** Attributes the grammar does not define, as written. */
28
+ unknownAttributes: string[];
29
+ /** `when` only: true when it sits inside another `when`. */
30
+ nested: boolean;
31
+ }
32
+ type Lookup = {
33
+ found: true;
34
+ value: unknown;
35
+ } | {
36
+ found: false;
37
+ };
38
+ /** The value at `identifier.key.key…` in resolved settings. */
39
+ export declare function lookupSetting(settings: GuideSettings, path: string): Lookup;
40
+ /** How a value reads in the guide, or null when it is not a renderable kind. */
41
+ export declare function formatSettingValue(value: unknown, locale: string): string | null;
42
+ /** Whether a `:::when` shows its content, or an error when it cannot be decided. */
43
+ export declare function evaluateWhen(settings: GuideSettings, attributes: Record<string, string | null | undefined>): {
44
+ show: boolean;
45
+ } | {
46
+ error: string;
47
+ };
48
+ /**
49
+ * Remark plugin evaluating `:setting` and `:::when` against resolved settings.
50
+ * Runs after `remark-directive` and before the guide's own directive handling,
51
+ * which would otherwise render `when` as an unknown admonition and restore
52
+ * `:setting` to its literal text.
53
+ */
54
+ export declare function remarkGuideSettings(options: {
55
+ settings: GuideSettings;
56
+ locale: string;
57
+ }): (tree: Root) => void;
58
+ /** A chapter's tree with its settings evaluated. */
59
+ export declare function evaluateChapter(markdown: string, settings: GuideSettings, locale: string): Root;
60
+ /**
61
+ * Whether a chapter has nothing to show once its settings are evaluated. Such
62
+ * a chapter is left out of the guide, table of contents included (§6.13.5).
63
+ */
64
+ export declare function isChapterEmpty(markdown: string, settings: GuideSettings): boolean;
65
+ /** Every setting a chapter names, for the build to check against the declared schemas. */
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[];
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
@@ -101,8 +101,17 @@ export interface HostChannelOptions {
101
101
  handshakeTimeoutMs?: number;
102
102
  /** Guest messages the channel does not answer itself. */
103
103
  onMessage?(message: GuestMessage): void;
104
- /** Called each time the handshake completes, reconnections included. */
105
- onConnect?(): void;
104
+ /**
105
+ * Called each time the handshake completes, reconnections included.
106
+ * `signalsRendered` says the guest announced it will send `rendered`
107
+ * (§12.5), so a host may keep its own loading screen up until
108
+ * {@link onRendered}; a guest that did not announce it is ready to show now.
109
+ */
110
+ onConnect?(handshake: {
111
+ signalsRendered: boolean;
112
+ }): void;
113
+ /** Called each time the guest reports its first paint on screen (§12.5). */
114
+ onRendered?(): void;
106
115
  /** Called when the channel gives up on the frame. */
107
116
  onTeardown?(reason: TeardownReason): void;
108
117
  /** Where diagnostics go. Defaults to `console`. */
@@ -10,6 +10,11 @@
10
10
  * supplies, and the host's definition of the wire messages. The guest half is
11
11
  * the UI wrappers in `@seriousgaming/sdk/ui`. The shapes
12
12
  * may change in a minor release.
13
+ *
14
+ * It also carries how the host reads a facilitator guide (§6.13): which locale
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.
13
18
  */
14
19
  export { HostChannel } from './host-channel.js';
15
20
  export type { FrameLike, GuestMessage, HostChannelOptions, HostMessage, TeardownReason, WindowLike, } from './host-channel.js';
@@ -17,4 +22,7 @@ export type { HostAdapter, RequestOrigin } from './adapter.js';
17
22
  export { isPlayerSurface, requiredMessagesFor, SURFACES, type SurfaceDescriptor, type SurfaceKind, } from './surfaces.js';
18
23
  export { UI_PROTOCOL_VERSION } from './protocol.js';
19
24
  export type { AssetUrls, HostSettingsEditorPortMessage, HostPortMessage, HostPresentationPortMessage, HostSessionPortMessage, HostWindowMessage, IFrameSettingsEditorPortMessage, IFrameMessage, IFramePortMessage, IFramePresentationPortMessage, IFrameSessionPortMessage, } from './protocol.js';
20
- export { contrastTextFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
25
+ export { contrastTextFor, neutralsFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
26
+ export { chapterSources, referenceLocale, type ChapterSource } from '../guide/locale.js';
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';