@seriousgaming/sdk-tools 1.9.0 → 1.11.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 (178) hide show
  1. package/dist/agent/guidance.md +31 -23
  2. package/dist/{cli-KJV3GGBA.js → cli-226ZJ72R.js} +1 -1
  3. package/dist/{cli-VRGVHSXH.js → cli-25SJZI7N.js} +44 -9
  4. package/dist/{cli-YI3WZF3C.js → cli-27TQVLVF.js} +11 -11
  5. package/dist/cli-27Z5T52R.js +30 -0
  6. package/dist/cli-3VLBFWHN.js +36 -0
  7. package/dist/{cli-DXHPYN4N.js → cli-44CM2AH2.js} +1 -1
  8. package/dist/{cli-2PMLR6WG.js → cli-4F24FUW6.js} +15 -15
  9. package/dist/{cli-6GDPO5VU.js → cli-4FJL3KQZ.js} +2 -2
  10. package/dist/{cli-2BF7KBBJ.js → cli-5ATO27Z4.js} +15 -15
  11. package/dist/{cli-AA5GMEUL.js → cli-5EH4WTH4.js} +4 -4
  12. package/dist/{cli-MPWTXNF6.js → cli-5M6KDNVX.js} +2 -2
  13. package/dist/{cli-J2OTL6JH.js → cli-5O7XENQY.js} +5 -5
  14. package/dist/{cli-XA4IL7IM.js → cli-5RRPUL6V.js} +11 -11
  15. package/dist/{cli-JEMWAIAA.js → cli-5TTJWM2R.js} +15 -15
  16. package/dist/{cli-S3YIYAXC.js → cli-5UKWX3IU.js} +12 -12
  17. package/dist/{cli-AEAFLZGY.js → cli-5VZBFMCK.js} +5 -1
  18. package/dist/{cli-AGYCXRPR.js → cli-5Z4D3F6Y.js} +3 -3
  19. package/dist/{cli-ZHFHOWJI.js → cli-6AMK3DYS.js} +11 -11
  20. package/dist/{cli-G7JTIP5G.js → cli-6BLVI2JM.js} +11 -7
  21. package/dist/{cli-SBKTGFY4.js → cli-6JWDFCUV.js} +17 -17
  22. package/dist/{cli-7OCEVQQN.js → cli-6O7YCK2M.js} +2 -2
  23. package/dist/{cli-GZE4V7RC.js → cli-6P6V2EHY.js} +19 -19
  24. package/dist/{cli-KD2RQS35.js → cli-77T4LJQF.js} +22 -19
  25. package/dist/{cli-IC5FOT2J.js → cli-7JUNA74L.js} +1 -1
  26. package/dist/{cli-2FXZZLCL.js → cli-AH6AMAIB.js} +1 -1
  27. package/dist/{cli-NTI22MRE.js → cli-ATAJSIXH.js} +16 -16
  28. package/dist/{cli-OOTGO3KW.js → cli-ATHATKI5.js} +49 -49
  29. package/dist/{cli-QWO3XJR3.js → cli-ATWJCB2G.js} +4 -4
  30. package/dist/{cli-QIHVXDMW.js → cli-B2QAJ5RQ.js} +15 -15
  31. package/dist/{cli-MN7X4UG2.js → cli-B3EFE7ZF.js} +1 -1
  32. package/dist/{cli-HJPNNORV.js → cli-BC67QHD5.js} +2 -2
  33. package/dist/cli-BINVO5R7.js +36 -0
  34. package/dist/{cli-PJO4BKSV.js → cli-BJFYGVJV.js} +16 -16
  35. package/dist/{cli-C45A5VX6.js → cli-BQ36DV5C.js} +3 -3
  36. package/dist/{cli-IJPRZSJ5.js → cli-BZOKZ7LP.js} +24 -22
  37. package/dist/{cli-GHIMH6JU.js → cli-C32Q5E5I.js} +1 -1
  38. package/dist/{cli-35K37SYY.js → cli-D3S7NJZ3.js} +14 -14
  39. package/dist/{cli-KGJHEDR2.js → cli-DBMEH4Y5.js} +23 -21
  40. package/dist/{cli-A7PITFRR.js → cli-DH35TZ2Q.js} +5 -3
  41. package/dist/{cli-A3P3PO6Z.js → cli-DQE7ITIR.js} +15 -15
  42. package/dist/{cli-BV7MX7JE.js → cli-EEO5ZPAZ.js} +3 -3
  43. package/dist/{cli-3RMP4HKZ.js → cli-ERJNDBDH.js} +2 -2
  44. package/dist/{cli-2JEICVMA.js → cli-F3YJKP6D.js} +3 -3
  45. package/dist/{cli-2VV5IPSY.js → cli-FT3X3D4P.js} +15 -15
  46. package/dist/{cli-LZFUSEJT.js → cli-FYPW25VD.js} +13 -13
  47. package/dist/{cli-CVOLMK3Z.js → cli-G2GLW5Z4.js} +1 -1
  48. package/dist/{cli-BYXNPBVG.js → cli-G3TU6CP6.js} +15 -15
  49. package/dist/{cli-4L7S27XO.js → cli-GO64NABP.js} +1 -1
  50. package/dist/{cli-XRVH5WV6.js → cli-GSOV26O5.js} +13 -13
  51. package/dist/{cli-2UOUIVHW.js → cli-H6PP2MZT.js} +24 -12
  52. package/dist/{cli-6Y4XIVQS.js → cli-HGCOEL5T.js} +3 -3
  53. package/dist/cli-HLI5UEKX.js +36 -0
  54. package/dist/{cli-B5LZEFLU.js → cli-HMDYG6PS.js} +15 -15
  55. package/dist/{cli-7CW2BBJG.js → cli-HNDFANQG.js} +1 -1
  56. package/dist/{cli-MSSJLABW.js → cli-IKSLPAZN.js} +3 -3
  57. package/dist/{cli-AJ5CABGJ.js → cli-JHLWBRXB.js} +15 -15
  58. package/dist/{cli-5PTCQTS6.js → cli-JXQLHJO2.js} +1 -1
  59. package/dist/{cli-H7T6E7OA.js → cli-K4HSQWXC.js} +2 -2
  60. package/dist/{cli-WJO75KP7.js → cli-KIZTASLL.js} +3 -3
  61. package/dist/{cli-MX7GFQ6N.js → cli-KJA6GLZI.js} +14 -14
  62. package/dist/{cli-KINJAQTJ.js → cli-L7F4XKCB.js} +19 -19
  63. package/dist/{cli-BC4KKNLA.js → cli-LHMRUJVN.js} +4 -2
  64. package/dist/{cli-CQUSM3SF.js → cli-LPFSJ625.js} +19 -19
  65. package/dist/{cli-BNN36WZJ.js → cli-MDVC5ZNM.js} +13 -13
  66. package/dist/{cli-TLRTLTGK.js → cli-MSNSXVGF.js} +18 -18
  67. package/dist/{cli-5BPQ73OM.js → cli-NKKCDO6K.js} +15 -15
  68. package/dist/{cli-L5ZKQNMI.js → cli-OBLEROSC.js} +15 -15
  69. package/dist/cli-OF36EA62.js +36 -0
  70. package/dist/{cli-MZM4MW7C.js → cli-OM32UURE.js} +19 -19
  71. package/dist/{cli-J75EBRAJ.js → cli-OMTHTWYJ.js} +17 -17
  72. package/dist/{cli-K6M6YB67.js → cli-OTBCA54D.js} +1 -1
  73. package/dist/cli-OVIJRBFI.js +36 -0
  74. package/dist/{cli-IVZ7AHUJ.js → cli-OXLOGXT3.js} +3 -3
  75. package/dist/{cli-NU4SCD5D.js → cli-P3NUTOPK.js} +1 -1
  76. package/dist/{cli-D6AC3ZCX.js → cli-PNS4KWWC.js} +22 -19
  77. package/dist/{cli-7N7WFRWA.js → cli-PXQYY6KM.js} +0 -0
  78. package/dist/{cli-MTAGL3QE.js → cli-Q7QSWNY2.js} +15 -15
  79. package/dist/{cli-7V6GUIIS.js → cli-QDBYFITU.js} +2 -2
  80. package/dist/{cli-QK2OD24J.js → cli-QEFYDXMH.js} +9 -2
  81. package/dist/{cli-MYBDWJP7.js → cli-QPV3TYOM.js} +20 -20
  82. package/dist/{cli-W4BHSBAX.js → cli-QTCTWYCM.js} +3 -3
  83. package/dist/{cli-HCMVZXWK.js → cli-R5SNTPND.js} +17 -17
  84. package/dist/{cli-RHYQYXE2.js → cli-REAM7LSC.js} +18 -18
  85. package/dist/{cli-GHQIATHP.js → cli-RHL4B4H7.js} +6 -5
  86. package/dist/{cli-RL5EBZL7.js → cli-RKPQLB7J.js} +3 -3
  87. package/dist/{cli-E77R7ZYB.js → cli-RMD5WSUQ.js} +15 -15
  88. package/dist/{cli-OX3254NS.js → cli-S3NHXAJM.js} +17 -17
  89. package/dist/{cli-6COAU7JR.js → cli-SRXDLMXY.js} +17 -17
  90. package/dist/{cli-DMKRP33X.js → cli-TCQJL2GY.js} +1 -1
  91. package/dist/{cli-KO26S2CL.js → cli-TEBV2OIW.js} +31 -14
  92. package/dist/{cli-USBJQAYI.js → cli-TI2FOFPA.js} +13 -13
  93. package/dist/{cli-7RLZIWFP.js → cli-TLSTSZAC.js} +19 -19
  94. package/dist/{cli-2CSI2UU2.js → cli-UEQMK4WX.js} +1 -1
  95. package/dist/cli-UIYKPSIY.js +36 -0
  96. package/dist/{cli-2I6UN6C3.js → cli-UQC46YSV.js} +3 -3
  97. package/dist/{cli-BF6L37O3.js → cli-UULZSQBV.js} +3 -3
  98. package/dist/{cli-OK6XWVIN.js → cli-UVIURDZC.js} +17 -17
  99. package/dist/{cli-6KL5B7EC.js → cli-VXLHOZSO.js} +15 -15
  100. package/dist/{cli-UR63LFVK.js → cli-W3RG2MRI.js} +2 -2
  101. package/dist/{cli-G54355N5.js → cli-WJVPSVF2.js} +22 -19
  102. package/dist/{cli-YD4SBAHQ.js → cli-WNBP3LOD.js} +19 -19
  103. package/dist/{cli-DJCQ5XFR.js → cli-WNHMJM3Z.js} +15 -15
  104. package/dist/{cli-CL3KF5KS.js → cli-WQ7JBZNW.js} +2 -2
  105. package/dist/{cli-VTLFQHDO.js → cli-WW54THXN.js} +1 -1
  106. package/dist/cli-WZNIW6ZO.js +16 -0
  107. package/dist/{cli-BT47H36C.js → cli-X3TSTTYI.js} +2 -2
  108. package/dist/{cli-ICLCA6VD.js → cli-X52TXCNF.js} +19 -19
  109. package/dist/{cli-ZZSPFLTK.js → cli-X64BNBQH.js} +26 -4
  110. package/dist/{cli-CKV44U7P.js → cli-XJ7JESC2.js} +19 -19
  111. package/dist/{cli-EDZF5Q2E.js → cli-XKAIDYIE.js} +14 -14
  112. package/dist/{cli-CPX4YA3P.js → cli-XNOAO6DY.js} +11 -11
  113. package/dist/{cli-R6YAZP6E.js → cli-XOYUTNER.js} +19 -19
  114. package/dist/{cli-3VV2JLHX.js → cli-XW3JLRSA.js} +1 -1
  115. package/dist/{cli-S7PLSPGE.js → cli-YYXAGJQR.js} +15 -15
  116. package/dist/{cli-LFUKHLHI.js → cli-ZGCG6C22.js} +17 -17
  117. package/dist/{cli-QRAYIXNE.js → cli-ZJW6HQ6N.js} +5 -5
  118. package/dist/{cli-Y33ULHYO.js → cli-ZNQBF4Z3.js} +1 -1
  119. package/dist/cli.js +52 -52
  120. package/dist/client/index.d.ts +1 -1
  121. package/dist/client/test-session.d.ts +44 -6
  122. package/dist/client.js +100 -12
  123. package/dist/dev/console/assets/{index-CVNjiRUh.js → index-Ch6HHb2T.js} +1 -1
  124. package/dist/dev/console/index.html +1 -1
  125. package/dist/dev/surfaces.d.ts +8 -2
  126. package/dist/docs/api/index.md +3 -1
  127. package/dist/docs/api/sdk-tools-client.md +38 -6
  128. package/dist/docs/api/sdk-tools-vite.md +21 -0
  129. package/dist/docs/api/sdk.md +2 -0
  130. package/dist/docs/changelog.md +49 -0
  131. package/dist/docs/cli-error-codes.md +41 -39
  132. package/dist/docs/cli-reference.md +2 -1
  133. package/dist/docs/guides/endpoints.md +1 -1
  134. package/dist/docs/guides/engine-testing.md +49 -14
  135. package/dist/docs/guides/engine.md +2 -2
  136. package/dist/docs/guides/scenario-editor.md +1 -1
  137. package/dist/docs/guides/setup.md +22 -5
  138. package/dist/docs/guides/testing.md +3 -8
  139. package/dist/docs/guides/upgrading.md +15 -0
  140. package/dist/docs/page-index.md +6 -5
  141. package/dist/docs/recipes/create-game.md +1 -1
  142. package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
  143. package/dist/docs/recipes/give-setup-a-menu.md +7 -1
  144. package/dist/docs/recipes/write-setup-notes.md +2 -2
  145. package/dist/host/protocol.d.ts +8 -5
  146. package/dist/oxlint/logic.json +184 -0
  147. package/dist/playwright.js +100 -12
  148. package/dist/runtime/manifest-version.d.ts +1 -1
  149. package/dist/runtime.js +1 -1
  150. package/dist/schema.json +20 -0
  151. package/dist/templates/package/README.md.liquid +1 -0
  152. package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
  153. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  154. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  155. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
  156. package/dist/templates/package/claude/settings.json.template +1 -0
  157. package/dist/templates/package/oxfmtrc.json.template +8 -1
  158. package/dist/templates/package/oxlintrc.json.template +1 -180
  159. package/dist/templates/package/package.json.liquid +1 -0
  160. package/dist/templates/package/vite.config.ts.liquid +2 -8
  161. package/dist/templates/package/vitest.config.ts.liquid +2 -8
  162. package/dist/templates/starter-game/package.json +2 -1
  163. package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
  164. package/dist/templates/starter-game/vite.config.ts +2 -8
  165. package/dist/templates/starter-game/vitest.config.ts +4 -3
  166. package/dist/utils/error-codes.d.ts +6 -2
  167. package/dist/utils/resource-scan.d.ts +5 -0
  168. package/dist/vite/index.d.ts +30 -0
  169. package/dist/vite.js +12 -0
  170. package/package.json +12 -4
  171. package/dist/cli-3I6AI4AA.js +0 -36
  172. package/dist/cli-3YGNWZC6.js +0 -30
  173. package/dist/cli-4X3X4HB2.js +0 -16
  174. package/dist/cli-6ZBQELF2.js +0 -36
  175. package/dist/cli-CUZUIYCQ.js +0 -36
  176. package/dist/cli-DNCJURUU.js +0 -36
  177. package/dist/cli-UKC7KXWU.js +0 -36
  178. package/dist/cli-WA2PDQUB.js +0 -36
