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

package/dist/docs/guides/speech-generation.md

@@ -0,0 +1,233 @@
+# Speech generation guide
+
+The SDK exposes a provider-agnostic text-to-speech callback, `generateSpeech`. Engines, hooks, tick controllers, and endpoints can synthesise audio without knowing which provider executes the call. User interfaces reach it through an endpoint. The audio is persisted as a blob, so the same artefact can be played from a UI or analysed in an engine.
+
+The dev server ships with one provider adapter (ElevenLabs). Additional providers (OpenAI, Google Cloud, Azure, AWS Polly) will land behind a future `TTS_PROVIDER` env var without breaking changes to game code.
+
+## Table of contents
+
+- [Overview](#overview)
+- [Configuration](#configuration)
+- [Voice presets](#voice-presets)
+- [Tiers](#tiers)
+- [Using generateSpeech in the engine, hooks, and tick controllers](#using-generatespeech-in-the-engine-hooks-and-tick-controllers)
+- [Using generateSpeech in user interfaces](#using-generatespeech-in-user-interfaces)
+- [Request and response shape](#request-and-response-shape)
+- [Limitations](#limitations)
+
+## Overview
+
+`generateSpeech` accepts either a bare string or a request object, mirroring `generateText`:
+
+```typescript
+await callbacks.generateSpeech('Welcome to the simulation.');
+await callbacks.generateSpeech({ text: '...', voice: 'narrator' });
+```
+
+It returns a `blob:<id>` asset reference in `reference`, a MIME type, and best-effort observability fields (`durationMs`, `charactersBilled`). Game code only ever passes role-based voice presets like `'narrator'` or `'announcer'`; the runtime maps each preset to a concrete provider voice.
+
+The callback is exposed to the engine, hooks, tick controllers, and endpoints. Every such resource gates calls through the standard `uses` declaration, so the bundle must list `'generateSpeech'` in `uses`. User interfaces cannot call `generateSpeech` directly; they reach it through an endpoint that declares the callback and returns the audio blob reference.
+
+### Plain text only
+
+`text` is read verbatim by the provider. Passing markdown (e.g. an LLM-generated report) causes the TTS engine to read out hashes, asterisks, and bullet characters. Strip the formatting first:
+
+```typescript
+const audio = await callbacks.generateSpeech({
+    text: stripMarkdown(report.content),
+    voice: 'narrator',
+});
+```
+
+A small inline stripper covering headings, emphasis, lists, links, and code is enough for most cases:
+
+````typescript
+export function stripMarkdown(input: string): string {
+    return input
+        .replace(/```[\s\S]*?```/g, '') // code fences
+        .replace(/^[ \t]*[-*_]{3,}[ \t]*$/gm, '') // horizontal rules
+        .replace(/^[ \t]{0,3}#{1,6}[ \t]+/gm, '') // heading markers
+        .replace(/^[ \t]{0,3}>[ \t]?/gm, '') // blockquote markers
+        .replace(/^[ \t]*[-*+][ \t]+/gm, '') // bullets
+        .replace(/^[ \t]*\d+\.[ \t]+/gm, '') // numbered items
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1') // images, to their alt text
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // links, to their text
+        .replace(/(\*\*|__)(.*?)\1/g, '$2') // bold
+        .replace(/(\*|_)(.*?)\1/g, '$2') // italic
+        .replace(/`([^`]+)`/g, '$1') // inline code
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+````
+
+SSML and provider-specific markup are out of scope (see [Limitations](#limitations)).
+
+## Configuration
+
+The dev server's v1 adapter is ElevenLabs. Operators configure it via environment variables. Models fall back along the tier chain (`expert` → `standard` → `quick`) and voice presets fall back to `neutral`, then to the provider's own default voice.
+
+```
+ELEVENLABS_API_KEY=...
+TTS_MODEL_QUICK=eleven_flash_v2_5            # Optional
+TTS_MODEL_STANDARD=eleven_turbo_v2_5         # Optional, falls back to quick
+TTS_MODEL_EXPERT=eleven_multilingual_v2      # Optional, falls back to standard
+TTS_VOICE_NEUTRAL=<voice-id>                 # Optional, falls back to ElevenLabs default
+TTS_VOICE_NARRATOR=<voice-id>                # Optional, falls back to neutral
+TTS_VOICE_ANNOUNCER=<voice-id>               # Optional, falls back to neutral
+TTS_VOICE_EXECUTIVE=<voice-id>               # Optional, falls back to neutral
+TTS_VOICE_COACH=<voice-id>                   # Optional, falls back to neutral
+```
+
+Browse and copy voice IDs from <https://elevenlabs.io/voices>. Any voice ID accepted by ElevenLabs works.
+
+Calling `generateSpeech` without `ELEVENLABS_API_KEY` set throws a `TtsClientError` with a configuration message. This matches the fail-at-call-time behaviour of `generateText`.
+
+Production runtimes are free to resolve provider, model, and voice mappings however they like (config files, admin UI, per-tenant settings); the SDK contract is just the callback signature and the preset name convention.
+
+## Voice presets
+
+The five recommended presets cover most simulation needs:
+
+| Preset      | Tone                               | Pace           | Formality       |
+| ----------- | ---------------------------------- | -------------- | --------------- |
+| `neutral`   | Warm, balanced, unobtrusive        | Medium         | Mid             |
+| `narrator`  | Engaging, gravitas, draws listener | Measured       | Mid-formal      |
+| `announcer` | Clear, authoritative, broadcast    | Crisp          | Formal          |
+| `executive` | Confident, weighty, commands focus | Measured       | Formal          |
+| `coach`     | Encouraging, warm, reassuring      | Conversational | Informal to mid |
+
+Games may pass any preset name; unknown presets fall back to `neutral`. Operators free-text-map each preset to a concrete provider voice through the env vars above.
+
+## Tiers
+
+`tier` works the same way it does for `generateText`. The default is `'quick'`. The runtime maps each tier to a provider model; missing tiers fall back toward `quick`.
+
+```typescript
+await callbacks.generateSpeech({ text: '...', tier: 'standard' });
+await callbacks.generateSpeech({ text: '...', tier: 'expert' });
+```
+
+For ElevenLabs, the defaults are `eleven_flash_v2_5` (quick), `eleven_turbo_v2_5` (standard), and `eleven_multilingual_v2` (expert).
+
+## Using generateSpeech in the engine, hooks, and tick controllers
+
+1. Declare the API in the resource's bundle:
+
+    ```json
+    {
+        "definition": {
+            "reads": ["briefing"],
+            "writes": ["briefing"],
+            "uses": ["generateSpeech"]
+        },
+        "logic": { "directory": "logic", "entrypoint": "logic.ts" },
+        "rootDirectory": "."
+    }
+    ```
+
+2. Run `pnpm run sdk generate` so the per-resource `types.ts` narrows the `Callbacks` alias.
+3. Call the callback from `Init` or `Run`:
+
+    ```typescript
+    import type { RunFunction } from '@seriousgaming/sdk';
+    import type { Context, Settings, Callbacks } from '../types';
+
+    export const Run: RunFunction<Context, Settings, Callbacks> = async ({
+        context,
+        callbacks,
+    }) => {
+        // Declared in `uses`, so present: a runtime without speech refuses the
+        // package at load rather than leaving this undefined.
+        const audio = await callbacks.generateSpeech({
+            text: 'Welcome to round two. Let us begin.',
+            voice: 'narrator',
+            tier: 'standard',
+        });
+        return {
+            capabilities: {
+                ...context,
+                briefing: {
+                    ...context.briefing,
+                    audioRef: audio.reference,
+                },
+            },
+        };
+    };
+    ```
+
+A UI reading `audioRef` can play the audio with `<audio src={callbacks.getAssetUrl(audioRef)} controls />`. See [Asset references](./file-handling.md#asset-references) for the full scheme.
+
+## Using generateSpeech in user interfaces
+
+User interfaces cannot call `generateSpeech` directly. Declare an [endpoint](../recipes/create-endpoint.md) that wraps the callback and returns the blob reference, then invoke it from the UI and resolve the reference with `getAssetUrl`.
+
+The endpoint bundle declares `'generateSpeech'` in its `uses`:
+
+```typescript
+// endpoints/narrate/logic/logic.ts
+import type { Handler } from '../types';
+
+export const Handle: Handler = async ({ request, callbacks }) => {
+    const audio = await callbacks.generateSpeech({
+        text: request.text,
+        voice: 'announcer',
+    });
+    return { audioRef: audio.reference };
+};
+```
+
+The UI declares the endpoint in its `endpoints` array, calls it, and plays the returned blob:
+
+```tsx
+const { getAssetUrl, endpoints } = useUserInterfaceCallbacks() as Callbacks;
+const [audioUrl, setAudioUrl] = useState<string | undefined>();
+
+const handleNarrate = async () => {
+    const { audioRef } = await endpoints['narrate']({ text: 'Time is up.' });
+    setAudioUrl(getAssetUrl(audioRef));
+};
+
+return audioUrl ? <audio src={audioUrl} autoPlay /> : <button onClick={handleNarrate}>Play</button>;
+```
+
+`getAssetUrl` stays available to UIs: it is runtime plumbing and is not gated by `uses`. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
+
+## Request and response shape
+
+```typescript
+type GenerateSpeechRequest = {
+    text: string;
+    voice?: string; // preset name; defaults to 'neutral'
+    tier?: 'quick' | 'standard' | 'expert'; // matches generateText
+    format?: 'mp3' | 'wav' | 'opus'; // default 'mp3'
+    languageHint?: string; // BCP-47, advisory
+    speed?: number; // 0.5 to 2.0, clamped per provider
+};
+
+type GenerateSpeechResponse = {
+    reference: string; // 'blob:abc123'; resolve via getAssetUrl or readAsset
+    mimeType: string; // e.g. 'audio/mpeg'
+    durationMs?: number; // best-effort
+    charactersBilled?: number; // observability
+};
+```
+
+## Limitations
+
+v1 is intentionally minimal so the API stays stable as providers come and go. The following are deliberately out of scope and may land later as non-breaking additions:
+
+- SSML and provider-specific markup
+- Style and emotion tags
+- Pitch and volume gain
+- Deterministic seed
+- Sample-rate control
+- Streaming responses
+- Multi-voice dialogue input
+
+## Related
+
+- [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses) - the safety boundary mental model
+- [Declare API uses](../recipes/declare-api-uses.md) - step-by-step declaration recipe
+- [LLM integration](llm-integration.md) - the companion `generateText` callback
+- [File handling](file-handling.md) - the unified `asset:` / `blob:` scheme for files
+- [Environment variables](../environment-variables.md) - full env-var reference

package/dist/docs/guides/starter-game.md

@@ -0,0 +1,164 @@
+# A tour of the starter game
+
+`new package` hands you Lemonade Stand, a complete game rather than an empty shell. This page walks through every directory and file it writes, says what each one does, and points at the guide that goes deeper.
+
+**Keywords:** starter game, lemonade stand, package layout, directory structure, scaffold, tour, what new package creates
+
+The game is the one the SDK's own test suites play, copied out whole. A team runs a lemonade stand for 10 days: each morning they choose how many lemonades, iced teas, and cookies to make, and the engine plays out the day against the weather. For how to play it and make a first change, see [Getting started](../getting-started.md).
+
+## The shape worth keeping
+
+Most of the starter game is ordinary, but four decisions in it are the ones a first game usually gets wrong. Keep them when you replace the model:
+
+- **State keyed so participants cannot overwrite each other.** `plan.Make` is keyed by menu item, and a hook puts each participant in charge of one item, so two people changing two numbers write two different keys
+- **A validator on the one thing they share.** Two changes can each fit while the merged plan busts the stall's capacity. No shape of state prevents that, so `validators/capacity` checks the merged result
+- **Every write awaited.** The game UI reports a refused write to the participant who made it, instead of showing a decision the game never received
+- **Teams run their own days.** The game is in independent mode: each team opens its stall when it is ready, and the facilitator watches and can undo
+
+[Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) explains the first two in full.
+
+## The manifest
+
+### `seriousgaming.sdk.json`
+
+The game itself, as one flat object: the package identifier, the locales and the game's name, `maxTicks: 10`, the team rules, the waiting room setting, and the scenario format. The game's own values are the defaults of its settings resources, not overrides here.
+
+- `teams.mode: "independent"` with one to eight teams of two to five participants
+- `waitingRoom.openOnStart: true`, so participants are held in the waiting room until the facilitator lets them in
+- `scenarioFormat: 1`, and no `customScenarios`, so a hosted runtime offers only the game's own scenarios. Facilitators saving scenarios of their own is a decision to make deliberately: add `customScenarios: { "supported": true }` when you want it, and bump `scenarioFormat` when a release changes what a setting means (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it)). The game has no scenario editor, so a runtime's generic form, or an AI agent, would author them from the settings schemas
+
+See [Shaping games](./games.md).
+
+## Capabilities
+
+### `capabilities/`
+
+Each directory is one capability, a named slice of the game's state with a JSON Schema for its variables. There is no logic here.
+
+| Capability | Holds                                                                                                                 |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| `plan`     | How many of each item to make today, keyed by item. The one capability participants write                             |
+| `weather`  | Today's forecast and roughly how many people will want each item                                                      |
+| `results`  | What happened yesterday, item by item, and the money: takings, spending, profit, and the running total in the jar     |
+| `roles`    | Which item each participant looks after, keyed by participant id                                                      |
+| `briefing` | A note from the facilitator shown on every team's screen. `shared` scope, so there is one value for the whole session |
+
+See [Capabilities](./capabilities.md).
+
+## Settings
+
+### `settings/`
+
+Each directory is one settings resource: read-only parameters, every one with a default, which a scenario or the facilitator can override before play starts. A resource reads the ones it lists in its own `settings`. Every property has a `title`, a `description` with its units, a range, and an `enum` where the choices are closed (`CurrencySymbol`), because those schemas are all a scenario author without an editor has to go on.
+
+| Settings  | Holds                                                                                                                                               | Read by                                                |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `menu`    | `Capacity` (120) and the `Menu`, each item's name, cost, and price                                                                                  | The engine, every surface, the hook, and the validator |
+| `engine`  | `UsualDemand` for each item, `SunnyPull`, `RainyPull`, and `Variation`. Only the engine reads it, so no participant's browser ever holds the demand | The engine                                             |
+| `ui`      | `Step` and `CurrencySymbol`                                                                                                                         | The game UI                                            |
+| `session` | `ShowJoinLinks` and `CurrencySymbol`                                                                                                                | The session UI                                         |
+
+See [Settings](./settings.md).
+
+## Logic
+
+### `engine/`
+
+The one engine, which plays a day each tick.
+
+- `engine.sdk.json`: what the engine reads and writes, and `"settings": ["menu", "engine"]`, the settings it plays with
+- `logic.ts`: `Init` sets a provisional plan and forecasts day one; `Run` plays the day, charges for everything made, and forecasts tomorrow. Weather and demand are derived from the session seed, so a day always plays out the same way
+- `logic.test.ts`: unit tests for one day's arithmetic
+- `test-helpers.ts`: starting fixtures the tests spread over
+- `types.ts` and `defaults.ts`: generated from the schemas. Do not edit them; `sdk generate`, `new`, and `update` rewrite them
+
+See [Creating engines](./engine.md) and [Testing](./testing.md).
+
+### `hooks/assignproducts/`
+
+A hook on the `participantJoin` signal. When a participant joins a team, it reads the `menu` settings and writes into `roles` which menu item they look after, so participants normally change different keys. Its logic is in `logic/logic.ts`, with tests beside it.
+
+See [Hooks](./hooks.md).
+
+### `validators/capacity/`
+
+A validator that sees every change a UI makes to the plan before it is applied. It reads the `menu` settings, and refuses a plan that asks for more than the stall's capacity, a negative or fractional count, or an item not on the menu. It never changes state; it only says no, with a message the game UI shows.
+
+See [Validators](./validators.md).
+
+## User interfaces
+
+Each is a small React app built with Vite and MUI, with its own `index.html`, `src/main.tsx` (the SDK wrapper, locale, and right-to-left set-up), `src/theme.ts` (typography over the host's palette), and `src/i18n.ts` (every string on the screen).
+
+### `ui/`
+
+The game UI: what each participant sees.
+
+- `src/App.tsx`: the layout, the facilitator's notice, and the one place a refused write is reported
+- `src/TodayPanel.tsx` and `src/MakeRow.tsx`: the controls for today's plan, one row per item, with the participant's own item marked
+- `src/DayBar.tsx`: the **Open the stall** button, which calls `requestTick` to play the team's day
+- `src/YesterdayPanel.tsx` and `src/HistoryPanel.tsx`: how yesterday went, and every day so far. The history table asks the host for the earlier days with `getPastState` and adds today's from live context, so nothing in context grows as the days go by (see [Review a past day in a UI](../recipes/review-a-past-day.md))
+- `src/writes.ts`: one mutation reporter every write goes through
+- `src/menu.ts`, `src/format.ts`, `src/Section.tsx`, `src/ThemeToggle.tsx`: menu ordering, money formatting, the card layout, and a light or dark switch
+- `ui.sdk.json`: reads every capability it shows, writes only `plan`, and reads the `ui` settings (`Step` and `CurrencySymbol`)
+
+See [Building user interfaces](./ui.md).
+
+### `session/`
+
+The session UI: the facilitator's whole screen, which the dev server shows at `/` as the console. It shows what each stall is making and whether anyone has changed it today, links into any stall to observe or join it (`src/TeamDoor.tsx`), writes the shared `briefing`, and toggles the waiting room and the facilitator guide through the host. `ShowJoinLinks`, in the `session` settings it reads, turns the per-team join and observe links off.
+
+See [Building session UIs](./session.md).
+
+### `waiting_room/`
+
+The screen participants see while the session is held. It tells a held start ('Nearly opening time') from a pause part-way through, shows who is on the team, and lets the team name its stall.
+
+See [Building waiting room UIs](./waiting-room.md).
+
+## Content
+
+### `scenarios/`
+
+Two variants of the game, each a `scenario.sdk.json`:
+
+- `ordinary_week`: 10 days of mixed weather, marked `default`, so a session starts on it
+- `heatwave`: five days with the `engine` settings' `SunnyPull` and `RainyPull` raised, so the queue is longer than the stall can serve
+
+See [Scenarios](./scenarios.md).
+
+### `guide/`
+
+The facilitator guide: three markdown chapters under `content/en/` (at a glance, preparation, running the day), rendered on the facilitator's page. `guide.test.ts` checks the structure the host relies on.
+
+See [Facilitator guides](./guide.md).
+
+## Tests
+
+### `testing/engine/`
+
+Whole-game tests that play several days in-process with `createTestSession`: no server, no browser. Run them with `pnpm test:engine`. See [Engine testing](./engine-testing.md).
+
+### `testing/e2e/`
+
+Playwright tests against a real dev server, which `testing/e2e/global-setup.ts` starts on free ports, beside any you have running. Run them with `pnpm test:e2e`. See [Test UIs end to end with Playwright](../recipes/e2e-testing.md).
+
+The unit and component tests sit beside the code they test (`*.test.ts`, `*.test.tsx`) and run with `pnpm test:run`.
+
+## Package files
+
+These are written by `new package` for every package, starter game or not:
+
+| File                                                  | What it is for                                                                                                                          |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `package.json`                                        | Dependencies, and the scripts: `sdk`, `generate`, `build`, `test:run`, `test:engine`, `test:e2e`, `typecheck`, `lint`                   |
+| `tsconfig.json`, `globals.d.ts`                       | TypeScript settings, and declarations for the font imports                                                                              |
+| `vite.config.ts`, `vitest.config.ts`, `test-setup.ts` | Build and component-test settings, including the single copy of React and the SDK every UI needs                                        |
+| `vitest.engine.config.ts`, `playwright.config.ts`     | Settings for the whole-game and browser test suites, and `testing/e2e/global-setup.ts`, which starts the browser suite's server         |
+| `pnpm-workspace.yaml`                                 | Dependency overrides and install-script decisions the SDK tooling needs                                                                 |
+| `.oxlintrc.json`, `.oxfmtrc.json`                     | Lint and format settings                                                                                                                |
+| `README.md`, `DESIGN.md`                              | A readme, and prompts for writing down your game's design as you build it                                                               |
+| `CLAUDE.md`, `.claude/`                               | Guidance and permissions for an AI coding agent working in the package                                                                  |
+| `.gitignore`                                          | Keeps `dist/`, `node_modules/`, `.seriousgaming-sdk/`, and Playwright's `test-results/` and `playwright-report/` out of version control |
+
+Two directories appear once you use the package. `dist/` is what `sdk build` writes. `.seriousgaming-sdk/` holds the dev server's lock file (`session.json`) and the session overrides `sdk configure` writes (`configuration.json`); the session itself lives only in the dev server's memory.