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

package/dist/agent-bridge/capabilities/shadows.js

@@ -1,9 +1,8 @@
-import { collectEditorShadowReceiverCandidates, detectEditorSceneDirectionalLightOrientationDrift, findEditorSceneTransform, normalizeEditorSceneLightDirectionVector, resolveEditorSceneGameObjectShadowSettings, resolveEditorShadowPlan, } from '@fps-games/editor-playable-sdk';
-import { assertEditorShadowSettingsContract, mergeEditorShadowSettings, readEditorShadowSettings, resolveEditorShadowParams, } from '@fps-games/playable-rendering';
+import { collectEditorShadowReceiverCandidates, detectEditorSceneDirectionalLightOrientationDrift, findEditorSceneModelRenderer, findEditorScenePrefabAsset, findEditorScenePrefabNode, findEditorSceneTransform, normalizeEditorSceneLightDirectionVector, readEditorScenePrefabNodes, readEditorScenePrefabRootNodeId, resolveEditorSceneGameObjectShadowSettings, resolveEditorSceneGameObjectRuntimeEntityIds, resolveEditorScenePrefabInstanceRelation, resolveEditorShadowPlan, } from '@fps-games/editor-playable-sdk';
+import { assertEditorShadowSettingsContract, assertShadowMapExperimentConfig, createShadowMapExperimentPlanSnapshot, createShadowMapExperimentPlanFingerprint, mergeEditorShadowSettings, readEditorShadowSettings, resolveEditorShadowParams, } from '@fps-games/playable-rendering';
 import { EDITOR_AGENT_BRIDGE_CAPABILITY_ID, } from '@fps-games/editor-protocol';
 import { createLocalEditorAgentBridgeFailure, editorTransformSnapshotToAgentTransform, } from '../diagnostics.js';
-import { getAgentBridgeSafeSceneSelection, isAgentBridgeSafeSceneObjectId, normalizeAgentBridgeIdList, normalizeAgentBridgeString, } from '../shared.js';
-const PREFAB_STAGE_ITEM_PREFIX = 'prefab-node:';
+import { createAgentBridgeSafePrefabReadModel, getAgentBridgeSafeSceneSelection, hasAgentBridgeSafeSceneScope, isAgentBridgeSafeSceneObjectId, normalizeAgentBridgeIdList, normalizeAgentBridgeString, } from '../shared.js';
 const SHADOW_POLICY_FIELDS = [
     'shadow.cast',
     'shadow.receive',
@@ -23,11 +22,75 @@ const SHADOW_POLICY_FIELDS = [
 ];
 export function createLocalEditorAgentBridgeShadowSource(state, options, renderUi, operations) {
     return {
+        getShadowMapExperimentConfig() {
+            const config = readShadowMapExperimentConfig(options, EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_CONFIG_GET);
+            if (!config.ok)
+                return config.result;
+            return createShadowMapExperimentConfigOutput(config.config);
+        },
+        getShadowMapExperimentPolicy(input) {
+            const config = readShadowMapExperimentConfig(options, EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_GET);
+            if (!config.ok)
+                return config.result;
+            const resolved = resolveShadowMapExperimentTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_GET, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            return createShadowMapExperimentPolicyOutput(resolved.target, config.config, readShadowMapExperimentPlan(options, resolved.target.rawDocument));
+        },
+        setShadowMapExperimentPolicy(input) {
+            const config = readShadowMapExperimentConfig(options, EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET);
+            if (!config.ok)
+                return config.result;
+            if (!config.config) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, 'Shadow Map experiment config is not available.', { code: 'shadowMapExperiment.configMissing' });
+            }
+            const validation = validateShadowMapExperimentPolicySetInput(input, config.config);
+            if (!validation.ok) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, validation.message, { code: 'shadowMapExperiment.invalidInput', details: { scope: input.scope } });
+            }
+            const resolved = resolveShadowMapExperimentTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            return setShadowMapExperimentPolicy(state, options, renderUi, operations, resolved.target, input, config.config);
+        },
+        previewShadowMapExperimentPlan() {
+            const rawDocument = state.session?.getState({ cloneDocuments: false }).workingDocument;
+            if (state.mode !== 'editor' || !rawDocument) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_PLAN_PREVIEW, 'Editor is not in edit mode.', { code: 'editor.notReady' });
+            }
+            const plan = readShadowMapExperimentPlan(options, rawDocument);
+            return { plan: plan ? structuredClone(plan) : null };
+        },
+        snapshotShadowMapExperimentRuntime() {
+            const rawDocument = state.session?.getState({ cloneDocuments: false }).workingDocument;
+            if (state.mode !== 'editor' || !rawDocument) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_RUNTIME_SNAPSHOT, 'Editor is not in edit mode.', { code: 'editor.notReady' });
+            }
+            const evidence = operations.getShadowPreviewDebugInfo?.()?.shadowMapExperiment ?? null;
+            const sourcePlan = readShadowMapExperimentPlan(options, rawDocument);
+            const plan = resolveEvidenceVerifiedShadowMapExperimentPlan(readShadowMapExperimentExecutionPlan(operations), sourcePlan, evidence);
+            if (!plan && !evidence)
+                return { snapshot: null };
+            return {
+                snapshot: structuredClone({
+                    planSchemaVersion: plan?.schemaVersion ?? evidence?.runtime.planSchemaVersion ?? null,
+                    planRevision: plan?.revision ?? null,
+                    runtime: evidence?.runtime ?? null,
+                    activity: evidence?.activity ?? null,
+                    registry: evidence?.registry ?? null,
+                    depth: evidence?.depth ?? null,
+                    receiverMeshCount: evidence?.receiverMeshCount ?? 0,
+                    renderListCount: evidence?.renderListCount ?? 0,
+                    backend: evidence?.backend ?? null,
+                    diagnostics: evidence?.diagnostics ?? [],
+                }),
+            };
+        },
         getPolicy(input) {
             const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_GET, state, input, operations);
             if (!resolved.ok)
                 return resolved.result;
-            return createShadowPolicyGetOutput(resolved.target);
+            return createShadowPolicyGetOutput(resolved.target, resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations));
         },
         setPolicy(input) {
             const policy = normalizeShadowPolicy(input.policy);
@@ -48,11 +111,16 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
                 return resolved.result;
             const casterId = getResolvedTargetCasterId(resolved.target);
             const projectionContext = createShadowProjectionContext(resolved.target, operations);
+            const canonicalPlan = resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations);
+            const receiverIds = canonicalPlan?.receiverIds ?? [];
             return {
                 receivers: mapShadowReceivers(collectEditorShadowReceiverCandidates({
                     document: resolved.target.document,
                     casterId,
-                }), state, { casterId, projectionContext }).filter(receiver => input.includeAuto === true || receiver.source !== 'auto'),
+                    ...(receiverIds.length > 0 ? { explicitReceiverIds: receiverIds } : {}),
+                }), state, { casterId, projectionContext }).filter(receiver => (canonicalPlan
+                    ? receiverIds.includes(receiver.receiverId)
+                    : input.includeAuto === true || receiver.source !== 'auto')),
                 diagnostics: createShadowTargetDiagnostics(resolved.target),
             };
         },
@@ -73,18 +141,30 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
                 strictExplicitReceivers: receiverIds.length > 0,
                 ...(policy.settings !== undefined ? { settings: { instance: policy.settings } } : {}),
             };
