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

package/dist/templates/starter-game/ui/src/test-helpers.ts

@@ -0,0 +1,58 @@
+import type { Context, Settings } from '../types';
+
+/**
+ * A complete starting context and settings for the surface's tests.
+ *
+ * A game wires one participant surface, so `Context` is every capability it
+ * reads or writes. A panel test cares about a handful of those, so it spreads
+ * what it needs over these rather than restating the whole shape, and adding a
+ * field to a capability does not break every test that was never about it.
+ */
+export const baseContext: Context = {
+    plan: { Make: { lemonade: 40, icedtea: 20, cookies: 10 } },
+    weather: { Today: 'sunny', Expected: { lemonade: 72, icedtea: 39, cookies: 26 } },
+    results: {
+        Day: 0,
+        Weather: 'sunny',
+        Lines: {},
+        Takings: 0,
+        Spent: 0,
+        Profit: 0,
+        Purse: 0,
+    },
+    roles: { LooksAfter: {} },
+    briefing: { Message: '' },
+};
+
+/** A day that has been played, for the panels that only appear once one has. */
+export const playedDay: Context = {
+    ...baseContext,
+    results: {
+        Day: 1,
+        Weather: 'sunny',
+        Lines: {
+            lemonade: { Made: 40, Wanted: 68, Sold: 40, PouredAway: 0, TurnedAway: 28 },
+            icedtea: { Made: 20, Wanted: 15, Sold: 15, PouredAway: 5, TurnedAway: 0 },
+            cookies: { Made: 10, Wanted: 24, Sold: 10, PouredAway: 0, TurnedAway: 14 },
+        },
+        Takings: 40 * 50 + 15 * 60 + 10 * 70,
+        Spent: 40 * 15 + 20 * 20 + 10 * 25,
+        Profit: 40 * 50 + 15 * 60 + 10 * 70 - (40 * 15 + 20 * 20 + 10 * 25),
+        Purse: 2350,
+    },
+};
+
+export const baseSettings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
+            icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
+            cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
+        },
+    },
+    ui: {
+        Step: 5,
+        CurrencySymbol: '£',
+    },
+};

package/dist/templates/starter-game/ui/src/theme.ts

@@ -0,0 +1,45 @@
+import { createTheme } from '@mui/material/styles';
+import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+import { useMemo } from 'react';
+
+/**
+ * The host owns the palette, the game owns the typography and the component
+ * shapes. Reading `theme.mode` rather than the browser's preference is what
+ * keeps a participant's screen and the facilitator's looking like one product.
+ */
+export const useAppTheme = () => {
+    const theme = useUserInterfaceTheme();
+
+    return useMemo(() => {
+        const colors = theme.mode === 'light' ? theme.light : theme.dark;
+        return createTheme({
+            palette: {
+                mode: theme.mode,
+                primary: { main: colors.primary, contrastText: colors.contrastText.primary },
+                secondary: { main: colors.secondary, contrastText: colors.contrastText.secondary },
+                success: { main: colors.success, contrastText: colors.contrastText.success },
+                error: { main: colors.error, contrastText: colors.contrastText.error },
+                warning: { main: colors.warning, contrastText: colors.contrastText.warning },
+                info: { main: colors.info, contrastText: colors.contrastText.info },
+            },
+            shape: { borderRadius: 10 },
+            components: {
+                MuiButton: { styleOverrides: { root: { textTransform: 'none' } } },
+                MuiTab: {
+                    styleOverrides: { root: { textTransform: 'none', fontSize: '0.95rem' } },
+                },
+                MuiToggleButton: { styleOverrides: { root: { textTransform: 'none' } } },
+                MuiTableCell: {
+                    styleOverrides: {
+                        head: {
+                            fontSize: '0.75rem',
+                            fontWeight: 700,
+                            letterSpacing: '0.07em',
+                            textTransform: 'uppercase',
+                        },
+                    },
+                },
+            },
+        });
+    }, [theme]);
+};

