@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e6680fa

package/src/engine-components/OrbitControls.ts

@@ -582,7 +582,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     };
 
     private _onPointerUpLate = (evt: NEPointerEvent) => {
-        if (this.doubleClickToFocus && evt.isDoubleClick && !evt.used) {
+        if (this.doubleClickToFocus && evt.isDoubleClick && !evt.used && this.canFocusAtPointer()) {
             this.setTargetFromRaycast();
         }
         // Automatically update the camera focus
@@ -663,7 +663,15 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
         this._controls.enabled = true;
 
-        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || (this.context.input.getPointerPressed(0) && this.context.input.getPointerPositionDelta(0)?.length() || 0 > .1)) {
+        // Interrupt programmatic transitions on meaningful new user interaction:
+        // - Middle/right button down (always intentional camera control)
+        // - Mouse wheel (zoom intent)
+        // - Left button drag start: getPointerDown(0) with a position delta — a bare click
+        //   without movement shouldn't cancel an animation, but starting to drag should.
+        //   Using getPointerDown (not getPointerPressed) ensures we only interrupt once at
+        //   drag onset, not continuously every frame during a drag.
+        const leftDragStart = this.context.input.getPointerDown(0) && (this.context.input.getPointerPositionDelta(0)?.length() || 0) > .1;
+        if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || leftDragStart) {
             this._inputs += 1;
         }
         if (this._inputs > 0 && this.allowInterrupt) {
@@ -708,7 +716,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             }
         }
 
-        const focusAtPointer = (this.middleClickToFocus && this.context.input.getPointerClicked(1));
+        const focusAtPointer = (this.middleClickToFocus && this.context.input.getPointerClicked(1) && this.canFocusAtPointer());
         if (focusAtPointer) {
             this.setTargetFromRaycast();
         }
@@ -758,19 +766,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (this.targetBounds) {
             // #region target bounds
-            const targetVector = this._controls.target;
             const boundsCenter = this.targetBounds.worldPosition;
             const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
             const min = getTempVector(boundsCenter).sub(boundsHalfSize);
             const max = getTempVector(boundsCenter).add(boundsHalfSize);
-            const newTarget = getTempVector(this._controls.target).clamp(min, max);
-            const duration = .1;
-            if (duration <= 0) targetVector.copy(newTarget);
-            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+
             if (this._lookTargetLerpActive) {
-                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
-                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+                // During a programmatic transition (fitCamera / setLookTargetPosition with immediate: false),
+                // only clamp the destination. The look-target lerp (above) handles moving _controls.target
+                // towards the endpoint — we must not fight it by also lerping _controls.target here.
+                this._lookTargetEndPosition.clamp(min, max);
+            }
+            else {
+                // Interactive use (pan/orbit): smoothly push the target back into bounds
+                const targetVector = this._controls.target;
+                const newTarget = getTempVector(targetVector).clamp(min, max);
+                const duration = .1;
+                if (duration <= 0) targetVector.copy(newTarget);
+                else targetVector.lerp(newTarget, Math.min(1, this.context.time.deltaTime / duration));
             }
+
             if (debug) {
                 Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
             }
@@ -847,7 +862,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
-                    Gizmos.DrawWireSphere(this._controls.target, 0.1, 0x00ff00);
+                    const distance = this._controls.getDistance();
+                    Gizmos.DrawWireSphere(this._controls.target, 0.01 * distance, 0x00ff00);
                 }
             }
         }
@@ -1022,7 +1038,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
         if (debug) {
             console.warn("OrbitControls: setLookTargetPosition", position, immediateOrDuration);
-            Gizmos.DrawWireSphere(this._lookTargetEndPosition, .2, 0xff0000, 2);
+            const distance = this._controls.getDistance();
+            Gizmos.DrawWireSphere(this._lookTargetEndPosition, 0.01 * distance, 0xff5500, 2);
         }
 
         if (immediateOrDuration === true) {
@@ -1063,6 +1080,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (this.lookAtTarget && this.lockLookAtTarget) this.lookAtTarget.worldPosition = this._controls.target;
     }
 
