rgpui 1.3.0

//! # rgpui - GPU 加速的跨平台 UI 框架
//!
//! rgpui 是基于 Zed 编辑器的 `gpui` 框架的跨平台移植版本。
//! 它提供了一套完整的 GPU 加速 UI 系统，包括：
//! - **实体系统（Entity System）**：基于 Arena 分配器的实体管理
//! - **响应式事件系统**：观察者模式的订阅和通知机制
//! - **键盘事件分发**：层级化的按键事件处理管线
//! - **布局引擎**：基于 Taffy 的 Flexbox 布局
//! - **文本渲染**：GPU 加速的文本排版和渲染
//! - **平台抽象层**：支持 Windows、macOS、Linux、Web 等平台
//!
//! ## 快速入门
//!
//! ```rust,no_run
//! use rgpui::prelude::*;
//! use rgpui::App;
//!
//! fn main() {
//!     App::new().run(|cx| {
//!         // 在这里创建你的第一个窗口和视图
//!     });
//! }
//! ```

#![doc = include_str!("../README.md")]
#![warn(missing_docs)]
#![allow(clippy::type_complexity)] // 回调在 RGPUI 中大量使用，类型复杂度检查不适用
#![allow(clippy::collapsible_else_if)] // 平台特定代码中可能产生误报
#![allow(unused_mut)] // 平台特定代码中可能产生误报

/// 将自身 crate 重导出为 `rgpui`，使得宏展开时能正确引用
extern crate self as rgpui;

/// RGPUI crate 的 manifest 目录路径，编译时由 Cargo 注入
#[doc(hidden)]
pub static GPUI_MANIFEST_DIR: &'static str = env!("CARGO_MANIFEST_DIR");

// ==================== 第一部分：框架核心（应用/元素/布局/渲染/文本/平台抽象） ====================

/// Action 系统 - 定义用户交互动作的序列化与分发机制
#[macro_use]
mod action;

/// 应用核心模块 - 包含 App 主结构体、Context、EntityMap 等
mod app;

/// Arena 分配器 - 高效的实体内存分配策略
mod arena;

/// 资源缓存 - 管理已加载的资源数据
mod asset_cache;

/// 资源缓存 - 管理已加载的资源数据
mod assets;

/// 资源系统 - 定义 Asset trait 和资源加载管线
mod bounds_tree;

/// 边界树 - 用于空间查询的高性能数据结构
pub mod collections;

/// 集合类型 - 提供 FxHashMap、FxHashSet 等高性能集合
mod color;

/// Web DOM 后端 - DOM 树数据模型与构建器（feature `dom-backend` 门控，默认关闭）
#[cfg(feature = "dom-backend")]
mod dom;

/// 颜色模块 - 定义 HSL、RGBA 等颜色类型及转换
/// RGPUI 默认使用的颜色常量和主题定义
pub mod colors;

/// 主题系统 - 颜色工具、色板与主题注册机制
pub mod theme;

/// 组件文本类型 - 轻量文本封装，供组件库使用
pub mod component_text;
/// 重导出组件文本类型
pub use component_text::{ComponentText, ComponentTextViewStyle};

/// 元素系统核心 - 定义 Element trait 和元素树构建机制
mod element;

/// 内置元素 - 提供 Div、Canvas、Img 等预定义 UI 元素
mod elements;

/// 执行器模块 - 定义前台和后台任务执行器 trait
mod executor;

/// 平台调度器 - 跨平台的定时器和任务调度实现
mod platform_scheduler;

/// 精化类型 - 支持部分初始化的类型安全模式
pub mod refineable;

/// 任务调度器 - 异步任务的执行和协调
pub mod scheduler;

/// 和树数据结构 - 一种并发友好的 B-tree 变体，用于文本缓冲区等场景
pub mod sum_tree;

pub(crate) use platform_scheduler::PlatformScheduler;

/// 几何类型 - 定义 Point、Size、Bounds、BoundsRect 等几何图元
mod geometry;

/// 手势识别 - 定义平台手势事件和原生手势识别器
mod gestures;

/// 全局状态 - 定义 Global trait，用于跨组件共享全局状态
mod global;

/// HTTP 客户端库 - 提供异步 HTTP 请求能力
pub mod http_client;

/// 输入事件 - 定义键盘、鼠标、触摸等输入事件类型
mod input;

/// 检查器 - 开发调试用的 UI 检查工具
mod inspector;

