@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.
- package/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20161 -5495
- package/dist/client.js +15737 -1151
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +230 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +185 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +85 -4
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +98 -6
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +3 -10
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +32 -36
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +208 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +13 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +4 -4
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +74 -0
- package/dist/guide/video-registry.d.ts +33 -1
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +9 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11621 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +11 -1
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/dist/validation/schema-validation.d.ts +12 -4
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
package/dist/docs/api/sdk-ui.md
CHANGED
|
@@ -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,30 @@ 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
|
+
### useBrandIcon
|
|
88
|
+
|
|
89
|
+
The host's square mark for the mode the surface is painting in, falling back to the other variant when the host sent only one, as `useBrandLogo` does. Undefined when the brand has no icon.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
function useBrandIcon(): BrandIcon | undefined;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### useBrandLogo
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
function useBrandLogo(): BrandLogo | undefined;
|
|
101
|
+
```
|
|
102
|
+
|
|
60
103
|
### useMutationReporter
|
|
61
104
|
|
|
62
105
|
Runs a fallible mutation (`setData`, `requestTick`, and the rest) so that a failure reaches the participant instead of vanishing.
|
|
@@ -582,6 +625,14 @@ The React context behind `useSettingsEditorThemePreference`.
|
|
|
582
625
|
const SettingsEditorThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
|
|
583
626
|
```
|
|
584
627
|
|
|
628
|
+
### SurfaceThemeContext
|
|
629
|
+
|
|
630
|
+
The theme of whichever surface is rendering, for the hooks every surface shares. Provided by every wrapper; game code reads it through `useBrand`, `useBrandLogo` and `useBrandIcon`.
|
|
631
|
+
|
|
632
|
+
```ts
|
|
633
|
+
const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
|
|
634
|
+
```
|
|
635
|
+
|
|
585
636
|
### UserInterfaceCallbacksContext
|
|
586
637
|
|
|
587
638
|
The React context behind `useUserInterfaceCallbacks`.
|
|
@@ -737,6 +788,76 @@ interface AssetState<T> {
|
|
|
737
788
|
}
|
|
738
789
|
```
|
|
739
790
|
|
|
791
|
+
### Brand
|
|
792
|
+
|
|
793
|
+
The host's brand: what a white-label host dresses the game in.
|
|
794
|
+
|
|
795
|
+
```ts
|
|
796
|
+
interface Brand {
|
|
797
|
+
name: string;
|
|
798
|
+
logo?: {
|
|
799
|
+
onLight?: string;
|
|
800
|
+
onDark?: string;
|
|
801
|
+
};
|
|
802
|
+
icon?: {
|
|
803
|
+
onLight?: string;
|
|
804
|
+
onDark?: string;
|
|
805
|
+
};
|
|
806
|
+
fonts?: {
|
|
807
|
+
heading?: BrandFont;
|
|
808
|
+
body?: BrandFont;
|
|
809
|
+
};
|
|
810
|
+
}
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
### BrandFont
|
|
814
|
+
|
|
815
|
+
A font family the host's brand sets text in, and the files it is drawn from.
|
|
816
|
+
|
|
817
|
+
```ts
|
|
818
|
+
interface BrandFont {
|
|
819
|
+
family: string;
|
|
820
|
+
sources: BrandFontSource[];
|
|
821
|
+
}
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
### BrandFontSource
|
|
825
|
+
|
|
826
|
+
One file a brand font is drawn from.
|
|
827
|
+
|
|
828
|
+
```ts
|
|
829
|
+
interface BrandFontSource {
|
|
830
|
+
url: string;
|
|
831
|
+
weight?: string;
|
|
832
|
+
style?: string;
|
|
833
|
+
}
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
### BrandLogo
|
|
837
|
+
|
|
838
|
+
The logo `useBrandLogo` picked, and the background it was drawn for.
|
|
839
|
+
|
|
840
|
+
```ts
|
|
841
|
+
interface BrandLogo {
|
|
842
|
+
src: string;
|
|
843
|
+
alt: string;
|
|
844
|
+
drawnFor: 'light' | 'dark';
|
|
845
|
+
}
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
### CreateSurfaceThemeOptions
|
|
849
|
+
|
|
850
|
+
The game's own fonts, used wherever the host's brand names none.
|
|
851
|
+
|
|
852
|
+
```ts
|
|
853
|
+
interface CreateSurfaceThemeOptions {
|
|
854
|
+
fonts?: {
|
|
855
|
+
body?: string;
|
|
856
|
+
heading?: string;
|
|
857
|
+
};
|
|
858
|
+
}
|
|
859
|
+
```
|
|
860
|
+
|
|
740
861
|
### EndpointFailure
|
|
741
862
|
|
|
742
863
|
A failed endpoint call, itemised so a caller can tell 'nothing happened' from 'the writes landed, then an action failed'.
|
|
@@ -866,6 +987,46 @@ interface SessionUserInterfaceHookFailuresValue {
|
|
|
866
987
|
}
|
|
867
988
|
```
|
|
868
989
|
|
|
990
|
+
### SurfacePaletteColor
|
|
991
|
+
|
|
992
|
+
A palette colour as MUI takes it.
|
|
993
|
+
|
|
994
|
+
```ts
|
|
995
|
+
interface SurfacePaletteColor {
|
|
996
|
+
main: string;
|
|
997
|
+
contrastText: string;
|
|
998
|
+
}
|
|
999
|
+
```
|
|
1000
|
+
|
|
1001
|
+
### SurfaceThemeOptions
|
|
1002
|
+
|
|
1003
|
+
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.
|
|
1004
|
+
|
|
1005
|
+
```ts
|
|
1006
|
+
interface SurfaceThemeOptions {
|
|
1007
|
+
palette: Record<ThemeColorRole, SurfacePaletteColor> & {
|
|
1008
|
+
mode: 'light' | 'dark';
|
|
1009
|
+
background: {
|
|
1010
|
+
default: string;
|
|
1011
|
+
paper: string;
|
|
1012
|
+
};
|
|
1013
|
+
text: {
|
|
1014
|
+
primary: string;
|
|
1015
|
+
};
|
|
1016
|
+
};
|
|
1017
|
+
typography: {
|
|
1018
|
+
fontFamily: string;
|
|
1019
|
+
} & Partial<
|
|
1020
|
+
Record<
|
|
1021
|
+
(typeof HEADINGS)[number],
|
|
1022
|
+
{
|
|
1023
|
+
fontFamily: string;
|
|
1024
|
+
}
|
|
1025
|
+
>
|
|
1026
|
+
>;
|
|
1027
|
+
}
|
|
1028
|
+
```
|
|
1029
|
+
|
|
869
1030
|
### TeamInfo
|
|
870
1031
|
|
|
871
1032
|
Who a team is: the fields every team entry in the SDK carries.
|
|
@@ -947,6 +1108,14 @@ How `useAsset` reads the response body.
|
|
|
947
1108
|
type AssetFormat = 'json' | 'text' | 'blob';
|
|
948
1109
|
```
|
|
949
1110
|
|
|
1111
|
+
### BrandIcon
|
|
1112
|
+
|
|
1113
|
+
The icon `useBrandIcon` picked, and the background it was drawn for.
|
|
1114
|
+
|
|
1115
|
+
```ts
|
|
1116
|
+
type BrandIcon = BrandLogo;
|
|
1117
|
+
```
|
|
1118
|
+
|
|
950
1119
|
### ContextDeletePath
|
|
951
1120
|
|
|
952
1121
|
Where to remove a key, as a path from the root of the context.
|
|
@@ -1162,6 +1331,7 @@ type SessionUserInterfaceTheme = {
|
|
|
1162
1331
|
mode: 'dark' | 'light';
|
|
1163
1332
|
dark: SessionUserInterfaceModeColors;
|
|
1164
1333
|
light: SessionUserInterfaceModeColors;
|
|
1334
|
+
brand: Brand;
|
|
1165
1335
|
};
|
|
1166
1336
|
```
|
|
1167
1337
|
|
|
@@ -1196,6 +1366,7 @@ type SettingsEditorTheme = {
|
|
|
1196
1366
|
mode: 'dark' | 'light';
|
|
1197
1367
|
dark: SettingsEditorModeColors;
|
|
1198
1368
|
light: SettingsEditorModeColors;
|
|
1369
|
+
brand: Brand;
|
|
1199
1370
|
};
|
|
1200
1371
|
```
|
|
1201
1372
|
|
|
@@ -1220,6 +1391,19 @@ type SharedState<TSharedContext = Record<string, unknown>> = {
|
|
|
1220
1391
|
};
|
|
1221
1392
|
```
|
|
1222
1393
|
|
|
1394
|
+
### SurfaceTheme
|
|
1395
|
+
|
|
1396
|
+
What every surface's theme carries, whichever wrapper delivers it.
|
|
1397
|
+
|
|
1398
|
+
```ts
|
|
1399
|
+
type SurfaceTheme = {
|
|
1400
|
+
mode: 'dark' | 'light';
|
|
1401
|
+
dark: SurfaceModeColors;
|
|
1402
|
+
light: SurfaceModeColors;
|
|
1403
|
+
brand: Brand;
|
|
1404
|
+
};
|
|
1405
|
+
```
|
|
1406
|
+
|
|
1223
1407
|
### TeamConfiguration
|
|
1224
1408
|
|
|
1225
1409
|
How teams work in this session: the interaction mode, and the bounds the host will hold the surface to.
|
|
@@ -1299,6 +1483,7 @@ type UserInterfaceTheme = {
|
|
|
1299
1483
|
mode: 'dark' | 'light';
|
|
1300
1484
|
dark: UserInterfaceModeColors;
|
|
1301
1485
|
light: UserInterfaceModeColors;
|
|
1486
|
+
brand: Brand;
|
|
1302
1487
|
};
|
|
1303
1488
|
```
|
|
1304
1489
|
|
package/dist/docs/api/sdk.md
CHANGED
|
@@ -177,7 +177,7 @@ interface CapabilityDefinition {
|
|
|
177
177
|
|
|
178
178
|
### EndpointBaseArgs
|
|
179
179
|
|
|
180
|
-
The arguments every
|
|
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
|
-
|
|
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
|
package/dist/docs/changelog.md
CHANGED
|
@@ -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
|
|
11
|
-
`
|
|
12
|
-
`
|
|
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,83 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
27
31
|
|
|
28
32
|
## [Unreleased]
|
|
29
33
|
|
|
34
|
+
## [1.2.0] — 2026-10-25
|
|
35
|
+
|
|
36
|
+
### Breaking Changes
|
|
37
|
+
|
|
38
|
+
- **`Brand.icon` is `{ onLight?, onDark? }`, like `logo`**, because a host sends its light and dark modes together and could not pick one icon for your surface. Only a `Brand` built by hand with a string `icon`, in a test or a mock, stops compiling; no game we know of builds one. See [1.2: give `Brand.icon` a variant for each background](guides/upgrading.md#12-give-brandicon-a-variant-for-each-background). A host built for 1.1 still sends one URL, and the wrapper gives it to you as both variants. `createMockBrand()` now includes an icon for each background
|
|
39
|
+
|
|
40
|
+
### Added
|
|
41
|
+
|
|
42
|
+
- **`useBrandIcon()` gives the host's square icon for the mode your surface paints in**, falling back to the other variant as `useBrandLogo()` does. Use it where the logo will not fit. `examples/factory` shows it in place of the logo on a phone. A dev server `--brand` file may now give `icon` as `{ "onLight": …, "onDark": … }`, and a single file still serves for both
|
|
43
|
+
- **The build warns about a settings schema that leaves an object open**: one that lists `properties` without `"additionalProperties": false`. A key such an object does not declare is now refused anyway (see Fixed), and the warning asks the schema to say so
|
|
44
|
+
- **The build warns about a `:::` in a guide chapter that closes nothing**, which is what a `:::when` holding an admonition leaves behind when it has only three colons
|
|
45
|
+
- **A facilitator guide can play a video it ships.** Put an `.mp4` or `.webm` in `guide/assets/` and embed it with a `video` block of `provider: file`, giving its `src` and optionally a `title`, a `poster` image and WebVTT `captions`. It plays with controls and never autoplays, and a printed guide shows the poster or title in its place. The build fails on a file that is missing, outside `assets/` or of the wrong type, and warns about a video over 25 MB. `examples/factory`'s guide shows one. See [Video embeds](guides/guide.md#video-embeds)
|
|
46
|
+
- **`@seriousgaming/sdk-tools/host` exports `parseVideoBlock`**, with `guideAssetPath`, `VIDEO_PROVIDERS` and `FILE_VIDEO_EXTENSIONS`, so a platform renders a guide's video blocks by the dev server's rules
|
|
47
|
+
- **The `workflow-create-guide.md` rule describes `file` videos.** Merge it into your game's `.claude/rules/`
|
|
48
|
+
- **`CLAUDE.md.template` mentions `useBrandIcon()` and the host's print sheets** under 'Honour the host's brand'. Merge the line into your game's `CLAUDE.md`
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
|
|
52
|
+
- **The session UI guide recommends the host's print sheets.** Open `openHostOverlay('print-sheets')` where the host offers it, so the sheet carries the brand of whoever runs the session. Draw your own only where it does not, with `useBrandLogo()`
|
|
53
|
+
|
|
54
|
+
### Fixed
|
|
55
|
+
|
|
56
|
+
- **A misspelt settings key is refused, not silently ignored, when the schema leaves its object open.** `min` for `Min`, in a setup UI's write, a scenario draft edit, a scenario you save or `sdk configure`, used to be accepted and change nothing on an object without `"additionalProperties": false`. It is now refused with the key it meant suggested. A map (`additionalProperties` set to a schema or `true`) and an object built from `oneOf` or `anyOf` branches are unchanged
|
|
57
|
+
- **The guide docs no longer suggest wrapping a chapter with admonitions in a three-colon `:::when`.** The admonition's closing `:::` closed the condition too, so everything after it showed in every scenario. Use `::::when` … `::::`
|
|
58
|
+
|
|
59
|
+
## [1.1.0] — 2026-10-24
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- **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)
|
|
64
|
+
- **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)
|
|
65
|
+
- **`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
|
|
66
|
+
- **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
|
|
67
|
+
- **`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)
|
|
68
|
+
- **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
|
|
69
|
+
- **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)
|
|
70
|
+
- **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)
|
|
71
|
+
- **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`
|
|
72
|
+
- **`@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`
|
|
73
|
+
- **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
|
|
74
|
+
- **`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)
|
|
75
|
+
- **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
|
|
76
|
+
- **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
|
|
77
|
+
- **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
|
|
78
|
+
- **`@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
|
|
79
|
+
- **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
|
|
80
|
+
- **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
|
|
81
|
+
- **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
|
|
82
|
+
|
|
83
|
+
### Changed
|
|
84
|
+
|
|
85
|
+
- **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
|
|
86
|
+
- **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
|
|
87
|
+
- **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
|
|
88
|
+
- **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`
|
|
89
|
+
- **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
|
|
90
|
+
- **`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
|
|
91
|
+
- **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)
|
|
92
|
+
- **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
|
|
93
|
+
- **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
|
|
94
|
+
- **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
|
|
95
|
+
- **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
|
|
96
|
+
- **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
|
|
97
|
+
|
|
98
|
+
### Fixed
|
|
99
|
+
|
|
100
|
+
- **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
|
|
101
|
+
- **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
|
|
102
|
+
- **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`)
|
|
103
|
+
- **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
|
|
104
|
+
- **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/`
|
|
105
|
+
- **`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
|
|
106
|
+
|
|
107
|
+
### Security
|
|
108
|
+
|
|
109
|
+
- **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
|
|
110
|
+
|
|
30
111
|
## [1.0.0] — 2026-10-18
|
|
31
112
|
|
|
32
113
|
### Breaking Changes
|
|
@@ -65,7 +146,7 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
65
146
|
- **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)
|
|
66
147
|
- **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)
|
|
67
148
|
- **`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)
|
|
68
|
-
- **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-
|
|
149
|
+
- **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)
|
|
69
150
|
- **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)
|
|
70
151
|
|
|
71
152
|
#### Surfaces
|
|
@@ -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
|