@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
@@ -56,6 +56,13 @@ export declare const UI_PROTOCOL_VERSION = 4;
56
56
  export type IFrameMessage = {
57
57
  type: 'ready';
58
58
  protocolVersion: number;
59
+ /**
60
+ * The surface will send `rendered` once its first paint is on screen, so a
61
+ * host may keep its own loading screen over the frame until then (§12.5).
62
+ * Absent from a surface built before the signal existed, which a host shows
63
+ * as soon as it connects, as it always did.
64
+ */
65
+ signalsRendered?: true;
59
66
  };
60
67
  /**
61
68
  * Window-level message: host → iframe. Carries port2 as a transfer.
@@ -133,6 +140,19 @@ export type HostPortMessage = {
133
140
  | {
134
141
  type: 'setRunKind';
135
142
  runKind: RunKind;
143
+ }
144
+ /**
145
+ * The active scenario's name in the session locale, or `null` when the
146
+ * session runs on the game's own settings. For display only (§6.15.1).
147
+ * Sent in the initial batch and again whenever it changes, with a locale
148
+ * change or a scenario switch.
149
+ *
150
+ * The wrapper's `null` default is a fallback for a host predating this
151
+ * message, which a surface already has to render (§12.3).
152
+ */
153
+ | {
154
+ type: 'setScenarioName';
155
+ scenarioName: string | null;
136
156
  } | {
137
157
  type: 'setTimer';
138
158
  payload: TimerState;
@@ -253,6 +273,10 @@ export type HostPortMessage = {
253
273
  /** Port messages sent from game UI iframe to host */
254
274
  export type IFramePortMessage = {
255
275
  type: 'pong';
276
+ }
277
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
278
+ | {
279
+ type: 'rendered';
256
280
  } | {
257
281
  type: 'updateData';
258
282
  requestId?: string;
@@ -383,6 +407,14 @@ export type HostSessionPortMessage = {
383
407
  type: 'setRunKind';
384
408
  runKind: RunKind;
385
409
  }
410
+ /**
411
+ * The active scenario's name in the session locale, or `null`. For
412
+ * display only (§6.15.1); sent as a game UI's is.
413
+ */
414
+ | {
415
+ type: 'setScenarioName';
416
+ scenarioName: string | null;
417
+ }
386
418
  /**
387
419
  * Where to open the walkthrough run (§5.7). Every host offers one, so this
388
420
  * always carries a link. Facilitator-only, and naming no team: a
@@ -473,6 +505,10 @@ export type HostSessionPortMessage = {
473
505
  /** Port messages sent from session UI iframe to host */
474
506
  export type IFrameSessionPortMessage = {
475
507
  type: 'pong';
508
+ }
509
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
510
+ | {
511
+ type: 'rendered';
476
512
  } | {
477
513
  type: 'updateSessionData';
478
514
  requestId?: string;
@@ -579,11 +615,11 @@ export type IFrameSessionPortMessage = {
579
615
  }
580
616
  /**
581
617
  * Ask the host to open one of its own overlays (§6.4). The host renders it;
582
- * this delegates the trigger alone. `target` is the overlay's argument — a
583
- * guide identifier for `facilitator-guide`, a team id for `print-sheets` —
584
- * and omitting it means the whole thing (the first declared guide, every
585
- * team). An overlay the host does not offer, or a `target` the active game
586
- * does not declare, settles as denied.
618
+ * this delegates the trigger alone. `target` is a team id for
619
+ * `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
621
+ * the host does not offer, or a team id not in the session, settles as
622
+ * denied.
587
623
  */
588
624
  | {
589
625
  type: 'openHostOverlay';
@@ -686,6 +722,10 @@ export type HostSettingsEditorPortMessage = {
686
722
  */
687
723
  export type IFrameSettingsEditorPortMessage = {
688
724
  type: 'pong';
725
+ }
726
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
727
+ | {
728
+ type: 'rendered';
689
729
  } | {
690
730
  type: 'updateSettings';
691
731
  requestId?: string;
@@ -767,6 +807,10 @@ export type HostPresentationPortMessage = {
767
807
  /** Port messages sent from presentation iframe to host. Reads only. */
768
808
  export type IFramePresentationPortMessage = {
769
809
  type: 'pong';
810
+ }
811
+ /** First paint is on screen, after the handshake that announced it (§12.5). */
812
+ | {
813
+ type: 'rendered';
770
814
  } | {
771
815
  type: 'refreshAssetAuth:response';
772
816
  requestId: string;
@@ -10,7 +10,7 @@
10
10
  * Platform-facing: exported from
11
11
  * `@seriousgaming/sdk-tools/host`.
12
12
  */
13
- import type { ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
13
+ import type { Brand, ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
14
14
  /** The roles a theme sends, in the order §12.3 lists them. */
15
15
  export declare const THEME_COLOR_ROLES: readonly ThemeColorRole[];
16
16
  /** The WCAG AA minimum for normal text. */
@@ -40,16 +40,42 @@ export declare function contrastTextFor(colour: string, preferred?: string): str
40
40
  /** One mode's colours before a host has given them their text colours. */
41
41
  export type ModeColoursInput = Record<ThemeColorRole, string> & {
42
42
  contrastText?: Partial<ThemeContrastText>;
43
+ /**
44
+ * The page colour, raised surfaces, and the author's text for both
45
+ * (§12.3). Optional here, because a host can always send a plain page's:
46
+ * the payload carries all three either way.
47
+ */
48
+ background?: string;
49
+ surface?: string;
50
+ text?: string;
43
51
  };
44
52
  /** A theme before a host has given its colours their text colours. */
45
53
  export interface ThemeInput {
46
54
  mode: 'light' | 'dark';
47
55
  light: ModeColoursInput;
48
56
  dark: ModeColoursInput;
57
+ /** The host's brand, sent as it is (§12.3). */
58
+ brand: Brand;
49
59
  }
60
+ type Neutrals = {
61
+ background: string;
62
+ surface: string;
63
+ text: string;
64
+ };
65
+ /**
66
+ * The author's page, surface and text colours, made fit to send, or undefined
67
+ * when they cannot be (§12.3).
68
+ *
69
+ * `text` is held to 4.5:1 or better against both of the others: the author's
70
+ * own where it meets that, otherwise black or white, whichever does better
71
+ * against the weaker of the two. Where neither can, the pair cannot carry text,
72
+ * and the caller sends a plain page instead.
73
+ */
74
+ export declare function neutralsFor(colours: Partial<Neutrals>): Neutrals | undefined;
50
75
  /**
51
76
  * The `setTheme` payload for a theme: every colour of both modes given its
52
- * `contrastText`, keeping any the author supplied that meet AA.
77
+ * `contrastText`, keeping any the author supplied that meet AA, page colours
78
+ * that carry text (the author's, or a plain page's), and the brand as it is.
53
79
  */
54
80
  export declare function withContrastText(theme: ThemeInput): UserInterfaceTheme;
55
81
  export {};