/// 检查器默认面板 - 开箱即用的检查器 UI（检查器打开时可用）
#[cfg(any(feature = "inspector", debug_assertions))]
pub mod inspector_panel;

/// 交互系统 - 定义 Focusable、ClickArea 等交互行为 trait
mod interactive;

/// 键盘事件分发 - 层级化的按键事件处理管线
mod key_dispatch;

/// 快捷键映射 - 定义 Keymap 和 KeyBinding，管理键盘快捷键绑定
mod keymap;

/// 路径构建器 - 链式调用构建路径字符串的工具
mod path_builder;

/// 性能基准测试工具 - 提供帧率和渲染性能的基准测试支持
pub mod perf;

/// 平台抽象层 - 定义 Platform trait，各平台实现此 trait 以提供系统能力
mod platform;

/// 预导入模块 - 常用类型的便捷重导出
pub mod prelude;

/// 性能分析工具 - 任务计时和线程性能追踪
pub mod profiler;

/// 优先级队列 - Windows/Linux/WASM 平台下的异步消息队列
#[cfg(any(target_os = "windows", target_os = "linux", target_family = "wasm"))]
pub mod queue;

mod rgpui_util;

/// 场景系统 - 元素树渲染后的场景描述，用于绘制指令生成
mod scene;

/// 共享字符串 - 引用计数的不可变字符串，降低内存拷贝开销
mod shared_string;

/// 共享 URI - 引用计数的 URI 类型
mod shared_uri;

/// 单实例模式 - 确保应用程序只有一个实例运行
pub mod single_instance;

/// 样式系统 - 定义 Style 结构体，包含布局和视觉属性
mod style;

/// 样式化 trait - 为元素添加链式样式配置的能力
mod styled;

/// 样式扩展 trait - 提供面向组件的补充样式方法（StyledExt、h_flex 等）
mod styled_ext;

/// 尺寸系统 - 定义统一的元素尺寸规格（Size 枚举）
mod size;

/// 订阅系统 - 观察者模式的事件订阅与通知机制
mod subscription;

/// 运行时采样 - Inspector“运行”卡片的数据源（帧率/CPU/内存）与 GPU 信息注册表
pub mod runtime_stats;

/// Taffy 布局引擎封装 - Flexbox 和 Grid 布局的 Rust 实现
mod taffy;

/// 测试支持模块 - 提供测试用的 mock 上下文和工具
#[cfg(any(test, feature = "test-support"))]
pub mod test;

/// 文本系统 - 文本排版、字体管理和 GPU 文本渲染管线
mod text_system;

/// 过渡动画系统 - Transition 组合动画、缓动函数与 Lerp 插值
mod transition;

/// 系统集成子系统 - 托盘、焦点陷阱、Tab 导航、窗口边框/扩展、SVG 渲染
mod system;

// ==================== 第二部分：UI 组件子系统（元素/表单/菜单/对话框/列表/扩展） ====================

/// 根视图 - 窗口顶层视图，管理全局覆盖层
mod root;

/// 对话框组件 - 模态对话框与警告对话框
mod dialog;

/// 菜单组件 - 弹窗菜单、右键菜单、下拉菜单与应用菜单栏
pub mod menu;

/// 表单组件 - 表单容器与表单字段
mod form;

/// 输入组件子系统 - 输入框、文本框、数字输入、掩码输入等
pub mod input_ui;

/// 统一初始化模块 - 聚合所有子系统的初始化调用
mod init;
pub use init::init_all;

/// 索引路径 - 列表/表格中用于定位节、行、列的索引
pub mod index_path;

/// 列表子系统 - 虚拟化列表、ListDelegate、ListState 等
pub mod list;

/// 表格子系统 - 虚拟化数据表格、列定义、表头与表体组件
pub mod table;

/// 标签页子系统 - Tab、TabBar、手风琴与折叠面板组件
pub mod tabs;

/// 标题栏子系统 - 自定义标题栏、窗口控制按钮与客户端装饰边框
pub mod title_bar;

/// 动画子模块 - 值驱动（弹簧）原语 + 上层动画 DSL + 核心动画桥接
pub mod animation;

/// 扩展组件库 - 核心没有的组件 + 动画组件/特效（原 rgpui-ui 并入）
pub mod components;

/// LSP 客户端核心 trait - 补全/悬停/定义/诊断/语义高亮（feature `lsp` 门控）
#[cfg(feature = "lsp")]
pub mod lsp;

