@seriousgaming/sdk-tools 1.3.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 (36) hide show
  1. package/dist/cli.js +3216 -2538
  2. package/dist/client.js +693 -161
  3. package/dist/core/session-host.d.ts +4 -2
  4. package/dist/core/settings-locks.d.ts +27 -2
  5. package/dist/dev/console/assets/{index-DEV8N0na.js → index-BvB-LFQZ.js} +10 -10
  6. package/dist/dev/console/index.html +1 -1
  7. package/dist/dev/routes.d.ts +4 -0
  8. package/dist/dev/view/batch.d.ts +7 -1
  9. package/dist/docs/api/index.md +1 -1
  10. package/dist/docs/api/sdk-tools-client.md +1 -0
  11. package/dist/docs/api/sdk.md +79 -2
  12. package/dist/docs/changelog.md +25 -0
  13. package/dist/docs/concepts/terminology.md +1 -1
  14. package/dist/docs/guides/capabilities.md +2 -0
  15. package/dist/docs/guides/endpoints.md +2 -2
  16. package/dist/docs/guides/engine-testing.md +1 -1
  17. package/dist/docs/guides/file-handling.md +113 -21
  18. package/dist/docs/guides/llm-integration.md +1 -1
  19. package/dist/docs/guides/scenario-editor.md +1 -1
  20. package/dist/docs/guides/scenarios.md +9 -1
  21. package/dist/docs/guides/settings.md +62 -2
  22. package/dist/docs/guides/validators.md +62 -4
  23. package/dist/docs/recipes/upload-and-display-files.md +7 -7
  24. package/dist/docs/recipes/validate-scenarios.md +4 -1
  25. package/dist/execution/endpoint-runner.d.ts +6 -0
  26. package/dist/execution/logic-calls.d.ts +7 -2
  27. package/dist/execution/scenario-gates.d.ts +21 -1
  28. package/dist/guide/settings.d.ts +1 -1
  29. package/dist/host.js +64 -2
  30. package/dist/runtime/manifest-version.d.ts +1 -1
  31. package/dist/runtime.js +7 -2
  32. package/dist/storage/asset-resolver.d.ts +24 -1
  33. package/dist/storage/blob-store.d.ts +7 -0
  34. package/dist/utils/local-refs.d.ts +40 -0
  35. package/dist/utils/schema-members.d.ts +19 -0
  36. package/package.json +3 -3
@@ -62,7 +62,7 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
62
62
  }
