@ignifx/core 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -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. */
@@ -216,6 +229,18 @@ export declare const CoreErrorCode: {
216
229
  readonly postProcessingFeatureOff: "IGX-0710";
217
230
  /** The host exposes no Web Crypto implementation. */
218
231
  readonly cryptoUnavailable: "IGX-1420";
232
+ /** A storage namespace name is not a legal namespace segment. */
233
+ readonly storageInvalidNamespace: "IGX-1421";
234
+ /** A storage key is empty, too long, or contains a control character. */
235
+ readonly storageInvalidKey: "IGX-1422";
236
+ /** A value handed to `app.storage.set` has no JSON form. */
237
+ readonly storageValueNotSerializable: "IGX-1423";
238
+ /** The storage backend refused a write because the host is out of quota or disk space. */
239
+ readonly storageQuotaExceeded: "IGX-1424";
240
+ /** The storage backend failed for a reason the engine cannot classify. */
241
+ readonly storageBackendFailed: "IGX-1425";
242
+ /** A stored value could not be read back; the store was damaged or written by something else. */
243
+ readonly storageValueCorrupt: "IGX-1426";
219
244
  /** An error code was registered twice. */
220
245
  readonly duplicateErrorCode: "IGX-1501";
221
246
  /** An error code does not match `IGX-####` in a known range. */
@@ -226,6 +251,8 @@ export declare const CoreErrorCode: {
226
251
  readonly unknownDiagnosticsCounter: "IGX-1504";
227
252
  /** A `switch` over a union reached a case the type system said was impossible. */
228
253
  readonly unreachableCase: "IGX-1505";
254
+ /** `app.hotReload.reloadScene()` was given an instance that was not built from a scene asset. */
255
+ readonly sceneNotReloadable: "IGX-1506";
229
256
  };
230
257
  /**
231
258
  * The union of the codes `@ignifx/core` owns. Use it to narrow `catch` blocks to core failures.
@@ -1035,7 +1062,9 @@ interface RegisterAssetOptions {
1035
1062
  /**
1036
1063
  * The `fetch` implementation the service performs every read through
1037
1064
  * (`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).
1065
+ * deterministic responses and how a Node app maps addresses onto `fs`. A packaged Electron build
1066
+ * needs no injection: `@ignifx/electron` serves `dist/` over `ignifx://`, which the renderer's own
1067
+ * `fetch` reaches.
1039
1068
  *
1040
1069
  * @public
1041
1070
  */
@@ -1083,6 +1112,14 @@ interface Assets {
1083
1112
  * @returns The handle, once it has loaded.
1084
1113
  */
1085
1114
  loadAsync<T>(ref: AssetRef<T> | string, options?: LoadOptions): Promise<AssetHandle<T>>;
1115
+ /**
1116
+ * Reloads a loaded asset from its source, delivering the new value through `onReplaced` the way a
1117
+ * development hot reload does (`docs/architecture/05-assets-and-loading.md` §7); a handle that is
1118
+ * not loaded is left alone. The Vite plugin's HMR channel and the devtools Assets panel call it.
1119
+ *
1120
+ * @param address - The asset's address.
1121
+ */
1122
+ reload(address: string): void;
1086
1123
  /**
1087
1124
  * Requests several assets as one batch.
1088
1125
  *
@@ -1189,7 +1226,7 @@ interface AssetLoadErrorOptions extends IgnifxErrorOptions {
1189
1226
  * await app.assets.loadAsync("levels/1.scene.json");
1190
1227
  * } catch (error) {
1191
1228
  * if (error instanceof AssetLoadError) {
1192
- * app.log.error("{address} failed from {url}", error.address, error.url);
1229
+ * app.log.error(`${error.address} failed from ${error.url}`, error);
1193
1230
  * }
1194
1231
  * }
1195
1232
  * ```
@@ -1452,8 +1489,12 @@ interface ComponentTypeToken<C> {
1452
1489
  interface AssetTypeToken<A> {
1453
1490
  /** The asset type name written into files when the extension is ambiguous. */
1454
1491
  readonly assetType?: string;
1455
- /** The instance shape the token names. */
1456
- readonly prototype: A;
1492
+ /**
1493
+ * The instance shape the token names. A class token carries it for free; a plain token for an
1494
+ * asset that has no class (a scene, a prefab) leaves it out and fixes `A` through its annotation —
1495
+ * see `SceneAssetToken`. Nothing reads it at runtime.
1496
+ */
1497
+ readonly prototype?: A;
1457
1498
  }
1458
1499
  /**
1459
1500
  * The plain, serializable form of an asset reference: what `{ "$asset": … }` decodes to before the
@@ -1822,6 +1863,18 @@ interface ComponentClassInfo {
1822
1863
  /** A dense index assigned in registration order, for array-indexed per-class bookkeeping. */
1823
1864
  readonly classIndex: number;
1824
1865
  }
1866
+ /**
1867
+ * What {@link ComponentRegistry.replace} swapped, for the hot-reload path that has to re-file every
1868
+ * live instance of the class that went away.
1869
+ *
1870
+ * @public
1871
+ */
1872
+ interface ComponentReplacement {
1873
+ /** The class registered under the id before, or `null` when nothing was. */
1874
+ readonly previous: ComponentType | null;
1875
+ /** The replacement's freshly built info. */
1876
+ readonly info: ComponentClassInfo;
1877
+ }
1825
1878
  /**
1826
1879
  * The component-class table of one app. There is one per {@link App}, never a module-level one
1827
1880
  * (`CONSTITUTION.md` §3.5, §3.6): two apps in one test process must not see each other's types.
@@ -1859,6 +1912,26 @@ export declare class ComponentRegistry {
1859
1912
  * @param types - The component classes.
1860
1913
  */
1861
1914
  registerAll(types: readonly ConcreteComponentType[]): void;
1915
+ /**
1916
+ * Swaps the class registered under a `typeId` for a replacement, for script hot reload
1917
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). The previous class's cached info is
1918
+ * dropped and the replacement inherits its `classIndex`, so per-class bookkeeping indexed by that
1919
+ * number stays valid across a reload.
1920
+ *
1921
+ * @remarks
1922
+ * Additive and hot-reload-only: nothing on the normal path replaces a registration, and
1923
+ * `register` still refuses to bind one id to two classes (`IGX-0203`).
1924
+ *
1925
+ * @param type - The replacement class. It must declare the `typeId` it replaces.
1926
+ * @returns The freshly built info for the replacement, and the class it replaced.
1927
+ * @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
1928
+ *
1929
+ * @example
1930
+ * ```ts
1931
+ * const { previous } = registry.replace(NextMover);
1932
+ * ```
1933
+ */
1934
+ replace(type: ConcreteComponentType): ComponentReplacement;
1862
1935
  /**
1863
1936
  * Describes a class, computing and caching its info on first sight. Explicit registration is only
1864
1937
  * needed for *serializable* components; a script added from code is described the first time it
@@ -2423,24 +2496,24 @@ export declare class Quat {
2423
2496
  /**
2424
2497
  * Builds a rotation from Euler angles in radians, in intrinsic XYZ order.
2425
2498
  *
2426
- * @param xRadians - Rotation about X, in radians.
2427
- * @param yRadians - Rotation about Y, in radians.
2428
- * @param zRadians - Rotation about Z, in radians.
2499
+ * @param xRad - Rotation about X, in radians.
2500
+ * @param yRad - Rotation about Y, in radians.
2501
+ * @param zRad - Rotation about Z, in radians.
2429
2502
  * @returns A new quaternion. **Allocates.**
2430
2503
  */
2431
- static fromEulerRadians(xRadians: number, yRadians: number, zRadians: number): Quat;
2504
+ static fromEulerRad(xRad: number, yRad: number, zRad: number): Quat;
2432
2505
  /**
2433
2506
  * Writes a rotation built from Euler radians into `out`. This is Babylon Lite's `eulerToQuat`
2434
2507
  * (`lib/math/quat-euler.js`) element for element, so a rotation built here means the same thing
2435
2508
  * to Lite's node hierarchy.
2436
2509
  *
2437
- * @param xRadians - Rotation about X, in radians.
2438
- * @param yRadians - Rotation about Y, in radians.
2439
- * @param zRadians - Rotation about Z, in radians.
2510
+ * @param xRad - Rotation about X, in radians.
2511
+ * @param yRad - Rotation about Y, in radians.
2512
+ * @param zRad - Rotation about Z, in radians.
2440
2513
  * @param out - The quaternion to write.
2441
2514
  * @returns `out`.
2442
2515
  */
2443
- static fromEulerRadiansToRef<TOut extends MutableQuat>(xRadians: number, yRadians: number, zRadians: number, out: TOut): TOut;
2516
+ static fromEulerRadToRef<TOut extends MutableQuat>(xRad: number, yRad: number, zRad: number, out: TOut): TOut;
2444
2517
  /**
2445
2518
  * Writes a rotation's Euler angles in degrees into `out`, in intrinsic XYZ order — the inverse of
2446
2519
  * {@link Quat.fromEulerDegreesToRef}.
@@ -2460,7 +2533,7 @@ export declare class Quat {
2460
2533
  * @param out - The vector to write, in radians.
2461
2534
  * @returns `out`.
2462
2535
  */
2463
- static toEulerRadiansToRef<TOut extends MutableVec3>(q: QuatLike, out: TOut): TOut;
2536
+ static toEulerRadToRef<TOut extends MutableVec3>(q: QuatLike, out: TOut): TOut;
2464
2537
  /**
2465
2538
  * Builds a rotation of `degrees` about an axis.
2466
2539
  *
@@ -4187,6 +4260,27 @@ interface SceneAsset {
4187
4260
  /** The content hash of {@link SceneAsset.file}, as `sha256:<hex>`. */
4188
4261
  readonly hash: string;
4189
4262
  }
4263
+ /**
4264
+ * The `asset()` token for a scene or prefab field. `SceneAsset` is an interface, so it cannot be
4265
+ * passed to `asset()` the way a class such as `MeshAsset` can; this token names the type instead:
4266
+ *
4267
+ * ```ts
4268
+ * class Spawner extends Script.define({ prefab: asset(SceneAssetToken) }) {
4269
+ * static typeId = "game/Spawner";
4270
+ * spawn(): void {
4271
+ * const value = this.prefab?.value;
4272
+ * if (value !== undefined) {
4273
+ * this.app.world.instantiate(value, { position: this.transform.position });
4274
+ * }
4275
+ * }
4276
+ * }
4277
+ * ```
4278
+ *
4279
+ * In a scene file the field is written as `{ "$asset": "props/crate.prefab.json" }`.
4280
+ *
4281
+ * @public
4282
+ */
4283
+ export declare const SceneAssetToken: AssetTypeToken<SceneAsset>;
4190
4284
  /**
4191
4285
  * The content hash of a scene file: SHA-256 over the canonical JSON text, so two saves of the same
4192
4286
  * state hash the same and an edited prefab does not
@@ -4931,6 +5025,17 @@ interface WorldInternals {
4931
5025
  * @returns `true` when at least one of the entity's scripts implements it.
4932
5026
  */
4933
5027
  entityImplements(entity: Entity, kind: ScriptCallbackKind): boolean;
5028
+ /**
5029
+ * Re-files an effectively-enabled script in the sorted dispatch lists after script hot reload
5030
+ * swapped its class (`docs/architecture/15-devtools-and-diagnostics.md` §5). No callback runs: the
5031
+ * script leaves the lists its previous class was filed in and joins the ones its new class
5032
+ * implements, at its new `executionOrder`.
5033
+ *
5034
+ * @param component - The component whose class was replaced. A plain component is ignored.
5035
+ * @param previous - The class info the component was filed under.
5036
+ * @param next - The class info it is filed under now, already written to its engine state.
5037
+ */
5038
+ rebindDispatch(component: Component, previous: ScriptClassInfo | null, next: ScriptClassInfo | null): void;
4934
5039
  /**
4935
5040
  * Tells the world which phase is running, so a failure reported through `app.onError` names it.
4936
5041
  * The scheduler sets it on entering a phase and clears it on leaving.
@@ -5327,15 +5432,6 @@ export declare class LayerTable {
5327
5432
  * @public
5328
5433
  */
5329
5434
  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
5435
  //#endregion
5340
5436
  //#region src/lifecycle/frame-state.d.ts
5341
5437
  /**
@@ -5585,15 +5681,16 @@ type LitePbrMaterial = PbrMaterialProps;
5585
5681
  */
5586
5682
  type LiteStandardMaterial = StandardMaterialProps;
5587
5683
  /**
5588
- * How a material's alpha channel is interpreted, in glTF's vocabulary.
5684
+ * How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector
5685
+ * lists them (`docs/architecture/07-rendering.md` §2.4).
5589
5686
  *
5590
- * @internal
5687
+ * @public
5591
5688
  */
5592
5689
  export declare const MATERIAL_ALPHA_MODES: readonly ["opaque", "mask", "blend"];
5593
5690
  /**
5594
5691
  * The union of the alpha modes a material can declare.
5595
5692
  *
5596
- * @internal
5693
+ * @public
5597
5694
  */
5598
5695
  type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
5599
5696
  //#endregion
