@fps-games/engine 0.0.1-beta.5 → 0.0.1-beta.8

package/dist/babylon/renderer/shadows/shadow-map-experiment-system.js

@@ -0,0 +1,4529 @@
+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, resolveShadowMapExperimentAppearance, createShadowMapExperimentActivityScheduler, createShadowMapExperimentDepthRefreshScheduler, createShadowMapExperimentInfluenceCullingState, createShadowMapExperimentRegistry, diffShadowMapExperimentPlans, shadowMapExperimentDepthLayerForUpdateClass, } from '../../../rendering/index.js';
+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 runtimeIncrementalMutationCount = 0;
+    let effectivePlanMaterializationCount = 0;
+    let materializedEffectivePlan = null;
+    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 pendingMeshObserverRestorations = new Map();
+    const pendingMeshRegistrationRollbacks = new Set();
+    const pendingSceneMeshRegistrations = new Set();
+    const pendingMeshUnregistrations = new Set();
+    const pendingRenderableMembershipRetries = new Map();
+    const pendingExplicitVisibility = new Map();
+    const pendingTransformMembershipRetries = new Set();
+    const activeCasterEntityIds = new Set();
+    const activeDeformationSourceCountByEntity = new Map();
+    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;
+    // Scene-fit bounds are read only at an explicit membership invalidation
+    // boundary, never by an otherwise idle render frame.
+    let sceneFitCoverageInvalidated = options.coverageMode === 'scene-fit';
+    let syncingSceneFitMembership = 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 automaticActivityCandidateBindings = new Map();
+    const receiverStates = new Map();
+    const receiverTargetByMesh = new Map();
+    // The target, rather than the requesting mesh, owns a failed receiver write:
+    // several source meshes can resolve to the same Babylon receiver.
+    const pendingReceiverRestorations = new Map();
+    const receiverRestorationAttemptsThisFlush = new Set();
+    const diagnostics = [];
+    const diagnosticKeys = new Set();
+    const runtimeRegistrations = new Map();
+    const sceneOwnedMeshes = new Set(scene.meshes);
+    const runtimeOwnedMeshes = new Set();
+    const explicitRuntimeActivityEntityIds = new Set();
+    const automaticAnimationGroups = new Map();
+    const automaticAnimationGroupsByResolvedTarget = new Map();
+    const automaticAnimationGroupsByResolvedTargetAncestor = new Map();
+    const automaticAnimationGroupsByResolvedTargetRenderable = new Map();
+    // Failed dormant source or full-detach cleanup is the only automatic-
+    // activity work allowed to wake the frame hook. Normal playback is event-driven.
+    const pendingAutomaticAnimationGroupSourceCleanups = new Set();
+    const pendingAutomaticAnimationGroupDetachCleanups = new Set();
+    const pendingAutomaticAnimationGroupReconciliations = new Set();
+    const pendingAutomaticAnimationGroupAttachments = new Set();
+    let pendingAutomaticActivityCandidateTransition = null;
+    let automaticActivityCandidateRevision = 0;
+    let automaticActivityTargetResolutionCount = 0;
+    let suppressAutomaticActivityCandidateRevision = false;
+    let stagingPlanCandidateTransitions = false;
+    let applyAutomaticActivityCandidateTransition = () => false;
+    let flushPendingAutomaticActivityCandidateTransition = () => { };
+    let flushingRefresh = false;
+    let pendingPlanRollbackRecovery = null;
+    let activatingRecoveryPlan = null;
+    let allowingRecoveryActivityRegistration = false;
+    const bumpAutomaticActivityCandidateRevision = () => {
+        if (suppressAutomaticActivityCandidateRevision)
+            return;
+        automaticActivityCandidateRevision += 1;
+    };
+    const isAutomaticActivityCandidateObject = (object) => object?.cast === true
+        && object.updateClass !== 'static'
+        && !explicitRuntimeActivityEntityIds.has(object.entityId);
+    const haveSameAutomaticActivityCandidates = (left, right, leftCandidateObjects = left.objects) => {
+        // Incremental runtime mutations intentionally leave `plan.objects` as the
+        // authored operational snapshot and advance only its revision.  An
+        // authored update, on the other hand, arrives as a fully composed Plan.
+        // Compare the same candidate topology without forcing the operational
+        // snapshot to materialize every runtime overlay object.
+        const signature = (objects) => objects
+            .filter(isAutomaticActivityCandidateObject)
+            .flatMap(object => object.renderableIds.map(renderableId => `${object.entityId}\u0000${renderableId}\u0000${object.updateClass}`))
+            .sort();
+        const leftCandidates = signature(leftCandidateObjects);
+        const rightCandidates = signature(right.objects);
+        return leftCandidates.length === rightCandidates.length
+            && leftCandidates.every((candidate, index) => candidate === rightCandidates[index]);
+    };
+    const updateAutomaticActivityCandidateBinding = (candidateView, binding, object) => {
+        // Candidate topology describes which registered meshes can ever provide
+        // automatic activity. Runtime visibility only controls caster membership
+        // and entity eligibility; it must not invalidate every AnimationGroup
+        // binding when a runtime state temporarily hides a model.
+        const shouldTrack = isAutomaticActivityCandidateObject(object);
+        const existing = candidateView.get(binding.mesh);
+        const tracked = existing !== undefined;
+        // A mesh can keep the same Babylon identity while its plan renderable is
+        // reassigned to another entity.  Treat that as a topology transition too:
+        // the automatic source belongs to the entity, not just to the mesh.
+        if (shouldTrack && tracked
+            && existing.entityId === binding.entityId
+            && existing.renderableId === binding.renderableId)
+            return false;
+        if (!shouldTrack && !tracked)
+            return false;
+        if (shouldTrack)
+            candidateView.set(binding.mesh, binding);
+        else
+            candidateView.delete(binding.mesh);
+        return true;
+    };
+    const syncAutomaticActivityCandidateBindingsForRenderable = (renderableId) => {
+        const object = objectByRenderable.get(renderableId);
+        const renderableBindings = [...(meshesByRenderable.get(renderableId) ?? [])]
+            .flatMap(mesh => {
+            const binding = bindings.get(mesh);
+            return binding ? [binding] : [];
+        });
+        const alreadySynchronized = renderableBindings.every(binding => {
+            const existing = automaticActivityCandidateBindings.get(binding.mesh);
+            if (!isAutomaticActivityCandidateObject(object))
+                return existing === undefined;
+            return existing?.entityId === binding.entityId
+                && existing.renderableId === binding.renderableId;
+        });
+        if (alreadySynchronized)
+            return false;
+        const nextCandidates = new Map(automaticActivityCandidateBindings);
+        let changed = false;
+        for (const binding of renderableBindings) {
+            changed = updateAutomaticActivityCandidateBinding(nextCandidates, binding, object) || changed;
+        }
+        if (changed && !applyAutomaticActivityCandidateTransition(nextCandidates)) {
+            throw new Error('shadowMapExperiment.automaticActivityCandidateCommitFailed');
+        }
+        return changed;
+    };
+    const assertUsable = (allowDisposing = false) => {
+        if (disposed || (disposing && !allowDisposing))
+            throw new Error('shadowMapExperiment.systemDisposed');
+    };
+    const assertNoPlanRollbackRecovery = () => {
+        if (pendingPlanRollbackRecovery) {
+            throw new Error('shadowMapExperiment.planRollbackRecoveryPending');
+        }
+    };
+    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 = createRuntimePlanObjects(basePlan, records);
+        return Object.freeze({
+            ...basePlan,
+            revision: basePlan.revision + overlayRevision,
+            objects: Object.freeze([...basePlan.objects, ...runtimeObjects]
+                .sort((left, right) => left.entityId.localeCompare(right.entityId))),
+        });
+    };
+    const createRuntimePlanObjects = (basePlan, records) => Object.freeze(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,
+        });
+    }));
+    const invalidateMaterializedEffectivePlan = () => {
+        materializedEffectivePlan = null;
+    };
+    const readMaterializedEffectivePlan = () => {
+        if (!sourcePlan || !plan)
+            return null;
+        if (!materializedEffectivePlan) {
+            materializedEffectivePlan = composeEffectivePlan(sourcePlan, [...runtimeRegistrations.values()].filter(record => !record.disposed), runtimeOverlayRevision);
+            effectivePlanMaterializationCount += 1;
+        }
+        return materializedEffectivePlan;
+    };
+    const updateOperationalPlanRevision = (overlayRevision) => {
+        if (!plan || !sourcePlan)
+            return;
+        plan = Object.freeze({
+            ...plan,
+            revision: sourcePlan.revision + overlayRevision,
+        });
+        invalidateMaterializedEffectivePlan();
+    };
+    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 markCompositeDepthDirty = (reason) => {
+        depthRefreshScheduler.markCompositeDirty(reason);
+        requestRefreshFrame(`shadow-map-experiment-${reason}`);
+    };
+    const invalidateSceneFitBounds = (renderableIds = null, refreshLocalBounds = false) => {
+        if (options.coverageMode !== 'scene-fit')
+            return;
+        const selected = renderableIds ? new Set(renderableIds) : null;
+        if (refreshLocalBounds) {
+            for (const binding of bindings.values()) {
+                if (!selected || selected.has(binding.renderableId)) {
+                    binding.sceneFitLocalBounds = readMeshLocalBounds(binding.mesh);
+                }
+            }
+        }
+        sceneFitCoverageInvalidated = true;
+    };
+    const syncSceneFitCoverage = (force = false) => {
+        if (!plan?.enabled || !lightState || options.coverageMode !== 'scene-fit')
+            return;
+        if (!force && !sceneFitCoverageInvalidated)
+            return;
+        const sceneBounds = collectActiveCasterWorldBounds(bindings, registry);
+        if (!sceneBounds) {
+            sceneFitCoverageInvalidated = false;
+            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) {
+            sceneFitCoverageInvalidated = false;
+            return;
+        }
+        effectiveCoverageCenter = nextCoverage.center;
+        effectiveCoverageExtent = nextCoverage.extent;
+        effectiveCoverageNear = nextCoverage.near;
+        effectiveCoverageFar = nextCoverage.far;
+        configureLight(lightState.light, plan, nextCoverage);
+        pendingCoverageMembershipRebuild = true;
+        sceneFitCoverageInvalidated = false;
+        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;
+        receiverRestorationAttemptsThisFlush.clear();
+        try {
+            // Recovery owns the old transaction until cleanup and (when applicable)
+            // reactivation have both completed. Do one bounded attempt and leave all
+            // ordinary queues untouched until that ownership is released.
+            if (pendingPlanRollbackRecovery) {
+                flushPendingPlanRollbackRecovery();
+                return;
+            }
+            flushPendingReceiverRestorations();
+            // No animation group is polled during normal rendering.  A frame retry
+            // exists only while a previous observer/source teardown is incomplete.
+            flushPendingAutomaticAnimationGroupDetachCleanups();
+            if (pendingAutomaticActivityCandidateTransition
+                && pendingMeshUnregistrations.size === 0
+                && pendingRenderableMembershipRetries.size === 0) {
+                // One candidate-transition retry gets one cleanup attempt per frame.
+                // Running the generic cleanup queue again in the same frame would
+                // collapse consecutive retry boundaries and could spin on a failing
+                // disposer. A mesh-unregistration owner retries the transition from
+                // inside its own backend/observer/registry journal instead.
+                flushPendingAutomaticActivityCandidateTransition();
+            }
+            else if (!pendingAutomaticActivityCandidateTransition) {
+                flushPendingAutomaticAnimationGroupSourceCleanups();
+            }
+            flushPendingAutomaticAnimationGroupAttachments();
+            flushPendingAutomaticAnimationGroupReconciliations();
+            flushPendingMeshObserverCleanups();
+            flushPendingMeshRegistrationRollbacks();
+            flushPendingBackendAllocationCleanup();
+            recoverPendingFallbackBackend();
+            if (!depthBackend || !registry)
+                return;
+            downgradeFailedSplitBackend();
+            if (!depthBackend)
+                return;
+            flushPendingMeshUnregistrations();
+            flushPendingSceneMeshRegistrations();
+            flushPendingRenderableMembershipRetries();
+            flushPendingTransformMembershipRetries();
+            flushMembershipInvalidations();
+            registry.consumeDirtyReasons();
+            const activityDecision = activityScheduler.consumeFrameDecision();
+            resyncExplicitDeformationMembership();
+            for (const reason of activityDecision.reasons)
+                routeDirtyReason(reason);
+            // Membership and deformation invalidations refresh local bounds first;
+            // scene-fit consumes the resulting committed topology once per event.
+            syncSceneFitCoverage();
+            updateCameraInfluenceCoverage();
+            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 {
+            receiverRestorationAttemptsThisFlush.clear();
+            if (pendingPlanRollbackRecovery) {
+                postFlushFrameReason = 'shadow-map-experiment-plan-rollback-recovery';
+            }
+            const pendingFallbackRecovery = pendingFallbackReason !== null
+                && depthBackend === null
+                && plan?.enabled === true
+                && plan.generator.backend.fallback !== 'disable';
+            if (!postFlushFrameReason
+                && (pendingAutomaticActivityCandidateTransition !== null
+                    || pendingAutomaticAnimationGroupSourceCleanups.size > 0
+                    || pendingAutomaticAnimationGroupDetachCleanups.size > 0
+                    || pendingAutomaticAnimationGroupAttachments.size > 0
+                    || pendingAutomaticAnimationGroupReconciliations.size > 0
+                    || pendingSceneMeshRegistrations.size > 0
+                    || pendingMeshRegistrationRollbacks.size > 0
+                    || pendingMeshObserverCleanups.size > 0
+                    || pendingMeshObserverRestorations.size > 0
+                    || pendingReceiverRestorations.size > 0
+                    || pendingBackendAllocationCleanup !== null
+                    || pendingFallbackRecovery
+                    || pendingMeshUnregistrations.size > 0
+                    || pendingRenderableMembershipRetries.size > 0
+                    || pendingTransformMembershipRetries.size > 0
+                    || pendingFinalDeformationEntityIds.size > 0
+                    || pendingDeformationInvalidations.size > 0
+                    || pendingCoverageMembershipRebuild
+                    || pendingMembershipInvalidationLayers.size > 0)) {
+                postFlushFrameReason = pendingAutomaticActivityCandidateTransition !== null
+                    || pendingAutomaticAnimationGroupSourceCleanups.size > 0
+                    || pendingAutomaticAnimationGroupDetachCleanups.size > 0
+                    || pendingAutomaticAnimationGroupAttachments.size > 0
+                    || pendingAutomaticAnimationGroupReconciliations.size > 0
+                    ? 'shadow-map-experiment-automatic-activity-cleanup-retry'
+                    : pendingReceiverRestorations.size > 0
+                        ? 'shadow-map-experiment-receiver-restoration-retry'
+                        : pendingBackendAllocationCleanup !== null
+                            ? 'shadow-map-experiment-backend-allocation-cleanup-retry'
+                            : pendingFallbackRecovery
+                                ? 'shadow-map-experiment-fallback-retry'
+                                : 'shadow-map-experiment-membership-retry';
+            }
+            flushingRefresh = false;
+            if (postFlushFrameReason)
+                requestRefreshFrame(postFlushFrameReason);
+        }
+    };
+    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);
+    };
+    const shouldRetainCaster = (mesh, updateClass, reuseCachedBounds = false) => {
+        if (plan?.culling.enabled === false) {
+            conservativeCasterMeshes.delete(mesh);
+            return true;
+        }
+        const deformable = isDeformableCaster(mesh, updateClass);
+        const binding = bindings.get(mesh);
+        let currentBoundingInfo;
+        try {
+            currentBoundingInfo = mesh.getBoundingInfo();
+        }
+        catch {
+            currentBoundingInfo = undefined;
+        }
+        const canReuseBounds = reuseCachedBounds
+            && binding?.influenceWorldBounds !== undefined
+            && binding.influenceBoundingInfo === currentBoundingInfo;
+        const bounds = canReuseBounds
+            ? binding.influenceWorldBounds ?? null
+            : readCasterWorldBounds(mesh, deformable, deformable
+                ? meshDataCacheByMesh.get(mesh) ?? createMeshDataCache(mesh, meshDataCacheByMesh)
+                : null);
+        if (binding && !canReuseBounds) {
+            binding.influenceWorldBounds = bounds;
+            binding.influenceBoundingInfo = currentBoundingInfo;
+        }
+        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 resyncExplicitDeformationMembership = () => {
+        const finalEntityIds = [...pendingFinalDeformationEntityIds];
+        const deformationInvalidations = [...pendingDeformationInvalidations.entries()];
+        if (finalEntityIds.length === 0 && deformationInvalidations.length === 0)
+            return;
+        const renderableIds = new Set();
+        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);
+        if (renderableIds.size > 0)
+            invalidateSceneFitBounds(renderableIds, true);
+        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;
+        const casterRenderableIds = new Set();
+        for (const mesh of candidateLayerByMesh.keys()) {
+            const binding = bindings.get(mesh);
+            if (binding)
+                casterRenderableIds.add(binding.renderableId);
+        }
+        for (const renderableId of casterRenderableIds)
+            syncCaster(renderableId, true);
+        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 {
+            syncingSceneFitMembership = true;
+            changedLayers = resyncAllCasterMembership();
+            pendingCoverageMembershipRebuild = false;
+        }
+        catch (error) {
+            pendingCoverageMembershipRebuild = true;
+            cullingStable = false;
+            throw error;
+        }
+        finally {
+            syncingSceneFitMembership = false;
+        }
+        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;
+        try {
+            failedBackend.dispose();
+        }
+        catch (error) {
+            depthBackend = null;
+            generator = null;
+            pendingFallbackReason = runtimeFailureReason;
+            pendingBackendAllocationCleanup = () => {
+                try {
+                    failedBackend.dispose();
+                    return Object.freeze([]);
+                }
+                catch (retryError) {
+                    return Object.freeze([retryError]);
+                }
+            };
+            throw error;
+        }
+        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, reuseCachedBounds = false) => {
+        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();
+        const previousMembership = [...meshes].map(mesh => ({
+            mesh,
+            candidateLayer: candidateLayerByMesh.get(mesh) ?? null,
+            staticCaster: depthBackend.hasCaster(mesh, 'static'),
+            dynamicCaster: depthBackend.hasCaster(mesh, 'dynamic'),
+            conservative: conservativeCasterMeshes.has(mesh),
+        }));
+        if (options.coverageMode === 'scene-fit' && !syncingSceneFitMembership) {
+            sceneFitCoverageInvalidated = true;
+        }
+        const rollbackMembership = (primaryError) => {
+            const rollbackErrors = [];
+            for (const previous of [...previousMembership].reverse()) {
+                try {
+                    if (previous.staticCaster)
+                        depthBackend.addCaster(previous.mesh, 'static');
+                    else if (previous.dynamicCaster)
+                        depthBackend.addCaster(previous.mesh, 'dynamic');
+                    else
+                        depthBackend.removeCaster(previous.mesh);
+                }
+                catch (rollbackError) {
+                    rollbackErrors.push(rollbackError);
+                }
+                setCandidateLayer(previous.mesh, previous.candidateLayer);
+                if (previous.conservative)
+                    conservativeCasterMeshes.add(previous.mesh);
+                else
+                    conservativeCasterMeshes.delete(previous.mesh);
+            }
+            syncCandidateCounts();
+            if (rollbackErrors.length > 0 && primaryError && typeof primaryError === 'object') {
+                attachFailureMetadata(primaryError, {
+                    casterMembershipRollbackErrors: Object.freeze(rollbackErrors),
+                });
+            }
+        };
+        try {
+            for (const mesh of meshes) {
+                const previousLayer = candidateLayerByMesh.get(mesh);
+                if (shouldCast && isMeshRuntimeVisible(mesh)) {
+                    const retained = shouldRetainCaster(mesh, record.updateClass, reuseCachedBounds);
+                    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);
+                }
+            }
+        }
+        catch (error) {
+            rollbackMembership(error);
+            throw error;
+        }
+        syncCandidateCounts();
+        for (const changedLayer of changedLayers) {
+            markDepthDirty(changedLayer, 'caster-influence-membership-changed');
+        }
+        syncActivityEligibility(record.entityId);
+        return rollbackMembership;
+    };
+    const restorePendingReceiver = (target) => {
+        const desired = pendingReceiverRestorations.get(target);
+        if (desired === undefined)
+            return;
+        if (flushingRefresh && receiverRestorationAttemptsThisFlush.has(target)) {
+            throw new Error('shadowMapExperiment.receiverRestorationPending');
+        }
+        if (!isDisposed(target) && target.receiveShadows !== desired)
+            target.receiveShadows = desired;
+        pendingReceiverRestorations.delete(target);
+    };
+    const flushPendingReceiverRestorations = () => {
+        for (const target of [...pendingReceiverRestorations.keys()]) {
+            receiverRestorationAttemptsThisFlush.add(target);
+            try {
+                const desired = pendingReceiverRestorations.get(target);
+                if (desired !== undefined && !isDisposed(target) && target.receiveShadows !== desired) {
+                    target.receiveShadows = desired;
+                }
+                pendingReceiverRestorations.delete(target);
+            }
+            catch {
+                // The target remains the owner and the post-flush predicate schedules
+                // exactly one further frame; no unrelated receiver is scanned.
+            }
+        }
+    };
+    const writeReceiver = (target, desired) => {
+        try {
+            if (!isDisposed(target) && target.receiveShadows !== desired)
+                target.receiveShadows = desired;
+            pendingReceiverRestorations.delete(target);
+        }
+        catch (error) {
+            pendingReceiverRestorations.set(target, desired);
+            throw error;
+        }
+    };
+    const restoreReceiver = (mesh) => {
+        const target = receiverTargetByMesh.get(mesh) ?? resolveReceiverTarget(mesh);
+        receiverTargetByMesh.delete(mesh);
+        const state = receiverStates.get(target);
+        if (!state)
+            return;
+        if (state.requests.get(mesh) === true)
+            state.enabledRequestCount -= 1;
+        state.requests.delete(mesh);
+        if (state.requests.size > 0) {
+            const next = state.enabledRequestCount > 0;
+            state.ownedValue = next;
+            writeReceiver(target, next);
+            return;
+        }
+        if (!isDisposed(target) && target.receiveShadows === state.ownedValue) {
+            writeReceiver(target, 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);
+        // A failed journal rollback must be restored before this target is read as
+        // a new baseline. Otherwise a later retry would capture our own stale
+        // value as caller state.
+        restorePendingReceiver(target);
+        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(),
+                enabledRequestCount: 0,
+                ownedValue: next,
+            };
+            receiverStates.set(target, state);
+        }
+        const previousRequest = state.requests.get(mesh);
+        if (previousRequest !== next) {
+            if (previousRequest === true)
+                state.enabledRequestCount -= 1;
+            if (next)
+                state.enabledRequestCount += 1;
+        }
+        state.requests.set(mesh, next);
+        const ownedValue = state.enabledRequestCount > 0;
+        state.ownedValue = ownedValue;
+        writeReceiver(target, 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 captureReceiverJournal = (meshes) => {
+        const touchedMeshes = [...meshes];
+        const touchedMeshesByTarget = new Map();
+        const trackTarget = (target, mesh) => {
+            let targetMeshes = touchedMeshesByTarget.get(target);
+            if (!targetMeshes) {
+                targetMeshes = new Set();
+                touchedMeshesByTarget.set(target, targetMeshes);
+            }
+            targetMeshes.add(mesh);
+        };
+        for (const mesh of touchedMeshes) {
+            trackTarget(resolveReceiverTarget(mesh), mesh);
+            const previousTarget = receiverTargetByMesh.get(mesh);
+            if (previousTarget)
+                trackTarget(previousTarget, mesh);
+        }
+        for (const target of touchedMeshesByTarget.keys())
+            restorePendingReceiver(target);
+        const states = [...touchedMeshesByTarget].map(([target, targetMeshes]) => {
+            const state = receiverStates.get(target);
+            return {
+                target,
+                state: state ?? null,
+                enabledRequestCount: state?.enabledRequestCount ?? 0,
+                ownedValue: state?.ownedValue ?? false,
+                requests: [...targetMeshes].map(mesh => [mesh, state?.requests.get(mesh)]),
+            };
+        });
+        return {
+            states,
+            targetsByMesh: touchedMeshes.map(mesh => [mesh, receiverTargetByMesh.get(mesh) ?? null]),
+            targetValues: [...touchedMeshesByTarget.keys()].map(target => [target, target.receiveShadows]),
+        };
+    };
+    const rollbackReceiverJournal = (journal, primaryError) => {
+        const rollbackErrors = [];
+        for (const entry of journal.states) {
+            if (!entry.state) {
+                receiverStates.delete(entry.target);
+                continue;
+            }
+            for (const [mesh, request] of entry.requests) {
+                if (request === undefined)
+                    entry.state.requests.delete(mesh);
+                else
+                    entry.state.requests.set(mesh, request);
+            }
+            entry.state.enabledRequestCount = entry.enabledRequestCount;
+            entry.state.ownedValue = entry.ownedValue;
+            receiverStates.set(entry.target, entry.state);
+        }
+        for (const [mesh, target] of journal.targetsByMesh) {
+            receiverTargetByMesh.delete(mesh);
+            if (target)
+                receiverTargetByMesh.set(mesh, target);
+        }
+        for (const [target, receiveShadows] of journal.targetValues) {
+            try {
+                writeReceiver(target, receiveShadows);
+            }
+            catch (error) {
+                rollbackErrors.push(error);
+            }
+        }
+        if (rollbackErrors.length > 0 && primaryError && typeof primaryError === 'object') {
+            attachFailureMetadata(primaryError, { receiverRollbackErrors: Object.freeze(rollbackErrors) });
+        }
+    };
+    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 receiverJournal = captureReceiverJournal(meshes);
+        let rollbackCasterMembership = null;
+        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');
+        }
+        try {
+            // Receiver preparation is fallible in host integrations and is journaled
+            // together with registry/backend state. Visibility/membership changes
+            // never publish automatic activity topology.
+            for (const mesh of meshes)
+                setReceiver(mesh, object.receive, renderableId);
+            rollbackCasterMembership = syncCaster(renderableId);
+            pendingRenderableMembershipRetries.delete(renderableId);
+        }
+        catch (error) {
+            rollbackCasterMembership?.(error);
+            rollbackReceiverJournal(receiverJournal, error);
+            if (previousRecord) {
+                if (previousRecord.renderableReady)
+                    registry.attach(renderableId, previousRecord.runtimeVisible);
+                else
+                    registry.detach(renderableId);
+                registry.setVisible(renderableId, previousRecord.runtimeVisible);
+            }
+            syncActivityEligibility(object.entityId);
+            pendingRenderableMembershipRetries.set(renderableId, 'renderable');
+            requestRefreshFrame('shadow-map-experiment-membership-retry');
+            throw error;
+        }
+    };
+    const flushPendingRenderableMembershipRetries = () => {
+        // Membership retries own only local receiver/caster state. Candidate
+        // topology is published by Mesh registration, unregistration, or an
+        // explicit Plan/runtime-object delta.
+        for (const [renderableId, retryKind] of [...pendingRenderableMembershipRetries]) {
+            if (!objectByRenderable.has(renderableId) || !meshesByRenderable.has(renderableId)) {
+                pendingRenderableMembershipRetries.delete(renderableId);
+                continue;
+            }
+            if (retryKind === 'renderable') {
+                try {
+                    syncRenderable(renderableId);
+                }
+                catch (error) {
+                    if (error instanceof Error
+                        && error.message === 'shadowMapExperiment.automaticActivityCandidateCommitFailed') {
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            else {
+                const pendingVisibility = pendingExplicitVisibility.get(renderableId);
+                const previousRecord = registry?.getRecord(renderableId) ?? null;
+                let rollbackCasterMembership = null;
+                if (pendingVisibility !== undefined)
+                    registry?.setVisible(renderableId, pendingVisibility);
+                try {
+                    rollbackCasterMembership = syncCaster(renderableId);
+                }
+                catch (error) {
+                    rollbackCasterMembership?.(error);
+                    if (previousRecord && registry) {
+                        if (previousRecord.renderableReady)
+                            registry.attach(renderableId, previousRecord.runtimeVisible);
+                        else
+                            registry.detach(renderableId);
+                        registry.setVisible(renderableId, previousRecord.runtimeVisible);
+                    }
+                    requestRefreshFrame('shadow-map-experiment-membership-retry');
+                    if (error instanceof Error
+                        && error.message === 'shadowMapExperiment.automaticActivityCandidateCommitFailed') {
+                        continue;
+                    }
+                    throw error;
+                }
+                pendingExplicitVisibility.delete(renderableId);
+                pendingRenderableMembershipRetries.delete(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);
+                requestRefreshFrame('shadow-map-experiment-membership-retry');
+                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 flushPendingMeshObserverRestoration = (mesh) => {
+        const pending = pendingMeshObserverRestorations.get(mesh);
+        if (!pending)
+            return Object.freeze([]);
+        const restorationErrors = [];
+        const mutable = pending.binding;
+        if (pending.enabledObserver) {
+            try {
+                const template = pending.enabledObserver;
+                mutable.enabledObserver = mesh.onEnabledStateChangedObservable.add(template.callback, template.mask, false, template.scope);
+                pending.enabledObserver = null;
+            }
+            catch (error) {
+                restorationErrors.push(error);
+            }
+        }
+        for (const restoration of [...pending.ancestorEnabledObservers]) {
+            try {
+                const { binding, template } = restoration;
+                binding.observer = binding.node.onEnabledStateChangedObservable.add(template.callback, template.mask, false, template.scope);
+                pending.ancestorEnabledObservers.splice(pending.ancestorEnabledObservers.indexOf(restoration), 1);
+            }
+            catch (error) {
+                restorationErrors.push(error);
+            }
+        }
+        if (pending.disposeObserver) {
+            try {
+                const template = pending.disposeObserver;
+                mutable.disposeObserver = mesh.onDisposeObservable.add(template.callback, template.mask, false, template.scope);
+                pending.disposeObserver = null;
+            }
+            catch (error) {
+                restorationErrors.push(error);
+            }
+        }
+        if (pending.matrixObserver) {
+            try {
+                const template = pending.matrixObserver;
+                mutable.matrixObserver = mesh.onAfterWorldMatrixUpdateObservable.add(template.callback, template.mask, false, template.scope);
+                pending.matrixObserver = null;
+            }
+            catch (error) {
+                restorationErrors.push(error);
+            }
+        }
+        if (!pending.enabledObserver
+            && pending.ancestorEnabledObservers.length === 0
+            && !pending.disposeObserver
+            && !pending.matrixObserver) {
+            pendingMeshObserverRestorations.delete(mesh);
+        }
+        return Object.freeze(restorationErrors);
+    };
+    const unregisterMesh = (mesh) => {
+        const binding = bindings.get(mesh);
+        if (!binding)
+            return false;
+        const pendingObserverRestorationErrors = flushPendingMeshObserverRestoration(mesh);
+        if (pendingObserverRestorationErrors.length > 0) {
+            pendingMeshUnregistrations.add(mesh);
+            requestRefreshFrame('shadow-map-experiment-mesh-observer-restoration-retry');
+            throw Object.assign(new Error('shadowMapExperiment.meshObserverRestorationFailed'), {
+                cleanupErrors: pendingObserverRestorationErrors,
+            });
+        }
+        const previousLayer = candidateLayerByMesh.get(mesh);
+        const wasStaticCaster = depthBackend?.hasCaster(mesh, 'static') === true;
+        const wasDynamicCaster = depthBackend?.hasCaster(mesh, 'dynamic') === true;
+        const wasCaster = wasStaticCaster || wasDynamicCaster;
+        const wasConservative = conservativeCasterMeshes.has(mesh);
+        const previousRecord = registry?.getRecord(binding.renderableId) ?? null;
+        const wasActiveRecord = previousRecord?.state === 'active';
+        const receiverJournal = captureReceiverJournal([mesh]);
+        const meshes = meshesByRenderable.get(binding.renderableId);
+        const remainingMeshes = [...(meshes ?? [])].filter(candidate => candidate !== mesh);
+        let enabledObserverRemoved = false;
+        const ancestorEnabledObserversRemoved = [];
+        let disposeObserverRemoved = false;
+        let matrixObserverRemoved = false;
+        const enabledObserverTemplate = binding.enabledObserver;
+        const disposeObserverTemplate = binding.disposeObserver;
+        const matrixObserverTemplate = binding.matrixObserver;
+        let automaticActivityCandidatesChanged = false;
+        const restoreRegistry = () => {
+            if (!registry || !previousRecord)
+                return;
+            if (previousRecord.renderableReady)
+                registry.attach(binding.renderableId, previousRecord.runtimeVisible);
+            else
+                registry.detach(binding.renderableId);
+            registry.setVisible(binding.renderableId, previousRecord.runtimeVisible);
+        };
+        try {
+            depthBackend?.removeCaster(mesh);
+            restoreReceiver(mesh);
+            if (remainingMeshes.length === 0)
+                registry?.detach(binding.renderableId);
+            else
+                registry?.setVisible(binding.renderableId, remainingMeshes.some(isMeshRuntimeVisible));
+            enabledObserverRemoved = mesh.onEnabledStateChangedObservable.remove(binding.enabledObserver);
+            for (const ancestorBinding of binding.ancestorEnabledObservers) {
+                const template = ancestorBinding.observer;
+                if (ancestorBinding.node.onEnabledStateChangedObservable.remove(template)) {
+                    ancestorEnabledObserversRemoved.push({ binding: ancestorBinding, template });
+                }
+            }
+            disposeObserverRemoved = mesh.onDisposeObservable.remove(binding.disposeObserver);
+            if (binding.matrixObserver) {
+                matrixObserverRemoved = mesh.onAfterWorldMatrixUpdateObservable.remove(binding.matrixObserver);
+            }
+            if (!stagingPlanCandidateTransitions) {
+                // A registration can fail while its new binding exists only in the
+                // unpublished proposal. Rollback must remove it from that proposed
+                // view, not just from the last committed candidate map, otherwise the
+                // next frame could publish a candidate whose mesh binding was deleted.
+                const ownsPendingCandidateTransition = pendingAutomaticActivityCandidateTransition !== null;
+                const nextCandidates = new Map(pendingAutomaticActivityCandidateTransition
+                    ?? automaticActivityCandidateBindings);
+                automaticActivityCandidatesChanged = updateAutomaticActivityCandidateBinding(nextCandidates, binding, null);
+                if ((automaticActivityCandidatesChanged || ownsPendingCandidateTransition)
+                    && !applyAutomaticActivityCandidateTransition(nextCandidates)) {
+                    throw new Error('shadowMapExperiment.automaticActivityCandidateCommitFailed');
+                }
+            }
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            try {
+                if (wasStaticCaster)
+                    depthBackend?.addCaster(mesh, 'static');
+                else if (wasDynamicCaster)
+                    depthBackend?.addCaster(mesh, 'dynamic');
+                else
+                    depthBackend?.removeCaster(mesh);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
+            try {
+                rollbackReceiverJournal(receiverJournal, error);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
+            try {
+                restoreRegistry();
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(rollbackError);
+            }
+            if (enabledObserverRemoved
+                || ancestorEnabledObserversRemoved.length > 0
+                || disposeObserverRemoved
+                || matrixObserverRemoved) {
+                pendingMeshObserverRestorations.set(mesh, {
+                    mesh,
+                    binding,
+                    enabledObserver: enabledObserverRemoved ? enabledObserverTemplate : null,
+                    ancestorEnabledObservers: ancestorEnabledObserversRemoved,
+                    disposeObserver: disposeObserverRemoved ? disposeObserverTemplate : null,
+                    matrixObserver: matrixObserverRemoved ? matrixObserverTemplate : null,
+                });
+                rollbackErrors.push(...flushPendingMeshObserverRestoration(mesh));
+            }
+            if (wasConservative)
+                conservativeCasterMeshes.add(mesh);
+            else
+                conservativeCasterMeshes.delete(mesh);
+            if (rollbackErrors.length > 0 && error && typeof error === 'object') {
+                attachFailureMetadata(error, { unregisterRollbackErrors: Object.freeze(rollbackErrors) });
+            }
+            // The binding/candidate map deliberately stays intact.  The queued retry
+            // is therefore the sole owner until every teardown step commits.
+            pendingMeshUnregistrations.add(mesh);
+            requestRefreshFrame(pendingMeshObserverRestorations.has(mesh)
+                ? 'shadow-map-experiment-mesh-observer-restoration-retry'
+                : 'shadow-map-experiment-membership-retry');
+            throw error;
+        }
+        if (remainingMeshes.length === 0) {
+            meshesByRenderable.delete(binding.renderableId);
+            pendingRenderableMembershipRetries.delete(binding.renderableId);
+            pendingExplicitVisibility.delete(binding.renderableId);
+        }
+        else {
+            meshes?.delete(mesh);
+        }
+        setCandidateLayer(mesh, null);
+        conservativeCasterMeshes.delete(mesh);
+        meshDataCacheByMesh.delete(mesh);
+        syncCandidateCounts();
+        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);
+        pendingMeshObserverRestorations.delete(mesh);
+        pendingMeshRegistrationRollbacks.delete(mesh);
+        pendingMeshUnregistrations.delete(mesh);
+        pendingTransformMembershipRetries.delete(mesh);
+        // Commit the candidate removal only after every fallible renderer,
+        // observer and receiver teardown above has completed.  Retrying a failed
+        // unregister therefore continues to expose the old valid topology.
+        return automaticActivityCandidatesChanged;
+    };
+    const requestMeshUnregistration = (mesh) => {
+        pendingSceneMeshRegistrations.delete(mesh);
+        try {
+            unregisterMesh(mesh);
+            pendingMeshUnregistrations.delete(mesh);
+        }
+        catch (error) {
+            pendingMeshUnregistrations.add(mesh);
+            requestRefreshFrame('shadow-map-experiment-membership-retry');
+            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 ?? activatingRecoveryPlan)?.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 || (!object.cast && !object.receive))
+            return false;
+        let enabledObserver = null;
+        const ancestorEnabledObservers = [];
+        let disposeObserver = null;
+        let bindingCommitted = false;
+        try {
+            const syncEnabledState = () => {
+                if (!disposed && !disposing) {
+                    try {
+                        syncRenderable(renderableId);
+                    }
+                    catch (error) {
+                        pendingRenderableMembershipRetries.set(renderableId, 'renderable');
+                        requestRefreshFrame('shadow-map-experiment-membership-retry');
+                        if (!(error instanceof Error)
+                            || error.message !== 'shadowMapExperiment.automaticActivityCandidateCommitFailed') {
+                            throw error;
+                        }
+                    }
+                }
+            };
+            enabledObserver = mesh.onEnabledStateChangedObservable.add(syncEnabledState);
+            let ancestor = mesh.parent;
+            while (ancestor) {
+                ancestorEnabledObservers.push({
+                    node: ancestor,
+                    observer: ancestor.onEnabledStateChangedObservable.add(syncEnabledState),
+                });
+                ancestor = ancestor.parent;
+            }
+            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),
+                influenceWorldBounds: undefined,
+                influenceBoundingInfo: undefined,
+                enabledObserver,
+                ancestorEnabledObservers,
+                disposeObserver,
+                matrixObserver: null,
+                worldMatrixSnapshot: null,
+            };
+            bindings.set(mesh, binding);
+            bindingCommitted = true;
+            if (options.coverageMode === 'scene-fit')
+                sceneFitCoverageInvalidated = true;
+            syncMatrixObserver(binding);
+            syncRenderable(renderableId);
+            if (!stagingPlanCandidateTransitions) {
+                syncAutomaticActivityCandidateBindingsForRenderable(renderableId);
+            }
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            if (bindingCommitted) {
+                try {
+                    unregisterMesh(mesh);
+                }
+                catch (rollbackError) {
+                    pendingMeshRegistrationRollbacks.add(mesh);
+                    requestRefreshFrame('shadow-map-experiment-mesh-registration-rollback-retry');
+                    rollbackErrors.push(rollbackError);
+                }
+            }
+            else {
+                pendingMeshObserverCleanups.set(mesh, {
+                    mesh,
+                    enabledObserver,
+                    ancestorEnabledObservers,
+                    disposeObserver,
+                });
+                rollbackErrors.push(...flushPendingMeshObserverCleanup(mesh));
+                if (pendingMeshObserverCleanups.has(mesh)) {
+                    requestRefreshFrame('shadow-map-experiment-mesh-observer-cleanup-retry');
+                }
+            }
+            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);
+            }
+        }
+        for (const binding of [...pending.ancestorEnabledObservers]) {
+            try {
+                binding.node.onEnabledStateChangedObservable.remove(binding.observer);
+                pending.ancestorEnabledObservers.splice(pending.ancestorEnabledObservers.indexOf(binding), 1);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (!pending.disposeObserver
+            && !pending.enabledObserver
+            && pending.ancestorEnabledObservers.length === 0) {
+            pendingMeshObserverCleanups.delete(mesh);
+        }
+        return Object.freeze(cleanupErrors);
+    };
+    const flushPendingMeshObserverCleanups = () => {
+        for (const mesh of [...pendingMeshObserverCleanups.keys()]) {
+            flushPendingMeshObserverCleanup(mesh);
+        }
+    };
+    const flushPendingMeshRegistrationRollbacks = () => {
+        for (const mesh of [...pendingMeshRegistrationRollbacks]) {
+            try {
+                unregisterMesh(mesh);
+                pendingMeshRegistrationRollbacks.delete(mesh);
+            }
+            catch {
+                // Ownership remains in the queue and the post-flush wake predicate
+                // schedules the next bounded attempt.
+            }
+        }
+    };
+    const flushPendingSceneMeshRegistrations = () => {
+        for (const mesh of [...pendingSceneMeshRegistrations]) {
+            if (!scene.meshes.includes(mesh)) {
+                pendingSceneMeshRegistrations.delete(mesh);
+                continue;
+            }
+            registerMesh(mesh);
+            pendingSceneMeshRegistrations.delete(mesh);
+        }
+    };
+    const deactivate = () => {
+        pendingCompositeRefreshReasons.clear();
+        // A proposed candidate view is unpublished state. Revoking it before any
+        // fallible backend cleanup prevents a later retry frame from committing
+        // that stale proposal after the Plan has been disabled or replaced.
+        pendingAutomaticActivityCandidateTransition = null;
+        const cleanupErrors = [];
+        const attempt = (operation) => {
+            try {
+                operation();
+                return true;
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+                return false;
+            }
+        };
+        for (const target of [...pendingReceiverRestorations.keys()]) {
+            attempt(() => restorePendingReceiver(target));
+        }
+        for (const [mesh, binding] of [...bindings]) {
+            let cleaned = true;
+            cleaned = attempt(() => mesh.onEnabledStateChangedObservable.remove(binding.enabledObserver)) && cleaned;
+            for (const ancestorBinding of binding.ancestorEnabledObservers) {
+                cleaned = attempt(() => {
+                    ancestorBinding.node.onEnabledStateChangedObservable.remove(ancestorBinding.observer);
+                }) && 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]) {
+            pendingReceiverRestorations.set(state.mesh, state.previousReceiveShadows);
+            if (attempt(() => {
+                if (!isDisposed(state.mesh) && state.mesh.receiveShadows === state.ownedValue) {
+                    writeReceiver(state.mesh, state.previousReceiveShadows);
+                }
+                else {
+                    pendingReceiverRestorations.delete(state.mesh);
+                }
+            }))
+                receiverStates.delete(mesh);
+        }
+        if (bindings.size === 0) {
+            if (automaticActivityCandidateBindings.size > 0) {
+                automaticActivityCandidateBindings.clear();
+                bumpAutomaticActivityCandidateRevision();
+            }
+            meshesByRenderable.clear();
+            candidateLayerByMesh.clear();
+            candidateMeshCounts.static = 0;
+            candidateMeshCounts.dynamic = 0;
+            conservativeCasterMeshes.clear();
+            meshDataCacheByMesh.clear();
+            pendingMeshRegistrationRollbacks.clear();
+            pendingMeshObserverRestorations.clear();
+            pendingSceneMeshRegistrations.clear();
+            pendingMeshUnregistrations.clear();
+            pendingRenderableMembershipRetries.clear();
+            pendingTransformMembershipRetries.clear();
+            activeCasterEntityIds.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 = resolveBabylonDirectionalLight(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();
+        stagingPlanCandidateTransitions = true;
+        try {
+            for (const mesh of scene.meshes)
+                registerMesh(mesh);
+        }
+        finally {
+            stagingPlanCandidateTransitions = false;
+        }
+        const nextCandidates = new Map();
+        for (const binding of bindings.values()) {
+            updateAutomaticActivityCandidateBinding(nextCandidates, binding, objectByRenderable.get(binding.renderableId));
+        }
+        if (!applyAutomaticActivityCandidateTransition(nextCandidates)
+            && pendingAutomaticAnimationGroupAttachments.size === 0
+            && pendingAutomaticAnimationGroupDetachCleanups.size === 0) {
+            throw new Error('shadowMapExperiment.automaticActivityCandidateCommitFailed');
+        }
+        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);
+                return;
+            }
+            if (previousCount <= 1) {
+                activeDeformationSourceCountByEntity.delete(input.entityId);
+                if (activeCasterEntityIds.has(input.entityId))
+                    pendingFinalDeformationEntityIds.add(input.entityId);
+            }
+            else {
+                activeDeformationSourceCountByEntity.set(input.entityId, previousCount - 1);
+            }
+        };
+        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, candidateView = automaticActivityCandidateBindings) => {
+        const desired = new Map();
+        if (candidateView.size === 0)
+            return desired;
+        const targets = new Set(group.targetedAnimations.map(targetedAnimation => targetedAnimation.target));
+        // Build the candidate relationship index once per group reconciliation.
+        // A skinned AnimationGroup commonly contains one targeted animation per
+        // linked bone TransformNode. Resolving every target by rescanning every
+        // candidate skeleton makes playback start O(targets × meshes × bones).
+        const targetIndex = createAutomaticActivityTargetIndex(candidateView, targets);
+        for (const target of targets) {
+            const resolvedTarget = resolveAutomaticActivityTarget(candidateView, target, objectByRenderable, targetIndex);
+            for (const mesh of resolvedTarget.meshes) {
+                const meshBinding = candidateView.get(mesh);
+                const object = meshBinding ? objectByEntity.get(meshBinding.entityId) : null;
+                if (!meshBinding || !isAutomaticActivityCandidateObject(object))
+                    continue;
+                const key = `${meshBinding.entityId}\u0000${resolvedTarget.kind}`;
+                desired.set(key, { entityId: meshBinding.entityId, kind: resolvedTarget.kind });
+            }
+        }
+        return desired;
+    };
+    const updateAutomaticAnimationGroupTargetIndex = (binding, targets) => {
+        const removeBinding = (index, key) => {
+            const indexedBindings = index.get(key);
+            indexedBindings?.delete(binding);
+            if (indexedBindings?.size === 0)
+                index.delete(key);
+        };
+        for (const key of binding.resolvedTargetIndexKeys) {
+            removeBinding(automaticAnimationGroupsByResolvedTarget, key);
+        }
+        for (const key of binding.resolvedTargetAncestorIndexKeys) {
+            removeBinding(automaticAnimationGroupsByResolvedTargetAncestor, key);
+        }
+        for (const key of binding.resolvedTargetRenderableIndexKeys) {
+            removeBinding(automaticAnimationGroupsByResolvedTargetRenderable, key);
+        }
+        const targetKeys = new Set();
+        const ancestorKeys = new Set();
+        const renderableKeys = new Set();
+        for (const target of targets) {
+            if (!target || (typeof target !== 'object' && typeof target !== 'function'))
+                continue;
+            targetKeys.add(target);
+            let current = target;
+            let ancestor = false;
+            const visited = new Set();
+            while (current && (typeof current === 'object' || typeof current === 'function')) {
+                if (visited.has(current))
+                    break;
+                visited.add(current);
+                if (ancestor)
+                    ancestorKeys.add(current);
+                for (const identity of collectIdentityCandidates(current)) {
+                    renderableKeys.add(identity);
+                }
+                current = current.parent ?? null;
+                ancestor = true;
+            }
+        }
+        for (const key of targetKeys) {
+            addMapSetValue(automaticAnimationGroupsByResolvedTarget, key, binding);
+        }
+        for (const key of ancestorKeys) {
+            addMapSetValue(automaticAnimationGroupsByResolvedTargetAncestor, key, binding);
+        }
+        for (const key of renderableKeys) {
+            addMapSetValue(automaticAnimationGroupsByResolvedTargetRenderable, key, binding);
+        }
+        binding.resolvedTargetIndexKeys = Object.freeze([...targetKeys]);
+        binding.resolvedTargetAncestorIndexKeys = Object.freeze([...ancestorKeys]);
+        binding.resolvedTargetRenderableIndexKeys = Object.freeze([...renderableKeys]);
+    };
+    const collectAutomaticActivityCandidateRelationshipKeys = (mesh) => {
+        const keys = new Set();
+        let current = mesh;
+        while (current && (typeof current === 'object' || typeof current === 'function')) {
+            if (keys.has(current))
+                break;
+            keys.add(current);
+            current = current.parent ?? null;
+        }
+        const skeleton = mesh.skeleton;
+        if (skeleton) {
+            keys.add(skeleton);
+            for (const bone of skeleton.bones ?? []) {
+                keys.add(bone);
+                const transformNode = callOptional(bone, 'getTransformNode')
+                    ?? bone?._linkedTransformNode
+                    ?? null;
+                if (transformNode)
+                    keys.add(transformNode);
+            }
+        }
+        const manager = mesh.morphTargetManager;
+        const count = manager?.numTargets ?? 0;
+        if (manager?.getTarget && Number.isInteger(count) && count > 0) {
+            for (let index = 0; index < count; index += 1) {
+                try {
+                    const target = manager.getTarget(index);
+                    if (target)
+                        keys.add(target);
+                }
+                catch {
+                    // A single malformed morph slot must not make the candidate delta
+                    // fan out to every AnimationGroup.
+                }
+            }
+        }
+        return Object.freeze([...keys]);
+    };
+    const collectAutomaticAnimationGroupsAffectedByCandidateTransition = (nextCandidates) => {
+        const affected = new Set();
+        const changedCandidates = [];
+        const changedEntityIds = new Set();
+        for (const mesh of new Set([
+            ...automaticActivityCandidateBindings.keys(),
+            ...nextCandidates.keys(),
+        ])) {
+            const previous = automaticActivityCandidateBindings.get(mesh);
+            const next = nextCandidates.get(mesh);
+            if (previous?.entityId === next?.entityId
+                && previous?.renderableId === next?.renderableId)
+                continue;
+            changedCandidates.push({ mesh, previous, next });
+            if (previous)
+                changedEntityIds.add(previous.entityId);
+            if (next)
+                changedEntityIds.add(next.entityId);
+        }
+        for (const binding of automaticAnimationGroups.values()) {
+            if (!binding.ready)
+                continue;
+            if (binding.rebindPending
+                || binding.resolvedCandidateRevision !== automaticActivityCandidateRevision
+                || [...binding.sources.values()].some(source => changedEntityIds.has(source.entityId))) {
+                affected.add(binding);
+            }
+        }
+        const includeIndexedBindings = (index, key) => {
+            for (const binding of index.get(key) ?? []) {
+                if (binding.ready)
+                    affected.add(binding);
+            }
+        };
+        for (const { mesh, previous, next } of changedCandidates) {
+            for (const key of collectAutomaticActivityCandidateRelationshipKeys(mesh)) {
+                includeIndexedBindings(automaticAnimationGroupsByResolvedTarget, key);
+            }
+            // A target below the candidate mesh is related, but a target below a
+            // sibling that merely shares a generic root is not.
+            includeIndexedBindings(automaticAnimationGroupsByResolvedTargetAncestor, mesh);
+            for (const renderableId of new Set([
+                previous?.renderableId,
+                next?.renderableId,
+            ].filter((value) => typeof value === 'string'))) {
+                includeIndexedBindings(automaticAnimationGroupsByResolvedTargetRenderable, renderableId);
+            }
+        }
+        return affected;
+    };
+    const shouldFullyResolveAutomaticActivityTargetsOnPlay = (binding) => {
+        if (binding.resolvedCandidateRevision !== automaticActivityCandidateRevision)
+            return false;
+        const currentTargets = binding.group.targetedAnimations.map(targetedAnimation => targetedAnimation.target);
+        if (currentTargets.length !== binding.resolvedTargets.length
+            || currentTargets.some((target, index) => target !== binding.resolvedTargets[index])) {
+            return true;
+        }
+        // A negative binding has no owner-scoped subset to validate. Preserve the
+        // restart boundary that lets a previously unresolved target become owned.
+        if (binding.sources.size === 0)
+            return true;
+        const sourceEntityIds = new Set([...binding.sources.values()].map(source => source.entityId));
+        const sourceCandidates = new Map();
+        for (const [mesh, candidate] of automaticActivityCandidateBindings) {
+            if (sourceEntityIds.has(candidate.entityId))
+                sourceCandidates.set(mesh, candidate);
+        }
+        const desired = resolveAutomaticActivityTargets(binding.group, sourceCandidates);
+        return desired.size !== binding.sources.size
+            || [...desired.keys()].some(key => !binding.sources.has(key));
+    };
+    const syncAutomaticAnimationGroupPlayback = (binding) => {
+        const active = binding.group.isPlaying === true;
+        for (const source of binding.sources.values())
+            source.controller.setActive(active);
+        binding.active = active;
+    };
+    const cleanupStagedAutomaticAnimationGroupSources = (binding) => {
+        const cleanupErrors = [];
+        for (const [key, source] of [...binding.stagedSources.entries()].reverse()) {
+            try {
+                source.controller.setActive(false);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+            try {
+                source.controller.dispose();
+                binding.stagedSources.delete(key);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (cleanupErrors.length > 0) {
+            pendingAutomaticAnimationGroupSourceCleanups.add(binding);
+        }
+        return Object.freeze(cleanupErrors);
+    };
+    const prepareAutomaticAnimationGroupRebind = (binding, candidateView, forceTargetResolution = false) => {
+        const shouldResolveTargets = forceTargetResolution
+            || binding.resolvedCandidateRevision !== automaticActivityCandidateRevision;
+        if (!shouldResolveTargets)
+            return false;
+        automaticActivityTargetResolutionCount += 1;
+        if (binding.stagedSources.size > 0) {
+            const cleanupErrors = cleanupStagedAutomaticAnimationGroupSources(binding);
+            if (cleanupErrors.length > 0) {
+                throw cleanupErrors[0];
+            }
+        }
+        const desired = resolveAutomaticActivityTargets(binding.group, candidateView);
+        if (desired.size !== binding.sources.size
+            || [...desired.keys()].some(key => !binding.sources.has(key))) {
+            binding.rebindPending = true;
+            binding.resolvedCandidateRevision = -1;
+        }
+        // Source replacement has one commit boundary: every stale committed
+        // source must be fully disposed before any replacement is acquired.
+        for (const [key, source] of [...binding.sources]) {
+            if (desired.has(key))
+                continue;
+            binding.rebindPending = true;
+            try {
+                source.controller.setActive(false);
+                source.controller.dispose();
+                binding.sources.delete(key);
+            }
+            catch (error) {
+                binding.resolvedCandidateRevision = -1;
+                pendingAutomaticAnimationGroupSourceCleanups.add(binding);
+                throw error;
+            }
+        }
+        try {
+            for (const [key, descriptor] of desired) {
+                if (binding.sources.has(key) || binding.stagedSources.has(key))
+                    continue;
+                const sourceId = `fps:auto:animation-group:${binding.group.uniqueId}:${descriptor.kind}`;
+                const controller = system.registerCasterActivitySource({ ...descriptor, sourceId });
+                binding.stagedSources.set(key, { ...descriptor, controller });
+            }
+        }
+        catch (error) {
+            cleanupStagedAutomaticAnimationGroupSources(binding);
+            throw error;
+        }
+        return true;
+    };
+    const commitPreparedAutomaticAnimationGroupRebind = (binding, candidateRevision) => {
+        for (const [key, source] of binding.stagedSources) {
+            binding.sources.set(key, source);
+        }
+        binding.stagedSources.clear();
+        binding.rebindPending = false;
+        binding.resolvedCandidateRevision = candidateRevision;
+        const resolvedTargets = Object.freeze(binding.group.targetedAnimations.map(targetedAnimation => targetedAnimation.target));
+        binding.resolvedTargets = resolvedTargets;
+        updateAutomaticAnimationGroupTargetIndex(binding, resolvedTargets);
+    };
+    const reconcileAutomaticAnimationGroup = (binding, forceTargetResolution = false) => {
+        const prepared = prepareAutomaticAnimationGroupRebind(binding, automaticActivityCandidateBindings, forceTargetResolution);
+        if (prepared) {
+            commitPreparedAutomaticAnimationGroupRebind(binding, automaticActivityCandidateRevision);
+        }
+        syncAutomaticAnimationGroupPlayback(binding);
+    };
+    const safelyReconcileAutomaticAnimationGroup = (binding, forceTargetResolution = false) => {
+        if (disposed || disposing || !binding.ready)
+            return true;
+        try {
+            reconcileAutomaticAnimationGroup(binding, forceTargetResolution);
+            pendingAutomaticAnimationGroupReconciliations.delete(binding);
+            return true;
+        }
+        catch (error) {
+            pendingAutomaticAnimationGroupReconciliations.add(binding);
+            requestRefreshFrame('shadow-map-experiment-automatic-activity-reconcile-retry');
+            if (pendingAutomaticAnimationGroupSourceCleanups.has(binding)) {
+                requestRefreshFrame('shadow-map-experiment-automatic-activity-cleanup-retry');
+            }
+            rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} could not bind shadow activity: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    };
+    const attachAutomaticAnimationGroup = (group, deferInitialReconcile = false) => {
+        if (automaticAnimationGroups.has(group) || disposed || disposing)
+            return;
+        const binding = {
+            group,
+            playObserver: null,
+            pauseObserver: null,
+            endObserver: null,
+            sources: new Map(),
+            stagedSources: new Map(),
+            active: false,
+            ready: false,
+            rebindPending: false,
+            resolvedCandidateRevision: -1,
+            resolvedTargets: Object.freeze([]),
+            resolvedTargetIndexKeys: Object.freeze([]),
+            resolvedTargetAncestorIndexKeys: Object.freeze([]),
+            resolvedTargetRenderableIndexKeys: Object.freeze([]),
+        };
+        automaticAnimationGroups.set(group, binding);
+        try {
+            binding.playObserver = group.onAnimationGroupPlayObservable.add(() => {
+                if (!binding.ready)
+                    return;
+                safelyReconcileAutomaticAnimationGroup(binding, shouldFullyResolveAutomaticActivityTargetsOnPlay(binding));
+                requestRefreshFrame('shadow-map-experiment-animation-group-played');
+            });
+            binding.pauseObserver = group.onAnimationGroupPauseObservable.add(() => {
+                if (!binding.ready)
+                    return;
+                try {
+                    syncAutomaticAnimationGroupPlayback(binding);
+                }
+                catch (error) {
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} could not update shadow activity: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+            binding.endObserver = group.onAnimationGroupEndObservable.add(() => {
+                if (!binding.ready)
+                    return;
+                try {
+                    syncAutomaticAnimationGroupPlayback(binding);
+                }
+                catch (error) {
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} could not update shadow activity: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+            binding.ready = true;
+            if (!deferInitialReconcile)
+                safelyReconcileAutomaticAnimationGroup(binding);
+            pendingAutomaticAnimationGroupAttachments.delete(group);
+        }
+        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;
+        updateAutomaticAnimationGroupTargetIndex(binding, Object.freeze([]));
+        pendingAutomaticAnimationGroupReconciliations.delete(binding);
+        const cleanupErrors = [...cleanupAutomaticAnimationGroupSources(binding)];
+        pendingAutomaticAnimationGroupSourceCleanups.delete(binding);
+        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.stagedSources.size === 0
+            && !binding.playObserver
+            && !binding.pauseObserver
+            && !binding.endObserver) {
+            automaticAnimationGroups.delete(group);
+            pendingAutomaticAnimationGroupDetachCleanups.delete(binding);
+        }
+        else {
+            pendingAutomaticAnimationGroupDetachCleanups.add(binding);
+            requestRefreshFrame('shadow-map-experiment-automatic-activity-detach-retry');
+        }
+        return Object.freeze(cleanupErrors);
+    };
+    const flushPendingAutomaticAnimationGroupDetachCleanups = () => {
+        if (pendingAutomaticAnimationGroupDetachCleanups.size === 0)
+            return;
+        for (const binding of [...pendingAutomaticAnimationGroupDetachCleanups]) {
+            const group = binding.group;
+            const cleanupErrors = detachAutomaticAnimationGroup(group);
+            if (cleanupErrors.length > 0)
+                continue;
+            if (!pendingAutomaticActivityCandidateTransition
+                && automaticActivityCandidateBindings.size > 0
+                && scene.animationGroups.includes(group)) {
+                try {
+                    attachAutomaticAnimationGroup(group);
+                    pendingAutomaticAnimationGroupAttachments.delete(group);
+                }
+                catch (error) {
+                    pendingAutomaticAnimationGroupAttachments.add(group);
+                    requestRefreshFrame('shadow-map-experiment-automatic-activity-attach-retry');
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityObserverFailed', `AnimationGroup ${group.name || group.uniqueId} could not be reattached after cleanup: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+    };
+    const flushPendingAutomaticAnimationGroupAttachments = () => {
+        // The proposed candidate transition owns observer acquisition while it is
+        // pending. Attaching here would reconcile against the old committed view.
+        if (pendingAutomaticActivityCandidateTransition)
+            return;
+        for (const group of [...pendingAutomaticAnimationGroupAttachments]) {
+            if (!scene.animationGroups.includes(group) || automaticActivityCandidateBindings.size === 0) {
+                pendingAutomaticAnimationGroupAttachments.delete(group);
+                continue;
+            }
+            try {
+                attachAutomaticAnimationGroup(group);
+                pendingAutomaticAnimationGroupAttachments.delete(group);
+            }
+            catch {
+                // Retain ownership in the queue; the post-flush wake predicate retries.
+            }
+        }
+    };
+    const flushPendingAutomaticAnimationGroupReconciliations = () => {
+        // A candidate transition owns source acquisition until it either commits
+        // or rolls back.  Rebinding an individual group against the previously
+        // committed view here would recreate the stale source set mid-transaction.
+        if (pendingAutomaticActivityCandidateTransition)
+            return;
+        for (const binding of [...pendingAutomaticAnimationGroupReconciliations]) {
+            if (!binding.ready || !automaticAnimationGroups.has(binding.group)) {
+                pendingAutomaticAnimationGroupReconciliations.delete(binding);
+                continue;
+            }
+            safelyReconcileAutomaticAnimationGroup(binding);
+        }
+    };
+    const cleanupAutomaticAnimationGroupSources = (binding) => {
+        const cleanupErrors = [];
+        binding.active = false;
+        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);
+            }
+        }
+        for (const [key, source] of [...binding.stagedSources.entries()].reverse()) {
+            try {
+                source.controller.setActive(false);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+            try {
+                source.controller.dispose();
+                binding.stagedSources.delete(key);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        return Object.freeze(cleanupErrors);
+    };
+    const enterAutomaticAnimationGroupDormant = (binding) => {
+        const cleanupErrors = cleanupAutomaticAnimationGroupSources(binding);
+        binding.resolvedCandidateRevision = automaticActivityCandidateRevision;
+        if (cleanupErrors.length === 0 && binding.sources.size === 0 && binding.stagedSources.size === 0) {
+            binding.rebindPending = false;
+            pendingAutomaticAnimationGroupSourceCleanups.delete(binding);
+            return;
+        }
+        binding.rebindPending = true;
+        pendingAutomaticAnimationGroupSourceCleanups.add(binding);
+        rememberDiagnostic('shadowMapExperiment.automaticActivityCleanupFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} activity cleanup failed.`);
+    };
+    const flushPendingAutomaticAnimationGroupSourceCleanups = () => {
+        if (pendingAutomaticAnimationGroupSourceCleanups.size === 0)
+            return;
+        for (const binding of [...pendingAutomaticAnimationGroupSourceCleanups]) {
+            const cleanupErrors = cleanupAutomaticAnimationGroupSources(binding);
+            if (cleanupErrors.length > 0) {
+                rememberDiagnostic('shadowMapExperiment.automaticActivityCleanupFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} activity cleanup failed.`);
+            }
+            else if (binding.sources.size === 0 && binding.stagedSources.size === 0) {
+                if (!pendingAutomaticActivityCandidateTransition)
+                    binding.rebindPending = false;
+                pendingAutomaticAnimationGroupSourceCleanups.delete(binding);
+                if (!pendingAutomaticActivityCandidateTransition
+                    && automaticActivityCandidateBindings.size > 0
+                    && binding.ready) {
+                    safelyReconcileAutomaticAnimationGroup(binding);
+                }
+            }
+        }
+        if (pendingAutomaticAnimationGroupSourceCleanups.size > 0) {
+            requestRefreshFrame('shadow-map-experiment-automatic-activity-cleanup-retry');
+        }
+    };
+    const haveSameAutomaticActivityCandidateView = (left, right) => left.size === right.size && [...left].every(([mesh, binding]) => {
+        const other = right.get(mesh);
+        return other?.entityId === binding.entityId
+            && other.renderableId === binding.renderableId;
+    });
+    applyAutomaticActivityCandidateTransition = (nextCandidates) => {
+        if (haveSameAutomaticActivityCandidateView(automaticActivityCandidateBindings, nextCandidates)) {
+            pendingAutomaticActivityCandidateTransition = null;
+            return true;
+        }
+        if (suppressAutomaticActivityCandidateRevision) {
+            // A full backend rebuild whose authored candidate signature is unchanged
+            // preserves the already-owned automatic sources.  Only replace the
+            // equivalent mesh-binding view; there is no topology publication.
+            automaticActivityCandidateBindings.clear();
+            for (const [mesh, binding] of nextCandidates) {
+                automaticActivityCandidateBindings.set(mesh, binding);
+            }
+            pendingAutomaticActivityCandidateTransition = null;
+            return true;
+        }
+        pendingAutomaticActivityCandidateTransition = new Map(nextCandidates);
+        if (pendingAutomaticAnimationGroupDetachCleanups.size > 0) {
+            requestRefreshFrame('shadow-map-experiment-automatic-activity-detach-retry');
+            return false;
+        }
+        if (pendingAutomaticAnimationGroupSourceCleanups.size > 0) {
+            flushPendingAutomaticAnimationGroupSourceCleanups();
+            if (pendingAutomaticAnimationGroupSourceCleanups.size > 0) {
+                requestRefreshFrame('shadow-map-experiment-automatic-activity-cleanup-retry');
+                return false;
+            }
+        }
+        if (nextCandidates.size > 0) {
+            for (const group of scene.animationGroups) {
+                try {
+                    // The proposed candidate view owns initial source resolution.  Only
+                    // acquire the lifecycle observers here; resolving against the old
+                    // committed view would publish a stale source set mid-transition.
+                    attachAutomaticAnimationGroup(group, true);
+                }
+                catch (error) {
+                    pendingAutomaticAnimationGroupAttachments.add(group);
+                    requestRefreshFrame('shadow-map-experiment-automatic-activity-attach-retry');
+                    rememberDiagnostic('shadowMapExperiment.automaticActivityObserverFailed', `AnimationGroup ${group.name || group.uniqueId} could not be observed: ${error instanceof Error ? error.message : String(error)}`);
+                    return false;
+                }
+            }
+        }
+        const affectedBindings = collectAutomaticAnimationGroupsAffectedByCandidateTransition(nextCandidates);
+        const preparedBindings = [];
+        try {
+            for (const binding of affectedBindings) {
+                prepareAutomaticAnimationGroupRebind(binding, nextCandidates, true);
+                preparedBindings.push(binding);
+            }
+        }
+        catch (error) {
+            for (const binding of preparedBindings) {
+                cleanupStagedAutomaticAnimationGroupSources(binding);
+            }
+            requestRefreshFrame('shadow-map-experiment-automatic-activity-reconcile-retry');
+            rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `Automatic candidate transition could not prepare activity sources: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        const nextRevision = automaticActivityCandidateRevision + 1;
+        automaticActivityCandidateBindings.clear();
+        for (const [mesh, binding] of nextCandidates) {
+            automaticActivityCandidateBindings.set(mesh, binding);
+        }
+        automaticActivityCandidateRevision = nextRevision;
+        for (const binding of preparedBindings) {
+            commitPreparedAutomaticAnimationGroupRebind(binding, nextRevision);
+            try {
+                syncAutomaticAnimationGroupPlayback(binding);
+                pendingAutomaticAnimationGroupReconciliations.delete(binding);
+            }
+            catch (error) {
+                pendingAutomaticAnimationGroupReconciliations.add(binding);
+                requestRefreshFrame('shadow-map-experiment-automatic-activity-reconcile-retry');
+                rememberDiagnostic('shadowMapExperiment.automaticActivityBindingFailed', `AnimationGroup ${binding.group.name || binding.group.uniqueId} could not activate committed shadow activity: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        for (const binding of automaticAnimationGroups.values()) {
+            if (binding.ready && !affectedBindings.has(binding)) {
+                binding.resolvedCandidateRevision = nextRevision;
+            }
+        }
+        pendingAutomaticActivityCandidateTransition = null;
+        return true;
+    };
+    flushPendingAutomaticActivityCandidateTransition = () => {
+        if (!pendingAutomaticActivityCandidateTransition)
+            return;
+        applyAutomaticActivityCandidateTransition(new Map(pendingAutomaticActivityCandidateTransition));
+    };
+    const reconcileAutomaticAnimationGroups = () => {
+        if (automaticActivityCandidateBindings.size === 0) {
+            pendingAutomaticAnimationGroupAttachments.clear();
+            pendingAutomaticAnimationGroupReconciliations.clear();
+            for (const binding of automaticAnimationGroups.values())
+                enterAutomaticAnimationGroupDormant(binding);
+            if (pendingAutomaticAnimationGroupSourceCleanups.size > 0) {
+                requestRefreshFrame('shadow-map-experiment-automatic-activity-cleanup-retry');
+            }
+            return pendingAutomaticAnimationGroupSourceCleanups.size === 0;
+        }
+        // A candidate can recover while an earlier dormant cleanup is still
+        // retrying.  Finish that cleanup before acquiring a new observer set.
+        flushPendingAutomaticAnimationGroupSourceCleanups();
+        for (const group of scene.animationGroups) {
+            try {
+                attachAutomaticAnimationGroup(group);
+            }
+            catch (error) {
+                pendingAutomaticAnimationGroupAttachments.add(group);
+                requestRefreshFrame('shadow-map-experiment-automatic-activity-attach-retry');
+                rememberDiagnostic('shadowMapExperiment.automaticActivityObserverFailed', `AnimationGroup ${group.name || group.uniqueId} could not be observed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        let committed = true;
+        for (const binding of automaticAnimationGroups.values()) {
+            if (!pendingAutomaticAnimationGroupSourceCleanups.has(binding)) {
+                committed = safelyReconcileAutomaticAnimationGroup(binding) && committed;
+            }
+        }
+        return committed && pendingAutomaticAnimationGroupSourceCleanups.size === 0;
+    };
+    const applyPlanInPlace = (previousPlan, nextPlan, runtimeOverlayMeshes = null, previousCandidateObjects = previousPlan.objects) => {
+        if (!registry || !generator || !depthBackend)
+            throw new Error('shadowMapExperiment.backendUnavailable');
+        const delta = diffShadowMapExperimentPlans(previousPlan, nextPlan);
+        const appearanceUpdate = delta.appearanceChanged
+            ? depthBackend.setAppearance(resolveShadowMapExperimentAppearance(nextPlan.generator))
+            : null;
+        plan = nextPlan;
+        if (delta.appearanceChanged) {
+            requestRefreshFrame('shadow-map-experiment-appearance-changed');
+            if (appearanceUpdate?.compositeRefreshRequired)
+                markCompositeDepthDirty('quality-changed');
+        }
+        if (delta.appearanceOnly)
+            return;
+        if (delta.lightDirectionChanged && lightState) {
+            configureLight(lightState.light, nextPlan, {
+                center: effectiveCoverageCenter ?? nextPlan.generator.bounds.center,
+                extent: effectiveCoverageExtent ?? nextPlan.generator.bounds.extent,
+                near: effectiveCoverageNear ?? nextPlan.generator.bounds.near,
+                far: effectiveCoverageFar ?? nextPlan.generator.bounds.far,
+            });
+            influenceCulling.configure(nextPlan.culling.guardBandRatio);
+            pendingCoverageMembershipRebuild = nextPlan.culling.enabled;
+            cullingStable = !nextPlan.culling.enabled;
+            lastCullingInvalidationReason = 'light-direction-changed';
+        }
+        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);
+        invalidateSceneFitBounds();
+        stagingPlanCandidateTransitions = true;
+        try {
+            const bindingsToReconcile = runtimeOverlayMeshes
+                ? [...runtimeOverlayMeshes].flatMap(mesh => {
+                    const binding = bindings.get(mesh);
+                    return binding ? [[mesh, binding]] : [];
+                })
+                : [...bindings];
+            for (const [mesh, binding] of bindingsToReconcile) {
+                const resolvedId = resolveRenderableId(mesh, objectByRenderable);
+                const resolvedObject = resolvedId ? objectByRenderable.get(resolvedId) : null;
+                const resolvedEntityId = resolvedObject?.entityId ?? null;
+                if (resolvedId !== binding.renderableId
+                    || resolvedEntityId !== binding.entityId
+                    || (!resolvedObject?.cast && !resolvedObject?.receive))
+                    unregisterMesh(mesh);
+                else {
+                    syncMatrixObserver(binding);
+                    syncRenderable(binding.renderableId);
+                }
+            }
+            for (const mesh of runtimeOverlayMeshes ?? scene.meshes)
+                registerMesh(mesh);
+        }
+        finally {
+            stagingPlanCandidateTransitions = false;
+        }
+        if (delta.lightDirectionChanged) {
+            syncSceneFitCoverage(true);
+            updateCameraInfluenceCoverage();
+        }
+        if (!haveSameAutomaticActivityCandidates(previousPlan, nextPlan, previousCandidateObjects)) {
+            const nextCandidates = new Map();
+            for (const binding of bindings.values()) {
+                updateAutomaticActivityCandidateBinding(nextCandidates, binding, objectByRenderable.get(binding.renderableId));
+            }
+            if (!applyAutomaticActivityCandidateTransition(nextCandidates)) {
+                throw new Error('shadowMapExperiment.automaticActivityCandidateCommitFailed');
+            }
+        }
+        for (const reason of delta.dirtyReasons) {
+            if (reason === 'quality-changed'
+                && delta.appearanceChanged
+                && !delta.generatorResourcesChanged)
+                continue;
+            registry.markDirty(reason);
+            enqueueRefresh(reason);
+        }
+    };
+    const flushPendingPlanRollbackRecovery = () => {
+        const recovery = pendingPlanRollbackRecovery;
+        if (!recovery)
+            return;
+        if (recovery.phase === 'deactivate') {
+            try {
+                deactivate();
+            }
+            catch { /* queue ownership remains for the next frame */ }
+            if (hasOwnedBackendState()) {
+                requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+                return;
+            }
+            if (!recovery.targetPlan?.enabled) {
+                pendingPlanRollbackRecovery = null;
+                return;
+            }
+            recovery.phase = 'activate';
+        }
+        const targetPlan = recovery.targetPlan;
+        if (!targetPlan)
+            return;
+        try {
+            if (!recovery.activated) {
+                // `plan` and the scheduler intentionally remain null until activation
+                // and automatic candidate/source publication have both completed.
+                activityScheduler.applyPlan(targetPlan);
+                activatingRecoveryPlan = targetPlan;
+                allowingRecoveryActivityRegistration = true;
+                try {
+                    activate(targetPlan);
+                }
+                finally {
+                    activatingRecoveryPlan = null;
+                }
+                recovery.activated = true;
+            }
+            allowingRecoveryActivityRegistration = true;
+            try {
+                flushPendingAutomaticAnimationGroupDetachCleanups();
+                flushPendingAutomaticAnimationGroupSourceCleanups();
+                flushPendingAutomaticActivityCandidateTransition();
+                flushPendingAutomaticAnimationGroupAttachments();
+                flushPendingAutomaticAnimationGroupReconciliations();
+            }
+            finally {
+                allowingRecoveryActivityRegistration = false;
+            }
+            if (pendingAutomaticActivityCandidateTransition
+                || pendingAutomaticAnimationGroupSourceCleanups.size > 0
+                || pendingAutomaticAnimationGroupDetachCleanups.size > 0
+                || pendingAutomaticAnimationGroupAttachments.size > 0
+                || pendingAutomaticAnimationGroupReconciliations.size > 0) {
+                requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+                return;
+            }
+            for (const entityId of recovery.activeEntityIds) {
+                activityScheduler.setEntityActive(entityId, true);
+                syncActivityEligibility(entityId);
+            }
+            plan = targetPlan;
+            automaticActivityCandidateRevision = recovery.candidateRevision;
+            for (const binding of automaticAnimationGroups.values()) {
+                binding.resolvedCandidateRevision = recovery.candidateRevision;
+            }
+            pendingPlanRollbackRecovery = null;
+        }
+        catch {
+            allowingRecoveryActivityRegistration = false;
+            plan = null;
+            activityScheduler.applyPlan(null);
+            recovery.phase = 'deactivate';
+            recovery.activated = false;
+            try {
+                deactivate();
+            }
+            catch { /* retained for bounded retry */ }
+            requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+        }
+    };
+    const rollbackPlanUpdate = (previousPlan, error, previousCandidateRevision = automaticActivityCandidateRevision) => {
+        let cleanupError = null;
+        try {
+            deactivate();
+        }
+        catch (deactivationError) {
+            cleanupError = deactivationError;
+        }
+        plan = null;
+        activityScheduler.applyPlan(null);
+        automaticActivityCandidateRevision = previousCandidateRevision;
+        if (cleanupError || hasOwnedBackendState()) {
+            pendingPlanRollbackRecovery = {
+                targetPlan: previousPlan,
+                candidateRevision: previousCandidateRevision,
+                activeEntityIds: new Set(activeCasterEntityIds),
+                phase: 'deactivate',
+                activated: false,
+            };
+            requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+            if (cleanupError && error && typeof error === 'object') {
+                attachFailureMetadata(error, { rollbackDeactivationErrors: Object.freeze([cleanupError]) });
+            }
+            throw error;
+        }
+        if (previousPlan?.enabled) {
+            pendingPlanRollbackRecovery = {
+                targetPlan: previousPlan,
+                candidateRevision: previousCandidateRevision,
+                activeEntityIds: new Set(activeCasterEntityIds),
+                phase: 'activate',
+                activated: false,
+            };
+            requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+        }
+        else {
+            automaticActivityCandidateRevision = previousCandidateRevision;
+        }
+        throw error;
+    };
+    const hasOwnedBackendState = () => bindings.size > 0
+        || pendingAutomaticActivityCandidateTransition !== null
+        || pendingMeshObserverCleanups.size > 0
+        || pendingMeshObserverRestorations.size > 0
+        || pendingMeshRegistrationRollbacks.size > 0
+        || pendingSceneMeshRegistrations.size > 0
+        || pendingMeshUnregistrations.size > 0
+        || pendingRenderableMembershipRetries.size > 0
+        || pendingTransformMembershipRetries.size > 0
+        || receiverStates.size > 0
+        || pendingReceiverRestorations.size > 0
+        || registry !== null
+        || depthBackend !== null
+        || pendingBackendAllocationCleanup !== null
+        || generator !== null
+        || lightState !== null
+        || previousSceneShadowsEnabled !== null;
+    const applyEffectivePlan = (value, allowDisposing = false, runtimeOverlayMeshes = null) => {
+        assertUsable(allowDisposing);
+        // Every caller supplies either a source snapshot or composeEffectivePlan()
+        // output. Re-cloning the full Plan for each runtime entity made a batch of
+        // synchronous overlay additions scale with the complete authored scene.
+        const nextPlan = value;
+        const previousPlan = plan;
+        const previousRuntimeOverlayObjects = [...runtimeRegistrations.values()]
+            .filter(record => !record.disposed)
+            .flatMap(record => {
+            const object = objectByEntity.get(record.entityId);
+            return object ? [object] : [];
+        });
+        // `plan.objects` may be a lazy operational snapshot (missing active
+        // overlays) or a previously materialized effective Plan (retaining a
+        // disposed overlay).  Rebuild only the candidate topology from the
+        // authored source and live overlays, never from that mixed snapshot.
+        const previousCandidateObjects = sourcePlan
+            ? [...sourcePlan.objects, ...previousRuntimeOverlayObjects]
+            : previousPlan?.objects ?? [];
+        const previousCandidateRevision = automaticActivityCandidateRevision;
+        if (previousPlan?.enabled && nextPlan?.enabled) {
+            const delta = diffShadowMapExperimentPlans(previousPlan, nextPlan);
+            if (!delta.generatorResourcesChanged) {
+                try {
+                    applyPlanInPlace(previousPlan, nextPlan, runtimeOverlayMeshes, previousCandidateObjects);
+                    return;
+                }
+                catch (error) {
+                    rollbackPlanUpdate(previousPlan, error, previousCandidateRevision);
+                }
+            }
+        }
+        const preserveAutomaticCandidates = previousPlan?.enabled === true
+            && nextPlan?.enabled === true
+            && haveSameAutomaticActivityCandidates(previousPlan, nextPlan, previousCandidateObjects);
+        suppressAutomaticActivityCandidateRevision = preserveAutomaticCandidates;
+        try {
+            deactivate();
+            plan = nextPlan;
+            activityScheduler.applyPlan(nextPlan?.enabled ? nextPlan : null);
+            if (!nextPlan?.enabled) {
+                reconcileAutomaticAnimationGroups();
+                return;
+            }
+            try {
+                activate(nextPlan);
+            }
+            catch (error) {
+                rollbackPlanUpdate(previousPlan, error, previousCandidateRevision);
+            }
+        }
+        finally {
+            suppressAutomaticActivityCandidateRevision = false;
+        }
+    };
+    const setPlan = (value) => {
+        assertUsable();
+        assertNoPlanRollbackRecovery();
+        const nextSourcePlan = value
+            ? deepFreezeShadowMapExperimentPlan(createShadowMapExperimentPlanSnapshot(value))
+            : null;
+        const records = [...runtimeRegistrations.values()].filter(record => !record.disposed);
+        const nextEffectivePlan = composeEffectivePlan(nextSourcePlan, records, runtimeOverlayRevision);
+        const previousSourcePlan = sourcePlan;
+        const previousMaterializedEffectivePlan = materializedEffectivePlan;
+        try {
+            applyEffectivePlan(nextEffectivePlan);
+            sourcePlan = nextSourcePlan;
+            materializedEffectivePlan = nextEffectivePlan;
+        }
+        catch (error) {
+            sourcePlan = previousSourcePlan;
+            materializedEffectivePlan = previousMaterializedEffectivePlan;
+            throw error;
+        }
+    };
+    const previewLightDirection = (entityId, direction) => {
+        assertUsable();
+        assertNoPlanRollbackRecovery();
+        if (!sourcePlan?.enabled
+            || !plan?.enabled
+            || !registry
+            || !lightState
+            || sourcePlan.light.entityId !== entityId)
+            return false;
+        if (areTuple3Equal(sourcePlan.light.direction, direction))
+            return true;
+        const nextLight = Object.freeze({
+            ...sourcePlan.light,
+            direction: Object.freeze([...direction]),
+        });
+        const nextSourcePlan = Object.freeze({
+            ...sourcePlan,
+            light: nextLight,
+        });
+        const nextOperationalPlan = Object.freeze({ ...plan, light: nextLight });
+        const nextMaterializedEffectivePlan = materializedEffectivePlan
+            ? Object.freeze({ ...materializedEffectivePlan, light: nextLight })
+            : null;
+        const previousPlan = plan;
+        const previousCandidateRevision = automaticActivityCandidateRevision;
+        const previousLightState = captureLight(lightState.light);
+        try {
+            configureLight(lightState.light, nextOperationalPlan, {
+                center: effectiveCoverageCenter ?? nextOperationalPlan.generator.bounds.center,
+                extent: effectiveCoverageExtent ?? nextOperationalPlan.generator.bounds.extent,
+                near: effectiveCoverageNear ?? nextOperationalPlan.generator.bounds.near,
+                far: effectiveCoverageFar ?? nextOperationalPlan.generator.bounds.far,
+            });
+        }
+        catch (error) {
+            try {
+                restoreLight(previousLightState);
+            }
+            catch (rollbackError) {
+                if (error && typeof error === 'object') {
+                    attachFailureMetadata(error, {
+                        lightPreviewRollbackErrors: Object.freeze([rollbackError]),
+                    });
+                }
+                rollbackPlanUpdate(previousPlan, error, previousCandidateRevision);
+            }
+            throw error;
+        }
+        sourcePlan = nextSourcePlan;
+        plan = nextOperationalPlan;
+        materializedEffectivePlan = nextMaterializedEffectivePlan;
+        influenceCulling.configure(nextOperationalPlan.culling.guardBandRatio);
+        pendingCoverageMembershipRebuild = nextOperationalPlan.culling.enabled;
+        cullingStable = !nextOperationalPlan.culling.enabled;
+        lastCullingInvalidationReason = 'light-direction-changed';
+        registry.markDirty('light-direction-changed');
+        enqueueRefresh('light-direction-changed');
+        return true;
+    };
+    const previewAppearance = (value) => {
+        assertUsable();
+        assertNoPlanRollbackRecovery();
+        if (!sourcePlan?.enabled || !plan?.enabled || !depthBackend)
+            return false;
+        const nextAppearance = resolveShadowMapExperimentAppearance(value);
+        const currentAppearance = resolveShadowMapExperimentAppearance(sourcePlan.generator);
+        if (nextAppearance.darkness === currentAppearance.darkness
+            && nextAppearance.softness === currentAppearance.softness)
+            return true;
+        setPlan(Object.freeze({
+            ...sourcePlan,
+            generator: Object.freeze({
+                ...sourcePlan.generator,
+                darkness: nextAppearance.darkness,
+                softness: nextAppearance.softness,
+            }),
+        }));
+        return true;
+    };
+    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 => {
+                sceneOwnedMeshes.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);
+                requestRefreshFrame('shadow-map-experiment-mesh-registration-retry');
+                queueMicrotask(() => {
+                    if (disposed || disposing || !pendingSceneMeshRegistrations.has(mesh))
+                        return;
+                    if (!scene.meshes.includes(mesh)) {
+                        pendingSceneMeshRegistrations.delete(mesh);
+                        return;
+                    }
+                    try {
+                        registerMesh(mesh);
+                        pendingSceneMeshRegistrations.delete(mesh);
+                    }
+                    catch {
+                        pendingSceneMeshRegistrations.add(mesh);
+                        requestRefreshFrame('shadow-map-experiment-mesh-registration-retry');
+                    }
+                });
+            });
+            acquiredRemovedMeshObserver = scene.onMeshRemovedObservable.add(mesh => {
+                sceneOwnedMeshes.delete(mesh);
+                requestMeshUnregistration(mesh);
+            });
+            acquiredNewAnimationGroupObserver = scene.onNewAnimationGroupAddedObservable.add(group => {
+                if (automaticActivityCandidateBindings.size === 0)
+                    return;
+                try {
+                    attachAutomaticAnimationGroup(group);
+                }
+                catch (error) {
+                    pendingAutomaticAnimationGroupAttachments.add(group);
+                    requestRefreshFrame('shadow-map-experiment-automatic-activity-attach-retry');
+                    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());
+            if (automaticActivityCandidateBindings.size > 0) {
+                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 disposeRuntimeRecordsForSystem = (records) => {
+        const cleanupErrors = [];
+        for (const record of [...records].reverse()) {
+            for (const [sourceId, controller] of [...record.controllers.entries()].reverse()) {
+                try {
+                    controller.setActive(false);
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+                try {
+                    controller.dispose();
+                    record.controllers.delete(sourceId);
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+            }
+            if (record.controllers.size === 0) {
+                runtimeRegistrations.delete(record.entityId);
+                for (const renderable of record.renderables)
+                    runtimeOwnedMeshes.delete(renderable.mesh);
+                explicitRuntimeActivityEntityIds.delete(record.entityId);
+                record.disposed = true;
+            }
+        }
+        return Object.freeze(cleanupErrors);
+    };
+    const applyRuntimeObjectDelta = (input) => {
+        if (!sourcePlan || !plan?.enabled || !registry || !generator) {
+            throw new Error('shadowMapExperiment.runtimePlanUnavailable');
+        }
+        runtimeIncrementalMutationCount += 1;
+        const removedEntityIds = input.removedObjects.map(object => object.entityId);
+        const removedRenderableIds = input.removedObjects.flatMap(object => object.renderableIds);
+        updateOperationalPlanRevision(input.overlayRevision);
+        for (const object of input.removedObjects) {
+            objectByEntity.delete(object.entityId);
+            for (const renderableId of object.renderableIds) {
+                if (objectByRenderable.get(renderableId)?.entityId === object.entityId) {
+                    objectByRenderable.delete(renderableId);
+                }
+            }
+        }
+        for (const object of input.upsertedObjects) {
+            objectByEntity.set(object.entityId, object);
+            for (const renderableId of object.renderableIds)
+                objectByRenderable.set(renderableId, object);
+        }
+        activityScheduler.applyObjectDelta({
+            upsertedObjects: input.upsertedObjects,
+            removedEntityIds,
+        });
+        registry.applyObjectDelta({
+            planRevision: sourcePlan.revision + input.overlayRevision,
+            upsertedObjects: input.upsertedObjects,
+            removedRenderableIds,
+        });
+        invalidateSceneFitBounds();
+        stagingPlanCandidateTransitions = true;
+        try {
+            for (const mesh of input.meshes) {
+                const binding = bindings.get(mesh);
+                if (!binding)
+                    continue;
+                const resolvedId = resolveRenderableId(mesh, objectByRenderable);
+                const resolvedObject = resolvedId ? objectByRenderable.get(resolvedId) : null;
+                if (resolvedId !== binding.renderableId
+                    || resolvedObject?.entityId !== binding.entityId
+                    || (!resolvedObject.cast && !resolvedObject.receive)) {
+                    unregisterMesh(mesh);
+                }
+                else {
+                    syncMatrixObserver(binding);
+                    syncRenderable(binding.renderableId);
+                }
+            }
+            for (const mesh of input.meshes)
+                registerMesh(mesh);
+        }
+        finally {
+            stagingPlanCandidateTransitions = false;
+        }
+        const candidateTopologyChanged = [...input.upsertedObjects, ...input.removedObjects]
+            .some(isAutomaticActivityCandidateObject);
+        if (candidateTopologyChanged) {
+            const nextCandidates = new Map();
+            for (const binding of bindings.values()) {
+                updateAutomaticActivityCandidateBinding(nextCandidates, binding, objectByRenderable.get(binding.renderableId));
+            }
+            if (!applyAutomaticActivityCandidateTransition(nextCandidates)) {
+                throw new Error('shadowMapExperiment.automaticActivityCandidateCommitFailed');
+            }
+        }
+    };
+    const createRuntimeOwner = (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);
+                if (pendingPlanRollbackRecovery && !disposing) {
+                    throw new Error('shadowMapExperiment.planRollbackRecoveryPending');
+                }
+                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 removedObjects = records.flatMap(record => {
+                        const object = objectByEntity.get(record.entityId);
+                        return object ? [object] : [];
+                    });
+                    const runtimeMeshes = collectRuntimeRecordMeshes(records);
+                    const previousCandidateRevision = automaticActivityCandidateRevision;
+                    try {
+                        applyRuntimeObjectDelta({
+                            upsertedObjects: Object.freeze([]),
+                            removedObjects,
+                            overlayRevision: nextOverlayRevision,
+                            meshes: runtimeMeshes,
+                        });
+                        for (const record of records) {
+                            runtimeRegistrations.delete(record.entityId);
+                            for (const renderable of record.renderables)
+                                runtimeOwnedMeshes.delete(renderable.mesh);
+                            explicitRuntimeActivityEntityIds.delete(record.entityId);
+                        }
+                        runtimeOverlayRevision = nextOverlayRevision;
+                    }
+                    catch (error) {
+                        try {
+                            rollbackPlanUpdate(composeEffectivePlan(sourcePlan, [...runtimeRegistrations.values()].filter(candidate => !candidate.disposed), runtimeOverlayRevision), error, previousCandidateRevision);
+                        }
+                        catch (rollbackError) {
+                            cleanupErrors.push(rollbackError);
+                        }
+                    }
+                }
+                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 collectRuntimeRecordMeshes = (records) => {
+        const meshes = new Set();
+        for (const record of records) {
+            for (const renderable of record.renderables) {
+                meshes.add(renderable.mesh);
+                for (const mesh of meshesByRenderable.get(renderable.renderableId) ?? [])
+                    meshes.add(mesh);
+            }
+        }
+        return meshes;
+    };
+    const isMeshOwnedByScene = (mesh) => {
+        if (mesh.getScene() !== scene || isDisposed(mesh))
+            return false;
+        if (sceneOwnedMeshes.has(mesh))
+            return true;
+        // Babylon can emit a removal notification while a caller-owned Mesh still
+        // remains in Scene.meshes. Revalidate only this cache-miss boundary and
+        // repair the event-maintained index; normal runtime registration is O(1).
+        if (!scene.meshes.includes(mesh))
+            return false;
+        sceneOwnedMeshes.add(mesh);
+        return true;
+    };
+    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) || objectByEntity.has(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 || !isMeshOwnedByScene(renderable.mesh)) {
+                throw new Error(`shadowMapExperiment.runtimeMeshSceneMismatch:${renderableId}`);
+            }
+            if (batchMeshes.has(renderable.mesh)
+                || runtimeOwnedMeshes.has(renderable.mesh)
+                || bindings.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 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)
+                || activityScheduler.hasSource(entityId, sourceId)) {
+                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 createRuntimeSnapshot = () => Object.freeze({
+        planSchemaVersion: sourcePlan?.schemaVersion ?? null,
+        sourcePlanRevision: sourcePlan?.revision ?? null,
+        effectivePlanRevision: plan?.revision ?? null,
+        overlayRevision: runtimeOverlayRevision,
+        incrementalMutationCount: runtimeIncrementalMutationCount,
+        effectivePlanMaterializationCount,
+        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))),
+    });
+    const system = {
+        setPlan,
+        previewLightDirection,
+        previewAppearance,
+        getPlan: readMaterializedEffectivePlan,
+        getShadowGenerator: () => generator,
+        registerMesh(mesh) {
+            assertUsable();
+            if (pendingPlanRollbackRecovery) {
+                pendingSceneMeshRegistrations.add(mesh);
+                requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+                return false;
+            }
+            return registerMesh(mesh);
+        },
+        unregisterMesh(mesh) {
+            assertUsable();
+            if (pendingPlanRollbackRecovery) {
+                pendingMeshUnregistrations.add(mesh);
+                requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+                return;
+            }
+            requestMeshUnregistration(mesh);
+        },
+        setRenderableVisible(renderableId, visible) {
+            assertUsable();
+            if (pendingPlanRollbackRecovery) {
+                pendingExplicitVisibility.set(renderableId, visible);
+                pendingRenderableMembershipRetries.set(renderableId, 'caster');
+                requestRefreshFrame('shadow-map-experiment-plan-rollback-recovery');
+                return;
+            }
+            const previousRecord = registry?.getRecord(renderableId) ?? null;
+            let rollbackCasterMembership = null;
+            registry?.setVisible(renderableId, visible);
+            try {
+                rollbackCasterMembership = syncCaster(renderableId);
+                pendingRenderableMembershipRetries.delete(renderableId);
+            }
+            catch (error) {
+                rollbackCasterMembership?.(error);
+                if (previousRecord && registry) {
+                    if (previousRecord.renderableReady)
+                        registry.attach(renderableId, previousRecord.runtimeVisible);
+                    else
+                        registry.detach(renderableId);
+                    registry.setVisible(renderableId, previousRecord.runtimeVisible);
+                }
+                pendingExplicitVisibility.set(renderableId, visible);
+                pendingRenderableMembershipRetries.set(renderableId, 'caster');
+                requestRefreshFrame('shadow-map-experiment-membership-retry');
+                throw error;
+            }
+            const entityId = objectByRenderable.get(renderableId)?.entityId;
+            if (entityId)
+                syncActivityEligibility(entityId);
+        },
+        registerCasterActivitySource(input) {
+            if (pendingPlanRollbackRecovery && !allowingRecoveryActivityRegistration) {
+                assertNoPlanRollbackRecovery();
+            }
+            return registerActivitySource(input);
+        },
+        registerRuntimeShadowObjects(input) {
+            assertUsable();
+            assertNoPlanRollbackRecovery();
+            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();
+            const batchActivityIdentities = new Set();
+            const records = input.objects.map(object => validateRuntimeRegistration(object, batchEntityIds, batchRenderableIds, batchMeshes, batchActivityIdentities));
+            if (!sourcePlan)
+                throw new Error('shadowMapExperiment.runtimePlanUnavailable');
+            const runtimeObjects = createRuntimePlanObjects(sourcePlan, records);
+            const owner = createRuntimeOwner(records);
+            const nextOverlayRevision = runtimeOverlayRevision + 1;
+            const previousCandidateRevision = automaticActivityCandidateRevision;
+            for (const record of records) {
+                if (record.activities.length > 0)
+                    explicitRuntimeActivityEntityIds.add(record.entityId);
+            }
+            let effectivePlanMutationStarted = false;
+            let effectivePlanApplied = false;
+            try {
+                effectivePlanMutationStarted = true;
+                applyRuntimeObjectDelta({
+                    upsertedObjects: runtimeObjects,
+                    removedObjects: Object.freeze([]),
+                    overlayRevision: nextOverlayRevision,
+                    meshes: collectRuntimeRecordMeshes(records),
+                });
+                effectivePlanApplied = true;
+                for (const record of records) {
+                    runtimeRegistrations.set(record.entityId, record);
+                    for (const renderable of record.renderables)
+                        runtimeOwnedMeshes.add(renderable.mesh);
+                }
+                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 (effectivePlanMutationStarted) {
+                    try {
+                        const previousEffectivePlan = composeEffectivePlan(sourcePlan, [...runtimeRegistrations.values()].filter(candidate => (!records.includes(candidate) && !candidate.disposed)), runtimeOverlayRevision);
+                        if (effectivePlanApplied) {
+                            applyEffectivePlan(previousEffectivePlan, false, collectRuntimeRecordMeshes(records));
+                        }
+                        else {
+                            rollbackPlanUpdate(previousEffectivePlan, error, previousCandidateRevision);
+                        }
+                    }
+                    catch (rollbackError) {
+                        if (effectivePlanApplied || rollbackError !== error) {
+                            effectivePlanRollbackFailed = true;
+                            rollbackErrors.push(rollbackError);
+                        }
+                    }
+                }
+                for (const record of records) {
+                    runtimeRegistrations.delete(record.entityId);
+                    for (const renderable of record.renderables)
+                        runtimeOwnedMeshes.delete(renderable.mesh);
+                }
+                if (rollbackErrors.length > 0) {
+                    for (const record of records) {
+                        runtimeRegistrations.set(record.entityId, record);
+                        for (const renderable of record.renderables)
+                            runtimeOwnedMeshes.add(renderable.mesh);
+                    }
+                    if (effectivePlanRollbackFailed)
+                        runtimeOverlayRevision = nextOverlayRevision;
+                    throw createRuntimeRegistrationRollbackFailure(error, owner, rollbackErrors);
+                }
+                else {
+                    for (const record of records) {
+                        explicitRuntimeActivityEntityIds.delete(record.entityId);
+                        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');
+                invalidateSceneFitBounds(targetedObject ? targetedObject.renderableIds : null, true);
+            }
+            if (reason === 'material-alpha-test-changed' && targetedLayer) {
+                markDepthDirty(targetedLayer, reason);
+                return;
+            }
+            enqueueRefresh(reason);
+        },
+        getRuntimeSnapshot() {
+            assertUsable();
+            return createRuntimeSnapshot();
+        },
+        getEvidence() {
+            const effectivePlanSnapshot = readMaterializedEffectivePlan();
+            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,
+                candidateMeshCount: automaticActivityCandidateBindings.size,
+                candidateRevision: automaticActivityCandidateRevision,
+                targetResolutionCount: automaticActivityTargetResolutionCount,
+                cachedNegativeAnimationGroupCount: automaticBindings.filter(binding => !binding.rebindPending
+                    && binding.resolvedCandidateRevision === automaticActivityCandidateRevision
+                    && binding.sources.size === 0).length,
+            });
+            const depthEvidence = depthBackend?.getEvidence() ?? null;
+            const thresholdDiagnostics = effectivePlanSnapshot ? createThresholdDiagnostics(effectivePlanSnapshot, depthEvidence?.static.candidateMeshCount ?? 0, depthEvidence?.dynamic.candidateMeshCount ?? 0) : [];
+            return Object.freeze({
+                enabled: plan?.enabled === true,
+                planRevision: plan?.revision ?? null,
+                planFingerprint: effectivePlanSnapshot
+                    ? createShadowMapExperimentPlanFingerprint(effectivePlanSnapshot)
+                    : null,
+                effectivePlan: effectivePlanSnapshot
+                    ? createShadowMapExperimentPlanSnapshot(effectivePlanSnapshot)
+                    : 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,
+                appearance: plan?.enabled
+                    ? resolveShadowMapExperimentAppearance(plan.generator)
+                    : null,
+                renderListCount: depthBackend
+                    ? depthBackend.getEvidence().static.renderListCount + depthBackend.getEvidence().dynamic.renderListCount
+                    : 0,
+                receiverMeshCount: [...receiverStates.values()].filter(state => !isDisposed(state.mesh)
+                    && state.ownedValue
+                    && state.mesh.receiveShadows === state.ownedValue).length,
+                boundMeshCount: bindings.size,
+                activity,
+                automaticActivity,
+                runtime: createRuntimeSnapshot(),
+                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;
+            // Disposal is cleanup-only. A rollback recovery may be waiting to
+            // reactivate an old Plan; cancel that target before runtime owners start
+            // removing their overlays so no dispose retry can resurrect it.
+            if (pendingPlanRollbackRecovery) {
+                pendingPlanRollbackRecovery = {
+                    ...pendingPlanRollbackRecovery,
+                    targetPlan: null,
+                    phase: 'deactivate',
+                };
+            }
+            plan = null;
+            sourcePlan = null;
+            materializedEffectivePlan = null;
+            activityScheduler.applyPlan(null);
+            const runtimeCleanupErrors = disposeRuntimeRecordsForSystem([...runtimeRegistrations.values()]);
+            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);
+            pendingPlanRollbackRecovery = 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()) {
+                sceneOwnedMeshes.clear();
+                activeDeformationSourceCountByEntity.clear();
+                pendingFinalDeformationEntityIds.clear();
+                pendingDeformationInvalidations.clear();
+                activeCasterEntityIds.clear();
+                pendingTransformMembershipRetries.clear();
+                pendingSceneMeshRegistrations.clear();
+                pendingMeshUnregistrations.clear();
+                pendingRenderableMembershipRetries.clear();
+                pendingExplicitVisibility.clear();
+                pendingAutomaticAnimationGroupAttachments.clear();
+                pendingAutomaticAnimationGroupReconciliations.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)]);
+}
+export function resolveBabylonDirectionalLight(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) && !allowsTransparentShadowReceiving(material))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function deepFreezeShadowMapExperimentPlan(plan) {
+    const freeze = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const child of Object.values(value))
+            freeze(child);
+        if (!Object.isFrozen(value))
+            Object.freeze(value);
+    };
+    freeze(plan);
+    return plan;
+}
+function allowsTransparentShadowReceiving(material) {
+    if (!material)
+        return false;
+    const metadata = isRecord(material.metadata) ? material.metadata : null;
+    const shadowMapExperiment = metadata && isRecord(metadata.shadowMapExperiment)
+        ? metadata.shadowMapExperiment
+        : null;
+    return shadowMapExperiment?.allowTransparentReceiver === 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 resolveAutomaticActivityTarget(bindings, target, objectByRenderable, targetIndex) {
+    const className = readBabylonClassName(target);
+    const resolved = new Set();
+    if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+        return Object.freeze({ kind: 'transform', meshes: resolved });
+    }
+    if (className === 'MorphTarget') {
+        for (const mesh of targetIndex.meshesByMorphTarget.get(target) ?? [])
+            resolved.add(mesh);
+        return Object.freeze({ kind: 'morph', meshes: resolved });
+    }
+    const skeletons = new Set(targetIndex.skeletonsByTarget.get(target) ?? []);
+    const directSkeleton = callOptional(target, 'getSkeleton')
+        ?? target?._skeleton
+        ?? null;
+    if (directSkeleton)
+        skeletons.add(directSkeleton);
+    if (className === 'Bone' || hasFunction(target, 'getSkeleton') || skeletons.size > 0) {
+        for (const skeleton of skeletons) {
+            for (const mesh of targetIndex.meshesBySkeleton.get(skeleton) ?? [])
+                resolved.add(mesh);
+        }
+        return Object.freeze({ kind: 'animation', meshes: resolved });
+    }
+    const authoredOwner = resolveBabylonNodeAuthoredOwner(target, objectByRenderable);
+    if (authoredOwner) {
+        for (const mesh of targetIndex.meshesByRenderable.get(authoredOwner.renderableId) ?? []) {
+            if (mesh === authoredOwner.node || isBabylonNodeDescendantOf(mesh, authoredOwner.node)) {
+                resolved.add(mesh);
+            }
+        }
+        return Object.freeze({ kind: 'transform', meshes: resolved });
+    }
+    for (const [mesh, binding] of bindings) {
+        if (mesh === target
+            || isBabylonNodeDescendantOf(mesh, target)
+            || isBabylonNodeDescendantOf(target, mesh)) {
+            resolved.add(mesh);
+        }
+    }
+    return Object.freeze({ kind: 'transform', meshes: resolved });
+}
+function resolveBabylonNodeAuthoredOwner(target, objectByRenderable) {
+    let current = target;
+    while (current && (typeof current === 'object' || typeof current === 'function')) {
+        for (const candidate of collectIdentityCandidates(current)) {
+            if (objectByRenderable.has(candidate)) {
+                return Object.freeze({
+                    node: current,
+                    renderableId: candidate,
+                });
+            }
+        }
+        current = current.parent ?? null;
+    }
+    return null;
+}
+function createAutomaticActivityTargetIndex(bindings, targets) {
+    const meshesByRenderable = new Map();
+    const meshesBySkeleton = new Map();
+    const skeletonsByTarget = new Map();
+    const meshesByMorphTarget = new Map();
+    const indexedSkeletons = new Set();
+    for (const [mesh, binding] of bindings) {
+        addMapSetValue(meshesByRenderable, binding.renderableId, mesh);
+        const skeleton = mesh.skeleton;
+        if (skeleton) {
+            addMapSetValue(meshesBySkeleton, skeleton, mesh);
+        }
+        if (skeleton && !indexedSkeletons.has(skeleton)) {
+            indexedSkeletons.add(skeleton);
+            for (const bone of skeleton.bones ?? []) {
+                if (targets.has(bone))
+                    addMapSetValue(skeletonsByTarget, bone, skeleton);
+                const transformNode = callOptional(bone, 'getTransformNode')
+                    ?? bone?._linkedTransformNode
+                    ?? null;
+                if (transformNode && targets.has(transformNode)) {
+                    addMapSetValue(skeletonsByTarget, transformNode, skeleton);
+                }
+            }
+        }
+        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) {
+            let morphTarget;
+            try {
+                morphTarget = manager.getTarget(index);
+            }
+            catch {
+                continue;
+            }
+            if (morphTarget && targets.has(morphTarget)) {
+                addMapSetValue(meshesByMorphTarget, morphTarget, mesh);
+            }
+        }
+    }
+    return {
+        meshesByRenderable,
+        meshesBySkeleton,
+        skeletonsByTarget,
+        meshesByMorphTarget,
+    };
+}
+function addMapSetValue(map, key, value) {
+    const values = map.get(key);
+    if (values) {
+        values.add(value);
+    }
+    else {
+        map.set(key, new Set([value]));
+    }
+}
+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