@seriousgaming/sdk-tools 1.6.1 → 1.8.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 (202) hide show
  1. package/dist/agent/guidance.md +1 -0
  2. package/dist/{cli-2NU2LPEE.js → cli-27M4PX7O.js} +17 -17
  3. package/dist/{cli-2BH7FX27.js → cli-2FXZZLCL.js} +1 -1
  4. package/dist/{cli-5ACDPCXI.js → cli-2KDV2DYC.js} +3 -3
  5. package/dist/{cli-OXAUOWCN.js → cli-2QM63J3I.js} +1 -1
  6. package/dist/{cli-HW53ICZC.js → cli-32NRB2IT.js} +15 -15
  7. package/dist/{cli-45OCBG53.js → cli-3HBYH4VF.js} +11 -11
  8. package/dist/{cli-4VFZHLDG.js → cli-3HPAKEJJ.js} +2 -2
  9. package/dist/{cli-R2MUZQE2.js → cli-3HZGJRQW.js} +11 -11
  10. package/dist/{cli-PGCIHPU7.js → cli-3OCKRPXI.js} +18 -18
  11. package/dist/{cli-64AB62PM.js → cli-3OVXQJEW.js} +2 -2
  12. package/dist/{cli-4UWFQNGF.js → cli-3VV2JLHX.js} +1 -1
  13. package/dist/{cli-XSLNH5PR.js → cli-42ZUP4X3.js} +141 -5
  14. package/dist/{cli-ZJFQ7EEA.js → cli-4B5OBHSY.js} +19 -19
  15. package/dist/{cli-7A6MKCUJ.js → cli-4EMNCU63.js} +27 -19
  16. package/dist/cli-5CG6BMCY.js +36 -0
  17. package/dist/{cli-XZCJIKIV.js → cli-5FRKWNVP.js} +19 -19
  18. package/dist/{cli-Y3DDNMPX.js → cli-5P66N5G6.js} +17 -17
  19. package/dist/{cli-6VNKQ3OX.js → cli-5SYPXJCB.js} +28 -16
  20. package/dist/{cli-G6CANSPL.js → cli-66AHBZRZ.js} +15 -15
  21. package/dist/{cli-BJMS3VX3.js → cli-6AGWTGTO.js} +106 -28
  22. package/dist/{cli-TTMBBEJC.js → cli-6BAZE75K.js} +18 -18
  23. package/dist/{cli-GFNDW2DL.js → cli-6FVHRL3H.js} +19 -19
  24. package/dist/{cli-QVASWX2A.js → cli-6GDPO5VU.js} +2 -2
  25. package/dist/{cli-7XLHO2FE.js → cli-6NBER36P.js} +1 -1
  26. package/dist/{cli-FQRVFGN6.js → cli-726NJARI.js} +0 -0
  27. package/dist/{cli-CD5CIJZI.js → cli-72DRYVTT.js} +13 -13
  28. package/dist/{cli-MMN4BPO4.js → cli-7CW2BBJG.js} +1 -1
  29. package/dist/{cli-XAT25PRU.js → cli-7GJGFILU.js} +15 -15
  30. package/dist/{cli-HFX3YPUL.js → cli-7NCVUM5U.js} +3 -3
  31. package/dist/cli-7S4G4EKK.js +110 -0
  32. package/dist/{cli-J4DKUUTK.js → cli-7V6GUIIS.js} +2 -2
  33. package/dist/{cli-N6H6T2E2.js → cli-AEAFLZGY.js} +12 -0
  34. package/dist/{cli-C47GJATR.js → cli-AGYCXRPR.js} +3 -3
  35. package/dist/{cli-XSVGKI3R.js → cli-BC4KKNLA.js} +1 -1
  36. package/dist/cli-BQ3FHENQ.js +16 -0
  37. package/dist/{cli-KGM6RRQW.js → cli-BXCCODYD.js} +20 -20
  38. package/dist/cli-C2XDL4LD.js +30 -0
  39. package/dist/{cli-MJUYJIEP.js → cli-C45A5VX6.js} +3 -3
  40. package/dist/{cli-DOXRQ3S5.js → cli-C7YZNPWX.js} +11 -11
  41. package/dist/{cli-HOE3WLFH.js → cli-CAX4CQTC.js} +13 -13
  42. package/dist/{cli-YOTGR3NB.js → cli-CVOLMK3Z.js} +1 -1
  43. package/dist/{cli-ILFDANBR.js → cli-D3CZRXVJ.js} +63 -17
  44. package/dist/{cli-4YB3ROVR.js → cli-DMKRP33X.js} +1 -1
  45. package/dist/{cli-Y3O5F4JN.js → cli-DPFN2LIZ.js} +15 -15
  46. package/dist/{cli-6UTPHWRQ.js → cli-DT756M3Z.js} +20 -20
  47. package/dist/{cli-TIDQ4WUE.js → cli-DXHPYN4N.js} +1 -1
  48. package/dist/{cli-6K3VQQUS.js → cli-E665NKUQ.js} +5 -5
  49. package/dist/{cli-O5ABH2WK.js → cli-EK7CGMGS.js} +17 -17
  50. package/dist/{cli-6QB2VFPY.js → cli-ESU3J563.js} +15 -15
  51. package/dist/{cli-VPRRICZA.js → cli-F47ELAXM.js} +47 -47
  52. package/dist/{cli-RLEGRWFM.js → cli-FH4WBZHA.js} +14 -14
  53. package/dist/{cli-3D3ZXWOV.js → cli-FHKRO6OU.js} +19 -19
  54. package/dist/{cli-JZCLIT3O.js → cli-FSEDPZR5.js} +19 -19
  55. package/dist/{cli-XOTNXEJA.js → cli-FV45UZQP.js} +19 -19
  56. package/dist/{cli-AV2FYC5G.js → cli-G7FX7ZIU.js} +12 -12
  57. package/dist/{cli-IP4RXGHM.js → cli-GFONBOJT.js} +129 -38
  58. package/dist/{cli-C5QOJJWX.js → cli-GHIMH6JU.js} +1 -1
  59. package/dist/{cli-IDVUHGKG.js → cli-HC7L5DXV.js} +15 -15
  60. package/dist/{cli-WU43JT4T.js → cli-HJPNNORV.js} +2 -2
  61. package/dist/{cli-QY5NZAR7.js → cli-HMEZHQBC.js} +17 -17
  62. package/dist/{cli-JZOZOEZM.js → cli-HQUVSAHY.js} +18 -18
  63. package/dist/{cli-MYJGMA6U.js → cli-IC5FOT2J.js} +1 -1
  64. package/dist/{cli-VL2P354N.js → cli-IVZ7AHUJ.js} +3 -3
  65. package/dist/{cli-B6YHEKIJ.js → cli-J2OTL6JH.js} +5 -5
  66. package/dist/{cli-Z56ZIVA6.js → cli-JA6UFTSX.js} +17 -17
  67. package/dist/{cli-MJV47HKI.js → cli-JOXCAGM7.js} +19 -19
  68. package/dist/{cli-ZBN5KAIB.js → cli-JQ6I5GGE.js} +3 -3
  69. package/dist/{cli-TDSQSCX4.js → cli-K6M6YB67.js} +1 -1
  70. package/dist/{cli-C6ZLPK2U.js → cli-KFVA7DT3.js} +3 -3
  71. package/dist/{cli-KOGRWFN7.js → cli-KH6FKM5A.js} +15 -15
  72. package/dist/{cli-5IAW3LIF.js → cli-KMT235FV.js} +2 -2
  73. package/dist/{cli-ZDUADFBY.js → cli-KU4PG7ZA.js} +15 -15
  74. package/dist/{cli-N45DREM4.js → cli-L4DEEAMK.js} +17 -17
  75. package/dist/{cli-MU5LB43S.js → cli-ME3JKMJL.js} +19 -19
  76. package/dist/{cli-C3CMJSNL.js → cli-MJ65PIYI.js} +15 -15
  77. package/dist/cli-MM2ROZWO.js +36 -0
  78. package/dist/{cli-RZITKPJX.js → cli-MN7X4UG2.js} +1 -1
  79. package/dist/{cli-4SIWLHQO.js → cli-MPU4FLA7.js} +4 -4
  80. package/dist/{cli-HCRTYQQS.js → cli-MPWTXNF6.js} +2 -2
  81. package/dist/{cli-EVI36HEM.js → cli-N5K2KHPR.js} +15 -15
  82. package/dist/{cli-RSW6EBBD.js → cli-NGOQWOQE.js} +15 -15
  83. package/dist/{cli-ZTWOE3ZT.js → cli-NU4SCD5D.js} +1 -1
  84. package/dist/{cli-BYCHKSSH.js → cli-O3IMNLN2.js} +282 -96
  85. package/dist/{cli-KGT5L7VZ.js → cli-OUFXSQOW.js} +7265 -4467
  86. package/dist/{cli-DFBTZEBX.js → cli-PEY6XZDE.js} +16 -16
  87. package/dist/{cli-QUSCIUOM.js → cli-PLW3TWJ7.js} +19 -19
  88. package/dist/{cli-JVI24FI6.js → cli-PO2ALWHP.js} +13 -13
  89. package/dist/{cli-3BRC32CP.js → cli-PPEB3ENS.js} +18 -18
  90. package/dist/{cli-ZDOTXEKL.js → cli-PZ7G544B.js} +3 -3
  91. package/dist/{cli-L7VYSXQK.js → cli-Q5BKFFDL.js} +4 -4
  92. package/dist/{cli-3ZKWV3PN.js → cli-QAI6T5FL.js} +15 -15
  93. package/dist/{cli-KSGB2ZLK.js → cli-QAVLRCQ5.js} +3 -3
  94. package/dist/{cli-VDBW23SS.js → cli-QDIH2G2P.js} +15 -15
  95. package/dist/cli-SN7D7HTX.js +36 -0
  96. package/dist/{cli-IEMKI7J7.js → cli-SOQJHK4Q.js} +6 -6
  97. package/dist/{cli-4PXNOJQX.js → cli-SPKPDXWD.js} +15 -15
  98. package/dist/{cli-MOPSZ3CS.js → cli-SWUAXVIJ.js} +15 -15
  99. package/dist/cli-TJNLXQJ5.js +36 -0
  100. package/dist/{cli-BUQI5UU4.js → cli-U2EWI6H5.js} +11 -11
  101. package/dist/{cli-TT36JCU5.js → cli-UADUC4JD.js} +2 -2
  102. package/dist/{cli-FWFRKQNE.js → cli-UR63LFVK.js} +2 -2
  103. package/dist/{cli-J4UBELKF.js → cli-UTHPCZYL.js} +2 -2
  104. package/dist/{cli-Q6ZBZYK2.js → cli-UYV3BDPA.js} +3 -3
  105. package/dist/{cli-LQOHATY2.js → cli-UZCQL6YP.js} +3 -3
  106. package/dist/{cli-HKORECAG.js → cli-V5K3CCYZ.js} +2 -2
  107. package/dist/cli-V7L3HEL4.js +36 -0
  108. package/dist/{cli-HSIHDN6K.js → cli-VBSF3R3L.js} +16 -16
  109. package/dist/{cli-NROTDF5Y.js → cli-VQ4OJ4KE.js} +18 -18
  110. package/dist/{cli-IUS2YCD3.js → cli-VTLFQHDO.js} +1 -1
  111. package/dist/{cli-JJSWBW4H.js → cli-W7XCTGQ7.js} +15 -15
  112. package/dist/{cli-UZZFNXRX.js → cli-W7Y7X3FX.js} +19 -19
  113. package/dist/cli-WWNTBK37.js +1973 -0
  114. package/dist/cli-XPJGW375.js +36 -0
  115. package/dist/{cli-SRHBXZCN.js → cli-Y33ULHYO.js} +1 -1
  116. package/dist/{cli-TTKICM5P.js → cli-YLYB4ITF.js} +13 -13
  117. package/dist/{cli-72XDEFU3.js → cli-ZFY6TGU7.js} +4 -4
  118. package/dist/{cli-6SGCYEEC.js → cli-ZSKP2IRP.js} +53 -38
  119. package/dist/cli.js +53 -51
  120. package/dist/client.js +17699 -16630
  121. package/dist/core/game-settings.d.ts +5 -3
  122. package/dist/core/save-scenario.d.ts +1 -0
  123. package/dist/core/session-roster.d.ts +10 -0
  124. package/dist/core/session-start-gate.d.ts +25 -0
  125. package/dist/core/session.d.ts +4 -0
  126. package/dist/dev/console/assets/index-CVNjiRUh.js +208 -0
  127. package/dist/dev/console/index.html +1 -1
  128. package/dist/dev/routes.d.ts +5 -2
  129. package/dist/dev/shell.d.ts +9 -1
  130. package/dist/dev/view/batch.d.ts +11 -1
  131. package/dist/dev/view/route.d.ts +18 -1
  132. package/dist/dev/view/view.d.ts +9 -0
  133. package/dist/docs/api/deck.md +1 -1
  134. package/dist/docs/api/index.md +2 -2
  135. package/dist/docs/api/sdk-commands.md +4 -0
  136. package/dist/docs/api/sdk-e2e.md +12 -6
  137. package/dist/docs/api/sdk-projection.md +1 -0
  138. package/dist/docs/api/sdk-tools-client.md +7 -1
  139. package/dist/docs/api/sdk-tools-playwright.md +1 -8
  140. package/dist/docs/api/sdk-ui-testing.md +1 -0
  141. package/dist/docs/api/sdk-ui.md +67 -63
  142. package/dist/docs/api/sdk.md +12 -1
  143. package/dist/docs/changelog.md +26 -0
  144. package/dist/docs/cli-and-dev-server.md +4 -0
  145. package/dist/docs/cli-error-codes.md +7 -1
  146. package/dist/docs/cli-reference.md +20 -2
  147. package/dist/docs/concepts/index.md +1 -0
  148. package/dist/docs/guides/engine.md +5 -0
  149. package/dist/docs/guides/file-handling.md +4 -1
  150. package/dist/docs/guides/llm-integration.md +3 -2
  151. package/dist/docs/guides/multi-team-games.md +2 -0
  152. package/dist/docs/guides/patterns.md +5 -0
  153. package/dist/docs/guides/presentation.md +11 -10
  154. package/dist/docs/guides/session-hooks.md +16 -0
  155. package/dist/docs/guides/session.md +1 -1
  156. package/dist/docs/guides/settings.md +6 -2
  157. package/dist/docs/guides/setup.md +23 -2
  158. package/dist/docs/guides/speech-generation.md +1 -0
  159. package/dist/docs/guides/testing.md +2 -0
  160. package/dist/docs/guides/tick-controller.md +2 -0
  161. package/dist/docs/guides/type-safety.md +2 -1
  162. package/dist/docs/guides/ui-files-and-llms.md +3 -1
  163. package/dist/docs/guides/upgrading.md +16 -0
  164. package/dist/docs/guides/validators.md +27 -4
  165. package/dist/docs/guides/waiting-room.md +2 -0
  166. package/dist/docs/page-index.md +12 -10
  167. package/dist/docs/recipes/call-endpoint-from-ui.md +1 -0
  168. package/dist/docs/recipes/create-scenario-editor.md +2 -1
  169. package/dist/docs/recipes/create-setup.md +2 -1
  170. package/dist/docs/recipes/declare-api-uses.md +1 -0
  171. package/dist/docs/recipes/describe-setup-with-endpoint.md +69 -0
  172. package/dist/docs/recipes/index.md +3 -1
  173. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +2 -2
  174. package/dist/docs/recipes/test-user-interface.md +1 -1
  175. package/dist/docs/recipes/validate-scenarios.md +9 -3
  176. package/dist/docs/recipes/write-setup-notes.md +58 -0
  177. package/dist/docs/troubleshooting.md +2 -1
  178. package/dist/execution/executor.d.ts +12 -0
  179. package/dist/execution/scenario-gates.d.ts +40 -0
  180. package/dist/host/protocol.d.ts +10 -1
  181. package/dist/host.js +1083 -467
  182. package/dist/playwright.js +17760 -16691
  183. package/dist/runtime/manifest-version.d.ts +1 -1
  184. package/dist/runtime.js +4 -2
  185. package/dist/schema.json +10 -1
  186. package/dist/setup/setup-notes.d.ts +42 -0
  187. package/dist/templates/package/package.json.liquid +15 -15
  188. package/dist/templates/starter-game/package.json +13 -13
  189. package/dist/utils/error-codes.d.ts +13 -1
  190. package/dist/validation/package-validation.d.ts +1 -1
  191. package/package.json +22 -23
  192. package/dist/cli-2GZYGRVL.js +0 -36
  193. package/dist/cli-5SM367K7.js +0 -30
  194. package/dist/cli-DDJYUKQG.js +0 -36
  195. package/dist/cli-LK3V4RI5.js +0 -36
  196. package/dist/cli-N24OHSAN.js +0 -36
  197. package/dist/cli-OMWC75CC.js +0 -256
  198. package/dist/cli-RCIWBCXD.js +0 -36
  199. package/dist/cli-UMEBPAZQ.js +0 -16
  200. package/dist/cli-VQ6HVQW4.js +0 -4010
  201. package/dist/cli-WR3NOY74.js +0 -36
  202. package/dist/dev/console/assets/index-CuMOOH9m.js +0 -204
