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/lyrics.ts

@@ -0,0 +1,64 @@
+/**
+ * Parse lyrics text into displayable lines. `.lrc` carries `[mm:ss.xx]` timestamps (possibly several per
+ * line, e.g. repeated choruses) and metadata tags ([ar:], [ti:], …) which are dropped. `.txt` is plain.
+ * A synced result is sorted by time so the active-line lookup is a simple scan.
+ *
+ * Ported from the mobile app (packages/core/src/services/lyrics.ts) — same file format, same server,
+ * so the two must agree on what a line is.
+ */
+export type LyricLine = { timeSec?: number; text: string };
+export type ParsedLyrics = { synced: boolean; lines: LyricLine[] };
+
+const TIME_RE = /\[(\d{1,2}):(\d{2})(?:[.:](\d{1,3}))?\]/g;
+const META_RE = /^\[(ar|ti|al|by|offset|length|re|ve|au|la|id):/i;
+
+/**
+ * Lines are treated as synced whenever the text actually contains `[mm:ss]` timestamps — the server's
+ * `X-Lyrics-Format` header is not trusted (it need not survive a proxy, and embedded lyrics carrying
+ * timestamps should sync regardless of which file they came from). No timestamps → plain text.
+ */
+export function parseLyrics(text: string): ParsedLyrics {
+  if (!/\[\d{1,2}:\d{2}/.test(text)) {
+    return { synced: false, lines: text.split(/\r?\n/).map((t) => ({ text: t.trim() })) };
+  }
+
+  const out: LyricLine[] = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    if (META_RE.test(rawLine.trim())) continue;
+    const stamps: number[] = [];
+    let m: RegExpExecArray | null;
+    TIME_RE.lastIndex = 0;
+    while ((m = TIME_RE.exec(rawLine)) !== null) {
+      const min = Number(m[1]);
+      const sec = Number(m[2]);
+      // "[00:12.3]" is three tenths, not three milliseconds — pad right before reading as thousandths.
+      const frac = m[3] ? Number(`${m[3]}00`.slice(0, 3)) / 1000 : 0;
+      stamps.push(min * 60 + sec + frac);
+    }
+    const lyric = rawLine.replace(TIME_RE, '').trim();
+    if (!stamps.length) {
+      if (lyric) out.push({ text: lyric }); // a plain line inside an otherwise-synced file
+      continue;
+    }
+    for (const t of stamps) out.push({ timeSec: t, text: lyric });
+  }
+
+  const synced = out.some((l) => l.timeSec != null);
+  if (synced) out.sort((a, b) => (a.timeSec ?? 0) - (b.timeSec ?? 0));
+  return { synced, lines: out };
+}
+
+/**
+ * Index of the active line for a playback position (synced only); -1 before the first line. The 0.2s
+ * lookahead lands the highlight fractionally early, which reads as on-time — arriving late reads as lag.
+ */
+export function activeLineIndex(lines: LyricLine[], positionSec: number): number {
+  let idx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i]?.timeSec;
+    if (t == null) continue;
+    if (t <= positionSec + 0.2) idx = i;
+    else break;
+  }
+  return idx;
+}