Render unknown URLs inside the app shell and move ListeningStats to the domain types

Add catch-all routes so unknown pages 404 inside the (app) layout and unknown
/api URLs return a JSON 404 instead of redirecting to the login page. Restore
the full root error page.

backend/Core/Musify.Application/PlayLists/AddAlbumToPlayList.cs

@@ -0,0 +1,86 @@
+using ErrorOr;
+using Mediator;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using Musify.Application.Contracts;
+using Musify.Application.PlayLists.Responses;
+using Musify.Domain.Entities;
+
+namespace Musify.Application.PlayLists
+{
+    public record AddAlbumToPlayListCommand(long UserId, Guid PlayListId, Guid AlbumId)
+        : ICommand<ErrorOr<AddAlbumToPlayListResponse>>;
+
+    public class AddAlbumToPlayListCommandHandler(
+        IDatabase database,
+        ILogger<AddAlbumToPlayListCommandHandler> logger)
+        : ICommandHandler<AddAlbumToPlayListCommand, ErrorOr<AddAlbumToPlayListResponse>>
+    {
+        public async ValueTask<ErrorOr<AddAlbumToPlayListResponse>> Handle(AddAlbumToPlayListCommand request, CancellationToken cancellationToken)
+        {
+            var playList = await database.PlayLists
+                .SingleOrDefaultAsync(pl => pl.Id == request.PlayListId, cancellationToken);
+            if (playList == null)
+            {
+                logger.LogInformation("Playlist {PlayListId} not found", request.PlayListId);
+                return Error.NotFound();
+            }
+
+            if (playList.UserId != request.UserId)
+            {
+                logger.LogWarning("User {UserId} is not the owner of playlist {PlayListId}", request.UserId, request.PlayListId);
+                return Error.Unauthorized();
+            }
+
+            var albumExists = await database.Albums
+                .AsNoTracking()
+                .AnyAsync(album => album.Id == request.AlbumId, cancellationToken);
+            if (!albumExists)
+            {
+                logger.LogInformation("Album {AlbumId} not found", request.AlbumId);
+                return Error.NotFound(description: $"Album {request.AlbumId} not found");
+            }
+
+            var albumTrackIds = await database.AlbumHasTracks
+                .AsNoTracking()
+                .Where(albumTrack => albumTrack.AlbumId == request.AlbumId)
+                .OrderBy(albumTrack => albumTrack.TrackNumber)
+                .Select(albumTrack => albumTrack.TrackId)
+                .ToListAsync(cancellationToken);
+
+            var playListTracksQuery = database.PlayListHasTracks
+                .Where(plt => plt.PlayListId == request.PlayListId);
+
+            var existingTrackIds = (await playListTracksQuery
+                .Select(plt => plt.TrackId)
+                .ToListAsync(cancellationToken)).ToHashSet();
+
+            var newTrackIds = albumTrackIds
+                .Where(trackId => !existingTrackIds.Contains(trackId))
+                .ToList();
+
+            if (newTrackIds.Count == 0)
+                return new AddAlbumToPlayListResponse(0);
+
+            var nextPosition = existingTrackIds.Count > 0
+                ? await playListTracksQuery.MaxAsync(plt => plt.Position, cancellationToken) + 1
+                : 0;
+
+            await database.PlayListHasTracks.AddRangeAsync(
+                newTrackIds.Select((trackId, index) => new PlayListHasTrack
+                {
+                    PlayListId = request.PlayListId,
+                    TrackId = trackId,
+                    Position = nextPosition + index
+                }),
+                cancellationToken);
+
+            await database.SaveChangesAsync(cancellationToken);
+
+            logger.LogInformation("Added {Count} tracks from album {AlbumId} to playlist {PlayListId}",
+                newTrackIds.Count, request.AlbumId, request.PlayListId);
+
+            return new AddAlbumToPlayListResponse(newTrackIds.Count);
+        }
+    }
+}

backend/Core/Musify.Application/PlayLists/GetPlayListById.cs

@@ -21,6 +21,8 @@ namespace Musify.Application.PlayLists
                 .Select(p => new
                 {
                     PlayList = p,
+                    TrackCount = p.PlayListTracks.Count,
+                    DurationSeconds = p.PlayListTracks.Sum(plt => (double?)plt.Track.DurationSeconds) ?? 0,
                     CoverTrackIds = p.PlayListTracks
                         .OrderBy(plt => plt.Position)
                         .Take(PlayListApplicationResponse.CoverTrackCount)
@@ -36,7 +38,7 @@ namespace Musify.Application.PlayLists
                 && entry.PlayList.UserId != request.RequestingUserId)
                 return Error.NotFound();
 
-            return PlayListApplicationResponse.FromEntity(entry.PlayList, entry.CoverTrackIds);
+            return PlayListApplicationResponse.FromEntity(entry.PlayList, entry.TrackCount, entry.DurationSeconds, entry.CoverTrackIds);
         }
     }
 }

backend/Core/Musify.Application/PlayLists/GetPlayLists.cs

