lecodes-sdk 0.19.0

package/dist/types/runtime/files.d.ts

@@ -0,0 +1,33 @@
+import { File, type FetchResponse } from "./fetch";
+type OpenFilePickerOptions = {
+    accept?: string;
+};
+export declare function openFilePicker(options?: OpenFilePickerOptions & {
+    multiple?: false;
+}): Promise<File | null>;
+export declare function openFilePicker(options: OpenFilePickerOptions & {
+    multiple: true;
+}): Promise<File[]>;
+/** Anything writable as-is: text, raw bytes, or a buffer the host already holds
+ *  (a picked `File`, a `FetchResponse`, a `Canvas.toFile()` snapshot). */
+export type FileData = string | Uint8Array | ArrayBuffer | File | FetchResponse;
+export declare const files: {
+    /** Is there a filesystem here (desktop)? False on web/mobile, where every other call rejects. */
+    readonly supported: boolean;
+    /** Replace the file's contents, creating the parent folders on the way. */
+    write(path: string, data: FileData): Promise<void>;
+    /** Add to the end of the file, creating it (and the parent folders) when it isn't there yet. */
+    append(path: string, data: FileData): Promise<void>;
+    /** The whole file as UTF-8 text — null when there is no such file. */
+    readText(path: string): Promise<string | null>;
+    /** The whole file as bytes — null when there is no such file. */
+    readBytes(path: string): Promise<Uint8Array | null>;
+    /** Delete a file, or a directory (empty, or any directory with `{ recursive: true }`). Deleting
+     *  something already gone is success — what's promised is that the path is free afterwards. */
+    delete(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Create a directory and any missing parents. An existing directory is fine. */
+    mkdir(path: string): Promise<void>;
+};
+export {};

package/dist/types/runtime/input.d.ts

@@ -0,0 +1,121 @@
+/** Continuous channel ids — the `_creatorUtils.inputRead` contract (bridges.d.ts). */
+export declare const InputChannel: {
+    readonly MouseX: 0;
+    readonly MouseY: 1;
+    readonly MouseDX: 2;
+    readonly MouseDY: 3;
+    readonly WheelX: 4;
+    readonly WheelY: 5;
+    readonly PointerLocked: 6;
+    readonly GamepadCount: 7;
+    readonly GamepadBase: 16;
+    readonly GamepadStride: 16;
+    readonly PadConnected: 0;
+    readonly PadLeftX: 1;
+    readonly PadLeftY: 2;
+    readonly PadRightX: 3;
+    readonly PadRightY: 4;
+    readonly PadLeftTrigger: 5;
+    readonly PadRightTrigger: 6;
+};
+export type InputEventName = "keydown" | "keyup" | "gamepadconnected" | "gamepaddisconnected";
+/** `keydown` / `keyup` payload. `code` is the same string `Input.key()` takes. */
+export interface InputKeyEvent {
+    readonly type: "keydown" | "keyup";
+    /** Button code: KeyboardEvent.code ('KeyW', 'Space'), 'MouseLeft|Right|Middle|Back|Forward', or
+     *  'GamepadSouth|East|West|North|L1|R1|L2|R2|Select|Start|L3|R3|Up|Down|Left|Right'. */
+    readonly code: string;
+    /** Which device: 'keyboard' | 'mouse' | 'gamepad'. */
+    readonly source: "keyboard" | "mouse" | "gamepad";
+    /** Pad index (0..3) for gamepad buttons, undefined otherwise. */
+    readonly gamepad?: number;
+    /** OS auto-repeat keydown (key still held) — ignore for one-shot actions. */
+    readonly repeat: boolean;
+}
+export interface InputGamepadEvent {
+    readonly type: "gamepadconnected" | "gamepaddisconnected";
+    readonly gamepad: number;
+}
+type Listener<E> = (e: E) => void;
+type InputEventMap = {
+    keydown: InputKeyEvent;
+    keyup: InputKeyEvent;
+    gamepadconnected: InputGamepadEvent;
+    gamepaddisconnected: InputGamepadEvent;
+};
+/** Mouse state — polled. Position is the cursor inside the viewport in logical px; `delta` is the
+ *  motion during the previous frame (raw where the OS offers it) and keeps counting while locked —
+ *  that's FPS look. Hosts without a mouse report zeros. */
+export declare const mouse: {
+    readonly position: {
+        x: number;
+        y: number;
+    };
+    readonly delta: {
+        x: number;
+        y: number;
+    };
+    /** Wheel notches during the previous frame (+y = wheel toward you / scroll down). */
+    readonly wheel: {
+        x: number;
+        y: number;
+    };
+    /** Pointer lock: cursor hidden + confined, `delta` keeps flowing. Web grants it only from a user
+     *  gesture (call it in a 'keydown' handler for MouseLeft); hosts drop it on focus loss and
+     *  re-acquire on focus. Escape does NOT unlock by itself on native hosts — call `unlock()`. */
+    readonly locked: boolean;
+    lock(): boolean;
+    unlock(): void;
+};
+export type GamepadAxisName = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger";
+export interface GamepadState {
+    readonly index: number;
+    readonly connected: boolean;
+    /** Stick axes −1..1 (+Y = down, like the web Gamepad API), triggers 0..1. `deadzone` (default
+     *  0.15) zeroes small stick drift — pass 0 for the raw value. */
+    axis(name: GamepadAxisName, deadzone?: number): number;
+    /** Held? Same as `Input.key(code, index)`. */
+    button(code: string): boolean;
+}
+export declare const Input: {
+    /**
+     * Is a button held? `code` is the physical key (`KeyboardEvent.code`: 'ArrowRight', 'KeyW',
+     * 'Space'), a mouse button ('MouseLeft', 'MouseRight', 'MouseMiddle') or a gamepad button
+     * ('GamepadSouth' = A/Cross, 'GamepadR2' = right trigger as a button …). Poll inside setLoop for
+     * frame-independent movement. `gamepad` scopes a Gamepad* code to one pad; omitted = any pad.
+     */
+    key(code: string, gamepad?: number): boolean;
+    /** Listen for a discrete input moment. `keydown`/`keyup` cover EVERY button — keyboard, mouse,
+     *  gamepad — filter on `e.code`. Use these for one-shot actions (jump, shoot, charge-release);
+     *  `Input.key` for continuous ones (walk). */
+    on<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void;
+    off<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void;
+    mouse: {
+        readonly position: {
+            x: number;
+            y: number;
+        };
+        readonly delta: {
+            x: number;
+            y: number;
+        };
+        /** Wheel notches during the previous frame (+y = wheel toward you / scroll down). */
+        readonly wheel: {
+            x: number;
+            y: number;
+        };
+        /** Pointer lock: cursor hidden + confined, `delta` keeps flowing. Web grants it only from a user
+         *  gesture (call it in a 'keydown' handler for MouseLeft); hosts drop it on focus loss and
+         *  re-acquire on focus. Escape does NOT unlock by itself on native hosts — call `unlock()`. */
+        readonly locked: boolean;
+        lock(): boolean;
+        unlock(): void;
+    };
+    /** Gamepad `index` (0..3). Always returns an object — check `.connected`. */
+    gamepad(index?: number): GamepadState;
+    /** Indices of the currently connected gamepads. */
+    gamepads(): number[];
+    /** @internal — hosts/tests: deliver an event exactly as the host listener would. */
+    _emit(kind: number, code: string, gamepad: number, repeat: number): void;
+};
+export {};

package/dist/types/runtime/media.d.ts

@@ -0,0 +1,46 @@
+import { Emitter } from "../core/events";
+import { Texture } from "../gl/Texture";
+type MediaEvents = {
+    /** Fired at each loop boundary while `loop` is true. */
+    loopReached: () => void;
+    /** Fired once when playback reaches the end while `loop` is false. */
+    completed: () => void;
+};
+declare abstract class MediaPlayer extends Emitter<MediaEvents> {
+    protected _id: number;
+    protected _src: string;
+    private _playing;
+    private _loop;
+    private _volume;
+    private _disposed;
+    private _assertAlive;
+    play(): void;
+    pause(): void;
+    get playing(): boolean;
+    set playing(value: boolean);
+    get volume(): number;
+    set volume(value: number);
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Current playback position, in seconds. Settable to seek. */
+    get time(): number;
+    set time(value: number);
+    /** Total media length in seconds (0 until metadata has loaded). */
+    get duration(): number;
+    /** True once {@link dispose} has been called; the player is unusable afterwards. */
+    get disposed(): boolean;
+    /**
+     * Release the underlying host media resource (decoder, network, buffers) immediately and detach
+     * all listeners. Idempotent. Any further use of the player throws.
+     */
+    dispose(): void;
+}
+export declare class AudioPlayer extends MediaPlayer {
+    constructor(src?: string);
+}
+export declare class VideoPlayer extends MediaPlayer {
+    constructor(src?: string);
+    /** A 3D Texture that samples this video (e.g. for a Material.video()). */
+    get texture(): Texture;
+}
+export {};

package/dist/types/runtime/misc.d.ts

@@ -0,0 +1,11 @@
+/** Show a transient toast notification. */
+export declare const toast: (msg: string) => void;
+/** Open `url` in the system browser / external handler (fire-and-forget, like `share`). Silent
+ *  no-op on hosts without one (headless). */
+export declare const openURL: (url: string) => void;
+export type SvgSourceValue = {
+    readonly svg: string;
+    tintColor: string | null;
+};
+/** Wrap raw SVG XML so it can be used as an image source. */
+export declare const SvgSource: (svg: string) => SvgSourceValue;

package/dist/types/runtime/net.d.ts

@@ -0,0 +1,15 @@
+import { Emitter } from "../core/events";
+type SocketEvents = {
+    open: () => void;
+    message: (data: any) => void;
+    close: (code?: number) => void;
+    error: () => void;
+};
+export declare class WebSocket extends Emitter<SocketEvents> {
+    private _id;
+    constructor(url: string, headers?: Record<string, string>);
+    send(message: string | ArrayBuffer): void;
+    close(): void;
+    private _onMessage;
+}
+export {};

package/dist/types/runtime/rpc.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client transport for the app backend (docs/backend-plan.md §3.2 / §3.3). The compiler replaces
+ * every `*.server.ts` module in the client bundle with a stub whose exports are built by the three
+ * globals below — user code never calls them; it imports the server function and calls it.
+ *
+ *   export const listNotes = __rpc("<serverUrl>", "notes.server.ts#listNotes")
+ *   export const chat      = __channel("<serverUrl>", "chat.server.ts#chat")
+ *   export const db        = __serverOnly("schema.server.ts#db")
+ *
+ * Wire (implemented by the runner):
+ *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
+ *   WS   <serverUrl>/ws  frames: → {t:"hello",session} {t:"sub",id,ch,topic} {t:"unsub",id}
+ *                                ← {t:"session",session} {t:"ok",id} {t:"err",id,status,message} {t:"ev",ch,topic,event,data}
+ *   (`ev` is addressed by channel + topic, not by subscription id, so the server can fan one publish out
+ *   to every socket of a topic natively; the client delivers it to each matching subscription.)
+ *
+ * The session token is transport-owned (cookie-like): stored under `lecodes.session:<serverUrl>` in
+ * localStorage, sent on every call and on the socket, replaced whenever a response carries `session`.
+ * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
+ */
+/** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
+ *  (0 = the request itself failed: no network / no server). */
+export declare class RpcError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Build the client proxy of endpoint `id`. Positional args travel as a JSON array. */
+export declare const __rpc: (serverUrl: string, id: string) => (...args: unknown[]) => Promise<any>;
+/** A server-only export (db, models, helpers) referenced from client code: any use throws. */
+export declare const __serverOnly: (id: string) => any;
+export interface ClientChannel<E extends Record<string, unknown> = Record<string, unknown>> {
+    /** Subscribe to `topic`; handlers are keyed by event name (+ `reconnect`/`error`). Returns `{ close }`. */
+    subscribe(topic: string, handlers: {
+        [K in keyof E]?: (payload: E[K]) => void;
+    } & {
+        reconnect?: () => void;
+        error?: (e: RpcError) => void;
+    }): {
+        close(): void;
+    };
+}
+/** Build the client proxy of channel `id`. */
+export declare const __channel: (serverUrl: string, id: string) => ClientChannel<any>;

package/dist/types/runtime/service.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/share.d.ts

@@ -0,0 +1,2 @@
+import type { File, FetchResponse } from "./fetch";
+export declare function share(media: File | FetchResponse, text?: string): void;

package/dist/types/runtime/storage.d.ts

@@ -0,0 +1,5 @@
+export declare const localStorage: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+};

