6c341990
docs: record appearance approval and GUI parity backlog
a73x 2026-09-06 06:20
Commit message
RETRO.md
| Old | New | ||
|---|---|---|---|
| @@ -812,10 +812,10 @@ Recorded demo acceptance was subsequently given on 2026-09-05, as noted below. | |||
| 812 | 812 | ||
| 813 | - [x] Record the user's review of the appearance demo separately from test | 813 | - [x] Record the user's review of the appearance demo separately from test |
| 814 | success: the recorded demo was approved on 2026-09-05; config/fonts follows. | 814 | success: the recorded demo was approved on 2026-09-05; config/fonts follows. |
| 815 | - [ ] In the config slice, restore `theme.legacy` as the no-config default and | 815 | - [x] Completed in slice 2: restore `theme.legacy` as the no-config default and |
| 816 | explicitly select a trial theme in appearance fixtures. Keep CLI precedence | 816 | explicitly select a trial theme in appearance fixtures. Keep CLI precedence |
| 817 | and font-size units consistent with the agreed Ghostty-compatible subset. | 817 | and font-size units consistent with the agreed Ghostty-compatible subset. |
| 818 | - [ ] Verify installed Nerd Font Mono symbols in the font slice; font fallback | 818 | - [x] Verified in slice 2: installed Nerd Font Mono symbols; font fallback |
| 819 | and cross-cell ligatures are not implied by choosing a family. | 819 | and cross-cell ligatures are not implied by choosing a family. |
| 820 | - [ ] Next renderer/offscreen-fixture work: investigate unpainted 0xaa capture | 820 | - [ ] Next renderer/offscreen-fixture work: investigate unpainted 0xaa capture |
| 821 | regions after offscreen surface growth if dynamic resizing is needed there. | 821 | regions after offscreen surface growth if dynamic resizing is needed there. |
| @@ -845,8 +845,8 @@ Automatic approval review rejected publishing this payload through Tailscale; | |||
| 845 | specific user approval was requested while the completed page remained local. | 845 | specific user approval was requested while the completed page remained local. |
| 846 | Native source is unchanged, so existing functional validation applies. | 846 | Native source is unchanged, so existing functional validation applies. |
| 847 | 847 | ||
| 848 | - [ ] Use the review webpage as the final handoff link in future slices; keep | 848 | - [x] Review webpage handoffs retained in slices 2 and 3, with validation limits |
| 849 | failed checks and pending acceptance visible beside the recording. | 849 | and acceptance status beside the recording. This remains the standing workflow. |
| 850 | - [x] Record the verified private URL and route-specific teardown in the | 850 | - [x] Record the verified private URL and route-specific teardown in the |
| 851 | appearance plan. The user authorised sharing sprint pages/assets on their | 851 | appearance plan. The user authorised sharing sprint pages/assets on their |
| 852 | own tailnet as the standing handoff. The recorded demo was then explicitly | 852 | own tailnet as the standing handoff. The recorded demo was then explicitly |
| @@ -891,12 +891,12 @@ cumulative agent counters (cached input included, not incremental cost) live in | |||
| 891 | - [x] Keep the webpage/video as the primary private handoff. | 891 | - [x] Keep the webpage/video as the primary private handoff. |
| 892 | - [x] Record slice 2 demo acceptance separately from tests; theme files authorised | 892 | - [x] Record slice 2 demo acceptance separately from tests; theme files authorised |
| 893 | on 2026-09-06. | 893 | on 2026-09-06. |
| 894 | - [ ] Theme slice: extend the strict parser intentionally and document the supported | 894 | - [x] Completed in slice 3: extend the strict parser intentionally and document the supported |
| 895 | Ghostty subset, defaults → theme → config → CLI precedence, and missing/default | 895 | Ghostty subset, defaults → theme → config → CLI precedence, and missing/default |
| 896 | behavior. Keep font-family lifetime and late raster rounding intact. | 896 | behavior. Keep font-family lifetime and late raster rounding intact. |
| 897 | - [ ] Renderer follow-up retains the earlier intermittent NVIDIA budget miss and | 897 | - [ ] Renderer follow-up retains the earlier intermittent NVIDIA budget miss and |
| 898 | offscreen surface-growth readback issue; a passing run does not settle either. | 898 | offscreen surface-growth readback issue; a passing run does not settle either. |
| 899 | - [ ] Discuss ligatures only after the preceding appearance slices. | 899 | - [x] Scope decision recorded on 2026-09-06: defer ligatures for now and review GUI/TUI parity. |
| 900 | 900 | ||
| 901 | ## Native appearance: Ghostty theme loading — 2026-09-06 | 901 | ## Native appearance: Ghostty theme loading — 2026-09-06 |
| 902 | 902 | ||
| @@ -908,8 +908,8 @@ under the worktree. Opening inspection found no preliminary refactor needed. | |||
| 908 | Implemented theme lookup by config-directory filename or absolute path, strict | 908 | Implemented theme lookup by config-directory filename or absolute path, strict |
| 909 | color/palette parsing, theme/config/CLI precedence, diagnostic warnings for | 909 | color/palette parsing, theme/config/CLI precedence, diagnostic warnings for |
| 910 | unsupported theme keys, and derived chrome for light/dark palettes. No-config | 910 | unsupported theme keys, and derived chrome for light/dark palettes. No-config |
| 911 | and font-only settings retain legacy appearance. Ligatures remain a later scope | 911 | and font-only settings retain legacy appearance. The user subsequently deferred |
| 912 | discussion. Closing cleanup removed a no-op callback, unused alias, and duplicate | 912 | ligatures on 2026-09-06 to focus on GUI/TUI parity. Closing cleanup removed a no-op callback, unused alias, and duplicate |
| 913 | palette index storage. Review found packed-channel overflow, missing cursor | 913 | palette index storage. Review found packed-channel overflow, missing cursor |
| 914 | fallback, loose lexical parsing, wrong diagnostic wording, and a contrast | 914 | fallback, loose lexical parsing, wrong diagnostic wording, and a contrast |
| 915 | calculation that returned different colors from those it measured. Root fixed | 915 | calculation that returned different colors from those it measured. Root fixed |
| @@ -917,8 +917,9 @@ the final contrast mismatch and added regression checks; real pixels verified | |||
| 917 | the integrated behavior after agent review. | 917 | the integrated behavior after agent review. |
| 918 | 918 | ||
| 919 | Native units/core, full native integration, offscreen theme acceptance, NVIDIA | 919 | Native units/core, full native integration, offscreen theme acceptance, NVIDIA |
| 920 | theme/DPI acceptance, and retained scale/resize acceptance passed. Final delivery validation and recording are complete; the recorded demo awaits | 920 | theme/DPI acceptance, and retained scale/resize acceptance passed. Final delivery |
| 921 | user acceptance. The first CI attempt exposed a | 921 | validation and recording are complete; the user approved the recorded demo on |
| 922 | 2026-09-06 (“LGTM”). No separate hands-on trial is inferred. The first CI attempt exposed a | ||
| 922 | baseline QUIC stop timeout; the focused retry passed, but source inspection found | 923 | baseline QUIC stop timeout; the focused retry passed, but source inspection found |
| 923 | that daemon shutdown quietly freed QUIC connections without sending a goodbye. | 924 | that daemon shutdown quietly freed QUIC connections without sending a goodbye. |
| 924 | Separate prerequisite commit `693d038` sends CONNECTION_CLOSE before quiet | 925 | Separate prerequisite commit `693d038` sends CONNECTION_CLOSE before quiet |
| @@ -947,8 +948,8 @@ agent-model/counter metadata are in `dist/appearance-slice3/`. | |||
| 947 | defaults → theme → config → CLI precedence, preserving font behavior. | 948 | defaults → theme → config → CLI precedence, preserving font behavior. |
| 948 | - [x] Validate light/dark terminal and chrome pixels, session survival, PTYs, | 949 | - [x] Validate light/dark terminal and chrome pixels, session survival, PTYs, |
| 949 | startup failures and warnings, and final CI/native/NVIDIA gates. | 950 | startup failures and warnings, and final CI/native/NVIDIA gates. |
| 950 | - [ ] Record the user's slice 3 demo acceptance separately from checks. | 951 | - [x] Recorded slice 3 demo approval on 2026-09-06, separately from checks. |
| 951 | - [ ] Discuss ligature scope and acceptance with the user before implementation. | 952 | - [x] Recorded the user’s decision to defer ligatures and review GUI/TUI parity. |
| 952 | - [ ] Retain the earlier NVIDIA frame-budget and offscreen growth observations | 953 | - [ ] Retain the earlier NVIDIA frame-budget and offscreen growth observations |
| 953 | for a renderer follow-up; this sprint's passes do not settle those causes. | 954 | for a renderer follow-up; this sprint's passes do not settle those causes. |
| 954 | 955 | ||
| @@ -959,3 +960,64 @@ routes passed verification. Owned browser/compositor fixtures were stopped; only | |||
| 959 | the allowlisted page server remains. The appearance plan records route-specific | 960 | the allowlisted page server remains. The appearance plan records route-specific |
| 960 | teardown. The worktree contains the prerequisite fix and the appearance slice | 961 | teardown. The worktree contains the prerequisite fix and the appearance slice |
| 961 | as separate commits; the original checkout's staged user file remains untouched. | 962 | as separate commits; the original checkout's staged user file remains untouched. |
| 963 | |||
| 964 | |||
| 965 | ## GUI/TUI parity and carry-forward audit — 2026-09-06 | ||
| 966 | |||
| 967 | The user approved appearance slice 3, deferred ligatures, and requested the GUI/TUI | ||
| 968 | gaps and remaining retro items. This is a read-only code/issue audit plus delivery | ||
| 969 | record cleanup, not implementation of the next feature. Historical entries above | ||
| 970 | remain evidence of their original status; this section consolidates the current | ||
| 971 | backlog. Duplicate appearance checkboxes now point to their completed slices. | ||
| 972 | |||
| 973 | ### Functional gaps from git-collab | ||
| 974 | |||
| 975 | | Issue | Current gap and evidence | | ||
| 976 | | --- | --- | | ||
| 977 | | `8b16e26b` mouse/wheel/selection | Missing pane wheel scrollback, terminal app mouse forwarding, drag selection and copy. `src/gui/frame.zig` handles left-button focus/rail drag, with no wheel event or clipboard path. Follow the issue's wheel-first slice, then shared selection and daemon-owned extraction. Paste is a subsequent slice. | | ||
| 978 | | `f3cf5785` SSH askpass | No native prompt UI for passphrases or first-use host-key confirmation. TUI owns the askpass listener/prompt flow; shared askpass support exists. Earlier SSH failure classification did not implement prompts. | | ||
| 979 | | `50ca9ba5` agent forwarding | No GUI `-A` policy or agent relay. Picker targets disable forwarding; functional relay handling remains in the TUI pump. | | ||
| 980 | | `fb4a0ee4` prediction | No native local typing prediction overlay. The predictor remains TUI-local; sharing must preserve the authoritative replica. | | ||
| 981 | | `0b725c82` End session | Partly delivered: pane End, pending identity and shared-holder force confirmation exist. Ending a selected session directly from the picker is absent; discovery currently supports only list/create. Ordinary shell exit retains an exited pane, so reconcile the ticket’s exit-removal wording with that existing UX when scoping the remainder. | | ||
| 982 | | `d61fdc4c` macOS | Native build, launch, integration and release evidence on an actual Mac remain missing. The cross-OS scripts have no native gate; Linux/NVIDIA evidence does not cover this. | | ||
| 983 | | `08ff372f` release/install | Partly delivered: Make installs and bundles both binaries. Fresh-machine dynamic dependency installation, actionable setup instructions and validation remain open. | | ||
| 984 | |||
| 985 | Parent `94ed7dfd` keeps terminal-wall retirement blocked until all seven gates | ||
| 986 | land. The browser retains its own layout. Do not close partly delivered tickets | ||
| 987 | on the strength of their stale descriptions. No git-collab issue content changed. | ||
| 988 | |||
| 989 | Recommended next functional slice: wheel scrolling in the pane under the pointer, | ||
| 990 | including unfocused/off-origin panes and app-mode wheel behavior. Demonstrate | ||
| 991 | three panes, independent scroll positions, return to live output and high-DPI | ||
| 992 | pointer coordinates in the actual GUI. Selection/copy follows separately. The | ||
| 993 | macOS gate can be investigated independently; this recommendation does not waive | ||
| 994 | it or authorize terminal-wall removal. | ||
| 995 | |||
| 996 | ### Remaining retrospective work | ||
| 997 | |||
| 998 | - Renderer/measurement owner, next performance investigation: explain intermittent | ||
| 999 | NVIDIA frame-budget misses, separating preparation/readback from compositor | ||
| 1000 | swap waiting. Later passes do not establish the cause of earlier failures. | ||
| 1001 | - Renderer/fixture owner, next offscreen resizing change: investigate unpainted | ||
| 1002 | `0xaa` readback after surface growth. Real Wayland resizing passes; offscreen | ||
| 1003 | growth remains unproven. | ||
| 1004 | - Painter/test-protocol owner, next change at that boundary: assess extracting | ||
| 1005 | observation hooks from `src/gui/frame.zig`, preserving passive observations. | ||
| 1006 | - Tooling owner, next recorder package: promote the reusable recorder/clip driver, | ||
| 1007 | including PTY registration, explicit compositor addresses, isolated XDG paths | ||
| 1008 | and geometry at mapping. The scale gate is already retained in the repository. | ||
| 1009 | - GUI owner, next header-layout change: consider displaying save failure and | ||
| 1010 | pending End together, with save errors still readable in narrow panes. | ||
| 1011 | - Shared client owner, next SSH diagnostic change: preserve unknown/recoverable | ||
| 1012 | handling for unrecognized, localized or truncated diagnostics; current | ||
| 1013 | classification is bounded to supported complete OpenSSH forms. | ||
| 1014 | - Delivery lead: older SSH, interaction-ownership and component-separation | ||
| 1015 | recordings lack separate recorded approvals. These are historical review | ||
| 1016 | bookkeeping, not known implementation failures or a new advancement gate. | ||
| 1017 | Appearance slices 1–3 and the chord changes are approved. | ||
| 1018 | |||
| 1019 | Assign concrete owners when work is selected, using the existing component | ||
| 1020 | briefs. Shared wire/lifecycle review, NVIDIA validation and private webpage/video | ||
| 1021 | handoffs remain standing practices, not separate unfinished features. Ligatures, | ||
| 1022 | font fallback, tabs and pane rearrangement remain outside the delivered scope; | ||
| 1023 | hot reload is intentionally excluded. | ||
docs/demos/native-appearance-slice3.html
| Old | New | ||
|---|---|---|---|
| @@ -23,7 +23,7 @@ | |||
| 23 | <div class="eyebrow">muxg · native appearance · slice 3</div> | 23 | <div class="eyebrow">muxg · native appearance · slice 3</div> |
| 24 | <h1>Your Ghostty themes, in muxg.</h1> | 24 | <h1>Your Ghostty themes, in muxg.</h1> |
| 25 | <p class="lede">Choose a theme file, add your own color overrides, and reopen the client. The saved shells keep running.</p> | 25 | <p class="lede">Choose a theme file, add your own color overrides, and reopen the client. The saved shells keep running.</p> |
| 26 | <div class="status"><i aria-hidden="true"></i>Validated · demo awaiting your review</div> | 26 | <div class="status"><i aria-hidden="true"></i>Validated · demo approved 6 September 2026</div> |
| 27 | <figure class="video-card"> | 27 | <figure class="video-card"> |
| 28 | <video controls playsinline preload="metadata" poster="preview.png" width="1100" height="700" aria-label="Ghostty themes in the actual muxg application"> | 28 | <video controls playsinline preload="metadata" poster="preview.png" width="1100" height="700" aria-label="Ghostty themes in the actual muxg application"> |
| 29 | <source src="demo.mp4" type="video/mp4">Your browser cannot play this video. <a href="demo.mp4">Download the recording</a>. | 29 | <source src="demo.mp4" type="video/mp4">Your browser cannot play this video. <a href="demo.mp4">Download the recording</a>. |
| @@ -53,7 +53,7 @@ background = #202030</code></pre> | |||
| 53 | <p>Unsupported theme keys produce a file/line warning and are ignored. The imported files include cursor-text and text-selection colors, which mux does not implement. Unknown keys in mux’s own config, malformed supported colors, duplicate entries, and missing theme files prevent startup with a diagnostic. Theme files do not change fonts or load other files.</p> | 53 | <p>Unsupported theme keys produce a file/line warning and are ignored. The imported files include cursor-text and text-selection colors, which mux does not implement. Unknown keys in mux’s own config, malformed supported colors, duplicate entries, and missing theme files prevent startup with a diagnostic. Theme files do not change fonts or load other files.</p> |
| 54 | <p>No hot reload, automatic light/dark switching, named X11 colors, or dynamic color expressions. <a href="https://ghostty.org/docs/config/reference">Ghostty’s full format</a> supports more than this subset.</p> | 54 | <p>No hot reload, automatic light/dark switching, named X11 colors, or dynamic color expressions. <a href="https://ghostty.org/docs/config/reference">Ghostty’s full format</a> supports more than this subset.</p> |
| 55 | </section> | 55 | </section> |
| 56 | <section><h2>What to review</h2><div class="review"><p>Check readability of the light and dark headers and menus, the color override, and the startup diagnostic. Prefix <strong>Ctrl+\</strong> then <strong>Enter</strong> opens the host picker; <strong>Esc</strong> closes it. After this slice’s review, we’ll discuss whether and how to tackle ligatures.</p></div></section> | 56 | <section><h2>What to review</h2><div class="review"><p>Check readability of the light and dark headers and menus, the color override, and the startup diagnostic. Prefix <strong>Ctrl+\</strong> then <strong>Enter</strong> opens the host picker; <strong>Esc</strong> closes it. The recorded demo is approved. Ligatures are deferred for now; the next planning focus is the gap between the GUI and TUI.</p></div></section> |
| 57 | <section><h2>Validation and limits</h2><p id="validation">Full CI, native units/core, and the full native integration suite passed. Real theme tests verified saved shell identities, kernel PTY sizes, off-origin pixels, light/dark menus, overrides and diagnostics. NVIDIA Wayland scale transitions passed at 200% → 100% → 150% → 200%. Both NVIDIA stress runs passed: final frame p99 17.84 ms with defaults and 17.81 ms with the configured light theme (20 ms limit); sampled input-to-painted upper bounds were 55.4 ms and 70.3 ms (250 ms limit, 5 ms polling). Frame timing includes framebuffer readback and vsync. These are current-build headless results, not a speedup or physical-display claim.</p> | 57 | <section><h2>Validation and limits</h2><p id="validation">Full CI, native units/core, and the full native integration suite passed. Real theme tests verified saved shell identities, kernel PTY sizes, off-origin pixels, light/dark menus, overrides and diagnostics. NVIDIA Wayland scale transitions passed at 200% → 100% → 150% → 200%. Both NVIDIA stress runs passed: final frame p99 17.84 ms with defaults and 17.81 ms with the configured light theme (20 ms limit); sampled input-to-painted upper bounds were 55.4 ms and 70.3 ms (250 ms limit, 5 ms polling). Frame timing includes framebuffer readback and vsync. These are current-build headless results, not a speedup or physical-display claim.</p> |
| 58 | <p>The first CI attempt exposed a QUIC shutdown timeout. A separate prerequisite fix now notifies peers before freeing connections; the focused test and full CI passed afterward. The original failure is retained in the sprint record.</p> | 58 | <p>The first CI attempt exposed a QUIC shutdown timeout. A separate prerequisite fix now notifies peers before freeing connections; the focused test and full CI passed afterward. The original failure is retained in the sprint record.</p> |
| 59 | <p>Earlier intermittent NVIDIA frame-budget misses and an offscreen surface-growth readback issue remain recorded. No physical-display or new macOS validation is claimed.</p></section> | 59 | <p>Earlier intermittent NVIDIA frame-budget misses and an offscreen surface-growth readback issue remain recorded. No physical-display or new macOS validation is claimed.</p></section> |
docs/superpowers/plans/2026-09-05-native-appearance.md
| Old | New | ||
|---|---|---|---|
| @@ -19,10 +19,10 @@ daemon sessions. Terminal CLI and browser appearance are outside this work. | |||
| 19 | appearance when no config exists in the completed feature. Report unsupported | 19 | appearance when no config exists in the completed feature. Report unsupported |
| 20 | appearance keys; document the supported subset. Demonstrate dark and light | 20 | appearance keys; document the supported subset. Demonstrate dark and light |
| 21 | themes and an explicit colour override. | 21 | themes and an explicit colour override. |
| 22 | 4. **Ligatures: discussion pending.** Discuss scope and acceptance with the user | 22 | 4. **Ligatures: deferred.** On 2026-09-06 the user chose to leave ligatures |
| 23 | when reaching this candidate sprint. Existing shaping is per cell; cross-cell | 23 | for now and review GUI/TUI parity instead. Existing shaping is per cell; |
| 24 | ligatures are not implied by font selection. No ligature implementation is | 24 | cross-cell ligatures are not implied by font selection. Revisit scope only |
| 25 | authorized for the active sprint. | 25 | when the user chooses to resume this work. |
| 26 | 26 | ||
| 27 | Each slice ends with validated work and an actual application demo. User demo | 27 | Each slice ends with validated work and an actual application demo. User demo |
| 28 | acceptance is recorded separately from implementation and test results. | 28 | acceptance is recorded separately from implementation and test results. |
| @@ -418,8 +418,9 @@ All required final gates passed. Evidence under `dist/appearance-slice3/`: | |||
| 418 | Timings include readback and vsync; no performance improvement or physical | 418 | Timings include readback and vsync; no performance improvement or physical |
| 419 | display claim is made. Both runs followed CI, other fixtures and recording. | 419 | display claim is made. Both runs followed CI, other fixtures and recording. |
| 420 | 420 | ||
| 421 | Recorded-demo acceptance remains pending. Ligatures are the next discussion, | 421 | The user approved slice 3 on 2026-09-06: “LGTM.” This records demo approval, |
| 422 | not an authorised implementation sprint. The private review page source is | 422 | not a separate hands-on trial. Ligatures are deferred at the user’s request; |
| 423 | the next planning task is the GUI/TUI gap and retrospective audit. The private review page source is | ||
| 423 | `docs/demos/native-appearance-slice3.html`; its staged copy and allowlisted assets | 424 | `docs/demos/native-appearance-slice3.html`; its staged copy and allowlisted assets |
| 424 | are in `dist/appearance-slice3/site/`. Private route and browser verification are | 425 | are in `dist/appearance-slice3/site/`. Private route and browser verification are |
| 425 | recorded below after publication. | 426 | recorded below after publication. |
| @@ -438,4 +439,4 @@ page server remains on `127.0.0.1:18773`; PID is recorded in | |||
| 438 | Teardown removes only this route with | 439 | Teardown removes only this route with |
| 439 | `tailscale serve --https=443 --set-path /appearance-slice3 off`, then stops that | 440 | `tailscale serve --https=443 --set-path /appearance-slice3 off`, then stops that |
| 440 | owned server. Preserve the other review routes. No user desktop outputs or | 441 | owned server. Preserve the other review routes. No user desktop outputs or |
| 441 | installed binaries were changed. Final recorded-demo acceptance is pending. | 442 | installed binaries were changed. The recorded demo was approved on 2026-09-06. |