Skip to content

Draft: improve theme customization (upstream #295) - #4

Merged
milan483 merged 4 commits into
mainfrom
feat/issue-295-theme-customization
Nov 11, 2026
Merged

milan483 merged 4 commits into
mainfrom
feat/issue-295-theme-customization

Conversation

@milan483

@milan483 milan483 commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Summary

Planning/handoff PR for upstream Vice #295: improved theme customization, including exact accent/background colors and optional Matugen integration.

Specification: .ai/tasks/vice-295-theme-customization.md

Implementation scope for this PR

  • Preserve five existing Material 3 generated palettes and custom accent behavior.
  • Add a distinct exact-manual theme mode, with independently chosen foreground accent and background, validation, live preview, and durable persistence.
  • Provide monochrome / true-black dark background option with adequate contrast.
  • Preserve boot-cover theming, native app restart behavior, localization and Discord embed accent.
  • Keep Matugen file import/following as a second PR, described in the specification.

Current status

  • Upstream issue and theme architecture researched.
  • Scope and acceptance criteria recorded in the repository.
  • Implementation by Codex.
  • Automated suite, build/typecheck/i18n/parity, and real KDE Wayland UI validation.
  • Codex PR implementation and test report.
  • Independent ChatGPT review.

Base and branch

This branch started from upstream splitshotz/Vice:main (ad7758bf5) for future upstream PR cleanliness. The fork's main is three commits ahead with unrelated GUI-close and session-game-tagging changes; they must not be bundled into the upstream contribution.

Keep draft until implementation, CI, and review are complete. Do not merge/release without explicit approval.

@milan483

milan483 commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author

Implementation and validation report

Validated PR head a3a3d36354a2e5f3e667a110bf1e14ed1f3b15c4. Implementation is in e36215b32a7f4e43391cc3c825d089e6b38d2ce6. The head commit contains the three KDE screenshots in a separate evidence commit. This branch is based on upstream ad7758bf.

  • Appearance and theme roles (ui-src/components/, ui-src/screens/, ui-src/theme/, ui-src/styles/settings.css) add Manual exact and Monochrome / AMOLED dark beside the five presets and Generated Material 3. Manual exact preserves the entered accent and page background, previews derived surfaces, and blocks invalid hex, light backgrounds, and low-contrast pairs. AMOLED uses #ffffff and #000000 with distinct raised and recessed surfaces.
  • Persistence and startup (ui-src/lib/, ui-src/state/store.tsx, ui-src/main.tsx, vice/share.py, vice/ui/index.html) migrate legacy theme storage, keep the last manual colors and generated seed across mode switches, and prepaint the boot cover from daemon-backed UI state. Share embeds use the displayed primary. The five locales and shipped UI bundles were updated.
  • Regression coverage (tests/, tools/accent-parity/, tools/verify-custom-accent.mjs) covers palette contrast, preset parity, grayscale seeds, preference fallback, legacy migration, boot colors, and escaping of saved theme data. The handoff spec received punctuation-only edits for the repository's shipped-text check.

Local validation

Command Result
npm ci Passed
npm run typecheck Passed
npm run build Passed. Vite reported the runtime font references and bundle-size warning.
npm run accents:verify Passed. All 25 roles for each of the five presets matched. The 15 generated probes and new exact-theme, preference, and boot checks passed.
npm run i18n:check Passed. All new keys are translated in the five locales. The checker still reports existing fallback strings.
Focused Python app-state, UI version, accent, parity, and shipped-text tests Passed, 14 tests
python -m unittest discover -s tests Failed, 930 passed, 2 failed, 1 skipped, exit 1. Both failures reproduced on the untouched PR head 7f73ff20.
git diff --check 7f73ff20..HEAD Passed

The two local baseline failures are test_gsr_build_cmd_maps_av1_encoders_to_gsr_codec (local GSR reports no AV1 support and chooses HEVC) and test_sets_default_chromium_flags (the host config enables hardware video decode).

KDE Plasma Wayland

Passed in the native QtWebEngine window against an isolated local server and disposable profile. Tested keyboard focus and Escape, the language selector, invalid hex, black-on-black rejection, reset/cancel/apply, exact white and black, mode switching, legacy migration, and corrupt-state fallback. Preset, Generated Material 3, Manual exact, and AMOLED each survived a fresh native process with browser storage cleared. With the UI bundle blocked, the AMOLED boot cover rendered black and white before React. The saved embed color matched each selected theme, and a public embed HTML fixture emitted the displayed generated accent.

Remaining validation

GTK/WebKit and an actual Discord client unfurl are unverified. GitHub had not reported checks for this head when this comment was posted. PR checks

@milan483 milan483 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review findings

This review records one required P2 correction and one non-blocking P3 UX suggestion.

I rechecked the current head a3a3d36354a2e5f3e667a110bf1e14ed1f3b15c4, the task specification, and Codex's implementation/validation report. GitHub currently reports no check runs and no commit statuses for this head. The local report records successful typecheck, build, accent parity, i18n, and 14 focused tests; the full Python suite had 930 passed, 2 failed, and 1 skipped, with both failures reported as reproducible on the baseline. GTK/WebKit and an actual Discord client unfurl remain unverified.

Please keep this PR in draft. Address the P2 issue and rerun validation before preparing the upstream contribution.

Comment thread vice/ui/index.html Resolved
contrastRatio(base, bg) < 4.5 ||
contrastRatio(base, ramp.surfaceHighest) < 4.5 ||
contrastRatio(base, ramp.onBase) < 4.5
) return {ramp: null, error: 'exactContrast'};

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3 — Non-blocking validation UX suggestion.

