@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
@@ -203,6 +203,14 @@ Hook to access all participants across all teams in the session.
203
203
  const useSessionUserInterfaceParticipants: () => Participant[];
204
204
  ```
205
205
 
206
+ ### useSessionUserInterfaceSessionJoinLink
207
+
208
+ Hook returning the session's one join link, or `null` when there is none to show.
209
+
210
+ ```ts
211
+ const useSessionUserInterfaceSessionJoinLink: () => SessionJoinLink | null;
212
+ ```
213
+
206
214
  ### useSessionUserInterfaceTeamConfiguration
207
215
 
208
216
  Hook to access the session's interaction mode and team bounds.
@@ -450,7 +458,7 @@ class TickSnapshotError extends Error {
450
458
  Provided by every surface wrapper. Exported for the test helpers, which provide it without a host; game code reads it through `useAssetUrl` and `useAsset`.
451
459
 
452
460
  ```ts
453
- const AssetContext: import('react').Context<AssetScope | undefined>;
461
+ const AssetContext: import("react").Context<AssetScope | undefined>;
454
462
  ```
455
463
 
456
464
  ### PastStateContext
@@ -458,7 +466,7 @@ const AssetContext: import('react').Context<AssetScope | undefined>;
458
466
  Provided by the wrappers whose surfaces can read past state: the player, session and presentation wrappers. Exported for the test helpers, which provide it without a host; game code reads it through `usePastState`.
459
467
 
460
468
  ```ts
461
- const PastStateContext: import('react').Context<PastStateReader | undefined>;
469
+ const PastStateContext: import("react").Context<PastStateReader | undefined>;
462
470
  ```
463
471
 
464
472
  ### PresentationContext
@@ -466,9 +474,7 @@ const PastStateContext: import('react').Context<PastStateReader | undefined>;
466
474
  The React context behind `usePresentation`.
467
475
 
468
476
  ```ts
469
- const PresentationContext: import('react').Context<
470
- PresentationValue<unknown, unknown, unknown> | undefined
471
- >;
477
+ const PresentationContext: import("react").Context<PresentationValue<unknown, unknown, unknown> | undefined>;
472
478
  ```
473
479
 
474
480
  ### SessionUserInterfaceCallbacksContext
@@ -476,9 +482,7 @@ const PresentationContext: import('react').Context<
476
482
  The React context behind `useSessionUserInterfaceCallbacks`.
477
483
 
478
484
  ```ts
479
- const SessionUserInterfaceCallbacksContext: import('react').Context<
480
- SessionUserInterfaceCallbacks | undefined
481
- >;
485
+ const SessionUserInterfaceCallbacksContext: import("react").Context<SessionUserInterfaceCallbacks | undefined>;
482
486
  ```
483
487
 
484
488
  ### SessionUserInterfaceDataContext
@@ -486,15 +490,7 @@ const SessionUserInterfaceCallbacksContext: import('react').Context<
486
490
  The React context behind `useSessionUserInterfaceData`.
487
491
 
488
492
  ```ts
489
- const SessionUserInterfaceDataContext: import('react').Context<
490
- | SessionUserInterfaceDataContextValue<
491
- SessionData<object, object>,
492
- unknown,
493
- Record<string, unknown>,
494
- Record<string, unknown>
495
- >
496
- | undefined
497
- >;
493
+ const SessionUserInterfaceDataContext: import("react").Context<SessionUserInterfaceDataContextValue<SessionData<object, object>, unknown, Record<string, unknown>, Record<string, unknown>> | undefined>;
498
494
  ```
499
495
 
500
496
  ### SessionUserInterfaceHookFailuresContext
@@ -502,9 +498,7 @@ const SessionUserInterfaceDataContext: import('react').Context<
502
498
  The React context behind `useSessionUserInterfaceHookFailures`.
503
499
 
504
500
  ```ts
505
- const SessionUserInterfaceHookFailuresContext: import('react').Context<
506
- SessionUserInterfaceHookFailuresValue | undefined
507
- >;
501
+ const SessionUserInterfaceHookFailuresContext: import("react").Context<SessionUserInterfaceHookFailuresValue | undefined>;
508
502
  ```
509
503
 
510
504
  ### SessionUserInterfaceHostOverlaysContext
@@ -512,7 +506,7 @@ const SessionUserInterfaceHookFailuresContext: import('react').Context<
512
506
  The React context behind `useSessionUserInterfaceHostOverlays`.
513
507
 
514
508
  ```ts
