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

package/dist/docs/recipes/declare-api-uses.md

@@ -0,0 +1,67 @@
+# Declare the runtime callbacks a resource uses
+
+**Keywords:** api uses, generateText permission, extractText permission, generateSpeech permission, callbacks declaration, allow LLM, allow document parsing, allow text-to-speech
+
+A logic-bearing resource (engine, hook, tick controller, endpoint) must declare the runtime callbacks it intends to call. Calls to undeclared callbacks throw at runtime, both in dev and production. The declaration lives in the resource's bundle file under `uses`. User interfaces do not declare these external-service callbacks: a UI reaches them through an [endpoint](create-endpoint.md) instead.
+
+## Prerequisites
+
+- A package with at least one engine, hook, tick controller, or endpoint that wants to call `callbacks.generateText`, `callbacks.extractText`, or `callbacks.generateSpeech`
+
+## Steps
+
+1. Open the resource's bundle file (for example `engine/engine.sdk.json`).
+2. Add a `uses` array to the `definition`, listing the callback names you intend to call. The values are `generateText`, `extractText`, `generateSpeech`, and `writeBlob`; see [The closed enum](../guides/llm-integration.md#the-apis-it-gates) for what each does:
+
+    ```json
+    {
+        "definition": {
+            "reads": ["text"],
+            "writes": ["summary"],
+            "uses": ["generateText"]
+        },
+        "logic": { "directory": ".", "entrypoint": "logic.ts" },
+        "rootDirectory": "."
+    }
+    ```
+
+3. Run `pnpm run sdk generate` to regenerate `types.ts`. The `Callbacks` type alias is narrowed to the callbacks you declared, each one present rather than optional, so undeclared calls fail at type-check before they fail at runtime and declared ones need no `?.` check.
+4. In your logic file, type the function signature with the `Callbacks` generic so calls are narrowed:
+
+    ```typescript
+    import { getText, type RunFunction } from '@seriousgaming/sdk';
+    import type { Context, Settings, Callbacks } from './types';
+
+    export const Run: RunFunction<Context, Settings, Callbacks> = async ({
+        context,
+        callbacks,
+    }) => {
+        const summary = await callbacks.generateText('Summarise: ' + context.text);
+        return {
+            capabilities: {
+                ...context,
+                summary: { content: getText(summary) },
+            },
+        };
+    };
+    ```
+
+## Verify
+
+- `pnpm run sdk build` typechecks cleanly: when `Callbacks` is threaded through the function generic, undeclared calls fail at compile time
+- Running the game with `pnpm run sdk tick` completes without throwing an `UndeclaredApiUseError`
+
+## Troubleshooting
+
+- **'UndeclaredApiUseError'** when running a game: the resource called a callback whose name is not in its `uses` array. Add the name and rebuild
+- **TypeScript error: 'Property generateText does not exist on type Callbacks'**: the resource's `Callbacks` type alias was generated with an empty (or partial) `uses` array. Add the missing API to the bundle's `uses` and run `pnpm run sdk generate`
+- **'`uses` has been removed from user interfaces'** when building: UIs cannot call these callbacks directly and carry no `uses`. Delete the field, move the call into an [endpoint](create-endpoint.md), and [invoke the endpoint from the UI](call-endpoint-from-ui.md)
+- **`LLMClientError` or `TtsClientError` from a declared callback**: the service is there but not configured, usually a missing API key. See [Environment variables](../environment-variables.md)
+
+## Related
+
+- [Declare the APIs a resource uses](../guides/llm-integration.md#declare-the-apis-a-resource-uses): the full list of values and where each may be declared
+- [Call an endpoint from a UI](call-endpoint-from-ui.md): how a UI reaches these services
+- [LLM integration](../guides/llm-integration.md): calling `generateText` from the engine and endpoints
+- [Speech generation](../guides/speech-generation.md): calling `generateSpeech` from the engine and endpoints
+- [Upload and display files](upload-and-display-files.md): the `extractText` callback for document parsing

package/dist/docs/recipes/design-state-for-concurrent-writes.md

@@ -0,0 +1,96 @@
+# Design state for concurrent writes
+
+**Keywords:** concurrent writes, lost update, clobber, race condition, id-keyed map, collaborative state, shared array, deep merge, deletes, conflict, mergingSetData
+
+Shape capabilities and `setData` calls so that several participants writing at once never overwrite each other. The host deep-merges each write (see [How setData merges](../guides/ui.md#how-setdata-merges)): writes to different keys merge, and writes to the same key resolve last-write-wins, so the aim is that normal play touches different keys.
+
+## Prerequisites
+
+- A capability your UI writes, declared in its `writes` (see [Create a capability](create-capability.md))
+
+## Steps
+
+1. Send only what changed. Never spread the current snapshot into the write:
+
+    ```typescript
+    // Merges with a team-mate's concurrent write to another field
+    setData({ decisions: { Committed: true } });
+
+    // Overwrites whatever a team-mate wrote a moment earlier
+    setData({ decisions: { ...data.decisions, Committed: true } });
+    ```
+
+2. Model a collection several people add to as an object keyed by a stable id, never an array. Arrays replace wholesale, so two simultaneous appends lose one:
+
+    ```json
+    "Notes": {
+        "type": "object",
+        "default": {},
+        "additionalProperties": {
+            "title": "PinboardNote",
+            "type": "object",
+            "properties": {
+                "Author": { "type": "string" },
+                "Text": { "type": "string" }
+            },
+            "required": ["Author", "Text"],
+            "additionalProperties": false
+        }
+    }
+    ```
+
+    ```typescript
+    setData({ pinboard: { Notes: { [noteId]: { Author: name, Text: text } } } });
+    ```
+
+    Sort for display by a field on each entry (a timestamp or the tick). The `title` names the item type in `types.ts` (see [Keyed collection](../guides/capabilities.md#keyed-collection)).
+
+3. Remove an entry with `deletes`, never by writing `null`. A merge cannot remove a key, and a `null` stays in the context, in every broadcast, and in every snapshot:
+
+    ```typescript
+    setData({}, { deletes: [`pinboard.Notes.${noteId}`] });
+    ```
+
+    Deletions apply after the patch, so one call can replace an entry. A path that resolves to nothing is a no-op, so two people clearing the same note is harmless. For a key containing a dot, pass segments: `[['pinboard', 'Notes', id]]`. A session surface deletes the same way, naming the team first, or from a shared capability with the one-argument form: `setData(teamId, {}, { deletes })` or `setData({}, { deletes })`.
+
+4. Where each participant owns a value (a vote, an allocation), key it by `participant.id`, so each only writes their own key:
+
+    ```typescript
+    const participant = useUserInterfaceParticipant(); // null when observed
+    if (participant) setData({ votes: { Votes: { [participant.id]: 'yes' } } });
+    ```
+
+5. Await the writes that matter through `useMutationReporter`, and show its `failure` (leaving out `validation-rejected`, which `useUserInterfaceValidationRejections` already explains) and its `late` notice. Never retry on your own: on a `conflict` the host has already retried, so offer `failure.retry` behind a 'Try again' button. See [Awaiting state changes](../guides/ui.md#awaiting-state-changes).
+
+6. Arbitrate a slot that is contested by design (two people claiming one role) with a [validator](create-validator.md) that compares `previous` with `next` and rejects the losing write. For a shared numeric pool, reconcile in the engine at tick time instead.
+
+7. In component tests, merge as the host does with `mergingSetData`, or a minimal write that is correct in production fails the test. It applies `deletes` after the merge too:
+
+    ```tsx
+    import { mergingSetData } from '@seriousgaming/sdk/ui/testing';
+
+    const [data, setLocal] = useState(mockContext);
+    const setData = mergingSetData(setLocal);
+    setData({}, { deletes: [`pinboard.Notes.${noteId}`] });
+    ```
+
+## Verify
+
+1. Open the same team's UI in two browser windows of `pnpm run sdk dev`
+2. Change a different field, or add a different entry, in each at the same time: both changes appear in both windows
+3. Clear an entry: it disappears, and its key is gone from `pnpm run sdk view` rather than holding `null`
+
+## Troubleshooting
+
+| Problem                                              | Solution                                                                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| One participant's change vanishes when another saves | A write spreads `...data[...]` or rewrites an array; reduce it to the changed entry              |
+| A cleared entry will not go away                     | The clear writes an empty patch; name the path in `deletes`, and check the path resolves         |
+| Writes work locally but conflict when hosted         | The dev server serialises writes; await through `useMutationReporter` so the participant is told |
+| A test fails on a write that works in the game       | The mock merges differently from the host; use `mergingSetData`                                  |
+
+## Related
+
+- [The starter game](../guides/starter-game.md): every step applied, in `capabilities/plan/`, `ui/src/TodayPanel.tsx`, `ui/src/writes.ts`, and `validators/capacity/`
+- [User interfaces guide](../guides/ui.md#writing-to-context)
+- [Create a validator](create-validator.md)

package/dist/docs/recipes/distribute-package.md

@@ -0,0 +1,80 @@
+# Distribute a built package
+
+Wrap a built `dist/` directory into a single zip archive that a production runtime can ingest as an upload.
+
+**Keywords:** distribute, package, bundle, zip, archive, upload, release, ci, production
+
+## What you'll build
+
+A `package bundle` step in your release pipeline that produces a single zip from `dist/`, then captures the result for CI artefact uploads.
+
+The archive is the upload contract between the SDK and a production runtime. Its root mirrors the build layout, with `seriousgaming.json` at the top.
+
+## Prerequisites
+
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Build the package
+
+```bash
+pnpm run sdk build
+```
+
+This produces `dist/` with the package manifest, bundled logic, and built UIs.
+
+### 2. Produce the distribution zip
+
+```bash
+pnpm run sdk package bundle
+```
+
+The default output path is `dist/<identifier>-<version>.zip`, derived from `dist/seriousgaming.json`.
+
+Use `-o, --output-file` to write the archive somewhere else:
+
+```bash
+pnpm run sdk package bundle --output-file artifacts/release.zip
+```
+
+### 3. Capture the result in CI
+
+```bash
+pnpm run --silent sdk package bundle --json > bundle.json
+```
+
+The envelope's `data` (see [JSON output](../cli-reference.md#json-output)) contains:
+
+```json
+{
+    "outputFile": "/path/to/dist/com.example.pkg-1.2.0.zip",
+    "size": 1234567,
+    "fileCount": 42,
+    "identifier": "com.example.pkg",
+    "version": "1.2.0"
+}
+```
+
+Use this in CI to attach the zip as a build artefact, tag the release with the version, or trigger an upload step.
+
+## Verify
+
+- The output file exists at the path you expect
+- Unzipping it produces `seriousgaming.json` at the archive root, alongside a directory for each built resource, laid out as in the package: `engine/`, `ui/`, `session/`, `waiting_room/` and `guide/` at their slots, and `hooks/<name>/`, `validators/<name>/` and the other plural kinds beneath their directories. Capabilities and settings have no directory of their own, since their schemas are carried in `seriousgaming.json`, and a scenario with no assets adds nothing to the archive
+- The runtime you target accepts the archive as an upload
+
+```bash
+unzip -l dist/com.example.pkg-1.2.0.zip | head
+```
+
+## Troubleshooting
+
+- **'Build directory not found'** - run `pnpm run sdk build` before `pnpm run sdk package bundle`. The bundle command does not build
+- **'Manifest not found'** - the build directory exists but has no `seriousgaming.json`. Re-run the build; check that it completed without errors
+- **Wrong identifier or version in the filename** - both are read from `dist/seriousgaming.json`, but they are authored in different places: the identifier in `seriousgaming.sdk.json`, the version in `package.json` (the manifest carries no version field). Fix whichever is wrong and rebuild
+
+## Related
+
+- [CLI reference: package bundle](../cli-reference.md#package-a-built-game-for-distribution)
+- [Publish a package to the Serious Gaming platform](./publish-a-package.md)

package/dist/docs/recipes/e2e-testing.md

@@ -0,0 +1,116 @@
+# Test UIs end to end with Playwright
+
+Test your game's screens in a real browser against an isolated dev server.
+
+**Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer
+
+## Prerequisites
+
+- A game package that builds (`pnpm run build`)
+- A package made with `sdk new package` already has the Playwright setup (`playwright.config.ts`, `testing/e2e/global-setup.ts`, a starter spec, and a `test:e2e` script): skip to step 4
+
+## Steps
+
+1. Install Playwright:
+
+    ```bash
+    pnpm add -D @playwright/test
+    pnpm exec playwright install chromium
+    ```
+
+2. Create `testing/e2e/global-setup.ts`, which starts an isolated dev server in Playwright's own process and stops it when the run ends:
+
+    ```typescript
+    import { dirname } from 'path';
+
+    import { startDevServer } from '@seriousgaming/sdk-tools/client';
+    import type { FullConfig } from '@playwright/test';
+
+    export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
+        const server = await startDevServer({
+            packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
+        });
+        process.env.SERIOUSGAMING_DEV_URL = server.url;
+        return () => server.stop();
+    }
+    ```
+
+3. Create `playwright.config.ts`, and add `"test:e2e": "playwright test"` to `package.json`:
+
+    ```typescript
+    import { defineConfig } from '@playwright/test';
+
+    export default defineConfig({
+        testDir: './testing/e2e',
+        globalSetup: './testing/e2e/global-setup.ts',
+        workers: 1,
+        use: { baseURL: process.env.SERIOUSGAMING_DEV_URL },
+    });
+    ```
+
+    One worker, because the tests share one session. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
+
+4. Start each test from a fresh session, and open a surface with `?bare` so the page holds your game and none of the console:
+
+    ```typescript
+    import { expect, test } from '@playwright/test';
+    import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
+
+    test.beforeEach(async () => {
+        await reinitialiseSession();
+    });
+
+    test('the stall opens on day one', async ({ page }) => {
+        await page.goto(DEV_SERVER.bare(DEV_SERVER.playerUrl(1)));
+
+        const frame = page.frameLocator(DEV_SERVER.iframeSelector('ui'));
+        await expect(frame.getByTestId('day')).toHaveText('Day 1');
+    });
+    ```
+
+    `playerUrl(team, participant?)` is 1-based. `observeUrl`, `waitingRoomUrl`, `setupUrl`, and the other builders are in the [e2e API reference](../api/sdk-e2e.md#dev_server).
+
+5. Act through the game's own controls, or as the facilitator with `runCommand`, and read the result with `getState`:
+
+    ```typescript
+    import { getState, runCommand } from '@seriousgaming/sdk/e2e';
+
+    await runCommand({ type: 'tick' });
+    expect((await getState()).session.completedTicks).toBe(1);
+    ```
+
+    A refused command answers `{ ok: false, outcome }` rather than throwing.
+
+6. Reach the failure paths your UI must handle by arming a fault, which fires once:
+
+    ```typescript
+    await runCommand({ type: 'armFault', fault: 'conflict' });
+    ```
+
+    The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
+
+7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)`.
+
+## Verify
+
+```bash
+pnpm run test:e2e
+```
+
+Every spec passes. Add `--headed` to watch, or `--debug` to step through.
+
+## Troubleshooting
+
+| Problem                               | Solution                                                                                           |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| The run hangs after the last test     | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
+| Tests pass alone and fail in a suite  | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added   |
+| Iframe content is not there yet       | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`)                         |
+| The `/e2e` import does not resolve    | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json`                           |
+| Every spec fails on a missing browser | Run `pnpm exec playwright install chromium` after a Playwright upgrade                             |
+
+## Related
+
+- [Testing guide: browser tests](../guides/testing.md#browser-e2e-tests-playwright)
+- [`@seriousgaming/sdk/e2e` reference](../api/sdk-e2e.md)
+- [Test a user interface](test-user-interface.md)

package/dist/docs/recipes/end-game-on-condition.md

@@ -0,0 +1,154 @@
+# End a game when a condition is met
+
+Stop a game automatically when a goal is reached, rather than after a fixed number of ticks.
+
+**Keywords:** dynamic ticks, goal-based game, end condition, complete, finish game, variable length, no fixed ticks
+
+## What you'll build
+
+An engine that ends the game once a target value in context is reached, by returning `complete: true` from `Run`. The manifest will have no `maxTicks` field: play continues until the condition fires. No tick controller is needed; that is only for timing ticks.
+
+## Prerequisites
+
+- A package with an engine and at least one capability that your condition will check
+- `seriousgaming.sdk.json` in your working directory
+
+## Steps
+
+### 1. Give the engine the target
+
+Put the target in a settings resource, so a scenario or a facilitator can change it, and list it in the engine's `settings`:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "goal",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "ProfitTarget": { "type": "number", "default": 10000 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+pnpm run sdk update engine --patch '[{
+  "op": "add",
+  "path": "/definition/settings",
+  "value": ["goal"]
+}]'
+pnpm run generate
+```
+
+If the engine already lists settings, append instead, with `"path": "/definition/settings/-"` and `"value": "goal"`.
+
+### 2. Return `complete` from `Run`
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const next = { ...context /* ...this round's updates */ };
+    return {
+        capabilities: next,
+        complete: next.financials.Profit >= settings.goal.ProfitTarget,
+    };
+};
+```
+
+`complete: true` ends the game for the team this `Run` ran for; leaving it out carries on. How that plays out across teams, and what undo does, is in [Game completion](../guides/tick-controller.md#game-completion).
+
+### 3. Drop the tick ceiling
+
+Remove `maxTicks` from `seriousgaming.sdk.json` (or keep it as a safety ceiling):
+
+```bash
+pnpm run sdk update package --patch '[{ "op": "remove", "path": "/maxTicks" }]'
+```
+
+> `build` warns that only the engine can end the game. That is expected here.
+
+### 4. Build
+
+```bash
+pnpm run build
+```
+
+## Verify
+
+```bash
+# Initialise
+pnpm run sdk init
+
+# Advance ticks until the goal fires
+pnpm run sdk tick
+
+# Once the condition is met the team is complete, and another tick exits with an error
+pnpm run sdk view
+```
+
+You can also start the dev server: tick requests are rejected and the dev drawer's **Tick** button is disabled once the game is complete.
+
+```bash
+pnpm run sdk dev
+```
+
+## Troubleshooting
+
+| Problem                             | Solution                                                                                         |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `complete` never becomes `true`     | Add a `console.log` in `Run` to inspect the context values being checked                         |
+| Type errors in logic.ts             | Run `pnpm run generate` to regenerate `types.ts`                                                 |
+| Game completes immediately (tick 0) | Your condition is true on the initial state; check your init logic or raise the target threshold |
+| Want a hard ceiling too             | Keep a `maxTicks` field in the manifest: both apply, and whichever triggers first ends the game  |
+
+## Variations
+
+### End after any team reaches the goal (aggregate engine)
+
+An aggregate engine sees every team at once. `complete: true` under `shared` ends the game for all of them; on a `teams` entry it ends it for that team alone:
+
+```typescript
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    teams,
+    settings,
+}) => ({
+    shared: {
+        capabilities: {},
+        complete: teams.some((t) => t.context.financials.Profit >= settings.goal.ProfitTarget),
+    },
+    teams: teams.map((t) => ({ capabilities: t.context })),
+});
+```
+
+Replace `.some` with `.every` to require all teams to reach the goal before the game ends.
+
+### End the moment a participant's write reaches the goal
+
+To end the game on the write itself rather than at the next tick, use a tick controller that reads the capability (see [From the tick controller](../guides/tick-controller.md#from-the-tick-controller)):
+
+```typescript
+export const GetTickController: GetTickControllerFunction<Context, Settings> = async ({
+    context,
+    settings,
+}) => ({
+    enabled: false,
+    complete: context.financials.Profit >= settings.goal.ProfitTarget,
+});
+```
+
+The tick controller receives the target only if it lists `goal` in its own `settings` too.
+
+### Automatic ticks with a goal
+
+Timing is what a tick controller is for. Return `enabled: true` and an `intervalMs`, and keep the goal in the engine's `complete`:
+
+```typescript
+return { intervalMs: 30_000, enabled: true };
+```
+
+The game ticks automatically every 30 seconds and stops as soon as `Run` reports the profit target reached.
+
+## Related
+
+- [Game completion](../guides/tick-controller.md#game-completion): both ways to end a game, what completion does, and multi-team patterns
+- [Create a tick controller](create-tick-controller.md): add timer-based automatic ticking
+- [Create a settings resource](create-settings.md): parameters a scenario or facilitator can change

package/dist/docs/recipes/fix-duplicate-packages.md

@@ -0,0 +1,101 @@
+# Fix duplicate package errors in a UI
+
+Resolve 'Invalid hook call' and similar errors caused by multiple copies of the same package
+being loaded by the dev server.
+
+**Keywords:** duplicate react, invalid hook call, resolve dedupe, vite config, @react-three/fiber,
+emotion, multiple instances, hooks error, cannot read properties of null useState, shared package,
+empty data, duplicate sdk
+
+Two copies of React in one page (a library that bundles its own, such as `@react-three/fiber`) make every hook fail. Two copies of `@seriousgaming/sdk` fail silently instead: the second copy's hooks find none of the host's providers and read empty data. Both are fixed by resolving each package to one copy.
+
+## Prerequisites
+
+- A user interface that uses a third-party React library
+- The dev server (`pnpm run sdk dev`) running and showing the error above
+
+## Steps
+
+### 1. Add a `vite.config.ts` to your project root
+
+Create `vite.config.ts` alongside your `seriousgaming.sdk.json`:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    resolve: {
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+        ],
+    },
+});
+```
+
+`resolve.dedupe` tells Vite to resolve these packages to the single copy at the project root,
+however many paths in the dependency tree lead to them.
+
+If your package was created with `sdk new package` and already has a `vite.config.ts`, add
+entries to its `dedupe` list rather than creating a second file.
+
+### 2. Restart the dev server
+
+```bash
+pnpm run sdk dev
+```
+
+The SDK picks up your `vite.config.ts` automatically, and applies the same file to
+`pnpm run sdk build`, so one file fixes both dev and production builds.
+
+### 3. Add more entries when you need them
+
+Add a package to `dedupe` whenever you install a library that:
+
+- Lists React (or Emotion) as a **peer dependency**, and
+- Also `require()`s that peer internally in its own bundled code
+
+Or any package that holds React context and that more than one path leads to, as the SDK does. A package created with `sdk new package` lists React, Emotion, the SDK and the deck already, in both `vite.config.ts` and `vitest.config.ts`.
+
+Example with additional libraries:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    resolve: {
+        dedupe: [
+            'react',
+            'react-dom',
+            '@emotion/react',
+            '@emotion/styled',
+            '@seriousgaming/sdk',
+            '@seriousgaming/deck',
+            '@react-three/fiber',
+        ],
+    },
+});
+```
+
+## Verify
+
+Reload the page in the dev server. The component that raised 'Invalid hook call' renders, and
+the browser console shows no hook errors. Run `pnpm run sdk build` to confirm the production
+build is clean too.
+
+## Troubleshooting
+
+| Problem                                  | Solution                                                                                                                                                                        |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The error persists after the restart     | Add the library that bundles React itself (for example `@react-three/fiber`) to `dedupe`                                                                                        |
+| The SDK warns about two Vite configs     | Remove the `vite.config.ts` inside `ui/` and keep one at the project root; see [Customising Vite](../guides/ui.md#customising-vite-dev-and-build)                               |
+| A Vite option in your file has no effect | The SDK owns structural fields (`root`, `base`, build output, entry points); additive options such as `resolve.dedupe`, `resolve.alias`, `optimizeDeps`, and `plugins` merge in |
+
+## Related
+
+- [Customising Vite](../guides/ui.md#customising-vite-dev-and-build): where the file goes and what merges
+- [User interfaces guide](../guides/ui.md)