package/dist/templates/starter-game/ui/src/writes.ts

@@ -0,0 +1,43 @@
+import type { MutationReporter } from '@seriousgaming/sdk/ui';
+import { createContext, useContext } from 'react';
+
+/**
+ * One mutation reporter for the whole surface.
+ *
+ * `setData` returns a promise, and a write the host refuses rejects it. Nothing
+ * on screen says so by itself, because the local view merged the change the
+ * moment it was sent: the participant is left looking at a decision the game
+ * never received. Every write here goes through `reporter.run`, and `App`
+ * renders the one notice that reports what comes back.
+ *
+ * The context carries the whole reporter, `pending` included, so any control
+ * can disable itself while a write is in flight. That re-renders the tab tree
+ * on every write, which is free at this size. A surface with dozens of leaf
+ * inputs would narrow the context to `run` alone and let individual controls
+ * call `useMutationReporter` for their own pending state.
+ */
+export const WriteContext = createContext<MutationReporter | null>(null);
+
+/**
+ * Outside a provider the write still runs and its result is dropped, so a
+ * component stays renderable on its own in a test without every one of them
+ * having to install the provider.
+ */
+const UNREPORTED: MutationReporter = {
+    run: async (mutate) => {
+        try {
+            await mutate();
+            return true;
+        } catch {
+            return false;
+        }
+    },
+    pending: false,
+    late: null,
+    failure: null,
+    dismiss: () => {},
+};
+
+export function useWrite(): MutationReporter {
+    return useContext(WriteContext) ?? UNREPORTED;
+}

package/dist/templates/starter-game/ui/types.ts

@@ -0,0 +1,137 @@
+// This file is auto-generated from the user interface's capability definitions.
+// Do not edit this file directly. It will be regenerated on build.
+
+export interface Context {
+    plan: {
+        /**
+         * How many of each menu item to make today, keyed by item id. Keyed rather than a flat set of fields so that two people changing two different items write different keys, and the host's merge keeps both.
+         */
+        Make: {
+            [k: string]: number;
+        };
+    };
+    weather: {
+        /**
+         * The forecast for the day about to be played
+         */
+        Today: 'sunny' | 'cloudy' | 'rainy';
+        /**
+         * Roughly how many of each item people will want today, keyed by item id. A forecast, not a promise: the day lands somewhere near it.
+         */
+        Expected: {
+            [k: string]: number;
+        };
+    };
+    results: {
+        /**
+         * The day these results are for
+         */
+        Day: number;
+        /**
+         * What the weather actually did
+         */
+        Weather: string;
+        /**
+         * What happened to each menu item, keyed by item id
+         */
+        Lines: {
+            [k: string]: DayLine;
+        };
+        /**
+         * Money in, in pence
+         */
+        Takings: number;
+        /**
+         * Cost of everything made, in pence
+         */
+        Spent: number;
+        /**
+         * Takings less spend, in pence
+         */
+        Profit: number;
+        /**
+         * Everything made so far, in pence
+         */
+        Purse: number;
+    };
+    roles: {
+        /**
+         * Which menu item each participant is in charge of, keyed by participant id. Written by the participantJoin hook, and the reason two people normally edit two different keys.
+         */
+        LooksAfter: {
+            [k: string]: string;
+        };
+    };
+    briefing: {
+        /**
+         * Facilitator note shown on every team's screen. Shared scope: one value for the whole session, written only from the session surface. Session lifetime: an undo or a reset leaves it as the facilitator last wrote it.
+         */
+        Message: string;
+    };
+}
+export interface DayLine {
+    Made: number;
+    /**
+     * How many people asked for one
+     */
+    Wanted: number;
+    Sold: number;
+    /**
+     * Made and not sold
+     */
+    PouredAway: number;
+    /**
+     * Asked for and not available
+     */
+    TurnedAway: number;
+}
+
+export type CrossTeamContext = Record<string, never>;
+
+export interface Settings {
+    menu: {
+        /**
+         * How many items the stall can make in a day, across the whole menu
+         */
+        Capacity: number;
+        Menu: Menu;
+    };
+    ui: {
+        /**
+         * How many items each nudge of a slider adds to or takes off the plan
+         */
+        Step: number;
+        /**
+         * Symbol for money on the participant surface. Prices are the same numbers whichever symbol is shown
+         */
+        CurrencySymbol: '£' | '$' | '€';
+    };
+}
+/**
+ * What the stall sells, keyed by item id. Money is in pence, so the sums stay in whole numbers. Read by the engine and every surface, so the price on screen and the price in the sums are the same number.
+ */
+export interface Menu {
+    [k: string]: MenuItem;
+}
+export interface MenuItem {
+    /**
+     * What the item is called on every screen
+     */
+    Name: string;
+    /**
+     * Where it sits on the menu, so every screen lists it in the same order. 1 comes first
+     */
+    Order: number;
+    /**
+     * Cost to make one, in pence
+     */
+    Cost: number;
+    /**
+     * Sale price, in pence
+     */
+    Price: number;
+}
+
+import type { UserInterfaceCallbacks } from '@seriousgaming/sdk';
+
+export type Callbacks = Pick<UserInterfaceCallbacks, never>;