package/dist/types/runtime/touch.d.ts

@@ -0,0 +1,56 @@
+export declare class ClickEvent<T = any> {
+    readonly type = "click";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    /** World-space hit position (2D scenes only; undefined in 3D). */
+    worldX?: number;
+    worldY?: number;
+    target: T;
+    constructor(clientX: number, clientY: number, pointerId: number);
+}
+export interface TrackHandler {
+    onMove?(pos: {
+        clientX: number;
+        clientY: number;
+        deltaX: number;
+        deltaY: number;
+    }): void;
+    onEnd?(pos: {
+        clientX: number;
+        clientY: number;
+        deltaX: number;
+        deltaY: number;
+    }): void;
+    onCancel?(): void;
+    claim?: boolean | "pan-x" | "pan-y" | "pan-down" | "pan-up" | "pan-left" | "pan-right";
+}
+export declare class TouchStartEvent<T = any> {
+    readonly type = "touchstart";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    /** World-space hit position (2D scenes only; undefined in 3D). */
+    worldX?: number;
+    worldY?: number;
+    target: T;
+    constructor(clientX: number, clientY: number, pointerId: number);
+    /** Capture subsequent moves/end for this pointer (drag/pan gestures). */
+    track(handler: TrackHandler): void;
+}
+/** Delivered to a `UIButton` `onLongPress` handler when a finger is held on the button past the
+ *  host's long-press threshold. Like `TouchStartEvent` it can `track(...)` the rest of the gesture —
+ *  so the common "press-and-hold, then drag to move" flow is one handler: start the drag from here. */
+export declare class LongPressEvent<T = any> {
+    readonly type = "longpress";
+    readonly pointerId: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    /** World-space hit position (2D scenes only; undefined in 3D). */
+    worldX?: number;
+    worldY?: number;
+    target: T;
+    constructor(clientX: number, clientY: number, pointerId: number);
+    /** Capture subsequent moves/end for this pointer — drag the element after the hold. */
+    track(handler: TrackHandler): void;
+}

