@babylonjs/lite 1.2.0 → 1.3.0

package/index.d.ts

@@ -170,6 +170,10 @@ export declare function addTaskBefore(target: FrameGraph | SceneContext, task: T
 /** Attach a `TextRenderable` to a scene. Uses the scene's deferred-renderables hook. */
 export declare function addTextRenderable(scene: SceneContext, renderable: TextRenderable): void;
 
+/** Add a text layer to an existing renderer if it is not already present.
+ *
+ *  @param tr - Text renderer to mutate.
+ *  @param layer - Layer to append; draw order is sorted during renderer update. */
 export declare function addTextRendererLayer(tr: TextRenderer, layer: TextLayer): void;
 
 /** Add one instance. Returns its index. Grows capacity as needed. */
@@ -297,7 +301,59 @@ export declare interface AnimationGroup {
     /** Whether animation loops (default true). */
     loopAnimation: boolean;
     /** Weighted contribution used by AnimationManager mixing (default 1). */
-    weight: number;
+    weight: number;
+    /** Optional include/exclude target-name mask. When set, only targets the mask retains
+     *  animate; masked-out targets stay at their bind/rest pose. Matched by glTF node /
+     *  bone name. See {@link createAnimationGroupMask}. To update an active mask, change
+     *  its `mode`/`disabled`, replace its `names` array, or reassign `group.mask`;
+     *  in-place same-length edits of `names` are not picked up. */
+    mask?: AnimationGroupMask;
+
+/**
+ * Filter applied to an {@link AnimationGroup} (via `group.mask`) that restricts which
+ * targets the group animates, matched by target name.
+ *
+ * A target is identified by its name (the glTF node / bone name). The same mask can be
+ * reused across animation groups whose targets are named the same way. Matching is exact
+ * and case-sensitive. Masked-out targets are left untouched and therefore stay at their
+ * bind/rest pose (matching Babylon.js, which pauses those targets).
+ *
+ * Pure state: create with {@link createAnimationGroupMask} and read membership with
+ * {@link animationGroupMaskRetainsTarget}. To change an active mask, toggle `mode` or
+ * `disabled`, or replace the `names` array (assign a new array, or push/pop): the
+ * controller re-resolves whenever `mode`, `disabled`, the `names` array reference, or
+ * its length changes. Editing `names` in place at the same length (e.g. `names[0] = …`
+ * or reordering) is NOT detected — assign a new `names` array, or reassign `group.mask`,
+ * to apply such a change.
+ */
+export declare interface AnimationGroupMask {
+    /** How `names` is interpreted (Include vs Exclude). */
+    mode: AnimationGroupMaskMode;
+    /** Target (node/bone) names listed by the mask. */
+    names: string[];
+    /** When true the mask is ignored and every target animates (default false). */
+    disabled: boolean;
+}
+
+/** Mode controlling how an {@link AnimationGroupMask} filters targets. */
+export declare enum AnimationGroupMaskMode {
+    /** Only the listed target names animate; every other target stays at its bind/rest pose. */
+    Include = 0,
+    /** Every target animates except the listed names (which stay at their bind/rest pose). */
+    Exclude = 1
+}
+
+/**
+ * Whether the mask retains (keeps animating) the given target name.
+ *
+ * Mirrors Babylon.js `AnimationGroupMask.retainsTarget`: in Include mode a name is
+ * retained when it is listed; in Exclude mode a name is retained when it is NOT listed.
+ * A disabled mask retains every name.
+ * @param mask - The mask to query.
+ * @param name - The target (node/bone) name to test.
+ * @returns True if a target with this name should animate, false if it is masked out.
+ */
+export declare function animationGroupMaskRetainsTarget(mask: AnimationGroupMask, name: string): boolean;
 
 /** A single keyframe on a property animation track. Supply exactly one of `time` (seconds) or `frame`. */
 export declare interface AnimationKeyframe {
@@ -499,16 +555,27 @@ export declare interface AssetContainer {
         packets: unknown[];
         assetPacket?: unknown;
     };
+    /** Bone-control handles, one per glTF skin. Present only when
+     *  `enableBoneControl()` was called before loading; otherwise `undefined`.
+     *  Drive bones via `getBoneByName()` + the `setBone*` functions. */
+    skeletons?: Skeleton[];
 }
 
 /** Bind the gizmo to a node — the gizmo follows the node's world translation
  *  and applies drag deltas to its `position`. */
 export declare function attachAxisDragGizmoToNode(gizmo: AxisDragGizmo, node: SceneNode | null): void;
 
+/** Attach the axis scale gizmo to a scene node, or detach it with `null`. */
 export declare function attachAxisScaleGizmoToNode(gizmo: AxisScaleGizmo, node: SceneNode | null): void;
 
+/** Attach the bounding-box gizmo to a node, or detach it with `null`.
+ * Recomputes the current bounds immediately so handles match the new target.
+ */
 export declare function attachBoundingBoxGizmoToNode(gizmo: BoundingBoxGizmo, node: SceneNode | null): void;
 
+/** Attach the camera gizmo to a camera, or detach it with `null`.
+ * The frustum wireframe is built lazily the first time a camera is attached.
+ */
 export declare function attachCameraGizmoToCamera(gizmo: CameraGizmo, camera: Camera | null): void;
 
 /**
@@ -592,16 +659,24 @@ export declare function attachFreeControl(camera: FreeCamera, canvas: HTMLCanvas
  */
 export declare function attachGeospatialControls(camera: GeospatialCamera, canvas: HTMLCanvasElement, scene: SceneContext, options?: GeospatialControlOptions): () => void;
 
+/** Attach the light gizmo to a light, or detach it with `null`.
+ * Type-specific geometry is built lazily when a light is first attached.
+ */
 export declare function attachLightGizmoToLight(gizmo: LightGizmo, light: LightBase | null): void;
 
+/** Attach the plane drag gizmo to a scene node, or detach it with `null`. */
 export declare function attachPlaneDragGizmoToNode(gizmo: PlaneDragGizmo, node: SceneNode | null): void;
 
+/** Attach the rotation gizmo to a scene node, or detach it with `null`. */
 export declare function attachPlaneRotationGizmoToNode(gizmo: PlaneRotationGizmo, node: SceneNode | null): void;
 
+/** Attach all position sub-gizmos to a node, or detach them with `null`. */
 export declare function attachPositionGizmoToNode(gizmo: PositionGizmo, node: SceneNode | null): void;
 
+/** Attach all rotation sub-gizmos to a node, or detach them with `null`. */
 export declare function attachRotationGizmoToNode(gizmo: RotationGizmo, node: SceneNode | null): void;
 
+/** Attach all scale sub-gizmos to a node, or detach them with `null`. */
 export declare function attachScaleGizmoToNode(gizmo: ScaleGizmo, node: SceneNode | null): void;
 
 /**
@@ -634,6 +709,7 @@ export declare function attachSpriteAnimationsToScene(scene: SceneContext, manag
  */
 export declare function attachVat(engine: EngineContext, mesh: Mesh, baked: VatBakeResult, clip?: string): VatHandle;
 
+/** A single arrow-shaped gizmo that translates its attached node along one axis. */
 export declare interface AxisDragGizmo {
     /** The root node — gizmo follows its `attachedNode` by copying world translation. */
     readonly root: SceneNode;
@@ -652,6 +728,7 @@ export declare interface AxisDragGizmo {
      *  automatically during pointer-down on the collider. */
     readonly materials: GizmoMaterialSet;
 
+/** Options for building a single-axis position drag gizmo. */
 export declare interface AxisDragGizmoOptions {
     /** World-space drag axis (unit vector). */
     dragAxis: Vec3;
@@ -668,6 +745,7 @@ export declare interface AxisDragGizmoOptions {
 /** A billboard sprite system that rotates only around a fixed world axis. */
 export declare type AxisLockedBillboardSpriteSystem = BillboardSpriteSystem<"axis-locked">;
 
+/** A cube or octahedron handle that scales its attached node from pointer drag distance. */
 export declare interface AxisScaleGizmo {
     readonly root: SceneNode;
     readonly drag: PointerDrag;
@@ -677,6 +755,7 @@ export declare interface AxisScaleGizmo {
     useLocalCoordinates: boolean;
     readonly materials: GizmoMaterialSet;
 
+/** Options for building a single-axis or uniform scale gizmo handle. */
 export declare interface AxisScaleGizmoOptions {
     /** World-space drag axis (unit vector). Scaling is applied to the attached
      *  node's local `scaling` components proportional to each axis component. */
@@ -877,6 +956,13 @@ export declare interface BlurPostProcessTaskConfig extends Omit<PostProcessTaskC
     kernel?: number;
 }
 
+/** A single bone of a {@link Skeleton}. Pure data — drive it via the `setBone*`
+ *  functions, addressing it through its owning `Skeleton`. */
+export declare interface Bone {
+    /** Bone (joint node) name from the glTF, or `bone_<index>` when unnamed. */
+    readonly name: string;
+
+/** Interactive bounding-box gizmo that can translate, rotate, and scale an attached node. */
 export declare interface BoundingBoxGizmo {
     readonly root: SceneNode;
     /** Currently attached node — set via `attachBoundingBoxGizmoToNode`. */
@@ -886,6 +972,7 @@ export declare interface BoundingBoxGizmo {
     /** Material used to render all gizmo geometry. */
     readonly material: StandardMaterialProps;
 
+/** Options for the interactive bounding-box gizmo. */
 export declare interface BoundingBoxGizmoOptions {
     /** RGB colour for the wireframe + handle materials. Defaults to grey. */
     color?: [number, number, number];
@@ -916,6 +1003,7 @@ export declare interface Camera {
     readonly worldMatrix: Mat4;
     readonly worldMatrixVersion: number;
 
+/** Display-only gizmo that visualizes an attached camera body and optional frustum. */
 export declare interface CameraGizmo {
     /** Root node — the gizmo follows the attached camera's world translation
      *  and orientation each frame. */
@@ -928,6 +1016,7 @@ export declare interface CameraGizmo {
     /** Currently attached camera — set via `attachCameraGizmoToCamera`. */
     attachedCamera: Camera | null;
 
+/** Options for the display-only camera gizmo. */
 export declare interface CameraGizmoOptions {
     /** RGB color for the camera body + frustum material.  Defaults to grey. */
     color?: [number, number, number];
@@ -1151,6 +1240,9 @@ export declare function clearAnimationManager(manager: AnimationManager): void;
  */
 export declare function clearBillboardSprites(system: BillboardSpriteSystem): void;
 
+/** Remove all overrides for a bone, reverting it to animation / rest pose, then re-bake. */
+export declare function clearBoneOverride(skeleton: Skeleton, bone: Bone): void;
+
 /** Clearcoat layer properties. Maps to BJS PBRMaterial.clearCoat sub-object. */
 export declare interface ClearCoatProps {
     /** Whether clearcoat is active. Default false. */
@@ -1327,6 +1419,7 @@ export declare interface CopyToTextureTask extends Task {
     readonly outputTexture: RenderTarget;
 }
 
+/** Options used to create a copy-to-texture frame-graph task. Selects the source render target, the target or resolve target, and optional viewport / mip-level settings for blit and copy paths. */
 export declare interface CopyToTextureTaskConfig {
     name?: string;
     sourceTexture: RenderTarget;
@@ -1374,6 +1467,19 @@ export declare function createAnaglyphPostProcessTask(config: AnaglyphPostProces
  */
 export declare function createAnimationController(clip: AnimationClip, nodes: readonly NodeRest[], skeletons: readonly SkeletonBinding[], morphBindings: readonly MorphBinding[], nodeTargets?: readonly (AnimatedNodeTarget | undefined)[], excludedNodeIndices?: ReadonlySet<number>): AnimationController;
 
+export declare function createAnimationController(clip: AnimationClip, nodes: readonly NodeRest[], skeletons: readonly SkeletonBinding[], morphBindings: readonly MorphBinding[], nodeTargets: readonly (AnimatedNodeTarget | undefined)[] | undefined, excludedNodeIndices: ReadonlySet<number> | undefined, boneOverrides: ReadonlyMap<number, unknown> | undefined): AnimationController;
+
+export declare function createAnimationController(clip: AnimationClip, nodes: readonly NodeRest[], skeletons: readonly SkeletonBinding[], morphBindings: readonly MorphBinding[], nodeTargets: readonly (AnimatedNodeTarget | undefined)[] | undefined, excludedNodeIndices: ReadonlySet<number> | undefined, boneOverrides: ReadonlyMap<number, unknown> | undefined, nodeNames?: readonly (string | undefined)[]): AnimationController;
+
+/**
+ * Create an {@link AnimationGroupMask}.
+ * @param names - Target names listed by the mask (copied). Defaults to empty.
+ * @param mode - Include (only listed names animate) or Exclude (all but listed names animate).
+ *               Defaults to {@link AnimationGroupMaskMode.Include}.
+ * @returns A new mask. Assign it to `animationGroup.mask`.
+ */
+export declare function createAnimationGroupMask(names?: string[], mode?: AnimationGroupMaskMode): AnimationGroupMask;
+
 /** Create AnimationGroup(s) from parsed glTF animation data.
  *  Returns one group per animation clip. */
 export declare function createAnimationGroups(animData: GltfAnimationData): AnimationGroup[];
@@ -1406,6 +1512,12 @@ export declare function createAxisDragGizmo(engine: EngineContext, layer: Utilit
  */
 export declare function createAxisLockedBillboardSystem(atlas: SpriteAtlas, axis: readonly [number, number, number], opts?: BillboardSpriteSystemOptions): AxisLockedBillboardSpriteSystem;
 
+/** Create an axis scale gizmo in the utility layer.
+ * @param engine - Engine that owns the created meshes.
+ * @param layer - Utility layer that renders and picks the gizmo.
+ * @param options - Drag axis, scale mode, sensitivity, and material options.
+ * @returns A detached scale gizmo ready to attach to a node.
+ */
 export declare function createAxisScaleGizmo(engine: EngineContext, layer: UtilityLayer, options: AxisScaleGizmoOptions): AxisScaleGizmo;
 
 /**
@@ -1441,6 +1553,12 @@ export declare function createBloomPostProcessTask(config: BloomPostProcessTaskC
  */
 export declare function createBlurPostProcessTask(config: BlurPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): BlurPostProcessTask;
 
+/** Create an interactive bounding-box gizmo in the utility layer.
+ * @param engine - Engine that owns the created meshes.
+ * @param layer - Utility layer that renders and picks the bounding-box handles.
+ * @param options - Visual size and color options for edges and handles.
+ * @returns A detached bounding-box gizmo ready to attach to a node.
+ */
 export declare function createBoundingBoxGizmo(engine: EngineContext, layer: UtilityLayer, options?: BoundingBoxGizmoOptions): BoundingBoxGizmo;
 
 /** Create a box mesh. Caller must assign material. */
@@ -1515,6 +1633,7 @@ export declare function createClusteredLightContainer(options?: ClusteredLightCo
  */
 export declare function createClusteredPointLight(container: ClusteredLightContainer, options: ClusteredPointLightOptions): ClusteredPointLight;
 
+/** Create a frame-graph task that copies, blits, or resolves one render target color attachment into another. The task chooses the fastest valid path during `record()` based on the configured targets, samples, viewport, and mip level. */
 export declare function createCopyToTextureTask(config: CopyToTextureTaskConfig, engine: EngineContext, scene: SceneContext): CopyToTextureTask;
 
 /**
@@ -1552,6 +1671,7 @@ export declare function createCsmDirectionalShadowGenerator(engine: EngineContex
 /** Create a cylinder (or cone / truncated cone / prism) mesh. Caller must assign material. */
 export declare function createCylinder(engine: EngineContext, options?: CylinderOptions): Mesh;
 
+/** Generate indexed vertex data for a cylinder, cone, truncated cone, or prism using Babylon-compatible defaults. The returned arrays contain positions, normals, UVs, and indices suitable for constructing a mesh. */
 export declare function createCylinderData(options?: CylinderOptions): CylinderData;
 
 /**
@@ -1958,8 +2078,20 @@ export declare function createPhysicsViewer(scene: SceneContext, world: PhysicsW
 /** Create a plane (unit quad facing -Z). Caller must assign material. */
 export declare function createPlane(engine: EngineContext, options?: PlaneOptions): Mesh;
 
+/** Create a planar drag gizmo in the utility layer.
+ * @param engine - Engine that owns the created meshes.
+ * @param layer - Utility layer that renders and picks the gizmo.
+ * @param options - Plane normal and material options.
+ * @returns A detached plane drag gizmo ready to attach to a node.
+ */
 export declare function createPlaneDragGizmo(engine: EngineContext, layer: UtilityLayer, options: PlaneDragGizmoOptions): PlaneDragGizmo;
 
+/** Create a plane rotation gizmo in the utility layer.
+ * @param engine - Engine that owns the created meshes and rotation display material.
+ * @param layer - Utility layer that renders and picks the gizmo.
+ * @param options - Plane normal, ring sizing, and material options.
+ * @returns A detached rotation gizmo ready to attach to a node.
+ */
 export declare function createPlaneRotationGizmo(engine: EngineContext, layer: UtilityLayer, options: PlaneRotationGizmoOptions): PlaneRotationGizmo;
 
 /** Build a PointerDrag descriptor.  The drag is inert until `registerPointerDrag`
@@ -2058,8 +2190,20 @@ export declare function createRenderTexture2D(engine: EngineContext, width: numb
 /** Create a ribbon from an array of parallel Vec3 paths. Caller must assign material. */
 export declare function createRibbon(engine: EngineContext, options: RibbonOptions): Mesh;
 
+/** Create a composite rotation gizmo with one ring for each principal axis.
+ * @param engine - Engine that owns the created meshes.
+ * @param layer - Utility layer that renders and picks the rings.
+ * @param options - Ring tessellation and thickness options.
+ * @returns A detached rotation gizmo ready to attach to a node.
+ */
 export declare function createRotationGizmo(engine: EngineContext, layer: UtilityLayer, options?: RotationGizmoOptions): RotationGizmo;
 
+/** Create a composite scale gizmo with per-axis handles and a uniform centre handle.
+ * @param engine - Engine that owns the created meshes.
+ * @param layer - Utility layer that renders and picks the handles.
+ * @param options - Shared scale-handle thickness options.
+ * @returns A detached scale gizmo ready to attach to a node.
+ */
 export declare function createScaleGizmo(engine: EngineContext, layer: UtilityLayer, options?: ScaleGizmoOptions): ScaleGizmo;
 
 /** Create an empty scene context bound to the given `surface`. The default render task
@@ -2193,10 +2337,25 @@ export declare function createSurface(engine: EngineContext, canvas: RenderCanva
  *  runs can be appended later via `updateTextData({ update: "addRun", … })`. */
 export declare function createTextData(storage: GlyphStorage, runs?: readonly GlyphRun[]): TextData;
 
+/** Create a 2D text layer that places a `TextData` block in canvas pixel space.
+ *
+ *  @param data - Text data block drawn by the layer.
+ *  @param options - Optional pixel placement, scale, order, opacity, and visibility.
+ *  @returns A mutable layer object for use with a `TextRenderer`. */
 export declare function createTextLayer(data: TextData, options?: TextLayerOptions): TextLayer;
 
+/** Create a scene renderable that draws the supplied `TextData` through the normal renderable pipeline.
+ *
+ *  @param data - Text data block to render.
+ *  @param options - Optional transform, opacity, depth, and ordering settings.
+ *  @returns A transparent renderable suitable for adding to a scene. */
 export declare function createTextRenderable(data: TextData, options?: TextRenderableOptions): TextRenderable;
 
+/** Create a standalone text renderer for one surface.
+ *
+ *  @param surface - Surface whose swapchain receives the text pass.
+ *  @param opts - Initial layers and clear settings.
+ *  @returns A rendering context that can be registered with the engine. */
 export declare function createTextRenderer(surface: SurfaceContext, opts: TextRendererOptions): TextRenderer;
 
 /**
@@ -2378,6 +2537,16 @@ export declare interface CylinderOptions {
     subdivisions?: number;
 }
 
+/** Result of {@link mat4Decompose}: a TRS triple. */
+export declare interface DecomposedTransform {
+    /** Translation (matrix columns 12/13/14). */
+    translation: Vec3;
+    /** Rotation as a unit quaternion. */
+    rotation: Quat;
+    /** Per-axis scale (lengths of the basis columns). */
+    scale: Vec3;
+}
+
 /** Convenience text-data variant that owns its `GlyphStorage` and exposes the laid-out
  *  pixel-space `width` / `height` of the text block. Produced by `createDefaultTextData`. */
 export declare interface DefaultTextData extends TextData {
@@ -2461,10 +2630,13 @@ export declare interface DiscOptions {
 /** Dispose the gizmo: remove meshes, unregister pointer-drag, drop materials. */
 export declare function disposeAxisDragGizmo(gizmo: AxisDragGizmo, layer: UtilityLayer): void;
 
+/** Dispose the axis scale gizmo meshes, observers, and pointer-drag registration. */
 export declare function disposeAxisScaleGizmo(gizmo: AxisScaleGizmo, layer: UtilityLayer): void;
 
+/** Dispose all meshes, observers, and pointer-drag registrations owned by the bounding-box gizmo. */
 export declare function disposeBoundingBoxGizmo(gizmo: BoundingBoxGizmo, layer: UtilityLayer): void;
 
+/** Dispose all meshes and follow callbacks owned by the camera gizmo. */
 export declare function disposeCameraGizmo(gizmo: CameraGizmo, layer: UtilityLayer): void;
 
 /** Frees the WASM memory backing a solid. The solid must not be used afterwards. */
@@ -2491,8 +2663,12 @@ export declare function disposeFrameGraphContext(ctx: FrameGraphContext): void;
  *  ensuring no `TextData` is still drawing from this storage. */
 export declare function disposeGlyphStorage(storage: GlyphStorage): void;
 
+/** Dispose all meshes and frame callbacks owned by the light gizmo. */
 export declare function disposeLightGizmo(gizmo: LightGizmo, layer: UtilityLayer): void;
 
+/** Destroy all GPU resources owned by a mesh (vertex buffers, skeleton, morph targets). */
+export declare function disposeMeshGpu(mesh: Mesh): void;
+
 /**
  * Removes and releases all bodies, then releases the native world. Call once when tearing down physics.
  * @param world - The physics world to dispose.
@@ -2505,14 +2681,19 @@ export declare function disposePhysicsViewer(viewer: PhysicsViewer): void;
 /** Dispose GPU resources owned by this picker. */
 export declare function disposePicker(picker: GpuPicker): void;
 
+/** Dispose the plane drag gizmo meshes and pointer-drag registration. */
 export declare function disposePlaneDragGizmo(gizmo: PlaneDragGizmo, layer: UtilityLayer): void;
 
+/** Dispose the rotation gizmo meshes, observers, and pointer-drag registration. */
 export declare function disposePlaneRotationGizmo(gizmo: PlaneRotationGizmo, layer: UtilityLayer): void;
 
+/** Dispose all sub-gizmos owned by the composite position gizmo. */
 export declare function disposePositionGizmo(gizmo: PositionGizmo, layer: UtilityLayer): void;
 
+/** Dispose all sub-gizmos owned by the composite rotation gizmo. */
 export declare function disposeRotationGizmo(gizmo: RotationGizmo, layer: UtilityLayer): void;
 
+/** Dispose all sub-gizmos owned by the composite scale gizmo. */
 export declare function disposeScaleGizmo(gizmo: ScaleGizmo, layer: UtilityLayer): void;
 
 /** Release all GPU resources owned by this scene. */
@@ -2546,8 +2727,10 @@ export declare function disposeSurface(surface: SurfaceContext): void;
  *  `disposeGlyphStorage` once no `TextData` references it. */
 export declare function disposeTextData(data: TextData): void;
 
+/** Release GPU buffers owned by a text renderable. The underlying `TextData` and `GlyphStorage` remain caller-owned. */
 export declare function disposeTextRenderable(renderable: TextRenderable): void;
 
+/** Dispose a text renderer and all per-layer GPU resources it owns. Layer `TextData` remains caller-owned. */
 export declare function disposeTextRenderer(tr: TextRenderer): void;
 
 /** Destroy the uniform buffer and clear cached GPU objects owned by the uniform effect wrapper. */
@@ -2665,6 +2848,27 @@ export declare interface EffectWrapperOptions {
 /** Enable advanced animation blending for a manager. Kept opt-in so manual-only weights do not pay for skeletal mixing code. */
 export declare function enableAnimationBlending(manager: AnimationManager): void;
 
+/**
+ * Enable bone control for skinned glTF models. Call once, before loading the
+ * assets you want to control. After loading, read `container.skeletons` and drive
+ * bones with {@link getBoneByName} + the `setBone*` functions.
+ *
+ * ```ts
+ * enableBoneControl(); // ← opt-in, before loadGltf
+ * const character = await loadGltf(engine, "character.glb");
+ * addToScene(scene, character);
+ * const skel = character.skeletons![0];
+ * const head = getBoneByName(skel, "Head");
+ * if (head) setBoneVisible(skel, head, false); // hide the head + everything under it
+ * ```
+ *
+ * Process-global and idempotent. Skinned scenes that never call this are
+ * unaffected (near byte-identical to a build without bone control).
+ *
+ * @public
+ */
+export declare function enableBoneControl(): void;
+
 /**
  * Enable detailed picking on a GPU picker.
  * When enabled, pickAsync() will compute faceId, bu, bv
@@ -2705,6 +2909,41 @@ export declare function enableHavokFloatingOrigin(world: PhysicsWorld, floatingO
  */
 export declare function enableMaterialPlugins(scene: SceneContext): void;
 
+/**
+ * Opt-in entry point for per-material stencil state.
+ *
+ * Stencil (a {@link StencilState} baked into a material's main-pass pipeline — used to mask/discard
+ * fragments, e.g. portals or decals) is an *explicit* opt-in so stencil-free scenes stay BYTE-IDENTICAL to a
+ * build without it. The always-fetched Standard / PBR / Shader pipeline builders reference stencil only
+ * through a module-local resolver hook that is `null` until this function installs it; with the hook absent
+ * from the bundle the tree-shaker + minifier fold every stencil branch away. Calling `enableMaterialStencil`
+ * links the resolver (and pulls in its descriptor-building code) into all three pipelines.
+ *
+ * Contract: attach stencil to materials via `material.stencil = { ... }`, then call this once AFTER creating
+ * the materials/meshes and BEFORE `registerScene(scene)`. It is process-global and idempotent — no engine or
+ * scene argument is needed.
+ */
+/**
+ * Enable per-material stencil state for Standard, PBR, and Shader materials.
+ *
+ * A writer material uses `compare: "always"` + `passOp: "increment-clamp"` to stamp the stencil buffer where
+ * it draws; a tester material uses `compare: "equal"` to draw only where the stencil is still the pass's
+ * default reference of 0 (i.e. where the writer did NOT draw). No dynamic stencil reference is needed.
+ *
+ * ```ts
+ * const mask = createStandardMaterial();
+ * mask.stencil = { passOp: "increment-clamp" }; // writes 1 where it draws
+ * const masked = createStandardMaterial();
+ * masked.stencil = { compare: "equal" };        // draws only where stencil is still 0
+ *
+ * enableMaterialStencil(); // ← opt-in, before registerScene
+ * await registerScene(scene);
+ * ```
+ *
+ * @public
+ */
+export declare function enableMaterialStencil(): 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 & {
@@ -2714,8 +2953,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;
 
+/** Enable mid-pass scene-color grabs for a single render task and return the live texture handle. The task is wrapped so transmissive draw calls can sample the opaque color rendered earlier in the same pass. */
 export declare function enableRenderTaskTransmission(task: RenderTask, engine: EngineContext, options?: TransmissionOptions): SceneColorGrab;
 
+/** Enable scene-color transmission for every render task currently registered in a scene. PBR materials are marked for linear transmission, and a trailing image-processing task is appended when needed. */
 export declare function enableSceneTransmission(scene: SceneContext, engine: EngineContext): void;
 
 /** Enable or disable GPU frustum culling for an existing thin-instanced mesh.
@@ -2914,6 +3155,7 @@ export declare interface FogConfig {
     color: [number, number, number];
 }
 
+/** Opaque handle for a loaded TrueType/OpenType font used by the default text layout and glyph extraction helpers. */
 export declare interface Font {
     readonly [fontBrand]: true;
 
@@ -3024,6 +3266,7 @@ export declare interface GeometryRendererTask extends Task {
     includeInVelocity(mesh: Mesh): void;
 }
 
+/** Configuration for a geometry-renderer frame-graph task. Describes the meshes, camera, target size, geometry texture attachments, and optional real-color output target used by the MRT pass. */
 export declare interface GeometryRendererTaskConfig {
     name?: string;
     /** Caster meshes. When omitted, defaults to `scene.meshes`. */
@@ -3047,7 +3290,7 @@ export declare interface GeometryRendererTaskConfig {
     reverseCulling?: boolean;
     /** Optional color render-target that receives the *real* (lit) material
      *  color, written as an additional color attachment alongside the geometry
-     *  data attachments. Must have the same {@link sampleCount} and resolved
+     *  data attachments. Must have the same `sampleCount` and resolved
      *  pixel size as the geometry MRT (size: `<surface>` with samples matching).
      *  When omitted, no real-color attachment is added to the pass.
      *
@@ -3068,10 +3311,10 @@ export declare interface GeometryRendererTextureDescription {
     /** Which geometry value to write. */
     readonly type: GeometryTextureType;
     /** Per-attachment WebGPU format override. Defaults to
-     *  {@link GEOMETRY_TEXTURE_DESCRIPTIONS}[type].defaultFormat. */
+     *  `GEOMETRY_TEXTURE_DESCRIPTIONS[type].defaultFormat`. */
     readonly format?: GPUTextureFormat;
     /** Per-attachment clear-value override. Defaults to
-     *  {@link GEOMETRY_TEXTURE_DESCRIPTIONS}[type].clearValue. Use to match a
+     *  `GEOMETRY_TEXTURE_DESCRIPTIONS[type].clearValue`. Use to match a
      *  reference engine's clear behaviour (e.g. clear VIEW_DEPTH to 0 instead of
      *  the camera far plane to mirror BJS's PREPASS_DEPTH). */
     readonly clearValue?: GPUColor;
@@ -3252,6 +3495,10 @@ export declare function getAnimationGroups(manager: AnimationManager): readonly
  */
 export declare function getBillboardSpriteHandleIndex(handle: BillboardSpriteHandle): number;
 
+/** Find a bone by its (glTF joint node) name. Returns `undefined` if not present.
+ *  When several joints share a name, the first in joint order is returned. */
+export declare function getBoneByName(skeleton: Skeleton, name: string): Bone | undefined;
+
 /** Get the world-space position of a camera. */
 export declare function getCameraPosition(camera: Camera): Vec3;
 
@@ -3404,8 +3651,19 @@ export declare interface GltfAnimationData {
      *  matrices bake an `invMeshWorld` captured at load, so moving them at runtime
      *  would double-transform the skinned vertices). */
     readonly excludedNodeIndices: ReadonlySet<number>;
-}
-
+    /** glTF node names indexed by node index (undefined for unnamed nodes). Used by
+     *  {@link AnimationGroupMask} to resolve include/exclude target names to the node
+     *  indices its channels animate. */
+    readonly nodeNames: readonly (string | undefined)[];
+    /** Shared node-index → bone override map, present only when `enableBoneControl()`
+     *  installed bone control. Handed to every AnimationController so a playing clip
+     *  honours user bone overrides (animation wins per-component). `undefined` on the
+     *  default path. Typed as `unknown` value to keep the internal `BoneOverride`
+     *  shape out of the public API surface. */
+    readonly boneOverrides?: ReadonlyMap<number, unknown>;
+}
+
+/** Axis-aligned glyph extents in font units, used to size the rendered quad and spatial curve bands. */
 export declare type GlyphBounds = {
     readonly xMin: number;
     readonly yMin: number;
@@ -3413,11 +3671,13 @@ export declare type GlyphBounds = {
     readonly yMax: number;
 };
 
+/** Complete outline data for one glyph id, ready to be packed into a `GlyphStorage` atlas. */
 export declare type GlyphCurves = {
     readonly glyphId: number;
     readonly curves: readonly QuadCurve[];
     readonly bounds: GlyphBounds;
 
+/** Batch of placed glyphs that all use the same curve set and font-unit-to-pixel scale. */
 export declare type GlyphRun = {
     /** Which curve set this run's glyph ids index into. */
     readonly curveSet: CurveSetId;
@@ -3765,6 +4025,7 @@ export declare interface LightBase extends IWorldMatrixProvider, IParentable {
     readonly worldMatrix: Mat4;
     readonly worldMatrixVersion: number;
 
+/** Display-only gizmo that visualizes an attached light using type-specific geometry. */
 export declare interface LightGizmo {
     /** Root node — follows the attached light's position (when it has one)
      *  and orients along its direction (when it has one). */
@@ -3773,6 +4034,7 @@ export declare interface LightGizmo {
     /** Currently attached light — set via `attachLightGizmoToLight`. */
     attachedLight: LightBase | null;
 
+/** Options for the display-only light gizmo. */
 export declare interface LightGizmoOptions {
     /** RGB color for the light gizmo body material.  Defaults to grey. */
     color?: [number, number, number];
@@ -3880,16 +4142,31 @@ export declare function loadEnvironment(scene: SceneContext, url: string, option
 export declare function loadFont(url: string): Promise<Font>;
 
 /**
- * Load a .glb or .gltf file, parse it, and upload mesh + material data to GPU.
+ * Load a glTF/GLB asset, parse it, and upload mesh + material data to GPU.
  * Supports both binary GLB and separate .gltf + .bin + image files.
  * Registers a deferred PBR renderable builder.
  * Automatically parses glTF animations if present.
  *
  * Returns a AssetContainer. Pass it to addToScene() which adds the hierarchy,
  * registers animation ticks, and applies any scene-level settings.
+ *
+ * @param engine - The engine to upload GPU resources to.
+ * @param url - URL of the .glb/.gltf asset to fetch.
  */
 export declare function loadGltf(engine: EngineContext, url: string): Promise<AssetContainer>;
 
+/**
+ * Load a glTF/GLB asset directly from already-loaded local data (drag-and-drop, OPFS, a `fetch` body, etc.).
+ *
+ * GLB-vs-glTF is determined from the data's magic bytes, not a file extension. `ArrayBuffer`/`Blob` inputs
+ * have no base URL, so they must be self-contained: a GLB, or a glTF whose buffers/images use `data:` URIs.
+ * A glTF that references external `.bin`/image files by relative path can only be loaded from a URL.
+ *
+ * @param engine - The engine to upload GPU resources to.
+ * @param data - The raw `ArrayBuffer` or `Blob` of a self-contained glTF/GLB asset.
+ */
+export declare function loadGltf(engine: EngineContext, data: ArrayBuffer | Blob): Promise<AssetContainer>;
+
 /**
  * Loads a Radiance `.hdr` (RGBE) equirectangular panorama and builds GPU-ready IBL textures
  * (prefiltered specular cubemap, BRDF LUT, and irradiance spherical harmonics), then attaches
@@ -3901,6 +4178,14 @@ export declare function loadGltf(engine: EngineContext, url: string): Promise<As
  */
 export declare function loadHdrEnvironment(scene: SceneContext, url: string, options?: HdrLoadOptions): Promise<EnvironmentTextures>;
 
+/** Fetch and decode a standalone KTX2 (Basis Universal) texture from a URL into a Texture2D, transcoded to the
+ *  device's best GPU-compressed format (BC7/ETC2/ASTC) so it STAYS compressed in VRAM (a few times less than the
+ *  uncompressed RGBA8 `loadTexture2D` always uploads). Mirrors `loadKtxTexture2D` (KTX1) for app textures that
+ *  live outside a glTF. Requires the KTX2 decoder (configure self-hosting via `setKtx2DecoderUrl`). `sRGB`
+ *  selects the `*-srgb` GPU format (default false: raw/linear sampling, matching `loadTexture2D`'s `srgb:false`).
+ *  The decoder uploads the stored mips as-is (no V-flip), so author the .ktx2 in the orientation you want. */
+export declare function loadKtx2Texture2D(engine: EngineContext, url: string, sRGB?: boolean): Promise<Texture2D>;
+
 /**
  * Load a texture with KTX compressed format auto-selection and fallback.
  *
@@ -3992,6 +4277,16 @@ export declare interface Mat4 {
    readonly length: 16;
 /** 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;
 
+/**
+ * Decompose a column-major 4×4 affine matrix into translation, rotation (unit
+ * quaternion), and scale. Assumes a TRS matrix (no shear). Mirror image (negative
+ * determinant) matrices are not specially handled — the returned scale is always
+ * non-negative, matching the rest of the engine's decompose usage.
+ * @param m - Column-major 4×4 matrix.
+ * @returns A new translation/rotation/scale triple.
+ */
+export declare function mat4Decompose(m: Mat4): DecomposedTransform;
+
 /** Create a rotation matrix from a quaternion. */
 export declare function mat4FromQuat(qx: number, qy: number, qz: number, qw: number): Mat4;
 
@@ -4085,7 +4380,7 @@ export declare interface MaterialVariantData {
  *  scenes that never create views do not retain view-specific unwrap branches.
  *
  *  Specialized views (e.g. the Standard geometry MRT view) override
- *  {@link Material._buildGroup} with a view-specific builder whose
+ *  `_buildGroup` with a view-specific builder whose
  *  `_rebuildSingle` builds the right kind of Renderable — no per-family
  *  branching is required in the core render-task. */
 export declare interface MaterialView extends Material {
@@ -4720,7 +5015,10 @@ export declare interface PbrMaterialProps extends Material {
     /** Linear-RGB tint applied to baseColor when `unlit` is true (i.e. glTF
      *  `baseColorFactor`). When omitted or [1,1,1], no tint is applied.
      *  Only bundled/bound when the unlit extension is active. */
-    unlitColor?: [number, number, number];
+    unlitColor?: [number, number, number];
    /** Optional stencil-test state baked into the main-pass pipeline. Lets this material write the stencil buffer
+     *  where it draws (mask) or discard where another material wrote it. Default none. See `StencilState`. */
+    stencil?: StencilState;
+}
 
 /** Configuration for a directional-light PCF shadow generator: map size, depth bias, darkness, and ortho projection bounds. */
 export declare interface PcfDirectionalShadowGeneratorConfig {
@@ -5187,6 +5485,7 @@ export declare interface PixelViewport {
     height: number;
 }
 
+/** Positioned glyph instance in pixel space, usually produced by layout before being packed into a `GlyphRun`. */
 export declare type PlacedGlyph = {
     readonly glyphId: number;
     /** Pixel position of glyph baseline origin. */
@@ -5199,6 +5498,7 @@ export declare type PlacedGlyph = {
     readonly color?: readonly [number, number, number, number];
 };
 
+/** A square planar gizmo that translates its attached node within a drag plane. */
 export declare interface PlaneDragGizmo {
     readonly root: SceneNode;
     readonly drag: PointerDrag;
@@ -5209,6 +5509,7 @@ export declare interface PlaneDragGizmo {
     useLocalCoordinates: boolean;
     readonly materials: GizmoMaterialSet;
 
+/** Options for building a planar position drag gizmo. */
 export declare interface PlaneDragGizmoOptions {
     /** World-space drag plane normal (unit vector). */
     dragPlaneNormal: Vec3;
@@ -5224,6 +5525,7 @@ export declare interface PlaneOptions {
     height?: number;
 }
 
+/** A torus-shaped gizmo that rotates its attached node around a plane normal. */
 export declare interface PlaneRotationGizmo {
     readonly root: SceneNode;
     readonly drag: PointerDrag;
@@ -5236,6 +5538,7 @@ export declare interface PlaneRotationGizmo {
      *  callers can change the colour at runtime. */
     readonly rotationDisplayMaterial: ShaderMaterial;
 
+/** Options for building a rotation ring constrained to a single plane. */
 export declare interface PlaneRotationGizmoOptions {
     /** World-space rotation plane normal (unit vector). */
     planeNormal: Vec3;
@@ -5338,6 +5641,7 @@ export declare interface PluginUboField {
     readonly type: string;
 }
 
+/** Pointer-drag behavior shared by gizmos and driven by the per-canvas dispatcher. */
 export declare interface PointerDrag {
     readonly options: Readonly<PointerDragOptions>;
     enabled: boolean;
    /** Fired once when a pointer-down lands on one of `_colliders`. */
@@ -5359,10 +5663,12 @@ export declare interface PointerDrag {
     hovering: boolean;
 }
 
+/** Event raised when the active pointer drag is released or cancelled. */
 export declare interface PointerDragEndEvent {
     pointerEvent: PointerEvent | null;
 }
 
+/** Event raised for each pointer move while a drag is active. */
 export declare interface PointerDragMoveEvent {
     /** World-space delta from the previous drag-plane point.  For axis-drag this
      *  is already projected onto the drag axis (parallel to axis). */
@@ -5374,6 +5680,7 @@ export declare interface PointerDragMoveEvent {
     dragDistance: number;
 }
 
+/** Configuration for converting pointer movement into world-space drag deltas. */
 export declare interface PointerDragOptions {
     /** Drag along a single world-space axis (unit vector). Mutually exclusive
      *  with `dragPlaneNormal`. */
@@ -5395,6 +5702,7 @@ export declare interface PointerDragOptions {
     getPlanePoint?: () => Vec3 | null;
 }
 
+/** Event raised when a pointer drag begins on one of the registered colliders. */
 export declare interface PointerDragStartEvent {
     /** World-space point where the ray intersected the drag plane on drag start. */
     dragPlanePoint: Vec3;
@@ -5427,6 +5735,7 @@ export declare interface PolyhedronOptions {
     flat?: boolean;
 }
 
+/** Composite translation gizmo made from X/Y/Z axis arrows and optional planar handles. */
 export declare interface PositionGizmo {
     readonly xGizmo: AxisDragGizmo;
     readonly yGizmo: AxisDragGizmo;
@@ -5437,6 +5746,7 @@ export declare interface PositionGizmo {
     attachedNode: SceneNode | null;
 }
 
+/** Options for the composite position gizmo. */
 export declare interface PositionGizmoOptions {
     /** When true, planar drag gizmos (XY/XZ/YZ) are created in addition to the
      *  3 axis arrows.  Default false — matches BJS where `planarGizmoEnabled`
@@ -5527,6 +5837,7 @@ export declare interface PropertyAnimationTrackOptions {
     readonly quaternion?: boolean;
 }
 
+/** Quadratic Bézier curve describing one segment of a glyph outline in font units. */
 export declare type QuadCurve = {
     readonly p0x: number;
     readonly p0y: number;
@@ -5544,6 +5855,25 @@ export declare interface Quat {
     w: number;
 }
 
+/**
+ * Build a unit quaternion that orients local +Z onto `forward` and local +Y onto
+ * `up`, using a right-handed basis (`right = up × forward`). Matches Babylon.js
+ * `Quaternion.FromLookDirectionRH`.
+ * @param forward - Desired forward direction (should be normalized).
+ * @param up - Desired up direction (should be normalized and not parallel to `forward`).
+ * @returns A new `{ x, y, z, w }` quaternion.
+ */
+export declare function quatFromLookDirectionRH(forward: Vec3, up: Vec3): Quat;
+
+/**
+ * Build a unit quaternion from the rotation part of a column-major 4×4 matrix,
+ * matching Babylon.js `Quaternion.FromRotationMatrix`. The matrix's upper-left
+ * 3×3 must be a pure rotation (orthonormal, no scale).
+ * @param matrix - Column-major 4×4 rotation matrix.
+ * @returns A new `{ x, y, z, w }` quaternion.
+ */
+export declare function quatFromRotationMatrix(matrix: Mat4): Quat;
+
 /** A ray defined by origin, direction, and length. */
 declare interface Ray {
     origin: [number, number, number];
@@ -5652,6 +5982,7 @@ export declare function registerSceneWithShadowSupport(scene: SceneContext): Pro
 /** Push the renderer onto its engine's `_renderingContexts`. Idempotent — a second call is a no-op. */
 export declare function registerSpriteRenderer(sr: SpriteRenderer): void;
 
+/** Register a text renderer with its surface so the engine updates and records it each frame. */
 export declare function registerTextRenderer(tr: TextRenderer): void;
 
 /** Register the utility layer with the engine. Must be called after the main
@@ -5751,6 +6082,9 @@ export declare function removeSpriteAnimationManager(manager: AnimationManager,
 /** Remove a layer from the renderer and destroy any GPU resources cached for it. */
 export declare function removeSpriteRendererLayer(sr: SpriteRenderer, layer: Sprite2DLayer): boolean;
 
+/** Remove a text layer and release its per-layer GPU buffers.
+ *
+ *  @returns `true` when the layer was present and removed. */
 export declare function removeTextRendererLayer(tr: TextRenderer, layer: TextLayer): boolean;
 
 /** Remove instance by index. Swap-removes: last instance fills the gap. */
@@ -5782,6 +6116,7 @@ export declare interface Renderable {
  */
 export declare type RenderCanvas = HTMLCanvasElement | OffscreenCanvas;
 
+/** Render one frame for every surface registered on the engine. Updates each rendering context, records its GPU work into a shared command encoder, submits the frame, and publishes the total draw-call count. */
 export declare function renderFrame(engine: EngineContext, delta: number): void;
 
 /**
@@ -5989,6 +6324,7 @@ export declare interface RibbonOptions {
     offset?: number;
 }
 
+/** Composite rotation gizmo made from X/Y/Z plane rotation rings. */
 export declare interface RotationGizmo {
     readonly xGizmo: PlaneRotationGizmo;
     readonly yGizmo: PlaneRotationGizmo;
@@ -5996,11 +6332,13 @@ export declare interface RotationGizmo {
     attachedNode: SceneNode | null;
 }
 
+/** Options for the composite rotation gizmo. */
 export declare interface RotationGizmoOptions {
     tessellation?: number;
     thickness?: number;
 }
 
+/** Composite scale gizmo made from X/Y/Z axis handles and a central uniform handle. */
 export declare interface ScaleGizmo {
     readonly xGizmo: AxisScaleGizmo;
     readonly yGizmo: AxisScaleGizmo;
@@ -6010,6 +6348,7 @@ export declare interface ScaleGizmo {
     attachedNode: SceneNode | null;
 }
 
+/** Options for the composite scale gizmo. */
 export declare interface ScaleGizmoOptions {
     thickness?: number;
 }
@@ -6166,6 +6505,24 @@ export declare function setBillboardSpriteFrame(handle: BillboardSpriteHandle, f
  */
 export declare function setBillboardSpriteFrameIndex(system: BillboardSpriteSystem, index: number, frame: number): void;
 
+/** Override a bone's local translation, then re-bake. Ignored each frame for a
+ *  bone whose translation the playing clip animates. */
+export declare function setBonePosition(skeleton: Skeleton, bone: Bone, x: number, y: number, z: number): void;
+
+/** Override a bone's local rotation (quaternion), then re-bake. Ignored each frame
+ *  for a bone whose rotation the playing clip animates. */
+export declare function setBoneRotationQuaternion(skeleton: Skeleton, bone: Bone, x: number, y: number, z: number, w: number): void;
+
+/** Override a bone's local scale, then re-bake. Ignored each frame for a bone
+ *  whose scale the playing clip animates. */
+export declare function setBoneScaling(skeleton: Skeleton, bone: Bone, x: number, y: number, z: number): void;
+
+/** Show or hide the sub-tree driven by a bone, the Babylon.js way: hiding scales
+ *  the bone to zero (collapsing it and its descendant bones to a point so the
+ *  skinned triangles degenerate and disappear); showing clears the scale override
+ *  so the bone returns to its animated / rest scale. */
+export declare function setBoneVisible(skeleton: Skeleton, bone: Bone, visible: boolean): 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
@@ -6202,6 +6559,9 @@ export declare function setCameraLimits(camera: ArcRotateCamera, limits: ArcRota
  */
 export declare function setClipPlane(scene: SceneContext, plane: ClipPlane): void;
 
+/** Override the base URL where draco_decoder.js and draco_decoder.wasm are hosted. */
+export declare function setDracoBaseUrl(url: string): 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.
@@ -6283,6 +6643,19 @@ export declare function setKtx2DecoderUrl(url: string, wasmUrls?: Record<string,
  *  and UBOs bake the cap into their WGSL/layout. */
 export declare function setMaxLights(n: number): void;
 
+/**
+ * Lazy EXT_meshopt_compression decoder.
+ *
+ * The meshoptimizer decoder (JS glue + embedded WASM) is loaded from
+ * `/meshopt_decoder.js` on first use via a `<script>` injection — exactly like
+ * the Draco decoder. This keeps bundle size at zero bytes for scenes that do
+ * not load meshopt-compressed glTF assets: the entire module (including this
+ * file) is dynamic-imported from the meshopt feature only when an asset's
+ * `extensionsUsed` lists EXT_meshopt_compression.
+ */
+/** Override the base URL where meshopt_decoder.js is hosted. */
+export declare function setMeshoptBaseUrl(url: string): void;
+
 /** Update morph target weights on CPU and GPU.
  *  Only the first four weights are used, matching the current morph target limit.
  *  @param engine - Engine context that owns the morph target GPU buffer.
@@ -6296,12 +6669,16 @@ export declare function setNavigationRandomSeed(plugin: NavigationPlugin, seed:
 
 /**
  * Reparents `child` while preserving its current world-space transform, mirroring
- * Babylon.js `TransformNode.setParent()`.
- * @param child - The mesh to reparent.
+ * Babylon.js `TransformNode.setParent()`. Also keeps the scene-graph `children`
+ * arrays consistent: the child is removed from its previous parent's `children`
+ * and appended to the new parent's, so traversal helpers see the new hierarchy.
+ * @param child - The node to reparent (mesh, transform node, or any scene node).
  * @param parent - The new parent (any world-matrix provider), or `null` to detach to world space.
  */
 export declare function setParent(child: Mesh, parent: IWorldMatrixProvider | null): void;
 
+export declare function setParent(child: SceneNode, parent: IWorldMatrixProvider | null): void;
+
 /**
  * Set a body's angular velocity (rad/s).
  */
@@ -6447,6 +6824,7 @@ export declare function setPhysicsTimestep(world: PhysicsWorld, dt: number): voi
  */
 export declare function setPhysicsVelocityLimits(world: PhysicsWorld, maxLinear: number, maxAngular: number): void;
 
+/** Toggle whether the position gizmo axes follow the attached node's rotation. */
 export declare function setPositionGizmoLocalCoordinates(gizmo: PositionGizmo, useLocal: boolean): void;
 
 /** Enable or disable per-frame-graph-task GPU timing.
@@ -6458,6 +6836,7 @@ export declare function setPositionGizmoLocalCoordinates(gizmo: PositionGizmo, u
  */
 export declare function setRenderTaskGpuTimingEnabled(engine: EngineContext, enabled: boolean): Promise<RenderTaskGpuTimings>;
 
+/** Toggle whether the rotation rings follow the attached node's rotation. */
 export declare function setRotationGizmoLocalCoordinates(gizmo: RotationGizmo, useLocal: boolean): void;
 
 /** Toggle local-coord mode on the per-axis scale arrows.  The uniform-scale
@@ -6628,7 +7007,11 @@ export declare interface ShaderMaterial extends Material {
     readonly depthCompare: GPUCompareFunction;
     readonly depthOnlyFragment: boolean;
     readonly depthBias: number;
-    readonly depthBiasSlopeScale: number;
+    readonly depthBiasSlopeScale: number;
+    /** Optional stencil-test state baked into the main-pass pipeline (mask write / discard). Set after
+     *  creation (`mat.stencil = { ... }`) and call `enableMaterialStencil()` before `registerScene`. Default
+     *  none. See `StencilState`. */
+    stencil?: StencilState;
 
 /** Options describing a ShaderMaterial: WGSL sources, attributes, uniforms,
  *  samplers, defines, and blend/depth state. Passed to `createShaderMaterial()`. */
@@ -6847,6 +7230,14 @@ export declare function showPhysicsBody(viewer: PhysicsViewer, body: PhysicsBody
 /** Shows a simplified Physics V2 constraint overlay: local axes (with arrowheads) plus angular-limit disks. */
 export declare function showPhysicsConstraint(viewer: PhysicsViewer, constraint: PhysicsConstraintDebug): Mesh[];
 
+/** A skinned model's skeleton — one per glTF skin, surfaced on
+ *  `AssetContainer.skeletons` once {@link enableBoneControl} is called. Reach its
+ *  bones via `skeleton.bones` / {@link getBoneByName}, and drive them via the
+ *  `setBone*` functions. */
+export declare interface Skeleton {
+    /** Bones in glTF joint order (matches the skin's `joints` array). */
+    readonly bones: readonly Bone[];
+
 /** Connects a skeleton to its GPU bone texture for per-frame updates. */
 declare interface SkeletonBinding {
     readonly jointNodes: readonly number[];
@@ -7256,6 +7647,9 @@ export declare interface StandardMaterialProps extends Material {
      *  on top of the built-in Standard pipeline). Attach via `material.plugins = [plugin]`,
      *  then call `enableMaterialPlugins(scene)` before `registerScene`. */
     plugins?: MaterialPlugin[];
+    /** Optional stencil-test state baked into the main-pass pipeline (mask write / discard). Default none.
+     *  See `StencilState`. */
+    stencil?: StencilState;
     diffuseColor: [number, number, number];
     alpha: number;
     specularColor: [number, number, number];
@@ -7338,6 +7732,29 @@ export declare function startEngine(engine: EngineContext): Promise<void>;
  */
 export declare function startSpriteAnimationManager(manager: SpriteAnimationManager): void;
 
+/** Optional stencil-test state baked into a material's main-pass pipeline. Shared by every concrete material kind
+ *  (Standard, PBR, Shader) so none has to depend on another. Lets one material WRITE the stencil buffer where it
+ *  draws (a mask) and another DISCARD fragments where the stencil was written — with NO dynamic stencil reference:
+ *  a writer uses `compare:"always"` + `passOp:"increment-clamp"` (stencil 0→1 where it draws); a tester uses
+ *  `compare:"equal"` (passes only where the stencil is still 0, i.e. NOT written), since the render pass's default
+ *  stencil reference is 0. Only takes effect on a stencil-capable depth target (the main color pass); ignored on
+ *  depth-only/shadow targets. Assigning `material.stencil` is inert until {@link enableMaterialStencil} is called
+ *  (the opt-in that keeps stencil-free scenes byte-identical) — call it once before `registerScene`. */
+export declare interface StencilState {
+    /** Stencil compare function, applied to front & back faces. Default `"always"`. */
+    readonly compare?: GPUCompareFunction;
+    /** Stencil operation when the stencil + depth tests both pass. Default `"keep"`. */
+    readonly passOp?: GPUStencilOperation;
+    /** Stencil operation when the stencil test fails. Default `"keep"`. */
+    readonly failOp?: GPUStencilOperation;
+    /** Stencil operation when the stencil test passes but depth fails. Default `"keep"`. */
+    readonly depthFailOp?: GPUStencilOperation;
+    /** Stencil read mask. Default `0xFF`. */
+    readonly readMask?: number;
+    /** Stencil write mask. Default `0xFF`. */
+    readonly writeMask?: number;
+}
+
 /** Stop playback and reset to frame 0. */
 export declare function stopAnimation(group: AnimationGroup): void;
 
@@ -7447,6 +7864,7 @@ export declare interface Task {
     dispose(): void;
 }
 
+/** Mutable text block data containing glyph runs and the packed per-glyph instance buffer consumed by text renderers. */
 export declare interface TextData {
     readonly [textDataBrand]: true;
     /** Live, in-insertion-order view of the runs currently rendered. Mutated by
@@ -7500,6 +7918,7 @@ export declare interface TextLayer {
    readonly data: TextData;
     opacity: number;
     visible: boolean;
 
+/** Initial placement and compositing options for a 2D text layer in a standalone text renderer. */
 export declare interface TextLayerOptions {
     /** Top-left origin (in canvas pixels) for the layer's local coordinate frame. Default (0, 0). */
     readonly positionPx?: {
@@ -7518,6 +7937,7 @@ export declare interface TextLayerOptions {
     readonly visible?: boolean;
 }
 
+/** Options for the default text layout helper, expressed in output pixels with simple LTR word wrapping. */
 export declare type TextLayoutOptions = {
     /** Max line width in pixels before word-wrap. Default: Infinity. */
     readonly maxWidth?: number;
@@ -7531,6 +7951,7 @@ export declare type TextLayoutOptions = {
     readonly tabSize?: number;
 };
 
+/** Scene renderable that draws a `TextData` block with mesh-like transform controls. */
 export declare interface TextRenderable extends Renderable {
    readonly position: ObservableVec3;
     readonly rotation: EulerProxy;
     readonly rotationQuaternion: ObservableQuat;
@@ -7540,6 +7961,7 @@ export declare interface TextRenderable extends Renderable {
    readonly positi
     ignoreDepth: boolean;
     order: number;
 
+/** Initial transform and draw options for a scene-attached text renderable. */
 export declare interface TextRenderableOptions {
     readonly position?: Readonly<Vec3>;
     readonly rotationQuaternion?: {
@@ -7556,8 +7978,10 @@ export declare interface TextRenderableOptions {
     readonly order?: number;
 }
 
+/** Standalone rendering context that draws sorted 2D text layers directly to the swapchain. */
 export declare interface TextRenderer extends RenderingContext_2 {
    readonly layers: readonly TextLayer[];
 
+/** Options for creating a standalone text renderer that draws directly to a surface. */
 export declare interface TextRendererOptions {
     layers: readonly TextLayer[];
     /** Default true. Set false for HUD overlays so the text pass preserves existing scene color. */
@@ -7718,6 +8142,7 @@ export declare interface TranslucencyProps {
     diffusionDistance?: [number, number, number];
 }
 
+/** Options controlling how a render task exposes opaque scene color to transmissive materials. Use these to opt out of the linear offscreen path, control refresh frequency, and limit mipmap generation cost. */
 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
@@ -7792,6 +8217,7 @@ export declare function unregisterScene(scene: SceneContext): void;
 /** Splice the renderer out of its engine's `_renderingContexts`. No-op if not present. */
 export declare function unregisterSpriteRenderer(sr: SpriteRenderer): void;
 
+/** Unregister a text renderer from its surface without disposing its layer data. */
 export declare function unregisterTextRenderer(tr: TextRenderer): void;
 
 /** Advances every active task by `deltaMs` (or by `fixedDeltaMs` when set), running the category handler first.
@@ -7887,6 +8313,10 @@ export declare function updateSprite2DIndex(layer: Sprite2DLayer, index: number,
  */
 export declare function updateSpriteAnimationManager(manager: SpriteAnimationManager, deltaMs: number): void;
 
+/** Apply an incremental edit to a `TextData`, such as adding, removing, replacing, or compacting runs.
+ *
+ *  @param data - Text data block to update.
+ *  @param update - Discriminated update operation to apply. */
 export declare function updateTextData(data: TextData, update: TextDataUpdate): void;
 
 /**
@@ -7914,6 +8344,7 @@ export declare interface UtilityLayer {
     readonly mainScene: SceneContext;
 }
 
+/** Options used when creating a utility layer for gizmos and overlays. */
 export declare interface UtilityLayerOptions {
     /** Add a built-in hemispheric light so gizmo materials are visible without
      *  the caller adding one. Defaults to true. */