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): restrict nested dialog focus to inner modal (#84)

YHHd50c85dab4ab
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 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 again
restores recorded history without automatically recording. Stop Play also
ends 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.md
index 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 remain
separate 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.ts
index 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): FocusTravers
const 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.ts
index 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.tsx
index 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.ts
index 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(), Re
if (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(), Re
world.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(), Re
count++;
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, {});