@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/templates/package/oxlintrc.json.template

@@ -0,0 +1,238 @@
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    "plugins": null,
+    "categories": {},
+    "rules": {
+        "typescript/no-explicit-any": "error",
+        "typescript/no-non-null-assertion": "error"
+    },
+    "settings": {
+        "jsx-a11y": {
+            "polymorphicPropName": null,
+            "components": {},
+            "attributes": {}
+        },
+        "next": {
+            "rootDir": []
+        },
+        "react": {
+            "formComponents": [],
+            "linkComponents": [],
+            "version": null,
+            "componentWrapperFunctions": []
+        },
+        "jsdoc": {
+            "ignorePrivate": false,
+            "ignoreInternal": false,
+            "ignoreReplacesDocs": true,
+            "overrideReplacesDocs": true,
+            "augmentsExtendsReplacesDocs": false,
+            "implementsReplacesDocs": false,
+            "exemptDestructuredRootsFromChecks": false,
+            "tagNamePreference": {}
+        },
+        "vitest": {
+            "typecheck": false
+        }
+    },
+    "env": {
+        "builtin": true
+    },
+    "globals": {},
+    "ignorePatterns": ["**/types.ts"],
+    "overrides": [
+        {
+            "files": [
+                "engine/**/*.ts",
+                "tick_controller/**/*.ts",
+                "**/hooks/*/logic/**/*.ts",
+                "**/validators/*/logic/**/*.ts",
+                "**/endpoints/*/logic/**/*.ts"
+            ],
+            "rules": {
+                "no-restricted-globals": [
+                    "error",
+                    {
+                        "name": "structuredClone",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Context is JSON-serialisable, so JSON.parse(JSON.stringify(value)) is the portable equivalent."
+                    },
+                    {
+                        "name": "TextEncoder",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Import encodeUtf8 from @seriousgaming/sdk instead."
+                    },
+                    {
+                        "name": "TextDecoder",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Import decodeUtf8 from @seriousgaming/sdk instead."
+                    },
+                    {
+                        "name": "fetch",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Reach external services through the injected callbacks, or through an endpoint."
+                    },
+                    {
+                        "name": "XMLHttpRequest",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Reach external services through the injected callbacks, or through an endpoint."
+                    },
+                    {
+                        "name": "setTimeout",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
+                    },
+                    {
+                        "name": "setInterval",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
+                    },
+                    {
+                        "name": "setImmediate",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
+                    },
+                    {
+                        "name": "queueMicrotask",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Ticks are the scheduling primitive: logic must run to completion within one tick."
+                    },
+                    {
+                        "name": "process",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Settings reach logic through the `settings` argument."
+                    },
+                    {
+                        "name": "Buffer",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Use Uint8Array, with the SDK's encodeUtf8 / decodeUtf8 for string conversion."
+                    },
+                    {
+                        "name": "URL",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics. Build asset URLs from the references and callbacks the runtime injects."
+                    },
+                    {
+                        "name": "clearTimeout",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "clearInterval",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "clearImmediate",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "URLSearchParams",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "crypto",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "atob",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "btoa",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "performance",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "ReadableStream",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "WritableStream",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "TransformStream",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "Blob",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "File",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "FormData",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "Headers",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "Request",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "Response",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "AbortController",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "EventTarget",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "WebSocket",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "localStorage",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "sessionStorage",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "window",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "document",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "navigator",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "require",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "__dirname",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    },
+                    {
+                        "name": "__filename",
+                        "message": "Not available in the production runtime, which is a bare V8 isolate exposing only the ECMAScript intrinsics."
+                    }
+                ]
+            }
+        },
+        {
+            "files": ["**/*.test.ts", "**/*.spec.ts"],
+            "rules": {
+                "no-restricted-globals": "off"
+            }
+        },
+        {
+            "files": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/testing/**"],
+            "rules": {
+                "typescript/no-explicit-any": "off",
+                "typescript/no-non-null-assertion": "off"
+            }
+        },
+        {
+            "files": ["**/src/main.tsx"],
+            "rules": {
+                "typescript/no-non-null-assertion": "off"
+            }
+        }
+    ]
+}

package/dist/templates/package/package.json.liquid

@@ -0,0 +1,65 @@
+{
+    "name": "{{ identifier }}",
+    "version": "{{ version }}",
+    "description": "{{ name }}",
+    "license": "UNLICENSED",
+    "files": [
+        "dist"
+    ],
+    "type": "module",
+    "main": "index.js",
+    "scripts": {
+        "generate": "pnpm run sdk generate",
+        "build": "pnpm run sdk build",
+        "start": "pnpm run sdk dev",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "test:engine": "vitest run --config vitest.engine.config.ts",
+        "test:e2e": "playwright test",
+        "lint": "oxlint --max-warnings=0",
+        "lint:fix": "oxlint --fix",
+        "format": "oxfmt",
+        "format:check": "oxfmt --check",
+        "typecheck": "tsc --noEmit",
+        "sdk": "seriousgaming-sdk"
+    },
+    "dependencies": {
+        "@emotion/cache": "^11.14.0",
+        "@emotion/react": "^11.14.0",
+        "@emotion/styled": "^11.14.1",
+        "@fontsource-variable/roboto-mono": "^5.3.0",
+        "@fontsource-variable/work-sans": "^5.3.0",
+        "@mui/icons-material": "^9.4.0",
+        "@mui/material": "^9.4.0",
+        "@mui/stylis-plugin-rtl": "^9.4.0",
+        "@seriousgaming/deck": "^{{ sdkVersion }}",
+        "i18next": "^26.4.2",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "react-i18next": "^17.0.16",
+        "stylis": "^4.4.0",
+        "vite": "^8.3.4"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.64.0",
+        "@seriousgaming/sdk": "^{{ sdkVersion }}",
+        "@seriousgaming/sdk-tools": "^{{ sdkVersion }}",
+        "@testing-library/jest-dom": "^7.0.1",
+        "@testing-library/react": "^16.3.3",
+        "@testing-library/user-event": "^14.6.7",
+        "@types/node": "^24.19.1",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "@types/stylis": "^4.2.7",
+        "jsdom": "^30.1.2",
+        "oxfmt": "^0.67.0",
+        "oxlint": "^1.87.0",
+        "typescript": "^6.0.3",
+        "vite-node": "^6.0.0",
+        "vitest": "^5.0.3"
+    },
+    "peerDependencies": {
+        "@seriousgaming/sdk": "^{{ sdkVersion }}"
+    }
+}

package/dist/templates/package/playwright.config.ts.liquid

@@ -0,0 +1,19 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './testing/e2e',
+    // Starts an isolated dev server on free ports, beside any `sdk dev` you
+    // have running, and stops it when the run ends. It names the server in
+    // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
+    globalSetup: './testing/e2e/global-setup.ts',
+    // One worker: these tests share a session, so a tick in one is visible to
+    // the next. Running them in parallel makes each test's starting state
+    // depend on what another happened to be doing.
+    workers: 1,
+    // A stray `test.only` passes locally and silently skips the rest on CI.
+    forbidOnly: !!process.env.CI,
+    use: {
+        // Read again in each worker, after the global setup has set it.
+        baseURL: process.env.SERIOUSGAMING_DEV_URL,
+    },
+});

package/dist/templates/package/pnpm-workspace.yaml.template

@@ -0,0 +1,27 @@
+# A transitive dependency of the SDK packages whose parent pins it to a range
+# that only reaches a version with a security advisory against it. Your package
+# does not depend on it directly, and nothing you change in package.json moves
+# it, so it is held here instead.
+# - image-size: @seriousgaming/deck reaches it through pptxgenjs, which asks for
+#   ^1.2.1, and no 1.x is patched against the parser loops in
+#   GHSA-5p2g-fcmc-qvqq and GHSA-w3rx-r6r6-pgpr. pptxgenjs never loads it at
+#   run time, so the newer major is safe.
+#
+# Keep the list this short. Most flagged transitives resolve to a patched
+# version on their own once you update, so run `pnpm audit` first and add an
+# override only for what it still reports. Note that overrides belong in this
+# file and not under a `pnpm` key in package.json: pnpm 11 no longer reads that
+# key, and ignores what it finds there without warning you.
+overrides:
+    image-size: '>=2.0.3'
+
+# Which dependencies may run an install script. esbuild reaches your game
+# through the SDK tooling, and its script has never run: the executable arrives
+# in the @esbuild/<platform> optional dependency, and the script only re-checks
+# that it matches. pnpm 11 onwards treats an undeclared install script as an
+# error rather than a warning, so without this entry `pnpm install` stops with
+# ERR_PNPM_IGNORED_BUILDS. Add your own entries here as you add dependencies
+# that want to run scripts, and prefer `false` unless the package genuinely
+# needs the script to work.
+allowBuilds:
+    esbuild: false

