@brika/plugin-spotify 0.3.0

package/README.md

@@ -0,0 +1,56 @@
+# Spotify Connect
+
+Spotify playback controller for BRIKA dashboards. Displays now-playing info, album art, and provides full transport controls via the Spotify Web API.
+
+## Setup
+
+1. Create an app at [developer.spotify.com](https://developer.spotify.com)
+2. Add `http://127.0.0.1:3001/api/oauth/spotify/callback` as a **Redirect URI** in your Spotify app settings
+3. In BRIKA, go to the plugin preferences and paste your **Client ID**
+4. Click the **Connect** link to authorize
+
+> Uses PKCE — no client secret needed.
+
+## Brick: Spotify Player
+
+Responsive player that adapts to the grid size:
+
+| Size     | Layout                                             |
+|----------|----------------------------------------------------|
+| 1-2 cols | Album art with play/pause overlay                  |
+| 3-4 cols | Album art background with floating control panel   |
+| 5+ cols  | Split layout — album art left, full controls right |
+
+Height unlocks additional features:
+
+- **h >= 3** (medium layout): seek slider
+- **h >= 4**: volume slider
+- **h >= 5** (large layout): device name badge
+
+### Config
+
+| Name              | Type   | Default | Description                         |
+|-------------------|--------|---------|-------------------------------------|
+| `refreshInterval` | number | 3000    | Polling interval in ms (1000–30000) |
+
+Progress is interpolated locally between polls for smooth UI updates.
+
+## Spark: Track Changed
+
+Emitted whenever the playing track changes.
+
+**Payload:**
+
+| Field        | Type           | Description                     |
+|--------------|----------------|---------------------------------|
+| `trackName`  | string         | Track title                     |
+| `artistName` | string         | Artist name(s), comma-separated |
+| `albumName`  | string         | Album title                     |
+| `albumArt`   | string \| null | Album art URL (640px)           |
+| `timestamp`  | number         | Unix timestamp (ms)             |
+
+## Scopes
+
+- `user-read-playback-state`
+- `user-modify-playback-state`
+- `user-read-currently-playing`

package/icon.svg

@@ -0,0 +1 @@
+<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class=""><rect id="_r_9_" width="512" height="512" x="0" y="0" rx="0" fill="url(#_r_a_)" stroke="#FFFFFF" stroke-width="0" stroke-opacity="100%" paint-order="stroke"></rect><clipPath id="clip"><use xlink:href="#_r_9_"></use></clipPath><defs><radialGradient id="_r_a_" cx="50%" cy="50%" r="100%" fx="50%" fy="0%" gradientUnits="objectBoundingBox"><stop stop-color="#1DB954"></stop><stop offset="1" stop-color="#0E7932"></stop></radialGradient><radialGradient id="_r_b_" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(256) rotate(90) scale(512)"><stop stop-color="white"></stop><stop offset="1" stop-color="white" stop-opacity="0"></stop></radialGradient></defs><svg xmlns="http://www.w3.org/2000/svg" shape-rendering="geometricPrecision" text-rendering="geometricPrecision" image-rendering="optimizeQuality" fill-rule="evenodd" clip-rule="evenodd" viewBox="0 0 512 511.991" width="352" height="352" x="80" y="80" alignment-baseline="middle" style="color: rgb(220, 238, 222); width: 352px; height: 352px;"><path fill="#fff" fill-rule="nonzero" d="M255.998.003C114.616.003 0 114.616 0 255.997c0 141.385 114.616 255.994 255.998 255.994C397.395 511.991 512 397.386 512 255.997 512 114.624 397.395.015 255.994.015l.004-.015v.003zm117.4 369.22c-4.585 7.519-14.427 9.908-21.949 5.288-60.104-36.714-135.771-45.027-224.882-24.668-8.587 1.954-17.146-3.425-19.104-12.015-1.967-8.591 3.394-17.15 12.003-19.104 97.518-22.28 181.164-12.688 248.645 28.55 7.522 4.616 9.907 14.427 5.288 21.95l-.001-.001zm31.335-69.703c-5.779 9.389-18.067 12.353-27.452 6.578-68.813-42.298-173.703-54.548-255.096-29.837-10.556 3.187-21.704-2.761-24.906-13.298-3.18-10.556 2.772-21.68 13.309-24.891 92.971-28.208 208.551-14.546 287.574 34.015 9.385 5.779 12.35 18.067 6.575 27.441v-.004l-.004-.004zm2.692-72.584c-82.511-49.006-218.635-53.51-297.409-29.603-12.649 3.837-26.027-3.302-29.86-15.955-3.832-12.656 3.303-26.023 15.96-29.867 90.428-27.452 240.753-22.149 335.747 34.245 11.401 6.754 15.133 21.446 8.375 32.809-6.728 11.378-21.462 15.13-32.802 8.371h-.011z"></path></svg></svg>

package/locales/en/plugin.json

@@ -0,0 +1,49 @@
+{
+  "name": "Spotify Connect",
+  "description": "Control Spotify playback and display album art on your dashboard",
+  "preferences": {
+    "clientId": {
+      "title": "Client ID",
+      "description": "Spotify Developer App client ID (create one at developer.spotify.com)"
+    },
+    "connect": {
+      "title": "Connect to Spotify",
+      "description": "Authorize BRIKA to access your Spotify account"
+    },
+    "developer": {
+      "title": "Spotify Developer Portal",
+      "description": "Create and manage your Spotify app credentials"
+    },
+    "defaultDevice": {
+      "title": "Default Device",
+      "description": "Select the device to auto-start playback on"
+    }
+  },
+  "bricks": {
+    "player": {
+      "name": "Spotify Player",
+      "description": "Control Spotify playback and display album art",
+      "config": {
+        "device": {
+          "label": "Device",
+          "description": "Override the default device for this brick"
+        },
+        "refreshInterval": {
+          "label": "Refresh interval (ms)"
+        }
+      }
+    }
+  },
+  "blocks": {
+    "play": {
+      "name": "Play Spotify",
+      "description": "Start playback on a Spotify device"
+    }
+  },
+  "sparks": {
+    "track-changed": {
+      "name": "Track Changed",
+      "description": "Emitted when the playing track changes"
+    }
+  }
+}

package/locales/fr/plugin.json

@@ -0,0 +1,49 @@
+{
+  "name": "Spotify Connect",
+  "description": "Contrôlez la lecture Spotify et affichez les pochettes d'album sur votre tableau de bord",
+  "preferences": {
+    "clientId": {
+      "title": "ID Client",
+      "description": "ID client de l'application Spotify Developer (créez-en un sur developer.spotify.com)"
+    },
+    "connect": {
+      "title": "Se connecter à Spotify",
+      "description": "Autoriser BRIKA à accéder à votre compte Spotify"
+    },
+    "developer": {
+      "title": "Portail développeur Spotify",
+      "description": "Créez et gérez vos identifiants d'application Spotify"
+    },
+    "defaultDevice": {
+      "title": "Appareil par défaut",
+      "description": "Sélectionnez l'appareil pour démarrer automatiquement la lecture"
+    }
+  },
+  "bricks": {
+    "player": {
+      "name": "Lecteur Spotify",
+      "description": "Contrôlez Spotify et affichez les pochettes d'album",
+      "config": {
+        "device": {
+          "label": "Appareil",
+          "description": "Remplacer l'appareil par défaut pour cette brique"
+        },
+        "refreshInterval": {
+          "label": "Intervalle de rafraîchissement (ms)"
+        }
+      }
+    }
+  },
+  "blocks": {
+    "play": {
+      "name": "Lire Spotify",
+      "description": "Démarrer la lecture sur un appareil Spotify"
+    }
+  },
+  "sparks": {
+    "track-changed": {
+      "name": "Piste modifiée",
+      "description": "Émis lorsque la piste en cours de lecture change"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://schema.brika.dev/plugin.schema.json",
+  "name": "@brika/plugin-spotify",
+  "displayName": "Spotify",
+  "version": "0.3.0",
+  "description": "Spotify Connect player for BRIKA dashboards",
+  "author": "BRIKA Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maxscharwath/brika.git",
+    "directory": "plugins/spotify"
+  },
+  "icon": "./icon.svg",
+  "keywords": [
+    "brika",
+    "brika-plugin",
+    "spotify",
+    "music",
+    "player"
+  ],
+  "type": "module",
+  "main": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx"
+  },
+  "engines": {
+    "brika": "^0.3.0"
+  },
+  "scripts": {
+    "link": "bun link",
+    "tsc": "bunx --bun tsc --noEmit",
+    "prepublishOnly": "brika-verify-plugin"
+  },
+  "preferences": [
+    {
+      "name": "clientId",
+      "type": "text",
+      "label": "Client ID",
+      "description": "Spotify Developer App client ID",
+      "required": true
+    },
+    {
+      "name": "connect",
+      "type": "link",
+      "label": "Connect to Spotify",
+      "description": "Authorize BRIKA to access your Spotify account",
+      "url": "/api/oauth/spotify/authorize"
+    },
+    {
+      "name": "developer",
+      "type": "link",
+      "label": "Spotify Developer Portal",
+      "description": "Create and manage your Spotify app credentials",
+      "url": "https://developer.spotify.com"
+    },
+    {
+      "name": "defaultDevice",
+      "type": "dynamic-dropdown",
+      "label": "Default Device",
+      "description": "Device to auto-start playback on"
+    }
+  ],
+  "bricks": [
+    {
+      "id": "player",
+      "name": "Spotify Player",
+      "description": "Control Spotify playback and display album art",
+      "category": "media",
+      "icon": "music",
+      "color": "#1DB954",
+      "config": [
+        {
+          "type": "dynamic-dropdown",
+          "name": "device",
+          "label": "Device",
+          "description": "Override the default device for this brick"
+        },
+        {
+          "type": "number",
+          "name": "refreshInterval",
+          "label": "Refresh interval (ms)",
+          "default": 3000,
+          "min": 1000,
+          "max": 30000,
+          "step": 1000
+        }
+      ]
+    }
+  ],
+  "blocks": [
+    {
+      "id": "play",
+      "name": "Play Spotify",
+      "description": "Start playback on a Spotify device",
+      "category": "action",
+      "icon": "play",
+      "color": "#1DB954"
+    }
+  ],
+  "sparks": [
+    {
+      "id": "track-changed",
+      "name": "Track Changed",
+      "description": "Emitted when the playing track changes"
+    }
+  ],
+  "dependencies": {
+    "@brika/sdk": "0.3.0"
+  },
+  "files": [
+    "src",
+    "locales",
+    "icon.svg",
+    "README.md"
+  ]
+}

package/src/blocks/play.ts

@@ -0,0 +1,45 @@
+import { defineReactiveBlock, input, log, output, z } from '@brika/sdk';
+import { getApi, resolveDevice, toSpotifyUri } from '../shared';
+
+export const playBlock = defineReactiveBlock(
+  {
+    id: 'play',
+    name: 'Play Spotify',
+    description: 'Start playback on a Spotify device',
+    category: 'action',
+    icon: 'play',
+    color: '#1DB954',
+    inputs: {
+      trigger: input(z.generic(), { name: 'Trigger' }),
+    },
+    outputs: {
+      started: output(z.object({ deviceId: z.string(), contextUri: z.string().optional() }), { name: 'Started' }),
+      error: output(z.object({ message: z.string() }), { name: 'Error' }),
+    },
+    config: z.object({
+      contextUri: z.string().optional().describe('Spotify URI or URL (playlist, album, or track). Empty = resume last played'),
+      deviceId: z.string().optional().describe('Device name or ID. Empty = use plugin default device'),
+    }),
+  },
+  ({ inputs, outputs, config }) => {
+    inputs.trigger.on(async () => {
+      try {
+        const deviceId = await resolveDevice(config.deviceId);
+        const contextUri = toSpotifyUri(config.contextUri);
+        const recent = await getApi().getRecentlyPlayed();
+        const uri = contextUri ?? recent?.uri;
+
+        if (deviceId) await getApi().transferPlayback(deviceId);
+        await getApi().play(deviceId, uri);
+
+        const target = deviceId ? ` on ${deviceId}` : '';
+        log.info(`Spotify playback started${target}`);
+        outputs.started.emit({ deviceId: deviceId ?? '', contextUri: uri });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`Spotify play failed: ${message}`);
+        outputs.error.emit({ message });
+      }
+    });
+  },
+);

