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

package/dist/docs/guides/patterns.md

@@ -0,0 +1,391 @@
+# Common patterns
+
+Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern. The second builds on the first; the third stands alone.
+
+For the shape of a whole game, start from the starter game `new package` gives you: [A tour of the starter game](./starter-game.md) walks through it, and [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) states the rules it follows on their own.
+
+## Table of contents
+
+- [Basic inventory system](#basic-inventory-system)
+- [Pricing and revenue](#pricing-and-revenue)
+- [Complex state management](#complex-state-management)
+
+## Basic inventory system
+
+A simple system that tracks stock and prevents negative inventory.
+
+**Capability:**
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "inventory",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Stock": { "type": "number", "default": 100, "minimum": 0 },
+        "ReorderPoint": { "type": "number", "default": 20 }
+      },
+      "required": ["Stock", "ReorderPoint"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+**Engine:**
+
+A game holds one engine, in `engine/`, so it carries no identifier of its own. Its parameters go in a settings resource it lists in `settings`:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "engine",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "DailySales": { "type": "number", "default": 5 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+
+pnpm run sdk new engine '{
+  "definition": {
+    "writes": ["inventory"],
+    "settings": ["engine"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+**Logic** (`engine/logic.ts`)**:**
+
+```typescript
+import { RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    let { Stock } = context.inventory;
+
+    // Reduce stock
+    Stock -= settings.engine.DailySales;
+
+    // Prevent negative stock
+    if (Stock < 0) {
+        Stock = 0;
+    }
+
+    return {
+        capabilities: {
+            ...context,
+            inventory: {
+                ...context.inventory,
+                Stock,
+            },
+        },
+    };
+};
+```
+
+## Pricing and revenue
+
+Calculate revenue based on inventory and pricing.
+
+**Capabilities:**
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "pricing",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Price": { "type": "number", "default": 0 },
+        "PriceHistory": { "type": "array", "default": [] }
+      },
+      "required": ["Price", "PriceHistory"],
+      "additionalProperties": false
+    }
+  }
+}'
+
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "revenue",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "TotalRevenue": { "type": "number", "default": 0 },
+        "ThisTickRevenue": { "type": "number", "default": 0 }
+      },
+      "required": ["TotalRevenue", "ThisTickRevenue"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+**Engine:**
+
+There is no second engine to create: revenue is another step of the one engine the game already holds. Add the conversion rate to its settings, and update its declarations so it reads the new capabilities and writes `revenue`:
+
+```bash
+pnpm run sdk update settings engine '{
+  "definition": {
+    "identifier": "engine",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "DailySales": { "type": "number", "default": 5 },
+        "ConversionRate": { "type": "number", "default": 0.8 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+
+pnpm run sdk update engine '{
+  "definition": {
+    "reads": ["pricing"],
+    "writes": ["inventory", "revenue"],
+    "settings": ["engine"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+**Logic:** move the stock calculation into a step file of its own, add the revenue step beside it, and let `logic.ts` call them in order.
+
+`engine/inventory.ts`:
+
+```typescript
+import type { StepFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const runInventory: StepFunction<Context, Settings> = async ({ context, settings }) => {
+    const Stock = Math.max(0, context.inventory.Stock - settings.engine.DailySales);
+
+    return {
+        ...context,
+        inventory: {
+            ...context.inventory,
+            Stock,
+        },
+    };
+};
+```
+
+`engine/sales.ts`:
+
+```typescript
+import type { StepFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const runSales: StepFunction<Context, Settings> = async ({ context, settings }) => {
+    const { Stock } = context.inventory;
+    const { Price } = context.pricing;
+    const { TotalRevenue } = context.revenue;
+
+    // Calculate potential sales
+    const potentialSales = Stock * Price;
+
+    // Apply conversion rate
+    const actualRevenue = potentialSales * settings.engine.ConversionRate;
+
+    return {
+        ...context,
+        revenue: {
+            ...context.revenue,
+            TotalRevenue: TotalRevenue + actualRevenue,
+            ThisTickRevenue: actualRevenue,
+        },
+    };
+};
+```
+
+`engine/logic.ts`:
+
+```typescript
+import { RunFunction } from '@seriousgaming/sdk';
+import { runInventory } from './inventory';
+import { runSales } from './sales';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async (args) => {
+    let context = args.context;
+    context = await runInventory({ ...args, context });
+    context = await runSales({ ...args, context });
+    return { capabilities: context };
+};
+```
+
+Each step is a `StepFunction`: it takes the context the previous one returned and returns the next one, flat, so the order of the calls is the order the simulation runs in, visible in one place. Only the exported `Run` wraps the final context in `{ capabilities }`.
+
+## Complex state management
+
+Managing state across several steps of one engine.
+
+**Scenario:** a production system that tracks demand, production, and costs.
+
+**Capabilities:**
+
+```bash
+# Demand capability
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "demand",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "CurrentDemand": { "type": "number", "default": 0 },
+        "DemandHistory": { "type": "array", "default": [] }
+      },
+      "required": ["CurrentDemand", "DemandHistory"],
+      "additionalProperties": false
+    }
+  }
+}'
+
+# Production capability
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "production",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "ProductionRate": { "type": "number", "default": 10 },
+        "TotalProduced": { "type": "number", "default": 0 }
+      },
+      "required": ["ProductionRate", "TotalProduced"],
+      "additionalProperties": false
+    }
+  }
+}'
+
+# Costs capability
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "costs",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "ProductionCost": { "type": "number", "default": 5 },
+        "TotalCosts": { "type": "number", "default": 0 }
+      },
+      "required": ["ProductionCost", "TotalCosts"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+The steps below read `BaseDemand`, `DemandVariance`, and `ProductionCost` from `settings/engine/`.
+
+**Demand step** (`engine/demand.ts`)**:**
+
+```typescript
+export const runDemand: StepFunction<Context, Settings> = async ({ context, settings }) => {
+    let demand = settings.engine.BaseDemand;
+
+    // Demand varies by sine wave for realistic pattern
+    const tick = context.demand.DemandHistory.length;
+    demand += Math.sin(tick * 0.5) * settings.engine.DemandVariance;
+    demand = Math.max(0, demand);
+
+    return {
+        ...context,
+        demand: {
+            ...context.demand,
+            CurrentDemand: demand,
+            DemandHistory: [...context.demand.DemandHistory, demand],
+        },
+    };
+};
+```
+
+**Production step** (`engine/production.ts`)**:**
+
+```typescript
+export const runProduction: StepFunction<Context, Settings> = async ({ context, settings }) => {
+    const { CurrentDemand } = context.demand;
+    const { ProductionRate, TotalProduced } = context.production;
+
+    // Adjust production based on demand
+    let adjustedProduction = ProductionRate;
+    if (CurrentDemand > ProductionRate) {
+        adjustedProduction = ProductionRate * 1.1; // Increase by 10%
+    }
+
+    return {
+        ...context,
+        production: {
+            ...context.production,
+            ProductionRate: adjustedProduction,
+            TotalProduced: TotalProduced + adjustedProduction,
+        },
+    };
+};
+```
+
+**Costs step** (`engine/costs.ts`)**:**
+
+```typescript
+export const runCosts: StepFunction<Context, Settings> = async ({ context, settings }) => {
+    const { ProductionRate } = context.production;
+    const { TotalCosts } = context.costs;
+
+    const costThisTick = ProductionRate * settings.engine.ProductionCost;
+
+    return {
+        ...context,
+        costs: {
+            ...context.costs,
+            ProductionCost: settings.engine.ProductionCost,
+            TotalCosts: TotalCosts + costThisTick,
+        },
+    };
+};
+```
+
+**Ordering** (`engine/logic.ts`)**:**
+
+```typescript
+import { RunFunction } from '@seriousgaming/sdk';
+import { runCosts } from './costs';
+import { runDemand } from './demand';
+import { runProduction } from './production';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async (args) => {
+    let context = args.context;
+    context = await runDemand({ ...args, context });
+    context = await runProduction({ ...args, context });
+    context = await runCosts({ ...args, context });
+    return { capabilities: context };
+};
+```
+
+## Best practices summary
+
+1. **Separate concerns**: one step per responsibility
+2. **Clear dependencies**: declare what you need explicitly
+3. **Immutable updates**: always use spread operators
+4. **Type safety**: use generated types
+5. **Test logic**: write unit tests
+6. **Document code**: comments for non-obvious logic
+
+## Next steps
+
+- [Creating engines](./engine.md): the reference for `Init`, `Run`, steps and the engine's private state
+- [Creating capabilities](./capabilities.md): scopes, lifetimes and typing a capability's variables
+- [Engine testing](./engine-testing.md): play a few ticks of a pattern in-process before building a UI on it

package/dist/docs/guides/presentation.md

@@ -0,0 +1,196 @@
+# Building presentations
+
+Ship the facilitator's slide deck as part of the game: an introduction, the briefing, a divider before each block of rounds, the debriefs and the results, localised, aware of the scenario, live with the session's results, and exportable for anyone who wants to take it away and edit it.
+
+**Keywords:** presentation, slides, slide deck, deck, briefing, debrief, results, PowerPoint, PDF, PNG, export, usePresentation, PresentationWrapper, @seriousgaming/deck, Deck, Slide, Step
+
+## What you'll learn
+
+- What a presentation is, and what a runtime does with it
+- How a deck reads the game and the session, and why `session` can be `null`
+- How to build slides with `Deck`, `Slide`, `Step` and the building blocks
+- How a deck remembers where the facilitator was
+- What export produces, and the habits that keep an export faithful
+
+## What is a presentation?
+
+A presentation is the slides a facilitator shows the room. A game holds at most one, in the `presentation/` slot. It is an ordinary UI bundle of the game's own, so the runtime renders it without knowing what a slide is: navigation, animation, layout and export all happen inside the frame.
+
+Every runtime offers it, so a game can rely on its deck being there for the briefing and the debrief. Three things set it apart from the other surfaces:
+
+- **Read-only.** It declares `reads` and `settings`, and no `writes`, `uses` or `endpoints`. The host refuses anything it sends except a read of past rounds
+- **Facilitator only.** It is never shown on a participant's or an observer's device. The room sees it because the facilitator shares or projects their screen
+- **Shown with or without a session.** It is the one surface a runtime shows with no session at all: from a game's page in a library, while a facilitator rehearses, or to export it before the day
+
+## Creating one
+
+```bash
+pnpm run sdk new presentation '{
+  "definition": {
+    "reads": ["results"],
+    "settings": ["engine"]
+  },
+  "rootDirectory": ".",
+  "ui": {
+    "entrypoint": "index.html"
+  }
+}'
+```
+
+The slot is the presentation's identifier, so `update presentation` and `delete presentation` take none. The scaffold depends on `@seriousgaming/deck`, the SDK's deck library, which a newly scaffolded package already lists. See [Create a presentation](../recipes/create-presentation.md) for the step-by-step version.
+
+The deck library is optional. A presentation is a UI bundle like any other, rendered under `PresentationWrapper`, so a deck written with another library, or none, works the same way. The rest of this guide assumes the SDK's own.
+
+## Reading the game and the session
+
+`usePresentation()` gives a deck everything it can see:
+
+```tsx
+import { usePresentation } from '@seriousgaming/sdk/ui';
+
+import type { Settings, SharedContext, TeamContext } from '../types';
+
+const { game, session, settings, theme, locale, getPastState, getAssetUrl } = usePresentation<
+    Settings,
+    TeamContext,
+    SharedContext
+>();
+```
+
+| Field          | What it holds                                                                                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `game`         | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
+| `session`      | `null` with no session. Otherwise its `id`, `name`, `tick` (the highest any team has reached), `data` (the shared store and every team, narrowed to `reads`) and `teams`   |
+| `settings`     | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one                                                         |
+| `theme`        | The host's theme, to map onto the deck's colours                                                                                                                           |
+| `locale`       | The locale to render in                                                                                                                                                    |
+| `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session                                                         |
+| `getAssetUrl`  | Turns an `asset:`, `shared:` or `blob:` reference into a URL                                                                                                               |
+
+A presentation sees every team: it is the facilitator's view of the room.
+
+The shared hooks work in a deck too: `useAssetUrl` and `useAsset` for assets, and `usePastState` in place of calling `getPastState` from an effect (it rejects into `error` when there is no session). `PresentationWrapper` sets the document's `lang`, `dir` and `color-scheme` from the locale and theme, as every wrapper does.
+
+### When `session` is `null`
+
+A deck must render with `session: null`. Wherever a slide would show results, show sample or placeholder figures, and label them as such on the slide so nobody mistakes them for the room's own. One hook that returns either the session's figures or a sample set flagged `live: false` keeps the branch in one place, and each results slide adds a note when `live` is false:
+
+```typescript
+export function useResults(): Results {
+    const { session } = usePresentation<Settings, TeamContext>();
+    if (!session || session.completedTicks < 1) return SAMPLE; // { live: false, ... }
+    return {
+        live: true,
+        teams: session.teams.map((team) => ({
+            name: team.name,
+            profit: session.data.teams[team.teamId]?.context.profit?.Profit ?? 0,
+        })),
+    };
+}
+```
+
+### Varying by scenario
+
+Branch on settings, scenario assets and `game.maxTicks`, never on `game.scenarioName`. A facilitator who saves their own scenario from one of yours gets a new identity, so a deck that branched on the name would show the wrong slides to exactly the facilitators who customised. `scenarioName` is for display.
+
+## Slides
+
+```tsx
+import { Bullets, Deck, Heading, Slide, Step, Text } from '@seriousgaming/deck';
+
+<Deck
+    title={game.name}
+    lang={locale.locale}
+    rememberAs={session ? `session:${session.id}` : 'rehearsal'}
+>
+    <Slide key="title">
+        <Heading level={1}>{game.name}</Heading>
+    </Slide>
+    <Slide key="agenda" transition="slide" notes="Reveal each point in turn.">
+        <Heading>{t('agendaHeading')}</Heading>
+        <Bullets stepped items={[t('intro'), t('play'), t('review')]} />
+        <Step at={4} animation="zoom">
+            <Text>{t('letsBegin')}</Text>
+        </Step>
+    </Slide>
+</Deck>;
+```
+
+- **`Deck`** shows one slide at a time, scaled to fit. Every direct child is one slide (arrays and fragments are flattened), so a component of your own counts as a slide only if it renders a single `Slide`
+- **`Slide`** lays its content out on a fixed 1920 by 1080 canvas. Position things however you like inside it. It takes `transition` (`none`, `fade`, `slide`, `zoom` or `rise`; the deck's own `transition` by default), `notes`, `background` (any CSS background) and `id`
+- **`Step`** is content revealed by a click: `at={1}` for the first, `at={2}` for the second, and steps may share a number. A hidden step keeps its space, so a slide never reflows as it builds. Its `animation` is `fade`, `fade-up` (the default), `fade-left`, `zoom`, `blur` or `none`
+- **`useStepVisible(at)`** builds a custom animation with clicks without wrapping it in a `Step`
+
+The facilitator moves with the keyboard, a clicker, a click or a swipe. Right, down, space, page down and enter advance; left, up, page up and backspace go back; home and end jump; F toggles fullscreen and O the overview. In a right-to-left deck the arrows swap. Going back lands on the previous slide fully built.
+
+`Deck` also takes `dir`, `lang`, `brand` (the deck's colours and fonts), `controls` and `clickToAdvance` (both on by default), `exportFormats`, and `onSlideChange`.
+
+### Building blocks
+
+| Block     | Use it for                                                                          | In PowerPoint                                                              |
+| --------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `Heading` | A slide title, `level` 1 to 3                                                       | Editable text                                                              |
+| `Text`    | Body copy, with `variant` `body`, `lead` or `caption`                               | Editable text                                                              |
+| `Bullets` | A list, `ordered` or not, revealed one item per click with `stepped`                | An editable list                                                           |
+| `Table`   | `columns` and `rows`, with an `align` per column                                    | An editable table                                                          |
+| `Image`   | A picture. `fit="contain"` (the default) or `fit="cover"` to fill and crop          | A movable picture with `contain`; part of the slide's picture with `cover` |
+| `Chart`   | A `bar` or `line` chart from `categories` and `series`, drawn in the deck's colours | Part of the slide's picture                                                |
+
+Everything else on a slide, your own components included, exports as part of the slide's picture. To make your own element export as editable text, spread `nativeText` onto it: `<div {...nativeText}>...</div>`.
+
+### Colours
+
+The deck draws in its own `brand`, which a game maps from the host's theme in a line or two, so the slides pick up the same primary and secondary as every other surface:
+
+```tsx
+const brand = {
+    colors: {
+        ...defaultBrand.colors,
+        primary: theme.light.primary,
+        secondary: theme.light.secondary,
+    },
+};
+```
+
+Use the light palette whatever mode the facilitator's screen is in: slides are made to be projected, and a projector washes out a dark slide. `useBrand()` gives a custom component the resolved colours, and the CSS variables `--deck-primary`, `--deck-secondary` and `--deck-muted` reach anything inside a slide.
+
+## Coming back to where you were
+
+`rememberAs` keeps the facilitator's place in the browser's own storage, so a reload, a closed laptop lid or a break comes back to the same slide and step:
+
+```tsx
+<Deck rememberAs={session ? `session:${session.id}` : 'rehearsal'} startAt="title">
+```
+
+- Key it by session, so each session keeps its own place. `session.id` is stable for the session's life and unique to it
+- The deck remembers a slide by its name (its `id`, or its React `key`) and falls back to its number, so a slide that a setting adds or removes does not shift the facilitator onto the wrong one. Give every slide a key
+- `startAt` is where to open when nothing is remembered: a slide's name or number. Compute it from where the room has got to, for instance `startAt={session && session.completedTicks > 0 ? 'results' : 'title'}`
+
+The position lives in one browser on one device. A facilitator who moves to another laptop starts at `startAt`.
+
+## Export
+
+The controls offer the whole deck as a PDF (through the browser's print dialogue), as a PowerPoint file, and the current slide as a PNG. The browser's own print shortcut gives the same PDF. Every export renders each slide still and fully built.
+
+In PowerPoint, **words are editable and visuals are pictures**. Headings, text, bullets and tables become native objects a facilitator can edit, and `notes` land in the notes pane. Charts, custom components and anything else become part of the slide's picture, so the export always matches the screen. An export is the facilitator's own file once it is downloaded: nothing about the game changes, and the game itself is never edited in place.
+
+## Habits that keep an export faithful
+
+- **Use the building blocks for anything a facilitator might edit.** Text drawn by your own component exports as a picture
+- **Render with `session === null`.** Every slide makes sense with no session, and labels sample figures as samples
+- **Branch on settings, not the scenario name.** A facilitator's own scenario has a different name and the same settings
+- **Show finished visuals in static mode.** Print, export and the overview render each slide still. A custom animation reads `useSlide().mode` and draws its end state when it is `'static'`, as in `const shown = useStepVisible(1); const on = mode === 'static' || shown;`
+- **Route every word through i18n.** A deck is shown in the session's language. Set `lang` and `dir` on the `Deck` from `locale`
+- **One element per slide.** Every element in the array is a slide; a wrapper around several is one slide
+
+## Testing
+
+To see your deck, run `pnpm run sdk dev` and open `/presentation`, or `/presentation?preview` for the deck with no session.
+
+## Related
+
+- [Create a presentation](../recipes/create-presentation.md): the step-by-step version
+- [Building session UIs](./session.md): the facilitator's other surface
+- [Facilitator guides](./guide.md): the run sheet beside the deck
+- [Internationalisation (i18n)](./internationalization.md): translating the deck's words
+- [Scenarios](./scenarios.md): what a scenario can change, and so what a deck can vary on