OpenNeo/impress
OpenNeo/impress
1
0
Fork 1
Code Pull requests Activity
impress/docs/wardrobe-v2-migration.md

33 KiB
Raw Blame History

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)

  • 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)

  • 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
  • Minimal JavaScript in outfits/new_v2.js

Pet Selection (new_v2.html.haml:31-42)

  • 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)

Item Display (new_v2.html.haml:47-64)

  • 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 Search (new_v2.html.haml:47-50)

  • Search form at top of controls section
  • Auto-filters to items that fit current pet (species + color + alt_style)
  • Uses Item::Search::Query.from_params for structured search
  • Toggles between search results and worn items views (full page refresh)
  • Pagination with 30 items per page using q[page] parameter
  • All search state scoped under q[...] params (name, page, etc.)
  • "Back to outfit" button to exit search

Item Addition (_search_results.html.haml)

  • Add button (➕) on each search result item
  • Adds item to outfit via GET request with updated objects[] params
  • Button hidden by default, appears on hover/focus
  • Preserves search state when adding items
  • Uses outfit.with_item(item) helper to generate new state

Item Removal (new_v2.html.haml:70-72)

  • Remove button (❌) on each worn 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-90)

  • All state lives in URL params (no client-side state)
  • outfit_state_params helper generates hidden fields for outfit state
  • Preserves: species, color, worn items (objects[]), search query (q[...])
  • Can exclude specific params via except: (e.g., to override species/color, or clear search)
  • Every action generates new URL via GET request

Supporting Helpers

outfit_items_by_zone (outfits_helper.rb:96-167)

  • 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

outfit_viewer (outfits_helper.rb:86-89)

  • 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)
  • <outfit-viewer> - Pet/item layer rendering (outfit-viewer.js)
  • <outfit-layer> - Individual layer loading/error states

Model Support

Outfit#without_item (outfit.rb:296-298)

  • Creates a duplicate outfit without the specified item
  • Used for remove button state generation

Outfit#with_item (outfit.rb:300-303)

  • Creates a duplicate outfit with the specified item added
  • Used for add button state generation in search results
  • Prevents duplicate items (checks if item already worn)

Outfit#visible_layers (outfit.rb:172-192)

  • 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

Item::Search::Query.from_params (item/search/query.rb)

  • Structured search query builder (vs. from_text which parses strings)
  • Takes indexed hash of filters with key, value, is_positive
  • Supported filters: name, is_nc, is_np, is_pb, fits, occupied_zone_set_name, etc.
  • Used by Wardrobe V2 to auto-filter items by current pet 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

  • ✅ Basic search UI implemented (text search only)
  • ✅ Item results display with pagination (30 per page)
  • ✅ Add items to outfit from search results
  • ✅ Auto-filtering to items that fit current pet
  • ✅ Empty state messages
  • ❌ Still missing from Wardrobe 2020:
    • Inline search syntax (is:nc, fits:blue-acara, etc.) - currently only supports plain text
    • Advanced filter UI (NC/NP/PB toggles, zone selector, ownership filters)
    • Filter chips display showing active filters
    • Autosuggest/autocomplete
    • Keyboard navigation in search results (Up/Down arrows, Escape, Enter)
    • Preloading adjacent pages for faster pagination
    • NC Styles intelligent hints
    • 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)
  • 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

Recently Completed:

  • ✅ Basic item search functionality (November 2025)
    • Text search with auto-filtering by pet compatibility
    • Pagination with 30 items per page
    • Add/remove items with state preservation
    • Clean URL-based state management with all search state scoped under q[...]

Phase 1: Core Functionality (MVP)

Goal: Basic usable wardrobe that can compete with essential features.

  1. Item Search & Addition 🟢 Complete (basic), 🟡 Enhancements pending

    • Search input field in sidebar
    • Basic text search (query Items API)
    • Paginated results display (30 per page)
    • Button to wear items (Add button on search results)
    • Add items to outfit via URL params
    • Empty state message
    • Auto-filter items to current pet compatibility
    • Back to outfit button to exit search
    • Search state scoped under q[...] params
    • Optional enhancements:
      • Inline search syntax (is:nc, fits:blue-acara)
      • Autosuggest/autocomplete
      • Filter chips display
      • Advanced filter UI (NC/NP/PB toggles, zone selector)
      • 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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.

  1. 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)

  2. Conflict Detection & Management

    • Automatic zone conflict resolution
    • Closet panel for conflicted items
    • Smart item restoration when unwearing
    • Visual conflict indicators

  3. Pet Loading

    • "Load my pet" input field
    • Integration with modeling system
    • Handle modeling errors gracefully
    • Redirect to wardrobe with loaded pet

  4. Search Enhancements (if needed)

    • Advanced search dropdown
    • Preload adjacent pages
    • NC Styles intelligent hints
    • Item restoration logic

  5. 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.

  1. 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

  2. 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.

  1. Migration Preparation

    • Feature flag system (A/B test)
    • User feedback collection mechanism
    • Performance monitoring
    • Bug tracking and triage
    • Documentation for users

  2. 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

  3. 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:

Wardrobe V2 Files:

Wardrobe 2020 Files (React):

Document Status: Living document - update as migration progresses Last Updated: 2025-11-03 Current Branch: feature/wardrobe-v2