515
- const SessionUserInterfaceHostOverlaysContext: import('react').Context<HostOverlay[]>;
509
+ const SessionUserInterfaceHostOverlaysContext: import("react").Context<HostOverlay[]>;
516
510
  ```
517
511
 
518
512
  ### SessionUserInterfaceLocaleContext
@@ -520,9 +514,7 @@ const SessionUserInterfaceHostOverlaysContext: import('react').Context<HostOverl
520
514
  The React context behind `useSessionUserInterfaceLocale`.
521
515
 
522
516
  ```ts
523
- const SessionUserInterfaceLocaleContext: import('react').Context<
524
- SessionUserInterfaceLocale | undefined
525
- >;
517
+ const SessionUserInterfaceLocaleContext: import("react").Context<SessionUserInterfaceLocale | undefined>;
526
518
  ```
527
519
 
528
520
  ### SessionUserInterfaceMetaContext
@@ -530,7 +522,7 @@ const SessionUserInterfaceLocaleContext: import('react').Context<
530
522
  The React context behind `useSessionUserInterfaceMeta`.
531
523
 
532
524
  ```ts
533
- const SessionUserInterfaceMetaContext: import('react').Context<SessionMeta | undefined>;
525
+ const SessionUserInterfaceMetaContext: import("react").Context<SessionMeta | undefined>;
534
526
  ```
535
527
 
536
528
  ### SessionUserInterfaceParticipantsContext
@@ -538,7 +530,15 @@ const SessionUserInterfaceMetaContext: import('react').Context<SessionMeta | und
538
530
  The React context behind `useSessionUserInterfaceParticipants`.
539
531
 
540
532
  ```ts
541
- const SessionUserInterfaceParticipantsContext: import('react').Context<Participant[] | undefined>;
533
+ const SessionUserInterfaceParticipantsContext: import("react").Context<Participant[] | undefined>;
534
+ ```
535
+
536
+ ### SessionUserInterfaceSessionJoinLinkContext
537
+
538
+ The React context behind `useSessionUserInterfaceSessionJoinLink`.
539
+
540
+ ```ts
541
+ const SessionUserInterfaceSessionJoinLinkContext: import("react").Context<SessionJoinLink | null>;
542
542
  ```
543
543
 
544
544
  ### SessionUserInterfaceTeamConfigurationContext
@@ -546,7 +546,7 @@ const SessionUserInterfaceParticipantsContext: import('react').Context<Participa
546
546
  The React context behind `useSessionUserInterfaceTeamConfiguration`.
547
547
 
548
548
  ```ts
549
- const SessionUserInterfaceTeamConfigurationContext: import('react').Context<TeamConfiguration>;
549
+ const SessionUserInterfaceTeamConfigurationContext: import("react").Context<TeamConfiguration>;
550
550
  ```
551
551
 
552
552
  ### SessionUserInterfaceTeamLinksContext
@@ -554,7 +554,7 @@ const SessionUserInterfaceTeamConfigurationContext: import('react').Context<Team
554
554
  The React context behind `useSessionUserInterfaceTeamLinks`.
555
555
 
556
556
  ```ts
557
- const SessionUserInterfaceTeamLinksContext: import('react').Context<TeamLinks[]>;
557
+ const SessionUserInterfaceTeamLinksContext: import("react").Context<TeamLinks[]>;
558
558
  ```
559
559
 
560
560
  ### SessionUserInterfaceTeamsContext
@@ -562,7 +562,7 @@ const SessionUserInterfaceTeamLinksContext: import('react').Context<TeamLinks[]>
562
562
  The React context behind `useSessionUserInterfaceTeams`.
563
563
 
564
564
  ```ts
565
- const SessionUserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
565
+ const SessionUserInterfaceTeamsContext: import("react").Context<TeamInfo[]>;
566
566
  ```
567
567
 
568
568
  ### SessionUserInterfaceThemeContext
@@ -570,9 +570,7 @@ const SessionUserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
570
570
  The React context behind `useSessionUserInterfaceTheme`.
571
571
 
572
572
  ```ts
573
- const SessionUserInterfaceThemeContext: import('react').Context<
574
- SessionUserInterfaceTheme | undefined
575
- >;
573
+ const SessionUserInterfaceThemeContext: import("react").Context<SessionUserInterfaceTheme | undefined>;
576
574
  ```
577
575
 
578
576
  ### SessionUserInterfaceThemePreferenceContext
@@ -580,9 +578,7 @@ const SessionUserInterfaceThemeContext: import('react').Context<
580
578
  The React context behind `useSessionUserInterfaceThemePreference`.
581
579
 
582
580
  ```ts
