# Interaction and accessibility

[Documentation index](README.md) · [Troubleshooting](troubleshooting.md) · [Result contract](result-contract.md)

Pi Rich Questions uses Pi's terminal UI and Editor component. Press `Ctrl+H` inside a form to toggle its contextual guide.

## Complete keyboard reference

| Key | Outside an editor | Inside an editor |
| --- | --- | --- |
| `↑` / `↓` | Move between choice options | Move the editor cursor |
| `Enter` | Select a radio option and advance; continue/save/submit where shown | Submit the current editor value |
| `Space` | Toggle a checkbox option | Insert a space |
| `N` | Edit a response note on the current predefined option | Insert text normally |
| `Shift+Enter` | — | Insert a newline when the terminal reports it to Pi Editor |
| `Tab` | Next question | Next question after saving the editor |
| `Shift+Tab` | Previous question | Previous question after saving the editor |
| `←` / `→` | Previous / next question | Move the editor cursor |
| `PgUp` / `PgDn` | Scroll by a visible page | Scroll the form by a visible page |
| `Home` / `End` | Jump to the top / bottom of form content | Retain Pi Editor behavior |
| `Ctrl+U` / `Ctrl+D` | — | Retain Pi Editor behavior |
| `Ctrl+H` | Toggle the guide | Toggle the guide |
| `Esc` | Cancel the form | Save and leave the active editor; a second press cancels |
| `Ctrl+C` | Cancel immediately | Cancel immediately |

On the review screen, the multiline “Additional freeform text” editor is optional. Required unanswered questions prevent final submission; navigate back and answer them.

## Multiline input and terminal protocols

Text answers, custom “Other” values, option response notes, and review notes use Pi Editor. The extension delegates raw line-feed, `Shift+Enter`, and backslash-plus-Enter behavior to that component rather than decoding terminal protocols itself.

Terminals differ in how they encode modified Enter. If `Shift+Enter` submits instead of inserting a line break, try the newline sequence supported by your Pi/terminal setup and consult Pi's terminal/keybinding documentation. Report the terminal, multiplexer, operating system, and whether a modified-key protocol is enabled when filing a bug.

## Long content and small terminals

The form is a terminal-width modal overlay. All rendered lines are truncated/wrapped to visible terminal width using Pi's ANSI- and Unicode-aware utilities. A viewport follows the active field; `PgUp` and `PgDn` switch to manual scrolling within the form rather than scrolling the transcript. An overflow line shows hidden rows above and below.

Automated fixtures cover ANSI text, CJK, emoji, combining characters, long tokens, one-row viewports, small modal heights, and visibility of Pi Editor's cursor marker. Extremely small terminals remain constrained by how much useful content a terminal can display; enlarge the terminal when practical.

## Unicode, ANSI, IME, and cursor behavior

- **Unicode and ANSI:** width calculations use Pi TUI's visible-width, wrapping, and truncation utilities; formatting escape codes should not count as visible columns.
- **IME input:** input is delegated to Pi Editor. Composition behavior depends on the terminal and Pi; it is not independently implemented by this extension.
- **Hardware cursor:** the active editor exposes Pi Editor's focus and cursor marker through the custom component. Cursor placement ultimately depends on Pi TUI and terminal behavior.
- **Themes:** Markdown uses the active Pi theme. Component invalidation also invalidates the editor; reload after extension changes if rendering appears stale.

## Cancellation and recovery

`Ctrl+C` cancels from any form state. `Esc` is deliberately two-stage while editing so an accidental escape does not discard the entire form. Cancellation does not submit partial answers: the tool reports a cancelled result, while the slash command shows a cancellation notification.

There is no persisted draft. If the session or terminal closes, invoke the tool or command again. `/rich-questions` can re-extract the latest completed assistant text; malformed extraction falls back to the preserved original message rather than silently dropping it.