@@ -5612,14 +5709,15 @@ type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
5612
5709
  * renderer". This module is that boundary: `baseColor`, `emissive`, `diffuse`, and `specular` are
5613
5710
  * decoded here and handed to the adapter linear. Factors that are not colours — `metallic`,
5614
5711
  * `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.
5712
+ * - **`"type": "shader"` is not implemented.** §2.6 lists it, and Lite's `createShaderMaterial`
5713
+ * exists, but its declaration takes a WGSL attribute/uniform/sampler layout whose shape is Lite's
5714
+ * own (`ShaderMaterialOptions`, `index.d.ts`); publishing that verbatim would put a Lite type in
5715
+ * the public API, which `CONSTITUTION.md` §3.4 forbids, and mirroring it is a design job of its
5716
+ * own that no delivered phase took on. A file that declares it is rejected with `IGX-0708`.
5717
+ * - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are not implemented** for the same
5718
+ * reason: each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
5719
+ * code is tree-shaken. The loader reports an unknown top-level key rather than silently dropping
5720
+ * it.
5623
5721
  *
5624
5722
  * ## Headless
5625
5723
  *
@@ -5664,18 +5762,6 @@ export declare const MATERIAL_KINDS: readonly ["pbr", "standard", "shader"];
5664
5762
  * @public
5665
5763
  */
5666
5764
  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
5765
  /**
5680
5766
  * The properties a `"pbr"` material declares. Every colour is sRGB; every factor is unitless.
5681
5767
  *
@@ -5699,7 +5785,7 @@ interface PbrMaterialDefinition {
5699
5785
  /** How strongly ambient occlusion darkens the surface, 0 to 1. */
5700
5786
  readonly occlusionStrength: number;
5701
5787
  /** How the alpha channel is interpreted. */
5702
- readonly alphaMode: MaterialAlphaModeName;
5788
+ readonly alphaMode: MaterialAlphaMode;
5703
5789
  /** The cutoff below which a `"mask"` material discards a fragment. */
5704
5790
  readonly alphaCutoff: number;
5705
5791
  /** Overall material alpha, 0 to 1. */
@@ -6364,15 +6450,18 @@ interface Renderer {
6364
6450
  */
6365
6451
  warmUp(materials: readonly MaterialAsset[]): void;
6366
6452
  /**
6367
- * Picks the object under one CSS pixel of the canvas, exactly, on the GPU
6453
+ * Picks the object under one pixel of the canvas, exactly, on the GPU
6368
6454
  * (`docs/architecture/07-rendering.md` §3).
6369
6455
  *
6370
6456
  * @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.
6457
+ * Coordinates are **backing-store pixels** — the canvas's `width`/`height`, the space
6458
+ * `Camera.worldToScreen` answers in — not CSS pixels; multiply a DOM event's `offsetX`/`offsetY`
6459
+ * by `devicePixelRatio` first. Picks are serialised per app: Lite's picker owns one set of staging
6460
+ * buffers and chains each call onto the previous one's promise. A headless app has no picker and
6461
+ * always misses.
6462
+ *
6463
+ * @param x - The backing-store pixel x, from the canvas's left edge.
6464
+ * @param y - The backing-store pixel y, from the canvas's top edge.
6376
6465
  * @param options - An entity filter.
6377
6466
  * @returns What was hit, or `null` for a miss.
6378
6467
  */
@@ -6457,6 +6546,17 @@ declare class RendererImpl implements Renderer {
6457
6546
  * @returns The surface, or `null` under the null engine.
6458
6547
  */
6459
6548
  get surface(): RenderSurface | null;
6549
+ /**
6550
+ * Destroys the GPU device the way a real loss would, so that recovery runs — for tests and probes.
6551
+ *
6552
+ * @remarks
6553
+ * Reached through `rendererInternals(app.renderer)`; a game never calls it. It throws when no
6554
+ * recovery strategy is enabled (`rendering.features.deviceLostRecovery` is off) or under the null
6555
+ * engine, which has no device to lose.
6556
+ *
6557
+ * @internal
6558
+ */
6559
+ forceDeviceLossForTesting(): void;
6460
6560
  /**
6461
6561
  * The offscreen render path, when the project declared `rendering.features.postProcessing`.
6462
6562
  *
@@ -6540,8 +6640,8 @@ declare class RendererImpl implements Renderer {
6540
6640
  * What the ADR actually measured makes the deadlock unnecessary. Lite stamps **every** PBR
6541
6641
  * material in the process with one `_buildGroup` singleton, and every Standard material with
6542
6642
  * 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
6643
+ * are four families to worry about, not one per asset". This warms the two families core can
6644
+ * produce, plus any material already in the cache, which reaches the ADR's outcome — a
6545
6645
  * mesh added later takes the synchronous rebuild path — with two degenerate triangles and no
6546
6646
  * ordering problem.
6547
6647
  *
@@ -6555,10 +6655,10 @@ declare class RendererImpl implements Renderer {
6555
6655
  */
6556
6656
  warmUp(materials: readonly MaterialAsset[]): void;
6557
6657
  /**
6558
- * Picks the object under one CSS pixel of the canvas.
6658
+ * Picks the object under one backing-store pixel of the canvas (see the interface's remarks).
6559
6659
  *
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.
6660
+ * @param x - The backing-store pixel x, from the canvas's left edge.
6661
+ * @param y - The backing-store pixel y, from the canvas's top edge.
6562
6662
  * @param options - An entity filter.
6563
6663
  * @returns What was hit, or `null` for a miss.
6564
6664
  */
@@ -6724,6 +6824,19 @@ declare class RendererImpl implements Renderer {
6724
6824
  */
6725
6825
  dispose(): void;
6726
6826
  }
6827
+ /**
6828
+ * Destroys a renderer's GPU device the way a real loss would, so that recovery runs — for tests and
6829
+ * probes that live outside `@ignifx/core` and may not import Babylon Lite (`CONSTITUTION.md` §3.4).
6830
+ *
6831
+ * @remarks
6832
+ * It throws when `rendering.features.deviceLostRecovery` is off, or under the null engine, which
6833
+ * has no device to lose.
6834
+ *
6835
+ * @param renderer - The app's renderer.
6836
+ *
6837
+ * @internal
6838
+ */
6839
+ export declare function forceRendererDeviceLossForTesting(renderer: Renderer): void;
6727
6840
  //#endregion
6728
6841
  //#region src/lite/camera.d.ts
6729
6842
  /**
@@ -7334,8 +7447,13 @@ export declare class Camera extends Component implements ComponentHooks {
7334
7447
  /**
7335
7448
  * Builds a world-space ray through a point on the canvas.
7336
7449
  *
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.
7450
+ * @remarks
7451
+ * Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
7452
+ * {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
7453
+ * CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
7454
+ *
7455
+ * @param x - The backing-store pixel x, from the canvas's left edge.
7456
+ * @param y - The backing-store pixel y, from the canvas's top edge.
7339
7457
  * @param out - The ray to fill; a fresh one is allocated when omitted.
7340
7458
  * @returns `out`, or `null` when the view-projection matrix is singular — a zero-sized viewport,
7341
7459
  * or a camera that is not attached.
@@ -7361,8 +7479,8 @@ export declare class Camera extends Component implements ComponentHooks {
7361
7479
  /**
7362
7480
  * The world-space point a canvas pixel maps to at a given distance along the view ray.
7363
7481
  *
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.
7482
+ * @param x - The backing-store pixel x, from the canvas's left edge (see {@link Camera.screenToRay}).
7483
+ * @param y - The backing-store pixel y, from the canvas's top edge.
7366
7484
  * @param distance - How far along the ray to travel, in metres.
7367
7485
  * @param out - Receives the point.
7368
7486
  * @returns `out`, or `null` when no ray could be built.
@@ -7410,10 +7528,10 @@ export declare class Camera extends Component implements ComponentHooks {
7410
7528
  * (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
7411
7529
  *
7412
7530
  * @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.
7531
+ * The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
7532
+ * the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
7533
+ * `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
7534
+ * raise.
7417
7535
  *
7418
7536
  * @example
7419
7537
  * ```ts
@@ -7524,13 +7642,13 @@ export declare class World implements WorldHost {
7524
7642
  */
7525
7643
  get onEntityDestroyed(): Signal<Entity>;
7526
7644
  /**
7527
- * Emitted when a scene instance finishes loading. Never fires before Phase 2.
7645
+ * Emitted when a scene instance finishes loading.
7528
7646
  *
7529
7647
  * @returns The signal.
7530
7648
  */
7531
7649
  get onSceneLoaded(): Signal<SceneInstance>;
7532
7650
  /**
7533
- * Emitted when a scene instance is unloaded. Never fires before Phase 2.
7651
+ * Emitted when a scene instance is unloaded.
7534
7652
  *
7535
7653
  * @returns The signal.
7536
7654
  */
@@ -9125,8 +9243,16 @@ interface FrameSample {
9125
9243
  /** How many entities and components were destroyed in this frame's flush. */
9126
9244
  destroyed: number;
9127
9245
  /**
9128
- * CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long and
9129
- * only filled in development builds.
9246
+ * CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long, and
9247
+ * filled only while the app is in development mode — every entry is `0` otherwise.
9248
+ *
9249
+ * @remarks
9250
+ * "Development mode" is `createApp({ mode })`, and nothing else. It is **not** the bundler's mode:
9251
+ * `mode` defaults to `"development"` and no ignifx tooling overrides it, so a `vite build` of a
9252
+ * game that never passes `mode` still records these timings. A project that wants them gone from
9253
+ * its shipped build passes `mode: "production"` itself — for example
9254
+ * `createApp({ mode: import.meta.env.PROD ? "production" : "development" })` — and a probe that
9255
+ * reads `cpuMs` then reports zeros.
9130
9256
  */
9131
9257
  readonly cpuMs: Float64Array;
9132
9258
  }
@@ -9192,8 +9318,10 @@ interface ProfileScope {
9192
9318
  */
9193
9319
  interface DiagnosticsOptions {
9194
9320
  /**
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`.
9321
+ * Whether the app runs in development mode. Per-phase CPU timings and
9322
+ * `performance.mark`/`measure` entries are only produced when it is `true`. Defaults to `false`
9323
+ * here; `createApp` passes `mode === "development"`, and that `mode` itself defaults to
9324
+ * `"development"` in every build — a bundler's production flag does not change it.
9197
9325
  */
9198
9326
  readonly development?: boolean;
9199
9327
  /**
@@ -9231,7 +9359,11 @@ export declare class Diagnostics {
9231
9359
  * them. Values are reset by {@link Diagnostics.beginFrame}.
9232
9360
  */
9233
9361
  readonly frame: FrameSample;
9234
- /** Whether per-phase timings and User Timing entries are being recorded. */
9362
+ /**
9363
+ * Whether per-phase timings and User Timing entries are being recorded — that is, whether the app
9364
+ * was created with `mode: "development"`, which is the default in every build. Read it before
9365
+ * trusting `FrameSample.cpuMs`.
9366
+ */
9235
9367
  readonly isDevelopment: boolean;
9236
9368
  /** How many frames the history can hold. */
9237
9369
  readonly historyCapacity: number;
