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) and block elements (U+2580–U+259F) painted as geometry, so lines join across cells.
• 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 and keypad modes, Option as Alt on macOS, the kitty keyboard protocol as the program sets its flags.
• 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 and keep their state in settings.
• The title shows the active session's title. Nothing else in the title bar.

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.
• 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.

Deferred

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