small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs tui-contributing.md
5.4 kB · 104 lines
Markdown
at main

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.