package/dist/types/scene/defineScene.d.ts

@@ -0,0 +1,296 @@
+import { type With } from "../core/Aspect";
+import { use, ref, make, type AspectEntry, type MakeEntry as SharedMakeEntry } from "./grammar";
+import type { Vec3Like } from "../math/vec";
+import { Scene, type SceneOptions } from "../gl/Scene";
+import { Node } from "../gl/Node";
+import { Mesh } from "../gl/Mesh";
+import { Model } from "../gl/Model";
+import { type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/Terrain";
+import { Light, type SunOptions } from "../gl/Light";
+import { type MaterialDef } from "./material";
+import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry";
+export type MeshDef = {
+    kind: "box";
+    size?: Vec3Like | number;
+} | ({
+    kind: "sphere";
+} & SphereOptions) | ({
+    kind: "cylinder";
+} & CylinderOptions) | ({
+    kind: "plane";
+} & PlaneOptions);
+export type LightDef = {
+    kind: "sun";
+} & SunOptions;
+/** A stamp: the terrain conforms to another node of this file (a road) at load — see Terrain.conform. */
+export type TerrainStampDef = {
+    /** Path of the node (a Mesh, a Model, or a node holding them) the ground hugs. */
+    node: string;
+    offset?: number;
+    falloff?: number;
+    mode?: "both" | "lower" | "raise";
+};
+/** The `terrain: {}` source block (docs/terrain-plan.md §3.3): a `.terrain` file OR a flat grid to
+ *  generate from, its layers, and the stamps / holes applied at load (in order, after every node of the
+ *  file exists — a road built by `make()` is a valid target). Add `Shape { heightfield: true }` +
+ *  `Physics { motion: 'static' }` in `aspects` for collision. */
+export type TerrainNodeDef = {
+    /** `asset('./assets/terrain/valley.terrain')` — heights / holes / control from a file. */
+    data?: string;
+    size?: number;
+    sizeX?: number;
+    sizeZ?: number;
+    cellSize?: number;
+    chunk?: number;
+    layers?: TerrainLayer[];
+    normals?: TerrainOptions["normals"];
+    tint?: TerrainOptions["tint"];
+    stamps?: TerrainStampDef[];
+    holes?: TerrainRegion[];
+};
+export type { MaterialDef };
+export { use, ref, make };
+export type { AspectEntry };
+/** A `make(fn, args)` source entry whose factory returns a 3D {@link Node}. */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>> = SharedMakeEntry<A, Node>;
+/** Transform overrides for one INTERNAL node of a GLB model or a prefab instance
+ *  (`overrides` on a model/prefab node, keyed by part path). */
+export type ModelOverrideDef = {
+    position?: Vec3Like;
+    eulerAngles?: Vec3Like;
+    scale?: Vec3Like | number;
+    visible?: boolean;
+    /** Materials by primitive SLOT of this part (`0` for a single-material mesh; the editor lists
+     *  the slots with their glTF material names): a material asset, an inline def, or a custom
+     *  shader. Slots left out keep the glTF material. */
+    materials?: Record<number | string, MaterialDef>;
+};
+/** Camera projection settings, shared by the `camera:` source block and the top-level `camera:`
+ *  block. All optional — an omitted key keeps the host default (60° / 0.01 / 1000). */
+export type CameraProjectionDef = {
+    /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+    fov?: number;
+    /** Near clip distance (default 0.01). */
+    near?: number;
+    /** Far clip distance = view range (default 1000); geometry past it is culled. */
+    far?: number;
+};
+/** The `camera: {}` source block — projection settings for the node that drives the view. */
+export type CameraNodeDef = CameraProjectionDef;
+export type SceneNodeDef = {
+    mesh?: MeshDef;
+    /** GLB url — `asset('./hero.glb')`. */
+    model?: string;
+    light?: LightDef;
+    /** A heightmap ground — see {@link TerrainNodeDef}. */
+    terrain?: TerrainNodeDef;
+    /** The scene camera as a NODE: in play mode `scene.camera` follows this node's world transform
+     *  every frame (so movement aspects on it are camera flythroughs); the editor shows a frustum
+     *  marker and refuses to delete the last camera node. The first camera node in file order wins;
+     *  cameras inside prefabs are ignored (like a prefab's `camera:` block). */
+    camera?: CameraNodeDef;
+    /** A code-built subtree — `make(factoryFn, { ...literal args })`. */
+    make?: MakeEntry<any>;
+    /** Another scene file used as a reusable composition — the imported handle:
+     *  `import streetlamp from './streetlamp.scene'` … `lamp: { prefab: streetlamp }`. Its nodes
+     *  instantiate under this node per instance (env/camera are the instancing file's business and
+     *  are ignored); `ref()`s inside the prefab resolve file-locally, per instance. */
+    prefab?: SceneHandle<any>;
+    /** Material for a `mesh` source. */
+    material?: MaterialDef;
+    /** Model/prefab sources: transform overrides for the INTERNAL nodes, keyed by part path
+     *  (see the part-path grammar above `modelPartRows`). Unresolved paths are ignored. */
+    overrides?: Record<string, ModelOverrideDef>;
+    /** On a CHILD of a model/prefab node: parent this node to that INTERNAL part of the parent's
+     *  asset at build time (part path — the same grammar `overrides` keys use), e.g. a flashlight
+     *  in a hand. The transform stays local to the part. A stale path (asset changed) falls back
+     *  to the parent root with a console warning. */
+    mount?: string;
+    position?: Vec3Like;
+    eulerAngles?: Vec3Like;
+    scale?: Vec3Like | number;
+    visible?: boolean;
+    /** Editor-only: viewport manipulation won't target this node (fields still edit). No runtime effect. */
+    locked?: boolean;
+    /** Editor-only, `model` nodes: the POSE the scene editor shows — a clip looped while editing
+     *  (`time` freezes it at that second instead), so attachments / sight lines / a first-person eye
+     *  are placed against the animated pose, not the rest pose. Never applied when the scene runs. */
+    editor?: {
+        clip?: string;
+        time?: number;
+    };
+    /** `mesh` / `model` nodes: real-time shadow flags. On a `model` they reach every renderable of
+     *  the GLB instance, so `castShadows: false` on a first-person viewmodel covers the whole gun. */
+    castShadows?: boolean;
+    receiveShadows?: boolean;
+    /** Baked lighting (a scene with `env.lightmap`): is this model/mesh node a lightmap STATIC — a
+     *  receiver and an occluder in the bake, real-time shadow casting off once the bake applies?
+     *  Default: static unless a `Physics` aspect moves the node (`dynamic` — Physics' default — or
+     *  `kinematic`). Set it only to override that rule; prefab subtrees inherit the verdict. */
+    lightmap?: boolean;
+    /** Navigation (a scene with `env.navmesh`, see navmesh.md): every STATIC body is walkable by
+     *  default. `false` leaves this one out of the bake; `'unwalkable'` cuts its footprint out
+     *  (nobody stands on or crosses it). */
+    nav?: false | "unwalkable";
+    /** The named navmesh area this static body's surface belongs to (a key of `env.navmesh.areas`). */
+    navArea?: string;
+    aspects?: readonly AspectEntry<any>[];
+    children?: Record<string, SceneNodeDef>;
+};
+export type SceneCameraDef = CameraProjectionDef & {
+    position?: Vec3Like;
+    /** Point the camera looks at. */
+    target?: Vec3Like;
+};
+/** `env.lightmap` — the level's baked lighting (see lightmap.md): the two files
+ *  `lecodes lightmap bake` writes, plus how the bake is applied. Absent = real-time only. */
+export type SceneLightmapDef = {
+    /** `asset('./assets/lightmap/lightmap.bake')` */
+    data: string;
+    /** `asset('./assets/lightmap/lightmap.ktx2')` — or, for a bake that took more than one atlas PAGE
+     *  (`lecodes lightmap bake --pages`), every page in order: `[asset('x.ktx2'), asset('x_1.ktx2')]`. */
+    texture: string | string[];
+    /** `asset('./assets/lightmap/lightmap-light.ktx2')` (pages like `texture`) — the point lights' baked
+     *  irradiance the bake writes when the level holds point lights; the real-time lights it carries are
+     *  switched off once it applies. Absent = the lamps stay real-time. */
+    light?: string | string[];
+    /** `asset('./assets/lightmap/lightmap.volume')` — the light VOLUME for everything that moves (the
+     *  same bake writes it): dynamic nodes, and every model loaded in code while the level runs, read
+     *  the baked sun/ambient at their own position. Absent = movers stay real-time only. */
+    volume?: string;
+    /** 1 = baked sun shadows at full strength, 0 = ambient occlusion only. Default 1. */
+    sunStrength?: number;
+    /** Multiplier on the ambient share in the shadow math (1 = filament's own darkness). Default 1. */
+    ambientScale?: number;
+    /** How much of the baked ambient occlusion applies: 1 = all of it, 0 = none. An interior lit by its
+     *  ambient probe alone can want less than the geometric truth. Default 1. */
+    aoStrength?: number;
+    /** Multiplier on the baked point lights' irradiance (default 1) - dial the lamps up or down
+     *  without a re-bake, since their irradiance lives in the atlas. Scales the light volume with the
+     *  atlas, so movers match the statics. See `LightmapLoadOptions.lightBoost`. */
+    lightBoost?: number;
+    /** Multiplier on the light VOLUME's irradiance alone (default = `lightBoost`). Since the volume is an
+     *  ambient cube (2026-08-31) movers shade like the statics and the default is right; it stays as a
+     *  trim. See `LightmapLoadOptions.volumeBoost`. */
+    volumeBoost?: number;
+};
+/** `env.navmesh` — the level's navigation mesh (see navmesh.md): the file `lecodes navmesh bake`
+ *  writes, the agent size it is built for, and the named areas. Absent = no navigation. */
+export type SceneNavmeshDef = {
+    /** `asset('./assets/nav/<scene>.navmesh')` */
+    data: string;
+    /** The agent the mesh is built for (radius 0.4 · height 1.8 · climb 0.4 · slope 50 by default). */
+    agent?: {
+        radius?: number;
+        height?: number;
+        climb?: number;
+        slope?: number;
+    };
+    /** Named areas → traversal cost (1 = plain ground); nodes join one with `navArea`. */
+    areas?: Record<string, number>;
+};
+export type SceneDef = {
+    env?: SceneOptions & {
+        lightmap?: SceneLightmapDef;
+        navmesh?: SceneNavmeshDef;
+    };
+    camera?: SceneCameraDef;
+    nodes?: Record<string, SceneNodeDef>;
+};
+type SourceNodeOf<N extends SceneNodeDef> = N extends {
+    model: string;
+} ? Model : N extends {
+    mesh: MeshDef;
+} ? Mesh : N extends {
+    light: LightDef;
+} ? Light : Node;
+type AspectsOf<N extends SceneNodeDef> = N extends {
+    aspects: readonly AspectEntry<infer A>[];
+} ? A : never;
+type NodeOf<N extends SceneNodeDef> = [
+    AspectsOf<N>
+] extends [never] ? SourceNodeOf<N> : With<SourceNodeOf<N>, AspectsOf<N>>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type ChildMapsOf<T extends Record<string, SceneNodeDef>, P extends string> = {
+    [K in keyof T & string]: T[K] extends {
+        children: infer C extends Record<string, SceneNodeDef>;
+    } ? NodesOf<C, `${P}${K}/`> : never;
+}[keyof T & string];
+type NodesOf<T extends Record<string, SceneNodeDef>, P extends string = ""> = {
+    [K in keyof T & string as `${P}${K}`]: NodeOf<T[K]>;
+} & ([ChildMapsOf<T, P>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T, P>>);
+export type SceneNodes<D extends SceneDef> = D["nodes"] extends Record<string, SceneNodeDef> ? NodesOf<D["nodes"]> : Record<string, Node>;
+export type LoadedScene<D extends SceneDef> = {
+    scene: Scene;
+    nodes: SceneNodes<D>;
+    /** Path lookup — typed for this scene's literal paths, `Node | null` for arbitrary strings. */
+    get: {
+        <P extends keyof SceneNodes<D> & string>(path: P): SceneNodes<D>[P];
+        (path: string): Node | null;
+    };
+};
+/** One instance of a scene file built as a subtree (`handle.instantiate`). */
+export type SceneInstance<D extends SceneDef> = {
+    /** The wrapper node the file's nodes build under — position it, parent it, hide it. */
+    root: Node;
+    nodes: SceneNodes<D>;
+    /** Anchor the instance on one of its own nodes: `root`'s local transform is set so that
+     *  `inner` coincides with the frame `root` is parented to (its origin and axes). One-shot,
+     *  from the CURRENT pose of `inner` — a rig's attachment frame (the eye place of a
+     *  first-person arms scene, the grip of a held prop). */
+    alignTo(inner: Node): void;
+    get: LoadedScene<D>["get"];
+    /** Remove the subtree from the scene and destroy it. */
+    dispose(): void;
+};
+/** One INTERNAL node of a loaded GLB (editor introspection). */
+export type ModelPartRow = {
+    path: string;
+    name: string;
+    depth: number;
+    node: Node;
+};
+/** Flatten a model's (or prefab instance's) internal hierarchy to rows (depth-first, the root
+ *  excluded). `__generated` containers are derived output, and def-built nodes (`_sceneDef` —
+ *  plain or `mount`ed children of the model) are addressed by their own def paths — both are
+ *  not parts, skipped. Filtering BEFORE segment math keeps `name[i]` indices stable no matter
+ *  what defs are parented in. */
+export declare const modelPartRows: (root: Node) => ModelPartRow[];
+/** The static verdict for one node def (the editor's "Baked lighting" switch shows the same rule). */
+export declare const isLightmapStatic: (def: SceneNodeDef) => boolean;
+/** Edit mode: play the preview pose on a model node (`editor: { clip, time }`) — idempotent, the
+ *  harness re-applies it on inspector edits. No clip = back to the rest pose. */
+export declare const applyEditorPose: (node: Node, pose: {
+    clip?: string;
+    time?: number;
+} | undefined) => void;
+export declare class SceneHandle<D extends SceneDef = SceneDef> {
+    readonly def: D;
+    private _loading?;
+    constructor(def: D);
+    /** Instantiate the scene (idempotent — subsequent calls return the same instance). Does not open. */
+    load(): Promise<LoadedScene<D>>;
+    /** Load and make active. */
+    open(): Promise<LoadedScene<D>>;
+    /**
+     * Build this scene file as a reusable SUBTREE inside an existing scene — a weapon under a hand
+     * bone, a streetlamp per street corner — as many times as you like (unlike `load()`, which is
+     * the one-instance "scene as a level" path). The nodes build under a fresh wrapper node (`root`)
+     * parented to `parent` (or left unparented); `env` / `camera` are ignored like a prefab's. The
+     * file's transforms are local to the wrapper, so author it with the wrapper as the attachment
+     * point. `ref()`s resolve per instance; aspects attach per instance. `dispose()` removes the
+     * subtree from the scene and destroys it.
+     */
+    instantiate(opts: {
+        scene: Scene;
+        parent?: Node | null;
+        name?: string;
+    }): Promise<SceneInstance<D>>;
+}
+/**
+ * Define a scene as data — the default export of a `.scene.ts` file. Returns a typed handle:
+ * `const { scene, nodes, get } = await handle.open()` gives `nodes[path]` typed by its source
+ * block (Mesh / Model / Light / Node) with its `use(...)`d aspects attached — root nodes read as
+ * plain properties (`nodes.hero`), nested ones by path (`nodes['hero/halo']` / `get('hero/halo')`).
+ */
+export declare const defineScene: <const D extends SceneDef>(def: D) => SceneHandle<D>;