@seriousgaming/sdk-tools 1.3.0 → 1.5.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/dist/cli.js +4055 -2646
- package/dist/client.js +807 -172
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-DEV8N0na.js → index-BVF8exas.js} +22 -22
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/public-origins.d.ts +61 -0
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/shell.d.ts +32 -4
- package/dist/dev/view/batch.d.ts +7 -1
- package/dist/docs/ai-agents.md +5 -0
- package/dist/docs/api/index.md +1 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk.md +79 -2
- package/dist/docs/changelog-0.x.md +2 -2
- package/dist/docs/changelog.md +62 -4
- package/dist/docs/cli-and-dev-server.md +58 -0
- package/dist/docs/cli-error-codes.md +39 -36
- package/dist/docs/cli-reference.md +68 -21
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/environment-variables.md +10 -5
- package/dist/docs/guides/ai-facilitation.md +2 -0
- package/dist/docs/guides/capabilities.md +4 -0
- package/dist/docs/guides/designing-a-game.md +2 -0
- package/dist/docs/guides/designing-screens.md +133 -0
- package/dist/docs/guides/endpoints.md +4 -2
- package/dist/docs/guides/engine-testing.md +6 -2
- package/dist/docs/guides/engine.md +2 -0
- package/dist/docs/guides/file-handling.md +116 -22
- package/dist/docs/guides/games.md +3 -1
- package/dist/docs/guides/global-settings.md +2 -0
- package/dist/docs/guides/guide.md +2 -0
- package/dist/docs/guides/hooks.md +2 -0
- package/dist/docs/guides/index.md +9 -0
- package/dist/docs/guides/internationalization.md +2 -0
- package/dist/docs/guides/llm-integration.md +5 -3
- package/dist/docs/guides/multi-team-games.md +3 -1
- package/dist/docs/guides/patterns.md +2 -0
- package/dist/docs/guides/presentation.md +1 -1
- package/dist/docs/guides/production-constraints.md +2 -0
- package/dist/docs/guides/scenario-editor.md +3 -1
- package/dist/docs/guides/scenarios.md +15 -3
- package/dist/docs/guides/session-game-flow.md +365 -0
- package/dist/docs/guides/session-hooks.md +205 -0
- package/dist/docs/guides/session.md +27 -565
- package/dist/docs/guides/settings.md +64 -2
- package/dist/docs/guides/setup.md +3 -1
- package/dist/docs/guides/speech-generation.md +2 -0
- package/dist/docs/guides/starter-game.md +61 -21
- package/dist/docs/guides/testing.md +2 -0
- package/dist/docs/guides/tick-controller.md +3 -1
- package/dist/docs/guides/type-safety.md +2 -0
- package/dist/docs/guides/ui-files-and-llms.md +328 -0
- package/dist/docs/guides/ui-participants.md +281 -0
- package/dist/docs/guides/ui-styling.md +263 -0
- package/dist/docs/guides/ui-ticks.md +247 -0
- package/dist/docs/guides/ui.md +11 -1092
- package/dist/docs/guides/upgrading.md +2 -0
- package/dist/docs/guides/validators.md +64 -4
- package/dist/docs/guides/waiting-room.md +1 -1
- package/dist/docs/index.md +2 -1
- package/dist/docs/page-index.md +145 -0
- package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/create-presentation.md +11 -0
- package/dist/docs/recipes/create-scenario-editor.md +1 -0
- package/dist/docs/recipes/create-session-ui.md +2 -1
- package/dist/docs/recipes/create-setup.md +1 -0
- package/dist/docs/recipes/create-user-interface.md +1 -0
- package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
- package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
- package/dist/docs/recipes/index.md +3 -0
- package/dist/docs/recipes/screenshot-a-surface.md +80 -0
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/use-request-tick.md +2 -2
- package/dist/docs/recipes/validate-scenarios.md +4 -1
- package/dist/execution/config-resolver.d.ts +4 -1
- package/dist/execution/endpoint-runner.d.ts +6 -0
- package/dist/execution/logic-calls.d.ts +7 -2
- package/dist/execution/scenario-gates.d.ts +21 -1
- package/dist/guide/settings.d.ts +1 -1
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +7 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- package/dist/templates/package/CLAUDE.md.template +14 -5
- package/dist/templates/package/DESIGN.md.liquid +39 -7
- package/dist/templates/package/README.md.liquid +1 -1
- package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
- package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
- package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
- package/dist/templates/starter-game/package.json +2 -0
- package/dist/templates/starter-game/presentation/defaults.ts +52 -0
- package/dist/templates/starter-game/presentation/index.html +20 -0
- package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
- package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
- package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
- package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
- package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
- package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
- package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
- package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
- package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
- package/dist/templates/starter-game/presentation/types.ts +94 -0
- package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
- package/dist/templates/starter-game/session/defaults.ts +6 -0
- package/dist/templates/starter-game/session/index.html +1 -1
- package/dist/templates/starter-game/session/session.sdk.json +2 -2
- package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
- package/dist/templates/starter-game/session/src/App.tsx +372 -222
- package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
- package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
- package/dist/templates/starter-game/session/src/Results.tsx +340 -0
- package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
- package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
- package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
- package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
- package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
- package/dist/templates/starter-game/session/src/i18n.ts +91 -24
- package/dist/templates/starter-game/session/src/status.ts +28 -0
- package/dist/templates/starter-game/session/types.ts +8 -2
- package/dist/templates/starter-game/shared/Awning.tsx +31 -0
- package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
- package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
- package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
- package/dist/templates/starter-game/shared/days.ts +11 -0
- package/dist/templates/starter-game/shared/format.test.ts +13 -0
- package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
- package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
- package/dist/templates/starter-game/ui/defaults.ts +3 -0
- package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
- package/dist/templates/starter-game/ui/src/App.tsx +176 -99
- package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
- package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
- package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
- package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
- package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
- package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
- package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
- package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
- package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
- package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
- package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
- package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
- package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
- package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
- package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
- package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
- package/dist/templates/starter-game/ui/src/days.ts +58 -0
- package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
- package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
- package/dist/templates/starter-game/ui/src/theme.ts +8 -8
- package/dist/templates/starter-game/ui/types.ts +6 -0
- package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
- package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
- package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
- package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
- package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
- package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
- package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
- package/dist/utils/error-codes.d.ts +12 -0
- package/dist/utils/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +11 -4
- package/dist/templates/starter-game/session/src/Section.tsx +0 -37
- package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
- package/dist/templates/starter-game/session/src/format.ts +0 -8
- package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
- package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
6
6
|
<link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
|
|
7
7
|
<title>Serious Gaming</title>
|
|
8
|
-
<script type="module" crossorigin src="/assets/index-
|
|
8
|
+
<script type="module" crossorigin src="/assets/index-BVF8exas.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The addresses a dev server behind a proxy is reached at (#788).
|
|
3
|
+
*
|
|
4
|
+
* The server otherwise names itself from the request: `http://`, the `Host`
|
|
5
|
+
* the browser sent, and the asset or hot-reload port in place of its own. A
|
|
6
|
+
* gateway that serves each origin on its own HTTPS hostname breaks every one
|
|
7
|
+
* of those guesses, so a server behind one is told its addresses instead.
|
|
8
|
+
*/
|
|
9
|
+
export declare const PUBLIC_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_URL";
|
|
10
|
+
export declare const PUBLIC_ASSET_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_ASSET_URL";
|
|
11
|
+
export declare const PUBLIC_HMR_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_HMR_URL";
|
|
12
|
+
/** The origins as given, each already parsed by {@link parsePublicOrigin}. */
|
|
13
|
+
export interface PublicOrigins {
|
|
14
|
+
/** The console, its API and every link a participant is handed. */
|
|
15
|
+
publicUrl?: string;
|
|
16
|
+
/** Game bundles and the files a frame reads. */
|
|
17
|
+
publicAssetUrl?: string;
|
|
18
|
+
/** Vite's hot-reload socket, as `ws:` or `wss:`. */
|
|
19
|
+
publicHmrUrl?: string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* An origin from a flag or an environment variable, normalised.
|
|
23
|
+
*
|
|
24
|
+
* Only an origin: a path would suggest the server can be mounted under one,
|
|
25
|
+
* and it cannot, since every route it serves is absolute.
|
|
26
|
+
*
|
|
27
|
+
* @throws {CliError} when the value is not an origin of the kind `flag` takes.
|
|
28
|
+
*/
|
|
29
|
+
export declare function parsePublicOrigin(value: string, flag: string, kind: 'http' | 'ws'): string;
|
|
30
|
+
/**
|
|
31
|
+
* The public origins for `sdk dev`: each flag, else its environment variable,
|
|
32
|
+
* parsed. Unset where neither gives one.
|
|
33
|
+
*
|
|
34
|
+
* @throws {CliError} when a value is not an origin.
|
|
35
|
+
*/
|
|
36
|
+
export declare function resolvePublicOrigins(flags: {
|
|
37
|
+
publicUrl?: string;
|
|
38
|
+
publicAssetUrl?: string;
|
|
39
|
+
publicHmrUrl?: string;
|
|
40
|
+
}, env?: NodeJS.ProcessEnv): PublicOrigins;
|
|
41
|
+
/**
|
|
42
|
+
* The asset origin: as given, else the public console's scheme and host on
|
|
43
|
+
* the asset port, which is what a proxy forwarding each port as it is serves.
|
|
44
|
+
* Null when neither is given, so the server goes on naming it from the request.
|
|
45
|
+
*/
|
|
46
|
+
export declare function publicAssetOrigin(origins: PublicOrigins, assetPort: number): string | null;
|
|
47
|
+
/**
|
|
48
|
+
* Where a frame's hot-reload client connects: as given, else the asset
|
|
49
|
+
* origin's host on the Vite port, over `wss:` when the asset origin is HTTPS.
|
|
50
|
+
* That default is where Vite's client connects when told nothing, so it
|
|
51
|
+
* changes only the scheme and the name. Null when no public origin is given.
|
|
52
|
+
*/
|
|
53
|
+
export declare function publicHmrOrigin(origins: PublicOrigins, assetPort: number, vitePort: number): string | null;
|
|
54
|
+
/** What Vite's client is told to connect to, from a `ws:` or `wss:` origin. */
|
|
55
|
+
export declare function hmrClientTarget(origin: string): {
|
|
56
|
+
protocol: 'ws' | 'wss';
|
|
57
|
+
host: string;
|
|
58
|
+
clientPort: number;
|
|
59
|
+
};
|
|
60
|
+
/** The hostnames a public origin names, which Vite must accept in a `Host` header. */
|
|
61
|
+
export declare function publicHostnames(origins: (string | null | undefined)[]): string[];
|
package/dist/dev/routes.d.ts
CHANGED
|
@@ -48,12 +48,16 @@ declare const ASSET_PATHS: {
|
|
|
48
48
|
readonly '/api': {
|
|
49
49
|
readonly blob: "/api/blobs/:blobId";
|
|
50
50
|
readonly scenario: "/api/scenario/assets/*path";
|
|
51
|
+
readonly editedScenario: "/api/scenarios/:scenario/assets/*path";
|
|
52
|
+
readonly noScenario: "/api/no-scenario/assets/*path";
|
|
51
53
|
readonly shared: "/api/shared/assets/*path";
|
|
52
54
|
readonly redeem: "/api/asset-auth/redeem";
|
|
53
55
|
};
|
|
54
56
|
readonly '/assets': {
|
|
55
57
|
readonly blob: "/assets/blobs/:blobId";
|
|
56
58
|
readonly scenario: "/assets/scenario/*path";
|
|
59
|
+
readonly editedScenario: "/assets/scenarios/:scenario/*path";
|
|
60
|
+
readonly noScenario: "/assets/no-scenario/*path";
|
|
57
61
|
readonly shared: "/assets/shared/*path";
|
|
58
62
|
readonly redeem: "/assets/auth/redeem";
|
|
59
63
|
};
|
package/dist/dev/shell.d.ts
CHANGED
|
@@ -18,7 +18,14 @@ import type { RunKind } from '@seriousgaming/sdk';
|
|
|
18
18
|
import type { MutationResult } from '@seriousgaming/sdk/projection';
|
|
19
19
|
import type { Command } from '../core/protocol';
|
|
20
20
|
import { Session, type SessionOptions } from '../core/session';
|
|
21
|
-
|
|
21
|
+
import { type PublicOrigins } from './public-origins';
|
|
22
|
+
/**
|
|
23
|
+
* `publicUrl`, `publicAssetUrl` and `publicHmrUrl` are the addresses a server
|
|
24
|
+
* behind a proxy is reached at (#788), each an origin as
|
|
25
|
+
* `parsePublicOrigin` leaves it. Unset, every address is named from the
|
|
26
|
+
* request that asked for it.
|
|
27
|
+
*/
|
|
28
|
+
export interface ShellOptions extends SessionOptions, PublicOrigins {
|
|
22
29
|
port?: number;
|
|
23
30
|
/** Port the Vite HMR socket binds to. Defaults to `port + 1`. */
|
|
24
31
|
vitePort?: number;
|
|
@@ -108,6 +115,8 @@ export declare class DevShell {
|
|
|
108
115
|
private viteFailure;
|
|
109
116
|
/** Serialises the first requests for a surface so they share one Vite. */
|
|
110
117
|
private viteStarting;
|
|
118
|
+
/** The hot-reload socket's own listener, when a public origin moves its client. */
|
|
119
|
+
private hmrServer;
|
|
111
120
|
private port;
|
|
112
121
|
private vitePort;
|
|
113
122
|
private assetPort;
|
|
@@ -171,14 +180,23 @@ export declare class DevShell {
|
|
|
171
180
|
get url(): string;
|
|
172
181
|
/** Where bundles are served from, once listening. */
|
|
173
182
|
get assetUrl(): string;
|
|
183
|
+
/** Where people reach the console, when a proxy stands in front of it. */
|
|
184
|
+
get publicUrl(): string | null;
|
|
185
|
+
/** Where people's browsers load bundles from, when a proxy stands in front. */
|
|
186
|
+
get publicAssetUrl(): string | null;
|
|
174
187
|
/**
|
|
175
|
-
* The asset origin as a client that reached `host` must name it: the
|
|
176
|
-
*
|
|
177
|
-
* address `localhost` would not
|
|
188
|
+
* The asset origin as a client that reached `host` must name it: the
|
|
189
|
+
* public one where given, else the same host on the asset port. A browser
|
|
190
|
+
* on another machine reached us by an address `localhost` would not
|
|
191
|
+
* resolve to on its side.
|
|
178
192
|
*/
|
|
179
193
|
assetOrigin(host: string | undefined): string;
|
|
180
194
|
/** The console's own origin, as a client that reached `host` names it. */
|
|
181
195
|
private consoleOrigin;
|
|
196
|
+
/** Where a frame's hot-reload client connects, when a public origin decides it. */
|
|
197
|
+
private get publicHmrUrl();
|
|
198
|
+
/** What the bundle policy's `connect-src` admits for hot reload. */
|
|
199
|
+
private hmrSources;
|
|
182
200
|
/** The session this shell wraps, for tests and for the CLI in-process path. */
|
|
183
201
|
get runtime(): Session;
|
|
184
202
|
/**
|
|
@@ -222,6 +240,16 @@ export declare class DevShell {
|
|
|
222
240
|
*/
|
|
223
241
|
private ensureVite;
|
|
224
242
|
private createVite;
|
|
243
|
+
/**
|
|
244
|
+
* Vite's server options: its own hot-reload socket on the Vite port, as
|
|
245
|
+
* before, unless a public origin says where the client connects.
|
|
246
|
+
*
|
|
247
|
+
* Vite takes one `host` for both where its socket listens and where its
|
|
248
|
+
* client connects, and a public hostname is no address to listen on. So
|
|
249
|
+
* behind a proxy the socket's listener is opened here, on the Vite port
|
|
250
|
+
* as usual, and Vite only attaches to it.
|
|
251
|
+
*/
|
|
252
|
+
private viteServerOptions;
|
|
225
253
|
private attachSockets;
|
|
226
254
|
private receive;
|
|
227
255
|
/** What one viewer page is owed, now. */
|
package/dist/dev/view/batch.d.ts
CHANGED
|
@@ -114,8 +114,14 @@ export declare function themeMessages(theme: Theme): HostMessage[];
|
|
|
114
114
|
*
|
|
115
115
|
* On the asset origin, beside the bundles, so a frame reads them as its own
|
|
116
116
|
* origin under `connect-src 'self'` and never needs the console's.
|
|
117
|
+
*
|
|
118
|
+
* `asset:` resolves against the session's scenario, except in the scenario
|
|
119
|
+
* editor, which reads the files of the scenario it is open on whatever the
|
|
120
|
+
* session runs (§6.5), and none when it is open on no scenario (§6.7).
|
|
117
121
|
*/
|
|
118
|
-
export declare function assetUrls(assetOrigin: string
|
|
122
|
+
export declare function assetUrls(assetOrigin: string, editing?: {
|
|
123
|
+
scenario: string | null;
|
|
124
|
+
}): Record<string, string>;
|
|
119
125
|
/**
|
|
120
126
|
* The whole initial batch for one surface.
|
|
121
127
|
*
|
package/dist/docs/ai-agents.md
CHANGED
|
@@ -14,10 +14,15 @@ The site describes the newest release. Inside a package, read the docs that ship
|
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
pnpm run --silent sdk docs view # the documentation tree
|
|
17
|
+
pnpm run --silent sdk docs view page-index.md # every page: summary and length
|
|
17
18
|
pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
|
|
19
|
+
pnpm run --silent sdk docs view guides/ui.md --outline # the headings of a page, with section lengths
|
|
20
|
+
pnpm run --silent sdk docs view guides/ui.md --section 'Writing to context' # one section
|
|
18
21
|
pnpm run sdk docs export # copy every page into the package, to search with grep
|
|
19
22
|
```
|
|
20
23
|
|
|
24
|
+
Some guides run past 50,000 characters. Rather than reading one whole, find it in the [page index](./page-index.md), list its headings with `--outline`, and read the section you need with `--section`, which takes a heading's text or the slug the outline prints. Every guide and recipe carries a `**Keywords:**` line, so `grep -rn` over the docs lands on the right page.
|
|
25
|
+
|
|
21
26
|
On the site, [llms.txt](https://sdk.seriousgaming.com/llms.txt) lists every page, [llms-small.txt](https://sdk.seriousgaming.com/llms-small.txt) holds the core pages in one file, and [llms-full.txt](https://sdk.seriousgaming.com/llms-full.txt) holds them all. Start from a recipe for a task and from a guide for a whole subject.
|
|
22
27
|
|
|
23
28
|
## 1. Scaffold without a prompt
|
package/dist/docs/api/index.md
CHANGED
|
@@ -6,7 +6,7 @@ Every type, function, hook and component your game imports, one page per entry p
|
|
|
6
6
|
|
|
7
7
|
| Entry point | Exports |
|
|
8
8
|
| ---------------------------------------------------------- | -------------------------------------------------------------- |
|
|
9
|
-
| [`@seriousgaming/sdk`](./sdk.md) |
|
|
9
|
+
| [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
|
|
10
10
|
| [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
|
|
11
11
|
| [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
|
|
12
12
|
| [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
|
|
@@ -129,6 +129,7 @@ Every callback a runtime may offer logic: the engine, hooks, tick controllers an
|
|
|
129
129
|
interface SignatureCallbacks {
|
|
130
130
|
generateText: LLMGenerateFunction;
|
|
131
131
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
132
|
+
describeAsset?: (reference: string) => Promise<AssetDescription | undefined>;
|
|
132
133
|
getPastState: <T = Record<string, unknown>>(
|
|
133
134
|
query: PastStateQuery<T>
|
|
134
135
|
) => Promise<PastStateEntry<T>[]>;
|
package/dist/docs/api/sdk.md
CHANGED
|
@@ -86,6 +86,14 @@ function nextWeeklyAt(
|
|
|
86
86
|
): number;
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
+
### parseSettingPath
|
|
90
|
+
|
|
91
|
+
Read a setting path back into its settings identifier and keys, or `undefined` when it is not a setting path. The inverse of `settingPath`: `parseSettingPath('ui.Cast["a.b"].portrait')` is `{ identifier: 'ui', keys: ['Cast', 'a.b', 'portrait'] }`. A plain key written in brackets, `ui["MinPrice"]`, reads as the same key.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
function parseSettingPath(path: string): ParsedSettingPath | undefined;
|
|
95
|
+
```
|
|
96
|
+
|
|
89
97
|
### scheduledTick
|
|
90
98
|
|
|
91
99
|
Convenience builder that creates a `TickControllerResult` for scheduled (absolute-time) ticking.
|
|
@@ -107,6 +115,14 @@ A seeded pseudo-random generator: call it for the next value in `[0, 1)`, like `
|
|
|
107
115
|
function seededRandom(seed: string): () => number;
|
|
108
116
|
```
|
|
109
117
|
|
|
118
|
+
### settingPath
|
|
119
|
+
|
|
120
|
+
The path naming a setting: its settings identifier, then each key below it.
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
function settingPath(identifier: string, ...keys: (string | number)[]): string;
|
|
124
|
+
```
|
|
125
|
+
|
|
110
126
|
## Classes
|
|
111
127
|
|
|
112
128
|
### EndpointError
|
|
@@ -124,6 +140,19 @@ class EndpointError extends Error {
|
|
|
124
140
|
}
|
|
125
141
|
```
|
|
126
142
|
|
|
143
|
+
### ScenarioAssetTooLargeError
|
|
144
|
+
|
|
145
|
+
Error a `Scenario` gate's `readAsset` rejects with for a file larger than `SCENARIO_GATE_READ_LIMIT_BYTES`. A gate that lets it escape counts as having thrown, so the build fails, or the save is refused, naming the file. To check a large file's presence or size, call `describeAsset`.
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
class ScenarioAssetTooLargeError extends Error {
|
|
149
|
+
readonly reference: string;
|
|
150
|
+
readonly size: number;
|
|
151
|
+
readonly limit: number;
|
|
152
|
+
constructor(reference: string, size: number);
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
127
156
|
### UndeclaredApiUseError
|
|
128
157
|
|
|
129
158
|
Error thrown when a resource invokes a callback it did not declare in its bundle's `uses` array. Carries the offending resource identifier and the callback name so a runtime can surface both to the operator.
|
|
@@ -136,6 +165,16 @@ class UndeclaredApiUseError extends Error {
|
|
|
136
165
|
}
|
|
137
166
|
```
|
|
138
167
|
|
|
168
|
+
## Constants
|
|
169
|
+
|
|
170
|
+
### SCENARIO_GATE_READ_LIMIT_BYTES
|
|
171
|
+
|
|
172
|
+
The largest file, in bytes, a `Scenario` gate's `readAsset` reads: 10 MB (10,485,760 bytes), the same in every runtime, so a gate gives the same answer at build and on save. A read of a larger file rejects with `ScenarioAssetTooLargeError` before any of it is read.
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
const SCENARIO_GATE_READ_LIMIT_BYTES: number;
|
|
176
|
+
```
|
|
177
|
+
|
|
139
178
|
## Interfaces
|
|
140
179
|
|
|
141
180
|
### AggregateFunctionShared
|
|
@@ -160,6 +199,17 @@ interface AggregateFunctionTeam<TTeamContext, TTeamState = never> {
|
|
|
160
199
|
}
|
|
161
200
|
```
|
|
162
201
|
|
|
202
|
+
### AssetDescription
|
|
203
|
+
|
|
204
|
+
Shape returned by `describeAsset`: what a file is, without its bytes.
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
interface AssetDescription {
|
|
208
|
+
mimeType: string;
|
|
209
|
+
size: number;
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
163
213
|
### CapabilityDefinition
|
|
164
214
|
|
|
165
215
|
Definition of a capability
|
|
@@ -726,6 +776,17 @@ interface PackageManifest {
|
|
|
726
776
|
}
|
|
727
777
|
```
|
|
728
778
|
|
|
779
|
+
### ParsedSettingPath
|
|
780
|
+
|
|
781
|
+
A setting path read back into the keys `settingPath` wrote it from.
|
|
782
|
+
|
|
783
|
+
```ts
|
|
784
|
+
interface ParsedSettingPath {
|
|
785
|
+
identifier: string;
|
|
786
|
+
keys: string[];
|
|
787
|
+
}
|
|
788
|
+
```
|
|
789
|
+
|
|
729
790
|
### Participant
|
|
730
791
|
|
|
731
792
|
A participant the platform tracks for some team in the session.
|
|
@@ -909,6 +970,17 @@ interface RunResult<TContext, TState = never> extends EngineResult<TContext, TSt
|
|
|
909
970
|
}
|
|
910
971
|
```
|
|
911
972
|
|
|
973
|
+
### ScenarioCallbacks
|
|
974
|
+
|
|
975
|
+
What a `Scenario` gate may call: the two file reads, and nothing else. No text generation and no `extractText`, so the gate stays deterministic.
|
|
976
|
+
|
|
977
|
+
```ts
|
|
978
|
+
interface ScenarioCallbacks {
|
|
979
|
+
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
980
|
+
describeAsset: (reference: string) => Promise<AssetDescription | undefined>;
|
|
981
|
+
}
|
|
982
|
+
```
|
|
983
|
+
|
|
912
984
|
### ScenarioDefinition
|
|
913
985
|
|
|
914
986
|
Definition of a scenario — a named flavour of a game bundling settings overrides and static assets
|
|
@@ -970,12 +1042,13 @@ Arguments of a validator's `Scenario` gate.
|
|
|
970
1042
|
interface ScenarioFunctionArgs<TSettings> {
|
|
971
1043
|
settings: TSettings;
|
|
972
1044
|
locale: string;
|
|
1045
|
+
callbacks?: ScenarioCallbacks;
|
|
973
1046
|
}
|
|
974
1047
|
```
|
|
975
1048
|
|
|
976
1049
|
### ScenarioProblem
|
|
977
1050
|
|
|
978
|
-
One thing wrong with a scenario. `path` names the setting it is about,
|
|
1051
|
+
One thing wrong with a scenario. `path` names the setting it is about as a setting path, from the settings identifier (`ui.MinPrice`), so an editor can show the problem beside the field. Build it with `settingPath`, which writes a key that is not a plain name in brackets (`ui.Cast["a.b"].portrait`).
|
|
979
1052
|
|
|
980
1053
|
```ts
|
|
981
1054
|
interface ScenarioProblem {
|
|
@@ -1364,6 +1437,7 @@ Every callback a runtime may offer logic: the engine, hooks, tick controllers an
|
|
|
1364
1437
|
interface SignatureCallbacks {
|
|
1365
1438
|
generateText: LLMGenerateFunction;
|
|
1366
1439
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
1440
|
+
describeAsset?: (reference: string) => Promise<AssetDescription | undefined>;
|
|
1367
1441
|
getPastState: <T = Record<string, unknown>>(
|
|
1368
1442
|
query: PastStateQuery<T>
|
|
1369
1443
|
) => Promise<PastStateEntry<T>[]>;
|
|
@@ -2144,7 +2218,10 @@ type ThemePreference = 'light' | 'dark' | 'system';
|
|
|
2144
2218
|
The `SignatureCallbacks` members that `uses` does not gate.
|
|
2145
2219
|
|
|
2146
2220
|
```ts
|
|
2147
|
-
type UngatedSignatureCallbacks = Pick<
|
|
2221
|
+
type UngatedSignatureCallbacks = Pick<
|
|
2222
|
+
SignatureCallbacks,
|
|
2223
|
+
'readAsset' | 'describeAsset' | 'getPastState'
|
|
2224
|
+
>;
|
|
2148
2225
|
```
|
|
2149
2226
|
|
|
2150
2227
|
### ValidationResult
|
|
@@ -563,8 +563,8 @@ Work through step 5 of the upgrade guide: it gives the five in order, with the e
|
|
|
563
563
|
### Added
|
|
564
564
|
|
|
565
565
|
- A scenario can configure the session user interface, through a `sessionUserInterfaces` bucket in its `configuration` alongside `modules` and `userInterfaces`. The surface's configuration now resolves through all four layers like any other resource: schema defaults, the game's `sessionUserInterface` reference, the active scenario, then the centralized layer. Session UIs get their own bucket rather than sharing `userInterfaces`, so a player UI and a session UI may carry the same identifier without crossing. See the [session UI guide](guides/session.md#configuring-the-surface)
|
|
566
|
-
- A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session.md#opening-host-overlays)
|
|
567
|
-
- `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session.md#extending-a-tick)
|
|
566
|
+
- A session user interface can open the host's own overlays with `openHostOverlay()`, so a facilitator does not have to leave the surface to reach the facilitator guide or a team's print sheet. The host still renders them, in its chrome above the surface, and reports which ones it offers through `useSessionUserInterfaceHostOverlays()`. Render a control only for an overlay in that list: a production host and the dev server do not offer the same set. See the [session UI guide](guides/session-game-flow.md#opening-host-overlays)
|
|
567
|
+
- `extendTick(seconds)` moves the deadline of the currently scheduled tick from a session user interface, so 'give them two more minutes' no longer means pausing the timer and remembering to resume it. It moves that one window: the interval your tick controller returns for later ticks is untouched, a negative value pulls the deadline in, and the adjustment reads back as `extendedMs` on the team's timer. See the [session UI guide](guides/session-game-flow.md#extending-a-tick)
|
|
568
568
|
- The dev server serves team print sheets at `/print-sheets`, one card per team with its join and observe URLs behind a print stylesheet. Print every team from the session menu, or one team from its card's own menu; a session UI reaches both through `openHostOverlay('print-sheets', teamId?)`. The sheets carry no QR code and no PIN, because the dev server has neither; a production host prints both
|
|
569
569
|
- A game can start its sessions with the waiting room already open, by setting `"openOnStart": true` on its `waitingRoom` reference. Without it the room is closed at the start, so the first player to follow a join link lands in the game rather than the holding screen unless the facilitator opened the room first. It seeds the session and nothing more: the facilitator owns the flag from then on, a reset does not re-park the session, and a dev server restart restores the flag the session was left with. Available to a game that authors its own waiting room UI. See the [waiting room guide](guides/waiting-room.md#starting-held)
|
|
570
570
|
- `new`, `update` and `delete` accept `-j, --json`, matching every other command in the CLI. The envelope names the command, the resource type, the identifier, and every file, reference and directory the operation touched; a failure reports the same shape with `"success": false` and an `error`, and exits non-zero. Because prompts cannot produce JSON, `new` and `update` need a definition or a `--patch` under the flag, and `delete` needs `--force`. See the [CLI reference](cli-reference.md#json-output)
|
package/dist/docs/changelog.md
CHANGED
|
@@ -31,13 +31,71 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
31
31
|
|
|
32
32
|
## [Unreleased]
|
|
33
33
|
|
|
34
|
+
## [1.5.0] — 2026-10-29
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`sdk dev` can run behind a proxy or gateway.** `--public-url`, `--public-asset-url` and `--public-hmr-url` (or `SERIOUSGAMING_DEV_PUBLIC_URL`, `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` and `SERIOUSGAMING_DEV_PUBLIC_HMR_URL`) name the addresses people reach it at, and every link and origin the server hands out uses them, where join links used to read `http://localhost:<port>`. With none set, nothing changes. See [Embedding the dev server](cli-and-dev-server.md#embedding-the-dev-server)
|
|
39
|
+
- **A page framing the dev console can set its colour scheme and brand.** Open it with `?scheme=light|dark|system` or `?brand=<id>`, or post `{ type: 'sg-dev-scheme', scheme }` to the frame to change the scheme without a reload. Neither overwrites the viewer's own stored choice, and the scheme reaches the game's surfaces as the dev drawer's does
|
|
40
|
+
- **The starter game has a presentation.** `new package` now writes Lemonade Stand with a `presentation/` slot: a title slide, a slide for each day with the forecast and how the room did the day before, and a results slide for the room. It shows the room rather than any stall by name, with each stall's figures in the speaker notes, renders with no session, and tests its figures as plain functions. See [A tour of the starter game](guides/starter-game.md#presentation)
|
|
41
|
+
- **A guide to designing screens.** [Designing screens](guides/designing-screens.md) sets out what a good simulation screen looks like whatever the brand: one main action, a spacing and type scale, a design for the phone, laptop or projector it is used on, every state from empty to end of game, feedback on a refused write, accessibility, and an identity of the game's own over the host's theme. New packages put it to work: `DESIGN.md.liquid` replaces the 'User interfaces' prompts with a screen brief (who plays and on what, tone, key screens and each one's main action, layout, states and identity), and `CLAUDE.md.template` asks for the brief before a surface is built and a check at phone and desktop size after. An existing package can copy both sections from the templates shipped in `@seriousgaming/sdk-tools`
|
|
42
|
+
- **Read a long page a section at a time.** `pnpm run sdk docs view <page> --outline` lists a page's headings, each with its slug and its section's length in characters, and `--section <heading>` prints only that section, named by its text or its slug. Both work with `--json`, and an unknown section fails with `DOCS_SECTION_NOT_FOUND`, listing the ones the page has. The installed docs gain `page-index.md`, every page with a one-sentence summary and its length, and every guide now carries a `**Keywords:**` line for `grep`. A new package's `CLAUDE.md` (`CLAUDE.md.template`) points to all three; merge its Documentation section into an existing package's. See [Read the docs for the installed version](ai-agents.md#read-the-docs-for-the-installed-version)
|
|
43
|
+
- **`pnpm run sdk screenshot <path>` captures a surface as a PNG**, as a participant sees it, once the surface reports its first paint rather than after a fixed delay. `--width` and `--height` set the viewport, `--scheme`, `--brand` and `--locale` what it shows, and `--full-page` its whole height; `--json` also lists the page's console errors, failed requests and uncaught exceptions, from inside the surface's frame too. It uses the running dev server, or starts one for the capture and stops it after. It drives the game's own Playwright, an optional peer of `@seriousgaming/sdk-tools` that every scaffolded game already has: without it, or without its Chromium, it fails with `BROWSER_MISSING`, and a surface that never renders fails with `SURFACE_NOT_RENDERED`. The starter's `CLAUDE.md.template` now tells agents to screenshot each screen at phone and desktop size. See [Screenshot a surface](recipes/screenshot-a-surface.md)
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- **A new game installs under a seven-day release-age policy.** `pnpm run sdk new package` writes `minimumReleaseAge: 10080` into the game's `pnpm-workspace.yaml`, the policy the SDK itself builds under, so pnpm refuses any dependency published in the last week and picks the newest older release in its range instead. The SDK's own packages (`@seriousgaming/*`) are exempt, so a game scaffolded on the day of an SDK release still installs. An existing game is unchanged: to opt in, copy `minimumReleaseAge` and `minimumReleaseAgeExclude`, with their comment, from the scaffold template `templates/package/pnpm-workspace.yaml.template` in the installed `@seriousgaming/sdk-tools` into your `pnpm-workspace.yaml`
|
|
48
|
+
- **A game with a default scenario always runs on a scenario.** Asking for none, with `pnpm run sdk scenario none`, `createTestSession({ scenarioId: null })` or a hosted runtime's equivalent, is refused with an error naming the default, where it used to run the game on its settings defaults alone, and the dev drawer's **Scenario** tab offers **None** only to a game with no default. If an engine test passes `scenarioId: null` to a game with a default, pin one of its scenarios instead. A game with no default runs on none as before. See [Scenarios](guides/scenarios.md)
|
|
49
|
+
- **The user interface and session UI guides are split into topic pages.** [Building user interfaces](guides/ui.md) and [Building session UIs](guides/session.md) keep their paths as entry pages that link to the rest: participants, ticks and the timer, styling, and files and LLMs for a game UI; running the game and the hooks reference for a session UI. A link to a section that moved needs its new page. The `docs view --section` examples in `CLAUDE.md.template` and the hook pointer in `workflow-create-user-interface.md` follow the new pages
|
|
50
|
+
|
|
51
|
+
- **The starter game's screens are redesigned to the [Designing screens](guides/designing-screens.md) guide.** A game made with `new package` now:
|
|
52
|
+
- Leads each participant screen with the day's decision, with the button that opens the stall in a bar at the foot of the layout and a timeline for looking back at earlier days
|
|
53
|
+
- Gives the facilitator one line of session controls, a card per stall, a side panel with no backdrop for managing one, results for the room, and join links in large type for the room to read
|
|
54
|
+
- Lets the facilitator hold the room at a day: a shared `pacing` capability, enforced by a `RequestTick` gate in `validators/daylimit`
|
|
55
|
+
- Takes its icons from `@mui/icons-material`, keeps its one drawn motif (the awning) and the host's logo in a new `shared/` folder, and lists `presentation-overlay` in `requires`, so the facilitator can open the slides from their screen
|
|
56
|
+
|
|
57
|
+
An existing game is unchanged. See [A tour of the starter game](guides/starter-game.md)
|
|
58
|
+
|
|
59
|
+
### Fixed
|
|
60
|
+
|
|
61
|
+
- **The starter game's facilitator screen shows the purse in pounds.** Lemonade Stand holds money in pence, and its session screen showed a purse of 2,200 pence as '£2,200' where the player's screen showed '£22.00'. A game made from an earlier starter can copy `money` from `ui/src/format.ts` into `session/src/format.ts`; the new starter keeps one copy, in `shared/format.ts`
|
|
62
|
+
|
|
63
|
+
### Security
|
|
64
|
+
|
|
65
|
+
- **The `fast-uri` advisories are cleared.** The SDK's lockfile now takes `fast-uri` 3.1.9 through `ajv`. `body-parser` 2.4.0, through `express` in the dev server, clears the seven-day gate later on 29 October and is taken by the next release; a game's own install already resolves it once it is old enough
|
|
66
|
+
|
|
67
|
+
## [1.4.0] — 2026-10-26
|
|
68
|
+
|
|
69
|
+
### Added
|
|
70
|
+
|
|
71
|
+
- **`describeAsset(reference)` tells logic a file's type and size without reading it**, or `undefined` when there is no such file, so checking that a scenario's videos exist no longer reads each one whole. It resolves references exactly as `readAsset` does and needs no `uses` entry. It is optional in `SignatureCallbacks`, so call it with `?.`, and a test that builds its callbacks by hand still compiles; `createStubCallbacks` describes the blobs it wrote. `examples/factory`'s `attachresearch` endpoint answers with the size of the document it attached. See [Checking a file without reading it](guides/file-handling.md#checking-a-file-without-reading-it)
|
|
72
|
+
- **A `Scenario` gate can check the files a scenario names.** List `scenario-files` in `requires`, and the gate receives `callbacks` with `readAsset` and `describeAsset`, resolved against the scenario being judged: its own files at build, a draft's on save. So a scenario naming a missing portrait is refused when it is saved, rather than the rule living again in an endpoint and a test. Without the feature, a call throws, naming it. A gate's `readAsset` reads no file over 10 MB (`SCENARIO_GATE_READ_LIMIT_BYTES`), the same in every runtime: a larger one rejects with a `ScenarioAssetTooLargeError`, which refuses the scenario naming the file, so check a video with `describeAsset`. Once you list it, your generated `ScenarioFunction` requires `callbacks`, so a test calling the gate passes them. `examples/factory`'s `scenariocheck` refuses a branding logo the scenario does not have. See [Checking the files a scenario names](guides/validators.md#checking-the-files-a-scenario-names)
|
|
73
|
+
- **Settings and capability schemas can reuse a shape, and nest it to any depth.** Declare it under `$defs` (or `definitions`) and use it with a local `$ref`, from inside itself included, so recursive data such as a rule whose branches are rules is checked at every level. `pnpm run sdk generate` used to fail on any `$ref` with `MissingPointerError`; it now emits one type per shape, so `"$ref": "#/$defs/rule"` is typed `Rule`, and a shape containing itself is an interface naming itself. The build refuses a `$ref` that names nothing or reaches outside its own schema, and scenarios, setup writes, scenario drafts, file settings and guide conditions all follow it. See [Reuse a shape, or nest it to any depth](guides/settings.md#reuse-a-shape-or-nest-it-to-any-depth). A schema is still JSON Schema Draft 7, read the same way whatever `$schema` it names; `$defs` and keywords beside a `$ref` are the two later-draft features it takes
|
|
74
|
+
|
|
75
|
+
- **`settingPath` and `parseSettingPath` build and read a setting path.** Use `settingPath('ui', 'Cast', key)` for a `Scenario` gate's problem `path` rather than joining keys with dots, so an editor reads back a map entry whose key holds a dot. See [How a setting is named](./guides/settings.md#how-a-setting-is-named)
|
|
76
|
+
|
|
77
|
+
### Changed
|
|
78
|
+
|
|
79
|
+
- **A package file's media type comes from one table.** The dev server serves a scenario or shared file, and `readAsset` reports it, under the type its extension names in the same table the build checks a file setting's `accept` against, so a file is served as the type it was accepted as. The table now also covers Office and OpenDocument files (`.docx`, `.xlsx`, `.pptx` and their older and open forms), `.zip`, `.xml`, `.yaml`, `.js` and `.mjs`, `.rtf`, more audio and video (`.m4a`, `.aac`, `.flac`, `.mov`, `.m4v`), and `.avif`, `.bmp`, `.tif`, `.vtt`, `.ttf` and `.otf`. A file with an extension the table does not list is `application/octet-stream`, where the dev server used to guess. The table is in the [file handling guide](guides/file-handling.md#media-types)
|
|
80
|
+
- **A custom scenario reads the files of the built-in scenario it was copied from.** An `asset:` reference your code builds, which copying a scenario cannot convert, resolves against that scenario, through any copies of copies, and a runtime refuses a custom scenario whose built-in scenario your release no longer ships. Bump `scenarioFormat` when you move or remove a built-in scenario's files. See [Files a custom scenario reads](guides/scenarios.md#files-a-custom-scenario-reads). A copy of a restricted scenario is restricted with it, offered only to callers granted the original
|
|
81
|
+
|
|
82
|
+
- **A setting under a key that is not a plain name is named in brackets.** A refusal, a lock's message or a file check naming a setting writes a key that is empty or holds a `.`, `[`, `]`, `"` or space as a JSON string, `ui.Cast["a.b"].portrait`, where it wrote `ui.Cast.a.b.portrait`, which reads two ways. Every path whose keys are plain names reads as before, and a guide's `:setting` and `:::when` read the bracketed form
|
|
83
|
+
|
|
84
|
+
### Fixed
|
|
85
|
+
|
|
86
|
+
- **The dev server answers a byte range of a blob.** A request for part of an uploaded or generated file, as a `<video>` or `<audio>` element makes to seek, was answered with the whole file, so a browser could not seek a blob's video and Safari would not play it. It is answered with `206 Partial Content`, as scenario and shared files already were, and a `HEAD` request carries `Accept-Ranges`
|
|
87
|
+
- **A `readOnly` lock the dev server could not enforce now fails the build.** A lock beneath an array's `items`, or a map's `additionalProperties` or `patternProperties`, was never enforced, so a scenario or a setup screen could change a value the game believed fixed. `sdk build` now refuses it, saying to lock the whole list or map instead. A lock reached through a local `$ref` is now enforced like one written in place, and a scenario naming it is refused
|
|
88
|
+
- **A file inside a keyed map is checked like any other.** A file setting or an endpoint file input declared as the entries of a map, through `additionalProperties` or `patternProperties` (`"Cast": { "additionalProperties": { "properties": { "portrait": { "type": "string", "blob": {...} } } } }`), was never checked: the build passed a scenario naming a file the package does not ship, the dev server stored a setting naming an upload of the wrong type, and an endpoint handler received a `data:` URI or a URL where it expected a `blob:` reference. Each entry is now held to the declaration, named by its key (`cast.Cast.ada.portrait`), and the generated `Request` types it as a `blob:` reference. A document per language is one such map, keyed by locale: see [A file per language](guides/file-handling.md#a-file-per-language)
|
|
89
|
+
- **On the dev server, the scenario editor reads the files of the scenario it is editing.** `getAssetUrl`, `readAsset` and `useAssetUrl` in the editor, and `readAsset` and `extractText` in the scenario-scoped endpoints it calls, resolved `asset:` references against the scenario the session was running. An editor open on any other scenario found that scenario's own files missing, and read the session's copy of any file both scenarios ship. You no longer need to restart the session on a scenario to edit it
|
|
90
|
+
- **An endpoint's generated `Settings` type matches the engine's.** Inside an object-valued setting, the keys its default carries are now required in an endpoint's `types.ts`, as they already were for every other resource, so code shared between an endpoint and the engine can use one type. A test that builds an endpoint's settings by hand may need those keys added; spreading the generated `defaultSettings` supplies them
|
|
91
|
+
|
|
34
92
|
## [1.3.0] — 2026-10-26
|
|
35
93
|
|
|
36
94
|
### Added
|
|
37
95
|
|
|
38
|
-
- **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session.md#opening-host-overlays)
|
|
39
|
-
- **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session.md#changing-the-language)
|
|
40
|
-
- **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui.md#letting-a-participant-fix-their-own-name)
|
|
96
|
+
- **A session UI can open the presentation.** `openHostOverlay('presentation')` opens your deck for the current session in the host's own chrome, usually in a window the facilitator can put on the projector. List `presentation-overlay` in `requires` to be offered it, and show the button only where `useSessionUserInterfaceHostOverlays()` includes `'presentation'`. `examples/factory` has one. See [Opening host overlays](guides/session-game-flow.md#opening-host-overlays)
|
|
97
|
+
- **A session UI can change the session's language** with `setLocale(locale)`, where `useSessionUserInterfaceMeta().canSetLocale` is `true`. A locale your game does not support is refused. See [Changing the language](guides/session-game-flow.md#changing-the-language)
|
|
98
|
+
- **A participant can fix their own name** with `renameSelf(name)` from a game or waiting room UI, where `useUserInterfaceCanRenameSelf()` is `true`. The host decides whose names are theirs to change. See [Letting a participant fix their own name](guides/ui-participants.md#letting-a-participant-fix-their-own-name)
|
|
41
99
|
- **A deck can show the room how to join.** A presentation's `session` carries every team's `participants`, a `joinLinks` entry per team and the session's `joinPin`, so a slide can put the join links on the projector and count who has arrived. See [Showing the room how to join](guides/presentation.md#showing-the-room-how-to-join)
|
|
42
100
|
- **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
|
|
43
101
|
|
|
@@ -235,7 +293,7 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
235
293
|
- **`failure.retry()` on `useMutationReporter`** after a `conflict`, for a person-initiated 'Try again'
|
|
236
294
|
- **Typed session writes and test fixtures.** A session UI's generated `types.ts` adds `TeamWrites`, the team-scope capabilities in its `writes`, and `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()` types the per-team `setData(teamId, update)` with it, so a team write naming a shared capability fails to compile. `createMockTeamState<TeamContext>`, `createMockSharedState<SharedContext>` and `renderSessionUserInterface<SessionData>` type a test's fixtures the same way. Every parameter defaults to today's untyped form, so existing code compiles unchanged. See [Session UIs](guides/testing.md#session-uis)
|
|
237
295
|
- **A session UI can delete keys.** Both forms of a session surface's `setData` take `{ deletes }` last, as a player surface's does: `setData(teamId, {}, { deletes })` removes from one team and `setData({}, { deletes })` from the shared store. Each path must fall under a capability the surface writes, of the form's scope, or the write is refused as `denied`. `mergingSetData` in `@seriousgaming/sdk/ui/testing` takes the same options and applies them after the merge, as the host does. See [Removing a key](guides/session.md#removing-a-key)
|
|
238
|
-
- **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session.md#deleting-a-team)
|
|
296
|
+
- **A session UI can delete an empty team** with `callbacks.deleteTeam(teamId)` in an independent session, once its participants have been moved out. The index is left as a gap, and undo never brings the team back. The dev console has a Delete team button. See [Deleting a team](guides/session-game-flow.md#deleting-a-team)
|
|
239
297
|
- **`pauseTimer` and `resumeTimer` are awaitable**, resolving once the host has applied the change and rejecting with a `MutationError` when it refuses
|
|
240
298
|
- **Every past-state entry carries `index` and `name`**, and the mode-colour theme types (`UserInterfaceModeColors` and siblings) are exported
|
|
241
299
|
|
|
@@ -80,6 +80,64 @@ can move it to any corner (remembered per browser).
|
|
|
80
80
|
Everything the drawer does, the CLI does too, because both send the same
|
|
81
81
|
commands.
|
|
82
82
|
|
|
83
|
+
## Embedding the dev server
|
|
84
|
+
|
|
85
|
+
On your own machine, the server works out every address it hands out from the
|
|
86
|
+
request: the host your browser used, `http://`, and its own ports. Behind a
|
|
87
|
+
proxy or gateway, such as a sandbox that serves the console on an HTTPS
|
|
88
|
+
hostname and shows it in a frame, those addresses come out wrong, and join
|
|
89
|
+
links read `http://localhost:47100/team/1/join`. Tell the server where it is
|
|
90
|
+
reached instead:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pnpm run sdk dev --no-open \
|
|
94
|
+
--public-url https://console.example.com \
|
|
95
|
+
--public-asset-url https://assets.example.com \
|
|
96
|
+
--public-hmr-url wss://hmr.example.com
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
| Option | Environment variable | What it names | Default when unset |
|
|
100
|
+
| -------------------- | ------------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
101
|
+
| `--public-url` | `SERIOUSGAMING_DEV_PUBLIC_URL` | The console, its API, and every link it hands out | The request's host |
|
|
102
|
+
| `--public-asset-url` | `SERIOUSGAMING_DEV_PUBLIC_ASSET_URL` | Where browsers load game surfaces and their files | The `--public-url` host on the asset port, else the request's host |
|
|
103
|
+
| `--public-hmr-url` | `SERIOUSGAMING_DEV_PUBLIC_HMR_URL` | Where a surface's hot-reload client connects | The public asset host on the Vite port, `wss://` when that host is HTTPS |
|
|
104
|
+
|
|
105
|
+
Each takes an origin only: a scheme, a host and, where it is not the default,
|
|
106
|
+
a port, with no path. The asset origin must differ from the console's, as it
|
|
107
|
+
does in production, so a game's code cannot call the console's API. A gateway
|
|
108
|
+
that serves each port on its own hostname needs all three set; one that keeps
|
|
109
|
+
the ports and adds TLS needs only `--public-url`. With none set, nothing
|
|
110
|
+
changes.
|
|
111
|
+
|
|
112
|
+
The server still listens on the ports it prints, so point the gateway at those:
|
|
113
|
+
the console's port, the asset port, and the Vite port for hot reload.
|
|
114
|
+
|
|
115
|
+
### Colour scheme and brand
|
|
116
|
+
|
|
117
|
+
The console keeps its colour scheme and brand in its own browser storage,
|
|
118
|
+
which a page on another origin cannot write. So the framing page says what it
|
|
119
|
+
wants in the console's URL:
|
|
120
|
+
|
|
121
|
+
- `?scheme=light`, `?scheme=dark` or `?scheme=system`: the colour scheme
|
|
122
|
+
- `?brand=<id>`: one of the brands the server offers, by the identifier its
|
|
123
|
+
**Brand** menu shows
|
|
124
|
+
|
|
125
|
+
Both apply from the first paint, last for the rest of that tab as the console
|
|
126
|
+
moves between its own pages, and never overwrite the viewer's stored choice.
|
|
127
|
+
Picking a scheme or brand in the dev drawer takes over from them. The scheme
|
|
128
|
+
reaches the game's surfaces exactly as the drawer's own scheme menu does.
|
|
129
|
+
|
|
130
|
+
To change the scheme later without a reload, post a message to the frame:
|
|
131
|
+
|
|
132
|
+
```ts
|
|
133
|
+
frame.contentWindow?.postMessage({ type: 'sg-dev-scheme', scheme: 'dark' }, consoleOrigin);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The console acts on it only when it is framed, and only from the page directly
|
|
137
|
+
around it. It does not check that page's origin, so any page that frames the
|
|
138
|
+
console can change its scheme: harmless for a colour scheme, and the reason the
|
|
139
|
+
message carries nothing else.
|
|
140
|
+
|
|
83
141
|
## How a command finds the session
|
|
84
142
|
|
|
85
143
|
`.seriousgaming-sdk/session.json` is a **lock file**, not state:
|