#14084 Feature: lightweight theme browser with current-directory previews

Summary

Add an interactive theme browser to Oh My Zsh that lets users explore installed themes and preview them in their current directory without changing their active shell or .zshrc.

Keep the implementation in the OMZ repository, dependency-free and loaded only when invoked. Theme creation is explicitly out of scope. This issue is a feature proposal and implementation brief; the rendering approach should be validated before building the full browser.

Motivation

omz theme list lists available themes, but choosing one typically involves browsing screenshots or repeatedly switching themes. Seeing the actual working directory and Git context would make selection more useful.

The existing tools/theme_chooser.sh provides basic previews, but sources successive themes into one process and prints left/right prompts with fixed spacing. It is not an isolated, interactive browser.

Proposed CLI

omz theme browse                 # Browse installed themes
omz theme browse agn             # Start with a theme-name filter
omz theme preview agnoster       # Preview one theme without applying it

These complement the existing omz theme list, omz theme use <theme>, and omz theme set <theme> commands. Add theme-name completion for the new commands where appropriate. Previewing uses the invoking directory by default.

Browser Experience

List bundled and custom themes, respecting normal OMZ resolution precedence and deduplicating selectable names.
Show one preview for the highlighted theme, using the current directory and relevant exported environment.
Filter by typing; render on demand rather than rendering every installed theme upfront.
Show useful errors for failing or unsupported themes; bound preview execution and cancel obsolete work.
After selection, explicitly offer use for this session, save as default, or return to browsing.
Never modify configuration or source preview themes into the parent shell during navigation.

Proposed shortcuts:

Key	Action
Up / Down or Ctrl-P / Ctrl-N	Navigate themes
Page Up / Page Down	Navigate by page
Type text	Filter names
Backspace	Remove a filter character
Ctrl-U	Clear the filter
Enter	Open selection actions
Esc / Ctrl-C	Cancel without changes

No new global aliases or shell keybindings by default.

Technical Direction

Prefer a small zsh implementation with no required Rust binary, fzf, images, fonts, or theme database.
Load browser code only when invoked through omz theme; avoid adding browser initialization to normal shell startup.
Use a fresh zsh worker per preview. Preserve the invoking directory and relevant environment, and load the OMZ helpers required by themes.
Start with isolated static previews and synchronous OMZ Git information. Validate hook initialization, multiline prompts, right prompts, and exit-status rendering before committing to the UI design.
Do not blindly source the full user startup configuration: update checks, cache writes, plugins, and arbitrary startup side effects need consideration.
Handle narrow terminals, resizing, cancellation, interruption, and terminal-state restoration. Handle non-interactive invocation gracefully.
Treat subprocesses as shell-state isolation, not a security sandbox: themes are executable code. Consider terminal-control output as well as shell-state leakage.
Reuse existing theme-selection commands where appropriate. Account for the fact that omz theme use does not tear down hooks, widgets, or other state installed by the previous theme.
Keep browsing, applying for the current session, and persisting/reloading distinct. Any subprocess-to-parent selection handoff should pass validated data, not shell code for eval.

The expected footprint is a small amount of shell source, not bundled megabytes; measure the actual change rather than treating an estimate as an acceptance result.

Implementation Plan

Prove isolated preview rendering against representative themes such as robbyrussell, agnoster, half-life, and dieter. Exercise actual Git context and identify fidelity limitations.
Add omz theme preview with error handling and bounded execution.
Add the lazy-loaded browser, filtering, navigation, and selected-theme preview.
Integrate explicit apply/save actions and safe cancellation.
Add completion, documentation, and focused regression tests. Measure installed footprint and startup impact.
Review acceptance criteria and conduct local interactive testing before opening a draft PR.

Acceptance Criteria

Users can browse bundled and custom themes without installing additional tools.
Previews use the invoking directory and show its Git state where supported.
Previewing and browsing leave the parent shell theme, hooks, keybindings, and configuration unchanged until an explicit apply/save action.
Theme resolution matches normal OMZ loading, including custom overrides.
Filtering and documented keyboard shortcuts work.
Preview failures and slow themes do not crash or indefinitely block the browser.
Cancellation and interruption restore terminal state.
Narrow terminals and resizing are handled gracefully.
Configuration changes require an explicit action.
Browser implementation loads only when invoked.
CLI completion and user documentation cover the new commands.
Focused tests cover resolution, isolation, failure handling, and cancellation where practical.
Added installation footprint, startup impact, and known preview limitations are documented.
Local interactive testing is completed before opening a draft PR.

Out of Scope

Theme creator or visual editor.
Downloading themes or a remote marketplace.
Screenshot galleries, bundled fonts, or a required compiled runtime.
Full terminal emulation or perfect support for arbitrary third-party interactive/async themes.

Questions for the Prototype

Are static previews sufficiently accurate for the initial release?
Should unsupported themes offer a temporary interactive-shell trial?
How much user configuration can be loaded without unwanted startup side effects?
Should the existing tools/theme_chooser.sh be retained, deprecated, or replaced after this ships?

Development Context

A local feat/theme-browser branch/worktree was created from bd77419b; no feature implementation has been made. Implementation and assignment are deferred to a later agent session.