@seriousgaming/sdk-tools 1.0.0 → 1.2.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 (167) hide show
  1. package/README.md +4 -4
  2. package/dist/brands/awkward/brand.json +16 -0
  3. package/dist/brands/awkward/logo-on-light.svg +4 -0
  4. package/dist/brands/serious-gaming/brand.json +42 -0
  5. package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
  6. package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
  7. package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
  8. package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
  9. package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
  10. package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
  11. package/dist/brands/serious-gaming/icon.svg +24 -0
  12. package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
  13. package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
  14. package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
  15. package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
  16. package/dist/cli.js +20161 -5495
  17. package/dist/client.js +15737 -1151
  18. package/dist/core/save-scenario.d.ts +25 -0
  19. package/dist/core/session-endpoints.d.ts +12 -13
  20. package/dist/core/session-host.d.ts +9 -1
  21. package/dist/core/session-writes.d.ts +2 -2
  22. package/dist/core/session.d.ts +9 -1
  23. package/dist/dev/brand-summary.d.ts +16 -0
  24. package/dist/dev/brands.d.ts +230 -0
  25. package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
  26. package/dist/dev/console/assets/index-BNLEVOQA.js +204 -0
  27. package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
  28. package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
  29. package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
  30. package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
  31. package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
  32. package/dist/dev/console/index.html +3 -1
  33. package/dist/dev/routes.d.ts +9 -0
  34. package/dist/dev/shell.d.ts +14 -0
  35. package/dist/dev/view/batch.d.ts +0 -2
  36. package/dist/docs/ai-agents.md +75 -0
  37. package/dist/docs/api/deck.md +38 -0
  38. package/dist/docs/api/index.md +5 -5
  39. package/dist/docs/api/sdk-commands.md +1 -1
  40. package/dist/docs/api/sdk-e2e.md +1 -0
  41. package/dist/docs/api/sdk-projection.md +1 -0
  42. package/dist/docs/api/sdk-testing.md +52 -1
  43. package/dist/docs/api/sdk-tools-client.md +1 -0
  44. package/dist/docs/api/sdk-ui-testing.md +30 -4
  45. package/dist/docs/api/sdk-ui.md +185 -0
  46. package/dist/docs/api/sdk.md +70 -4
  47. package/dist/docs/changelog.md +85 -4
  48. package/dist/docs/cli-and-dev-server.md +2 -0
  49. package/dist/docs/cli-error-codes.md +65 -59
  50. package/dist/docs/cli-reference.md +84 -45
  51. package/dist/docs/concepts/index.md +74 -6
  52. package/dist/docs/concepts/terminology.md +17 -11
  53. package/dist/docs/getting-started.md +30 -11
  54. package/dist/docs/guides/ai-facilitation.md +5 -1
  55. package/dist/docs/guides/capabilities.md +3 -1
  56. package/dist/docs/guides/designing-a-game.md +85 -0
  57. package/dist/docs/guides/endpoints.md +57 -13
  58. package/dist/docs/guides/engine-testing.md +4 -13
  59. package/dist/docs/guides/engine.md +14 -2
  60. package/dist/docs/guides/file-handling.md +14 -10
  61. package/dist/docs/guides/games.md +2 -8
  62. package/dist/docs/guides/guide.md +98 -6
  63. package/dist/docs/guides/index.md +3 -4
  64. package/dist/docs/guides/internationalization.md +8 -14
  65. package/dist/docs/guides/llm-integration.md +19 -31
  66. package/dist/docs/guides/multi-team-games.md +9 -14
  67. package/dist/docs/guides/patterns.md +0 -6
  68. package/dist/docs/guides/presentation.md +6 -10
  69. package/dist/docs/guides/production-constraints.md +3 -10
  70. package/dist/docs/guides/scenario-editor.md +11 -11
  71. package/dist/docs/guides/scenarios.md +26 -14
  72. package/dist/docs/guides/session.md +32 -36
  73. package/dist/docs/guides/settings.md +28 -2
  74. package/dist/docs/guides/setup.md +2 -7
  75. package/dist/docs/guides/speech-generation.md +8 -17
  76. package/dist/docs/guides/starter-game.md +2 -1
  77. package/dist/docs/guides/testing.md +45 -43
  78. package/dist/docs/guides/theming-and-branding.md +208 -0
  79. package/dist/docs/guides/tick-controller.md +8 -4
  80. package/dist/docs/guides/type-safety.md +8 -6
  81. package/dist/docs/guides/ui.md +41 -62
  82. package/dist/docs/guides/upgrading.md +13 -3
  83. package/dist/docs/guides/validators.md +64 -3
  84. package/dist/docs/guides/waiting-room.md +3 -10
  85. package/dist/docs/index.md +40 -10
  86. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  87. package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
  88. package/dist/docs/recipes/create-capability.md +1 -1
  89. package/dist/docs/recipes/create-endpoint.md +7 -2
  90. package/dist/docs/recipes/create-engine.md +1 -1
  91. package/dist/docs/recipes/create-guide.md +4 -4
  92. package/dist/docs/recipes/create-hook.md +1 -1
  93. package/dist/docs/recipes/create-session-ui.md +1 -1
  94. package/dist/docs/recipes/create-settings.md +1 -1
  95. package/dist/docs/recipes/create-tick-controller.md +1 -1
  96. package/dist/docs/recipes/create-user-interface.md +1 -1
  97. package/dist/docs/recipes/create-validator.md +1 -1
  98. package/dist/docs/recipes/declare-api-uses.md +2 -2
  99. package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
  100. package/dist/docs/recipes/distribute-package.md +3 -3
  101. package/dist/docs/recipes/e2e-testing.md +11 -9
  102. package/dist/docs/recipes/index.md +6 -2
  103. package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
  104. package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
  105. package/dist/docs/recipes/publish-a-package.md +1 -1
  106. package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
  107. package/dist/docs/recipes/review-a-past-day.md +4 -2
  108. package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
  109. package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
  110. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  111. package/dist/docs/recipes/test-user-interface.md +13 -2
  112. package/dist/docs/recipes/validate-scenarios.md +91 -0
  113. package/dist/docs/troubleshooting.md +44 -2
  114. package/dist/execution/blob-inputs.d.ts +7 -2
  115. package/dist/execution/config-resolver.d.ts +10 -0
  116. package/dist/execution/endpoint-runner.d.ts +8 -1
  117. package/dist/execution/executor-callbacks.d.ts +7 -0
  118. package/dist/execution/executor.d.ts +11 -0
  119. package/dist/execution/logic-calls.d.ts +8 -1
  120. package/dist/execution/scenario-gates.d.ts +34 -0
  121. package/dist/guide/effective-guide.d.ts +20 -0
  122. package/dist/guide/locale.d.ts +12 -0
  123. package/dist/guide/settings.d.ts +74 -0
  124. package/dist/guide/video-registry.d.ts +33 -1
  125. package/dist/host/host-channel.d.ts +11 -2
  126. package/dist/host/index.d.ts +9 -1
  127. package/dist/host/protocol.d.ts +49 -5
  128. package/dist/host/theme.d.ts +28 -2
  129. package/dist/host.js +11621 -15
  130. package/dist/runtime/index.d.ts +1 -1
  131. package/dist/runtime/manifest-version.d.ts +17 -0
  132. package/dist/runtime.js +12 -1
  133. package/dist/schema.json +32 -4
  134. package/dist/storage/blob-store.d.ts +3 -2
  135. package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
  136. package/dist/templates/endpoint/logic.ts.liquid +18 -0
  137. package/dist/templates/hook/logic.test.ts.liquid +2 -2
  138. package/dist/templates/package/CLAUDE.md.template +5 -2
  139. package/dist/templates/package/README.md.liquid +2 -0
  140. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
  141. package/dist/templates/package/claude/rules/workflow-create-guide.md +9 -2
  142. package/dist/templates/presentation/src/App.tsx.liquid +5 -11
  143. package/dist/templates/session/src/App.test.tsx.liquid +2 -4
  144. package/dist/templates/session/src/theme.ts.liquid +26 -33
  145. package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
  146. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
  147. package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
  148. package/dist/templates/starter-game/session/src/theme.ts +26 -33
  149. package/dist/templates/starter-game/ui/src/App.tsx +2 -0
  150. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
  151. package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
  152. package/dist/templates/starter-game/ui/src/theme.ts +26 -33
  153. package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
  154. package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
  155. package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
  156. package/dist/templates/ui/src/theme.ts.liquid +26 -33
  157. package/dist/templates/validator/logic.ts.liquid +4 -0
  158. package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
  159. package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
  160. package/dist/utils/error-codes.d.ts +15 -3
  161. package/dist/validation/ajv.d.ts +9 -5
  162. package/dist/validation/facilitator-guide-validator.d.ts +11 -1
  163. package/dist/validation/file-settings.d.ts +49 -0
  164. package/dist/validation/guide-settings-validator.d.ts +26 -0
  165. package/dist/validation/schema-validation.d.ts +12 -4
  166. package/package.json +6 -5
  167. package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