583
- const SessionUserInterfaceThemePreferenceContext: import('react').Context<
584
- ThemePreference | undefined
585
- >;
581
+ const SessionUserInterfaceThemePreferenceContext: import("react").Context<ThemePreference | undefined>;
586
582
  ```
587
583
 
588
584
  ### SessionUserInterfaceWalkthroughLinkContext
@@ -590,7 +586,7 @@ const SessionUserInterfaceThemePreferenceContext: import('react').Context<
590
586
  The React context behind `useSessionUserInterfaceWalkthroughLink`.
591
587
 
592
588
  ```ts
593
- const SessionUserInterfaceWalkthroughLinkContext: import('react').Context<WalkthroughLink | null>;
589
+ const SessionUserInterfaceWalkthroughLinkContext: import("react").Context<WalkthroughLink | null>;
594
590
  ```
595
591
 
596
592
  ### SettingsEditorCallbacksContext
@@ -598,7 +594,7 @@ const SessionUserInterfaceWalkthroughLinkContext: import('react').Context<Walkth
598
594
  The React context behind `useSettingsEditorCallbacks`.
599
595
 
600
596
  ```ts
601
- const SettingsEditorCallbacksContext: import('react').Context<SettingsEditorCallbacks | undefined>;
597
+ const SettingsEditorCallbacksContext: import("react").Context<SettingsEditorCallbacks | undefined>;
602
598
  ```
603
599
 
604
600
  ### SettingsEditorContext
@@ -606,7 +602,7 @@ const SettingsEditorCallbacksContext: import('react').Context<SettingsEditorCall
606
602
  The React context behind `useSettingsEditor`.
607
603
 
608
604
  ```ts
609
- const SettingsEditorContext: import('react').Context<SettingsEditorValue<unknown> | undefined>;
605
+ const SettingsEditorContext: import("react").Context<SettingsEditorValue<unknown> | undefined>;
610
606
  ```
611
607
 
612
608
  ### SettingsEditorLocaleContext
@@ -614,7 +610,7 @@ const SettingsEditorContext: import('react').Context<SettingsEditorValue<unknown
614
610
  The React context behind `useSettingsEditorLocale`.
615
611
 
616
612
  ```ts
617
- const SettingsEditorLocaleContext: import('react').Context<SettingsEditorLocale | undefined>;
613
+ const SettingsEditorLocaleContext: import("react").Context<SettingsEditorLocale | undefined>;
618
614
  ```
619
615
 
620
616
  ### SettingsEditorThemeContext
@@ -622,7 +618,7 @@ const SettingsEditorLocaleContext: import('react').Context<SettingsEditorLocale
622
618
  The React context behind `useSettingsEditorTheme`.
623
619
 
624
620
  ```ts
625
- const SettingsEditorThemeContext: import('react').Context<SettingsEditorTheme | undefined>;
621
+ const SettingsEditorThemeContext: import("react").Context<SettingsEditorTheme | undefined>;
626
622
  ```
627
623
 
628
624
  ### SettingsEditorThemePreferenceContext
@@ -630,7 +626,7 @@ const SettingsEditorThemeContext: import('react').Context<SettingsEditorTheme |
630
626
  The React context behind `useSettingsEditorThemePreference`.
631
627
 
632
628
  ```ts
633
- const SettingsEditorThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
629
+ const SettingsEditorThemePreferenceContext: import("react").Context<ThemePreference | undefined>;
634
630
  ```
635
631
 
636
632
  ### SurfaceThemeContext
@@ -638,7 +634,7 @@ const SettingsEditorThemePreferenceContext: import('react').Context<ThemePrefere
638
634
  The theme of whichever surface is rendering, for the hooks every surface shares. Provided by every wrapper; game code reads it through `useBrand`, `useBrandLogo` and `useBrandIcon`.
639
635
 
640
636
  ```ts
641
- const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
637
+ const SurfaceThemeContext: import("react").Context<SurfaceTheme | undefined>;
642
638
  ```
643
639
 
644
640
  ### UserInterfaceCallbacksContext
@@ -646,7 +642,7 @@ const SurfaceThemeContext: import('react').Context<SurfaceTheme | undefined>;
646
642
  The React context behind `useUserInterfaceCallbacks`.
647
643
 
648
644
  ```ts
649
- const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
645
+ const UserInterfaceCallbacksContext: import("react").Context<UserInterfaceCallbacks | undefined>;
650
646
  ```
651
647
 
652
648
  ### UserInterfaceCanRenameSelfContext
@@ -654,7 +650,7 @@ const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallba
654
650
  The React context behind `useUserInterfaceCanRenameSelf`.
655
651
 
656
652
  ```ts
657
- const UserInterfaceCanRenameSelfContext: import('react').Context<boolean>;
653
+ const UserInterfaceCanRenameSelfContext: import("react").Context<boolean>;
658
654
  ```
659
655
 
660
656
  ### UserInterfaceCrossTeamDataContext
@@ -662,7 +658,7 @@ const UserInterfaceCanRenameSelfContext: import('react').Context<boolean>;
662
658
  The React context behind `useUserInterfaceCrossTeamData`.
663
659
 
664
660
  ```ts
