Align rendering orchestration with camera stack plans

engine/include/XCEngine/Rendering/AGENTS.md

@@ -62,6 +62,9 @@ Unity 兼容的公开命名、对象所有权和扩展点。
   具体后端头。
 - 新增 camera-stack、renderer-index、shadow、depth、post-process 或 final output 行为时，不要绕过
   `CameraFramePlanBuilder` 或 `SceneRenderRequestPlanner`。
+- 修改 camera stack 行为时，要保持 `CameraRenderRequest.cameraStackId`、`CameraStackFramePlan`、
+  `RenderPipelineHost::BuildStackFramePlans` 和 `SceneRenderer::BuildStackFramePlans` 同步。
+  `CameraFramePlan` 是每个 camera 的叶子计划；`CameraStackFramePlan` 是顶层渲染生命周期根。
 - 不要在 native 长生命周期对象里保存 raw managed object pointers 或 managed context handles。
   需要持久化时，通过现有 external managed object handle 系统 retain。
 - Managed URP public APIs 不要依赖 `CameraFrameGraph` 或 `NativeSceneRecorder` 这类 native
@@ -97,8 +100,9 @@ Unity 兼容的公开命名、对象所有权和扩展点。
   built-in forward pipeline policy，而不是作为 URP-declared work 的 backend executor。
 - 目标所有权模型是：URP 决定渲染什么、何时渲染、哪些 renderer lists/passes/features 激活，以及
   哪些 stages 存在；native 只执行这些声明，不夹带 built-in pipeline policy。
-- `CameraFramePlanBuilder` 现在只负责从 request 构造 `CameraFramePlan` 并委托所选
-  `RenderPipelineAsset::ConfigureCameraFramePlan`。它不再在 asset hook 之后追加通用 legacy
+- `CameraFramePlanBuilder` 现在负责从 request 构造 per-camera `CameraFramePlan`，再按
+  `CameraRenderRequest.cameraStackId` 收口为 `CameraStackFramePlan`。它委托所选
+  `RenderPipelineAsset::ConfigureCameraFramePlan` 配置叶子计划，不再在 asset hook 之后追加通用 legacy
   fullscreen stage heuristic；默认 native fullscreen/final-output 行为应留在 native asset policy 内部。
 - Hidden fallback 很危险。如果 managed URP stage 声明支持但无法 record，失败必须可见。不要静默用
   default built-in path 画同一个 stage，然后称之为 URP。
@@ -132,10 +136,12 @@ Native renderer 现在是 camera frame planner 加 RenderGraph executor，manage
 叠在 native scene draw backend 之上。
 
 - `SceneRenderer` 是 scene-level convenience entry point。它的公开管线选择根是 `RenderPipelineAsset`；
-  它通过 `SceneRenderRequestPlanner` 收集 camera requests，通过 `RenderPipelineHost` 构建 frame plans，
-  然后渲染排序后的 camera plans。
+  它通过 `SceneRenderRequestPlanner` 收集 camera requests，通过 `RenderPipelineHost` 构建
+  `CameraStackFramePlan`，然后以 camera stack 为根渲染。旧的 `BuildFramePlans`/flat-plan `Render`
+  API 只是兼容包装。
 - `RenderPipelineHost` 拥有一个 `CameraFramePlanBuilder` 和一个 `CameraRenderer`。它是从
-  `CameraRenderRequest` 到 `CameraFramePlan` 的常规 native bridge，并沿用同一个 asset selection root。
+  `CameraRenderRequest` 到 `CameraStackFramePlan` 的常规 native bridge，并沿用同一个 asset selection root。
+  Stack 渲染完成后由所选 `RenderPipeline` 接收 `FinishCameraStackRendering`，用于 URP stack 生命周期收尾。
 - `CameraRenderer` 拥有 asset 创建出的所选 `RenderPipeline`，提取 `RenderSceneData`，解析 directional
   shadow execution，把全部 frame stages 记录进 native `RenderGraph`，编译 graph 并执行。
 - `RenderPipelineAsset` 是 native asset contract。它创建 pipeline，配置 pipeline 实例，配置 request
