Catppuccin base fidelity, full bg contract, and review-driven fixes

[hyperb1iss]

🎨 Catppuccin base fidelity, the full bg contract, and review-driven fixes

Closes #2. Branched from main at v0.4.1. Twelve commits, each one revertable on its own; the Catppuccin remap and the contract change are the two that consumers will notice.

💡 What this is

Issue #2 asked two things: why the dark Catppuccin flavors map bg.base to crust when Catppuccin itself calls base the background pane, and why bg.elevated has no constant when every builtin defines it. Both were defects, not design. The naive fix is to swap two lines in three TOML files. What the repo actually needed was to say what the bg.* family means, because the token guide called bg.base the "main background" while three of the four Catppuccin flavors contradicted the fourth, and the contract had silently drifted two tokens and one style behind what every theme ships.

The rest of the branch is what a full-project review turned up alongside: a loader panic on malformed hex, a red clippy gate on current stable, test targets that only compiled with all features on, four confirmed widget bugs, one terminal-adapter mis-map, and a docs site with a broken CI badge, a missing iced page, and several snippets that do not compile.

🤔 Why we need it

Every one of the 39 builtin themes maps bg.base to the deepest neutral in its palette and steps the other bg.* tokens toward the text color. Catppuccin's design goes the other way for secondary panes: base is the editor background, and mantle and crust are the recessed sidebars and status areas. Mocha, Macchiato, and Frappé painted the app canvas with crust, so an Opaline app on a Catppuccin terminal showed #11111b where the user's terminal is #1e1e2e. Latte already had it right (bg.base = base, bg.panel = mantle), which made the dark flavors inconsistent with their own sibling as well as with upstream.

The contract gap was the same shape: bg.elevated, bg.active, and cursor_line exist in all 39 themes, but nothing in opaline::names, the contract test, or the docs mentioned them, so consumers reached for raw strings and could not rely on the tokens existing.

What is deliberately not done here: the other dark families (Tokyo Night, Dracula, Nord, Everforest Dark, Gruvbox) still map bg.base to the upstream sidebar color rather than the iconic editor background. That is the same class of question as #2 and it deserves its own decision rather than a drive-by inside this branch. See follow-ups.

🎯 The invariant

bg.base is the canvas an app paints first. bg.panel is one step away from it in whichever direction the source palette prefers, and bg.highlight, bg.elevated, and bg.active step toward the text color. The contract test now builds its required lists from opaline::names, so a constant cannot exist without being enforced and a token cannot be enforced without having a constant.

🛠️ How it works

1. Catppuccin remap (src/builtins/catppuccin_{mocha,macchiato,frappe}.toml)

Flavor	bg.base	bg.panel	bg.code	bg.highlight
Mocha	#1e1e2e	#181825	#11111b	#313244
Macchiato	#24273a	#1e2030	#181926	#363a4f
Frappé	#303446	#292c3c	#232634	#414559
Latte	#eff1f5	#e6e9ef	#dce0e8	#ccd0da

Only the three bg.base/bg.panel/bg.code lines changed per dark flavor; the surface ladder (highlight, elevated, active, selection) is untouched. The fidelity test catppuccin_flavors_map_base_to_main_background in tests/builtins_tests.rs pins all four flavors by hex.

2. The contract (src/names.rs, tests/builtins_tests.rs)

tokens::BG_ELEVATED, tokens::BG_ACTIVE, and styles::CURSOR_LINE are new. REQUIRED_TOKENS, REQUIRED_STYLES, and REQUIRED_GRADIENTS are now arrays of names:: constants instead of string literals, and contract_sizes_match_documentation asserts 28 / 14 / 5. Every count mention in README, AGENTS.md, CONTRIBUTING.md, and the docs site moved from 26/13 to 28/14, and docs/guide/tokens.md gained the ladder description above plus rows for the two tokens.

3. Loader panic (src/color.rs)

from_hex checked byte length and then sliced by byte index. A 7-byte string with a multibyte character ("#aé000") passed the length check and panicked at a char boundary. Palette values feed straight into this, so a malformed user theme file crashed any app using discovery. Non-ASCII input is now rejected as InvalidHex before any slicing. Tests cover the color path and the loader path.

4. Theme selector (src/widgets/theme_selector.rs)

Five defects, each with a regression test that fails against the previous code:

• Key-release events (Windows, kitty protocol) fired every action twice. KeyEventKind::Release now returns Noop.
• Ctrl, Alt, and Super chords arrived as plain characters and went into the filter, eating Ctrl+C. Those chords now return Noop.
• Enter as the first key returned Select(id) without applying that theme, because the preview only ran on navigation. Enter now calls apply_preview first.
• The sticky section header always rendered the list's first section, so a window scrolled into the light themes read "Dark Themes". Only visible items feed the header state now, and a buffer-render test pins it.
• A heading whose section started exactly at the viewport edge rendered on the last row with nothing beneath it. A heading now needs room for its first item, and a height-sweep test pins that.

