@seriousgaming/sdk-tools 1.0.0-alpha.4 → 1.1.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 (165) 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 +20003 -5523
  17. package/dist/client.js +15534 -1134
  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 +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -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 +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +64 -6
  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 +64 -3
  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 +2 -9
  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 +29 -35
  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 +194 -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 +28 -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 +2 -2
  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 +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -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,67 @@
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
+ export {};
@@ -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,10 @@
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, and how settings in its markdown evaluate, so a
16
+ * platform shows exactly the guide the dev server shows.
13
17
  */
14
18
  export { HostChannel } from './host-channel.js';
15
19
  export type { FrameLike, GuestMessage, HostChannelOptions, HostMessage, TeardownReason, WindowLike, } from './host-channel.js';
@@ -17,4 +21,6 @@ export type { HostAdapter, RequestOrigin } from './adapter.js';
17
21
  export { isPlayerSurface, requiredMessagesFor, SURFACES, type SurfaceDescriptor, type SurfaceKind, } from './surfaces.js';
18
22
  export { UI_PROTOCOL_VERSION } from './protocol.js';
19
23
  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';
24
+ export { contrastTextFor, neutralsFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
25
+ export { chapterSources, referenceLocale, type ChapterSource } from '../guide/locale.js';
26
+ export { evaluateChapter, evaluateWhen, formatSettingValue, isChapterEmpty, lookupSetting, remarkGuideSettings, type GuideSettings, } from '../guide/settings.js';
@@ -56,6 +56,13 @@ export declare const UI_PROTOCOL_VERSION = 4;
56
56
  export type IFrameMessage = {
57
57
  type: 'ready';
58
58
  protocolVersion: number;
59
+ /**
60
+ * The surface will send `rendered` once its first paint is on screen, so a
61
+ * host may keep its own loading screen over the frame until then (§12.5).
62
+ * Absent from a surface built before the signal existed, which a host shows
63
+ * as soon as it connects, as it always did.
64
+ */
65
+ signalsRendered?: true;
59
66
  };
60
67
  /**
61
68
  * Window-level message: host → iframe. Carries port2 as a transfer.
@@ -133,6 +140,19 @@ export type HostPortMessage = {
133
140
  | {
134
141
  type: 'setRunKind';
135
142
  runKind: RunKind;
143
+ }
144
+ /**
145
+ * The active scenario's name in the session locale, or `null` when the
146
+ * session runs on the game's own settings. For display only (§6.15.1).
147
+ * Sent in the initial batch and again whenever it changes, with a locale
148
+ * change or a scenario switch.
149
+ *
150
+ * The wrapper's `null` default is a fallback for a host predating this
151
+ * message, which a surface already has to render (§12.3).
152
+ */
153
+ | {
154
+ type: 'setScenarioName';
155
+ scenarioName: string | null;
136
156
  } | {
137
157
  type: 'setTimer';
138
158
  payload: TimerState;
@@ -253,6 +273,10 @@ export type HostPortMessage = {
253
273
  /** Port messages sent from game UI iframe to host */
254
274
  export type IFramePortMessage = {
255
275
  type: 'pong';
276
+ }
277
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
278
+ | {
279
+ type: 'rendered';
256
280
  } | {
257
281
  type: 'updateData';
258
282
  requestId?: string;
@@ -383,6 +407,14 @@ export type HostSessionPortMessage = {
383
407
  type: 'setRunKind';
384
408
  runKind: RunKind;
385
409
  }
410
+ /**
411
+ * The active scenario's name in the session locale, or `null`. For
412
+ * display only (§6.15.1); sent as a game UI's is.
413
+ */
414
+ | {
415
+ type: 'setScenarioName';
416
+ scenarioName: string | null;
417
+ }
386
418
  /**
387
419
  * Where to open the walkthrough run (§5.7). Every host offers one, so this
388
420
  * always carries a link. Facilitator-only, and naming no team: a
@@ -473,6 +505,10 @@ export type HostSessionPortMessage = {
473
505
  /** Port messages sent from session UI iframe to host */
474
506
  export type IFrameSessionPortMessage = {
475
507
  type: 'pong';
508
+ }
509
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
510
+ | {
511
+ type: 'rendered';
476
512
  } | {
477
513
  type: 'updateSessionData';
478
514
  requestId?: string;
@@ -579,11 +615,11 @@ export type IFrameSessionPortMessage = {
579
615
  }
580
616
  /**
581
617
  * Ask the host to open one of its own overlays (§6.4). The host renders it;
582
- * this delegates the trigger alone. `target` is the overlay's argument — a
583
- * guide identifier for `facilitator-guide`, a team id for `print-sheets` —
584
- * and omitting it means the whole thing (the first declared guide, every
585
- * team). An overlay the host does not offer, or a `target` the active game
586
- * does not declare, settles as denied.
618
+ * this delegates the trigger alone. `target` is a team id for
619
+ * `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
621
+ * the host does not offer, or a team id not in the session, settles as
622
+ * denied.
587
623
  */
588
624
  | {
589
625
  type: 'openHostOverlay';
@@ -686,6 +722,10 @@ export type HostSettingsEditorPortMessage = {
686
722
  */
687
723
  export type IFrameSettingsEditorPortMessage = {
688
724
  type: 'pong';
725
+ }
726
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
727
+ | {
728
+ type: 'rendered';
689
729
  } | {
690
730
  type: 'updateSettings';
691
731
  requestId?: string;
@@ -767,6 +807,10 @@ export type HostPresentationPortMessage = {
767
807
  /** Port messages sent from presentation iframe to host. Reads only. */
768
808
  export type IFramePresentationPortMessage = {
769
809
  type: 'pong';
810
+ }
811
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
812
+ | {
813
+ type: 'rendered';
770
814
  } | {
771
815
  type: 'refreshAssetAuth:response';
772
816
  requestId: string;
@@ -10,7 +10,7 @@
10
10
  * Platform-facing: exported from
11
11
  * `@seriousgaming/sdk-tools/host`.
12
12
  */
13
- import type { ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
13
+ import type { Brand, ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
14
14
  /** The roles a theme sends, in the order §12.3 lists them. */
15
15
  export declare const THEME_COLOR_ROLES: readonly ThemeColorRole[];
16
16
  /** The WCAG AA minimum for normal text. */
@@ -40,16 +40,42 @@ export declare function contrastTextFor(colour: string, preferred?: string): str
40
40
  /** One mode's colours before a host has given them their text colours. */
41
41
  export type ModeColoursInput = Record<ThemeColorRole, string> & {
42
42
  contrastText?: Partial<ThemeContrastText>;
43
+ /**
44
+ * The page colour, raised surfaces, and the author's text for both
45
+ * (§12.3). Optional here, because a host can always send a plain page's:
46
+ * the payload carries all three either way.
47
+ */
48
+ background?: string;
49
+ surface?: string;
50
+ text?: string;
43
51
  };
44
52
  /** A theme before a host has given its colours their text colours. */
45
53
  export interface ThemeInput {
46
54
  mode: 'light' | 'dark';
47
55
  light: ModeColoursInput;
48
56
  dark: ModeColoursInput;
57
+ /** The host's brand, sent as it is (§12.3). */
58
+ brand: Brand;
49
59
  }
60
+ type Neutrals = {
61
+ background: string;
62
+ surface: string;
63
+ text: string;
64
+ };
65
+ /**
66
+ * The author's page, surface and text colours, made fit to send, or undefined
67
+ * when they cannot be (§12.3).
68
+ *
69
+ * `text` is held to 4.5:1 or better against both of the others: the author's
70
+ * own where it meets that, otherwise black or white, whichever does better
71
+ * against the weaker of the two. Where neither can, the pair cannot carry text,
72
+ * and the caller sends a plain page instead.
73
+ */
74
+ export declare function neutralsFor(colours: Partial<Neutrals>): Neutrals | undefined;
50
75
  /**
51
76
  * The `setTheme` payload for a theme: every colour of both modes given its
52
- * `contrastText`, keeping any the author supplied that meet AA.
77
+ * `contrastText`, keeping any the author supplied that meet AA, page colours
78
+ * that carry text (the author's, or a plain page's), and the brand as it is.
53
79
  */
54
80
  export declare function withContrastText(theme: ThemeInput): UserInterfaceTheme;
55
81
  export {};