@threenative/core 0.3.2 → 0.3.4

package/dist/{game-XGrTzapq.d.ts → game-CljaDv4D.d.ts}

@@ -1,7 +1,7 @@
-import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-kyoF7JlJ.js';
-import { h as IFramePhaseSample, i as IPipelineCensus, I as IRendererLike, a6 as IRendererOptions, g as IFrameBudgetWindow, e as IFrameBudgetOptions } from './renderer-C6hqZpoG.js';
+import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-CqvE429w.js';
+import { F as FramePassKind, K as IRenderPassSample, n as IFramePhaseSample, o as IPipelineCensus, I as IRendererLike, as as IRendererOptions, a as IFrameBudgetWindow, j as IFrameBudgetOptions } from './renderer-CfsS2hxi.js';
 import { Vector2, Vector3, Object3D, Camera, Intersection, Scene as Scene$1 } from 'three';
-import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-BLVijiUJ.js';
+import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-DDmC_VVF.js';
 import { StoreApi } from 'zustand/vanilla';
 
 type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
@@ -101,6 +101,23 @@ interface IThreeNativeModelPassesConfig {
 }
 /** Model optimization options for the asset compile step; `"none"` ships sources verbatim. */
 interface IThreeNativeModelsConfig {
+    /**
+     * Lossless scene-graph compaction: flatten empty transform chains, join sibling primitives
+     * that share a material, and batch a mesh several nodes reuse as `EXT_mesh_gpu_instancing`.
+     *
+     * On by default; `false` ships the scene graph as authored. A node matching `protectedPattern`,
+     * named in `protectedNames`, targeted by an animation or a skin joint is never merged or
+     * instanced, so an exact-name lookup or a bone-driven node survives.
+     */
+    readonly compact?: boolean | {
+        readonly flatten?: boolean;
+        readonly instance?: boolean | {
+            readonly min?: number;
+        };
+        readonly join?: boolean;
+        readonly protectedNames?: readonly string[];
+        readonly protectedPattern?: string;
+    };
     /** Standard glTF TEXCOORD_1 atlas generation for offline static-light assets. */
     readonly lightmap?: {
         readonly atlasSize: number;
@@ -167,6 +184,113 @@ interface IThreeNativeModelsConfig {
         readonly simplifyRatio?: number;
     };
 }
+/** Quality policy for automatic discrete LOD; it picks the projected pixel-error budget. */
+type ThreeNativeLodPreset = "aggressive" | "balanced" | "quality";
+/** What the `minTriangles` pre-filter is measured against. */
+type ThreeNativeLodMinTrianglesScope = "primitive" | "asset";
+/** Generation knobs shared by every preset. All are ceilings or filters, not promises. */
+interface IThreeNativeLodGenerationConfig {
+    /**
+     * Increasing geometric-error targets in normalized mesh-extent units; 1–16 positive finite
+     * numbers that strictly increase. Default `[0.002, 0.006, 0.02, 0.06]`. Each is simplified from
+     * LOD0 independently and a target that cannot reduce is dropped.
+     */
+    readonly errorTargets?: readonly number[];
+    /** Levels in the chain **including LOD0**; integer 1–8, default 4. `1` emits nothing derived. */
+    readonly maxLevels?: number;
+    /**
+     * Fraction of its predecessor's triangles a derived level must save to be kept; finite in
+     * `[0, 1)`, default `0.2`. This is the benefit gate — a mesh that cannot reach it is skipped
+     * with `insufficient-reduction`, which is a normal outcome, not an error.
+     */
+    readonly minSaving?: number;
+    /**
+     * Cheap pre-filter floor in triangles; positive integer, default `128`. It only avoids
+     * clearly-pointless work (the simplifier's fixed per-call cost); `minSaving` is the real gate.
+     */
+    readonly minTriangles?: number;
+    /**
+     * What `minTriangles` is measured against; `"primitive"` or `"asset"`, default `"asset"`. The
+     * asset scope measures the whole model, so a model split into many small primitives is still
+     * eligible on its total.
+     */
+    readonly minTrianglesScope?: ThreeNativeLodMinTrianglesScope;
+    /**
+     * Opt-in far rung that joins a mesh's same-material primitives into one draw per material group.
+     * Default `false`: with no option the cook is byte-identical to today. A join never crosses a
+     * material, never touches a skinned, morph-target or animated node, and never leaves the mesh's
+     * own node, so authored LOD0, node identity, per-node visibility, picking and transforms are
+     * untouched; the joined geometry is an additional far rung beside LOD0.
+     */
+    readonly join?: boolean;
+}
+/** Screen-space selection knobs. */
+interface IThreeNativeLodRuntimeConfig {
+    /** Projected geometric-error budget in raster pixels; positive finite. Default by preset. */
+    readonly maxPixelError?: number;
+    /** Fraction in `[0, 0.5)`, default 0.15, that stabilizes coarsening at a boundary. */
+    readonly hysteresis?: number;
+}
+/** A partial override for one asset; nested objects overlay, they never replace. */
+interface IThreeNativeLodOverride {
+    readonly enabled?: boolean;
+    readonly generation?: IThreeNativeLodGenerationConfig;
+    readonly preset?: ThreeNativeLodPreset;
+    readonly runtime?: IThreeNativeLodRuntimeConfig;
+}
+/**
+ * Automatic discrete LOD policy. `{}` resolves to enabled/balanced and any explicit block turns
+ * generation on; `false` and `{ enabled: false }` are equivalent absolute kill switches that no
+ * per-asset override can re-enable. Overrides are keyed by canonical project-relative source asset
+ * (`/` separators).
+ *
+ * Omission currently bakes nothing: the default-on front door opens only after the qualification
+ * phase passes. Until then `assets.lod: {}` is the opt-in that resolves to enabled/balanced.
+ */
+interface IThreeNativeLodConfig {
+    readonly enabled?: boolean;
+    readonly generation?: IThreeNativeLodGenerationConfig;
+    readonly overrides?: Readonly<Record<string, boolean | IThreeNativeLodOverride>>;
+    readonly preset?: ThreeNativeLodPreset;
+    readonly runtime?: IThreeNativeLodRuntimeConfig;
+}
+/** One measured byte ceiling on a produced artifact, and what crossing it does. */
+interface IThreeNativeArtifactBudgetLimit {
+    /** Bytes, exclusive: a build measuring exactly the limit is inside it. */
+    readonly limit: number;
+    /** `"error"` refuses the build and keeps the previous artifact; `"warn"` prints and publishes. */
+    readonly severity: "error" | "warn";
+}
+/**
+ * Runtime ceilings a profile wants every playtest of the artifact it builds to hold.
+ *
+ * The fields are the playtest harness's own `assert.performance` fields, one name for one meaning:
+ * a budget declared here is merged into each scenario's performance assertion, so a budget and a
+ * scenario bound the same number instead of two vocabularies for one measurement. Spelled out
+ * rather than imported — the harness runs against plain Three.js with no dependency on this
+ * package, and core must not invert that. A closed key list validated in both places is the price;
+ * `create-threenative/__tests__/build-report.spec.ts` fails if the two lists drift.
+ */
+interface IThreeNativePerformanceBudget {
+    /** Per-pass draw-call ceilings, keyed by pass kind: main, shadow, reflection, nested. */
+    readonly maxPassDrawCalls?: Readonly<Partial<Record<ThreeNativeRenderPassKind, number>>>;
+    /** Per-pass triangle ceilings, keyed by pass kind: main, shadow, reflection, nested. */
+    readonly maxPassTriangles?: Readonly<Partial<Record<ThreeNativeRenderPassKind, number>>>;
+    /** Per-phase millisecond ceilings at nearest-rank p95: hostGap, update, render, overlay, residual. */
+    readonly maxPhaseMsP95?: Readonly<Partial<Record<ThreeNativeFramePhase, number>>>;
+    /** Maximum renderer draw-call count across every pass combined. */
+    readonly maxDrawCalls?: number;
+    /** Maximum nearest-rank 95th-percentile frame time in milliseconds. */
+    readonly maxFrameMsP95?: number;
+    /** Maximum renderer triangle count across every pass combined. */
+    readonly maxTriangles?: number;
+    /** Frame-budget floor: the median presented frame must sustain at least this many frames a second. */
+    readonly minFps?: number;
+}
+/** The engine's frame-budget phases, as a budget spells them. */
+type ThreeNativeFramePhase = "hostGap" | "overlay" | "render" | "residual" | "update";
+/** The render-pass kinds a per-pass budget bounds. */
+type ThreeNativeRenderPassKind = "main" | "shadow" | "reflection" | "nested";
 interface IThreeNativeConfig {
     readonly app?: {
         readonly id?: string;
@@ -181,7 +305,10 @@ interface IThreeNativeConfig {
         readonly fullscreen?: boolean;
         readonly keepScreenOn?: boolean;
         /**
-         * Maximum native presentation rate in frames per second. Defaults to 60; `0` removes the
+         * Maximum native presentation rate in frames per second. Left out, it follows the display's own
+         * refresh rate capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is
+         * power and heat; the resolved value and its source are reported on every `TN_FRAME_BUDGET`
+         * line as `targetFps` and `targetSource`. A number set here wins outright, and `0` removes the
          * software ceiling. Android also submits this value as the surface's preferred frame rate,
          * which the display policy may decline because of hardware, power, or thermal state. Android
          * uses non-blocking presentation above 60 fps so a missed high-refresh interval does not fall
@@ -207,6 +334,43 @@ interface IThreeNativeConfig {
         readonly maximized?: boolean;
         readonly resizable?: boolean;
     };
+    /**
+     * Named cook profiles: one authored asset tree, one compiler, a different representation per
+     * artifact. `--profile` on `threenative build` wins over `defaults[target]`; with neither, the
+     * `assets` block is used exactly as declared. An overlay changes resource-processing options
+     * only — the source root, the output root, worker concurrency and exclusions stay in `assets`.
+     */
+    readonly buildProfiles?: {
+        readonly defaults?: {
+            readonly android?: string;
+            readonly desktop?: string;
+            readonly ios?: string;
+            readonly web?: string;
+        };
+        readonly profiles: Readonly<Record<string, {
+            /**
+             * Byte ceilings on what this profile actually produced, measured after packaging and
+             * checked before the artifact is published. `artifactBytes` is the artifact itself (a
+             * file, or the recursive sum of a directory, `.app` bundle or outDir);
+             * `packagedAssetBytes` is the sum of the asset files that survived the packaging
+             * selector. `"error"` refuses the build and leaves the previous artifact in place;
+             * `"warn"` prints and publishes.
+             */
+            readonly artifactBudget?: {
+                readonly artifactBytes?: IThreeNativeArtifactBudgetLimit;
+                readonly packagedAssetBytes?: IThreeNativeArtifactBudgetLimit;
+            };
+            /**
+             * Runtime ceilings this profile's artifact must hold, published into the
+             * `<artifact>.build-report.json` a build writes beside it and merged by
+             * `threenative-playtest --build-report` into every scenario's `assert.performance`. The
+             * build measures none of it — it cannot; the numbers exist only once a runtime drew
+             * frames — so a budget never refuses a build and never passes one either.
+             */
+            readonly performanceBudget?: IThreeNativePerformanceBudget;
+            readonly assets?: Pick<NonNullable<IThreeNativeConfig["assets"]>, "audio" | "budget" | "lod" | "models" | "targets" | "textures">;
+        }>>;
+    };
     readonly assets?: {
         /**
          * Audio conditioning options, or `"none"` to ship every clip exactly as committed. Absent
@@ -224,6 +388,18 @@ interface IThreeNativeConfig {
         };
         /** Source-relative globs omitted from builds; excluded bytes are still reported. */
         readonly exclude?: readonly string[];
+        /**
+         * How many cook workers a bake may run at once; absent means the driver's default,
+         * min(4, cores - 1). Not part of any cache key, so changing it re-cooks nothing.
+         */
+        readonly concurrency?: number;
+        /**
+         * Automatic discrete LOD. `assets.lod: {}` opts in with the balanced default; `false` or
+         * `{ enabled: false }` is the absolute kill switch, and per-asset overrides key off canonical
+         * source asset paths. Omission currently bakes nothing — the default-on front door opens only
+         * after the qualification phase passes. See {@link IThreeNativeLodConfig}.
+         */
+        readonly lod?: boolean | IThreeNativeLodConfig;
         readonly models?: "none" | IThreeNativeModelsConfig;
         readonly output?: string;
         readonly source?: string;
@@ -258,6 +434,63 @@ interface IThreeNativeConfig {
          * surface, and says so in `TN_ALPHA_ANTIALIASING` rather than reporting itself applied.
          */
         readonly alphaAntialiasing?: boolean;
+        /**
+         * Whether the engine may render an internal mirror of the scene to collapse repeated draws,
+         * and how often that mirror proves a batched material still matches its group's shared draw.
+         *
+         * On by default, which is the shipping behaviour and is what an unset option means. The mirror
+         * is opportunistic and correctness-preserving, but it pays a reconciliation cost per frame, so
+         * a game that has measured it as a loss — a scene whose draw count falls without its frame time
+         * following — can decline it with `false`. An opted-out game builds no mirror and runs no
+         * eligibility scan, so the opt-out costs nothing rather than declining each frame; the authored
+         * scene is what renders. The `TN_RENDER_PROJECTION` marker still reports it, with its own
+         * reason code rather than one of the measured declines.
+         *
+         * An object instead of `false` names the material check:
+         *
+         * - `materialChecks: "spread"` — **the default.** A bounded slice of the batched materials is
+         *   proved per frame instead of all of them, so a frame of 4,096 colour-only materials costs
+         *   512 checks rather than 4,096. A material that gains a roughness, a map or a define still
+         *   leaves its group and is drawn exactly; it is caught up to `materialCheckStaleFrames` frames
+         *   later, and `TN_RENDER_PROJECTION` reports that bound. A base-colour edit never waits: the
+         *   per-instance colour is O(1) per member and always exact.
+         * - `materialChecks: "everyFrame"` — the named alternative, and the check exactly as it shipped
+         *   before the sweep existed: every material proved every frame, at about 1.1 µs a material. Use
+         *   it when a game would rather pay the per-frame cost than accept the bound.
+         *
+         * Any other value throws at startup rather than falling back to a default nobody asked for.
+         */
+        readonly projection?: boolean | {
+            readonly materialChecks?: "spread" | "everyFrame";
+        };
+        /**
+         * Projected diameter, in raster pixels, below which the engine does not submit an object to
+         * the render camera. On by default at a conservative **0.5 px**: an object under half a pixel
+         * cannot light a whole pixel of the frame, so only unresolvable geometry is removed. Set a
+         * larger number for a tuned cut — a shipped game's ladder chose 2 px — or `false` to leave
+         * every object drawn. The measurement still runs with `false`; `TN_PROJECTION` reports how many
+         * objects were considered and skipped. Exempt a single object with `alwaysRender` from
+         * `@threenative/core`; the player's camera-attached objects and shadow casters are already kept.
+         */
+        readonly minimumProjectedPixels?: number | false;
+        /**
+         * How much of the scene graph the engine walks for world matrices each frame.
+         *
+         * `"visible"` — the default — does not recurse into a hidden subtree. three's own
+         * `updateMatrixWorld` walks every child whatever its `visible` flag, multiplying a world matrix
+         * for a full-detail body whose merged stand-in is showing, a hidden LOD level, a parked model —
+         * none of which can draw. The engine composes every visible node exactly as three does, and
+         * remembers a hidden node it skipped so the first frame that subtree shows again its whole
+         * chain is refreshed before anything reads it. A game that reads a **hidden** object's
+         * `matrixWorld` directly must not rely on the walk having reached it: use `getWorldPosition`
+         * (which updates the chain) or call `updateWorldMatrix(true, false)` first.
+         *
+         * `"all"` visits every node, exactly as three's own walk does — for a game that reads hidden
+         * world matrices without going through `getWorld*` and cannot say so per object. Both modes
+         * report the number of nodes walked in the `TN_PROJECTION` window, so the cost of the walk the
+         * default removed is measurable rather than asserted.
+         */
+        readonly matrixWorld?: "visible" | "all";
         /**
          * Android-only rendering overrides selected by the engine.
          *
@@ -279,7 +512,7 @@ interface IThreeNativeConfig {
     };
     readonly ui?: {
         /**
-         * Which renderer draws `src/ui/`.
+         * Which renderer draws `src/ui/`. Defaults to `"web"`.
          *
          * `"web"` runs the same React DOM, Tailwind, CSS, SVG and fonts on every target, through
          * that platform's own browser-class renderer composited over the game surface. What is
@@ -298,6 +531,182 @@ interface IThreeNativeConfig {
     };
 }
 
+/**
+ * Per-object geometry cost, measured from what the renderer actually submitted.
+ *
+ * A total triangle counter cannot name the offender: a main character can cost 500 triangles while
+ * a barely visible tree submits two million, and both land in the same number. `FrameBudget` stays
+ * authoritative for a frame's per-pass totals; this attributes a slice of those totals to the
+ * objects that caused them, and reconciles the two so the difference is visible rather than
+ * assumed away.
+ *
+ * Three properties make it a measurement rather than a guess:
+ *
+ * 1. **It counts submissions, not scene contents.** The instrument is `onBeforeRender`, which the
+ *    renderer calls once per object, per material group, per pass, *after* frustum and projected-
+ *    size culling. A `visible` flag is a game's intent; a submission is what the GPU was handed.
+ * 2. **It is armed only on request.** Nothing is installed, walked or counted until a consumer asks
+ *    for one capture, and every hook is removed when that frame ends, is cancelled, or the scene
+ *    exits. An idle game pays nothing.
+ * 3. **It says "unavailable" with a reason.** A packed batch's per-member draws, an indirect
+ *    counter with no readback, a geometry with no recoverable source detail: each is named, never
+ *    reported as zero and never quietly dropped, and the unattributed remainder of every pass is
+ *    reported beside the measured total.
+ *
+ * @situation find out which scene object is submitting the frame's triangles
+ * @situation tell a cheap foreground character from an expensive distant prop
+ */
+
+/** Rows returned when a request does not name a limit. */
+declare const GEOMETRY_CAPTURE_DEFAULT_LIMIT = 50;
+/** The most rows one request may ask for. A transport carries a report, not a scene dump. */
+declare const GEOMETRY_CAPTURE_MAX_LIMIT = 500;
+/** The inspection ceiling, shared with scene-node observation so one scene has one limit. */
+declare const GEOMETRY_CAPTURE_WALK_CAP = 50000;
+/** How long a request waits for a presented world frame before answering "unavailable". */
+declare const GEOMETRY_CAPTURE_TIMEOUT_MS = 2000;
+/** The `userData` key a loader stamps on a model root so a clone keeps its provenance. */
+declare const GEOMETRY_ASSET_KEY = "tnAssetPath";
+/** The orderings a request may ask for. Ranking happens over the inspected scope, then slices. */
+declare const GEOMETRY_CAPTURE_SORTS: readonly ["triangles", "draws", "projected"];
+type GeometryCaptureSort = (typeof GEOMETRY_CAPTURE_SORTS)[number];
+interface IGeometryCaptureRequest {
+    /** Rows to return, 1 to `GEOMETRY_CAPTURE_MAX_LIMIT`. */
+    readonly limit?: number;
+    readonly sort?: GeometryCaptureSort;
+    readonly timeoutMs?: number;
+}
+/** What a rendered object is: the game's own object, or the mirror standing in for some of them. */
+type GeometryOwnershipKind = "exact" | "instancedBatch" | "materialBatch";
+/** Where a row's triangle number came from, so a derived number is never read as a measured one. */
+type GeometryTriangleSource = "renderer" | "batchMembers";
+interface IGeometryPassCost {
+    readonly draws: number;
+    readonly triangles: number;
+}
+interface IGeometryCapturePass extends IGeometryPassCost {
+    readonly kind: FramePassKind;
+    /** What the rows below account for. */
+    readonly attributedDraws: number;
+    readonly attributedTriangles: number;
+    /**
+     * Measured minus attributed. Negative means the rows over-claim — a derived batch sum, say —
+     * which is a finding, not something to clamp away.
+     */
+    readonly unattributedDraws: number;
+    readonly unattributedTriangles: number;
+}
+interface IGeometryCaptureMesh {
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly type: string;
+    /** LOD0 triangles of this mesh, when the source detail is recoverable. */
+    readonly fullDetailTriangles?: number;
+    /** Triangles in the buffer the renderer was pointed at this frame. */
+    readonly selectedDetailTriangles?: number;
+    readonly submittedTriangles?: number;
+    readonly trianglesSource?: GeometryTriangleSource;
+    readonly draws: number;
+    readonly materials: number;
+    readonly instances?: number;
+    readonly submissions: Readonly<Partial<Record<FramePassKind, IGeometryPassCost>>>;
+    readonly batchOwner?: string;
+    readonly visible: boolean;
+    readonly inFrustum?: boolean;
+    readonly unavailable?: readonly string[];
+}
+interface IGeometryCaptureRow {
+    readonly id: string;
+    readonly generation: number;
+    readonly name: string;
+    readonly path: string;
+    readonly type: string;
+    /** The logical asset this row came from, when a loader stamped one. */
+    readonly asset?: string;
+    readonly fullDetailTriangles?: number;
+    readonly selectedDetailTriangles?: number;
+    readonly submittedTriangles?: number;
+    readonly trianglesSource?: GeometryTriangleSource;
+    readonly lod?: {
+        readonly level?: number;
+        readonly levels?: number;
+    };
+    /** Estimated projected diameter in drawing-buffer pixels. An estimate, never a pixel count. */
+    readonly projectedPixels?: number;
+    /**
+     * Where those bounds landed, in drawing-buffer pixels from the top-left. An overlay outlines
+     * this; it is the estimated bounds' centre, not a silhouette.
+     */
+    readonly projectedCenter?: readonly [number, number];
+    readonly viewportFraction?: number;
+    readonly cameraDistance?: number;
+    readonly inFrustum?: boolean;
+    readonly visibility: "submitted" | "notSubmitted";
+    /** Submitted copies of this row's geometry, instances included. */
+    readonly copies: number;
+    readonly instances?: number;
+    /** Triangles counted once per distinct geometry, for a unique-inventory reading. */
+    readonly uniqueTriangles?: number;
+    readonly draws: number;
+    readonly materials: number;
+    readonly submissions: Readonly<Partial<Record<FramePassKind, IGeometryPassCost>>>;
+    readonly batch?: {
+        readonly kind: GeometryOwnershipKind;
+        readonly owner: string;
+        readonly members: number;
+        readonly perMemberDrawsAvailable: boolean;
+    };
+    readonly unavailable?: readonly string[];
+    readonly meshes: readonly IGeometryCaptureMesh[];
+}
+interface IGeometryCaptureAsset {
+    readonly asset: string;
+    readonly objects: number;
+    readonly submittedTriangles?: number;
+    readonly draws: number;
+    /** Triangles of the distinct geometries this asset contributed, counted once each. */
+    readonly uniqueTriangles?: number;
+    readonly unavailable?: readonly string[];
+}
+interface IGeometryCaptureReport {
+    readonly status: "captured" | "unavailable";
+    /** Set when `status` is `unavailable`. A stale capture is never returned as a fresh one. */
+    readonly reason?: string;
+    readonly capturedAtMs?: number;
+    readonly durationMs?: number;
+    readonly generation?: number;
+    readonly tick?: number;
+    readonly frame?: number;
+    readonly backend?: string;
+    readonly camera?: {
+        readonly type: "perspective" | "orthographic" | "unknown";
+        readonly position: readonly [number, number, number];
+        readonly fov?: number;
+        readonly zoom?: number;
+        readonly near?: number;
+        readonly far?: number;
+    };
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly sort?: GeometryCaptureSort;
+    readonly limit?: number;
+    /** Rows the inspected scope produced before the limit sliced them. */
+    readonly matched?: number;
+    readonly returned?: number;
+    /** True when the limit cut rows; distinct from an incomplete inspection. */
+    readonly rowsTruncated?: boolean;
+    /** False when the walk cap stopped the inspection, so no ranking is a global claim. */
+    readonly inspectionComplete?: boolean;
+    readonly partialRanking?: boolean;
+    readonly inspectedNodes?: number;
+    readonly passes?: readonly IGeometryCapturePass[];
+    readonly objects?: readonly IGeometryCaptureRow[];
+    readonly assets?: readonly IGeometryCaptureAsset[];
+}
+
 /**
  * One action, read either as a button through `pressed`/`justPressed`, a 2D axis through
  * `vector`, or a scalar axis through `axis`. Which one you get depends on the fields you fill in,
@@ -398,6 +807,14 @@ interface IRawInputState {
         buttons: readonly boolean[];
     };
 }
+/**
+ * Ask the browser to lock the pointer to `target`, the capture every first-person mouse look needs.
+ *
+ * Returns the platform's own promise when it has one, so the caller can wait for the lock the way
+ * the browser reports it, and `undefined` when the platform answered synchronously. A target that
+ * cannot capture at all throws rather than leaving a game with a camera that never turns.
+ */
+declare function captureMouse(target: EventTarget): Promise<void> | undefined;
 declare class InputMap {
     #private;
     readonly raw: IRawInputState;
@@ -438,6 +855,7 @@ interface IAfterPhysicsContext {
 declare function afterPhysics(context: IAfterPhysicsContext, callback: AfterPhysicsCallback): () => void;
 interface IRenderPerformanceMetrics {
     readonly drawCalls?: number;
+    readonly passes?: readonly IRenderPassSample[];
     readonly triangles?: number;
 }
 interface IRenderPerformanceSample extends IRenderPerformanceMetrics {
@@ -704,6 +1122,33 @@ interface IWarmUpOptions {
      * This is opt-in because WebGPU does not expose a portable pipeline-serialization API.
      */
     readonly cache?: IWarmUpCacheOptions;
+    /**
+     * Render the warm scene once after compiling, so every pass's pipelines exist before the first
+     * frame. Default `true`.
+     *
+     * `compileAsync` builds only the main-pass pipelines. A shadow-casting light's shadow map and a
+     * reflection pass each need their own variants, created synchronously on first use — on a native
+     * Midway launch that was **44–107 pipelines after "ready"**, with freezes up to 615 ms. One
+     * hidden render of the warm scene, with the shadow map forced to update, builds them while the
+     * startup cover is still up. The render is invisible (it does not clear, and its output is
+     * behind the loading layer) and restores every renderer and scene state it touches.
+     *
+     * Set `false` to skip it. The warm-up still reports `passes: []` and `passPipelines: 0`, because
+     * turning a convention off must not turn its measurement off.
+     */
+    readonly renderPasses?: boolean;
+    /**
+     * Also render objects the scene has hidden for that one covered render. Default `false`.
+     *
+     * `renderPasses` already disables frustum culling, so every caster is submitted to the shadow
+     * pass and every reflected object to the reflection pass even when the startup camera cannot see
+     * it. A hidden LOD level or a parked model is still skipped, though: three never draws a subtree
+     * whose ancestor's `visible` is false, so its shadow and reflection pipelines stay unbuilt. With
+     * this on, the warm-up forces every hidden object visible for that one render — ancestors
+     * included — and restores every original `visible` exactly afterwards. The count is reported as
+     * `visibilityForced`, so a game can see how much of its scene the render had to un-hide.
+     */
+    readonly includeHidden?: boolean;
 }
 /** What the warm-up did, so a caller can report it rather than assume it. */
 type WarmUpObservationStatus = "complete" | "incomplete" | "unavailable";
@@ -770,12 +1215,27 @@ interface IWarmUpReport {
     readonly computeTimedOut?: boolean;
     /** The optional persistent warm-up hint's outcome. */
     readonly cache?: WarmUpCacheStatus;
+    /**
+     * The passes the hidden warm render exercised: `main` always, plus `shadow` when a shadow-casting
+     * light is present and `reflection` when a reflector node is reachable from a material. Empty when
+     * `renderPasses` was off, so an overridden convention still reports what it did. Absent when the
+     * renderer exposes no `render` at all.
+     */
+    readonly passes?: readonly string[];
+    /** Backend pipelines observed created by the hidden warm render alone. Absent with `passes`. */
+    readonly passPipelines?: number;
+    /** Objects whose `frustumCulled` the warm render turned off, so off-screen casters were submitted. */
+    readonly cullingForced?: number;
+    /** Hidden objects the warm render forced visible (`includeHidden`); zero when it was off. */
+    readonly visibilityForced?: number;
 }
 /** The narrow slice of the renderer this needs. Structural so a test needs no renderer. */
 interface IWarmUpRenderer {
     compileAsync?: (scene: Object3D, camera: Camera, targetScene?: Object3D) => Promise<void>;
     computeAsync?: (node: unknown) => Promise<void>;
     pipelineCensus?: () => IPipelineCensus;
+    /** The renderer's own render path, used to build every pass's pipelines once. */
+    render?: (scene: Object3D, camera: Camera) => void;
     raw?: unknown;
 }
 /**
@@ -861,6 +1321,10 @@ interface IStartupStatus {
      * 0 to 1, monotonic and honest: the loader's settled/requested ratio carries the first 0.7
      * while the start scene loads, 0.8 once the world is entered, 0.9 once first-use compilation
      * settled, 1 when `whenReady()` resolves.
+     *
+     * Monotonic is enforced, not assumed: this is a high-water mark over the measured load state,
+     * because that state can fall — requesting an asset after an earlier one settled shrinks the
+     * ratio, and a bar that jumps backwards reads to a player as the load restarting.
      */
     readonly progress: number;
     /** When each milestone happened; members appear as they are reached. */
@@ -925,6 +1389,12 @@ interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>,
     readonly after: (delay: number, callback: () => void) => ScheduleHandle;
     /** Register a callback for the engine-owned phase after physics writes solved transforms. */
     readonly afterPhysics: (callback: AfterPhysicsCallback) => () => void;
+    /**
+     * Register work that runs once per actual world render, after the frame's last fixed update and
+     * before the projection reconciles and the renderer draws. A held, loader-only frame has no world
+     * draw and therefore dispatches nothing.
+     */
+    readonly beforeRender: (callback: () => void) => () => void;
     readonly every: (callback: (dt: number) => void) => ScheduleHandle;
     readonly state: GameStore<TState>;
     readonly tween: <T extends object>(target: T, properties: {
@@ -951,13 +1421,19 @@ interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>,
 type PluginCleanup = () => void;
 interface IGameObservationSampleRequest {
     readonly entities?: readonly string[];
+    /** Asks for one armed per-object geometry capture. Absent means no capture is collected. */
+    readonly geometry?: IGeometryCaptureRequest;
     readonly include?: readonly string[];
     readonly label?: string;
     readonly resources?: readonly string[];
 }
 interface IGameObservationContribution {
     readonly capabilities: readonly string[];
-    readonly sample: (request: IGameObservationSampleRequest) => Readonly<Record<string, unknown>>;
+    /**
+     * May answer a promise: an observation that has to wait for the renderer — a geometry capture
+     * waits for one presented world frame — cannot be produced inside the request that asked for it.
+     */
+    readonly sample: (request: IGameObservationSampleRequest) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
 }
 interface IGameRuntimeObservations {
     contribute(contribution: IGameObservationContribution): PluginCleanup;
@@ -974,12 +1450,22 @@ interface IGamePluginRuntime {
     readonly enableRuntimeDiagnostics?: () => void;
     /** The frame's cost attribution so far, or undefined when the game turned the budget off. */
     readonly frameBudgetWindow?: () => IFrameBudgetWindow | undefined;
+    /**
+     * Stop the live clock, so a rendered frame simulates nothing and banks no wall-clock time.
+     *
+     * A run that counts fixed-step ticks must not also accumulate real seconds into the same
+     * simulation, and the frames before its first `advance()` are exactly where a boot's seconds
+     * used to land. Optional: a runtime without a clock just never freezes one.
+     */
+    readonly freezeClock?: () => void;
     /**
      * Hold start-scene entry until `gate` settles.
      *
-     * The returned promise settles after `Scene.enter()` has run. A runner can therefore release the
-     * gate after applying pre-entry setup, then await the returned promise before describing
-     * entity-derived capabilities. The frame loop remains held throughout.
+     * The returned promise settles after the scene that owns the world has entered: the start scene
+     * unless it navigated out of its own `enter()`, in which case it is the scene it navigated to,
+     * loaded and entered. A runner can therefore release the gate after applying pre-entry setup,
+     * then await the returned promise before describing entity-derived capabilities — the entities
+     * they read are the ones the world actually has. The frame loop remains held throughout.
      */
     readonly holdStart?: (gate: Promise<void>) => Promise<void>;
     readonly observations: IGameRuntimeObservations;
@@ -1001,6 +1487,11 @@ interface IGamePluginRuntime {
     readonly startupTimeline?: () => IStartupTimeline;
     /** The renderer-owned bounded pipeline capture, when the renderer has not been opted out. */
     readonly pipelineCensus?: () => IPipelineCensus;
+    /**
+     * Arms one per-object geometry capture and answers its report after the next presented world
+     * frame. Absent on a runtime with no render loop to arm.
+     */
+    readonly geometryCapture?: (request?: IGeometryCaptureRequest) => Promise<IGeometryCaptureReport>;
     readonly step: number;
 }
 interface IGamePlatformSource {
@@ -1100,6 +1591,7 @@ interface IGameConfig<TState extends Record<string, unknown> = Record<string, un
      */
     readonly step?: number;
     readonly start: string;
+    /** Optional slower UI publication interval. Omitted publishes once per rendered frame. */
     readonly stateFlushMs?: number;
 }
 interface IPerspectiveCameraConfig {
@@ -1124,7 +1616,7 @@ type CameraConfig = IPerspectiveCameraConfig | IOrthogonalCameraConfig;
  * two channels through an in-process broker, which is what keeps one `src/ui/` honest: a HUD
  * that works here works on a phone.
  *
- * Publication is automatic and throttled to the store's own published cadence, and it stops
+ * Publication is automatic at the rendered frame cadence (or the named stateFlushMs override), and it stops
  * entirely when nothing is listening — a game whose `ui.renderer` is `native` pays nothing.
  */
 interface IGameUi {
@@ -1163,4 +1655,4 @@ interface IGame<TState extends Record<string, unknown> = Record<string, unknown>
 }
 declare function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>(config: IGameConfig<TState, TPhysics>): IGame<TState, TPhysics>;
 
-export { afterPhysics as $, type AfterPhysicsCallback as A, type IThreeNativeIconVariants as B, type ContextMenuPolicy as C, type IThreeNativeTexturesConfig as D, type ITweenOptions as E, type IWarmUpCacheOptions as F, type IWarmUpObservation as G, type IWarmUpOptions as H, type IGame as I, type IWarmUpProgress as J, type IWarmUpRenderer as K, type IWarmUpReport as L, type InputBindings as M, type InputPlatformSource as N, type PointerEvent3DType as O, type PointerEvent3DListener as P, PointerEvents3D as Q, type SceneFrame as R, Scene as S, ScenePicker as T, type ScheduleHandle as U, Scheduler as V, type ThreeNativeBackgroundMode as W, type ThreeNativeOrientation as X, type ThreeNativeUiRenderer as Y, type WarmUpCacheStatus as Z, type WarmUpObservationStatus as _, type IGamePluginRuntime as a, createRandom as a0, defineGame as a1, warmUpScene as a2, type IGamePluginHooks as b, type ICtx as c, type IGameObservationContribution as d, type IGameObservationSampleRequest as e, type IGamePlatformSource as f, type IInputAction as g, type IInputGamepad as h, type IPointerDragHandle as i, type IPointerEvent3D as j, type IPointerEvents3D as k, type IPointerEvents3DOptions as l, type IPointerEvents3DPicker as m, type IPointerState as n, type IRandom as o, type IRawInputPointer as p, type IRawInputPointerEdge as q, type IRawInputState as r, type IRaycastOptions as s, type IScenePickerOptions as t, type IThreeNativeAudioConfig as u, type IThreeNativeAudioLoop as v, type IThreeNativeAudioOverride as w, type IThreeNativeAudioSpectrum as x, type IThreeNativeBootSplash as y, type IThreeNativeConfig as z };
+export { type IWarmUpRenderer as $, type AfterPhysicsCallback as A, type IRandom as B, type ContextMenuPolicy as C, type IRawInputPointer as D, type IRawInputPointerEdge as E, type IRawInputState as F, GEOMETRY_ASSET_KEY as G, type IRaycastOptions as H, type IGame as I, type IScenePickerOptions as J, type IThreeNativeAudioConfig as K, type IThreeNativeAudioLoop as L, type IThreeNativeAudioOverride as M, type IThreeNativeAudioSpectrum as N, type IThreeNativeBootSplash as O, type IThreeNativeConfig as P, type IThreeNativeIconVariants as Q, type IThreeNativeLodConfig as R, type IThreeNativeLodGenerationConfig as S, type IThreeNativeLodOverride as T, type IThreeNativeLodRuntimeConfig as U, type IThreeNativeTexturesConfig as V, type ITweenOptions as W, type IWarmUpCacheOptions as X, type IWarmUpObservation as Y, type IWarmUpOptions as Z, type IWarmUpProgress as _, type IGamePluginRuntime as a, type IWarmUpReport as a0, type InputBindings as a1, InputMap as a2, type InputPlatformSource as a3, type PointerEvent3DListener as a4, type PointerEvent3DType as a5, PointerEvents3D as a6, Scene as a7, type SceneFrame as a8, ScenePicker as a9, type ScheduleHandle as aa, Scheduler as ab, type ThreeNativeBackgroundMode as ac, type ThreeNativeLodMinTrianglesScope as ad, type ThreeNativeLodPreset as ae, type ThreeNativeOrientation as af, type ThreeNativeUiRenderer as ag, type WarmUpCacheStatus as ah, type WarmUpObservationStatus as ai, afterPhysics as aj, captureMouse as ak, createRandom as al, defineGame as am, warmUpScene as an, type IGamePluginHooks as b, GEOMETRY_CAPTURE_DEFAULT_LIMIT as c, GEOMETRY_CAPTURE_MAX_LIMIT as d, GEOMETRY_CAPTURE_SORTS as e, GEOMETRY_CAPTURE_TIMEOUT_MS as f, GEOMETRY_CAPTURE_WALK_CAP as g, type GeometryCaptureSort as h, type ICtx as i, type IGameObservationContribution as j, type IGameObservationSampleRequest as k, type IGamePlatformSource as l, type IGeometryCaptureAsset as m, type IGeometryCaptureMesh as n, type IGeometryCapturePass as o, type IGeometryCaptureReport as p, type IGeometryCaptureRequest as q, type IGeometryCaptureRow as r, type IInputAction as s, type IInputGamepad as t, type IPointerDragHandle as u, type IPointerEvent3D as v, type IPointerEvents3D as w, type IPointerEvents3DOptions as x, type IPointerEvents3DPicker as y, type IPointerState as z };