lecodes-sdk 1.1.0 → 2.0.0

package/dist/types/canvas/gen/spec.d.ts

@@ -0,0 +1,144 @@
+export declare const SPEC_VERSION = 1;
+export declare const LineJoin: {
+    readonly MITER: 0;
+    readonly ROUND: 1;
+    readonly BEVEL: 2;
+};
+export type LineJoin = (typeof LineJoin)[keyof typeof LineJoin];
+export declare const LineJoinName: readonly string[];
+export declare const LineCap: {
+    readonly BUTT: 0;
+    readonly ROUND: 1;
+    readonly SQUARE: 2;
+};
+export type LineCap = (typeof LineCap)[keyof typeof LineCap];
+export declare const LineCapName: readonly string[];
+export declare const TextAlign: {
+    readonly LEFT: 0;
+    readonly CENTER: 1;
+    readonly RIGHT: 2;
+    readonly START: 3;
+    readonly END: 4;
+};
+export type TextAlign = (typeof TextAlign)[keyof typeof TextAlign];
+export declare const TextAlignName: readonly string[];
+export declare const TextBaseline: {
+    readonly ALPHABETIC: 0;
+    readonly TOP: 1;
+    readonly MIDDLE: 2;
+    readonly BOTTOM: 3;
+    readonly HANGING: 4;
+    readonly IDEOGRAPHIC: 5;
+};
+export type TextBaseline = (typeof TextBaseline)[keyof typeof TextBaseline];
+export declare const TextBaselineName: readonly string[];
+export declare const FillRule: {
+    readonly NONZERO: 0;
+    readonly EVENODD: 1;
+};
+export type FillRule = (typeof FillRule)[keyof typeof FillRule];
+export declare const FillRuleName: readonly string[];
+export declare const Spread: {
+    readonly PAD: 0;
+    readonly REFLECT: 1;
+    readonly REPEAT: 2;
+};
+export type Spread = (typeof Spread)[keyof typeof Spread];
+export declare const SpreadName: readonly string[];
+export declare const Gradient: {
+    readonly LINEAR: 0;
+    readonly RADIAL: 1;
+};
+export type Gradient = (typeof Gradient)[keyof typeof Gradient];
+export declare const GradientName: readonly string[];
+export declare const Paint: {
+    readonly COLOR: 0;
+    readonly LINEAR: 1;
+    readonly RADIAL: 2;
+};
+export type Paint = (typeof Paint)[keyof typeof Paint];
+export declare const PaintName: readonly string[];
+export declare const PathVerb: {
+    readonly MOVE: 0;
+    readonly LINE: 1;
+    readonly QUAD: 2;
+    readonly CUBIC: 3;
+    readonly CLOSE: 4;
+};
+export type PathVerb = (typeof PathVerb)[keyof typeof PathVerb];
+export declare const PathVerbName: readonly string[];
+export declare const ImageFormat: {
+    readonly PNG: 0;
+    readonly JPEG: 1;
+};
+export type ImageFormat = (typeof ImageFormat)[keyof typeof ImageFormat];
+export declare const ImageFormatName: readonly string[];
+/** The opcode stream: op id → the word after it. */
+export declare const OP: {
+    readonly SAVE: 0;
+    readonly RESTORE: 1;
+    readonly TRANSLATE: 2;
+    readonly SCALE: 3;
+    readonly ROTATE: 4;
+    readonly TRANSFORM: 5;
+    readonly SET_TRANSFORM: 6;
+    readonly RESET_TRANSFORM: 7;
+    readonly GLOBAL_ALPHA: 8;
+    readonly FILL_STYLE: 9;
+    readonly STROKE_STYLE: 10;
+    readonly FILL_GRADIENT: 11;
+    readonly STROKE_GRADIENT: 12;
+    readonly LINE_WIDTH: 13;
+    readonly LINE_JOIN: 14;
+    readonly LINE_CAP: 15;
+    readonly MITER_LIMIT: 16;
+    readonly LINE_DASH: 17;
+    readonly LINE_DASH_OFFSET: 18;
+    readonly FONT: 19;
+    readonly TEXT_ALIGN: 20;
+    readonly TEXT_BASELINE: 21;
+    readonly LETTER_SPACING: 22;
+    readonly PATH_BEGIN: 23;
+    readonly PATH_CLOSE: 24;
+    readonly MOVE_TO: 25;
+    readonly LINE_TO: 26;
+    readonly QUADRATIC_TO: 27;
+    readonly BEZIER_TO: 28;
+    readonly ARC: 29;
+    readonly ARC_TO: 30;
+    readonly ELLIPSE: 31;
+    readonly RECT: 32;
+    readonly ROUND_RECT: 33;
+    readonly FILL: 34;
+    readonly STROKE: 35;
+    readonly CLIP: 36;
+    readonly FILL_RECT: 37;
+    readonly STROKE_RECT: 38;
+    readonly CLEAR_RECT: 39;
+    readonly FILL_TEXT: 40;
+    readonly STROKE_TEXT: 41;
+    readonly DRAW_IMAGE: 42;
+};
+export type OP = (typeof OP)[keyof typeof OP];
+/** Operand layout per op: `args` is one letter per fixed word (f float, i int, r string ref);
+ *  `repeat` is the group that follows the trailing count. */
+export declare const OP_ARGS: Record<number, {
+    args: string;
+    repeat: string;
+}>;
+export declare const OP_NAME: readonly string[];
+/** The draw list: command id → the word after it. */
+export declare const DRAW: {
+    readonly SET_TRANSFORM: 0;
+    readonly SAVE: 1;
+    readonly RESTORE: 2;
+    readonly CLIP: 3;
+    readonly FILL_PATH: 4;
+    readonly STROKE_PATH: 5;
+    readonly FILL_TEXT: 6;
+    readonly STROKE_TEXT: 7;
+    readonly DRAW_IMAGE: 8;
+    readonly CLEAR_RECT: 9;
+};
+export type DRAW = (typeof DRAW)[keyof typeof DRAW];
+export declare const DRAW_NAME: readonly string[];

