# Plan: #12 — Move queue frontend→backend communication to Wails bindings

## Goal

Replace the 15 `Request*` events (frontend→backend) with direct Wails bindings while keeping the 4 backend→frontend push events (`QueueChanged`, `QueueIndexChanged`, `QueueModeChanged`, `QueueTracksModified`) intact. This eliminates ~420 lines of handler boilerplate in Go and aligns the queue's communication pattern with playlists.

## Rationale

**Why bindings for frontend→backend (replacing events):**
- Eliminates 420 lines of hand-written type-assertion boilerplate in `handlers.go`
- Provides compile-time type safety — Wails auto-generates typed TypeScript bindings from Go method signatures, so `float64`→`int` casting, `[]interface{}`→`[]string` conversion, and `len(data)` validation all disappear
- Adding a new queue operation becomes a 1-file change (add Go method) vs the current 4-file change (Go event constant, TS event constant, Go handler, TS store method)
- Aligns with the playlist pattern, reducing cognitive overhead

**Why keep events for backend→frontend (not replacing with invalidate-and-refetch):**
- The queue's delta system (`QueueTracksModified` with add/insert/remove/move actions) is genuinely good architecture for a data structure that changes frequently during playback
- Avoids unnecessary round-trips — the backend pushes only what changed
- The playlist's invalidate-and-refetch pattern works for playlists (infrequent mutations) but would be wasteful for a queue (changes on every track advance)

## Prerequisites

The queue must be created in `NewYellowJacketApp()` (before `wails.Run()`) rather than in `OnStartup()`, because Wails v2 consumes the `Bind` slice eagerly at startup via reflection. The struct pointer must be non-nil and fully constructed at `Bind` time.

This is safe because `queue.NewQueue()` only needs `logger` and `db` (both already available in `NewYellowJacketApp`). The player dependency and context are set later via `SetPlayer()` and `SetContext()` during `OnStartup`, which is the existing two-phase initialization pattern used by all other bound services.

## Detailed Steps

### Step 1: Move queue construction to `NewYellowJacketApp` and add to `FEBindings`

**File:** `backend/app.go`

In `NewYellowJacketApp()`, after the playlist service is created (~line 104), add:

```go
yjApp.queue = queue.NewQueue(yjApp.logger, yjApp.database)
```

Add the queue to `FEBindings`:

```go
yjApp.FEBindings = []any{
    yjApp.FrontendUtil,
    yjApp.appConfig,
    yjApp.library,
    yjApp.playlist,
    yjApp.queue,
}
```

In `OnStartup()`, remove `queue.NewQueue(...)` and keep only the deferred initialization:

```go
yj.queue.SetContext(ctx)
yj.queue.SetPlayer(yj.player)
yj.queue.RestoreState()
```

### Step 2: Remove `registerEventHandlers()` and all handler boilerplate

**File:** `backend/queue/handlers.go`

Remove:
- `registerEventHandlers()` — all 16 `runtime.EventsOn` registrations (lines 41-172)
- All 10 `handle*` functions (lines 201-461): `handleSetQueue`, `handleAddToQueue`, `handlePlayNext`, `handleRemoveFromQueue`, `handleRemoveTracksFromQueue`, `handleAddTracksToQueue`, `handleInsertTracksAtIndex`, `handleMoveQueueTracks`, `handlePlayQueueIndex`, `handlePlayTracksNext`
- The two helper functions `toStringSlice` and `toIntSlice` (lines 175-199)

Keep:
- `OnPlaybackFinished()` (lines 11-38) — this is domain logic, not event boilerplate

**File:** `backend/queue/queue.go`

In `SetContext()`, remove the call to `q.registerEventHandlers()`. The method becomes:

```go
func (q *Queue) SetContext(ctx context.Context) {
    q.ctx = ctx
}
```

### Step 3: Remove the 15 `Request*` queue event constants

**File:** `backend/events/events.go`

