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(ui): scope safe-area resize subscriptions to their apps
yhhb2deccaf9933
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 52001c780..cc1e17a64 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Safe-area resize listeners belong to their App.** Quitting an older App no longer removes a newer App's browser listener or leaves its own behind. Rebuilding replaces the same App's binding, cleanup uses the original host and WeChat callback identity, and older hosts without an unsubscribe API revoke the retained callback.+- **Camera fitting and editor previews use outer canvases consistently.** A nested canvas appearing first no longer overrides the scene design resolution or becomes the default host for new UI. Scene-filtered camera collection uses a running scene's outer canvas, and preview selection queries Canvas components directly. The experimental `canvasRootEntities` helper shares root selection across runtime and editor workflows.- **Nested canvases keep their parent layout and authored draw order.** Only top-level eligible canvases start traversal, so a nested canvas is not laid out again against the full screen or assigned a second draw-order range. Descendants inherit the nearest canvas's sorting layer regardless of canvas creation order.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c20cfe6cc..aee4c561f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -7156,7 +7156,7 @@ avoidHostMenu: boolean## SafeAreaPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "safeArea"static new (): SafeAreaPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 966045e51..afa806311 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -7360,7 +7360,7 @@ avoidHostMenu: boolean## SafeAreaPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "safeArea"static new (): SafeAreaPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 4264ef660..884ed6ba9 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -7151,7 +7151,7 @@ avoidHostMenu: boolean## SafeAreaPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "safeArea"static new (): SafeAreaPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 3a3791e25..7719b2f5f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -7424,7 +7424,7 @@ avoidHostMenu: boolean## SafeAreaPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "safeArea"static new (): SafeAreaPlugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex ae59cbbc4..48cfac654 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -7158,7 +7158,7 @@ avoidHostMenu: boolean## SafeAreaPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voiddependencies: "uiLayout"[]name: "safeArea"static new (): SafeAreaPlugindiff --git a/sdk/src/ui/layout/safe-area-resize.ts b/sdk/src/ui/layout/safe-area-resize.tsnew file mode 100644index 000000000..75e4baa63--- /dev/null+++ b/sdk/src/ui/layout/safe-area-resize.ts@@ -0,0 +1,28 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { isWeChat } from '../../platform';++/** Bind to the current host; revocation also drops the callback on older hosts without offWindowResize. */+export function subscribeSafeAreaResize(onResize: (() => void) | null): () => void {+ const listener = () => onResize?.();+ let detach = () => {};+ if (isWeChat()) {+ const host = (globalThis as unknown as { wx?: {+ onWindowResize?(listener: () => void): void;+ offWindowResize?(listener: () => void): void;+ } }).wx;+ if (host?.onWindowResize) {+ host.onWindowResize(listener);+ detach = () => host.offWindowResize?.(listener);+ }+ } else if (typeof window !== 'undefined') {+ const host = window;+ host.addEventListener('resize', listener);+ detach = () => host.removeEventListener('resize', listener);+ }+ return () => {+ if (onResize === null) return;+ onResize = null;+ detach();+ };+}diff --git a/sdk/src/ui/layout/safe-area.ts b/sdk/src/ui/layout/safe-area.tsindex 654dd86e9..43b3e04a9 100644--- a/sdk/src/ui/layout/safe-area.ts+++ b/sdk/src/ui/layout/safe-area.ts@@ -16,6 +16,7 @@ import { UINode } from '../core/ui-node';import type { UINodeData } from '../core/ui-node';import { px } from '../core/dimension';import { SystemLabel, PluginName } from '../../ecs/systemLabels';+import { subscribeSafeAreaResize } from './safe-area-resize';export interface SafeAreaData {applyTop: boolean;@@ -50,7 +51,6 @@ interface WxGlobal {wx?: {getSystemInfoSync?(): { safeArea: { top: number; bottom: number; left: number; right: number }; screenWidth: number; screenHeight: number } | undefined;getMenuButtonBoundingClientRect?(): { top: number; bottom: number; left: number; right: number } | undefined;- onWindowResize?(cb: () => void): void;};}@@ -109,16 +109,19 @@ export class SafeAreaPlugin implements Plugin {name = PluginName.SafeArea;dependencies = [PluginName.UILayout];- private onResize_: (() => void) | null = null;+ private readonly resizeCleanups_ = new WeakMap<App, () => void>();+ private latestResizeCleanup_: (() => void) | null = null;- cleanup(): void {- if (this.onResize_ && typeof window !== 'undefined') {- window.removeEventListener('resize', this.onResize_);- }- this.onResize_ = null;+ cleanup(app?: App): void {+ const release = app ? this.resizeCleanups_.get(app) : this.latestResizeCleanup_;+ if (!release) return;+ if (app) this.resizeCleanups_.delete(app);+ if (release === this.latestResizeCleanup_) this.latestResizeCleanup_ = null;+ release();}build(app: App): void {+ this.cleanup(app);registerComponent('SafeArea', SafeArea);const world = app.world;@@ -131,13 +134,9 @@ export class SafeAreaPlugin implements Plugin {let prevScreenH = 0;let prevLayoutH = 0;- if (isWeChat()) {- const g = globalThis as unknown as WxGlobal;- g.wx?.onWindowResize?.(() => { stale = true; });- } else if (typeof window !== 'undefined') {- this.onResize_ = () => { stale = true; };- window.addEventListener('resize', this.onResize_);- }+ const release = subscribeSafeAreaResize(() => { stale = true; });+ this.resizeCleanups_.set(app, release);+ this.latestResizeCleanup_ = release;app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([Res(ScreenLayout)],diff --git a/sdk/tests/safe-area-lifecycle.test.ts b/sdk/tests/safe-area-lifecycle.test.tsnew file mode 100644index 000000000..ff1fb80f0--- /dev/null+++ b/sdk/tests/safe-area-lifecycle.test.ts@@ -0,0 +1,85 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, expect, it, vi } from 'vitest';+import { SafeAreaPlugin } from '../src/ui/layout/safe-area';+import { uiLayoutPlugin } from '../src/ui/layout/layout';+import { subscribeSafeAreaResize } from '../src/ui/layout/safe-area-resize';+import { setPlatform } from '../src/platform/base';+import { webAdapter } from '../src/platform/web';+import { MiniGamePlatformAdapter } from '../src/platform/minigame/adapter';+import { wechatProfile } from '../src/platform/wechat/profile';+import { bootMockApp } from './helpers/mockApp';+import type { App } from '../src/app/app';+const apps: App[] = [];+afterEach(() => {+ for (const app of apps.splice(0)) app.quit();+ vi.unstubAllGlobals(); setPlatform(webAdapter);+});+const appWith = (plugin: SafeAreaPlugin) => {+ const app = bootMockApp().app; apps.push(app); app.addPlugin(uiLayoutPlugin); app.addPlugin(plugin); return app;+};+const webHost = () => {+ const callbacks = new Set<() => void>();+ return { callbacks, window: {+ addEventListener: (type: string, listener: () => void) => { if (type === 'resize') callbacks.add(listener); },+ removeEventListener: (type: string, listener: () => void) => { if (type === 'resize') callbacks.delete(listener); },+ } };+};+it('quitting one app preserves the other app resize listener and releases its own', () => {+ const host = webHost(); vi.stubGlobal('window', host.window); setPlatform(webAdapter);+ const plugin = new SafeAreaPlugin(), first = appWith(plugin);+ const firstListener = [...host.callbacks][0];+ const second = appWith(plugin), secondListener = [...host.callbacks][1];+ first.quit();+ expect(host.callbacks.has(firstListener)).toBe(false);+ expect(host.callbacks.has(secondListener)).toBe(true);+ second.quit(); expect(host.callbacks.size).toBe(0);+});+it('rebuilding the same app keeps only its latest resize listener', () => {+ const host = webHost(); vi.stubGlobal('window', host.window); setPlatform(webAdapter);+ const plugin = new SafeAreaPlugin(), app = appWith(plugin);+ plugin.build(app);+ expect(host.callbacks.size).toBe(1);+ app.quit(); expect(host.callbacks.size).toBe(0);+});+it('cleanup uses the window that registered the listener after the global host changes', () => {+ const original = webHost(), replacement = webHost();+ vi.stubGlobal('window', original.window); setPlatform(webAdapter);+ const app = appWith(new SafeAreaPlugin());+ vi.stubGlobal('window', replacement.window);+ app.quit(); expect(original.callbacks.size).toBe(0);+});+it('releases each WeChat resize listener by the same callback identity', () => {+ const callbacks = new Set<() => void>();+ vi.stubGlobal('wx', { onWindowResize: (listener: () => void) => callbacks.add(listener), offWindowResize: (listener: () => void) => callbacks.delete(listener) });+ setPlatform(new MiniGamePlatformAdapter(wechatProfile));+ const plugin = new SafeAreaPlugin(), first = appWith(plugin), firstListener = [...callbacks][0];+ const second = appWith(plugin), secondListener = [...callbacks][1];+ first.quit(); expect(callbacks.has(firstListener)).toBe(false); expect(callbacks.has(secondListener)).toBe(true);+ second.quit(); expect(callbacks.size).toBe(0);+});+it('revokes callbacks on older WeChat hosts that cannot unregister listeners', () => {+ let listener = () => {};+ vi.stubGlobal('wx', { onWindowResize: (callback: () => void) => { listener = callback; } });+ setPlatform(new MiniGamePlatformAdapter(wechatProfile));+ const changed = vi.fn(), release = subscribeSafeAreaResize(changed);+ listener(); expect(changed).toHaveBeenCalledOnce();+ release(); listener(); expect(changed).toHaveBeenCalledOnce();+ expect(() => release()).not.toThrow();+});+it('keeps parameterless cleanup compatible and idempotent for the latest app', () => {+ const host = webHost(); vi.stubGlobal('window', host.window); setPlatform(webAdapter);+ const plugin = new SafeAreaPlugin(), app = appWith(plugin);+ plugin.cleanup(); plugin.cleanup(); expect(host.callbacks.size).toBe(0);+ app.quit(); expect(host.callbacks.size).toBe(0);+});+it('keeps listener counts bounded through repeated preview app creation and shutdown', () => {+ const host = webHost(); vi.stubGlobal('window', host.window); setPlatform(webAdapter);+ const plugin = new SafeAreaPlugin(), main = appWith(plugin);+ for (let cycle = 0; cycle < 100; cycle++) {+ const preview = appWith(plugin);+ expect(host.callbacks.size).toBe(2);+ preview.quit(); expect(host.callbacks.size).toBe(1);+ }+ main.quit(); expect(host.callbacks.size).toBe(0);+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex da833b97d..2502a0aa6 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(ui): scope safe-area resize subscriptions to their apps':+ { note: 'Safe-area resize listeners belong to their App.' },'fix(camera): align canvas fitting with hierarchy and scene filters':{ note: 'Camera fitting and editor previews use outer canvases consistently.' },'fix(editor): use outer canvases for previews and UI hosting':