From 80db7ad3bf5c4b65ddbbf07d8a3359a923f51a13 Mon Sep 17 00:00:00 2001 From: Emi Matchu Date: Mon, 3 Nov 2025 06:51:43 +0000 Subject: [PATCH] [WV2] Add migration plan document Claude made this, I'm not editing it hardly at all; it's mainly a context dump for itself. --- docs/wardrobe-v2-migration.md | 955 ++++++++++++++++++++++++++++++++++ 1 file changed, 955 insertions(+) create mode 100644 docs/wardrobe-v2-migration.md diff --git a/docs/wardrobe-v2-migration.md b/docs/wardrobe-v2-migration.md new file mode 100644 index 00000000..a9731421 --- /dev/null +++ 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 `` 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 `` 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** +- `` - Auto-submit form on change ([species-color-picker.js](app/assets/javascripts/species-color-picker.js)) +- `` - Pet/item layer rendering ([outfit-viewer.js](app/assets/javascripts/outfit-viewer.js)) +- `` - 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: ``, `` + +### 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`