Add or change a terminal screen #
Use this guide when changing the terminal client. Preserve its shared layout and interaction rules instead of designing each list screen independently.
Compose the shared components #
Build list screens from listFrame,
listView,
confirm, and the
matchFields and searchWords matcher.
Embed pageStatus for loading, saving, errors,
and request generations.
Let the frame own clipping, pane placement, and height arithmetic. Supply the
list, pane, summary, and footer. Do not add screen-specific terminal clipping or
Height-N layout constants. Put essential facts first in the pane because short
terminals cut its bottom. Put errors and notices in the footer, not in data
rows.
Keep list filtering live. Route movement and typing through listView.update,
and compute its command before returning the updated model. Use setRows to
preserve the cursor's row across reloads. Do not use bare letters as list
actions. Chat and the agents canvas have different input needs and do not use
the list layout.
Keep matcher behavior consistent with the web matcher and the shared search cases. Change both clients when changing matching rules.
Keep requests within their screen generation #
Carry the starting generation on every asynchronous request and reply. Use
pageStatus.settle or an equivalent generation check before accepting a reply.
Commands can outlive a closed screen, so reopening the screen must use a new
generation. Invalidate requests when their target changes too.
Keep the last valid rows after a failed refresh. A reply without a listing does
not establish that the listing is empty. Re-read state after a mutation,
including a refused mutation. Follow
WebhooksPageModel for the load, save,
and refresh flow.
Preserve key meanings #
Use these conventions for new list actions. Show screen-specific actions in the footer.
| Key | Action |
|---|---|
| Up, Down, Ctrl+P, Ctrl+N, Page Up, Page Down | Move through rows with listView. |
| Enter | Run the row's main action. |
| Shift+Enter or Alt+Enter | Apply the action to this session where session scope exists. |
| Ctrl+X | Drop this session's choice and follow the global choice. |
| Ctrl+D | Delete, remove, or unlink after confirmation. |
| Ctrl+E | Edit. |
| Ctrl+O | Add, create, or link. |
| Ctrl+R | Refresh or retry a load. |
| Escape | Go back, or cancel the current form or confirmation. |
Do not clear the filter on Escape instead of going back. Keep ordinary typing, including spaces, available to the filter. Existing exceptions include Ctrl+R for rename in the session picker and login profile picker. The agents canvas uses Ctrl+X to delete and Ctrl+F to search. The Discord channel view uses Space to cycle delivery. Preserve existing exceptions when changing those screens rather than applying the table blindly.
Confirm consequential actions #
Use confirm for destructive or far-reaching actions, including replacing a
secret or enabling something that reloads a session. Let Enter accept and Escape
or Ctrl+C cancel. Ignore other keys. Do not introduce a bare y confirmation or
cancel on any other key. Cheap, reversible toggles can act directly.
Name the affected scope in the prompt. Some terminals send plain Enter for Shift+Enter, so the prompt must make a global versus session-only choice visible before acceptance. If an action cannot succeed, explain the reason instead of asking a question that can only fail.
Check the screen #
Register relevant states in the shot gallery
and inspect the rendered result at wide and narrow sizes. Cover filtering,
loading, empty results, errors, forms, and confirmations where applicable. Set
ALBEDO_SHOT_DIR to run the gallery; ordinary test runs skip rendering it.
Follow the repository UI review instructions
for commands and cleanup.
When keys change, update the affected key-routing tests, real-daemon scenarios
in cli/test/e2e, and gallery states that show the footer.
Keep focused tests for stale replies and in-flight rendering when those
behaviors change.