Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(native): keep authored UI inside live device safe areas

yhh06366d08ca46
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8328cf0d9..db900365d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Native UI follows the device safe area.** iOS view insets and Android content bounds reach `SafeArea` in surface pixels, including delayed layouts and landscape side changes. The localization sample places its text and controls inside an authored safe-area container so the iPhone cutout does not cover the paragraph.
+
- **The installed macOS MCP entry launches the bundled editor.** It reads `CFBundleExecutable` from the app's Info.plist instead of assuming the product name matches the executable file.
- **Saving Prefab instances preserves authored draw order.** Collapsed instances keep their root's position among ordinary entities instead of moving to the end of the scene. Unresolved instances also retain their original positions.
diff --git a/docs/astro/src/content/docs/ui/widgets.mdx b/docs/astro/src/content/docs/ui/widgets.mdx
index 33e5a71f0..63b2deeed 100644
--- a/docs/astro/src/content/docs/ui/widgets.mdx
+++ b/docs/astro/src/content/docs/ui/widgets.mdx
@@ -423,6 +423,11 @@ Add `SafeArea` to a full-screen, absolutely-positioned `UINode` container and it
insets track the platform safe area — notches, rounded corners, the WeChat capsule —
with per-edge opt-outs. See **[Screen & Resolution](/docs/core-concepts/screen/)**.
+Native iOS and Android hosts supply live content insets in surface pixels,
+including landscape rotation and layout changes. Put the content container under
+the Canvas; the world and backgrounds can still fill the whole screen. The
+`ui-localization-debug` example authors this container around its text and controls.
+
## Theming
Widget colors come from a shared token set with roles like `surface`, `control`,
diff --git a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx
index cad78928e..de81dfa71 100644
--- a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx
@@ -382,6 +382,10 @@ Enter/Space 激活,滑块接管方向键,聚焦的控件显示其 `focused` 交
刘海、圆角、微信胶囊——并支持按边退出。见
**[屏幕与分辨率](/docs/zh-cn/core-concepts/screen/)**。
+原生 iOS 和 Android 宿主以渲染表面像素提供实时内容边距,跟随横屏旋转和布局变化。
+把内容容器放在 Canvas 下,世界和背景仍可铺满屏幕。
+`ui-localization-debug` 示例为文字和控件配置了这个容器。
+
## 主题
控件颜色来自共享的 token 集,角色如 `surface`、`control`、`primary`、`track`;
diff --git a/examples/ui-localization-debug/assets/scenes/main.esscene b/examples/ui-localization-debug/assets/scenes/main.esscene
index 6d5e6e738..c093b469e 100644
--- a/examples/ui-localization-debug/assets/scenes/main.esscene
+++ b/examples/ui-localization-debug/assets/scenes/main.esscene
@@ -34,18 +34,7 @@
"name": "Canvas",
"parent": null,
"children": [
- 2,
- 3,
- 4,
- 5,
- 6,
- 7,
- 8,
- 9,
- 10,
- 11,
- 12,
- 13
+ 14
],
"visible": true,
"components": [
@@ -72,7 +61,7 @@
{
"id": 2,
"name": "Title",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -122,7 +111,7 @@
{
"id": 3,
"name": "English",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -174,7 +163,7 @@
{
"id": 4,
"name": "Chinese",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -224,7 +213,7 @@
{
"id": 5,
"name": "Japanese",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -274,7 +263,7 @@
{
"id": 6,
"name": "Korean",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -324,7 +313,7 @@
{
"id": 7,
"name": "Arabic — shaping unverified",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -374,7 +363,7 @@
{
"id": 8,
"name": "Thai — shaping unverified",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -424,7 +413,7 @@
{
"id": 9,
"name": "Wrapped paragraph",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -475,7 +464,7 @@
{
"id": 10,
"name": "Preview status",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -525,7 +514,7 @@
{
"id": 11,
"name": "LocaleButton",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -600,7 +589,7 @@
{
"id": 12,
"name": "PseudoButton",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -675,7 +664,7 @@
{
"id": 13,
"name": "WidthButton",
- "parent": 1,
+ "parent": 14,
"children": [],
"visible": true,
"components": [
@@ -746,6 +735,42 @@
"type": "Focusable"
}
]
+ },
+ {
+ "id": 14,
+ "name": "Safe Content",
+ "parent": 1,
+ "children": [
+ 2,
+ 3,
+ 4,
+ 5,
+ 6,
+ 7,
+ 8,
+ 9,
+ 10,
+ 11,
+ 12,
+ 13
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1
+ }
+ },
+ {
+ "type": "SafeArea",
+ "data": {}
+ }
+ ]
}
]
}
diff --git a/native/host/Host.hpp b/native/host/Host.hpp
index 26294d2dd..1c49fcfd3 100644
--- a/native/host/Host.hpp
+++ b/native/host/Host.hpp
@@ -185,6 +185,10 @@ struct Platform {
virtual esengine::WebGPUDevice::NativeSurface surface() = 0;
virtual void surfaceSize(esengine::u32& width, esengine::u32& height) = 0;
+ /** Content must stay inside these live margins, in surface pixels. */
+ struct SafeInsets { float top = 0; float bottom = 0; float left = 0; float right = 0; };
+ virtual SafeInsets safeAreaInsets() const { return {}; }
+
virtual void log(bool error, const char* message) = 0;
/** A font for @p family that covers @p codepoint, with @p style's bold/italic
diff --git a/native/host/bindings/RenderBindings.cpp b/native/host/bindings/RenderBindings.cpp
index 5bfc8441a..e0f692dfb 100644
--- a/native/host/bindings/RenderBindings.cpp
+++ b/native/host/bindings/RenderBindings.cpp
@@ -139,6 +139,18 @@ JSValue js_renderer_surfaceSize(JSContext* ctx, JSValueConst, int, JSValueConst*
return o;
}
+// OS content insets in the same pixel domain as the rendered surface.
+JSValue js_safeAreaInsets(JSContext* ctx, JSValueConst, int, JSValueConst*) {
+ const auto insets = hostAlive() && host().platform
+ ? host().platform->safeAreaInsets() : Platform::SafeInsets{};
+ JSValue o = JS_NewObject(ctx);
+ JS_SetPropertyStr(ctx, o, "top", JS_NewFloat64(ctx, insets.top));
+ JS_SetPropertyStr(ctx, o, "bottom", JS_NewFloat64(ctx, insets.bottom));
+ JS_SetPropertyStr(ctx, o, "left", JS_NewFloat64(ctx, insets.left));
+ JS_SetPropertyStr(ctx, o, "right", JS_NewFloat64(ctx, insets.right));
+ return o;
+}
+
// es_setWindowSize(w, h): the project's design resolution, which only the SDK can
// read (the window exists before any JS, and the host parses no JSON). A platform
// that is GIVEN its screen ignores it.
@@ -173,6 +185,7 @@ void registerRenderBindings(HostState& h, JSValue global) {
bindGlobal(h, global, "es_getTextureDimensions", js_getTextureDimensions, 1);
bindGlobal(h, global, "es_rasterizeGlyph", js_rasterizeGlyph, 1);
bindGlobal(h, global, "es_renderer_surfaceSize", js_renderer_surfaceSize, 0);
+ bindGlobal(h, global, "es_safeAreaInsets", js_safeAreaInsets, 0);
bindGlobal(h, global, "es_setWindowSize", js_setWindowSize, 2);
bindGlobal(h, global, "es_registry_getCameraEntities", js_registry_getCameraEntities, 0);
}
diff --git a/native/host/platform/android.cpp b/native/host/platform/android.cpp
index f552298f9..78aced9e3 100644
--- a/native/host/platform/android.cpp
+++ b/native/host/platform/android.cpp
@@ -167,6 +167,15 @@ void performHttp(JNIEnv* env, const eshost::FetchRequest& req, eshost::FetchResu
struct AndroidPlatform final : eshost::Platform {
AAssetManager* assets = nullptr; // APK assets/ — the game + its content
ANativeWindow* window = nullptr;
+ ARect contentRect{};
+
+ SafeInsets safeAreaInsets() const override {
+ if (!window || contentRect.right <= contentRect.left || contentRect.bottom <= contentRect.top) return {};
+ const int width = ANativeWindow_getWidth(window), height = ANativeWindow_getHeight(window);
+ const auto clamp = [](int value, int limit) { return (float)(value < 0 ? 0 : value > limit ? limit : value); };
+ return { clamp(contentRect.top, height), clamp(height - contentRect.bottom, height),
+ clamp(contentRect.left, width), clamp(width - contentRect.right, width) };
+ }
JavaVM* vm = nullptr; // for JNI HttpURLConnection off-thread
std::string cache; // getCacheDir() — the system may reclaim it
std::string data; // internalDataPath — files/, survives
@@ -493,6 +502,9 @@ void framesSurface(bool has);
void framesResumed(bool is);
void onAppCmd(android_app* app, int32_t cmd) {
+ // NativeActivity supplies a content rectangle in window pixels; the glue
+ // updates it before delivering CONTENT_RECT_CHANGED, including rotation.
+ g_platform.contentRect = app->contentRect;
switch (cmd) {
case APP_CMD_INIT_WINDOW:
// First time: boot the engine. Afterwards (screen-on): just rebind the
diff --git a/native/host/platform/ios.mm b/native/host/platform/ios.mm
index f428f8bd9..fcdd05aff 100644
--- a/native/host/platform/ios.mm
+++ b/native/host/platform/ios.mm
@@ -47,6 +47,8 @@ using esengine::WebGPUDevice;
namespace {
struct IOSPlatform final : eshost::Platform {
+ SafeInsets contentInsets;
+ SafeInsets safeAreaInsets() const override { return contentInsets; }
CAMetalLayer* layer = nil;
// Whoever owns the responder the keyboard talks to (the view controller); set
// once it has loaded, which is also what makes hasTextEditor() true.
@@ -226,6 +228,9 @@ IOSPlatform g_platform;
const BOOL resized = !CGSizeEqualToSize(layer.drawableSize, size);
layer.drawableSize = size;
g_platform.layer = layer;
+ const UIEdgeInsets insets = self.view.safeAreaInsets;
+ g_platform.contentInsets = { (float)(insets.top * scale), (float)(insets.bottom * scale),
+ (float)(insets.left * scale), (float)(insets.right * scale) };
// Boot on the first laid-out frame: Dawn needs a layer with a real size to
// configure a surface against. Later layouts (rotation) just rebind.
@@ -238,6 +243,14 @@ IOSPlatform g_platform;
- (void)step:(CADisplayLink*)link { eshost::frame(); }
+- (void)viewSafeAreaInsetsDidChange {
+ [super viewSafeAreaInsetsDidChange];
+ const CGFloat scale = (self.view.window.screen ?: UIScreen.mainScreen).scale;
+ const UIEdgeInsets insets = self.view.safeAreaInsets;
+ g_platform.contentInsets = { (float)(insets.top * scale), (float)(insets.bottom * scale),
+ (float)(insets.left * scale), (float)(insets.right * scale) };
+}
+
- (void)appBackgrounded {
_displayLink.paused = YES;
eshost::surfaceLost();
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 6d3851fdb..0bad39cfc 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5885,6 +5885,7 @@ readTextFile: (path: string) => Promise<string>
registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefined
removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
screenRecorder: (() => PlatformScreenRecorder | null) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a959aaf60..742e0f01c 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5346,6 +5346,7 @@ readCacheFile: ((key: string) => Promise<ArrayBuffer | null>) | undefined
readFile: (path: string) => Promise<ArrayBuffer>
registerInput: (listener: NativeInputListener) => () => void
removeStorageItem: (key: string) => void
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
setStorageItem: (key: string, value: string) => void
setWindowSize: ((width: number, height: number) => void) | undefined
socket: NativeSocketBridge | undefined
@@ -5412,6 +5413,7 @@ es_readAsset: (path: string) => ArrayBuffer | null
es_readCacheFile: ((key: string) => ArrayBuffer | null) | undefined
es_readDataFile: ((key: string) => ArrayBuffer | null) | undefined
es_removeStorageItem: ((key: string) => void) | undefined
+es_safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
es_setStorageItem: ((key: string, value: string) => void) | undefined
es_setWindowSize: ((width: number, height: number) => void) | undefined
es_steam_available: (() => boolean) | undefined
@@ -5487,6 +5489,7 @@ readCacheFile: (key: string) => Promise<ArrayBuffer | null>
readFile: (path: string) => Promise<ArrayBuffer>
readTextFile: (path: string) => Promise<string>
removeStorageItem: (key: string) => void
+safeAreaInsets: () => { top: number; bottom: number; left: number; right: number; }
setStorageItem: (key: string, value: string) => void
setWindowSize: (width: number, height: number) => void
steamAchievements: (appId: number) => AchievementProvider | null
@@ -6076,6 +6079,7 @@ readTextFile: (path: string) => Promise<string>
registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefined
removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
screenRecorder: (() => PlatformScreenRecorder | null) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 136a82bda..ad67d80ce 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5880,6 +5880,7 @@ readTextFile: (path: string) => Promise<string>
registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefined
removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
screenRecorder: (() => PlatformScreenRecorder | null) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 21ac19217..ca0d4999d 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6153,6 +6153,7 @@ readTextFile: (path: string) => Promise<string>
registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefined
removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
screenRecorder: (() => PlatformScreenRecorder | null) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 65faa8a1b..ae4f9a849 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5887,6 +5887,7 @@ readTextFile: (path: string) => Promise<string>
registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefined
removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefined
screenRecorder: (() => PlatformScreenRecorder | null) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.ts
index 804ba5728..e9c123473 100644
--- a/sdk/src/platform/native/adapter.ts
+++ b/sdk/src/platform/native/adapter.ts
@@ -140,6 +140,10 @@ export class NativePlatformAdapter implements PlatformAdapter {
return this.bridge_.devicePixelRatio();
}
+ safeAreaInsets(): { top: number; bottom: number; left: number; right: number } {
+ return this.bridge_.safeAreaInsets?.() ?? { top: 0, bottom: 0, left: 0, right: 0 };
+ }
+
language(): string {
// platformLanguage() normalizes underscores ('zh_CN' → 'zh-CN').
return this.bridge_.language?.() ?? 'en';
diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.ts
index c95475939..553d87284 100644
--- a/sdk/src/platform/native/bridge.ts
+++ b/sdk/src/platform/native/bridge.ts
@@ -217,6 +217,8 @@ export interface NativeBridge {
steam?: NativeSteamBridge;
devicePixelRatio(): number;
+ /** Live content insets in surface pixels. Optional for older native hosts. */
+ safeAreaInsets?(): { top: number; bottom: number; left: number; right: number };
/** High-resolution clock. Optional — falls back to the host's `performance.now()`,
* then `Date.now()`, whose whole milliseconds read sub-millisecond spans as 0. */
now?(): number;
diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.ts
index 375f5b44f..8fc1d81b9 100644
--- a/sdk/src/platform/native/hostBridge.ts
+++ b/sdk/src/platform/native/hostBridge.ts
@@ -63,6 +63,8 @@ export interface NativeHostBindings {
es_storageKeys?(): string[];
/** Screen scale (1 when the host reports surface pixels directly). */
es_devicePixelRatio?(): number;
+ /** OS content insets, already converted to the rendered surface pixel domain. */
+ es_safeAreaInsets?(): { top: number; bottom: number; left: number; right: number };
/** The gamepads this frame, in the W3C standard layout. Absent on a host with
* no pads to report — a phone, where the SDK sees the same empty list a
@@ -242,6 +244,7 @@ export function createHostBridge(
return () => { listener = null; };
},
devicePixelRatio: () => bindings.es_devicePixelRatio?.() ?? 1,
+ safeAreaInsets: () => bindings.es_safeAreaInsets?.() ?? { top: 0, bottom: 0, left: 0, right: 0 },
// All-or-nothing: the host binds the whole surface or none of it, so one
// probe decides rather than nine optional calls at every site.
...(bindings.es_steam_init
diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.ts
index 2f57284e7..6f4853df1 100644
--- a/sdk/src/platform/types.ts
+++ b/sdk/src/platform/types.ts
@@ -654,6 +654,10 @@ export interface PlatformAdapter {
devicePixelRatio(): number;
+ /** Live native content insets in framebuffer pixels, independent of DPR.
+ * Absent on hosts without a safe-area source. */
+ safeAreaInsets?(): { top: number; bottom: number; left: number; right: number };
+
getStorageItem(key: string): string | null;
setStorageItem(key: string, value: string): void;
removeStorageItem(key: string): void;
diff --git a/sdk/src/ui/layout/safe-area.ts b/sdk/src/ui/layout/safe-area.ts
index fff543102..654dd86e9 100644
--- a/sdk/src/ui/layout/safe-area.ts
+++ b/sdk/src/ui/layout/safe-area.ts
@@ -6,7 +6,7 @@
* platform safe-area insets into UINode insets, co-located.
*/
import type { App, Plugin } from '../../app/app';
-import { isWeChat, platformDevicePixelRatio } from '../../platform';
+import { getPlatform, isNative, isWeChat, platformDevicePixelRatio } from '../../platform';
import { defineComponent, registerComponent } from '../../ecs/component';
import { Res } from '../../ecs/resource';
import { defineSystem, Schedule } from '../../ecs/system';
@@ -99,10 +99,9 @@ function getSafeAreaInsets(): SafeAreaInsets {
if (isWeChat()) {
return getWeChatSafeAreaInsets();
}
- // Native (no DOM) falls through to getWebSafeAreaInsets, which returns zero
- // insets when `document` is absent — harmless. When the native shell exposes
- // notch insets (a bridge.safeAreaInsets() seam), gate `isWeChat() || isNative()`
- // here and read them the wechat way (non-DPR-scaled).
+ if (isNative()) {
+ return getPlatform().safeAreaInsets?.() ?? { top: 0, bottom: 0, left: 0, right: 0 };
+ }
return getWebSafeAreaInsets();
}
@@ -144,6 +143,8 @@ export class SafeAreaPlugin implements Plugin {
[Res(ScreenLayout)],
(layout: ScreenLayoutData) => {
if (!layout.valid || layout.viewportH === 0) return;
+ const safeNodes = world.getEntitiesWithComponents([SafeArea, UINode]);
+ if (safeNodes.length === 0) return;
const layoutH = layout.top - layout.bottom;
if (layout.viewportH !== prevScreenH || layoutH !== prevLayoutH) {
@@ -152,21 +153,21 @@ export class SafeAreaPlugin implements Plugin {
stale = true;
}
- // Only the READ is throttled; the nodes are visited every frame.
- // A scene loaded later brings its own, and deciding once on
- // frame one never looks at them.
- if (stale) {
+ // Read native cached OS insets each frame: delayed layout and
+ // landscape side changes need not resize the framebuffer.
+ // Visit nodes each tick so later scenes acquire their margins.
+ if (stale || isNative()) {
stale = false;
cachedInsets = getSafeAreaInsets();
cachedMenuBottom = hostMenuBottom();
}
const dpr = platformDevicePixelRatio();
- const insetScale = isWeChat() ? (1 / layout.scale) : (dpr / layout.scale);
+ const insetScale = isWeChat() || isNative() ? (1 / layout.scale) : (dpr / layout.scale);
// UINode targets (CSS box): safe-area insets map to the node's
// absolute insets. The node is expected to be position:Absolute.
- for (const entity of world.getEntitiesWithComponents([SafeArea, UINode])) {
+ for (const entity of safeNodes) {
const sa = world.get(entity, SafeArea) as SafeAreaData;
const node = world.get(entity, UINode) as UINodeData;
diff --git a/sdk/tests/native-host-bridge.test.ts b/sdk/tests/native-host-bridge.test.ts
index 4e8b2d812..2c476d455 100644
--- a/sdk/tests/native-host-bridge.test.ts
+++ b/sdk/tests/native-host-bridge.test.ts
@@ -7,7 +7,7 @@
* what is missing, not fail later somewhere unrelated.
*/
import { describe, it, expect, vi } from 'vitest';
-import { createHostBridge, assertHostEnvironment, assertNativeHost } from '../src/platform/native';
+import { createHostBridge, assertHostEnvironment, assertNativeHost, NativePlatformAdapter } from '../src/platform/native';
import { cacheEntryName } from '../src/platform/cacheEntryName';
import { REGISTRY_BINDINGS, RESOURCE_BINDINGS, PLATFORM_BINDINGS } from '../src/ecs/bridge/nativeBindings';
@@ -326,6 +326,23 @@ describe('a CDN image on a native build', () => {
});
});
+describe('native content insets reach the platform adapter', () => {
+ it('preserves surface-pixel units and reads changing OS layout values', () => {
+ let insets = { top: 0, bottom: 60, left: 192, right: 72 };
+ const adapter = new NativePlatformAdapter(createHostBridge(hostScope({
+ es_devicePixelRatio: () => 3, es_safeAreaInsets: () => insets,
+ }) as never));
+ expect(adapter.safeAreaInsets()).toEqual(insets);
+ insets = { top: 0, bottom: 60, left: 72, right: 192 };
+ expect(adapter.safeAreaInsets()).toEqual(insets);
+ });
+
+ it('supports an older host with no inset binding', () => {
+ const adapter = new NativePlatformAdapter(createHostBridge(hostScope() as never));
+ expect(adapter.safeAreaInsets()).toEqual({ top: 0, bottom: 0, left: 0, right: 0 });
+ });
+});
+
describe('the host bridge names its device and carries its socket client', () => {
it('passes both through when the host binds them', () => {
const opened: string[] = [];
diff --git a/sdk/tests/safe-area-native.test.ts b/sdk/tests/safe-area-native.test.ts
new file mode 100644
index 000000000..5b4455c4a
--- /dev/null
+++ b/sdk/tests/safe-area-native.test.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, describe, expect, it } from 'vitest';
+import { App } from '../src/app/app';
+import { setPlatform } from '../src/platform/base';
+import type { PlatformAdapter } from '../src/platform/types';
+import { webAdapter } from '../src/platform/web';
+import { SafeArea, safeAreaPlugin, type SafeAreaInsets } from '../src/ui/layout/safe-area';
+import { uiLayoutPlugin } from '../src/ui/layout/layout';
+import { ScreenLayout } from '../src/ui/core/screen-layout';
+import { UINode } from '../src/ui/core/ui-node';
+import { createMockModule } from './mocks/wasm';
+
+afterEach(() => setPlatform(webAdapter));
+
+function setup(readInsets?: () => SafeAreaInsets) {
+ setPlatform({ ...webAdapter, name: 'native', devicePixelRatio: () => 3,
+ ...(readInsets ? { safeAreaInsets: readInsets } : {}),
+ } as PlatformAdapter);
+ const module = createMockModule();
+ const app = App.new();
+ app.connectCpp(module.getRegistry(), module);
+ app.insertResource(ScreenLayout, {
+ ...ScreenLayout._default, valid: true, scale: 2,
+ left: 0, bottom: 0, right: 1200, top: 600,
+ viewportW: 2400, viewportH: 1200,
+ });
+ app.addPlugin(uiLayoutPlugin);
+ app.addPlugin(safeAreaPlugin);
+ const entity = app.world.spawn();
+ app.world.insert(entity, UINode, { ...UINode._default });
+ app.world.insert(entity, SafeArea, { ...SafeArea._default });
+ const read = () => {
+ const node = app.world.get(entity, UINode);
+ return { top: node.insetTop.value, bottom: node.insetBottom.value,
+ left: node.insetLeft.value, right: node.insetRight.value };
+ };
+ return { app, read };
+}
+
+describe('native safe-area layout', () => {
+ it('keeps a landscape notch clear in surface pixels without applying DPR twice', async () => {
+ const { app, read } = setup(() => ({ top: 0, bottom: 60, left: 192, right: 72 }));
+ await app.tick(1 / 60);
+ expect(read()).toEqual({ top: 0, bottom: 30, left: 96, right: 36 });
+ });
+
+ it('accepts delayed native layout and a side swap with the same viewport dimensions', async () => {
+ let insets = { top: 0, bottom: 0, left: 0, right: 0 };
+ const { app, read } = setup(() => insets);
+ await app.tick(1 / 60);
+ expect(read().left).toBe(0);
+ insets = { top: 0, bottom: 60, left: 192, right: 72 };
+ await app.tick(1 / 60);
+ expect(read()).toEqual({ top: 0, bottom: 30, left: 96, right: 36 });
+ insets = { top: 0, bottom: 60, left: 72, right: 192 };
+ await app.tick(1 / 60);
+ expect(read()).toEqual({ top: 0, bottom: 30, left: 36, right: 96 });
+ });
+
+ it('keeps older hosts with no safe-area bridge compatible', async () => {
+ const { app, read } = setup();
+ await app.tick(1 / 60);
+ expect(read()).toEqual({ top: 0, bottom: 0, left: 0, right: 0 });
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 85643badf..20fed9ead 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(native): keep authored UI inside live device safe areas':
+ { note: 'Native UI follows the device safe area.' },
'chore(release): isolate compositor capture and preserve GPU diagnostics':
{ internal: 'Release-only capture separates the virtual-display compositor from software WebGL, retains game-canvas/window images and logs, and continues to fail on any game error; runtime behavior is unchanged.' },
'fix(editor): resolve the installed macOS executable from its bundle metadata':