@needle-tools/engine 5.1.0-alpha.8 → 5.1.0-beta

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -1,6 +1,6 @@
 import { showBalloonMessage } from "../../debug/debug.js";
 import type { Context } from "../../engine_context.js";
-import { bLW, $bxGE, Telemetry } from "../../engine_license.js";
+import { $fwGZrGe, $BWnhWzrW, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
 import { HTMLElementBase } from "../../engine_ssr.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
@@ -778,8 +778,8 @@ export class NeedleMenuElement extends HTMLElementBase {
         try {
             // if the user has a license then we CAN hide the needle logo
             // calling this method immediately will cause an issue with vite bundling tho
-            window.requestAnimationFrame(() => $bxGE(res => {
-                if (res == true && bLW() && !debugNonCommercial) {
+            window.requestAnimationFrame(() => $BWnhWzrW(res => {
+                if (res == true && $fwGZrGe() && !debugNonCommercial) {
                     let visible = this._userRequestedLogoVisible;
                     if (visible === undefined) visible = false;
                     this.___onSetLogoVisible(visible);
@@ -830,7 +830,7 @@ export class NeedleMenuElement extends HTMLElementBase {
                 // ensure the menu is not hidden or removed
                 const requiredParent = this?.parentNode;
                 if (this.style.display != "flex" || this.style.visibility != "visible" || this.style.opacity != "1" || requiredParent != this._domElement?.shadowRoot) {
-                    if (!bLW()) {
+                    if (!$fwGZrGe()) {
                         const change = changeEventCounter++;
                         // if a user doesn't have a local pro license *but* for development the menu is hidden then we show a warning
                         if (isLocalNetwork() && this._userRequestedMenuVisible === false) {
@@ -918,7 +918,7 @@ export class NeedleMenuElement extends HTMLElementBase {
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
         if (!visible) {
-            if (!bLW() || debugNonCommercial) {
+            if (!$fwGZrGe() || debugNonCommercial) {
                 console.warn("[Needle Engine] You need a PRO license to hide the Needle Engine logo in production.");
                 const localNetwork = isLocalNetwork()
                 if (!localNetwork) return;

package/src/engine/webcomponents/needle-engine.loading.ts

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { bLW, _$QyV, _MHgSj } from "../engine_license.js";
+import { $fwGZrGe, _XtEQ, ICD } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { LoadingProgressArgs } from "../engine_setup.js";
 import { getParam } from "../engine_utils.js";
@@ -205,7 +205,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
 
-        const hasLicense = _$QyV();
+        const hasLicense = _XtEQ();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
             this._loadingElement.style.width = "100%";
@@ -373,7 +373,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
 
     // private async handleRuntimeLicense(loadingElement: HTMLElement) {
     //     // First check if we have a commercial license
-    //     let commercialLicense = bLW();
+    //     let commercialLicense = $fwGZrGe();
     //     // if it's the case then we don't need to perform a runtime check
     //     if (commercialLicense) return;
 
@@ -393,10 +393,10 @@ export class EngineLoadingView implements ILoadingViewHandler {
     //     loadingElement.appendChild(nonCommercialContainer);
 
     //     // Use the runtime license check
-    //     if (!isDevEnvironment() && _MHgSj) {
+    //     if (!isDevEnvironment() && ICD) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await _MHgSj;
-    //         commercialLicense = bLW();
+    //         await ICD;
+    //         commercialLicense = $fwGZrGe();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

package/src/engine/webcomponents/needle-engine.ts

@@ -3,7 +3,7 @@ import type { Texture } from "three";
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { bLW } from "../engine_license.js";
+import { $fwGZrGe } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -579,7 +579,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = bLW();
+        const allowOverridingDefaultLoading = $fwGZrGe();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { bLW } from "../engine_license.js";
+import { $fwGZrGe } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (bLW()) {
+        if ($fwGZrGe()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

package/src/engine-components/AudioSource.ts

@@ -1,4 +1,4 @@
-import { AudioLoader, PositionalAudio } from "three";
+import { PositionalAudio } from "three";
 import { PositionalAudioHelper } from 'three/examples/jsm/helpers/PositionalAudioHelper.js';
 
 import { isDevEnvironment } from "../engine/debug/index.js";
@@ -136,7 +136,13 @@ export class AudioSource extends Behaviour {
      * 
      * @returns True if the audio is playing, false otherwise
      */
-    get isPlaying(): boolean { return this.sound?.isPlaying ?? false; }
+    get isPlaying(): boolean {
+        // For the media-element path (string clips and MediaStreams) three.js does NOT maintain
+        // sound.isPlaying (hasPlaybackControl is false once a media/stream source is set), so the
+        // <audio> element is the source of truth.
+        if (this._audioElement) return !this._audioElement.paused && !this._audioElement.ended;
+        return this.sound?.isPlaying ?? false;
+    }
 
     /**
      * The total duration of the currently loaded audio clip in seconds.
@@ -145,11 +151,14 @@ export class AudioSource extends Behaviour {
      * @remarks For MediaStream clips, duration is not directly available and will return undefined. If the audio clip has not started loading or is still loading, duration may also be undefined until the audio buffer is ready.
      */
     get duration() {
-        if (this.sound?.buffer?.duration) {
-            return this.sound.buffer.duration;
+        // Media-element path is the primary source of truth for string clips.
+        // (NaN/Infinity for MediaStream or before metadata is loaded → treated as "unknown".)
+        const elDuration = this._usesMediaElementSource ? this._audioElement?.duration : undefined;
+        if (elDuration && isFinite(elDuration)) {
+            return elDuration;
         }
-        else if (this._audioElement?.duration) {
-            return this._audioElement.duration;
+        else if (this.sound?.buffer?.duration) {
+            return this.sound.buffer.duration;
         }
         else if (this._loadedClip instanceof MediaStream) {
             // MediaStream duration is not directly available; return undefined or estimate if possible
@@ -164,14 +173,14 @@ export class AudioSource extends Behaviour {
      */
     get time01() {
         const duration = this.duration;
-        if (duration && this.sound) {
-            return this.sound?.context.currentTime / duration;
+        if (duration) {
+            return this.time / duration;
         }
         return 0;
     }
     set time01(val: number) {
         const duration = this.duration;
-        if (duration && this.sound) {
+        if (duration) {
             this.time = val * duration;
         }
     }
@@ -180,8 +189,17 @@ export class AudioSource extends Behaviour {
      * The current playback position in seconds.
      * Can be set to seek to a specific time in the audio.
      */
-    get time(): number { return this.sound?.source ? (this.sound.source?.context.currentTime - this._lastContextTime + this.sound.offset) : 0; }
+    get time(): number {
+        // Media-element path: the element's currentTime is authoritative.
+        if (this._usesMediaElementSource && this._audioElement) return this._audioElement.currentTime;
+        return this.sound?.source ? (this.sound.source?.context.currentTime - this._lastContextTime + this.sound.offset) : 0;
+    }
     set time(val: number) {
+        // Media-element path: seek directly on the element (sound.offset is not used for media nodes).
+        if (this._usesMediaElementSource && this._audioElement) {
+            this._audioElement.currentTime = val;
+            return;
+        }
         if (this.sound) {
             if (val === this.sound.offset) return;
             const wasPlaying = this.isPlaying;
@@ -199,12 +217,19 @@ export class AudioSource extends Behaviour {
      */
     @serializable()
     get loop(): boolean {
+        // Media-element path: the element holds the authoritative loop flag (sound.getLoop()
+        // warns and returns false once hasPlaybackControl is false).
+        if (this._usesMediaElementSource && this._audioElement) {
+            this._loop = this._audioElement.loop;
+            return this._loop;
+        }
         if (this.sound) this._loop = this.sound.getLoop();
         return this._loop;
     }
     set loop(val: boolean) {
         this._loop = val;
-        if (this.sound) this.sound.setLoop(val);
+        if (this._usesMediaElementSource && this._audioElement) this._audioElement.loop = val;
+        else if (this.sound) this.sound.setLoop(val);
     }
 
     /**
@@ -279,9 +304,13 @@ export class AudioSource extends Behaviour {
      */
     @serializable()
     set pitch(val: number) {
-        if (this.sound) this.sound.setPlaybackRate(val);
+        // Media-element path: playbackRate on the element (sound.setPlaybackRate warns and is a
+        // no-op once hasPlaybackControl is false).
+        if (this._usesMediaElementSource && this._audioElement) this._audioElement.playbackRate = val;
+        else if (this.sound) this.sound.setPlaybackRate(val);
     }
     get pitch(): number {
+        if (this._usesMediaElementSource && this._audioElement) return this._audioElement.playbackRate;
         return this.sound ? this.sound.getPlaybackRate() : 1;
     }
 
@@ -298,13 +327,20 @@ export class AudioSource extends Behaviour {
     private sound: PositionalAudio | null = null;
     private helper: PositionalAudioHelper | null = null;
     private wasPlaying = false;
-    private audioLoader: AudioLoader | null = null;
     private shouldPlay: boolean = false;
     // set this from audio context time, used to set clip offset when setting "time" property
     // there is maybe a better way to set a audio clip current time?!
-    private _lastClipStartedLoading: string | MediaStream | null = null;
     private _loadedClip: string | MediaStream | null = null;
     private _audioElement: HTMLAudioElement | null = null;
+    /**
+     * True when {@link _audioElement} is a file-URL element routed through
+     * `sound.setMediaElementSource()` (the iOS-survivable string-clip path). For this path ALL
+     * playback control (play/pause/stop/loop/pitch/time/isPlaying) goes through the element,
+     * because three.js sets `hasPlaybackControl = false` once a media source is attached.
+     * It is `false` for the distinct MediaStream path (which uses an element with `srcObject`
+     * plus `setMediaStreamSource()` and is controlled differently).
+     */
+    private _usesMediaElementSource: boolean = false;
 
     // Spatial blend dual-path audio nodes
     private _entryNode: GainNode | null = null;
@@ -352,18 +388,49 @@ export class AudioSource extends Behaviour {
         return this.sound?.context;
     }
 
+    /**
+     * Resumes the shared AudioContext if it is currently suspended/interrupted and the
+     * page is visible. Uses the same policy as the global resume handler so this never
+     * triggers the iOS `InvalidStateError: Failed to start the audio device` (which
+     * happens when resuming while the page is hidden). No-op when the context is already
+     * running or when resuming is not currently allowed.
+     */
+    private ensureContextResumed() {
+        const ctx = this.audioContext;
+        if (!ctx) return;
+        const visibility = typeof document !== "undefined" ? document.visibilityState : "visible";
+        // Only skip while hidden — resuming a hidden context throws iOS InvalidStateError.
+        if (visibility !== "visible") return;
+        // Resume even when ctx.state already reports "running". On iOS an auto-resume that
+        // happened OUTSIDE a user gesture (e.g. our visibilitychange retry) can leave the
+        // context reporting "running" while the audio HARDWARE stays off ("zombie" context).
+        // play() is user-initiated, so this resume() runs inside the gesture and re-enables
+        // actual output. It is a harmless no-op on an already-healthy context.
+        // (The global handler in engine_audio.ts still uses shouldResumeAudioContext, because
+        // it fires on timers/events with no gesture and must not spam resume on a running ctx.)
+        ctx.resume().catch(e => { if (debug) console.warn("[AudioSource] Failed to resume AudioContext:", e); });
+    }
+
     /** @internal */
     awake() {
         if (debug) console.log("[AudioSource]", this);
 
-        this.audioLoader = new AudioLoader();
         if (this.playOnAwake) this.shouldPlay = true;
 
         if (this.preload) {
             if (typeof this.clip === "string" && this.clip.length > 0) {
-                this.audioLoader.load(this.clip, this.createAudio, () => { }, e => {
-                    console.error(`[AudioSource] Error preloading audio clip "${this.clip}":`, e);
-                });
+                // Preload = create the <audio> element and wire it into the Web Audio graph, but do
+                // NOT play. Wiring needs the PositionalAudio (Sound), which in turn needs an
+                // AudioListener that only exists after a user gesture — so defer when not ready.
+                if (this.Sound) {
+                    this.createAudioFromElement();
+                }
+                else {
+                    AudioSource.registerWaitForAllowAudio(() => {
+                        if (this.destroyed || this.enabled === false) return;
+                        if (typeof this.clip === "string" && this.clip.length > 0) this.createAudioFromElement();
+                    });
+                }
             }
         }
     }
@@ -397,15 +464,23 @@ export class AudioSource extends Behaviour {
         switch (document.visibilityState) {
             case "hidden":
                 if (this.playInBackground === false || DeviceUtilities.isMobileDevice()) {
-                    this.wasPlaying = this.isPlaying;
-                    if (this.isPlaying) {
+                    const wasPlaying = this.isPlaying;
+                    if (wasPlaying) {
                         this.pause();
                     }
+                    // pause() clears wasPlaying so a *user-initiated* pause is not auto-resumed on
+                    // the next foreground. This pause is automatic (page hidden / device locked), so
+                    // re-assert the resume intent AFTER pause() — otherwise we never resume on unlock.
+                    this.wasPlaying = wasPlaying;
                 }
                 break;
             case "visible":
                 if (debug) console.log("visible", this.enabled, this.playOnAwake, !this.isPlaying, AudioSource.userInteractionRegistered, this.wasPlaying);
-                if (this.enabled && this.playOnAwake && !this.isPlaying && AudioSource.userInteractionRegistered && this.wasPlaying) {
+                // Resume anything that was actively playing when the page was hidden — not
+                // just playOnAwake sources. `wasPlaying` is the correct signal: it is only
+                // set when this source was playing at hide time, so script-started clips
+                // resume too (previously they stayed silent until a manual play()).
+                if (this.enabled && !this.isPlaying && AudioSource.userInteractionRegistered && this.wasPlaying) {
                     this.play();
                 }
                 break;
@@ -419,13 +494,89 @@ export class AudioSource extends Behaviour {
             this.sound?.setVolume(this.volume);
     }
 
-    private createAudio = (buffer?: AudioBuffer) => {
+    /**
+     * Sets up playback of a string (file URL) clip through an `HTMLAudioElement` routed into the
+     * Web Audio graph via `sound.setMediaElementSource()`.
+     *
+     * Why a media element instead of a decoded `AudioBuffer`: on iOS Safari an
+     * `AudioBufferSourceNode` has its output torn down after a device lock / audio-session
+     * interruption and cannot be reliably revived. A `MediaElementAudioSourceNode` survives the
+     * lock because the playing `<audio>` element keeps iOS's media session alive, so the shared
+     * AudioContext is never torn down and resumes cleanly. This is the same approach three.js's own
+     * `webaudio_orientation` example uses.
+     *
+     * This does NOT start playback — it only creates/wires the element so a later `.play()` (driven
+     * by a user gesture) is cheap.
+     */
+    private createAudioFromElement() {
         if (this.destroyed) {
             if (debug) console.warn("AudioSource destroyed, not creating audio", this.name);
             return;
         }
+        const sound = this.Sound;
+        if (!sound) {
+            if (debug) console.warn("Failed getting sound?", this.name);
+            return;
+        }
+
+        // If the element is already wired for the CURRENT clip, there is nothing to (re)create —
+        // re-running setMediaElementSource on the same element throws InvalidStateError
+        // ("already connected to a MediaElementSourceNode"), so bail out early.
+        if (this._audioElement && this._usesMediaElementSource && this._loadedClip === this.clip) {
+            // keep volume/mute in sync, then we're done
+            if (this.context.application.muted) sound.setVolume(0);
+            else sound.setVolume(this.volume);
+            return;
+        }
+
+        // (re)create the element when the clip changed since the element was wired.
+        if (this._audioElement && this._loadedClip !== this.clip) {
+            this._audioElement.pause();
+            this._audioElement = null;
+            this._usesMediaElementSource = false;
+        }
+        const created = !this._audioElement;
+        if (created) {
+            const el = new Audio();
+            el.crossOrigin = "anonymous";
+            el.preload = "auto";
+            el.src = this.clip as string;
+            this._audioElement = el;
+        }
+        this._audioElement!.loop = this._loop;
+
+        // IMPORTANT: build the spatial-blend graph FIRST so getOutput() returns the entry node,
+        // THEN route the media element source into it. setMediaElementSource() immediately calls
+        // sound.connect() (source → getOutput()), so the entry node and the getOutput override
+        // must already exist. Order matters.
+        this.setupSpatialBlendNodes();
+        // Only connect once per element — createMediaElementSource() throws if the same
+        // HTMLMediaElement is passed to it twice.
+        if (!this._usesMediaElementSource) {
+            sound.setMediaElementSource(this._audioElement!);
+            this._usesMediaElementSource = true;
+        }
+        this._loadedClip = this.clip;
 
-        if (debug) console.log("AudioBuffer finished loading", buffer);
+        if (this.context.application.muted) sound.setVolume(0);
+        else sound.setVolume(this.volume);
+        this.applySpatialDistanceSettings();
+
+        // Playback is started explicitly by onNewClip()/play()/onEnable — do NOT auto-play here.
+        // Registering __onAllowAudioCallback would (once the user has interacted) fire immediately
+        // and call play() a SECOND time, restarting the element → audible "clipping repeat".
+    }
+
+    /**
+     * Sets up the {@link PositionalAudio} graph for a MediaStream clip (used for the MediaStream
+     * path only — string clips go through {@link createAudioFromElement}). The actual stream node
+     * is attached in {@link play} via `setMediaStreamSource`.
+     */
+    private createAudio = () => {
+        if (this.destroyed) {
+            if (debug) console.warn("AudioSource destroyed, not creating audio", this.name);
+            return;
+        }
 
         const sound = this.Sound;
         if (!sound) {
@@ -433,21 +584,12 @@ export class AudioSource extends Behaviour {
             return;
         }
 
-        if (sound.isPlaying)
-            sound.stop();
-
-        if (buffer) sound.setBuffer(buffer);
         this._loadedClip = this.clip;
-        sound.loop = this._loop;
         if (this.context.application.muted) sound.setVolume(0);
         else sound.setVolume(this.volume);
-        sound.autoplay = this.shouldPlay && AudioSource.userInteractionRegistered;
         this.setupSpatialBlendNodes();
         this.applySpatialDistanceSettings();
 
-        if (sound.isPlaying)
-            sound.stop();
-
         // make sure we only play the sound if the user has interacted with the page
         AudioSource.registerWaitForAllowAudio(this.__onAllowAudioCallback);
     }
@@ -564,23 +706,21 @@ export class AudioSource extends Behaviour {
             if (debug)
                 console.log(clip);
             if (clip.endsWith(".mp3") || clip.endsWith(".wav") || clip.endsWith(".ogg") || clip.endsWith(".opus") || clip.endsWith(".flac") || clip.endsWith(".aac") || clip.endsWith(".webm")) {
-                if (!this.audioLoader)
-                    this.audioLoader = new AudioLoader();
                 this.shouldPlay = true;
-                if (this._lastClipStartedLoading === clip) {
-                    if (debug) console.log("Is currently loading:", this._lastClipStartedLoading, this)
-                    return;
+                // Route the file URL through an <audio> element (survives iOS lock — see
+                // createAudioFromElement). This creates/wires the element without playing.
+                this.createAudioFromElement();
+                // Start playback through the element (NOT this.sound — hasPlaybackControl is false
+                // for a media-element source). __onAllowAudioCallback would also play once
+                // interaction is registered; this covers the already-interacted case directly.
+                if (this.shouldPlay && AudioSource.userInteractionRegistered) {
+                    this.ensureContextResumed();
+                    this._hasEnded = false;
+                    this._audioElement?.play().catch(e => {
+                        if (debug) console.warn(`[AudioSource] Failed to play audio clip "${clip}":`, e);
+                    });
+                    this.fadeEntryGain(1); // fade in (no-op on first play; undoes a prior pause() fade)
                 }
-                this._lastClipStartedLoading = clip;
-                if (debug)
-                    console.log("load audio", clip);
-                const buffer = await this.audioLoader.loadAsync(clip).catch(e => {
-                    console.error(`[AudioSource] Error loading audio clip "${clip}":`, e);
-                    return null;
-                });
-                if (this.destroyed) return;
-                if (this._lastClipStartedLoading === clip) this._lastClipStartedLoading = null;
-                if (buffer) this.createAudio(buffer);
             }
             else console.warn("Unsupported audio clip type", clip)
         }
@@ -612,9 +752,12 @@ export class AudioSource extends Behaviour {
 
         // Load if the sound hasn't been created yet or if the clip changed since last load
         let needsLoading = !this.sound || (clip && clip !== this._loadedClip);
-        if (typeof clip === "string" && !this.audioLoader) needsLoading = true;
+        // For string clips the <audio> element must additionally be wired (createAudioFromElement);
+        // if it isn't yet (e.g. preload was off, or the element was torn down), force a (re)load.
+        if (typeof clip === "string" && (!this._audioElement || !this._usesMediaElementSource)) needsLoading = true;
         if (clip instanceof MediaStream || typeof clip === "string")
             this.clip = clip;
+
         if (needsLoading) {
             this.shouldPlay = true;
             return this.onNewClip(clip).then(() => true).catch(() => false);
@@ -625,16 +768,23 @@ export class AudioSource extends Behaviour {
 
         if (debug) console.log("[AudioSource] play", this.sound?.getVolume(), this.sound);
         // If a different clip was passed in, needsLoading above would be true and onNewClip handles it.
-        // This guard prevents double-playing the same already-playing sound (which would throw in three.js).
-        if (this.sound && !this.sound.isPlaying) {
+        // This guard prevents double-playing the same already-playing sound.
+        if (this.sound && !this.isPlaying) {
+            // On iOS the shared context can be suspended/interrupted (device locked, app
+            // backgrounded, audio session interrupted by a call) — starting playback on it produces
+            // no sound until it is resumed. Resume it here (we are inside a user gesture) so playback
+            // does not silently depend on the global resume handler running first. See engine_audio.ts.
+            this.ensureContextResumed();
             const muted = this.context.application.muted;
             if (muted) this.sound.setVolume(0);
             this.gameObject?.add(this.sound);
 
             if (this.clip instanceof MediaStream) {
 
-                // We have to set the audio element source to the mediastream as well
-                // otherwise it will not play for some reason...
+                // Distinct from the file-URL media-element path: a MediaStream uses
+                // setMediaStreamSource + an element holding srcObject (the element is only needed
+                // so the stream actually plays — playback is not controlled through it here).
+                this._usesMediaElementSource = false;
                 this.sound.setMediaStreamSource(this.clip);
 
                 if (!this._audioElement) {
@@ -649,8 +799,15 @@ export class AudioSource extends Behaviour {
 
             }
             else {
-                if (this._audioElement) this._audioElement.remove();
-                this.sound.play(muted ? .1 : 0);
+                // File-URL media-element path: playback control is on the element, not this.sound
+                // (hasPlaybackControl is false once setMediaElementSource was called). Volume/mute
+                // is still applied via sound.setVolume() above (the gain node still works).
+                // Resume the element from its (frozen) position, then fade the entry gain back in so
+                // the resume is click-free. No seek, no graph reconnect — both caused the stutter.
+                this._audioElement?.play().catch(e => {
+                    if (debug) console.warn("[AudioSource] Failed to play audio element:", e);
+                });
+                this.fadeEntryGain(1);
                 return true;
             }
         }
@@ -658,6 +815,23 @@ export class AudioSource extends Behaviour {
         return false;
     }
 
+    /**
+     * Smoothly ramp the spatial-graph entry-gain node to `target` (1 = audible, 0 = silent) over a
+     * few ms. A short *fade* — not a hard 0/1 gain change and not a connect/disconnect — is what
+     * avoids the click on pause/resume (an instant change or a graph (dis)connect steps the waveform
+     * → audible click). On iOS the MediaElementAudioSourceNode keeps feeding the graph after
+     * element.pause() following an interruption, so fading this gain to 0 is what actually silences a
+     * "paused" media clip; element.pause() only freezes its playback position.
+     */
+    private fadeEntryGain(target: number, seconds = 0.02) {
+        if (!this._entryNode || !this.sound) return;
+        const ctx = this.sound.context;
+        const g = this._entryNode.gain;
+        g.cancelScheduledValues(ctx.currentTime);
+        g.setValueAtTime(g.value, ctx.currentTime);
+        g.linearRampToValueAtTime(target, ctx.currentTime + seconds);
+    }
+
     /**
      * Pauses audio playback while maintaining the current position.
      * Use play() to resume from the paused position.
@@ -666,10 +840,24 @@ export class AudioSource extends Behaviour {
         if (debug) console.log("[AudioSource] pause", this);
         this._hasEnded = true;
         this.shouldPlay = false;
+        // A user-initiated pause must not be revived by the visibility handler on the next
+        // foreground (it replays sources whose `wasPlaying` is set).
+        this.wasPlaying = false;
+        if (this._usesMediaElementSource) {
+            // File-URL media-element path. On iOS the MediaElementAudioSourceNode keeps emitting into
+            // the Web Audio graph after element.pause() once the audio session has been interrupted
+            // (lock/unlock) — pausing the element does NOT silence it (confirmed on-device). So we
+            // fade the entry gain to 0 (click-free silence — the fade is what actually silences it),
+            // then freeze the element's position. play() fades it back in.
+            this.fadeEntryGain(0);
+            this._audioElement?.pause();
+            return;
+        }
         if (this.sound && this.sound.isPlaying && this.sound.source) {
             this._lastContextTime = this.sound?.context.currentTime;
             this.sound.pause();
         }
+        // MediaStream / legacy path: drop the stream element as before.
         this._audioElement?.remove();
     }
 
@@ -681,12 +869,22 @@ export class AudioSource extends Behaviour {
         if (debug) console.log("[AudioSource] stop", this);
         this._hasEnded = true;
         this.shouldPlay = false;
+        this.wasPlaying = false;
+        if (this._usesMediaElementSource) {
+            // True stop: detach the source from the graph (see pause() — element.pause() alone does
+            // not silence it on iOS after an interruption), pause, and rewind to the start.
+            this.fadeEntryGain(0);
+            this._audioElement?.pause();
+            if (this._audioElement) this._audioElement.currentTime = 0;
+            return;
+        }
         if (this.sound && this.sound.source) {
             this._lastContextTime = this.sound?.context.currentTime;
             if (debug)
                 console.log("[AudioSource] lastContextTime", this._lastContextTime);
             this.sound.stop();
         }
+        // MediaStream / legacy path: drop the stream element as before.
         this._audioElement?.remove();
     }
 
@@ -707,7 +905,10 @@ export class AudioSource extends Behaviour {
             this.applySpatialDistanceSettings();
         }
 
-        if (this.sound && !this.sound.isPlaying && this.shouldPlay && !this._hasEnded) {
+        // Use the element-aware `isPlaying` getter, NOT `sound.isPlaying`: for a media-element
+        // source three.js leaves `sound.isPlaying` permanently false (hasPlaybackControl=false),
+        // which would otherwise fire "ended" every frame during playback.
+        if (this.sound && !this.isPlaying && this.shouldPlay && !this._hasEnded) {
             this._hasEnded = true;
             if (debug) console.log("[AudioSource] Audio clip ended", this.clip);
             this.dispatchEvent(new CustomEvent("ended", { detail: this }));

package/src/engine-components/Component.ts

@@ -1107,7 +1107,8 @@ export abstract class Component implements IComponent, EventTarget,
         this.__didCompleteStart = false;
         this.__inEnableOrDisableCallback = false;
         this.__didEnable = false;
-        this.__isEnabled = undefined;
+        // Preserve copied/constructor-assigned enabled state while resetting lifecycle flags.
+        // Cloned disabled components must not fall back to the default enabled=true state.
         this.__destroyed = false;
         this._internalInit(init);
         return this;

package/src/engine-components/DragControls.ts

@@ -113,6 +113,7 @@ export class DragProfile {
  * @see {@link SyncedTransform} for networked dragging
  * @see {@link ObjectRaycaster} for pointer detection
  */
+
 export class DragControls extends Behaviour implements IPointerEventHandler {
 
     /**
@@ -797,8 +798,8 @@ class MultiTouchDragHandler implements IDragHandler {
     private _currentScaleRatio: number = 1;
     /** World-scale of the dragged object captured at drag start. Used to apply scale directly. */
     private readonly _initialWorldScale: Vector3 = new Vector3(1, 1, 1);
-    /** Clamps the dragged object's world scale during two-pointer scaling. Defaults to [0.01, 10000] relative to initial scale. */
-    private readonly _scaleLimitConstraint: ScaleLimitConstraint = new ScaleLimitConstraint(0.01, 10000, true);
+    /** Clamps the dragged object's world scale during two-pointer scaling. */
+    private readonly _scaleLimitConstraint: ScaleLimitConstraint = new ScaleLimitConstraint(0.0001, 1_000_000, true);
 
     private _tempVec1: Vector3 = new Vector3();
     private _tempVec2: Vector3 = new Vector3();