The same rules lived in two or three places across web, mobile, and Convex, and some copies had already drifted apart. The Convex queue mutations carried a comment saying they "mirror" the client rules, and codec and bitrate selection was written three times with different defaults.
What moved into @otunes/convex
Queue rules: the Convex playback mutations now run the pure functions in client/playback-queue.ts through one updateQueue helper.
Stream plan:playbackStreamPlan now also returns the source file and kbps. The play route and server-hls.ts use it in place of their own selection code. parsePlaybackQuality reads the quality param.
Stream URLs:songPlayPath / songHlsPlaylistPath in playback-stream.ts replace web's song-play-url.ts and mobile's two builders.
PlaybackQuality: the 4 local web copies and the mobile copy now import the shared type.
Share links:client/media-links.ts holds mediaShareUrl and shouldShowShare, which were also duplicated.
Small helpers:userIdFromToken (client/auth-token.ts), song search (client/song-search.ts), and format badge path data (client/audio-format-marks.ts). Each platform still draws its own SVG.
Favorites:client/favorites.ts holds one set of optimistic updates. Web now gets stable mutation identities like mobile already had; before, it rebuilt .withOptimisticUpdate() on every render.
Atmos (mobile):atmosEnabled(user) replaces the 5 inline checks. The second check in urls.ts is gone because callers already pass plan.preferAtmos.
Where copies disagreed
Adding to the queue reset the current song's progress on the server. Convex addToQueueNext / addToQueueLast went through a helper that set currentSongProgress to 0. The client keeps the position, so the shared client rule wins. Neither app calls these mutations today (both sync through syncPlaybackState), so users won't see a change.
Missing quality on the play route. The route served the original file, while playbackStreamPlan defaults to medium. Both apps always send a quality, so the route keeps its old default (?? "lossless"). HLS keeps its medium default. The "falls back to 128 vs 0" difference was HLS needing a target bitrate for lossless quality; it now asks for medium explicitly.
Playlist search. Web trimmed the query and mobile relied on its debounce hook to trim. The shared filter trims.
Older-server album format fallback
Removed on both apps. Album pages read album.hasLossless / album.hasAtmos directly and no longer fetch every song when the flags are missing. Servers from before #61 (2026-11-03) will no longer show the Lossless and Atmos badges on mobile; that is accepted.
Cache hooks stay per app
use-cached-query and the useSong / useSongs hooks stay in each app. React only lives in the apps (web is on 19.3.1, mobile on 19.3.0), and @otunes/convex has no React dependency. Importing hooks from the package would resolve a second React copy. The cache logic underneath was already shared. This PR moves the remaining snapshot logic into client/song-cache.ts and gives web mobile's useSong, which only re-renders when that one song changes.
Testing
Convex typecheck, web typecheck and lint, mobile typecheck all pass.
Built this branch's Docker image and ran it in isolation against a generated 6-track lossless + AAC library. Checked in headless Chrome:
Album play: the Lossless badge renders.
Every quality through the play route behaves as on main: none, bogus, and lossless give the original FLAC; low and medium transcode; high streams the AAC file directly. HLS playlists generate.
Shuffle album, next, previous, shuffle off and on, and repeat all work.
Favorites toggle optimistically.
The share link is correct.
Playlist search works.
Made by Claude Opus 5.5 (claude-opus-5-5) in Claude Code, via T3 Code.
The same rules lived in two or three places across web, mobile, and Convex, and some copies had already drifted apart. The Convex queue mutations carried a comment saying they "mirror" the client rules, and codec and bitrate selection was written three times with different defaults.
## What moved into `@otunes/convex`
- **Queue rules:** the Convex playback mutations now run the pure functions in `client/playback-queue.ts` through one `updateQueue` helper.
- **Stream plan:** `playbackStreamPlan` now also returns the `source` file and `kbps`. The play route and `server-hls.ts` use it in place of their own selection code. `parsePlaybackQuality` reads the `quality` param.
- **Stream URLs:** `songPlayPath` / `songHlsPlaylistPath` in `playback-stream.ts` replace web's `song-play-url.ts` and mobile's two builders.
- **`PlaybackQuality`:** the 4 local web copies and the mobile copy now import the shared type.
- **Share links:** `client/media-links.ts` holds `mediaShareUrl` and `shouldShowShare`, which were also duplicated.
- **Small helpers:** `userIdFromToken` (`client/auth-token.ts`), song search (`client/song-search.ts`), and format badge path data (`client/audio-format-marks.ts`). Each platform still draws its own SVG.
- **Favorites:** `client/favorites.ts` holds one set of optimistic updates. Web now gets stable mutation identities like mobile already had; before, it rebuilt `.withOptimisticUpdate()` on every render.
- **Atmos (mobile):** `atmosEnabled(user)` replaces the 5 inline checks. The second check in `urls.ts` is gone because callers already pass `plan.preferAtmos`.
## Where copies disagreed
- **Adding to the queue reset the current song's progress on the server.** Convex `addToQueueNext` / `addToQueueLast` went through a helper that set `currentSongProgress` to 0. The client keeps the position, so the shared client rule wins. Neither app calls these mutations today (both sync through `syncPlaybackState`), so users won't see a change.
- **Missing `quality` on the play route.** The route served the original file, while `playbackStreamPlan` defaults to medium. Both apps always send a quality, so the route keeps its old default (`?? "lossless"`). HLS keeps its medium default. The "falls back to 128 vs 0" difference was HLS needing a target bitrate for lossless quality; it now asks for medium explicitly.
- **Playlist search.** Web trimmed the query and mobile relied on its debounce hook to trim. The shared filter trims.
## Older-server album format fallback
Removed on both apps. Album pages read `album.hasLossless` / `album.hasAtmos` directly and no longer fetch every song when the flags are missing. Servers from before #61 (2026-11-03) will no longer show the Lossless and Atmos badges on mobile; that is accepted.
## Cache hooks stay per app
`use-cached-query` and the `useSong` / `useSongs` hooks stay in each app. React only lives in the apps (web is on 19.3.1, mobile on 19.3.0), and `@otunes/convex` has no React dependency. Importing hooks from the package would resolve a second React copy. The cache logic underneath was already shared. This PR moves the remaining snapshot logic into `client/song-cache.ts` and gives web mobile's `useSong`, which only re-renders when that one song changes.
## Testing
- Convex typecheck, web typecheck and lint, mobile typecheck all pass.
- Built this branch's Docker image and ran it in isolation against a generated 6-track lossless + AAC library. Checked in headless Chrome:
- Album play: the Lossless badge renders.
- Every quality through the play route behaves as on main: none, `bogus`, and `lossless` give the original FLAC; low and medium transcode; high streams the AAC file directly. HLS playlists generate.
- Shuffle album, next, previous, shuffle off and on, and repeat all work.
- Favorites toggle optimistically.
- The share link is correct.
- Playlist search works.
---
Made by Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, via T3 Code.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Move queue rules, stream planning, stream URLs, share links, song search,
favorites optimistic updates, token parsing, and format badge marks into
@otunes/convex so each rule has one implementation.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
The same rules lived in two or three places across web, mobile, and Convex, and some copies had already drifted apart. The Convex queue mutations carried a comment saying they "mirror" the client rules, and codec and bitrate selection was written three times with different defaults.
What moved into
@otunes/convexclient/playback-queue.tsthrough oneupdateQueuehelper.playbackStreamPlannow also returns thesourcefile andkbps. The play route andserver-hls.tsuse it in place of their own selection code.parsePlaybackQualityreads thequalityparam.songPlayPath/songHlsPlaylistPathinplayback-stream.tsreplace web'ssong-play-url.tsand mobile's two builders.PlaybackQuality: the 4 local web copies and the mobile copy now import the shared type.client/media-links.tsholdsmediaShareUrlandshouldShowShare, which were also duplicated.userIdFromToken(client/auth-token.ts), song search (client/song-search.ts), and format badge path data (client/audio-format-marks.ts). Each platform still draws its own SVG.client/favorites.tsholds one set of optimistic updates. Web now gets stable mutation identities like mobile already had; before, it rebuilt.withOptimisticUpdate()on every render.atmosEnabled(user)replaces the 5 inline checks. The second check inurls.tsis gone because callers already passplan.preferAtmos.Where copies disagreed
addToQueueNext/addToQueueLastwent through a helper that setcurrentSongProgressto 0. The client keeps the position, so the shared client rule wins. Neither app calls these mutations today (both sync throughsyncPlaybackState), so users won't see a change.qualityon the play route. The route served the original file, whileplaybackStreamPlandefaults to medium. Both apps always send a quality, so the route keeps its old default (?? "lossless"). HLS keeps its medium default. The "falls back to 128 vs 0" difference was HLS needing a target bitrate for lossless quality; it now asks for medium explicitly.Older-server album format fallback
Removed on both apps. Album pages read
album.hasLossless/album.hasAtmosdirectly and no longer fetch every song when the flags are missing. Servers from before #61 (2026-11-03) will no longer show the Lossless and Atmos badges on mobile; that is accepted.Cache hooks stay per app
use-cached-queryand theuseSong/useSongshooks stay in each app. React only lives in the apps (web is on 19.3.1, mobile on 19.3.0), and@otunes/convexhas no React dependency. Importing hooks from the package would resolve a second React copy. The cache logic underneath was already shared. This PR moves the remaining snapshot logic intoclient/song-cache.tsand gives web mobile'suseSong, which only re-renders when that one song changes.Testing
bogus, andlosslessgive the original FLAC; low and medium transcode; high streams the AAC file directly. HLS playlists generate.Made by Claude Opus 5.5 (
claude-opus-5-5) in Claude Code, via T3 Code.🤖 Generated with Claude Code