package/dist/types/core/color.d.ts

@@ -8,6 +8,8 @@ export declare const Color: {
     toPackedRgb(c: ColorInput): number;
     /** 0xRRGGBBAA packed int (unsigned). */
     toPackedRgba(c: ColorInput): number;
-    /** '#rrggbb' (or '#rrggbbaa' when alpha < 1) — for the 3D material color uniforms. */
+    /** '#rrggbbaa' (lower-case, always eight digits) — the UI wire form and the 3D material color. */
     toHexString(c: ColorInput): string;
+    /** [r,g,b,a] in 0..1, or `null` when `c` is not a color — the non-throwing probe. */
+    tryParse(c: unknown): [number, number, number, number] | null;
 };

package/dist/types/core/pins.d.ts

@@ -0,0 +1,18 @@
+/** The handle of a wrapper whose resource is gone: `id` 0, nothing to finalize. Replacing `_h`
+ *  with it drops the real handle, so the runtime's record can go. */
+export declare const DEAD_HANDLE: Handle;
+export interface Pinned {
+    readonly _h: Handle;
+    /** The runtime freed the resource underneath (an ancestor's free): mark the wrapper dead. */
+    _freed?(): void;
+}
+export declare class Pins<T extends Pinned> {
+    private readonly map;
+    /** Keep `obj` alive and findable while native owns its resource. */
+    pin(obj: T | null | undefined): void;
+    unpin(id: number): void;
+    get(id: number): T | undefined;
+    has(id: number): boolean;
+    /** The runtime freed these resources: drop the pins, tell the wrappers. */
+    freed(ids: number[]): void;
+}

package/dist/types/g2/Node2D.d.ts

@@ -1,6 +1,5 @@
 import { AspectHost } from "../core/Aspect";
 import type { CompAxis, CompWriter } from "../core/compWrite";
-import { Registry } from "../core/registry";
 import { Vec2, type Vec2Like } from "../math/vec";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { Animation } from "../animate/tween/Animation";
@@ -38,11 +37,9 @@ export type Contact2D = {
     normal: Vec2;
     speed: number;
 };
-/** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
-export declare const node2dRegistry: Registry<Node2D>;
 export declare class Node2D extends AspectHost<Node2DEvents> implements CompWriter {
-    /** Native entity handle. */
-    readonly id: number;
+    /** Native entity id. */
+    get id(): number;
     /** Optional debug/editor name (plain JS data — scene2d files stamp their node names here). */
     name?: string;
     protected _x: number;
