@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
@@ -23,5 +23,5 @@ export { assertJsonSerialisable } from '../execution/engine-state.js';
23
23
  export { readAggregateResult, readEngineResult, readTickControllerResult, } from '../execution/logic-result.js';
24
24
  export type { EngineResultRead } from '../execution/logic-result.js';
25
25
  export type { ValidateTickResultOptions } from './tick-validation.js';
26
- export { MANIFEST_VERSION, SUPPORTED_FEATURES, SUPPORTED_SERVICES, unsupportedFeatures, unsupportedServices, } from './manifest-version.js';
26
+ export { MANIFEST_VERSION, SPEC_REVISION, SUPPORTED_FEATURES, SUPPORTED_SERVICES, isLaterSpecRevision, unsupportedFeatures, unsupportedServices, } from './manifest-version.js';
27
27
  export type { ServiceDeclaration } from './manifest-version.js';
@@ -17,6 +17,23 @@ import type { ApiUse } from '@seriousgaming/sdk';
17
17
  * archived and must stay runnable.
18
18
  */
19
19
  export declare const MANIFEST_VERSION = 3;
20
+ /**
21
+ * The revision of the specification this SDK implements, as `major.minor`,
22
+ * which the build stamps into the manifest's `builtWith` (§2.2).
23
+ *
24
+ * While Appendix D has an `Unreleased` section, this is the revision those
25
+ * entries will ship as, since the SDK already implements them; once that
26
+ * section is stamped, it is the revision at the top of the appendix.
27
+ * `spec-revision.test.ts` holds the two together.
28
+ */
29
+ export declare const SPEC_REVISION = "1.2";
30
+ /**
31
+ * Whether specification revision `revision` is later than `than`, both as
32
+ * `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
33
+ * is later than the revision it implements, and MUST NOT refuse it (§2.6).
34
+ * Compared numerically, so `1.10` is later than `1.9`.
35
+ */
36
+ export declare function isLaterSpecRevision(revision: string, than: string): boolean;
20
37
  /**
21
38
  * The optional features this runtime supports, by the names a manifest's
22
39
  * `requires` lists them under.
package/dist/runtime.js CHANGED
@@ -302,7 +302,16 @@ function readTickControllerResult(label, result) {
302
302
 
303
303
  // cli/runtime/manifest-version.ts
304
304
  var MANIFEST_VERSION = 3;
305
- var SUPPORTED_FEATURES = [];
305
+ var SPEC_REVISION = "1.2";
306
+ function isLaterSpecRevision(revision, than) {
307
+ const [major, minor] = revision.split(".").map(Number);
308
+ const [thanMajor, thanMinor] = than.split(".").map(Number);
309
+ return major === thanMajor ? minor > thanMinor : major > thanMajor;
310
+ }
311
+ var SUPPORTED_FEATURES = [
312
+ // A validator's `Scenario` gate (§15.8).
313
+ "scenario-validation"
314
+ ];
306
315
  function unsupportedFeatures(manifest) {
307
316
  return (manifest.requires ?? []).filter((feature) => !SUPPORTED_FEATURES.includes(feature));
308
317
  }
@@ -328,6 +337,7 @@ function unsupportedServices(resources, supported = SUPPORTED_SERVICES) {
328
337
  }
329
338
  export {
330
339
  MANIFEST_VERSION,
340
+ SPEC_REVISION,
331
341
  SUPPORTED_FEATURES,
332
342
  SUPPORTED_SERVICES,
333
343
  applyContextUpdate,
@@ -335,6 +345,7 @@ export {
335
345
  createGuardedCallbacks,
336
346
  declaredCapabilityIds,
337
347
  deepMergeContext,
348
+ isLaterSpecRevision,
338
349
  projectContext,
339
350
  readAggregateResult,
340
351
  readEngineResult,
package/dist/schema.json CHANGED
@@ -50,6 +50,24 @@
50
50
  "default": 1,
51
51
  "description": "The format of the game's scenarios, which the author bumps whenever a custom scenario saved against an earlier value may no longer be correct: a setting removed, renamed or reshaped, a change in what a value means, or a change in how the game loads scenario assets. A purely additive change, such as a new setting with a default, needs no bump. A runtime stores it with each custom scenario it persists and refuses to apply a saved scenario whose format differs from the package's. Absent means 1."
52
52
  },
53
+ "BuiltWith": {
54
+ "type": "object",
55
+ "description": "What built the package, written by the build and never authored. Informational: a runtime MAY warn when specRevision is later than the revision it implements, naming both, and MUST NOT refuse a package for it. requires stays the one gate.",
56
+ "properties": {
57
+ "sdk": {
58
+ "type": "string",
59
+ "minLength": 1,
60
+ "description": "The version of the SDK tooling that ran the build"
61
+ },
62
+ "specRevision": {
63
+ "type": "string",
64
+ "pattern": "^[0-9]+\\.[0-9]+$",
65
+ "description": "The specification revision that SDK implements, as major.minor"
66
+ }
67
+ },
68
+ "required": ["sdk", "specRevision"],
69
+ "additionalProperties": false
70
+ },
53
71
  "ApiUse": {
54
72
  "type": "string",
55
73
  "description": "Runtime callback API (a service) a logic-bearing resource is permitted to invoke. A declared API is always present for that resource, and a runtime that cannot provide one a package declares refuses the package at load. Calling an undeclared API throws at runtime, in both dev and production. Resources that omit `uses` (or declare an empty array) cannot call any callbacks.",
@@ -529,6 +547,15 @@
529
547
  },
530
548
  "minProperties": 1,
531
549
  "additionalProperties": false
550
+ },
551
+ "settings": {
552
+ "type": "array",
553
+ "description": "Identifiers of the settings resources this guide reads. Its chapters may show their values with :setting[identifier.path] and show or hide content on them with :::when, resolved as for every other resource that reads settings",
554
+ "items": {
555
+ "type": "string",
556
+ "pattern": "^[a-z][a-z0-9_]*$"
557
+ },
558
+ "uniqueItems": true
532
559
  }
533
560
  },
534
561
  "required": ["identifier", "locales"],
@@ -941,8 +968,8 @@
941
968
  },
942
969
  "ValidatorGate": {
943
970
  "type": "string",
944
- "description": "A participant action a validator can gate, named after the surface message it gates: a context write, or a request for the next tick",
945
- "enum": ["updateData", "requestTick"]
971
+ "description": "What a validator can gate: a participant's context write, a participant's request for the next tick, or a scenario (a package scenario at build, a custom scenario when it is saved)",
972
+ "enum": ["updateData", "requestTick", "scenario"]
946
973
  },
947
974
  "ValidatorDefinition": {
948
975
  "type": "object",
@@ -1015,8 +1042,8 @@
1015
1042
  },
1016
1043
  "scope": {
1017
1044
  "type": "string",
1018
- "enum": ["session", "team"],
1019
- "description": "Whether this endpoint acts on one team or on the session as a whole. A team-scoped endpoint receives that team's context and a `team` naming it, whoever calls it; a session-scoped one has neither. Absent means `team`.",
1045
+ "enum": ["session", "team", "scenario"],
1046
+ "description": "What this endpoint acts on: one team, the session as a whole, or a scenario being written. A team-scoped endpoint receives that team's context and a `team` naming it, whoever calls it; a session-scoped one has neither. A scenario-scoped endpoint runs on a scenario draft with no session: it receives the draft's settings and nothing of game state, declares no `reads`, `writes` or `actions`, and only the scenario editor, or an authoring agent when it is `external`, may call it. Absent means `team`.",
1020
1047
  "default": "team"
1021
1048
  },
1022
1049
  "requestSchema": {
@@ -1114,6 +1141,7 @@
1114
1141
  },
1115
1142
  "requires": { "$ref": "#/$defs/RequiredFeatures" },
1116
1143
  "scenarioFormat": { "$ref": "#/$defs/ScenarioFormat" },
1144
+ "builtWith": { "$ref": "#/$defs/BuiltWith" },
1117
1145
  "package": { "$ref": "#/$defs/SDKPackage" },
1118
1146
  "game": { "$ref": "#/$defs/SDKGame" },
1119
1147
  "engine": { "$ref": "#/$defs/SDKEngine" },
@@ -7,9 +7,10 @@
7
7
  *
8
8
  * Retention (§16.2) is a deletion-lifecycle bucket, not an access dimension:
9
9
  * "settings" — survives a session reset; cleared on a re-initialise
10
- * "game" — cleared on a session reset or a re-initialise
10
+ * "game" — cleared on a session reset or a re-initialise
11
+ * "scenario" — a scenario draft's file; no session operation clears it
11
12
  */
