@fps-games/editor 0.2.0-beta.4 → 0.2.1-beta.2

package/node_modules/@fps-games/babylon-renderer/dist/shadows/shadow-map-experiment-system.js

@@ -0,0 +1,2735 @@
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight.js';
+import { ShadowGenerator } from '@babylonjs/core/Lights/Shadows/shadowGenerator.js';
+import './shadow-generator-shaders.js';
+import { Matrix, Vector3 } from '@babylonjs/core/Maths/math.vector.js';
+import { createShadowMapExperimentPlanSnapshot, createShadowMapExperimentPlanFingerprint, createShadowMapExperimentActivityScheduler, createShadowMapExperimentDepthRefreshScheduler, createShadowMapExperimentInfluenceCullingState, createShadowMapExperimentRegistry, diffShadowMapExperimentPlans, shadowMapExperimentDepthLayerForUpdateClass, } from '@fps-games/playable-rendering/runtime';
+import { createBabylonShadowMapExperimentDepthBackend, createBabylonShadowMapExperimentSingleDepthBackend, readBabylonShadowMapExperimentAllocationCleanup, } from './shadow-map-experiment-depth-backend.js';
+import '@babylonjs/core/Lights/Shadows/shadowGeneratorSceneComponent.js';
+export function readBabylonShadowMapExperimentSystemCleanup(error) {
+    if (!error || (typeof error !== 'object' && typeof error !== 'function'))
+        return null;
+    const cleanup = error.shadowMapExperimentSystemCleanup;
+    return typeof cleanup === 'function' ? cleanup : null;
+}
+export function readBabylonRuntimeShadowObjectsRecoveryOwner(error) {
+    if (!error || (typeof error !== 'object' && typeof error !== 'function'))
+        return null;
+    const owner = error.runtimeShadowObjectsRecoveryOwner;
+    return owner && typeof owner === 'object' && typeof owner.dispose === 'function'
+        ? owner
+        : null;
+}
+export function createBabylonShadowMapExperimentSystem(scene, initialPlan = null, options = {}) {
+    let disposed = false;
+    let disposing = false;
+    let sourcePlan = null;
+    let plan = null;
+    let runtimeOverlayRevision = 0;
+    let lightState = null;
+    let generator = null;
+    let depthBackend = null;
+    let registry = null;
+    let previousSceneShadowsEnabled = null;
+    let refreshCount = 0;
+    let lastRefreshReasons = Object.freeze([]);
+    const activityScheduler = createShadowMapExperimentActivityScheduler();
+    const depthRefreshScheduler = createShadowMapExperimentDepthRefreshScheduler();
+    const influenceCulling = createShadowMapExperimentInfluenceCullingState(0.25);
+    const candidateLayerByMesh = new Map();
+    const candidateMeshCounts = { static: 0, dynamic: 0 };
+    const meshDataCacheByMesh = new Map();
+    const conservativeCasterMeshes = new Set();
+    const pendingMeshObserverCleanups = new Map();
+    const pendingMeshRegistrationRollbacks = new Set();
+    const pendingSceneMeshRegistrations = new Set();
+    const pendingMeshUnregistrations = new Set();
+    const pendingRenderableMembershipRetries = new Set();
+    const pendingTransformMembershipRetries = new Set();
+    const activeCasterEntityIds = new Set();
+    const activeDeformationSourceCountByEntity = new Map();
+    const eligibleActiveDeformationEntityIds = new Set();
+    const pendingFinalDeformationEntityIds = new Set();
+    const pendingDeformationInvalidations = new Map();
+    const pendingMembershipInvalidationLayers = new Set();
+    const pendingCompositeRefreshReasons = new Set();
+    const fallbackWarnings = new Set();
+    let pendingBackendAllocationCleanup = null;
+    let pendingFallbackReason = null;
+    let pendingCoverageMembershipRebuild = false;
+    let cullingStable = false;
+    let lastCullingInvalidationReason = null;
+    let effectiveCoverageCenter = null;
+    let effectiveCoverageExtent = null;
+    let effectiveCoverageNear = null;
+    let effectiveCoverageFar = null;
+    const objectByEntity = new Map();
+    const objectByRenderable = new Map();
+    const meshesByRenderable = new Map();
+    const bindings = new Map();
+    const receiverStates = new Map();
+    const receiverTargetByMesh = new Map();
+    const diagnostics = [];
+    const diagnosticKeys = new Set();
+    const runtimeRegistrations = new Map();
+    const automaticAnimationGroups = new Map();
+    let flushingRefresh = false;
+    const assertUsable = (allowDisposing = false) => {
+        if (disposed || (disposing && !allowDisposing))
+            throw new Error('shadowMapExperiment.systemDisposed');
+    };
+    const rememberDiagnostic = (code, message, identity = {}) => {
+        const key = `${code}\u0000${identity.entityId ?? ''}\u0000${identity.renderableId ?? ''}`;
+        if (diagnosticKeys.has(key))
+            return;
+        diagnosticKeys.add(key);
+        diagnostics.push({ code, message, ...identity });
+    };
+    const requireRuntimeProfile = (basePlan, behaviorProfileId, entityId) => {
+        if (!basePlan || basePlan.schemaVersion !== 3) {
+            const code = 'shadowMapExperiment.runtimeProfileCatalogUnavailable';
+            rememberDiagnostic(code, 'Plan v3 behavior profile catalog is required for runtime shadow registration.', { entityId });
+            throw new Error(`${code}:plan-v${basePlan?.schemaVersion ?? 'none'}`);
+        }
+        const profile = basePlan.behaviorProfiles[behaviorProfileId];
+        if (!profile) {
+            const code = 'shadowMapExperiment.runtimeBehaviorProfileUnknown';
+            rememberDiagnostic(code, `Unknown runtime behavior profile: ${behaviorProfileId}`, { entityId });
+            throw new Error(`${code}:${behaviorProfileId}`);
+        }
+        if (profile.updateClass === 'auto') {
+            const code = 'shadowMapExperiment.runtimeBehaviorProfileAutoUnsupported';
+            rememberDiagnostic(code, `Runtime behavior profile ${behaviorProfileId} must declare a deterministic updateClass.`, { entityId });
+            throw new Error(`${code}:${behaviorProfileId}`);
+        }
+        return profile;
+    };
+    const composeEffectivePlan = (basePlan, records, overlayRevision) => {
+        if (!basePlan) {
+            if (records.length > 0)
+                throw new Error('shadowMapExperiment.runtimePlanUnavailable');
+            return null;
+        }
+        if (records.length === 0)
+            return basePlan;
+        const runtimeObjects = records.map(record => {
+            const profile = requireRuntimeProfile(basePlan, record.behaviorProfileId, record.entityId);
+            if (record.activities.length > 0 && (!profile.cast || profile.updateClass === 'static')) {
+                throw new Error(`shadowMapExperiment.runtimeActivityProfileIneligible:${record.behaviorProfileId}`);
+            }
+            return Object.freeze({
+                entityId: record.entityId,
+                renderableIds: Object.freeze(record.renderables.map(renderable => renderable.renderableId).sort()),
+                cast: profile.cast,
+                receive: profile.receive,
+                updateClass: profile.updateClass,
+                behaviorProfileId: record.behaviorProfileId,
+            });
+        });
+        return createShadowMapExperimentPlanSnapshot({
+            ...basePlan,
+            revision: basePlan.revision + overlayRevision,
+            objects: [...basePlan.objects, ...runtimeObjects].sort((left, right) => left.entityId.localeCompare(right.entityId)),
+        });
+    };
+    const requestRefreshFrame = (reason) => {
+        if (disposed || disposing || flushingRefresh || !options.requestFrame)
+            return;
+        try {
+            options.requestFrame(reason);
+        }
+        catch (error) {
+            const code = 'shadowMapExperiment.frameRequestFailed';
+            if (diagnosticKeys.has(code))
+                return;
+            diagnosticKeys.add(code);
+            diagnostics.push({
+                code,
+                message: `Shadow refresh frame request failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    };
+    const enqueueRefresh = (reason) => {
+        activityScheduler.markDirty(reason);
+        requestRefreshFrame(`shadow-map-experiment-${reason}`);
+    };
+    const markDepthDirty = (layer, reason) => {
+        depthRefreshScheduler.markDirty(layer, reason);
+        requestRefreshFrame(`shadow-map-experiment-${reason}`);
+    };
+    const markAllDepthDirty = (reason) => {
+        depthRefreshScheduler.markAllDirty(reason);
+        requestRefreshFrame(`shadow-map-experiment-${reason}`);
+    };
+    const syncSceneFitCoverage = (force = false) => {
+        if (!plan?.enabled || !lightState || options.coverageMode !== 'scene-fit')
+            return;
+        const sceneBounds = collectActiveCasterWorldBounds(bindings, registry);
+        if (!sceneBounds)
+            return;
+        const nextCoverage = createSceneFitCoverage(plan, sceneBounds);
+        const currentCenter = effectiveCoverageCenter ?? plan.generator.bounds.center;
+        const currentExtent = effectiveCoverageExtent ?? plan.generator.bounds.extent;
+        const currentNear = effectiveCoverageNear ?? plan.generator.bounds.near;
+        const currentFar = effectiveCoverageFar ?? plan.generator.bounds.far;
+        if (!force
+            && areTuple3Equal(currentCenter, nextCoverage.center)
+            && areTuple3Equal(currentExtent, nextCoverage.extent)
+            && currentNear === nextCoverage.near
+            && currentFar === nextCoverage.far)
+            return;
+        effectiveCoverageCenter = nextCoverage.center;
+        effectiveCoverageExtent = nextCoverage.extent;
+        effectiveCoverageNear = nextCoverage.near;
+        effectiveCoverageFar = nextCoverage.far;
+        configureLight(lightState.light, plan, nextCoverage);
+        pendingCoverageMembershipRebuild = true;
+        lastCullingInvalidationReason = 'scene-fit-coverage-changed';
+        markAllDepthDirty('camera-influence-region-changed');
+    };
+    const handleCompositorLifecycleEvent = (event) => {
+        if (disposed || disposing)
+            return;
+        if (event === 'ready')
+            markAllDepthDirty('compositor-ready');
+        else
+            requestRefreshFrame(`shadow-map-experiment-compositor-${event}`);
+    };
+    const routeDirtyReason = (reason) => {
+        if (isDynamicDirtyReason(reason)) {
+            depthRefreshScheduler.markDirty('dynamic', reason);
+            return;
+        }
+        if (isStaticDirtyReason(reason)) {
+            depthRefreshScheduler.markDirty('static', reason);
+            return;
+        }
+        depthRefreshScheduler.markAllDirty(reason);
+    };
+    const syncCandidateCounts = () => {
+        depthBackend?.setCandidateCounts(candidateMeshCounts.static, candidateMeshCounts.dynamic);
+    };
+    const setCandidateLayer = (mesh, nextLayer) => {
+        const previousLayer = candidateLayerByMesh.get(mesh) ?? null;
+        if (previousLayer === nextLayer)
+            return;
+        if (previousLayer)
+            candidateMeshCounts[previousLayer] -= 1;
+        if (nextLayer) {
+            candidateLayerByMesh.set(mesh, nextLayer);
+            candidateMeshCounts[nextLayer] += 1;
+        }
+        else {
+            candidateLayerByMesh.delete(mesh);
+        }
+    };
+    const warnForFallback = (reason) => {
+        if (fallbackWarnings.has(reason))
+            return;
+        fallbackWarnings.add(reason);
+        console.warn(`[shadow-map-experiment] split backend unavailable; using single ShadowMap (${reason})`);
+    };
+    const flushRefresh = () => {
+        if (disposed || disposing)
+            return;
+        let postFlushFrameReason = null;
+        flushingRefresh = true;
+        try {
+            syncAutomaticAnimationGroupStates();
+            flushPendingBackendAllocationCleanup();
+            recoverPendingFallbackBackend();
+            if (!depthBackend || !registry)
+                return;
+            downgradeFailedSplitBackend();
+            if (!depthBackend)
+                return;
+            flushPendingMeshUnregistrations();
+            flushPendingSceneMeshRegistrations();
+            flushPendingRenderableMembershipRetries();
+            flushPendingTransformMembershipRetries();
+            syncSceneFitCoverage();
+            updateCameraInfluenceCoverage();
+            flushMembershipInvalidations();
+            registry.consumeDirtyReasons();
+            const activityDecision = activityScheduler.consumeFrameDecision();
+            resyncActivityDeformationMembership(activityDecision.reasons);
+            for (const reason of activityDecision.reasons)
+                routeDirtyReason(reason);
+            const decision = depthRefreshScheduler.consumeFrameDecision();
+            let refreshDecision = decision;
+            if (options.requestFrame && depthBackend.mode === 'split-static-dynamic') {
+                const settlementReasons = Object.freeze([...pendingCompositeRefreshReasons]);
+                pendingCompositeRefreshReasons.clear();
+                for (const reason of decision.composite.reasons)
+                    pendingCompositeRefreshReasons.add(reason);
+                refreshDecision = Object.freeze({
+                    static: decision.static,
+                    dynamic: decision.dynamic,
+                    composite: Object.freeze({
+                        shouldRefresh: settlementReasons.length > 0,
+                        reasons: settlementReasons,
+                    }),
+                });
+                if (pendingCompositeRefreshReasons.size > 0) {
+                    postFlushFrameReason = 'shadow-map-experiment-composite-settlement';
+                }
+            }
+            else if (pendingCompositeRefreshReasons.size > 0) {
+                const compositeReasons = Object.freeze([
+                    ...new Set([...pendingCompositeRefreshReasons, ...decision.composite.reasons]),
+                ]);
+                pendingCompositeRefreshReasons.clear();
+                refreshDecision = Object.freeze({
+                    static: decision.static,
+                    dynamic: decision.dynamic,
+                    composite: Object.freeze({ shouldRefresh: true, reasons: compositeReasons }),
+                });
+            }
+            if (!refreshDecision.static.shouldRefresh
+                && !refreshDecision.dynamic.shouldRefresh
+                && !refreshDecision.composite.shouldRefresh)
+                return;
+            depthBackend.refresh(refreshDecision);
+            if (!refreshDecision.composite.shouldRefresh)
+                return;
+            registry.markShadowRendered();
+            refreshCount += 1;
+            lastRefreshReasons = refreshDecision.composite.reasons;
+        }
+        finally {
+            flushingRefresh = false;
+            if (postFlushFrameReason)
+                requestRefreshFrame(postFlushFrameReason);
+        }
+    };
+    const syncDeformationActivityEligibility = (entityId) => {
+        if (activeCasterEntityIds.has(entityId)
+            && (activeDeformationSourceCountByEntity.get(entityId) ?? 0) > 0) {
+            eligibleActiveDeformationEntityIds.add(entityId);
+        }
+        else {
+            eligibleActiveDeformationEntityIds.delete(entityId);
+        }
+    };
+    const syncActivityEligibility = (entityId) => {
+        const object = objectByEntity.get(entityId);
+        const active = object?.renderableIds.some(renderableId => registry?.getRecord(renderableId)?.state === 'active') === true;
+        activityScheduler.setEntityActive(entityId, active);
+        if (active)
+            activeCasterEntityIds.add(entityId);
+        else
+            activeCasterEntityIds.delete(entityId);
+        syncDeformationActivityEligibility(entityId);
+    };
+    const shouldRetainCaster = (mesh, updateClass) => {
+        if (plan?.culling.enabled === false) {
+            conservativeCasterMeshes.delete(mesh);
+            return true;
+        }
+        const deformable = isDeformableCaster(mesh, updateClass);
+        const bounds = readCasterWorldBounds(mesh, deformable, deformable
+            ? meshDataCacheByMesh.get(mesh) ?? createMeshDataCache(mesh, meshDataCacheByMesh)
+            : null);
+        if (!bounds) {
+            conservativeCasterMeshes.add(mesh);
+            const binding = bindings.get(mesh);
+            const code = deformable
+                ? 'shadowMapExperiment.deformationBoundsUnavailable'
+                : 'shadowMapExperiment.casterBoundsUnavailable';
+            const key = `${code}:${mesh.uniqueId}`;
+            if (!diagnosticKeys.has(key)) {
+                diagnosticKeys.add(key);
+                diagnostics.push({
+                    code,
+                    message: deformable
+                        ? 'Deformed caster bounds were unavailable, so influence culling retained the caster conservatively.'
+                        : 'Caster bounds were unavailable, so influence culling retained the caster conservatively.',
+                    entityId: binding?.entityId,
+                    renderableId: binding?.renderableId,
+                });
+            }
+        }
+        else {
+            conservativeCasterMeshes.delete(mesh);
+        }
+        return influenceCulling.shouldRetainCaster({
+            casterBounds: bounds,
+            lightDirection: plan?.light.direction ?? null,
+            projectionDistance: plan
+                ? Math.max(0, (effectiveCoverageFar ?? plan.generator.bounds.far)
+                    - (effectiveCoverageNear ?? plan.generator.bounds.near))
+                : 0,
+        });
+    };
+    const resyncActivityDeformationMembership = (reasons) => {
+        const hasDeformationFrame = reasons.includes('skinned-animation-frame')
+            || reasons.includes('morph-animation-frame');
+        const finalEntityIds = [...pendingFinalDeformationEntityIds];
+        const deformationInvalidations = [...pendingDeformationInvalidations.entries()];
+        if (!hasDeformationFrame && finalEntityIds.length === 0 && deformationInvalidations.length === 0)
+            return;
+        const renderableIds = new Set();
+        if (hasDeformationFrame) {
+            for (const entityId of eligibleActiveDeformationEntityIds) {
+                const object = objectByEntity.get(entityId);
+                if (!object)
+                    continue;
+                for (const renderableId of object.renderableIds)
+                    renderableIds.add(renderableId);
+            }
+        }
+        if (finalEntityIds.length > 0) {
+            for (const entityId of finalEntityIds) {
+                if (!activeCasterEntityIds.has(entityId))
+                    continue;
+                const object = objectByEntity.get(entityId);
+                if (!object)
+                    continue;
+                for (const renderableId of object.renderableIds)
+                    renderableIds.add(renderableId);
+            }
+        }
+        for (const [entityId] of deformationInvalidations) {
+            if (!activeCasterEntityIds.has(entityId))
+                continue;
+            const object = objectByEntity.get(entityId);
+            if (!object)
+                continue;
+            for (const renderableId of object.renderableIds)
+                renderableIds.add(renderableId);
+        }
+        for (const renderableId of renderableIds)
+            syncCaster(renderableId);
+        for (const entityId of finalEntityIds)
+            pendingFinalDeformationEntityIds.delete(entityId);
+        if (finalEntityIds.length > 0) {
+            markDepthDirty('dynamic', 'caster-activity-stopped');
+        }
+        for (const [entityId, invalidationReasons] of deformationInvalidations) {
+            pendingDeformationInvalidations.delete(entityId);
+            for (const reason of invalidationReasons)
+                markDepthDirty('dynamic', reason);
+        }
+    };
+    const resyncAllCasterMembership = () => {
+        const beforeStatic = depthBackend?.getEvidence().static.retainedMeshCount ?? 0;
+        const beforeDynamic = depthBackend?.getEvidence().dynamic.retainedMeshCount ?? 0;
+        for (const renderableId of meshesByRenderable.keys())
+            syncCaster(renderableId);
+        const after = depthBackend?.getEvidence();
+        const changed = [];
+        if (beforeStatic !== (after?.static.retainedMeshCount ?? 0))
+            changed.push('static');
+        if (beforeDynamic !== (after?.dynamic.retainedMeshCount ?? 0))
+            changed.push('dynamic');
+        return Object.freeze(changed);
+    };
+    const resyncLayerCasterMembership = (layer) => {
+        const renderableIds = new Set();
+        for (const [mesh, candidateLayer] of candidateLayerByMesh) {
+            if (candidateLayer !== layer)
+                continue;
+            const binding = bindings.get(mesh);
+            if (binding)
+                renderableIds.add(binding.renderableId);
+        }
+        for (const renderableId of renderableIds)
+            syncCaster(renderableId);
+    };
+    const flushMembershipInvalidations = () => {
+        for (const layer of pendingMembershipInvalidationLayers)
+            resyncLayerCasterMembership(layer);
+        pendingMembershipInvalidationLayers.clear();
+    };
+    const updateCameraInfluenceCoverage = () => {
+        if (!plan?.enabled)
+            return;
+        if (!plan.culling.enabled) {
+            cullingStable = true;
+            pendingCoverageMembershipRebuild = false;
+            return;
+        }
+        const camera = scene.activeCamera;
+        const decision = influenceCulling.updateCoverage({
+            cameraId: camera ? String(camera.uniqueId) : 'none',
+            projectionSignature: camera
+                ? `${readCameraProjectionSignature(camera, scene)}:${JSON.stringify({
+                    ...plan.generator.bounds,
+                    center: effectiveCoverageCenter ?? plan.generator.bounds.center,
+                    extent: effectiveCoverageExtent ?? plan.generator.bounds.extent,
+                    near: effectiveCoverageNear ?? plan.generator.bounds.near,
+                    far: effectiveCoverageFar ?? plan.generator.bounds.far,
+                })}`
+                : 'none',
+            visibleBounds: camera
+                ? calculateCameraShadowCoverage(camera, plan, effectiveCoverageCenter ?? plan.generator.bounds.center, effectiveCoverageExtent ?? plan.generator.bounds.extent)
+                : null,
+        });
+        const retryingMembershipRebuild = pendingCoverageMembershipRebuild;
+        cullingStable = !decision.rebuilt && !retryingMembershipRebuild;
+        if (!decision.rebuilt && !retryingMembershipRebuild)
+            return;
+        if (decision.rebuilt && !retryingMembershipRebuild) {
+            lastCullingInvalidationReason = 'camera-influence-region-changed';
+        }
+        let changedLayers;
+        try {
+            changedLayers = resyncAllCasterMembership();
+            pendingCoverageMembershipRebuild = false;
+        }
+        catch (error) {
+            pendingCoverageMembershipRebuild = true;
+            cullingStable = false;
+            throw error;
+        }
+        const dirtyLayers = retryingMembershipRebuild
+            ? Object.freeze(['static', 'dynamic'])
+            : changedLayers;
+        for (const layer of dirtyLayers) {
+            markDepthDirty(layer, 'camera-influence-region-changed');
+        }
+    };
+    const downgradeFailedSplitBackend = () => {
+        if (!depthBackend || depthBackend.mode !== 'split-static-dynamic' || !plan?.enabled || !lightState)
+            return;
+        const runtimeFailureReason = depthBackend.getRuntimeFailureReason();
+        if (!runtimeFailureReason)
+            return;
+        const failedBackend = depthBackend;
+        failedBackend.dispose();
+        depthBackend = null;
+        generator = null;
+        pendingFallbackReason = runtimeFailureReason;
+        recoverPendingFallbackBackend();
+    };
+    const rememberBackendAllocationCleanup = (error) => {
+        const cleanup = readBabylonShadowMapExperimentAllocationCleanup(error);
+        if (cleanup)
+            pendingBackendAllocationCleanup = cleanup;
+    };
+    const flushPendingBackendAllocationCleanup = () => {
+        if (!pendingBackendAllocationCleanup)
+            return;
+        const cleanupErrors = pendingBackendAllocationCleanup();
+        if (cleanupErrors.length > 0) {
+            throw Object.assign(new Error('shadowMapExperiment.backendAllocationCleanupFailed'), { cleanupErrors });
+        }
+        pendingBackendAllocationCleanup = null;
+    };
+    const prepareBackendCasterMembership = (backend) => {
+        let staticCandidateCount = 0;
+        let dynamicCandidateCount = 0;
+        for (const [mesh, layer] of candidateLayerByMesh) {
+            if (layer === 'static')
+                staticCandidateCount += 1;
+            else
+                dynamicCandidateCount += 1;
+            const binding = bindings.get(mesh);
+            const updateClass = binding ? objectByRenderable.get(binding.renderableId)?.updateClass : null;
+            if (!updateClass || shouldRetainCaster(mesh, updateClass))
+                backend.addCaster(mesh, layer);
+        }
+        backend.setCandidateCounts(staticCandidateCount, dynamicCandidateCount);
+    };
+    const recoverPendingFallbackBackend = () => {
+        if (!pendingFallbackReason || depthBackend || !plan?.enabled || !lightState)
+            return;
+        flushPendingBackendAllocationCleanup();
+        const fallbackReason = pendingFallbackReason;
+        if (plan.generator.backend.fallback === 'disable')
+            return;
+        let replacement = null;
+        try {
+            replacement = createBabylonShadowMapExperimentSingleDepthBackend(lightState.light, plan, fallbackReason);
+            prepareBackendCasterMembership(replacement);
+            depthBackend = replacement;
+            generator = replacement.generator;
+            pendingFallbackReason = null;
+        }
+        catch (error) {
+            rememberBackendAllocationCleanup(error);
+            if (replacement) {
+                const ownedReplacement = replacement;
+                try {
+                    ownedReplacement.dispose();
+                }
+                catch (cleanupError) {
+                    pendingBackendAllocationCleanup = () => {
+                        try {
+                            ownedReplacement.dispose();
+                            return Object.freeze([]);
+                        }
+                        catch (retryError) {
+                            return Object.freeze([retryError]);
+                        }
+                    };
+                    if (error && typeof error === 'object') {
+                        attachFailureMetadata(error, {
+                            fallbackPreparationCleanupErrors: Object.freeze([cleanupError]),
+                        });
+                    }
+                }
+            }
+            throw error;
+        }
+        warnForFallback(fallbackReason);
+        markAllDepthDirty('generator-created');
+    };
+    const syncCaster = (renderableId) => {
+        const record = registry?.getRecord(renderableId);
+        const meshes = meshesByRenderable.get(renderableId);
+        if (!depthBackend || !record || !meshes)
+            return;
+        const layer = shadowMapExperimentDepthLayerForUpdateClass(record.updateClass);
+        const shouldCast = record.state === 'active';
+        const changedLayers = new Set();
+        for (const mesh of meshes) {
+            const previousLayer = candidateLayerByMesh.get(mesh);
+            if (shouldCast && isMeshRuntimeVisible(mesh)) {
+                const retained = shouldRetainCaster(mesh, record.updateClass);
+                if (retained) {
+                    const wasRetained = depthBackend.hasCaster(mesh, layer);
+                    depthBackend.addCaster(mesh, layer);
+                    setCandidateLayer(mesh, layer);
+                    if (!wasRetained || previousLayer !== layer)
+                        changedLayers.add(layer);
+                    if (previousLayer && previousLayer !== layer)
+                        changedLayers.add(previousLayer);
+                }
+                else {
+                    const wasRetained = depthBackend.hasCaster(mesh);
+                    depthBackend.removeCaster(mesh);
+                    setCandidateLayer(mesh, layer);
+                    if (wasRetained)
+                        changedLayers.add(previousLayer ?? layer);
+                }
+            }
+            else {
+                const wasRetained = depthBackend.hasCaster(mesh);
+                depthBackend.removeCaster(mesh);
+                setCandidateLayer(mesh, null);
+                conservativeCasterMeshes.delete(mesh);
+                if (wasRetained)
+                    changedLayers.add(previousLayer ?? layer);
+            }
+        }
+        syncCandidateCounts();
+        for (const changedLayer of changedLayers) {
+            markDepthDirty(changedLayer, 'caster-influence-membership-changed');
+        }
+        syncActivityEligibility(record.entityId);
+    };
+    const restoreReceiver = (mesh) => {
+        const target = receiverTargetByMesh.get(mesh) ?? resolveReceiverTarget(mesh);
+        receiverTargetByMesh.delete(mesh);
+        const state = receiverStates.get(target);
+        if (!state)
+            return;
+        state.requests.delete(mesh);
+        if (state.requests.size > 0) {
+            const next = [...state.requests.values()].some(Boolean);
+            state.ownedValue = next;
+            if (!isDisposed(target) && target.receiveShadows !== next)
+                target.receiveShadows = next;
+            return;
+        }
+        if (!isDisposed(target) && target.receiveShadows === state.ownedValue) {
+            target.receiveShadows = state.previousReceiveShadows;
+        }
+        receiverStates.delete(target);
+    };
+    const setReceiver = (mesh, enabled, renderableId) => {
+        const eligible = !enabled || isReceiverEligible(mesh);
+        const next = enabled && eligible;
+        const previousTarget = receiverTargetByMesh.get(mesh);
+        const target = resolveReceiverTarget(mesh);
+        if (previousTarget && previousTarget !== target)
+            restoreReceiver(mesh);
+        receiverTargetByMesh.set(mesh, target);
+        let state = receiverStates.get(target);
+        if (!state) {
+            state = {
+                mesh: target,
+                previousReceiveShadows: target.receiveShadows,
+                requests: new Map(),
+                ownedValue: next,
+            };
+            receiverStates.set(target, state);
+        }
+        state.requests.set(mesh, next);
+        const ownedValue = [...state.requests.values()].some(Boolean);
+        state.ownedValue = ownedValue;
+        if (target.receiveShadows !== ownedValue)
+            target.receiveShadows = ownedValue;
+        if (enabled && !eligible) {
+            const code = 'shadowMapExperiment.transparentReceiver';
+            const key = `${code}:${renderableId}`;
+            if (!diagnosticKeys.has(key)) {
+                diagnosticKeys.add(key);
+                diagnostics.push({
+                    code,
+                    message: 'Receiver was excluded because its current material is not shadow-receiver eligible.',
+                    renderableId,
+                });
+            }
+        }
+    };
+    const syncRenderable = (renderableId) => {
+        const meshes = meshesByRenderable.get(renderableId);
+        const object = objectByRenderable.get(renderableId);
+        if (!meshes || !object || !registry)
+            return;
+        const visible = [...meshes].some(isMeshRuntimeVisible);
+        const previousRecord = registry.getRecord(renderableId);
+        const nextRecord = previousRecord?.renderableReady
+            ? registry.setVisible(renderableId, visible)
+            : registry.attach(renderableId, visible);
+        if (previousRecord?.state === 'active'
+            && nextRecord?.state !== 'active'
+            && registry.snapshot().activeCasterCount === 0) {
+            registry.markDirty('empty-list-clear');
+            markDepthDirty(shadowMapExperimentDepthLayerForUpdateClass(object.updateClass), 'empty-list-clear');
+        }
+        for (const mesh of meshes)
+            setReceiver(mesh, object.receive, renderableId);
+        try {
+            syncCaster(renderableId);
+            pendingRenderableMembershipRetries.delete(renderableId);
+        }
+        catch (error) {
+            pendingRenderableMembershipRetries.add(renderableId);
+            throw error;
+        }
+    };
+    const flushPendingRenderableMembershipRetries = () => {
+        for (const renderableId of [...pendingRenderableMembershipRetries]) {
+            if (!objectByRenderable.has(renderableId) || !meshesByRenderable.has(renderableId)) {
+                pendingRenderableMembershipRetries.delete(renderableId);
+                continue;
+            }
+            syncCaster(renderableId);
+            pendingRenderableMembershipRetries.delete(renderableId);
+            enqueueRefresh('caster-visibility-changed');
+        }
+    };
+    const syncMatrixObserver = (binding) => {
+        const object = objectByRenderable.get(binding.renderableId);
+        if (!object?.cast) {
+            if (binding.matrixObserver)
+                binding.mesh.onAfterWorldMatrixUpdateObservable.remove(binding.matrixObserver);
+            binding.matrixObserver = null;
+            binding.worldMatrixSnapshot = null;
+            pendingTransformMembershipRetries.delete(binding.mesh);
+            return;
+        }
+        if (binding.matrixObserver)
+            return;
+        binding.worldMatrixSnapshot = readWorldMatrixSnapshot(binding.mesh);
+        binding.matrixObserver = binding.mesh.onAfterWorldMatrixUpdateObservable.add(() => {
+            if (disposed || disposing)
+                return;
+            const nextSnapshot = readWorldMatrixSnapshot(binding.mesh);
+            if (areMatrixSnapshotsEqual(binding.worldMatrixSnapshot, nextSnapshot))
+                return;
+            const currentObject = objectByRenderable.get(binding.renderableId);
+            if (!currentObject?.cast) {
+                binding.worldMatrixSnapshot = nextSnapshot;
+                return;
+            }
+            try {
+                syncCaster(binding.renderableId);
+            }
+            catch (error) {
+                pendingTransformMembershipRetries.add(binding.mesh);
+                throw error;
+            }
+            binding.worldMatrixSnapshot = nextSnapshot;
+            enqueueRefresh(currentObject.updateClass === 'static' ? 'static-transform-changed' : 'dynamic-transform-changed');
+        });
+    };
+    const flushPendingTransformMembershipRetries = () => {
+        for (const mesh of [...pendingTransformMembershipRetries]) {
+            const binding = bindings.get(mesh);
+            const currentObject = binding ? objectByRenderable.get(binding.renderableId) : null;
+            if (!binding || !currentObject?.cast) {
+                pendingTransformMembershipRetries.delete(mesh);
+                if (binding)
+                    binding.worldMatrixSnapshot = readWorldMatrixSnapshot(mesh);
+                continue;
+            }
+            syncCaster(binding.renderableId);
+            binding.worldMatrixSnapshot = readWorldMatrixSnapshot(mesh);
+            pendingTransformMembershipRetries.delete(mesh);
+            enqueueRefresh(currentObject.updateClass === 'static' ? 'static-transform-changed' : 'dynamic-transform-changed');
+        }
+    };
+    const unregisterMesh = (mesh) => {
+        const binding = bindings.get(mesh);
+        if (!binding)
+            return;
+        const previousLayer = candidateLayerByMesh.get(mesh);
+        const wasCaster = depthBackend?.hasCaster(mesh) === true;
+        const wasActiveRecord = registry?.getRecord(binding.renderableId)?.state === 'active';
+        depthBackend?.removeCaster(mesh);
+        mesh.onEnabledStateChangedObservable.remove(binding.enabledObserver);
+        mesh.onDisposeObservable.remove(binding.disposeObserver);
+        if (binding.matrixObserver)
+            mesh.onAfterWorldMatrixUpdateObservable.remove(binding.matrixObserver);
+        restoreReceiver(mesh);
+        setCandidateLayer(mesh, null);
+        conservativeCasterMeshes.delete(mesh);
+        meshDataCacheByMesh.delete(mesh);
+        syncCandidateCounts();
+        const meshes = meshesByRenderable.get(binding.renderableId);
+        meshes?.delete(mesh);
+        if (!meshes || meshes.size === 0) {
+            meshesByRenderable.delete(binding.renderableId);
+            registry?.detach(binding.renderableId);
+            pendingRenderableMembershipRetries.delete(binding.renderableId);
+        }
+        else {
+            const visible = [...meshes].some(isMeshRuntimeVisible);
+            registry?.setVisible(binding.renderableId, visible);
+        }
+        if (binding) {
+            syncActivityEligibility(binding.entityId);
+        }
+        if (wasCaster || wasActiveRecord) {
+            if (registry?.snapshot().activeCasterCount === 0)
+                registry.markDirty('empty-list-clear');
+            if (previousLayer)
+                markDepthDirty(previousLayer, 'caster-removed');
+            else
+                enqueueRefresh('caster-removed');
+            if (candidateLayerByMesh.size === 0 && previousLayer) {
+                markDepthDirty(previousLayer, 'empty-list-clear');
+            }
+        }
+        bindings.delete(mesh);
+        pendingMeshRegistrationRollbacks.delete(mesh);
+        pendingMeshUnregistrations.delete(mesh);
+        pendingTransformMembershipRetries.delete(mesh);
+    };
+    const requestMeshUnregistration = (mesh) => {
+        pendingSceneMeshRegistrations.delete(mesh);
+        try {
+            unregisterMesh(mesh);
+            pendingMeshUnregistrations.delete(mesh);
+            reconcileAutomaticAnimationGroups();
+        }
+        catch (error) {
+            pendingMeshUnregistrations.add(mesh);
+            throw error;
+        }
+    };
+    const flushPendingMeshUnregistrations = () => {
+        for (const mesh of [...pendingMeshUnregistrations])
+            requestMeshUnregistration(mesh);
+    };
+    const registerMesh = (mesh) => {
+        const pendingObserverCleanupErrors = flushPendingMeshObserverCleanup(mesh);
+        if (pendingObserverCleanupErrors.length > 0) {
+            throw Object.assign(new Error('shadowMapExperiment.meshObserverCleanupFailed'), {
+                cleanupErrors: pendingObserverCleanupErrors,
+            });
+        }
+        if (pendingMeshRegistrationRollbacks.has(mesh)) {
+            try {
+                unregisterMesh(mesh);
+            }
+            catch (error) {
+                throw Object.assign(new Error('shadowMapExperiment.meshRegistrationRollbackFailed'), {
+                    cause: error,
+                });
+            }
+            pendingMeshRegistrationRollbacks.delete(mesh);
+        }
+        if (!plan?.enabled || !registry || bindings.has(mesh) || isDisposed(mesh))
+            return false;
+        const renderableId = resolveRenderableId(mesh, objectByRenderable);
+        if (!renderableId)
+            return false;
+        const object = objectByRenderable.get(renderableId);
+        if (!object)
+            return false;
+        let enabledObserver = null;
+        let disposeObserver = null;
+        let bindingCommitted = false;
+        try {
+            enabledObserver = mesh.onEnabledStateChangedObservable.add(() => {
+                if (!disposed && !disposing) {
+                    syncRenderable(renderableId);
+                    reconcileAutomaticAnimationGroups();
+                }
+            });
+            disposeObserver = mesh.onDisposeObservable.add(() => requestMeshUnregistration(mesh));
+            const meshes = meshesByRenderable.get(renderableId) ?? new Set();
+            meshes.add(mesh);
+            meshesByRenderable.set(renderableId, meshes);
+            const binding = {
+                mesh,
+                entityId: object.entityId,
+                renderableId,
+                sceneFitLocalBounds: readMeshLocalBounds(mesh),
+                enabledObserver,
+                disposeObserver,
+                matrixObserver: null,
+                worldMatrixSnapshot: null,
+            };
+            bindings.set(mesh, binding);
+            bindingCommitted = true;
+            syncMatrixObserver(binding);
+            syncRenderable(renderableId);
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            if (bindingCommitted) {
+                try {
+                    unregisterMesh(mesh);
+                }
+                catch (rollbackError) {
+                    pendingMeshRegistrationRollbacks.add(mesh);
+                    rollbackErrors.push(rollbackError);
+                }
+            }
+            else {
+                pendingMeshObserverCleanups.set(mesh, { mesh, enabledObserver, disposeObserver });
+                rollbackErrors.push(...flushPendingMeshObserverCleanup(mesh));
+            }
+            if (rollbackErrors.length > 0 && error && typeof error === 'object') {
+                attachFailureMetadata(error, { registrationRollbackErrors: Object.freeze(rollbackErrors) });
+            }
+            throw error;
+        }
+        return true;
+    };
+    const flushPendingMeshObserverCleanup = (mesh) => {
+        const pending = pendingMeshObserverCleanups.get(mesh);
+        if (!pending)
+            return Object.freeze([]);
+        const cleanupErrors = [];
+        if (pending.disposeObserver) {
+            try {
+                pending.mesh.onDisposeObservable.remove(pending.disposeObserver);
+                pending.disposeObserver = null;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (pending.enabledObserver) {
+            try {
+                pending.mesh.onEnabledStateChangedObservable.remove(pending.enabledObserver);
+                pending.enabledObserver = null;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (!pending.disposeObserver && !pending.enabledObserver)
+            pendingMeshObserverCleanups.delete(mesh);
+        return Object.freeze(cleanupErrors);
+    };
+    const flushPendingSceneMeshRegistrations = () => {
+        let registered = false;
+        for (const mesh of [...pendingSceneMeshRegistrations]) {
+            if (!scene.meshes.includes(mesh)) {
+                pendingSceneMeshRegistrations.delete(mesh);
+                continue;
+            }
+            registered = registerMesh(mesh) || registered;
+            pendingSceneMeshRegistrations.delete(mesh);
+        }
+        if (registered)
+            reconcileAutomaticAnimationGroups();
+    };
+    const deactivate = () => {
+        pendingCompositeRefreshReasons.clear();
+        const cleanupErrors = [];
+        const attempt = (operation) => {
+            try {
+                operation();
+                return true;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+                return false;
+            }
+        };
+        for (const [mesh, binding] of [...bindings]) {
+            let cleaned = true;
+            cleaned = attempt(() => mesh.onEnabledStateChangedObservable.remove(binding.enabledObserver)) && cleaned;
+            cleaned = attempt(() => mesh.onDisposeObservable.remove(binding.disposeObserver)) && cleaned;
+            if (binding.matrixObserver) {
+                cleaned = attempt(() => mesh.onAfterWorldMatrixUpdateObservable.remove(binding.matrixObserver)) && cleaned;
+            }
+            cleaned = attempt(() => restoreReceiver(mesh)) && cleaned;
+            if (depthBackend) {
+                cleaned = attempt(() => depthBackend.removeCaster(mesh)) && cleaned;
+            }
+            cleaned = attempt(() => activityScheduler.setEntityActive(binding.entityId, false)) && cleaned;
+            if (cleaned)
+                bindings.delete(mesh);
+            if (cleaned)
+                pendingMeshRegistrationRollbacks.delete(mesh);
+        }
+        for (const mesh of [...pendingMeshObserverCleanups.keys()]) {
+            cleanupErrors.push(...flushPendingMeshObserverCleanup(mesh));
+        }
+        for (const [mesh, state] of [...receiverStates]) {
+            if (attempt(() => {
+                if (!isDisposed(state.mesh) && state.mesh.receiveShadows === state.ownedValue) {
+                    state.mesh.receiveShadows = state.previousReceiveShadows;
+                }
+            }))
+                receiverStates.delete(mesh);
+        }
+        if (bindings.size === 0) {
+            meshesByRenderable.clear();
+            candidateLayerByMesh.clear();
+            candidateMeshCounts.static = 0;
+            candidateMeshCounts.dynamic = 0;
+            conservativeCasterMeshes.clear();
+            meshDataCacheByMesh.clear();
+            pendingMeshRegistrationRollbacks.clear();
+            pendingSceneMeshRegistrations.clear();
+            pendingMeshUnregistrations.clear();
+            pendingRenderableMembershipRetries.clear();
+            pendingTransformMembershipRetries.clear();
+            activeCasterEntityIds.clear();
+            eligibleActiveDeformationEntityIds.clear();
+            pendingFinalDeformationEntityIds.clear();
+            pendingDeformationInvalidations.clear();
+            pendingMembershipInvalidationLayers.clear();
+            pendingCoverageMembershipRebuild = false;
+            objectByRenderable.clear();
+            objectByEntity.clear();
+        }
+        receiverTargetByMesh.clear();
+        if (registry) {
+            const ownedRegistry = registry;
+            if (attempt(() => ownedRegistry.dispose()))
+                registry = null;
+        }
+        if (depthBackend) {
+            const ownedBackend = depthBackend;
+            if (attempt(() => ownedBackend.dispose())) {
+                depthBackend = null;
+                generator = null;
+            }
+        }
+        if (pendingBackendAllocationCleanup) {
+            const cleanup = pendingBackendAllocationCleanup;
+            if (attempt(() => {
+                const errors = cleanup();
+                if (errors.length > 0) {
+                    throw Object.assign(new Error('shadowMapExperiment.backendAllocationCleanupFailed'), { cleanupErrors: errors });
+                }
+            }))
+                pendingBackendAllocationCleanup = null;
+        }
+        if (!depthBackend && !pendingBackendAllocationCleanup)
+            pendingFallbackReason = null;
+        if (lightState) {
+            const ownedLightState = lightState;
+            if (attempt(() => restoreLight(ownedLightState)))
+                lightState = null;
+        }
+        if (previousSceneShadowsEnabled !== null) {
+            const ownedSceneShadowsEnabled = previousSceneShadowsEnabled;
+            if (attempt(() => { scene.shadowsEnabled = ownedSceneShadowsEnabled; }))
+                previousSceneShadowsEnabled = null;
+        }
+        effectiveCoverageCenter = null;
+        effectiveCoverageExtent = null;
+        effectiveCoverageNear = null;
+        effectiveCoverageFar = null;
+        if (cleanupErrors.length > 0) {
+            throw Object.assign(new Error('shadowMapExperiment.deactivationFailed'), { cleanupErrors });
+        }
+    };
+    const activate = (nextPlan) => {
+        const light = resolveDirectionalLight(scene, nextPlan.light.entityId);
+        if (!light)
+            throw new Error(`shadowMapExperiment.lightMissing:${nextPlan.light.entityId}`);
+        const existingGenerators = readShadowGenerators(light);
+        if (existingGenerators.length > 0)
+            throw new Error(`shadowMapExperiment.backendConflict:${nextPlan.light.entityId}`);
+        previousSceneShadowsEnabled = scene.shadowsEnabled;
+        influenceCulling.configure(nextPlan.culling.guardBandRatio);
+        lightState = captureLight(light);
+        effectiveCoverageCenter = nextPlan.generator.bounds.center;
+        effectiveCoverageExtent = nextPlan.generator.bounds.extent;
+        effectiveCoverageNear = nextPlan.generator.bounds.near;
+        effectiveCoverageFar = nextPlan.generator.bounds.far;
+        configureLight(light, nextPlan, {
+            center: nextPlan.generator.bounds.center,
+            extent: nextPlan.generator.bounds.extent,
+            near: nextPlan.generator.bounds.near,
+            far: nextPlan.generator.bounds.far,
+        });
+        scene.shadowsEnabled = true;
+        light.shadowEnabled = true;
+        try {
+            depthBackend = createBabylonShadowMapExperimentDepthBackend(scene, light, nextPlan, {
+                onCompositorLifecycleEvent: handleCompositorLifecycleEvent,
+            });
+        }
+        catch (error) {
+            rememberBackendAllocationCleanup(error);
+            throw error;
+        }
+        generator = depthBackend.generator;
+        if (depthBackend.fallbackReason)
+            warnForFallback(depthBackend.fallbackReason);
+        registry = createShadowMapExperimentRegistry(nextPlan);
+        for (const object of nextPlan.objects) {
+            objectByEntity.set(object.entityId, object);
+            for (const renderableId of object.renderableIds)
+                objectByRenderable.set(renderableId, object);
+        }
+        updateCameraInfluenceCoverage();
+        for (const mesh of scene.meshes)
+            registerMesh(mesh);
+        reconcileAutomaticAnimationGroups();
+        markAllDepthDirty('generator-created');
+    };
+    const registerActivitySource = (input) => {
+        assertUsable();
+        const controller = activityScheduler.registerSource(input);
+        const deformationSource = input.kind === 'animation' || input.kind === 'morph';
+        let sourceActive = false;
+        let controllerDisposed = false;
+        const updateDeformationSourceCount = (previousActive, nextActive) => {
+            if (!deformationSource || previousActive === nextActive)
+                return;
+            const previousCount = activeDeformationSourceCountByEntity.get(input.entityId) ?? 0;
+            if (nextActive) {
+                activeDeformationSourceCountByEntity.set(input.entityId, previousCount + 1);
+                pendingFinalDeformationEntityIds.delete(input.entityId);
+                syncDeformationActivityEligibility(input.entityId);
+                return;
+            }
+            if (previousCount <= 1) {
+                activeDeformationSourceCountByEntity.delete(input.entityId);
+                if (activeCasterEntityIds.has(input.entityId))
+                    pendingFinalDeformationEntityIds.add(input.entityId);
+            }
+            else {
+                activeDeformationSourceCountByEntity.set(input.entityId, previousCount - 1);
+            }
+            syncDeformationActivityEligibility(input.entityId);
+        };
+        return Object.freeze({
+            entityId: controller.entityId,
+            kind: controller.kind,
+            sourceId: controller.sourceId,
+            setActive(nextActive) {
+                if (disposed || disposing || controllerDisposed || sourceActive === nextActive)
+                    return false;
+                if (!controller.setActive(nextActive))
+                    return false;
+                updateDeformationSourceCount(sourceActive, nextActive);
+                sourceActive = nextActive;
+                requestRefreshFrame(`shadow-map-experiment-${nextActive ? 'caster-activity-started' : 'caster-activity-stopped'}`);
+                return true;
+            },
+            invalidate() {
+                if (disposed || disposing || controllerDisposed)
+                    return false;
+                const invalidated = controller.invalidate();
+                if (!invalidated)
+                    return false;
+                const reason = dirtyReasonForActivityKind(input.kind);
+                if (deformationSource) {
+                    const invalidationReasons = pendingDeformationInvalidations.get(input.entityId) ?? new Set();
+                    invalidationReasons.add(reason);
+                    pendingDeformationInvalidations.set(input.entityId, invalidationReasons);
+                }
+                requestRefreshFrame(`shadow-map-experiment-${reason}`);
+                return true;
+            },
+            dispose() {
+                if (controllerDisposed)
+                    return;
+                const wasActive = sourceActive;
+                updateDeformationSourceCount(sourceActive, false);
+                sourceActive = false;
+                controllerDisposed = true;
+                controller.dispose();
+                if (wasActive)
+                    requestRefreshFrame('shadow-map-experiment-caster-activity-stopped');
+            },
+        });
+    };
+    const resolveAutomaticActivityTargets = (group) => {
+        const desired = new Map();
+        for (const targetedAnimation of group.targetedAnimations) {
+            const target = targetedAnimation.target;
+            const kind = classifyAutomaticActivityTarget(target, bindings);
+            const targetMeshes = resolveAutomaticActivityTargetMeshes(scene, bindings, target, kind);
+            for (const mesh of targetMeshes) {
+                if (!isMeshRuntimeVisible(mesh))
+                    continue;
+                const meshBinding = bindings.get(mesh);
+                const object = meshBinding ? objectByEntity.get(meshBinding.entityId) : null;
+                if (!meshBinding || !object?.cast || object.updateClass === 'static')
+                    continue;
+                const key = `${meshBinding.entityId}\u0000${kind}`;
+                desired.set(key, { entityId: meshBinding.entityId, kind });
+            }
+        }
+        return desired;
+    };
+    const reconcileAutomaticAnimationGroup = (binding) => {
+        const active = binding.group.isPlaying === true;
+        const desired = resolveAutomaticActivityTargets(binding.group);
+        const created = [];
+        try {
+            for (const [key, descriptor] of desired) {
+                if (binding.sources.has(key))
+                    continue;
+                const sourceId = `fps:auto:animation-group:${binding.group.uniqueId}:${descriptor.kind}`;
+                const controller = registerActivitySource({ ...descriptor, sourceId });
+                const source = { ...descriptor, controller };
+                binding.sources.set(key, source);
+                created.push({ key, source });
+                if (active)
+                    controller.setActive(true);
+            }
+        }
+        catch (error) {
+            for (const entry of created.reverse()) {
+                try {
+                    entry.source.controller.setActive(false);
+                }
+                catch { /* Best-effort rollback. */ }
+                try {
+                    entry.source.controller.dispose();
+                }
+                catch { /* Best-effort rollback. */ }
+                binding.sources.delete(entry.key);
+            }
+            throw error;
+        }
+        for (const [key, source] of [...binding.sources]) {
+            if (desired.has(key))
+                continue;
+            source.controller.setActive(false);
+            source.controller.dispose();
+            binding.sources.delete(key);
+        }
+        for (const source of binding.sources.values())
+            source.controller.setActive(active);
+        binding.active = active;
+    };
+    const safelyReconcileAutomaticAnimationGroup = (binding) => {
+        if (disposed || disposing || !binding.ready)
+            return;
+        try {
+            reconcileAutomaticAnimationGroup(binding);
+        }
+        catch (error) {
+            rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} could not bind shadow activity: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const attachAutomaticAnimationGroup = (group) => {
+        if (automaticAnimationGroups.has(group) || disposed || disposing)
+            return;
+        const binding = {
+            group,
+            playObserver: null,
+            pauseObserver: null,
+            endObserver: null,
+            sources: new Map(),
+            active: false,
+            ready: false,
+        };
+        automaticAnimationGroups.set(group, binding);
+        try {
+            binding.playObserver = group.onAnimationGroupPlayObservable.add(() => {
+                if (!binding.ready)
+                    return;
+                safelyReconcileAutomaticAnimationGroup(binding);
+                requestRefreshFrame('shadow-map-experiment-animation-group-played');
+            });
+            binding.pauseObserver = group.onAnimationGroupPauseObservable.add(() => {
+                if (binding.ready)
+                    safelyReconcileAutomaticAnimationGroup(binding);
+            });
+            binding.endObserver = group.onAnimationGroupEndObservable.add(() => {
+                if (binding.ready)
+                    safelyReconcileAutomaticAnimationGroup(binding);
+            });
+            binding.ready = true;
+            safelyReconcileAutomaticAnimationGroup(binding);
+        }
+        catch (error) {
+            binding.ready = false;
+            const cleanupErrors = detachAutomaticAnimationGroup(group);
+            if (cleanupErrors.length > 0 && error && typeof error === 'object') {
+                attachFailureMetadata(error, { cleanupErrors });
+            }
+            throw error;
+        }
+    };
+    const detachAutomaticAnimationGroup = (group) => {
+        const binding = automaticAnimationGroups.get(group);
+        if (!binding)
+            return Object.freeze([]);
+        binding.ready = false;
+        const cleanupErrors = [];
+        for (const [key, source] of [...binding.sources.entries()].reverse()) {
+            try {
+                source.controller.setActive(false);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+            try {
+                source.controller.dispose();
+                binding.sources.delete(key);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (binding.playObserver) {
+            try {
+                group.onAnimationGroupPlayObservable.remove(binding.playObserver);
+                binding.playObserver = null;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (binding.pauseObserver) {
+            try {
+                group.onAnimationGroupPauseObservable.remove(binding.pauseObserver);
+                binding.pauseObserver = null;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (binding.endObserver) {
+            try {
+                group.onAnimationGroupEndObservable.remove(binding.endObserver);
+                binding.endObserver = null;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (cleanupErrors.length === 0
+            && binding.sources.size === 0
+            && !binding.playObserver
+            && !binding.pauseObserver
+            && !binding.endObserver)
+            automaticAnimationGroups.delete(group);
+        return Object.freeze(cleanupErrors);
+    };
+    const reconcileAutomaticAnimationGroups = () => {
+        for (const binding of automaticAnimationGroups.values())
+            safelyReconcileAutomaticAnimationGroup(binding);
+    };
+    const syncAutomaticAnimationGroupStates = () => {
+        for (const binding of automaticAnimationGroups.values()) {
+            if (!binding.ready)
+                continue;
+            const active = binding.group.isPlaying === true;
+            if (active !== binding.active || (active && binding.sources.size === 0)) {
+                safelyReconcileAutomaticAnimationGroup(binding);
+            }
+        }
+    };
+    const applyPlanInPlace = (previousPlan, nextPlan) => {
+        if (!registry || !generator)
+            throw new Error('shadowMapExperiment.backendUnavailable');
+        const delta = diffShadowMapExperimentPlans(previousPlan, nextPlan);
+        plan = nextPlan;
+        objectByRenderable.clear();
+        objectByEntity.clear();
+        for (const object of nextPlan.objects) {
+            objectByEntity.set(object.entityId, object);
+            for (const renderableId of object.renderableIds)
+                objectByRenderable.set(renderableId, object);
+        }
+        activityScheduler.applyPlan(nextPlan);
+        registry.applyPlan(nextPlan);
+        for (const [mesh, binding] of [...bindings]) {
+            const resolvedId = resolveRenderableId(mesh, objectByRenderable);
+            const resolvedEntityId = resolvedId ? objectByRenderable.get(resolvedId)?.entityId : null;
+            if (resolvedId !== binding.renderableId || resolvedEntityId !== binding.entityId)
+                unregisterMesh(mesh);
+            else {
+                syncMatrixObserver(binding);
+                syncRenderable(binding.renderableId);
+            }
+        }
+        for (const mesh of scene.meshes)
+            registerMesh(mesh);
+        reconcileAutomaticAnimationGroups();
+        for (const reason of delta.dirtyReasons) {
+            registry.markDirty(reason);
+            enqueueRefresh(reason);
+        }
+    };
+    const rollbackPlanUpdate = (previousPlan, error) => {
+        const rollbackDeactivationErrors = [];
+        try {
+            deactivate();
+        }
+        catch (deactivationError) {
+            rollbackDeactivationErrors.push(deactivationError);
+        }
+        plan = previousPlan;
+        activityScheduler.applyPlan(previousPlan?.enabled ? previousPlan : null);
+        const rollbackErrors = [];
+        if (previousPlan?.enabled && !hasOwnedBackendState()) {
+            try {
+                activate(previousPlan);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+                try {
+                    deactivate();
+                }
+                catch (deactivationError) {
+                    rollbackDeactivationErrors.push(deactivationError);
+                }
+            }
+        }
+        if ((rollbackErrors.length > 0 || rollbackDeactivationErrors.length > 0) && error && typeof error === 'object') {
+            attachFailureMetadata(error, {
+                rollbackErrors,
+                ...(rollbackDeactivationErrors.length > 0 ? { rollbackDeactivationErrors } : {}),
+            });
+        }
+        throw error;
+    };
+    const hasOwnedBackendState = () => bindings.size > 0
+        || pendingMeshObserverCleanups.size > 0
+        || pendingMeshRegistrationRollbacks.size > 0
+        || pendingSceneMeshRegistrations.size > 0
+        || pendingMeshUnregistrations.size > 0
+        || pendingRenderableMembershipRetries.size > 0
+        || pendingTransformMembershipRetries.size > 0
+        || receiverStates.size > 0
+        || registry !== null
+        || depthBackend !== null
+        || pendingBackendAllocationCleanup !== null
+        || generator !== null
+        || lightState !== null
+        || previousSceneShadowsEnabled !== null;
+    const applyEffectivePlan = (value, allowDisposing = false) => {
+        assertUsable(allowDisposing);
+        const nextPlan = value ? createShadowMapExperimentPlanSnapshot(value) : null;
+        const previousPlan = plan;
+        if (previousPlan?.enabled && nextPlan?.enabled) {
+            const delta = diffShadowMapExperimentPlans(previousPlan, nextPlan);
+            if (!delta.generatorChanged) {
+                try {
+                    applyPlanInPlace(previousPlan, nextPlan);
+                    return;
+                }
+                catch (error) {
+                    rollbackPlanUpdate(previousPlan, error);
+                }
+            }
+        }
+        deactivate();
+        plan = nextPlan;
+        activityScheduler.applyPlan(nextPlan?.enabled ? nextPlan : null);
+        if (!nextPlan?.enabled) {
+            reconcileAutomaticAnimationGroups();
+            return;
+        }
+        try {
+            activate(nextPlan);
+        }
+        catch (error) {
+            rollbackPlanUpdate(previousPlan, error);
+        }
+    };
+    const setPlan = (value) => {
+        assertUsable();
+        const nextSourcePlan = value ? createShadowMapExperimentPlanSnapshot(value) : null;
+        const records = [...runtimeRegistrations.values()].filter(record => !record.disposed);
+        const nextEffectivePlan = composeEffectivePlan(nextSourcePlan, records, runtimeOverlayRevision);
+        const previousSourcePlan = sourcePlan;
+        try {
+            applyEffectivePlan(nextEffectivePlan);
+            sourcePlan = nextSourcePlan;
+        }
+        catch (error) {
+            sourcePlan = previousSourcePlan;
+            throw error;
+        }
+    };
+    const { newMeshObserver, removedMeshObserver, frameObserver, newAnimationGroupObserver, removedAnimationGroupObserver, } = (() => {
+        let acquiredNewMeshObserver = null;
+        let acquiredRemovedMeshObserver = null;
+        let acquiredFrameObserver = null;
+        let acquiredNewAnimationGroupObserver = null;
+        let acquiredRemovedAnimationGroupObserver = null;
+        try {
+            acquiredNewMeshObserver = scene.onNewMeshAddedObservable.add(mesh => {
+                // Babylon announces a mesh from its constructor before every identity and
+                // visibility field is guaranteed to be initialized. Bind after that
+                // constructor completes; this is still an event-local operation, not a scan.
+                if (disposed || disposing || !scene.meshes.includes(mesh))
+                    return;
+                pendingSceneMeshRegistrations.add(mesh);
+                queueMicrotask(() => {
+                    if (disposed || disposing || !pendingSceneMeshRegistrations.has(mesh))
+                        return;
+                    if (!scene.meshes.includes(mesh)) {
+                        pendingSceneMeshRegistrations.delete(mesh);
+                        return;
+                    }
+                    try {
+                        const registered = registerMesh(mesh);
+                        pendingSceneMeshRegistrations.delete(mesh);
+                        if (registered)
+                            reconcileAutomaticAnimationGroups();
+                    }
+                    catch {
+                        pendingSceneMeshRegistrations.add(mesh);
+                    }
+                });
+            });
+            acquiredRemovedMeshObserver = scene.onMeshRemovedObservable.add(mesh => requestMeshUnregistration(mesh));
+            acquiredNewAnimationGroupObserver = scene.onNewAnimationGroupAddedObservable.add(group => {
+                try {
+                    attachAutomaticAnimationGroup(group);
+                }
+                catch (error) {
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityObserverFailed', `AnimationGroup ${group.name || group.uniqueId} could not be observed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+            acquiredRemovedAnimationGroupObserver = scene.onAnimationGroupRemovedObservable.add(group => {
+                const cleanupErrors = detachAutomaticAnimationGroup(group);
+                if (cleanupErrors.length > 0) {
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityCleanupFailed', `AnimationGroup ${group.name || group.uniqueId} activity cleanup failed.`);
+                }
+            });
+            acquiredFrameObserver = scene.onBeforeRenderObservable.add(() => flushRefresh());
+            for (const group of scene.animationGroups)
+                attachAutomaticAnimationGroup(group);
+            return {
+                newMeshObserver: acquiredNewMeshObserver,
+                removedMeshObserver: acquiredRemovedMeshObserver,
+                frameObserver: acquiredFrameObserver,
+                newAnimationGroupObserver: acquiredNewAnimationGroupObserver,
+                removedAnimationGroupObserver: acquiredRemovedAnimationGroupObserver,
+            };
+        }
+        catch (error) {
+            const cleanup = () => {
+                const cleanupErrors = [];
+                for (const group of [...automaticAnimationGroups.keys()].reverse()) {
+                    cleanupErrors.push(...detachAutomaticAnimationGroup(group));
+                }
+                if (acquiredRemovedAnimationGroupObserver) {
+                    try {
+                        scene.onAnimationGroupRemovedObservable.remove(acquiredRemovedAnimationGroupObserver);
+                        acquiredRemovedAnimationGroupObserver = null;
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                }
+                if (acquiredNewAnimationGroupObserver) {
+                    try {
+                        scene.onNewAnimationGroupAddedObservable.remove(acquiredNewAnimationGroupObserver);
+                        acquiredNewAnimationGroupObserver = null;
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                }
+                if (acquiredFrameObserver) {
+                    try {
+                        scene.onBeforeRenderObservable.remove(acquiredFrameObserver);
+                        acquiredFrameObserver = null;
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                }
+                if (acquiredRemovedMeshObserver) {
+                    try {
+                        scene.onMeshRemovedObservable.remove(acquiredRemovedMeshObserver);
+                        acquiredRemovedMeshObserver = null;
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                }
+                if (acquiredNewMeshObserver) {
+                    try {
+                        scene.onNewMeshAddedObservable.remove(acquiredNewMeshObserver);
+                        acquiredNewMeshObserver = null;
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                }
+                return Object.freeze(cleanupErrors);
+            };
+            const cleanupErrors = cleanup();
+            if (cleanupErrors.length > 0)
+                throw createInitializationFailure(error, cleanup, cleanupErrors);
+            throw error;
+        }
+    })();
+    let disposeNewMeshObserverRemoved = false;
+    let disposeRemovedMeshObserverRemoved = false;
+    let disposeFrameObserverRemoved = false;
+    let disposeNewAnimationGroupObserverRemoved = false;
+    let disposeRemovedAnimationGroupObserverRemoved = false;
+    let disposeActivitySchedulerDisposed = false;
+    let disposeDepthRefreshSchedulerDisposed = false;
+    let disposeInfluenceCullingDisposed = false;
+    const createRuntimeOwner = (records) => {
+        const recordSet = new Set(records);
+        const owner = Object.freeze({
+            entityIds: Object.freeze(records.map(record => record.entityId).sort()),
+            renderableIds: Object.freeze(records.flatMap(record => (record.renderables.map(renderable => renderable.renderableId))).sort()),
+            getBehaviorProfileId(entityId) {
+                return records.find(record => record.entityId === entityId && !record.disposed)?.behaviorProfileId ?? null;
+            },
+            getActivityController(entityId, sourceId) {
+                const record = records.find(candidate => candidate.entityId === entityId && !candidate.disposed);
+                return record?.controllers.get(sourceId) ?? null;
+            },
+            dispose() {
+                if (records.every(record => record.disposed))
+                    return;
+                assertUsable(true);
+                const cleanupErrors = [];
+                for (const record of [...records].reverse()) {
+                    for (const sourceId of [...record.controllers.keys()].reverse()) {
+                        const controller = record.controllers.get(sourceId);
+                        if (!controller)
+                            continue;
+                        try {
+                            controller.setActive(false);
+                        }
+                        catch (error) {
+                            cleanupErrors.push(error);
+                        }
+                        try {
+                            controller.dispose();
+                            record.controllers.delete(sourceId);
+                        }
+                        catch (error) {
+                            cleanupErrors.push(error);
+                        }
+                    }
+                }
+                const controllersDisposed = records.every(record => record.controllers.size === 0);
+                const anyRegistered = records.some(record => runtimeRegistrations.get(record.entityId) === record);
+                if (controllersDisposed && anyRegistered) {
+                    const nextOverlayRevision = runtimeOverlayRevision + 1;
+                    const nextRecords = [...runtimeRegistrations.values()].filter(candidate => !recordSet.has(candidate) && !candidate.disposed);
+                    try {
+                        applyEffectivePlan(composeEffectivePlan(sourcePlan, nextRecords, nextOverlayRevision), true);
+                        for (const record of records)
+                            runtimeRegistrations.delete(record.entityId);
+                        runtimeOverlayRevision = nextOverlayRevision;
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+                if (controllersDisposed && records.every(record => runtimeRegistrations.get(record.entityId) !== record)) {
+                    for (const record of records)
+                        record.disposed = true;
+                }
+                if (cleanupErrors.length > 0) {
+                    const error = Object.assign(new Error('shadowMapExperiment.runtimeOwnerDisposeFailed'), {
+                        cleanupErrors: Object.freeze(cleanupErrors),
+                        runtimeShadowObjectsRecoveryOwner: owner,
+                    });
+                    throw error;
+                }
+            },
+        });
+        for (const record of records)
+            record.owner = owner;
+        return owner;
+    };
+    const validateRuntimeRegistration = (input, batchEntityIds, batchRenderableIds, batchMeshes, batchActivityIdentities) => {
+        const entityId = input.entityId?.trim();
+        const behaviorProfileId = input.behaviorProfileId?.trim();
+        if (!entityId || entityId !== input.entityId)
+            throw new Error('shadowMapExperiment.runtimeEntityIdRequired');
+        if (!behaviorProfileId || behaviorProfileId !== input.behaviorProfileId) {
+            throw new Error('shadowMapExperiment.runtimeBehaviorProfileIdRequired');
+        }
+        const profile = requireRuntimeProfile(sourcePlan, behaviorProfileId, entityId);
+        if (!sourcePlan?.enabled)
+            throw new Error('shadowMapExperiment.runtimePlanDisabled');
+        if (batchEntityIds.has(entityId) || runtimeRegistrations.has(entityId) || sourcePlan.objects.some(object => object.entityId === entityId)) {
+            throw new Error(`shadowMapExperiment.runtimeEntityConflict:${entityId}`);
+        }
+        batchEntityIds.add(entityId);
+        if (!Array.isArray(input.renderables) || input.renderables.length === 0) {
+            throw new Error(`shadowMapExperiment.runtimeRenderableRequired:${entityId}`);
+        }
+        const renderableIds = new Set();
+        const renderables = input.renderables.map((renderable, index) => {
+            const renderableId = renderable.renderableId?.trim();
+            if (!renderableId || renderableId !== renderable.renderableId) {
+                throw new Error(`shadowMapExperiment.runtimeRenderableIdRequired:${entityId}:${index}`);
+            }
+            if (renderableIds.has(renderableId) || batchRenderableIds.has(renderableId) || objectByRenderable.has(renderableId)) {
+                throw new Error(`shadowMapExperiment.runtimeRenderableConflict:${renderableId}`);
+            }
+            if (!renderable.mesh || renderable.mesh.getScene() !== scene || isDisposed(renderable.mesh) || !scene.meshes.includes(renderable.mesh)) {
+                throw new Error(`shadowMapExperiment.runtimeMeshSceneMismatch:${renderableId}`);
+            }
+            if (batchMeshes.has(renderable.mesh))
+                throw new Error(`shadowMapExperiment.runtimeMeshConflict:${renderableId}`);
+            if (!meshIdentityChainContains(renderable.mesh, renderableId)) {
+                throw new Error(`shadowMapExperiment.runtimeRenderableIdentityMismatch:${renderableId}`);
+            }
+            renderableIds.add(renderableId);
+            batchRenderableIds.add(renderableId);
+            batchMeshes.add(renderable.mesh);
+            return Object.freeze({ renderableId, mesh: renderable.mesh });
+        });
+        const existingActivityIdentities = new Set(activityScheduler.snapshot().sources.map(source => `${source.entityId}\u0000${source.sourceId}`));
+        const activitySourceIds = new Set();
+        const activities = (input.activities ?? []).map((activity, index) => {
+            const sourceId = activity.sourceId?.trim();
+            if (!sourceId || sourceId !== activity.sourceId) {
+                throw new Error(`shadowMapExperiment.runtimeActivitySourceIdRequired:${entityId}:${index}`);
+            }
+            if (!['transform', 'animation', 'morph', 'physics'].includes(activity.kind)) {
+                throw new Error(`shadowMapExperiment.runtimeActivityKindInvalid:${activity.kind}`);
+            }
+            const identity = `${entityId}\u0000${sourceId}`;
+            if (activitySourceIds.has(sourceId) || batchActivityIdentities.has(identity) || existingActivityIdentities.has(identity)) {
+                throw new Error(`shadowMapExperiment.runtimeActivityConflict:${entityId}:${sourceId}`);
+            }
+            if (!profile.cast || profile.updateClass === 'static') {
+                throw new Error(`shadowMapExperiment.runtimeActivityProfileIneligible:${behaviorProfileId}`);
+            }
+            activitySourceIds.add(sourceId);
+            batchActivityIdentities.add(identity);
+            return Object.freeze({ kind: activity.kind, sourceId, initiallyActive: activity.initiallyActive === true });
+        });
+        return {
+            entityId,
+            behaviorProfileId,
+            renderables: Object.freeze(renderables),
+            activities: Object.freeze(activities),
+            controllers: new Map(),
+            owner: null,
+            disposed: false,
+        };
+    };
+    const system = {
+        setPlan,
+        getPlan: () => plan,
+        getShadowGenerator: () => generator,
+        registerMesh(mesh) {
+            assertUsable();
+            return registerMesh(mesh);
+        },
+        unregisterMesh(mesh) {
+            assertUsable();
+            requestMeshUnregistration(mesh);
+        },
+        setRenderableVisible(renderableId, visible) {
+            assertUsable();
+            registry?.setVisible(renderableId, visible);
+            try {
+                syncCaster(renderableId);
+                pendingRenderableMembershipRetries.delete(renderableId);
+            }
+            catch (error) {
+                pendingRenderableMembershipRetries.add(renderableId);
+                throw error;
+            }
+            const entityId = objectByRenderable.get(renderableId)?.entityId;
+            if (entityId)
+                syncActivityEligibility(entityId);
+        },
+        registerCasterActivitySource(input) {
+            return registerActivitySource(input);
+        },
+        registerRuntimeShadowObjects(input) {
+            assertUsable();
+            if (!Array.isArray(input.objects) || input.objects.length === 0) {
+                throw new Error('shadowMapExperiment.runtimeObjectsRequired');
+            }
+            const batchEntityIds = new Set();
+            const batchRenderableIds = new Set();
+            const batchMeshes = new Set([
+                ...bindings.keys(),
+                ...[...runtimeRegistrations.values()].flatMap(record => record.renderables.map(renderable => renderable.mesh)),
+            ]);
+            const batchActivityIdentities = new Set();
+            const records = input.objects.map(object => validateRuntimeRegistration(object, batchEntityIds, batchRenderableIds, batchMeshes, batchActivityIdentities));
+            const owner = createRuntimeOwner(records);
+            const previousEffectivePlan = plan;
+            const nextOverlayRevision = runtimeOverlayRevision + 1;
+            let effectivePlanApplied = false;
+            try {
+                const nextRecords = [...runtimeRegistrations.values(), ...records].filter(candidate => !candidate.disposed);
+                applyEffectivePlan(composeEffectivePlan(sourcePlan, nextRecords, nextOverlayRevision));
+                effectivePlanApplied = true;
+                for (const record of records)
+                    runtimeRegistrations.set(record.entityId, record);
+                for (const record of records) {
+                    for (const activity of record.activities) {
+                        const controller = system.registerCasterActivitySource({
+                            entityId: record.entityId,
+                            kind: activity.kind,
+                            sourceId: activity.sourceId,
+                        });
+                        record.controllers.set(activity.sourceId, controller);
+                        if (activity.initiallyActive)
+                            controller.setActive(true);
+                    }
+                }
+                runtimeOverlayRevision = nextOverlayRevision;
+                return owner;
+            }
+            catch (error) {
+                const rollbackErrors = [];
+                for (const record of [...records].reverse()) {
+                    for (const [sourceId, controller] of [...record.controllers.entries()].reverse()) {
+                        try {
+                            controller.setActive(false);
+                        }
+                        catch (rollbackError) {
+                            rollbackErrors.push(rollbackError);
+                        }
+                        try {
+                            controller.dispose();
+                            record.controllers.delete(sourceId);
+                        }
+                        catch (rollbackError) {
+                            rollbackErrors.push(rollbackError);
+                        }
+                    }
+                }
+                let effectivePlanRollbackFailed = false;
+                if (effectivePlanApplied) {
+                    try {
+                        applyEffectivePlan(previousEffectivePlan);
+                    }
+                    catch (rollbackError) {
+                        effectivePlanRollbackFailed = true;
+                        rollbackErrors.push(rollbackError);
+                    }
+                }
+                for (const record of records)
+                    runtimeRegistrations.delete(record.entityId);
+                if (rollbackErrors.length > 0) {
+                    for (const record of records)
+                        runtimeRegistrations.set(record.entityId, record);
+                    if (effectivePlanRollbackFailed)
+                        runtimeOverlayRevision = nextOverlayRevision;
+                    throw createRuntimeRegistrationRollbackFailure(error, owner, rollbackErrors);
+                }
+                else {
+                    for (const record of records)
+                        record.disposed = true;
+                }
+                throw error;
+            }
+        },
+        markDirty(reason, targetEntityOrRenderableId) {
+            assertUsable();
+            const targetedObject = targetEntityOrRenderableId
+                ? objectByEntity.get(targetEntityOrRenderableId) ?? objectByRenderable.get(targetEntityOrRenderableId)
+                : null;
+            const targetedLayer = targetedObject?.cast
+                ? shadowMapExperimentDepthLayerForUpdateClass(targetedObject.updateClass)
+                : null;
+            if (reason === 'static-geometry-changed')
+                pendingMembershipInvalidationLayers.add('static');
+            if (reason === 'material-alpha-test-changed' && targetedLayer) {
+                markDepthDirty(targetedLayer, reason);
+                return;
+            }
+            enqueueRefresh(reason);
+        },
+        getEvidence() {
+            const bounds = plan?.generator.bounds;
+            const lightSpaceSize = plan?.enabled && bounds
+                ? calculateLightSpaceSize(plan.light.direction, effectiveCoverageExtent ?? bounds.extent)
+                : null;
+            const activity = activityScheduler.snapshot();
+            const automaticBindings = [...automaticAnimationGroups.values()];
+            const automaticActivity = Object.freeze({
+                observedAnimationGroupCount: automaticBindings.length,
+                boundAnimationGroupCount: automaticBindings.filter(binding => binding.sources.size > 0).length,
+                activeAnimationGroupCount: automaticBindings.filter(binding => binding.active).length,
+                registeredActivitySourceCount: automaticBindings.reduce((count, binding) => count + binding.sources.size, 0),
+                unresolvedActiveAnimationGroupCount: automaticBindings.filter(binding => binding.active && binding.sources.size === 0).length,
+            });
+            const depthEvidence = depthBackend?.getEvidence() ?? null;
+            const thresholdDiagnostics = plan ? createThresholdDiagnostics(plan, depthEvidence?.static.candidateMeshCount ?? 0, depthEvidence?.dynamic.candidateMeshCount ?? 0) : [];
+            return Object.freeze({
+                enabled: plan?.enabled === true,
+                planRevision: plan?.revision ?? null,
+                planFingerprint: plan ? createShadowMapExperimentPlanFingerprint(plan) : null,
+                effectivePlan: plan ? createShadowMapExperimentPlanSnapshot(plan) : null,
+                lightEntityId: plan?.light.entityId ?? null,
+                generatorAllocated: generator !== null,
+                resolution: plan?.enabled ? plan.generator.maps.compositeResolution : null,
+                configuredMapResolutions: plan?.enabled ? Object.freeze({
+                    static: plan.generator.maps.staticResolution,
+                    dynamic: plan.generator.maps.dynamicResolution,
+                    composite: plan.generator.maps.compositeResolution,
+                }) : null,
+                mapResolutions: depthEvidence ? Object.freeze({
+                    static: depthEvidence.static.resolution,
+                    dynamic: depthEvidence.dynamic.resolution,
+                    composite: depthEvidence.compositeResolution,
+                }) : null,
+                diagnosticThresholds: plan?.enabled ? plan.diagnosticThresholds : null,
+                filter: plan?.enabled ? plan.generator.filter : null,
+                renderListCount: depthBackend
+                    ? depthBackend.getEvidence().static.renderListCount + depthBackend.getEvidence().dynamic.renderListCount
+                    : 0,
+                receiverMeshCount: [...receiverStates.values()].filter(state => state.ownedValue).length,
+                boundMeshCount: bindings.size,
+                activity,
+                automaticActivity,
+                runtime: Object.freeze({
+                    planSchemaVersion: sourcePlan?.schemaVersion ?? null,
+                    sourcePlanRevision: sourcePlan?.revision ?? null,
+                    effectivePlanRevision: plan?.revision ?? null,
+                    overlayRevision: runtimeOverlayRevision,
+                    registrationCount: runtimeRegistrations.size,
+                    activityOwnerCount: [...runtimeRegistrations.values()].reduce((total, record) => total + record.controllers.size, 0),
+                    registrations: Object.freeze([...runtimeRegistrations.values()]
+                        .filter(record => !record.disposed)
+                        .map(record => Object.freeze({
+                        entityId: record.entityId,
+                        behaviorProfileId: record.behaviorProfileId,
+                        renderableIds: Object.freeze(record.renderables.map(renderable => renderable.renderableId).sort()),
+                        activitySourceIds: Object.freeze([...record.controllers.keys()].sort()),
+                    }))
+                        .sort((left, right) => left.entityId.localeCompare(right.entityId))),
+                }),
+                refreshCount,
+                lastRefreshReasons,
+                worldUnitsPerTexel: plan?.enabled && lightSpaceSize && depthEvidence
+                    ? Object.freeze([
+                        lightSpaceSize[0] / depthEvidence.compositeResolution,
+                        lightSpaceSize[1] / depthEvidence.compositeResolution,
+                    ])
+                    : null,
+                worldUnitsPerTexelByMap: plan?.enabled && lightSpaceSize && depthEvidence ? Object.freeze({
+                    static: texelSize(lightSpaceSize, depthEvidence.static.resolution),
+                    dynamic: texelSize(lightSpaceSize, depthEvidence.dynamic.resolution),
+                    composite: texelSize(lightSpaceSize, depthEvidence.compositeResolution),
+                }) : null,
+                registry: registry?.snapshot() ?? null,
+                backend: depthBackend?.mode ?? null,
+                fallbackReason: depthBackend?.fallbackReason ?? pendingFallbackReason,
+                fallbackWarningEmitted: depthBackend?.fallbackReason
+                    ? fallbackWarnings.has(depthBackend.fallbackReason)
+                    : false,
+                depth: depthEvidence,
+                culling: Object.freeze({
+                    ...influenceCulling.snapshot(),
+                    enabled: plan?.culling.enabled === true,
+                    conservative: influenceCulling.snapshot().conservative || conservativeCasterMeshes.size > 0,
+                    stable: cullingStable,
+                    lastInvalidationReason: lastCullingInvalidationReason,
+                    coverageMode: options.coverageMode === 'scene-fit' ? 'scene-fit' : 'fixed',
+                    authoredCenter: plan
+                        ? Object.freeze([...plan.generator.bounds.center])
+                        : null,
+                    effectiveCenter: plan
+                        ? Object.freeze([
+                            ...(effectiveCoverageCenter ?? plan.generator.bounds.center),
+                        ])
+                        : null,
+                    authoredExtent: plan
+                        ? Object.freeze([...plan.generator.bounds.extent])
+                        : null,
+                    effectiveExtent: plan
+                        ? Object.freeze([
+                            ...(effectiveCoverageExtent ?? plan.generator.bounds.extent),
+                        ])
+                        : null,
+                    anchor: null,
+                }),
+                diagnostics: Object.freeze([
+                    ...diagnostics.map(entry => Object.freeze({ ...entry })),
+                    ...thresholdDiagnostics,
+                    ...((depthBackend?.fallbackReason ?? pendingFallbackReason) ? [Object.freeze({
+                            code: plan?.generator.backend.fallback === 'disable'
+                                ? 'shadowMapExperiment.splitBackendDisabled'
+                                : 'shadowMapExperiment.splitBackendFallback',
+                            message: plan?.generator.backend.fallback === 'disable'
+                                ? `Split depth backend was disabled: ${depthBackend?.fallbackReason ?? pendingFallbackReason}`
+                                : `Split depth backend fell back to a single ShadowMap: ${depthBackend?.fallbackReason ?? pendingFallbackReason}`,
+                        })] : []),
+                ]),
+            });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposing = true;
+            const runtimeCleanupErrors = [];
+            for (const record of [...runtimeRegistrations.values()].reverse()) {
+                try {
+                    record.owner?.dispose();
+                }
+                catch (error) {
+                    runtimeCleanupErrors.push(error);
+                }
+            }
+            if (runtimeCleanupErrors.length > 0) {
+                throw Object.assign(new Error('shadowMapExperiment.disposeFailed'), {
+                    cleanupErrors: Object.freeze(runtimeCleanupErrors),
+                });
+            }
+            const cleanupErrors = [];
+            const attempt = (operation, completed) => {
+                try {
+                    operation();
+                    completed();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+            };
+            if (!disposeNewAnimationGroupObserverRemoved) {
+                attempt(() => { scene.onNewAnimationGroupAddedObservable.remove(newAnimationGroupObserver); }, () => { disposeNewAnimationGroupObserverRemoved = true; });
+            }
+            if (!disposeRemovedAnimationGroupObserverRemoved) {
+                attempt(() => { scene.onAnimationGroupRemovedObservable.remove(removedAnimationGroupObserver); }, () => { disposeRemovedAnimationGroupObserverRemoved = true; });
+            }
+            for (const group of [...automaticAnimationGroups.keys()].reverse()) {
+                cleanupErrors.push(...detachAutomaticAnimationGroup(group));
+            }
+            if (!disposeNewMeshObserverRemoved) {
+                attempt(() => { scene.onNewMeshAddedObservable.remove(newMeshObserver); }, () => { disposeNewMeshObserverRemoved = true; });
+            }
+            if (!disposeRemovedMeshObserverRemoved) {
+                attempt(() => { scene.onMeshRemovedObservable.remove(removedMeshObserver); }, () => { disposeRemovedMeshObserverRemoved = true; });
+            }
+            if (!disposeFrameObserverRemoved) {
+                attempt(() => { scene.onBeforeRenderObservable.remove(frameObserver); }, () => { disposeFrameObserverRemoved = true; });
+            }
+            if (hasOwnedBackendState())
+                attempt(deactivate, () => undefined);
+            plan = null;
+            sourcePlan = null;
+            const observersRemoved = disposeNewMeshObserverRemoved
+                && disposeRemovedMeshObserverRemoved
+                && disposeFrameObserverRemoved
+                && disposeNewAnimationGroupObserverRemoved
+                && disposeRemovedAnimationGroupObserverRemoved
+                && automaticAnimationGroups.size === 0;
+            if (observersRemoved && !hasOwnedBackendState()) {
+                if (!disposeActivitySchedulerDisposed) {
+                    attempt(activityScheduler.dispose, () => { disposeActivitySchedulerDisposed = true; });
+                }
+                if (!disposeDepthRefreshSchedulerDisposed) {
+                    attempt(depthRefreshScheduler.dispose, () => { disposeDepthRefreshSchedulerDisposed = true; });
+                }
+                if (!disposeInfluenceCullingDisposed) {
+                    attempt(influenceCulling.dispose, () => { disposeInfluenceCullingDisposed = true; });
+                }
+            }
+            if (!hasOwnedBackendState()) {
+                activeDeformationSourceCountByEntity.clear();
+                eligibleActiveDeformationEntityIds.clear();
+                pendingFinalDeformationEntityIds.clear();
+                pendingDeformationInvalidations.clear();
+                activeCasterEntityIds.clear();
+                pendingTransformMembershipRetries.clear();
+                pendingSceneMeshRegistrations.clear();
+                pendingMeshUnregistrations.clear();
+                pendingRenderableMembershipRetries.clear();
+            }
+            disposed = observersRemoved
+                && !hasOwnedBackendState()
+                && disposeActivitySchedulerDisposed
+                && disposeDepthRefreshSchedulerDisposed
+                && disposeInfluenceCullingDisposed;
+            if (cleanupErrors.length > 0) {
+                throw Object.assign(new Error('shadowMapExperiment.disposeFailed'), { cleanupErrors });
+            }
+        },
+    };
+    if (initialPlan) {
+        try {
+            setPlan(initialPlan);
+        }
+        catch (error) {
+            let newMeshObserverRemoved = false;
+            let removedMeshObserverRemoved = false;
+            let frameObserverRemoved = false;
+            let newAnimationGroupObserverRemoved = false;
+            let removedAnimationGroupObserverRemoved = false;
+            let activitySchedulerDisposed = false;
+            let depthRefreshSchedulerDisposed = false;
+            let influenceCullingDisposed = false;
+            let cleanupComplete = false;
+            const cleanup = () => {
+                if (cleanupComplete)
+                    return Object.freeze([]);
+                const cleanupErrors = [];
+                const attempt = (operation, completed) => {
+                    try {
+                        operation();
+                        completed();
+                    }
+                    catch (cleanupError) {
+                        cleanupErrors.push(cleanupError);
+                    }
+                };
+                if (!newAnimationGroupObserverRemoved) {
+                    attempt(() => { scene.onNewAnimationGroupAddedObservable.remove(newAnimationGroupObserver); }, () => { newAnimationGroupObserverRemoved = true; });
+                }
+                if (!removedAnimationGroupObserverRemoved) {
+                    attempt(() => { scene.onAnimationGroupRemovedObservable.remove(removedAnimationGroupObserver); }, () => { removedAnimationGroupObserverRemoved = true; });
+                }
+                for (const group of [...automaticAnimationGroups.keys()].reverse()) {
+                    cleanupErrors.push(...detachAutomaticAnimationGroup(group));
+                }
+                if (!newMeshObserverRemoved) {
+                    attempt(() => { scene.onNewMeshAddedObservable.remove(newMeshObserver); }, () => { newMeshObserverRemoved = true; });
+                }
+                if (!removedMeshObserverRemoved) {
+                    attempt(() => { scene.onMeshRemovedObservable.remove(removedMeshObserver); }, () => { removedMeshObserverRemoved = true; });
+                }
+                if (!frameObserverRemoved) {
+                    attempt(() => { scene.onBeforeRenderObservable.remove(frameObserver); }, () => { frameObserverRemoved = true; });
+                }
+                if (hasOwnedBackendState()) {
+                    attempt(deactivate, () => undefined);
+                }
+                plan = null;
+                const observersRemoved = newMeshObserverRemoved
+                    && removedMeshObserverRemoved
+                    && frameObserverRemoved
+                    && newAnimationGroupObserverRemoved
+                    && removedAnimationGroupObserverRemoved
+                    && automaticAnimationGroups.size === 0;
+                if (observersRemoved && !hasOwnedBackendState()) {
+                    if (!activitySchedulerDisposed) {
+                        attempt(activityScheduler.dispose, () => { activitySchedulerDisposed = true; });
+                    }
+                    if (!depthRefreshSchedulerDisposed) {
+                        attempt(depthRefreshScheduler.dispose, () => { depthRefreshSchedulerDisposed = true; });
+                    }
+                    if (!influenceCullingDisposed) {
+                        attempt(influenceCulling.dispose, () => { influenceCullingDisposed = true; });
+                    }
+                }
+                cleanupComplete = observersRemoved
+                    && !hasOwnedBackendState()
+                    && activitySchedulerDisposed
+                    && depthRefreshSchedulerDisposed
+                    && influenceCullingDisposed;
+                if (cleanupComplete)
+                    disposed = true;
+                return Object.freeze(cleanupErrors);
+            };
+            const initializationCleanupErrors = cleanup();
+            if (initializationCleanupErrors.length > 0) {
+                throw createInitializationFailure(error, cleanup, initializationCleanupErrors);
+            }
+            throw error;
+        }
+    }
+    return system;
+}
+function createThresholdDiagnostics(plan, staticCasterCount, dynamicCasterCount) {
+    const thresholds = plan.diagnosticThresholds;
+    const result = [];
+    if (staticCasterCount > thresholds.staticCasterCountWarning) {
+        result.push({
+            code: 'shadowMapExperiment.staticCasterCountWarning',
+            message: `Static caster count ${staticCasterCount} exceeds the configured warning threshold ${thresholds.staticCasterCountWarning}.`,
+        });
+    }
+    if (dynamicCasterCount > thresholds.dynamicCasterCountWarning) {
+        result.push({
+            code: 'shadowMapExperiment.dynamicCasterCountWarning',
+            message: `Dynamic caster count ${dynamicCasterCount} exceeds the configured warning threshold ${thresholds.dynamicCasterCountWarning}.`,
+        });
+    }
+    const renderableCount = plan.objects.reduce((total, object) => total + object.renderableIds.length, 0);
+    if (renderableCount > thresholds.renderableCountWarning) {
+        result.push({
+            code: 'shadowMapExperiment.renderableCountWarning',
+            message: `Renderable count ${renderableCount} exceeds the configured warning threshold ${thresholds.renderableCountWarning}.`,
+        });
+    }
+    return Object.freeze(result.map(entry => Object.freeze(entry)));
+}
+function texelSize(lightSpaceSize, resolution) {
+    return Object.freeze([
+        lightSpaceSize[0] / resolution,
+        lightSpaceSize[1] / resolution,
+    ]);
+}
+function configureLight(light, plan, coverage) {
+    const direction = Vector3.FromArray(plan.light.direction).normalize();
+    if (direction.lengthSquared() < 1e-8)
+        throw new Error('shadowMapExperiment.lightDirectionInvalid');
+    const center = Vector3.FromArray(coverage.center);
+    const depth = (coverage.near + coverage.far) * 0.5;
+    const [width, height] = calculateLightSpaceSize(plan.light.direction, coverage.extent);
+    light.direction.copyFrom(direction);
+    light.position.copyFrom(center.subtract(direction.scale(depth)));
+    light.autoUpdateExtends = false;
+    light.orthoLeft = -width * 0.5;
+    light.orthoRight = width * 0.5;
+    light.orthoBottom = -height * 0.5;
+    light.orthoTop = height * 0.5;
+    light.shadowMinZ = coverage.near;
+    light.shadowMaxZ = coverage.far;
+}
+function createSceneFitCoverage(plan, bounds) {
+    const min = Vector3.FromArray(bounds.min);
+    const max = Vector3.FromArray(bounds.max);
+    const rawExtent = max.subtract(min);
+    const maxExtent = Math.max(rawExtent.x, rawExtent.y, rawExtent.z, 1);
+    const padding = Math.max(0.5, maxExtent * 0.05);
+    const extent = Object.freeze([
+        Math.max(4, rawExtent.x + padding * 2),
+        Math.max(4, rawExtent.y + padding * 2),
+        Math.max(4, rawExtent.z + padding * 2),
+    ]);
+    const near = Math.min(plan.generator.bounds.near, 0.1);
+    const far = Math.max(plan.generator.bounds.far, Math.hypot(extent[0], extent[1], extent[2]) + padding * 2);
+    const center = snapSceneFitCenterToTexels(plan, vectorTuple(min.add(max).scale(0.5)), extent, near, far);
+    return Object.freeze({ center, extent, near, far });
+}
+function collectActiveCasterWorldBounds(bindings, registry) {
+    let min = null;
+    let max = null;
+    for (const binding of bindings.values()) {
+        if (registry?.getRecord(binding.renderableId)?.state !== 'active')
+            continue;
+        if (!isMeshRuntimeVisible(binding.mesh))
+            continue;
+        const bounds = readStableMeshWorldBounds(binding);
+        if (!bounds)
+            continue;
+        const boundsMin = Vector3.FromArray(bounds.min);
+        const boundsMax = Vector3.FromArray(bounds.max);
+        min = min ? Vector3.Minimize(min, boundsMin) : boundsMin;
+        max = max ? Vector3.Maximize(max, boundsMax) : boundsMax;
+    }
+    return min && max
+        ? Object.freeze({ min: vectorTuple(min), max: vectorTuple(max) })
+        : null;
+}
+function createLightSpaceBasis(direction) {
+    const upSeed = Math.abs(Vector3.Dot(direction, Vector3.Up())) > 0.98 ? Vector3.Forward() : Vector3.Up();
+    const right = Vector3.Cross(upSeed, direction).normalize();
+    const up = Vector3.Cross(direction, right).normalize();
+    return { right, up };
+}
+function snapSceneFitCenterToTexels(plan, centerValue, extentValue, near, far) {
+    const direction = Vector3.FromArray(plan.light.direction).normalize();
+    const { right, up } = createLightSpaceBasis(direction);
+    const center = Vector3.FromArray(centerValue);
+    const [width, height] = calculateLightSpaceSize(plan.light.direction, extentValue);
+    const resolution = Math.max(1, plan.generator.maps.compositeResolution);
+    const depth = Math.max(far - near, 1e-4);
+    const snap = (value, step) => Math.round(value / step) * step;
+    const rightValue = snap(Vector3.Dot(center, right), width / resolution);
+    const upValue = snap(Vector3.Dot(center, up), height / resolution);
+    const depthValue = snap(Vector3.Dot(center, direction), depth / resolution);
+    const result = right.scale(rightValue).add(up.scale(upValue)).add(direction.scale(depthValue));
+    return vectorTuple(result);
+}
+function areTuple3Equal(left, right) {
+    return left.every((value, index) => Math.abs(value - right[index]) <= 1e-8);
+}
+function calculateLightSpaceSize(directionValue, extent) {
+    const direction = Vector3.FromArray(directionValue).normalize();
+    const { right, up } = createLightSpaceBasis(direction);
+    const half = new Vector3(extent[0] * 0.5, extent[1] * 0.5, extent[2] * 0.5);
+    let width = 0;
+    let height = 0;
+    for (const x of [-half.x, half.x]) {
+        for (const y of [-half.y, half.y]) {
+            for (const z of [-half.z, half.z]) {
+                const corner = new Vector3(x, y, z);
+                width = Math.max(width, Math.abs(Vector3.Dot(corner, right)) * 2);
+                height = Math.max(height, Math.abs(Vector3.Dot(corner, up)) * 2);
+            }
+        }
+    }
+    return Object.freeze([Math.max(width, 1e-4), Math.max(height, 1e-4)]);
+}
+function resolveDirectionalLight(scene, entityId) {
+    for (const light of scene.lights) {
+        if (!isBabylonDirectionalLight(light))
+            continue;
+        if (collectIdentityCandidates(light).has(entityId))
+            return light;
+    }
+    return null;
+}
+function isBabylonDirectionalLight(light) {
+    if (light instanceof DirectionalLight)
+        return true;
+    if (!isRecord(light) || typeof light.getClassName !== 'function')
+        return false;
+    try {
+        return light.getClassName() === 'DirectionalLight';
+    }
+    catch {
+        return false;
+    }
+}
+function resolveRenderableId(mesh, objectByRenderable) {
+    let current = mesh;
+    while (current) {
+        for (const candidate of collectIdentityCandidates(current)) {
+            if (objectByRenderable.has(candidate))
+                return candidate;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+function collectIdentityCandidates(node) {
+    const candidates = new Set();
+    if (node.id)
+        candidates.add(node.id);
+    if (node.name)
+        candidates.add(node.name);
+    const metadata = isRecord(node.metadata) ? node.metadata : null;
+    if (!metadata)
+        return candidates;
+    addIdentityCandidatesFromRecord(candidates, metadata);
+    const projection = isRecord(metadata.editorProjection) ? metadata.editorProjection : null;
+    if (projection)
+        addIdentityCandidatesFromRecord(candidates, projection);
+    const editorSource = isRecord(metadata.__fpsEditor) ? metadata.__fpsEditor : null;
+    if (editorSource)
+        addIdentityCandidatesFromRecord(candidates, editorSource);
+    const sourceBinding = isRecord(metadata.sourceBinding) ? metadata.sourceBinding : null;
+    if (sourceBinding)
+        addIdentityCandidatesFromRecord(candidates, sourceBinding);
+    return candidates;
+}
+function addIdentityCandidatesFromRecord(candidates, record) {
+    for (const key of [
+        'entityId',
+        'renderableId',
+        'runtimeNodeId',
+        'nodeId',
+        'rootNodeId',
+        'objectId',
+        'sourceId',
+    ]) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim())
+            candidates.add(value);
+    }
+}
+function meshIdentityChainContains(mesh, identity) {
+    let current = mesh;
+    while (current) {
+        if (collectIdentityCandidates(current).has(identity))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+function isReceiverEligible(mesh) {
+    const metadata = isRecord(mesh.metadata) ? mesh.metadata : null;
+    const projection = metadata && isRecord(metadata.editorProjection) ? metadata.editorProjection : null;
+    if (metadata?.helper === true || projection?.helper === true)
+        return false;
+    const material = mesh.material;
+    if (!material)
+        return true;
+    if ('disableLighting' in material && material.disableLighting === true)
+        return false;
+    try {
+        if (material.needAlphaBlendingForMesh(mesh))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function resolveReceiverTarget(mesh) {
+    const sourceMesh = mesh.sourceMesh;
+    return sourceMesh && !isDisposed(sourceMesh) ? sourceMesh : mesh;
+}
+function readWorldMatrixSnapshot(mesh) {
+    const matrix = mesh.getWorldMatrix?.();
+    if (!matrix || typeof matrix.asArray !== 'function')
+        return null;
+    return [...matrix.asArray()];
+}
+function areMatrixSnapshotsEqual(previous, next) {
+    if (previous === next)
+        return true;
+    if (!previous || !next || previous.length !== next.length)
+        return false;
+    for (let index = 0; index < previous.length; index += 1) {
+        if (previous[index] !== next[index])
+            return false;
+    }
+    return true;
+}
+function isMeshRuntimeVisible(mesh) {
+    return !isDisposed(mesh) && mesh.isEnabled() && mesh.isVisible && mesh.visibility > 0;
+}
+function isDisposed(mesh) {
+    return typeof mesh.isDisposed === 'function' && mesh.isDisposed();
+}
+function readMeshLocalBounds(mesh) {
+    try {
+        const bounds = mesh.getBoundingInfo?.().boundingBox;
+        if (!bounds)
+            return null;
+        const min = bounds.minimum;
+        const max = bounds.maximum;
+        if (![min.x, min.y, min.z, max.x, max.y, max.z].every(Number.isFinite))
+            return null;
+        return Object.freeze({ min: vectorTuple(min), max: vectorTuple(max) });
+    }
+    catch {
+        return null;
+    }
+}
+function readStableMeshWorldBounds(binding) {
+    const local = binding.sceneFitLocalBounds;
+    if (!local)
+        return readMeshWorldBounds(binding.mesh);
+    try {
+        binding.mesh.computeWorldMatrix(false);
+        const matrix = binding.mesh.getWorldMatrix();
+        const min = Vector3.FromArray(local.min);
+        const max = Vector3.FromArray(local.max);
+        let worldMin = null;
+        let worldMax = null;
+        for (const x of [min.x, max.x]) {
+            for (const y of [min.y, max.y]) {
+                for (const z of [min.z, max.z]) {
+                    const point = Vector3.TransformCoordinates(new Vector3(x, y, z), matrix);
+                    worldMin = worldMin ? Vector3.Minimize(worldMin, point) : point;
+                    worldMax = worldMax ? Vector3.Maximize(worldMax, point) : point;
+                }
+            }
+        }
+        return worldMin && worldMax
+            ? Object.freeze({ min: vectorTuple(worldMin), max: vectorTuple(worldMax) })
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readMeshWorldBounds(mesh) {
+    try {
+        mesh.computeWorldMatrix(false);
+        const bounds = mesh.getBoundingInfo?.().boundingBox;
+        if (!bounds)
+            return null;
+        const min = bounds.minimumWorld;
+        const max = bounds.maximumWorld;
+        if (![min.x, min.y, min.z, max.x, max.y, max.z].every(Number.isFinite))
+            return null;
+        return Object.freeze({ min: vectorTuple(min), max: vectorTuple(max) });
+    }
+    catch {
+        return null;
+    }
+}
+function isDeformableCaster(mesh, updateClass) {
+    const deformable = mesh;
+    return updateClass === 'skinned' || Boolean(deformable.skeleton) || Boolean(deformable.morphTargetManager);
+}
+function createMeshDataCache(mesh, caches) {
+    const cache = {};
+    caches.set(mesh, cache);
+    return cache;
+}
+function readCasterWorldBounds(mesh, deformable, cache) {
+    if (deformable) {
+        const deformableMesh = mesh;
+        const applySkeleton = Boolean(deformableMesh.skeleton);
+        const applyMorph = Boolean(deformableMesh.morphTargetManager);
+        if (applySkeleton || applyMorph) {
+            try {
+                mesh.refreshBoundingInfo({
+                    applySkeleton,
+                    applyMorph,
+                    updatePositionsArray: false,
+                    ...(cache ? { cache } : {}),
+                });
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return readMeshWorldBounds(mesh);
+}
+function readCameraProjectionSignature(camera, scene) {
+    const projection = camera.getProjectionMatrix().asArray()
+        .map(value => Number.isFinite(value) ? value.toFixed(5) : String(value))
+        .join(',');
+    const engine = scene.getEngine();
+    return `${camera.mode}:${engine.getRenderWidth()}:${engine.getRenderHeight()}:${projection}`;
+}
+function calculateCameraShadowCoverage(camera, plan, centerValue = plan.generator.bounds.center, extentValue = plan.generator.bounds.extent) {
+    try {
+        const fixedMin = Vector3.FromArray(centerValue).subtract(Vector3.FromArray(extentValue).scale(0.5));
+        const fixedMax = Vector3.FromArray(centerValue).add(Vector3.FromArray(extentValue).scale(0.5));
+        const inverse = Matrix.Invert(camera.getTransformationMatrix());
+        const engine = camera.getScene().getEngine();
+        const ndcNearZ = engine.isNDCHalfZRange ? 0 : -1;
+        const frustumCorners = [];
+        for (const x of [-1, 1]) {
+            for (const y of [-1, 1]) {
+                for (const z of [ndcNearZ, 1]) {
+                    frustumCorners.push(Vector3.TransformCoordinates(new Vector3(x, y, z), inverse));
+                }
+            }
+        }
+        const frustumMin = frustumCorners.reduce((result, point) => Vector3.Minimize(result, point), frustumCorners[0].clone());
+        const frustumMax = frustumCorners.reduce((result, point) => Vector3.Maximize(result, point), frustumCorners[0].clone());
+        const min = Vector3.Maximize(frustumMin, fixedMin);
+        const max = Vector3.Minimize(frustumMax, fixedMax);
+        if (min.x > max.x || min.y > max.y || min.z > max.z)
+            return null;
+        return Object.freeze({ min: vectorTuple(min), max: vectorTuple(max) });
+    }
+    catch {
+        return null;
+    }
+}
+function vectorTuple(value) {
+    return Object.freeze([value.x, value.y, value.z]);
+}
+function classifyAutomaticActivityTarget(target, bindings) {
+    const className = readBabylonClassName(target);
+    if (className === 'MorphTarget')
+        return 'morph';
+    if (className === 'Bone' || hasFunction(target, 'getSkeleton'))
+        return 'animation';
+    if (resolveAutomaticActivityTargetSkeletons(bindings, target).size > 0)
+        return 'animation';
+    return 'transform';
+}
+function resolveAutomaticActivityTargetMeshes(_scene, bindings, target, kind) {
+    const resolved = new Set();
+    if (!target || (typeof target !== 'object' && typeof target !== 'function'))
+        return resolved;
+    if (kind === 'animation') {
+        const skeletons = resolveAutomaticActivityTargetSkeletons(bindings, target);
+        if (skeletons.size === 0)
+            return resolved;
+        for (const mesh of bindings.keys()) {
+            if (skeletons.has(mesh.skeleton))
+                resolved.add(mesh);
+        }
+        return resolved;
+    }
+    if (kind === 'morph') {
+        for (const mesh of bindings.keys()) {
+            const manager = mesh.morphTargetManager;
+            const count = manager?.numTargets ?? 0;
+            if (!manager?.getTarget || !Number.isInteger(count) || count < 1)
+                continue;
+            for (let index = 0; index < count; index += 1) {
+                if (manager.getTarget(index) === target) {
+                    resolved.add(mesh);
+                    break;
+                }
+            }
+        }
+        return resolved;
+    }
+    for (const mesh of bindings.keys()) {
+        if (mesh === target
+            || isBabylonNodeDescendantOf(mesh, target)
+            || isBabylonNodeDescendantOf(target, mesh)) {
+            resolved.add(mesh);
+        }
+    }
+    return resolved;
+}
+function resolveAutomaticActivityTargetSkeletons(bindings, target) {
+    const skeletons = new Set();
+    const directSkeleton = callOptional(target, 'getSkeleton')
+        ?? target?._skeleton
+        ?? null;
+    if (directSkeleton)
+        skeletons.add(directSkeleton);
+    for (const mesh of bindings.keys()) {
+        const skeleton = mesh.skeleton;
+        if (!skeleton || skeletons.has(skeleton))
+            continue;
+        for (const bone of skeleton.bones ?? []) {
+            if (bone === target
+                || callOptional(bone, 'getTransformNode') === target
+                || bone?._linkedTransformNode === target) {
+                skeletons.add(skeleton);
+                break;
+            }
+        }
+    }
+    return skeletons;
+}
+function readBabylonClassName(value) {
+    const className = callOptional(value, 'getClassName');
+    return typeof className === 'string' ? className : null;
+}
+function isBabylonNodeDescendantOf(value, ancestor) {
+    if (!hasFunction(value, 'isDescendantOf'))
+        return false;
+    try {
+        return value.isDescendantOf(ancestor);
+    }
+    catch {
+        return false;
+    }
+}
+function hasFunction(value, key) {
+    return Boolean(value)
+        && (typeof value === 'object' || typeof value === 'function')
+        && typeof value[key] === 'function';
+}
+function callOptional(value, key) {
+    if (!hasFunction(value, key))
+        return undefined;
+    try {
+        return value[key]();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isStaticDirtyReason(reason) {
+    return reason === 'static-transform-changed'
+        || reason === 'static-geometry-changed'
+        || reason === 'static-depth-invalidated';
+}
+function isDynamicDirtyReason(reason) {
+    return reason === 'dynamic-transform-changed'
+        || reason === 'caster-activity-started'
+        || reason === 'caster-activity-stopped'
+        || reason === 'dynamic-frame'
+        || reason === 'skinned-animation-frame'
+        || reason === 'morph-animation-frame'
+        || reason === 'physics-motion-frame'
+        || reason === 'dynamic-depth-invalidated';
+}
+function dirtyReasonForActivityKind(kind) {
+    switch (kind) {
+        case 'animation': return 'skinned-animation-frame';
+        case 'morph': return 'morph-animation-frame';
+        case 'physics': return 'physics-motion-frame';
+        case 'transform': return 'dynamic-frame';
+    }
+}
+function captureLight(light) {
+    return {
+        light,
+        direction: light.direction.clone(),
+        position: light.position.clone(),
+        autoUpdateExtends: light.autoUpdateExtends,
+        shadowEnabled: light.shadowEnabled,
+        orthoLeft: light.orthoLeft,
+        orthoRight: light.orthoRight,
+        orthoTop: light.orthoTop,
+        orthoBottom: light.orthoBottom,
+        shadowMinZ: light.shadowMinZ,
+        shadowMaxZ: light.shadowMaxZ,
+    };
+}
+function restoreLight(state) {
+    const light = state.light;
+    if (light.isDisposed())
+        return;
+    light.direction.copyFrom(state.direction);
+    light.position.copyFrom(state.position);
+    light.autoUpdateExtends = state.autoUpdateExtends;
+    light.shadowEnabled = state.shadowEnabled;
+    light.orthoLeft = state.orthoLeft;
+    light.orthoRight = state.orthoRight;
+    light.orthoTop = state.orthoTop;
+    light.orthoBottom = state.orthoBottom;
+    light.shadowMinZ = state.shadowMinZ;
+    light.shadowMaxZ = state.shadowMaxZ;
+}
+function readShadowGenerators(light) {
+    const generators = light.getShadowGenerators?.();
+    if (!generators)
+        return [];
+    if (Array.isArray(generators))
+        return generators;
+    if (generators instanceof Map)
+        return [...generators.values()];
+    return [];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function attachFailureMetadata(error, metadata) {
+    try {
+        Object.assign(error, metadata);
+    }
+    catch {
+        // Error annotation is diagnostic only; it must never replace the primary failure.
+    }
+}
+function createInitializationFailure(error, cleanup, initializationCleanupErrors) {
+    const metadata = {
+        initializationCleanupErrors: Object.freeze([...initializationCleanupErrors]),
+        shadowMapExperimentSystemCleanup: cleanup,
+    };
+    if (error && (typeof error === 'object' || typeof error === 'function')) {
+        try {
+            Object.assign(error, metadata);
+            if (readBabylonShadowMapExperimentSystemCleanup(error) === cleanup)
+                return error;
+        }
+        catch {
+            // A non-extensible primary error is wrapped below so cleanup ownership remains reachable.
+        }
+    }
+    const failure = new Error(error instanceof Error ? error.message : 'shadowMapExperiment.initializationFailed');
+    return Object.assign(failure, { cause: error, ...metadata });
+}
+function createRuntimeRegistrationRollbackFailure(error, owner, rollbackErrors) {
+    const metadata = {
+        rollbackErrors: Object.freeze([...rollbackErrors]),
+        runtimeShadowObjectsRecoveryOwner: owner,
+    };
+    if (error && (typeof error === 'object' || typeof error === 'function')) {
+        try {
+            Object.assign(error, metadata);
+            if (readBabylonRuntimeShadowObjectsRecoveryOwner(error) === owner)
+                return error;
+        }
+        catch {
+            // A non-extensible primary error is wrapped below so recovery ownership remains reachable.
+        }
+    }
+    const failure = new Error(error instanceof Error ? error.message : 'shadowMapExperiment.runtimeRegistrationFailed');
+    return Object.assign(failure, { cause: error, ...metadata });
+}
+//# sourceMappingURL=shadow-map-experiment-system.js.map