@seriousgaming/sdk-tools 1.0.0-alpha.2 → 1.0.0-alpha.4

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 (61) 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 +117 -71
  12. package/dist/docs/cli-and-dev-server.md +16 -15
  13. package/dist/docs/cli-reference.md +10 -0
  14. package/dist/docs/concepts/index.md +1 -1
  15. package/dist/docs/concepts/terminology.md +6 -6
  16. package/dist/docs/getting-started.md +4 -2
  17. package/dist/docs/guides/engine-testing.md +1 -1
  18. package/dist/docs/guides/engine.md +13 -0
  19. package/dist/docs/guides/file-handling.md +4 -4
  20. package/dist/docs/guides/internationalization.md +15 -1
  21. package/dist/docs/guides/llm-integration.md +2 -0
  22. package/dist/docs/guides/patterns.md +33 -5
  23. package/dist/docs/guides/presentation.md +9 -9
  24. package/dist/docs/guides/session.md +22 -19
  25. package/dist/docs/guides/testing.md +3 -3
  26. package/dist/docs/guides/tick-controller.md +5 -3
  27. package/dist/docs/guides/ui.md +5 -1
  28. package/dist/docs/guides/upgrading.md +21 -6
  29. package/dist/docs/recipes/create-endpoint.md +1 -1
  30. package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
  31. package/dist/docs/recipes/use-request-tick.md +1 -1
  32. package/dist/docs/troubleshooting.md +6 -4
  33. package/dist/schema.json +6 -6
  34. package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
  35. package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
  36. package/dist/templates/engine/logic.test.ts.liquid +22 -34
  37. package/dist/templates/hook/logic.test.ts.liquid +28 -32
  38. package/dist/templates/package/CLAUDE.md.template +1 -1
  39. package/dist/templates/package/README.md.liquid +3 -3
  40. package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
  41. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
  42. package/dist/templates/package/vitest.config.ts.liquid +18 -2
  43. package/dist/templates/presentation/src/App.tsx.liquid +1 -1
  44. package/dist/templates/session/src/main.tsx.liquid +3 -3
  45. package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
  46. package/dist/templates/starter-game/engine/logic.test.ts +37 -47
  47. package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
  48. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
  49. package/dist/templates/starter-game/session/src/main.tsx +3 -3
  50. package/dist/templates/starter-game/ui/src/main.tsx +3 -3
  51. package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
  52. package/dist/templates/starter-game/vitest.config.ts +18 -2
  53. package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
  54. package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
  55. package/dist/templates/ui/src/App.tsx.liquid +22 -11
  56. package/dist/templates/ui/src/i18n.ts.liquid +3 -0
  57. package/dist/templates/ui/src/main.tsx.liquid +3 -3
  58. package/dist/templates/validator/logic.test.ts.liquid +21 -30
  59. package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
  60. package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
  61. package/package.json +3 -3
@@ -1,58 +1,45 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, it, expect } from 'vitest';
3
+
4
+ import { defaultContext{% if hasSettings %}, defaultSettings{% endif %} } from '../defaults';
5
+ import type { Request } from '../types';
2
6
  import { Handle } from './logic';
3
- import type { Request, Response, Context, Callbacks } from '../types';
4
- import type { EndpointCaller, EndpointSession, {% unless sessionScoped %}TeamInfo, {% endunless %}LogicMeta } from '@seriousgaming/sdk';
5
7
 