@@ -54,9 +51,7 @@ export declare class Node2D extends AspectHost<Node2DEvents> implements CompWrit
     protected _z: number;
     protected _visible: boolean;
     private _pushXf;
-    private _parent;
-    private _children;
-    constructor(internalId?: number);
+    constructor(internalId?: number | Handle);
     private _pull;
     get x(): number;
     set x(v: number);
@@ -103,5 +98,7 @@ export declare class Node2D extends AspectHost<Node2DEvents> implements CompWrit
     localToWorld(p: Vec2Like): Vec2;
     private _syncLocalFromNative;
     addEventListener<K extends keyof Node2DEvents>(channel: K, callback: Node2DEvents[K]): void;
+    /** Destroy this node and its whole subtree (children go with it — the 3D / UI contract). Every
+     *  aspect in the subtree detaches first (physics bodies released, updaters unregistered). */
     destroy(): void;
 }

package/dist/types/g2/Scene2D.d.ts

@@ -1,6 +1,6 @@
 import { type ColorInput } from "../core/color";
 import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
-import { Presentable, type PresentOptions } from "../ui/presentable";
+import { Presentable, type DismissOptions, type PresentOptions } from "../ui/presentable";
 import { type Vec2Like } from "../math/vec";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import { Camera2D } from "./Camera2D";
@@ -62,11 +62,15 @@ export declare class Scene2D implements Presentable {
     onOpen(callback: () => void): this;
     /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
     onClose(callback: () => void): this;
+    /** Hardware/system back while the scene is current. */
+    onBack(callback: () => void): this;
+    /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+     *  rename; removed with the release that recompiles them. */
     onBackPressed(callback: () => void): this;
     /** Make this the active scene — shows it as the current destination (replaces a screen /
      *  another scene; only the active scene renders). */
     open(options?: PresentOptions): this;
-    close(): this;
+    close(options?: DismissOptions): this;
     destroy(): void;
 }
 export {};

package/dist/types/gl/Foliage.d.ts

