From 312e0ae2ee8f11940b676f5d77fc233ae44c56c9 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 12:04:39 +0100
Subject: [PATCH 01/11] fix(mobile): guard against OOM crash on Load, fix stuck
 Preparing audio

Two bugs reported in #234 (via discussion #216):

1. Mobile browsers crash (WebKit tab kill) when loading long tracks because
   createAudioEngine decodes all stems into AudioBuffers in parallel. Added
   an estimateDecodedBytes check before creating the engine: tracks whose
   decoded PCM would exceed 200 MB (approx 4.5 min x 4 stems) now surface a
   clear error instead of silently crashing the tab.

2. After a crash-induced reload, loadLibrary auto-selected state.tracks[0]
   without calling openTrack(), leaving the player stuck on "Preparing audio"
   indefinitely. Removed the auto-select: the library is visible on load and
   the user can pick a track explicitly.

Closes #234
---
 static/mobile/app.js | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 3f22521f..6b7f0b75 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -4,7 +4,7 @@
 // (GET /api/jobs, /api/jobs/{id}, the Web Audio engine, mixdown export).
 // Extract is still mock pending the SSE/upload wiring (next step).
 import { fetchJobs, jobToCard } from "../js/shared/jobs.js";
-import { createAudioEngine } from "../js/audioEngine.js";
+import { createAudioEngine, estimateDecodedBytes } from "../js/audioEngine.js";
 
 // Per-stem label + color, keyed by the backend stem name. Unknown names fall
 // back to a rotating palette so non-standard models still render sensibly.
@@ -259,6 +259,16 @@ async function openTrack(card, { autoplay = false } = {}) {
     return;
   }
 