package/dist/templates/starter-game/ui/ui.sdk.json

@@ -0,0 +1,11 @@
+{
+    "definition": {
+        "reads": ["plan", "weather", "results", "roles", "briefing"],
+        "writes": ["plan"],
+        "settings": ["menu", "ui"]
+    },
+    "ui": {
+        "entrypoint": "index.html"
+    },
+    "rootDirectory": "."
+}

package/dist/templates/starter-game/validators/capacity/defaults.ts

@@ -0,0 +1,37 @@
+// This file is auto-generated from the schemas the resource declares: the values
+// a session starts with, for use as test fixtures.
+// Do not edit this file directly. It will be regenerated on build.
+
+import type { Context, Settings } from './types';
+
+export const defaultContext: Context = {
+    plan: {
+        Make: {},
+    },
+};
+
+export const defaultSettings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: {
+                Name: 'Lemonade',
+                Order: 1,
+                Cost: 15,
+                Price: 50,
+            },
+            icedtea: {
+                Name: 'Iced tea',
+                Order: 2,
+                Cost: 20,
+                Price: 60,
+            },
+            cookies: {
+                Name: 'Cookies',
+                Order: 3,
+                Cost: 25,
+                Price: 70,
+            },
+        },
+    },
+};

package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Settings, Context } from '../types';
+import { UpdateData } from './logic';
+
+const actor = {
+    role: 'participant',
+    participant: {
+        id: 'participant-1',
+        teamId: 'team-1',
+        name: 'Ada',
+        index: 0,
+        connected: true,
+    },
+} as const;
+
+const settings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: { Name: 'Lemonade', Order: 1, Cost: 15, Price: 50 },
+            icedtea: { Name: 'Iced tea', Order: 2, Cost: 20, Price: 60 },
+            cookies: { Name: 'Cookies', Order: 3, Cost: 25, Price: 70 },
+        },
+    },
+};
+
+const START = { lemonade: 40, icedtea: 20, cookies: 10 };
+
+/** `next` is the merged state the write would produce, which is what the host hands a validator. */
+const verdict = (
+    made: Partial<Record<string, number>>,
+    over: { previous?: Partial<Context['plan']['Make']> } = {}
+) =>
+    UpdateData({
+        participants: [],
+        previous: { plan: { Make: { ...START, ...over.previous } } },
+        next: {
+            plan: { Make: { ...START, ...over.previous, ...made } as Record<string, number> },
+        },
+        actor,
+        settings,
+        meta: { locale: 'en', seed: 'lemonade-test-seed', runKind: 'session', now: 0 },
+    });
+
+describe('UpdateData', () => {
+    it('accepts a plan the stall can make', async () => {
+        expect(await verdict({ lemonade: 60 })).toEqual({ ok: true });
+    });
+
+    it('accepts a plan that fills the stall exactly', async () => {
+        expect(await verdict({ lemonade: 90, icedtea: 20, cookies: 10 })).toEqual({ ok: true });
+    });
+
+    /**
+     * The case the whole validator exists for. Two people each change their own
+     * item, each within capacity on the screen in front of them, and the merged
+     * plan is not.
+     */
+    it('refuses the write that tips the merged plan over capacity', async () => {
+        // Ada took the lemonade to 70: 70 + 20 + 10 is 100, and lands.
+        expect(await verdict({ lemonade: 70 })).toEqual({ ok: true });
+
+        // Grace, at the same moment, takes the cookies to 60. Her screen showed
+        // the lemonade at 40, so 40 + 20 + 60 looked fine to her. It merges onto
+        // Ada's write, and 70 + 20 + 60 does not fit in the stall.
+        const result = await verdict({ cookies: 60 }, { previous: { lemonade: 70 } });
+
+        expect(result.ok).toBe(false);
+        expect(result).toHaveProperty('message', expect.stringContaining('asks for 150'));
+        expect(result).toHaveProperty(
+            'message',
+            expect.stringContaining('at the same time as you')
+        );
+    });
+
+    it('refuses a fraction of a cup', async () => {
+        const result = await verdict({ lemonade: 40.5 });
+
+        expect(result.ok).toBe(false);
+        expect(result).toHaveProperty('message', expect.stringContaining('Lemonade'));
+    });
+
+    it('refuses a negative number', async () => {
+        const result = await verdict({ lemonade: -1 });
+
+        expect(result.ok).toBe(false);
+    });
+
+    it('refuses something that is not on the menu', async () => {
+        const result = await verdict({ brownies: 10 });
+
+        expect(result.ok).toBe(false);
+        expect(result).toHaveProperty('message', expect.stringContaining('no brownies'));
+    });
+});

