docs(frame): clarify safe-area env injection

CHANGELOG.md

@@ -109,6 +109,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 
+- `@devicekit/frame`: clarified that safe-area attributes and `deviceProfile.safeAreaInsets` update frame metrics, CSS custom properties and rendering, but do not inject native CSS `env(safe-area-inset-*)` values into slotted or separately hosted pages; Electron/Chromium hosts must apply their own CDP override when they need native `env()` simulation.
 - Corrected the direction of `ContentRect.scale`, what `embedded` zeroes, what a `<device-frame>` with no `device` renders, what `tab-bar-height="0"` does, and which device fields every device actually carries.
 - Spelled out that `embedded` and `immersive` behave like `hidden`: presence is truth as an attribute, but a JS-truthy check as a property, so `embedded=""` reads as false through the property setter — pass `embedded={true}` (or the bare `embedded` shorthand) in React, not `embedded=""`, since React 18 and React 19 disagree on what an empty string means there.
 - Documented that without a `ResizeObserver` (old WebViews, jsdom by default) the element does not re-measure on its own; call `refreshContentRect()` after layout changes.

packages/frame/README.md

@@ -192,7 +192,9 @@ Use these variables to change the frame appearance:
 
 If `--device-frame-border` changes the border width, set `--device-frame-border-width` to the same width so the radius calculation remains aligned.
 
-These variables do not change browser values such as `env(safe-area-inset-top)`. A page in the default slot must read the `--device-safe-area-*` variables or receive the values from its host.
+`<device-frame safe-area-bottom="30">` overrides the bottom safe-area inset. Setting `safeAreaInsets.bottom: 30` in `deviceProfile` does the same. Both update `metrics.safeAreaInsets.bottom` and `--device-safe-area-bottom`, and change the element's own bottom safe-area and home-indicator rendering.
+
+This does not change native CSS `env()`. Content in the default slot can read `var(--device-safe-area-bottom)`, but `env(safe-area-inset-bottom)` there does not become `30px`. A separate document, such as a page in an iframe or `WebContentsView`, cannot read the host element's custom property, so its host must pass the value to it. To change native `env()` in an Electron/Chromium page, the host can inject the value with CDP `Emulation.setSafeAreaInsetsOverride`. `@devicekit/frame` neither manages those pages nor performs CDP injection; a web-only host has no equivalent.
 
 ## Content rectangle events
 

packages/frame/README.zh-CN.md

@@ -350,7 +350,9 @@ frame 只帮这个槽让开状态栏。**横屏时它不处理左右安全区**
 
 外观也留了几个变量可以盖：`--device-frame-radius`（盖过机型自己的机身圆角，现在同时驱动机身和屏幕两处圆角，屏幕会自动跟着收窄描边和内边距那部分；只接受 CSS `<length>`——百分比会被浏览器各自相对两个盒子单独解析，机身和屏幕就不再共享同一个圆心，这个变量也就不再是"同心一个圆角"的意思了）、`--device-frame-border`、`--device-frame-background`、`--device-frame-shadow`、`--device-cutout-color`（刘海/灵动岛/挖孔的颜色）、`--device-screen-background`（屏幕上没被 slot 盖住的地方显示什么——状态栏默认透明，没有 `navigation-bar` slot 时时钟那一条露出来的就是它；默认白色，暗色页面要把它设成页面自己的背景色，否则白色状态栏文字没东西衬）。机身默认是近黑色（`#0b0b0c`）配一圈极淡的白色描边，`--device-bezel` 按平台取默认值（iOS 6、Android/HarmonyOS 4），单个机型可以在 `shell.bezel` 里覆盖。改 `--device-frame-border` 顺带把描边宽度也改了的话，必须同步设置 `--device-frame-border-width`，否则圆角公式还是按旧的默认宽度算。
 
-**它只给数值，不改 `env(safe-area-inset-*)`。** 被预览的页面里那句 `env(safe-area-inset-top)` 拿到的仍然是 0，因为浏览器不让 JS 改这个值。要让页面里的 `env()` 真的返回 59，只有 Electron / Chromium 能做到，走 CDP 的 `Emulation.setSafeAreaInsetsOverride`：宿主给被预览页面挂上调试器，把这里算出来的边距喂进去就行。纯 web 宿主没有对应能力，只能让被预览的页面改读上面那几个 CSS 变量。
+`<device-frame safe-area-bottom="30">` 会覆盖底部安全区；在 `deviceProfile` 里设置 `safeAreaInsets.bottom: 30` 也一样。它会更新 `metrics.safeAreaInsets.bottom`、`--device-safe-area-bottom`，并让元素自身按这个安全区绘制底部区域和手势条。
+
+**这不等于改了原生 CSS `env()`。** 插槽内容可以读 `var(--device-safe-area-bottom)`，但其中的 `env(safe-area-inset-bottom)` 仍不会变成 `30px`。独立文档（例如 iframe 或 `WebContentsView` 里的页面）拿不到宿主元素的变量，需要宿主传入这个值；若要改变 Electron/Chromium 页面里的原生 `env()`，宿主可通过 CDP `Emulation.setSafeAreaInsetsOverride` 注入。`@devicekit/frame` 本身不管理这些页面，也不执行 CDP 注入；纯 web 宿主没有对应能力。
 
 ## 用 webview 装内容