/// WebView 组件 - 基于 wry 的网页视图，用于嵌入网页内容（feature `webview` 门控）
#[cfg(feature = "webview")]
pub mod webview;

/// 语法高亮 trait - tree-sitter/syntect 等解析器的抽象层
pub mod highlight;

/// 树形组件 - 分层树视图（文件树、目录树等）
pub mod tree;

/// 鼠标手势识别 - 轻点/双击/长按/拖动/滑动
pub mod mouse_gestures;

/// 滚动物理模型 - 滚动惯性（动量）、减速度与越界回弹
pub mod scroll_physics;

/// 文件监视 API - 监控文件或目录的变化
pub mod file_watcher;

/// 配置持久化 API - 应用配置的加载、保存和监听
pub mod config_store;

/// Chat UI 组件 - 聊天消息展示
pub mod chat;

/// FPS 监控 HUD - 实时帧率/CPU/内存监控
pub mod fps_hud;

/// 国际化 (I18n) 支持 - 多语言文本管理和本地化
pub mod i18n;

/// 主题热重载 - 运行时主题切换和监听
pub mod theme_watcher;

/// 块级渲染组件 - 文档块级元素的渲染支持
pub mod block_render;

/// 虚拟滚动增强 - 支持大量数据的高效渲染
pub mod virtual_scroll;

/// 源码映射支持 - 编辑器位置与源码位置的双向映射
pub mod source_map;

/// Markdown 插件扩展系统 - 支持自定义 Markdown 渲染器
pub mod markdown_ext;

/// Tokio 异步运行时集成 - 在 Tokio 线程池上生成任务并通过 RGPUI 任务返回结果（feature `tokio` 门控）
#[cfg(feature = "tokio")]
pub mod tokio;

/// 工具函数 - 异步超时、延迟执行等通用辅助工具
#[allow(missing_docs)]
pub mod util;

// ==================== 第三部分：视图与窗口 ====================

/// 视图系统 - 定义 View trait 和窗口视图的生命周期管理
mod view;

/// 窗口系统 - 窗口创建、管理、渲染管线和事件处理
mod window;

/// 窗口定位器 - 计算新窗口在屏幕上的初始位置
pub mod window_positioner;

/// 属性测试框架 - 用于基于属性的自动化测试
#[cfg(any(test, feature = "test-support"))]
pub use proptest;

/// 无障碍访问文档模块 - 描述 RGPUI 的无障碍访问架构
#[cfg(doc)]
pub mod _accessibility;

/// 所有权与数据流文档模块 - 描述 RGPUI 的数据所有权模型
#[cfg(doc)]
pub mod _ownership_and_data_flow;

/// 内部私有模块 - 供 rgpui_macros 等过程宏使用的底层依赖
/// 请勿直接使用，此处内容仅供宏展开时引用
#[doc(hidden)]
pub mod private {
    pub use anyhow;
    pub use inventory;
    pub use schemars;
    pub use serde;
    pub use serde_json;
}

/// 密封 trait 机制 - 限制 trait 只能在 rgpui 内部实现
/// 参见: <https://predr.ag/blog/definitive-guide-to-sealed-traits-in-rust/>
mod seal {
    /// 密封 trait，阻止外部 crate 实现此 trait
    pub trait Sealed {}
}

/// 无障碍访问库 - 提供屏幕阅读器等辅助功能的接口
pub use accesskit;
/// 无障碍访问动作类型重导出
pub use accesskit::Action as AccessibleAction;
/// 无障碍访问枚举类型重导出（方向、角色、切换状态）
pub use accesskit::{Orientation, Role, Toggled};

// ==================== 模块重导出 ====================

