docs: update docs (#43)

- macOS, Linux badge and AI suggestions showcase in README - Update user guide and docs for development
2026-07-27 19:50:28 +07:00
parent 1540b9655a
commit 078e5e817c
13 changed files with 490 additions and 333 deletions
@@ -0,0 +1,39 @@
+# Overlay rendering UI (`integration/overlay.go`)
+
+The `overlay` package handles the visual representation of suggestions. It is designed to be non-destructive, drawing over the shell without corrupting the prompt or scrollback buffer.
+
+## Design philosophy
+
+- **ANSI ESC everywhere**: Uses ANSI escape sequences and CSI (Control Sequence Introducer) codes to manipulate terminal positioning.
+- **Save and restore**: Uses DECSC (`\0337`) and DECRC (`\0338`) escape sequences to return to prompt anchor after drawing.
+- **Fixed width**: Menu box uses a standard 72-character width (`boxWidth`) for consistent layout rendering.
+
+## Technical details
+
+The overlay engine manages positioning, scrolling protection, and styled cell drawing directly on the terminal grid.
+
+### Terminal scrolling protection
+
+When rendering near the bottom of the screen, printing new lines causes terminal scrolling which buries the active prompt. Iris prevents this by:
+
+1. Moving to the prompt anchor.
+2. Printing N empty newlines to pre-allocate scroll space.
+3. Moving back up N lines.
+4. Re-saving the cursor at this stabilized location.
+
+### Styling with Lipgloss
+
+While Iris handles cursor positioning via raw ANSI codes, visual component styling uses Lipgloss:
+
+- **Colors**: Dracula-inspired color theme (`#BD93F9`, `#6272A4`).
+- **Icons**: Fixed-width columns for category badges and completion types.
+- **Selection**: Highlights the currently active suggestion item with a distinct background (`#44475A`).
+
+## Example logic
+
+To render line 1 of the menu dropdown:
+
+1. `\0338` (Jump to prompt anchor).
+2. `\033[2B` (Move 2 lines down).
+3. `\033[K` (Clear line buffer).
+4. Print formatted item: `│ [Icon] Command name... │`.