665
- const UserInterfaceCrossTeamDataContext: import('react').Context<CrossTeamData | undefined>;
661
+ const UserInterfaceCrossTeamDataContext: import("react").Context<CrossTeamData | undefined>;
666
662
  ```
667
663
 
668
664
  ### UserInterfaceDataContext
@@ -670,9 +666,7 @@ const UserInterfaceCrossTeamDataContext: import('react').Context<CrossTeamData |
670
666
  The React context behind `useUserInterfaceData`.
671
667
 
672
668
  ```ts
673
- const UserInterfaceDataContext: import('react').Context<
674
- UserInterfaceDataContextValue<unknown, unknown> | undefined
675
- >;
669
+ const UserInterfaceDataContext: import("react").Context<UserInterfaceDataContextValue<unknown, unknown> | undefined>;
676
670
  ```
677
671
 
678
672
  ### UserInterfaceLocaleContext
@@ -680,7 +674,7 @@ const UserInterfaceDataContext: import('react').Context<
680
674
  The React context behind `useUserInterfaceLocale`.
681
675
 
682
676
  ```ts
683
- const UserInterfaceLocaleContext: import('react').Context<UserInterfaceLocale | undefined>;
677
+ const UserInterfaceLocaleContext: import("react").Context<UserInterfaceLocale | undefined>;
684
678
  ```
685
679
 
686
680
  ### UserInterfaceOwnTeamContext
@@ -688,7 +682,7 @@ const UserInterfaceLocaleContext: import('react').Context<UserInterfaceLocale |
688
682
  The React context behind `useUserInterfaceOwnTeam`.
689
683
 
690
684
  ```ts
691
- const UserInterfaceOwnTeamContext: import('react').Context<TeamInfo | null>;
685
+ const UserInterfaceOwnTeamContext: import("react").Context<TeamInfo | null>;
692
686
  ```
693
687
 
694
688
  ### UserInterfaceOwnTeamJoinLinkContext
@@ -696,7 +690,7 @@ const UserInterfaceOwnTeamContext: import('react').Context<TeamInfo | null>;
696
690
  The React context behind `useUserInterfaceOwnTeamJoinLink`.
697
691
 
698
692
  ```ts
699
- const UserInterfaceOwnTeamJoinLinkContext: import('react').Context<OwnTeamJoinLink | null>;
693
+ const UserInterfaceOwnTeamJoinLinkContext: import("react").Context<OwnTeamJoinLink | null>;
700
694
  ```
701
695
 
702
696
  ### UserInterfaceParticipantContext
@@ -704,7 +698,7 @@ const UserInterfaceOwnTeamJoinLinkContext: import('react').Context<OwnTeamJoinLi
704
698
  The React context behind `useUserInterfaceParticipant`.
705
699
 
706
700
  ```ts
707
- const UserInterfaceParticipantContext: import('react').Context<Participant | null | undefined>;
701
+ const UserInterfaceParticipantContext: import("react").Context<Participant | null | undefined>;
708
702
  ```
709
703
 
710
704
  ### UserInterfaceParticipantsContext
@@ -712,7 +706,7 @@ const UserInterfaceParticipantContext: import('react').Context<Participant | nul
712
706
  The React context behind `useUserInterfaceParticipants`.
713
707
 
714
708
  ```ts
715
- const UserInterfaceParticipantsContext: import('react').Context<Participant[]>;
709
+ const UserInterfaceParticipantsContext: import("react").Context<Participant[]>;
716
710
  ```
717
711
 
718
712
  ### UserInterfaceRunKindContext
@@ -720,7 +714,7 @@ const UserInterfaceParticipantsContext: import('react').Context<Participant[]>;
720
714
  The React context behind `useRunKind`.
721
715
 
722
716
  ```ts
723
- const UserInterfaceRunKindContext: import('react').Context<RunKind>;
717
+ const UserInterfaceRunKindContext: import("react").Context<RunKind>;
724
718
  ```
725
719
 
726
720
  ### UserInterfaceTeamsContext
@@ -728,7 +722,7 @@ const UserInterfaceRunKindContext: import('react').Context<RunKind>;
728
722
  The React context behind `useUserInterfaceTeams`.
729
723
 
730
724
  ```ts
731
- const UserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
725
+ const UserInterfaceTeamsContext: import("react").Context<TeamInfo[]>;
732
726
  ```
733
727
 
734
728
  ### UserInterfaceThemeContext
@@ -736,7 +730,7 @@ const UserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
736
730
  The React context behind `useUserInterfaceTheme`.
737
731
 
738
732
  ```ts