All failed accent contrast checks collapse to exactContrast, so the UI can only show one generic message. Consider returning a structured failure identifying the failing role pair (and optionally its measured ratio), then localize/display the relevant correction. This isn't a merge blocker, but it would make the manual editor easier to troubleshoot.

@milan483

milan483 commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author

Implementation and validation report

Addressed the required boot consistency finding in 6f85e9ca1b86410689ea40ed42dffb4a5e256408.

The boot cover and React now share the same preference validation and palette resolver in ui-src/theme/. A parser-blocking prepaint entry loads before the cover markup and derives the colors from the saved seed or exact pair. The old boot cache is ignored and omitted on future saves. The palette generator no longer writes duplicate maps into index.html. Vite builds the additional versioned script at vice/ui/scripts/theme-boot.js (89.65 kB, 21.56 kB gzipped).

Local check Result
npm run accents Passed. Generated preset files were byte-for-byte identical.
npm run typecheck, npm run build, npm run accents:verify, npm run i18n:check Passed. Accent verification includes missing and stale cache regression cases for manual and generated modes.
npm run dev Both assets built in watch mode. The smoke run ended at its timeout.
Focused Python tests 19 passed.
python -m unittest discover -s tests Exit 1. 930 passed, 2 failed, 1 skipped. The same local GSR AV1 and hardware video-decode configuration failures were reproduced on the original PR head.
uv build --wheel Passed. The wheel contains both scripts and the matching HTML.
git diff --check Passed.

Native QtWebEngine on KDE Plasma Wayland passed all four combinations of manual/generated mode and missing/stale cache. Each cover painted the expected palette with the app bundle blocked, then matched the live theme when the bundle was restored. GTK/WebKit remains unverified. The optional contrast-message suggestion remains open.

GitHub had yet to report checks for this head at posting time. PR checks

milan483 commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author

Follow-up review — head 6f85e9ca1b86410689ea40ed42dffb4a5e256408

The P2 boot-theme inconsistency is addressed. I verified that both the prepaint entry and React load the same persisted preference through loadThemePreference() and resolve it through resolveRamp(). The old cached boot colors are no longer trusted; the new tests exercise generated/manual preferences with missing or stale cache data. I've resolved the P2 inline thread.

The P3 contrast-error suggestion remains optional and is not a blocker.

Remaining validation and PR housekeeping

  • GitHub currently reports no workflow runs and no commit statuses for this head. The local validation report is useful, but there is no GitHub CI result to independently confirm yet.
  • The full Python suite still exits non-zero: 930 passed, 2 failed, 1 skipped. The report says both failures reproduce on the original PR head; retain that baseline evidence and do not describe the full suite as passing.
  • GTK/WebKit remains unverified. Native QtWebEngine on KDE Plasma Wayland is the reported manual test.
  • This draft currently targets milan483/Vice:main. That branch has three fork-only commits not present in this feature branch, so GitHub marks this PR dirty (3 commits behind, 4 ahead). Upstream splitshotz/Vice:main is still exactly at the feature branch's stated baseline, ad7758bf55e48b53db0b7e2dce11bedb465b90a3.

Do not merge the fork's three unrelated commits into this feature branch just to clear the current PR conflict. Keep this internal draft as-is. When the implementation is ready for upstream submission, create a separate draft PR against splitshotz/Vice:main using milan483:feat/issue-295-theme-customization as the head. Do not merge either PR without approval.

@milan483

Copy link
Copy Markdown
Owner Author

Fork main integration and installation

At the owner's request, merged the tested theme branch into the fork's latest main as a419d26f0fba4716ce5a9a92fc2122ecd1f1501b. Source files merged cleanly. The generated app JavaScript and CSS were rebuilt to resolve their conflicts.

The combined source passed typecheck, build, accent verification, localization checks, and diff checks. The Python suite ran 979 tests with 974 passes, 3 skips, and the two previously documented local GSR AV1 / hardware video-decode failures.

Installed this exact main build as vice-clipper 2.17.0-1.4. Verified installed Python and UI files against main. The native window is open, replay recording and hotkeys report ready, and the library reports 121 clips. The close-to-tray and session identity source changes are included.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant