[WV2] Add migration plan document

Claude made this, I'm not editing it hardly at all; it's mainly a context dump for itself.
2025-11-03 06:51:43 +00:00 · 2025-11-03 06:51:43 +00:00 · 80db7ad3bf
commit 80db7ad3bf
parent 481fbce6ce
1 changed files with 955 additions and 0 deletions
--- a/docs/wardrobe-v2-migration.md
+++ b/docs/wardrobe-v2-migration.md
@ -0,0 +1,955 @@
+# 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 early prototype/proof-of-concept stage.** It's accessible at `/outfits/new/v2` but is not yet linked from the main UI.
+
+### What's Implemented
+
+#### Core Infrastructure
+
+**Route & Controller** ([outfits_controller.rb:80-115](app/controllers/outfits_controller.rb#L80-L115))
+- `GET /outfits/new/v2` - Main wardrobe endpoint
+- Takes URL params: `species`, `color`, `objects[]` (item IDs)
+- Returns full HTML page (no layout, designed to work standalone)
+- Defaults to Blue Acara if no pet specified
+
+**View Layer** ([new_v2.html.haml](app/views/outfits/new_v2.html.haml))
+- Full-page layout with preview (left) and controls (right)
+- Responsive: stacks vertically on mobile (< 800px)
+- Uses existing `outfit_viewer` partial for rendering
+- Custom CSS in [outfits/new_v2.css](app/assets/stylesheets/outfits/new_v2.css)
+- Minimal JavaScript in [outfits/new_v2.js](app/assets/javascripts/outfits/new_v2.js)
+
+**Pet Selection** ([new_v2.html.haml:31-42](app/views/outfits/new_v2.html.haml#L31-L42))
+- Species/color picker using `<species-color-picker>` web component
+- Floats over preview area (bottom), reveals on hover/focus
+- Progressive enhancement: submit button appears if JS slow/disabled
+- Auto-submits form on change when JS loaded
+- Filters colors to only those compatible with selected species
+- Advanced fallback: if species+color combo doesn't exist, falls back to simple color ([outfits_controller.rb:89-98](app/controllers/outfits_controller.rb#L89-L98))
+
+**Item Display** ([new_v2.html.haml:47-64](app/views/outfits/new_v2.html.haml#L47-L64))
+- Groups worn items by zone (Hat, Jacket, Wings, etc.)
+- Smart multi-zone simplification: hides redundant single-item zones
+- Shows items that occupy multiple zones in conflict zones only
+- Handles zone label disambiguation (adds IDs when duplicates exist)
+- Separates incompatible items (wrong body_id) into "Incompatible" section
+- Displays item thumbnails, names, and badges (NC/NP, first seen date)
+- Alphabetical sorting within zones
+
+**Item Removal** ([new_v2.html.haml:62-64](app/views/outfits/new_v2.html.haml#L62-L64))
+- Remove button (❌) on each item
+- Removes item from outfit via GET request with updated `objects[]` params
+- Button hidden by default, appears on hover/focus
+- Uses `outfit.without_item(item)` helper to generate new state
+
+**State Management** ([outfits_helper.rb:68-84](app/helpers/outfits_helper.rb#L68-L84))
+- All state lives in URL params (no client-side state)
+- `outfit_state_params` helper generates hidden fields
+- Preserves: species, color, worn items (`objects[]`)
+- Can exclude specific params (e.g., to override in species/color form)
+- Every action generates new URL via GET request
+
+#### Supporting Helpers
+
+**`outfit_items_by_zone`** ([outfits_helper.rb:96-167](app/helpers/outfits_helper.rb#L96-L167))
+- Core grouping logic for items by zone
+- Matches wardrobe-2020's `getZonesAndItems` behavior
+- Returns array of `{zone_id:, zone_label:, items:}` hashes
+- Extensively tested in [outfits_helper_spec.rb](spec/helpers/outfits_helper_spec.rb)
+
+**`outfit_viewer`** ([outfits_helper.rb:86-89](app/helpers/outfits_helper.rb#L86-L89))
+- Renders `<outfit-viewer>` web component
+- Displays pet + item layers using HTML5 Canvas/iframes
+- Reused from existing codebase (also used on item pages, alt style pages, etc.)
+
+**Web Components**
+- `<species-color-picker>` - Auto-submit form on change ([species-color-picker.js](app/assets/javascripts/species-color-picker.js))
+- `<outfit-viewer>` - Pet/item layer rendering ([outfit-viewer.js](app/assets/javascripts/outfit-viewer.js))
+- `<outfit-layer>` - Individual layer loading/error states
+
+#### Model Support
+
+**`Outfit#without_item`** ([outfit.rb:296-298](app/models/outfit.rb#L296-L298))
+- Creates a duplicate outfit without the specified item
+- Used for remove button state generation
+
+**`Outfit#visible_layers`** ([outfit.rb:172-192](app/models/outfit.rb#L172-L192))
+- Returns array of `SwfAsset` layers to render
+- Combines pet biology layers + compatible item layers
+- Filters by zone restrictions
+- Note: Doesn't currently handle alt styles (TODO in code)
+
+**`Item.appearances_for`**
+- Batch-loads item appearances for multiple items on a pet type
+- Returns hash of `{item_id => Appearance}` structs
+- Used by `outfit_items_by_zone` to determine compatibility
+
+### What's NOT Implemented Yet
+
+Below is a comprehensive comparison with the full feature set of Wardrobe 2020 (React version).
+
+#### Critical Missing Features
+
+**Item Search & Addition**
+- ❌ No search UI at all
+- ❌ No item browser/results display
+- ❌ No way to add items to outfit
+- ❌ Missing from Wardrobe 2020:
+  - Free text search with autosuggest
+  - Advanced filters (NC/NP/PB, zone, ownership)
+  - Filter chips display
+  - Paginated results (30 per page)
+  - Keyboard navigation in search results (Up/Down arrows, Escape, Enter)
+  - Preloading adjacent pages
+  - NC Styles intelligent hints
+  - Empty state messages
+  - Item restoration logic (restoring previous items when trying on conflicts)
+
+**Outfit Saving/Loading**
+- ❌ No save button
+- ❌ No editable outfit name field
+- ❌ No load existing outfit capability
+- ❌ No user authentication integration
+- ❌ Missing from Wardrobe 2020:
+  - Auto-save with debounce
+  - "Saving..." / "Saved" indicator
+  - Version tracking
+  - Navigation blocking for unsaved changes
+  - Owner-only editing restrictions
+  - Outfit menu (Edit a Copy, Rename, Delete)
+  - Shopping list link (Items Sources page)
+
+**Pose/Emotion Selection**
+- ✅ Has: Species and color pickers
+- ❌ No pose picker UI
+- ❌ Locked to canonical pose for pet type
+- ❌ Missing from Wardrobe 2020:
+  - Tabbed interface (Expressions tab, Styles tab)
+  - Expression grid (3×2 matrix: Happy/Sad/Sick × Masc/Fem)
+  - Visual pose preview thumbnails
+  - Unconverted (UC) pose option with warning
+  - Pose availability indicators (grayed out with "?")
+  - Auto-recovery when pose becomes invalid
+  - Alt Styles/Pet Styles picker (Styles tab)
+  - "Default" option to return to normal appearance
+  - Visual thumbnails for each alt style
+  - Link to Rainbow Pool Styles info
+
+**Pet Loading**
+- ❌ No "load my pet" feature (pet name lookup)
+- ❌ Can only use species/color pickers
+- ❌ No modeling integration
+
+**Preview Controls**
+- ✅ Has: Basic outfit viewer rendering
+- ❌ No overlay controls
+- ❌ Missing from Wardrobe 2020:
+  - Back button (to homepage/Your Outfits)
+  - Play/Pause animation button (with localStorage persistence)
+  - Download outfit as PNG (with pre-generation on hover)
+  - Copy link to clipboard (with "Copied!" confirmation)
+  - Settings popover:
+    - Hi-res mode toggle (SVG vs PNG)
+    - Use DTI's image archive toggle
+  - HTML5 conversion badge (green checkmark / warnings)
+  - Known glitches badge (lists specific issues)
+  - Right-click context menu (Download, Layers info modal)
+  - Auto-hide controls on desktop, always visible on touch
+  - Focus lock on touch devices
+
+**Advanced Item Features**
+- ✅ Has: Item badges (NC/NP, first seen)
+- ✅ Has: Remove item button
+- ❌ Missing from Wardrobe 2020:
+  - Wear/unwear toggle (click to toggle, radio button behavior)
+  - Item info button (opens item page in new tab)
+  - "You own this" badge (for logged-in users)
+  - "You want this" badge (for logged-in users)
+  - Zone badges (shows occupied zones on item)
+  - Restricted zone badges
+  - Incompatible items tooltip (explains why item doesn't fit)
+  - Alt Style incompatibility indicators
+  - Smooth animations (fade out and collapse on removal)
+
+**User Features**
+- ❌ No user authentication
+- ❌ No closet integration
+- ❌ No ownership tracking
+- ❌ No wishlist tracking
+- ❌ Can't filter search by owned/wanted items
+
+**URL State**
+- ✅ Has: Basic state (species, color, items)
+- ❌ Missing parameters:
+  - `name` - Outfit name
+  - `pose` - Pose string (e.g., HAPPY_FEM)
+  - `style` - Alt Style ID
+  - `state` - Appearance ID (pose version pinning)
+  - `closet[]` - Closeted items array
+- ❌ No browser back/forward support (full page reloads)
+- ❌ No legacy URL format support (#params)
+
+#### UI/UX Gaps
+
+**Visual Polish**
+- Basic styling, needs design refinement
+- No loading spinners with configurable delay
+- No skeleton screens
+- No smooth transitions (fade in/out as layers load)
+- No error boundaries
+- No toast notifications
+- Species/color picker styling is functional but basic
+- No dark mode support
+
+**Accessibility**
+- ❌ Missing from Wardrobe 2020:
+  - ARIA labels on all interactive elements
+  - VisuallyHidden screen reader helpers
+  - Semantic heading hierarchy
+  - Landmark regions
+  - Skip links between sections
+  - High color contrast
+  - Comprehensive keyboard shortcuts
+
+**Performance**
+- ❌ No optimistic updates (every change is full page navigation)
+- ❌ Could benefit from Turbo Frames for partial updates
+- ❌ No prefetching/preloading
+- ❌ Missing from Wardrobe 2020:
+  - React.memo optimizations
+  - Object caching to prevent re-renders
+  - GraphQL query caching
+  - Image preloading
+  - LRU caches for expensive computations
+  - Low FPS detection and auto-pause
+  - Network error recovery
+  - Incremental loading
+  - Non-blocking loading overlays
+
+**Mobile Experience**
+- ✅ Has: Basic responsive layout (stacks vertically)
+- ❌ Touch interactions not optimized
+- ❌ Species/color picker hover state doesn't work well on touch
+- ❌ Missing from Wardrobe 2020:
+  - Large touch targets
+  - Always-visible action buttons on touch devices
+  - Adapted control layouts for small screens
+  - No hover-only interactions
+
+#### Advanced Features Not Implemented
+
+**Conflict Detection & Resolution**
+- ❌ No automatic zone conflict resolution
+- ❌ No smart item restoration when unwearing
+- ❌ No closet panel for conflicted items
+- ❌ Current: Remove item just removes it (can't restore)
+
+**Special Cases**
+- ❌ No known glitch detection system
+- ❌ No special handling for:
+  - Unconverted (UC) pets
+  - Invisible pets
+  - Dyeworks items
+  - Baby Body Paint warnings
+  - Faerie Uni dithering horn
+  - Body ID mismatches
+- ❌ No glitch badges or warnings
+
+**Appearance Customization**
+- ❌ No pose locking (pinning to specific appearance version)
+- ❌ No manual appearance ID selection
+- ❌ No layer visibility controls
+- ❌ No zone restriction customization
+
+**Data Management**
+- ❌ No modeling integration
+- ❌ No contribution tracking
+- ❌ No appearance version history
+
+#### Support/Admin Features (Not Needed for MVP)
+
+**Support Mode** (for staff users only):
+- ❌ Item Support Drawer
+- ❌ Appearance Layer Support Modal
+- ❌ Pose Picker Support Mode
+- ❌ All Item Layers Support Modal
+- ❌ Debug features (appearance IDs, "Maybe Animated" badge)
+- Note: These are staff-only and not required for general migration
+
+## Technical Approach
+
+### State Management Philosophy
+
+**URL as Single Source of Truth**
+- All outfit state encoded in URL params
+- No JavaScript state management
+- Every interaction generates a new URL via GET
+- Browser back/forward work naturally
+- Easy to bookmark/share
+
+**Progressive Enhancement**
+- Works without JavaScript (submit buttons, full page loads)
+- Web Components enhance with auto-submit, hover effects
+- Graceful degradation at every layer
+
+### Rendering Strategy
+
+**Server-Side Rendering**
+- All HTML generated server-side
+- No client-side templates
+- Uses existing Rails helpers and partials
+- Fast initial load, good for SEO
+
+**Web Components for Interactivity**
+- Lightweight custom elements for specific behaviors
+- No framework overhead
+- Easy to understand and maintain
+- Examples: `<species-color-picker>`, `<outfit-viewer>`
+
+### Data Flow
+
+```
+User Action (click/submit)
+  ↓
+GET request with updated params
+  ↓
+Controller builds Outfit model
+  ↓
+Preloads all necessary data (SwfAssets, manifests)
+  ↓
+Renders full HTML with outfit_viewer
+  ↓
+Browser displays (instant if Turbo, full page otherwise)
+```
+
+### Testing Strategy
+
+**Helper specs** cover core logic:
+- `outfit_items_by_zone` - extensively tested for all edge cases
+- Multi-zone simplification
+- Zone label disambiguation
+- Incompatible item handling
+- Sorting behavior
+
+**Missing test coverage:**
+- Controller specs
+- Integration/system specs
+- JavaScript web component tests
+
+## Migration Challenges
+
+### Data Model Gaps
+
+**Current Issues:**
+- Alt style support not implemented in `visible_layers`
+- Outfit model designed around saved outfits (has `user_id`, `name`)
+- Need to handle unsaved/anonymous outfits better
+
+### Performance Concerns
+
+**Full Page Loads**
+- Every species/color/item change triggers new page load
+- Could use Turbo Frames to update only changed sections
+- Need to measure actual performance impact
+
+**Asset Preloading**
+- Currently preloads all visible layer manifests ([outfits_controller.rb:112](app/controllers/outfits_controller.rb#L112))
+- Good for parallelization, but loads data that might not be needed
+- Could be more selective
+
+### User Experience Parity
+
+**Wardrobe 2020 Features to Match:**
+- Real-time search with instant results
+- Drag-and-drop item management
+- Visual zone conflict indicators
+- Item info popovers
+- "Try on all these items" bulk add
+- Sharing outfits with generated images
+
+### Migration Path Unknowns
+
+**Big Questions:**
+1. Can we achieve acceptable UX without heavy JavaScript?
+2. Is Turbo sufficient, or do we need more React-like patterns?
+3. How to handle the transition period (two wardrobes)?
+4. What to do with existing saved outfits (data model changes)?
+5. How to migrate user workflows (muscle memory, bookmarks)?
+
+## Next Steps
+
+### Phase 1: Core Functionality (MVP)
+
+**Goal:** Basic usable wardrobe that can compete with essential features.
+
+1. **Item Search & Addition** 🔴 Critical
+   - [ ] Search input field in sidebar
+   - [ ] Basic text search (query Items API)
+   - [ ] Paginated results display (30 per page)
+   - [ ] Checkbox to wear/unwear items
+   - [ ] Add items to outfit via URL params
+   - [ ] Empty state message
+   - Optional enhancements:
+     - [ ] Autosuggest/autocomplete
+     - [ ] Filter chips display
+     - [ ] Advanced filters (NC/NP/PB, zone)
+     - [ ] Keyboard navigation (arrows, escape, enter)
+
+2. **Outfit Saving/Loading** 🔴 Critical
+   - [ ] Editable outfit name field
+   - [ ] Save button (for logged-in users)
+   - [ ] Auto-save on change (with debounce)
+   - [ ] "Saving..." / "Saved" indicator
+   - [ ] Route: `GET /outfits/:id/v2` to load saved outfit
+   - [ ] Owner-only editing enforcement
+   - [ ] Handle unsaved outfits gracefully
+   - Optional enhancements:
+     - [ ] Navigation blocking for unsaved changes
+     - [ ] Outfit menu (Delete, Edit a Copy)
+
+3. **Pose Selection** 🟡 Important
+   - [ ] Pose picker UI (emotion grid)
+   - [ ] Visual pose thumbnails (tiny pet renders)
+   - [ ] Update pet_state via URL params
+   - [ ] Handle missing/invalid poses gracefully
+   - [ ] Add `pose` param to URL state
+   - Optional enhancements:
+     - [ ] Tabbed interface (Expressions / Styles)
+     - [ ] Pose availability indicators (gray out unavailable)
+     - [ ] Auto-recovery when pose becomes invalid
+
+4. **Alt Styles Support** 🟡 Important
+   - [ ] Alt styles picker (Styles tab in pose picker?)
+   - [ ] Visual thumbnails for each style
+   - [ ] Add `style` param to URL state
+   - [ ] Update `Outfit#visible_layers` to handle alt styles
+   - [ ] "Default" option to return to normal
+   - Optional enhancements:
+     - [ ] Link to Rainbow Pool Styles info
+
+### Phase 2: Polish & UX Improvements
+
+**Goal:** Match quality and usability of Wardrobe 2020.
+
+5. **Improved Item Display**
+   - [ ] Wear/unwear toggle (click item to toggle)
+   - [ ] Item info button (link to item page)
+   - [ ] Zone badges on items
+   - [ ] Smooth animations on removal (fade + collapse)
+   - [ ] Better incompatible items messaging
+   - [ ] Tooltips explaining incompatibility
+
+6. **Preview Controls**
+   - [ ] Overlay controls (auto-hide on desktop, always visible on touch)
+   - [ ] Play/Pause animation button
+   - [ ] Download outfit as PNG
+   - [ ] Copy link to clipboard (with confirmation)
+   - [ ] Settings dropdown (hi-res mode, use archive)
+   - [ ] HTML5 conversion badge
+   - Optional:
+     - [ ] Known glitches badge
+     - [ ] Right-click context menu
+
+7. **Loading & Error States**
+   - [ ] Loading spinners with delay
+   - [ ] Skeleton screens for items
+   - [ ] Smooth transitions (fade in/out)
+   - [ ] Toast notifications for errors
+   - [ ] Network error recovery
+   - [ ] Graceful degradation
+
+8. **Mobile Optimization**
+   - [ ] Large touch targets
+   - [ ] Always-visible controls on touch devices
+   - [ ] Fix species/color picker on touch (no hover)
+   - [ ] Optimized layout for small screens
+   - [ ] Test swipe gestures
+
+9. **Keyboard Navigation & Accessibility**
+   - [ ] Comprehensive keyboard shortcuts (match Wardrobe 2020)
+   - [ ] ARIA labels on all interactive elements
+   - [ ] Semantic heading hierarchy
+   - [ ] Skip links between sections
+   - [ ] High color contrast
+   - [ ] Screen reader testing
+
+### Phase 3: Advanced Features
+
+**Goal:** Feature parity with Wardrobe 2020 where valuable.
+
+10. **User Features** (if keeping)
+    - [ ] User authentication integration
+    - [ ] Closet integration
+    - [ ] "You own this" badges
+    - [ ] "You want this" badges
+    - [ ] Filter search by owned/wanted items
+    - [ ] Shopping list link (Items Sources page)
+
+11. **Conflict Detection & Management**
+    - [ ] Automatic zone conflict resolution
+    - [ ] Closet panel for conflicted items
+    - [ ] Smart item restoration when unwearing
+    - [ ] Visual conflict indicators
+
+12. **Pet Loading**
+    - [ ] "Load my pet" input field
+    - [ ] Integration with modeling system
+    - [ ] Handle modeling errors gracefully
+    - [ ] Redirect to wardrobe with loaded pet
+
+13. **Search Enhancements** (if needed)
+    - [ ] Advanced search dropdown
+    - [ ] Preload adjacent pages
+    - [ ] NC Styles intelligent hints
+    - [ ] Item restoration logic
+
+14. **URL Enhancements**
+    - [ ] Add missing params (pose, style, state, closet[])
+    - [ ] Browser back/forward support (Turbo handles this?)
+    - [ ] Legacy URL format support (#params)
+    - [ ] Clean URL generation
+
+### Phase 4: Performance & Optimization
+
+**Goal:** Fast, smooth experience comparable to React version.
+
+15. **Performance Improvements**
+    - [ ] Evaluate Turbo Frames for partial updates
+    - [ ] Measure page load times
+    - [ ] Image preloading strategies
+    - [ ] Optimize database queries (N+1, etc.)
+    - [ ] Consider caching strategies
+    - [ ] Monitor real-world performance
+
+16. **Visual Polish**
+    - [ ] Design refinement (match DTI aesthetic)
+    - [ ] Dark mode support
+    - [ ] Smooth animations throughout
+    - [ ] Responsive typography
+    - [ ] Consistent spacing/layout
+
+### Phase 5: Migration & Rollout
+
+**Goal:** Transition users from Wardrobe 2020 to Wardrobe V2.
+
+17. **Migration Preparation**
+    - [ ] Feature flag system (A/B test)
+    - [ ] User feedback collection mechanism
+    - [ ] Performance monitoring
+    - [ ] Bug tracking and triage
+    - [ ] Documentation for users
+
+18. **Gradual Rollout**
+    - [ ] Internal testing (staff only)
+    - [ ] Beta testing (opt-in users)
+    - [ ] Gradual percentage rollout
+    - [ ] Monitor error rates and feedback
+    - [ ] Make default for new users
+    - [ ] Eventually deprecate old wardrobe
+
+19. **Deprecation Cleanup**
+    - [ ] Remove wardrobe-2020 JavaScript code
+    - [ ] Update Impress 2020 dependencies doc
+    - [ ] Remove GraphQL queries (if no longer needed)
+    - [ ] Simplify codebase
+    - [ ] Update documentation
+
+### Deferred / Maybe Never
+
+**Features that may not be worth implementing:**
+
+- ❓ Support mode features (can keep using old wardrobe for this)
+- ❓ Unconverted pet support (being phased out in favor of Alt Styles)
+- ❓ Known glitches system (complex, low value)
+- ❓ Appearance version pinning (niche feature)
+- ❓ Manual appearance ID selection (staff only)
+- ❓ Layer visibility controls (complexity vs value)
+- ❓ Low FPS detection and auto-pause (nice-to-have)
+- ❓ All the React.memo micro-optimizations (Rails is different)
+
+### Success Criteria for Each Phase
+
+**Phase 1 (MVP):**
+- ✅ Can search for and add items
+- ✅ Can remove items
+- ✅ Can change species/color/pose
+- ✅ Can save and load outfits
+- ✅ Can use alt styles
+- ✅ Works without JavaScript (progressive enhancement)
+
+**Phase 2 (Polish):**
+- ✅ Feels responsive and smooth
+- ✅ Works well on mobile
+- ✅ Accessible to keyboard and screen reader users
+- ✅ Handles errors gracefully
+- ✅ Loading states don't feel jarring
+
+**Phase 3 (Advanced):**
+- ✅ Feature parity with Wardrobe 2020 for common workflows
+- ✅ Closet integration works (if keeping)
+- ✅ Conflict resolution feels natural
+- ✅ Pet loading works reliably
+
+**Phase 4 (Performance):**
+- ✅ Page loads in < 1 second
+- ✅ Interactions feel instant (< 100ms perceived)
+- ✅ No janky animations
+- ✅ Works well on slower connections
+
+**Phase 5 (Migration):**
+- ✅ User satisfaction meets or exceeds old wardrobe
+- ✅ Error rates acceptable (< 1% of interactions)
+- ✅ Can safely deprecate old wardrobe
+- ✅ Impress 2020 dependencies reduced/eliminated
+
+## Open Questions
+
+**Architecture Decisions:**
+- Should we commit fully to Rails/Turbo, or is some React necessary?
+- Can we get away with just Web Components, or need a framework?
+- Is the URL-as-state approach sustainable as complexity grows?
+
+**Feature Parity:**
+- Which wardrobe-2020 features are actually essential?
+- What can we simplify or eliminate?
+- Are there features users don't use that we can drop?
+
+**Migration Logistics:**
+- Do we maintain both wardrobes during transition?
+- How to handle user preferences (which wardrobe to use)?
+- What's the deprecation timeline for Impress 2020?
+
+**Data Model:**
+- Should Outfit model change to better support unsaved/anonymous outfits?
+- How to handle alt styles in visible_layers?
+- Any schema changes needed?
+
+## Appendix: Wardrobe 2020 Complete Feature Reference
+
+This section documents ALL features in the React-based Wardrobe 2020 for reference during migration.
+
+### UI Layout
+
+**Main Structure:**
+- Split-screen: Preview (left/top) + Items/Search panel (right/bottom)
+- Responsive: Different layouts for mobile vs desktop
+- Search footer (desktop only, behind feature flag)
+
+### Pet Customization
+
+**Species & Color Picker:**
+- Species dropdown
+- Color dropdown
+- Real-time validation (red border for invalid combos)
+- Smart fallback to basic colors
+- Loading states with placeholders
+
+**Pose Picker:**
+- Tabbed interface: "Expressions" and "Styles"
+- Expression tab: 3×2 grid (Happy/Sad/Sick × Masc/Fem)
+- Visual pose preview thumbnails
+- Unconverted (UC) option with warning
+- Pose availability indicators (grayed out + "?")
+- Auto-recovery to valid pose
+- Full keyboard/screen reader support
+
+**Alt Styles (Styles Tab):**
+- Grid of available alt styles for species
+- "Default" option to return to normal
+- Visual thumbnails
+- Link to Rainbow Pool Styles page
+
+### Item Management
+
+**Items Panel:**
+- Editable outfit name (click to rename)
+- Items grouped by zone (Hat, Jacket, etc.)
+- Zone conflict display (multiple items per zone)
+- Zone label deduplication (adds IDs)
+- Incompatible items section with tooltip
+- Per-item actions:
+  - Remove (X icon)
+  - Info (opens item page)
+  - Support drawer (staff only)
+- Wear/unwear toggle (click/space to toggle)
+- Radio button behavior for zone conflicts
+- Keyboard navigation (space, tab)
+- Smooth animations (fade + collapse)
+
+**Item Display:**
+- Thumbnail image
+- Item name
+- Badge system:
+  - NC/NP/PB (item type)
+  - Zone badges (occupied zones)
+  - Restricted zone badges
+  - "You own this" (logged in)
+  - "You want this" (logged in)
+  - "Maybe animated" (support only)
+
+### Search
+
+**Search Toolbar:**
+- Free text input
+- Autosuggest dropdown
+- Advanced search dropdown (chevron)
+- Active filter chips
+- Clear button (X)
+
+**Search Filters:**
+- Item type: NC, NP, PB
+- Zone filter (by body zone)
+- Ownership: items you own, items you want (logged in)
+
+**Search Results:**
+- Paginated (30 per page)
+- Pagination toolbar
+- Preloads adjacent pages
+- Visual checkboxes (wear/unwear)
+- Item restoration logic
+- Keyboard navigation:
+  - Arrow Up/Down between results
+  - Arrow Up from first → search box
+  - Escape → search box
+  - Enter to toggle
+- NC Styles intelligent hint
+- Empty state message
+
+### Outfit Preview
+
+**Preview Display:**
+- 600×600px canvas
+- Layered rendering (proper z-index)
+- Loading spinner (with delay)
+- Cached thumbnail placeholder
+- HTML5 Canvas animations
+- SVG hi-res mode (optional)
+- Performance monitoring (auto-pause on low FPS)
+- Error handling (fallback to static)
+- Smooth transitions
+
+**Overlay Controls:**
+- Auto-hide on desktop (hover/focus to show)
+- Always visible on touch devices
+- Focus lock on touch (tap to lock)
+
+**Control Buttons:**
+- Back (to homepage/Your Outfits)
+- Play/Pause (remembers in localStorage)
+- Download PNG (pre-generates on hover)
+- Copy link (shows "Copied!" confirmation)
+- Settings popover:
+  - Hi-res mode toggle
+  - Use DTI's archive toggle
+
+**Info Badges:**
+- HTML5 conversion status:
+  - Green checkmark (fully converted)
+  - Gray/warning (not converted)
+  - Lists unconverted items
+- Known glitches badge:
+  - Lists specific issues
+  - Covers: UC compat, Dyeworks, Baby Body Paint, Invisible, etc.
+
+**Context Menu (Right-click):**
+- Download option
+- Layers info modal (SWF/PNG/SVG links)
+
+### Outfit Saving
+
+**Save Functionality:**
+- Auto-save (debounced)
+- Save button for new outfits
+- Save indicator (Saving... / Saved / error)
+- Version tracking
+- Navigation blocking (unsaved changes)
+- Owner-only editing
+
+**Outfit Menu:**
+- Edit a copy (new tab)
+- Rename (inline editing)
+- Delete (with confirmation)
+- Shopping list (Items Sources page)
+
+### URL State
+
+**Parameters:**
+- `outfit` - Outfit ID
+- `name` - Outfit name
+- `species` - Species ID
+- `color` - Color ID
+- `pose` - Pose string (HAPPY_FEM, etc.)
+- `style` - Alt Style ID
+- `state` - Appearance ID (version pinning)
+- `objects[]` - Worn item IDs
+- `closet[]` - Closeted item IDs
+
+**Behavior:**
+- Real-time URL updates
+- Browser back/forward support
+- Deep linking
+- Legacy format support (`#params`)
+- Path routing (`/outfits/:id` or `/outfits/new`)
+
+### Keyboard Shortcuts
+
+**Search Panel:**
+- Escape: Clear/close
+- Enter: Accept suggestion
+- Arrow Down (from search): Focus first result
+- Arrow Up/Down: Navigate results
+- Arrow Up (from first): Back to search
+- Backspace (at start): Clear filters
+- Space: Toggle item
+
+**Items Panel:**
+- Space: Toggle wear/unwear
+- Tab: Navigate between items
+
+**Pose Picker:**
+- Tab: Navigate poses
+- Enter/Space: Select
+
+### Accessibility
+
+**Screen Readers:**
+- ARIA labels on all controls
+- VisuallyHidden checkboxes/radios
+- Semantic HTML (headings, landmarks)
+- Landmark regions
+
+**Keyboard:**
+- Full keyboard control
+- Logical focus order
+- Visible focus indicators
+- Skip links
+
+**Visual:**
+- High color contrast
+- Dark mode support
+- Clear focus states
+- Icon + text labels
+
+### Performance
+
+**Optimizations:**
+- React.memo on heavy components
+- Object caching (prevent re-renders)
+- GraphQL query caching
+- Image preloading
+- LRU caches (movie clips, etc.)
+- Pagination preloading
+
+**Error Handling:**
+- Error boundaries
+- Network error recovery
+- Animation fallbacks
+- Low FPS detection + auto-pause
+- Toast notifications
+
+**Loading:**
+- Skeleton screens
+- Delayed spinners
+- Incremental loading
+- Non-blocking overlays
+
+### Mobile/Responsive
+
+- Touch-friendly targets
+- Vertical stacking on mobile
+- Adapted controls for small screens
+- Always-visible buttons on touch
+- No hover-only interactions
+
+### Special Cases
+
+**Known Glitches System:**
+- UC/Invisible compatibility
+- OFFICIAL_SWF_IS_INCORRECT
+- OFFICIAL_MOVIE_IS_INCORRECT
+- OFFICIAL_SVG_IS_INCORRECT (hi-res)
+- DISPLAYS_INCORRECTLY_BUT_CAUSE_UNKNOWN
+- OFFICIAL_BODY_ID_IS_INCORRECT
+- Dyeworks unconverted warnings
+- Baby Body Paint warnings
+- Invisible pet blanket warning
+- Faerie Uni dithering horn
+
+**Special Pet Types:**
+- Unconverted (UC) pets
+- Invisible pets
+- Alt Style pets
+- Dithering pets
+
+### Support/Admin Features
+
+**Support Mode (Staff Only):**
+- Item Support Drawer
+- Appearance Layer Support Modal
+- Pose Picker Support Mode
+- All Item Layers Support Modal
+- Debug info (appearance IDs, localhost)
+- "Maybe Animated" badge
+- Extra logging
+
+### Data Features
+
+**Conflict Detection:**
+- Auto zone conflict resolution
+- Smart item restoration on unwear
+- Zone restriction handling
+
+**Appearance Data:**
+- Body ID compatibility system
+- Alt Style support
+- Pose locking (via appearanceId)
+- Unconverted preservation
+
+**User Data (Logged In):**
+- Ownership tracking
+- Wishlist tracking
+- Closet filtering
+
+## References
+
+**Related Documentation:**
+- [Impress 2020 Dependencies](./impress-2020-dependencies.md) - What still uses the GraphQL API
+- [Customization Architecture](./customization-architecture.md) - Data model deep dive
+
+**Wardrobe V2 Files:**
+- Controller: [app/controllers/outfits_controller.rb](../app/controllers/outfits_controller.rb)
+- View: [app/views/outfits/new_v2.html.haml](../app/views/outfits/new_v2.html.haml)
+- Helpers: [app/helpers/outfits_helper.rb](../app/helpers/outfits_helper.rb)
+- Tests: [spec/helpers/outfits_helper_spec.rb](../spec/helpers/outfits_helper_spec.rb)
+- Styles: [app/assets/stylesheets/outfits/new_v2.css](../app/assets/stylesheets/outfits/new_v2.css)
+- JavaScript: [app/assets/javascripts/outfits/new_v2.js](../app/assets/javascripts/outfits/new_v2.js)
+- Web Components:
+  - [app/assets/javascripts/species-color-picker.js](../app/assets/javascripts/species-color-picker.js)
+  - [app/assets/javascripts/outfit-viewer.js](../app/assets/javascripts/outfit-viewer.js)
+
+**Wardrobe 2020 Files (React):**
+- Main directory: [app/javascript/wardrobe-2020/](../app/javascript/wardrobe-2020/)
+- Main page: [WardrobePage/index.js](../app/javascript/wardrobe-2020/WardrobePage/index.js)
+- State: [useOutfitState.js](../app/javascript/wardrobe-2020/WardrobePage/useOutfitState.js)
+- Search: [SearchToolbar.js](../app/javascript/wardrobe-2020/WardrobePage/SearchToolbar.js)
+- Items: [ItemsPanel.js](../app/javascript/wardrobe-2020/WardrobePage/ItemsPanel.js)
+- Preview: [OutfitPreview.js](../app/javascript/wardrobe-2020/components/OutfitPreview.js)
+
+---
+
+**Document Status:** Living document - update as migration progresses
+**Last Updated:** 2025-11-03
+**Current Branch:** `feature/wardrobe-v2`