739
- const UserInterfaceThemeContext: import('react').Context<UserInterfaceTheme | undefined>;
733
+ const UserInterfaceThemeContext: import("react").Context<UserInterfaceTheme | undefined>;
740
734
  ```
741
735
 
742
736
  ### UserInterfaceThemePreferenceContext
@@ -744,7 +738,7 @@ const UserInterfaceThemeContext: import('react').Context<UserInterfaceTheme | un
744
738
  The React context behind `useUserInterfaceThemePreference`.
745
739
 
746
740
  ```ts
747
- const UserInterfaceThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
741
+ const UserInterfaceThemePreferenceContext: import("react").Context<ThemePreference | undefined>;
748
742
  ```
749
743
 
750
744
  ### UserInterfaceTimerContext
@@ -752,7 +746,7 @@ const UserInterfaceThemePreferenceContext: import('react').Context<ThemePreferen
752
746
  The React context behind `useUserInterfaceTimer`.
753
747
 
754
748
  ```ts
755
- const UserInterfaceTimerContext: import('react').Context<TimerState>;
749
+ const UserInterfaceTimerContext: import("react").Context<TimerState>;
756
750
  ```
757
751
 
758
752
  ### UserInterfaceValidationRejectionsContext
@@ -760,9 +754,7 @@ const UserInterfaceTimerContext: import('react').Context<TimerState>;
760
754
  The React context behind `useUserInterfaceValidationRejections`.
761
755
 
762
756
  ```ts
763
- const UserInterfaceValidationRejectionsContext: import('react').Context<
764
- UserInterfaceValidationRejectionsValue | undefined
765
- >;
757
+ const UserInterfaceValidationRejectionsContext: import("react").Context<UserInterfaceValidationRejectionsValue | undefined>;
766
758
  ```
767
759
 
768
760
  ### UserInterfaceViewerRoleContext
@@ -770,7 +762,7 @@ const UserInterfaceValidationRejectionsContext: import('react').Context<
770
762
  The React context behind `useUserInterfaceViewerRole`.
771
763
 
772
764
  ```ts
773
- const UserInterfaceViewerRoleContext: import('react').Context<ViewerRole>;
765
+ const UserInterfaceViewerRoleContext: import("react").Context<ViewerRole>;
774
766
  ```
775
767
 
776
768
  ### ViewerStorageContext
@@ -778,7 +770,7 @@ const UserInterfaceViewerRoleContext: import('react').Context<ViewerRole>;
778
770
  Provided by every surface wrapper. Exported for the test helpers, which provide it without a host; game code reads it through `useViewerStorage`.
779
771
 
780
772
  ```ts
781
- const ViewerStorageContext: import('react').Context<ViewerStorageScope | undefined>;
773
+ const ViewerStorageContext: import("react").Context<ViewerStorageScope | undefined>;
782
774
  ```
783
775
 
784
776
  ## Interfaces
@@ -976,6 +968,7 @@ interface PresentationSession<
976
968
  participants?: Participant[];
977
969
  joinLinks?: PresentationJoinLink[];
978
970
  joinPin?: string | null;
971
+ sessionJoinLink?: SessionJoinLink | null;
979
972
  }
980
973
  ```
981
974
 
@@ -1327,6 +1320,17 @@ type SessionData<
1327
1320
  };
1328
1321
  ```
1329
1322
 
1323
+ ### SessionJoinLink
1324
+
1325
+ One join link for the whole session: somebody who follows it is placed in a team by the host, rather than choosing one.
1326
+
1327
+ ```ts
1328
+ type SessionJoinLink = {
1329
+ joinUrl: string;
1330
+ fallbackJoinUrl?: string;
1331
+ };
1332
+ ```
1333
+
1330
1334
  ### SessionMeta
1331
1335
 
1332
1336
  The session's identity and lifecycle state, pushed on connect and again whenever any of it changes.
@@ -508,6 +508,7 @@ interface GameSettings {
508
508
  name: string;
509
509
  };
510
510
  }[];
511
+ sessionJoin?: boolean;
511
512
  };
512
513
  waitingRoom?: {
513
514
  openOnStart?: boolean;
@@ -530,6 +531,7 @@ interface GameSettingsConstraints {
530
531
  maxParticipants?: GameSettingConstraint;
531
532
  };
532
533
  defaultNames?: GameSettingConstraint;
534
+ sessionJoin?: GameSettingConstraint;
533
535
  };
534
536
  waitingRoom?: {
535
537
  openOnStart?: GameSettingConstraint;
@@ -1054,6 +1056,7 @@ One thing wrong with a scenario. `path` names the setting it is about as a setti
1054
1056
  interface ScenarioProblem {
1055
1057
  message: string;
1056
1058
  path?: string;
1059
+ level?: ScenarioProblemLevel;
1057
1060
  }
1058
1061
  ```