@@ -198,6 +198,7 @@ The engine receives `readAsset` in its callbacks. It accepts an `asset:`, `share
198
198
 
199
199
  ```typescript
200
200
  import { decodeUtf8, getText, type RunFunction } from '@seriousgaming/sdk';
201
+
201
202
  import type { Context, Settings } from './types';
202
203
 
203
204
  export const Run: RunFunction<Context, Settings> = async ({ context, callbacks }) => {
@@ -266,6 +267,7 @@ Declare `"uses": ["extractText", "generateText"]` on the engine, and pass the ge
266
267
 
267
268
  ```typescript
268
269
  import { getText, type RunFunction } from '@seriousgaming/sdk';
270
+
269
271
  import type { Callbacks, Context, Settings } from './types';
270
272
 
271
273
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({
@@ -317,8 +319,9 @@ export const Handle: Handler = async ({ request, callbacks }) => {
317
319
  The endpoint bundle declares `"uses": ["extractText"]`; the UI declares the endpoint in its `endpoints` array and calls it:
318
320
 
319
321
  ```tsx
320
- import { useState } from 'react';
321
322
  import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
323
+ import { useState } from 'react';
324
+
322
325
  import type { Callbacks } from '../types';
323
326
 
324
327
  function DocumentProcessor() {
@@ -164,10 +164,10 @@ All engine functions are async and receive a `callbacks` parameter:
164
164
 
165
165
  ```typescript
166
166
  import { RunFunction } from '@seriousgaming/sdk';
167
- import type { Context, Settings } from './types';
168
-
169
167
  import { getText } from '@seriousgaming/sdk';
170
168
 
169
+ import type { Context, Settings } from './types';
170
+
171
171
  export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
172
172
  // Simple text generation (quick tier by default)
173
173
  const response = await callbacks.generateText('Your prompt here');
@@ -481,6 +481,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call se
481
481
  ```typescript
482
482
  // endpoints/chat/logic/logic.ts
483
483
  import { getText } from '@seriousgaming/sdk';
484
+
484
485
  import type { Handler } from '../types';
485
486
 
486
487
  export const Handle: Handler = async ({ request, callbacks }) => {
@@ -279,6 +279,7 @@ import {
279
279
  InitAggregateFunction,
280
280
  RunAggregateFunction,
281
281
  } from '@seriousgaming/sdk';
282
+
282
283
  import type { Context, Settings, SharedContext, TeamContext } from './types';
283
284
 
284
285
  // Per-team init: set this team's own default values
@@ -413,6 +414,7 @@ Each entry in the `teams` array is `{ teamId, index, context }`, and the array i
413
414
 
414
415
  ```typescript
415
416
  import { RunAggregateFunction } from '@seriousgaming/sdk';
417
+
416
418
  import type { Settings, SharedContext, TeamContext } from './types';
417
419
 
418
420
  // Per-team starting capital, indexed by the stable team index
@@ -64,6 +64,7 @@ pnpm run sdk new engine '{
64
64
 
65
65
  ```typescript
66
66
  import { RunFunction } from '@seriousgaming/sdk';
67
+
67
68
  import type { Context, Settings } from './types';
68
69
 
69
70
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -166,6 +167,7 @@ pnpm run sdk update engine '{
166
167
 
167
168
  ```typescript
168
169
  import type { StepFunction } from '@seriousgaming/sdk';
170
+
169
171
  import type { Context, Settings } from './types';
170
172
 
171
173
  export const runInventory: StepFunction<Context, Settings> = async ({ context, settings }) => {
@@ -185,6 +187,7 @@ export const runInventory: StepFunction<Context, Settings> = async ({ context, s
185
187
 
186
188
  ```typescript
187
189
  import type { StepFunction } from '@seriousgaming/sdk';
190
+
188
191
  import type { Context, Settings } from './types';
189
192
 
190
193
  export const runSales: StepFunction<Context, Settings> = async ({ context, settings }) => {
@@ -213,6 +216,7 @@ export const runSales: StepFunction<Context, Settings> = async ({ context, setti
213
216
 
214
217
  ```typescript
215
218
  import { RunFunction } from '@seriousgaming/sdk';
219
+
216
220
  import { runInventory } from './inventory';
217
221
  import { runSales } from './sales';
218
222
  import type { Context, Settings } from './types';
@@ -385,6 +389,7 @@ export const runCosts: StepFunction<Context, Settings> = async ({ context, setti
385
389
 
386
390
  ```typescript
387
391
  import { RunFunction } from '@seriousgaming/sdk';
392
+
388
393
  import { runCosts } from './costs';
389
394
  import { runDemand } from './demand';
390
395
  import { runProduction } from './production';
@@ -53,15 +53,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
53
53
  >();
54
54
  ```
55
55
 
56
- | Field | What it holds |
57
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
58
- | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
- | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
60
- | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
- | `theme` | The host's theme, to map onto the deck's colours |
62
- | `locale` | The locale to render in |
63
- | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
- | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
56
+ | Field | What it holds |
57
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
+ | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks`, `sessionJoinLink` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
60
+ | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
+ | `theme` | The host's theme, to map onto the deck's colours |
62
+ | `locale` | The locale to render in |
63
+ | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
+ | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
65
65
 
66
66
  A presentation sees every team: it is the facilitator's view of the room.
67
67
 
@@ -90,10 +90,11 @@ export function useResults(): Results {
90
90
  The first slides are often on the projector while the room arrives, so a session carries what a join slide needs:
91
91
 
92
92
  - **`joinLinks`**: one entry per team, in index order, each `{ teamId, joinUrl, fallbackJoinUrl? }`. Encode `joinUrl` in a QR code; offer `fallbackJoinUrl` only on request. There is no observe URL: watching a team is the facilitator's tool, not the room's
93
+ - **`sessionJoinLink`**: one link for the whole room, `{ joinUrl, fallbackJoinUrl? }`, or `null` when the host has none or the game turns it off. The host puts whoever follows it in a team, and no host promises which, so show it as one code for everyone and keep the team links for anyone who needs a particular team
93
94
  - **`joinPin`**: the code to enter alongside the link, or `null` when joining needs none. Show it beside the link, never inside it
94
95
  - **`participants`**: every team's participants, `connected` or not, for a count of who has arrived
95
96
 
96
- All three are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
97
+ All four are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
97
98
 
98
99
  ### Varying by scenario
99
100
 
@@ -76,6 +76,21 @@ const teamLinks = useSessionUserInterfaceTeamLinks();
76
76
 
77
77
  Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
78
78
 
79
+ ## useSessionUserInterfaceSessionJoinLink
80
+
81
+ Get the session's one join link, for a single QR code the whole room scans:
82
+
83
+ ```typescript
84
+ import { useSessionUserInterfaceSessionJoinLink } from '@seriousgaming/sdk/ui';
85
+
86
+ const sessionLink = useSessionUserInterfaceSessionJoinLink();
87
+ // SessionJoinLink | null: { joinUrl, fallbackJoinUrl? }
88
+ ```
89
+
90
+ Somebody who follows it is placed in a team by the host, rather than choosing one, and joins as an ordinary participant. That is what a room of many small teams needs: one code on the projector instead of one per team. Encode `joinUrl` and offer `fallbackJoinUrl` on request, as with the team links.
91
+
92
+ It is `null` until the host sends it, on a host with no session link, and for a game that turns it off, so fall back to the team links whenever it is. Never depend on which team somebody lands in: hosts choose differently, and none promises an order or a balance. If it matters, move people afterwards with `moveParticipant`, or turn the link off with `teams.sessionJoin` (see [The game settings](./settings.md#the-game-settings)).
93
+
79
94
  ## useSessionUserInterfaceHostOverlays
80
95
 
81
96
  Find out which host overlays this host offers, before rendering a control for one:
@@ -201,5 +216,6 @@ Additional messages sent after initialisation:
201
216
  | -------------------- | -------------------------------------------------------------------------------------------------------- |
202
217
  | `setTeamList` | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
203
218
  | `setTeamLinks` | Updates each team's facilitator-only join and observe URLs |
219
+ | `setSessionJoinLink` | Updates the session's one join link, or `null` when there is none |
204
220
  | `setParticipantList` | Updates the participant roster across all teams |
205
221
  | `hookFailed` | Reports a hook chain that threw |
@@ -406,8 +406,8 @@ Read colours from the theme hook below rather than hard-coding them, so your ses
406
406
  Edit `src/theme.ts` to use the session theme hook, and turn it into MUI theme options with `createSurfaceTheme`:
407
407
 
408
408
  ```typescript
409
- import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
410
409
  import { createTheme } from '@mui/material/styles';
410
+ import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
411
411
  import { useMemo } from 'react';
412
412
 
413
413
  export function useAppTheme() {
@@ -232,6 +232,7 @@ The engine, hooks, validators, the tick controller and endpoints receive `settin
232
232
 
233
233
  ```typescript
234
234
  import type { RunFunction } from '@seriousgaming/sdk';
235
+
235
236
  import type { Context, Settings } from './types';
236
237
 
237
238
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -253,6 +254,7 @@ A game UI, session UI and waiting room UI read `settings` from their data hook:
253
254
 
254
255
  ```tsx
255
256
  import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
257
+
256
258
  import type { Context, Settings } from '../types';
257
259
 
258
260
  function PricePanel() {
@@ -293,7 +295,7 @@ Keep a value in a capability only when it changes during play, or when it is com
293
295
 
294
296
  ## The game settings
295
297
 
296
- Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
298
+ Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, whether one link may join the whole session, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
297
299
 
298
300
  | Setting | The game's value, in `seriousgaming.sdk.json` | What it does |
299
301
  | --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
@@ -301,6 +303,7 @@ Every game has one built-in settings resource, `game`, holding the game-level se
301
303
  | `teams.min`, `teams.max` | `teams.min` and `teams.max`, or `null` for no bound | The fewest teams play can start with, and the most a session can hold |
302
304
  | `teams.perTeam.minParticipants`, `.maxParticipants` | `teams.perTeam`, or `null` | Guidance on team size shown to the facilitator, never a limit on joining |
303
305
  | `teams.defaultNames` | `teams.defaultNames`, or `[]` | The names teams start with, by team index. A facilitator or the team can rename |
306
+ | `teams.sessionJoin` | `teams.sessionJoin`, or `true` | Whether the host may offer one join link for the whole session |
304
307
  | `waitingRoom.openOnStart` | `waitingRoom.openOnStart`, or `false` | Whether a new session starts with participants held in the waiting room |
305
308
 
306
309
  `teams.mode` stays in the manifest and is not a setting: a game is independent or shared-state, and nothing can change that.
@@ -312,9 +315,10 @@ Override the game settings as you would any other, under `game`:
312
315
  - **`sdk configure`** sets them on the dev server: `pnpm run sdk configure '{"game":{"maxTicks":6}}'`
313
316
  - **Any resource can read them** by listing `game` in its `settings`, and its generated `types.ts` types them
314
317
 
315
- Two rules are particular to these settings:
318
+ Three rules are particular to these settings:
316
319
 
317
320
  - **`waitingRoom.openOnStart` is set by the game or a scenario, never by setup.** It takes effect as the session is created, before setup runs, so a setup value would do nothing, and is refused
321
+ - **`teams.sessionJoin` is set by the game or a scenario, never by setup.** It is read as the session is created, because people can follow the session link before play starts, so a setup value is refused. Set it to `false` when your teams are not interchangeable, such as one role per team or teams set up by index: the host places whoever follows the session link in a team of its own choosing, so a game like that hands out team links instead (see [useSessionUserInterfaceSessionJoinLink](./session-hooks.md#usesessionuserinterfacesessionjoinlink))
318
322
  - **Play cannot start outside the team bounds.** Setup can change `teams.min` and `teams.max` after the teams were created, so play is refused while the team count is outside them. Add or remove teams, or change the setting, and start again
319
323
 
320
324
  A settings resource of your own may not be called `game`, and is refused with a message saying what to change.
@@ -62,8 +62,9 @@ setup/
62
62
  Spreading `settings` into an update is safe: an unchanged value is never stored as a facilitator override, so a scenario chosen later still applies to it.
63
63
 
64
64
  ```tsx
65
- import { useSettingsEditor } from '@seriousgaming/sdk/ui';
66
65
  import { Stack, TextField } from '@mui/material';
66
+ import { useSettingsEditor } from '@seriousgaming/sdk/ui';
67
+
67
68
  import type { Settings } from '../types';
68
69
 
69
70
  function SetupForm() {
@@ -116,8 +117,8 @@ A write is also refused, as `denied` and with none of it applied, when it change
116
117
  `useSettingsEditorCallbacks()` gives the screen `requestPlay`, which leaves the configuration step exactly as the host's Play control does:
117
118
 
118
119
  ```tsx
119
- import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
120
120
  import { Button } from '@mui/material';
121
+ import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
121
122
 
122
123
  function StartButton() {
123
124
  const { requestPlay } = useSettingsEditorCallbacks();
@@ -150,6 +151,24 @@ Setup is embedded in the host's page, not a page of its own:
150
151
 
151
152
  The [session UI guide](./session.md#rendering-inside-the-host) covers the same ground in more detail.
152
153
 
154
+ ## Notes for assistants
155
+
156
+ An AI assistant can set a session up for a facilitator, changing the settings your setup screen `configures`. From the schemas alone it cannot tell which few settings matter, or what 'make it a bit harder' means in your game. Tell it in setup notes: Markdown at `setup/notes/<locale>.md`, one file per locale.
157
+
158
+ ```markdown
159
+ ## What requests mean
160
+
161
+ - **'Harder'**: lower `engine.BaseDemand` to 7,000 and raise `engine.DemandPriceModifier` to 700
162
+ - **'Shorter'**: set `game.maxTicks` to 6
163
+ ```
164
+
165
+ - **Name each setting as a setting path in a code span**, such as `engine.BaseDemand`: an assistant writes it back as it stands. The build checks every code span that starts with one of your settings identifiers, failing on one that names no setting (`SETTINGS_UNKNOWN`) and warning on one your setup screen does not configure (`SETUP_NOTES_UNCONFIGURED`)
166
+ - **Say what a schema cannot**: the two to five choices worth asking about, what common requests mean as settings and values, and what to leave alone. Where a request matches a scenario, say to pick that scenario
167
+ - **They are for assistants.** Your setup screen is what a facilitator sees, and a host need not show the notes to anyone. They grant nothing: an assistant is held to `configures` and to your game's [Scenario gate](./validators.md#when-it-runs) like anyone else
168
+ - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
169
+
170
+ The build ships them as written. In the dev server, **Notes for assistants** on the configuration step shows them exactly as an assistant receives them. `examples/factory` has a set; see [Write setup notes for assistants](../recipes/write-setup-notes.md), and [Describe a setup with an endpoint](../recipes/describe-setup-with-endpoint.md) to let an assistant read a setup back in your game's words.
171
+
153
172
  ## Dev server behaviour
154
173
 
155
174
  `pnpm run sdk dev` opens a game with a setup slot at its configuration step, on `/setup`. Fill in the form and press Play (or your own control). Once play starts, `/setup` shows that the step has closed; **Reconfigure** in the dev drawer returns the session to it and every team to tick 0. Overrides persist in `.seriousgaming-sdk/` between runs, and `pnpm run sdk configure` sets them from the command line.
@@ -173,6 +192,7 @@ Deleting the slot removes the configuration step: the game then starts at tick 0
173
192
 
174
193
  ```tsx
175
194
  import { renderSettingsEditor } from '@seriousgaming/sdk/ui/testing';
195
+
176
196
  import { defaultSettings } from '../defaults';
177
197
 
178
198
  renderSettingsEditor(<SetupForm />, {
@@ -188,3 +208,4 @@ See [Test a user interface](../recipes/test-user-interface.md).
188
208
  - [Settings](./settings.md): declaring, reading, and overriding settings
189
209
  - [Scenarios](./scenarios.md)
190
210
  - [Create a setup screen](../recipes/create-setup.md)
211
+ - [Write setup notes for assistants](../recipes/write-setup-notes.md)
@@ -123,6 +123,7 @@ For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5
123
123
 
124
124
  ```typescript
125
125
  import type { RunFunction } from '@seriousgaming/sdk';
126
+
126
127
  import type { Context, Settings, Callbacks } from '../types';
127
128
 
128
129
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({
@@ -47,6 +47,7 @@ Every capability variable must declare a `default` for this to work. The build s
47
47
  // engine/logic.test.ts
48
48
  import { logicArgs } from '@seriousgaming/sdk/testing';
49
49
  import { describe, it, expect } from 'vitest';
50
+
50
51
  import { defaultSettings, defaultContext } from './defaults';
51
52
  import { Run } from './logic';
52
53
  import type { Context, Settings } from './types';
@@ -122,6 +123,7 @@ describe('Warehouse Init', () => {
122
123
 
123
124
  ```typescript
124
125
  import { logicArgs } from '@seriousgaming/sdk/testing';
126
+
125
127
  import { defaultSettings, defaultSharedContext, defaultTeamContext } from './defaults';
126
128
  import { RunAggregate } from './logic';
127
129
 
@@ -78,6 +78,7 @@ The generated `tick_controller/logic.ts` exports a `GetTickController` function.
78
78
 
79
79
  ```typescript
80
80
  import { GetTickControllerFunction, intervalTick } from '@seriousgaming/sdk';
81
+
81
82
  import type { Context, Settings } from './types';
82
83
 
83
84
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -444,6 +445,7 @@ The SDK provides helpers that compute the next occurrence of a daily or weekly t
444
445
 
445
446
  ```typescript
446
447
  import { GetTickControllerFunction, nextDailyAt, scheduledTick } from '@seriousgaming/sdk';
448
+
447
449
  import type { Context, Settings } from './types';
448
450
 
449
451
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -45,9 +45,10 @@ export const Run: RunFunction<any, any> = async ({ context, settings, callbacks
45
45
  ### ✅ CORRECT: using generated types
46
46
 
47
47
  ```typescript
48
+ import { RunFunction } from '@seriousgaming/sdk';
49
+
48
50
  // logic.ts
49
51
  import type { Context, Settings } from './types';
50
- import { RunFunction } from '@seriousgaming/sdk';
51
52
 
52
53
  // ✅ CORRECT
53
54
  export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
@@ -149,6 +149,7 @@ The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
149
149
  ```typescript
150
150
  // endpoints/chat/logic/logic.ts
151
151
  import { getText } from '@seriousgaming/sdk';
152
+
152
153
  import type { Handler } from '../types';
153
154
 
154
155
  export const Handle: Handler = async ({ request, callbacks }) => {
@@ -178,8 +179,9 @@ The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no
178
179
  Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
179
180
 
180
181
  ```tsx
181
- import { useState } from 'react';
182
182
  import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
183
+ import { useState } from 'react';
184
+
183
185
  import type { Context, Settings } from '../types';
184
186
  import type { Callbacks } from '../types';
185
187
 
@@ -152,6 +152,7 @@ grep -rn "configuration" testing scripts
152
152
 
153
153
  ```typescript
154
154
  import type { RunFunction } from '@seriousgaming/sdk';
155
+
155
156
  import type { Context, Settings } from './types';
156
157
 
157
158
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -276,6 +277,7 @@ An engine that splits `Init` or `Run` into several functions typed as `RunFuncti
276
277
 
277
278
  ```typescript
278
279
  import type { RunFunction, StepFunction } from '@seriousgaming/sdk';
280
+
279
281
  import type { Context, Settings } from './types';
280
282
 
281
283
  export const runSales: StepFunction<Context, Settings> = async ({ context }) => ({
@@ -295,6 +297,7 @@ An aggregate engine split into steps works the same way. There is no step type f
295
297
 
296
298
  ```typescript
297
299
  import type { RunAggregateFunction } from '@seriousgaming/sdk';
300
+
298
301
  import type { Settings, SharedContext, TeamContext } from './types';
299
302
 
300
303
  type Board = { shared: SharedContext; teams: TeamContext[] };
@@ -550,6 +553,7 @@ Every logic call now receives `meta.now` (the operation's time in milliseconds)
550
553
 
551
554
  ```typescript
552
555
  import { logicArgs } from '@seriousgaming/sdk/testing';
556
+
553
557
  import { defaultSettings } from '../../engine/defaults';
554
558
 
555
559
  const result = await Run(logicArgs.run({ context, settings: defaultSettings }));
@@ -684,6 +688,18 @@ renderUserInterface(<App />, { callbacks: { requestTick } });
684
688
 
685
689
  These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
686
690
 
691
+ ### 1.7: turn off the session join link where teams are not interchangeable
692
+
693
+ A host may now offer one join link for the whole session and put each person who follows it in a team of its choosing. A game that gives each team a role, or sets teams up by index, should not offer it. Set it off in `seriousgaming.sdk.json` and rebuild:
694
+
695
+ ```json
696
+ {
697
+ "teams": { "mode": "independent", "sessionJoin": false }
698
+ }
699
+ ```
700
+
701
+ A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
702
+
687
703
  ### Optional: import the SDK's agent guidance in `CLAUDE.md`
688
704
 
689
705
  A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
@@ -110,7 +110,8 @@ Each validator is told who submitted the mutation, as `actor`:
110
110
 
111
111
  ```typescript
112
112
  type ValidatorActor =
113
- { role: 'participant'; participant: Participant } | { role: 'observer'; teamId: string };
113
+ | { role: 'participant'; participant: Participant }
114
+ | { role: 'observer'; teamId: string };
114
115
  ```
115
116
 
116
117
  It is a union rather than an optional participant, because these are two callers rather than an identity and the absence of one. `participant` is unreachable until you have narrowed on `role`, so a validator cannot read an identity it has not first decided it has.
@@ -288,8 +289,30 @@ const judge = (ui: Partial<Settings['ui']>) =>
288
289
  ### When it runs
289
290
 
290
291
  - **`sdk build`** runs it on every scenario in `scenarios/`, and on the defaults alone when no scenario is the default, since a session can then run on no scenario. A problem fails the build (`SCENARIO_REFUSED`), pointing at the setting in the scenario's file
291
- - **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed
292
- - **Never when a session starts.** By then its scenario has passed
292
+ - **Saving a scenario** runs it, from the scenario editor, a form the platform generates, or an agent writing settings, and a problem refuses the save with every problem listed. A gate that runs out of time is run once more first, since a busy host can push a sound gate over its time limit
293
+ - **As a session starts**, when the game lists `session-validation` in `requires`. It judges the session's own settings, what setup changed over the scenario, and a session it finds an error with does not start: the facilitator, or an agent setting the session up, sees every problem and changes the setting. A session nobody changed, on a scenario the build checked, is not judged again. Without `session-validation`, a session is never refused on the gate
294
+
295
+ ```json
296
+ "requires": ["scenario-validation", "session-validation"]
297
+ ```
298
+
299
+ In the dev server, Play shows the refusal or the warnings, `pnpm run sdk play` prints the warnings, and `pnpm run sdk configure` runs the gate before it saves anything, so a refused change is never written and a running session is left as it was.
300
+
301
+ A gate that throws also stops a session starting, and is reported as a fault in the game rather than in its settings, since changing a setting will not clear it. One that runs out of time is run once more first, since a busy host can push a sound gate over its time limit, and refuses only if it overruns again. Nothing overrides it, so test your gate against the settings your setup screen can produce. The build notes each settings resource your setup UI changes that no `Scenario` gate declares in its `settings` (`SETTINGS_UNGATED`): nothing checks those changes before play.
302
+
303
+ ### Errors and warnings
304
+
305
+ A problem is an error unless you say otherwise. Give it `level: 'warning'` for something unusual that may well be meant, such as a story week outside the rounds the game plays. A warning is reported wherever an error is, by the build (`SCENARIO_WARNING`), with a saved scenario and with a session start, and never refuses any of them:
306
+
307
+ ```typescript
308
+ problems.push({
309
+ path: settingPath('engine', 'CostPerUnit'),
310
+ level: 'warning',
311
+ message: 'Making a unit costs nothing, so unsold stock never costs a team anything',
312
+ });
313
+ ```
314
+
315
+ Keep errors for what breaks play, such as a document that never arrives. With `session-validation`, an error stops a facilitator starting their session, so a borderline case is better as a warning. `examples/factory`'s `scenariocheck` validator warns on a unit cost of £0.
293
316
 
294
317
  ### It judges values, not where they came from
295
318
 
@@ -305,7 +328,7 @@ The gate is the last word, and it runs on save. A [scenario editor](./scenario-e
305
328
 
306
329
  The gate reads no game state and receives no `actor` or `meta`: there is no session or participant behind a scenario. Its only callbacks are the file reads above. It ignores the validator's `reads`, so a validator that only exports `Scenario` declares none.
307
330
 
308
- The gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
331
+ Without `session-validation`, the gate runs when a scenario is saved, not each time one is used, so a scenario a facilitator saved before you added or tightened a rule has never met it. Bump `scenarioFormat` in `seriousgaming.sdk.json` when you do, and a runtime stops using those older scenarios. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
309
332
 
310
333
  ## Settings
311
334
 
@@ -81,6 +81,7 @@ Same as any game UI. Declare the capability in `reads`, regenerate, and read it
81
81
 
82
82
  ```typescript
83
83
  import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
84
+
84
85
  import type { Context, Settings } from '../types';
85
86
 
86
87
  function App() {
@@ -182,6 +183,7 @@ Opening the room pauses nothing. The decision belongs to the game, because only
182
183
 
183
184
  ```typescript
184
185
  import type { GetTickControllerFunction } from '@seriousgaming/sdk';
186
+
185
187
  import type { Context, Settings } from '../types';
186
188
 
187
189
  export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
@@ -25,8 +25,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
25
25
  - [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
26
26
  - [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
27
27
  - [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
28
- - [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
29
- - [`cli-reference.md`](cli-reference.md), about 161k characters: Every `seriousgaming-sdk` command and flag, in one place.
28
+ - [`cli-error-codes.md`](cli-error-codes.md), about 32k characters: Every code a failed `seriousgaming-sdk` command can report.
29
+ - [`cli-reference.md`](cli-reference.md), about 163k characters: Every `seriousgaming-sdk` command and flag, in one place.
30
30
  - [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
31
31
  - [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
32
32
  - [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
@@ -56,15 +56,15 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
56
56
  - [`guides/llm-integration.md`](guides/llm-integration.md), about 26k characters: Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
57
57
  - [`guides/multi-team-games.md`](guides/multi-team-games.md), about 35k characters: Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
58
58
  - [`guides/patterns.md`](guides/patterns.md), about 12k characters: Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern.
59
- - [`guides/presentation.md`](guides/presentation.md), about 16k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
59
+ - [`guides/presentation.md`](guides/presentation.md), about 17k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
60
60
  - [`guides/production-constraints.md`](guides/production-constraints.md), about 10k characters: In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
61
61
  - [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
62
62
  - [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
63
63
  - [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
64
- - [`guides/session-hooks.md`](guides/session-hooks.md), about 14k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
64
+ - [`guides/session-hooks.md`](guides/session-hooks.md), about 15k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
65
65
  - [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
66
66
  - [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
67
- - [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
67
+ - [`guides/setup.md`](guides/setup.md), about 11k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
68
68
  - [`guides/speech-generation.md`](guides/speech-generation.md), about 10k characters: Give characters and briefings a voice: generate speech from server-side logic and play it in any UI.
69
69
  - [`guides/starter-game.md`](guides/starter-game.md), about 18k characters: `new package` hands you Lemonade Stand, a complete game rather than an empty shell.
70
70
  - [`guides/testing.md`](guides/testing.md), about 34k characters: Test your engine's logic and your user interfaces, so a broken rule or a broken screen fails on your machine rather than in front of a room.
@@ -76,8 +76,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
76
76
  - [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
77
77
  - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
78
  - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
- - [`guides/upgrading.md`](guides/upgrading.md), about 67k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
- - [`guides/validators.md`](guides/validators.md), about 23k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
79
+ - [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
+ - [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
81
  - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
82
82
 
83
83
  ## Recipes
@@ -105,6 +105,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
105
105
  - [`recipes/create-validator.md`](recipes/create-validator.md), about 4k characters: Reject a participant's write that breaks the game's rules, before the runtime applies it.
106
106
  - [`recipes/create-waiting-room-ui.md`](recipes/create-waiting-room-ui.md), about 5k characters: Replace the host's stock holding screen with your own, so participants see your branding and your words while the facilitator has the waiting room open.
107
107
  - [`recipes/declare-api-uses.md`](recipes/declare-api-uses.md), about 4k characters: A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call.
108
+ - [`recipes/describe-setup-with-endpoint.md`](recipes/describe-setup-with-endpoint.md), about 3k characters: Let an assistant, or your own setup screen, ask your game to describe a session's settings in the game's own words before it starts.
108
109
  - [`recipes/design-state-for-concurrent-writes.md`](recipes/design-state-for-concurrent-writes.md), about 6k characters: Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other.
109
110
  - [`recipes/distribute-package.md`](recipes/distribute-package.md), about 3k characters: Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
110
111
  - [`recipes/e2e-testing.md`](recipes/e2e-testing.md), about 6k characters: Test your game's screens in a real browser against an isolated dev server.
@@ -129,7 +130,8 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
129
130
  - [`recipes/upload-and-display-files.md`](recipes/upload-and-display-files.md), about 6k characters: Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
130
131
  - [`recipes/use-request-play.md`](recipes/use-request-play.md), about 2k characters: Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
131
132
  - [`recipes/use-request-tick.md`](recipes/use-request-tick.md), about 3k characters: Trigger the next game tick from within your user interface, so participants submit their decisions via your own button.
132
- - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 4k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
133
+ - [`recipes/validate-scenarios.md`](recipes/validate-scenarios.md), about 5k characters: Refuse a scenario whose settings break your game's rules, at build and when one is saved, and optionally a session whose setup breaks them.
134
+ - [`recipes/write-setup-notes.md`](recipes/write-setup-notes.md), about 3k characters: Tell an AI assistant setting a session up which of your game's settings matter, and what a request such as 'make it a bit harder' means in your game.
133
135
 
134
136
  ## API reference
135
137
 
@@ -142,5 +144,5 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
142
144
  - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
143
145
  - [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
144
146
  - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
145
- - [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
146
- - [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
147
+ - [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
148
+ - [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.
@@ -27,6 +27,7 @@ Call a server-side endpoint from any of your game's screens and handle its respo
27
27
 
28
28
  ```tsx
29
29
  import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
30
+
30
31
  import type { Callbacks } from '../types';
31
32
 
32
33
  function ReportButton({ reportText }: { reportText: string }) {
@@ -44,8 +44,9 @@ This creates `scenario_editor/` with `scenario_editor.sdk.json`, `index.html`, `
44
44
  Open `scenario_editor/src/App.tsx`. It uses the same hooks as setup:
45
45
 
46
46
  ```tsx
47
- import { useSettingsEditor } from '@seriousgaming/sdk/ui';
48
47
  import { Stack, TextField } from '@mui/material';
48
+ import { useSettingsEditor } from '@seriousgaming/sdk/ui';
49
+
49
50
  import type { Settings } from '../types';
50
51
 
51
52
  function App() {
@@ -48,8 +48,9 @@ setup/
48
48
  Open `setup/src/App.tsx`. Read and write the settings with `useSettingsEditor`, typed by the generated `Settings`:
49
49
 
50
50
  ```tsx
51
- import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
52
51
  import { Button, Stack, TextField } from '@mui/material';
52
+ import { useSettingsEditor, useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
53
+
53
54
  import type { Settings } from '../types';
54
55
 
55
56
  function App() {
@@ -30,6 +30,7 @@ A logic-bearing resource (engine, hook, tick controller, endpoint) must declare
30
30
 
31
31
  ```typescript
32
32
  import { getText, type RunFunction } from '@seriousgaming/sdk';
33
+
33
34
  import type { Context, Settings, Callbacks } from './types';
34
35
 
35
36
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({