{/* Track info */}
diff --git a/frontend/src/hooks/useInstallPrompt.ts b/frontend/src/hooks/useInstallPrompt.ts
new file mode 100644
index 0000000..fdac729
--- /dev/null
+++ b/frontend/src/hooks/useInstallPrompt.ts
@@ -0,0 +1,107 @@
+import { useEffect } from 'react';
+import { useToastStore, toast } from '../store/useToastStore';
+
+/**
+ * Chrome fires `beforeinstallprompt` when the app qualifies for installation.
+ * Not in lib.dom yet, so the shape is declared here.
+ */
+interface BeforeInstallPromptEvent extends Event {
+ prompt: () => Promise;
+ userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+}
+
+const SNOOZE_KEY = 'muzick.install-prompt.snoozed-at';
+const SNOOZE_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Long enough that the suggestion lands after the app has proved useful, not
+// while the first page is still painting.
+const DELAY_MS = 20_000;
+
+function snoozed(): boolean {
+ try {
+ const at = Number(localStorage.getItem(SNOOZE_KEY));
+ return Number.isFinite(at) && at > 0 && Date.now() - at < SNOOZE_MS;
+ } catch {
+ return false; // Private mode or blocked storage — just ask.
+ }
+}
+
+function snooze() {
+ try {
+ localStorage.setItem(SNOOZE_KEY, String(Date.now()));
+ } catch {
+ /* ignore */
+ }
+}
+
+/**
+ * Offers "Add to Home screen" as a toast, once the browser says the app is
+ * installable. Declining snoozes the suggestion for a month; installing
+ * silences it for good.
+ */
+export function useInstallPrompt() {
+ useEffect(() => {
+ // Already installed — the standalone display mode is the reliable signal.
+ if (window.matchMedia?.('(display-mode: standalone)').matches) return;
+ if (snoozed()) return;
+
+ let deferred: BeforeInstallPromptEvent | null = null;
+ let timer: ReturnType | undefined;
+ let unsubscribe: (() => void) | undefined;
+
+ const offer = () => {
+ if (!deferred) return;
+ const event = deferred;
+ let accepted = false;
+
+ const id = toast.info('Muzick runs better from your home screen.', {
+ ttl: 0,
+ action: {
+ label: 'Install',
+ onClick: () => {
+ accepted = true;
+ unsubscribe?.();
+ // A prompt can only be shown once per event; drop it either way.
+ deferred = null;
+ void event.prompt().then(() => event.userChoice).then((choice) => {
+ if (choice.outcome === 'dismissed') snooze();
+ }).catch(() => snooze());
+ },
+ },
+ });
+
+ // The toast's own close button calls dismiss() directly, so the only way
+ // to notice a decline is to watch the toast leave the store.
+ unsubscribe = useToastStore.subscribe((state) => {
+ if (accepted) return;
+ if (!state.toasts.some((t) => t.id === id)) {
+ snooze();
+ unsubscribe?.();
+ }
+ });
+ };
+
+ const onBeforeInstallPrompt = (e: Event) => {
+ // Suppress Chrome's own mini-infobar so only our toast asks.
+ e.preventDefault();
+ deferred = e as BeforeInstallPromptEvent;
+ timer = setTimeout(offer, DELAY_MS);
+ };
+
+ const onInstalled = () => {
+ deferred = null;
+ if (timer) clearTimeout(timer);
+ snooze();
+ };
+
+ window.addEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+ window.addEventListener('appinstalled', onInstalled);
+
+ return () => {
+ window.removeEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+ window.removeEventListener('appinstalled', onInstalled);
+ if (timer) clearTimeout(timer);
+ unsubscribe?.();
+ };
+ }, []);
+}
diff --git a/frontend/src/index.css b/frontend/src/index.css
index 9d4220d..784d3a9 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -112,6 +112,19 @@ input[type='range'] {
-webkit-tap-highlight-color: transparent;
}
+/* ── Safe area ────────────────────────────────────────────────────────────────
+ Installed on Android the app paints edge to edge (viewport-fit=cover), so the
+ gesture bar and any display cutout sit on top of the layout. These add the
+ inset on top of whatever padding the element already carries. */
+.safe-b {
+ padding-bottom: calc(var(--safe-b-base, 0px) + env(safe-area-inset-bottom));
+}
+
+.safe-x {
+ padding-left: calc(var(--safe-x-base, 0px) + env(safe-area-inset-left));
+ padding-right: calc(var(--safe-x-base, 0px) + env(safe-area-inset-right));
+}
+
@media (pointer: coarse) {
input[type='range']::-webkit-slider-thumb {
width: 18px;
diff --git a/frontend/src/router.tsx b/frontend/src/router.tsx
index 874dfb3..bea429d 100644
--- a/frontend/src/router.tsx
+++ b/frontend/src/router.tsx
@@ -2,22 +2,29 @@ import {
createRootRoute,
createRoute,
createRouter,
+ lazyRouteComponent,
} from '@tanstack/react-router';
import { z } from 'zod';
import AppShell from './components/AppShell';
+import { LoadingState } from './components/LoadingState';
import Home from './pages/Home';
-import Artists from './pages/Artists';
-import ArtistDetail from './pages/ArtistDetail';
-import Albums from './pages/Albums';
-import AlbumDetail from './pages/AlbumDetail';
-import Tracks from './pages/Tracks';
-import Genres from './pages/Genres';
-import Vibe from './pages/Vibe';
-import Recommendations from './pages/Recommendations';
-import Search from './pages/Search';
-import Settings from './pages/Settings';
-import Quarantine from './pages/Quarantine';
-import Jobs from './pages/Jobs';
+
+// Home is imported eagerly: it is the landing route, and deferring it would put
+// a second round trip in front of the first paint. Every other page is a
+// separate chunk, fetched when the listener first goes there and then held by
+// the service worker.
+const Artists = lazyRouteComponent(() => import('./pages/Artists'));
+const ArtistDetail = lazyRouteComponent(() => import('./pages/ArtistDetail'));
+const Albums = lazyRouteComponent(() => import('./pages/Albums'));
+const AlbumDetail = lazyRouteComponent(() => import('./pages/AlbumDetail'));
+const Tracks = lazyRouteComponent(() => import('./pages/Tracks'));
+const Genres = lazyRouteComponent(() => import('./pages/Genres'));
+const Vibe = lazyRouteComponent(() => import('./pages/Vibe'));
+const Recommendations = lazyRouteComponent(() => import('./pages/Recommendations'));
+const Search = lazyRouteComponent(() => import('./pages/Search'));
+const Settings = lazyRouteComponent(() => import('./pages/Settings'));
+const Quarantine = lazyRouteComponent(() => import('./pages/Quarantine'));
+const Jobs = lazyRouteComponent(() => import('./pages/Jobs'));
// Root route renders the AppShell (NavRail + TopBar + PlaybackBar + NowPlayingPanel)
// with an where the active child route renders.
@@ -122,7 +129,12 @@ const routeTree = rootRoute.addChildren([
jobsRoute,
]);
-export const router = createRouter({ routeTree });
+export const router = createRouter({
+ routeTree,
+ // Shown while a route's chunk is in flight. Without it the shell holds the
+ // previous page and the tap reads as a dropped input.
+ defaultPendingComponent: () => ,
+});
// Type-safety: register the router instance type globally.
declare module '@tanstack/react-router' {
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
index 3da3662..6de333a 100644
--- a/frontend/vite.config.js
+++ b/frontend/vite.config.js
@@ -1,8 +1,65 @@
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
+import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
- plugins: [react()],
+ plugins: [
+ react(),
+ VitePWA({
+ registerType: 'autoUpdate',
+ includeAssets: ['favicon-32.png', 'apple-touch-icon.png'],
+ manifest: {
+ name: 'Muzick',
+ short_name: 'Muzick',
+ description: 'Self-hosted music player and recommendation engine',
+ start_url: '/',
+ scope: '/',
+ display: 'standalone',
+ orientation: 'portrait',
+ background_color: '#14110D',
+ theme_color: '#14110D',
+ icons: [
+ { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+ {
+ src: '/icon-maskable-512.png',
+ sizes: '512x512',
+ type: 'image/png',
+ purpose: 'maskable',
+ },
+ ],
+ },
+ workbox: {
+ globPatterns: ['**/*.{js,css,html,woff2}'],
+
+ // The SPA fallback must never swallow the API: /api/playback/stream is a
+ // long-lived SSE channel and the track endpoints stream audio. Both look
+ // like navigations to Workbox unless they are denied here.
+ navigateFallback: '/index.html',
+ navigateFallbackDenylist: [/^\/api\//],
+
+ // A waiting service worker would otherwise activate and reload the page
+ // mid-song. Letting it wait means updates land on the next cold start,
+ // which is the right trade for a player that runs in the background.
+ skipWaiting: false,
+ clientsClaim: false,
+
+ runtimeCaching: [
+ {
+ // Artwork only. Audio is deliberately absent: range requests and
+ // multi-megabyte bodies do not belong in the shell cache.
+ urlPattern: ({ request }) => request.destination === 'image',
+ handler: 'CacheFirst',
+ options: {
+ cacheName: 'muzick-artwork',
+ expiration: { maxEntries: 300, maxAgeSeconds: 60 * 60 * 24 * 30 },
+ cacheableResponse: { statuses: [0, 200] },
+ },
+ },
+ ],
+ },
+ }),
+ ],
test: {
environment: 'jsdom',
setupFiles: './src/test/setup.ts',
@@ -18,5 +75,15 @@ export default defineConfig({
build: {
outDir: 'dist',
emptyOutDir: true,
+ rollupOptions: {
+ output: {
+ // The framework changes on an npm upgrade, the app changes every
+ // deploy. Splitting them means a redeploy re-downloads app code only,
+ // which matters here because the service worker precaches the lot.
+ manualChunks: {
+ vendor: ['react', 'react-dom', '@tanstack/react-router', '@tanstack/react-query'],
+ },
+ },
+ },
}
})