@threenative/core 0.2.0 → 0.3.1

package/dist/game-XGrTzapq.d.ts

@@ -0,0 +1,1166 @@
+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';
+
+type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
+/** Which renderer draws a game's `src/ui/`. @see IThreeNativeConfig.ui */
+type ThreeNativeUiRenderer = "native" | "web";
+/** What the native host does with the render loop while the app is off-screen. */
+type ThreeNativeBackgroundMode = "continue" | "pause";
+interface IThreeNativeIconVariants {
+    readonly android?: {
+        readonly foreground?: string;
+        readonly background?: string;
+        readonly monochrome?: string;
+    };
+    readonly ios?: {
+        readonly dark?: string;
+        readonly tinted?: string;
+    };
+    readonly web?: {
+        readonly favicon?: string;
+        readonly maskable?: string;
+        readonly monochrome?: string;
+        readonly appleTouch?: string;
+    };
+}
+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;
+        readonly quality?: number;
+    }[];
+    /** ETC1S encoder quality 1–255. Ignored for UASTC. */
+    readonly quality?: number;
+}
+/** Model optimization sub-pass switches; absent means every pass runs. */
+interface IThreeNativeModelPassesConfig {
+    readonly dedup?: boolean;
+    readonly meshopt?: boolean;
+    readonly prune?: boolean;
+    readonly quantize?: boolean;
+    readonly reorder?: boolean;
+}
+/** Model optimization options for the asset compile step; `"none"` ships sources verbatim. */
+interface IThreeNativeModelsConfig {
+    /** Standard glTF TEXCOORD_1 atlas generation for offline static-light assets. */
+    readonly lightmap?: {
+        readonly atlasSize: number;
+        readonly padding: number;
+    };
+    readonly passes?: IThreeNativeModelPassesConfig;
+    readonly quantize?: {
+        readonly normalBits?: number;
+        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`.
+     *
+     * On by default in the compile step; `"none"` ships every embedded image exactly as
+     * authored. `maxSize` caps the longest edge, preserving aspect and snapping to whole 4x4
+     * blocks, and never upscales.
+     */
+    readonly textures?: "none" | {
+        readonly maxSize?: number;
+        readonly quality?: number;
+        readonly overrides?: readonly {
+            readonly slot: string;
+            readonly codec: "etc1s" | "none" | "uastc";
+        }[];
+    };
+    /**
+     * Mesh simplification. Absent means none at all, which is the default.
+     *
+     * `ratio` is the fraction of triangles to keep. `error` is a quality guard rather than a
+     * target — the largest a vertex may move as a fraction of the mesh's extent — so a loose
+     * ratio with a tight error stops short, and the compile step reports the ratio it actually
+     * achieved next to the one that was asked for.
+     */
+    readonly simplify?: {
+        readonly ratio: number;
+        readonly error?: number;
+    };
+    /**
+     * Cluster-DAG bake for virtual geometry, or `"none"` to ship every primitive as authored.
+     *
+     * Absent means on with defaults: any primitive of 65,536 triangles or more bakes to a cluster
+     * DAG the loader turns into a `ClusteredMesh`, and everything below that line compiles
+     * byte-identically. The payload costs roughly 3-4x the primitive's compiled bytes, which is
+     * what `"none"` and `minSourceTriangles` are for.
+     */
+    readonly virtual?: "none" | {
+        /** Clusters folded together per group, default 4. */
+        readonly groupSize?: number;
+        /** Upper bound on a cluster's triangles, default 128. */
+        readonly maxTriangles?: number;
+        /** Lower bound on a cluster's triangles, default 96. */
+        readonly minTriangles?: number;
+        /** Primitives below this many triangles are left alone, default 65,536. */
+        readonly minSourceTriangles?: number;
+        /** Fraction of a group's triangles kept per level, default 0.5. */
+        readonly simplifyRatio?: number;
+    };
+}
+interface IThreeNativeConfig {
+    readonly app?: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly version?: string;
+        readonly build?: number;
+        readonly icon?: string;
+        readonly icons?: IThreeNativeIconVariants;
+    };
+    readonly display?: {
+        readonly orientation?: ThreeNativeOrientation;
+        readonly fullscreen?: boolean;
+        readonly keepScreenOn?: boolean;
+        /**
+         * Maximum native presentation rate in frames per second. Defaults to 60; `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
+         * to an integer refresh-rate divisor.
+         */
+        readonly maxFps?: number;
+        /**
+         * What the native host does when the player leaves the app — presses the power button,
+         * switches away, minimizes the window. `"pause"` (the default) stops running frames and
+         * suspends audio until the app comes back; `"continue"` keeps rendering off-screen, which a
+         * server-shaped or split-screen game may genuinely want.
+         *
+         * Turning the pause off does not turn the reporting off: `TN_LIFECYCLE` markers are emitted
+         * either way and name the mode that executed.
+         */
+        readonly backgroundMode?: ThreeNativeBackgroundMode;
+    };
+    readonly window?: {
+        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;
+        readonly targets?: {
+            readonly maxMaterials?: number;
+            readonly maxTriangles?: number;
+            readonly maxTextureDimension?: number;
+        };
+        /** Texture compression options, or `"none"` to ship every texture exactly as committed. */
+        readonly textures?: "none" | IThreeNativeTexturesConfig;
+    };
+    readonly bootSplash?: IThreeNativeBootSplash;
+    readonly nativeEntry?: string;
+    readonly renderer?: {
+        readonly preferWebGPU?: boolean;
+        /**
+         * Portable drawing-buffer scale. CSS and UI layout dimensions are unchanged.
+         *
+         * `"auto"` — the default a template ships — lets the engine hold the `display.maxFps` budget
+         * without the game hand-authoring a resolution constant. A number in `(0, 1]` pins it and
+         * turns the loop off. Either way the active scale is reported in every `TN_FRAME_BUDGET`
+         * window: turning the convention off does not turn its measurement off.
+         */
+        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.
+         *
+         * `antialias` belongs here beside `resolutionScale` because they spend the same budget: a
+         * tile-based mobile GPU resolves MSAA in tile memory and prices it quite differently from a
+         * desktop one, so a platform that scales resolution down must be able to buy sampling back
+         * on that same platform rather than accepting whatever the portable value happened to be.
+         */
+        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?: {
+        /**
+         * Which renderer draws `src/ui/`.
+         *
+         * `"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
+         * guaranteed is source parity — one `src/ui/` — not browser-binary parity, which no design
+         * using the platforms' own engines can offer once iOS is in the set.
+         *
+         * `"native"` maps React to `CanvasLayer` quads with no web view, no CSS and no second
+         * process. Choose it for a UI that is part of the rendered frame, or a target with no web
+         * view, or zero extra processes — and own the appearance difference, which is the trade
+         * being made rather than something to discover in a screenshot.
+         *
+         * Which surface `"web"` lands on is the platform's business and never a game's: no config,
+         * type or document names the engine underneath.
+         */
+        readonly renderer?: ThreeNativeUiRenderer;
+    };
+}
+
+/**
+ * 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,
+ * and mixing the two is what makes bindings confusing to read:
+ *
+ * ```ts
+ * jump: { keys: ["Space"], buttons: [0] }                 // a button: key or *gamepad* button 0
+ * fire: { keys: ["Space"], mouseButtons: [0] }            // a button: key or *left mouse*
+ * move: { up: ["KeyW"], down: ["KeyS"], left: [...], right: [...] }  // an axis
+ * ```
+ *
+ * **`buttons` is the gamepad, `mouseButtons` is the mouse.** They are separate devices and
+ * `buttons: [0]` on a machine with no gamepad plugged in silently never fires.
+ *
+ * `up`/`down`/`left`/`right` are **directions of an axis**, not "the keys that press this".
+ * They are named after the vector they build, so `pressed("move")` is true whenever any
+ * direction is held — including `ArrowDown`. For a button, use `keys`.
+ */
+interface IInputAction {
+    /** **Gamepad** button indices that press this action. For the mouse, see `mouseButtons`. */
+    readonly buttons?: readonly number[];
+    /** **Gamepad** axis indices whose values contribute to `axis(name)`. */
+    readonly gamepadAxes?: readonly number[];
+    /**
+     * **Mouse** button indices that press this action, numbered as `MouseEvent.button`:
+     * `0` left, `1` middle, `2` right. Binding `2` also suppresses the browser context menu on
+     * the pointer target, because a right-click binding is unusable while the menu eats it.
+     */
+    readonly mouseButtons?: readonly number[];
+    /**
+     * Keyboard codes that press this action. Use this for a button — `jump`, `restart`, `fire`.
+     * A key listed here never contributes to `vector`.
+     */
+    readonly keys?: readonly string[];
+    /** The **−y** direction of `vector(name)`. Not "the keys that press this action" — see `keys`. */
+    readonly down?: readonly string[];
+    /** The −x direction of `vector(name)`. */
+    readonly left?: readonly string[];
+    /** Any active pointer or touch presses this action. */
+    readonly pointer?: boolean;
+    /** Add normalized browser/native wheel motion to `axis(name)`; negative DOM deltaY (toward-user) is positive. */
+    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)`. 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)`. */
+    readonly up?: readonly string[];
+}
+type InputBindings = Record<string, IInputAction>;
+/**
+ * What the browser context menu does over the game surface. `"suppress"` is the default: a
+ * right-click binding cannot work while the menu opens on the same press, and a context menu
+ * over a game canvas is almost never what anyone wants. `"allow"` restores the browser default.
+ */
+type ContextMenuPolicy = "allow" | "suppress";
+interface IInputGamepad {
+    readonly axes: ArrayLike<number>;
+    readonly buttons: readonly {
+        readonly pressed: boolean;
+    }[];
+}
+type InputPlatformSource = () => readonly (IInputGamepad | null)[];
+interface IRawInputPointer {
+    readonly id: number;
+    buttons: number;
+    readonly position: Vector2;
+}
+interface IRawInputPointerEdge {
+    readonly buttons: number;
+    readonly id: number;
+    readonly position: Vector2;
+    readonly type: "cancel" | "down" | "up";
+}
+interface IRawInputState {
+    readonly keys: ReadonlySet<string>;
+    readonly pointer: {
+        buttons: number;
+        captured: boolean;
+        down: boolean;
+        readonly position: Vector2;
+        /** Accumulated relative mouse motion since the last `tick`, in canvas pixels. */
+        readonly relative: Vector2;
+    };
+    /** Pointer transitions captured since the previous input tick, grouped by pointer id. */
+    readonly pointerEdges: ReadonlyMap<number, readonly IRawInputPointerEdge[]>;
+    readonly pointers: ReadonlyMap<number, IRawInputPointer>;
+    readonly gamepad: {
+        axes: readonly number[];
+        buttons: readonly boolean[];
+    };
+}
+declare class InputMap {
+    #private;
+    readonly raw: IRawInputState;
+    constructor(bindings?: InputBindings, target?: EventTarget, pointerTarget?: EventTarget, source?: InputPlatformSource, contextMenu?: ContextMenuPolicy);
+    /**
+     * Returns a 2D action vector where +y is up. On a conventional XZ ground plane whose
+     * forward direction is -z, map `vector.y` to `-z`. This differs from Godot's
+     * `Input.get_vector`, where up is -y.
+     */
+    vector(name: string): Vector2;
+    /**
+     * Returns a scalar action for this fixed-step tick, clamped to `[-1, 1]`.
+     *
+     * `scroll: true` normalizes wheel deltas to pixels before scaling them: one line is 16 pixels,
+     * one page is 800 pixels, and 100 pixels is one axis unit. Browser and native wheel events use
+     * the same DOM sign convention, so scrolling the wheel toward the user (negative DOM `deltaY`) is
+     * positive and scrolling away (positive DOM `deltaY`) is negative. `pinch: true` reports the relative distance change of the first two active pointers;
+     * a third pointer is ignored and a changing pair starts a new gesture without a jump.
+     */
+    axis(name: string): number;
+    /** 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;
+    pressed(name: string): boolean;
+    justPressed(name: string): boolean;
+    justReleased(name: string): boolean;
+    tick(): void;
+    clear(): void;
+    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;
+}
+interface IRenderPerformanceSample extends IRenderPerformanceMetrics {
+    readonly frameMs: number;
+    /** Where this frame's milliseconds went. Present whenever a frame budget is installed. */
+    readonly phases?: IFramePhaseSample;
+}
+
+interface IRandom {
+    (): number;
+    pick<T>(items: readonly T[]): T;
+    range(min: number, max: number): number;
+    state: number;
+}
+declare function createRandom(seed?: number): IRandom;
+
+type EntitySnapshot = Record<string, Record<string, unknown> & {
+    tags?: string[];
+}>;
+
+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;
+    clear(): void;
+    snapshot(): EntitySnapshot;
+}
+
+interface IRaycastOptions {
+    /** Screen point in canvas pixels. Mutually exclusive with `origin` and `direction`. */
+    readonly screen?: Vector2;
+    /** World-space ray origin. Requires `direction`. */
+    readonly origin?: Vector3;
+    /** World-space ray direction. The caller must provide a normalised vector. */
+    readonly direction?: Vector3;
+    /** Maximum distance. Defaults to unbounded. */
+    readonly far?: number;
+    /** What to test. Defaults to the whole scene. */
+    readonly targets?: Object3D | readonly Object3D[];
+    /** Subtrees never hit, whatever `targets` says. */
+    readonly exclude?: Object3D | readonly Object3D[];
+}
+interface IScenePickerOptions {
+    readonly camera: Camera;
+    readonly pointer: () => Vector2;
+    readonly scene: Object3D;
+    readonly viewport: Viewport;
+}
+/**
+ * Ray queries against scene geometry, accelerated by a bounding volume hierarchy that is
+ * built on first use and rebuilt when the geometry's positions change.
+ *
+ * The acceleration is an implementation detail: nothing about it reaches the caller, no
+ * `three` prototype is patched, and a game that never calls `raycast` never builds a tree.
+ * Skinned, instanced, batched and morphed meshes fall back to the stock `three` path,
+ * because a hierarchy over their rest positions would report hits in the wrong place.
+ */
+declare class ScenePicker {
+    #private;
+    constructor(options: IScenePickerOptions);
+    /**
+     * The closest hit, or `undefined` when the ray hits nothing.
+     *
+     * Collects at most one hit per target: the traversal runs with `firstHitOnly` so BVH-backed
+     * meshes stop at their own closest triangle (PRD-186 phase 1), and anything on the stock
+     * fallback path — instanced, skinned, morphed — is reduced to its own nearest before it joins
+     * the candidates. The winner is a running minimum, never a full sort: a game asking "what did
+     * this round hit" should not pay for every wall behind the answer.
+     */
+    raycast(options?: IRaycastOptions): Intersection | undefined;
+    /** Every hit, sorted from the nearest to the farthest. */
+    raycastAll(options?: IRaycastOptions, target?: Intersection[]): readonly Intersection[];
+    /** Drops every cached hierarchy. The next `raycast` rebuilds what it needs. */
+    dispose(): void;
+}
+
+declare const POINTER_EVENT_TYPES: readonly ["pointerEntered", "pointerExited", "pointerPressed", "pointerReleased", "tapped", "dragStarted", "dragged", "dragEnded"];
+type PointerEvent3DType = (typeof POINTER_EVENT_TYPES)[number];
+interface IPointerState {
+    readonly id: number;
+    readonly buttons: number;
+    readonly position: Vector2;
+}
+interface IPointerEvent3D {
+    readonly buttons: number;
+    readonly intersection: Intersection | undefined;
+    readonly object: Object3D;
+    readonly point: Vector3;
+    readonly pointerId: number;
+    readonly target: Object3D;
+    readonly type: PointerEvent3DType;
+    stopPropagation(): void;
+}
+type PointerEvent3DListener = (event: IPointerEvent3D) => void;
+interface IPointerDragHandle {
+    cancel(): void;
+}
+interface IPointerEvents3DPicker {
+    raycastAll(options?: IRaycastOptions): readonly Intersection[];
+}
+interface IPointerEvents3D {
+    on(object: Object3D, type: PointerEvent3DType, listener: PointerEvent3DListener): () => void;
+    off(object: Object3D, type: PointerEvent3DType, listener: PointerEvent3DListener): void;
+    drag(object: Object3D): IPointerDragHandle;
+}
+interface IPointerEvents3DOptions {
+    /** Convert an input position into the canvas-relative pixels expected by ScenePicker. */
+    readonly screen?: (position: Vector2, target: Vector2) => Vector2;
+}
+type PrimaryPointer = Pick<IPointerState, "buttons" | "position">;
+type PointerEdge = IRawInputPointerEdge;
+type PointerEdges = ReadonlyMap<number, readonly PointerEdge[]>;
+type PointerPicker = Pick<ScenePicker, "raycastAll"> | IPointerEvents3DPicker;
+/**
+ * Dispatch portable pointer events from the input stream to registered Three.js objects.
+ *
+ * Listeners live in a side table, so this never patches Three.js prototypes. The picker receives
+ * one target list and one query per active pointer, while the empty registration path does no
+ * queries at all.
+ */
+declare class PointerEvents3D implements IPointerEvents3D {
+    #private;
+    constructor(options?: IPointerEvents3DOptions);
+    /** Listen for one event on an object. The returned function removes exactly this listener. */
+    on(object: Object3D, type: PointerEvent3DType, listener: PointerEvent3DListener): () => void;
+    /** Remove a listener previously passed to `on`. */
+    off(object: Object3D, type: PointerEvent3DType, listener: PointerEvent3DListener): void;
+    /** Make an object capture a pointer for drag events until its handle is cancelled. */
+    drag(object: Object3D): IPointerDragHandle;
+    /**
+     * Advance every pointer by one simulation tick.
+     *
+     * `primary` is the legacy mouse position: InputMap keeps it even when no button is down, which
+     * lets hover work on web without changing the existing held-touch map. It is ignored whenever
+     * the per-id map has a live pointer.
+     */
+    tick(pointers: ReadonlyMap<number, IPointerState>, picker: PointerPicker, primary?: PrimaryPointer, edges?: PointerEdges): void;
+    /** Remove all registrations and release all per-pointer state, usually on scene change. */
+    clear(): void;
+    dispose(): void;
+}
+
+type ScheduleHandle = (() => void) & {
+    cancel(): void;
+    readonly active: boolean;
+};
+type TweenProperties<T extends object> = {
+    [K in keyof T]?: number;
+};
+interface ITweenOptions {
+    readonly ease?: (t: number) => number;
+}
+declare class Scheduler {
+    #private;
+    get size(): number;
+    after(delay: number, callback: () => void): ScheduleHandle;
+    every(callback: (dt: number) => void): ScheduleHandle;
+    tween<T extends object>(target: T, properties: TweenProperties<T>, duration: number, options?: ITweenOptions): Promise<void>;
+    tick(dt: number): void;
+    clear(): void;
+}
+
+type StatePatch<T extends Record<string, unknown>> = Partial<T> | ((state: T) => Partial<T>);
+type GameStore<T extends Record<string, unknown>> = StoreApi<T> & {
+    getPublishedState(): T;
+    set(patch: StatePatch<T>): void;
+    flush(): void;
+    start(): void;
+    stop(): void;
+};
+
+/**
+ * Compiles a scene's pipelines before the first frame, in slices, yielding between them.
+ *
+ * On a phone every distinct pipeline is built the first time something using it is drawn. Nothing
+ * spreads that cost: the first `render()` of a fully built scene compiles all of it, on the main
+ * loop, inside one frame. Measured on a Pixel 8, `sandbox/fps-framework` spent **24.5 seconds
+ * across 107 pipeline compiles** inside a single frame — 92 % of everything the launch-stall
+ * budget could attribute (`TN_STALL_SEGMENTS`, PRD-218). For that whole span the loop presented
+ * nothing, drained no UI messages and ran no callback, so the loading screen froze mid-animation
+ * and the game read as hung. The player's report was "the loading screen takes thirty seconds".
+ *
+ * This does not make the compiling cheaper — the same pipelines are built either way, and a claim
+ * otherwise would be a lie the next measurement catches. What it changes is **who waits and
+ * whether anything moves**: the work is cut into slices with a frame between them, so the loop
+ * presents, the loading screen animates, the UI bridge delivers, and progress is a number the game
+ * can show instead of a static label. A cost that cannot be removed must at least be visible; that
+ * is the whole of what this buys, and it is worth saying plainly.
+ *
+ * The slices are compiled through the renderer's own `compileAsync`, which is stock `three`.
+ * Nothing here mutates the scene: no reparenting, no temporary groups, no visibility flipping. A
+ * warm-up that edited the graph to compile it would be a correctness risk taken for a progress
+ * bar, and the object it handed back would not be the one the game authored.
+ */
+/** One renderable's worth of progress, reported as the warm-up advances. */
+interface IWarmUpProgress {
+    /** Renderable candidates handed to the renderer so far. */
+    readonly done: number;
+    /** 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[];
+    /**
+     * 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
+     * on the screen roughly every 30 objects' worth of work while adding a handful of presents to
+     * the launch.
+     */
+    readonly sliceSize?: number;
+    /** Called after each slice. Never called with `done` greater than `total`. */
+    readonly onProgress?: (progress: IWarmUpProgress) => void;
+    /**
+     * How the warm-up lets the host present between slices. Defaults to yielding one macrotask,
+     * which is one native-runtime loop iteration and therefore one presented frame. A caller that
+     * knows its host wants a different signal passes one; a test passes a resolved promise.
+     */
+    readonly yieldFrame?: () => Promise<void>;
+    /**
+     * How long one pipeline may take before the warm-up gives up on it. Default 2000 ms.
+     *
+     * A real compile on a Pixel 8 measured ~77 ms; two seconds is a compile that is not coming back.
+     */
+    readonly compileTimeoutMs?: number;
+    /**
+     * How long the whole warm-up may take before it stops and lets the game start. Default 15000 ms.
+     *
+     * The launch must never be *worse* for having tried to optimize it.
+     */
+    readonly budgetMs?: number;
+    /**
+     * How the scene is handed to the renderer. Default `"scene"`.
+     *
+     * `"scene"` makes one `compileAsync(scene, camera)` call, which is the shape `three` is built
+     * 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 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 {
+    /** 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. */
+    readonly elapsedMs: number;
+    /**
+     * True when the renderer had no `compileAsync` to call — a WebGL renderer, or a stub.
+     *
+     * Reported rather than silently skipped: "the warm-up ran and found nothing to do" and "this
+     * renderer cannot warm up" produce the same zero, and only one of them is a reason a launch
+     * still stalls.
+     */
+    readonly unsupported: boolean;
+    /**
+     * Pipelines whose compile never came back inside `compileTimeoutMs`, and pipelines never
+     * reached because the whole warm-up ran out of budget.
+     *
+     * Reported, never thrown. A warm-up is an optimization on the launch path: the one thing it must
+     * never do is stop the game from starting, and the first version of this did exactly that — a
+     * `compileAsync` that never resolved on the device left `#boot` awaiting forever, so the loop
+     * stayed held, the simulation never advanced and the game sat on its loading screen. A launch
+     * that is slower than it could be is a disappointment; a launch that never finishes is a bug.
+     */
+    readonly abandoned: number;
+    /** True when the overall budget ran out before every pipeline was warmed. */
+    readonly timedOut: boolean;
+    /** Compute kernels compiled before the scene pipelines. Present only when computeNodes was set. */
+    readonly computeCompiled?: number;
+    /** Compute kernels that rejected or exceeded their bound. Present only when computeNodes was set. */
+    readonly computeAbandoned?: number;
+    /** True when the renderer exposed no computeAsync seam. Present only when computeNodes was set. */
+    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;
+}
+/**
+ * Warms up `scene` for `camera`, in slices, presenting a frame between each.
+ *
+ * Fail closed on a nonsensical slice size rather than quietly choosing one: a zero or negative
+ * slice would loop forever, and a caller that passed it has a bug worth seeing now.
+ * @situation compile a scene's shaders during the loading screen instead of on the first frame
+ * @situation stop a native launch freezing for seconds inside its first rendered frame
+ * @example await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });
+ */
+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[];
+    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>>;
+}
+interface IGameRuntimeObservations {
+    contribute(contribution: IGameObservationContribution): PluginCleanup;
+    contributions(): readonly IGameObservationContribution[];
+}
+interface IGamePluginRuntime {
+    readonly fixedStep: (ticks: number) => number;
+    /**
+     * Announces that a diagnostics consumer is going to read render metrics, turning per-frame
+     * sample collection on for the rest of the run. Optional: a runtime without collection
+     * support just never enables. Games collect nothing until this fires — the samples exist for
+     * assertions, not for every frame of every game.
+     */
+    readonly enableRuntimeDiagnostics?: () => void;
+    /** The frame's cost attribution so far, or undefined when the game turned the budget off. */
+    readonly frameBudgetWindow?: () => IFrameBudgetWindow | undefined;
+    /**
+     * 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.
+     */
+    readonly holdStart?: (gate: Promise<void>) => Promise<void>;
+    readonly observations: IGameRuntimeObservations;
+    readonly tick: () => number;
+    readonly runtimeDiagnosticsSeries?: () => readonly IRenderPerformanceSample[];
+    readonly random?: Pick<IRandom, "state">;
+    rapier?: string | null;
+    readonly seed: number | null;
+    /**
+     * Whether first-use compilation has settled, separately from full readiness.
+     *
+     * Readiness also requires a sustained in-budget frame window, which is a player-experience
+     * gate — a CPU rasteriser never meets it and resolves on the window's own timeout instead. A
+     * harness that has been told the machine has no GPU needs the earlier, cheaper signal, and it
+     * 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 {
+    readonly devToolsHost?: Record<string, unknown>;
+    readonly input: NonNullable<ConstructorParameters<typeof InputMap>[3]>;
+    readonly inputTarget?: EventTarget;
+    readonly renderer: NonNullable<IRendererOptions["source"]>;
+    readonly viewport: NonNullable<IViewportOptions["source"]>;
+    mountCanvas(canvas: HTMLCanvasElement, container?: HTMLElement): void;
+    unmountCanvas(canvas: HTMLCanvasElement): void;
+}
+type GamePluginFunction<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = (ctx: ICtx<TState, TPhysics>) => undefined | PluginCleanup;
+interface IGamePluginHooks<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    setup?(ctx: ICtx<TState, TPhysics>, runtime?: IGamePluginRuntime): undefined | PluginCleanup | Promise<undefined | PluginCleanup>;
+    beforeUpdate?(ctx: ICtx<TState, TPhysics>, dt: number): void;
+    update?(ctx: ICtx<TState, TPhysics>, dt: number): void;
+    sceneExit?(ctx: ICtx<TState, TPhysics>): void;
+    dispose?(ctx: ICtx<TState, TPhysics>): void;
+}
+type GamePlugin<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> = GamePluginFunction<TState, TPhysics> | IGamePluginHooks<TState, TPhysics>;
+interface IGameConfig<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly assets?: IAssetLoaderOptions;
+    readonly camera?: CameraConfig;
+    readonly canvas?: HTMLCanvasElement;
+    readonly container?: HTMLElement;
+    readonly input?: InputBindings;
+    /**
+     * Browser context menu over the game surface. Defaults to `"suppress"`, which is what a game
+     * wants: right-click is a binding, not a menu. Set `"allow"` only if your game genuinely needs
+     * the browser menu over its canvas.
+     */
+    readonly contextMenu?: ContextMenuPolicy;
+    /**
+     * Per-frame cost attribution, on by default. Every `reportEvery` presented frames the game
+     * prints one `TN_FRAME_BUDGET` line naming where the frame went — present wait, simulation,
+     * three.js render, overlay, the rest — which is what a device lane reads instead of guessing.
+     * Pass `false` to silence the marker; the same numbers still reach a playtest `performance`
+     * assertion, because turning a convention off must not turn its measurement off.
+     */
+    readonly frameBudget?: IFrameBudgetOptions | false;
+    readonly initialState?: TState;
+    /**
+     * 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
+     * which 8.0 s was 105 pipeline compiles** — a launch the player reads as a hang, because the
+     * 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.
+     *
+     * **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;
+    /**
+     * Maximum simulation steps per rendered frame. Default 5. Caps the catch-up burst after a
+     * stall so a slow frame cannot cascade into a spiral of longer frames.
+     */
+    readonly maxSteps?: number;
+    readonly platform?: IGamePlatformSource;
+    readonly plugins?: readonly GamePlugin<TState, TPhysics>[];
+    /**
+     * The project's `display` block, passed straight through from `threenative.config.ts`. The
+     * adaptive scale holds `maxFps` as its budget, so a game that does not pass this gets the
+     * 60 fps default rather than a scaler with no target.
+     */
+    readonly display?: NonNullable<IThreeNativeConfig["display"]>;
+    readonly render?: NonNullable<IThreeNativeConfig["renderer"]>;
+    readonly renderer?: IRendererOptions;
+    readonly seed?: number;
+    readonly scenes: Record<string, SceneConstructor<TState, TPhysics>>;
+    /**
+     * Fixed simulation step in seconds, e.g. `1 / 60`. **This is the fixed-step knob a game
+     * wants**; every `update(ctx, dt)` receives exactly this `dt`, never a variable frame time,
+     * so gameplay and physics advance together and never see a stall.
+     *
+     * Do not write your own accumulator on top of this. Doing so runs the scene's update several
+     * times per already-fixed step and decouples gameplay from the simulation — a real build lost
+     * its largest wrong turn to exactly that, because this field carried no documentation.
+     */
+    readonly step?: number;
+    readonly start: string;
+    readonly stateFlushMs?: number;
+}
+interface IPerspectiveCameraConfig {
+    readonly projection: "perspective";
+    readonly fov?: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+interface IOrthogonalCameraConfig {
+    readonly projection: "orthogonal";
+    readonly size: number;
+    readonly near?: number;
+    readonly far?: number;
+}
+type CameraConfig = IPerspectiveCameraConfig | IOrthogonalCameraConfig;
+/**
+ * The game's end of the UI bridge.
+ *
+ * The UI renders through the platform's own browser-class renderer, which on every native
+ * target is a different realm from this one — so it holds a mirror of the game's published
+ * state and sends intents back rather than calling into the game. The web target uses the same
+ * 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
+ * entirely when nothing is listening — a game whose `ui.renderer` is `native` pays nothing.
+ */
+interface IGameUi {
+    /**
+     * Whether a UI layer has announced itself.
+     *
+     * Stricter than "a transport exists": the UI sends `tn:ready` once its tree has rendered and its
+     * interactive rectangles are published, and only then is this true. A transport with nothing on
+     * the other end and a UI that failed to render look the same to a game otherwise.
+     */
+    readonly connected: boolean;
+    /** Handle an intent the UI sent — `restart`, `pause`, whatever the game defines. */
+    onIntent(listener: (intent: string, payload: unknown) => void): () => void;
+    /** Publish the current state now, whether or not it changed. */
+    publish(): void;
+}
+interface IGotoOptions<TState extends Record<string, unknown>> {
+    readonly carry?: Partial<TState>;
+}
+interface IGame<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
+    readonly ctx: ICtx<TState, TPhysics> | undefined;
+    readonly scene: Scene<TState, TPhysics> | undefined;
+    /** The name of the entered scene, or undefined before `start()`. */
+    readonly sceneName: string | undefined;
+    readonly state: GameStore<TState>;
+    /** The seam between the game and its UI layer, on every target. @see IGameUi */
+    readonly ui: IGameUi;
+    /** Rebuilds the requested scene from its initial state, then merges an optional carry patch. */
+    goto(name: string, options?: IGotoOptions<TState>): Promise<void>;
+    /** Boot into `name` instead of `config.start` on the next `start()`. Hot reload's restore path. */
+    resumeScene(name: string): void;
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+}
+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 };