package/src/bricks/components.tsx

@@ -0,0 +1,81 @@
+/**
+ * Shared sub-components for the Spotify player brick.
+ * Each renders a reusable piece of the player UI.
+ */
+
+import { Box, Button, Row, Slider, Text } from '@brika/sdk/bricks';
+import { formatMs, progressPercent } from './utils';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface PlayerActions {
+  onPlay: () => void;
+  onPause: () => void;
+  onNext: () => void;
+  onPrev: () => void;
+  onSeek: (payload?: Record<string, unknown>) => void;
+  onVolume: (payload?: Record<string, unknown>) => void;
+}
+
+// ─── Transport Controls ─────────────────────────────────────────────────────
+
+export function Controls({ isPlaying, onPlay, onPause, onPrev, onNext }: Readonly<{
+  isPlaying: boolean;
+  onPlay: () => void;
+  onPause: () => void;
+  onPrev: () => void;
+  onNext: () => void;
+}>) {
+  return (
+    <Row gap="sm" justify="center" align="center">
+      <Button onPress={onPrev} icon="skip-back" color="rgba(0,0,0,0.3)" />
+      {isPlaying
+        ? <Button onPress={onPause} icon="pause" color="rgba(0,0,0,0.5)" />
+        : <Button onPress={onPlay} icon="play" color="rgba(0,0,0,0.5)" />}
+      <Button onPress={onNext} icon="skip-forward" color="rgba(0,0,0,0.3)" />
+    </Row>
+  );
+}
+
+// ─── Track Info ─────────────────────────────────────────────────────────────
+
+export function TrackInfo({ trackName, artistName }: Readonly<{
+  trackName: string;
+  artistName: string;
+}>) {
+  return (
+    <Row gap="sm" align="center">
+      <Text content={trackName} variant="heading" color="rgba(255,255,255,0.95)" />
+      <Text content={artistName} variant="caption" color="rgba(255,255,255,0.55)" />
+    </Row>
+  );
+}
+
+// ─── Progress Bar ───────────────────────────────────────────────────────────
+
+export function ProgressBar({ localProgressMs, durationMs, onSeek }: Readonly<{
+  localProgressMs: number;
+  durationMs: number;
+  onSeek: (payload?: Record<string, unknown>) => void;
+}>) {
+  return (
+    <Row gap="sm" align="center">
+      <Text content={formatMs(localProgressMs)} variant="caption" color="rgba(255,255,255,0.55)" />
+      <Box grow>
+        <Slider value={progressPercent(localProgressMs, durationMs)} min={0} max={100} step={1} onChange={onSeek} color="#1DB954" />
+      </Box>
+      <Text content={formatMs(durationMs)} variant="caption" color="rgba(255,255,255,0.55)" />
+    </Row>
+  );
+}
+
+// ─── Volume Slider ──────────────────────────────────────────────────────────
+
+export function VolumeSlider({ volume, onVolume }: Readonly<{
+  volume: number;
+  onVolume: (payload?: Record<string, unknown>) => void;
+}>) {
+  return (
+    <Slider label="Volume" value={volume} min={0} max={100} step={5} unit="%" onChange={onVolume} icon="volume-2" color="rgba(255,255,255,0.6)" />
+  );
+}