@@ -5,7 +5,7 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
7
7
  <title>Serious Gaming</title>
8
- <script type="module" crossorigin src="/assets/index-CVNjiRUh.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-Ch6HHb2T.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -32,10 +32,16 @@ export interface MountableSurface {
32
32
  /** Whether it may ask for every team's roster (§6.3, §12.5). */
33
33
  crossTeamParticipants: boolean;
34
34
  /**
35
- * Settings resources it is sent (§8): those it lists in `settings`, or for
36
- * the setup UI and the scenario editor, those it `configures`.
35
+ * Settings resources it is sent (§8): those it lists in `settings`, and
36
+ * for the setup UI and the scenario editor, those it `configures` too.
37
37
  */
38
38
  settings: string[];
39
+ /**
40
+ * For the setup UI and the scenario editor, the settings resources it may
41
+ * change (§6.5), sent beside `setSettings` because what it is sent also
42
+ * holds the settings it only reads. Absent for every other surface.
43
+ */
44
+ configures?: string[];
39
45
  }
40
46
  /** URL prefix each surface kind is served under. */
41
47
  export declare const SURFACE_PREFIX: Record<SurfaceKind, string>;
@@ -14,8 +14,9 @@ Every type, function, hook and component your game imports, one page per entry p
14
14
  | [`@seriousgaming/sdk/commands`](./sdk-commands.md) | 3 interfaces, 5 types |
