@seriousgaming/sdk-tools 1.10.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 (105) hide show
  1. package/dist/agent/guidance.md +31 -23
  2. package/dist/{cli-5V4N4BR4.js → cli-27TQVLVF.js} +1 -1
  3. package/dist/{cli-FGP6YYM7.js → cli-3VLBFWHN.js} +8 -8
  4. package/dist/{cli-XR3O2YTV.js → cli-4F24FUW6.js} +5 -5
  5. package/dist/{cli-CQ4ZR3ZQ.js → cli-5ATO27Z4.js} +5 -5
  6. package/dist/{cli-MGZYQDCH.js → cli-5TTJWM2R.js} +5 -5
  7. package/dist/{cli-6CYAOUYT.js → cli-5UKWX3IU.js} +4 -4
  8. package/dist/{cli-LLJQI2QP.js → cli-6AMK3DYS.js} +1 -1
  9. package/dist/{cli-WOFYI7HZ.js → cli-6JWDFCUV.js} +6 -6
  10. package/dist/{cli-A3AJQZEN.js → cli-6P6V2EHY.js} +7 -7
  11. package/dist/{cli-RSF5R3HC.js → cli-77T4LJQF.js} +10 -7
  12. package/dist/{cli-LNEZ6KDW.js → cli-ATAJSIXH.js} +4 -4
  13. package/dist/{cli-4A7RWFNO.js → cli-ATHATKI5.js} +47 -47
  14. package/dist/{cli-QW7VXL2V.js → cli-B2QAJ5RQ.js} +5 -5
  15. package/dist/{cli-BB6CU4ZC.js → cli-BINVO5R7.js} +8 -8
  16. package/dist/{cli-5SHG2M7E.js → cli-BJFYGVJV.js} +4 -4
  17. package/dist/{cli-J42N4PJG.js → cli-BZOKZ7LP.js} +11 -9
  18. package/dist/{cli-MUOLHQNL.js → cli-D3S7NJZ3.js} +1 -1
  19. package/dist/{cli-WLSACMYA.js → cli-DBMEH4Y5.js} +10 -8
  20. package/dist/{cli-CLO7HKEQ.js → cli-DH35TZ2Q.js} +4 -2
  21. package/dist/{cli-2ANX6E3A.js → cli-DQE7ITIR.js} +5 -5
  22. package/dist/{cli-467VRXGP.js → cli-EEO5ZPAZ.js} +1 -1
  23. package/dist/{cli-B5DWKRZ4.js → cli-ERJNDBDH.js} +1 -1
  24. package/dist/{cli-IQBY7Z7Q.js → cli-FT3X3D4P.js} +5 -5
  25. package/dist/{cli-5TKPT3CY.js → cli-FYPW25VD.js} +4 -4
  26. package/dist/{cli-36GABN2A.js → cli-G3TU6CP6.js} +5 -5
  27. package/dist/{cli-NAZTYKZT.js → cli-H6PP2MZT.js} +14 -2
  28. package/dist/{cli-5XE4OMFL.js → cli-HLI5UEKX.js} +8 -8
  29. package/dist/{cli-YZJBFKRI.js → cli-HMDYG6PS.js} +5 -5
  30. package/dist/{cli-2AH6D32V.js → cli-K4HSQWXC.js} +1 -1
  31. package/dist/{cli-EXUPHPDJ.js → cli-L7F4XKCB.js} +7 -7
  32. package/dist/{cli-O5WYATAI.js → cli-LHMRUJVN.js} +3 -1
  33. package/dist/{cli-VALLLE6Y.js → cli-LPFSJ625.js} +7 -7
  34. package/dist/{cli-HN442ZVK.js → cli-MSNSXVGF.js} +5 -5
  35. package/dist/{cli-OXU6TTEN.js → cli-NKKCDO6K.js} +5 -5
  36. package/dist/{cli-L54SXUK6.js → cli-OBLEROSC.js} +4 -4
  37. package/dist/{cli-RFAPPYXK.js → cli-OF36EA62.js} +8 -8
  38. package/dist/{cli-XB5PI2XT.js → cli-OM32UURE.js} +6 -6
  39. package/dist/{cli-2AVPNSAX.js → cli-OMTHTWYJ.js} +6 -6
  40. package/dist/{cli-I3ZAZYWP.js → cli-OVIJRBFI.js} +8 -8
  41. package/dist/{cli-IPTHJT3J.js → cli-PNS4KWWC.js} +10 -7
  42. package/dist/{cli-VZVHS5AP.js → cli-Q7QSWNY2.js} +5 -5
  43. package/dist/{cli-GRSQRFRG.js → cli-QEFYDXMH.js} +8 -1
  44. package/dist/{cli-TDLIPYKT.js → cli-QPV3TYOM.js} +8 -8
  45. package/dist/{cli-PYAST3G5.js → cli-R5SNTPND.js} +6 -6
  46. package/dist/{cli-WG7MAOCS.js → cli-REAM7LSC.js} +5 -5
  47. package/dist/{cli-URCHZDTS.js → cli-RHL4B4H7.js} +3 -2
  48. package/dist/{cli-KNXY43YV.js → cli-RKPQLB7J.js} +1 -1
  49. package/dist/{cli-PBSLPO6G.js → cli-RMD5WSUQ.js} +4 -4
  50. package/dist/{cli-PTXOKO2Y.js → cli-S3NHXAJM.js} +1 -1
  51. package/dist/{cli-33MZSPPK.js → cli-SRXDLMXY.js} +6 -6
  52. package/dist/{cli-M6AZFIMV.js → cli-TEBV2OIW.js} +5 -2
  53. package/dist/{cli-35GV2F6R.js → cli-TI2FOFPA.js} +4 -4
  54. package/dist/{cli-JMNPMDXH.js → cli-TLSTSZAC.js} +7 -7
  55. package/dist/{cli-XEEOJGBL.js → cli-UIYKPSIY.js} +8 -8
  56. package/dist/{cli-267QJ2DS.js → cli-UVIURDZC.js} +1 -1
  57. package/dist/{cli-JAVMRERQ.js → cli-VXLHOZSO.js} +5 -5
  58. package/dist/{cli-SOO6SEIS.js → cli-WJVPSVF2.js} +10 -7
  59. package/dist/{cli-RUEPTOWG.js → cli-WNBP3LOD.js} +7 -7
  60. package/dist/{cli-ILHHJR2S.js → cli-WNHMJM3Z.js} +5 -5
  61. package/dist/{cli-4JNF3O5N.js → cli-WQ7JBZNW.js} +1 -1
  62. package/dist/{cli-5DWR7RPQ.js → cli-X3TSTTYI.js} +1 -1
  63. package/dist/{cli-Z3DITVBE.js → cli-X52TXCNF.js} +7 -7
  64. package/dist/{cli-HNG6PZW2.js → cli-XJ7JESC2.js} +7 -7
  65. package/dist/{cli-7NUFHMGE.js → cli-XNOAO6DY.js} +1 -1
  66. package/dist/{cli-HHRP6FP6.js → cli-XOYUTNER.js} +7 -7
  67. package/dist/{cli-YFLQ7XOO.js → cli-YYXAGJQR.js} +5 -5
  68. package/dist/{cli-NQSL2CIH.js → cli-ZGCG6C22.js} +6 -6
  69. package/dist/cli.js +24 -24
  70. package/dist/client/index.d.ts +1 -1
  71. package/dist/client/test-session.d.ts +44 -6
  72. package/dist/client.js +16 -3
  73. package/dist/docs/api/index.md +3 -1
  74. package/dist/docs/api/sdk-tools-client.md +38 -6
  75. package/dist/docs/api/sdk-tools-vite.md +21 -0
  76. package/dist/docs/changelog.md +39 -0
  77. package/dist/docs/guides/endpoints.md +1 -1
  78. package/dist/docs/guides/engine-testing.md +49 -14
  79. package/dist/docs/guides/engine.md +2 -2
  80. package/dist/docs/guides/testing.md +3 -8
  81. package/dist/docs/guides/upgrading.md +15 -0
  82. package/dist/docs/page-index.md +4 -3
  83. package/dist/docs/recipes/create-game.md +1 -1
  84. package/dist/docs/recipes/fix-duplicate-packages.md +8 -19
  85. package/dist/oxlint/logic.json +184 -0
  86. package/dist/playwright.js +16 -3
  87. package/dist/templates/package/README.md.liquid +1 -0
  88. package/dist/templates/package/claude/rules/workflow-create-engine.md +1 -1
  89. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  90. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  91. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +2 -2
  92. package/dist/templates/package/claude/settings.json.template +1 -0
  93. package/dist/templates/package/oxfmtrc.json.template +8 -1
  94. package/dist/templates/package/oxlintrc.json.template +1 -180
  95. package/dist/templates/package/package.json.liquid +1 -0
  96. package/dist/templates/package/vite.config.ts.liquid +2 -8
  97. package/dist/templates/package/vitest.config.ts.liquid +2 -8
  98. package/dist/templates/starter-game/package.json +2 -1
  99. package/dist/templates/starter-game/testing/engine/game.engine.test.ts +62 -37
  100. package/dist/templates/starter-game/vite.config.ts +2 -8
  101. package/dist/templates/starter-game/vitest.config.ts +4 -3
  102. package/dist/utils/resource-scan.d.ts +5 -0
  103. package/dist/vite/index.d.ts +30 -0
  104. package/dist/vite.js +12 -0
  105. package/package.json +12 -4