@@ -265,6 +271,9 @@ package。
 - `RendererFramePlan` 不得只是 pass 对象引用列表。`ScriptableRenderPass.CreateFramePlanSnapshot` 是冻结
   pass 状态的边界；新增 mutable pass state 时必须确认它能被 frame-plan snapshot 捕获，避免后续 camera
   planning 改写前一个 camera 的 recording。
+- `OnFinishCameraStackRendering` 是 camera-stack 生命周期回调，不是 per-stage 或 per-camera-frame 回调。
+  `ScriptableRenderer` 可以在 `RecordRendererFromFramePlan` 时登记待收尾的 `RendererFramePlan`，但只能由
+  native `CameraStackFramePlan` 渲染完成后的 `FinishCameraStackRendering` 触发实际回调。
 - URP features 的 `AddRenderPasses` 是 per-camera 声明点，不是 per-stage 回调。不要通过
   stage 数据分阶段重复 enqueue；`AddRenderPasses`/`SetupRenderPasses` 必须使用 `RendererPassQueueData`，
   而不是 recording 阶段的 `RenderingData`。pass 所属 stage 应由 `RenderPassEvent -> RendererBlock`
@@ -377,6 +386,8 @@ Scene data 每个 camera frame 提取一次，然后由 pipeline 调整。
   authoring 还未公开。
 - `UniversalPostProcessBlock` 仍保留 post-process source promotion helper；实际 post-process stage 由
   active pass queue 中的 features/passes 声明。
+- 当前 camera stack 归属仍来自 `SceneRenderRequestPlanner` 对 base/overlay 请求流的 `cameraStackId`
+  分组；引擎相机数据模型还没有 Unity `cameraStack` 那种显式 per-base overlay 列表。
 - Render-pipeline selection 已切到 `AssetRef` 作为根身份，并且 managed SRP descriptor 已保存
   ScriptableObject graph snapshot；完整 editor/importer `.asset` 持久化和 sub-asset authoring 仍未完成。
 - 当前 shadow support 是单个 main directional shadow path，没有 cascades。
@@ -411,6 +422,10 @@ Scene data 每个 camera frame 提取一次，然后由 pipeline 调整。
 - URP stage planning 已收口到 renderer active pass queue 派生的 per-`framePlanId` `RendererFramePlan` 和
   stage manifest。Stage support 和 stage recording 现在消费 planning 阶段保存的同一份冻结 plan，
   关闭了 feature planning hook、support probe、recording 和各 stage 分别重建 pass queue 的重复事实源。
+- 顶层 native orchestration 已从 flat camera frame list 收口为 `CameraStackFramePlan`。`SceneRenderer`
+  和 `RenderPipelineHost` 的真实渲染入口以 camera stack 为根；flat `CameraFramePlan` APIs 保留为兼容包装。
+- URP `OnFinishCameraStackRendering` 已改为 stack-end 语义：recording 阶段只登记待收尾 pass，native
+  `CameraStackFramePlan` 渲染完成后再通过 pipeline/stage-recorder bridge 触发。
 - `CameraFramePlanBuilder` 已移除对 fullscreen stages 的通用尾部自动补齐；selected
   `RenderPipelineAsset` 现在是 native plan policy 的唯一入口，managed URP path 不再保留第二个
   fullscreen stage planner。

engine/include/XCEngine/Rendering/Execution/CameraStackFramePlan.h

@@ -0,0 +1,28 @@
+#pragma once
+
+#include <XCEngine/Rendering/Execution/CameraFramePlan.h>
+
+#include <cstdint>
+#include <vector>
+
+namespace XCEngine {
+namespace Rendering {
+
+struct CameraStackFramePlan {
+    uint64_t stackPlanId = 0u;
+    uint64_t cameraStackId = 0u;
+    std::vector<CameraFramePlan> cameraPlans = {};
+
+    static CameraStackFramePlan FromCameraPlans(
+        uint64_t cameraStackId,
+        std::vector<CameraFramePlan> cameraPlans);
+
+    bool IsValid() const;
+    bool HasBaseCamera() const;
+    bool IsOverlayOnly() const;
+    const CameraFramePlan* GetBaseCameraPlan() const;
+    const CameraFramePlan* GetSortKeyPlan() const;
+};
+
+} // namespace Rendering
+} // namespace XCEngine

