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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(native): keep authored UI inside live device safe areas
yhh06366d08ca46
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdxindex 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 itinsets 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.+## ThemingWidget 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.mdxindex 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.essceneindex 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.hppindex 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/italicdiff --git a/native/host/bindings/RenderBindings.cpp b/native/host/bindings/RenderBindings.cppindex 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.cppindex 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::FetchResustruct AndroidPlatform final : eshost::Platform {AAssetManager* assets = nullptr; // APK assets/ — the game + its contentANativeWindow* 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-threadstd::string cache; // getCacheDir() — the system may reclaim itstd::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 thediff --git a/native/host/platform/ios.mm b/native/host/platform/ios.mmindex 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.mdindex 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>) | undefinedremoveStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedscreenRecorder: (() => PlatformScreenRecorder | null) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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>) | undefinedreadFile: (path: string) => Promise<ArrayBuffer>registerInput: (listener: NativeInputListener) => () => voidremoveStorageItem: (key: string) => void+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedsetStorageItem: (key: string, value: string) => voidsetWindowSize: ((width: number, height: number) => void) | undefinedsocket: NativeSocketBridge | undefined@@ -5412,6 +5413,7 @@ es_readAsset: (path: string) => ArrayBuffer | nulles_readCacheFile: ((key: string) => ArrayBuffer | null) | undefinedes_readDataFile: ((key: string) => ArrayBuffer | null) | undefinedes_removeStorageItem: ((key: string) => void) | undefined+es_safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedes_setStorageItem: ((key: string, value: string) => void) | undefinedes_setWindowSize: ((width: number, height: number) => void) | undefinedes_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) => voidsetWindowSize: (width: number, height: number) => voidsteamAchievements: (appId: number) => AchievementProvider | null@@ -6076,6 +6079,7 @@ readTextFile: (path: string) => Promise<string>registerFont: ((family: string, bytes: ArrayBuffer) => Promise<void>) | undefinedremoveStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedscreenRecorder: (() => PlatformScreenRecorder | null) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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>) | undefinedremoveStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedscreenRecorder: (() => PlatformScreenRecorder | null) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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>) | undefinedremoveStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedscreenRecorder: (() => PlatformScreenRecorder | null) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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>) | undefinedremoveStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined+safeAreaInsets: (() => { top: number; bottom: number; left: number; right: number; }) | undefinedscreenRecorder: (() => PlatformScreenRecorder | null) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => voiddiff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 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.tsindex 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.tsindex 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_initdiff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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':