Remove from the "Queue events" const block (lines 38-52):
- `RequestNext`
- `RequestPrevious`
- `RequestSetQueue`
- `RequestAddToQueue`
- `RequestPlayNext`
- `RequestRemoveFromQueue`
- `RequestToggleShuffle`
- `RequestCycleRepeat`
- `RequestAddTracksToQueue`
- `RequestPlayTracksNext`
- `RequestPlayQueueIndex`
- `RequestRemoveTracksFromQueue`
- `RequestInsertTracksAtIndex`
- `RequestMoveQueueTracks`
- `RequestClearQueue`

Keep `RequestPlay` — it's in the "Playback control events" block and is used by the queue's event handler. Since we're removing `registerEventHandlers`, also remove `RequestPlay` from the queue's event handler. But check if `RequestPlay` is still used by the player package first.

> **Note:** `RequestPlay` is currently handled by the queue (in `handlers.go:48`), not the player. After this refactor, the queue's `Play()` method will be callable directly via bindings, so the `RequestPlay` event handler in the queue is no longer needed. However, `RequestPlay` may still be emitted by the frontend for player-related actions — audit all `RequestPlay` usages before removing the constant.

**File:** `frontend/src/events.ts`

Remove the corresponding 15 `Request*` constants from lines 28-42. Keep the 4 backend→frontend queue events (lines 24-27).

### Step 4: Rewrite the queue store to use Wails bindings

**File:** `frontend/src/store/queue-store.ts`

Replace the 14 action methods that call `EventsEmit(Events.Request*)` with direct calls to the auto-generated Wails bindings.

**Before** (example):
```typescript
import { EventsOn, EventsEmit } from '@runtime/runtime';
import { Events } from '../events';

// ...
next(): void {
    EventsEmit(Events.RequestNext);
}

setQueue(filePaths: string[], startIndex: number, shuffleStart = false): void {
    EventsEmit(Events.RequestSetQueue, filePaths, startIndex, shuffleStart);
}
```

**After** (example):
```typescript
import { EventsOn } from '@runtime/runtime';
import { Events } from '../events';
import * as QueueService from '@go/queue/Queue';

// ...
next(): void {
    QueueService.Next();
}

setQueue(filePaths: string[], startIndex: number, shuffleStart = false): void {
    QueueService.SetQueue(filePaths, startIndex, shuffleStart);
}
```

Keep the entire `initializeEventListeners()` method unchanged — the 4 backend→frontend event subscriptions (`QueueChanged`, `QueueIndexChanged`, `QueueModeChanged`, `QueueTracksModified`) and the `applyTracksDelta()` logic remain as-is.

Remove the `EventsEmit` import if no longer needed after removing all `Request*` emissions.

**Complete action method mapping** (queue store method → Wails binding):

| Store method | Current event | Wails binding call |
|---|---|---|
| `next()` | `RequestNext` | `QueueService.Next()` |
| `previous()` | `RequestPrevious` | `QueueService.Previous()` |
| `setQueue(filePaths, startIndex, shuffleStart)` | `RequestSetQueue` | `QueueService.SetQueue(filePaths, startIndex, shuffleStart)` |
| `addToQueue(filePath)` | `RequestAddToQueue` | `QueueService.AddTrack(filePath)` |
| `playNext(filePath)` | `RequestPlayNext` | `QueueService.InsertNext(filePath)` |
| `removeFromQueue(position)` | `RequestRemoveFromQueue` | `QueueService.RemoveTrack(position)` |
| `removeTracksFromQueue(positions)` | `RequestRemoveTracksFromQueue` | `QueueService.RemoveTracks(positions)` |
| `addTracksToQueue(filePaths)` | `RequestAddTracksToQueue` | `QueueService.AddTracks(filePaths)` |
| `playTracksNext(filePaths)` | `RequestPlayTracksNext` | `QueueService.InsertNextTracks(filePaths)` |
| `toggleShuffle()` | `RequestToggleShuffle` | `QueueService.ToggleShuffle()` |
| `cycleRepeat()` | `RequestCycleRepeat` | `QueueService.CycleRepeat()` |
| `playAtIndex(index)` | `RequestPlayQueueIndex` | `QueueService.PlayIndex(index)` |
| `insertTracksAtIndex(filePaths, index)` | `RequestInsertTracksAtIndex` | `QueueService.InsertTracksAt(filePaths, index)` |
| `moveTracksInQueue(fromIndices, toIndex)` | `RequestMoveQueueTracks` | `QueueService.MoveQueueTracks(fromIndices, toIndex)` |
| `clearQueue()` | `RequestClearQueue` | `QueueService.Clear()` |

