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

package/dist/docs/guides/production-constraints.md

@@ -0,0 +1,130 @@
+# Production security constraints
+
+In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel. The dev server mirrors this policy, so a UI that works locally will work in production. This guide explains the constraints and the things to do and avoid so you never ship a UI that passes locally and breaks live.
+
+## What you'll learn
+
+- Why your UI is sandboxed in production and what that means in practice
+- What your UI is allowed to do inside its frame, and what it is not
+- The exact content security policy your bundle runs under
+- What to do and what to avoid when building UIs
+- How to recognise and fix the most common policy violations
+- The write, retry and logic rules that hold beyond the frame
+
+## The two-origin model
+
+The platform serves the app and your content from two separate domains:
+
+- App host (for example `businesssimulations.com`): the single-page app, the REST APIs, and the page that embeds your iframe
+- Asset host (a per-brand content domain, for example `assets.businesssimulations.com`): your bundle, scenario assets, and blobs
+
+Your iframe points at the asset host, so your code is cross-origin to the parent app. This cross-origin isolation is the primary sandbox: it keeps uploaded simulation code away from the main host's cookies and APIs. Access to your bundle is gated by a short-lived, automatically managed cookie, so your same-origin requests to the asset host just work without any credential handling on your part.
+
+## The content security policy
+
+Your bundle runs under this policy on the asset host:
+
+```
+default-src 'self'
+connect-src 'self'
+img-src 'self' data:
+media-src 'self' blob: data:
+font-src 'self' data:
+style-src 'self' 'unsafe-inline'
+script-src 'self' 'unsafe-inline'
+frame-src 'self' https://www.youtube.com https://www.youtube-nocookie.com
+form-action 'self'
+frame-ancestors *
+```
+
+The headline rule is `default-src 'self'`: everything your UI loads must be first-party to the asset host or bundled into your build. Inline scripts and styles are allowed, but external origins are not.
+
+## What your UI may do inside its frame
+
+The policy above governs what your UI can _load_. A second set of limits, set on the iframe itself, governs what it can _do_. These are fixed: there is nothing to declare in your bundle, and every UI type gets the same set.
+
+Your UI can:
+
+- Copy to the clipboard, so a 'copy join link' or 'copy your code' button works
+- Print, via `window.print()`
+- Offer downloads, so a results CSV or a team report reaches the participant
+- Go fullscreen
+- Play audio automatically, which is what makes generated speech playback work
+- Hold a screen wake lock, so a tablet does not sleep mid-session
+- Present to a second screen
+- Open an external link in a new tab, with `target="_blank" rel="noopener noreferrer"`. A `mailto:` or `tel:` link needs the same treatment: a bare one is blocked, because the surface itself cannot navigate to an external protocol handler
+- Ask the browser for the microphone, camera, or location. The participant still sees the browser's own permission prompt, so treat a refusal as a normal outcome and design a path through it
+- Use picture-in-picture, the Web Share sheet, a gamepad, multi-screen window placement, and speaker selection
+
+Your UI cannot:
+
+- Read the clipboard. Writing is allowed, reading is not
+- Navigate the top-level page away from the session. The page your surface sits in stays put, which is why an outbound link opens in a new tab rather than in place
+- Capture the screen, or detect whether the participant is idle
+- Reach USB, serial, HID, Bluetooth, or MIDI devices
+- Use the Payment Request API, WebAuthn, or any other credential API
+- Read motion, orientation, light, or pressure sensors, or enumerate local fonts
+- Submit a form to another origin. `form-action 'self'` confines submission to your own origin, just as `connect-src` confines `fetch`
+
+Nothing here needs declaring. If your UI needs something on the second list, it belongs in an endpoint or the engine, not in the frame.
+
+## Being granted a capability is not the same as having it
+
+The list above is what the host grants. What the browser on a participant's device actually implements is a separate question, and the two do not always meet:
+
+- Printing, downloads, fullscreen, and autoplay are broadly supported
+- Multi-screen window placement and speaker selection are Chromium-only
+- Clipboard writing is granted as a Permissions Policy feature in Chromium, while Safari and Firefox instead require the write to happen inside a user gesture
+
+The pattern that works everywhere is to call `navigator.clipboard.writeText()` directly inside a click handler, never after an `await` or in a timeout, and to feature-detect anything beyond the broadly supported four. Participants join on their own devices, iPads included, so treat an unsupported capability as a normal case and give the participant another way through.
+
+One thing to keep in mind about `alert()`, `confirm()`, and `prompt()`: they work, but they block the surface that raises one until it is dismissed. In a live facilitated session that is usually the wrong choice. Prefer an in-page dialog.
+
+## Content types are not sniffed
+
+Alongside the policy, the asset host sends `X-Content-Type-Options: nosniff` on every response. The browser will not guess an asset's type from its bytes: a script must arrive as JavaScript, a stylesheet as CSS. An asset served with a missing or wrong `Content-Type` is refused rather than loaded. The dev server mirrors this header too, so a build that leans on MIME sniffing fails on localhost instead of only in production.
+
+## What to do
+
+- Bundle every asset into your build so it resolves to `'self'`: fonts, icons, CSS, images, and scripts
+- Self-host fonts: import an `@fontsource` package, or drop `.woff2` files in your UI directory and reference them with a relative path. The example games use `@fontsource-variable/work-sans` and `@fontsource-variable/roboto-mono`, both bundled at build time
+- Use the `asset:`, `shared:`, and `blob:` scheme for files: it resolves to runtime-served URLs on the asset host (see [File handling](./file-handling.md))
+- Embed video through YouTube (standard or no-cookie); other frame sources are blocked
+- Route any outbound network call through an engine, an endpoint, or a host capability rather than fetching from the UI (see [LLM integration](./llm-integration.md) and [Endpoints](./endpoints.md))
+
+## What to avoid
+
+- Loading fonts, CSS, or scripts from a third-party CDN (Google Fonts, jsDelivr, unpkg). These are blocked: bundle them instead
+- Web workers created from a `blob:` URL. There is no `worker-src`, so a blob worker falls back to `script-src 'self' 'unsafe-inline'` and is blocked. Configure libraries that spin up workers (PDF.js, transformers.js, ONNX runtime, and others) to load a bundled worker file, or avoid them
+- `eval` and `new Function`: `unsafe-eval` is not granted, so runtime code evaluation fails
+- `fetch` or `XMLHttpRequest` to any third-party origin: `connect-src 'self'` allows the asset host only
+- Relying on CSP nonces or hashes: none are issued, so do not build around them
+
+## How the dev server helps
+
+The dev server serves your game UIs under the same policy, and sets the same limits on the iframe itself, so violations surface on localhost instead of in production. The single deliberate difference is `connect-src`, which is widened to allow the Vite hot-reload websocket so development still works. Everything else matches production exactly.
+
+This matters most for the frame limits. The dev server serves your UI from its own origin, on a port of its own, just as production serves it from the asset host. A cross-origin frame is denied capabilities like clipboard access and fullscreen unless the host grants them explicitly, so the dev server grants exactly what production does: a copy button or a fullscreen toggle that works locally works in a live session too.
+
+It also means your UI cannot reach the dev server's own API, only the host messages. Code that fetches `/api/...` directly fails in the dev server exactly as it would in production, where no runtime allows it.
+
+If you see a CSP violation in the dev server console, fix it there: it would otherwise have reached production unnoticed.
+
+## Beyond the frame: writes and logic
+
+Three more rules hold in production, and the dev server enforces each of them the same way. A fourth is a habit rather than a check:
+
+- **A UI writes only what it declares.** A game or waiting room UI's `setData` may change only the capabilities in its `writes`. Anything else, including a `deletes` path into a capability it only reads, is refused as `denied` and nothing of the write lands. The host decides which UI sent a write; the page cannot claim to be another
+- **A UI never retries on its own.** A production host may lose a race with a tick and retries the write itself before reporting `conflict`. When a `conflict` reaches your UI the host has given up, so show it and offer a 'Try again' button (`failure.retry` from `useMutationReporter`) rather than re-sending automatically. The dev server serialises writes, so it produces a `conflict` only when you arm one with `sdk fault conflict`
+- **Game logic cannot import Node built-ins.** Engine, hook, validator, endpoint and tick controller logic runs on the ECMAScript intrinsics alone, with no `require`. An import of `node:fs`, `crypto`, `path` or any other built-in fails `sdk build`, `sdk dev` and `tick` with `LOGIC_NODE_BUILTIN`, naming the file and the import (see [the language environment](./engine.md#the-language-environment-your-logic-runs-in))
+- **Game logic reads the time from `meta.now`, never `Date.now()`.** A production runtime may run one tick more than once and keeps only the last run, so a clock read in logic differs between the runs. `meta.now` is the instant the operation started, the same for every call in it and for a re-run of it (see [the time](./engine.md#the-time)). Derive randomness from `meta.seed` for the same reason
+
+## A note on caching
+
+Published bundles are cached as immutable for a year, so cache-busting comes from publishing a fresh version, never from editing files in place. Always ship a new version rather than mutating a deployed bundle.
+
+## Related
+
+- [Building user interfaces](./ui.md)
+- [File handling (blobs)](./file-handling.md)
+- [LLM integration](./llm-integration.md)

package/dist/docs/guides/scenario-editor.md

@@ -0,0 +1,143 @@
+# Building a scenario editor
+
+The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it. It works at any time, with no session, and what it produces is a lasting scenario. This guide covers creating one, what it may and may not do, and when you need one at all.
+
+## What you'll learn
+
+- What the scenario editor is for, and how it differs from setup
+- When a game needs one, and when descriptive settings schemas are enough
+- How to create an editor and choose the settings it edits
+- Which endpoints the editor may call, and what they receive
+- How saving works in a hosted runtime and in the dev server
+
+## What the scenario editor is
+
+A game holds at most one scenario editor, at `scenario_editor/`. It is a slot, like `session` or `setup`, so it carries no name of its own: the slot is its identifier.
+
+| Aspect               | Setup                                   | Scenario editor              |
+| -------------------- | --------------------------------------- | ---------------------------- |
+| **When shown**       | When a session is created               | At any time, with no session |
+| **What it does**     | A short form for this session           | Authoring a lasting scenario |
+| **Output**           | Session overrides for this session only | A saved scenario             |
+| **Save as scenario** | Never offered                           | Offered by the host          |
+| **Guide**            | [Setup](./setup.md)                     | This page                    |
+
+The host offers save-as-scenario from the scenario editor only, never from setup. Setup changes one session; the editor is where reusable work happens, so there is room for a richer flow here: several steps, previews, uploaded media, an assistant behind an endpoint.
+
+## Do you need one?
+
+The editor is optional. What switches custom scenarios on is one declaration in `seriousgaming.sdk.json`:
+
+```json
+{
+    "customScenarios": { "supported": true }
+}
+```
+
+With it, a hosted runtime persists scenarios authored for the game and lists them beside its built-in ones. Without an editor, a scenario can still be authored: by a facilitator in the runtime's own generic form, or by an AI agent working from the settings schemas. That only works if the schemas say what each value means, so describe every setting:
+
+- `title` and `description`: what the value is and what changing it does
+- Units in the description or title ('in pounds', 'per tick', 'as a fraction of revenue')
+- `minimum` and `maximum` (or `exclusiveMinimum` and `exclusiveMaximum`) for ranges
+- `enum` for a closed set of choices
+
+```json
+"BaseDemand": {
+    "type": "number",
+    "title": "Base demand",
+    "description": "Units customers would buy each tick at a price of zero",
+    "minimum": 0,
+    "maximum": 100000,
+    "default": 10000
+}
+```
+
+Once facilitators have saved scenarios, a release can leave them behind. When you remove, rename, or reshape a setting, change what a value means, or change how the game loads scenario assets, bump `scenarioFormat` in `seriousgaming.sdk.json` (it starts at 1), and a runtime refuses the older scenarios rather than applying them wrongly. A new setting with a default needs no bump. See [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it).
+
+Build an editor when a form is not enough: values that only make sense together, uploaded assets, a preview of what participants will see, or guidance a facilitator needs while choosing.
+
+## Creating a scenario editor
+
+```bash
+pnpm run sdk new scenario_editor '{
+  "definition": {
+    "configures": ["engine", "ui"]
+  },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+```
+
+`configures` names the [settings resources](./settings.md) the editor edits, by identifier. It receives the resolved values of exactly those settings and can change nothing else (an `updateSettings` call naming any other settings resource is refused, and none of it is applied), and the build fails if you name a settings resource the package does not declare. Settings the editor does not configure keep the values the scenario starts from. List `game` to let the editor set the scenario's number of rounds and team settings, which it saves under the scenario's `settings.game` (see [The game settings](./settings.md#the-game-settings)). An edit that changes a setting the game locks with `readOnly`, or sets a value outside its schema's range, is refused the same way, and the draft keeps none of it. The editor is sent values, not schemas, so show a locked field as read-only, as the factory example's editor does (see [Lock a setting](./settings.md#lock-a-setting)).
+
+```
+scenario_editor/
+├── scenario_editor.sdk.json
+├── index.html
+├── types.ts        # generated
+├── defaults.ts     # generated
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── i18n.ts
+    └── theme.ts
+```
+
+## Building the editor
+
+The editor uses the same wrapper and hooks as setup: `SettingsEditorWrapper` in `src/main.tsx`, and `useSettingsEditor()` for `{ settings, updateSettings, configures }`. The generated `Settings` and `defaultSettings` are keyed by settings identifier. The [setup guide](./setup.md#building-the-form) shows a form; everything there applies here.
+
+Two differences:
+
+- **No `requestPlay`.** There may be no session to start. The callback exists on `useSettingsEditorCallbacks()`, because one wrapper serves both slots, but the host ignores it from the editor
+- **No save button of your own.** The host owns saving: it supplies the name, decides where the scenario is stored, and offers the action in its own chrome. The editor only edits values
+
+`useSettingsEditorCallbacks()` also gives `uploadBlob`, `getAssetUrl`, `readAsset`, and the `endpoints` the bundle declares. An uploaded `blob:` reference stored in a setting travels with the saved scenario.
+
+## Calling endpoints
+
+The editor has no session, so an endpoint it lists must be session-scoped and declare no `reads`, `writes` or `actions`: there is no game state for it to read, change or act on. The build refuses one that does with `EDITOR_ENDPOINT_STATEFUL`, pointing at the entry in `endpoints`. To use one that needs game state elsewhere, give the editor an endpoint of its own.
+
+What such an endpoint receives is its declared `settings`, resolved from the scenario being edited with the editor's unsaved changes over it, so it sees the draft without the editor sending the values in the request. `context` and `participants` are empty, `session` has played nothing and holds no teams, and `caller` is `{ role: 'author', userInterfaceIdentifier: 'scenario_editor' }`, with no `sessionId`. The person editing a scenario may not be a facilitator, so the editor's calls never report `'facilitator'`. See [Calls from the scenario editor](./endpoints.md#calls-from-the-scenario-editor).
+
+```json
+{
+    "definition": {
+        "scope": "session",
+        "settings": ["engine", "ui"],
+        "uses": ["generateText"],
+        "requestSchema": { "type": "object", "properties": {}, "additionalProperties": false },
+        "responseSchema": { "type": "object", "properties": {}, "additionalProperties": false }
+    }
+}
+```
+
+## Dev server behaviour
+
+The dev drawer's **Scenario** tab opens the editor: **Add scenario** creates a scenario and opens the editor on it, and **Edit** opens it on an existing one. It runs on `/scenario-editor`, always on one scenario, in a new tab.
+
+What you edit there is a draft of that scenario, which the dev server keeps apart from its session. The session running beside the editor stays on the scenario it was on, and an edit changes none of its settings, now or when it starts play. Endpoints the editor calls read the draft. Each scenario open in an editor has its own draft, and reloading the editor's tab keeps it.
+
+**Save** in the page's toolbar writes the draft into `scenarios/<identifier>/scenario.sdk.json`, materialising any `blob:` references as files under the scenario's `assets/shared/`. It replaces the scenario's `settings` and nothing else, so its names, descriptions and other fields stay as you wrote them. A session sees the values once it is started on that scenario. That is author-time work in your own source tree; a hosted runtime saves to its own store instead. See [Save as a scenario](./scenarios.md#save-as-a-scenario-dev-server).
+
+## Managing the slot
+
+```bash
+pnpm run sdk update scenario_editor '{
+  "definition": { "configures": ["engine"] },
+  "rootDirectory": ".",
+  "ui": { "entrypoint": "index.html" }
+}'
+pnpm run sdk delete scenario_editor
+```
+
+## Testing
+
+`renderSettingsEditor` from `@seriousgaming/sdk/ui/testing` renders a component inside every settings editor provider, as for setup. Start from `defaultSettings` and override what the screen under test reads.
+
+## See also
+
+- [Setup](./setup.md): the short form at session creation
+- [Scenarios](./scenarios.md): built-in and custom scenarios
+- [Settings](./settings.md): declaring settings, and describing them well
+- [Create a scenario editor](../recipes/create-scenario-editor.md)