docs(Mobile): define mobile package and adapter boundaries

2026-10-17 05:31:01 +08:00 · 2026-08-11 09:28:00 +08:00
parent 957e7de590
commit 6e81c13225
9 changed files with 329 additions and 5 deletions
@@ -2,7 +2,7 @@

 本文档记录 `AtomUI.slnx` 中项目的主要引用关系。它描述源码维护视角下的依赖方向，不等同于 NuGet 包的最终依赖闭包。

-## 解决方案项目
+## 当前解决方案项目

 `AtomUI.slnx` 当前包含核心库、控件库、图标字体、Gallery 宿主：

@@ -65,3 +65,24 @@
 `AtomUI.Native` 是能力层，不是策略层。上层库可以通过 internal API 启用原生能力，但不应把控件行为、
 主题策略或平台默认配置下沉到 Native。反过来，P/Invoke、原生结构体、协议对象和可释放 native hook
 也不应散落在控件实现里。
+
+## 已批准目标依赖
+
+以下关系属于 Mobile Foundation 的目标架构，不是当前 `AtomUI.slnx` 项目或当前直接引用：
+
+```mermaid
+flowchart LR
+    Controls["AtomUI.Controls"] --> Mobile["AtomUI.Mobile.Controls\n目标项目，当前未实现"]
+    Native["AtomUI.Native"] -. capability .-> Mobile
+    Generator["AtomUI.Generator"] -. analyzer .-> Mobile
+    Mobile -. target .-> IOS["iOS Host"]
+    Mobile -. target .-> Android["Android Host"]
+```
+
+- `AtomUI.Mobile.Controls` 直接建立在 `AtomUI.Controls` 上，与 `AtomUI.Desktop.Controls` 平行且不依赖 Desktop。
+- `AtomUI.Native` 作为正交能力层，仅在 Avalonia 公共 API 无法表达能力时供 Mobile adapter 使用。
+- `AtomUI.Generator` 提供构建期静态 descriptor、Theme 和 Localization 注册，不成为运行时发现机制。
+- iOS/Android Host 提供生命周期和 adapter；平台宿主不拥有 Control API、Theme 或跨平台状态机。
+
+目标项目加入解决方案后，必须把真实项目引用补入“解决方案项目”和“主要项目引用”；在此之前不得把本节视为当前构建图。
+详细包边界见 [Mobile Controls 模块](../../modules/mobile-controls/overview.md)。
@@ -1,6 +1,7 @@
 # 运行平台策略

-AtomUI 当前面向 Windows、macOS、Linux 桌面运行，同时支持 Browser Gallery 作为展示和验证路径。移动端目录在文档中预留，但当前解决方案没有 `AtomUI.Mobile.Controls` 项目。
+AtomUI 当前面向 Windows、macOS、Linux 桌面运行，同时支持 Browser Gallery 作为展示和验证路径。移动端已有批准的
+iOS/Android 目标架构，但当前解决方案没有 `AtomUI.Mobile.Controls` 项目或 Mobile Gallery Host。

 ## 桌面端

@@ -32,4 +33,21 @@ Browser Gallery 使用 `net10.0-browser` 和 `Avalonia.Browser`。浏览器环

 ## 移动端