/// 重导出所有集合类型
pub use crate::collections::*;
/// 重导出所有 Action 相关类型
pub use action::*;
/// 重导出 anyhow::Result 作为统一错误类型
pub use anyhow::Result;
/// 重导出 App 核心模块（App、Context、Entity、EntityId 等）
pub use app::*;
/// 重导出 Arena 分配器内部类型（crate 内部使用）
pub(crate) use arena::*;
/// 重导出资源缓存相关类型
pub use asset_cache::*;
/// 重导出资源加载相关类型
pub use assets::*;
/// 重导出颜色类型（Hsla、Rgba、HslOverride 等）
pub use color::*;
/// 重导出 Web DOM 后端类型（DomNode、DomTree、DomStyle 等）
#[cfg(feature = "dom-backend")]
pub use dom::*;
/// 当 dom-backend 未启用时，提供 DomNodeKey 占位类型，使函数签名编译通过。
#[cfg(not(feature = "dom-backend"))]
pub(crate) type DomNodeKey = ();
pub use theme::color::{ColorName, Colorize, hsl, try_parse_background, try_parse_color};
// 重导出主题色阶函数（red_500、blue_600 等）
/// 重导出 ctor 宏，用于在程序启动前执行初始化函数
pub use ctor::ctor;
/// 重导出元素系统核心类型
pub use element::*;
/// 重导出所有内置元素类型
pub use elements::*;
/// 重导出执行器类型（ForegroundExecutor、BackgroundExecutor）
pub use executor::*;
/// 重导出几何类型（Point、Size、Bounds 等）
pub use geometry::*;
/// 重导出手势识别相关类型
pub use gestures::*;
/// 重导出全局状态相关类型
pub use global::*;
/// 重导出 rgpui_macros 中的过程宏（AppContext、IntoElement、Render 等）
pub use rgpui_macros::{
    AppContext, IntoElement, Render, VisualContext, bench, icon_named, property_test,
    register_action, test,
};
/// 重导出焦点陷阱能力（FocusTrapElement、FocusTrapContainer）
pub use system::focus_trap::*;
pub use theme::registry::DEFAULT_THEME_COLORS;
pub use theme::{
    ActiveTheme, HighlightTheme, HighlightThemeStyle, ListSettings, NotificationSettings,
    ScrollbarShow, SheetSettings, StatusColors, SyntaxColors, TITLE_BAR_HEIGHT, Theme, ThemeColor,
    ThemeConfig, ThemeConfigColors, ThemeMode, ThemeRegistry, ThemeSet, ThemeToken, ThemeTokens,
};
pub use theme::{
    amber_50, amber_100, amber_200, amber_300, amber_400, amber_500, amber_600, amber_700,
    amber_800, amber_900, amber_950, blue_50, blue_100, blue_200, blue_300, blue_400, blue_500,
    blue_600, blue_700, blue_800, blue_900, blue_950, cyan_50, cyan_100, cyan_200, cyan_300,
    cyan_400, cyan_500, cyan_600, cyan_700, cyan_800, cyan_900, cyan_950, emerald_50, emerald_100,
    emerald_200, emerald_300, emerald_400, emerald_500, emerald_600, emerald_700, emerald_800,
    emerald_900, emerald_950, fuchsia_50, fuchsia_100, fuchsia_200, fuchsia_300, fuchsia_400,
    fuchsia_500, fuchsia_600, fuchsia_700, fuchsia_800, fuchsia_900, fuchsia_950, gray_50,
    gray_100, gray_200, gray_300, gray_400, gray_500, gray_600, gray_700, gray_800, gray_900,
    gray_950, green_50, green_100, green_200, green_300, green_400, green_500, green_600,
    green_700, green_800, green_900, green_950, indigo_50, indigo_100, indigo_200, indigo_300,
    indigo_400, indigo_500, indigo_600, indigo_700, indigo_800, indigo_900, indigo_950, lime_50,
    lime_100, lime_200, lime_300, lime_400, lime_500, lime_600, lime_700, lime_800, lime_900,
    lime_950, neutral_50, neutral_100, neutral_200, neutral_300, neutral_400, neutral_500,
    neutral_600, neutral_700, neutral_800, neutral_900, neutral_950, orange_50, orange_100,
    orange_200, orange_300, orange_400, orange_500, orange_600, orange_700, orange_800, orange_900,
    orange_950, pink_50, pink_100, pink_200, pink_300, pink_400, pink_500, pink_600, pink_700,
    pink_800, pink_900, pink_950, purple_50, purple_100, purple_200, purple_300, purple_400,
    purple_500, purple_600, purple_700, purple_800, purple_900, purple_950, red_50, red_100,
    red_200, red_300, red_400, red_500, red_600, red_700, red_800, red_900, red_950, rose_50,
    rose_100, rose_200, rose_300, rose_400, rose_500, rose_600, rose_700, rose_800, rose_900,
    rose_950, sky_50, sky_100, sky_200, sky_300, sky_400, sky_500, sky_600, sky_700, sky_800,
    sky_900, sky_950, slate_50, slate_100, slate_200, slate_300, slate_400, slate_500, slate_600,
    slate_700, slate_800, slate_900, slate_950, stone_50, stone_100, stone_200, stone_300,
    stone_400, stone_500, stone_600, stone_700, stone_800, stone_900, stone_950, teal_50, teal_100,
    teal_200, teal_300, teal_400, teal_500, teal_600, teal_700, teal_800, teal_900, teal_950,
    violet_50, violet_100, violet_200, violet_300, violet_400, violet_500, violet_600, violet_700,
    violet_800, violet_900, violet_950, yellow_50, yellow_100, yellow_200, yellow_300, yellow_400,
    yellow_500, yellow_600, yellow_700, yellow_800, yellow_900, yellow_950, zinc_50, zinc_100,
    zinc_200, zinc_300, zinc_400, zinc_500, zinc_600, zinc_700, zinc_800, zinc_900, zinc_950,
};