package/dist/templates/starter-game/validators/capacity/logic/logic.ts

@@ -0,0 +1,45 @@
+import type { ValidatorFunction } from '../types';
+
+/**
+ * The gate on every change a surface makes to the day's plan.
+ *
+ * This is the case a schema shape cannot fix, and the reason validators exist.
+ *
+ * Each person looks after one thing on the menu, so two people changing two
+ * different things write two different keys and the host's merge keeps both.
+ * That is the design working. But the stall can only make so much in a day, and
+ * the cap is on the *total*: Ada can raise the lemonade to 70 and Grace can
+ * raise the cookies to 60 at the same moment, each of them looking at a screen
+ * where their own change fits, and the merged plan asks the stall for 130.
+ *
+ * Neither write is wrong on its own, and no amount of keying state differently
+ * makes them compatible. Only something looking at the merged result can tell,
+ * which is exactly what `next` is. The second write is refused with a message
+ * saying what happened, instead of quietly committing a plan nobody chose.
+ */
+export const UpdateData: ValidatorFunction = async ({ next, settings }) => {
+    const { Capacity, Menu } = settings.menu;
+
+    let total = 0;
+    for (const [id, count] of Object.entries(next.plan.Make)) {
+        if (!Menu[id]) {
+            return { ok: false, message: `There is no ${id} on the menu.` };
+        }
+        if (!Number.isInteger(count) || count < 0) {
+            return {
+                ok: false,
+                message: `You cannot make ${count} ${Menu[id].Name}.`,
+            };
+        }
+        total += count;
+    }
+
+    if (total > Capacity) {
+        return {
+            ok: false,
+            message: `The stall can make ${Capacity} things in a day, and that plan asks for ${total}. Somebody may have changed something at the same time as you.`,
+        };
+    }
+
+    return { ok: true };
+};

package/dist/templates/starter-game/validators/capacity/types.ts

