@fps-games/editor 0.1.6-beta.1 → 0.1.7-beta.2

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

@@ -0,0 +1,1876 @@
+import { collectEditorShadowReceiverCandidates, detectEditorSceneDirectionalLightOrientationDrift, findEditorSceneTransform, mergeEditorShadowSettings, normalizeEditorSceneLightDirectionVector, readEditorShadowSettings, readEditorShadowSettingsWithLegacy, resolveEditorSceneGameObjectShadowSettings, resolveEditorShadowParams, resolveEditorShadowPlan, } from '@fps-games/editor-playable-sdk';
+import { EDITOR_AGENT_BRIDGE_CAPABILITY_ID, } from '@fps-games/editor-protocol';
+import { createLocalEditorAgentBridgeFailure, editorTransformSnapshotToAgentTransform, } from '../diagnostics.js';
+import { normalizeAgentBridgeIdList, normalizeAgentBridgeString, } from '../shared.js';
+const PREFAB_STAGE_ITEM_PREFIX = 'prefab-node:';
+const SHADOW_POLICY_FIELDS = [
+    'shadow.cast',
+    'shadow.receive',
+    'shadow.mode',
+    'shadow.quality',
+    'shadow.light.mode',
+    'shadow.light.lightId',
+    'shadow.params.opacity',
+    'shadow.params.softness',
+    'shadow.params.bias',
+    'shadow.params.normalBias',
+    'shadow.params.maxDistance',
+    'shadow.params.resolution',
+    'shadow.params.cascadeCount',
+    'shadow.params.bakeSamples',
+    'shadow.params.blurKernel',
+];
+export function createLocalEditorAgentBridgeShadowSource(state, options, renderUi, operations) {
+    return {
+        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);
+        },
+        setPolicy(input) {
+            const policy = normalizeShadowPolicy(input.policy);
+            if (!policy.ok) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_SET, policy.message, { code: 'shadow.invalidInput', details: { hasPolicy: input.policy != null } });
+            }
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_SET, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            if (resolved.target.kind === 'scene') {
+                return setSceneShadowPolicy(state, options, renderUi, operations, resolved.target, policy.settings);
+            }
+            return setPrefabStageShadowPolicy(renderUi, operations, resolved.target, policy.settings);
+        },
+        listReceivers(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_RECEIVERS_LIST, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const casterId = getResolvedTargetCasterId(resolved.target);
+            const projectionContext = createShadowProjectionContext(resolved.target, operations);
+            return {
+                receivers: mapShadowReceivers(collectEditorShadowReceiverCandidates({
+                    document: resolved.target.document,
+                    casterId,
+                }), state, { casterId, projectionContext }).filter(receiver => input.includeAuto === true || receiver.source !== 'auto'),
+                diagnostics: createShadowTargetDiagnostics(resolved.target),
+            };
+        },
+        resolvePreview(input) {
+            const policy = input.policy === undefined ? { ok: true, settings: undefined } : normalizeShadowPolicy(input.policy);
+            if (!policy.ok) {
+                return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_RESOLVE_PREVIEW, policy.message, { code: 'shadow.invalidInput', details: { hasPolicy: input.policy != null } });
+            }
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_RESOLVE_PREVIEW, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const receiverIds = normalizeAgentBridgeIdList(input.receiverIds ?? []);
+            const casterId = getResolvedTargetCasterId(resolved.target);
+            const planInput = {
+                document: resolved.target.document,
+                casterId,
+                explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+                strictExplicitReceivers: receiverIds.length > 0,
+                ...(policy.settings !== undefined ? { settings: { instance: policy.settings } } : {}),
+            };
+            const plan = mapShadowPlan(resolveEditorShadowPlan(planInput));
+            const allReceivers = mapShadowReceivers(collectEditorShadowReceiverCandidates({
+                document: resolved.target.document,
+                casterId,
+                explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+            }), state, {
+                casterId,
+                lightId: plan.lightId,
+                projectionContext: createShadowProjectionContext(resolved.target, operations),
+            });
+            const receiverIdSet = new Set(plan.receiverIds);
+            const receivers = receiverIds.length > 0
+                ? allReceivers.filter(receiver => receiverIdSet.has(receiver.receiverId))
+                : allReceivers;
+            const light = createShadowLightSummary(resolved.target.document, plan.lightId);
+            return {
+                target: resolved.target.target,
+                plan,
+                caster: createShadowDebugTargetSummary(resolved.target, state, createShadowProjectionContext(resolved.target, operations)),
+                ...(light ? { light } : {}),
+                footprint: createShadowFootprintSummary(plan, receivers, state, createShadowProjectionContext(resolved.target, operations), light),
+                receivers,
+                diagnostics: createShadowTargetDiagnostics(resolved.target),
+            };
+        },
+        inspectDebug(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_DEBUG_INSPECT, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            return createShadowDebugInspectOutput(resolved.target, state, {
+                projectionContext: createShadowProjectionContext(resolved.target, operations),
+            }, {
+                shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+            });
+        },
+        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);
+        },
+        clearDebugContext() {
+            return clearShadowDebugContext(state, renderUi, operations);
+        },
+        setDebugOverlay(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_DEBUG_OVERLAY_SET, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const inspect = createShadowDebugInspectOutput(resolved.target, state, {
+                receiverIds: input.receiverIds ?? [],
+                projectionContext: createShadowProjectionContext(resolved.target, operations),
+            });
+            const overlayItems = createShadowDebugOverlayItems(inspect, input);
+            const overlayIds = operations.setShadowDebugOverlay?.(overlayItems)
+                ?? state.projection?.setShadowDebugOverlay?.(overlayItems)
+                ?? overlayItems.map(item => item.id);
+            operations.requestSceneFrame('agent-shadow-debug-overlay-set');
+            renderUi();
+            const diagnostics = [
+                ...(inspect.diagnostics ?? []),
+                ...(!overlayItems.length ? [{
+                        severity: 'warning',
+                        source: 'editor',
+                        code: 'shadow.debugOverlayEmpty',
+                        message: 'No shadow debug overlay items could be created for the resolved target.',
+                    }] : []),
+            ];
+            return {
+                enabled: overlayItems.length > 0,
+                target: inspect.target,
+                overlayIds,
+                ...(diagnostics.length ? { diagnostics } : {}),
+            };
+        },
+        clearDebugOverlay() {
+            const cleared = operations.clearShadowDebugOverlay?.()
+                ?? state.projection?.clearShadowDebugOverlay?.()
+                ?? false;
+            operations.requestSceneFrame('agent-shadow-debug-overlay-clear');
+            renderUi();
+            return {
+                cleared,
+            };
+        },
+        measureVisibility(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_DEBUG_VISIBILITY_MEASURE, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const inspect = createShadowDebugInspectOutput(resolved.target, state, {
+                receiverIds: input.receiverIds ?? [],
+                projectionContext: createShadowProjectionContext(resolved.target, operations),
+            });
+            return createShadowDebugVisibilityMeasureOutput(inspect, input);
+        },
+        async bakeStatic(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_STATIC_BAKE, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const receiverIds = normalizeAgentBridgeIdList(input.receiverIds ?? []);
+            const casterId = getResolvedTargetCasterId(resolved.target);
+            const quality = input.quality && input.quality !== 'inherit' ? input.quality : undefined;
+            const effectivePolicy = getResolvedTargetShadowPolicy(resolved.target);
+            const bakePolicy = mergeEditorShadowSettings(effectivePolicy, {
+                mode: 'static',
+                ...(quality ? { quality } : {}),
+            });
+            const planInput = {
+                document: resolved.target.document,
+                casterId,
+                explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+                strictExplicitReceivers: receiverIds.length > 0,
+                settings: { instance: bakePolicy },
+            };
+            const plan = mapShadowPlan(resolveEditorShadowPlan(planInput));
+            const targetDiagnostics = createShadowTargetDiagnostics(resolved.target);
+            if (resolved.target.kind !== 'scene') {
+                return {
+                    target: resolved.target.target,
+                    baked: false,
+                    plan,
+                    stale: true,
+                    diagnostics: [
+                        ...targetDiagnostics,
+                        {
+                            severity: 'warning',
+                            source: 'editor',
+                            code: 'shadow.staticBakeSceneOnly',
+                            message: 'Static shadow baking runs against the main scene. Prefab stage policies are baked after prefab instances are placed in a scene.',
+                        },
+                    ],
+                };
+            }
+            if (!operations.runRenderingAction) {
+                return {
+                    target: resolved.target.target,
+                    baked: false,
+                    plan,
+                    stale: true,
+                    diagnostics: [
+                        ...targetDiagnostics,
+                        {
+                            severity: 'warning',
+                            source: 'editor',
+                            code: 'shadow.staticBakeUnavailable',
+                            message: 'Static shadow bake is unavailable because this editor session does not expose the rendering action pipeline.',
+                        },
+                    ],
+                };
+            }
+            const actionResult = await operations.runRenderingAction('bake-static-shadows');
+            const bakedSourceNodeIds = readRenderingActionStaticBakeSourceNodeIds(actionResult);
+            const targetConfirmed = bakedSourceNodeIds?.includes(casterId) === true;
+            const baked = actionResult.ok === true && actionResult.changed === true && targetConfirmed;
+            const bakeDiagnostic = createStaticBakeDiagnostic(actionResult, targetConfirmed, bakedSourceNodeIds);
+            return {
+                target: resolved.target.target,
+                baked,
+                plan,
+                stale: !baked,
+                diagnostics: [
+                    ...targetDiagnostics,
+                    bakeDiagnostic,
+                ],
+            };
+        },
+        invalidateStatic(input) {
+            const resolved = resolveShadowTarget(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_STATIC_INVALIDATE, state, input, operations);
+            if (!resolved.ok)
+                return resolved.result;
+            const targetDiagnostics = createShadowTargetDiagnostics(resolved.target);
+            if (resolved.target.kind !== 'scene') {
+                return {
+                    target: resolved.target.target,
+                    invalidated: false,
+                    stale: true,
+                    diagnostics: [
+                        ...targetDiagnostics,
+                        {
+                            severity: 'warning',
+                            source: 'editor',
+                            code: 'shadow.staticInvalidateSceneOnly',
+                            message: 'Static shadow invalidation runs against scene instances. Prefab stage policies are invalidated after placement in a scene.',
+                        },
+                    ],
+                };
+            }
+            const plan = mapShadowPlan(resolveEditorShadowPlan({
+                document: resolved.target.document,
+                casterId: resolved.target.objectId,
+            }));
+            if (plan.backend !== 'static-baked') {
+                return {
+                    target: resolved.target.target,
+                    invalidated: false,
+                    stale: false,
+                    diagnostics: [
+                        ...targetDiagnostics,
+                        {
+                            severity: 'warning',
+                            source: 'editor',
+                            code: 'shadow.staticInvalidateNonStaticTarget',
+                            message: 'Static shadow invalidation only applies to targets resolved to the static-baked backend.',
+                            details: { backend: plan.backend, mode: plan.mode },
+                        },
+                    ],
+                };
+            }
+            if (!operations.invalidateStaticShadowArtifact) {
+                return {
+                    target: resolved.target.target,
+                    invalidated: false,
+                    stale: true,
+                    diagnostics: [
+                        ...targetDiagnostics,
+                        {
+                            severity: 'warning',
+                            source: 'editor',
+                            code: 'shadow.staticInvalidateUnavailable',
+                            message: 'Static shadow invalidation is unavailable because this editor session does not expose the shadow preview artifact lifecycle.',
+                        },
+                    ],
+                };
+            }
+            const invalidated = operations.invalidateStaticShadowArtifact();
+            return {
+                target: resolved.target.target,
+                invalidated,
+                stale: true,
+                diagnostics: [
+                    ...targetDiagnostics,
+                    {
+                        severity: invalidated ? 'info' : 'warning',
+                        source: 'editor',
+                        code: invalidated ? 'shadow.staticInvalidated' : 'shadow.staticInvalidateNoArtifact',
+                        message: invalidated
+                            ? 'Static shadow preview artifact was invalidated; run shadow.static.bake to refresh scene artifacts.'
+                            : 'Static shadow target is static, but no active preview artifact was available to invalidate.',
+                        details: { backend: plan.backend, mode: plan.mode },
+                    },
+                ],
+            };
+        },
+    };
+}
+function createShadowPolicyGetOutput(resolved) {
+    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({
+                document: resolved.document,
+                casterId: resolved.objectId,
+            })),
+            diagnostics: [
+                ...mapShadowDiagnostics(effective.diagnostics),
+                ...createShadowTargetDiagnostics(resolved),
+            ],
+        };
+    }
+    const policy = readPrefabNodeShadowPolicy(resolved.node);
+    return {
+        target: resolved.target,
+        ...(policy ? { policy: structuredClone(policy) } : {}),
+        effectivePolicy: (policy ? structuredClone(policy) : {}),
+        plan: mapShadowPlan(resolveEditorShadowPlan({
+            document: resolved.document,
+            casterId: resolved.nodeId,
+        })),
+        diagnostics: createShadowTargetDiagnostics(resolved),
+    };
+}
+function createShadowDebugInspectOutput(resolved, state, options = {}, extraOptions) {
+    const casterId = getResolvedTargetCasterId(resolved);
+    const projectionContext = options.projectionContext ?? createIdentityShadowProjectionContext();
+    const effectivePolicy = getResolvedTargetShadowPolicy(resolved);
+    const receiverIds = normalizeAgentBridgeIdList(options.receiverIds ?? []);
+    const planInput = {
+        document: resolved.document,
+        casterId,
+        explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+        strictExplicitReceivers: receiverIds.length > 0,
+    };
+    const plan = mapShadowPlan(resolveEditorShadowPlan(planInput));
+    const allReceivers = mapShadowReceivers(collectEditorShadowReceiverCandidates({
+        document: resolved.document,
+        casterId,
+        explicitReceiverIds: receiverIds.length > 0 ? receiverIds : undefined,
+    }), state, { casterId, lightId: plan.lightId, projectionContext });
+    const resolvedReceiverIds = new Set(plan.receiverIds);
+    const receivers = receiverIds.length > 0
+        ? allReceivers.filter(receiver => resolvedReceiverIds.has(receiver.receiverId))
+        : allReceivers;
+    const authoredPolicy = getResolvedTargetAuthoredPolicy(resolved);
+    const light = createShadowLightSummary(resolved.document, plan.lightId);
+    const runtimeEvidence = createShadowDebugRuntimeEvidence(plan, receivers, extraOptions?.shadowPreviewDebugInfo, createShadowRuntimeEvidenceCasterIds(resolved, casterId, projectionContext));
+    const diagnostics = [
+        ...createShadowTargetDiagnostics(resolved),
+        ...plan.diagnostics,
+        ...(runtimeEvidence.diagnostics ?? []),
+    ];
+    return {
+        target: resolved.target,
+        caster: createShadowDebugTargetSummary(resolved, state, projectionContext),
+        ...(authoredPolicy ? { policy: structuredClone(authoredPolicy) } : {}),
+        effectivePolicy: (effectivePolicy ? structuredClone(effectivePolicy) : {}),
+        plan,
+        ...(light ? { light } : {}),
+        receivers,
+        footprint: createShadowFootprintSummary(plan, receivers, state, projectionContext, light),
+        runtimeEvidence,
+        ...(diagnostics.length ? { diagnostics } : {}),
+    };
+}
+function enterShadowDebugContext(state, renderUi, operations, resolved, input) {
+    const projectionContext = createShadowProjectionContext(resolved, operations);
+    const receiverIds = normalizeAgentBridgeIdList(input.receiverIds ?? []);
+    const initialInspect = createShadowDebugInspectOutput(resolved, state, {
+        receiverIds,
+        projectionContext,
+    }, {
+        shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+    });
+    const targetId = getResolvedTargetCasterId(resolved);
+    const logicalKeepIds = new Set([targetId]);
+    const protectedReceiverIds = initialInspect.plan.receiverIds.length > 0
+        ? initialInspect.plan.receiverIds
+        : initialInspect.receivers.map(receiver => receiver.receiverId);
+    for (const receiverId of protectedReceiverIds)
+        logicalKeepIds.add(receiverId);
+    if (initialInspect.light?.lightId)
+        logicalKeepIds.add(initialInspect.light.lightId);
+    const ambientLightIds = input.includeAmbientLights === false
+        ? []
+        : collectShadowDebugAmbientLightIds(resolved.document, initialInspect.light?.lightId);
+    for (const ambientId of ambientLightIds)
+        logicalKeepIds.add(ambientId);
+    const projectionKeepIds = new Set();
+    for (const id of logicalKeepIds) {
+        const projectionId = projectionContext.resolveProjectionId(id);
+        projectionKeepIds.add(projectionId);
+        for (const parentId of state.projection?.getProjectionParentIds?.(projectionId) ?? []) {
+            projectionKeepIds.add(parentId);
+        }
+    }
+    const objectIds = state.projection?.getProjectedNodeIds?.() ?? [...projectionKeepIds];
+    if (objectIds.length === 0) {
+        return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_DEBUG_CONTEXT_ENTER, 'Viewport projection is unavailable or has no projected objects for Shadow Debug Context.', { code: 'viewport.projectionUnavailable' });
+    }
+    const nextOverrides = {};
+    for (const objectId of objectIds)
+        nextOverrides[objectId] = projectionKeepIds.has(objectId);
+    const previous = JSON.stringify(state.previewVisibility);
+    state.previewVisibility.overrides = nextOverrides;
+    state.previewVisibility.isolatedObjectIds = [...projectionKeepIds];
+    state.previewVisibility.protectedReceiverIds = [...new Set(protectedReceiverIds.flatMap(id => [
+            id,
+            projectionContext.resolveProjectionId(id),
+        ]))];
+    state.previewVisibility.protectedObjectIds = [...new Set([...state.previewVisibility.protectedReceiverIds, ...ambientLightIds.flatMap(id => [
+                id,
+                projectionContext.resolveProjectionId(id),
+            ])])];
+    state.previewVisibility.reason = normalizeAgentBridgeString(input.reason)
+        || `Shadow Debug Context for ${targetId}`;
+    state.projection?.clearPreviewVisibilityOverrides?.();
+    const entries = state.projection?.setPreviewVisibilityOverrides?.(nextOverrides) ?? [];
+    const inspect = createShadowDebugInspectOutput(resolved, state, {
+        receiverIds,
+        projectionContext,
+    }, {
+        shadowPreviewDebugInfo: operations.getShadowPreviewDebugInfo?.() ?? null,
+    });
+    const overlayItems = input.showOverlay === false
+        ? []
+        : createShadowDebugOverlayItems(inspect, {
+            ...input,
+            showCasterBounds: true,
+            showReceiverBounds: true,
+            showLightDirection: true,
+            showFootprint: true,
+            showArtifactBounds: true,
+        });
+    const overlayIds = overlayItems.length > 0
+        ? operations.setShadowDebugOverlay?.(overlayItems)
+            ?? state.projection?.setShadowDebugOverlay?.(overlayItems)
+            ?? overlayItems.map(item => item.id)
+        : [];
+    const visibilityMeasure = createShadowDebugVisibilityMeasureOutput(inspect, input);
+    const hiddenObjectIds = objectIds.filter(objectId => !projectionKeepIds.has(objectId));
+    const diagnostics = [
+        ...(inspect.diagnostics ?? []),
+        ...(!protectedReceiverIds.length ? [{
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.debugContextNoReceiver',
+                message: 'Shadow Debug Context could not resolve a receiver to protect; screenshots may still be ambiguous.',
+                details: { targetId },
+            }] : []),
+        ...(!initialInspect.light?.lightId && initialInspect.plan.backend !== 'none' ? [{
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.debugContextNoLight',
+                message: 'Shadow Debug Context could not resolve a shadow light to preserve.',
+                details: { backend: initialInspect.plan.backend, targetId },
+            }] : []),
+        ...(!ambientLightIds.length && input.includeAmbientLights !== false ? [{
+                severity: 'info',
+                source: 'editor',
+                code: 'shadow.debugContextNoAmbientLight',
+                message: 'No ambient/environment light was found to preserve for visual debugging.',
+            }] : []),
+    ];
+    operations.requestSceneFrame('agent-shadow-debug-context-enter');
+    renderUi();
+    return {
+        entered: previous !== JSON.stringify(state.previewVisibility) || overlayIds.length > 0,
+        target: inspect.target,
+        keptObjectIds: [...logicalKeepIds],
+        hiddenObjectIds,
+        protectedReceiverIds,
+        lightIds: initialInspect.light?.lightId ? [initialInspect.light.lightId] : [],
+        ambientLightIds,
+        overlayIds,
+        snapshot: createShadowDebugContextVisibilitySnapshot(state, entries, diagnostics),
+        inspect,
+        visibilityMeasure,
+        ...(diagnostics.length ? { diagnostics } : {}),
+    };
+}
+function clearShadowDebugContext(state, renderUi, operations) {
+    const previousCount = Object.keys(state.previewVisibility.overrides).length;
+    const hadIsolation = state.previewVisibility.isolatedObjectIds.length > 0;
+    const hadProtection = (state.previewVisibility.protectedObjectIds?.length ?? 0) > 0
+        || (state.previewVisibility.protectedReceiverIds?.length ?? 0) > 0;
+    state.previewVisibility.overrides = {};
+    state.previewVisibility.isolatedObjectIds = [];
+    delete state.previewVisibility.protectedObjectIds;
+    delete state.previewVisibility.protectedReceiverIds;
+    delete state.previewVisibility.reason;
+    state.projection?.clearPreviewVisibilityOverrides?.();
+    const overlayCleared = operations.clearShadowDebugOverlay?.()
+        ?? state.projection?.clearShadowDebugOverlay?.()
+        ?? false;
+    const visibilityCleared = previousCount > 0 || hadIsolation || hadProtection;
+    operations.requestSceneFrame('agent-shadow-debug-context-clear');
+    renderUi();
+    return {
+        cleared: visibilityCleared || overlayCleared,
+        overlayCleared,
+        visibilityCleared,
+    };
+}
+function createShadowDebugContextVisibilitySnapshot(state, entries, diagnostics) {
+    const entryById = new Map(entries.map(entry => [entry.nodeId, entry]));
+    const objectIds = new Set([
+        ...Object.keys(state.previewVisibility.overrides),
+        ...entries.map(entry => entry.nodeId),
+        ...state.previewVisibility.isolatedObjectIds,
+    ]);
+    const isolatedIds = new Set(state.previewVisibility.isolatedObjectIds);
+    return {
+        isolated: isolatedIds.size > 0,
+        isolatedObjectIds: [...isolatedIds],
+        entries: [...objectIds].sort().map((objectId) => {
+            const entry = entryById.get(objectId);
+            const overrideVisible = state.previewVisibility.overrides[objectId];
+            const authoredVisible = entry?.authoredActive ?? true;
+            return {
+                objectId,
+                authoredVisible,
+                previewVisible: entry?.effectiveVisible ?? (authoredVisible && overrideVisible !== false),
+                ...(typeof overrideVisible === 'boolean' ? { overrideVisible } : {}),
+                isolated: isolatedIds.has(objectId),
+                ...(state.previewVisibility.protectedReceiverIds?.includes(objectId) ? {
+                    diagnostics: [{
+                            severity: 'info',
+                            source: 'editor',
+                            code: 'shadow.receiverProtectedInDebugContext',
+                            message: 'This receiver is protected by the active Shadow Debug Context and should remain visible for screenshot validation.',
+                            details: { objectId },
+                        }],
+                } : {}),
+            };
+        }),
+        ...(state.previewVisibility.reason ? { reason: state.previewVisibility.reason } : {}),
+        ...(diagnostics.length ? { diagnostics: [...diagnostics] } : {}),
+    };
+}
+function collectShadowDebugAmbientLightIds(document, shadowLightId) {
+    const ids = [];
+    const seen = new Set();
+    const gameObjects = Array.isArray(document.scene?.gameObjects) ? document.scene.gameObjects : [];
+    for (const gameObject of gameObjects) {
+        if (!isRecord(gameObject))
+            continue;
+        const id = typeof gameObject.id === 'string' ? gameObject.id : '';
+        if (!id || id === shadowLightId || seen.has(id))
+            continue;
+        const name = typeof gameObject.name === 'string' ? gameObject.name : '';
+        const light = isRecord(gameObject.light) ? gameObject.light : null;
+        const lightType = typeof light?.type === 'string' ? light.type.toLowerCase() : '';
+        const haystack = `${id} ${name}`.toLowerCase();
+        const isAmbient = lightType === 'hemispheric'
+            || lightType === 'ambient'
+            || lightType === 'environment'
+            || haystack.includes('environment_light')
+            || haystack.includes('environment light')
+            || haystack.includes('ambient');
+        if (!isAmbient)
+            continue;
+        seen.add(id);
+        ids.push(id);
+    }
+    return ids;
+}
+function createShadowDebugOverlayItems(inspect, input) {
+    const items = [];
+    const flags = readShadowDebugOverlayFlags(input);
+    const receiverIds = new Set(normalizeAgentBridgeIdList(input.receiverIds ?? []));
+    const targetId = inspect.caster?.objectId ?? inspect.caster?.nodeId ?? 'target';
+    const casterBounds = createOverlayBounds(inspect.caster?.bounds);
+    if (flags.showCasterBounds && casterBounds) {
+        items.push({
+            id: `shadow-debug:caster:${targetId}`,
+            kind: 'caster-bounds',
+            bounds: casterBounds,
+        });
+    }
+    const receivers = receiverIds.size
+        ? inspect.receivers.filter(receiver => receiverIds.has(receiver.receiverId))
+        : inspect.receivers;
+    if (flags.showReceiverBounds) {
+        for (const receiver of receivers) {
+            const bounds = createOverlayBounds(receiver.bounds);
+            if (!bounds)
+                continue;
+            items.push({
+                id: `shadow-debug:receiver:${receiver.receiverId}`,
+                kind: 'receiver-bounds',
+                bounds,
+            });
+            items.push({
+                id: `shadow-debug:receiver-surface:${receiver.receiverId}`,
+                kind: 'receiver-surface',
+                bounds,
+            });
+        }
+    }
+    if (flags.showFootprint && inspect.footprint.center && inspect.footprint.size) {
+        items.push({
+            id: `shadow-debug:footprint:${inspect.footprint.receiverId ?? targetId}`,
+            kind: 'footprint',
+            center: { ...inspect.footprint.center },
+            size: {
+                x: Math.max(inspect.footprint.size.x, 0.01),
+                y: Math.max(inspect.footprint.size.y, 0.015),
+                z: Math.max(inspect.footprint.size.z, 0.01),
+            },
+        });
+    }
+    if (flags.showLightDirection) {
+        const lightDirection = inspect.light?.direction ?? inspect.footprint.normal;
+        const center = inspect.footprint.center ?? casterBounds?.center;
+        const size = inspect.footprint.size ?? casterBounds?.size ?? { x: 2, y: 2, z: 2 };
+        if (center && lightDirection) {
+            items.push({
+                id: `shadow-debug:light:${inspect.light?.lightId ?? targetId}`,
+                kind: 'light-direction',
+                center: { ...center },
+                size: { ...size },
+                direction: { ...lightDirection },
+            });
+        }
+    }
+    if (flags.showArtifactBounds && inspect.footprint.kind === 'artifact') {
+        const artifactBounds = inspect.footprint.center && inspect.footprint.size
+            ? createOverlayBoundsFromCenterSize(inspect.footprint.center, inspect.footprint.size)
+            : undefined;
+        if (artifactBounds) {
+            items.push({
+                id: `shadow-debug:artifact:${targetId}`,
+                kind: 'artifact-bounds',
+                bounds: artifactBounds,
+            });
+        }
+    }
+    return items;
+}
+function createShadowDebugVisibilityMeasureOutput(inspect, input) {
+    const diagnostics = [
+        ...(inspect.diagnostics ?? []),
+        {
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.pixelReadbackUnavailable',
+            message: 'Pixel readback is not available in this editor bridge session, so shadow visibility is measured structurally from policy, receivers, footprint, and runtime evidence.',
+        },
+    ];
+    const requestedReceiverIds = normalizeAgentBridgeIdList(input.receiverIds ?? []);
+    const renderableCount = inspect.runtimeEvidence.renderableShadowPrimitiveCount ?? 0;
+    let visibleScore = 0;
+    let coverage = 0;
+    const opacity = clamp01(readNumber(inspect.plan.params.opacity, 0.42));
+    const casterInactive = inspect.caster?.active === false || inspect.caster?.visible === false;
+    const lightRequired = inspect.plan.backend === 'dynamic-map' || inspect.plan.backend === 'static-baked' || inspect.plan.backend === 'projected';
+    const lightMissing = lightRequired && !inspect.light?.lightId;
+    const missingCasterBounds = !inspect.caster?.bounds;
+    const plannedReceivers = inspect.receivers.filter(receiver => inspect.plan.receiverIds.includes(receiver.receiverId));
+    const visiblePlannedReceivers = plannedReceivers.filter(receiver => isShadowReceiverUsableForVisibility(receiver));
+    const selectedReceiver = selectShadowFootprintReceiver(inspect.plan, plannedReceivers);
+    const missingReceiverBounds = inspect.plan.receiverIds.length > 0
+        && inspect.plan.receiverIds.some(receiverId => !plannedReceivers.some(receiver => receiver.receiverId === receiverId && !!receiver.bounds));
+    const hiddenReceiverIds = plannedReceivers
+        .filter(receiver => receiver.active === false || receiver.visible === false)
+        .map(receiver => receiver.receiverId);
+    const ignoredHiddenReceiverIds = hiddenReceiverIds.filter(receiverId => receiverId !== selectedReceiver?.receiverId);
+    if (inspect.plan.backend === 'none' || inspect.plan.mode === 'none') {
+        diagnostics.push({
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.visibilityPolicyNone',
+            message: 'Resolved Shadow V2 policy is none, so no visible shadow is expected.',
+            details: { backend: inspect.plan.backend, mode: inspect.plan.mode },
+        });
+    }
+    else if (opacity <= 0.001) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityOpacityZero',
+            message: 'Resolved Shadow V2 opacity is zero, so no visible shadow is expected.',
+            details: { opacity },
+        });
+    }
+    else if (casterInactive) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityCasterInactive',
+            message: 'The resolved caster is inactive or hidden, so no visible shadow is expected.',
+            details: { active: inspect.caster?.active, visible: inspect.caster?.visible },
+        });
+    }
+    else if (lightMissing) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityLightMissing',
+            message: 'The resolved shadow backend requires a light, but no usable shadow light was resolved.',
+            details: { backend: inspect.plan.backend, lightId: inspect.plan.lightId },
+        });
+    }
+    else if (missingCasterBounds || missingReceiverBounds) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityBoundsUnavailable',
+            message: 'Caster or receiver projection bounds are unavailable, so structural visibility cannot confirm a visible shadow.',
+            details: { missingCasterBounds, missingReceiverBounds, receiverIds: inspect.plan.receiverIds },
+        });
+    }
+    else if (visiblePlannedReceivers.length === 0 && hiddenReceiverIds.length > 0) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityReceiverInactive',
+            message: 'One or more resolved receivers are inactive or hidden in the current preview, so structural visibility cannot confirm a visible shadow.',
+            details: { receiverIds: hiddenReceiverIds },
+        });
+    }
+    else if (inspect.receivers.length === 0 || inspect.plan.receiverIds.length === 0) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityNoReceiver',
+            message: 'Resolved Shadow V2 plan has no receiver, so a visible shadow is unlikely.',
+            details: { receiverIds: inspect.plan.receiverIds, requestedReceiverIds },
+        });
+    }
+    else if (renderableCount <= 0) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.visibilityNoRuntimePrimitive',
+            message: 'Resolved Shadow V2 plan has receivers but no renderable shadow primitive evidence.',
+            details: { backend: inspect.plan.backend, renderableShadowPrimitiveCount: renderableCount },
+        });
+    }
+    else {
+        if (ignoredHiddenReceiverIds.length > 0) {
+            diagnostics.push({
+                severity: 'info',
+                source: 'editor',
+                code: 'shadow.visibilityIgnoredHiddenReceiver',
+                message: 'Some resolved receivers are hidden in the current preview; structural visibility used the best visible receiver instead.',
+                details: {
+                    receiverIds: ignoredHiddenReceiverIds,
+                    selectedReceiverId: selectedReceiver?.receiverId,
+                },
+            });
+        }
+        const footprintConfidence = clamp01(readNumber(inspect.footprint.confidence, 0.5));
+        const receiverCoverage = clamp01((visiblePlannedReceivers.length > 0 ? visiblePlannedReceivers : plannedReceivers).reduce((max, receiver) => {
+            const overlap = receiver.suitability?.overlap;
+            return Math.max(max, typeof overlap === 'number' ? overlap : 0);
+        }, 0));
+        if (receiverCoverage <= 0.01) {
+            diagnostics.push({
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.visibilityReceiverCoverageTooLow',
+                message: 'Resolved receivers have no meaningful X/Z overlap with the caster, so structural visibility cannot confirm a visible shadow.',
+                details: { coverage: receiverCoverage, receiverIds: inspect.plan.receiverIds },
+            });
+        }
+        else {
+            const backendFactor = inspect.plan.backend === 'dynamic-map'
+                ? 0.9
+                : inspect.plan.backend === 'static-baked'
+                    ? inspect.plan.stale === true ? 0.35 : 0.85
+                    : inspect.plan.backend === 'blob' || inspect.plan.backend === 'projected'
+                        ? 0.75
+                        : 0.5;
+            coverage = clamp01(Math.max(receiverCoverage, footprintConfidence * 0.65));
+            visibleScore = clamp01((0.2 + opacity * 0.35 + coverage * 0.3 + backendFactor * 0.15) * (renderableCount > 0 ? 1 : 0));
+            if (inspect.plan.stale === true || inspect.runtimeEvidence.artifactStale === true) {
+                visibleScore = Math.min(visibleScore, 0.35);
+                diagnostics.push({
+                    severity: 'warning',
+                    source: 'editor',
+                    code: 'shadow.visibilityStaticStale',
+                    message: 'Static shadow evidence is stale; treat visibility as low confidence until rebaked.',
+                });
+            }
+        }
+    }
+    return {
+        target: inspect.target,
+        visible: visibleScore >= 0.45,
+        visibleScore,
+        coverage,
+        renderableShadowPrimitiveCount: renderableCount,
+        measurementKind: 'structural',
+        diagnostics,
+    };
+}
+function isShadowReceiverUsableForVisibility(receiver) {
+    return receiver.active !== false && receiver.visible !== false && !!receiver.bounds;
+}
+function readNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function readShadowDebugOverlayFlags(input) {
+    const explicit = input.showCasterBounds !== undefined
+        || input.showReceiverBounds !== undefined
+        || input.showLightDirection !== undefined
+        || input.showFootprint !== undefined
+        || input.showArtifactBounds !== undefined;
+    return {
+        showCasterBounds: explicit ? input.showCasterBounds === true : true,
+        showReceiverBounds: explicit ? input.showReceiverBounds === true : true,
+        showLightDirection: explicit ? input.showLightDirection === true : true,
+        showFootprint: explicit ? input.showFootprint === true : true,
+        showArtifactBounds: explicit ? input.showArtifactBounds === true : true,
+    };
+}
+function createOverlayBounds(bounds) {
+    if (!bounds?.center || !bounds.size)
+        return undefined;
+    const min = bounds.min ?? {
+        x: bounds.center.x - bounds.size.x / 2,
+        y: bounds.center.y - bounds.size.y / 2,
+        z: bounds.center.z - bounds.size.z / 2,
+    };
+    const max = bounds.max ?? {
+        x: bounds.center.x + bounds.size.x / 2,
+        y: bounds.center.y + bounds.size.y / 2,
+        z: bounds.center.z + bounds.size.z / 2,
+    };
+    return {
+        min: { ...min },
+        max: { ...max },
+        size: { ...bounds.size },
+        center: { ...bounds.center },
+    };
+}
+function createOverlayBoundsFromCenterSize(center, size) {
+    return {
+        center: { ...center },
+        size: { ...size },
+        min: {
+            x: center.x - size.x / 2,
+            y: center.y - size.y / 2,
+            z: center.z - size.z / 2,
+        },
+        max: {
+            x: center.x + size.x / 2,
+            y: center.y + size.y / 2,
+            z: center.z + size.z / 2,
+        },
+    };
+}
+function setSceneShadowPolicy(state, options, renderUi, operations, resolved, policy) {
+    if (!state.session) {
+        return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_SET, 'Editor is not in edit mode.', { code: 'editor.notReady', objectId: resolved.objectId });
+    }
+    let changed = false;
+    let workingDocument = resolved.rawDocument;
+    for (const { path, value } of createShadowPolicyFieldPatches(policy)) {
+        const patch = options.documentAdapter.createSerializedPropertyPatch({
+            document: workingDocument,
+            targetId: resolved.objectId,
+            path,
+            value,
+            commitMode: 'change',
+            persistence: 'document',
+            source: 'custom',
+        });
+        if (!patch)
+            continue;
+        const result = state.session.dispatch({
+            type: 'document.patch',
+            label: patch.label ?? `Agent set shadow ${path}`,
+            patch: patch.patch,
+            targetId: resolved.objectId,
+            ...operations.withProjectionImpact(operations.resolveProjectionImpact(patch, operations.createReprojectProjectionImpact(patch.reprojectIds ?? [patch.changedId ?? resolved.objectId]))),
+        });
+        workingDocument = result.workingDocument;
+        if (result.documentChanged)
+            changed = true;
+    }
+    if (!changed) {
+        const output = createShadowPolicyGetOutput(resolved);
+        return {
+            target: output.target,
+            changed: false,
+            ...(output.policy ? { policy: output.policy } : {}),
+            effectivePolicy: output.effectivePolicy,
+            plan: output.plan,
+            diagnostics: output.diagnostics,
+        };
+    }
+    operations.reprojectProjectionForChangedIds(workingDocument, [resolved.objectId]);
+    state.summary = operations.summarizeDocument(workingDocument, state.session.getSource());
+    state.status = `Agent set shadow policy ${resolved.objectId}`;
+    renderUi();
+    const nextDocument = asEditorSceneDocument(workingDocument);
+    const nextObject = nextDocument ? findShadowGameObject(nextDocument, resolved.objectId) : null;
+    if (!nextDocument || !nextObject) {
+        return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_SET, `Shadow target disappeared after patch: ${resolved.objectId}`, { code: 'shadow.targetMissing', objectId: resolved.objectId });
+    }
+    const output = createShadowPolicyGetOutput({
+        kind: 'scene',
+        target: resolved.target,
+        document: nextDocument,
+        rawDocument: workingDocument,
+        objectId: resolved.objectId,
+        gameObject: nextObject,
+    });
+    return {
+        target: output.target,
+        changed: true,
+        ...(output.policy ? { policy: output.policy } : {}),
+        effectivePolicy: output.effectivePolicy,
+        plan: output.plan,
+        diagnostics: output.diagnostics,
+    };
+}
+function setPrefabStageShadowPolicy(renderUi, operations, resolved, policy) {
+    const rootNodeId = findPrefabRootNodeId(resolved.details);
+    const changed = resolved.nodeId === rootNodeId
+        ? setPrefabRootShadowPolicy(operations, resolved.details, policy)
+        : operations.runPrefabStageAssetAction({
+            actionId: 'prefab.node.setShadow',
+            targetPrefabAssetId: resolved.details.stage.assetId,
+            nodeId: resolved.nodeId,
+            value: policy ?? null,
+        });
+    if (!changed) {
+        return createLocalEditorAgentBridgeFailure(EDITOR_AGENT_BRIDGE_CAPABILITY_ID.SHADOW_POLICY_SET, `Shadow policy action did not change prefab node: ${resolved.nodeId}`, { code: 'shadow.policyUnchanged', details: { assetId: resolved.details.stage.assetId, nodeId: resolved.nodeId } });
+    }
+    renderUi();
+    const nextDetails = operations.getPrefabStageDetails() ?? resolved.details;
+    const nextResolved = resolvePrefabShadowTargetFromDetails(nextDetails, {
+        nodeId: resolved.nodeId,
+        assetId: resolved.details.stage.assetId,
+    });
+    const output = createShadowPolicyGetOutput(nextResolved ?? resolved);
+    return {
+        target: output.target,
+        changed: true,
+        ...(output.policy ? { policy: output.policy } : {}),
+        effectivePolicy: output.effectivePolicy,
+        plan: output.plan,
+        diagnostics: output.diagnostics,
+    };
+}
+function setPrefabRootShadowPolicy(operations, details, policy) {
+    let changed = false;
+    for (const { path, value } of createShadowPolicyFieldPatches(policy)) {
+        const patched = operations.runPrefabStageAssetAction({
+            actionId: 'asset.edit-prefab-field',
+            assetId: details.stage.assetId,
+            browserAssetId: details.stage.browserAssetId,
+            assetKind: 'prefab',
+            targetPrefabAssetId: details.stage.assetId,
+            fieldPath: `prefab.defaults.${path}`,
+            value,
+        });
+        if (patched)
+            changed = true;
+    }
+    return changed;
+}
+function createShadowProjectionContext(resolved, operations) {
+    if (resolved.kind !== 'prefab-stage')
+        return createIdentityShadowProjectionContext();
+    return {
+        resolveProjectionId: targetId => operations.resolvePrefabStageProjectionNodeId?.(targetId) ?? targetId,
+    };
+}
+function createIdentityShadowProjectionContext() {
+    return {
+        resolveProjectionId: targetId => targetId,
+    };
+}
+function resolveShadowTarget(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);
+    const objectId = normalizeAgentBridgeString(input.objectId);
+    if (objectId) {
+        if (!document) {
+            return {
+                ok: false,
+                result: createLocalEditorAgentBridgeFailure(capabilityId, 'Shadow capabilities require an editor scene document.', {
+                    code: 'shadow.unsupportedDocument',
+                    details: { objectId },
+                }),
+            };
+        }
+        const gameObject = findShadowGameObject(document, objectId);
+        if (!gameObject) {
+            return {
+                ok: false,
+                result: createLocalEditorAgentBridgeFailure(capabilityId, `Shadow target object not found: ${objectId}`, {
+                    code: 'shadow.targetNotFound',
+                    objectId,
+                }),
+            };
+        }
+        return {
+            ok: true,
+            target: {
+                kind: 'scene',
+                target: { objectId },
+                document,
+                rawDocument: sessionState.workingDocument,
+                objectId,
+                gameObject,
+            },
+        };
+    }
+    const details = operations.getPrefabStageDetails();
+    if (details) {
+        const prefabTarget = resolvePrefabShadowTargetFromDetails(details, input);
+        if (prefabTarget)
+            return { ok: true, target: prefabTarget };
+    }
+    const activeId = normalizeAgentBridgeString(sessionState.selection.activeId);
+    if (activeId && document) {
+        const gameObject = findShadowGameObject(document, activeId);
+        if (gameObject) {
+            return {
+                ok: true,
+                target: {
+                    kind: 'scene',
+                    target: { objectId: activeId },
+                    document,
+                    rawDocument: sessionState.workingDocument,
+                    objectId: activeId,
+                    gameObject,
+                },
+            };
+        }
+    }
+    return {
+        ok: false,
+        result: createLocalEditorAgentBridgeFailure(capabilityId, 'Shadow target is required. Provide objectId, or open a Prefab stage and provide nodeId/assetId.', {
+            code: 'shadow.targetRequired',
+            details: { objectId: input.objectId, nodeId: input.nodeId, assetId: 'assetId' in input ? input.assetId : undefined },
+        }),
+    };
+}
+function resolvePrefabShadowTargetFromDetails(details, input) {
+    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 node = nodes.find(candidate => candidate.id === nodeId) ?? null;
+    if (!node)
+        return null;
+    const document = createPrefabStageShadowDocument(details, nodes);
+    return {
+        kind: 'prefab-stage',
+        target: { assetId: details.stage.assetId, nodeId: node.id },
+        details,
+        nodeId: node.id,
+        node,
+        document,
+    };
+}
+function createPrefabStageShadowDocument(details, nodes) {
+    return {
+        version: 1,
+        schemaVersion: 1,
+        assets: [],
+        scene: {
+            gameObjects: nodes.map((node) => ({
+                id: node.id,
+                name: node.label,
+                parentId: node.parentId ?? undefined,
+                active: readBoolean(node.defaults?.active, true),
+                kind: node.kind === 'primitive' ? 'primitive' : 'transform',
+                ...(node.defaults?.shadowMode ? { shadowMode: node.defaults.shadowMode } : {}),
+                ...(node.defaults?.shadow ? { shadow: structuredClone(node.defaults.shadow) } : {}),
+                ...(node.primitive ? { primitive: structuredClone(node.primitive) } : {}),
+                ...(node.light ? { light: structuredClone(node.light) } : {}),
+                components: [],
+            })),
+        },
+        metadata: {
+            prefabStageAssetId: details.stage.assetId,
+        },
+    };
+}
+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 createShadowPolicyFieldPatches(policy) {
+    const record = (policy ?? {});
+    return SHADOW_POLICY_FIELDS.map(path => ({
+        path,
+        value: readShadowPolicyFieldValue(record, path) ?? null,
+    }));
+}
+function readShadowPolicyFieldValue(policy, path) {
+    if (path === 'shadow.cast')
+        return policy.cast;
+    if (path === 'shadow.receive')
+        return policy.receive;
+    if (path === 'shadow.mode')
+        return policy.mode;
+    if (path === 'shadow.quality')
+        return policy.quality;
+    if (path === 'shadow.light.mode')
+        return policy.light?.mode;
+    if (path === 'shadow.light.lightId')
+        return policy.light?.lightId;
+    const param = path.slice('shadow.params.'.length);
+    return policy.params?.[param];
+}
+function normalizeShadowPolicy(value) {
+    if (!isRecord(value))
+        return { ok: false, message: 'shadow policy must be an object.' };
+    if (Object.keys(value).length === 0)
+        return { ok: true, settings: undefined };
+    const settings = readEditorShadowSettings(value);
+    if (!settings)
+        return { ok: false, message: 'shadow policy did not contain any valid Shadow V2 fields.' };
+    return { ok: true, settings };
+}
+function readPrefabNodeShadowPolicy(node) {
+    return readEditorShadowSettingsWithLegacy({
+        shadow: node.defaults?.shadow,
+        shadowMode: node.defaults?.shadowMode,
+    }).shadow;
+}
+function createRenderingActionDiagnosticDetails(result) {
+    return {
+        ok: result.ok,
+        changed: result.changed,
+        rendered: result.rendered,
+        ...(result.status ? { status: result.status } : {}),
+        ...(result.statusTone ? { statusTone: result.statusTone } : {}),
+        ...(result.statusDetails ? { statusDetails: result.statusDetails } : {}),
+        ...(isRecord(result.details) ? { actionDetails: result.details } : {}),
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
+function createStaticBakeDiagnostic(result, targetConfirmed, sourceNodeIds) {
+    if (result.ok === true && result.changed === true && targetConfirmed) {
+        return {
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.staticBakeCompleted',
+            message: 'Static shadow bake rendering action completed and included the requested caster.',
+            details: createRenderingActionDiagnosticDetails(result),
+        };
+    }
+    if (result.ok === true && result.changed === true && sourceNodeIds !== null) {
+        return {
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.staticBakeTargetNotFound',
+            message: 'Static shadow bake produced an artifact, but the requested caster was not included in the baked source nodes.',
+            details: createRenderingActionDiagnosticDetails(result),
+        };
+    }
+    if (result.ok === true && result.changed === true) {
+        return {
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.staticBakeTargetUnknown',
+            message: 'Static shadow bake produced an artifact, but the rendering action did not report target source nodes.',
+            details: createRenderingActionDiagnosticDetails(result),
+        };
+    }
+    return {
+        severity: 'warning',
+        source: 'editor',
+        code: 'shadow.staticBakeNoChange',
+        message: result.ok === false
+            ? 'Static shadow bake rendering action did not complete successfully.'
+            : 'Static shadow bake rendering action completed without producing a changed artifact.',
+        details: createRenderingActionDiagnosticDetails(result),
+    };
+}
+function readRenderingActionStaticBakeSourceNodeIds(result) {
+    if (!isRecord(result.details))
+        return null;
+    const details = result.details;
+    if (!Object.prototype.hasOwnProperty.call(details, 'sourceNodeIds'))
+        return null;
+    return normalizeAgentBridgeIdList(readRenderingActionStringList(details.sourceNodeIds));
+}
+function readRenderingActionStringList(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function getResolvedTargetShadowPolicy(target) {
+    if (target.kind === 'scene') {
+        return resolveEditorSceneGameObjectShadowSettings(target.document, target.gameObject).settings;
+    }
+    return readPrefabNodeShadowPolicy(target.node);
+}
+function getResolvedTargetAuthoredPolicy(target) {
+    return target.kind === 'scene'
+        ? readEditorShadowSettings(target.gameObject.shadow)
+        : readPrefabNodeShadowPolicy(target.node);
+}
+function createShadowDebugRuntimeEvidence(plan, receivers, shadowPreviewDebugInfo, casterIds) {
+    const diagnostics = [];
+    if (plan.backend === 'none') {
+        diagnostics.push({
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.runtimeBackendNone',
+            message: 'Resolved backend is none, so no runtime shadow primitive is expected.',
+        });
+    }
+    if (plan.backend !== 'none' && receivers.length === 0) {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.runtimeNoReceivers',
+            message: 'Resolved shadow backend requires receivers, but no receiver candidates are available.',
+        });
+    }
+    if (plan.backend === 'static-baked') {
+        diagnostics.push({
+            severity: 'warning',
+            source: 'editor',
+            code: 'shadow.staticArtifactEvidenceUnavailable',
+            message: 'Static-baked shadow visibility requires a baked artifact; this editor bridge session does not expose artifact presence evidence to shadow.debug.visibilityMeasure.',
+        });
+    }
+    return {
+        backend: plan.backend,
+        renderableShadowPrimitiveCount: plan.backend === 'none' || plan.backend === 'static-baked'
+            ? 0
+            : receivers.filter(receiver => receiver.active !== false && receiver.visible !== false).length,
+        casterRuntimeObjectCount: plan.backend === 'none' ? 0 : 1,
+        receiverRuntimeObjectCount: receivers.length,
+        ...createPlanarShadowRuntimeEvidence(shadowPreviewDebugInfo, casterIds),
+        ...(plan.stale === true ? { artifactStale: true } : {}),
+        ...(diagnostics.length ? { diagnostics } : {}),
+    };
+}
+function createPlanarShadowRuntimeEvidence(shadowPreviewDebugInfo, casterIds) {
+    const planar = shadowPreviewDebugInfo?.planar;
+    if (!planar)
+        return {};
+    const matchingCasters = planar.casters.filter(caster => isPlanarShadowCasterEvidenceForTarget(collectPlanarShadowCasterSourceNodeIds(caster), casterIds));
+    const casters = matchingCasters;
+    if (casters.length === 0)
+        return {};
+    const fallbackReasons = uniqueStrings(casters.flatMap(caster => caster.fallbackReasons ?? []));
+    const alphaCutoutChannels = uniqueStrings(casters.flatMap(caster => caster.alphaCutoutChannels ?? []))
+        .filter((channel) => channel === 'alpha' || channel === 'luminance' || channel === 'red');
+    const alphaCutoutUvSets = uniqueNumbers(casters.flatMap(caster => caster.alphaCutoutUvSets ?? []));
+    const alphaCutoutLevels = uniqueNumbers(casters.flatMap(caster => caster.alphaCutoutLevels ?? []));
+    const strategy = summarizePlanarShadowDebugStrategy(casters);
+    return {
+        planar: {
+            ...(strategy ? { strategy } : {}),
+            sourceMeshCount: casters.length,
+            projectedMeshCount: casters.reduce((sum, caster) => sum + caster.projectedMeshCount, 0),
+            convexHullMeshCount: casters.reduce((sum, caster) => sum + caster.convexHullMeshCount, 0),
+            alphaCutoutMeshCount: casters.reduce((sum, caster) => sum + caster.alphaCutoutMeshCount, 0),
+            ...(alphaCutoutChannels.length ? { alphaCutoutChannels } : {}),
+            ...(alphaCutoutUvSets.length ? { alphaCutoutUvSets } : {}),
+            ...(alphaCutoutLevels.length ? { alphaCutoutLevels } : {}),
+            ...(fallbackReasons.length ? { fallbackReasons } : {}),
+            casters: casters.map(caster => ({
+                sourceName: caster.sourceName,
+                ...(caster.sourceNodeId ? { sourceNodeId: caster.sourceNodeId } : {}),
+                ...(caster.sourceNodeIds?.length ? { sourceNodeIds: [...caster.sourceNodeIds] } : {}),
+                ...(caster.sourceMeshNames?.length ? { sourceMeshNames: [...caster.sourceMeshNames] } : {}),
+                shadowName: caster.shadowName,
+                strategy: caster.strategy,
+                hasSkeleton: caster.hasSkeleton,
+                projectedMeshCount: caster.projectedMeshCount,
+                convexHullMeshCount: caster.convexHullMeshCount,
+                alphaCutoutMeshCount: caster.alphaCutoutMeshCount,
+                ...(caster.alphaCutoutChannels?.length ? { alphaCutoutChannels: [...caster.alphaCutoutChannels] } : {}),
+                ...(caster.fallbackReasons?.length ? { fallbackReasons: [...caster.fallbackReasons] } : {}),
+            })),
+        },
+    };
+}
+function createShadowRuntimeEvidenceCasterIds(resolved, casterId, projectionContext) {
+    const authoringIds = new Set([casterId]);
+    addShadowRuntimeEvidenceSceneDescendants(authoringIds, resolved.document, casterId);
+    const ids = new Set();
+    for (const id of authoringIds) {
+        ids.add(id);
+        ids.add(projectionContext.resolveProjectionId(id));
+    }
+    return ids;
+}
+function addShadowRuntimeEvidenceSceneDescendants(ids, document, parentId) {
+    for (const gameObject of document.scene.gameObjects) {
+        const candidateParentId = readShadowSceneGameObjectParentId(gameObject);
+        if (candidateParentId !== parentId || ids.has(gameObject.id))
+            continue;
+        ids.add(gameObject.id);
+        addShadowRuntimeEvidenceSceneDescendants(ids, document, gameObject.id);
+    }
+}
+function readShadowSceneGameObjectParentId(gameObject) {
+    const parentId = gameObject.parentId;
+    return typeof parentId === 'string' && parentId.length > 0 ? parentId : null;
+}
+function collectPlanarShadowCasterSourceNodeIds(caster) {
+    return uniqueStrings([
+        ...(caster.sourceNodeId ? [caster.sourceNodeId] : []),
+        ...(caster.sourceNodeIds ?? []),
+    ]);
+}
+function isPlanarShadowCasterEvidenceForTarget(sourceNodeIds, casterIds) {
+    for (const sourceNodeId of sourceNodeIds) {
+        if (casterIds.has(sourceNodeId))
+            return true;
+        for (const casterId of casterIds) {
+            if (sourceNodeId.startsWith(`${casterId}::`))
+                return true;
+        }
+    }
+    return false;
+}
+function summarizePlanarShadowDebugStrategy(casters) {
+    if (casters.length === 0)
+        return undefined;
+    const hasProjected = casters.some(caster => caster.projectedMeshCount > 0);
+    const hasHull = casters.some(caster => caster.convexHullMeshCount > 0);
+    if (hasProjected && hasHull)
+        return 'auto';
+    if (hasProjected)
+        return 'projected-mesh';
+    if (hasHull)
+        return 'convex-hull';
+    return undefined;
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(value => value.length > 0))];
+}
+function uniqueNumbers(values) {
+    return [...new Set(values.filter(value => Number.isFinite(value)))];
+}
+function mapShadowPlan(plan) {
+    return {
+        casterId: plan.casterId,
+        receiverIds: [...plan.receiverIds],
+        ...(plan.lightId ? { lightId: plan.lightId } : {}),
+        backend: plan.backend,
+        mode: plan.mode,
+        quality: plan.quality,
+        params: { ...plan.params },
+        ...(plan.stale === true ? { stale: true } : {}),
+        diagnostics: mapShadowDiagnostics(plan.diagnostics),
+    };
+}
+function mapShadowReceivers(receivers, state, context = {}) {
+    const projectionContext = context.projectionContext ?? createIdentityShadowProjectionContext();
+    const casterBounds = context.casterId
+        ? readShadowProjectionBounds(state, context.casterId, projectionContext)
+        : undefined;
+    return receivers.map((receiver) => {
+        const bounds = readShadowProjectionBounds(state, receiver.receiverId, projectionContext);
+        const diagnostics = mapShadowDiagnostics(receiver.diagnostics ?? []);
+        if (!bounds) {
+            diagnostics.push({
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.receiverBoundsUnavailable',
+                message: `Projection bounds are unavailable for receiver "${receiver.receiverId}".`,
+                details: { receiverId: receiver.receiverId },
+            });
+        }
+        const authoredActive = receiver.active !== false;
+        const authoredVisible = authoredActive && receiver.visible !== false;
+        const effectiveVisible = readShadowPreviewEffectiveVisible(state, receiver.receiverId, projectionContext, authoredVisible);
+        const suitability = createShadowReceiverSuitability(receiver, casterBounds, bounds, context.lightId);
+        return {
+            receiverId: receiver.receiverId,
+            source: receiver.source,
+            score: receiver.score,
+            ...(bounds ? { bounds, boundsCenter: bounds.center } : {}),
+            active: authoredActive,
+            visible: effectiveVisible,
+            ...(receiver.receive ? { receive: receiver.receive } : {}),
+            ...(suitability ? { suitability } : {}),
+            ...(diagnostics.length ? { diagnostics } : {}),
+        };
+    });
+}
+function createShadowReceiverSuitability(receiver, casterBounds, receiverBounds, lightId) {
+    const reasons = [...(receiver.suitability?.reasons ?? [])];
+    if (receiverBounds)
+        reasons.push('receiver bounds available');
+    else
+        reasons.push('receiver bounds unavailable');
+    if (casterBounds)
+        reasons.push('caster bounds available');
+    if (lightId)
+        reasons.push(`light ${lightId}`);
+    const distance = casterBounds && receiverBounds ? distance3(casterBounds.center, receiverBounds.center) : undefined;
+    const overlap = casterBounds && receiverBounds ? overlapRatioXZ(casterBounds, receiverBounds) : undefined;
+    return {
+        score: receiver.suitability?.score ?? receiver.score,
+        ...(overlap !== undefined ? { overlap } : {}),
+        ...(distance !== undefined ? { distance } : {}),
+        ...(receiver.suitability?.material ? { material: receiver.suitability.material } : {}),
+        ...(lightId ? { light: lightId } : receiver.suitability?.light ? { light: receiver.suitability.light } : {}),
+        reasons,
+    };
+}
+function createShadowDebugTargetSummary(target, state, projectionContext = createIdentityShadowProjectionContext()) {
+    const id = getResolvedTargetCasterId(target);
+    const projectionId = projectionContext.resolveProjectionId(id);
+    const bounds = readShadowProjectionBounds(state, id, projectionContext);
+    const transform = editorTransformSnapshotToAgentTransform(state.projection?.readNodeTransform(projectionId));
+    if (target.kind === 'scene') {
+        const active = target.gameObject.active !== false;
+        return {
+            objectId: target.objectId,
+            label: target.gameObject.name ?? target.objectId,
+            kind: target.gameObject.kind ?? 'transform',
+            active,
+            visible: readShadowPreviewEffectiveVisible(state, id, projectionContext, active),
+            ...(bounds ? { bounds } : {}),
+            ...(transform ? { transform } : {}),
+            ...(!bounds ? {
+                diagnostics: [{
+                        severity: 'warning',
+                        source: 'editor',
+                        code: 'shadow.casterBoundsUnavailable',
+                        message: `Projection bounds are unavailable for caster "${target.objectId}".`,
+                    }],
+            } : {}),
+        };
+    }
+    return {
+        nodeId: target.nodeId,
+        label: target.node.label,
+        kind: target.node.kind,
+        active: readBoolean(target.node.defaults?.active, true),
+        visible: readShadowPreviewEffectiveVisible(state, id, projectionContext, readBoolean(target.node.defaults?.active, true)),
+        ...(bounds ? { bounds } : {}),
+        ...(transform ? { transform } : {}),
+        ...(!bounds ? {
+            diagnostics: [{
+                    severity: 'warning',
+                    source: 'editor',
+                    code: 'shadow.casterBoundsUnavailable',
+                    message: `Projection bounds are unavailable for prefab node "${target.nodeId}".`,
+                }],
+        } : {}),
+    };
+}
+function createShadowLightSummary(document, lightId) {
+    if (!lightId)
+        return undefined;
+    const light = findShadowGameObject(document, lightId);
+    if (!light?.light) {
+        return {
+            lightId,
+            diagnostics: [{
+                    severity: 'warning',
+                    source: 'editor',
+                    code: 'shadow.lightNotFound',
+                    message: `Resolved shadow light "${lightId}" was not found in the preview document.`,
+                }],
+        };
+    }
+    const diagnostics = [];
+    let direction;
+    let directionSource;
+    const orientationDiagnostics = [];
+    if (light.light.type === 'directional') {
+        direction = normalizeEditorSceneLightDirectionVector(light.light.direction);
+        directionSource = 'light.direction';
+        const transform = findEditorSceneTransform(light);
+        const rotation = transform && 'rotation' in transform ? transform.rotation : undefined;
+        const drift = detectEditorSceneDirectionalLightOrientationDrift({
+            direction: light.light.direction,
+            rotation,
+        });
+        if (drift.hasDrift) {
+            orientationDiagnostics.push({
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.lightOrientationDrift',
+                message: 'Directional Light transform.rotation and light.direction are out of sync. Runtime shadows use light.direction until the light orientation is edited again.',
+                details: {
+                    expectedDirectionFromTransform: cloneShadowVec3Json(drift.expectedDirection),
+                    actualDirection: cloneShadowVec3Json(drift.actualDirection),
+                    delta: drift.delta,
+                    tolerance: drift.tolerance,
+                },
+            });
+            diagnostics.push(...orientationDiagnostics);
+        }
+    }
+    return {
+        lightId,
+        label: light.name ?? light.id,
+        type: light.light.type,
+        ...(light.shadow?.light?.mode ? { mode: light.shadow.light.mode } : {}),
+        ...(direction ? { direction } : {}),
+        ...(directionSource ? { directionSource } : {}),
+        ...(orientationDiagnostics.length ? { orientationDiagnostics } : {}),
+        ...(typeof light.light.intensity === 'number' ? { intensity: light.light.intensity } : {}),
+        ...(diagnostics.length ? { diagnostics } : {}),
+    };
+}
+function cloneShadowVec3(value) {
+    return { x: value.x, y: value.y, z: value.z };
+}
+function cloneShadowVec3Json(value) {
+    return { x: value.x, y: value.y, z: value.z };
+}
+function createShadowFootprintSummary(plan, receivers, state, projectionContext = createIdentityShadowProjectionContext(), light) {
+    if (plan.backend === 'none' || plan.receiverIds.length === 0) {
+        return {
+            kind: 'none',
+            confidence: plan.backend === 'none' ? 1 : 0,
+            diagnostics: plan.backend === 'none'
+                ? [{
+                        severity: 'info',
+                        source: 'editor',
+                        code: 'shadow.footprintNone',
+                        message: 'Shadow backend is none, so no footprint is expected.',
+                    }]
+                : [{
+                        severity: 'warning',
+                        source: 'editor',
+                        code: 'shadow.receiverNotFound',
+                        message: 'No receiver is available for an estimated shadow footprint.',
+                    }],
+        };
+    }
+    const receiver = selectShadowFootprintReceiver(plan, receivers);
+    if (!receiver) {
+        return {
+            kind: 'unknown',
+            receiverId: plan.receiverIds[0],
+            confidence: 0.1,
+            diagnostics: [{
+                    severity: 'warning',
+                    source: 'editor',
+                    code: 'shadow.footprintReceiverUnavailable',
+                    message: 'Resolved shadow plan has receiver ids, but no receiver summaries are available for footprint selection.',
+                    details: { receiverIds: plan.receiverIds },
+                }],
+        };
+    }
+    const receiverBounds = receiver?.bounds;
+    const casterBounds = readShadowProjectionBounds(state, plan.casterId, projectionContext);
+    if (!receiverBounds || !casterBounds) {
+        return {
+            kind: 'unknown',
+            receiverId: receiver?.receiverId ?? plan.receiverIds[0],
+            confidence: 0.25,
+            diagnostics: [{
+                    severity: 'warning',
+                    source: 'editor',
+                    code: 'shadow.footprintBoundsUnavailable',
+                    message: 'Caster or receiver bounds are unavailable, so the footprint can only be reported structurally.',
+                }],
+        };
+    }
+    const footprintHeight = 0.02;
+    const direction = normalizeShadowDirection(light?.direction);
+    const projectedBounds = direction
+        ? projectCasterBoundsToReceiver(casterBounds, receiverBounds, direction)
+        : null;
+    const size = projectedBounds
+        ? {
+            x: Math.min(receiverBounds.size.x, Math.max(projectedBounds.size.x, 0.01)),
+            y: footprintHeight,
+            z: Math.min(receiverBounds.size.z, Math.max(projectedBounds.size.z, 0.01)),
+        }
+        : {
+            x: Math.min(receiverBounds.size.x, Math.max(casterBounds.size.x, 0.01)),
+            y: footprintHeight,
+            z: Math.min(receiverBounds.size.z, Math.max(casterBounds.size.z, 0.01)),
+        };
+    const center = projectedBounds?.center ?? casterBounds.center;
+    const contactTolerance = Math.max(0.025, casterBounds.size.y * 0.04);
+    const contactsReceiver = Math.abs(casterBounds.min.y - receiverBounds.max.y) <= contactTolerance
+        || casterBounds.min.y < receiverBounds.max.y;
+    const diagnostics = [
+        ...(!direction && light?.type === 'directional' ? [{
+                severity: 'warning',
+                source: 'editor',
+                code: 'shadow.footprintDirectionUnavailable',
+                message: 'Directional shadow light is missing a direction, so the footprint falls back to caster bounds.',
+                details: { lightId: light.lightId },
+            }] : []),
+        ...(contactsReceiver ? [{
+                severity: 'info',
+                source: 'editor',
+                code: 'shadow.casterContactsReceiver',
+                message: 'Caster bounds touch or intersect the receiver plane. A real screenshot may show only the outside portions of the shadow because the caster itself occludes the contact footprint.',
+                details: {
+                    casterMinY: casterBounds.min.y,
+                    receiverMaxY: receiverBounds.max.y,
+                    contactTolerance,
+                },
+            }] : []),
+    ];
+    return {
+        kind: plan.backend === 'static-baked' ? 'artifact' : 'estimated',
+        receiverId: receiver.receiverId,
+        center: {
+            x: center.x,
+            y: receiverBounds.max.y + footprintHeight / 2 + 0.002,
+            z: center.z,
+        },
+        size,
+        normal: { x: 0, y: 1, z: 0 },
+        ...(direction ? { direction } : {}),
+        area: Math.max(0, size.x) * Math.max(0, size.z),
+        confidence: receiver.suitability?.overlap !== undefined ? Math.min(1, Math.max(0.35, receiver.suitability.overlap)) : 0.6,
+        ...(diagnostics.length ? { diagnostics } : {}),
+    };
+}
+function selectShadowFootprintReceiver(plan, receivers) {
+    const planOrder = new Map(plan.receiverIds.map((receiverId, index) => [receiverId, index]));
+    const candidates = receivers.filter(receiver => planOrder.has(receiver.receiverId));
+    const ranked = candidates.length > 0 ? candidates : receivers;
+    return [...ranked].sort((left, right) => compareShadowReceiverForFootprint(left, right, planOrder))[0];
+}
+function compareShadowReceiverForFootprint(left, right, planOrder) {
+    const leftVisible = left.active !== false && left.visible !== false ? 1 : 0;
+    const rightVisible = right.active !== false && right.visible !== false ? 1 : 0;
+    if (leftVisible !== rightVisible)
+        return rightVisible - leftVisible;
+    const leftHasBounds = left.bounds ? 1 : 0;
+    const rightHasBounds = right.bounds ? 1 : 0;
+    if (leftHasBounds !== rightHasBounds)
+        return rightHasBounds - leftHasBounds;
+    const leftOverlap = typeof left.suitability?.overlap === 'number' ? left.suitability.overlap : -1;
+    const rightOverlap = typeof right.suitability?.overlap === 'number' ? right.suitability.overlap : -1;
+    if (leftOverlap !== rightOverlap)
+        return rightOverlap - leftOverlap;
+    const leftDistance = typeof left.suitability?.distance === 'number' ? left.suitability.distance : Number.POSITIVE_INFINITY;
+    const rightDistance = typeof right.suitability?.distance === 'number' ? right.suitability.distance : Number.POSITIVE_INFINITY;
+    if (leftDistance !== rightDistance)
+        return leftDistance - rightDistance;
+    const leftScore = typeof left.suitability?.score === 'number' ? left.suitability.score : left.score ?? 0;
+    const rightScore = typeof right.suitability?.score === 'number' ? right.suitability.score : right.score ?? 0;
+    if (leftScore !== rightScore)
+        return rightScore - leftScore;
+    const leftOrder = planOrder.get(left.receiverId) ?? Number.MAX_SAFE_INTEGER;
+    const rightOrder = planOrder.get(right.receiverId) ?? Number.MAX_SAFE_INTEGER;
+    return leftOrder - rightOrder;
+}
+function normalizeShadowDirection(direction) {
+    if (!direction)
+        return null;
+    const length = Math.hypot(direction.x, direction.y, direction.z);
+    if (!Number.isFinite(length) || length <= 1e-6)
+        return null;
+    return {
+        x: direction.x / length,
+        y: direction.y / length,
+        z: direction.z / length,
+    };
+}
+function projectCasterBoundsToReceiver(casterBounds, receiverBounds, direction) {
+    if (Math.abs(direction.y) <= 1e-5)
+        return null;
+    const receiverY = receiverBounds.max.y;
+    const points = [];
+    for (const x of [casterBounds.min.x, casterBounds.max.x]) {
+        for (const y of [casterBounds.min.y, casterBounds.max.y]) {
+            for (const z of [casterBounds.min.z, casterBounds.max.z]) {
+                const t = (receiverY - y) / direction.y;
+                if (!Number.isFinite(t))
+                    continue;
+                if (t < 0) {
+                    points.push({ x, y: receiverY, z });
+                    continue;
+                }
+                points.push({
+                    x: x + direction.x * t,
+                    y: receiverY,
+                    z: z + direction.z * t,
+                });
+            }
+        }
+    }
+    if (points.length === 0)
+        return null;
+    const min = {
+        x: Math.min(...points.map(point => point.x)),
+        y: receiverY,
+        z: Math.min(...points.map(point => point.z)),
+    };
+    const max = {
+        x: Math.max(...points.map(point => point.x)),
+        y: receiverY,
+        z: Math.max(...points.map(point => point.z)),
+    };
+    return {
+        center: {
+            x: (min.x + max.x) / 2,
+            y: receiverY,
+            z: (min.z + max.z) / 2,
+        },
+        size: {
+            x: Math.max(0, max.x - min.x),
+            y: 0,
+            z: Math.max(0, max.z - min.z),
+        },
+    };
+}
+function readShadowProjectionBounds(state, targetId, projectionContext) {
+    const projectionId = projectionContext.resolveProjectionId(targetId);
+    return createAgentBridgeBounds(state.projection?.getSelectionBounds([projectionId]) ?? null);
+}
+function readShadowPreviewEffectiveVisible(state, targetId, projectionContext, authoredVisible) {
+    const projectionId = projectionContext.resolveProjectionId(targetId);
+    const projectionEntry = state.projection?.getPreviewVisibilityOverrides?.()
+        ?.find(entry => entry.nodeId === projectionId || entry.nodeId === targetId);
+    if (projectionEntry)
+        return projectionEntry.effectiveVisible;
+    const overrides = state.previewVisibility?.overrides ?? {};
+    const override = overrides[projectionId] ?? overrides[targetId];
+    return authoredVisible && override !== false;
+}
+function createAgentBridgeBounds(bounds) {
+    if (!bounds)
+        return undefined;
+    const half = {
+        x: bounds.size.x / 2,
+        y: bounds.size.y / 2,
+        z: bounds.size.z / 2,
+    };
+    return {
+        center: { ...bounds.center },
+        size: { ...bounds.size },
+        min: {
+            x: bounds.center.x - half.x,
+            y: bounds.center.y - half.y,
+            z: bounds.center.z - half.z,
+        },
+        max: {
+            x: bounds.center.x + half.x,
+            y: bounds.center.y + half.y,
+            z: bounds.center.z + half.z,
+        },
+    };
+}
+function distance3(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+function overlapRatioXZ(a, b) {
+    const overlapX = Math.max(0, Math.min(a.max.x, b.max.x) - Math.max(a.min.x, b.min.x));
+    const overlapZ = Math.max(0, Math.min(a.max.z, b.max.z) - Math.max(a.min.z, b.min.z));
+    const intersection = overlapX * overlapZ;
+    const casterArea = Math.max(0.0001, a.size.x * a.size.z);
+    return Math.max(0, Math.min(1, intersection / casterArea));
+}
+function mapShadowDiagnostics(diagnostics) {
+    return diagnostics.map(diagnostic => ({
+        severity: diagnostic.severity,
+        source: 'editor',
+        code: diagnostic.code,
+        message: diagnostic.message,
+        ...(diagnostic.casterId ? { objectId: diagnostic.casterId } : {}),
+        details: {
+            ...(diagnostic.details ?? {}),
+            ...(diagnostic.casterId ? { casterId: diagnostic.casterId } : {}),
+            ...(diagnostic.receiverId ? { receiverId: diagnostic.receiverId } : {}),
+            ...(diagnostic.lightId ? { lightId: diagnostic.lightId } : {}),
+        },
+    }));
+}
+function createShadowTargetDiagnostics(resolved) {
+    if (resolved.kind !== 'prefab-stage')
+        return [];
+    return [{
+            severity: 'info',
+            source: 'editor',
+            code: 'shadow.prefabStagePreview',
+            message: 'Prefab stage shadow resolution uses editable prefab nodes as a preview scene; runtime scene receiver/light binding is finalized by the scene compiler.',
+            details: { assetId: resolved.details.stage.assetId, nodeId: resolved.nodeId },
+        }];
+}
+function getResolvedTargetCasterId(target) {
+    return target.kind === 'scene' ? target.objectId : target.nodeId;
+}
+function asEditorSceneDocument(value) {
+    if (!isRecord(value))
+        return null;
+    const scene = value.scene;
+    if (!isRecord(scene) || !Array.isArray(scene.gameObjects))
+        return null;
+    if (!Array.isArray(value.assets))
+        return null;
+    return 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);
+}
+function readBoolean(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+//# sourceMappingURL=shadows.js.map