-`AtomUI.Native` 已对 `AtomUI.Mobile.Controls` 开放 `InternalsVisibleTo`，说明未来有移动端扩展空间。当前文档只预留 [移动端 Control 文档](../../controls/mobile/overview.md)，不把移动端作为已实现模块描述。
+> 状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 `AtomUI.Mobile.Controls`。
+
+Mobile 采用与 Desktop 平行的产品包和 iOS/Android Host：
+
+- `AtomUI.Mobile.Controls` 消费 `AtomUI.Controls` 的公共抽象，并拥有 Mobile Control、Runtime scope、Theme 和平台默认策略。
+- 每个 Host 提供统一 capability adapter，向 Runtime 投射 Safe Area、system bars、input pane、返回/导航手势、haptic、
+  touch profile、前后台、Reduce Motion、字体缩放和无障碍环境。
+- iOS 是首个实现与体验验收平台；Android adapter、公共 API 和验证责任从 Foundation 开始存在。
+- Control 只消费 capability/profile，不读取 OS 名称，也不在控件内散布条件编译。
+- `AtomUI.Native` 只在 Avalonia 公共 API 无法表达所需 OS 能力时提供底层调用、handle、hook 和确定释放。
+
+跨模块契约见 [Mobile 系统架构](../systems/mobile/overview.md)，目标包边界见
+[Mobile Controls 模块](../../modules/mobile-controls/overview.md)。当前 iOS 工程环境记录见
+[Apple iOS 开发环境](../../engineering/platforms/apple-ios-development-environment.md)；Android 工程文档在获得真实工具链证据前
+只定义验证边界，不声明未经验证的命令或版本。
+
+`AtomUI.Native` 已对目标程序集名称开放 `InternalsVisibleTo`，但当前没有 Mobile 实现消费者；该声明不能作为源码、平台验证
+或发布证据。
@@ -0,0 +1,71 @@
+# AtomUI.Mobile.Controls 模块概览
+
+> 状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 `AtomUI.Mobile.Controls`。
+
+`AtomUI.Mobile.Controls` 是与 `AtomUI.Desktop.Controls` 平行的目标源码项目和 NuGet 包。它提供移动产品控件、
+每 `TopLevel` Runtime scope、移动主题与本地化资产，以及对平台 capability adapter 的统一消费；Mobile 不依赖
+Desktop，也不以 `MobileMode` 复用 Desktop 产品控件。
+
+## 模块职责
+
+| 拥有 | 不拥有 |
+| --- | --- |
+| Mobile Public Controls、ControlTheme、Own Token 和产品文案 | Desktop Window、标题栏、桌面 Popup 默认策略 |
+| `MobileViewportContext`、`MobileOverlayManager`、`MobileGestureCoordinator` 的包内实现与装配 | 第二套 Global Token、Theme Algorithm 或 Localization runtime |
+| 平台 capability contract 的消费、Runtime scope 生命周期和降级策略 | 可由 Avalonia 公共 API 表达的 Host 工具链职责 |
+| `UseMobileControls(...)` 注册、生成式 descriptor 和主题/语言资产接入 | iOS/Android 签名、部署、应用生命周期入口 |
+| iOS、Android 与 Headless adapter 的公共内部契约 | P/Invoke、native handle、原生结构体和不可释放 hook |
+
+跨模块 Runtime 不变量由 [AtomUI Mobile 系统架构](../../architecture/systems/mobile/overview.md) 维护；本目录只描述
+目标包自身的 ownership、注册、打包和 adapter 边界。
+
+## 目标依赖
+
+```mermaid
+flowchart LR
+    Controls["AtomUI.Controls\n公共抽象与 primitives"] --> Mobile["AtomUI.Mobile.Controls\n目标项目，当前未实现"]
+    Native["AtomUI.Native\n必要的底层 OS 能力"] -. capability .-> Mobile
+    Generator["AtomUI.Generator\n构建期静态 descriptor"] -. analyzer .-> Mobile
+    Mobile -. target .-> IOS["iOS Host"]
+    Mobile -. target .-> Android["Android Host"]
+```
+
+- `AtomUI.Controls` 是目标运行时上游，间接提供 Core、Controls.Shared、Theme、Localization 和公共 Control 能力。
+- `AtomUI.Native` 是正交能力上游；只有 Avalonia 公共 API 无法表达所需 OS 能力时才进入调用链。
+- `AtomUI.Generator` 是构建期基础设施，不通过运行时程序集扫描替代静态注册。
+- iOS/Android Host 是下游组合入口，只负责生命周期、平台初始化、签名/部署和 adapter 提供。
+- `AtomUI.Desktop.Controls` 不在 Mobile 的依赖闭包中。
+
+具体当前/目标依赖视图见 [项目依赖关系](../../architecture/foundations/dependency-graph.md)。
+
+## 启动与消费
+
+目标注册入口 `UseMobileControls(...)` 连接现有 `UseAtomUI(...)` Builder，注册 Mobile descriptor、Theme、Localization、
+Runtime scope factory 和 Host adapter。该名称属于已批准目标契约，当前仓库没有对应实现；真实签名、程序集和目标框架必须
+在 Foundation 源码与测试存在后回写。
+
+应用业务库应依赖 `AtomUI.Controls` 或更低层的稳定公共契约；只有实际承载移动 UI 的应用或 Mobile Gallery Host 才直接
+组合 `AtomUI.Mobile.Controls`。同一应用可以在组合根选择 Desktop 或 Mobile 产品包，但不能让两个产品包互相引用。
+
+## 专题导航
+
+| 文档 | 职责 |
+| --- | --- |
+| [源码职责](source-ownership.md) | Public Controls、Runtime、Theme、Localization、平台能力消费和生成资产的 ownership |
+| [启动与打包](startup-and-packaging.md) | `UseMobileControls(...)`、多目标公共 API、NuGet 和 AOT/trimming 边界 |
+| [平台 Adapter](platform-adapters.md) | Headless、iOS、Android adapter 的统一 capability contract 与生命周期 |
+| [Mobile 系统架构](../../architecture/systems/mobile/overview.md) | 跨模块 Viewport、Navigation、Overlay、Gesture、Theme 和验证不变量 |
+| [Mobile Control 文档](../../controls/mobile/overview.md) | 具体能力分类、Public API 和实现证据 |
+
+## 当前证据
+
+| 维度 | 当前状态 |
+| --- | --- |
+| Design | 能力已纳入总体设计 |
+| Source | 未实现 |
+| iOS | 未验证 |
+| Android | 未验证 |
+| Release | 未验证 |
+| Publication | 未发布 |
+
+`AtomUI.Native` 中预留的 internal visibility 只是未来集成边界，不是 Mobile 源码、包或平台支持证据。
@@ -0,0 +1,71 @@
+# AtomUI.Mobile.Controls 平台 Adapter
+
+> 状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 `AtomUI.Mobile.Controls`。
+
+Mobile 使用一个内部 capability contract，由 Headless、iOS 和 Android adapter 分别实现。Control 和 Runtime scope 只消费
+统一 snapshot、事件与 hook，不读取 OS 名称，也不在具体 Control 中散布条件编译。
+
+## Capability Contract
+
+| 能力 | 统一输出/入口 | Owner |
+| --- | --- | --- |
+| Safe Area 与 system bars | Insets、available bounds 和变化通知 | Adapter 读取平台；`MobileViewportContext` 合并状态 |
+| Input pane / IME | Occlusion、可用性和变化通知 | Adapter 投递；Viewport/输入 Control 协调消费 |
+| Back 与 navigation gesture | 单次可仲裁的系统输入 | Adapter 投递；Overlay/Navigation 决定 owner |
+| Haptic | 可用性与受约束调用入口 | Adapter 执行；Control policy 决定是否请求 |
+| Touch profile | 已解析的最小触控目标和 interaction profile | Adapter/profile 提供；Theme/Control 消费值 |
+| Foreground/background | Host 状态、恢复和 detach/recreation 通知 | Host/adapter 投递；Runtime scope 统一清理或恢复 |
+| Reduce Motion 与 font scale | 一致 snapshot 字段 | Adapter 投递；Viewport 发布 |
+| Accessibility environment | 平台环境和能力状态 | Adapter 投递；Control 仍拥有 AutomationPeer 语义 |
+
+平台 adapter 提供事实与 hook，不决定 Control 视觉、Token、导航结果、Overlay 关闭原因或默认产品行为。
+
+## 实现角色
+
+| Adapter | 目标用途 | 不能证明 |
+| --- | --- | --- |
+| Headless | 注入确定 snapshot、模拟能力缺失、验证状态机和 acquire/release | iOS/Android 触摸、IME、系统返回或无障碍体验 |
+| iOS | 投射 iOS Host 生命周期、viewport、输入、返回手势、haptic 和 accessibility 环境 | Android 行为或发布状态 |
+| Android | 投射 Android Host 生命周期、system back、viewport、输入、haptic 和 accessibility 环境 | iOS 行为或发布状态 |
+
+iOS 是首个实现平台，但三个 adapter 从 Foundation 使用相同 contract。iOS 适配不能把平台 SDK 类型、pt 特例或 Host 生命周期
+泄漏到 Public Control API；Android 适配不能在后续通过修改公共契约追补基本能力。
+
+## Owner 生命周期
+
+1. Host 在 AtomUI 组合根提供 adapter。
+2. 每个 `TopLevel` attach 时，Mobile Runtime scope acquire 与 adapter 建立 owner-scoped subscription。
+3. Adapter 在 UI thread 边界投递原始变化；Runtime 合并为一致 snapshot。
+4. `TopLevel` detach、Host recreation 或应用终止时取消 pending work，并释放 subscription、hook 和 owner 引用。
+5. 新 Host/TopLevel 创建新的 scope；旧 adapter 不通过 static cache 保留 Visual、Control 或 session。
+
+如果 native hook 需要跨线程回调，adapter 必须在进入 Runtime 前完成线程和 lifetime 归一化，不能让 Control 直接处理原生回调。
+
+## 能力缺失
+
+| 缺失能力 | 退化行为 |
+| --- | --- |
+| Safe Area/system bar 来源 | 使用零 inset 并保留可诊断状态 |
+| Input pane bounds | 保持最近一致 viewport，不猜测键盘高度 |
+| Haptic | 跳过反馈，不改变逻辑终态和事件顺序 |
+| 系统返回/gesture | 显式导航命令继续使用同一事务 |
+| Reduce Motion | 移除非必要动效，保持提交、焦点和 cleanup |
+| Host detach | 以统一原因终止 session、pointer chain 和订阅 |
+
+必需 adapter 缺失或重复属于启动/acquire 配置错误，不使用静默 fallback。可选 capability 缺失则按上表退化，Control 不通过
+OS 名称猜测值。
+
+## Native 边界
+
+Adapter 优先使用 Avalonia 公共 API。只有能力涉及 P/Invoke、native handle、原生结构体、协议对象或可释放 hook，且 Avalonia
+公共 API 无法表达时，才调用 `AtomUI.Native`。Native 负责参数/handle 校验、底层调用、错误转换和确定释放；Mobile adapter
+负责 owner、订阅、状态归一化和产品侧调用时机。
+
+## 验证
+
+- Contract/Headless：snapshot 合并、能力缺失、重复 adapter、detach、取消和无残留引用。
+- iOS：Simulator 与真机分别验证 Safe Area、IME、返回手势、旋转、前后台、VoiceOver 和 haptic 降级。
+- Android：Emulator 与真机分别验证 system bars、IME、system back、multi-window、Activity recreation、TalkBack 和 haptic 降级。
+- Release：两个平台分别验证 trim/AOT 后 adapter、Theme、Localization 和 DataTemplate 可发现，产物可安装启动。
+
+测试层级与证据要求见 [Mobile 验证架构](../../architecture/systems/mobile/verification.md)。当前没有 adapter 源码或平台通过证据。
@@ -0,0 +1,55 @@
+# AtomUI.Mobile.Controls 源码职责
+
+> 状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 `AtomUI.Mobile.Controls`。
+
+本文按稳定职责域定义目标包的 source ownership，不虚构尚不存在的项目文件树、namespace 清单或实现类。Foundation 落地后，
+本页必须以真实 Public API、Theme、测试和生成产物替换预实现描述。
+
+## 职责域
+
+| 职责域 | 输入 | 输出 | Public / internal 边界 | 替换预实现描述所需证据 |
+| --- | --- | --- | --- | --- |
+| Public Controls | `AtomUI.Controls` 抽象、移动交互设计、平台无关状态模型 | Mobile Control API、事件、Command、AutomationPeer 契约 | 应用语义为 public；session、policy 和 adapter 细节为 internal | 可审查 Public API 源码、默认值、Contract tests 和 Gallery API 表 |
+| Runtime scopes | `TopLevel`、平台 snapshot、导航与 gesture policy | 每 `TopLevel` 的 Viewport、Overlay 和 Gesture 服务 | 应用只消费 Control/受约束服务 API；scope owner 和 coordinator 为 internal | attach/detach 源码、Headless 生命周期测试和资源释放证据 |
+| Themes and Tokens | Global Token、Theme Algorithm、`ThemeConfigProvider`、Control descriptor | Mobile ControlTheme、Own Token、必要的 Mobile Alias Token | Token/Theme 定制契约为 public；资源装配与 snapshot 消费为 internal | AXAML Theme、生成 descriptor、Light/Dark visual baseline 和 Token 表 |
+| Localization resources | Catalog、Snapshot、fallback、Generator | Mobile 文案 key、默认语言资源和静态注册 | 面向应用的本地化行为稳定；catalog 装配为 internal | 真实 catalog、生成注册、fallback tests 和 Gallery locale 场景 |
+| Platform capability consumption | 统一 adapter snapshot、Host 生命周期、可选 Native 能力 | Safe Area、IME、back、haptic、touch profile 等平台无关状态 | Control 不暴露 OS-specific 类型；adapter 和 profile 为 internal | iOS/Android/Headless adapter 源码、平台测试和缺失能力测试 |
+| Registration and generated descriptors | `IAtomUIBuilder`、Generator 输入、Theme/Localization 资产 | `UseMobileControls(...)` 与静态 descriptor/manifest 注册 | 包级启动入口为 public；生成池、adapter validation 和 scope factory 为 internal | 真实生成输出、启动失败测试、trim/AOT publish 和安装启动证据 |
+
+## Public Controls
+
+同名 Desktop/Mobile Control 只有在 API、状态机、Form 和无障碍语义真正一致时才复用 `AtomUI.Controls` 抽象。数据和
+协调逻辑一致但视觉/交互不同的能力只共享 model/coordinator；移动 viewport、Overlay、手势或输入语义占主导时设计独立
+Mobile API。Desktop ControlTheme、Desktop Token 和 Desktop 私有类型不能成为 Mobile 的实现依赖。
+
+具体 Control 目录只有满足 [Mobile 单 Control 文档门禁](../../engineering/contributing/mobile-documentation-guidelines.md#单-control-文档创建门禁)
+后才创建；本模块文档不提前枚举 82 个源码目录。
+
+## Runtime Scopes
+
+每个活动 `TopLevel` 恰好拥有一个 Mobile Runtime scope。scope 装配 `MobileViewportContext`、
+`MobileOverlayManager`、`MobileGestureCoordinator` 和 Host adapter，并在 detach 时统一取消 pending work、释放订阅、
+pointer capture、animation owner 与 session。跨模块状态机以 [Mobile Runtime 架构](../../architecture/systems/mobile/overview.md)
+为准，包内实现不得另建不兼容副本。
+
+## Themes、Tokens 与 Localization
+
+Mobile 复用现有 Global Token、Theme Algorithm、`ThemeConfigProvider`、Catalog、Snapshot、fallback 和 Generator。
+移动特有的运行时状态不进入 Token；平台 adapter 不提供产品文案；内置资产通过生成式 descriptor 或显式静态注册进入
+启动链路，不使用反射扫描或字符串成员访问。
+
+## 平台与 Native 边界
+
+平台目录只实现统一 internal capability contract，不新增平台专属 Public Control API。能由 Avalonia 公共 API 表达的能力
+直接通过 adapter 投射；只有 P/Invoke、native handle、原生结构体、hook 或协议对象确实必要时才调用 `AtomUI.Native`。
+Native 管理底层资源和错误边界，Mobile 管理 owner、viewport、gesture、Overlay、Theme 和产品默认策略。
+
+## 同步门禁
+
+Foundation 源码进入仓库后，本页至少同步：
+
+1. 真实项目与 namespace 定位，但不罗列无维护价值的完整文件树。
+2. Public/internal 类型 owner、注册入口和生成资产来源。
+3. Runtime scope acquire/release 对和 adapter 生命周期。
+4. Theme、Localization、测试、Gallery 和 AOT 证据链接。
+5. iOS、Android、Release 与 Publication 的独立状态。
@@ -0,0 +1,74 @@
+# AtomUI.Mobile.Controls 启动与打包
+
+> 状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 `AtomUI.Mobile.Controls`。
+
+本文定义目标 `UseMobileControls(...)` 注册职责、多目标公共契约、静态资产注册和 NuGet/AOT 边界。所有 API 名称均为
+已批准目标契约；真实签名、TFM、RID、包依赖和命令只能由实际项目与构建证据确认。
+
+## `UseMobileControls(...)` 职责
+
+目标入口与 `UseDesktopControls()` 平行，并接入现有 `UseAtomUI(...)` Builder。它负责：
+
+1. 确保真正共享的 Common Controls 基础只注册一次。
+2. 注册 Mobile Control descriptor、Own Token、ControlTheme asset manifest 和产品本地化资源。
+3. 注册每 `TopLevel` Mobile Runtime scope 的 factory、attach 和 detach 回调。
+4. 连接当前 Host 提供的平台 capability adapter。
+5. 在启动/acquire 阶段拒绝缺失、重复或与 Host 不匹配的 adapter。
+6. 注册必要的包级 initializer，不把平台生命周期和应用签名职责带入 Control 包。
+
+目标入口不创建可变进程级 Overlay host、不扫描程序集发现 Control，也不通过 OS 名称选择 Public API。
+
+## 多目标公共 API
+
+- iOS 和 Android 目标暴露相同的 Public Control API、事件、Token identity 和本地化 key。
+- 平台差异只实现 internal adapter 或 platform profile；Public API 不暴露平台 SDK 类型。
+- Headless target/adapter 用于 Contract 和生命周期测试，不构成移动平台发布目标。
+- 具体 TFM、RID 与 workload 由仓库集中构建配置和 Foundation 验证固定，不能在预实现文档中猜测。
+- iOS-first 只决定实现与体验验收顺序，不允许 Android 编译契约在 Foundation 中缺席。
+
+## 静态注册与 Generator
+
+Mobile 沿用现有生成式注册模型：
+
+| 资产 | 目标注册方式 |
+| --- | --- |
+| Control/Token descriptor | Generator 输出 exact CLR type、identity、Own Token schema 和强类型构造 |
+| ControlTheme asset | 构建期校验并生成 manifest，保持 owner 和引用 identity |
+| Localization | 静态 catalog descriptor 与内置 Translation Bundle 注册 |
+| Runtime/adapter | 显式 factory 与 Host 提供关系，不进行运行时程序集扫描 |
+
+新的 Generator 能力只有在现有 descriptor 模型无法表达 Mobile 稳定契约时才扩展。运行时反射、字符串成员访问和动态
+factory 不能作为缺少静态设计的替代方案。
+
+## Host 组合与校验
+
+iOS/Android Host 在应用组合根完成平台初始化、生命周期桥接和 adapter 提供，再调用 AtomUI 注册链路。注册成功至少证明：
+
+- 恰好存在一个与 Host 匹配的 adapter。
+- 每个 `TopLevel` 只创建一个 Mobile Runtime scope。
+- Theme、Localization 和 Control descriptor 在首个 Control 创建前已经冻结到有效 snapshot。
+- Host detach 可以终止 scope-owned session、pointer chain、subscription 和 pending update。
+
+缺失或重复 adapter 应给出可诊断的启动/acquire 失败；不可延迟到第一次 Overlay、IME 或 gesture 才暴露。
+
+## NuGet 依赖边界
+
+目标包的直接产品依赖是 `AtomUI.Controls`；需要 Avalonia 公共 API 无法表达的能力时引用 `AtomUI.Native`；
+`AtomUI.Generator` 以构建期 Analyzer/生成基础设施参与。`AtomUI.Desktop.Controls`、Desktop DataGrid、Desktop
+ColorPicker、Desktop Extras 和当前 Desktop-bound GalleryBase 都不得进入 Mobile 包的依赖闭包。
+
+发布包只携带运行时必需程序集、Theme、Localization 和静态 descriptor 资产。平台 Host、签名 profile、设备部署配置和
+Gallery 示例属于各自应用工程，不作为 Mobile Control NuGet 包的隐式副作用。
+
+## AOT 与 Trimming
+
+- 内置 Control、Token、Theme、Localization 和 adapter 注册使用显式 descriptor 或 Source Generator。
+- DataTemplate、ControlTheme 和语言资源在裁剪后必须可发现。
+- 非 Visual `AvaloniaObject` 的动态资源遵循 scoped resource host 生命周期。
+- Analyzer 和普通 build 只能证明静态约束，不能替代 iOS/Android Release publish。
+- Release 结论要求产物真实构建、安装并启动；两个平台分别记录。
+
+## 当前状态
+
+当前不存在 `UseMobileControls(...)` 实现、Mobile 包、目标 TFM 或发布产物。本页不能作为 NuGet 安装、平台构建或 AOT
+通过证据；对应项目落地后必须用真实源码、测试和发布记录校准。
@@ -31,8 +31,9 @@ AtomUI.Native
  - 管理原生资源、hook 和错误边界
 ```

-所有成员目前都是 `internal`，通过 `InternalsVisibleTo` 向 `AtomUI.Desktop.Controls` 和预留的
-`AtomUI.Mobile.Controls` 开放。它是实现包，不是公共 Native SDK。
+所有成员目前都是 `internal`，通过 `InternalsVisibleTo` 向 `AtomUI.Desktop.Controls` 和目标程序集名称
+`AtomUI.Mobile.Controls` 开放。当前仓库没有 Mobile 实现消费者；这项预留只定义未来可见性边界，不是 Mobile 源码、
+平台验证或发布证据。它是实现包，不是公共 Native SDK。

 ### 能力与策略分界

@@ -41,6 +42,7 @@ AtomUI.Native
 | `AtomUI.Native` | 封装 OS/backend 原生调用、窗口系统底层能力、消息结构体、hook/façade、句柄校验、原生资源释放 | 决定窗口主题、Dialog 行为、控件状态机、Token、默认平台策略 |
 | `AtomUI.Core` | AtomUI 基础设施、主题/Token/语言、资源、动画、应用启动默认选项；必要时调用 `AtomUI.Native` 获取底层 OS 能力 | 直接散落 P/Invoke、原生结构体、平台协议细节，或依赖具体控件生命周期 |
 | `AtomUI.Desktop.Controls` | Window/Dialog/Popup 等桌面控件语义、生命周期、何时调用 Native 能力 | 直接维护 P/Invoke、原生结构体或重复实现 OS 协议 |
+| `AtomUI.Mobile.Controls`（目标） | Viewport、Gesture、Overlay、Theme、owner 生命周期、平台默认策略，以及何时调用 Native 能力 | 直接维护 P/Invoke、原生 handle/结构体、不可释放 hook，或把 OS 类型暴露到 Public Control API |

 `AtomUI.Core` 可以依赖 `AtomUI.Native`。`Core` 是 AtomUI 的基础设施层，不等于必须排除所有 Window
 或 OS 概念；判断标准是能力本身是否属于底层 OS/native 操作。例如安全打开文件、解析真实路径、读取系统
@@ -61,6 +63,10 @@ AtomUI.Native
 “纯净”而把 P/Invoke、native struct 或平台错误处理留在 `Core`；也不能因为某个 native 能力最终服务于
 Window/Dialog，就把底层 OS 细节放回 `AtomUI.Desktop.Controls`。

+未来 Mobile adapter 同样遵循这条边界：优先使用 Avalonia 公共 API；只有 Safe Area、system bar、input pane、返回手势、
+haptic 或生命周期能力确实需要原生调用时才进入 Native。Native 负责底层资源和确定释放，Mobile Runtime 负责
+`TopLevel` owner、订阅、snapshot 合并、取消和产品行为。
+
 ## 目录和职责

 ```text
@@ -11,6 +11,11 @@
 - 承载 Wayland input-region 的协议对象解析与 NWayland 调用；调用时机、输入矩形计算和 Window 状态策略仍属于
  `AtomUI.Desktop.Controls`。
 - 为 `AtomUI.Core` 和 `AtomUI.Desktop.Controls` 提供内部基础设施。
+- 为目标 `AtomUI.Mobile.Controls` 保留 internal 能力边界；当前没有 Mobile 实现消费者。
+
+未来 Mobile adapter 只有在 Avalonia 公共 API 无法表达所需 OS 能力时才消费 Native。Native 可以拥有 P/Invoke、native
+handle、原生结构体、协议对象、可释放 hook 和错误转换；Mobile Controls 继续拥有 viewport、gesture、Overlay、Theme、
+owner 生命周期与平台默认策略。预留的 `InternalsVisibleTo` 不代表 Mobile 包已经实现或通过平台验证。

 ## 目录结构

@@ -37,5 +42,7 @@ src/AtomUI.Native/
 - [macos.md](macos.md)
 - [linux.md](linux.md)
 - [Windowing 系统](../../architecture/systems/windowing/overview.md)
+- [Mobile 系统](../../architecture/systems/mobile/overview.md)
+- [Mobile 平台 Adapter](../mobile-controls/platform-adapters.md)
 - [跨平台 Window 定制指南](../../guides/windowing/cross-platform-window.md)
 - [WindowDrawnDecorations 指南](../../guides/windowing/window-drawn-decorations.md)
@@ -11,6 +11,7 @@
 | [Localization](localization/overview.md) | `src/AtomUI.Localization` | [本地化系统](../architecture/systems/localization/overview.md) |
 | [Controls.Shared](controls-shared/overview.md) | `src/AtomUI.Controls.Shared` | [Control 基础设施](../architecture/systems/control-infrastructure/overview.md) |
 | [Controls](controls/overview.md) | `src/AtomUI.Controls` | [渲染系统](../architecture/systems/rendering/overview.md) |
+| [Mobile Controls](mobile-controls/overview.md) | 目标 `AtomUI.Mobile.Controls` 项目与包，当前未实现 | [Mobile 系统](../architecture/systems/mobile/overview.md) |
 | [Generator](generator/overview.md) | `src/AtomUI.Generator` | [主题系统](../architecture/systems/theming/overview.md)、[本地化系统](../architecture/systems/localization/overview.md) |
 | [Fonts](fonts/overview.md) | `src/AtomUI.Fonts.*` | [主题系统](../architecture/systems/theming/overview.md) |
 | [Icons](icons/overview.md) | `src/AtomUI.Icons.*` | [整体架构](../architecture/overview.md) |