@naxodev/opencode-music-player 0.2.4 → 0.2.6

package/README.md

@@ -16,6 +16,10 @@ Read the [music session architecture field guide](../../docs/music-session-archi
 
 The daemon performs the bounded native `media-control get --now` read and validates the complete recording identity before and after the read. OpenCode uses those bytes when available, then keeps iTunes Search fallback, image downloads, conversion, cache/job ownership, and terminal rendering locally. Artwork failure never blocks playback state.
 
+Catalog matching, bounded downloads, cancellation, and transient retries use the [shared host-side acquisition policy](../music-core/README.md#host-side-catalog-artwork). OpenCode keeps image conversion and its shared presentation cache/jobs. Track changes remove only the changing view's interest; another view can keep the same job alive.
+
+Run `/music-artwork`, or select **Music → Refresh artwork** in the command palette, to recover artwork for the current track after connectivity returns. Automatic recovery stops after three transient attempts. A settled mismatch does not retry on playback snapshots. Refresh starts a new bounded attempt set; repeated refreshes while a job is active share that job. This action does not change playback.
+
 Ghostty and other terminals with Kitty graphics support display the cover as a native image. Other terminals receive a true-color half-block rendering of the same cover.
 
 Terminal multiplexers must pass Kitty graphics through to use native images. The player uses the half-block rendering when the host does not expose that support.

package/artwork.ts

@@ -3,226 +3,33 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { PNG } from "pngjs"
 import type { Artwork } from "./types.ts"
+import {
+  acquireCatalogArtwork,
+  MAX_ARTWORK_BYTES,
+  selectCatalogResolution,
+  type CatalogTarget as TrackIdentity,
+  type ArtworkFetcher as Fetcher,
+} from "@naxodev/music-core"
+export {
+  selectCatalogResolution,
+  selectCatalogTrack,
+  readLimitedResponse,
+  downloadCatalogImage,
+  type CatalogTrack,
+} from "@naxodev/music-core"
 
-const MAX_ARTWORK_BYTES = 3_000_000
-const MAX_CATALOG_RESPONSE_BYTES = 512_000
 const MAX_CONVERTED_PNG_BYTES = 1_000_000
 const MAX_IMAGE_DIMENSION = 4_096
 const MAX_IMAGE_PIXELS = 12_000_000
-const FETCH_TIMEOUT_MS = 4_000
 const CONVERSION_TIMEOUT_MS = 3_000
-// MediaRemote may expose whole seconds while catalogs retain milliseconds.
-const DURATION_TOLERANCE_MS = 1_000
-const MAX_CATALOG_DURATION_MS = 24 * 60 * 60 * 1_000
-
-type TrackIdentity = {
-  title: string
-  artist: string
-  album: string
-  duration_ms: number
-}
-
-export type CatalogTrack = {
-  trackName?: string
-  artistName?: string
-  collectionName?: string
-  trackTimeMillis?: number
-  artworkUrl100?: string
-}
-
-type Fetcher = (
-  input: string | URL | Request,
-  init?: RequestInit,
-) => Promise<Response>
-
-function normalized(value: string | undefined): string {
-  return (value ?? "")
-    .normalize("NFKC")
-    .replace(/’/g, "'")
-    .replace(/\s+/g, " ")
-    .trim()
-    .toLowerCase()
-}
 
 export function selectArtworkUrl(
   target: TrackIdentity,
-  results: CatalogTrack[],
+  results: import("@naxodev/music-core").CatalogTrack[],
 ): string | null {
   return selectCatalogResolution(target, results).artworkUrl
 }
 
-function matchingCatalogTracks(
-  target: TrackIdentity,
-  results: CatalogTrack[],
-): CatalogTrack[] {
-  const title = normalized(target.title)
-  const artist = normalized(target.artist)
-  const album = normalized(target.album)
-  if (!title || !artist) return []
-
-  let matches = results.filter(
-    (item) =>
-      normalized(item.trackName) === title &&
-      normalized(item.artistName) === artist,
-  )
-  if (album) {
-    matches = matches.filter(
-      (item) => normalized(item.collectionName) === album,
-    )
-  }
-  return matches
-}
-
-function validCatalogDuration(value: number | undefined): value is number {
-  return (
-    typeof value === "number" &&
-    Number.isFinite(value) &&
-    value > 0 &&
-    value <= MAX_CATALOG_DURATION_MS
-  )
-}
-
-function selectCatalogCandidate(
-  target: TrackIdentity,
-  results: CatalogTrack[],
-): CatalogTrack | null {
-  let matches = matchingCatalogTracks(target, results)
-  if (target.duration_ms > 0) {
-    matches = matches.filter(
-      (item) =>
-        validCatalogDuration(item.trackTimeMillis) &&
-        Math.abs(item.trackTimeMillis! - target.duration_ms) <=
-          DURATION_TOLERANCE_MS,
-    )
-  } else if (matches.length !== 1) {
-    return null
-  }
-
-  return matches[0] ?? null
-}
-
-export function selectCatalogTrack(
-  target: TrackIdentity,
-  results: CatalogTrack[],
-): CatalogTrack | null {
-  const match = selectCatalogCandidate(target, results)
-  return validCatalogDuration(match?.trackTimeMillis) ? match : null
-}
-
-export function selectCatalogResolution(
-  target: TrackIdentity,
-  results: CatalogTrack[],
-): { artworkUrl: string | null; duration_ms: number } {
-  const match = selectCatalogCandidate(target, results)
-  return {
-    artworkUrl:
-      match?.artworkUrl100?.replace(/100x100(?=[a-z]*\.)/, "300x300") ?? null,
-    duration_ms: validCatalogDuration(match?.trackTimeMillis)
-      ? match.trackTimeMillis
-      : target.duration_ms,
-  }
-}
-
-function allowedCatalogImageUrl(raw: string | URL): URL | null {
-  try {
-    const url = new URL(raw)
-    if (url.protocol !== "https:" || !url.hostname.endsWith(".mzstatic.com")) {
-      return null
-    }
-    return url
-  } catch {
-    return null
-  }
-}
-
-export async function readLimitedResponse(
-  response: Response,
-  maxBytes: number,
-): Promise<Uint8Array | null> {
-  const declared = Number(response.headers.get("content-length"))
-  if (Number.isFinite(declared) && declared > maxBytes) return null
-  if (!response.body) return new Uint8Array()
-
-  const bytes = new Uint8Array(maxBytes)
-  const reader = response.body.getReader()
-  let total = 0
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      if (total + value.byteLength > maxBytes) {
-        await reader.cancel("artwork exceeds byte limit")
-        return null
-      }
-      bytes.set(value, total)
-      total += value.byteLength
-    }
-  } finally {
-    reader.releaseLock()
-  }
-
-  return bytes.slice(0, total)
-}
-
-export async function downloadCatalogImage(
-  rawUrl: string,
-  fetcher: Fetcher = fetch,
-): Promise<Uint8Array | null> {
-  const url = allowedCatalogImageUrl(rawUrl)
-  if (!url) return null
-  try {
-    const response = await fetcher(url, {
-      redirect: "error",
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-    })
-    if (!response.ok || response.redirected) return null
-    if (response.url && !allowedCatalogImageUrl(response.url)) return null
-    return readLimitedResponse(response, MAX_ARTWORK_BYTES)
-  } catch {
-    return null
-  }
-}
-
-async function catalogArtwork(
-  target: TrackIdentity,
-  fetcher: Fetcher = fetch,
-): Promise<{ bytes: Uint8Array | null; duration_ms: number } | null> {
-  if (!target.title || !target.artist) return null
-  const term = [target.artist, target.title, target.album]
-    .filter(Boolean)
-    .join(" ")
-  const url = new URL("https://itunes.apple.com/search")
-  url.searchParams.set("term", term)
-  url.searchParams.set("entity", "song")
-  url.searchParams.set("limit", "10")
-
-  try {
-    const result = await fetcher(url, {
-      redirect: "error",
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-    })
-    if (!result.ok || result.redirected) return null
-    const responseBytes = await readLimitedResponse(
-      result,
-      MAX_CATALOG_RESPONSE_BYTES,
-    )
-    if (!responseBytes) return null
-    const payload = JSON.parse(new TextDecoder().decode(responseBytes)) as {
-      results?: CatalogTrack[]
-    }
-    const results = payload.results ?? []
-    const resolution = selectCatalogResolution(target, results)
-    const bytes = resolution.artworkUrl
-      ? await downloadCatalogImage(resolution.artworkUrl, fetcher)
-      : null
-    if (!resolution.artworkUrl && resolution.duration_ms === target.duration_ms)
-      return null
-    return { bytes, duration_ms: resolution.duration_ms }
-  } catch {
-    return null
-  }
-}
-
 export function imageDimensionsAreSafe(width: number, height: number): boolean {
   return (
     Number.isInteger(width) &&
@@ -356,7 +163,9 @@ export async function resolveArtworkDetails(
   nativeBase64: string | null,
   legacyId = id,
   fetcher: Fetcher = fetch,
+  signal?: AbortSignal,
 ): Promise<ArtworkResolution> {
+  if (signal?.aborted) return { artwork: null, duration_ms: target.duration_ms }
   const candidates: Uint8Array[] = []
   if (nativeBase64) {
     try {
@@ -390,8 +199,15 @@ export async function resolveArtworkDetails(
     }
   }
 
-  const catalog = await catalogArtwork(target, fetcher)
-  if (!catalog) return { artwork: null, duration_ms: target.duration_ms }
+  const catalog = await acquireCatalogArtwork(target, {
+    fetch: fetcher,
+    signal,
+  })
+  if (catalog.kind !== "available" || signal?.aborted)
+    return {
+      artwork: null,
+      duration_ms: catalog.duration_ms ?? target.duration_ms,
+    }
   if (!catalog.bytes) {
     return { artwork: null, duration_ms: catalog.duration_ms }
   }

package/index.tsx

@@ -26,6 +26,7 @@ export type Controller = {
   subscribe: (listener: (session: SessionStore) => void) => () => void
   openApp: () => Promise<void>
   refreshAll: () => Promise<void>
+  refreshArtwork: () => Promise<void>
   playPause: () => Promise<void>
   seek: (positionMs: number) => Promise<void>
   next: () => Promise<void>
@@ -321,6 +322,14 @@ export function createController(
       return () => sessionListeners.delete(listener)
     },
     refreshAll,
+    refreshArtwork: async () => {
+      if (!isActive()) return
+      try {
+        await media.refreshArtwork()
+      } catch (error) {
+        if (isActive()) setTransportError(errMsg(error))
+      }
+    },
     async openApp() {
       if (!isActive()) return
       try {
@@ -396,6 +405,14 @@ function AppHost(props: { context: Context; ctrl: Controller }) {
         slash: { name: "music-app" },
         run: () => void ctrl.openApp(),
       },
+      {
+        id: "music.refresh-artwork",
+        title: "Refresh artwork",
+        group: "Music",
+        palette: true,
+        slash: { name: "music-artwork" },
+        run: () => void ctrl.refreshArtwork(),
+      },
     ],
   }))
   return (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naxodev/opencode-music-player",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "macOS system Now Playing controls for the OpenCode 2 TUI",
   "license": "MIT",
   "author": {
@@ -62,20 +62,21 @@
     "format:check": "prettier --check .",
     "check": "tsc --noEmit",
     "test": "bun test --preload @opentui/solid/preload",
-    "pack:check": "bun run scripts/verify-pack.ts",
+    "pack:check": "bun run ../../scripts/music-release.ts opencode-music-player --staged-only && bun run scripts/verify-pack.ts",
+    "prepublish:core": "bun run ../../scripts/music-release.ts opencode-music-player",
     "smoke:package": "bun run scripts/package-smoke.ts",
     "validate": "bun run format:check && bun run check && bun run test && bun run pack:check"
   },
   "dependencies": {
-    "@naxodev/music-core": "^0.1.1",
+    "@naxodev/music-core": "^0.1.4",
     "@opencode-ai/plugin": "0.0.0-next-17444",
-    "@opentui/core": "0.5.3",
-    "@opentui/solid": "0.5.3",
+    "@opentui/core": "0.5.4",
+    "@opentui/solid": "0.5.4",
     "pngjs": "^7.0.0",
-    "solid-js": "1.9.12"
+    "solid-js": "1.9.15"
   },
   "devDependencies": {
-    "@opencode-ai/theme": "0.0.0-next-17444",
+    "@opencode-ai/theme": "0.0.0",
     "@types/bun": "^1.3.14",
     "@types/pngjs": "^6.0.5",
     "prettier": "3.9.6",

package/system-media.ts

@@ -27,8 +27,7 @@ type ArtworkCacheEntry = {
   duration_ms: number
   resolved: boolean
   pending: boolean
-  attempts: number
-  retry_at: number
+  abort: AbortController
   interests: Map<PresentationHost, ArtworkIdentity>
 }
 const MAX_ARTWORK_ENTRIES = 32
@@ -52,7 +51,9 @@ const waitingArtwork = new Map<string, DeferredArtwork>()
 type ArtworkResolver = typeof resolveArtworkDetails
 
 /** Public-contract-only seam for the reconnecting session adapter. */
-export type SessionClientFactory = () => Promise<ReconnectingMusicSessionClient>
+export type SessionClientFactory = (
+  signal?: AbortSignal,
+) => Promise<ReconnectingMusicSessionClient>
 export type SessionSystemMediaOverrides = {
   readonly createClient?: SessionClientFactory
   readonly resolveArtworkDetails?: ArtworkResolver
@@ -60,11 +61,12 @@ export type SessionSystemMediaOverrides = {
 }
 
 let sessionClientSequence = 0
-const createOpenCodeSessionClient: SessionClientFactory = () =>
+const createOpenCodeSessionClient: SessionClientFactory = (signal) =>
   createReconnectingMusicSessionClient({
     clientId: `opencode-music-player-${++sessionClientSequence}`,
     hostKind: "opencode",
     capabilities: [...baselineCapabilities],
+    ...(signal ? { signal } : {}),
   })
 
 type PresentationHost = {
@@ -189,6 +191,7 @@ function removeArtworkInterests(host: PresentationHost) {
   // A host owns only its interest. The physical job keeps its slot until it settles.
   for (const entry of artworkJobs.values()) {
     entry.interests.delete(host)
+    if (!entry.interests.size) entry.abort.abort()
   }
 }
 
@@ -202,9 +205,10 @@ function artworkForTrack(
   identity: ArtworkIdentity,
   now: () => number,
 ): { artwork: Artwork | null; duration_ms: number; loading: boolean } {
-  let entry = artworkCache.get(key) ?? artworkJobs.get(key)
+  let entry = artworkJobs.get(key) ?? artworkCache.get(key)
+  if (entry?.abort.signal.aborted) entry = undefined
   if (!entry) {
-    if (artworkJobs.size >= MAX_ARTWORK_ENTRIES) {
+    if (artworkJobs.has(key) || artworkJobs.size >= MAX_ARTWORK_ENTRIES) {
       removeWaitingInterest(host)
       let deferred = waitingArtwork.get(key)
       if (!deferred && waitingArtwork.size < MAX_ARTWORK_ENTRIES) {
@@ -235,22 +239,15 @@ function artworkForTrack(
       duration_ms: target.duration_ms,
       resolved: false,
       pending: false,
-      attempts: 0,
-      retry_at: 0,
+      abort: new AbortController(),
       interests: new Map(),
     }
   }
   // A state change that reached admission supersedes any older deferred
   // identity owned by this adapter generation.
   removeWaitingInterest(host)
-  if (
-    !entry.pending &&
-    entry.attempts < 3 &&
-    now() >= entry.retry_at &&
-    (!entry.resolved || entry.value === null)
-  ) {
+  if (!entry.pending && !entry.resolved) {
     entry.pending = true
-    entry.attempts++
     artworkJobs.set(key, entry)
     const activeEntry = entry
     void (async () => {
@@ -260,15 +257,24 @@ function artworkForTrack(
       } catch {
         // Session artwork failure is transient; host catalog fallback remains.
       }
-      return resolver(key, target, data, legacyKey)
+      return resolver(
+        key,
+        target,
+        data,
+        legacyKey,
+        undefined,
+        activeEntry.abort.signal,
+      )
     })().then(
       (resolution) => {
         activeEntry.value = resolution.artwork
         activeEntry.duration_ms = resolution.duration_ms
         activeEntry.resolved = true
         activeEntry.pending = false
-        if (!resolution.artwork)
-          activeEntry.retry_at = now() + 2_000 * 2 ** (activeEntry.attempts - 1)
+        if (activeEntry.abort.signal.aborted) {
+          releaseArtworkSlot(key)
+          return
+        }
         settleArtworkEntry(key, activeEntry)
         publishArtworkCompletion(activeEntry, resolution.artwork)
       },
@@ -276,7 +282,10 @@ function artworkForTrack(
         activeEntry.value = null
         activeEntry.resolved = true
         activeEntry.pending = false
-        activeEntry.retry_at = now() + 2_000 * 2 ** (activeEntry.attempts - 1)
+        if (activeEntry.abort.signal.aborted) {
+          releaseArtworkSlot(key)
+          return
+        }
         settleArtworkEntry(key, activeEntry)
         publishArtworkCompletion(activeEntry, null)
       },
@@ -302,8 +311,10 @@ export function createSessionSystemMedia(
   const now = overrides.now ?? Date.now
   const listeners = new Set<(event: SessionMediaEvent) => void>()
   const presentationListeners = new Set<ArtworkPresentationListener>()
+  const acquisitionAbort = new AbortController()
   let disposed = false
   let currentArtworkIdentity: string | null = null
+  let currentArtworkKey: string | null = null
   let client: ReconnectingMusicSessionClient | undefined
   let installed = false
   let latest: RevisionedState | undefined
@@ -315,10 +326,10 @@ export function createSessionSystemMedia(
   let clientReleased = false
   let disposal: Promise<void> | undefined
 
-  const releaseClient = (next: ReconnectingMusicSessionClient) => {
-    if (clientReleased) return Promise.resolve()
+  const releaseClient = async (next: ReconnectingMusicSessionClient) => {
+    if (clientReleased) return
     clientReleased = true
-    return Promise.resolve(next.dispose()).catch(() => {})
+    await next.dispose()
   }
   const emit = (event: SessionMediaEvent) => {
     if (disposed) return
@@ -384,6 +395,11 @@ export function createSessionSystemMedia(
     emit(event)
   }
   const project = (state: RevisionedState | undefined): PlayerState | null => {
+    const nextKey = state?.state.track
+      ? artworkCacheKey(identityFromTrack(state.state.track))
+      : null
+    if (nextKey !== currentArtworkKey) removeArtworkInterests(host)
+    currentArtworkKey = nextKey
     if (!state) {
       currentArtworkIdentity = null
       return null
@@ -458,10 +474,12 @@ export function createSessionSystemMedia(
     ]
   }
   const clientPromise = Promise.resolve()
-    .then(factory)
+    .then(() => factory(acquisitionAbort.signal))
     .then((next) => {
       if (disposed) {
-        void releaseClient(next)
+        void releaseClient(next).catch((error) => {
+          console.error("Failed to dispose late music session client", error)
+        })
         return next
       }
       install(next)
@@ -484,6 +502,16 @@ export function createSessionSystemMedia(
       await activeClient()
       return project(latest)
     },
+    async refreshArtwork() {
+      await activeClient()
+      const track = latest?.state.track
+      if (!track) return
+      const key = artworkCacheKey(identityFromTrack(track))
+      // Repeated refreshes join active work; no new slot or retry budget.
+      if (artworkJobs.has(key)) return
+      artworkCache.delete(key)
+      emit({ type: "snapshot", state: project(latest)! })
+    },
     async play() {
       await (await activeClient()).play()
     },
@@ -528,18 +556,30 @@ export function createSessionSystemMedia(
     dispose() {
       if (disposal) return disposal
       disposed = true
-      for (const unsubscribe of unsubscribers.splice(0)) {
-        try {
-          unsubscribe()
-        } catch {}
-      }
-      listeners.clear()
-      presentationListeners.clear()
-      removeArtworkInterests(host)
-      disposal = clientPromise.then(
-        (next) => releaseClient(next),
-        () => undefined,
-      )
+      disposal = Promise.resolve().then(async () => {
+        const errors: unknown[] = []
+        for (const unsubscribe of unsubscribers.splice(0)) {
+          try {
+            unsubscribe()
+          } catch (error) {
+            errors.push(error)
+          }
+        }
+        listeners.clear()
+        presentationListeners.clear()
+        removeArtworkInterests(host)
+        // Acquisition is cooperative. A late client is released by its callback.
+        if (client) {
+          try {
+            await releaseClient(client)
+          } catch (error) {
+            errors.push(error)
+          }
+        }
+        if (errors.length)
+          throw new AggregateError(errors, "music session cleanup failed")
+      })
+      acquisitionAbort.abort()
       return disposal
     },
   }

package/types.ts

@@ -68,6 +68,7 @@ export type SessionMediaDisposer = () => void
 /** The OpenCode controller's session-only media contract. */
 export type SessionMedia = {
   player: () => Promise<PlayerState | null>
+  refreshArtwork: () => Promise<void>
   play: () => Promise<unknown>
   pause: () => Promise<unknown>
   next: () => Promise<unknown>