1059
1062
 
@@ -2184,7 +2187,7 @@ type ScenarioEndpointHandler<
2184
2187
 
2185
2188
  ### ScenarioFunction
2186
2189
 
2187
- A validator's `Scenario` export: the gate on a scenario. It runs at build on every package scenario, and on a session with no scenario when the game has no default, and when a custom scenario is saved. Never when a session is created. Returns every problem it finds; an empty array passes.
2190
+ A validator's `Scenario` export: the gate on a scenario. It runs at build on every package scenario, and on a session with no scenario when the game has no default, and when a custom scenario is saved. In a package that lists `session-validation` it also runs as a session starts, on the session's own settings. Returns every problem it finds; an empty array passes.
2188
2191
 
2189
2192
  ```ts
2190
2193
  type ScenarioFunction<TSettings = unknown> = (
@@ -2192,6 +2195,14 @@ type ScenarioFunction<TSettings = unknown> = (
2192
2195
  ) => Promise<ScenarioProblem[]>;
2193
2196
  ```
2194
2197
 
2198
+ ### ScenarioProblemLevel
2199
+
2200
+ How serious a `ScenarioProblem` is.
2201
+
2202
+ ```ts
2203
+ type ScenarioProblemLevel = 'error' | 'warning';
2204
+ ```
2205
+
2195
2206
  ### StepFunction
2196
2207
 
2197
2208
  One step of an engine that splits its `Init` or `Run` into several functions.
