@ignifx/ui 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignifx/ui",
3
- "version": "0.0.0",
3
+ "version": "0.1.0",
4
4
  "description": "ignifx UI: DOM overlay host, focus routing, world and HUD text.",
5
5
  "keywords": [
6
6
  "ignifx",
@@ -9,6 +9,11 @@
9
9
  "homepage": "https://ignifx.com",
10
10
  "license": "Apache-2.0",
11
11
  "author": "Astrum Forge Studios",
12
+ "repository": {
13
+ "type": "git",
14
+ "url": "git+https://github.com/astrum-forge/ignifx.git",
15
+ "directory": "packages/ui"
16
+ },
12
17
  "files": [
13
18
  "dist",
14
19
  "skills"
@@ -24,39 +29,56 @@
24
29
  },
25
30
  "publishConfig": {
26
31
  "access": "public",
27
- "provenance": true
28
- },
29
- "scripts": {
30
- "build": "tsdown",
31
- "typecheck": "tsc --build tsconfig.json tsconfig.test.json",
32
- "test": "vitest run --project node --root ../.. packages/ui",
33
- "api-report": "api-extractor run --verbose",
34
- "docs:api": "typedoc",
35
- "api-report:update": "api-extractor run --local --verbose",
36
- "pack-check": "publint && attw --pack . --profile esm-only"
32
+ "provenance": false
37
33
  },
38
34
  "devDependencies": {
39
- "@arethetypeswrong/cli": "catalog:",
40
- "@ignifx/core": "workspace:*",
41
- "@microsoft/api-extractor": "catalog:",
42
- "@types/webxr": "catalog:",
43
- "@webgpu/types": "catalog:",
44
- "publint": "catalog:",
45
- "tsdown": "catalog:",
46
- "typedoc": "catalog:",
47
- "typedoc-plugin-markdown": "catalog:",
48
- "typescript-native": "catalog:",
49
- "vitest": "catalog:"
35
+ "@arethetypeswrong/cli": "^0.18.5",
36
+ "@babylonjs/lite": "1.27.0",
37
+ "@microsoft/api-extractor": "^7.59.0",
38
+ "@types/webxr": "^0.5.0",
39
+ "@webgpu/types": "^0.1.72",
40
+ "publint": "^0.3.24",
41
+ "tsdown": "^0.23.0",
42
+ "typedoc": "^0.28.20",
43
+ "typedoc-plugin-markdown": "^4.13.0",
44
+ "typescript-native": "npm:typescript@7.0.2",
45
+ "vitest": "^5.0.0",
46
+ "@ignifx/core": "0.1.0",
47
+ "@ignifx/input": "0.1.0"
50
48
  },
51
49
  "peerDependencies": {
52
- "@ignifx/core": "workspace:*"
50
+ "@babylonjs/lite": "1.27.0",
51
+ "@ignifx/core": "0.1.0",
52
+ "@ignifx/input": "0.1.0"
53
+ },
54
+ "peerDependenciesMeta": {
55
+ "@ignifx/input": {
56
+ "optional": true
57
+ }
53
58
  },
54
59
  "ignifx": {
55
60
  "extension": true,
56
61
  "engine": ">=0.0.0 <1.0.0",
57
62
  "requires": [],
58
- "optional": [],
59
- "capabilities": [],
63
+ "optional": [
64
+ "@ignifx/input"
65
+ ],
66
+ "capabilities": [
67
+ "components",
68
+ "systems",
69
+ "services",
70
+ "settings",
71
+ "assets"
72
+ ],
60
73
  "skill": "./skills/ui/SKILL.md"
74
+ },
75
+ "scripts": {
76
+ "build": "tsdown",
77
+ "typecheck": "tsc --build tsconfig.json tsconfig.test.json",
78
+ "test": "vitest run --project node --root ../.. packages/ui",
79
+ "api-report": "api-extractor run --verbose",
80
+ "docs:api": "typedoc",
81
+ "api-report:update": "api-extractor run --local --verbose",
82
+ "pack-check": "publint && attw --pack . --profile esm-only"
61
83
  }
62
- }
84
+ }
@@ -1,46 +1,349 @@
1
1
  ---
2
2
  name: ui
