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

package/dist/docs/recipes/take-a-file-in-an-endpoint.md

@@ -0,0 +1,82 @@
+# Take a file in an endpoint
+
+**Keywords:** file upload, upload a file to an endpoint, image upload, PDF upload, blob input, data URI, base64, attach file, AI agent upload, MCP file, API upload, script upload
+
+Let an endpoint accept a file, such as a team photo or a research PDF, from a game UI, a script calling the API, or an AI agent.
+
+## Prerequisites
+
+- An endpoint that already works (see [Create an endpoint](create-endpoint.md))
+- Somewhere for the file to go: usually a capability holding its `blob:` reference, which a screen shows with `getAssetUrl` or logic reads with `readAsset` or `extractText`
+
+## Steps
+
+1. Mark the request property as a file with `blob`, saying which types it takes and how large:
+
+    ```json
+    {
+        "definition": {
+            "requestSchema": {
+                "type": "object",
+                "properties": {
+                    "document": {
+                        "type": "string",
+                        "description": "The research, as a PDF.",
+                        "blob": { "accept": ["application/pdf"], "maxBytes": 5242880 }
+                    }
+                },
+                "required": ["document"],
+                "additionalProperties": false
+            },
+            "writes": ["upload"]
+        }
+    }
+    ```
+
+    `accept` takes media types and `type/*` wildcards (`"image/*"`), and allows any type when left out. The property must be `"type": "string"`, or the build fails.
+
+2. Regenerate the types, so the field is typed as a reference:
+
+    ```bash
+    pnpm run sdk generate
+    ```
+
+    `Request['document']` is now `` `blob:${string}` ``.
+
+3. Use the reference in the handler:
+
+    ```typescript
+    export const Handle: Handler = async ({ request, context }) => ({
+        response: { replaced: context.upload.DocumentBlobId !== '' },
+        capabilities: { upload: { ...context.upload, DocumentBlobId: request.document } },
+    });
+    ```
+
+    The runtime has already checked the file against the declaration, including its real type from its bytes rather than the one the caller claimed, and stored it. There is nothing to decode or check here. To read the bytes, call `callbacks.readAsset(request.document)`.
+
+4. If the endpoint is for callers outside the game, say how to send the file in its description (see [Make an endpoint callable from outside the game](make-an-endpoint-external.md)):
+
+    > Send a PDF of at most 5 MB: inline as a data: URI, or upload it first and send the blob: reference.
+
+    A caller sends either a `blob:` reference or a `data:` URI, never a URL (see [Files in and out](../guides/endpoints.md#files-in-and-out)).
+
+## Verify
+
+- `pnpm run sdk endpoint call attachresearch --external --team 1 --attach document=./research.pdf` succeeds, and `pnpm run sdk view` shows the reference on the team's board
+- `pnpm run sdk blob upload ./research.pdf`, then the call with `--request '{"document": "blob:..."}'`, succeeds the same way
+- The same call with a PNG is refused before your handler runs
+
+## Troubleshooting
+
+- _'must be a blob: reference or a data: URI'_: The caller sent something else, commonly a URL or a bare id without `blob:`
+- _'claims image/png, but its bytes are application/pdf'_: The `data:` URI's type does not match the file. Fix the type the caller sends
+- _'is image/gif, which is not one of ...'_: Widen `accept`, or send a type it lists
+- _'names a blob this session does not hold'_: The reference is wrong, or the file was uploaded to a different session
+- _'carries more than ... bytes a data: URI may carry inline'_: Upload the file first and send the reference
+- _'declares `blob` but is not `"type": "string"`'_: A file field is a string; change its type
+
+## Related
+
+- [Endpoints (concept)](../guides/endpoints.md)
+- [File handling](../guides/file-handling.md)
+- [Make an endpoint callable from outside the game](make-an-endpoint-external.md)

package/dist/docs/recipes/test-a-multi-role-game.md

@@ -0,0 +1,51 @@
+# Test a multi-role game in the dev server
+
+Drive a game that needs several participants per team (for example a buyer and a seller who each act before a tick advances) from a single dev-server session, using the per-team participant roster.
+
+**Keywords:** multiple participants, roles, multi-role, participant roster, add participant, rename participant, open participant, buyer seller, connected, /play participant
+
+## What you'll build
+
+A running session where one team has several named participants, each opened in its own browser tab and acting independently, so a role-based interaction can be played through end to end.
+
+## Prerequisites
+
+- A game whose UI branches on participant identity via `useUserInterfaceParticipant()` (see [Create a user interface](create-user-interface.md))
+- The dev server running (`pnpm run sdk dev`)
+
+## Steps
+
+### 1. Open the console and expand a team
+
+A fresh team starts with one participant, at `/team/<n>/player/1`. Participants are positions in the URL, 1-based, so there is no id to look up and nothing to resolve.
+
+### 2. Add and name the participants you need
+
+Use **Add participant** on the team's row in the dev drawer to create each role, or `pnpm run sdk participant add Buyer --team 1` from the CLI, which names it too. To rename one later, use `pnpm run sdk participant rename <participantId> <name>`; `pnpm run sdk view` lists the ids. Creating a participant fires the `participantJoin` hook, exactly as it would in production, so any join-driven setup runs.
+
+If the game declares `teams.perTeam.minParticipants` / `maxParticipants`, the roster shows an advisory caption (for example '2–5 recommended for this scenario'). It is guidance only and never blocks adding or removing.
+
+### 3. Open each participant in its own tab
+
+Open `/team/<n>/player/<p>` for each role, in its own tab, and arrange them side by side. Each tab holds its own live connection, so every participant shows as connected at the same time, which is what a multi-role game gates on.
+
+### 4. Drive the interaction
+
+Act as each role in its tab. Because each tab carries its own participant identity, every state mutation is attributed to the right actor, so per-participant validators see the correct actor and the game advances once the roles have acted.
+
+## Verify
+
+- The team's row in the dev drawer counts every participant you added
+- Opening two participants in two tabs shows both as connected in `pnpm run sdk view` (each participant carries `connected`)
+- Renaming a participant updates its name in every open view
+
+## Troubleshooting
+
+- **'No such participant' when opening a link.** The URL asks for a seat the team does not have: opening `/team/1/player/3` before adding a third participant, or following a stale link. The screen says how many the team holds and offers **Add participant**. A second tab is not a second participant, so add them in step 2 first. The dev server does not invent one, and does not serve an unidentified surface: a write it cannot attribute to a participant would skip the game's validators, so it is refused instead
+- **A participant shows as disconnected.** Its tab is closed. Connection state is live only; it is never persisted, so every participant starts disconnected after a dev-server restart even though its name is restored
+- **A new participant did not trigger role setup.** Role assignment usually lives in a `participantJoin` hook. Confirm the game declares the hook (see [Create a hook](create-hook.md))
+
+## Related
+
+- [Accessing participant info](../guides/ui.md#accessing-participant-info)
+- [Test UIs end to end with Playwright](e2e-testing.md): drive several participants from a test

package/dist/docs/recipes/test-user-interface.md

@@ -0,0 +1,95 @@
+# Test a user interface
+
+Write and run component tests for a user interface with Vitest, React Testing Library, and the SDK's render helpers.
+
+**Keywords:** test UI, unit test, React testing, App.test.tsx, vitest, testing library, mock context, setData, controlled input, renderUserInterface, renderSessionUserInterface, renderSettingsEditor, mock participant, participant roster, sessionKey
+
+## Prerequisites
+
+- A user interface, with the scaffolded `vitest.config.ts`, `test-setup.ts`, and `src/App.test.tsx`
+
+## Steps
+
+1. Open the test beside the component: `ui/src/App.test.tsx` for the game UI (`session/src/`, `waiting_room/src/`, `setup/src/` and the others for theirs).
+
+2. Render through the helper for the surface, giving it only what the test cares about. Every other context value has a complete default, so never build the providers by hand:
+
+    ```tsx
+    import { fireEvent, screen } from '@testing-library/react';
+    import { renderUserInterface } from '@seriousgaming/sdk/ui/testing';
+    import { describe, expect, it, vi } from 'vitest';
+
+    import { defaultContext, defaultSettings } from '../defaults';
+    import './i18n';
+    import App from './App';
+
+    describe('Dashboard', () => {
+        it('shows the current stock', () => {
+            renderUserInterface(<App />, {
+                data: { ...defaultContext, inventory: { Stock: 100 } },
+                settings: defaultSettings,
+            });
+            expect(screen.getByLabelText(/stock/i)).toHaveValue(100);
+        });
+    });
+    ```
+
+    Use `renderSessionUserInterface` for a session UI and `renderSettingsEditor` for setup and the scenario editor (see [Using render helpers](../guides/testing.md#using-render-helpers)).
+
+3. Assert on writes with a mock `setData`. Drive a controlled input with `fireEvent.change`, since a mocked `setData` never updates the displayed value between keystrokes:
+
+    ```tsx
+    it('writes the new price', () => {
+        const setData = vi.fn();
+        renderUserInterface(<App />, { data: defaultContext, settings: defaultSettings, setData });
+
+        fireEvent.change(screen.getByLabelText(/price/i), { target: { value: '50' } });
+
+        expect(setData).toHaveBeenCalledWith({ pricing: { Price: 50 } });
+    });
+    ```
+
+4. Pass any callback you assert on. Callbacks you leave out default to no-ops:
+
+    ```tsx
+    const requestTick = vi.fn();
+    renderUserInterface(<App />, {
+        data: defaultContext,
+        settings: defaultSettings,
+        callbacks: { requestTick },
+    });
+    ```
+
+5. For a participant-aware UI, pass `participant` and `participants`, built with `createMockParticipant` and `createMockParticipants`. The roster defaults to `[]`, the real first-render state:
+
+    ```tsx
+    import { createMockParticipants } from '@seriousgaming/sdk/ui/testing';
+
+    renderUserInterface(<App />, { data: defaultContext, participants: createMockParticipants(3) });
+    ```
+
+6. Run the tests:
+
+    ```bash
+    pnpm run test
+    ```
+
+## Verify
+
+Every test passes, and `pnpm typecheck` accepts the mock data: `defaultContext` and `defaultSettings` come from the generated `defaults.ts`, so a missing capability is a type error.
+
+## Troubleshooting
+
+| Problem                                    | Solution                                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 'Invalid hook call'                        | Two copies of React; see [Fix duplicate package errors in a UI](fix-duplicate-packages.md)                                                       |
+| 'Found multiple elements with the text: X' | `test-setup.ts` must run `cleanup` after each test                                                                                               |
+| `setData` is never called                  | `userEvent.type` on a controlled input; use `fireEvent.change`                                                                                   |
+| A hook throws 'must be used inside'        | The component was rendered without a helper. Render through `renderUserInterface` or its siblings                                                |
+| A write the game accepts fails the test    | The mock does not merge as the host does; use `mergingSetData` (see [Design state for concurrent writes](design-state-for-concurrent-writes.md)) |
+
+## Related
+
+- [Testing guide](../guides/testing.md): every render helper and option
+- [Test a whole game in-process](test-with-engine.md)
+- [Test UIs end to end with Playwright](e2e-testing.md)

package/dist/docs/recipes/test-with-engine.md

@@ -0,0 +1,115 @@
+# Test a whole game in-process
+
+Test your whole game (engine, hooks, validators, endpoints, and completion) in one Node.js process, with no dev server, browser, or subprocess.
+
+**Keywords:** engine test, createTestSession, test session, in-process test, vitest engine, test game logic, programmatic client, setData, tick
+
+## Prerequisites
+
+- A game package with its dependencies installed. One made with `sdk new package` already has the engine test setup: skip to step 4
+
+## Steps
+
+1. Add the test session's package, if it is not already a dependency:
+
+    ```bash
+    pnpm add -D @seriousgaming/sdk-tools
+    ```
+
+2. Create `vitest.engine.config.ts` in the package root:
+
+    ```typescript
+    import { defineConfig } from 'vitest/config';
+
+    export default defineConfig({
+        test: {
+            environment: 'node',
+            testTimeout: 60_000,
+            include: ['testing/engine/**/*.engine.test.ts'],
+        },
+    });
+    ```
+
+    In `vitest.config.ts`, add `exclude: ['testing/**', '**/node_modules/**']` to `test`, so the jsdom and engine configs do not pick up each other's files.
+
+3. Add the script to `package.json`:
+
+    ```json
+    { "scripts": { "test:engine": "vitest run --config vitest.engine.config.ts" } }
+    ```
+
+4. Write `testing/engine/game.engine.test.ts`. Type the session with the engine's generated `Context` and `SharedContext`, so its helpers need no casts:
+
+    ```typescript
+    import { fileURLToPath } from 'url';
+
+    import { createTestSession, type TestSession } from '@seriousgaming/sdk-tools/client';
+    import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+    import type { Context, SharedContext } from '../../engine/types';
+
+    const PACKAGE_PATH = fileURLToPath(new URL('../..', import.meta.url));
+
+    describe('mygame', () => {
+        let session: TestSession<Context, SharedContext>;
+
+        beforeEach(async () => {
+            session = await createTestSession<Context, SharedContext>({
+                packagePath: PACKAGE_PATH,
+            });
+        });
+
+        afterEach(async () => {
+            await session.close();
+        });
+
+        it('calculates revenue from workers and price', async () => {
+            await session.setData(0, { workers: { WorkerCount: 20 }, pricing: { Price: 10 } });
+
+            expect((await session.tick()).ok).toBe(true);
+
+            const { context } = session.team(0);
+            expect(context.production.Production).toBe(1000);
+            expect(context.revenue.Revenue).toBe(10_000);
+        });
+    });
+    ```
+
+    `setData(0, ...)` writes as team 0's first participant through the game UI, so the write is held to the UI's `writes` and your validators judge it. Assert on a computed value, not only on the value you wrote.
+
+5. Optional: choose what the model answers. A test session answers `generateText`, `generateSpeech`, and `extractText` from offline stubs; override one with `callbacks`:
+
+    ```typescript
+    session = await createTestSession<Context, SharedContext>({
+        packagePath: PACKAGE_PATH,
+        callbacks: {
+            generateText: async () => ({
+                content: [{ type: 'text' as const, text: 'mock response' }],
+                stopReason: 'endTurn' as const,
+            }),
+        },
+    });
+    ```
+
+## Verify
+
+```bash
+pnpm test:engine
+```
+
+Every test passes, each in well under a second.
+
+## Troubleshooting
+
+| Problem                                         | Solution                                                                                                 |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `TextEncoder` invariant in the default test run | The jsdom config picked up the engine test. Add `testing/**` to `exclude` in `vitest.config.ts` (step 2) |
+| A context field is a type error                 | The capability is not in the `Context` you passed; intersect the hook's `Context` if a hook keeps it     |
+| `setData` answers `validation-rejected`         | Your validator refused it. Pass `{ as: 'system' }` to arrange state the test then plays on               |
+| Tests are slow or time out                      | A test passes `services: 'platform'`, or a callback override calls the network                           |
+
+## Related
+
+- [Engine testing guide](../guides/engine-testing.md): every `createTestSession` option, completion, endpoints, timers, and scenarios
+- [Testing guide](../guides/testing.md): unit tests with `logicArgs`, and component tests
+- [Test UIs end to end with Playwright](e2e-testing.md)

package/dist/docs/recipes/upload-and-display-files.md

@@ -0,0 +1,148 @@
+# Upload and display files
+
+Let a participant attach a file (a PDF, CSV, or image) in the game UI, show it back, and optionally summarise it in the engine.
+
+**Keywords:** upload file, file upload, attach document, blob, asset reference, uploadBlob, getAssetUrl, useAssetUrl, extractText, embed PDF
+
+## Prerequisites
+
+- A game with an engine and a game UI
+- For step 5, platform access for the LLM (see [LLM integration](../guides/llm-integration.md#configuration))
+
+## Steps
+
+1. Create a capability to hold the file's reference:
+
+    ```bash
+    pnpm run sdk new capability '{
+      "definition": {
+        "identifier": "upload",
+        "variablesSchema": {
+          "type": "object",
+          "properties": {
+            "DocumentRef": { "type": "string", "default": "" }
+          },
+          "required": ["DocumentRef"],
+          "additionalProperties": false
+        }
+      }
+    }'
+    ```
+
+2. Let the game UI write it (`writes` makes it readable too):
+
+    ```bash
+    pnpm run sdk update ui --patch '[
+      { "op": "add", "path": "/definition/writes/-", "value": "upload" }
+    ]'
+    ```
+
+3. Upload from the UI and store the reference. Read the empty string as 'nothing uploaded':
+
+    ```tsx
+    import {
+        useAssetUrl,
+        useUserInterfaceCallbacks,
+        useUserInterfaceData,
+    } from '@seriousgaming/sdk/ui';
+
+    import type { Context, Settings } from '../types';
+
+    export function ResearchPanel() {
+        const { uploadBlob } = useUserInterfaceCallbacks();
+        const { data, setData } = useUserInterfaceData<Context, Settings>();
+        const reference = data.upload.DocumentRef;
+        const url = useAssetUrl(reference); // undefined while the reference is ''
+
+        const onFile = async (event: React.ChangeEvent<HTMLInputElement>) => {
+            const file = event.target.files?.[0];
+            if (!file) return;
+            await setData({ upload: { DocumentRef: await uploadBlob(file) } });
+        };
+
+        return url ? (
+            <embed src={url} type="application/pdf" style={{ width: '100%', height: 500 }} />
+        ) : (
+            <input type="file" accept=".pdf" onChange={onFile} />
+        );
+    }
+    ```
+
+4. Optional: create the capability the engine writes its summary to, and let the engine read the upload, write the summary, and call the two services. Calls to a service the engine does not list in `uses` throw:
+
+    ```bash
+    pnpm run sdk new capability '{
+      "definition": {
+        "identifier": "summary",
+        "variablesSchema": {
+          "type": "object",
+          "properties": { "Summary": { "type": "string", "default": "" } },
+          "required": ["Summary"],
+          "additionalProperties": false
+        }
+      }
+    }'
+    pnpm run sdk update engine --patch '[
+      { "op": "add", "path": "/definition/reads/-", "value": "upload" },
+      { "op": "add", "path": "/definition/writes/-", "value": "summary" },
+      { "op": "add", "path": "/definition/uses", "value": ["extractText", "generateText"] }
+    ]'
+    ```
+
+    If the engine already declares `uses`, append to it instead (`"path": "/definition/uses/-"`).
+
+5. Optional: summarise the file in the engine's `Run`:
+
+    ```typescript
+    import { getText, type RunFunction } from '@seriousgaming/sdk';
+
+    import type { Callbacks, Context, Settings } from './types';
+
+    export const Run: RunFunction<Context, Settings, Callbacks> = async ({
+        context,
+        callbacks,
+    }) => {
+        const reference = context.upload.DocumentRef;
+        if (!reference) return { capabilities: context };
+
+        const { content } = await callbacks.extractText(reference);
+        const result = await callbacks.generateText({
+            prompt: `Summarise this market research:\n\n${content}`,
+            tier: 'standard',
+        });
+        return {
+            capabilities: { ...context, summary: { ...context.summary, Summary: getText(result) } },
+        };
+    };
+    ```
+
+    Typed with the generated `Callbacks`, both services are present rather than optional. For raw bytes rather than text, use `readAsset` (see [Reading an asset in an engine](../guides/file-handling.md#reading-an-asset-in-an-engine)).
+
+## Verify
+
+From the CLI:
+
+```bash
+REFERENCE=$(pnpm run --silent sdk blob upload ./test.pdf --json | jq -r '.data.reference')
+pnpm run sdk patch "[{\"op\":\"replace\",\"path\":\"/upload/DocumentRef\",\"value\":\"$REFERENCE\"}]"
+pnpm run sdk tick
+pnpm run sdk view
+```
+
+`summary.Summary` holds the model's summary. In the dev server, uploading a PDF from a team's screen replaces the input with the embedded document.
+
+## Troubleshooting
+
+| Problem                              | Solution                                                                                                          |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `data.upload` is a type error        | `upload` is not in the UI's `reads` or `writes`; step 2 regenerates `types.ts`                                    |
+| `UndeclaredApiUseError` at tick time | The engine calls a service missing from its `uses` (step 4)                                                       |
+| The engine never sees the reference  | Add `upload` to the engine's `reads`                                                                              |
+| The PDF does not render              | Match the `<embed>` type to the file; see [Supported file types](../guides/file-handling.md#supported-file-types) |
+| `LLMClientError` from `generateText` | Platform access is not configured; see [Environment variables](../environment-variables.md)                       |
+
+## Related
+
+- [File handling guide](../guides/file-handling.md): references, uploading, displaying, and reading files
+- [Declare the runtime callbacks a resource uses](declare-api-uses.md)
+- [Take a file in an endpoint](take-a-file-in-an-endpoint.md)

package/dist/docs/recipes/use-request-play.md

@@ -0,0 +1,65 @@
+# Use requestPlay in a setup screen
+
+Leave the configuration step and start the game from within your setup screen, so operators can move to play from your own control as well as from the host's Play button.
+
+**Keywords:** requestPlay, request play, start game, setup play, custom play button, setup submit, leave configuration step
+
+## What you'll build
+
+A setup screen with a custom 'Start' button that moves the session from its configuration step to play when clicked. The host's own Play button stays: a runtime always renders it, and no game can hide it.
+
+## Prerequisites
+
+- An existing setup screen (see [Create a setup screen](create-setup.md))
+
+## Steps
+
+### 1. Call `requestPlay` from your setup screen
+
+Use the `useSettingsEditorCallbacks` hook and call `requestPlay` when the operator is ready to move on:
+
+```typescript
+import { useSettingsEditorCallbacks } from '@seriousgaming/sdk/ui';
+
+function SetupPanel() {
+    const { requestPlay } = useSettingsEditorCallbacks();
+
+    return (
+        <button onClick={() => requestPlay()}>
+            Start game
+        </button>
+    );
+}
+```
+
+### 2. Start the dev server and verify
+
+```bash
+pnpm run sdk dev
+```
+
+Click your custom button. The session should leave the configuration step and start play.
+
+## Verify
+
+- [ ] Clicking the custom button moves the session from the configuration step to play
+- [ ] Any setting changes made before clicking are preserved
+
+## Troubleshooting
+
+**Nothing happens when clicking the button in the scenario editor**
+
+That is expected. `requestPlay` means something only in `setup`; the host ignores it from `scenario_editor`, which may have no session to start. The callback is present in both because one wrapper, `SettingsEditorWrapper`, serves both slots.
+
+**Two Play controls are visible**
+
+That is expected. The host always renders its own, so your control is an addition rather than a replacement: a form with its own finish button at the bottom, say. A game cannot hide the host's, because a bug in your own control would otherwise strand a facilitator on the configuration step with no way forward.
+
+**`useSettingsEditorCallbacks` throws an error**
+
+The hook must be called inside a component rendered within `SettingsEditorWrapper`. The scaffolded `src/main.tsx` provides it, so check your component is a descendant of it.
+
+## Related
+
+- [Use requestTick in a UI](./use-request-tick.md)
+- [Building a setup screen](../guides/setup.md)

package/dist/docs/recipes/use-request-tick.md

@@ -0,0 +1,75 @@
+# Use requestTick in a UI
+
+Trigger the next game tick from within your user interface, so participants submit their decisions via your own button. This is how games advance: there is no built-in next tick button, so every game provides its own tick control.
+
+**Keywords:** requestTick, request tick, submit, next tick, end turn, custom submit button, tick from UI
+
+## What you'll build
+
+A user interface with a submit button that advances the game to the next tick when clicked.
+
+## Prerequisites
+
+- An existing user interface (see [Create a user interface](create-user-interface.md))
+- An existing game that includes the UI (see [Shape your game](create-game.md))
+
+## Steps
+
+### 1. Call `requestTick` from your UI component
+
+Use the `useUserInterfaceCallbacks` hook and call `requestTick` when the participant submits:
+
+```typescript
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+function DecisionPanel() {
+  const callbacks = useUserInterfaceCallbacks();
+
+  const handleSubmit = async () => {
+    await callbacks.requestTick();
+  };
+
+  return (
+    <button onClick={handleSubmit}>
+      Submit Decision
+    </button>
+  );
+}
+```
+
+`requestTick` is a required member of `UserInterfaceCallbacks` and returns a `Promise<void>`. It resolves once the tick has finished and context is updated, and rejects with a `MutationError` when the tick cannot run (for example, the tick limit has been reached).
+
+The same callback is available to session UIs, so a session UI provides its own tick controls the same way (the scaffolded starter package wires all of them).
+
+### 2. Start the dev server and verify
+
+```bash
+pnpm run sdk dev
+```
+
+Click your custom button. The game should advance to the next tick and your UI should receive the updated context.
+
+During development you can also advance ticks without a game control: the dev drawer (press the backtick key) has a developer-only **Tick** button.
+
+## Verify
+
+- [ ] Clicking the custom button advances the tick counter
+- [ ] Context updates are reflected in your UI after each tick
+
+## Troubleshooting
+
+**Nothing happens when clicking the button**
+
+Await the returned promise and catch the rejection: a tick the host refuses rejects with a `MutationError` rather than failing silently.
+
+**`useUserInterfaceCallbacks` throws an error**
+
+The hook must be called inside a component rendered within `UserInterfaceWrapper`. This is provided automatically by the SDK template, so check your component is a descendant of `UserInterfaceWrapper`.
+
+**UI shows a brief flicker after calling `setData` then `requestTick`**
+
+When you call `setData({ ... }); callbacks.requestTick();`, the `setData` change is visible immediately but the tick is asynchronous. Between the two, UIs show the raw `setData` values without any engine-computed results. This resolves once the tick completes (typically a few milliseconds). See [Combining setData with requestTick](../guides/ui.md#combining-setdata-with-requesttick) for strategies to handle the intermediate state.
+
+## Related
+
+- [User interfaces guide: requesting a tick](../guides/ui.md#requesting-a-tick)