@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
@@ -6,6 +6,17 @@ Every export of `@seriousgaming/sdk/ui`, with the declaration it is published wi
6
6
 
7
7
  ## Functions
8
8
 
9
+ ### createSurfaceTheme
10
+
11
+ The host's theme as MUI theme options: every colour role with its `contrastText`, the page and surface colours and the text on them, and the brand's fonts, which the wrapper has already loaded.
12
+
13
+ ```ts
14
+ function createSurfaceTheme(
15
+ theme: SurfaceTheme,
16
+ options?: CreateSurfaceThemeOptions
17
+ ): SurfaceThemeOptions;
18
+ ```
19
+
9
20
  ### PresentationWrapper
10
21
 
11
22
  Wrap a presentation bundle. Read-only: there is nothing here to write with, and the host would refuse it if there were.
@@ -30,6 +41,14 @@ The wrapper for both settings editors, the `setup` slot and the `scenario_editor
30
41
  function SettingsEditorWrapper(props: SettingsEditorWrapperProps): import('react').JSX.Element;
31
42
  ```
32
43
 
44
+ ### SurfaceLoading
45
+
46
+ What a surface shows until the host has sent everything it needs and the brand's fonts have loaded: the default `fallback` of every wrapper.
47
+
48
+ ```ts
49
+ function SurfaceLoading(options: { label?: string }): ReactElement;
50
+ ```
51
+
33
52
  ### useAsset
34
53
 
35
54
  Fetch an asset and read its body, preferring a copy in the surface's locale.
@@ -57,6 +76,22 @@ The URL an `asset:`, `shared:` or `blob:` reference resolves to, for an `<img>`,
57
76
  function useAssetUrl(reference: string | null | undefined): string | undefined;
58
77
  ```
59
78
 
79
+ ### useBrand
80
+
81
+ The host's brand: always a name, empty only on a host that predates brands, and whatever logo, icon and fonts the host has.
82
+
83
+ ```ts
84
+ function useBrand(): Brand;
85
+ ```
86
+
87
+ ### useBrandLogo
88
+
89
+ The host's logo for the mode the surface is painting in, falling back to the other variant when the host sent only one. Undefined when the brand has no logo: the SDK never supplies one of its own, so a white-label host never shows someone else's.
90
+
91
+ ```ts
92
+ function useBrandLogo(): BrandLogo | undefined;
93
+ ```
94
+
60
95
  ### useMutationReporter
61
96
 
62
97
  Runs a fallible mutation (`setData`, `requestTick`, and the rest) so that a failure reaches the participant instead of vanishing.
@@ -582,6 +617,14 @@ The React context behind `useSettingsEditorThemePreference`.
582
617
  const SettingsEditorThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
583
618
  ```
584
619
 
620
+ ### SurfaceThemeContext
621
+
622
+ The theme of whichever surface is rendering, for the hooks every surface shares. Provided by every wrapper; game code reads it through `useBrand` and `useBrandLogo`.
623
+
624
+ ```ts
625
+ const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
626
+ ```
627
+
585
628
  ### UserInterfaceCallbacksContext
586
629
 
587
630
  The React context behind `useUserInterfaceCallbacks`.
@@ -737,6 +780,73 @@ interface AssetState<T> {
737
780
  }
738
781
  ```
739
782
 
783
+ ### Brand
784
+
785
+ The host's brand: what a white-label host dresses the game in.
786
+
787
+ ```ts
788
+ interface Brand {
789
+ name: string;
790
+ logo?: {
791
+ onLight?: string;
792
+ onDark?: string;
793
+ };
794
+ icon?: string;
795
+ fonts?: {
796
+ heading?: BrandFont;
797
+ body?: BrandFont;
798
+ };
799
+ }
800
+ ```
801
+
802
+ ### BrandFont
803
+
804
+ A font family the host's brand sets text in, and the files it is drawn from.
805
+
806
+ ```ts
807
+ interface BrandFont {
808
+ family: string;
809
+ sources: BrandFontSource[];
810
+ }
811
+ ```
812
+
813
+ ### BrandFontSource
814
+
815
+ One file a brand font is drawn from.
816
+
817
+ ```ts
818
+ interface BrandFontSource {
819
+ url: string;
820
+ weight?: string;
821
+ style?: string;
822
+ }
823
+ ```
824
+
825
+ ### BrandLogo
826
+
827
+ The logo `useBrandLogo` picked, and the background it was drawn for.
828
+
829
+ ```ts
830
+ interface BrandLogo {
831
+ src: string;
832
+ alt: string;
833
+ drawnFor: 'light' | 'dark';
834
+ }
835
+ ```
836
+
837
+ ### CreateSurfaceThemeOptions
838
+
839
+ The game's own fonts, used wherever the host's brand names none.
840
+
841
+ ```ts
842
+ interface CreateSurfaceThemeOptions {
843
+ fonts?: {
844
+ body?: string;
845
+ heading?: string;
846
+ };
847
+ }
848
+ ```
849
+
740
850
  ### EndpointFailure
741
851
 
742
852
  A failed endpoint call, itemised so a caller can tell 'nothing happened' from 'the writes landed, then an action failed'.
@@ -866,6 +976,46 @@ interface SessionUserInterfaceHookFailuresValue {
866
976
  }
867
977
  ```