3
- description: Builds game UI in ignifx with @ignifx/ui: the DOM overlay host and layers, scaling modes, input focus routing, world-space anchors, world and HUD text, virtual joysticks and buttons for touch, dialogs, toasts, loading screens, and localization. Use when adding or editing menus, HUDs, on-screen text, touch controls, or overlay UI in an ignifx project, or when the user mentions @ignifx/ui, HudText, WorldAnchor, or VirtualJoystick.
3
+ description: Builds game UI in ignifx with @ignifx/ui: the DOM overlay host and layers, scaling modes, input focus routing, world-space anchors, world and HUD text on Babylon Lite's text renderer, menus and menu stacks, virtual joysticks and buttons for touch, dialogs, toasts, loading screens, and localization. Use when adding or editing menus, title/pause/settings screens, HUDs, on-screen text, touch controls, or overlay UI in an ignifx project, or when the user mentions @ignifx/ui, Menu, MenuStack, HudText, WorldAnchor, VirtualJoystick, or app.i18n.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.0.0-unreleased"
6
+ ignifx-version: "0.1.0"
7
7
  ---
8
8
 
9
9
  # @ignifx/ui
10
10
 
11
- > **Scaffold notice.** ignifx is in the planning phase and `@ignifx/ui` is an empty package. Every section below is filled by Phase 8 of `docs/plan/engineering-plan.md`; until then this file makes no API claims (`CONSTITUTION.md` Article V).
12
-
13
11
  ## What this is / when to use
14
12
 
15
- `@ignifx/ui` is the ignifx extension that provides the DOM overlay UI host, input focus routing, and world and HUD text components _(populated in Phase 8)_.
13
+ **Game UI in ignifx is HTML.** `@ignifx/ui` puts one absolutely positioned `<div>` over the canvas
14
+ and lets a game mount React, Svelte, Vue or plain DOM into named layers inside it. That is what
15
+ gives every game accessibility, real fonts, real layout, and any framework the team already knows.
16
+
17
+ Use the DOM for menus, HUDs, dialogs and touch controls. Use the **text components** only for text
18
+ that has to be drawn by the GPU: text that belongs in the world (`WorldText`), text that follows an
19
+ entity (`WorldText2D`), and pixel-exact HUD text that has to show up in `captureScreenshot()`
20
+ (`HudText`).
21
+
22
+ Everything registers headlessly. With no canvas, `app.ui.root` is `null`, every DOM member is a
23
+ documented no-op, and the components keep their state — so the same script runs in a Node test.
16
24
 
17
25
  ## Environment
18
26
 
19
- Engine version, the pinned Babylon Lite version, and the registration snippet for this extension _(populated in Phase 8)_.
27
+ - Engine: ignifx `0.0.0-unreleased`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
28
+ - WebGPU only, browser and Electron. Babylon Lite `1.27.0` is a peer dependency.
29
+ - `@ignifx/input` is an **optional** peer: only `VirtualJoystick` and `VirtualButton` need it.
30
+ - Register it like any extension; nothing happens at import time.
31
+
32
+ ```ts
33
+ import { createApp } from "ignifx";
34
+ import { ui } from "@ignifx/ui";
35
+
36
+ const canvas = document.querySelector("canvas");
37
+ if (canvas instanceof HTMLCanvasElement) {
38
+ const app = await createApp({
39
+ canvas,
40
+ extensions: [ui({ scaling: "fit", referenceResolution: [640, 360] })],
41
+ });
42
+ await app.start();
43
+ }
44
+ ```
45
+
46
+ `ignifx.config.ts` carries the same settings under `ui`:
47
+
48
+ | Setting | Default | Meaning |
49
+ | --------------------- | ---------------------------- | --------------------------------------- |
50
+ | `scaling` | `"css"` | `"css"`, `"fit"` or `"dpi"` — see below |
51
+ | `referenceResolution` | `[1920, 1080]` | The `[w, h]` `"fit"` scales to |
52
+ | `layers` | `["hud", "menu", "overlay"]` | Created up front, back to front |
53
+ | `visible` | `true` | Whether the overlay is shown |
54
+
55
+ `ui()` also takes `strings` (a `.i18n.json` address to load at start-up) and `locale`.
20
56
 
21
57
  ## Mental model
22
58
 
