@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.
Files changed (50) hide show
  1. package/dist/cli.js +3582 -2834
  2. package/dist/client.js +1145 -543
  3. package/dist/core/participant-registry.d.ts +6 -0
  4. package/dist/core/session-host.d.ts +4 -2
  5. package/dist/core/session-roster.d.ts +4 -1
  6. package/dist/core/settings-locks.d.ts +27 -2
  7. package/dist/dev/console/assets/{index-BNLEVOQA.js → index-BvB-LFQZ.js} +47 -47
  8. package/dist/dev/console/index.html +1 -1
  9. package/dist/dev/routes.d.ts +4 -0
  10. package/dist/dev/view/batch.d.ts +24 -10
  11. package/dist/dev/view/view.d.ts +2 -1
  12. package/dist/docs/api/index.md +2 -2
  13. package/dist/docs/api/sdk-commands.md +4 -0
  14. package/dist/docs/api/sdk-e2e.md +4 -0
  15. package/dist/docs/api/sdk-tools-client.md +5 -0
  16. package/dist/docs/api/sdk-ui-testing.md +1 -0
  17. package/dist/docs/api/sdk-ui.md +33 -1
  18. package/dist/docs/api/sdk.md +82 -3
  19. package/dist/docs/changelog.md +41 -0
  20. package/dist/docs/concepts/terminology.md +1 -1
  21. package/dist/docs/guides/capabilities.md +2 -0
  22. package/dist/docs/guides/endpoints.md +2 -2
  23. package/dist/docs/guides/engine-testing.md +1 -1
  24. package/dist/docs/guides/file-handling.md +113 -21
  25. package/dist/docs/guides/llm-integration.md +1 -1
  26. package/dist/docs/guides/presentation.md +23 -9
  27. package/dist/docs/guides/scenario-editor.md +1 -1
  28. package/dist/docs/guides/scenarios.md +9 -1
  29. package/dist/docs/guides/session.md +47 -8
  30. package/dist/docs/guides/settings.md +62 -2
  31. package/dist/docs/guides/testing.md +9 -0
  32. package/dist/docs/guides/ui.md +33 -0
  33. package/dist/docs/guides/upgrading.md +11 -0
  34. package/dist/docs/guides/validators.md +62 -4
  35. package/dist/docs/guides/waiting-room.md +2 -0
  36. package/dist/docs/recipes/upload-and-display-files.md +7 -7
  37. package/dist/docs/recipes/validate-scenarios.md +4 -1
  38. package/dist/execution/endpoint-runner.d.ts +6 -0
  39. package/dist/execution/logic-calls.d.ts +7 -2
  40. package/dist/execution/scenario-gates.d.ts +21 -1
  41. package/dist/guide/settings.d.ts +1 -1
  42. package/dist/host/protocol.d.ts +27 -2
  43. package/dist/host.js +64 -2
  44. package/dist/runtime/manifest-version.d.ts +1 -1
  45. package/dist/runtime.js +9 -2
  46. package/dist/storage/asset-resolver.d.ts +24 -1
  47. package/dist/storage/blob-store.d.ts +7 -0
  48. package/dist/utils/local-refs.d.ts +40 -0
  49. package/dist/utils/schema-members.d.ts +19 -0
  50. 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 as a dotted `path`; an empty array passes:
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.MinPrice',
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.ClientName',
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`, `meta` or callbacks: there is no session or participant behind a scenario. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
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 [Supported file types](../guides/file-handling.md#supported-file-types) |
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, blobRetention?: BlobRetention): SignatureCallbacks;
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 { ResolvedPackageManifest, ScenarioProblem } from '@seriousgaming/sdk';
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[];
@@ -35,7 +35,7 @@ type Lookup = {
35
35
  } | {
36
36
  found: false;
37
37
  };
38
- /** The value at `identifier.key.key…` in resolved settings. */
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;
@@ -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
- * takes none: a game holds one guide, and a `target` is ignored. An overlay
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 [identifier, ...keys] = path2.split(".");
11944
- if (!identifier || keys.length === 0 || !(identifier in settings)) return { found: false };
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.2";
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.2";
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 implementation.
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.2.0",
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.2.0",
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.2.0"
102
+ "@seriousgaming/sdk": "^1.4.0"
103
103
  },
104
104
  "engines": {
105
105
  "node": ">=24"