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

package/dist/docs/troubleshooting.md

@@ -0,0 +1,816 @@
+# Troubleshooting
+
+Find the symptom you are seeing, then read its cause and fix. Entries are grouped by where the problem shows up.
+
+- [Dev server and sessions](#dev-server-and-sessions)
+- [Engine logic and endpoints](#engine-logic-and-endpoints)
+- [Build and validation](#build-and-validation)
+- [User interfaces](#user-interfaces)
+- [Tests](#tests)
+- [Other error messages](#other-error-messages)
+
+## Dev server and sessions
+
+### The dev server does not start
+
+**Symptom:** `pnpm run sdk dev` fails, or does not open http://localhost:3000.
+
+**Fix:** work through these in order.
+
+1. Check the Node.js version. The SDK requires Node 24 or later:
+
+    ```bash
+    node --version
+    ```
+
+2. Check you are in a package directory:
+
+    ```bash
+    ls seriousgaming.sdk.json
+    ```
+
+3. Install dependencies:
+
+    ```bash
+    pnpm install
+    ```
+
+4. Clean and rebuild:
+
+    ```bash
+    rm -rf node_modules dist
+    pnpm install
+    pnpm run build
+    pnpm run sdk dev
+    ```
+
+5. Try a different port:
+
+    ```bash
+    pnpm run sdk dev --port 3001
+    ```
+
+### A command fails with SESSION_STALE
+
+**Symptom:** `sdk tick` or another session command fails with `SESSION_STALE` (exit 5), saying the dev server was started by different tools.
+
+**Cause:** the dev server you started with `sdk dev` is running an older build of the SDK tools than your CLI: you upgraded, rebuilt a linked checkout, or switched branch while it ran. Its answers may not match what is on disk, and a server you started yourself is never stopped for you. A server a command started in the background is replaced automatically instead.
+
+**Fix:** stop it and start it again:
+
+```bash
+pnpm run sdk dev stop
+pnpm run sdk dev
+```
+
+### sdk dev says a server is running when none is
+
+A lock whose process is gone, whose pid is the process reading it, that was written on another machine, or whose port does not answer as that server is removed, and `sdk dev` starts. If your project directory is restored from a snapshot, set `SERIOUSGAMING_DEV_STATE_DIR` to a directory outside it so the lock is not restored at all (see [Environment variables](./environment-variables.md#dev-server)).
+
+### A command fails with DEV_SERVER_UNRESPONSIVE, or hangs after a tick
+
+**Symptom:** a tick never finishes, and every command after it fails with `DEV_SERVER_UNRESPONSIVE`, saying the server accepts connections but did not answer.
+
+**Cause:** logic is stuck in synchronous code that never returns, such as a `while (true)` whose exit condition is never met. The dev server runs logic on its own thread, so a loop like this blocks the whole server, and the time limit on the call cannot fire until the loop ends (see [Time limits](./guides/engine.md#time-limits)).
+
+**Fix:** stop the server, which kills it if it does not exit on its own, then fix the loop and start again:
+
+```bash
+pnpm run sdk dev stop
+```
+
+A `tick --no-server` stuck the same way runs in your terminal: stop it with Ctrl+C.
+
+### The console says 'Nothing is answering', or the CLI and the browser disagree
+
+**Symptom:** the console sits on 'Nothing is answering', or `sdk tick` advances a session the browser does not show.
+
+**Cause:** the browser is on a different dev server from the one your commands reach, usually an older one still holding the port, so the server you just started moved to the next free port. The CLI and a browser on the same server cannot disagree: they are one session.
+
+**Fix:** ask where this package's server actually is, and open that address, or stop the old one:
+
+```bash
+pnpm run sdk dev status
+pnpm run sdk dev stop
+```
+
+### Game surfaces cannot be served
+
+**Symptom:** `sdk dev` starts, but a surface fails to load and the server prints 'Game surfaces cannot be served'.
+
+**Cause:** the package's dependencies are not installed, so Vite cannot load its configuration. The session still runs, so the CLI and the console's state work as usual.
+
+**Fix:** install the dependencies and start the server again:
+
+```bash
+pnpm install
+pnpm run sdk dev stop
+pnpm run sdk dev
+```
+
+### Engine code does not appear, or is stale
+
+**Symptom:** the dev server does not pick up the engine, or runs old code.
+
+**Cause:** a logic edit changes the next run, not the ticks already played. If the engine still looks wrong after a new tick, the files themselves may be missing or incomplete. See [What reloads](./cli-reference.md#what-reloads).
+
+**Fix:**
+
+1. Rebuild after making changes:
+
+    ```bash
+    pnpm run build
+    pnpm run sdk dev
+    ```
+
+2. Check the engine file exists:
+
+    ```bash
+    ls engine/logic.ts
+    ```
+
+3. Check the engine exports the right functions:
+
+    ```bash
+    grep "export const Run" engine/logic.ts
+    ```
+
+4. Check the engine bundle:
+
+    ```bash
+    cat engine/engine.sdk.json
+    ```
+
+### UIs crash after a capability schema change
+
+**Symptom:** after changing a capability's `variablesSchema` while a game is running under `sdk dev`, UIs crash reading fields that do not exist yet, and team contexts keep the old shape.
+
+**Cause:** a bundle edit is adopted and a logic edit reaches the next run, but neither resets the session. Contexts that `Init` has already built keep the shape they had, so a new field has no value until something writes it.
+
+**Fix:**
+
+1. Reset the session so `Init` runs again against the new schema:
+
+    ```bash
+    pnpm run sdk reset
+    ```
+
+2. Or undo and tick again to replay a tick from the same starting point with the new code. See [What reloads](./cli-reference.md#what-reloads)
+
+### A tick is refused with 'Tick limit reached'
+
+**Symptom:** a tick request is refused instead of advancing the game. From a UI, `requestTick` rejects with a `MutationError` whose `outcome.kind` is `'tick-failed'`; from the CLI, `sdk tick` exits non-zero. The message is `Tick limit reached`, or `The game is complete` once the session has finished.
+
+**Cause:** the game has reached its declared `maxTicks` limit, and the runtime refuses to execute a tick beyond it.
+
+**Fix:**
+
+1. This is the expected end of the game. Use undo or reset to keep playing, or raise `maxTicks` in `seriousgaming.sdk.json` if the game should run longer
+2. Your UI does not need to gate its advance control on `latestTick < maxTicks` for correctness, because the runtime enforces the limit. Disabling the control remains good UX
+
+### A tick is refused with 'Team is already complete'
+
+**Symptom:** `sdk tick --team N` is refused with `Team is already complete`.
+
+**Cause:** in an independent game, that team has finished.
+
+**Fix:** tick another team, tick with no `--team` to advance every team that can move, or reset the session with `pnpm run sdk reset`.
+
+### The dev server is slow
+
+**Symptom:** the game runs slowly and the dev server is sluggish.
+
+**Fix:**
+
+1. Reduce the tick count while testing:
+
+    ```bash
+    pnpm run sdk update package --patch '[{"op":"replace","path":"/maxTicks","value":5}]'
+    ```
+
+2. Profile the engine. Logic runs with only the ECMAScript intrinsics and the SDK's `console` shim (`log`, `info`, `warn`, `error`, and `debug`; there is no `console.time`), so time a section with `Date.now()`:
+
+    ```typescript
+    const started = Date.now();
+    // engine logic
+    console.log(`engine-run: ${Date.now() - started}ms`);
+    ```
+
+3. Make expensive calculations cheaper:
+    - Avoid loops in `Run` functions
+    - Cache computed values
+    - Use efficient algorithms
+
+4. Check system resources:
+
+    ```bash
+    top  # macOS/Linux
+    tasklist  # Windows
+    ```
+
+## Engine logic and endpoints
+
+### Context changes do not appear in the next tick
+
+**Symptom:** changes the engine makes to the context are gone on the next tick.
+
+**Cause:** one of three mistakes in `Run`.
+
+**Fix:**
+
+1. **Return a new object instead of mutating the context:**
+
+    ```typescript
+    // ❌ Wrong - mutates context
+    context.inventory.variable = value;
+
+    // ✅ Correct - immutable update
+    return {
+        capabilities: {
+            ...context,
+            inventory: {
+                ...context.inventory,
+                variable: value,
+            },
+        },
+    };
+    ```
+
+2. **Return the result from `Run`:**
+
+    ```typescript
+    // ❌ Wrong - doesn't return
+    export const Run = async ({ context, settings, callbacks }) => {
+      // modify context
+    };
+
+    // ✅ Correct
+    export const Run = async ({ context, settings, callbacks }) => {
+      return { capabilities: { ...context, ... } };
+    };
+    ```
+
+3. **Key the result by the capability identifier:**
+
+    ```typescript
+    // ❌ Wrong - wrong identifier
+    return {
+      capabilities: {
+        ...context,
+        "com.wrong.identifier": { ... }
+      },
+    };
+
+    // ✅ Correct
+    return {
+      capabilities: {
+        ...context,
+        "inventory": { ... }
+      },
+    };
+    ```
+
+### A tick fails with 'returned unknown top-level key'
+
+**Symptom:** a tick, init, hook or endpoint call fails with an error such as `Engine "engine" Run returned unknown top-level key "inventory"`.
+
+**Cause:** the logic returns its capabilities flat, the shape SDK 0.6 and earlier used (or `{ response, context }` from a writing endpoint). Logic now returns what it writes under `capabilities`, and the runtime refuses any top-level key it does not know rather than silently discarding the writes.
+
+**Fix:** wrap the return:
+
+```typescript
+// ❌ Wrong - flat
+return { ...context, inventory: { ...context.inventory, Stock } };
+
+// ✅ Correct
+return { capabilities: { ...context, inventory: { ...context.inventory, Stock } } };
+```
+
+An aggregate engine returns `{ shared: { capabilities }, teams: [{ capabilities }] }`, and a writing endpoint `{ response, capabilities }`. See the [upgrading guide](./guides/upgrading.md).
+
+### Variables have unexpected values
+
+**Symptom:** variables show values you did not expect.
+
+**Fix:**
+
+1. Check the variable schema defaults:
+
+    ```bash
+    cat capabilities/inventory/capability.sdk.json
+    ```
+
+2. Trace engine initialisation:
+
+    ```typescript
+    // Add logging in Init function
+    export const Init = async ({ context, settings, callbacks }) => {
+      console.log('Initial context:', context);
+      console.log('Settings:', settings);
+      return { ... };
+    };
+    ```
+
+3. Inspect the actual values in the dev server's context inspector
+
+### A field the engine cleared comes back on a hosted session
+
+**Symptom:** the engine clears an object variable by returning `{}`, for example `PendingJunction: {}`. Locally the field is empty after the tick, in the dev server and in tests alike. On a hosted session the old value is still there.
+
+**Cause:** a returned variable replaces its old value whole, so `{}` empties it (see [how a result folds into the context](./guides/engine.md#how-a-result-folds-into-the-context)). A runtime that instead merges the returned object into the old one treats `{}` as a change to nothing. No runtime should do that, but a hosted runtime has done it.
+
+**Fix:** return a value that comes out the same either way. Set each field inside the variable explicitly, or return `null` for the variable if its schema allows `null`. Both clear the field on every runtime.
+
+### Shared values from an aggregate engine stay at their defaults
+
+**Symptom:** values an aggregate engine returns in the `shared` slice of its `InitAggregate` or `RunAggregate` result stay at their schema defaults on every tick, with no error.
+
+**Cause:** SDK versions before 0.0.104 discard the `shared` slice, so a shared value persists only if the engine also writes it into each `teams` context.
+
+**Fix:**
+
+1. Update the SDK. The runtime writes `shared` to the shared store after applying `teams`, so returning the value in `shared` alone is enough. Remove any copy the workaround wrote into each `teams` context: a shared capability in a `teams` entry now fails the init or tick (see the next entry)
+2. Check that every key in `shared.capabilities` is a `scope: 'shared'` capability. Anything else fails the init or tick with an error naming the engine and the capability
+
+### An aggregate engine fails with 'returned shared capability in teams'
+
+**Symptom:** an init or tick fails with an error such as `Engine "engine" returned shared capability "market" in teams[0] of RunAggregate. Return shared capabilities once, under "shared": { capabilities: { market: ... } }.`
+
+**Cause:** a `teams` entry of the result carries a `scope: 'shared'` capability. A `teams` entry is a per-team patch, and a capability with one value per session has no per-team value, so the runtime refuses it even when every team carries the same value. Earlier SDK versions adopted a value every team carried identically; that channel is removed.
+
+**Fix:**
+
+1. Return the shared value once, under `shared: { capabilities }`
+2. Read the previous value from the `shared` argument (`shared.context.market`), not off a team. Each `teams[i].context` now carries team scope only, so spreading `...t.context` into a `teams` entry no longer copies shared capabilities back
+3. Type the function with the generated `TeamContext` and `SharedContext`: `RunAggregateFunction<TeamContext, SharedContext, Settings>`. A shared capability in a `teams` entry is then a compile error as well. See [step 5 of the upgrading guide](./guides/upgrading.md#step-5-read-shared-state-from-its-own-channel)
+
+### A writing endpoint is refused with 'the game moved on'
+
+**Symptom:** an endpoint that declares `writes` returns _'The game moved on while the endpoint was running'_ and changes nothing.
+
+**Cause:** a tick committed while the handler was still running, so its patch was computed against a board that has since been replaced. Applying it would silently undo part of the tick that just closed.
+
+**Fix:**
+
+1. Make the handler faster. A handler that calls a model can easily outlive the tick it was called in, and a facilitator operation taking that long is a poor experience regardless
+2. Move the slow part into the engine, which runs as part of the tick rather than beside it
+3. Where the work genuinely has to be slow and the result genuinely has to land, have the handler write a request into the context and let the next tick act on it
+
+## Build and validation
+
+### TypeScript reports errors about `Context` or `Settings` types
+
+**Symptom:** compilation fails with errors about the generated `Context` or `Settings` types.
+
+**Fix:**
+
+1. Regenerate types:
+
+    ```bash
+    pnpm run generate
+    pnpm run build
+    ```
+
+2. Check the resource definitions are valid:
+
+    ```bash
+    pnpm run sdk build --validate-only
+    ```
+
+3. Check the generated types file:
+
+    ```bash
+    cat engine/types.ts
+    ```
+
+4. Restart your editor's TypeScript server (in VS Code: Cmd+Shift+P, then 'TypeScript: Restart TS server')
+
+### The build fails with a missing capability
+
+**Symptom:** `Engine "engine" reads capability "foo" which is not found in configuration`, or the same for another resource, or for `writes`.
+
+**Fix:**
+
+1. Check the capability exists:
+
+    ```bash
+    ls capabilities/foo/capability.sdk.json
+    ```
+
+2. Check the spelling in the engine definition:
+
+    ```bash
+    grep -r "foo" engine/
+    ```
+
+3. Create the missing capability:
+
+    ```bash
+    pnpm run sdk new capability '{
+      "definition": {
+        "identifier": "foo",
+        "variablesSchema": {
+          "type": "object",
+          "properties": {},
+          "required": [],
+          "additionalProperties": false
+        }
+      }
+    }'
+    ```
+
+### The build rejects `aggregate` in engine.sdk.json
+
+**Symptom:** `pnpm run sdk build` fails with ``\`aggregate\` has been removed`` on an engine bundle that carries the flag.
+
+**Cause:** an engine is aggregate because its logic exports `InitAggregate` and `RunAggregate`, and the build reads that from the code. An authored flag could only agree with the exports or contradict them, so the bundle may not carry one.
+
+**Fix:**
+
+1. Delete the field. Nothing replaces it:
+
+    ```bash
+    pnpm run sdk update engine --patch '[
+      { "op": "remove", "path": "/definition/aggregate" }
+    ]'
+    ```
+
+2. If the engine is meant to be aggregate, make sure its logic exports `InitAggregate` and `RunAggregate` (and `Init`, if it needs one). Exporting one of the aggregate pair without the other fails the build, naming the missing one
+3. If it is meant to be per team, remove the aggregate exports and keep `Run` (and `Init`, if it has one)
+
+### The build rejects `configurationSchema` or the game's `configuration` block
+
+**Symptom:** loading or building the package fails with one of these:
+
+```
+`configurationSchema` has been removed. Move these properties into a settings resource (`pnpm run sdk new settings`), and list it in this resource's `settings`.
+```
+
+```
+The game-level `configuration` block has been removed: edit the settings resource's defaults instead, or override them in a scenario's `settings`. Delete the block.
+```
+
+**Cause:** settings are no longer declared per resource. It lives in settings resources, `settings/<name>/settings.sdk.json`, which any resource reads by listing them in its `settings`. A game's own values are those resources' defaults, so there is no game-level override layer left for the manifest's `configuration` block to fill.
+
+**Fix:**
+
+1. Create a settings resource holding the old `configurationSchema` properties, with `pnpm run sdk new settings` (interactive) or `pnpm run sdk new settings '<JSON>'` (see [Create settings](./recipes/create-settings.md)). Every property needs a `default`
+2. Delete the `configurationSchema` from the bundle and add `"settings": ["<name>"]` in its place
+3. Read `settings.<name>.X` in logic and surfaces where they read `config.X`, then run `pnpm run sdk generate`
+4. Copy any values from the manifest's `configuration` block into the settings defaults, then delete the block
+
+[Step 2 of the upgrading guide](./guides/upgrading.md#step-2-move-configuration-into-settings-resources) walks through the whole move.
+
+### The build rejects `demo` or a user interface's `uses`
+
+**Symptom:** loading or building the package fails with one of these:
+
+```
+Demo mode has been removed, so `demo` is read by nothing. To show a game to a room, start a walkthrough run, which plays it without touching the session. Delete the block.
+```
+
+```
+`uses` has been removed from user interfaces: a user interface reaches a service through an endpoint. Declare the API in the endpoint's `uses`, list the endpoint in this interface's `endpoints`, and delete the field.
+```
+
+**Cause:** both fields were removed in 1.0. Nothing defined how a session entered demo mode, and a walkthrough run is where a game is demonstrated. A user interface could never call a service directly, so every value its `uses` accepted was either refused or did nothing.
+
+**Fix:**
+
+1. Delete the `demo` block from `seriousgaming.sdk.json` and from any scenario. To rehearse or show the game, use a walkthrough run (see [Adapt a game for walkthroughs](./recipes/adapt-a-game-for-walkthroughs.md))
+2. Delete `uses` from the user interface. If it needs a service, put the call in an endpoint that declares it, and list that endpoint in the interface's `endpoints` (see [Call an endpoint from a UI](./recipes/call-endpoint-from-ui.md))
+
+### A settings override fails with 'Unknown settings'
+
+**Symptom:** `sdk configure`, `sdk init`, `sdk build`, or a scenario switch fails with `Unknown settings "engine": expected one of ...` (or `this package declares no settings`).
+
+**Cause:** a scenario's `settings`, `sdk configure` input, and `.seriousgaming-sdk/configuration.json` are keyed by settings identifier, the directory name under `settings/`. They were keyed by slot before, so an override written for the old shape names a slot (`engine`, `ui`, `tick_controller`) that the package holds no settings resource for. The override is refused rather than ignored, because an override that reaches nothing reads as applied.
+
+**Fix:** re-key the override by the settings resource that declares the property, or create one with that name. A value in `.seriousgaming-sdk/configuration.json` can be corrected in place, or the file deleted to start again from the defaults. See [Overriding settings](./guides/settings.md#overriding-settings).
+
+### An aggregate engine fails the build with 'must export Init and Run'
+
+**Symptom:** an engine you intended as aggregate fails `pnpm run sdk build` with errors saying it must export `Init` and `Run`.
+
+**Cause:** its logic exports neither `InitAggregate` nor `RunAggregate`, so the build reads it as a per-team engine and applies the per-team export contract. Merging several files into one engine makes this easy to do: the aggregate functions end up in a file nothing re-exports.
+
+**Fix:**
+
+1. Check what the entrypoint actually exports:
+
+    ```bash
+    grep -n 'export const \(Init\|Run\)' engine/logic.ts
+    ```
+
+2. Export the aggregate pair from the entrypoint. A re-export counts:
+
+    ```typescript
+    export { InitAggregate, RunAggregate } from './market';
+    ```
+
+3. `sdk new engine --aggregate` scaffolds all three exports for a fresh engine
+
+### The build rejects a teamless surface calling a team-scoped endpoint
+
+**Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI, setup screen, or scenario editor.
+
+**Cause:** an endpoint declares whether it acts on one team or on the session, and `scope` is `'team'` when absent. A session UI, a setup screen, and a scenario editor have no team of their own, so there is nothing for a team-scoped call to act against.
+
+**Fix:**
+
+1. If the endpoint acts on the session, declare it session-scoped:
+
+    ```json
+    { "definition": { "scope": "session" } }
+    ```
+
+2. If the endpoint genuinely acts on one team, stop listing it on the teamless surface and call it from the game UI instead
+3. Check what each endpoint declares:
+
+    ```bash
+    pnpm run sdk endpoint list
+    ```
+
+### The build is slow
+
+**Symptom:** `pnpm run build` takes a long time.
+
+**Fix:**
+
+1. Check for large files:
+
+    ```bash
+    find . -size +10M
+    ```
+
+2. Clear the build cache:
+
+    ```bash
+    rm -rf dist build node_modules
+    pnpm install
+    pnpm run build
+    ```
+
+3. Use the dev server while you work: it watches sources for you rather than needing a full rebuild each time (start it yourself; agents should not):
+
+    ```bash
+    pnpm run sdk dev
+    ```
+
+### A package built on Windows serves the wrong asset paths
+
+**Symptom:** a package builds and runs on your machine, but once published a user interface fails to load its files, or `pnpm run sdk build` in a project that depends on the package fails to find a resource directory. `dist/seriousgaming.json` shows a backslash in the path:
+
+```json
+"rootDirectory": "user-interfaces\\com.example.dashboard"
+```
+
+**Cause:** the package was built on Windows with SDK 0.0.119 or earlier, which composed each `rootDirectory` with the host's path separator. A POSIX host and an object store cannot follow a backslash. A browser normalises one in a URL path, which is why the dev server and a direct page load look fine.
+
+**Fix:**
+
+1. Upgrade the SDK and rebuild:
+
+    ```bash
+    pnpm run sdk build
+    grep rootDirectory dist/seriousgaming.json
+    ```
+
+    Every value should read `<resource-kind>/<identifier>` with forward slashes.
+
+2. Republish the package, since the bad paths are baked into the published artefact:
+
+    ```bash
+    pnpm run sdk package bundle
+    pnpm run sdk package publish
+    ```
+
+3. If you consume a package published this way and cannot get it rebuilt, upgrade your own SDK instead. It normalises the separator as a dependency's manifest is read, so the package works without being rebuilt
+
+## User interfaces
+
+### A UI is blank or does not appear
+
+**Symptom:** a user interface shows nothing in the dev server.
+
+**Fix:**
+
+1. Check the UI bundle:
+
+    ```bash
+    cat ui/ui.sdk.json
+    ```
+
+2. Check the React component exports:
+
+    ```bash
+    grep "export default" ui/src/App.tsx
+    ```
+
+3. Check the build output:
+
+    ```bash
+    ls dist/ui/
+    ```
+
+4. Look in the browser console for errors (F12 in the dev server)
+
+5. Open the dev drawer (press the backtick key). If the **State** tab shows what you expect, the problem is in the surface rather than the session, and the **Errors** tab lists anything the session reported
+
+### 'Invalid hook call' or 'Cannot read properties of null'
+
+**Symptom:** the UI crashes with:
+
+> Error: Invalid hook call. Hooks can only be called inside of the function body of a function component.
+
+or:
+
+> Cannot read properties of null (reading 'useState')
+
+**Cause:** a third-party library (such as `@react-three/fiber` or MUI) has React as a peer dependency but also `require()`s React internally. Vite's pre-bundler produces a second copy of React, so two React instances are active at runtime. Hooks fail because the renderer's dispatcher is registered on one while components read from the other.
+
+**Fix:** add a `vite.config.ts` to your project root with `resolve.dedupe`, as `sdk new package` writes it:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    resolve: {
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+        ],
+    },
+});
+```
+
+The SDK packages are there for the same reason as React: a second copy of the SDK, such as one a shared package of yours resolves, brings its own React contexts, so its hooks read empty data rather than throwing.
+
+Restart the dev server. The SDK merges this config automatically for both `sdk dev` and `sdk build`. See [Fix duplicate package errors in a UI](./recipes/fix-duplicate-packages.md) for more.
+
+### `useUserInterfaceData()` throws, or its data is undefined
+
+**Symptom:** `useUserInterfaceData()` throws an error, or the data it returns is undefined.
+
+**Fix:**
+
+1. Make sure the UI reads the capabilities it needs:
+
+    ```bash
+    cat ui/ui.sdk.json | grep "reads"
+    ```
+
+2. Use the hook the SDK provides:
+
+    ```typescript
+    // ✅ Correct
+    const { data, settings, setData } = useUserInterfaceData<Context, Settings>();
+    const { Stock } = data.inventory;
+
+    // ❌ Wrong - trying to use non-existent hooks
+    const context = useUserInterfaceContext<Context>();
+    const settings = useUserInterfaceSettings<Settings>();
+    ```
+
+3. Check the type imports:
+
+    ```typescript
+    import type { Context, Settings } from '../types';
+    import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+    ```
+
+4. Call the hook inside `UserInterfaceWrapper`:
+
+    ```typescript
+    // ❌ Wrong - hook used outside wrapper
+    const { data } = useUserInterfaceData<Context, Settings>();
+
+    export default () => <App />;
+
+    // ✅ Correct - hook inside wrapper
+    export default () => <UserInterfaceWrapper><App /></UserInterfaceWrapper>;
+    ```
+
+### A UI is blocked by the content security policy
+
+**Symptom:** the browser console shows errors such as:
+
+```
+Content-Security-Policy: The page's settings blocked a worker script (worker-src)
+at blob:... because it violates the following directive: "script-src 'self' 'unsafe-inline'"
+```
+
+or fonts, scripts, or stylesheets fail to load from an external origin (for example `fonts.googleapis.com`).
+
+**Cause:** your UI runs under a strict content security policy on the isolated asset host, and the dev server applies the same policy as production. Everything must be first-party to your bundle, outbound network calls are limited to the asset host, and blob-URL workers are blocked.
+
+**Fix:**
+
+1. Bundle external assets into your build. Replace CDN font links with a self-hosted package (for example `@fontsource-variable/work-sans`) imported in your UI source
+2. Remove blob-URL web workers. Configure libraries that spawn workers (PDF.js, transformers.js, ONNX runtime) to load a bundled worker file, or avoid them
+3. Move outbound network calls out of the UI: fetch through an engine, an endpoint, or a host capability rather than calling a third-party origin directly
+4. Drop any reliance on `eval` or `new Function`: `unsafe-eval` is not granted
+
+See [Production security constraints](./guides/production-constraints.md) for the full policy.
+
+### An asset is refused because its content type was not sniffed
+
+**Symptom:** a script, stylesheet, or other asset is blocked with a console error such as:
+
+```
+Refused to execute script from '...' because its MIME type ('text/plain') is not
+executable, and strict MIME type checking is enabled.
+```
+
+**Cause:** both production and the dev server send `X-Content-Type-Options: nosniff`, so the browser will not guess an asset's type from its bytes. An asset served with a missing or wrong `Content-Type` (a script delivered as `text/plain`, a stylesheet with the wrong type) is refused rather than sniffed into the right type.
+
+**Fix:**
+
+1. Bundle the asset into your build so it is served with the correct type, rather than referencing a loosely typed file
+2. If you serve the asset through an endpoint or capability, set an accurate `Content-Type` on the response
+
+See [Production security constraints](./guides/production-constraints.md) for the full asset-host response contract.
+
+### Content is hidden behind the iOS URL bar
+
+**Symptom:** on iOS Safari or Chrome, the bottom of a UI is cut off behind the browser's URL bar, and the page will not scroll to reveal it.
+
+**Cause:** on iOS WebKit, `height: 100vh` (and `min-height: 100vh`) resolves to the tall viewport you get once the URL bar collapses, even while the bar is still showing. A full-height element is therefore taller than the visible area on load.
+
+**Fix:**
+
+1. Size your UI to its container (`height: 100%` through `html`, `body`, and the root element) rather than the viewport. The host already sizes the iframe to the visible area
+2. If you use viewport units, add a `dvh` value after the `vh` fallback: `min-height: 100vh; min-height: 100dvh;` (in MUI `sx`, `{ minHeight: '100vh', '@supports (height: 100dvh)': { minHeight: '100dvh' } }`)
+
+See the [user interfaces guide](./guides/ui.md) for sizing to the viewport on mobile.
+
+## Tests
+
+### Tests will not run
+
+**Symptom:** `pnpm run test` fails before any test runs.
+
+**Fix:**
+
+1. Install the test runner:
+
+    ```bash
+    pnpm add -D vitest
+    ```
+
+2. Check the test file:
+
+    ```bash
+    cat engine/logic.test.ts
+    ```
+
+3. Run with verbose output:
+
+    ```bash
+    pnpm run test -- --reporter=verbose
+    ```
+
+### Tests pass locally but fail in CI
+
+**Fix:**
+
+1. Run tests with the same Node version as CI:
+
+    ```bash
+    node --version
+    ```
+
+2. Clear `node_modules` and reinstall:
+
+    ```bash
+    rm -rf node_modules pnpm-lock.yaml
+    pnpm install
+    pnpm run test
+    ```
+
+3. Look for timing and async issues in the tests
+
+## Other error messages
+
+| Error                                    | Fix                                        |
+| ---------------------------------------- | ------------------------------------------ |
+| `ENOENT: no such file or directory`      | Check file paths, and create missing files |
+| `JSON.parse error`                       | Check the JSON syntax in CLI commands      |
+| `Cannot find engine`                     | Run `pnpm install`, and check imports      |
+| `Type 'X' is not assignable to type 'Y'` | Check generated types, and regenerate them |
+
+## Getting help
+
+Collect a detailed report and share it when you ask for help:
+
+```bash
+pnpm run sdk build --validate-only
+pnpm run lint
+pnpm run build --verbose 2>&1 | tee build.log
+```
+
+For more, see the [guides](./guides/index.md), the [concepts](./concepts/index.md), and the [CLI reference](./cli-reference.md). [Drive a game from the CLI](./cli-simulation-testing.md#troubleshooting) covers errors from session commands.