package/src/bricks/player.tsx

@@ -0,0 +1,194 @@
+import { Badge, Box, Button, Column, defineBrick, Icon, Image, Row, Spacer, Text, useBrickSize, useEffect, usePluginPreference, usePreference, useRef, useState } from '@brika/sdk/bricks';
+import { spotify } from '../index';
+import {
+  acquirePolling,
+  next,
+  pause,
+  play,
+  previous,
+  seek,
+  setVolume,
+  startPlayback,
+  usePlayerStore,
+} from '../playback-store';
+import type { PlaybackState } from '../spotify-api';
+import { Controls, type PlayerActions, ProgressBar, TrackInfo, VolumeSlider } from './components';
+
+// ─── Common layout props ─────────────────────────────────────────────────────
+
+interface TrackDisplay {
+  trackName: string;
+  artistName: string;
+  albumArt: string | null;
+}
+
+interface LayoutProps {
+  track: TrackDisplay;
+  playback: PlaybackState | null;
+  actions: PlayerActions;
+}
+
+// ─── Layout: Small (1-2 cols) ───────────────────────────────────────────────
+
+function SmallPlayer({ track, playback, width, actions }: Readonly<LayoutProps & { width: number }>) {
+  const isPlaying = playback?.isPlaying ?? false;
+  return (
+    <Box backgroundImage={track.albumArt ?? undefined} backgroundFit="cover" rounded="lg" grow>
+      <Box background="rgba(0,0,0,0.3)" grow>
+        <Column justify="center" align="center" gap="sm">
+          <Spacer />
+          {width >= 2
+            ? <Controls isPlaying={isPlaying} onPlay={actions.onPlay} onPause={actions.onPause} onPrev={actions.onPrev} onNext={actions.onNext} />
+            : <Button onPress={isPlaying ? actions.onPause : actions.onPlay} icon={isPlaying ? 'pause' : 'play'} color="rgba(0,0,0,0.4)" />}
+          <Spacer />
+        </Column>
+      </Box>
+    </Box>
+  );
+}
+
+// ─── Layout: Medium (3-4 cols) ──────────────────────────────────────────────
+
+function MediumPlayer({ track, playback, height, localProgressMs, actions }: Readonly<LayoutProps & { height: number; localProgressMs: number }>) {
+  const isPlaying = playback?.isPlaying ?? false;
+  return (
+    <Box backgroundImage={track.albumArt ?? undefined} backgroundFit="cover" rounded="lg" grow padding="sm">
+      <Column grow justify={height >= 2 ? 'end' : 'start'}>
+        <Box background="rgba(0,0,0,0.7)" blur="lg" padding="md" grow={height < 2} rounded={height < 2 ? 'lg' : 'md'}>
+          <Column gap="sm">
+            <TrackInfo trackName={track.trackName} artistName={track.artistName} />
+            <Controls isPlaying={isPlaying} onPlay={actions.onPlay} onPause={actions.onPause} onPrev={actions.onPrev} onNext={actions.onNext} />
+            {playback && <ProgressBar localProgressMs={localProgressMs} durationMs={playback.durationMs} onSeek={actions.onSeek} />}
+            {playback && height >= 4 && <VolumeSlider volume={playback.volume} onVolume={actions.onVolume} />}
+          </Column>
+        </Box>
+      </Column>
+    </Box>
+  );
+}
+
+// ─── Layout: Large (5+ cols) ────────────────────────────────────────────────
+
+function LargePlayer({ track, playback, height, localProgressMs, actions }: Readonly<LayoutProps & { height: number; localProgressMs: number }>) {
+  const isPlaying = playback?.isPlaying ?? false;
+  return (
+    <Box backgroundImage={track.albumArt ?? undefined} backgroundFit="cover" rounded="lg" blur="sm">
+      <Box background="rgba(0,0,0,0.7)" blur="lg" padding="lg" rounded="lg" grow>
+        <Row gap="lg">
+          {track.albumArt == null
+            ? <Box padding="none" />
+            : <Image src={track.albumArt} alt={playback?.albumName ?? track.trackName} fit="cover" rounded aspectRatio="1/1" />}
+          <Box grow padding="none">
+            <Column gap="sm" justify="center">
+              <TrackInfo trackName={track.trackName} artistName={track.artistName} />
+              <Controls isPlaying={isPlaying} onPlay={actions.onPlay} onPause={actions.onPause} onPrev={actions.onPrev} onNext={actions.onNext} />
+              {playback && <ProgressBar localProgressMs={localProgressMs} durationMs={playback.durationMs} onSeek={actions.onSeek} />}
+              {playback && height >= 4 && <VolumeSlider volume={playback.volume} onVolume={actions.onVolume} />}
+              {playback && height >= 5 && <Badge label={playback.deviceName} icon="speaker" variant="secondary" color="rgba(255,255,255,0.6)" />}
+            </Column>
+          </Box>
+        </Row>
+      </Box>
+    </Box>
+  );
+}
+
+// ─── Brick ──────────────────────────────────────────────────────────────────
+
+export const playerBrick = defineBrick(
+  {
+    id: 'player',
+    families: ['sm', 'md', 'lg'],
+    minSize: { w: 1, h: 1 },
+    maxSize: { w: 12, h: 8 },
+  },
+  () => {
+    const { width, height } = useBrickSize();
+    const { playback, recentTrack, devices, isAuthed, anchor } = usePlayerStore();
+    const [instanceDeviceId] = usePreference<string>('device', '');
+    const pluginDeviceId = usePluginPreference<string>('defaultDevice', '');
+    const preferredId = instanceDeviceId || pluginDeviceId || undefined;
+    const targetId = preferredId ?? devices[0]?.id;
+    const [localProgressMs, setLocalProgressMs] = useState(anchor.progressMs);
+    const anchorRef = useRef(anchor);
+
+    // Start/stop shared polling
+    useEffect(() => acquirePolling(), []);
+
+    // Keep anchor ref in sync and snap localProgressMs immediately
+    useEffect(() => {
+      anchorRef.current = anchor;
+      setLocalProgressMs(anchor.progressMs);
+    }, [anchor]);
+
+    // ─── Local progress interpolation (1s tick) ─────────────────────────
+
+    useEffect(() => {
+      if (!playback?.isPlaying) return;
+      const id = setInterval(() => {
+        const elapsed = Date.now() - anchorRef.current.timestamp;
+        const interpolated = Math.min(
+          anchorRef.current.progressMs + elapsed,
+          playback.durationMs,
+        );
+        setLocalProgressMs(interpolated);
+      }, 1000);
+      return () => clearInterval(id);
+    }, [playback?.isPlaying, playback?.durationMs]);
+
+    // ─── Actions ────────────────────────────────────────────────────────
+
+    const actions: PlayerActions = {
+      onPlay() {
+        if (playback) play(targetId);
+        else startPlayback(targetId);
+      },
+      onPause() { pause(targetId); },
+      onNext() { next(); },
+      onPrev() { previous(); },
+      onSeek(payload) {
+        if (typeof payload?.value === 'number' && playback) {
+          const positionMs = Math.round((payload.value / 100) * playback.durationMs);
+          seek(positionMs);
+          setLocalProgressMs(positionMs);
+        }
+      },
+      onVolume(payload) {
+        if (typeof payload?.value === 'number') setVolume(payload.value);
+      },
+    };
+
+    // ─── Render ─────────────────────────────────────────────────────────
+
+    if (!isAuthed) {
+      return (
+        <Box background="rgba(0,0,0,0.4)" blur="md" padding="lg" rounded="lg">
+          <Column gap="md" align="center" justify="center" grow>
+            <Icon name="music" size="lg" color="#1DB954" />
+            <Text content="Spotify" variant="heading" color="rgba(255,255,255,0.95)" />
+            <Spacer size="sm" />
+            <Button label="Login with Spotify" url={spotify.getAuthUrl()} icon="log-in" color="#1DB954" />
+          </Column>
+        </Box>
+      );
+    }
+
+    const track = playback ?? recentTrack;
+
+    if (!track) {
+      return (
+        <Box background="rgba(0,0,0,0.3)" blur="sm" padding="md" rounded="lg">
+          <Column align="center" justify="center" grow>
+            <Button icon="play" color="#1DB954" onPress={actions.onPlay} />
+          </Column>
+        </Box>
+      );
+    }
+
+    const layoutProps = { track, playback, actions };
+
+    if (width <= 2) return <SmallPlayer {...layoutProps} width={width} />;
+    if (width <= 4) return <MediumPlayer {...layoutProps} height={height} localProgressMs={localProgressMs} />;
+    return <LargePlayer {...layoutProps} height={height} localProgressMs={localProgressMs} />;
+  },
+);

