Merge pull request #35 from NuclearPlayer/feat/dashboard

Dashboard

Author: nukeop

AGENTS.md

@@ -193,6 +193,12 @@ Tests use Vitest + React Testing Library. Globals enabled (`describe`, `it`, `ex
 - When semantic queries aren't possible, add `data-testid` attributes. And don't be shy with them
 - Don't use defensive measures like try-catch or conditional checks in tests. The test will fail anyway if our assumptions are wrong.
 
+### Test-first for views
+
+When building a new view, write the test wrapper and tests **before** any implementation code. The tests describe what the user sees and does — they define the contract. Then implement to make them pass.
+
+Don't start with unit tests for internal utilities (grouping functions, registries, etc.). Start from the outside: what does the user see on the page? The internal structure is an implementation detail that falls out of making the tests green.
+
 ### Test Wrappers for Views
 
 Player views and some components use a `*.test-wrapper.tsx` file that creates a domain-specific abstraction layer over the DOM. This lets tests read like user stories, and if the implementation changes, only the wrapper needs updating.
@@ -206,6 +212,43 @@ Player views and some components use a `*.test-wrapper.tsx` file that creates a
 - Don't use queryX methods in the wrapper - always get or find as appropriate.
 - Never use fireEvent. Always use userEvent for interactions.
 
+### Test fixtures
+
+To populate the app with testing data, use fixtures. See `packages/player/src/test/fixtures` for examples.
+
+### Wrapper fixtures
+
+Test wrappers can expose a `fixtures` object with factory methods that return pre-configured builders for common test scenarios. This keeps test setup readable and co-located with the wrapper, while the raw fixture data itself lives in `packages/player/src/test/fixtures/`.
+
+```tsx
+// Dashboard.test-wrapper.tsx
+import { TOP_TRACKS_RADIOHEAD } from '../../test/fixtures/dashboard';
+
+export const DashboardWrapper = {
+  // ... mount, getters, etc.
+
+  fixtures: {
+    topTracksProvider() {
+      return new DashboardProviderBuilder()
+        .withCapabilities('topTracks')
+        .withFetchTopTracks(async () => TOP_TRACKS_RADIOHEAD);
+    },
+  },
+};
+
+// Dashboard.test.tsx
+DashboardWrapper.seedProvider(DashboardWrapper.fixtures.topTracksProvider());
+```
+
+### The builder pattern for tests
+
+We use builders to create test data and various entities cleanly. You can see them in `packages/player/src/test/builders`.
+
+- A builder is a class that has an instance of the object it's building
+- When the builder is instantiated, it creates a default object with reasonable defaults
+- The builder has methods that mutate the object and return `this` for chaining
+- The `build()` method returns the final object, which can then be used in tests
+
 ```tsx
 // Playlists.test-wrapper.tsx
 export const PlaylistsWrapper = {

packages/docs/README.md

@@ -1,5 +1,5 @@
 ---
-description: Nuclear Music Player. Play the web!
+description: Nuclear Music Player docs
 ---
 
 # Nuclear Documentation
@@ -19,7 +19,7 @@ Nuclear is a free, open‑source music player that acts as a hub for many servic
 ## For users
 
 - Themes: Nuclear supports theming. You can load your own JSON themes or choose built‑ins.
-- Plugins: Extend Nuclear with plugins. There is no sandbox—plugins can control the player directly. Only install plugins you trust.
+- Plugins: Extend Nuclear with plugins. There is no sandbox, plugins can control the player directly. Only install plugins you trust.
 
 ## What is in this repo?
 
@@ -42,7 +42,7 @@ This is a pnpm/turbo monorepo with these major packages:
 - TypeScript everywhere
 - Tauri (desktop shell)
 - React 18
-- Tailwind v4 configured via CSS (@theme/@layer) — no tailwind.config.js
+- Tailwind v4 configured via CSS (@theme/@layer), no tailwind.config.js
 - TanStack Router (routing)
 - TanStack Query v5 (HTTP and client‑side server state; no backend server)
 - Vitest + React Testing Library (tests)

packages/docs/SUMMARY.md

@@ -9,6 +9,7 @@
 * [Favorites](plugins/favorites.md)
 * [Streaming](plugins/streaming.md)
 * [Metadata](plugins/metadata.md)
+* [Dashboard](plugins/dashboard.md)
 * [Providers](plugins/providers.md)
 
 ## Theming

packages/docs/plugins/dashboard.md

@@ -0,0 +1,131 @@
+---
+description: Supply dashboard content: top tracks, trending artists, curated playlists, and more.
+---
+
+# Dashboard
+
+## Dashboard Providers
+
+Dashboard providers supply Nuclear's home screen with content like charts, trending artists, new releases, and curated playlists. When you open the player, Nuclear calls each registered dashboard provider and assembles the results into an overview. Without a dashboard provider, the dashboard shows an empty state prompting the user to enable a plugin.
+
+Plugins can either add a new dashboard provider, or consume dashboard data from existing providers.
+
+---
+
+## Implementing a provider
+
+### Minimal example
+
+You register dashboard providers with `api.Providers.register()` just like any other provider. It needs an `id`, `kind: 'dashboard'`, a `name`, a `metadataProviderId`, and a list of `capabilities` declaring which content it can supply:
+
+```typescript
+import type { DashboardProvider, NuclearPlugin, NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';
+
+const provider: DashboardProvider = {
+  id: 'acme-dashboard',
+  kind: 'dashboard',
+  name: 'Acme Music',
+
+  metadataProviderId: 'acme-metadata',
+  capabilities: ['topTracks', 'newReleases'],
+
+  async fetchTopTracks() {
+    // Call your API, return Track[]
+  },
+  async fetchNewReleases() {
+    // Call your API, return AlbumRef[]
+  },
+};
+
+const plugin: NuclearPlugin = {
+  onEnable(api: NuclearPluginAPI) {
+    api.Providers.register(provider);
+  },
+  onDisable(api: NuclearPluginAPI) {
+    api.Providers.unregister('acme-dashboard');
+  },
+};
+
+export default plugin;
+```
+
+{% hint style="warning" %}
+Always unregister your provider in `onDisable`. If you don't, it stays registered and Nuclear will keep calling it after the plugin is disabled.
+{% endhint %}
+
+### Capabilities
+
+Capabilities tell Nuclear which content your provider can fetch. Nuclear only calls methods for capabilities you declare. If you don't list `'topArtists'`, `fetchTopArtists` is never called even if you define it.
+
+| Capability | Method called | Returns | Widget |
+|------------|--------------|---------|--------|
+| `'topTracks'` | `fetchTopTracks()` | `Track[]` | Track table with playback controls |
+| `'topArtists'` | `fetchTopArtists()` | `ArtistRef[]` | Artist card row |
+| `'topAlbums'` | `fetchTopAlbums()` | `AlbumRef[]` | Album card row |
+| `'editorialPlaylists'` | `fetchEditorialPlaylists()` | `PlaylistRef[]` | Playlist card row |
+| `'newReleases'` | `fetchNewReleases()` | `AlbumRef[]` | Album card row |
+
+{% hint style="info" %}
+Nuclear only calls methods for declared capabilities. Declare only the ones you actually implement.
+{% endhint %}
+
+Note that `fetchTopTracks` returns full `Track[]` objects, not `TrackRef[]`. The dashboard track table needs complete track data (title, artist, duration, thumbnail) to render without additional lookups.
+
+---
+
+## The `metadataProviderId` field
+
+Every dashboard provider must specify a `metadataProviderId`. This tells Nuclear which metadata provider can look up the entities your dashboard returns.
+
+When a user clicks an artist or album on the dashboard, Nuclear navigates to a detail page. It needs to know which metadata provider can fetch that entity's full details, that's what `metadataProviderId` is for. If you set it to a provider that doesn't exist or can't resolve your IDs, artist and album links from the dashboard will fail.
+
+Typically, your plugin registers both a metadata provider and a dashboard provider, and they share the same underlying API. Point `metadataProviderId` at your metadata provider's `id`.
+
+---
+
+## Attributed results
+
+When multiple dashboard providers are registered, Nuclear will render results from all of them. The API wraps each provider's data in an `AttributedResult<T>`:
+
+```typescript
+type AttributedResult<T> = {
+  providerId: string;
+  metadataProviderId: string;
+  providerName: string;
+  items: T[];
+};
+```
+
+Each attributed result carries the provider's name and IDs, so Nuclear can render labeled sections (e.g. "Top Tracks - Acme Music") and route navigation to the correct metadata provider.
+
+---
+
+## Using dashboard data
+
+Plugins can consume dashboard data from all registered providers via `api.Dashboard.*`:
+
+```typescript
+export default {
+  async onEnable(api: NuclearPluginAPI) {
+    const topTracks = await api.Dashboard.fetchTopTracks();
+
+    for (const result of topTracks) {
+      console.log(`${result.providerName}: ${result.items.length} tracks`);
+    }
+  },
+};
+```
+
+### Consumer reference
+
+```typescript
+api.Dashboard.fetchTopTracks(providerId?: string): Promise<AttributedResult<Track>[]>
+api.Dashboard.fetchTopArtists(providerId?: string): Promise<AttributedResult<ArtistRef>[]>
+api.Dashboard.fetchTopAlbums(providerId?: string): Promise<AttributedResult<AlbumRef>[]>
+api.Dashboard.fetchEditorialPlaylists(providerId?: string): Promise<AttributedResult<PlaylistRef>[]>
+api.Dashboard.fetchNewReleases(providerId?: string): Promise<AttributedResult<AlbumRef>[]>
+```
+
+All methods accept an optional `providerId`. If omitted, Nuclear queries all registered dashboard providers and returns an array with one `AttributedResult` per provider. If provided, only that provider is queried.
+
+---

packages/docs/plugins/favorites.md

@@ -30,7 +30,7 @@ Each favorite entry includes a timestamp (`addedAtIso`) recording when it was ad
 
 ### Identity and deduplication
 
-Favorites are identified by their `source` field—a combination of provider name and ID. Because each metadata provider stores music data differently, **favorites from each provider are treated separately**.
+Favorites are identified by their `source` fiels. It's a combination of provider name and ID. Because each metadata provider stores music data differently, **favorites from each provider are treated separately**.
 
 ```typescript
 type ProviderRef = {

packages/docs/plugins/providers.md

@@ -1,28 +1,79 @@
 ---
-description: Extend Nuclear with custom metadata providers through the Providers API.
+description: Register providers that supply metadata, audio streams, dashboard content, and more to Nuclear.
 ---
 
 # Providers
 
 ## Providers API for Plugins
 
-The Providers API allows plugins to register custom providers that supply metadata for tracks, albums, and artists. This enables Nuclear to integrate with any music service or database.
+Providers are modules that fulfill specific data requests from Nuclear. When the player needs to search for tracks, stream audio, or populate the dashboard, it queries the providers for that kind of request. Different provider kinds serve different purposes, and plugins can register as many providers as they need.
+
+All registration and lookup goes through `api.Providers`.
 
 {% hint style="info" %}
-Access providers via `NuclearAPI.Providers.*` in your plugin's lifecycle hooks. Only metadata providers are supported.
+Every provider extends the `ProviderDescriptor` base type, which requires an `id`, `kind`, and `name`. Each provider kind then adds its own domain-specific methods (e.g., `search` for metadata, `getStreamUrl` for streaming).
 {% endhint %}
 
----
+## Provider kinds
+
+| Kind | Purpose | Guide |
+|------|---------|-------|
+| `'metadata'` | Search results, artist & album details | [Metadata](metadata.md) |
+| `'streaming'` | Audio stream URLs for playback | [Streaming](streaming.md) |
+| `'dashboard'` | Dashboard content (top tracks, new releases, etc.) | [Dashboard](dashboard.md) |
+| `'lyrics'` | Song lyrics *(planned)* | N/A |
+
+## Registration
+
+Register providers in your plugin's `onEnable` hook and unregister them in `onDisable`:
+
+```ts
+import type { NuclearPluginAPI, MetadataProvider } from '@nuclearplayer/plugin-sdk';
+
+let providerId: string;
+
+export default {
+  onEnable(api: NuclearPluginAPI) {
+    const provider: MetadataProvider = {
+      id: 'my-metadata-source',
+      kind: 'metadata',
+      name: 'My Metadata Source',
+      search: async (query) => { /* ... */ },
+      fetchArtist: async (artistId) => { /* ... */ },
+      fetchAlbum: async (albumId) => { /* ... */ },
+    };
+
+    providerId = api.Providers.register(provider);
+  },
+
+  onDisable(api: NuclearPluginAPI) {
+    api.Providers.unregister(providerId);
+  },
+};
+```
+
+`register()` returns the provider's ID, which you pass to `unregister()` later.
+
+## Provider lifecycle
+
+Always register in `onEnable` and unregister in `onDisable`. If you skip unregistration, the provider stays in Nuclear's registry after your plugin is disabled, and the player may still pass queries to that phantom provider.
 
-## Core concepts
+| Hook | Action |
+|------|--------|
+| `onEnable` | `api.Providers.register(provider)` |
+| `onDisable` | `api.Providers.unregister(providerId)` |
 
-### What are providers?
+## Base type
 
-Providers are modules that fulfill specific data requests from Nuclear. When the app needs information (like album art, track metadata, or artist details), it queries the selected provider.
+All providers share this shape:
 
-### Provider types
+```ts
+type ProviderDescriptor<K extends ProviderKind = ProviderKind> = {
+  id: string;
+  kind: K;
+  name: string;
+  pluginId?: string;
+};
+```
 
-**Metadata Providers** (current)
-- Supply information about tracks, albums, and artists
-- Examples: MusicBrainz, Last.fm, Discogs
-- Used for search, library management, and display
+Each provider kind (e.g., `MetadataProvider`, `StreamingProvider`, `DashboardProvider`) extends `ProviderDescriptor` with its own methods. See the individual guides linked above for details.

packages/i18n/src/locales/en_US.json

@@ -144,7 +144,18 @@
   },
   "dashboard": {
     "title": "Dashboard",
-    "content": "Dashboard view"
+    "empty-state": "No dashboard data available",
+    "empty-state-description": "Enable a plugin that provides dashboard content.",
+    "top-tracks": "Top Tracks",
+    "top-artists": "Top Artists",
+    "top-albums": "Top Albums",
+    "editorial-playlists": "Top Playlists",
+    "new-releases": "New Releases",
+    "filter-artists": "Filter artists...",
+    "filter-albums": "Filter albums...",
+    "filter-playlists": "Filter playlists...",
+    "filter-releases": "Filter releases...",
+    "nothing-found": "Nothing found"
   },
   "plugins": {
     "title": "Plugins",

packages/player/src-tauri/src/main.rs

@@ -10,13 +10,24 @@ fn main() {
 
 #[cfg(target_os = "linux")]
 fn apply_linux_workarounds() {
-    // Fix for WebKitGTK DMA-BUF renderer causing "Could not create default EGL display:
-    // EGL_BAD_PARAMETER" on various Linux systems including Steam Deck, NVIDIA GPUs,
-    // and certain Wayland compositors.
+    // Fix for WebKitGTK GPU rendering failures on various Linux systems including
+    // Steam Deck, NVIDIA GPUs, and W**land compositors.
+    //
+    // WEBKIT_DISABLE_DMABUF_RENDERER: Fixes "Could not create default EGL display:
+    // EGL_BAD_PARAMETER" and blank screens on NVIDIA.
     // See: https://github.com/tauri-apps/tauri/issues/9394
+    //
+    // WEBKIT_DISABLE_COMPOSITING_MODE: Fixes "Failed to get GBM device" errors
+    // and crashes on resize with NVIDIA/Steam Deck.
+    // See: https://github.com/tauri-apps/tauri/issues/11994
     if std::env::var("WEBKIT_DISABLE_DMABUF_RENDERER").is_err() {
         unsafe {
             std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");
         }
     }
+    if std::env::var("WEBKIT_DISABLE_COMPOSITING_MODE").is_err() {
+        unsafe {
+            std::env::set_var("WEBKIT_DISABLE_COMPOSITING_MODE", "1");
+        }
+    }
 }