> **Note:** Some store method names don't match Go method names (e.g., `addToQueue` → `AddTrack`, `playNext` → `InsertNext`). The store method names can remain unchanged for API stability — only the implementation changes.

### Step 5: Handle `Play()` specifically

The queue's `Play()` method is currently triggered by the `RequestPlay` event, which is in the "Playback control events" group and is also emitted by `player-controls.ts`. After this refactor:

- The `RequestPlay` event handler in `handlers.go:48` is removed along with all other handlers
- The frontend should call `QueueService.Play()` directly instead of `EventsEmit(Events.RequestPlay)`

Audit all places that emit `RequestPlay`:
- `frontend/src/components/audio-player/controls/player-controls.ts` — the play button emits `RequestPlay`. This should be changed to call `QueueService.Play()` (or more likely, the queue store should expose a `play()` method that delegates to the binding)

If `RequestPlay` has no other consumers after this change, remove the event constant from both `events.go` and `events.ts`.

### Step 6: Regenerate Wails bindings

Run `wails generate module` (or `make dev` which triggers binding generation) to produce the auto-generated files:

- `frontend/wailsjs/go/queue/Queue.js` — JavaScript bridge calling `window['go']['queue']['Queue'][method](...)`
- `frontend/wailsjs/go/queue/Queue.d.ts` — TypeScript declarations with proper types
- `frontend/wailsjs/go/models.ts` — Updated with `queue.Track`, `queue.State`, `queue.RepeatMode`, etc.

