@iwsdk/core 0.5.2 → 1.0.0-rc.0

package/dist/layers/xr-layer-system.js

@@ -1,9 +1,11 @@
 import { createSystem } from '../ecs/system.js';
 import '../runtime/three.js';
 import { XRCylinderLayer } from './xr-cylinder-layer.js';
+import { createQuadLayerInit } from './xr-layer-init.js';
 import { XRLayerState } from './xr-layer-state.js';
+import { resolveLayerReferencePose, resolveQuadLayerDimensions, resolveCylinderLayerDimensions, isValidCylinderLayerAngle } from './xr-layer-transform.js';
 import { XRQuadLayer } from './xr-quad-layer.js';
-import { Vector3, Quaternion, Color, PlaneGeometry, CylinderGeometry, MeshBasicMaterial, Mesh, FrontSide, BackSide, CustomBlending, AddEquation, ZeroFactor, SRGBColorSpace, WebGLRenderTarget, DepthTexture, UnsignedByteType, RGBAFormat, UnsignedInt248Type, UnsignedIntType, DepthStencilFormat, DepthFormat } from 'three';
+import { Vector3, Quaternion, Matrix4, Color, MeshBasicMaterial, FrontSide, BackSide, Mesh, CustomBlending, AddEquation, ZeroFactor, SRGBColorSpace, PlaneGeometry, CylinderGeometry, WebGLRenderTarget, DepthTexture, UnsignedByteType, RGBAFormat, UnsignedInt248Type, UnsignedIntType, DepthStencilFormat, DepthFormat } from 'three';
 
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
@@ -13,17 +15,37 @@ import { Vector3, Quaternion, Color, PlaneGeometry, CylinderGeometry, MeshBasicM
  */
 const _position = new Vector3();
 const _quaternion = new Quaternion();
+const _scale = new Vector3();
+const _configuration = new Vector3();
+const _relativeMatrix = new Matrix4();
 const _clearColor = new Color();
 function toRigidTransform(pos, quat) {
     return new XRRigidTransform({ x: pos.x, y: pos.y, z: pos.z }, { x: quat.x, y: quat.y, z: quat.z, w: quat.w });
 }
+function isObjectTreeVisible(object) {
+    for (let current = object; current; current = current.parent) {
+        if (!current.visible) {
+            return false;
+        }
+    }
+    return true;
+}
+function sameNumber(first, second) {
+    return first === second || (Number.isNaN(first) && Number.isNaN(second));
+}
+function sameVector(first, second) {
+    return (sameNumber(first.x, second.x) &&
+        sameNumber(first.y, second.y) &&
+        sameNumber(first.z, second.z));
+}
 /**
  * XRLayerSystem manages WebXR quad and cylinder composition layers.
  *
  * For each entity with an {@link XRQuadLayer} or {@link XRCylinderLayer}
  * component, the system:
  * - Creates a mesh (plane or cylinder) as a child of the entity's object3D
- * - Renders layer content each frame via the component's `renderCallback`
+ * - Renders layer content via the component's `renderCallback` while its
+ *   render surface is visible and active
  * - In XR sessions with layer support, creates native XR composition layers
  *   and switches the mesh to a punch-through material that makes the
  *   projection layer transparent where the content layer appears
@@ -39,6 +61,12 @@ class XRLayerSystem extends createSystem({
     constructor() {
         super(...arguments);
         this.sessionUsesLayers = false;
+        this.sessionLayerInitializationPending = false;
+        this.unsupportedLayerStates = new Map();
+        this.pendingNativeLayerRemovals = new Set();
+        this.retiredLayers = [];
+        this.layerVisibility = new Map();
+        this.layerConfigurations = new Map();
     }
     init() {
         const onSessionStart = () => this.handleSessionStart();
@@ -49,9 +77,25 @@ class XRLayerSystem extends createSystem({
         // Register the query subscriptions on cleanupFuncs so they're released on
         // system teardown (matching the xr listeners above).
         this.cleanupFuncs.push(this.queries.quadLayers.subscribe('qualify', (entity) => this.setupLayer(entity, 'quad')), this.queries.quadLayers.subscribe('disqualify', (entity) => this.teardownLayer(entity)), this.queries.cylinderLayers.subscribe('qualify', (entity) => this.setupLayer(entity, 'cylinder')), this.queries.cylinderLayers.subscribe('disqualify', (entity) => this.teardownLayer(entity)));
+        // Query disqualify does not run merely because the system itself is being
+        // destroyed. Release every live compositor and GPU resource explicitly.
+        this.cleanupFuncs.push(() => {
+            for (const entity of [...this.queries.activeLayers.entities]) {
+                this.teardownLayer(entity);
+            }
+            this.disposeRetiredLayers();
+            this.unsupportedLayerStates.clear();
+            this.pendingNativeLayerRemovals.clear();
+            this.layerVisibility.clear();
+            this.layerConfigurations.clear();
+        });
     }
     update() {
-        if (this.queries.activeLayers.entities.size === 0) {
+        if (this.sessionLayerInitializationPending) {
+            this.tryInitializeSessionLayers();
+        }
+        if (this.queries.activeLayers.entities.size === 0 &&
+            this.retiredLayers.length === 0) {
             return;
         }
         this.renderLayers();
@@ -66,21 +110,8 @@ class XRLayerSystem extends createSystem({
         const pixelWidth = entity.getValue(component, 'pixelWidth');
         const pixelHeight = entity.getValue(component, 'pixelHeight');
         const stencil = entity.getValue(component, 'stencil');
-        let geometry;
-        let side;
-        if (isQuad) {
-            const width = entity.getValue(XRQuadLayer, 'width');
-            const height = entity.getValue(XRQuadLayer, 'height');
-            geometry = new PlaneGeometry(width, height);
-            side = FrontSide;
-        }
-        else {
-            const radius = entity.getValue(XRCylinderLayer, 'radius');
-            const centralAngle = entity.getValue(XRCylinderLayer, 'centralAngle');
-            const aspectRatio = entity.getValue(XRCylinderLayer, 'aspectRatio');
-            geometry = new CylinderGeometry(radius, radius, (radius * centralAngle) / aspectRatio, 64, 64, true, Math.PI - centralAngle / 2, centralAngle);
-            side = BackSide;
-        }
+        const geometry = this.createFallbackGeometry(entity, isQuad);
+        const side = isQuad ? FrontSide : BackSide;
         const renderTarget = this.createRenderTarget(pixelWidth, pixelHeight, stencil);
         const fallbackMaterial = new MeshBasicMaterial({
             color: 0xffffff,
@@ -101,57 +132,90 @@ class XRLayerSystem extends createSystem({
             pixelHeight,
             stencil,
         });
+        this.readLayerConfiguration(entity, isQuad, _configuration);
+        this.layerConfigurations.set(entity.index, _configuration.clone());
         if (this.sessionUsesLayers) {
             this.activateNativeLayer(entity);
             this.updateSessionLayers();
         }
     }
     teardownLayer(entity) {
+        var _a, _b;
         const mesh = XRLayerState.data.mesh[entity.index];
         if (!mesh) {
             return;
         }
-        const fallbackMaterial = XRLayerState.data.fallbackMaterial[entity.index];
-        const renderTarget = XRLayerState.data.renderTarget[entity.index];
-        const xrLayer = XRLayerState.data.xrLayer[entity.index];
-        if (xrLayer && this.sessionUsesLayers) {
-            entity.setValue(XRLayerState, 'xrLayer', null);
-            this.updateSessionLayers();
-        }
-        mesh.geometry.dispose();
-        fallbackMaterial.dispose();
-        if (mesh.material !== fallbackMaterial) {
-            mesh.material.dispose();
+        const resources = {
+            xrLayer: XRLayerState.data.xrLayer[entity.index],
+            mesh,
+            fallbackMaterial: XRLayerState.data.fallbackMaterial[entity.index],
+            renderTarget: XRLayerState.data.renderTarget[entity.index],
+        };
+        const nativeLayerIsActive = (_b = (_a = this.xrManager.getSession()) === null || _a === void 0 ? void 0 : _a.renderState.layers) === null || _b === void 0 ? void 0 : _b.includes(resources.xrLayer);
+        if (resources.xrLayer && this.sessionUsesLayers) {
+            this.updateSessionLayers(entity);
         }
-        renderTarget.dispose();
         mesh.removeFromParent();
-        entity.removeComponent(XRLayerState);
+        if (entity.active) {
+            entity.removeComponent(XRLayerState);
+        }
+        this.unsupportedLayerStates.delete(entity.index);
+        this.pendingNativeLayerRemovals.delete(entity.index);
+        this.layerVisibility.delete(entity.index);
+        this.layerConfigurations.delete(entity.index);
+        if (resources.xrLayer && this.sessionUsesLayers && nativeLayerIsActive) {
+            this.retiredLayers.push(resources);
+        }
+        else {
+            this.disposeLayerResources(resources);
+        }
     }
     // ---------------------------------------------------------------------------
     // XR session lifecycle
     // ---------------------------------------------------------------------------
     handleSessionStart() {
+        this.sessionUsesLayers = false;
+        this.sessionLayerInitializationPending = true;
+        this.tryInitializeSessionLayers();
+    }
+    handleSessionEnd() {
+        for (const entity of this.queries.activeLayers.entities) {
+            this.deactivateNativeLayer(entity);
+        }
+        this.disposeRetiredLayers();
+        this.unsupportedLayerStates.clear();
+        this.pendingNativeLayerRemovals.clear();
+        this.layerVisibility.clear();
+        this.sessionUsesLayers = false;
+        this.sessionLayerInitializationPending = false;
+    }
+    /**
+     * Enable composition layers once the projection layer is active.
+     *
+     * super-three queues its projection-layer render state before dispatching
+     * `sessionstart`, so `renderState.layers` can legitimately be empty during
+     * that event. Keep rendering the mesh fallback and retry on subsequent
+     * frames instead of permanently classifying the session as unsupported.
+     */
+    tryInitializeSessionLayers() {
         var _a;
         const session = this.xrManager.getSession();
-        const layers = (_a = session === null || session === void 0 ? void 0 : session.renderState) === null || _a === void 0 ? void 0 : _a.layers;
-        // Need both a layers array AND a projection layer at index 0.
-        // The IWER emulator exposes an empty layers array which is truthy
-        // but has no projection layer -- treat that as "no layers support".
-        if (!(layers === null || layers === void 0 ? void 0 : layers.length)) {
-            this.sessionUsesLayers = false;
-            return;
+        const binding = this.xrManager.getBinding();
+        const renderState = session === null || session === void 0 ? void 0 : session.renderState;
+        if (!session || !binding || !renderState || renderState.baseLayer) {
+            this.sessionLayerInitializationPending = false;
+            return false;
         }
+        if (!((_a = renderState.layers) === null || _a === void 0 ? void 0 : _a[0])) {
+            return false;
+        }
+        this.sessionLayerInitializationPending = false;
         this.sessionUsesLayers = true;
         for (const entity of this.queries.activeLayers.entities) {
             this.activateNativeLayer(entity);
         }
         this.updateSessionLayers();
-    }
-    handleSessionEnd() {
-        for (const entity of this.queries.activeLayers.entities) {
-            this.deactivateNativeLayer(entity);
-        }
-        this.sessionUsesLayers = false;
+        return true;
     }
     // ---------------------------------------------------------------------------
     // Native layer management
@@ -160,105 +224,208 @@ class XRLayerSystem extends createSystem({
         const binding = this.xrManager.getBinding();
         const session = this.xrManager.getSession();
         if (!binding || !session) {
-            return;
+            return false;
         }
         const isQuad = !!XRLayerState.data.isQuad[entity.index];
         const mesh = XRLayerState.data.mesh[entity.index];
         const pixelWidth = XRLayerState.data.pixelWidth[entity.index];
         const pixelHeight = XRLayerState.data.pixelHeight[entity.index];
-        const renderTarget = XRLayerState.data.renderTarget[entity.index];
         const refSpace = this.xrManager.getReferenceSpace();
-        mesh.updateMatrixWorld(true);
-        mesh.getWorldPosition(_position);
-        mesh.getWorldQuaternion(_quaternion);
-        const transform = toRigidTransform(_position, _quaternion);
+        if (!refSpace) {
+            return false;
+        }
+        this.readLayerConfiguration(entity, isQuad, _configuration);
+        const hasSupportedTransform = resolveLayerReferencePose(mesh, this.player, _position, _quaternion, _scale, _relativeMatrix);
         let xrLayer;
         if (isQuad) {
-            const width = entity.getValue(XRQuadLayer, 'width');
-            const height = entity.getValue(XRQuadLayer, 'height');
-            xrLayer = binding.createQuadLayer({
-                transform,
-                width: width / 2,
-                height: height / 2,
+            const dimensions = hasSupportedTransform
+                ? resolveQuadLayerDimensions(_configuration.x, _configuration.y, _scale)
+                : null;
+            if (!dimensions) {
+                this.rememberUnsupportedLayer(entity, 'quad');
+                return false;
+            }
+            xrLayer = binding.createQuadLayer(createQuadLayerInit({
+                transform: toRigidTransform(_position, _quaternion),
+                width: dimensions.width,
+                height: dimensions.height,
                 space: refSpace,
-                viewPixelWidth: pixelWidth,
-                viewPixelHeight: pixelHeight,
-                clearOnAccess: false,
-            });
+                pixelWidth,
+                pixelHeight,
+            }));
         }
         else {
-            const radius = entity.getValue(XRCylinderLayer, 'radius');
-            const centralAngle = entity.getValue(XRCylinderLayer, 'centralAngle');
-            const aspectRatio = entity.getValue(XRCylinderLayer, 'aspectRatio');
+            const dimensions = hasSupportedTransform
+                ? resolveCylinderLayerDimensions(_configuration.x, _configuration.y, _scale)
+                : null;
+            if (!dimensions || !isValidCylinderLayerAngle(_configuration.z)) {
+                this.rememberUnsupportedLayer(entity, 'cylinder');
+                return false;
+            }
             xrLayer = binding.createCylinderLayer({
-                transform,
-                radius,
-                centralAngle,
-                aspectRatio,
+                transform: toRigidTransform(_position, _quaternion),
+                radius: dimensions.radius,
+                centralAngle: _configuration.z,
+                aspectRatio: dimensions.aspectRatio,
                 space: refSpace,
                 viewPixelWidth: pixelWidth,
                 viewPixelHeight: pixelHeight,
                 clearOnAccess: false,
             });
         }
+        this.unsupportedLayerStates.delete(entity.index);
         entity.setValue(XRLayerState, 'xrLayer', xrLayer);
-        // Switch to punch-through material so the projection layer is
-        // transparent where this content layer appears.
-        const side = isQuad ? FrontSide : BackSide;
+        entity.setValue(XRLayerState, 'cachedTransform', {
+            position: _position.clone(),
+            quaternion: _quaternion.clone(),
+            scale: _scale.clone(),
+            configuration: _configuration.clone(),
+        });
+        return true;
+    }
+    deactivateNativeLayer(entity) {
+        var _a;
+        const mesh = XRLayerState.data.mesh[entity.index];
+        const xrLayer = XRLayerState.data.xrLayer[entity.index];
+        if (!xrLayer) {
+            entity.setValue(XRLayerState, 'cachedTransform', null);
+            this.pendingNativeLayerRemovals.delete(entity.index);
+            return;
+        }
+        (_a = xrLayer.destroy) === null || _a === void 0 ? void 0 : _a.call(xrLayer);
+        this.useFallbackSurface(entity, mesh);
+        entity.setValue(XRLayerState, 'xrLayer', null);
+        entity.setValue(XRLayerState, 'cachedTransform', null);
+        this.pendingNativeLayerRemovals.delete(entity.index);
+    }
+    /**
+     * Switch from the internal fallback texture only after the compositor layer
+     * is active. This avoids punching a transparent hole while
+     * updateRenderState() is still pending.
+     */
+    useNativeSurface(entity, mesh) {
+        const fallbackMaterial = XRLayerState.data.fallbackMaterial[entity.index];
+        if (mesh.material !== fallbackMaterial) {
+            return;
+        }
+        const side = XRLayerState.data.isQuad[entity.index] ? FrontSide : BackSide;
         const punchMaterial = new MeshBasicMaterial({ color: 0xffffff, side });
         punchMaterial.blending = CustomBlending;
         punchMaterial.blendEquation = AddEquation;
         punchMaterial.blendSrc = ZeroFactor;
         punchMaterial.blendDst = ZeroFactor;
         mesh.material = punchMaterial;
-        // Mark render target for external-texture usage and set colorSpace so
-        // that WebGLPrograms can derive the correct output encoding (super-three
-        // reads renderTarget.texture.colorSpace when isXRRenderTarget is true).
+        const xrLayer = XRLayerState.data.xrLayer[entity.index];
+        xrLayer.blendTextureSourceAlpha = true;
+        const renderTarget = XRLayerState.data.renderTarget[entity.index];
         renderTarget.isXRRenderTarget = true;
         renderTarget.texture.colorSpace = SRGBColorSpace;
-        entity.setValue(XRLayerState, 'cachedTransform', {
-            position: _position.clone(),
-            quaternion: _quaternion.clone(),
-        });
     }
-    deactivateNativeLayer(entity) {
-        const mesh = XRLayerState.data.mesh[entity.index];
+    /** Restore a fresh internal target after an external XR texture was bound. */
+    useFallbackSurface(entity, mesh) {
         const fallbackMaterial = XRLayerState.data.fallbackMaterial[entity.index];
-        const pixelWidth = XRLayerState.data.pixelWidth[entity.index];
-        const pixelHeight = XRLayerState.data.pixelHeight[entity.index];
-        const stencil = !!XRLayerState.data.stencil[entity.index];
-        // Dispose punch-through material
-        if (mesh.material !== fallbackMaterial) {
-            mesh.material.dispose();
+        if (mesh.material === fallbackMaterial) {
+            return;
         }
-        // Recreate render target so stale __hasExternalTextures state is cleared
+        mesh.material.dispose();
         const oldRenderTarget = XRLayerState.data.renderTarget[entity.index];
         oldRenderTarget.dispose();
-        const newRenderTarget = this.createRenderTarget(pixelWidth, pixelHeight, stencil);
+        const newRenderTarget = this.createRenderTarget(XRLayerState.data.pixelWidth[entity.index], XRLayerState.data.pixelHeight[entity.index], !!XRLayerState.data.stencil[entity.index]);
         entity.setValue(XRLayerState, 'renderTarget', newRenderTarget);
-        // Restore fallback material with the fresh render target texture
         fallbackMaterial.map = newRenderTarget.texture;
         fallbackMaterial.map.offset.y = 1;
         fallbackMaterial.map.repeat.y = -1;
         mesh.material = fallbackMaterial;
-        entity.setValue(XRLayerState, 'xrLayer', null);
-        entity.setValue(XRLayerState, 'cachedTransform', null);
+    }
+    disposeLayerResources(resources) {
+        var _a, _b;
+        (_b = (_a = resources.xrLayer) === null || _a === void 0 ? void 0 : _a.destroy) === null || _b === void 0 ? void 0 : _b.call(_a);
+        resources.mesh.geometry.dispose();
+        resources.fallbackMaterial.dispose();
+        if (resources.mesh.material !== resources.fallbackMaterial) {
+            resources.mesh.material.dispose();
+        }
+        resources.renderTarget.dispose();
+    }
+    disposeRetiredLayers() {
+        for (const resources of this.retiredLayers) {
+            this.disposeLayerResources(resources);
+        }
+        this.retiredLayers.length = 0;
+    }
+    /**
+     * Keep removed layers alive until the queued render state no longer
+     * references them. While removal is pending, clear their native textures so
+     * the compositor cannot present stale content from the detached entity.
+     */
+    renderRetiredLayers(renderer) {
+        var _a;
+        if (this.retiredLayers.length === 0) {
+            return;
+        }
+        const activeLayers = (_a = this.xrManager.getSession()) === null || _a === void 0 ? void 0 : _a.renderState.layers;
+        if (!activeLayers) {
+            this.disposeRetiredLayers();
+            return;
+        }
+        const retained = [];
+        const released = [];
+        for (const resources of this.retiredLayers) {
+            if (activeLayers.includes(resources.xrLayer)) {
+                retained.push(resources);
+            }
+            else {
+                released.push(resources);
+            }
+        }
+        // Commit the classification before disposal or compositor access. If a
+        // later getSubImage() throws, already-released entries cannot be disposed
+        // again, while every still-active entry remains tracked for retry.
+        this.retiredLayers = retained;
+        for (const resources of released) {
+            this.disposeLayerResources(resources);
+        }
+        const binding = this.xrManager.getBinding();
+        const frame = this.xrFrame;
+        for (const resources of retained) {
+            if (!binding || !frame) {
+                continue;
+            }
+            resources.xrLayer.blendTextureSourceAlpha = true;
+            resources.renderTarget.isXRRenderTarget = true;
+            resources.renderTarget.texture.colorSpace = SRGBColorSpace;
+            const subImage = binding.getSubImage(resources.xrLayer, frame);
+            renderer.setRenderTargetTextures(resources.renderTarget, subImage.colorTexture, undefined);
+            renderer.setRenderTarget(resources.renderTarget);
+            renderer.clear(true, true, true);
+        }
     }
     /**
      * Rebuild the session's render state layers array.
      * Keeps the projection layer at index 0, then appends content layers.
      */
-    updateSessionLayers() {
+    updateSessionLayers(excludedEntity) {
         const session = this.xrManager.getSession();
         if (!(session === null || session === void 0 ? void 0 : session.renderState.layers)) {
             return;
         }
         // Projection layer is always the first entry
         const projLayer = session.renderState.layers[0];
-        const layers = projLayer ? [projLayer] : [];
+        if (!projLayer) {
+            return;
+        }
+        const layers = [projLayer];
         for (const entity of this.queries.activeLayers.entities) {
+            if (entity === excludedEntity) {
+                continue;
+            }
             const xrLayer = XRLayerState.data.xrLayer[entity.index];
-            if (xrLayer) {
+            const mesh = XRLayerState.data.mesh[entity.index];
+            const visible = mesh != null && isObjectTreeVisible(mesh);
+            this.layerVisibility.set(entity.index, visible);
+            if (xrLayer &&
+                visible &&
+                !this.pendingNativeLayerRemovals.has(entity.index)) {
                 layers.push(xrLayer);
             }
         }
@@ -268,48 +435,98 @@ class XRLayerSystem extends createSystem({
     // Per-frame rendering
     // ---------------------------------------------------------------------------
     renderLayers() {
+        var _a, _b;
+        if (this.sessionLayerInitializationPending) {
+            this.tryInitializeSessionLayers();
+        }
         const renderer = this.renderer;
         const savedRenderTarget = renderer.getRenderTarget();
-        // Disable XR so renderer.render() uses the layer's own camera
-        // instead of the headset-tracked XR cameras.
         const savedXrEnabled = renderer.xr.enabled;
-        renderer.xr.enabled = false;
-        // Save clear color so we can clear layers to transparent
+        // Save clear color so we can clear layers to transparent.
         renderer.getClearColor(_clearColor);
         const savedClearAlpha = renderer.getClearAlpha();
-        renderer.setClearColor(0x000000, 0);
-        for (const entity of this.queries.activeLayers.entities) {
-            const isQuad = !!XRLayerState.data.isQuad[entity.index];
-            const component = isQuad ? XRQuadLayer : XRCylinderLayer;
-            const callback = entity.getValue(component, 'renderCallback');
-            if (!callback) {
-                continue;
-            }
-            const xrLayer = XRLayerState.data.xrLayer[entity.index];
-            const mesh = XRLayerState.data.mesh[entity.index];
-            const renderTarget = XRLayerState.data.renderTarget[entity.index];
-            if (this.sessionUsesLayers && xrLayer) {
-                // XR path: sync native layer transform and render to its texture
-                const binding = this.xrManager.getBinding();
-                const frame = this.xrFrame;
-                if (!binding || !frame) {
+        try {
+            // Disable XR so renderer.render() uses the layer-specific camera instead of
+            // the headset-tracked XR cameras.
+            renderer.xr.enabled = false;
+            renderer.setClearColor(0x000000, 0);
+            this.renderRetiredLayers(renderer);
+            for (const entity of this.queries.activeLayers.entities) {
+                const isQuad = !!XRLayerState.data.isQuad[entity.index];
+                const component = isQuad ? XRQuadLayer : XRCylinderLayer;
+                let xrLayer = XRLayerState.data.xrLayer[entity.index];
+                const mesh = XRLayerState.data.mesh[entity.index];
+                this.syncLayerGeometry(entity, mesh, isQuad);
+                const visible = isObjectTreeVisible(mesh);
+                if (this.layerVisibility.get(entity.index) !== visible) {
+                    this.layerVisibility.set(entity.index, visible);
+                    if (this.sessionUsesLayers && xrLayer) {
+                        this.updateSessionLayers();
+                    }
+                }
+                if (this.sessionUsesLayers && xrLayer) {
+                    // An unsupported live transform queues removal. Keep the old native
+                    // surface valid until that pending render state becomes active.
+                    this.syncLayerTransform(xrLayer, mesh, entity);
+                }
+                if (this.sessionUsesLayers &&
+                    !xrLayer &&
+                    this.shouldRetryNativeLayer(entity, mesh, isQuad) &&
+                    this.activateNativeLayer(entity)) {
+                    xrLayer = XRLayerState.data.xrLayer[entity.index];
+                    this.updateSessionLayers();
+                }
+                let nativeActive = this.sessionUsesLayers &&
+                    xrLayer != null &&
+                    ((_b = (_a = this.xrManager.getSession()) === null || _a === void 0 ? void 0 : _a.renderState.layers) === null || _b === void 0 ? void 0 : _b.includes(xrLayer));
+                if (xrLayer &&
+                    this.pendingNativeLayerRemovals.has(entity.index) &&
+                    !nativeActive) {
+                    this.deactivateNativeLayer(entity);
+                    xrLayer = null;
+                    nativeActive = false;
+                }
+                if (nativeActive && xrLayer) {
+                    this.useNativeSurface(entity, mesh);
+                }
+                else {
+                    this.useFallbackSurface(entity, mesh);
+                }
+                const callback = entity.getValue(component, 'renderCallback');
+                if (!visible && !nativeActive) {
                     continue;
                 }
-                this.syncLayerTransform(xrLayer, mesh, entity);
-                const subImage = binding.getSubImage(xrLayer, frame);
-                renderer.setRenderTargetTextures(renderTarget, subImage.colorTexture, undefined);
-                renderer.setRenderTarget(renderTarget);
-            }
-            else {
-                // Fallback path: render to the internal render target
-                renderer.setRenderTarget(renderTarget);
+                const renderTarget = XRLayerState.data.renderTarget[entity.index];
+                if (nativeActive && xrLayer) {
+                    const binding = this.xrManager.getBinding();
+                    const frame = this.xrFrame;
+                    if (!binding || !frame) {
+                        continue;
+                    }
+                    const subImage = binding.getSubImage(xrLayer, frame);
+                    renderer.setRenderTargetTextures(renderTarget, subImage.colorTexture, undefined);
+                    renderer.setRenderTarget(renderTarget);
+                    if (!visible) {
+                        // A hidden layer remains in the current render state until the next
+                        // XR frame. Clear it now so that pending removal cannot expose the
+                        // previous frame's stale content.
+                        renderer.clear(true, true, true);
+                        continue;
+                    }
+                }
+                else {
+                    renderer.setRenderTarget(renderTarget);
+                }
+                callback === null || callback === void 0 ? void 0 : callback();
             }
-            callback();
         }
-        // Restore renderer state
-        renderer.setClearColor(_clearColor, savedClearAlpha);
-        renderer.xr.enabled = savedXrEnabled;
-        renderer.setRenderTarget(savedRenderTarget);
+        finally {
+            // Never leak layer-rendering state into the application render, even
+            // when a binding or user render callback throws.
+            renderer.setClearColor(_clearColor, savedClearAlpha);
+            renderer.xr.enabled = savedXrEnabled;
+            renderer.setRenderTarget(savedRenderTarget);
+        }
     }
     // ---------------------------------------------------------------------------
     // Helpers
@@ -319,25 +536,182 @@ class XRLayerSystem extends createSystem({
      * avoiding per-frame XRRigidTransform allocations for static layers.
      */
     syncLayerTransform(xrLayer, mesh, entity) {
-        mesh.updateMatrixWorld(true);
-        mesh.getWorldPosition(_position);
-        mesh.getWorldQuaternion(_quaternion);
+        const hasSupportedTransform = resolveLayerReferencePose(mesh, this.player, _position, _quaternion, _scale, _relativeMatrix);
+        const isQuad = !!XRLayerState.data.isQuad[entity.index];
+        this.readLayerConfiguration(entity, isQuad, _configuration);
         const cached = XRLayerState.data.cachedTransform[entity.index];
-        if ((cached === null || cached === void 0 ? void 0 : cached.position.equals(_position)) &&
-            cached.quaternion.equals(_quaternion)) {
-            return;
+        if (hasSupportedTransform &&
+            (cached === null || cached === void 0 ? void 0 : cached.position.equals(_position)) &&
+            cached.quaternion.equals(_quaternion) &&
+            cached.scale.equals(_scale) &&
+            sameVector(cached.configuration, _configuration)) {
+            this.restorePendingNativeLayer(entity);
+            return true;
         }
+        if (isQuad) {
+            const dimensions = hasSupportedTransform
+                ? resolveQuadLayerDimensions(_configuration.x, _configuration.y, _scale)
+                : null;
+            if (!dimensions) {
+                this.rememberUnsupportedLayer(entity, 'quad');
+                this.requestNativeLayerRemoval(entity);
+                return false;
+            }
+            xrLayer.width = dimensions.width;
+            xrLayer.height = dimensions.height;
+        }
+        else {
+            const dimensions = hasSupportedTransform
+                ? resolveCylinderLayerDimensions(_configuration.x, _configuration.y, _scale)
+                : null;
+            if (!dimensions || !isValidCylinderLayerAngle(_configuration.z)) {
+                this.rememberUnsupportedLayer(entity, 'cylinder');
+                this.requestNativeLayerRemoval(entity);
+                return false;
+            }
+            xrLayer.radius = dimensions.radius;
+            xrLayer.aspectRatio = dimensions.aspectRatio;
+            xrLayer.centralAngle = _configuration.z;
+        }
+        this.restorePendingNativeLayer(entity);
         xrLayer.transform = toRigidTransform(_position, _quaternion);
         if (cached) {
             cached.position.copy(_position);
             cached.quaternion.copy(_quaternion);
+            cached.scale.copy(_scale);
+            cached.configuration.copy(_configuration);
         }
         else {
             entity.setValue(XRLayerState, 'cachedTransform', {
                 position: _position.clone(),
                 quaternion: _quaternion.clone(),
+                scale: _scale.clone(),
+                configuration: _configuration.clone(),
             });
         }
+        return true;
+    }
+    requestNativeLayerRemoval(entity) {
+        if (this.pendingNativeLayerRemovals.has(entity.index)) {
+            return;
+        }
+        this.pendingNativeLayerRemovals.add(entity.index);
+        this.updateSessionLayers();
+    }
+    restorePendingNativeLayer(entity) {
+        this.unsupportedLayerStates.delete(entity.index);
+        if (!this.pendingNativeLayerRemovals.delete(entity.index)) {
+            return;
+        }
+        this.updateSessionLayers();
+    }
+    readLayerConfiguration(entity, isQuad, target) {
+        if (isQuad) {
+            target.set(entity.getValue(XRQuadLayer, 'width'), entity.getValue(XRQuadLayer, 'height'), 0);
+            return;
+        }
+        target.set(entity.getValue(XRCylinderLayer, 'radius'), entity.getValue(XRCylinderLayer, 'aspectRatio'), entity.getValue(XRCylinderLayer, 'centralAngle'));
+    }
+    syncLayerGeometry(entity, mesh, isQuad) {
+        this.readLayerConfiguration(entity, isQuad, _configuration);
+        const cached = this.layerConfigurations.get(entity.index);
+        if (cached && sameVector(cached, _configuration)) {
+            return;
+        }
+        this.layerConfigurations.set(entity.index, _configuration.clone());
+        // The fallback must reflect every live configuration, including values
+        // that a native composition layer cannot represent. Collapse non-finite
+        // dimensions to a safe degenerate geometry instead of leaving the last
+        // valid (and therefore misleading) shape on screen.
+        const geometry = this.createFallbackGeometry(entity, isQuad);
+        const oldGeometry = mesh.geometry;
+        mesh.geometry = geometry;
+        oldGeometry.dispose();
+    }
+    createFallbackGeometry(entity, isQuad) {
+        this.readLayerConfiguration(entity, isQuad, _configuration);
+        if (isQuad) {
+            const width = Number.isFinite(_configuration.x) ? _configuration.x : 0;
+            const height = Number.isFinite(_configuration.y) ? _configuration.y : 0;
+            return new PlaneGeometry(width, height);
+        }
+        const radius = Number.isFinite(_configuration.x) ? _configuration.x : 0;
+        const centralAngle = Number.isFinite(_configuration.z)
+            ? _configuration.z
+            : 0;
+        const rawHeight = (_configuration.x * _configuration.z) / _configuration.y;
+        const height = Number.isFinite(rawHeight) ? rawHeight : 0;
+        return new CylinderGeometry(radius, radius, height, 64, 64, true, Math.PI - centralAngle / 2, centralAngle);
+    }
+    shouldRetryNativeLayer(entity, mesh, isQuad) {
+        const unsupported = this.unsupportedLayerStates.get(entity.index);
+        if (!unsupported) {
+            return true;
+        }
+        const hasSupportedTransform = resolveLayerReferencePose(mesh, this.player, _position, _quaternion, _scale, _relativeMatrix);
+        this.readLayerConfiguration(entity, isQuad, _configuration);
+        const hasSupportedConfiguration = isQuad
+            ? resolveQuadLayerDimensions(_configuration.x, _configuration.y, _scale) != null
+            : resolveCylinderLayerDimensions(_configuration.x, _configuration.y, _scale) != null && isValidCylinderLayerAngle(_configuration.z);
+        // Approximate cache equality suppresses repeated work while a layer stays
+        // unsupported. Never let that tolerance hide a boundary crossing back to
+        // a representable native layer.
+        if (hasSupportedTransform && hasSupportedConfiguration) {
+            return true;
+        }
+        return (!sameVector(unsupported.configuration, _configuration) ||
+            this.hasLayerShapeChanged(unsupported.relativeMatrix, _relativeMatrix));
+    }
+    hasLayerShapeChanged(previous, current) {
+        const previousElements = previous.elements;
+        const currentElements = current.elements;
+        const previousFinite = previousElements.every(Number.isFinite);
+        const currentFinite = currentElements.every(Number.isFinite);
+        if (!previousFinite || !currentFinite) {
+            return previousElements.some((value, index) => !sameNumber(value, currentElements[index]));
+        }
+        const gram = (elements) => {
+            const xx = elements[0] ** 2 + elements[1] ** 2 + elements[2] ** 2;
+            const yy = elements[4] ** 2 + elements[5] ** 2 + elements[6] ** 2;
+            const zz = elements[8] ** 2 + elements[9] ** 2 + elements[10] ** 2;
+            const normalizeDot = (dot, first, second) => {
+                const denominator = Math.sqrt(first * second);
+                return denominator === 0 ? dot : dot / denominator;
+            };
+            return [
+                xx,
+                yy,
+                zz,
+                normalizeDot(elements[0] * elements[4] +
+                    elements[1] * elements[5] +
+                    elements[2] * elements[6], xx, yy),
+                normalizeDot(elements[0] * elements[8] +
+                    elements[1] * elements[9] +
+                    elements[2] * elements[10], xx, zz),
+                normalizeDot(elements[4] * elements[8] +
+                    elements[5] * elements[9] +
+                    elements[6] * elements[10], yy, zz),
+            ];
+        };
+        const previousGram = gram(previousElements);
+        const currentGram = gram(currentElements);
+        const nearlyEqual = (a, b, index) => {
+            const tolerance = index < 3
+                ? 1e-10 * Math.max(Number.EPSILON, Math.abs(a), Math.abs(b))
+                : 1e-10;
+            return Math.abs(a - b) <= tolerance;
+        };
+        return (previousGram.some((value, index) => !nearlyEqual(value, currentGram[index], index)) ||
+            Math.sign(previous.determinant()) !== Math.sign(current.determinant()));
+    }
+    rememberUnsupportedLayer(entity, type) {
+        if (!this.unsupportedLayerStates.has(entity.index)) {
+            console.warn(`[XRLayerSystem] ${type} layer ${entity.index} has unsupported dimensions or a non-finite, reflected, or sheared transform; using projection fallback.`);
+        }
+        this.unsupportedLayerStates.set(entity.index, {
+            relativeMatrix: _relativeMatrix.clone(),
+            configuration: _configuration.clone(),
+        });
     }
     createRenderTarget(width, height, stencil) {
         return new WebGLRenderTarget(width, height, {