Skip to content

feat(plugins): app and terminal themes in one Theme list, painted safely - #30719

Merged
nwparker merged 6 commits into
mainfrom
nwparker/plugins-v2-4-themes
Oct 28, 2026
Merged

nwparker merged 6 commits into
mainfrom
nwparker/plugins-v2-4-themes

Conversation

@nwparker

@nwparker nwparker commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 16 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​747 $\color{#cf222e}{\Huge{\mathbf{−}}}$​8 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​739
Prod 40 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1260 $\color{#cf222e}{\Huge{\mathbf{−}}}$​69 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​1191

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:

  • 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.
  • Applying colors (src/renderer/src/lib/plugin-theme-tokens.ts, document-theme.ts):
    • 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.
  • Terminal palettes (terminal-theme-selection.ts, terminal-plugin-palettes.ts, plugin-themes.ts):
    • 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: t0-before-no-plugin-themes.png
  • One Theme menu; two plugin themes named "Dusk" show their publishers: t1-theme-list-collision.png
  • "Ember", a theme that sets only background and foreground: muted text, borders and the selected/hovered rows are derived and visible: t2-ember-two-tokens.png
  • Dusk applied through the real menu: t3-dusk-selected.png
  • After "Use its terminal colors", a terminal printing ANSI colors in Dusk's palette: t4-dusk-terminal.png
  • A consent dialog keeps Orca's colors while the app behind it uses a loud pink primary color: t5-consent-under-theme.png
  • Disabling the Dusk plugin restores System, the choice made before picking Dusk: t6-dusk-disabled-restores-system.png

Testing

  • Unit tests:

    • App and terminal theme formats: color-only values, required tokens, derivation (plugin-theme-artifact.test.ts).
    • Theme registries (plugin-theme-registries.test.ts).
    • 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.

Notes

Checklist

  • This PR is small and focused
  • 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

@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from 0db147c to 9fc2023 Compare October 19, 2026 21:41
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from 4bed5ac to e440c51 Compare October 19, 2026 21:41
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from 9fc2023 to f828fed Compare October 21, 2026 06:30
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from e440c51 to c8b1ba8 Compare October 21, 2026 06:31
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from f828fed to dc669ca Compare October 21, 2026 12:22
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from c8b1ba8 to f1b54cb Compare October 21, 2026 12:22
@nwparker
nwparker marked this pull request as ready for review October 21, 2026 12:24
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from dc669ca to c3cce13 Compare October 21, 2026 20:09
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from f1b54cb to 6093e0a Compare October 21, 2026 20:09
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from c3cce13 to b90df10 Compare October 24, 2026 11:43
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from 6093e0a to 91448eb Compare October 24, 2026 11:43
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from b90df10 to f27a26e Compare October 25, 2026 05:23
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch 2 times, most recently from 61dea6d to 9e5eb2a Compare October 26, 2026 12:04
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from f27a26e to 7a56a37 Compare October 26, 2026 12:04
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from 9e5eb2a to 77f45dc Compare October 26, 2026 12:32
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from ea386b5 to dce92a3 Compare October 28, 2026 04:57
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from 77f45dc to 8a969d0 Compare October 28, 2026 04:57
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from dce92a3 to b7a4a3c Compare October 28, 2026 05:29
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch 2 times, most recently from 39d5f46 to 1597ccb Compare October 28, 2026 10:53
@nwparker
nwparker force-pushed the nwparker/plugins-v2-2-approval branch from 00d3122 to 2e3e915 Compare October 28, 2026 20:38
@nwparker
nwparker changed the base branch from nwparker/plugins-v2-2-approval to main October 28, 2026 21:28
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.
@nwparker
nwparker force-pushed the nwparker/plugins-v2-4-themes branch from 1597ccb to 68aa255 Compare October 28, 2026 21:30
@coderabbitai

coderabbitai Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 19 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • 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: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning 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 Passed checks: 4 passed
Check name Status Explanation
Title check Passed 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 Passed 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 Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed 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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The changes since the previous review appear safe to merge.

Summary

Adds plugin app and terminal themes to the existing theme controls, with saved terminal palettes and checks that keep app text readable.

  • Plugin themes can recolor Orca while keeping built-in choices easy to restore.
  • Plugin terminal palettes can color Orca terminals and host color replies.

Reviews (3) · Last reviewed commit: "fix(plugins): reject theme colors the ca..." · Reviewed by Greptile

Comment thread src/renderer/src/main.tsx Resolved
…minal overrides when adopting a theme's terminal colors

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 1

Nitpick comments: 1
src/shared/plugins/plugin-theme-artifact.test.ts: 1

22-35: Trivial · Functional Correctness · Quick win

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.

Suggested fix
-    ['a URL', { base: 'dark', tokens: { '--background': 'url(x)' } }],
-    ['a var() chain', { base: 'dark', tokens: { '--background': 'var(--a)' } }],
-    ['declaration syntax', { base: 'dark', tokens: { '--background': '#000; color: red' } }],
+    ['a URL', { base: 'dark', tokens: { '--background': 'url(x)', '--foreground': '#fff' } }],
+    ['a var() chain', { base: 'dark', tokens: { '--background': 'var(--a)', '--foreground': '#fff' } }],
+    [
+      'declaration syntax',
+      { base: 'dark', tokens: { '--background': '#000; color: red', '--foreground': '#fff' } }
+    ],

Review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 37c7d1d9-032b-40df-acea-d33e6c4874ae
Commits

Reviewing files that changed from the base of the PR and between c66d873 and fc8cf42.

Files selected for processing: 56
  • docs/reference/plugin-themes.md
  • src/main/ipc/plugins.ts
  • src/main/persistence/applying-settings/settings-update.ts
  • src/main/persistence/loading-store/normalize-loaded-global-settings.ts
  • src/main/plugins/plugin-artifact-validation.ts
  • src/main/plugins/plugin-content-pack-registry.ts
  • src/main/plugins/plugin-marketplace-fetch.test.ts
  • src/main/plugins/plugin-marketplace-service.test.ts
  • src/main/plugins/plugin-theme-registries.test.ts
  • src/main/plugins/plugin-theme-registries.ts
  • src/preload/api/plugin-host-api.ts
  • src/preload/api/plugins-bridge.ts
  • src/renderer/src/app-shell/use-document-appearance.test.tsx
  • src/renderer/src/app-shell/use-document-appearance.ts
  • src/renderer/src/components/settings/AppearanceInterfaceSection.tsx
  • src/renderer/src/components/settings/AppearanceThemeControl.test.tsx
  • src/renderer/src/components/settings/AppearanceThemeControl.tsx
  • src/renderer/src/components/settings/PluginMarketplaceBrowser.test.tsx
  • src/renderer/src/components/settings/TerminalThemePicker.tsx
  • src/renderer/src/components/settings/TerminalThemeSections.lifecycle.test.ts
  • src/renderer/src/components/settings/TerminalThemeSections.tsx
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/fr.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/renderer/src/lib/document-theme.test.ts
  • src/renderer/src/lib/document-theme.ts
  • src/renderer/src/lib/plugin-theme-tokens.ts
  • src/renderer/src/lib/terminal-plugin-palettes.test.ts
  • src/renderer/src/lib/terminal-plugin-palettes.ts
  • src/renderer/src/lib/terminal-theme.test.ts
  • src/renderer/src/lib/terminal-theme.ts
  • src/renderer/src/main.tsx
  • src/renderer/src/store/plugin-themes.ts
  • src/shared/default-global-settings.ts
  • src/shared/global-settings-base.ts
  • src/shared/plugin-appearance-settings-types.ts
  • src/shared/plugin-theme-settings.test.ts
  • src/shared/plugin-theme-settings.ts
  • src/shared/plugins/plugin-catalog-release.test.ts
  • src/shared/plugins/plugin-catalog-release.ts
  • src/shared/plugins/plugin-content-pack-contributions.test.ts
  • src/shared/plugins/plugin-content-pack-contributions.ts
  • src/shared/plugins/plugin-manifest-contribution-validation.ts
  • src/shared/plugins/plugin-manifest.ts
  • src/shared/plugins/plugin-marketplace.test.ts
  • src/shared/plugins/plugin-marketplace.ts
  • src/shared/plugins/plugin-terminal-theme-artifact.ts
  • src/shared/plugins/plugin-theme-artifact.test.ts
  • src/shared/plugins/plugin-theme-artifact.ts
  • src/shared/terminal-color-overrides.ts
  • src/shared/terminal-theme-selection.test.ts
  • src/shared/terminal-theme-selection.ts
  • src/shared/wsl-move/wsl-move-storage-dispositions.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

@nwparker
nwparker merged commit 5018241 into main Oct 28, 2026
57 checks passed
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