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.

Share focus traversal policy with UI diagnostics (#72)

YHHeffe193ee883
diff --git a/desktop b/desktop
index 17bbe943a..fb87c4636 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 17bbe943a3bbfb0f264218d20a69b2eaafcf6020
+Subproject commit fb87c46365a03c78f45c8d47c80d97438939767f
diff --git a/examples/ui-localization-debug/README.md b/examples/ui-localization-debug/README.md
index 13187bce6..d520935e8 100644
--- a/examples/ui-localization-debug/README.md
+++ b/examples/ui-localization-debug/README.md
@@ -1,6 +1,6 @@
# UI localization debug
-Open this project and use Window → UI Text Inspector. Wait for layout and
+Open this project and use Window → UI Inspector → Text. Wait for layout and
capture again. Original / Accents + 35% / Accents + 100% inspect a snapshot
without editing or saving scene content. Select jumps to the authored entity.
Box and text sizes are local display pixels, before Clip / Ellipsis truncation.
@@ -17,5 +17,12 @@ fit verdict. Custom font assets, rich text and unresolved boxes are also marked
for review. Bounds cover glyph advances and line height, not stroke, shadow or
ink overhang. Host fonts can differ; inspect the exported game on each target.
-This is RM-009 stage one. Focus paths, hit regions, platform shaping,
+Focus order shows the editor snapshot of the runtime Tab policy: ascending
+indices, stable ECS query order on ties, disabled/hidden controls skipped and
+open dialog subtrees restricting traversal. It does not move focus; edit a
+control, capture again, then Select to find it in Details. The host must expose
+resolved visibility, otherwise a warning is shown. This does not verify actual
+keyboard delivery, screen readers or IME on a target device.
+
+This is a partial RM-009 delivery. Hit regions, platform shaping,
real IME/device acceptance and layout cache performance remain separate work.
diff --git a/examples/ui-localization-debug/VALIDATION.md b/examples/ui-localization-debug/VALIDATION.md
index 16f3630ea..aed28c0db 100644
--- a/examples/ui-localization-debug/VALIDATION.md
+++ b/examples/ui-localization-debug/VALIDATION.md
@@ -24,7 +24,7 @@ remains In Progress; this is not complex-script or device acceptance.
## Limits and observations
Arabic joining/bidi, Thai shaping, rich-text metrics, custom-font metrics,
-real IME, minigame/native devices, focus paths, hit regions and performance
+real IME, minigame/native devices, actual device focus delivery, hit regions and performance
acceptance are not covered. Host fallback fonts require visual review; this
inspector measures advances/line height, not ink, stroke or shadow extents.
@@ -46,3 +46,23 @@ Electron or native test window.
Export with `node pipeline/bin/estella.mjs export examples/ui-localization-debug
--out <output-directory>`; serve that directory with a normal HTTP server.
+
+## Focus inspection increment — 2026-10-08
+
+The runtime Tab path and SDK `inspectFocusTraversal` share the same read-only
+policy. The editor UI Inspector has Text and Focus order views. Inspection
+never moves focus or emits focus/click events. This is the editor realm's
+snapshot; live-game-only dialogs and scripts need runtime acceptance separately.
+
+- SDK: 14 focus tests pass, including four new inspection checks. Runtime
+ forward/reverse Tab navigation agrees with inspection, disabled controls are
+ reported, host hierarchical visibility is respected, and closing a dialog
+ restores controls outside its subtree. Missing host visibility is disclosed.
+- Editor: 26 existing i18n/menu/controller checks, typecheck and Vite build pass.
+- Built-in WebGL2 fixture: 14/14 checks pass, including host visibility, the
+ sample's three buttons in order, and unchanged authored scene data.
+- Manual Web checks: select LocaleButton, disable Interactable in Details,
+ observe stale snapshot/disabled selection, refresh to two navigable controls
+ and one disabled entry, undo, and observe stale state again. No edit was saved.
+- No local native test runner was launched. The card remains In Progress;
+ layout boundaries, pointer hit diagnostics and device acceptance remain open.
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d971ffb46..931ee1c1f 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1542 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1547 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3714,6 +3714,11 @@ NoWrap = 0
Wrap = 1
```
+## FocusInspectionWorld — type @experimental
+```
+Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>
+```
+
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -3739,6 +3744,24 @@ static new (): FocusPlugin
static prototype: FocusPlugin
```
+## FocusSkipReason — type @experimental
+```
+'disabled' | 'hidden' | 'outside-dialog'
+```
+
+## FocusTraversalEntry — interface @experimental
+```
+entity: number
+skipped: FocusSkipReason | null
+tabIndex: number
+```
+
+## FocusTraversalInspection — interface @experimental
+```
+entries: FocusTraversalEntry[]
+visibilityResolved: boolean
+```
+
## Focusable — const @experimental
```
ComponentDef<FocusableData>
@@ -11378,6 +11401,11 @@ InputPlugin
InputRouter
```
+## inspectFocusTraversal — function @experimental
+```
+(world: FocusInspectionWorld): FocusTraversalInspection
+```
+
## inspectTextLayout — function @experimental
```
(text: string, opts: TextInspectionOptions): TextInspection
@@ -11455,7 +11483,7 @@ InputRouter
## isDialogOpen — function @experimental
```
-(world: World, root: Entity): boolean
+(world: Pick<World, "has" | "get">, root: Entity): boolean
```
## isDropdownOpen — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a34a7e988..a5b27f766 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 96 beta · 1561 experimental · 3 deprecated
+Symbols: 115 public · 96 beta · 1566 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -3722,6 +3722,11 @@ NoWrap = 0
Wrap = 1
```
+## FocusInspectionWorld — type @experimental
+```
+Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>
+```
+
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -3747,6 +3752,24 @@ static new (): FocusPlugin
static prototype: FocusPlugin
```
+## FocusSkipReason — type @experimental
+```
+'disabled' | 'hidden' | 'outside-dialog'
+```
+
+## FocusTraversalEntry — interface @experimental
+```
+entity: number
+skipped: FocusSkipReason | null
+tabIndex: number
+```
+
+## FocusTraversalInspection — interface @experimental
+```
+entries: FocusTraversalEntry[]
+visibilityResolved: boolean
+```
+
## Focusable — const @experimental
```
ComponentDef<FocusableData>
@@ -11624,6 +11647,11 @@ InputPlugin
InputRouter
```
+## inspectFocusTraversal — function @experimental
+```
+(world: FocusInspectionWorld): FocusTraversalInspection
+```
+
## inspectTextLayout — function @experimental
```
(text: string, opts: TextInspectionOptions): TextInspection
@@ -11706,7 +11734,7 @@ InputRouter
## isDialogOpen — function @experimental
```
-(world: World, root: Entity): boolean
+(world: Pick<World, "has" | "get">, root: Entity): boolean
```
## isDropdownOpen — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d1f84540b..385982e3d 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 93 beta · 1541 experimental · 3 deprecated
+Symbols: 115 public · 93 beta · 1546 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3709,6 +3709,11 @@ NoWrap = 0
Wrap = 1
```
+## FocusInspectionWorld — type @experimental
+```
+Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>
+```
+
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -3734,6 +3739,24 @@ static new (): FocusPlugin
static prototype: FocusPlugin
```
+## FocusSkipReason — type @experimental
+```
+'disabled' | 'hidden' | 'outside-dialog'
+```
+
+## FocusTraversalEntry — interface @experimental
+```
+entity: number
+skipped: FocusSkipReason | null
+tabIndex: number
+```
+
+## FocusTraversalInspection — interface @experimental
+```
+entries: FocusTraversalEntry[]
+visibilityResolved: boolean
+```
+
## Focusable — const @experimental
```
ComponentDef<FocusableData>
@@ -11373,6 +11396,11 @@ InputPlugin
InputRouter
```
+## inspectFocusTraversal — function @experimental
+```
+(world: FocusInspectionWorld): FocusTraversalInspection
+```
+
## inspectTextLayout — function @experimental
```
(text: string, opts: TextInspectionOptions): TextInspection
@@ -11450,7 +11478,7 @@ InputRouter
## isDialogOpen — function @experimental
```
-(world: World, root: Entity): boolean
+(world: Pick<World, "has" | "get">, root: Entity): boolean
```
## isDropdownOpen — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 921e669ca..c943b9f71 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1563 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1568 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3709,6 +3709,11 @@ NoWrap = 0
Wrap = 1
```
+## FocusInspectionWorld — type @experimental
+```
+Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>
+```
+
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -3734,6 +3739,24 @@ static new (): FocusPlugin
static prototype: FocusPlugin
```
+## FocusSkipReason — type @experimental
+```
+'disabled' | 'hidden' | 'outside-dialog'
+```
+
+## FocusTraversalEntry — interface @experimental
+```
+entity: number
+skipped: FocusSkipReason | null
+tabIndex: number
+```
+
+## FocusTraversalInspection — interface @experimental
+```
+entries: FocusTraversalEntry[]
+visibilityResolved: boolean
+```
+
## Focusable — const @experimental
```
ComponentDef<FocusableData>
@@ -11662,6 +11685,11 @@ InputPlugin
InputRouter
```
+## inspectFocusTraversal — function @experimental
+```
+(world: FocusInspectionWorld): FocusTraversalInspection
+```
+
## inspectTextLayout — function @experimental
```
(text: string, opts: TextInspectionOptions): TextInspection
@@ -11744,7 +11772,7 @@ InputRouter
## isDialogOpen — function @experimental
```
-(world: World, root: Entity): boolean
+(world: Pick<World, "has" | "get">, root: Entity): boolean
```
## isDropdownOpen — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 385a68205..020da6d94 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 91 beta · 1554 experimental · 3 deprecated
+Symbols: 115 public · 91 beta · 1559 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -3709,6 +3709,11 @@ NoWrap = 0
Wrap = 1
```
+## FocusInspectionWorld — type @experimental
+```
+Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>
+```
+
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -3734,6 +3739,24 @@ static new (): FocusPlugin
static prototype: FocusPlugin
```
+## FocusSkipReason — type @experimental
+```
+'disabled' | 'hidden' | 'outside-dialog'
+```
+
+## FocusTraversalEntry — interface @experimental
+```
+entity: number
+skipped: FocusSkipReason | null
+tabIndex: number
+```
+
+## FocusTraversalInspection — interface @experimental
+```
+entries: FocusTraversalEntry[]
+visibilityResolved: boolean
+```
+
## Focusable — const @experimental
```
ComponentDef<FocusableData>
@@ -11414,6 +11437,11 @@ InputPlugin
InputRouter
```
+## inspectFocusTraversal — function @experimental
+```
+(world: FocusInspectionWorld): FocusTraversalInspection
+```
+
## inspectTextLayout — function @experimental
```
(text: string, opts: TextInspectionOptions): TextInspection
@@ -11491,7 +11519,7 @@ InputRouter
## isDialogOpen — function @experimental
```
-(world: World, root: Entity): boolean
+(world: Pick<World, "has" | "get">, root: Entity): boolean
```
## isDropdownOpen — function @experimental
diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.ts
index 76dd68195..ddc442162 100644
--- a/sdk/src/core-ui.ts
+++ b/sdk/src/core-ui.ts
@@ -65,6 +65,10 @@ export {
FillOrigin,
Draggable,
DragState,
+ inspectFocusTraversal,
+ type FocusTraversalInspection, type FocusInspectionWorld,
+ type FocusTraversalEntry,
+ type FocusSkipReason,
Focusable,
FocusManager,
FocusManagerState,
diff --git a/sdk/src/ui/behavior/dialog.ts b/sdk/src/ui/behavior/dialog.ts
index edad60336..d075b8b13 100644
--- a/sdk/src/ui/behavior/dialog.ts
+++ b/sdk/src/ui/behavior/dialog.ts
@@ -34,7 +34,7 @@ export const UIDialog = defineComponent<UIDialogData>('UIDialog', {
});
/** True when the dialog root's subtree is displayed. */
-export function isDialogOpen(world: World, root: Entity): boolean {
+export function isDialogOpen(world: Pick<World, 'has' | 'get'>, root: Entity): boolean {
if (!world.has(root, UINode)) return false;
return (world.get(root, UINode) as UINodeData).display !== UIDisplay.None;
}
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index e8ca6fb42..38590f541 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -384,6 +384,8 @@ export { TextInputPlugin, textInputPlugin } from './text/text-input-plugin';
export { DragPlugin, dragPlugin } from './input/drag';
+export { inspectFocusTraversal, type FocusTraversalInspection, type FocusInspectionWorld, type FocusTraversalEntry, type FocusSkipReason } from './input/focus-inspection';
+
export { FocusPlugin, focusPlugin } from './input/focus';
export {
diff --git a/sdk/src/ui/input/focus-inspection.ts b/sdk/src/ui/input/focus-inspection.ts
new file mode 100644
index 000000000..76f1c2078
--- /dev/null
+++ b/sdk/src/ui/input/focus-inspection.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { World } from '../../ecs/world';
+import type { Entity } from '../../types';
+import { worldEngineApi } from '../../ecs/bridge/engineApi';
+import { Focusable } from './focusable';
+import { Interactable } from './interactable';
+import { UIDialog, isDialogOpen } from '../behavior/dialog';
+import { walkParentChain } from '../util/helpers';
+
+/** Read-only scene queries needed to inspect focus. @experimental */
+export type FocusInspectionWorld = Pick<World, 'getWasmModule' | 'getCppRegistry' | 'getEntitiesWithComponents' | 'valid' | 'has' | 'get'>;
+
+/** Why a focusable is absent from the current Tab ring. @experimental */
+export type FocusSkipReason = 'disabled' | 'hidden' | 'outside-dialog';
+/** A read-only focus traversal entry. Equal indices keep ECS query order. @experimental */
+export interface FocusTraversalEntry {
+ entity: Entity;
+ tabIndex: number;
+ skipped: FocusSkipReason | null;
+}
+/** The same snapshot used by keyboard traversal. @experimental */
+export interface FocusTraversalInspection {
+ entries: FocusTraversalEntry[];
+ /** False when the host cannot report resolved hierarchical visibility. */
+ visibilityResolved: boolean;
+}
+
+/** Inspect Tab order without moving focus or emitting events. @experimental */
+export function inspectFocusTraversal(world: FocusInspectionWorld): FocusTraversalInspection {
+ const engine = worldEngineApi(world);
+ const registry = world.getCppRegistry();
+ const visibilityResolved = !!(registry && engine?.getUINodeHiddenInTree);
+ const roots = new Set(world.getEntitiesWithComponents([UIDialog])
+ .filter(entity => isDialogOpen(world, entity)));
+ const entries: FocusTraversalEntry[] = [];
+ for (const entity of world.getEntitiesWithComponents([Focusable])) {
+ if (!world.valid(entity)) continue;
+ let skipped: FocusSkipReason | null = null;
+ if (world.has(entity, Interactable) && !world.get(entity, Interactable).enabled) {
+ skipped = 'disabled';
+ } else if (visibilityResolved && engine!.getUINodeHiddenInTree!(registry!, entity)) {
+ skipped = 'hidden';
+ } else if (roots.size > 0 && !roots.has(entity)) {
+ let inside = false;
+ walkParentChain(world, entity, ancestor => {
+ inside = roots.has(ancestor);
+ return inside;
+ });
+ if (!inside) skipped = 'outside-dialog';
+ }
+ entries.push({ entity, tabIndex: world.get(entity, Focusable).tabIndex, skipped });
+ }
+ entries.sort((a, b) => a.tabIndex - b.tabIndex);
+ return { entries, visibilityResolved };
+}
diff --git a/sdk/src/ui/input/focus.ts b/sdk/src/ui/input/focus.ts
index 044651808..0e70c16e8 100644
--- a/sdk/src/ui/input/focus.ts
+++ b/sdk/src/ui/input/focus.ts
@@ -14,8 +14,7 @@ import type { InteractableData } from './interactable';
import { UIInteraction } from './interactable';
import type { UIInteractionData } from './interactable';
import { TextInput } from '../text/text-input';
-import { UIDialog, isDialogOpen } from '../behavior/dialog';
-import { walkParentChain } from '../util/helpers';
+import { inspectFocusTraversal } from './focus-inspection';
import { playModeOnly } from '../../ecs/env';
import { UIEvents, UIEventQueue, UIEventType } from '../core/events';
import { PluginName } from '../../ecs/systemLabels';
@@ -41,26 +40,6 @@ export class FocusPlugin implements Plugin {
!!(engine?.getUINodeHiddenInTree && registry
&& engine.getUINodeHiddenInTree(registry, e));
- // An open modal traps the Tab ring: only focusables inside an open
- // UIDialog subtree participate while one is up (the scrim already
- // blocks pointer focus outside).
- const openDialogRoots = (): Entity[] =>
- world.getEntitiesWithComponents([UIDialog]).filter((e) => isDialogOpen(world, e));
- const insideAny = (entity: Entity, roots: Entity[]): boolean => {
- if (roots.length === 0) return true;
- const set = new Set(roots.map((r) => r as number));
- if (set.has(entity as number)) return true;
- let inside = false;
- walkParentChain(world, entity, (ancestor) => {
- if (set.has(ancestor as number)) {
- inside = true;
- return true;
- }
- return false;
- });
- return inside;
- };
-
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Input), Res(UIEvents)],
(input: InputState, events: UIEventQueue) => {
@@ -129,21 +108,8 @@ export class FocusPlugin implements Plugin {
}
function getSortedFocusables(): Entity[] {
- const trapRoots = openDialogRoots();
- const entries: { entity: Entity; tabIndex: number }[] = [];
- for (const entity of focusableEntities) {
- if (!world.valid(entity)) continue;
- if (world.has(entity, Interactable)) {
- const interactable = world.get(entity, Interactable) as InteractableData;
- if (!interactable.enabled) continue;
- }
- if (hiddenInTree(entity)) continue;
- if (!insideAny(entity, trapRoots)) continue;
- const f = world.get(entity, Focusable) as FocusableData;
- entries.push({ entity, tabIndex: f.tabIndex });
- }
- entries.sort((a, b) => a.tabIndex - b.tabIndex);
- return entries.map(e => e.entity);
+ return inspectFocusTraversal(world).entries
+ .filter(entry => entry.skipped === null).map(entry => entry.entity);
}
function setFocus(entity: Entity, visible: boolean): void {
diff --git a/sdk/src/ui/util/helpers.ts b/sdk/src/ui/util/helpers.ts
index c9473887c..808a5e3d3 100644
--- a/sdk/src/ui/util/helpers.ts
+++ b/sdk/src/ui/util/helpers.ts
@@ -77,7 +77,7 @@ export function getUINodeHeight(entity: Entity): number {
export function walkParentChain(
- world: World, entity: Entity,
+ world: Pick<World, 'has' | 'get' | 'valid'>, entity: Entity,
callback: (ancestor: Entity) => boolean,
): void {
let current = entity;
diff --git a/sdk/tests/ui-focus-inspection.test.ts b/sdk/tests/ui-focus-inspection.test.ts
new file mode 100644
index 000000000..c2dd24cce
--- /dev/null
+++ b/sdk/tests/ui-focus-inspection.test.ts
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect, beforeEach } from 'vitest';
+import { flushPendingRegistrations } from '../src/app/app';
+import { Parent } from '../src/ecs/component';
+import { Input, InputState } from '../src/input/input';
+import { UIEvents, UIEventQueue } from '../src/ui/core/events';
+import { UINode, UIDisplay } from '../src/ui/core/ui-node';
+import { UIDialog } from '../src/ui/behavior/dialog';
+import { Focusable, FocusManager } from '../src/ui/input/focusable';
+import { Interactable } from '../src/ui/input/interactable';
+import { inspectFocusTraversal } from '../src/ui/input/focus-inspection';
+import { focusPlugin } from '../src/ui/input/focus';
+import { bootMockApp } from './helpers/mockApp';
+import type { Entity } from '../src/types';
+let harness: ReturnType<typeof bootMockApp>;
+beforeEach(() => { harness = bootMockApp(); });
+function control(index: number, enabled = true) {
+ const entity = harness.app.world.spawn();
+ harness.app.world.insert(entity, Focusable, { tabIndex: index, isFocused: false });
+ harness.app.world.insert(entity, Interactable, { enabled });
+ return entity;
+}
+describe('focus inspection shares runtime traversal', () => {
+ it('reports disabled entries and stable ties, without focusing or writing', async () => {
+ const { app } = harness;
+ app.insertResource(Input, new InputState());
+ app.insertResource(UIEvents, new UIEventQueue());
+ focusPlugin.build(app);
+ flushPendingRegistrations(app);
+ const first = control(2), skipped = control(1, false), last = control(2);
+ const snapshot = inspectFocusTraversal(app.world);
+ expect(snapshot.entries.map(e => e.entity)).toEqual([skipped, first, last]);
+ expect(snapshot.entries[0].skipped).toBe('disabled');
+ expect(app.getResource(FocusManager).focusedEntity).toBeNull();
+ expect(app.world.get(first, Focusable).isFocused).toBe(false);
+ const input = app.getResource(Input);
+ input.keysPressed.add('Tab');
+ await app.tick(1 / 60);
+ expect(app.getResource(FocusManager).focusedEntity).toBe(first);
+ input.keysPressed.clear();
+ input.keysDown.add('Shift');
+ input.keysPressed.add('Tab');
+ await app.tick(1 / 60);
+ expect(app.getResource(FocusManager).focusedEntity).toBe(last);
+ });
+ it('uses host hierarchical visibility, with disabled taking precedence', () => {
+ const hidden = control(0), disabled = control(1, false), shown = control(2);
+ harness.module.getUINodeHiddenInTree = (_registry: unknown, entity: Entity) => entity !== shown;
+ const result = inspectFocusTraversal(harness.app.world);
+ expect(result.visibilityResolved).toBe(true);
+ expect(result.entries.map(e => [e.entity, e.skipped])).toEqual([[hidden, 'hidden'], [disabled, 'disabled'], [shown, null]]);
+ });
+ it('limits an open dialog to its root and descendants; closing restores the ring', () => {
+ const world = harness.app.world;
+ const outside = control(0), root = control(1), child = control(2);
+ world.insert(root, UIDialog);
+ world.insert(root, UINode, { display: UIDisplay.Flex });
+ world.insert(child, Parent, { entity: root });
+ expect(inspectFocusTraversal(world).entries.map(e => e.skipped)).toEqual(['outside-dialog', null, null]);
+ world.update(root, UINode, node => { node.display = UIDisplay.None; });
+ expect(inspectFocusTraversal(world).entries.find(e => e.entity === outside)?.skipped).toBeNull();
+ });
+ it('discloses unavailable host visibility rather than asserting visible bounds', () => {
+ control(0);
+ delete harness.module.getUINodeHiddenInTree;
+ expect(inspectFocusTraversal(harness.app.world).visibilityResolved).toBe(false);
+ });
+});
diff --git a/tools/ui-localization-browser.tsx b/tools/ui-localization-browser.tsx
index 1d13bf8e0..02e69721c 100644
--- a/tools/ui-localization-browser.tsx
+++ b/tools/ui-localization-browser.tsx
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
import '../desktop/src/main';
-import { captureUITextRows } from '../desktop/src/panels/UITextDebugPanel';
+import { captureUITextRows, captureUIFocusRows } from '../desktop/src/panels/UITextDebugPanel';
import { EngineHost } from '../desktop/src/engine/EngineHost';
import { SceneModel } from '../desktop/src/engine/SceneModel';
import { useEditorStore } from '../desktop/src/store/editorStore';
@@ -38,6 +38,10 @@ for (const name of ['Arabic — shaping unverified', 'Thai — shaping unverifie
const wrapped = rows.find(row => row.name === 'Wrapped paragraph')!;
check(inspectTextLayout(wrapped.text.content, { ...options, width: wrapped.width, height: wrapped.height, wordWrap: true }).verticalOverflow, 'Wrapped paragraph detects vertical truncation');
check(JSON.stringify(SceneModel.serialize()) === before, 'Inspection / pseudolocalization leave authored scene unchanged');
+const focusRows = captureUIFocusRows();
+check(focusRows.visibilityResolved, 'Focus inspection uses host hierarchical visibility');
+check(focusRows.entries.filter(e => e.order !== null).map(e => e.name).join(',') === 'LocaleButton,PseudoButton,WidthButton', 'Focus inspection reports the three authored buttons in runtime order');
+check(JSON.stringify(SceneModel.serialize()) === before, 'Focus snapshot leaves authored scene unchanged');
status.textContent += `RESULT ${passed} passed, ${failed} failed · ${EngineHost.activeBackend}`;
const dismiss = document.createElement('button');
dismiss.textContent = 'Dismiss verification report';