@seriousgaming/sdk-tools 1.0.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.
Files changed (167) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20161 -5495
  17. package/dist/client.js +15737 -1151
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +230 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
  27. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +185 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +85 -4
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +98 -6
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +3 -10
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +32 -36
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +208 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +13 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +4 -4
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +74 -0
  124. package/dist/guide/video-registry.d.ts +33 -1
  125. package/dist/host/host-channel.d.ts +11 -2
  126. package/dist/host/index.d.ts +9 -1
  127. package/dist/host/protocol.d.ts +49 -5
  128. package/dist/host/theme.d.ts +28 -2
  129. package/dist/host.js +11621 -15
  130. package/dist/runtime/index.d.ts +1 -1
  131. package/dist/runtime/manifest-version.d.ts +17 -0
  132. package/dist/runtime.js +12 -1
  133. package/dist/schema.json +32 -4
  134. package/dist/storage/blob-store.d.ts +3 -2
  135. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  136. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  137. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  138. package/dist/templates/package/CLAUDE.md.template +5 -2
  139. package/dist/templates/package/README.md.liquid +2 -0
  140. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  141. package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
  142. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  143. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  144. package/dist/templates/session/src/theme.ts.liquid +26 -33
  145. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  146. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  147. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  148. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  149. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  151. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  152. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  153. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  154. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  155. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  156. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  157. package/dist/templates/validator/logic.ts.liquid +4 -0
  158. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  159. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  160. package/dist/utils/error-codes.d.ts +15 -3
  161. package/dist/validation/ajv.d.ts +9 -5
  162. package/dist/validation/facilitator-guide-validator.d.ts +11 -1
  163. package/dist/validation/file-settings.d.ts +49 -0
  164. package/dist/validation/guide-settings-validator.d.ts +26 -0
  165. package/dist/validation/schema-validation.d.ts +12 -4
  166. package/package.json +6 -5
  167. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -9,9 +9,13 @@ import Ajv from 'ajv';
9
9
  *
10
10
  * Two keywords are registered, each of which would otherwise fail strict mode
11
11
  * as unknown. `tsType` names the TypeScript type a capability property
12
- * generates to (#601) and constrains nothing at run time. `blob` marks an
13
- * endpoint request field as a file (§6.12): by the time the schema sees the
14
- * request the runtime has resolved every such field to a `blob:` reference,
15
- * so the keyword holds it to that.
12
+ * generates to (#601) and constrains nothing at run time. `blob` marks a
13
+ * string as a file. On an endpoint request (§6.12) the runtime has resolved
14
+ * every such field to a `blob:` reference by the time the schema sees it, so
15
+ * the keyword holds it to that. A setting holding a file (§6.1a) is an asset
16
+ * reference of any kind, or empty for none, which `fileValues: 'reference'`
17
+ * admits instead.
16
18
  */
17
- export declare function createAjv(): Ajv;
19
+ export declare function createAjv(fileValues?: 'resolved' | 'reference'): Ajv;
20
+ /** A file setting's value (§6.1a): empty for no file, or an asset reference. */
21
+ export declare function isFileSettingValue(value: string): boolean;
@@ -1,5 +1,6 @@
1
1
  import type { FacilitatorGuideDefinition } from '@seriousgaming/sdk';
2
2
  import { referenceLocale } from '../guide/locale.js';
3
+ import { type GuideSettingsContext } from './guide-settings-validator.js';
3
4
  /**
4
5
  * Facilitator guide content validation.
5
6
  *
@@ -7,9 +8,14 @@ import { referenceLocale } from '../guide/locale.js';
7
8
  * - Locale completeness: each declared locale should mirror the reference
8
9
  * locale's chapter file set (warnings — fallback handles gaps at runtime)
9
10
  * - Video blocks: provider and parameters must validate against the closed
10
- * 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
11
14
  * - Referenced assets: relative image references must resolve to a file
12
15
  * inside the guide directory (errors)
16
+ * - Settings: every `:setting` and `:::when` names a value the guide declares
17
+ * and can show or compare (errors), and no chapter is hidden everywhere
18
+ * (warnings); see `guide-settings-validator.ts`
13
19
  *
14
20
  * This is the **semantic / content** layer (the `validation/` directory); the
15
21
  * schema-level bundle-shape check is `validateSDKFacilitatorGuide` in
@@ -19,9 +25,13 @@ export interface GuideContentValidationResult {
19
25
  errors: string[];
20
26
  warnings: string[];
21
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;
22
30
  export { referenceLocale };
23
31
  export declare function validateFacilitatorGuideContent(options: {
24
32
  definition: FacilitatorGuideDefinition;
25
33
  /** Absolute path to the guide's root directory */
26
34
  rootDirectory: string;
35
+ /** The package's settings schemas and scenarios, to check the guide's use of settings against. */
36
+ settings?: Omit<GuideSettingsContext, 'declared'>;
27
37
  }): GuideContentValidationResult;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Settings that hold a file (§6.1a).
