@seriousgaming/sdk-tools 1.0.0-alpha.3 → 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 (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 +116 -73
  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 +17 -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
@@ -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`.
@@ -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
 
@@ -1,74 +1,22 @@
1
- import type { TeamRunMeta } from '@seriousgaming/sdk';
2
-
3
- import type { Context, Settings } from './types';
1
+ import { defaultContext } from './defaults';
2
+ import type { Context } from './types';
4
3
 
5
4
  /**
6
- * Starting fixtures for the engine's tests.
5
+ * The context the engine's tests start from.
7
6
  *
8
- * A test spreads what it cares about over these rather than restating the whole
7
+ * A test spreads what it cares about over this rather than restating the whole
9
8
  * context, so adding a field to a capability does not break every test that was
10
- * never about that field.
9
+ * never about that field. It starts from the generated defaults and names only
10
+ * what this suite deliberately runs on instead: a plan with something on it and
11
+ * an ordinary, cloudy forecast.
12
+ *
13
+ * Settings need no fixture of their own: the tests pass the generated
14
+ * `defaultSettings`, and `meta`, the roster and the callbacks are `logicArgs`'s
15
+ * to fill (`@seriousgaming/sdk/testing`).
11
16
  */
12
- export const baseSettings: Settings = {
13
- menu: {
14
- Capacity: 120,
15
- Menu: {
16
- lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
17
- icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
18
- cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
19
- },
20
- },
21
- engine: {
22
- UsualDemand: { lemonade: 55, icedtea: 30, cookies: 20 },
23
- SunnyPull: 1.3,
24
- RainyPull: 0.65,
25
- Variation: 0.2,
26
- },
27
- };
28
-
29
17
  export const baseContext: Context = {
18
+ ...defaultContext,
30
19
  plan: { Make: { lemonade: 28, icedtea: 15, cookies: 10 } },
31
20
  weather: { Today: 'cloudy', Expected: { lemonade: 55, icedtea: 30, cookies: 20 } },
32
- results: {
33
- Day: 0,
34
- Weather: 'cloudy',
35
- Lines: {},
36
- Takings: 0,
37
- Spent: 0,
38
- Profit: 0,
39
- Purse: 0,
40
- },
41
- };
42
-
43
- /**
44
- * The `meta` the runtime supplies. `seed` is fixed, so the weather and the
45
- * day's custom are the same every run: this game derives both from it rather
46
- * than drawing them, which is what makes a test like this possible at all.
47
- */
48
- export const baseMeta: TeamRunMeta = {
49
- tick: 1,
50
- locale: 'en',
51
- teamId: 'team-1',
52
- index: 0,
53
- seed: 'lemonade-test-seed',
54
- runKind: 'session',
55
- now: 0,
56
- };
57
-
58
- /**
59
- * The engine declares no `uses`, so every gated callback throws rather than
60
- * returning a benign value: a call that reaches one is a declaration bug, and a
61
- * test that quietly passes hides it.
62
- *
63
- * The ungated ones are a different case. They need no declaration, so reaching
64
- * one is legitimate, and they answer as a session with nothing in it would.
65
- */
66
- export const callbacks = {
67
- generateText: async () => {
68
- throw new Error('generateText is not declared by this engine');
69
- },
70
- readAsset: async () => {
71
- throw new Error('readAsset reached, but this engine references no assets');
72
- },
73
- getPastState: async () => [],
21
+ results: { ...defaultContext.results, Weather: 'cloudy' },
74
22
  };
@@ -1,38 +1,32 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, expect, it } from 'vitest';
2
3
 
3
- import type { Callbacks, Settings, Context } from '../types';
4
+ import { defaultContext, defaultSettings } from '../defaults';
5
+ import type { Settings, Context } from '../types';
4
6
  import { Run } from './logic';
5
7
 
6
- const callbacks = {} as Callbacks;
7
- const settings: Settings = {
8
- menu: {
9
- Capacity: 120,
10
- Menu: {
11
- lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
12
- icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
13
- cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
14
- },
15
- },
16
- };
8
+ const empty: Context = { ...defaultContext, roles: { LooksAfter: {} } };
17
9
 
18
- const empty: Context = { roles: { LooksAfter: {} } };
19
-
20
- const join = async (context: Context, id: string, index: number, over: Settings = settings) =>
10
+ const join = async (
11
+ context: Context,
12
+ id: string,
13
+ index: number,
14
+ settings: Settings = defaultSettings
15
+ ) =>
21
16
  (
22
- await Run({
23
- participants: [],
24
- context,
25
- settings: over,
26
- callbacks,
27
- meta: { locale: 'en', seed: 'lemonade-test-seed', runKind: 'session', now: 0 },
28
- participant: {
29
- id,
30
- teamId: 'team-1',
31
- name: `Participant ${index + 1}`,
32
- index,
33
- connected: true,
34
- },
35
- })
17
+ await Run(
18
+ logicArgs.hook({
19
+ context,
20
+ settings,
21
+ participant: {
22
+ id,
23
+ teamId: 'team-1',
24
+ name: `Participant ${index + 1}`,
25
+ index,
26
+ connected: true,
27
+ },
28
+ })
29
+ )
36
30
  ).capabilities;
37
31
 
38
32
  describe('Run', () => {
@@ -69,7 +63,7 @@ describe('Run', () => {
69
63
 
70
64
  it('does nothing when the menu is empty', async () => {
71
65
  const result = await join(empty, 'participant-1', 0, {
72
- menu: { ...settings.menu, Menu: {} },
66
+ menu: { ...defaultSettings.menu, Menu: {} },
73
67
  });
74
68
 
75
69
  expect(result.roles.LooksAfter).toEqual({});