feat: buddy color progression (species x rarity x XP)

[Ldaco]

Summary

Replaces the single hard-coded MAGENTA sprite color with a three-input gradient driven by (species, rarity, totalXp), so every buddy reads as a distinct, evolving color identity.

• New module src/lib/color.ts — 21 species palettes (84 RGB anchors) + 5 rarity metal tiers (10 anchors), saturation tint, bold weight at Rare+, and a four-tier terminal capability cascade (truecolor / 256-color / 16-color / NO_COLOR).
• Public API: colorFor(species, rarity, totalXp, caps?) returns the appropriate ANSI escape (or empty string for NO_COLOR).
• Integrations:
  • statusline-wrapper.ts normal sprite mode
  • statusline-wrapper.ts bubble sprite mode
  • card.ts renderCard()
  • share.ts renderShareHtml() — Puppeteer/PNG output uses inline rgb() + font-weight: bold for Rare+
• Design: species color is the dominant identity at low levels; from Lv ~30-40 the buddy bridges into the rarity's metal anchor (Common -> Iron, Uncommon -> Copper, Rare -> Gold, Epic -> Diamond, Legendary -> Aurum). Saturation tint per rarity (0.85x for Common up to 1.20x for Legendary) reinforces the tier feel.

Spec: docs/superpowers/specs/2026-05-12-buddy-color-progression-design.md
Plan: docs/superpowers/plans/2026-05-12-buddy-color-progression.md

Test plan

• 79 unit tests in src/__tests__/color.test.ts (every exported function covered)
• 15-fixture snapshot contract in src/__tests__/color-snapshot.test.ts
• Card integration tests in src/__tests__/card-color.test.ts (3 tests)
• Share/HTML integration tests in src/__tests__/share-color.test.ts (7 tests)
• Full suite: 829 pass, 2 pre-existing Penguin failures unrelated to this branch
• Manual verification across capability tiers (NO_COLOR / truecolor / 256-color / 16-color) all produce the expected output paths
• PNG share renders verified visually for 6 species/rarity/level combinations including Data Drake Common Lv 50 -> iron-gray and Legendary Lv 50 -> aurum

Notes

• The 2 pre-existing Penguin sprite test failures (`animation-stability.test.ts`, `species.test.ts`) were present on master before this branch and are unrelated to color work.
• Branch is currently behind origin/master by 12 commits (graph CLI + installer fixes); no expected conflicts (disjoint files), happy to rebase if maintainer prefers.

[Copilot]

Pull request overview

Introduces a new buddy sprite color system that evolves based on (species, rarity, totalXp) and wires it into terminal rendering (statusline + card) and share HTML output.

Changes:

• Added src/lib/color.ts with palette/rarity anchoring, XP-driven interpolation, and terminal capability detection (truecolor/256/16/NO_COLOR).
• Updated statusline wrapper and card rendering to use colorFor(...) instead of a single hard-coded sprite color.
• Updated share HTML rendering to style the sprite placeholder with an inline rgb(...) color and bold weight for Rare+; added unit + snapshot + integration tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/lib/color.ts	New color computation + terminal capability detection + colorFor public API.
src/statusline-wrapper.ts	Uses colorFor for sprite art in normal + bubble modes.
src/lib/card.ts	Wraps sprite art lines in colorFor(...) escape codes.
src/lib/share.ts	Applies computed RGB + bold weight to the share sprite placeholder via inline style.
src/tests/color.test.ts	Unit tests for constants/helpers/capability detection and colorFor.
src/tests/color-snapshot.test.ts	Snapshot fixtures to lock down ANSI escape output.
src/tests/card-color.test.ts	Card integration tests for ANSI color injection.
src/tests/share-color.test.ts	Share HTML integration tests for inline RGB/bold behavior.
src/tests/snapshots/color-snapshot.test.ts.snap	Snapshot outputs for the fixture contract.

Comments suppressed due to low confidence (1)

src/statusline-wrapper.ts:285