868
978
 
979
+ ### SurfacePaletteColor
980
+
981
+ A palette colour as MUI takes it.
982
+
983
+ ```ts
984
+ interface SurfacePaletteColor {
985
+ main: string;
986
+ contrastText: string;
987
+ }
988
+ ```
989
+
990
+ ### SurfaceThemeOptions
991
+
992
+ MUI theme options for a surface: plain data, so this package takes no MUI dependency. Pass it to `createTheme` first, with the game's own shape and component overrides after it.
993
+
994
+ ```ts
995
+ interface SurfaceThemeOptions {
996
+ palette: Record<ThemeColorRole, SurfacePaletteColor> & {
997
+ mode: 'light' | 'dark';
998
+ background: {
999
+ default: string;
1000
+ paper: string;
1001
+ };
1002
+ text: {
1003
+ primary: string;
1004
+ };
1005
+ };
1006
+ typography: {
1007
+ fontFamily: string;
1008
+ } & Partial<
1009
+ Record<
1010
+ (typeof HEADINGS)[number],
1011
+ {
1012
+ fontFamily: string;
1013
+ }
1014
+ >
1015
+ >;
1016
+ }
1017
+ ```
1018
+
869
1019
  ### TeamInfo
870
1020
 
871
1021
  Who a team is: the fields every team entry in the SDK carries.
@@ -1162,6 +1312,7 @@ type SessionUserInterfaceTheme = {
1162
1312
  mode: 'dark' | 'light';
1163
1313
  dark: SessionUserInterfaceModeColors;
1164
1314
  light: SessionUserInterfaceModeColors;
1315
+ brand: Brand;
1165
1316
  };
1166
1317
  ```
1167
1318
 
@@ -1196,6 +1347,7 @@ type SettingsEditorTheme = {
1196
1347
  mode: 'dark' | 'light';
1197
1348
  dark: SettingsEditorModeColors;
1198
1349
  light: SettingsEditorModeColors;
1350
+ brand: Brand;
1199
1351
  };
1200
1352
  ```
1201
1353
 
@@ -1220,6 +1372,19 @@ type SharedState<TSharedContext = Record<string, unknown>> = {
1220
1372
  };
1221
1373
  ```
1222
1374
 
1375
+ ### SurfaceTheme
1376
+
1377
+ What every surface's theme carries, whichever wrapper delivers it.
1378
+
1379
+ ```ts
1380
+ type SurfaceTheme = {
1381
+ mode: 'dark' | 'light';
1382
+ dark: SurfaceModeColors;
1383
+ light: SurfaceModeColors;
1384
+ brand: Brand;
1385
+ };
1386
+ ```
1387
+
1223
1388
  ### TeamConfiguration
1224
1389
 
1225
1390
  How teams work in this session: the interaction mode, and the bounds the host will hold the surface to.
@@ -1299,6 +1464,7 @@ type UserInterfaceTheme = {
1299
1464
  mode: 'dark' | 'light';
1300
1465
  dark: UserInterfaceModeColors;
1301
1466
  light: UserInterfaceModeColors;
1467
+ brand: Brand;
1302
1468
  };
1303
1469
  ```
1304
1470
 