15
15
  | [`@seriousgaming/sdk/e2e`](./sdk-e2e.md) | 6 functions, 1 constant, 4 interfaces, 5 types |
16
16
  | [`@seriousgaming/deck`](./deck.md) | 16 functions, 5 constants, 15 interfaces, 4 types |
17
- | [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 5 functions, 1 class, 12 interfaces, 11 types |
17
+ | [`@seriousgaming/sdk-tools/client`](./sdk-tools-client.md) | 5 functions, 1 class, 13 interfaces, 12 types |
18
18
  | [`@seriousgaming/sdk-tools/playwright`](./sdk-tools-playwright.md) | 1 function, 3 constants, 2 interfaces, 1 type |
19
+ | [`@seriousgaming/sdk-tools/vite`](./sdk-tools-vite.md) | 1 constant |
19
20
 
20
21
  ## Which entry point to import from
21
22
 
@@ -27,6 +28,7 @@ Every type, function, hook and component your game imports, one page per entry p
27
28
  - **`@seriousgaming/sdk/commands`** and **`@seriousgaming/sdk/projection`**: the commands a client may send a session, and the shape of the state it reads back (`sdk view --json` and the dev server's `/api/state`)
28
29
  - **`@seriousgaming/sdk-tools/client`**: `createTestSession`, which plays a whole game in-process, `startDevServer`, which starts an isolated dev server for browser tests, and `buildSurfaces`, which builds a game's surfaces for those servers to serve
29
30
  - **`@seriousgaming/sdk-tools/playwright`**: the Playwright `test` that starts a dev server for each worker, and the `globalSetup` that builds the surfaces they serve
31
+ - **`@seriousgaming/sdk-tools/vite`**: `REACT_CONTEXT_PACKAGES`, the list a `vite.config.ts` and a `vitest.config.ts` pass to `resolve.dedupe`
30
32
  - **`@seriousgaming/deck`**: the slide components and layout primitives a presentation is built from
31
33
 
32
34
  `@seriousgaming/sdk-tools` also exports `/host` and `/runtime`. They are for people building a runtime that hosts games, not for game authors, their shapes may change in a minor release, and they are not documented here.
@@ -151,6 +151,28 @@ interface DevServerOptions {
151
151
  }
152
152
  ```
153
153
 
154
+ ### LogicErrorLocation
155
+
156
+ Where game logic threw, read back to the file the author wrote: the resource whose logic it was, the tick and team it ran for, and the source position. `file` is relative to the package root; `line` and `column` are 1-based.
157
+
158
+ ```ts
159
+ interface LogicErrorLocation {
160
+ resource: {
161
+ type: string;
162
+ identifier: string;
163
+ };
164
+ message: string;
165
+ tick?: number;
166
+ team?: {
167
+ teamId: string;
168
+ index: number;
169
+ };
170
+ file?: string;
171
+ line?: number;
172
+ column?: number;
173
+ }
174
+ ```
175
+
154
176
  ### SignatureCallbacks
155
177
 
156
178
  Every callback a runtime may offer logic: the engine, hooks, tick controllers and endpoints.
@@ -221,30 +243,30 @@ A session to test against.
221
243
 
222
244
  ```ts
223
245
  interface TestSession<Context = UntypedContext, Shared = UntypedContext> {
224
- send(command: MutationCommand): Promise<MutationResult>;
246
+ send(command: MutationCommand): Promise<TestMutationResult>;
225
247
  send(command: QueryCommand): Promise<QueryResult>;
226
- send(command: Command): Promise<MutationResult | QueryResult>;
248
+ send(command: Command): Promise<TestMutationResult | QueryResult>;
227
249
  state(): TestSessionState<Context, Shared>;
228
250
  team(index: number): TestSessionTeam<Context>;
229
251
  readonly shared: {
230
252
  readonly context: Shared;
231
253
  };
232
- tick(options?: { team?: number }): Promise<MutationResult>;
254
+ tick(options?: { team?: number }): Promise<TestMutationResult>;
233
255
  requestTick(
234
256
  team: number,
235
257
  options?: {
236
258
  participantId?: string;
237
259
  }
238
- ): Promise<MutationResult>;
260
+ ): Promise<TestMutationResult>;
239
261
  setData(
240
262
  team: number,
241
263
  patch: ContextUpdate<Context>,
242
264
  options?: TestSessionSetDataOptions
243
- ): Promise<MutationResult>;
265
+ ): Promise<TestMutationResult>;
244
266
  setSharedData(
245
267
  patch: ContextUpdate<Shared>,
246
268
  options?: TestSessionSetSharedDataOptions
247
- ): Promise<MutationResult>;
269
+ ): Promise<TestMutationResult>;
248
270
  settled(): Promise<void>;