6
- // The run-wide facts the host supplies: the session locale, its random seed,
7
- // whether this is the game being played or a walkthrough beside it, and when
8
- // the operation started.
9
- const meta: LogicMeta = { locale: 'en', seed: 'test-seed', runKind: 'session', now: Date.UTC(2026, 0, 1) };
10
- // Where the session stands when the call is made: the ticks it has completed,
11
- // whether the waiting room is open, and every team's standing.
12
- const session: EndpointSession = {
13
- mode: 'independent',
14
- completedTicks: 1,
15
- maxTicks: null,
16
- waitingRoomOpen: false,
17
- complete: false,
18
- teams: [],
19
- };
20
- const callbacks = {} as Callbacks;
21
- const caller: EndpointCaller = {
22
- sessionId: 'test-session',
23
- // A participant's own team; a facilitator's or external call carries none.
24
- teamId: 'team-1',
25
- role: 'participant',
26
- userInterfaceIdentifier: '{{ identifier }}',
27
- };
28
- {% unless sessionScoped %}// The team the call runs for, which the runtime always supplies on team scope.
29
- const team: TeamInfo = { teamId: 'team-1', index: 0, name: 'Team 1' };
30
- {% endunless %}
8
+ {% if hasSettings -%}
9
+ // `defaultContext` and `defaultSettings` are generated beside the types, from
10
+ // the very schemas they satisfy: the values a session opens with. Spread them
11
+ // and name only what the case is about.
12
+ {% else -%}
13
+ // `defaultContext` is generated beside the types, from the very schemas it
14
+ // satisfies: the values a session opens with. Spread it and name only what the
15
+ // case is about. Once the endpoint lists settings resources in `settings`,
16
+ // `defaultSettings` is generated beside it: pass `settings: { ...defaultSettings }`.
17
+ {% endif -%}
18
+ //
19
+ // `logicArgs.endpoint` fills everything else the runtime would supply: `meta`
20
+ // (a fixed locale, seed and clock), the roster, offline callback stubs, a
21
+ // session summary, the caller (a participant on `team-1`, through `ui`) and,
22
+ // on team scope, the team the call runs for. Name any of them to override it,
23
+ // for example `caller: { role: 'facilitator' }`.
24
+
31
25
  describe('{{ identifier }}', () => {
32
26
  describe('Handle', () => {
33
27
  it('returns a valid response', async () => {
34
- const request: Request = {
35
- // TODO: populate request fields from requestSchema
36
- } as Request;
37
- const context: Context = {
38
- // TODO: populate context based on declared reads
39
- } as Context;
40
-
41
- // The settings resources this endpoint lists in `settings`, keyed by
42
- // identifier. Empty until it lists some.
43
- const settings = {} as Parameters<typeof Handle>[0]['settings'];
28
+ // TODO: populate the request fields from requestSchema, then drop the
29
+ // `as Request`, which is only here so the scaffold compiles before then
30
+ const request = {} as Request;
44
31
 
45
- const result = await Handle({
46
- request,
47
- context,
48
- settings,
49
- callbacks,
50
- caller,
51
- {% unless sessionScoped %} team,
52
- {% endunless %} meta,
53
- participants: [],
54
- session,
55
- });
32
+ const result = await Handle(
33
+ logicArgs.endpoint({
34
+ request,
35
+ // TODO: override the capabilities this case is about
36
+ context: { ...defaultContext },
37
+ {%- if hasSettings %}
38
+ // TODO: override the settings this case is about
39
+ settings: { ...defaultSettings },
40
+ {%- endif %}
41
+ })
42
+ );
56
43
 
57
44
  // TODO: assert result matches responseSchema
58
45
  expect(result).toBeDefined();
@@ -1,28 +1,8 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, it, expect } from 'vitest';
2
- import type { Participant, TeamRunMeta } from '@seriousgaming/sdk';
3
+
3
4
  import { defaultSettings, defaultContext, defaultSharedContext, defaultTeamContext } from './defaults';
4
5
  import { Init, InitAggregate, RunAggregate } from './logic';
5
- import type { Context, Settings, Callbacks, TeamContext } from './types';
6
-
7
- // `teamId` and `index` name the team whose context a per-team call receives,
8
- // `seed` is the session's random seed (a fixed one here keeps an assertion on
9
- // derived randomness stable), `runKind` says whether this is the game being
10
- // played or a walkthrough beside it, and `now` is when the operation started
11
- // (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
12
- // real session, so a test has to state them.
13
- const meta: TeamRunMeta = {
14
- tick: 0,
15
- locale: 'en',
16
- teamId: 'team-1',
17
- index: 0,
18
- seed: 'test-seed',
19
- runKind: 'session',
20
- now: Date.UTC(2026, 0, 1),
21
- };
22
- // The participants on the team, taken when the operation started. Empty here;
23
- // add records to test logic that reads the roster.
24
- const participants: Participant[] = [];
25
- const callbacks = {} as Callbacks;
26
6
 
27
7
  // `defaultContext` and `defaultSettings` are generated beside the types, from
28
8
  // the very schemas they satisfy: the values a session opens with. Spread
@@ -31,17 +11,23 @@ const callbacks = {} as Callbacks;
31
11
  // aggregate function receives them split: the shared store once, and each
32
12
  // team's own capabilities, so its fixtures use `defaultSharedContext` and
33
13
  // `defaultTeamContext`.
34
- const shared = { context: { ...defaultSharedContext } };
14
+ //
15
+ // `logicArgs` fills everything else the runtime would supply: `meta` (tick 0
16
+ // for `init` and 1 for the rest, a fixed seed and clock), the roster and
17
+ // offline callback stubs. Name any of them to override it, for example
18
+ // `meta: { tick: 3 }`. A team's `teamId` follows its `index`.
35
19
 
36
20
  describe('{{ identifier }}', () => {
37
21
  describe('Init', () => {
38
22
  it('should initialize each team context', async () => {
39
- // TODO: override the capabilities this case is about
40
- const context: Context = { ...defaultContext };
41
- // TODO: override the settings this case is about
42
- const settings: Settings = { ...defaultSettings };
43
-
44
- const { capabilities } = await Init({ context, settings, meta, participants, callbacks });
23
+ const { capabilities } = await Init(
24
+ logicArgs.init({
25
+ // TODO: override the capabilities this case is about
26
+ context: { ...defaultContext },
27
+ // TODO: override the settings this case is about
28
+ settings: { ...defaultSettings },
29
+ })
30
+ );
45
31
 
46
32
  // TODO: Add assertions for initialized values
47
33
  expect(capabilities).toBeDefined();
@@ -50,41 +36,36 @@ describe('{{ identifier }}', () => {
50
36
 
51
37
  describe('InitAggregate', () => {
52
38
  it('should seed shared state across all teams', async () => {
53
- const teams = [
54
- {
55
- teamId: 'team-1',
56
- index: 0,
39
+ const result = await InitAggregate(
40
+ logicArgs.aggregate({
41
+ shared: { context: { ...defaultSharedContext } },
57
42
  // TODO: override the capabilities this case is about
58
- context: { ...defaultTeamContext } satisfies TeamContext,
59
- },
60
- ];
61
- // TODO: override the settings this case is about
62
- const settings: Settings = { ...defaultSettings };
63
-
64
- const result = await InitAggregate({ shared, teams, settings, meta, participants, callbacks });
43
+ teams: [{ index: 0, context: { ...defaultTeamContext } }],
44
+ // TODO: override the settings this case is about
45
+ settings: { ...defaultSettings },
46
+ meta: { tick: 0 },
47
+ })
48
+ );
65
49
 
66
50
  // TODO: Add assertions for shared and per-team values
67
- expect(result.teams).toHaveLength(teams.length);
51
+ expect(result.teams).toHaveLength(1);
68
52
  });
69
53
  });
70
54
 
71
55
  describe('RunAggregate', () => {
72
56
  it('should update shared state on each tick', async () => {
73
- const teams = [
74
- {
75
- teamId: 'team-1',
76
- index: 0,
57
+ const result = await RunAggregate(
58
+ logicArgs.aggregate({
59
+ shared: { context: { ...defaultSharedContext } },
77
60
  // TODO: override the capabilities this case is about
78
- context: { ...defaultTeamContext } satisfies TeamContext,
79
- },
80
- ];
81
- // TODO: override the settings this case is about
82
- const settings: Settings = { ...defaultSettings };
83
-
84
- const result = await RunAggregate({ shared, teams, settings, meta, participants, callbacks });
61
+ teams: [{ index: 0, context: { ...defaultTeamContext } }],
62
+ // TODO: override the settings this case is about
63
+ settings: { ...defaultSettings },
64
+ })
65
+ );
85
66
 
86
67
  // TODO: Add assertions for shared and per-team values
87
- expect(result.teams).toHaveLength(teams.length);
68
+ expect(result.teams).toHaveLength(1);
88
69
  });
89
70
  });
90
71
  });
@@ -1,44 +1,30 @@
1
- import type { Participant, TeamRunMeta } from '@seriousgaming/sdk';
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
2
2
  import { describe, it, expect } from 'vitest';
3
3
 
4
4
  import { defaultSettings, defaultContext } from './defaults';
5
5
  import { Init, Run } from './logic';
6
- import type { Context, Settings, Callbacks } from './types';
7
-
8
- // `teamId` and `index` name the team whose context a per-team call receives,
9
- // `seed` is the session's random seed (a fixed one here keeps an assertion on
10
- // derived randomness stable), `runKind` says whether this is the game being
11
- // played or a walkthrough beside it, and `now` is when the operation started
12
- // (fixed here, as `seed` is, so a test asserting on it is stable). All of them come from the runtime in a
13
- // real session, so a test has to state them.
14
- const meta: TeamRunMeta = {
15
- tick: 0,
16
- locale: 'en',
17
- teamId: 'team-1',
18
- index: 0,
19
- seed: 'test-seed',
20
- runKind: 'session',
21
- now: Date.UTC(2026, 0, 1),
22
- };
23
- // The participants on the team, taken when the operation started. Empty here;
24
- // add records to test logic that reads the roster.
25
- const participants: Participant[] = [];
26
- const callbacks = {} as Callbacks;
27
6
 
28
7
  // `defaultContext` and `defaultSettings` are generated beside the types, from
29
8
  // the very schemas they satisfy: the values a session opens with. Spread
30
9
  // them and name only what the case is about, and a capability added later
31
10
  // arrives here already populated rather than breaking every fixture.
11
+ //
12
+ // `logicArgs` fills everything else the runtime would supply: `meta` (tick 0
13
+ // for `init` and 1 for `run`, team `team-1`, a fixed seed and clock), the
14
+ // roster and offline callback stubs. Name any of them to override it, for
15
+ // example `meta: { tick: 3 }`.
32
16
 
33
17
  describe('{{ identifier }}', () => {
34
18
  describe('Init', () => {
35
19
  it('should initialize context variables', async () => {
36
- // TODO: override the capabilities this case is about
37
- const context: Context = { ...defaultContext };
38
- // TODO: override the settings this case is about
39
- const settings: Settings = { ...defaultSettings };
40
-
41
- const { capabilities } = await Init({ context, settings, meta, participants, callbacks });
20
+ const { capabilities } = await Init(
21
+ logicArgs.init({
22
+ // TODO: override the capabilities this case is about
23
+ context: { ...defaultContext },
24
+ // TODO: override the settings this case is about
25
+ settings: { ...defaultSettings },
26
+ })
27
+ );
42
28
 
43
29
  // TODO: Add assertions for initialized values
44
30
  expect(capabilities).toBeDefined();
@@ -47,12 +33,14 @@ describe('{{ identifier }}', () => {
47
33
 
48
34
  describe('Run', () => {
49
35
  it('should update context on each tick', async () => {
50
- // TODO: override the capabilities this case is about
51
- const context: Context = { ...defaultContext };
52
- // TODO: override the settings this case is about
53
- const settings: Settings = { ...defaultSettings };
54
-
55
- const { capabilities } = await Run({ context, settings, meta, participants, callbacks });
36
+ const { capabilities } = await Run(
37
+ logicArgs.run({
38
+ // TODO: override the capabilities this case is about
39
+ context: { ...defaultContext },
40
+ // TODO: override the settings this case is about
41
+ settings: { ...defaultSettings },
42
+ })
43
+ );
56
44
 
57
45
  // TODO: Add assertions for updated values
58
46
  expect(capabilities).toBeDefined();
@@ -1,43 +1,39 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, it, expect } from 'vitest';
2
- import { Run } from './logic';
3
- import type { Context, Settings, Callbacks } from '../types';
4
- import type { LogicMeta } from '@seriousgaming/sdk';
5
3
 
6
- // The run-wide facts the host supplies: the session locale, its random seed,
7
- // whether this is the game being played or a walkthrough beside it, and when
8
- // the operation started.
9
- const meta: LogicMeta = { locale: 'en', seed: 'test-seed', runKind: 'session', now: Date.UTC(2026, 0, 1) };
4
+ import { defaultContext, defaultSettings } from '../defaults';
5
+ import { Run } from './logic';
10
6
 
11
- const callbacks = {} as Callbacks;
7
+ // `defaultContext` and `defaultSettings` are generated beside the types, from
8
+ // the very schemas they satisfy: the values a session opens with. Spread them
9
+ // and name only what the case is about.
10
+ //
11
+ // `logicArgs.hook` takes the signal's payload and fills the rest the runtime
12
+ // would supply: `meta` (a fixed locale, seed and clock), the roster (the
13
+ // participant the signal concerns) and offline callback stubs.
12
14
 
13
- // The participant the signal concerns, and the roster the hook receives.
14
- const participant = {
15
- id: '1',
16
- teamId: 'team-1',
17
- name: 'Participant 1',
18
- index: 0,
19
- connected: true,
20
- };
15
+ // The participant the signal concerns.
16
+ const participant = { id: '1', teamId: 'team-1', name: 'Participant 1', index: 0, connected: true };
21
17
 
22
18
  describe('{{ identifier }}', () => {
23
19
  describe('Run', () => {
24
20
  it('should update context in response to the signal', async () => {
25
- const context: Context = {
26
- // TODO: Add context values based on required/provided capabilities
27
- } as Context;
28
- const settings: Settings = {
29
- // TODO: Add values for the settings resources this reads
30
- } as Settings;
31
-
32
- // TODO: replace with the payload fields the hook's signal supplies
33
- const { capabilities } = await Run({
34
- context,
35
- settings,
36
- callbacks,
37
- meta,
38
- participant,
39
- participants: [participant],
40
- } as Parameters<typeof Run>[0]);
21
+ const { capabilities } = await Run(
22
+ logicArgs.hook({
23
+ signal: '{{ signal }}',
24
+ // TODO: override the capabilities this case is about
25
+ context: { ...defaultContext },
26
+ // TODO: override the settings this case is about
27
+ settings: { ...defaultSettings },
28
+ participant,
29
+ {%- if signal == 'participantMove' %}
30
+ fromTeamId: 'team-2',
31
+ toTeamId: 'team-1',
32
+ // Which team's context this call owns: 'departure' for the team left
33
+ phase: 'arrival',
34
+ {%- endif %}
35
+ })
36
+ );
41
37
 
42
38
  // TODO: Add assertions for updated values
43
39
  expect(capabilities).toBeDefined();
@@ -139,7 +139,7 @@ pnpm run sdk new capability '{...}' # likewise hook, validator, endpoint,
139
139
  pnpm run sdk new setup '{...}' # an empty slot: setup, scenario_editor, presentation, tick_controller
140
140
  pnpm run sdk update engine --patch '[{"op":"add","path":"/definition/writes/-","value":"results"}]'
141
141
  pnpm run sdk update capability plan '{...}' # full replacement
142
- pnpm run sdk update package --patch '[{"op":"replace","path":"/ticks","value":12}]'
142
+ pnpm run sdk update package --patch '[{"op":"replace","path":"/maxTicks","value":12}]'
143
143
  pnpm run sdk delete capability plan --yes
144
144
  pnpm run generate # regenerate types after a hand edit (new and update already do)
145
145
  pnpm run build # validate, generate and bundle into dist/
@@ -39,9 +39,9 @@ them in. Press the backtick key on any page for the dev drawer: tick, undo, and
39
39
  reset controls, and the state as JSON.
40
40
 
41
41
  Edits to logic, UIs, `*.sdk.json` bundles and `seriousgaming.sdk.json` reach
42
- the running game without a restart. A settings change, which reaches the game
43
- through `Init`, waits for you to re-initialise once a round has been played:
44
- the console says so and offers a button.
42
+ the running game without a restart. A settings change is the exception once a
43
+ round has been played: settings are fixed when play starts, so it waits for you
44
+ to re-initialise. The console says so and offers a button.
45
45
 
46
46
  ### Drive it from the CLI
47
47
 
@@ -13,7 +13,7 @@ Capabilities are the data definitions the engine and UIs read from and write to.
13
13
  ```bash
14
14
  pnpm run --silent sdk docs view recipes/create-capability.md
15
15
  ```
16
- 2. **Create the capability** with `pnpm run sdk new capability '{ ... }'`. `definition.identifier` is a short lowercase name (`sales`), which becomes the directory `capabilities/sales/` and the key `context.sales`. The `variablesSchema` must be a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`), not a properties-only object. Set `scope` (`team` by default, or `team-readable`, `shared`, `private`) if the capability is not private to each team.
16
+ 2. **Create the capability** with `pnpm run sdk new capability '{ ... }'`. `definition.identifier` is a short lowercase name (`sales`), which becomes the directory `capabilities/sales/` and the key `context.sales`. The `variablesSchema` must be a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`), not a properties-only object. `scope` says who sees the value. Leave it out for the default, `team`: one value per team, shown on that team's screens. Set `team-readable` to let other teams' screens observe it too, `shared` for one value across the whole session, or `private` for per-team engine bookkeeping that no screen ever receives. Set `lifetime: "session"` for a value that undo and reset must leave alone, such as a facilitator's announcement; the engine cannot read or write one (see `pnpm run --silent sdk docs view guides/capabilities.md`, 'Lifetime').
17
17
  3. **Declare it** in the `reads` or `writes` of every resource that uses it (`pnpm run sdk update engine --patch '[...]'`, and so on). A resource is handed only the capabilities it declares.
18
18
  4. **Verify**: `pnpm run build` should pass without type errors. `new` and `update` regenerate types; run `pnpm run generate` yourself only after editing a bundle by hand.
19
19
 
@@ -16,7 +16,7 @@ Endpoints are named, server-side handlers that user interfaces (and, when its `v
16
16
  2. **Decide the request and response shapes.** Each is a full JSON Schema 7 object (`type: 'object'` + `properties` + `required` + `additionalProperties: false`).
17
17
  3. **Decide what it touches**: which capabilities it `reads`, which it `writes` (if any), which settings resources it reads (`settings`), which runtime callbacks it `uses` (`generateText`, `extractText`, `generateSpeech`, `writeBlob`), which session `actions` it may return (such as advancing a tick or closing the waiting room), whether its `session` argument needs each team's participants (`roster: true`), and its `scope`: `team` (the default: it acts on the calling team's board) or `session` (for a session UI, setup screen, or scenario editor, which has no team of its own).
18
18
  4. **Create the endpoint** with `pnpm run sdk new endpoint '{ ... }'`, declaring `identifier`, `requestSchema`, `responseSchema`, and whichever of `reads`, `writes`, `settings`, `uses`, `actions`, `roster`, `scope`, `visibility`, and `description` apply. An outside caller, such as an AI agent, reads `description` to decide whether to call an external endpoint, so write it for that reader. An external endpoint's `requestSchema` must be `"type": "object"` at the top (`EXTERNAL_REQUEST_NOT_OBJECT`); one taking no input declares an object with no properties.
19
- 5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
19
+ 5. **Implement `Handle`** in `endpoints/<name>/logic/logic.ts`. It takes `{ request, context, callbacks, caller, settings, meta, participants, session }`, plus `team` (`{ teamId, index, name }`) on a team-scoped endpoint, which is how it identifies its own team, or `teams` (every team's values) on a session-scoped endpoint that declares a capability that is not shared. Without `writes` or `actions` it returns the response alone; otherwise it returns `{ response, capabilities, actions }`, where `capabilities` holds only the capabilities it changed and `actions` only those it declared. To remove a key (one entry of a map), add `deletes: [['orders', 'Open', id]]` beside `capabilities`; each path must sit under a capability in `writes`. The generated `Handler` type switches shape to match, so the compiler tells you which one you owe. An endpoint whose response must describe the state its effects leave (for example the tick it just advanced) exports `Plan` and `Respond` instead of `Handle`, typed with the generated `Planner` and `Responder`: `Plan` returns the effects alone, and `Respond` receives `plan` and `outcomes` after they have landed and returns the response.
20
20
  6. **Allow the UI to call it.** Add the endpoint identifier to the `endpoints` array in the bundle of every UI that should be permitted to call it (`pnpm run sdk update ui --patch '[...]'`). Without this, the host rejects the call and TypeScript flags it. The UI then calls `callbacks.endpoints['<name>'](request)`.
21
21
  7. **Add a unit test** in the scaffolded `endpoints/<name>/logic/logic.test.ts` covering the happy path and any branch in `Handle`.
22
22
  8. **Verify**: `pnpm run sdk endpoint list` shows its scope and whether it writes; `pnpm run --silent sdk endpoint call <name> --no-server --team 1 --request '{...}'` runs it without a UI; then `pnpm run build` and `pnpm test:run`.
@@ -17,9 +17,25 @@ export default defineConfig({
17
17
  jsx: 'automatic',
18
18
  },
19
19
  test: {
20
- environment: 'jsdom',
21
- setupFiles: ['./test-setup.ts'],
22
20
  // Exclude engine tests (node env, separate config) and Playwright specs
23
21
  exclude: ['testing/**', '**/node_modules/**'],
22
+ // Logic tests need no DOM, and building one per file is most of what
23
+ // they cost. A test that renders, `renderHook` included, is a .tsx.
24
+ projects: [
25
+ {
26
+ extends: true,
27
+ test: { name: 'logic', include: ['**/*.test.ts'], environment: 'node' },
28
+ },
29
+ {
30
+ extends: true,
31
+ test: {
32
+ name: 'components',
33
+ include: ['**/*.test.tsx'],
34
+ environment: 'jsdom',
35
+ pool: 'vmThreads',
36
+ setupFiles: ['./test-setup.ts'],
37
+ },
38
+ },
39
+ ],
24
40
  },
25
41
  });
@@ -19,7 +19,7 @@ pick up the same primary and secondary as every other surface.
19
19
  export default function App() {
20
20
  const { game, session, theme, locale } = usePresentation<Settings, TeamContext, SharedContext>();
21
21
  const { t, i18n } = useTranslation();
22
- const language = locale.locale.split('-')[0];
22
+ const language = locale.locale;
23
23
 
24
24
  useEffect(() => {
25
25
  void i18n.changeLanguage(language);
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
28
28
  const { locale } = useSessionUserInterfaceLocale();
29
29
 
30
30
  useEffect(() => {
31
- const i18nextLocale = locale.split('-')[0];
32
- i18n.changeLanguage(i18nextLocale);
31
+ // The whole tag, so i18next falls back through it: zh-Hant-TW, zh-Hant, zh.
32
+ i18n.changeLanguage(locale);
33
33
  }, [locale]);
34
34
 
35
- const isRtl = i18n.dir(locale.split('-')[0]) === 'rtl';
35
+ const isRtl = i18n.dir(locale) === 'rtl';
36
36
 
37
37
  return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
38
38
  }
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
28
28
  const { locale } = useSettingsEditorLocale();
29
29
 
30
30
  useEffect(() => {
31
- const i18nextLocale = locale.split('-')[0];
32
- i18n.changeLanguage(i18nextLocale);
31
+ // The whole tag, so i18next falls back through it: zh-Hant-TW, zh-Hant, zh.
32
+ i18n.changeLanguage(locale);
33
33
  }, [locale]);
34
34
 
35
- const isRtl = i18n.dir(locale.split('-')[0]) === 'rtl';
35
+ const isRtl = i18n.dir(locale) === 'rtl';
36
36
 
37
37
  return <CacheProvider value={isRtl ? cacheRtl : cacheLtr}>{children}</CacheProvider>;
38
38
  }
@@ -1,30 +1,22 @@
1
+ import type { TeamRunMeta } from '@seriousgaming/sdk';
2
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
3
  import { describe, expect, it } from 'vitest';
2
4
 
5
+ import { defaultSettings } from './defaults';
3
6
  import { Init, Run } from './logic';
4
- import { baseSettings, baseContext, baseMeta, callbacks } from './test-helpers';
7
+ import { baseContext } from './test-helpers';
5
8
  import type { Context } from './types';
6
9
 
7
- const init = async (over: Partial<typeof baseMeta> = {}) =>
8
- (
9
- await Init({
10
- participants: [],
11
- context: baseContext,
12
- settings: baseSettings,
13
- meta: { ...baseMeta, ...over },
14
- callbacks,
15
- })
16
- ).capabilities;
17
-
18
- const run = async (context: Context, day = 1, over: Partial<typeof baseMeta> = {}) =>
19
- (
20
- await Run({
21
- participants: [],
22
- context,
23
- settings: baseSettings,
24
- meta: { ...baseMeta, tick: day, ...over },
25
- callbacks,
26
- })
27
- ).capabilities;
10
+ // The seed is fixed (`logicArgs` supplies one), so the weather and the day's
11
+ // custom are the same every run: this game derives both from it rather than
12
+ // drawing them, which is what makes a test like this possible at all.
13
+ const init = async (meta: Partial<TeamRunMeta> = {}) =>
14
+ (await Init(logicArgs.init({ context: baseContext, settings: defaultSettings, meta })))
15
+ .capabilities;
16
+
17
+ const run = async (context: Context, day = 1, meta: Partial<TeamRunMeta> = {}) =>
18
+ (await Run(logicArgs.run({ context, settings: defaultSettings, meta: { tick: day, ...meta } })))
19
+ .capabilities;
28
20
 
29
21
  const makeAll = (context: Context, counts: Record<string, number>): Context => ({
30
22
  ...context,
@@ -43,22 +35,21 @@ describe('Init', () => {
43
35
  it('expects nobody for an item the demand settings say nothing about', async () => {
44
36
  // A scenario can add to the menu without touching the engine's
45
37
  // settings. The new item still gets a line, just an empty one.
46
- const { capabilities: result } = await Init({
47
- participants: [],
48
- context: baseContext,
49
- settings: {
50
- ...baseSettings,
51
- menu: {
52
- ...baseSettings.menu,
53
- Menu: {
54
- ...baseSettings.menu.Menu,
55
- flapjack: { Name: 'Flapjack', Order: 4, Cost: 20, Price: 80 },
38
+ const { capabilities: result } = await Init(
39
+ logicArgs.init({
40
+ context: baseContext,
41
+ settings: {
42
+ ...defaultSettings,
43
+ menu: {
44
+ ...defaultSettings.menu,
45
+ Menu: {
46
+ ...defaultSettings.menu.Menu,
47
+ flapjack: { Name: 'Flapjack', Order: 4, Cost: 20, Price: 80 },
48
+ },
56
49
  },
57
50
  },
58
- },
59
- meta: baseMeta,
60
- callbacks,
61
- });
51
+ })
52
+ );
62
53
 
63
54
  expect(result.plan.Make.flapjack).toBe(0);
64
55
  expect(result.weather.Expected.flapjack).toBe(0);
@@ -98,16 +89,15 @@ describe('Init', () => {
98
89
  });
99
90
 
100
91
  it('clears everything a previous session left behind', async () => {
101
- const { capabilities: result } = await Init({
102
- participants: [],
103
- context: {
104
- ...baseContext,
105
- results: { ...baseContext.results, Purse: 9999, Day: 7 },
106
- },
107
- settings: baseSettings,
108
- meta: baseMeta,
109
- callbacks,
110
- });
92
+ const { capabilities: result } = await Init(
93
+ logicArgs.init({
94
+ context: {
95
+ ...baseContext,
96
+ results: { ...baseContext.results, Purse: 9999, Day: 7 },
97
+ },
98
+ settings: defaultSettings,
99
+ })
100
+ );
111
101
 
112
102
  expect(result.results.Purse).toBe(0);
113
103
  expect(result.results.Day).toBe(0);
@@ -153,7 +143,7 @@ describe('Run', () => {
153
143
  it('takes the sale price for every cup it sells', async () => {
154
144
  const result = await run(baseContext);
155
145
  const expected = Object.entries(result.results.Lines).reduce(
156
- (total, [id, line]) => total + line.Sold * baseSettings.menu.Menu[id]!.Price,
146
+ (total, [id, line]) => total + line.Sold * defaultSettings.menu.Menu[id]!.Price,
157
147
  0
158
148
  );
159
149