package/src/bricks/utils.ts

@@ -0,0 +1,13 @@
+/** Format milliseconds as m:ss */
+export function formatMs(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  const m = Math.floor(s / 60);
+  const sec = s % 60;
+  return `${m}:${sec.toString().padStart(2, '0')}`;
+}
+
+/** Convert progress/duration to 0-100 percentage */
+export function progressPercent(progress: number, duration: number): number {
+  if (duration <= 0) return 0;
+  return Math.round((progress / duration) * 100);
+}

package/src/index.tsx

@@ -0,0 +1,49 @@
+import { defineOAuth, definePreferenceOptions } from '@brika/sdk';
+import { log, onStop } from '@brika/sdk/lifecycle';
+
+// ─── OAuth ────────────────────────────────────────────────────────────────────
+
+export const spotify = defineOAuth({
+  id: 'spotify',
+  authorizeUrl: 'https://accounts.spotify.com/authorize',
+  tokenUrl: 'https://accounts.spotify.com/api/token',
+  scopes: [
+    'user-read-playback-state',
+    'user-modify-playback-state',
+    'user-read-currently-playing',
+    'user-read-recently-played',
+  ],
+  clientIdPreference: 'clientId',
+});
+
+// ─── Dynamic Preferences ─────────────────────────────────────────────────────
+
+// Lazy import to break the circular dependency (shared.ts imports spotify from here)
+async function fetchDeviceOptions() {
+  const { getApi } = await import('./shared');
+  const devices = await getApi().getDevices();
+  return devices.map((d) => ({ value: d.id, label: `${d.name} (${d.type})` }));
+}
+
+definePreferenceOptions('defaultDevice', fetchDeviceOptions);
+definePreferenceOptions('device', fetchDeviceOptions);
+
+// ─── Sparks ───────────────────────────────────────────────────────────────────
+
+export { trackChanged } from './sparks';
+
+// ─── Blocks ───────────────────────────────────────────────────────────────────
+
+export { playBlock } from './blocks/play';
+
+// ─── Bricks ───────────────────────────────────────────────────────────────────
+
+export { playerBrick } from './bricks/player';
+
+// ─── Lifecycle ────────────────────────────────────────────────────────────────
+
+onStop(() => {
+  log.info('Spotify plugin stopping');
+});
+
+log.info('Spotify plugin loaded');