23
- How this subsystem's components, services, and phases fit into the App → World → Entity model _(populated in Phase 8)_.
59
+ ```
60
+ app.ui (UiHost)
61
+ ├─ root the <div> over the canvas; pointer-events: none
62
+ ├─ layer(name) one <div> per layer, z-index 10, 20, 30 …
63
+ ├─ scaling "css" | "fit" | "dpi"; layout · pixelMapping · onLayoutChanged
64
+ ├─ visible · pointerOverUi · keyboardHasFocus · refresh()
65
+ app.i18n (I18nService)
66
+ └─ load(handle) · t(key, params) · locale · onLocaleChanged · availableLocales
67
+
68
+ components WorldAnchor · HudText · WorldText2D · WorldText
69
+ helpers Menu · MenuStack · Dialog · Toast · LoadingScreen · VirtualJoystick · VirtualButton
70
+ ```
71
+
72
+ **One system, `PreRender` order 1100** — after core's camera sync at 900, because every projection
73
+ needs this frame's camera. It projects the anchors, re-shapes whatever text changed, and writes the
74
+ DOM.
75
+
76
+ **Three coordinate systems.** A canvas has a CSS size and a backing-store size. `Camera.worldToScreen`,
77
+ `HudText`, and `captureScreenshot()` all work in **backing-store** pixels; a DOM element is placed in
78
+ **UI units**. The scaling mode decides what a UI unit is:
79
+
80
+ | Mode | One UI unit is | Use it for |
81
+ | ------- | ------------------- | ------------------------------------------------------ |
82
+ | `"css"` | one CSS pixel | responsive HTML menus (the browser default) |
83
+ | `"fit"` | one reference pixel | a HUD authored once at a fixed resolution, letterboxed |
84
+ | `"dpi"` | one backing pixel | a pixel HUD that must line up with a screenshot |
85
+
86
+ `app.ui.pixelMapping` converts between them, and `WorldAnchor` already does it for you.
24
87
 
25
88
  ## First app
26
89
 
27
- A complete, compiling example that registers the extension and uses it once _(populated in Phase 8)_.
90
+ ```ts
91
+ import { createApp, FontAsset } from "ignifx";
92
+ import { HudText, ui, WorldAnchor } from "@ignifx/ui";
93
+
94
+ const canvas = document.querySelector("canvas");
95
+ if (canvas instanceof HTMLCanvasElement) {
96
+ const app = await createApp({ canvas, extensions: [ui()] });
97
+
98
+ // A name tag that follows an entity. (A plain DOM label goes in
99
+ // `app.ui.layer("hud").element` the same way, positioned with CSS.)
100
+ const tag = document.createElement("div");
101
+ tag.textContent = "Boss";
102
+ app.ui.layer("hud").element?.append(tag);
103
+ const boss = app.world.createEntity("boss");
104
+ const anchor = boss.addComponent(WorldAnchor);
105
+ anchor.element = tag;
106
+ anchor.offset = { x: 0, y: 2, z: 0 };
107
+
108
+ // GPU text, for a pixel-exact readout.
109
+ const font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
110
+ const readout = app.world.createEntity("readout").addComponent(HudText);
111
+ readout.font = font;
112
+ readout.text = "60 fps";
113
+ readout.anchor = "topRight";
114
+ readout.position = { x: -16, y: 16 };
115
+
116
+ await app.start();
117
+ }
118
+ ```
28
119
 
29
120
  ## Core APIs
30
121
 
