impress/docs/wardrobe-v2-migration.md

# Wardrobe V2 Migration Status

This document tracks the status of Wardrobe V2, a ground-up rewrite of the outfit editor using Rails + Turbo, replacing the React + GraphQL system embedded from Impress 2020.

## Goal

Replace the complex React outfit editor (`app/javascript/wardrobe-2020/`) with a simpler Rails/Turbo implementation that:
- Eliminates dependency on Impress 2020's GraphQL API
- Uses progressive enhancement (works without JavaScript)
- Leverages Web Components for interactive features
- Reduces frontend complexity and maintenance burden
- Eventually enables full deprecation of the Impress 2020 service

## Current Status

**Wardrobe V2 is in active development** on the `feature/wardrobe-v2` branch. It's accessible at `/wardrobe/v2` but is not yet linked from the main UI.

### What Works

- **Species/color/pose/style selection**: Full picker UI with visual pose thumbnails, availability indicators, canonical fallback, and alt style picker with tabbed UI
- **Item search**: Text search with auto-filtering by pet compatibility, pagination, add/remove items
- **Item display**: Grouped by zone with multi-zone simplification, incompatible items section, NC/NP badges
- **Outfit rendering**: Uses the shared `<outfit-viewer>` web component
- **Progressive enhancement**: Everything works without JS; web components add auto-submit and smoother interactions
- **Smooth navigation**: Idiomorph DOM morphing reuses `<outfit-viewer>` layers across full-page navigations

### Key implementation files

Code lives in `app/controllers/wardrobe_controller.rb`, `app/views/wardrobe/`, `app/helpers/wardrobe_helper.rb`, and `app/assets/{stylesheets,javascripts}/wardrobe/`.

## Technical Approach

**Simplicity over polish**: Unlike many webapps, we value the simplicity of the codebase very highly, even at the expense of an ideal user experience. Start with simple solutions, even if the UX is clunky; then we'll iterate up as needed.

**URL as single source of truth**: All outfit state lives in URL params (`species`, `color`, `pose`, `style`, `objects[]`, `q[...]`). Every interaction is a GET request that generates a new URL. No client-side state management. Browser back/forward work naturally.

**Server-side rendering + Web Components**: All HTML is generated server-side. Lightweight web components (`<species-color-picker>`, `<pose-picker-popover>`, `<tab-panel>`, `<outfit-viewer>`) add interactivity without framework overhead.

**Progressive enhancement**: Submit buttons appear when JS is slow/disabled. Web components enhance forms with auto-submit on change.

## Roadmap

### Phase 1: Core Functionality (MVP)

The goal is a basic usable wardrobe. Species/color/pose selection, item search, and add/remove are already done.

**Outfit Saving/Loading** (critical, not started)
- Save button, editable outfit name, auto-save with indicator
- Route to load saved outfits (`GET /outfits/:id/v2`)
- Owner-only editing, handle unsaved outfits gracefully

**Alt Styles Support** (done)
- `Outfit#visible_layers` handles alt styles
- Picker UI with tabbed Expressions/Styles panels, `style` URL param, visual thumbnails, "Default" option
- Stale style params dropped gracefully when switching species
- Search results auto-filtered by alt style compatibility

### Phase 2: Polish & Parity

Match the quality and usability of Wardrobe 2020 where it matters.

- **Item UX**: Wear/unwear toggle, item info links, zone badges, removal animations, incompatibility tooltips
- **Preview controls**: Download as PNG, copy link, settings (hi-res mode, archive toggle), HTML5 conversion badge
- **Loading & errors**: Spinners, skeleton screens, smooth transitions, error recovery
- **Mobile**: Touch-friendly targets, fix hover-dependent interactions, always-visible controls on touch
- **Accessibility**: ARIA labels, keyboard navigation, semantic headings, skip links, color contrast

### Phase 3: Advanced Features

Feature parity with Wardrobe 2020 where valuable.

- **User features**: Auth integration, closet/ownership/wishlist badges, filter search by owned/wanted
- **Conflict management**: Auto zone conflict resolution, smart item restoration on unwear
- **Pet loading**: "Load my pet" by name, modeling integration
- **Search enhancements**: Inline syntax (`is:nc`, `fits:blue-acara`), advanced filter UI, autocomplete

### Phase 4: Migration & Rollout

- Gradual rollout (staff → beta → default)
- Performance measurement and optimization (Turbo Frames for partial updates?)
- Visual polish and design refinement
- Remove wardrobe-2020 code and update Impress 2020 dependencies doc

### Deferred / Maybe Never

- Support mode features (can keep using old wardrobe)
- Known glitches system (complex, low value)
- Appearance version pinning (niche)
- UC pet support (being phased out)

## Open Questions

- Is the URL-as-state approach sustainable as complexity grows (saving, closet, conflicts)?
- Which Wardrobe 2020 features are actually essential vs. nice-to-have? (Need user feedback)
- How to handle the transition period (maintain both? redirect? feature flag?)

## References

- [Impress 2020 Dependencies](./impress-2020-dependencies.md) - What still depends on the Impress 2020 service
- [Customization Architecture](./customization-architecture.md) - Data model deep dive
- Wardrobe 2020 source: `app/javascript/wardrobe-2020/` (the authoritative reference for feature parity comparisons)