+    private canFocusAtPointer(): boolean {
+        // A locked lookAtTarget is the authoritative orbit center. Pointer focus would
+        // otherwise move the assigned scene object via lerpLookTarget's back-sync.
+        return !(this.lookAtTarget && this.lockLookAtTarget);
+    }
+
     private setTargetFromRaycast(ray?: Ray, immediateOrDuration: number | boolean = false): boolean {
         if (!this.controls) return false;
         const rc = ray ? this.context.physics.raycastFromRay(ray) : this.context.physics.raycast();
@@ -1086,13 +1109,16 @@ export class OrbitControls extends Behaviour implements ICameraController {
     // Adapted from https://discourse.threejs.org/t/camera-zoom-to-fit-object/936/24
     // Slower but better implementation that takes bones and exact vertex positions into account: https://github.com/google/model-viewer/blob/04e900c5027de8c5306fe1fe9627707f42811b05/packages/model-viewer/src/three-components/ModelScene.ts#L321
 
-    /** 
-     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
+    /**
+     * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in)
      * @param options The options for fitting the camera. Use to provide objects to fit to, fit direction and size and other settings.
     */
     fitCamera(options?: OrbitFitCameraOptions);
-    /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
+    // Deprecated overload commented out: it accepted Object3D as first arg, which caused
+    // TypeScript autocomplete to show Object3D properties (position, worldPosition, etc.)
+    // instead of OrbitFitCameraOptions. The implementation still handles Object3D at runtime
+    // for backwards-compat — use fitCamera({ objects: [...] }) instead.
+    // fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {
 
 

package/src/engine-components/RigidBody.ts

@@ -204,12 +204,19 @@ export class Rigidbody extends Behaviour implements IRigidbody {
 
     get isRigidbody() { return true; }
 
-    /** When true the mass will be automatically calculated by the attached colliders */
+    /** When true the mass is automatically computed from the attached colliders using `mass = density × volume`.
+     * Each collider's {@link Collider.density} determines how heavy it contributes to the total mass.
+     * Disable to set mass explicitly via the `mass` property.
+     */
     @validate()
     autoMass: boolean = true;
 
-    /** By default the mass will be automatically calculated (see `autoMass`) by the physics engine using the collider sizes  
-     * To set the mass manually you can either set the `mass` value or set `autoMass` to `false`
+    /** The mass of the rigidbody in kg (when `autoMass` is disabled).
+     * When `autoMass` is enabled, reading this returns the computed mass from `density × volume` of all attached colliders.
+     * Setting this property automatically disables `autoMass`.
+     *
+     * **Prefer using {@link Collider.density}** with `autoMass` enabled instead — density scales
+     * naturally with collider size, while explicit mass stays fixed regardless of shape changes.
      */
     @serializable()
     set mass(value: number) {
@@ -403,9 +410,16 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this.context.physics.engine?.removeBody(this);
     }
 
-    onValidate() {
+    onValidate(property?: string) {
         this._propertiesChanged = true;
+        if (property === "autoMass" && !this.autoMass) {
+            if (isDevEnvironment() && !Rigidbody._didWarnAutoMass) {
+                Rigidbody._didWarnAutoMass = true;
+                console.warn("[Rigidbody] autoMass disabled — consider using Collider.density instead of setting mass explicitly. Density scales naturally with collider size.");
+            }
+        }
     }
+    private static _didWarnAutoMass = false;
 
     // need to do this right before updating physics to prevent rendered object glitching through physical bodies
     * beforePhysics() {

package/src/engine-components/SceneSwitcher.ts

@@ -747,6 +747,9 @@ export class SceneSwitcher extends Behaviour {
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
                 this.sceneLoaded?.invoke(this);
+                if (this._currentSceneAsset) {
+                    this.context.events.emit("scene-content-changed", { source: this, object: this._currentSceneAsset });
+                }
                 return true;
             }
         }

package/src/engine-components/SeeThrough.ts

@@ -249,10 +249,10 @@ export class SeeThrough extends Behaviour {
             }
 
             const materials = renderer.sharedMaterials;// : this.rendererMaterials.get(renderer);
-            if (!materials) return;
+            if (!materials?.length) return;
 
             const block = MaterialPropertyBlock.get(renderer.gameObject);
-            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0].opacity ?? 1);
+            const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0]?.opacity ?? 1);
 
             let newAlpha = Mathf.lerp(currentOpacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
             if (newAlpha >= 0.99) newAlpha = 1;

package/src/engine-components/VideoPlayer.ts

@@ -207,16 +207,13 @@ export class VideoPlayer extends Behaviour {
      */
     get isPlaying(): boolean {
         const video = this._videoElement;
-        if (video) {
-            if (video.currentTime > 0 && !video.paused && !video.ended
-                && video.readyState > video.HAVE_CURRENT_DATA)
-                return true;
-            else if (video.srcObject) {
-                const stream = video.srcObject as MediaStream;
-                if (stream.active) return true;
-            }
+        if (!video) return false;
+        if (video.paused || video.ended) return false;
+        if (video.srcObject) {
+            const stream = video.srcObject as MediaStream;
+            return stream.active;
         }
-        return false;
+        return video.currentTime > 0 && video.readyState > video.HAVE_CURRENT_DATA;
     }
 
     get crossOrigin(): string | null {
@@ -430,26 +427,52 @@ export class VideoPlayer extends Behaviour {
 
     private _playErrors: number = 0;
 
-    /** start playing the video source */
-    play() {
+    /**
+     * Plays the assigned video clip, URL, or MediaStream.
+     * If a `clip` argument is passed, it is used as the new video source (mirroring {@link AudioSource.play}).
+     *
+     * @param clip - Optional video URL string or {@link MediaStream} to play. If omitted, plays the currently assigned source.
+     * @returns A promise that resolves to `true` when playback was successfully started, or `false` on error.
+     */
+    async play(clip?: string | MediaStream): Promise<boolean> {
+        // Defensive: if called from an event handler with a non-string/non-MediaStream argument
+        // (e.g. SpatialTrigger.onEnter passes a receiver object), ignore the arg and fall back to the assigned source.
+        // Same pattern as AudioSource.play.
+        if (clip !== undefined && typeof clip !== "string" && !(clip instanceof MediaStream)) {
+            if (isDevEnvironment()) console.warn("[VideoPlayer] Called play with unknown argument type. Using assigned source instead.", clip);
+            clip = undefined;
+        }
+
+        if (typeof clip === "string") {
+            this.setClipURL(clip);
+        }
+        else if (clip instanceof MediaStream) {
+            this.setVideo(clip);
+        }
+
         if (!this._videoElement) this.create(false);
         if (!this._videoElement) {
             if (debug) console.warn("Can not play: no video element found", this);
-            return
+            return false;
         }
-        if (this._isPlaying && !this._videoElement?.ended && !this._videoElement?.paused) return;
+        if (this._isPlaying && !this._videoElement?.ended && !this._videoElement?.paused) return true;
         this._isPlaying = true;
         if (!this._receivedInput) this._videoElement.muted = true;
         this.handleBeginPlaying(false);
 
         if (this.shouldUseM3U) {
             this.ensureM3UCanBePlayed();
-            return;
+            return true;
         }
 
         if (debug) console.log("Video Play()", this.clip, this._videoElement, this.time);
         this._videoElement.currentTime = this.time;
-        this._videoElement.play().catch(err => {
+        try {
+            await this._videoElement.play();
+            if (debug) console.log("play", this._videoElement, this.time);
+            return true;
+        }
+        catch (err: any) {
             if (this._playErrors++ < 10) console.error(err);
             else if (this._playErrors === 10) console.error("Multiple errors playing video, further errors will be suppressed. Use 'debugvideo' param to see all errors.");
             // https://developer.chrome.com/blog/play-request-was-interrupted/
@@ -459,8 +482,8 @@ export class VideoPlayer extends Behaviour {
                 if (this._isPlaying && !this.destroyed && this.activeAndEnabled)
                     this.play();
             }, 1000);
-        });
-        if (debug) console.log("play", this._videoElement, this.time);
+            return false;
+        }
     }
 
     /**

package/src/engine-components/Voip.ts

@@ -36,9 +36,9 @@ const debugParam = getParam("debugvoip");
  * voip.createMenuButton = true;
  *
  * // Manual control
- * voip.connect();    // Start sending audio
- * voip.disconnect(); // Stop sending
- * voip.setMuted(true); // Mute microphone
+ * voip.connect();    // Start sending your microphone
+ * voip.disconnect(); // Stop sending your microphone
+ * voip.setMuted(true); // Mute incoming audio (silence other users)
  * ```
  *
  * @summary Voice over IP for networked audio communication
@@ -84,9 +84,13 @@ export class Voip extends Behaviour {
     @serializable()
     get volume(): number { return this._volume; }
     set volume(val: number) {
-        this._volume = val;
+        // HTMLMediaElement.volume throws IndexSizeError outside [0,1] — clamp before assigning.
+        // Reject NaN so we don't poison _volume and break serialization.
+        if (Number.isNaN(val)) return;
+        const clamped = Math.max(0, Math.min(1, val));
+        this._volume = clamped;
         for (const audio of this._incomingStreams.values()) {
-            audio.volume = val;
+            audio.volume = clamped;
         }
     }
 
@@ -119,11 +123,11 @@ export class Voip extends Behaviour {
     }
 
     /**
-     * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
-     * they are considered "speaking". Default is 30.
+     * Normalized amplitude threshold for speaking detection (0–1). When a user's average
+     * audio amplitude exceeds this, they are considered "speaking". Default is 0.1.
      */
     @serializable()
-    speakingThreshold: number = 30;
+    speakingThreshold: number = 0.1;
 
     /**
      * Event fired when a user's speaking state changes.
@@ -133,7 +137,11 @@ export class Voip extends Behaviour {
     onSpeakingChanged: EventList = new EventList();
 
     private _speakingStates = new Map<string, boolean>();
-    private _analysers = new Map<string, { analyser: AnalyserNode, data: Uint8Array, context: AudioContext }>();
+    private _analysers = new Map<string, { source: MediaStreamAudioSourceNode, analyser: AnalyserNode, data: Uint8Array }>();
+    // Single shared AudioContext for all remote-user analysers. Browsers cap live AudioContexts at ~6 per tab,
+    // so one-per-user would break voice rooms of 7+ participants. Lazily created on first setupAnalyser.
+    private _sharedAudioContext?: AudioContext;
+    private _lastSpeakingPollMs = 0;
 
     private _net?: NetworkedStreams;
     private _menubutton?: HTMLElement;
@@ -142,12 +150,12 @@ export class Voip extends Behaviour {
     awake() {
         if (debugParam) this.debug = true;
         if (this.debug) {
-            console.log("VOIP debugging: press 'v' to toggle mute or 'c' to toggle connect/disconnect");
+            console.log("VOIP debugging: press 'v' to toggle incoming mute, 'c' to toggle connect/disconnect");
             window.addEventListener("keydown", async (evt) => {
                 const key = evt.key.toLowerCase();
                 switch (key) {
                     case "v":
-                        console.log("MUTE?", !this.isMuted)
+                        console.log("VOIP: toggle incoming mute → ", !this.isMuted);
                         this.setMuted(!this.isMuted);
                         break;
                     case "c":
@@ -156,15 +164,6 @@ export class Voip extends Behaviour {
                         break;
                 }
             });
-            // mute unfocused
-            window.addEventListener("blur", () => {
-                console.log("VOIP: MUTE ON BLUR")
-                this.setMuted(true);
-            });
-            window.addEventListener("focus", () => {
-                console.log("VOIP: UNMUTE ON FOCUS")
-                this.setMuted(false);
-            });
         }
     }
 
@@ -201,10 +200,11 @@ export class Voip extends Behaviour {
         this.onEnabledChanged();
         this.updateButton();
         window.removeEventListener("visibilitychange", this.onVisibilityChanged);
-        // Clean up analysers
+        // Clean up analysers and the shared AudioContext (lazily recreated on next setupAnalyser).
         for (const userId of [...this._analysers.keys()]) {
             this.cleanupAnalyser(userId);
         }
+        this.closeSharedAudioContext();
     }
 
     /** @internal */
@@ -215,6 +215,7 @@ export class Voip extends Behaviour {
         for (const userId of [...this._analysers.keys()]) {
             this.cleanupAnalyser(userId);
         }
+        this.closeSharedAudioContext();
         for (const incoming of this._incomingStreams.values()) {
             disposeStream(incoming.srcObject as MediaStream);
         }
@@ -225,6 +226,10 @@ export class Voip extends Behaviour {
     /** Set via the mic button (e.g. when the websocket connection closes and rejoins but the user was muted before we don't want to enable VOIP again automatically) */
     private _allowSending = true;
     private _outputStream: MediaStream | null = null;
+    // Tracks an in-flight connect() so concurrent callers coalesce onto the same promise
+    // instead of each running getUserMedia in parallel (which would leak a MediaStream and
+    // briefly transmit then kill the first acquired stream).
+    private _connectInFlight?: Promise<boolean>;
 
     /**
      * @returns true if the component is currently sending audio
@@ -233,7 +238,18 @@ export class Voip extends Behaviour {
 
 
     /** Start sending audio. */
-    async connect(audioSource?: MediaTrackConstraints) {
+    connect(audioSource?: MediaTrackConstraints): Promise<boolean> {
+        // Coalesce concurrent callers. Without this, two near-simultaneous connect() calls
+        // each call getUserMedia in parallel, the first stream gets disposed mid-broadcast
+        // by the second, and a MediaStream leaks.
+        if (this._connectInFlight) return this._connectInFlight;
+        this._connectInFlight = this._connectImpl(audioSource).finally(() => {
+            this._connectInFlight = undefined;
+        });
+        return this._connectInFlight;
+    }
+
+    private async _connectImpl(audioSource?: MediaTrackConstraints): Promise<boolean> {
         if (!this._net) {
             console.error("Cannot connect to voice chat - NetworkedStreams not initialized. Make sure the component is enabled before calling this method.");
             return false;
@@ -281,27 +297,25 @@ export class Voip extends Behaviour {
     }
 
     /**
-     * Mute or unmute the audio stream (this will only mute incoming streams and not mute your own microphone. Use disconnect() to mute your own microphone)
+     * Mute or unmute the audio you hear from other users (incoming streams).
+     * This does NOT mute your own microphone — use {@link disconnect} to stop sending your microphone.
      */
     setMuted(mute: boolean) {
-        const audio = this._outputStream?.getAudioTracks();
-        if (audio) {
-            for (const track of audio) {
-                track.enabled = !mute
-            }
+        for (const audio of this._incomingStreams.values()) {
+            audio.muted = mute;
         }
     }
 
-    /** Returns true if the audio stream is currently muted */
+    /**
+     * Returns true if incoming audio is currently muted (you can't hear other users).
+     * When there are no incoming streams, returns false.
+     */
     get isMuted() {
-        if (this._outputStream === null) return false;
-        const audio = this._outputStream?.getAudioTracks();
-        if (audio) {
-            for (const track of audio) {
-                if (!track.enabled) return true;
-            }
+        if (this._incomingStreams.size === 0) return false;
+        for (const audio of this._incomingStreams.values()) {
+            if (!audio.muted) return false;
         }
-        return false;
+        return true;
     }
 
     private async updateButton() {
@@ -381,7 +395,7 @@ export class Voip extends Behaviour {
                 .catch((err) => {
                     console.warn("VOIP failed getting audio stream", err);
                     return null;
-                });;
+                });
         }
 
         const stream = await getUserMedia(audio);
@@ -397,7 +411,13 @@ export class Voip extends Behaviour {
             if (nonBuiltInAudioSource) {
                 const constraints = Object.assign({}, audio);
                 constraints.deviceId = nonBuiltInAudioSource.deviceId;
-                return await getUserMedia(constraints);
+                const externalStream = await getUserMedia(constraints);
+                if (externalStream) {
+                    // Release the built-in mic stream we grabbed first — otherwise its tracks stay live.
+                    disposeStream(stream);
+                    return externalStream;
+                }
+                // External device acquisition failed — keep the original stream rather than returning null.
             }
         }
 
@@ -431,20 +451,25 @@ export class Voip extends Behaviour {
     update() {
         // Only run speaking detection if someone is listening
         if (!this.onSpeakingChanged || this.onSpeakingChanged.listenerCount <= 0) return;
+        // Rate-limit analysis to ~10Hz. Speaking-state is a coarse UI signal; running FFT per
+        // remote user every frame (60Hz) is wasteful and scales linearly with participant count.
+        const now = performance.now();
+        if (now - this._lastSpeakingPollMs < 100) return;
+        this._lastSpeakingPollMs = now;
 
         for (const [userId, info] of this._analysers) {
             info.analyser.getByteFrequencyData(info.data as Uint8Array<ArrayBuffer>);
-            // Average amplitude
+            // Average amplitude normalized to 0–1
             let sum = 0;
             for (let i = 0; i < info.data.length; i++) sum += info.data[i];
-            const avg = sum / info.data.length;
+            const volume = sum / info.data.length / 255;
 
             const wasSpeaking = this._speakingStates.get(userId) ?? false;
-            const isSpeaking = avg > this.speakingThreshold;
+            const isSpeaking = volume > this.speakingThreshold;
 
             if (isSpeaking !== wasSpeaking) {
                 this._speakingStates.set(userId, isSpeaking);
-                this.onSpeakingChanged.invoke({ userId, isSpeaking, volume: avg / 255 });
+                this.onSpeakingChanged.invoke({ userId, isSpeaking, volume });
             }
         }
     }
@@ -453,13 +478,16 @@ export class Voip extends Behaviour {
         // Only set up if someone is listening or might listen
         if (this._analysers.has(userId)) return;
         try {
-            const audioCtx = new AudioContext();
-            const source = audioCtx.createMediaStreamSource(stream);
-            const analyser = audioCtx.createAnalyser();
+            if (!this._sharedAudioContext) {
+                this._sharedAudioContext = new AudioContext();
+            }
+            const ctx = this._sharedAudioContext;
+            const source = ctx.createMediaStreamSource(stream);
+            const analyser = ctx.createAnalyser();
             analyser.fftSize = 256;
             source.connect(analyser);
             const data = new Uint8Array(analyser.frequencyBinCount);
-            this._analysers.set(userId, { analyser, data, context: audioCtx });
+            this._analysers.set(userId, { source, analyser, data });
         }
         catch (err) {
             if (this.debug) console.warn("VOIP: Failed to create analyser for", userId, err);
@@ -469,12 +497,20 @@ export class Voip extends Behaviour {
     private cleanupAnalyser(userId: string) {
         const info = this._analysers.get(userId);
         if (info) {
-            info.context.close();
+            info.source.disconnect();
+            info.analyser.disconnect();
             this._analysers.delete(userId);
         }
         this._speakingStates.delete(userId);
     }
 
+    private closeSharedAudioContext() {
+        if (this._sharedAudioContext) {
+            this._sharedAudioContext.close();
+            this._sharedAudioContext = undefined;
+        }
+    }
+
     private onReceiveStream = (evt: StreamReceivedEvent) => {
         const userId = evt.target.userId;
         const stream = evt.stream;
@@ -512,12 +548,11 @@ export class Voip extends Behaviour {
 
     private onVisibilityChanged = () => {
         if (this.runInBackground) return;
-        const visible = document.visibilityState === "visible";
-        const muted = !visible;
+        const muted = document.visibilityState !== "visible";
+        // Mute incoming so we don't hear other users while tab is hidden.
         this.setMuted(muted);
-        for (const element of this._incomingStreams) {
-            const str = element[1];
-            str.muted = muted;
-        }
+        // Also disable our outgoing mic tracks (cheaper than disconnect/reconnect — keeps the mic permission).
+        const tracks = this._outputStream?.getAudioTracks();
+        if (tracks) for (const t of tracks) t.enabled = !muted;
     };
 }

package/src/engine-components/api.ts

@@ -34,12 +34,14 @@
  * @module Built-in Components
  */
 
+export { AnimationBuilder, type AnimationKeyframe, type Tween, type AnimationInterpolation } from "./AnimationBuilder.js";
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.builder.js";
 export * from "./codegen/components.js";
-export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 
 // We dont want to export everything in the extensions
+export { AudioRolloffMode } from "./AudioSource.js";
 export { ClearFlags } from "./Camera.js"
 export { DragMode } from "./DragControls.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";

package/src/engine-components/codegen/components.ts

@@ -3,21 +3,13 @@
 export class __Ignore {}
 export { AlignmentConstraint } from "../AlignmentConstraint.js";
 export { Animation } from "../Animation.js";
+export { AnimationBuilder } from "../AnimationBuilder.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
-export { AnimatorControllerBuilder } from "../AnimatorController.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";
-export { Avatar_POI } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_Brain_LookAt } from "../avatar/Avatar_Brain_LookAt.js";
-export { Avatar_MouthShapes } from "../avatar/Avatar_MouthShapes.js";
-export { Avatar_MustacheShake } from "../avatar/Avatar_MustacheShake.js";
-export { AvatarBlink_Simple } from "../avatar/AvatarBlink_Simple.js";
-export { AvatarEyeLook_Rotation } from "../avatar/AvatarEyeLook_Rotation.js";
-export { AvatarModel } from "../AvatarLoader.js";
-export { AvatarLoader } from "../AvatarLoader.js";
 export { AxesHelper } from "../AxesHelper.js";
 export { BasicIKConstraint } from "../BasicIKConstraint.js";
 export { BoxHelperComponent } from "../BoxHelperComponent.js";
@@ -168,11 +160,13 @@ export { PlayableDirector } from "../timeline/PlayableDirector.js";
 export { SignalAsset } from "../timeline/SignalAsset.js";
 export { SignalReceiverEvent } from "../timeline/SignalAsset.js";
 export { SignalReceiver } from "../timeline/SignalAsset.js";
-export { AnimationTrackHandler } from "../timeline/TimelineTracks.js";
-export { AudioTrackHandler } from "../timeline/TimelineTracks.js";
-export { MarkerTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineBuilder } from "../timeline/TimelineBuilder.js";
+export { TimelineAnimationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineAudioTrack } from "../timeline/TimelineTracks.js";
+export { TimelineMarkerTrack } from "../timeline/TimelineTracks.js";
 export { SignalTrackHandler } from "../timeline/TimelineTracks.js";
-export { ControlTrackHandler } from "../timeline/TimelineTracks.js";
+export { TimelineActivationTrack } from "../timeline/TimelineTracks.js";
+export { TimelineControlTrack } from "../timeline/TimelineTracks.js";
 export { TransformGizmo } from "../TransformGizmo.js";
 export { BaseUIComponent } from "../ui/BaseUIComponent.js";
 export { UIRootComponent } from "../ui/BaseUIComponent.js";