/// 定义用于标注了 `#[rgpui::bench]` 的基准测试的 Criterion 基准测试组。
///
/// 这镜像了 `criterion::criterion_group!`，使 RGPUI 基准测试文件可以保持与普通
/// Criterion 基准测试相同的形式。
///
/// [`rgpui::bench`]: crate::bench
#[macro_export]
macro_rules! bench_group {
    ($($tokens:tt)*) => {
        criterion::criterion_group!($($tokens)*);
    };
}

/// 定义 RGPUI Criterion 基准测试组的入口点。
///
/// 这镜像了 `criterion::criterion_main!`，使 RGPUI 基准测试文件可以保持与普通
/// Criterion 基准测试相同的形式。
#[macro_export]
macro_rules! bench_main {
    ($($tokens:tt)*) => {
        criterion::criterion_main!($($tokens)*);
    };
}

/// 重导出 ArcCow - 引用计数的写时复制智能指针
pub use rgpui_util::arc_cow::ArcCow;
/// 重导出 SharedString 相关类型
pub use shared_string::*;

// rgpui_util::Deferred 与 elements 中的 Deferred 冲突，因此不直接导出 rgpui_util 中的 Deferred
/// 重导出精化类型（Refined、Incomplete 等部分初始化类型）
pub use crate::refineable::*;
/// 重导出输入事件相关类型
pub use input::*;
/// 重导出检查器相关类型
pub use inspector::*;
/// 重导出检查器默认面板（检查器打开时可用）
#[cfg(any(feature = "inspector", debug_assertions))]
pub use inspector_panel::{
    InspectorHeaderSlot, InspectorPanelSlots, InspectorSectionSlot, default_inspector_header,
    default_inspector_panel, default_inspector_section, render_div_inspector_state,
};
/// 重导出交互系统相关类型（Focusable、ClickArea 等）
pub use interactive::*;
use key_dispatch::*;
/// 重导出快捷键映射相关类型
pub use keymap::*;
/// 重导出路径构建器
pub use path_builder::*;
/// 重导出平台抽象层相关类型
pub use platform::*;
/// 重导出性能分析工具
pub use profiler::*;
/// 重导出优先级队列类型（仅 Windows/Linux/WASM）
#[cfg(any(target_os = "windows", target_os = "linux", target_family = "wasm"))]
pub use queue::{PriorityQueueReceiver, PriorityQueueSender};
/// 重导出 rgpui_util 中的常用工具（defer、log_err、measure 等）
pub use rgpui_util::{
    Deferred as UtilDeferred, ResultExt, TryFutureExt, TryFutureExtBacktrace, defer, log_err,
    measure, post_inc, some_or_debug_panic,
};
/// 重导出场景系统相关类型
pub use scene::*;
/// 重导出共享 URI 类型
pub use shared_uri::*;
/// 重导出单实例管理相关类型
pub use single_instance::*;
use std::{any::Any, future::Future};
/// 重导出样式类型（Style、Display、Position 等）
pub use style::*;
/// 重导出样式化 trait
pub use styled::*;
pub use styled_ext::*;

/// 重导出过渡动画系统
pub use transition::*;