> **Important:** The auto-generated TypeScript types will mirror the Go struct JSON tags, so the frontend types already defined in `queue-store.ts` (`QueueTrack`, `QueueState`, `IndexChanged`, `ModeChanged`, `TracksModified`) will have matching auto-generated equivalents in `models.ts`. We should keep the manually-defined types in the store (they're used by the event listeners which still need them) but could optionally import the model types where convenient.

### Step 7: Handle `SetContext` visibility

When a struct is added to Wails `FEBindings`, **all exported methods** become callable from JavaScript. `SetContext(ctx context.Context)` and `SetPlayer(player TrackLoader)` would be exposed, which is undesirable — they're internal lifecycle methods, not frontend API.

Options:
1. **Unexport them** — rename to `setContext`/`setPlayer`. This requires updating `app.go` to call `q.setContext(ctx)` etc. But unexported methods on structs in other packages aren't accessible, so this won't work without making them package-internal.
2. **Create a thin facade struct** — a `Service` (or `API`) struct that embeds or wraps `*Queue` and only exposes the methods the frontend should call. This is the playlist pattern (`playlist.Service`).
3. **Accept the exposure** — Wails will generate bindings for `SetContext` and `SetPlayer`, but the frontend simply won't call them. They'll be inert in the generated JS. This is what happens with `playlist.Service.SetContext` — it's in the generated `Service.js` but never imported by the frontend.

**Recommendation:** Option 3 — accept it. The playlist already has `SetContext` exposed in its generated bindings (`frontend/wailsjs/go/playlist/Service.js:69`) and it's not a problem. Wails bindings are not a security boundary (the frontend and backend are in the same process). The generated bindings are auto-generated artifacts, not a public API. No one will accidentally call `SetContext` from the frontend.

If `SetPlayer` is a concern because `TrackLoader` is an interface type that Wails can't serialize, Wails may skip it or error during binding generation. If so, either unexport `SetPlayer` only, or have `app.go` set it via an unexported package-level function. This needs testing during step 6.

### Step 8: Update `queue-controller.ts` (no changes needed)

The `QueueController` (`frontend/src/store/controllers/queue-controller.ts`) proxies all actions through `queueStore.*()`. Since we're only changing the store's internal implementation (from `EventsEmit` to binding calls), the controller needs zero changes. All 14 action proxy methods remain identical.

### Step 9: Update components that call `queueStore` directly (no changes needed)

These 6 components import `queueStore` and call its action methods:
- `player-controls.ts` — `queueStore.next()`, `.previous()`, `.toggleShuffle()`, `.cycleRepeat()`
- `track-list.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
- `cover-grid.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
- `genres-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
- `artists-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
- `playlist-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`

Since the store's public API (method signatures) is unchanged, none of these components need modifications.

**Exception:** `player-controls.ts` currently emits `Events.RequestPlay` directly for the play/pause button (not through the queue store). This specific call site needs to be updated to either:
- Call `queueStore.play()` (add a `play()` method to the store), or
- Call `QueueService.Play()` directly

### Step 10: Run tests, lint, and build

```bash
make test          # Verify Go tests pass (especially queue tests)
make lint          # Verify linting passes
cd frontend && pnpm exec tsc --noEmit   # Verify TypeScript types
make build-dev     # Full build to verify Wails binding generation works
```

## Files Modified

| File | Action | Description |
|---|---|---|
| `backend/app.go` | Edit | Move queue construction; add to `FEBindings` |
| `backend/queue/handlers.go` | Major edit | Remove all `handle*` functions, `registerEventHandlers`, `toStringSlice`, `toIntSlice`. Keep only `OnPlaybackFinished` |
| `backend/queue/queue.go` | Edit | Remove `registerEventHandlers()` call from `SetContext` |
| `backend/events/events.go` | Edit | Remove 15 `Request*` queue constants |
| `frontend/src/events.ts` | Edit | Remove 15 `Request*` queue constants |
| `frontend/src/store/queue-store.ts` | Edit | Replace `EventsEmit` action methods with Wails binding calls |
| `frontend/src/components/audio-player/controls/player-controls.ts` | Edit | Replace `RequestPlay` event emission with binding call |
| `frontend/wailsjs/go/queue/Queue.js` | Auto-generated | New file from `wails generate` |
| `frontend/wailsjs/go/queue/Queue.d.ts` | Auto-generated | New file from `wails generate` |
| `frontend/wailsjs/go/models.ts` | Auto-generated | Updated with queue types |

## Files NOT Modified

| File | Reason |
|---|---|
| `backend/queue/emit.go` | Backend→frontend push events are kept as-is |
| `frontend/src/store/controllers/queue-controller.ts` | Proxies through store; no API change |
| `frontend/src/components/queue-panel/queue-panel.ts` | Uses controller; no API change |
| `frontend/src/components/track-list/track-list.ts` | Calls store methods; no API change |
| `frontend/src/components/cover-grid/cover-grid.ts` | Calls store methods; no API change |
| `frontend/src/components/genres-view/genres-view.ts` | Calls store methods; no API change |
| `frontend/src/components/artists-view/artists-view.ts` | Calls store methods; no API change |
| `frontend/src/components/playlist-view/playlist-view.ts` | Calls store methods; no API change |

## Risk Assessment

**Low risk:**
- The queue's public Go methods are already well-tested and have clear type signatures
- The store's public API doesn't change, so no component-level regressions
- The backend→frontend event system is untouched
- The pattern is proven by the playlist package

**Medium risk:**
- `SetPlayer(TrackLoader)` exposure in Wails bindings — Wails may not handle the interface parameter. If binding generation fails, we'll need to unexport `SetPlayer` and wire it via a package-level function or an exported setter that takes concrete types
- `RequestPlay` event has cross-cutting usage in `player-controls.ts` — needs careful auditing to avoid breaking play/pause

## Net Effect

- **~420 lines removed** from `handlers.go` (boilerplate)
- **~20 lines removed** from `events.go` and `events.ts` (15 event constants each)
- **~30 lines changed** in `queue-store.ts` (swap `EventsEmit` for binding calls)
- **~10 lines changed** in `app.go` (move construction, add to bindings)
- **~3 auto-generated files** created/updated by Wails
- Adding a new queue operation goes from a 4-file change to a 1-2 file change