-            const plan = mapShadowPlan(resolveEditorShadowPlan(planInput));
+            const shadowPreviewDebugInfo = operations.getShadowPreviewDebugInfo?.() ?? null;
+            const runtimeReceiverMeshCount = shadowPreviewDebugInfo?.shadowMapExperiment?.receiverMeshCount ?? 0;
+            const reconciledRuntimeReceiverMeshCount = receiverIds.length === 0 ? runtimeReceiverMeshCount : 0;
+            const legacyPlan = mapShadowPlan(resolveEditorShadowPlan(planInput), reconciledRuntimeReceiverMeshCount);
+            const canonicalPlan = input.policy === undefined && receiverIds.length === 0
+                ? resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations)
+                : null;
+            const plan = canonicalPlan ?? legacyPlan;
+            const plannedReceiverIds = plan.receiverIds;
             const allReceivers = mapShadowReceivers(collectEditorShadowReceiverCandidates({
                 document: resolved.target.document,
                 casterId,
-                explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+                explicitReceiverIds: receiverIds.length > 0
+                    ? receiverIds
+                    : plannedReceiverIds.length > 0
+                        ? plannedReceiverIds
+                        : undefined,
             }), state, {
                 casterId,
                 lightId: plan.lightId,
                 projectionContext: createShadowProjectionContext(resolved.target, operations),
             });
-            const receiverIdSet = new Set(plan.receiverIds);
-            const receivers = receiverIds.length > 0
+            const receiverIdSet = new Set(plannedReceiverIds);
+            const receivers = receiverIds.length > 0 || canonicalPlan
                 ? allReceivers.filter(receiver => receiverIdSet.has(receiver.receiverId))
                 : allReceivers;
             const light = createShadowLightSummary(resolved.target.document, plan.lightId);
@@ -93,7 +173,7 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
                 plan,
                 caster: createShadowDebugTargetSummary(resolved.target, state, createShadowProjectionContext(resolved.target, operations)),
                 ...(light ? { light } : {}),
-                footprint: createShadowFootprintSummary(plan, receivers, state, createShadowProjectionContext(resolved.target, operations), light),
+                footprint: createShadowFootprintSummary(plan, receivers, state, createShadowProjectionContext(resolved.target, operations), light, reconciledRuntimeReceiverMeshCount),
                 receivers,
                 diagnostics: createShadowTargetDiagnostics(resolved.target),
             };
@@ -106,13 +186,14 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
                 projectionContext: createShadowProjectionContext(resolved.target, operations),
             }, {
                 shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+                canonicalPlan: resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations),
             });
         },
         enterDebugContext(input) {
             const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_DEBUG_CONTEXT_ENTER, state, input, operations);
             if (!resolved.ok)
                 return resolved.result;
-            return enterShadowDebugContext(state, renderUi, operations, resolved.target, input);
+            return enterShadowDebugContext(state, renderUi, operations, resolved.target, input, resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations));
         },
         clearDebugContext() {
             return clearShadowDebugContext(state, renderUi, operations);
@@ -124,6 +205,8 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
             const inspect = createShadowDebugInspectOutput(resolved.target, state, {
                 receiverIds: input.receiverIds ?? [],
                 projectionContext: createShadowProjectionContext(resolved.target, operations),
+            }, {
+                canonicalPlan: resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations),
             });
             const overlayItems = createShadowDebugOverlayItems(inspect, input);
             const overlayIds = operations.setShadowDebugOverlay?.(overlayItems)
@@ -164,6 +247,8 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
             const inspect = createShadowDebugInspectOutput(resolved.target, state, {
                 receiverIds: input.receiverIds ?? [],
                 projectionContext: createShadowProjectionContext(resolved.target, operations),
+            }, {
+                canonicalPlan: resolveCanonicalShadowMapExperimentPlan(options, resolved.target, operations),
             });
             return createShadowDebugVisibilityMeasureOutput(inspect, input);
         },
@@ -317,14 +402,571 @@ export function createLocalEditorAgentBridgeShadowSource(state, options, renderU
         },
     };
 }
