Many improvements

mostly stability, bug fixes, and performance

- [X] A versioning system, linked with `send-beta-build.yml` and the `links.json` but different file, supporting both git commits (for beta/dev stuff) and github latest releases for normal people use
  - maybe this isn't needed (note to self, read *all* of the docs first): <https://vite-pwa-org.netlify.app/frameworks/react.html#react>
  - to migrate?: <https://vite-pwa-org.netlify.app/guide/unregister-service-worker.html#custom-selfdestroying-service-worker>
    - shouldn't clear cache handle this? ¯\_(ツ)_/¯

- [X] Make loading of songs, playlists, etc on load more staggered so that page doesn't freeze
  - Added staggered loading with configurable batch sizes

- [X] Add more to about menu

- [X] Loading a custom iconset tanks performance
  - Stabilized loadIcon reference with useRef pattern to prevent re-creation
  - Added cache key tracking to skip redundant fetches when icon set changes
  - Wrapped Icon component with React.memo to prevent unnecessary re-renders
  - Removed state updates from inside loadIcon callback

- [X] Gapless and crossfade are just broken, they just are
  - Fixed race condition: added crossfadeInitiatedRef guard to prevent multiple triggers from timeupdate
  - Fixed event listener cleanup: track and remove ended handler on cancelCrossfade
  - Fixed handleEnded during crossfade: properly defer to crossfade manager
  - Removed duplicate ended listener from nextAudio element
  - Fixed memory leak: revoke blob URLs after crossfade swap
  - Widened gapless trigger threshold from 50ms to 150ms with setTimeout for precision
  - Added AudioContext resume check before starting crossfade
  - Use crossfadeManager.getActiveElement() to determine current element after swap

- [X] Load all cover art more lazily and delayed for same reason as above
  - Added loading="lazy" and decoding="async" to album art images

- [X] fix drag and drop of songs not triggering sometimes

- [X] Fix share_target so that it supports both importing songs if music files supported by filePickerHelper (as a "polyfill" for file_handlers) and searching/sharing songs if text
  - Share target already supports both files and text/search queries

- [X] Fix sharing so that it just doesn't copy URL
  - Removed URL from share data for both songs and playlists

- [X] Make dragging songs not select song details in song list but also make sure we can select that stuff (prevent conflicts)

- [X] Slide out settings menu on close

- [X] Prevent/recover from Failed to play song so that HTMLPlayer and system don't get unsynced
  - (`The play() request was interrupted by a new load request. https://goo.gl/LdLk22`)

- [X] fix the UI of the 'Repeat Once' button

- [X] Can't move playlist to root unless I have another playlist in root

- [X] Center `Empty folder...`

- [X] Show SYLT first if both USLT and SYLT are available

- [X] fix visualizer missing left padding

- [X] prevent esc from closing lyrics overlay

- [X] In Home, show `1 Song` rather than `1 Songs`

- [X] On mobile, the Persistent Dropdowns are loaded inside the top bar, when they should be overlays

Author: NellowTCS

.gitignore

@@ -137,4 +137,5 @@ dist
 
 .DS_Store
 beta/
-.vscode/
+.vscode/
+dev-dist/

BUGS.md

@@ -4,68 +4,29 @@
   - [ ] Compact mode
   - [ ] Show Lyrics
   - [ ] Show Album Art
-  - [ ] Toggle Lyrics
-  - [ ] Toggle Visualizer
-
-- [ ] Show SYLT first if both USLT and SYLT are available
-
-- [ ] fix visualizer missing left padding
-
-- [ ] prevent esc from closing lyrics overlay
+  - [X] Toggle Lyrics
+  - [X] Toggle Visualizer
 
 - [ ] Lessen delays while reordering
 
-- [ ] Slide out settings menu on close
-
-- [ ] Prevent/recover from Failed to play song so that HTMLPlayer and system don't get unsynced
-  - (`The play() request was interrupted by a new load request. https://goo.gl/LdLk22`)
-
-- [ ] Make loading of songs, playlists, etc on load more staggered so that page doesn't freeze
-
-- [ ] Load all cover art more lazily and delayed for same reason as above
-
 - [ ] Use List Virtualization for song list so that having larger libraries doesn't cause lag on all songs
-  - in short, loading only visible songs and not showing rest, but smartly loading the top and botton (for ex. predictively loading on scrolling)
+  - in short, loading only visible songs and not showing rest, but smartly loading the top and bottom (for ex. predictively loading on scrolling)
 
 - [ ] Allow drag and drop to playlist from Home view
 
-- [ ] In Home, show `1 Song` rather than `1 Songs`
-
 - [ ] Fix Help menu
-  - On Home menu, when pressing Help, use different help guide
-  - Disable keyboard shortcuts while in help menu to prevent conflict
-
-- [ ] On mobile, the Persistent Dropdowns are loaded inside the top bar, when they should be overlays
+  - [ ] On Home menu, when pressing Help, use different help guide
+  - [X] Disable keyboard shortcuts while in help menu to prevent conflict
 
 - [ ] Fix top bar on mobile
 
