You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(plugins): app and terminal themes in one Theme list, painted safely - #30719
Plugins can now change Orca's colors and its terminal colors. Pick a plugin theme from the same Theme menu as System, Dark and Light. One more click applies the same plugin's terminal colors. Trust and approval dialogs keep Orca's own colors whatever theme is active, so a theme can't disguise what you are approving.
What Changed
Before: Orca accepted only built-in themes and user-imported terminal themes. A plugin couldn't contribute either.
After:
One Theme control.
The System / Dark / Light control is unchanged until an enabled plugin offers a theme.
Then Theme becomes one menu: System, Dark, Light, a divider, then plugin themes.
Picking a plugin theme recolors the app at once. A "Use its terminal colors" link applies that plugin's terminal theme.
Two plugin themes with the same name show their publisher, e.g. "Dusk · samples" and "Dusk · acme".
Disabling, removing or deselecting the plugin theme restores the Theme choice you had before (for example System), without a reload.
Terminal themes from plugins appear under "Plugins" in the terminal theme picker, with the plugin's display name.
No flash at startup. The last applied theme is painted before the first render.
Hosts answer correctly. A selected plugin terminal theme gives the right colors on hosts, headless servers and SSH relays before a window opens. Native chat's "match terminal" follows it too.
How it works:
Manifest (src/shared/plugins/plugin-content-pack-contributions.ts, plugin-manifest.ts): two contribution families, themes and terminalThemes. Each entry points at a JSON file of at most 16 KiB.
App theme files (plugin-theme-artifact.ts):
A file sets a light or dark base and colors for a fixed public list of CSS tokens.
--background and --foreground are required. Omitted tokens are derived from the ones set: muted text, borders and hover/selected rows are mixed from the foreground into the background, so a two-color theme still has readable secondary text and visible selection.
Values must be colors. Lengths, calc(), var() and url() are refused.
Each theme file carries a content hash (revision).
The format is documented in docs/reference/plugin-themes.md.
The renderer applies only values the browser itself parses as colors.
Contrast is checked on what will actually be on screen: the plugin's values, with Orca's own value for the theme's light/dark base wherever the plugin is silent.
Any text/surface pair that isn't opaque or is below 4.5:1 is dropped back to Orca's colors. Dropping one value can expose a built-in value that breaks another pair, so the check repeats until nothing changes.
Focus rings must keep 2:1 against their surface, and borders and inputs can't be fully or almost fully transparent, however the color is written (#0000, rgba(…, 0), transparent).
The applied theme is cached, keyed by the plugin theme's id and content hash, and src/renderer/src/main.tsx paints it before first render. The cache is ignored when the theme is no longer selected or the plugin is disabled, so a revoked theme doesn't flash at startup.
Light/dark mode (AppearanceThemeControl.tsx, use-document-appearance.ts): choosing a plugin theme stores its base in the existing theme setting, so every part of Orca that asks "light or dark?" agrees with the painted colors. pluginAppTheme records which plugin theme was chosen, and themeBeforePlugin remembers the earlier choice so it can be restored. If a plugin update changes the base, theme follows it.
Selecting a plugin terminal theme saves a copy of its palette in settings (terminalPluginPalettes).
The shared terminal theme lookup reads that copy, so the main process, headless serve and relays resolve it without the plugin loaded.
The copy is refreshed when the plugin updates the palette.
Settings checked on write (src/shared/plugin-theme-settings.ts): like imported terminal themes, the new settings are sanitized and size-bounded in the main process on every write and load. Uninstalling a plugin clears its app theme (restoring the earlier choice), resets terminal slots that used its palettes, and removes those palette copies.
Loading (src/main/plugins/plugin-theme-registries.ts): both families load through the shared verified artifact-pack registry, reach the renderer over IPC and are re-validated there.
Catalog (plugin-catalog-release.ts, plugin-marketplace.ts): catalog releases can declare app-theme and terminal-theme, and marketplaces stop hiding theme listings.
Trust and approval surfaces keep Orca's own colors through the host-owned security surface from #30710 (merged).
Why
One menu, like familiar editors. A second "Plugin theme" select next to System/Dark/Light was two controls for one choice. It also showed "System" while a dark theme was in force.
Base stored in theme. Updating the ~27 places that read the light/dark setting would have been fragile. Storing the theme's base there keeps every reader correct with no change to them, and older clients and mobile see a valid light or dark value.
Palette copy in settings. The main process, headless serve and relays can't read plugin files when they answer terminal color queries; a renderer-only lookup gave them the wrong colors until a window loaded. Like an imported terminal theme, the copy keeps working if the plugin is turned off.
Validation and contrast checked in the renderer. The browser's own color parser is the only reliable judge of what will actually paint. Checking only the plugin's own pairs was bypassable (a theme could set a light background and white muted text, have the background dropped, and leave black text on Orca's dark background), so the check runs on the final combined set until it is stable.
Restore the earlier Theme choice. Leaving users on Dark after removing a plugin theme they picked over System would silently change their setting.
Linked Issue
None — this is part of the plugin platform rework (maintainer change).
Visual Proof
Screenshots from a hidden dev window (ORCA_BACKGROUND_LAUNCH=1, isolated profile, mock keychain), captured over CDP after rebasing onto current main:
Before, with no plugin themes: the System/Dark/Light control:
One Theme menu; two plugin themes named "Dusk" show their publishers:
"Ember", a theme that sets only background and foreground: muted text, borders and the selected/hovered rows are derived and visible:
Dusk applied through the real menu:
After "Use its terminal colors", a terminal printing ANSI colors in Dusk's palette:
A consent dialog keeps Orca's colors while the app behind it uses a loud pink primary color:
Disabling the Dusk plugin restores System, the choice made before picking Dusk:
Safe token application on the combined set, including the bypass example, built-in context, ring and border transparency, a two-token theme, and the startup cache's id/hash check (document-theme.test.ts).
Settings sanitizing on write and cleanup on uninstall (plugin-theme-settings.test.ts).
Effective appearance, restoring the earlier choice when the plugin goes away (use-document-appearance.test.tsx).
Single Theme control, publisher labels on name collisions, and the one-click terminal colors (AppearanceThemeControl.test.tsx).
Palette copy, refresh and pruning (terminal-plugin-palettes.test.ts).
Host color replies from the saved copy, and fallback for a malformed one (terminal-theme-selection.test.ts).
Picker options with the plugin's name (terminal-theme.test.ts).
Local suites: plugin, shared, git, IPC, persistence, terminal, settings, UI, lib, store, app-shell and preload suites pass (26k tests). Typecheck (tc:node, tc:web), oxlint, check:code-quality:changed and localization coverage are clean.
End-to-end: the plugin e2e specs (demo, marketplace content, panel containment, startup budget) pass locally, run in the background.
Startup paint: measured over CDP after a relaunch. The first React render already had the theme's background and dark mode, with no later change.
Platforms: macOS locally. This draft skips most CI jobs; Linux and Windows aren't covered yet.
I manually tested these changes locally
Automated tests added/updated, or explained why not below
AI Disclosure
Review
Agent skill upstream boundary
Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.
I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
Before/after screenshots or videos attached for UI changes, or N/A with reason
Self-reviewed for correctness, security, and performance
Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred) — targeted suites, tc:node, tc:web, oxlint, the change-quality gate, localization coverage and plugin e2e pass locally; full pnpm lint not run
Manifests can contribute themes (public CSS tokens over a light or dark
base) and terminal themes (an ANSI palette), each at most 16 KiB. App
themes must set --background and --foreground; omitted tokens are derived
from them (surfaces copy the background, muted text, borders and accents
mix the foreground into it), and values must be colors (no keywords,
lengths, calc, var or url). Both load through the shared artifact-pack
registry with the plugin's display name and a content revision, reach the
renderer over IPC and are re-validated there. Catalog releases can declare
app-theme and terminal-theme, and marketplaces stop hiding theme listings.
docs/reference/plugin-themes.md documents the format.
Selecting a plugin terminal theme saves a copy of its palette in settings
(terminalPluginPalettes). The shared lookup reads it, so main, headless
serve and relays answer terminal color queries and native chat matches the
terminal without the plugin loaded; a malformed snapshot falls back to the
default theme.
Appearance keeps the System/Dark/Light control until a plugin offers a
theme; then Theme becomes one list with plugin themes after a divider,
labelled with the publisher when names collide. Choosing one stores its
base in theme and remembers the earlier built-in choice, which comes back
while the plugin is off or after it is uninstalled; a plugin update that
changes the base re-syncs theme. It also offers the plugin's terminal
colors in one click.
The renderer paints only values CSS parses as colors, checks every
text/surface pair, ring and border against the effective set (plugin
values over this mode's built-ins) and repeats until nothing changes, so
dropping one pair cannot expose another. The applied theme is cached with
its id and revision, painted before first render, and dropped as soon as
settings show it no longer applies. Main bounds the new settings on every
write and load, and uninstalling a plugin clears its theme choices and
palette copies. Terminal themes appear under Plugins in the picker with the
plugin's name and are passed to lookups instead of read from a store.
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: cdb03fee-5307-4628-a1fb-33261ee8b601
Commits
Reviewing files that changed from the base of the PR and between fc8cf42 and 6f67936.
Files selected for processing: 1
src/renderer/src/lib/plugin-theme-tokens.ts
Walkthrough
The change adds app and terminal theme contributions to plugin manifests, validates and loads their artifacts, and exposes registrations through IPC. It adds settings fields and normalization for selected plugin themes and saved terminal palettes. The renderer can select and apply plugin app themes, restore cached themes at startup, and include plugin terminal themes in theme options and color lookup. The change also adds theme documentation, translations, and tests.
Priority: Normal
Merge Risk: Low · previous review fc8cf
Malformed cached theme colors can evade a contrast check, though the normal plugin artifact parser rejects those values. This is a bounded risk; the change is mergeable with owner awareness and a fix for the color probe.
Pre-merge checks: 4 · 1
Failed checks: 1 warning
Check name
Status
Explanation
Resolution
Docstring Coverage
Docstring coverage is 42.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…
Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed checks: 4 passed
Check name
Status
Explanation
Title check
The title clearly and concisely describes the main change: adding safely rendered app and terminal themes for plugins in the shared Theme list.
Description check
The description is substantially complete. It includes the required ELI5, change summary, rationale, testing details, visual proof, compatibility notes, security considerations, and checklist status. …
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Description check
Explanation
The description is substantially complete. It includes the required ELI5, change summary, rationale, testing details, visual proof, compatibility notes, security considerations, and checklist status. It also explains that no linked issue is required because this is a maintainer change.
Full details: Docstring Coverage
Explanation
Docstring coverage is 42.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 38 functions across 49 files. (7 skipped: 7 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
Finishing Touches: 💡 1
📝 Generate docstrings: 💡
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Make the invalid-value cases isolate color validation.
The URL, var(), and declaration-syntax cases omit --foreground. The parser can reject them for the missing required token, so these tests do not prove that color validation rejects the values.
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
ELI5
Plugins can now change Orca's colors and its terminal colors. Pick a plugin theme from the same Theme menu as System, Dark and Light. One more click applies the same plugin's terminal colors. Trust and approval dialogs keep Orca's own colors whatever theme is active, so a theme can't disguise what you are approving.
What Changed
Before: Orca accepted only built-in themes and user-imported terminal themes. A plugin couldn't contribute either.
After:
How it works:
src/shared/plugins/plugin-content-pack-contributions.ts,plugin-manifest.ts): two contribution families,themesandterminalThemes. Each entry points at a JSON file of at most 16 KiB.plugin-theme-artifact.ts):baseand colors for a fixed public list of CSS tokens.--backgroundand--foregroundare required. Omitted tokens are derived from the ones set: muted text, borders and hover/selected rows are mixed from the foreground into the background, so a two-color theme still has readable secondary text and visible selection.calc(),var()andurl()are refused.revision).docs/reference/plugin-themes.md.src/renderer/src/lib/plugin-theme-tokens.ts,document-theme.ts):#0000,rgba(…, 0),transparent).src/renderer/src/main.tsxpaints it before first render. The cache is ignored when the theme is no longer selected or the plugin is disabled, so a revoked theme doesn't flash at startup.AppearanceThemeControl.tsx,use-document-appearance.ts): choosing a plugin theme stores itsbasein the existingthemesetting, so every part of Orca that asks "light or dark?" agrees with the painted colors.pluginAppThemerecords which plugin theme was chosen, andthemeBeforePluginremembers the earlier choice so it can be restored. If a plugin update changes the base,themefollows it.terminal-theme-selection.ts,terminal-plugin-palettes.ts,plugin-themes.ts):terminalPluginPalettes).src/shared/plugin-theme-settings.ts): like imported terminal themes, the new settings are sanitized and size-bounded in the main process on every write and load. Uninstalling a plugin clears its app theme (restoring the earlier choice), resets terminal slots that used its palettes, and removes those palette copies.src/main/plugins/plugin-theme-registries.ts): both families load through the shared verified artifact-pack registry, reach the renderer over IPC and are re-validated there.plugin-catalog-release.ts,plugin-marketplace.ts): catalog releases can declareapp-themeandterminal-theme, and marketplaces stop hiding theme listings.Trust and approval surfaces keep Orca's own colors through the host-owned security surface from #30710 (merged).
Why
theme. Updating the ~27 places that read the light/dark setting would have been fragile. Storing the theme's base there keeps every reader correct with no change to them, and older clients and mobile see a valid light or dark value.Linked Issue
None — this is part of the plugin platform rework (maintainer change).
Visual Proof
Screenshots from a hidden dev window (
ORCA_BACKGROUND_LAUNCH=1, isolated profile, mock keychain), captured over CDP after rebasing onto currentmain:Testing
Unit tests:
plugin-theme-artifact.test.ts).plugin-theme-registries.test.ts).document-theme.test.ts).plugin-theme-settings.test.ts).use-document-appearance.test.tsx).AppearanceThemeControl.test.tsx).terminal-plugin-palettes.test.ts).terminal-theme-selection.test.ts).terminal-theme.test.ts).Local suites: plugin, shared, git, IPC, persistence, terminal, settings, UI, lib, store, app-shell and preload suites pass (26k tests). Typecheck (
tc:node,tc:web), oxlint,check:code-quality:changedand localization coverage are clean.End-to-end: the plugin e2e specs (demo, marketplace content, panel containment, startup budget) pass locally, run in the background.
Startup paint: measured over CDP after a relaunch. The first React render already had the theme's background and dark mode, with no later change.
Platforms: macOS locally. This draft skips most CI jobs; Linux and Windows aren't covered yet.
I manually tested these changes locally
Automated tests added/updated, or explained why not below
AI Disclosure
Review
Agent skill upstream boundary
Notes
pluginAppTheme,themeBeforePluginandterminalPluginPalettes, and see a validtheme.plugin:terminal theme falls back to the default where no copy exists.main.Checklist
N/Awith reasonpnpm lint,pnpm typecheck,pnpm test, andpnpm buildpass (or CI will cover; local preferred) — targeted suites,tc:node,tc:web, oxlint, the change-quality gate, localization coverage and plugin e2e pass locally; fullpnpm lintnot run