@@ -0,0 +1,55 @@
+// This file is auto-generated from the validator's capability definitions.
+// Do not edit this file directly. It will be regenerated on build.
+
+export interface Context {
+    plan: {
+        /**
+         * How many of each menu item to make today, keyed by item id. Keyed rather than a flat set of fields so that two people changing two different items write different keys, and the host's merge keeps both.
+         */
+        Make: {
+            [k: string]: number;
+        };
+    };
+}
+
+export interface Settings {
+    menu: {
+        /**
+         * How many items the stall can make in a day, across the whole menu
+         */
+        Capacity: number;
+        Menu: Menu;
+    };
+}
+/**
+ * What the stall sells, keyed by item id. Money is in pence, so the sums stay in whole numbers. Read by the engine and every surface, so the price on screen and the price in the sums are the same number.
+ */
+export interface Menu {
+    [k: string]: MenuItem;
+}
+export interface MenuItem {
+    /**
+     * What the item is called on every screen
+     */
+    Name: string;
+    /**
+     * Where it sits on the menu, so every screen lists it in the same order. 1 comes first
+     */
+    Order: number;
+    /**
+     * Cost to make one, in pence
+     */
+    Cost: number;
+    /**
+     * Sale price, in pence
+     */
+    Price: number;
+}
+
+import type {
+    RequestTickFunction as SDKRequestTickFunction,
+    ValidatorFunction as SDKValidatorFunction,
+} from '@seriousgaming/sdk';
+
+export type ValidatorFunction = SDKValidatorFunction<Context, Settings>;
+export type RequestTickFunction = SDKRequestTickFunction<Context, Settings>;

package/dist/templates/starter-game/validators/capacity/validator.sdk.json

@@ -0,0 +1,11 @@
+{
+    "definition": {
+        "reads": ["plan"],
+        "settings": ["menu"]
+    },
+    "logic": {
+        "directory": "logic",
+        "entrypoint": "logic.ts"
+    },
+    "rootDirectory": "."
+}

package/dist/templates/starter-game/vite.config.ts

@@ -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/starter-game/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    resolve: {
+        // Ensure a single React instance is used across the project and
+        // file:// SDK dependency, preventing "Invalid hook call" errors.
+        dedupe: ['react', 'react-dom'],
+    },
+    test: {
+        environment: 'jsdom',
+        setupFiles: ['./test-setup.ts'],
+        // Exclude engine tests (node env, separate config) and Playwright specs
+        exclude: ['testing/**', '**/node_modules/**'],
+    },
+});

package/dist/templates/starter-game/vitest.engine.config.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from 'url';
+
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    resolve: {
+        alias: {
+            // Point the client subpath to source in development (dist doesn't exist until built)
+            '@seriousgaming/sdk-tools/client': fileURLToPath(
+                new URL('../../sdk-tools/cli/client/index.ts', import.meta.url)
+            ),
+        },
+    },
+    test: {
+        environment: 'node',
+        testTimeout: 60_000,
+        include: ['testing/engine/**/*.engine.test.ts'],
+    },
+});

package/dist/templates/starter-game/waiting_room/defaults.ts

@@ -0,0 +1,40 @@
+// This file is auto-generated from the schemas the resource declares: the values
+// a session starts with, for use as test fixtures.
+// Do not edit this file directly. It will be regenerated on build.
+
+import type { Context, Settings } from './types';
+
+export const defaultContext: Context = {
+    roles: {
+        LooksAfter: {},
+    },
+    briefing: {
+        Message: '',
+    },
+};
+
+export const defaultSettings: Settings = {
+    menu: {
+        Capacity: 120,
+        Menu: {
+            lemonade: {
+                Name: 'Lemonade',
+                Order: 1,
+                Cost: 15,
+                Price: 50,
+            },
+            icedtea: {
+                Name: 'Iced tea',
+                Order: 2,
+                Cost: 20,
+                Price: 60,
+            },
+            cookies: {
+                Name: 'Cookies',
+                Order: 3,
+                Cost: 25,
+                Price: 70,
+            },
+        },
+    },
+};

package/dist/templates/starter-game/waiting_room/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Lemonade Stand</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="./src/main.tsx"></script>
+    </body>
+</html>