`env`

env 提供 guest 无法自行观察、但应用确实需要的宿主环境状态。字段按信任档位粗化并以一致快照返回，避免应用分别探测多个高熵平台细节。

基本示例

let environment = await host.env.snapshot();
applyTheme(environment.colorScheme);
applySafeArea(environment.safeArea);

host.events.on('env.change', async ({ changedFields }) => {
  if (!changedFields.includes('colorScheme')) return;
  environment = await host.env.snapshot();
  applyTheme(environment.colorScheme);
});

变化事件只告诉 guest 哪些字段失效；重新读取快照可以避免多个字段来自不同时刻。

适用场景

深浅色主题、语言和粗化时区。
无障碍偏好，如减少动态效果或提高对比度。
绘图面的安全区域。
只用于 UI 提示的粗化连接状态。

设备型号、User-Agent、CPU/GPU、内存、序列号、字体枚举、精确网络类型和稳定硬件标识不属于 env。

能力声明

{
  "capabilities": ["host:env.snapshot"]
}

Reference

env.snapshot()
env.change event

env.snapshot() -> EnvironmentSnapshot

event env.change {
  changedFields: EnvironmentField[]
}

EnvironmentSnapshot {
  colorScheme: "light" | "dark"
  locale: bounded-locale
  timeZone: bounded-time-zone
  accessibility: {
    reducedMotion: boolean
    increasedContrast: boolean
  }
  connectivity: "offline" | "online" | "unknown"
  safeArea: { top, right, bottom, left }
  precision: "exact" | "coarse"
}

online 只表示宿主认为网络路径可能可用，不保证特定服务可达。

原生 WASM 示例

EnvironmentSnapshot env = host_env_snapshot();
ui_set_dark_mode(env.color_scheme == COLOR_DARK);
ui_set_reduced_motion(env.accessibility.reduced_motion);

字符串通过有界 UTF-8 绑定返回；未知枚举必须映射为规范的 unknown，不能把浏览器原始字符串穿透给 guest。

精度规则

green 应用的 locale 可以只保留语言或语言—文字，时区可以粗化为 UTC offset。
更高档位是否提供更具体值由宿主策略决定，并在 precision 中如实标明。
颜色方案和无障碍布尔偏好属于用户与本应用的直接 UI 上下文。
安全区域使用当前应用绘图面的逻辑像素，不泄露屏幕绝对尺寸。

事件与生命周期

change 可以合并多个字段，也可以合并短时间内的重复变化。
guest 不应从事件次数推断用户行为。
应用恢复前台时宿主可以只发一次综合变化。
快照内部字段必须来自同一逻辑时点或有明确一致性规则。

安全与预算

信任档位：green；入向 flow 如实标记，provenance 为 app-context。
字段集合封闭；新增高熵字段必须进入新版本并重新做指纹评审。
snapshot 和变化事件都有时间窗预算。
不提供可用来构造高精度计时器的时间戳。
宿主不得为追踪目的故意制造每应用不同的环境值。

错误与测试

env.snapshot 通常不会因单个字段不可用而整体失败；该字段使用安全默认或 unknown。一致性测试至少覆盖主题切换、语言/时区粗化、安全区域、后台恢复、事件合并、未知平台值和不同信任档位的信息量。