ELYTerminal/PRD.md

# ELYTerminal PRD

A terminal for macOS, Windows and Linux. Rust, GPUI, Ely components. It draws a terminal as well as Ghostty does, shows every setting on screen, and makes no noise.

Chapters run in build order. `TASKS.md` follows them line by line.

## 1. Product

- One window. Sessions on the left, the terminal in the middle, Git or Files on the right.
- Every setting has a control in the settings window. No setting lives only in a file.
- Silent: no sound, no bell, no notifications, no update checks, no telemetry, no tips, no onboarding.
- Clean: no subtitle, no tagline, no logging options, no status bar, no badges that do not carry state.
- Built-in themes, each shown as a small preview, Catppuccin among them. A theme colors the terminal and the chrome.
- The window background blurs on macOS, Windows, Wayland and X11.

## 2. Foundation

- One binary crate, `elyterminal`, edition 2024, Rust 1.95.
- Ely from git.zacharyzhang.com by pinned rev. gpui, gpui_platform from crates.io `gpui-pre` at the exact version Ely pins.
- `alacritty_terminal` 0.26 for the grid, the parser and the pseudo-terminal, as Ely uses it.
- Logs through `log` to stderr, `RUST_LOG` sets the level. No log setting in the app.
- CI on Gitea Actions: macOS builds, tests and lints; Ubuntu and Windows build and test.
- Private repo `ELYTerminal` on git.zacharyzhang.com. No credential in any file or commit.

## 3. Settings model and storage

- One JSON file, `settings.json`, in the platform config folder (`dirs::config_dir()/ELYTerminal`).
- Every field has a default. A missing file means defaults. A missing field means its default.
- A file that does not parse, or a value out of range, stops the start with an error naming the file and the field. The app never overwrites a file it could not read.
- Writes go to a temp file in the same folder, then rename. One writer: the app's settings entity.
- Fields: see chapter 10.

## 4. Themes

- Built in: Ely Dark, Ely Light, Catppuccin Mocha, Catppuccin Macchiato, Catppuccin Frappé, Catppuccin Latte, Tokyo Night, Dracula, Nord, Gruvbox Dark, Rosé Pine, Solarized Light, One Light, Kanagawa Wave.
- A theme holds background, foreground, cursor, cursor text, selection background and foreground, and the 16 ANSI colors. Values come from the theme's upstream files (iTerm2-Color-Schemes' Ghostty export, or Ely's palette).
- A theme maps onto Ely's `Palette` through `Theme::set_palette`, so panels, inputs and lists wear the theme.
- Dark mode: one theme, or a second theme for when the system is dark.

## 5. Terminal engine

Ghostty is the bar for what the terminal does. ELYTerminal owns its engine on `alacritty_terminal`; Ely's `Terminal` is a gallery widget without mouse reporting, IME, kitty keys or style settings.

