Signed-off-by: mbrucedogs <mbrucedogs@gmail.com>

README.md

@@ -15,7 +15,7 @@ A real-time karaoke application designed for in-home party use with multi-user s
 - **Artist Browsing** - Browse songs by artist with modal views
 - **Song Lists** - Predefined song collections with availability matching
 - **Top Played** - Popular songs based on play history
-- **New Songs** - Recently added songs to the catalog
+- **New Songs** - Recently added songs to the catalog (see PRD for implementation details)
 
 ### **Admin Features**
 - **Queue Control** - Reorder and delete queue items

docs/PRD.md

@@ -148,6 +148,19 @@ This document defines the functional, technical, and UX requirements for the Kar
 **Requirements (Platform-Agnostic):**
 - Shows recently added songs from the `newSongs` node
 - Real-time updates and infinite scroll
+- **Data Format Support**: Handles both full song objects and path-only references
+- **Reverse Lookup**: Automatically resolves song paths to full song objects from main catalog
+- **Backward Compatibility**: Works with both old and new data formats
+
+**Implementation Details:**
+- **Format Detection**: Automatically detects whether `newSongs` contains full song objects or path-only references
+- **Reverse Lookup**: When path-only data is detected, performs lookup against main songs catalog
+- **Error Resilience**: Gracefully handles missing songs without breaking the UI
+- **Debug Logging**: Provides detailed logging for troubleshooting missing songs
+
+**Data Formats Supported:**
+1. **New Format**: `{ path: "song_path", key: "firebase_key" }` → Performs reverse lookup
+2. **Old Format**: Full song objects with `artist`, `title`, `path`, etc. → Uses as-is
 
 **Platform Implementation:**
 - **Web:** See `platforms/web/PRD-web.md#new-songs` for React/Ionic implementation

docs/README.md