+  // Mobile browsers crash (OOM tab kill) when decoding all stems into AudioBuffers
+  // for long tracks. 200 MB covers ~4.5 min x 4 stems at 44.1 kHz / Float32.
+  const MOBILE_DECODE_LIMIT = 200e6;
+  const estimatedBytes = estimateDecodedBytes(detail.duration || 0, laneList.length);
+  if (estimatedBytes > MOBILE_DECODE_LIMIT) {
+    state.current.error = "Track too long to load on mobile. Try a shorter track (under ~5 minutes).";
+    render();
+    return;
+  }
+
   engine = createAudioEngine(laneList.map((l) => ({ name: l.name, url: l.url })), {
     onTime: onEngineTime,
     onEnded: () => { state.playing = false; render(); },
@@ -890,7 +900,6 @@ async function loadLibrary() {
     const jobs = await fetchJobs();
     state.tracks = jobs.map(jobToCard).sort((a, b) => b.createdAt - a.createdAt);
     state.libState = state.tracks.length ? "ready" : "empty";
-    if (!state.current && state.tracks.length) state.current = state.tracks[0];
   } catch (e) {
     console.warn("[mobile] failed to load library:", e);
     state.libState = "error";

From 03a1d8488bfe002e0cd1ec382b43900ed2130589 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 12:41:32 +0100
Subject: [PATCH 02/11] fix(mobile): replace OOM hard error with streaming
 engine fallback

Instead of blocking long tracks with an error, tracks that would exceed
200 MB of decoded PCM (approx 4.5 min x 4 stems) now fall back to a
streaming engine backed by <audio> elements and createMediaElementSource.
No PCM is held in RAM -- the browser streams on demand -- so OOM crashes
are avoided without restricting track length.

The streaming engine implements the same interface as createAudioEngine
(play/pause/seek/setGain/destroy/ready) so openTrack needs no structural
changes beyond selecting which engine to create.
---
 static/mobile/app.js | 115 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 105 insertions(+), 10 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 6b7f0b75..7503733d 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -46,6 +46,101 @@ function ensureAudioCtx() {
   return audioCtx;
 }
 
+// Streaming audio engine for tracks too large to decode into AudioBuffers.
+// Uses <audio> elements + createMediaElementSource instead of decodeAudioData,
+// so no PCM is held in RAM -- the browser streams on demand.
+function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {}) {
+  const AC = window.AudioContext || window.webkitAudioContext;
+  const ctx = context || new AC();
+  const ownsCtx = !context;
+  const master = ctx.createGain();
+  master.connect(ctx.destination);
+
+  const tracks = new Map();
+  let primaryAudio = null;
+  let duration = 0;
+  let playing = false;
+  let rafId = null;
+  let destroyed = false;
+
+  for (const s of stemDefs) {
+    if (!s?.url) continue;
+    const audio = new Audio();
+    audio.crossOrigin = "anonymous";
+    audio.preload = "auto";
+    audio.src = s.url;
+    const source = ctx.createMediaElementSource(audio);
+    const gain = ctx.createGain();
+    source.connect(gain);
+    gain.connect(master);
+    tracks.set(s.name, { audio, gain });
+    if (!primaryAudio) primaryAudio = audio;
+  }
+
+  const ready = new Promise((resolve) => {
+    if (!primaryAudio) { resolve(false); return; }
+    const done = () => { duration = isFinite(primaryAudio.duration) ? primaryAudio.duration : 0; resolve(tracks.size > 0); };
+    if (primaryAudio.readyState >= 3) { done(); return; }
+    primaryAudio.addEventListener("canplay", done, { once: true });
+    primaryAudio.addEventListener("error", () => resolve(false), { once: true });
+  });
+
+  function tick() {
+    if (!playing || !primaryAudio) return;
+    const t = primaryAudio.currentTime;
+    if (duration > 0 && t >= duration) {
+      playing = false;
+      if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
+      onEnded?.();
+      return;
+    }
+    onTime?.(t);
+    rafId = requestAnimationFrame(tick);
+  }
+
+  return {
+    ready,
+    play() {
+      if (playing || destroyed || !primaryAudio) return;
+      if (ctx.state === "suspended") ctx.resume().catch(() => {});
+      for (const { audio } of tracks.values()) audio.play().catch((e) => console.warn("[streaming] play:", e));
+      playing = true;
+      rafId = requestAnimationFrame(tick);
+    },
+    pause() {
+      if (!playing) return;
+      for (const { audio } of tracks.values()) audio.pause();
+      playing = false;
+      if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
+    },
+    seek(t) {
+      const clamped = Math.max(0, Math.min(t, duration || 0));
+      for (const { audio } of tracks.values()) audio.currentTime = clamped;
+      onTime?.(clamped);
+    },
+    setTime(t) { this.seek(t); },
+    isPlaying: () => playing,
+    getCurrentTime: () => (primaryAudio ? primaryAudio.currentTime : 0),
+    getDuration: () => duration,
+    setLoop: () => {},
+    setGain(name, v) {
+      const t = tracks.get(name);
+      if (t) t.gain.gain.setTargetAtTime(Math.max(0, v), ctx.currentTime, 0.01);
+    },
+    setMasterGain(v) { master.gain.setTargetAtTime(Math.max(0, v), ctx.currentTime, 0.01); },
+    getAnalyser: () => null,
+    getBuffers: () => new Map(),
+    destroy() {
+      destroyed = true;
+      this.pause();
+      for (const { audio } of tracks.values()) { audio.pause(); audio.src = ""; }
+      tracks.clear();
+      if (ownsCtx) ctx.close().catch(() => {});
+    },
+    audioContext: ctx,
+  };
+}
+
 const ICON = {
   chevron: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>',
   dots: '<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.6"/><circle cx="12" cy="12" r="1.6"/><circle cx="19" cy="12" r="1.6"/></svg>',
@@ -259,21 +354,21 @@ async function openTrack(card, { autoplay = false } = {}) {
     return;
   }
 
-  // Mobile browsers crash (OOM tab kill) when decoding all stems into AudioBuffers
-  // for long tracks. 200 MB covers ~4.5 min x 4 stems at 44.1 kHz / Float32.
+  // Tracks too large to decode into AudioBuffers (which would OOM mobile browsers)
+  // fall back to a streaming engine that uses <audio> elements instead. 200 MB
+  // covers ~4.5 min x 4 stems at 44.1 kHz / Float32.
   const MOBILE_DECODE_LIMIT = 200e6;
   const estimatedBytes = estimateDecodedBytes(detail.duration || 0, laneList.length);
-  if (estimatedBytes > MOBILE_DECODE_LIMIT) {
-    state.current.error = "Track too long to load on mobile. Try a shorter track (under ~5 minutes).";
-    render();
-    return;
-  }
-
-  engine = createAudioEngine(laneList.map((l) => ({ name: l.name, url: l.url })), {
+  const useStreaming = estimatedBytes > MOBILE_DECODE_LIMIT;
+  const engineOpts = {
     onTime: onEngineTime,
     onEnded: () => { state.playing = false; render(); },
     context: ensureAudioCtx(),
-  });
+  };
+  const stemList = laneList.map((l) => ({ name: l.name, url: l.url }));
+  engine = useStreaming
+    ? createStreamingAudioEngine(stemList, engineOpts)
+    : createAudioEngine(stemList, engineOpts);
   engineTrackId = card.id;
   render();
 

From 39a0be8b480381074c7dfcc96be74cc95e2af4f4 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 12:50:40 +0100
Subject: [PATCH 03/11] fix(mobile): play button state color, fix streaming
 engine seek desync

Play button: add data-playing attribute and CSS so the button turns green
when playing (gold when paused), making the state immediately obvious.

Seek desync: the streaming engine was setting currentTime on all <audio>
elements while they continued playing, causing each stem to arrive at the
new position at a slightly different time. Fix: pause all elements first,
seek all, then resume -- this guarantees all stems restart from the same
position simultaneously.
---
 static/mobile/app.js     | 8 +++++++-
 static/mobile/styles.css | 5 +++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 7503733d..ea774d95 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -115,7 +115,13 @@ function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {})
     },
     seek(t) {
       const clamped = Math.max(0, Math.min(t, duration || 0));
+      // Pause all elements before seeking so they all start from the same
+      // position — setting currentTime while playing causes each element to
+      // arrive at the new position at a slightly different moment (desync).
+      const wasPlaying = playing;
+      if (wasPlaying) for (const { audio } of tracks.values()) audio.pause();
       for (const { audio } of tracks.values()) audio.currentTime = clamped;
+      if (wasPlaying) for (const { audio } of tracks.values()) audio.play().catch(() => {});
       onTime?.(clamped);
     },
     setTime(t) { this.seek(t); },
@@ -553,7 +559,7 @@ function mixerScreen() {
       <div class="transport">
         <button class="t-ghost">${ICON.clock}.75x</button>
         <button class="t-step">${ICON.prev}</button>
-        <button class="t-play" data-action="play" ${canPlay ? "" : "disabled style=opacity:.45"}>${state.playing ? ICON.pause(26, "#1a1206") : ICON.play(28, "#1a1206")}</button>
+        <button class="t-play" data-action="play" data-playing="${state.playing}" ${canPlay ? "" : "disabled style=opacity:.45"}>${state.playing ? ICON.pause(26, "#1a1206") : ICON.play(28, "#1a1206")}</button>
         <button class="t-step">${ICON.next}</button>
         <button class="t-ghost" style="color:#85858d">${ICON.loop}</button>
       </div>
diff --git a/static/mobile/styles.css b/static/mobile/styles.css
index e9457dc1..8a3286cd 100644
--- a/static/mobile/styles.css
+++ b/static/mobile/styles.css
@@ -278,6 +278,11 @@ button {
   align-items: center;
   justify-content: center;
   cursor: pointer;
+  transition: background 0.15s, box-shadow 0.15s;
+}
+.t-play[data-playing="true"] {
+  background: linear-gradient(135deg, #3fcf6e 0%, #1fa84e 100%);
+  box-shadow: 0 12px 30px -6px rgba(63, 207, 110, 0.65);
 }
 
 .mx-prep {

From 093856b90c8f3bff60bb1f6ad78d6770119ce312 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:04:27 +0100
Subject: [PATCH 04/11] feat(mobile): wire prev/next track buttons, match
 desktop icon button style

Prev/next buttons were rendered but had no data-action and no handler --
clicking them did nothing. Now:

- prevTrack() / nextTrack() navigate state.tracks by index, autoplaying if
  a track was already playing when the button was pressed
- Buttons are disabled at the ends of the library (no prev on first track,
  no next on last track)
- .t-step CSS updated to match the desktop daw-iconbtn style: transparent
  background, rounded corners, hover highlight, scale(0.96) on active
---
 static/mobile/app.js     | 27 +++++++++++++++++++++++++--
 static/mobile/styles.css | 13 +++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index ea774d95..3af85b55 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -393,6 +393,20 @@ async function openTrack(card, { autoplay = false } = {}) {
   if (pendingPlay) { pendingPlay = false; engine.play(); state.playing = engine.isPlaying(); render(); }
 }
 
+function prevTrack() {
+  if (!state.tracks.length || !state.current) return;
+  const idx = state.tracks.findIndex((t) => t.id === state.current.id);
+  const target = state.tracks[idx - 1];
+  if (target) openTrack(target, { autoplay: state.playing });
+}
+
+function nextTrack() {
+  if (!state.tracks.length || !state.current) return;
+  const idx = state.tracks.findIndex((t) => t.id === state.current.id);
+  const target = state.tracks[idx + 1];
+  if (target) openTrack(target, { autoplay: state.playing });
+}
+
 function togglePlay() {
   if (!state.current) return;
   ensureAudioCtx(); // unlock audio within this gesture
@@ -538,6 +552,9 @@ function mixerScreen() {
   const ready = engineReady && engineTrackId === state.current?.id;
   const preparing = !!state.current && !state.current.loading && !state.current.error && !ready;
   const canPlay = ready;
+  const curIdx = state.current ? state.tracks.findIndex((t) => t.id === state.current.id) : -1;
+  const hasPrev = curIdx > 0;
+  const hasNext = curIdx >= 0 && curIdx < state.tracks.length - 1;
 
   return `<div class="screen scrl">
     <div class="pad">
@@ -558,9 +575,9 @@ function mixerScreen() {
       </div>
       <div class="transport">
         <button class="t-ghost">${ICON.clock}.75x</button>
-        <button class="t-step">${ICON.prev}</button>
+        <button class="t-step" data-action="prev" ${hasPrev ? "" : "disabled"}>${ICON.prev}</button>
         <button class="t-play" data-action="play" data-playing="${state.playing}" ${canPlay ? "" : "disabled style=opacity:.45"}>${state.playing ? ICON.pause(26, "#1a1206") : ICON.play(28, "#1a1206")}</button>
-        <button class="t-step">${ICON.next}</button>
+        <button class="t-step" data-action="next" ${hasNext ? "" : "disabled"}>${ICON.next}</button>
         <button class="t-ghost" style="color:#85858d">${ICON.loop}</button>
       </div>
       ${preparing ? '<div class="mx-prep">Preparing audio…</div>' : ""}
@@ -935,6 +952,12 @@ app.addEventListener("click", (e) => {
     case "mixview":
       state.mixerView = t.dataset.view;
       break;
+    case "prev":
+      prevTrack();
+      return;
+    case "next":
+      nextTrack();
+      return;
     case "play":
     case "play-mini":
       e.stopPropagation();
diff --git a/static/mobile/styles.css b/static/mobile/styles.css
index 8a3286cd..24f53f38 100644
--- a/static/mobile/styles.css
+++ b/static/mobile/styles.css
@@ -261,12 +261,21 @@ button {
   font-weight: 600;
 }
 .t-step {
-  background: none;
-  border: none;
+  width: 44px;
+  height: 44px;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: 9px;
   color: #d8d8dc;
   cursor: pointer;
   display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.12s, color 0.12s, transform 0.08s;
 }
+.t-step:hover { background: rgba(255,255,255,0.06); border-color: rgba(255,255,255,0.1); color: #fff; }
+.t-step:active { transform: scale(0.96); }
+.t-step:disabled { opacity: 0.3; cursor: default; }
 .t-play {
   width: 66px;
   height: 66px;

From b494650ac9c08856560858dca505eb13e571dc84 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:11:56 +0100
Subject: [PATCH 05/11] fix(mobile): proper seek sync and drift correction in
 streaming engine

Two-part fix for stems going out of sync after dragging the playhead:

1. Seek: pause all elements, set all currentTime, then wait one RAF frame
   for the browser to settle the seeks. Re-read the primary element's
   actual position and align all secondaries to it before calling play().
   This eliminates startup desync caused by elements buffering at different
   rates after a seek.

2. Drift correction: tick() now checks secondary elements every ~1 second
   (60 RAF frames) and snaps any that have drifted more than 50ms back to
   the primary's position. Catches any clock skew that accumulates during
   long playback.
---
 static/mobile/app.js | 47 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 9 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 3af85b55..3ed5a67f 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -85,6 +85,17 @@ function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {})
     primaryAudio.addEventListener("error", () => resolve(false), { once: true });
   });
 
+  // Snap all secondary elements back to the primary's position if they drift.
+  // 50 ms is the threshold -- inaudible as a correction, noticeable as drift.
+  function syncSecondaries(refTime) {
+    for (const { audio } of tracks.values()) {
+      if (audio !== primaryAudio && Math.abs(audio.currentTime - refTime) > 0.05) {
+        audio.currentTime = refTime;
+      }
+    }
+  }
+
+  let _tickCount = 0;
   function tick() {
     if (!playing || !primaryAudio) return;
     const t = primaryAudio.currentTime;
@@ -94,18 +105,24 @@ function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {})
       onEnded?.();
       return;
     }
+    // Correct accumulated drift roughly every second (60 frames at 60fps).
+    if (++_tickCount % 60 === 0) syncSecondaries(t);
     onTime?.(t);
     rafId = requestAnimationFrame(tick);
   }
 
+  function startAll() {
+    if (ctx.state === "suspended") ctx.resume().catch(() => {});
+    for (const { audio } of tracks.values()) audio.play().catch(() => {});
+    playing = true;
+    rafId = requestAnimationFrame(tick);
+  }
+
   return {
     ready,
     play() {
       if (playing || destroyed || !primaryAudio) return;
-      if (ctx.state === "suspended") ctx.resume().catch(() => {});
-      for (const { audio } of tracks.values()) audio.play().catch((e) => console.warn("[streaming] play:", e));
-      playing = true;
-      rafId = requestAnimationFrame(tick);
+      startAll();
     },
     pause() {
       if (!playing) return;
@@ -115,14 +132,26 @@ function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {})
     },
     seek(t) {
       const clamped = Math.max(0, Math.min(t, duration || 0));
-      // Pause all elements before seeking so they all start from the same
-      // position — setting currentTime while playing causes each element to
-      // arrive at the new position at a slightly different moment (desync).
       const wasPlaying = playing;
-      if (wasPlaying) for (const { audio } of tracks.values()) audio.pause();
+      // Pause everything first so no element advances while others are seeking.
+      if (wasPlaying) {
+        for (const { audio } of tracks.values()) audio.pause();
+        playing = false;
+        if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
+      }
       for (const { audio } of tracks.values()) audio.currentTime = clamped;
-      if (wasPlaying) for (const { audio } of tracks.values()) audio.play().catch(() => {});
       onTime?.(clamped);
+      if (wasPlaying) {
+        // Wait one frame for currentTime assignments to settle in the browser,
+        // then re-read the primary's actual position and align all secondaries
+        // to it before starting -- eliminates seek-induced startup desync.
+        requestAnimationFrame(() => {
+          if (destroyed) return;
+          const syncTo = primaryAudio.currentTime;
+          syncSecondaries(syncTo);
+          startAll();
+        });
+      }
     },
     setTime(t) { this.seek(t); },
     isPlaying: () => playing,

From f0a0bdd1be5cc3426548d36fec822dd5aa0cadb1 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:19:47 +0100
Subject: [PATCH 06/11] fix(mobile): redesign prev/next buttons to match
 standard mobile player style

Remove the rectangular box shape (border-radius:9px) that clashed with the
circular play button. Prev/next are now naked icon buttons with a circular
tap area -- the pattern used by Spotify, Apple Music, etc. Icons enlarged
from 26px to 32px to sit proportionally next to the 66px play button.
Press feedback is a scale+opacity pop instead of a subtle background fill.
---
 static/mobile/app.js     |  4 ++--
 static/mobile/styles.css | 20 ++++++++++----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 3ed5a67f..f858fd0d 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -180,8 +180,8 @@ const ICON = {
   chevron: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>',
   dots: '<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.6"/><circle cx="12" cy="12" r="1.6"/><circle cx="19" cy="12" r="1.6"/></svg>',
   clock: '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/></svg>',
-  prev: '<svg width="26" height="26" viewBox="0 0 24 24" fill="currentColor"><path d="M7 6v12M19 6l-9 6 9 6z"/></svg>',
-  next: '<svg width="26" height="26" viewBox="0 0 24 24" fill="currentColor"><path d="M17 6v12M5 6l9 6-9 6z"/></svg>',
+  prev: '<svg width="32" height="32" viewBox="0 0 24 24" fill="currentColor"><path d="M7 6v12M19 6l-9 6 9 6z"/></svg>',
+  next: '<svg width="32" height="32" viewBox="0 0 24 24" fill="currentColor"><path d="M17 6v12M5 6l9 6-9 6z"/></svg>',
   loop: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 2l4 4-4 4"/><path d="M3 11v-1a4 4 0 0 1 4-4h14"/><path d="M7 22l-4-4 4-4"/><path d="M21 13v1a4 4 0 0 1-4 4H3"/></svg>',
   play: (sz, fill) => `<svg width="${sz}" height="${sz}" viewBox="0 0 24 24" fill="${fill}"><path d="M8 5.5v13l11-6.5z"/></svg>`,
   pause: (sz, fill) => `<svg width="${sz}" height="${sz}" viewBox="0 0 24 24" fill="${fill}"><rect x="6" y="5" width="4" height="14" rx="1.3"/><rect x="14" y="5" width="4" height="14" rx="1.3"/></svg>`,
diff --git a/static/mobile/styles.css b/static/mobile/styles.css
index 24f53f38..5df78b8d 100644
--- a/static/mobile/styles.css
+++ b/static/mobile/styles.css
@@ -261,21 +261,21 @@ button {
   font-weight: 600;
 }
 .t-step {
-  width: 44px;
-  height: 44px;
-  background: transparent;
-  border: 1px solid transparent;
-  border-radius: 9px;
-  color: #d8d8dc;
+  width: 48px;
+  height: 48px;
+  background: none;
+  border: none;
+  border-radius: 50%;
+  color: #c8c8cc;
   cursor: pointer;
   display: flex;
   align-items: center;
   justify-content: center;
-  transition: background 0.12s, color 0.12s, transform 0.08s;
+  transition: color 0.12s, transform 0.1s, opacity 0.12s;
 }
-.t-step:hover { background: rgba(255,255,255,0.06); border-color: rgba(255,255,255,0.1); color: #fff; }
-.t-step:active { transform: scale(0.96); }
-.t-step:disabled { opacity: 0.3; cursor: default; }
+.t-step:hover { color: #fff; }
+.t-step:active { transform: scale(0.88); opacity: 0.7; }
+.t-step:disabled { opacity: 0.22; cursor: default; }
 .t-play {
   width: 66px;
   height: 66px;

From e3542007911f68e234415c12fbf08a04c5bec2fe Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:24:11 +0100
Subject: [PATCH 07/11] chore(mobile): remove unimplemented speed and loop stub
 buttons

---
 static/mobile/app.js     |  4 ----
 static/mobile/styles.css | 12 ------------
 2 files changed, 16 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index f858fd0d..52683296 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -179,10 +179,8 @@ function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {})
 const ICON = {
   chevron: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>',
   dots: '<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><circle cx="5" cy="12" r="1.6"/><circle cx="12" cy="12" r="1.6"/><circle cx="19" cy="12" r="1.6"/></svg>',
-  clock: '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/></svg>',
   prev: '<svg width="32" height="32" viewBox="0 0 24 24" fill="currentColor"><path d="M7 6v12M19 6l-9 6 9 6z"/></svg>',
   next: '<svg width="32" height="32" viewBox="0 0 24 24" fill="currentColor"><path d="M17 6v12M5 6l9 6-9 6z"/></svg>',
-  loop: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 2l4 4-4 4"/><path d="M3 11v-1a4 4 0 0 1 4-4h14"/><path d="M7 22l-4-4 4-4"/><path d="M21 13v1a4 4 0 0 1-4 4H3"/></svg>',
   play: (sz, fill) => `<svg width="${sz}" height="${sz}" viewBox="0 0 24 24" fill="${fill}"><path d="M8 5.5v13l11-6.5z"/></svg>`,
   pause: (sz, fill) => `<svg width="${sz}" height="${sz}" viewBox="0 0 24 24" fill="${fill}"><rect x="6" y="5" width="4" height="14" rx="1.3"/><rect x="14" y="5" width="4" height="14" rx="1.3"/></svg>`,
   download: '<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v12"/><path d="M8 11l4 4 4-4"/><path d="M4 21h16"/></svg>',
@@ -603,11 +601,9 @@ function mixerScreen() {
         <div class="wave-times"><span class="cur">${fmt(state.progress * dur)}</span><span class="dur">${fmt(dur)}</span></div>
       </div>
       <div class="transport">
-        <button class="t-ghost">${ICON.clock}.75x</button>
         <button class="t-step" data-action="prev" ${hasPrev ? "" : "disabled"}>${ICON.prev}</button>
         <button class="t-play" data-action="play" data-playing="${state.playing}" ${canPlay ? "" : "disabled style=opacity:.45"}>${state.playing ? ICON.pause(26, "#1a1206") : ICON.play(28, "#1a1206")}</button>
         <button class="t-step" data-action="next" ${hasNext ? "" : "disabled"}>${ICON.next}</button>
-        <button class="t-ghost" style="color:#85858d">${ICON.loop}</button>
       </div>
       ${preparing ? '<div class="mx-prep">Preparing audio…</div>' : ""}
       <div class="segmented">
diff --git a/static/mobile/styles.css b/static/mobile/styles.css
index 5df78b8d..4e416954 100644
--- a/static/mobile/styles.css
+++ b/static/mobile/styles.css
@@ -248,18 +248,6 @@ button {
   gap: 22px;
   margin-top: 8px;
 }
-.t-ghost {
-  background: none;
-  border: none;
-  color: var(--muted);
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  font-family: var(--mono);
-  font-size: 12px;
-  font-weight: 600;
-}
 .t-step {
   width: 48px;
   height: 48px;

From ad4a628eceddc455474b8f9087801852bd6607f7 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:28:35 +0100
Subject: [PATCH 08/11] fix(mobile): drop streaming engine, use buffer engine
 for all tracks

The streaming engine (<audio> elements via createMediaElementSource) caused
constant choppy audio -- the exact same HTTP/1.1 connection-cap underrun
issue that audioEngine.js was built to solve in the first place.

Replace with the buffer engine for all tracks. Raise the decoded-PCM limit
from 200 MB to 600 MB, which covers ~14 min x 4 stems at 44.1 kHz/Float32
-- well within the per-tab budget of any post-2019 phone. Tracks over that
threshold get a clear error rather than glitchy playback.
---
 static/mobile/app.js | 152 ++++---------------------------------------
 1 file changed, 13 insertions(+), 139 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 52683296..175829ff 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -5,7 +5,6 @@
 // Extract is still mock pending the SSE/upload wiring (next step).
 import { fetchJobs, jobToCard } from "../js/shared/jobs.js";
 import { createAudioEngine, estimateDecodedBytes } from "../js/audioEngine.js";
-
 // Per-stem label + color, keyed by the backend stem name. Unknown names fall
 // back to a rotating palette so non-standard models still render sensibly.
 const STEM_META = {
@@ -46,135 +45,6 @@ function ensureAudioCtx() {
   return audioCtx;
 }
 
-// Streaming audio engine for tracks too large to decode into AudioBuffers.
-// Uses <audio> elements + createMediaElementSource instead of decodeAudioData,
-// so no PCM is held in RAM -- the browser streams on demand.
-function createStreamingAudioEngine(stemDefs, { onTime, onEnded, context } = {}) {
-  const AC = window.AudioContext || window.webkitAudioContext;
-  const ctx = context || new AC();
-  const ownsCtx = !context;
-  const master = ctx.createGain();
-  master.connect(ctx.destination);
-
-  const tracks = new Map();
-  let primaryAudio = null;
-  let duration = 0;
-  let playing = false;
-  let rafId = null;
-  let destroyed = false;
-
-  for (const s of stemDefs) {
-    if (!s?.url) continue;
-    const audio = new Audio();
-    audio.crossOrigin = "anonymous";
-    audio.preload = "auto";
-    audio.src = s.url;
-    const source = ctx.createMediaElementSource(audio);
-    const gain = ctx.createGain();
-    source.connect(gain);
-    gain.connect(master);
-    tracks.set(s.name, { audio, gain });
-    if (!primaryAudio) primaryAudio = audio;
-  }
-
-  const ready = new Promise((resolve) => {
-    if (!primaryAudio) { resolve(false); return; }
-    const done = () => { duration = isFinite(primaryAudio.duration) ? primaryAudio.duration : 0; resolve(tracks.size > 0); };
-    if (primaryAudio.readyState >= 3) { done(); return; }
-    primaryAudio.addEventListener("canplay", done, { once: true });
-    primaryAudio.addEventListener("error", () => resolve(false), { once: true });
-  });
-
-  // Snap all secondary elements back to the primary's position if they drift.
-  // 50 ms is the threshold -- inaudible as a correction, noticeable as drift.
-  function syncSecondaries(refTime) {
-    for (const { audio } of tracks.values()) {
-      if (audio !== primaryAudio && Math.abs(audio.currentTime - refTime) > 0.05) {
-        audio.currentTime = refTime;
-      }
-    }
-  }
-
-  let _tickCount = 0;
-  function tick() {
-    if (!playing || !primaryAudio) return;
-    const t = primaryAudio.currentTime;
-    if (duration > 0 && t >= duration) {
-      playing = false;
-      if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
-      onEnded?.();
-      return;
-    }
-    // Correct accumulated drift roughly every second (60 frames at 60fps).
-    if (++_tickCount % 60 === 0) syncSecondaries(t);
-    onTime?.(t);
-    rafId = requestAnimationFrame(tick);
-  }
-
-  function startAll() {
-    if (ctx.state === "suspended") ctx.resume().catch(() => {});
-    for (const { audio } of tracks.values()) audio.play().catch(() => {});
-    playing = true;
-    rafId = requestAnimationFrame(tick);
-  }
-
-  return {
-    ready,
-    play() {
-      if (playing || destroyed || !primaryAudio) return;
-      startAll();
-    },
-    pause() {
-      if (!playing) return;
-      for (const { audio } of tracks.values()) audio.pause();
-      playing = false;
-      if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
-    },
-    seek(t) {
-      const clamped = Math.max(0, Math.min(t, duration || 0));
-      const wasPlaying = playing;
-      // Pause everything first so no element advances while others are seeking.
-      if (wasPlaying) {
-        for (const { audio } of tracks.values()) audio.pause();
-        playing = false;
-        if (rafId) { cancelAnimationFrame(rafId); rafId = null; }
-      }
-      for (const { audio } of tracks.values()) audio.currentTime = clamped;
-      onTime?.(clamped);
-      if (wasPlaying) {
-        // Wait one frame for currentTime assignments to settle in the browser,
-        // then re-read the primary's actual position and align all secondaries
-        // to it before starting -- eliminates seek-induced startup desync.
-        requestAnimationFrame(() => {
-          if (destroyed) return;
-          const syncTo = primaryAudio.currentTime;
-          syncSecondaries(syncTo);
-          startAll();
-        });
-      }
-    },
-    setTime(t) { this.seek(t); },
-    isPlaying: () => playing,
-    getCurrentTime: () => (primaryAudio ? primaryAudio.currentTime : 0),
-    getDuration: () => duration,
-    setLoop: () => {},
-    setGain(name, v) {
-      const t = tracks.get(name);
-      if (t) t.gain.gain.setTargetAtTime(Math.max(0, v), ctx.currentTime, 0.01);
-    },
-    setMasterGain(v) { master.gain.setTargetAtTime(Math.max(0, v), ctx.currentTime, 0.01); },
-    getAnalyser: () => null,
-    getBuffers: () => new Map(),
-    destroy() {
-      destroyed = true;
-      this.pause();
-      for (const { audio } of tracks.values()) { audio.pause(); audio.src = ""; }
-      tracks.clear();
-      if (ownsCtx) ctx.close().catch(() => {});
-    },
-    audioContext: ctx,
-  };
-}
 
 const ICON = {
   chevron: '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9l6 6 6-6"/></svg>',
@@ -387,21 +257,25 @@ async function openTrack(card, { autoplay = false } = {}) {
     return;
   }
 
-  // Tracks too large to decode into AudioBuffers (which would OOM mobile browsers)
-  // fall back to a streaming engine that uses <audio> elements instead. 200 MB
-  // covers ~4.5 min x 4 stems at 44.1 kHz / Float32.
-  const MOBILE_DECODE_LIMIT = 200e6;
+  // Streaming <audio> elements cause underruns on mobile Safari (HTTP/1.1
+  // connection cap + small buffers). The buffer engine decodes all stems into
+  // AudioBuffers first, giving glitch-free playback at the cost of RAM.
+  // 600 MB covers ~14 min x 4 stems at 44.1 kHz / Float32, which is well
+  // within the per-tab budget of any post-2019 phone. Tracks that exceed this
+  // will show an error rather than play with constant chopping.
+  const MOBILE_DECODE_LIMIT = 600e6;
   const estimatedBytes = estimateDecodedBytes(detail.duration || 0, laneList.length);
-  const useStreaming = estimatedBytes > MOBILE_DECODE_LIMIT;
+  if (estimatedBytes > MOBILE_DECODE_LIMIT) {
+    state.current.error = "Track too long to load on mobile (over ~14 minutes). Try a shorter track.";
+    render();
+    return;
+  }
   const engineOpts = {
     onTime: onEngineTime,
     onEnded: () => { state.playing = false; render(); },
     context: ensureAudioCtx(),
   };
-  const stemList = laneList.map((l) => ({ name: l.name, url: l.url }));
-  engine = useStreaming
-    ? createStreamingAudioEngine(stemList, engineOpts)
-    : createAudioEngine(stemList, engineOpts);
+  engine = createAudioEngine(laneList.map((l) => ({ name: l.name, url: l.url })), engineOpts);
   engineTrackId = card.id;
   render();
 

From ec6ca4db89b95935c662a15daa4d0a33fc686b38 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 15:09:36 +0100
Subject: [PATCH 09/11] fix(mobile): correct OOM limit comment and dynamic
 error message

600 MB / (stems * 2ch * 44100Hz * 4 bytes) = ~7 min for 4 stems, not 14.
The 14-minute figure was only accurate for a 2-stem track. Error message
now computes and shows the real cap based on the actual stem count.
---
 static/mobile/app.js | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/static/mobile/app.js b/static/mobile/app.js
index 175829ff..75ddf3ab 100644
--- a/static/mobile/app.js
+++ b/static/mobile/app.js
@@ -260,13 +260,14 @@ async function openTrack(card, { autoplay = false } = {}) {
   // Streaming <audio> elements cause underruns on mobile Safari (HTTP/1.1
   // connection cap + small buffers). The buffer engine decodes all stems into
   // AudioBuffers first, giving glitch-free playback at the cost of RAM.
-  // 600 MB covers ~14 min x 4 stems at 44.1 kHz / Float32, which is well
-  // within the per-tab budget of any post-2019 phone. Tracks that exceed this
-  // will show an error rather than play with constant chopping.
+  // 600 MB at Float32 / 44.1 kHz / stereo = ~425 s per stem-slot, so the
+  // practical cap is ~7 min for 4 stems or ~14 min for 2 stems. Tracks that
+  // exceed this will show an error rather than play with constant chopping.
   const MOBILE_DECODE_LIMIT = 600e6;
   const estimatedBytes = estimateDecodedBytes(detail.duration || 0, laneList.length);
   if (estimatedBytes > MOBILE_DECODE_LIMIT) {
-    state.current.error = "Track too long to load on mobile (over ~14 minutes). Try a shorter track.";
+    const maxMin = Math.round(MOBILE_DECODE_LIMIT / (laneList.length * 2 * 44100 * 4) / 60);
+    state.current.error = `Track too long to load on mobile (limit is ~${maxMin} min for ${laneList.length} stems). Try a shorter track.`;
     render();
     return;
   }

From 7e38ea7828b13d2d18d77e97c35314c1fdeafc15 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 15:19:43 +0100
Subject: [PATCH 10/11] fix(dev): bind to 0.0.0.0 by default to allow LAN
 access for mobile testing

---
 run.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/run.sh b/run.sh
index 2f79507b..9eb1b0a1 100755
--- a/run.sh
+++ b/run.sh
@@ -5,7 +5,7 @@ set -euo pipefail
 
 cd "$(dirname "$0")"
 
-HOST="${HOST:-127.0.0.1}"
+HOST="${HOST:-0.0.0.0}"
 PORT="${PORT:-8000}"
 RELOAD="${RELOAD:-0}"
 FOREGROUND="${FOREGROUND:-0}"

From dcf31669a93ee8f4ba4a35950649f0b24bab9d1f Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 29 Jun 2026 15:21:38 +0100
Subject: [PATCH 11/11] fix(dev): align run.sh default port to 8080 to match
 settings and desktop

---
 run.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/run.sh b/run.sh
index 9eb1b0a1..26e00389 100755
--- a/run.sh
+++ b/run.sh
@@ -6,7 +6,7 @@ set -euo pipefail
 cd "$(dirname "$0")"
 
 HOST="${HOST:-0.0.0.0}"
-PORT="${PORT:-8000}"
+PORT="${PORT:-8080}"
 RELOAD="${RELOAD:-0}"
 FOREGROUND="${FOREGROUND:-0}"
 PID_FILE=".run/uvicorn.pid"