package/dist/cli.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  RESOURCE_DESCRIPTORS,
4
4
  lazy
5
- } from "./cli-4A7RWFNO.js";
5
+ } from "./cli-ATHATKI5.js";
6
6
  import {
7
7
  DEV_PORT_ENV_VAR,
8
8
  ERROR_OVERLAY_ENV_VAR,
@@ -139,14 +139,14 @@ function newFileHelp(spec) {
139
139
 
140
140
  // cli/program.ts
141
141
  var blobUploadCommand = lazy(() => import("./cli-W3RG2MRI.js"), "blobUploadCommand");
142
- var buildCommand = lazy(() => import("./cli-NAZTYKZT.js"), "buildCommand");
142
+ var buildCommand = lazy(() => import("./cli-H6PP2MZT.js"), "buildCommand");
143
143
  var buildEngineCommand = lazy(() => import("./cli-5EH4WTH4.js"), "buildEngineCommand");
144
144
  var configGetCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configGetCommand");
145
145
  var configPathCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configPathCommand");
146
146
  var configSetCommand = lazy(() => import("./cli-OXLOGXT3.js"), "configSetCommand");
147
147
  var configureCommand = lazy(() => import("./cli-XKAIDYIE.js"), "configureCommand");
148
- var deleteCommand = lazy(() => import("./cli-LLJQI2QP.js"), "deleteCommand");
149
- var devCommand = lazy(() => import("./cli-267QJ2DS.js"), "devCommand");
148
+ var deleteCommand = lazy(() => import("./cli-6AMK3DYS.js"), "deleteCommand");
149
+ var devCommand = lazy(() => import("./cli-UVIURDZC.js"), "devCommand");
150
150
  var devStatusCommand = lazy(() => import("./cli-5Z4D3F6Y.js"), "devStatusCommand");
151
151
  var devStopCommand = lazy(() => import("./cli-5Z4D3F6Y.js"), "devStopCommand");
152
152
  var docsCommand = lazy(() => import("./cli-44CM2AH2.js"), "docsCommand");
@@ -159,7 +159,7 @@ var endpointCallCommand = lazy(() => import("./cli-JHLWBRXB.js"), "endpointCallC
159
159
  var endpointListCommand = lazy(() => import("./cli-HGCOEL5T.js"), "endpointListCommand");
160
160
  var generateCommand = lazy(() => import("./cli-WZNIW6ZO.js"), "generateCommand");
161
161
  var initCommand = lazy(() => import("./cli-GSOV26O5.js"), "initCommand");
162
- var newCommand = lazy(() => import("./cli-7NUFHMGE.js"), "newCommand");
162
+ var newCommand = lazy(() => import("./cli-XNOAO6DY.js"), "newCommand");
163
163
  var packageBundleCommand = lazy(
164
164
  () => import("./cli-BQ36DV5C.js"),
165
165
  "packageBundleCommand"
@@ -174,29 +174,29 @@ var packageVersionCommand = lazy(
174
174
  );
175
175
  var patchCommand = lazy(() => import("./cli-KJA6GLZI.js"), "patchCommand");
176
176
  var resolveCommand = lazy(() => import("./cli-IKSLPAZN.js"), "resolveCommand");
177
- var screenshotCommand = lazy(() => import("./cli-PTXOKO2Y.js"), "screenshotCommand");
178
- var clockAdvanceCommand = lazy(() => import("./cli-MUOLHQNL.js"), "clockAdvanceCommand");
179
- var faultCommand = lazy(() => import("./cli-MUOLHQNL.js"), "faultCommand");
180
- var localeCommand = lazy(() => import("./cli-MUOLHQNL.js"), "localeCommand");
181
- var participantAddCommand = lazy(() => import("./cli-MUOLHQNL.js"), "participantAddCommand");
182
- var participantJoinCommand = lazy(() => import("./cli-MUOLHQNL.js"), "participantJoinCommand");
183
- var participantMoveCommand = lazy(() => import("./cli-MUOLHQNL.js"), "participantMoveCommand");
177
+ var screenshotCommand = lazy(() => import("./cli-S3NHXAJM.js"), "screenshotCommand");
178
+ var clockAdvanceCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "clockAdvanceCommand");
179
+ var faultCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "faultCommand");
180
+ var localeCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "localeCommand");
181
+ var participantAddCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantAddCommand");
182
+ var participantJoinCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantJoinCommand");
183
+ var participantMoveCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "participantMoveCommand");
184
184
  var participantRenameCommand = lazy(
185
- () => import("./cli-MUOLHQNL.js"),
185
+ () => import("./cli-D3S7NJZ3.js"),
186
186
  "participantRenameCommand"
187
187
  );
