morille 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# morille
+
+A terminal-based Spotify player built with TypeScript, ink (React for the terminal), and the Spotify Web API.
+
+## Install & run
+
+```sh
+npx morille
+```
+
+That's it. morille ships with a default Spotify Client ID baked into the binary,
+so the app works out of the box — no registration required for most users.
+
+> Spotify Premium is required for playback control.
+
+### Running from source
+
+```sh
+pnpm install
+pnpm build
+node dist/index.js
+```
+
+### Using your own Client ID
+
+If you want to use your own Spotify app (for development, higher rate limits,
+or access to more users via [extended quota mode][quota]), override the
+embedded default with an environment variable:
+
+1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+2. Create a new app
+3. In your app settings, add `http://127.0.0.1:8888/callback` as a Redirect URI
+4. Copy the **Client ID** from your app's overview page
+5. Export it before running morille:
+   ```sh
+   export SPOTIFY_CLIENT_ID=your_client_id_here
+   npx morille
+   ```
+
+`SPOTIFY_CLIENT_ID` always takes precedence over the embedded default. To
+change the embedded default, edit `DEFAULT_SPOTIFY_CLIENT_ID` in `src/config.ts`
+and rebuild.
+
+[quota]: https://developer.spotify.com/documentation/web-api/concepts/quota-modes
+
+## Usage
+
+- **Space** - toggle play/pause
+- **n** / **Right arrow** - next track
+- **p** / **Left arrow** - previous track
+- **.** - seek forward 10s
+- **,** - seek backward 10s
+- **Up arrow** - volume up 5%
+- **Down arrow** - volume down 5%
+- **s** - toggle shuffle
+- **r** - cycle repeat (off / context / track)
+- **l** - toggle lyrics display
+- **d** - toggle queue view (up/down to navigate, enter to select)
+- **/** - search tracks, albums, artists, playlists (type to search, left/right to switch category, enter to select)
+- **b** - browse your playlists (enter to view tracks, enter to play)
+- **q** - quit
+
+## Development
+
+```sh
+pnpm install
+pnpm dev          # watch mode
+pnpm build        # compile
+pnpm test:ts      # type-check
+pnpm test:biome   # lint/format check
+```
+
+## Roadmap
+
+- Add track to queue
+- Device selection / transfer playback
+- ~~Search tracks, albums, artists, and playlists~~
+- ~~Browse and play playlists~~
+- ~~Browse and play albums~~
+- Show recently played tracks
+- Like / unlike tracks (save to library)
+- Keyboard shortcuts customization

package/dist/app.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Root application component. Handles Spotify authentication on mount,
+ * then renders the {@link Player} once connected.
+ */
+export declare function App(): import("react/jsx-runtime").JSX.Element;

package/dist/app.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useApp, useInput } from 'ink';
+import { useEffect, useRef, useState } from 'react';
+import { Player } from './components/player.js';
+import { createSpotifyClient, getClientId } from './spotify/client.js';
+/**
+ * Root application component. Handles Spotify authentication on mount,
+ * then renders the {@link Player} once connected.
+ */
+export function App() {
+    const [client, setClient] = useState(null);
+    const [authError, setAuthError] = useState(null);
+    const [authUrl, setAuthUrl] = useState(null);
+    const openBrowserRef = useRef(null);
+    const { exit } = useApp();
+    useEffect(() => {
+        let cancelled = false;
+        async function init() {
+            try {
+                const clientId = getClientId();
+                const spotify = await createSpotifyClient(clientId, {
+                    onAuthUrl: (url, openFn) => {
+                        if (!cancelled) {
+                            setAuthUrl(url);
+                            openBrowserRef.current = openFn;
+                        }
+                    },
+                });
+                if (!cancelled) {
+                    setClient(spotify);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setAuthError(err instanceof Error ? err.message : 'Authentication failed');
+                }
+            }
+        }
+        init();
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    useInput((input) => {
+        if (input === 'o' && openBrowserRef.current) {
+            openBrowserRef.current();
+        }
+    }, {
+        isActive: !client && !!authUrl,
+    });
+    useEffect(() => {
+        if (authError) {
+            exit();
+        }
+    }, [
+        authError,
+        exit,
+    ]);
+    if (authError) {
+        return (_jsx(Box, { padding: 1, children: _jsx(Text, { color: "red", children: authError }) }));
+    }
+    if (!client) {
+        return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(Text, { dimColor: true, children: "Authenticating with Spotify..." }), authUrl && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: ["Open this URL in your browser, or press ", _jsx(Text, { bold: true, children: "o" }), " to open automatically:"] }), _jsx(Text, { color: "cyan", children: authUrl })] }))] }));
+    }
+    return _jsx(Player, { client: client });
+}

