@threenative/core 0.3.0 → 0.3.2

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

@@ -1,57 +1,9 @@
-import { Texture, Vector2, Vector3, Object3D, Camera, Intersection, Scene as Scene$1 } from 'three';
-import { h as IFramePhaseSample, U as Viewport, I as IRendererLike, C as CanvasLayer, W as IRendererOptions, X as IViewportOptions, g as IFrameBudgetWindow, e as IFrameBudgetOptions } from './canvas-layer-CtrZHgIh.js';
+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 { 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 { StoreApi } from 'zustand/vanilla';
 
-interface IAssetLoaderOptions {
-    readonly basePath?: string;
-    /**
-     * URL of the manifest written by the asset compile step (`public/assets.manifest.json`).
-     * Defaults to `assets.manifest.json` resolved against `basePath`. A logical path is resolved
-     * to its compiled output through it; a manifest that is absent — 404 or unfetchable — falls
-     * back to loading every path verbatim, while one that is served malformed or with an unknown
-     * version throws.
-     */
-    readonly manifest?: string;
-    readonly model?: (url: string) => Promise<unknown>;
-    readonly texture?: (url: string) => Promise<Texture>;
-    readonly audio?: (url: string) => Promise<AudioBuffer>;
-    /**
-     * The live renderer (`IRendererLike.raw`), handed to `KTX2Loader.detectSupport()` exactly
-     * once so compiled KTX2 textures transcode to a format this machine's GPU actually supports.
-     * Required for games whose textures compile to `.ktx2`; without it such a load throws rather
-     * than silently uploading decoded RGBA.
-     */
-    readonly renderer?: unknown;
-}
-/** The structural slice of three's `KTX2Loader` core depends on. */
-interface IKTX2LoaderLike {
-    detectSupport(renderer: unknown): unknown;
-    load(url: string, onLoad: (texture: Texture) => void, onProgress?: (event: ProgressEvent<EventTarget>) => void, onError?: (error: unknown) => void): unknown;
-    setTranscoderPath(path: string): unknown;
-}
-/**
- * Present only when a renderer was handed to the asset loader. `ready` settles once support
- * detection ran; it rejects naming the renderer and platform when no compressed format is
- * supported, and `defineGame` awaits it during boot so such a target fails at construction.
- */
-interface ICompressedTextureSupport {
-    /**
-     * The one shared instance, also handed to `GLTFLoader.setKTX2Loader()` for models. Resolves
-     * `undefined` when the renderer exposed no surface to probe (see `createKtx2Loader`).
-     */
-    readonly loader: Promise<IKTX2LoaderLike | undefined>;
-    readonly ready: Promise<void>;
-}
-interface IAssetLoader {
-    readonly compressedTextures?: ICompressedTextureSupport;
-    model<T = unknown>(path: string): Promise<T>;
-    texture(path: string): Promise<Texture>;
-    audio(path: string): Promise<AudioBuffer>;
-    release(kind: "audio" | "model" | "texture", path: string): boolean;
-    clear(): void;
-}
-declare function createAssetLoader(options?: IAssetLoaderOptions): IAssetLoader;
-
 type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
 /** Which renderer draws a game's `src/ui/`. @see IThreeNativeConfig.ui */
 type ThreeNativeUiRenderer = "native" | "web";
@@ -78,8 +30,59 @@ interface IThreeNativeBootSplash {
     readonly backgroundColor?: string;
     readonly image?: string;
 }
+/** What a clip is for, stated as a bound on where its energy sits, in the inspector's bands. */
+interface IThreeNativeAudioSpectrum {
+    readonly band: "air" | "high" | "low" | "mid" | "sub";
+    /** Most of the clip's energy that may sit in the band. */
+    readonly maxPercent?: number;
+    /** Least of the clip's energy that must sit in the band. */
+    readonly minPercent?: number;
+}
+/** Loop conditioning for a clip that repeats forever; its seam is cross-faded, then asserted. */
+interface IThreeNativeAudioLoop {
+    /** Equal-power cross-fade in milliseconds. `0` keeps the clip's own length and still asserts. */
+    readonly crossFadeMs?: number;
+    /** How far the splice may move to find a quiet seam, in milliseconds. */
+    readonly spliceToleranceMs?: number;
+}
+/**
+ * Per-glob audio declarations. Which clips loop, which are positional, and what a clip is for are
+ * facts only the game knows, so they are declared and never inferred from a filename.
+ */
+interface IThreeNativeAudioOverride {
+    /** `"none"` ships these bytes as committed; measurement and a declared loop's assertion run. */
+    readonly conditioning?: "none";
+    /** First matching override wins; matched against the logical path, e.g. `"audio/bed.ogg"`. */
+    readonly glob: string;
+    readonly loop?: boolean | IThreeNativeAudioLoop;
+    readonly normalise?: "ceiling" | "peak";
+    /** Peak ceiling in dBFS, between -60 and 0. */
+    readonly peakDb?: number;
+    /** The clip plays from a place in the world, so it is downmixed to mono. */
+    readonly positional?: boolean;
+    /** Vorbis VBR quality, -1 to 10. */
+    readonly quality?: number;
+    /** The largest wrap-to-neighbourhood step ratio a declared loop may ship with, 1 to 5. */
+    readonly seamMaxRatio?: number;
+    readonly spectrum?: IThreeNativeAudioSpectrum;
+}
+/**
+ * Audio conditioning options for the asset compile step; `"none"` ships clips verbatim.
+ *
+ * `"ceiling"` normalisation only ever attenuates, keeping the game's relative mix; `"peak"` also
+ * lifts a quiet clip to the ceiling.
+ */
+interface IThreeNativeAudioConfig {
+    readonly normalise?: "ceiling" | "peak";
+    readonly overrides?: readonly IThreeNativeAudioOverride[];
+    readonly peakDb?: number;
+    readonly quality?: number;
+    readonly seamMaxRatio?: number;
+}
 /** Texture compression options for the asset compile step; `"none"` ships sources verbatim. */
 interface IThreeNativeTexturesConfig {
+    /** Integer at least 4; caps the longest edge, preserving aspect and 4x4 alignment; never upscales. */
+    readonly maxSize?: number;
     readonly overrides?: readonly {
         readonly codec: "etc1s" | "none" | "uastc";
         readonly glob: string;
@@ -109,6 +112,13 @@ interface IThreeNativeModelsConfig {
         readonly positionBits?: number;
         readonly uvBits?: number;
     };
+    /**
+     * Write each distinct embedded image once under `shared/images/` and reference it from every
+     * model that carries it. A marketplace pack whose eight pines all embed the same bark map then
+     * ships and encodes it once. Default true; false embeds and re-encodes duplicate images in
+     * each model. The served GLB references files beside it.
+     */
+    readonly sharedImages?: boolean;
     /**
      * Embedded-texture compression for images carried inside a `.glb`.
      *
@@ -193,9 +203,27 @@ interface IThreeNativeConfig {
         readonly title?: string;
         readonly width?: number;
         readonly height?: number;
+        /** Start maximized on desktop when `display.fullscreen` is false. */
+        readonly maximized?: boolean;
         readonly resizable?: boolean;
     };
     readonly assets?: {
+        /**
+         * Audio conditioning options, or `"none"` to ship every clip exactly as committed. Absent
+         * means conditioning runs with defaults. `"none"` still measures and still reports.
+         */
+        readonly audio?: "none" | IThreeNativeAudioConfig;
+        /**
+         * Byte ceilings: uncooked defaults to 64,000,000; total defaults to "none". Mobile
+         * targets without decoders are exempt from uncooked. A number sets uncooked; "none"
+         * disables both gates. Measurements still print when a gate is disabled.
+         */
+        readonly budget?: number | "none" | {
+            readonly uncooked?: number | "none";
+            readonly total?: number | "none";
+        };
+        /** Source-relative globs omitted from builds; excluded bytes are still reported. */
+        readonly exclude?: readonly string[];
         readonly models?: "none" | IThreeNativeModelsConfig;
         readonly output?: string;
         readonly source?: string;
@@ -222,6 +250,14 @@ interface IThreeNativeConfig {
         readonly resolutionScale?: number | "auto";
         /** Portable multisampling. Sampling and resolution are one pixel budget, not two. */
         readonly antialias?: boolean;
+        /**
+         * Portable alpha antialiasing: resolve alpha-tested cutout silhouettes — foliage, fences,
+         * hair — through the multisample coverage mask rather than a binary `discard`. On by default,
+         * costing no target and no pass; it buys the cutouts the samples `antialias` already pays
+         * for. Set false for a deliberately hard-edged look. It does nothing on a single-sampled
+         * surface, and says so in `TN_ALPHA_ANTIALIASING` rather than reporting itself applied.
+         */
+        readonly alphaAntialiasing?: boolean;
         /**
          * Android-only rendering overrides selected by the engine.
          *
@@ -233,6 +269,12 @@ interface IThreeNativeConfig {
         readonly android?: {
             readonly resolutionScale?: number | "auto";
             readonly antialias?: boolean;
+            /**
+             * `alphaAntialiasing` belongs here for the reason `antialias` does, one step on: a phone
+             * that bought sampling back must be able to spend it on cutouts, and one that gave sampling
+             * up has nothing to spend.
+             */
+            readonly alphaAntialiasing?: boolean;
         };
     };
     readonly ui?: {
@@ -300,8 +342,14 @@ interface IInputAction {
     readonly scroll?: boolean;
     /** Add the signed two-pointer distance change to `axis(name)`; moving apart is positive. */
     readonly pinch?: boolean;
-    /** Add raw mouse movement since the last input tick to `vector(name)`. */
+    /**
+     * Add raw mouse movement since the last input tick to `vector(name)`. A click on the pointer
+     * target automatically asks for pointer capture when this binding is present; call
+     * `captureMouse()` explicitly when a game needs to start capture from another named gesture.
+     */
     readonly pointerRelative?: boolean;
+    /** Disable the automatic click capture for a relative binding that has its own gesture. */
+    readonly captureOnClick?: boolean;
     /** The +x direction of `vector(name)`. */
     readonly right?: readonly string[];
     /** The +y direction of `vector(name)`. */
@@ -370,7 +418,7 @@ declare class InputMap {
      * a third pointer is ignored and a changing pair starts a new gesture without a jump.
      */
     axis(name: string): number;
-    /** Request pointer capture. Call this from a user gesture on the game surface. */
+    /** Request pointer capture explicitly from a named game gesture. Relative bindings request it on canvas click by default. */
     captureMouse(): void;
     /** Release pointer capture. A browser refusal remains an unhandled rejection. */
     releaseMouse(): void;
@@ -382,6 +430,12 @@ declare class InputMap {
     dispose(): void;
 }
 
+type AfterPhysicsCallback = (dt: number) => void;
+interface IAfterPhysicsContext {
+    readonly afterPhysics: (callback: AfterPhysicsCallback) => () => void;
+}
+/** Register work that reads transforms after every simulation step and before the frame renders. */
+declare function afterPhysics(context: IAfterPhysicsContext, callback: AfterPhysicsCallback): () => void;
 interface IRenderPerformanceMetrics {
     readonly drawCalls?: number;
     readonly triangles?: number;
@@ -408,6 +462,7 @@ declare class Registry {
     #private;
     add<T extends object>(name: string, entity: T): T;
     get<T extends object = object>(name: string): T | undefined;
+    forEach(callback: (name: string, entity: object) => void): void;
     remove(name: string): void;
     queueFree(target: string | object): void;
     sweep(): void;
@@ -558,84 +613,6 @@ type GameStore<T extends Record<string, unknown>> = StoreApi<T> & {
     stop(): void;
 };
 
-declare abstract class Scene<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    static readonly initialState: Record<string, unknown> | undefined;
-    load(_ctx: ICtx<TState, TPhysics>): void | Promise<void>;
-    enter(_ctx: ICtx<TState, TPhysics>): SceneEnterResult<TState, TPhysics>;
-    exit(_ctx: ICtx<TState, TPhysics>): void;
-    update(_ctx: ICtx<TState, TPhysics>, _dt: number): void;
-    render(_ctx: ICtx<TState, TPhysics>): void;
-}
-type SceneConstructor<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = new () => Scene<TState, TPhysics>;
-type SceneFrame<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: ICtx<TState, TPhysics>, dt: number) => void;
-type SceneEnterResult<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = // biome-ignore lint/suspicious/noConfusingVoidType: void preserves existing Scene.enter overrides.
-void | SceneFrame<TState, TPhysics>;
-interface IStartupStatus {
-    /**
-     * True once first-use compilation has settled — earlier than `phase === "ready"`, which also
-     * waits for a sustained in-budget frame window.
-     *
-     * This is the signal a game wants when something must not run during the launch. `phase` cannot
-     * express it: it is binary, and on a software rasteriser the frame window can only ever expire
-     * rather than be met, so a game gated on `phase` alone does nothing for tens of seconds there.
-     * Measured as a chase route of length `0.000000` against a required `6`, because the scenario
-     * ended before the window did.
-     */
-    readonly compileSettled: boolean;
-    /**
-     * `collapsing` until first-use work and a sustained in-budget frame window complete, `ready`
-     * once the world is safe to show.
-     */
-    readonly phase: "observing" | "collapsing" | "ready";
-    /** 0 while first-use work or the sustained frame window is pending, then 1. */
-    readonly progress: number;
-    /** Resolves after first-use work and the sustained frame window, so it is always awaitable. */
-    whenReady(): Promise<void>;
-}
-interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
-    readonly fps: number;
-    readonly renderer: IRendererLike;
-    readonly viewport: Viewport;
-    readonly scene: Scene$1;
-    readonly camera: Camera;
-    readonly canvasLayer: CanvasLayer;
-    readonly entities: Registry;
-    /**
-     * Adds a node to the scene and hands it straight back, with its own type intact.
-     *
-     * Generic rather than `Object3D` because a game writes `const sea = ctx.add(new SpectralOcean())`
-     * and then calls a method on it. Erasing the type here makes every typed node in every scene need
-     * a cast back to what it already was, and that cast is where a game stops noticing it is holding
-     * something else.
-     */
-    readonly add: <T extends Object3D>(object: T) => T;
-    readonly input: InputMap;
-    readonly pointer: IPointerEvents3D;
-    readonly assets: IAssetLoader;
-    readonly after: (delay: number, callback: () => void) => ScheduleHandle;
-    readonly every: (callback: (dt: number) => void) => ScheduleHandle;
-    readonly state: GameStore<TState>;
-    readonly tween: <T extends object>(target: T, properties: {
-        [K in keyof T]?: number;
-    }, duration: number, options?: ITweenOptions) => Promise<void>;
-    readonly random: IRandom;
-    readonly raycast: (options?: IRaycastOptions) => Intersection | undefined;
-    readonly raycastAll: (options?: IRaycastOptions, target?: Intersection[]) => readonly Intersection[];
-    /**
-     * The framework's own startup work — what a loading screen waits on.
-     *
-     * A shader may compile the first time something using it is drawn, and the render projection may
-     * do its first build in that same frame. Both costs are real and belong before the world is shown.
-     *
-     * Keeping the world hidden until `whenReady()` resolves does more than hide the mess: the
-     * shaders that would have been compiled for geometry the projection then discards are never
-     * compiled at all, so waiting is *faster* than not waiting.
-     */
-    readonly startup: IStartupStatus;
-    readonly goto: (name: string) => Promise<void>;
-    physics: TPhysics;
-}
-
 /**
  * Compiles a scene's pipelines before the first frame, in slices, yielding between them.
  *
@@ -661,16 +638,28 @@ interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>,
  */
 /** One renderable's worth of progress, reported as the warm-up advances. */
 interface IWarmUpProgress {
-    /** Distinct pipelines warmed so far. */
+    /** Renderable candidates handed to the renderer so far. */
     readonly done: number;
-    /** Distinct pipelines the warm-up will build in total. Known before the first slice. */
+    /** Renderable candidates the warm-up will hand to the renderer in total. */
     readonly total: number;
 }
+/** The result of the optional persistent warm-up hint. */
+type WarmUpCacheStatus = "disabled" | "unavailable" | "miss" | "hit" | "stored";
+interface IWarmUpCacheOptions {
+    /**
+     * A game-owned revision for the scene's materials, shaders and renderer settings.
+     *
+     * The value is a hint that the native driver's own pipeline cache survived a relaunch; it is
+     * not a serialized WebGPU pipeline. Change it whenever those inputs change. A missing or
+     * unavailable localStorage implementation never prevents the warm-up from running.
+     */
+    readonly key: string;
+}
 interface IWarmUpOptions {
     /** Compute kernels to compile in the same bounded startup window as draw pipelines. */
     readonly computeNodes?: readonly unknown[];
     /**
-     * Distinct pipelines compiled between yields. Default 24.
+     * Renderable candidates handed to the renderer between yields. Default 24.
      *
      * The trade is presented frames against total warm-up time: every yield costs one frame's
      * present, and a slice of one would spend more time presenting than compiling. 24 puts a frame
@@ -705,18 +694,47 @@ interface IWarmUpOptions {
      * for and the only one measured to be affordable: on a Pixel 8 the renderer builds all 107 of
      * this game's pipelines in **8.1 s** that way.
      *
-     * `"object"` walks one representative per pipeline and yields between slices, which is the only
-     * way to show progress — but it was measured at **more than 2 s per call** on the same device,
-     * so warming the same scene would take minutes. It is kept, and kept off, because a scene with
-     * few pipelines can afford it and a progress bar is worth something there; the default may not
-     * be a mechanism that turns a 8 s launch into a 15 s one.
+     * `"object"` walks every renderable candidate and yields between slices, which is the only way
+     * to show candidate progress. The renderer owns cache reuse and actual pipeline identity, so the
+     * warm-up never drops an object based on a material or geometry guess.
      */
     readonly granularity?: "scene" | "object";
+    /**
+     * Remember a completed warm-up so a later launch can trust the driver's persistent cache.
+     * This is opt-in because WebGPU does not expose a portable pipeline-serialization API.
+     */
+    readonly cache?: IWarmUpCacheOptions;
 }
 /** What the warm-up did, so a caller can report it rather than assume it. */
+type WarmUpObservationStatus = "complete" | "incomplete" | "unavailable";
+interface IWarmUpObservation {
+    /** Pipeline creations observed between the census snapshots. */
+    readonly created: number;
+    /** Pipeline creations that failed between the census snapshots. */
+    readonly failed: number;
+    /** Pipeline creations still pending at the ending census snapshot, delta-adjusted. */
+    readonly pending: number;
+    /** New shader-program identities observed between the census snapshots. */
+    readonly uniquePrograms: number;
+    /** New backend pipeline identities observed between the census snapshots. */
+    readonly uniquePipelines: number;
+    /** Whether the renderer supplied a complete observation for this warm-up. */
+    readonly status: WarmUpObservationStatus;
+}
 interface IWarmUpReport {
-    /** Distinct pipelines warmed — one representative object each, not one per renderable. */
+    /** Compile calls that settled successfully; retained for compatibility with existing callers. */
     readonly compiled: number;
+    /**
+     * @deprecated Candidate count retained under the old public name. Use `candidates` for its
+     * actual unit and `observed` for backend-created pipelines.
+     */
+    readonly pipelines: number;
+    /** Renderable objects selected for warm-up, before backend cache identity is known. */
+    readonly candidates: number;
+    /** Number of compileAsync calls attempted, including rejected and timed-out calls. */
+    readonly attempted: number;
+    /** Backend creation counts observed between the warm-up's start and end snapshots. */
+    readonly observed: IWarmUpObservation;
     /** Slices the work was cut into, and therefore the frames the loop got to present. */
     readonly slices: number;
     /** Wall-clock milliseconds the warm-up took, compiling and yielding together. */
@@ -750,11 +768,14 @@ interface IWarmUpReport {
     readonly computeUnsupported?: boolean;
     /** True when compute warm-up consumed the startup budget. Present only when computeNodes was set. */
     readonly computeTimedOut?: boolean;
+    /** The optional persistent warm-up hint's outcome. */
+    readonly cache?: WarmUpCacheStatus;
 }
 /** 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;
     raw?: unknown;
 }
 /**
@@ -768,6 +789,165 @@ interface IWarmUpRenderer {
  */
 declare function warmUpScene(renderer: IWarmUpRenderer, scene: Object3D, camera: Camera, options?: IWarmUpOptions): Promise<IWarmUpReport>;
 
+declare abstract class Scene<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    static readonly initialState: Record<string, unknown> | undefined;
+    load(_ctx: ICtx<TState, TPhysics>): void | Promise<void>;
+    enter(_ctx: ICtx<TState, TPhysics>): SceneEnterResult<TState, TPhysics>;
+    exit(_ctx: ICtx<TState, TPhysics>): void;
+    update(_ctx: ICtx<TState, TPhysics>, _dt: number): void;
+    render(_ctx: ICtx<TState, TPhysics>): void;
+}
+type SceneConstructor<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = new () => Scene<TState, TPhysics>;
+type SceneFrame<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: ICtx<TState, TPhysics>, dt: number) => void;
+type SceneEnterResult<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = // biome-ignore lint/suspicious/noConfusingVoidType: void preserves existing Scene.enter overrides.
+void | SceneFrame<TState, TPhysics>;
+/**
+ * When the framework's startup milestones happened, in milliseconds on the host's monotonic
+ * clock (`performance.now()`: since navigation on the web, since process start on native).
+ *
+ * Absent members have not happened yet. Published to the playtest bridge so a scenario asserts
+ * startup time as an observation rather than reading it off a console log.
+ */
+interface IStartupTimeline {
+    /** The start scene's `load()` began. */
+    readonly loadStartedMs?: number;
+    /** The start scene's `enter()` returned: the world is built and the loop can move. */
+    readonly enteredMs?: number;
+    /** First-use compilation settled or its budget expired. */
+    readonly compileSettledMs?: number;
+    /**
+     * The framework's own launch work finished: compilation settled and the frame window held.
+     *
+     * Equal to `readyMs` unless the game registered a `startup.hold()`. Kept separate so that making
+     * `readyMs` honest about the player's wait does not delete the only measurement of the
+     * framework's own cost — a game with a slow asset tier would otherwise hide a framework
+     * regression inside its own loading time.
+     */
+    readonly frameworkReadyMs?: number;
+    /**
+     * `whenReady()` resolved: the world is safe to show, including anything the game held for.
+     *
+     * This is the number to compare against what a player experiences. It used to be the
+     * framework's own readiness and nothing else, which reported 1.5 s on a valley that took 8.8 s
+     * to appear — and `assert.startup`'s `maxReadyMs` passed on it.
+     */
+    readonly readyMs?: number;
+}
+interface IStartupStatus {
+    /** The most recent warm-up accounting, when a warm-up has run. */
+    readonly warmup?: {
+        readonly attempted?: number;
+        readonly candidates?: number;
+        readonly observed?: IWarmUpObservation;
+        readonly status: WarmUpObservationStatus;
+    };
+    /**
+     * True once first-use compilation has settled — earlier than `phase === "ready"`, which also
+     * waits for a sustained in-budget frame window.
+     *
+     * This is the signal a game wants when something must not run during the launch. `phase` cannot
+     * express it: it is binary, and on a software rasteriser the frame window can only ever expire
+     * rather than be met, so a game gated on `phase` alone does nothing for tens of seconds there.
+     * Measured as a chase route of length `0.000000` against a required `6`, because the scenario
+     * ended before the window did.
+     */
+    readonly compileSettled: boolean;
+    /**
+     * `collapsing` until first-use work and a sustained in-budget frame window complete, `ready`
+     * once the world is safe to show.
+     */
+    readonly phase: "observing" | "collapsing" | "ready";
+    /**
+     * 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.
+     */
+    readonly progress: number;
+    /** When each milestone happened; members appear as they are reached. */
+    readonly timeline: IStartupTimeline;
+    /** Resolves after first-use work, the sustained frame window, and every game `hold()`. */
+    whenReady(): Promise<void>;
+    /**
+     * Resolves after first-use work and the sustained frame window, and **before** any `hold()`.
+     *
+     * This is what a game should sequence its own launch work off. `whenReady()` cannot be used for
+     * that once the game holds startup: the hold makes readiness wait for the game's work, so work
+     * *started* from `whenReady()` waits for a gate that is waiting for it. The cycle is only broken
+     * by the hold's budget expiring, which looks exactly like a very slow asset load — measured as a
+     * valley revealing its critical tier after a 45 s stall with `trees=1`.
+     *
+     * Use this when the reason to wait is the framework's launch cost — not competing with first-use
+     * compilation, not stealing frames from the stable-frame window — which is the usual reason.
+     *
+     * @situation start the game's own asset streaming after the framework's launch work, without deadlocking the readiness gate
+     */
+    whenFrameworkReady(): Promise<void>;
+    /**
+     * Add the game's own launch work to the readiness gate, so every framework-owned observation of
+     * startup describes the moment the player actually reached the world.
+     *
+     * For a game that streams a second asset tier after the framework is done. Without it the only
+     * options are to show a half-built world or to hold a curtain past `whenReady()`, and the second
+     * leaves `progress`, `phase`, `timeline.readyMs` and the playtest bridge's `assert.startup` all
+     * describing a moment nobody experienced.
+     *
+     * Fails open twice: a hold that rejects counts as settled, and `budgetMs` bounds how long it may
+     * delay the world (45 s by default). A launch slower than it could be is a disappointment; a
+     * launch that never finishes because one asset 404'd is a bug.
+     *
+     * Throws on an empty or duplicate label, and on a hold registered after startup already
+     * resolved — each means the caller believes it is gating something it is not.
+     *
+     * @situation hold the loading screen until the game's own asset tier has landed
+     */
+    hold(label: string, work: Promise<unknown>, budgetMs?: number): void;
+}
+interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly fps: number;
+    readonly renderer: IRendererLike;
+    readonly viewport: Viewport;
+    readonly scene: Scene$1;
+    readonly camera: Camera;
+    readonly canvasLayer: CanvasLayer;
+    readonly entities: Registry;
+    /**
+     * Adds a node to the scene and hands it straight back, with its own type intact.
+     *
+     * Generic rather than `Object3D` because a game writes `const sea = ctx.add(new SpectralOcean())`
+     * and then calls a method on it. Erasing the type here makes every typed node in every scene need
+     * a cast back to what it already was, and that cast is where a game stops noticing it is holding
+     * something else.
+     */
+    readonly add: <T extends Object3D>(object: T) => T;
+    readonly input: InputMap;
+    readonly pointer: IPointerEvents3D;
+    readonly assets: IAssetLoader;
+    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;
+    readonly every: (callback: (dt: number) => void) => ScheduleHandle;
+    readonly state: GameStore<TState>;
+    readonly tween: <T extends object>(target: T, properties: {
+        [K in keyof T]?: number;
+    }, duration: number, options?: ITweenOptions) => Promise<void>;
+    readonly random: IRandom;
+    readonly raycast: (options?: IRaycastOptions) => Intersection | undefined;
+    readonly raycastAll: (options?: IRaycastOptions, target?: Intersection[]) => readonly Intersection[];
+    /**
+     * The framework's own startup work — what a loading screen waits on.
+     *
+     * A shader may compile the first time something using it is drawn, and the render projection may
+     * do its first build in that same frame. Both costs are real and belong before the world is shown.
+     *
+     * Keeping the world hidden until `whenReady()` resolves does more than hide the mess: the
+     * shaders that would have been compiled for geometry the projection then discards are never
+     * compiled at all, so waiting is *faster* than not waiting.
+     */
+    readonly startup: IStartupStatus;
+    readonly goto: (name: string) => Promise<void>;
+    physics: TPhysics;
+}
+
 type PluginCleanup = () => void;
 interface IGameObservationSampleRequest {
     readonly entities?: readonly string[];
@@ -795,14 +975,13 @@ interface IGamePluginRuntime {
     /** The frame's cost attribution so far, or undefined when the game turned the budget off. */
     readonly frameBudgetWindow?: () => IFrameBudgetWindow | undefined;
     /**
-     * Hold the frame loop until `gate` settles, after the start scene has entered.
+     * Hold start-scene entry until `gate` settles.
      *
-     * A plugin that blocks its own `setup` blocks it too early: entity-derived capabilities are
-     * registered by the scene, which runs after plugin setup, so a runner reading `describe()`
-     * during that hold sees a description missing them. Handing the gate here instead holds the
-     * loop at the last possible moment — everything is registered, nothing has stepped.
+     * 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.
      */
-    readonly holdStart?: (gate: Promise<void>) => void;
+    readonly holdStart?: (gate: Promise<void>) => Promise<void>;
     readonly observations: IGameRuntimeObservations;
     readonly tick: () => number;
     readonly runtimeDiagnosticsSeries?: () => readonly IRenderPerformanceSample[];
@@ -818,6 +997,10 @@ interface IGamePluginRuntime {
      * must be reported rather than inferred from a phase that cannot distinguish the two.
      */
     readonly startupCompileSettled?: () => boolean;
+    /** When the startup milestones happened, for the playtest bridge's startup observation. */
+    readonly startupTimeline?: () => IStartupTimeline;
+    /** The renderer-owned bounded pipeline capture, when the renderer has not been opted out. */
+    readonly pipelineCensus?: () => IPipelineCensus;
     readonly step: number;
 }
 interface IGamePlatformSource {
@@ -860,7 +1043,7 @@ interface IGameConfig<TState extends Record<string, unknown> = Record<string, un
     readonly frameBudget?: IFrameBudgetOptions | false;
     readonly initialState?: TState;
     /**
-     * Shader warm-up before the first frame. **Off by default, on the evidence below.**
+     * The **pre-start** shader warm-up. Off by default, and that is not the same as no warm-up.
      *
      * Every distinct pipeline is otherwise built the first time something using it is drawn, inside
      * the first rendered frame of a fully built scene. On a Pixel 8 that frame lasted **12.0 s, of
@@ -868,21 +1051,24 @@ interface IGameConfig<TState extends Record<string, unknown> = Record<string, un
      * loop presents nothing for the whole span. Warming those pipelines while the loading screen is
      * up is the obvious fix, and it is the one this option exists for.
      *
-     * It remains opt-in for callers that want to pay this cost before `start()` releases the held
-     * loop. On the native host it currently cannot complete: **`renderer.compileAsync()` never
-     * resolves there**. Measured on the same device, both granularities were abandoned by their own
-     * budget having compiled nothing —
-     * `TN_WARMUP:{"compiled":0,"abandoned":1,"timedOut":true,"elapsedMs":15325}` for one
-     * whole-scene call, and 6 of 490 in 15 s for the per-object walk — while the first frame
-     * compiled the identical pipelines synchronously in 8.0 s. Turning this on today buys nothing
-     * and spends the budget waiting, so the default may not be on until the host resolves that
-     * promise; the seam is the async-pipeline shim in `runtime-native`'s WebGPU bindings.
-     *
-     * Set it to `{}` or an options object to enable it — on web, where `compileAsync` does resolve,
-     * it does what it says. The default loading layer has its own bounded post-enter readiness gate,
-     * so setting this option is not required for a loading screen to cover first-use work. Either
-     * way `TN_WARMUP` reports what happened, because turning a convention off must not turn its
-     * measurement off.
+     * **A game with this unset still warms up.** `startupCompile` runs the same `warmUpScene` from
+     * inside the loading layer's bounded readiness gate, where the opaque layer is on screen and the
+     * loop is turning. This option only moves that work *earlier*, to before `start()` releases the
+     * loop, where nothing is presenting — which is a thing to choose deliberately, not a default.
+     *
+     * **What PRD-327 changed is the mechanism, not this default.** The native host used to answer
+     * `createRenderPipelineAsync` with the synchronous create wrapped in a resolved promise, so
+     * `compileAsync` compiled on the main loop and was abandoned by its own budget having finished
+     * nothing — `TN_WARMUP:{"compiled":0,"abandoned":1,"timedOut":true,"elapsedMs":15325}` — while
+     * the first frame compiled the identical pipelines in 8.0 s anyway. Both entries are native
+     * handlers now, handing the descriptor to a host compile pool and holding the main thread for
+     * 0.27 ms of a 70 ms compile (ratio 0.0038 against a pre-registered bar of 0.25, asserted by
+     * `threenative-async-pipeline-thread-test`). The default path started working without its
+     * default moving.
+     *
+     * Pass `{}` or an options object to opt in, or `false` to opt out of warm-up entirely. Either
+     * way `TN_WARMUP` and `TN_STARTUP_WARMUP` report what happened, because turning a convention off
+     * must not turn its measurement off.
      */
     readonly warmUp?: IWarmUpOptions | false | true;
     readonly inputTarget?: EventTarget;
@@ -977,4 +1163,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 { type ITweenOptions as A, type IWarmUpOptions as B, type ContextMenuPolicy as C, type IWarmUpProgress as D, type IWarmUpRenderer as E, type IWarmUpReport as F, type InputBindings as G, type InputPlatformSource as H, type IGame as I, type PointerEvent3DType as J, PointerEvents3D as K, type SceneFrame as L, ScenePicker as M, type ScheduleHandle as N, Scheduler as O, type PointerEvent3DListener as P, type ThreeNativeOrientation as Q, type ThreeNativeUiRenderer as R, Scene as S, type ThreeNativeBackgroundMode as T, createAssetLoader as U, createRandom as V, defineGame as W, warmUpScene as X, type IGamePluginRuntime as a, type IGamePluginHooks as b, type IAssetLoader as c, type IAssetLoaderOptions as d, type ICtx as e, type IGameObservationContribution as f, type IGameObservationSampleRequest as g, type IGamePlatformSource as h, type IInputAction as i, type IInputGamepad as j, type IPointerDragHandle as k, type IPointerEvent3D as l, type IPointerEvents3D as m, type IPointerEvents3DOptions as n, type IPointerEvents3DPicker as o, type IPointerState as p, type IRandom as q, type IRawInputPointer as r, type IRawInputPointerEdge as s, type IRawInputState as t, type IRaycastOptions as u, type IScenePickerOptions as v, type IThreeNativeBootSplash as w, type IThreeNativeConfig as x, type IThreeNativeIconVariants as y, type IThreeNativeTexturesConfig as z };
+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 };