188
- var playCommand = lazy(() => import("./cli-MUOLHQNL.js"), "playCommand");
189
- var reconfigureCommand = lazy(() => import("./cli-MUOLHQNL.js"), "reconfigureCommand");
190
- var resetCommand = lazy(() => import("./cli-MUOLHQNL.js"), "resetCommand");
191
- var scenarioCommand = lazy(() => import("./cli-MUOLHQNL.js"), "scenarioCommand");
192
- var teamAddCommand = lazy(() => import("./cli-MUOLHQNL.js"), "teamAddCommand");
193
- var teamRemoveCommand = lazy(() => import("./cli-MUOLHQNL.js"), "teamRemoveCommand");
194
- var teamRenameCommand = lazy(() => import("./cli-MUOLHQNL.js"), "teamRenameCommand");
195
- var timerCommand = lazy(() => import("./cli-MUOLHQNL.js"), "timerCommand");
196
- var undoCommand = lazy(() => import("./cli-MUOLHQNL.js"), "undoCommand");
197
- var waitingRoomCommand = lazy(() => import("./cli-MUOLHQNL.js"), "waitingRoomCommand");
188
+ var playCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "playCommand");
189
+ var reconfigureCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "reconfigureCommand");
190
+ var resetCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "resetCommand");
191
+ var scenarioCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "scenarioCommand");
192
+ var teamAddCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamAddCommand");
193
+ var teamRemoveCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamRemoveCommand");
194
+ var teamRenameCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "teamRenameCommand");
195
+ var timerCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "timerCommand");
196
+ var undoCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "undoCommand");
197
+ var waitingRoomCommand = lazy(() => import("./cli-D3S7NJZ3.js"), "waitingRoomCommand");
198
198
  var tickCommand = lazy(() => import("./cli-27Z5T52R.js"), "tickCommand");
