@babylonjs/lite 0.1.1 → 0.2.0

package/index.d.ts

@@ -48,6 +48,15 @@ export declare function addBillboardSpriteIndex(system: BillboardSpriteSystem, p
  */
 export declare function addBoxObstacle(plugin: NavigationPlugin, position: Vec3, halfExtents: Vec3, angle: number): ObstacleHandle | null;
 
+/**
+ * Register a clustered light container on a scene, building its GPU state and
+ * wiring it into the PBR materials already present in the scene.
+ *
+ * @param scene - The scene to attach the container to.
+ * @param container - The clustered light container to register.
+ */
+export declare function addClusteredLightContainer(scene: SceneContext, container: ClusteredLightContainer): void;
+
 /**
  * Add a cylinder obstacle to a tile-cache navmesh.
  *
@@ -124,9 +133,11 @@ export declare function addTaskBefore(target: FrameGraph | SceneContext, task: T
 export declare function addThinInstance(mesh: Mesh, matrix: Mat4): number;
 
 /**
- * Adds an entity to the scene, dispatching on its type. Asset containers are unpacked and
- * each contained entity added recursively; meshes, lights, cameras, transform nodes, and
- * shadow generators are registered in their respective scene collections.
+ * Adds an entity (mesh, light, camera, transform node, shadow generator, or asset container)
+ * to the scene, dispatching on its type. Asset containers are unpacked and each contained
+ * entity added recursively. Optional scene-hosted systems such as depth-hosted sprites
+ * expose their own opt-in add functions so mesh-only scenes do not pay feature-specific
+ * routing bytes here.
  * @param scene - The owning scene (pillar 4b: entities never reference the scene themselves).
  * @param entity - The entity (or asset container) to add.
  */
@@ -338,11 +349,39 @@ export declare interface ArcRotateCamera extends Camera, IWorldMatrixProvider, I
     inertialRadiusOffset: number;
     inertialPanningX: number;
     inertialPanningY: number;
-    parent: IWorldMatrixProvider | null;
+    /**
+     * Optional orbit limits enforced by {@link attachControl}'s per-frame loop.
+     * `undefined` means unbounded on that side. Set these via {@link setCameraLimits}
+     * so the current pose is clamped immediately (and inertia zeroed at the wall),
+     * avoiding any overshoot-then-snap jiggle. Angles are in radians.
+     */
+    lowerAlphaLimit?: number;
+    upperAlphaLimit?: number;
+    lowerBetaLimit?: number;
+    upperBetaLimit?: number;
+    lowerRadiusLimit?: number;
+    upperRadiusLimit?: number;
    parent: IWorldMatrixProvider | null;
     readonly worldMatrix: Mat4;
     readonly worldMatrixVersion: number;
 }
 
