@seriousgaming/sdk-tools 1.0.0-alpha.4 → 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 +64 -6
  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 +28 -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
@@ -3,8 +3,10 @@
3
3
  <head>
4
4
  <meta charset="UTF-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
6
7
  <title>Serious Gaming</title>
7
- <script type="module" crossorigin src="/assets/index-DgFglsnA.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-qxHcu9fJ.js"></script>
9
+ <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
8
10
  </head>
9
11
  <body>
10
12
  <div id="root"></div>
@@ -13,6 +13,7 @@ import type { MutationResult } from '@seriousgaming/sdk/projection';
13
13
  import express from 'express';
14
14
  import type { Command } from '../core/protocol';
15
15
  import type { Session } from '../core/session';
16
+ import { type DevBrand } from './brands';
16
17
  export interface RouteDeps {
17
18
  session: Session;
18
19
  /**
@@ -38,6 +39,8 @@ export interface RouteDeps {
38
39
  code: string;
39
40
  message: string;
40
41
  }>;
42
+ /** The brands the console offers, the first its default (§12.3). */
43
+ brands: () => DevBrand[];
41
44
  }
42
45
  export declare function registerRoutes(app: express.Application, deps: RouteDeps): void;
43
46
  /** Where the reads a frame makes are mounted, on one origin or the other. */