@@ -9282,6 +9414,11 @@ export declare class Diagnostics {
9282
9414
  /**
9283
9415
  * Registers a subsystem's counter group.
9284
9416
  *
9417
+ * @remarks
9418
+ * A second registration of the same name is a mistake, not a merge, so it throws. A script that
9419
+ * cannot know whether it is the first instance to run — a gameplay counter shared by every enemy,
9420
+ * a group that survives a scene reload — asks for {@link Diagnostics.groupOrRegister} instead.
9421
+ *
9285
9422
  * @param name - The group name, unique within this app.
9286
9423
  * @param counterNames - The counter names, in the order their indices are assigned.
9287
9424
  * @returns The group, whose indices are resolved once with {@link DiagnosticsGroup.index}.
@@ -9296,6 +9433,33 @@ export declare class Diagnostics {
9296
9433
  * absence, not a failure (coding standards §5.5).
9297
9434
  */
9298
9435
  group(name: string): DiagnosticsGroup | null;
9436
+ /**
9437
+ * Looks a counter group up by name and registers it if no subsystem has yet — the idiom for code
9438
+ * that may run more than once (`docs/architecture/15-devtools-and-diagnostics.md` §3).
9439
+ *
9440
+ * @remarks
9441
+ * `registerGroup` throws `IGX-1503` on a duplicate name, which is right for an extension that
9442
+ * registers its group once at `register()` time and wrong for a script: a script's `awake` runs
9443
+ * once per instance, and a scene reload runs it again, so `group(name) ?? registerGroup(name, …)`
9444
+ * had to be written out by hand at every call site. This is that expression, with one difference
9445
+ * worth knowing: when the group already exists it is returned **as it was registered**, and
9446
+ * `counterNames` is ignored rather than merged — Lite-style counter arrays are indexed, and
9447
+ * growing one under a subsystem that already holds indices into it would silently renumber its
9448
+ * counters. A caller that then asks for a counter the first registration did not declare gets
9449
+ * `IGX-1504` from {@link DiagnosticsGroup.index}, which names the group and the counter.
9450
+ *
9451
+ * @param name - The group name.
9452
+ * @param counterNames - The counter names to register with, used only on the first call.
9453
+ * @returns The existing group, or the newly registered one.
9454
+ *
9455
+ * @example
9456
+ * ```ts
9457
+ * // In a Script's `awake`, which runs once per instance and again after a scene reload.
9458
+ * const counters = this.app.diagnostics.groupOrRegister("game", ["enemiesAlive", "wavesCleared"]);
9459
+ * this.enemiesAlive = counters.index("enemiesAlive");
9460
+ * ```
9461
+ */
9462
+ groupOrRegister(name: string, counterNames: readonly string[]): DiagnosticsGroup;
9299
9463
  /**
9300
9464
  * Opens a timing scope. In development builds it writes a `performance.mark`/`measure` pair that
9301
9465
  * shows up in browser profilers; outside development it is free
@@ -9314,6 +9478,141 @@ export declare class Diagnostics {
9314
9478
  profile(name: string): ProfileScope;
9315
9479
  }
9316
9480
  //#endregion
9481
+ //#region src/hot-reload/contract.d.ts
9482
+ /**
9483
+ * What a class asks the engine to do with its live instances when its module is replaced
9484
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5).
9485
+ *
9486
+ * @remarks
9487
+ * `"patch"` is the default and the one to reach for while iterating on logic: the live instances
9488
+ * keep their identity and every field value, and no lifecycle callback re-runs. `"recreate"` is
9489
+ * required when the *field layout* changes, because a patched instance keeps whatever properties
9490
+ * its constructor assigned and a renamed or added field would read `undefined`.
9491
+ *
9492
+ * @public
9493
+ */
9494
+ type HotReloadPolicy = "patch" | "recreate";
9495
+ /**
9496
+ * What one {@link HotReloadReport} describes: a prototype swap, a destroy-and-rebuild of component
9497
+ * instances, or a scene instance rebuilt from its file.
9498
+ *
9499
+ * @public
9500
+ */
9501
+ type HotReloadKind = "patch" | "recreate" | "scene";
9502
+ /**
9503
+ * The statics a component or script class may declare to steer its own hot reload
9504
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). Structural and optional, for the reason
9505
+ * given on `ComponentStatics`: a member declared on the `Component` base class would force the
9506
+ * `override` keyword on every `static hotReload = "recreate"` under `noImplicitOverride`.
9507
+ *
9508
+ * @example
9509
+ * ```ts
9510
+ * class Inventory extends Script.define({ slots: u32(4) }) {
9511
+ * static typeId = "mygame/Inventory";
9512
+ * static hotReload = "recreate" as const;
9513
+ * }
9514
+ * ```
9515
+ *
9516
+ * @public
9517
+ */
9518
+ interface HotReloadStatics {
9519
+ /** The policy for this class; defaults to `"patch"`. */
9520
+ readonly hotReload?: HotReloadPolicy;
9521
+ /**
9522
+ * Runs once on the **new** class after every live instance of it has been swapped or re-created,
9523
+ * with the class that was registered before as `previous`. It is the seam for class-level
9524
+ * transient state — a cache keyed off the old class, a static counter — and it is deliberately
9525
+ * not per instance: under `"patch"` the instances are the very same objects, so there is
9526
+ * nothing to copy across (PlayCanvas's `swap(old)` exists only because it re-instantiates), and
9527
+ * under `"recreate"` per-instance state is re-derived from the schema by design.
9528
+ *
9529
+ * @param previous - The class this one replaces.
9530
+ */
9531
+ onHotReload?(previous: ConcreteComponentType): void;
9532
+ }
9533
+ /**
9534
+ * One replaced module's worth of component classes, as the HMR client hands them over. Classes the
9535
+ * app has never seen are registered; classes whose `typeId` is already registered to a different
9536
+ * class are reloaded under their policy; classes that are already the registered ones are skipped.
9537
+ *
9538
+ * @public
9539
+ */
9540
+ interface HotReloadModule {
9541
+ /** Every component or script class the replaced module exports. */
9542
+ readonly types: readonly ConcreteComponentType[];
9543
+ }
9544
+ /**
9545
+ * What one hot reload did, for logs, tests, and the devtools overlay.
9546
+ *
9547
+ * @public
9548
+ */
9549
+ interface HotReloadReport {
9550
+ /** Which of the three operations this report describes. */
9551
+ readonly kind: HotReloadKind;
9552
+ /** The `typeId`s actually reloaded, in the order they were applied; empty when nothing changed. */
9553
+ readonly typeIds: readonly string[];
9554
+ /** How many live component instances were swapped or re-created, or entities rebuilt for a scene. */
9555
+ readonly instances: number;
9556
+ /** How long the operation took, in milliseconds. */
9557
+ readonly durationMs: number;
9558
+ /** Everything that threw on the way; the reload continues past each one. */
9559
+ readonly errors: readonly unknown[];
9560
+ }
9561
+ /**
9562
+ * The app's hot-reload service, reached as `app.hotReload`
9563
+ * (`docs/architecture/15-devtools-and-diagnostics.md` §5). It works with no Vite and no browser:
9564
+ * `@ignifx/vite-plugin` generates a client that calls {@link HotReloadHost.apply}, and a headless
9565
+ * test calls it directly.
9566
+ *
9567
+ * @example
9568
+ * ```ts
9569
+ * const report = app.hotReload.apply([{ types: [NextMover] }]);
9570
+ * console.log(report.kind, report.typeIds, report.instances);
9571
+ * ```
9572
+ *
9573
+ * @public
9574
+ */
9575
+ interface HotReloadHost {
9576
+ /**
9577
+ * Emitted once per completed {@link HotReloadHost.apply} or
9578
+ * {@link HotReloadHost.reloadScene} with the report that call returns.
9579
+ */
9580
+ readonly onApplied: SignalLike<HotReloadReport>;
9581
+ /**
9582
+ * Whether a changed scene file re-instantiates the live scene instances built from it, set with
9583
+ * `createApp({ hotReload: { reloadScenes: true } })`. Off by default, because rebuilding a scene
9584
+ * throws away everything the running game has done to it.
9585
+ */
9586
+ readonly reloadScenes: boolean;
9587
+ /**
9588
+ * Applies replaced component classes to the running app.
9589
+ *
9590
+ * @param modules - The replaced modules and the classes they export.
9591
+ * @returns What was reloaded.
9592
+ * @throws IgnifxError with code `IGX-0208` when called from inside a lifecycle callback, where a
9593
+ * half-swapped world would be observable.
9594
+ */
9595
+ apply(modules: readonly HotReloadModule[]): HotReloadReport;
9596
+ /**
9597
+ * Rebuilds one scene instance from its asset's current value, honouring the file's instance
9598
+ * overrides wherever their paths still resolve.
9599
+ *
9600
+ * @param instance - The instance to rebuild. It is unloaded and a fresh one takes its place.
9601
+ * @returns The new instance.
9602
+ * @throws IgnifxError with code `IGX-0209` when the instance was not built from a scene asset.
9603
+ */
9604
+ reloadScene(instance: SceneInstance): Promise<SceneInstance>;
9605
+ }
9606
+ /**
9607
+ * The `hotReload` section of `createApp`'s options.
9608
+ *
9609
+ * @public
9610
+ */
9611
+ interface HotReloadOptions {
9612
+ /** Sets {@link HotReloadHost.reloadScenes}. Defaults to `false`. */
9613
+ readonly reloadScenes?: boolean;
9614
+ }
9615
+ //#endregion
9317
9616
  //#region src/log/log-level.d.ts
9318
9617
  /**
9319
9618
  * Severity levels and the record shape the logging sinks receive
@@ -9400,10 +9699,15 @@ interface LogSink {
9400
9699
  * one numeric comparison. The rest parameter itself is still materialised by the JavaScript engine,
9401
9700
  * so per-frame call sites guard with {@link Logger.isEnabled} instead (coding standards §7).
9402
9701
  *
9702
+ * **A message is not a format string.** It is written to the sink verbatim and the extras are
9703
+ * appended beside it, the way `console.warn(message, ...data)` does; nothing substitutes into it, so
9704
+ * a `{placeholder}` token is printed literally. Pass values as extras
9705
+ * (`log.info("hero z:", z)`), never as tokens inside the message.
9706
+ *
9403
9707
  * @example
9404
9708
  * ```ts
9405
9709
  * const log = app.log.child("physics");
9406
- * log.info("stepping at {hz}Hz", 60);
9710
+ * log.info("stepping at 60 Hz");
9407
9711
  * if (log.isEnabled("debug")) {
9408
9712
  * log.debug("contacts", collectContacts());
9409
9713
  * }
@@ -9475,6 +9779,16 @@ interface Logger {
9475
9779
  * @returns The scoped logger.
9476
9780
  */
9477
9781
  child(scope: string): Logger;
9782
+ /**
9783
+ * Adds a second sink that receives every record this logger tree writes, alongside the one
9784
+ * `createApp({ logSink })` installed. Children share the list, so a sink added on `app.log` sees
9785
+ * `ctx.log` records too. This is how `@ignifx/devtools` fills its Console panel without the game
9786
+ * wiring anything.
9787
+ *
9788
+ * @param sink - The sink to add.
9789
+ * @returns A function that removes it again.
9790
+ */
9791
+ addSink(sink: LogSink): () => void;
9478
9792
  }
9479
9793
  /**
9480
9794
  * Options for {@link createLogger}.
@@ -9503,7 +9817,8 @@ interface LoggerOptions {
9503
9817
  * @example
9504
9818
  * ```ts
9505
9819
  * const log = createLogger({ sink: createConsoleSink(), level: "debug" });
9506
- * log.child("assets").warnOnce("missing-atlas", "No atlas for sprite {id}.");
9820
+ * // A message is not a format string — nothing substitutes into it. Pass values as extras.
9821
+ * log.child("assets").warnOnce("missing-atlas", "No atlas for sprite:", spriteId);
9507
9822
  * ```
9508
9823
  *
9509
9824
  * @public
@@ -9512,117 +9827,923 @@ export declare function createLogger(options: LoggerOptions): Logger;
9512
9827
  //#endregion
9513
9828
  //#region src/platform/platform.d.ts
9514
9829
  /**
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`.
9830
+ * `app.platform`: what the engine knows about the host it is running on
9831
+ * (`docs/architecture/14-platform-electron.md` §1). Extensions branch on it — the input extension to
9832
+ * decide whether pointer lock is worth offering, the renderer to size its budgets — and game code
9833
+ * rarely should.
9834
+ *
9835
+ * ## Decisions the documents left open
9836
+ *
9837
+ * - **Detection is a pure function of a `PlatformHost` record.** §1 says the service is
9838
+ * "populated at `createApp`" and nothing else. Reading the globals and *interpreting* them are
9839
+ * two different jobs, and only the first one needs a browser: `readPlatformHost` scrapes
9840
+ * `globalThis` and `detectPlatform` turns the result into a {@link PlatformInfo}. That is
9841
+ * what lets the whole of the interpretation — every operating system, every mobile heuristic — be
9842
+ * unit-tested under Node with a fabricated host.
9843
+ * - **`kind` is `"browser"` until something proves otherwise.** An Electron renderer *is* a browser
9844
+ * as far as the kernel can tell; guessing from the user agent would be worse than being honest.
9845
+ * `@ignifx/electron` detects its own preload bridge and calls
9846
+ * `platformInternals(app.platform).setKind("electron")`, which is the one supported mutation.
9847
+ * - **`webgpu` describes the adapter, not the device.** Babylon Lite's public `index.d.ts` (v1.27.0)
9848
+ * exposes neither the `GPUAdapter` nor the `GPUDevice` it acquired — `EngineContext` declares only
9849
+ * `surfaces`, `drawCallCount`, `gpuFrameTimeMs`, `useHighPrecisionMatrix` and `useFloatingOrigin`
9850
+ * — so reaching the engine's device would mean an assertion onto an undocumented `_device`
9851
+ * property. `createApp` asks `navigator.gpu` for a *second* adapter instead, which costs nothing
9852
+ * (an adapter is not a device) and reports what the hardware can do rather than what Lite asked
9853
+ * for. `features` and `limits` are therefore an upper bound on the running device's.
9854
+ * - **Every field is plain data.** `features` is a sorted string array and `limits` a number record,
9855
+ * not the live `GPUSupportedFeatures`/`GPUSupportedLimits` objects, so the whole record survives
9856
+ * `JSON.stringify` into a bug report or a devtools panel.
9520
9857
  */