249
271
  close(): Promise<void>;
250
272
  }
@@ -578,6 +600,16 @@ type QueryResult =
578
600
  };
579
601
  ```
580
602
 
603
+ ### TestMutationResult
604
+
605
+ What a test session answers a mutation with. A refusal that came from logic throwing (a failed tick, a hook, a validator) carries `logicError` beside its outcome, which is what `sdk tick` reports from the command line:
606
+
607
+ ```ts
608
+ type TestMutationResult = MutationResult & {
609
+ logicError?: LogicErrorLocation;
610
+ };
611
+ ```
612
+
581
613
  ### TestServices
582
614
 
583
615
  Where a test session's service callbacks go (`TestSessionOptions.services`).
@@ -0,0 +1,21 @@
1
+ <!-- Generated by `pnpm docs:generate` from the exports of `@seriousgaming/sdk-tools/vite`. Edit those, not this file. -->
2
+
3
+ # `@seriousgaming/sdk-tools/vite`
4
+
5
+ What a game's Vite and Vitest configs need from the SDK.
6
+
7
+ Imported from `@seriousgaming/sdk-tools/vite` by a `vite.config.ts` or a
8
+ `vitest.config.ts`, so it stays free of the CLI and the dev server: a config
9
+ file is loaded on every run.
10
+
11
+ Every export of `@seriousgaming/sdk-tools/vite`, with the declaration it is published with. Anything tagged `@internal` is left out: it ships in the declarations, but is not part of the supported API and may change without a major release. For how the pieces fit together, see the [API reference](./index.md) and the guides it links to.
12
+
13
+ ## Constants
14
+
15
+ ### REACT_CONTEXT_PACKAGES
16
+
17
+ Every package that holds React context a surface reads, for `resolve.dedupe`.
18
+
19
+ ```ts
20
+ const REACT_CONTEXT_PACKAGES: readonly string[];
21
+ ```
@@ -1014,6 +1014,7 @@ Definition of the game's scenario editor: an authoring screen, used at any time
1014
1014
  interface ScenarioEditorDefinition {
1015
1015
  identifier: string;
1016
1016
  configures?: string[];
1017
+ settings?: string[];
1017
1018
  endpoints?: string[];
1018
1019
  }
1019
1020
  ```
@@ -1428,6 +1429,7 @@ Definition of the game's setup user interface: a small form shown at session cre
1428
1429
  interface SetupDefinition {
1429
1430
  identifier: string;
1430
1431
  configures?: string[];
1432
+ settings?: string[];
1431
1433
  endpoints?: string[];
1432
1434
  }