@@ -25,6 +25,8 @@ namespace Musify.Application.PlayLists
                 .Select(p => new
                 {
                     PlayList = p,
+                    TrackCount = p.PlayListTracks.Count,
+                    DurationSeconds = p.PlayListTracks.Sum(plt => (double?)plt.Track.DurationSeconds) ?? 0,
                     CoverTrackIds = p.PlayListTracks
                         .OrderBy(plt => plt.Position)
                         .Take(PlayListApplicationResponse.CoverTrackCount)
@@ -34,7 +36,7 @@ namespace Musify.Application.PlayLists
                 .ToPagedListAsync(request.PageNumber, request.PageSize, totalCount, cancellationToken);
 
             var pagedPlayLists = new StaticPagedList<PlayListApplicationResponse>(
-                pagedEntities.Select(entry => PlayListApplicationResponse.FromEntity(entry.PlayList, entry.CoverTrackIds)),
+                pagedEntities.Select(entry => PlayListApplicationResponse.FromEntity(entry.PlayList, entry.TrackCount, entry.DurationSeconds, entry.CoverTrackIds)),
                 pagedEntities.PageNumber, pagedEntities.PageSize, pagedEntities.TotalItemCount);
 
             return PaginatedResponse<PlayListApplicationResponse>.FromPagedList(pagedPlayLists);

backend/Core/Musify.Application/PlayLists/GetPlayListsByUserId.cs

@@ -46,6 +46,8 @@ namespace Musify.Application.PlayLists
                 .Select(p => new
                 {
                     PlayList = p,
+                    TrackCount = p.PlayListTracks.Count,
+                    DurationSeconds = p.PlayListTracks.Sum(plt => (double?)plt.Track.DurationSeconds) ?? 0,
                     CoverTrackIds = p.PlayListTracks
                         .OrderBy(plt => plt.Position)
                         .Take(PlayListApplicationResponse.CoverTrackCount)
@@ -55,7 +57,7 @@ namespace Musify.Application.PlayLists
                 .ToPagedListAsync(request.PageNumber, request.PageSize, totalCount, cancellationToken);
 
             var pagedPlayLists = new StaticPagedList<PlayListApplicationResponse>(
-                pagedEntities.Select(entry => PlayListApplicationResponse.FromEntity(entry.PlayList, entry.CoverTrackIds)),
+                pagedEntities.Select(entry => PlayListApplicationResponse.FromEntity(entry.PlayList, entry.TrackCount, entry.DurationSeconds, entry.CoverTrackIds)),
                 pagedEntities.PageNumber, pagedEntities.PageSize, pagedEntities.TotalItemCount);
 
             return PaginatedResponse<PlayListApplicationResponse>.FromPagedList(pagedPlayLists);

backend/Core/Musify.Application/PlayLists/Responses/AddAlbumToPlayListResponse.cs

@@ -0,0 +1,4 @@
+namespace Musify.Application.PlayLists.Responses
+{
+    public record AddAlbumToPlayListResponse(int AddedCount);
+}

backend/Core/Musify.Application/PlayLists/Responses/PlayListApplicationResponse.cs

@@ -1,3 +1,5 @@
+using System.Text.Json.Serialization;
+using Musify.Application.Serialization;
 using Musify.Domain.Entities;
 using Musify.Domain.ValueObjects;
 
@@ -10,7 +12,10 @@ namespace Musify.Application.PlayLists.Responses
         string? SmallImageKeyName,
         string? MediumImageKeyName,
         string? LargeImageKeyName,
+        [property: JsonConverter(typeof(LongAsStringConverter))] long OwnerUserId,
         PlaylistVisibility Visibility,
+        int TrackCount,
+        double DurationSeconds,
         DateTime CreatedAt,
         DateTime UpdatedAt,
         IReadOnlyList<Guid> CoverTrackIds)
@@ -19,6 +24,8 @@ namespace Musify.Application.PlayLists.Responses
 
         public static PlayListApplicationResponse FromEntity(
             PlayList playList,
+            int trackCount = 0,
+            double durationSeconds = 0,
             IReadOnlyList<Guid>? coverTrackIds = null)
         {
             return new PlayListApplicationResponse(
@@ -28,7 +35,10 @@ namespace Musify.Application.PlayLists.Responses
                 playList.Pictures?.SmallName,
                 playList.Pictures?.MediumName,
                 playList.Pictures?.LargeName,
+                playList.UserId,
                 playList.Visibility,
+                trackCount,
+                durationSeconds,
                 playList.CreatedAt,
                 playList.UpdatedAt,
                 coverTrackIds ?? []);

backend/Core/Musify.Application/PlayLists/UpdatePlayList.cs

@@ -112,7 +112,22 @@ namespace Musify.Application.PlayLists
                 .ToListAsync(cancellationToken);
 
             logger.LogInformation("Updated playlist {PlayListId}", playListEntity.Id);
-            return PlayListApplicationResponse.FromEntity(playListEntity, coverTrackIds);
+            var totals = await database.PlayListHasTracks
+                .AsNoTracking()
+                .Where(plt => plt.PlayListId == playListEntity.Id)
+                .GroupBy(plt => plt.PlayListId)
+                .Select(group => new
+                {
+                    TrackCount = group.Count(),
+                    DurationSeconds = group.Sum(plt => plt.Track.DurationSeconds)
+                })
+                .SingleOrDefaultAsync(cancellationToken);
+
+            return PlayListApplicationResponse.FromEntity(
+                playListEntity,
+                totals?.TrackCount ?? 0,
+                totals?.DurationSeconds ?? 0,
+                coverTrackIds);
         }
 
         private async Task<ErrorOr<Success>> PublishUpdatePlayListPictureSourceEventAsync(

backend/Hosts/Musify.Api/Endpoints/PlayListEndpoints.cs

@@ -94,6 +94,14 @@ public static class PlayListEndpoints
             .Produces(StatusCodes.Status404NotFound)
             .Produces(StatusCodes.Status409Conflict);
 
+        group.MapPost("/{playlistId}/albums/{albumId}", AddAlbumToPlayList)
+            .WithName("AddAlbumToPlayList")
+            .WithSummary("Add All The Tracks Of An Album To One Of Your PlayLists, Skipping Those Already In It.")
+            .RequireAuthorization()
+            .Produces<AddAlbumToPlayListResponse>()
+            .Produces(StatusCodes.Status401Unauthorized)
+            .Produces(StatusCodes.Status404NotFound);
+
         group.MapDelete("/{playlistId}/tracks/{trackId}", RemoveTrackFromPlayList)
             .WithName("RemoveTrackFromPlayList")
             .WithSummary("Remove A Track From A PlayList.")
@@ -234,6 +242,20 @@ public static class PlayListEndpoints
         return trackResult.ToCreatedResult(track => $"/tracks/{track.Id}");
     }
 
+    private static async Task<IResult> AddAlbumToPlayList(
+        IMediator mediator,
+        CurrentUser currentUser,
+        Guid playlistId,
+        Guid albumId,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(
+            new AddAlbumToPlayListCommand(currentUser.RequiredId, playlistId, albumId),
+            cancellationToken);
+
+        return result.ToHttpResult();
+    }
+
     private static async Task<IResult> RemoveTrackFromPlayList(
         IMediator mediator,
         CurrentUser currentUser,

backend/Tests/Musify.Application.Tests/PlayLists/AddAlbumToPlayListCommandHandlerTests.cs

@@ -0,0 +1,91 @@
+using ErrorOr;
+using Microsoft.EntityFrameworkCore;
+using Musify.Application.PlayLists;
+using Musify.Application.Tests.TestSupport;
+using Musify.Domain.Entities;
+using Xunit;
+
+namespace Musify.Application.Tests.PlayLists
+{
+    public sealed class AddAlbumToPlayListCommandHandlerTests : HandlerTestBase
+    {
+        private AddAlbumToPlayListCommandHandler CreateHandler() => new(Database, NoOpLogger<AddAlbumToPlayListCommandHandler>());
+
+        [Fact]
+        public async Task Handle_AddsAlbumTracksInAlbumOrder()
+        {
+            var owner = TestEntities.User();
+            var playList = TestEntities.PlayList(owner.Id);
+            var album = TestEntities.Album(owner.Id);
+            var first = TestEntities.Track(owner, "First");
+            var second = TestEntities.Track(owner, "Second");
+            await SeedAsync(
+                owner, playList, album, first, second,
+                new AlbumHasTrack { AlbumId = album.Id, TrackId = second.Id, TrackNumber = 2 },
+                new AlbumHasTrack { AlbumId = album.Id, TrackId = first.Id, TrackNumber = 1 });
+
+            var result = await CreateHandler().Handle(new AddAlbumToPlayListCommand(owner.Id, playList.Id, album.Id), TestContext.Current.CancellationToken);
+
+            Assert.False(result.IsError);
+            Assert.Equal(2, result.Value.AddedCount);
+            var links = await Database.PlayListHasTracks.OrderBy(link => link.Position).ToListAsync(TestContext.Current.CancellationToken);
+            Assert.Equal([first.Id, second.Id], links.Select(link => link.TrackId));
+            Assert.Equal([0, 1], links.Select(link => link.Position));
+        }
+
+        [Fact]
+        public async Task Handle_SkipsTracksAlreadyInPlayList_AndAppendsAfterThem()
+        {
+            var owner = TestEntities.User();
+            var playList = TestEntities.PlayList(owner.Id);
+            var album = TestEntities.Album(owner.Id);
+            var existing = TestEntities.Track(owner, "Existing");
+            var fresh = TestEntities.Track(owner, "Fresh");
+            await SeedAsync(
+                owner, playList, album, existing, fresh,
+                new AlbumHasTrack { AlbumId = album.Id, TrackId = existing.Id, TrackNumber = 1 },
+                new AlbumHasTrack { AlbumId = album.Id, TrackId = fresh.Id, TrackNumber = 2 },
+                new PlayListHasTrack { PlayListId = playList.Id, TrackId = existing.Id, Position = 4 });
+
+            var result = await CreateHandler().Handle(new AddAlbumToPlayListCommand(owner.Id, playList.Id, album.Id), TestContext.Current.CancellationToken);
+
+            Assert.Equal(1, result.Value.AddedCount);
+            var link = await Database.PlayListHasTracks.SingleAsync(l => l.TrackId == fresh.Id, TestContext.Current.CancellationToken);
+            Assert.Equal(5, link.Position);
+        }
+
+        [Fact]
+        public async Task Handle_PlayListMissing_ReturnsNotFound()
+        {
+            var result = await CreateHandler().Handle(new AddAlbumToPlayListCommand(1, Guid.NewGuid(), Guid.NewGuid()), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.NotFound, result.FirstError.Type);
+        }
+
+        [Fact]
+        public async Task Handle_NotOwner_ReturnsUnauthorized()
+        {
+            var owner = TestEntities.User(1, "owner");
+            var stranger = TestEntities.User(2, "stranger");
+            var playList = TestEntities.PlayList(owner.Id);
+            var album = TestEntities.Album(owner.Id);
+            await SeedAsync(owner, stranger, playList, album);
+
+            var result = await CreateHandler().Handle(new AddAlbumToPlayListCommand(stranger.Id, playList.Id, album.Id), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.Unauthorized, result.FirstError.Type);
+        }
+
+        [Fact]
+        public async Task Handle_AlbumMissing_ReturnsNotFound()
+        {
+            var owner = TestEntities.User();
+            var playList = TestEntities.PlayList(owner.Id);
+            await SeedAsync(owner, playList);
+
+            var result = await CreateHandler().Handle(new AddAlbumToPlayListCommand(owner.Id, playList.Id, Guid.NewGuid()), TestContext.Current.CancellationToken);
+
+            Assert.Equal(ErrorType.NotFound, result.FirstError.Type);
+        }
+    }
+}

web-player/.env.example

@@ -11,8 +11,9 @@ ZITADEL_CLIENT_SECRET=your-web-app-client-secret
 AUTH_REDIRECT_URI=http://localhost:5173/auth/callback
 AUTH_POST_LOGOUT_URI=http://localhost:5173/
 
-# Secret used to derive the session cookie encryption key (any long random string)
-SESSION_SECRET=change-me-to-a-long-random-string
+# Secret used to derive the session cookie encryption key. Required, at least
+# 32 characters (e.g. `openssl rand -base64 48`).
+SESSION_SECRET=change-me-to-a-long-random-string-of-32-chars-or-more
 
 # Backend API base URL
 API_BASE_URL=http://localhost:5111

web-player/CLAUDE.md

@@ -1,6 +1,6 @@
 # Musify: web-player
 
-Musify's public web app (`web-player/` folder). For design and UI recipes, use the **`musify-web`** skill.
+Musify's public web app (`web-player/` folder). Design and UI recipes live in this file and in `src/routes/layout.css`.
 
 ## Stack
 
@@ -15,7 +15,8 @@ npm run dev          # dev server (port 5173)
 npm run build
 npm run check         # svelte-check, must exit 0 errors before closing a change
 npm run format         # prettier --write .
-npm run lint            # prettier --check . && eslint . && npm run lint:tokens
+npm run test            # vitest run (tests live next to the file they test)
+npm run lint            # prettier --check . && eslint . && npm run lint:tokens && npm run test
 npm run lint:tokens      # scripts/check-tokens.mjs, the design system guardrail (see below)
 ```
 
@@ -23,6 +24,7 @@ npm run lint:tokens      # scripts/check-tokens.mjs, the design system guardrail
 
 - **No comments** in code unless essential.
 - `npm run lint` and `npm run check` must exit clean before closing a change.
+- **Imports:** always `$lib/...`, never `../` (ESLint enforces it). Non-null assertions are forbidden too.
 - **Always Svelte 5 runes:** `$props()` with `interface Props`, `$state`, `$derived`, `$effect`. No `export let` or `$:`. `{#each}` always keyed.
 - **Server only code goes under `$lib/server/`**, and it's never imported from client code.
 - SSR data comes through `load` in `+page.server.ts`/`+layout.server.ts` and lands in the `data` prop.
@@ -31,26 +33,40 @@ npm run lint:tokens      # scripts/check-tokens.mjs, the design system guardrail
 
 ## Folder structure
 
-- `src/lib/state/` holds reactive rune based state (`*.svelte.ts` files that don't have a more specific home). Player state stays in `$lib/player/`, theme mode in `$lib/theme/`.
-- `src/lib/data/` holds client side domain helpers: albums, collections, genres, mixes, recentlyPlayed, search.
-- `src/lib/utils/` holds generic utilities with no domain knowledge, like `format.ts`.
-- `src/lib/components/layout/` holds the app chrome: Sidebar, TopBar, TabsBar, MobileHeader.
+- `src/lib/types.ts` holds the domain types (`Track`, `Album`, `Playlist`, `Mix`, `ListeningStats`, `Paged<T>`). Pages and the player only ever see these, never raw API DTOs.
+- `src/lib/player/` is the player: `player.svelte.ts` (state and orchestration), `queue.ts` (pure queue operations), `stream.ts`, `mediaSession.ts`, `progressClock.ts`, `listenTracker.ts`, `recentlyPlayed.ts` (merges `player.recentlyPlayed` with the server history), and `actions.ts` (`playAllOrToggle`, `playShuffled`, `isQueueCurrent`).
+- `src/lib/state/` holds reactive rune state: `panels.svelte.ts` (queue panel, create playlist modal), `history.svelte.ts` (previous page for `BackLink`), `menu.svelte.ts` (`createMenu<T>()`), `pagedList.svelte.ts` (`createPagedList`), `dialog.svelte.ts`, `liked.svelte.ts` (the user's liked tracks), `toggle.svelte.ts` (`createToggle`), and `scroll.ts` (`restoreScroll`). Nothing in `state/` imports from `components/`.
+- `src/lib/theme/` holds the theme: `accent.svelte.ts` (accent hue per track and the hue fade), `mode.svelte.ts`, `palette.ts`, `tokens.ts`, and `color.ts` (`ACCENT_HUE`). The player never imports from `theme/`: `(app)/+layout.svelte` follows `player.currentId` and calls `accent.follow`.
+- `src/lib/data/` holds client side domain helpers: albums, genres, search. It never imports from `player/`.
+- `src/lib/utils/` holds generic utilities: `format.ts`, `collections.ts`, `hrefs.ts` (search, genre and cover URLs), `menuPosition.ts`, `storage.ts`, `transitions.ts`.
+- `src/lib/actions/` holds Svelte actions: `clickOutside`, `onEscape`, `pressable`.
+- `src/lib/validation.ts` holds the form limits (`LIMITS`) shared by client forms and server parsers.
+- `src/lib/server/` is server only code (see below).
+- `src/lib/components/shell/` holds the app shell: Sidebar, TopBar, TabsBar, MobileHeader, AccountMenu, and `navLinks.ts`.
 - `src/lib/components/player/` holds the player UI: PlayerBar, PlayerDock, Queue, TrackInfo, TransportControls.
-- `src/lib/components/ui/` holds the design system components, split into five categories:
+- `src/lib/components/music/` holds the components that connect the UI to app state (the player, album data): TrackList, PlayAllButton, TrackContextMenu, AlbumContextMenu.
+- `src/lib/components/ui/` holds the design system, which is presentation only. ESLint forbids importing `$lib/player/*`, `$lib/data/*`, `$lib/server/*`, `components/music`, `components/shell` and `components/player` from it; it can use `$lib/state/*`, `$lib/utils/*`, `$lib/actions/*`, `$lib/theme/*` and `$lib/types`. It is split into five categories:
   - `primitives/` for generic controls with no music domain knowledge (Button, Input, Chip, Slider, and so on).
-  - `overlay/` for anything that floats above the content (Modal, ContextMenu, AccountMenu, and so on).
-  - `media/` for music domain display components (Artwork, TrackList, MediaCard, PlayButton, and so on).
+  - `overlay/` for anything that floats above the content (Modal, ContextMenu, GlassMenu, ConfirmDialog, and so on).
+  - `media/` for stateless music display components that receive props (Artwork, MediaCard, ListRow, PlayButton, and so on).
   - `forms/` for composite entity forms (AlbumForm, PlaylistForm, CoverForm, ImageDropzone).
-  - `layout/` for page level scaffolding (Page, PageHeader, SectionHeading). This is different from `components/layout/` above, which is the global app chrome.
-- Auth routes live under `src/routes/auth/`: `+page.svelte` is the login screen, and `login/`, `logout/`, `callback/` are the OIDC endpoints. The public user profile route is `src/routes/(app)/user/[id]/`, and its followers/following lists share one route, `user/[id]/[list=followList]/` (matcher in `src/params/followList.ts`).
+  - `layout/` for page level scaffolding (Page, PageHeader, SectionHeading).
+- The root `+layout.svelte` only holds the globals (fonts, theme, `DialogHost`). Everything the user sees after signing in lives under `src/routes/(app)/`, including Home (`(app)/+page.svelte`); `(app)/+layout.server.ts` guards the group and loads the shell data, and `(app)/+error.svelte` renders inside the shell. Unknown URLs hit the catch-all `(app)/[...rest]/` (it throws a 404) so they also get the shell (unknown `/api/...` URLs hit `api/[...rest]/`, a JSON 404); the root `+error.svelte` only covers errors outside the group or in the group layout load. Auth routes live under `src/routes/auth/`: `+page.svelte` is the login screen, and `login/`, `logout/`, `callback/` are the OIDC endpoints. The public user profile route is `src/routes/(app)/user/[id]/`, and its followers/following lists share one route, `user/[id]/[list=followList]/` (matcher in `src/params/followList.ts`).
+
+## Naming conventions and glossary
+
+- Variant maps are module level constants in upper case (`SIZE`, `VARIANT`).
+- Errors: destructure as `const { data, error } = ...` and name the caught value `err` in `catch (err)`.
+- Play handlers: `playFrom(index)` and `playAll()`. Form actions: `create`, `edit`, `delete`, `addTrack`, `removeTrack`.
+- UI copy: "Playlist" (never "Lista"), "Mezcla" (never "Mix"), "Modo claro". Total durations always go through `fmtDurationLong`.
 
 ## Styles
 
 The design system lives in `src/routes/layout.css` (`@theme` tokens plus `@utility` recipes) and in `src/lib/theme/` (`theme.css` for the static neutrals, `tokens.ts` for the dynamic tokens that depend on the user's hue). `scripts/check-tokens.mjs` (run as `npm run lint:tokens`, part of `lint`) fails on a stock radius, an `h-N w-N` pair, fractional quarter spacing, a literal hex/`rgba()`, or an arbitrary `-[…]` value outside its whitelist, so check that script before adding one.
 
 - **Radii:** always `rounded-tag/thumb/control/art/art-lg/panel/panel-lg` (or `rounded-full` for pills and circles). Never `rounded-sm/md/lg/xl/2xl/3xl` or a bare `rounded`.
-- **Square sizes:** use `size-*` instead of repeating `h-N w-N` (icons: `size-icon-xs/sm/md/lg/xl`; covers: `size-cover-xs` through `size-cover-hero`).
-- **Typography:** use the recipes `text-display-1/2/3/4`, `text-eyebrow`, `text-body`, `text-count`, with tracking through `tracking-display`/`tracking-eyebrow` rather than a loose `tracking-[…]`.
+- **Square sizes:** use `size-*` instead of repeating `h-N w-N` (icons: `size-icon-xs/sm/md/lg/xl/2xl/3xl`; covers: `size-cover-xs` through `size-cover-hero`).
+- **Typography:** use the recipes `text-display-1/2/3/4`, `text-eyebrow`, `text-body`, with tracking through `tracking-display`/`tracking-eyebrow` rather than a loose `tracking-[…]`.
 - **Spacing:** stick to the Tailwind scale in `.5` steps and avoid quarters like `.25`/`.75`, unless the semantic token calls for it (for example `mb-4.5` in `SectionHeading`).
 - **Colors:** always use `--mf-*`/`text-*`/`bg-*`/`border-*` from `theme.css`/`tokens.ts`. Never a literal hex or `rgba()` inside a `.svelte` file; those literals only belong in `theme.css`/`tokens.ts` as the source of truth.
 - **Inline `style="…"` and arbitrary `-[…]` values:** only the ones whitelisted in `scripts/check-tokens.mjs` (the stagger variable `--i`, tile hue, menu position, progress width, `text-[clamp(…)]`, `leading-[…]` on login's display type, `grid-cols-[auto_1fr]`, `max-h-[85dvh]`, `my-`/`py-[Ndvh]` for vertical centering, `transition-[filter]` on genre tiles, and `bg-[image:var(--mf-*)]`). Everything else should become a token.
@@ -59,7 +75,7 @@ The design system lives in `src/routes/layout.css` (`@theme` tokens plus `@utili
 
 ## App shell
 
-The shell in `src/routes/+layout.svelte` is a fixed `h-dvh` frame: Sidebar | (content column over PlayerDock) | Queue. Only the content column (`app-scroll`) scrolls, so nothing ever passes under the dock and the chrome can stay transparent over `app-backdrop`. Because the window never scrolls, scroll reset/restore on navigation is handled by `restoreScroll()` in `$lib/state/navigation.svelte.ts`; don't use `window.scrollTo`/`scrollY`.
+The shell in `src/routes/(app)/+layout.svelte` is a fixed `h-dvh` frame: Sidebar | (content column over PlayerDock) | Queue. Only the content column (`app-scroll`) scrolls, so nothing ever passes under the dock and the chrome can stay transparent over `app-backdrop`. Because the window never scrolls, scroll reset/restore on navigation is handled by `restoreScroll()` in `$lib/state/scroll.ts`; don't use `window.scrollTo`/`scrollY`.
 
 ## Motion
 
@@ -67,7 +83,7 @@ Every animation follows one scale of three durations and one easing curve, all d
 
 Entrances and movement always use `--mf-ease` (`ease-snappy` in Tailwind, `expoOut` in Svelte transitions), which feels immediate because most of the motion happens at the start. Color transitions keep the Tailwind default curve. Overlays must feel instant: the modal backdrop uses `transition:fade={{ duration: 200 }}` and the panel uses a local `pop` transition (opacity + scale + translateY, `expoOut`, 200ms) mirroring `animate-pop`'s keyframes — both directives so the modal fades and pops on close too, not just on open, and the whole thing settles in 200ms. Staggered lists use `--i` with 40ms steps capped at ten items.
 
-The only exceptions are looping indicators (equalizer bars, pulse, spin, sheen) and the accent hue crossfade in `+layout.svelte` (a random 2 to 4 seconds per song change), which is ambient and meant to be slow. Do not add new durations or curves; if something needs a different feel, pick the closest step of the scale. `prefers-reduced-motion` disables everything globally in `layout.css`.
+The only exceptions are looping indicators (equalizer bars, pulse, spin, sheen) and the accent hue crossfade in the root `+layout.svelte` (a random 2 to 4 seconds per song change), which is ambient and meant to be slow. Do not add new durations or curves; if something needs a different feel, pick the closest step of the scale. `prefers-reduced-motion` disables everything globally in `layout.css`.
 
 ## Auth
 
@@ -77,12 +93,21 @@ Environment variables live in `.env` (see `.env.example`): `ZITADEL_*`, `AUTH_RE
 
 ## Backend API
 
-Typed client via `openapi-fetch` over the `Musify.Api` OpenAPI spec. Inside a server `load` or action:
+Typed client via `openapi-fetch` over the `Musify.Api` OpenAPI spec. Inside a server `load` or action use the client in `$lib/server/api.ts`:
 
 ```ts
-import { createApiClient } from '$lib/server/api';
-const api = createApiClient({ fetch, accessToken: locals.accessToken ?? undefined });
-const { data, error: err } = await api.GET('/tracks');
+const api = apiFor(event); // or apiFor({ fetch, locals }); adds the bearer token when there is a session
+const { data, error } = await api.GET('/tracks');
 ```
 
-It returns `{ data, error }` (ErrorOr style) and never throws. The types live in `src/lib/api/schema.d.ts` and get regenerated with `npm run gen:api` (this needs the dev API running at `API_BASE_URL`, which only exposes `/openapi/v1.json` in Development).
+It returns `{ data, error }` (ErrorOr style) and never throws except on network errors. The types live in `src/lib/api/schema.d.ts` and get regenerated with `npm run gen:api` (this needs the dev API running at `API_BASE_URL`, which only exposes `/openapi/v1.json` in Development).
+
+Server helpers:
+
+- `api.ts` holds the client and error handling: `apiFor`, `unwrapOrError`, `failOnError` (turns an API error into a `fail(...)`), `requireData` (also narrows the response data) and `apiErrorDetail`.
+- `guards.ts` holds `requireUser`, `optionalUser` and `loginRedirect`. Keep them in pages and actions even though the `(app)` layout also redirects: page loads run in parallel with the layout load, and form actions skip it.
+- `mappers.ts` (`toTrack`, `toAlbum`, `toPlaylist`, `toMix`, `toPage`, `toCount`, `toListeningStats`, ...) turn DTOs into the domain types. Every load and `/api` endpoint goes through them, so `Number()` conversions on DTOs never reach routes or the client.
+- `actions/` holds `authedAction(handler)` (returns 401 without a token, reads the form and hands `{ api, form, params, locals, url }` to the handler) plus the shared `follow` and `playlist` actions.
+- `forms/` holds `fields.ts` (`formString`, `formFile`) and the form parsers (`parseAlbumForm`, `parsePlaylistForm`, `parseTrackUploadForm`); they validate with `LIMITS` from `$lib/validation`. `uploadOptionalCover` handles the optional cover upload.
+- `genres.ts` caches the genre list; `playbackConfig.ts` caches the anonymous listening setting.
+- Page sizes come from `$lib/config`; do not hardcode them.

web-player/README.md

@@ -31,5 +31,4 @@ Built and run as a container by the production stack — see
 [../deploy/README.md](../deploy/README.md). There the same variables come from
 `deploy/.env.prod` through compose instead of from `.env`.
 
-Conventions and the design system are documented in [CLAUDE.md](CLAUDE.md) and
-in the `musify-web` skill.
+Conventions and the design system are documented in [CLAUDE.md](CLAUDE.md).

web-player/docs/frontend-audit-plan.md

@@ -0,0 +1,315 @@
+# Plan de refactor tras la auditoría del frontend
+
+> **Cerrado.** Todas las partes están hechas; el plan activo es `frontend-structure-plan.md`.
+
+Plan de trabajo derivado de la auditoría del `web-player` (2026-09-24). Cada parte es un PR independiente, revisable por separado, que deja `npm run check` y `npm run lint` en verde. Antes de empezar una parte, mira el **Registro** del final.
+
+Leyenda de tamaño: **S** (< 1 h) · **M** (medio día) · **L** (1 día o más). Las partes marcadas con 🔗 dependen de cambios en `Musify.Api`.
+
+## Orden y dependencias
+
+```
+P0 Red de seguridad
+ └─ P1 Seguridad ─ P2 Reproductor ─ P3 Bugs de páginas ─ P4 Código muerto
+                                                            └─ P5 Modelo Track único
+                                                                 ├─ P6 Capa de servidor ─ P7 Formularios y validación
+                                                                 │                         └─ P8 Rendimiento 🔗
+                                                                 └─ P9 Responsabilidades ─ P10 Componentes y páginas
+                                                                                            └─ P11 Consistencia ─ P12 Guardarraíles y docs
+```
+
+P1 a P4 son arreglos acotados y se pueden mergear en cualquier orden. De P5 en adelante el orden importa: cada parte simplifica la siguiente.
+
+---
+
+## P0 · Red de seguridad (M)
+
+Objetivo: tener tests de las funciones puras antes de tocar lógica.
+
+- Añadir Vitest (`vitest`, script `npm run test`, incluido en `lint` o en CI).
+- Tests para lo que ya es puro: `fmtTime`, `fmtDurationLong`, `plural`, `albumMeta` (`utils/format.ts`), `findTopResult` (`data/search.ts`), `findConflict`, `genreHue` (`data/genres.ts`), `pickGreeting` (`server/greeting.ts`), `parseAlbumForm` (`server/albumForm.ts`), `appendUnique`, `shuffle`.
+- Extraer las operaciones de cola de `PlayerState` a funciones puras en `player/queue.ts` (`insertNext`, `append`, `move`, `nextIndex`, `previousIndex`) y testearlas. `PlayerState` pasa a llamarlas. Esto prepara P2.
+
+**Cierre:** `npm run test` en verde y cubre las funciones anteriores.
+
+---
+
+## P1 · Seguridad (S)
+
+1. **Redirección abierta con `returnTo`.**
+   - Nueva función `safeReturnTo(value: string | null | undefined): string` en `$lib/server/auth.ts`: acepta solo rutas que empiecen por `/` y no por `//` ni `/\`; si no, devuelve `/`.
+   - Aplicarla en `routes/auth/+page.server.ts` (ambos usos), en `routes/auth/login/+server.ts` (antes de guardar la cookie) y en `routes/auth/callback/+server.ts` (al leer la cookie).
+2. **`SESSION_SECRET` obligatorio.** En `$lib/server/config.ts`, `sessionSecret` pasa por `required()` y exige una longitud mínima de 32 caracteres. Actualizar el comentario de `.env.example`.
+3. **Validar las entradas de los endpoints `/api`.**
+   - `api/likes/+server.ts`: no reenviar el body tal cual; leer `trackId`, comprobar que es un string no vacío y devolver 400 si no.
+   - `api/listens/[id]/progress/+server.ts`: envolver `request.json()` para devolver 400 con JSON inválido en vez de 500.
+   - `server/image.ts`: `encodeURIComponent(id)` al construir la URL de upstream.
+   - `api/tracks/+server.ts`: acotar `pageSize` con un máximo (`MAX_PAGE_SIZE` en `config.ts`).
+
+**Cierre:** `/auth?returnTo=https://example.com` acaba en `/`; arrancar sin `SESSION_SECRET` falla con un mensaje claro; tests de `safeReturnTo`.
+
+---
+
+## P2 · Reproductor y cola (M)
+
+1. **Duplicados en la cola** (`player.svelte.ts` `playNext`/`appendToQueue`, `Queue.svelte`).
+   - `playNext` mueve la pista si ya estaba en la cola, en vez de duplicarla.
+   - `appendToQueue` omite las pistas que ya están pendientes.
+   - Con esto las claves `(track.id)` vuelven a ser únicas y `#index()` es fiable.
+2. **Fin de cola.** Con repetir desactivado, al terminar la última pista el reproductor se detiene en vez de volver al principio. Si más adelante se quiere "repetir todo", `repeat` pasará a `'off' | 'all' | 'one'` (queda fuera de este plan).
+3. **La cola se abre sola** (`+layout.svelte:44`). Abrirla solo la primera vez que empieza a sonar algo en la sesión (`currentId` pasa de `null` a un valor) y no volver a abrirla si el usuario la cierra.
+4. **Rollback de "Me gusta"** (`liked.svelte.ts:69`). En caso de error, revertir solo la entrada de ese id, no sustituir el mapa entero.
+5. **localStorage seguro.**
+   - Nuevo `$lib/utils/storage.ts` con `readStorage(key, fallback)` y `writeStorage(key, value)` envueltos en try/catch.
+   - Volumen: validar y acotar a 0–100 (hoy puede quedar `NaN`).
+   - Unificar claves: `musify.player.volume`, `musify.player.muted`, `musify.theme`.
+   - Persistir el volumen siempre, no solo cuando existe el elemento `<audio>`.
+
+**Cierre:** añadir la misma pista dos veces a la cola no rompe nada; la cola termina; tests de `player/queue.ts` actualizados; prueba manual en el Browser pane.
+
+---
+
+## P3 · Bugs de páginas y datos (M)
+
+1. **Permisos en la playlist** (`playlists/[id]`).
+   - El `load` devuelve `isOwner`, comparando el propietario de la playlist con `locals.user.sub`. Si la API no expone el propietario, añadirlo al DTO 🔗.
+   - Mostrar Editar, Eliminar y "Quitar" solo al propietario. Añadir `BackLink` como en el álbum y la mezcla, y `section: '/playlists'` cuando sea propia.
+2. **Una sola fuente para las playlists del usuario.**
+   - `+layout.server.ts` carga las playlists del usuario con `PLAYLIST_PICKER_PAGE_SIZE` y devuelve también `totalItemCount`.
+   - La barra lateral muestra las 8 primeras y usa el total real en el contador.
+   - Los menús contextuales (inicio, explorar, mezcla) usan esa lista desde `page.data` y así explorar y mezcla dejan de pedirla aparte.
+3. **Playlist destacada de inicio.**
+   - Nuevo endpoint `api/playlists/[id]/tracks/+server.ts`, análogo al de álbumes. "Reproducir" y "Aleatorio" cargan la lista completa en ese momento.
+   - La meta muestra el total real. La duración se quita hasta que la API la devuelva (P8).
+   - La promesa se resuelve con `{#await}` en vez de con un `$effect` que copia a estado.
+4. **Borrar canción de la biblioteca con confirmación.** `ConfirmDialog` acepta `fields` (inputs ocultos) y `library` lo usa, igual que álbumes y playlists.
+5. **Explorar.**
+   - Usar `plural()` para el número de canciones de un álbum.
+   - Contadores de chips y "N coincidencias" a partir de `totalItemCount` de cada respuesta, no de lo cargado.
+6. **Enlace `/terms`** en la subida: quitar el enlace hasta que exista una página de términos (o crearla, si se decide).
+7. **`playbackConfig.ts`:** no guardar en caché cuando la respuesta trae `error`.
+8. **`ImageDropzone`:** liberar la URL anterior con `URL.revokeObjectURL` al cambiar de archivo y al desmontar.
+9. **Textos.**
+   - "Populares esta semana" duplica "Continuar escuchando": quitar la sección hasta que haya un endpoint real de más escuchadas (o renombrarla a "Escuchado recientemente").
+   - `+error.svelte`: quitar la promesa de modo sin conexión.
+   - "Retomalo" → "Retómalo"; "Modo blanco" → "Modo claro".
+
+**Cierre:** un no propietario no ve acciones de edición; la barra lateral cuenta bien; la destacada reproduce la lista completa.
+
+---
+
+## P4 · Código muerto (S)
+
+Borrar sin sustituto:
+
+- `player.svelte.ts`: `playPlaylist`, `playlistTracks`, `playlists`, interfaz `Playlist`, getter `isPlaying`, `playNextItem` (usar `playNext([item])`).
+- `theme/palette.ts`: `Accent.gradient` (y con ello el tipo `Accent`, que queda en `string`).
+- `IconButton`: el mapa `TEXT` y la prop `tone` pasan a `plain` o por defecto; `muted` y `subtle` son idénticos.
+- `Artwork`: prop `fallback` y sus ramas `gradient` y `none`.
+- `MediaIdentity.badge`, `FollowButton.userId`, `EqBars.size` y `EqBars.barWidth`.
+- Acciones `follow` y `unfollow` en `explore/+page.server.ts` y en `user/[id]/[list=followList]/+page.server.ts`, con el `form?.message` que solo servía para ellas.
+- Utilidades `media-grid` y `text-count` de `layout.css` (y su mención en `CLAUDE.md`).
+- `TrackList.svelte`: el `use:enhance` redundante (queda `use:enhance`) y los `stopPropagation` de la línea 141.
+- `+page.server.ts` (inicio): el `redirect` previo a `requireUser`. `+layout.server.ts`: la rama `accountUrl = null`.
+- Clases que no hacen nada: `hover:text-fg-2` sobre `text-fg-2` (SegmentedControl, Sidebar, ArtistLink) y el `hidden sm:flex` anidado de `PlayerBar`.
+- Separadores vacíos (`<span></span>`, `<div class="flex-1">`) en `CoverForm` y `TopBar`: sustituir por `ml-auto`.
+- `sessionCookieOptions` deja de exportarse.
+
+**Cierre:** `grep` de cada símbolo sin resultados; la app se comporta igual.
+
+---
+
+## P5 · Modelo `Track` único (L)
+
+Objetivo: una sola forma de pista, normalizada en la frontera del servidor. Es el cambio que más código quita.
+
+1. **Tipos de dominio** en `$lib/types.ts`:
+   ```ts
+   export interface Track {
+   	id: string;
+   	title: string;
+   	artist: string | null;
+   	ownerUserId: string | null;
+   	explicit: boolean;
+   	duration: number;
+   	listensCount: number;
+   }
+   export interface LikedTrack extends Track {
+   	likedAt: number;
+   }
+   ```
+   Más `Album` y `Playlist` normalizados (`trackCount: number`, `releaseYear: number | null`, ids como `string`).
+2. **Mappers de servidor** en `$lib/server/mappers.ts`: `toTrack`, `toAlbum`, `toPlaylist`, `toMixTrack` (sustituye a `mixItemTrack`). Hacen todas las conversiones `Number()` y `String()`. Todos los `load` y los endpoints `/api` que devuelven pistas los usan.
+3. **El reproductor usa `Track`.**
+   - Se eliminan `PlayerTrack`, `QueueItem`, `ApiTrackLike`, `LikeToggleInput` y `TrackListTrack` (que pasa a ser `Track & { date?: string | number }`).
+   - Se eliminan `toQueueItems`, `toQueueItem`, `trackFromQueueItem` y `toTrack` del cliente.
+   - `current` pasa a ser `Track | null` en vez del centinela `EMPTY` con `id: ''`.
+4. **Páginas.** Quitar todos los `Number(...)`, los `?? undefined` y los mapeos intermedios (`listTracks`, `songRows`, `spotlightRows`, `popularTracks`…).
+
+**Cierre:** `grep -rn "Number(" src/routes --include=*.svelte` vacío; `isExplicit` solo aparece en `mappers.ts`; tests de los mappers.
+
+---
+
+## P6 · Capa de servidor (M)
+
+1. **Helpers en `$lib/server/api.ts`.**
+   - `apiFor(event)` sustituye los 15 `createApiClient({ fetch, accessToken: locals.accessToken ?? undefined })`.
+   - Exportar `type ApiClient` (hoy se redefine en `follows.ts`).
+   - `loginRedirect(url)`, usado por `requireUser`, `optionalUser` y `+layout.server.ts`.
+2. **Envoltorio de acciones** `authedAction(handler)`: comprueba el token (401 si falta), crea `api`, lee `form` y pasa `{ api, form, params, locals }`. Sustituye el bloque `requireAccessTokenAction` + `typeof` + `formData` + `createApiClient` de las ~10 acciones.
+3. **Lectura de formularios:** `formString(form, key)` y `formFile(form, key)` (devuelve `null` si el archivo viene vacío). Sustituyen los 17 `String(form.get(...) ?? '')` y los `instanceof File && size > 0`.
+4. **Nombres.**
+   - `unwrapOrFail` → `failOnError` (no desenvuelve nada).
+   - Desestructurar siempre como `const { data, error } = ...` y usar `catch (err)`.
+   - La acción `rename` de playlist pasa a `edit` y devuelve `{ edited: true }`, como la de álbum.
+5. **Sin aserciones no nulas:** quitar `urlsResult.data!` y `trackResult.data!` de `upload/+page.server.ts` usando el patrón de `failOnError` que estrecha el tipo.
+6. **`+layout.server.ts`:** una sola función para las tres cargas con fallback, sin `try/catch` duplicado (openapi-fetch solo lanza con error de red).
+7. **Tamaños de página:** todos los `pageSize` salen de `config.ts` (quitar `50`, `200`, `500` sueltos y el `PAGE_SIZE` local de `library`). Quitar el alias `EXPLORE_PAGE_SIZE as PAGE_SIZE`.
+
+**Cierre:** ninguna acción repite la plantilla de autenticación; `grep "createApiClient(" src/routes` vacío.
+
+---
+
+## P7 · Formularios y validación compartida (M)
+
+1. **Límites en un único sitio:** `$lib/validation.ts` (compartido entre cliente y servidor):
+   ```ts
+   export const LIMITS = {
+   	playlistName: 100,
+   	playlistDescription: 300,
+   	albumTitle: 200,
+   	albumDescription: 256,
+   	trackTitle: 100
+   } as const;
+   ```
+   Antes de fijarlos, comprobar los validadores de `Musify.Api` y usar sus valores. `ALBUM_EARLIEST_YEAR` se mueve aquí.
+2. **Parsers de servidor** en `$lib/server/forms/`: `parseAlbumForm` (existente), `parsePlaylistForm` (nuevo, sustituye el código duplicado de `create` y `edit`), `parseTrackUploadForm` (sacado de `upload/+page.server.ts`). Todos validan con `LIMITS`.
+3. **Portadas:** `uploadOptionalCover(api, endpoint, file)` sustituye los 4 bloques `if (cover ...) uploadPresignedImage(...)`.
+4. **Formularios de cliente:** `AlbumForm`, `PlaylistForm` y la subida usan `LIMITS` en `maxlength` y en el contador. Añadir el contador que falta en `AlbumForm` para que los tres se comporten igual.
+5. `formatSize` de la subida pasa a `utils/format.ts`.
+
+**Cierre:** cambiar un límite en `LIMITS` actualiza cliente y servidor; tests de los parsers.
+
+---
+
+## P8 · Rendimiento 🔗 (M, parte en backend)
+
+1. **Backend:** añadir `trackCount` y `durationSeconds` a la respuesta de playlist.
+2. **Frontend:**
+   - `playlists/+page.server.ts` deja de pedir hasta 500 pistas por playlist.
+   - `user/[id]/+page.server.ts` deja de hacer una petición por playlist.
+   - La destacada de inicio recupera la duración real.
+3. **Explorar:** cachear `/genres` en `$lib/server/genres.ts` (como `playbackConfig`, con TTL de unos minutos) y lanzar todas las peticiones en paralelo en vez de esperar primero a los géneros.
+4. **Añadir álbum a playlist** (`playlistActions.ts`): hoy hace un POST por pista en serie y se corta en 200. Pedir un endpoint de inserción múltiple 🔗; mientras tanto, paralelizar con un límite de concurrencia.
+
+**Cierre:** la página de playlists hace una sola petición a la API; el perfil hace dos.
+
+---
+
+## P9 · Separación de responsabilidades en `lib/` (L)
+
+1. **Dividir `player.svelte.ts`:**
+   - `player/queue.ts`: operaciones de cola (de P0).
+   - `player/stream.ts`: `resolveStream(id)` (fetch de `/stream`, ticket, `listenId`) y `readErrorMessage`.
+   - `player/mediaSession.ts`: registro de acciones y sincronización de metadatos y estado.
+   - `player/progressClock.ts`: el bucle `requestAnimationFrame` de progreso suave.
+   - `player/actions.ts`: `playAllOrToggle`, `playShuffled`, `isQueueCurrent`.
+   - `player/player.svelte.ts`: solo el estado y la orquestación.
+2. **Acento como número.**
+   - Nuevo `theme/accent.svelte.ts`: caché, `extractAccent` y el tono actual como `number`.
+   - Ahí mismo vive el fundido de tono que hoy está en `+layout.svelte` (`animateThemeHue()`).
+   - Se elimina `parseHue` (ya no hay que leer el tono de una cadena `oklch(...)`).
+3. **Dividir `state/navigation.svelte.ts`:**
+   - `state/history.svelte.ts`: `trackNavigation`, `previousPage`.
+   - `state/scroll.ts`: `restoreScroll`.
+   - `utils/hrefs.ts`: `searchHref`, `genreHref` y las URLs de portada (`trackCover(id, size)`, `playlistCover(playlist, size)` con el `v=updatedAt`, `albumCover(id, size)`), que hoy se escriben a mano en más de 15 sitios.
+   - `components/layout/navLinks.ts`: `appNavLinks` e `isNavActive` (sustituye el `isActive` duplicado de Sidebar y TabsBar).
+4. **Menús.** `contextMenuPosition` y `MenuPosition` pasan a `utils/menuPosition.ts`, sin `preventDefault()` dentro (lo hace quien llama). `state/menus.svelte.ts` deja de importar de un componente.
+5. **Movimientos de archivos:**
+   - `data/collections.ts` → `utils/collections.ts`.
+   - `player/queuePanel.svelte.ts` y `state/playlists.svelte.ts` → `state/panels.svelte.ts` (`queuePanel`, `createPlaylistModal`).
+   - `data/search.ts`: claves internas (`tracks`, `albums`, `playlists`, `users`) y etiquetas aparte en un mapa de textos.
+6. Tipar `+layout.svelte` con `interface Props`.
+
+**Cierre:** `player.svelte.ts` por debajo de ~250 líneas; ningún archivo de `state/` importa de `components/`.
+
+---
+
+## P10 · Componentes extraídos y páginas más finas (L)
+
+1. **Menú contextual.**
+   - `state/menu.svelte.ts` con `createMenu<T>()` genérico: sustituye `createTrackMenu` y el `albumMenu` hecho a mano de explorar.
+   - Componente `TrackContextMenu` que encapsula el bloque de 15 líneas repetido en inicio, explorar y mezcla. `AlbumContextMenu` para explorar.
+2. **`PlayAllButton {items}`** con el "Reproducir/Pausar" de álbum, playlist, mezcla, me gusta y la portada de inicio.
+3. **`createPagedList(fetcher)`** en `state/pagedList.svelte.ts` para la paginación infinita de explorar y de seguidores (estado, `appendUnique`, `hasMore` y un estado de error visible en vez de tragarse el fallo).
+4. **Primitivas.**
+   - `Button`, `IconButton`, `Chip` y `MenuItem` usan `<svelte:element this={href ? 'a' : 'button'}>` en vez de duplicar las dos ramas.
+   - Acción `use:onEscape` para `Modal`, `ContextMenu` y `AccountMenu`.
+   - `AccountMenu` incluye su propio disparador con el `Avatar`; `TopBar` y `MobileHeader` dejan de duplicarlo.
+   - `Artwork` y `Avatar` usan `{#key src}` en vez del `$effect` que reinicia `failed`.
+5. **Páginas.**
+   - Quitar los alias `const x = $derived(data.x)` y las funciones de una línea (`playSpotlight`, `shuffleSpotlight`, `openContextMenu`, `stepClass`…).
+   - Sustituir los `$effect` que copian `data` a estado local por `$derived` escribible cuando sea posible.
+   - Navegación con enlaces reales: `ListRow href` en vez de `onclick={() => goto(...)}`, y la destacada de inicio como `<a>`.
+   - `upload`: el indicador de pasos solo refleja estados reales (o se simplifica a "subiendo / listo").
+
+**Cierre:** ninguna página repite el bloque del menú ni el botón de reproducir; las tarjetas se pueden abrir con clic central.
+
+---
+
+## P11 · Consistencia (M, mecánico)
+
+1. **Imports:** siempre `$lib/...`, nunca `../`. Se hace cumplir en P12.
+2. **Convenciones de nombres** (se documentan en `CLAUDE.md`):
+   - Mapas de variantes en constantes de módulo en mayúsculas (`SIZE`, `VARIANT`).
+   - Errores: `error` al desestructurar y `err` en `catch`.
+   - Manejadores de reproducción: `playFrom(index)`, `playAll()`.
+   - Acciones: `create`, `edit`, `delete`, `addTrack`, `removeTrack`.
+3. **Glosario de interfaz:** "Playlist" (nunca "Lista"), "Mezcla" (nunca "Mix"), "Modo claro". Duraciones totales siempre con `fmtDurationLong`.
+4. **Tokens.**
+   - Iconos siempre con `size-icon-*`; añadir `size-icon-2xs` si hace falta para los de 14 px.
+   - Nada de `size={16}` en iconos Lucide.
+   - No usar tokens de icono como espaciado (`pb-icon-md`, `gap-icon-md`).
+   - Anchos siempre con clase (`w-(--mf-sidebar-w)`), no con `style`.
+   - Nueva utilidad `focus-ring` usada por `Button`, `IconButton`, `Chip` y los enlaces interactivos.
+5. **Rutas:** mover `routes/+page.svelte` y `+page.server.ts` (inicio) dentro de `(app)`, para que el grupo tenga sentido: todo lo de la app dentro y `auth/` fuera.
+
+**Cierre:** `npm run lint` en verde con las reglas nuevas de P12.
+
+---
+
+## P12 · Guardarraíles y documentación (S)
+
+1. **ESLint:**
+   - `no-restricted-imports` que prohíba `../*`.
+   - `@typescript-eslint/no-non-null-assertion`.
+   - `svelte/no-unused-props`.
+2. **`scripts/check-tokens.mjs`:** fallar con `size={N}` en iconos y con `size-N` sobre componentes Lucide.
+3. **Opcional:** `knip` para detectar exportaciones y archivos sin uso.
+4. **Documentación:**
+   - `CLAUDE.md`: nueva estructura de carpetas, helpers de servidor (`apiFor`, `authedAction`, mappers), convenciones de nombres y glosario.
+   - `docs/paginas.md`: está desactualizado (menciona el grupo `(marketing)` y la landing, que ya no existen).
+
+**Cierre:** las reglas nuevas fallan si se reintroduce cualquiera de los patrones eliminados.
+
+---
+
+## Registro
+
+| Parte                       | Estado | PR / notas                                                                                                             |
+| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| P0 Red de seguridad         | ✅     | Vitest + 37 tests; `player/queue.ts` extraído. `lint` ahora ejecuta `test`                                             |
+| P1 Seguridad                | ✅     | Hecho en la rama `claude/frontend-audit-plan-4f9432`                                                                   |
+| P2 Reproductor y cola       | ✅     | Sin probar en navegador (API caída)                                                                                    |
+| P3 Bugs de páginas          | ✅     | Backend: `ownerUserId` en playlist. Sin probar en navegador                                                            |
+| P4 Código muerto            | ✅     | Se mantiene el redirect a `/explore` de inicio (cubre escucha anónima)                                                 |
+| P5 Modelo Track único       | ✅     | `Paged<T>`, `Mix`, `PlaylistSummary` añadidos. Sin probar en navegador                                                 |
+| P6 Capa de servidor         | ✅     | `failOnError` + `requireData`; `parseAlbumForm` usa `formString`                                                       |
+| P7 Formularios y validación | ✅     | Límites según las columnas de BD del backend (playlist 50/256, pista 200)                                              |
+| P8 Rendimiento 🔗           | ✅     | Backend: `trackCount` y `durationSeconds` en playlist. Añadir álbum usa `POST /playlists/{id}/albums/{albumId}` (bulk) |
+| P9 Responsabilidades        | ✅     | `player.svelte.ts` queda en ~320 líneas                                                                                |
+| P10 Componentes y páginas   | ✅     | Quedan algunos alias `$derived(data.x)`; `{#key}` sustituido por `failedSrc`                                           |
+| P11 Consistencia            | ✅     |                                                                                                                        |
+| P12 Guardarraíles y docs    | ✅     | `knip` no añadido (opcional)                                                                                           |
+
+Leyenda: ⬜ pendiente · 🟡 en curso · ✅ hecho.

web-player/docs/frontend-structure-plan.md

@@ -0,0 +1,185 @@
+# Plan de estructura del frontend
+
+Plan derivado de la revisión de estructura del `web-player` (2026-09-24), hecha después de cerrar `frontend-audit-plan.md` (P0–P12). Cada parte es un PR independiente que deja `npm run check` y `npm run lint` en verde y no cambia el comportamiento visible. Antes de empezar una parte, mira el **Registro** del final.
+
+Leyenda de tamaño: **S** (< 1 h) · **M** (medio día) · **L** (1 día o más).
+
+## Orden y dependencias
+
+```
+E1 Layout del grupo (app)
+ └─ E2 Carpeta shell
+     └─ E3 Frontera de ui/ ─ E6 Explorar en componentes
+
+E4 Ubicación de estados   (independiente)
+E5 Capa de servidor       (independiente)
+E7 Acento fuera del reproductor (después de E1)
+
+E9 Tests (antes o junto con E1 y E5)
+
+E8 Documentación (al final)
+```
+
+E1 → E2 → E3 van en orden porque tocan los mismos imports. E4 y E5 se pueden hacer en cualquier momento. Conviene hacer E9 primero, o al menos sus puntos 1 y 2, para que E1 y E5 muevan el código de sesión con tests que detecten si algo se rompe.
+
+---
+
+## E1 · Layout del grupo `(app)` (M)
+
+Problema: el grupo `(app)` no tiene `+layout`. El shell y las cargas de la app están en la raíz, que distingue la pantalla de login a mano (`isAuthPage` en `+layout.svelte`, `PUBLIC_PATHS` en `+layout.server.ts`). Por eso `/auth` también consulta `playbackConfig`, y `+error.svelte` se pinta fuera del shell (un 404 dentro de la app pierde la barra lateral y el reproductor).
+
+1. **`routes/+layout.svelte`** se queda con lo global: fuentes, `theme.css`, `layout.css`, favicon, el `<style>` inicial del tema, `animateThemeHue` y `<DialogHost />`. Renderiza `children` sin envoltorio.
+2. **`routes/+layout.server.ts`** desaparece (o queda vacío). Si alguna ruta fuera de `(app)` necesita `user`, lo lee de `locals` en su propio `load`.
+3. **Nuevo `routes/(app)/+layout.server.ts`** con todo lo que hoy hay en la raíz: `getAllowAnonymousListening`, el guard (`loginRedirect` si no hay usuario ni escucha anónima), `accountUrl`, playlists del usuario, me gusta y última pista. Sin `PUBLIC_PATHS`.
+4. **Nuevo `routes/(app)/+layout.svelte`** con el shell: backdrop, `Sidebar`, `MobileHeader`, `TopBar`, `<main>` con el `{#key}`, `Queue`, `PlayerDock`, el modal de crear playlist, la hidratación de `liked` y `player`, la apertura automática de la cola y el atajo de la barra espaciadora. Desaparecen `isAuthPage` y la rama `!data.user && !data.allowAnonymousListening`, porque el guard ya ha redirigido.
+5. **Nuevo `routes/(app)/+error.svelte`** (el contenido del actual) para que los errores dentro de la app se vean con el shell. El `+error.svelte` de la raíz se queda como fallback mínimo para errores fuera del grupo.
+6. **No quitar** los `requireUser`/`optionalUser` de las páginas ni `authedAction`. Los `load` de página se ejecutan en paralelo con los del layout, y las acciones de formulario no ejecutan el `load` del layout, así que el guard del layout no basta.
+
+**Cierre:** `grep -rn "isAuthPage\|PUBLIC_PATHS" src` vacío; `/auth` no llama a la API; un 404 en `/albums/xxx` se ve dentro del shell; prueba manual con sesión, sin sesión y con escucha anónima.
+
+---
+
+## E2 · Carpeta `shell` (S)
+
+Problema: hay dos carpetas `layout` con significados distintos (`components/layout/` es el shell de la app y `components/ui/layout/` son piezas para montar páginas). `AccountMenu` está en `ui/overlay/`, pero solo lo usan `TopBar` y `MobileHeader`.
+
+1. Renombrar `components/layout/` a `components/shell/` (`Sidebar`, `TopBar`, `TabsBar`, `MobileHeader`, `navLinks.ts`).
+2. Mover `components/ui/overlay/AccountMenu.svelte` a `components/shell/AccountMenu.svelte`.
+3. Actualizar imports en `(app)/+layout.svelte` y `components/player/PlayerDock.svelte`.
+
+**Cierre:** `grep -rn "components/layout/\|overlay/AccountMenu" src` vacío.
+
+---
+
+## E3 · Frontera de `components/ui/` (M)
+
+Problema: `ui/` se presenta como el design system, pero cuatro componentes dependen del estado global de la app. `TrackList` y `PlayAllButton` importan `player`. `TrackContextMenu` y `AlbumContextMenu` importan `player`, y `AlbumContextMenu` también importa `$lib/data/albums`. El resto de `ui/media/` son componentes de presentación sin estado (reciben props), y así deben quedarse.
+
+1. **Nueva carpeta `components/music/`** para los componentes que conectan la interfaz con el estado de la app:
+   - `ui/media/TrackList.svelte` → `music/TrackList.svelte`
+   - `ui/media/PlayAllButton.svelte` → `music/PlayAllButton.svelte`
+   - `ui/overlay/TrackContextMenu.svelte` → `music/TrackContextMenu.svelte`
+   - `ui/overlay/AlbumContextMenu.svelte` → `music/AlbumContextMenu.svelte`
+2. **Regla de ESLint:** un bloque con `files: ['src/lib/components/ui/**']` y `no-restricted-imports` que prohíba `$lib/player/*`, `$lib/data/*`, `$lib/server/*`, `$lib/components/music/*`, `$lib/components/shell/*` y `$lib/components/player/*`. Hay que repetir en ese bloque el patrón `../*` del bloque general, porque la configuración de un override sustituye a la del bloque general, no se suma.
+3. Comprobar que la regla pasa sin excepciones. `ui/` puede seguir importando `$lib/state/*` (historial, diálogos), `$lib/utils/*`, `$lib/actions/*`, `$lib/theme/*` y `$lib/types`.
+
+**Cierre:** `npm run lint` en verde; si un componente de `ui/` importa `player`, el lint falla.
+
+---
+
+## E4 · Ubicación de estados (S)
+
+1. `player/liked.svelte.ts` → `state/liked.svelte.ts`. Guarda los me gusta del usuario, no el estado del reproductor, y lo usan `Sidebar`, `TrackInfo`, el layout y las páginas.
+2. `data/recentlyPlayed.ts` → `player/recentlyPlayed.ts`. Solo mezcla `player.recentlyPlayed` con el historial, y hoy es el único archivo de `data/` que depende del reproductor.
+
+**Cierre:** `grep -rn "player/liked\|data/recentlyPlayed" src` vacío; `data/` no importa de `player/`.
+
+---
+
+## E5 · Capa de servidor (S–M)
+
+Problema: `server/api.ts` mezcla el cliente de la API, los guards de sesión, la lectura de formularios y el envoltorio de acciones. Los parsers de `server/forms/` importan `api.ts` solo para usar `formString`/`formFile`.
+
+1. **`server/api.ts`** se queda con el cliente y el manejo de errores: `createApiClient`, `ApiClient`, `apiFor`, `unwrapOrError`, `apiErrorDetail`, `failOnError`, `requireData`.
+2. **Nuevo `server/guards.ts`:** `loginRedirect`, `requireUser`, `optionalUser` (14 imports en `routes/` más `(app)/+layout.server.ts`).
+3. **Nuevo `server/forms/fields.ts`:** `formString`, `formFile`. Los parsers de `forms/` lo importan desde ahí.
+4. **Nueva carpeta `server/actions/`:**
+   - `authedAction.ts` con `authedAction` y `ActionContext`.
+   - `followActions.ts` → `actions/follow.ts`.
+   - `playlistActions.ts` → `actions/playlist.ts`.
+
+**Cierre:** `server/forms/` no importa `server/api`; `api.ts` no importa `redirect` ni `RequestEvent` salvo para `apiFor`.
+
+---
+
+## E6 · Explorar en componentes (M)
+
+Problema: `(app)/explore/+page.svelte` (393 líneas) resuelve tres vistas en una: la rejilla de géneros, la vista de un género y los resultados de búsqueda (mejor resultado y cuatro grupos).
+
+1. Sacar componentes junto a la página (SvelteKit ignora los archivos sin `+` dentro de `routes/`):
+   - `explore/GenreGrid.svelte`: la rejilla de géneros y el estado vacío.
+   - `explore/TopResult.svelte`: el snippet `topResultBody` y `playTopResult`.
+   - `explore/SearchResults.svelte`: los cuatro grupos, `capped`, `showGroup` y el `InfiniteScroll` de pistas.
+2. `+page.svelte` queda como selector de vista: cabecera, chips, mensaje de "sin resultados" y los dos menús contextuales.
+3. El estado compartido (`createPagedList`, `trackMenu`, `albumMenu`) se crea en la página y se pasa por props; los componentes no leen `page.data`.
+
+**Cierre:** `explore/+page.svelte` por debajo de ~150 líneas; ninguna vista nueva supera las ~150.
+
+---
+
+## E7 · Acento fuera del reproductor (S)
+
+Problema: `player.svelte.ts` importa `theme/accent.svelte` y en `#announce` llama a `accent.follow(...)`, así que el estado del reproductor depende del tema visual.
+
+1. Quitar `accent` y `trackCover` de `player.svelte.ts`; `#announce` solo actualiza `mediaSession`.
+2. En `(app)/+layout.svelte`, un `$effect` que siga a `player.currentId` y llame a `accent.follow(trackCover(id, 'small'), () => player.currentId === id)`.
+3. Comprobar que la hidratación de la última pista también actualiza el acento (el efecto depende de `currentId`, así que debería).
+
+**Cierre:** `player/` no importa de `theme/`; el color cambia al cambiar de canción y al cargar la página con una última pista.
+
+---
+
+## E8 · Documentación y restos (S)
+
+1. **`CLAUDE.md`:**
+   - Estructura de carpetas con `components/shell/`, `components/music/`, la regla de frontera de `ui/`, `state/liked.svelte.ts`, `server/guards.ts`, `server/forms/fields.ts` y `server/actions/`.
+   - Documentar lo que falta: `lib/actions/` (`clickOutside`, `onEscape`, `pressable`), `state/toggle.svelte.ts` y `theme/color.ts`.
+   - Corregir la referencia a `$lib/state/navigation.svelte.ts` en "App shell" (ahora es `restoreScroll` en `$lib/state/scroll.ts`) y describir el shell en `(app)/+layout.svelte`.
+   - La skill `musify-web` que cita la introducción no está en `web-player/.claude/skills`: añadirla o quitar la referencia.
+2. **Conversiones fuera de los mappers.** La regla de P5 dice que los `Number(...)` sobre DTOs solo se hacen en `server/mappers.ts`, pero quedan varios en `routes/`:
+   - `(app)/+page.server.ts`: las estadísticas de escucha (nuevo `toListeningStats`, con test) y `totalItemCount` de las playlists.
+   - `(app)/explore/+page.server.ts`: `albumsTotal` y `usersTotal`.
+   - `(app)/user/[id]/+page.server.ts`: `followersCount`.
+   - La carga de playlists del layout (que tras E1 está en `(app)/+layout.server.ts`): `totalItemCount`.
+
+   Los totales pueden salir de `toPage(...).totalItemCount` o de un helper `toCount` en los mappers.
+
+3. **Planes:** marcar `frontend-audit-plan.md` como cerrado (o archivarlo) y dejar este como el plan activo.
+
+**Cierre:** cada ruta citada en `CLAUDE.md` existe; `grep -rn "Number(" src/routes` solo devuelve lecturas de parámetros o formularios.
+
+---
+
+## E9 · Tests de los arreglos y del código con efectos (M)
+
+Los tests se quedan junto al archivo que prueban (`x.ts` + `x.test.ts`); no se crea una carpeta `tests/`. Hoy cubren bien la lógica pura (formatos, mappers, parsers, cola, búsqueda), pero no el código con fetch, estado o tiempo, ni los arreglos de seguridad de P1 y P2, que pueden volver sin que nada falle.
+
+1. **Sesión y guards.**
+   - `server/auth.ts`: `encodeSession` → `decodeSession` devuelve la misma sesión; un token manipulado, cifrado con otra clave o vacío devuelve `null`. Para el secreto, usar `vi.mock('$env/dynamic/private')` con un `SESSION_SECRET` de prueba, no el `.env` local (en CI no existe).
+   - Guards (`requireUser`, `optionalUser`, `loginRedirect`; en `server/guards.ts` tras E5): redirigen a `/auth?returnTo=…` con la ruta y la query codificadas, y dejan pasar cuando toca.
+   - Tras E1, el `load` de `(app)/+layout.server.ts`: redirige sin sesión ni escucha anónima, devuelve datos vacíos en modo anónimo y no llama a la API sin usuario.
+2. **Endpoints `/api` (arreglos de P1).** Llamar al `RequestHandler` con un evento falso y un `fetch` simulado:
+   - `api/likes`: 401 sin token, 400 con `trackId` ausente, vacío o no string, 502 si la API falla.
+   - `api/listens/[id]/progress`: 400 con JSON inválido, con `playedSeconds` negativo, no finito o no numérico; 404 si la API devuelve 404.
+   - `api/tracks`: `pageSize` se limita a `MAX_PAGE_SIZE` y `pageNumber` inválido pasa a 1.
+3. **Rollback de "Me gusta" (`liked.svelte.ts`, arreglo de P2).** Con `fetch` simulado que falla: se revierte solo esa pista y se conservan los cambios hechos mientras tanto en otras. También los casos de dar y quitar el me gusta, y que `hydrate` solo se aplica una vez.
+4. **`ListenTracker`.** Con `vi.useFakeTimers()` y `fetch` simulado:
+   - Suma solo los avances de hasta 2,5 s; un salto mayor (seek) o hacia atrás no cuenta.
+   - `interrupt()` hace que el siguiente `tick` no sume.
+   - Envía a los 30 s y en `flush()`; no reenvía si no hay progreso nuevo.
+   - Si el envío falla, el siguiente `flush()` vuelve a enviar el total.
+   - `begin()` envía lo pendiente de la escucha anterior antes de empezar la nueva.
+5. **`createPagedList`.** Añade la página siguiente sin duplicados, actualiza `hasMore`, ignora un `loadMore` con otro en curso y, si falla, marca `error` y conserva los elementos. `reset` limpia el error.
+6. **`apiErrorDetail`.** Mensajes de `errors` (varios campos, arrays), después `detail`, después `title`, y `undefined` para valores que no son objeto o sin texto.
+
+Fuera de alcance, a propósito: tests de componentes (sobre todo presentación, ya vigilada por `check-tokens`), utilidades triviales (`storage`, `menuPosition`, `navLinks`), `mediaSession`, `progressClock`, `palette` (necesita canvas) y `player.svelte.ts` entero (depende de `<audio>`; su lógica está en `queue.ts`, que ya tiene tests). E2E con Playwright queda para cuando CI pueda levantar el backend y Zitadel.
+
+**Cierre:** cada punto anterior tiene su `*.test.ts` junto al módulo; `npm run test` en verde sin `.env` local; volver a introducir cualquiera de los bugs de P1/P2 cubiertos hace fallar un test.
+
+---
+
+## Registro
+
+| Parte                           | Estado | PR / notas                               |
+| ------------------------------- | ------ | ---------------------------------------- |
+| E1 Layout del grupo (app)       | ✅     |                                          |
+| E2 Carpeta shell                | ✅     |                                          |
+| E3 Frontera de ui/              | ✅     | Regla de ESLint sobre `components/ui/**` |
+| E4 Ubicación de estados         | ✅     |                                          |
+| E5 Capa de servidor             | ✅     |                                          |
+| E6 Explorar en componentes      | ✅     | `+page.svelte` queda en ~180 líneas      |
+| E7 Acento fuera del reproductor | ✅     |                                          |
+| E8 Documentación y restos       | ✅     |                                          |
+| E9 Tests                        | ✅     | 121 tests, sin `.env` local              |
+
+Leyenda: ⬜ pendiente · 🟡 en curso · ✅ hecho.

web-player/docs/paginas.md

@@ -1,128 +1,50 @@
 # Musify, page guide
 
-Living document describing what each page of the web frontend should contain. It works as a map for prioritizing features. The design system (tokens, recipes, components) lives in the `musify-web` skill; here we describe **content and structure**, not styling.
-
-Status legend: ✅ done · 🟡 partial / mockup · ⬜ pending.
-
-> **Note (app redesign):** the `Musify.dc.html` prototype is being ported over (an app with a sidebar, views, and a persistent player with a dynamic accent per track). The marketing landing page was removed. The sections below still describe the older design and are pending an update to match the app views (Home, Search, Library, Upload, Import, Downloads, Playlists). The **player** is already built as components in `$lib/components/player/`, with its theme in `$lib/theme/` (`theme.css` for the palette, `color.ts` for the accent and gradient).
-
-## Home (app) `/` 🟡
-
-- **Hero**: a greeting plus "Your music. No limits." with a color wash taken from the current track's hue.
-- **Quick access, meaning recently played** (`GET /users/{id}/listening-history` merged with `player.recentlyPlayed` via `mergeRecentlyPlayed`). Empty state with an icon and an "Explore" CTA.
-- **Your playlists**: mosaic cards for the user's playlists (sample data for now). Has an empty state.
-- **Resume on load**: the root layout fetches `GET /users/{id}/last-listened-track` and hydrates the player (`player.hydrate`) with it, paused, so the player bar isn't empty on a fresh session. Only applies when nothing is already loaded (won't override an in-progress session).
-
-### Pending backend work (ASP.NET) for Home
-
-- **Playlists by last listen**: add `lastPlayedAt` to the playlist (the schema currently only has `createdAt`/`updatedAt`) and allow sorting `GET /playlists/users/{userId}` by that field (for example `?sort=lastPlayed`), to show "your most recently played" playlists.
-- Tracks will need an **artist** and a **color/hue** (or a real cover to extract one from) for the artwork and the dynamic accent. Right now `TrackApplicationResponse` carries neither artist nor color.
+Living document describing what each page of the web frontend contains. The design system (tokens, recipes, components) lives in the `musify-web` skill and in `CLAUDE.md`; here we describe **content and structure**, not styling.
 
 ## Route structure
 
-Routes are grouped to separate the public experience from the authenticated one (the groups don't change the URL):
+Everything the user sees after signing in lives under the `(app)` group (the group doesn't change the URL). `auth/` and `api/` sit outside it.
 
 ```
 src/routes/
-  (marketing)/        Public, no session required
-    +page.svelte        /            Landing            ✅
-  (app)/              The app experience
-    explore/            /explore     Explore / search    ✅
-    upload/             /upload      Upload music         🟡 mockup
-    library/             /library     Your library          ⬜
-    playlists/            /playlists   Your playlists         ⬜
-      [id]/                /playlists/:id  Playlist detail    ⬜
-  auth  auth/login  auth/logout  auth/callback  Auth (page + endpoints)   ✅
-  api/tracks/[id]/stream             Stream proxy         ✅
+  (app)/
+    +page.svelte                  /                      Home
+    explore/                      /explore               Search and genre discovery
+    liked/                        /liked                 Liked songs
+    library/                      /library               Your uploaded songs
+    upload/                       /upload                Upload a song
+    albums/                       /albums                Your albums
+      [id]/                       /albums/:id            Album detail
+    playlists/                    /playlists             Your playlists
+      [id]/                       /playlists/:id         Playlist detail
+    mixes/[id]/                   /mixes/:id             Generated mix
+    user/[id]/                    /user/:id              Public profile
+      [list=followList]/          /user/:id/followers|following
+  auth/  auth/login  auth/logout  auth/callback         Login screen and OIDC endpoints
+  api/                                                   Same origin JSON endpoints used by the client
 ```
 
-Global components (present on every page): **Navbar**, **Footer**, and **PlayerBar** (the fixed playback bar, shown while something is playing).
+Global chrome on every app page: sidebar (desktop) or tab bar (mobile), top bar with search and account menu, the persistent player dock, and the queue panel.
 
----
+## Pages
 
-## 1. Landing `/` ✅ (marketing)
+- **Home `/`**: a greeting, weekly listening stats, "continue listening" (recently played merged with the in-session history), the featured playlist with its first tracks (play and shuffle load the full list on demand), the user's mixes and playlists. Anonymous visitors are redirected to `/explore`.
+- **Explore `/explore`**: genre tiles when there is no query, otherwise search results grouped by songs, albums, users and playlists with filter chips and counts taken from the API totals. Songs paginate with infinite scroll. Track and album context menus offer play next, add to queue and add to playlist.
+- **Liked `/liked`**: the songs the user liked, newest first, with unlike per row.
+- **Library `/library`**: the songs the user uploaded, with a confirmed delete.
+- **Upload `/upload`**: audio, cover, title, genres (incompatible genres are blocked) and explicit flag. The server reserves presigned URLs, uploads both files and creates the track; processing happens asynchronously in the backend.
+- **Albums `/albums`, `/albums/:id`**: list and create albums. The owner can edit, delete and add or remove tracks from their library.
+- **Playlists `/playlists`, `/playlists/:id`**: list and create playlists. The owner can edit, delete and remove tracks; everyone else gets a read only view.
+- **Mix `/mixes/:id`**: a generated mix with play, shuffle and a track menu.
+- **Profile `/user/:id`**: public playlists, follow button and links to the followers and following lists, which respect the profile's privacy.
+- **Auth `/auth`**: the login screen. Its buttons lead to `/auth/login`, which starts the Zitadel OIDC flow; `?mode=register` opens the sign up variant and `?returnTo=` (local paths only) sends the user back afterwards. `/auth/logout` ends the session and `/auth/callback` creates the encrypted `mf_session` cookie.
 
-The entry page for logged out visitors. Its job is to sell the product and drive people to sign up or explore.
+## Data flow
 
-- **Hero**: a status badge (beta), a title, a subtitle, a primary CTA (Start for free, leading to sign up) and a secondary one (Explore songs).
-- **Features**: three cards covering listening, playlists, and uploading.
-- **Suggested next steps**: a screenshots or demo section, social proof, a short FAQ.
+Each page loads its data in `+page.server.ts` through the typed API client, and normalizes it with the mappers in `$lib/server/mappers.ts` so the client only ever sees the domain types in `$lib/types.ts`. Mutations are form actions built with `authedAction`. Client side pagination goes through the `/api/*` endpoints.
 
-## 2. Login / Auth ✅ (endpoints)
+## Pending backend work
 
-`/auth` is Musify's login screen; its buttons lead to `/auth/login`, which kicks off the Zitadel OIDC flow and redirects. `?mode=register` starts on the sign up variant, and `?returnTo=` sends the user back to the route they came from once they're in. `/auth/logout` ends the session. `/auth/callback` exchanges the code and creates the encrypted `mf_session` cookie. The credentials UI itself is served by Zitadel, not by Musify.
-
-## 3. Explore / Search `/explore` ✅ (app)
-
-Discovery and search over the catalog.
-
-- **Search box**: a text input (`?q=`) that filters by name on the backend.
-- **Results count** and a **track grid** (2 to 4 columns): cover, title, date, and a play/pause button on hover that queues and plays through the global player.
-- **Pagination**: previous/next (`?page=`, 24 per page).
-- **Empty state**: no results, or an empty catalog.
-- **Suggested next steps**: filters (most recent, by user), loading skeletons, a real track cover (the listing API doesn't currently return the image key).
-
-## 4. Upload music `/upload` 🟡 mockup (app)
-
-Adding a new song. The real backend flow, for when it gets wired up:
-
-1. `POST /tracks/upload-urls` returns presigned URLs for cover and audio, plus `intentId`s.
-2. `PUT` each file to its presigned URL (a direct upload to storage).
-3. `POST /tracks` with `title`, `pictureIntentId`, `audioIntentId`.
-4. The backend processes the audio asynchronously (transcoding it to DASH).
-
-What the page needs:
-
-- **Audio zone**: drag and drop or a file picker, showing the file's name and size, with type (audio) and size validation.
-- **Cover**: an image picker with a square preview.
-- **Metadata**: title (required), with room for future fields like a description.
-- **Visible pipeline**: the Upload, Process, Publish steps and their status.
-- **Progress bar** for the upload and the processing state.
-- **States**: empty, file selected, uploading, processing, published, error.
-- **Requires a session** (once wired up: redirect to `/auth?returnTo=/upload`).
-
-## 5. Your library `/library` ⬜ (app)
-
-The authenticated user's personal panel, everything of theirs in one place.
-
-- **Tabs / sections**: "Your songs" (`GET /tracks/users/{userId}`) and "Your playlists" (`GET /playlists/users/{userId}`).
-- **Your songs**: a list with play, plus management actions (delete via `DELETE /tracks/{id}`, add to a playlist).
-- **Your playlists**: a grid of covers with a "Create playlist" button.
-- **Empty state** with a CTA to upload or create.
-- **Requires a session.**
-
-## 6. Playlists `/playlists` ⬜ (app)
-
-A listing of the user's playlists.
-
-- **Grid** of playlists (cover, name, track count), linking to the detail page.
-- **Create playlist**: a modal or page with a name, description, and cover (`POST /playlists`, cover via `POST /playlists/upload-picture`).
-- **Empty state** with a CTA.
-- **Requires a session.**
-
-## 7. Playlist detail `/playlists/[id]` ⬜ (app)
-
-- **Header**: a large cover, name, description, track count, and a "Play all" button.
-- **Track list** (`GET /playlists/{id}/tracks`, paginated): index, title, date, play, and remove from the playlist (`DELETE /playlists/{id}/tracks/{trackId}`).
-- **Owner actions**: edit (`PUT`), delete (`DELETE`) the playlist, reorder (a future addition).
-- **Add tracks**: from explore or the library (`POST /playlists/{id}/tracks/{trackId}`).
-
-## 8. User profile `/user/[id]` ⬜ (future)
-
-A public view of a user: avatar, name, their public songs and playlists (`GET /users/{id}`, `GET /tracks/users/{id}`, `GET /playlists/users/{id}`).
-
----
-
-## Global player (PlayerBar) ✅
-
-A fixed bottom bar, visible while something is playing. Shows track info, transport controls (previous, play/pause, next), a progress bar, and volume control. Queues lists from any grid (`player.playQueue`). Plays DASH through the `/api/tracks/:id/stream` proxy, which requests a manifest and a signed ticket from the backend.
-
-## Available backend (summary)
-
-| Resource  | Endpoints                                                         |
-| --------- | ----------------------------------------------------------------- |
-| Tracks    | list/search, detail, by user, stream, create, delete, upload-urls |
-| Playlists | CRUD, playlist tracks, add/remove track, upload-picture           |
-| Users     | list/search, detail, create                                       |
-
-Typed client in `$lib/server/api.ts` (`openapi-fetch`, ErrorOr style). Use it inside `load`/server actions, never from the client. Types live in `src/lib/api/schema.d.ts`.
+- Sorting playlists by last listen (`lastPlayedAt`) for a "recently played playlists" shelf.
+- An endpoint returning the most listened tracks, to bring back a "popular" section on Home.

web-player/eslint.config.js

@@ -19,6 +19,19 @@ export default ts.config(
 				'error',
 				{ argsIgnorePattern: '^_', varsIgnorePattern: '^_' }
 			],
+			'@typescript-eslint/no-non-null-assertion': 'error',
+			'no-restricted-imports': [
+				'error',
+				{
+					patterns: [
+						{
+							group: ['../*'],
+							message: 'Use $lib/... instead of relative parent imports.'
+						}
+					]
+				}
+			],
+			'svelte/no-unused-props': 'error',
 			'svelte/no-navigation-without-resolve': 'off',
 			'svelte/prefer-svelte-reactivity': 'off'
 		}
@@ -35,6 +48,34 @@ export default ts.config(
 			'@typescript-eslint/no-unused-expressions': 'off'
 		}
 	},
+	{
+		files: ['src/lib/components/ui/**'],
+		rules: {
+			'no-restricted-imports': [
+				'error',
+				{
+					patterns: [
+						{
+							group: ['../*'],
+							message: 'Use $lib/... instead of relative parent imports.'
+						},
+						{
+							group: [
+								'$lib/player/*',
+								'$lib/data/*',
+								'$lib/server/*',
+								'$lib/components/music/*',
+								'$lib/components/shell/*',
+								'$lib/components/player/*'
+							],
+							message:
+								'components/ui is the presentation layer: it cannot depend on app state, data or other component layers.'
+						}
+					]
+				}
+			]
+		}
+	},
 	{
 		ignores: ['build/', '.svelte-kit/', 'static/', 'src/lib/api/schema.d.ts']
 	}

web-player/package-lock.json

@@ -36,7 +36,8 @@
 				"tailwindcss": "^4.3.0",
 				"typescript": "^6.0.3",
 				"typescript-eslint": "^8.64.0",
-				"vite": "^8.0.16"
+				"vite": "^8.0.16",
+				"vitest": "^5.0.1"
 			}
 		},
 		"node_modules/@emnapi/core": {
@@ -51,17 +52,6 @@
 				"tslib": "^2.4.0"
 			}
 		},
-		"node_modules/@emnapi/core/node_modules/@emnapi/wasi-threads": {
-			"version": "1.2.3",
-			"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.3.tgz",
-			"integrity": "sha512-ELEBe8PsLvvJ6QMr0zLt8ffvOHW/dc1m3CEzNMg7aJUv3bMaoDtw2TXyDAwkYBuroxxuHEwhRTLJSe5sya547g==",
-			"license": "MIT",
-			"optional": true,
-			"peer": true,
-			"dependencies": {
-				"tslib": "^2.4.0"
-			}
-		},
 		"node_modules/@emnapi/runtime": {
 			"version": "1.11.3",
 			"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
@@ -74,11 +64,12 @@
 			}
 		},
 		"node_modules/@emnapi/wasi-threads": {
-			"version": "1.2.2",
-			"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz",
-			"integrity": "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==",
+			"version": "1.2.3",
+			"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.3.tgz",
+			"integrity": "sha512-ELEBe8PsLvvJ6QMr0zLt8ffvOHW/dc1m3CEzNMg7aJUv3bMaoDtw2TXyDAwkYBuroxxuHEwhRTLJSe5sya547g==",
 			"license": "MIT",
 			"optional": true,
+			"peer": true,
 			"dependencies": {
 				"tslib": "^2.4.0"
 			}
@@ -343,9 +334,9 @@
 			}
 		},
 		"node_modules/@jridgewell/sourcemap-codec": {
-			"version": "1.5.5",
-			"resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
-			"integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+			"version": "1.6.0",
+			"resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
+			"integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
 			"license": "MIT"
 		},
 		"node_modules/@jridgewell/trace-mapping": {
@@ -368,21 +359,24 @@
 			}
 		},
 		"node_modules/@napi-rs/wasm-runtime": {
-			"version": "1.1.6",
-			"resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.6.tgz",
-			"integrity": "sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==",
+			"version": "1.2.4",
+			"resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.2.4.tgz",
+			"integrity": "sha512-AJxoUD2/15ESHbvpcyjU274nsAPLuOtPHCk0vKJM5pj//Fg/B1FXNWjPnXTT9PymCYYiHo4zPj0ZomXBKhoy7g==",
 			"license": "MIT",
 			"optional": true,
 			"dependencies": {
 				"@tybys/wasm-util": "^0.10.3"
 			},
+			"engines": {
+				"node": "^20.19.0 || ^22.13.0 || >=23.5.0"
+			},
 			"funding": {
 				"type": "github",
 				"url": "https://github.com/sponsors/Brooooooklyn"
 			},
 			"peerDependencies": {
-				"@emnapi/core": "^1.7.1",
-				"@emnapi/runtime": "^1.7.1"
+				"@emnapi/core": "^1.7.1 || ^2.0.0-alpha.4",
+				"@emnapi/runtime": "^1.7.1 || ^2.0.0-alpha.4"
 			}
 		},
 		"node_modules/@oxc-project/types": {
@@ -631,6 +625,16 @@
 				"tslib": "^2.4.0"
 			}
 		},
+		"node_modules/@rolldown/binding-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+			"version": "1.2.2",
+			"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz",
+			"integrity": "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==",
+			"license": "MIT",
+			"optional": true,
+			"dependencies": {
+				"tslib": "^2.4.0"
+			}
+		},
 		"node_modules/@rolldown/binding-win32-arm64-msvc": {
 			"version": "1.1.4",
 			"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.1.4.tgz",
@@ -1556,21 +1560,39 @@
 			}
 		},
 		"node_modules/@tybys/wasm-util": {
-			"version": "0.10.3",
-			"resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",
-			"integrity": "sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==",
+			"version": "0.10.4",
+			"resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.4.tgz",
+			"integrity": "sha512-W3c4gRigFS0T/Ma4qIYF3GDAc5AQdHb1yL5znJT1Zv1YaD9Kitx656wBjvr19qbiosmZT8lWDM5BEMynUqX65A==",
 			"license": "MIT",
 			"optional": true,
 			"dependencies": {
 				"tslib": "^2.4.0"
 			}
 		},
+		"node_modules/@types/chai": {
+			"version": "5.2.3",
+			"resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+			"integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@types/deep-eql": "*",
+				"assertion-error": "^2.0.1"
+			}
+		},
 		"node_modules/@types/cookie": {
 			"version": "0.6.0",
 			"resolved": "https://registry.npmjs.org/@types/cookie/-/cookie-0.6.0.tgz",
 			"integrity": "sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==",
 			"license": "MIT"
 		},
