@ignifx/core 0.0.0 → 0.2.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
@@ -91,9 +91,14 @@ type ErrorCode = `IGX-${number}`;
91
91
  *
92
92
  * @remarks
93
93
  * Code blocks reserved for other first-party packages, which cannot import this table
94
- * (`docs/architecture/00-overview.md` §2): `@ignifx/cli` owns `IGX-1401`–`IGX-1419`;
94
+ * (`docs/architecture/00-overview.md` §2): `@ignifx/cli` owns `IGX-1401`–`IGX-1419`; `@ignifx/electron`
95
+ * owns `IGX-1460`–`IGX-1499` (core's own platform codes therefore stop at `IGX-1459`); `@ignifx/devtools`
96
+ * owns `IGX-1550`–`IGX-1599` (core's own devtools-range codes stop at `IGX-1549`);
95
97
  * `@ignifx/vite-plugin` owns `IGX-0550`–`IGX-0599` and `IGX-0650`–`IGX-0699`. Core allocates its
96
- * own codes from the bottom of each range and, in the platform range, from `IGX-1420` upward.
98
+ * own codes from the bottom of each range and, in the platform range, from `IGX-1420` upward —
99
+ * which is where `app.platform` and `app.storage` live, because storage is a *platform* service:
100
+ * the same three calls resolve to IndexedDB, a directory, or the Electron bridge depending only on
101
+ * the host, so a failure is a platform failure and not a serialization or asset one.
97
102
  *
98
103
  * @public
99
104
  */
@@ -114,6 +119,10 @@ export declare const CoreErrorCode: {
114
119
  readonly appNotReady: "IGX-0107";
115
120
  /** A `Time` property was set to a value outside its documented domain. */
116
121
  readonly invalidTimeValue: "IGX-0108";
122
+ /** A `app.tweens.to(...)` option was outside its documented domain. */
123
+ readonly invalidTweenOptions: "IGX-0109";
124
+ /** A tweened field is not a number, `Vec2`, `Vec3`, or `Quat`, or is not writable. */
125
+ readonly tweenFieldNotTweenable: "IGX-0110";
117
126
  /** A component declared through `requires` is missing from the entity. */
118
127
  readonly requiredComponentMissing: "IGX-0201";
119
128
  /** A second instance of a component type that does not allow multiples was added. */
@@ -126,6 +135,10 @@ export declare const CoreErrorCode: {
126
135
  readonly transformIsNotRemovable: "IGX-0205";
127
136
  /** A component's engine-assigned state was read before the engine attached it to an entity. */
128
137
  readonly componentNotAttached: "IGX-0206";
138
+ /** A hot-reloaded class kept the `"patch"` policy while its schema shape changed. */
139
+ readonly hotReloadSchemaChanged: "IGX-0207";
140
+ /** `app.hotReload.apply()` was called from inside a lifecycle callback. */
141
+ readonly hotReloadInsideCallback: "IGX-0208";
129
142
  /** A scene was instantiated before it had finished loading. */
130
143
  readonly sceneNotLoaded: "IGX-0301";
131
144
  /** Instantiating a scene would place an instance inside itself. */
@@ -214,8 +227,22 @@ export declare const CoreErrorCode: {
214
227
  readonly invalidAssetFile: "IGX-0709";
215
228
  /** A `PostProcessStack` was attached without the `postProcessing` rendering feature. */
216
229
  readonly postProcessingFeatureOff: "IGX-0710";
230
+ /** An `Environment.skybox` asks for a background the environment it installed cannot draw. */
231
+ readonly skyboxFixedAtLoad: "IGX-0711";
217
232
  /** The host exposes no Web Crypto implementation. */
218
233
  readonly cryptoUnavailable: "IGX-1420";
234
+ /** A storage namespace name is not a legal namespace segment. */
235
+ readonly storageInvalidNamespace: "IGX-1421";
236
+ /** A storage key is empty, too long, or contains a control character. */
237
+ readonly storageInvalidKey: "IGX-1422";
238
+ /** A value handed to `app.storage.set` has no JSON form. */
239
+ readonly storageValueNotSerializable: "IGX-1423";
240
+ /** The storage backend refused a write because the host is out of quota or disk space. */
241
+ readonly storageQuotaExceeded: "IGX-1424";
242
+ /** The storage backend failed for a reason the engine cannot classify. */
243
+ readonly storageBackendFailed: "IGX-1425";
244
+ /** A stored value could not be read back; the store was damaged or written by something else. */
245
+ readonly storageValueCorrupt: "IGX-1426";
219
246
  /** An error code was registered twice. */
220
247
  readonly duplicateErrorCode: "IGX-1501";
221
248
  /** An error code does not match `IGX-####` in a known range. */
@@ -226,6 +253,8 @@ export declare const CoreErrorCode: {
226
253
  readonly unknownDiagnosticsCounter: "IGX-1504";
227
254
  /** A `switch` over a union reached a case the type system said was impossible. */
228
255
  readonly unreachableCase: "IGX-1505";
256
+ /** `app.hotReload.reloadScene()` was given an instance that was not built from a scene asset. */
257
+ readonly sceneNotReloadable: "IGX-1506";
229
258
  };
230
259
  /**
231
260
  * The union of the codes `@ignifx/core` owns. Use it to narrow `catch` blocks to core failures.
@@ -1035,7 +1064,9 @@ interface RegisterAssetOptions {
1035
1064
  /**
1036
1065
  * The `fetch` implementation the service performs every read through
1037
1066
  * (`docs/architecture/05-assets-and-loading.md` §8). Injecting it is how headless tests supply
1038
- * deterministic responses and how a Node app maps addresses onto `fs` (Phase 9).
1067
+ * deterministic responses and how a Node app maps addresses onto `fs`. A packaged Electron build
1068
+ * needs no injection: `@ignifx/electron` serves `dist/` over `ignifx://`, which the renderer's own
1069
+ * `fetch` reaches.
1039
1070
  *
1040
1071
  * @public
1041
1072
  */
@@ -1083,6 +1114,14 @@ interface Assets {
1083
1114
  * @returns The handle, once it has loaded.
1084
1115
  */
1085
1116
  loadAsync<T>(ref: AssetRef<T> | string, options?: LoadOptions): Promise<AssetHandle<T>>;
1117
+ /**
1118
+ * Reloads a loaded asset from its source, delivering the new value through `onReplaced` the way a
1119
+ * development hot reload does (`docs/architecture/05-assets-and-loading.md` §7); a handle that is
1120
+ * not loaded is left alone. The Vite plugin's HMR channel and the devtools Assets panel call it.
1121
+ *
1122
+ * @param address - The asset's address.
1123
+ */
1124
+ reload(address: string): void;
1086
1125
  /**
1087
1126
  * Requests several assets as one batch.
1088
1127
  *
@@ -1189,7 +1228,7 @@ interface AssetLoadErrorOptions extends IgnifxErrorOptions {
1189
1228
  * await app.assets.loadAsync("levels/1.scene.json");
1190
1229
  * } catch (error) {
1191
1230
  * if (error instanceof AssetLoadError) {
1192
- * app.log.error("{address} failed from {url}", error.address, error.url);
1231
+ * app.log.error(`${error.address} failed from ${error.url}`, error);
1193
1232
  * }
1194
1233
  * }
1195
1234
  * ```
@@ -1452,8 +1491,12 @@ interface ComponentTypeToken<C> {
1452
1491
  interface AssetTypeToken<A> {
1453
1492
  /** The asset type name written into files when the extension is ambiguous. */
1454
1493
  readonly assetType?: string;
1455
- /** The instance shape the token names. */
1456
- readonly prototype: A;
1494
+ /**
1495
+ * The instance shape the token names. A class token carries it for free; a plain token for an
1496
+ * asset that has no class (a scene, a prefab) leaves it out and fixes `A` through its annotation —
1497
+ * see `SceneAssetToken`. Nothing reads it at runtime.
1498
+ */
1499
+ readonly prototype?: A;
1457
1500
  }
1458
1501
  /**
1459
1502
  * The plain, serializable form of an asset reference: what `{ "$asset": … }` decodes to before the
@@ -1822,6 +1865,18 @@ interface ComponentClassInfo {
1822
1865
  /** A dense index assigned in registration order, for array-indexed per-class bookkeeping. */
1823
1866
  readonly classIndex: number;
1824
1867
  }
1868
+ /**
1869
+ * What {@link ComponentRegistry.replace} swapped, for the hot-reload path that has to re-file every
1870
+ * live instance of the class that went away.
1871
+ *
1872
+ * @public
1873
+ */
1874
+ interface ComponentReplacement {
1875
+ /** The class registered under the id before, or `null` when nothing was. */
1876
+ readonly previous: ComponentType | null;
1877
+ /** The replacement's freshly built info. */
1878
+ readonly info: ComponentClassInfo;
1879
+ }
1825
1880
  /**
1826
1881
  * The component-class table of one app. There is one per {@link App}, never a module-level one
1827
1882
  * (`CONSTITUTION.md` §3.5, §3.6): two apps in one test process must not see each other's types.
@@ -1859,6 +1914,26 @@ export declare class ComponentRegistry {
1859
1914
  * @param types - The component classes.
1860
1915
  */
1861
1916
  registerAll(types: readonly ConcreteComponentType[]): void;
1917
+ /**
1918
+ * Swaps the class registered under a `typeId` for a replacement, for script hot reload
1919
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). The previous class's cached info is
1920
+ * dropped and the replacement inherits its `classIndex`, so per-class bookkeeping indexed by that
1921
+ * number stays valid across a reload.
1922
+ *
1923
+ * @remarks
1924
+ * Additive and hot-reload-only: nothing on the normal path replaces a registration, and
1925
+ * `register` still refuses to bind one id to two classes (`IGX-0203`).
1926
+ *
1927
+ * @param type - The replacement class. It must declare the `typeId` it replaces.
1928
+ * @returns The freshly built info for the replacement, and the class it replaced.
1929
+ * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
1930
+ *
1931
+ * @example
1932
+ * ```ts
1933
+ * const { previous } = registry.replace(NextMover);
1934
+ * ```
1935
+ */
1936
+ replace(type: ConcreteComponentType): ComponentReplacement;
1862
1937
  /**
1863
1938
  * Describes a class, computing and caching its info on first sight. Explicit registration is only
1864
1939
  * needed for *serializable* components; a script added from code is described the first time it
@@ -2423,24 +2498,24 @@ export declare class Quat {
2423
2498
  /**
2424
2499
  * Builds a rotation from Euler angles in radians, in intrinsic XYZ order.
2425
2500
  *
2426
- * @param xRadians - Rotation about X, in radians.
2427
- * @param yRadians - Rotation about Y, in radians.
2428
- * @param zRadians - Rotation about Z, in radians.
2501
+ * @param xRad - Rotation about X, in radians.
2502
+ * @param yRad - Rotation about Y, in radians.
2503
+ * @param zRad - Rotation about Z, in radians.
2429
2504
  * @returns A new quaternion. **Allocates.**
2430
2505
  */
2431
- static fromEulerRadians(xRadians: number, yRadians: number, zRadians: number): Quat;
2506
+ static fromEulerRad(xRad: number, yRad: number, zRad: number): Quat;
2432
2507
  /**
2433
2508
  * Writes a rotation built from Euler radians into `out`. This is Babylon Lite's `eulerToQuat`
2434
2509
  * (`lib/math/quat-euler.js`) element for element, so a rotation built here means the same thing
2435
2510
  * to Lite's node hierarchy.
2436
2511
  *
2437
- * @param xRadians - Rotation about X, in radians.
2438
- * @param yRadians - Rotation about Y, in radians.
2439
- * @param zRadians - Rotation about Z, in radians.
2512
+ * @param xRad - Rotation about X, in radians.
2513
+ * @param yRad - Rotation about Y, in radians.
2514
+ * @param zRad - Rotation about Z, in radians.
2440
2515
  * @param out - The quaternion to write.
2441
2516
  * @returns `out`.
2442
2517
  */
2443
- static fromEulerRadiansToRef<TOut extends MutableQuat>(xRadians: number, yRadians: number, zRadians: number, out: TOut): TOut;
2518
+ static fromEulerRadToRef<TOut extends MutableQuat>(xRad: number, yRad: number, zRad: number, out: TOut): TOut;
2444
2519
  /**
2445
2520
  * Writes a rotation's Euler angles in degrees into `out`, in intrinsic XYZ order — the inverse of
2446
2521
  * {@link Quat.fromEulerDegreesToRef}.
@@ -2460,7 +2535,7 @@ export declare class Quat {
2460
2535
  * @param out - The vector to write, in radians.
2461
2536
  * @returns `out`.
2462
2537
  */
2463
- static toEulerRadiansToRef<TOut extends MutableVec3>(q: QuatLike, out: TOut): TOut;
2538
+ static toEulerRadToRef<TOut extends MutableVec3>(q: QuatLike, out: TOut): TOut;
2464
2539
  /**
2465
2540
  * Builds a rotation of `degrees` about an axis.
2466
2541
  *
@@ -4187,6 +4262,27 @@ interface SceneAsset {
4187
4262
  /** The content hash of {@link SceneAsset.file}, as `sha256:<hex>`. */
4188
4263
  readonly hash: string;
4189
4264
  }
4265
+ /**
4266
+ * The `asset()` token for a scene or prefab field. `SceneAsset` is an interface, so it cannot be
4267
+ * passed to `asset()` the way a class such as `MeshAsset` can; this token names the type instead:
4268
+ *
4269
+ * ```ts
4270
+ * class Spawner extends Script.define({ prefab: asset(SceneAssetToken) }) {
4271
+ * static typeId = "game/Spawner";
4272
+ * spawn(): void {
4273
+ * const value = this.prefab?.value;
4274
+ * if (value !== undefined) {
4275
+ * this.app.world.instantiate(value, { position: this.transform.position });
4276
+ * }
4277
+ * }
4278
+ * }
4279
+ * ```
4280
+ *
4281
+ * In a scene file the field is written as `{ "$asset": "props/crate.prefab.json" }`.
4282
+ *
4283
+ * @public
4284
+ */
4285
+ export declare const SceneAssetToken: AssetTypeToken<SceneAsset>;
4190
4286
  /**
4191
4287
  * The content hash of a scene file: SHA-256 over the canonical JSON text, so two saves of the same
4192
4288
  * state hash the same and an edited prefab does not
@@ -4931,6 +5027,17 @@ interface WorldInternals {
4931
5027
  * @returns `true` when at least one of the entity's scripts implements it.
4932
5028
  */
4933
5029
  entityImplements(entity: Entity, kind: ScriptCallbackKind): boolean;
5030
+ /**
5031
+ * Re-files an effectively-enabled script in the sorted dispatch lists after script hot reload
5032
+ * swapped its class (`docs/architecture/15-devtools-and-diagnostics.md` §5). No callback runs: the
5033
+ * script leaves the lists its previous class was filed in and joins the ones its new class
5034
+ * implements, at its new `executionOrder`.
5035
+ *
5036
+ * @param component - The component whose class was replaced. A plain component is ignored.
5037
+ * @param previous - The class info the component was filed under.
5038
+ * @param next - The class info it is filed under now, already written to its engine state.
5039
+ */
5040
+ rebindDispatch(component: Component, previous: ScriptClassInfo | null, next: ScriptClassInfo | null): void;
4934
5041
  /**
4935
5042
  * Tells the world which phase is running, so a failure reported through `app.onError` names it.
4936
5043
  * The scheduler sets it on entering a phase and clears it on leaving.
@@ -5327,15 +5434,6 @@ export declare class LayerTable {
5327
5434
  * @public
5328
5435
  */
5329
5436
  export declare function createLayerTable(names?: readonly string[]): LayerTable;
5330
- /**
5331
- * Checks that a number is a usable layer slot.
5332
- *
5333
- * @param layer - The candidate slot.
5334
- * @returns `true` when the value is an integer in `[0, 31]`.
5335
- *
5336
- * @internal
5337
- */
5338
- export declare function isValidLayer(layer: number): boolean;
5339
5437
  //#endregion
5340
5438
  //#region src/lifecycle/frame-state.d.ts
5341
5439
  /**
@@ -5585,15 +5683,16 @@ type LitePbrMaterial = PbrMaterialProps;
5585
5683
  */
5586
5684
  type LiteStandardMaterial = StandardMaterialProps;
5587
5685
  /**
5588
- * How a material's alpha channel is interpreted, in glTF's vocabulary.
5686
+ * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector
5687
+ * lists them (`docs/architecture/07-rendering.md` §2.4).
5589
5688
  *
5590
- * @internal
5689
+ * @public
5591
5690
  */
5592
5691
  export declare const MATERIAL_ALPHA_MODES: readonly ["opaque", "mask", "blend"];
5593
5692
  /**
5594
5693
  * The union of the alpha modes a material can declare.
5595
5694
  *
5596
- * @internal
5695
+ * @public
5597
5696
  */
5598
5697
  type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
5599
5698
  //#endregion
@@ -5612,14 +5711,15 @@ type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
5612
5711
  * renderer". This module is that boundary: `baseColor`, `emissive`, `diffuse`, and `specular` are
5613
5712
  * decoded here and handed to the adapter linear. Factors that are not colours — `metallic`,
5614
5713
  * `roughness`, `alpha` — are unitless and pass through.
5615
- * - **`"type": "shader"` is Phase 7.** §2.6 lists it, and Lite's `createShaderMaterial` exists, but
5616
- * its declaration takes a WGSL attribute/uniform/sampler layout whose shape is Lite's own
5617
- * (`ShaderMaterialOptions`, `index.d.ts`); publishing that verbatim would put a Lite type in the
5618
- * public API, which `CONSTITUTION.md` §3.4 forbids, and mirroring it is a design job of its own.
5619
- * A file that declares it is rejected with `IGX-0708` naming the phase.
5620
- * - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are Phase 7** for the same reason:
5621
- * each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader code is
5622
- * tree-shaken. The loader reports an unknown top-level key rather than silently dropping it.
5714
+ * - **`"type": "shader"` is not implemented.** §2.6 lists it, and Lite's `createShaderMaterial`
5715
+ * exists, but its declaration takes a WGSL attribute/uniform/sampler layout whose shape is Lite's
5716
+ * own (`ShaderMaterialOptions`, `index.d.ts`); publishing that verbatim would put a Lite type in
5717
+ * the public API, which `CONSTITUTION.md` §3.4 forbids, and mirroring it is a design job of its
5718
+ * own that no delivered phase took on. A file that declares it is rejected with `IGX-0708`.
5719
+ * - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are not implemented** for the same
5720
+ * reason: each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
5721
+ * code is tree-shaken. The loader reports an unknown top-level key rather than silently dropping
5722
+ * it.
5623
5723
  *
5624
5724
  * ## Headless
5625
5725
  *
@@ -5664,18 +5764,6 @@ export declare const MATERIAL_KINDS: readonly ["pbr", "standard", "shader"];
5664
5764
  * @public
5665
5765
  */
5666
5766
  type MaterialKind = (typeof MATERIAL_KINDS)[number];
5667
- /**
5668
- * How a material interprets its alpha channel, in glTF's vocabulary.
5669
- *
5670
- * @public
5671
- */
5672
- type MaterialAlphaModeName = MaterialAlphaMode;
5673
- /**
5674
- * The alpha modes a material may declare, in the order the inspector lists them.
5675
- *
5676
- * @public
5677
- */
5678
- export declare const MATERIAL_ALPHA_MODE_NAMES: readonly MaterialAlphaModeName[];
5679
5767
  /**
5680
5768
  * The properties a `"pbr"` material declares. Every colour is sRGB; every factor is unitless.
5681
5769
  *
@@ -5699,7 +5787,7 @@ interface PbrMaterialDefinition {
5699
5787
  /** How strongly ambient occlusion darkens the surface, 0 to 1. */
5700
5788
  readonly occlusionStrength: number;
5701
5789
  /** How the alpha channel is interpreted. */
5702
- readonly alphaMode: MaterialAlphaModeName;
5790
+ readonly alphaMode: MaterialAlphaMode;
5703
5791
  /** The cutoff below which a `"mask"` material discards a fragment. */
5704
5792
  readonly alphaCutoff: number;
5705
5793
  /** Overall material alpha, 0 to 1. */
@@ -6364,15 +6452,18 @@ interface Renderer {
6364
6452
  */
6365
6453
  warmUp(materials: readonly MaterialAsset[]): void;
6366
6454
  /**
6367
- * Picks the object under one CSS pixel of the canvas, exactly, on the GPU
6455
+ * Picks the object under one pixel of the canvas, exactly, on the GPU
6368
6456
  * (`docs/architecture/07-rendering.md` §3).
6369
6457
  *
6370
6458
  * @remarks
6371
- * Picks are serialised per app: Lite's picker owns one set of staging buffers and chains each
6372
- * call onto the previous one's promise. A headless app has no picker and always misses.
6373
- *
6374
- * @param x - The CSS pixel x, from the canvas's left edge.
6375
- * @param y - The CSS pixel y, from the canvas's top edge.
6459
+ * Coordinates are **backing-store pixels** — the canvas's `width`/`height`, the space
6460
+ * `Camera.worldToScreen` answers in — not CSS pixels; multiply a DOM event's `offsetX`/`offsetY`
6461
+ * by `devicePixelRatio` first. Picks are serialised per app: Lite's picker owns one set of staging
6462
+ * buffers and chains each call onto the previous one's promise. A headless app has no picker and
6463
+ * always misses.
6464
+ *
6465
+ * @param x - The backing-store pixel x, from the canvas's left edge.
6466
+ * @param y - The backing-store pixel y, from the canvas's top edge.
6376
6467
  * @param options - An entity filter.
6377
6468
  * @returns What was hit, or `null` for a miss.
6378
6469
  */
@@ -6400,6 +6491,25 @@ interface Renderer {
6400
6491
  * which point Lite has compiled what it is going to compile.
6401
6492
  */
6402
6493
  requireFeature(feature: RenderingFeature): void;
6494
+ /**
6495
+ * Registers a probe that answers whether a rendering context **other than the render scene** is
6496
+ * drawing a world through a camera of its own.
6497
+ *
6498
+ * @remarks
6499
+ * The one caller is an extension that owns a second rendering context on the same surface —
6500
+ * `@ignifx/2d`'s sprite renderer, which draws a `"sprite"`-mode frame through a `Camera2D` and
6501
+ * needs no 3D `Camera` at all. `IGX-0706` says "this world has no enabled camera, so nothing is
6502
+ * drawn"; on such a world the second half is false, so the probe suppresses it
6503
+ * (`docs/architecture/07-rendering.md` §2.1, `11-2d-toolkit.md` §1). The probe is asked only in
6504
+ * the frames where no 3D camera was selected, and it is never cached: a scene that loses its
6505
+ * `Camera2D` starts warning again.
6506
+ *
6507
+ * @param probe - Answers `true` while the caller has an active camera for the world it is handed.
6508
+ * @returns A function that removes the probe.
6509
+ *
6510
+ * @internal
6511
+ */
6512
+ addCameraSource(probe: (world: World) => boolean): Disconnect;
6403
6513
  }
6404
6514
  /**
6405
6515
  * The rendering service of one app, and the render layer's per-app state.
@@ -6457,6 +6567,17 @@ declare class RendererImpl implements Renderer {
6457
6567
  * @returns The surface, or `null` under the null engine.
6458
6568
  */
6459
6569
  get surface(): RenderSurface | null;
6570
+ /**
6571
+ * Destroys the GPU device the way a real loss would, so that recovery runs — for tests and probes.
6572
+ *
6573
+ * @remarks
6574
+ * Reached through `rendererInternals(app.renderer)`; a game never calls it. It throws when no
6575
+ * recovery strategy is enabled (`rendering.features.deviceLostRecovery` is off) or under the null
6576
+ * engine, which has no device to lose.
6577
+ *
6578
+ * @internal
6579
+ */
6580
+ forceDeviceLossForTesting(): void;
6460
6581
  /**
6461
6582
  * The offscreen render path, when the project declared `rendering.features.postProcessing`.
6462
6583
  *
@@ -6540,8 +6661,8 @@ declare class RendererImpl implements Renderer {
6540
6661
  * What the ADR actually measured makes the deadlock unnecessary. Lite stamps **every** PBR
6541
6662
  * material in the process with one `_buildGroup` singleton, and every Standard material with
6542
6663
  * another, so the unit that has to exist at `registerScene` is the *family*, not the asset: "there
6543
- * are four families to worry about, not one per asset". This warms the two families a Phase 2
6544
- * app can produce, plus any material already in the cache, which reaches the ADR's outcome — a
6664
+ * are four families to worry about, not one per asset". This warms the two families core can
6665
+ * produce, plus any material already in the cache, which reaches the ADR's outcome — a
6545
6666
  * mesh added later takes the synchronous rebuild path — with two degenerate triangles and no
6546
6667
  * ordering problem.
6547
6668
  *
@@ -6555,10 +6676,10 @@ declare class RendererImpl implements Renderer {
6555
6676
  */
6556
6677
  warmUp(materials: readonly MaterialAsset[]): void;
6557
6678
  /**
6558
- * Picks the object under one CSS pixel of the canvas.
6679
+ * Picks the object under one backing-store pixel of the canvas (see the interface's remarks).
6559
6680
  *
6560
- * @param x - The CSS pixel x, from the canvas's left edge.
6561
- * @param y - The CSS pixel y, from the canvas's top edge.
6681
+ * @param x - The backing-store pixel x, from the canvas's left edge.
6682
+ * @param y - The backing-store pixel y, from the canvas's top edge.
6562
6683
  * @param options - An entity filter.
6563
6684
  * @returns What was hit, or `null` for a miss.
6564
6685
  */
@@ -6583,6 +6704,27 @@ declare class RendererImpl implements Renderer {
6583
6704
  * @throws IgnifxError with code `IGX-0704` after the render scene has been registered.
6584
6705
  */
6585
6706
  requireFeature(feature: RenderingFeature): void;
6707
+ /**
6708
+ * Registers a probe that answers whether another rendering context has a camera of its own.
6709
+ *
6710
+ * @param probe - Answers `true` while the caller has an active camera for the world.
6711
+ * @returns A function that removes the probe.
6712
+ */
6713
+ addCameraSource(probe: (world: World) => boolean): Disconnect;
6714
+ /**
6715
+ * Whether any registered probe claims a camera for this world.
6716
+ *
6717
+ * @remarks
6718
+ * Asked by the render sync system only in a frame where no enabled `Camera` was found, which is
6719
+ * what keeps `IGX-0706` off a correct 2D-only scene without costing a well-formed 3D scene
6720
+ * anything (`docs/architecture/07-rendering.md` §2.1).
6721
+ *
6722
+ * @param world - The world being reconciled.
6723
+ * @returns `true` when something other than the render scene draws it.
6724
+ *
6725
+ * @internal
6726
+ */
6727
+ hasExternalCamera(world: World): boolean;
6586
6728
  /**
6587
6729
  * The material a `MeshRenderer` draws with when it declares none
6588
6730
  * (`docs/architecture/07-rendering.md` §2.3): a neutral, fully rough dielectric.
@@ -6724,6 +6866,19 @@ declare class RendererImpl implements Renderer {
6724
6866
  */
6725
6867
  dispose(): void;
6726
6868
  }
6869
+ /**
6870
+ * Destroys a renderer's GPU device the way a real loss would, so that recovery runs — for tests and
6871
+ * probes that live outside `@ignifx/core` and may not import Babylon Lite (`CONSTITUTION.md` §3.4).
6872
+ *
6873
+ * @remarks
6874
+ * It throws when `rendering.features.deviceLostRecovery` is off, or under the null engine, which
6875
+ * has no device to lose.
6876
+ *
6877
+ * @param renderer - The app's renderer.
6878
+ *
6879
+ * @internal
6880
+ */
6881
+ export declare function forceRendererDeviceLossForTesting(renderer: Renderer): void;
6727
6882
  //#endregion
6728
6883
  //#region src/lite/camera.d.ts
6729
6884
  /**
@@ -7334,8 +7489,13 @@ export declare class Camera extends Component implements ComponentHooks {
7334
7489
  /**
7335
7490
  * Builds a world-space ray through a point on the canvas.
7336
7491
  *
7337
- * @param x - The CSS pixel x, from the canvas's left edge.
7338
- * @param y - The CSS pixel y, from the canvas's top edge.
7492
+ * @remarks
7493
+ * Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
7494
+ * {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
7495
+ * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
7496
+ *
7497
+ * @param x - The backing-store pixel x, from the canvas's left edge.
7498
+ * @param y - The backing-store pixel y, from the canvas's top edge.
7339
7499
  * @param out - The ray to fill; a fresh one is allocated when omitted.
7340
7500
  * @returns `out`, or `null` when the view-projection matrix is singular — a zero-sized viewport,
7341
7501
  * or a camera that is not attached.
@@ -7361,8 +7521,8 @@ export declare class Camera extends Component implements ComponentHooks {
7361
7521
  /**
7362
7522
  * The world-space point a canvas pixel maps to at a given distance along the view ray.
7363
7523
  *
7364
- * @param x - The CSS pixel x, from the canvas's left edge.
7365
- * @param y - The CSS pixel y, from the canvas's top edge.
7524
+ * @param x - The backing-store pixel x, from the canvas's left edge (see {@link Camera.screenToRay}).
7525
+ * @param y - The backing-store pixel y, from the canvas's top edge.
7366
7526
  * @param distance - How far along the ray to travel, in metres.
7367
7527
  * @param out - Receives the point.
7368
7528
  * @returns `out`, or `null` when no ray could be built.
@@ -7410,10 +7570,10 @@ export declare class Camera extends Component implements ComponentHooks {
7410
7570
  * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
7411
7571
  *
7412
7572
  * @remarks
7413
- * Phase 1 ships the subset that needs no asset system: entity creation, queries, the implicit
7414
- * `"default"` scene, and the lifecycle. `loadScene`, `unloadScene`, `instantiate`,
7415
- * `instantiateAsync`, and `moveEntityToScene` arrive in Phase 2, and `onSceneLoaded`/
7416
- * `onSceneUnloaded` exist here but never fire until then.
7573
+ * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
7574
+ * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
7575
+ * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
7576
+ * raise.
7417
7577
  *
7418
7578
  * @example
7419
7579
  * ```ts
@@ -7524,13 +7684,13 @@ export declare class World implements WorldHost {
7524
7684
  */
7525
7685
  get onEntityDestroyed(): Signal<Entity>;
7526
7686
  /**
7527
- * Emitted when a scene instance finishes loading. Never fires before Phase 2.
7687
+ * Emitted when a scene instance finishes loading.
7528
7688
  *
7529
7689
  * @returns The signal.
7530
7690
  */
7531
7691
  get onSceneLoaded(): Signal<SceneInstance>;
7532
7692
  /**
7533
- * Emitted when a scene instance is unloaded. Never fires before Phase 2.
7693
+ * Emitted when a scene instance is unloaded.
7534
7694
  *
7535
7695
  * @returns The signal.
7536
7696
  */
@@ -9125,8 +9285,16 @@ interface FrameSample {
9125
9285
  /** How many entities and components were destroyed in this frame's flush. */
9126
9286
  destroyed: number;
9127
9287
  /**
9128
- * CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long and
9129
- * only filled in development builds.
9288
+ * CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long, and
9289
+ * filled only while the app is in development mode — every entry is `0` otherwise.
9290
+ *
9291
+ * @remarks
9292
+ * "Development mode" is `createApp({ mode })`, and nothing else. It is **not** the bundler's mode:
9293
+ * `mode` defaults to `"development"` and no ignifx tooling overrides it, so a `vite build` of a
9294
+ * game that never passes `mode` still records these timings. A project that wants them gone from
9295
+ * its shipped build passes `mode: "production"` itself — for example
9296
+ * `createApp({ mode: import.meta.env.PROD ? "production" : "development" })` — and a probe that
9297
+ * reads `cpuMs` then reports zeros.
9130
9298
  */
9131
9299
  readonly cpuMs: Float64Array;
9132
9300
  }
@@ -9192,8 +9360,10 @@ interface ProfileScope {
9192
9360
  */
9193
9361
  interface DiagnosticsOptions {
9194
9362
  /**
9195
- * Whether this is a development build. Per-phase CPU timings and `performance.mark`/`measure`
9196
- * entries are only produced when it is `true`. Defaults to `false`.
9363
+ * Whether the app runs in development mode. Per-phase CPU timings and
9364
+ * `performance.mark`/`measure` entries are only produced when it is `true`. Defaults to `false`
9365
+ * here; `createApp` passes `mode === "development"`, and that `mode` itself defaults to
9366
+ * `"development"` in every build — a bundler's production flag does not change it.
9197
9367
  */
9198
9368
  readonly development?: boolean;
9199
9369
  /**
@@ -9231,7 +9401,11 @@ export declare class Diagnostics {
9231
9401
  * them. Values are reset by {@link Diagnostics.beginFrame}.
9232
9402
  */
9233
9403
  readonly frame: FrameSample;
9234
- /** Whether per-phase timings and User Timing entries are being recorded. */
9404
+ /**
9405
+ * Whether per-phase timings and User Timing entries are being recorded — that is, whether the app
9406
+ * was created with `mode: "development"`, which is the default in every build. Read it before
9407
+ * trusting `FrameSample.cpuMs`.
9408
+ */
9235
9409
  readonly isDevelopment: boolean;
9236
9410
  /** How many frames the history can hold. */
9237
9411
  readonly historyCapacity: number;
@@ -9282,6 +9456,11 @@ export declare class Diagnostics {
9282
9456
  /**
9283
9457
  * Registers a subsystem's counter group.
9284
9458
  *
9459
+ * @remarks
9460
+ * A second registration of the same name is a mistake, not a merge, so it throws. A script that
9461
+ * cannot know whether it is the first instance to run — a gameplay counter shared by every enemy,
9462
+ * a group that survives a scene reload — asks for {@link Diagnostics.groupOrRegister} instead.
9463
+ *
9285
9464
  * @param name - The group name, unique within this app.
9286
9465
  * @param counterNames - The counter names, in the order their indices are assigned.
9287
9466
  * @returns The group, whose indices are resolved once with {@link DiagnosticsGroup.index}.
@@ -9296,6 +9475,33 @@ export declare class Diagnostics {
9296
9475
  * absence, not a failure (coding standards §5.5).
9297
9476
  */
9298
9477
  group(name: string): DiagnosticsGroup | null;
9478
+ /**
9479
+ * Looks a counter group up by name and registers it if no subsystem has yet — the idiom for code
9480
+ * that may run more than once (`docs/architecture/15-devtools-and-diagnostics.md` §3).
9481
+ *
9482
+ * @remarks
9483
+ * `registerGroup` throws `IGX-1503` on a duplicate name, which is right for an extension that
9484
+ * registers its group once at `register()` time and wrong for a script: a script's `awake` runs
9485
+ * once per instance, and a scene reload runs it again, so `group(name) ?? registerGroup(name, …)`
9486
+ * had to be written out by hand at every call site. This is that expression, with one difference
9487
+ * worth knowing: when the group already exists it is returned **as it was registered**, and
9488
+ * `counterNames` is ignored rather than merged — Lite-style counter arrays are indexed, and
9489
+ * growing one under a subsystem that already holds indices into it would silently renumber its
9490
+ * counters. A caller that then asks for a counter the first registration did not declare gets
9491
+ * `IGX-1504` from {@link DiagnosticsGroup.index}, which names the group and the counter.
9492
+ *
9493
+ * @param name - The group name.
9494
+ * @param counterNames - The counter names to register with, used only on the first call.
9495
+ * @returns The existing group, or the newly registered one.
9496
+ *
9497
+ * @example
9498
+ * ```ts
9499
+ * // In a Script's `awake`, which runs once per instance and again after a scene reload.
9500
+ * const counters = this.app.diagnostics.groupOrRegister("game", ["enemiesAlive", "wavesCleared"]);
9501
+ * this.enemiesAlive = counters.index("enemiesAlive");
9502
+ * ```
9503
+ */
9504
+ groupOrRegister(name: string, counterNames: readonly string[]): DiagnosticsGroup;
9299
9505
  /**
9300
9506
  * Opens a timing scope. In development builds it writes a `performance.mark`/`measure` pair that
9301
9507
  * shows up in browser profilers; outside development it is free
@@ -9314,6 +9520,141 @@ export declare class Diagnostics {
9314
9520
  profile(name: string): ProfileScope;
9315
9521
  }
9316
9522
  //#endregion
9523
+ //#region src/hot-reload/contract.d.ts
9524
+ /**
9525
+ * What a class asks the engine to do with its live instances when its module is replaced
9526
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5).
9527
+ *
9528
+ * @remarks
9529
+ * `"patch"` is the default and the one to reach for while iterating on logic: the live instances
9530
+ * keep their identity and every field value, and no lifecycle callback re-runs. `"recreate"` is
9531
+ * required when the *field layout* changes, because a patched instance keeps whatever properties
9532
+ * its constructor assigned and a renamed or added field would read `undefined`.
9533
+ *
9534
+ * @public
9535
+ */
9536
+ type HotReloadPolicy = "patch" | "recreate";
9537
+ /**
9538
+ * What one {@link HotReloadReport} describes: a prototype swap, a destroy-and-rebuild of component
9539
+ * instances, or a scene instance rebuilt from its file.
9540
+ *
9541
+ * @public
9542
+ */
9543
+ type HotReloadKind = "patch" | "recreate" | "scene";
9544
+ /**
9545
+ * The statics a component or script class may declare to steer its own hot reload
9546
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). Structural and optional, for the reason
9547
+ * given on `ComponentStatics`: a member declared on the `Component` base class would force the
9548
+ * `override` keyword on every `static hotReload = "recreate"` under `noImplicitOverride`.
9549
+ *
9550
+ * @example
9551
+ * ```ts
9552
+ * class Inventory extends Script.define({ slots: u32(4) }) {
9553
+ * static typeId = "mygame/Inventory";
9554
+ * static hotReload = "recreate" as const;
9555
+ * }
9556
+ * ```
9557
+ *
9558
+ * @public
9559
+ */
9560
+ interface HotReloadStatics {
9561
+ /** The policy for this class; defaults to `"patch"`. */
9562
+ readonly hotReload?: HotReloadPolicy;
9563
+ /**
9564
+ * Runs once on the **new** class after every live instance of it has been swapped or re-created,
9565
+ * with the class that was registered before as `previous`. It is the seam for class-level
9566
+ * transient state — a cache keyed off the old class, a static counter — and it is deliberately
9567
+ * not per instance: under `"patch"` the instances are the very same objects, so there is
9568
+ * nothing to copy across (PlayCanvas's `swap(old)` exists only because it re-instantiates), and
9569
+ * under `"recreate"` per-instance state is re-derived from the schema by design.
9570
+ *
9571
+ * @param previous - The class this one replaces.
9572
+ */
9573
+ onHotReload?(previous: ConcreteComponentType): void;
9574
+ }
9575
+ /**
9576
+ * One replaced module's worth of component classes, as the HMR client hands them over. Classes the
9577
+ * app has never seen are registered; classes whose `typeId` is already registered to a different
9578
+ * class are reloaded under their policy; classes that are already the registered ones are skipped.
9579
+ *
9580
+ * @public
9581
+ */
9582
+ interface HotReloadModule {
9583
+ /** Every component or script class the replaced module exports. */
9584
+ readonly types: readonly ConcreteComponentType[];
9585
+ }
9586
+ /**
9587
+ * What one hot reload did, for logs, tests, and the devtools overlay.
9588
+ *
9589
+ * @public
9590
+ */
9591
+ interface HotReloadReport {
9592
+ /** Which of the three operations this report describes. */
9593
+ readonly kind: HotReloadKind;
9594
+ /** The `typeId`s actually reloaded, in the order they were applied; empty when nothing changed. */
9595
+ readonly typeIds: readonly string[];
9596
+ /** How many live component instances were swapped or re-created, or entities rebuilt for a scene. */
9597
+ readonly instances: number;
9598
+ /** How long the operation took, in milliseconds. */
9599
+ readonly durationMs: number;
9600
+ /** Everything that threw on the way; the reload continues past each one. */
9601
+ readonly errors: readonly unknown[];
9602
+ }
9603
+ /**
9604
+ * The app's hot-reload service, reached as `app.hotReload`
9605
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). It works with no Vite and no browser:
9606
+ * `@ignifx/vite-plugin` generates a client that calls {@link HotReloadHost.apply}, and a headless
9607
+ * test calls it directly.
9608
+ *
9609
+ * @example
9610
+ * ```ts
9611
+ * const report = app.hotReload.apply([{ types: [NextMover] }]);
9612
+ * console.log(report.kind, report.typeIds, report.instances);
9613
+ * ```
9614
+ *
9615
+ * @public
9616
+ */
9617
+ interface HotReloadHost {
9618
+ /**
9619
+ * Emitted once per completed {@link HotReloadHost.apply} or
9620
+ * {@link HotReloadHost.reloadScene} with the report that call returns.
9621
+ */
9622
+ readonly onApplied: SignalLike<HotReloadReport>;
9623
+ /**
9624
+ * Whether a changed scene file re-instantiates the live scene instances built from it, set with
9625
+ * `createApp({ hotReload: { reloadScenes: true } })`. Off by default, because rebuilding a scene
9626
+ * throws away everything the running game has done to it.
9627
+ */
9628
+ readonly reloadScenes: boolean;
9629
+ /**
9630
+ * Applies replaced component classes to the running app.
9631
+ *
9632
+ * @param modules - The replaced modules and the classes they export.
9633
+ * @returns What was reloaded.
9634
+ * @throws IgnifxError with code `IGX-0208` when called from inside a lifecycle callback, where a
9635
+ * half-swapped world would be observable.
9636
+ */
9637
+ apply(modules: readonly HotReloadModule[]): HotReloadReport;
9638
+ /**
9639
+ * Rebuilds one scene instance from its asset's current value, honouring the file's instance
9640
+ * overrides wherever their paths still resolve.
9641
+ *
9642
+ * @param instance - The instance to rebuild. It is unloaded and a fresh one takes its place.
9643
+ * @returns The new instance.
9644
+ * @throws IgnifxError with code `IGX-0209` when the instance was not built from a scene asset.
9645
+ */
9646
+ reloadScene(instance: SceneInstance): Promise<SceneInstance>;
9647
+ }
9648
+ /**
9649
+ * The `hotReload` section of `createApp`'s options.
9650
+ *
9651
+ * @public
9652
+ */
9653
+ interface HotReloadOptions {
9654
+ /** Sets {@link HotReloadHost.reloadScenes}. Defaults to `false`. */
9655
+ readonly reloadScenes?: boolean;
9656
+ }
9657
+ //#endregion
9317
9658
  //#region src/log/log-level.d.ts
9318
9659
  /**
9319
9660
  * Severity levels and the record shape the logging sinks receive
@@ -9400,10 +9741,15 @@ interface LogSink {
9400
9741
  * one numeric comparison. The rest parameter itself is still materialised by the JavaScript engine,
9401
9742
  * so per-frame call sites guard with {@link Logger.isEnabled} instead (coding standards §7).
9402
9743
  *
9744
+ * **A message is not a format string.** It is written to the sink verbatim and the extras are
9745
+ * appended beside it, the way `console.warn(message, ...data)` does; nothing substitutes into it, so
9746
+ * a `{placeholder}` token is printed literally. Pass values as extras
9747
+ * (`log.info("hero z:", z)`), never as tokens inside the message.
9748
+ *
9403
9749
  * @example
9404
9750
  * ```ts
9405
9751
  * const log = app.log.child("physics");
9406
- * log.info("stepping at {hz}Hz", 60);
9752
+ * log.info("stepping at 60 Hz");
9407
9753
  * if (log.isEnabled("debug")) {
9408
9754
  * log.debug("contacts", collectContacts());
9409
9755
  * }
@@ -9475,6 +9821,16 @@ interface Logger {
9475
9821
  * @returns The scoped logger.
9476
9822
  */
9477
9823
  child(scope: string): Logger;
9824
+ /**
9825
+ * Adds a second sink that receives every record this logger tree writes, alongside the one
9826
+ * `createApp({ logSink })` installed. Children share the list, so a sink added on `app.log` sees
9827
+ * `ctx.log` records too. This is how `@ignifx/devtools` fills its Console panel without the game
9828
+ * wiring anything.
9829
+ *
9830
+ * @param sink - The sink to add.
9831
+ * @returns A function that removes it again.
9832
+ */
9833
+ addSink(sink: LogSink): () => void;
9478
9834
  }
9479
9835
  /**
9480
9836
  * Options for {@link createLogger}.
@@ -9503,7 +9859,8 @@ interface LoggerOptions {
9503
9859
  * @example
9504
9860
  * ```ts
9505
9861
  * const log = createLogger({ sink: createConsoleSink(), level: "debug" });
9506
- * log.child("assets").warnOnce("missing-atlas", "No atlas for sprite {id}.");
9862
+ * // A message is not a format string — nothing substitutes into it. Pass values as extras.
9863
+ * log.child("assets").warnOnce("missing-atlas", "No atlas for sprite:", spriteId);
9507
9864
  * ```
9508
9865
  *
9509
9866
  * @public
@@ -9512,102 +9869,908 @@ export declare function createLogger(options: LoggerOptions): Logger;
9512
9869
  //#endregion
9513
9870
  //#region src/platform/platform.d.ts
9514
9871
  /**
9515
- * The minimal platform probe reached as `app.platform`
9516
- * (`docs/architecture/14-platform-electron.md` §1). Phase 1 answers only the question the kernel
9517
- * itself asks — is there a document to hang `visibilitychange` on? — and the rest of §1's surface
9518
- * (`os`, `isMobile`, `hasPointerLock`, `hasGamepads`, `webgpu`, `locale`, `reducedMotion`) arrives
9519
- * with `@ignifx/electron` in Phase 9 of `docs/plan/engineering-plan.md`.
9872
+ * `app.platform`: what the engine knows about the host it is running on
9873
+ * (`docs/architecture/14-platform-electron.md` §1). Extensions branch on it — the input extension to
9874
+ * decide whether pointer lock is worth offering, the renderer to size its budgets — and game code
9875
+ * rarely should.
9876
+ *
9877
+ * ## Decisions the documents left open
9878
+ *
9879
+ * - **Detection is a pure function of a `PlatformHost` record.** §1 says the service is
9880
+ * "populated at `createApp`" and nothing else. Reading the globals and *interpreting* them are
9881
+ * two different jobs, and only the first one needs a browser: `readPlatformHost` scrapes
9882
+ * `globalThis` and `detectPlatform` turns the result into a {@link PlatformInfo}. That is
9883
+ * what lets the whole of the interpretation — every operating system, every mobile heuristic — be
9884
+ * unit-tested under Node with a fabricated host.
9885
+ * - **`kind` is `"browser"` until something proves otherwise.** An Electron renderer *is* a browser
9886
+ * as far as the kernel can tell; guessing from the user agent would be worse than being honest.
9887
+ * `@ignifx/electron` detects its own preload bridge and calls
9888
+ * `platformInternals(app.platform).setKind("electron")`, which is the one supported mutation.
9889
+ * - **`webgpu` describes the adapter, not the device.** Babylon Lite's public `index.d.ts` (v1.27.0)
9890
+ * exposes neither the `GPUAdapter` nor the `GPUDevice` it acquired — `EngineContext` declares only
9891
+ * `surfaces`, `drawCallCount`, `gpuFrameTimeMs`, `useHighPrecisionMatrix` and `useFloatingOrigin`
9892
+ * — so reaching the engine's device would mean an assertion onto an undocumented `_device`
9893
+ * property. `createApp` asks `navigator.gpu` for a *second* adapter instead, which costs nothing
9894
+ * (an adapter is not a device) and reports what the hardware can do rather than what Lite asked
9895
+ * for. `features` and `limits` are therefore an upper bound on the running device's.
9896
+ * - **Every field is plain data.** `features` is a sorted string array and `limits` a number record,
9897
+ * not the live `GPUSupportedFeatures`/`GPUSupportedLimits` objects, so the whole record survives
9898
+ * `JSON.stringify` into a bug report or a devtools panel.
9520
9899
  */
9521
9900
  /**
9522
9901
  * Where an app is running.
9523
9902
  *
9903
+ * @public
9904
+ */
9905
+ type PlatformKind = "browser" | "electron" | "node";
9906
+ /**
9907
+ * Which operating system the host runs, as far as it will admit.
9908
+ *
9909
+ * @remarks
9910
+ * `"unknown"` is a real answer, not a failure: a locked-down browser that freezes its user agent
9911
+ * and exposes no `navigator.userAgentData` genuinely does not say, and code that branches on the
9912
+ * operating system has to have a default anyway.
9913
+ *
9914
+ * @public
9915
+ */
9916
+ type PlatformOs = "macos" | "windows" | "linux" | "ios" | "android" | "unknown";
9917
+ /**
9918
+ * Who made the GPU, as WebGPU reports it.
9919
+ *
9524
9920
  * @remarks
9525
- * `"electron"` is deliberately absent until the Electron extension can detect it reliably: an
9526
- * Electron renderer is a browser as far as the kernel is concerned, and guessing from the user
9527
- * agent would be worse than saying `"browser"`.
9921
+ * Browsers deliberately blur these strings — most return an empty `architecture` and `device` on
9922
+ * the default, non-`unmaskHints` path — so treat every field as a hint for a bug report rather than
9923
+ * as something to branch on.
9528
9924
  *
9529
9925
  * @public
9530
9926
  */
9531
- type PlatformKind = "browser" | "node";
9927
+ interface GpuAdapterInfo {
9928
+ /** The GPU vendor, `"apple"` or `"nvidia"`; `""` when the browser withholds it. */
9929
+ readonly vendor: string;
9930
+ /** The GPU family, `"metal-3"`; `""` when the browser withholds it. */
9931
+ readonly architecture: string;
9932
+ /** The specific device; `""` when the browser withholds it. */
9933
+ readonly device: string;
9934
+ /** A human-readable summary; `""` when the browser withholds it. */
9935
+ readonly description: string;
9936
+ }
9937
+ /**
9938
+ * What the host's WebGPU adapter offers.
9939
+ *
9940
+ * @public
9941
+ */
9942
+ interface WebGpuInfo {
9943
+ /** Who made the adapter. */
9944
+ readonly adapterInfo: GpuAdapterInfo;
9945
+ /** The optional features the adapter supports, sorted ascending. */
9946
+ readonly features: readonly string[];
9947
+ /** The adapter's limits, by their WebGPU names. */
9948
+ readonly limits: Readonly<Record<string, number>>;
9949
+ }
9532
9950
  /**
9533
- * What the kernel knows about the host.
9951
+ * What the kernel knows about the host, reached as `app.platform`.
9534
9952
  *
9535
9953
  * @example
9536
9954
  * ```ts
9537
- * if (app.platform.kind === "browser") {
9538
- * document.title = "playing";
9955
+ * if (app.platform.isMobile) {
9956
+ * app.renderer.resolutionScale = 0.75;
9957
+ * }
9958
+ * if (app.platform.reducedMotion) {
9959
+ * disableScreenShake();
9539
9960
  * }
9540
9961
  * ```
9541
9962
  *
9542
9963
  * @public
9543
9964
  */
9544
9965
  interface PlatformInfo {
9545
- /** Whether the app runs in a document or in a bare JavaScript runtime. */
9966
+ /** Whether the app runs in a document, in an Electron renderer, or in a bare JavaScript runtime. */
9546
9967
  readonly kind: PlatformKind;
9547
- }
9548
- //#endregion
9549
- //#region src/app/types.d.ts
9550
- /**
9551
- * The contracts the kernel and the runtime agree on: frame phases, the clock, systems, extensions,
9552
- * services, coroutines, and the `App` surface a script sees through `this.app`
9553
- * (`docs/architecture/01-lifecycle-and-time.md`, `03-scripting-and-components.md` §6–§7,
9554
- * `04-extensions.md` §1).
9968
+ /** The operating system, or `"unknown"` when the host does not say. */
9969
+ readonly os: PlatformOs;
9970
+ /** `true` on a phone or a tablet. */
9971
+ readonly isMobile: boolean;
9972
+ /** `true` when the host implements the Pointer Lock API. */
9973
+ readonly hasPointerLock: boolean;
9974
+ /** `true` when the host implements the Gamepad API. */
9975
+ readonly hasGamepads: boolean;
9976
+ /** What WebGPU offers, or `null` in a headless app and on a host with no WebGPU. */
9977
+ readonly webgpu: WebGpuInfo | null;
9978
+ /** The host's BCP 47 language tag, `"en-AU"`. Never empty. */
9979
+ readonly locale: string;
9980
+ /** `true` when the user asked their system for reduced motion. */
9981
+ readonly reducedMotion: boolean;
9982
+ }
9983
+ /**
9984
+ * The raw host readings `detectPlatform` interprets. Every field is exactly one global read, so a
9985
+ * test can fabricate any host without touching `globalThis`.
9555
9986
  *
9556
- * The module declares types and two frozen constant tables only — no classes and no behaviour — so
9557
- * that the scene graph and the runtime can be written against it independently.
9987
+ * @internal
9988
+ */
9989
+ interface PlatformHost {
9990
+ /** `true` when both a `document` and a `window` are reachable. */
9991
+ readonly hasDocument: boolean;
9992
+ /** `navigator.userAgent`, or `null`. */
9993
+ readonly userAgent: string | null;
9994
+ /** The deprecated `navigator.platform`, or `null`. */
9995
+ readonly navigatorPlatform: string | null;
9996
+ /** `navigator.userAgentData.platform`, or `null` on a browser that has no client hints. */
9997
+ readonly userAgentDataPlatform: string | null;
9998
+ /** `navigator.userAgentData.mobile`, or `null` on a browser that has no client hints. */
9999
+ readonly userAgentDataMobile: boolean | null;
10000
+ /** `navigator.maxTouchPoints`, `0` when the host has none. */
10001
+ readonly maxTouchPoints: number;
10002
+ /** `true` when the document implements pointer lock. */
10003
+ readonly hasPointerLock: boolean;
10004
+ /** `true` when the navigator implements the Gamepad API. */
10005
+ readonly hasGamepads: boolean;
10006
+ /** The BCP 47 language tag the host reports. */
10007
+ readonly locale: string;
10008
+ /** `true` when `(prefers-reduced-motion: reduce)` matches. */
10009
+ readonly reducedMotion: boolean;
10010
+ /** Node's `process.platform`, or `null` outside Node. */
10011
+ readonly processPlatform: string | null;
10012
+ }
10013
+ /**
10014
+ * The mutable `PlatformInfo` the app owns.
10015
+ *
10016
+ * @internal
9558
10017
  */
10018
+ declare class PlatformInfoImpl implements PlatformInfo {
10019
+ #private;
10020
+ /** The operating system. */
10021
+ readonly os: PlatformOs;
10022
+ /** `true` on a phone or a tablet. */
10023
+ readonly isMobile: boolean;
10024
+ /** `true` when the host implements pointer lock. */
10025
+ readonly hasPointerLock: boolean;
10026
+ /** `true` when the host implements the Gamepad API. */
10027
+ readonly hasGamepads: boolean;
10028
+ /** The host's BCP 47 language tag. */
10029
+ readonly locale: string;
10030
+ /** `true` when the user asked for reduced motion. */
10031
+ readonly reducedMotion: boolean;
10032
+ /**
10033
+ * Builds the record from one set of host readings.
10034
+ *
10035
+ * @param host - What `readPlatformHost` scraped, or what a test fabricated.
10036
+ */
10037
+ constructor(host: PlatformHost);
10038
+ /**
10039
+ * Where the app is running.
10040
+ *
10041
+ * @returns The host kind.
10042
+ */
10043
+ get kind(): PlatformKind;
10044
+ /**
10045
+ * What WebGPU offers.
10046
+ *
10047
+ * @returns The adapter report, or `null` in a headless app.
10048
+ */
10049
+ get webgpu(): WebGpuInfo | null;
10050
+ /**
10051
+ * Records that this browser is in fact an Electron renderer.
10052
+ *
10053
+ * @param kind - The host kind to report from now on.
10054
+ */
10055
+ setKind(kind: PlatformKind): void;
10056
+ /**
10057
+ * Records what the WebGPU adapter offered.
10058
+ *
10059
+ * @param webgpu - The adapter report, or `null` to clear it.
10060
+ */
10061
+ setWebGpu(webgpu: WebGpuInfo | null): void;
10062
+ }
9559
10063
  /**
9560
- * The ordered frame phases (`docs/architecture/01-lifecycle-and-time.md` §3). The ordinals are the
9561
- * order the frame function walks them in, and they index the per-phase CPU timings in
9562
- * `FrameSample.cpuMs`.
10064
+ * Reaches the mutable half of `app.platform`, the way `rendererInternals` does for the renderer.
10065
+ * `@ignifx/electron` uses it to record that the browser it detected is an Electron renderer.
9563
10066
  *
9564
- * @remarks
9565
- * `EndOfFrame` is ordinal `0` because the work it carries is drained at the *top* of the next
9566
- * frame, before the clock advances; the name describes when the work was queued, the ordinal
9567
- * describes when it runs.
10067
+ * @param platform - The record, normally `app.platform`.
10068
+ * @returns The implementation.
10069
+ * @throws IgnifxError with code `IGX-0702` when the record was not created by this copy of
10070
+ * `@ignifx/core`.
9568
10071
  *
9569
10072
  * @example
9570
10073
  * ```ts
9571
- * ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });
10074
+ * platformInternals(app.platform).setKind("electron");
9572
10075
  * ```
9573
10076
  *
9574
- * @public
10077
+ * @internal
9575
10078
  */
9576
- export declare const Phase: {
9577
- /** Deferred signal deliveries and end-of-frame systems, drained at the start of the next frame. */
9578
- readonly EndOfFrame: 0;
9579
- /** Input polling and asset delivery, before any script callback. */
9580
- readonly PreUpdate: 1;
9581
- /** The fixed-timestep simulation loop: `fixedUpdate`, physics, collision dispatch. */
9582
- readonly FixedUpdate: 2;
9583
- /** `update` on every enabled script, then coroutine resumption. */
9584
- readonly Update: 3;
9585
- /** Animation, state machines, and tweens, between `update` and `lateUpdate`. */
9586
- readonly PostUpdate: 4;
9587
- /** Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics. */
9588
- readonly PreRender: 5;
9589
- };
10079
+ export declare function platformInternals(platform: PlatformInfo): PlatformInfoImpl;
10080
+ //#endregion
10081
+ //#region src/storage/backend.d.ts
9590
10082
  /**
9591
- * The union of the frame phases.
10083
+ * The contract every storage backend implements, and the value shape backends persist
10084
+ * (`docs/architecture/14-platform-electron.md` §2). This module declares types only — no behaviour,
10085
+ * no imports — so that `@ignifx/electron` can implement the contract without depending on anything
10086
+ * else in the kernel, and so that {@link StorageBackend} can be quoted in full in a design review.
9592
10087
  *
9593
- * @public
9594
- */
9595
- export type Phase = (typeof Phase)[keyof typeof Phase];
9596
- /**
9597
- * Every phase in frame order, for loops that walk them all.
10088
+ * The split of responsibilities is the whole point of the contract:
9598
10089
  *
9599
- * @public
10090
+ * - The `Storage` facade (`./storage.ts`) owns **policy**: it validates namespace and key syntax,
10091
+ * turns a JavaScript value into a {@link StoredValue} (canonical JSON text, or bytes), and turns a
10092
+ * {@link StoredValue} back into a value. A backend never sees a user object.
10093
+ * - A backend owns **persistence**: it stores opaque JSON text or opaque bytes under a
10094
+ * `(namespace, key)` pair, and reports failures as `IgnifxError`s from the storage code block.
10095
+ *
10096
+ * A backend that keeps those two rules is interchangeable with every other one, which is what makes
10097
+ * the same save file readable from the memory backend in a unit test, the IndexedDB backend in a
10098
+ * browser, and the Electron file-system backend on a desktop build.
9600
10099
  */
9601
- export declare const PHASES: readonly Phase[];
9602
10100
  /**
9603
- * The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
10101
+ * Which of the two representations a stored value uses.
10102
+ *
10103
+ * @remarks
10104
+ * `"json"` carries text produced by the facade's canonical `JSON.stringify`; `"bytes"` carries the
10105
+ * raw octets of a `Blob`, `ArrayBuffer`, or `Uint8Array` the caller handed to `set`. The kind is
10106
+ * stored alongside the payload — a backend that loses it cannot round-trip, because JSON text and
10107
+ * a UTF-8 byte array are indistinguishable once written.
9604
10108
  *
9605
10109
  * @public
9606
10110
  */
9607
- export declare const PHASE_NAMES: readonly string[];
10111
+ type StoredValueKind = "json" | "bytes";
9608
10112
  /**
9609
- * The clock reached as `app.time` (`docs/architecture/01-lifecycle-and-time.md` §2). Every value is
9610
- * in **seconds** unless its name ends in `Ms`.
10113
+ * A value as a backend sees it: opaque JSON text, or opaque octets.
10114
+ *
10115
+ * @remarks
10116
+ * The two members are a discriminated union on their `kind`, so a backend switches once
10117
+ * and the compiler proves both arms are handled. Backends must round-trip both members exactly: the
10118
+ * `json` string that comes back from {@link StorageBackend.get} has to be the same string that went
10119
+ * into {@link StorageBackend.set}, and the `bytes` have to be byte-identical and the same length. A
10120
+ * backend may copy the bytes (IndexedDB's structured clone does) but must never alias the caller's
10121
+ * buffer after `set` resolves.
10122
+ *
10123
+ * @example
10124
+ * ```ts
10125
+ * const value: StoredValue = { kind: "json", json: '{"volume":0.8}' };
10126
+ * await backend.set("settings", "audio", value);
10127
+ * ```
10128
+ *
10129
+ * @public
10130
+ */
10131
+ type StoredValue = {
10132
+ /** Discriminant: this value is JSON text. */
10133
+ readonly kind: "json";
10134
+ /** The canonical JSON text of the value. Never `undefined`, never empty. */
10135
+ readonly json: string;
10136
+ } | {
10137
+ /** Discriminant: this value is a byte array. */
10138
+ readonly kind: "bytes";
10139
+ /** The octets. May be empty. */
10140
+ readonly bytes: Uint8Array;
10141
+ };
10142
+ /**
10143
+ * Where `app.storage` actually puts things (`docs/architecture/14-platform-electron.md` §2).
10144
+ *
10145
+ * @remarks
10146
+ * **The contract.** Implementations may assume all of the following, because the `Storage` facade
10147
+ * guarantees them before every call:
10148
+ *
10149
+ * 1. `namespace` is a non-empty `/`-joined path of segments; each segment is 1–64 characters of
10150
+ * `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, or `-`, and no segment is `.` or `..`. A backend that maps
10151
+ * namespaces onto a hierarchy (directories, object stores) must encode each segment so that two
10152
+ * namespaces differing only in case cannot collide on a case-insensitive file system.
10153
+ * 2. `key` is 1–512 characters, contains no C0 or C1 control character, and is otherwise arbitrary
10154
+ * Unicode — including `/`, `..`, `:`, and characters Windows forbids in file names. Keys are
10155
+ * opaque: a backend never interprets a key's structure, and `keys(namespace, prefix)` is a plain
10156
+ * string-prefix filter, not a path walk.
10157
+ * 3. Namespaces are **scopes, not prefixes**: `get("saves", "a")` and `get("saves/coop", "a")` name
10158
+ * two different values, and neither appears in the other's `keys()` listing.
10159
+ *
10160
+ * Implementations must guarantee all of the following:
10161
+ *
10162
+ * 4. `get` resolves `null` for an absent key — absence is not an error.
10163
+ * 5. `set` replaces any existing value under the same `(namespace, key)`, whatever its kind, and
10164
+ * is atomic against a crash: a reader either sees the whole previous value or the whole new one,
10165
+ * never a partial write. `delete` on an absent key resolves without error.
10166
+ * 6. `keys` resolves the keys of one namespace, filtered by `prefix` when it is given, sorted
10167
+ * ascending with the default `Array.prototype.sort` comparison (UTF-16 code unit order). An
10168
+ * unknown namespace lists as `[]` rather than throwing.
10169
+ * 7. `clear` removes every key of one namespace and leaves other namespaces untouched. Clearing an
10170
+ * unknown namespace resolves without error.
10171
+ * 8. Every rejection is an `IgnifxError` carrying a code from the storage block: `IGX-1424` when the
10172
+ * host is out of quota, `IGX-1426` when a stored value cannot be read back, and `IGX-1425` for
10173
+ * every other backend failure, with the underlying failure as `cause`. Backends never reject with
10174
+ * a raw `DOMException` or a Node `SystemError`.
10175
+ * 9. Every method is safe to call concurrently. Two `set` calls on the same key may land in either
10176
+ * order, but neither may leave the store damaged.
10177
+ *
10178
+ * @example
10179
+ * ```ts
10180
+ * const backend: StorageBackend = new MemoryStorageBackend();
10181
+ * await backend.set("saves", "slot1", { kind: "json", json: '{"level":3}' });
10182
+ * await backend.keys("saves"); // ["slot1"]
10183
+ * ```
10184
+ *
10185
+ * @public
10186
+ */
10187
+ interface StorageBackend {
10188
+ /**
10189
+ * A short, stable identifier for this backend — `"memory"`, `"file"`, `"indexeddb"`,
10190
+ * `"electron-file"`. It appears in error context so a failure names the store it came from.
10191
+ */
10192
+ readonly name: string;
10193
+ /**
10194
+ * Reads one value.
10195
+ *
10196
+ * @param namespace - The namespace path.
10197
+ * @param key - The key inside that namespace.
10198
+ * @returns The stored value, or `null` when the namespace has no such key.
10199
+ */
10200
+ get(namespace: string, key: string): Promise<StoredValue | null>;
10201
+ /**
10202
+ * Writes one value, replacing whatever was there.
10203
+ *
10204
+ * @param namespace - The namespace path, created on demand.
10205
+ * @param key - The key inside that namespace.
10206
+ * @param value - The JSON text or the octets to persist.
10207
+ * @returns A promise that settles once the value is durable.
10208
+ */
10209
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
10210
+ /**
10211
+ * Removes one value.
10212
+ *
10213
+ * @param namespace - The namespace path.
10214
+ * @param key - The key inside that namespace.
10215
+ * @returns A promise that settles once the value is gone; removing an absent key is a no-op.
10216
+ */
10217
+ delete(namespace: string, key: string): Promise<void>;
10218
+ /**
10219
+ * Lists the keys of one namespace.
10220
+ *
10221
+ * @param namespace - The namespace path.
10222
+ * @param prefix - When given, only keys that start with this string are returned.
10223
+ * @returns The matching keys, sorted ascending; `[]` for an unknown namespace.
10224
+ */
10225
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
10226
+ /**
10227
+ * Removes every value of one namespace.
10228
+ *
10229
+ * @param namespace - The namespace path.
10230
+ * @returns A promise that settles once the namespace is empty; an unknown namespace is a no-op.
10231
+ */
10232
+ clear(namespace: string): Promise<void>;
10233
+ /**
10234
+ * Releases whatever the backend holds open — an IndexedDB connection, a file handle, a bridge
10235
+ * subscription. Called from `app.dispose()`. Disposing twice is a no-op, and a backend that holds
10236
+ * nothing may omit the method entirely.
10237
+ */
10238
+ dispose?(): void;
10239
+ }
10240
+ //#endregion
10241
+ //#region src/storage/storage.d.ts
10242
+ /**
10243
+ * `app.storage`: the small, asynchronous key-value store a game keeps its settings, its save slots,
10244
+ * and its input rebindings in (`docs/architecture/14-platform-electron.md` §2).
10245
+ *
10246
+ * The facade owns policy and the backend owns persistence (`./backend.ts`). Everything a game sees
10247
+ * — namespaces, JSON canonicalization, `Blob` support, the error codes — lives here, once, so that
10248
+ * a save written under Node's memory backend in a unit test reads back identically from IndexedDB
10249
+ * in a browser and from the Electron bridge on a desktop build.
10250
+ *
10251
+ * ## Decisions the documents left open
10252
+ *
10253
+ * - **A namespace is a backend scope, not a key prefix.** §2 offers `namespace(name)` without
10254
+ * saying which. A scope is the stronger contract: `keys()` on `"saves"` cannot leak a key from
10255
+ * `"saves-old"`, a directory backend gets one directory per namespace for free, and clearing a
10256
+ * namespace is one operation rather than a scan. Nested namespaces join with `/`, so
10257
+ * `storage.namespace("saves").namespace("coop")` is the scope `"saves/coop"` — a *different*
10258
+ * scope from `"saves"`, whose keys it does not list.
10259
+ * - **`app.storage` itself is the namespace `"default"`.** Every backend call carries a namespace,
10260
+ * so the root needs a name rather than an empty string each backend would special-case.
10261
+ * - **`namespace(name)` is memoized.** Two calls with the same name return the same object, which
10262
+ * makes `app.storage.namespace("saves") === app.storage.namespace("saves")` true and keeps a
10263
+ * per-frame call from allocating.
10264
+ */
10265
+ /**
10266
+ * The store reached as `app.storage`, and as `app.storage.namespace(name)`.
10267
+ *
10268
+ * @remarks
10269
+ * Values are JSON, or binary: a `Blob`, an `ArrayBuffer`, or any typed array is stored as octets
10270
+ * and read back as a `Uint8Array`. Numbers inside JSON values are canonicalized the way scene files
10271
+ * canonicalize them (`docs/architecture/06-serialization-and-scene-format.md` §2), so writing the
10272
+ * same state twice produces the same bytes.
10273
+ *
10274
+ * Reads and writes are asynchronous on every backend, including the in-memory one, so that game
10275
+ * code written against a test app keeps working on IndexedDB.
10276
+ *
10277
+ * @example
10278
+ * ```ts
10279
+ * const settings = app.storage.namespace("settings");
10280
+ * await settings.set("audio", { master: 0.8, music: 0.5 });
10281
+ * const audio = await settings.get<{ master: number; music: number }>("audio");
10282
+ * ```
10283
+ *
10284
+ * @public
10285
+ */
10286
+ interface Storage {
10287
+ /**
10288
+ * Reads one value.
10289
+ *
10290
+ * @typeParam T - What the caller declares the key holds; unchecked, as for `JSON.parse`.
10291
+ * @param key - The key, 1–512 characters with no control characters.
10292
+ * @returns The value, or `null` when the key was never written.
10293
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1426` when the stored
10294
+ * value cannot be read back, or `IGX-1425` when the backend fails.
10295
+ */
10296
+ get<T>(key: string): Promise<T | null>;
10297
+ /**
10298
+ * Writes one value, replacing whatever was there.
10299
+ *
10300
+ * @typeParam T - The value's type.
10301
+ * @param key - The key, 1–512 characters with no control characters.
10302
+ * @param value - A JSON value, a `Blob`, an `ArrayBuffer`, or a typed array.
10303
+ * @returns A promise that settles once the value is durable.
10304
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1423` when the value has
10305
+ * no JSON form, `IGX-1424` when the host is out of quota, or `IGX-1425` when the backend fails.
10306
+ */
10307
+ set<T>(key: string, value: T): Promise<void>;
10308
+ /**
10309
+ * Removes one value.
10310
+ *
10311
+ * @param key - The key.
10312
+ * @returns A promise that settles once the value is gone. Deleting an absent key is a no-op.
10313
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, or `IGX-1425` when the
10314
+ * backend fails.
10315
+ */
10316
+ delete(key: string): Promise<void>;
10317
+ /**
10318
+ * Lists this namespace's keys.
10319
+ *
10320
+ * @param prefix - When given, only keys that start with this string are returned.
10321
+ * @returns The keys, sorted ascending. Keys of nested namespaces are not included.
10322
+ * @throws IgnifxError with code `IGX-1425` when the backend fails.
10323
+ */
10324
+ keys(prefix?: string): Promise<readonly string[]>;
10325
+ /**
10326
+ * Narrows to a child namespace — `"saves"`, `"settings"`, `"input-overrides"`.
10327
+ *
10328
+ * @param name - 1–64 characters of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`; not `.` or `..`.
10329
+ * @returns The child store, which shares this store's backend and sees none of its keys.
10330
+ * @throws IgnifxError with code `IGX-1421` when the name is not a legal namespace segment.
10331
+ */
10332
+ namespace(name: string): Storage;
10333
+ }
10334
+ /**
10335
+ * The `Storage` implementation: one object per namespace, all of them sharing one backend.
10336
+ *
10337
+ * @internal
10338
+ */
10339
+ declare class StorageImpl implements Storage {
10340
+ #private;
10341
+ /**
10342
+ * Builds a store.
10343
+ *
10344
+ * @param backend - Where values are persisted.
10345
+ * @param namespace - This store's namespace path. Defaults to `"default"`.
10346
+ */
10347
+ constructor(backend: StorageBackend, namespace?: string);
10348
+ /**
10349
+ * This store's namespace path.
10350
+ *
10351
+ * @returns The path, `"default"` at the root and `"saves/coop"` two levels down.
10352
+ */
10353
+ get namespacePath(): string;
10354
+ /**
10355
+ * The backend behind this store and every namespace derived from it.
10356
+ *
10357
+ * @returns The backend.
10358
+ */
10359
+ get backend(): StorageBackend;
10360
+ /**
10361
+ * Swaps the backend of this store and of every namespace already derived from it.
10362
+ *
10363
+ * @remarks
10364
+ * This is how `@ignifx/electron`'s renderer extension installs the file-system backend after
10365
+ * `createApp` has already built the default one: the `app.storage` object a script may already
10366
+ * hold keeps working and starts writing through the bridge.
10367
+ *
10368
+ * @param backend - The replacement backend.
10369
+ */
10370
+ setBackend(backend: StorageBackend): void;
10371
+ /**
10372
+ * Reads one value.
10373
+ *
10374
+ * @typeParam T - What the caller declares the key holds.
10375
+ * @param key - The key.
10376
+ * @returns The value, or `null`.
10377
+ */
10378
+ get<T>(key: string): Promise<T | null>;
10379
+ /**
10380
+ * Writes one value.
10381
+ *
10382
+ * @typeParam T - The value's type.
10383
+ * @param key - The key.
10384
+ * @param value - The value.
10385
+ * @returns A promise that settles once the value is durable.
10386
+ */
10387
+ set<T>(key: string, value: T): Promise<void>;
10388
+ /**
10389
+ * Removes one value.
10390
+ *
10391
+ * @param key - The key.
10392
+ * @returns A promise that settles once the value is gone.
10393
+ */
10394
+ delete(key: string): Promise<void>;
10395
+ /**
10396
+ * Lists this namespace's keys.
10397
+ *
10398
+ * @param prefix - An optional key prefix.
10399
+ * @returns The keys, sorted ascending.
10400
+ */
10401
+ keys(prefix?: string): Promise<readonly string[]>;
10402
+ /**
10403
+ * Narrows to a child namespace.
10404
+ *
10405
+ * @param name - The child segment.
10406
+ * @returns The child store.
10407
+ */
10408
+ namespace(name: string): Storage;
10409
+ }
10410
+ /**
10411
+ * Reaches the engine-owned half of a `Storage`, the way `rendererInternals` does for the
10412
+ * renderer. `@ignifx/electron` uses it to install its bridge backend after `createApp`.
10413
+ *
10414
+ * @param storage - The store, normally `app.storage`.
10415
+ * @returns The implementation.
10416
+ * @throws IgnifxError with code `IGX-0702` when the object was not created by this copy of
10417
+ * `@ignifx/core`.
10418
+ *
10419
+ * @example
10420
+ * ```ts
10421
+ * storageInternals(app.storage).setBackend(new ElectronFileStorageBackend(host));
10422
+ * ```
10423
+ *
10424
+ * @internal
10425
+ */
10426
+ export declare function storageInternals(storage: Storage): StorageImpl;
10427
+ //#endregion
10428
+ //#region src/tween/channel.d.ts
10429
+ /**
10430
+ * One tweened property: what kind of value it holds, where it started, where it is going, and how
10431
+ * to write it back (`docs/architecture/12-3d-toolkit.md` §4).
10432
+ *
10433
+ * A channel allocates its two endpoint buffers once, when the tween is created, and never again —
10434
+ * which is what keeps `Tweens.advance` allocation-free on the per-frame path (coding standards §7).
10435
+ */
10436
+ /**
10437
+ * The four value shapes a tween can interpolate.
10438
+ *
10439
+ * @public
10440
+ */
10441
+ export declare const TWEEN_VALUE_KINDS: readonly ["number", "vec2", "vec3", "quat"];
10442
+ /**
10443
+ * The union of {@link TWEEN_VALUE_KINDS}.
10444
+ *
10445
+ * @public
10446
+ */
10447
+ type TweenValueKind = (typeof TWEEN_VALUE_KINDS)[number];
10448
+ /**
10449
+ * A value a tween knows how to interpolate: a plain number, or an object with `x`/`y`(`/z`(`/w`))
10450
+ * components.
10451
+ *
10452
+ * @public
10453
+ */
10454
+ type TweenableValue = number | Vec2Like | Vec3Like | QuatLike;
10455
+ //#endregion
10456
+ //#region src/tween/easing.d.ts
10457
+ /**
10458
+ * A curve mapping normalized time to a normalized value. Custom curves have this shape.
10459
+ *
10460
+ * @param t - Normalized time in `[0, 1]`.
10461
+ * @returns The eased value; `0` at `t = 0` and `1` at `t = 1`, free to overshoot in between.
10462
+ *
10463
+ * @public
10464
+ */
10465
+ type EasingFunction = (t: number) => number;
10466
+ /**
10467
+ * Every named easing curve, keyed by the name `TweenOptions.ease` accepts.
10468
+ *
10469
+ * @example
10470
+ * ```ts
10471
+ * const halfway = EASINGS.cubicInOut(0.5); // 0.5
10472
+ * ```
10473
+ *
10474
+ * @public
10475
+ */
10476
+ export declare const EASINGS: Readonly<Record<string, EasingFunction>>;
10477
+ /**
10478
+ * The names {@link EASINGS} declares, in table order (coding standards §5.2 — an `as const` table
10479
+ * and the union derived from it, never an enum).
10480
+ *
10481
+ * @public
10482
+ */
10483
+ export declare const EASING_NAMES: readonly ["linear", "quadIn", "quadOut", "quadInOut", "cubicIn", "cubicOut", "cubicInOut", "sineInOut", "backOut", "elasticOut", "bounceOut"];
10484
+ /**
10485
+ * The union of the named easing curves.
10486
+ *
10487
+ * @public
10488
+ */
10489
+ type EasingName = (typeof EASING_NAMES)[number];
10490
+ /**
10491
+ * Resolves an `ease` option to the function a tween will call.
10492
+ *
10493
+ * @param ease - A name from {@link EASING_NAMES}, a custom curve, or `undefined` for `linear`.
10494
+ * @returns The curve, or `null` when the name is not one the table declares.
10495
+ *
10496
+ * @example
10497
+ * ```ts
10498
+ * const curve = resolveEase("cubicOut");
10499
+ * ```
10500
+ *
10501
+ * @public
10502
+ */
10503
+ export declare function resolveEase(ease: EasingName | EasingFunction | undefined): EasingFunction | null;
10504
+ //#endregion
10505
+ //#region src/tween/tween.d.ts
10506
+ /**
10507
+ * A running tween and the handle a game holds on to (`docs/architecture/12-3d-toolkit.md` §4).
10508
+ *
10509
+ * A tween is created by `app.tweens.to(...)`, advanced once per frame in `PostUpdate`, and dies
10510
+ * with the app. Everything it needs is allocated in the constructor: advancing one costs a few
10511
+ * multiplications per channel and nothing on the heap (coding standards §7).
10512
+ */
10513
+ /**
10514
+ * `loop: -1` means "repeat until stopped".
10515
+ *
10516
+ * @public
10517
+ */
10518
+ export declare const TWEEN_LOOP_FOREVER = -1;
10519
+ /**
10520
+ * What `app.tweens.to(...)` accepts.
10521
+ *
10522
+ * @public
10523
+ */
10524
+ interface TweenOptions {
10525
+ /** How long one cycle takes, in seconds. Must be finite and greater than zero. */
10526
+ readonly duration: number;
10527
+ /** The curve, by name or as a custom `(t) => number`. Defaults to `"linear"`. */
10528
+ readonly ease?: EasingName | EasingFunction;
10529
+ /** How long to wait before the first cycle starts, in seconds. Defaults to `0`. */
10530
+ readonly delay?: number;
10531
+ /** How many extra cycles to run; `-1` repeats forever. Defaults to `0` — one cycle. */
10532
+ readonly loop?: number;
10533
+ /** Whether every other cycle plays backwards. Defaults to `false`. */
10534
+ readonly yoyo?: boolean;
10535
+ /**
10536
+ * Whether the tween keeps running while `app.pause()` holds. A tween that does advances on
10537
+ * `time.unscaledDeltaTime`; every other tween advances on `time.deltaTime` and is frozen by a
10538
+ * pause. Defaults to `false`.
10539
+ */
10540
+ readonly updateWhenPaused?: boolean;
10541
+ /** Called once when the tween finishes on its own or through {@link Tween.complete}. */
10542
+ readonly onComplete?: () => void;
10543
+ }
10544
+ /**
10545
+ * A tween in flight.
10546
+ *
10547
+ * @remarks
10548
+ * Endpoints are latched when the delay elapses, not when the tween is created, so two tweens queued
10549
+ * on one property in the same frame chain rather than fight.
10550
+ *
10551
+ * @example
10552
+ * ```ts
10553
+ * const tween = app.tweens.to(entity.transform, { position: { x: 5, y: 0, z: 0 } }, {
10554
+ * duration: 1,
10555
+ * ease: "cubicInOut",
10556
+ * });
10557
+ * tween.onComplete.connect(() => app.log.info("arrived"));
10558
+ * ```
10559
+ *
10560
+ * @public
10561
+ */
10562
+ export declare class Tween {
10563
+ #private;
10564
+ /** Fires once when the tween finishes, with the tween itself. Never fires after `stop`. */
10565
+ readonly onComplete: Signal<Tween>;
10566
+ /** Whether the tween runs while the app is paused. */
10567
+ readonly updateWhenPaused: boolean;
10568
+ /**
10569
+ * Builds a tween. Games call `app.tweens.to(...)` instead.
10570
+ *
10571
+ * @param target - The object whose fields move.
10572
+ * @param props - The destination value of each field.
10573
+ * @param options - Duration, curve, delay, looping, and the completion callback.
10574
+ * @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
10575
+ * @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
10576
+ *
10577
+ * @internal
10578
+ */
10579
+ constructor(target: object, props: Readonly<Record<string, TweenableValue>>, options: TweenOptions);
10580
+ /**
10581
+ * The object being tweened, for `stopAllOf`.
10582
+ *
10583
+ * @returns The object being tweened, for `stopAllOf`.
10584
+ */
10585
+ get target(): object;
10586
+ /**
10587
+ * How far through the current cycle the tween is, in `[0, 1]`, after the yoyo reversal and before
10588
+ * the easing curve.
10589
+ *
10590
+ * @returns The normalized cycle time.
10591
+ */
10592
+ get progress(): number;
10593
+ /**
10594
+ * Whether the tween is still advancing.
10595
+ *
10596
+ * @returns Whether the tween is still advancing.
10597
+ */
10598
+ get isPlaying(): boolean;
10599
+ /**
10600
+ * Whether `pause` is holding the tween.
10601
+ *
10602
+ * @returns Whether `pause` is holding the tween.
10603
+ */
10604
+ get isPaused(): boolean;
10605
+ /**
10606
+ * Whether the tween has finished or been stopped and will never advance again.
10607
+ *
10608
+ * @returns Whether the tween has finished or been stopped and will never advance again.
10609
+ */
10610
+ get isDone(): boolean;
10611
+ /** Holds the tween where it is; `resume` picks it back up. */
10612
+ pause(): void;
10613
+ /** Releases a `pause`. */
10614
+ resume(): void;
10615
+ /**
10616
+ * Ends the tween where it stands, leaving the target at its current value. `onComplete` does not
10617
+ * fire.
10618
+ */
10619
+ stop(): void;
10620
+ /**
10621
+ * Jumps the target to the tween's end value, then finishes it. `onComplete` fires, exactly as it
10622
+ * would have on the last frame.
10623
+ */
10624
+ complete(): void;
10625
+ /**
10626
+ * Advances the tween by one frame's worth of time.
10627
+ *
10628
+ * @param dt - Seconds to advance by, already chosen for this tween's `updateWhenPaused`.
10629
+ * @returns `true` when the tween is done and should leave the list.
10630
+ *
10631
+ * @internal
10632
+ */
10633
+ advance(dt: number): boolean;
10634
+ }
10635
+ //#endregion
10636
+ //#region src/tween/tweens.d.ts
10637
+ /**
10638
+ * `app.tweens` (`docs/architecture/12-3d-toolkit.md` §4): the app-wide tween list, advanced once
10639
+ * per frame in `PostUpdate` on ignifx's own clock.
10640
+ *
10641
+ * Tweens live in core rather than in a toolkit because both toolkits use them, and because a tween
10642
+ * is a clock consumer like any other: it obeys `time.timeScale`, it is frozen by `app.pause()`
10643
+ * unless it opted out, and it dies when the app is disposed (ADR-0003).
10644
+ */
10645
+ /**
10646
+ * The destination value the tween should reach for one field, narrowed to the field's own shape.
10647
+ *
10648
+ * @remarks
10649
+ * `QuatLike` is tested before `Vec3Like` because a quaternion satisfies both: `{ x, y, z, w }` is
10650
+ * assignable to `{ x, y, z }`.
10651
+ *
10652
+ * @typeParam V - The field's declared type.
10653
+ *
10654
+ * @public
10655
+ */
10656
+ type TweenTargetValue<V> = V extends number ? number : V extends QuatLike ? QuatLike : V extends Vec3Like ? Vec3Like : V extends Vec2Like ? Vec2Like : never;
10657
+ /**
10658
+ * The destinations `app.tweens.to` accepts for a target: every numeric, `Vec2`, `Vec3`, or `Quat`
10659
+ * field of `T`, each one optional.
10660
+ *
10661
+ * @typeParam T - The target object's type.
10662
+ *
10663
+ * @example
10664
+ * ```ts
10665
+ * const props: TweenProps<Transform> = { position: { x: 1, y: 2, z: 3 } };
10666
+ * ```
10667
+ *
10668
+ * @public
10669
+ */
10670
+ type TweenProps<T> = { readonly [K in keyof T as T[K] extends TweenableValue ? K : never]?: TweenTargetValue<T[K]>; };
10671
+ /**
10672
+ * The app-wide tween list.
10673
+ *
10674
+ * @example
10675
+ * ```ts
10676
+ * app.tweens.to(entity.transform, { position: { x: 0, y: 3, z: 0 } }, {
10677
+ * duration: 0.6,
10678
+ * ease: "backOut",
10679
+ * yoyo: true,
10680
+ * loop: 1,
10681
+ * });
10682
+ * ```
10683
+ *
10684
+ * @public
10685
+ */
10686
+ interface Tweens {
10687
+ /** How many tweens are alive. */
10688
+ readonly count: number;
10689
+ /**
10690
+ * Starts a tween towards `props` and returns the handle.
10691
+ *
10692
+ * @typeParam T - The target object's type.
10693
+ * @param target - The object whose fields move. Any object with numeric or vector fields works.
10694
+ * @param props - The destination value of each field to move.
10695
+ * @param options - Duration, curve, delay, looping, and the completion callback.
10696
+ * @returns The running tween.
10697
+ * @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
10698
+ * @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
10699
+ */
10700
+ to<T extends object>(target: T, props: TweenProps<T>, options: TweenOptions): Tween;
10701
+ /** Stops every tween, without firing any `onComplete`. */
10702
+ stopAll(): void;
10703
+ /**
10704
+ * Stops every tween that moves one object.
10705
+ *
10706
+ * @param target - The object.
10707
+ * @returns How many tweens were stopped.
10708
+ */
10709
+ stopAllOf(target: object): number;
10710
+ }
10711
+ //#endregion
10712
+ //#region src/app/types.d.ts
10713
+ /**
10714
+ * The contracts the kernel and the runtime agree on: frame phases, the clock, systems, extensions,
10715
+ * services, coroutines, and the `App` surface a script sees through `this.app`
10716
+ * (`docs/architecture/01-lifecycle-and-time.md`, `03-scripting-and-components.md` §6–§7,
10717
+ * `04-extensions.md` §1).
10718
+ *
10719
+ * The module declares types and two frozen constant tables only — no classes and no behaviour — so
10720
+ * that the scene graph and the runtime can be written against it independently.
10721
+ */
10722
+ /**
10723
+ * The ordered frame phases (`docs/architecture/01-lifecycle-and-time.md` §3). The ordinals are the
10724
+ * order the frame function walks them in, and they index the per-phase CPU timings in
10725
+ * `FrameSample.cpuMs`.
10726
+ *
10727
+ * @remarks
10728
+ * `EndOfFrame` is ordinal `0` because the work it carries is drained at the *top* of the next
10729
+ * frame, before the clock advances; the name describes when the work was queued, the ordinal
10730
+ * describes when it runs.
10731
+ *
10732
+ * @example
10733
+ * ```ts
10734
+ * ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });
10735
+ * ```
10736
+ *
10737
+ * @public
10738
+ */
10739
+ export declare const Phase: {
10740
+ /** Deferred signal deliveries and end-of-frame systems, drained at the start of the next frame. */
10741
+ readonly EndOfFrame: 0;
10742
+ /** Input polling and asset delivery, before any script callback. */
10743
+ readonly PreUpdate: 1;
10744
+ /** The fixed-timestep simulation loop: `fixedUpdate`, physics, collision dispatch. */
10745
+ readonly FixedUpdate: 2;
10746
+ /** `update` on every enabled script, then coroutine resumption. */
10747
+ readonly Update: 3;
10748
+ /** Animation, state machines, and tweens, between `update` and `lateUpdate`. */
10749
+ readonly PostUpdate: 4;
10750
+ /** Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics. */
10751
+ readonly PreRender: 5;
10752
+ };
10753
+ /**
10754
+ * The union of the frame phases.
10755
+ *
10756
+ * @public
10757
+ */
10758
+ export type Phase = (typeof Phase)[keyof typeof Phase];
10759
+ /**
10760
+ * Every phase in frame order, for loops that walk them all.
10761
+ *
10762
+ * @public
10763
+ */
10764
+ export declare const PHASES: readonly Phase[];
10765
+ /**
10766
+ * The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
10767
+ *
10768
+ * @public
10769
+ */
10770
+ export declare const PHASE_NAMES: readonly string[];
10771
+ /**
10772
+ * The clock reached as `app.time` (`docs/architecture/01-lifecycle-and-time.md` §2). Every value is
10773
+ * in **seconds** unless its name ends in `Ms`.
9611
10774
  *
9612
10775
  * @example
9613
10776
  * ```ts
@@ -9662,7 +10825,11 @@ interface SystemContext {
9662
10825
  readonly time: Time;
9663
10826
  /** The phase currently running. */
9664
10827
  readonly phase: Phase;
9665
- /** Seconds elapsed: `time.deltaTime`, or `time.fixedDeltaTime` inside the fixed loop. */
10828
+ /**
10829
+ * Seconds elapsed: `time.deltaTime`, or `time.fixedDeltaTime` inside the fixed loop. Systems run
10830
+ * while the app is paused and `dt` is **not** zeroed then — only scripts are filtered by
10831
+ * `updateWhenPaused` — so a system that animates checks `time.paused` itself.
10832
+ */
9666
10833
  readonly dt: number;
9667
10834
  }
9668
10835
  /**
@@ -9855,7 +11022,7 @@ interface AppSettings {
9855
11022
  * @example
9856
11023
  * ```ts
9857
11024
  * app.onError.connect((report) => {
9858
- * app.log.error("{source} callback threw on {entity}", report.source, report.entity?.name ?? "-");
11025
+ * app.log.error(`${report.source} callback threw on ${report.entity?.name ?? "-"}`, report.error);
9859
11026
  * });
9860
11027
  * ```
9861
11028
  *
@@ -10062,14 +11229,31 @@ interface App {
10062
11229
  /** The `@ignifx/core` version this app was built from. */
10063
11230
  readonly version: string;
10064
11231
  /**
10065
- * Where the app is running (`docs/architecture/14-platform-electron.md` §1). Phase 1 answers only
10066
- * `kind`; the rest of §1's surface arrives with `@ignifx/electron`.
11232
+ * Where the app is running, what it is running on, and what its WebGPU adapter offers
11233
+ * (`docs/architecture/14-platform-electron.md` §1).
10067
11234
  */
10068
11235
  readonly platform: PlatformInfo;
11236
+ /**
11237
+ * The asynchronous key-value store settings, save games, and input rebindings live in
11238
+ * (`docs/architecture/14-platform-electron.md` §2). The backend is chosen from
11239
+ * {@link PlatformInfo.kind} — IndexedDB in a browser, memory under Node — unless `createApp` was
11240
+ * given one.
11241
+ */
11242
+ readonly storage: Storage;
10069
11243
  /** Unstable Babylon Lite escape hatch (`docs/architecture/00-overview.md` §3). */
10070
11244
  readonly lite: AppLiteHandles;
10071
11245
  /** The coroutine scheduler. */
10072
11246
  readonly coroutines: CoroutineHost;
11247
+ /**
11248
+ * The app-wide tween list (`docs/architecture/12-3d-toolkit.md` §4), advanced in `PostUpdate` on
11249
+ * ignifx's clock and used by both toolkits.
11250
+ */
11251
+ readonly tweens: Tweens;
11252
+ /**
11253
+ * Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5). The Vite
11254
+ * plugin's HMR client drives it in development; it works headlessly with no bundler at all.
11255
+ */
11256
+ readonly hotReload: HotReloadHost;
10073
11257
  /**
10074
11258
  * Makes component `typeId`s known to the serializer and the inspector
10075
11259
  * (`docs/architecture/03-scripting-and-components.md` §4).
@@ -10390,6 +11574,42 @@ interface Extension {
10390
11574
  */
10391
11575
  type SettingsInput = Readonly<Record<string, unknown>>;
10392
11576
  //#endregion
11577
+ //#region src/storage/node/file-backend.d.ts
11578
+ /**
11579
+ * Options accepted by {@link createFileStorageBackend}.
11580
+ *
11581
+ * @public
11582
+ */
11583
+ interface FileStorageOptions {
11584
+ /**
11585
+ * The root directory. It is created on first write, together with every namespace directory
11586
+ * under it. Under Electron this is `app.getPath("userData")`; in a test it is a temporary
11587
+ * directory.
11588
+ */
11589
+ readonly directory: string;
11590
+ }
11591
+ /**
11592
+ * Builds a storage backend over a directory (`docs/architecture/14-platform-electron.md` §5).
11593
+ *
11594
+ * @remarks
11595
+ * Node only: the factory loads `node:fs/promises` and rejects on a host that has none. It is what
11596
+ * `createApp({ storage: { directory } })` calls, and it is exported so that tooling — `ignifx bake`,
11597
+ * a future authoritative server — can build one without an app.
11598
+ *
11599
+ * @param options - The root directory.
11600
+ * @returns The backend.
11601
+ * @throws IgnifxError with code `IGX-1425` when the host exposes no `node:fs/promises`.
11602
+ *
11603
+ * @example
11604
+ * ```ts
11605
+ * const app = await createApp({ headless: true, storage: { directory: "./.saves" } });
11606
+ * await app.storage.namespace("saves").set("slot1", { level: 3 });
11607
+ * ```
11608
+ *
11609
+ * @public
11610
+ */
11611
+ export declare function createFileStorageBackend(options: FileStorageOptions): Promise<StorageBackend>;
11612
+ //#endregion
10393
11613
  //#region src/time/clock.d.ts
10394
11614
  /**
10395
11615
  * The wall clock the runtime reads (`docs/architecture/01-lifecycle-and-time.md` §2, §8). It is a
@@ -10504,10 +11724,17 @@ interface CreateAppOptions {
10504
11724
  readonly extensions?: readonly Extension[];
10505
11725
  /**
10506
11726
  * Project settings, as `ignifx.config.ts` would supply them
10507
- * (`docs/architecture/04-extensions.md` §5). The Vite plugin injects the resolved config in
10508
- * Phase 2; tests and Electron tooling pass it here.
11727
+ * (`docs/architecture/04-extensions.md` §5). `@ignifx/vite-plugin` injects the resolved
11728
+ * `ignifx.config.ts` as the `import.meta.env.IGNIFX_CONFIG` literal, which a game passes straight
11729
+ * in here; tests and Electron tooling pass their own object instead.
10509
11730
  */
10510
11731
  readonly settings?: SettingsInput;
11732
+ /**
11733
+ * Where `app.storage` puts things (`docs/architecture/14-platform-electron.md` §2). Pass a
11734
+ * {@link StorageBackend} to install one, or `{ directory }` to write a directory tree under Node.
11735
+ * Defaults to IndexedDB in a browser and to an in-memory store everywhere else.
11736
+ */
11737
+ readonly storage?: StorageBackend | FileStorageOptions;
10511
11738
  /**
10512
11739
  * The asset service's construction options
10513
11740
  * (`docs/architecture/05-assets-and-loading.md` §7). The manifest normally arrives from
@@ -10531,8 +11758,17 @@ interface CreateAppOptions {
10531
11758
  readonly clock?: Clock;
10532
11759
  /**
10533
11760
  * `"development"` turns on per-phase CPU timings, full error messages, and the strict half of
10534
- * every rule `04-extensions.md` §2 relaxes in production. Defaults to `"development"`; the Vite
10535
- * plugin sets it from the build mode in Phase 2.
11761
+ * every rule `04-extensions.md` §2 relaxes in production.
11762
+ *
11763
+ * @remarks
11764
+ * Defaults to `"development"`, and **nothing else ever changes it**: neither `@ignifx/vite-plugin`
11765
+ * nor a template overrides it, so a production `vite build` of a game that passes no `mode` runs
11766
+ * in development mode — full error text, `performance.mark`/`measure` entries, and
11767
+ * `FrameSample.cpuMs` filled in. That is deliberate: the mode decides how the *engine* reports
11768
+ * itself, and only the game knows whether its shipped build wants that. Pass it from the bundler's
11769
+ * own flag to opt out — `mode: import.meta.env.PROD ? "production" : "development"`.
11770
+ *
11771
+ * @defaultValue `"development"`
10536
11772
  */
10537
11773
  readonly mode?: ErrorFormatMode;
10538
11774
  /** Where `app.log` writes. Defaults to the console sink. */
@@ -10542,6 +11778,12 @@ interface CreateAppOptions {
10542
11778
  * prints nothing at startup; pass `"debug"` to see the kernel's own diagnostics.
10543
11779
  */
10544
11780
  readonly logLevel?: LogThreshold;
11781
+ /**
11782
+ * Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5).
11783
+ * `app.hotReload.apply` always works; the only thing to configure is whether a changed scene file
11784
+ * rebuilds the live instances built from it.
11785
+ */
11786
+ readonly hotReload?: HotReloadOptions;
10545
11787
  }
10546
11788
  /**
10547
11789
  * Creates a game (`docs/architecture/00-overview.md` §1, `04-extensions.md` §2).
@@ -10839,7 +12081,8 @@ export declare const coreExtension: (options?: void) => Extension;
10839
12081
  *
10840
12082
  * @typeParam O - The options object the factory accepts. Defaults to `void` for an extension that
10841
12083
  * takes none.
10842
- * @param factory - Builds the extension descriptor from its options.
12084
+ * @param factory - Builds the extension descriptor from its options, which are `undefined` when the
12085
+ * game called the factory without an argument — default them (`(options = {})`) or read them as optional.
10843
12086
  * @returns A factory that may be called with no argument, in which case the options are `undefined`.
10844
12087
  *
10845
12088
  * @example
@@ -10858,7 +12101,7 @@ export declare const coreExtension: (options?: void) => Extension;
10858
12101
  *
10859
12102
  * @public
10860
12103
  */
10861
- export declare function defineExtension<O = void>(factory: (options: O) => Extension): (options?: O) => Extension;
12104
+ export declare function defineExtension<O = void>(factory: (options: O | undefined) => Extension): (options?: O) => Extension;
10862
12105
  //#endregion
10863
12106
  //#region src/ids/random-source.d.ts
10864
12107
  /**
@@ -11103,7 +12346,7 @@ type LiteShadowGenerator = ShadowGenerator;
11103
12346
  /**
11104
12347
  * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
11105
12348
  *
11106
- * @internal
12349
+ * @public
11107
12350
  */
11108
12351
  export declare const SHADOW_TECHNIQUES: readonly ["esm", "pcf", "csm"];
11109
12352
  //#endregion
@@ -12025,7 +13268,39 @@ export declare class Vec4 {
12025
13268
  * `setSceneImageProcessing` is **async** (`index.d.ts` 10917) because tone mapping is baked into
12026
13269
  * the PBR shaders at `registerScene` time; changing it recompiles the affected pipelines
12027
13270
  * (`rebuildScenePbrPipelines`). Setting exposure or contrast alone still goes through the same
12028
- * call.
13271
+ * call. Note that `loadEnvironment` **overwrites** all three (`toneMappingEnabled = true`,
13272
+ * `exposure = 0.8`, `contrast = 1.2`) as a side effect of installing an environment, which is why
13273
+ * the `Environment` component re-applies its own image processing after every install.
13274
+ *
13275
+ * ## Swapping the installed environment: `scene._envTextures`
13276
+ *
13277
+ * Lite 1.27.0 declares **no** public way to replace, clear, or read back a registered scene's
13278
+ * environment. `index.d.ts` has no `scene.environmentTexture`, no `unloadEnvironment`, and no
13279
+ * setter of any kind; `loadEnvironment` is the only installer and it fetches, decodes, and uploads
13280
+ * a fresh cube map every call. What it actually installs is one field —
13281
+ * `scene._envTextures = textures` (`lib/_chunks/env-helpers-CRI1i-A3.js` 24, and the same line in
13282
+ * `lib/loader-hdr/load-hdr.js` 23, `lib/loader-env/load-dds-env.js` 177 and
13283
+ * `lib/loader-gltf/gltf-ext-lights-image-based.js` 65) — and every consumer reads that field:
13284
+ *
13285
+ * - the PBR group builder, which bakes the cube view and sampler into each material's bind group
13286
+ * (`lib/material/pbr/pbr-material.js` 12 → `lib/material/pbr/pbr-renderable.js`);
13287
+ * - the scene-uniform packer, for `lodGenerationScale` (`lib/frame-graph/scene-uniforms-pack.js` 21);
13288
+ * - the env UBO contributor, for the diffuse spherical harmonics (`lib/scene/scene-ubo-extras.js` 24);
13289
+ * - the blur contributor, for `lodGenerationOffset` (`lib/scene/set-environment-blur.js` 8);
13290
+ * - the render task's scene-UBO cache key, which is keyed on the **object identity** of the field
13291
+ * (`lib/frame-graph/render-task.js` 358), so a new object re-uploads the harmonics by itself.
13292
+ *
13293
+ * Lite's own device-lost recovery replaces the field exactly this way
13294
+ * (`lib/loader-env/environment-recovery.js` 16 and 38), so {@link installSceneEnvironment} writes it
13295
+ * too. Bind groups are the one consumer that does *not* re-read it: they hold the `GPUTextureView`,
13296
+ * so a swap only reaches the specular reflection once the material groups have been rebuilt, which
13297
+ * `rebuildSceneRenderables` does (`lib/scene/scene-rebuild.js`, `rebuildEachGroup`). The
13298
+ * `Environment` component therefore reports an install as a topology change and lets the render-sync
13299
+ * system fire its one coalesced rebuild. This is the only place in ignifx that touches a Lite field
13300
+ * `index.d.ts` does not declare, which is what the adapter boundary exists for
13301
+ * (`CONSTITUTION.md` §3.4, ADR-0002); it is pinned by
13302
+ * `packages/core/test/lite/render/environment.browser.test.ts`, which fails loudly if the field is
13303
+ * renamed.
12029
13304
  */
12030
13305
  /**
12031
13306
  * The GPU-resident image-based-lighting textures `loadEnvironment` resolves to, re-exported under an
@@ -12040,7 +13315,7 @@ type LiteEnvironmentTextures = EnvironmentTextures;
12040
13315
  /**
12041
13316
  * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.
12042
13317
  *
12043
- * @internal
13318
+ * @public
12044
13319
  */
12045
13320
  export declare const TONE_MAPPING_NAMES: readonly ["none", "standard", "aces", "neutral"];
12046
13321
  //#endregion
@@ -12219,6 +13494,53 @@ export declare function environmentDefinition(overrides?: Partial<EnvironmentDef
12219
13494
  * becoming an unhandled rejection (coding standards §8). The visible consequence is that a script
12220
13495
  * that ramps exposure every frame gets as many recompiles as the GPU can keep up with and no queue.
12221
13496
  *
13497
+ * ## Switching environments at runtime
13498
+ *
13499
+ * An `.env` is loaded **onto the scene** by the asset loader, because that is the only shape Lite's
13500
+ * `loadEnvironment` has (`./environment-asset.ts` explains it at length). Until 2026-09-08 that
13501
+ * meant `environment` was effectively read-only after the first load: the component re-aimed what
13502
+ * the loader had installed and nothing more, so assigning a second loaded handle changed the
13503
+ * rotation and the blur and left the lighting alone. It now installs the asset's recorded handles
13504
+ * on the scene (`./gpu/environment-install.ts`) and reports the install as a **topology change**,
13505
+ * which the render-sync system coalesces into the frame's one `rebuildSceneRenderables` — the step
13506
+ * that makes every PBR material re-bind the new cube map, because a bind group holds the texture
13507
+ * view rather than the scene's slot. Two loaded handles can therefore be swapped back and forth for
13508
+ * free: the GPU resources belong to the assets, stay alive while their handles are retained, and are
13509
+ * released by the asset system exactly as before.
13510
+ *
13511
+ * Installing also re-applies rotation, blur, **and** image processing, because Lite's
13512
+ * `loadEnvironment` overwrites `scene.imageProcessing` (`toneMappingEnabled`, `exposure = 0.8`,
13513
+ * `contrast = 1.2`) as a side effect of every load.
13514
+ *
13515
+ * ## Assigning `null` leaves the scene lit
13516
+ *
13517
+ * Lite 1.27.0 has no inverse of `loadEnvironment` — no `unloadEnvironment`, no
13518
+ * `scene.environmentTexture` to clear — and clearing its slot by hand would leave every PBR
13519
+ * material bound to a cube map the scene no longer admits to having until the next renderable
13520
+ * rebuild. So `environment = null` is documented as "stop steering the environment", not "turn the
13521
+ * lights off": the last installed environment keeps lighting the scene, exactly as detaching the
13522
+ * component does. {@link Environment.installed} keeps naming it, because that is what the scene is
13523
+ * actually lit by. To change the lighting, install a different loaded environment.
13524
+ *
13525
+ * ## `skybox` is decided when the environment loads, not here
13526
+ *
13527
+ * Lite builds the background inside `loadEnvironment`, as a *feature-owned* `Renderable` pushed
13528
+ * onto the scene from a deferred builder that `registerScene` drains
13529
+ * (`lib/_chunks/env-helpers-*.js`). `Renderable` (`index.d.ts` 9678) is `{ order, isTransparent,
13530
+ * mesh?, bind }` — no visibility flag, no size, no handle — and Lite exposes no way to remove one,
13531
+ * so a background that has been built cannot be hidden, resized, or re-aimed at another cube map.
13532
+ * The `.environment.json` is therefore the authority: `skyboxEnabled`, `skybox` and `skyboxSize`
13533
+ * decide the background when the asset loads. The component's `skybox` record is read every frame
13534
+ * so that a value the installed environment cannot deliver is *reported* — `IGX-0711`, once per
13535
+ * component — rather than silently ignored, which is what it was until 2026-09-08. A field left at
13536
+ * its schema default never reports anything, so only a project that actually asked for a different
13537
+ * background hears about it.
13538
+ *
13539
+ * The one improvement that did fit: an environment with `skyboxEnabled` and no explicit `skybox`
13540
+ * now draws **its own** prefiltered cube map (`./loaders/environment-loader.ts`), where Lite's
13541
+ * default was a flat box painted in the clear colour. So a bare `.env` gets a real background, and
13542
+ * the component's default `skybox.enabled: true` agrees with it.
13543
+ *
12222
13544
  * ## `ambientColor` does not exist
12223
13545
  *
12224
13546
  * §2.5 lists an `ambientColor` field. Babylon Lite 1.27.0 has no scene-level ambient term:
@@ -12269,6 +13591,24 @@ interface EnvironmentFogSettings {
12269
13591
  /** Where linear fog reaches full strength, in metres. */
12270
13592
  end: number;
12271
13593
  }
13594
+ /**
13595
+ * The `skybox` record an `Environment` declares (`docs/architecture/07-rendering.md` §2.5).
13596
+ *
13597
+ * @remarks
13598
+ * Babylon Lite 1.27.0 builds the background inside `loadEnvironment` and hands back no handle on
13599
+ * it, so both fields are decided when the environment **loads** and cannot be changed afterwards.
13600
+ * Declare them in the `.environment.json` (`skyboxEnabled`, `skyboxSize`); a component that asks
13601
+ * for something else logs `IGX-0711` once. The defaults match the file format's, so the ordinary
13602
+ * case is silent.
13603
+ *
13604
+ * @public
13605
+ */
13606
+ interface EnvironmentSkyboxSettings {
13607
+ /** Whether a background is drawn behind the scene. */
13608
+ enabled: boolean;
13609
+ /** The background cube's size, in metres. */
13610
+ size: number;
13611
+ }
12272
13612
  /**
12273
13613
  * The `imageProcessing` record an `Environment` declares
12274
13614
  * (`docs/architecture/07-rendering.md` §2.5).
@@ -12289,12 +13629,20 @@ interface ImageProcessingSettings {
12289
13629
  * @example
12290
13630
  * ```ts
12291
13631
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
12292
- * world.createEntity("Environment").addComponent(Environment, {
13632
+ * const env = world.createEntity("Environment").addComponent(Environment, {
12293
13633
  * environment: studio.retain(),
12294
13634
  * imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
12295
13635
  * });
12296
13636
  * ```
12297
13637
  *
13638
+ * @example
13639
+ * Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
13640
+ *
13641
+ * ```ts
13642
+ * const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
13643
+ * env.environment = night.retain();
13644
+ * ```
13645
+ *
12298
13646
  * @public
12299
13647
  */
12300
13648
  export declare class Environment extends Component implements ComponentHooks {
@@ -12308,19 +13656,22 @@ export declare class Environment extends Component implements ComponentHooks {
12308
13656
  environment: AssetHandle<EnvironmentAsset> | null;
12309
13657
  rotation: number;
12310
13658
  blur: number;
12311
- skybox: {
12312
- enabled: boolean;
12313
- size: number;
12314
- };
13659
+ skybox: EnvironmentSkyboxSettings;
12315
13660
  fog: EnvironmentFogSettings;
12316
13661
  imageProcessing: ImageProcessingSettings;
12317
13662
  clearColor: ColorLike;
12318
13663
  /** Applies the schema defaults, exactly as `Component.define` would. */
12319
13664
  constructor();
12320
13665
  /**
12321
- * The environment asset this component installed, once it has loaded.
13666
+ * The environment asset this component installed on the scene.
12322
13667
  *
12323
- * @returns The asset, or `null` when none is loaded.
13668
+ * @remarks
13669
+ * It stops at the **last installed** asset, which is what the scene is actually lit by: setting
13670
+ * `environment` back to `null` does not un-light the scene, because Lite has no inverse of
13671
+ * `loadEnvironment` (see the module remarks). Headless it names the asset too — what a headless
13672
+ * app skips is the cube map, not the bookkeeping.
13673
+ *
13674
+ * @returns The asset, or `null` when this component has never installed one.
12324
13675
  */
12325
13676
  get installed(): EnvironmentAsset | null;
12326
13677
  /** Records that the component exists; the scene is written on the first sync. */
@@ -12340,10 +13691,13 @@ export declare class Environment extends Component implements ComponentHooks {
12340
13691
  * environment only.
12341
13692
  *
12342
13693
  * @param renderer - The rendering service, for the scene and the headless flag.
13694
+ * @returns `true` when a different environment was installed on the scene this frame, which is a
13695
+ * topology change: the render-sync system owes the frame one `rebuildSceneRenderables` so that
13696
+ * every PBR material re-binds the new cube map.
12343
13697
  *
12344
13698
  * @internal
12345
13699
  */
12346
- sync(renderer: RendererImpl): void;
13700
+ sync(renderer: RendererImpl): boolean;
12347
13701
  }
12348
13702
  //#endregion
12349
13703
  //#region src/lite/font.d.ts
@@ -12661,6 +14015,14 @@ export declare class Light extends Component implements ComponentHooks {
12661
14015
  * file (`docs/architecture/05-assets-and-loading.md` §5,
12662
14016
  * `06-serialization-and-scene-format.md` §6).
12663
14017
  *
14018
+ * ## The skybox is decided here, once
14019
+ *
14020
+ * Lite builds the background inside `loadEnvironment` and hands back no handle on it, so this is
14021
+ * the only place that can decide whether there is one: `Environment.skybox` can report a
14022
+ * disagreement (`IGX-0711`) but cannot change it. `skyboxEnabled: false` skips the background;
14023
+ * otherwise the declaration's `skybox` image is used, and when it names none the environment draws
14024
+ * **its own** prefiltered cube map (see {@link toLoadOptions}).
14025
+ *
12664
14026
  * ## Two addresses, one asset type
12665
14027
  *
12666
14028
  * A bare `.env` address is the common case: load this IBL, take the BRDF table and the skybox from
@@ -12781,7 +14143,9 @@ export declare function createMaterialLoader(): AssetLoader<MaterialAsset>;
12781
14143
  *
12782
14144
  * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
12783
14145
  *
12784
- * `loadGltf(engine, source)` (`index.d.ts` 6821) takes a URL, an `ArrayBuffer`, or a `Blob` and
14146
+ * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
14147
+ * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
14148
+ * `ArrayBuffer`, or a `Blob` and
12785
14149
  * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
12786
14150
  * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
12787
14151
  * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
@@ -12852,8 +14216,8 @@ type LiteSkeleton = Skeleton;
12852
14216
  * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
12853
14217
  * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
12854
14218
  * removes them from the container the moment it is loaded and the asset keeps them
12855
- * ({@link ModelAsset.animations}). Phase 2 exposes them and advances nothing; `@ignifx/3d`'s
12856
- * animator is what plays them.
14219
+ * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
14220
+ * `Animator` is what plays them.
12857
14221
  *
12858
14222
  * ## Instance counting
12859
14223
  *
@@ -12923,9 +14287,9 @@ export declare class ModelAsset {
12923
14287
  * The clips the file declared, stripped from the container so Lite never ticks them.
12924
14288
  *
12925
14289
  * @remarks
12926
- * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s animator, and they
12927
- * are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. A `Model` re-binds
12928
- * them per instance when the animation system lands; in Phase 2 they are read-only metadata.
14290
+ * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
14291
+ * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
14292
+ * are read-only metadata: nothing here advances or re-binds them.
12929
14293
  *
12930
14294
  * @beta
12931
14295
  */
@@ -12998,8 +14362,8 @@ export declare class ModelAsset {
12998
14362
  * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
12999
14363
  *
13000
14364
  * A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
13001
- * resolve those relative URLs itself, which it can only do when it did the fetching. Phase 2 loads
13002
- * the container from bytes either way and therefore supports self-contained `.gltf` files and
14365
+ * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
14366
+ * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
13003
14367
  * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
13004
14368
  * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
13005
14369
  * three-line change whenever a project needs it.
@@ -13394,10 +14758,11 @@ export declare class MeshAsset {
13394
14758
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
13395
14759
  * `Mesh.id` strings (`lib/render/lights-ubo.js`), and §2.2 maps `Light.includeOnly` onto them
13396
14760
  * from *entity* references. The uid is the one identifier both sides can name.
13397
- * - **`materials` beyond the first is accepted and ignored in Phase 2.** §2.3 says "one per
13398
- * submesh", but Lite's `Mesh.material` is a single value and Lite has no submesh material list in
13399
- * 1.27.0. The field keeps its array shape so files do not have to change when submeshes land; the
13400
- * renderer uses index 0, or the default material when the array is empty.
14761
+ * - **`materials` beyond the first is accepted and ignored.** §2.3 says "one per submesh", but
14762
+ * Lite's `Mesh.material` is a single value and Lite has no submesh material list in 1.27.0, so
14763
+ * there is nothing for the extra entries to drive. The field keeps its array shape so files do
14764
+ * not have to change if submeshes land; the renderer uses index 0, or the default material when
14765
+ * the array is empty.
13401
14766
  *
13402
14767
  * ## Headless
13403
14768
  *
@@ -13524,8 +14889,8 @@ export declare class Model extends Component implements ComponentHooks {
13524
14889
  * The clips the file declared.
13525
14890
  *
13526
14891
  * @remarks
13527
- * Unstable: these are Lite's own animation groups, and ignifx does not advance them in Phase 2
13528
- * (ADR-0003 — `@ignifx/3d`'s animator owns playback).
14892
+ * Unstable: these are Lite's own animation groups, and core does not advance them
14893
+ * (ADR-0003 — `@ignifx/3d`'s `Animator` owns playback).
13529
14894
  *
13530
14895
  * @returns The clips, in load order.
13531
14896
  *
@@ -13614,8 +14979,8 @@ export declare class Model extends Component implements ComponentHooks {
13614
14979
  * neither is inspectable without extra tooling. Three optional records with an `order` each is the
13615
14980
  * simplest shape that round-trips through `encodeProps`/`decodeProps` unchanged, shows up in the
13616
14981
  * inspector with real field names and tooltips, and still lets a project reorder the chain. The
13617
- * cost is that adding a fourth effect in Phase 7 adds a fourth record rather than a new list entry;
13618
- * that is a schema addition, which the format already tolerates.
14982
+ * cost is that a fourth effect would add a fourth record rather than a new list entry; that is a
14983
+ * schema addition, which the format already tolerates.
13619
14984
  *
13620
14985
  * ## It needs `rendering.features.postProcessing`, declared at app start
13621
14986
  *
@@ -13706,6 +15071,12 @@ interface ImageProcessingEffectSettings {
13706
15071
  * One instance of a post-process chain, attached to the main camera's entity
13707
15072
  * (`docs/architecture/07-rendering.md` §2.7).
13708
15073
  *
15074
+ * @remarks
15075
+ * The stack may be attached and configured either **before** or after `app.start()`. Before start
15076
+ * the chain's frame-graph tasks are appended and recorded by the scene registration `start()` runs;
15077
+ * after start they are recorded on the spot. Either way the first frame the canvas presents already
15078
+ * carries the effects.
15079
+ *
13709
15080
  * @example
13710
15081
  * ```ts
13711
15082
  * cameraEntity.addComponent(PostProcessStack, {
@@ -13744,6 +15115,13 @@ export declare class PostProcessStack extends Component implements ComponentHook
13744
15115
  * Builds the chain the first time any effect is enabled, and switches individual effects on and
13745
15116
  * off after that. The `PreRender` system calls it.
13746
15117
  *
15118
+ * @remarks
15119
+ * It is also called once by `app.start()`, through `renderer.syncBeforeRegister`, which is what
15120
+ * makes a stack configured **before** `start()` work: at that point the scene's frame graph has
15121
+ * not been built, so the chain appends its tasks and lets `registerScene` record them
15122
+ * (`PostProcessChain`'s `isFrameGraphBuilt`). Recording them early instead binds a scene colour
15123
+ * that no task has allocated yet and Lite rejects the whole frame with error 107.
15124
+ *
13747
15125
  * @param renderer - The rendering service, for the engine and the scene.
13748
15126
  *
13749
15127
  * @internal
@@ -14473,8 +15851,8 @@ export declare function optional<T>(inner: FieldDefinition<T>, options?: FieldOp
14473
15851
  * project settings does not silently repoint existing files
14474
15852
  * (`docs/architecture/06-serialization-and-scene-format.md` §3).
14475
15853
  *
14476
- * The value type is a read-only array of names in Phase 1; the kernel's `LayerMask` class arrives
14477
- * with the layer registry and will satisfy the same structural shape.
15854
+ * The field's value is a read-only array of names. The kernel's `LayerMask` satisfies the same
15855
+ * structural shape, so a component may hold either.
14478
15856
  *
14479
15857
  * @param defaultValue - The names a new component starts with; defaults to empty.
14480
15858
  * @param options - Inspector and serializer metadata.
@@ -14708,5 +16086,196 @@ export declare function waitUntil(predicate: () => boolean): WaitInstruction;
14708
16086
  */
14709
16087
  export declare function waitWhile(predicate: () => boolean): WaitInstruction;
14710
16088
  //#endregion
14711
- export type { App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentRefFieldSpec, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CurveFieldSpec, CurveKey, CurveValue, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FontAssetLiteHandles, FrameSample, FrameState, GroundMeshOptions, IgnifxErrorOptions, ImageProcessingEffectSettings, ImageProcessingSettings, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAlphaModeName, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MemorySink, MeshAssetLiteHandles, MeshGeometryData, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PlaneMeshOptions, PlatformInfo, PlatformKind, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderPick, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, StringFieldSpec, System, SystemContext, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WorldLiteHandles };
16089
+ //#region src/storage/memory-backend.d.ts
16090
+ /**
16091
+ * The in-memory storage backend: the default for a headless app, and the one every unit test in the
16092
+ * engine runs against (`docs/architecture/14-platform-electron.md` §2, §5).
16093
+ *
16094
+ * It is the reference implementation of `./backend.ts`: nothing here is a shortcut for being
16095
+ * in-process. Values are copied in and out, so a caller that mutates the `Uint8Array` it wrote
16096
+ * cannot reach the store; namespaces are separate maps rather than prefixed keys; and every method
16097
+ * is asynchronous even though none of them needs to be, because game code written against this
16098
+ * backend has to keep working on IndexedDB.
16099
+ */
16100
+ /**
16101
+ * A store that lives as long as the app does.
16102
+ *
16103
+ * @example
16104
+ * ```ts
16105
+ * const app = await createApp({ storage: new MemoryStorageBackend() });
16106
+ * ```
16107
+ *
16108
+ * @public
16109
+ */
16110
+ export declare class MemoryStorageBackend implements StorageBackend {
16111
+ #private;
16112
+ /** The identifier that appears in error context. */
16113
+ readonly name = "memory";
16114
+ /**
16115
+ * Reads one value.
16116
+ *
16117
+ * @param namespace - The namespace path.
16118
+ * @param key - The key.
16119
+ * @returns A copy of the stored value, or `null`.
16120
+ */
16121
+ get(namespace: string, key: string): Promise<StoredValue | null>;
16122
+ /**
16123
+ * Writes one value.
16124
+ *
16125
+ * @param namespace - The namespace path, created on demand.
16126
+ * @param key - The key.
16127
+ * @param value - The value to copy in.
16128
+ * @returns A promise that settles once the value is stored.
16129
+ */
16130
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
16131
+ /**
16132
+ * Removes one value.
16133
+ *
16134
+ * @param namespace - The namespace path.
16135
+ * @param key - The key.
16136
+ * @returns A promise that settles once the value is gone.
16137
+ */
16138
+ delete(namespace: string, key: string): Promise<void>;
16139
+ /**
16140
+ * Lists one namespace's keys.
16141
+ *
16142
+ * @param namespace - The namespace path.
16143
+ * @param prefix - An optional key prefix.
16144
+ * @returns The matching keys, sorted ascending.
16145
+ */
16146
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
16147
+ /**
16148
+ * Empties one namespace.
16149
+ *
16150
+ * @param namespace - The namespace path.
16151
+ * @returns A promise that settles once the namespace is empty.
16152
+ */
16153
+ clear(namespace: string): Promise<void>;
16154
+ /** Drops every namespace. */
16155
+ dispose(): void;
16156
+ }
16157
+ //#endregion
16158
+ //#region src/storage/names.d.ts
16159
+ /**
16160
+ * The syntax rules `app.storage` enforces on namespaces and keys before a backend ever sees them
16161
+ * (`docs/architecture/14-platform-electron.md` §2), and the reasons they are as narrow as they are.
16162
+ *
16163
+ * A **namespace** ends up as a directory on disk and as part of a compound IndexedDB key, so its
16164
+ * alphabet has to survive every file system ignifx runs on: it is deliberately small, and the
16165
+ * validator refuses the two names — `.` and `..` — that mean something else to a path resolver. A
16166
+ * **key** is opaque: it may hold anything a game wants to name a save slot, including `/`, `..`,
16167
+ * `:` and characters Windows forbids, because backends encode keys rather than resolve them
16168
+ * (`./file-names.ts`). All a key may not be is empty, unreasonably long, or full of control
16169
+ * characters that would make a listing unreadable.
16170
+ */
16171
+ /**
16172
+ * The namespace `app.storage` itself reads and writes before `namespace(name)` is called.
16173
+ *
16174
+ * @remarks
16175
+ * Every backend call carries a namespace, so the root storage needs a name of its own rather than
16176
+ * an empty string that each backend would have to special-case. `"default"` is a legal namespace
16177
+ * name, which means a game that writes `app.storage.namespace("default")` reaches the same values —
16178
+ * intentionally, since the two are the same store.
16179
+ *
16180
+ * @public
16181
+ */
16182
+ export declare const DEFAULT_STORAGE_NAMESPACE = "default";
16183
+ /**
16184
+ * The longest one segment of a namespace path may be.
16185
+ *
16186
+ * @public
16187
+ */
16188
+ export declare const NAMESPACE_SEGMENT_MAX_LENGTH = 64;
16189
+ /**
16190
+ * The longest a storage key may be.
16191
+ *
16192
+ * @remarks
16193
+ * 512 UTF-16 code units is comfortably below the ~255 *byte* file-name limit once percent-encoding
16194
+ * has expanded the key, which is why the file backend hashes nothing and truncates nothing: a key
16195
+ * that passes this check always encodes to a name a file system accepts.
16196
+ *
16197
+ * @public
16198
+ */
16199
+ export declare const STORAGE_KEY_MAX_LENGTH = 512;
16200
+ //#endregion
16201
+ //#region src/storage/web/indexeddb-backend.d.ts
16202
+ /**
16203
+ * A store backed by the browser's IndexedDB.
16204
+ *
16205
+ * @example
16206
+ * ```ts
16207
+ * const app = await createApp({ canvas, storage: new IndexedDbStorageBackend() });
16208
+ * ```
16209
+ *
16210
+ * @public
16211
+ */
16212
+ export declare class IndexedDbStorageBackend implements StorageBackend {
16213
+ #private;
16214
+ /** The identifier that appears in error context. */
16215
+ readonly name = "indexeddb";
16216
+ /**
16217
+ * Reads one value.
16218
+ *
16219
+ * @param namespace - The namespace path.
16220
+ * @param key - The key.
16221
+ * @returns The value, or `null`.
16222
+ */
16223
+ get(namespace: string, key: string): Promise<StoredValue | null>;
16224
+ /**
16225
+ * Writes one value.
16226
+ *
16227
+ * @param namespace - The namespace path.
16228
+ * @param key - The key.
16229
+ * @param value - The value.
16230
+ * @returns A promise that settles once the transaction commits.
16231
+ */
16232
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
16233
+ /**
16234
+ * Removes one value.
16235
+ *
16236
+ * @param namespace - The namespace path.
16237
+ * @param key - The key.
16238
+ * @returns A promise that settles once the transaction commits.
16239
+ */
16240
+ delete(namespace: string, key: string): Promise<void>;
16241
+ /**
16242
+ * Lists one namespace's keys.
16243
+ *
16244
+ * @param namespace - The namespace path.
16245
+ * @param prefix - An optional key prefix.
16246
+ * @returns The matching keys, in ascending order.
16247
+ */
16248
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
16249
+ /**
16250
+ * Empties one namespace.
16251
+ *
16252
+ * @param namespace - The namespace path.
16253
+ * @returns A promise that settles once the transaction commits.
16254
+ */
16255
+ clear(namespace: string): Promise<void>;
16256
+ /** Closes the connection. The next call opens a new one. */
16257
+ dispose(): void;
16258
+ }
16259
+ //#endregion
16260
+ //#region src/tween/tween-system.d.ts
16261
+ /**
16262
+ * The `PostUpdate` system that advances `app.tweens` (`docs/architecture/01-lifecycle-and-time.md`
16263
+ * §3 step 5, `12-3d-toolkit.md` §4).
16264
+ *
16265
+ * `PostUpdate` is where every clock consumer in ignifx advances, so a `lateUpdate` and the render
16266
+ * sync both see the value a tween wrote in the same frame it wrote it.
16267
+ */
16268
+ /**
16269
+ * The `PostUpdate` order the tween system runs at.
16270
+ *
16271
+ * @remarks
16272
+ * `-100` puts tweens **before** the toolkits' animation systems, which register at `0`
16273
+ * (`@ignifx/2d`) and `10` (`@ignifx/3d`): a tween that drives an `Animator` parameter or a
16274
+ * material property is read by the animation that runs after it, in the same frame.
16275
+ *
16276
+ * @public
16277
+ */
16278
+ export declare const TWEEN_SYSTEM_ORDER = -100;
16279
+ //#endregion
16280
+ export type { App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CurveFieldSpec, CurveKey, CurveValue, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, ImageProcessingEffectSettings, ImageProcessingSettings, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MemorySink, MeshAssetLiteHandles, MeshGeometryData, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderPick, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StoredValue, StoredValueKind, StringFieldSpec, System, SystemContext, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
14712
16281
  //# sourceMappingURL=index.d.ts.map