@seriousgaming/sdk-tools 1.2.0 → 1.4.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 +3582 -2834
- package/dist/client.js +1145 -543
- package/dist/core/participant-registry.d.ts +6 -0
- package/dist/core/session-host.d.ts +4 -2
- package/dist/core/session-roster.d.ts +4 -1
- package/dist/core/settings-locks.d.ts +27 -2
- package/dist/dev/console/assets/{index-BNLEVOQA.js → index-BvB-LFQZ.js} +47 -47
- package/dist/dev/console/index.html +1 -1
- package/dist/dev/routes.d.ts +4 -0
- package/dist/dev/view/batch.d.ts +24 -10
- package/dist/dev/view/view.d.ts +2 -1
- package/dist/docs/api/index.md +2 -2
- package/dist/docs/api/sdk-commands.md +4 -0
- package/dist/docs/api/sdk-e2e.md +4 -0
- package/dist/docs/api/sdk-tools-client.md +5 -0
- package/dist/docs/api/sdk-ui-testing.md +1 -0
- package/dist/docs/api/sdk-ui.md +33 -1
- package/dist/docs/api/sdk.md +82 -3
- package/dist/docs/changelog.md +41 -0
- package/dist/docs/concepts/terminology.md +1 -1
- package/dist/docs/guides/capabilities.md +2 -0
- package/dist/docs/guides/endpoints.md +2 -2
- package/dist/docs/guides/engine-testing.md +1 -1
- package/dist/docs/guides/file-handling.md +113 -21
- package/dist/docs/guides/llm-integration.md +1 -1
- package/dist/docs/guides/presentation.md +23 -9
- package/dist/docs/guides/scenario-editor.md +1 -1
- package/dist/docs/guides/scenarios.md +9 -1
- package/dist/docs/guides/session.md +47 -8
- package/dist/docs/guides/settings.md +62 -2
- package/dist/docs/guides/testing.md +9 -0
- package/dist/docs/guides/ui.md +33 -0
- package/dist/docs/guides/upgrading.md +11 -0
- package/dist/docs/guides/validators.md +62 -4
- package/dist/docs/guides/waiting-room.md +2 -0
- package/dist/docs/recipes/upload-and-display-files.md +7 -7
- package/dist/docs/recipes/validate-scenarios.md +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/protocol.d.ts +27 -2
- package/dist/host.js +64 -2
- package/dist/runtime/manifest-version.d.ts +1 -1
- package/dist/runtime.js +9 -2
- package/dist/storage/asset-resolver.d.ts +24 -1
- package/dist/storage/blob-store.d.ts +7 -0
- package/dist/utils/local-refs.d.ts +40 -0
- package/dist/utils/schema-members.d.ts +19 -0
- package/package.json +3 -3
|
@@ -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-BvB-LFQZ.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
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/view/batch.d.ts
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* boundary, and a host that sends everything and lets the guest ignore the rest
|
|
12
12
|
* has not projected at all.
|
|
13
13
|
*/
|
|
14
|
-
import type { HostOverlay } from '@seriousgaming/sdk';
|
|
14
|
+
import type { HostOverlay, ResolvedPackageManifest } from '@seriousgaming/sdk';
|
|
15
15
|
import type { StateProjection } from '@seriousgaming/sdk/projection';
|
|
16
16
|
import type { CrossTeamData, SessionData, TeamConfiguration, TeamLinks, WalkthroughLink } from '@seriousgaming/sdk/ui';
|
|
17
17
|
import type { ViewerRole } from '../../core/protocol';
|
|
@@ -57,8 +57,8 @@ export interface BatchOptions {
|
|
|
57
57
|
assetOrigin?: string;
|
|
58
58
|
/** The game's own name, which a session surface renders as the session's. */
|
|
59
59
|
gameName: string;
|
|
60
|
-
/**
|
|
61
|
-
|
|
60
|
+
/** The host overlays a session surface is offered (§6.4); see {@link availableOverlays}. */
|
|
61
|
+
overlays?: HostOverlay[];
|
|
62
62
|
/** Whether a tick is running over this viewer's team (§12.4.4). */
|
|
63
63
|
roundProcessing?: boolean;
|
|
64
64
|
/**
|
|
@@ -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
|
*
|
|
@@ -140,13 +146,21 @@ export declare function walkthroughLink(origin: string): WalkthroughLink;
|
|
|
140
146
|
/**
|
|
141
147
|
* The host-owned overlays a session surface may open (§6.4).
|
|
142
148
|
*
|
|
143
|
-
*
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
149
|
+
* Each is the console's own page rather than anything the game mounts, which
|
|
150
|
+
* is what makes them the host's to offer: a facilitator on a surface that owns
|
|
151
|
+
* the whole canvas can reach the guide, the team sheets and the deck without
|
|
152
|
+
* leaving it. A guide is offered only when the package ships one, and the deck
|
|
153
|
+
* only when it ships one and lists `presentation-overlay` (§2.6) — a control
|
|
154
|
+
* for an overlay the host does not have is a control that cannot work.
|
|
148
155
|
*/
|
|
149
|
-
export declare function availableOverlays(
|
|
156
|
+
export declare function availableOverlays(offered?: {
|
|
157
|
+
guide?: boolean;
|
|
158
|
+
presentation?: boolean;
|
|
159
|
+
}): HostOverlay[];
|
|
160
|
+
/** Whether a package is offered its deck as a host overlay (§6.4). */
|
|
161
|
+
export declare function offersPresentationOverlay(config: ResolvedPackageManifest | null): boolean;
|
|
162
|
+
/** The `requires` feature name behind the `'presentation'` overlay (§6.4). */
|
|
163
|
+
export declare const PRESENTATION_OVERLAY = "presentation-overlay";
|
|
150
164
|
/**
|
|
151
165
|
* One join and observe URL per team, for the facilitator surface.
|
|
152
166
|
*
|
package/dist/dev/view/view.d.ts
CHANGED
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
* The operator console, which renders its own inspector in the same document
|
|
10
10
|
* as the frame, keeps the whole projection and resolves the same rules itself.
|
|
11
11
|
*/
|
|
12
|
+
import type { HostOverlay } from '@seriousgaming/sdk';
|
|
12
13
|
import type { StateProjection } from '@seriousgaming/sdk/projection';
|
|
13
14
|
import type { HostMessage, SurfaceKind } from '../../host';
|
|
14
15
|
import type { MountableSurface } from '../surfaces';
|
|
@@ -71,7 +72,7 @@ export interface ViewMessageOptions {
|
|
|
71
72
|
origin: string;
|
|
72
73
|
assetOrigin: string;
|
|
73
74
|
gameName: string;
|
|
74
|
-
|
|
75
|
+
overlays: HostOverlay[];
|
|
75
76
|
roundProcessing: boolean;
|
|
76
77
|
}
|
|
77
78
|
/** Every message a viewer page's surface is owed, less the theme the page adds. */
|
package/dist/docs/api/index.md
CHANGED
|
@@ -6,8 +6,8 @@ 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) |
|
|
10
|
-
| [`@seriousgaming/sdk/ui`](./sdk-ui.md) |
|
|
9
|
+
| [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
|
|
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 |
|
|
13
13
|
| [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
|
package/dist/docs/api/sdk-e2e.md
CHANGED
|
@@ -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>[]>;
|
|
@@ -380,6 +381,10 @@ type MutationCommand =
|
|
|
380
381
|
type: 'renameOwnTeam';
|
|
381
382
|
name: string;
|
|
382
383
|
} & Actor)
|
|
384
|
+
| ({
|
|
385
|
+
type: 'renameSelf';
|
|
386
|
+
name: string;
|
|
387
|
+
} & Actor)
|
|
383
388
|
| {
|
|
384
389
|
type: 'addParticipant';
|
|
385
390
|
teamId: string;
|
|
@@ -237,6 +237,7 @@ type RenderUserInterfaceOptions = {
|
|
|
237
237
|
teams?: TeamInfo[];
|
|
238
238
|
ownTeam?: TeamInfo | null;
|
|
239
239
|
ownTeamJoinLink?: OwnTeamJoinLink | null;
|
|
240
|
+
canRenameSelf?: boolean;
|
|
240
241
|
timer?: TimerState;
|
|
241
242
|
validationRejections?: ValidationRejection[];
|
|
242
243
|
clearRejections?: () => void;
|
package/dist/docs/api/sdk-ui.md
CHANGED
|
@@ -287,6 +287,14 @@ const useSettingsEditorThemePreference: () => ThemePreference;
|
|
|
287
287
|
const useUserInterfaceCallbacks: () => UserInterfaceCallbacks;
|
|
288
288
|
```
|
|
289
289
|
|
|
290
|
+
### useUserInterfaceCanRenameSelf
|
|
291
|
+
|
|
292
|
+
Whether the participant using this surface may change their own name with `renameSelf`.
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
const useUserInterfaceCanRenameSelf: () => boolean;
|
|
296
|
+
```
|
|
297
|
+
|
|
290
298
|
### useUserInterfaceCrossTeamData
|
|
291
299
|
|
|
292
300
|
Observe every team's live cross-team state, including the calling team's own. Entries update as teams change their pending state, without waiting for a tick.
|
|
@@ -641,6 +649,14 @@ The React context behind `useUserInterfaceCallbacks`.
|
|
|
641
649
|
const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
|
|
642
650
|
```
|
|
643
651
|
|
|
652
|
+
### UserInterfaceCanRenameSelfContext
|
|
653
|
+
|
|
654
|
+
The React context behind `useUserInterfaceCanRenameSelf`.
|
|
655
|
+
|
|
656
|
+
```ts
|
|
657
|
+
const UserInterfaceCanRenameSelfContext: import('react').Context<boolean>;
|
|
658
|
+
```
|
|
659
|
+
|
|
644
660
|
### UserInterfaceCrossTeamDataContext
|
|
645
661
|
|
|
646
662
|
The React context behind `useUserInterfaceCrossTeamData`.
|
|
@@ -931,6 +947,18 @@ interface PresentationGame {
|
|
|
931
947
|
}
|
|
932
948
|
```
|
|
933
949
|
|
|
950
|
+
### PresentationJoinLink
|
|
951
|
+
|
|
952
|
+
How participants join one team, as a deck shows it to the room: the join links a session surface is given, without the facilitator's observe URL.
|
|
953
|
+
|
|
954
|
+
```ts
|
|
955
|
+
interface PresentationJoinLink {
|
|
956
|
+
teamId: string;
|
|
957
|
+
joinUrl: string;
|
|
958
|
+
fallbackJoinUrl?: string;
|
|
959
|
+
}
|
|
960
|
+
```
|
|
961
|
+
|
|
934
962
|
### PresentationSession
|
|
935
963
|
|
|
936
964
|
The session a presentation is shown during: the shared store and every team, narrowed to what the presentation `reads`.
|
|
@@ -945,6 +973,9 @@ interface PresentationSession<
|
|
|
945
973
|
completedTicks: number;
|
|
946
974
|
data: SessionData<TTeamContext, TSharedContext>;
|
|
947
975
|
teams: TeamInfo[];
|
|
976
|
+
participants?: Participant[];
|
|
977
|
+
joinLinks?: PresentationJoinLink[];
|
|
978
|
+
joinPin?: string | null;
|
|
948
979
|
}
|
|
949
980
|
```
|
|
950
981
|
|
|
@@ -1192,7 +1223,7 @@ type EndpointFailureOutcome =
|
|
|
1192
1223
|
A host-rendered overlay a session surface may ask the host to open.
|
|
1193
1224
|
|
|
1194
1225
|
```ts
|
|
1195
|
-
type HostOverlay = 'facilitator-guide' | 'print-sheets';
|
|
1226
|
+
type HostOverlay = 'facilitator-guide' | 'print-sheets' | 'presentation';
|
|
1196
1227
|
```
|
|
1197
1228
|
|
|
1198
1229
|
### MutationFailure
|
|
@@ -1307,6 +1338,7 @@ type SessionMeta = {
|
|
|
1307
1338
|
readOnly: boolean;
|
|
1308
1339
|
waitingRoomOpen: boolean;
|
|
1309
1340
|
joinPin: string | null;
|
|
1341
|
+
canSetLocale?: boolean;
|
|
1310
1342
|
};
|
|
1311
1343
|
```
|
|
1312
1344
|
|
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 {
|
|
@@ -1290,6 +1363,7 @@ interface SessionUserInterfaceCallbacks {
|
|
|
1290
1363
|
extendTick: (byMs: number, teamId?: string) => Promise<void>;
|
|
1291
1364
|
openHostOverlay: (overlay: HostOverlay, target?: string) => Promise<void>;
|
|
1292
1365
|
setWaitingRoom: (open: boolean) => Promise<void>;
|
|
1366
|
+
setLocale: (locale: string) => Promise<void>;
|
|
1293
1367
|
resetWalkthrough: () => Promise<void>;
|
|
1294
1368
|
createTeam: (name?: string) => Promise<void>;
|
|
1295
1369
|
renameTeam: (teamId: string, name: string) => Promise<void>;
|
|
@@ -1363,6 +1437,7 @@ Every callback a runtime may offer logic: the engine, hooks, tick controllers an
|
|
|
1363
1437
|
interface SignatureCallbacks {
|
|
1364
1438
|
generateText: LLMGenerateFunction;
|
|
1365
1439
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
1440
|
+
describeAsset?: (reference: string) => Promise<AssetDescription | undefined>;
|
|
1366
1441
|
getPastState: <T = Record<string, unknown>>(
|
|
1367
1442
|
query: PastStateQuery<T>
|
|
1368
1443
|
) => Promise<PastStateEntry<T>[]>;
|
|
@@ -1484,6 +1559,7 @@ Callbacks available to user interface components
|
|
|
1484
1559
|
interface UserInterfaceCallbacks {
|
|
1485
1560
|
requestTick: () => Promise<void>;
|
|
1486
1561
|
renameOwnTeam: (name: string) => Promise<void>;
|
|
1562
|
+
renameSelf: (name: string) => Promise<void>;
|
|
1487
1563
|
uploadBlob: (file: File) => Promise<string>;
|
|
1488
1564
|
getAssetUrl: (reference: string) => string;
|
|
1489
1565
|
readAsset: (reference: string) => Promise<ReadAssetResponse>;
|
|
@@ -1969,7 +2045,7 @@ type HookSignal = 'participantJoin' | 'participantMove';
|
|
|
1969
2045
|
A host-rendered overlay a session surface may ask the host to open.
|
|
1970
2046
|
|
|
1971
2047
|
```ts
|
|
1972
|
-
type HostOverlay = 'facilitator-guide' | 'print-sheets';
|
|
2048
|
+
type HostOverlay = 'facilitator-guide' | 'print-sheets' | 'presentation';
|
|
1973
2049
|
```
|
|
1974
2050
|
|
|
1975
2051
|
### InitAggregateFunction
|
|
@@ -2142,7 +2218,10 @@ type ThemePreference = 'light' | 'dark' | 'system';
|
|
|
2142
2218
|
The `SignatureCallbacks` members that `uses` does not gate.
|
|
2143
2219
|
|
|
2144
2220
|
```ts
|
|
2145
|
-
type UngatedSignatureCallbacks = Pick<
|
|
2221
|
+
type UngatedSignatureCallbacks = Pick<
|
|
2222
|
+
SignatureCallbacks,
|
|
2223
|
+
'readAsset' | 'describeAsset' | 'getPastState'
|
|
2224
|
+
>;
|
|
2146
2225
|
```
|
|
2147
2226
|
|
|
2148
2227
|
### ValidationResult
|
package/dist/docs/changelog.md
CHANGED
|
@@ -31,6 +31,47 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
31
31
|
|
|
32
32
|
## [Unreleased]
|
|
33
33
|
|
|
34
|
+
## [1.4.0] — 2026-10-26
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
|
|
38
|
+
- **`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)
|
|
39
|
+
- **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)
|
|
40
|
+
- **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
|
|
41
|
+
|
|
42
|
+
- **`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)
|
|
43
|
+
|
|
44
|
+
### Changed
|
|
45
|
+
|
|
46
|
+
- **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)
|
|
47
|
+
- **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
|
|
48
|
+
|
|
49
|
+
- **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
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
- **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`
|
|
54
|
+
- **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
|
|
55
|
+
- **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)
|
|
56
|
+
- **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
|
|
57
|
+
- **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
|
|
58
|
+
|
|
59
|
+
## [1.3.0] — 2026-10-26
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- **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)
|
|
64
|
+
- **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)
|
|
65
|
+
- **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)
|
|
66
|
+
- **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)
|
|
67
|
+
- **`renderUserInterface` takes `canRenameSelf`**, and `renderSessionUserInterface`'s `sessionMeta` takes `canSetLocale`, for testing these controls
|
|
68
|
+
|
|
69
|
+
### Changed
|
|
70
|
+
|
|
71
|
+
- **A host may open an overlay in a window of its own** as well as over your session UI. Nothing to change: `openHostOverlay` still only asks
|
|
72
|
+
- **The callbacks a surface is handed may gain required members in a minor release.** `UserInterfaceCallbacks`, `SessionUserInterfaceCallbacks` and `SettingsEditorCallbacks` are implemented by the runtime, so they are now outside semantic versioning, as their contexts already were. This release adds `renameSelf` and `setLocale` to them, so a test that builds a callbacks object by hand and passes it to a context provider stops compiling. Render through the `render*` helpers instead, which fill in every callback you do not pass. See [1.3: let the render helpers build your callbacks](guides/upgrading.md#13-let-the-render-helpers-build-your-callbacks) and [What a minor release may change](guides/testing.md#what-a-minor-release-may-change)
|
|
73
|
+
- **The dev server refuses a session locale the game does not declare**, from `pnpm run sdk locale`, the console's picker or an endpoint's `setLocale` action, rather than switching to it
|
|
74
|
+
|
|
34
75
|
## [1.2.0] — 2026-10-25
|
|
35
76
|
|
|
36
77
|
### Breaking Changes
|
|
@@ -298,7 +298,7 @@ The quality and cost level of an LLM call. The platform maps each tier to a mode
|
|
|
298
298
|
|
|
299
299
|
### Asset reference
|
|
300
300
|
|
|
301
|
-
A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
|
|
301
|
+
A string naming a file the SDK can read: `asset:<path>` for a file in the active scenario's `assets/` directory, or `blob:<id>` for a file uploaded at run time. Every callback that takes a file takes one: `getAssetUrl`, `readAsset`, `describeAsset`, `extractText`. See [Asset references](../guides/file-handling.md).
|
|
302
302
|
|
|
303
303
|
### Blob
|
|
304
304
|
|
|
@@ -14,6 +14,8 @@ A capability is a named collection of related variables, declared by a schema. F
|
|
|
14
14
|
|
|
15
15
|
Each capability declares its variables in a `variablesSchema`: a full JSON Schema 7 object whose properties are the variables, each with a type, a `default`, and any constraints. Every capability starts from those defaults, so its variables exist from the first tick for anything that declares it.
|
|
16
16
|
|
|
17
|
+
A shape used in several places, or one that contains itself, is declared once under `$defs` and used with a `$ref`, as in a settings schema (see [Reuse a shape, or nest it to any depth](./settings.md#reuse-a-shape-or-nest-it-to-any-depth)). The variable's `default` goes beside the `$ref`.
|
|
18
|
+
|
|
17
19
|
### Context is scoped by capability
|
|
18
20
|
|
|
19
21
|
A team's state, the context, is one object keyed by capability identifier, each value holding that capability's variables:
|
|
@@ -120,7 +120,7 @@ The handler receives:
|
|
|
120
120
|
- `context`: the capabilities listed in `reads` and `writes`, and nothing else. On a session-scoped endpoint, only the shared ones (see above)
|
|
121
121
|
- `team`: on a team-scoped endpoint, the team the call acts on. `teams`: on a session-scoped one, every team's declared values
|
|
122
122
|
- `settings`: exactly the settings resources listed in `settings`, keyed by identifier, read-only
|
|
123
|
-
- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset` and `getPastState`. An undeclared gated callback throws
|
|
123
|
+
- `callbacks`: the callbacks named in `uses`, plus the ungated `readAsset`, `describeAsset` and `getPastState`. An undeclared gated callback throws
|
|
124
124
|
- `caller`: who is calling, issued by the host and never by the iframe (see below)
|
|
125
125
|
- `meta`: the facts true of the whole run: `meta.locale` (the session locale), `meta.seed`, `meta.runKind`, `meta.now`, the instant the call started, and `meta.scenarioName`, the active scenario's name for display
|
|
126
126
|
- `participants`: a read-only copy of the roster the call covers, the addressed team's on a team-scoped endpoint and every participant on a session-scoped one
|
|
@@ -284,7 +284,7 @@ A request field can be a file. Mark a string property with `blob`, saying which
|
|
|
284
284
|
}
|
|
285
285
|
```
|
|
286
286
|
|
|
287
|
-
The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
|
|
287
|
+
The handler always receives a `blob:` reference, typed `` `blob:${string}` ``, already checked against the declaration. It reads the file with `callbacks.readAsset`, asks its size with `callbacks.describeAsset`, passes it to `extractText`, or stores the reference in a capability for a screen to show with `getAssetUrl`.
|
|
288
288
|
|
|
289
289
|
The caller sends one of two things:
|
|
290
290
|
|
|
@@ -286,7 +286,7 @@ Tests are offline by default, whether they run a whole session or call one logic
|
|
|
286
286
|
- **`generateSpeech`** stores 100ms of silence as a WAV blob and returns `{ reference: 'blob:<id>', mimeType: 'audio/wav', durationMs: 100, charactersBilled: 0 }`, so `readAsset` resolves it as it would real audio
|
|
287
287
|
- **`extractText`** answers `{ content: '[stub] text of <reference>', mimeType: 'text/plain' }`, without reading the file
|
|
288
288
|
|
|
289
|
-
With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), and `getPastState` answers `[]`.
|
|
289
|
+
With no session behind them, the arguments `logicArgs` builds stub the rest as well: `writeBlob` stores in memory and returns `blob:stub-<n>`, `readAsset` reads back only a blob written in the same test (and rejects anything else, `asset:` references included), `describeAsset` describes only such a blob (and answers `undefined` for anything else), and `getPastState` answers `[]`.
|
|
290
290
|
|
|
291
291
|
| Export | From | Use it to |
|
|
292
292
|
| --------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|