+/** Orbit limits for an {@link ArcRotateCamera}. Omit a field to leave that bound
+ *  unbounded; pass an explicit `undefined` to clear a previously-set bound. */
+export declare interface ArcRotateCameraLimits {
+    /** Minimum alpha (orbit) angle, radians. */
+    lowerAlphaLimit?: number;
+    /** Maximum alpha (orbit) angle, radians. */
+    upperAlphaLimit?: number;
+    /** Minimum beta (elevation) angle, radians. */
+    lowerBetaLimit?: number;
+    /** Maximum beta (elevation) angle, radians. */
+    upperBetaLimit?: number;
+    /** Minimum radius (closest zoom). */
+    lowerRadiusLimit?: number;
+    /** Maximum radius (farthest zoom). */
+    upperRadiusLimit?: number;
+}
+
 /**
  * Result returned by loadGltf / loadBabylon.
  * Pass directly to addToScene() — it handles all fields automatically.
@@ -378,7 +417,11 @@ export declare interface AssetContainer {
  * - Pinch: zoom (touch, direct — no inertia)
  *
  * Input handlers accumulate into the camera's inertial offset properties.
- * Inertia is applied each frame via scene._beforeRender (single RAF loop).
+ * Inertia is applied each frame via scene._beforeRender (the engine's render
+ * loop); a scene is required for inertia, there is no standalone rAF fallback.
+ *
+ * Orbit/zoom limits are entirely opt-in via {@link setCameraLimits}; the camera
+ * self-clamps in its setters, so this loop carries no limit code.
  *
  * Camera stays plain data — this function reads/writes its properties.
  * Returns a cleanup function to remove all listeners and the beforeRender hook.
@@ -596,7 +639,13 @@ export declare interface BlurPostProcessTaskConfig extends Omit<PostProcessTaskC
 
 /** Minimal camera contract — any camera that can provide view/projection matrices.
  *  Both ArcRotateCamera and FreeCamera implement this interface.
- *  Pure state, no scene knowledge (pillar 4b). */
+ *  Pure state, no scene knowledge (pillar 4b).
+ *
+ *  The view/projection matrix caches below are allocated by the camera factory
+ *  via the process-global `allocateMat4()` singleton — F32 by default, F64
+ *  after any HPM engine is constructed (see
+ *  `docs/architecture/33-high-precision-matrix.md`). The storage
+ *  type is fixed at construction and never changes. */
 export declare interface Camera {
     fov: number;
     nearPlane: number;
@@ -680,34 +729,72 @@ export declare function clearSpriteAnimations(manager: SpriteAnimationManager):
 /** A clipping plane expressed as the coefficients `[a, b, c, d]` of `a·x + b·y + c·z + d`. */
 export declare type ClipPlane = readonly [number, number, number, number];
 
+/** Create a fresh Texture2D wrapper that shares GPU resources with `base`
+ *  but carries its own UV transform. Use this when the same underlying image
+ *  is referenced with different transforms (e.g. glTF KHR_texture_transform
+ *  on different textureInfos pointing at the same source). The caller is
+ *  responsible for acquireTexture/release pairing if the wrapper outlives
+ *  the base. */
+export declare function cloneTexture2D(base: Texture2D, transform: Partial<Pick<Texture2D, "uScale" | "vScale" | "uOffset" | "vOffset" | "uAng">> & {
+    _texCoord?: 0 | 1;
+    _hasTx?: true;
+}): Texture2D;
+
 /** Deep-clone a SceneNode tree. Meshes are shallow-cloned (shared GPU buffers).
  *  Lights, cameras, and other non-mesh/non-TN children are shallow-cloned. */
 export declare function cloneTransformNode(src: SceneNode): SceneNode;
 
+/**
+ * Holds a large set of point lights that are binned into screen-space clusters
+ * on the GPU, so PBR materials can shade hundreds of lights efficiently. Add it
+ * to a scene with {@link addClusteredLightContainer}.
+ */
 export declare interface ClusteredLightContainer {
+    /** Discriminant tag identifying this object as a clustered light container. */
     readonly kind: "clusteredLightContainer";
+    /** The point lights managed by this container. */
     pointLights: ClusteredPointLight[];
+    /** Number of cluster tiles across the screen horizontally. */
     horizontalTiles: number;
+    /** Number of cluster tiles across the screen vertically. */
     verticalTiles: number;
+    /** Number of depth slices used to bin lights along view-space Z. */
     zSlices: number;
 
+/** Options for {@link createClusteredLightContainer}. */
 export declare interface ClusteredLightContainerOptions {
+    /** Number of cluster tiles across the screen horizontally. Default `64`. */
     horizontalTiles?: number;
+    /** Number of cluster tiles across the screen vertically. Default `64`. */
     verticalTiles?: number;
+    /** Number of depth slices used to bin lights along view-space Z. Default `16`. */
     zSlices?: number;
 }
 
+/**
+ * A single point light stored inside a {@link ClusteredLightContainer}. Plain
+ * data — created via {@link createClusteredPointLight} and mutated in place.
+ */
 export declare interface ClusteredPointLight {
+    /** World-space position `[x, y, z]`. */
     position: [number, number, number];
+    /** Diffuse colour `[r, g, b]` in linear space. */
     diffuse: [number, number, number];
+    /** Falloff range in world units. */
     range: number;
+    /** Light intensity multiplier. */
     intensity: number;
 }
 
+/** Options for {@link createClusteredPointLight}. */
 export declare interface ClusteredPointLightOptions {
+    /** World-space position `[x, y, z]`. */
     position: [number, number, number];
+    /** Diffuse colour `[r, g, b]` in linear space. */
     diffuse: [number, number, number];
+    /** Falloff range in world units. Default `1`. */
     range?: number;
+    /** Light intensity multiplier. Default `1`. */
     intensity?: number;
 }
 
@@ -802,6 +889,26 @@ export declare function createBox(engine: EngineContext, size?: number): Mesh;
  */
 export declare function createChromaticAberrationPostProcessTask(config: ChromaticAberrationPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): ChromaticAberrationPostProcessTask;
 
+/**
+ * Create an empty {@link ClusteredLightContainer}. Add point lights with
+ * {@link createClusteredPointLight}, then register it on a scene via
+ * {@link addClusteredLightContainer}.
+ *
+ * @param options - Optional cluster tiling overrides.
+ * @returns A new, empty clustered light container.
+ */
+export declare function createClusteredLightContainer(options?: ClusteredLightContainerOptions): ClusteredLightContainer;
+
+/**
+ * Add a point light to a clustered light container.
+ *
+ * @param container - The container to add the light to.
+ * @param options - The light's position, colour and (optional) range/intensity.
+ * @returns The created light (also pushed onto `container.pointLights`); mutate
+ * it in place and call {@link markClusteredLightContainerDirty} to animate it.
+ */
+export declare function createClusteredPointLight(container: ClusteredLightContainer, options: ClusteredPointLightOptions): ClusteredPointLight;
+
 /**
  * Builds a {@link Csg2Solid} from a mesh's CPU geometry, baking its world transform.
  * @param mesh - Source mesh; must retain CPU positions, normals, and indices.
@@ -818,6 +925,22 @@ export declare function createCsg2FromMesh(mesh: Mesh, materialSlot?: number): C
  */
 export declare function createCsgFromMesh(mesh: Mesh, materialSlot?: number): CsgSolid;
 
+/**
+ * Creates a cascaded shadow map (CSM) generator for a directional light.
+ *
+ * The shadow map is a `depth32float` `texture_2d_array` with one layer per
+ * cascade; each cascade is fit to a logarithmic/uniform slice of the active
+ * camera frustum and sampled on the receiver with a 5×5 PCF kernel. Casters are
+ * supplied via {@link setShadowTaskCasterMeshes} and the receiver is any mesh
+ * with `receiveShadows = true`.
+ *
+ * @param engine - The engine providing the GPU device.
+ * @param _light - The directional light that casts the shadows.
+ * @param cfg - Optional cascade, map-size and bias configuration.
+ * @returns A `ShadowGenerator` wired to the CSM render path.
+ */
+export declare function createCsmDirectionalShadowGenerator(engine: EngineContext, _light: DirectionalLight, cfg?: CsmDirectionalShadowGeneratorConfig): ShadowGenerator;
+
 /** Create a cylinder (or cone / truncated cone / prism) mesh. Caller must assign material. */
 export declare function createCylinder(engine: EngineContext, options?: CylinderOptions): Mesh;
 
@@ -1282,6 +1405,18 @@ export declare function createTexture2DFromPixels(engine: EngineContext, data: U
 /** Create a torus mesh. Caller must assign material. */
 export declare function createTorus(engine: EngineContext, options?: TorusOptions): Mesh;
 
+/** Create a torus-knot mesh. Caller must assign material. */
+export declare function createTorusKnot(engine: EngineContext, options?: TorusKnotOptions): Mesh;
+
+/**
+ * Builds the CPU vertex data for a torus knot, matching Babylon.js byte-for-byte
+ * (same curve math, same Frenet frame, same ComputeNormals, same index winding).
+ *
+ * @param opts - Optional radius / tube / segmentation / winding parameters.
+ * @returns Tightly-packed `positions`, `normals`, `uvs` and `indices` typed arrays.
+ */
+export declare function createTorusKnotData(opts?: TorusKnotOptions): TorusKnotData;
+
 /** Create a TransformNode (SceneNode) with TRS values and lazy world matrix.
  *  Parameters: name, position (px,py,pz), rotation quaternion (qx,qy,qz,qw), scaling (sx,sy,sz). */
 export declare function createTransformNode(name: string, px?: number, py?: number, pz?: number, qx?: number, qy?: number, qz?: number, qw?: number, sx?: number, sy?: number, sz?: number): TransformNode;
@@ -1354,6 +1489,30 @@ export declare function csgSubtract(a: CsgSolid, b: CsgSolid): CsgSolid;
  */
 export declare function csgUnion(a: CsgSolid, b: CsgSolid): CsgSolid;
 
+/** Configuration for a directional-light cascaded shadow generator. */
+export declare interface CsmDirectionalShadowGeneratorConfig {
+    /** Shadow map resolution per cascade (square). Default 1024. */
+    mapSize?: number;
+    /** Number of cascades. Default 4 (max 4). */
+    numCascades?: number;
+    /** Split blend between logarithmic and uniform partitioning, 0..1. Default 0.5. */
+    lambda?: number;
+    /** Fraction of a cascade used to cross-fade into the next one. Default 0.1. Set 0 to disable blending. */
+    cascadeBlendPercentage?: number;
+    /** Use a stable bounding-sphere fit (no shimmering) instead of a tight AABB fit. Default false. */
+    stabilizeCascades?: boolean;
+    /** Maximum shadow distance in world units. Default = camera far plane. */
+    shadowMaxZ?: number;
+    /** Depth bias added during shadow-map generation. Default 0.00005. */
+    bias?: number;
+    /** Shadow darkness (0 = black shadow, 1 = no shadow). Default 0. */
+    darkness?: number;
+    /** Soft fade-out at the edge of each cascade frustum, 0..1. Default 0. */
+    frustumEdgeFalloff?: number;
+    /** Regenerate every cascade every frame even when nothing moved. Default false. */
+    forceRefreshEveryFrame?: boolean;
+}
+
 /** One extra texture bound after the atlas. In WGSL it becomes `<name>Tex` + `<name>Samp`. */
 export declare interface CustomShaderTexture {
     /** Identifier used in WGSL: becomes `<name>Tex` (texture) and `<name>Samp` (sampler). */
@@ -1549,6 +1708,21 @@ export declare function enableAnimationBlending(manager: AnimationManager): void
  */
 export declare function enableDetailedPicking(picker: GpuPicker): void;
 
+/**
+ * Enable material-plugin support for `scene`.
+ *
+ * - Registers the PBR plugin bridge: its `detect` hook encodes a per-signature
+ *   index into each PBR material's feature bits during the build, so no mesh
+ *   walk is needed here.
+ * - Registers the Standard plugin bridge and walks `scene.meshes`, pre-baking a
+ *   per-signature index into every Standard plugin material's cached
+ *   `_renderFeatures` (Standard's feature computation is not ext-extensible, so
+ *   the index must be baked in up front). Standard plugin uniforms are delivered
+ *   through a self-managed uniform buffer built here and bound via the
+ *   pre-existing `StdExt._bind` loop.
+ */
+export declare function enableMaterialPlugins(scene: SceneContext): void;
+
 /** Enable automatic dirty tracking on a PBR or Standard material.
  *  After calling this, any UBO-backed property mutation marks the source material UBO dirty. */
 export declare function enableMaterialTracking(material: Material & {
@@ -1558,6 +1732,10 @@ export declare function enableMaterialTracking(material: Material & {
 /** Enables weighted property-animation blending on `manager` by registering its category handler. */
 export declare function enablePropertyAnimationBlending(manager: AnimationManager): void;
 
+export declare function enableRenderTaskTransmission(task: RenderTask, engine: EngineContext, options?: TransmissionOptions): SceneColorGrab;
+
+export declare function enableSceneTransmission(scene: SceneContext, engine: EngineContext): void;
+
 /** Enable or disable GPU frustum culling for an existing thin-instanced mesh.
  *
  * Call this after `setThinInstances()`/`addThinInstance()` and before `registerScene()`.
@@ -1578,6 +1756,22 @@ export declare interface EngineContext {
     readonly format: GPUTextureFormat;
     /** Number of GPU draw calls in the last rendered frame. */
     drawCallCount: number;
+    /**
+     * When true, world matrices are computed using Float64 intermediate precision
+     * and downcast to Float32 at GPU upload time. Defaults to false.
+     */
+    useHighPrecisionMatrix: boolean;
+    /**
+     * When true, every scene on this engine uses the floating-origin (eye-relative
+     * upload) trick to render large-world coordinates without F32 jitter. Requires
+     * `useHighPrecisionMatrix: true`. Defaults to false.
+     *
+     * LWR is engine-wide: all scenes created against this engine inherit the
+     * mode. The LWR runtime module (`large-world/floating-origin.js`) is
+     * dynamically imported during `createEngine` only when this flag is true,
+     * so non-LWR engines never pull the module into their bundle.
+     */
+    useFloatingOrigin: boolean;
     /** Clamps the effective device pixel ratio used for the swapchain backing store.
      *  The backing store is sized at `min(devicePixelRatio, maxDevicePixelRatio) * cssPixels`.
      *  `maxDevicePixelRatio = 1` renders at native CSS-pixel resolution (no DPR upscaling);
@@ -1598,6 +1792,21 @@ export declare interface EngineOptions {
      * with `alpha < 1` will let HTML content underneath show through). Defaults to "opaque".
      */
     alphaMode?: GPUCanvasAlphaMode;
+    /**
+     * Enable Float64 intermediate precision for world matrix computations. Defaults to false.
+     */
+    useHighPrecisionMatrix?: boolean;
+    /**
+     * Enable floating-origin (Large World Rendering) for every scene on this engine.
+     * Requires `useHighPrecisionMatrix: true` — throws synchronously if set without it.
+     * Defaults to false.
+     *
+     * When true, `createEngine` dynamically imports the LWR runtime
+     * (`large-world/floating-origin.js`) so engines without LWR never pull the
+     * module into their bundle (tree-shaken via the dynamic-import gate, same
+     * pattern as the F64 storage module).
+     */
+    useFloatingOrigin?: boolean;
     /**
      * Clamps the effective device pixel ratio used for the swapchain backing store.
      * The backing store is sized at `min(devicePixelRatio, maxDevicePixelRatio) * cssPixels`.
@@ -1805,6 +2014,12 @@ export declare function getClosestPoint(plugin: NavigationPlugin, position: Vec3
 /** Returns the render-target aspect ratio adjusted for the camera's normalized viewport, or the raw ratio if none. */
 export declare function getEffectiveAspectRatio(camera: Camera | null | undefined, targetWidth: number, targetHeight: number): number;
 
+/** Read the current floating-origin offset from a scene as a `Vec3`. The
+ *  offset is the active camera's world position. Returns the zero vector
+ *  when no camera is set (typical headless/precompute case). For non-LWR
+ *  engines this module is not imported, so the function is unreachable. */
+export declare function getFloatingOriginOffset(scene: SceneContext): Vec3;
+
 /** Get the scene's frame graph. Always non-null — created in `createSceneContext`. */
 export declare function getFrameGraph(scene: SceneContext): FrameGraph;
 
@@ -1865,7 +2080,19 @@ export declare function getSprite2DHandleIndex(handle: Sprite2DHandle): number;
  */
 export declare function getVariantNames(container: AssetContainer): readonly string[];
 
-/** Compute the view matrix for a camera. Cached per worldMatrixVersion. */
+/** Compute the view matrix for a camera. Cached per worldMatrixVersion.
+ *
+ *  Floating-origin awareness: when `camera._useFloatingOrigin` is set
+ *  (LWR — wired by the scene's `_update` when the active scene camera is
+ *  bound to an LWR engine), the view matrix translation column is forced
+ *  to zero. The GPU vertex shader then sees the camera at the origin in
+ *  the eye-relative frame, matching the mesh-world UBO pack which
+ *  subtracted the camera position from world translations. View × world
+ *  in the shader produces eye-relative vertex coordinates at full
+ *  precision regardless of how far from world-origin the scene is.
+ *
+ *  When the flag is unset (standard non-LWR rendering), this path is
+ *  bit-identical to a normal `R_inv * -cameraPos` view matrix. */
 export declare function getViewMatrix(camera: Camera): Mat4;
 
 /** Compute the view-projection matrix for a camera. Cached per worldMatrixVersion + aspect. */
@@ -2273,16 +2500,24 @@ export declare function loadSPZ(scene: SceneContext, url: string): Promise<Gauss
  *  @returns A promise resolving to the uploaded `Texture2D`. */
 export declare function loadTexture2D(engine: EngineContext, url: string, opts?: Texture2DOptions): Promise<Texture2D>;
 
+/** Force the container's GPU light state to re-upload next frame. Call after mutating a light's
+ *  position / range / intensity / diffuse in place (e.g. animated lights such as drifting fireflies),
+ *  since those edits don't bump the container version on their own. */
+export declare function markClusteredLightContainerDirty(container: ClusteredLightContainer): void;
+
 /** Mark a material source (or one of its views) as needing UBO re-upload.
  *  The source owns a monotonic version so multiple renderables/views can observe
  *  the same mutation independently without racing on a single cleared boolean. */
 export declare function markMaterialUboDirty(materialOrView: Material): void;
 
-/** 4x4 column-major matrix stored as a flat Float32Array (16 elements).
- *  Layout matches WebGPU/WGSL mat4x4<f32> memory order. */
-declare type Mat4 = Float32Array & {
-    readonly __brand: "Mat4";
-};
+/** 4x4 column-major matrix (16 elements).
+ *  Layout matches WebGPU/WGSL mat4x4<f32> memory order. Opaque-by-convention:
+ *  callers MUST NOT depend on the underlying storage (Float32Array vs
+ *  Float64Array). Internal kernels and uploaders use the `Mat4Storage` view
+ *  defined below to access the concrete typed array behind the brand. */
+export declare interface Mat4 {
    readonly length: 16;
+    readonly [index: number]: number;
+}
 
 /** Compose TRS (translation * rotation * scale) into a single Mat4. */
 export declare function mat4Compose(tx: number, ty: number, tz: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number): Mat4;
@@ -2290,6 +2525,9 @@ export declare function mat4Compose(tx: number, ty: number, tz: number, qx: numb
 /** Create a new identity Mat4. */
 export declare function mat4Identity(): Mat4;
 
+/** Compute inverse of a Mat4. Returns null if singular. */
+export declare function mat4Invert(input: Mat4): Mat4 | null;
+
 /** Create a scaling matrix. */
 export declare function mat4Scale(x: number, y: number, z: number): Mat4;
 
@@ -2304,6 +2542,37 @@ export declare interface Material {
    /** Optional human-readable name. Popula
      *  (e.g. the glTF material name) so callers can look a material up by name. */
     name?: string;
 
+/** Plain-data material plugin. All behaviour is via optional function members. */
+export declare interface MaterialPlugin {
+    /** Stable identifier. Factored into the pipeline cache key. */
+    readonly name: string;
+    /** Lower runs first. Default 500. */
+    priority?: number;
+    /** Default true when attached. A disabled plugin contributes no shader code
+     *  but still changes the pipeline cache key (so toggling forces a rebuild). */
+    isEnabled?: boolean;
+    /** Static defines folded into the pipeline cache key (and available to the
+     *  plugin when it builds its custom code). */
+    defines?: Record<string, boolean | number>;
+    /** Return WGSL snippets keyed by injection point, or null. */
+    getCustomCode?(shaderType: "vertex" | "fragment"): Partial<Record<MaterialPluginPoint, string>> | null;
+    /** Declare custom UBO fields appended to the host material's uniform buffer. */
+    getUniforms?(): {
+        ubo?: PluginUboField[];
+    };
+    /** Declare custom texture/sampler bindings. */
+    getSamplers?(): PluginSamplerDecl[];
+    /** Write this plugin's UBO slice. `offsets` maps field name → byte offset. */
+    writeUbo?(data: Float32Array, offsets: ReadonlyMap<string, number>): void;
+    /** Emit texture bindings in the same order as {@link getSamplers}. */
+    bindTextures?(out: PluginTextureBinding[]): void;
+    /** Enumerate textures for acquire/release bookkeeping. */
+    getActiveTextures?(out: Texture2D[]): void;
+}
+
+/** BJS-compatible injection-point names accepted by {@link MaterialPlugin.getCustomCode}. */
+export declare type MaterialPluginPoint = "CUSTOM_FRAGMENT_DEFINITIONS" | "CUSTOM_FRAGMENT_MAIN_BEGIN" | "CUSTOM_FRAGMENT_UPDATE_ALPHA" | "CUSTOM_FRAGMENT_UPDATE_DIFFUSE" | "CUSTOM_FRAGMENT_BEFORE_LIGHTS" | "CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION" | "CUSTOM_FRAGMENT_BEFORE_FRAGCOLOR" | "CUSTOM_VERTEX_MAIN_BEGIN" | "CUSTOM_VERTEX_UPDATE_WORLDPOS" | "CUSTOM_VERTEX_MAIN_END";
+
 /** Exact material render-feature override used by MaterialView.
  *  Feature bits are interpreted by each concrete material family. */
 export declare interface MaterialRenderFeatures {
@@ -2361,6 +2630,12 @@ export declare interface Mesh extends SceneNode {
     /** User-controlled render order. Lower = drawn first within phase.
      *  Only affects ordering within the opaque or transparent phase. */
     renderOrder?: number;
+    /** On a transmission-enabled render task, draw this transparent mesh LAST — after the transmissive
+     *  surface and after the scene-colour grab — so it sits on top of the water/glass AND is excluded from
+     *  what that surface refracts (e.g. lily pads resting on water should not appear in the refraction).
+     *  Enable transmission on the task with `enableRenderTaskTransmission`; only transparent surfaces
+     *  (`needAlphaBlending`) are deferred. No effect on tasks without transmission. */
+    renderOnTop?: boolean;
     /** Thin instance data (CPU-side). GPU buffer managed by render system. */
     thinInstances?: ThinInstanceData | null;
 
@@ -2672,7 +2947,12 @@ export declare class ObservableQuat implements Quat {
     private _z;
     private _w;
     private readonly _onDirty;
+    /** Bumped on every value change. Lets derived caches (e.g. the Euler proxy) detect
+     *  external quaternion writes and re-sync only when needed. */
+    private _version;
     constructor(x: number, y: number, z: number, w: number, onDirty: () => void);
+    /** Monotonic change counter — incremented whenever any component changes. */
+    get version(): number;
     get x(): number;
     set x(v: number);
     get y(): number;
@@ -2728,6 +3008,27 @@ export declare interface OffMeshConnection {
 /** Register a callback to run before each rendered frame. */
 export declare function onBeforeRender(scene: SceneContext, cb: (deltaMs: number) => void): void;
 
+/**
+ * Register a callback fired each frame the CSM cascades are recomputed, right after the receiver
+ * UBO is updated and uploaded — and before the shadow map and main pass are rendered.
+ *
+ * Custom `ShaderMaterial` receivers that mirror the cascade transforms into their own uniforms
+ * (rather than binding the generator's receiver UBO directly, as the built-in standard/PBR/node
+ * receivers do) MUST sync from inside this callback. Syncing from an `onBeforeRender` callback
+ * reads the *previous* frame's transforms — a one-frame lag that makes those shadows visibly swim
+ * while the camera moves (the cascade window can slide many texels per frame during a zoom).
+ *
+ * Multiple receivers may register on the same generator; every registered callback is invoked each
+ * frame. The callback receives the 80-float receiver UBO (layout: four `mat4x4` cascade transforms,
+ * `viewFrustumZ`, `frustumLengths`, `shadowsInfo`, `csmParams` — see the cascaded-shadow
+ * architecture doc). The array is reused each frame; copy what you need.
+ *
+ * @param sg - A cascaded-shadow generator from {@link createCsmDirectionalShadowGenerator}.
+ * @param cb - Receiver-sync callback.
+ * @returns A disposer that unregisters this callback.
+ */
+export declare function onCsmReceiverUpdate(sg: ShadowGenerator, cb: (data: Float32Array) => void): () => void;
+
 /** Register a callback to run when `disposeScene` is called. Used to tie
  *  user-owned GPU resources (e.g. a `SpriteRenderer`) to the scene's lifetime. */
 export declare function onSceneDispose(scene: SceneContext, cb: () => void): void;
@@ -2776,6 +3077,10 @@ export declare function pauseAnimation(group: AnimationGroup): void;
  *  Optional sub-feature objects (clearcoat, sheen, anisotropy, subsurface) are
  *  only bundled when referenced. */
 export declare interface PbrMaterialProps extends Material {
+    /** Optional opt-in material plugins (custom WGSL + uniforms + samplers layered
+     *  on top of the built-in PBR pipeline). Attach via `material.plugins = [plugin]`,
+     *  then call `enableMaterialPlugins(scene)` before `registerScene`. */
+    plugins?: MaterialPlugin[];
     baseColorTexture?: Texture2D;
     /** Linear RGB/A factor multiplied with the base-color texture (glTF baseColorFactor). Default [1,1,1,1]. */
     baseColorFactor?: [number, number, number, number];
@@ -3084,6 +3389,32 @@ export declare interface PlaySpriteAnimationOptions {
 /** Replay an animation; omit options to keep callbacks/removal, pass options to overwrite them, or `{}` to clear them. */
 export declare function playSpriteFrameAnimation(animation: SpriteFrameAnimation, from?: number, to?: number, loop?: boolean, delayMs?: number, options?: PlaySpriteAnimationOptions): void;
 
+/** A texture + sampler pair contributed by a plugin. `texture`/`sampler` are the
+ *  WGSL variable names used by the plugin's custom code; the engine wires up the
+ *  GPU bindings in declaration order from {@link MaterialPlugin.bindTextures}. */
+export declare interface PluginSamplerDecl {
+    readonly texture: string;
+    readonly sampler: string;
+    /** Defaults to "texture_2d<f32>". */
+    readonly textureType?: "texture_2d<f32>";
+    /** Defaults to "sampler". */
+    readonly samplerType?: "sampler" | "sampler_non_filtering";
+}
+
+/** A texture binding emitted by {@link MaterialPlugin.bindTextures}. Public types
+ *  only — no raw GPU handles (GUIDANCE §4d). The engine reads `texture.view` /
+ *  `texture.sampler` internally. */
+export declare interface PluginTextureBinding {
+    readonly texture: Texture2D;
+}
+
+/** A custom uniform contributed by a plugin. The WGSL `type` is used verbatim
+ *  (e.g. "vec4<f32>", "f32", "mat4x4<f32>") inside the host material's UBO. */
+export declare interface PluginUboField {
+    readonly name: string;
+    readonly type: string;
+}
+
 export declare interface PointLight extends LightBase {
     readonly lightType: "point";
     position: ObservableVec3;
@@ -3474,6 +3805,15 @@ declare interface ScatteringProps {
     metersPerUnit?: number;
 }
 
+/** Handle to a render task's scene-color grab, returned by `enableRenderTaskTransmission`. */
+export declare interface SceneColorGrab {
+    /** The live opaque-scene-color texture sampled by transmissive surfaces, or null before the
+     *  frame graph has built the task at least once. Its identity changes when the task rebuilds
+     *  (e.g. on resize), so consumers that bind it to a custom material should re-bind when it
+     *  changes. */
+    readonly texture: Texture2D | null;
+}
+
 /** Top-level scene context — pure state, no attached methods. */
 export declare interface SceneContext extends RenderingContext_2 {
     readonly engine: EngineContext;
@@ -3577,6 +3917,42 @@ export declare function setBillboardSpriteFrame(handle: BillboardSpriteHandle, f
  */
 export declare function setBillboardSpriteFrameIndex(system: BillboardSpriteSystem, index: number, frame: number): void;
 
+/**
+ * Configure orbit/zoom limits on an ArcRotateCamera. This is fully opt-in and
+ * self-contained: cameras that never call it pay zero cost and bundle no clamping
+ * code (the camera's scalar setters call an undefined hook).
+ *
+ * What it does:
+ *  1. Stores the provided bounds on the camera and clamps the current pose into
+ *     range right away (inertia zeroed), so enabling limits never causes a jump.
+ *  2. Installs a self-clamp hook on the camera (`_clampToLimits`). The
+ *     alpha/beta/radius setters invoke it on every mutation, so any caller —
+ *     pinch direct-write, inertial overshoot, auto-rotate — is snapped back to
+ *     the wall in the same statement that pushed past it. The camera is therefore
+ *     never observably out of bounds at any point a per-frame callback reads it
+ *     (e.g. a camera-pinned skybox), eliminating both the overshoot-then-snap
+ *     jiggle and the one-frame clip "blink" of a deferred per-frame clamp.
+ *
+ * Only the fields present on `limits` are written, so calls compose; pass a field
+ * as `undefined` to remove that bound. Returns a disposer that removes the
+ * self-clamp hook.
+ *
+ * The optional `scene` parameter is accepted for backward compatibility and is
+ * unused — enforcement no longer needs a per-frame scene hook.
+ */
+export declare function setCameraLimits(camera: ArcRotateCamera, limits: ArcRotateCameraLimits, scene?: SceneContext): () => void;
+
+/**
+ * Set the scene clip plane and register its scene-uniform contributor.
+ *
+ * The clip plane is opt-in: importing `setClipPlane` is what pulls the clip-plane
+ * UBO writer into the bundle, keeping those bytes out of scenes that never clip.
+ *
+ * @param scene - The scene to configure.
+ * @param plane - The clip plane as `[a, b, c, d]` coefficients of `a·x + b·y + c·z + d`.
+ */
+export declare function setClipPlane(scene: SceneContext, plane: ClipPlane): void;
+
 /**
  * Bind a texture to one of the effect's texture slots, marking the bind group dirty so it is rebuilt.
  * @param wrapper - The effect wrapper to update.
@@ -3600,6 +3976,17 @@ export declare function setEffectUniforms(wrapper: EffectWrapper, data: ArrayBuf
  *  optional `_resize` hook. */
 export declare function setEngineSize(engine: EngineContext, widthPx: number, heightPx: number): void;
 
+/**
+ * Enable scene fog and register its scene-uniform contributor.
+ *
+ * Fog is an opt-in feature: importing `setFog` is what pulls the fog UBO writer
+ * into the bundle, keeping those bytes out of scenes that never use fog.
+ *
+ * @param scene - The scene to configure.
+ * @param config - The fog configuration (mode, density, start, end, color).
+ */
+export declare function setFog(scene: SceneContext, config: FogConfig): void;
+
 /** Raise (or lower) the maximum number of scene lights in the shared lights UBO.
  *  Must be called BEFORE scene pipelines are compiled — existing pipelines
  *  and UBOs bake the cap into their WGSL/layout. */
@@ -3674,8 +4061,11 @@ export declare function setPhysicsVelocityLimits(world: PhysicsWorld, maxLinear:
 /** Set a declared `f32` uniform. Convenience wrapper over `setShaderUniform()`. */
 export declare function setShaderFloat(material: ShaderMaterial, name: string, value: number): void;
 
-/** Set a declared `mat4x4<f32>` uniform. Convenience wrapper over `setShaderUniform()`. */
-export declare function setShaderMatrix(material: ShaderMaterial, name: string, value: Float32Array): void;
+/** Set a declared `mat4x4<f32>` uniform. Convenience wrapper over `setShaderUniform()`.
+ *  Accepts a raw `Float32Array` or the engine's branded `Mat4` (e.g. the result of
+ *  `getViewProjectionMatrix()` / `mat4Invert()`), so camera/math matrices can be fed
+ *  straight into a matrix uniform without laundering through a typed array. */
+export declare function setShaderMatrix(material: ShaderMaterial, name: string, value: Float32Array | Mat4): void;
 
 /** Bind (or clear) the texture for a declared sampler, enforcing that depth and
  *  non-depth samplers receive a matching `Texture2D`.
@@ -3746,7 +4136,7 @@ export declare function setThinInstanceColors(mesh: Mesh, colors: Float32Array):
 export declare function setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void;
 
 /** Set all instances from a pre-built matrix array. */
-export declare function setThinInstances(mesh: Mesh, matrices: Float32Array, count: number): void;
+export declare function setThinInstances(mesh: Mesh, matrices: Float32Array | Float64Array, count: number): void;
 
 /**
  * Write bytes into the uniform effect's single uniform buffer.
@@ -3783,6 +4173,8 @@ export declare interface ShaderMaterial extends Material {
     readonly defines: readonly ShaderDefine[];
     readonly needAlphaBlending: boolean;
     readonly blendMode: "alpha" | "additive";
+    /** True for transmissive/refractive surfaces (see `ShaderMaterialOptions.transmissive`). */
+    readonly transmissive: boolean;
     readonly needAlphaTesting: boolean;
     readonly backFaceCulling: boolean;
     readonly depthWrite: boolean;
@@ -3803,6 +4195,13 @@ export declare interface ShaderMaterialOptions {
      *  standard src-over; "additive" adds the fragment's premultiplied-by-alpha
      *  color to the framebuffer, which is the right choice for glows/light FX. */
     readonly blendMode?: "alpha" | "additive";
+    /** Mark this surface as transmissive/refractive: the renderer grabs the opaque scene color
+     *  behind it just before it draws, so the fragment can sample what is *through* it (water,
+     *  glass). Requires `needAlphaBlending` (the surface composites over the grabbed scene
+     *  color). Enable the scene-color grab on the surface's render task with
+     *  `enableRenderTaskTransmission`, then bind the resulting texture via `setShaderTexture`.
+     *  Default false. */
+    readonly transmissive?: boolean;
     readonly needAlphaTesting?: boolean;
     readonly backFaceCulling?: boolean;
     readonly depthWrite?: boolean;
@@ -3813,6 +4212,12 @@ export declare interface ShaderMaterialOptions {
 export declare interface ShaderSamplerDecl {
     readonly name: string;
     readonly sampleType?: "float" | "unfilterable-float" | "depth";
+    /** Texture view dimension. Default "2d". Use "2d-array" for layered maps such as
+     *  cascaded-shadow (CSM) depth arrays. */
+    readonly viewDimension?: "2d" | "2d-array";
+    /** Bind a hardware comparison sampler (`sampler_comparison`) for depth compare / PCF
+     *  filtering. Implies a depth texture. Default false. */
+    readonly comparison?: boolean;
 }
 
 /** A sampler entry: either a bare sampler name or an explicit declaration. */
@@ -4246,6 +4651,10 @@ declare interface StageState {
 
 /** StandardMaterial properties — plain data. */
 export declare interface StandardMaterialProps extends Material {
+    /** Optional opt-in material plugins (custom WGSL + uniforms + samplers layered
+     *  on top of the built-in Standard pipeline). Attach via `material.plugins = [plugin]`,
+     *  then call `enableMaterialPlugins(scene)` before `registerScene`. */
+    plugins?: MaterialPlugin[];
     diffuseColor: [number, number, number];
     alpha: number;
     specularColor: [number, number, number];
@@ -4445,8 +4854,11 @@ export declare interface ThicknessProps {
 
 /** CPU-side data backing a thin-instanced mesh: world matrices, optional colors, and GPU sync state. */
 export declare interface ThinInstanceData {
-    /** CPU-side instance world matrices (16 floats per instance). */
-    matrices: Float32Array;
+    /** CPU-side instance world matrices (16 floats per instance). Storage may
+     *  be Float32Array (default) or Float64Array (after an HPM engine is
+     *  constructed; the caller built the slab via `allocateMat4()`). The GPU
+     *  upload path in thin-instance-gpu.ts handles both (REQ-API-3, D5). */
+    matrices: Float32Array | Float64Array;
     /** Active instance count. */
     count: number;
    /** Optional per-instance RGBA colors (4 floats per instance). */
     colors?: Float32Array | null;
@@ -4459,6 +4871,51 @@ export declare interface TintProps {
     atDistance?: number;
 }
 
+/**
+ * Torus-knot mesh generator — matches Babylon.js `CreateTorusKnotVertexData` exactly.
+ *
+ * The knot centre-line is the (p, q) torus knot curve:
+ *
+ *   getPos(angle):
+ *     cu = cos(angle), su = sin(angle), s = (q/p) * angle
+ *     x = radius * (2 + cos(s)) * 0.5 * cu
+ *     y = radius * (2 + cos(s)) * 0.5 * su
+ *     z = radius * sin(s) * 0.5
+ *
+ * A Frenet-like frame (tangent / normal / bitangent built from cross products of
+ * the curve point and a nearby sample) sweeps a circle of `tube` radius around
+ * the curve. Normals are computed with the area-weighted-per-face-then-normalize
+ * scheme of Babylon's `VertexData.ComputeNormals` (see {@link computeNormals}),
+ * NOT analytically, so the knot shades pixel-identically to Babylon.js.
+ *
+ * Loop bounds mirror Babylon precisely: the vertex loop runs `i <= radialSegments`
+ * (with `i % radialSegments` wrap) while the index loop runs `i < radialSegments`
+ * and `j < tubularSegments` (with `(j + 1) % tubularSegments` wrap).
+ */
+/** CPU geometry for a torus knot: tightly-packed typed arrays ready for GPU upload. */
+export declare interface TorusKnotData {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+
+/** Options for {@link createTorusKnotData}. Subset of Babylon's CreateTorusKnot. */
+export declare interface TorusKnotOptions {
+    /** Global radius of the torus knot. Default 2. */
+    radius?: number;
+    /** Thickness of the tube. Default 0.5. */
+    tube?: number;
+    /** Number of sides on each tube segment. Default 32. */
+    radialSegments?: number;
+    /** Number of tubes the knot is decomposed into. Default 32. */
+    tubularSegments?: number;
+    /** Number of windings around the z axis. Default 2. */
+    p?: number;
+    /** Number of windings around the x axis. Default 3. */
+    q?: number;
+}
+
 /** Options for `createTorusData`. Subset of Babylon's CreateTorus. */
 export declare interface TorusOptions {
     diameter?: number;
@@ -4480,6 +4937,19 @@ export declare interface TranslucencyProps {
     diffusionDistance?: [number, number, number];
 }
 
+export declare interface TransmissionOptions {
+    /** When true (the default), retarget the task's color buffer to a linear `rgba16float`
+     *  offscreen and tone-map it in a trailing image-processing pass — the model PBR
+     *  transmission uses so refractive materials read scene color in *linear* space.
+     *
+     *  Set false to perform ONLY the mid-pass scene-color grab: the task's render target
+     *  format / sample count / clear are left untouched and no tone-map pass is added. Use
+     *  this for consumers that own their tone mapping / post (e.g. a custom depth-of-field
+     *  stack) and just need the opaque scene color exposed to a custom transmissive
+     *  `ShaderMaterial`. */
+    linear?: boolean;
+}
+
 /** Options for `createTubeData`: a circular cross-section swept along a path. */
 export declare interface TubeOptions {
     path: Vec3[];
@@ -4585,6 +5055,23 @@ export declare function updateSprite2DIndex(layer: Sprite2DLayer, index: number,
  */
 export declare function updateSpriteAnimationManager(manager: SpriteAnimationManager, deltaMs: number): void;
 
+/**
+ * Update a rectangular region of an existing `Texture2D` from a tightly-packed RGBA8 byte buffer.
+ *
+ * The texture must have been created with `COPY_DST` usage (as `createTexture2DFromPixels` does).
+ * This is the runtime counterpart to `createTexture2DFromPixels` — for data textures the app mutates
+ * each frame / on demand (e.g. a terrain carve heightmap stamped by a dig tool).
+ *
+ * @param engine - Engine context.
+ * @param tex - Target texture (from `createTexture2DFromPixels`).
+ * @param data - `width * height * 4` bytes for the sub-region, row-major, straight alpha.
+ * @param x - Destination origin X in texels (default 0).
+ * @param y - Destination origin Y in texels (default 0).
+ * @param width - Region width in texels (default `tex.width`).
+ * @param height - Region height in texels (default `tex.height`).
+ */
+export declare function updateTexture2DFromPixels(engine: EngineContext, tex: Texture2D, data: Uint8Array, x?: number, y?: number, width?: number, height?: number): void;
+
 /** Per-mesh original + variant material entry. */
 declare interface VariantMeshEntry {
     mesh: Mesh;