music, extracted from the platform into its own repository

Everything the plugin is, moved out of officerdev/platform on 2026-08-15 —
41 files, unchanged from the tree they left.

  manifest.ts   identity, one permission, ffmpeg/ffprobe declared
  api/          the sidecar proxy; the prefix comes from mountPrefix()
  sidecar/      the whole /api/music contract — indexing, streaming, per-user state
  db/           music_favorites, _playlists, _playlist_items, _now_playing
  web/          panels, layout, and the player: engine, bar, lyrics, favourites
  cliamp/       the second playback path, parked — not working, kept deliberately
  widgets/      the dashboard widget, parked — plugins cannot contribute widgets
  assets/       icon.png, the dock tile
  scripts/      the reindex CLI

PLUGIN.md is the design record: what moved, what stayed, what broke, and why.
MUSIC_API.md is the contract the phone and tablet apps speak, and the reason
the sidecar's HTTP shape is not free to change.

── It does not build here, and that is the point ──

The platform resolves `hooks/useClient`, `officerdev`, `officerdb/db` and `@@/*`
through the workspace links in its own node_modules. Measured from this
directory, outside the platform checkout, every one of them fails to resolve —
7 imports in the backend, ~29 in the frontend.

So this repository is the source of truth, not yet a buildable unit. Making it
one means the host API becoming something a plugin can depend on rather than
something it reaches into. That is the next problem, and having the code here
is what makes it unavoidable rather than theoretical.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

web/useMusicPlayer.ts

@@ -0,0 +1,47 @@
+import { useGlobal } from 'hooks/useGlobal';
+
+// App-wide music player state (react-query-backed via useGlobal, so it's shared across the whole app and
+// survives route changes). The audio element itself lives in MusicPlayerHost (mounted once in the
+// persistent DashboardLayout); this hook is the control surface any component uses to drive it.
+
+export type PlayerTrack = {
+  albumRel: string; // album path relative to the Music root (for stream + cover URLs)
+  file: string; // track filename within the album folder
+  title?: string;
+  artist?: string;
+};
+
+export type MusicPlayerState = {
+  queue: PlayerTrack[];
+  index: number;
+  playing: boolean;
+};
+
+const INITIAL: MusicPlayerState = { queue: [], index: 0, playing: false };
+
+export function useMusicPlayer() {
+  const [state, setState] = useGlobal<MusicPlayerState>('MUSIC_PLAYER', INITIAL);
+
+  const playQueue = (queue: PlayerTrack[], index = 0) =>
+    setState({ queue, index: Math.max(0, Math.min(index, Math.max(0, queue.length - 1))), playing: true });
+  // Like playQueue but paused — for restoring a saved "currently playing" on load without auto-playing
+  // (browsers block autoplay on reload anyway; the user resumes with a click).
+  const loadQueue = (queue: PlayerTrack[], index = 0) =>
+    setState({ queue, index: Math.max(0, Math.min(index, Math.max(0, queue.length - 1))), playing: false });
+  const toggle = () => setState((s) => ({ ...s, playing: !s.playing }));
+  const setPlaying = (playing: boolean) => setState((s) => ({ ...s, playing }));
+  // Mirror an engine-driven natural advance into the index WITHOUT restarting playback (the audio engine
+  // has already transitioned to the next track gaplessly; this only updates the UI/highlight).
+  const syncIndex = (index: number) => setState((s) => ({ ...s, index }));
+  const jump = (index: number) =>
+    setState((s) => ({ ...s, index: Math.max(0, Math.min(index, s.queue.length - 1)), playing: true }));
+  const next = () =>
+    setState((s) =>
+      s.index < s.queue.length - 1 ? { ...s, index: s.index + 1, playing: true } : { ...s, playing: false },
+    );
+  const prev = () => setState((s) => (s.index > 0 ? { ...s, index: s.index - 1, playing: true } : s));
+  const close = () => setState(INITIAL);
+
+  const current = state.queue[state.index];
+  return { ...state, current, playQueue, loadQueue, toggle, setPlaying, syncIndex, jump, next, prev, close };
+}