+		"node_modules/@types/deep-eql": {
+			"version": "4.0.2",
+			"resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+			"integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/@types/esrecurse": {
 			"version": "4.3.1",
 			"resolved": "https://registry.npmjs.org/@types/esrecurse/-/esrecurse-4.3.1.tgz",
@@ -1843,6 +1865,64 @@
 				"url": "https://opencollective.com/typescript-eslint"
 			}
 		},
+		"node_modules/@vitest/mocker": {
+			"version": "5.0.1",
+			"resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.0.1.tgz",
+			"integrity": "sha512-6K1DoBNAPGvuOcSsGA4D6x+5zEEff/KmOOP3uetT2TrGpVfI+HRHRnJJfKi5ib/g1vx8IYHQD8s0pbJz8WQI7Q==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@jridgewell/trace-mapping": "0.3.31",
+				"@vitest/spy": "5.0.1",
+				"estree-walker": "^3.0.3",
+				"magic-string": "^1.2.3"
+			},
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			},
+			"peerDependencies": {
+				"msw": "^2.4.9",
+				"vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+			},
+			"peerDependenciesMeta": {
+				"msw": {
+					"optional": true
+				},
+				"vite": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/@vitest/mocker/node_modules/estree-walker": {
+			"version": "3.0.3",
+			"resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+			"integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@types/estree": "^1.0.0"
+			}
+		},
+		"node_modules/@vitest/mocker/node_modules/magic-string": {
+			"version": "1.4.2",
+			"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.2.tgz",
+			"integrity": "sha512-vG+rjFRj1PqdIBozIxAGMjPlOhaVe+GXpbttY/iSK7rGcJRMlwNJO7dcUwmUqkymsFLJiNGI06t4D7Fr7yRC9g==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@jridgewell/sourcemap-codec": "^1.6.0"
+			}
+		},
+		"node_modules/@vitest/spy": {
+			"version": "5.0.1",
+			"resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.0.1.tgz",
+			"integrity": "sha512-rbto/mF/SGERxEgYOek7Xm6B9b+y+mVoo+f4b2LymYO8zM1b7uB5nHuhVMTP2hxdzgxvGiZYGxGIaMvL5y180Q==",
+			"dev": true,
+			"license": "MIT",
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			}
+		},
 		"node_modules/acorn": {
 			"version": "8.17.0",
 			"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
@@ -1891,6 +1971,16 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/assertion-error": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+			"integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=12"
+			}
+		},
 		"node_modules/axobject-query": {
 			"version": "4.1.0",
 			"resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
@@ -1923,6 +2013,16 @@
 				"node": "18 || 20 || >=22"
 			}
 		},