@@ -1,194 +0,0 @@
-# 📄 Documentation & Reference Models
-
-This `/docs` folder contains **Product Requirements Documents (PRD)**, **data model definitions**, and **Firebase schema references** for the Karaoke App project.
-
-These files are intended for:
-- 📃 Developers reviewing the business logic and architecture.
-- 🤖 AI tools like Cursor or Copilot that reference documentation for context-aware coding.
-- 📝 Project planning, architecture decisions, and future enhancements.
-- 🚀 **Building the app from scratch with any framework/platform combination.**
-
----
-
-## Contents
-
-| File | Purpose |
-|------|---------|
-| `PRD.md` | **Complete Product Requirements Document** — platform-agnostic business logic, technical specifications, data flows, service APIs, component architecture, error handling, and performance optimizations. **Self-guiding for AI implementation.** |
-| `types.ts` | Reference TypeScript interfaces used for modeling app objects. **Not imported into app runtime code.** |
-| `firebase_schema.json` | Example Firebase Realtime Database structure for understanding data relationships and CRUD operations. |
-| `platforms/web/design/` | **Web UI/UX Design Assets** — mockups and visual references for web platform features. |
-
----
-
-## 🚀 How to Use This Documentation
-
-### **For AI-Assisted Development:**
-Simply say **"Read this PRD"** in any new chat. The PRD contains:
-- **Self-guiding instructions** for AI implementation
-- **Complete technical specifications** for 100% accuracy
-- **Implementation questions** to determine platform/framework choices
-- **Step-by-step build process** with checklists
-
-### **For Human Developers:**
-- **Reference during implementation** for business logic and data flows
-- **Guide for architecture decisions** and technology choices
-- **Source of truth** for all functional requirements
-- **Migration guide** when switching frameworks/platforms
-
-### **For New Implementations:**
-1. **Read the PRD completely** - it contains comprehensive specifications
-2. **Review design assets** in `platforms/web/design/` folder for visual reference
-3. **Answer implementation questions** from Section 29
-4. **Follow the implementation checklist** for complete build process
-5. **Preserve business logic** while adapting UI to chosen framework
-
----
-
-## 📋 Key Features of the Updated PRD
-
-### **Platform-Agnostic Design:**
-- **Core business logic** completely separated from implementation details
-- **Firebase architecture** and data models for any platform
-- **Cross-platform references** to platform-specific PRDs
-- **Universal business rules** that apply to all implementations
-
-### **Complete Technical Specifications:**
-- **Firebase data structure** and relationships
-- **Business logic patterns** and validation rules
-- **Real-time synchronization** requirements
-- **User role permissions** and access control
-- **Error handling scenarios** and recovery patterns
-- **Performance requirements** and optimization guidelines
-
-### **Implementation Guide:**
-- **Platform selection questions** to determine technology stack
-- **5-phase implementation checklist** for complete builds
-- **Business logic preservation** guidelines
-- **Critical success factors** for accurate implementations
-
-### **Design Assets:**
-- **Visual mockups** for all major features and screens
-- **Platform-specific designs** (web, mobile, etc.)
-- **UX patterns** and interaction flows
-- **Design system references** for consistent implementation
-
----
-
-## 🔄 Workflow for New Versions
-
-### **When Creating New Implementations:**
-1. **Use the PRD as-is** - it's designed for any framework/platform
-2. **Reference design assets** for visual guidance and UX patterns
-3. **Follow the implementation guide** in Section 29
-4. **Preserve all business logic** while adapting UI layer
-5. **Test against specifications** for 100% accuracy
-
-### **When Updating the PRD:**
-1. **Keep platform-agnostic requirements** intact
-2. **Add new implementation details** to appropriate sections
-3. **Update toolset sections** with new technology choices
-4. **Maintain self-guiding nature** for AI implementation
-
-### **When Migrating Platforms:**
-1. **Keep all business logic** from core requirements
-2. **Replace only implementation details** in platform-specific sections
-3. **Add new platform sections** following the established pattern
-4. **Update toolset rationale** for new technology choices
-
----
-
-## Important Notes
-- ✅ These files are **not intended for direct import or use in application runtime**.
-- ✅ Validation logic and data models here serve as **development references only**.
-- ✅ Any updates to business logic, data flow, or app architecture should be reflected here for documentation purposes.
-- ✅ AI tools may use this information to assist with code generation but will not access `/src` directly.
-- ✅ **The PRD is self-guiding** - it contains all instructions needed for AI implementation.
-- ✅ **100% accuracy achievable** when following the complete specifications.
-
----
-
-## 🎨 Design Assets Reference
-
-### **Current Web Design Assets:**
-Located in `platforms/web/design/` folder with comprehensive mockups for all features:
-
-#### **Core Navigation & Layout:**
-- `00-web-layout.JPG` - Overall web layout structure
-- `01-Login.png` - Login screen design
-- `02-menu.jpeg`, `02a-menu.jpeg`, `02b-menu.png`, `02c-menu.jpeg` - Navigation menu variations
-
-#### **Queue Management:**
-- `02-queue.png` - Main queue view
-- `02-queue-delete.png` - Queue with delete functionality
-- `02-queue-drag.png` - Queue reordering with drag and drop
-- `02-queue-sorting.png` - Queue sorting interface
-
-#### **Search & Discovery:**
-- `04-search.png` - Main search interface
-- `04-search typing .png` - Search with typing interaction
-- `04-search-song info.png` - Search results with song information
-
-#### **User Management:**
-- `05-singers.png` - Singer list view
-- `05-singers add.png` - Singer management interface
-
-#### **Content Browsing:**
-- `06-artists .png` - Artist browse interface
-- `06-artists (not admin).png` - Non-admin artist view
-- `06-artists search.png` - Artist search functionality
-- `06-artists songs.png` - Artist songs list
-
-#### **User Features:**
-- `07-favorites.png` - Favorites management
-- `08-history.png` - Play history view
-- `09-songs list.png` - Main song lists view
-- `09-song lists - songs.png` - Song lists with song details
-- `09- song lists songs expand.png` - Song lists with expandable sections
-
-#### **Admin Features:**
-- `10-Settings.png` - Settings interface
-- `11-top 100.png` - Top played songs
-- `12-favorites .png` - Favorites view
-- `12-favorite lists.png` - Favorite lists management
-
-#### **Menu States:**
-- `03-menu.png` - General menu layout
-- `03-menu current page and non-admin.png` - Navigation with current page indicators
-- `03-menu playing (admin).png` - Admin view during playback
-
-### **Future Platform Design Structure:**
-```
-docs/platforms/
-├── web/
-│   └── design/   # Current web mockups
-├── ios/
-│   └── design/   # Future iOS designs
-├── android/
-│   └── design/   # Future Android designs
-├── tablet/
-│   └── design/   # Future tablet designs
-└── desktop/
-    └── design/   # Future desktop designs
-```
-
-### **Using Design Assets:**
-- **Reference during implementation** for visual accuracy
-- **Understand UX patterns** and interaction flows
-- **Guide UI component design** and layout decisions
-- **Ensure consistency** across different implementations
-- **Validate feature completeness** against visual requirements
-
----
-
-## 🎯 Success Metrics
-- **Zero ambiguity** in technical requirements
-- **Framework independence** for easy migration
-- **Complete implementation path** from start to finish
-- **Consistent results** across different technology stacks
-- **Self-documenting** for future developers and AI tools
-
----
-
-_This documentation is designed to be your **ultimate development tool** - enabling accurate builds with any framework/platform combination._
-