199
- var updateCommand = lazy(() => import("./cli-5V4N4BR4.js"), "updateCommand");
199
+ var updateCommand = lazy(() => import("./cli-27TQVLVF.js"), "updateCommand");
200
200
  var versionCommand = lazy(() => import("./cli-5M6KDNVX.js"), "versionCommand");
201
201
  var viewCommand = lazy(() => import("./cli-MDVC5ZNM.js"), "viewCommand");
202
202
  function commandPath(command) {
@@ -19,7 +19,7 @@
19
19
  * ```
20
20
  */
21
21
  export type { ContextDeletePath, ContextUpdate, SignatureCallbacks } from '@seriousgaming/sdk';
22
- export { createTestSession, type TestSession, type TestSessionOptions, type TestSessionSetDataOptions, type TestSessionSetSharedDataOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
22
+ export { createTestSession, type LogicErrorLocation, type TestMutationResult, type TestSession, type TestSessionOptions, type TestSessionSetDataOptions, type TestSessionSetSharedDataOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
23
23
  export { startDevServer, type DevServer, type DevServerOptions } from './dev-server';
24
24
  export { buildSurfaces, type BuildSurfacesOptions, type BuiltSurfaces } from './build-surfaces';
25
25
  export { createStubServices, stubGenerateText, type TestServices } from './stub-services';
@@ -62,6 +62,44 @@ export interface TestSessionOptions {
62
62
  apiHost?: string;
63
63
  };
64
64
  }
65
+ /**
66
+ * Where game logic threw, read back to the file the author wrote: the resource
67
+ * whose logic it was, the tick and team it ran for, and the source position.
68
+ * `file` is relative to the package root; `line` and `column` are 1-based.
69
+ */
70
+ export interface LogicErrorLocation {
71
+ resource: {
72
+ type: string;
73
+ identifier: string;
74
+ };
75
+ message: string;
76
+ tick?: number;
77
+ team?: {
78
+ teamId: string;
79
+ index: number;
80
+ };
81
+ file?: string;
82
+ line?: number;
83
+ column?: number;
84
+ }
85
+ /**
86
+ * What a test session answers a mutation with. A refusal that came from logic
87
+ * throwing (a failed tick, a hook, a validator) carries `logicError` beside
88
+ * its outcome, which is what `sdk tick` reports from the command line:
89
+ *
90
+ * ```ts
91
+ * const result = await session.tick();
92
+ * if (!result.ok) {
93
+ * const at = result.logicError;
94
+ * throw new Error(`${result.outcome.kind} at ${at?.file}:${at?.line} (tick ${at?.tick})`);
95
+ * }
96
+ * ```
97
+ *
98
+ * A surface never sees it: the outcome alone is what the runtime tells one.
99
+ */
100
+ export type TestMutationResult = MutationResult & {
101
+ logicError?: LogicErrorLocation;
102
+ };
65
103
  /** A capability context as the projection carries it, before a game's types narrow it. */
66
104
  export type UntypedContext = Record<string, Record<string, unknown>>;
67
105
  /** One team as {@link TestSession.state} reports it, its context typed. */
@@ -119,9 +157,9 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
119
157
  * `{ ok: true }` or `{ ok: false, outcome }`, and a read answers with its
120
158
  * result. A refusal is an answer, not a throw.
121
159
  */
122
- send(command: MutationCommand): Promise<MutationResult>;
160
+ send(command: MutationCommand): Promise<TestMutationResult>;
123
161
  send(command: QueryCommand): Promise<QueryResult>;
124
- send(command: Command): Promise<MutationResult | QueryResult>;
162
+ send(command: Command): Promise<TestMutationResult | QueryResult>;
125
163
  /** The whole session now: teams, contexts, rosters, the store, the timer. */
126
164
  state(): TestSessionState<Context, Shared>;
127
165
  /**
@@ -143,7 +181,7 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
143
181
  */
144
182
  tick(options?: {
145
183
  team?: number;
146
- }): Promise<MutationResult>;
184
+ }): Promise<TestMutationResult>;
147
185
  /**
148
186
  * Ask for the next tick as a participant's surface does, so the
149
187
  * validators' `RequestTick` gates judge it. Asks as the team's first
@@ -151,14 +189,14 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
151
189
  */
152
190
  requestTick(team: number, options?: {
153
191
  participantId?: string;
154
- }): Promise<MutationResult>;
192
+ }): Promise<TestMutationResult>;
155
193
  /**
156
194
  * Write to one team's context, by stable index. As a participant through
157
195
  * `ui` unless `as: 'system'` (see {@link TestSessionSetDataOptions}).
158
196
  */
159
- setData(team: number, patch: ContextUpdate<Context>, options?: TestSessionSetDataOptions): Promise<MutationResult>;
197
+ setData(team: number, patch: ContextUpdate<Context>, options?: TestSessionSetDataOptions): Promise<TestMutationResult>;
160
198
  /** Write to the shared store, as the facilitator does. */
161
- setSharedData(patch: ContextUpdate<Shared>, options?: TestSessionSetSharedDataOptions): Promise<MutationResult>;
199
+ setSharedData(patch: ContextUpdate<Shared>, options?: TestSessionSetSharedDataOptions): Promise<TestMutationResult>;
162
200
  /**
163
201
  * Resolves once everything queued has run, including a tick a timer set
164
202
  * off. `advanceClock` already waits; this is for a timer moved by hand.
package/dist/client.js CHANGED
@@ -28030,6 +28030,7 @@ import { WebSocketServer } from "ws";
28030
28030
 
28031
28031
  // cli/core/listen-with-fallback.ts
28032
28032
  import { createServer as createSocket } from "net";
28033
+ var PORT_IN_USE_HINT = "`sdk dev status` says whether a dev server is already running for this package. Pass --port auto to take any free port.";
28033
28034
  async function listenWithPortFallback(server, startPort, options = {}) {
28034
28035
  const maxAttempts = options.maxAttempts ?? 100;
28035
28036
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
@@ -28043,7 +28044,8 @@ async function listenWithPortFallback(server, startPort, options = {}) {
28043
28044
  }
28044
28045
  throw new CliError(
28045
28046
  "PORT_IN_USE",
28046
- `Could not find available port after ${maxAttempts} attempts`
28047
+ `Could not find available port after ${maxAttempts} attempts`,
28048
+ { hint: PORT_IN_USE_HINT }
28047
28049
  );
28048
28050
  }
28049
28051
  function tryListen(server, port, host) {
@@ -28081,7 +28083,8 @@ async function findFreePort(startPort, maxAttempts = 100) {
28081
28083
  }
28082
28084
  throw new CliError(
28083
28085
  "PORT_IN_USE",
28084
- `Could not find available port after ${maxAttempts} attempts`
28086
+ `Could not find available port after ${maxAttempts} attempts`,
28087
+ { hint: PORT_IN_USE_HINT }
28085
28088
  );
28086
28089
  }
28087
28090
  var PROBED_ADDRESSES = [void 0, "127.0.0.1", "::1"];
@@ -33458,6 +33461,16 @@ function distPath(meta, identifier) {
33458
33461
  return `${meta.pluralDir}/${identifier}`;
33459
33462
  }
33460
33463
 
33464
+ // cli/vite/index.ts
33465
+ var REACT_CONTEXT_PACKAGES = [
33466
+ "react",
33467
+ "react-dom",
33468
+ "@emotion/react",
33469
+ "@emotion/styled",
33470
+ "@seriousgaming/sdk",
33471
+ "@seriousgaming/deck"
33472
+ ];
33473
+
33461
33474
  // cli/bundling/ui-bundler.ts
33462
33475
  async function bundleUserInterface(ui, workingDir, buildDir, type) {
33463
33476
  const uiOutputDir = join21(buildDir, distPath(getResourceMeta(type), ui.definition.identifier));
@@ -33483,7 +33496,7 @@ async function bundleUserInterface(ui, workingDir, buildDir, type) {
33483
33496
  configFile: false,
33484
33497
  plugins: [react2()],
33485
33498
  resolve: {
33486
- dedupe: ["react", "react-dom", "@emotion/react", "@emotion/styled"]
33499
+ dedupe: [...REACT_CONTEXT_PACKAGES]
33487
33500
  },
33488
33501
  build: {
33489
33502
  outDir: uiOutputDir,
@@ -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
+ ```
@@ -27,10 +27,49 @@ 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
+
34
73
  ## [1.10.0] — 2026-11-07
35
74
 
36
75
  ### Added
@@ -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
 
@@ -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
  });