@@ -3,19 +3,20 @@ import { Node } from "./Node";
 export type FoliageWind = {
     /** Direction on the ground (x, z); normalised by the engine. Default [1, 0.3]. */
     direction?: [number, number];
-    /** Metres of sway at `bendHeight` (taller parts sway more). Default 0.07. 0 = still. */
-    strength?: number;
-    /** Radians per second of the main sway. Default 1.2. */
+    /** The wind speed in m/s — the plants' permanent bend and how fast the field drifts past them. Default 8.3
+     *  (30 km/h, the pack's demo). 0 = still. */
     speed?: number;
-    /** 0..1: how much the strength breathes over a slow envelope. Default 0.6. */
+    /** 0..2: the random share of the speed — how far the bend wanders off the mean wind and how much the leaves move.
+     *  Default 0.4. */
+    turbulence?: number;
+    /** 0..1: the gusts' strength — waves of extra wind that travel over the level, calm between. Default 0.35. */
     gust?: number;
+    /** m/s the gust pattern travels at. Default 5.6 (20 km/h). */
+    gustSpeed?: number;
 };
 export type FoliageOptions = {
     /** The wind, or `false` for none. */
     wind?: FoliageWind | false;
-    /** Height above the instance origin (m) where the full sway / touch applies; the base never moves.
-     *  Default 1.5. */
-    bendHeight?: number;
     /** Metres the TOP of a small plant leans away from a bender standing at its centre; the whole plant leans
      *  as one, rooted at its base. Plants over ~2 m react less, trees over ~5 m not at all (the engine
      *  measures each asset). Default 0.6. 0 = no touch reaction. */
@@ -25,6 +26,28 @@ export type FoliageOptions = {
     variation?: number;
     /** 0..1: wrapped sun lighting — thin leaves let light through. Default 0.5. */
     sunWrap?: number;
+    /** A multiplier on every material's shiver drag (the leaves' own motion on top of the bend): 1 = as the
+     *  model's materials say, 0 = the leaves ride the bend alone. Default 1. */
+    shiver?: number;
+    /** 0..1: the sun through a thin leaf lit from behind (a back-lit crown glows). Default 0.35. */
+    translucency?: number;
+    /** 0..1: how much of a light's shadow a leaf card takes. A crown scatters light through itself, so its cards take the
+     *  shadow map partly — at 1 a distant crown is a dark silhouette lit only on its top layer. Bark always takes the
+     *  shadow in full. Default 0.6. */
+    leafShadow?: number;
+    /** 0..1: how far the baked per-vertex sky visibility (the crown's interior, the trunk under it) darkens the ambient.
+     *  Default 0.7. */
+    skyAo?: number;
+    /** 0..1: a leaf card's shading normal, from the card's own plane (0) to the crown's hull normal (1) — what hides that a
+     *  crown is flat quads: each card is lit as the part of the volume it sits in. Default 0.7. */
+    canopy?: number;
+    /** The cards' normal-map strength (a strong map brings the planes back). Default 0.5. */
+    normalMap?: number;
+    /** A card seen edge-on dissolves over this much of |N·V| — no paper edges on the silhouette. Default 0.15, 0 = none. */
+    edgeFade?: number;
+    /** Coverage held over distance: the cards' alpha × (1 + coverage × mip level), so a far crown does not thin out as its
+     *  atlas mips away. Default 0.25, 0 = none; past ~0.5 a crown turns into a solid mass. */
+    coverage?: number;
 };
 export declare const Foliage: {
     /** Level-wide options; each field given replaces the current value (a scene file's `env.foliage`

package/dist/types/gl/Light.d.ts

@@ -22,6 +22,9 @@ export type SunOptions = {
      *   3 - 2048 map, contact-hardening soft edges (PCSS: sharp where the caster touches, softer
      *       away; discrete-GPU territory, ~+60 % of a frame on an iGPU)
      * A lightmapped level already carries every static shadow, so 0 is a legitimate choice there.
+     * On a level with a baked light grid the variance / PCSS filters cannot be used (they need every
+     * receiver in the shadow map, and the baked statics are kept out of it): 3 renders as PCSS on the
+     * depth map - the same contact-hardening look - and 2 renders as 1.
      */
     shadowsQuality?: 0 | 1 | 2 | 3;
     /**
@@ -30,6 +33,13 @@ export type SunOptions = {
      * the same quality and puts fewer casters in the shadow pass. 30-40 is plenty in first person.
      */
     shadowDistance?: number;
+    /**
+     * How many shadow-map cascades split `shadowDistance` (default 1). One map over the whole range gives a tall
+     * tree 5-10 cm shadow texels on its own trunk; 3 cascades put a tight map on the first metres and coarser
+     * ones behind, fit to their texel grids so the shadow does not swim as the camera moves. Each cascade is
+     * another caster pass, so it costs in proportion to what casts: forests, not a lightmapped level.
+     */
+    shadowCascades?: 1 | 2 | 3 | 4;
 };
 export type PointOptions = {
     /**
@@ -71,6 +81,7 @@ export declare class Light extends Node {
     /** The most recently created sun. */
     static lastSun: Light | null;
     _shadowDistance: number;
+    _shadowCascades: number;
     /** A directional sun light. */
     static sun(options?: SunOptions): Light;
     /**

package/dist/types/gl/Lightmap.d.ts

@@ -93,6 +93,17 @@ export declare class Lightmap {
     private static loadVolume;
     /** Forget every registration (a scene rebuild). */
     static clear(): void;
+    /** THE MOVERS' SUN SHADOWS ON THE BAKED STATICS (a bot, a barrel, the player's rifle darkening the ground under
+     *  it): the lightmap shader reads the real-time shadow map and the bake's sun map for it, per pixel. Off, a baked
+     *  surface takes no real-time shadow at all — the cheapest lighting tier (some 4 ms of a 16 ms 720p frame on an
+     *  integrated GPU, the yard 2026-09-26); a mover still shades ITSELF and the other movers. Live: it rebinds the
+     *  level's material instances at once. */
+    static get moverShadows(): boolean;
+    static set moverShadows(on: boolean);
+    private static _moverShadows;
+    /** The loaded bake's sun (TO the sun ×3, its illuminance rgb, the sun map's levels), null without a sun map. */
+    private static sunArgs;
+    private static applySun;
     /** Apply a bake — or, under `lecodes lightmap bake`, run it. Resolves to null when nothing was
      *  applied (no bake yet, a host without the feature, bake mode). */
     private static scene;
@@ -116,8 +127,8 @@ export declare class Lightmap {
      *  so the value can be looked up in the bake's debug layers (`lecodes lightmap inspect`). null when
      *  nothing baked is under the point or the host has no triangle pick. */
     static probe(screenX: number, screenY: number): LightmapProbe | null;
-    /** A hex colour as the 9-char form the float4 uniform path expects ("#rrggbbaa"). */
-    private static hex8;
+    /** A material's colour uniform as "#rrggbbaa" (the float4 uniform path sets its alpha); white without one. */
+    private static colorUniform;
     /** The lightmap material for a static Mesh, from whatever lit material it carried (colour, map, roughness, metallic). */
     private static meshMaterial;
     private static bake;

package/dist/types/gl/Material.d.ts

@@ -123,7 +123,7 @@ export declare class Material {
     readonly shader: FetchResponse | "unknown";
     readonly uniforms: Record<string, UniformValue>;
     private _colorKey;
-    constructor(shader: FetchResponse | number);
+    constructor(shader: FetchResponse | Handle | number);
     /** Set a uniform (chainable). */
     set(key: string, value: UniformValue): this;
     set color(c: ColorInput);
@@ -137,6 +137,8 @@ export declare class Material {
     /** The stencil test / write (write-only; `null` = back to none). See `MaterialStencil`. */
     set stencil(s: MaterialStencil | null);
     set map(value: Texture | Canvas | null);
+    /** The material an instance handle is of; a host that carries none under `name` is an error naming it. */
+    private static _builtin;
     /** PBR lit material. */
     static lit(options?: LitMaterialOptions): Material;
     /** Unlit (flat) material — opaque unless `transparent` asks for alpha blending. */
@@ -151,7 +153,7 @@ export declare class Material {
     static decal(options?: DecalMaterialOptions): Material;
     /** Material that samples a VideoPlayer's texture. */
     static video(map?: Texture): Material;
-    /** The lightmap material (packages/creator-bake): a lit PBR material whose whole DIFFUSE light is the
+    /** The lightmap material (engines/bake): a lit PBR material whose whole DIFFUSE light is the
      *  baked irradiance atlas on UV1 (`lightmapLight`, lux) — the real-time sun, lamps and diffuse IBL do not
      *  touch it; the specular IBL stays, occluded by the baked sky visibility. Models take it through
      *  `Model.load(…, { lightmap: true })`; a static Mesh gets one from here. Parameters use gltfio's names
@@ -161,6 +163,17 @@ export declare class Material {
     /** `Material.lightmap()`'s masked twin (`blending: masked`, same shader and parameters): what the engine
      *  gives a lightmapped model's alpha-MASK materials. The cutoff comes from the glTF material. */
     static lightmapMasked(): Material;
+    /** THE LIGHTMAP SHADER TIER, engine-wide: `"full"` = the target's own blob (desktop: the bicubic atlas fetch, eight
+     *  probe corners, the sun's highlight on metal), `"lite"` = the blob the phones ship (bilinear fetch, one probe
+     *  corner, no sun highlight; the movers' shadows on the statics stay) — on an integrated GPU some 30 % less per
+     *  pixel on a baked level, the picture a phone shows. Read when a lightmap material is FIRST made, which
+     *  `Model.load({ lightmap })` does once per world: set it BEFORE the level loads (a graphics preset applied at
+     *  boot, like `Texture.maxSize`); a change afterwards takes the next level. A host without the lite material
+     *  (a phone: its own blob is that shader already) takes the full one. */
+    static lightmapShading: "full" | "lite";
+    /** The lite tier's instance, or — said once — that this host has none and the full shader is used. */
+    private static _liteTier;
+    private static _liteWarned;
     /** The terrain splat material (docs/terrain-plan.md §1.5): four albedo (+ normal-map) layers blended by
      *  a control map on the terrain's own grid, per-layer `tiling` (metres per repeat) / `roughness` /
      *  `normalScale` / `triplanar`. `Terrain` builds and owns one per terrain; the uniforms are primed here so an
@@ -186,8 +199,9 @@ export declare class Material {
     private static _glbDefaults;
     private static _lightmapDefaults;
     private static _folTemplate;
-    static _foliageMaskedTemplate(): Material;
+    static _foliageMaskedTemplate(): Material | null;
     private static _folMaskedTemplate;
+    private static _glbTemplate;
     /** Shadow-catcher material (transparent except where shadows fall). */
     static shadow(color?: ColorInput): Material;
     /** Load a custom compiled shader (.mat URL) as a material. */

package/dist/types/gl/Model.d.ts

@@ -12,12 +12,16 @@ export interface TrianglePick {
     mesh: string;
     primitive: number;
     material: string;
+    /** the node's lightmap group (scene-file extras), when it has one */
+    lightmapGroup?: number;
     /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
     triangle: number;
     backface: boolean;
     distance: number;
     point: [number, number, number];
     bary: [number, number, number];
+    /** the lightmap uv (TEXCOORD_1) at the hit, when the primitive carries one */
+    uv1?: [number, number];
     skin: string;
     vertices: {
         index: number;
@@ -33,7 +37,7 @@ export declare class Model extends Node {
     /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
      *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
     readonly anim: Animator;
-    constructor(internalId: number);
+    constructor(internalId: number | Handle);
     /** Does this model cast a real-time shadow? Unlike Mesh (one renderable) a GLB is a whole
      *  hierarchy, so the flag goes to EVERY renderable of the instance. A first-person viewmodel —
      *  arms, weapon, attachments — sets it false: it lives in front of the camera and its shadow
@@ -77,7 +81,7 @@ export declare class Model extends Node {
             loaded: number;
             total?: number;
         }) => void;
-        /** Baked lighting (packages/creator-bake). `true` = a STATIC: loads through the lightmap material so
+        /** Baked lighting (engines/bake). `true` = a STATIC: loads through the lightmap material so
          *  `Lightmap.load` can bind its atlas rect (the GLB needs TEXCOORD_1 — `lecodes assets doctor
          *  --lightmap-uv`) and takes nothing from the real-time lights once the bake applies. Omitted / `false` =
          *  the standard shader, lit real-time (movers). Hosts without lightmap support ignore it. */

package/dist/types/gl/Node.d.ts

@@ -1,5 +1,4 @@
 import { AspectHost } from "../core/Aspect";
-import { Registry } from "../core/registry";
 import { Vec3, type Vec3Like } from "../math/vec";
 import { Quat, type QuatLike } from "../math/quat";
 import { Mat4, type Mat4Like } from "../math/mat4";
@@ -18,8 +17,6 @@ export type NodeTweenProps = {
     /** Degrees, YXZ; interpolated per axis without shortest-arc, so `[0, 720, 0]` spins twice. */
     eulerAngles?: Vec3Like | Vec3Like[];
 };
-/** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
-export declare const nodeRegistry: Registry<Node>;
 export type NodeEvents = {
     click: (ev: ClickEvent<Node | null>) => void;
     touchstart: (ev: TouchStartEvent<Node | null>) => void;
@@ -33,8 +30,8 @@ export type NodeEvents = {
     exit: (other: Node) => void;
 };
 export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
-    /** Native entity handle. */
-    readonly id: number;
+    /** Native entity id. */
+    get id(): number;
     /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
      *  'track' / 'untrack' events; `false` for any non-anchor node. */
     isTracked: boolean;
@@ -43,7 +40,7 @@ export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
     private _boneCache?;
     /** Materials assigned through setMaterial, by primitive slot (a Mesh fills slot 0 itself). */
     protected _materials?: Material[];
-    constructor(internalId?: number);
+    constructor(internalId?: number | Handle);
     /** Geometry, if this node is a Mesh (used by physics auto-shape). Overridden by Mesh. */
     get geometry(): Geometry | undefined;
     get name(): string;

package/dist/types/gl/Particles.d.ts

@@ -184,6 +184,15 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
      *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
      *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
     order?: number;
+    /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+     *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
+     *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
+     *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's
+     *  share of it (tinted the way the shade is) under a roof — per particle, so a trail of puffs laid from the sun
+     *  into the shade is lit along its length. Author the colour for the open; nothing else to tune. Without a grid
+     *  — a level with no bake, a host that has none — the colours are drawn as authored. Points, quads, stretch and
+     *  `Trail`; mesh particles are lit by their material. Default false. */
+    lit?: boolean;
     /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
      *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
      *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
@@ -234,6 +243,8 @@ export declare class Particles extends Node {
     /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
     set smooth(val: boolean);
     set order(val: number);
+    /** Colours × the baked light where each particle is — see `ParticlesOptions.lit`. */
+    set lit(val: boolean);
     /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
     set renderPriority(v: number);
     set velocityOverLife(v: VelocityOverLife);
@@ -279,6 +290,9 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
      *  frame rate, since a longer frame bows further off its own chord. Default false; see
      *  `ParticlesOptions.smooth`. */
     smooth?: boolean;
+    /** The strip takes the baked light of the place each of its points is at — `ParticlesOptions.lit`. Smoke and
+     *  dust trails; leave it off for a glowing one. Default false. */
+    lit?: boolean;
     /** Which way the strip's WIDTH points.
      *
      *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
@@ -317,6 +331,7 @@ export declare class Trail extends Node {
     set minDistance(val: number);
     /** Follow a curve through the emitter's path instead of the straight chord between frames. */
     set smooth(val: boolean);
+    set lit(val: boolean);
     /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
     set orient(val: "camera" | "x" | "y" | "z");
     /** The hybrid's floor — see `TrailOptions.faceCamera`. */

package/dist/types/gl/Scene.d.ts

@@ -1,6 +1,6 @@
 import { type ColorInput } from "../core/color";
 import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
-import { Presentable, type PresentOptions } from "../ui/presentable";
+import { Presentable, type DismissOptions, type PresentOptions } from "../ui/presentable";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
 import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
@@ -18,6 +18,20 @@ export type AmbientOcclusionOptions = {
     /** Sample count + filtering (default 'medium'). Not the buffer resolution — that stays half. */
     quality?: "low" | "medium" | "high" | "ultra";
 };
+/** `SceneOptions.taa` / `scene.setAntialias("taa", 4, taa)`: the temporal anti-aliasing knobs. */
+export type TaaOptions = {
+    /** Render the 3D at this fraction (0.5–1) and TAA-upscale it to the viewport; 1 = none. */
+    upscale?: number;
+    /** The history's share, 0 (max smoothing) … 1 (none); 0.12 default. */
+    feedback?: number;
+    /** Post-TAA sharpen 0–1; defaults to 0.5 with `upscale` below 1, else 0. */
+    sharpness?: number;
+    /** A first-person viewmodel: everything closer than this many metres to the camera is treated as
+     *  fixed on screen — its history is read at the same pixel, not reprojected by the camera's motion,
+     *  which would trail the weapon on every turn (TAA has no per-object motion vectors). 1 covers arms
+     *  and weapon at eye height; 0 (the default) = off. A wall walked into within the band smears a little. */
+    viewmodel?: number;
+};
 export type FogOptions = {
     /** A TINT on the in-scattered ambient, not an absolute colour: the engine multiplies it by the
      *  environment luminance, so white (the default) means "fog as bright as the ambient" and the fog
@@ -92,10 +106,18 @@ export type SceneOptions = {
      *  at every distance — the skybox included — so the sky itself takes the fog colour and the horizon
      *  blends on its own; `cutoff` opts geometry beyond a distance back out. */
     fog?: FogOptions;
-    /** Multisample anti-aliasing: `true` = 4×, `2`/`4` = that many samples, `false` = off (FXAA
-     *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
-     *  fill-rate cost after resolution — turn it down on big screens before anything else. */
-    antialias?: boolean | 2 | 4;
+    /** Anti-aliasing: `true` = 4× MSAA, `2`/`4` = that many samples, `false` = off (FXAA takes over),
+     *  `"taa"` = temporal anti-aliasing (Filament's TAA: one full-screen history blend instead of the
+     *  multisampled buffers — cheaper than MSAA on an integrated GPU and it also calms specular and
+     *  foliage shimmer; see `taa` for its knobs). Unset keeps the host default (desktop 4×, mobile/web
+     *  off). The biggest single fill-rate cost after resolution — turn it down on big screens first. */
+    antialias?: boolean | 2 | 4 | "taa";
+    /** The TAA's knobs (`antialias: "taa"`): `upscale` = render the 3D at this fraction (0.5–1) and let
+     *  TAA reconstruct the full resolution — the cheap way to a lower render cost with most of the
+     *  detail kept (`renderScale` shrinks the buffer and stretches it instead); `feedback` = the
+     *  history's share, 0.12 by default (raise it toward 0.3 if fast motion ghosts); `sharpness` =
+     *  a post-TAA sharpen 0–1, useful with `upscale`. */
+    taa?: TaaOptions;
     /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
      *  Needed before any material's `stencil` test or write does anything. */
     stencil?: boolean;
@@ -152,7 +174,8 @@ export declare class Scene implements Presentable {
     setRenderOptions(renderScale: number, dynamicResolution?: boolean | {
         min?: number;
     }): void;
-    /** Scene occlusion material. */
+    /** Scene occlusion material: an unlit instance in the occluder blue (the built-in `unlit`, which
+     *  every runtime carries) — one per scene, made on first use. */
     get occlusionMaterial(): Material;
     set skybox(sky: ColorInput | "environment" | {
         texture: string;
@@ -162,7 +185,7 @@ export declare class Scene implements Presentable {
     /** Runtime form of `fog` (weather, entering a building). `false` turns it off. */
     setFog(options: FogOptions | false): void;
     setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void;
-    setAntialias(enabled: boolean, scale?: number): void;
+    setAntialias(mode: boolean | 2 | 4 | "taa", scale?: number, taa?: TaaOptions): void;
     /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
      *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
      *  frame). Off = hard-edged particles, no decals, no pre-pass. Engine-wide, live. */
@@ -189,8 +212,8 @@ export declare class Scene implements Presentable {
     private static _warnedEnvIntensity;
     /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
     setStencil(enabled: boolean): void;
-    add(...nodes: Node[]): this;
-    remove(...nodes: Node[]): this;
+    add(...list: Node[]): this;
+    remove(...list: Node[]): this;
     /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed
      *  as now-having it (`scene.system(Hud).hud`). A `System<'x', Scene2D>` is rejected here. */
     system<Self extends TargetOf<A>, A extends Aspect<any, any, any>>(this: Self, ctor: AspectCtor<A>, opts?: Partial<A>): Self & FieldOf<A>;
@@ -219,11 +242,16 @@ export declare class Scene implements Presentable {
     onOpen(callback: () => void): this;
     /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
     onClose(callback: () => void): this;
+    /** Hardware/system back while the scene is current. */
+    onBack(callback: () => void): this;
+    /** @deprecated Renamed `onBack` (2026-09-26). An alias for the projects compiled before the
+     *  rename; removed with the release that recompiles them. */
     onBackPressed(callback: () => void): this;
     /** Make this the active scene — shows it as the current destination (replaces a screen /
-     *  another scene; only the active scene renders). */
+     *  another scene; only the active scene renders). The runtime activates the engine as part of
+     *  presenting the destination. */
     open(options?: PresentOptions): void | Promise<void>;
-    close(): void;
+    close(options?: DismissOptions): void;
     addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void;
     addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node | null>) => void): void;
     removeEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void;
@@ -248,7 +276,7 @@ export declare class ARScene<T extends ARMode = "default"> extends Scene {
      */
     addControls(target: Node, options?: ControlsOptions): ControlsHandle;
     open(options?: PresentOptions): Promise<void>;
-    close(): void;
+    close(options?: DismissOptions): void;
 }
 /**
  * A 3D scene rendered in a VR headset (OpenXR — e.g. Meta Quest). The headset drives the camera:
@@ -260,5 +288,5 @@ export declare class ARScene<T extends ARMode = "default"> extends Scene {
  */
 export declare class VRScene extends Scene {
     open(options?: PresentOptions): Promise<void>;
-    close(): void;
+    close(options?: DismissOptions): void;
 }

package/dist/types/gl/Texture.d.ts

@@ -29,7 +29,7 @@ export declare class Texture {
     wrapS: number;
     /** Vertical wrap mode (V). */
     wrapT: number;
-    constructor(width: number, height: number, id: number);
+    constructor(width: number, height: number, id: Handle | number);
     static fromCanvas(canvas: {
         _bakeSurface(): number;
         width: number;