@seriousgaming/sdk-tools 1.0.0 → 1.1.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 (165) 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 +20003 -5523
  17. package/dist/client.js +15534 -1134
  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 +213 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  27. package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -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 +166 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +60 -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 +64 -3
  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 +2 -9
  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 +29 -35
  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 +194 -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 +5 -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 +2 -2
  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 +67 -0
  124. package/dist/host/host-channel.d.ts +11 -2
  125. package/dist/host/index.d.ts +7 -1
  126. package/dist/host/protocol.d.ts +49 -5
  127. package/dist/host/theme.d.ts +28 -2
  128. package/dist/host.js +11490 -15
  129. package/dist/runtime/index.d.ts +1 -1
  130. package/dist/runtime/manifest-version.d.ts +17 -0
  131. package/dist/runtime.js +12 -1
  132. package/dist/schema.json +32 -4
  133. package/dist/storage/blob-store.d.ts +3 -2
  134. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  135. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  136. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  137. package/dist/templates/package/CLAUDE.md.template +5 -2
  138. package/dist/templates/package/README.md.liquid +2 -0
  139. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  140. package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
  141. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  142. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  143. package/dist/templates/session/src/theme.ts.liquid +26 -33
  144. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  145. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  146. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  147. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  148. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  149. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  151. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  152. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  153. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  154. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  155. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  156. package/dist/templates/validator/logic.ts.liquid +4 -0
  157. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  158. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  159. package/dist/utils/error-codes.d.ts +15 -3
  160. package/dist/validation/ajv.d.ts +9 -5
  161. package/dist/validation/facilitator-guide-validator.d.ts +6 -0
  162. package/dist/validation/file-settings.d.ts +49 -0
  163. package/dist/validation/guide-settings-validator.d.ts +26 -0
  164. package/package.json +6 -5
  165. 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
  *
@@ -10,6 +11,9 @@ import { referenceLocale } from '../guide/locale.js';
10
11
  * provider registry (errors — these render as inert error blocks)
11
12
  * - Referenced assets: relative image references must resolve to a file
12
13
  * inside the guide directory (errors)
14
+ * - Settings: every `:setting` and `:::when` names a value the guide declares
15
+ * and can show or compare (errors), and no chapter is hidden everywhere
16
+ * (warnings); see `guide-settings-validator.ts`
13
17
  *
14
18
  * This is the **semantic / content** layer (the `validation/` directory); the
15
19
  * schema-level bundle-shape check is `validateSDKFacilitatorGuide` in
@@ -24,4 +28,6 @@ export declare function validateFacilitatorGuideContent(options: {
24
28
  definition: FacilitatorGuideDefinition;
25
29
  /** Absolute path to the guide's root directory */
26
30
  rootDirectory: string;
31
+ /** The package's settings schemas and scenarios, to check the guide's use of settings against. */
32
+ settings?: Omit<GuideSettingsContext, 'declared'>;
27
33
  }): 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
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seriousgaming/sdk-tools",
3
- "version": "1.0.0",
3
+ "version": "1.1.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.1.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.1.0"
102
103
  },
103
104
  "engines": {
104
105
  "node": ">=24"