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

package/dist/docs/guides/ui.md

@@ -0,0 +1,1389 @@
+# Building user interfaces
+
+This guide shows you how to create and develop custom user interfaces for your games.
+
+## What you'll learn
+
+- How to create a new user interface
+- How to read game context and settings
+- How to write to context and request a tick
+- How to work with participants, teams, observers, and walkthroughs
+- How to show the tick timer, localise, theme, and upload files
+- How to reach an LLM from a UI, through an endpoint
+
+## Creating a user interface
+
+The starter game already fills this slot, and `new` refuses a filled one with `RESOURCE_EXISTS`. In a package made by `new package`, change it with `update ui` instead, or start from `new package --empty`.
+
+Create a new user interface:
+
+```bash
+pnpm run sdk new ui '{
+  "definition": {
+    "reads": ["inventory", "sales", "pricing"],
+    "writes": [],
+    "settings": ["ui"]
+  },
+  "ui": {
+    "entrypoint": "index.html"
+  },
+  "rootDirectory": "."
+}'
+```
+
+`settings` names the settings resources the UI reads, here a `settings/ui/` declaring `RefreshRate` (create it first with `pnpm run sdk new settings`; see [Create settings](../recipes/create-settings.md)). Leave it out and the UI reads none.
+
+This creates a UI structure:
+
+```
+ui/
+├── ui.sdk.json
+├── index.html
+├── src/
+│   ├── main.tsx
+│   ├── App.tsx
+│   ├── App.test.tsx
+│   ├── i18n.ts
+│   └── theme.ts
+└── types.ts
+```
+
+## Accessing context and settings
+
+Access game context and settings in your React components:
+
+```typescript
+// src/App.tsx
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function Dashboard() {
+  const { data, settings } = useUserInterfaceData<Context, Settings>();
+
+  const { Stock } = data.inventory;
+  const { Revenue } = data.sales;
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>Current Stock: {Stock} units</p>
+      <p>Revenue: ${Revenue}</p>
+      <p>Refresh rate: {settings.ui.RefreshRate}ms</p>
+    </div>
+  );
+}
+
+export default Dashboard;
+```
+
+The `useUserInterfaceData` hook provides:
+
+- **`data`**: The game context (read-only by default)
+- **`settings`**: The settings resources this UI lists in `settings`, keyed by identifier (`settings.ui.RefreshRate`). Read-only, and fixed when play starts
+- **`completedTicks`**: The number of ticks this team has completed: `0` until the first tick commits, `N - 1` while round N is played. Use it to bound a review scrubber (see below)
+- **`isRoundProcessing`**: Whether the host is running a tick right now (see below)
+- **`setData`**: Function to update context (available only for capabilities in `writes`)
+
+### Saying a tick is processing
+
+In a shared-state game every team ticks together, so the host settles all of them in one go. In a large session that takes long enough for participants to see, and they did not press the button, so an unexplained pause reads as the screen having broken. `isRoundProcessing` lets you say what is happening:
+
+```typescript
+const { isRoundProcessing } = useUserInterfaceData<Context, Settings>();
+
+if (isRoundProcessing) {
+    return <p>Processing round…</p>;
+}
+```
+
+Show it in place of a countdown, which has nothing to count down to mid-tick.
+
+**Your writes still work.** This is a signal, not a closed window. A `setData` during a tick is queued by the host and applied after the tick, and its promise resolves when it commits, exactly as at any other time. So:
+
+- Disable a submit button on the flag if you would rather participants waited for the new numbers
+- Or leave it enabled, and nothing is lost
+
+Both are fine. Nothing about the flag changes whether a write is accepted.
+
+A session UI does not receive it, and does not need it: `requestTick` returns a promise, so a facilitator screen can render 'processing' between calling it and its resolution.
+
+### Reviewing past ticks
+
+`useUserInterfaceCallbacks()` exposes `getPastState(query)`, a read-only reader for committed past state, composed exactly like live `data`. Entry N is the state after tick N (after `Init`, for entry 0) with the decisions the next round entered on it, so it carries tick N's outcomes and those decisions together, and a value your engine clears each tick is still reviewable. One call serves every review, because the query spans the two axes a review screen varies:
+
+```typescript
+getPastState<Context>({
+    fromTick: 3, // required, inclusive
+    toTick: 8, // optional; omit to read fromTick alone
+    teams: 'all', // 'own' (default), 'all', or a 'team-N' id
+    capabilityIds: ['profit'], // optional projection
+});
+```
+
+It answers with one entry per (tick, team) it reaches, ascending by tick then by team. A tick that is not reviewable (`completedTicks` itself, which is the live board, or one that is undone, reset, or out of range) is simply an absent row rather than a null, so an empty array means the query reaches nothing. Tick 0 is not a played tick, so nothing is reviewable before the first tick. It rejects with a `TickSnapshotError` only on a genuine fault, and is not gated by `uses`. A session UI takes the same signature: having no own team, its `teams: 'own'` means the whole session.
+
+Each entry extends the live cross-team shape with the tick it was captured at, so a live row from `useUserInterfaceCrossTeamData()` and a historical row read identically and one renderer serves both.
+
+Debounce scrubbing and cache fetched entries, which are immutable within a session until an undo takes the newest tick back into live state. Note that a reset bulk-deletes reviewable history, making it a participant-visible action wherever a UI exposes review. See [Review a past day in a UI](../recipes/review-a-past-day.md) for the full pattern.
+
+For a chart or a table over several ticks, give the query a `toTick` rather than making a call per tick: one request, and `capabilityIds` narrows each returned context to the fields you plot. Reading history back from the host is what lets you stop keeping a growing log in context, which is otherwise delivered to every screen on every update.
+
+In a component, `usePastState(query)` does the bookkeeping for you. It reads when the query changes (compared by value, so an inline object is fine), keeps the last entries on screen while a new query loads, and drops the answer to any read a newer one has overtaken:
+
+```tsx
+import { usePastState } from '@seriousgaming/sdk/ui';
+
+const { completedTicks } = useUserInterfaceData<Context, Settings>();
+const { entries, error, loading, refetch } = usePastState<Context>(
+    completedTicks > 0 ? { fromTick: 0, toTick: completedTicks, capabilityIds: ['profit'] } : null
+);
+```
+
+Pass `null` to read nothing yet. `refetch()` reads the same query again. It works on the game UI, the waiting room, the session UI and a presentation, the surfaces that have `getPastState`.
+
+### Settings are what your UI declares
+
+`settings` holds exactly the settings resources listed in the UI's `settings`, and no others. A UI that needs one of the engine's values lists the same settings resource the engine does (`"settings": ["engine"]`) and reads `settings.engine.X`: there is no need to copy it into context at `Init`, and no copy to go stale.
+
+The reverse is how you keep a value off participant screens. An answer key, a hidden target, or a scoring rubric goes in a settings resource that only the engine declares, and it never reaches the browser.
+
+When you need a value in a UI, choose one:
+
+- Read a settings resource, by listing it in `settings`. Best for static setup that is fixed for the session
+- Write it into context from an engine and read it via `data`. Best when the value is computed or changes during play
+
+See [Settings](./settings.md#keeping-a-value-off-participant-screens) for the full picture.
+
+## Writing to context
+
+Update game context from user interactions:
+
+```typescript
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function PriceController() {
+  const { data, settings, setData } = useUserInterfaceData<Context, Settings>();
+
+  const handlePriceChange = (newPrice: number) => {
+    // Update only the capability this UI provides
+    setData({
+      price: { Price: newPrice }
+    });
+  };
+
+  return (
+    <input
+      type="number"
+      value={data.price.Price}
+      onChange={(e) => handlePriceChange(parseFloat(e.target.value))}
+      min={settings.ui.MinPrice}
+      max={settings.ui.MaxPrice}
+    />
+  );
+}
+```
+
+**Important:**
+
+- **Write access**: Only capabilities listed in `writes` can be updated via `setData`. The runtime enforces it: a write (or a `deletes` path) naming anything else is refused as `denied`, naming the key, and nothing of it is applied. Your generated types already forbid it, so this catches an untyped or hand-built payload
+- **Partial updates**: Pass only the fields you changed to `setData`
+- **Scoped by identifier**: Always key the update by the capability's identifier, which is its directory name (e.g., `price`)
+
+### How setData merges
+
+Each `setData` call sends only the update you pass; the host deep-merges it into the current context. Objects are merged recursively, while arrays, scalars, and `null` replace the existing value wholesale. Your local view applies the same merge immediately, so a minimal patch never blanks sibling fields you did not touch.
+
+This means you do not need to spread the whole capability into every write:
+
+```typescript
+// Preferred: send only what changed
+setData({ exercise: { Committed: true } });
+
+// Unnecessary (and harmful under concurrency): re-sending untouched fields
+setData({ exercise: { ...data.exercise, Committed: true } });
+```
+
+Sending minimal patches is what lets two participants on the same team submit different decisions at the same time without overwriting each other: writes that touch different fields merge cleanly on the host. A merge has no way to express deletion, so removing an entry is a separate instruction on the same write: `setData({}, { deletes: ['pinboard.Notes.' + noteId] })`. Deletions apply after the patch, so one call can replace an entry, and a path that resolves to nothing is a no-op.
+
+Because arrays replace wholesale, a shared array that participants read, modify, and write back is still a lost-update hazard even with minimal patches: two simultaneous appends each send an array missing the other's item. Model collaborative collections as objects keyed by a stable id instead, so concurrent writes touch disjoint keys and merge cleanly. See [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) for the full set of patterns, including clearing entries with `null` and arbitrating genuinely contested slots with a validator.
+
+### How setData timing works
+
+Understanding when `setData` changes become visible is critical for designing your game loop correctly.
+
+1. **Immediate in context**: When a UI calls `setData`, the change is merged into the game context right away. Other UIs reading the same capability will see the updated value immediately (via WebSocket sync in the dev server).
+
+2. **Engines process on next tick**: Engine `Run` functions only execute when a tick advances. They see whatever context exists at that point, including any `setData` changes made since the last tick.
+
+3. **Multiple `setData` calls accumulate**: If a participant changes Price to 50, then to 75 before the next tick, the engine will see 75. Only the final state matters.
+
+**Design implication**: Use `setData` for participant input within a tick (decisions, adjustments, form entries). Use tick advancement to trigger computation (the engine runs, state updates cascade). Don't try to run game logic inside `setData` handlers: that bypasses the tick mechanism and breaks the reactive spreadsheet model.
+
+```
+Player adjusts price via UI (setData)  →  context updated immediately
+Player clicks "Submit" (tick advances)  →  the engine runs with the new price
+                                        →  UIs re-render with computed results
+```
+
+## Requesting a tick
+
+User interfaces advance the game to the next tick using the `requestTick` callback. This is how games provide their 'Submit' control. There is no built-in next tick button, so every game that ticks manually needs one of these.
+
+```typescript
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+function DecisionPanel() {
+  const callbacks = useUserInterfaceCallbacks();
+
+  const handleSubmit = () => {
+    callbacks.requestTick?.();
+  };
+
+  return (
+    <button onClick={handleSubmit}>
+      Submit Decision
+    </button>
+  );
+}
+```
+
+During development, the dev drawer (press the backtick key) also has a developer-only **Tick** button, so you can advance the game before your control exists.
+
+See [Host controls](./games.md#host-controls) for what the host renders and what is left to your game.
+
+### Combining setData with requestTick
+
+A common pattern is to update context and immediately request a tick: for example, a 'Start exercise' button that sets an initial value and advances the game:
+
+```typescript
+const handleStart = () => {
+    setData({ exercise: { Started: true } });
+    callbacks.requestTick?.();
+};
+```
+
+This works correctly: the `setData` change is merged into context immediately, and the tick that follows will see `Started: true` when the engine runs. However, there is a brief intermediate state that is worth understanding:
+
+1. **`setData` merges immediately**: the local UI and all connected UIs see `Started: true` right away.
+2. **`requestTick` is asynchronous**: the tick message is sent to the host, which queues and executes the tick. This takes a few milliseconds.
+3. **Between steps 1 and 2**, UIs see the `setData` change but the engine has not yet run. If the engine computes derived values (e.g. a status message based on `Started`), the UI will briefly show the raw `setData` values without the engine-computed results.
+4. **After the tick completes**, the host broadcasts updated context to all UIs. This overwrites the intermediate state with the fully computed post-tick values.
+
+In most cases this intermediate state is invisible to the participant, because the tick completes in milliseconds. But if your UI derives display values from both `setData` fields and engine-computed fields, you may see a brief flicker. Two strategies to handle this:
+
+**Option A: UI-level loading state**: set a local loading flag before requesting the tick, and clear it when new context arrives:
+
+```typescript
+const [ticking, setTicking] = useState(false);
+
+const handleStart = () => {
+    setData({ exercise: { Started: true } });
+    setTicking(true);
+    callbacks.requestTick?.();
+};
+
+// Clear on next context push (setData from host resets the component)
+useEffect(() => {
+    setTicking(false);
+}, [data]);
+```
+
+**Option B: Drive display from engine-computed values only**: if possible, have your UI read from the engine's output capability rather than from the raw `setData` input. The engine output is only updated after the tick, so there is no intermediate state.
+
+### Awaiting state changes
+
+`setData` and `requestTick` each return a promise, as do a session UI's `undoTick` and `resetGame` and a setup screen or scenario editor's `updateSettings`. It resolves once the operation has committed (a `setData` once the write is persisted, a `requestTick` once that tick has finished and context is updated) and rejects with a `MutationError` when it fails. The error's `outcome` is a discriminated union you can branch on:
+
+- `conflict`: the write lost a race with a tick, and the runtime retried it itself and gave up. A person may try again; your code never retries it on its own
+- `superseded`: what the operation addressed has already moved on because somebody else did the same thing, such as a tick button pressed twice. Terminal but not a failure: the state is what the caller asked for
+- `validation-rejected`: a validator rejected the write; `outcome.rejections` carries the same detail delivered to `useUserInterfaceValidationRejections`
+- `denied`: the operation was not permitted (for example, a write of a capability this UI does not declare in `writes`)
+- `tick-failed`: the tick could not run (tick limit reached, game complete, or the executor threw)
+- `error`: anything else unexpected
+
+Reach for `useMutationReporter` rather than branching by hand. It awaits the write, tracks whether one is in flight, and hands you the failure to render:
+
+```tsx
+import { useMutationReporter } from '@seriousgaming/sdk/ui';
+
+const { run, pending, failure, dismiss } = useMutationReporter();
+
+<Button disabled={pending} onClick={() => run(() => setData({ exercise: { Revenue: 100 } }))}>
+    {t('save')}
+</Button>;
+{
+    failure && (
+        <Alert
+            onClose={dismiss}
+            action={failure.retry && <Button onClick={failure.retry}>{t('tryAgain')}</Button>}
+        >
+            {t('saveFailed')}
+        </Alert>
+    );
+}
+```
+
+`setData` also resolves with which tick the write landed in. If a participant submits as the tick is being processed the write commits into the next one, and `reporter.late` says so, carrying both the tick composed against and the tick committed into. That is not a failure (the write is in), but nothing else on screen distinguishes it from a decision that arrived in time.
+
+**The host retries; your surface never does.** A runtime using optimistic concurrency retries a losing write itself before it reports one, so a `conflict` reaching a surface is a write the host has already retried and given up on, and a surface must never retry it automatically. What a person can do is try again, so on a `conflict` (and only then) `failure.retry` is set: it runs the same operation again, resolving as `run` does. Put it behind a 'Try again' button, as the snippet above does, and never call it from an effect or a timer.
+
+Ignoring the returned promise still compiles, but it is a hazard rather than a convenience: the local view merges the change the moment it is sent, so a refused write leaves the participant looking at a decision the game never received. A no-floating-promises lint rule may start flagging unawaited calls; route them through `run` rather than marking them with `void`.
+
+> Note: against a hosted runtime that does not yet send the correlated acknowledgement, an awaited mutation stays pending until the connection resets. The dev server always responds, so promises settle promptly in local development.
+
+## Accessing participant info
+
+Use the `useUserInterfaceParticipant` hook to read the current participant's identity:
+
+```typescript
+import { useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
+
+function Dashboard() {
+  const participant = useUserInterfaceParticipant();
+
+  // null when the surface is being observed rather than played (see 'Observers')
+  if (!participant) return <p>Observing this team</p>;
+
+  return (
+    <div>
+      <p>Hello, {participant.name}!</p>           {/* e.g. "Participant 1" */}
+      <p>Participant #{participant.index}</p>      {/* sequential index */}
+      <p>Team: {participant.teamId}</p>            {/* e.g. "team-1" */}
+    </div>
+  );
+}
+```
+
+| Field    | Type     | Description                                            |
+| -------- | -------- | ------------------------------------------------------ |
+| `id`     | `string` | Platform-assigned participant ID                       |
+| `name`   | `string` | Display name (e.g. `"Participant 1"`)                  |
+| `index`  | `number` | Zero-based join order within the team                  |
+| `teamId` | `string` | The team this participant belongs to (e.g. `"team-1"`) |
+
+For a participant the wrapper does not render children until the platform sends participant info, so all fields are guaranteed to be present. The one case where the hook returns `null` is an observer (see [Observers](#observers) below); guard for it. In the dev server, identity comes from a session cookie (so different browser sessions are different participants).
+
+### Seeing the whole team
+
+`useUserInterfaceParticipant()` returns the caller; `useUserInterfaceParticipants()` returns the full roster for the caller's team, including the caller's own entry. Each entry adds a `connected` flag to the identity fields:
+
+```typescript
+import { useUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
+
+function Roster() {
+  const participants = useUserInterfaceParticipants();
+
+  if (participants.length === 0) return <p>Waiting for teammates…</p>;
+
+  return (
+    <ul>
+      {participants.map((p) => (
+        <li key={p.id}>
+          {p.name} {p.connected ? '🟢' : '⚪'}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+| Field       | Type      | Description                                            |
+| ----------- | --------- | ------------------------------------------------------ |
+| `id`        | `string`  | Platform-assigned participant ID                       |
+| `name`      | `string`  | Display name (e.g. `"Participant 1"`)                  |
+| `index`     | `number`  | Zero-based join order within the team                  |
+| `connected` | `boolean` | `true` while the participant has a live connection     |
+| `teamId`    | `string`  | The team this participant belongs to (e.g. `"team-1"`) |
+
+### Participant presence lifecycle
+
+The presence guarantees are firm, so design against them rather than defensively:
+
+- **The caller is always present.** `useUserInterfaceParticipant()` never returns a partial value. The wrapper gates rendering on the participant message, so `id`, `name`, `index`, and `teamId` are populated before your first render
+- **The roster may be empty on first render.** `useUserInterfaceParticipants()` is not gated, so it starts as `[]` and fills in reactively as the platform sends the list. Render an empty-roster state rather than assuming at least one entry
+- **The caller is included in the roster.** Once populated, the list always contains the caller's own entry alongside every other participant on the team
+- **A disconnect keeps the entry.** When a participant drops their connection their entry stays in the roster with `connected` flipped to `false`, so you can still show who was here. Participants do not leave: an entry lasts for the whole session, keeping its `id` and `index`
+
+Because the caller is guaranteed and the roster fills in reactively, there is no separate loading flag to check: branch on `participants.length === 0` for the brief pre-population window, and on `connected` to distinguish live from dropped teammates.
+
+**Under `sdk dev`**, a participant is connected while a page addressed to them is open, at `/team/N/player/M` with or without `?bare`. Several tabs on the same participant count once, and they stay connected until the last one closes. An observer page and the console's session surface are nobody's, so they connect nobody. To see a teammate drop out, open two participants' pages and close one.
+
+### Seeing every team's participants
+
+`useUserInterfaceParticipants()` covers your own team. In a shared-state game where teams deal with each other, a UI can also read the roster of every team through the `getAllTeamsParticipants()` callback, for a directory of who is on each competing team. Declare `crossTeamParticipants: true` in the UI bundle to authorise it (an undeclared UI receives an empty array), then call it and group the flat result by `teamId`:
+
+```tsx
+const { getAllTeamsParticipants } = useUserInterfaceCallbacks();
+const everyone = await getAllTeamsParticipants(); // Participant[]
+```
+
+Unlike the own-team hook, this is a point-in-time snapshot rather than a live subscription: call it again to refresh. See [Show all teams' participants in a UI](../recipes/show-all-teams-participants.md) for the full pattern.
+
+### Observers
+
+Your UI can be rendered for an **observer** as well as a participant. An observer is a facilitator watching one team's live game UI without joining as a team member, for seeing how a team is playing, troubleshooting, or running a debrief. An observer is not in the roster and has no participant identity, so `useUserInterfaceParticipant()` returns `null` in that mode.
+
+Read the viewer role with `useUserInterfaceViewerRole()`:
+
+```tsx
+import { useUserInterfaceViewerRole, useUserInterfaceParticipant } from '@seriousgaming/sdk/ui';
+
+function Decisions() {
+    const isObserver = useUserInterfaceViewerRole() === 'observer';
+    const participant = useUserInterfaceParticipant(); // null when observing
+
+    return (
+        <>
+            {isObserver && <Banner>Observing: you are watching this team, not playing</Banner>}
+            <PriceInput readOnly={isObserver} />
+        </>
+    );
+}
+```
+
+Most UIs need no changes: an observer sees the live game UI exactly as a participant does, and can still drive it. Any change an observer makes goes to the game's validators, as a participant's would, with `actor.role` set to `'observer'` so a validator can treat it differently (see [Validators](./validators.md)). Reach for `useUserInterfaceViewerRole()` only when you want to adapt: hide a participant-only control (anything keyed by participant id has no id to write under), reveal state you keep hidden during play, or present a deliberately read-only debrief view.
+
+One read does need attention. To find out **which team** your UI is rendering, use `useUserInterfaceOwnTeam()`, not `useUserInterfaceParticipant()?.teamId`:
+
+```typescript
+import { useUserInterfaceOwnTeam } from '@seriousgaming/sdk/ui';
+
+const ownTeam = useUserInterfaceOwnTeam(); // { teamId, index, name }, populated when observing too
+```
+
+The participant route is the obvious one and it is `null` under observation, so anything derived from it (marking your row in a cross-team list, labelling a board, keying a write) works when played and breaks when observed. `useUserInterfaceOwnTeam()` comes from the host, which always knows which surface it mounted. Do not confuse it with the plural `useUserInterfaceTeams()`, which lists every team in the session without marking yours.
+
+### Walkthroughs
+
+Your UI can also be rendered in a **walkthrough**: a disposable second run of the game beside the session, for demonstrating it. One team, one participant, always from tick 0, touching nothing real. It is what a facilitator puts on a projector while talking a room through the game.
+
+Read it with `useRunKind()`:
+
+```tsx
+import { useRunKind } from '@seriousgaming/sdk/ui';
+
+function Leaderboard() {
+    const runKind = useRunKind();
+    const data = useUserInterfaceData();
+
+    // A walkthrough has one team, so the board has one row. Fill it in rather
+    // than showing a room an empty board they will never see again.
+    const rows = runKind === 'walkthrough' ? demonstrationRows : data.market.Standings;
+
+    return <Board rows={rows} />;
+}
+```
+
+Most UIs need no changes, and one that ignores this renders exactly as it always has: every session reports `'session'`, and only the walkthrough beside it differs. Reach for it to fill in what a solo run genuinely lacks (rival teams, teammates in a presence list), or to hide something you would rather not spoil before play.
+
+**The line to hold:** do not change how the game UI plays. The walkthrough exists to show the room this game, and one that behaves differently shows them a different one.
+
+The value is the host's, it is the same one your engine reads as `meta.runKind`, and it does not change for the life of the run, so a decision taken here and one taken in logic cannot disagree.
+
+A session UI gets two more pieces. `useSessionUserInterfaceWalkthroughLink()` returns where to open the walkthrough, or `null` until the host has said (every host offers one), and `callbacks.resetWalkthrough()` throws it away and starts it again at tick 0. Gate the control on the link, the way a guide button gates on `useSessionUserInterfaceHostOverlays()`:
+
+```tsx
+const walkthrough = useSessionUserInterfaceWalkthroughLink();
+const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
+
+{
+    walkthrough && (
+        <>
+            <Button href={walkthrough.url} target="_blank" rel="noreferrer">
+                Walkthrough
+            </Button>
+            <Button onClick={() => void resetWalkthrough()}>Start it again</Button>
+        </>
+    );
+}
+```
+
+## Showing how to join this team
+
+Every game UI is told how to join the team it is rendering. Use it to put
+a join code on the screen the participants are actually looking at, rather than having
+the facilitator read a URL out.
+
+```typescript
+import { useUserInterfaceOwnTeamJoinLink } from '@seriousgaming/sdk/ui';
+
+function JoinCode() {
+    const joinLink = useUserInterfaceOwnTeamJoinLink();
+    // `null` until the host delivers it, so render nothing for that first frame
+    if (!joinLink) return null;
+    return <QrCode value={joinLink.joinUrl} />;
+}
+```
+
+Points worth knowing:
+
+- You always get your own team and only your own team. There is no list, and no
+  way to reach another team's link from a game UI
+- Observers get it too, and that is the case the feature exists for. A tablet
+  parked on a table showing a team's game UI has no participant of its own, so
+  it is opened as an observer: exactly the screen a walk-up join code belongs on
+- Encode `joinUrl` in a QR code, not any longer form you build yourself. The host
+  picks which form of the link to send, and it picks the short one because a
+  denser code is harder to scan across a table
+- `fallbackJoinUrl` is there for one failure only, a network that blocks the
+  shortened link. Offer it on request (a 'link not working?' control), not beside
+  the main one with equal weight
+- The session PIN never reaches a game UI. In a session that requires one,
+  the code on screen is not enough to join on its own, which is what bounds how
+  much a visible code gives away. An operator who wants a self-sufficient walk-up
+  code runs the session without a PIN
+
+## Letting a team name itself
+
+A game UI can rename the team it belongs to. The name it sets is the
+team's real name everywhere, including the host's own chrome and print sheets, so
+a game that offers this keeps no display name of its own alongside it.
+
+```typescript
+import { MutationError, useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+const { renameOwnTeam } = useUserInterfaceCallbacks();
+
+try {
+    await renameOwnTeam(draftName);
+} catch (error) {
+    // A refusal is terminal: explain it rather than retrying
+    if (error instanceof MutationError) setRefused(true);
+}
+```
+
+Points worth knowing:
+
+- **It names no team.** The host works out which team the caller is on, so a
+  surface can only ever rename its own. There is no `teamId` argument to get
+  wrong
+- **Available everywhere, with nothing to declare.** Game UIs and waiting room
+  UIs, participants and observers alike. A game that does not want its teams
+  renamed simply does not offer the control
+- **Render the result, not the request.** A facilitator can rename the same team
+  from the session UI at the same moment. There is one name per team and the
+  last write wins, so read it back from `useUserInterfaceOwnTeam()` rather than trusting what
+  you just sent
+- **The host owns the limits.** It trims the name, refuses a blank one, and
+  refuses one longer than its cap (60 characters on the reference platform). Each
+  arrives as a terminal `denied`, so surface it rather than looping
+- **`teams.defaultNames` becomes a starting point**, not a fixed label, in any
+  game that offers this
+
+## Displaying the tick timer
+
+When a game uses an automatic [tick controller](./tick-controller.md), the host pushes the current schedule to every UI via the `useUserInterfaceTimer` hook, as a `TimerState`. Use this when you want your UI to show its own countdown: for example, a circular progress bar in the corner of a Decisions panel, or a floating 'Next tick in 12s' badge on a results screen.
+
+```typescript
+import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
+
+function NextTickBadge() {
+    const { enabled, paused, nextTickAt, intervalMs } = useUserInterfaceTimer();
+
+    if (!enabled || nextTickAt === null) {
+        return null; // manual game, or no tick currently scheduled
+    }
+
+    const remainingMs = nextTickAt - Date.now();
+    return <span>Next tick in {Math.ceil(remainingMs / 1000)}s</span>;
+}
+```
+
+The fields are those of [`TimerState`](../api/sdk-ui.md#timerstate), the one timer shape every surface reads. Durations are milliseconds and end in `Ms`; timestamps are milliseconds since the epoch, in `Date.now()` space, and end in `At`. Which field to reach for:
+
+- **`enabled`** is false for a manual-tick game, or once the controller stops scheduling: hide the countdown
+- **`nextTickAt - Date.now()`** is the time left, and **`intervalMs`** the length of the window, for a progress bar. Both are `null` when nothing is scheduled
+- **`paused`** and **`pausedAt`** say whether, and since when, the host has paused ticking
+- **`extendedMs`** is how far a facilitator has moved the current deadline (negative when pulled in), reset with each new tick. Read it to say 'extended by 2m' rather than inferring that from a moved `nextTickAt`
+- **`scheduleStartedAt`** and **`pausedMs`** drive a [simulated game clock](#simulated-game-time)
+
+The hook always returns a value: there is no 'loading' state. Before any timer message has arrived, and for games that don't use a tick controller at all, it returns a disabled timer: `enabled` and `paused` false, every timestamp and `intervalMs` `null`, and `pausedMs` and `extendedMs` 0. The `enabled` check is enough to hide the countdown for manual games without any extra branching.
+
+### Driving the countdown
+
+The hook only fires when the _schedule_ changes: typically once per tick (when the next interval is computed) plus pause/resume events. It does **not** push a new value every second. UIs that want a live ticking countdown must run their own loop locally:
+
+```typescript
+import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
+import { useEffect, useState } from 'react';
+
+function NextTickCountdown() {
+    const { enabled, paused, nextTickAt, intervalMs } = useUserInterfaceTimer();
+    const [remainingMs, setRemainingMs] = useState(() =>
+        nextTickAt === null ? 0 : Math.max(0, nextTickAt - Date.now())
+    );
+
+    useEffect(() => {
+        if (!enabled || nextTickAt === null) {
+            setRemainingMs(0);
+            return;
+        }
+        if (paused) {
+            // Hold the displayed value steady while paused.
+            setRemainingMs(Math.max(0, nextTickAt - Date.now()));
+            return;
+        }
+        let raf = 0;
+        const loop = () => {
+            setRemainingMs(Math.max(0, nextTickAt - Date.now()));
+            raf = requestAnimationFrame(loop);
+        };
+        raf = requestAnimationFrame(loop);
+        return () => cancelAnimationFrame(raf);
+    }, [enabled, paused, nextTickAt]);
+
+    if (!enabled || nextTickAt === null) return null;
+
+    const seconds = Math.ceil(remainingMs / 1000);
+    const progress = intervalMs ? 1 - remainingMs / intervalMs : 0;
+    return (
+        <div>
+            <span>{seconds}s</span>
+            <progress value={progress} max={1} />
+        </div>
+    );
+}
+```
+
+This pattern is deliberate: by keeping the per-frame state inside one leaf component, only that component re-renders 60 times a second, and the rest of your UI is untouched. If you instead put the live remaining time into a context or shared state, every consumer of that context would re-render on every frame, which can quickly become expensive in a non-trivial UI.
+
+### How `nextTickAt` and clocks interact
+
+`nextTickAt` is an absolute timestamp in the **same clock-space as `Date.now()`**, so consumer code never needs to compute clock offsets: just subtract. The host is responsible for stamping it in a clock the consumer will recognise:
+
+- For dev-server-hosted games (the default), the dev server, the console and your iframe all share `Date.now()`, so `nextTickAt` is correct as-is.
+- For cross-machine deployments, hosts rely on NTP-synced wall clocks. NTP keeps machines within tens of milliseconds of each other, well below the granularity of a second-level countdown.
+
+The wrapper does not attempt to re-translate `nextTickAt` on receipt. With only the value and the receiver's `Date.now()` it cannot distinguish 'the host's clock is N ms ahead of mine' from 'this message has been sitting around for N ms', and getting that wrong is exactly how a stored timer state replayed to a remounted iframe would drift. Trusting the timestamp verbatim is what makes the countdown stay accurate when the iframe is remounted.
+
+### Pause and resume
+
+When the host pauses the timer (e.g. via the dev server's pause button: see [Pausing, resuming and extending](./tick-controller.md#pausing-resuming-and-extending) in the tick controller guide), the hook returns `{ enabled: true, paused: true, nextTickAt: null, intervalMs: null }`. The `nextTickAt: null` tells you there is no scheduled fire-time to count down toward; freeze your displayed value rather than letting it tick to zero. When the host resumes, a new schedule is pushed and the countdown picks up from the new `nextTickAt`.
+
+If you want the displayed value to _freeze_ at the moment of pause (rather than disappear), capture the last non-null `nextTickAt` in a ref:
+
+```typescript
+const lastScheduledRef = useRef<number | null>(null);
+useEffect(() => {
+    if (nextTickAt !== null) lastScheduledRef.current = nextTickAt;
+}, [nextTickAt]);
+
+const displayTick = nextTickAt ?? lastScheduledRef.current;
+```
+
+### Simulated game time
+
+If your game compresses real time into simulated time (e.g. 1 real second = 1 simulated hour), you need a clock that advances with wall time but freezes during pauses. The `pausedAt`, `pausedMs`, and `scheduleStartedAt` fields make this possible without any client-side persistence:
+
+```typescript
+import { useUserInterfaceTimer } from '@seriousgaming/sdk/ui';
+
+const COMPRESSION = 3600; // 1 real second = 1 simulated hour
+
+function SimulatedClock() {
+    const { scheduleStartedAt, pausedMs, pausedAt } = useUserInterfaceTimer();
+
+    if (scheduleStartedAt === null) return null;
+
+    // Effective elapsed time = wall time minus all pauses (completed + current)
+    const effectiveElapsedMs =
+        (Date.now() - scheduleStartedAt)
+        - pausedMs
+        - (pausedAt ? Date.now() - pausedAt : 0);
+
+    const simMinutes = Math.floor((effectiveElapsedMs * COMPRESSION) / 60_000);
+    const hours = Math.floor(simMinutes / 60);
+    const mins = simMinutes % 60;
+    return <span>{hours}h {mins}m</span>;
+}
+```
+
+`pausedMs` accumulates the duration of all _completed_ pauses. It does not include the pause currently in progress, which is derived live from `pausedAt`. This avoids the host having to push updates during a pause while still giving clients a fully accurate value at any instant.
+
+Both `pausedMs` and `scheduleStartedAt` reset when the tick controller disables ticking (returns `enabled: false` or `null`). They are **not** reset when the game reaches max ticks or is marked complete, so UIs can still display the final session time after the game ends.
+
+## Remembering a viewer's choice
+
+A viewer's own choices, the tab they had open or a panel they collapsed, should survive a reload. `useViewerStorage` is `useState` that the browser remembers:
+
+```tsx
+import { useViewerStorage } from '@seriousgaming/sdk/ui';
+
+const [tab, setTab] = useViewerStorage('tab', 0);
+```
+
+Do not key `localStorage` by team id yourself: every session's first team is `team-1`, so one session's values turn up in the next. The hook keys each value by the session (an opaque `sessionKey` the host sends every surface on connect, different for every session and for a walkthrough), the surface (a game UI and its waiting room share, as both are the player's), and the viewer (the participant, or the role where there is none). It works on every surface. Every storage access is guarded, so a browser that blocks storage keeps the value in memory for the page's life instead of throwing, and other tabs follow a change.
+
+It is per browser and never shared: anything the game or other players need belongs in context. In tests, the `render*` helpers take a `sessionKey` option. See [Remember a viewer's choice](../recipes/remember-a-viewers-choice.md).
+
+## Building components
+
+Create React components that display game data:
+
+```typescript
+import { useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { LineChart, Line, XAxis, YAxis } from 'recharts';
+import type { Context, Settings } from '../types';
+
+function InventoryChart() {
+  const { data } = useUserInterfaceData<Context, Settings>();
+
+  const { Stock } = data.inventory;
+
+  const chartData = [
+    { tick: 1, stock: 100 },
+    { tick: 2, stock: 95 },
+    { tick: 3, stock: Stock }
+  ];
+
+  return (
+    <LineChart width={600} height={300} data={chartData}>
+      <XAxis dataKey="tick" />
+      <YAxis />
+      <Line type="monotone" dataKey="stock" stroke="#8884d8" />
+    </LineChart>
+  );
+}
+
+export default InventoryChart;
+```
+
+## Using internationalisation
+
+The wrapper sets `lang` and `dir` on the document root from the locale (`dir="rtl"` for Arabic, Hebrew, Persian, Urdu and any other right-to-left script) and keeps them in step when the facilitator changes language, so a surface does not set them itself. It also sets the root's `color-scheme` to the theme's mode, so scrollbars and native form controls follow a dark theme without MUI.
+
+Use React i18next for multi-language support:
+
+```typescript
+import { useTranslation } from 'react-i18next';
+import { useUserInterfaceLocale } from '@seriousgaming/sdk/ui';
+
+function Dashboard() {
+  const { t } = useTranslation();
+  const { locale } = useUserInterfaceLocale();
+
+  return (
+    <div>
+      <h1>{t('dashboard.title')}</h1>
+      <p>{t('dashboard.welcome')}</p>
+      <p>Current language: {locale}</p>
+    </div>
+  );
+}
+```
+
+Update your `src/i18n.ts`:
+
+```typescript
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+const resources = {
+    en: {
+        translation: {
+            'dashboard.title': 'Dashboard',
+            'dashboard.welcome': 'Welcome',
+            'inventory.label': 'Stock Level',
+            'revenue.label': 'Revenue',
+        },
+    },
+    es: {
+        translation: {
+            'dashboard.title': 'Panel de Control',
+            'dashboard.welcome': 'Bienvenido',
+            'inventory.label': 'Nivel de Stock',
+            'revenue.label': 'Ingresos',
+        },
+    },
+};
+
+i18n.use(initReactI18next).init({
+    resources,
+    lng: 'en',
+    interpolation: { escapeValue: false },
+});
+
+export default i18n;
+```
+
+## Linking to static assets
+
+User interfaces run inside an iframe served at a nested path (e.g.,
+`/user-interfaces/ui/`). Because of this, **absolute URLs
+like `/my-file.pdf` will not resolve to your assets**: they escape the iframe
+and hit the shell app's origin instead.
+
+Always use **relative paths** when linking to files in your UI's directory:
+
+```typescript
+// Wrong: escapes the iframe, loads the shell app's index.html
+window.open('/Briefing.pdf');
+
+// Correct: resolves relative to your UI's index.html
+window.open('./Briefing.pdf');
+```
+
+This applies to any reference from your UI code to static files: `<a href>`,
+`<img src>`, `<embed src>`, `window.open()`, `fetch()`, etc. The same rule
+holds in both the dev server and production builds.
+
+In production your UI also runs under a strict content security policy: every
+asset must be bundled into your build (no external CDNs, no Google Fonts, no
+blob-URL workers), and outbound network calls go through an engine, an endpoint,
+or a host capability. The dev server mirrors this policy, so violations
+surface locally. See [Production security constraints](./production-constraints.md)
+for the full policy and the do's and don'ts.
+
+**Where to put static files:** Place them in your UI's directory alongside
+`index.html` (or in a subdirectory). For the default scaffold structure, that
+means inside `ui/`:
+
+```
+ui/
+├── index.html
+├── Briefing.pdf              ← ./Briefing.pdf
+├── public/
+│   └── logo.png              ← ./public/logo.png
+└── src/
+    └── App.tsx
+```
+
+## File uploads
+
+User interfaces can upload files (PDFs, images, CSV, etc.) using the `uploadBlob` callback and display them using `getAssetUrl`. Uploaded files and scenario-bundled files share a single asset reference scheme (see [Asset references](../guides/file-handling.md#asset-references) for the full picture).
+
+### Uploading a file
+
+```typescript
+import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+
+function DocumentUpload() {
+  const callbacks = useUserInterfaceCallbacks();
+  const { setData } = useUserInterfaceData<Context, Settings>();
+  const [isUploading, setIsUploading] = useState(false);
+
+  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file || !callbacks.uploadBlob) return;
+
+    try {
+      setIsUploading(true);
+      const reference = await callbacks.uploadBlob(file);
+      setData({ 'upload': { DocumentRef: reference } });
+    } finally {
+      setIsUploading(false);
+      e.target.value = '';
+    }
+  };
+
+  return (
+    <input type="file" accept=".pdf,.csv,.txt" onChange={handleUpload} disabled={isUploading} />
+  );
+}
+```
+
+The capability holding the reference must be listed in the UI's `writes`. The maximum file size is **20 MB**.
+
+### Displaying a file
+
+Use `useAssetUrl` to get a URL suitable for `<img>`, `<embed>`, or `<video>`. It resolves uploaded blobs and scenario-bundled assets alike, and returns `undefined` for an absent reference, so there is nothing to guard:
+
+```typescript
+import { useAssetUrl } from '@seriousgaming/sdk/ui';
+
+function DocumentViewer() {
+  const { data } = useUserInterfaceData<Context, Settings>();
+  const src = useAssetUrl(data.upload?.DocumentRef);
+  if (!src) return null;
+
+  return (
+    <embed
+      src={src}
+      type="application/pdf"
+      style={{ width: '100%', height: '500px', border: 'none' }}
+    />
+  );
+}
+```
+
+The capability holding the reference must be listed in the UI's `reads`. `useAssetUrl` works on every surface; the `getAssetUrl` callback does the same job outside a component.
+
+For the full reference, including engine access via `readAsset`, blob scopes, CLI upload, and supported file types, see [File handling](./file-handling.md).
+
+## Reading an asset's contents
+
+To render what is in a file rather than link to it, such as a briefing, a JSON table of scenario prose, or a CSV, use `useAsset`. It fetches the asset, reads the body `as` `'json'`, `'text'` or `'blob'`, and returns `{ data, error, loading }`:
+
+```tsx
+import { useAsset } from '@seriousgaming/sdk/ui';
+
+function Briefing() {
+    const { data, error, loading } = useAsset('shared:briefing/briefing.md', { as: 'text' });
+    if (loading) return <Spinner />;
+    if (error) return <Alert>{error.message}</Alert>;
+    return <Markdown>{data}</Markdown>;
+}
+```
+
+It prefers a copy in the surface's locale, held in a directory named for the locale just before the file name, and falls back to the reference as given. In `fr-CA`, `shared:briefing/briefing.md` tries `shared:briefing/fr-CA/briefing.md`, then `shared:briefing/fr/briefing.md`, then `shared:briefing/briefing.md`:
+
+```
+shared-assets/
+  briefing/
+    briefing.md        ← the untranslated text, and the fallback
+    fr/briefing.md
+    ar/briefing.md
+```
+
+Pass `locale` to look in a different one, or `locale: false` to read the reference alone. A `blob:` reference is always read as given. The hook refetches when the reference or the locale changes, so it follows a mid-session language switch, and an answer to a reference that has since changed is discarded. For JSON, give the type: `useAsset<Briefing>(reference, { as: 'json' })`.
+
+## Theming and styling
+
+Serious Gaming provides a theming system that allows your user interfaces to adapt to the host environment's look and feel. This is handled through the `@seriousgaming/sdk` package.
+
+### Accessing theme information
+
+You can access the current theme information within your components using the `useUserInterfaceTheme` hook.
+
+```typescript
+import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+
+function MyComponent() {
+  const theme = useUserInterfaceTheme();
+  // theme.mode will be 'light' or 'dark'
+  // theme.light and theme.dark will contain color palettes
+
+  return (
+    <div style={% raw %}{{{% endraw %} background: theme.mode === 'light' ? theme.light.primary : theme.dark.primary {% raw %}}}{% endraw %}>
+      My Component
+    </div>
+  );
+}
+```
+
+### Theme object structure
+
+The `theme` object returned by `useUserInterfaceTheme` has the following structure:
+
+```typescript
+type UserInterfaceTheme = {
+    mode: 'dark' | 'light';
+    dark: UserInterfaceModeColors;
+    light: UserInterfaceModeColors;
+};
+
+type UserInterfaceModeColors = {
+    primary: string;
+    secondary: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    contrastText: {
+        primary: string;
+        secondary: string;
+        success: string;
+        error: string;
+        warning: string;
+        info: string;
+    };
+};
+```
+
+- `mode`: Indicates whether the current theme is `'light'` or `'dark'`.
+- `light`: An object containing the colour palette for the light theme.
+- `dark`: An object containing the colour palette for the dark theme.
+- `contrastText`: The text colour to draw on each palette colour, an opaque `#rrggbb` the host guarantees meets WCAG AA (4.5:1) against it. Use it rather than computing your own: the theme's author may have chosen one, and the host keeps it when it passes.
+
+```tsx
+const colors = theme.mode === 'light' ? theme.light : theme.dark;
+
+<span style={% raw %}{{{% endraw %} background: colors.primary, color: colors.contrastText.primary {% raw %}}}{% endraw %}>Live</span>
+```
+
+Passing `contrastText` through to Material-UI, as the template's `theme.ts` does (below), means every contained button and chip already uses it.
+
+### Reading the host's theme preference
+
+`useUserInterfaceTheme` gives you the resolved palette, but `theme.mode` only tells you the colours to paint right now. It cannot tell you whether the host is following the operating system or has been pinned to a specific scheme. When you need that distinction, read the host's preference with the `useUserInterfaceThemePreference()` hook. It returns `'light'`, `'dark'`, or `'system'` and re-renders when the preference changes, exactly like `useUserInterfaceTheme()`:
+
+```typescript
+import { useUserInterfaceThemePreference } from '@seriousgaming/sdk/ui';
+
+function ThemePreferenceBadge() {
+  const preference = useUserInterfaceThemePreference();
+  return <span>Following: {preference}</span>;
+}
+```
+
+Each UI surface has its own hook: `useUserInterfaceThemePreference`, `useSessionUserInterfaceThemePreference`, and `useSettingsEditorThemePreference`.
+
+A UI can also change the preference with the `setThemePreference` callback. The host applies it, persists it, and broadcasts the change back, so every other UI (and every theme-preference hook) sees it:
+
+```typescript
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+function ThemeSwitcher() {
+  const callbacks = useUserInterfaceCallbacks();
+  return (
+    <>
+      <button onClick={() => callbacks.setThemePreference('light')}>Light</button>
+      <button onClick={() => callbacks.setThemePreference('dark')}>Dark</button>
+      <button onClick={() => callbacks.setThemePreference('system')}>System</button>
+    </>
+  );
+}
+```
+
+`setThemePreference` is available on every UI surface (game, waiting room, session, configuration). No `uses` declaration is needed, because theme preference is not gated.
+
+### Integrating with Material-UI
+
+The default user interface template uses [Material-UI](https://mui.com/) for its component library.
+
+Here's how to create a dynamic theme in your `App.tsx`:
+
+```typescript
+// src/App.tsx
+import React, { useMemo } from 'react';
+import { createTheme, ThemeProvider } from '@mui/material';
+import { useUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+import MyComponent from './MyComponent';
+
+function App() {
+    const theme = useUserInterfaceTheme();
+
+    const customTheme = useMemo(() => {
+        const themeColors = theme.mode === 'light' ? theme.light : theme.dark;
+        return createTheme({
+            palette: {
+                mode: theme.mode,
+                primary: { main: themeColors.primary, contrastText: themeColors.contrastText.primary },
+                secondary: { main: themeColors.secondary, contrastText: themeColors.contrastText.secondary },
+                success: { main: themeColors.success, contrastText: themeColors.contrastText.success },
+                error: { main: themeColors.error, contrastText: themeColors.contrastText.error },
+                warning: { main: themeColors.warning, contrastText: themeColors.contrastText.warning },
+                info: { main: themeColors.info, contrastText: themeColors.contrastText.info },
+            }
+        });
+    }, [theme]);
+
+    return (
+        <ThemeProvider theme={customTheme}>
+            <MyComponent />
+        </ThemeProvider>
+    );
+}
+```
+
+By using `useMemo`, you ensure that the theme object is only recreated when the theme context from Serious Gaming changes, which is important for performance.
+
+## Sizing to the viewport on mobile
+
+The host sizes your UI's iframe to the visible viewport, so size your UI to fill its container rather than the browser viewport: prefer `height: 100%` (down through `html`, `body`, and the root element) with flex or grid layouts over viewport units.
+
+If you do reach for viewport units, use `dvh` with a `vh` fallback. On iOS WebKit `100vh` resolves to the tall (URL-bar-collapsed) viewport even while the bar is showing, so a `100vh` element runs off the bottom of the screen; `100dvh` tracks the live visible viewport:
+
+```css
+min-height: 100vh; /* fallback for older browsers */
+min-height: 100dvh; /* tracks the live viewport on iOS */
+```
+
+In MUI `sx`, where you cannot repeat a key, express the fallback with `@supports`:
+
+```ts
+sx={{ minHeight: '100vh', '@supports (height: 100dvh)': { minHeight: '100dvh' } }}
+```
+
+Embedded in the host this rarely bites, because an iframe has no collapsing browser chrome and `vh` resolves to the iframe's own height. The `dvh` form keeps your UI correct if it is ever opened standalone in a mobile browser, and the scaffold templates already follow it.
+
+## Using LLMs in user interfaces
+
+User interfaces cannot call `generateText` (or `extractText` or `generateSpeech`) directly. A UI reaches these services through an [endpoint](./endpoints.md): the endpoint wraps the callback and runs server-side, and the UI invokes it through `callbacks.endpoints['<endpoint-id>']`. This keeps credential-holding calls off the untrusted iframe. To create one, follow [Create an endpoint](../recipes/create-endpoint.md). See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md) and the [LLM integration guide](llm-integration.md) for the full pattern.
+
+### The endpoint
+
+The endpoint bundle declares `"uses": ["generateText"]` and runs the LLM call:
+
+```typescript
+// endpoints/chat/logic/logic.ts
+import { getText } from '@seriousgaming/sdk';
+import type { Handler } from '../types';
+
+export const Handle: Handler = async ({ request, callbacks }) => {
+    const response = await callbacks.generateText({
+        messages: request.messages,
+        systemPrompt:
+            request.systemPrompt ?? 'You are a helpful business advisor. Provide concise guidance.',
+    });
+    return { reply: getText(response) };
+};
+```
+
+The UI bundle declares the endpoint in its `endpoints` array. A UI bundle has no `uses` field, and the build refuses one.
+
+```json
+{
+    "definition": {
+        "endpoints": ["chat"]
+    },
+    "rootDirectory": ".",
+    "ui": { "entrypoint": "index.html" }
+}
+```
+
+### Calling the endpoint from a component
+
+Access `callbacks.endpoints` with the `useUserInterfaceCallbacks` hook. Persist the conversation in a capability so it survives across ticks:
+
+```tsx
+import { useState } from 'react';
+import { useUserInterfaceCallbacks, useUserInterfaceData } from '@seriousgaming/sdk/ui';
+import type { Context, Settings } from '../types';
+import type { Callbacks } from '../types';
+
+function ChatAssistant() {
+    const { data, setData } = useUserInterfaceData<Context, Settings>();
+    const callbacks = useUserInterfaceCallbacks() as Callbacks;
+    const [isLoading, setIsLoading] = useState(false);
+
+    const messages = data.chathistory.Messages;
+
+    const handleSendMessage = async (userMessage: string) => {
+        if (!userMessage.trim()) return;
+        setIsLoading(true);
+        try {
+            const newMessages = [...messages, { role: 'user' as const, content: userMessage }];
+            const { reply } = await callbacks.endpoints['chat']({
+                messages: newMessages,
+            });
+            await setData({
+                chathistory: {
+                    Messages: [...newMessages, { role: 'assistant' as const, content: reply }],
+                },
+            });
+        } finally {
+            setIsLoading(false);
+        }
+    };
+
+    return (
+        <div>
+            {messages.map((msg, idx) => (
+                <div key={idx} className={msg.role}>
+                    {msg.content}
+                </div>
+            ))}
+            <input
+                type="text"
+                placeholder="Type your message..."
+                onKeyPress={(e) => {
+                    if (e.key === 'Enter' && !isLoading) {
+                        handleSendMessage(e.currentTarget.value);
+                        e.currentTarget.value = '';
+                    }
+                }}
+                disabled={isLoading}
+            />
+            {isLoading && <p>Loading...</p>}
+        </div>
+    );
+}
+```
+
+### Localising prompts
+
+Translate the system prompt in the UI with i18n and pass it to the endpoint in the request. The endpoint forwards it to `generateText`:
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation();
+const { reply } = await callbacks.endpoints['chat']({
+    messages: newMessages,
+    systemPrompt: t('chatSystemPrompt'),
+});
+```
+
+Update `src/i18n.ts`:
+
+```typescript
+const resources = {
+    en: {
+        translation: {
+            chatSystemPrompt: 'You are a helpful assistant for a business game.',
+            askForAdvice: 'Ask for advice...',
+        },
+    },
+    es: {
+        translation: {
+            chatSystemPrompt: 'Eres un asistente útil para un juego de simulación empresarial.',
+            askForAdvice: 'Pedir consejo...',
+        },
+    },
+};
+```
+
+### Markdown rendering in chat
+
+Render markdown replies with `react-markdown`:
+
+```typescript
+import { useUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import ReactMarkdown from 'react-markdown';
+import { Box, styled } from '@mui/material';
+
+const StyledMarkdown = styled(Box)(({ theme }) => ({
+  '& code': {
+    backgroundColor: theme.palette.action.hover,
+    padding: '2px 6px',
+    borderRadius: '4px',
+    fontFamily: 'monospace'
+  },
+  '& pre': {
+    backgroundColor: theme.palette.action.hover,
+    padding: theme.spacing(1),
+    borderRadius: '4px',
+    overflow: 'auto'
+  }
+}));
+
+function ChatMessage({ content }: { content: string }) {
+  return (
+    <StyledMarkdown>
+      <ReactMarkdown>{content}</ReactMarkdown>
+    </StyledMarkdown>
+  );
+}
+```
+
+### Error handling
+
+A failed endpoint call rejects with an `EndpointError`, the endpoint counterpart of `MutationError`. `error.kind` (shorthand for `error.outcome.kind`) says why: the `MutationOutcome` kinds above, plus `invalid-request` (the request failed `requestSchema` and the handler never ran), `handler-error` (the handler threw or overran its time limit) and `invalid-response` (it returned something its declaration forbids). `error.applied` lists the endpoint's effects that had already landed, and `error.failedStep` names the one that failed, so you can tell a call that changed nothing from one that saved its write and then failed on an action:
+
+```typescript
+import { EndpointError } from '@seriousgaming/sdk/ui';
+
+try {
+    const { reply } = await callbacks.endpoints['chat']({ messages });
+    setResponse(reply);
+} catch (error) {
+    if (error instanceof EndpointError && error.kind === 'handler-error') {
+        setError(t('chatUnavailable'));
+    } else {
+        setError(error instanceof Error ? error.message : String(error));
+    }
+}
+```
+
+An empty `applied` means nothing changed. As with a mutation, never retry an endpoint call automatically: a `conflict` means a person may try again. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md#steps) for every kind.
+
+### Putting a chat UI together
+
+The sections above are the parts of a complete chat surface. Beyond them, a chat that feels finished usually adds:
+
+- Message history kept in the component's state, or in a capability when it must survive a reload, and sent with each call
+- A loading state while the call is in flight, with the send button disabled
+- Scrolling to the latest message when one arrives
+
+## Best practices
+
+1. **Use type safety** - Import generated types from `./types`
+    - ✅ `useUserInterfaceData<Context, Settings>()`
+    - ❌ `useUserInterfaceData<any, any>()`
+
+2. **Access data via destructuring** - Get data, settings, and setData from the hook
+    - ✅ `const { data, settings, setData } = useUserInterfaceData<Context, Settings>()`
+    - ❌ Trying to access missing hooks like `useUserInterfaceContext`
+
+3. **Declare every capability you render** - `data` carries exactly what the bundle declares
+    - ✅ Add the capability to `reads` (or `writes`) and read `data.inventory.Stock` directly
+    - ❌ Render a capability the bundle never declared and guard the `undefined` with `?.`
+
+4. **Respect write boundaries** - Only update capabilities in `writes`
+    - ✅ Use `setData` for capabilities in `writes`
+    - ❌ Try to update read-only capabilities
+
+5. **Responsive design** - Ensure UIs work on different screen sizes
+    - ✅ Use flexbox/grid, size to the container, test on mobile
+    - ❌ Fixed widths, desktop-only design, `100vh` without a `dvh` fallback
+
+6. **Performance** - Use React hooks efficiently
+    - ✅ `useEffect` for side effects, memoisation for expensive renders
+    - ❌ Recalculate everything on every render
+
+## Testing UIs
+
+For component tests with Vitest and the render helpers from `@seriousgaming/sdk/ui/testing`, see [Testing user interfaces](./testing.md#testing-user-interfaces). To see a UI running, start the dev server in your game directory:
+
+```bash
+pnpm run sdk dev
+```
+
+Your UI appears in the dev server at http://localhost:3000. You can:
+
+- View context in real time
+- Step through ticks
+- Watch UI update with each tick
+- Switch languages
+- Undo/redo changes
+
+## Customising Vite (dev and build)
+
+When the SDK starts Vite for your UI (whether for the dev server or a production build), you can customise Vite's behaviour by creating a `vite.config.ts` file. The SDK loads it and merges it with its own inline config.
+
+### Where to put `vite.config.ts`
+
+**Put it at the project root** (alongside `seriousgaming.sdk.json`). This is the recommended location: one file applies to every UI in the package, and the same file is used by both `sdk dev` and `sdk build`.
+
+```
+my-package/
+├── seriousgaming.sdk.json
+├── vite.config.ts          ← recommended location
+├── ui/
+│   ├── index.html
+│   └── src/
+└── session/
+    └── ...
+```
+
+### Per-UI overrides
+
+You can also drop a `vite.config.ts` inside an individual `ui/` directory. The SDK loads it in addition to the project-root config and the per-UI file's values override the root's on conflicts. This is useful when one UI needs a specific alias or plugin that would break the others, but in practice the root config is almost always enough, and per-UI files multiply maintenance.
+
+**Don't keep both a root config and a per-UI config for the same UI unless you really mean to.** If the SDK finds both while building a given UI it prints a warning and asks you to consolidate. Merging still happens so the build doesn't break, but the warning is telling you that the intent is unclear.
+
+### What merges and what doesn't
+
+The merge order is:
+
+```
+project-root vite.config.ts  →  ui/vite.config.ts  →  SDK inline config
+       (baseline)                  (overrides root)      (SDK owns these)
+```
+
+**Additive options merge cleanly.** `resolve.dedupe`, `resolve.alias`, `optimizeDeps.include`, `esbuild`, extra `plugins`, and similar fields are not set (or only partially set) by the SDK, so your entries are combined with the SDK's.
+
+**The SDK wins on structural fields.** `root`, `base`, `build.outDir`, `build.rollupOptions.input`, and the dev-server `server.middlewareMode`/`appType`/`hmr` settings are owned by the SDK and cannot be overridden: trying to set them in `vite.config.ts` has no effect.
+
+A common use case is preventing duplicate package instances when using third-party React libraries:
+
+```typescript
+// vite.config.ts (project root)
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    resolve: {
+        dedupe: ['react', 'react-dom'],
+    },
+});
+```
+
+See [Fix duplicate package errors in a UI](../recipes/fix-duplicate-packages.md) for a full explanation of when and why this is needed.
+
+## Next steps
+
+- [Internationalisation guide](./internationalization.md) - Add multi-language support
+- [Getting started](../getting-started.md) - Run the dev server