@@ -700,6 +700,21 @@ A host may now offer one join link for the whole session and put each person who
700
700
 
701
701
  A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
702
702
 
703
+ ### 1.11: catch an older package's scaffold up
704
+
705
+ Nothing here is required. A package made by `sdk new package` at 1.11 has all of it, and from 1.11 each release's changelog lists what changed in the scaffold under **Scaffold changes**, one line per file, so a later upgrade only has to read those lines. An older package copies from `node_modules/@seriousgaming/sdk-tools/dist/templates/package/`, in this order:
706
+
707
+ 1. **Replace `playwright.config.ts` first**, if it still names a port. Copy `global-setup.ts.template` to `testing/e2e/global-setup.ts` and replace `playwright.config.ts` from `playwright.config.ts.liquid`: and import `test` and `expect` from `@seriousgaming/sdk-tools/playwright` in each spec. Every worker then starts an isolated dev server on free ports, so two packages, or two checkouts of one, can run their browser tests at once
708
+ 2. **Add the `check` script** to `package.json`, from `package.json.liquid`. It validates the package, typechecks, lints, and runs the unit and engine tests, stopping at the first that fails. Drop the `test:engine` step from it if the package has no engine tests
709
+ 3. **Add an engine test that plays every scenario**, as [Playing every scenario](./engine-testing.md#playing-every-scenario) shows. Engine tests run logic in the restricted runtime, so this is what catches a scenario the engine cannot play
710
+ 4. **Extend the SDK's lint rules for logic** in place of your copy. In `.oxlintrc.json`, add `"extends": ["./node_modules/@seriousgaming/sdk-tools/dist/oxlint/logic.json"]` and delete the override that lists `no-restricted-globals`, and the one that turns it off for tests. The list of globals the production runtime lacks then comes from the installed SDK
711
+ 5. **Read the dedupe list from the SDK** in `vite.config.ts` and `vitest.config.ts`: `import { REACT_CONTEXT_PACKAGES } from '@seriousgaming/sdk-tools/vite'` and set `resolve.dedupe` to `[...REACT_CONTEXT_PACKAGES]`, followed by any package of your own that holds React context
712
+ 6. **Keep build output out of the formatter.** Add `lib/`, `test-results/` and `playwright-report/` to `ignorePatterns` in `.oxfmtrc.json`
713
+ 7. **Write the team mode down.** If `seriousgaming.sdk.json` has no `teams.mode`, add `"teams": { "mode": "independent" }`, which is what it has been running as, or `"shared-state"` if that is what the game needs
714
+ 8. **Refresh the upgrade rule itself.** Replace `.claude/rules/workflow-update-sdk-version.md` from `claude/rules/`: the new one reads the **Scaffold changes** sections on every later upgrade
715
+
716
+ A workspace of several games applies each step to every game. The copies stay the game's own, so keep any local edit a template does not have.
717
+
703
718
  ### Optional: import the SDK's agent guidance in `CLAUDE.md`
704
719
 
705
720
  A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
@@ -45,7 +45,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
45
45
  - [`guides/designing-a-game.md`](guides/designing-a-game.md), about 13k characters: A serious game teaches by letting people act and then see what their actions caused.
46
46
  - [`guides/designing-screens.md`](guides/designing-screens.md), about 12k characters: What a good simulation screen looks like, whatever the brand: how to decide what a screen should be before you build it, and how to check it afterwards.
47
47
  - [`guides/endpoints.md`](guides/endpoints.md), about 29k characters: An endpoint is a named, server-side handler that a caller invokes by identifier: one of the game's own user interfaces, or a caller outside the game, such as a facilitator's AI agent or a platform API, when the endpoint allows it.
48
- - [`guides/engine-testing.md`](guides/engine-testing.md), about 28k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
48
+ - [`guides/engine-testing.md`](guides/engine-testing.md), about 30k characters: Test your whole game in-process: no dev server, no browser, and no LLM API key required, because service callbacks are stubbed by default.
49
49
  - [`guides/engine.md`](guides/engine.md), about 33k characters: The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick.
50
50
  - [`guides/file-handling.md`](guides/file-handling.md), about 28k characters: Ship files with your game or let participants upload them, then show them in any UI and read them in logic, all through one reference scheme.
51
51
  - [`guides/games.md`](guides/games.md), about 7k characters: Shape the game as a whole: how many rounds it runs, how teams form, which languages it speaks, and where participants wait.
@@ -76,7 +76,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
76
76
  - [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
77
77
  - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
78
  - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
- - [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
79
+ - [`guides/upgrading.md`](guides/upgrading.md), about 71k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
80
  - [`guides/validators.md`](guides/validators.md), about 25k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
81
  - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
82
82
 
@@ -142,8 +142,9 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
142
142
  - [`api/sdk-e2e.md`](api/sdk-e2e.md), about 11k characters: End-to-end testing helpers for Serious Gaming SDK consumers.
143
143
  - [`api/sdk-projection.md`](api/sdk-projection.md), about 5k characters: The one documented shape of a session's observable state.
144
144
  - [`api/sdk-testing.md`](api/sdk-testing.md), about 7k characters: Helpers for unit-testing a game's logic without a runtime.
145
- - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
145
+ - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 15k characters: Programmatic API for testing a game in-process.
146
146
  - [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
147
+ - [`api/sdk-tools-vite.md`](api/sdk-tools-vite.md), under 1k characters: What a game's Vite and Vitest configs need from the SDK.
147
148
  - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
148
149
  - [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
149
150
  - [`api/sdk.md`](api/sdk.md), about 59k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.