@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
@@ -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 } = useUserInterfaceLocale();
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,47 +1,24 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, expect, it } from 'vitest';
2
3
 
3
- import type { Settings, Context } from '../types';
4
+ import { defaultSettings } from '../defaults';
5
+ import type { Context } from '../types';
4
6
  import { UpdateData } from './logic';
5
7
 
6
- const actor = {
7
- role: 'participant',
8
- participant: {
9
- id: 'participant-1',
10
- teamId: 'team-1',
11
- name: 'Ada',
12
- index: 0,
13
- connected: true,
14
- },
15
- } as const;
16
-
17
- const settings: Settings = {
18
- menu: {
19
- Capacity: 120,
20
- Menu: {
21
- lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
22
- icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
23
- cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
24
- },
25
- },
26
- };
27
-
28
8
  const START = { lemonade: 40, icedtea: 20, cookies: 10 };
29
9
 
30
10
  /** `next` is the merged state the write would produce, which is what the host hands a validator. */
31
11
  const verdict = (
32
- made: Partial<Record<string, number>>,
33
- over: { previous?: Partial<Context['plan']['Make']> } = {}
12
+ made: Context['plan']['Make'],
13
+ over: { previous?: Context['plan']['Make'] } = {}
34
14
  ) =>
35
- UpdateData({
36
- participants: [],
37
- previous: { plan: { Make: { ...START, ...over.previous } } },
38
- next: {
39
- plan: { Make: { ...START, ...over.previous, ...made } as Record<string, number> },
40
- },
41
- actor,
42
- settings,
43
- meta: { locale: 'en', seed: 'lemonade-test-seed', runKind: 'session', now: 0 },
44
- });
15
+ UpdateData(
16
+ logicArgs.validator({
17
+ previous: { plan: { Make: { ...START, ...over.previous } } },
18
+ next: { plan: { Make: { ...START, ...over.previous, ...made } } },
19
+ settings: defaultSettings,
20
+ })
21
+ );
45
22
 