@@ -64,4 +67,10 @@ declare const ASSET_PATHS: {
64
67
  * the console's origin under `/api` for the CLI and for the console itself.
65
68
  */
66
69
  export declare function registerAssetRoutes(app: express.Application, deps: Pick<RouteDeps, 'session' | 'packagePath'>, prefix: keyof typeof ASSET_PATHS): void;
70
+ /**
71
+ * The files a brand names, at `/assets/brands/<id>/<path>` on the asset
72
+ * origin, so a surface loads its logo and fonts as its own origin (§16.5).
73
+ * No asset-auth: a host's brand is no secret.
74
+ */
75
+ export declare function registerBrandRoutes(app: express.Application, brands: () => DevBrand[]): void;
67
76
  export {};
@@ -47,6 +47,12 @@ export interface ShellOptions extends SessionOptions {
47
47
  * the session, its API and the package's files.
48
48
  */
49
49
  lan?: boolean;
50
+ /**
51
+ * Brand files to offer in the console's brand picker, ahead of the
52
+ * built-in ones, the first selected (§12.3). Each is read when the server
53
+ * starts, so a broken one fails the start rather than the page.
54
+ */
55
+ brandFiles?: string[];
50
56
  }
51
57
  /**
52
58
  * Something the server could not apply live, kept until it no longer holds so
@@ -87,6 +93,7 @@ export declare class DevShell {
87
93
  /** The participant an operator page says it is showing, where it shows one. */
88
94
  private readonly socketPresence;
89
95
  private readonly options;
96
+ private brands;
90
97
  private server;
91
98
  private assetServer;
92
99
  private sockets;
@@ -117,6 +124,13 @@ export declare class DevShell {
117
124
  /** Where an isolated server keeps blobs, and how to stop doing so. */
118
125
  private isolatedBlobs;
119
126
  constructor(options: ShellOptions);
127
+ /**
128
+ * The brands, read again so an edit to a brand file shows on the next
129
+ * page load. One that has broken since keeps its last good reading, with
130
+ * the reason logged: the server is already up, and a typo mid-edit is not
131
+ * worth taking the page down for.
132
+ */
133
+ private currentBrands;
120
134
  start(): Promise<void>;
121
135
  private releaseIsolatedBlobs;
122
136
  private listen;
@@ -66,8 +66,6 @@ export interface BatchOptions {
66
66
  * like in a game's library, or exported before the day.
67
67
  */
68
68
  sessionless?: boolean;
69
- /** The active scenario's name in the session locale, for a presentation. */
70
- scenarioName?: string | null;
71
69
  }
72
70
  /**
73
71
  * Narrow a context to what a surface declared (§7.4).
@@ -0,0 +1,75 @@
1
+ # For AI agents
2
+
3
+ An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer. This page is the loop to follow, and where to read next.
4
+
5
+ **Keywords:** ai agent, coding agent, claude, llms.txt, non-interactive, automation, json output, scripting, headless
6
+
7
+ ## What you are building
8
+
9
+ A game is a package: TypeScript logic that plays one round at a time, React screens for participants and the facilitator, and JSON bundles that declare what each part reads, writes, and uses. [Core concepts](./concepts/index.md) has the model on one screen, and [Designing a serious game](./guides/designing-a-game.md) turns a brief, such as 'a negotiation exercise for our sales team', into decisions, rounds, and a debrief.
10
+
11
+ ## Read the docs for the installed version
12
+
13
+ The site describes the newest release. Inside a package, read the docs that ship with the version it has installed:
14
+
15
+ ```bash
16
+ pnpm run --silent sdk docs view # the documentation tree
17
+ pnpm run --silent sdk docs view recipes/index.md # every recipe, one line each
18
+ pnpm run sdk docs export # copy every page into the package, to search with grep
19
+ ```
20
+
21
+ On the site, [llms.txt](https://sdk.seriousgaming.com/llms.txt) lists every page, [llms-small.txt](https://sdk.seriousgaming.com/llms-small.txt) holds the core pages in one file, and [llms-full.txt](https://sdk.seriousgaming.com/llms-full.txt) holds them all. Start from a recipe for a task and from a guide for a whole subject.
22
+
23
+ ## 1. Scaffold without a prompt
24
+
25
+ Pass the package definition as JSON, so nothing waits for an answer:
26
+
27
+ ```bash
28
+ mkdir my-game && cd my-game
29
+ pnpm dlx @seriousgaming/sdk-tools new package '{"identifier":"com.example.mygame","name":"My Game","version":"0.1.0"}'
30
+ ```
31
+
32
+ You get the starter game, a complete lemonade stand, with tests at every level, a `CLAUDE.md`, and `.claude/rules/`. Read `CLAUDE.md` before changing anything: it holds the rules that are expensive to get wrong. Pass `--empty` for the package files and the agent guidance alone.
33
+
34
+ Without a terminal, the CLI never prompts: a command that would ask fails with `PROMPT_REQUIRED` and exit code 2. Every `new` and `update` takes its definition as an argument, with `--file`, or on stdin, and `delete` takes `--yes`.
35
+
36
+ ## 2. Change it through the CLI
37
+
38
+ ```bash
39
+ pnpm run sdk new capability --help # every resource type prints its JSON format
40
+ pnpm run sdk new capability '{...}'
41
+ pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/writes/-","value":"results"}]'
42
+ ```
43
+
44
+ The CLI writes the bundle and regenerates the typed `types.ts` beside it. Edit logic and screens directly, and never edit a `types.ts`.
45
+
46
+ ## 3. Check every change
47
+
48
+ Run these in order, and stop at the first that fails:
49
+
50
+ ```bash
51
+ pnpm run --silent sdk build --validate-only --json # the package: bundles, references, settings
52
+ pnpm run typecheck
53
+ pnpm run lint
54
+ pnpm test:run # unit tests beside each resource
55
+ pnpm test:engine # whole games, in-process
56
+ pnpm run --silent sdk tick --no-server --json # one tick in the restricted production runtime
57
+ ```
58
+
59
+ With `--json`, a command prints exactly one JSON document on stdout, whether it succeeds or fails. Branch on `ok`, the exit code, and `error.code`, never on the message, and on a failure read `diagnostics[]` first: each names the file and the place in it. [Check a package from a script](./recipes/check-a-package-from-a-script.md) has the whole contract, and [CLI error codes](./cli-error-codes.md) every code.
60
+
61
+ ## 4. Play it
62
+
63
+ ```bash
64
+ pnpm run --silent sdk tick --no-server --json --patch '[{"op":"replace","path":"/plan/Make/lemonade","value":70}]'
65
+ pnpm run --silent sdk view --no-server --json
66
+ ```
67
+
68
+ `--no-server` runs each command in-process against a fresh session and leaves nothing running. Without it, a session command uses the dev server the user is watching, or starts one in the background. [Drive a game from the CLI](./cli-simulation-testing.md) covers the whole workflow.
69
+
70
+ ## What not to do
71
+
72
+ - Never start `pnpm run sdk dev`, or anything else that keeps running. The user starts the dev server when they want to watch
73
+ - Never publish, and never add a dependency, unless the user asks
74
+ - Never mutate `context` in logic, or use `Math.random()`, the clock, Node.js, or browser APIs there. [Core concepts](./concepts/index.md#the-model-on-one-screen) says what to use instead
75
+ - Never hard-code a number a facilitator or a scenario might want to change: make it a [setting](./guides/settings.md)
@@ -6,6 +6,19 @@ Every export of `@seriousgaming/deck`, with the declaration it is published with
6
6
 
7
7
  ## Functions
8
8
 
9
+ ### brandFromTheme
10
+
11
+ A host's theme as a deck brand: its accents and their text colours, its page, surface and text colours where it sends them, and its fonts.
12
+
13
+ ```ts
14
+ function brandFromTheme(
15
+ theme: HostTheme,
16
+ options?: {
17
+ mode?: 'light' | 'dark';
18
+ }
19
+ ): Brand;
20
+ ```
21
+
9
22
  ### Bullets
10
23
 
11
24
  A bulleted or numbered list. Exports as an editable PowerPoint list.
@@ -136,6 +149,8 @@ const ALL_STEPS: number;
136
149
 
137
150
  ### defaultBrand
138
151
 
152
+ Serious Gaming: its purple and teal, its charcoal text, Sora for headings and Work Sans for body text. The families are names only: a surface whose host sends them as brand fonts has them loaded, and any other falls back to the system's sans-serif.
153
+
139
154
  ```ts
140
155
  const defaultBrand: Brand;
141
156
  ```
@@ -179,6 +194,8 @@ interface Brand {
179
194
  surface: string;
180
195
  text: string;
181
196
  muted: string;
197
+ onPrimary?: string;
198
+ onSecondary?: string;
182
199
  };
183
200
  fonts: {
184
201
  heading: string;
@@ -267,6 +284,27 @@ interface HeadingProps extends TextBase {
267
284
  }
268
285
  ```
269
286
 
287
+ ### HostTheme
288
+
289
+ A host theme as the deck reads it. Declared here by shape rather than imported, so the deck still depends on nothing of the SDK's: `useSessionUserInterfaceTheme()` and a presentation's `theme` both fit it.
290
+
291
+ ```ts
292
+ interface HostTheme {
293
+ light: HostModeColors;
294
+ dark: HostModeColors;
295
+ brand?: {
296
+ fonts?: {
297
+ heading?: {
298
+ family: string;
299
+ };
300
+ body?: {
301
+ family: string;
302
+ };
303
+ };
304
+ };
305
+ }
306
+ ```
307
+
270
308
  ### ImageProps
271
309
 
272
310
  ```ts
@@ -6,14 +6,14 @@ Every type, function, hook and component your game imports, one page per entry p
6
6
 
7
7
  | Entry point | Exports |
8
8
  | ---------------------------------------------------------- | -------------------------------------------------------------- |
9
- | [`@seriousgaming/sdk`](./sdk.md) | 10 functions, 2 classes, 94 interfaces, 46 types |
10
- | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 43 functions, 3 classes, 37 constants, 18 interfaces, 35 types |
11
- | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 11 functions, 6 types |
12
- | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 4 functions, 4 constants, 7 types |
9
+ | [`@seriousgaming/sdk`](./sdk.md) | 10 functions, 2 classes, 97 interfaces, 48 types |
10
+ | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 47 functions, 3 classes, 38 constants, 25 interfaces, 36 types |
11
+ | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
12
+ | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
13
13
  | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
14
14
  | [`@seriousgaming/sdk/commands`](./sdk-commands.md) | 3 interfaces, 5 types |
15
15
  | [`@seriousgaming/sdk/e2e`](./sdk-e2e.md) | 6 functions, 1 constant, 4 interfaces, 5 types |
16
- | [`@seriousgaming/deck`](./deck.md) | 15 functions, 5 constants, 14 interfaces, 4 types |
16
+ | [`@seriousgaming/deck`](./deck.md) | 16 functions, 5 constants, 15 interfaces, 4 types |
17
17
  | [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 4 functions, 1 class, 10 interfaces, 11 types |
18
18
 
19
19
  ## Which entry point to import from
@@ -39,7 +39,7 @@ interface EndpointListing {
39
39
  identifier: string;
40
40
  displayName?: string;
41
41
  description?: string;
42
- scope: 'session' | 'team';
42
+ scope: 'session' | 'team' | 'scenario';
43
43
  visibility: 'internal' | 'external';
44
44
  requestSchema: Record<string, unknown>;
45
45
  responseSchema: Record<string, unknown>;
@@ -160,6 +160,7 @@ interface StateProjection {
160
160
  identifier: string;
161
161
  name: string;
162
162
  scenarioId: string | null;
163
+ scenarioName: string | null;
163
164
  };
164
165
  session: {
165
166
  completedTicks: number;
@@ -115,6 +115,7 @@ interface StateProjection {
115
115
  identifier: string;
116
116
  name: string;
117
117
  scenarioId: string | null;
118
+ scenarioName: string | null;
118
119
  };
119
120
  session: {
120
121
  completedTicks: number;
@@ -7,7 +7,9 @@ Helpers for unit-testing a game's logic without a runtime.
7
7
  `logicArgs` builds the arguments object a logic function takes, filling
8
8
  everything the test does not name. `createStubCallbacks` is the offline,
9
9
  deterministic set of callbacks it uses, and the stubs behind it are the ones
10
- `createTestSession` answers service callbacks with.
10
+ `createTestSession` answers service callbacks with. `createMockTeam`,
11
+ `createMockParticipant` and their plurals build the teams and participants
12
+ a test passes in.
11
13
 
12
14
  To test a game as a whole (hooks, validators, endpoints, undo, timers), use
13
15
  `createTestSession` from `@seriousgaming/sdk-tools/client`.
@@ -16,6 +18,38 @@ Every export of `@seriousgaming/sdk/testing`, with the declaration it is publish
16
18
 
17
19
  ## Functions
18
20
 
21
+ ### createMockParticipant
22
+
23
+ Creates a valid `Participant` for use in tests: the participant a hook's payload or a validator's actor names, or a surface's own identity, as `useUserInterfaceParticipant()` returns it.
24
+
25
+ ```ts
26
+ function createMockParticipant(overrides?: Partial<Participant>): Participant;
27
+ ```
28
+
29
+ ### createMockParticipants
30
+
31
+ Creates a roster of participants for use in tests, as `useUserInterfaceParticipants()` and its session equivalent return it. Ids, names and indices follow the runtime's conventions (`id` is `String(index + 1)`, `name` is `Participant N`), and every entry is `connected`.
32
+
33
+ ```ts
34
+ function createMockParticipants(count?: number, teamId?: string): Participant[];
35
+ ```
36
+
37
+ ### createMockTeam
38
+
39
+ Creates a valid `TeamInfo` for use in tests: the team a team-scoped endpoint acts on, an entry of `useSessionUserInterfaceTeams()`, or a surface's `ownTeam`. `teamId` and `name` follow `index` unless given, so `createMockTeam({ index: 2 })` is `team-3`, `Team 3`.
40
+
41
+ ```ts
42
+ function createMockTeam(overrides?: Partial<TeamInfo>): TeamInfo;
43
+ ```
44
+
45
+ ### createMockTeams
46
+
47
+ Creates a list of teams for use in tests, as `useSessionUserInterfaceTeams()` returns it: indices from 0, in index order, each built by `createMockTeam`.
48
+
49
+ ```ts
50
+ function createMockTeams(count?: number): TeamInfo[];
51
+ ```
52
+
19
53
  ### createStubCallbacks
20
54
 
21
55
  Every callback logic can receive, stubbed, for calling a logic function directly in a unit test.
@@ -61,6 +95,7 @@ const logicArgs: {
61
95
  aggregate: typeof aggregate;
62
96
  hook: typeof hook;
63
97
  endpoint: typeof endpoint;
98
+ scenarioEndpoint: typeof scenarioEndpoint;
64
99
  tickController: typeof tickController;
65
100
  validator: typeof validator;
66
101
  requestTick: typeof requestTick;
@@ -185,6 +220,22 @@ type RequestTickArgsInput<TContext, TSettings> = SettingsInput<TSettings> & {
185
220
  };
186
221
  ```
187
222
 
223
+ ### ScenarioEndpointArgsInput
224
+
225
+ Input to `logicArgs.scenarioEndpoint`.
226
+
227
+ ```ts
228
+ type ScenarioEndpointArgsInput<TRequest, TCallbacks, TSettings> = Pick<
229
+ CommonInput<TCallbacks>,
230
+ 'callbacks'
231
+ > &
232
+ SettingsInput<TSettings> & {
233
+ request: TRequest;
234
+ caller?: Partial<EndpointCaller>;
235
+ meta?: Partial<LogicMeta>;
236
+ };
237
+ ```
238
+
188
239
  ### TickControllerArgsInput
189
240
 
190
241
  Input to `logicArgs.tickController`.
@@ -154,6 +154,7 @@ interface StateProjection {
154
154
  identifier: string;
155
155
  name: string;
156
156
  scenarioId: string | null;
157
+ scenarioName: string | null;
157
158
  };
158
159
  session: {
159
160
  completedTicks: number;
@@ -6,9 +6,17 @@ Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is publ
6
6
 
7
7
  ## Functions
8
8
 
9
+ ### createMockBrand
10
+
11
+ A host brand for tests: a name and a logo for each background, as `data:` URLs, so a component reading `useBrand()` or `useBrandLogo()` has something to render. It names no fonts, so nothing waits on a load.
12
+
13
+ ```ts
14
+ function createMockBrand(overrides?: Partial<Brand>): Brand;
15
+ ```
16
+
9
17
  ### createMockParticipant
10
18
 
11
- Creates a valid Participant for use in tests — the caller's own identity, as returned by `useUserInterfaceParticipant()`.
19
+ Creates a valid `Participant` for use in tests: the participant a hook's payload or a validator's actor names, or a surface's own identity, as `useUserInterfaceParticipant()` returns it.
12
20
 
13
21
  ```ts
14
22
  function createMockParticipant(overrides?: Partial<Participant>): Participant;
@@ -16,7 +24,7 @@ function createMockParticipant(overrides?: Partial<Participant>): Participant;
16
24
 
17
25
  ### createMockParticipants
18
26
 
19
- Creates a roster of participants for use in tests — the list returned by `useUserInterfaceParticipants()` (and the session equivalent, which shares the same shape). Ids, names, and indices follow the runtime's conventions (`id` is `String(index + 1)`, `name` is `Participant N`), and every entry is `connected` by default.
27
+ Creates a roster of participants for use in tests, as `useUserInterfaceParticipants()` and its session equivalent return it. Ids, names and indices follow the runtime's conventions (`id` is `String(index + 1)`, `name` is `Participant N`), and every entry is `connected`.
20
28
 
21
29
  ```ts
22
30
  function createMockParticipants(count?: number, teamId?: string): Participant[];
@@ -54,6 +62,22 @@ function createMockSharedState<T extends object = Record<string, unknown>>(
54
62
  ): SharedState<T>;
55
63
  ```
56
64
 
65
+ ### createMockTeam
66
+
67
+ Creates a valid `TeamInfo` for use in tests: the team a team-scoped endpoint acts on, an entry of `useSessionUserInterfaceTeams()`, or a surface's `ownTeam`. `teamId` and `name` follow `index` unless given, so `createMockTeam({ index: 2 })` is `team-3`, `Team 3`.
68
+
69
+ ```ts
70
+ function createMockTeam(overrides?: Partial<TeamInfo>): TeamInfo;
71
+ ```
72
+
73
+ ### createMockTeams
74
+
75
+ Creates a list of teams for use in tests, as `useSessionUserInterfaceTeams()` returns it: indices from 0, in index order, each built by `createMockTeam`.
76
+
77
+ ```ts
78
+ function createMockTeams(count?: number): TeamInfo[];
79
+ ```
80
+
57
81
  ### createMockTeamState
58
82
 
59
83
  A `TeamState` for a session-surface fixture, with the fields a test rarely cares about filled in.
@@ -131,6 +155,7 @@ type RenderSessionUserInterfaceOptions<
131
155
  > = {
132
156
  sessionData?: Partial<TData>;
133
157
  settings?: unknown;
158
+ scenarioName?: string | null;
134
159
  setData?: SessionSetDataMock<TData>;
135
160
  sessionKey?: string;
136
161
  theme?: SessionUserInterfaceTheme;
@@ -138,8 +163,8 @@ type RenderSessionUserInterfaceOptions<
138
163
  locale?: SessionUserInterfaceLocale;
139
164
  participants?: Participant[];
140
165
  teams?: TeamInfo[];
141
- teamConfiguration?: TeamConfiguration;
142
- sessionMeta?: SessionMeta;
166
+ teamConfiguration?: Partial<TeamConfiguration>;
167
+ sessionMeta?: Partial<SessionMeta>;
143
168
  teamLinks?: TeamLinks[];
144
169
  runKind?: RunKind;
145
170
  walkthroughLink?: WalkthroughLink | null;
@@ -197,6 +222,7 @@ type RenderSettingsEditorResult = RenderResult & {
197
222
  type RenderUserInterfaceOptions = {
198
223
  data?: object;
199
224
  settings?: unknown;
225
+ scenarioName?: string | null;
200
226
  completedTicks?: number;
201
227
  isRoundProcessing?: boolean;
202
228
  setData?: (update: Partial<Record<string, unknown>>) => void;