• Same issue as bubble mode: buddy.rarity comes from JSON and can be missing/invalid, but it’s passed directly into colorFor(). If rarity is undefined this will throw and break the statusline rendering. Please default/validate rarity before calling colorFor (consistent with the earlier buddy.rarity || 'common' fallback).

        const artWidth = Math.max(...asciiLines.map((l: string) => l.length));
        const spriteColor = colorFor(buddy.species, buddy.rarity, buddy.xp);
        for (let i = 0; i < asciiLines.length; i++) {
          const artPart = `${spriteColor}${(asciiLines[i] || "").padEnd(artWidth)}${RESET}`;
          if (i === 0) {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/statusline-wrapper.ts:286

• Same runtime-safety issue as bubble mode: buddy.rarity || 'common' won’t protect against an invalid-but-truthy rarity string from buddy-status.json. If colorFor() throws here, the statusline wrapper will output nothing. Recommend validating rarity before calling colorFor() and falling back to 'common'/no color for unknown values.

        const artWidth = Math.max(...asciiLines.map((l: string) => l.length));
        const spriteColor = colorFor(buddy.species, buddy.rarity || 'common', buddy.xp ?? 0);
        const spriteReset = spriteColor ? RESET : '';
        for (let i = 0; i < asciiLines.length; i++) {
          const artPart = `${spriteColor}${(asciiLines[i] || "").padEnd(artWidth)}${spriteReset}`;

[Ldaco]

Renamed to artInner in 6cf9891.

[fiorastudio]

I reviewed PR #126 locally with your “impact on existing users” concern in mind. I also kicked off a parallel Codex review, but it timed out before returning, so
this is my direct review only.

Bottom line

• I think feat: buddy color progression (species x rarity x XP) #126 is low-to-moderate risk for existing users.
• It appears to be a presentation-only change: buddy sprite art gets colorized in terminal card output, share snapshots, and the statusline.
• I do not see install, storage, config, migration, or API changes that would break existing users.
• My main concern is terminal compatibility / readability, not data loss or upgrade breakage.

What changes for existing users

• renderCard() now wraps sprite lines with a dynamic ANSI color from colorFor(...) in src/lib/card.ts:43.
• Statusline sprite/bubble art also switches from a fixed magenta to species/rarity/xp-based color in src/statusline-wrapper.ts:167 and src/statusline-
  wrapper.ts:280.
• Share HTML uses computed RGB and font-weight for the sprite in src/lib/share.ts:16 and src/lib/share.ts:201.
• New color system lives in src/lib/color.ts:1.

So existing users should mostly experience:

• same buddy features
• same commands
• same data
• same cards/statusline/share output structure
• different colors

Existing-user impact assessment

• Safe areas
  • No DB schema change
  • No new config requirement
  • No tool/API signature change
  • No installer/uninstaller changes
  • No change to companion state or saved data model
• Risk areas
  • More ANSI escape sequences in card/statusline output
  • Potential rendering oddities in terminals with weak color support
  • Potential snapshot/automation diffs if anyone parses terminal output literally

My main concern

• The PR changes long-standing terminal output from fixed color behavior to computed per-buddy color behavior, but I haven’t yet seen explicit guarantees about
  fallback behavior for:
  • no color
  • ANSI-16 only
  • ANSI-256 only
  • unsupported / quirky terminals
• If colorFor() handles those correctly, risk stays low.
• If it assumes richer color capability too aggressively, existing users could get ugly or inconsistent output rather than broken functionality.

What I’d specifically ask before merge

1. Verify fallback behavior
   • Confirm NO_COLOR still disables sprite color cleanly.
   • Confirm ANSI-16/ANSI-256 fallback is readable and not noisy.
   • Confirm plain terminals don’t get malformed escape spam.
2. Call out user-visible change in PR
   • Existing users will notice a visual change immediately in statusline/card/share.
   • That should be explicit in the PR description.
3. Consider rollout sensitivity
   • If you’re worried about existing-user surprise, this is a good candidate for:
     • a feature flag
     • or at least a conservative fallback path

Merge recommendation

• Probably okay to merge if terminal fallback behavior is solid.
• If you want to be extra careful for current users, request one final check:
  • “Please verify NO_COLOR, ANSI-16, ANSI-256, and truecolor behavior before merge.”

Suggested review comment

• “This looks mostly presentation-only, so I’m not too worried about breaking existing users functionally. My main concern is terminal compatibility/readability,
  since this changes long-standing card/statusline output from fixed colors to computed ANSI colors. Before merge, can we confirm fallback behavior is solid for
  NO_COLOR, ANSI-16, ANSI-256, and truecolor terminals, and call out the visual change explicitly in the PR description?”