@@ -177,7 +177,7 @@ interface CapabilityDefinition {
177
177
 
178
178
  ### EndpointBaseArgs
179
179
 
180
- The arguments every endpoint receives, whatever its scope.
180
+ The arguments every team- or session-scoped endpoint receives.
181
181
 
182
182
  ```ts
183
183
  interface EndpointBaseArgs<
@@ -221,7 +221,7 @@ interface EndpointDefinition {
221
221
  identifier: string;
222
222
  displayName?: string;
223
223
  description?: string;
224
- scope?: 'session' | 'team';
224
+ scope?: 'session' | 'team' | 'scenario';
225
225
  requestSchema: {
226
226
  [k: string]: unknown;
227
227
  };
@@ -406,6 +406,7 @@ interface FacilitatorGuideDefinition {
406
406
  name: string;
407
407
  };
408
408
  };
409
+ settings?: string[];
409
410
  }
410
411
  ```
411
412
 
@@ -679,6 +680,7 @@ interface LogicMeta {
679
680
  seed: string;
680
681
  runKind: RunKind;
681
682
  now: number;
683
+ scenarioName?: string | null;
682
684
  }
683
685
  ```
684
686
 
@@ -814,6 +816,7 @@ interface ResolvedPackageManifest {
814
816
  manifestVersion?: number;
815
817
  requires?: RequiredFeatures;
816
818
  scenarioFormat?: ScenarioFormat;
819
+ builtWith?: BuiltWith;
817
820
  package: SDKPackage;
818
821
  game: SDKGame;
819
822
  engine?: SDKEngine;
@@ -941,6 +944,46 @@ interface ScenarioEditorDefinition {
941
944
  }
942
945
  ```
943
946
 
947
+ ### ScenarioEndpointArgs
948
+
949
+ What a scenario-scoped endpoint receives: a scenario draft, and no session. There is no board, roster or round for `context`, `participants` or `session` to describe, so none is typed, and reaching for one fails to compile rather than reading an invented empty value.
950
+
951
+ ```ts
952
+ interface ScenarioEndpointArgs<
953
+ TRequest,
954
+ TCallbacks = SignatureCallbacks,
955
+ TSettings = Record<string, never>,
956
+ > {
957
+ request: TRequest;
958
+ callbacks: TCallbacks;
959
+ caller: EndpointCaller;
960
+ settings: TSettings;
961
+ meta: LogicMeta;
962
+ }
963
+ ```
964
+
965
+ ### ScenarioFunctionArgs
966
+
967
+ Arguments of a validator's `Scenario` gate.
968
+
969
+ ```ts
970
+ interface ScenarioFunctionArgs<TSettings> {
971
+ settings: TSettings;
972
+ locale: string;
973
+ }
974
+ ```
975
+
976
+ ### ScenarioProblem
977
+
978
+ One thing wrong with a scenario. `path` names the setting it is about, dotted from the settings identifier (`ui.MinPrice`), so an editor can show the problem beside the field.
979
+
980
+ ```ts
981
+ interface ScenarioProblem {
982
+ message: string;
983
+ path?: string;
984
+ }
985
+ ```
986
+
944
987
  ### ScheduleOptions
945
988
 
946
989
  Options accepted by all schedule-computation helpers.
@@ -2050,6 +2093,29 @@ Which kind of run a function is executing in.
2050
2093
  type RunKind = 'session' | 'walkthrough';
2051
2094
  ```
2052
2095
 
2096
+ ### ScenarioEndpointHandler
2097
+
2098
+ Function signature for a scenario-scoped endpoint. It returns its response alone: it changes nothing, and a file it makes for a setting is returned as a `blob:` reference for the author to write into the draft.
2099
+
2100
+ ```ts
2101
+ type ScenarioEndpointHandler<
2102
+ TRequest = unknown,
2103
+ TResponse = unknown,
2104
+ TCallbacks = SignatureCallbacks,
2105
+ TSettings = Record<string, never>,
2106
+ > = (args: ScenarioEndpointArgs<TRequest, TCallbacks, TSettings>) => Promise<TResponse>;
2107
+ ```
2108
+
2109
+ ### ScenarioFunction
2110
+
2111
+ A validator's `Scenario` export: the gate on a scenario. It runs at build on every package scenario, and on a session with no scenario when the game has no default, and when a custom scenario is saved. Never when a session is created. Returns every problem it finds; an empty array passes.
2112
+
2113
+ ```ts
2114
+ type ScenarioFunction<TSettings = unknown> = (
2115
+ args: ScenarioFunctionArgs<TSettings>
2116
+ ) => Promise<ScenarioProblem[]>;
2117
+ ```
2118
+
2053
2119
  ### StepFunction
2054
2120
 
2055
2121
  One step of an engine that splits its `Init` or `Run` into several functions.
@@ -2122,10 +2188,10 @@ type ValidatorFunction<TContext = unknown, TSettings = unknown> = (
2122
2188
 
2123
2189
  ### ValidatorGate
2124
2190
 
2125
- A participant action a validator can gate, named after the surface message it gates: a context write, or a request for the next tick
2191
+ 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)
2126
2192
 
2127
2193
  ```ts
2128
- type ValidatorGate = 'updateData' | 'requestTick';
2194
+ type ValidatorGate = 'updateData' | 'requestTick' | 'scenario';
2129
2195
  ```
2130
2196
 
2131
2197
  ### WaitingRoomUserInterfaceCallbacks
@@ -7,9 +7,13 @@ and the SDK adheres to [Semantic Versioning](https://semver.org/).
7
7
 
8
8
  ## How to read this file
9
9
 
10
- 1. Find your currently installed SDK version in `package.json` (or run
11
- `cat node_modules/@seriousgaming/sdk/package.json | grep '"version"'`, or
12
- `node_modules/@businesssimulations/seriousgaming-sdk/package.json` before 1.0).
10
+ 1. Find your installed SDK version with `pnpm run sdk version` (the
11
+ `seriousgaming-sdk version` command). A workspace that pins the SDK in a
12
+ catalog has `"catalog:"` in `package.json` and the version in
13
+ `pnpm-workspace.yaml`. From the game's directory,
14
+ `cat node_modules/@seriousgaming/sdk/package.json | grep '"version"'` also
15
+ works (`node_modules/@businesssimulations/seriousgaming-sdk/package.json`
16
+ before 1.0).
13
17
  2. Read every entry **above** that version: those are the changes since you
14
18
  last updated.
15
19
  3. If any entry is under **Breaking Changes**, address it before rebuilding.
@@ -27,6 +31,60 @@ are in the [0.x changelog](changelog-0.x.md).
27
31
 
28
32
  ## [Unreleased]
29
33
 
34
+ ## [1.1.0] — 2026-10-24
35
+
36
+ ### Added
37
+
38
+ - **Your game can wear the host's brand.** The theme now carries the host's brand: always its name, and, where the brand has them, a logo for light and dark backgrounds, a square icon and the fonts its text is set in. Every mode also carries page, surface and text colours. `createSurfaceTheme(theme, { fonts })` in `@seriousgaming/sdk/ui` turns the theme into Material-UI theme options with every colour, its `contrastText`, the page colours and the brand's fonts, so a game no longer maps the palette by hand. `useBrand()` gives the brand and `useBrandLogo()` the logo for the current mode, or `undefined` when the brand has none, on every surface. On a host that predates brands, the wrapper fills in a brand with an empty name and a plain page, so a game never has to check for them. The mock themes in `@seriousgaming/sdk/ui/testing` carry a brand that is only a name. The wrapper loads a brand's fonts before first paint, waiting at most 1.5 seconds. `createMockBrand()` in `@seriousgaming/sdk/ui/testing` gives a brand to test with. The starter game shows the host's logo in its top bar, and the factory example in its tab bar. See [Theming and branding](guides/theming-and-branding.md)
39
+ - **Preview your game in another brand.** The dev drawer has a **Brand** menu, beside the colour scheme, offering Serious Gaming, a plain brand that is only a name, and an awkward test brand built to show up hard-coded colours and layouts. `sdk dev --brand <file>` adds a brand of your own from a JSON file, with its logos, fonts and an optional loading animation beside it, and selects it. Its **Loading** menu holds every surface on the dev server's loading screen, or on your game's own, for as long as you want to look at it. See [Preview your game in another brand](guides/theming-and-branding.md#preview-your-game-in-another-brand)
40
+ - **`brandFromTheme(theme)` in `@seriousgaming/deck`** turns the host's theme into a deck brand: the accents and the host's own text colours for them, the neutral colours and the brand's fonts. The deck now draws text on its primary and secondary colours in the host's `contrastText` when it is given one
41
+ - **The host covers a surface until it has painted.** The wrapper reports when a surface's first paint is on screen, so a host can keep its own loading screen up until then rather than lifting it onto a blank frame. The dev server does, showing the picked brand's loading animation (the Serious Gaming icon's bar filling and draining) or its logo
42
+ - **`createMockTeam` and `createMockTeams` build the `TeamInfo` a test needs.** Import them from `@seriousgaming/sdk/testing` for a logic test or `@seriousgaming/sdk/ui/testing` for a user interface test: the team an endpoint acts on, a session surface's `teams`, or a surface's `ownTeam`. `teamId` and `name` follow `index` unless given, so `createMockTeam({ index: 2 })` is `team-3`, `Team 3`. Build teams with these rather than by hand, so a field later added to `TeamInfo` reaches your tests with a value. `createMockParticipant` and `createMockParticipants` are now importable from `@seriousgaming/sdk/testing` as well, for the participant a hook's payload or a validator's actor names. The scaffold's `templates/session/src/App.test.tsx.liquid`, `templates/waiting-room/src/App.test.tsx.liquid` and `templates/hook/logic.test.ts.liquid`, and the starter game's tests, now use them. See [Testing](guides/testing.md#testing-hooks-endpoints-validators-and-tick-controllers)
43
+ - **Endpoints for writing scenarios: `"scope": "scenario"`.** A scenario-scoped endpoint runs on a scenario being written, a draft, with no session: it receives the draft's `settings`, `request`, `callbacks`, `caller` and `meta`, and no `context`, `participants` or `session`, and returns its response alone. Use it to tell whoever is writing a scenario what they cannot work out from the settings, such as what a round would come to under the draft, or to make a file for a setting. Every call reports `caller.role` as `'author'`. The scenario editor calls those it lists, and an agent writing a scenario calls those marked `"visibility": "external"`. Its generated `Handler` is the new `ScenarioEndpointHandler`, `logicArgs.scenarioEndpoint` builds its test arguments, and `sdk new endpoint` scaffolds it. `sdk endpoint call --draft [scenario]` calls one on a draft, as an agent would with `--external`. The factory example's `configassistant` is one, and its new external `previewround` works out a round under the draft with the engine's own maths. See [Scenario-scoped endpoints](guides/endpoints.md#scenario-scoped-endpoints) and [Writing scenarios with an agent](guides/scenarios.md#writing-scenarios-with-an-agent). The scaffold's endpoint templates (`templates/endpoint/logic.ts.liquid` and `logic.test.ts.liquid`) and its `workflow-create-endpoint.md` rule cover the new scope. A production host that predates this refuses a package with a scenario-scoped endpoint, naming the scope, so check the host supports it first
44
+ - **A setting can say what file it holds.** Mark a string settings property with `"blob": { "accept": [...], "maxBytes": ... }`, as an endpoint request marks a file. Its value is an `asset:`, `shared:` or `blob:` reference, or empty for none. The build checks the declaration, refuses a default that is not empty or `shared:`, and checks every file a package scenario names is shipped, small enough and of an accepted type. A setup screen, the scenario editor or an agent writing a `blob:` reference that names no stored file, or one too large or of the wrong type, is refused as `denied`, naming the setting, and so is a value that is not a reference. The factory example's `BrandingLogo` declares one. A production host that predates this may refuse the package or a file setting's value, so check the host supports it before relying on it. See [Settings that hold a file](guides/settings.md#settings-that-hold-a-file)
45
+ - **Files made for a scenario belong to the scenario.** Uploads from the scenario editor, and every file a scenario-scoped endpoint stores, take a new `'scenario'` retention that no session reset, re-initialise or scenario change clears. `sdk blob upload --scenario` stores one. A draft reads those files and never a session's: a file input on a draft, or a file setting edited on one, naming a session's `'game'` or `'settings'` file is refused, since the scenario would lose it at the session's next reset. See [Blob scopes](guides/file-handling.md#blob-scopes)
46
+ - **The game is told which scenario the session is running.** Logic reads its name as `meta.scenarioName`, and a participant, waiting room or session UI as `scenarioName` from `useUserInterfaceData()` or `useSessionUserInterfaceData()`, in the session's language, or `null` when the session runs on the game's own settings. Show it so the room can tell one copy of a scenario from another, but never branch on it: a facilitator's own copy has a name of its own. See [Showing the scenario](guides/engine.md#showing-the-scenario). `meta.scenarioName` is optional, because a production host that predates it leaves it out, and the user interface hooks read `null` there. The `render*` helpers in `@seriousgaming/sdk/ui/testing` take a `scenarioName` option, `logicArgs` defaults it to `null`, and `sdk view --full` reports it as `game.scenarioName`
47
+ - **`@seriousgaming/sdk`, `@seriousgaming/sdk-tools` and `@seriousgaming/deck` export `./package.json`**, so `require.resolve('@seriousgaming/sdk/package.json')` and the tools that read a package's version that way no longer fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`
48
+ - **A facilitator guide can follow the session's settings.** List the settings resources it reads in `guide.sdk.json`'s `settings`, then show a value in any chapter with `:setting[engine.totalWeeks]` and show a block only sometimes with `:::when{setting="engine.observers"}` (with `is="…"` to compare and `not` to invert). A chapter left with nothing to show is left out of the guide, so wrapping a chapter in one `:::when` shows it only in the scenarios that need it. The build checks every name and value against the settings schemas. See [Facilitator guides](guides/guide.md#following-the-scenarios-settings) and the new recipe, [Make a guide follow the scenario](recipes/make-a-guide-follow-the-scenario.md). A production host that predates this shows the directives as errors or literal text, so check the host supports it before relying on it
49
+ - **`sdk init`, `sdk tick` and `sdk view` take `--summary`**, which prints only `gameId`, `completedTicks`, `maxTicks` and `complete` (and `scenario` for `init`) instead of the whole context, for a smoke check or an agent that cannot read thousands of lines. With `--json`, the envelope's `data` carries the same shape. See [A summary instead of the state](cli-reference.md#a-summary-instead-of-the-state)
50
+ - **The conformance suite checks that a forked custom scenario keeps its source's settings.** The specification now says outright that a session on an unedited fork resolves every setting, the `game` settings included, exactly as a session on its source would. A new optional `custom-scenarios` driver capability, with `forkScenario`, lets the suite fork a package scenario and a custom one and compare the sessions. A driver that does not offer it has those checks reported unsupported
51
+ - **The conformance suite checks files on a scenario draft.** A file sent inline on a draft is stored as the draft's and comes back as a `blob:` reference the draft can use again, even after the session beside it resets, and a draft refuses a URL, an unknown blob and a session's file, in a file input or a file setting. The specification now says what a draft can read: `scenario` files, and those the scenario it started from references. A new optional `draft-edits` driver capability, with `editDraft`, lets the suite edit a draft's settings; a driver that does not offer it has those checks reported unsupported
52
+ - **The conformance suite checks that the scenario editor opens on the scenario it edits.** FEAT-013 now says outright that the editor's `setSettings` carries the settings it configures resolved under that scenario, never the defaults alone, since an editor seeded with the defaults and then saved writes them into the scenario. Two new checks cover a package scenario and, for a driver offering `custom-scenarios`, a custom one
53
+ - **`@seriousgaming/sdk-tools/host` exports how the host reads a guide**: `chapterSources` for per-file locale fallback, and `evaluateChapter`, `remarkGuideSettings`, `isChapterEmpty` and their helpers for settings in guide content, so a platform renders the same guide the dev server does
54
+ - **A game can refuse a scenario that breaks its rules.** A validator may export `Scenario`, which receives the scenario's resolved settings and returns every problem it finds, each naming the setting it is about as a `path` where it can. Use it for what a settings schema cannot say: two values that conflict, such as a lowest price above the highest, or a value every scenario must supply, defaulted to an empty one. `sdk build` runs it on every package scenario, and on the defaults when no scenario is the default, failing with `SCENARIO_REFUSED`; saving a scenario from the dev server runs it too. It never runs when a session starts. A game using it lists `"scenario-validation"` in `requires` (the build says so with `FEATURE_UNDECLARED` otherwise), so a production host without it refuses the game rather than skipping the check. The factory example's editor shows its price and worker rules under each field, from a file the gate shares. See [Gating scenarios](guides/validators.md#gating-scenarios) and the new recipe, [Validate a game's scenarios](recipes/validate-scenarios.md). The scaffold's validator template, `templates/validator/logic.ts.liquid`, mentions the new export
55
+ - **The built manifest records what built it.** `sdk build` writes `builtWith` into `dist/seriousgaming.json`: `sdk`, the SDK tools version that ran the build, and `specRevision`, the revision of the specification that SDK implements. It is informational, so a host may warn when your package expects a later revision than it implements, and never refuses a package for it. You never write it yourself. `@seriousgaming/sdk-tools/runtime` exports `SPEC_REVISION` and `isLaterSpecRevision` for a host making that comparison
56
+ - **The conformance suite holds a runtime to the revision of the specification it implements.** Every Appendix B item records the revision that added it, `checksForRevision(revision, ALL_CHECKS)` keeps the checks a runtime implementing that revision is held to, and `buildReport(runtime, results, revision)` reports against it, listing later items apart rather than as failures. Without a revision, a report is made against the latest. See the suite's README, 'Holding a runtime to a revision'. `SG_CONFORMANCE_REVISION=1.0 pnpm test:conformance` runs the SDK's own suite at 1.0
57
+
58
+ ### Changed
59
+
60
+ - **The dev server is Serious Gaming throughout.** Its console, and the theme it sends your surfaces, are the Serious Gaming purple and teal with Sora and Work Sans, in place of the navy and teal it used before. A game whose look depended on the old dev palette will look different in development, and nowhere else: the platform sends its own theme
61
+ - **The default loading screen is a spinner.** A surface waiting for the host now shows a small spinner, in place of the unstyled 'Loading...' text that flashed white in dark mode. It follows the browser's light or dark scheme until the host's theme arrives, then the theme's mode, page colour and primary colour. A `fallback` you pass to a wrapper still replaces it, and `SurfaceLoading` is exported for a fallback of your own
62
+ - **The deck's default brand is Serious Gaming.** A deck given no brand is drawn in the Serious Gaming purple, teal and charcoal, with Sora headings and Work Sans text where those fonts are loaded, in place of a generic blue and teal. Unlike the dev palette, this shows on the platform too, for any presentation that relies on the default
63
+ - **Every scaffolded theme uses `createSurfaceTheme`, and applies its font.** The `theme.ts` templates (`templates/ui/src/theme.ts.liquid`, `templates/session/src/theme.ts.liquid`, `templates/waiting-room/src/theme.ts.liquid` and `templates/settings-editor/src/theme.ts.liquid`) and the starter game's build the theme with `createSurfaceTheme` and pass `Work Sans Variable`, the font they import. Before, the font was imported but never applied, so games rendered in Roboto. The scaffold's `CLAUDE.md.template` says to honour the host's brand. An existing game can make the same change to its own `theme.ts`
64
+ - **A theme carries the brand and the page colours, so one built by hand needs them.** `UserInterfaceTheme`, `SessionUserInterfaceTheme` and `SettingsEditorTheme` have a required `brand`, and every mode a required `background`, `surface` and `text`. The wrappers fill them in on a host that sends none, so reading a theme is unchanged. A test that builds a whole theme or mode by hand fails to compile until it adds them: spread `createMockUserInterfaceTheme().light`, or the mock for its surface, and override only the colours the test is about
65
+ - **`renderSessionUserInterface` takes only the `sessionMeta` and `teamConfiguration` fields a test is about.** Each is merged over the helper's default, so `sessionMeta: { readOnly: true }` and `teamConfiguration: { max: 2 }` replace a full object. A full object still works
66
+ - **The scenario editor lists only scenario-scoped endpoints.** An editor listing a session-scoped endpoint now fails the build with `EDITOR_ENDPOINT_NOT_SCENARIO`, which replaces `EDITOR_ENDPOINT_STATEFUL` (removed, so a script matching that code should match `EDITOR_ENDPOINT_NOT_SCENARIO` and `SCENARIO_ENDPOINT_STATEFUL`); such an endpoint was answered with an empty context and a made-up session. Set `"scope": "scenario"` on it, remove any `reads`, `writes`, `actions` or `roster` (`SCENARIO_ENDPOINT_STATEFUL`), run `pnpm run sdk generate`, and drop any use of `context`, `participants` or `session` from its handler. Calling a scenario-scoped endpoint on a session, or any other endpoint on a draft, is refused as `denied`. No other surface may list a scenario-scoped endpoint. See [step 7e](guides/upgrading.md#7e-give-the-scenario-editor-scenario-scoped-endpoints)
67
+ - **A scenario editor's uploads are no longer `'settings'` blobs.** They take the new `'scenario'` retention, so re-initialising the session running beside the editor no longer deletes them
68
+ - **The build no longer advises widening a setting to allow `null`.** A settings schema that declares a top-level `required`, or an object default missing a key its `required` lists, used to be told to make the value nullable, which made every reader guard a `null` the game never meant to send. The messages now suggest an empty default and a `Scenario` gate where every scenario must supply a real value
69
+ - **The scaffolded user interface and waiting room tests render through `renderUserInterface`** (`templates/ui/src/App.test.tsx.liquid` and `templates/waiting-room/src/App.test.tsx.liquid`) rather than providing `UserInterfaceDataContext` and its neighbours by hand. The data context now carries `scenarioName`, so a test that still provides it by hand fails to compile until it adds `scenarioName: null`. Switching to `renderUserInterface` from `@seriousgaming/sdk/ui/testing`, as the new templates do, fixes it and keeps a later field from doing the same. The React context objects were never covered by semantic versioning; the hooks that read them are
70
+ - **The scaffold points agents at the docs.** The scaffolded `CLAUDE.md.template` now points an agent at `pnpm run sdk docs export` and at the online docs' `llms.txt`, and `README.md.liquid` links the online docs. Merge both into an existing package by hand if you want them
71
+ - **The presentation scaffold takes the host's brand whole.** `templates/presentation/src/App.tsx.liquid` builds the deck's brand with `brandFromTheme`, so a new presentation picks up the host's fonts and text colours as well as its primary and secondary. The scaffold's `workflow-create-guide.md` rule now covers settings in a guide, and `CLAUDE.md.template` mentions the `Scenario` gate. Merge them into an existing package by hand if you want them
72
+
73
+ ### Fixed
74
+
75
+ - **A participant page in the dev server is told when a quick round starts.** When a round started and settled before the page next rendered, the page passed on only the second message, so the surface never saw `isRoundProcessing` become true
76
+ - **A presentation opened on its own page in the dev server names the scenario.** Opened from a link rather than inside the console, a presentation was told no scenario, so a deck showing `game.scenarioName` showed nothing there
77
+ - **The dev server's guide falls back to another locale for an untranslated chapter.** A chapter missing from the locale you were reading disappeared from the guide; it now shows from `en`, or the first declared locale, with a notice that it is not yet translated, as a production host shows it. The guide page also opens a chapter from its URL (`/guide?locale=de&chapter=02-running-the-game.md`)
78
+ - **Editing a guide chapter refreshes the dev server's guide.** The guide page read the guide once and kept it until you refreshed the browser, and edits to chapter files did not reload the package at all
79
+ - **An `asset:` or `shared:` reference can no longer reach a sibling directory.** The traversal guard compared paths without a separator, so `asset:../assets-old/x.png` read a file from `assets-old/` beside the scenario's `assets/`
80
+ - **`openHostOverlay`'s `target` is documented as the specification defines it.** The SDK's callback and protocol docs, and the session guide, said the guide overlay took a guide identifier. A game holds one guide, so the target is ignored; only print sheets take one, a team id
81
+
82
+ ### Security
83
+
84
+ - **Two `pnpm audit` advisories are left open on purpose.** `fast-uri` (through `ajv`) and `body-parser` (through `express`, used by the dev server) are patched in releases younger than the seven-day gate on new dependencies. A game's own install resolves the patched versions once they are published, since the SDK's ranges already allow them; the SDK's lockfile takes them once they clear the gate, on 26 and 29 October
85
+
86
+ ## [1.0.0] — 2026-10-18
87
+
30
88
  ### Breaking Changes
31
89
 
32
90
  #### Packages
@@ -63,7 +121,7 @@ are in the [0.x changelog](changelog-0.x.md).
63
121
  - **An external endpoint's request is an object.** The build refuses an endpoint with `"visibility": "external"` whose `requestSchema` is not `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`), since an outside caller, such as an AI agent, passes named arguments. Internal endpoints are unaffected. See [step 7a](guides/upgrading.md#7a-replace-agentcallable-with-visibility)
64
122
  - **Handlers receive `settings`, `session` and, team-scoped, `team`.** The generated `Handler` type requires them, so a unit test building arguments by hand passes them, or uses `logicArgs.endpoint`. A session-scoped handler's type has no `team`. See [step 7b](guides/upgrading.md#7b-handle-the-new-arguments)
65
123
  - **`caller.teamId` is the caller's own team**, absent for a facilitator or a caller outside the game, where it held the endpoint's target team. Read the target from `team`. See [step 7d](guides/upgrading.md#7d-read-the-target-team-from-team)
66
- - **The scenario editor calls only endpoints that need no session.** The build refuses a `scenario_editor` listing an endpoint that declares `reads`, `writes` or `actions` (`EDITOR_ENDPOINT_STATEFUL`), and the dev server answers a call from the editor with no session: the endpoint's `settings` resolved from the scenario being edited and the editor's unsaved changes, an empty `context`, no participants, a `session` of nothing played, and a `caller` of the new role `'author'`, not `'facilitator'`, since whoever creates a scenario may not be a facilitator, with no `sessionId`, which is now optional on `EndpointCaller`. The `workflow-create-endpoint.md` rule says so. See [step 7e](guides/upgrading.md#7e-give-the-scenario-editor-endpoints-that-need-no-session)
124
+ - **The scenario editor calls only endpoints that need no session.** The build refuses a `scenario_editor` listing an endpoint that declares `reads`, `writes` or `actions` (`EDITOR_ENDPOINT_STATEFUL`), and the dev server answers a call from the editor with no session: the endpoint's `settings` resolved from the scenario being edited and the editor's unsaved changes, an empty `context`, no participants, a `session` of nothing played, and a `caller` of the new role `'author'`, not `'facilitator'`, since whoever creates a scenario may not be a facilitator, with no `sessionId`, which is now optional on `EndpointCaller`. The `workflow-create-endpoint.md` rule says so. See [step 7e](guides/upgrading.md#7e-give-the-scenario-editor-scenario-scoped-endpoints)
67
125
  - **Endpoint failures are typed.** A surface's endpoint call rejects with `EndpointError` (`kind`, `outcome`, `applied`, `failedStep`), `callEndpoint:response` carries those fields in place of `error`, and `Session.query` and `createTestSession().send` answer `{ type: 'endpointFailure', failure }` instead of throwing. See [step 7c](guides/upgrading.md#7c-branch-on-an-endpoint-failures-kind)
68
126
 
69
127
  #### Surfaces
@@ -73,7 +131,7 @@ are in the [0.x changelog](changelog-0.x.md).
73
131
  - **`uses` on user interfaces is removed**, and the build refuses it. It never had an effect; a surface reaches a service through an endpoint that declares it. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
74
132
  - **Demo mode is removed.** `demo` in the manifest and scenarios, `GameDemo` and `sdk dev --demo` are gone, and the build refuses the field. Use a walkthrough run to show a game. See [step 9](guides/upgrading.md#step-9-meet-what-the-build-and-runtime-now-enforce)
75
133
  - **A session UI's callbacks include `deleteTeam`**, so a hand-built callbacks object in a test must supply it. See [step 10d](guides/upgrading.md#10d-update-ui-component-tests)
76
- - **Four `./ui` names pair with their hook or theme type.** `CrossTeamDataContext` is `UserInterfaceCrossTeamDataContext`, `UserInterfaceValidationContext` is `UserInterfaceValidationRejectionsContext` (its value type `UserInterfaceValidationRejectionsValue`), and in `./ui/testing` `createMockTheme` is `createMockUserInterfaceTheme` and `createMockSessionTheme` is `createMockSessionUserInterfaceTheme`
134
+ - **Four `./ui` names pair with their hook or theme type.** `CrossTeamDataContext` is `UserInterfaceCrossTeamDataContext`, `UserInterfaceValidationContext` is `UserInterfaceValidationRejectionsContext` (its value type `UserInterfaceValidationRejectionsValue`), and in `./ui/testing` `createMockTheme` is `createMockUserInterfaceTheme` and `createMockSessionTheme` is `createMockSessionUserInterfaceTheme`. See [step 10d](guides/upgrading.md#10d-update-ui-component-tests)
77
135
 
78
136
  #### CLI
79
137
 
@@ -284,4 +342,4 @@ are in the [0.x changelog](changelog-0.x.md).
284
342
 
285
343
  ### Security
286
344
 
287
- - **`pnpm audit` is clean.** Six advisories are cleared, one of them critical (`proxy-addr`), with `source-map-js`, `fast-uri` and `sharp`. `image-size`, reached through `@seriousgaming/deck`'s PowerPoint export, is held to `>=2.0.3` by a new override (GHSA-5p2g-fcmc-qvqq, GHSA-w3rx-r6r6-pgpr). A scaffolded package carries the same override in its `pnpm-workspace.yaml`: copy that block into an existing package's file, then run `pnpm update -r` and `pnpm audit`
345
+ - **Six advisories are cleared**, one of them critical (`proxy-addr`), with `source-map-js`, `fast-uri` and `sharp`. `image-size`, reached through `@seriousgaming/deck`'s PowerPoint export, is held to `>=2.0.3` by a new override (GHSA-5p2g-fcmc-qvqq, GHSA-w3rx-r6r6-pgpr). A scaffolded package carries the same override in its `pnpm-workspace.yaml`: copy that block into an existing package's file, then run `pnpm update -r` and `pnpm audit`
@@ -1,5 +1,7 @@
1
1
  # The CLI and the dev server
2
2
 
3
+ The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal. This page explains how the two share one session, and what each is for.
4
+
3
5
  ## One session, two ways in
4
6
 
5
7
  The dev server owns the session. It holds the teams, the contexts, the roster