engine/include/XCEngine/Rendering/Execution/RenderPipelineHost.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <XCEngine/Rendering/Execution/CameraStackFramePlan.h>
 #include <XCEngine/Rendering/Execution/CameraRenderer.h>
 
 #include <memory>
@@ -22,9 +23,13 @@ public:
 
     std::vector<CameraFramePlan> BuildFramePlans(
         const std::vector<CameraRenderRequest>& requests);
+    std::vector<CameraStackFramePlan> BuildStackFramePlans(
+        const std::vector<CameraRenderRequest>& requests);
 
     bool Render(const CameraFramePlan& plan);
     bool Render(const std::vector<CameraFramePlan>& plans);
+    bool Render(const CameraStackFramePlan& stackPlan);
+    bool Render(const std::vector<CameraStackFramePlan>& stackPlans);
 
 private:
     CameraRenderer m_cameraRenderer;

engine/include/XCEngine/Rendering/Execution/SceneRenderer.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <XCEngine/Rendering/Execution/CameraStackFramePlan.h>
 #include <XCEngine/Rendering/Execution/RenderPipelineHost.h>
 #include <XCEngine/Rendering/Planning/SceneRenderRequestPlanner.h>
 
@@ -28,9 +29,16 @@ public:
         Components::CameraComponent* overrideCamera,
         const RenderContext& context,
         const RenderSurface& surface);
+    std::vector<CameraStackFramePlan> BuildStackFramePlans(
+        const Components::Scene& scene,
+        Components::CameraComponent* overrideCamera,
+        const RenderContext& context,
+        const RenderSurface& surface);
 
     bool Render(const CameraFramePlan& plan);
     bool Render(const std::vector<CameraFramePlan>& plans);
+    bool Render(const CameraStackFramePlan& stackPlan);
+    bool Render(const std::vector<CameraStackFramePlan>& stackPlans);
     bool Render(
         const Components::Scene& scene,
         Components::CameraComponent* overrideCamera,

engine/include/XCEngine/Rendering/Pipelines/ScriptableRenderPipelineHost.h

@@ -60,6 +60,8 @@ public:
         const RenderContext& context,
         const RenderSurface& surface,
         const RenderSceneData& sceneData) override;
+    void FinishCameraStackRendering(
+        const CameraStackFramePlan& stackPlan) override;
     void ConfigureRenderSceneData(
         const CameraFramePlan& plan,
         RenderSceneData& sceneData) const override;

engine/include/XCEngine/Rendering/Planning/CameraRenderRequest.h

@@ -27,6 +27,7 @@ struct CameraRenderRequest {
     FinalOutputRenderRequest finalOutput;
     ResolvedFinalColorPolicy finalColorPolicy = {};
     ObjectIdRenderRequest objectId;
+    uint64_t cameraStackId = 0u;
     float cameraDepth = 0.0f;
     uint8_t cameraStackOrder = 0;
     int32_t rendererIndex = -1;

engine/include/XCEngine/Rendering/RenderPipeline.h

@@ -23,6 +23,7 @@ namespace Rendering {
 
 class RenderGraphBuilder;
 struct CameraFramePlan;
+struct CameraStackFramePlan;
 struct DirectionalShadowExecutionState;
 struct DirectionalShadowSurfaceAllocation;
 
@@ -91,6 +92,8 @@ public:
         const RenderPipelineStageRenderGraphContext&) {
         return false;
     }
+    virtual void FinishCameraStackRendering(
+        const CameraStackFramePlan&) {}
 };
 
 class RenderPipelineBackend {
@@ -142,6 +145,8 @@ public:
         const CameraFramePlan& plan,
         const DirectionalShadowSurfaceAllocation& shadowAllocation,
         DirectionalShadowExecutionState& shadowState) const;
+    virtual void FinishCameraStackRendering(
+        const CameraStackFramePlan&) {}
 
     void SetCameraFrameStandalonePass(
         CameraFrameStage stage,