@@ -1,45 +1,38 @@
1
1
  import { createTheme } from '@mui/material/styles';
2
- import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useSessionUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
@@ -25,6 +25,7 @@ import { useTranslation } from 'react-i18next';
25
25
  import type { Settings, Context } from '../types';
26
26
  import DayBar from './DayBar';
27
27
  import HistoryPanel from './HistoryPanel';
28
+ import HostLogo from './HostLogo';
28
29
  import { useAppTheme } from './theme';
29
30
  import ThemeToggle from './ThemeToggle';
30
31
  import TodayPanel from './TodayPanel';
@@ -65,6 +66,7 @@ function Shell() {
65
66
  <Box sx={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
66
67
  <AppBar position="static" color="default" elevation={0}>
67
68
  <Toolbar sx={{ gap: 1 }}>
69
+ <HostLogo />
68
70
  <Typography variant="h6" component="h1" sx={{ flexGrow: 1 }} noWrap>
69
71
  {ownTeam?.name ?? t('shell.untitledTeam')}
70
72
  </Typography>
@@ -0,0 +1,25 @@
1
+ import {
2
+ createMockBrand,
3
+ createMockUserInterfaceTheme,
4
+ renderUserInterface,
5
+ } from '@seriousgaming/sdk/ui/testing';
6
+ import { screen } from '@testing-library/react';
7
+ import { describe, expect, it } from 'vitest';
8
+
9
+ import HostLogo from './HostLogo';
10
+
11
+ describe('the host logo', () => {
12
+ it("shows the host's logo, named for the host", () => {
13
+ const brand = createMockBrand({ name: 'Northwind' });
14
+ renderUserInterface(<HostLogo />, { theme: createMockUserInterfaceTheme({ brand }) });
15
+
16
+ const logo = screen.getByRole('img', { name: 'Northwind' });
17
+ expect(logo).toHaveAttribute('src', brand.logo?.onLight);
18
+ });
19
+
20
+ it('shows nothing when the host sends no logo', () => {
21
+ renderUserInterface(<HostLogo />);
22
+
23
+ expect(screen.queryByTestId('host-logo')).not.toBeInTheDocument();
24
+ });
25
+ });
@@ -0,0 +1,38 @@
1
+ import { Box, useTheme } from '@mui/material';
2
+ import { useBrandLogo } from '@seriousgaming/sdk/ui';
3
+
4
+ /**
5
+ * The host's logo, where it sends one, so the stall sits inside whoever is
6
+ * running the session. Nothing at all when the host sends no logo.
7
+ *
8
+ * A host that sent only the other variant gets a panel of the colour the
9
+ * artwork was drawn for, rather than dark ink on a dark bar.
10
+ */
11
+ export default function HostLogo() {
12
+ const logo = useBrandLogo();
13
+ const mode = useTheme().palette.mode;
14
+ if (!logo) return null;
15
+
16
+ const mismatched = logo.drawnFor !== mode;
17
+ return (
18
+ <Box
19
+ component="img"
20
+ src={logo.src}
21
+ alt={logo.alt}
22
+ data-testid="host-logo"
23
+ sx={{
24
+ height: 28,
25
+ maxWidth: 140,
26
+ objectFit: 'contain',
27
+ flexShrink: 0,
28
+ ...(mismatched && {
29
+ bgcolor: logo.drawnFor === 'light' ? '#ffffff' : '#121212',
30
+ borderRadius: 1,
31
+ px: 1,
32
+ py: 0.5,
33
+ boxSizing: 'content-box',
34
+ }),
35
+ }}
36
+ />
37
+ );
38
+ }
@@ -1,45 +1,38 @@
1
1
  import { createTheme } from '@mui/material/styles';
2
- import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
@@ -48,8 +48,10 @@ export interface MenuItem {
48
48
 
49
49
  import type {
50
50
  RequestTickFunction as SDKRequestTickFunction,
51
+ ScenarioFunction as SDKScenarioFunction,
51
52
  ValidatorFunction as SDKValidatorFunction,
52
53
  } from '@seriousgaming/sdk';
53
54
 
54
55
  export type ValidatorFunction = SDKValidatorFunction<Context, Settings>;
55
56
  export type RequestTickFunction = SDKRequestTickFunction<Context, Settings>;
57
+ export type ScenarioFunction = SDKScenarioFunction<Settings>;
@@ -1,45 +1,38 @@
1
1
  import { createTheme } from '@mui/material/styles';
2
- import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
@@ -1,25 +1,13 @@
1
- {% raw %}import { describe, it, expect, vi } from 'vitest';
2
- import { render, screen, fireEvent } from '@testing-library/react';
3
- import {
4
- UserInterfaceThemeContext,
5
- UserInterfaceDataContext,
6
- } from '@seriousgaming/sdk/ui';
7
- import { createMockUserInterfaceTheme } from '@seriousgaming/sdk/ui/testing';
1
+ {% raw %}import { describe, it, expect } from 'vitest';
2
+ import { screen, fireEvent } from '@testing-library/react';
3
+ import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
8
4
  import './i18n';
9
5
  import App from './App';
10
6
 
11
- // Wrap App with the SDK context providers it needs.
12
- // These replace the iframe communication that the real app uses — no mocking needed.
13
- const renderApp = (data = {}, settings = {}) =>
14
- render(
15
- <UserInterfaceThemeContext.Provider value={createMockUserInterfaceTheme()}>
16
- <UserInterfaceDataContext.Provider
17
- value={{ data, settings, completedTicks: 0, isRoundProcessing: false, setData: vi.fn() }}
18
- >
19
- <App />
20
- </UserInterfaceDataContext.Provider>
21
- </UserInterfaceThemeContext.Provider>
22
- );
7
+ // `renderUserInterface` supplies every SDK context the app reads, in place of
8
+ // the iframe communication the real app uses. Prefer it to providing a context
9
+ // yourself: a later SDK may add a field to one, which it fills in for you.
10
+ const renderApp = (data = {}, settings = {}) => renderUserInterface(<App />, { data, settings });
23
11
 
24
12
  describe('App', () => {
25
13
  it('renders the welcome message', () => {
@@ -1,46 +1,39 @@
1
1
  {% raw %}import { createTheme } from '@mui/material/styles';
2
- import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
46
39
  {% endraw %}
@@ -4,6 +4,10 @@ import type { ValidatorFunction } from '../types';
4
4
  // is `UpdateData`, the gate on a context write. Export `RequestTick` as well
5
5
  // (typed `RequestTickFunction` from '../types') to gate a participant's request
6
6
  // for the next tick: it receives `{ context, requestedTick, actor, settings, meta }`.
7
+ // Export `Scenario` (typed `ScenarioFunction`) to refuse a scenario whose
8
+ // settings break the game's rules: it receives `{ settings, locale }` and
9
+ // returns every problem as `{ path, message }`, and the game lists
10
+ // "scenario-validation" in `requires` in seriousgaming.sdk.json.
7
11
  export const UpdateData: ValidatorFunction = async ({ previous, next, actor, settings }) => {
8
12
  // Validators gate UI-submitted mutations before they're applied.
9
13
  // Return { ok: true } to allow, { ok: false, message: '...' } to reject.
@@ -1,42 +1,28 @@
1
- {% raw %}import { describe, it, expect, vi } from 'vitest';
2
- import { render, screen } from '@testing-library/react';
1
+ {% raw %}import { describe, it, expect } from 'vitest';
2
+ import { screen } from '@testing-library/react';
3
3
  import {
4
- UserInterfaceDataContext,
5
- UserInterfaceOwnTeamContext,
6
- UserInterfaceParticipantContext,
7
- UserInterfaceParticipantsContext,
8
- UserInterfaceThemeContext,
9
- } from '@seriousgaming/sdk/ui';
10
- import { createMockUserInterfaceTheme } from '@seriousgaming/sdk/ui/testing';
4
+ createMockParticipant,
5
+ createMockTeam,
6
+ renderUserInterface,
7
+ } from '@seriousgaming/sdk/ui/testing';
11
8
  import './i18n';
12
9
  import App from './App';
13
10
 
14
- // A waiting room UI is a player UI, so it renders under the same context
15
- // providers. These replace the iframe communication the real app uses.
16
- const SELF = { id: 'p1', name: 'Ada', index: 0, connected: true, teamId: 'team-1' };
11
+ // A waiting room UI is a player UI, so `renderUserInterface` supplies the
12
+ // contexts it reads, in place of the iframe communication the real app uses.
13
+ const SELF = createMockParticipant({ id: 'p1', name: 'Ada' });
17
14
  const ROSTER = [
18
- { ...SELF, connected: true },
19
- { id: 'p2', name: 'Grace', index: 1, teamId: 'team-1', connected: false },
15
+ SELF,
16
+ createMockParticipant({ id: 'p2', name: 'Grace', index: 1, connected: false }),
20
17
  ];
21
18
 
22
19
  const renderApp = (completedTicks = 0) =>
23
- render(
24
- <UserInterfaceThemeContext.Provider value={createMockUserInterfaceTheme()}>
25
- <UserInterfaceDataContext.Provider
26
- value={{ data: {}, settings: {}, completedTicks, isRoundProcessing: false, setData: vi.fn() }}
27
- >
28
- <UserInterfaceOwnTeamContext.Provider
29
- value={{ teamId: 'team-1', index: 0, name: 'Team 1' }}
30
- >
31
- <UserInterfaceParticipantContext.Provider value={SELF}>
32
- <UserInterfaceParticipantsContext.Provider value={ROSTER}>
33
- <App />
34
- </UserInterfaceParticipantsContext.Provider>
35
- </UserInterfaceParticipantContext.Provider>
36
- </UserInterfaceOwnTeamContext.Provider>
37
- </UserInterfaceDataContext.Provider>
38
- </UserInterfaceThemeContext.Provider>
39
- );
20
+ renderUserInterface(<App />, {
21
+ completedTicks,
22
+ ownTeam: createMockTeam(),
23
+ participant: SELF,
24
+ participants: ROSTER,
25
+ });
40
26
 
41
27
  describe('App', () => {
42
28
  it('says the session has not begun at tick 0', () => {
@@ -1,46 +1,39 @@
1
1
  {% raw %}import { createTheme } from '@mui/material/styles';
2
- import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
2
+ import { createSurfaceTheme, useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
3
3
  import { useMemo } from 'react';
4
4
 
5
5
  /**
6
- * The host owns the palette, the game owns the typography and the component
7
- * shapes. Reading `theme.mode` rather than the browser's preference is what
8
- * keeps a participant's screen and the facilitator's looking like one product.
6
+ * The host owns the palette, the brand and its fonts; the game owns the
7
+ * component shapes, and its own font where the host's brand names none.
8
+ * Reading `theme.mode` rather than the browser's preference is what keeps a
9
+ * participant's screen and the facilitator's looking like one product.
9
10
  */
10
11
  export const useAppTheme = () => {
11
12
  const theme = useUserInterfaceTheme();
12
13
 
13
- return useMemo(() => {
14
- const colors = theme.mode === 'light' ? theme.light : theme.dark;
15
- return createTheme({
16
- palette: {
17
- mode: theme.mode,
18
- primary: { main: colors.primary, contrastText: colors.contrastText.primary },
19
- secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
20
- success: { main: colors.success, contrastText: colors.contrastText.success },
21
- error: { main: colors.error, contrastText: colors.contrastText.error },
22
- warning: { main: colors.warning, contrastText: colors.contrastText.warning },
23
- info: { main: colors.info, contrastText: colors.contrastText.info },
24
- },
25
- shape: { borderRadius: 10 },
26
- components: {
27
- MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
28
- MuiTab: {
29
- styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
30
- },
31
- MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
32
- MuiTableCell: {
33
- styleOverrides: {
34
- head: {
35
- fontSize: '0.75rem',
36
- fontWeight: 700,
37
- letterSpacing: '0.07em',
38
- textTransform: 'uppercase',
14
+ return useMemo(
15
+ () =>
16
+ createTheme(createSurfaceTheme(theme, { fonts: { body: 'Work Sans Variable' } }), {
17
+ shape: { borderRadius: 10 },
18
+ components: {
19
+ MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
20
+ MuiTab: {
21
+ styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
22
+ },
23
+ MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
24
+ MuiTableCell: {
25
+ styleOverrides: {
26
+ head: {
27
+ fontSize: '0.75rem',
28
+ fontWeight: 700,
29
+ letterSpacing: '0.07em',
30
+ textTransform: 'uppercase',
31
+ },
39
32
  },
40
33
  },
41
34
  },
42
- },
43
- });
44
- }, [theme]);
35
+ }),
36
+ [theme]
37
+ );
45
38
  };
46
39
  {% endraw %}
@@ -141,6 +141,10 @@ export declare const ERROR_CODES: {
141
141
  readonly category: "package";
142
142
  readonly description: "The manifest's `requires` names an optional feature this version of the SDK does not support.";
143
143
  };
144
+ readonly FEATURE_UNDECLARED: {
145
+ readonly category: "package";
146
+ readonly description: "The package uses an optional feature its manifest's `requires` does not list, so a runtime without the feature would run it with part of it missing.";
147
+ };
144
148
  readonly REFERENCE_UNKNOWN: {
145
149
  readonly category: "package";
146
150
  readonly description: "A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.";
@@ -189,9 +193,17 @@ export declare const ERROR_CODES: {
189
193
  readonly category: "package";
190
194
  readonly description: "A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.";
191
195
  };
192
- readonly EDITOR_ENDPOINT_STATEFUL: {
196
+ readonly SCENARIO_REFUSED: {
197
+ readonly category: "package";
198
+ readonly description: "A validator's `Scenario` gate found a problem with a package scenario, or with the defaults when no scenario is the default. The diagnostic points at the setting it names.";
199
+ };
200
+ readonly EDITOR_ENDPOINT_NOT_SCENARIO: {
201
+ readonly category: "package";
202
+ readonly description: "The scenario editor lists an endpoint that is not scenario-scoped. It works on a scenario draft with no session, so it calls `\"scope\": \"scenario\"` endpoints alone.";
203
+ };
204
+ readonly SCENARIO_ENDPOINT_STATEFUL: {
193
205
  readonly category: "package";
194
- readonly description: "The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.";
206
+ readonly description: "A scenario-scoped endpoint declares `reads`, `writes`, `actions` or `roster`, which need a session a scenario draft does not have.";
195
207
  };
196
208
  readonly EXTERNAL_REQUEST_NOT_OBJECT: {
197
209
  readonly category: "package";
@@ -332,7 +344,7 @@ export type ErrorCode = keyof typeof ERROR_CODES;
332
344
  * failure's `error.code` says what kind of failure it was; its diagnostics say
333
345
  * what was found and where. LOGIC_ERROR is only ever a diagnostic.
334
346
  */
335
- export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "SCENARIO_EDITOR_UNREACHABLE", "EDITOR_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
347
+ export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "FEATURE_UNDECLARED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "SCENARIO_EDITOR_UNREACHABLE", "SCENARIO_REFUSED", "EDITOR_ENDPOINT_NOT_SCENARIO", "SCENARIO_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
336
348
  export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
337
349
  export declare function categoryOf(code: ErrorCode): ErrorCategory;
338
350
  export declare function exitCodeOf(code: ErrorCode): number;