@threenative/core 0.1.0 → 0.3.0

package/dist/game-CYIaKhgl.d.ts

@@ -0,0 +1,980 @@
+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 { 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";
+/** 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;
+}
+/** Texture compression options for the asset compile step; `"none"` ships sources verbatim. */
+interface IThreeNativeTexturesConfig {
+    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;
+    };
+    /**
+     * 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;
+        readonly resizable?: boolean;
+    };
+    readonly assets?: {
+        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;
+        /**
+         * 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;
+        };
+    };
+    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)`. */
+    readonly pointerRelative?: 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. Call this from a user gesture on the game surface. */
+    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;
+}
+
+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;
+    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;
+};
+
+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.
+ *
+ * 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 {
+    /** Distinct pipelines warmed so far. */
+    readonly done: number;
+    /** Distinct pipelines the warm-up will build in total. Known before the first slice. */
+    readonly total: number;
+}
+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.
+     *
+     * 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 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.
+     */
+    readonly granularity?: "scene" | "object";
+}
+/** What the warm-up did, so a caller can report it rather than assume it. */
+interface IWarmUpReport {
+    /** Distinct pipelines warmed — one representative object each, not one per renderable. */
+    readonly compiled: number;
+    /** 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 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>;
+    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>;
+
+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 the frame loop until `gate` settles, after the start scene has entered.
+     *
+     * 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.
+     */
+    readonly holdStart?: (gate: Promise<void>) => 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;
+    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;
+    /**
+     * Shader warm-up before the first frame. **Off by default, on the evidence below.**
+     *
+     * 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.
+     *
+     * 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.
+     */
+    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 { 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 };