/// 重导出对话框组件
pub use dialog::*;
/// 重导出表单组件
pub use form::*;
/// 重导出索引路径类型
pub use index_path::*;
/// 重导出菜单组件
pub use menu::*;
/// 重导出根视图
pub use root::*;
/// 重导出运行时采样类型（GpuInfo、set_gpu_info 等）
pub use runtime_stats::{GpuInfo, gpu_info, set_gpu_info};
pub use size::*;
/// 重导出订阅系统类型（Subscription、SubscriberSet 等）
pub use subscription::*;
/// 重导出 SVG 渲染器相关类型
pub use system::svg_renderer::*;
/// 重导出 Tab 停止位计算（crate 内部使用）
pub(crate) use system::tab_stop::*;
/// 重导出系统托盘相关类型
pub use system::tray::*;
/// 重导出窗口边框工具
pub use system::window_border::*;
/// 重导出窗口扩展 trait
pub use system::window_ext::*;
use taffy::TaffyLayoutEngine;
/// 重导出 Taffy 布局引擎类型（AvailableSpace、LayoutId）
pub use taffy::{AvailableSpace, LayoutId};
/// 重导出测试支持工具
#[cfg(any(test, feature = "test-support"))]
pub use test::*;
/// 重导出文本系统相关类型
pub use text_system::*;
/// 重导出异步工具（FutureExt、Timeout）与字符串安全切片（SafeStrSlice）
pub use util::{FutureExt, SafeStrSlice, Timeout};
/// 重导出视图系统类型
pub use view::*;
/// 重导出窗口系统类型
pub use window::*;

/// 重导出 pollster::block_on 用于在同步上下文中阻塞等待异步任务
pub use pollster::block_on;

/// 应用上下文 trait - RGPUI 中最核心的 trait，允许不同的上下文类型在某些操作中互换使用。
///
/// 该 trait 提供了以下核心能力：
/// - **实体管理**：创建（`new`）、更新（`update_entity`）、读取（`read_entity`）实体
/// - **窗口操作**：更新窗口（`update_window`）、获取当前窗口（`with_window`）
/// - **后台任务**：在后台线程上生成异步任务（`background_spawn`）
/// - **全局状态**：读取全局值（`read_global`）
///
/// # 实现说明
///
/// 主要实现者包括：
/// - [`App`] - 应用级别的上下文
/// - [`Window`] - 窗口级别的上下文
/// - [`Context<T>`] - 实体级别的上下文
pub trait AppContext {
    /// 在应用上下文中创建新实体。
    ///
    /// 通过闭包 `build_entity` 构建实体的初始状态，闭包会收到一个 `Context<T>`，
    /// 用于在实体创建过程中进行事件订阅、子实体创建等操作。
    ///
    /// # 参数
    /// * `build_entity` - 构建实体的闭包，接收 `Context<T>`，返回实体实例 `T`
    ///
    /// # 返回值
    /// 返回新创建的实体句柄 `Entity<T>`
    #[expect(
        clippy::wrong_self_convention,
        reason = "`App::new` is an ubiquitous function for creating entities"
    )]
    fn new<T: 'static>(&mut self, build_entity: impl FnOnce(&mut Context<T>) -> T) -> Entity<T>;

    /// 为稍后插入的实体预留一个槽位。
    ///
    /// 返回的 [`Reservation`] 允许你在实体实际创建之前就获取其 [`EntityId`]，
    /// 这在需要预先知道实体 ID 的场景下非常有用（如循环创建实体时避免借用冲突）。
    fn reserve_entity<T: 'static>(&mut self) -> Reservation<T>;

    /// 基于之前从 [`reserve_entity`] 获得的 [`Reservation`] 在应用上下文中插入新实体。
    ///
    /// 与 `new` 不同，`insert_entity` 使用之前预留的槽位来存储实体，
    /// 确保预留时获取的 EntityId 与最终创建的实体一致。
    ///
    /// [`reserve_entity`]: Self::reserve_entity
    fn insert_entity<T: 'static>(
        &mut self,
        reservation: Reservation<T>,
        build_entity: impl FnOnce(&mut Context<T>) -> T,
    ) -> Entity<T>;

    /// 更新应用上下文中的实体。
    ///
    /// 通过闭包 `update` 获取实体的可变引用和上下文，对实体进行修改。
    /// 闭包的返回值会作为 `update_entity` 的返回值传递出去。
    fn update_entity<T, R>(
        &mut self,
        handle: &Entity<T>,
        update: impl FnOnce(&mut T, &mut Context<T>) -> R,
    ) -> R
    where
        T: 'static;

    /// 获取实体的可变借用句柄（`GpuiBorrow`），用于需要长时间持有可变引用的场景。
    ///
    /// 返回的 `GpuiBorrow` 实现了 `Deref` 和 `DerefMut`，
    /// 允许直接操作实体数据。
    fn as_mut<'a, T>(&'a mut self, handle: &Entity<T>) -> GpuiBorrow<'a, T>
    where
        T: 'static;

    /// 从应用上下文中读取实体。
    ///
    /// 通过闭包 `read` 获取实体的不可变引用和 App 句柄，进行只读操作。
    /// 与 `update_entity` 不同，此方法不会修改实体状态。
    fn read_entity<T, R>(&self, handle: &Entity<T>, read: impl FnOnce(&T, &App) -> R) -> R
    where
        T: 'static;

    /// 更新给定句柄的窗口。
    ///
    /// 闭包接收三个参数：窗口的 AnyView、可变 Window 引用、可变 App 引用。
    /// 通过此方法可以修改窗口内容、替换根视图等。
    fn update_window<T, F>(&mut self, window: AnyWindowHandle, f: F) -> Result<T>
    where
        F: FnOnce(AnyView, &mut Window, &mut App) -> T;

    /// 对实体的*当前*窗口运行闭包 `f`。
    ///
    /// "当前窗口"指实体最近一次被渲染到的窗口。如果实体没有当前窗口或该窗口不可用，
    /// 则返回 `None`。
    ///
    /// 参见 [`App::with_window`] 了解底层查找逻辑。
    fn with_window<R>(
        &mut self,
        entity_id: EntityId,
        f: impl FnOnce(&mut Window, &mut App) -> R,
    ) -> Option<R>;

    /// 从应用上下文中读取窗口。
    ///
    /// 通过窗口句柄获取实体和 App 的不可变引用，进行只读操作。
    fn read_window<T, R>(
        &self,
        window: &WindowHandle<T>,
        read: impl FnOnce(Entity<T>, &App) -> R,
    ) -> Result<R>
    where
        T: 'static;

    /// 在后台线程上生成异步任务。
    ///
    /// 生成的 Future 会在后台线程池中执行，不阻塞前台 UI。
    /// 返回的 [`Task`] 可用于等待任务完成或取消任务。
    fn background_spawn<R>(&self, future: impl Future<Output = R> + Send + 'static) -> Task<R>
    where
        R: Send + 'static;

    /// 从此应用上下文中读取全局值。
    ///
    /// 全局值通过 [`Global`] trait 标记，通常是应用级别的单例状态
    /// （如主题配置、全局设置等）。
    fn read_global<G, R>(&self, callback: impl FnOnce(&G, &App) -> R) -> R
    where
        G: Global;
}

