# Private phone views

Use a private view when a player needs information or input that does not belong on the shared screen. Send it with `ControllerHost.setView(playerId, view)` or the corresponding engine adapter method.

| Kind | Purpose | Important fields |
| --- | --- | --- |
| `gamepad` | Normal controls | `title`, `hint`, optional game-specific instructions |
| `waiting` | A joined player waiting for a round | `title`, `text` |
| `secret-role` | A role, clue and private choices | `role`, `clue`, `text`, `choices`, `submitted`, `phase` |
| `drawing` | An artist's prompt or a guesser's view | `artist`, `prompt`, `colors`, `ink`, `phase`, `feedback` |
| `keypad` | Split code fragments and dials | `fragment`, `text`, `phase` |
| `desktop` | Companion-controlled pointer/typing view | Requires separate owner-approved system-control authority |

The current clients implement these view types. They do not render arbitrary HTML or execute scripts supplied by a game. A new view type needs a client implementation and a documented fallback.

## Send choices

A secret-role view can provide choices with an ID, visible label and event name. The phone returns the selected target as an event. The server decides whether the choice is allowed, whether it may be changed, and what it means.

```js
controllers.setView(playerId, {
  kind: 'secret-role',
  title: 'Midnight Table',
  role: 'seer',
  text: 'Choose a player to inspect.',
  choices: [{id: 'p2', label: 'Player 2', event: 'choose'}],
  submitted: false,
  phase: 'night'
});
```

Do not send the other roles as hidden fields. Hidden UI is not an access-control mechanism. The client should receive only information that player is permitted to know.

## Drawing and text

Drawing arrives as bounded point batches with a color and width. Validate authorship, coordinate range, ink/time budget and round phase before accepting it. Guesses need length and attempt limits. Never send the hidden answer in the guesser's view.

Keep large media outside these small view messages. Camera/AR and other advanced capabilities need their own declared, permission-aware adapters; they are not implied by a `view` payload.

For a gamepad view, `labels` is `classic` or `standard`. Players can override the printed letters without changing positional IDs. `completeControls: true` selects a full layout with both sticks and all sixteen logical buttons; it does not require Pro.