@@ -31,6 +31,32 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.8.0] — 2026-11-06
35
+
36
+ ### Added
37
+
38
+ - **A `Scenario` gate can stop a session starting.** List `session-validation` in `requires` (beside `scenario-validation`) and your validator's `Scenario` gate also runs as a session starts, on what setup changed: a session it finds an error with does not start, and the facilitator, or an agent setting the session up, is told every problem and the setting to change. A gate that throws also stops the start, reported as a fault in the game rather than in the settings; one that times out is run once more first, since a busy host can cause it. Nothing overrides either. A session nobody changed, on a scenario the build already checked, is not judged again. In the dev server, Play shows the refusal or the warnings, `pnpm run sdk play` prints the warnings, and `pnpm run sdk configure` checks the settings before it saves them, so a refused change is never written. See [When it runs](guides/validators.md#when-it-runs)
39
+ - **A busy host no longer refuses a sound scenario save.** A `Scenario` gate that runs out of time when a scenario is saved is run once more before the save is refused, and a refusal then says the host may have been busy. A gate that throws still refuses at once, and the build does not retry
40
+ - **Warnings from a `Scenario` gate.** Give a problem `level: 'warning'` for something unusual that may be meant. It is reported by the build (`SCENARIO_WARNING`), with a saved scenario and with a session start, and never refuses any of them. A problem with no `level` is an error, as before. See [Errors and warnings](guides/validators.md#errors-and-warnings)
41
+ - **The build notes a setting setup can change that no `Scenario` gate reads** (`SETTINGS_UNGATED`), since nothing then checks a facilitator's changes to it before play
42
+ - **Setup notes for assistants.** Put Markdown at `setup/notes/<locale>.md` to tell an AI assistant setting a session up which settings matter and what requests such as 'make it harder' mean as settings and values. Name settings as setting paths in code spans (`engine.BaseDemand`): the build fails on one that names no setting (`SETTINGS_UNKNOWN`) and warns on one your setup screen does not configure (`SETUP_NOTES_UNCONFIGURED`). They ship in the build, and the dev server shows them on the configuration step under **Notes for assistants**. See [Notes for assistants](guides/setup.md#notes-for-assistants)
43
+ - **Two recipes for assistant-led setup**: [Write setup notes for assistants](recipes/write-setup-notes.md), and [Describe a setup with an endpoint](recipes/describe-setup-with-endpoint.md), an external endpoint that reads a session's settings back in the game's own words during setup
44
+
45
+ ### Changed
46
+
47
+ - **New packages start on current tooling.** `pnpm run sdk new package` now pins oxfmt 0.75 (up from 0.67), oxlint 1.90, Vite 8.3.5, Vitest 5.0.5, MUI 9.5, i18next 26.5 and react-i18next 17.1, among other patch updates. oxfmt 0.75 formats some JSX conditionals and wrapped callbacks differently, so an existing package that moves to it should run `pnpm format` once and commit the result on its own
48
+
49
+ ## [1.7.0] — 2026-11-05
50
+
51
+ ### Added
52
+
53
+ - **One join link for the whole session.** A session UI reads it with `useSessionUserInterfaceSessionJoinLink()`, and a presentation as `session.sessionJoinLink`, so a facilitator can put a single QR code in front of a room and let the host put each person in a team. It is `null` where the host has none. Someone joining through it is an ordinary participant with an ordinary `participantJoin`, but no host promises which team they land in, so never depend on it. The dev server offers it at `/join`, placing each arrival in the team with the fewest participants, and lists it in the dev drawer as 'Session join link'. `pnpm run sdk participant join` does the same from the command line, and `renderSessionUserInterface` takes a `sessionJoinLink` option for tests. See [useSessionUserInterfaceSessionJoinLink](guides/session-hooks.md#usesessionuserinterfacesessionjoinlink)
54
+ - **`teams.sessionJoin` turns the session link off.** A new game setting, `true` by default, which a game sets in `seriousgaming.sdk.json` or a scenario sets under `settings.game`; setup cannot. A game whose teams are not interchangeable, such as one that gives each team a role, should set it to `false` and rebuild. A test that builds the `game` settings by hand, rather than from the generated `defaultSettings`, adds `sessionJoin` to `teams`. See [The game settings](guides/settings.md#the-game-settings)
55
+
56
+ ### Fixed
57
+
58
+ - **`sdk screenshot` works against a dev server given public origins this machine cannot reach.** With `--public-url`, `--public-asset-url` or `--public-hmr-url` set, it used to load the game's frames from those public origins, so a sandbox that cannot reach its own proxy (a hosted builder's, say) failed with `SURFACE_NOT_RENDERED`. It now asks the server for its local ports (`?local-origins` on the page it opens) and loads everything from them, and leaves the frame's hot-reload socket unconnected, as a capture never needs it. Everyone else is still handed the public origins, and the flagged responses are sent `Cache-Control: no-store`, so a proxy or CDN in front never keeps one
59
+
34
60
  ## [1.6.1] — 2026-11-02
35
61
 
36
62
  ### Changed
@@ -112,6 +112,10 @@ changes.
112
112
  The server still listens on the ports it prints, so point the gateway at those:
113
113
  the console's port, the asset port, and the Vite port for hot reload.
114
114
 
115
+ `sdk screenshot` runs on the server's own machine, which may not reach the
116
+ public origins at all, so it asks for the local ports instead and loads
117
+ everything from them. No other page is affected.
118
+
115
119
  ### Colour scheme and brand
116
120
 
117
121
  The console keeps its colour scheme and brand in its own browser storage,
@@ -12,7 +12,7 @@ The codes are the contract: branch on the code, never on the message. A code is
12
12
  | --------- | ------------- | ------------------- | ----- |
13
13
  | 1 | `internal` | Internal error | 1 |
14
14
  | 2 | `usage` | Usage error | 16 |
15
- | 3 | `package` | Invalid package | 32 |
15
+ | 3 | `package` | Invalid package | 35 |
16
16
  | 4 | `refused` | Refused by the game | 12 |
17
17
  | 5 | `environment` | Environment | 19 |
18
18
 
@@ -77,6 +77,9 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
77
77
  | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
78
78
  | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. | Yes |
79
79
  | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. | Yes |
80
+ | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. | Yes |
81
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. | Yes |
82
+ | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. | Yes |
80
83
  | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. | Yes |
81
84
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. | Yes |
82
85
  | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes |
@@ -154,6 +157,9 @@ The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits
154
157
  | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
155
158
  | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
156
159
  | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
160
+ | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. |
161
+ | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. |
162
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. |
157
163
  | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
158
164
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
159
165
  | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
@@ -235,6 +235,9 @@ Without `--json`, each diagnostic that names a file is printed under the error a
235
235
  | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. |
236
236
  | `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it. |
237
237
  | `SCENARIO_REFUSED` | A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names. |
238
+ | `SCENARIO_WARNING` | A warning: a validator's `Scenario` gate marked a problem with a package scenario, or with the defaults, as a `warning`. It is reported and never fails the build. |
239
+ | `SETTINGS_UNGATED` | A warning: the setup UI `configures` a settings resource no `Scenario` gate declares, so nothing checks what a facilitator changes in it before the session starts. |
240
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI does not `configures`, so a host refuses the change they describe. |
238
241
  | `EDITOR_ENDPOINT_NOT_SCENARIO` | The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `"scope": "scenario"` endpoints alone. |
239
242
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
240
243
  | `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. |
@@ -1598,6 +1601,17 @@ Add a participant to a team.
1598
1601
  | `--team [NUMBER]` | | Team to add them to (1-based, defaults to 1). |
1599
1602
  | `--no-server` | | Run in this process instead of starting a dev server. |
1600
1603
 
1604
+ ```text
1605
+ pnpm run sdk participant join [name] [options]
1606
+ ```
1607
+
1608
+ Join through the session link, letting the session choose the team.
1609
+
1610
+ | Option | Default | Description |
1611
+ | -------------------------- | --------------------- | ----------------------------------------------------- |
1612
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1613
+ | `--no-server` | | Run in this process instead of starting a dev server. |
1614
+
1601
1615
  ```text
1602
1616
  pnpm run sdk participant rename <participantId> <name> [options]
1603
1617
  ```
@@ -1620,7 +1634,11 @@ Move a participant to another team (1-based).
1620
1634
  | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1621
1635
  | `--no-server` | | Run in this process instead of starting a dev server. |
1622
1636
 
1623
- `participant add` defaults to team 1 when `--team` is omitted.
1637
+ `participant add` defaults to team 1 when `--team` is omitted. `participant join` is what following the session's one join link does: the dev server places the newcomer in the team with the fewest participants, the lowest numbered on a tie, and refuses when the game sets `teams.sessionJoin` to `false`. Another host may place people differently, so a game must not depend on where they land.
1638
+
1639
+ ```bash
1640
+ pnpm run sdk participant join Ada
1641
+ ```
1624
1642
 
1625
1643
  ### Waiting room, scenario, and locale
1626
1644
 
@@ -2127,7 +2145,7 @@ Capture a surface as a PNG, as a participant sees it.
2127
2145
  pnpm run sdk screenshot /team/1/player/1 --width 390 --height 844 --scheme dark --out plan.png --json
2128
2146
  ```
2129
2147
 
2130
- The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
2148
+ The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you, and so is `?local-origins`, which loads everything from the server's local ports even when it was given public origins this machine cannot reach. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
2131
2149
 
2132
2150
  It drives the game's own Playwright (`@playwright/test`, which every scaffolded game has), and fails with `BROWSER_MISSING` (exit 5) without it or its Chromium. A surface that does not connect, or does not report its first paint within `--timeout`, fails with `SURFACE_NOT_RENDERED` (exit 4), carrying the same three lists in `error.details`.
2133
2151
 
@@ -77,6 +77,7 @@ Add `"uses": ["generateText"]` to call an external service such as generated tex
77
77
 
78
78
  ```typescript
79
79
  import type { InitializationFunction, RunFunction } from '@seriousgaming/sdk';
80
+
80
81
  import type { Context, Settings } from './types';
81
82
 
82
83
  export const Init: InitializationFunction<Context, Settings> = async ({ context }) => ({
@@ -115,6 +115,7 @@ To change a value for one scenario, override it in the scenario's `settings` und
115
115
 
116
116
  ```typescript
117
117
  import { InitializationFunction } from '@seriousgaming/sdk';
118
+
118
119
  import type { Context, Settings } from './types';
119
120
 
120
121
  export const Init: InitializationFunction<Context, Settings> = async ({ context, settings }) => {
@@ -136,6 +137,7 @@ export const Init: InitializationFunction<Context, Settings> = async ({ context,
136
137
 
137
138
  ```typescript
138
139
  import { RunFunction } from '@seriousgaming/sdk';
140
+
139
141
  import type { Context, Settings } from './types';
140
142
 
141
143
  export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
@@ -221,6 +223,7 @@ Some of what an engine knows is nobody else's business: a record of every round
221
223
 
222
224
  ```typescript
223
225
  import type { InitializationFunction, RunFunction, SignatureCallbacks } from '@seriousgaming/sdk';
226
+
224
227
  import type { Context, Settings } from './types';
225
228
 
226
229
  interface EngineState {
@@ -482,6 +485,7 @@ The per-resource `types.ts` generator narrows the `Callbacks` type alias to the
482
485
 
483
486
  ```typescript
484
487
  import type { RunFunction } from '@seriousgaming/sdk';
488
+
485
489
  import type { Context, Settings, Callbacks } from './types';
486
490
 
487
491
  export const Run: RunFunction<Context, Settings, Callbacks> = async ({ context, callbacks }) => {
@@ -499,6 +503,7 @@ Build the arguments with `logicArgs` from `@seriousgaming/sdk/testing`, which fi
499
503
  ```typescript
500
504
  import { logicArgs } from '@seriousgaming/sdk/testing';
501
505
  import { describe, it, expect } from 'vitest';
506
+
502
507
  import { defaultContext, defaultSettings } from './defaults';
503
508
  import { Run } from './logic';
504
509
  import type { Context, Settings } from './types';