9521
9858
  /**
9522
9859
  * Where an app is running.
9523
9860
  *
9861
+ * @public
9862
+ */
9863
+ type PlatformKind = "browser" | "electron" | "node";
9864
+ /**
9865
+ * Which operating system the host runs, as far as it will admit.
9866
+ *
9867
+ * @remarks
9868
+ * `"unknown"` is a real answer, not a failure: a locked-down browser that freezes its user agent
9869
+ * and exposes no `navigator.userAgentData` genuinely does not say, and code that branches on the
9870
+ * operating system has to have a default anyway.
9871
+ *
9872
+ * @public
9873
+ */
9874
+ type PlatformOs = "macos" | "windows" | "linux" | "ios" | "android" | "unknown";
9875
+ /**
9876
+ * Who made the GPU, as WebGPU reports it.
9877
+ *
9524
9878
  * @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"`.
9879
+ * Browsers deliberately blur these strings — most return an empty `architecture` and `device` on
9880
+ * the default, non-`unmaskHints` path — so treat every field as a hint for a bug report rather than
9881
+ * as something to branch on.
9882
+ *
9883
+ * @public
9884
+ */
9885
+ interface GpuAdapterInfo {
9886
+ /** The GPU vendor, `"apple"` or `"nvidia"`; `""` when the browser withholds it. */
9887
+ readonly vendor: string;
9888
+ /** The GPU family, `"metal-3"`; `""` when the browser withholds it. */
9889
+ readonly architecture: string;
9890
+ /** The specific device; `""` when the browser withholds it. */
9891
+ readonly device: string;
9892
+ /** A human-readable summary; `""` when the browser withholds it. */
9893
+ readonly description: string;
9894
+ }
9895
+ /**
9896
+ * What the host's WebGPU adapter offers.
9528
9897
  *
9529
9898
  * @public
9530
9899
  */
9531
- type PlatformKind = "browser" | "node";
9900
+ interface WebGpuInfo {
9901
+ /** Who made the adapter. */
9902
+ readonly adapterInfo: GpuAdapterInfo;
9903
+ /** The optional features the adapter supports, sorted ascending. */
9904
+ readonly features: readonly string[];
9905
+ /** The adapter's limits, by their WebGPU names. */
9906
+ readonly limits: Readonly<Record<string, number>>;
9907
+ }
9532
9908
  /**
9533
- * What the kernel knows about the host.
9909
+ * What the kernel knows about the host, reached as `app.platform`.
9534
9910
  *
9535
9911
  * @example
9536
9912
  * ```ts
9537
- * if (app.platform.kind === "browser") {
9538
- * document.title = "playing";
9913
+ * if (app.platform.isMobile) {
9914
+ * app.renderer.resolutionScale = 0.75;
9915
+ * }
9916
+ * if (app.platform.reducedMotion) {
9917
+ * disableScreenShake();
9539
9918
  * }
9540
9919
  * ```
9541
9920
  *
9542
9921
  * @public
9543
9922
  */
9544
9923
  interface PlatformInfo {
9545
- /** Whether the app runs in a document or in a bare JavaScript runtime. */
9924
+ /** Whether the app runs in a document, in an Electron renderer, or in a bare JavaScript runtime. */
9546
9925
  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).
9926
+ /** The operating system, or `"unknown"` when the host does not say. */
9927
+ readonly os: PlatformOs;
9928
+ /** `true` on a phone or a tablet. */
9929
+ readonly isMobile: boolean;
9930
+ /** `true` when the host implements the Pointer Lock API. */
9931
+ readonly hasPointerLock: boolean;
9932
+ /** `true` when the host implements the Gamepad API. */
9933
+ readonly hasGamepads: boolean;
9934
+ /** What WebGPU offers, or `null` in a headless app and on a host with no WebGPU. */
9935
+ readonly webgpu: WebGpuInfo | null;
9936
+ /** The host's BCP 47 language tag, `"en-AU"`. Never empty. */
9937
+ readonly locale: string;
9938
+ /** `true` when the user asked their system for reduced motion. */
9939
+ readonly reducedMotion: boolean;
9940
+ }
9941
+ /**
9942
+ * The raw host readings `detectPlatform` interprets. Every field is exactly one global read, so a
9943
+ * test can fabricate any host without touching `globalThis`.
9555
9944
  *
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.
9945
+ * @internal
9946
+ */
9947
+ interface PlatformHost {
9948
+ /** `true` when both a `document` and a `window` are reachable. */
9949
+ readonly hasDocument: boolean;
9950
+ /** `navigator.userAgent`, or `null`. */
9951
+ readonly userAgent: string | null;
9952
+ /** The deprecated `navigator.platform`, or `null`. */
9953
+ readonly navigatorPlatform: string | null;
9954
+ /** `navigator.userAgentData.platform`, or `null` on a browser that has no client hints. */
9955
+ readonly userAgentDataPlatform: string | null;
9956
+ /** `navigator.userAgentData.mobile`, or `null` on a browser that has no client hints. */
9957
+ readonly userAgentDataMobile: boolean | null;
9958
+ /** `navigator.maxTouchPoints`, `0` when the host has none. */
9959
+ readonly maxTouchPoints: number;
9960
+ /** `true` when the document implements pointer lock. */
9961
+ readonly hasPointerLock: boolean;
9962
+ /** `true` when the navigator implements the Gamepad API. */
9963
+ readonly hasGamepads: boolean;
9964
+ /** The BCP 47 language tag the host reports. */
9965
+ readonly locale: string;
9966
+ /** `true` when `(prefers-reduced-motion: reduce)` matches. */
9967
+ readonly reducedMotion: boolean;
9968
+ /** Node's `process.platform`, or `null` outside Node. */
9969
+ readonly processPlatform: string | null;
9970
+ }
9971
+ /**
9972
+ * The mutable `PlatformInfo` the app owns.
9973
+ *
9974
+ * @internal
9558
9975
  */
9976
+ declare class PlatformInfoImpl implements PlatformInfo {
9977
+ #private;
9978
+ /** The operating system. */
9979
+ readonly os: PlatformOs;
9980
+ /** `true` on a phone or a tablet. */
9981
+ readonly isMobile: boolean;
9982
+ /** `true` when the host implements pointer lock. */
9983
+ readonly hasPointerLock: boolean;
9984
+ /** `true` when the host implements the Gamepad API. */
9985
+ readonly hasGamepads: boolean;
9986
+ /** The host's BCP 47 language tag. */
9987
+ readonly locale: string;
9988
+ /** `true` when the user asked for reduced motion. */
9989
+ readonly reducedMotion: boolean;
9990
+ /**
9991
+ * Builds the record from one set of host readings.
9992
+ *
9993
+ * @param host - What `readPlatformHost` scraped, or what a test fabricated.
9994
+ */
9995
+ constructor(host: PlatformHost);
9996
+ /**
9997
+ * Where the app is running.
9998
+ *
9999
+ * @returns The host kind.
10000
+ */
10001
+ get kind(): PlatformKind;
10002
+ /**
10003
+ * What WebGPU offers.
10004
+ *
10005
+ * @returns The adapter report, or `null` in a headless app.
10006
+ */
10007
+ get webgpu(): WebGpuInfo | null;
10008
+ /**
10009
+ * Records that this browser is in fact an Electron renderer.
10010
+ *
10011
+ * @param kind - The host kind to report from now on.
10012
+ */
10013
+ setKind(kind: PlatformKind): void;
10014
+ /**
10015
+ * Records what the WebGPU adapter offered.
10016
+ *
10017
+ * @param webgpu - The adapter report, or `null` to clear it.
10018
+ */
10019
+ setWebGpu(webgpu: WebGpuInfo | null): void;
10020
+ }
9559
10021
  /**
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`.
10022
+ * Reaches the mutable half of `app.platform`, the way `rendererInternals` does for the renderer.
10023
+ * `@ignifx/electron` uses it to record that the browser it detected is an Electron renderer.
9563
10024
  *
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.
10025
+ * @param platform - The record, normally `app.platform`.
10026
+ * @returns The implementation.
10027
+ * @throws IgnifxError with code `IGX-0702` when the record was not created by this copy of
10028
+ * `@ignifx/core`.
9568
10029
  *
9569
10030
  * @example
9570
10031
  * ```ts
9571
- * ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });
10032
+ * platformInternals(app.platform).setKind("electron");
9572
10033
  * ```
9573
10034
  *
9574
- * @public
10035
+ * @internal
9575
10036
  */
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
- };
10037
+ export declare function platformInternals(platform: PlatformInfo): PlatformInfoImpl;
10038
+ //#endregion
10039
+ //#region src/storage/backend.d.ts
9590
10040
  /**
9591
- * The union of the frame phases.
10041
+ * The contract every storage backend implements, and the value shape backends persist
10042
+ * (`docs/architecture/14-platform-electron.md` §2). This module declares types only — no behaviour,
10043
+ * no imports — so that `@ignifx/electron` can implement the contract without depending on anything
10044
+ * else in the kernel, and so that {@link StorageBackend} can be quoted in full in a design review.
9592
10045
  *
9593
- * @public
10046
+ * The split of responsibilities is the whole point of the contract:
10047
+ *
10048
+ * - The `Storage` facade (`./storage.ts`) owns **policy**: it validates namespace and key syntax,
10049
+ * turns a JavaScript value into a {@link StoredValue} (canonical JSON text, or bytes), and turns a
10050
+ * {@link StoredValue} back into a value. A backend never sees a user object.
10051
+ * - A backend owns **persistence**: it stores opaque JSON text or opaque bytes under a
10052
+ * `(namespace, key)` pair, and reports failures as `IgnifxError`s from the storage code block.
10053
+ *
10054
+ * A backend that keeps those two rules is interchangeable with every other one, which is what makes
10055
+ * the same save file readable from the memory backend in a unit test, the IndexedDB backend in a
10056
+ * browser, and the Electron file-system backend on a desktop build.
9594
10057
  */
9595
- export type Phase = (typeof Phase)[keyof typeof Phase];
9596
10058
  /**
9597
- * Every phase in frame order, for loops that walk them all.
10059
+ * Which of the two representations a stored value uses.
10060
+ *
10061
+ * @remarks
10062
+ * `"json"` carries text produced by the facade's canonical `JSON.stringify`; `"bytes"` carries the
10063
+ * raw octets of a `Blob`, `ArrayBuffer`, or `Uint8Array` the caller handed to `set`. The kind is
10064
+ * stored alongside the payload — a backend that loses it cannot round-trip, because JSON text and
10065
+ * a UTF-8 byte array are indistinguishable once written.
9598
10066
  *
9599
10067
  * @public
9600
10068
  */
9601
- export declare const PHASES: readonly Phase[];
10069
+ type StoredValueKind = "json" | "bytes";
9602
10070
  /**
9603
- * The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
10071
+ * A value as a backend sees it: opaque JSON text, or opaque octets.
10072
+ *
10073
+ * @remarks
10074
+ * The two members are a discriminated union on their `kind`, so a backend switches once
10075
+ * and the compiler proves both arms are handled. Backends must round-trip both members exactly: the
10076
+ * `json` string that comes back from {@link StorageBackend.get} has to be the same string that went
10077
+ * into {@link StorageBackend.set}, and the `bytes` have to be byte-identical and the same length. A
10078
+ * backend may copy the bytes (IndexedDB's structured clone does) but must never alias the caller's
10079
+ * buffer after `set` resolves.
10080
+ *
10081
+ * @example
10082
+ * ```ts
10083
+ * const value: StoredValue = { kind: "json", json: '{"volume":0.8}' };
10084
+ * await backend.set("settings", "audio", value);
10085
+ * ```
9604
10086
  *
9605
10087
  * @public
9606
10088
  */
9607
- export declare const PHASE_NAMES: readonly string[];
10089
+ type StoredValue = {
10090
+ /** Discriminant: this value is JSON text. */
10091
+ readonly kind: "json";
10092
+ /** The canonical JSON text of the value. Never `undefined`, never empty. */
10093
+ readonly json: string;
10094
+ } | {
10095
+ /** Discriminant: this value is a byte array. */
10096
+ readonly kind: "bytes";
10097
+ /** The octets. May be empty. */
10098
+ readonly bytes: Uint8Array;
10099
+ };
9608
10100
  /**
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`.
10101
+ * Where `app.storage` actually puts things (`docs/architecture/14-platform-electron.md` §2).
10102
+ *
10103
+ * @remarks
10104
+ * **The contract.** Implementations may assume all of the following, because the `Storage` facade
10105
+ * guarantees them before every call:
10106
+ *
10107
+ * 1. `namespace` is a non-empty `/`-joined path of segments; each segment is 1–64 characters of
10108
+ * `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, or `-`, and no segment is `.` or `..`. A backend that maps
10109
+ * namespaces onto a hierarchy (directories, object stores) must encode each segment so that two
10110
+ * namespaces differing only in case cannot collide on a case-insensitive file system.
10111
+ * 2. `key` is 1–512 characters, contains no C0 or C1 control character, and is otherwise arbitrary
10112
+ * Unicode — including `/`, `..`, `:`, and characters Windows forbids in file names. Keys are
10113
+ * opaque: a backend never interprets a key's structure, and `keys(namespace, prefix)` is a plain
10114
+ * string-prefix filter, not a path walk.
10115
+ * 3. Namespaces are **scopes, not prefixes**: `get("saves", "a")` and `get("saves/coop", "a")` name
10116
+ * two different values, and neither appears in the other's `keys()` listing.
10117
+ *
10118
+ * Implementations must guarantee all of the following:
10119
+ *
10120
+ * 4. `get` resolves `null` for an absent key — absence is not an error.
10121
+ * 5. `set` replaces any existing value under the same `(namespace, key)`, whatever its kind, and
10122
+ * is atomic against a crash: a reader either sees the whole previous value or the whole new one,
10123
+ * never a partial write. `delete` on an absent key resolves without error.
10124
+ * 6. `keys` resolves the keys of one namespace, filtered by `prefix` when it is given, sorted
10125
+ * ascending with the default `Array.prototype.sort` comparison (UTF-16 code unit order). An
10126
+ * unknown namespace lists as `[]` rather than throwing.
10127
+ * 7. `clear` removes every key of one namespace and leaves other namespaces untouched. Clearing an
10128
+ * unknown namespace resolves without error.
10129
+ * 8. Every rejection is an `IgnifxError` carrying a code from the storage block: `IGX-1424` when the
10130
+ * host is out of quota, `IGX-1426` when a stored value cannot be read back, and `IGX-1425` for
10131
+ * every other backend failure, with the underlying failure as `cause`. Backends never reject with
10132
+ * a raw `DOMException` or a Node `SystemError`.
10133
+ * 9. Every method is safe to call concurrently. Two `set` calls on the same key may land in either
10134
+ * order, but neither may leave the store damaged.
9611
10135
  *
9612
10136
  * @example
9613
10137
  * ```ts
9614
- * class Spin extends Script {
9615
- * update(dt: number): void {
9616
- * // `dt` is the argument, never `app.time.deltaTime`, inside a callback.
9617
- * this.transform.rotate({ x: 0, y: 90 * dt, z: 0 });
9618
- * }
9619
- * }
10138
+ * const backend: StorageBackend = new MemoryStorageBackend();
10139
+ * await backend.set("saves", "slot1", { kind: "json", json: '{"level":3}' });
10140
+ * await backend.keys("saves"); // ["slot1"]
9620
10141
  * ```
9621
10142
  *
9622
10143
  * @public
9623
10144
  */