/// 实体预留槽位 - 由 [`Context::reserve_entity`] 返回，用于稍后传递给 [`Context::insert_entity`]。
///
/// 允许你在实体创建之前获取其 [`EntityId`]，解决了循环引用场景下
/// 实体 ID 不可预知的问题。
pub struct Reservation<T>(pub(crate) Slot<T>);

impl<T: 'static> Reservation<T> {
    /// 返回实体插入后将关联的 [`EntityId`]。
    ///
    /// 此 ID 在预留时就已确定，即使实体尚未实际创建。
    pub fn entity_id(&self) -> EntityId {
        self.0.entity_id()
    }
}

/// 可视化上下文 trait - RGPUI 中需要窗口才能运行的上下文类型。
///
/// 该 trait 扩展了 [`AppContext`]，添加了窗口特定的操作：
/// - 创建窗口级别的实体
/// - 替换窗口的根视图
/// - 聚焦特定实体
///
/// # 主要实现者
/// - [`Window`] - 窗口上下文
/// - [`WindowContext`] - 窗口上下文的便捷别名
pub trait VisualContext: AppContext {
    /// 窗口操作的结果类型。在同步上下文中为 `T`，在异步上下文中为 `Task<T>`。
    type Result<T>;

    /// 返回与此上下文关联的窗口句柄。
    fn window_handle(&self) -> AnyWindowHandle;