5. Everything else

• src/adapters/owo_colors.rs: rapid_blink maps to blink_fast() (SGR 6) instead of collapsing into blink() (SGR 5), matching crossterm and ratatui.
• src/adapters/egui.rs: twelve Stroke::new(1.0, …) literals gained _f32. They tripped the future-incompat float_literal_f32_fallback lint on current stable, which made clippy -- -D warnings exit 101.
• tests/*.rs: gradient, ratatui, and builtin-dependent tests are gated on their features, so cargo test compiles under any feature selection. CI only runs --all-features, which is why this was invisible.
• examples/theme_showcase.rs: the style samples panel rendered eight names no theme defines; it now samples the 14 contract styles and reads the theme count from BUILTIN_COUNT.
• deny.toml: CI's cargo-deny job fails on every branch today because RUSTSEC-2026-0192 (ttf-parser unmaintained) landed in the advisory database after main's last run. It reaches opaline only through egui 0.33 and is a maintenance notice, so it is acknowledged next to the existing time entry with the exit path recorded.
• Docs: README CI badge pointed at ci.yml (the workflow is cicd.yml); the docs.rs feature table listed 6 of 13 features; the iced adapter had no guide page; the ratatui guide imported Stylize where the method lives on Styled; two CircularReference patterns omitted token; the CSS guide showed Catppuccin hex values for Theme::default(); the egui table claimed text.primary drives override_text_color; missing-token fallbacks were described as magenta (they are neutral gray).

🧪 Validation

All receipts against b70c98f.

• cargo fmt --all --check → clean.
• cargo clippy --all-targets --all-features → zero warnings (was 12 on main).
• cargo test --all-features → 220 passed, 0 failed (210 on main; new tests cover the hex panic, the Catppuccin mapping, contract sizes, SGR 5 vs 6, and the five widget fixes).
• cargo test --no-default-features → 66 passed. --features builtin-themes → 83. --features gradients → 90. --features ratatui → 66. All of these failed to compile on main.
• cargo doc --all-features --no-deps → zero warnings.
• cargo deny --all-features check → advisories ok, bans ok, licenses ok, sources ok (advisories failed on main before the ignore entry).
• Falsifier check: with src/widgets/theme_selector.rs reverted to main, the five new selector tests fail and the six existing ones pass.
• An independent verification pass over the branch (62 adversarial from_hex inputs, 7 loader inputs, 2008 selector renders across five filters, eight heights, and full cursor sweeps) reported 0 panics, 0 cells drawn outside the area, and 0 missing cursor markers, and confirmed each new test fails against a copy of main.
• The from_hex panic was reproduced on main (load_from_str with palette value "#aé000" → byte index 3 is not a char boundary) before the fix.

⚠️ The README showcase screenshots for Catppuccin Mocha and Latte are not regenerated; Mocha's canvas is now #1e1e2e rather than #11111b, so the image is one shade off until a rerender.

🔍 What reviewers should focus on

• The Catppuccin decision itself. For the dark flavors, bg.panel now sits darker than bg.base (mantle under base). Kanagawa already ships that way and Latte already did, but it is a visible change for anyone painting panels with bg.panel on a Catppuccin theme.
• render_theme_entries in src/widgets/theme_selector.rs. The skip-before-header reorder is small, but scroll math depends on count_section_headers and the rendered header count staying equal.
• from_hex now returns InvalidHex for non-ASCII input even when the character count is wrong; previously such input either panicked or returned InvalidLength.
• The strongest objection would be a consumer that computed contrast assuming bg.panel is lighter than bg.base. I found none in this repo, git-iris, or hypercolor, but say so if you have one.

📌 Follow-ups (deliberate non-fixes)

• Decide whether Tokyo Night, Dracula, Nord, Everforest Dark, and Gruvbox should map bg.base to their iconic editor background the way Catppuccin now does. Same class as "bg.base" and "bg.panel" swapped for catppuccin themes? #2, wider blast radius.
• ThemeSelectorState has no restore_original() for close paths other than Esc, and no constructor that takes an app-specific theme list. Both are additive API and want a design call.
• Discovery uses the raw file stem as the id while builtins hyphenate, so rose_pine.toml in a user dir does not shadow rose-pine. Normalising the stem is a one-liner but changes ids users may already rely on.
• Theme::gradient_text(gradient, text) and cli_gradient(text, gradient) take the same two &str in opposite order; fixing it is a breaking change.
• OpalineError::MissingSection is never constructed. Removing it and marking the enum #[non_exhaustive] belongs in the next minor.
• Bump egui once a release drops ttf-parser, then remove the RUSTSEC-2026-0192 ignore.
• tests/adapter_tests.rs is gated on ratatui and gradients together, so a ratatui-only build exercises none of the From impl tests. Splitting the gate per test is mechanical.

🤖 Generated with Claude Code

https://claude.ai/code/session_015pQZqxAgTfPCnwGRFcVF2M