46
23
  describe('UpdateData', () => {
47
24
  it('accepts a plan the stall can make', async () => {
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
28
28
  const { locale } = useUserInterfaceLocale();
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
  }
@@ -4,7 +4,7 @@ import {
4
4
  UserInterfaceThemeContext,
5
5
  UserInterfaceDataContext,
6
6
  } from '@seriousgaming/sdk/ui';
7
- import { createMockTheme } from '@seriousgaming/sdk/ui/testing';
7
+ import { createMockUserInterfaceTheme } from '@seriousgaming/sdk/ui/testing';
8
8
  import './i18n';
9
9
  import App from './App';
10
10
 
@@ -12,7 +12,7 @@ import App from './App';
12
12
  // These replace the iframe communication that the real app uses — no mocking needed.
13
13
  const renderApp = (data = {}, settings = {}) =>
14
14
  render(
15
- <UserInterfaceThemeContext.Provider value={createMockTheme()}>
15
+ <UserInterfaceThemeContext.Provider value={createMockUserInterfaceTheme()}>
16
16
  <UserInterfaceDataContext.Provider
17
17
  value={{ data, settings, completedTicks: 0, isRoundProcessing: false, setData: vi.fn() }}
18
18
  >
@@ -1,12 +1,13 @@
1
1
  import React, { useState } from 'react';
2
2
  import {
3
+ Alert,
3
4
  Box,
4
5
  Button,
5
6
  CssBaseline,
6
7
  ThemeProvider,
7
8
  Typography,
8
9
  } from '@mui/material';
9
- import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
10
+ import { useMutationReporter, useUserInterfaceData } from '@seriousgaming/sdk/ui';
10
11
  import { useTranslation } from 'react-i18next';
11
12
  import { Context, Settings } from '../types';
12
13
  import { useAppTheme } from './theme';
@@ -50,11 +51,12 @@ shared state, follow these steps:
50
51
  2. In your ui.sdk.json, add "uicounter" to the `writes` array.
51
52
 
52
53
  3. In this file (App.tsx), uncomment the lines related to `useUserInterfaceData`
53
- to connect the component to the capability.
54
+ and `useMutationReporter` to connect the component to the capability.
54
55
  */
55
56
 
56
57
  function App() {
57
58
  // const { data, setData } = useUserInterfaceData<Context, Settings>();
59
+ // const reporter = useMutationReporter();
58
60
  const { t } = useTranslation();
59
61
  const theme = useAppTheme();
60
62
  const [localCounter, setLocalCounter] = useState(0);
@@ -65,18 +67,20 @@ function App() {
65
67
  const counterValue = localCounter;
66
68
  // const counterValue = data.uicounter.value;
67
69
 
68
- const handleIncrement = () => {
70
+ const handleIncrement = async () => {
69
71
  // This is a local state update example.
70
72
  setLocalCounter((c) => c + 1);
71
73
 
72
- // To send data to the game, uncomment the `setData` call below.
73
- // setData({
74
- // uicounter: {
75
- // // Spread existing capability data to avoid overwriting other variables
76
- // ...(data.uicounter || {}),
77
- // value: (data.uicounter?.value ?? 0) + 1,
78
- // },
79
- // });
74
+ // To send data to the game, replace the line above with the call below.
75
+ // `setData` rejects when the host refuses the write, so await it through
76
+ // the reporter, which keeps the refusal for the notice rendered below.
77
+ // `uicounter` is declared in `writes`, so it is always present: spread
78
+ // it to keep its other variables, with no fallback.
79
+ // await reporter.run(() =>
80
+ // setData({
81
+ // uicounter: { ...data.uicounter, value: data.uicounter.value + 1 },
82
+ // })
83
+ // );
80
84
  };
81
85
 
82
86
  return (
@@ -91,10 +95,17 @@ function App() {
91
95
  {t('currentValue', { value: counterValue })}
92
96
  </Typography>
93
97
  <Box>
98
+ {/* Once connected, add disabled={reporter.pending} while a write is in flight. */}
94
99
  <Button variant="contained" onClick={handleIncrement}>
95
100
  {t('updateButton')}
96
101
  </Button>
97
102
  </Box>
103
+ {/* Uncomment to tell the participant when a write did not land.
104
+ {reporter.failure && (
105
+ <Alert severity="error" onClose={reporter.dismiss}>
106
+ {t('writeFailed')}
107
+ </Alert>
108
+ )} */}
98
109
  </Box>
99
110
  </ThemeProvider>
100
111
  );
@@ -11,6 +11,7 @@ const resources = {
11
11
  "The component below demonstrates reading and writing data to the game's shared state by using a capability.",
12
12
  currentValue: 'Current value: {% raw %}{{value}}{% endraw %}',
13
13
  updateButton: 'Increment Value',
14
+ writeFailed: 'That change did not reach the game. Please try again.',
14
15
  },
15
16
  },
16
17
  it: {
@@ -21,6 +22,7 @@ const resources = {
21
22
  'Il componente sottostante dimostra come leggere e scrivere dati nello stato condiviso della simulazione utilizzando una capability.',
22
23
  currentValue: 'Valore corrente: {% raw %}{{value}}{% endraw %}',
23
24
  updateButton: 'Incrementa valore',
25
+ writeFailed: 'La modifica non ha raggiunto la simulazione. Riprova.',
24
26
  },
25
27
  },
26
28
  ar: {
@@ -31,6 +33,7 @@ const resources = {
31
33
  'يوضح المكون أدناه قراءة البيانات وكتابتها إلى الحالة المشتركة للمحاكاة باستخدام إحدى الإمكانات.',
32
34
  currentValue: 'القيمة الحالية: {% raw %}{{value}}{% endraw %}',
33
35
  updateButton: 'زيادة القيمة',
36
+ writeFailed: 'لم يصل هذا التغيير إلى المحاكاة. يرجى المحاولة مرة أخرى.',
34
37
  },
35
38
  },
36
39
  };
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
28
28
  const { locale } = useUserInterfaceLocale();
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,40 +1,31 @@
1
+ import { logicArgs } from '@seriousgaming/sdk/testing';
1
2
  import { describe, it, expect } from 'vitest';
2
- import { UpdateData } from './logic';
3
- import type { Context, Settings } 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 { UpdateData } from './logic';
10
6
 
11
- // Who submitted the mutation. Swap for `{ role: 'observer', teamId: 'team-1' }`
12
- // to cover a facilitator observing the team on the same surface.
13
- const actor = {
14
- role: 'participant',
15
- participant: {
16
- id: '1',
17
- teamId: 'team-1',
18
- name: 'Participant 1',
19
- index: 0,
20
- connected: true,
21
- },
22
- } as const;
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.validator` fills everything else: `meta` (a fixed locale, seed
12
+ // and clock), a roster of one participant on `team-1`, and that participant
13
+ // as the actor. Pass `actor: { role: 'observer', teamId: 'team-1' }` to cover
14
+ // a facilitator observing the team on the same surface.
23
15
 
24
16
  describe('{{ identifier }}', () => {
25
17
  describe('UpdateData', () => {
26
18
  it('accepts a valid mutation', async () => {
27
- const previous: Context = {
28
- // TODO: Add context values based on required capabilities
29
- } as Context;
30
- const next: Context = {
31
- // TODO: Add proposed next-state values
32
- } as Context;
33
- const settings: Settings = {
34
- // TODO: Add values for the settings resources this reads
35
- } as Settings;
36
-
37
- const result = await UpdateData({ previous, next, actor, settings, meta, participants: [actor.participant] });
19
+ const result = await UpdateData(
20
+ logicArgs.validator({
21
+ // TODO: override the capabilities this case is about
22
+ previous: { ...defaultContext },
23
+ // TODO: add the proposed next-state values
24
+ next: { ...defaultContext },
25
+ // TODO: override the settings this case is about
26
+ settings: { ...defaultSettings },
27
+ })
28
+ );
38
29
 
39
30
  expect(result.ok).toBe(true);
40
31
  });
@@ -7,7 +7,7 @@ import {
7
7
  UserInterfaceParticipantsContext,
8
8
  UserInterfaceThemeContext,
9
9
  } from '@seriousgaming/sdk/ui';
10
- import { createMockTheme } from '@seriousgaming/sdk/ui/testing';
10
+ import { createMockUserInterfaceTheme } from '@seriousgaming/sdk/ui/testing';
11
11
  import './i18n';
12
12
  import App from './App';
13
13
 
@@ -21,7 +21,7 @@ const ROSTER = [
21
21
 
22
22
  const renderApp = (completedTicks = 0) =>
23
23
  render(
24
- <UserInterfaceThemeContext.Provider value={createMockTheme()}>
24
+ <UserInterfaceThemeContext.Provider value={createMockUserInterfaceTheme()}>
25
25
  <UserInterfaceDataContext.Provider
26
26
  value={{ data: {}, settings: {}, completedTicks, isRoundProcessing: false, setData: vi.fn() }}
27
27
  >
@@ -28,11 +28,11 @@ function RootWrapper({ children }: { children: React.ReactNode }) {
28
28
  const { locale } = useUserInterfaceLocale();
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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seriousgaming/sdk-tools",
3
- "version": "1.0.0-alpha.3",
3
+ "version": "1.0.0-alpha.4",
4
4
  "description": "SDK tooling for building Serious Gaming games",
5
5
  "homepage": "https://sdk.seriousgaming.com/",
6
6
  "license": "SEE LICENSE IN LICENSE",
@@ -68,7 +68,7 @@
68
68
  "@mui/icons-material": "^9.4.0",
69
69
  "@mui/material": "^9.4.0",
70
70
  "@playwright/test": "^1.64.0",
71
- "@seriousgaming/sdk": "1.0.0-alpha.3",
71
+ "@seriousgaming/sdk": "1.0.0-alpha.4",
72
72
  "@testing-library/jest-dom": "^7.0.1",
73
73
  "@testing-library/react": "^16.3.3",
74
74
  "@types/adm-zip": "^0.5.8",
@@ -98,7 +98,7 @@
98
98
  "vitest": "^5.0.3"
99
99
  },
100
100
  "peerDependencies": {
101
- "@seriousgaming/sdk": "^1.0.0-alpha.3"
101
+ "@seriousgaming/sdk": "^1.0.0-alpha.4"
102
102
  },
103
103
  "engines": {
104
104
  "node": ">=24"