1433
1435
  ```
@@ -27,10 +27,59 @@ Entries are grouped into: **Breaking Changes**, **Added**, **Changed**,
27
27
  **Deprecated**, **Removed**, **Fixed** and **Security**. Releases before 1.0
28
28
  are in the [0.x changelog](changelog-0.x.md).
29
29
 
30
+ From 1.11, a release that changed what `sdk new package` writes, a shipped
31
+ `.claude/rules/` file or the agent guidance also has a **Scaffold changes**
32
+ section: one line per file, saying what changed, why, and after `Adopt:`
33
+ whether an existing package should copy the change. Nothing updates a package's
34
+ own copies, so read those lines for every release you cross.
35
+
30
36
  ---
31
37
 
32
38
  ## [Unreleased]
33
39
 
40
+ ## [1.11.0] — 2026-11-11
41
+
42
+ ### Added
43
+
44
+ - **`pnpm check` in a new package**: one script that validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. It is the package's own script, so add steps to it. The guidance now tells an agent to run it after every change. To add it to an existing package, see [Catch an older package's scaffold up](guides/upgrading.md#111-catch-an-older-packages-scaffold-up)
45
+ - **The lint rules for logic files ship in the SDK.** A package's `.oxlintrc.json` extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` (also exported as `@seriousgaming/sdk-tools/oxlint/logic.json`), which refuses the globals the production runtime lacks in engine, hook, validator, endpoint and tick controller logic, and exempts tests. A package no longer keeps its own copy of the list, so the list keeps up with the SDK
46
+ - **`REACT_CONTEXT_PACKAGES` from `@seriousgaming/sdk-tools/vite`**: the packages that hold React context, for `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`. `sdk build` dedupes the same list itself, which now includes `@seriousgaming/sdk` and `@seriousgaming/deck`
47
+ - **An engine test sees where logic threw.** A `createTestSession` result that was refused because logic threw carries `logicError`: the resource, the message, the tick and team, and the `file`, `line` and `column` of the source, as `sdk tick` reports them. It was already there at run time; it is now typed, as `TestMutationResult` and `LogicErrorLocation` from `@seriousgaming/sdk-tools/client`, and documented in [Engine testing](guides/engine-testing.md#ticking-and-asserting)
48
+ - **A hint on three more failures.** `RESOURCE_NOT_FOUND` from `update` names the resources of that type the package holds, `MANIFEST_NOT_FOUND` says where to run the command, and `PORT_IN_USE` points at `sdk dev status` and `--port auto`
49
+ - **The conformance suite carries the specification and the manifest schema it was built from**, in the installed package's `dist/`, so a runtime that pins the suite gets all three at one revision. The specification's changelog now maps each SDK release to the revision it implements. See the suite's README
50
+
51
+ ### Changed
52
+
53
+ - **`sdk new package --empty` writes `teams.mode` into the manifest**, as `"independent"`, which is what an absent mode already meant. A game that needs shared state now has the field in front of it to change
54
+ - **The starter game's engine test is typed and plays every scenario.** It passes the engine's generated `Context` to `createTestSession`, so it reads `team.context.results.Day` without a cast, and ends with a test that starts each scenario on disk and plays a day
55
+
56
+ ### Fixed
57
+
58
+ - **The guides agree on what leaving a key out does.** A variable logic returns replaces the old one whole, so an entry of a map is gone if the returned map leaves it out. The engine guide and the agent guidance both said it never was. `deletes` is still the way to remove one: it works however the map was built
59
+ - **Every documented `--json` command uses `pnpm run --silent`**, so no pnpm banner precedes the JSON. Two examples did not
60
+
61
+ ### Scaffold changes
62
+
63
+ - `package.json`: gains a `check` script that runs `sdk build --validate-only`, `typecheck`, `lint`, `test:run` and `test:engine` in order. It gives an agent one command to run after every change. Adopt: yes, copy the script, and drop its last step if the package has no engine tests
64
+ - `.oxlintrc.json` (`oxlintrc.json.template`): extends `./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json` in place of its own `no-restricted-globals` override and the override that turned it off for tests. The list of globals the production runtime lacks now comes from the installed SDK. Adopt: yes, add the `extends` line and delete the two overrides
65
+ - `vite.config.ts` and `vitest.config.ts`: `resolve.dedupe` is `[...REACT_CONTEXT_PACKAGES]`, imported from `@seriousgaming/sdk-tools/vite`, in place of a written-out list. Adopt: optional, and keep any package of your own after the spread
66
+ - `.oxfmtrc.json` (`oxfmtrc.json.template`): `ignorePatterns` gains `lib/`, `test-results/` and `playwright-report/`, so the formatter stops rewriting build output and test reports. Adopt: yes
67
+ - `.claude/settings.json` (`settings.json.template`): allows `pnpm check` without a prompt, beside the steps it runs. Adopt: yes, add the line
68
+ - `README.md`: lists `pnpm check` under 'Running the tests'. Adopt: no
69
+ - `guidance.md`: the loop is `pnpm check`; `tick --no-server` is a smoke test, since engine tests run in the same restricted runtime; session examples pass `--summary`; `cli-reference.md`, `changelog.md` and `guides/upgrading.md` are never to be read whole; and removing a key is described as it behaves. Adopt: no, it updates with the installed version
70
+ - `.claude/rules/workflow-update-sdk-version.md`: step 7 reads this section of every release crossed, oldest first, and step 6 runs `pnpm check`. Adopt: yes, replace the file, so later upgrades find these lines
71
+ - `.claude/rules/workflow-create-engine.md`, `workflow-create-user-interface.md` and `workflow-test-engine-or-ui.md`: the verify step is `pnpm check`. Adopt: optional
72
+
73
+ ## [1.10.0] — 2026-11-07
74
+
75
+ ### Added
76
+
77
+ - **A setup screen or scenario editor can read settings it does not configure.** List them in the bundle's new `settings`, as every other resource does: the screen receives their resolved values beside the ones it configures, and cannot change them. A setup menu whose choices depend on the scenario can now show only what the scenario offers, rather than letting a facilitator choose an option that is refused at Play. `useSettingsEditor().configures` still names only what the screen may change. The build fails on a settings resource the package does not declare, and warns on one listed in both `configures` and `settings` (`EDITOR_SETTINGS_CONFIGURED`). `examples/factory`'s setup reads `engine` and `ui` to disable a market nobody would buy in. See [Read settings you do not configure](guides/setup.md#read-settings-you-do-not-configure)
78
+
79
+ ### Fixed
80
+
81
+ - **Setup notes are no longer warned for naming where the menu's offer comes from.** A setting your setup screen lists in `settings` may be named in your notes without `SETUP_NOTES_UNCONFIGURED`, which now warns only on a setting the screen neither configures nor reads
82
+
34
83
  ## [1.9.0] — 2026-11-07
35
84
 
36
85
  ### Added
@@ -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 | 35 |
15
+ | 3 | `package` | Invalid package | 36 |
16
16
  | 4 | `refused` | Refused by the game | 12 |
17
17
  | 5 | `environment` | Environment | 19 |
18
18
 
@@ -49,43 +49,44 @@ A code marked as a diagnostic also appears in a failure's `diagnostics`, one fin
49
49
 
50
50
  ### Exit 3: invalid package
51
51
 
52
- | Code | When | Also a diagnostic |
53
- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
54
- | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
55
- | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
56
- | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
57
- | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
58
- | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
59
- | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
60
- | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
61
- | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
62
- | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
63
- | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
64
- | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
65
- | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
66
- | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
67
- | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
68
- | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
69
- | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
70
- | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
71
- | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
72
- | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
73
- | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
74
- | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
75
- | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
76
- | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
77
- | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
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
- | `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 |
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 |
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 |
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 |
86
- | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
87
- | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
88
- | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
52
+ | Code | When | Also a diagnostic |
53
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
54
+ | `PACKAGE_INVALID` | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet. | Yes |
55
+ | `MANIFEST_NOT_FOUND` | There is no seriousgaming.sdk.json (or package.json) where the command looked. | |
56
+ | `MANIFEST_INVALID` | seriousgaming.sdk.json or package.json cannot be read, or is not valid. | |
57
+ | `BUNDLE_INVALID` | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid. | |
58
+ | `LOGIC_NODE_BUILTIN` | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone. | Yes |
59
+ | `LOGIC_BUNDLE_FAILED` | A logic file does not bundle: a syntax error, or an import that does not resolve. | Yes |
60
+ | `SCHEMA_INVALID` | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value. | Yes |
61
+ | `JSON_INVALID` | A bundle file is not valid JSON. | Yes |
62
+ | `BUNDLE_MISSING` | A resource directory holds no bundle file. | Yes |
63
+ | `REMOVED_FIELD` | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it. | Yes |
64
+ | `LAYOUT_OUTDATED` | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now. | Yes |
65
+ | `FEATURE_UNSUPPORTED` | The manifest's `requires` names an optional feature this version of the SDK does not support. | Yes |
66
+ | `FEATURE_UNDECLARED` | The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing. | Yes |
67
+ | `REFERENCE_UNKNOWN` | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare. | Yes |
68
+ | `SETTINGS_UNKNOWN` | A scenario overrides a settings resource the package does not declare. | Yes |
69
+ | `SETTINGS_UNKNOWN_KEY` | A scenario overrides a key that its settings resource does not declare. | Yes |
70
+ | `SETTINGS_INVALID` | A scenario's override does not match its settings resource's schema. | Yes |
71
+ | `SETTINGS_RESERVED` | A settings resource is named `game`, which is reserved for the built-in game settings. | Yes |
72
+ | `SETTINGS_LOCKED` | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`. | Yes |
73
+ | `GAME_CONSTRAINT_INVALID` | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it. | Yes |
74
+ | `GAME_CONSTRAINT_VIOLATED` | The game's own value for a `game` setting breaks its `gameSettingsConstraints`. | Yes |
75
+ | `LOGIC_EXPORT_MISSING` | A logic file is missing, or does not export the functions its resource needs. | Yes |
76
+ | `READ_NEVER_WRITTEN` | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults. | Yes |
77
+ | `NO_TERMINATION` | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it. | Yes |
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
+ | `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 neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. | Yes |
82
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. | Yes |
83
+ | `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 |
84
+ | `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 |
85
+ | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. | Yes |
86
+ | `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 |
87
+ | `ENDPOINT_UNREQUESTED` | A warning: an internal endpoint no user interface lists in its `endpoints`. | Yes |
88
+ | `PLATFORM_REJECTED` | The platform refused the uploaded package as invalid. | |
89
+ | `VERSION_EXISTS` | The platform already has this version of the package. Bump it and publish again. | |
89
90
 
90
91
  ### Exit 4: refused by the game
91
92
 
@@ -159,7 +160,8 @@ The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits
159
160
  | `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
161
  | `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
162
  | `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. |
163
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. |
164
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. |
163
165
  | `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. |
164
166
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
165
167
  | `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. |
@@ -237,7 +237,8 @@ Without `--json`, each diagnostic that names a file is printed under the error a
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
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
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. |
240
+ | `SETUP_NOTES_UNCONFIGURED` | A warning: the setup notes name a setting the setup UI neither `configures` nor lists in `settings`, so a host refuses the change they describe and the setup UI cannot see it. |
241
+ | `EDITOR_SETTINGS_CONFIGURED` | A warning: a settings editor lists a settings resource in both `configures` and `settings`. Configuring a resource already sends it, so the `settings` entry does nothing. |
241
242
  | `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. |
242
243
  | `SCENARIO_ENDPOINT_STATEFUL` | A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have. |
243
244
  | `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. |
@@ -344,7 +344,7 @@ An internal endpoint's request may take any shape. Which outside callers may use
344
344
 
345
345
  ## When a call fails
346
346
 
347
- A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
347
+ A failed call is never a bare message, because a caller has to tell a call that changed nothing from one whose writes landed before an action failed. A UI's call rejects with an [`EndpointError`](../api/sdk-ui.md#endpointerror), `pnpm run --silent sdk endpoint call --json` prints the same thing, and a `createTestSession` call answers `{ type: 'endpointFailure', failure }`. Each carries:
348
348
 
349
349
  - `outcome`: why, as `outcome.kind` and usually `outcome.message`. The kinds are those of a refused write (`denied`, `conflict`, `tick-failed` and the rest) plus three only an endpoint has: `invalid-request` (the request failed `requestSchema`, so the handler did not run), `handler-error` (the handler threw or overran its time limit), and `invalid-response` (what it returned broke its declaration)
350
350
  - `applied`: the steps that committed before the failure, in order: `{ kind: 'capabilities' }`, `{ kind: 'teams', teamId }`, or `{ kind: 'action', index, type }`. Empty when nothing changed
@@ -116,6 +116,16 @@ it('adds Delta to Total on each tick', async () => {
116
116
  });
117
117
  ```
118
118
 
119
+ When the refusal came from logic that threw, the result also carries `logicError`: the resource whose logic it was, the message, the tick and team it ran for, and the `file`, `line` and `column` of the source, which is what `sdk tick` reports from the command line. Put it in the failure message and a failing test says where to look:
120
+
121
+ ```typescript
122
+ const result = await session.tick();
123
+ if (!result.ok) {
124
+ const at = result.logicError;
125
+ throw new Error(`${result.outcome.kind} at ${at?.file}:${at?.line} (tick ${at?.tick})`);
126
+ }
127
+ ```
128
+
119
129
  Every helper is a command underneath, and `send` takes any command directly: `session.tick()` is `session.send({ type: 'tick' })`.
120
130
 
121
131
  `state()` is the whole session: `session.completedTicks`, `session.complete`, every team with its `context`, `completedTicks` and `participants`, the shared store, the timer and `settings`, every settings resource's resolved values keyed by identifier.
@@ -278,6 +288,27 @@ await createTestSession({ packagePath: PACKAGE_PATH, scenarioId: null });
278
288
 
279
289
  A game that marks a default scenario never runs on none, so `scenarioId: null` is refused for it, naming the default. Pin one of its scenarios instead.
280
290
 
291
+ ### Playing every scenario
292
+
293
+ A scenario overrides settings, and a value the engine cannot work with only shows when the game is played on it. Start every scenario and play a tick, reading the list from disk so a new scenario is covered the day it is added:
294
+
295
+ ```typescript
296
+ const scenarios = readdirSync(join(PACKAGE_PATH, 'scenarios'), { withFileTypes: true })
297
+ .filter((entry) => entry.isDirectory())
298
+ .map((entry) => entry.name);
299
+
300
+ it.each(scenarios)('%s starts and plays a tick', async (scenarioId) => {
301
+ const session = await createTestSession<Context>({ packagePath: PACKAGE_PATH, scenarioId });
302
+ try {
303
+ expect(await session.tick()).toMatchObject({ ok: true });
304
+ } finally {
305
+ await session.close();
306
+ }
307
+ });
308
+ ```
309
+
310
+ The starter game's `testing/engine/game.engine.test.ts` ends with this test.
311
+
281
312
  ### The configuration step
282
313
 
283
314
  A game with a `setup` slot starts at its configuration step. `createTestSession` presses Play for you, so a tick has a game to run. Pass `play: false` to test the step itself, then send `updateSettings` (keyed by settings identifier, for example `{ type: 'updateSettings', payload: { engine: { BaseDemand: 200 } } }`) and `play` as the setup screen would. Settings are fixed from Play onwards, so `state().settings` after `play` is what every tick reads.
@@ -383,6 +414,10 @@ pnpm exec vitest --config vitest.engine.config.ts testing/engine/game.engine.tes
383
414
 
384
415
  Engine tests run in milliseconds per test because there are no subprocesses, no HTTP, and no browser startup.
385
416
 
417
+ They run logic in the same restricted runtime as `sdk tick` and the dev server, which exposes only the ECMAScript intrinsics. A host global the production runtime lacks, such as `structuredClone` or `fetch`, fails an engine test with a `ReferenceError`, where a unit test calling `Run` directly runs in Node and passes.
418
+
419
+ `pnpm check` runs them last, after validating the package, typechecking, linting and the unit tests. Run it after every change.
420
+
386
421
  ## CI integration
387
422
 
388
423
  Engine tests require nothing beyond Node.js: no dev server, no browser, and no platform API key, because the service callbacks are stubbed unless a test asks for the platform. Add them to your CI pipeline alongside unit tests:
@@ -418,20 +453,20 @@ Run Playwright tests in a separate job or stage, since they need a browser and t
418
453
 
419
454
  ### `TestSession`
420
455
 
421
- | Member | Returns | Description |
422
- | -------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
423
- | `send(command)` | `Promise<MutationResult>` or `Promise<QueryResult>` | Run a command as the dev server would. A refusal is an answer, not a throw |
424
- | `state()` | `TestSessionState<Context, Shared>` | The whole session now, each team's context typed |
425
- | `team(index)` | `TestSessionTeam<Context>` | One team by stable index: `context`, `participants`, `completedTicks` and the rest. Throws for an unknown one |
426
- | `shared` | `{ context: Shared }` | The shared store now, under `context` as a session surface's `sessionData.shared` holds it |
427
- | `tick(options?)` | `Promise<MutationResult>` | A facilitator's tick. `{ team }` ticks one team in independent mode |
428
- | `requestTick(team, options?)` | `Promise<MutationResult>` | A participant's request, which `RequestTick` gates judge. `{ participantId }` to choose who asks |
429
- | `setData(team, patch, options?)` | `Promise<MutationResult>` | A participant's write through `ui`, or `{ as: 'system' }` for a trusted one. Also `deletes`, `participantId`, `ui` |
430
- | `setSharedData(patch, options?)` | `Promise<MutationResult>` | A write to the shared store. `{ ui }` holds it to that session surface's `writes`; also `deletes` |
431
- | `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
432
- | `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
433
-
434
- `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
456
+ | Member | Returns | Description |
457
+ | -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
458
+ | `send(command)` | `Promise<TestMutationResult>` or `Promise<QueryResult>` | Run a command as the dev server would. A refusal is an answer, not a throw |
459
+ | `state()` | `TestSessionState<Context, Shared>` | The whole session now, each team's context typed |
460
+ | `team(index)` | `TestSessionTeam<Context>` | One team by stable index: `context`, `participants`, `completedTicks` and the rest. Throws for an unknown one |
461
+ | `shared` | `{ context: Shared }` | The shared store now, under `context` as a session surface's `sessionData.shared` holds it |
462
+ | `tick(options?)` | `Promise<TestMutationResult>` | A facilitator's tick. `{ team }` ticks one team in independent mode |
463
+ | `requestTick(team, options?)` | `Promise<TestMutationResult>` | A participant's request, which `RequestTick` gates judge. `{ participantId }` to choose who asks |
464
+ | `setData(team, patch, options?)` | `Promise<TestMutationResult>` | A participant's write through `ui`, or `{ as: 'system' }` for a trusted one. Also `deletes`, `participantId`, `ui` |
465
+ | `setSharedData(patch, options?)` | `Promise<TestMutationResult>` | A write to the shared store. `{ ui }` holds it to that session surface's `writes`; also `deletes` |
466
+ | `settled()` | `Promise<void>` | Resolves once everything queued has run, including a timer's tick |
467
+ | `close()` | `Promise<void>` | Stop the session's timers. Call it in `afterEach` |
468
+
469
+ A `TestMutationResult` is a `MutationResult` that may carry `logicError`, a `LogicErrorLocation`. `Command`, `MutationCommand`, `QueryCommand`, `QueryResult`, `MutationResult`, `TestMutationResult`, `LogicErrorLocation`, `StateProjection`, `TestSessionState`, `TestSessionTeam`, `TestSessionSetDataOptions`, `TestSessionSetSharedDataOptions`, `ContextUpdate`, `ContextDeletePath`, `FakeClock`, `ParticipantCounts`, `TestServices`, `createStubServices` and `stubGenerateText` are exported from the same module.
435
470
 
436
471
  To call one logic function directly instead, with no session, build its arguments with `logicArgs` from `@seriousgaming/sdk/testing` (see [Testing](./testing.md#testing-the-run-function)).
437
472
 
@@ -201,7 +201,7 @@ This is not how a UI's `setData` behaves. A UI deep-merges its patch, because it
201
201
 
202
202
  ### Removing a key
203
203
 
204
- A variable you leave out keeps its value, so a fold can never take an entry out of a map keyed by something arbitrary, such as an order or team id. Name the entry in `deletes` instead:
204
+ A variable you return replaces the old one whole, so an entry of a map is gone only if the map you return leaves it out. The usual way to build that map spreads the old one (`{ ...context.orders.Open, [id]: order }`), which carries every entry forward, the one you meant to remove included. Rather than rebuild the map without it, name the entry in `deletes`:
205
205
 
206
206
  ```typescript
207
207
  return {
@@ -305,7 +305,7 @@ Engine logic runs in a **bare V8 isolate**. The runtime provides the ECMAScript
305
305
  Referencing one throws `ReferenceError` at tick time. Two things protect you:
306
306
 
307
307
  - **The dev server and CLI enforce it.** `sdk dev` and `tick` run your logic in the same restricted environment, so the failure surfaces locally rather than on deploy
308
- - **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
308
+ - **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The rules ship in the SDK, and the package's `.oxlintrc.json` extends them (`./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json`), so the list keeps up with the runtime. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
309
309
 
310
310
  ### What to use instead
311
311
 
@@ -67,7 +67,7 @@ pnpm run sdk new scenario_editor '{
67
67
  }'
68
68
  ```
69
69
 
70
- `configures` names the [settings resources](./settings.md) the editor edits, by identifier. It receives the resolved values of exactly those settings and can change nothing else (an `updateSettings` call naming any other settings resource is refused, and none of it is applied), and the build fails if you name a settings resource the package does not declare. Settings the editor does not configure keep the values the scenario starts from. List `game` to let the editor set the scenario's number of rounds and team settings, which it saves under the scenario's `settings.game` (see [The game settings](./settings.md#the-game-settings)). An edit that changes a setting the game locks with `readOnly`, or sets a value outside its schema's range, is refused the same way, and the draft keeps none of it. The editor is sent values, not schemas, so show a locked field as read-only, as the factory example's editor does (see [Lock a setting](./settings.md#lock-a-setting)).
70
+ `configures` names the [settings resources](./settings.md) the editor edits, by identifier. It receives the resolved values of exactly those settings and can change nothing else (an `updateSettings` call naming any other settings resource is refused, and none of it is applied), and the build fails if you name a settings resource the package does not declare. Settings the editor does not configure keep the values the scenario starts from. To show one without letting the editor change it, list it in `settings` instead: the editor receives it resolved under the scenario, read-only (see [Read settings you do not configure](./setup.md#read-settings-you-do-not-configure)). List `game` to let the editor set the scenario's number of rounds and team settings, which it saves under the scenario's `settings.game` (see [The game settings](./settings.md#the-game-settings)). An edit that changes a setting the game locks with `readOnly`, or sets a value outside its schema's range, is refused the same way, and the draft keeps none of it. The editor is sent values, not schemas, so show a locked field as read-only, as the factory example's editor does (see [Lock a setting](./settings.md#lock-a-setting)).
71
71
 
72
72
  ```
73
73
  scenario_editor/
@@ -81,20 +81,37 @@ So put the choices your setup offers in a settings resource of their own, a menu
81
81
  - **Give each a `title` and a `description`.** An assistant shows them to the facilitator when it confirms a choice
82
82
  - **Let your logic decide what a choice means.** Declare the menu in the `settings` of the engine and of any other resource it affects, and work out the values there. A choice relative to the scenario, such as 'tougher than the scenario', never clashes with what a scenario sets
83
83
  - **A scenario sets the menu's defaults** by setting the menu resource, like any other setting. Add the menu to the scenario editor's `configures` to let an author choose them
84
- - **Keep what the menu offers per scenario in your other settings.** When a choice is only available in some scenarios, such as an aid a scenario may or may not allow, the list of what is allowed belongs in a settings resource setup does not configure. Say where it is in the menu setting's `description` and in your [notes for assistants](#notes-for-assistants)
84
+ - **Keep what the menu offers per scenario in your other settings.** When a choice is only available in some scenarios, such as an aid a scenario may or may not allow, the list of what is allowed belongs in a settings resource setup does not configure. List that resource in your setup's `settings` so the screen can offer only what is allowed (see [Read settings you do not configure](#read-settings-you-do-not-configure)), and say where it is in the menu setting's `description` and in your [notes for assistants](#notes-for-assistants)
85
85
  - **Refuse a choice that is wrong for the scenario** in a [Scenario gate](./validators.md#when-it-runs), with `session-validation` in `requires`: it runs as the session starts, on what setup changed
86
86
 
87
87
  Everything else stays in the game's other settings, for scenario authors. A facilitator who wants something the menu does not offer needs a scenario that does it.
88
88
 
89
89
  `examples/factory` does this: its setup configures `game` and a `setup` menu with one choice, `Market`; the engine applies the choice to the scenario's demand, and its `Scenario` gate refuses a market that would leave no team selling anything. See [Give setup a menu](../recipes/give-setup-a-menu.md) to move an existing setup to one.
90
90
 
91
+ ## Read settings you do not configure
92
+
93
+ A screen sometimes needs to see a setting it must not change, such as the scenario's list of what the menu may offer. List it in `settings`, beside `configures`:
94
+
95
+ ```json
96
+ {
97
+ "definition": {
98
+ "configures": ["game", "setup"],
99
+ "settings": ["engine", "ui"]
100
+ }
101
+ }
102
+ ```
103
+
104
+ The screen receives the resolved values of both lists in `settings` from `useSettingsEditor()`, and the generated `Settings` types them all. Only what it configures can change: an `updateSettings` call naming a resource it only reads is refused, and none of it is applied. `configures` from `useSettingsEditor()` names the resources it may change. The build fails if `settings` names a settings resource the package does not declare, and warns on one listed in both (`EDITOR_SETTINGS_CONFIGURED`), since configuring a resource already sends it.
105
+
106
+ `examples/factory`'s setup reads `engine` and `ui` and disables a market in which nobody would buy at the scenario's lowest price, using the same rule as its `Scenario` gate, so a facilitator never picks a choice that is refused at Play. The scenario editor takes `settings` the same way.
107
+
91
108
  ## Building the form
92
109
 
93
110
  `useSettingsEditor()` returns three things:
94
111
 
95
- - `settings`: the resolved values of the settings this screen configures, keyed by settings identifier
112
+ - `settings`: the resolved values of the settings this screen configures and of those it [reads](#read-settings-you-do-not-configure), keyed by settings identifier
96
113
  - `updateSettings(update)`: merges an update and sends the host only what changed. It returns a promise that rejects with a `MutationError` when the host refuses the write
97
- - `configures`: the identifiers this screen was sent
114
+ - `configures`: the identifiers of the settings this screen may change
98
115
 
99
116
  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.
100
117
 
@@ -201,8 +218,8 @@ An AI assistant can set a session up for a facilitator, choosing from what your
201
218
  ```
202
219
 
203
220
  - **Describe your menu, and nothing beyond it.** Name only settings your setup screen configures, with values their schemas allow. A request the menu cannot meet needs a scenario, so say which, rather than naming a setting setup cannot change
204
- - **Name each setting as a setting path in a code span**, such as `setup.Market`: 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`)
205
- - **Say what a schema cannot**: which choices are worth asking about, what common requests mean as choices, and, where what the menu offers depends on the scenario, which setting says what it offers. A host may show an assistant your other settings, read-only, for exactly this
221
+ - **Name each setting as a setting path in a code span**, such as `setup.Market`: 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 neither configures nor lists in `settings` (`SETUP_NOTES_UNCONFIGURED`)
222
+ - **Say what a schema cannot**: which choices are worth asking about, what common requests mean as choices, and, where what the menu offers depends on the scenario, which setting says what it offers. List that setting's resource in your setup's `settings`, so the build knows the notes name it to be read. A host may show an assistant your other settings, read-only, for exactly this
206
223
  - **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
207
224
  - **Locales fall back** from the assistant's locale to `en`, then your first supported locale
208
225
 
@@ -412,16 +412,11 @@ setData({}, { deletes: ['pinboard.Notes.p1'] }); // the note's key is gone, not
412
412
  Two copies of React are loaded: one from your package and one from the `file://` SDK dependency. Add `resolve.dedupe` to your `vitest.config.ts`, with the SDK packages beside React so a second copy of the SDK cannot hide the providers either:
413
413
 
414
414
  ```typescript
415
+ import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite';
416
+
415
417
  export default defineConfig({
416
418
  resolve: {
417
- dedupe: [
418
- 'react',
419
- 'react-dom',
420
- '@emotion/react',
421
- '@emotion/styled',
422
- '@seriousgaming/sdk',
423
- '@seriousgaming/deck',
424
- ],
419
+ dedupe: [...REACT_CONTEXT_PACKAGES],
425
420
  },
426
421
  // ...
427
422
  });