Let embedders register built-in themes via RegisterBuiltinThemes

[EronWright]

What

Adds styles.RegisterBuiltinThemes(fsys fs.FS) error, which lets an embedder
contribute additional built-in themes from a filesystem (typically an
embed.FS of themes/*.yaml).

Why

Themes are already partial overrides on top of DefaultTheme() — loadBuiltinTheme
and loadThemeFrom both mergeTheme(DefaultTheme(), &override), which is why a
bundled theme YAML only declares the colors it changes. But the built-in set is a
single compile-time //go:embed themes/*.yaml, which a downstream consumer can't
extend.

A downstream CLI/TUI built on cagent wants its own theme(s) to be first-class
without forking. RegisterBuiltinThemes generalizes the bundled-theme source
from one hardcoded embed.FS to a list, so registered themes flow through the
exact list/load/merge pipeline cagent already uses. They are treated like
cagent's own built-ins with no changes to the picker or handlers:

• appear in ListThemeRefs (and the /theme picker),
• resolve via LoadTheme / ApplyThemeRef,
• classify as built-in (IsBuiltinTheme),
• persist as the user's selection.

Registered sources take precedence over the bundled themes, so an embedder can
override a built-in and, in particular, mask default with their own. A
masked default is still a partial override merged onto cagent's pristine
DefaultTheme() base, so it only needs to specify the fields it changes.
DefaultTheme() itself remains the canonical merge base.

Embedder usage

import (
    "embed"

    "github.com/docker/docker-agent/pkg/tui/styles"
)

//go:embed themes/*.yaml
var brandThemes embed.FS

// At startup, before applying any persisted theme:
if err := styles.RegisterBuiltinThemes(brandThemes); err != nil {
    return err
}

themes/brand.yaml is a partial override; unset fields fall back to the default
theme:

# themes/brand.yaml
name: Brand
colors:
  accent: "#FF6A00"
  brand: "#FF6A00"
  background: "#1A0F0A"
# text_primary, success, error, chroma.*, etc. are inherited from the default.

To make the brand theme the launch default, ship it as themes/default.yaml
instead (or in addition) — it masks cagent's default while inheriting everything
it doesn't set.

Notes / semantics

• The source must contain themes/<ref>.yaml (or .yml). An embedder that
  embeds at themes/*.yaml passes its embed.FS directly; otherwise fs.Sub to
  re-root at the themes dir.
• A registered ref that collides with a bundled name overrides it; the bundled
  name is still listed once.
• RegisterBuiltinThemes validates the source eagerly (nil / missing themes
  dir) so problems surface at registration, not at picker time.

Tests

Tests live in theme_test.go (package styles), consistent with the existing
theme tests, and exercise registration through the public functions an embedder
uses, with a small unexported reset for isolation:

• TestRegisterBuiltinThemes_EmbedderFlow — registers from a real embed.FS and
  runs the full register → list → IsBuiltinTheme → ApplyThemeRef loop.
• TestRegisterBuiltinThemes — listed, classified built-in, loads merged onto
  the default (overridden field changes, unset fields inherited).
• TestRegisterBuiltinThemes_MultipleSources — aggregates across more than one
  source; first-registered wins a collision between two registered sources.
• TestRegisterBuiltinThemes_OverridesBuiltin — a registered name overrides the
  bundled theme.
• TestRegisterBuiltinThemes_MasksDefault — masks default, merged onto the
  pristine DefaultTheme() base.
• TestRegisterBuiltinThemes_Errors — nil / missing-themes-dir rejected eagerly.

Full pkg/tui/styles suite passes under -race; go vet and gofmt clean.

[Sayt-0]

Pushed a few fixes (7cad5565):

• Lint: errors.New + require.Error to get CI green (perfsprint / testifylint).
• Docs: the godoc said default is ignored and collisions keep the bundled theme, but registered sources actually take precedence and can mask default (as the PR description and the override/mask tests assert). Rewrote it to match.
• Bug: registration only invalidated the refs-list cache, not the parsed-theme cache. A built-in (or default) loaded before RegisterBuiltinThemes stayed cached, so the override was silently dropped. Added InvalidateThemeCache("") + a regression test.

[EronWright]

Thanks for the collaboration @Sayt-0! Here's a screenshot of a test app built from this branch (incl. your commit), showing an overridden default theme ("Embedded Default") plus an additional theme ("Embedded Extra").

[Sayt-0]

Reviewed the full register/list/load/merge path plus a multi-lens pass (concurrency, consistency, edge cases, tests). The design is clean: generalizing the built-in source from a single embed.FS to a list lets registered themes flow through the exact existing pipeline with no picker/handler changes, and the partial-override-onto-pristine-default semantics are preserved. Build, vet, test -race, and golangci-lint all pass locally; the 7 new tests pass.

Approving. The notes below are minor, non-blocking polish (hardening plus test coverage on documented behaviors); none affect the core feature.

Two candidate concerns were investigated and dismissed:

• registeredThemeFSes() returning the live slice is not a data race: the slice is append-only under lock and readers only range [0,len), so an in-place append writes a disjoint index. A -race stress test (8 writers / 16 readers) is clean. The word "snapshot" in its godoc is slightly loose, nothing more; slices.Clone would be harmless future-proofing.
• Masking default is honored on every real path (LoadTheme, the picker, startup, cancel-preview); the empty/nil fallback divergence is not reachable because the cancel ref always comes from CurrentTheme().Ref, which is never empty.

One additional note on a file not in this diff: ApplyThemeRef (pkg/tui/styles/hooks.go:39-46) falls back to DefaultTheme() (the pristine base) on a LoadTheme error, whereas LoadTheme("default") and the picker resolve an embedder-masked default. The mainline ApplyThemeRef("default") path is correct; only an unresolvable ref reaches the divergence. Optional: fall back through LoadTheme(DefaultThemeRef) so the fallback agrees with the picker.

[Sayt-0]

Registered refs are aggregated here skipping only default and duplicates, but they are not validated. A registered file named themes/user:x.yaml yields ref user:x, which is listed as a built-in, yet IsBuiltinTheme("user:x") returns false and LoadTheme routes it to the user-theme dir (not found). A name containing .. is listed and classified built-in, but LoadTheme rejects it via validateThemeRef. Not a security issue (fs.ReadFile stays rooted), but the listing layer disagrees with the classify/load layer, leaving an unselectable picker entry.

Optional hardening, mirroring the existing default skip: also skip refs where strings.HasPrefix(r, UserThemePrefix) or validateThemeRef(r) != nil, so every listed built-in ref is guaranteed loadable and IsBuiltinTheme agrees with LoadTheme.

[Sayt-0]

readThemeData and readThemeRefsFromFS try .yaml then .yml for registered sources, and .yml is documented as supported on RegisterBuiltinThemes. The existing .yml coverage only exercises the os-based user-dir path (loadThemeFrom / listThemeRefsFrom), not the fs.FS path, so the registered .yml branch is untested. Consider one MapFS case with only themes/foo.yml, asserted via ListThemeRefs and LoadTheme("foo").

[Sayt-0]

The error path for a registered theme with invalid YAML is uncovered: loadBuiltinTheme wraps the unmarshal error and ApplyThemeRef then silently falls back to the default. Consider registering a themes/bad.yaml with malformed YAML and asserting LoadTheme("bad") errors (and is not cached), plus ApplyThemeRef("bad") falls back to the default theme.

[Sayt-0]

These override/mask tests assert LoadTheme behavior but not the listing invariants the PR documents ("each name listed once", "default listed first"). assert.Contains cannot catch a duplicate. Consider asserting refs[0] == DefaultThemeRef and that default and nord each appear exactly once after registering a masking default and an override, so a regression in the dedup (seen[r]) or ordering is caught.