31
- Component and service tables generated from `skills/ignifx/references/api/ui.md` _(populated in Phase 8)_.
122
+ **`app.ui`** — `root`, `isActive`, `layer(name, { zIndex, visible })`, `layers`, `scaling`,
123
+ `referenceResolution`, `visible`, `layout`, `pixelMapping`, `pointerOverUi`, `keyboardHasFocus`,
124
+ `onLayoutChanged`, `refresh()`.
125
+
126
+ **`UiLayer`** — `name`, `element`, `zIndex`, `visible`, `clear()`.
127
+
128
+ **`WorldAnchor`** — `element` (assigned in code, never serialised), `offset`,
129
+ `hideWhenBehindCamera`, `clampToScreen`, `scaleWithDistance`, `referenceDistance`, `minScale`,
130
+ `maxScale`, `placement`.
131
+
132
+ **`HudText`** — the shared text fields plus `anchor` (one of nine), `position` (backing pixels from
133
+ that anchor), `order`, `metrics`.
134
+
135
+ **`WorldText2D`** — the shared fields plus `offset` (world), `screenOffset` (pixels), `pivot`,
136
+ `hideWhenBehindCamera`, `order`.
137
+
138
+ **`WorldText`** — the shared fields plus `offset`, `pixelsPerUnit` (default 100), `billboard`,
139
+ `alwaysOnTop`.
140
+
141
+ Shared text fields: `font` (a `FontAsset` handle), `text`, `i18nKey`, `fontSize`, `color`, `align`,
142
+ `maxWidth`, `lineHeight`, `opacity`.
143
+
144
+ **`Menu`** — `new Menu(app.ui, { id, title, subtitle, layer, rows, visible, cancelable, keyboard,
145
+ wrap, text })`, then `setRows`, `refresh()`, `show()`/`hide()`, `moveSelection(±1)`,
146
+ `adjustSelection(±1)`, `activateSelection()`, `select(id)`, `cancel()`, `dispose()`, plus `element`,
147
+ `rows`, `selected`, `selectedIndex`, `isVisible`, `cancelable`, `keyboardEnabled`, and the signals
148
+ `onSelectionChanged`, `onActivated`, `onBack`.
149
+
150
+ | Row `kind` | What it declares, on top of `id`, `label` and `enabled?` |
151
+ | ------------- | ------------------------------------------------------------- |
152
+ | `"action"` | `activate?()`, and an optional right-hand `value` |
153
+ | `"toggle"` | `get`/`set` a boolean; drawn with the menu's `text.on`/`.off` |
154
+ | `"slider"` | `min`/`max`/`step` plus `get`/`set`, and an optional `format` |
155
+ | `"choice"` | `values` plus `get`/`set` a string, and an optional `format` |
156
+ | `"binding"` | `path()` and `rebind?()`, and an optional `listening()` |
157
+ | `"heading"` | a label that groups the rows under it; never selected |
158
+ | `"separator"` | a rule; never selected |
159
+
160
+ `label` (and `title`, `subtitle`, `text.*`) is a string **or** a function, re-read on every
161
+ `refresh()` — which is what makes a menu localizable.
162
+
163
+ **`MenuStack`** — `new MenuStack({ navigation, repeatDelay, repeatInterval, threshold })`, then
164
+ `push(menu)`, `pop()`, `closeAll()`, `refresh()`, `update(unscaledDelta)`, plus `top`, `bottom`,
165
+ `menus`, `depth`, `isOpen`, `suspended`, and `onChanged`/`onSelectionChanged`/`onActivated`.
166
+ `navigation` is `{ move, submit, back }` — three objects shaped like `@ignifx/input` actions, which
167
+ is how the widget reaches a gamepad without importing the package.
168
+
169
+ **`app.i18n`** — `load(handleOrAsset)`, `t(key, params)`, `has(key)`, `locale`, `fallbackLocale`,
170
+ `availableLocales`, `onLocaleChanged`.
171
+
172
+ Full signatures: `skills/ignifx/references/api/ui.md`.
32
173
 
33
174
  ## Recipes
34
175
 