63
63
  ```
64
64
 
65
- `settingsSchema` is a full JSON Schema Draft 7 object. Two rules are stricter than for a capability's `variablesSchema`:
65
+ `settingsSchema` is a full JSON Schema Draft 7 object, as every schema a game writes is, read the same way whatever `$schema` it names. Two features of later drafts also work: `$defs` beside `definitions`, and keywords written beside a `$ref` (see [Reuse a shape](#reuse-a-shape-or-nest-it-to-any-depth)). Two rules are stricter than for a capability's `variablesSchema`:
66
66
 
67
67
  - Every property needs a `default`. `new settings`, `update settings` and `sdk build` all refuse a property without one
68
68
  - Every default must fit its own schema, at any depth. `sdk build` refuses a string default on a number property, a default outside its range or `enum`, and an object default missing a key its own `required` lists, naming the settings resource and the path. The generated `Settings` type comes from the schema, so the compiler cannot catch a default that disagrees with it
@@ -70,6 +70,43 @@ Run `pnpm run sdk new settings` with no JSON to be prompted for each property in
70
70
 
71
71
  A `required` inside an object-valued property is allowed. It holds the property's `default` to its keys, never a scenario or a setup change: those are partial at every depth, so a scenario or a setup UI may set one key of the object and leave the rest to the layer beneath. An array is the exception: it replaces the one beneath whole, so each item an override supplies must be complete.
72
72
 
73
+ ### Reuse a shape, or nest it to any depth
74
+
75
+ Declare a shape once under `$defs` (or `definitions`) and use it with a `$ref`. A shape may contain itself, which is how recursive data, such as a running order whose items hold items or a rule whose branches are rules, is checked to every depth rather than left as a bare object below the first level:
76
+
77
+ ```json
78
+ "settingsSchema": {
79
+ "type": "object",
80
+ "properties": {
81
+ "Agenda": {
82
+ "title": "Agenda",
83
+ "$ref": "#/$defs/agendaItem",
84
+ "default": { "title": "Workshop", "children": [] }
85
+ }
86
+ },
87
+ "$defs": {
88
+ "agendaItem": {
89
+ "type": "object",
90
+ "properties": {
91
+ "title": { "type": "string" },
92
+ "children": { "type": "array", "items": { "$ref": "#/$defs/agendaItem" } }
93
+ },
94
+ "required": ["title", "children"],
95
+ "additionalProperties": false
96
+ }
97
+ },
98
+ "additionalProperties": false
99
+ }
100
+ ```
101
+
102
+ - **A reference stays inside its own schema.** It names a part of the settings resource that holds it, as `#/$defs/<name>`. The build refuses one that names nothing, another file, a URL or another resource's schema, pointing at it
103
+ - **Write the `default` beside the `$ref`.** Keywords beside a reference apply with it, so the property's `default`, `title` and `description` go there, and so does a constraint for this use alone, such as a `maximum`
104
+ - **Every check follows it.** The defaults, scenarios, setup and scenario editor writes, [file settings](#settings-that-hold-a-file), [locks](#lock-a-setting) and [guide conditions](./guide.md) all reach through a reference, at every depth
105
+ - **Each use keeps its own rule.** Where the shape is an object setting, a scenario may set one key of it and leave the rest; where it is an array's item, each item must be complete
106
+ - **The generated types name it.** `Agenda` is typed `AgendaItem`, one interface whose `children` are `AgendaItem[]`, exported from `types.ts` for your own code. When two resources a file reads both define the same name, the second is prefixed with its identifier (`EngineRule`)
107
+
108
+ A capability's `variablesSchema` takes `$defs` and `$ref` the same way.
109
+
73
110
  ### Describe every setting
74
111
 
75
112
  A settings schema is read by more than the build. A hosted runtime's generic settings form, a [scenario editor](./scenario-editor.md), and an AI agent authoring a scenario for your released game all work from it, and an agent can edit a game with no editor UI at all if the schema says what each value means. Give every property:
@@ -112,6 +149,8 @@ Some values are part of the game's design rather than something to tune: a const
112
149
  - **Nothing can change a locked value.** The build refuses a scenario that sets it, with `SETTINGS_LOCKED` pointing at the value, even when it sets the same value as your default. A setup screen or scenario editor that changes it is refused as `denied`, with a message naming the setting (`"engine.LowProductionThreshold" is read-only`), and none of that write applies
113
150
  - **Sending it back unchanged is fine.** An editor that spreads the settings it was given sends the locked value back as it was, and only what changed is applied, so spreading is still safe
114
151
  - **Locking an object locks everything in it.** `readOnly` on an object-valued property fixes every key inside it, at any depth
152
+ - **Lock named properties, or a whole list or map.** A list's items and a map's entries come and go as scenarios add and remove them, so there is no single value of yours for a lock inside one to keep. The build refuses `readOnly` beneath `items`, `additionalProperties` or `patternProperties`; put it on the list or map itself instead
153
+ - **A lock reached through a `$ref` counts.** `readOnly` on a shape under `$defs` locks every named property that uses it (see [Reuse a shape, or nest it to any depth](#reuse-a-shape-or-nest-it-to-any-depth))
115
154
  - **Saving a scenario leaves locked values out.** The dev console's Save writes every other setting and drops the locked ones, so the scenario still builds
116
155
  - **Editors are not sent the schema.** A setup screen or scenario editor receives the values, not the schema, so show a locked field as read-only yourself, as the factory example's scenario editor does
117
156
  - **Adding a lock is a scenario-format change.** A custom scenario saved before the lock may hold a value for it, so bump `scenarioFormat` when you lock a setting a released version left open (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it))
@@ -136,6 +175,27 @@ A setting can hold a file, such as a client's logo or a briefing document. Mark
136
175
  - **The build checks your files.** Every file a package scenario or a default names must be shipped, within `maxBytes`, and of a type `accept` lists, judged from its extension. A `blob:` reference in a package scenario fails the build: it is an upload, which no package can carry
137
176
  - **Every write is checked against it.** A setup screen, the scenario editor or an agent sets a file by uploading it first and writing the `blob:` reference it gets back. A reference to a file nobody uploaded, or one too large or of the wrong type, is refused as `denied`, naming the setting. So is anything that is not a reference, a `data:` URI or a URL included
138
177
  - **It tells an agent what to upload.** A schema alone says only that the value is a string; `blob` says it is a PNG of up to 512 KB
178
+ - **A map can hold a file per key.** Put `blob` on a map's `additionalProperties` (or a `patternProperties` schema), and every entry is a file setting of its own, checked and named by its key (`brand.Cast.ada`, see [How a setting is named](#how-a-setting-is-named)). A file per language is one such map (see [A file per language](./file-handling.md#a-file-per-language))
179
+
180
+ ### How a setting is named
181
+
182
+ A refusal, a lock's message, a `Scenario` gate's problem and a guide's `:setting` all name one value by its setting path: the settings identifier, then each key down to the value.
183
+
184
+ ```text
185
+ ui.MinPrice
186
+ brand.Cast.ada.portrait
187
+ engine.Rounds.0.Price
188
+ brand.Cast["a.b"].portrait
189
+ ```
190
+
191
+ A plain key, one that is not empty and holds no `.`, `[`, `]`, `"` or space, follows a dot, and so does a list's position. Any other key, such as a map entry named `a.b`, goes in brackets as a JSON string, so the path reads back one way only. Build and read paths with `settingPath` and `parseSettingPath` from `@seriousgaming/sdk` rather than joining keys yourself:
192
+
193
+ ```typescript
194
+ import { parseSettingPath, settingPath } from '@seriousgaming/sdk';
195
+
196
+ settingPath('brand', 'Cast', 'a.b', 'portrait'); // 'brand.Cast["a.b"].portrait'
197
+ parseSettingPath('brand.Cast["a.b"].portrait'); // { identifier: 'brand', keys: ['Cast', 'a.b', 'portrait'] }
198
+ ```
139
199
 
140
200
  ### How to divide settings
141
201
 
@@ -402,7 +462,7 @@ Options:
402
462
  Every override source is validated against the `settingsSchema` of the settings resource it names, scenario overrides and session overrides alike. Neither has to name every property, but both are refused for:
403
463
 
404
464
  - A key naming no settings resource the package declares
405
- - A property the schema does not declare, such as a misspelling
465
+ - A property the schema does not declare, such as a misspelling. An object that lists `properties` and says nothing else of its keys refuses any key it does not list, whether or not it sets `additionalProperties: false`. A bare `{ "type": "object" }`, or an object with `patternProperties`, an `additionalProperties` schema or `allOf`/`anyOf`/`oneOf`, takes whatever its schema admits, so an object meant to hold any keys, such as a map of triggers, is written that way
406
466
  - A value of the wrong type, or outside a `minimum`, `maximum` or `enum`
407
467
  - A value the schema locks with `readOnly` (see [Lock a setting](#lock-a-setting))
408
468
 
@@ -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
 
@@ -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;
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.3";
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.3";
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);
@@ -312,7 +315,9 @@ var SUPPORTED_FEATURES = [
312
315
  // A validator's `Scenario` gate (§15.8).
313
316
  "scenario-validation",
314
317
  // The presentation as a host overlay a session surface may open (§6.4).
315
- "presentation-overlay"
318
+ "presentation-overlay",
319
+ // File reads in a validator's `Scenario` gate (§15.8).
320
+ "scenario-files"
316
321
  ];
317
322
  function unsupportedFeatures(manifest) {
318
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.3.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.3.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.3.0"
102
+ "@seriousgaming/sdk": "^1.4.0"
103
103
  },
104
104
  "engines": {
105
105
  "node": ">=24"