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(ui): resolve live display ancestry for keyboard focus

yhh41f59733ad80
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 664dc3b0a..e4ce05efb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Keyboard focus observes authored visibility between layout passes.** Focus traversal and single-target checks read current display ancestry, so hiding a tree or opening a previously hidden modal immediately changes eligibility without waiting for the cached layout bit. Per-query ancestry memoization and borrowed component reads share work across controls; hosts without authored UI ancestry retain their existing visibility fallback.
+
- **Text-input length limits preserve complete supplementary characters.** Oversized host input still uses UTF-16 length limits, but truncation backs off when the boundary would split a valid surrogate pair. The corrected value and selection return to the editing surface together, preventing malformed emoji in committed input while preserving BMP limits and existing cursor semantics.
- **Text fields read only the editing surface they actually own.** Newly focused fields retain their committed display until attached, and read-only fields never borrow a previous field's transient value. Switching a live field to read-only detaches the OS surface and hides its caret; restoring editability reattaches the committed value without replaying rejected input.
diff --git a/sdk/src/ui/input/focus-inspection.ts b/sdk/src/ui/input/focus-inspection.ts
index 4eae2ee4a..bd74c8812 100644
--- a/sdk/src/ui/input/focus-inspection.ts
+++ b/sdk/src/ui/input/focus-inspection.ts
@@ -7,6 +7,8 @@ import { Focusable } from './focusable';
import { Interactable } from './interactable';
import { UIDialog, isDialogOpen } from '../behavior/dialog';
import { walkParentChain } from '../util/helpers';
+import { Parent } from '../../ecs/component';
+import { UINode, UIDisplay, type UINodeData } from '../core/ui-node';
/** Read-only scene queries needed to inspect focus. @experimental */
export type FocusInspectionWorld = Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>;
@@ -30,9 +32,11 @@ function focusContext(world: FocusInspectionWorld) {
const engine = worldEngineApi(world);
const registry = world.getCppRegistry();
const visibilityResolved = !!(registry && engine?.getUINodeHiddenInTree);
+ const hiddenInTree = liveVisibility(world, entity =>
+ visibilityResolved && engine!.getUINodeHiddenInTree!(registry!, entity));
const roots = new Set(world.getEntitiesWithComponents([UIDialog])
.filter(entity => isDialogOpen(world, entity)
- && (!visibilityResolved || !engine!.getUINodeHiddenInTree!(registry!, entity))));
+ && !hiddenInTree(entity)));
// A nested modal excludes its parent dialog's other controls. Independent
// dialog branches retain the existing union policy; no stacking order is inferred.
for (const root of [...roots]) {
@@ -41,15 +45,53 @@ function focusContext(world: FocusInspectionWorld) {
return false;
});
}
- return { engine, registry, visibilityResolved, roots };
+ return { visibilityResolved, roots, hiddenInTree };
+}
+
+/** Authored display is current even between layout passes. Memoize shared
+ * ancestors only within this read-only query, never across scene mutations. */
+function liveVisibility(world: FocusInspectionWorld, fallback: (entity: Entity) => boolean) {
+ const getter = (world as FocusInspectionWorld & Partial<Pick<World, 'resolveGetter'>>)
+ .resolveGetter?.(UINode) as ((entity: Entity) => UINodeData) | null | undefined;
+ const readNode = getter ?? ((entity: Entity) => world.get(entity, UINode));
+ const memo = new Map<Entity, { hidden: boolean; authored: boolean; pending: boolean }>();
+ const path: Entity[] = [];
+ return (entity: Entity): boolean => {
+ path.length = 0;
+ let current = entity, hidden = false, authored = false;
+ while (world.valid(current)) {
+ const cached = memo.get(current);
+ if (cached) {
+ // Invalid cyclic ancestry cannot receive keyboard input.
+ hidden = cached.pending || cached.hidden;
+ authored = cached.pending || cached.authored;
+ break;
+ }
+ memo.set(current, { hidden: false, authored: false, pending: true });
+ path.push(current);
+ if (!world.has(current, Parent)) break;
+ current = world.get(current, Parent).entity;
+ }
+ for (let i = path.length - 1; i >= 0; i--) {
+ const entry = memo.get(path[i])!;
+ if (world.has(path[i], UINode)) {
+ authored = true;
+ hidden = hidden || readNode(path[i]).display === UIDisplay.None;
+ }
+ entry.hidden = hidden;
+ entry.authored = authored;
+ entry.pending = false;
+ }
+ return authored ? hidden : fallback(entity);
+ };
}
function skipReason(world: FocusInspectionWorld, entity: Entity,
- { engine, registry, visibilityResolved, roots }: ReturnType<typeof focusContext>): FocusSkipReason | null {
+ { hiddenInTree, roots }: ReturnType<typeof focusContext>): FocusSkipReason | null {
let skipped: FocusSkipReason | null = null;
if (world.has(entity, Interactable) && !world.get(entity, Interactable).enabled) {
skipped = 'disabled';
- } else if (visibilityResolved && engine!.getUINodeHiddenInTree!(registry!, entity)) {
+ } else if (hiddenInTree(entity)) {
skipped = 'hidden';
} else if (roots.size > 0 && !roots.has(entity)) {
let inside = false;
diff --git a/sdk/tests/ui-focus-inspection.test.ts b/sdk/tests/ui-focus-inspection.test.ts
index e434003c2..000bdc996 100644
--- a/sdk/tests/ui-focus-inspection.test.ts
+++ b/sdk/tests/ui-focus-inspection.test.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
import { flushPendingRegistrations } from '../src/app/app';
import { Parent } from '../src/ecs/component';
import { Input, InputState } from '../src/input/input';
@@ -81,6 +81,7 @@ it('does not trap visible controls behind a dialog hidden by an ancestor', () =>
harness.module.getUINodeHiddenInTree = (_registry: unknown, entity: Entity) => hidden && entity === dialog;
expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual([null, 'hidden']);
hidden = false;
+ world.update(host, UINode, node => { node.display = UIDisplay.Flex; });
expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', null]);
world.despawn(dialog);
expect(inspectFocusTraversal(world).entries.find(e => e.entity === outside)?.skipped).toBeNull();
@@ -93,6 +94,9 @@ it('keeps a visible modal active when a second modal is hierarchically hidden',
world.insert(entity, UIDialog);
world.insert(entity, UINode, { display: UIDisplay.Flex });
}
+ const hiddenParent = world.spawn();
+ world.insert(hiddenParent, UINode, { display: UIDisplay.None });
+ world.setParent(hidden, hiddenParent);
harness.module.getUINodeHiddenInTree = (_registry: unknown, entity: Entity) => entity === hidden;
expect(inspectFocusTraversal(world).entries.map(e => [e.entity, e.skipped]))
.toEqual([[background, 'outside-dialog'], [visible, null], [hidden, 'hidden']]);
@@ -106,7 +110,10 @@ it('restricts nested dialogs to the innermost visible subtree and restores the p
focusPlugin.build(app);
flushPendingRegistrations(app);
const page = control(0), outer = control(1), nested = control(2), confirm = control(3);
- world.insert(nested, Parent, { entity: outer });
+ const nestedHost = world.spawn();
+ world.insert(nestedHost, UINode);
+ world.insert(nestedHost, Parent, { entity: outer });
+ world.insert(nested, Parent, { entity: nestedHost });
world.insert(confirm, Parent, { entity: nested });
for (const root of [outer, nested]) {
world.insert(root, UIDialog);
@@ -121,10 +128,12 @@ it('restricts nested dialogs to the innermost visible subtree and restores the p
expect(app.getResource(FocusManager).focusedEntity).toBe(nested);
input.keysPressed.clear();
nestedHidden = true;
+ world.update(nestedHost, UINode, node => { node.display = UIDisplay.None; });
await app.tick(1 / 60);
expect(app.getResource(FocusManager).focusedEntity).toBeNull();
expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', null, 'hidden', 'hidden']);
nestedHidden = false;
+ world.update(nestedHost, UINode, node => { node.display = UIDisplay.Flex; });
world.update(nested, UINode, node => { node.display = UIDisplay.None; });
expect(inspectFocusTraversal(world).entries.find(e => e.entity === outer)?.skipped).toBeNull();
world.remove(nested, UIDialog);
@@ -143,3 +152,38 @@ it('retains independent dialog branches when one branch contains a nested dialog
}
expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', null, null]);
});
+
+it('resolves shared display ancestry once per query and observes mutations on the next query', () => {
+ const world = harness.app.world, root = world.spawn();
+ world.insert(root, UINode);
+ const controls = Array.from({ length: 500 }, (_, i) => {
+ const entity = control(i);
+ world.insert(entity, UINode);
+ world.setParent(entity, root);
+ return entity;
+ });
+ let reads = 0;
+ const original = world.resolveGetter.bind(world);
+ const spy = vi.spyOn(world, 'resolveGetter').mockImplementation((component, mode) => {
+ const getter = original(component, mode);
+ return component !== UINode || !getter ? getter : entity => { reads++; return getter(entity); };
+ });
+ try {
+ expect(inspectFocusTraversal(world).entries.every(e => e.skipped === null)).toBe(true);
+ expect(reads).toBe(controls.length + 1);
+ world.update(root, UINode, node => { node.display = UIDisplay.None; });
+ expect(inspectFocusTraversal(world).entries.every(e => e.skipped === 'hidden')).toBe(true);
+ // Hidden ancestry short-circuits leaf display reads.
+ expect(reads).toBe(controls.length + 2);
+ } finally { spy.mockRestore(); }
+});
+
+it('uses authored hidden ancestry even when the host has no resolved-visibility query', () => {
+ const world = harness.app.world, root = world.spawn(), entity = control(0);
+ world.insert(root, UINode, { display: UIDisplay.None });
+ world.setParent(entity, root);
+ delete harness.module.getUINodeHiddenInTree;
+ const result = inspectFocusTraversal(world);
+ expect(result.visibilityResolved).toBe(false);
+ expect(result.entries[0].skipped).toBe('hidden');
+});
diff --git a/sdk/tests/ui-focus-transition-wasm.test.ts b/sdk/tests/ui-focus-transition-wasm.test.ts
index e750b063f..527a5fe7f 100644
--- a/sdk/tests/ui-focus-transition-wasm.test.ts
+++ b/sdk/tests/ui-focus-transition-wasm.test.ts
@@ -3,12 +3,12 @@
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
import { App, flushPendingRegistrations } from '../src/app/app';
import { AppContext, setDefaultContext } from '../src/ecs/context';
-import { Disabled, Parent } from '../src/ecs/component';
+import { Canvas, Disabled, Parent, Transform } from '../src/ecs/component';
import { setEditorMode, setPlayMode } from '../src/ecs/env';
import { Input, InputState } from '../src/input/input';
import { UIEvents, UIEventQueue } from '../src/ui/core/events';
import { UIDialog } from '../src/ui/behavior/dialog';
-import { UINode } from '../src/ui/core/ui-node';
+import { UINode, UIDisplay } from '../src/ui/core/ui-node';
import { Focusable, FocusManager } from '../src/ui/input/focusable';
import { focusPlugin } from '../src/ui/input/focus';
import { inspectFocusTraversal, isFocusEligible } from '../src/ui/input/focus-inspection';
@@ -80,4 +80,43 @@ describe.skipIf(!HAS_WASM)('focus transitions on real WASM', () => {
expect(queries.mock.calls.every(([components]) => !components.includes(Focusable))).toBe(true);
queries.mockRestore();
});
+
+ it('rejects a control immediately after its ancestor is hidden, before another layout pass', () => {
+ const root = app.world.spawn(), entity = control(0);
+ app.world.insert(root, Canvas);
+ app.world.insert(root, Transform);
+ app.world.insert(root, UINode);
+ app.world.insert(entity, Transform);
+ app.world.insert(entity, UINode);
+ app.world.setParent(entity, root);
+ engine.uiLayout_update(registry, -400, -300, 400, 300, true);
+ expect(isFocusEligible(app.world, entity)).toBe(true);
+ app.world.update(root, UINode, n => { n.display = UIDisplay.None; });
+ expect(engine.getUINodeHiddenInTree(registry, entity)).toBe(false);
+ expect(isFocusEligible(app.world, entity)).toBe(false);
+ app.world.update(root, UINode, n => { n.display = UIDisplay.Flex; });
+ expect(isFocusEligible(app.world, entity)).toBe(true);
+ });
+
+ it('applies a newly opened modal before its cached hidden bit is refreshed', () => {
+ const root = app.world.spawn(), outside = control(0), dialog = control(1);
+ app.world.insert(root, Canvas);
+ app.world.insert(root, Transform);
+ app.world.insert(root, UINode);
+ for (const entity of [outside, dialog]) {
+ app.world.insert(entity, Transform);
+ app.world.insert(entity, UINode, { display: entity === dialog ? UIDisplay.None : UIDisplay.Flex });
+ app.world.setParent(entity, root);
+ }
+ app.world.insert(dialog, UIDialog);
+ engine.uiLayout_update(registry, -400, -300, 400, 300, true);
+ expect(engine.getUINodeHiddenInTree(registry, dialog)).toBe(true);
+ expect(isFocusEligible(app.world, outside)).toBe(true);
+ app.world.update(dialog, UINode, n => { n.display = UIDisplay.Flex; });
+ expect(engine.getUINodeHiddenInTree(registry, dialog)).toBe(true);
+ expect(isFocusEligible(app.world, outside)).toBe(false);
+ expect(isFocusEligible(app.world, dialog)).toBe(true);
+ app.world.update(dialog, UINode, n => { n.display = UIDisplay.None; });
+ expect(isFocusEligible(app.world, outside)).toBe(true);
+ });
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 30c79529d..ae2320281 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): resolve live display ancestry for keyboard focus':
+ { note: 'Keyboard focus observes authored visibility between layout passes.' },
'fix(ui): preserve surrogate pairs when clamping host input':
{ note: 'Text-input length limits preserve complete supplementary characters.' },
'fix(ui): bind field rendering to the active editing owner':