35
- Task-oriented examples extracted from `examples/recipes/` _(populated in Phase 8)_.
176
+ ### A pause menu, and a loading screen
177
+
178
+ ```ts
179
+ import { createApp } from "ignifx";
180
+ import { LoadingScreen, Menu, MenuStack, ui } from "@ignifx/ui";
181
+
182
+ const canvas = document.querySelector("canvas");
183
+ if (canvas instanceof HTMLCanvasElement) {
184
+ const app = await createApp({ canvas, extensions: [ui()] });
185
+
186
+ const loading = new LoadingScreen(app.ui, { label: "Loading…" });
187
+ loading.bindTo(app.assets);
188
+ await app.assets.preloadGroup("boot").promise;
189
+ loading.hide();
190
+
191
+ const state = { music: 0.8, shadows: true };
192
+ const stack = new MenuStack();
193
+ const pause = new Menu(app.ui, {
194
+ id: "pause",
195
+ title: "Paused",
196
+ text: { on: "On", off: "Off" },
197
+ rows: [
198
+ { kind: "action", id: "resume", label: "Resume", activate: stack.closeAll.bind(stack) },
199
+ { kind: "heading", id: "audio", label: "Audio" },
200
+ // prettier-ignore
201
+ { kind: "slider", id: "music", label: "Music", min: 0, max: 1, step: 0.05,
202
+ get: (): number => state.music, set: (v: number): void => void (state.music = v),
203
+ format: (v: number): string => `${String(Math.round(v * 100))}%` },
204
+ // prettier-ignore
205
+ { kind: "toggle", id: "shadows", label: "Shadows",
206
+ get: (): boolean => state.shadows, set: (v: boolean): void => void (state.shadows = v) },
207
+ ],
208
+ });
209
+ // The stack owns pausing: any screen up stops the game, and the last one closing starts it again.
210
+ stack.onChanged.connect((top: Menu | null): void => {
211
+ if (top === null) {
212
+ app.resume();
213
+ } else {
214
+ app.pause();
215
+ }
216
+ });
217
+
218
+ stack.push(pause); // …from the game's own input handling
219
+ await app.start();
220
+ }
221
+ ```
222
+
223
+ `stack.push(other)` opens a screen over this one and `pop()` (or Escape, or the pad's east button)
224
+ comes back; `menu.cancelable = false` is what stops Escape unwinding past a title screen.
225
+
226
+ With no `navigation` source a menu reads the keyboard itself — Up/Down, Left/Right, Enter, Escape —
227
+ because the list takes DOM focus on `show()`. Give the stack one to add the gamepad, and pump it
228
+ from a script that declares `static updateWhenPaused = true`:
229
+
230
+ ```ts ignore-check
231
+ const map = app.input.actions.maps.get("UI") ?? null;
232
+ const stack = new MenuStack({
233
+ navigation: {
234
+ move: map?.actions.get("menuMove") ?? null,
235
+ submit: map?.actions.get("menuSubmit") ?? null,
236
+ back: map?.actions.get("menuBack") ?? null,
237
+ },
238
+ });
239
+ stack.update(app.time.unscaledDeltaTime); // in the script's update
240
+ ```
241
+
242
+ ### Touch controls
243
+
244
+ ```ts
245
+ import { createApp } from "ignifx";
246
+ import { input } from "@ignifx/input";
247
+ import { ui, VirtualButton, VirtualJoystick } from "@ignifx/ui";
248
+
249
+ const canvas = document.querySelector("canvas");
250
+ if (canvas instanceof HTMLCanvasElement) {
251
+ const app = await createApp({ canvas, extensions: [input(), ui()] });
252
+ if (navigator.maxTouchPoints > 0) {
253
+ const stick = new VirtualJoystick(app, { control: "joystick", style: { left: "2rem", bottom: "2rem" } });
254
+ const jump = new VirtualButton(app, { control: "jump", label: "A", style: { right: "2rem", bottom: "2rem" } });
255
+ void stick;
256
+ void jump;
257
+ }
258
+ await app.start();
259
+ }
260
+ ```
261
+
262
+ Bind `<Virtual>/joystick` and `<Virtual>/jump` in the game's `.input.json` exactly as any hardware
263
+ path; nothing else changes.
264
+
265
+ ### Localized text
266
+
267
+ ```ts
268
+ import { createApp } from "ignifx";
269
+ import { LocaleAsset, ui } from "@ignifx/ui";
270
+
271
+ const app = await createApp({ headless: true, extensions: [ui()] });
272
+ const strings = app.assets.load<LocaleAsset>("ui/strings.i18n.json");
273
+ await app.i18n.load(strings);
274
+
275
+ app.i18n.t("hud.score", { score: 42 }); // "Score: 42"
276
+ app.i18n.t("hud.lives", { count: 1 }); // "1 life"
277
+ app.i18n.t("hud.lives", { count: 3 }); // "3 lives"
278
+
279
+ app.i18n.locale = "fr";
280
+ app.i18n.t("hud.lives", { count: 3 }); // "3 vies"
281
+ app.dispose();
282
+ ```
283
+
284
+ A `HudText`, `WorldText` or `WorldText2D` with an `i18nKey` re-shapes itself when the locale
285
+ changes; `i18nKey` wins over `text`.
36
286
 
37
287
  ## File formats
38
288
 
39
- The file formats this subsystem reads and writes, with links to `skills/ignifx/references/formats/` _(populated in Phase 8)_.
289
+ `ignifx.i18n` (`.i18n.json`, asset type `i18n`) — one document, every locale:
290
+
291
+ ```json
292
+ {
293
+ "format": "ignifx.i18n",
294
+ "formatVersion": 1,
295
+ "defaultLocale": "en",
296
+ "locales": {
297
+ "en": { "hud.lives": "{count, plural, =0 {No lives} one {# life} other {# lives}}" },
298
+ "fr": { "hud.lives": "{count, plural, =0 {Aucune vie} one {# vie} other {# vies}}" }
299
+ }
300
+ }
301
+ ```
302
+
303
+ Supported: `{name}` interpolation, `{n, plural, …}` with `=0`-style exact matches, the CLDR
304
+ categories for the active locale, and `#` for the number. Not supported: `select`, number and date
305
+ skeletons, and ICU's apostrophe quoting — braces are structural, so a literal brace arrives as a
306
+ parameter. Field reference: `skills/ignifx/references/formats/ignifx.i18n.md`.
40
307
 
41
308
  ## Gotchas
42
309
 
43
- The traps this subsystem has, each with the replacement to use instead _(populated in Phase 8)_.
310
+ - **A click on UI never reaches gameplay, but a drag does.** `@ignifx/input` reads `pointerdown`
311
+ from the _canvas_, and the overlay is the canvas's sibling — so a press on a
312
+ `pointer-events: auto` element is never queued. It reads `pointermove`/`pointerup` from the
313
+ _window_, so a drag that started on a slider still moves `<Pointer>/delta`. Check
314
+ `app.ui.pointerOverUi` in a camera script.
315
+ - **Only text fields take the keyboard.** `app.input.uiHasFocus` is set for `<input>` (except the
316
+ button- and slider-like types), `<textarea>`, `<select>` and `contenteditable`. A focused
317
+ `<button>` deliberately does not stop gameplay. Override with `data-ignifx-focus="capture"` or
318
+ `"ignore"`.
319
+ - **`HudText.position` is in render-target pixels, not CSS pixels.** That is the point: it is the
320
+ same space `captureScreenshot()` reads back. A DOM label in `app.ui.layer("hud")` is the right
321
+ tool when you want CSS pixels.
322
+ - **`WorldText` has to exist before `app.start()`.** Babylon Lite drains a deferred scene renderable
323
+ exactly once, when the scene is registered, and offers no way to drain a later one; a sign that
324
+ first gets its text mid-game logs `IGX-1308` and does not draw. Use `WorldText2D`, which owns a
325
+ text layer and can be added at any time.
326
+ - **`align` aligns lines against each other, not against `maxWidth`.** To centre a block on screen,
327
+ use `HudText.anchor` (or read `metrics` and do the arithmetic).
328
+ - **Changing `fontSize`, `maxWidth`, `align`, `lineHeight` or `font` re-shapes from scratch**;
329
+ changing `text` or `color` does not. A per-frame counter is cheap; a per-frame font size is not.
330
+ - **`WorldAnchor.element` is not serialised.** A scene file carries the flags; the game assigns the
331
+ element in `awake`.
332
+ - **A `Toast` runs on the game clock, and nothing advances it for you.** Call `toast.advance(dt)`
333
+ from a script's `update`. A message shown from a pause menu only expires if that script declares
334
+ `static updateWhenPaused = true` and passes `app.time.unscaledDeltaTime` — `app.pause()` stops
335
+ `update` for every other script.
336
+ - **A `Dialog` is always above the other roots of its layer.** The stylesheet gives it
337
+ `z-index: 1000` (`UI_DIALOG_Z_INDEX`, overridable with `DialogOptions.zIndex`), because siblings
338
+ with no `z-index` paint in DOM order and a modal built before a `Menu` would otherwise sit under
339
+ it with its backdrop swallowing every click. Re-use one dialog and call `setTitle`, `setMessage`
340
+ and `setButtons` rather than building one per question.
341
+ - **A menu owns its selection; the browser owns focus only for the list.** Rows are `tabindex="-1"`
342
+ and the list carries `aria-activedescendant`, because a gamepad raises no DOM focus events. If the
343
+ game also binds arrows to a `menuMove` action, drive the menus through a `MenuStack` with a
344
+ `navigation` source — it turns each pushed menu's own key handling off, and back on when it pops.
345
+ - **Two apps in one document share one stylesheet and get one overlay each.** The root is mounted
346
+ as the canvas's next sibling, so put the canvas in a positioned wrapper.
44
347
 
45
348
  ## Deprecated (current window)
46
349
 
@@ -48,4 +351,5 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
48
351
 
49
352
  ## Where to look next
50
353
 
51
- `skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/` for design rationale.
354
+ `skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/13-ui.md` for design
355
+ rationale · `skills/ignifx/references/api/ui.md` for full signatures.