@naxodev/opencode-music-player 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+This file records the initial package release. Later versions use generated [GitHub release notes](https://github.com/naxodev/ai/releases?q=opencode-music-player).
+
+## [0.1.0] - 2026-08-20
+
+### Added
+
+- Initial macOS system Now Playing integration for the OpenCode 2 TUI.
+- Playback controls, progress display, expandable details, and waveform visualization.
+
+### Changed
+
+- Move the player from the footer overlay into the OpenCode sidebar.
+- Keep a responsive one-row music bar below the active route when the sidebar is collapsed.
+- Simplify compact metadata from title and artist to title, truncated title, then playback marker as terminal width decreases.
+- Display native album artwork in Kitty-compatible terminals with a true-color fallback elsewhere.
+- Support native artwork through Herdr and tmux graphics passthrough.
+- Resolve missing system artwork through exact iTunes catalog matches.
+- Refresh promptly for provider changes, retain bounded polling fallback, and clean up subscriptions on plugin disposal.
+
+### Fixed
+
+- Re-anchor native album artwork and remove stale Kitty images when its sidebar slot moves or resizes.
+
+[0.1.0]: https://github.com/naxodev/ai/releases/tag/opencode-music-player@v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nacho Vazquez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @naxodev/opencode-music-player
+
+A sidebar player and compact bottom bar for the OpenCode 2 TUI that display and control the active macOS system media session.
+
+It supports browsers, Spotify, Apple Music, Kaset, and other apps exposed through [`media-control`](https://github.com/ungive/media-control). The player keeps the existing OpenCode theme and provides keyboard and mouse controls.
+
+## Architecture
+
+One reconnecting music-session client supplies replayed and live state, provider status, transport, and daemon-owned native artwork bytes. The shared same-user daemon owns provider discovery, provider events and polling, the playback clock, and global transport ordering.
+
+OpenCode keeps plugin/controller lifecycle, the Solid compact and sidebar UI, optimistic transport presentation, seek coalescing, notifications, waveform projection, iTunes catalog fallback and downloads, conversion, bounded presentation cache/jobs, and Kitty or half-block rendering. Plugin disposal removes local listeners and presentation work, then disposes only its session client. Other clients keep the shared daemon alive.
+
+Read the [music session architecture field guide](../../docs/music-session-architecture.html) for the daemon protocol, replay, reconnect, and cleanup model.
+
+## Artwork
+
+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.
+
+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.
+
+Herdr users can enable its experimental renderer in `~/.config/herdr/config.toml`:
+
+```toml
+[experimental]
+kitty_graphics = true
+```
+
+tmux 3.3 and later users must allow wrapped graphics passthrough in `~/.tmux.conf`:
+
+```tmux
+set -g allow-passthrough on
+```
+
+> [!IMPORTANT]
+> This package targets the beta OpenCode 2 TUI plugin API in `opencode2 v0.0.0-next-17395`. OpenCode may change this API before its stable release.
+
+## Requirements
+
+- macOS
+- OpenCode 2 `v0.0.0-next-17395`
+- Bun, which OpenCode uses to load TypeScript plugin packages
+- [`media-control`](https://github.com/ungive/media-control), recommended:
+
+  ```sh
+  brew tap ungive/media-control
+  brew install media-control
+  ```
+
+[`nowplaying-cli`](https://github.com/kirtan-shah/nowplaying-cli) is a fallback. Its play state can freeze for some media apps.
+
+## Install
+
+Add the package to the `plugin` array in your global `~/.config/opencode/tui.jsonc` or project `.opencode/tui.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@naxodev/opencode-music-player"],
+}
+```
+
+OpenCode installs npm plugin packages and their production dependencies in its isolated cache. Restart OpenCode after changing the package entry.
+
+### Local checkout
+
+OpenCode imports local packages directly and does not install their dependencies. Install them first:
+
+```sh
+git clone https://github.com/naxodev/ai.git
+cd ai
+bun install --frozen-lockfile
+```
+
+Then reference the absolute package path:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["/absolute/path/to/ai/packages/opencode-music-player"],
+}
+```
+
+## Verify
+
+Start OpenCode and list active plugin IDs:
+
+```sh
+opencode2 api get /api/plugin
+```
+
+The response should include `music-player`. If it does not, inspect `~/.local/share/opencode/log/opencode.log` for package resolution or setup errors.
+
+## Controls
+
+The compact bar appears below the active route whenever a current track exists, including while playback is paused. It remains visible when the session sidebar is collapsed. Wide terminals show the playback marker, title, and artist. Medium terminals omit the artist. Narrow terminals truncate the title, then keep only the playback marker when metadata cannot fit safely. The bar always stays on one row.
+
+| Input              | Action         |
+| ------------------ | -------------- |
+| `ctrl+shift+p`     | Play or pause  |
+| `ctrl+shift+left`  | Previous track |
+| `ctrl+shift+right` | Next track     |
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run check
+```
+
+The workspace smoke packs OpenCode and music-core, installs them into an isolated project, and launches the exact manifest-selected OpenCode CLI. It verifies the packed plugin's deterministic playing, paused, collapsed, narrow, and smallest layouts. See the workspace [contribution guide](../../CONTRIBUTING.md) for the contribution and release process.
+
+## Community
+
+- Ask usage questions in [GitHub Discussions](https://github.com/naxodev/ai/discussions).
+- Report reproducible bugs with the [bug form](https://github.com/naxodev/ai/issues/new?template=bug.yml).
+- Read [SUPPORT.md](SUPPORT.md) before requesting support.
+- Report vulnerabilities privately as described in the workspace [security policy](../../SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/SUPPORT.md

@@ -0,0 +1,7 @@
+# Support
+
+Use [GitHub Discussions](https://github.com/naxodev/ai/discussions) for installation and usage questions.
+
+Use [GitHub Issues](https://github.com/naxodev/ai/issues) for reproducible defects and focused feature requests. Include your macOS version, `opencode2 --version`, package version, media backend, and relevant redacted logs.
+
+Security reports must follow the workspace [security policy](../../SECURITY.md).

package/artwork-placement.ts

@@ -0,0 +1,169 @@
+/**
+ * Pure planner for native Kitty album-artwork placement.
+ *
+ * Decides which cleanup/draw actions to run when slot geometry or image
+ * identity changes. No I/O, no PNG bytes, no terminal writes.
+ *
+ * **Write-failure / `nextState` commit rule (Phase 2 executor):**
+ * `nextState` is the state to commit **only after every planned action is
+ * applied successfully**. On any failed write, the executor must keep the
+ * previous `state` so the next frame retries from a known-good snapshot.
+ * This module only proposes the post-success state; it does not simulate I/O.
+ */
+
+export type NativeArtworkPlacement = {
+  imageId: number
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export type NativeArtworkState = {
+  /** Kitty image id currently believed transmitted (`0` = none). */
+  transmitted: number
+  /** Last successfully applied geometry, or `null`. */
+  placement: NativeArtworkPlacement | null
+}
+
+export type NativeArtworkPlacementInput = {
+  state: NativeArtworkState
+  /** Desired Kitty image id for current artwork; ignored when clearing. */
+  imageId: number
+  /** Desired absolute cell geometry (caller applies any tmux offset). */
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Host can show native graphics. */
+  kittySupported: boolean
+  /** Container present, not destroyed, `width >= 1`, `height >= 1`. */
+  slotValid: boolean
+  /** Component tearing down. */
+  disposed: boolean
+}
+
+export type NativeArtworkPlacementAction =
+  | { type: "delete-image"; imageId: number }
+  | { type: "delete-placement"; imageId: number }
+  | {
+      type: "transmit-and-display"
+      imageId: number
+      x: number
+      y: number
+      width: number
+      height: number
+    }
+  | {
+      type: "place"
+      imageId: number
+      placementId: number
+      x: number
+      y: number
+      width: number
+      height: number
+    }
+
+export type NativeArtworkPlacementPlan = {
+  actions: NativeArtworkPlacementAction[]
+  /**
+   * Proposed state after successful apply of every action.
+   * Do not commit on partial/failed writes — see module JSDoc.
+   */
+  nextState: NativeArtworkState
+}
+
+const CLEARED_STATE: NativeArtworkState = {
+  transmitted: 0,
+  placement: null,
+}
+
+/** Stable key matching the historical `imageId:x:y:width:height` string shape. */
+export function placementKey(placement: NativeArtworkPlacement): string {
+  return [
+    placement.imageId,
+    placement.x,
+    placement.y,
+    placement.width,
+    placement.height,
+  ].join(":")
+}
+
+function samePlacement(
+  a: NativeArtworkPlacement | null,
+  b: NativeArtworkPlacement,
+): boolean {
+  return a !== null && placementKey(a) === placementKey(b)
+}
+
+/**
+ * Plan Kitty cleanup/draw actions for the next native-artwork frame.
+ *
+ * Decision table:
+ * 1. disposed / unsupported / invalid slot → delete transmitted image (if any)
+ * 2. different image id (incl. first paint) → delete old image, then transmit-and-display
+ * 3. same image id, geometry changed → delete-placement then place
+ * 4. same image id, same geometry → no-op
+ */
+export function planNativeArtworkPlacement(
+  input: NativeArtworkPlacementInput,
+): NativeArtworkPlacementPlan {
+  const { state, imageId, x, y, width, height } = input
+  const desired: NativeArtworkPlacement = { imageId, x, y, width, height }
+
+  if (input.disposed || !input.kittySupported || !input.slotValid) {
+    if (state.transmitted !== 0) {
+      return {
+        actions: [{ type: "delete-image", imageId: state.transmitted }],
+        nextState: CLEARED_STATE,
+      }
+    }
+    return { actions: [], nextState: state }
+  }
+
+  if (state.transmitted !== imageId) {
+    const actions: NativeArtworkPlacementAction[] = []
+    if (state.transmitted !== 0) {
+      actions.push({ type: "delete-image", imageId: state.transmitted })
+    } else {
+      // A remount loses local state, but the terminal may still hold this ID.
+      actions.push({ type: "delete-image", imageId })
+    }
+    actions.push({
+      type: "transmit-and-display",
+      imageId,
+      x,
+      y,
+      width,
+      height,
+    })
+    return {
+      actions,
+      nextState: { transmitted: imageId, placement: desired },
+    }
+  }
+
+  // Same image id.
+  if (samePlacement(state.placement, desired)) {
+    return { actions: [], nextState: state }
+  }
+
+  const actions: NativeArtworkPlacementAction[] = []
+  // Applied placement or transmitted image → clear old placement first.
+  if (state.placement !== null || state.transmitted !== 0) {
+    actions.push({ type: "delete-placement", imageId })
+  }
+  actions.push({
+    type: "place",
+    imageId,
+    placementId: imageId,
+    x,
+    y,
+    width,
+    height,
+  })
+  return {
+    actions,
+    nextState: { transmitted: imageId, placement: desired },
+  }
+}