docs: rebuild audio and core api docs

docs/api/XCEngine/Core/LayerStack/LayerStack.md

@@ -6,43 +6,120 @@
 
 **头文件**: `XCEngine/Core/LayerStack.h`
 
-**描述**: 定义 `XCEngine/Core` 子目录中的 `LayerStack` public API。
+**描述**: 一个按“普通层 + overlay”分段组织的 `Layer` 容器，负责遍历和基础生命周期分发。
 
-## 概述
+## 角色概述
 
-`LayerStack.h` 是 `XCEngine/Core` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`LayerStack` 负责管理多个 [Layer](../Layer/Layer.md) 实例的顺序关系。它把容器分成两段：
 
-## 声明概览
+- 普通 layers
+- overlays
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `LayerStack` | `class` | 头文件中的公开声明。 |
+这是一种常见的应用壳层设计，适合把“主功能层”和“悬浮 UI / 调试覆盖层”分开组织。
 
-## 公共方法
+## 当前实现行为
 
-| 方法 | 描述 |
-|------|------|
-| [LayerStack()](Constructor.md) | 构造对象。 |
-| [~LayerStack()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [pushLayer](pushLayer.md) | 公开方法，详见头文件声明。 |
-| [pushOverlay](pushOverlay.md) | 公开方法，详见头文件声明。 |
-| [popLayer](popLayer.md) | 公开方法，详见头文件声明。 |
-| [popOverlay](popOverlay.md) | 公开方法，详见头文件声明。 |
-| [onUpdate](onUpdate.md) | 公开方法，详见头文件声明。 |
-| [onEvent](onEvent.md) | 公开方法，详见头文件声明。 |
-| [onImGuiRender](onImGuiRender.md) | 公开方法，详见头文件声明。 |
-| [onAttach](onAttach.md) | 公开方法，详见头文件声明。 |
-| [onDetach](onDetach.md) | 公开方法，详见头文件声明。 |
-| [begin](begin.md) | 公开方法，详见头文件声明。 |
-| [end](end.md) | 公开方法，详见头文件声明。 |
-| [rbegin](rbegin.md) | 公开方法，详见头文件声明。 |
-| [rend](rend.md) | 公开方法，详见头文件声明。 |
-| [cbegin](cbegin.md) | 公开方法，详见头文件声明。 |
-| [cend](cend.md) | 公开方法，详见头文件声明。 |
-| [crbegin](crbegin.md) | 公开方法，详见头文件声明。 |
-| [crend](crend.md) | 公开方法，详见头文件声明。 |
+### 1. 所有权由 `std::unique_ptr<Layer>` 表达
+
+`LayerStack` 内部直接持有：
+
+`std::vector<std::unique_ptr<Layer>> m_layers`
+
+因此：
+
+- stack 拥有 layer 生命周期
+- `pushLayer()` / `pushOverlay()` 都会转移 unique ownership
+- `popLayer()` / `popOverlay()` 删除元素时会触发对象析构
+
+### 2. 普通层和 overlay 的分界靠 `m_layerInsertIndex`
+
+`pushLayer()` 会把新层插入 `m_layers.begin() + m_layerInsertIndex`，然后递增索引；`pushOverlay()` 则直接追加到尾部。
+
+这意味着当前排序规则是：
+
+- 普通层保持在前半段
+- overlay 永远位于后半段
+
+### 3. `push*` 不会自动调用 `onAttach()`
+
+这是一个非常重要的当前行为。很多引擎框架会在 push 时立刻 attach，但当前实现不会：
+
+- `pushLayer()` 只做插入
+- `pushOverlay()` 只做插入
+
+真正的 attach 分发只发生在显式调用 [onAttach](onAttach.md) 时。
+
+### 4. `pop*` 会调用 `onDetach()`
+
+相对地，`popLayer()` 和 `popOverlay()` 在删除元素前都会先调用对应 layer 的 `onDetach()`。
+
+### 5. 遍历顺序是正向遍历
+
+以下分发方法当前都按 `m_layers` 的正向顺序调用：
+
+- `onUpdate()`
+- `onEvent()`
+- `onImGuiRender()`
+- `onAttach()`
+- `onDetach()`
+
+这尤其意味着 `onEvent()` 不是“从 top-most overlay 逆向往下传”的模式，而是从前到后正向调用。对有事件吞噬需求的系统来说，这一点必须明确。
+
+## 迭代器暴露
+
+`LayerStack` 同时暴露了：
+
+- `begin()` / `end()`
+- `rbegin()` / `rend()`
+- `cbegin()` / `cend()`
+- `crbegin()` / `crend()`
+
+这让外部可以按需要自定义遍历顺序，但也说明它没有封装成强约束的调度器。
+
+## 当前代码库中的使用情况
+
+在当前取证范围内，没有看到它在 `engine/src` 里形成广泛调用链。因此这更像基础应用框架能力，而不是当前引擎主运行时的核心主线。
+
+## 线程语义
+
+- 当前实现没有加锁。
+- 所有修改和遍历都应按单线程外部驱动理解。
+
+## 当前实现限制
+
+- `pushLayer()` / `pushOverlay()` 不会自动 `onAttach()`。
+- `onDetach()` 在 `pop*` 时会调用，但析构函数本身是默认实现，不会自动遍历 detach 剩余层。
+- `onEvent()` 采用正向遍历，不是常见的逆向 overlay 优先分发。
+- 没有看到直接测试覆盖。
+
+## 相关方法
+
+- [Constructor](Constructor.md)
+- [Destructor](Destructor.md)
+- [pushLayer](pushLayer.md)
+- [pushOverlay](pushOverlay.md)
+- [popLayer](popLayer.md)
+- [popOverlay](popOverlay.md)
+- [onUpdate](onUpdate.md)
+- [onEvent](onEvent.md)
+- [onImGuiRender](onImGuiRender.md)
+- [onAttach](onAttach.md)
+- [onDetach](onDetach.md)
+- [begin](begin.md)
+- [end](end.md)
+- [rbegin](rbegin.md)
+- [rend](rend.md)
+- [cbegin](cbegin.md)
+- [cend](cend.md)
+- [crbegin](crbegin.md)
+- [crend](crend.md)
+
+## 相关指南
+
+- [Core Foundations: Ownership, Events, And Layers](../../../_guides/Core/Core-Foundations-Ownership-Events-And-Layers.md)
 
 ## 相关文档
 
-- [当前目录](../Core.md) - 返回 `Core` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Core.md)
+- [Layer](../Layer/Layer.md)
+- [API 总索引](../../../main.md)