Skip to main content

Companion vNext — Shop/Wardrobe, more base types, cosmetic compatibility

Date: 2026-07-26 Status: Backlog / roadmap (NOT built — captured so it isn't lost). Owner-flagged during the Profile+companion-proxy shell build.

These are future companion enhancements, deliberately out of scope of the current shell-chrome redesign and the shipped My Cosmos build. Each gets its own spec → plan → build when scheduled.

1. Shop vs Wardrobe (clarity split)​

Today the companion "adornments tray" (DsCompanionSheet cosmetics + MyCosmosPage) is a single grid that buys when not owned, equips when owned — the two intents are conflated. Split into two clearer surfaces:

  • Shop — browse the catalog + purchase with Stardust (the buy path; purchaseAdornment).
  • Wardrobe — equip / unequip what you already own (the equip path; equipAdornment).

Architecture fit: presentation-only. The two states already exist — CompanionView.ownedAdornmentIds (derived from companion_ledger purchases) vs Companion.adornments (currently-equipped). No SDK/data change; it's a UI reorganisation of the existing verbs.

2. More base companion types (spaceship, planet, comet, …)​

Expand beyond nebula / star / moon. The CompanionType enum already reserves planet / comet; add spaceship (and others) + their painters + per-type stage-name groups.

Architecture fit: low structural risk. Rendering is a CompanionType → companionBodyPainter(type, stage) seam (packages/design_system/lib/src/graphics/companion/), so each new type = a new CustomPainter + an enum value + a stageNamesFor group + goldens. The DB member_companion.type is already a free text column (post My Cosmos cutover), so no migration is needed to store new type values — only when a type ships.

3. Cosmetic compatibility (some cosmetics don't attach to all companions)​

Certain adornments only make sense on certain companion types (e.g. a "ring" reads on a planet, not on a spaceship). Give each cosmetic a compatible-types set; Shop hides/greys incompatible cosmetics, and Wardrobe only lets you equip a compatible one.

Architecture fit: the ONE piece here that touches the SDK model — CompanionAdornment (in packages/client_sdk/lib/src/models/companion.dart) gains a compatibleTypes: Set<CompanionType> (default = all, so existing four adornments stay universal). Pure model + presentation filtering; no schema change (the catalog is code-defined kCompanionAdornments, not a DB table). The equip path could additionally reject an incompatible equip in the service for defence-in-depth.

Sequencing note​

Natural order when picked up: (2) add types → (3) cosmetic compatibility (needs types to matter) → or independently (1) Shop/Wardrobe split (pure UI, can ship first as the clarity win). All three are additive to the shipped My Cosmos economy + the companion-as-identity shell work; none change the SP-C economy, RLS, or the earn/spend invariants.