fix: stem mixer on iOS — install play/pause shims via defineProperty

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the Stems Toggle plugin are documented here.
 
+## [0.7.1] — iOS stem playback fix
+
+### Fixed
+
+- **Stem mixer now works on iOS (iPhone/iPad).** The `#audio` takeover shims for
+  `play` / `pause` were installed with a direct `core.play = fn` assignment, which
+  iOS WebKit rejects with "Attempted to assign to readonly property" (those methods
+  are non-writable there, and the plugin runs as a strict-mode ES module). The
+  throw left the critical-shim gate `shimsUsable` false, so `onSongReady()` aborted
+  the sloppak takeover and handed playback back to the native `<audio>` element —
+  which plays only `stems[0]`. On-device this looked like "only one stem plays and
+  the mixer sliders do nothing." `play`/`pause` are now installed with
+  `Object.defineProperty` (an own property on the instance), matching the
+  currentTime/paused/duration shims and working on both WebKit and Chromium.
+  Desktop/Electron was unaffected. Discovered while running the plugin through the
+  native iOS client (`feedback-client-app`).
+
 ## [0.7.0] — Pristine full mix at unity
 
 ### Added

plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "stems",
   "name": "Stems Toggle",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "settings": {
     "html": "settings.html",

screen.js

@@ -706,26 +706,44 @@
                 });
             } catch (e) { console.warn('[stems] duration shim install failed:', e); }
         }
+        // play/pause are installed with Object.defineProperty rather than a plain
+        // `core.play = fn` assignment. iOS WebKit exposes HTMLMediaElement.play /
+        // .pause as non-writable, so the assignment throws "Attempted to assign to
+        // readonly property" in this plugin's strict-mode (ES module) context —
+        // which left playOk/pauseOk false, so onSongReady() refused the takeover
+        // and the browser played only stems[0] (single stem, dead mixer sliders).
+        // Chromium/Electron silently allow the assignment, so this only bit on iOS.
+        // Defining an OWN property on the instance sidesteps the prototype's
+        // writability and works on both engines — matching the currentTime/paused/
+        // duration shims above, which already use defineProperty.
         try {
-            core.play = function () {
-                if (sloppakActive) {
-                    transportPlay();
-                    // Resolve immediately if playback actually started; otherwise
-                    // return a promise that settles when the deferred play starts
-                    // (or is cancelled), matching HTMLMediaElement.play()'s
-                    // "resolves once playback begins" contract.
-                    if (transport.playing || !pendingPlay) return Promise.resolve();
-                    return new Promise((resolve) => { pendingPlayResolvers.push(resolve); });
-                }
-                return coreNativePlay();
-            };
+            Object.defineProperty(core, 'play', {
+                configurable: true,
+                writable: true,
+                value: function () {
+                    if (sloppakActive) {
+                        transportPlay();
+                        // Resolve immediately if playback actually started; otherwise
+                        // return a promise that settles when the deferred play starts
+                        // (or is cancelled), matching HTMLMediaElement.play()'s
+                        // "resolves once playback begins" contract.
+                        if (transport.playing || !pendingPlay) return Promise.resolve();
+                        return new Promise((resolve) => { pendingPlayResolvers.push(resolve); });
+                    }
+                    return coreNativePlay();
+                },
+            });
             playOk = true;
         } catch (e) { console.warn('[stems] play shim install failed:', e); }
         try {
-            core.pause = function () {
-                if (sloppakActive) { transportPause(); return; }
-                return coreNativePause();
-            };
+            Object.defineProperty(core, 'pause', {
+                configurable: true,
+                writable: true,
+                value: function () {
+                    if (sloppakActive) { transportPause(); return; }
+                    return coreNativePause();
+                },
+            });
             pauseOk = true;
         } catch (e) { console.warn('[stems] pause shim install failed:', e); }
         // The slopsmith speed slider writes #audio.playbackRate; mirror it

tests/ios-play-pause-shim.test.mjs

@@ -0,0 +1,61 @@
+// Regression test for the iOS WebKit #audio play/pause shim install.
+//
+// iOS WebKit exposes HTMLMediaElement.play / .pause as NON-writable properties,
+// so a plain `core.play = fn` assignment throws "Attempted to assign to readonly
+// property" in this plugin's strict-mode (ES module) execution context. That
+// left playOk/pauseOk false, so onSongReady() refused the sloppak takeover and
+// the browser played only stems[0] — the reported "only one stem, mixer sliders
+// do nothing" on iPhone/iPad. Chromium/Electron silently allow the assignment,
+// which is why it only bit on iOS. installAudioShims() must install play/pause
+// with Object.defineProperty (an OWN property on the instance), which works even
+// when the inherited method is non-writable.
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const src = fs.readFileSync(path.join(__dirname, '..', 'screen.js'), 'utf8');
+
+test('play/pause shims use defineProperty, not the assignment that throws on iOS', () => {
+    assert.ok(
+        !/\bcore\.play\s*=\s*function/.test(src),
+        'core.play must not be installed via direct assignment (throws on iOS WebKit)'
+    );
+    assert.ok(
+        !/\bcore\.pause\s*=\s*function/.test(src),
+        'core.pause must not be installed via direct assignment (throws on iOS WebKit)'
+    );
+    assert.match(src, /Object\.defineProperty\(core, 'play'/, 'core.play must use Object.defineProperty');
+    assert.match(src, /Object\.defineProperty\(core, 'pause'/, 'core.pause must use Object.defineProperty');
+});
+
+test('defineProperty overrides a non-writable method where assignment throws (iOS WebKit model)', () => {
+    // Model an iOS-style media element: play/pause are non-writable + configurable,
+    // exactly the shape that makes `el.play = fn` throw but defineProperty succeed.
+    const makeIOSElement = () => {
+        const el = {};
+        for (const name of ['play', 'pause']) {
+            Object.defineProperty(el, name, {
+                configurable: true,
+                writable: false,
+                value: () => `native ${name}`,
+            });
+        }
+        return el;
+    };
+
+    // The OLD pattern throws (this file is a module, so already strict mode).
+    const a = makeIOSElement();
+    assert.throws(() => { a.play = () => 'shim'; }, /read.?only|assign/i);
+
+    // The NEW pattern succeeds and the override actually takes effect.
+    const b = makeIOSElement();
+    assert.doesNotThrow(() => {
+        Object.defineProperty(b, 'play', { configurable: true, writable: true, value: () => 'shim play' });
+        Object.defineProperty(b, 'pause', { configurable: true, writable: true, value: () => 'shim pause' });
+    });
+    assert.equal(b.play(), 'shim play');
+    assert.equal(b.pause(), 'shim pause');
+});