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): restrict nested dialog focus to inner modal (#84)
YHHd50c85dab4ab
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.mdindex add2346d1..f3cf16e49 100644--- a/examples/ui-localization-debug/README.md+++ b/examples/ui-localization-debug/README.md@@ -127,3 +127,9 @@ game. Returning to Events keeps recording, the filter and dispatch history.Toggle panel closes the debugger and stops observation; opening it againrestores recorded history without automatically recording. Stop Play alsoends observation.++For nested modal focus, click Inside to create Runtime button, then press N.+An outer UIDialog contains Runtime button and Nested confirm (another UIDialog).+Only Nested confirm should remain in the Tab ring. Tab and Shift+Tab stay there;+Enter dismisses it, and Tab returns to Runtime button in the outer modal.+R closes the fixture's dialogs. Independent modal stacking is not covered here.diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.mdindex 44d49b14d..eba612bc7 100644--- a/examples/ui-localization-debug/VALIDATION.md+++ b/examples/ui-localization-debug/VALIDATION.md@@ -345,3 +345,22 @@ snapshot; live-game-only dialogs and scripts need runtime acceptance separately.- No Electron/native runner launched. This improves the UI debugging workflow;device IME/accessibility, modal stacking, shaping and cache performance remainseparate acceptance items. RM-009 remains In Progress.++## Nested modal focus — 2026-10-09++- An open nested UIDialog now excludes its ancestor modal's other controls+ from the focus ring. Hidden/closed nested dialogs restore the ancestor's+ scope. Independent dialog branches retain the previous union policy;+ sibling stacking order remains unresolved.+- The new regression fails before the change: the outer dialog remains+ eligible. After the fix, 31 targeted focus/quick-click tests pass, including+ stale focus clearing, hidden/closed/removed nested dialog components, and+ independent visible branches. SDK build and 16 source/built API checks pass.+- Built-in browser, production Play host/SDK/WASM: click Inside, press N to+ create the actual outer/nested UIDialog hierarchy. Focus shows one navigable+ control and three outside-dialog controls (including Runtime button).+ Tab/Shift+Tab focus Nested confirm. Enter despawns it; Tab returns to+ Runtime button, while the two page controls stay outside the outer dialog.+- No local Electron/native runner launched. Device IME/accessibility,+ independent modal stacking, custom-scheme, shaping and cache performance+ remain open. RM-009 and RM-008 are still the two unfinished 0.94.0 cards.diff --git a/sdk/src/ui/input/focus-inspection.ts b/sdk/src/ui/input/focus-inspection.tsindex 6bc1c9dba..5c0b6047f 100644--- a/sdk/src/ui/input/focus-inspection.ts+++ b/sdk/src/ui/input/focus-inspection.ts@@ -34,6 +34,14 @@ export function inspectFocusTraversal(world: FocusInspectionWorld): FocusTraversconst roots = new Set(world.getEntitiesWithComponents([UIDialog]).filter(entity => isDialogOpen(world, entity)&& (!visibilityResolved || !engine!.getUINodeHiddenInTree!(registry!, 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]) {+ walkParentChain(world, root, ancestor => {+ roots.delete(ancestor);+ return false;+ });+ }const entries: FocusTraversalEntry[] = [];for (const entity of world.getEntitiesWithComponents([Focusable])) {if (!world.valid(entity)) continue;diff --git a/sdk/tests/ui-focus-inspection.test.ts b/sdk/tests/ui-focus-inspection.test.tsindex cf62a2f8d..e434003c2 100644--- a/sdk/tests/ui-focus-inspection.test.ts+++ b/sdk/tests/ui-focus-inspection.test.ts@@ -97,3 +97,49 @@ it('keeps a visible modal active when a second modal is hierarchically hidden',expect(inspectFocusTraversal(world).entries.map(e => [e.entity, e.skipped])).toEqual([[background, 'outside-dialog'], [visible, null], [hidden, 'hidden']]);});++it('restricts nested dialogs to the innermost visible subtree and restores the parent when closed', async () => {+ const { app, module } = harness;+ const world = app.world;+ app.insertResource(Input, new InputState());+ app.insertResource(UIEvents, new UIEventQueue());+ focusPlugin.build(app);+ flushPendingRegistrations(app);+ const page = control(0), outer = control(1), nested = control(2), confirm = control(3);+ world.insert(nested, Parent, { entity: outer });+ world.insert(confirm, Parent, { entity: nested });+ for (const root of [outer, nested]) {+ world.insert(root, UIDialog);+ world.insert(root, UINode, { display: UIDisplay.Flex });+ }+ let nestedHidden = false;+ module.getUINodeHiddenInTree = (_registry: unknown, entity: Entity) => nestedHidden && [nested, confirm].includes(entity);+ expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', 'outside-dialog', null, null]);+ const input = app.getResource(Input);+ input.keysPressed.add('Tab');+ await app.tick(1 / 60);+ expect(app.getResource(FocusManager).focusedEntity).toBe(nested);+ input.keysPressed.clear();+ nestedHidden = true;+ 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(nested, UINode, node => { node.display = UIDisplay.None; });+ expect(inspectFocusTraversal(world).entries.find(e => e.entity === outer)?.skipped).toBeNull();+ world.remove(nested, UIDialog);+ world.update(nested, UINode, node => { node.display = UIDisplay.Flex; });+ expect(inspectFocusTraversal(world).entries.find(e => e.entity === outer)?.skipped).toBeNull();+ expect(inspectFocusTraversal(world).entries.find(e => e.entity === page)?.skipped).toBe('outside-dialog');+});++it('retains independent dialog branches when one branch contains a nested dialog', () => {+ const world = harness.app.world;+ const outer = control(0), nested = control(1), sibling = control(2);+ world.insert(nested, Parent, { entity: outer });+ for (const root of [outer, nested, sibling]) {+ world.insert(root, UIDialog);+ world.insert(root, UINode, { display: UIDisplay.Flex });+ }+ expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', null, null]);+});diff --git a/tools/ui-events-play-browser.tsx b/tools/ui-events-play-browser.tsxindex b5fe1d103..7a3113f1c 100644--- a/tools/ui-events-play-browser.tsx+++ b/tools/ui-events-play-browser.tsx@@ -38,7 +38,7 @@ function Fixture() {return <main style={{ padding: 16, height: '100vh', display: 'flex', flexDirection: 'column', gap: 12 }}><h2>UI Events · production Play realm browser verification</h2><div><button onClick={() => void start()}>Start Play</button> <button onClick={() => { PlayInspect.stop(); PlayRealm.stop(); }}>Stop Play</button> <button onClick={() => setMounted(value => !value)}>Toggle panel</button> <button onClick={() => void inspect()}>Read runtime snapshot</button></div>- <small>Game keys: M opens the runtime button as a dialog; R closes it; D disables current focus; E restores disabled controls; H hides the dialog parent; V shows it again; T toggles a real text input (outside text editing).</small>+ <small>Game keys: M opens a dialog; N opens a nested confirmation; R closes dialogs; D disables current focus; E restores controls; H hides the dialog parent; V shows it; T toggles a text input (outside text editing).</small><p role="status">{realm.playing ? 'Playing' : 'Stopped'} · {realm.ready ? 'Ready' : 'Not ready'} · {realm.error ?? ''}</p><div style={{ display: 'flex', gap: 16, flex: 1, minHeight: 0 }}><div style={{ width: 800, height: 600, flexShrink: 0 }} ref={attach} />diff --git a/tools/ui-events-play-project.ts b/tools/ui-events-play-project.tsindex 3beb248f8..3452a2e6e 100644--- a/tools/ui-events-play-project.ts+++ b/tools/ui-events-play-project.ts@@ -9,7 +9,7 @@ addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Reif (inside === null) return;const partial = world.findEntityByName('Partial')!;const inner = world.findEntityByName('InnerMask')!;- let count = 0, dynamic: Entity | null = null, dialogHost: Entity | null = null;+ let count = 0, dynamic: Entity | null = null, dialogHost: Entity | null = null, nested: Entity | null = null;let textField: TextInputHandle | null = null;const restore = new Set<Entity>();installed.set(world, () => {@@ -31,8 +31,31 @@ addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Reworld.insert(dynamic, UIDialog, { closeOnEscape: false, closeOnBackdrop: false });world.insert(dynamic, Text, { ...world.get(dynamic, Text), content: 'Dialog confirm' });}+ if (input.isKeyPressed('KeyN') && dynamic !== null && dialogHost !== null && world.valid(dynamic)) {+ // Real hierarchy: an outer modal contains a page button and a nested modal.+ world.remove(dynamic, UIDialog);+ world.insert(dialogHost, UIDialog, { closeOnEscape: false, closeOnBackdrop: false });+ if (nested === null) {+ nested = world.spawn('Nested confirm');+ world.insert(nested, Transform, {});+ world.insert(nested, UINode, { position: 1, width: px(150), height: px(32), insetLeft: px(20), insetTop: px(75) });+ world.insert(nested, UIVisual, { visualType: 1, color: { r: 0.55, g: 0.3, b: 0.15, a: 1 } });+ world.insert(nested, Text, { content: 'Nested confirm', fontFamily: 'Arial', fontSize: 16 });+ world.insert(nested, Interactable, { enabled: true, raycastTarget: true, blockRaycast: true });+ world.insert(nested, Focusable, { tabIndex: 4 });+ world.insert(nested, UIDialog, { closeOnEscape: false, closeOnBackdrop: false });+ world.setParent(nested, dialogHost);+ events.on(nested, 'click', () => {+ if (nested !== null) world.despawn(nested);+ nested = null;+ });+ }+ }if (input.isKeyPressed('KeyR') && dynamic !== null && world.valid(dynamic)) {world.remove(dynamic, UIDialog);+ if (dialogHost !== null) world.remove(dialogHost, UIDialog);+ if (nested !== null) world.despawn(nested);+ nested = null;world.insert(dynamic, Text, { ...world.get(dynamic, Text), content: 'Runtime button' });}if (dialogHost !== null && world.valid(dialogHost)) {@@ -54,7 +77,7 @@ addSystemToSchedule(Schedule.Update, defineSystem([Res(UIEvents), GetWorld(), Recount++;world.insert(inside, Text, { ...world.get(inside, Text), content: `Clicks ${count}` });world.insert(inside, UINode, { ...world.get(inside, UINode), width: px(count % 2 ? 160 : 120) });- if (dynamic !== null) { world.despawn(dynamic); dynamic = null; if (dialogHost !== null) world.despawn(dialogHost); dialogHost = null; }+ if (dynamic !== null) { if (nested !== null) world.despawn(nested); nested = null; world.despawn(dynamic); dynamic = null; if (dialogHost !== null) world.despawn(dialogHost); dialogHost = null; }else {dialogHost = world.spawn('Runtime dialog host');world.insert(dialogHost, Transform, {});