@seriousgaming/sdk-tools 1.0.0-alpha.3 → 1.0.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 (58) hide show
  1. package/README.md +5 -5
  2. package/dist/cli.js +30 -12
  3. package/dist/client/index.d.ts +2 -2
  4. package/dist/client/test-session.d.ts +12 -15
  5. package/dist/client.js +20 -11
  6. package/dist/docs/api/index.md +1 -1
  7. package/dist/docs/api/sdk-tools-client.md +40 -32
  8. package/dist/docs/api/sdk-ui-testing.md +4 -4
  9. package/dist/docs/api/sdk-ui.md +80 -20
  10. package/dist/docs/api/sdk.md +37 -21
  11. package/dist/docs/changelog.md +119 -74
  12. package/dist/docs/cli-and-dev-server.md +16 -15
  13. package/dist/docs/concepts/index.md +1 -1
  14. package/dist/docs/concepts/terminology.md +6 -6
  15. package/dist/docs/getting-started.md +4 -2
  16. package/dist/docs/guides/engine-testing.md +1 -1
  17. package/dist/docs/guides/engine.md +13 -0
  18. package/dist/docs/guides/file-handling.md +4 -4
  19. package/dist/docs/guides/internationalization.md +15 -1
  20. package/dist/docs/guides/llm-integration.md +2 -0
  21. package/dist/docs/guides/patterns.md +33 -5
  22. package/dist/docs/guides/presentation.md +9 -9
  23. package/dist/docs/guides/session.md +22 -19
  24. package/dist/docs/guides/testing.md +1 -1
  25. package/dist/docs/guides/tick-controller.md +5 -3
  26. package/dist/docs/guides/ui.md +5 -1
  27. package/dist/docs/guides/upgrading.md +40 -5
  28. package/dist/docs/recipes/create-endpoint.md +1 -1
  29. package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
  30. package/dist/docs/recipes/use-request-tick.md +1 -1
  31. package/dist/docs/troubleshooting.md +6 -4
  32. package/dist/schema.json +6 -6
  33. package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
  34. package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
  35. package/dist/templates/engine/logic.test.ts.liquid +22 -34
  36. package/dist/templates/hook/logic.test.ts.liquid +28 -32
  37. package/dist/templates/package/CLAUDE.md.template +1 -1
  38. package/dist/templates/package/README.md.liquid +3 -3
  39. package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
  40. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
  41. package/dist/templates/presentation/src/App.tsx.liquid +1 -1
  42. package/dist/templates/session/src/main.tsx.liquid +3 -3
  43. package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
  44. package/dist/templates/starter-game/engine/logic.test.ts +37 -47
  45. package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
  46. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
  47. package/dist/templates/starter-game/session/src/main.tsx +3 -3
  48. package/dist/templates/starter-game/ui/src/main.tsx +3 -3
  49. package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
  50. package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
  51. package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
  52. package/dist/templates/ui/src/App.tsx.liquid +22 -11
  53. package/dist/templates/ui/src/i18n.ts.liquid +3 -0
  54. package/dist/templates/ui/src/main.tsx.liquid +3 -3
  55. package/dist/templates/validator/logic.test.ts.liquid +21 -30
  56. package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
  57. package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
  58. package/package.json +3 -3
package/README.md CHANGED
@@ -16,14 +16,14 @@ The scaffolded package installs this package beside `@seriousgaming/sdk`, which
16
16
 
17
17
  ## Stability
18
18
 
19
- A version with a prerelease suffix, such as `1.0.0-alpha.1`, carries none of these guarantees: it can change in any way before the release it leads to. Until 1.0.0 ships, npm's `latest` tag points at a prerelease, so a bare install gets one.
19
+ A version with a prerelease suffix, such as `1.0.0-alpha.1`, carries none of these guarantees: it can change in any way before the release it leads to.
20
20
 
21
21
  From 1.0.0, these follow semantic versioning. A breaking change waits for a major release:
22
22
 