src/redux/selectors.ts

@@ -108,14 +108,50 @@ export const selectFavoritesArrayWithoutDisabled = createSelector(
 );
 
 export const selectNewSongsArray = createSelector(
-  [selectNewSongs],
+  [selectNewSongs, selectSongs],
-  (newSongs) => sortSongsByArtistAndTitle(objectToArray(newSongs))
+  (newSongs, songs) => {
+    // Handle both formats:
+    // 1. Array of objects with only path property (new format)
+    // 2. Array of full song objects (old format)
+    
+    const newSongsArray = objectToArray(newSongs);
+    
+    // Check if the first item has only path and key properties (new format) or is a full song object (old format)
+    if (newSongsArray.length > 0 && 
+        typeof newSongsArray[0] === 'object' && 
+        newSongsArray[0] !== null &&
+        'path' in newSongsArray[0] && 
+        !('artist' in newSongsArray[0]) && 
+        !('title' in newSongsArray[0])) {
+      // New format: array of objects with only path property - do reverse lookup
+      const songPaths = (newSongsArray as { path: string }[]).map(item => item.path);
+      const songsMap = new Map(Object.values(songs as Record<string, Song>).map(song => [song.path, song]));
+      
+      const resolvedSongs = songPaths
+        .map(path => songsMap.get(path))
+        .filter((song): song is Song => song !== undefined);
+      
+      debugLog('selectNewSongsArray - reverse lookup:', {
+        pathsCount: songPaths.length,
+        resolvedCount: resolvedSongs.length,
+        missingPaths: songPaths.filter(path => !songsMap.has(path))
+      });
+      
+      return sortSongsByArtistAndTitle(resolvedSongs);
+    } else {
+      // Old format: array of full song objects
+      return sortSongsByArtistAndTitle(newSongsArray as Song[]);
+    }
+  }
 );
 
 // New songs array without disabled songs
 export const selectNewSongsArrayWithoutDisabled = createSelector(
   [selectNewSongsArray, (_state: RootState, disabledSongPaths: Set<string>) => disabledSongPaths],
-  (newSongs, disabledSongPaths) => newSongs.filter(song => !disabledSongPaths.has(song.path))
+  (newSongs, disabledSongPaths) => {
+    // The selectNewSongsArray already handles the reverse lookup, so we just filter disabled songs
+    return newSongs.filter(song => !disabledSongPaths.has(song.path));
+  }
 );
 
 export const selectSingersArray = createSelector(

src/types/index.ts

@@ -93,7 +93,7 @@ export interface Controller {
   favorites: Record<string, Song>;
   history: Record<string, Song>;
   topPlayed: Record<string, TopPlayed>;
-  newSongs: Record<string, Song>;
+  newSongs: Record<string, Song | { path: string }>; // Can be either Song objects or objects with only path property
   player: {
     queue: Record<string, QueueItem>;
     settings: Settings;