+		"node_modules/chai": {
+			"version": "6.2.2",
+			"resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+			"integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			}
+		},
 		"node_modules/chokidar": {
 			"version": "4.0.3",
 			"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
@@ -2063,6 +2163,13 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/es-module-lexer": {
+			"version": "2.3.2",
+			"resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+			"integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/escape-string-regexp": {
 			"version": "4.0.0",
 			"resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -2323,6 +2430,16 @@
 				"node": ">=0.10.0"
 			}
 		},
+		"node_modules/expect-type": {
+			"version": "1.4.0",
+			"resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+			"integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+			"dev": true,
+			"license": "Apache-2.0",
+			"engines": {
+				"node": ">=12.0.0"
+			}
+		},
 		"node_modules/fast-deep-equal": {
 			"version": "3.1.3",
 			"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -3007,9 +3124,9 @@
 			}
 		},
 		"node_modules/obug": {
-			"version": "2.1.3",
-			"resolved": "https://registry.npmjs.org/obug/-/obug-2.1.3.tgz",
-			"integrity": "sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==",
+			"version": "2.2.1",
+			"resolved": "https://registry.npmjs.org/obug/-/obug-2.2.1.tgz",
+			"integrity": "sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q==",
 			"funding": [
 				"https://github.com/sponsors/sxzz",
 				"https://opencollective.com/debug"
@@ -3130,9 +3247,9 @@
 			"license": "ISC"
 		},
 		"node_modules/picomatch": {
-			"version": "4.0.5",
-			"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
-			"integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
+			"version": "4.0.7",
+			"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
+			"integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
 			"license": "MIT",
 			"engines": {
 				"node": ">=12"
@@ -3573,6 +3690,13 @@
 				"node": ">=8"
 			}
 		},
+		"node_modules/siginfo": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+			"integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+			"dev": true,
+			"license": "ISC"
+		},
 		"node_modules/sirv": {
 			"version": "3.0.2",
 			"resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
@@ -3596,6 +3720,20 @@
 				"node": ">=0.10.0"
 			}
 		},
+		"node_modules/stackback": {
+			"version": "0.0.2",
+			"resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+			"integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+			"dev": true,
+			"license": "MIT"
+		},
+		"node_modules/std-env": {
+			"version": "4.2.0",
+			"resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",
+			"integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",
+			"dev": true,
+			"license": "MIT"
+		},
 		"node_modules/supports-preserve-symlinks-flag": {
 			"version": "1.0.0",
 			"resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz",
@@ -3760,6 +3898,26 @@
 				"url": "https://opencollective.com/webpack"
 			}
 		},
+		"node_modules/tinybench": {
+			"version": "6.1.4",
+			"resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.1.4.tgz",
+			"integrity": "sha512-9APumHG7r4yOk4X4WlkmE71aZcv1gvin1czO3OQ1U9iJcFA5Ja/ygyb0vPOVHTthFozUYs8CLoLUlM8grb2lTQ==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/tinyexec": {
+			"version": "1.3.0",
+			"resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz",
+			"integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			}
+		},
 		"node_modules/tinyglobby": {
 			"version": "0.2.17",
 			"resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
@@ -3976,6 +4134,99 @@
 				}
 			}
 		},
+		"node_modules/vitest": {
+			"version": "5.0.1",
+			"resolved": "https://registry.npmjs.org/vitest/-/vitest-5.0.1.tgz",
+			"integrity": "sha512-iA95lQbKEkvrtTkdAgnWbXfbipWiiWe/hDl2P5tMi6WFwD76G0NxXAGp/M9EOcYupeGJRr6wppMc7CoA41TQjg==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@types/chai": "^5.2.2",
+				"@vitest/mocker": "5.0.1",
+				"chai": "^6.2.2",
+				"es-module-lexer": "^2.3.2",
+				"expect-type": "^1.4.0",
+				"magic-string": "^1.2.3",
+				"obug": "^2.1.4",
+				"picomatch": "^4.0.7",
+				"std-env": "^4.2.0",
+				"tinybench": "6.1.4",
+				"tinyexec": "1.3.0",
+				"tinyglobby": "^0.2.17",
+				"why-is-node-running": "^2.3.0"
+			},
+			"bin": {
+				"vitest": "vitest.mjs"
+			},
+			"engines": {
+				"node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			},
+			"peerDependencies": {
+				"@edge-runtime/vm": "*",
+				"@opentelemetry/api": "^1.9.0",
+				"@types/node": "^22.0.0 || >=24.0.0",
+				"@vitest/browser-playwright": "5.0.1",
+				"@vitest/browser-preview": "5.0.1",
+				"@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0",
+				"@vitest/coverage-istanbul": "5.0.1",
+				"@vitest/coverage-v8": "5.0.1",
+				"@vitest/ui": "5.0.1",
+				"happy-dom": "*",
+				"jsdom": "*",
+				"vite": "^6.4.0 || ^7.0.0 || ^8.0.0"
+			},
+			"peerDependenciesMeta": {
+				"@edge-runtime/vm": {
+					"optional": true
+				},
+				"@opentelemetry/api": {
+					"optional": true
+				},
+				"@types/node": {
+					"optional": true
+				},
+				"@vitest/browser-playwright": {
+					"optional": true
+				},
+				"@vitest/browser-preview": {
+					"optional": true
+				},
+				"@vitest/browser-webdriverio": {
+					"optional": true
+				},
+				"@vitest/coverage-istanbul": {
+					"optional": true
+				},
+				"@vitest/coverage-v8": {
+					"optional": true
+				},
+				"@vitest/ui": {
+					"optional": true
+				},
+				"happy-dom": {
+					"optional": true
+				},
+				"jsdom": {
+					"optional": true
+				},
+				"vite": {
+					"optional": false
+				}
+			}
+		},
+		"node_modules/vitest/node_modules/magic-string": {
+			"version": "1.4.2",
+			"resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.2.tgz",
+			"integrity": "sha512-vG+rjFRj1PqdIBozIxAGMjPlOhaVe+GXpbttY/iSK7rGcJRMlwNJO7dcUwmUqkymsFLJiNGI06t4D7Fr7yRC9g==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"@jridgewell/sourcemap-codec": "^1.6.0"
+			}
+		},
 		"node_modules/which": {
 			"version": "2.0.2",
 			"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -3992,6 +4243,23 @@
 				"node": ">= 8"
 			}
 		},