3
+ *
4
+ * A string property of a `settingsSchema` carrying the `blob` keyword an
5
+ * endpoint request uses says what file it expects:
6
+ *
7
+ * "BrandingLogo": { "type": "string", "default": "", "blob": { "accept": ["image/*"] } }
8
+ *
9
+ * Its value is an asset reference, `asset:`, `shared:` or `blob:`, or the
10
+ * empty string for no file. The declaration is checked twice over: the build
11
+ * holds the keyword to its shape and every file a package scenario or a
12
+ * default names to it, and the runtime holds every `blob:` value written to
13
+ * it, since neither the schema, which sees a string, nor a `Scenario` gate,
14
+ * which opens no file, can.
15
+ */
16
+ import type { JSONSchema7 } from 'json-schema';
17
+ import type { BlobRetention } from '../storage/blob-store';
18
+ import type { SettingsSchemas } from './schema-validation';
19
+ /** A stored file's type and size, or undefined when there is none. */
20
+ export type DescribeFile = (reference: string) => Promise<{
21
+ mimeType: string;
22
+ size: number;
23
+ retention?: BlobRetention;
24
+ } | undefined>;
25
+ /**
26
+ * The build's check of a settings resource's file declarations (§6.1a): each
27
+ * on a string, well formed, and defaulting to no file or a `shared:` one. A
28
+ * default is resolved with no scenario active, so an `asset:` default could
29
+ * never resolve.
30
+ */
31
+ export declare function fileSettingDeclarationErrors(identifier: string, settingsSchema: JSONSchema7): string[];
32
+ /**
33
+ * The build's check of the files a package scenario, or the defaults, set
34
+ * (§6.1a): each shipped, within `maxBytes`, and of a type `accept` lists,
35
+ * judged from its file extension. A `blob:` reference is an upload, which no
36
+ * package can carry. `resolve` answers for `asset:` and `shared:` references;
37
+ * `skip` leaves out a reference another check already refuses.
38
+ */
39
+ export declare function packageFileSettingErrors(owner: string, settings: Record<string, unknown>, schemas: SettingsSchemas, resolve: DescribeFile, skip?: (reference: string) => boolean): Promise<string[]>;
40
+ /**
41
+ * The runtime's check of a write to file settings (§6.1a): each `blob:` value
42
+ * names a stored blob whose type and size meet the declaration, and on a
43
+ * scenario draft one the draft can read. A value of
44
+ * any other form never gets this far, since the schema refuses one that is
45
+ * neither empty nor a reference.
46
+ */
47
+ export declare function fileSettingWriteErrors(overrides: Record<string, unknown>, schemas: SettingsSchemas, describeBlob: DescribeFile, options?: {
48
+ draft?: boolean;
49
+ }): Promise<string[]>;
@@ -0,0 +1,26 @@
1
+ import type { JSONSchema7 } from 'json-schema';
2
+ /**
3
+ * The build's checks on settings in guide markdown (§6.13.5): every
4
+ * `:setting` and `:::when` names a value the guide declares and can show or
5
+ * compare, the grammar is used as defined, and no chapter is hidden in every
6
+ * scenario the package ships.
7
+ */
8
+ /** One chapter's markdown, labelled as the build reports it (`content/en/01-overview.md`). */
9
+ export interface GuideChapter {
10
+ label: string;
11
+ markdown: string;
12
+ /** Whether this is the reference locale's file, which decides whether a chapter shows. */
13
+ reference: boolean;
14
+ }
15
+ export interface GuideSettingsContext {
16
+ /** The settings identifiers the guide declares. */
17
+ declared: string[];
18
+ /** Every settings resource's schema, by identifier. */
19
+ schemas: Record<string, JSONSchema7>;
20
+ /** Each package scenario's settings overrides, by scenario identifier. */
21
+ scenarios: Record<string, Record<string, Record<string, unknown>>>;
22
+ }
23
+ export declare function validateGuideSettings(chapters: GuideChapter[], context: GuideSettingsContext): {
24
+ errors: string[];
25
+ warnings: string[];
26
+ };
@@ -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.0.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",
@@ -40,10 +40,12 @@
40
40
  "types": "./dist/runtime/index.d.ts",
41
41
  "default": "./dist/runtime.js"
42
42
  },
43
- "./schema.json": "./dist/schema.json"
43
+ "./schema.json": "./dist/schema.json",
44
+ "./package.json": "./package.json"
44
45
  },
45
46
  "dependencies": {
46
47
  "@inquirer/prompts": "^8.7.3",
48
+ "@types/mdast": "^4.0.4",
47
49
  "@vitejs/plugin-react": "^6.1.2",
48
50
  "adm-zip": "^0.6.1",
49
51
  "ajv": "^8.20.0",
@@ -68,14 +70,13 @@
68
70
  "@mui/icons-material": "^9.4.0",
69
71
  "@mui/material": "^9.4.0",
70
72
  "@playwright/test": "^1.64.0",
71
- "@seriousgaming/sdk": "1.0.0",
73
+ "@seriousgaming/sdk": "1.2.0",
72
74
  "@testing-library/jest-dom": "^7.0.1",
73
75
  "@testing-library/react": "^16.3.3",
74
76
  "@types/adm-zip": "^0.5.8",
75
77
  "@types/express": "^5.0.6",
76
78
  "@types/hast": "^3.0.5",
77
79
  "@types/json-schema": "^7.0.15",
78
- "@types/mdast": "^4.0.4",
79
80
  "@types/node": "^24.19.1",
80
81
  "@types/react": "^19.3.0",
81
82
  "@types/react-dom": "^19.3.0",
@@ -98,7 +99,7 @@
98
99
  "vitest": "^5.0.3"
99
100
  },
100
101
  "peerDependencies": {
101
- "@seriousgaming/sdk": "^1.0.0"
102
+ "@seriousgaming/sdk": "^1.2.0"
102
103
  },
103
104
  "engines": {
104
105
  "node": ">=24"