package/src/playback-store.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared playback store — one polling loop, all player bricks react.
+ *
+ * Built on `defineSharedStore` from the SDK. Any brick that calls
+ * `usePlayerStore()` automatically re-renders when the state changes.
+ */
+
+import { log } from '@brika/sdk';
+import { defineSharedStore } from '@brika/sdk/bricks';
+import { spotify } from './index';
+import { getApi } from './shared';
+import { trackChanged } from './sparks';
+import type { PlaybackState, RecentTrack, SpotifyDevice } from './spotify-api';
+import { SpotifyAuthError } from './spotify-api';
+
+// ─── Store ───────────────────────────────────────────────────────────────────
+
+export interface Anchor { progressMs: number; timestamp: number }
+
+interface PlayerState {
+  playback: PlaybackState | null;
+  recentTrack: RecentTrack | null;
+  devices: SpotifyDevice[];
+  isAuthed: boolean;
+  loaded: boolean;
+  anchor: Anchor;
+}
+
+export const usePlayerStore = defineSharedStore<PlayerState>({
+  playback: null,
+  recentTrack: null,
+  devices: [],
+  isAuthed: false,
+  loaded: false,
+  anchor: { progressMs: 0, timestamp: Date.now() },
+});
+
+// ─── Polling (reference-counted) ─────────────────────────────────────────────
+
+const POLL_MS = 3000;
+
+let refCount = 0;
+let timer: ReturnType<typeof setInterval> | null = null;
+let lastTrack = '';
+
+/** Reset the polling interval so the next poll is a full POLL_MS away. */
+function resetPollTimer(): void {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = setInterval(poll, POLL_MS);
+}
+
+/** Force an immediate poll and restart the timer. */
+function pollNow(): void {
+  poll();
+  resetPollTimer();
+}
+
+function emitTrackChanged(state: PlaybackState): void {
+  if (state.trackName === lastTrack) return;
+  lastTrack = state.trackName;
+  trackChanged.emit({
+    trackName: state.trackName,
+    artistName: state.artistName,
+    albumName: state.albumName,
+    albumArt: state.albumArt,
+    timestamp: Date.now(),
+  });
+}
+
+async function poll(): Promise<void> {
+  if (!spotify.isAuthenticated()) {
+    usePlayerStore.set({ playback: null, recentTrack: null, devices: [], isAuthed: false, loaded: true, anchor: { progressMs: 0, timestamp: Date.now() } });
+    return;
+  }
+
+  try {
+    const state = await getApi().getCurrentPlayback();
+    const anchor: Anchor = { progressMs: state?.progressMs ?? 0, timestamp: Date.now() };
+
+    let devices: SpotifyDevice[] = [];
+    let recentTrack = usePlayerStore.get().recentTrack;
+    if (state) {
+      recentTrack = null;
+    } else {
+      [devices, recentTrack] = await Promise.all([
+        getApi().getDevices(),
+        recentTrack ? Promise.resolve(recentTrack) : getApi().getRecentlyPlayed(),
+      ]);
+    }
+    usePlayerStore.set({ playback: state, recentTrack, devices, isAuthed: true, loaded: true, anchor });
+
+    if (state) emitTrackChanged(state);
+  } catch (err) {
+    if (err instanceof SpotifyAuthError) {
+      usePlayerStore.set((prev) => ({ ...prev, playback: null, isAuthed: false, loaded: true }));
+    } else {
+      usePlayerStore.set((prev) => ({ ...prev, loaded: true }));
+    }
+  }
+}
+
+/** Acquire polling — starts on first subscriber, stops on last. */
+export function acquirePolling(): () => void {
+  refCount++;
+  if (refCount === 1) {
+    // Sync auth state immediately so bricks don't flash the login screen
+    const authed = spotify.isAuthenticated();
+    if (authed !== usePlayerStore.get().isAuthed) {
+      usePlayerStore.set((prev) => ({ ...prev, isAuthed: authed }));
+    }
+    poll();
+    timer = setInterval(poll, POLL_MS);
+  }
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    refCount--;
+    if (refCount === 0 && timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+}
+
+// ─── Actions ─────────────────────────────────────────────────────────────────
+
+/** Catch and log errors from fire-and-forget API calls. */
+function silent(promise: Promise<unknown>): void {
+  promise.catch((err) => {
+    log.error(`Spotify API error: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}
+
+export function play(deviceId?: string): void {
+  silent(getApi().play(deviceId));
+  usePlayerStore.set((prev) => {
+    if (!prev.playback) return prev;
+    const elapsed = Date.now() - prev.anchor.timestamp;
+    return {
+      ...prev,
+      playback: { ...prev.playback, isPlaying: true },
+      anchor: { progressMs: prev.anchor.progressMs + elapsed, timestamp: Date.now() },
+    };
+  });
+  resetPollTimer();
+}
+
+export function pause(deviceId?: string): void {
+  silent(getApi().pause(deviceId));
+  usePlayerStore.set((prev) => {
+    if (!prev.playback) return prev;
+    const elapsed = Date.now() - prev.anchor.timestamp;
+    const progressMs = Math.min(prev.anchor.progressMs + elapsed, prev.playback.durationMs);
+    return {
+      ...prev,
+      playback: { ...prev.playback, isPlaying: false },
+      anchor: { progressMs, timestamp: Date.now() },
+    };
+  });
+  resetPollTimer();
+}
+
+export function next(): void {
+  silent(getApi().next().then(() => pollNow()));
+}
+
+export function previous(): void {
+  silent(getApi().previous().then(() => pollNow()));
+}
+
+export function seek(positionMs: number): void {
+  silent(getApi().seek(positionMs));
+  usePlayerStore.set((prev) => ({
+    ...prev,
+    playback: prev.playback ? { ...prev.playback, progressMs: positionMs } : null,
+    anchor: { progressMs: positionMs, timestamp: Date.now() },
+  }));
+  resetPollTimer();
+}
+
+export function setVolume(percent: number): void {
+  silent(getApi().setVolume(percent));
+  usePlayerStore.set((prev) => {
+    if (!prev.playback) return prev;
+    return { ...prev, playback: { ...prev.playback, volume: percent } };
+  });
+  resetPollTimer();
+}
+
+export function transferPlayback(deviceId: string): void {
+  silent(getApi().transferPlayback(deviceId).then(() => pollNow()));
+}
+
+export async function startPlayback(deviceId?: string): Promise<void> {
+  if (deviceId) await getApi().transferPlayback(deviceId);
+  const recent = await getApi().getRecentlyPlayed();
+  await getApi().play(deviceId, recent?.uri);
+  pollNow();
+}

package/src/shared.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared helpers for the Spotify plugin.
+ *
+ * Uses lazy initialization to avoid circular imports — `spotify` (the OAuth
+ * client) is exported from `index.tsx`, which re-exports bricks/blocks/sparks
+ * that also need the API.
+ */
+
+import { getPreferences } from '@brika/sdk';
+import { spotify } from './index';
+import { createSpotifyApi } from './spotify-api';
+
+// ─── Lazy API singleton ───────────────────────────────────────────────────────
+
+let api: ReturnType<typeof createSpotifyApi> | null = null;
+
+/** Return (or create) the shared Spotify API instance. */
+export function getApi(): ReturnType<typeof createSpotifyApi> {
+  api ??= createSpotifyApi(spotify);
+  return api;
+}
+
+// ─── Device resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve the best device ID from instance config → plugin preference → undefined.
+ * Callers can further fall back to `devices[0]?.id` when a list is available.
+ */
+export function resolveDeviceId(instanceDeviceId?: string): string | undefined {
+  const id = instanceDeviceId?.trim() || undefined;
+  if (id) return id;
+  const prefs = getPreferences<{ defaultDevice?: string }>();
+  return prefs.defaultDevice?.trim() || undefined;
+}
+
+/**
+ * Resolve a device value that may be an ID or a name.
+ * Fetches the device list and matches by ID first, then by name (case-insensitive).
+ */
+export async function resolveDevice(value?: string): Promise<string | undefined> {
+  const id = resolveDeviceId(value);
+  if (!id) return undefined;
+
+  const devices = await getApi().getDevices();
+  // Exact ID match — return as-is
+  if (devices.some((d) => d.id === id)) return id;
+  // Name match (case-insensitive)
+  const byName = devices.find((d) => d.name.toLowerCase() === id.toLowerCase());
+  return byName?.id ?? id;
+}
+
+// ─── Spotify URI helpers ──────────────────────────────────────────────────────
+
+const SPOTIFY_URL_RE = /^https?:\/\/open\.spotify\.com\/(track|album|playlist)\/([A-Za-z0-9]+)/;
+
+/**
+ * Normalize a Spotify URL or URI to a proper `spotify:type:id` URI.
+ * Accepts:
+ *   - `spotify:track:ABC123` → returned as-is
+ *   - `https://open.spotify.com/track/ABC123?si=...` → `spotify:track:ABC123`
+ * Returns undefined for empty/invalid input.
+ */
+export function toSpotifyUri(input?: string): string | undefined {
+  const value = input?.trim();
+  if (!value) return undefined;
+  if (value.startsWith('spotify:')) return value;
+  const match = SPOTIFY_URL_RE.exec(value);
+  if (match) return `spotify:${match[1]}:${match[2]}`;
+  return undefined;
+}

package/src/sparks.ts

@@ -0,0 +1,12 @@
+import { defineSpark, z } from '@brika/sdk/sparks';
+
+export const trackChanged = defineSpark({
+  id: 'track-changed',
+  schema: z.object({
+    trackName: z.string(),
+    artistName: z.string(),
+    albumName: z.string(),
+    albumArt: z.string().nullable(),
+    timestamp: z.number(),
+  }),
+});

package/src/spotify-api.ts

@@ -0,0 +1,216 @@
+/**
+ * Spotify Web API wrapper using the OAuth client.
+ */
+
+import type { OAuthClient } from '@brika/sdk';
+
+const BASE = 'https://api.spotify.com/v1';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SpotifyImage {
+  url: string;
+  width: number;
+  height: number;
+}
+
+export interface PlaybackState {
+  isPlaying: boolean;
+  trackName: string;
+  artistName: string;
+  albumName: string;
+  albumArt: string | null;
+  progressMs: number;
+  durationMs: number;
+  volume: number;
+  deviceName: string;
+}
+
+export interface RecentTrack {
+  trackName: string;
+  artistName: string;
+  albumArt: string | null;
+  uri: string;
+}
+
+export interface SpotifyDevice {
+  id: string;
+  name: string;
+  type: string;
+  isActive: boolean;
+  volumePercent: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// API Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Thrown when the Spotify API returns 401 — signals re-auth is needed. */
+export class SpotifyAuthError extends Error {
+  constructor() {
+    super('Spotify token expired or revoked');
+    this.name = 'SpotifyAuthError';
+  }
+}
+
+function pickArt(images: SpotifyImage[]): string | null {
+  const art = images.find((i) => i.width === 640) ?? images[0];
+  return art?.url ?? null;
+}
+
+export function createSpotifyApi(oauth: OAuthClient) {
+  async function api<T>(path: string, init?: RequestInit): Promise<T | null> {
+    if (!oauth.isAuthenticated()) return null;
+
+    const res = await oauth.fetch(`${BASE}${path}`, init);
+
+    // 204 = no active device/playback — legitimate "no data"
+    if (res.status === 204) return null;
+
+    // 401 = token invalid — bubble up so the brick can reset auth state
+    if (res.status === 401) throw new SpotifyAuthError();
+
+    // Other errors — return null (rate-limit, server error, etc.)
+    if (!res.ok) return null;
+
+    // Some endpoints return empty bodies (play, pause, next, previous)
+    const text = await res.text();
+    if (!text) return null;
+
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    async getCurrentPlayback(): Promise<PlaybackState | null> {
+      const data = await api<{
+        is_playing: boolean;
+        progress_ms: number;
+        item: {
+          name: string;
+          duration_ms: number;
+          artists: { name: string }[];
+          album: {
+            name: string;
+            images: SpotifyImage[];
+          };
+        } | null;
+        device: {
+          name: string;
+          volume_percent: number;
+        };
+      }>('/me/player');
+
+      if (!data?.item) return null;
+
+      return {
+        isPlaying: data.is_playing,
+        trackName: data.item.name,
+        artistName: data.item.artists.map((a) => a.name).join(', '),
+        albumName: data.item.album.name,
+        albumArt: pickArt(data.item.album.images),
+        progressMs: data.progress_ms,
+        durationMs: data.item.duration_ms,
+        volume: data.device.volume_percent,
+        deviceName: data.device.name,
+      };
+    },
+
+    async play(deviceId?: string, contextUri?: string): Promise<void> {
+      const qs = deviceId ? `?device_id=${deviceId}` : '';
+      let body: string | undefined;
+      if (contextUri) {
+        const payload = contextUri.includes(':track:')
+          ? { uris: [contextUri] }
+          : { context_uri: contextUri };
+        body = JSON.stringify(payload);
+      }
+      await api(`/me/player/play${qs}`, {
+        method: 'PUT',
+        ...(body && { headers: { 'Content-Type': 'application/json' }, body }),
+      });
+    },
+
+    async pause(deviceId?: string): Promise<void> {
+      const qs = deviceId ? `?device_id=${deviceId}` : '';
+      await api(`/me/player/pause${qs}`, { method: 'PUT' });
+    },
+
+    async next(): Promise<void> {
+      await api('/me/player/next', { method: 'POST' });
+    },
+
+    async previous(): Promise<void> {
+      await api('/me/player/previous', { method: 'POST' });
+    },
+
+    async seek(positionMs: number): Promise<void> {
+      const ms = Math.round(Math.max(0, positionMs));
+      await api(`/me/player/seek?position_ms=${ms}`, { method: 'PUT' });
+    },
+
+    async setVolume(percent: number): Promise<void> {
+      const vol = Math.round(Math.max(0, Math.min(100, percent)));
+      await api(`/me/player/volume?volume_percent=${vol}`, { method: 'PUT' });
+    },
+
+    async transferPlayback(deviceId: string): Promise<void> {
+      await api('/me/player', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ device_ids: [deviceId], play: false }),
+      });
+    },
+
+    async getRecentlyPlayed(): Promise<RecentTrack | null> {
+      const data = await api<{
+        items: Array<{
+          context?: { uri: string };
+          track: {
+            uri: string;
+            name: string;
+            artists: { name: string }[];
+            album: { images: SpotifyImage[] };
+          };
+        }>;
+      }>('/me/player/recently-played?limit=1');
+      if (!data?.items?.[0]) return null;
+      const { context, track } = data.items[0];
+      return {
+        trackName: track.name,
+        artistName: track.artists.map((a) => a.name).join(', '),
+        albumArt: pickArt(track.album.images),
+        uri: context?.uri ?? track.uri,
+      };
+    },
+
+    async getDevices(): Promise<SpotifyDevice[]> {
+      const data = await api<{
+        devices: {
+          id: string;
+          name: string;
+          type: string;
+          is_active: boolean;
+          volume_percent: number;
+        }[];
+      }>('/me/player/devices');
+
+      if (!data) return [];
+
+      return data.devices.map((d) => ({
+        id: d.id,
+        name: d.name,
+        type: d.type,
+        isActive: d.is_active,
+        volumePercent: d.volume_percent,
+      }));
+    },
+  };
+}
+
+export type SpotifyApi = ReturnType<typeof createSpotifyApi>;