9624
- interface Time {
9625
- /** Scaled seconds since the previous frame; what `update` and `lateUpdate` receive. */
10145
+ interface StorageBackend {
10146
+ /**
10147
+ * A short, stable identifier for this backend — `"memory"`, `"file"`, `"indexeddb"`,
10148
+ * `"electron-file"`. It appears in error context so a failure names the store it came from.
10149
+ */
10150
+ readonly name: string;
10151
+ /**
10152
+ * Reads one value.
10153
+ *
10154
+ * @param namespace - The namespace path.
10155
+ * @param key - The key inside that namespace.
10156
+ * @returns The stored value, or `null` when the namespace has no such key.
10157
+ */
10158
+ get(namespace: string, key: string): Promise<StoredValue | null>;
10159
+ /**
10160
+ * Writes one value, replacing whatever was there.
10161
+ *
10162
+ * @param namespace - The namespace path, created on demand.
10163
+ * @param key - The key inside that namespace.
10164
+ * @param value - The JSON text or the octets to persist.
10165
+ * @returns A promise that settles once the value is durable.
10166
+ */
10167
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
10168
+ /**
10169
+ * Removes one value.
10170
+ *
10171
+ * @param namespace - The namespace path.
10172
+ * @param key - The key inside that namespace.
10173
+ * @returns A promise that settles once the value is gone; removing an absent key is a no-op.
10174
+ */
10175
+ delete(namespace: string, key: string): Promise<void>;
10176
+ /**
10177
+ * Lists the keys of one namespace.
10178
+ *
10179
+ * @param namespace - The namespace path.
10180
+ * @param prefix - When given, only keys that start with this string are returned.
10181
+ * @returns The matching keys, sorted ascending; `[]` for an unknown namespace.
10182
+ */
10183
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
10184
+ /**
10185
+ * Removes every value of one namespace.
10186
+ *
10187
+ * @param namespace - The namespace path.
10188
+ * @returns A promise that settles once the namespace is empty; an unknown namespace is a no-op.
10189
+ */
10190
+ clear(namespace: string): Promise<void>;
10191
+ /**
10192
+ * Releases whatever the backend holds open — an IndexedDB connection, a file handle, a bridge
10193
+ * subscription. Called from `app.dispose()`. Disposing twice is a no-op, and a backend that holds
10194
+ * nothing may omit the method entirely.
10195
+ */
10196
+ dispose?(): void;
10197
+ }
10198
+ //#endregion
10199
+ //#region src/storage/storage.d.ts
10200
+ /**
10201
+ * `app.storage`: the small, asynchronous key-value store a game keeps its settings, its save slots,
10202
+ * and its input rebindings in (`docs/architecture/14-platform-electron.md` §2).
10203
+ *
10204
+ * The facade owns policy and the backend owns persistence (`./backend.ts`). Everything a game sees
10205
+ * — namespaces, JSON canonicalization, `Blob` support, the error codes — lives here, once, so that
10206
+ * a save written under Node's memory backend in a unit test reads back identically from IndexedDB
10207
+ * in a browser and from the Electron bridge on a desktop build.
10208
+ *
10209
+ * ## Decisions the documents left open
10210
+ *
10211
+ * - **A namespace is a backend scope, not a key prefix.** §2 offers `namespace(name)` without
10212
+ * saying which. A scope is the stronger contract: `keys()` on `"saves"` cannot leak a key from
10213
+ * `"saves-old"`, a directory backend gets one directory per namespace for free, and clearing a
10214
+ * namespace is one operation rather than a scan. Nested namespaces join with `/`, so
10215
+ * `storage.namespace("saves").namespace("coop")` is the scope `"saves/coop"` — a *different*
10216
+ * scope from `"saves"`, whose keys it does not list.
10217
+ * - **`app.storage` itself is the namespace `"default"`.** Every backend call carries a namespace,
10218
+ * so the root needs a name rather than an empty string each backend would special-case.
10219
+ * - **`namespace(name)` is memoized.** Two calls with the same name return the same object, which
10220
+ * makes `app.storage.namespace("saves") === app.storage.namespace("saves")` true and keeps a
10221
+ * per-frame call from allocating.
10222
+ */
10223
+ /**
10224
+ * The store reached as `app.storage`, and as `app.storage.namespace(name)`.
10225
+ *
10226
+ * @remarks
10227
+ * Values are JSON, or binary: a `Blob`, an `ArrayBuffer`, or any typed array is stored as octets
10228
+ * and read back as a `Uint8Array`. Numbers inside JSON values are canonicalized the way scene files
10229
+ * canonicalize them (`docs/architecture/06-serialization-and-scene-format.md` §2), so writing the
10230
+ * same state twice produces the same bytes.
10231
+ *
10232
+ * Reads and writes are asynchronous on every backend, including the in-memory one, so that game
10233
+ * code written against a test app keeps working on IndexedDB.
10234
+ *
10235
+ * @example
10236
+ * ```ts
10237
+ * const settings = app.storage.namespace("settings");
10238
+ * await settings.set("audio", { master: 0.8, music: 0.5 });
10239
+ * const audio = await settings.get<{ master: number; music: number }>("audio");
10240
+ * ```
10241
+ *
10242
+ * @public
10243
+ */
10244
+ interface Storage {
10245
+ /**
10246
+ * Reads one value.
10247
+ *
10248
+ * @typeParam T - What the caller declares the key holds; unchecked, as for `JSON.parse`.
10249
+ * @param key - The key, 1–512 characters with no control characters.
10250
+ * @returns The value, or `null` when the key was never written.
10251
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1426` when the stored
10252
+ * value cannot be read back, or `IGX-1425` when the backend fails.
10253
+ */
10254
+ get<T>(key: string): Promise<T | null>;
10255
+ /**
10256
+ * Writes one value, replacing whatever was there.
10257
+ *
10258
+ * @typeParam T - The value's type.
10259
+ * @param key - The key, 1–512 characters with no control characters.
10260
+ * @param value - A JSON value, a `Blob`, an `ArrayBuffer`, or a typed array.
10261
+ * @returns A promise that settles once the value is durable.
10262
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1423` when the value has
10263
+ * no JSON form, `IGX-1424` when the host is out of quota, or `IGX-1425` when the backend fails.
10264
+ */
10265
+ set<T>(key: string, value: T): Promise<void>;
10266
+ /**
10267
+ * Removes one value.
10268
+ *
10269
+ * @param key - The key.
10270
+ * @returns A promise that settles once the value is gone. Deleting an absent key is a no-op.
10271
+ * @throws IgnifxError with code `IGX-1422` when the key is invalid, or `IGX-1425` when the
10272
+ * backend fails.
10273
+ */
10274
+ delete(key: string): Promise<void>;
10275
+ /**
10276
+ * Lists this namespace's keys.
10277
+ *
10278
+ * @param prefix - When given, only keys that start with this string are returned.
10279
+ * @returns The keys, sorted ascending. Keys of nested namespaces are not included.
10280
+ * @throws IgnifxError with code `IGX-1425` when the backend fails.
10281
+ */
10282
+ keys(prefix?: string): Promise<readonly string[]>;
10283
+ /**
10284
+ * Narrows to a child namespace — `"saves"`, `"settings"`, `"input-overrides"`.
10285
+ *
10286
+ * @param name - 1–64 characters of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`; not `.` or `..`.
10287
+ * @returns The child store, which shares this store's backend and sees none of its keys.
10288
+ * @throws IgnifxError with code `IGX-1421` when the name is not a legal namespace segment.
10289
+ */
10290
+ namespace(name: string): Storage;
10291
+ }
10292
+ /**
10293
+ * The `Storage` implementation: one object per namespace, all of them sharing one backend.
10294
+ *
10295
+ * @internal
10296
+ */
10297
+ declare class StorageImpl implements Storage {
10298
+ #private;
10299
+ /**
10300
+ * Builds a store.
10301
+ *
10302
+ * @param backend - Where values are persisted.
10303
+ * @param namespace - This store's namespace path. Defaults to `"default"`.
10304
+ */
10305
+ constructor(backend: StorageBackend, namespace?: string);
10306
+ /**
10307
+ * This store's namespace path.
10308
+ *
10309
+ * @returns The path, `"default"` at the root and `"saves/coop"` two levels down.
10310
+ */
10311
+ get namespacePath(): string;
10312
+ /**
10313
+ * The backend behind this store and every namespace derived from it.
10314
+ *
10315
+ * @returns The backend.
10316
+ */
10317
+ get backend(): StorageBackend;
10318
+ /**
10319
+ * Swaps the backend of this store and of every namespace already derived from it.
10320
+ *
10321
+ * @remarks
10322
+ * This is how `@ignifx/electron`'s renderer extension installs the file-system backend after
10323
+ * `createApp` has already built the default one: the `app.storage` object a script may already
10324
+ * hold keeps working and starts writing through the bridge.
10325
+ *
10326
+ * @param backend - The replacement backend.
10327
+ */
10328
+ setBackend(backend: StorageBackend): void;
10329
+ /**
10330
+ * Reads one value.
10331
+ *
10332
+ * @typeParam T - What the caller declares the key holds.
10333
+ * @param key - The key.
10334
+ * @returns The value, or `null`.
10335
+ */
10336
+ get<T>(key: string): Promise<T | null>;
10337
+ /**
10338
+ * Writes one value.
10339
+ *
10340
+ * @typeParam T - The value's type.
10341
+ * @param key - The key.
10342
+ * @param value - The value.
10343
+ * @returns A promise that settles once the value is durable.
10344
+ */
10345
+ set<T>(key: string, value: T): Promise<void>;
10346
+ /**
10347
+ * Removes one value.
10348
+ *
10349
+ * @param key - The key.
10350
+ * @returns A promise that settles once the value is gone.
10351
+ */
10352
+ delete(key: string): Promise<void>;
10353
+ /**
10354
+ * Lists this namespace's keys.
10355
+ *
10356
+ * @param prefix - An optional key prefix.
10357
+ * @returns The keys, sorted ascending.
10358
+ */
10359
+ keys(prefix?: string): Promise<readonly string[]>;
10360
+ /**
10361
+ * Narrows to a child namespace.
10362
+ *
10363
+ * @param name - The child segment.
10364
+ * @returns The child store.
10365
+ */
10366
+ namespace(name: string): Storage;
10367
+ }
10368
+ /**
10369
+ * Reaches the engine-owned half of a `Storage`, the way `rendererInternals` does for the
10370
+ * renderer. `@ignifx/electron` uses it to install its bridge backend after `createApp`.
10371
+ *
10372
+ * @param storage - The store, normally `app.storage`.
10373
+ * @returns The implementation.
10374
+ * @throws IgnifxError with code `IGX-0702` when the object was not created by this copy of
10375
+ * `@ignifx/core`.
10376
+ *
10377
+ * @example
10378
+ * ```ts
10379
+ * storageInternals(app.storage).setBackend(new ElectronFileStorageBackend(host));
10380
+ * ```
10381
+ *
10382
+ * @internal
10383
+ */
10384
+ export declare function storageInternals(storage: Storage): StorageImpl;
10385
+ //#endregion
10386
+ //#region src/tween/channel.d.ts
10387
+ /**
10388
+ * One tweened property: what kind of value it holds, where it started, where it is going, and how
10389
+ * to write it back (`docs/architecture/12-3d-toolkit.md` §4).
10390
+ *
10391
+ * A channel allocates its two endpoint buffers once, when the tween is created, and never again —
10392
+ * which is what keeps `Tweens.advance` allocation-free on the per-frame path (coding standards §7).
10393
+ */
10394
+ /**
10395
+ * The four value shapes a tween can interpolate.
10396
+ *
10397
+ * @public
10398
+ */
10399
+ export declare const TWEEN_VALUE_KINDS: readonly ["number", "vec2", "vec3", "quat"];
10400
+ /**
10401
+ * The union of {@link TWEEN_VALUE_KINDS}.
10402
+ *
10403
+ * @public
10404
+ */
10405
+ type TweenValueKind = (typeof TWEEN_VALUE_KINDS)[number];
10406
+ /**
10407
+ * A value a tween knows how to interpolate: a plain number, or an object with `x`/`y`(`/z`(`/w`))
10408
+ * components.
10409
+ *
10410
+ * @public
10411
+ */
10412
+ type TweenableValue = number | Vec2Like | Vec3Like | QuatLike;
10413
+ //#endregion
10414
+ //#region src/tween/easing.d.ts
10415
+ /**
10416
+ * A curve mapping normalized time to a normalized value. Custom curves have this shape.
10417
+ *
10418
+ * @param t - Normalized time in `[0, 1]`.
10419
+ * @returns The eased value; `0` at `t = 0` and `1` at `t = 1`, free to overshoot in between.
10420
+ *
10421
+ * @public
10422
+ */
10423
+ type EasingFunction = (t: number) => number;
10424
+ /**
10425
+ * Every named easing curve, keyed by the name `TweenOptions.ease` accepts.
10426
+ *
10427
+ * @example
10428
+ * ```ts
10429
+ * const halfway = EASINGS.cubicInOut(0.5); // 0.5
10430
+ * ```
10431
+ *
10432
+ * @public
10433
+ */
10434
+ export declare const EASINGS: Readonly<Record<string, EasingFunction>>;
10435
+ /**
10436
+ * The names {@link EASINGS} declares, in table order (coding standards §5.2 — an `as const` table
10437
+ * and the union derived from it, never an enum).
10438
+ *
10439
+ * @public
10440
+ */
10441
+ export declare const EASING_NAMES: readonly ["linear", "quadIn", "quadOut", "quadInOut", "cubicIn", "cubicOut", "cubicInOut", "sineInOut", "backOut", "elasticOut", "bounceOut"];
10442
+ /**
10443
+ * The union of the named easing curves.
10444
+ *
10445
+ * @public
10446
+ */
10447
+ type EasingName = (typeof EASING_NAMES)[number];
10448
+ /**
10449
+ * Resolves an `ease` option to the function a tween will call.
10450
+ *
10451
+ * @param ease - A name from {@link EASING_NAMES}, a custom curve, or `undefined` for `linear`.
10452
+ * @returns The curve, or `null` when the name is not one the table declares.
10453
+ *
10454
+ * @example
10455
+ * ```ts
10456
+ * const curve = resolveEase("cubicOut");
10457
+ * ```
10458
+ *
10459
+ * @public
10460
+ */
10461
+ export declare function resolveEase(ease: EasingName | EasingFunction | undefined): EasingFunction | null;
10462
+ //#endregion
10463
+ //#region src/tween/tween.d.ts
10464
+ /**
10465
+ * A running tween and the handle a game holds on to (`docs/architecture/12-3d-toolkit.md` §4).
10466
+ *
10467
+ * A tween is created by `app.tweens.to(...)`, advanced once per frame in `PostUpdate`, and dies
10468
+ * with the app. Everything it needs is allocated in the constructor: advancing one costs a few
10469
+ * multiplications per channel and nothing on the heap (coding standards §7).
10470
+ */
10471
+ /**
10472
+ * `loop: -1` means "repeat until stopped".
10473
+ *
10474
+ * @public
10475
+ */
10476
+ export declare const TWEEN_LOOP_FOREVER = -1;
10477
+ /**
10478
+ * What `app.tweens.to(...)` accepts.
10479
+ *
10480
+ * @public
10481
+ */
10482
+ interface TweenOptions {
10483
+ /** How long one cycle takes, in seconds. Must be finite and greater than zero. */
10484
+ readonly duration: number;
10485
+ /** The curve, by name or as a custom `(t) => number`. Defaults to `"linear"`. */
10486
+ readonly ease?: EasingName | EasingFunction;
10487
+ /** How long to wait before the first cycle starts, in seconds. Defaults to `0`. */
10488
+ readonly delay?: number;
10489
+ /** How many extra cycles to run; `-1` repeats forever. Defaults to `0` — one cycle. */
10490
+ readonly loop?: number;
10491
+ /** Whether every other cycle plays backwards. Defaults to `false`. */
10492
+ readonly yoyo?: boolean;
10493
+ /**
10494
+ * Whether the tween keeps running while `app.pause()` holds. A tween that does advances on
10495
+ * `time.unscaledDeltaTime`; every other tween advances on `time.deltaTime` and is frozen by a
10496
+ * pause. Defaults to `false`.
10497
+ */
10498
+ readonly updateWhenPaused?: boolean;
10499
+ /** Called once when the tween finishes on its own or through {@link Tween.complete}. */
10500
+ readonly onComplete?: () => void;
10501
+ }
10502
+ /**
10503
+ * A tween in flight.
10504
+ *
10505
+ * @remarks
10506
+ * Endpoints are latched when the delay elapses, not when the tween is created, so two tweens queued
10507
+ * on one property in the same frame chain rather than fight.
10508
+ *
10509
+ * @example
10510
+ * ```ts
10511
+ * const tween = app.tweens.to(entity.transform, { position: { x: 5, y: 0, z: 0 } }, {
10512
+ * duration: 1,
10513
+ * ease: "cubicInOut",
10514
+ * });
10515
+ * tween.onComplete.connect(() => app.log.info("arrived"));
10516
+ * ```
10517
+ *
10518
+ * @public
10519
+ */
10520
+ export declare class Tween {
10521
+ #private;
10522
+ /** Fires once when the tween finishes, with the tween itself. Never fires after `stop`. */
10523
+ readonly onComplete: Signal<Tween>;
10524
+ /** Whether the tween runs while the app is paused. */
10525
+ readonly updateWhenPaused: boolean;
10526
+ /**
10527
+ * Builds a tween. Games call `app.tweens.to(...)` instead.
10528
+ *
10529
+ * @param target - The object whose fields move.
10530
+ * @param props - The destination value of each field.
10531
+ * @param options - Duration, curve, delay, looping, and the completion callback.
10532
+ * @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
10533
+ * @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
10534
+ *
10535
+ * @internal
10536
+ */
10537
+ constructor(target: object, props: Readonly<Record<string, TweenableValue>>, options: TweenOptions);
10538
+ /**
10539
+ * The object being tweened, for `stopAllOf`.
10540
+ *
10541
+ * @returns The object being tweened, for `stopAllOf`.
10542
+ */
10543
+ get target(): object;
10544
+ /**
10545
+ * How far through the current cycle the tween is, in `[0, 1]`, after the yoyo reversal and before
10546
+ * the easing curve.
10547
+ *
10548
+ * @returns The normalized cycle time.
10549
+ */
10550
+ get progress(): number;
10551
+ /**
10552
+ * Whether the tween is still advancing.
10553
+ *
10554
+ * @returns Whether the tween is still advancing.
10555
+ */
10556
+ get isPlaying(): boolean;
10557
+ /**
10558
+ * Whether `pause` is holding the tween.
10559
+ *
10560
+ * @returns Whether `pause` is holding the tween.
10561
+ */
10562
+ get isPaused(): boolean;
10563
+ /**
10564
+ * Whether the tween has finished or been stopped and will never advance again.
10565
+ *
10566
+ * @returns Whether the tween has finished or been stopped and will never advance again.
10567
+ */
10568
+ get isDone(): boolean;
10569
+ /** Holds the tween where it is; `resume` picks it back up. */
10570
+ pause(): void;
10571
+ /** Releases a `pause`. */
10572
+ resume(): void;
10573
+ /**
10574
+ * Ends the tween where it stands, leaving the target at its current value. `onComplete` does not
10575
+ * fire.
10576
+ */
10577
+ stop(): void;
10578
+ /**
10579
+ * Jumps the target to the tween's end value, then finishes it. `onComplete` fires, exactly as it
10580
+ * would have on the last frame.
10581
+ */
10582
+ complete(): void;
10583
+ /**
10584
+ * Advances the tween by one frame's worth of time.
10585
+ *
10586
+ * @param dt - Seconds to advance by, already chosen for this tween's `updateWhenPaused`.
10587
+ * @returns `true` when the tween is done and should leave the list.
10588
+ *
10589
+ * @internal
10590
+ */
10591
+ advance(dt: number): boolean;
10592
+ }
10593
+ //#endregion
10594
+ //#region src/tween/tweens.d.ts
10595
+ /**
10596
+ * `app.tweens` (`docs/architecture/12-3d-toolkit.md` §4): the app-wide tween list, advanced once
10597
+ * per frame in `PostUpdate` on ignifx's own clock.
10598
+ *
10599
+ * Tweens live in core rather than in a toolkit because both toolkits use them, and because a tween
10600
+ * is a clock consumer like any other: it obeys `time.timeScale`, it is frozen by `app.pause()`
10601
+ * unless it opted out, and it dies when the app is disposed (ADR-0003).
10602
+ */
10603
+ /**
10604
+ * The destination value the tween should reach for one field, narrowed to the field's own shape.
10605
+ *
10606
+ * @remarks
10607
+ * `QuatLike` is tested before `Vec3Like` because a quaternion satisfies both: `{ x, y, z, w }` is
10608
+ * assignable to `{ x, y, z }`.
10609
+ *
10610
+ * @typeParam V - The field's declared type.
10611
+ *
10612
+ * @public
10613
+ */
10614
+ type TweenTargetValue<V> = V extends number ? number : V extends QuatLike ? QuatLike : V extends Vec3Like ? Vec3Like : V extends Vec2Like ? Vec2Like : never;
10615
+ /**
10616
+ * The destinations `app.tweens.to` accepts for a target: every numeric, `Vec2`, `Vec3`, or `Quat`
10617
+ * field of `T`, each one optional.
10618
+ *
10619
+ * @typeParam T - The target object's type.
10620
+ *
10621
+ * @example
10622
+ * ```ts
10623
+ * const props: TweenProps<Transform> = { position: { x: 1, y: 2, z: 3 } };
10624
+ * ```
10625
+ *
10626
+ * @public
10627
+ */
10628
+ type TweenProps<T> = { readonly [K in keyof T as T[K] extends TweenableValue ? K : never]?: TweenTargetValue<T[K]>; };
10629
+ /**
10630
+ * The app-wide tween list.
10631
+ *
10632
+ * @example
10633
+ * ```ts
10634
+ * app.tweens.to(entity.transform, { position: { x: 0, y: 3, z: 0 } }, {
10635
+ * duration: 0.6,
10636
+ * ease: "backOut",
10637
+ * yoyo: true,
10638
+ * loop: 1,
10639
+ * });
10640
+ * ```
10641
+ *
10642
+ * @public
10643
+ */
10644
+ interface Tweens {
10645
+ /** How many tweens are alive. */
10646
+ readonly count: number;
10647
+ /**
10648
+ * Starts a tween towards `props` and returns the handle.
10649
+ *
10650
+ * @typeParam T - The target object's type.
10651
+ * @param target - The object whose fields move. Any object with numeric or vector fields works.
10652
+ * @param props - The destination value of each field to move.
10653
+ * @param options - Duration, curve, delay, looping, and the completion callback.
10654
+ * @returns The running tween.
10655
+ * @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
10656
+ * @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
10657
+ */
10658
+ to<T extends object>(target: T, props: TweenProps<T>, options: TweenOptions): Tween;
10659
+ /** Stops every tween, without firing any `onComplete`. */
10660
+ stopAll(): void;
10661
+ /**
10662
+ * Stops every tween that moves one object.
10663
+ *
10664
+ * @param target - The object.
10665
+ * @returns How many tweens were stopped.
10666
+ */
10667
+ stopAllOf(target: object): number;
10668
+ }
10669
+ //#endregion
10670
+ //#region src/app/types.d.ts
10671
+ /**
10672
+ * The contracts the kernel and the runtime agree on: frame phases, the clock, systems, extensions,
10673
+ * services, coroutines, and the `App` surface a script sees through `this.app`
10674
+ * (`docs/architecture/01-lifecycle-and-time.md`, `03-scripting-and-components.md` §6–§7,
10675
+ * `04-extensions.md` §1).
10676
+ *
10677
+ * The module declares types and two frozen constant tables only — no classes and no behaviour — so
10678
+ * that the scene graph and the runtime can be written against it independently.
10679
+ */
10680
+ /**
10681
+ * The ordered frame phases (`docs/architecture/01-lifecycle-and-time.md` §3). The ordinals are the
10682
+ * order the frame function walks them in, and they index the per-phase CPU timings in
10683
+ * `FrameSample.cpuMs`.
10684
+ *
10685
+ * @remarks
10686
+ * `EndOfFrame` is ordinal `0` because the work it carries is drained at the *top* of the next
10687
+ * frame, before the clock advances; the name describes when the work was queued, the ordinal
10688
+ * describes when it runs.
10689
+ *
10690
+ * @example
10691
+ * ```ts
10692
+ * ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });
10693
+ * ```
10694
+ *
10695
+ * @public
10696
+ */
10697
+ export declare const Phase: {
10698
+ /** Deferred signal deliveries and end-of-frame systems, drained at the start of the next frame. */
10699
+ readonly EndOfFrame: 0;
10700
+ /** Input polling and asset delivery, before any script callback. */
10701
+ readonly PreUpdate: 1;
10702
+ /** The fixed-timestep simulation loop: `fixedUpdate`, physics, collision dispatch. */
10703
+ readonly FixedUpdate: 2;
10704
+ /** `update` on every enabled script, then coroutine resumption. */
10705
+ readonly Update: 3;
10706
+ /** Animation, state machines, and tweens, between `update` and `lateUpdate`. */
10707
+ readonly PostUpdate: 4;
10708
+ /** Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics. */
10709
+ readonly PreRender: 5;
10710
+ };
10711
+ /**
10712
+ * The union of the frame phases.
10713
+ *
10714
+ * @public
10715
+ */
10716
+ export type Phase = (typeof Phase)[keyof typeof Phase];
10717
+ /**
10718
+ * Every phase in frame order, for loops that walk them all.
10719
+ *
10720
+ * @public
10721
+ */
10722
+ export declare const PHASES: readonly Phase[];
10723
+ /**
10724
+ * The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
10725
+ *
10726
+ * @public
10727
+ */
10728
+ export declare const PHASE_NAMES: readonly string[];
10729
+ /**
10730
+ * The clock reached as `app.time` (`docs/architecture/01-lifecycle-and-time.md` §2). Every value is
10731
+ * in **seconds** unless its name ends in `Ms`.
10732
+ *
10733
+ * @example
10734
+ * ```ts
10735
+ * class Spin extends Script {
10736
+ * update(dt: number): void {
10737
+ * // `dt` is the argument, never `app.time.deltaTime`, inside a callback.
10738
+ * this.transform.rotate({ x: 0, y: 90 * dt, z: 0 });
10739
+ * }
10740
+ * }
10741
+ * ```
10742
+ *
10743
+ * @public
10744
+ */
10745
+ interface Time {
10746
+ /** Scaled seconds since the previous frame; what `update` and `lateUpdate` receive. */
9626
10747
  readonly deltaTime: number;
9627
10748
  /** Wall-clock frame delta after the {@link Time.maximumDeltaTime} clamp, unscaled. */
9628
10749
  readonly unscaledDeltaTime: number;
@@ -9662,7 +10783,11 @@ interface SystemContext {
9662
10783
  readonly time: Time;
9663
10784
  /** The phase currently running. */
9664
10785
  readonly phase: Phase;
9665
- /** Seconds elapsed: `time.deltaTime`, or `time.fixedDeltaTime` inside the fixed loop. */
10786
+ /**
10787
+ * Seconds elapsed: `time.deltaTime`, or `time.fixedDeltaTime` inside the fixed loop. Systems run
10788
+ * while the app is paused and `dt` is **not** zeroed then — only scripts are filtered by
10789
+ * `updateWhenPaused` — so a system that animates checks `time.paused` itself.
10790
+ */
9666
10791
  readonly dt: number;
9667
10792
  }
9668
10793
  /**
@@ -9855,7 +10980,7 @@ interface AppSettings {
9855
10980
  * @example
9856
10981
  * ```ts
9857
10982
  * app.onError.connect((report) => {
9858
- * app.log.error("{source} callback threw on {entity}", report.source, report.entity?.name ?? "-");
10983
+ * app.log.error(`${report.source} callback threw on ${report.entity?.name ?? "-"}`, report.error);
9859
10984
  * });
9860
10985
  * ```
9861
10986
  *
@@ -10062,14 +11187,31 @@ interface App {
10062
11187
  /** The `@ignifx/core` version this app was built from. */
10063
11188
  readonly version: string;
10064
11189
  /**
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`.
11190
+ * Where the app is running, what it is running on, and what its WebGPU adapter offers
11191
+ * (`docs/architecture/14-platform-electron.md` §1).
10067
11192
  */
10068
11193
  readonly platform: PlatformInfo;
11194
+ /**
11195
+ * The asynchronous key-value store settings, save games, and input rebindings live in
11196
+ * (`docs/architecture/14-platform-electron.md` §2). The backend is chosen from
11197
+ * {@link PlatformInfo.kind} — IndexedDB in a browser, memory under Node — unless `createApp` was
11198
+ * given one.
11199
+ */
11200
+ readonly storage: Storage;
10069
11201
  /** Unstable Babylon Lite escape hatch (`docs/architecture/00-overview.md` §3). */
10070
11202
  readonly lite: AppLiteHandles;
10071
11203
  /** The coroutine scheduler. */
10072
11204
  readonly coroutines: CoroutineHost;
11205
+ /**
11206
+ * The app-wide tween list (`docs/architecture/12-3d-toolkit.md` §4), advanced in `PostUpdate` on
11207
+ * ignifx's clock and used by both toolkits.
11208
+ */
11209
+ readonly tweens: Tweens;
11210
+ /**
11211
+ * Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5). The Vite
11212
+ * plugin's HMR client drives it in development; it works headlessly with no bundler at all.
11213
+ */
11214
+ readonly hotReload: HotReloadHost;
10073
11215
  /**
10074
11216
  * Makes component `typeId`s known to the serializer and the inspector
10075
11217
  * (`docs/architecture/03-scripting-and-components.md` §4).
@@ -10390,6 +11532,42 @@ interface Extension {
10390
11532
  */
10391
11533
  type SettingsInput = Readonly<Record<string, unknown>>;
10392
11534
  //#endregion
11535
+ //#region src/storage/node/file-backend.d.ts
11536
+ /**
11537
+ * Options accepted by {@link createFileStorageBackend}.
11538
+ *
11539
+ * @public
11540
+ */
11541
+ interface FileStorageOptions {
11542
+ /**
11543
+ * The root directory. It is created on first write, together with every namespace directory
11544
+ * under it. Under Electron this is `app.getPath("userData")`; in a test it is a temporary
11545
+ * directory.
11546
+ */
11547
+ readonly directory: string;
11548
+ }
11549
+ /**
11550
+ * Builds a storage backend over a directory (`docs/architecture/14-platform-electron.md` §5).
11551
+ *
11552
+ * @remarks
11553
+ * Node only: the factory loads `node:fs/promises` and rejects on a host that has none. It is what
11554
+ * `createApp({ storage: { directory } })` calls, and it is exported so that tooling — `ignifx bake`,
11555
+ * a future authoritative server — can build one without an app.
11556
+ *
11557
+ * @param options - The root directory.
11558
+ * @returns The backend.
11559
+ * @throws IgnifxError with code `IGX-1425` when the host exposes no `node:fs/promises`.
11560
+ *
11561
+ * @example
11562
+ * ```ts
11563
+ * const app = await createApp({ headless: true, storage: { directory: "./.saves" } });
11564
+ * await app.storage.namespace("saves").set("slot1", { level: 3 });
11565
+ * ```
11566
+ *
11567
+ * @public
11568
+ */
11569
+ export declare function createFileStorageBackend(options: FileStorageOptions): Promise<StorageBackend>;
11570
+ //#endregion
10393
11571
  //#region src/time/clock.d.ts
10394
11572
  /**
10395
11573
  * The wall clock the runtime reads (`docs/architecture/01-lifecycle-and-time.md` §2, §8). It is a
@@ -10504,10 +11682,17 @@ interface CreateAppOptions {
10504
11682
  readonly extensions?: readonly Extension[];
10505
11683
  /**
10506
11684
  * 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.
11685
+ * (`docs/architecture/04-extensions.md` §5). `@ignifx/vite-plugin` injects the resolved
11686
+ * `ignifx.config.ts` as the `import.meta.env.IGNIFX_CONFIG` literal, which a game passes straight
11687
+ * in here; tests and Electron tooling pass their own object instead.
10509
11688
  */
10510
11689
  readonly settings?: SettingsInput;
11690
+ /**
11691
+ * Where `app.storage` puts things (`docs/architecture/14-platform-electron.md` §2). Pass a
11692
+ * {@link StorageBackend} to install one, or `{ directory }` to write a directory tree under Node.
11693
+ * Defaults to IndexedDB in a browser and to an in-memory store everywhere else.
11694
+ */
11695
+ readonly storage?: StorageBackend | FileStorageOptions;
10511
11696
  /**
10512
11697
  * The asset service's construction options
10513
11698
  * (`docs/architecture/05-assets-and-loading.md` §7). The manifest normally arrives from
@@ -10531,8 +11716,17 @@ interface CreateAppOptions {
10531
11716
  readonly clock?: Clock;
10532
11717
  /**
10533
11718
  * `"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.
11719
+ * every rule `04-extensions.md` §2 relaxes in production.
11720
+ *
11721
+ * @remarks
11722
+ * Defaults to `"development"`, and **nothing else ever changes it**: neither `@ignifx/vite-plugin`
11723
+ * nor a template overrides it, so a production `vite build` of a game that passes no `mode` runs
11724
+ * in development mode — full error text, `performance.mark`/`measure` entries, and
11725
+ * `FrameSample.cpuMs` filled in. That is deliberate: the mode decides how the *engine* reports
11726
+ * itself, and only the game knows whether its shipped build wants that. Pass it from the bundler's
11727
+ * own flag to opt out — `mode: import.meta.env.PROD ? "production" : "development"`.
11728
+ *
11729
+ * @defaultValue `"development"`
10536
11730
  */
10537
11731
  readonly mode?: ErrorFormatMode;
10538
11732
  /** Where `app.log` writes. Defaults to the console sink. */
@@ -10542,6 +11736,12 @@ interface CreateAppOptions {
10542
11736
  * prints nothing at startup; pass `"debug"` to see the kernel's own diagnostics.
10543
11737
  */
10544
11738
  readonly logLevel?: LogThreshold;
11739
+ /**
11740
+ * Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5).
11741
+ * `app.hotReload.apply` always works; the only thing to configure is whether a changed scene file
11742
+ * rebuilds the live instances built from it.
11743
+ */
11744
+ readonly hotReload?: HotReloadOptions;
10545
11745
  }
10546
11746
  /**
10547
11747
  * Creates a game (`docs/architecture/00-overview.md` §1, `04-extensions.md` §2).
@@ -10839,7 +12039,8 @@ export declare const coreExtension: (options?: void) => Extension;
10839
12039
  *
10840
12040
  * @typeParam O - The options object the factory accepts. Defaults to `void` for an extension that
10841
12041
  * takes none.
10842
- * @param factory - Builds the extension descriptor from its options.
12042
+ * @param factory - Builds the extension descriptor from its options, which are `undefined` when the
12043
+ * game called the factory without an argument — default them (`(options = {})`) or read them as optional.
10843
12044
  * @returns A factory that may be called with no argument, in which case the options are `undefined`.
10844
12045
  *
10845
12046
  * @example
@@ -10858,7 +12059,7 @@ export declare const coreExtension: (options?: void) => Extension;
10858
12059
  *
10859
12060
  * @public
10860
12061
  */
10861
- export declare function defineExtension<O = void>(factory: (options: O) => Extension): (options?: O) => Extension;
12062
+ export declare function defineExtension<O = void>(factory: (options: O | undefined) => Extension): (options?: O) => Extension;
10862
12063
  //#endregion
10863
12064
  //#region src/ids/random-source.d.ts
10864
12065
  /**
@@ -11103,7 +12304,7 @@ type LiteShadowGenerator = ShadowGenerator;
11103
12304
  /**
11104
12305
  * The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
11105
12306
  *
11106
- * @internal
12307
+ * @public
11107
12308
  */
11108
12309
  export declare const SHADOW_TECHNIQUES: readonly ["esm", "pcf", "csm"];
11109
12310
  //#endregion
@@ -12040,7 +13241,7 @@ type LiteEnvironmentTextures = EnvironmentTextures;
12040
13241
  /**
12041
13242
  * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.
12042
13243
  *
12043
- * @internal
13244
+ * @public
12044
13245
  */
12045
13246
  export declare const TONE_MAPPING_NAMES: readonly ["none", "standard", "aces", "neutral"];
12046
13247
  //#endregion
@@ -12781,7 +13982,9 @@ export declare function createMaterialLoader(): AssetLoader<MaterialAsset>;
12781
13982
  *
12782
13983
  * ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
12783
13984
  *
12784
- * `loadGltf(engine, source)` (`index.d.ts` 6821) takes a URL, an `ArrayBuffer`, or a `Blob` and
13985
+ * `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
13986
+ * `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
13987
+ * `ArrayBuffer`, or a `Blob` and
12785
13988
  * resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
12786
13989
  * glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
12787
13990
  * `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
@@ -12852,8 +14055,8 @@ type LiteSkeleton = Skeleton;
12852
14055
  * `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
12853
14056
  * install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
12854
14057
  * 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.
14058
+ * ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
14059
+ * `Animator` is what plays them.
12857
14060
  *
12858
14061
  * ## Instance counting
12859
14062
  *
@@ -12923,9 +14126,9 @@ export declare class ModelAsset {
12923
14126
  * The clips the file declared, stripped from the container so Lite never ticks them.
12924
14127
  *
12925
14128
  * @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.
14129
+ * Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
14130
+ * they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
14131
+ * are read-only metadata: nothing here advances or re-binds them.
12929
14132
  *
12930
14133
  * @beta
12931
14134
  */
@@ -12998,8 +14201,8 @@ export declare class ModelAsset {
12998
14201
  * priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
12999
14202
  *
13000
14203
  * 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
14204
+ * resolve those relative URLs itself, which it can only do when it did the fetching. This loader
14205
+ * loads the container from bytes either way and therefore supports self-contained `.gltf` files and
13003
14206
  * `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
13004
14207
  * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
13005
14208
  * three-line change whenever a project needs it.
@@ -13394,10 +14597,11 @@ export declare class MeshAsset {
13394
14597
  * - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
13395
14598
  * `Mesh.id` strings (`lib/render/lights-ubo.js`), and §2.2 maps `Light.includeOnly` onto them
13396
14599
  * 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.
14600
+ * - **`materials` beyond the first is accepted and ignored.** §2.3 says "one per submesh", but
14601
+ * Lite's `Mesh.material` is a single value and Lite has no submesh material list in 1.27.0, so
14602
+ * there is nothing for the extra entries to drive. The field keeps its array shape so files do
14603
+ * not have to change if submeshes land; the renderer uses index 0, or the default material when
14604
+ * the array is empty.
13401
14605
  *
13402
14606
  * ## Headless
13403
14607
  *
@@ -13524,8 +14728,8 @@ export declare class Model extends Component implements ComponentHooks {
13524
14728
  * The clips the file declared.
13525
14729
  *
13526
14730
  * @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).
14731
+ * Unstable: these are Lite's own animation groups, and core does not advance them
14732
+ * (ADR-0003 — `@ignifx/3d`'s `Animator` owns playback).
13529
14733
  *
13530
14734
  * @returns The clips, in load order.
13531
14735
  *
@@ -13614,8 +14818,8 @@ export declare class Model extends Component implements ComponentHooks {
13614
14818
  * neither is inspectable without extra tooling. Three optional records with an `order` each is the
13615
14819
  * simplest shape that round-trips through `encodeProps`/`decodeProps` unchanged, shows up in the
13616
14820
  * 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.
14821
+ * cost is that a fourth effect would add a fourth record rather than a new list entry; that is a
14822
+ * schema addition, which the format already tolerates.
13619
14823
  *
13620
14824
  * ## It needs `rendering.features.postProcessing`, declared at app start
13621
14825
  *
@@ -13706,6 +14910,12 @@ interface ImageProcessingEffectSettings {
13706
14910
  * One instance of a post-process chain, attached to the main camera's entity
13707
14911
  * (`docs/architecture/07-rendering.md` §2.7).
13708
14912
  *
14913
+ * @remarks
14914
+ * The stack may be attached and configured either **before** or after `app.start()`. Before start
14915
+ * the chain's frame-graph tasks are appended and recorded by the scene registration `start()` runs;
14916
+ * after start they are recorded on the spot. Either way the first frame the canvas presents already
14917
+ * carries the effects.
14918
+ *
13709
14919
  * @example
13710
14920
  * ```ts
13711
14921
  * cameraEntity.addComponent(PostProcessStack, {
@@ -13744,6 +14954,13 @@ export declare class PostProcessStack extends Component implements ComponentHook
13744
14954
  * Builds the chain the first time any effect is enabled, and switches individual effects on and
13745
14955
  * off after that. The `PreRender` system calls it.
13746
14956
  *
14957
+ * @remarks
14958
+ * It is also called once by `app.start()`, through `renderer.syncBeforeRegister`, which is what
14959
+ * makes a stack configured **before** `start()` work: at that point the scene's frame graph has
14960
+ * not been built, so the chain appends its tasks and lets `registerScene` record them
14961
+ * (`PostProcessChain`'s `isFrameGraphBuilt`). Recording them early instead binds a scene colour
14962
+ * that no task has allocated yet and Lite rejects the whole frame with error 107.
14963
+ *
13747
14964
  * @param renderer - The rendering service, for the engine and the scene.
13748
14965
  *
13749
14966
  * @internal
@@ -14473,8 +15690,8 @@ export declare function optional<T>(inner: FieldDefinition<T>, options?: FieldOp
14473
15690
  * project settings does not silently repoint existing files
14474
15691
  * (`docs/architecture/06-serialization-and-scene-format.md` §3).
14475
15692
  *
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.
15693
+ * The field's value is a read-only array of names. The kernel's `LayerMask` satisfies the same
15694
+ * structural shape, so a component may hold either.
14478
15695
  *
14479
15696
  * @param defaultValue - The names a new component starts with; defaults to empty.
14480
15697
  * @param options - Inspector and serializer metadata.
@@ -14708,5 +15925,196 @@ export declare function waitUntil(predicate: () => boolean): WaitInstruction;
14708
15925
  */
14709
15926
  export declare function waitWhile(predicate: () => boolean): WaitInstruction;
14710
15927
  //#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 };
15928
+ //#region src/storage/memory-backend.d.ts
15929
+ /**
15930
+ * The in-memory storage backend: the default for a headless app, and the one every unit test in the
15931
+ * engine runs against (`docs/architecture/14-platform-electron.md` §2, §5).
15932
+ *
15933
+ * It is the reference implementation of `./backend.ts`: nothing here is a shortcut for being
15934
+ * in-process. Values are copied in and out, so a caller that mutates the `Uint8Array` it wrote
15935
+ * cannot reach the store; namespaces are separate maps rather than prefixed keys; and every method
15936
+ * is asynchronous even though none of them needs to be, because game code written against this
15937
+ * backend has to keep working on IndexedDB.
15938
+ */
15939
+ /**
15940
+ * A store that lives as long as the app does.
15941
+ *
15942
+ * @example
15943
+ * ```ts
15944
+ * const app = await createApp({ storage: new MemoryStorageBackend() });
15945
+ * ```
15946
+ *
15947
+ * @public
15948
+ */
15949
+ export declare class MemoryStorageBackend implements StorageBackend {
15950
+ #private;
15951
+ /** The identifier that appears in error context. */
15952
+ readonly name = "memory";
15953
+ /**
15954
+ * Reads one value.
15955
+ *
15956
+ * @param namespace - The namespace path.
15957
+ * @param key - The key.
15958
+ * @returns A copy of the stored value, or `null`.
15959
+ */
15960
+ get(namespace: string, key: string): Promise<StoredValue | null>;
15961
+ /**
15962
+ * Writes one value.
15963
+ *
15964
+ * @param namespace - The namespace path, created on demand.
15965
+ * @param key - The key.
15966
+ * @param value - The value to copy in.
15967
+ * @returns A promise that settles once the value is stored.
15968
+ */
15969
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
15970
+ /**
15971
+ * Removes one value.
15972
+ *
15973
+ * @param namespace - The namespace path.
15974
+ * @param key - The key.
15975
+ * @returns A promise that settles once the value is gone.
15976
+ */
15977
+ delete(namespace: string, key: string): Promise<void>;
15978
+ /**
15979
+ * Lists one namespace's keys.
15980
+ *
15981
+ * @param namespace - The namespace path.
15982
+ * @param prefix - An optional key prefix.
15983
+ * @returns The matching keys, sorted ascending.
15984
+ */
15985
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
15986
+ /**
15987
+ * Empties one namespace.
15988
+ *
15989
+ * @param namespace - The namespace path.
15990
+ * @returns A promise that settles once the namespace is empty.
15991
+ */
15992
+ clear(namespace: string): Promise<void>;
15993
+ /** Drops every namespace. */
15994
+ dispose(): void;
15995
+ }
15996
+ //#endregion
15997
+ //#region src/storage/names.d.ts
15998
+ /**
15999
+ * The syntax rules `app.storage` enforces on namespaces and keys before a backend ever sees them
16000
+ * (`docs/architecture/14-platform-electron.md` §2), and the reasons they are as narrow as they are.
16001
+ *
16002
+ * A **namespace** ends up as a directory on disk and as part of a compound IndexedDB key, so its
16003
+ * alphabet has to survive every file system ignifx runs on: it is deliberately small, and the
16004
+ * validator refuses the two names — `.` and `..` — that mean something else to a path resolver. A
16005
+ * **key** is opaque: it may hold anything a game wants to name a save slot, including `/`, `..`,
16006
+ * `:` and characters Windows forbids, because backends encode keys rather than resolve them
16007
+ * (`./file-names.ts`). All a key may not be is empty, unreasonably long, or full of control
16008
+ * characters that would make a listing unreadable.
16009
+ */
16010
+ /**
16011
+ * The namespace `app.storage` itself reads and writes before `namespace(name)` is called.
16012
+ *
16013
+ * @remarks
16014
+ * Every backend call carries a namespace, so the root storage needs a name of its own rather than
16015
+ * an empty string that each backend would have to special-case. `"default"` is a legal namespace
16016
+ * name, which means a game that writes `app.storage.namespace("default")` reaches the same values —
16017
+ * intentionally, since the two are the same store.
16018
+ *
16019
+ * @public
16020
+ */
16021
+ export declare const DEFAULT_STORAGE_NAMESPACE = "default";
16022
+ /**
16023
+ * The longest one segment of a namespace path may be.
16024
+ *
16025
+ * @public
16026
+ */
16027
+ export declare const NAMESPACE_SEGMENT_MAX_LENGTH = 64;
16028
+ /**
16029
+ * The longest a storage key may be.
16030
+ *
16031
+ * @remarks
16032
+ * 512 UTF-16 code units is comfortably below the ~255 *byte* file-name limit once percent-encoding
16033
+ * has expanded the key, which is why the file backend hashes nothing and truncates nothing: a key
16034
+ * that passes this check always encodes to a name a file system accepts.
16035
+ *
16036
+ * @public
16037
+ */
16038
+ export declare const STORAGE_KEY_MAX_LENGTH = 512;
16039
+ //#endregion
16040
+ //#region src/storage/web/indexeddb-backend.d.ts
16041
+ /**
16042
+ * A store backed by the browser's IndexedDB.
16043
+ *
16044
+ * @example
16045
+ * ```ts
16046
+ * const app = await createApp({ canvas, storage: new IndexedDbStorageBackend() });
16047
+ * ```
16048
+ *
16049
+ * @public
16050
+ */
16051
+ export declare class IndexedDbStorageBackend implements StorageBackend {
16052
+ #private;
16053
+ /** The identifier that appears in error context. */
16054
+ readonly name = "indexeddb";
16055
+ /**
16056
+ * Reads one value.
16057
+ *
16058
+ * @param namespace - The namespace path.
16059
+ * @param key - The key.
16060
+ * @returns The value, or `null`.
16061
+ */
16062
+ get(namespace: string, key: string): Promise<StoredValue | null>;
16063
+ /**
16064
+ * Writes one value.
16065
+ *
16066
+ * @param namespace - The namespace path.
16067
+ * @param key - The key.
16068
+ * @param value - The value.
16069
+ * @returns A promise that settles once the transaction commits.
16070
+ */
16071
+ set(namespace: string, key: string, value: StoredValue): Promise<void>;
16072
+ /**
16073
+ * Removes one value.
16074
+ *
16075
+ * @param namespace - The namespace path.
16076
+ * @param key - The key.
16077
+ * @returns A promise that settles once the transaction commits.
16078
+ */
16079
+ delete(namespace: string, key: string): Promise<void>;
16080
+ /**
16081
+ * Lists one namespace's keys.
16082
+ *
16083
+ * @param namespace - The namespace path.
16084
+ * @param prefix - An optional key prefix.
16085
+ * @returns The matching keys, in ascending order.
16086
+ */
16087
+ keys(namespace: string, prefix?: string): Promise<readonly string[]>;
16088
+ /**
16089
+ * Empties one namespace.
16090
+ *
16091
+ * @param namespace - The namespace path.
16092
+ * @returns A promise that settles once the transaction commits.
16093
+ */
16094
+ clear(namespace: string): Promise<void>;
16095
+ /** Closes the connection. The next call opens a new one. */
16096
+ dispose(): void;
16097
+ }
16098
+ //#endregion
16099
+ //#region src/tween/tween-system.d.ts
16100
+ /**
16101
+ * The `PostUpdate` system that advances `app.tweens` (`docs/architecture/01-lifecycle-and-time.md`
16102
+ * §3 step 5, `12-3d-toolkit.md` §4).
16103
+ *
16104
+ * `PostUpdate` is where every clock consumer in ignifx advances, so a `lateUpdate` and the render
16105
+ * sync both see the value a tween wrote in the same frame it wrote it.
16106
+ */
16107
+ /**
16108
+ * The `PostUpdate` order the tween system runs at.
16109
+ *
16110
+ * @remarks
16111
+ * `-100` puts tweens **before** the toolkits' animation systems, which register at `0`
16112
+ * (`@ignifx/2d`) and `10` (`@ignifx/3d`): a tween that drives an `Animator` parameter or a
16113
+ * material property is read by the animation that runs after it, in the same frame.
16114
+ *
16115
+ * @public
16116
+ */
16117
+ export declare const TWEEN_SYSTEM_ORDER = -100;
16118
+ //#endregion
16119
+ 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, 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
16120
  //# sourceMappingURL=index.d.ts.map