    /// 使用给定回调更新窗口中的实体。
    ///
    /// 闭包可以同时访问实体数据和窗口，适用于需要同时操作 UI 和窗口的场景。
    fn update_window_entity<T: 'static, R>(
        &mut self,
        entity: &Entity<T>,
        update: impl FnOnce(&mut T, &mut Window, &mut Context<T>) -> R,
    ) -> Self::Result<R>;

    /// 创建新实体，并可访问窗口。
    ///
    /// 新创建的实体可以订阅窗口事件、操作窗口内容等。
    fn new_window_entity<T: 'static>(
        &mut self,
        build_entity: impl FnOnce(&mut Window, &mut Context<T>) -> T,
    ) -> Self::Result<Entity<T>>;

    /// 用新视图替换窗口的根视图。
    ///
    /// 新视图会成为窗口的主要内容，旧视图将被丢弃。
    /// 视图必须实现 [`Render`] trait。
    fn replace_root_view<V>(
        &mut self,
        build_view: impl FnOnce(&mut Window, &mut Context<V>) -> V,
    ) -> Self::Result<Entity<V>>
    where
        V: 'static + Render;

    /// 聚焦窗口中的实体，前提是该实体实现了 [`Focusable`] trait。
    ///
    /// 聚焦后，该实体将成为键盘事件的主要接收者。
    fn focus<V>(&mut self, entity: &Entity<V>) -> Self::Result<()>
    where
        V: Focusable;
}

/// 事件发射器 trait - 用于绑定实体类型与其可发出的事件类型。
///
/// 实现此 trait 的实体可以通过上下文的 `emit` 方法发出指定类型的事件，
/// 其他组件可以通过 `subscribe` 方法监听这些事件。
///
/// # 示例
///
/// ```rust,ignore
/// struct MyEntity { /* ... */ }
///
/// struct MyEvent { data: String }
///
/// impl EventEmitter<MyEvent> for MyEntity {}
/// ```
pub trait EventEmitter<E: Any>: 'static {}

/// 应用上下文借用 trait - 为可以互换使用的上下文自动实现全局状态管理方法。
///
/// 此 trait 为所有实现了 `BorrowMut<App>` 的类型提供了：
/// - `set_global` - 设置全局值
/// - `update_global` - 更新全局值
/// - `update_default_global` - 更新全局值，不存在则创建默认值
pub trait BorrowAppContext {
    /// 在上下文中设置全局值。
    fn set_global<T: Global>(&mut self, global: T);

    /// 更新给定类型的全局状态。
    ///
    /// 通过闭包 `f` 获取全局值的可变引用和当前上下文的可变引用，
    /// 闭包返回值会作为 `update_global` 的返回值传递出去。
    fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
    where
        G: Global;

    /// 更新给定类型的全局状态，如果之前不存在则先创建默认值。
    ///
    /// 适用于需要确保全局状态一定存在的场景。
    fn update_default_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
    where
        G: Global + Default;
}

impl<C> BorrowAppContext for C
where
    C: std::borrow::BorrowMut<App>,
{
    fn set_global<G: Global>(&mut self, global: G) {
        self.borrow_mut().set_global(global)
    }

    #[track_caller]
    fn update_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
    where
        G: Global,
    {
        // 通过租赁机制获取全局值的可变引用，避免长时间持有借用
        let mut global = self.borrow_mut().lease_global::<G>();
        let result = f(&mut global, self);
        // 归还租赁的全局值
        self.borrow_mut().end_global_lease(global);
        result
    }

    fn update_default_global<G, R>(&mut self, f: impl FnOnce(&mut G, &mut Self) -> R) -> R
    where
        G: Global + Default,
    {
        // 确保全局值已初始化
        self.borrow_mut().default_global::<G>();
        self.update_global(f)
    }
}

/// GPU 规格信息 - 描述 rgpui 运行所在的 GPU 硬件信息。
///
/// 包含 GPU 是否为软件模拟、设备名称、驱动程序名称和详细信息。
/// 可通过 [`App::gpu_specs`] 方法获取。
#[derive(Default, Debug, serde::Serialize, serde::Deserialize, Clone)]
pub struct GpuSpecs {
    /// GPU 是否为软件模拟（如 `llvmpipe`）在 CPU 上运行。
    /// 当此值为 `true` 时，渲染性能可能显著下降。
    pub is_software_emulated: bool,
    /// 设备名称，由 Vulkan/OpenGL 报告（如 "NVIDIA GeForce RTX 3080"）。
    pub device_name: String,
    /// 驱动程序名称，由 Vulkan/OpenGL 报告。
    pub driver_name: String,
    /// 驱动程序详细信息，由 Vulkan/OpenGL 报告（如版本号等）。
    pub driver_info: String,
}