-function createShadowPolicyGetOutput(resolved) {
+function readShadowMapExperimentConfig(options, capabilityId) {
+    const value = options.documentAdapter.getShadowMapExperimentConfig?.() ?? null;
+    if (value === null)
+        return { ok: true, config: null };
+    try {
+        assertShadowMapExperimentConfig(value);
+        return { ok: true, config: structuredClone(value) };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, error instanceof Error ? error.message : String(error), { code: 'shadowMapExperiment.invalidConfig' }),
+        };
+    }
+}
+function createShadowMapExperimentConfigOutput(config) {
+    return {
+        configured: config !== null,
+        readonly: true,
+        config: config ? structuredClone(config) : null,
+        qualityProfileIds: config ? Object.keys(config.qualityProfiles).sort() : [],
+        behaviorProfileIds: config ? Object.keys(config.behaviorProfiles).sort() : [],
+    };
+}
+function readShadowMapExperimentPlan(options, document) {
+    try {
+        const value = options.documentAdapter?.getShadowMapExperimentPlan?.(document) ?? null;
+        if (value === null)
+            return null;
+        return createShadowMapExperimentPlanSnapshot(value);
+    }
+    catch {
+        return null;
+    }
+}
+function readShadowMapExperimentExecutionPlan(operations) {
+    if (operations.getShadowMapExperimentExecutionPlan) {
+        try {
+            const value = operations.getShadowMapExperimentExecutionPlan();
+            if (value === null)
+                return null;
+            return createShadowMapExperimentPlanSnapshot(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function resolveCanonicalShadowMapExperimentPlan(options, target, operations) {
+    if (target.kind !== 'scene')
+        return null;
+    const sourcePlan = readShadowMapExperimentPlan(options, target.rawDocument);
+    const shadowMapExperimentEvidence = operations.getShadowPreviewDebugInfo?.()?.shadowMapExperiment ?? null;
+    const directExecutionPlan = readShadowMapExperimentExecutionPlan(operations);
+    const verifiedExecutionPlan = resolveEvidenceVerifiedShadowMapExperimentPlan(directExecutionPlan, sourcePlan, shadowMapExperimentEvidence);
+    const executionPlan = verifiedExecutionPlan;
+    const projectionPlan = sourcePlan?.enabled === true && executionPlan?.enabled !== true
+        ? sourcePlan
+        : executionPlan ?? sourcePlan;
+    if (!projectionPlan?.enabled)
+        return null;
+    const executionObjects = executionPlan?.enabled
+        ? resolveShadowMapExperimentPlanObjectsForGameObject(executionPlan, target.document, target.objectId)
+        : [];
+    const sourceObjects = sourcePlan?.enabled
+        ? resolveShadowMapExperimentPlanObjectsForGameObject(sourcePlan, target.document, target.objectId)
+        : [];
+    const objects = executionObjects.length > 0 ? executionObjects : sourceObjects;
+    const object = objects[0];
+    if (!object)
+        return null;
+    const cast = executionObjects.some(candidate => candidate.cast);
+    const receiverIds = cast && executionPlan
+        ? resolveShadowMapExperimentAuthoringReceiverIds(executionPlan, target.document, target.objectId)
+        : [];
+    const diagnostics = [];
+    if (executionObjects.length > 0 && executionPlan) {
+        diagnostics.push({
+            severity: 'info',
+            source: 'editor',
+            code: directExecutionPlan ? 'shadow.canonicalExecutionPlan' : 'shadow.canonicalExecutionEvidence',
+            message: directExecutionPlan
+                ? 'Editor shadow preview is resolved from the Renderer plan that is currently in effect.'
+                : 'Editor shadow preview is resolved from the complete Renderer evidence plan that is currently in effect.',
+            details: {
+                planSchemaVersion: executionPlan.schemaVersion,
+                planRevision: executionPlan.revision,
+                qualityProfileId: executionPlan.qualityProfileId,
+                behaviorProfileId: object.behaviorProfileId,
+                updateClass: object.updateClass,
+            },
+        });
+    }
+    else {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.canonicalExecutionPending',
+            message: 'The authored Shadow Map plan is not active in Renderer yet, so the target currently casts no preview shadow.',
+            details: {
+                sourcePlanRevision: sourcePlan?.revision ?? null,
+                effectivePlanRevision: executionPlan?.revision ?? null,
+                sourcePlanFingerprint: sourcePlan ? createShadowMapExperimentPlanFingerprint(sourcePlan) : null,
+                effectivePlanFingerprint: shadowMapExperimentEvidence?.planFingerprint ?? null,
+            },
+        });
+    }
+    if (executionObjects.some(candidate => candidate.cast !== executionObjects[0]?.cast)) {
+        diagnostics.push({
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.canonicalTargetMixedExecution',
+            message: 'The authored object contains multiple runtime entities with mixed caster state; object-level preview reports active when any entity casts.',
+            details: {
+                entityIds: executionObjects.map(candidate => candidate.entityId),
+            },
+        });
+    }
+    if (sourcePlan && executionPlan && sourcePlan.revision !== executionPlan.revision) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.canonicalExecutionRevisionMismatch',
+            message: 'Renderer kept a previous Shadow Map plan after the authored plan changed.',
+            details: {
+                sourcePlanRevision: sourcePlan.revision,
+                effectivePlanRevision: executionPlan.revision,
+            },
+        });
+    }
+    for (const diagnostic of projectionPlan.diagnostics) {
+        if (diagnostic.entityId && !objects.some(candidate => candidate.entityId === diagnostic.entityId))
+            continue;
+        diagnostics.push({
+            severity: diagnostic.severity,
+            source: 'runtime',
+            code: diagnostic.code,
+            message: diagnostic.message,
+            ...(diagnostic.details ? { details: structuredClone(diagnostic.details) } : {}),
+        });
+    }
+    const resolution = resolveShadowMapExperimentResolution(projectionPlan);
+    return {
+        casterId: target.objectId,
+        receiverIds,
+        ...(cast && executionPlan ? { lightId: executionPlan.light.entityId } : {}),
+        backend: cast ? 'dynamic-map' : 'none',
+        mode: cast ? 'dynamic' : 'none',
+        quality: resolveShadowMapExperimentQuality(resolution),
+        params: {
+            opacity: projectionPlan.generator.darkness,
+            softness: projectionPlan.generator.filter === 'hard' ? 0 : 0.5,
+            bias: projectionPlan.generator.bias,
+            normalBias: projectionPlan.generator.normalBias,
+            maxDistance: projectionPlan.generator.bounds.far,
+            resolution,
+            cascadeCount: 1,
+            bakeSamples: 1,
+            blurKernel: 0,
+        },
+        diagnostics,
+    };
+}
+function resolveEvidenceVerifiedShadowMapExperimentPlan(executionPlan, sourcePlan, evidence) {
+    if (executionPlan)
+        return executionPlan;
+    if (evidence?.effectivePlan) {
+        try {
+            const effectivePlan = createShadowMapExperimentPlanSnapshot(evidence.effectivePlan);
+            if (evidence.planFingerprint
+                && evidence.planFingerprint !== createShadowMapExperimentPlanFingerprint(effectivePlan))
+                return null;
+            return effectivePlan;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (sourcePlan
+        && evidence?.enabled === true
+        && evidence.planFingerprint === createShadowMapExperimentPlanFingerprint(sourcePlan)) {
+        return sourcePlan;
+    }
+    return null;
+}
+function resolveShadowMapExperimentPlanObjectsForGameObject(plan, document, objectId) {
+    const runtimeEntityIds = new Set(resolveEditorSceneGameObjectRuntimeEntityIds(document, objectId));
+    runtimeEntityIds.add(objectId);
+    return plan.objects.filter(candidate => runtimeEntityIds.has(candidate.entityId));
+}
+function resolveShadowMapExperimentAuthoringReceiverIds(plan, document, casterObjectId) {
+    const receivingEntityIds = new Set(plan.objects.filter(candidate => candidate.receive).map(candidate => candidate.entityId));
+    return document.scene.gameObjects
+        .filter(candidate => candidate.id !== casterObjectId)
+        .filter(candidate => resolveEditorSceneGameObjectRuntimeEntityIds(document, candidate.id)
+        .some(entityId => receivingEntityIds.has(entityId)))
+        .map(candidate => candidate.id);
+}
+function resolveShadowMapExperimentQuality(resolution) {
+    if (resolution <= 512)
+        return 'low';
+    if (resolution <= 1024)
+        return 'medium';
+    if (resolution <= 2048)
+        return 'high';
+    return 'ultra';
+}
+function resolveShadowMapExperimentResolution(plan) {
+    const resolution = Math.max(plan.generator.maps.staticResolution, plan.generator.maps.dynamicResolution, plan.generator.maps.compositeResolution);
+    if (resolution <= 512)
+        return 512;
+    if (resolution <= 1024)
+        return 1024;
+    if (resolution <= 2048)
+        return 2048;
+    return 4096;
+}
+function resolveShadowMapExperimentTarget(capabilityId, state, input, operations) {
+    if (state.mode !== 'editor' || !state.session) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, 'Editor is not in edit mode.', { code: 'editor.notReady' }),
+        };
+    }
+    const sessionState = state.session.getState({ cloneDocuments: false });
+    const document = asEditorSceneDocument(sessionState.workingDocument);
+    if (!document) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, 'Shadow Map profiles require an editor scene document.', {
+                code: 'shadowMapExperiment.unsupportedDocument',
+            }),
+        };
+    }
+    if (input.scope === 'scene') {
+        if (!hasAgentBridgeSafeSceneScope(operations)) {
+            return {
+                ok: false,
+                result: createLocalEditorAgentBridgeFailure(capabilityId, 'Scene Shadow Map profiles require the active Scene Hierarchy scope.', {
+                    code: 'shadowMapExperiment.scopeMismatch',
+                }),
+            };
+        }
+        return {
+            ok: true,
+            target: {
+                kind: 'scene',
+                target: { scope: 'scene' },
+                document,
+                rawDocument: sessionState.workingDocument,
+            },
+        };
+    }
+    if (input.scope === 'object') {
+        const objectId = normalizeAgentBridgeString(input.objectId);
+        const gameObject = objectId && isAgentBridgeSafeSceneObjectId(operations, objectId)
+            ? findShadowGameObject(document, objectId)
+            : null;
+        if (!gameObject) {
+            return {
+                ok: false,
+                result: createLocalEditorAgentBridgeFailure(capabilityId, objectId
+                    ? `Shadow Map target object not found: ${objectId}`
+                    : 'objectId is required for object scope.', {
+                    code: objectId ? 'shadowMapExperiment.targetNotFound' : 'shadowMapExperiment.targetRequired',
+                    objectId: objectId || undefined,
+                }),
+            };
+        }
+        return {
+            ok: true,
+            target: {
+                kind: 'object',
+                target: { scope: 'object', objectId },
+                document,
+                rawDocument: sessionState.workingDocument,
+                objectId,
+                gameObject,
+            },
+        };
+    }
+    if (input.scope !== 'prefab-node') {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, `Unsupported Shadow Map target scope: ${String(input.scope)}`, {
+                code: 'shadowMapExperiment.invalidScope',
+            }),
+        };
+    }
+    const details = operations.getPrefabStageDetails();
+    if (!details) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, 'Open the target Prefab stage before editing a prefab-node profile.', {
+                code: 'prefab.stageNotOpen',
+            }),
+        };
+    }
+    const requestedAssetId = normalizeAgentBridgeString(input.prefabAssetId);
+    if (requestedAssetId && requestedAssetId !== details.stage.assetId && requestedAssetId !== details.stage.browserAssetId) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, `Open Prefab stage does not match ${requestedAssetId}.`, {
+                code: 'prefab.stageAssetMismatch',
+                details: { requestedAssetId, openAssetId: details.stage.assetId },
+            }),
+        };
+    }
+    if (!hasActivePrefabHierarchyScope(operations, details)) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, 'Open Prefab stage does not own the active Hierarchy authority.', {
+                code: 'shadowMapExperiment.scopeMismatch',
+                details: { prefabAssetId: details.stage.assetId },
+            }),
+        };
+    }
+    const prefabAsset = findEditorScenePrefabAsset(document, details.stage.assetId);
+    const rootNodeId = readEditorScenePrefabRootNodeId(prefabAsset);
+    const safeModel = createAgentBridgeSafePrefabReadModel(operations.getHierarchyReadModel(), details.nodeDetails);
+    const nodeId = resolveSafePrefabNodeAuthoredId(safeModel, normalizePrefabNodeId(input.nodeId));
+    const node = prefabAsset && nodeId ? findEditorScenePrefabNode(prefabAsset, nodeId) : null;
+    if (!prefabAsset || !rootNodeId || !nodeId || !node) {
+        return {
+            ok: false,
+            result: createLocalEditorAgentBridgeFailure(capabilityId, `Prefab node not found: ${nodeId ?? '(none)'}`, {
+                code: 'prefab.nodeNotFound',
+                details: { prefabAssetId: details.stage.assetId, nodeId },
+            }),
+        };
+    }
+    return {
+        ok: true,
+        target: {
+            kind: 'prefab-node',
+            target: { scope: 'prefab-node', prefabAssetId: details.stage.assetId, nodeId },
+            document,
+            rawDocument: sessionState.workingDocument,
+            prefabAssetId: details.stage.assetId,
+            nodeId,
+            rootNodeId,
+            prefabAsset,
+            node,
+        },
+    };
+}
+function validateShadowMapExperimentPolicySetInput(input, config) {
+    const hasQualityProfile = Object.prototype.hasOwnProperty.call(input, 'qualityProfile');
+    const hasBehaviorProfile = Object.prototype.hasOwnProperty.call(input, 'behaviorProfile');
+    if (!hasQualityProfile && !hasBehaviorProfile)
+        return { ok: false, message: 'At least one profile reference is required.' };
+    if (input.scope !== 'scene' && hasQualityProfile) {
+        return { ok: false, message: 'qualityProfile is only valid for scene scope.' };
+    }
+    if (input.qualityProfile !== undefined && input.qualityProfile !== null) {
+        if (!config || !Object.prototype.hasOwnProperty.call(config.qualityProfiles, input.qualityProfile)) {
+            return { ok: false, message: `Unknown quality profile: ${input.qualityProfile}` };
+        }
+    }
+    if (input.behaviorProfile !== undefined && input.behaviorProfile !== null) {
+        if (!config || !Object.prototype.hasOwnProperty.call(config.behaviorProfiles, input.behaviorProfile)) {
+            return { ok: false, message: `Unknown behavior profile: ${input.behaviorProfile}` };
+        }
+    }
+    return { ok: true };
+}
+function createShadowMapExperimentPolicyOutput(resolved, config, plan) {
+    const authored = readAuthoredShadowMapExperimentProfiles(resolved);
+    const plannedBehavior = resolved.kind === 'object'
+        ? summarizeShadowMapExperimentPlanObjectBehavior(plan, resolveEditorSceneGameObjectRuntimeEntityIds(resolved.document, resolved.objectId))
+        : null;
+    const qualityProfileId = resolved.kind === 'object'
+        ? plannedBehavior
+            ? plan?.qualityProfileId ?? null
+            : null
+        : plan?.qualityProfileId
+            ?? authored.qualityProfile
+            ?? resolved.document.scene.shadowMapExperiment?.qualityProfile
+            ?? config?.defaultQualityProfile
+            ?? null;
+    const behaviorProfileId = resolved.kind === 'object'
+        ? plannedBehavior?.behaviorProfileId ?? null
+        : resolveEffectiveShadowMapExperimentBehaviorProfile(resolved, config, plan);
+    const behavior = behaviorProfileId ? config?.behaviorProfiles[behaviorProfileId] : undefined;
+    return {
+        target: resolved.target,
+        authored,
+        effective: {
+            qualityProfileId,
+            behaviorProfileId,
+            cast: plannedBehavior ? plannedBehavior.cast : (behavior ? behavior.cast === 'enabled' : null),
+            receive: plannedBehavior ? plannedBehavior.receive : (behavior ? behavior.receive === 'enabled' : null),
+            updateClass: plannedBehavior
+                ? plannedBehavior.updateClass
+                : (behavior?.updateClass === 'auto' || !behavior ? null : behavior.updateClass),
+        },
+        qualityProfileIds: config ? Object.keys(config.qualityProfiles).sort() : [],
+        behaviorProfileIds: config ? Object.keys(config.behaviorProfiles).sort() : [],
+    };
+}
+function summarizeShadowMapExperimentPlanObjectBehavior(plan, runtimeEntityIds) {
+    const entityIds = new Set(runtimeEntityIds);
+    const candidates = plan?.objects.filter(object => entityIds.has(object.entityId)) ?? [];
+    const first = candidates[0];
+    if (!first)
+        return null;
+    const homogeneous = candidates.every(candidate => (candidate.behaviorProfileId === first.behaviorProfileId
+        && candidate.cast === first.cast
+        && candidate.receive === first.receive
+        && candidate.updateClass === first.updateClass));
+    if (!homogeneous) {
+        return { behaviorProfileId: null, cast: null, receive: null, updateClass: null };
+    }
+    return {
+        behaviorProfileId: first.behaviorProfileId,
+        cast: first.cast,
+        receive: first.receive,
+        updateClass: first.updateClass,
+    };
+}
+function readAuthoredShadowMapExperimentProfiles(resolved) {
+    if (resolved.kind === 'scene') {
+        return {
+            qualityProfile: resolved.document.scene.shadowMapExperiment?.qualityProfile ?? null,
+            behaviorProfile: resolved.document.scene.shadowMapExperiment?.behaviorProfile ?? null,
+        };
+    }
+    if (resolved.kind === 'object') {
+        return { qualityProfile: null, behaviorProfile: resolved.gameObject.shadowMapExperiment?.behaviorProfile ?? null };
+    }
+    const behaviorProfile = resolved.node.defaults?.shadowMapExperiment?.behaviorProfile;
+    return { qualityProfile: null, behaviorProfile: behaviorProfile ?? null };
+}
+function resolveEffectiveShadowMapExperimentBehaviorProfile(resolved, config, plan) {
+    if (resolved.kind === 'scene') {
+        return resolved.document.scene.shadowMapExperiment?.behaviorProfile ?? config?.defaultBehaviorProfile ?? null;
+    }
+    if (resolved.kind === 'object') {
+        const relation = resolveEditorScenePrefabInstanceRelation(resolved.document, resolved.objectId);
+        const modelRenderer = findEditorSceneModelRenderer(resolved.gameObject);
+        const sourceAsset = relation.sourceAsset
+            ?? (modelRenderer ? resolved.document.assets.find(asset => asset.id === modelRenderer.assetId) : undefined);
+        return resolved.gameObject.shadowMapExperiment?.behaviorProfile
+            ?? relation.definition?.prefab?.defaults?.shadowMapExperiment?.behaviorProfile
+            ?? readAssetShadowMapExperimentBehaviorProfile(sourceAsset)
+            ?? resolved.document.scene.shadowMapExperiment?.behaviorProfile
+            ?? config?.defaultBehaviorProfile
+            ?? null;
+    }
+    const sourceAsset = resolved.node.kind === 'model' && resolved.node.sourceAssetId
+        ? resolved.document.assets.find(asset => asset.id === resolved.node.sourceAssetId)
+        : undefined;
+    let behaviorProfile = config?.defaultBehaviorProfile ?? null;
+    behaviorProfile = resolved.document.scene.shadowMapExperiment?.behaviorProfile ?? behaviorProfile;
+    behaviorProfile = readAssetShadowMapExperimentBehaviorProfile(sourceAsset) ?? behaviorProfile;
+    behaviorProfile = resolved.prefabAsset.prefab?.defaults?.shadowMapExperiment?.behaviorProfile ?? behaviorProfile;
+    const nodes = readEditorScenePrefabNodes(resolved.prefabAsset);
+    const byId = new Map(nodes.map(node => [node.id, node]));
+    const ancestry = [];
+    let current = resolved.node;
+    while (current) {
+        ancestry.unshift(current);
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+    for (const node of ancestry) {
+        behaviorProfile = node.defaults?.shadowMapExperiment?.behaviorProfile ?? behaviorProfile;
+    }
+    return behaviorProfile;
+}
+function readAssetShadowMapExperimentBehaviorProfile(asset) {
+    if (!isRecord(asset) || !isRecord(asset.defaults) || !isRecord(asset.defaults.shadowMapExperiment))
+        return null;
+    return normalizeAgentBridgeString(asset.defaults.shadowMapExperiment.behaviorProfile) || null;
+}
+function setShadowMapExperimentPolicy(state, options, renderUi, operations, resolved, input, config) {
+    if (!state.session) {
+        return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, 'Editor is not in edit mode.', { code: 'editor.notReady' });
+    }
+    const authored = readAuthoredShadowMapExperimentProfiles(resolved);
+    const hasQualityProfile = Object.prototype.hasOwnProperty.call(input, 'qualityProfile');
+    const hasBehaviorProfile = Object.prototype.hasOwnProperty.call(input, 'behaviorProfile');
+    const qualityUnchanged = !hasQualityProfile || authored.qualityProfile === (input.qualityProfile ?? null);
+    const behaviorUnchanged = !hasBehaviorProfile || authored.behaviorProfile === (input.behaviorProfile ?? null);
+    if (qualityUnchanged && behaviorUnchanged) {
+        return {
+            changed: false,
+            policy: createShadowMapExperimentPolicyOutput(resolved, config, readShadowMapExperimentPlan(options, resolved.rawDocument)),
+        };
+    }
+    let changed = false;
+    if (resolved.kind === 'scene') {
+        const patch = options.documentAdapter.createShadowMapExperimentProfilesPatch?.({
+            document: resolved.rawDocument,
+            ...(hasQualityProfile ? { qualityProfile: input.qualityProfile ?? null } : {}),
+            ...(hasBehaviorProfile ? { behaviorProfile: input.behaviorProfile ?? null } : {}),
+        });
+        if (!patch) {
+            return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, 'The project rendering capability does not expose a scene Shadow Map profile patch.', { code: 'shadowMapExperiment.scenePatchUnavailable' });
+        }
+        const result = state.session.dispatch({
+            type: 'document.patch',
+            label: patch.label ?? 'Agent set scene Shadow Map profiles',
+            patch: patch.patch,
+            targetId: patch.changedId,
+            ...operations.withProjectionImpact(operations.resolveProjectionImpact(patch, operations.createReprojectProjectionImpact(patch.reprojectIds ?? []))),
+        });
+        changed = result.documentChanged;
+    }
+    else if (resolved.kind === 'object') {
+        const patch = options.documentAdapter.createSerializedPropertyPatch({
+            document: resolved.rawDocument,
+            targetId: resolved.objectId,
+            path: 'shadowMapExperiment.behaviorProfile',
+            value: input.behaviorProfile ?? null,
+            commitMode: 'change',
+            persistence: 'document',
+            source: 'custom',
+        });
+        if (!patch) {
+            return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, `Unable to create Shadow Map profile patch for ${resolved.objectId}.`, { code: 'shadowMapExperiment.objectPatchUnavailable', objectId: resolved.objectId });
+        }
+        const result = state.session.dispatch({
+            type: 'document.patch',
+            label: patch.label ?? `Agent set Shadow Map behavior profile ${resolved.objectId}`,
+            patch: patch.patch,
+            targetId: resolved.objectId,
+            ...operations.withProjectionImpact(operations.resolveProjectionImpact(patch, operations.createReprojectProjectionImpact(patch.reprojectIds ?? [resolved.objectId]))),
+        });
+        changed = result.documentChanged;
+    }
+    else {
+        changed = operations.runPrefabStageAssetAction({
+            actionId: 'prefab.node.setShadowMapExperiment',
+            targetPrefabAssetId: resolved.prefabAssetId,
+            nodeId: resolved.nodeId,
+            value: input.behaviorProfile == null ? null : { behaviorProfile: input.behaviorProfile },
+        });
+        if (!changed) {
+            return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_SET, `Shadow Map profile action did not change prefab node: ${resolved.nodeId}`, { code: 'shadowMapExperiment.prefabPatchUnavailable', details: { prefabAssetId: resolved.prefabAssetId, nodeId: resolved.nodeId } });
+        }
+    }
+    if (changed) {
+        const nextDocument = state.session.getState({ cloneDocuments: false }).workingDocument;
+        state.summary = operations.summarizeDocument(nextDocument, state.session.getSource());
+        state.status = `Agent set Shadow Map profiles for ${resolved.target.scope}`;
+        operations.refreshShadowPreview?.();
+        renderUi();
+    }
+    const nextResolved = resolveShadowMapExperimentTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_MAP_EXPERIMENT_POLICY_GET, state, resolved.target, operations);
+    if (!nextResolved.ok)
+        return nextResolved.result;
+    return {
+        changed,
+        policy: createShadowMapExperimentPolicyOutput(nextResolved.target, config, readShadowMapExperimentPlan(options, nextResolved.target.rawDocument)),
+    };
+}
+function createShadowPolicyGetOutput(resolved, canonicalPlan = null) {
     if (resolved.kind === 'scene') {
         const effective = resolveEditorSceneGameObjectShadowSettings(resolved.document, resolved.gameObject);
         return {
             target: resolved.target,
             ...(resolved.gameObject.shadow ? { policy: structuredClone(resolved.gameObject.shadow) } : {}),
             effectivePolicy: (effective.settings ? structuredClone(effective.settings) : {}),
-            plan: mapShadowPlan(resolveEditorShadowPlan({
+            plan: canonicalPlan ?? mapShadowPlan(resolveEditorShadowPlan({
                 document: resolved.document,
                 casterId: resolved.objectId,
             })),
@@ -357,14 +999,20 @@ function createShadowDebugInspectOutput(resolved, state, options = {}, extraOpti
         explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
         strictExplicitReceivers: receiverIds.length > 0,
     };
-    const plan = mapShadowPlan(resolveEditorShadowPlan(planInput));
+    const runtimeReceiverMeshCount = extraOptions?.shadowPreviewDebugInfo?.shadowMapExperiment?.receiverMeshCount ?? 0;
+    const reconciledRuntimeReceiverMeshCount = receiverIds.length === 0 ? runtimeReceiverMeshCount : 0;
+    const plan = extraOptions?.canonicalPlan ?? mapShadowPlan(resolveEditorShadowPlan(planInput), reconciledRuntimeReceiverMeshCount);
     const allReceivers = mapShadowReceivers(collectEditorShadowReceiverCandidates({
         document: resolved.document,
         casterId,
-        explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+        explicitReceiverIds: receiverIds.length > 0
+            ? receiverIds
+            : plan.receiverIds.length > 0
+                ? plan.receiverIds
+                : undefined,
     }), state, { casterId, lightId: plan.lightId, projectionContext });
     const resolvedReceiverIds = new Set(plan.receiverIds);
-    const receivers = receiverIds.length > 0
+    const receivers = receiverIds.length > 0 || extraOptions?.canonicalPlan
         ? allReceivers.filter(receiver => resolvedReceiverIds.has(receiver.receiverId))
         : allReceivers;
     const authoredPolicy = getResolvedTargetAuthoredPolicy(resolved);
@@ -383,12 +1031,12 @@ function createShadowDebugInspectOutput(resolved, state, options = {}, extraOpti
         plan,
         ...(light ? { light } : {}),
         receivers,
-        footprint: createShadowFootprintSummary(plan, receivers, state, projectionContext, light),
+        footprint: createShadowFootprintSummary(plan, receivers, state, projectionContext, light, reconciledRuntimeReceiverMeshCount),
         runtimeEvidence,
         ...(diagnostics.length ? { diagnostics } : {}),
     };
 }
-function enterShadowDebugContext(state, renderUi, operations, resolved, input) {
+function enterShadowDebugContext(state, renderUi, operations, resolved, input, canonicalPlan = null) {
     const projectionContext = createShadowProjectionContext(resolved, operations);
     const receiverIds = normalizeAgentBridgeIdList(input.receiverIds ?? []);
     const initialInspect = createShadowDebugInspectOutput(resolved, state, {
@@ -396,6 +1044,7 @@ function enterShadowDebugContext(state, renderUi, operations, resolved, input) {
         projectionContext,
     }, {
         shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+        canonicalPlan,
     });
     const targetId = getResolvedTargetCasterId(resolved);
     const logicalKeepIds = new Set([targetId]);
@@ -441,11 +1090,13 @@ function enterShadowDebugContext(state, renderUi, operations, resolved, input) {
         || `Shadow Debug Context for ${targetId}`;
     state.projection?.clearPreviewVisibilityOverrides?.();
     const entries = state.projection?.setPreviewVisibilityOverrides?.(nextOverrides) ?? [];
+    operations.refreshShadowPreview?.();
     const inspect = createShadowDebugInspectOutput(resolved, state, {
         receiverIds,
         projectionContext,
     }, {
         shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+        canonicalPlan,
     });
     const overlayItems = input.showOverlay === false
         ? []
@@ -515,6 +1166,7 @@ function clearShadowDebugContext(state, renderUi, operations) {
     delete state.previewVisibility.protectedReceiverIds;
     delete state.previewVisibility.reason;
     state.projection?.clearPreviewVisibilityOverrides?.();
+    operations.refreshShadowPreview?.();
     const overlayCleared = operations.clearShadowDebugOverlay?.()
         ?? state.projection?.clearShadowDebugOverlay?.()
         ?? false;
@@ -947,8 +1599,7 @@ function setSceneShadowPolicy(state, options, renderUi, operations, resolved, po
     };
 }
 function setPrefabStageShadowPolicy(renderUi, operations, resolved, policy) {
-    const rootNodeId = findPrefabRootNodeId(resolved.details);
-    const changed = resolved.nodeId === rootNodeId
+    const changed = resolved.nodeId === resolved.rootNodeId
         ? setPrefabRootShadowPolicy(operations, resolved.details, policy)
         : operations.runPrefabStageAssetAction({
             actionId: 'prefab.node.setShadow',
@@ -964,7 +1615,7 @@ function setPrefabStageShadowPolicy(renderUi, operations, resolved, policy) {
     const nextResolved = resolvePrefabShadowTargetFromDetails(nextDetails, {
         nodeId: resolved.nodeId,
         assetId: resolved.details.stage.assetId,
-    });
+    }, operations);
     const output = createShadowPolicyGetOutput(nextResolved ?? resolved);
     return {
         target: output.target,
@@ -1057,7 +1708,16 @@ function resolveShadowTarget(capabilityId, state, input, operations) {
     }
     const details = operations.getPrefabStageDetails();
     if (details) {
-        const prefabTarget = resolvePrefabShadowTargetFromDetails(details, input);
+        if (!hasActivePrefabHierarchyScope(operations, details)) {
+            return {
+                ok: false,
+                result: createLocalEditorAgentBridgeFailure(capabilityId, 'Open Prefab stage does not own the active Hierarchy authority.', {
+                    code: 'shadow.scopeMismatch',
+                    details: { prefabAssetId: details.stage.assetId },
+                }),
+            };
+        }
+        const prefabTarget = resolvePrefabShadowTargetFromDetails(details, input, operations);
         if (prefabTarget)
             return { ok: true, target: prefabTarget };
     }
@@ -1086,27 +1746,47 @@ function resolveShadowTarget(capabilityId, state, input, operations) {
         }),
     };
 }
-function resolvePrefabShadowTargetFromDetails(details, input) {
+function resolvePrefabShadowTargetFromDetails(details, input, operations) {
     const requestedAssetId = 'assetId' in input ? normalizeAgentBridgeString(input.assetId) : '';
     if (requestedAssetId && requestedAssetId !== details.stage.assetId && requestedAssetId !== details.stage.browserAssetId)
         return null;
-    const nodes = listPrefabShadowNodes(details);
-    const nodeId = normalizePrefabNodeId(input.nodeId)
-        || getSelectedPrefabNodeId(details.stage.selectedItemId)
-        || findPrefabRootNodeId(details);
+    const model = operations.getHierarchyReadModel();
+    if (!hasActivePrefabHierarchyScope(operations, details, model))
+        return null;
+    const safeModel = createAgentBridgeSafePrefabReadModel(model, details.nodeDetails);
+    const nodes = listPrefabShadowNodes(safeModel);
+    const nodeId = resolveSafePrefabNodeAuthoredId(safeModel, normalizePrefabNodeId(input.nodeId));
     const node = nodes.find(candidate => candidate.id === nodeId) ?? null;
     if (!node)
         return null;
+    const rootNodeId = safeModel.nodes.find(candidate => candidate.role === 'root')?.nodeId
+        ?? safeModel.nodes.find(candidate => candidate.parentNodeId === null)?.nodeId
+        ?? node.id;
     const document = createPrefabStageShadowDocument(details, nodes);
     return {
         kind: 'prefab-stage',
         target: { assetId: details.stage.assetId, nodeId: node.id },
         details,
         nodeId: node.id,
+        rootNodeId,
         node,
         document,
     };
 }
+function resolveSafePrefabNodeAuthoredId(safeModel, requestedNodeId) {
+    if (requestedNodeId) {
+        return safeModel.nodes.find(node => (node.nodeId === requestedNodeId || node.rowId === requestedNodeId))?.nodeId ?? null;
+    }
+    if (safeModel.activeNodeId)
+        return safeModel.activeNodeId;
+    return safeModel.nodes.find(node => node.role === 'root')?.nodeId
+        ?? safeModel.nodes.find(node => node.parentNodeId === null)?.nodeId
+        ?? null;
+}
+function hasActivePrefabHierarchyScope(operations, details, model = operations.getHierarchyReadModel()) {
+    return model.snapshot.scopeType === 'prefab-stage'
+        && model.snapshot.scopeKey === `prefab-stage:${details.stage.assetId}`;
+}
 function createPrefabStageShadowDocument(details, nodes) {
     return {
         version: 1,
@@ -1130,29 +1810,16 @@ function createPrefabStageShadowDocument(details, nodes) {
         },
     };
 }
-function listPrefabShadowNodes(details) {
-    const nodes = [];
-    const visit = (item, parentId) => {
-        const nodeId = normalizePrefabNodeId(item?.nodeId ?? item?.id);
-        const isNode = item?.itemType === 'prefab-node' || !!item?.nodeId || String(item?.id ?? '').startsWith(PREFAB_STAGE_ITEM_PREFIX);
-        const currentParent = isNode && nodeId ? nodeId : parentId;
-        if (isNode && nodeId) {
-            nodes.push({
-                id: nodeId,
-                label: typeof item.label === 'string' ? item.label : nodeId,
-                kind: typeof item.kind === 'string' ? item.kind : 'group',
-                parentId,
-                ...(isRecord(item.defaults) ? { defaults: structuredClone(item.defaults) } : {}),
-                ...(isRecord(item.primitive) ? { primitive: structuredClone(item.primitive) } : {}),
-                ...(isRecord(item.light) ? { light: structuredClone(item.light) } : {}),
-            });
-        }
-        for (const child of Array.isArray(item?.children) ? item.children : [])
-            visit(child, currentParent);
-    };
-    for (const item of details.structureItems)
-        visit(item, null);
-    return nodes;
+function listPrefabShadowNodes(safeModel) {
+    return safeModel.nodes.map(node => ({
+        id: node.nodeId,
+        label: node.label,
+        kind: node.details?.kind ?? node.role ?? 'group',
+        parentId: node.parentNodeId,
+        ...(isRecord(node.details?.defaults) ? { defaults: structuredClone(node.details.defaults) } : {}),
+        ...(isRecord(node.details?.primitive) ? { primitive: structuredClone(node.details.primitive) } : {}),
+        ...(isRecord(node.details?.light) ? { light: structuredClone(node.details.light) } : {}),
+    }));
 }
 function createShadowPolicyFieldPatches(policy) {
     const record = (policy ?? {});
@@ -1278,7 +1945,8 @@ function createShadowDebugRuntimeEvidence(plan, receivers, shadowPreviewDebugInf
             message: 'Resolved backend is none, so no runtime shadow primitive is expected.',
         });
     }
-    if (plan.backend !== 'none' && receivers.length === 0) {
+    const experimentReceiverMeshCount = shadowPreviewDebugInfo?.shadowMapExperiment?.receiverMeshCount ?? 0;
+    if (plan.backend !== 'none' && receivers.length === 0 && experimentReceiverMeshCount === 0) {
         diagnostics.push({
             severity: 'warning',
             source: 'editor',
@@ -1300,7 +1968,89 @@ function createShadowDebugRuntimeEvidence(plan, receivers, shadowPreviewDebugInf
             ? 0
             : receivers.filter(receiver => receiver.active !== false && receiver.visible !== false).length,
         casterRuntimeObjectCount: plan.backend === 'none' ? 0 : 1,
-        receiverRuntimeObjectCount: receivers.length,
+        receiverRuntimeObjectCount: Math.max(receivers.length, experimentReceiverMeshCount),
+        ...(shadowPreviewDebugInfo?.shadowMapExperiment
+            ? {
+                shadowMapExperiment: {
+                    ...shadowPreviewDebugInfo.shadowMapExperiment,
+                    mapResolutions: shadowPreviewDebugInfo.shadowMapExperiment.mapResolutions
+                        ? { ...shadowPreviewDebugInfo.shadowMapExperiment.mapResolutions }
+                        : null,
+                    configuredMapResolutions: shadowPreviewDebugInfo.shadowMapExperiment.configuredMapResolutions
+                        ? { ...shadowPreviewDebugInfo.shadowMapExperiment.configuredMapResolutions }
+                        : null,
+                    diagnosticThresholds: shadowPreviewDebugInfo.shadowMapExperiment.diagnosticThresholds
+                        ? { ...shadowPreviewDebugInfo.shadowMapExperiment.diagnosticThresholds }
+                        : null,
+                    activity: {
+                        ...shadowPreviewDebugInfo.shadowMapExperiment.activity,
+                        activeActivityKindCounts: { ...shadowPreviewDebugInfo.shadowMapExperiment.activity.activeActivityKindCounts },
+                        pendingDirtyReasons: [...shadowPreviewDebugInfo.shadowMapExperiment.activity.pendingDirtyReasons],
+                        untrackedDynamicCasterEntityIds: [...shadowPreviewDebugInfo.shadowMapExperiment.activity.untrackedDynamicCasterEntityIds],
+                        sources: shadowPreviewDebugInfo.shadowMapExperiment.activity.sources.map(entry => structuredClone(entry)),
+                    },
+                    runtime: {
+                        ...shadowPreviewDebugInfo.shadowMapExperiment.runtime,
+                        registrations: shadowPreviewDebugInfo.shadowMapExperiment.runtime.registrations.map(entry => ({
+                            ...entry,
+                            renderableIds: [...entry.renderableIds],
+                            activitySourceIds: [...entry.activitySourceIds],
+                        })),
+                    },
+                    lastRefreshReasons: [...shadowPreviewDebugInfo.shadowMapExperiment.lastRefreshReasons],
+                    depth: shadowPreviewDebugInfo.shadowMapExperiment.depth
+                        ? {
+                            ...shadowPreviewDebugInfo.shadowMapExperiment.depth,
+                            gpuCapability: { ...shadowPreviewDebugInfo.shadowMapExperiment.depth.gpuCapability },
+                            static: {
+                                ...shadowPreviewDebugInfo.shadowMapExperiment.depth.static,
+                                lastRefreshReasons: [...shadowPreviewDebugInfo.shadowMapExperiment.depth.static.lastRefreshReasons],
+                            },
+                            dynamic: {
+                                ...shadowPreviewDebugInfo.shadowMapExperiment.depth.dynamic,
+                                lastRefreshReasons: [...shadowPreviewDebugInfo.shadowMapExperiment.depth.dynamic.lastRefreshReasons],
+                            },
+                        }
+                        : null,
+                    culling: {
+                        ...shadowPreviewDebugInfo.shadowMapExperiment.culling,
+                        authoredCenter: shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredCenter
+                            ? [...shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredCenter]
+                            : shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredCenter,
+                        effectiveCenter: shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveCenter
+                            ? [...shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveCenter]
+                            : shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveCenter,
+                        authoredExtent: shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredExtent
+                            ? [...shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredExtent]
+                            : shadowPreviewDebugInfo.shadowMapExperiment.culling.authoredExtent,
+                        effectiveExtent: shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveExtent
+                            ? [...shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveExtent]
+                            : shadowPreviewDebugInfo.shadowMapExperiment.culling.effectiveExtent,
+                        anchor: shadowPreviewDebugInfo.shadowMapExperiment.culling.anchor
+                            ? [...shadowPreviewDebugInfo.shadowMapExperiment.culling.anchor]
+                            : shadowPreviewDebugInfo.shadowMapExperiment.culling.anchor,
+                        coverage: shadowPreviewDebugInfo.shadowMapExperiment.culling.coverage
+                            ? {
+                                min: [...shadowPreviewDebugInfo.shadowMapExperiment.culling.coverage.min],
+                                max: [...shadowPreviewDebugInfo.shadowMapExperiment.culling.coverage.max],
+                            }
+                            : null,
+                    },
+                    worldUnitsPerTexel: shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexel
+                        ? [...shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexel]
+                        : null,
+                    worldUnitsPerTexelByMap: shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexelByMap
+                        ? {
+                            static: [...shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexelByMap.static],
+                            dynamic: [...shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexelByMap.dynamic],
+                            composite: [...shadowPreviewDebugInfo.shadowMapExperiment.worldUnitsPerTexelByMap.composite],
+                        }
+                        : null,
+                    registry: structuredClone(shadowPreviewDebugInfo.shadowMapExperiment.registry),
+                    diagnostics: shadowPreviewDebugInfo.shadowMapExperiment.diagnostics.map(entry => ({ ...entry })),
+                },
+            }
+            : {}),
         ...createPlanarShadowRuntimeEvidence(shadowPreviewDebugInfo, casterIds),
         ...(plan.stale === true ? { artifactStale: true } : {}),
         ...(diagnostics.length ? { diagnostics } : {}),
@@ -1426,7 +2176,13 @@ function uniqueStrings(values) {
 function uniqueNumbers(values) {
     return [...new Set(values.filter(value => Number.isFinite(value)))];
 }
-function mapShadowPlan(plan) {
+function mapShadowPlan(plan, runtimeReceiverMeshCount = 0) {
+    const diagnostics = mapShadowDiagnostics(plan.diagnostics);
+    if (plan.backend !== 'none' && plan.receiverIds.length === 0 && runtimeReceiverMeshCount > 0) {
+        const retainedDiagnostics = diagnostics.filter(diagnostic => diagnostic.code !== 'shadow.receiverNotFound');
+        retainedDiagnostics.push(createRuntimeReceiversBoundDiagnostic(runtimeReceiverMeshCount));
+        diagnostics.splice(0, diagnostics.length, ...retainedDiagnostics);
+    }
     return {
         casterId: plan.casterId,
         receiverIds: [...plan.receiverIds],
@@ -1436,7 +2192,7 @@ function mapShadowPlan(plan) {
         quality: plan.quality,
         params: { ...plan.params },
         ...(plan.stale === true ? { stale: true } : {}),
-        diagnostics: mapShadowDiagnostics(plan.diagnostics),
+        diagnostics,
     };
 }
 function mapShadowReceivers(receivers, state, context = {}) {
@@ -1599,8 +2355,15 @@ function cloneShadowVec3(value) {
 function cloneShadowVec3Json(value) {
     return { x: value.x, y: value.y, z: value.z };
 }
-function createShadowFootprintSummary(plan, receivers, state, projectionContext = createIdentityShadowProjectionContext(), light) {
+function createShadowFootprintSummary(plan, receivers, state, projectionContext = createIdentityShadowProjectionContext(), light, runtimeReceiverMeshCount = 0) {
     if (plan.backend === 'none' || plan.receiverIds.length === 0) {
+        if (plan.backend !== 'none' && runtimeReceiverMeshCount > 0) {
+            return {
+                kind: 'unknown',
+                confidence: 0.7,
+                diagnostics: [createRuntimeReceiversBoundDiagnostic(runtimeReceiverMeshCount)],
+            };
+        }
         return {
             kind: 'none',
             confidence: plan.backend === 'none' ? 1 : 0,
@@ -1705,6 +2468,15 @@ function createShadowFootprintSummary(plan, receivers, state, projectionContext
         ...(diagnostics.length ? { diagnostics } : {}),
     };
 }
+function createRuntimeReceiversBoundDiagnostic(runtimeReceiverMeshCount) {
+    return {
+        severity: 'info',
+        source: 'runtime',
+        code: 'shadow.runtimeReceiversBound',
+        message: `${runtimeReceiverMeshCount} receiver meshes are bound by the Shadow Map runtime; no authored receiver id is required.`,
+        details: { runtimeReceiverMeshCount },
+    };
+}
 function selectShadowFootprintReceiver(plan, receivers) {
     const planOrder = new Map(plan.receiverIds.map((receiverId, index) => [receiverId, index]));
     const candidates = receivers.filter(receiver => planOrder.has(receiver.receiverId));
@@ -1885,18 +2657,9 @@ function asEditorSceneDocument(value) {
 function findShadowGameObject(document, objectId) {
     return document.scene.gameObjects.find(gameObject => gameObject.id === objectId) ?? null;
 }
-function findPrefabRootNodeId(details) {
-    const nodes = listPrefabShadowNodes(details);
-    return nodes.find(node => node.kind === 'root')?.id
-        ?? nodes.find(node => !node.parentId)?.id
-        ?? 'prefab-root';
-}
 function normalizePrefabNodeId(value) {
     const id = normalizeAgentBridgeString(value);
-    return id.startsWith(PREFAB_STAGE_ITEM_PREFIX) ? id.slice(PREFAB_STAGE_ITEM_PREFIX.length) : id;
-}
-function getSelectedPrefabNodeId(itemId) {
-    return normalizePrefabNodeId(itemId);
+    return id.startsWith('prefab-node:') ? id.slice('prefab-node:'.length) : id;
 }
 function readBoolean(value, fallback) {
     return typeof value === 'boolean' ? value : fallback;