-- [ ] Add more to about menu
-
 - [ ] The app is using 400 MB RAM by default, but it should use more like 200 MB
   - now 290 MB
   - around 320-330 MB when playing a song
 
-- [ ] Loading a custom iconset tanks performance
-
-- [ ] Gapless and crossfade are just broken, they just are
-
-- [ ] fix drag and drop of songs not triggering sometimes
-
-- [ ] fix the UI of the 'Repeat Once' button
-
-- [ ] Fix share_target so that it supports both importing songs (as a "polyfill" for file_handlers) and searching/sharing songs
-
 - [ ] fix some themes' visibility issues
   - light mode mostly fixed, re-check all
 
-- [ ] Fix sharing so that it just doesn't copy URL
-
-- [ ] Can't move playlist to root unless I have another playlist in root
-
-- [ ] Center `Empty folder...`
-
-- [ ] Make dragging songs not select song details in song list but also make sure we can select that stuff (prevent conflicts)
-
 - [ ] proper pitch manipulation
   - [PitchShift](https://tonejs.github.io/docs/15.1.22/classes/PitchShift.html)?
 

Build/public/locales/en/translation.json

@@ -1,5 +1,13 @@
 {
   "title": "HTMLPlayer",
+  "update": {
+    "available": "Update Available",
+    "description": "A new version of HTMLPlayer is ready to install.",
+    "now": "Update Now",
+    "later": "Later",
+    "installing": "Installing update...",
+    "installed": "Update installed! Reloading..."
+  },
   "common": {
     "cancel": "Cancel",
     "close": "Close",
@@ -130,7 +138,11 @@
   },
   "about": {
     "toggleVisualizerShortcut": "Toggle visualizer shortcut - implementation needed",
-    "description": "A modern music player interface with playlists, song management, and an amazing visualizer."
+    "description": "A modern music player interface with playlists, song management, and an amazing visualizer.",
+    "version": "Version",
+    "privacy": "Privacy Policy",
+    "terms": "Terms of Service",
+    "madeWith": "Made with ❤️ using React, TypeScript, and Web Audio API"
   },
   "metadataWorker": {
     "failedToReadAlbumArt": "Failed to read album art",
@@ -199,7 +211,8 @@
     "failedToReadFile": "Failed to read file",
     "cannotMoveIntoItself": "Cannot move item into itself",
     "cannotMoveFolderIntoDescendant": "Cannot move folder into its descendant",
-    "noFoldersAvailable": "No folders available"
+    "noFoldersAvailable": "No folders available",
+    "emptyFolder": "Empty folder"
   },
   "noResults": {
     "search": "No songs found",
@@ -392,7 +405,8 @@
     "featuredPlaylists": "Spotlight playlists",
     "emptyPlaylists": "Create playlists to pin them here.",
     "playPlaylist": "Play",
-    "playlistCount": "{{count}} songs"
+    "playlistCount_one": "{{count}} song",
+    "playlistCount_other": "{{count}} songs"
   },
   "pip": {
     "couldNotAccessStylesheet": "Could not access stylesheet:",

Build/public/locales/fr/translation.json

@@ -1,5 +1,13 @@
 {
   "title": "HTMLPlayer",
+  "update": {
+    "available": "Mise à jour disponible",
+    "description": "Une nouvelle version de HTMLPlayer est prête à être installée.",
+    "now": "Mettre à jour",
+    "later": "Plus tard",
+    "installing": "Installation de la mise à jour...",
+    "installed": "Mise à jour installée ! Rechargement..."
+  },
   "common": {
     "cancel": "Annuler",
     "close": "Fermer",
@@ -129,7 +137,11 @@
   },
   "about": {
     "toggleVisualizerShortcut": "Raccourci pour activer/désactiver le visualiseur - implémentation nécessaire",
-    "description": "Une interface moderne de lecteur de musique avec playlists, gestion des chansons et un visualiseur incroyable."
+    "description": "Une interface moderne de lecteur de musique avec playlists, gestion des chansons et un visualiseur incroyable.",
+    "version": "Version",
+    "privacy": "Politique de confidentialité",
+    "terms": "Conditions d'utilisation",
+    "madeWith": "Fait avec ❤️ en utilisant React, TypeScript et Web Audio API"
   },
   "metadataWorker": {
     "failedToReadAlbumArt": "Échec de lecture de la pochette d'album",
@@ -195,7 +207,8 @@
     "failedToReadFile": "Échec de lecture du fichier",
     "cannotMoveIntoItself": "Impossible de déplacer l'élément vers lui-même",
     "cannotMoveFolderIntoDescendant": "Impossible de déplacer le dossier vers son descendant",
-    "noFoldersAvailable": "Aucun dossier disponible"
+    "noFoldersAvailable": "Aucun dossier disponible",
+    "emptyFolder": "Dossier vide"
   },
   "noResults": {
     "search": "Aucune chanson trouvée",
@@ -364,7 +377,8 @@
     "featuredPlaylists": "Playlists à l'honneur",
     "emptyPlaylists": "Créez des playlists pour les retrouver ici.",
     "playPlaylist": "Lecture",
-    "playlistCount": "{{count}} titres"
+    "playlistCount_one": "{{count}} titre",
+    "playlistCount_other": "{{count}} titres"
   },
   "pip": {
     "couldNotAccessStylesheet": "Impossible d'accéder à la feuille de style :",

Build/src/components/Draggable.module.css

@@ -141,4 +141,17 @@
 .draggableItem[data-dragging="true"] {
   opacity: 0.5;
   cursor: grabbing;
+  user-select: none;
+}
+
+/* Drag handle, only this area triggers drag */
+.dragHandle {
+  cursor: grab;
+  user-select: none;
+  -webkit-user-select: none;
+  touch-action: none;
+}
+
+.dragHandle:active {
+  cursor: grabbing;
 }

Build/src/components/Draggable.tsx

@@ -46,8 +46,15 @@ interface DraggableItemProps {
   id: string;
   type: "song" | "playlist" | "folder";
   data: any;
-  children: React.ReactNode;
+  children: React.ReactNode | ((dragHandleProps: DragHandleProps) => React.ReactNode);
   disabled?: boolean;
+  /** If true, only the DragHandle child will initiate drag (allows text selection) */
+  useDragHandle?: boolean;
+}
+
+export interface DragHandleProps {
+  listeners: ReturnType<typeof useDraggable>["listeners"];
+  attributes: ReturnType<typeof useDraggable>["attributes"];
 }
 
 interface DropZoneProps {
@@ -259,6 +266,7 @@ export const DraggableItem: React.FC<DraggableItemProps> = ({
   data,
   children,
   disabled = false,
+  useDragHandle = false,
 }) => {
   const { attributes, listeners, setNodeRef, transform, isDragging } =
     useDraggable({
@@ -273,13 +281,53 @@ export const DraggableItem: React.FC<DraggableItemProps> = ({
       }
     : undefined;
 
+  // If using drag handle, pass listeners via render prop or inject into children
+  const renderChildren = (): React.ReactNode => {
+    if (useDragHandle && typeof children === "function") {
+      // Render prop pattern - call the function with drag handle props
+      return children({ listeners, attributes });
+    } else if (useDragHandle && typeof children !== "function" && React.isValidElement(children)) {
+      // Clone children and inject drag listeners for any DragHandle components
+      return React.Children.map(children, (child) => {
+        if (React.isValidElement(child)) {
+          return React.cloneElement(child as React.ReactElement<any>, {
+            __dragListeners: listeners,
+          });
+        }
+        return child;
+      });
+    }
+    return typeof children === "function" ? null : children;
+  };
+
   return (
     <div
       ref={setNodeRef}
       style={style}
       className={dragStyles.draggableItem}
       data-dragging={isDragging ? "true" : "false"}
-      {...listeners}
+      {...(useDragHandle ? {} : listeners)}
+      {...(useDragHandle ? {} : attributes)}
+    >
+      {renderChildren()}
+    </div>
+  );
+};
+
+// Drag handle component - only this element initiates drag when useDragHandle is true
+export const DragHandle: React.FC<{
+  children: React.ReactNode;
+  className?: string;
+  listeners?: DragHandleProps["listeners"];
+  attributes?: DragHandleProps["attributes"];
+  __dragListeners?: any; // Legacy: Injected by DraggableItem via cloneElement
+}> = ({ children, className, listeners, attributes, __dragListeners }) => {
+  // Use explicit props first, fall back to injected props
+  const dragListeners = listeners || __dragListeners;
+  return (
+    <div
+      className={`${dragStyles.dragHandle} ${className || ""}`}
+      {...dragListeners}
       {...attributes}
     >
       {children}

Build/src/components/HelpGuide.tsx

@@ -11,10 +11,13 @@ interface HelpGuideProps {
 
 const { Badge, Close, Navigation } = components;
 
-const TourContext = createContext<{ loaded: boolean }>({ loaded: false });
+const TourContext = createContext<{ loaded: boolean; isOpen: boolean }>({ loaded: false, isOpen: false });
 
 export const useTourLoaded = () => useContext(TourContext);
 
+// Re-export useTour for external use (e.g., keyboard shortcuts)
+export { useTour };
+
 export const HelpGuideProvider = ({ children }: HelpGuideProps) => {
   function useTourStepsConfig() {
     const { i18n } = useTranslation();
@@ -60,14 +63,14 @@ export const HelpGuideProvider = ({ children }: HelpGuideProps) => {
 
   if (!tourStepsConfig.length) {
     return (
-      <TourContext.Provider value={{ loaded: false }}>
+      <TourContext.Provider value={{ loaded: false, isOpen: false }}>
         {children}
       </TourContext.Provider>
     );
   }
 
   return (
-    <TourContext.Provider value={{ loaded: true }}>
+    <TourContext.Provider value={{ loaded: true, isOpen: false }}>
       <TourProvider
         steps={steps}
         styles={{