@seriousgaming/sdk-tools 1.1.0 → 1.2.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.
@@ -15,19 +15,25 @@ Facilitator guides are content, not code: per-locale markdown chapters plus shar
15
15
  ```
16
16
  2. **Create or change the guide.** The starter game already has one, so edit its chapters directly and change its bundle with `pnpm run sdk update guide`; `new guide` refuses while `guide/` exists. In an empty package, `pnpm run sdk new guide '{ ... }'`. Declare every locale up front: the scaffold creates a chapter skeleton per declared locale, and the per-locale `name` is the title the host renders.
17
17
  3. **Write the chapters** in `guide/content/<locale>/`. Chapters are ordered by file name (number them `01-`, `02-`, …) and file names must be identical across locales.
18
- 4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks or image references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
18
+ 4. **Validate**: `pnpm run sdk build --validate-only`. This warns on missing translations and fails on malformed video blocks, or image or video references that do not resolve. There is nothing to wire: a `guide/` directory beside `seriousgaming.sdk.json` is served.
19
19
 
20
20
  ## Content format
21
21
 
22
22
  - Admonitions are container directives: `:::note`, `:::warning`, `:::tip`, plus the facilitation-specific `:::say`, `:::do`, and `:::timing`. Unknown types render as error blocks
23
23
  - Headings build the table of contents (chapter H1 plus H2 to H3); end a heading with `{-}` to omit it
24
24
  - Images go in the shared `assets/` directory, referenced relatively (`../../assets/diagram.png` from a chapter)
25
- - Video embeds are fenced `video` blocks validated against a closed registry (YouTube only):
25
+ - Video embeds are fenced `video` blocks validated against a closed registry: `youtube` with an `id`, or `file` with a `src` in `assets/` (and optionally `title`, `poster` and `captions`):
26
26
  ````markdown
27
27
  ```video
28
28
  provider: youtube
29
29
  id: dQw4w9WgXcQ
30
30
  ```
31
+
32
+ ```video
33
+ provider: file
34
+ src: ../../assets/intro.mp4
35
+ title: How a round runs
36
+ ```
31
37
  ````
32
38
  - A chapter can follow the session's settings: list the settings resources the guide reads in `guide.sdk.json`'s `settings`, show a value with `:setting[engine.totalWeeks]`, and show a block only in some scenarios with `:::when{setting="engine.observers"}` (`is="…"` to compare, `not` to invert). The build checks every name and value. See `recipes/make-a-guide-follow-the-scenario.md`
33
39
  - Raw HTML never renders: it is escaped to visible text. Use markdown, admonitions, and video blocks only
@@ -8,7 +8,9 @@ import { type GuideSettingsContext } from './guide-settings-validator.js';
8
8
  * - Locale completeness: each declared locale should mirror the reference
9
9
  * locale's chapter file set (warnings — fallback handles gaps at runtime)
10
10
  * - Video blocks: provider and parameters must validate against the closed
11
- * provider registry (errors — these render as inert error blocks)
11
+ * provider registry (errors — these render as inert error blocks), and each
12
+ * file a `file` video names must exist in `assets/` (errors), warning above
13
+ * a size threshold
12
14
  * - Referenced assets: relative image references must resolve to a file
13
15
  * inside the guide directory (errors)
14
16
  * - Settings: every `:setting` and `:::when` names a value the guide declares
@@ -23,6 +25,8 @@ export interface GuideContentValidationResult {
23
25
  errors: string[];
24
26
  warnings: string[];
25
27
  }
28
+ /** Above this a video file slows every upload of the package enough to say so. */
29
+ export declare const LARGE_VIDEO_FILE_BYTES: number;
26
30
  export { referenceLocale };
27
31
  export declare function validateFacilitatorGuideContent(options: {
28
32
  definition: FacilitatorGuideDefinition;
@@ -1,5 +1,5 @@
1
1
  import type { ErrorObject } from 'ajv';
2
- import type { JSONSchema7 } from 'json-schema';
2
+ import type { JSONSchema7, JSONSchema7Definition } from 'json-schema';
3
3
  import { type Finding } from './findings.js';
4
4
  /**
5
5
  * Validation result
@@ -108,8 +108,16 @@ export declare function validateSettingsOverrides(overrides: Record<string, unkn
108
108
  * through (see {@link withoutRequired}), even against a schema still carrying
109
109
  * the top-level `required` that `sdk build` rejects: faulting partial
110
110
  * overrides on it is how #389 broke every scenario, and on a nested one how
111
- * #682 broke a setup UI that spread an object. `additionalProperties` (false
112
- * by convention) still rejects undeclared keys, and type and value checks
113
- * still apply to the keys that are present.
111
+ * #682 broke a setup UI that spread an object. An undeclared key is
112
+ * refused even where the schema leaves its object open (see
113
+ * {@link closed}), and type and value checks still apply to the keys that
114
+ * are present.
114
115
  */
115
116
  export declare function validatePartialOverride(override: unknown, settingsSchema: JSONSchema7): ErrorObject[] | null;
117
+ /**
118
+ * Where a settings schema leaves a plain object open, as JSON pointers into
119
+ * the schema (`''` for the top level), for the build to warn about. Each is
120
+ * closed all the same when an override is checked (see {@link closed}), but a
121
+ * runtime or an agent reading the schema would not know it.
122
+ */
123
+ export declare function openSettingsObjects(schema: JSONSchema7Definition, at?: string): string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seriousgaming/sdk-tools",
3
- "version": "1.1.0",
3
+ "version": "1.2.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.1.0",
73
+ "@seriousgaming/sdk": "1.2.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.1.0"
102
+ "@seriousgaming/sdk": "^1.2.0"
103
103
  },
104
104
  "engines": {
105
105
  "node": ">=24"