23
- | Surface | What it holds |
24
- | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
25
- | The `seriousgaming-sdk` command | Commands, flags, the JSON result envelope, exit codes and error codes. Message text is not part of it |
26
- | `./client` | `createTestSession`, `startDevServer`, `FakeClock`, the stub services and their types |
23
+ | Surface | What it holds |
24
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | The `seriousgaming-sdk` command | Commands, flags, the JSON result envelope, exit codes and error codes. Message text is not part of it |
26
+ | `./client` | `createTestSession`, `startDevServer`, `FakeClock`, the stub services and their types, and the command and projection types it re-exports from `@seriousgaming/sdk` |
27
27
 
28
28
  These exist for the Serious Gaming platform and this repository's own tooling, not for games, and clause 4(b) of the licence does not allow you to use them to build any other runtime. They are versioned with the package but may change in a minor release:
29
29
 
package/dist/cli.js CHANGED
@@ -2009,7 +2009,7 @@ var schema_default = {
2009
2009
  type: "object",
2010
2010
  description: "Localized scenario fields with one entry per supported locale",
2011
2011
  patternProperties: {
2012
- "^[a-z]{2}(-[A-Z]{2})?$": {
2012
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
2013
2013
  type: "object",
2014
2014
  description: "Localized fields for this locale",
2015
2015
  properties: {
@@ -2063,7 +2063,7 @@ var schema_default = {
2063
2063
  type: "object",
2064
2064
  description: "Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.",
2065
2065
  patternProperties: {
2066
- "^[a-z]{2}(-[A-Z]{2})?$": {
2066
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
2067
2067
  type: "object",
2068
2068
  description: "Localized fields for this locale",
2069
2069
  properties: {
@@ -2112,7 +2112,7 @@ var schema_default = {
2112
2112
  description: "List of locales supported by this game (e.g., ['en', 'es', 'fr'])",
2113
2113
  items: {
2114
2114
  type: "string",
2115
- pattern: "^[a-z]{2}(-[A-Z]{2})?$"
2115
+ pattern: "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
2116
2116
  },
2117
2117
  minItems: 1,
2118
2118
  uniqueItems: true
@@ -2121,7 +2121,7 @@ var schema_default = {
2121
2121
  type: "object",
2122
2122
  description: "Localized game fields with one entry per supported locale",
2123
2123
  patternProperties: {
2124
- "^[a-z]{2}(-[A-Z]{2})?$": {
2124
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
2125
2125
  type: "object",
2126
2126
  description: "Localized fields for this locale",
2127
2127
  properties: {
@@ -2188,7 +2188,7 @@ var schema_default = {
2188
2188
  type: "object",
2189
2189
  description: "Localised default name for one team, with one entry per supported locale",
2190
2190
  patternProperties: {
2191
- "^[a-z]{2}(-[A-Z]{2})?$": {
2191
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
2192
2192
  type: "object",
2193
2193
  description: "Localised fields for this locale",
2194
2194
  properties: {
@@ -2317,7 +2317,7 @@ var schema_default = {
2317
2317
  type: "object",
2318
2318
  description: "Localised default name for one team, with one entry per supported locale",
2319
2319
  patternProperties: {
2320
- "^[a-z]{2}(-[A-Z]{2})?$": {
2320
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
2321
2321
  type: "object",
2322
2322
  description: "Localised fields for this locale",
2323
2323
  properties: {
@@ -5995,7 +5995,19 @@ ${contextTS}${teamContextTS}${writesTS}${teamWritesTS}${settingsTS}${handlerAlia
5995
5995
  schema: schema2
5996
5996
  })
5997
5997
  ])
5998
- )
5998
+ ),
5999
+ ...hasSettings ? {
6000
+ settings: Object.fromEntries(
6001
+ Object.entries(settingsScope.properties).map(([identifier, schema2]) => [
6002
+ identifier,
6003
+ schemaDefaults2({
6004
+ owner: `Settings "${identifier}"`,
6005
+ kind: "configuration",
6006
+ schema: schema2
6007
+ })
6008
+ ])
6009
+ )
6010
+ } : {}
5999
6011
  });
6000
6012
  }
6001
6013
 
@@ -9117,6 +9129,7 @@ function formatPlatformErrors(body) {
9117
9129
  // cli/utils/llm-client.ts
9118
9130
  var TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
9119
9131
  var STOP_REASONS = ["endTurn", "toolUse", "maxTokens", "refusal"];
9132
+ var CONTENT_BLOCK_TYPES = ["text", "toolUse", "toolResult"];
9120
9133
  var LLM_NOT_CONFIGURED = "LLM_NOT_CONFIGURED";
9121
9134
  var LLM_NOT_CONFIGURED_HINT = "Set SERIOUSGAMING_API_KEY in the environment or in .env, or run `seriousgaming-sdk config set platform.apiKey <key>`, or pass `sdk dev --api-key <key>`, then restart the dev server. Issue a key from your organisation settings on the platform.";
9122
9135
  var LLMClientError = class extends Error {
@@ -9221,12 +9234,12 @@ function translateResponse(parsedBody) {
9221
9234
  if (!Array.isArray(content) || content.length === 0) {
9222
9235
  throw new LLMClientError("Empty response from the platform LLM API");
9223
9236
  }
9224
- if (typeof stopReason !== "string" || !STOP_REASONS.includes(stopReason)) {
9237
+ if (typeof stopReason !== "string") {
9225
9238
  throw new LLMClientError("Unexpected response format from the platform LLM API");
9226
9239
  }
9227
9240
  const response = {
9228
- content,
9229
- stopReason
9241
+ content: content.filter(isKnownContentBlock),
9242
+ stopReason: STOP_REASONS.includes(stopReason) ? stopReason : "endTurn"
9230
9243
  };
9231
9244
  if (usage2 && typeof usage2 === "object") {
9232
9245
  const { inputTokens, outputTokens } = usage2;
@@ -9236,6 +9249,11 @@ function translateResponse(parsedBody) {
9236
9249
  }
9237
9250
  return response;
9238
9251
  }
9252
+ function isKnownContentBlock(block) {
9253
+ if (block === null || typeof block !== "object") return false;
9254
+ const { type } = block;
9255
+ return typeof type === "string" && CONTENT_BLOCK_TYPES.includes(type);
9256
+ }
9239
9257
 
9240
9258
  // cli/execution/bundle-reload.ts
9241
9259
  import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
@@ -18292,7 +18310,7 @@ function createHookFiles(options) {
18292
18310
  {
18293
18311
  path: "logic/logic.test.ts",
18294
18312
  template: "hook/logic.test.ts.liquid",
18295
- data: { identifier }
18313
+ data: { identifier, signal: signal2 }
18296
18314
  }
18297
18315
  ]
18298
18316
  });
@@ -18355,7 +18373,7 @@ function createEndpointFiles(options) {
18355
18373
  {
18356
18374
  path: "logic/logic.test.ts",
18357
18375
  template: "endpoint/logic.test.ts.liquid",
18358
- data: { identifier, sessionScoped: scope === "session" }
18376
+ data: { identifier, hasSettings: Boolean(settings && settings.length > 0) }
18359
18377
  }
18360
18378
  ]
18361
18379
  });
@@ -18,8 +18,8 @@
18
18
  * await session.send({ type: 'tick' });
19
19
  * ```
20
20
  */
21
- export type { SignatureCallbacks } from '@seriousgaming/sdk';
22
- export { createTestSession, type ContextPatch, type DeletePath, type SetDataOptions, type SetSharedDataOptions, type TestSession, type TestSessionOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
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';
23
23
  export { startDevServer, type DevServer, type DevServerOptions } from './dev-server';
24
24
  export { createStubServices, stubGenerateText, type TestServices } from './stub-services';
25
25
  export { FakeClock, type Clock } from '../core/clock';
@@ -10,7 +10,7 @@
10
10
  * the console, the CLI or a surface can send, it can send, and it answers the
11
11
  * same way.
12
12
  */
13
- import type { SignatureCallbacks } from '@seriousgaming/sdk';
13
+ import type { ContextDeletePath, ContextUpdate, SignatureCallbacks } from '@seriousgaming/sdk';
14
14
  import type { MutationResult, ProjectedTeam, StateProjection } from '@seriousgaming/sdk/projection';
15
15
  import type { Clock } from '../core/clock';
16
16
  import type { Command, MutationCommand, QueryCommand, QueryResult } from '../core/protocol';
@@ -75,17 +75,12 @@ export type TestSessionState<Context = UntypedContext, Shared = UntypedContext>
75
75
  shared: Shared;
76
76
  };
77
77
  /**
78
- * A write to some of a context's capabilities, each merged one level deep as
79
- * a surface's `setData` is (§9.5): name the variables that change.
78
+ * What {@link TestSession.setData} takes beyond the patch. A surface's
79
+ * `SetDataOptions` carries only `deletes`; a test also says who writes.
80
80
  */
81
- export type ContextPatch<Context> = {
82
- [K in keyof Context]?: Partial<Context[K]>;
83
- };
84
- /** A path to remove, as a surface's `deletes` names one (§9.5). */
85
- export type DeletePath = string | string[];
86
- export interface SetDataOptions {
81
+ export interface TestSessionSetDataOptions {
87
82
  /** Paths to remove once the patch has merged. */
88
- deletes?: DeletePath[];
83
+ deletes?: ContextDeletePath[];
89
84
  /**
90
85
  * Who writes. `'participant'`, the default, writes as a player surface
91
86
  * does: as the team's first participant (or `participantId`), held to the
@@ -99,8 +94,10 @@ export interface SetDataOptions {
99
94
  /** The player surface the participant writes through. Defaults to `ui`. */
100
95
  ui?: string;
101
96
  }
102
- export interface SetSharedDataOptions {
103
- deletes?: DeletePath[];
97
+ /** What {@link TestSession.setSharedData} takes beyond the patch. */
98
+ export interface TestSessionSetSharedDataOptions {
99
+ /** Paths to remove once the patch has merged. */
100
+ deletes?: ContextDeletePath[];
104
101
  /**
105
102
  * The session surface the facilitator writes through, which holds the
106
103
  * write to that surface's `writes`. Omit to write as the CLI does,
@@ -157,11 +154,11 @@ export interface TestSession<Context = UntypedContext, Shared = UntypedContext>
157
154
  }): Promise<MutationResult>;
158
155
  /**
159
156
  * Write to one team's context, by stable index. As a participant through
160
- * `ui` unless `as: 'system'` (see {@link SetDataOptions}).
157
+ * `ui` unless `as: 'system'` (see {@link TestSessionSetDataOptions}).
161
158
  */
162
- setData(team: number, patch: ContextPatch<Context>, options?: SetDataOptions): Promise<MutationResult>;
159
+ setData(team: number, patch: ContextUpdate<Context>, options?: TestSessionSetDataOptions): Promise<MutationResult>;
163
160
  /** Write to the shared store, as the facilitator does. */
164
- setSharedData(patch: ContextPatch<Shared>, options?: SetSharedDataOptions): Promise<MutationResult>;
161
+ setSharedData(patch: ContextUpdate<Shared>, options?: TestSessionSetSharedDataOptions): Promise<MutationResult>;
165
162
  /**
166
163
  * Resolves once everything queued has run, including a tick a timer set
167
164
  * off. `advanceClock` already waits; this is for a timer moved by hand.
package/dist/client.js CHANGED
@@ -1317,7 +1317,7 @@ var schema_default = {
1317
1317
  type: "object",
1318
1318
  description: "Localized scenario fields with one entry per supported locale",
1319
1319
  patternProperties: {
1320
- "^[a-z]{2}(-[A-Z]{2})?$": {
1320
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
1321
1321
  type: "object",
1322
1322
  description: "Localized fields for this locale",
1323
1323
  properties: {
@@ -1371,7 +1371,7 @@ var schema_default = {
1371
1371
  type: "object",
1372
1372
  description: "Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.",
1373
1373
  patternProperties: {
1374
- "^[a-z]{2}(-[A-Z]{2})?$": {
1374
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
1375
1375
  type: "object",
1376
1376
  description: "Localized fields for this locale",
1377
1377
  properties: {
@@ -1420,7 +1420,7 @@ var schema_default = {
1420
1420
  description: "List of locales supported by this game (e.g., ['en', 'es', 'fr'])",
1421
1421
  items: {
1422
1422
  type: "string",
1423
- pattern: "^[a-z]{2}(-[A-Z]{2})?$"
1423
+ pattern: "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$"
1424
1424
  },
1425
1425
  minItems: 1,
1426
1426
  uniqueItems: true
@@ -1429,7 +1429,7 @@ var schema_default = {
1429
1429
  type: "object",
1430
1430
  description: "Localized game fields with one entry per supported locale",
1431
1431
  patternProperties: {
1432
- "^[a-z]{2}(-[A-Z]{2})?$": {
1432
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
1433
1433
  type: "object",
1434
1434
  description: "Localized fields for this locale",
1435
1435
  properties: {
@@ -1496,7 +1496,7 @@ var schema_default = {
1496
1496
  type: "object",
1497
1497
  description: "Localised default name for one team, with one entry per supported locale",
1498
1498
  patternProperties: {
1499
- "^[a-z]{2}(-[A-Z]{2})?$": {
1499
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
1500
1500
  type: "object",
1501
1501
  description: "Localised fields for this locale",
1502
1502
  properties: {
@@ -1625,7 +1625,7 @@ var schema_default = {
1625
1625
  type: "object",
1626
1626
  description: "Localised default name for one team, with one entry per supported locale",
1627
1627
  patternProperties: {
1628
- "^[a-z]{2}(-[A-Z]{2})?$": {
1628
+ "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$": {
1629
1629
  type: "object",
1630
1630
  description: "Localised fields for this locale",
1631
1631
  properties: {
@@ -5109,6 +5109,7 @@ function formatPlatformErrors(body) {
5109
5109
  // cli/utils/llm-client.ts
5110
5110
  var TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
5111
5111
  var STOP_REASONS = ["endTurn", "toolUse", "maxTokens", "refusal"];
5112
+ var CONTENT_BLOCK_TYPES = ["text", "toolUse", "toolResult"];
5112
5113
  var LLM_NOT_CONFIGURED = "LLM_NOT_CONFIGURED";
5113
5114
  var LLMClientError = class extends Error {
5114
5115
  constructor(message, code) {
@@ -5212,12 +5213,12 @@ function translateResponse(parsedBody) {
5212
5213
  if (!Array.isArray(content) || content.length === 0) {
5213
5214
  throw new LLMClientError("Empty response from the platform LLM API");
5214
5215
  }
5215
- if (typeof stopReason !== "string" || !STOP_REASONS.includes(stopReason)) {
5216
+ if (typeof stopReason !== "string") {
5216
5217
  throw new LLMClientError("Unexpected response format from the platform LLM API");
5217
5218
  }
5218
5219
  const response = {
5219
- content,
5220
- stopReason
5220
+ content: content.filter(isKnownContentBlock),
5221
+ stopReason: STOP_REASONS.includes(stopReason) ? stopReason : "endTurn"
5221
5222
  };
5222
5223
  if (usage && typeof usage === "object") {
5223
5224
  const { inputTokens, outputTokens } = usage;
@@ -5227,6 +5228,11 @@ function translateResponse(parsedBody) {
5227
5228
  }
5228
5229
  return response;
5229
5230
  }
5231
+ function isKnownContentBlock(block) {
5232
+ if (block === null || typeof block !== "object") return false;
5233
+ const { type } = block;
5234
+ return typeof type === "string" && CONTENT_BLOCK_TYPES.includes(type);
5235
+ }
5230
5236
 
5231
5237
  // cli/execution/bundle-reload.ts
5232
5238
  import { isDeepStrictEqual as isDeepStrictEqual2 } from "util";
@@ -12644,6 +12650,9 @@ function createStubServices(packagePath) {
12644
12650
  }
12645
12651
 
12646
12652
  // cli/client/test-session.ts
12653
+ function toCommandPaths(paths) {
12654
+ return paths.map((path2) => typeof path2 === "string" ? path2 : [...path2]);
12655
+ }
12647
12656
  async function createTestSession(options) {
12648
12657
  const onPlatform = options.services === "platform";
12649
12658
  const environment = onPlatform ? loadEnvironmentConfig(options.packagePath) : {};
@@ -12706,7 +12715,7 @@ async function createTestSession(options) {
12706
12715
  type: "updateContext",
12707
12716
  teamIndex: index2,
12708
12717
  payload: patch,
12709
- ...writeOptions.deletes === void 0 ? {} : { deletes: writeOptions.deletes }
12718
+ ...writeOptions.deletes === void 0 ? {} : { deletes: toCommandPaths(writeOptions.deletes) }
12710
12719
  };
12711
12720
  if (writeOptions.as === "system") return send2(write);
12712
12721
  return send2({
@@ -12720,7 +12729,7 @@ async function createTestSession(options) {
12720
12729
  setSharedData: (patch, writeOptions = {}) => send2({
12721
12730
  type: "updateSharedContext",
12722
12731
  payload: patch,
12723
- ...writeOptions.deletes === void 0 ? {} : { deletes: writeOptions.deletes },
12732
+ ...writeOptions.deletes === void 0 ? {} : { deletes: toCommandPaths(writeOptions.deletes) },
12724
12733
  ...writeOptions.ui === void 0 ? {} : { uiIdentifier: writeOptions.ui }
12725
12734
  }),
12726
12735
  settled: () => session.settled(),
@@ -7,7 +7,7 @@ Every type, function, hook and component your game imports, one page per entry p
7
7
  | Entry point | Exports |
8
8
  | ---------------------------------------------------------- | -------------------------------------------------------------- |
9
9
  | [`@seriousgaming/sdk`](./sdk.md) | 10 functions, 2 classes, 94 interfaces, 46 types |
10
- | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 44 functions, 3 classes, 37 constants, 18 interfaces, 35 types |
10
+ | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 43 functions, 3 classes, 37 constants, 18 interfaces, 35 types |
11
11
  | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 11 functions, 6 types |
12
12
  | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 4 functions, 4 constants, 7 types |
13
13
  | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
@@ -121,26 +121,6 @@ interface DevServerOptions {
121
121
  }
122
122
  ```
123
123
 
124
- ### SetDataOptions
125
-
126
- ```ts
127
- interface SetDataOptions {
128
- deletes?: DeletePath[];
129
- as?: 'participant' | 'system';
130
- participantId?: string;
131
- ui?: string;
132
- }
133
- ```
134
-
135
- ### SetSharedDataOptions
136
-
137
- ```ts
138
- interface SetSharedDataOptions {
139
- deletes?: DeletePath[];
140
- ui?: string;
141
- }
142
- ```
143
-
144
124
  ### SignatureCallbacks
145
125
 
146
126
  Every callback a runtime may offer logic: the engine, hooks, tick controllers and endpoints.
@@ -226,12 +206,12 @@ interface TestSession<Context = UntypedContext, Shared = UntypedContext> {
226
206
  ): Promise<MutationResult>;
227
207
  setData(
228
208
  team: number,
229
- patch: ContextPatch<Context>,
230
- options?: SetDataOptions
209
+ patch: ContextUpdate<Context>,
210
+ options?: TestSessionSetDataOptions
231
211
  ): Promise<MutationResult>;
232
212
  setSharedData(
233
- patch: ContextPatch<Shared>,
234
- options?: SetSharedDataOptions
213
+ patch: ContextUpdate<Shared>,
214
+ options?: TestSessionSetSharedDataOptions
235
215
  ): Promise<MutationResult>;
236
216
  settled(): Promise<void>;
237
217
  close(): Promise<void>;
@@ -258,6 +238,30 @@ interface TestSessionOptions {
258
238
  }
259
239
  ```
260
240
 
241
+ ### TestSessionSetDataOptions
242
+
243
+ What `TestSession.setData` takes beyond the patch. A surface's `SetDataOptions` carries only `deletes`; a test also says who writes.
244
+
245
+ ```ts
246
+ interface TestSessionSetDataOptions {
247
+ deletes?: ContextDeletePath[];
248
+ as?: 'participant' | 'system';
249
+ participantId?: string;
250
+ ui?: string;
251
+ }
252
+ ```
253
+
254
+ ### TestSessionSetSharedDataOptions
255
+
256
+ What `TestSession.setSharedData` takes beyond the patch.
257
+
258
+ ```ts
259
+ interface TestSessionSetSharedDataOptions {
260
+ deletes?: ContextDeletePath[];
261
+ ui?: string;
262
+ }
263
+ ```
264
+
261
265
  ### TestSessionTeam
262
266
 
263
267
  One team as `TestSession.state` reports it, its context typed.
@@ -276,22 +280,26 @@ interface TestSessionTeam<Context = UntypedContext> extends Omit<ProjectedTeam,
276
280
  type Command = MutationCommand | QueryCommand;
277
281
  ```
278
282
 
279
- ### ContextPatch
283
+ ### ContextDeletePath
280
284
 
281
- A write to some of a context's capabilities, each merged one level deep as a surface's `setData` is: name the variables that change.
285
+ Where to remove a key, as a path from the root of the context.
282
286
 
283
287
  ```ts
284
- type ContextPatch<Context> = {
285
- [K in keyof Context]?: Partial<Context[K]>;
286
- };
288
+ type ContextDeletePath = string | readonly string[];
287
289
  ```
288
290
 
289
- ### DeletePath
291
+ ### ContextUpdate
290
292
 
291
- A path to remove, as a surface's `deletes` names one.
293
+ A partial update accepted by `setData` and merged with `deepMergeContext`. Mirrors the merge semantics at the type level: object values may be given partially (they merge), while arrays and scalars must be given whole (they replace).
292
294
 
293
295
  ```ts
294
- type DeletePath = string | string[];
296
+ type ContextUpdate<T> = {
297
+ [K in keyof T]?: T[K] extends ReadonlyArray<unknown>
298
+ ? T[K]
299
+ : T[K] extends Record<string, unknown>
300
+ ? ContextUpdate<T[K]>
301
+ : T[K];
302
+ };
295
303
  ```
296
304
 
297
305
  ### MutationCommand
@@ -22,12 +22,12 @@ Creates a roster of participants for use in tests — the list returned by `useU
22
22
  function createMockParticipants(count?: number, teamId?: string): Participant[];
23
23
  ```
24
24
 
25
- ### createMockSessionTheme
25
+ ### createMockSessionUserInterfaceTheme
26
26
 
27
27
  Creates a valid SessionUserInterfaceTheme for use in tests.
28
28
 
29
29
  ```ts
30
- function createMockSessionTheme(
30
+ function createMockSessionUserInterfaceTheme(
31
31
  overrides?: Partial<SessionUserInterfaceTheme>
32
32
  ): SessionUserInterfaceTheme;
33
33
  ```
@@ -66,12 +66,12 @@ function createMockTeamState<T extends object = Record<string, unknown>>(
66
66
  ): TeamState<T>;
67
67
  ```
68
68
 
69
- ### createMockTheme
69
+ ### createMockUserInterfaceTheme
70
70
 
71
71
  Creates a valid UserInterfaceTheme for use in tests.
72
72
 
73
73
  ```ts
74
- function createMockTheme(overrides?: Partial<UserInterfaceTheme>): UserInterfaceTheme;
74
+ function createMockUserInterfaceTheme(overrides?: Partial<UserInterfaceTheme>): UserInterfaceTheme;
75
75
  ```
76
76
 
77
77
  ### mergingSetData