package/dist/templates/package/test-setup.ts.liquid

@@ -0,0 +1,7 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+// RTL does not auto-detect Vitest without globals mode enabled,
+// so we explicitly clean up the DOM after each test.
+afterEach(cleanup);

package/dist/templates/package/tsconfig.json.liquid

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "esnext",
+        "allowJs": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "noImplicitAny": true,
+        "sourceMap": true,
+        "outDir": "dist",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "jsx": "react-jsx"
+    }
+}

package/dist/templates/package/vite.config.ts.liquid

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    resolve: {
+        // One copy of each package that holds React context, however many
+        // paths lead to it. A second copy brings contexts of its own, so a
+        // hook reads empty data: React's "Invalid hook call" when MUI bundles
+        // its own React, or an SDK hook in a shared package of yours that
+        // finds none of the providers the host set up.
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+        ],
+    },
+});

package/dist/templates/package/vitest.config.ts.liquid

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    resolve: {
+        // The same single copies vite.config.ts asks for, so a test renders
+        // with the providers the component reads.
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+        ],
+    },
+    esbuild: {
+        jsx: 'automatic',
+    },
+    test: {
+        environment: 'jsdom',
+        setupFiles: ['./test-setup.ts'],
+        // Exclude engine tests (node env, separate config) and Playwright specs
+        exclude: ['testing/**', '**/node_modules/**'],
+    },
+});

package/dist/templates/package/vitest.engine.config.ts.liquid

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        // Node environment — engine tests run the game engine in-process,
+        // no browser APIs needed.
+        environment: 'node',
+        // Allow long-running games (e.g. 100+ ticks with LLM calls).
+        testTimeout: 60_000,
+        include: ['testing/engine/**/*.engine.test.ts'],
+    },
+});

package/dist/templates/presentation/index.html.liquid

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{{ name }}</title>
+        <style>
+            html,
+            body,
+            #root {
+                height: 100%;
+                margin: 0;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./src/main.tsx"></script>
+    </body>
+</html>

package/dist/templates/presentation/src/App.tsx.liquid