+		"node_modules/why-is-node-running": {
+			"version": "2.3.0",
+			"resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+			"integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+			"dev": true,
+			"license": "MIT",
+			"dependencies": {
+				"siginfo": "^2.0.0",
+				"stackback": "0.0.2"
+			},
+			"bin": {
+				"why-is-node-running": "cli.js"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/word-wrap": {
 			"version": "1.2.5",
 			"resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",

web-player/package.json

@@ -11,9 +11,11 @@
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"gen:api": "npx -y openapi-typescript@7 http://localhost:5111/openapi/v1.json -o src/lib/api/schema.d.ts",
+		"test": "vitest run",
+		"test:watch": "vitest",
 		"format": "prettier --write .",
 		"lint:tokens": "node scripts/check-tokens.mjs",
-		"lint": "prettier --check . && eslint . && npm run lint:tokens"
+		"lint": "prettier --check . && eslint . && npm run lint:tokens && npm run test"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
@@ -33,7 +35,8 @@
 		"tailwindcss": "^4.3.0",
 		"typescript": "^6.0.3",
 		"typescript-eslint": "^8.64.0",
-		"vite": "^8.0.16"
+		"vite": "^8.0.16",
+		"vitest": "^5.0.1"
 	},
 	"dependencies": {
 		"@fontsource-variable/bricolage-grotesque": "^5.3.0",

web-player/scripts/check-tokens.mjs

@@ -24,12 +24,16 @@ const PAIRED_HW = /\b(?:([a-z0-9-]+:))?h-([\d.]+)\s+\1w-\2\b/g;
 const QUARTER_STEP_SPACING = /\b[a-z-]+-\d+\.(25|75)\b/g;
 const HEX_COLOR = /#[0-9a-fA-F]{3,8}\b/g;
 const RGBA_LITERAL = /\brgba?\(/g;
+const LUCIDE_IMPORT = /import (\w+) from '@lucide\/svelte\/icons\/[\w-]+'/g;
+const ICON_PIXEL_SIZE = /\bsize=\{\d+\}/;
+const ICON_RAW_SIZE = /\bclass="[^"]*\bsize-\d[\w.]*/;
 
 let violations = [];
 
 for (const file of files) {
 	const content = readFileSync(file, 'utf8');
 	const lines = content.split('\n');
+	const icons = [...content.matchAll(LUCIDE_IMPORT)].map((m) => m[1]);
 
 	lines.forEach((line, i) => {
 		const lineNo = i + 1;
@@ -40,6 +44,17 @@ for (const file of files) {
 			}
 		}
 
+		for (const icon of icons) {
+			const tag = line.match(new RegExp(`<${icon}\\s[^>]*`));
+			if (!tag) continue;
+			if (ICON_PIXEL_SIZE.test(tag[0])) {
+				violations.push(`${file}:${lineNo} — icono con size={N}: usa una clase size-icon-*`);
+			}
+			if (ICON_RAW_SIZE.test(tag[0])) {
+				violations.push(`${file}:${lineNo} — icono con size-N: usa una clase size-icon-*`);
+			}
+		}
+
 		for (const match of line.matchAll(RAW_ROUNDED)) {
 			violations.push(`${file}:${lineNo} — radio de Tailwind sin tokenizar: \`${match[0]}\``);
 		}

web-player/src/lib/actions/onEscape.ts

@@ -0,0 +1,17 @@
+import type { Action } from 'svelte/action';
+
+export const onEscape: Action<HTMLElement, (() => void) | undefined> = (_node, handler) => {
+	function onKeydown(event: KeyboardEvent) {
+		if (event.key === 'Escape') handler?.();
+	}
+	window.addEventListener('keydown', onKeydown);
+
+	return {
+		update(next) {
+			handler = next;
+		},
+		destroy() {
+			window.removeEventListener('keydown', onKeydown);
+		}
+	};
+};

web-player/src/lib/api/schema.d.ts

@@ -331,6 +331,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/playlists/{playlistId}/albums/{albumId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Add All The Tracks Of An Album To One Of Your PlayLists, Skipping Those Already In It. */
+        post: operations["AddAlbumToPlayList"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/playlists/{playlistId}/tracks": {
         parameters: {
             query?: never;
@@ -731,6 +748,10 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        AddAlbumToPlayListResponse: {
+            /** Format: int32 */
+            addedCount: number | string;
+        };
         AddPlayListTrackRequest: {
             /** Format: uuid */
             trackId: string;
@@ -940,7 +961,12 @@ export interface components {
             smallImageKeyName: null | string;
             mediumImageKeyName: null | string;
             largeImageKeyName: null | string;
+            ownerUserId: string;
             visibility: components["schemas"]["PlaylistVisibility"];
+            /** Format: int32 */
+            trackCount: number | string;
+            /** Format: double */
+            durationSeconds: number | string;
             /** Format: date-time */
             createdAt: string;
             /** Format: date-time */
@@ -1887,6 +1913,43 @@ export interface operations {
             };
         };
     };
+    AddAlbumToPlayList: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                playlistId: string;
+                albumId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AddAlbumToPlayListResponse"];
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not Found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     AddPlayListTrack: {
         parameters: {
             query?: never;

web-player/src/lib/components/music/AlbumContextMenu.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+	import ListEnd from '@lucide/svelte/icons/list-end';
+	import ListPlus from '@lucide/svelte/icons/list-plus';
+	import { player } from '$lib/player/player.svelte';
+	import { fetchAlbumTracks } from '$lib/data/albums';
+	import type { Menu } from '$lib/state/menu.svelte';
+	import type { Playlist } from '$lib/types';
+	import ContextMenu from '$lib/components/ui/overlay/ContextMenu.svelte';
+
+	interface Props {
+		menu: Menu<string>;
+		playlists: Playlist[];
+	}
+
+	let { menu, playlists }: Props = $props();
+
+	async function playNext(albumId: string) {
+		menu.close();
+		player.playNext(await fetchAlbumTracks(albumId));
+	}
+
+	async function addToQueue(albumId: string) {
+		menu.close();
+		player.appendToQueue(await fetchAlbumTracks(albumId));
+	}
+</script>
+
+{#if menu.state}
+	{@const { target: albumId, x, y, openLeft } = menu.state}
+	<ContextMenu
+		{x}
+		{y}
+		{openLeft}
+		onClose={() => menu.close()}
+		items={[
+			{ icon: ListPlus, label: 'Reproducir a continuación', onclick: () => playNext(albumId) },
+			{ icon: ListEnd, label: 'Añadir a la cola', onclick: () => addToQueue(albumId) }
+		]}
+		playlistAction={{
+			action: '?/addAlbumToPlaylist',
+			fields: { albumId },
+			label: 'Añadir álbum a una playlist'
+		}}
+		{playlists}
+	/>
+{/if}

web-player/src/lib/components/music/PlayAllButton.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+	import { player } from '$lib/player/player.svelte';
+	import { isQueueCurrent, playAllOrToggle } from '$lib/player/actions';
+	import type { Track } from '$lib/types';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
+
+	interface Props {
+		items: Track[];
+		load?: () => Promise<Track[]>;
+		variant?: 'primary' | 'secondary' | 'accent';
+		size?: 'sm' | 'md' | 'lg';
+		idleLabel?: string;
+		activeLabel?: string;
+	}
+
+	let {
+		items,
+		load,
+		variant = 'primary',
+		size = 'sm',
+		idleLabel = 'Reproducir',
+		activeLabel = 'Pausar'
+	}: Props = $props();
+
+	const active = $derived(isQueueCurrent(items) && player.playing);
+
+	async function play() {
+		if (load && !isQueueCurrent(items)) playAllOrToggle(await load());
+		else playAllOrToggle(items);
+	}
+</script>
+
+<Button {variant} {size} onclick={play} disabled={items.length === 0 && !load}>
+	{active ? activeLabel : idleLabel}
+</Button>

web-player/src/lib/components/music/TrackContextMenu.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import ListPlus from '@lucide/svelte/icons/list-plus';
+	import { player } from '$lib/player/player.svelte';
+	import type { Menu } from '$lib/state/menu.svelte';
+	import type { Playlist, Track } from '$lib/types';
+	import ContextMenu from '$lib/components/ui/overlay/ContextMenu.svelte';
+
+	interface Props {
+		menu: Menu<Track>;
+		playlists: Playlist[];
+	}
+
+	let { menu, playlists }: Props = $props();
+
+	function playNext(track: Track) {
+		player.playNext([track]);
+		menu.close();
+	}
+</script>
+
+{#if menu.state}
+	{@const { target: track, x, y, openLeft } = menu.state}
+	<ContextMenu
+		{x}
+		{y}
+		{openLeft}
+		onClose={() => menu.close()}
+		items={[{ icon: ListPlus, label: 'Reproducir a continuación', onclick: () => playNext(track) }]}
+		playlistAction={{
+			action: '?/addTrack',
+			fields: { trackId: track.id },
+			label: 'Añadir a una playlist'
+		}}
+		{playlists}
+	/>
+{/if}

web-player/src/lib/components/music/TrackList.svelte

@@ -1,18 +1,9 @@
 <script lang="ts" module>
+	import type { Track } from '$lib/types';
+
 	export type TrackListColumn = 'added' | 'uploaded' | 'plays';
 
-	export interface TrackListTrack {
-		id: string | number;
-		title: string;
-		artist?: string | null;
-		ownerUserId?: string | number | null;
-		isExplicit?: boolean;
-		explicit?: boolean;
-		duration?: number | string;
-		listensCount?: number | string;
-		addedAt?: string | number;
-		uploadedAt?: string | number;
-	}
+	export type TrackListTrack = Track & { date?: string | number };
 
 	const COLUMN_PRESET: Record<TrackListColumn, { label: string; width: string }> = {
 		added: { label: 'Añadida', width: '124px' },
@@ -34,9 +25,9 @@
 	import { player } from '$lib/player/player.svelte';
 	import { fmtTime, fmtDate } from '$lib/utils/format';
 	import { pressable } from '$lib/actions/pressable';
-	import MediaIdentity from './MediaIdentity.svelte';
-	import EqBars from './EqBars.svelte';
-	import IconButton from '../primitives/IconButton.svelte';
+	import MediaIdentity from '$lib/components/ui/media/MediaIdentity.svelte';
+	import EqBars from '$lib/components/ui/media/EqBars.svelte';
+	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
 
 	interface RowAction {
 		action?: string;
@@ -95,7 +86,7 @@
 		style="--mf-track-cols:{gridColumns}; --mf-track-cols-mobile:{gridColumnsMobile}"
 	>
 		{#if index}
-			<Hash size={16} />
+			<Hash class="size-icon-sm" />
 		{/if}
 		<span>Título</span>
 		{#each columns as column (column)}
@@ -108,7 +99,7 @@
 	</div>
 	<div class="mt-1 flex flex-col gap-0.5" role="list">
 		{#each tracks as track, i (track.id)}
-			{@const active = player.current.id === track.id}
+			{@const active = player.currentId === track.id}
 
 			<div
 				role="listitem"
@@ -138,8 +129,6 @@
 					role="button"
 					tabindex="0"
 					use:pressable={() => onPlay(i)}
-					onclick={(event) => event.stopPropagation()}
-					onkeydown={(event) => event.stopPropagation()}
 					class="flex min-w-0 flex-1 text-left"
 				>
 					<MediaIdentity
@@ -147,7 +136,7 @@
 						title={track.title}
 						artist={track.artist}
 						ownerUserId={track.ownerUserId}
-						explicit={track.isExplicit ?? track.explicit ?? false}
+						explicit={track.explicit}
 						{active}
 					>
 						{#snippet overlay()}
@@ -160,26 +149,18 @@
 				{#each columns as column (column)}
 					<span class="hidden truncate text-center text-xs text-fg-2 tabular-nums sm:block">
 						{#if column === 'plays'}
-							{Number(track.listensCount ?? 0)}
-						{:else if column === 'added' && track.addedAt}
-							{fmtDate(track.addedAt)}
-						{:else if column === 'uploaded' && track.uploadedAt}
-							{fmtDate(track.uploadedAt)}
+							{track.listensCount}
+						{:else if track.date}
+							{fmtDate(track.date)}
 						{/if}
 					</span>
 				{/each}
 				<span class="truncate text-center text-xs text-fg-2 tabular-nums">
-					{fmtTime(Number(track.duration))}
+					{fmtTime(track.duration)}
 				</span>
 				{#if rowAction}
 					{#if rowAction.action}
-						<form
-							method="POST"
-							action={rowAction.action}
-							use:enhance={() =>
-								async ({ update }) =>
-									update()}
-						>
+						<form method="POST" action={rowAction.action} use:enhance>
 							<input type="hidden" name="trackId" value={track.id} />
 							<IconButton type="submit" label={rowAction.label} size="xs" revealOnHover>
 								<rowAction.icon class="size-icon-sm" />

web-player/src/lib/components/player/PlayerBar.svelte

@@ -4,7 +4,7 @@
 	import Slider from '$lib/components/ui/primitives/Slider.svelte';
 	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
 	import { player } from '$lib/player/player.svelte';
-	import { queuePanel } from '$lib/player/queuePanel.svelte';
+	import { queuePanel } from '$lib/state/panels.svelte';
 	import { fmtTime } from '$lib/utils/format';
 	import Volume1 from '@lucide/svelte/icons/volume-1';
 	import Volume2 from '@lucide/svelte/icons/volume-2';
@@ -12,12 +12,12 @@
 	import ListMusic from '@lucide/svelte/icons/list-music';
 
 	function seek(value: number) {
-		if (player.current.duration > 0) player.seekFraction(value / player.current.duration);
+		if (player.duration > 0) player.seekFraction(value / player.duration);
 	}
 </script>
 
 <div
-	class="animate-enter pointer-events-auto flex items-center gap-icon-md px-4 py-3 glass-bar sm:hidden"
+	class="animate-enter pointer-events-auto flex items-center gap-4.5 px-4 py-3 glass-bar sm:hidden"
 >
 	<div class="min-w-0 flex-1">
 		<TrackInfo compact />
@@ -39,20 +39,20 @@
 			</span>
 			<Slider
 				value={player.progress}
-				max={player.current.duration}
+				max={player.duration}
 				label="Barra de progreso"
 				oninput={seek}
 				variant="seek"
 			/>
 			<span class="min-w-8 text-xs text-fg-2 tabular-nums">
-				{fmtTime(player.current.duration)}
+				{fmtTime(player.duration)}
 			</span>
 		</div>
 	</div>
-	<div class="hidden w-(--mf-player-side-w) shrink-0 items-center justify-end gap-3.5 sm:flex">
+	<div class="flex w-(--mf-player-side-w) shrink-0 items-center justify-end gap-3.5">
 		<IconButton
 			label={player.muted ? 'Activar sonido' : 'Silenciar'}
-			tone="plain"
+			plain
 			size="xs"
 			onclick={() => player.toggleMute()}
 		>
@@ -73,7 +73,7 @@
 		/>
 		<IconButton
 			label="Cola de reproducción"
-			tone="plain"
+			plain
 			size="xs"
 			pressed={queuePanel.open}
 			onclick={() => queuePanel.toggle()}

web-player/src/lib/components/player/PlayerDock.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import PlayerBar from './PlayerBar.svelte';
-	import TabsBar from '../layout/TabsBar.svelte';
+	import TabsBar from '$lib/components/shell/TabsBar.svelte';
 	import { player } from '$lib/player/player.svelte';
 	import type { SessionUser } from '$lib/types';
 

web-player/src/lib/components/player/Queue.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { player } from '$lib/player/player.svelte';
-	import { queuePanel } from '$lib/player/queuePanel.svelte';
+	import { queuePanel } from '$lib/state/panels.svelte';
 	import MediaIdentity from '$lib/components/ui/media/MediaIdentity.svelte';
 	import ListRow from '$lib/components/ui/media/ListRow.svelte';
 	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
@@ -43,17 +43,16 @@
 	inert={!queuePanel.open}
 >
 	<aside
-		class="flex min-h-0 shrink-0 flex-col border-l border-hairline px-4 pt-5 pb-5"
-		style="width:var(--mf-queue-w)"
+		class="flex min-h-0 w-(--mf-queue-w) shrink-0 flex-col border-l border-hairline px-4 pt-5 pb-5"
 	>
 		<div class="mb-5 flex items-center justify-between">
 			<h2 class="font-display text-base font-medium tracking-tight text-fg">En cola</h2>
-			<IconButton label="Cerrar cola" tone="plain" size="xs" onclick={() => queuePanel.close()}>
+			<IconButton label="Cerrar cola" plain size="xs" onclick={() => queuePanel.close()}>
 				<X class="size-icon-md" />
 			</IconButton>
 		</div>
 
-		{#if player.current.id}
+		{#if player.current}
 			<p class="mb-3 text-eyebrow text-fg-2">Reproduciendo</p>
 			<div class="mb-6 surface-active rounded-control p-2.5">
 				<MediaIdentity

web-player/src/lib/components/player/TrackInfo.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import { player } from '$lib/player/player.svelte';
-	import { liked } from '$lib/player/liked.svelte';
+	import { liked } from '$lib/state/liked.svelte';
 	import Artwork from '$lib/components/ui/media/Artwork.svelte';
 	import ExplicitBadge from '$lib/components/ui/media/ExplicitBadge.svelte';
 	import ArtistLink from '$lib/components/ui/media/ArtistLink.svelte';
@@ -13,27 +13,20 @@
 
 	let { compact = false }: Props = $props();
 
-	const isLiked = $derived(player.current.id !== '' && liked.isLiked(player.current.id));
+	const current = $derived(player.current);
+	const isLiked = $derived(current !== null && liked.isLiked(current.id));
 
 	function toggleLike() {
-		if (!player.current.id) return;
-		liked.toggle({
-			id: player.current.id,
-			title: player.current.title,
-			artist: player.current.artist,
-			explicit: player.current.explicit,
-			ownerUserId: player.current.ownerUserId,
-			duration: player.current.duration
-		});
+		if (current) liked.toggle(current);
 	}
 </script>
 
 <div class="flex min-w-0 items-center gap-2.5 md:gap-3">
-	{#if player.current.id}
+	{#if current}
 		<Artwork
-			trackIds={[player.current.id]}
+			trackIds={[current.id]}
 			size="sm"
-			alt={player.current.title}
+			alt={current.title}
 			class="shrink-0 md:size-cover-md"
 		/>
 	{:else}
@@ -41,21 +34,21 @@
 	{/if}
 	<div class="min-w-0">
 		<div class="flex min-w-0 items-center gap-1.5">
-			{#if player.current.explicit}
+			{#if current?.explicit}
 				<ExplicitBadge />
 			{/if}
-			<span class="truncate text-sm text-fg">{player.current.title}</span>
+			<span class="truncate text-sm text-fg">{current?.title ?? ''}</span>
 		</div>
 		<ArtistLink
-			name={player.current.artist || '—'}
-			ownerUserId={player.current.ownerUserId}
+			name={current?.artist || '—'}
+			ownerUserId={current?.ownerUserId}
 			class="mt-0.5 text-xs text-fg-2"
 		/>
 	</div>
 	{#if !compact}
 		<IconButton
 			label={isLiked ? 'Quitar de Me gusta' : 'Añadir a Me gusta'}
-			tone="plain"
+			plain
 			size="md"
 			pressed={isLiked}
 			onclick={toggleLike}

web-player/src/lib/components/player/TransportControls.svelte

@@ -26,7 +26,7 @@
 			aria-label="Aleatorio"
 			class="transition-colors hover:text-fg {player.shuffle ? 'text-accent' : 'text-fg-2'}"
 		>
-			<Shuffle class="size-4" />
+			<Shuffle class="size-icon-sm" />
 		</button>
 	{/if}
 
@@ -58,7 +58,7 @@
 			aria-label="Repetir"
 			class="transition-colors hover:text-fg {player.repeat ? 'text-accent' : 'text-fg-2'}"
 		>
-			<Repeat class="size-4" />
+			<Repeat class="size-icon-sm" />
 		</button>
 	{/if}
 </div>

web-player/src/lib/components/shell/AccountMenu.svelte

@@ -6,20 +6,21 @@
 	import Settings from '@lucide/svelte/icons/settings';
 	import Sun from '@lucide/svelte/icons/sun';
 	import Moon from '@lucide/svelte/icons/moon';
-	import MenuItem from './MenuItem.svelte';
-	import GlassMenu from './GlassMenu.svelte';
+	import MenuItem from '$lib/components/ui/overlay/MenuItem.svelte';
+	import GlassMenu from '$lib/components/ui/overlay/GlassMenu.svelte';
 	import { themeMode } from '$lib/theme/mode.svelte';
 	import { clickOutside } from '$lib/actions/clickOutside';
+	import { onEscape } from '$lib/actions/onEscape';
+	import Avatar from '$lib/components/ui/media/Avatar.svelte';
 
 	interface Props {
 		user: SessionUser;
 		accountUrl?: string | null;
 		width?: 'sm' | 'md';
 		extraItems?: Snippet<[{ close: () => void }]>;
-		trigger: Snippet<[{ toggle: () => void; open: boolean }]>;
 	}
 
-	let { user, accountUrl, width = 'sm', extraItems, trigger }: Props = $props();
+	let { user, accountUrl, width = 'sm', extraItems }: Props = $props();
 
 	const WIDTH: Record<'sm' | 'md', string> = { sm: 'w-52', md: 'w-56' };
 
@@ -32,16 +33,23 @@
 	function close() {
 		open = false;
 	}
-
-	function onWindowKeydown(event: KeyboardEvent) {
-		if (event.key === 'Escape') close();
-	}
 </script>
 
-<svelte:window onkeydown={onWindowKeydown} />
-
-<div class="relative" use:clickOutside={close}>
-	{@render trigger({ toggle, open })}
+<div class="relative" use:clickOutside={close} use:onEscape={open ? close : undefined}>
+	<button
+		type="button"
+		onclick={toggle}
+		aria-label="Tu cuenta"
+		aria-expanded={open}
+		class="block shrink-0 rounded-full transition active:scale-95"
+	>
+		<Avatar
+			name={user.name}
+			src={user.picture}
+			size="sm"
+			class="border border-line-strong opacity-90"
+		/>
+	</button>
 
 	{#if open}
 		<GlassMenu
@@ -61,7 +69,7 @@
 			{/if}
 			<MenuItem
 				icon={themeMode.current === 'dark' ? Sun : Moon}
-				label={themeMode.current === 'dark' ? 'Modo blanco' : 'Modo oscuro'}
+				label={themeMode.current === 'dark' ? 'Modo claro' : 'Modo oscuro'}
 				onclick={() => themeMode.toggle()}
 			/>
 			<form method="POST" action="/auth/logout" data-sveltekit-reload>

web-player/src/lib/components/shell/MobileHeader.svelte

@@ -3,11 +3,10 @@
 	import Upload from '@lucide/svelte/icons/upload';
 	import Folder from '@lucide/svelte/icons/folder';
 	import LogIn from '@lucide/svelte/icons/log-in';
-	import MenuItem from '../ui/overlay/MenuItem.svelte';
-	import AccountMenu from '../ui/overlay/AccountMenu.svelte';
-	import Avatar from '../ui/media/Avatar.svelte';
-	import IconButton from '../ui/primitives/IconButton.svelte';
-	import Logo from '../ui/primitives/Logo.svelte';
+	import MenuItem from '$lib/components/ui/overlay/MenuItem.svelte';
+	import AccountMenu from '$lib/components/shell/AccountMenu.svelte';
+	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
+	import Logo from '$lib/components/ui/primitives/Logo.svelte';
 
 	interface Props {
 		user: SessionUser | null;
@@ -26,17 +25,6 @@
 
 	{#if user}
 		<AccountMenu {user} {accountUrl} width="md">
-			{#snippet trigger({ toggle, open })}
-				<button
-					type="button"
-					onclick={toggle}
-					aria-label="Tu cuenta"
-					aria-expanded={open}
-					class="flex items-center rounded-full"
-				>
-					<Avatar name={user.name} src={user.picture} size="sm" />
-				</button>
-			{/snippet}
 			{#snippet extraItems({ close })}
 				<MenuItem icon={Folder} label="Canciones subidas" href="/library" onclick={close} />
 				<MenuItem icon={Upload} label="Subir música" href="/upload" onclick={close} />

web-player/src/lib/components/shell/Sidebar.svelte

@@ -1,38 +1,39 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import { isSectionActive, appNavLinks } from '$lib/state/navigation.svelte';
-	import { liked } from '$lib/player/liked.svelte';
-	import { createPlaylistModal } from '$lib/state/playlists.svelte';
+	import { appNavLinks, isNavActive } from './navLinks';
+	import { playlistCover } from '$lib/utils/hrefs';
+	import { liked } from '$lib/state/liked.svelte';
+	import { createPlaylistModal } from '$lib/state/panels.svelte';
 	import type { SessionUser } from '$lib/types';
-	import ListRow from '../ui/media/ListRow.svelte';
-	import IconButton from '../ui/primitives/IconButton.svelte';
+	import ListRow from '$lib/components/ui/media/ListRow.svelte';
+	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
 	import Plus from '@lucide/svelte/icons/plus';
-	import Logo from '../ui/primitives/Logo.svelte';
+	import Logo from '$lib/components/ui/primitives/Logo.svelte';
+
+	const SIDEBAR_PLAYLISTS_LIMIT = 8;
 
 	interface SidebarPlaylist {
 		id: string;
 		name: string;
-		coverTrackIds: (string | number)[];
+		coverTrackIds: string[];
 		updatedAt: string;
 	}
 
 	interface Props {
 		user: SessionUser | null;
 		playlists: SidebarPlaylist[];
+		playlistCount: number;
 	}
 
-	let { user, playlists }: Props = $props();
+	let { user, playlists, playlistCount }: Props = $props();
 
-	const navLinks = $derived(appNavLinks(user, { playlists: playlists.length, liked: liked.count }));
+	const visiblePlaylists = $derived(playlists.slice(0, SIDEBAR_PLAYLISTS_LIMIT));
 
-	function isActive(href: string) {
-		return isSectionActive(href, page.url.pathname, page.data.section);
-	}
+	const navLinks = $derived(appNavLinks(user, { playlists: playlistCount, liked: liked.count }));
 </script>
 
 <aside
-	class="hidden min-h-0 shrink-0 flex-col border-r border-hairline p-5 lg:flex"
-	style="width:var(--mf-sidebar-w)"
+	class="hidden min-h-0 w-(--mf-sidebar-w) shrink-0 flex-col border-r border-hairline p-5 lg:flex"
 >
 	<a href="/" class="mb-4">
 		<Logo size="sm" />
@@ -40,7 +41,7 @@
 
 	<nav class="flex flex-col gap-1">
 		{#each navLinks as link (link.href)}
-			{@const active = isActive(link.href)}
+			{@const active = isNavActive(link.href)}
 			<a
 				href={link.href}
 				aria-current={active ? 'page' : undefined}
@@ -61,10 +62,10 @@
 		<div class="mx-3 mt-6 mb-3.5 h-px bg-line"></div>
 		<div class="flex items-center justify-between px-3 pb-1.5">
 			<span class="text-eyebrow text-fg-2">Tus playlists</span>
-			{#if playlists.length > 0}
+			{#if visiblePlaylists.length > 0}
 				<IconButton
 					label="Crear playlist"
-					tone="plain"
+					plain
 					size="xs"
 					onclick={() => createPlaylistModal.show()}
 				>
@@ -73,17 +74,15 @@
 			{/if}
 		</div>
 
-		<div class="flex min-h-0 flex-1 flex-col gap-px overflow-y-auto pb-icon-md">
-			{#each playlists as playlist (playlist.id)}
+		<div class="flex min-h-0 flex-1 flex-col gap-px overflow-y-auto pb-4.5">
+			{#each visiblePlaylists as playlist (playlist.id)}
 				{@const active = page.url.pathname === `/playlists/${playlist.id}`}
 				<ListRow
 					href="/playlists/{playlist.id}"
 					{active}
 					size="xs"
 					title={playlist.name}
-					coverSrc="/api/playlists/{playlist.id}/cover?size=small&v={encodeURIComponent(
-						playlist.updatedAt
-					)}"
+					coverSrc={playlistCover(playlist, 'small')}
 					trackIds={playlist.coverTrackIds}
 					class="px-3 py-2"
 				/>
@@ -91,10 +90,10 @@
 				<button
 					type="button"
 					onclick={() => createPlaylistModal.show()}
-					class="flex items-center gap-2 rounded-control px-3 py-2 text-xs text-fg-2 transition-colors hover:bg-hover hover:text-fg-2"
+					class="flex items-center gap-2 rounded-control px-3 py-2 text-xs text-fg-2 transition-colors hover:bg-hover"
 				>
-					<Plus class="size-3.5" />
-					Crear tu primera lista
+					<Plus class="size-icon-xs" />
+					Crear tu primera playlist
 				</button>
 			{/each}
 		</div>

web-player/src/lib/components/shell/TabsBar.svelte

@@ -1,6 +1,5 @@
 <script lang="ts">
-	import { page } from '$app/state';
-	import { isSectionActive, appNavLinks } from '$lib/state/navigation.svelte';
+	import { appNavLinks, isNavActive } from './navLinks';
 	import type { SessionUser } from '$lib/types';
 
 	interface Props {
@@ -11,10 +10,6 @@
 	let { user, class: klass = '' }: Props = $props();
 
 	const links = $derived(appNavLinks(user).filter((link) => link.primary));
-
-	function isActive(href: string) {
-		return isSectionActive(href, page.url.pathname, page.data.section);
-	}
 </script>
 
 <nav
@@ -22,7 +17,7 @@
 	style="padding-bottom:calc(0.4375rem + var(--mf-safe-b))"
 >
 	{#each links as link (link.href)}
-		{@const active = isActive(link.href)}
+		{@const active = isNavActive(link.href)}
 		<a
 			href={link.href}
 			aria-current={active ? 'page' : undefined}
@@ -30,7 +25,7 @@
 				? 'text-fg'
 				: 'text-fg-2'}"
 		>
-			<link.icon class="size-4" />
+			<link.icon class="size-icon-sm" />
 			<span class="text-xs font-medium">{link.label}</span>
 		</a>
 	{/each}

web-player/src/lib/components/shell/TopBar.svelte

@@ -3,14 +3,13 @@
 	import { page } from '$app/state';
 	import type { SessionUser } from '$lib/types';
 	import { SEARCH_DEBOUNCE_MS, SEARCH_MIN_LENGTH } from '$lib/config';
-	import { searchHref } from '$lib/state/navigation.svelte';
+	import { searchHref } from '$lib/utils/hrefs';
 	import Search from '@lucide/svelte/icons/search';
 	import X from '@lucide/svelte/icons/x';
 	import ChevronLeft from '@lucide/svelte/icons/chevron-left';
-	import AccountMenu from '../ui/overlay/AccountMenu.svelte';
-	import Avatar from '../ui/media/Avatar.svelte';
-	import IconButton from '../ui/primitives/IconButton.svelte';
-	import Button from '../ui/primitives/Button.svelte';
+	import AccountMenu from '$lib/components/shell/AccountMenu.svelte';
+	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
 
 	interface Props {
 		user: SessionUser | null;
@@ -54,14 +53,7 @@
 </script>
 
 <header class="hidden items-center gap-3.5 px-6.5 pt-4 pb-3 sm:flex">
-	<IconButton
-		label="Atrás"
-		shape="round"
-		tone="subtle"
-		surface
-		size="xs"
-		onclick={() => history.back()}
-	>
+	<IconButton label="Atrás" shape="round" surface size="xs" onclick={() => history.back()}>
 		<ChevronLeft class="size-icon-sm" />
 	</IconButton>
 
@@ -69,7 +61,7 @@
 		<label
 			class="flex h-9.5 w-full items-center gap-2.5 rounded-control bg-surface-2 px-3.5 transition focus-within:bg-surface-hover"
 		>
-			<Search class="size-4 shrink-0 text-fg-2" />
+			<Search class="size-icon-sm shrink-0 text-fg-2" />
 			<input
 				type="text"
 				bind:this={searchInput}
@@ -85,34 +77,15 @@
 					aria-label="Borrar búsqueda"
 					class="grid size-5 shrink-0 place-items-center rounded-full text-fg-2 transition hover:text-fg"
 				>
-					<X class="size-3.5" />
+					<X class="size-icon-xs" />
 				</button>
 			{/if}
 		</label>
 	</form>
 
-	<div class="flex-1"></div>
-
-	<div class="shrink-0">
+	<div class="ml-auto shrink-0">
 		{#if user}
-			<AccountMenu {user} {accountUrl}>
-				{#snippet trigger({ toggle, open })}
-					<button
-						type="button"
-						onclick={toggle}
-						aria-label="Tu cuenta"
-						aria-expanded={open}
-						class="block shrink-0 rounded-full transition active:scale-95"
-					>
-						<Avatar
-							name={user.name}
-							src={user.picture}
-							size="sm"
-							class="border border-line-strong opacity-90"
-						/>
-					</button>
-				{/snippet}
-			</AccountMenu>
+			<AccountMenu {user} {accountUrl} />
 		{:else}
 			<Button href="/auth/login" reload variant="accent" size="sm" class="shrink-0"
 				>Iniciar sesión</Button

web-player/src/lib/components/shell/navLinks.ts

@@ -0,0 +1,48 @@
+import { page } from '$app/state';
+import type { LucideIcon } from '@lucide/svelte';
+import Home from '@lucide/svelte/icons/house';
+import Compass from '@lucide/svelte/icons/compass';
+import ListMusic from '@lucide/svelte/icons/list-music';
+import Heart from '@lucide/svelte/icons/heart';
+import Disc from '@lucide/svelte/icons/disc-2';
+import Folder from '@lucide/svelte/icons/folder';
+import Upload from '@lucide/svelte/icons/upload';
+import type { SessionUser } from '$lib/types';
+
+export interface AppNavLink {
+	href: string;
+	label: string;
+	icon: LucideIcon;
+	count?: number;
+	primary: boolean;
+}
+
+export interface AppNavCounts {
+	playlists?: number;
+	liked?: number;
+}
+
+export function isNavActive(href: string): boolean {
+	const section: string | null | undefined = page.data.section;
+	if (section !== undefined) return section === href;
+	return href === '/' ? page.url.pathname === '/' : page.url.pathname.startsWith(href);
+}
+
+export function appNavLinks(user: SessionUser | null, counts: AppNavCounts = {}): AppNavLink[] {
+	if (!user) return [{ href: '/explore', label: 'Descubrir', icon: Compass, primary: true }];
+	return [
+		{ href: '/', label: 'Inicio', icon: Home, primary: true },
+		{ href: '/explore', label: 'Descubrir', icon: Compass, primary: true },
+		{
+			href: '/playlists',
+			label: 'Playlists',
+			icon: ListMusic,
+			count: counts.playlists,
+			primary: true
+		},
+		{ href: '/liked', label: 'Me gusta', icon: Heart, count: counts.liked, primary: true },
+		{ href: '/albums', label: 'Mis álbumes', icon: Disc, primary: false },
+		{ href: '/library', label: 'Canciones subidas', icon: Folder, primary: false },
+		{ href: '/upload', label: 'Subir música', icon: Upload, primary: false }
+	];
+}

web-player/src/lib/components/ui/forms/AlbumForm.svelte

@@ -2,10 +2,10 @@
 	import { untrack } from 'svelte';
 	import Disc3 from '@lucide/svelte/icons/disc-3';
 	import CoverForm from './CoverForm.svelte';
-	import Field from '../primitives/Field.svelte';
-	import Input from '../primitives/Input.svelte';
-	import Textarea from '../primitives/Textarea.svelte';
-	import { ALBUM_EARLIEST_YEAR } from '$lib/config';
+	import Field from '$lib/components/ui/primitives/Field.svelte';
+	import Input from '$lib/components/ui/primitives/Input.svelte';
+	import Textarea from '$lib/components/ui/primitives/Textarea.svelte';
+	import { ALBUM_EARLIEST_YEAR, LIMITS } from '$lib/validation';
 
 	interface Props {
 		action: string;
@@ -58,10 +58,13 @@
 >
 	{#snippet fields()}
 		<Field label="Título" for="album-title">
+			{#snippet hint()}
+				<span class="ml-auto tabular-nums">{title.length}/{LIMITS.albumTitle}</span>
+			{/snippet}
 			<Input
 				id="album-title"
 				name="title"
-				maxlength={200}
+				maxlength={LIMITS.albumTitle}
 				required
 				bind:value={title}
 				placeholder={titlePlaceholder}
@@ -85,7 +88,7 @@
 			<Textarea
 				id="album-description"
 				name="description"
-				maxlength={256}
+				maxlength={LIMITS.albumDescription}
 				bind:value={description}
 				placeholder="¿De qué va este álbum?"
 			/>

web-player/src/lib/components/ui/forms/CoverForm.svelte

@@ -3,9 +3,9 @@
 	import { enhance } from '$app/forms';
 	import type { LucideIcon } from '@lucide/svelte';
 	import ImageDropzone from './ImageDropzone.svelte';
-	import Button from '../primitives/Button.svelte';
-	import Field from '../primitives/Field.svelte';
-	import Alert from '../primitives/Alert.svelte';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
+	import Field from '$lib/components/ui/primitives/Field.svelte';
+	import Alert from '$lib/components/ui/primitives/Alert.svelte';
 
 	interface Props {
 		action: string;
@@ -81,10 +81,8 @@
 	<div class="flex items-center justify-between gap-4">
 		{#if helperText}
 			<p class="text-sm text-fg-2">{helperText}</p>
-		{:else}
-			<span></span>
 		{/if}
-		<div class="flex shrink-0 items-center gap-3">
+		<div class="ml-auto flex shrink-0 items-center gap-3">
 			<Button type="button" variant="secondary" onclick={onCancel}>Cancelar</Button>
 			<Button type="submit" disabled={submitting || !canSubmit}>
 				{submitting ? submittingLabel : submitLabel}

web-player/src/lib/components/ui/forms/ImageDropzone.svelte

@@ -37,9 +37,16 @@
 	function onInput(event: Event) {
 		const file = (event.currentTarget as HTMLInputElement).files?.[0];
 		if (!file) return;
+		releasePreview();
 		preview = URL.createObjectURL(file);
 		onselect?.(file);
 	}
+
+	function releasePreview() {
+		if (preview !== '') URL.revokeObjectURL(preview);
+	}
+
+	$effect(() => releasePreview);
 </script>
 
 <label

web-player/src/lib/components/ui/forms/PlaylistForm.svelte

@@ -2,13 +2,12 @@
 	import { untrack } from 'svelte';
 	import Music from '@lucide/svelte/icons/music';
 	import CoverForm from './CoverForm.svelte';
-	import Field from '../primitives/Field.svelte';
-	import Input from '../primitives/Input.svelte';
-	import Textarea from '../primitives/Textarea.svelte';
-	import SegmentedControl from '../primitives/SegmentedControl.svelte';
+	import Field from '$lib/components/ui/primitives/Field.svelte';
+	import Input from '$lib/components/ui/primitives/Input.svelte';
+	import Textarea from '$lib/components/ui/primitives/Textarea.svelte';
+	import SegmentedControl from '$lib/components/ui/primitives/SegmentedControl.svelte';
 
-	const NAME_MAX_LENGTH = 60;
-	const DESCRIPTION_MAX_LENGTH = 300;
+	import { LIMITS } from '$lib/validation';
 
 	interface Props {
 		action: string;
@@ -61,12 +60,12 @@
 		<input type="hidden" name="visibility" value={visibility} />
 		<Field label="Nombre" for="playlist-name">
 			{#snippet hint()}
-				<span class="ml-auto tabular-nums">{name.length}/{NAME_MAX_LENGTH}</span>
+				<span class="ml-auto tabular-nums">{name.length}/{LIMITS.playlistName}</span>
 			{/snippet}
 			<Input
 				id="playlist-name"
 				name="name"
-				maxlength={NAME_MAX_LENGTH}
+				maxlength={LIMITS.playlistName}
 				required
 				bind:value={name}
 				placeholder={namePlaceholder}
@@ -77,7 +76,7 @@
 			<Textarea
 				id="playlist-description"
 				name="description"
-				maxlength={DESCRIPTION_MAX_LENGTH}
+				maxlength={LIMITS.playlistDescription}
 				bind:value={description}
 				placeholder="Para qué sirve esta playlist, cuándo la escuchas…"
 				class="flex-1"

web-player/src/lib/components/ui/media/ArtistLink.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	interface Props {
 		name?: string | null;
-		ownerUserId?: string | number | null;
+		ownerUserId?: string | null;
 		class?: string;
 	}
 
@@ -13,7 +13,7 @@
 		<a
 			href="/user/{ownerUserId}"
 			onclick={(e) => e.stopPropagation()}
-			class="block max-w-full truncate hover:text-fg-2 hover:underline {klass}"
+			class="block max-w-full truncate hover:underline {klass}"
 		>
 			{name}
 		</a>

web-player/src/lib/components/ui/media/Artwork.svelte

@@ -1,15 +1,15 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
+	import { trackCover } from '$lib/utils/hrefs';
 
 	type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'hero' | 'fill';
 
 	interface Props {
 		src?: string | null;
-		trackIds?: (string | number)[];
+		trackIds?: string[];
 		size: Size;
 		shape?: 'auto' | 'round';
 		imageSize?: 'small' | 'medium' | 'large';
-		fallback?: 'music' | 'gradient' | 'none';
 		alt?: string;
 		class?: string;
 		children?: Snippet;
@@ -21,7 +21,6 @@
 		size,
 		shape = 'auto',
 		imageSize,
-		fallback = 'music',
 		alt = '',
 		class: klass = '',
 		children
@@ -63,22 +62,12 @@
 	const resolvedImageSize = $derived(imageSize ?? AUTO_IMAGE_SIZE[size]);
 	const radius = $derived(shape === 'round' ? 'rounded-full' : RADIUS[size]);
 
-	let srcFailed = $state(false);
-	$effect(() => {
-		src;
-		srcFailed = false;
-	});
+	let failedSrc = $state<string | null>(null);
+	let failedSingle = $state<string | null>(null);
 
-	let singleFailed = $state(false);
-	$effect(() => {
-		trackIds[0];
-		singleFailed = false;
-	});
-
-	const showSrc = $derived(!!src && !srcFailed);
+	const showSrc = $derived(!!src && failedSrc !== src);
 	const showMosaic = $derived(!showSrc && trackIds.length >= 4);
 	const singleId = $derived(!showSrc && !showMosaic && trackIds.length > 0 ? trackIds[0] : null);
-	const showSingle = $derived(singleId !== null && !singleFailed);
 </script>
 
 <div class="relative overflow-hidden {DIMENSION[size]} {radius} {klass}">
@@ -89,14 +78,14 @@
 			loading="lazy"
 			decoding="async"
 			fetchpriority="low"
-			onerror={() => (srcFailed = true)}
+			onerror={() => (failedSrc = src ?? null)}
 			class="h-full w-full object-cover"
 		/>
 	{:else if showMosaic}
 		<div class="grid h-full w-full grid-cols-2 grid-rows-2">
 			{#each trackIds.slice(0, 4) as id (id)}
 				<img
-					src="/api/tracks/{id}/cover?size=small"
+					src={trackCover(id, 'small')}
 					alt=""
 					loading="lazy"
 					decoding="async"
@@ -106,17 +95,17 @@
 				/>
 			{/each}
 		</div>
-	{:else if showSingle}
+	{:else if singleId !== null && failedSingle !== singleId}
 		<img
-			src="/api/tracks/{singleId}/cover?size={resolvedImageSize}"
+			src={trackCover(singleId, resolvedImageSize)}
 			{alt}
 			loading="lazy"
 			decoding="async"
 			fetchpriority="low"
-			onerror={() => (singleFailed = true)}
+			onerror={() => (failedSingle = singleId)}
 			class="h-full w-full object-cover"
 		/>
-	{:else if fallback === 'music'}
+	{:else}
 		<div class="grid h-full w-full place-items-center bg-surface">
 			<svg viewBox="0 0 24 24" fill="currentColor" class="h-2/5 w-2/5 text-fg-2">
 				<path
@@ -124,10 +113,6 @@
 				/>
 			</svg>
 		</div>
-	{:else if fallback === 'gradient'}
-		<div class="h-full w-full bg-(image:--mf-cover-grad)"></div>
-	{:else}
-		<div class="h-full w-full bg-surface"></div>
 	{/if}
 	{@render children?.()}
 </div>

web-player/src/lib/components/ui/media/Avatar.svelte

@@ -33,11 +33,7 @@
 			.join('')
 	);
 
-	let failed = $state(false);
-	$effect(() => {
-		src;
-		failed = false;
-	});
+	let failedSrc = $state<string | null>(null);
 </script>
 
 <div
@@ -45,13 +41,13 @@
 		size
 	]} {klass}"
 >
-	{#if src && !failed}
+	{#if src && failedSrc !== src}
 		<img
 			{src}
 			alt=""
 			loading="lazy"
 			decoding="async"
-			onerror={() => (failed = true)}
+			onerror={() => (failedSrc = src ?? null)}
 			class="absolute inset-0 h-full w-full object-cover"
 		/>
 	{:else}

web-player/src/lib/components/ui/media/EqBars.svelte

@@ -1,19 +1,11 @@
 <script lang="ts">
 	interface Props {
-		size?: number;
-		barWidth?: number;
 		paused?: boolean;
 		overlay?: boolean;
 		class?: string;
 	}
 
-	let {
-		size = 13,
-		barWidth = 2,
-		paused = false,
-		overlay = false,
-		class: klass = ''
-	}: Props = $props();
+	let { paused = false, overlay = false, class: klass = '' }: Props = $props();
 
 	const delays = [0, 0.3, 0.6];
 </script>
@@ -30,11 +22,11 @@
 		{/each}
 	</div>
 {:else}
-	<div class="flex items-end justify-center gap-0.5 {klass}" style="height:{size}px">
+	<div class="flex h-3.5 items-end justify-center gap-0.5 {klass}">
 		{#each delays as delay (delay)}
 			<span
-				class="rounded-full bg-accent"
-				style="width:{barWidth}px; height:100%; animation:equalize .9s ease-in-out {delay}s infinite; animation-play-state:{paused
+				class="h-full w-0.5 rounded-full bg-accent"
+				style="animation:equalize .9s ease-in-out {delay}s infinite; animation-play-state:{paused
 					? 'paused'
 					: 'running'}"
 			></span>

web-player/src/lib/components/ui/media/FollowButton.svelte

@@ -1,16 +1,15 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
 	import { enhance } from '$app/forms';
-	import Button from '../primitives/Button.svelte';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
 
 	interface Props {
 		following: boolean;
-		userId?: string;
 		invalidateAll?: boolean;
 		class?: string;
 	}
 
-	let { following: initial, userId, invalidateAll = false, class: klass = '' }: Props = $props();
+	let { following: initial, invalidateAll = false, class: klass = '' }: Props = $props();
 
 	let following = $state(untrack(() => initial));
 	let submitting = $state(false);
@@ -30,9 +29,6 @@
 		};
 	}}
 >
-	{#if userId}
-		<input type="hidden" name="userId" value={userId} />
-	{/if}
 	<Button
 		type="submit"
 		size="sm"

web-player/src/lib/components/ui/media/ListRow.svelte

@@ -12,10 +12,10 @@
 		variant?: 'row' | 'card';
 		title: string;
 		subtitle?: string | null;
-		subtitleHref?: string | number | null;
+		subtitleHref?: string | null;
 		explicit?: boolean;
-		trackId?: string | number;
-		trackIds?: (string | number)[];
+		trackId?: string;
+		trackIds?: string[];
 		coverSrc?: string | null;
 		art?: Snippet;
 		overlay?: Snippet;

web-player/src/lib/components/ui/media/MediaCard.svelte

@@ -8,7 +8,7 @@
 		title: string;
 		subtitle?: string | null;
 		src?: string | null;
-		trackIds?: (string | number)[];
+		trackIds?: string[];
 		onPlay?: (event: MouseEvent) => void;
 		art?: Snippet;
 		oncontextmenu?: (event: MouseEvent) => void;

web-player/src/lib/components/ui/media/MediaIdentity.svelte

@@ -5,11 +5,11 @@
 	import ArtistLink from './ArtistLink.svelte';
 
 	interface Props {
-		trackId?: string | number;
-		trackIds?: (string | number)[];
+		trackId?: string;
+		trackIds?: string[];
 		title: string;
 		artist?: string | null;
-		ownerUserId?: string | number | null;
+		ownerUserId?: string | null;
 		coverSrc?: string | null;
 		size?: 'xs' | 'sm' | 'lg';
 		explicit?: boolean;
@@ -18,7 +18,6 @@
 		class?: string;
 		art?: Snippet;
 		overlay?: Snippet;
-		badge?: Snippet;
 	}
 
 	let {
@@ -34,8 +33,7 @@
 		titleClass = '',
 		class: klass = '',
 		art,
-		overlay,
-		badge
+		overlay
 	}: Props = $props();
 </script>
 
@@ -61,7 +59,6 @@
 			<span class="min-w-0 truncate text-sm {active ? 'text-accent-soft' : 'text-fg'} {titleClass}"
 				>{title}</span
 			>
-			{@render badge?.()}
 		</div>
 		<ArtistLink name={artist} {ownerUserId} class="mt-0.5 text-xs text-fg-2" />
 	</div>

web-player/src/lib/components/ui/overlay/ConfirmDialog.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import Dialog from './Dialog.svelte';
-	import Button from '../primitives/Button.svelte';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
 
 	interface Props {
 		open: boolean;
@@ -9,15 +9,19 @@
 		description: string;
 		confirmLabel: string;
 		action: string;
+		fields?: Record<string, string>;
 	}
 
-	let { open, onClose, title, description, confirmLabel, action }: Props = $props();
+	let { open, onClose, title, description, confirmLabel, action, fields = {} }: Props = $props();
 </script>
 
 <Dialog {open} {onClose} {title} {description}>
 	{#snippet actions()}
 		<Button variant="secondary" onclick={onClose}>Cancelar</Button>
 		<form method="POST" {action}>
+			{#each Object.entries(fields) as [name, value] (name)}
+				<input type="hidden" {name} {value} />
+			{/each}
 			<Button type="submit" variant="danger">{confirmLabel}</Button>
 		</form>
 	{/snippet}

web-player/src/lib/components/ui/overlay/ContextMenu.svelte

@@ -1,27 +1,10 @@
-<script lang="ts" module>
-	import { MENU_WIDTH, SUBMENU_WIDTH } from '$lib/config';
-
-	export interface MenuPosition {
-		x: number;
-		y: number;
-		openLeft: boolean;
-	}
-
-	export function contextMenuPosition(event: MouseEvent): MenuPosition {
-		event.preventDefault();
-		return {
-			x: Math.max(8, Math.min(event.clientX, window.innerWidth - MENU_WIDTH - 8)),
-			y: Math.max(8, Math.min(event.clientY, window.innerHeight - 60)),
-			openLeft: event.clientX + MENU_WIDTH + SUBMENU_WIDTH + 16 > window.innerWidth
-		};
-	}
-</script>
-
 <script lang="ts">
 	import { enhance } from '$app/forms';
+	import { onEscape } from '$lib/actions/onEscape';
+	import { playlistCover } from '$lib/utils/hrefs';
 	import type { LucideIcon } from '@lucide/svelte';
 	import ChevronRight from '@lucide/svelte/icons/chevron-right';
-	import MediaIdentity from '../media/MediaIdentity.svelte';
+	import MediaIdentity from '$lib/components/ui/media/MediaIdentity.svelte';
 	import GlassMenu from './GlassMenu.svelte';
 	import MenuItem from './MenuItem.svelte';
 
@@ -32,21 +15,16 @@
 		onClose: () => void;
 		items: { icon: LucideIcon; label: string; onclick: () => void }[];
 		playlistAction?: { action: string; fields: Record<string, string>; label: string };
-		playlists?: { id: string; name: string }[];
+		playlists?: { id: string; name: string; updatedAt: string }[];
 	}
 
 	let { x, y, openLeft, onClose, items, playlistAction, playlists = [] }: Props = $props();
-
-	function onWindowKeydown(event: KeyboardEvent) {
-		if (event.key === 'Escape') onClose();
-	}
 </script>
 
-<svelte:window onkeydown={onWindowKeydown} />
-
 <div
 	class="fixed inset-0 z-(--z-backdrop)"
 	role="presentation"
+	use:onEscape={onClose}
 	onclick={onClose}
 	oncontextmenu={(e) => {
 		e.preventDefault();
@@ -97,7 +75,7 @@
 								>
 									<MediaIdentity
 										title={playlist.name}
-										coverSrc="/api/playlists/{playlist.id}/cover?size=small"
+										coverSrc={playlistCover(playlist, 'small')}
 										size="xs"
 										titleClass="text-fg-2"
 									/>

web-player/src/lib/components/ui/overlay/DialogHost.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import Dialog from './Dialog.svelte';
-	import Button from '../primitives/Button.svelte';
+	import Button from '$lib/components/ui/primitives/Button.svelte';
 	import { dialog, type DialogAction, type DialogOptions } from '$lib/state/dialog.svelte';
 
 	// Keep the last dialog's content so the exit transition doesn't render an empty panel.

web-player/src/lib/components/ui/overlay/MenuItem.svelte

@@ -28,21 +28,17 @@
 	);
 </script>
 
-{#if href}
-	<a
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<svelte:element
+	this={href ? 'a' : 'button'}
 	{href}
 	{target}
-		rel={target === '_blank' ? 'noopener noreferrer' : undefined}
-		data-sveltekit-reload={reload ? '' : undefined}
+	rel={href && target === '_blank' ? 'noopener noreferrer' : undefined}
+	type={href ? undefined : type}
+	data-sveltekit-reload={href && reload ? '' : undefined}
 	{onclick}
 	class={classes}
-	>
+>
 	<Icon class="size-icon-md shrink-0" />
 	{label}
-	</a>
-{:else}
-	<button {type} {onclick} class={classes}>
-		<Icon class="size-icon-md shrink-0" />
-		{label}
-	</button>
-{/if}
+</svelte:element>

web-player/src/lib/components/ui/overlay/Modal.svelte

@@ -1,9 +1,10 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import X from '@lucide/svelte/icons/x';
-	import IconButton from '../primitives/IconButton.svelte';
+	import IconButton from '$lib/components/ui/primitives/IconButton.svelte';
 	import { fade } from 'svelte/transition';
 	import { pop } from '$lib/utils/transitions';
+	import { onEscape } from '$lib/actions/onEscape';
 
 	interface Props {
 		open: boolean;
@@ -48,12 +49,7 @@
 	}
 
 	function onWindowKeydown(event: KeyboardEvent) {
-		if (!open) return;
-		if (event.key === 'Escape') {
-			onClose();
-			return;
-		}
-		if (event.key !== 'Tab') return;
+		if (!open || event.key !== 'Tab') return;
 		const elements = focusableElements();
 		if (elements.length === 0) return;
 		const first = elements[0];
@@ -79,6 +75,7 @@
 	>
 		<div
 			bind:this={panel}
+			use:onEscape={onClose}
 			transition:pop={{ duration: 200 }}
 			class="glass-panel max-h-[85dvh] w-full glow-drift overflow-y-auto {maxWidth} rounded-panel p-5 outline-none sm:p-6 {panelClass}"
 			role="dialog"
@@ -99,7 +96,7 @@
 						</h2>
 					</div>
 					<IconButton label="Cerrar" onclick={onClose} class="shrink-0">
-						<X class="size-4" />
+						<X class="size-icon-sm" />
 					</IconButton>
 				</div>
 			{/if}

web-player/src/lib/components/ui/primitives/BackLink.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import ArrowLeft from '@lucide/svelte/icons/arrow-left';
-	import { previousPage } from '$lib/state/navigation.svelte';
+	import { previousPage } from '$lib/state/history.svelte';
 
 	interface Props {
 		href: string;

web-player/src/lib/components/ui/primitives/Button.svelte

@@ -28,13 +28,13 @@
 		children
 	}: Props = $props();
 
-	const sizes = {
+	const SIZE = {
 		sm: 'rounded-control px-4 py-2 text-xs',
 		md: 'rounded-btn-sm px-4.5 py-2.5 text-control-sm',
 		lg: 'rounded-btn px-6 py-3.5 text-sm'
 	};
 
-	const variants = {
+	const VARIANT = {
 		primary: 'bg-cta-strong text-ink hover:bg-cta-strong-hover',
 		secondary: 'bg-btn text-fg hover:bg-btn-hover',
 		accent: 'surface-active text-accent-soft hover:surface-active-hover',
@@ -42,19 +42,22 @@
 	};
 
 	const classes = $derived(
-		`inline-flex items-center justify-center gap-2 font-medium btn-transition focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-bg focus-visible:outline-none disabled:opacity-40 ${sizes[size]} ${variants[variant]} ${klass}`
+		`inline-flex items-center justify-center gap-2 font-medium btn-transition focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-bg disabled:opacity-40 ${SIZE[size]} ${VARIANT[variant]} ${klass}`
 	);
 </script>
 
-{#if href}
-	<a {href} data-sveltekit-reload={reload ? '' : undefined} class={classes}>
-		{@render children()}
-	</a>
-{:else}
-	<button {type} disabled={disabled || loading} {onclick} class={classes}>
-		{#if loading}
-			<LoaderCircle class="size-4 animate-spin" />
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<svelte:element
+	this={href ? 'a' : 'button'}
+	{href}
+	type={href ? undefined : type}
+	disabled={href ? undefined : disabled || loading}
+	data-sveltekit-reload={href && reload ? '' : undefined}
+	{onclick}
+	class={classes}
+>
+	{#if loading && !href}
+		<LoaderCircle class="size-icon-sm animate-spin" />
 	{/if}
 	{@render children()}
-	</button>
-{/if}
+</svelte:element>

web-player/src/lib/components/ui/primitives/Checkbox.svelte

@@ -21,7 +21,7 @@
 			class="peer size-5 cursor-pointer appearance-none rounded-tag border border-line bg-surface transition checked:border-accent-soft checked:bg-accent-soft focus-visible:border-accent/60 focus-visible:outline-none"
 		/>
 		<Check
-			class="pointer-events-none absolute size-3.5 text-ink opacity-0 transition peer-checked:opacity-100"
+			class="pointer-events-none absolute size-icon-xs text-ink opacity-0 transition peer-checked:opacity-100"
 		/>
 	</span>
 	<span class="cursor-pointer">{@render children()}</span>

web-player/src/lib/components/ui/primitives/Chip.svelte

@@ -14,22 +14,24 @@
 
 	const classes = $derived(
 		href
-			? 'rounded-full border border-line-strong px-3.5 py-2 text-xs text-fg-2 transition-colors hover:bg-hover hover:text-fg'
-			: `flex items-center gap-2 rounded-full px-3.5 py-2 text-xs font-medium transition ${
+			? 'focus-ring rounded-full border border-line-strong px-3.5 py-2 text-xs text-fg-2 transition-colors hover:bg-hover hover:text-fg'
+			: `focus-ring flex items-center gap-2 rounded-full px-3.5 py-2 text-xs font-medium transition ${
 					selected ? 'bg-cta-strong text-ink' : 'bg-btn text-fg-2 hover:bg-btn-hover hover:text-fg'
 				} ${disabled ? 'cursor-not-allowed opacity-40' : ''}`
 	);
 </script>
 
-{#snippet content()}
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<svelte:element
+	this={href ? 'a' : 'button'}
+	{href}
+	type={href ? undefined : 'button'}
+	disabled={href ? undefined : disabled}
+	onclick={href ? undefined : onclick}
+	class={classes}
+>
 	{@render children()}
 	{#if count !== undefined}
 		<span class="tabular-nums {selected ? 'opacity-55' : 'text-fg-2'}">{count}</span>
 	{/if}
-{/snippet}
-
-{#if href}
-	<a {href} class={classes}>{@render content()}</a>
-{:else}
-	<button type="button" {onclick} {disabled} class={classes}>{@render content()}</button>
-{/if}
+</svelte:element>

web-player/src/lib/components/ui/primitives/IconButton.svelte

@@ -6,7 +6,7 @@
 		type?: 'button' | 'submit';
 		size?: 'xs' | 'sm' | 'md' | 'lg';
 		shape?: 'square' | 'round';
-		tone?: 'muted' | 'subtle' | 'plain';
+		plain?: boolean;
 		pressed?: boolean;
 		surface?: boolean;
 		revealOnHover?: boolean;
@@ -22,7 +22,7 @@
 		type = 'button',
 		size = 'sm',
 		shape = 'square',
-		tone = 'muted',
+		plain = false,
 		pressed,
 		surface = false,
 		revealOnHover = false,
@@ -40,35 +40,28 @@
 		lg: 'size-10'
 	};
 
-	const TEXT: Record<'muted' | 'subtle' | 'plain', string> = {
-		muted: 'text-fg-2 hover:text-fg',
-		subtle: 'text-fg-2 hover:text-fg',
-		plain: 'text-fg-2 hover:text-fg'
-	};
-
 	const background = $derived(
-		surface ? 'bg-surface-2 hover:bg-surface-hover' : tone === 'plain' ? '' : 'hover:bg-hover'
+		surface ? 'bg-surface-2 hover:bg-surface-hover' : plain ? '' : 'hover:bg-hover'
 	);
 
 	const classes = $derived(
-		`grid place-items-center transition focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none ${SIZE[size]} ${shape === 'round' ? 'rounded-full' : 'rounded-control'} ${pressed ? 'text-accent' : TEXT[tone]} ${background} ${
+		`grid place-items-center transition focus-ring ${SIZE[size]} ${shape === 'round' ? 'rounded-full' : 'rounded-control'} ${pressed ? 'text-accent' : 'text-fg-2 hover:text-fg'} ${background} ${
 			revealOnHover ? 'sm:opacity-0 sm:group-hover:opacity-100 sm:focus-visible:opacity-100' : ''
 		} ${klass}`
 	);
 </script>
 
-{#if href}
-	<a
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<svelte:element
+	this={href ? 'a' : 'button'}
 	{href}
-		data-sveltekit-reload={reload ? '' : undefined}
+	type={href ? undefined : type}
+	data-sveltekit-reload={href && reload ? '' : undefined}
 	aria-label={label}
+	aria-pressed={href ? undefined : pressed}
 	title={label}
+	{onclick}
 	class={classes}
-	>
+>
 	{@render children()}
-	</a>
-{:else}
-	<button {type} {onclick} aria-label={label} title={label} aria-pressed={pressed} class={classes}>
-		{@render children()}
-	</button>
-{/if}
+</svelte:element>

web-player/src/lib/components/ui/primitives/InfiniteScroll.svelte

@@ -1,15 +1,23 @@
 <script lang="ts">
 	import LoaderCircle from '@lucide/svelte/icons/loader-circle';
+	import Button from './Button.svelte';
 	import { INFINITE_SCROLL_ROOT_MARGIN } from '$lib/config';
 
 	interface Props {
 		onLoadMore: () => void;
 		hasMore: boolean;
 		loading: boolean;
+		error?: boolean;
 		rootMargin?: string;
 	}
 
-	let { onLoadMore, hasMore, loading, rootMargin = INFINITE_SCROLL_ROOT_MARGIN }: Props = $props();
+	let {
+		onLoadMore,
+		hasMore,
+		loading,
+		error = false,
+		rootMargin = INFINITE_SCROLL_ROOT_MARGIN
+	}: Props = $props();
 
 	let sentinel = $state<HTMLDivElement>();
 	let visible = $state(false);
@@ -28,12 +36,17 @@
 	});
 
 	$effect(() => {
-		if (visible && hasMore && !loading) onLoadMore();
+		if (visible && hasMore && !loading && !error) onLoadMore();
 	});
 </script>
 
 <div bind:this={sentinel} class="flex min-h-12 items-center justify-center py-8">
 	{#if loading}
-		<LoaderCircle class="size-5 animate-spin text-fg-2" />
+		<LoaderCircle class="size-icon-lg animate-spin text-fg-2" />
+	{:else if error}
+		<div class="flex items-center gap-3 text-sm text-fg-2">
+			No se pudo cargar más.
+			<Button variant="secondary" size="sm" onclick={onLoadMore}>Reintentar</Button>
+		</div>
 	{/if}
 </div>

web-player/src/lib/components/ui/primitives/SegmentedControl.svelte

@@ -26,7 +26,7 @@
 			class="relative z-(--z-raised) flex-1 px-4 py-1.5 text-center text-xs font-medium transition-colors {value ===
 			option.value
 				? 'text-ink'
-				: 'text-fg-2 hover:text-fg-2'}"
+				: 'text-fg-2'}"
 		>
 			{option.label}
 		</button>

web-player/src/lib/config.ts

@@ -1,19 +1,21 @@
 export const EXPLORE_PAGE_SIZE = 27;
+export const MAX_PAGE_SIZE = 100;
 export const SEARCH_DEBOUNCE_MS = 450;
 export const SEARCH_MIN_LENGTH = 2;
 export const INFINITE_SCROLL_ROOT_MARGIN = '300px';
 export const ALBUMS_PAGE_SIZE = 50;
 export const ALBUM_TRACKS_PAGE_SIZE = 200;
-export const ALBUM_EARLIEST_YEAR = 1877;
+export const PLAYLIST_TRACKS_PAGE_SIZE = 200;
 export const LIBRARY_PICKER_PAGE_SIZE = 50;
+export const LIBRARY_PAGE_SIZE = 50;
+export const PLAYLISTS_PAGE_SIZE = 50;
+export const PROFILE_PLAYLISTS_PAGE_SIZE = 50;
 export const EXPLORE_ALBUMS_PAGE_SIZE = 10;
 export const EXPLORE_ALBUMS_LIMIT = 18;
-export const HOME_LATEST_PAGE_SIZE = 10;
 export const HOME_MIXES_LIMIT = 6;
 export const HOME_SHELF_LIMIT = 6;
 export const HOME_CONTINUE_LIMIT = 10;
 export const HOME_SPOTLIGHT_TRACKS_LIMIT = 5;
-export const HOME_POPULAR_MAX = 8;
 export const PLAYLIST_PICKER_PAGE_SIZE = 50;
 export const LIKED_TRACKS_PAGE_SIZE = 500;
 export const EXPLORE_USERS_LIMIT = 12;

web-player/src/lib/data/albums.ts

@@ -1,8 +1,12 @@
-import { toQueueItems, type ApiTrackLike, type QueueItem } from '$lib/player/player.svelte';
+import type { Paged, Track } from '$lib/types';
 
-export async function fetchAlbumQueueItems(albumId: string): Promise<QueueItem[]> {
-	const res = await fetch(`/api/albums/${albumId}/tracks`);
+async function fetchTracks(url: string): Promise<Track[]> {
+	const res = await fetch(url);
 	if (!res.ok) return [];
-	const data = (await res.json()) as { items: ApiTrackLike[] };
-	return toQueueItems(data.items ?? []);
+	return ((await res.json()) as Paged<Track>).items;
 }
+
+export const fetchAlbumTracks = (albumId: string) => fetchTracks(`/api/albums/${albumId}/tracks`);
+
+export const fetchPlaylistTracks = (playlistId: string) =>
+	fetchTracks(`/api/playlists/${playlistId}/tracks`);

web-player/src/lib/data/genres.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { findConflict, genreHue } from './genres';
+
+describe('genreHue', () => {
+	it('is stable and within 0-359', () => {
+		for (const genre of ['rock', 'something-unknown', 'ñandú']) {
+			const hue = genreHue(genre);
+			expect(hue).toBe(genreHue(genre));
+			expect(hue).toBeGreaterThanOrEqual(0);
+			expect(hue).toBeLessThan(360);
+		}
+	});
+});
+
+describe('findConflict', () => {
+	const options = [
+		{ genre: 'a', incompatibleWith: ['b'] },
+		{ genre: 'b', incompatibleWith: ['a'] },
+		{ genre: 'c', incompatibleWith: [] }
+	];
+	it('returns the first incompatible pair', () => {
+		expect(findConflict(['c', 'a', 'b'], options)).toEqual(['a', 'b']);
+	});
+	it('returns undefined when compatible or unknown', () => {
+		expect(findConflict(['a', 'c'], options)).toBeUndefined();
+		expect(findConflict(['x', 'y'], options)).toBeUndefined();
+	});
+});

web-player/src/lib/data/mixes.ts

@@ -1,19 +0,0 @@
-import type { components } from '$lib/api/schema';
-import type { ApiTrackLike } from '$lib/player/player.svelte';
-
-export type Mix = components['schemas']['MixApplicationResponse'];
-export type MixItem = components['schemas']['MixItemApplicationResponse'];
-
-export function mixItemKey(item: MixItem): string {
-	return `mf:${item.trackId}`;
-}
-
-export function mixItemTrack(item: MixItem): ApiTrackLike {
-	return {
-		id: item.trackId,
-		title: item.title,
-		artist: item.artist,
-		duration: item.durationSeconds,
-		listensCount: item.listensCount
-	};
-}

web-player/src/lib/data/recentlyPlayed.ts

@@ -1,22 +0,0 @@
-import { player, toQueueItems, type ApiTrackLike, type QueueItem } from '$lib/player/player.svelte';
-
-export function mergeRecentlyPlayed(history: ApiTrackLike[], limit: number): QueueItem[] {
-	const seen = new Set<string>();
-	const merged: QueueItem[] = [];
-
-	for (const t of player.recentlyPlayed) {
-		const id = String(t.id);
-		if (seen.has(id)) continue;
-		seen.add(id);
-		merged.push({ ...t, id });
-	}
-
-	for (const item of toQueueItems(history)) {
-		const id = String(item.id);
-		if (seen.has(id)) continue;
-		seen.add(id);
-		merged.push({ ...item, id });
-	}
-
-	return merged.slice(0, limit);
-}

web-player/src/lib/data/search.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { findTopResult, searchChips } from './search';
+
+const empty = { tracks: [], albums: [], playlists: [], users: [] };
+
+describe('findTopResult', () => {
+	it('prefers prefix matches by kind: user, track, album, playlist', () => {
+		const result = findTopResult({
+			query: 'Ab',
+			users: [{ name: 'Zed' }, { name: 'abel' }],
+			tracks: [{ title: 'Abc' }],
+			albums: [{ title: 'Abd' }],
+			playlists: [{ name: 'Abe' }]
+		});
+		expect(result).toEqual({ kind: 'user', user: { name: 'abel' } });
+	});
+	it('matches case-insensitively and ignores surrounding spaces', () => {
+		const result = findTopResult({ ...empty, query: '  SO ', tracks: [{ title: 'song' }] });
+		expect(result).toEqual({ kind: 'track', track: { title: 'song' } });
+	});
+	it('falls back to the first available result', () => {
+		const result = findTopResult({ ...empty, query: 'zzz', albums: [{ title: 'Other' }] });
+		expect(result).toEqual({ kind: 'album', album: { title: 'Other' } });
+	});
+	it('returns null without results', () => {
+		expect(findTopResult({ ...empty, query: 'x' })).toBeNull();
+	});
+});
+
+describe('searchChips', () => {
+	it('adds an "all" chip with the total', () => {
+		const chips = searchChips({ tracks: 3, albums: 2, playlists: 0, users: 1 });
+		expect(chips.map((chip) => [chip.filter, chip.count])).toEqual([
+			['all', 6],
+			['tracks', 3],
+			['albums', 2],
+			['playlists', 0],
+			['users', 1]
+		]);
+		expect(chips[0].label).toBe('Todo');
+	});
+});

web-player/src/lib/data/search.ts

@@ -1,38 +1,40 @@
-export const SEARCH_FILTERS = ['Todo', 'Canciones', 'Álbumes', 'Playlists', 'Usuarios'] as const;
-export type SearchFilter = (typeof SEARCH_FILTERS)[number];
+export const SEARCH_KINDS = ['tracks', 'albums', 'playlists', 'users'] as const;
+export type SearchKind = (typeof SEARCH_KINDS)[number];
+export type SearchFilter = 'all' | SearchKind;
 export const SEARCH_GROUP_PREVIEW = 4;
 
-export function showGroup(filter: SearchFilter, label: Exclude<SearchFilter, 'Todo'>) {
-	return filter === 'Todo' || filter === label;
+export const SEARCH_LABELS: Record<SearchFilter, string> = {
+	all: 'Todo',
+	tracks: 'Canciones',
+	albums: 'Álbumes',
+	playlists: 'Playlists',
+	users: 'Usuarios'
+};
+
+export function showGroup(filter: SearchFilter, kind: SearchKind) {
+	return filter === 'all' || filter === kind;
 }
 
 export function capped<T>(filter: SearchFilter, list: T[]) {
-	return filter === 'Todo' ? list.slice(0, SEARCH_GROUP_PREVIEW) : list;
+	return filter === 'all' ? list.slice(0, SEARCH_GROUP_PREVIEW) : list;
 }
 
 export function matchPlaylists<T extends { name: string }>(playlists: T[], query: string): T[] {
 	return query ? playlists.filter((p) => p.name.toLowerCase().includes(query.toLowerCase())) : [];
 }
 
-export function searchCounts(counts: {
-	tracks: number;
-	albums: number;
-	playlists: number;
-	users: number;
-}) {
-	return {
-		Canciones: counts.tracks,
-		Álbumes: counts.albums,
-		Playlists: counts.playlists,
-		Usuarios: counts.users
-	};
+export type SearchCounts = Record<SearchKind, number>;
+
+export function searchTotal(counts: SearchCounts): number {
+	return SEARCH_KINDS.reduce((sum, kind) => sum + counts[kind], 0);
 }
 
-export function searchChips(counts: ReturnType<typeof searchCounts>) {
-	const total = counts.Canciones + counts.Álbumes + counts.Playlists + counts.Usuarios;
-	return SEARCH_FILTERS.map((label) => ({
-		label,
-		count: label === 'Todo' ? total : counts[label]
+export function searchChips(counts: SearchCounts) {
+	const filters: SearchFilter[] = ['all', ...SEARCH_KINDS];
+	return filters.map((filter) => ({
+		filter,
+		label: SEARCH_LABELS[filter],
+		count: filter === 'all' ? searchTotal(counts) : counts[filter]
 	}));
 }
 

web-player/src/lib/player/actions.ts

@@ -0,0 +1,18 @@
+import { shuffle } from '$lib/utils/collections';
+import type { Track } from '$lib/types';
+import { player } from './player.svelte';
+
+export function isQueueCurrent(items: { id: string }[]): boolean {
+	return items.some((item) => item.id === player.currentId);
+}
+
+export function playAllOrToggle(items: Track[]) {
+	if (items.length === 0) return;
+	if (isQueueCurrent(items)) player.toggle();
+	else player.playQueue(items, 0);
+}
+
+export function playShuffled(items: Track[]) {
+	if (items.length === 0) return;
+	player.playQueue(shuffle(items), 0);
+}

web-player/src/lib/player/liked.svelte.ts

@@ -1,74 +0,0 @@
-import { toQueueItems, type ApiTrackLike } from './player.svelte';
-
-export interface LikedTrack {
-	id: string;
-	title: string;
-	artist?: string;
-	explicit?: boolean;
-	ownerUserId?: string | number | null;
-	listensCount?: number | string;
-	duration?: number | string;
-	likedAt: number;
-}
-
-type LikeToggleInput = {
-	id: string | number;
-	title: string;
-	artist?: string;
-	explicit?: boolean;
-	ownerUserId?: string | number | null;
-	duration?: number | string;
-};
-
-class LikedStore {
-	entries = $state<Record<string, LikedTrack>>({});
-	private hydrated = false;
-
-	count = $derived(Object.keys(this.entries).length);
-	list = $derived(Object.values(this.entries).sort((a, b) => b.likedAt - a.likedAt));
-
-	hydrate(tracks: (ApiTrackLike & { createdAt: string; duration: number | string })[]) {
-		if (this.hydrated) return;
-		this.hydrated = true;
-
-		const items = toQueueItems(tracks);
-		const next: Record<string, LikedTrack> = {};
-		items.forEach((item, i) => {
-			const id = String(item.id);
-			next[id] = {
-				...item,
-				id,
-				duration: tracks[i].duration,
-				likedAt: new Date(tracks[i].createdAt).getTime()
-			};
-		});
-		this.entries = next;
-	}
-
-	isLiked(id: string | number): boolean {
-		return String(id) in this.entries;
-	}
-
-	async toggle(track: LikeToggleInput) {
-		const id = String(track.id);
-		const before = this.entries;
-		const wasLiked = id in before;
-		const next = { ...before };
-		if (wasLiked) delete next[id];
-		else next[id] = { ...track, id, likedAt: Date.now() };
-		this.entries = next;
-
-		try {
-			const res = await fetch('/api/likes', {
-				method: 'POST',
-				headers: { 'content-type': 'application/json' },
-				body: JSON.stringify({ trackId: id })
-			});
-			if (!res.ok) throw new Error('Failed to toggle like');
-		} catch {
-			this.entries = before;
-		}
-	}
-}
-
-export const liked = new LikedStore();

web-player/src/lib/player/listenTracker.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ListenTracker } from './listenTracker';
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function sentSeconds(call: number): number {
+	const init = fetchMock.mock.calls[call][1] as RequestInit;
+	return JSON.parse(init.body as string).playedSeconds;
+}
+
+beforeEach(() => {
+	vi.useFakeTimers();
+	fetchMock = vi.fn().mockResolvedValue({ ok: true });
+	vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+	vi.unstubAllGlobals();
+});
+
+function startedTracker(id = 'l1') {
+	const tracker = new ListenTracker();
+	tracker.begin(id);
+	tracker.tick(0);
+	return tracker;
+}
+
+describe('ListenTracker', () => {
+	it('sums small forward advances', () => {
+		const tracker = startedTracker();
+		tracker.tick(1);
+		tracker.tick(2);
+		tracker.flush();
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		expect(sentSeconds(0)).toBe(2);
+	});
+
+	it('ignores seeks forward and backwards', () => {
+		const tracker = startedTracker();
+		tracker.tick(1);
+		tracker.tick(60);
+		tracker.tick(10);
+		tracker.tick(11);
+		tracker.flush();
+		expect(sentSeconds(0)).toBe(2);
+	});
+
+	it('does not count the tick after interrupt()', () => {
+		const tracker = startedTracker();
+		tracker.tick(1);
+		tracker.interrupt();
+		tracker.tick(2);
+		tracker.tick(3);
+		tracker.flush();
+		expect(sentSeconds(0)).toBe(2);
+	});
+
+	it('sends after 30 seconds of wall time', () => {
+		const tracker = startedTracker();
+		tracker.tick(1);
+		expect(fetchMock).not.toHaveBeenCalled();
+		vi.advanceTimersByTime(30_000);
+		tracker.tick(2);
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		expect(sentSeconds(0)).toBe(2);
+	});
+
+	it('does not resend without new progress', () => {
+		const tracker = startedTracker();
+		tracker.tick(1);
+		tracker.flush();
+		tracker.flush();
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		tracker.tick(2);
+		tracker.flush();
+		expect(fetchMock).toHaveBeenCalledTimes(2);
+		expect(sentSeconds(1)).toBe(2);
+	});
+
+	it('sends nothing when there is no listen id', () => {
+		const tracker = new ListenTracker();
+		tracker.begin(null);
+		tracker.tick(0);
+		tracker.tick(1);
+		tracker.flush();
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it('resends the total after a failed request', async () => {
+		fetchMock.mockRejectedValueOnce(new Error('offline'));
+		const tracker = startedTracker();
+		tracker.tick(1);
+		tracker.flush();
+		await vi.runAllTimersAsync();
+		tracker.flush();
+		expect(fetchMock).toHaveBeenCalledTimes(2);
+		expect(sentSeconds(1)).toBe(1);
+	});
+
+	it('flushes the previous listen when a new one begins', () => {
+		const tracker = startedTracker('old');
+		tracker.tick(1);
+		tracker.begin('new');
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+		expect(fetchMock.mock.calls[0][0]).toBe('/api/listens/old/progress');
+		tracker.flush();
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+	});
+});

web-player/src/lib/player/mediaSession.ts

@@ -0,0 +1,36 @@
+import { browser } from '$app/environment';
+import type { Track } from '$lib/types';
+import { trackCover } from '$lib/utils/hrefs';
+
+interface MediaSessionHandlers {
+	play: () => void;
+	pause: () => void;
+	previous: () => void;
+	next: () => void;
+}
+
+const supported = () => browser && 'mediaSession' in navigator;
+
+export const mediaSession = {
+	setup(handlers: MediaSessionHandlers) {
+		if (!supported()) return;
+		navigator.mediaSession.setActionHandler('play', handlers.play);
+		navigator.mediaSession.setActionHandler('pause', handlers.pause);
+		navigator.mediaSession.setActionHandler('previoustrack', handlers.previous);
+		navigator.mediaSession.setActionHandler('nexttrack', handlers.next);
+	},
+
+	setPlaying(playing: boolean) {
+		if (!supported()) return;
+		navigator.mediaSession.playbackState = playing ? 'playing' : 'paused';
+	},
+
+	setTrack(track: Track) {
+		if (!supported()) return;
+		navigator.mediaSession.metadata = new MediaMetadata({
+			title: track.title,
+			artist: track.artist ?? '',
+			artwork: [{ src: trackCover(track.id, 'small'), sizes: '256x256' }]
+		});
+	}
+};

web-player/src/lib/player/player.svelte.ts

@@ -1,149 +1,54 @@
 import { browser } from '$app/environment';
-import { DEFAULT_ACCENT } from '$lib/theme/color';
-import { extractAccent, type Accent } from '$lib/theme/palette';
-import { shuffle } from '$lib/data/collections';
 import { dialog } from '$lib/state/dialog.svelte';
+import type { Track } from '$lib/types';
+import { readStorage, writeStorage } from '$lib/utils/storage';
 import { ListenTracker } from './listenTracker';
-
-export interface PlayerTrack {
-	id: string | number;
-	title: string;
-	artist: string;
-	duration: number;
-	explicit?: boolean;
-	ownerUserId?: string | number | null;
-	listensCount?: number | string;
-}
-
-export interface Playlist {
-	id: string | number;
-	name: string;
-	trackIds: (string | number)[];
-}
-
-export interface QueueItem {
-	id: string | number;
-	title: string;
-	artist?: string;
-	duration?: number | string;
-	explicit?: boolean;
-	ownerUserId?: string | number | null;
-	listensCount?: number | string;
-}
-
-export interface ApiTrackLike {
-	id: string | number;
-	title: string;
-	artist?: string | null;
-	duration?: number | string;
-	isExplicit?: boolean;
-	ownerUserId?: string | number | null;
-	listensCount?: number | string;
-}
-
-export function toQueueItems(tracks: ApiTrackLike[]): QueueItem[] {
-	return tracks.map((track) => ({
-		id: track.id,
-		title: track.title,
-		artist: track.artist ?? undefined,
-		duration: track.duration,
-		explicit: track.isExplicit,
-		ownerUserId: track.ownerUserId,
-		listensCount: track.listensCount
-	}));
-}
-
-export function toQueueItem(track: ApiTrackLike): QueueItem {
-	return toQueueItems([track])[0];
-}
-
-export function trackFromQueueItem(item: QueueItem): ApiTrackLike {
-	return {
-		id: item.id,
-		title: item.title,
-		artist: item.artist,
-		duration: item.duration,
-		isExplicit: item.explicit,
-		ownerUserId: item.ownerUserId,
-		listensCount: item.listensCount
-	};
-}
-
-export function isQueueCurrent(items: { id: string | number }[]): boolean {
-	return items.some((item) => item.id === player.current.id);
-}
-
-export function playAllOrToggle(items: QueueItem[]) {
-	if (items.length === 0) return;
-	if (isQueueCurrent(items)) player.toggle();
-	else player.playQueue(items, 0);
-}
-
-export function playShuffled(items: QueueItem[]) {
-	if (items.length === 0) return;
-	player.playQueue(shuffle(items), 0);
-}
-
-async function readErrorMessage(res: Response): Promise<string> {
-	try {
-		const body = (await res.json()) as { message?: string };
-		return body?.message || `Error ${res.status}`;
-	} catch {
-		return `Error ${res.status}`;
-	}
-}
+import { mediaSession } from './mediaSession';
+import { ProgressClock } from './progressClock';
+import { append, insertNext, isLastIndex, move, nextIndex, previousIndex } from './queue';
+import { resolveStream } from './stream';
 
 const RECENT_LIMIT = 15;
+const DEFAULT_VOLUME = 100;
+const VOLUME_KEY = 'musify.player.volume';
+const MUTED_KEY = 'musify.player.muted';
 
-const EMPTY: PlayerTrack = {
-	id: '',
-	title: '',
-	artist: '',
-	duration: 0
-};
+function clampVolume(value: number): number {
+	return Math.min(100, Math.max(0, Math.round(value)));
+}
 
-function toTrack(item: QueueItem): PlayerTrack {
-	return {
-		id: item.id,
-		title: item.title,
-		artist: item.artist ?? '',
-		duration: Number(item.duration) || 0,
-		explicit: item.explicit,
-		ownerUserId: item.ownerUserId,
-		listensCount: item.listensCount
-	};
+function loadVolume(): number {
+	const stored = readStorage(VOLUME_KEY);
+	if (stored === null || stored.trim() === '') return DEFAULT_VOLUME;
+	const parsed = Number(stored);
+	return Number.isFinite(parsed) ? clampVolume(parsed) : DEFAULT_VOLUME;
 }
 
 class PlayerState {
-	tracks = $state<PlayerTrack[]>([]);
-	currentId = $state<string | number | null>(null);
+	tracks = $state<Track[]>([]);
+	currentId = $state<string | null>(null);
 	playing = $state(false);
 	progress = $state(0);
-	volume = $state(browser ? Number(localStorage.getItem('player.volume') ?? 100) : 100);
-	muted = $state(browser ? localStorage.getItem('player.muted') === 'true' : false);
+	volume = $state(browser ? loadVolume() : DEFAULT_VOLUME);
+	muted = $state(browser ? readStorage(MUTED_KEY) === 'true' : false);
 	loading = $state(false);
-	recentlyPlayed = $state<PlayerTrack[]>([]);
-	playlists = $state<Playlist[]>([]);
+	recentlyPlayed = $state<Track[]>([]);
 	shuffle = $state(false);
 	repeat = $state(false);
 
-	accentColor = $state<string | null>(null);
-
 	#audio: HTMLAudioElement | null = null;
 	#loadToken = 0;
-	#accentCache = new Map<string, Accent>();
-	#rafId: number | null = null;
 	#listen = new ListenTracker();
-
-	current = $derived(this.tracks.find((t) => t.id === this.currentId) ?? EMPTY);
-	accent = $derived(this.accentColor ?? DEFAULT_ACCENT);
-	progressPercent = $derived(
-		this.current.duration > 0 ? Math.min(100, (this.progress / this.current.duration) * 100) : 0
+	#clock = new ProgressClock(
+		() => this.#audio,
+		(value) => (this.progress = value)
 	);
 
-	get isPlaying() {
-		return this.playing;
-	}
+	current = $derived(this.tracks.find((t) => t.id === this.currentId) ?? null);
+	duration = $derived(this.current?.duration ?? 0);
+	progressPercent = $derived(
+		this.duration > 0 ? Math.min(100, (this.progress / this.duration) * 100) : 0
+	);
 
 	#audioEl(): HTMLAudioElement | null {
 		if (!browser) return null;
@@ -162,18 +67,18 @@ class PlayerState {
 		audio.addEventListener('play', () => {
 			this.#listen.resync(audio.currentTime);
 			this.playing = true;
-			this.#startProgressLoop();
-			this.#syncMediaSessionPlaybackState();
+			this.#clock.start();
+			mediaSession.setPlaying(true);
 		});
 		audio.addEventListener('pause', () => {
 			this.#listen.interrupt();
 			this.#listen.flush();
 			this.playing = false;
-			this.#stopProgressLoop();
-			this.#syncMediaSessionPlaybackState();
+			this.#clock.stop();
+			mediaSession.setPlaying(false);
 		});
 		audio.addEventListener('ended', () => {
-			this.#stopProgressLoop();
+			this.#clock.stop();
 			this.#listen.tick(audio.currentTime);
 			this.#listen.begin(null);
 			if (this.repeat) {
@@ -182,10 +87,14 @@ class PlayerState {
 				audio.play().catch(() => {});
 				return;
 			}
+			if (!this.shuffle && isLastIndex(this.tracks.length, this.#index())) {
+				this.#stopAtEnd(audio);
+				return;
+			}
 			this.next();
 		});
 		audio.addEventListener('error', () => {
-			this.#stopProgressLoop();
+			this.#clock.stop();
 			this.loading = false;
 			this.playing = false;
 			this.#fail();
@@ -195,61 +104,20 @@ class PlayerState {
 			if (document.visibilityState === 'hidden') this.#listen.flush();
 		});
 		window.addEventListener('pagehide', () => this.#listen.flush());
-		this.#setupMediaSession(audio);
+		mediaSession.setup({
+			play: () => audio.play().catch(() => {}),
+			pause: () => audio.pause(),
+			previous: () => this.previous(),
+			next: () => this.next()
+		});
 		return audio;
 	}
 
-	#setupMediaSession(audio: HTMLAudioElement) {
-		if (!('mediaSession' in navigator)) return;
-		navigator.mediaSession.setActionHandler('play', () => audio.play().catch(() => {}));
-		navigator.mediaSession.setActionHandler('pause', () => audio.pause());
-		navigator.mediaSession.setActionHandler('previoustrack', () => this.previous());
-		navigator.mediaSession.setActionHandler('nexttrack', () => this.next());
-	}
-
-	#syncMediaSessionPlaybackState() {
-		if (!browser || !('mediaSession' in navigator)) return;
-		navigator.mediaSession.playbackState = this.playing ? 'playing' : 'paused';
-	}
-
-	#syncMediaSessionMetadata(track: PlayerTrack) {
-		if (!browser || !('mediaSession' in navigator)) return;
-		if (!track.id) {
-			navigator.mediaSession.metadata = null;
-			return;
-		}
-		navigator.mediaSession.metadata = new MediaMetadata({
-			title: track.title,
-			artist: track.artist,
-			artwork: [{ src: `/api/tracks/${track.id}/cover?size=small`, sizes: '256x256' }]
-		});
-	}
-
-	#clockTime = 0;
-	#clockStamp = 0;
-
-	#tickProgress = (now: number) => {
-		const audio = this.#audio;
-		if (!audio) return;
-		if (audio.currentTime !== this.#clockTime) {
-			this.#clockTime = audio.currentTime;
-			this.#clockStamp = now;
-		}
-		const elapsed = Math.min(0.25, (now - this.#clockStamp) / 1000);
-		const smooth = this.#clockTime + (audio.paused ? 0 : elapsed * audio.playbackRate);
-		this.progress = Math.min(smooth, Number.isFinite(audio.duration) ? audio.duration : smooth);
-		this.#rafId = requestAnimationFrame(this.#tickProgress);
-	};
-
-	#startProgressLoop() {
-		if (this.#rafId !== null) return;
-		this.#rafId = requestAnimationFrame(this.#tickProgress);
-	}
-
-	#stopProgressLoop() {
-		if (this.#rafId === null) return;
-		cancelAnimationFrame(this.#rafId);
-		this.#rafId = null;
+	#stopAtEnd(audio: HTMLAudioElement) {
+		audio.currentTime = 0;
+		this.progress = 0;
+		this.playing = false;
+		mediaSession.setPlaying(false);
 	}
 
 	#syncDuration(value: number) {
@@ -262,29 +130,15 @@ class PlayerState {
 		return this.tracks.findIndex((t) => t.id === this.currentId);
 	}
 
-	#pushRecent(track: PlayerTrack) {
-		if (!track.id) return;
+	#pushRecent(track: Track) {
 		this.recentlyPlayed = [track, ...this.recentlyPlayed.filter((t) => t.id !== track.id)].slice(
 			0,
 			RECENT_LIMIT
 		);
 	}
 
-	async #applyAccent(id: string | number) {
-		const key = String(id);
-		const cached = this.#accentCache.get(key);
-		if (cached) {
-			this.accentColor = cached.accent;
-			return;
-		}
-		const result = await extractAccent(`/api/tracks/${id}/cover?size=small`);
-		if (this.currentId !== id) return;
-		if (result) {
-			this.#accentCache.set(key, result);
-			this.accentColor = result.accent;
-		} else {
-			this.accentColor = null;
-		}
+	#announce(track: Track) {
+		mediaSession.setTrack(track);
 	}
 
 	async #loadCurrent() {
@@ -292,32 +146,27 @@ class PlayerState {
 		if (!audio || this.currentId === null) return;
 		const id = this.currentId;
 		const track = this.tracks.find((t) => t.id === id);
-		this.#applyAccent(id);
-		if (track) this.#syncMediaSessionMetadata(track);
+		if (track) this.#announce(track);
 		this.#listen.begin(null);
 		const token = ++this.#loadToken;
 		this.loading = true;
 		this.progress = 0;
 		try {
-			const { src, listenId } = await this.#resolveLocalSrc(String(id));
+			const { src, listenId } = await resolveStream(id);
 			if (token !== this.#loadToken) return;
 			audio.src = src;
 			audio.volume = this.volume / 100;
 			this.#listen.begin(listenId);
 			await audio.play();
 			this.loading = false;
-			this.#pushRecent(this.current);
-		} catch (exception) {
-			console.error('playback failed', exception);
+			if (track) this.#pushRecent(track);
+		} catch (err) {
+			console.error('playback failed', err);
 			if (token !== this.#loadToken) return;
 			this.loading = false;
 			this.playing = false;
-			if (exception instanceof DOMException && exception.name === 'AbortError') return;
-			this.#fail(
-				exception instanceof Error && !(exception instanceof DOMException)
-					? exception.message
-					: undefined
-			);
+			if (err instanceof DOMException && err.name === 'AbortError') return;
+			this.#fail(err instanceof Error && !(err instanceof DOMException) ? err.message : undefined);
 		}
 	}
 
@@ -329,109 +178,54 @@ class PlayerState {
 		);
 	}
 
-	async #resolveLocalSrc(id: string): Promise<{ src: string; listenId: string | null }> {
-		const res = await fetch(`/api/tracks/${id}/stream`);
-		if (!res.ok) throw new Error(await readErrorMessage(res));
-		const { manifestUrl, ticket, listenId } = (await res.json()) as {
-			manifestUrl: string;
-			ticket: string;
-			listenId?: string | null;
-		};
-		return { src: this.#withTicket(manifestUrl, ticket), listenId: listenId ?? null };
-	}
-
 	async #beginRepeatListen() {
 		const id = this.currentId;
 		if (id === null) return;
 		try {
-			const res = await fetch(`/api/tracks/${id}/stream`);
-			if (!res.ok) return;
-			const { listenId } = (await res.json()) as { listenId?: string | null };
-			if (this.currentId === id) this.#listen.begin(listenId ?? null);
+			const { listenId } = await resolveStream(id);
+			if (this.currentId === id) this.#listen.begin(listenId);
 		} catch {
 			return;
 		}
 	}
 
-	#withTicket(url: string, ticket: string): string {
-		if (!ticket) return url;
-		const sep = url.includes('?') ? '&' : '?';
-		return `${url}${sep}t=${encodeURIComponent(ticket)}`;
-	}
-
-	hydrate(item: ApiTrackLike) {
+	hydrate(track: Track) {
 		if (this.currentId !== null || this.tracks.length > 0) return;
-		const track = toTrack(toQueueItem(item));
 		this.tracks = [track];
 		this.currentId = track.id;
-		this.#applyAccent(track.id);
-		this.#syncMediaSessionMetadata(track);
+		this.#announce(track);
 	}
 
-	playlistTracks(ids: (string | number)[]): PlayerTrack[] {
-		return ids
-			.map((id) => this.tracks.find((t) => t.id === id))
-			.filter((t): t is PlayerTrack => Boolean(t));
-	}
-
-	playQueue(list: QueueItem[], startIndex = 0) {
+	playQueue(list: Track[], startIndex = 0) {
 		if (list.length === 0) return;
-		this.tracks = list.map(toTrack);
+		this.tracks = [...list];
 		const start = this.tracks[startIndex] ?? this.tracks[0];
 		this.currentId = start.id;
 		this.#loadCurrent();
 	}
 
-	playOrToggle(list: QueueItem[], index: number) {
+	playOrToggle(list: Track[], index: number) {
 		if (index < 0 || index >= list.length) return;
 		if (this.currentId === list[index].id) this.toggle();
 		else this.playQueue(list, index);
 	}
 
-	playNextItem(item: QueueItem) {
-		this.playNext([item]);
-	}
-
-	playNext(items: QueueItem[]) {
+	playNext(items: Track[]) {
 		if (items.length === 0) return;
 		if (this.currentId === null) {
 			this.playQueue(items, 0);
 			return;
 		}
-		const tracks = [...this.tracks];
-		tracks.splice(this.#index() + 1, 0, ...items.map(toTrack));
-		this.tracks = tracks;
+		this.tracks = insertNext(this.tracks, this.#index(), items);
 	}
 
-	appendToQueue(items: QueueItem[]) {
+	appendToQueue(items: Track[]) {
 		if (items.length === 0) return;
 		if (this.currentId === null) {
 			this.playQueue(items, 0);
 			return;
 		}
-		this.tracks = [...this.tracks, ...items.map(toTrack)];
-	}
-
-	playTrack(id: string | number) {
-		if (this.currentId === id) {
-			this.toggle();
-			return;
-		}
-		const known =
-			this.tracks.find((t) => t.id === id) ?? this.recentlyPlayed.find((t) => t.id === id);
-		if (known && !this.tracks.some((t) => t.id === id)) {
-			this.tracks = [known];
-		}
-		if (!this.tracks.some((t) => t.id === id)) return;
-		this.currentId = id;
-		this.#loadCurrent();
-	}
-
-	playPlaylist(id: string | number) {
-		const playlist = this.playlists.find((p) => p.id === id);
-		if (!playlist) return;
-		const items = this.playlistTracks(playlist.trackIds);
-		if (items.length > 0) this.playQueue(items, 0);
+		this.tracks = append(this.tracks, items);
 	}
 
 	toggle() {
@@ -454,19 +248,13 @@ class PlayerState {
 		this.muted = value;
 		const audio = this.#audioEl();
 		if (audio) audio.muted = value;
-		if (browser) localStorage.setItem('player.muted', String(value));
+		if (browser) writeStorage(MUTED_KEY, String(value));
 	}
 
 	next() {
 		if (this.tracks.length === 0) return;
 		const idx = this.#index();
-		let nextIdx = (idx + 1) % this.tracks.length;
-		if (this.shuffle && this.tracks.length > 1) {
-			do {
-				nextIdx = Math.floor(Math.random() * this.tracks.length);
-			} while (nextIdx === idx);
-		}
-		this.currentId = this.tracks[nextIdx].id;
+		this.currentId = this.tracks[nextIndex(this.tracks.length, idx, this.shuffle)].id;
 		this.#loadCurrent();
 	}
 
@@ -490,17 +278,11 @@ class PlayerState {
 	}
 
 	moveQueueItem(from: number, insertAt: number) {
-		if (from < 0 || from >= this.tracks.length) return;
-		const target = insertAt > from ? insertAt - 1 : insertAt;
-		if (target === from) return;
-		const tracks = [...this.tracks];
-		const [item] = tracks.splice(from, 1);
-		tracks.splice(target, 0, item);
-		this.tracks = tracks;
+		this.tracks = move(this.tracks, from, insertAt);
 	}
 
 	clearUpcoming() {
-		this.tracks = this.currentId === null ? [] : [this.current];
+		this.tracks = this.current ? [this.current] : [];
 	}
 
 	previous() {
@@ -511,26 +293,24 @@ class PlayerState {
 			return;
 		}
 		const idx = this.#index();
-		this.currentId = this.tracks[(idx - 1 + this.tracks.length) % this.tracks.length].id;
+		this.currentId = this.tracks[previousIndex(this.tracks.length, idx)].id;
 		this.#loadCurrent();
 	}
 
 	seekFraction(fraction: number) {
 		const audio = this.#audioEl();
 		const clamped = Math.min(1, Math.max(0, fraction));
-		const target = clamped * this.current.duration;
+		const target = clamped * this.duration;
 		this.progress = target;
 		if (audio && Number.isFinite(audio.duration)) audio.currentTime = target;
 	}
 
 	setVolume(value: number) {
-		this.volume = Math.min(100, Math.max(0, Math.round(value)));
+		this.volume = Number.isFinite(value) ? clampVolume(value) : this.volume;
 		if (this.muted && this.volume > 0) this.#applyMuted(false);
 		const audio = this.#audioEl();
-		if (audio) {
-			audio.volume = this.volume / 100;
-			localStorage.setItem('player.volume', String(this.volume));
-		}
+		if (audio) audio.volume = this.volume / 100;
+		if (browser) writeStorage(VOLUME_KEY, String(this.volume));
 	}
 }
 

web-player/src/lib/player/progressClock.ts

@@ -0,0 +1,36 @@
+const MAX_INTERPOLATION_SECONDS = 0.25;
+
+export class ProgressClock {
+	#rafId: number | null = null;
+	#time = 0;
+	#stamp = 0;
+
+	constructor(
+		private getAudio: () => HTMLAudioElement | null,
+		private onProgress: (seconds: number) => void
+	) {}
+
+	#tick = (now: number) => {
+		const audio = this.getAudio();
+		if (!audio) return;
+		if (audio.currentTime !== this.#time) {
+			this.#time = audio.currentTime;
+			this.#stamp = now;
+		}
+		const elapsed = Math.min(MAX_INTERPOLATION_SECONDS, (now - this.#stamp) / 1000);
+		const smooth = this.#time + (audio.paused ? 0 : elapsed * audio.playbackRate);
+		this.onProgress(Math.min(smooth, Number.isFinite(audio.duration) ? audio.duration : smooth));
+		this.#rafId = requestAnimationFrame(this.#tick);
+	};
+
+	start() {
+		if (this.#rafId !== null) return;
+		this.#rafId = requestAnimationFrame(this.#tick);
+	}
+
+	stop() {
+		if (this.#rafId === null) return;
+		cancelAnimationFrame(this.#rafId);
+		this.#rafId = null;
+	}
+}

web-player/src/lib/player/queue.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { append, insertNext, isLastIndex, move, nextIndex, previousIndex } from './queue';
+
+const t = (id: string) => ({ id });
+const ids = (queue: { id: string }[]) => queue.map((item) => item.id);
+
+describe('insertNext', () => {
+	it('inserts right after the current track without mutating', () => {
+		const queue = ['a', 'b', 'c'].map(t);
+		expect(ids(insertNext(queue, 0, ['x', 'y'].map(t)))).toEqual(['a', 'x', 'y', 'b', 'c']);
+		expect(ids(queue)).toEqual(['a', 'b', 'c']);
+	});
+	it('inserts at the start when there is no current track', () => {
+		expect(ids(insertNext([t('a')], -1, [t('x')]))).toEqual(['x', 'a']);
+	});
+	it('moves tracks already queued instead of duplicating them', () => {
+		const queue = ['a', 'b', 'c', 'd'].map(t);
+		expect(ids(insertNext(queue, 1, [t('d'), t('a')]))).toEqual(['b', 'd', 'a', 'c']);
+	});
+	it('ignores the current track', () => {
+		const queue = ['a', 'b'].map(t);
+		expect(ids(insertNext(queue, 0, [t('a')]))).toEqual(['a', 'b']);
+	});
+});
+
+describe('append', () => {
+	it('adds new items at the end', () => {
+		expect(ids(append([t('a')], ['b', 'c'].map(t)))).toEqual(['a', 'b', 'c']);
+	});
+	it('skips tracks already in the queue and repeated ones', () => {
+		expect(ids(append(['a', 'b'].map(t), ['b', 'c', 'c'].map(t)))).toEqual(['a', 'b', 'c']);
+	});
+	it('returns the same queue when nothing is added', () => {
+		const queue = [t('a')];
+		expect(append(queue, [t('a')])).toBe(queue);
+	});
+});
+
+describe('move', () => {
+	const queue = ['a', 'b', 'c', 'd'];
+	it('moves an item forward using insert position semantics', () => {
+		expect(move(queue, 0, 3)).toEqual(['b', 'c', 'a', 'd']);
+	});
+	it('moves an item backward', () => {
+		expect(move(queue, 3, 1)).toEqual(['a', 'd', 'b', 'c']);
+	});
+	it('is a no-op when the target equals the origin', () => {
+		expect(move(queue, 1, 1)).toBe(queue);
+		expect(move(queue, 1, 2)).toBe(queue);
+	});
+	it('ignores out-of-range origins', () => {
+		expect(move(queue, -1, 0)).toBe(queue);
+		expect(move(queue, 4, 0)).toBe(queue);
+	});
+});
+
+describe('nextIndex', () => {
+	it('advances and wraps around', () => {
+		expect(nextIndex(3, 0, false)).toBe(1);
+		expect(nextIndex(3, 2, false)).toBe(0);
+	});
+	it('never repeats the current index when shuffling', () => {
+		const values = [0.4, 0.5, 0.9];
+		let call = 0;
+		expect(nextIndex(3, 1, true, () => values[call++])).toBe(2);
+		expect(call).toBe(3);
+	});
+	it('ignores shuffle with a single track', () => {
+		expect(nextIndex(1, 0, true)).toBe(0);
+	});
+});
+
+describe('previousIndex', () => {
+	it('steps back and wraps around', () => {
+		expect(previousIndex(3, 2)).toBe(1);
+		expect(previousIndex(3, 0)).toBe(2);
+	});
+});
+
+describe('isLastIndex', () => {
+	it('detects the end of the queue', () => {
+		expect(isLastIndex(3, 2)).toBe(true);
+		expect(isLastIndex(3, 1)).toBe(false);
+	});
+});

web-player/src/lib/player/queue.ts

@@ -0,0 +1,60 @@
+interface Identified {
+	id: string;
+}
+
+export function insertNext<T extends Identified>(
+	queue: T[],
+	currentIndex: number,
+	items: T[]
+): T[] {
+	const currentId = queue[currentIndex]?.id;
+	const incoming = items.filter((item) => item.id !== currentId);
+	const moving = new Set(incoming.map((item) => item.id));
+	const rest = queue.filter((item) => !moving.has(item.id));
+	const anchor = currentId === undefined ? -1 : rest.findIndex((item) => item.id === currentId);
+	return [...rest.slice(0, anchor + 1), ...incoming, ...rest.slice(anchor + 1)];
+}
+
+export function append<T extends Identified>(queue: T[], items: T[]): T[] {
+	const present = new Set(queue.map((item) => item.id));
+	const added = items.filter((item) => {
+		if (present.has(item.id)) return false;
+		present.add(item.id);
+		return true;
+	});
+	return added.length > 0 ? [...queue, ...added] : queue;
+}
+
+export function move<T>(queue: T[], from: number, insertAt: number): T[] {
+	if (from < 0 || from >= queue.length) return queue;
+	const target = insertAt > from ? insertAt - 1 : insertAt;
+	if (target === from) return queue;
+	const result = [...queue];
+	const [item] = result.splice(from, 1);
+	result.splice(target, 0, item);
+	return result;
+}
+
+export function isLastIndex(length: number, index: number): boolean {
+	return index >= length - 1;
+}
+
+export function nextIndex(
+	length: number,
+	index: number,
+	shuffle: boolean,
+	random: () => number = Math.random
+): number {
+	if (shuffle && length > 1) {
+		let next: number;
+		do {
+			next = Math.floor(random() * length);
+		} while (next === index);
+		return next;
+	}
+	return (index + 1) % length;
+}
+
+export function previousIndex(length: number, index: number): number {
+	return (index - 1 + length) % length;
+}

web-player/src/lib/player/queuePanel.svelte.ts

@@ -1,3 +0,0 @@
-import { createToggle } from '../state/toggle.svelte';
-
-export const queuePanel = createToggle();

web-player/src/lib/player/recentlyPlayed.ts

@@ -0,0 +1,15 @@
+import { player } from '$lib/player/player.svelte';
+import type { Track } from '$lib/types';
+
+export function mergeRecentlyPlayed(history: Track[], limit: number): Track[] {
+	const seen = new Set<string>();
+	const merged: Track[] = [];
+
+	for (const track of [...player.recentlyPlayed, ...history]) {
+		if (seen.has(track.id)) continue;
+		seen.add(track.id);
+		merged.push(track);
+	}
+
+	return merged.slice(0, limit);
+}

web-player/src/lib/player/stream.ts

@@ -0,0 +1,25 @@
+async function readErrorMessage(res: Response): Promise<string> {
+	try {
+		const body = (await res.json()) as { message?: string };
+		return body?.message || `Error ${res.status}`;
+	} catch {
+		return `Error ${res.status}`;
+	}
+}
+
+function withTicket(url: string, ticket: string): string {
+	if (!ticket) return url;
+	const separator = url.includes('?') ? '&' : '?';
+	return `${url}${separator}t=${encodeURIComponent(ticket)}`;
+}
+
+export async function resolveStream(id: string): Promise<{ src: string; listenId: string | null }> {
+	const res = await fetch(`/api/tracks/${id}/stream`);
+	if (!res.ok) throw new Error(await readErrorMessage(res));
+	const { manifestUrl, ticket, listenId } = (await res.json()) as {
+		manifestUrl: string;
+		ticket: string;
+		listenId?: string | null;
+	};
+	return { src: withTicket(manifestUrl, ticket), listenId: listenId ?? null };
+}

web-player/src/lib/server/actions/authedAction.ts

@@ -0,0 +1,27 @@
+import { fail, type RequestEvent } from '@sveltejs/kit';
+import { apiFor, type ApiClient } from '$lib/server/api';
+
+export interface ActionContext {
+	api: ApiClient;
+	form: FormData;
+	params: Record<string, string>;
+	locals: App.Locals;
+	url: URL;
+}
+
+export function authedAction<R>(
+	handler: (context: ActionContext) => R | Promise<R>,
+	unauthorizedMessage = 'Inicia sesión.'
+) {
+	return async (event: RequestEvent) => {
+		if (!event.locals.accessToken) return fail(401, { message: unauthorizedMessage });
+		const form = await event.request.formData();
+		return handler({
+			api: apiFor(event),
+			form,
+			params: event.params as Record<string, string>,
+			locals: event.locals,
+			url: event.url
+		});
+	};
+}

web-player/src/lib/server/actions/follow.ts

@@ -0,0 +1,24 @@
+import { fail } from '@sveltejs/kit';
+import { authedAction } from '$lib/server/actions/authedAction';
+
+const setFollowing = (follow: boolean) =>
+	authedAction(async ({ api, params }) => {
+		const id = params.id ?? '';
+		if (!id) return fail(400, { message: 'Falta el usuario.' });
+
+		const options = { params: { path: { id } } };
+		const { error } = follow
+			? await api.POST('/users/{id}/follow', options)
+			: await api.DELETE('/users/{id}/follow', options);
+
+		if (error) {
+			return fail(502, {
+				message: follow ? 'No se pudo seguir al usuario.' : 'No se pudo dejar de seguir al usuario.'
+			});
+		}
+
+		return { following: follow, userId: id };
+	});
+
+export const followUserAction = setFollowing(true);
+export const unfollowUserAction = setFollowing(false);

web-player/src/lib/server/actions/playlist.ts

@@ -0,0 +1,46 @@
+import { fail } from '@sveltejs/kit';
+import { formString } from '$lib/server/forms/fields';
+import { authedAction } from '$lib/server/actions/authedAction';
+
+export const addTrackAction = authedAction(async ({ api, form, params }) => {
+	const playlistId = formString(form, 'playlistId') || (params.id ?? '');
+	const trackId = formString(form, 'trackId');
+
+	if (!playlistId || !trackId) {
+		return fail(400, { message: 'Faltan datos de la canción.' });
+	}
+
+	const { error, response } = await api.POST('/playlists/{playlistId}/tracks', {
+		params: { path: { playlistId } },
+		body: { trackId }
+	});
+
+	if (error) {
+		if (response?.status === 409) {
+			return fail(409, { message: 'La canción ya está en esa playlist.', trackId });
+		}
+		return fail(502, { message: 'No se pudo añadir la canción.', trackId });
+	}
+
+	return { added: true, trackId, playlistId };
+});
+
+export const addAlbumToPlaylistAction = authedAction(async ({ api, form, params }) => {
+	const playlistId = formString(form, 'playlistId') || (params.id ?? '');
+	const albumId = formString(form, 'albumId');
+
+	if (!playlistId || !albumId) {
+		return fail(400, { message: 'Faltan datos del álbum.' });
+	}
+
+	const { data, error } = await api.POST('/playlists/{playlistId}/albums/{albumId}', {
+		params: { path: { playlistId, albumId } }
+	});
+
+	if (error || !data) {
+		return fail(502, { message: 'No se pudo añadir el álbum.', albumId });
+	}
+
+	const added = Number(data.addedCount);
+	return { addedAlbum: true, albumId, playlistId, added };
+});

web-player/src/lib/server/api.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { apiErrorDetail } from './api';
+
+describe('apiErrorDetail', () => {
+	it('joins the validation messages from errors', () => {
+		expect(
+			apiErrorDetail({ errors: { Name: ['Too short.', 'Required.'], Genre: ['Invalid.'] } })
+		).toBe('Too short. Required. Invalid.');
+	});
+
+	it('flattens arrays and ignores non-string entries', () => {
+		expect(apiErrorDetail({ errors: { A: ['one', 2, null], B: 'two' } })).toBe('one two');
+	});
+
+	it('falls back to detail when errors has no text', () => {
+		expect(apiErrorDetail({ errors: {}, detail: 'Bad request.' })).toBe('Bad request.');
+	});
+
+	it('falls back to title after detail', () => {
+		expect(apiErrorDetail({ detail: '', title: 'Conflict' })).toBe('Conflict');
+		expect(apiErrorDetail({ title: 'Conflict' })).toBe('Conflict');
+	});
+
+	it('returns undefined for non-objects and empty objects', () => {
+		expect(apiErrorDetail(undefined)).toBeUndefined();
+		expect(apiErrorDetail(null)).toBeUndefined();
+		expect(apiErrorDetail('boom')).toBeUndefined();
+		expect(apiErrorDetail({})).toBeUndefined();
+		expect(apiErrorDetail({ detail: 3, title: '' })).toBeUndefined();
+	});
+});

web-player/src/lib/server/api.ts

@@ -1,7 +1,6 @@
 import createClient from 'openapi-fetch';
-import { error, fail, redirect, type ActionFailure } from '@sveltejs/kit';
+import { error, fail, type ActionFailure, type RequestEvent } from '@sveltejs/kit';
 import type { paths } from '$lib/api/schema';
-import type { SessionUser } from '$lib/types';
 import { apiConfig } from '$lib/server/config';
 
 interface ApiClientOptions {
@@ -17,28 +16,10 @@ export function createApiClient({ fetch, accessToken }: ApiClientOptions) {
 	});
 }
 
-export function requireUser(locals: App.Locals, url: URL): SessionUser {
-	if (!locals.user)
-		redirect(302, `/auth?returnTo=${encodeURIComponent(url.pathname + url.search)}`);
-	return locals.user;
-}
+export type ApiClient = ReturnType<typeof createApiClient>;
 
-export function optionalUser(
-	locals: App.Locals,
-	url: URL,
-	allowAnonymousListening: boolean
-): SessionUser | null {
-	if (locals.user) return locals.user;
-	if (!allowAnonymousListening)
-		redirect(302, `/auth?returnTo=${encodeURIComponent(url.pathname + url.search)}`);
-	return null;
-}
-
-export function requireAccessTokenAction(
-	locals: App.Locals,
-	message = 'Inicia sesión.'
-): string | ActionFailure<{ message: string }> {
-	return locals.accessToken ?? fail(401, { message });
+export function apiFor({ fetch, locals }: Pick<RequestEvent, 'fetch' | 'locals'>): ApiClient {
+	return createApiClient({ fetch, accessToken: locals.accessToken ?? undefined });
 }
 
 export function unwrapOrError<T>(
@@ -70,9 +51,18 @@ export function apiErrorDetail(error: unknown): string | undefined {
 	return undefined;
 }
 
-export function unwrapOrFail(
-	result: { error?: unknown },
-	message: string
-): ActionFailure<{ message: string; detail?: string }> | undefined {
+type Failure = ActionFailure<{ message: string; detail?: string }>;
+
+export function failOnError(result: { error?: unknown }, message: string): Failure | undefined {
 	return result.error ? fail(502, { message, detail: apiErrorDetail(result.error) }) : undefined;
 }
+
+export function requireData<T>(
+	result: { data?: T; error?: unknown },
+	message: string
+): { data: T; failure?: undefined } | { data?: undefined; failure: Failure } {
+	if (result.error || result.data === undefined) {
+		return { failure: fail(502, { message, detail: apiErrorDetail(result.error) }) };
+	}
+	return { data: result.data };
+}

web-player/src/lib/server/auth.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { safeReturnTo } from './auth';
+
+describe('safeReturnTo', () => {
+	it('keeps local paths', () => {
+		expect(safeReturnTo('/')).toBe('/');
+		expect(safeReturnTo('/playlists/1?tab=x#top')).toBe('/playlists/1?tab=x#top');
+	});
+	it('falls back to / for missing values', () => {
+		expect(safeReturnTo(null)).toBe('/');
+		expect(safeReturnTo(undefined)).toBe('/');
+		expect(safeReturnTo('')).toBe('/');
+	});
+	it('rejects absolute and protocol-relative URLs', () => {
+		expect(safeReturnTo('https://example.com')).toBe('/');
+		expect(safeReturnTo('//example.com')).toBe('/');
+		expect(safeReturnTo('/\\example.com')).toBe('/');
+		expect(safeReturnTo('javascript:alert(1)')).toBe('/');
+		expect(safeReturnTo('relative/path')).toBe('/');
+	});
+});

web-player/src/lib/server/auth.ts

@@ -18,6 +18,13 @@ export interface Session extends SessionUser {
 	expiresAt: number;
 }
 
+export function safeReturnTo(value: string | null | undefined): string {
+	if (!value || !value.startsWith('/') || value.startsWith('//') || value.startsWith('/\\')) {
+		return '/';
+	}
+	return value;
+}
+
 let configPromise: Promise<client.Configuration> | undefined;
 export function getOidcConfig(): Promise<client.Configuration> {
 	configPromise ??= (async () => {
@@ -29,9 +36,9 @@ export function getOidcConfig(): Promise<client.Configuration> {
 		return secret
 			? client.discovery(issuer, authConfig.clientId, secret, undefined, options)
 			: client.discovery(issuer, authConfig.clientId, undefined, client.None(), options);
-	})().catch((exception) => {
+	})().catch((err) => {
 		configPromise = undefined;
-		throw exception;
+		throw err;
 	});
 	return configPromise;
 }
@@ -44,7 +51,7 @@ function sessionKey(): Promise<Uint8Array> {
 	return keyPromise;
 }
 
-export function sessionCookieOptions(url: URL) {
+function sessionCookieOptions(url: URL) {
 	return {
 		httpOnly: true,
 		sameSite: 'lax' as const,
@@ -144,8 +151,8 @@ export async function refreshSession(session: Session): Promise<Session | null>
 			idToken: tokens.id_token ?? session.idToken,
 			expiresAt: Math.floor(Date.now() / 1000) + (tokens.expires_in ?? 3600)
 		};
-	} catch (exception) {
-		console.error('Token refresh failed', exception);
+	} catch (err) {
+		console.error('Token refresh failed', err);
 		return null;
 	}
 }

web-player/src/lib/server/config.ts

@@ -1,6 +1,7 @@
 import { env } from '$env/dynamic/private';
 
 const DAY_SECONDS = 60 * 60 * 24;
+const MIN_SESSION_SECRET_LENGTH = 32;
 const DEFAULT_OIDC_SCOPE = 'openid profile email offline_access';
 
 function positiveInt(value: string | undefined, fallback: number): number {
@@ -35,7 +36,13 @@ export const authConfig = {
 		return required('AUTH_POST_LOGOUT_URI', env.AUTH_POST_LOGOUT_URI);
 	},
 	get sessionSecret() {
-		return env.SESSION_SECRET;
+		const secret = required('SESSION_SECRET', env.SESSION_SECRET);
+		if (secret.length < MIN_SESSION_SECRET_LENGTH) {
+			throw new Error(
+				`SESSION_SECRET must be at least ${MIN_SESSION_SECRET_LENGTH} characters long.`
+			);
+		}
+		return secret;
 	},
 	get sessionTtlSeconds() {
 		return positiveInt(env.SESSION_TTL_SECONDS, 7 * DAY_SECONDS);

web-player/src/lib/server/followActions.ts

@@ -1,28 +0,0 @@
-import { fail, type RequestEvent } from '@sveltejs/kit';
-import { createApiClient, requireAccessTokenAction } from '$lib/server/api';
-
-async function setFollowing({ request, params, locals, fetch }: RequestEvent, follow: boolean) {
-	const accessToken = requireAccessTokenAction(locals);
-	if (typeof accessToken !== 'string') return accessToken;
-
-	const form = await request.formData();
-	const id = String(form.get('userId') ?? '') || String(params.id ?? '');
-	if (!id) return fail(400, { message: 'Falta el usuario.' });
-
-	const api = createApiClient({ fetch, accessToken });
-	const options = { params: { path: { id } } };
-	const { error } = follow
-		? await api.POST('/users/{id}/follow', options)
-		: await api.DELETE('/users/{id}/follow', options);
-
-	if (error) {
-		return fail(502, {
-			message: follow ? 'No se pudo seguir al usuario.' : 'No se pudo dejar de seguir al usuario.'
-		});
-	}
-
-	return { following: follow, userId: id };
-}
-
-export const followUserAction = (event: RequestEvent) => setFollowing(event, true);
-export const unfollowUserAction = (event: RequestEvent) => setFollowing(event, false);

web-player/src/lib/server/follows.ts

@@ -1,8 +1,6 @@
-import type { createApiClient } from '$lib/server/api';
+import type { ApiClient } from '$lib/server/api';
 import type { FollowList } from '$lib/types';
 
-type ApiClient = ReturnType<typeof createApiClient>;
-
 export function fetchFollowList(
 	api: ApiClient,
 	list: FollowList,

web-player/src/lib/server/forms/albumForm.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { ALBUM_EARLIEST_YEAR } from '$lib/validation';
+import { parseAlbumForm } from './albumForm';
+
+function form(fields: Record<string, string>): FormData {
+	const data = new FormData();
+	for (const [key, value] of Object.entries(fields)) data.set(key, value);
+	return data;
+}
+
+describe('parseAlbumForm', () => {
+	it('parses a valid form and trims values', () => {
+		expect(
+			parseAlbumForm(form({ title: ' Title ', description: ' d ', releaseYear: '2020' }))
+		).toEqual({ body: { title: 'Title', description: 'd', releaseYear: 2020 } });
+	});
+	it('turns empty optional fields into null', () => {
+		expect(parseAlbumForm(form({ title: 'T' }))).toEqual({
+			body: { title: 'T', description: null, releaseYear: null }
+		});
+	});
+	it('rejects empty or too long titles', () => {
+		expect(parseAlbumForm(form({ title: '  ' }))).toHaveProperty('failMessage');
+		expect(parseAlbumForm(form({ title: 'x'.repeat(201) }))).toHaveProperty('failMessage');
+	});
+	it('rejects too long descriptions', () => {
+		expect(parseAlbumForm(form({ title: 'T', description: 'x'.repeat(257) }))).toHaveProperty(
+			'failMessage'
+		);
+	});
+	it('rejects invalid years', () => {
+		for (const releaseYear of ['abc', '2020.5', String(ALBUM_EARLIEST_YEAR - 1), '9999']) {
+			expect(parseAlbumForm(form({ title: 'T', releaseYear }))).toHaveProperty('failMessage');
+		}
+	});
+});

web-player/src/lib/server/forms/albumForm.ts

@@ -1,4 +1,5 @@
-import { ALBUM_EARLIEST_YEAR } from '$lib/config';
+import { formString } from '$lib/server/forms/fields';
+import { ALBUM_EARLIEST_YEAR, LIMITS } from '$lib/validation';
 
 interface AlbumFormBody {
 	title: string;
@@ -7,17 +8,19 @@ interface AlbumFormBody {
 }
 
 export function parseAlbumForm(form: FormData): { body: AlbumFormBody } | { failMessage: string } {
-	const title = String(form.get('title') ?? '').trim();
-	if (title === '' || title.length > 200) {
-		return { failMessage: 'El título es obligatorio (máx. 200 caracteres).' };
+	const title = formString(form, 'title').trim();
+	if (title === '' || title.length > LIMITS.albumTitle) {
+		return { failMessage: `El título es obligatorio (máx. ${LIMITS.albumTitle} caracteres).` };
 	}
 
-	const description = String(form.get('description') ?? '').trim();
-	if (description.length > 256) {
-		return { failMessage: 'La descripción no puede pasar de 256 caracteres.' };
+	const description = formString(form, 'description').trim();
+	if (description.length > LIMITS.albumDescription) {
+		return {
+			failMessage: `La descripción no puede pasar de ${LIMITS.albumDescription} caracteres.`
+		};
 	}
 
-	const rawYear = String(form.get('releaseYear') ?? '').trim();
+	const rawYear = formString(form, 'releaseYear').trim();
 	const latestYear = new Date().getFullYear() + 1;
 	let releaseYear: number | null = null;
 

web-player/src/lib/server/forms/fields.ts

@@ -0,0 +1,8 @@
+export function formString(form: FormData, key: string): string {
+	return String(form.get(key) ?? '');
+}
+
+export function formFile(form: FormData, key: string): File | null {
+	const value = form.get(key);
+	return value instanceof File && value.size > 0 ? value : null;
+}

web-player/src/lib/server/forms/playlistForm.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { LIMITS } from '$lib/validation';
+import { parsePlaylistForm } from './playlistForm';
+
+function form(fields: Record<string, string>): FormData {
+	const data = new FormData();
+	for (const [key, value] of Object.entries(fields)) data.set(key, value);
+	return data;
+}
+
+describe('parsePlaylistForm', () => {
+	it('parses a valid form', () => {
+		expect(
+			parsePlaylistForm(form({ name: ' Mix ', description: ' d ', visibility: 'public' }))
+		).toEqual({ body: { name: 'Mix', description: 'd', visibility: 'Public', cover: null } });
+	});
+	it('defaults to private', () => {
+		const parsed = parsePlaylistForm(form({ name: 'Mix' }));
+		expect(parsed).toMatchObject({ body: { visibility: 'Private', description: '' } });
+	});
+	it('rejects empty or too long names keeping the typed values', () => {
+		expect(parsePlaylistForm(form({ name: ' ', description: 'd' }))).toMatchObject({
+			failMessage: expect.any(String),
+			description: 'd'
+		});
+		expect(parsePlaylistForm(form({ name: 'x'.repeat(LIMITS.playlistName + 1) }))).toHaveProperty(
+			'failMessage'
+		);
+	});
+	it('rejects too long descriptions', () => {
+		const description = 'x'.repeat(LIMITS.playlistDescription + 1);
+		expect(parsePlaylistForm(form({ name: 'Mix', description }))).toHaveProperty('failMessage');
+	});
+});

web-player/src/lib/server/forms/playlistForm.ts

@@ -0,0 +1,42 @@
+import { formFile, formString } from '$lib/server/forms/fields';
+import { LIMITS } from '$lib/validation';
+
+interface PlaylistFormBody {
+	name: string;
+	description: string;
+	visibility: 'Public' | 'Private';
+	cover: File | null;
+}
+
+export type PlaylistFormFailure = { failMessage: string; name: string; description: string };
+
+export function parsePlaylistForm(
+	form: FormData
+): { body: PlaylistFormBody } | PlaylistFormFailure {
+	const name = formString(form, 'name').trim();
+	const description = formString(form, 'description').trim();
+
+	if (name === '' || name.length > LIMITS.playlistName) {
+		return {
+			failMessage: `El nombre es obligatorio (máx. ${LIMITS.playlistName} caracteres).`,
+			name,
+			description
+		};
+	}
+	if (description.length > LIMITS.playlistDescription) {
+		return {
+			failMessage: `La descripción no puede pasar de ${LIMITS.playlistDescription} caracteres.`,
+			name,
+			description
+		};
+	}
+
+	return {
+		body: {
+			name,
+			description,
+			visibility: formString(form, 'visibility') === 'public' ? 'Public' : 'Private',
+			cover: formFile(form, 'cover')
+		}
+	};
+}

web-player/src/lib/server/forms/trackUploadForm.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { LIMITS } from '$lib/validation';
+import { parseTrackUploadForm } from './trackUploadForm';
+
+function form(fields: Record<string, string | string[] | File>): FormData {
+	const data = new FormData();
+	for (const [key, value] of Object.entries(fields)) {
+		if (Array.isArray(value)) value.forEach((item) => data.append(key, item));
+		else data.set(key, value);
+	}
+	return data;
+}
+
+const audio = new File(['a'], 'a.mp3');
+const cover = new File(['c'], 'c.png');
+
+describe('parseTrackUploadForm', () => {
+	it('parses a valid form and deduplicates tags', () => {
+		const parsed = parseTrackUploadForm(
+			form({ title: ' Song ', audio, cover, tags: ['rock', 'rock', 'pop'], isExplicit: 'on' })
+		);
+		expect(parsed).toMatchObject({
+			body: { title: 'Song', tags: ['rock', 'pop'], isExplicit: true }
+		});
+	});
+	it('validates each field', () => {
+		const ok = { title: 'Song', audio, cover, tags: ['rock'] };
+		expect(parseTrackUploadForm(form({ ...ok, title: '' }))).toHaveProperty('failMessage');
+		expect(
+			parseTrackUploadForm(form({ ...ok, title: 'x'.repeat(LIMITS.trackTitle + 1) }))
+		).toHaveProperty('failMessage');
+		expect(parseTrackUploadForm(form({ ...ok, audio: '' }))).toHaveProperty('failMessage');
+		expect(parseTrackUploadForm(form({ ...ok, cover: '' }))).toHaveProperty('failMessage');
+		expect(parseTrackUploadForm(form({ ...ok, tags: [] }))).toHaveProperty('failMessage');
+	});
+});

web-player/src/lib/server/forms/trackUploadForm.ts

@@ -0,0 +1,30 @@
+import { formFile, formString } from '$lib/server/forms/fields';
+import { LIMITS } from '$lib/validation';
+
+interface TrackUploadBody {
+	title: string;
+	audio: File;
+	cover: File;
+	tags: string[];
+	isExplicit: boolean;
+}
+
+export function parseTrackUploadForm(
+	form: FormData
+): { body: TrackUploadBody } | { failMessage: string } {
+	const title = formString(form, 'title').trim();
+	if (title === '' || title.length > LIMITS.trackTitle) {
+		return { failMessage: `El título es obligatorio (máx. ${LIMITS.trackTitle} caracteres).` };
+	}
+
+	const audio = formFile(form, 'audio');
+	if (!audio) return { failMessage: 'Selecciona un archivo de audio.' };
+
+	const cover = formFile(form, 'cover');
+	if (!cover) return { failMessage: 'Selecciona una portada.' };
+
+	const tags = [...new Set(form.getAll('tags').map(String))];
+	if (tags.length === 0) return { failMessage: 'Elige al menos un género.' };
+
+	return { body: { title, audio, cover, tags, isExplicit: form.get('isExplicit') === 'on' } };
+}

web-player/src/lib/server/genres.ts

@@ -0,0 +1,18 @@
+import type { ApiClient } from '$lib/server/api';
+import type { components } from '$lib/api/schema';
+
+type GenreInfo = components['schemas']['GenreResponse'];
+
+const CACHE_TTL_MS = 5 * 60_000;
+
+let cached: { genres: GenreInfo[]; expiresAt: number } | null = null;
+
+export async function getGenres(api: ApiClient): Promise<GenreInfo[]> {
+	if (cached && cached.expiresAt > Date.now()) return cached.genres;
+
+	const { data } = await api.GET('/genres');
+	if (!data) return cached?.genres ?? [];
+
+	cached = { genres: data, expiresAt: Date.now() + CACHE_TTL_MS };
+	return data;
+}

web-player/src/lib/server/greeting.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { pickGreeting } from './greeting';
+
+const BIRTHDAY = 'Hoy toca celebrar. Tú eliges la música.';
+
+describe('pickGreeting', () => {
+	it('uses the birthday message over special dates', () => {
+		const date = new Date(2026, 11, 25, 10);
+		expect(pickGreeting(date, { month: 12, day: 25 })).toBe(BIRTHDAY);
+	});
+	it('uses the special date message', () => {
+		expect(pickGreeting(new Date(2026, 11, 25, 10))).toBe('Feliz Navidad. Pon tu banda sonora.');
+	});
+	it('returns a non-empty schedule message at every hour', () => {
+		for (let hour = 0; hour < 24; hour++) {
+			expect(pickGreeting(new Date(2026, 2, 10, hour)).length).toBeGreaterThan(0);
+		}
+	});
+	it('ignores a birthday on another day', () => {
+		expect(pickGreeting(new Date(2026, 2, 10, 10), { month: 1, day: 2 })).not.toBe(BIRTHDAY);
+	});
+});

web-player/src/lib/server/guards.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { loginRedirect, optionalUser, requireUser } from './guards';
+
+const user = { sub: 'u1', name: 'Ana' };
+
+function redirectOf(fn: () => unknown): { status: number; location: string } {
+	try {
+		fn();
+	} catch (thrown) {
+		return thrown as { status: number; location: string };
+	}
+	throw new Error('Expected a redirect');
+}
+
+describe('loginRedirect', () => {
+	it('redirects to /auth with the encoded path and query', () => {
+		const result = redirectOf(() => loginRedirect(new URL('http://x/albums/1?tab=a&b=c')));
+		expect(result.status).toBe(302);
+		expect(result.location).toBe(`/auth?returnTo=${encodeURIComponent('/albums/1?tab=a&b=c')}`);
+	});
+});
+
+describe('requireUser', () => {
+	it('returns the user when signed in', () => {
+		const locals = { user, accessToken: 't' } as App.Locals;
+		expect(requireUser(locals, new URL('http://x/'))).toBe(user);
+	});
+
+	it('redirects when there is no user', () => {
+		const locals = { user: null, accessToken: null } as App.Locals;
+		const result = redirectOf(() => requireUser(locals, new URL('http://x/library')));
+		expect(result.location).toBe('/auth?returnTo=%2Flibrary');
+	});
+});
+
+describe('optionalUser', () => {
+	it('returns the user when signed in', () => {
+		const locals = { user, accessToken: 't' } as App.Locals;
+		expect(optionalUser(locals, new URL('http://x/'), false)).toBe(user);
+	});
+
+	it('returns null for anonymous listening', () => {
+		const locals = { user: null, accessToken: null } as App.Locals;
+		expect(optionalUser(locals, new URL('http://x/'), true)).toBeNull();
+	});
+
+	it('redirects anonymous visitors when listening is not allowed', () => {
+		const locals = { user: null, accessToken: null } as App.Locals;
+		const result = redirectOf(() => optionalUser(locals, new URL('http://x/albums/1'), false));
+		expect(result.location).toBe('/auth?returnTo=%2Falbums%2F1');
+	});
+});

web-player/src/lib/server/guards.ts

@@ -0,0 +1,21 @@
+import { redirect } from '@sveltejs/kit';
+import type { SessionUser } from '$lib/types';
+
+export function loginRedirect(url: URL): never {
+	redirect(302, `/auth?returnTo=${encodeURIComponent(url.pathname + url.search)}`);
+}
+
+export function requireUser(locals: App.Locals, url: URL): SessionUser {
+	if (!locals.user) loginRedirect(url);
+	return locals.user;
+}
+
+export function optionalUser(
+	locals: App.Locals,
+	url: URL,
+	allowAnonymousListening: boolean
+): SessionUser | null {
+	if (locals.user) return locals.user;
+	if (!allowAnonymousListening) loginRedirect(url);
+	return null;
+}

web-player/src/lib/server/image.ts

@@ -10,7 +10,9 @@ export async function proxyCoverImage(
 ): Promise<Response> {
 	const safeSize = size && ALLOWED_SIZES.has(size) ? size : 'medium';
 
-	const upstream = await fetch(`${apiConfig.baseUrl}/${kind}/${id}/cover?size=${safeSize}`);
+	const upstream = await fetch(
+		`${apiConfig.baseUrl}/${kind}/${encodeURIComponent(id)}/cover?size=${safeSize}`
+	);
 
 	if (!upstream.ok) {
 		return new Response(null, { status: upstream.status });