12
- export type BlobRetention = 'settings' | 'game';
13
+ export type BlobRetention = 'settings' | 'game' | 'scenario';
13
14
  export interface BlobMeta {
14
15
  name: string;
15
16
  mimeType: string;
@@ -1,11 +1,22 @@
1
1
  import { logicArgs } from '@seriousgaming/sdk/testing';
2
2
  import { describe, it, expect } from 'vitest';
3
3
 
4
+ {% if scenario -%}
5
+ {% if hasSettings %}import { defaultSettings } from '../defaults';
6
+ {% endif -%}
7
+ {% else -%}
4
8
  import { defaultContext{% if hasSettings %}, defaultSettings{% endif %} } from '../defaults';
9
+ {% endif -%}
5
10
  import type { Request } from '../types';
6
11
  import { Handle } from './logic';
7
12
 
8
- {% if hasSettings -%}
13
+ {% if scenario -%}
14
+ // A scenario-scoped endpoint runs on a scenario draft: `logicArgs.scenarioEndpoint`
15
+ // fills what the runtime would supply (a fixed locale and clock, offline
16
+ // callback stubs, and an author calling from the scenario editor). Pass the
17
+ // draft's values as `settings`{% if hasSettings %}: spread the generated `defaultSettings` and
18
+ // name only what the case is about{% endif %}.
19
+ {%- elsif hasSettings -%}
9
20
  // `defaultContext` and `defaultSettings` are generated beside the types, from
10
21
  // the very schemas they satisfy: the values a session opens with. Spread them
11
22
  // and name only what the case is about.
@@ -15,12 +26,14 @@ import { Handle } from './logic';
15
26
  // case is about. Once the endpoint lists settings resources in `settings`,
16
27
  // `defaultSettings` is generated beside it: pass `settings: { ...defaultSettings }`.
17
28
  {% endif -%}
29
+ {% unless scenario -%}
18
30
  //
19
31
  // `logicArgs.endpoint` fills everything else the runtime would supply: `meta`
20
32
  // (a fixed locale, seed and clock), the roster, offline callback stubs, a
21
33
  // session summary, the caller (a participant on `team-1`, through `ui`) and,
22
34
  // on team scope, the team the call runs for. Name any of them to override it,
23
35
  // for example `caller: { role: 'facilitator' }`.
36
+ {%- endunless %}
24
37
 
25
38
  describe('{{ identifier }}', () => {
26
39
  describe('Handle', () => {
@@ -30,10 +43,15 @@ describe('{{ identifier }}', () => {
30
43
  const request = {} as Request;
31
44
 
32
45
  const result = await Handle(
46
+ {%- if scenario %}
47
+ logicArgs.scenarioEndpoint({
48
+ request,
49
+ {%- else %}
33
50
  logicArgs.endpoint({
34
51
  request,
35
52
  // TODO: override the capabilities this case is about
36
53
  context: { ...defaultContext },
54
+ {%- endif %}
37
55
  {%- if hasSettings %}
38
56
  // TODO: override the settings this case is about
39
57
  settings: { ...defaultSettings },
@@ -1,5 +1,22 @@
1
1
  import type { Handler } from '../types';
2
2
 
3
+ {% if scenario -%}
4
+ export const Handle: Handler = async ({ request, settings, callbacks, caller }) => {
5
+ // The runtime validates `request` against the requestSchema before this
6
+ // runs, and the response against the responseSchema before it reaches the
7
+ // caller.
8
+ //
9
+ // This endpoint is scenario-scoped: it runs on a scenario draft, with no
10
+ // session, for whoever is writing the scenario (`caller.role` is always
11
+ // 'author'). `settings` is the draft as it stands. It changes nothing: tell
12
+ // the author something they cannot work out from the settings alone, or
13
+ // make a file and return its `blob:` reference for them to write into a
14
+ // setting.
15
+ return {
16
+ // TODO: build the response shape declared in responseSchema
17
+ } as Awaited<ReturnType<Handler>>;
18
+ };
19
+ {%- else -%}
3
20
  export const Handle: Handler = async ({ request, context, callbacks, caller }) => {
4
21
  // The runtime validates `request` against the requestSchema before this
5
22
  // runs, and the response against the responseSchema before it reaches the
@@ -23,3 +40,4 @@ export const Handle: Handler = async ({ request, context, callbacks, caller }) =
23
40
  } as Awaited<ReturnType<Handler>>;
24
41
  {%- endif %}
25
42
  };
43
+ {%- endif %}
@@ -1,4 +1,4 @@
1
- import { logicArgs } from '@seriousgaming/sdk/testing';
1
+ import { createMockParticipant, logicArgs } from '@seriousgaming/sdk/testing';
2
2
  import { describe, it, expect } from 'vitest';
3
3
 
4
4
  import { defaultContext, defaultSettings } from '../defaults';
@@ -13,7 +13,7 @@ import { Run } from './logic';
13
13
  // participant the signal concerns) and offline callback stubs.
14
14
 
15
15
  // The participant the signal concerns.
16
- const participant = { id: '1', teamId: 'team-1', name: 'Participant 1', index: 0, connected: true };
16
+ const participant = createMockParticipant();
17
17
 
18
18
  describe('{{ identifier }}', () => {
19
19
  describe('Run', () => {
@@ -40,6 +40,8 @@ pnpm run --silent sdk docs view cli-reference.md # every command a
40
40
 
41
41
  The same files are on disk in `node_modules/@seriousgaming/sdk-tools/dist/docs/`, so you can search them with `grep -rn`. Start from `recipes/` for a task, `guides/` for a whole subject, and `concepts/` for the model.
42
42
 
43
+ `pnpm run sdk docs export` copies them into the package, for a tool that cannot read `node_modules`. The same docs for the newest release are at https://sdk.seriousgaming.com/llms.txt; prefer the installed copy, which matches the version this package runs.
44
+
43
45
  ## This package
44
46
 
45
47
  Unless it was created with `--empty`, this package holds a complete, playable starter game: a lemonade stand, run for 10 days. Each morning a team decides how many lemonades, iced teas, and cookies to make. Whatever they make they pay for, whatever is left at closing is poured away, and anyone who wanted something that ran out simply leaves.
@@ -61,7 +63,7 @@ A game works like a **reactive spreadsheet**:
61
63
  - **Settings**: read-only parameters, each property with a default, overridden by scenarios
62
64
  - **The engine**: the formulas (`Init` sets up, `Run` computes one tick)
63
65
  - **User interfaces**: charts and input cells (`ui/` for participants, `session/` for the facilitator, `waiting_room/` before play, `setup/` and `scenario_editor/` for settings)
64
- - **Validators**: data validation on input cells (reject a write, never change it)
66
+ - **Validators**: data validation on input cells (reject a write, never change it), and an optional `Scenario` gate that refuses a scenario breaking the game's rules
65
67
  - **Hooks**: handlers that run outside the tick on a signal such as `participantJoin`
66
68
  - **Endpoints**: server-side functions a surface, or with `visibility: "external"` a caller outside the game, calls by identifier
67
69
  - **Guide and presentation**: the facilitator's run-sheet and slide deck
@@ -284,7 +286,8 @@ expect(session.team(0).context.results.Day).toBe(1);
284
286
 
285
287
  ## User interfaces
286
288
 
287
- - **Default to MUI** (`@mui/material`), as the starter game does. Another library must integrate with `useUserInterfaceTheme` so colours and dark mode work, and text on a theme colour uses that colour's `contrastText` (`colors.contrastText.primary`)
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, 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
288
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
289
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
290
293
  - **A viewer's own choices** (a tab, a collapsed panel) go in `useViewerStorage(key, initial)`, never `localStorage`, which collides across sessions
@@ -141,3 +141,5 @@ pnpm run sdk docs view recipes/index.md
141
141
  The same documents are on disk in
142
142
  `node_modules/@seriousgaming/sdk-tools/dist/docs/`, and
143
143
  describe the SDK version you have installed.
144
+ The docs for the newest release are also online, at
145
+ https://sdk.seriousgaming.com.
@@ -14,9 +14,9 @@ Endpoints are named, server-side handlers that user interfaces (and, when its `v
14
14
  pnpm run --silent sdk docs view recipes/create-endpoint.md
15
15
  ```
16
16
  2. **Decide the request and response shapes.** Each is a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`).
17
- 3. **Decide what it touches**: which capabilities it `reads`, which it `writes` (if any), which settings resources it reads (`settings`), which runtime callbacks it `uses` (`generateText`, `extractText`, `generateSpeech`, `writeBlob`), which session `actions` it may return (such as advancing a tick or closing the waiting room), whether its `session` argument needs each team's participants (`roster: true`), and its `scope`: `team` (the default: it acts on the calling team's board) or `session` (for a session UI, setup screen, or scenario editor, which has no team of its own).
17
+ 3. **Decide what it touches**: which capabilities it `reads`, which it `writes` (if any), which settings resources it reads (`settings`), which runtime callbacks it `uses` (`generateText`, `extractText`, `generateSpeech`, `writeBlob`), which session `actions` it may return (such as advancing a tick or closing the waiting room), whether its `session` argument needs each team's participants (`roster: true`), and its `scope`: `team` (the default: it acts on the calling team's board), `session` (for a session UI or setup screen, which has no team of its own), or `scenario` (for the scenario editor, or an agent writing a scenario: it runs on a scenario draft, reads the draft's `settings`, and declares no `reads`, `writes`, `actions` or `roster`).
18
18
  4. **Create the endpoint** with `pnpm run sdk new endpoint '{ ... }'`, declaring `identifier`, `requestSchema`, `responseSchema`, and whichever of `reads`, `writes`, `settings`, `uses`, `actions`, `roster`, `scope`, `visibility`, and `description` apply. An outside caller, such as an AI agent, reads `description` to decide whether to call an external endpoint, so write it for that reader. An external endpoint's `requestSchema` must be `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`); one taking no input declares an object with no properties.
19
- 5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, participants, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team, or `teams` (every team's values) on a session-scoped endpoint that declares a capability that is not shared. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
19
+ 5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, participants, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team, or `teams` (every team's values) on a session-scoped endpoint that declares a capability that is not shared. A scenario-scoped endpoint takes `{ request, settings, callbacks, caller, meta }` only, and returns its response: it informs whoever is writing the scenario, such as working out what the draft would mean in play, or makes a file for a setting and returns its `blob:` reference, and never edits settings. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
20
20
  6. **Allow the UI to call it.** Add the endpoint identifier to the `endpoints` array in the bundle of every UI that should be permitted to call it (`pnpm run sdk update ui --patch '[...]'`). Without this, the host rejects the call and TypeScript flags it. The UI then calls `callbacks.endpoints['<name>'](request)`.
21
21
  7. **Add a unit test** in the scaffolded `endpoints/<name>/logic/logic.test.ts` covering the happy path and any branch in `Handle`.
22
22
  8. **Verify**: `pnpm run sdk endpoint list` shows its scope and whether it writes; `pnpm run --silent sdk endpoint call <name> --no-server --team 1 --request '{...}'` runs it without a UI; then `pnpm run build` and `pnpm test:run`.
@@ -30,6 +30,7 @@ Endpoints are named, server-side handlers that user interfaces (and, when its `v
30
30
  - Forgetting to add the endpoint identifier to the UI's `endpoints` array: the host rejects every call from that UI
31
31
  - Returning a capability outside `writes` in `capabilities`: the whole call fails and none of the change is applied
32
32
  - Returning a bare value from an endpoint that declares `writes` or `actions`, or `{ response, capabilities }` from one that declares neither
33
- - Calling a team-scoped endpoint from a session UI, setup screen, or scenario editor: the build fails. Set `"scope": "session"`
34
- - Listing an endpoint with `reads`, `writes` or `actions` in the scenario editor: the build fails (`EDITOR_ENDPOINT_STATEFUL`). The editor has no session, so its endpoints read their `settings`, resolved from the scenario being edited, and nothing else
33
+ - Calling a team-scoped endpoint from a session UI or setup screen: the build fails. Set `"scope": "session"`
34
+ - Listing an endpoint that is not `"scope": "scenario"` in the scenario editor: the build fails (`EDITOR_ENDPOINT_NOT_SCENARIO`). The editor has no session, so its endpoints read their `settings`, resolved from the draft being edited, and nothing else. A scenario-scoped endpoint declaring `reads`, `writes`, `actions` or `roster` fails too (`SCENARIO_ENDPOINT_STATEFUL`)
35
+ - Expecting an agent writing a scenario to reach an internal scenario-scoped endpoint: it calls only those marked `"visibility": "external"`. Try one as it would with `pnpm run --silent sdk endpoint call <name> --no-server --draft <scenario> --external --request '{...}'`
35
36
  - Returning binary data inline: declare `'writeBlob'` in `uses`, call `callbacks.writeBlob(bytes, { name, mimeType })`, and return the resulting `blob:<id>` reference in the JSON response
@@ -15,20 +15,27 @@ 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
  ````
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`
32
39
  - Raw HTML never renders: it is escaped to visible text. Use markdown, admonitions, and video blocks only
33
40
 
34
41
  ## Things that almost always go wrong
@@ -1,6 +1,6 @@
1
- import { Deck, defaultBrand, type Brand } from '@seriousgaming/deck';
1
+ import { brandFromTheme, Deck } from '@seriousgaming/deck';
2
2
  import { usePresentation } from '@seriousgaming/sdk/ui';
3
- import { useEffect } from 'react';
3
+ import { useEffect, useMemo } from 'react';
4
4
  import { useTranslation } from 'react-i18next';
5
5
 
6
6
  import type { Settings, SharedContext, TeamContext } from '../types';
@@ -12,8 +12,8 @@ with or without a session: in a game's library, while rehearsing or to export
12
12
  it beforehand, `session` is null, so every slide must make sense without
13
13
  results.
14
14
 
15
- The host's theme colours are mapped onto the deck's brand here, so the slides
16
- pick up the same primary and secondary as every other surface.
15
+ The host's theme becomes the deck's brand here, so the slides pick up the same
16
+ colours and fonts as every other surface.
17
17
  */
18
18
 
19
19
  export default function App() {
@@ -25,13 +25,7 @@ export default function App() {
25
25
  void i18n.changeLanguage(language);
26
26
  }, [i18n, language]);
27
27
 
28
- const brand: Partial<Brand> = {
29
- colors: {
30
- ...defaultBrand.colors,
31
- primary: theme.light.primary,
32
- secondary: theme.light.secondary,
33
- },
34
- };
28
+ const brand = useMemo(() => brandFromTheme(theme), [theme]);
35
29
 
36
30
  return (
37
31
  <Deck
@@ -1,5 +1,6 @@
1
1
  {% raw %}import {
2
2
  createMockSharedState,
3
+ createMockTeams,
3
4
  createMockTeamState,
4
5
  renderSessionUserInterface,
5
6
  } from '@seriousgaming/sdk/ui/testing';
@@ -21,10 +22,7 @@ const mockTimer = {
21
22
  extendedMs: 0,
22
23
  };
23
24
 
24
- const teams = [
25
- { teamId: 'team-1', index: 0, name: 'Team 1' },
26
- { teamId: 'team-2', index: 1, name: 'Team 2' },
27
- ];
25
+ const teams = createMockTeams(2);
28
26
 
29
27
  // `createMockTeamState` and `createMockSharedState` fill in the fields a test
30
28
  // rarely cares about, `revision` included. Typed with the generated contexts,
@@ -1,46 +1,39 @@
1
1
  {% raw %}import { createTheme } from '@mui/material/styles';
2
- import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useSessionUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
46
39
  {% endraw %}
@@ -1,24 +1,19 @@
1
- import { createTheme } from '@mui/material/styles';
2
- import { useSettingsEditorTheme } from '@seriousgaming/sdk/ui';
1
+ {% raw %}import { createTheme } from '@mui/material/styles';
2
+ import { createSurfaceTheme, useSettingsEditorTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
+ /**
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
10
+ */
5
11
  export const useAppTheme = () => {
6
12
  const theme = useSettingsEditorTheme();
7
13
 
8
- const appTheme = useMemo(() => {
9
- const themeColors = theme.mode === 'light' ? theme.light : theme.dark;
10
- return createTheme({
11
- palette: {
12
- mode: theme.mode,
13
- primary: { main: themeColors.primary, contrastText: themeColors.contrastText.primary },
14
- secondary: { main: themeColors.secondary, contrastText: themeColors.contrastText.secondary },
15
- success: { main: themeColors.success, contrastText: themeColors.contrastText.success },
16
- error: { main: themeColors.error, contrastText: themeColors.contrastText.error },
17
- warning: { main: themeColors.warning, contrastText: themeColors.contrastText.warning },
18
- info: { main: themeColors.info, contrastText: themeColors.contrastText.info },
19
- },
20
- });
21
- }, [theme]);
22
-
23
- return appTheme;
14
+ return useMemo(
15
+ () => createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } })),
16
+ [theme]
17
+ );
24
18
  };
19
+ {% endraw %}
@@ -1,4 +1,4 @@
1
- import { logicArgs } from '@seriousgaming/sdk/testing';
1
+ import { createMockParticipant, logicArgs } from '@seriousgaming/sdk/testing';
2
2
  import { describe, expect, it } from 'vitest';
3
3
 
4
4
  import { defaultContext, defaultSettings } from '../defaults';
@@ -18,13 +18,7 @@ const join = async (
18
18
  logicArgs.hook({
19
19
  context,
20
20
  settings,
21
- participant: {
22
- id,
23
- teamId: 'team-1',
24
- name: `Participant ${index + 1}`,
25
- index,
26
- connected: true,
27
- },
21
+ participant: createMockParticipant({ id, name: `Participant ${index + 1}`, index }),
28
22
  })
29
23
  )
30
24
  ).capabilities;
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  createMockSharedState,
3
+ createMockTeam,
3
4
  createMockTeamState,
4
5
  renderSessionUserInterface,
5
6
  type RenderSessionUserInterfaceOptions,
@@ -67,13 +68,8 @@ const traded = (made: { lemonade: number; icedtea: number }, plan = made): TeamC
67
68
  },
68
69
  });
69
70
 
70
- const sessionMeta = {
71
- sessionId: 'session-1',
72
- name: 'Tuesday cohort',
73
- readOnly: false,
74
- waitingRoomOpen: false,
75
- joinPin: null,
76
- };
71
+ // Only what the screen shows: the helper fills the rest of the session in.
72
+ const sessionMeta = { name: 'Tuesday cohort' };
77
73
 
78
74
  const links = [
79
75
  {
@@ -96,8 +92,8 @@ const render = (options: RenderSessionUserInterfaceOptions<SessionData> = {}) =>
96
92
  sessionMeta,
97
93
  teamLinks: links,
98
94
  teams: [
99
- { teamId: 'team-1', index: 0, name: 'Bluebird' },
100
- { teamId: 'team-2', index: 1, name: 'Kestrel' },
95
+ createMockTeam({ name: 'Bluebird' }),
96
+ createMockTeam({ index: 1, name: 'Kestrel' }),
101
97
  ],
102
98
  ...options,
103
99
  // A case names only the half it is about; the other keeps its default.
@@ -298,7 +294,7 @@ describe('a read-only session', () => {
298
294
  }),
299
295
  },
300
296
  },
301
- teams: [{ teamId: 'team-1', index: 0, name: 'Bluebird' }],
297
+ teams: [createMockTeam({ name: 'Bluebird' })],
302
298
  });
303
299
 
304
300
  expect(screen.getByText(/read only/)).toBeInTheDocument();