@@ -0,0 +1,49 @@
+import { Deck, defaultBrand, type Brand } from '@seriousgaming/deck';
+import { usePresentation } from '@seriousgaming/sdk/ui';
+import { useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import type { Settings, SharedContext, TeamContext } from '../types';
+import { slides } from './Slides';
+
+/*
+A presentation is the facilitator's slide deck. It is read-only, and it renders
+with or without a session: in a game's library, while rehearsing or to export
+it beforehand, `session` is null, so every slide must make sense without
+results.
+
+The host's theme colours are mapped onto the deck's brand here, so the slides
+pick up the same primary and secondary as every other surface.
+*/
+
+export default function App() {
+    const { game, session, theme, locale } = usePresentation<Settings, TeamContext, SharedContext>();
+    const { t, i18n } = useTranslation();
+    const language = locale.locale.split('-')[0];
+
+    useEffect(() => {
+        void i18n.changeLanguage(language);
+    }, [i18n, language]);
+
+    const brand: Partial<Brand> = {
+        colors: {
+            ...defaultBrand.colors,
+            primary: theme.light.primary,
+            secondary: theme.light.secondary,
+        },
+    };
+
+    return (
+        <Deck
+            brand={brand}
+            title={game.name}
+            dir={i18n.dir(language)}
+            lang={language}
+            // Come back to the same slide after a reload or a break. Each session
+            // keeps its own place; rehearsing without one has one of its own.
+            rememberAs={session ? `session:${session.id}` : `rehearsal:${game.name}`}
+        >
+            {slides({ game, session, t })}
+        </Deck>
+    );
+}

package/dist/templates/presentation/src/Slides.tsx.liquid

@@ -0,0 +1,81 @@
+{% raw %}import {
+    Bullets,
+    Heading,
+    Slide,
+    Table,
+    Text,
+} from '@seriousgaming/deck';
+import type { PresentationGame } from '@seriousgaming/sdk/ui';
+import type { TFunction } from 'i18next';
+
+import type { PresentationSession } from '../types';
+
+const PADDING = '120px 140px';
+
+/*
+Every element in the returned array is one slide, so add a slide by adding an
+element. Keep them in an array rather than wrapping them in a component of
+your own: the deck counts its direct children, and a wrapper would be one
+slide.
+
+Every word goes through `t`, so the slides follow the session's language.
+*/
+export function slides({
+    game,
+    session,
+    t,
+}: {
+    game: PresentationGame;
+    session: PresentationSession | null;
+    t: TFunction;
+}) {
+    return [
+        <Slide key="title" notes="Welcome everyone and introduce the session.">
+            <div
+                style={{
+                    display: 'flex',
+                    flexDirection: 'column',
+                    justifyContent: 'center',
+                    gap: 32,
+                    height: '100%',
+                    padding: PADDING,
+                    boxSizing: 'border-box',
+                }}
+            >
+                <Heading level={1}>{game.name}</Heading>
+                {session && <Text variant="lead">{session.name}</Text>}
+            </div>
+        </Slide>,
+
+        <Slide key="agenda" transition="slide" notes="Reveal each point in turn.">
+            <div style={{ padding: PADDING }}>
+                <Heading>{t('agendaHeading')}</Heading>
+                <Bullets
+                    stepped
+                    style={{ marginTop: 60 }}
+                    items={[t('agendaTeam'), t('agendaDecide'), t('agendaReview')]}
+                />
+            </div>
+        </Slide>,
+
+        <Slide key="results" transition="rise">
+            <div style={{ padding: PADDING }}>
+                <Heading>{t('resultsHeading')}</Heading>
+                <div style={{ marginTop: 60 }}>
+                    {session ? (
+                        <Table
+                            columns={[t('resultsTeam'), t('resultsRound')]}
+                            align={['start', 'end']}
+                            rows={session.teams.map((team) => [
+                                team.name,
+                                session.data.teams[team.teamId]?.completedTicks ?? 0,
+                            ])}
+                        />
+                    ) : (
+                        <Text>{t('resultsPending')}</Text>
+                    )}
+                </div>
+            </div>
+        </Slide>,
+    ];
+}{% endraw %}

package/dist/templates/presentation/src/i18n.ts.liquid

@@ -0,0 +1,54 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+// Every word on a slide comes from here, so the deck follows the session's
+// language and exports in it.
+const resources = {
+    en: {
+        translation: {
+            agendaHeading: 'Today',
+            agendaTeam: 'Meet your team',
+            agendaDecide: 'Make your decisions each round',
+            agendaReview: 'Review the results together',
+            resultsHeading: 'Results',
+            resultsTeam: 'Team',
+            resultsRound: 'Round',
+            resultsPending: 'Results appear here once the session has started',
+        },
+    },
+    it: {
+        translation: {
+            agendaHeading: 'Oggi',
+            agendaTeam: 'Conosci la tua squadra',
+            agendaDecide: 'Prendi le tue decisioni a ogni turno',
+            agendaReview: 'Esaminate insieme i risultati',
+            resultsHeading: 'Risultati',
+            resultsTeam: 'Squadra',
+            resultsRound: 'Turno',
+            resultsPending: 'I risultati compaiono qui quando la sessione è iniziata',
+        },
+    },
+    ar: {
+        translation: {
+            agendaHeading: 'اليوم',
+            agendaTeam: 'تعرّف على فريقك',
+            agendaDecide: 'اتخذ قراراتك في كل جولة',
+            agendaReview: 'راجعوا النتائج معًا',
+            resultsHeading: 'النتائج',
+            resultsTeam: 'الفريق',
+            resultsRound: 'الجولة',
+            resultsPending: 'تظهر النتائج هنا بعد بدء الجلسة',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    fallbackLng: 'en',
+    interpolation: {
+        escapeValue: false, // React already escapes
+    },
+});
+
+export default i18n;

package/dist/templates/presentation/src/main.tsx.liquid

@@ -0,0 +1,14 @@
+import { PresentationWrapper } from '@seriousgaming/sdk/ui';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import App from './App';
+import './i18n';
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <PresentationWrapper>
+            <App />
+        </PresentationWrapper>
+    </StrictMode>
+);