@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/dist/index.d.ts CHANGED
@@ -1 +1,3460 @@
1
- export {}
1
+ import { App, AssetHandle, AssetLoader, AssetProgress, Assets, ColorLike, Component, ComponentHooks, Disconnect, ErrorContext, Extension, FontAsset, IgnifxError, JsonSchemaObject, LiteScene, Logger, QuatLike, Schema, SchemaDescription, SignalLike, System, SystemContext, Vec2Like, Vec3Like, World } from "@ignifx/core";
2
+ import { DefaultTextData, Font, TextLayer, TextRenderable, TextRenderer } from "@babylonjs/lite";
3
+ //#region src/dom/layer.d.ts
4
+ /**
5
+ * One named stacking layer inside the overlay root (`docs/architecture/13-ui.md` §1:
6
+ * "games mount React/Preact/Svelte/Vue/vanilla trees into it, or into named layers"*).
7
+ *
8
+ * A layer is a plain absolutely-positioned `<div>` that fills the root, carries a `z-index`, and is
9
+ * `pointer-events: none` like the root — children opt in with the
10
+ * {@link UI_CLASS_NAMES.interactive} class or their own CSS. Under a headless app the layer still
11
+ * exists as an object, with `element` `null` and every mutation a no-op, so game code never has to
12
+ * branch on the environment.
13
+ */
14
+ /**
15
+ * Options accepted by `app.ui.layer`.
16
+ *
17
+ * @public
18
+ */
19
+ interface UiLayerOptions {
20
+ /** The stacking order. Defaults to the layer's declaration index times `UI_LAYER_Z_STEP`. */
21
+ readonly zIndex?: number;
22
+ /** Whether the layer starts visible. Defaults to `true`. */
23
+ readonly visible?: boolean;
24
+ }
25
+ /**
26
+ * A named layer of the overlay.
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * const hud = app.ui.layer("hud");
31
+ * hud.element?.append(document.createElement("div"));
32
+ * hud.visible = false;
33
+ * ```
34
+ *
35
+ * @public
36
+ */
37
+ export declare class UiLayer {
38
+ #private;
39
+ /** The name the layer is addressed by. */
40
+ readonly name: string;
41
+ /**
42
+ * Builds a layer. `app.ui.layer` does this; a game never constructs one.
43
+ *
44
+ * @param name - The layer name.
45
+ * @param element - The layer's element, or `null` under a headless app.
46
+ * @param zIndex - The initial stacking order.
47
+ * @param visible - Whether the layer starts visible.
48
+ *
49
+ * @internal
50
+ */
51
+ constructor(name: string, element: HTMLDivElement | null, zIndex: number, visible: boolean);
52
+ /**
53
+ * Gives a layer that was created before the overlay mounted its element.
54
+ *
55
+ * @remarks
56
+ * The host builds its root when the world is created, which is after every extension registered;
57
+ * a layer declared in the `ui` settings section therefore exists as an object first and gets its
58
+ * element a moment later. Nothing observable changes: an unmounted layer is exactly a headless
59
+ * one.
60
+ *
61
+ * @param element - The layer's element.
62
+ *
63
+ * @internal
64
+ */
65
+ attach(element: HTMLDivElement): void;
66
+ /**
67
+ * The layer's element, or `null` when the app has no DOM overlay.
68
+ *
69
+ * @returns The `<div>` a game mounts its tree into.
70
+ */
71
+ get element(): HTMLDivElement | null;
72
+ /**
73
+ * The layer's stacking order within the root.
74
+ *
75
+ * @returns The `z-index`.
76
+ */
77
+ get zIndex(): number;
78
+ set zIndex(value: number);
79
+ /**
80
+ * Whether the layer is shown. Hiding a layer hides everything mounted in it without unmounting
81
+ * anything, which is what a pause menu wants.
82
+ *
83
+ * @returns `true` while the layer is shown.
84
+ */
85
+ get visible(): boolean;
86
+ set visible(value: boolean);
87
+ /**
88
+ * Removes every child of the layer without removing the layer itself.
89
+ *
90
+ * @remarks
91
+ * A no-op under a headless app.
92
+ */
93
+ clear(): void;
94
+ }
95
+ //#endregion
96
+ //#region src/dom/dom-target.d.ts
97
+ /**
98
+ * What the overlay host needs from the host page (`docs/architecture/13-ui.md` §1). Passing it
99
+ * explicitly, instead of reaching for `globalThis.document`, is what makes two apps in one document
100
+ * possible (`CONSTITUTION.md` §3.6) and what lets a test hand in a fake.
101
+ *
102
+ * The whole module is written against the real DOM types rather than structural stand-ins, which is
103
+ * the choice `@ignifx/input`'s `DomTarget` already made: games get real elements to mount React or
104
+ * Svelte into, and the node test suite passes a fake through one `as unknown as` in
105
+ * `test/support/fake-dom.ts` rather than every call site paying for an abstraction.
106
+ */
107
+ /**
108
+ * The DOM objects one app's overlay is built in.
109
+ *
110
+ * @public
111
+ */
112
+ interface UiDomTarget {
113
+ /** The canvas the overlay is positioned over. */
114
+ readonly canvas: HTMLCanvasElement;
115
+ /** The document the overlay's elements and its stylesheet are created in. */
116
+ readonly document: Document;
117
+ /** The window resize and focus events are read from, and the pixel ratio is read from. */
118
+ readonly window: Window;
119
+ }
120
+ //#endregion
121
+ //#region src/settings.d.ts
122
+ /**
123
+ * The `ui` project settings section (`docs/architecture/04-extensions.md` §5, `13-ui.md` §1).
124
+ * Everything here is what a game writes in `ignifx.config.ts`; the knobs a game changes per frame
125
+ * live on `app.ui` and on the individual layers instead.
126
+ */
127
+ /**
128
+ * The section name as it appears in `ignifx.config.ts`.
129
+ *
130
+ * @public
131
+ */
132
+ export declare const UI_SETTINGS_SECTION = "ui";
133
+ /**
134
+ * Every scaling mode the overlay host supports, in the order an inspector should list them
135
+ * (`docs/architecture/13-ui.md` §1).
136
+ *
137
+ * @public
138
+ */
139
+ export declare const UI_SCALING_MODES: readonly ["css", "fit", "dpi"];
140
+ /**
141
+ * How the overlay's coordinate system relates to the canvas.
142
+ *
143
+ * @remarks
144
+ * - `"css"` — one UI unit is one CSS pixel and nothing is scaled. The browser default, and what a
145
+ * responsive HTML menu wants.
146
+ * - `"fit"` — the root is exactly {@link UiSettings.referenceResolution} CSS pixels and is scaled
147
+ * uniformly to fit inside the canvas, keeping aspect and centring the letterbox. A HUD authored
148
+ * once at 1920x1080 then looks the same on every window size.
149
+ * - `"dpi"` — one UI unit is one **render-target** pixel: the root is sized to the canvas's
150
+ * backing store and scaled by `1 / devicePixelRatio` so it still covers the same area. This is
151
+ * the space `Camera.worldToScreen`, `HudText`, and `app.renderer.captureScreenshot()` all work
152
+ * in, so an element placed at `left: 100px` lands on render-target column 100 exactly.
153
+ *
154
+ * @public
155
+ */
156
+ type UiScalingMode = (typeof UI_SCALING_MODES)[number];
157
+ /**
158
+ * The resolved `ui` settings section.
159
+ *
160
+ * @example
161
+ * ```ts
162
+ * // ignifx.config.ts
163
+ * export default defineConfig({
164
+ * ui: { scaling: "fit", referenceResolution: [640, 360], layers: ["hud", "menu"] },
165
+ * });
166
+ * ```
167
+ *
168
+ * @public
169
+ */
170
+ interface UiSettings {
171
+ /** How the overlay's coordinate system relates to the canvas. Defaults to `"css"`. */
172
+ readonly scaling: UiScalingMode;
173
+ /**
174
+ * The `[width, height]`, in UI units, that `"fit"` scales to. Ignored by the other two modes.
175
+ * Defaults to `[1920, 1080]`.
176
+ */
177
+ readonly referenceResolution: readonly number[];
178
+ /**
179
+ * The layers created eagerly, back to front. Declaring them here is what makes their stacking
180
+ * order independent of the order the game happens to call {@link UiHost.layer} in.
181
+ */
182
+ readonly layers: readonly string[];
183
+ /** Whether the overlay is shown at all. Defaults to `true`. */
184
+ readonly visible: boolean;
185
+ }
186
+ /**
187
+ * The z-index step between two consecutive layers. The first declared layer sits at
188
+ * `UI_LAYER_Z_STEP`, the second at twice that, and so on, which leaves nine free slots between any
189
+ * two layers for a game that wants to interleave its own elements.
190
+ *
191
+ * @public
192
+ */
193
+ export declare const UI_LAYER_Z_STEP = 10;
194
+ /**
195
+ * The values used for everything a project omits.
196
+ *
197
+ * @returns The default `ui` section.
198
+ *
199
+ * @public
200
+ */
201
+ export declare function defaultUiSettings(): UiSettings;
202
+ /**
203
+ * The schema the `ui` section is validated against.
204
+ *
205
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
206
+ *
207
+ * @public
208
+ */
209
+ export declare function uiSettingsSchema(): Schema;
210
+ //#endregion
211
+ //#region src/dom/scaling.d.ts
212
+ /**
213
+ * The scaling arithmetic behind `app.ui.scaling` (`docs/architecture/13-ui.md` §1). Every function
214
+ * here is pure: it takes measurements and returns numbers, so the three modes are unit-testable
215
+ * under Node with no DOM at all, and the host is left with nothing but the DOM writes.
216
+ *
217
+ * ## The three coordinate systems
218
+ *
219
+ * A canvas has two sizes: its **CSS** size, which is what layout and pointer coordinates use, and
220
+ * its **backing-store** size (`canvas.width`/`canvas.height`), which is what WebGPU renders into.
221
+ * Their ratio is the effective device pixel ratio. `Camera.worldToScreen`, Lite's text renderer,
222
+ * and `app.renderer.captureScreenshot()` all work in backing-store pixels; a DOM element is placed
223
+ * in CSS pixels. A "UI unit" is whichever of the two — or neither — the scaling mode picks:
224
+ *
225
+ * | Mode | One UI unit is | Root size | Scale |
226
+ * | ------- | -------------------- | ------------------------ | ---------------------------- |
227
+ * | `"css"` | one CSS pixel | the canvas's CSS size | `1` |
228
+ * | `"fit"` | one reference pixel | `referenceResolution` | `min(cssW/refW, cssH/refH)` |
229
+ * | `"dpi"` | one backing pixel | the canvas's pixel size | `cssW / backingW` |
230
+ */
231
+ /**
232
+ * The two sizes of the canvas the overlay covers, both measured by the host.
233
+ *
234
+ * @public
235
+ */
236
+ interface UiSurfaceMetrics {
237
+ /** The canvas's laid-out width, in CSS pixels. */
238
+ readonly cssWidth: number;
239
+ /** The canvas's laid-out height, in CSS pixels. */
240
+ readonly cssHeight: number;
241
+ /** The canvas's backing-store width, in device pixels — `canvas.width`. */
242
+ readonly deviceWidth: number;
243
+ /** The canvas's backing-store height, in device pixels — `canvas.height`. */
244
+ readonly deviceHeight: number;
245
+ }
246
+ /**
247
+ * Where the overlay root sits and how big it is, in the units the mode chose.
248
+ *
249
+ * @public
250
+ */
251
+ interface UiLayout {
252
+ /** The mode this layout was computed for. */
253
+ readonly mode: UiScalingMode;
254
+ /** The root's width, in UI units. */
255
+ readonly width: number;
256
+ /** The root's height, in UI units. */
257
+ readonly height: number;
258
+ /** The uniform CSS scale applied to the root. */
259
+ readonly scale: number;
260
+ /** The root's left edge, in CSS pixels from the canvas's left edge. */
261
+ readonly offsetX: number;
262
+ /** The root's top edge, in CSS pixels from the canvas's top edge. */
263
+ readonly offsetY: number;
264
+ }
265
+ /**
266
+ * Computes the overlay root's size, scale, and offset for one mode and one measured canvas.
267
+ *
268
+ * @param mode - The scaling mode.
269
+ * @param metrics - The canvas's CSS and backing-store sizes.
270
+ * @param reference - The `[width, height]` a `"fit"` layout scales to; ignored by the other modes.
271
+ * @returns The layout to write onto the root.
272
+ *
273
+ * @example
274
+ * ```ts
275
+ * computeUiLayout("fit", { cssWidth: 800, cssHeight: 600, deviceWidth: 800, deviceHeight: 600 }, [
276
+ * 400, 300,
277
+ * ]).scale; // 2
278
+ * ```
279
+ *
280
+ * @public
281
+ */
282
+ export declare function computeUiLayout(mode: UiScalingMode, metrics: UiSurfaceMetrics, reference: readonly number[]): UiLayout;
283
+ /**
284
+ * How a render-target pixel maps onto a UI unit under one layout.
285
+ *
286
+ * @remarks
287
+ * `Camera.worldToScreen` answers in **backing-store** pixels (it divides by
288
+ * `RendererImpl.readTargetSize`, which reads `canvas.width`/`canvas.height`), and a DOM element is
289
+ * placed in UI units inside a root that is itself translated by `offsetX`/`offsetY` CSS pixels and
290
+ * scaled by `scale`. This is the conversion between the two, expressed so a per-frame loop needs
291
+ * two multiplies and a subtract and allocates nothing.
292
+ *
293
+ * @public
294
+ */
295
+ interface UiPixelMapping {
296
+ /** Multiply a backing-store x by this. */
297
+ readonly scaleX: number;
298
+ /** Then subtract this. */
299
+ readonly originX: number;
300
+ /** Multiply a backing-store y by this. */
301
+ readonly scaleY: number;
302
+ /** Then subtract this. */
303
+ readonly originY: number;
304
+ }
305
+ /**
306
+ * Builds the backing-store-pixel to UI-unit conversion for one layout and one canvas.
307
+ *
308
+ * @param layout - The current layout.
309
+ * @param metrics - The canvas's CSS and backing-store sizes.
310
+ * @returns The mapping.
311
+ *
312
+ * @example
313
+ * ```ts
314
+ * const metrics = { cssWidth: 400, cssHeight: 300, deviceWidth: 800, deviceHeight: 600 };
315
+ * const layout = computeUiLayout("css", metrics, [400, 300]);
316
+ * const map = pixelMapping(layout, metrics);
317
+ * map.scaleX * 800 - map.originX; // 400 — the canvas's right edge, in CSS pixels
318
+ * ```
319
+ *
320
+ * @public
321
+ */
322
+ export declare function pixelMapping(layout: UiLayout, metrics: UiSurfaceMetrics): UiPixelMapping;
323
+ //#endregion
324
+ //#region src/dom/host.d.ts
325
+ /**
326
+ * What {@link UiHost} is constructed with.
327
+ *
328
+ * @internal
329
+ */
330
+ interface UiHostOptions {
331
+ /**
332
+ * Finds the DOM to build the overlay in, or answers `null` for a headless app. Called once, from
333
+ * {@link UiHost.mount}, because the render surface does not exist while extensions register.
334
+ */
335
+ readonly resolveTarget: () => UiDomTarget | null;
336
+ /** The resolved `ui` settings section, already merged with the extension's options. */
337
+ readonly settings: UiSettings;
338
+ /** The extension's logger. */
339
+ readonly log: Logger;
340
+ /**
341
+ * Writes `app.input.uiHasFocus`. The extension supplies a setter that duck-types the input
342
+ * service, so `@ignifx/ui` never imports `@ignifx/input` and the peer stays genuinely optional.
343
+ */
344
+ readonly setInputFocus: (value: boolean) => void;
345
+ /**
346
+ * Writes `app.input.uiHasPointer`: `true` while at least one pointer is pressed on the overlay,
347
+ * so pointing-device actions read as released during a drag that began on UI. Same duck-typing
348
+ * as {@link UiHostOptions.setInputFocus}.
349
+ */
350
+ readonly setInputPointer: (value: boolean) => void;
351
+ }
352
+ /**
353
+ * The DOM overlay host, reached as `app.ui`.
354
+ *
355
+ * @example
356
+ * ```ts
357
+ * const hud = app.ui.layer("hud");
358
+ * app.ui.scaling = "fit";
359
+ * app.ui.referenceResolution = [640, 360];
360
+ * ```
361
+ *
362
+ * @public
363
+ */
364
+ export declare class UiHost {
365
+ #private;
366
+ /**
367
+ * Builds the host and, when there is a DOM, the root and the declared layers.
368
+ *
369
+ * @param options - The DOM target, the settings, the logger, and the focus setter.
370
+ *
371
+ * @internal
372
+ */
373
+ constructor(options: UiHostOptions);
374
+ /**
375
+ * Builds the root, the layer elements, the focus watcher, and the resize subscriptions. Called
376
+ * once, from `UiSystem.onWorldCreated`; calling it again does nothing.
377
+ *
378
+ * @internal
379
+ */
380
+ mount(): void;
381
+ /**
382
+ * The overlay root: an absolutely positioned `<div>` covering the canvas, `pointer-events: none`.
383
+ *
384
+ * @returns The root, or `null` when the app has no DOM overlay.
385
+ */
386
+ get root(): HTMLDivElement | null;
387
+ /**
388
+ * Whether there is a DOM overlay at all. `false` under a headless app, an `OffscreenCanvas`, or a
389
+ * detached canvas — the three cases in which every other member is a no-op.
390
+ *
391
+ * @returns `true` when {@link UiHost.root} is an element.
392
+ */
393
+ get isActive(): boolean;
394
+ /**
395
+ * How the overlay's coordinate system relates to the canvas. Writing it recomputes the layout
396
+ * immediately.
397
+ *
398
+ * @returns The current mode.
399
+ */
400
+ get scaling(): UiScalingMode;
401
+ set scaling(value: UiScalingMode);
402
+ /**
403
+ * The `[width, height]` the `"fit"` mode scales to. Writing it recomputes the layout.
404
+ *
405
+ * @returns A copy of the current reference resolution.
406
+ */
407
+ get referenceResolution(): readonly number[];
408
+ set referenceResolution(value: readonly number[]);
409
+ /**
410
+ * Whether the whole overlay is shown. Per-layer visibility is `app.ui.layer(name).visible`.
411
+ *
412
+ * @returns `true` while the overlay is shown.
413
+ */
414
+ get visible(): boolean;
415
+ set visible(value: boolean);
416
+ /**
417
+ * The root's current size, scale, and offset, in the units the scaling mode chose.
418
+ *
419
+ * @returns The layout last computed.
420
+ */
421
+ get layout(): UiLayout;
422
+ /**
423
+ * The conversion from render-target pixels — the space `Camera.worldToScreen`, `HudText`, and
424
+ * `app.renderer.captureScreenshot()` work in — to UI units.
425
+ *
426
+ * @returns The mapping last computed.
427
+ */
428
+ get pixelMapping(): UiPixelMapping;
429
+ /**
430
+ * Every layer, back to front.
431
+ *
432
+ * @returns The layers, ordered by `zIndex`.
433
+ */
434
+ get layers(): readonly UiLayer[];
435
+ /**
436
+ * Whether a pointer is currently pressed on an interactive element of the overlay.
437
+ *
438
+ * @remarks
439
+ * A click on a UI element never reaches gameplay in the first place: `@ignifx/input` reads
440
+ * `pointerdown` and `wheel` from the **canvas** (`packages/input/src/dom/pointer-source.ts`), and
441
+ * the overlay root is the canvas's sibling rather than its child, so a press that lands on a
442
+ * `pointer-events: auto` element is not on the canvas and is never queued. This flag covers the
443
+ * remaining case: `pointermove` and `pointerup` are read from the **window**, so a drag that
444
+ * started on a slider still moves `<Pointer>/delta`. A camera script that must ignore that reads
445
+ * this flag.
446
+ *
447
+ * @returns `true` while at least one pointer is down on the overlay.
448
+ */
449
+ get pointerOverUi(): boolean;
450
+ /**
451
+ * Whether a text field currently owns the keyboard — the same value the host writes into
452
+ * `app.input.uiHasFocus`.
453
+ *
454
+ * @returns `true` while typing must not fire keyboard actions.
455
+ */
456
+ get keyboardHasFocus(): boolean;
457
+ /**
458
+ * Emitted after every recomputation that changed the layout: a canvas resize, a device-pixel-ratio
459
+ * change, or a write to {@link UiHost.scaling} or {@link UiHost.referenceResolution}.
460
+ *
461
+ * @returns The signal.
462
+ */
463
+ get onLayoutChanged(): SignalLike<UiLayout>;
464
+ /**
465
+ * Returns the named layer, creating it the first time it is asked for.
466
+ *
467
+ * @param name - The layer name.
468
+ * @param options - The stacking order and the initial visibility, used only on creation.
469
+ * @returns The layer.
470
+ *
471
+ * @example
472
+ * ```ts
473
+ * const menu = app.ui.layer("menu", { zIndex: 100 });
474
+ * ```
475
+ */
476
+ layer(name: string, options?: UiLayerOptions): UiLayer;
477
+ /**
478
+ * Re-measures the canvas and rewrites the root's geometry.
479
+ *
480
+ * @remarks
481
+ * Called by the `ResizeObserver`, by the window's `resize` event — which is what a
482
+ * device-pixel-ratio change fires — and by every write to a scaling property. Games call it after
483
+ * changing the canvas's size by hand. A recomputation that produces the same layout writes
484
+ * nothing and emits nothing.
485
+ */
486
+ refresh(): void;
487
+ /**
488
+ * Removes the overlay from the document and unsubscribes from everything.
489
+ *
490
+ * @internal
491
+ */
492
+ dispose(): void;
493
+ }
494
+ //#endregion
495
+ //#region src/i18n/locale-file.d.ts
496
+ /**
497
+ * The `ignifx.i18n` document (`docs/architecture/06-serialization-and-scene-format.md` §6,
498
+ * `13-ui.md` §3: *"loaded from `.json` assets"*).
499
+ *
500
+ * One file carries **every** locale, keyed by BCP 47 tag, because a game with two languages should
501
+ * not need two fetches and a `locale` switch should not need a load at all:
502
+ *
503
+ * ```json
504
+ * {
505
+ * "format": "ignifx.i18n",
506
+ * "formatVersion": 1,
507
+ * "defaultLocale": "en",
508
+ * "locales": {
509
+ * "en": { "hud.score": "Score: {score}" },
510
+ * "fr": { "hud.score": "Score : {score}" }
511
+ * }
512
+ * }
513
+ * ```
514
+ *
515
+ * A game that would rather ship one file per locale loads several documents and calls
516
+ * `app.i18n.load` on each; the service merges them, later loads winning on a repeated key.
517
+ */
518
+ /**
519
+ * The `format` discriminator every translation document carries.
520
+ *
521
+ * @public
522
+ */
523
+ export declare const I18N_FORMAT = "ignifx.i18n";
524
+ /**
525
+ * The `formatVersion` this build writes and is the only one it can read. Before 1.0 the number
526
+ * stays `1` and an incompatible change invalidates files rather than migrating them
527
+ * (`CONSTITUTION.md` §4.2); a file declaring anything else is rejected with `IGX-1302`.
528
+ *
529
+ * @public
530
+ */
531
+ export declare const I18N_FORMAT_VERSION = 1;
532
+ /**
533
+ * The asset type translation documents are registered under.
534
+ *
535
+ * @public
536
+ */
537
+ export declare const I18N_ASSET_TYPE = "i18n";
538
+ /**
539
+ * The file extensions the translation loader claims.
540
+ *
541
+ * @public
542
+ */
543
+ export declare const I18N_FILE_EXTENSIONS: readonly string[];
544
+ /**
545
+ * A parsed `ignifx.i18n` document.
546
+ *
547
+ * @public
548
+ */
549
+ interface LocaleDocument {
550
+ /** The locale used when nothing else selected one. */
551
+ readonly defaultLocale: string;
552
+ /** Every locale's message table, keyed by BCP 47 tag. */
553
+ readonly locales: Readonly<Record<string, Readonly<Record<string, string>>>>;
554
+ }
555
+ /**
556
+ * Parses and validates a translation document.
557
+ *
558
+ * @param value - The parsed JSON.
559
+ * @param address - The address it came from, for the error's context.
560
+ * @returns The document.
561
+ * @throws IgnifxError with code `IGX-1302` when the header is missing, the version does not match,
562
+ * or the file declares no locales.
563
+ *
564
+ * @example
565
+ * ```ts
566
+ * const document = parseLocaleFile(
567
+ * { format: "ignifx.i18n", formatVersion: 1, defaultLocale: "en", locales: { en: { ok: "OK" } } },
568
+ * "ui/strings.i18n.json",
569
+ * );
570
+ * document.locales["en"]?.["ok"]; // "OK"
571
+ * ```
572
+ *
573
+ * @public
574
+ */
575
+ export declare function parseLocaleFile(value: unknown, address: string): LocaleDocument;
576
+ /**
577
+ * A loaded translation document (`docs/architecture/05-assets-and-loading.md` §5).
578
+ *
579
+ * @remarks
580
+ * Pure data: it loads identically under Node and in a browser and has nothing to release.
581
+ *
582
+ * @example
583
+ * ```ts
584
+ * const strings = await app.assets.loadAsync<LocaleAsset>("ui/strings.i18n.json");
585
+ * strings.value.availableLocales; // ["en", "fr"]
586
+ * ```
587
+ *
588
+ * @public
589
+ */
590
+ export declare class LocaleAsset {
591
+ /** The type name the asset service registers translation documents under. */
592
+ static assetType: string;
593
+ /** The address the document was loaded from. */
594
+ readonly address: string;
595
+ /** The parsed document. */
596
+ readonly document: LocaleDocument;
597
+ /**
598
+ * Wraps a parsed document. The `i18n` loader constructs these.
599
+ *
600
+ * @param address - The address it was loaded from.
601
+ * @param document - The parsed document.
602
+ *
603
+ * @internal
604
+ */
605
+ constructor(address: string, document: LocaleDocument);
606
+ /**
607
+ * Every locale the document declares, sorted.
608
+ *
609
+ * @returns The BCP 47 tags.
610
+ */
611
+ get availableLocales(): readonly string[];
612
+ }
613
+ /**
614
+ * The schema a translation document is described and validated against for tooling.
615
+ *
616
+ * @remarks
617
+ * The loader validates with {@link parseLocaleFile}, which produces an actionable `IGX-1302`
618
+ * naming the file; this schema is what `pnpm docs:schemas` renders and what a JSON Schema for an
619
+ * editor is generated from — the split `@ignifx/2d`'s `file-schemas.ts` documents.
620
+ *
621
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
622
+ *
623
+ * @public
624
+ */
625
+ export declare function localeFileSchema(): Schema;
626
+ /**
627
+ * Describes the `ignifx.i18n` file format for the documentation harness.
628
+ *
629
+ * @returns The record `pnpm docs:schemas` renders.
630
+ *
631
+ * @public
632
+ */
633
+ export declare function describeLocaleFileFormat(): SchemaDescription;
634
+ /**
635
+ * The JSON Schema a tool validates a `.i18n.json` document against.
636
+ *
637
+ * @returns The JSON Schema object.
638
+ *
639
+ * @public
640
+ */
641
+ export declare function localeJsonSchema(): JsonSchemaObject;
642
+ //#endregion
643
+ //#region src/i18n/message.d.ts
644
+ /**
645
+ * What a message's parameters may be.
646
+ *
647
+ * @public
648
+ */
649
+ type MessageParams = Readonly<Record<string, string | number>>;
650
+ /**
651
+ * Chooses a plural category for a number, in one locale.
652
+ *
653
+ * @public
654
+ */
655
+ type PluralSelector = (value: number) => string;
656
+ /**
657
+ * A run of literal text.
658
+ *
659
+ * @public
660
+ */
661
+ interface TextNode {
662
+ /** The discriminator. */
663
+ readonly kind: "text";
664
+ /** The literal. */
665
+ readonly value: string;
666
+ }
667
+ /**
668
+ * A `{name}` substitution.
669
+ *
670
+ * @public
671
+ */
672
+ interface ArgumentNode {
673
+ /** The discriminator. */
674
+ readonly kind: "argument";
675
+ /** The parameter name. */
676
+ readonly name: string;
677
+ }
678
+ /**
679
+ * A `{name, plural, …}` selection.
680
+ *
681
+ * @public
682
+ */
683
+ interface PluralNode {
684
+ /** The discriminator. */
685
+ readonly kind: "plural";
686
+ /** The parameter name holding the number. */
687
+ readonly name: string;
688
+ /** The branches, keyed by `"=0"`-style exact matches and by plural category. */
689
+ readonly branches: ReadonlyMap<string, readonly MessageNode[]>;
690
+ }
691
+ /**
692
+ * One piece of a parsed message.
693
+ *
694
+ * @public
695
+ */
696
+ type MessageNode = TextNode | ArgumentNode | PluralNode;
697
+ /**
698
+ * A parsed message, or the reason it could not be parsed.
699
+ *
700
+ * @public
701
+ */
702
+ interface MessagePattern {
703
+ /** The nodes to render. Holds the raw pattern as one text node when {@link MessagePattern.error} is set. */
704
+ readonly nodes: readonly MessageNode[];
705
+ /** Why the pattern could not be read, or `null` when it parsed. */
706
+ readonly error: string | null;
707
+ }
708
+ /**
709
+ * Parses one message pattern.
710
+ *
711
+ * @param pattern - The pattern, as written in the `.i18n.json` document.
712
+ * @returns The parsed nodes, or the raw text plus the reason it could not be parsed.
713
+ *
714
+ * @example
715
+ * ```ts
716
+ * parseMessage("{count, plural, one {# life} other {# lives}}").error; // null
717
+ * parseMessage("{count, plural, one {# life}}").error; // "plural count has no other branch"
718
+ * ```
719
+ *
720
+ * @public
721
+ */
722
+ export declare function parseMessage(pattern: string): MessagePattern;
723
+ /**
724
+ * Builds the plural selector for a locale.
725
+ *
726
+ * @remarks
727
+ * `Intl.PluralRules` is present in every browser and in Node, but a stripped runtime without
728
+ * `Intl` still has to work, so the fallback is English's two-category rule.
729
+ *
730
+ * @param locale - The BCP 47 locale tag.
731
+ * @returns A function from a number to a plural category.
732
+ *
733
+ * @example
734
+ * ```ts
735
+ * createPluralSelector("en")(1); // "one"
736
+ * ```
737
+ *
738
+ * @public
739
+ */
740
+ export declare function createPluralSelector(locale: string): PluralSelector;
741
+ /**
742
+ * Renders a parsed message.
743
+ *
744
+ * @param pattern - The parsed pattern.
745
+ * @param params - The values to substitute.
746
+ * @param select - The active locale's plural selector.
747
+ * @returns The rendered string.
748
+ *
749
+ * @example
750
+ * ```ts
751
+ * const pattern = parseMessage("{count, plural, one {# life} other {# lives}}");
752
+ * renderMessage(pattern, { count: 3 }, createPluralSelector("en")); // "3 lives"
753
+ * ```
754
+ *
755
+ * @public
756
+ */
757
+ export declare function renderMessage(pattern: MessagePattern, params: MessageParams, select: PluralSelector): string;
758
+ //#endregion
759
+ //#region src/i18n/i18n-service.d.ts
760
+ /**
761
+ * What {@link I18nService} is constructed with.
762
+ *
763
+ * @internal
764
+ */
765
+ interface I18nServiceOptions {
766
+ /** The extension's logger. */
767
+ readonly log: Logger;
768
+ /** The locale the app starts in, before any document is loaded. */
769
+ readonly locale: string;
770
+ }
771
+ /**
772
+ * The localization service, reached as `app.i18n`.
773
+ *
774
+ * @example
775
+ * ```ts
776
+ * await app.i18n.load(app.assets.load<LocaleAsset>("ui/strings.i18n.json"));
777
+ * app.i18n.locale = "fr";
778
+ * app.i18n.t("hud.lives", { count: 3 });
779
+ * ```
780
+ *
781
+ * @public
782
+ */
783
+ export declare class I18nService {
784
+ #private;
785
+ /**
786
+ * Builds an empty service. The extension does this; a game never constructs one.
787
+ *
788
+ * @param options - The logger and the starting locale.
789
+ *
790
+ * @internal
791
+ */
792
+ constructor(options: I18nServiceOptions);
793
+ /**
794
+ * The active locale. Writing a locale no loaded document declares throws `IGX-1303`, because a
795
+ * silent no-op there is a bug that only shows up as untranslated text much later.
796
+ *
797
+ * @returns The BCP 47 tag.
798
+ * @throws IgnifxError with code `IGX-1303` when no loaded document declares the tag.
799
+ */
800
+ get locale(): string;
801
+ set locale(value: string);
802
+ /**
803
+ * The locale a key falls back to when the active locale has no entry for it. Set from the first
804
+ * document's `defaultLocale`.
805
+ *
806
+ * @returns The BCP 47 tag.
807
+ */
808
+ get fallbackLocale(): string;
809
+ set fallbackLocale(value: string);
810
+ /**
811
+ * Every locale any loaded document declares, sorted.
812
+ *
813
+ * @returns The BCP 47 tags.
814
+ */
815
+ get availableLocales(): readonly string[];
816
+ /**
817
+ * Emitted after {@link I18nService.locale} changed. UI that caches rendered strings — `HudText`
818
+ * does — redraws from here.
819
+ *
820
+ * @returns The signal.
821
+ */
822
+ get onLocaleChanged(): SignalLike<string>;
823
+ /**
824
+ * Merges a translation document into the service.
825
+ *
826
+ * @remarks
827
+ * Accepts a loaded {@link LocaleAsset} or the handle of one, in which case the merge happens when
828
+ * the handle settles. Later loads win on a repeated key, which is what makes a per-locale
829
+ * download or a downloadable language pack work. The first document loaded also sets
830
+ * {@link I18nService.fallbackLocale} and, when the app is still on its starting locale and the
831
+ * document does not declare it, moves the active locale to the document's `defaultLocale`.
832
+ *
833
+ * @param source - A loaded document, or its handle.
834
+ * @returns A promise that settles once the document has been merged.
835
+ *
836
+ * @example
837
+ * ```ts
838
+ * using strings = app.assets.load<LocaleAsset>("ui/strings.i18n.json");
839
+ * await app.i18n.load(strings);
840
+ * ```
841
+ */
842
+ load(source: AssetHandle<LocaleAsset> | LocaleAsset): Promise<void>;
843
+ /**
844
+ * Whether the active locale, or the fallback, has an entry for a key.
845
+ *
846
+ * @param key - The message key.
847
+ * @returns `true` when {@link I18nService.t} will find a message.
848
+ */
849
+ has(key: string): boolean;
850
+ /**
851
+ * Renders a message.
852
+ *
853
+ * @param key - The message key.
854
+ * @param params - The values `{name}` placeholders and plural selectors read.
855
+ * @returns The rendered message, or the key itself when no document declares it.
856
+ *
857
+ * @example
858
+ * ```ts
859
+ * app.i18n.t("hud.lives", { count: 1 }); // "1 life"
860
+ * app.i18n.t("hud.lives", { count: 4 }); // "4 lives"
861
+ * ```
862
+ */
863
+ t(key: string, params?: MessageParams): string;
864
+ /**
865
+ * Drops every loaded document.
866
+ *
867
+ * @internal
868
+ */
869
+ clear(): void;
870
+ /**
871
+ * Releases everything the service holds.
872
+ *
873
+ * @internal
874
+ */
875
+ dispose(): void;
876
+ }
877
+ //#endregion
878
+ //#region src/augmentation.d.ts
879
+ /**
880
+ * The typed entry points (`docs/architecture/03-scripting-and-components.md` §7). Declaration
881
+ * merging is what makes `this.app.ui` and `this.app.i18n` fully typed when `@ignifx/ui` is
882
+ * installed and a compile error when it is not.
883
+ *
884
+ * Two mechanics carry over from `@ignifx/input` and `@ignifx/2d`, both measured rather than assumed:
885
+ *
886
+ * - The module **must** import something from `@ignifx/core`. A `declare module "@ignifx/core"`
887
+ * block in a file that never imports the module is `TS2664: Invalid module name in augmentation`
888
+ * under both `tsc --build` and TypeDoc; importing the `ExtensionContext` type used below is
889
+ * enough to bring the module into the program.
890
+ * - The barrel **must** name this module in a bare `import "./augmentation.js"`. Declaration
891
+ * bundling drops a module whose only exports are unreferenced from the public surface, which
892
+ * silently takes the augmentation out of `dist/index.d.ts` with it. The bare import is a
893
+ * type-only side effect: the emitted JavaScript keeps no statement for it, so `sideEffects: false`
894
+ * stays honest.
895
+ */
896
+ declare module "@ignifx/core" {
897
+ interface App {
898
+ /**
899
+ * The DOM overlay host (`docs/architecture/13-ui.md` §1): the root over the canvas, the named
900
+ * layers, the scaling modes, the safe-area variables, and the focus flag.
901
+ */
902
+ readonly ui: UiHost;
903
+ /**
904
+ * The localization service (`docs/architecture/13-ui.md` §3): `.i18n.json` documents,
905
+ * `{name}` interpolation, ICU-style plurals, and the active locale.
906
+ */
907
+ readonly i18n: I18nService;
908
+ }
909
+ }
910
+ //#endregion
911
+ //#region src/dom/focus.d.ts
912
+ /**
913
+ * Focus routing (`docs/architecture/13-ui.md` §1, `08-input.md` §5).
914
+ *
915
+ * ## What `@ignifx/input` does and does not do
916
+ *
917
+ * `InputService.uiHasFocus` is a **plain settable property**; its own documentation says so —
918
+ * "`@ignifx/ui` assigns it"* (`packages/input/src/service/input-service.ts` 340-349). Nothing in
919
+ * `@ignifx/input` watches the DOM for it: `FocusSource` subscribes only to `blur` and
920
+ * `visibilitychange`, and translates both into one `releaseAll`. So the policy for *what counts as
921
+ * a focused text field* is defined here, by this module, and this module is the only thing that
922
+ * ever writes the flag. While it is `true`, `Binding.readRef` reports every keyboard control as
923
+ * released (`packages/input/src/bindings/binding.ts` 330 and 350), which is what makes typing in a
924
+ * field stop firing actions; pointer and gamepad controls are untouched.
925
+ *
926
+ * ## The policy
927
+ *
928
+ * An element takes the keyboard when it is a text-entry element: a `<textarea>`, a `<select>`, a
929
+ * `contenteditable` element, or an `<input>` whose type is not one of the button-like or
930
+ * slider-like types (which games legitimately want to drive with the keyboard *and* have the
931
+ * player use). Two data attributes override the guess in either direction, for the widgets a
932
+ * framework builds out of `<div role="textbox">` and for the search box a game wants to keep
933
+ * transparent to gameplay:
934
+ *
935
+ * - `data-ignifx-focus="capture"` — always takes the keyboard.
936
+ * - `data-ignifx-focus="ignore"` — never takes it.
937
+ */
938
+ /**
939
+ * The attribute that overrides the editability guess in either direction.
940
+ *
941
+ * @public
942
+ */
943
+ export declare const UI_FOCUS_ATTRIBUTE = "data-ignifx-focus";
944
+ /**
945
+ * Reports whether a focused node is a text-entry element, and therefore owns the keyboard.
946
+ *
947
+ * @remarks
948
+ * Deliberately structural rather than `instanceof HTMLInputElement`: the same function then answers
949
+ * for a real element in Chromium and for the fake DOM the node suite builds, and two documents in
950
+ * one page (an `<iframe>`) do not need their constructors to match.
951
+ *
952
+ * @param node - The node that just received focus, or `null`.
953
+ * @returns `true` when typing into it must stop keyboard actions from firing.
954
+ *
955
+ * @example
956
+ * ```ts
957
+ * const field = document.createElement("input");
958
+ * isEditableElement(field); // true — an <input> with no type is a text field
959
+ * ```
960
+ *
961
+ * @public
962
+ */
963
+ export declare function isEditableElement(node: unknown): boolean;
964
+ //#endregion
965
+ //#region src/dom/styles.d.ts
966
+ /**
967
+ * The one stylesheet `@ignifx/ui` injects, and the class names it defines
968
+ * (`docs/architecture/13-ui.md` §3: *"plain DOM helper classes with no styling opinions beyond a
969
+ * minimal stylesheet; templates ship their own CSS"*).
970
+ *
971
+ * The rules do only what a game cannot reasonably be asked to repeat: position the root over the
972
+ * canvas, make it click-through, and give the helper widgets a shape that is visible before any
973
+ * game CSS loads. No rule uses `!important`, and every rule is a single class selector — except the
974
+ * two that carry a state a game must not be able to defeat by accident: `.ignifx-ui-menu[hidden]`,
975
+ * which is what actually hides a menu, and the `[data-focused]` / `[data-disabled]` row states,
976
+ * which a game restyles by writing the same selector.
977
+ */
978
+ /**
979
+ * The `id` of the injected `<style>` element, so a second app in one document reuses it.
980
+ *
981
+ * @public
982
+ */
983
+ export declare const UI_STYLE_ELEMENT_ID = "ignifx-ui-styles";
984
+ /**
985
+ * The `z-index` a `Dialog` is drawn at inside its layer.
986
+ *
987
+ * @remarks
988
+ * A dialog is modal, and a modal that paints under the panel that opened it swallows every click
989
+ * on that panel. Siblings with no `z-index` paint in DOM order, so a `Dialog` created before a
990
+ * `Menu` in the same layer would lose; giving every dialog one number puts it above every other
991
+ * root of its layer whatever order they were built in. Two dialogs in one layer still stack in DOM
992
+ * order, and `DialogOptions.zIndex` overrides the number for a dialog that must sit elsewhere.
993
+ *
994
+ * @public
995
+ */
996
+ export declare const UI_DIALOG_Z_INDEX = 1e3;
997
+ /**
998
+ * The class names the host and the helper widgets set, so a template's CSS can target them without
999
+ * guessing (`docs/architecture/13-ui.md` §3).
1000
+ *
1001
+ * @public
1002
+ */
1003
+ export declare const UI_CLASS_NAMES: {
1004
+ /** The overlay root. */
1005
+ readonly root: "ignifx-ui-root";
1006
+ /** A named layer inside the root. */
1007
+ readonly layer: "ignifx-ui-layer";
1008
+ /** Anything that should receive pointer events; the root does not. */
1009
+ readonly interactive: "ignifx-ui-interactive";
1010
+ /** A `Dialog`'s outermost element. */
1011
+ readonly dialog: "ignifx-ui-dialog";
1012
+ /** A `Dialog`'s backdrop. */
1013
+ readonly dialogBackdrop: "ignifx-ui-dialog-backdrop";
1014
+ /** A `Dialog`'s panel. */
1015
+ readonly dialogPanel: "ignifx-ui-dialog-panel";
1016
+ /** A `Dialog`'s title. */
1017
+ readonly dialogTitle: "ignifx-ui-dialog-title";
1018
+ /** A `Dialog`'s message. */
1019
+ readonly dialogMessage: "ignifx-ui-dialog-message";
1020
+ /** A `Dialog`'s button row. */
1021
+ readonly dialogButtons: "ignifx-ui-dialog-buttons";
1022
+ /** One `Dialog` button. */
1023
+ readonly dialogButton: "ignifx-ui-dialog-button";
1024
+ /** A `Menu`'s outermost panel. */
1025
+ readonly menu: "ignifx-ui-menu";
1026
+ /** A `Menu`'s heading. */
1027
+ readonly menuTitle: "ignifx-ui-menu-title";
1028
+ /** A `Menu`'s subtitle. */
1029
+ readonly menuSubtitle: "ignifx-ui-menu-subtitle";
1030
+ /** The list a `Menu`'s rows are appended to. */
1031
+ readonly menuRows: "ignifx-ui-menu-rows";
1032
+ /** One selectable `Menu` row. */
1033
+ readonly menuRow: "ignifx-ui-menu-row";
1034
+ /** A `Menu` row's left-hand text. */
1035
+ readonly menuRowLabel: "ignifx-ui-menu-row-label";
1036
+ /** A `Menu` row's right-hand text. */
1037
+ readonly menuRowValue: "ignifx-ui-menu-row-value";
1038
+ /** A `Menu` slider row's range input. */
1039
+ readonly menuRowSlider: "ignifx-ui-menu-row-slider";
1040
+ /** A `Menu`'s `"heading"` row. */
1041
+ readonly menuHeading: "ignifx-ui-menu-heading";
1042
+ /** A `Menu`'s `"separator"` row. */
1043
+ readonly menuSeparator: "ignifx-ui-menu-separator";
1044
+ /** A `Toast`'s stack container. */
1045
+ readonly toastStack: "ignifx-ui-toasts";
1046
+ /** One toast. */
1047
+ readonly toast: "ignifx-ui-toast";
1048
+ /** A `LoadingScreen`'s outermost element. */
1049
+ readonly loading: "ignifx-ui-loading";
1050
+ /** A `LoadingScreen`'s label. */
1051
+ readonly loadingLabel: "ignifx-ui-loading-label";
1052
+ /** A `LoadingScreen`'s progress track. */
1053
+ readonly loadingTrack: "ignifx-ui-loading-track";
1054
+ /** A `LoadingScreen`'s progress bar. */
1055
+ readonly loadingBar: "ignifx-ui-loading-bar";
1056
+ /** A `VirtualJoystick`'s outer pad. */
1057
+ readonly joystick: "ignifx-ui-joystick";
1058
+ /** A `VirtualJoystick`'s knob. */
1059
+ readonly joystickKnob: "ignifx-ui-joystick-knob";
1060
+ /** A `VirtualButton`. */
1061
+ readonly button: "ignifx-ui-button";
1062
+ };
1063
+ /**
1064
+ * The CSS custom properties the root carries, so game CSS can read the safe area and the current
1065
+ * scale without measuring anything (`docs/architecture/13-ui.md` §1).
1066
+ *
1067
+ * @public
1068
+ */
1069
+ export declare const UI_CSS_VARIABLES: {
1070
+ /** The top safe-area inset, from `env(safe-area-inset-top)`. */
1071
+ readonly safeTop: "--ignifx-safe-top";
1072
+ /** The right safe-area inset. */
1073
+ readonly safeRight: "--ignifx-safe-right";
1074
+ /** The bottom safe-area inset. */
1075
+ readonly safeBottom: "--ignifx-safe-bottom";
1076
+ /** The left safe-area inset. */
1077
+ readonly safeLeft: "--ignifx-safe-left";
1078
+ /** The uniform scale the root is drawn at, as a bare number. */
1079
+ readonly scale: "--ignifx-ui-scale";
1080
+ };
1081
+ //#endregion
1082
+ //#region src/errors.d.ts
1083
+ /**
1084
+ * The diagnostic codes `@ignifx/ui` owns. The UI subsystem sits in the `13` range of
1085
+ * `docs/architecture/15-devtools-and-diagnostics.md` §1 — *"`13xx` UI"* — so every code reads
1086
+ * `IGX-13##`. `@ignifx/ui` is the only package in the range and owns all of it.
1087
+ *
1088
+ * The table lives here rather than in `@ignifx/core`'s `CoreErrorCode`: an extension owns its own
1089
+ * codes and hands them to the app through `ExtensionContext.registerErrorCodes`
1090
+ * (`docs/architecture/04-extensions.md` §3).
1091
+ */
1092
+ /**
1093
+ * Every diagnostic code `@ignifx/ui` can throw or log, keyed by an intention-revealing name so call
1094
+ * sites read as prose and the compiler catches typos (coding standards §5.2).
1095
+ *
1096
+ * @example
1097
+ * ```ts
1098
+ * throw uiError(UiErrorCode.unknownLayer, "hud is not a declared UI layer.", {
1099
+ * context: { layer: "hud" },
1100
+ * });
1101
+ * ```
1102
+ *
1103
+ * @public
1104
+ */
1105
+ export declare const UiErrorCode: {
1106
+ /** A second `ui()` extension was registered on one app. */
1107
+ readonly duplicateExtension: "IGX-1301";
1108
+ /** A `.i18n.json` file is not an `ignifx.i18n` document this build can read. */
1109
+ readonly invalidLocaleFile: "IGX-1302";
1110
+ /** `app.i18n.locale` was set to a locale the loaded document does not declare. */
1111
+ readonly unknownLocale: "IGX-1303";
1112
+ /** A message pattern could not be parsed: an unbalanced brace or an unknown argument form. */
1113
+ readonly invalidMessagePattern: "IGX-1304";
1114
+ /** A widget that needs `@ignifx/input` was built on an app that did not register it. */
1115
+ readonly inputExtensionMissing: "IGX-1305";
1116
+ /** A `WorldText` or `HudText` was asked to draw before its `font` asset was assigned. */
1117
+ readonly missingFont: "IGX-1306";
1118
+ /** A DOM-only member was reached on a host with no document, and did nothing. */
1119
+ readonly headlessNoOp: "IGX-1307";
1120
+ /** A `WorldText` needed a scene renderable after the render scene had already been built. */
1121
+ readonly sceneAlreadyBuilt: "IGX-1308";
1122
+ };
1123
+ /**
1124
+ * The union of the codes the `UiErrorCode` table declares.
1125
+ *
1126
+ * @public
1127
+ */
1128
+ export type UiErrorCode = (typeof UiErrorCode)[keyof typeof UiErrorCode];
1129
+ /**
1130
+ * The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
1131
+ * Context keys appear in braces, matching the core table's convention.
1132
+ *
1133
+ * @public
1134
+ */
1135
+ export declare const UI_ERROR_MESSAGES: Readonly<Record<string, string>>;
1136
+ /**
1137
+ * Options accepted by {@link uiError}: the same subset of `IgnifxErrorOptions` this package uses.
1138
+ *
1139
+ * @public
1140
+ */
1141
+ interface UiErrorOptions {
1142
+ /** Identifiers that locate the failure. */
1143
+ readonly context?: ErrorContext;
1144
+ /** One sentence telling the developer what to do about it. */
1145
+ readonly hint?: string;
1146
+ /** The failure being wrapped, when there is one. */
1147
+ readonly cause?: unknown;
1148
+ }
1149
+ /**
1150
+ * Builds an `IgnifxError` carrying one of this package's codes.
1151
+ *
1152
+ * @param code - The code from the `UiErrorCode` table.
1153
+ * @param message - The actionable development sentence.
1154
+ * @param options - Context identifiers, a remedy hint, and the wrapped cause.
1155
+ * @returns The error to throw or to reject with.
1156
+ *
1157
+ * @example
1158
+ * ```ts
1159
+ * throw uiError(UiErrorCode.unknownLocale, "fr is not a locale strings.i18n.json declares.", {
1160
+ * context: { locale: "fr" },
1161
+ * });
1162
+ * ```
1163
+ *
1164
+ * @public
1165
+ */
1166
+ export declare function uiError(code: UiErrorCode, message: string, options?: UiErrorOptions): IgnifxError;
1167
+ //#endregion
1168
+ //#region src/extension.d.ts
1169
+ /**
1170
+ * The `@ignifx/ui` extension (`docs/architecture/04-extensions.md` §1, `13-ui.md`).
1171
+ * Registering it is the whole installation: `ui()` gives a game `app.ui`, `app.i18n`, four
1172
+ * components, the `i18n` asset type, the `ui` settings section, and the one `PreRender` system that
1173
+ * projects anchors and re-shapes text.
1174
+ *
1175
+ * ## What it needs, and what it does not
1176
+ *
1177
+ * `@ignifx/input` is an **optional** peer. The overlay host, the text components, and the
1178
+ * localization service work without it; only `VirtualJoystick` and `VirtualButton` need it, and
1179
+ * they say so with `IGX-1305`. The extension never imports it — it reaches
1180
+ * `app.input.uiHasFocus` structurally, for the reason `src/widgets/virtual-device.ts` records.
1181
+ *
1182
+ * ## Headless
1183
+ *
1184
+ * Everything registers headlessly. With no DOM canvas the host is inert (`13-ui.md` §1's
1185
+ * "the host hides itself in headless mode"*, read through `07-rendering.md` §6's rule that a
1186
+ * headless member is a documented no-op rather than a throw), no text renderer is created, and the
1187
+ * `PreRender` system still runs — so `WorldText` keeps its state and a test asserts on it.
1188
+ */
1189
+ /**
1190
+ * What `ui()` accepts. Every field that names a settings value overrides the matching `ui` section
1191
+ * value, which is the shape `04-extensions.md` §1 shows for `physics()`.
1192
+ *
1193
+ * @public
1194
+ */
1195
+ interface UiOptions {
1196
+ /** How the overlay's coordinate system relates to the canvas. */
1197
+ readonly scaling?: UiScalingMode;
1198
+ /** The `[width, height]` the `"fit"` mode scales to. */
1199
+ readonly referenceResolution?: readonly number[];
1200
+ /** The layers created up front, back to front. */
1201
+ readonly layers?: readonly string[];
1202
+ /** Whether the overlay starts shown. */
1203
+ readonly visible?: boolean;
1204
+ /**
1205
+ * The address of a `.i18n.json` document to load into `app.i18n` at start-up. Empty loads
1206
+ * nothing; a game that ships one file per locale calls `app.i18n.load` itself.
1207
+ */
1208
+ readonly strings?: string;
1209
+ /** The locale the app starts in, before any document is loaded. Defaults to `"en"`. */
1210
+ readonly locale?: string;
1211
+ }
1212
+ /**
1213
+ * The `@ignifx/ui` extension factory.
1214
+ *
1215
+ * @param options - Overrides for the `ui` settings section, plus the start-up translation document.
1216
+ * @returns The extension descriptor to pass to `createApp`.
1217
+ *
1218
+ * @example
1219
+ * ```ts
1220
+ * const app = await createApp({
1221
+ * canvas,
1222
+ * extensions: [ui({ scaling: "fit", referenceResolution: [640, 360] })],
1223
+ * });
1224
+ * ```
1225
+ *
1226
+ * @public
1227
+ */
1228
+ export declare const ui: (options?: UiOptions) => Extension;
1229
+ //#endregion
1230
+ //#region src/i18n/loader.d.ts
1231
+ /**
1232
+ * The `i18n` asset loader: `.i18n.json` to {@link LocaleAsset}
1233
+ * (`docs/architecture/05-assets-and-loading.md` §5).
1234
+ *
1235
+ * The file is data, so the loader is identical under Node and in a browser and has nothing to
1236
+ * release on unload. `.i18n.json` is a longer suffix than `.json` and the asset service picks the
1237
+ * longest match, so registering it does not shadow the generic JSON loader.
1238
+ */
1239
+ /**
1240
+ * Builds the loader for `.i18n.json` addresses.
1241
+ *
1242
+ * @returns The loader to register with `ctx.registerAssetLoader`.
1243
+ *
1244
+ * @example
1245
+ * ```ts
1246
+ * ctx.registerAssetLoader(createLocaleLoader());
1247
+ * ```
1248
+ *
1249
+ * @public
1250
+ */
1251
+ export declare function createLocaleLoader(): AssetLoader<LocaleAsset>;
1252
+ //#endregion
1253
+ //#region src/lite/text.d.ts
1254
+ /**
1255
+ * The device-free half of the Babylon Lite text adapter (`docs/architecture/13-ui.md` §2).
1256
+ * Everything here shapes text, measures it, and builds the pure-data objects a renderer later
1257
+ * draws; nothing touches `engine._device`, which is why this module is **not** under `./gpu/` and
1258
+ * is covered by the node suite. Only `createTextRenderer` needs a surface, and that lives in
1259
+ * `./gpu/text-renderer.ts`.
1260
+ *
1261
+ * ## What was verified against `@babylonjs/lite@1.27.0`
1262
+ *
1263
+ * - `createDefaultTextData(font, fontSizePx, text, textColor?, options?)` (`index.d.ts` 2377)
1264
+ * shapes the string, extracts the glyph outlines, and **owns its own `GlyphStorage`** — the
1265
+ * doc comment at 2375 says so, and `disposeDefaultTextData` (3948) releases both. The returned
1266
+ * `DefaultTextData` carries the laid-out `width` and `height` in pixels (3736-3741), which is
1267
+ * the only text measurement Lite offers.
1268
+ * - `updateDefaultTextData(data, text, textColor?)` (13247) re-shapes **with the font size and the
1269
+ * layout options the block was created with** — `lib/text/default-text-data.js` reads
1270
+ * `data._fontSizePx` and `data._options` and never takes new ones — and writes fresh `width`
1271
+ * and `height` onto the block. Changing `fontSize`, `maxWidth`, `align`, `lineHeight`, or the
1272
+ * font therefore means **recreating** the block; changing `text` or `color` does not. Omitting
1273
+ * `textColor` preserves the run's existing colour (13245-13246).
1274
+ * - `TextLayoutOptions` (12821) is `{ maxWidth, lineHeight, align, letterSpacing, tabSize }`, in
1275
+ * output pixels, with simple LTR word wrapping.
1276
+ * - `align` aligns the lines of a block against **the longest line**, not against `maxWidth`:
1277
+ * measured on the pinned build, `"AAAA\nB"` at 32 px puts the `B` at x 0, 25.92 and 51.84 for
1278
+ * `"left"`, `"center"` and `"right"`, with `width` 69.12 in all three. Centring a block on the
1279
+ * screen is therefore the caller's arithmetic, against {@link measureText}.
1280
+ * - Glyph baselines run **downwards in negative y**: line n sits at `-n × fontSizePx × lineHeight`
1281
+ * (`PlacedGlyph`, 8854-8858). A block's first baseline is at the layer's `positionPx`, so its
1282
+ * ascent is above that point.
1283
+ * - `createTextLayer(data, options)` (3257) and `createTextRenderable(data, options)` (3264) are
1284
+ * pure object construction; `lib/text/text-renderer.js` and `lib/text/text-renderable.js` build
1285
+ * plain records with `_gpu: null` and allocate GPU resources lazily on the first frame.
1286
+ * - **There is no `removeTextRenderable`.** `addTextRenderable(scene, renderable)` (208) pushes a
1287
+ * deferred builder onto the scene (`lib/text/text-renderable.js` 242-249) and Lite exposes no
1288
+ * inverse — `removeFromScene` (9613) takes meshes, lights, cameras, shadow generators, transform
1289
+ * nodes and asset containers, and not a `TextRenderable`. {@link detachSceneText} therefore
1290
+ * empties the block and zeroes its opacity, which makes it draw nothing; the record itself stays
1291
+ * in the scene's renderable list until the scene is disposed. This is reported as a Lite gap.
1292
+ *
1293
+ * Everything here is `@internal` apart from the type aliases the `.lite` escape hatches name.
1294
+ */
1295
+ /**
1296
+ * The Babylon Lite font handle, re-exported under an ignifx name so feature code can name the type
1297
+ * without importing `@babylonjs/lite` (`CONSTITUTION.md` §3.4).
1298
+ *
1299
+ * @remarks
1300
+ * Unstable: it is Lite's own type, reachable only through documented `.lite` escape hatches.
1301
+ *
1302
+ * @public
1303
+ */
1304
+ type LiteFont = Font;
1305
+ /**
1306
+ * A shaped block of text, with its glyph storage.
1307
+ *
1308
+ * @remarks
1309
+ * Unstable escape-hatch type.
1310
+ *
1311
+ * @public
1312
+ */
1313
+ type LiteTextData = DefaultTextData;
1314
+ /**
1315
+ * A 2D text layer placed in render-target pixel space.
1316
+ *
1317
+ * @remarks
1318
+ * Unstable escape-hatch type.
1319
+ *
1320
+ * @public
1321
+ */
1322
+ type LiteTextLayer = TextLayer;
1323
+ /**
1324
+ * A scene renderable that draws a block of text in world space.
1325
+ *
1326
+ * @remarks
1327
+ * Unstable escape-hatch type.
1328
+ *
1329
+ * @public
1330
+ */
1331
+ type LiteTextRenderable = TextRenderable;
1332
+ /**
1333
+ * The standalone rendering context that draws 2D text layers onto the swapchain.
1334
+ *
1335
+ * @remarks
1336
+ * Unstable escape-hatch type.
1337
+ *
1338
+ * @public
1339
+ */
1340
+ type LiteTextRenderer = TextRenderer;
1341
+ /**
1342
+ * The pixel size of a laid-out block.
1343
+ *
1344
+ * @public
1345
+ */
1346
+ interface TextMetrics {
1347
+ /** The width of the longest line, in render-target pixels. */
1348
+ readonly width: number;
1349
+ /** The number of lines times the line height, in render-target pixels. */
1350
+ readonly height: number;
1351
+ }
1352
+ //#endregion
1353
+ //#region src/schemas.d.ts
1354
+ /**
1355
+ * The documentation harness's view of everything `@ignifx/ui` declares
1356
+ * (`docs/architecture/16-docs-harness-and-skill.md` §3, `scripts/README.md`).
1357
+ *
1358
+ * `pnpm docs:schemas` imports the built entry point, calls {@link describeSchemas}, and renders
1359
+ * `skills/ignifx/references/formats/<format>.md` plus `ignifx.schemas.json` from the result. The
1360
+ * **function** form is what a package exports rather than a `schemas` object: building the record
1361
+ * means calling `describeSchema` for every component, and module scope holds declarations only
1362
+ * (`CONSTITUTION.md` §3.5).
1363
+ *
1364
+ * The translation document is keyed `ignifx/i18n-file` rather than `ignifx.i18n`: the harness
1365
+ * rejects a key with no `/` (`scripts/lib/schema-source.ts`), and it is the entry's `format` — not
1366
+ * its key — that decides which page it lands on. `@ignifx/core` and `@ignifx/audio` key their file
1367
+ * formats the same way.
1368
+ */
1369
+ /**
1370
+ * Describes every component and file format this package declares, for the documentation harness.
1371
+ *
1372
+ * @returns The records, keyed by namespaced type id.
1373
+ *
1374
+ * @example
1375
+ * ```ts
1376
+ * describeSchemas()["ignifx/HudText"].fields["fontSize"].default; // 32
1377
+ * ```
1378
+ *
1379
+ * @public
1380
+ */
1381
+ export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
1382
+ //#endregion
1383
+ //#region src/text/hud-layout.d.ts
1384
+ /**
1385
+ * Where a shaped block goes on the screen (`docs/architecture/13-ui.md` §2).
1386
+ *
1387
+ * Pure arithmetic, so the node suite covers all nine anchors with no GPU and no DOM.
1388
+ *
1389
+ * ## What Lite gives, and what it does not
1390
+ *
1391
+ * A `DefaultTextData` reports the laid-out `width` and `height` of the block and nothing else — no
1392
+ * ascent, no descent, no baseline offset (`index.d.ts` 3736-3741). Glyph baselines run downwards
1393
+ * in negative y from the layer's `positionPx`, verified on the pinned build: `"A\nB\nC"` at 32 px
1394
+ * with `lineHeight` 2 places the three baselines at y `0`, `-64`, `-128`.
1395
+ *
1396
+ * So the **first baseline** is at `positionPx.y`, and the box the reader perceives starts one em
1397
+ * above it. `ascentOf` is that approximation, stated once here rather than guessed at in three
1398
+ * components: an em is the right order of magnitude for every Latin face and it is what makes
1399
+ * `anchor: "topLeft"` put the text just inside the top-left corner rather than half off-screen.
1400
+ */
1401
+ /**
1402
+ * The nine points of a rectangle a block can be anchored to.
1403
+ *
1404
+ * @public
1405
+ */
1406
+ export declare const HUD_ANCHORS: readonly ["topLeft", "top", "topRight", "left", "center", "right", "bottomLeft", "bottom", "bottomRight"];
1407
+ /**
1408
+ * Which point of the render target a `HudText`'s position is measured from, and which point of the
1409
+ * block sits there.
1410
+ *
1411
+ * @public
1412
+ */
1413
+ type HudAnchor = (typeof HUD_ANCHORS)[number];
1414
+ /**
1415
+ * A layer position, written in place so the per-frame path allocates nothing.
1416
+ *
1417
+ * @public
1418
+ */
1419
+ interface HudPlacement {
1420
+ /** The layer's x, in render-target pixels. */
1421
+ x: number;
1422
+ /** The layer's y — the first baseline — in render-target pixels. */
1423
+ y: number;
1424
+ }
1425
+ /**
1426
+ * What {@link computeHudPlacement} needs.
1427
+ *
1428
+ * @public
1429
+ */
1430
+ interface HudPlacementInput {
1431
+ /** Which point of the target the position is measured from, and which point of the block lands there. */
1432
+ readonly anchor: HudAnchor;
1433
+ /** The offset from that point, in render-target pixels; x grows right, y grows down. */
1434
+ readonly offsetX: number;
1435
+ /** The offset from that point, in render-target pixels. */
1436
+ readonly offsetY: number;
1437
+ /** The render target's width, in pixels. */
1438
+ readonly targetWidth: number;
1439
+ /** The render target's height, in pixels. */
1440
+ readonly targetHeight: number;
1441
+ /** The block's laid-out width. */
1442
+ readonly blockWidth: number;
1443
+ /** The block's laid-out height. */
1444
+ readonly blockHeight: number;
1445
+ /** The em size the block was shaped at. */
1446
+ readonly fontSize: number;
1447
+ }
1448
+ /**
1449
+ * Places a block against one of the nine anchors of the render target.
1450
+ *
1451
+ * @param input - The anchor, the offset, the target size, and the block's size.
1452
+ * @param out - Receives the layer position.
1453
+ * @returns `out`, for chaining.
1454
+ *
1455
+ * @example
1456
+ * ```ts
1457
+ * const out = { x: 0, y: 0 };
1458
+ * computeHudPlacement(
1459
+ * {
1460
+ * anchor: "topRight",
1461
+ * offsetX: -16,
1462
+ * offsetY: 16,
1463
+ * targetWidth: 800,
1464
+ * targetHeight: 600,
1465
+ * blockWidth: 100,
1466
+ * blockHeight: 40,
1467
+ * fontSize: 32,
1468
+ * },
1469
+ * out,
1470
+ * );
1471
+ * out.x; // 684 — 16 px in from the right edge
1472
+ * ```
1473
+ *
1474
+ * @public
1475
+ */
1476
+ export declare function computeHudPlacement(input: HudPlacementInput, out: HudPlacement): HudPlacement;
1477
+ /**
1478
+ * Places a block around a point, with the given point of the block sitting on it.
1479
+ *
1480
+ * @param pivot - Which point of the block lands on the position.
1481
+ * @param x - The point's x, in render-target pixels.
1482
+ * @param y - The point's y, in render-target pixels.
1483
+ * @param blockWidth - The block's laid-out width.
1484
+ * @param blockHeight - The block's laid-out height.
1485
+ * @param fontSize - The em size the block was shaped at.
1486
+ * @param out - Receives the layer position.
1487
+ * @returns `out`, for chaining.
1488
+ *
1489
+ * @example
1490
+ * ```ts
1491
+ * const out = { x: 0, y: 0 };
1492
+ * computePivotPlacement("center", 400, 300, 100, 40, 32, out);
1493
+ * out.x; // 350
1494
+ * ```
1495
+ *
1496
+ * @public
1497
+ */
1498
+ export declare function computePivotPlacement(pivot: HudAnchor, x: number, y: number, blockWidth: number, blockHeight: number, fontSize: number, out: HudPlacement): HudPlacement;
1499
+ //#endregion
1500
+ //#region src/text/text-component.d.ts
1501
+ /**
1502
+ * The fields and the block lifecycle every text component shares (`docs/architecture/13-ui.md` §2:
1503
+ * "`text`, `fontSize`, `color`, `align`, `maxWidth`, `opacity`, `billboard`"*).
1504
+ *
1505
+ * ## Why the block is rebuilt for some changes and updated for others
1506
+ *
1507
+ * `updateDefaultTextData` re-shapes with the font size and layout options the block was created
1508
+ * with, and only those — verified in `@babylonjs/lite@1.27.0`'s `lib/text/default-text-data.js`, which reads
1509
+ * `data._fontSizePx` and `data._options` and never takes new ones. So a change to `text` or
1510
+ * `color` is an update, which keeps the glyph storage and its atlas; a change to `font`,
1511
+ * `fontSize`, `maxWidth`, `align`, or `lineHeight` is a rebuild. The component tracks both, so a
1512
+ * HUD counter that changes every frame pays for one re-shape and nothing else.
1513
+ *
1514
+ * ## Localization
1515
+ *
1516
+ * `i18nKey` wins over `text` when it is set, and the block is re-shaped whenever
1517
+ * `app.i18n.onLocaleChanged` fires. A component with neither draws nothing rather than drawing an
1518
+ * empty box.
1519
+ */
1520
+ /**
1521
+ * The alignments Lite's default layout supports (`index.d.ts` 12826-12827).
1522
+ *
1523
+ * @public
1524
+ */
1525
+ export declare const TEXT_ALIGNMENTS: readonly ["left", "center", "right"];
1526
+ /**
1527
+ * Which edge a block's lines align to. Lite aligns lines against the block's **longest line**, not
1528
+ * against `maxWidth`, so a single-line block looks the same in all three.
1529
+ *
1530
+ * @public
1531
+ */
1532
+ type TextAlignment = (typeof TEXT_ALIGNMENTS)[number];
1533
+ /**
1534
+ * The base of `HudText`, `WorldText2D`, and `WorldText`: the schema fields and the shaped block.
1535
+ *
1536
+ * @remarks
1537
+ * Abstract, and never registered as a component itself; the three concrete classes are.
1538
+ *
1539
+ * @public
1540
+ */
1541
+ export declare abstract class TextComponent extends Component {
1542
+ #private;
1543
+ /** The TTF or OTF the glyphs come from. */
1544
+ font: AssetHandle<FontAsset> | null;
1545
+ /** The literal string to draw; ignored when {@link TextComponent.i18nKey} is set. */
1546
+ text: string;
1547
+ /** A translation key looked up in `app.i18n`; wins over {@link TextComponent.text}. */
1548
+ i18nKey: string;
1549
+ /** The em size, in render-target pixels. */
1550
+ fontSize: number;
1551
+ /** The colour every glyph starts with. */
1552
+ color: ColorLike;
1553
+ /** Which edge the lines align to. */
1554
+ align: TextAlignment;
1555
+ /** The wrap width, in render-target pixels; `0` does not wrap. */
1556
+ maxWidth: number;
1557
+ /** The line-height multiplier. */
1558
+ lineHeight: number;
1559
+ /** The whole-block alpha multiplier. */
1560
+ opacity: number;
1561
+ /**
1562
+ * The shaped block, or `null` until a font and a non-empty string are both present.
1563
+ *
1564
+ * @returns The block.
1565
+ *
1566
+ * @internal
1567
+ */
1568
+ get block(): LiteTextData | null;
1569
+ /**
1570
+ * The block's laid-out size, in render-target pixels.
1571
+ *
1572
+ * @remarks
1573
+ * `{ width: 0, height: 0 }` until the block exists. This is Lite's only text measurement, and
1574
+ * it is what a caller centring a block on the screen needs — Lite's `align` aligns lines against
1575
+ * each other, not against the screen.
1576
+ *
1577
+ * @returns The size.
1578
+ *
1579
+ * @example
1580
+ * ```ts
1581
+ * const label = entity.addComponent(HudText);
1582
+ * label.metrics.width; // 0 until a font and a string are set
1583
+ * ```
1584
+ */
1585
+ get metrics(): TextMetrics;
1586
+ /**
1587
+ * The string that will actually be drawn: the translated `i18nKey`, or `text`.
1588
+ *
1589
+ * @param i18n - The localization service, or `null` when the app has none.
1590
+ * @returns The resolved string.
1591
+ */
1592
+ resolveText(i18n: I18nService | null): string;
1593
+ /**
1594
+ * Brings the shaped block in line with the component's fields.
1595
+ *
1596
+ * @remarks
1597
+ * The one place a block is created, re-shaped, or destroyed. Called by the UI text system once a
1598
+ * frame; it does nothing at all when nothing changed, which is what keeps a static label free.
1599
+ *
1600
+ * @param i18n - The localization service, or `null`.
1601
+ * @returns `"created"` when a new block was built (the caller has to rebuild its layer or
1602
+ * renderable), `"updated"` when the existing one was re-shaped, `"removed"` when the block went
1603
+ * away, and `"unchanged"` otherwise.
1604
+ *
1605
+ * @internal
1606
+ */
1607
+ syncBlock(i18n: I18nService | null): "created" | "updated" | "removed" | "unchanged";
1608
+ /**
1609
+ * Releases the shaped block. The concrete components call it from `onDestroy`.
1610
+ *
1611
+ * @internal
1612
+ */
1613
+ releaseBlock(): void;
1614
+ }
1615
+ //#endregion
1616
+ //#region src/text/text-runtime.d.ts
1617
+ /**
1618
+ * The text renderer's life, injected rather than imported so the node suite covers it
1619
+ * (`docs/architecture/11-2d-toolkit.md` §1 uses the same shape for the sprite renderer, and
1620
+ * `07-rendering.md` §1 is the rule both follow).
1621
+ *
1622
+ * ## Why the renderer is created lazily
1623
+ *
1624
+ * A `TextRenderer` must be registered **after** the render scene, so it composites over the frame
1625
+ * rather than under it. An extension's `register` runs before the scene exists and its `onStart`
1626
+ * runs only when a game calls `app.start()` — which a headless tool never does. Creating it on the
1627
+ * first `PreRender` tick is the one moment that satisfies both: the scene is registered, and a
1628
+ * headless app never gets there because it has no renderer factory in the first place.
1629
+ */
1630
+ /**
1631
+ * The renderer operations the runtime needs, supplied by the extension so this module never imports
1632
+ * `@babylonjs/lite`.
1633
+ *
1634
+ * @internal
1635
+ */
1636
+ interface TextRuntimeOptions {
1637
+ /** Creates and registers the renderer, or `null` under a headless app. */
1638
+ readonly createRenderer: (() => LiteTextRenderer) | null;
1639
+ /** Adds a layer to the renderer's draw list. */
1640
+ readonly attachLayer: (renderer: LiteTextRenderer, layer: LiteTextLayer) => void;
1641
+ /** Removes a layer from the renderer's draw list. */
1642
+ readonly detachLayer: (renderer: LiteTextRenderer, layer: LiteTextLayer) => boolean;
1643
+ /** Unregisters and disposes the renderer. */
1644
+ readonly destroyRenderer: (renderer: LiteTextRenderer) => void;
1645
+ }
1646
+ /**
1647
+ * Owns the one text renderer an app has, and the layers registered on it.
1648
+ *
1649
+ * @internal
1650
+ */
1651
+ declare class TextRuntime {
1652
+ #private;
1653
+ /**
1654
+ * Builds the runtime. The extension does this.
1655
+ *
1656
+ * @param options - The renderer operations.
1657
+ */
1658
+ constructor(options: TextRuntimeOptions);
1659
+ /**
1660
+ * The renderer, once it exists.
1661
+ *
1662
+ * @returns The renderer, or `null` before the first frame and under a headless app.
1663
+ */
1664
+ get renderer(): LiteTextRenderer | null;
1665
+ /**
1666
+ * How many layers are currently drawn.
1667
+ *
1668
+ * @returns The count.
1669
+ */
1670
+ get layerCount(): number;
1671
+ /**
1672
+ * Creates the renderer if it does not exist yet and flushes the layers that were registered
1673
+ * before it did. The UI text system calls this at the top of every `PreRender`.
1674
+ */
1675
+ ensureRenderer(): void;
1676
+ /**
1677
+ * Starts drawing a layer.
1678
+ *
1679
+ * @param layer - The layer.
1680
+ */
1681
+ addLayer(layer: LiteTextLayer): void;
1682
+ /**
1683
+ * Stops drawing a layer and frees its per-layer GPU buffers.
1684
+ *
1685
+ * @param layer - The layer.
1686
+ */
1687
+ removeLayer(layer: LiteTextLayer): void;
1688
+ /** Tears the renderer down. The extension calls this from `onDispose`. */
1689
+ dispose(): void;
1690
+ }
1691
+ //#endregion
1692
+ //#region src/text/hud-text.d.ts
1693
+ /**
1694
+ * `HudText` (`docs/architecture/13-ui.md` §2): pixel-space text drawn by Babylon Lite rather than
1695
+ * by the DOM, *"when DOM text is not desirable (e.g. capture-perfect pixel HUDs, screenshots via
1696
+ * `captureScreenshot`)"*.
1697
+ *
1698
+ * ## The coordinate system is the render target, not CSS
1699
+ *
1700
+ * Lite's text renderer positions a layer against `surface.canvas.width`/`.height`
1701
+ * (`lib/text/text-renderer.js`), so `position` is in **backing-store pixels**. That is deliberate
1702
+ * and is the whole point of the component: the pixel a `HudText` draws on is the pixel
1703
+ * `app.renderer.captureScreenshot()` reads back, so a golden test asserts on an exact address. A
1704
+ * DOM label in `app.ui.layer("hud")` is the right tool whenever that is not what you want.
1705
+ */
1706
+ /**
1707
+ * Pixel-space HUD text.
1708
+ *
1709
+ * @example
1710
+ * ```ts
1711
+ * const label = app.world.createEntity("score").addComponent(HudText);
1712
+ * label.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
1713
+ * label.anchor = "topLeft";
1714
+ * label.position = { x: 16, y: 16 };
1715
+ * label.i18nKey = "hud.score";
1716
+ * ```
1717
+ *
1718
+ * @public
1719
+ */
1720
+ export declare class HudText extends TextComponent implements ComponentHooks {
1721
+ #private;
1722
+ /** The registration id the serializer writes into scene files. */
1723
+ static typeId: string;
1724
+ /** One HUD label per entity; a second belongs on a second entity. */
1725
+ static allowMultiple: boolean;
1726
+ /** The declarative fields (ADR-0004). */
1727
+ static schema: Schema;
1728
+ /** Which point of the render target {@link HudText.position} is measured from. */
1729
+ anchor: HudAnchor;
1730
+ /** The offset from the anchor, in render-target pixels; x grows right, y grows down. */
1731
+ position: Vec2Like;
1732
+ /** The sort order within the text renderer; lower draws first. */
1733
+ order: number;
1734
+ /** Builds a HUD label with the schema's defaults. */
1735
+ constructor();
1736
+ /**
1737
+ * The Babylon Lite objects the component owns. Unstable escape hatch
1738
+ * (`docs/architecture/00-overview.md` §3).
1739
+ *
1740
+ * @returns The text layer, or `null` before the first frame that had a font and a string.
1741
+ */
1742
+ get lite(): {
1743
+ readonly layer: LiteTextLayer | null;
1744
+ };
1745
+ /** Drops the layer and the block when the component goes away. */
1746
+ onDetach(): void;
1747
+ /**
1748
+ * Brings the layer in line with the component's fields. The UI text system calls it once a frame.
1749
+ *
1750
+ * @param runtime - The renderer the layer is registered on.
1751
+ * @param i18n - The localization service, or `null`.
1752
+ * @param targetWidth - The render target's width, in pixels.
1753
+ * @param targetHeight - The render target's height, in pixels.
1754
+ *
1755
+ * @internal
1756
+ */
1757
+ sync(runtime: TextRuntime, i18n: I18nService | null, targetWidth: number, targetHeight: number): void;
1758
+ }
1759
+ //#endregion
1760
+ //#region src/text/world-text.d.ts
1761
+ /**
1762
+ * `WorldText` (`docs/architecture/13-ui.md` §2): text that is part of the world — a sign, a
1763
+ * banner, a floating label that is hidden by the wall in front of it — drawn as a Babylon Lite
1764
+ * `TextRenderable` inside the render scene.
1765
+ *
1766
+ * ## Blocks are laid out in pixels, so the renderable is scaled down
1767
+ *
1768
+ * `createDefaultTextData` shapes in pixels: at `fontSize` 32 a capital letter is about 32 units
1769
+ * tall. A renderable at scale 1 would therefore be tens of metres high. {@link WorldText.pixelsPerUnit}
1770
+ * is the divisor, defaulting to 100 to match `@ignifx/2d`'s own default, so a 32-pixel block is
1771
+ * 0.32 m tall.
1772
+ *
1773
+ * ## It has to exist before `app.start()`
1774
+ *
1775
+ * `addTextRenderable` (`index.d.ts` 208) pushes a **deferred builder** onto the scene
1776
+ * (`lib/text/text-renderable.js` 242-249), and the only thing that drains those builders is
1777
+ * `buildScene`, which `registerScene` calls once (`lib/scene/scene-core.js` 228-241 and 246-262).
1778
+ * `rebuildSceneRenderables` — the one public rebuild — explicitly does not: it rebuilds *groups*
1779
+ * and returns early on an unbuilt scene, and Lite's runtime-build machinery is for meshes only. So
1780
+ * a renderable added after `app.start()` has registered the scene never materialises, and there is
1781
+ * no public call that would make it.
1782
+ *
1783
+ * A `WorldText` whose font and text are both present before the app starts therefore draws; one
1784
+ * that first gets its text mid-game does not, and says so once with `IGX-1308`. Until Lite exposes
1785
+ * a way to drain a late deferred renderable, the answers are to author signs in the scene file the
1786
+ * game starts with, or to use {@link WorldText2D}, which owns a text *layer* and can be added at
1787
+ * any time.
1788
+ *
1789
+ * ## Removal is one-way
1790
+ *
1791
+ * Babylon Lite 1.27.0 has `addTextRenderable` (`index.d.ts` 208) and **no inverse**:
1792
+ * `removeFromScene` (9613) accepts meshes, lights, cameras, shadow generators, transform nodes and
1793
+ * asset containers, and a `TextRenderable` is none of them. A destroyed `WorldText` therefore
1794
+ * empties its block and zeroes the renderable's opacity — it draws nothing and holds no GPU
1795
+ * buffers — but the record itself stays in the scene's renderable list until the scene is disposed.
1796
+ * A game that spawns and destroys thousands of signs should pool the components rather than the
1797
+ * entities. This is recorded as a Lite gap rather than worked around.
1798
+ */
1799
+ /**
1800
+ * World-space 3D text.
1801
+ *
1802
+ * @example
1803
+ * ```ts
1804
+ * const sign = app.world.createEntity("sign").addComponent(WorldText);
1805
+ * sign.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
1806
+ * sign.text = "Danger";
1807
+ * sign.billboard = true;
1808
+ * ```
1809
+ *
1810
+ * @public
1811
+ */
1812
+ export declare class WorldText extends TextComponent implements ComponentHooks {
1813
+ #private;
1814
+ /** The registration id the serializer writes into scene files. */
1815
+ static typeId: string;
1816
+ /** One sign per entity. */
1817
+ static allowMultiple: boolean;
1818
+ /** The declarative fields (ADR-0004). */
1819
+ static schema: Schema;
1820
+ /** A local offset added to the entity's world position, in metres. */
1821
+ offset: Vec3Like;
1822
+ /** How many pixels of laid-out text span one world metre. */
1823
+ pixelsPerUnit: number;
1824
+ /** Whether the text turns to face the camera instead of following the entity's rotation. */
1825
+ billboard: boolean;
1826
+ /** Whether the text draws through geometry in front of it. */
1827
+ alwaysOnTop: boolean;
1828
+ /** Builds a sign with the schema's defaults. */
1829
+ constructor();
1830
+ /**
1831
+ * The Babylon Lite objects the component owns. Unstable escape hatch.
1832
+ *
1833
+ * @returns The renderable, or `null` before the first frame that had a font and a string.
1834
+ */
1835
+ get lite(): {
1836
+ readonly renderable: LiteTextRenderable | null;
1837
+ };
1838
+ /** Silences and releases the renderable when the component goes away. */
1839
+ onDetach(): void;
1840
+ /**
1841
+ * Brings the renderable in line with the component's fields and the entity's transform.
1842
+ *
1843
+ * @param scene - The Lite scene the renderable is added to, from `app.lite.scene`.
1844
+ * @param i18n - The localization service, or `null`.
1845
+ * @param cameraRotation - The main camera's world rotation, for billboarding, or `null` when the
1846
+ * world has no camera.
1847
+ *
1848
+ * @internal
1849
+ */
1850
+ sync(scene: LiteScene, i18n: I18nService | null, cameraRotation: QuatLike | null): void;
1851
+ /**
1852
+ * The scene the renderable was added to, for diagnostics.
1853
+ *
1854
+ * @returns The scene, or `null` when nothing has been added yet.
1855
+ *
1856
+ * @internal
1857
+ */
1858
+ get scene(): LiteScene | null;
1859
+ }
1860
+ //#endregion
1861
+ //#region src/text/world-text-2d.d.ts
1862
+ /**
1863
+ * `WorldText2D` (`docs/architecture/13-ui.md` §2): text that belongs to the world — damage numbers,
1864
+ * floating names — but is drawn as a flat pixel-space layer rather than as geometry, so it never
1865
+ * shrinks with distance and never intersects a wall.
1866
+ *
1867
+ * It is `HudText`'s twin: the same Lite text layer, positioned from the entity's **projected**
1868
+ * screen position instead of from a screen anchor. `WorldText` is the other choice, and the one to
1869
+ * take when the text should be occluded by the world.
1870
+ */
1871
+ /**
1872
+ * World-anchored pixel-space text.
1873
+ *
1874
+ * @example
1875
+ * ```ts
1876
+ * const damage = app.world.createEntity("damage").addComponent(WorldText2D);
1877
+ * damage.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
1878
+ * damage.text = "-12";
1879
+ * damage.offset = { x: 0, y: 1.8, z: 0 };
1880
+ * ```
1881
+ *
1882
+ * @public
1883
+ */
1884
+ export declare class WorldText2D extends TextComponent implements ComponentHooks {
1885
+ #private;
1886
+ /** The registration id the serializer writes into scene files. */
1887
+ static typeId: string;
1888
+ /** One floating label per entity. */
1889
+ static allowMultiple: boolean;
1890
+ /** The declarative fields (ADR-0004). */
1891
+ static schema: Schema;
1892
+ /** A world-space offset added to the entity's position before projecting, in metres. */
1893
+ offset: Vec3Like;
1894
+ /** A screen-space offset added after projecting, in render-target pixels. */
1895
+ screenOffset: Vec2Like;
1896
+ /** Which point of the block sits on the projected position. */
1897
+ pivot: HudAnchor;
1898
+ /** Whether the label is hidden when the anchor point is behind the camera. */
1899
+ hideWhenBehindCamera: boolean;
1900
+ /** The sort order within the text renderer; lower draws first. */
1901
+ order: number;
1902
+ /** Builds a floating label with the schema's defaults. */
1903
+ constructor();
1904
+ /**
1905
+ * The Babylon Lite objects the component owns. Unstable escape hatch.
1906
+ *
1907
+ * @returns The text layer, or `null` before the first frame that had a font and a string.
1908
+ */
1909
+ get lite(): {
1910
+ readonly layer: LiteTextLayer | null;
1911
+ };
1912
+ /** Drops the layer and the block when the component goes away. */
1913
+ onDetach(): void;
1914
+ /**
1915
+ * Brings the layer in line with the component's fields and the projected position.
1916
+ *
1917
+ * @param runtime - The renderer the layer is registered on.
1918
+ * @param i18n - The localization service, or `null`.
1919
+ * @param screenX - The entity's projected x, in render-target pixels.
1920
+ * @param screenY - The entity's projected y, in render-target pixels.
1921
+ * @param inFront - Whether the anchor point is in front of the camera.
1922
+ *
1923
+ * @internal
1924
+ */
1925
+ sync(runtime: TextRuntime, i18n: I18nService | null, screenX: number, screenY: number, inFront: boolean): void;
1926
+ }
1927
+ //#endregion
1928
+ //#region src/version.d.ts
1929
+ /**
1930
+ * The package's own version, reported as `Extension.version`
1931
+ * (`docs/architecture/04-extensions.md` §1). First-party packages ship one version line, so this
1932
+ * tracks `package.json` and the release tooling bumps both together.
1933
+ */
1934
+ /**
1935
+ * The `@ignifx/ui` version this build was cut from.
1936
+ *
1937
+ * @public
1938
+ */
1939
+ export declare const VERSION = "0.0.0";
1940
+ //#endregion
1941
+ //#region src/widgets/dialog.d.ts
1942
+ /**
1943
+ * `Dialog` (`docs/architecture/13-ui.md` §3): *"plain DOM helper classes with no styling opinions
1944
+ * beyond a minimal stylesheet; templates ship their own CSS"*.
1945
+ *
1946
+ * The whole point is that a template's pause menu is two lines:
1947
+ *
1948
+ * ```ts ignore-check
1949
+ * const pause = new Dialog(app.ui, {
1950
+ * title: "Paused",
1951
+ * buttons: [{ id: "resume", label: "Resume" }, { id: "quit", label: "Quit" }],
1952
+ * });
1953
+ * pause.onChosen.connect((id) => {
1954
+ * pause.hide();
1955
+ * if (id === "resume") app.resume();
1956
+ * });
1957
+ * ```
1958
+ *
1959
+ * Under a headless app every method is a no-op and {@link Dialog.element} is `null`, so the same
1960
+ * code runs in a test.
1961
+ *
1962
+ * ## Stacking
1963
+ *
1964
+ * A dialog is modal, so it is always drawn **above** the other roots of its layer: the stylesheet
1965
+ * gives `.ignifx-ui-dialog` a `z-index` of `UI_DIALOG_Z_INDEX`, and {@link DialogOptions.zIndex}
1966
+ * overrides it per dialog. Without that rule a dialog created before a `Menu` in the same layer
1967
+ * paints under it — siblings with no `z-index` paint in DOM order — and the invisible backdrop
1968
+ * swallows every click meant for the panel on top. Two dialogs in one layer still stack in DOM
1969
+ * order, so the one shown last is the one on top.
1970
+ */
1971
+ /**
1972
+ * One button in a dialog.
1973
+ *
1974
+ * @public
1975
+ */
1976
+ interface DialogButton {
1977
+ /** The identifier `onChosen` reports. */
1978
+ readonly id: string;
1979
+ /** The text drawn on the button. */
1980
+ readonly label: string;
1981
+ }
1982
+ /**
1983
+ * What `new Dialog(app.ui, options)` accepts.
1984
+ *
1985
+ * @public
1986
+ */
1987
+ interface DialogOptions {
1988
+ /** The heading. Omit for a dialog with no title. */
1989
+ readonly title?: string;
1990
+ /** The body text. Omit for a dialog with no message. */
1991
+ readonly message?: string;
1992
+ /** The buttons, left to right. */
1993
+ readonly buttons?: readonly DialogButton[];
1994
+ /** The layer to mount into. Defaults to `"menu"`. */
1995
+ readonly layer?: string;
1996
+ /** Whether the dialog starts shown. Defaults to `false`. */
1997
+ readonly visible?: boolean;
1998
+ /** Whether a click on the backdrop dismisses the dialog. Defaults to `false`. */
1999
+ readonly dismissOnBackdrop?: boolean;
2000
+ /** The stacking order inside the layer. Defaults to `UI_DIALOG_Z_INDEX`, from the stylesheet. */
2001
+ readonly zIndex?: number;
2002
+ }
2003
+ /**
2004
+ * A modal panel with a title, a message, and buttons.
2005
+ *
2006
+ * @public
2007
+ */
2008
+ export declare class Dialog {
2009
+ #private;
2010
+ /**
2011
+ * Builds the dialog and mounts it hidden.
2012
+ *
2013
+ * @param host - The overlay host, normally `app.ui`.
2014
+ * @param options - The title, the message, the buttons, and the layer.
2015
+ */
2016
+ constructor(host: UiHost, options?: DialogOptions);
2017
+ /**
2018
+ * The dialog's outermost element, so a template can restyle it or mount more into it.
2019
+ *
2020
+ * @returns The element, or `null` when the app has no DOM overlay.
2021
+ */
2022
+ get element(): HTMLDivElement | null;
2023
+ /**
2024
+ * Whether the dialog is shown.
2025
+ *
2026
+ * @returns `true` while it is on screen.
2027
+ */
2028
+ get isVisible(): boolean;
2029
+ /**
2030
+ * Emitted with a button's `id` when it is pressed. The dialog does not hide itself; the game
2031
+ * decides, because "Cancel" and "Delete everything" want different follow-ups.
2032
+ *
2033
+ * @returns The signal.
2034
+ */
2035
+ get onChosen(): SignalLike<string>;
2036
+ /**
2037
+ * Emitted after {@link Dialog.hide}, whatever caused it.
2038
+ *
2039
+ * @returns The signal.
2040
+ */
2041
+ get onDismissed(): SignalLike;
2042
+ /** Shows the dialog. */
2043
+ show(): void;
2044
+ /** Hides the dialog and emits {@link Dialog.onDismissed}. */
2045
+ hide(): void;
2046
+ /**
2047
+ * Replaces the heading, if the dialog was built with one.
2048
+ *
2049
+ * @param text - The new heading.
2050
+ */
2051
+ setTitle(text: string): void;
2052
+ /**
2053
+ * Replaces the body text, if the dialog was built with one.
2054
+ *
2055
+ * @param text - The new message.
2056
+ */
2057
+ setMessage(text: string): void;
2058
+ /**
2059
+ * Replaces the buttons.
2060
+ *
2061
+ * @remarks
2062
+ * One dialog re-used for every question is cheaper than one dialog per question and keeps the
2063
+ * stacking predictable, so the buttons have to be able to change: a confirmation asks
2064
+ * "Yes"/"No", a save error offers "Retry"/"Cancel", and a locale change relabels both.
2065
+ *
2066
+ * @param buttons - The buttons, left to right. An empty list leaves the row empty.
2067
+ *
2068
+ * @example
2069
+ * ```ts ignore-check
2070
+ * dialog.setMessage("Delete this save?");
2071
+ * dialog.setButtons([{ id: "no", label: "No" }, { id: "yes", label: "Yes" }]);
2072
+ * ```
2073
+ */
2074
+ setButtons(buttons: readonly DialogButton[]): void;
2075
+ /** Removes the dialog and unsubscribes. */
2076
+ dispose(): void;
2077
+ }
2078
+ //#endregion
2079
+ //#region src/widgets/loading-screen.d.ts
2080
+ /**
2081
+ * `LoadingScreen` (`docs/architecture/13-ui.md` §3): a full-overlay panel with a label and a
2082
+ * progress bar, bound to `app.assets`.
2083
+ *
2084
+ * ## Where the number comes from
2085
+ *
2086
+ * `app.assets.onProgress` carries `{ loaded, total, bytesLoaded, bytesTotal }`
2087
+ * (`packages/core/src/assets/types.ts`). {@link progressFraction} prefers the byte counts, because
2088
+ * a 40 MB level and a 2 KB config are not half the work each, and falls back to the handle counts
2089
+ * when the build recorded no sizes. A `BatchHandle` from `app.assets.preloadGroup("boot")` reports
2090
+ * its own mean in `progress`, which {@link LoadingScreen.progress} also accepts.
2091
+ *
2092
+ * ## Pairing with the asset-delivery rule
2093
+ *
2094
+ * A completed load settles as soon as it finishes before `app.start()` and after `app.stop()`;
2095
+ * once the loop runs, delivery waits for `PreUpdate`. So a boot screen that awaits
2096
+ * `preloadGroup("boot").promise` **before** `start()` needs no frames, and one that loads a level
2097
+ * mid-game is driven by the frames the loop is already running. Neither case needs this class to
2098
+ * poll.
2099
+ */
2100
+ /**
2101
+ * What `new LoadingScreen(app.ui, options)` accepts.
2102
+ *
2103
+ * @public
2104
+ */
2105
+ interface LoadingScreenOptions {
2106
+ /** The layer to mount into. Defaults to `"overlay"`. */
2107
+ readonly layer?: string;
2108
+ /** The initial label. Defaults to `"Loading…"`. */
2109
+ readonly label?: string;
2110
+ /** Whether the screen starts shown. Defaults to `true` — a boot screen is up before anything else. */
2111
+ readonly visible?: boolean;
2112
+ }
2113
+ /**
2114
+ * The fraction of an asset batch that is done.
2115
+ *
2116
+ * @remarks
2117
+ * Bytes when the build recorded sizes, handles otherwise, and `1` for an empty batch — a loading
2118
+ * screen that never reaches 100% because nothing was queued is worse than one that closes at once.
2119
+ *
2120
+ * @param progress - The payload of `app.assets.onProgress`.
2121
+ * @returns The fraction, in `[0, 1]`.
2122
+ *
2123
+ * @example
2124
+ * ```ts
2125
+ * progressFraction({ loaded: 1, total: 4, bytesLoaded: 0, bytesTotal: 0 }); // 0.25
2126
+ * ```
2127
+ *
2128
+ * @public
2129
+ */
2130
+ export declare function progressFraction(progress: AssetProgress): number;
2131
+ /**
2132
+ * A full-overlay loading panel.
2133
+ *
2134
+ * @example
2135
+ * ```ts
2136
+ * const screen = new LoadingScreen(app.ui, { label: "Loading…" });
2137
+ * screen.bindTo(app.assets);
2138
+ * await app.assets.preloadGroup("boot").promise;
2139
+ * screen.hide();
2140
+ * ```
2141
+ *
2142
+ * @public
2143
+ */
2144
+ export declare class LoadingScreen {
2145
+ #private;
2146
+ /**
2147
+ * Builds the screen and mounts it.
2148
+ *
2149
+ * @param host - The overlay host, normally `app.ui`.
2150
+ * @param options - The layer, the label, and the initial visibility.
2151
+ */
2152
+ constructor(host: UiHost, options?: LoadingScreenOptions);
2153
+ /**
2154
+ * The screen's outermost element, so a template can restyle it or add a logo.
2155
+ *
2156
+ * @returns The element, or `null` when the app has no DOM overlay.
2157
+ */
2158
+ get element(): HTMLDivElement | null;
2159
+ /**
2160
+ * Whether the screen is shown.
2161
+ *
2162
+ * @returns `true` while it is on screen.
2163
+ */
2164
+ get isVisible(): boolean;
2165
+ /**
2166
+ * How far along the bar is, in `[0, 1]`. Writing it moves the bar; values outside the range are
2167
+ * clamped.
2168
+ *
2169
+ * @returns The fraction.
2170
+ */
2171
+ get progress(): number;
2172
+ set progress(value: number);
2173
+ /**
2174
+ * Emitted after {@link LoadingScreen.hide}, whatever caused it.
2175
+ *
2176
+ * @returns The signal.
2177
+ */
2178
+ get onDismissed(): SignalLike;
2179
+ /**
2180
+ * Follows an asset service's aggregate progress until {@link LoadingScreen.dispose} or a second
2181
+ * call to this method.
2182
+ *
2183
+ * @param assets - The asset service, normally `app.assets`.
2184
+ * @returns A function that stops following.
2185
+ */
2186
+ bindTo(assets: Assets): Disconnect;
2187
+ /**
2188
+ * Replaces the label.
2189
+ *
2190
+ * @param text - The new label.
2191
+ */
2192
+ setLabel(text: string): void;
2193
+ /** Shows the screen. */
2194
+ show(): void;
2195
+ /** Hides the screen and emits {@link LoadingScreen.onDismissed}. */
2196
+ hide(): void;
2197
+ /** Removes the screen and stops following the asset service. */
2198
+ dispose(): void;
2199
+ }
2200
+ //#endregion
2201
+ //#region src/widgets/menu-row.d.ts
2202
+ /**
2203
+ * The row vocabulary {@link Menu} draws, and the two pure functions that
2204
+ * turn a row's declaration into the text on screen.
2205
+ *
2206
+ * A row is **declarative**: it says what it edits (`get`/`set`) rather than how to draw it, so the
2207
+ * widget can render it, adjust it with Left/Right, announce it to a screen reader, and keep the
2208
+ * value in step with whatever else changes it. That is the difference between this and a list of
2209
+ * buttons: a settings screen written as buttons has to re-implement clamping, formatting and
2210
+ * repeat in every game.
2211
+ */
2212
+ /**
2213
+ * Text that is either fixed or re-read on every refresh.
2214
+ *
2215
+ * @remarks
2216
+ * A function is what makes a menu localizable: `label: () => app.i18n.t("menu.resume")` re-renders
2217
+ * itself when `app.i18n.locale` changes, because {@link Menu.refresh} calls it again.
2218
+ *
2219
+ * @public
2220
+ */
2221
+ type MenuLabel = string | (() => string);
2222
+ /**
2223
+ * The values a `"choice"` row cycles through: a fixed list, or one read per use.
2224
+ *
2225
+ * @public
2226
+ */
2227
+ type MenuChoiceValues = readonly string[] | (() => readonly string[]);
2228
+ /**
2229
+ * What every selectable row carries.
2230
+ *
2231
+ * @public
2232
+ */
2233
+ interface MenuRowBase {
2234
+ /** A stable id. It becomes the row's `data-row` attribute, which is what a test selects on. */
2235
+ readonly id: string;
2236
+ /** The left-hand text. */
2237
+ readonly label: MenuLabel;
2238
+ /** Whether the row can be selected. A row that answers `false` is drawn dimmed and skipped. */
2239
+ readonly enabled?: () => boolean;
2240
+ }
2241
+ /**
2242
+ * A row that runs something when it is activated.
2243
+ *
2244
+ * @public
2245
+ */
2246
+ interface MenuActionRow extends MenuRowBase {
2247
+ /** What kind of row this is. */
2248
+ readonly kind: "action";
2249
+ /** The right-hand text, when the row shows one. */
2250
+ readonly value?: MenuLabel;
2251
+ /** What Enter, the pad's south button and a click do. */
2252
+ readonly activate?: () => void;
2253
+ }
2254
+ /**
2255
+ * A row that flips a flag.
2256
+ *
2257
+ * @public
2258
+ */
2259
+ interface MenuToggleRow extends MenuRowBase {
2260
+ /** What kind of row this is. */
2261
+ readonly kind: "toggle";
2262
+ /** Reads the flag. */
2263
+ readonly get: () => boolean;
2264
+ /** Writes the flag. */
2265
+ readonly set: (value: boolean) => void;
2266
+ /** Renders the flag. Defaults to the menu's `text.on` / `text.off`. */
2267
+ readonly format?: (value: boolean) => string;
2268
+ }
2269
+ /**
2270
+ * A row that edits a number over a range.
2271
+ *
2272
+ * @remarks
2273
+ * Drawn as a native `<input type="range">` plus the formatted value, because dragging a knob is
2274
+ * worth having and `@ignifx/ui`'s own focus policy deliberately does not count a slider as a text
2275
+ * field (`docs/architecture/13-ui.md` §1), so a slider under the pointer never suppresses gameplay
2276
+ * input.
2277
+ *
2278
+ * @public
2279
+ */
2280
+ interface MenuSliderRow extends MenuRowBase {
2281
+ /** What kind of row this is. */
2282
+ readonly kind: "slider";
2283
+ /** The lowest value the row may take. */
2284
+ readonly min: number;
2285
+ /** The highest value the row may take. */
2286
+ readonly max: number;
2287
+ /** How far one Left or Right press moves the value. */
2288
+ readonly step: number;
2289
+ /** Reads the current value. */
2290
+ readonly get: () => number;
2291
+ /** Writes a new value, already clamped and snapped to the step. */
2292
+ readonly set: (value: number) => void;
2293
+ /** Renders the value. Defaults to the number itself. */
2294
+ readonly format?: (value: number) => string;
2295
+ }
2296
+ /**
2297
+ * A row that cycles through a list of values.
2298
+ *
2299
+ * @public
2300
+ */
2301
+ interface MenuChoiceRow extends MenuRowBase {
2302
+ /** What kind of row this is. */
2303
+ readonly kind: "choice";
2304
+ /** The values to cycle through, in order. */
2305
+ readonly values: MenuChoiceValues;
2306
+ /** Reads the current value. */
2307
+ readonly get: () => string;
2308
+ /** Writes the new value. */
2309
+ readonly set: (value: string) => void;
2310
+ /** Renders a value for display. Defaults to the value itself. */
2311
+ readonly format?: (value: string) => string;
2312
+ }
2313
+ /**
2314
+ * A row that shows one input binding and starts a rebind when it is activated.
2315
+ *
2316
+ * @remarks
2317
+ * The row knows nothing about `@ignifx/input`: it is handed the binding's path as a string and a
2318
+ * callback that starts whatever rebinding flow the game uses. `@ignifx/input`'s
2319
+ * `performInteractiveRebind` is the usual one.
2320
+ *
2321
+ * @public
2322
+ */
2323
+ interface MenuBindingRow extends MenuRowBase {
2324
+ /** What kind of row this is. */
2325
+ readonly kind: "binding";
2326
+ /** Reads the binding path, such as `<Keyboard>/arrowUp`, or `""` when nothing is bound. */
2327
+ readonly path: () => string;
2328
+ /** Starts the rebind. */
2329
+ readonly rebind?: () => void;
2330
+ /** Whether this row's rebind is listening right now, which changes what the row shows. */
2331
+ readonly listening?: () => boolean;
2332
+ }
2333
+ /**
2334
+ * A non-selectable label that groups the rows under it.
2335
+ *
2336
+ * @public
2337
+ */
2338
+ interface MenuHeadingRow {
2339
+ /** What kind of row this is. */
2340
+ readonly kind: "heading";
2341
+ /** A stable id, which becomes the row's `data-row` attribute. */
2342
+ readonly id: string;
2343
+ /** The heading text. */
2344
+ readonly label: MenuLabel;
2345
+ }
2346
+ /**
2347
+ * A non-selectable rule between groups of rows.
2348
+ *
2349
+ * @public
2350
+ */
2351
+ interface MenuSeparatorRow {
2352
+ /** What kind of row this is. */
2353
+ readonly kind: "separator";
2354
+ /** A stable id, which becomes the row's `data-row` attribute. */
2355
+ readonly id: string;
2356
+ }
2357
+ /**
2358
+ * One row of a {@link Menu}.
2359
+ *
2360
+ * @public
2361
+ */
2362
+ type MenuRow = MenuActionRow | MenuBindingRow | MenuChoiceRow | MenuHeadingRow | MenuSeparatorRow | MenuSliderRow | MenuToggleRow;
2363
+ /**
2364
+ * The words a menu uses for the states its rows can be in, so a localized game sets them once per
2365
+ * menu rather than on every row.
2366
+ *
2367
+ * @public
2368
+ */
2369
+ interface MenuText {
2370
+ /** What a `"toggle"` row shows when it is on. Defaults to `"On"`. */
2371
+ readonly on?: MenuLabel;
2372
+ /** What a `"toggle"` row shows when it is off. Defaults to `"Off"`. */
2373
+ readonly off?: MenuLabel;
2374
+ /** What a `"binding"` row shows when nothing is bound. Defaults to `"—"`. */
2375
+ readonly unbound?: MenuLabel;
2376
+ /** What a `"binding"` row shows while it is listening. Defaults to `"Press any key…"`. */
2377
+ readonly listening?: MenuLabel;
2378
+ }
2379
+ /**
2380
+ * Reads a {@link MenuLabel}.
2381
+ *
2382
+ * @param label - The fixed string, the function, or nothing.
2383
+ * @param fallback - What to answer when `label` is `undefined`.
2384
+ * @returns The text to draw.
2385
+ *
2386
+ * @public
2387
+ */
2388
+ export declare function resolveMenuLabel(label: MenuLabel | undefined, fallback: string): string;
2389
+ /**
2390
+ * Reads a {@link MenuChoiceValues}.
2391
+ *
2392
+ * @param values - The fixed list or the function.
2393
+ * @returns The values, in order.
2394
+ *
2395
+ * @public
2396
+ */
2397
+ export declare function resolveMenuChoices(values: MenuChoiceValues): readonly string[];
2398
+ /**
2399
+ * Clamps a number into a range and snaps it to the step.
2400
+ *
2401
+ * @remarks
2402
+ * Snapping rather than accumulating is what stops a slider from drifting by floating-point error
2403
+ * after a few hundred key presses: every value is recomputed from `min` and a whole number of
2404
+ * steps.
2405
+ *
2406
+ * @param value - The raw value.
2407
+ * @param min - The lowest allowed value.
2408
+ * @param max - The highest allowed value.
2409
+ * @param step - The grid the value is snapped to. A step of `0` or less disables snapping.
2410
+ * @returns The clamped, snapped value.
2411
+ *
2412
+ * @example
2413
+ * ```ts
2414
+ * snapToStep(0.37, 0, 1, 0.05); // 0.35
2415
+ * ```
2416
+ *
2417
+ * @public
2418
+ */
2419
+ export declare function snapToStep(value: number, min: number, max: number, step: number): number;
2420
+ /**
2421
+ * Renders an `@ignifx/input` binding path the way a player reads it.
2422
+ *
2423
+ * @param path - The binding path, such as `<Keyboard>/arrowUp`, or `""` for none.
2424
+ * @param unbound - What to answer for an empty path.
2425
+ * @returns The label, such as `Keyboard: Arrow up`.
2426
+ *
2427
+ * @example
2428
+ * ```ts
2429
+ * formatBindingPath("<Keyboard>/arrowUp", "—"); // "Keyboard: Arrow up"
2430
+ * formatBindingPath("", "—"); // "—"
2431
+ * ```
2432
+ *
2433
+ * @public
2434
+ */
2435
+ export declare function formatBindingPath(path: string, unbound: string): string;
2436
+ //#endregion
2437
+ //#region src/widgets/menu.d.ts
2438
+ /**
2439
+ * `Menu` — the list widget every game menu is made of: a title, an optional subtitle, and a
2440
+ * vertical list of {@link MenuRow}s that keyboard, gamepad and pointer all drive through one
2441
+ * selection model.
2442
+ *
2443
+ * It is a DOM helper in the same family as `Dialog`, `Toast` and `LoadingScreen`
2444
+ * (`docs/architecture/13-ui.md` §3: *"plain DOM helper classes with no styling opinions beyond a
2445
+ * minimal stylesheet; templates ship their own CSS"*), and it follows the same two rules: with no
2446
+ * DOM overlay every method is a no-op and {@link Menu.element} is `null`, and every visible piece
2447
+ * carries a `UI_CLASS_NAMES` class that a game restyles.
2448
+ *
2449
+ * ## Why the widget owns the selection instead of the browser
2450
+ *
2451
+ * Every row is `tabindex="-1"` and the selected row is chosen by this class rather than by
2452
+ * `document.activeElement`. The reason is the gamepad: a pad produces no DOM focus events, so pad
2453
+ * navigation needs its own path anyway, and two focus authorities in one screen disagree the first
2454
+ * time a row is added or removed. The DOM focus that does exist goes to the **list**, once, which
2455
+ * is what lets `aria-activedescendant` tell a screen reader where the selection is and what lets
2456
+ * the widget read the keyboard at all. The pointer only *moves* the selection and activates it,
2457
+ * because a mouse already has a cursor.
2458
+ *
2459
+ * ## ARIA
2460
+ *
2461
+ * The list is `role="menu"` and its rows are `role="menuitem"`, with `role="menuitemcheckbox"` plus
2462
+ * `aria-checked` for a `"toggle"` row and `role="separator"` for headings and separators. `menu`
2463
+ * was chosen over `listbox`/`option` for two reasons: WAI-ARIA's `option` expresses only *"is in
2464
+ * the selection"*, so a toggle's on/off state has nowhere to live, while `menuitemcheckbox` is
2465
+ * exactly that state; and a menu is what this is — a list of commands the player runs, not a set of
2466
+ * values one of which is chosen. `aria-activedescendant` on the list expresses the roving selection
2467
+ * without moving focus, which both roles support.
2468
+ *
2469
+ * The one compromise is the slider row. ARIA has no `menuitemslider`, and neither `menuitem` nor
2470
+ * `option` may contain an interactive descendant, so the native `<input type="range">` is marked
2471
+ * `aria-hidden="true"` and `tabindex="-1"`: it is a pointer affordance only, it is not in the
2472
+ * accessibility tree, and the value reaches a screen reader through the row's own accessible name
2473
+ * (its label plus the formatted value), which is refreshed on every change. Left and Right on the
2474
+ * row adjust the value with no pointer at all.
2475
+ */
2476
+ /**
2477
+ * What `new Menu(app.ui, options)` accepts.
2478
+ *
2479
+ * @public
2480
+ */
2481
+ interface MenuOptions {
2482
+ /** A stable id; it becomes the panel's `data-menu` attribute. */
2483
+ readonly id: string;
2484
+ /** The panel's heading. Re-read on every {@link Menu.refresh}. */
2485
+ readonly title?: MenuLabel;
2486
+ /** A line of prose under the heading. */
2487
+ readonly subtitle?: MenuLabel;
2488
+ /** The overlay layer to mount into. Defaults to `"menu"`. */
2489
+ readonly layer?: string;
2490
+ /** The rows to start with. More usually arrive through {@link Menu.setRows}. */
2491
+ readonly rows?: readonly MenuRow[];
2492
+ /** Whether the menu starts shown. Defaults to `false`. */
2493
+ readonly visible?: boolean;
2494
+ /** Whether Escape and {@link Menu.cancel} back out of the menu. Defaults to `true`. */
2495
+ readonly cancelable?: boolean;
2496
+ /**
2497
+ * Whether the widget reads the keyboard itself. Defaults to `true`.
2498
+ *
2499
+ * @remarks
2500
+ * Turn it off when the game drives navigation from its own input actions, or every arrow press
2501
+ * moves the selection twice. A {@link MenuStack} built with a navigation
2502
+ * source does that for you.
2503
+ */
2504
+ readonly keyboard?: boolean;
2505
+ /** Whether the selection wraps at both ends. Defaults to `true`. */
2506
+ readonly wrap?: boolean;
2507
+ /** The words the rows use for their states. */
2508
+ readonly text?: MenuText;
2509
+ }
2510
+ /**
2511
+ * A panel of selectable rows in an overlay layer.
2512
+ *
2513
+ * @example
2514
+ * ```ts ignore-check
2515
+ * const pause = new Menu(app.ui, { id: "pause", title: "Paused" });
2516
+ * pause.setRows([
2517
+ * { kind: "action", id: "resume", label: "Resume", activate: () => pause.hide() },
2518
+ * { kind: "slider", id: "music", label: "Music", min: 0, max: 1, step: 0.05,
2519
+ * get: () => music.volume, set: (v) => { music.volume = v; },
2520
+ * format: (v) => `${String(Math.round(v * 100))}%` },
2521
+ * ]);
2522
+ * pause.show();
2523
+ * ```
2524
+ *
2525
+ * @public
2526
+ */
2527
+ export declare class Menu {
2528
+ #private;
2529
+ /** The id the menu was built with. */
2530
+ readonly id: string;
2531
+ /**
2532
+ * Builds the panel and mounts it, hidden unless `options.visible` says otherwise.
2533
+ *
2534
+ * @param host - The overlay host, normally `app.ui`.
2535
+ * @param options - The id, the heading, the layer, and the starting rows.
2536
+ */
2537
+ constructor(host: UiHost, options: MenuOptions);
2538
+ /**
2539
+ * The panel element, so a game can restyle it or a test can read it.
2540
+ *
2541
+ * @returns The element, or `null` under an app with no DOM overlay.
2542
+ */
2543
+ get element(): HTMLDivElement | null;
2544
+ /**
2545
+ * Whether the panel is on screen.
2546
+ *
2547
+ * @returns `true` between {@link Menu.show} and {@link Menu.hide}.
2548
+ */
2549
+ get isVisible(): boolean;
2550
+ /**
2551
+ * The rows the menu is drawing.
2552
+ *
2553
+ * @returns The rows, in draw order.
2554
+ */
2555
+ get rows(): readonly MenuRow[];
2556
+ /**
2557
+ * The selected row.
2558
+ *
2559
+ * @returns The row under the selection, or `null` when nothing can be selected.
2560
+ */
2561
+ get selected(): MenuRow | null;
2562
+ /**
2563
+ * Where the selection sits.
2564
+ *
2565
+ * @returns The index into {@link Menu.rows}.
2566
+ */
2567
+ get selectedIndex(): number;
2568
+ /**
2569
+ * Whether Escape and {@link Menu.cancel} back out of this menu. A title screen sets it `false`.
2570
+ *
2571
+ * @returns `true` when the menu can be dismissed.
2572
+ */
2573
+ get cancelable(): boolean;
2574
+ set cancelable(value: boolean);
2575
+ /**
2576
+ * Whether the widget reads the keyboard itself.
2577
+ *
2578
+ * @returns `true` while its own `keydown` handler acts.
2579
+ */
2580
+ get keyboardEnabled(): boolean;
2581
+ set keyboardEnabled(value: boolean);
2582
+ /**
2583
+ * Emitted with the newly selected row whenever the selection moves, from any device. A game
2584
+ * connects a click sound to it.
2585
+ *
2586
+ * @returns The signal.
2587
+ */
2588
+ get onSelectionChanged(): SignalLike<MenuRow>;
2589
+ /**
2590
+ * Emitted with the row that was activated, after its own handler ran.
2591
+ *
2592
+ * @returns The signal.
2593
+ */
2594
+ get onActivated(): SignalLike<MenuRow>;
2595
+ /**
2596
+ * Emitted by {@link Menu.cancel} — Escape, the pad's east button, or a call — when the menu is
2597
+ * {@link Menu.cancelable}. A {@link MenuStack} connects `pop` to it.
2598
+ *
2599
+ * @returns The signal.
2600
+ */
2601
+ get onBack(): SignalLike;
2602
+ /**
2603
+ * Replaces the rows and rebuilds the panel.
2604
+ *
2605
+ * @remarks
2606
+ * Rebuilding rather than diffing is deliberate: the row list changes when a save appears, when a
2607
+ * control scheme changes and when the locale changes, and a menu of at most a few dozen rows is
2608
+ * not worth a reconciler. The selection stays on the same row id when that id is still present.
2609
+ *
2610
+ * @param rows - The rows, in draw order.
2611
+ */
2612
+ setRows(rows: readonly MenuRow[]): void;
2613
+ /** Re-reads every label and value and redraws the selection. */
2614
+ refresh(): void;
2615
+ /** Shows the panel, puts the selection on the first row that can take it, and focuses the list. */
2616
+ show(): void;
2617
+ /** Hides the panel. */
2618
+ hide(): void;
2619
+ /**
2620
+ * Moves the selection, skipping headings, separators and disabled rows.
2621
+ *
2622
+ * @param delta - `-1` for up, `1` for down.
2623
+ */
2624
+ moveSelection(delta: -1 | 1): void;
2625
+ /**
2626
+ * Puts the selection on a row by id.
2627
+ *
2628
+ * @param id - The row's {@link MenuRowBase.id}.
2629
+ * @returns `true` when a selectable row with that id was found.
2630
+ */
2631
+ select(id: string): boolean;
2632
+ /**
2633
+ * Runs the selected row's Left or Right behaviour: a slider moves by one step, a toggle flips,
2634
+ * and a choice advances.
2635
+ *
2636
+ * @param direction - `-1` for left, `1` for right.
2637
+ */
2638
+ adjustSelection(direction: -1 | 1): void;
2639
+ /** Runs the selected row's activate behaviour. */
2640
+ activateSelection(): void;
2641
+ /**
2642
+ * Backs out of the menu, if it is {@link Menu.cancelable}.
2643
+ *
2644
+ * @returns `true` when {@link Menu.onBack} was emitted, so the caller knows the press was used.
2645
+ */
2646
+ cancel(): boolean;
2647
+ /** Removes the panel from the overlay and unsubscribes everything. */
2648
+ dispose(): void;
2649
+ }
2650
+ //#endregion
2651
+ //#region src/widgets/menu-stack.d.ts
2652
+ /**
2653
+ * `MenuStack` — screen navigation for {@link Menu}: push a screen on top, pop back to the one
2654
+ * underneath, and drive the whole stack from one place.
2655
+ *
2656
+ * Every front end that has more than one screen needs the same three things, and they are the
2657
+ * three things games get wrong: exactly one screen is visible at a time; Escape (or the pad's east
2658
+ * button) unwinds exactly one level; and a held direction repeats on the **unscaled** clock, so
2659
+ * navigation still works while `app.pause()` has stopped the game.
2660
+ *
2661
+ * ## Why the input is an interface and not `@ignifx/input`
2662
+ *
2663
+ * `@ignifx/input` is an optional peer of `@ignifx/ui` (`docs/architecture/13-ui.md` header), and a
2664
+ * menu is exactly the kind of thing a game builds without it. {@link MenuNavigation} is therefore a
2665
+ * structural shape that an `InputAction` already satisfies — pass the actions of a `UI` action map
2666
+ * straight in — while a game with no input extension passes its own objects, or nothing at all and
2667
+ * uses the widget's own keyboard handling.
2668
+ *
2669
+ * ```ts ignore-check
2670
+ * const ui = app.input.actions.maps.get("UI") ?? null;
2671
+ * const stack = new MenuStack({
2672
+ * navigation: {
2673
+ * move: ui?.actions.get("menuMove") ?? null,
2674
+ * submit: ui?.actions.get("menuSubmit") ?? null,
2675
+ * back: ui?.actions.get("menuBack") ?? null,
2676
+ * },
2677
+ * });
2678
+ * ```
2679
+ *
2680
+ * A stack built with a navigation source turns each pushed menu's own keyboard handling **off**
2681
+ * while the menu is on the stack, and restores it on the way out: otherwise a keyboard bound to
2682
+ * `menuMove` would move the selection twice per press, once through the action and once through
2683
+ * the DOM.
2684
+ */
2685
+ /**
2686
+ * Anything with a two-dimensional value, which `@ignifx/input`'s `InputAction` is.
2687
+ *
2688
+ * @public
2689
+ */
2690
+ interface MenuVectorSource {
2691
+ /** The direction, `-1` to `1` on each axis. Positive `y` is up. */
2692
+ readonly vector: Vec2Like;
2693
+ }
2694
+ /**
2695
+ * Anything with a press edge, which `@ignifx/input`'s `InputAction` is.
2696
+ *
2697
+ * @public
2698
+ */
2699
+ interface MenuButtonSource {
2700
+ /** Whether the control went down this frame. */
2701
+ readonly wasPressedThisFrame: boolean;
2702
+ }
2703
+ /**
2704
+ * The three controls a menu stack reads.
2705
+ *
2706
+ * @public
2707
+ */
2708
+ interface MenuNavigation {
2709
+ /** Moves the selection (`y`) and adjusts the selected row (`x`). */
2710
+ readonly move?: MenuVectorSource | null;
2711
+ /** Activates the selected row. */
2712
+ readonly submit?: MenuButtonSource | null;
2713
+ /** Backs out one screen. */
2714
+ readonly back?: MenuButtonSource | null;
2715
+ }
2716
+ /**
2717
+ * What `new MenuStack(options)` accepts.
2718
+ *
2719
+ * @public
2720
+ */
2721
+ interface MenuStackOptions {
2722
+ /** The controls to read in {@link MenuStack.update}. Omit to drive the stack by hand. */
2723
+ readonly navigation?: MenuNavigation;
2724
+ /** How long the first repeat of a held direction waits, in seconds. Defaults to `0.35`. */
2725
+ readonly repeatDelay?: number;
2726
+ /** How long each following repeat waits, in seconds. Defaults to `0.12`. */
2727
+ readonly repeatInterval?: number;
2728
+ /** How far an axis must move before it counts as a direction. Defaults to `0.5`. */
2729
+ readonly threshold?: number;
2730
+ }
2731
+ /**
2732
+ * A stack of {@link Menu} screens, innermost last.
2733
+ *
2734
+ * @example
2735
+ * ```ts ignore-check
2736
+ * const stack = new MenuStack({ navigation });
2737
+ * stack.push(title);
2738
+ * // in a script that runs while paused:
2739
+ * stack.update(app.time.unscaledDeltaTime);
2740
+ * ```
2741
+ *
2742
+ * @public
2743
+ */
2744
+ export declare class MenuStack {
2745
+ #private;
2746
+ /**
2747
+ * Builds an empty stack.
2748
+ *
2749
+ * @param options - The controls to read, and the repeat timings.
2750
+ */
2751
+ constructor(options?: MenuStackOptions);
2752
+ /**
2753
+ * The menus on the stack, outermost first.
2754
+ *
2755
+ * @returns The menus, in push order.
2756
+ */
2757
+ get menus(): readonly Menu[];
2758
+ /**
2759
+ * The menu on top, which is the visible one.
2760
+ *
2761
+ * @returns The top menu, or `null` when the stack is empty.
2762
+ */
2763
+ get top(): Menu | null;
2764
+ /**
2765
+ * The menu at the bottom, which is the one the stack was opened with.
2766
+ *
2767
+ * @returns The first menu pushed, or `null` when the stack is empty.
2768
+ */
2769
+ get bottom(): Menu | null;
2770
+ /**
2771
+ * How deep the stack is.
2772
+ *
2773
+ * @returns The number of menus on it.
2774
+ */
2775
+ get depth(): number;
2776
+ /**
2777
+ * Whether any menu is open.
2778
+ *
2779
+ * @returns `true` while the stack is not empty.
2780
+ */
2781
+ get isOpen(): boolean;
2782
+ /**
2783
+ * Whether {@link MenuStack.update} is reading its controls.
2784
+ *
2785
+ * @remarks
2786
+ * Set it while something modal is on top of the menu — a confirmation `Dialog`, or a rebind that
2787
+ * is listening for the next key — so that the same press does not reach both.
2788
+ *
2789
+ * @returns `true` while navigation is suspended.
2790
+ */
2791
+ get suspended(): boolean;
2792
+ set suspended(value: boolean);
2793
+ /**
2794
+ * Emitted with the new top menu — `null` when the stack empties — whenever the stack changes. A
2795
+ * game connects its audio ducking and its pause state to it.
2796
+ *
2797
+ * @returns The signal.
2798
+ */
2799
+ get onChanged(): SignalLike<Menu | null>;
2800
+ /**
2801
+ * Emitted with the newly selected row whenever the selection moves on the top menu.
2802
+ *
2803
+ * @returns The signal.
2804
+ */
2805
+ get onSelectionChanged(): SignalLike<MenuRow>;
2806
+ /**
2807
+ * Emitted with the row that was activated on the top menu.
2808
+ *
2809
+ * @returns The signal.
2810
+ */
2811
+ get onActivated(): SignalLike<MenuRow>;
2812
+ /**
2813
+ * Hides whatever is on top and shows `menu` over it.
2814
+ *
2815
+ * @param menu - The menu to open.
2816
+ */
2817
+ push(menu: Menu): void;
2818
+ /**
2819
+ * Closes the top menu and shows the one underneath.
2820
+ *
2821
+ * @returns The menu that was closed, or `null` when the stack was already empty.
2822
+ */
2823
+ pop(): Menu | null;
2824
+ /** Closes every menu on the stack. */
2825
+ closeAll(): void;
2826
+ /** Re-reads every label on every menu on the stack, for a locale change. */
2827
+ refresh(): void;
2828
+ /**
2829
+ * Reads the navigation controls and applies them to the top menu.
2830
+ *
2831
+ * @remarks
2832
+ * Call it from a script that declares `static updateWhenPaused = true`, with
2833
+ * `app.time.unscaledDeltaTime`: a menu that repeats a held direction has to keep time while the
2834
+ * game is stopped, and scaled time is pinned at zero while it is.
2835
+ *
2836
+ * @param unscaledDelta - Seconds since the last call, on the unscaled clock.
2837
+ */
2838
+ update(unscaledDelta: number): void;
2839
+ /** Drops every subscription. The menus themselves belong to the game and are not disposed. */
2840
+ dispose(): void;
2841
+ }
2842
+ //#endregion
2843
+ //#region src/widgets/toast.d.ts
2844
+ /**
2845
+ * `Toast` (`docs/architecture/13-ui.md` §3): a transient message stacked in a corner of the
2846
+ * overlay.
2847
+ *
2848
+ * ## Why the clock is the app's, not the browser's
2849
+ *
2850
+ * A toast dismisses itself after a number of **game seconds**, advanced by
2851
+ * {@link Toast.advance} from the game's own loop, rather than by `setTimeout`. Three reasons: it
2852
+ * pauses when the game pauses, it is deterministic in a headless test that steps the clock, and it
2853
+ * cannot fire after the app has been disposed. A game that wants wall-clock timing passes
2854
+ * `app.time.unscaledDeltaTime`.
2855
+ *
2856
+ * The consequence is the one thing to remember: **`app.pause()` stops `update` for every ordinary
2857
+ * script**, so a toast advanced from an ordinary script freezes with the game and a message shown
2858
+ * from a pause menu never expires. The script that calls {@link Toast.advance} declares
2859
+ * `static updateWhenPaused = true` and passes `app.time.unscaledDeltaTime`. `UiSystem` deliberately
2860
+ * does not advance toasts for you: `docs/architecture/13-ui.md` §3 defines a toast as running on
2861
+ * the game clock, and a system that advanced every toast would take that choice away from the game
2862
+ * and would have to keep a registry of every toast ever built.
2863
+ */
2864
+ /**
2865
+ * What `new Toast(app.ui, options)` accepts.
2866
+ *
2867
+ * @public
2868
+ */
2869
+ interface ToastOptions {
2870
+ /** The layer to mount the stack into. Defaults to `"overlay"`. */
2871
+ readonly layer?: string;
2872
+ /** How long a message stays up, in seconds, unless {@link Toast.show} overrides it. */
2873
+ readonly duration?: number;
2874
+ /** How many messages are stacked before the oldest is dropped. Defaults to `4`. */
2875
+ readonly maxVisible?: number;
2876
+ }
2877
+ /**
2878
+ * A stack of transient messages.
2879
+ *
2880
+ * @example
2881
+ * ```ts
2882
+ * const toasts = new Toast(app.ui);
2883
+ * toasts.show("Checkpoint reached");
2884
+ * // in the update of a script that declares `static updateWhenPaused = true`:
2885
+ * toasts.advance(app.time.unscaledDeltaTime);
2886
+ * ```
2887
+ *
2888
+ * @public
2889
+ */
2890
+ export declare class Toast {
2891
+ #private;
2892
+ /**
2893
+ * Builds the stack and mounts it.
2894
+ *
2895
+ * @param host - The overlay host, normally `app.ui`.
2896
+ * @param options - The layer, the default duration, and the stack depth.
2897
+ */
2898
+ constructor(host: UiHost, options?: ToastOptions);
2899
+ /**
2900
+ * The stack element, so a template can reposition it.
2901
+ *
2902
+ * @returns The element, or `null` when the app has no DOM overlay.
2903
+ */
2904
+ get element(): HTMLDivElement | null;
2905
+ /**
2906
+ * The messages currently on screen, oldest first.
2907
+ *
2908
+ * @returns The texts.
2909
+ */
2910
+ get messages(): readonly string[];
2911
+ /**
2912
+ * Emitted with a message's text when it times out or is pushed off the stack.
2913
+ *
2914
+ * @returns The signal.
2915
+ */
2916
+ get onDismissed(): SignalLike<string>;
2917
+ /**
2918
+ * Shows a message.
2919
+ *
2920
+ * @param text - The message.
2921
+ * @param duration - How long it stays up, in seconds; defaults to the stack's own duration.
2922
+ */
2923
+ show(text: string, duration?: number): void;
2924
+ /**
2925
+ * Advances every message's timer.
2926
+ *
2927
+ * @remarks
2928
+ * Nothing calls this for you. The script that does must declare `static updateWhenPaused = true`
2929
+ * if toasts are to expire while the game is paused — a menu's "Saved" message is shown from a
2930
+ * paused game, and an ordinary script gets no `update` there.
2931
+ *
2932
+ * @param deltaSeconds - Seconds elapsed since the previous call; `dt` from a script's `update`, or
2933
+ * `app.time.unscaledDeltaTime` when the toast has to expire while the game is paused.
2934
+ */
2935
+ advance(deltaSeconds: number): void;
2936
+ /** Removes every message at once. */
2937
+ clear(): void;
2938
+ /** Removes the stack and unsubscribes. */
2939
+ dispose(): void;
2940
+ }
2941
+ //#endregion
2942
+ //#region src/widgets/virtual-button.d.ts
2943
+ /**
2944
+ * `VirtualButton` (`docs/architecture/13-ui.md` §3): an on-screen button that writes a
2945
+ * `<Virtual>/…` button control, so `jump` is one action bound to a key, a gamepad face button, and
2946
+ * this widget at the same time.
2947
+ *
2948
+ * A real `<button>` element rather than a `<div>`, so it is focusable, announced by a screen
2949
+ * reader, and reachable by keyboard. That has one consequence worth knowing: pressing it with the
2950
+ * keyboard fires a `click`, not a `pointerdown`, so the button also releases on `blur` — otherwise a
2951
+ * `Tab` away mid-press would stick.
2952
+ */
2953
+ /**
2954
+ * What `new VirtualButton(app, options)` accepts.
2955
+ *
2956
+ * @public
2957
+ */
2958
+ interface VirtualButtonOptions {
2959
+ /** The `<Virtual>/…` control to write. */
2960
+ readonly control: string;
2961
+ /** The glyph or word drawn on the button. Defaults to the control name. */
2962
+ readonly label?: string;
2963
+ /** The layer to mount into. Defaults to `"hud"`. */
2964
+ readonly layer?: string;
2965
+ /** Inline styles applied to the button, for placement. */
2966
+ readonly style?: Readonly<Record<string, string>>;
2967
+ /** An accessible label. Defaults to the control name. */
2968
+ readonly ariaLabel?: string;
2969
+ }
2970
+ /**
2971
+ * An on-screen button.
2972
+ *
2973
+ * @example
2974
+ * ```ts
2975
+ * const jump = new VirtualButton(app, { control: "jump", label: "A" });
2976
+ * ```
2977
+ *
2978
+ * @public
2979
+ */
2980
+ export declare class VirtualButton {
2981
+ #private;
2982
+ /**
2983
+ * Builds the widget and mounts it.
2984
+ *
2985
+ * @param app - The running app; `app.ui` and `app.input.devices.virtual` are the parts used.
2986
+ * @param options - The control name, the label, the layer, and the placement styles.
2987
+ * @throws IgnifxError with code `IGX-1305` when `@ignifx/input` is not registered.
2988
+ */
2989
+ constructor(app: App, options: VirtualButtonOptions);
2990
+ /**
2991
+ * The button element, so a template can restyle or reposition it.
2992
+ *
2993
+ * @returns The element, or `null` when the app has no DOM overlay.
2994
+ */
2995
+ get element(): HTMLButtonElement | null;
2996
+ /**
2997
+ * The control this button writes.
2998
+ *
2999
+ * @returns The name, as it appears after `<Virtual>/`.
3000
+ */
3001
+ get control(): string;
3002
+ /**
3003
+ * Whether the button is currently held.
3004
+ *
3005
+ * @returns `true` while it is pressed.
3006
+ */
3007
+ get isPressed(): boolean;
3008
+ /** Removes the widget, unsubscribes, and releases the control. */
3009
+ dispose(): void;
3010
+ }
3011
+ //#endregion
3012
+ //#region src/widgets/virtual-device.d.ts
3013
+ /**
3014
+ * How `@ignifx/ui` reaches `@ignifx/input`'s virtual device without importing it
3015
+ * (`docs/architecture/13-ui.md` §3, `08-input.md` §8).
3016
+ *
3017
+ * `@ignifx/input` is an **optional** peer: the overlay host, the text components, and the
3018
+ * localization service do not need it, and only the two touch widgets do. Importing it — even
3019
+ * `import type` — would pull its `declare module "@ignifx/core"` augmentation into every consumer's
3020
+ * program, so an app that installs `@ignifx/ui` alone would suddenly have a typed `app.input` that
3021
+ * does not exist at runtime. The device is therefore reached structurally: the two methods the
3022
+ * widgets call, found by name on `app.input.devices.virtual`.
3023
+ *
3024
+ * `VirtualDevice` satisfies {@link VirtualDeviceLike} exactly
3025
+ * (`packages/input/src/devices/virtual.ts`), so nothing is lost by not naming the class.
3026
+ */
3027
+ /**
3028
+ * The part of `@ignifx/input`'s virtual device the touch widgets use.
3029
+ *
3030
+ * @remarks
3031
+ * Structural on purpose. A test passes a recording double; a game passes
3032
+ * `app.input.devices.virtual`.
3033
+ *
3034
+ * @public
3035
+ */
3036
+ interface VirtualDeviceLike {
3037
+ /**
3038
+ * Writes a scalar control, creating it when it does not exist.
3039
+ *
3040
+ * @param name - The control name, as it appears after `<Virtual>/`.
3041
+ * @param value - The new value.
3042
+ */
3043
+ set(name: string, value: number): void;
3044
+ /**
3045
+ * Writes a vector control, creating it when it does not exist.
3046
+ *
3047
+ * @param name - The control name.
3048
+ * @param x - The new x component.
3049
+ * @param y - The new y component.
3050
+ */
3051
+ setVector(name: string, x: number, y: number): void;
3052
+ }
3053
+ /**
3054
+ * Finds `app.input.devices.virtual`, if `@ignifx/input` is registered.
3055
+ *
3056
+ * @param app - The running app.
3057
+ * @returns The device, or `null` when the input extension is not installed.
3058
+ *
3059
+ * @example
3060
+ * ```ts
3061
+ * const device = findVirtualDevice(app);
3062
+ * device?.setVector("joystick", 0, 1);
3063
+ * ```
3064
+ *
3065
+ * @public
3066
+ */
3067
+ export declare function findVirtualDevice(app: App): VirtualDeviceLike | null;
3068
+ //#endregion
3069
+ //#region src/widgets/virtual-joystick.d.ts
3070
+ /**
3071
+ * `VirtualJoystick` (`docs/architecture/13-ui.md` §3): an on-screen thumbstick that writes a
3072
+ * `<Virtual>/…` vector control, so a touch game binds exactly the same action to
3073
+ * `<Virtual>/joystick` that a desktop game binds to `<Keyboard>/wasd`.
3074
+ *
3075
+ * ## Replacing a template's own widget
3076
+ *
3077
+ * `templates/2d-topdown/src/touch-controls.ts` says it is *"meant to be **deleted** when
3078
+ * `@ignifx/ui` ships a `VirtualJoystick`… the bindings in `game.input.json`
3079
+ * (`<Virtual>/joystick`, `<Virtual>/interact`) do not change"*. This class writes the same two
3080
+ * controls with the same axis convention — screen `+Y` is down and the stick's `+Y` is up, so the
3081
+ * vertical axis is negated here and nowhere else — and the swap is that file's deletion plus:
3082
+ *
3083
+ * ```ts ignore-check
3084
+ * const stick = new VirtualJoystick(app, { control: "joystick" });
3085
+ * const jump = new VirtualButton(app, { control: "interact", label: "E" });
3086
+ * ```
3087
+ *
3088
+ * ## Multi-touch
3089
+ *
3090
+ * The stick claims exactly one `pointerId` and ignores every other pointer until that one is
3091
+ * released, so a thumb on the stick and a thumb on a button never fight. `pointerup` **and**
3092
+ * `pointercancel` both release it: a value written on `pointerdown` and never cleared would leave
3093
+ * the character walking for ever, which is the bug the template's own comment calls out.
3094
+ */
3095
+ /**
3096
+ * What `new VirtualJoystick(app, options)` accepts.
3097
+ *
3098
+ * @public
3099
+ */
3100
+ interface VirtualJoystickOptions {
3101
+ /** The `<Virtual>/…` control to write. Defaults to `"joystick"`. */
3102
+ readonly control?: string;
3103
+ /** The layer to mount into. Defaults to `"hud"`. */
3104
+ readonly layer?: string;
3105
+ /** How far the knob travels, in UI units, before the stick reads as fully deflected. */
3106
+ readonly radius?: number;
3107
+ /** Deflections shorter than this fraction of the radius read as zero. Defaults to `0.15`. */
3108
+ readonly deadZone?: number;
3109
+ /** Inline styles applied to the pad, for placement. */
3110
+ readonly style?: Readonly<Record<string, string>>;
3111
+ /** An accessible label for the pad. Defaults to the control name. */
3112
+ readonly ariaLabel?: string;
3113
+ }
3114
+ /**
3115
+ * Converts a raw deflection into the value written to the control.
3116
+ *
3117
+ * @param delta - The deflection along one axis, in UI units.
3118
+ * @param length - The deflection's length, in UI units.
3119
+ * @param radius - The radius at which the stick is fully deflected.
3120
+ * @param deadZone - The fraction of the radius below which the stick reads as centred.
3121
+ * @returns The axis value, in `-1` to `1`.
3122
+ *
3123
+ * @example
3124
+ * ```ts
3125
+ * stickAxis(0, 0, 44, 0.15); // 0
3126
+ * stickAxis(44, 44, 44, 0.15); // 1
3127
+ * ```
3128
+ *
3129
+ * @public
3130
+ */
3131
+ export declare function stickAxis(delta: number, length: number, radius: number, deadZone: number): number;
3132
+ /**
3133
+ * An on-screen thumbstick.
3134
+ *
3135
+ * @example
3136
+ * ```ts
3137
+ * const stick = new VirtualJoystick(app, { control: "joystick" });
3138
+ * // later
3139
+ * stick.dispose();
3140
+ * ```
3141
+ *
3142
+ * @public
3143
+ */
3144
+ export declare class VirtualJoystick {
3145
+ #private;
3146
+ /**
3147
+ * Builds the widget and mounts it.
3148
+ *
3149
+ * @param app - The running app; `app.ui` and `app.input.devices.virtual` are the parts used.
3150
+ * @param options - The control name, the layer, the geometry, and the placement styles.
3151
+ * @throws IgnifxError with code `IGX-1305` when `@ignifx/input` is not registered.
3152
+ */
3153
+ constructor(app: App, options?: VirtualJoystickOptions);
3154
+ /**
3155
+ * The pad element, so a template can restyle or reposition it.
3156
+ *
3157
+ * @returns The element, or `null` when the app has no DOM overlay.
3158
+ */
3159
+ get element(): HTMLDivElement | null;
3160
+ /**
3161
+ * The control this stick writes.
3162
+ *
3163
+ * @returns The name, as it appears after `<Virtual>/`.
3164
+ */
3165
+ get control(): string;
3166
+ /**
3167
+ * Whether a pointer currently holds the stick.
3168
+ *
3169
+ * @returns `true` while the stick is being dragged.
3170
+ */
3171
+ get isActive(): boolean;
3172
+ /** Removes the widget, unsubscribes, and centres the control. */
3173
+ dispose(): void;
3174
+ }
3175
+ //#endregion
3176
+ //#region src/world/anchor-math.d.ts
3177
+ /**
3178
+ * Where a `WorldAnchor`'s element goes, and whether it is shown
3179
+ * (`docs/architecture/13-ui.md` §2). Pure arithmetic, so every combination of
3180
+ * `hideWhenBehindCamera`, `clampToScreen` and `scaleWithDistance` is a node test with a fake
3181
+ * camera and no DOM.
3182
+ *
3183
+ * ## The two pixel spaces
3184
+ *
3185
+ * `Camera.worldToScreen` writes **render-target** pixels: it divides by
3186
+ * `RendererImpl.readTargetSize`, which is `canvas.width`/`canvas.height`
3187
+ * (`packages/core/src/lite/gpu/render-diagnostics-gpu.ts` 126-128). A DOM element lives in the
3188
+ * overlay's UI units. {@link UiPixelMapping}, built by the host from the current layout, is the
3189
+ * conversion, and it is applied here rather than in the system so the system does nothing but
3190
+ * loop.
3191
+ *
3192
+ * ## Behind the camera
3193
+ *
3194
+ * `worldToScreen` returns `false` and leaves a **mirrored** projection in `out` when the point is
3195
+ * behind the camera — its own documentation says the value "should be ignored". So a point behind
3196
+ * the camera is either hidden (`hideWhenBehindCamera`) or, when the anchor also clamps, reflected
3197
+ * about the viewport centre before being clamped, which pushes an off-screen marker to the correct
3198
+ * edge instead of the opposite one. With neither flag set it is hidden, because a mirrored
3199
+ * position is not a position.
3200
+ */
3201
+ /**
3202
+ * Everything {@link computeAnchorPlacement} reads.
3203
+ *
3204
+ * @public
3205
+ */
3206
+ interface AnchorInput {
3207
+ /** The projected x, in render-target pixels. */
3208
+ readonly screenX: number;
3209
+ /** The projected y, in render-target pixels. */
3210
+ readonly screenY: number;
3211
+ /** Whether the point is in front of the camera. */
3212
+ readonly inFront: boolean;
3213
+ /** How far the point is from the camera, in metres. */
3214
+ readonly distance: number;
3215
+ /** The overlay root's width, in UI units. */
3216
+ readonly viewWidth: number;
3217
+ /** The overlay root's height, in UI units. */
3218
+ readonly viewHeight: number;
3219
+ /** The render-target-pixel to UI-unit conversion. */
3220
+ readonly mapping: UiPixelMapping;
3221
+ /** Whether the element is hidden when the point is behind the camera. */
3222
+ readonly hideWhenBehindCamera: boolean;
3223
+ /** Whether the element is kept inside the overlay's bounds. */
3224
+ readonly clampToScreen: boolean;
3225
+ /** Whether the element shrinks with distance. */
3226
+ readonly scaleWithDistance: boolean;
3227
+ /** The distance at which {@link AnchorInput.scaleWithDistance} produces a scale of `1`. */
3228
+ readonly referenceDistance: number;
3229
+ /** The smallest scale distance scaling may produce. */
3230
+ readonly minScale: number;
3231
+ /** The largest scale distance scaling may produce. */
3232
+ readonly maxScale: number;
3233
+ }
3234
+ /**
3235
+ * Where the element goes, written in place so the per-frame path allocates nothing.
3236
+ *
3237
+ * @public
3238
+ */
3239
+ interface AnchorPlacement {
3240
+ /** Whether the element is shown at all. */
3241
+ visible: boolean;
3242
+ /** The x, in UI units from the overlay root's left edge. */
3243
+ x: number;
3244
+ /** The y, in UI units from the overlay root's top edge. */
3245
+ y: number;
3246
+ /** The uniform scale to draw the element at. */
3247
+ scale: number;
3248
+ }
3249
+ /**
3250
+ * Computes where an anchored element goes this frame.
3251
+ *
3252
+ * @param input - The projection, the flags, and the conversion.
3253
+ * @param out - Receives the placement.
3254
+ * @returns `out`, for chaining.
3255
+ *
3256
+ * @example
3257
+ * ```ts
3258
+ * const out = createAnchorPlacement();
3259
+ * computeAnchorPlacement(
3260
+ * {
3261
+ * screenX: 400,
3262
+ * screenY: 300,
3263
+ * inFront: true,
3264
+ * distance: 10,
3265
+ * viewWidth: 800,
3266
+ * viewHeight: 600,
3267
+ * mapping: { scaleX: 1, originX: 0, scaleY: 1, originY: 0 },
3268
+ * hideWhenBehindCamera: true,
3269
+ * clampToScreen: false,
3270
+ * scaleWithDistance: false,
3271
+ * referenceDistance: 10,
3272
+ * minScale: 0.5,
3273
+ * maxScale: 2,
3274
+ * },
3275
+ * out,
3276
+ * );
3277
+ * out.x; // 400
3278
+ * ```
3279
+ *
3280
+ * @public
3281
+ */
3282
+ export declare function computeAnchorPlacement(input: AnchorInput, out: AnchorPlacement): AnchorPlacement;
3283
+ //#endregion
3284
+ //#region src/world/ui-system.d.ts
3285
+ /**
3286
+ * The one system `@ignifx/ui` registers (`docs/architecture/01-lifecycle-and-time.md` §3,
3287
+ * `13-ui.md` §2: *"Updated in `PreRender` after camera sync, in batch, using
3288
+ * `Camera.worldToScreen`"*).
3289
+ *
3290
+ * ## Ordering
3291
+ *
3292
+ * `@ignifx/core`'s `RenderSyncSystem` runs at `PreRender` order **900**
3293
+ * (`packages/core/src/render/render-sync-system.ts` 63) and is what refreshes the render target's
3294
+ * size on every `Camera` and writes the frame's transforms onto the Lite cameras. Every projection
3295
+ * this system performs would be a frame stale, and would divide by last frame's viewport, if it ran
3296
+ * before that. {@link UI_SYNC_ORDER} is therefore **1100**: after core's sync, and inside the
3297
+ * `[1001, 9999]` band `RegisterSystemOptions` reserves for extensions
3298
+ * (`packages/core/src/app/types.ts` 649). Nothing else in the engine occupies it — physics
3299
+ * interpolation is at `-500`, 2D sync at `-450`, audio at `-400`.
3300
+ *
3301
+ * ## What it does
3302
+ *
3303
+ * One pass per component kind, in the order a frame needs them: create the text renderer if this is
3304
+ * the first frame, project every `WorldAnchor` and every `WorldText2D` once, then re-shape whatever
3305
+ * text changed. Projection uses the world's main camera; with no camera nothing is projected and
3306
+ * every anchored element is hidden, which is what a loading screen with no scene looks like.
3307
+ */
3308
+ /**
3309
+ * The `PreRender` order the UI system runs at.
3310
+ *
3311
+ * @remarks
3312
+ * After `RENDER_SYNC_ORDER` (900), which is the frame's camera synchronisation, and inside the
3313
+ * extension band. See the module's own remarks.
3314
+ *
3315
+ * @public
3316
+ */
3317
+ export declare const UI_SYNC_ORDER = 1100;
3318
+ /**
3319
+ * What the system is built with. Only `uiExtension` builds one, through `UiSystem`'s `@internal`
3320
+ * constructor.
3321
+ *
3322
+ * @internal
3323
+ */
3324
+ interface UiSystemOptions {
3325
+ /** The app, for the render surface's size and the Lite scene. */
3326
+ readonly app: App;
3327
+ /** The overlay host, for the layout the anchors are placed in. */
3328
+ readonly host: UiHost;
3329
+ /** The text renderer's life. */
3330
+ readonly runtime: TextRuntime;
3331
+ /** The localization service `i18nKey` is resolved through. */
3332
+ readonly i18n: I18nService;
3333
+ }
3334
+ /**
3335
+ * Projects world anchors and re-shapes text once per frame.
3336
+ *
3337
+ * @public
3338
+ */
3339
+ export declare class UiSystem implements System {
3340
+ #private;
3341
+ /** The name diagnostics and error reports use. */
3342
+ readonly name = "ignifx/ui-sync";
3343
+ /**
3344
+ * Builds the system. The extension does this; a game never constructs one.
3345
+ *
3346
+ * @param options - The app, the host, the text runtime, and the localization service.
3347
+ *
3348
+ * @internal
3349
+ */
3350
+ constructor(options: UiSystemOptions);
3351
+ /**
3352
+ * Builds the overlay, now that the engine and its canvas exist.
3353
+ *
3354
+ * @remarks
3355
+ * This is the only hook that fires inside `createApp` **after** the Lite engine was created:
3356
+ * `register` runs before it, and `onStart` runs only when a game calls `app.start()`, which a
3357
+ * headless tool never does. `@ignifx/2d` uses the same hook for the same reason.
3358
+ *
3359
+ * @param _world - The new world, which the overlay does not need.
3360
+ */
3361
+ onWorldCreated(_world: World): void;
3362
+ /**
3363
+ * Runs one frame's synchronisation.
3364
+ *
3365
+ * @param ctx - The world, clock, phase, and delta.
3366
+ */
3367
+ update(ctx: SystemContext): void;
3368
+ }
3369
+ //#endregion
3370
+ //#region src/world/world-anchor.d.ts
3371
+ /**
3372
+ * `WorldAnchor` (`docs/architecture/13-ui.md` §2): *"keeps a DOM element positioned at the entity's
3373
+ * screen position (name tags, health bars, markers)"*.
3374
+ *
3375
+ * ## The element is the game's, not the component's
3376
+ *
3377
+ * A game creates the element — with its framework, its CSS, its accessibility attributes — mounts
3378
+ * it in whichever `app.ui.layer` it belongs to, and assigns it to {@link WorldAnchor.element}. The
3379
+ * component writes exactly three properties on it and nothing else: `position: absolute`,
3380
+ * `left`/`top` at the origin, and a `transform` carrying the translate and the scale. That keeps a
3381
+ * React tree's own rendering untouched — the anchor only ever writes inline style — and it means
3382
+ * an anchor with no element is simply inert.
3383
+ *
3384
+ * ## Cost
3385
+ *
3386
+ * The transform string is the one per-frame allocation and it is unavoidable: the DOM takes CSS
3387
+ * text. Everything else is compared first, so an anchor whose entity did not move and whose camera
3388
+ * did not move writes nothing at all (coding standards §7).
3389
+ */
3390
+ /**
3391
+ * An entity-to-element anchor.
3392
+ *
3393
+ * @example
3394
+ * ```ts
3395
+ * const tag = document.createElement("div");
3396
+ * tag.textContent = "Boss";
3397
+ * app.ui.layer("hud").element?.append(tag);
3398
+ *
3399
+ * const anchor = enemy.addComponent(WorldAnchor);
3400
+ * anchor.element = tag;
3401
+ * anchor.offset = { x: 0, y: 2, z: 0 };
3402
+ * ```
3403
+ *
3404
+ * @public
3405
+ */
3406
+ export declare class WorldAnchor extends Component implements ComponentHooks {
3407
+ #private;
3408
+ /** The registration id the serializer writes into scene files. */
3409
+ static typeId: string;
3410
+ /** One anchored element per entity. */
3411
+ static allowMultiple: boolean;
3412
+ /** The declarative fields (ADR-0004). */
3413
+ static schema: Schema;
3414
+ /** A world-space offset added to the entity's position before projecting, in metres. */
3415
+ offset: Vec3Like;
3416
+ /** Whether the element is hidden when the anchor point is behind the camera. */
3417
+ hideWhenBehindCamera: boolean;
3418
+ /** Whether the element is kept inside the overlay's bounds instead of being hidden off-screen. */
3419
+ clampToScreen: boolean;
3420
+ /** Whether the element shrinks with distance. */
3421
+ scaleWithDistance: boolean;
3422
+ /** The distance at which {@link WorldAnchor.scaleWithDistance} produces a scale of `1`, in metres. */
3423
+ referenceDistance: number;
3424
+ /** The smallest scale distance scaling may produce. */
3425
+ minScale: number;
3426
+ /** The largest scale distance scaling may produce. */
3427
+ maxScale: number;
3428
+ /**
3429
+ * The element to position. Not serialised — a DOM node cannot be — so a scene file carries the
3430
+ * flags and the game assigns the element in `awake`.
3431
+ */
3432
+ element: HTMLElement | null;
3433
+ /** Builds an anchor with the schema's defaults. */
3434
+ constructor();
3435
+ /**
3436
+ * Where the element was placed on the last synchronised frame.
3437
+ *
3438
+ * @returns The placement; `visible` is `false` before the first sync.
3439
+ */
3440
+ get placement(): Readonly<AnchorPlacement>;
3441
+ /** Hides the element when the component goes away, so an orphaned tag does not linger. */
3442
+ onDetach(): void;
3443
+ /**
3444
+ * Places the element for this frame.
3445
+ *
3446
+ * @param screenX - The anchor point's projected x, in render-target pixels.
3447
+ * @param screenY - The anchor point's projected y, in render-target pixels.
3448
+ * @param inFront - Whether the point is in front of the camera.
3449
+ * @param distance - How far the point is from the camera, in metres.
3450
+ * @param viewWidth - The overlay root's width, in UI units.
3451
+ * @param viewHeight - The overlay root's height, in UI units.
3452
+ * @param mapping - The render-target-pixel to UI-unit conversion.
3453
+ *
3454
+ * @internal
3455
+ */
3456
+ place(screenX: number, screenY: number, inFront: boolean, distance: number, viewWidth: number, viewHeight: number, mapping: UiPixelMapping): void;
3457
+ }
3458
+ //#endregion
3459
+ export type { AnchorInput, AnchorPlacement, ArgumentNode, DialogButton, DialogOptions, HudAnchor, HudPlacement, HudPlacementInput, LiteFont, LiteTextData, LiteTextLayer, LiteTextRenderable, LiteTextRenderer, LoadingScreenOptions, LocaleDocument, MenuActionRow, MenuBindingRow, MenuButtonSource, MenuChoiceRow, MenuChoiceValues, MenuHeadingRow, MenuLabel, MenuNavigation, MenuOptions, MenuRow, MenuRowBase, MenuSeparatorRow, MenuSliderRow, MenuStackOptions, MenuText, MenuToggleRow, MenuVectorSource, MessageNode, MessageParams, MessagePattern, PluralNode, PluralSelector, TextAlignment, TextMetrics, TextNode, ToastOptions, UiDomTarget, UiErrorOptions, UiLayerOptions, UiLayout, UiOptions, UiPixelMapping, UiScalingMode, UiSettings, UiSurfaceMetrics, VirtualButtonOptions, VirtualDeviceLike, VirtualJoystickOptions };
3460
+ //# sourceMappingURL=index.d.ts.map