muzical-ui 0.1.1

package/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### 0.1.1 (2026-05-18)
+
+
+### Features
+
+* add more settings, queue persistence ([8a759b9](https://github.com/f3rnox/muzical-ui/commit/8a759b9f9fd294a0b7c29ec6e41db04bc30c44c3))
+* add scan notification and scan on startup ([d73d5e7](https://github.com/f3rnox/muzical-ui/commit/d73d5e75112c75ceede00c3bf38cffd3ad64e48e))
+* finish musicbrainz integration and add yt data api for playback ([7641d5e](https://github.com/f3rnox/muzical-ui/commit/7641d5e9b5b169aac013814e0e6943da64e7a06c))
+* initial commit ([fe9b411](https://github.com/f3rnox/muzical-ui/commit/fe9b411d0f67a038f6ac8b3fe0a21dd7f57806f9))
+* update ([4116257](https://github.com/f3rnox/muzical-ui/commit/41162577d715056be8544406919c62dfc8309e86))
+* update ([fa94934](https://github.com/f3rnox/muzical-ui/commit/fa94934525eb72bdbcafa1eb6280d80572de2c1c))
+* update ([ba023e6](https://github.com/f3rnox/muzical-ui/commit/ba023e6080cb061ff4e38bb02e463e541393b5f8))
+* update ([a33bcf3](https://github.com/f3rnox/muzical-ui/commit/a33bcf34e449528f458ab1a2bc0eee81fa6fa5e9))
+* update ([9b1020b](https://github.com/f3rnox/muzical-ui/commit/9b1020b5b6fe6b9863e5b00eaad680687180daa9))
+* update ([d6aca7d](https://github.com/f3rnox/muzical-ui/commit/d6aca7ddd4c9e410896f3b97f664eab84148dc28))
+* update manifest for release, add bin ([5b7bba5](https://github.com/f3rnox/muzical-ui/commit/5b7bba5318727c504ab29a41611ec5636b0d4c04))
+* WIP musicbrainz ([fd51c92](https://github.com/f3rnox/muzical-ui/commit/fd51c92512511a8db6b809095d9b026dafa4f994))
+* WIP musicbrainz integration ([f47cc07](https://github.com/f3rnox/muzical-ui/commit/f47cc07d8972dd9978f4d04016efa42d8ecadf2f))
+
+
+### Bug Fixes
+
+* error ([223cbd6](https://github.com/f3rnox/muzical-ui/commit/223cbd682726a5f25a226e753f6bd7c984e1ebda))
+* linter errors ([e281e80](https://github.com/f3rnox/muzical-ui/commit/e281e80042285a5e5a45a92860762ec2e0852885))
+* linter warnings ([6c6ba71](https://github.com/f3rnox/muzical-ui/commit/6c6ba71ac268433161afe1672dfebb999c16a507))
+* queue topbar alignment ([39d24b2](https://github.com/f3rnox/muzical-ui/commit/39d24b23ff8b2503b7cd191e4048274ca5f1a57c))

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Cris Mihalache <f3rnox42@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/app/globals.css

@@ -0,0 +1,67 @@
+@import "tailwindcss";
+
+html {
+  height: 100%;
+}
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+:root {
+  --background: #fafafa;
+  --foreground: #171717;
+}
+
+.dark {
+  --background: #0a0a0a;
+  --foreground: #ededed;
+}
+
+/* Custom scrollbars (WebKit + Firefox). */
+:root {
+  --scrollbar-track: rgba(63, 63, 70, 0.15);
+  --scrollbar-thumb: rgba(161, 161, 170, 0.7);
+  --scrollbar-thumb-hover: rgba(161, 161, 170, 0.95);
+}
+
+.dark {
+  --scrollbar-track: rgba(39, 39, 42, 0.7);
+  --scrollbar-thumb: rgba(82, 82, 91, 0.9);
+  --scrollbar-thumb-hover: rgba(82, 82, 91, 1);
+}
+
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+}
+
+*::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+*::-webkit-scrollbar-track {
+  background: var(--scrollbar-track);
+}
+
+*::-webkit-scrollbar-thumb {
+  background-color: var(--scrollbar-thumb);
+  border-radius: 9999px;
+  border: 2px solid var(--scrollbar-track);
+}
+
+*::-webkit-scrollbar-thumb:hover {
+  background-color: var(--scrollbar-thumb-hover);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+body {
+  height: 100%;
+  margin: 0;
+  font-family: var(--font-sans), ui-sans-serif, system-ui, sans-serif;
+}

package/app/layout.tsx

@@ -0,0 +1,49 @@
+import type { Metadata } from 'next'
+import { Geist, Geist_Mono } from 'next/font/google'
+import Script from 'next/script'
+import { LibraryProvider } from '@/components/LibraryProvider'
+import { ThemeProvider } from '@/components/ThemeProvider'
+import { getThemeInitScript } from '@/lib/theme-init-script'
+import './globals.css'
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: 'Muzical',
+  description: 'Local music player',
+}
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      suppressHydrationWarning
+      className={`${geistSans.variable} ${geistMono.variable} h-full min-h-0 antialiased`}
+    >
+      <body className="flex h-full min-h-0 flex-col overflow-hidden bg-background font-sans text-foreground">
+        <Script
+          id="theme-init"
+          strategy="beforeInteractive"
+          dangerouslySetInnerHTML={{ __html: getThemeInitScript() }}
+        />
+        <div className="flex min-h-0 flex-1 flex-col">
+          <ThemeProvider>
+            <LibraryProvider>{children}</LibraryProvider>
+          </ThemeProvider>
+        </div>
+      </body>
+    </html>
+  );
+}

package/app/musicbrainz/page.tsx

@@ -0,0 +1,6 @@
+import { redirect } from 'next/navigation'
+
+/** Legacy route; MusicBrainz lives in the player browse panel. */
+export default function MusicBrainzPage() {
+  redirect('/?view=musicbrainz')
+}

package/app/page.tsx

@@ -0,0 +1,12 @@
+import { Suspense } from 'react'
+import MusicPlayer from '@/components/MusicPlayer'
+
+export default function Home() {
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col">
+      <Suspense fallback={null}>
+        <MusicPlayer />
+      </Suspense>
+    </div>
+  )
+}

package/app/settings/display/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next'
+import DisplaySettingsPanel from '@/components/DisplaySettingsPanel'
+
+export const metadata: Metadata = {
+  title: 'Display · Settings · Muzical',
+  description: 'Display preferences for Muzical',
+}
+
+export default function DisplaySettingsPage() {
+  return <DisplaySettingsPanel />
+}

package/app/settings/layout.tsx

@@ -0,0 +1,19 @@
+import type { Metadata } from 'next'
+import SettingsShell from '@/components/SettingsShell'
+
+export const metadata: Metadata = {
+  title: 'Settings · Muzical',
+  description: 'Configure Muzical on this device',
+}
+
+export default function SettingsLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col">
+      <SettingsShell>{children}</SettingsShell>
+    </div>
+  )
+}

package/app/settings/library/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next'
+import LibrarySettingsPanel from '@/components/LibrarySettingsPanel'
+
+export const metadata: Metadata = {
+  title: 'Library · Settings · Muzical',
+  description: 'Configure local music library scan folders',
+}
+
+export default function LibrarySettingsPage() {
+  return <LibrarySettingsPanel />
+}

package/app/settings/page.tsx

@@ -0,0 +1,5 @@
+import SettingsOverview from '@/components/SettingsOverview'
+
+export default function SettingsPage() {
+  return <SettingsOverview />
+}

package/app/settings/playback/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next'
+import PlaybackSettingsPanel from '@/components/PlaybackSettingsPanel'
+
+export const metadata: Metadata = {
+  title: 'Playback · Settings · Muzical',
+  description: 'Playback preferences for Muzical',
+}
+
+export default function PlaybackSettingsPage() {
+  return <PlaybackSettingsPanel />
+}

package/app/settings/youtube/page.tsx

@@ -0,0 +1,11 @@
+import type { Metadata } from 'next'
+import YouTubeSettingsPanel from '@/components/YouTubeSettingsPanel'
+
+export const metadata: Metadata = {
+  title: 'YouTube · Settings · Muzical',
+  description: 'YouTube Data API configuration for Muzical',
+}
+
+export default function YoutubeSettingsPage() {
+  return <YouTubeSettingsPanel />
+}

package/bin/stt-ui.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const { spawn } = require('node:child_process')
+const path = require('node:path')
+
+const packageRoot = path.resolve(__dirname, '..')
+const nextBin = require.resolve('next/dist/bin/next')
+
+const child = spawn(
+  process.execPath,
+  [nextBin, 'start', ...process.argv.slice(2)],
+  {
+    cwd: packageRoot,
+    stdio: 'inherit',
+    env: process.env,
+  },
+)
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal)
+    return
+  }
+  process.exit(code ?? 0)
+})

package/components/AlbumCoverThumb.tsx

@@ -0,0 +1,82 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useLibrary } from '@/components/LibraryProvider'
+import type { Track } from '@/types/track'
+import { getCoverBytesForTrack } from '@/lib/library/cover-bytes-cache'
+
+type AlbumCoverThumbProps = {
+  /** Representative track (e.g. first on the album) — embedded art is read from its file */
+  track: Track | undefined
+  className?: string
+}
+
+/**
+ * Loads embedded cover art for a library track and shows a square thumbnail or letter fallback.
+ */
+export default function AlbumCoverThumb(props: AlbumCoverThumbProps) {
+  const { track, className = 'h-12 w-12 shrink-0 overflow-hidden rounded-md ring-1 ring-zinc-200/80 dark:ring-zinc-700/80' } =
+    props
+  const { resolveFileForTrack } = useLibrary()
+  const [coverUrl, setCoverUrl] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    let createdUrl: string | null = null
+
+    if (!track?.library) {
+      void Promise.resolve().then(() => {
+        if (!cancelled) setCoverUrl(null)
+      })
+      return (): void => {
+        cancelled = true
+      }
+    }
+
+    const t = track
+
+    void (async (): Promise<void> => {
+      const file = await resolveFileForTrack(t)
+      if (cancelled || !file) return
+      const bytes = await getCoverBytesForTrack(t.id, file)
+      if (cancelled) return
+      if (!bytes) {
+        setCoverUrl(null)
+        return
+      }
+      const u = URL.createObjectURL(new Blob([bytes.data], { type: bytes.mime }))
+      if (cancelled) {
+        if (u) URL.revokeObjectURL(u)
+        return
+      }
+      createdUrl = u
+      setCoverUrl(u)
+    })()
+
+    return (): void => {
+      cancelled = true
+      if (createdUrl) URL.revokeObjectURL(createdUrl)
+    }
+  }, [track, resolveFileForTrack])
+
+  const letter = track?.album?.trim().charAt(0) || '♪'
+
+  return (
+    <div
+      className={[
+        'relative bg-linear-to-br from-amber-200/70 via-zinc-100 to-zinc-200 dark:from-amber-900/35 dark:via-zinc-800 dark:to-zinc-900',
+        className,
+      ].join(' ')}
+      aria-hidden
+    >
+      {coverUrl ? (
+        // eslint-disable-next-line @next/next/no-img-element -- blob URL from tags
+        <img src={coverUrl} alt="" className="absolute inset-0 h-full w-full object-cover" decoding="async" />
+      ) : (
+        <span className="flex h-full w-full items-center justify-center text-lg font-semibold tracking-tight text-amber-900/25 dark:text-zinc-600/90">
+          {letter}
+        </span>
+      )}
+    </div>
+  )
+}

package/components/BrowsePanel.tsx

@@ -0,0 +1,64 @@
+'use client'
+
+import { useCallback } from 'react'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+import LibraryBrowser from '@/components/LibraryBrowser'
+import MusicBrainzBrowser from '@/components/MusicBrainzBrowser'
+
+export type BrowseView = 'library' | 'musicbrainz'
+
+const BROWSE_VIEWS: readonly BrowseView[] = ['library', 'musicbrainz']
+
+function parseBrowseView(raw: string | null): BrowseView {
+  return raw === 'musicbrainz' ? 'musicbrainz' : 'library'
+}
+
+/**
+ * Left-panel shell: switch between local library browse and MusicBrainz discovery.
+ */
+export default function BrowsePanel() {
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  const view = parseBrowseView(searchParams.get('view'))
+
+  const setView = useCallback(
+    (next: BrowseView) => {
+      const params = new URLSearchParams(searchParams.toString())
+      if (next === 'musicbrainz') {
+        params.set('view', 'musicbrainz')
+      } else {
+        params.delete('view')
+      }
+      const qs = params.toString()
+      router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false })
+    },
+    [pathname, router, searchParams],
+  )
+
+  return (
+    <div className="flex h-full min-h-0 flex-1 flex-col overflow-hidden">
+      <div className="flex h-11 shrink-0 items-center gap-1 border-b border-zinc-200 bg-white/80 px-3 dark:border-zinc-800 dark:bg-zinc-950/80">
+        {BROWSE_VIEWS.map((id) => (
+          <button
+            key={id}
+            type="button"
+            onClick={() => setView(id)}
+            className={[
+              'cursor-pointer rounded-full px-3 py-1.5 text-xs font-medium capitalize transition',
+              view === id
+                ? 'bg-amber-500 text-zinc-950'
+                : 'bg-zinc-200 text-zinc-700 hover:bg-zinc-300 dark:bg-zinc-800 dark:text-zinc-300 dark:hover:bg-zinc-700',
+            ].join(' ')}
+            aria-pressed={view === id}
+          >
+            {id === 'musicbrainz' ? 'MusicBrainz' : 'Library'}
+          </button>
+        ))}
+      </div>
+      <div className="min-h-0 flex-1 overflow-hidden">
+        {view === 'library' ? <LibraryBrowser /> : <MusicBrainzBrowser />}
+      </div>
+    </div>
+  )
+}

package/components/DisplaySettingsPanel.tsx

@@ -0,0 +1,30 @@
+'use client'
+
+import { useLibrary } from '@/components/LibraryProvider'
+import SettingsSwitchRow from '@/components/SettingsSwitchRow'
+
+/**
+ * Display settings: list density and related UI preferences.
+ */
+export default function DisplaySettingsPanel() {
+  const { compactLists, setCompactLists } = useLibrary()
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div>
+        <h2 className="text-lg font-semibold tracking-tight text-zinc-900 dark:text-zinc-100">Display</h2>
+        <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">Adjust how lists and panels look in the player.</p>
+      </div>
+
+      <section className="rounded-2xl border border-zinc-200 bg-white p-6 shadow-sm dark:border-zinc-800 dark:bg-zinc-900/40">
+        <SettingsSwitchRow
+          title="Compact UI"
+          description="Tighter spacing in the player, queue, and library browser."
+          checked={compactLists}
+          onChange={setCompactLists}
+          ariaLabel="Enable compact UI"
+        />
+      </section>
+    </div>
+  )
+}

package/components/FavoriteStarButton.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+type FavoriteStarButtonProps = {
+  filled: boolean
+  onPress: () => void
+  label: string
+  /** Merged after base styles; omit for default circular hit target. */
+  className?: string
+}
+
+/**
+ * Toggle control for favoriting artists, albums, or tracks.
+ */
+export default function FavoriteStarButton(props: FavoriteStarButtonProps) {
+  const { filled, onPress, label, className } = props
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation()
+        e.preventDefault()
+        onPress()
+      }}
+      aria-label={label}
+      aria-pressed={filled}
+      className={[
+        'inline-flex h-7 w-7 shrink-0 items-center justify-center self-center leading-none text-amber-600 transition hover:bg-amber-500/15 hover:text-amber-700 dark:text-amber-400 dark:hover:bg-amber-500/10 dark:hover:text-amber-300',
+        className ?? 'rounded-full',
+      ].join(' ')}
+    >
+      <svg viewBox="0 0 24 24" className="block h-4 w-4 shrink-0" fill={filled ? 'currentColor' : 'none'} aria-hidden>
+        <path
+          stroke="currentColor"
+          strokeWidth="1.75"
+          strokeLinejoin="round"
+          d="M12 3.5l2.35 4.76 5.26.77-3.8 3.7.9 5.24L12 15.9 6.29 18l.9-5.24-3.8-3.7 5.26-.77L12 3.5z"
+        />
+      </svg>
+    </button>
+  )
+}