@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
|
@@ -193,9 +193,11 @@ A refusal stops the tick, and the participant's `requestTick()` rejects with the
|
|
|
193
193
|
|
|
194
194
|
A settings schema checks each value on its own. It cannot say that two values conflict, such as a lowest price above the highest, or that a value has no sensible default and every scenario must supply its own, such as the name of the client an edition is built for. A `Scenario` gate says both.
|
|
195
195
|
|
|
196
|
-
Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about
|
|
196
|
+
Export `Scenario` from a validator's logic. It receives the settings the validator lists in `settings`, resolved through the defaults and the scenario being judged, and the `locale` to phrase a problem in. It returns every problem it finds, each naming the setting it is about by its `path`; an empty array passes:
|
|
197
197
|
|
|
198
198
|
```typescript
|
|
199
|
+
import { settingPath } from '@seriousgaming/sdk';
|
|
200
|
+
|
|
199
201
|
import type { ScenarioFunction } from '../types';
|
|
200
202
|
|
|
201
203
|
export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
@@ -203,13 +205,13 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
|
203
205
|
const problems = [];
|
|
204
206
|
if (MinPrice > MaxPrice) {
|
|
205
207
|
problems.push({
|
|
206
|
-
path: 'pricing
|
|
208
|
+
path: settingPath('pricing', 'MinPrice'),
|
|
207
209
|
message: `The lowest price (£${MinPrice}) must be at or below the highest price (£${MaxPrice})`,
|
|
208
210
|
});
|
|
209
211
|
}
|
|
210
212
|
if (settings.edition.ClientName === '') {
|
|
211
213
|
problems.push({
|
|
212
|
-
path: 'edition
|
|
214
|
+
path: settingPath('edition', 'ClientName'),
|
|
213
215
|
message: 'Every scenario names the client it is built for',
|
|
214
216
|
});
|
|
215
217
|
}
|
|
@@ -217,6 +219,8 @@ export const Scenario: ScenarioFunction = async ({ settings }) => {
|
|
|
217
219
|
};
|
|
218
220
|
```
|
|
219
221
|
|
|
222
|
+
A `path` is a setting path: `pricing.MinPrice`, the settings identifier and each key below it (see [How a setting is named](./settings.md#how-a-setting-is-named)). An editor reads it back to show the problem beside its field. Build it with `settingPath` rather than joining keys with dots, so a map entry whose key holds a dot is still named one way: `settingPath('cast', 'Portraits', 'a.b')` is `cast.Portraits["a.b"]`.
|
|
223
|
+
|
|
220
224
|
A game whose validator exports `Scenario` lists the feature in `seriousgaming.sdk.json`, and the build refuses it otherwise (`FEATURE_UNDECLARED`). A runtime that cannot run the gate then refuses the game, rather than saving scenarios your rules would refuse:
|
|
221
225
|
|
|
222
226
|
```json
|
|
@@ -225,6 +229,60 @@ A game whose validator exports `Scenario` lists the feature in `seriousgaming.sd
|
|
|
225
229
|
}
|
|
226
230
|
```
|
|
227
231
|
|
|
232
|
+
### Checking the files a scenario names
|
|
233
|
+
|
|
234
|
+
A rule about a file setting is often a rule about the file: that the portrait is there, or that the briefing is not empty. List `scenario-files` in `requires` beside `scenario-validation`, and the gate receives `callbacks` with two file reads, `readAsset` and `describeAsset`:
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
{
|
|
238
|
+
"requires": ["scenario-validation", "scenario-files"]
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
import type { ScenarioFunction } from '../types';
|
|
244
|
+
|
|
245
|
+
export const Scenario: ScenarioFunction = async ({ settings, callbacks }) => {
|
|
246
|
+
const portrait = settings.cast.CeoPortrait;
|
|
247
|
+
if (portrait !== '' && (await callbacks.describeAsset(portrait)) === undefined) {
|
|
248
|
+
return [
|
|
249
|
+
{
|
|
250
|
+
path: 'cast.CeoPortrait',
|
|
251
|
+
message: `The CEO's portrait (${portrait}) is not a file this scenario has. Upload it again`,
|
|
252
|
+
},
|
|
253
|
+
];
|
|
254
|
+
}
|
|
255
|
+
return [];
|
|
256
|
+
};
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
- **They read the scenario being judged.** At build, `asset:` resolves against that scenario's own `assets/` and `shared:` against `shared-assets/`; a package scenario cannot name a blob, so a `blob:` reference finds nothing. On save, a draft's files resolve as the draft reads them: the built-in scenario it descends from, which for a draft of a package scenario is that scenario, and the files uploaded to it
|
|
260
|
+
- **`describeAsset`** answers `{ mimeType, size }`, or `undefined` for a file that is not there, without reading it. Prefer it when you only need to know the file exists or fits. **`readAsset`** returns the bytes, and rejects for a file that is not there
|
|
261
|
+
- **Nothing else.** No `generateText` and no `extractText`: the gate stays quick and gives the same answer every time. A rule that needs either belongs in an endpoint the scenario editor calls
|
|
262
|
+
- **Reads count against the gate's time limit**, so a gate reading every video whole may run out of time and refuse the scenario. Use `describeAsset` for those
|
|
263
|
+
- **`readAsset` reads nothing over 10 MB.** For a larger file it rejects with a `ScenarioAssetTooLargeError`, before reading any of it, and unless you catch it the gate counts as refusing the scenario: the build fails, or the save is refused, naming the file, its size and the limit. The limit is `SCENARIO_GATE_READ_LIMIT_BYTES` from `@seriousgaming/sdk` (10,485,760 bytes), the same in every runtime, so the gate gives the same answer at build and on save. To check that a video is there, or how big it is, call `describeAsset`, which works on a file of any size. To catch the error, test its `name`, not `instanceof`: the gate may run apart from the SDK that defines the class
|
|
264
|
+
- **Without `scenario-files`**, each call throws, naming the feature, and the gate counts as refusing the scenario. The build cannot tell in advance whether your gate reads a file, so this is where you find out
|
|
265
|
+
- **Your generated `ScenarioFunction` requires `callbacks`** once the package lists the feature, so a test calls the gate with them. Build them from plain functions:
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
const judge = (ui: Partial<Settings['ui']>) =>
|
|
269
|
+
Scenario({
|
|
270
|
+
settings: { ui: { ...defaultSettings.ui, ...ui } },
|
|
271
|
+
locale: 'en',
|
|
272
|
+
callbacks: {
|
|
273
|
+
describeAsset: async (reference) =>
|
|
274
|
+
reference === 'shared:branding/logo.svg'
|
|
275
|
+
? { mimeType: 'image/svg+xml', size: 2048 }
|
|
276
|
+
: undefined,
|
|
277
|
+
readAsset: async (reference) => {
|
|
278
|
+
throw new Error(`${reference} is not read in this test`);
|
|
279
|
+
},
|
|
280
|
+
},
|
|
281
|
+
});
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
`examples/factory`'s `scenariocheck` validator refuses a scenario whose branding logo is not a file it has.
|
|
285
|
+
|
|
228
286
|
### When it runs
|
|
229
287
|
|
|
230
288
|
- **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
|
|
@@ -243,7 +301,7 @@ A problem's message is shown as it is, to whoever is editing the scenario, and a
|
|
|
243
301
|
|
|
244
302
|
The gate is the last word, and it runs on save. A [scenario editor](./scenario-editor.md) can show the same problems as the author types by importing the rules the gate uses. Put the rules in a file both can reach, such as `shared/scenario-rules.ts`, call it from the gate, and call it from the editor to mark each field. Rules shared with logic run in the logic environment too, so keep them to plain functions with no browser or Node APIs.
|
|
245
303
|
|
|
246
|
-
The gate reads no game state and receives no `actor
|
|
304
|
+
The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
|
|
247
305
|
|
|
248
306
|
The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
|
|
249
307
|
|
|
@@ -174,6 +174,8 @@ await renameOwnTeam('The Cartographers');
|
|
|
174
174
|
|
|
175
175
|
It names no team: the host resolves the caller's, so a surface can only rename its own. Render `useUserInterfaceOwnTeam()?.name` rather than what you sent, because a facilitator may rename the same team at the same moment and the last write wins. A blank or over-long name is refused as a terminal `MutationError`. See [Letting a team name itself](./ui.md) for the full contract.
|
|
176
176
|
|
|
177
|
+
The lobby is also where a participant notices they mistyped their own name. Where `useUserInterfaceCanRenameSelf()` is `true`, `renameSelf(name)` fixes it. See [Letting a participant fix their own name](./ui.md#letting-a-participant-fix-their-own-name).
|
|
178
|
+
|
|
177
179
|
## Stopping the clock
|
|
178
180
|
|
|
179
181
|
Opening the room pauses nothing. The decision belongs to the game, because only the author knows whether the simulation should keep advancing in the background:
|
|
@@ -133,13 +133,13 @@ pnpm run sdk view
|
|
|
133
133
|
|
|
134
134
|
## Troubleshooting
|
|
135
135
|
|
|
136
|
-
| Problem | Solution
|
|
137
|
-
| ------------------------------------ |
|
|
138
|
-
| `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts`
|
|
139
|
-
| `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4)
|
|
140
|
-
| The engine never sees the reference | Add `upload` to the engine's `reads`
|
|
141
|
-
| The PDF does not render | Match the `<embed>` type to the file; see [
|
|
142
|
-
| `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md)
|
|
136
|
+
| Problem | Solution |
|
|
137
|
+
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
|
|
138
|
+
| `data.upload` is a type error | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts` |
|
|
139
|
+
| `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4) |
|
|
140
|
+
| The engine never sees the reference | Add `upload` to the engine's `reads` |
|
|
141
|
+
| The PDF does not render | Match the `<embed>` type to the file; see [Media types](../guides/file-handling.md#media-types) |
|
|
142
|
+
| `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md) |
|
|
143
143
|
|
|
144
144
|
## Related
|
|
145
145
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
|
|
4
4
|
|
|
5
|
-
**Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, custom scenario check
|
|
5
|
+
**Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, scenario-files, missing file, custom scenario check
|
|
6
6
|
|
|
7
7
|
## Prerequisites
|
|
8
8
|
|
|
@@ -72,6 +72,8 @@ Refuse a scenario whose settings break your game's rules, at build and when one
|
|
|
72
72
|
|
|
73
73
|
6. Optionally, show the same problems in your scenario editor by calling `scenarioProblems(settings.ui)` and marking each field whose setting a problem names
|
|
74
74
|
|
|
75
|
+
7. Optionally, check the files the scenario names: add `"scenario-files"` to `requires`, and the gate receives `callbacks.describeAsset` and `callbacks.readAsset`, resolved against the scenario being judged. See [Checking the files a scenario names](../guides/validators.md#checking-the-files-a-scenario-names)
|
|
76
|
+
|
|
75
77
|
## Verify
|
|
76
78
|
|
|
77
79
|
- `pnpm run sdk build --validate-only` passes
|
|
@@ -82,6 +84,7 @@ Refuse a scenario whose settings break your game's rules, at build and when one
|
|
|
82
84
|
- _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`
|
|
83
85
|
- _`SCENARIO_REFUSED` for 'The defaults'_: no scenario is the default, so a session can run on the defaults alone, and they break a rule. Mark a scenario `"default": true`, or change the defaults
|
|
84
86
|
- _A placeholder that is also a real choice_: the gate sees values, not where they came from, so it cannot tell a scenario that chose `0` from one that forgot. Use an obviously empty default (`""`, `[]` or `{}`)
|
|
87
|
+
- _'needs the "scenario-files" feature'_: the gate called `readAsset` or `describeAsset`, which it is handed only when `requires` lists `"scenario-files"`
|
|
85
88
|
- _'Validator scenariocheck threw'_: the gate threw, which counts as a problem so that a broken rule never lets a scenario through. Check the settings it reads are listed in `settings`
|
|
86
89
|
|
|
87
90
|
## Related
|
|
@@ -57,6 +57,12 @@ export interface EndpointCallArgs {
|
|
|
57
57
|
* (§6.12). The session's when absent.
|
|
58
58
|
*/
|
|
59
59
|
scenarioName?: string | null;
|
|
60
|
+
/**
|
|
61
|
+
* The root directory of the scenario a scenario-scoped call is made on,
|
|
62
|
+
* which its `asset:` references resolve against (§6.5), or null for a
|
|
63
|
+
* draft of no scenario.
|
|
64
|
+
*/
|
|
65
|
+
scenarioRoot?: string | null;
|
|
60
66
|
}
|
|
61
67
|
/**
|
|
62
68
|
* One endpoint call's outcome: the response its caller receives, and, for an
|
|
@@ -11,7 +11,6 @@
|
|
|
11
11
|
* own copy and drifting.
|
|
12
12
|
*/
|
|
13
13
|
import type { ApiUse, ResolvedPackageManifest, LogicMeta, Participant, RunKind, RunMeta, SignatureCallbacks } from '@seriousgaming/sdk';
|
|
14
|
-
import type { BlobRetention } from '../storage/blob-store';
|
|
15
14
|
import { type ExecutorCallbacksDeps } from './executor-callbacks';
|
|
16
15
|
import { type LogicOrigin, type SourceMapRegistry } from './logic-failure';
|
|
17
16
|
import type { LogicKind, LogicResource } from './logic-loader';
|
|
@@ -159,8 +158,14 @@ export declare class LogicCalls {
|
|
|
159
158
|
* The callbacks a resource receives: the raw runtime callbacks, built
|
|
160
159
|
* fresh so they read the live game, with every one its `uses` does not
|
|
161
160
|
* declare replaced by a throwing stub.
|
|
161
|
+
*
|
|
162
|
+
* `onDraft` is a scenario-scoped call's: its files are the draft's, and
|
|
163
|
+
* `asset:` resolves against the scenario being written, not the session's
|
|
164
|
+
* (§6.5, §6.12, §16.2).
|
|
162
165
|
*/
|
|
163
|
-
callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined,
|
|
166
|
+
callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined, onDraft?: {
|
|
167
|
+
scenarioRoot: string | null;
|
|
168
|
+
}): SignatureCallbacks;
|
|
164
169
|
/**
|
|
165
170
|
* Bound one call into author logic that runs as part of a tick, or of the
|
|
166
171
|
* initialisation a tick starts from (§11.10).
|
|
@@ -6,11 +6,29 @@
|
|
|
6
6
|
* board, so the build can run it on a package's own scenarios and the dev
|
|
7
7
|
* server on a scenario about to be saved, with only the package and a loader.
|
|
8
8
|
*/
|
|
9
|
-
import type
|
|
9
|
+
import { type ResolvedPackageManifest, type ScenarioProblem } from '@seriousgaming/sdk';
|
|
10
10
|
import { LogicLoader } from './logic-loader';
|
|
11
11
|
import type { SessionSettingsOverrides } from './types';
|
|
12
12
|
/** The `requires` feature name a package using the `Scenario` gate lists (§15.8). */
|
|
13
13
|
export declare const SCENARIO_VALIDATION = "scenario-validation";
|
|
14
|
+
/** The `requires` feature name a package whose `Scenario` gate reads files lists (§15.8). */
|
|
15
|
+
export declare const SCENARIO_FILES = "scenario-files";
|
|
16
|
+
/**
|
|
17
|
+
* Where the files of the scenario being judged resolve (§15.8): as that
|
|
18
|
+
* scenario resolves them, so a gate finds exactly the files a session started
|
|
19
|
+
* on it would.
|
|
20
|
+
*/
|
|
21
|
+
export interface ScenarioFileRoots {
|
|
22
|
+
/** The scenario's root directory, which `asset:` resolves against, or null for none. */
|
|
23
|
+
scenarioRoot: string | null;
|
|
24
|
+
/**
|
|
25
|
+
* Which blobs `blob:` resolves to: none for a package scenario, which can
|
|
26
|
+
* name no blob; the ones a draft can read, its `scenario` blobs, for a
|
|
27
|
+
* draft (§6.12); and every one for the session's own settings saved as a
|
|
28
|
+
* scenario, whose files the save takes with it.
|
|
29
|
+
*/
|
|
30
|
+
blobs: 'none' | 'draft' | 'all';
|
|
31
|
+
}
|
|
14
32
|
/** A problem one validator found with a scenario. */
|
|
15
33
|
export interface ScenarioGateProblem extends ScenarioProblem {
|
|
16
34
|
validatorIdentifier: string;
|
|
@@ -29,6 +47,8 @@ export declare function runScenarioGates(options: {
|
|
|
29
47
|
locale?: string;
|
|
30
48
|
loader?: LogicLoader;
|
|
31
49
|
boundMs?: number;
|
|
50
|
+
/** Where the scenario's files resolve. None at all when absent: the defaults alone. */
|
|
51
|
+
files?: ScenarioFileRoots;
|
|
32
52
|
}): Promise<ScenarioGateProblem[]>;
|
|
33
53
|
/** One line per problem, naming the validator and the setting. */
|
|
34
54
|
export declare function describeScenarioProblems(problems: ScenarioGateProblem[]): string[];
|
package/dist/guide/settings.d.ts
CHANGED
|
@@ -35,7 +35,7 @@ type Lookup = {
|
|
|
35
35
|
} | {
|
|
36
36
|
found: false;
|
|
37
37
|
};
|
|
38
|
-
/** The value at `identifier.key.key
|
|
38
|
+
/** The value at a setting path (§6.1a), `identifier.key.key…`, in resolved settings. */
|
|
39
39
|
export declare function lookupSetting(settings: GuideSettings, path: string): Lookup;
|
|
40
40
|
/** How a value reads in the guide, or null when it is not a renderable kind. */
|
|
41
41
|
export declare function formatSettingValue(value: unknown, locale: string): string | null;
|
package/dist/host/protocol.d.ts
CHANGED
|
@@ -121,9 +121,15 @@ export type HostPortMessage = {
|
|
|
121
121
|
} | {
|
|
122
122
|
type: 'setLocale';
|
|
123
123
|
payload: UserInterfaceLocale;
|
|
124
|
-
}
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* `canRenameSelf`: whether this host accepts `renameSelf` from this
|
|
127
|
+
* participant (§12.3). Send `true` only where it will; absent reads as `false`.
|
|
128
|
+
*/
|
|
129
|
+
| {
|
|
125
130
|
type: 'setParticipant';
|
|
126
131
|
payload: Participant;
|
|
132
|
+
canRenameSelf?: boolean;
|
|
127
133
|
} | {
|
|
128
134
|
type: 'setViewerRole';
|
|
129
135
|
role: ViewerRole;
|
|
@@ -319,6 +325,15 @@ export type IFramePortMessage = {
|
|
|
319
325
|
type: 'renameOwnTeam';
|
|
320
326
|
requestId?: string;
|
|
321
327
|
name: string;
|
|
328
|
+
}
|
|
329
|
+
/**
|
|
330
|
+
* Rename the sending participant (§12.5). Names nobody: resolve the caller
|
|
331
|
+
* yourself, and refuse it from anyone not reported `canRenameSelf: true`.
|
|
332
|
+
*/
|
|
333
|
+
| {
|
|
334
|
+
type: 'renameSelf';
|
|
335
|
+
requestId?: string;
|
|
336
|
+
name: string;
|
|
322
337
|
} | {
|
|
323
338
|
type: 'uploadBlob';
|
|
324
339
|
requestId: string;
|
|
@@ -604,6 +619,15 @@ export type IFrameSessionPortMessage = {
|
|
|
604
619
|
requestId?: string;
|
|
605
620
|
open: boolean;
|
|
606
621
|
}
|
|
622
|
+
/**
|
|
623
|
+
* The session's locale (§12.5). Session-wide; deny a locale the game does
|
|
624
|
+
* not declare in `supportedLocales`, and report `SessionMeta.canSetLocale`.
|
|
625
|
+
*/
|
|
626
|
+
| {
|
|
627
|
+
type: 'setLocale';
|
|
628
|
+
requestId?: string;
|
|
629
|
+
locale: string;
|
|
630
|
+
}
|
|
607
631
|
/**
|
|
608
632
|
* Throw the walkthrough away and start it again at tick 0 (§5.7). Session-
|
|
609
633
|
* wide like `setWaitingRoom`, and settling the same way. Denied while
|
|
@@ -617,7 +641,8 @@ export type IFrameSessionPortMessage = {
|
|
|
617
641
|
* Ask the host to open one of its own overlays (§6.4). The host renders it;
|
|
618
642
|
* this delegates the trigger alone. `target` is a team id for
|
|
619
643
|
* `print-sheets`, and omitting it means every team. `facilitator-guide`
|
|
620
|
-
*
|
|
644
|
+
* and `presentation` take none: a game holds one of each, and a `target`
|
|
645
|
+
* is ignored. An overlay
|
|
621
646
|
* the host does not offer, or a team id not in the session, settles as
|
|
622
647
|
* denied.
|
|
623
648
|
*/
|
package/dist/host.js
CHANGED
|
@@ -739,6 +739,66 @@ function chapterSources(locales, chapters, requested) {
|
|
|
739
739
|
});
|
|
740
740
|
}
|
|
741
741
|
|
|
742
|
+
// ../sdk/lib/build/tick-validation.js
|
|
743
|
+
var MAX_EFFECTIVE_TICK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
|
|
744
|
+
|
|
745
|
+
// ../sdk/lib/build/setting-path.js
|
|
746
|
+
var NOT_PLAIN = /[.[\]"\s]/u;
|
|
747
|
+
function isPlainKey(key) {
|
|
748
|
+
return key !== "" && !NOT_PLAIN.test(key);
|
|
749
|
+
}
|
|
750
|
+
function parseSettingPath(path2) {
|
|
751
|
+
const steps = [];
|
|
752
|
+
let at = 0;
|
|
753
|
+
while (at < path2.length) {
|
|
754
|
+
if (path2[at] === "[") {
|
|
755
|
+
const end2 = closingQuote(path2, at + 1);
|
|
756
|
+
if (end2 === void 0 || path2[end2 + 1] !== "]")
|
|
757
|
+
return void 0;
|
|
758
|
+
let key2;
|
|
759
|
+
try {
|
|
760
|
+
key2 = JSON.parse(path2.slice(at + 1, end2 + 1));
|
|
761
|
+
} catch {
|
|
762
|
+
return void 0;
|
|
763
|
+
}
|
|
764
|
+
if (typeof key2 !== "string")
|
|
765
|
+
return void 0;
|
|
766
|
+
steps.push(key2);
|
|
767
|
+
at = end2 + 2;
|
|
768
|
+
continue;
|
|
769
|
+
}
|
|
770
|
+
if (steps.length > 0) {
|
|
771
|
+
if (path2[at] !== ".")
|
|
772
|
+
return void 0;
|
|
773
|
+
at += 1;
|
|
774
|
+
}
|
|
775
|
+
let end = at;
|
|
776
|
+
while (end < path2.length && path2[end] !== "." && path2[end] !== "[")
|
|
777
|
+
end += 1;
|
|
778
|
+
const key = path2.slice(at, end);
|
|
779
|
+
if (!isPlainKey(key))
|
|
780
|
+
return void 0;
|
|
781
|
+
steps.push(key);
|
|
782
|
+
at = end;
|
|
783
|
+
}
|
|
784
|
+
const [identifier, ...keys] = steps;
|
|
785
|
+
return identifier === void 0 ? void 0 : { identifier, keys };
|
|
786
|
+
}
|
|
787
|
+
function closingQuote(path2, start) {
|
|
788
|
+
if (path2[start] !== '"')
|
|
789
|
+
return void 0;
|
|
790
|
+
for (let at = start + 1; at < path2.length; at += 1) {
|
|
791
|
+
if (path2[at] === "\\")
|
|
792
|
+
at += 1;
|
|
793
|
+
else if (path2[at] === '"')
|
|
794
|
+
return at;
|
|
795
|
+
}
|
|
796
|
+
return void 0;
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
// ../sdk/lib/build/validators.js
|
|
800
|
+
var SCENARIO_GATE_READ_LIMIT_BYTES = 10 * 1024 * 1024;
|
|
801
|
+
|
|
742
802
|
// ../node_modules/.pnpm/ccount@2.0.1/node_modules/ccount/index.js
|
|
743
803
|
function ccount(value, character) {
|
|
744
804
|
const source = String(value);
|
|
@@ -11940,8 +12000,10 @@ function isUint8Array2(value) {
|
|
|
11940
12000
|
|
|
11941
12001
|
// cli/guide/settings.ts
|
|
11942
12002
|
function lookupSetting(settings, path2) {
|
|
11943
|
-
const
|
|
11944
|
-
if (!
|
|
12003
|
+
const parsed = parseSettingPath(path2);
|
|
12004
|
+
if (!parsed || parsed.keys.length === 0) return { found: false };
|
|
12005
|
+
const { identifier, keys } = parsed;
|
|
12006
|
+
if (!Object.prototype.hasOwnProperty.call(settings, identifier)) return { found: false };
|
|
11945
12007
|
let value = settings[identifier];
|
|
11946
12008
|
for (const key of keys) {
|
|
11947
12009
|
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
@@ -26,7 +26,7 @@ export declare const MANIFEST_VERSION = 3;
|
|
|
26
26
|
* section is stamped, it is the revision at the top of the appendix.
|
|
27
27
|
* `spec-revision.test.ts` holds the two together.
|
|
28
28
|
*/
|
|
29
|
-
export declare const SPEC_REVISION = "1.
|
|
29
|
+
export declare const SPEC_REVISION = "1.4";
|
|
30
30
|
/**
|
|
31
31
|
* Whether specification revision `revision` is later than `than`, both as
|
|
32
32
|
* `major.minor`. A runtime MAY warn when a package's `builtWith.specRevision`
|
package/dist/runtime.js
CHANGED
|
@@ -13,6 +13,9 @@ var UndeclaredApiUseError = class extends Error {
|
|
|
13
13
|
// ../sdk/lib/build/tick-validation.js
|
|
14
14
|
var MAX_EFFECTIVE_TICK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1e3;
|
|
15
15
|
|
|
16
|
+
// ../sdk/lib/build/validators.js
|
|
17
|
+
var SCENARIO_GATE_READ_LIMIT_BYTES = 10 * 1024 * 1024;
|
|
18
|
+
|
|
16
19
|
// cli/runtime/guarded-callbacks.ts
|
|
17
20
|
var API_USE_TO_CALLBACK = {
|
|
18
21
|
generateText: "generateText",
|
|
@@ -302,7 +305,7 @@ function readTickControllerResult(label, result) {
|
|
|
302
305
|
|
|
303
306
|
// cli/runtime/manifest-version.ts
|
|
304
307
|
var MANIFEST_VERSION = 3;
|
|
305
|
-
var SPEC_REVISION = "1.
|
|
308
|
+
var SPEC_REVISION = "1.4";
|
|
306
309
|
function isLaterSpecRevision(revision, than) {
|
|
307
310
|
const [major, minor] = revision.split(".").map(Number);
|
|
308
311
|
const [thanMajor, thanMinor] = than.split(".").map(Number);
|
|
@@ -310,7 +313,11 @@ function isLaterSpecRevision(revision, than) {
|
|
|
310
313
|
}
|
|
311
314
|
var SUPPORTED_FEATURES = [
|
|
312
315
|
// A validator's `Scenario` gate (§15.8).
|
|
313
|
-
"scenario-validation"
|
|
316
|
+
"scenario-validation",
|
|
317
|
+
// The presentation as a host overlay a session surface may open (§6.4).
|
|
318
|
+
"presentation-overlay",
|
|
319
|
+
// File reads in a validator's `Scenario` gate (§15.8).
|
|
320
|
+
"scenario-files"
|
|
314
321
|
];
|
|
315
322
|
function unsupportedFeatures(manifest) {
|
|
316
323
|
return (manifest.requires ?? []).filter((feature) => !SUPPORTED_FEATURES.includes(feature));
|
|
@@ -10,13 +10,25 @@
|
|
|
10
10
|
* server's blob store.
|
|
11
11
|
*
|
|
12
12
|
* The dispatch lives here so every engine-side and endpoint-side caller
|
|
13
|
-
* (`readAsset`, `extractText`) shares a single
|
|
13
|
+
* (`readAsset`, `describeAsset`, `extractText`) shares a single
|
|
14
|
+
* implementation.
|
|
14
15
|
*/
|
|
16
|
+
import type { AssetDescription } from '@seriousgaming/sdk';
|
|
17
|
+
/**
|
|
18
|
+
* The media type of a package file, by its extension: the table in §16.3,
|
|
19
|
+
* which the build judges a file setting's `accept` by and the dev server
|
|
20
|
+
* serves files under. `media-types.test.ts` holds the two to each other.
|
|
21
|
+
*/
|
|
22
|
+
export declare const EXTENSION_MEDIA_TYPES: Readonly<Record<string, string>>;
|
|
23
|
+
/** What a file whose extension §16.3's table does not list is. */
|
|
24
|
+
export declare const UNLISTED_MEDIA_TYPE = "application/octet-stream";
|
|
15
25
|
export interface ResolvedAsset {
|
|
16
26
|
data: Buffer;
|
|
17
27
|
mimeType: string;
|
|
18
28
|
name: string;
|
|
19
29
|
}
|
|
30
|
+
/** The media type §16.3's table names for a file's extension, compared case-insensitively. */
|
|
31
|
+
export declare function mediaTypeOf(path: string): string;
|
|
20
32
|
/**
|
|
21
33
|
* Returns true when `value` is a string starting with one of the known
|
|
22
34
|
* asset URI scheme prefixes.
|
|
@@ -47,3 +59,14 @@ export declare function resolveSharedAsset(packagePath: string, path: string): P
|
|
|
47
59
|
* scenario root before passing it in.
|
|
48
60
|
*/
|
|
49
61
|
export declare function readAssetByReference(packagePath: string, scenarioRootDirectory: string | null, reference: string): Promise<ResolvedAsset>;
|
|
62
|
+
/**
|
|
63
|
+
* Describe what an `asset:<path>`, `shared:<path>`, or `blob:<id>` reference
|
|
64
|
+
* names, as {@link readAssetByReference} would resolve it, without reading the
|
|
65
|
+
* bytes: its MIME type and size, or undefined when there is no such file. An
|
|
66
|
+
* `asset:` reference with no active scenario names no file.
|
|
67
|
+
*
|
|
68
|
+
* A reference with none of the three prefixes, or a path escaping its
|
|
69
|
+
* directory, is a mistake rather than a missing file, so it throws as
|
|
70
|
+
* {@link readAssetByReference} does.
|
|
71
|
+
*/
|
|
72
|
+
export declare function describeAssetByReference(packagePath: string, scenarioRootDirectory: string | null, reference: string): Promise<AssetDescription | undefined>;
|
|
@@ -35,6 +35,13 @@ export declare function storeBlob(packagePath: string, data: Buffer, name: strin
|
|
|
35
35
|
* Throws if the blob does not exist.
|
|
36
36
|
*/
|
|
37
37
|
export declare function readBlob(packagePath: string, id: string): Promise<BlobData>;
|
|
38
|
+
/**
|
|
39
|
+
* A stored blob's metadata and size, read without its bytes, or undefined
|
|
40
|
+
* when the store holds no such blob.
|
|
41
|
+
*/
|
|
42
|
+
export declare function describeBlob(packagePath: string, id: string): Promise<(BlobMeta & {
|
|
43
|
+
size: number;
|
|
44
|
+
}) | undefined>;
|
|
38
45
|
/**
|
|
39
46
|
* Delete every blob held under one of `retentions` (§16.2). A deleted blob is
|
|
40
47
|
* read as an unknown one: {@link readBlob} throws, and the asset route 404s.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { JSONSchema7, JSONSchema7Definition } from 'json-schema';
|
|
2
|
+
/**
|
|
3
|
+
* Local references in a resource's schema (§6.1, §6.1a): a `$ref` naming a
|
|
4
|
+
* part of the same schema, such as a subschema under `$defs` or
|
|
5
|
+
* `definitions`, so that one shape can be used in several places or contain
|
|
6
|
+
* itself. A reference resolves against the schema of the resource that holds
|
|
7
|
+
* it, never another file or another resource's schema.
|
|
8
|
+
*/
|
|
9
|
+
/** Whether `ref` names a part of the schema holding it: `#` or `#/...`. */
|
|
10
|
+
export declare function isLocalRef(ref: string): boolean;
|
|
11
|
+
/** The part of `root` a local `ref` names, or undefined when it names nothing. */
|
|
12
|
+
export declare function resolveLocalRef(root: JSONSchema7, ref: string): JSONSchema7Definition | undefined;
|
|
13
|
+
/**
|
|
14
|
+
* `schema` with its `$ref` followed, as many times as it takes, and the
|
|
15
|
+
* keywords written beside each reference kept over the target's: a
|
|
16
|
+
* `{ "$ref": "#/$defs/rule", "default": ... }` is the rule with that default.
|
|
17
|
+
* A reference that names nothing, or a chain that comes back on itself, stops
|
|
18
|
+
* where it is, without its `$ref`; the build refuses the first, and the
|
|
19
|
+
* second describes no value.
|
|
20
|
+
*/
|
|
21
|
+
export declare function dereference(root: JSONSchema7, schema: JSONSchema7): JSONSchema7;
|
|
22
|
+
/** Every subschema directly beneath `schema`, with its JSON pointer step. */
|
|
23
|
+
export declare function childSchemas(schema: JSONSchema7): {
|
|
24
|
+
step: string;
|
|
25
|
+
schema: JSONSchema7;
|
|
26
|
+
}[];
|
|
27
|
+
/** A `$ref` the build refuses, with the JSON pointer of the subschema carrying it. */
|
|
28
|
+
export interface RefProblem {
|
|
29
|
+
pointer: string;
|
|
30
|
+
ref: string;
|
|
31
|
+
reason: 'not-local' | 'unresolved';
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Every `$ref` in `schema` that is not local or names nothing in it, for the
|
|
35
|
+
* build to refuse: a runtime resolves references against the resource's own
|
|
36
|
+
* schema and nothing else (§6.1a), so either would leave a value unchecked.
|
|
37
|
+
*/
|
|
38
|
+
export declare function refProblems(schema: JSONSchema7): RefProblem[];
|
|
39
|
+
/** A {@link RefProblem} as a build error line. */
|
|
40
|
+
export declare function refProblemMessage(owner: string, keyword: string, problem: RefProblem): string;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { JSONSchema7 } from 'json-schema';
|
|
2
|
+
/**
|
|
3
|
+
* The subschemas a value under `key` of an object is held to: its entry in
|
|
4
|
+
* `properties`, every `patternProperties` schema whose pattern the key
|
|
5
|
+
* matches, and `additionalProperties` when it is a schema and neither of the
|
|
6
|
+
* others applies, as JSON Schema applies them. A keyed map, the shape a
|
|
7
|
+
* setting takes when scenarios add and remove its entries, is declared
|
|
8
|
+
* through the last two.
|
|
9
|
+
*/
|
|
10
|
+
export declare function memberSchemas(schema: JSONSchema7, key: string): JSONSchema7[];
|
|
11
|
+
/**
|
|
12
|
+
* Every subschema an object's members are declared by, with the step a path
|
|
13
|
+
* through it takes: the property's name, `*` for `additionalProperties`, or
|
|
14
|
+
* the pattern between slashes for a `patternProperties` entry.
|
|
15
|
+
*/
|
|
16
|
+
export declare function memberDeclarations(schema: JSONSchema7): {
|
|
17
|
+
step: string;
|
|
18
|
+
schema: JSONSchema7;
|
|
19
|
+
}[];
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seriousgaming/sdk-tools",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.0",
|
|
4
4
|
"description": "SDK tooling for building Serious Gaming games",
|
|
5
5
|
"homepage": "https://sdk.seriousgaming.com/",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
"@mui/icons-material": "^9.4.0",
|
|
71
71
|
"@mui/material": "^9.4.0",
|
|
72
72
|
"@playwright/test": "^1.64.0",
|
|
73
|
-
"@seriousgaming/sdk": "1.
|
|
73
|
+
"@seriousgaming/sdk": "1.4.0",
|
|
74
74
|
"@testing-library/jest-dom": "^7.0.1",
|
|
75
75
|
"@testing-library/react": "^16.3.3",
|
|
76
76
|
"@types/adm-zip": "^0.5.8",
|
|
@@ -99,7 +99,7 @@
|
|
|
99
99
|
"vitest": "^5.0.3"
|
|
100
100
|
},
|
|
101
101
|
"peerDependencies": {
|
|
102
|
-
"@seriousgaming/sdk": "^1.
|
|
102
|
+
"@seriousgaming/sdk": "^1.4.0"
|
|
103
103
|
},
|
|
104
104
|
"engines": {
|
|
105
105
|
"node": ">=24"
|