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

package/dist/docs/guides/session.md

@@ -0,0 +1,972 @@
+# Building session UIs
+
+Build facilitator-only UIs that operate across all teams in a session at once: session-wide dashboards, cross-team comparisons, and global game controls.
+
+**Keywords:** manage session, session UI, facilitator UI, session-level, cross-team, multi-team dashboard, facilitator controls, session dashboard, all teams, independent mode, shared-state mode
+
+## What you'll learn
+
+- How to create a session UI
+- How to read and write per-team state from a single session-level view
+- How to target game flow controls at individual teams or all teams at once
+- How to handle both independent and shared-state interaction modes
+- How to configure the session UI per game and per scenario
+
+## What are session UIs?
+
+The session UI is the facilitator's whole-session screen. The host renders it full-bleed beneath a thin band of its own chrome, and it owns everything below that: teams, participants, and game controls. A game wires in at most one, and a package that ships none falls back to the host's own roster page.
+
+| Aspect                | Session UI                                            | Game UI              |
+| --------------------- | ----------------------------------------------------- | -------------------- |
+| **Who sees it**       | Facilitator only                                      | Participants         |
+| **Scope**             | Every team in the session                             | Single team          |
+| **Data model**        | `SessionData` (shared store and teams map)            | Flat context         |
+| **Where shown**       | Full-bleed under the host's chrome                    | During game play     |
+| **Cardinality**       | At most one per game                                  | At most one per game |
+| **Tick control**      | Per-team or all-teams tick, undo, pause, reset        | `requestTick` only   |
+| **Roster control**    | Create and rename teams, rename and move participants | None                 |
+| **Interaction modes** | Aware of independent vs shared-state                  | Not mode-aware       |
+
+Capability is inferred, not declared: shipping a session UI claims the whole canvas. There is no partial takeover and no per-capability negotiation.
+
+## Creating a session UI
+
+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 session` instead, or start from `new package --empty`.
+
+```bash
+pnpm run sdk new session '{
+  "definition": {
+    "reads": ["price", "workers", "production"],
+    "writes": ["price", "workers"]
+  },
+  "rootDirectory": "."
+}'
+```
+
+This creates:
+
+```
+session/
+├── session.sdk.json
+├── index.html
+├── types.ts
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    ├── i18n.ts
+    └── theme.ts
+```
+
+## Configuring the surface
+
+Give the session UI values a game can vary without a code change by putting them in a settings resource, `settings/session/settings.sdk.json`:
+
+```json
+{
+    "definition": {
+        "settingsSchema": {
+            "type": "object",
+            "properties": {
+                "NoticeboardLabel": { "type": "string", "default": "Noticeboard" },
+                "ShowJoinLinks": { "type": "boolean", "default": true }
+            },
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+and listing it in `session/session.sdk.json`:
+
+```json
+{
+    "definition": {
+        "reads": ["noticeboard"],
+        "writes": ["noticeboard"],
+        "settings": ["session"]
+    }
+}
+```
+
+The resolved values arrive as `settings` on
+[`useSessionUserInterfaceData`](#usesessionuserinterfacedata), keyed by
+settings identifier (`settings.session.ShowJoinLinks`) and typed as the
+generated `Settings` from the session UI's `types.ts`. The surface receives
+exactly the settings it lists, so it can also read the engine's by listing
+`engine`, and never sees one it does not list.
+
+The values resolve like any settings (see [Overriding settings](./settings.md#overriding-settings)).
+To change a value for every session, edit its default. To vary it by
+scenario, set it under the settings identifier in the scenario's
+`settings`:
+
+```json
+{
+    "definition": {
+        "locales": {
+            "en": {
+                "name": "Executive briefing"
+            }
+        },
+        "settings": {
+            "session": {
+                "ShowJoinLinks": false
+            }
+        }
+    },
+    "rootDirectory": "."
+}
+```
+
+Every layer is partial: set only the keys you want to change, and the rest
+fall through. Settings are fixed when play starts. See
+[Settings](./settings.md) for the whole model.
+
+## Building the session UI
+
+Use `useSessionUserInterfaceData` to read session data and write per-team overrides. The data model carries the shared store once, and wraps each team's own context, tick count, and timer state, into a `SessionData` structure:
+
+```typescript
+type SharedState = {
+    // The shared-scope capabilities this UI declares in reads and writes
+    context: Record<string, unknown>;
+    // Wrapper plumbing; nothing on screen needs it
+    revision: number;
+};
+
+type TeamState = {
+    // This team's own capabilities (team scope only), projected onto
+    // the capabilities this UI declares in reads and writes
+    context: Record<string, unknown>;
+    completedTicks: number; // ticks this team has completed
+    timer: TimerState; // the timer, as a game UI reads it
+    // Wrapper plumbing; nothing on screen needs it
+    revision: number;
+};
+
+type SessionData = {
+    shared: SharedState; // present even in a session with no teams
+    teams: Record<string, TeamState>;
+};
+```
+
+`timer` is the one [`TimerState`](../api/sdk-ui.md#timerstate) shape a game UI reads from `useUserInterfaceTimer()`, so a countdown is drawn as in [Displaying the tick timer](./ui.md#displaying-the-tick-timer).
+
+Three notes on that shape. Each `context` carries only the capabilities this session UI declared (see [Capabilities](./capabilities.md#a-declaration-is-what-gets-delivered)), so declare everything the screen renders. A `scope: 'shared'` capability arrives once, in `shared.context`, and never in a team's `context`: read it there rather than off whichever team comes first. And `revision` is how the wrapper tracks updates: on a large session the host sends one team's state (or the shared store) rather than every team's, and the wrapper merges each one into the `SessionData` you read, asking for a fresh snapshot if it notices one went missing. You never need to read it, and you can leave it out of hand-written test fixtures.
+
+The SDK types are generic (`SessionData<TTeamContext, TSharedContext>`, `TeamState<TTeamContext>` and `SharedState<TSharedContext>`), and the generated `types.ts` beside your session UI exports `SessionData` already filled in with its `TeamContext` and `SharedContext`. Pass it as the first generic of `useSessionUserInterfaceData` and both halves are typed:
+
+```typescript
+import type { SessionData, Settings } from '../types';
+
+const { sessionData } = useSessionUserInterfaceData<SessionData, Settings>();
+const briefing = sessionData.shared.context.briefing.Message; // once, not off teams[0]
+const price = sessionData.teams['team-1']?.context.price.Price; // a team's own
+```
+
+The keys of `sessionData.teams` are stable team ids (`team-1`, `team-2`, and so on). Each id carries the team's zero-based `index` (`team-N` carries index N-1), and the id never renumbers. Because removing a team leaves a gap, the key set can be sparse (for example `team-1` and `team-3` with no `team-2`); iterate the keys rather than assuming a contiguous `1..N` range. Each `TeamInfo` from `useSessionUserInterfaceTeams` carries the matching `index`, so a UI can find its own slot with `teams.find((t) => t.teamId === participant.teamId)?.index`.
+
+### Reading session data
+
+```typescript
+import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { Typography, Paper, Grid } from '@mui/material';
+
+function App() {
+    const { sessionData, settings, setData } = useSessionUserInterfaceData();
+
+    return (
+        <Grid container spacing={2}>
+            {Object.entries(sessionData.teams).map(([teamId, team]) => (
+                <Grid item xs={6} key={teamId}>
+                    <Paper sx={{ p: 2 }}>
+                        <Typography variant="h6">{teamId} (Tick {team.completedTicks})</Typography>
+                        <Typography>
+                            Price: {(team.context.price as any)?.Price}
+                        </Typography>
+                        <Typography>
+                            Production: {(team.context.production as any)?.Production}
+                        </Typography>
+                    </Paper>
+                </Grid>
+            ))}
+        </Grid>
+    );
+}
+
+export default App;
+```
+
+### Writing per-team overrides
+
+The session-level `setData` requires a `teamId` parameter to specify which team to update, since the session UI is not scoped to one team:
+
+```typescript
+import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { TextField } from '@mui/material';
+
+function TeamPriceEditor({ teamId }: { teamId: string }) {
+    const { sessionData, setData } = useSessionUserInterfaceData();
+    const team = sessionData.teams[teamId];
+
+    return (
+        <TextField
+            label={`${teamId} Price`}
+            type="number"
+            value={(team.context.price as any)?.Price}
+            onChange={(e) =>
+                setData(teamId, {
+                    price: { Price: Number(e.target.value) },
+                })
+            }
+        />
+    );
+}
+```
+
+Changes made via `setData` are sent immediately to the dev server and merged into the target team's context, so there is no 'Apply' button to press.
+
+A team write may change only the capabilities this UI declares in `writes`. One that changes any other capability, or names a key that is not a capability, is refused as `denied` and none of it is applied. Sending a team's whole context back with one field edited is fine: a capability the write carries unchanged is not a change.
+
+The one-argument form, `setData(update)`, writes `scope: 'shared'` capabilities session-wide instead, and merges optimistically into `sessionData.shared.context`. See [Facilitator-writable shared capabilities](./multi-team-games.md#facilitator-writable-shared-capabilities).
+
+Type both forms with the generated types in the surface's `types.ts`. `SharedWrites` is the shared capabilities in this UI's `writes`, and `TeamWrites` the rest of them, so a team write naming a shared capability fails to compile rather than being refused when the session holds more than one team:
+
+```typescript
+import type { SessionData, Settings, SharedWrites, TeamWrites } from '../types';
+
+const { setData } = useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>();
+
+setData(teamId, { price: { Price: 12 } }); // TeamWrites
+setData({ dials: { BasePrice: 12 } }); // SharedWrites
+setData(teamId, { dials: { BasePrice: 12 } }); // compile error: dials is shared
+```
+
+### Removing a key
+
+A merge cannot remove a key, so both forms take `deletes` as their last argument, as a player surface's `setData` does. The paths are removed after the update merges:
+
+```typescript
+// Take one team's note down
+setData(teamId, {}, { deletes: [['pinboard', 'Notes', noteId]] });
+
+// Remove an offer from the shared store, for every team
+setData({}, { deletes: [`market.Offers.${offerId}`] });
+```
+
+The host holds each path to this UI's `writes`: a team delete must name a team-scope capability it writes, and a shared delete a shared one it writes. Anything else is refused as `denied`, and none of the write is applied. A shared capability has one value for the session, so remove from it with the shared form, never through a team. See [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) for when to delete rather than write `null`.
+
+### Per-team views
+
+A common pattern is to iterate over teams and render a card or panel for each one:
+
+```typescript
+import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
+import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
+import { Card, CardContent, Typography, Grid, TextField } from '@mui/material';
+
+function SessionDashboard() {
+    const { sessionData, setData } = useSessionUserInterfaceData();
+    const teams = useSessionUserInterfaceTeams();
+
+    return (
+        <Grid container spacing={2}>
+            {teams.map((team) => {
+                const state = sessionData.teams[team.teamId];
+                if (!state) return null;
+
+                return (
+                    <Grid item xs={12} md={6} key={team.teamId}>
+                        <Card>
+                            <CardContent>
+                                <Typography variant="h6">{team.name}</Typography>
+                                <Typography variant="body2">Tick: {state.completedTicks}</Typography>
+                                <TextField
+                                    label="Workers"
+                                    type="number"
+                                    value={(state.context.workers as any)?.WorkerCount}
+                                    onChange={(e) =>
+                                        setData(team.teamId, {
+                                            workers: {
+                                                WorkerCount: Number(e.target.value),
+                                            },
+                                        })
+                                    }
+                                />
+                            </CardContent>
+                        </Card>
+                    </Grid>
+                );
+            })}
+        </Grid>
+    );
+}
+```
+
+### Interaction mode awareness
+
+The interaction mode lives on `useSessionUserInterfaceTeamConfiguration()`, alongside the team bounds: one hook for how teams work, one for which teams exist. Use it to adapt the UI, for example by hiding per-team tick controls in shared-state mode (where all teams tick together):
+
+```typescript
+import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
+import { Alert } from '@mui/material';
+
+function ModeIndicator() {
+    const { mode } = useSessionUserInterfaceTeamConfiguration();
+
+    return (
+        <Alert severity="info">
+            {mode === 'shared-state'
+                ? 'Shared-state mode: all teams tick together.'
+                : 'Independent mode: each team ticks on its own schedule.'}
+        </Alert>
+    );
+}
+```
+
+In **shared-state** mode, calling `requestTick()` without a `teamId` advances all teams simultaneously. In **independent** mode, you can target individual teams or advance all teams at once: with no `teamId`, every team that can still move advances by one from its own round, so a team that is behind stays behind, and a team that is complete or at the round limit is skipped.
+
+## Controlling game flow
+
+Session UIs have full control over the game lifecycle via callbacks. Every game-flow callback accepts an optional `teamId`; when it is omitted the action applies to all teams.
+
+Every game-flow callback except `pauseTimer` and `resumeTimer` returns a promise that resolves once the host has committed the change, and rejects with a `MutationError` when it will not. Await it when you want to report the outcome honestly; ignore it when you do not. Either way the resulting state arrives through the normal session data channel.
+
+### Triggering ticks
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
+import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
+import { Button, Stack } from '@mui/material';
+
+function TickControls() {
+    const { requestTick } = useSessionUserInterfaceCallbacks();
+    const teams = useSessionUserInterfaceTeams();
+    const { mode } = useSessionUserInterfaceTeamConfiguration();
+
+    return (
+        <Stack spacing={1}>
+            <Button onClick={() => requestTick()} variant="contained">
+                Advance All Teams
+            </Button>
+            {mode === 'independent' &&
+                teams.map((team) => (
+                    <Button
+                        key={team.teamId}
+                        onClick={() => requestTick(team.teamId)}
+                        variant="outlined"
+                    >
+                        Advance {team.name}
+                    </Button>
+                ))}
+        </Stack>
+    );
+}
+```
+
+The session UI's `requestTick` control is how facilitators advance the game: there is no built-in next tick button. The scaffolded session UI wires a session-wide tick button out of the box; during development the console's dev drawer also has a developer-only **Tick** button.
+
+### Pausing and resuming the timer
+
+When a game uses a [tick controller](./tick-controller.md) with automatic ticking, facilitators can pause and resume per-team or globally:
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import { Button, Stack } from '@mui/material';
+
+function TimerControls({ teamId }: { teamId?: string }) {
+    const { pauseTimer, resumeTimer } = useSessionUserInterfaceCallbacks();
+
+    return (
+        <Stack direction="row" spacing={1}>
+            <Button onClick={() => pauseTimer(teamId)} variant="outlined" color="warning">
+                {teamId ? `Pause ${teamId}` : 'Pause All'}
+            </Button>
+            <Button onClick={() => resumeTimer(teamId)} variant="contained" color="success">
+                {teamId ? `Resume ${teamId}` : 'Resume All'}
+            </Button>
+        </Stack>
+    );
+}
+```
+
+While paused, manual ticks via `requestTick` still work. Timer state for each team is available in `sessionData.teams[teamId].timer`.
+
+### Extending a tick
+
+Pausing is the wrong tool for 'give them two more minutes'. It stops the clock until someone remembers to start it again, and it does not move the deadline your countdown is drawn from. `extendTick` moves the deadline instead. It takes milliseconds:
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import { Button, Stack } from '@mui/material';
+
+function ExtendControls({ teamId }: { teamId?: string }) {
+    const { extendTick } = useSessionUserInterfaceCallbacks();
+
+    return (
+        <Stack direction="row" spacing={1}>
+            <Button onClick={() => void extendTick(120_000, teamId)}>+2 min</Button>
+            <Button onClick={() => void extendTick(-30_000, teamId)}>-30 sec</Button>
+        </Stack>
+    );
+}
+```
+
+Three things worth knowing:
+
+- **It moves one window, not the cadence.** The interval your tick controller returns for later ticks is untouched, so a session does not run permanently late because one tick ran long
+- **A negative value pulls the deadline in**, clamped at now. It never fires a tick retroactively
+- **Read the result back from `extendedMs`** on the team's timer rather than inferring it from a moved `nextTickAt`. A deadline that jumped is equally the signature of a freshly scheduled tick, so `extendedMs` is the only honest source for 'extended by 2m'
+
+```typescript
+const { extendedMs } = sessionData.teams[teamId].timer;
+```
+
+It rejects with a `MutationError` carrying `{ kind: 'denied' }` when there is no tick to move: automatic ticking is off, the game is complete, or the timer is paused. Resume first, then extend.
+
+Deliberately, the [tick interval bounds](./tick-controller.md) do not apply. They bound the cadence a tick controller may schedule; a facilitator in the room already reaches outside both with an immediate `requestTick` and an indefinite `pauseTimer`.
+
+### Opening host overlays
+
+Some things a facilitator wants are drawn by the host rather than by your game: the [facilitator guide](./guide.md), a team's print sheet. Your session UI owns the whole canvas, so without a way to ask, a facilitator has to leave it to reach them.
+
+`openHostOverlay` asks. The host renders the overlay in its own chrome, above your session UI, where you can neither restyle nor suppress it:
+
+```typescript
+import {
+    useSessionUserInterfaceCallbacks,
+    useSessionUserInterfaceHostOverlays,
+} from '@seriousgaming/sdk/ui';
+import { Button, Stack } from '@mui/material';
+
+function OverlayControls() {
+    const overlays = useSessionUserInterfaceHostOverlays();
+    const { openHostOverlay } = useSessionUserInterfaceCallbacks();
+
+    return (
+        <Stack direction="row" spacing={1}>
+            {overlays.includes('facilitator-guide') && (
+                <Button onClick={() => void openHostOverlay('facilitator-guide')}>Guide</Button>
+            )}
+            {overlays.includes('print-sheets') && (
+                <Button onClick={() => void openHostOverlay('print-sheets')}>Print sheets</Button>
+            )}
+        </Stack>
+    );
+}
+```
+
+**Always gate on `useSessionUserInterfaceHostOverlays()`.** Which overlays exist is the host's answer, not yours: a production host and the dev server do not offer the same set, and the guide is only available when the active game declares one. A button for an overlay the host does not have is a button that cannot work. The list is empty until the host answers, and it can change mid-session when a scenario switch changes which guides the game declares.
+
+The second argument narrows the overlay:
+
+| Overlay               | Second argument                       | Omitted means                   |
+| --------------------- | ------------------------------------- | ------------------------------- |
+| `'facilitator-guide'` | A guide identifier your game declares | The game's first declared guide |
+| `'print-sheets'`      | A team id                             | Every team                      |
+
+It rejects with a `MutationError` carrying `{ kind: 'denied' }` for an overlay the host does not offer and for an argument that does not resolve.
+
+### Undoing and resetting
+
+Facilitators can revert the last tick or reset games, targeted at a specific team or all teams:
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+import { Button, Stack } from '@mui/material';
+
+function GameControls() {
+    const { undoTick, resetGame } = useSessionUserInterfaceCallbacks();
+
+    return (
+        <Stack direction="row" spacing={1}>
+            <Button onClick={() => undoTick()} variant="outlined">
+                Undo All Teams
+            </Button>
+            <Button onClick={() => resetGame()} variant="outlined" color="error">
+                Reset All Teams
+            </Button>
+        </Stack>
+    );
+}
+```
+
+- **`undoTick(teamId?)`** puts teams back on the board they were holding when the last tick was taken, decisions and all: it un-runs the engine rather than re-dealing the tick. When `teamId` is omitted, reverts all teams; naming one is independent mode only, since shared-state teams advance together. With no history to undo, the promise rejects with a `MutationError` whose `outcome.kind` is `denied`.
+- **`resetGame(teamId?)`** clears all context, deletes game-scoped blobs, and re-initialises from scratch. When `teamId` is omitted, resets all teams. Settings are preserved.
+
+### Opening and closing the waiting room
+
+`setWaitingRoom` parks the session: every participant's game UI is replaced with the game's [waiting room UI](./waiting-room.md) until you close it again.
+
+```typescript
+const { setWaitingRoom } = useSessionUserInterfaceCallbacks();
+
+<Button onClick={() => setWaitingRoom(true)} variant="outlined">
+    Open waiting room
+</Button>
+```
+
+- **`setWaitingRoom(open)`** takes **no `teamId`**, unlike every other control above. The waiting room is one flag for the whole session, so there is no per-team variant to target
+- Game state is untouched in both directions. Per-team context, the current tick, and timers all survive, which is the point: park a live session for a discussion and resume exactly where teams were
+- It does not stop the clock. Automatic ticks keep firing while participants wait; halting play is the tick controller's decision, via `waitingRoomOpen`
+- It resolves once the host confirms the change and rejects with a `MutationError` otherwise
+
+The host provides its own toggle too, so building one is optional. Reach for this when you want the control to sit inside your own facilitator layout, or to pair it with a note you set on a shared capability at the same moment.
+
+### Controlling the roster
+
+The session UI owns the roster. Five callbacks create, rename and delete teams, and rename and move participants:
+
+```typescript
+const { createTeam, renameTeam, deleteTeam, renameParticipant, moveParticipant } =
+    useSessionUserInterfaceCallbacks();
+
+await createTeam('Marketing'); // name is optional
+await renameTeam('team-1', 'Sales');
+await renameParticipant('participant-3', 'Sam');
+await moveParticipant('participant-3', 'team-2');
+await deleteTeam('team-3'); // independent mode, empty teams only
+```
+
+Each resolves on commit and rejects with a `MutationError`. Three refusals arrive as `{ kind: 'denied' }`: the team count is at the effective maximum, a team is being added to a shared-state session (whose team count is fixed at creation, though the dev server relaxes that before the first tick as an authoring convenience), or the session is read-only. **A denial is terminal**: unlike `conflict`, waiting and re-sending cannot change the outcome, so surface it rather than looping.
+
+Creating or erasing a participant is deliberately not exposed.
+
+#### Deleting a team
+
+`deleteTeam(teamId)` removes a team from an **independent-mode** session. Every runtime supports it, unlike `createTeam`, which a runtime may refuse. It is refused with `{ kind: 'denied' }` when:
+
+- The session is shared-state, at any point, before the first tick included. A shared-state engine initialised over the whole cohort, so its team count is fixed for the session
+- The team still has participants, connected or not. A participant is never erased, so move every one out with `moveParticipant` first
+- It is the last team in the session
+- The session does not hold the team, or is read-only
+
+A deleted team's index is left as a gap, and no other team's index or id changes. The next `createTeam` takes the lowest free index back, as a new team with the default name: nothing of the deleted team returns with it. Undo never brings a deleted team back, and no hook fires.
+
+Offer the control only where it can succeed, so a facilitator is not shown a button the host will refuse:
+
+```tsx
+const { mode } = useSessionUserInterfaceTeamConfiguration();
+const participants = useSessionUserInterfaceParticipants();
+const { deleteTeam } = useSessionUserInterfaceCallbacks();
+
+{
+    mode === 'independent' && (
+        <Button
+            disabled={teams.length <= 1 || participants.some((p) => p.teamId === team.teamId)}
+            onClick={() => void deleteTeam(team.teamId).catch(showDenial)}
+        >
+            Delete team
+        </Button>
+    );
+}
+```
+
+The host enforces every rule itself, so the disabled state is a convenience, not a guard. In the dev server every team starts with a placeholder participant, so move it out first, or add the team with `pnpm run sdk team add --participants 0`.
+
+`renameTeam` is not the only writer. A team's own participants can rename it from a game UI or waiting room UI, so a session UI should render the name from `setTeamList` rather than from its own optimistic state: there is one name per team, not one per writer, and the last write wins. A blank name and one past the host's cap (60 characters) are both refused as terminal denials, for either writer.
+
+#### Moving a participant
+
+A move has a consequence worth designing for, and one that is easy to confuse it with:
+
+- The participant's **browser loses local component state**, because their game UI remounts against the destination team. Ordinary remount behaviour, and rarely worth warning anyone about
+- Their **earlier writes stay with the source team**. Anything they wrote through `setData` is in that team's context and does not travel, so they arrive with none of their own state
+
+A move does not reset either team. The source team's context, including every pending pre-tick decision in it, is untouched.
+
+The second consequence is what a game handles, and the mechanism is the [`participantMove` hook](./hooks.md): seed the destination on `phase: 'arrival'` the way `participantJoin` seeds a new participant. There is no transfer channel: a hook returns one team's context, so the departure hook's return value is invisible to arrival. A shared-state game carries state across through the shared store; an independent-mode game re-derives it. Warning a facilitator is the fallback for the case where it genuinely cannot be re-derived, not the default: they cannot implement a hook mid-session, so the warning is only useful where you already know re-seeding is impossible.
+
+## Working with participants
+
+Session UIs can enumerate participants across all teams in the session. The hook uses the `Participant` type, which includes a `teamId` field for grouping participants by team.
+
+### Reading the participant list
+
+```typescript
+import {
+    useSessionUserInterfaceParticipants,
+    type Participant,
+} from '@seriousgaming/sdk/ui';
+import { List, ListItem, ListItemText, Chip, Typography, Stack } from '@mui/material';
+
+function AllParticipantsPanel() {
+    const participants = useSessionUserInterfaceParticipants();
+
+    // Group by team
+    const byTeam = participants.reduce<Record<string, Participant[]>>(
+        (acc, p) => {
+            (acc[p.teamId] ??= []).push(p);
+            return acc;
+        },
+        {}
+    );
+
+    return (
+        <>
+            {Object.entries(byTeam).map(([teamId, members]) => (
+                <div key={teamId}>
+                    <Typography variant="h6">{teamId}</Typography>
+                    <List>
+                        {members.map((p) => (
+                            <ListItem key={p.id}>
+                                <ListItemText
+                                    primary={p.name}
+                                />
+                                <Chip
+                                    size="small"
+                                    label={p.connected ? 'Online' : 'Offline'}
+                                    color={p.connected ? 'success' : 'default'}
+                                />
+                            </ListItem>
+                        ))}
+                    </List>
+                </div>
+            ))}
+        </>
+    );
+}
+```
+
+The hook updates reactively whenever:
+
+- A new participant joins any team
+- A participant disconnects (`connected` flips to `false`; the entry stays so you can see who was here)
+
+`Participant` exposes:
+
+| Field       | Type      | Notes                                                   |
+| ----------- | --------- | ------------------------------------------------------- |
+| `id`        | `string`  | Stable identifier; survives reconnects within a session |
+| `name`      | `string`  | Display name (defaults to `Participant N`)              |
+| `index`     | `number`  | Zero-based join order within the team                   |
+| `connected` | `boolean` | Whether the participant has a live platform connection  |
+| `teamId`    | `string`  | The team this participant belongs to (e.g. `"team-1"`)  |
+
+## Rendering inside the host
+
+A session UI is not a standalone page. The host mounts it in an iframe under a thin band of its own chrome, and that changes several things a full-page layout takes for granted. None of it is enforced, and all of it is visible to a facilitator the moment it goes wrong.
+
+### Leave the ground to the host
+
+Do not paint a page background. The host paints the canvas behind your session UI, and a surface painting its own reads as a panel bolted onto the page rather than part of it. It also never quite matches: the host's background is not a colour your theme exposes, so any value you pick is a guess that drifts the next time the host's palette moves.
+
+MUI's `CssBaseline` paints `background.default` on the body, so override it:
+
+```tsx
+import { CssBaseline, GlobalStyles, ThemeProvider } from '@mui/material';
+
+const TRANSPARENT_BODY = { body: { backgroundColor: 'transparent' } };
+
+<ThemeProvider theme={theme}>
+    <CssBaseline enableColorScheme />
+    <GlobalStyles styles={TRANSPARENT_BODY} />
+    {/* your surface */}
+</ThemeProvider>;
+```
+
+Paint backgrounds on the things that are meant to look raised, like cards and panels, not on the page.
+
+### Prefer full-screen dialogs
+
+A centred modal inside an iframe is centred within the frame, not the viewport, and its backdrop dims only the frame. The host's chrome above stays bright, so the result reads as a dialog inside a box rather than a dialog over the page. Use `fullScreen`:
+
+```tsx
+<Dialog open={open} onClose={close} fullScreen>
+    …
+</Dialog>
+```
+
+The same applies to anything anchored to the viewport. A toast pinned to the top, a drawer sliding in from an edge, a sticky bar: each lands against the frame's edge rather than the screen's. Your session UI cannot escape its bounds, so design the overlay to sit inside them deliberately instead of discovering where it lands.
+
+### Do not reproduce host chrome
+
+The Game view / Platform view toggle, the language picker, the theme control, and the guide button all live in the chrome above your session UI. A second copy inside it looks like the same control and is not: yours cannot switch the host's view, and two language menus on one screen is a bug report waiting to happen.
+
+When you want one of the host's own overlays, ask for it with [`openHostOverlay`](#opening-host-overlays) rather than rebuilding it.
+
+### Own your internal scroll
+
+The session UI fills the canvas beneath the chrome at a fixed height. There is no resize handshake, so a surface that grows past the canvas is clipped rather than accommodated. Give your layout a real height and let the part that grows scroll:
+
+```tsx
+<Box sx={{ height: '100%', display: 'flex', flexDirection: 'column', minHeight: 0 }}>
+    <Header />
+    <Box sx={{ flex: 1, overflowY: 'auto', minHeight: 0 }}>{/* the long part */}</Box>
+</Box>
+```
+
+### Take colour from the theme
+
+Read colours from the theme hook below rather than hard-coding them, so your session UI follows the host's light and dark scheme. A surface with a fixed palette is the one thing on screen that does not change when a facilitator switches theme in the room's lighting.
+
+## Using the theme
+
+Edit `src/theme.ts` to use the session theme hook:
+
+```typescript
+import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+import { createTheme } from '@mui/material/styles';
+import { useMemo } from 'react';
+
+export function useAppTheme() {
+    const sdkTheme = useSessionUserInterfaceTheme();
+    return useMemo(
+        () =>
+            createTheme({
+                palette: {
+                    mode: sdkTheme.mode,
+                    primary: {
+                        main: (sdkTheme.mode === 'light' ? sdkTheme.light : sdkTheme.dark).primary,
+                    },
+                },
+            }),
+        [sdkTheme]
+    );
+}
+```
+
+## Dev server behaviour
+
+When you run `pnpm run sdk dev` for a game with session UIs:
+
+1. Your session UI **is** the console. The dev server renders it full-bleed in its canvas, under a band of chrome, and opens on it by default whenever the package ships one
+2. The chrome's **Game view / Platform view** toggle switches between your session UI and the dev server's own roster page, which is the fallback for a package that ships no session UI. It sits outside your iframe, so your session UI cannot suppress it
+3. The chrome also carries the language picker, the theme control, the facilitator guide and print sheets, the scenario and setup entries, and undo / reset / reload. Do not rebuild these inside your session UI; to open the guide or a print sheet, use [`openHostOverlay`](#opening-host-overlays)
+4. The route `/session` also works directly, which is useful for iterating on the session UI alone. Opened that way there is no chrome above it, so a host overlay opens in a new tab rather than in a dialog
+5. Any `setData` calls from the UI iframe are immediately forwarded to the dev server and reflected in the relevant team's game UI
+
+Every surface (the console, each game UI, and the session UI) stays in sync via WebSocket.
+
+## Managing session UIs
+
+### Update definition
+
+```bash
+pnpm run sdk update session '{
+  "definition": {
+    "reads": ["price", "workers"]
+  }
+}'
+```
+
+### Delete
+
+Empties the `session/` slot. A package declares whatever is on disk, so removing the directory is the whole of the removal:
+
+```bash
+pnpm run sdk delete session
+```
+
+## Testing
+
+`renderSessionUserInterface` from `@seriousgaming/sdk/ui/testing` renders a session UI with every provider it reads, seeded with `createMockTeamState` and `createMockSharedState`: see [Session UIs](./testing.md#session-uis) in the testing guide.
+
+## Hooks reference
+
+### useSessionUserInterfaceData
+
+Read session-wide data and write per-team overrides:
+
+```typescript
+import { useSessionUserInterfaceData } from '@seriousgaming/sdk/ui';
+
+const { sessionData, settings, setData } = useSessionUserInterfaceData();
+// sessionData: SessionData, the shared store once (shared.context), and a teams map with each team's own context, tick, and timer
+// setData(partial): writes shared capabilities session-wide
+// settings: the settings resources this surface lists in `settings`, keyed by identifier (see Configuring the surface)
+// setData(teamId, partial): merges partial context into the specified team's state
+// Both forms take { deletes } last: setData(teamId, {}, { deletes: ['pinboard.Notes.p1'] })
+```
+
+### useSessionUserInterfaceTeams
+
+Get the team list:
+
+```typescript
+import { useSessionUserInterfaceTeams } from '@seriousgaming/sdk/ui';
+
+const teams = useSessionUserInterfaceTeams();
+// TeamInfo[]: an array of { teamId, index, name }, sorted by index
+```
+
+### useSessionUserInterfaceTeamConfiguration
+
+Get the interaction mode and the bounds the host will hold the session UI to:
+
+```typescript
+import { useSessionUserInterfaceTeamConfiguration } from '@seriousgaming/sdk/ui';
+
+const { mode, min, max, perTeam } = useSessionUserInterfaceTeamConfiguration();
+// mode: 'independent' | 'shared-state'
+// max: the effective maximum team count, already resolved as the lower of the
+//      game's declared maximum and the platform's own ceiling
+// min, perTeam: advisory guidance to display, not rules to block on
+```
+
+Every bound here is for rendering honest affordances. The host enforces all of them itself, so a surface that disables 'add team' at the maximum is being polite, not authoritative, and must still handle a denial.
+
+### useSessionUserInterfaceMeta
+
+Read the session itself:
+
+```typescript
+import { useSessionUserInterfaceMeta } from '@seriousgaming/sdk/ui';
+
+const { sessionId, name, readOnly, waitingRoomOpen, joinPin } = useSessionUserInterfaceMeta();
+```
+
+`joinPin` is the code participants enter to join, or `null` when joining needs none. How joining is secured is up to the runtime, so it need not be a PIN and some runtimes never set it: render it as an opaque string, and hide the panel when it is `null`. `readOnly` marks a frozen session, so a surface can disable its own controls and explain why rather than offering affordances that will be denied. `waitingRoomOpen` is the current value of a flag the session UI can also write through `setWaitingRoom`; since the host usually renders its own waiting-room control too, read the result back rather than assuming your write won.
+
+### useSessionUserInterfaceTeamLinks
+
+Get each team's facilitator-only URLs, so a game draws its own QR codes and join sheets:
+
+```typescript
+import { useSessionUserInterfaceTeamLinks } from '@seriousgaming/sdk/ui';
+
+const teamLinks = useSessionUserInterfaceTeamLinks();
+// TeamLinks[]: each { teamId, joinUrl, fallbackJoinUrl?, observeUrl }
+```
+
+Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
+
+### useSessionUserInterfaceHostOverlays
+
+Find out which host overlays this host offers, before rendering a control for one:
+
+```typescript
+import { useSessionUserInterfaceHostOverlays } from '@seriousgaming/sdk/ui';
+
+const overlays = useSessionUserInterfaceHostOverlays();
+// HostOverlay[]: 'facilitator-guide' | 'print-sheets'
+```
+
+Empty until the host answers, and empty is also the correct answer for a host that delegates none. It can change mid-session. See [Opening host overlays](#opening-host-overlays).
+
+### useSessionUserInterfaceHookFailures
+
+Report hook chains that threw, on the surface the facilitator is actually looking at:
+
+```typescript
+import { useSessionUserInterfaceHookFailures } from '@seriousgaming/sdk/ui';
+
+const { failures, clearFailures } = useSessionUserInterfaceHookFailures();
+// failures: { signal, teamId, message }[], kept until cleared
+```
+
+A hook failure is deliberately not a failed mutation: hooks fire after the change they react to is applied, so the mutation that triggered them has already settled. Reporting it as failed would invite retrying an action that worked.
+
+### useSessionUserInterfaceLocale
+
+Get the current locale:
+
+```typescript
+import { useSessionUserInterfaceLocale } from '@seriousgaming/sdk/ui';
+
+const { locale } = useSessionUserInterfaceLocale();
+```
+
+### useSessionUserInterfaceTheme
+
+Read the host's colour scheme and palettes (`{ mode, light, dark }`, the same shape as the game UI's theme). See [Using the theme](#using-the-theme) for turning it into an MUI theme:
+
+```typescript
+import { useSessionUserInterfaceTheme } from '@seriousgaming/sdk/ui';
+
+function MyComponent() {
+    const theme = useSessionUserInterfaceTheme();
+    const colours = theme.mode === 'light' ? theme.light : theme.dark;
+    return <div style={{ color: colours.primary }}>Session Dashboard</div>;
+}
+```
+
+### useSessionUserInterfaceParticipants
+
+Reactive list of participants across all teams in the session:
+
+```typescript
+import { useSessionUserInterfaceParticipants } from '@seriousgaming/sdk/ui';
+
+function Roster() {
+    const participants = useSessionUserInterfaceParticipants();
+    return <div>{participants.length} participants across all teams</div>;
+}
+```
+
+Use this to enumerate participants for facilitator workflows like cross-team comparisons or session-wide reporting. See [Working with participants](#working-with-participants) above for the full field reference.
+
+### useSessionUserInterfaceCallbacks
+
+Session-level facilitator callbacks. This is a standalone interface (`SessionUserInterfaceCallbacks`): it does not extend `UserInterfaceCallbacks`. All game-flow callbacks accept an optional `teamId` parameter; omitting it targets all teams.
+
+```typescript
+import { useSessionUserInterfaceCallbacks } from '@seriousgaming/sdk/ui';
+
+const { requestTick, pauseTimer, resumeTimer, undoTick, resetGame } =
+    useSessionUserInterfaceCallbacks();
+```
+
+| Callback            | Signature                                                  | Description                                                                                                              |
+| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `requestTick`       | `(teamId?: string) => Promise<void>`                       | Advance the game by one tick; omit `teamId` to advance all teams                                                         |
+| `pauseTimer`        | `(teamId?: string) => void`                                | Pause automatic ticking; omit `teamId` to pause all teams                                                                |
+| `resumeTimer`       | `(teamId?: string) => void`                                | Resume automatic ticking; omit `teamId` to resume all teams                                                              |
+| `undoTick`          | `(teamId?: string) => Promise<void>`                       | Un-run the last tick, keeping the tick's decisions; omit `teamId` to undo all teams. Naming one is independent mode only |
+| `resetGame`         | `(teamId?: string) => Promise<void>`                       | Re-initialise the game from scratch; omit `teamId` to reset all teams                                                    |
+| `extendTick`        | `(byMs, teamId?) => Promise<void>`                         | Move the currently scheduled tick's deadline by `byMs` milliseconds; negative pulls it in                                |
+| `openHostOverlay`   | `(overlay, target?) => Promise<void>`                      | Ask the host to open the guide or a print sheet                                                                          |
+| `uploadBlob`        | `(file: File) => Promise<string>`                          | Upload a file, returns a `blob:<id>` reference                                                                           |
+| `getAssetUrl`       | `(reference: string) => string`                            | Resolve an `asset:`, `shared:`, or `blob:` reference to a URL                                                            |
+| `readAsset`         | `(reference: string) => Promise<{ data, mimeType, name }>` | Read bytes for an `asset:`, `shared:`, or `blob:` reference                                                              |
+| `endpoints`         | `Record<string, (request) => Promise<Response>>`           | Call a declared endpoint by identifier                                                                                   |
+| `setWaitingRoom`    | `(open: boolean) => Promise<void>`                         | Open or close the session's waiting room; no `teamId`                                                                    |
+| `createTeam`        | `(name?: string) => Promise<void>`                         | Add a team; the host assigns the index                                                                                   |
+| `renameTeam`        | `(teamId, name) => Promise<void>`                          | Rename a team                                                                                                            |
+| `renameParticipant` | `(participantId, name) => Promise<void>`                   | Rename a participant; the host resolves their team                                                                       |
+| `moveParticipant`   | `(participantId, teamId) => Promise<void>`                 | Reassign a participant to another team                                                                                   |
+| `deleteTeam`        | `(teamId) => Promise<void>`                                | Delete an empty team; independent mode only, and never the last team                                                     |
+
+The promise-returning callbacks resolve and reject as described in [Controlling game flow](#controlling-game-flow). The wrapper supplies every callback, so none needs an optional-chaining guard.
+
+To generate text, extract document text, or synthesise speech, declare an [endpoint](../recipes/create-endpoint.md) that wraps `generateText`, `extractText`, or `generateSpeech`, then call it through `callbacks.endpoints['…']`. These callbacks are not exposed to UI iframes. See [Call an endpoint from a UI](../recipes/call-endpoint-from-ui.md).
+
+### Message protocol
+
+The `SessionUserInterfaceWrapper` holds the fallback until every required message has arrived:
+
+| Required message       | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `setSessionData`       | The shared store and all teams' state            |
+| `setSessionMeta`       | Session identity and lifecycle state             |
+| `setSettings`          | The settings this session UI declares, resolved  |
+| `setTheme`             | Colour scheme and palettes                       |
+| `setLocale`            | Current locale string                            |
+| `setAssetUrls`         | Prefixes for resolving asset and blob references |
+| `setTeamConfiguration` | Interaction mode and team bounds                 |
+
+`setTeamConfiguration` gates first paint because its default cannot be rendered honestly: a surface painting before bounds arrive would hold a maximum of zero and disable the controls that read it.
+
+Additional messages sent after initialisation:
+
+| Additional message   | Description                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `setTeamList`        | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
+| `setTeamLinks`       | Updates each team's facilitator-only join and observe URLs                                               |
+| `setParticipantList` | Updates the participant roster across all teams                                                          |
+| `hookFailed`         | Reports a hook chain that threw                                                                          |
+
+## Examples
+
+The session UI follows the same file structure conventions as other UI resource types. The starter game's `session/` is a complete one: per-team status, join and observe links, a shared briefing, and the waiting room and guide toggles (see [A tour of the starter game](./starter-game.md#session)).
+
+## See also
+
+- [Multi-team games](./multi-team-games.md) - Independent and shared-state interaction modes
+- [Building user interfaces](./ui.md) - Building participant-facing game UIs
+- [Building a setup screen](./setup.md) - The form at session creation
+- [Building a scenario editor](./scenario-editor.md) - Authoring lasting scenarios
+- [Tick controllers](./tick-controller.md) - Automatic tick timing
+- [Testing](./testing.md) - Writing UI tests
+- [CLI reference](../cli-reference.md) - `new`, `update`, and `delete session` commands