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 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`