From 955f3ff1d73e39a7511285dff0832c982154edbe Mon Sep 17 00:00:00 2001
From: Sergey Fedorov <barracuda@macos-powerpc.org>
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) <noreply@anthropic.com>
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).