package/dist/components/animated-line.d.ts

@@ -0,0 +1,12 @@
+type AnimatedLineProps = {
+    text: string;
+    progress: number;
+};
+/**
+ * Renders a text line with a karaoke-style sweep animation.
+ * Characters that have "passed" are dark green, upcoming characters are bright green.
+ * @param text - The lyric line text
+ * @param progress - Fraction of the line elapsed, from 0 to 1
+ */
+export declare function AnimatedLine({ text, progress }: AnimatedLineProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/animated-line.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from 'ink';
+/**
+ * Renders a text line with a karaoke-style sweep animation.
+ * Characters that have "passed" are dark green, upcoming characters are bright green.
+ * @param text - The lyric line text
+ * @param progress - Fraction of the line elapsed, from 0 to 1
+ */
+export function AnimatedLine({ text, progress }) {
+    const splitIndex = Math.round(Math.min(Math.max(progress, 0), 1) * text.length);
+    const passed = text.slice(0, splitIndex);
+    const upcoming = text.slice(splitIndex);
+    return (_jsxs(Text, { bold: true, children: [_jsx(Text, { color: "#0f570f", children: passed }), _jsx(Text, { color: "#0cb80c", children: upcoming })] }));
+}

package/dist/components/browse-detail-view.d.ts

@@ -0,0 +1,14 @@
+import type { BrowseData } from '../hooks/use-browse.js';
+type BrowseDetailViewProps = {
+    data: BrowseData;
+    selectedIndex: number;
+    currentTrackUri: string | null;
+    height: number;
+};
+/**
+ * Renders album or playlist track lists with a scrolling selection window.
+ * Reuses the windowing pattern from queue-view for consistent navigation.
+ * Highlights the currently playing track in green with a play icon.
+ */
+export declare function BrowseDetailView({ data, selectedIndex, currentTrackUri, height }: BrowseDetailViewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/browse-detail-view.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+/**
+ * Renders album or playlist track lists with a scrolling selection window.
+ * Reuses the windowing pattern from queue-view for consistent navigation.
+ * Highlights the currently playing track in green with a play icon.
+ */
+export function BrowseDetailView({ data, selectedIndex, currentTrackUri, height }) {
+    const headerLines = 2;
+    const listHeight = Math.max(height - headerLines, 2);
+    const items = data.tracks;
+    const halfHeight = Math.floor(listHeight / 2);
+    const startIndex = Math.max(0, Math.min(selectedIndex - halfHeight, items.length - listHeight));
+    const visibleCount = Math.min(listHeight, items.length);
+    return (_jsxs(Box, { flexDirection: "column", height: height, overflow: "hidden", children: [_jsxs(Box, { gap: 1, borderColor: "gray", borderStyle: "single", borderBottom: true, borderLeft: false, borderRight: false, borderTop: false, children: [_jsx(Text, { bold: true, children: data.title }), data.subtitle && _jsxs(Text, { dimColor: true, children: ["- ", data.subtitle] })] }), items.length === 0 && _jsx(Text, { dimColor: true, children: "No tracks found" }), Array.from({
+                length: visibleCount,
+            }, (_, i) => {
+                const idx = startIndex + i;
+                const item = items[idx];
+                if (!item)
+                    return _jsx(Text, { children: " " }, idx);
+                const label = `${item.artist} - ${item.name}`;
+                const isSelected = idx === selectedIndex;
+                const isPlaying = currentTrackUri !== null && item.uri === currentTrackUri;
+                const icon = isPlaying ? '\u25B6 ' : isSelected ? '> ' : '  ';
+                if (isPlaying) {
+                    return (_jsxs(Text, { bold: true, color: "green", inverse: isSelected, children: [icon, label] }, item.uri + idx));
+                }
+                return (_jsxs(Text, { inverse: isSelected, children: [icon, label] }, item.uri + idx));
+            })] }));
+}

package/dist/components/keyboard-hints.d.ts

@@ -0,0 +1,12 @@
+type Hint = {
+    key: string;
+    label: string;
+};
+type KeyboardHintsProps = {
+    hints: Hint[];
+};
+/**
+ * Renders a row of keyboard shortcut hints in dimmed text.
+ */
+export declare function KeyboardHints({ hints }: KeyboardHintsProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/keyboard-hints.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+/**
+ * Renders a row of keyboard shortcut hints in dimmed text.
+ */
+export function KeyboardHints({ hints }) {
+    return (_jsx(Box, { marginTop: 1, gap: 1, flexWrap: "wrap", children: hints.map((hint) => (_jsxs(Text, { dimColor: true, children: [_jsx(Text, { bold: true, dimColor: true, children: hint.key }), ":", hint.label] }, hint.key))) }));
+}

package/dist/components/lyrics-panel.d.ts

@@ -0,0 +1,10 @@
+type LyricsPanelProps = {
+    progressMs: number;
+    height: number;
+};
+/**
+ * Renders lyrics content from LyricsContext.
+ * Shows loading state, synced lyrics view, plain text fallback, or no-lyrics message.
+ */
+export declare function LyricsPanel({ progressMs, height }: LyricsPanelProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/lyrics-panel.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useLyricsContext } from '../contexts/lyrics-context.js';
+import { LyricsView } from './lyrics-view.js';
+/**
+ * Renders plain text lyrics in a scrollable view.
+ * Scrolls via keyboard (up/down arrows).
+ */
+function PlainLyricsView({ text, scrollPosition, height }) {
+    const lines = text.split('\n');
+    const maxStart = Math.max(lines.length - height, 0);
+    const startIndex = Math.min(scrollPosition, maxStart);
+    const visible = lines.slice(startIndex, startIndex + height);
+    return (_jsx(Box, { flexDirection: "column", height: height, overflow: "hidden", children: visible.map((line, offset) => {
+            const lineIndex = startIndex + offset;
+            return (_jsx(Text, { dimColor: true, children: line || ' ' }, lineIndex));
+        }) }));
+}
+/**
+ * Renders lyrics content from LyricsContext.
+ * Shows loading state, synced lyrics view, plain text fallback, or no-lyrics message.
+ */
+export function LyricsPanel({ progressMs, height }) {
+    const { lyrics, isLoading, offset, scrollPosition } = useLyricsContext();
+    if (isLoading) {
+        return _jsx(Text, { dimColor: true, children: "Loading lyrics..." });
+    }
+    if (!lyrics) {
+        return _jsx(Text, { dimColor: true, children: "No lyrics available" });
+    }
+    if (lyrics.synced.length > 0) {
+        return _jsx(LyricsView, { lyrics: lyrics.synced, progressMs: progressMs, height: height, offsetMs: offset });
+    }
+    if (lyrics.plain) {
+        return _jsx(PlainLyricsView, { text: lyrics.plain, scrollPosition: scrollPosition, height: height });
+    }
+    return _jsx(Text, { dimColor: true, children: "No lyrics available" });
+}

package/dist/components/lyrics-view.d.ts

@@ -0,0 +1,14 @@
+import type { LyricLine } from '../spotify/lyrics.js';
+type LyricsViewProps = {
+    lyrics: LyricLine[];
+    progressMs: number;
+    height: number;
+    offsetMs: number;
+};
+/**
+ * Scrolling lyrics display synchronized with playback progress.
+ * Current line has a karaoke sweep animation (dark green → bright green).
+ * Past lines are gray (dimColor), upcoming lines are white.
+ */
+export declare function LyricsView({ lyrics, progressMs, height, offsetMs }: LyricsViewProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/lyrics-view.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { getCurrentLineIndex } from '../spotify/lyrics.js';
+import { AnimatedLine } from './animated-line.js';
+function LyricSlot({ line, isCurrent, isPast, lineProgress }) {
+    if (isCurrent) {
+        return _jsx(AnimatedLine, { text: line.text || '\u266A', progress: lineProgress });
+    }
+    if (isPast) {
+        return _jsx(Text, { dimColor: true, children: line.text || ' ' });
+    }
+    return _jsx(Text, { children: line.text || ' ' });
+}
+function computeLineProgress(lyrics, index, progressMs, offsetMs) {
+    const currentTime = lyrics[index].timeMs;
+    const nextLine = index + 1 < lyrics.length ? lyrics[index + 1] : undefined;
+    const lineDuration = nextLine ? nextLine.timeMs - currentTime : 5000;
+    return lineDuration > 0 ? (progressMs - currentTime + offsetMs) / lineDuration : 1;
+}
+/**
+ * Scrolling lyrics display synchronized with playback progress.
+ * Current line has a karaoke sweep animation (dark green → bright green).
+ * Past lines are gray (dimColor), upcoming lines are white.
+ */
+export function LyricsView({ lyrics, progressMs, height, offsetMs }) {
+    const currentIndex = getCurrentLineIndex(lyrics, progressMs, offsetMs);
+    const halfHeight = Math.floor(height / 2);
+    const startIndex = currentIndex - halfHeight;
+    const slots = [];
+    for (let i = 0; i < height; i++) {
+        const idx = startIndex + i;
+        if (idx >= 0 && idx < lyrics.length) {
+            slots.push({
+                index: idx,
+                line: lyrics[idx],
+            });
+        }
+        else {
+            slots.push({
+                index: idx,
+            });
+        }
+    }
+    return (_jsx(Box, { flexDirection: "column", height: height, overflow: "hidden", children: slots.map((slot) => {
+            if (!slot.line) {
+                return _jsx(Text, { children: " " }, slot.index);
+            }
+            return (_jsx(LyricSlot, { line: slot.line, isCurrent: slot.index === currentIndex, isPast: slot.index < currentIndex, lineProgress: slot.index === currentIndex ? computeLineProgress(lyrics, slot.index, progressMs, offsetMs) : 0 }, slot.index));
+        }) }));
+}

package/dist/components/panel-content.d.ts

@@ -0,0 +1,10 @@
+type PanelContentProps = {
+    progressMs: number;
+    height: number;
+};
+/**
+ * Renders the active panel content based on the current panel mode.
+ * Reads panel mode from context; child components read their own data from their contexts.
+ */
+export declare function PanelContent({ progressMs, height }: PanelContentProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/panel-content.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePanelMode } from '../contexts/panel-mode-context.js';
+import { LyricsPanel } from './lyrics-panel.js';
+import { QueueView } from './queue-view.js';
+import { SearchPanel } from './search-panel.js';
+/**
+ * Renders the active panel content based on the current panel mode.
+ * Reads panel mode from context; child components read their own data from their contexts.
+ */
+export function PanelContent({ progressMs, height }) {
+    const { panelMode } = usePanelMode();
+    if (panelMode === 'lyrics') {
+        return _jsx(LyricsPanel, { progressMs: progressMs, height: height });
+    }
+    if (panelMode === 'queue') {
+        return _jsx(QueueView, { height: height });
+    }
+    if (panelMode === 'search') {
+        return _jsx(SearchPanel, { height: height });
+    }
+    return null;
+}

package/dist/components/playback-status.d.ts

@@ -0,0 +1,16 @@
+import type { TrackInfo } from '../spotify/playback.js';
+type PlaybackStatusProps = {
+    track: TrackInfo | null;
+    isLoading: boolean;
+    error: string | null;
+    art: string | null;
+    progressBarWidth: number;
+};
+/**
+ * Renders the main playback area: loading skeleton, error, no-playback message,
+ * or the current track info with optional album art.
+ * During initial load, renders a shimmer skeleton matching the final layout to
+ * avoid flicker when data arrives.
+ */
+export declare function PlaybackStatus({ track, isLoading, error, art, progressBarWidth }: PlaybackStatusProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/playback-status.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { TrackInfoView } from './track-info.js';
+import { TrackInfoSkeleton } from './track-info-skeleton.js';
+/**
+ * Renders the main playback area: loading skeleton, error, no-playback message,
+ * or the current track info with optional album art.
+ * During initial load, renders a shimmer skeleton matching the final layout to
+ * avoid flicker when data arrives.
+ */
+export function PlaybackStatus({ track, isLoading, error, art, progressBarWidth }) {
+    if (error) {
+        return _jsx(Text, { color: "red", children: error });
+    }
+    if (isLoading && !track) {
+        return _jsx(TrackInfoSkeleton, { progressBarWidth: progressBarWidth });
+    }
+    if (!track) {
+        return _jsx(Text, { dimColor: true, children: "No active playback. Start playing on any Spotify client." });
+    }
+    return (_jsxs(Box, { children: [art && (_jsx(Box, { marginRight: 2, flexShrink: 0, children: _jsx(Text, { children: art }) })), _jsx(TrackInfoView, { track: track, progressBarWidth: progressBarWidth })] }));
+}

package/dist/components/player.d.ts

@@ -0,0 +1,9 @@
+import type { SpotifyApi } from '@spotify/web-api-ts-sdk';
+type PlayerProps = {
+    client: SpotifyApi;
+};
+/**
+ * Player component wrapped with context providers.
+ */
+export declare function Player({ client }: PlayerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.d.ts","sourceRoot":"","sources":["../../src/components/player.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiB1D,KAAK,WAAW,GAAG;IACjB,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAmLF;;GAEG;AACH,wBAAgB,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,WAAW,2CAM7C"}