From 955f3ff1d73e39a7511285dff0832c982154edbe Mon Sep 17 00:00:00 2001 From: Sergey Fedorov Date: Sun, 19 Jul 2026 14:16:29 +0000 Subject: [PATCH 29/71] docs(macos): feature roadmap for the native frontend A grounded subset of upstream contour's features: color themes (dark/light), minimal preferences (theme/font/encoding/terminal-id), standard Window menu, full-screen (native + a 10.6 manual path), drag & drop, scrollback wheel scroll, selection->copy, plus an OpenGL 2.0/2.1 render backend (sibling of the CPU SoftwareRenderTarget, with runtime CPU fallback). Notes the pre-existing uneven-spacing issue and that tabs/split panes are engine-supported (vtmux) but frontend-deferred. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01AeG2jwYMX5gdvvtUnx3PJa --- docs/macos-roadmap.md | 103 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/macos-roadmap.md diff --git a/docs/macos-roadmap.md b/docs/macos-roadmap.md new file mode 100644 index 00000000..aa73eccd --- /dev/null +++ b/docs/macos-roadmap.md @@ -0,0 +1,103 @@ +# contour macOS frontend — feature roadmap + +Status as of the first running build: native AppKit window, live PTY-backed shell, +CPU (CoreGraphics) rendering, keyboard + basic mouse input, standard menu bar +(Shell: New/Close; Edit: Copy/Paste/Select All; Quit). The mixed-compiler build works +(C++23 engine via modern gcc, ObjC++ frontend via gcc-4.2, linked through the opaque +SessionBridge). Primary target macOS 10.6 PowerPC; also modern macOS. + +This roadmap is a grounded subset of what upstream contour offers (its config surface +includes colorschemes, fullscreen, tabs/splits, scrollbar, history, bell, opacity/blur, +permissions, mouse, image protocols, terminal_id) — "normal minimal features users expect, +plus whatever is cheap to add," not visual parity with the Qt GUI. + +## Known open issues (pre-existing, tracked) + +- **Uneven character spacing** — `advanceToCells` rounds per-glyph advances to whole cells; + the shaper's advances don't cleanly equal the cell width, so spacing drifts. Fix in the + shaping/advance path (force monospace advance == cell width), not the compositor, without + distorting glyphs. (Task in the tracker.) +- **libstdc++ malloc noise** — only if it ever causes a real crash; the MacPorts DYLD + wrapper handles it. Do not touch otherwise. + +## Requested features (this roadmap's core) + +Priority order is roughly top-to-bottom; each is independent unless noted. + +### 1. Color themes (dark + light, minimum) +Contour has full colorschemes. Minimum: ship a **dark** and a **light** built-in palette, +selectable, applied to `vtbackend::ColorPalette` (which the engine already themes). The +compositor and engine already consume the palette; this is wiring + two palette tables. +Later: honor the system appearance (10.14+ dark mode) where available; on 10.6 it is a +manual/config choice. + +### 2. Preferences (minimal) +A small preferences window (or plist-backed defaults) covering: +- **Default theme** (dark/light, from #1). +- **Default font** (family + size; the engine already takes a `FontDescriptions`). +- **Default encoding** — practically UTF-8; expose the option even if UTF-8 is the only + sane default initially. +- **"Declare terminal as" (`TERM` / terminal id)** — `TERM` value sent to the shell + (currently hardcoded `xterm-256color`) and/or the VT identification (`Settings.terminalId`, + default VT525). Expose both: the `TERM` env string and the DA/DA2 terminal id. +Persist via `NSUserDefaults`. Keep it a plain AppKit window, no fancy UI. + +### 3. Window menu (standard macOS) +The standard **Window** menu that lists open windows, with Minimize/Zoom and the +auto-maintained window list. AppKit provides most of this via `-[NSApplication windowsMenu]` +and `addWindowsItem:`; wiring it is small. Complements the multi-window support already in +place (New Window). + +### 4. Full-screen support +Native full screen. On modern macOS: `NSWindowCollectionBehaviorFullScreenPrimary` + +`toggleFullScreen:`. On 10.6 (pre-Lion, no native full screen): a manual full-screen mode +(borderless window sized to the screen, menu item toggles it). Provide both paths behind one +menu item / shortcut. + +### 5. Drag & drop +- **Drop onto the terminal**: files/text dropped in paste their path(s)/content to the shell + (register `NSFilenamesPboardType` / string types on the view; on drop, `sendPaste` the + path(s)). Standard terminal behavior. +- Optionally **drag out** a selection as text (lower priority). + +## Additional low-cost features worth adding (from contour, cheap here) + +These are cheap because the engine already implements the behavior; only frontend wiring or +a palette/flag is needed: +- **Scrollback + scroll input** — wheel/trackpad scroll maps to the engine's viewport scroll; + optional scrollbar. (Engine has full history + viewport.) +- **Mouse selection → copy** — drag-select already routes through the mouse events; verify + selection rendering and that Copy grabs it. (Selection API is in the engine.) +- **Bell** — already wired to `NSBeep`; add a visual-bell option later. +- **Window title from the shell (OSC 0/2)** — already wired (`setWindowTitle`). +- **Cursor shape/blink** — engine supports Block/Bar/Underline/Rectangle + steady/blink; + expose as a preference. (Note the block-cursor "char stays visible" invariant.) +- **Sixel / image display** — the compositor's `ImageTextureBackend` path exists; verify + end-to-end once text is solid (this was a motivating feature of the whole port). +- **Font ligatures / fallback fonts** — engine supports; wiring/config only. + +## Rendering: OpenGL 2.0/2.1 backend (with CPU fallback) + +Add a **GL 2.0/2.1 render backend** as a sibling of the CPU `SoftwareRenderTarget`, +implementing the same three interfaces (`RenderTarget` + `AtlasBackend` + +`ImageTextureBackend`). The seam is already abstract, so this is a drop-in: +- Atlas → a GL texture (`glTexSubImage2D` for `uploadTile`); whole-image textures likewise. +- `renderTile`/`renderImageQuad` → textured quads (`glDrawArrays`), GLSL 1.20 fragment + shaders downported from `text.frag` (the per-selector tint math already documented). +- Straight-alpha src-over via `glBlendFunc`; `glScissor` for clipping. +- Host via `NSOpenGLView` / `NSOpenGLContext` (GL 2.1 available on 2005-era PPC GPUs and + later Intel; modern macOS keeps a GL 2.1 compatibility profile). +- **Fallback**: if GL context creation or a required feature is unavailable, fall back to the + CPU `SoftwareRenderTarget` at runtime. Config/auto-detect chooses the backend; the CPU + path stays the reference and the guaranteed floor. + +This is the performance path (CPU per-pixel blending on every keystroke/`cat` is the risk on +slow PPC memory bandwidth). The CPU backend was built first deliberately as the correctness +reference the GL backend is validated against. + +## Explicitly out of scope for now (from contour, deferred) + +Tabs and split panes (engine model `vtmux` is present and linked, so the frontend can add +them later — nice-to-have, not required now); tmux control mode; the QML settings pages; +shell-integration niceties beyond the basics; blur-behind / vibrancy; per-profile config +files (a minimal preferences store covers the near-term need).