@threenative/core 0.3.2 → 0.3.3

package/dist/{assets-kyoF7JlJ.d.ts → assets-CYKk2WTu.d.ts}

@@ -74,6 +74,13 @@ interface IAssetLoader {
      * stay 0 for a game with no manifest, where no size is knowable before the bytes arrive.
      */
     readonly progress: {
+        /**
+         * The logical paths asked for and not yet settled, in request order. A loading screen that
+         * only shows a ratio cannot say *what* it is waiting for, which is the difference between
+         * "still loading" and "stuck on `akagi.glb`" — and a stall report that names nothing is a
+         * bug report nobody can act on.
+         */
+        readonly pending: readonly string[];
         readonly requested: number;
         readonly requestedBytes: number;
         readonly settled: number;

package/dist/{audio-BFiGneTL.d.ts → audio-7i3Xl0l3.d.ts}

@@ -14,6 +14,15 @@ interface IAudioBusOptions {
     readonly maxVoices?: number;
 }
 interface IAudioPlayOptions {
+    /**
+     * What this cue is, for anything reading back what the game played — a playtest above all.
+     *
+     * Nothing about the sound changes. Every other audio check answers "is the file right": that it
+     * exists, decodes, and is inside its byte budget. None of them can answer "did the game say the
+     * general-quarters line twice", which is the class of defect players actually report, so the bus
+     * keeps a ledger of the labels it was given.
+     */
+    readonly cue?: string;
     readonly fade?: number;
     readonly loop?: boolean;
     readonly volume?: number;
@@ -49,6 +58,21 @@ interface IAudioPlayOptions {
     readonly lowpassHz?: number;
 }
 interface IAudioRuntimeSnapshot {
+    /**
+     * How many times each labelled cue has sounded, across every live bus.
+     *
+     * This is the only observation that can answer "what did the game actually say, and how often".
+     * Every other audio check in the repository is about the *file* — that it exists, decodes and is
+     * inside its budget — and all of them stay green while a one-shot line plays a second time
+     * halfway through a match, which is the defect players report. A game opts a cue in by passing
+     * `cue` to `play`/`playAt`; unlabelled sounds never appear here.
+     */
+    readonly cues: Readonly<Record<string, number>>;
+    /** The most recent labelled cues in the order they sounded, bounded per bus. */
+    readonly recentCues: ReadonlyArray<{
+        readonly atMs: number;
+        readonly cue: string;
+    }>;
     readonly queued: number;
     readonly voices: number;
     /** Retired voices held for reuse. Bounded by peak concurrency, never by session length. */
@@ -67,6 +91,13 @@ interface IAudioRuntimeSnapshot {
      */
     readonly unsupported: readonly string[];
 }
+/**
+ * Forgets every recorded cue.
+ *
+ * @situation clear the recorded audio cue counts between tests so one test cannot read another's plays
+ * @example resetAudioCueLedger();
+ */
+declare function resetAudioCueLedger(): void;
 declare class AudioBus {
     #private;
     readonly listener: AudioListener;
@@ -153,4 +184,4 @@ declare class AudioBus {
 }
 declare function audioRuntimeSnapshot(): IAudioRuntimeSnapshot;
 
-export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioPlayOptions as b };
+export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioPlayOptions as b, resetAudioCueLedger as r };

package/dist/{canvas-layer-BLVijiUJ.d.ts → canvas-layer-C1SnMoJ-.d.ts}

@@ -1,6 +1,6 @@
 import * as three from 'three';
 import { Camera, Vector2, Vector3, Scene, OrthographicCamera } from 'three';
-import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+import { I as IRendererLike } from './renderer-Cy4qeBOA.js';
 
 interface IViewportSize {
     readonly aspect: number;

package/dist/{game-XGrTzapq.d.ts → game-D_6r-k4Y.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-CYKk2WTu.js';
+import { F as FramePassKind, H as IRenderPassSample, m as IFramePhaseSample, n as IPipelineCensus, I as IRendererLike, ad as IRendererOptions, a as IFrameBudgetWindow, i as IFrameBudgetOptions } from './renderer-Cy4qeBOA.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-C1SnMoJ-.js';
 import { StoreApi } from 'zustand/vanilla';
 
 type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
@@ -167,6 +167,76 @@ 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;
+}
 interface IThreeNativeConfig {
     readonly app?: {
         readonly id?: string;
@@ -224,6 +294,13 @@ interface IThreeNativeConfig {
         };
         /** Source-relative globs omitted from builds; excluded bytes are still reported. */
         readonly exclude?: readonly string[];
+        /**
+         * 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 +335,46 @@ 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.
+         *
+         * 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.
+         */
+        readonly projection?: boolean;
+        /**
+         * 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 +396,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 +415,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,
@@ -438,6 +731,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 +998,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 +1091,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 +1197,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 +1265,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 +1297,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;
@@ -1001,6 +1353,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 +1457,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 +1482,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 +1521,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, type InputPlatformSource as a2, type PointerEvent3DListener as a3, type PointerEvent3DType as a4, PointerEvents3D as a5, Scene as a6, type SceneFrame as a7, ScenePicker as a8, type ScheduleHandle as a9, Scheduler as aa, type ThreeNativeBackgroundMode as ab, type ThreeNativeLodMinTrianglesScope as ac, type ThreeNativeLodPreset as ad, type ThreeNativeOrientation as ae, type ThreeNativeUiRenderer as af, type WarmUpCacheStatus as ag, type WarmUpObservationStatus as ah, afterPhysics as ai, createRandom as aj, defineGame as ak, warmUpScene as al, 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 };

package/dist/{gpu-readback-D2iRvoe9.d.ts → gpu-readback-CMklJs6r.d.ts}

@@ -1,5 +1,5 @@
 import { Object3D } from 'three';
-import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+import { I as IRendererLike } from './renderer-Cy4qeBOA.js';
 
 /**
  * The lifecycle contract for a game-owned GPU simulation.

package/dist/hot.d.ts

@@ -1,10 +1,10 @@
-import { a as audioRuntimeSnapshot } from './audio-BFiGneTL.js';
-import { I as IGame } from './game-XGrTzapq.js';
+import { a as audioRuntimeSnapshot } from './audio-7i3Xl0l3.js';
+import { I as IGame } from './game-D_6r-k4Y.js';
 import 'three';
-import './assets-kyoF7JlJ.js';
-import './renderer-C6hqZpoG.js';
+import './assets-CYKk2WTu.js';
+import './renderer-Cy4qeBOA.js';
 import 'three/webgpu';
-import './canvas-layer-BLVijiUJ.js';
+import './canvas-layer-C1SnMoJ-.js';
 import 'zustand/vanilla';
 
 interface IHotDiagnostics {

package/dist/hot.js

@@ -1,21 +1,38 @@
 import 'three';
 
 // src/audio.ts
-var buses = /* @__PURE__ */ new Set();
+var AUDIO_STATE = /* @__PURE__ */ Symbol.for("threenative.audio.runtime");
+function audioState() {
+  const host = globalThis;
+  const existing = host[AUDIO_STATE];
+  if (existing !== void 0) return existing;
+  const created = { buses: /* @__PURE__ */ new Set(), cueCounts: /* @__PURE__ */ new Map(), cueLog: [] };
+  host[AUDIO_STATE] = created;
+  return created;
+}
 function audioRuntimeSnapshot() {
   let queued = 0;
   let voices = 0;
   let pooled = 0;
   let paused = 0;
   const unsupported = /* @__PURE__ */ new Set();
-  for (const bus of buses) {
+  const state = audioState();
+  for (const bus of state.buses) {
     queued += bus.queued;
     voices += bus.voices;
     pooled += bus.pooled;
     paused += bus.pausedVoices;
     for (const option of bus.unsupported) unsupported.add(option);
   }
-  return { paused, pooled, queued, unsupported: [...unsupported].sort(), voices };
+  return {
+    cues: Object.fromEntries(state.cueCounts),
+    paused,
+    pooled,
+    queued,
+    recentCues: state.cueLog.map((entry) => ({ ...entry })),
+    unsupported: [...unsupported].sort(),
+    voices
+  };
 }
 
 // src/hot.ts