- PTY: alacritty's `tty` and event loop. The pty is wrapped so its reader passes bytes through an OSC 7 scanner. The scanner reports the working directory.
- Shell integration for zsh, bash, fish and PowerShell, injected at launch as Ghostty does: each prompt sends OSC 7 and a title. A shell without integration reports nothing, and the panels say so.
- Grid: colors (named, 256, truecolor, OSC 4/10/11/12), bold, dim, italic, underline (single, double, curly, dotted, dashed), strikethrough, inverse, hidden, wide characters, combining marks.
- Box drawing (U+2500–U+257F), block elements (U+2580–U+259F) and powerline shapes (U+E0B0–U+E0B7) painted as geometry, so lines and segments join across cells.
- Fonts: JetBrains Mono by default, any installed font by choice; Nerd Font icons the font lacks come from a bundled Nerd Font.
- Cursor: block, bar, underline, hollow block; blinking per setting and per DECSCUSR; hollow when the window is not focused.
- Keys: xterm encoding with modifiers, application cursor mode, Option as Alt on macOS, the kitty keyboard protocol as the program sets its flags. Keypad keys type their characters, as Ghostty's do with mode 1035 on by default.
- IME: marked text drawn at the cursor; committed text sent to the program.
- Mouse: select by character, word (double press) and line (triple press); Shift extends; mouse reporting (X10, normal, button, any; SGR and UTF-8); wheel scrolls back, or reports, or sends arrows on the alternate screen.
- Clipboard: copy, paste (bracketed when asked), copy on select per setting, OSC 52 writes.
- Links: OSC 8 and plain URLs; Cmd-press (Ctrl-press off macOS) opens them.
- Focus reporting, title (OSC 0/2), scrollback limit per setting, find in scrollback (Ely's `FindWidget`).
- Bell: no sound. The session row marks it until the session is shown.

## 6. Main window and layout

- Ely's `ColumnShell`: sessions column, terminal column, right column. The window opens with blur when the setting is on.
- The sessions column and the right column toggle, each by a button at its end of the title bar or by key, and keep their state in settings, so the window opens as it was left.
- The title shows the active session's title, and no other text.
- The title bar is transparent, as Ghostty's: the window's background, opacity and blur run under it, so it wears the terminal's color.

## 7. Sessions panel

- A list of sessions. Each row: title, then the working directory, home as `~`.
- New session (+ and Cmd-T), close (row's ×, Cmd-W), select (press, Cmd-1…9, Ctrl-Tab and Ctrl-Shift-Tab).
- A session whose program ends closes its row. The last row closing closes the window.
- A bell in a hidden session marks its row.

## 8. Right panel: Files

- A switch at the top: Git, Files.
- Files shows the active session's working directory as a tree, folders first, Git status colors on names.
- Double press: a folder opens, a file opens in the system's default app.
- It reloads when the session reports a new directory and at each prompt.

## 9. Right panel: Git

- Through the `git` command line. No libgit2.
- Shows the branch, staged and unstaged changes, a commit message field and Commit, and recent commits.
- Stage and unstage a file. Press a file to see its diff in Ely's `DiffViewer`.
- Discard, which Ely's changes list draws on every unstaged and untracked row, asks first: an edit goes back to the index, a new file is deleted.
- Outside a repository it says so. A failed git command shows its error.
- It reloads at each prompt and on directory change.

## 10. Settings window

Cmd-, opens it. Categories on the left, rows on the right, Ely's settings components. Changes apply at once to every session and save.

- General
  - Shell: a path; empty runs the login shell.
  - Start in: Home, or the active session's folder.
- Appearance
  - Theme: a grid of previews.
  - Separate dark theme: a switch; when on, a second grid for dark mode.
  - Font family: a list of installed fonts. Font size. Line height. Ligatures.
  - Cursor: style (block, bar, underline, hollow), blink, with a live preview.
  - Background opacity: a slider. Background blur: a switch.
  - Padding: horizontal and vertical.
- Terminal
  - Scrollback lines.
  - Option as Alt: off, left, right, both (macOS only).
  - Copy on select.

## 11. Background blur

- macOS: gpui's `WindowBackgroundAppearance::Blurred` (NSVisualEffectView).
- Windows: gpui's `Blurred` (acrylic accent).
- Wayland: gpui's `Blurred` speaks `org_kde_kwin_blur`; ELYTerminal adds `ext_background_effect_v1` on the window's surface, which GNOME 51 and Plasma 6.7 support.
- X11: ELYTerminal sets `_KDE_NET_WM_BLUR_BEHIND_REGION` (CARDINAL, 32) on the window, as Ghostty does; removes it when blur turns off.
- A compositor with neither protocol shows transparency without blur. The app logs which path it took.

## 12. Menus and shortcuts

- macOS menu bar: ELYTerminal (Settings, Quit), Shell (New Session, Close Session), Edit (Copy, Paste, Select All, Find), View (Toggle Sessions, Toggle Right Panel, Bigger, Smaller, Reset Size), Window.
- The same shortcuts on Windows and Linux with Ctrl-Shift for terminal-colliding keys.

## 13. Acceptance

- Each chapter's tasks ticked in `TASKS.md` with a passing review in `tasks/reviews.md`.
- `scripts/check.sh` passes: fmt, clippy with `-D warnings`, tests, no file over 500 lines.
- CI green on macOS, Ubuntu and Windows.

## 14. Icon and the macOS app

- The icon is Ely, a girl with long pink hair, holding a terminal in front of her.
- macOS: the icon on the rounded square macOS gives app icons. Windows and Linux: the figure alone, no ground, flat, as Papirus draws.
- `scripts/mac-app.sh` builds `ELYTerminal.app` from a release build with its icon, signed ad hoc, and a disk image holding it beside a link to Applications.

## 15. Release

- A release on Gitea, tagged `vVERSION`, carries three builds: the macOS disk image (Apple silicon), a Windows zip (x86_64) and a Linux tarball (x86_64).
- The Windows executable carries the icon. The Linux tarball carries the icon and a desktop entry, and the window names itself after it, `com.zacharyzhang.elyterminal`, as the macOS bundle does.
- Each build comes from its platform's script: `scripts/mac-app.sh`, `scripts/windows-zip.ps1`, `scripts/linux-tar.sh`.

## Deferred

Splits, tabs inside a session, profiles, key rebinding, kitty graphics, sixel, OSC 133 prompt marks, session restore, push and pull, quick terminal.