@babylonjs/lite 0.1.1 → 1.0.0

package/index.d.ts

@@ -1,3 +1,6 @@
+/** Increment ref count on a Texture2D. First acquire sets count to 1. */
+export declare function acquireTexture(tex: Texture2D): void;
+
 /** Add an agent to the crowd. Returns the agent index. */
 export declare function addAgent(crowd: NavCrowd, position: Vec3, params: AgentParameters): number;
 
@@ -48,6 +51,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.
  *
@@ -120,13 +132,20 @@ export declare function addTaskAtStart(target: FrameGraph | SceneContext, task:
 /** Insert a task BEFORE another task in execute order. Accepts a FrameGraph or a SceneContext. */
 export declare function addTaskBefore(target: FrameGraph | SceneContext, task: Task, before: Task): void;
 
+/** Attach a `TextRenderable` to a scene. Uses the scene's deferred-renderables hook. */
+export declare function addTextRenderable(scene: SceneContext, renderable: TextRenderable): void;
+
+export declare function addTextRendererLayer(tr: TextRenderer, layer: TextLayer): void;
+
 /** Add one instance. Returns its index. Grows capacity as needed. */
 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.
  */
@@ -308,6 +327,36 @@ export declare interface AnisotropyProps {
 
 declare type AnyMaterial = StandardMaterialProps | PbrMaterialProps;
 
+/**
+ * Append `sources` into the remaining free space of an atlas previously built by
+ * `createSpriteAtlasFromFrames`. The existing `GPUTexture` (and any bind group already
+ * referencing it) stays valid — each new frame is uploaded with a single
+ * `queue.writeTexture` and the UV slots of the *existing* frames are not touched, so
+ * sprite instances already drawing from this atlas remain correct.
+ *
+ * Returns the integer indices of the newly-appended frames in `atlas.frames`, in input
+ * order. Sources are validated and placed before any texel is written, so a thrown
+ * "atlas full" error leaves the atlas state untouched (all-or-nothing semantics).
+ *
+ * Throws when:
+ *   - The atlas was built by `createGridSpriteAtlas` / `loadSpriteAtlas` (no packer state).
+ *   - Any source has invalid size / sub-rect / pixel buffer length.
+ *   - A source wider than `maxWidthPx` is supplied (cannot fit any shelf).
+ *   - The packed sources would overflow the atlas height. Pre-size the atlas via
+ *     `createSpriteAtlasFromFrames(engine, [...], { capacityPx: [w, h] })` to reserve room.
+ */
+export declare function appendSpriteAtlasFrames(engine: EngineContext, atlas: SpriteAtlas, sources: readonly SpriteAtlasFrameSource[]): number[];
+
+/**
+ * Apply a one-shot linear impulse (kg·m/s) to a body at a world `point` (defaults to the body's
+ * current position / centre of mass), waking it if asleep. Used to shoot, throw, or shove a prop.
+ * @param world - The physics world.
+ * @param body - The body to push.
+ * @param impulse - World-space impulse vector (kg·m/s).
+ * @param point - World point of application; defaults to the body's current position.
+ */
+export declare function applyPhysicsImpulse(world: PhysicsWorld, body: PhysicsBody, impulse: Vec3, point?: Vec3): void;
+
 /** ArcRotateCamera — orbits around a target point.
  *  Uses Babylon.js convention: left-handed, alpha=rotation around Y, beta=elevation.
  *  Plain data + methods. Does NOT know about the scene.
@@ -338,11 +387,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.
@@ -369,6 +446,16 @@ export declare interface AssetContainer {
     };
 }
 
+/** 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;
+
+export declare function attachAxisScaleGizmoToNode(gizmo: AxisScaleGizmo, node: SceneNode | null): void;
+
+export declare function attachBoundingBoxGizmoToNode(gizmo: BoundingBoxGizmo, node: SceneNode | null): void;
+
+export declare function attachCameraGizmoToCamera(gizmo: CameraGizmo, camera: Camera | null): void;
+
 /**
  * Attach orbit/zoom/pan controls to an ArcRotateCamera.
  * Matches Babylon.js ArcRotateCameraPointersInput behavior with inertia:
@@ -378,12 +465,43 @@ 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.
  */
-export declare function attachControl(camera: ArcRotateCamera, canvas: HTMLCanvasElement, scene?: SceneContext): () => void;
+export declare function attachControl(camera: ArcRotateCamera, canvas: HTMLCanvasElement, scene?: SceneContext, options?: AttachControlOptions): () => void;
+
+/**
+ * Optional hooks that let an {@link attachControl} caller defer pointer
+ * gestures to an external interactor (typically a gizmo pointer-drag
+ * dispatcher) so the camera doesn't orbit when the user is interacting with
+ * something else on top of it.  All fields are optional; omit them to keep
+ * the default behavior (the camera always handles its own pointer input).
+ */
+export declare interface AttachControlOptions {
+    /** Optional predicate consulted on every pointer-down.  When it returns
+     *  false the camera ignores that gesture (no rotate / pan).  Used to defer
+     *  to gizmo interaction so pressing or dragging a gizmo doesn't also orbit
+     *  the camera. */
+    shouldHandlePointerDown?: (event: PointerEvent) => boolean;
+    /** Optional predicate consulted on pointer-move while a camera drag is in
+     *  progress.  When it returns true the camera ABORTS the current drag.
+     *  Because gizmo picking is async, a press on a gizmo may not be known at
+     *  pointer-down time (so the camera optimistically starts orbiting); once
+     *  the gizmo drag is recognised a frame later this lets the gizmo reclaim
+     *  the gesture and undo the (not-yet-applied) orbit. */
+    isExternalDragActive?: () => boolean;
+    /** Optional predicate consulted on pointer-move.  While it returns true the
+     *  camera DEFERS its orbit (consumes the move without applying it) — used
+     *  to wait out an in-flight async gizmo pick so a press that lands on a
+     *  gizmo never produces a stray orbit, regardless of pick latency. */
+    isExternalPickPending?: () => boolean;
+}
 
 /**
  * Attach keyboard + mouse controls to a FreeCamera.
@@ -399,6 +517,36 @@ export declare function attachControl(camera: ArcRotateCamera, canvas: HTMLCanva
  */
 export declare function attachFreeControl(camera: FreeCamera, canvas: HTMLCanvasElement, scene?: SceneContext): () => void;
 
+/**
+ * Attach orbit / pan / zoom controls to a {@link GeospatialCamera}, matching
+ * Babylon.js `GeospatialCamera` interactions:
+ *  - Left-drag: pan (the cursor stays anchored to the globe surface).
+ *  - Middle/right-drag: rotate (yaw + pitch / tilt).
+ *  - Wheel: zoom (toward the cursor by default).
+ *  - Keyboard: arrows = tilt, W/A/S/D = pan, +/- = zoom.
+ *
+ * Movement uses Babylon.js's framerate-independent physics model (velocity +
+ * inertial decay). Globe picking is analytic ray-sphere against the planet
+ * sphere (origin-centred, radius = `limits.planetRadius`) — no mesh picking
+ * subsystem is required. Inertia is integrated once per frame from the scene's
+ * render loop (`scene._beforeRender`).
+ *
+ * Returns a disposer that removes all listeners and the per-frame hook.
+ */
+export declare function attachGeospatialControls(camera: GeospatialCamera, canvas: HTMLCanvasElement, scene: SceneContext, options?: GeospatialControlOptions): () => void;
+
+export declare function attachLightGizmoToLight(gizmo: LightGizmo, light: LightBase | null): void;
+
+export declare function attachPlaneDragGizmoToNode(gizmo: PlaneDragGizmo, node: SceneNode | null): void;
+
+export declare function attachPlaneRotationGizmoToNode(gizmo: PlaneRotationGizmo, node: SceneNode | null): void;
+
+export declare function attachPositionGizmoToNode(gizmo: PositionGizmo, node: SceneNode | null): void;
+
+export declare function attachRotationGizmoToNode(gizmo: RotationGizmo, node: SceneNode | null): void;
+
+export declare function attachScaleGizmoToNode(gizmo: ScaleGizmo, node: SceneNode | null): void;
+
 /**
  * Attaches a manager to a sprite renderer's update hooks so its animations advance each frame.
  * @param renderer - Sprite renderer whose update loop drives the manager.
@@ -417,9 +565,76 @@ export declare function attachSpriteAnimationsToRenderer(renderer: SpriteRendere
  */
 export declare function attachSpriteAnimationsToScene(scene: SceneContext, manager: SpriteAnimationManager): SpriteAnimationBinding;
 
+/**
+ * Attach a baked VAT to a mesh: builds the settings UBO, sets `mesh.vat` (reusing the skeleton's
+ * joints/weights vertex buffers), and DROPS the live skeleton so it's no longer CPU-updated. Returns a
+ * handle that advances the animation clock.
+ *
+ * @param engine - Engine context.
+ * @param mesh   - The mesh that was baked (still has `mesh.skeleton`).
+ * @param baked  - The result of `bakeVat`.
+ * @param clip   - Initial clip name to play (defaults to the first baked clip).
+ */
+export declare function attachVat(engine: EngineContext, mesh: Mesh, baked: VatBakeResult, clip?: string): VatHandle;
+
+export declare interface AxisDragGizmo {
+    /** The root node — gizmo follows its `attachedNode` by copying world translation. */
+    readonly root: SceneNode;
+    /** Drag behaviour driving the pointer interaction. */
+    readonly drag: PointerDrag;
+    /** Fired whenever a drag delta is applied to the attached node. */
+    readonly onPositionChanged: GizmoObservable<Vec3>;
+    /** Currently attached node — set via `attachAxisDragGizmoToNode`. */
+    attachedNode: SceneNode | null;
+    /** When true, the gizmo's drag axis is rotated each frame by the attached
+     *  node's world rotation (local-coord mode).  When false (default), the
+     *  drag axis stays world-aligned.  Mirrors BJS
+     *  `updateGizmoRotationToMatchAttachedMesh`. */
+    useLocalCoordinates: boolean;
+    /** Material triplet (colored / hover / disabled).  Hover state is updated
+     *  automatically during pointer-down on the collider. */
+    readonly materials: GizmoMaterialSet;
+
+export declare interface AxisDragGizmoOptions {
+    /** World-space drag axis (unit vector). */
+    dragAxis: Vec3;
+    /** Material color of the rendered arrow.  Defaults to grey. */
+    color?: [number, number, number];
+    /** Hover material colour (defaults to yellow). */
+    hoverColor?: [number, number, number];
+    /** Disabled-state material colour (defaults to grey, alpha 0.4). */
+    disableColor?: [number, number, number];
+    /** Multiplier applied to the rendered arrow's tube/cone thickness. */
+    thickness?: number;
+}
+
 /** A billboard sprite system that rotates only around a fixed world axis. */
 export declare type AxisLockedBillboardSpriteSystem = BillboardSpriteSystem<"axis-locked">;
 
+export declare interface AxisScaleGizmo {
+    readonly root: SceneNode;
+    readonly drag: PointerDrag;
+    readonly onScaleChanged: GizmoObservable<Vec3>;
+    attachedNode: SceneNode | null;
+    /** Local-coord mode: drag axis rotates with the attached node. */
+    useLocalCoordinates: boolean;
+    readonly materials: GizmoMaterialSet;
+
+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. */
+    dragAxis: Vec3;
+    color?: [number, number, number];
+    hoverColor?: [number, number, number];
+    disableColor?: [number, number, number];
+    /** Tube thickness multiplier (visible only; collider gets +4). */
+    thickness?: number;
+    /** Optional multiplier on the per-frame drag strength. Default 1. */
+    sensitivity?: number;
+    /** When true, scale uniformly on all 3 axes (matches BJS uniformScaling). */
+    uniformScaling?: boolean;
+}
+
 /**
  * Bakes the mesh's current world matrix into its splat vertices, then resets the mesh's
  * position, rotation, and scaling to identity so the visual result is unchanged.
@@ -435,6 +650,17 @@ export declare function bakeCurrentTransformIntoVertices(mesh: GaussianSplatting
  */
 export declare function bakeTransformIntoVertices(mesh: GaussianSplattingMesh, transform: Mat4): void;
 
+/**
+ * Bake the given animation clips of a skinned mesh into a VAT texture. The clips are laid out as
+ * contiguous row blocks (clip 0 first), one texture row per frame. The mesh must still have its live
+ * `skeleton` at bake time (the bone matrices are read from it as each frame is evaluated).
+ *
+ * @param engine - Engine context.
+ * @param mesh   - The skinned source mesh (must have `mesh.skeleton`).
+ * @param groups - The animation clips to bake (e.g. a creature's gait clips).
+ */
+export declare function bakeVat(engine: EngineContext, mesh: Mesh, groups: AnimationGroup[]): VatBakeResult;
+
 /**
  * Additive blending for world-space billboards. The billboard's RGB, scaled by its own alpha, is
  * added to the framebuffer (no depth write, like the other transparent modes), so overlapping
@@ -594,9 +820,36 @@ export declare interface BlurPostProcessTaskConfig extends Omit<PostProcessTaskC
     kernel?: number;
 }
 
+export declare interface BoundingBoxGizmo {
+    readonly root: SceneNode;
+    /** Currently attached node — set via `attachBoundingBoxGizmoToNode`. */
+    attachedNode: SceneNode | null;
+    /** Fires when any drag (scale / rotate / translate) updates the attached node. */
+    readonly onChanged: GizmoObservable<void>;
+    /** Material used to render all gizmo geometry. */
+    readonly material: StandardMaterialProps;
+
+export declare interface BoundingBoxGizmoOptions {
+    /** RGB colour for the wireframe + handle materials. Defaults to grey. */
+    color?: [number, number, number];
+    /** Edge wireframe thickness (world units before scaling). Default 0.06. */
+    edgeThickness?: number;
+    /** Side length of the 8 corner scale boxes (world units). Default 0.18. */
+    scaleBoxSize?: number;
+    /** Length of the 12 elongated edge rotation anchors (world units). Default
+     *  0.16; thickness is length/4 (BJS 1.6:0.4 ratio). */
+    rotationAnchorSize?: number;
+}
+
 /** 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;
@@ -606,6 +859,30 @@ export declare interface Camera {
     readonly worldMatrix: Mat4;
     readonly worldMatrixVersion: number;
 
+export declare interface CameraGizmo {
+    /** Root node — the gizmo follows the attached camera's world translation
+     *  and orientation each frame. */
+    readonly root: SceneNode;
+    /** Material shared by the body + frustum.  Mutate `diffuseColor` to recolor. */
+    readonly material: StandardMaterialProps;
+    /** Alias of `material` — kept for backward compatibility with callers
+     *  that mutated `frustumMaterial` against the older variant. */
+    readonly frustumMaterial: StandardMaterialProps;
+    /** Currently attached camera — set via `attachCameraGizmoToCamera`. */
+    attachedCamera: Camera | null;
+
+export declare interface CameraGizmoOptions {
+    /** RGB color for the camera body + frustum material.  Defaults to grey. */
+    color?: [number, number, number];
+    /** RGB color for the frustum wireframe edges (alias of `color` kept for
+     *  backward compatibility with the previous tube-body variant). */
+    frustumColor?: [number, number, number];
+    /** Set to false to omit the frustum wireframe.  Defaults to true. */
+    displayFrustum?: boolean;
+    /** Set to false to omit the camera body mesh (box + cylinders). Default true. */
+    displayBody?: boolean;
+}
+
 /** Cap mode: close both ends of the tube/extrusion. */
 export declare const CAP_ALL = 3;
 
@@ -618,6 +895,32 @@ export declare const CAP_NONE = 0;
 /** Cap mode: close only the start of the tube/extrusion. */
 export declare const CAP_START = 1;
 
+/**
+ * Capture the current canvas backbuffer of a {@link SurfaceContext} — the final presented
+ * frame (post-processing and all) with NO HTML/DOM overlay, since those are never drawn
+ * into the canvas.
+ *
+ * Pass `engine` to capture the engine's primary surface (the canvas given to `createEngine`),
+ * or pass an auxiliary surface returned by `createSurface` to capture that canvas. Each
+ * surface owns its own capture queue and COPY_SRC swapchain state, so surfaces that never
+ * capture stay compression-friendly even when another surface on the same engine is being
+ * captured every frame.
+ *
+ * The read is scheduled on a rendered frame: the copy is recorded into that frame's command
+ * encoder (so it reads a valid, just-rendered swapchain texture), then the staging buffer is
+ * mapped after submit and the pixels are unpacked. Requires a running render loop
+ * (`startEngine`); the returned promise resolves once the readback completes.
+ *
+ * Multiple calls queued on the same surface before the next serviced frame share a single
+ * GPU copy and all resolve with the same image.
+ *
+ * The readback implementation is loaded lazily on the first call, so engines whose surfaces
+ * never capture a screenshot ship none of it. The surface's swapchain stays a plain,
+ * compression-friendly RENDER_ATTACHMENT surface until the first capture is queued, at which
+ * point `renderFrame` reconfigures it once with COPY_SRC (before acquiring that frame's texture).
+ */
+export declare function captureScreenshot(surface: SurfaceContext): Promise<Screenshot>;
+
 /** A post-process task that offsets the red/green/blue channels to simulate lens chromatic aberration. */
 export declare interface ChromaticAberrationPostProcessTask extends PostProcessTask {
     aberrationAmount: number;
@@ -634,6 +937,57 @@ export declare interface ChromaticAberrationPostProcessTaskConfig extends Omit<P
     centerPosition?: PostProcessVec2_2;
 }
 
+/** A post-process task that writes the per-pixel circle-of-confusion (grayscale)
+ *  derived from scene depth and the lens focus parameters. */
+export declare interface CircleOfConfusionPostProcessTask extends PostProcessTask {
+    lensSize: number;
+    fStop: number;
+    focusDistance: number;
+    focalLength: number;
+}
+
+/**
+ * Configuration for `createCircleOfConfusionPostProcessTask`.
+ *
+ * Models Babylon.js's `FrameGraphCircleOfConfusionTask` +
+ * `ThinCircleOfConfusionPostProcess`.
+ */
+export declare interface CircleOfConfusionPostProcessTaskConfig extends Omit<PostProcessTaskConfig, "_shader"> {
+    /** Depth texture supplying per-pixel scene depth. With `depthNotNormalized`
+     *  it must store **camera-space (view) depth** (the geometry renderer's
+     *  VIEW_DEPTH attachment); otherwise it stores normalized [0,1] view depth. */
+    depthTexture: RenderTarget;
+    /** Camera used to read minZ/maxZ when the depth is normalized. */
+    camera: Camera;
+    /** Max lens size in scene units / 1000 (e.g. mm). Standard cameras are 50mm. Default 50. */
+    lensSize?: number;
+    /** F-Stop of the camera. Aperture diameter = lensSize / fStop. Default 1.4. */
+    fStop?: number;
+    /** Distance from the camera to focus on, in scene units / 1000. Default 2000. */
+    focusDistance?: number;
+    /** Focal length of the camera in scene units / 1000. Default 50. */
+    focalLength?: number;
+    /** When true the depth texture stores camera-space depth (0..maxZ) rather
+     *  than normalized [0,1] depth, skipping the `cameraMinMaxZ` reconstruction. */
+    depthNotNormalized?: boolean;
+}
+
+/**
+ * Clamp the camera centre away from the geographic poles (in place), so the
+ * tangent basis stays well-defined. Mirrors Babylon.js `ClampCenterFromPolesInPlace`.
+ */
+export declare function clampCenterFromPoles(center: Vec3): Vec3;
+
+/**
+ * Clamps a requested zoom distance so it respects the radius limits.
+ * @param limits - The geospatial limits.
+ * @param zoomDistance - Requested zoom (positive = zoom in, negative = zoom out).
+ * @param currentRadius - Current camera radius.
+ * @param distanceToTarget - Optional distance to the zoom target point (used for zoom-in clamping).
+ * @returns The clamped zoom distance.
+ */
+export declare function clampZoomDistance(limits: GeospatialLimits, zoomDistance: number, currentRadius: number, distanceToTarget?: number): number;
+
 /** Removes and disposes every task attached to `manager`. */
 export declare function clearAnimationManager(manager: AnimationManager): void;
 
@@ -668,6 +1022,9 @@ export declare interface ClearCoatProps {
     useF0Remap?: boolean;
 }
 
+/** Clear sampler cache for a device. */
+export declare function clearSamplerCache(engine: EngineContext): void;
+
 /** Clear all sprites from a layer while preserving allocated capacity. */
 export declare function clearSprite2DLayer(layer: Sprite2DLayer): void;
 
@@ -680,40 +1037,149 @@ 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;
 }
 
+/**
+ * Build the east/north/up orthonormal basis at a point on the globe (left-handed
+ * convention). `up` is the geocentric normal (normalized position); `east` and
+ * `north` complete a right-handed-looking tangent frame given the LH world.
+ * Writes into the provided result objects and returns nothing.
+ */
+export declare function computeLocalBasis(worldPos: Vec3, refEast: Vec3, refNorth: Vec3, refUp: Vec3): void;
+
+/**
+ * Compute the lookAt direction from yaw/pitch at a centre point (forward formula).
+ * Writes the normalized direction into `result`.
+ */
+export declare function computeLookAtFromYawPitch(yaw: number, pitch: number, center: Vec3, result: Vec3): Vec3;
+
 /** Compute a path between two world positions, snapped to the navmesh. */
 export declare function computePath(plugin: NavigationPlugin, start: Vec3, end: Vec3): Vec3[];
 
+/**
+ * Inverse of {@link computeLookAtFromYawPitch}: given a lookAt direction and centre,
+ * recover the yaw/pitch that would produce it. Writes `[yaw, pitch]` into `result`.
+ * `currentYaw` is used as a fallback when looking straight down/up (yaw undefined).
+ */
+export declare function computeYawPitchFromLookAt(lookAt: Vec3, center: Vec3, currentYaw: number, result: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};
+
+export declare interface CopyToTextureTask extends Task {
+    readonly name: string;
+    sourceTexture: RenderTarget;
+    targetTexture: RenderTarget | undefined;
+    resolveTexture: RenderTarget | undefined;
+    viewport: NormalizedViewport | null | undefined;
+    lodLevel: number;
+    /** `resolveTexture` if set, otherwise `targetTexture`. Kept for API parity
+     *  with BJS `FrameGraphCopyToTextureTask.outputTexture`. */
+    readonly outputTexture: RenderTarget;
+}
+
+export declare interface CopyToTextureTaskConfig {
+    name?: string;
+    sourceTexture: RenderTarget;
+    /** Target attachment that receives the blit. Required UNLESS `resolveTexture`
+     *  is set, in which case the task does a resolve-only operation and writes
+     *  directly into `resolveTexture`. */
+    targetTexture?: RenderTarget;
+    /** Viewport applied to the target before the blit. When undefined (default),
+     *  the whole target is overwritten and the encoder-copy fast path becomes
+     *  available. When set, the blit path is used. */
+    viewport?: NormalizedViewport | null;
+    /** Source mip level to copy from. Default 0. The fast path uses this as
+     *  the source `mipLevel`; the blit path samples with `textureSampleLevel`. */
+    lodLevel?: number;
+    /** Optional single-sample texture that receives a hardware MSAA-resolve of
+     *  the task's MSAA color attachment at end-of-pass. Two modes:
+     *
+     *  - Blit + resolve: `targetTexture` is MSAA and `resolveTexture` is SS.
+     *    The shader blit writes into `targetTexture` and at end-of-pass the
+     *    GPU resolves `targetTexture` into `resolveTexture`.
+     *
+     *  - Resolve-only: `targetTexture` is omitted. The task runs a no-draw
+     *    render pass with `sourceTexture` as the color attachment (so the
+     *    source itself must be MSAA) and `resolveTexture` as its resolve
+     *    target. `viewport` and `lodLevel` are ignored. `sourceTexture` and
+     *    `resolveTexture` must have matching dimensions.
+     *
+     *  In both modes, `resolveTexture.format` must match the MSAA
+     *  attachment's format and `resolveTexture` must be single-sample. */
+    resolveTexture?: RenderTarget;
+}
+
 /**
  * Create a post-process task that merges a left-eye texture with the source (right eye) into a red/cyan anaglyph.
  * @param config - Source/target settings and the left-eye `leftTexture`.
@@ -747,6 +1213,10 @@ export declare function createAnimationTask(update: AnimationTaskUpdate, options
 /** Create a bare ArcRotateCamera with given params. Pure data, no scene knowledge. */
 export declare function createArcRotateCamera(alpha: number, beta: number, radius: number, target: Vec3): ArcRotateCamera;
 
+/** Build an axis-drag gizmo and attach it to the given utility layer.  Call
+ *  `attachAxisDragGizmoToNode` to bind it to a node so it follows + drives it. */
+export declare function createAxisDragGizmo(engine: EngineContext, layer: UtilityLayer, options: AxisDragGizmoOptions): AxisDragGizmo;
+
 /**
  * Creates a billboard sprite system whose quads rotate only around a fixed world axis.
  * @param atlas - Sprite atlas supplying frames.
@@ -757,6 +1227,8 @@ export declare function createArcRotateCamera(alpha: number, beta: number, radiu
  */
 export declare function createAxisLockedBillboardSystem(atlas: SpriteAtlas, axis: readonly [number, number, number], opts?: BillboardSpriteSystemOptions): AxisLockedBillboardSpriteSystem;
 
+export declare function createAxisScaleGizmo(engine: EngineContext, layer: UtilityLayer, options: AxisScaleGizmoOptions): AxisScaleGizmo;
+
 /**
  * Build a custom-shader descriptor to pass as `customShader` when creating a billboard system.
  * The descriptor is opaque; the pipeline consumes it lazily.
@@ -790,9 +1262,28 @@ export declare function createBloomPostProcessTask(config: BloomPostProcessTaskC
  */
 export declare function createBlurPostProcessTask(config: BlurPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): BlurPostProcessTask;
 
+export declare function createBoundingBoxGizmo(engine: EngineContext, layer: UtilityLayer, options?: BoundingBoxGizmoOptions): BoundingBoxGizmo;
+
 /** Create a box mesh. Caller must assign material. */
 export declare function createBox(engine: EngineContext, size?: number): Mesh;
 
+/** Build a display-only camera gizmo and attach it to the given utility
+ *  layer.  Call `attachCameraGizmoToCamera` to bind a camera.
+ *
+ *  The gizmo has two independently-toggleable parts, both visible by default
+ *  and parented to a root that follows the attached camera's world translation
+ *  + orientation each frame:
+ *
+ *  - A camera **body** (`displayBody`, defaults to `true`) — a distance-scaled
+ *    box + 3 cylinders ported from BJS `_CreateCameraMesh`, lit grey, sized
+ *    so it stays a roughly constant size on screen.
+ *  - A camera **frustum** (`displayFrustum`, defaults to `true`) — 12 thin
+ *    cylinder edges forming a truncated-pyramid wireframe sized from the
+ *    camera's fov / near / far (far clamped to 60× near), unlit white.
+ *
+ *  Set the matching option to `false` to display only one of them. */
+export declare function createCameraGizmo(engine: EngineContext, layer: UtilityLayer, options?: CameraGizmoOptions): CameraGizmo;
+
 /**
  * Create a post-process task that simulates chromatic aberration by shifting color channels outward from a center point.
  * @param config - Aberration parameters and source/target settings.
@@ -802,6 +1293,41 @@ export declare function createBox(engine: EngineContext, size?: number): Mesh;
  */
 export declare function createChromaticAberrationPostProcessTask(config: ChromaticAberrationPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): ChromaticAberrationPostProcessTask;
 
+/**
+ * Create a circle-of-confusion post-process task. The output is a grayscale map
+ * where 0 = in focus and 1 = maximally out of focus, computed from the supplied
+ * depth texture and the lens parameters (the usual first stage of a depth-of-field
+ * pipeline). See https://developer.nvidia.com/gpugems/GPUGems/gpugems_ch23.html.
+ *
+ * @param config - Depth texture, camera, lens parameters and source/target settings.
+ * @param engine - The owning engine.
+ * @param scene - Optional owning scene. Omit for scene-less standalone frame graphs.
+ * @returns The circle-of-confusion post-process task.
+ */
+export declare function createCircleOfConfusionPostProcessTask(config: CircleOfConfusionPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): CircleOfConfusionPostProcessTask;
+
+/**
+ * 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;
+
+export declare function createCopyToTextureTask(config: CopyToTextureTaskConfig, engine: EngineContext, scene: SceneContext): CopyToTextureTask;
+
 /**
  * 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,9 +1344,27 @@ 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;
 
+export declare function createCylinderData(options?: CylinderOptions): CylinderData;
+
 /**
  * Extract debug visualization geometry from the generated navmesh.
  * Faces are detached (each triangle gets its own 3 vertices) and per-vertex
@@ -841,6 +1385,28 @@ export declare function createDebugNavMeshGeometry(plugin: NavigationPlugin): {
  *  Matches Babylon.js createDefaultCameraOrLight(true, true, true). */
 export declare function createDefaultCamera(scene: SceneContext): ArcRotateCamera;
 
+/** Shape `text` with the default layout, extract glyph curves, and bundle into a
+ *  `DefaultTextData`. `textColor` is applied as the run's defaultColor (per-glyph color
+ *  overrides remain available via direct `updateTextData(replaceRun)` calls).
+ *
+ *  The returned `DefaultTextData` owns its underlying `GlyphStorage` — release both with
+ *  `disposeDefaultTextData(data)`. */
+export declare function createDefaultTextData(font: Font, fontSizePx: number, text: string, textColor?: readonly [number, number, number, number], options?: TextLayoutOptions): DefaultTextData;
+
+/**
+ * Create a depth-of-field post-process task. The source image is first reduced
+ * to a circle-of-confusion map (from the depth texture + lens parameters), then
+ * blurred at one to three decreasing resolutions with CoC-weighted blurs, and
+ * finally merged so each pixel transitions smoothly from sharp to blurred based
+ * on how far out of focus it is.
+ *
+ * @param config - Source/depth textures, camera, lens parameters, blur level, and target settings.
+ * @param engine - The owning engine.
+ * @param scene - Optional owning scene. Omit for scene-less standalone frame graphs.
+ * @returns The depth-of-field post-process task.
+ */
+export declare function createDepthOfFieldPostProcessTask(config: DepthOfFieldPostProcessTaskConfig, engine: EngineContext, scene?: SceneContext): DepthOfFieldPostProcessTask;
+
 /**
  * Creates a directional light shining along `direction` (a parallel light source, like the sun).
  * @param direction - World-space direction the light travels along.
@@ -860,7 +1426,7 @@ export declare function createDisc(engine: EngineContext, options?: DiscOptions)
  * Call `registerEffectRenderer` to start rendering, `unregisterEffectRenderer`
  * to pause, and `disposeEffectRenderer` to free GPU resources.
  */
-export declare function createEffectRenderer(engine: EngineContext, effect: EffectWrapper, options?: EffectRendererOptions): EffectRenderer;
+export declare function createEffectRenderer(surface: SurfaceContext, effect: EffectWrapper, options?: EffectRendererOptions): EffectRenderer;
 
 /**
  * Create a frame-graph task that draws an effect as a fullscreen pass into `config.target`.
@@ -880,9 +1446,15 @@ export declare function createEffectRenderTask(config: EffectRenderTaskConfig, e
  */
 export declare function createEffectWrapper(engine: EngineContext, options: EffectWrapperOptions): EffectWrapper;
 
-/** Create the Babylon Lite engine. Acquires GPU adapter + device, configures swapchain.
- *  Accepts either a DOM canvas (main thread) or an `OffscreenCanvas` (e.g. transferred to
- *  a Web Worker) — see {@link RenderCanvas}. */
+/** Create the Babylon Lite engine bound to `canvas`. Acquires the GPU adapter + device,
+ *  configures the canvas's WebGPU context, and returns an `EngineContext` that *is also*
+ *  the primary `SurfaceContext` — i.e. the returned engine is itself the surface for the
+ *  given canvas. Additional canvases can be attached afterwards via
+ *  `createSurface(engine, otherCanvas, ...)`; they share device-scoped GPU resources
+ *  (textures, meshes, pipelines, bind groups) with the engine and with each other.
+ *
+ *  Accepts either a DOM canvas (main thread) or an `OffscreenCanvas` (e.g. transferred
+ *  to a Web Worker) — see {@link RenderCanvas}. */
 export declare function createEngine(canvas: RenderCanvas, options?: EngineOptions): Promise<EngineContext>;
 
 /**
@@ -915,12 +1487,32 @@ export declare function createExtrudeShape(engine: EngineContext, options: Extru
  */
 export declare function createFacingBillboardSystem(atlas: SpriteAtlas, opts?: BillboardSpriteSystemOptions): FacingBillboardSpriteSystem;
 
-/** Create a scene-less frame-graph context for fullscreen effects and post-process chains. */
-export declare function createFrameGraphContext(engine: EngineContext, options?: FrameGraphContextOptions): FrameGraphContext;
+/** Build a `Font` from an in-memory TTF/OTF buffer. */
+export declare function createFontFromBuffer(data: ArrayBuffer): Font;
+
+/** Create a scene-less frame-graph context bound to `surface`, for fullscreen effects
+ *  and post-process chains. Pass the engine directly for the single-canvas case (since
+ *  `EngineContext extends SurfaceContext`); pass an auxiliary surface for multi-canvas. */
+export declare function createFrameGraphContext(surface: SurfaceContext, options?: FrameGraphContextOptions): FrameGraphContext;
 
 /** Create a FreeCamera at the given position looking at target. Pure data, no scene knowledge. */
 export declare function createFreeCamera(position: Vec3, target: Vec3): FreeCamera;
 
+/** Create a geometry-renderer task. All GPU resources are allocated lazily
+ *  during the first `record()` call (when the frame graph is built). */
+export declare function createGeometryRendererTask(config: GeometryRendererTaskConfig, engine: EngineContext, scene: SceneContext): GeometryRendererTask;
+
+/** Create a {@link GeospatialCamera} for a planet of the given radius. Pure data, no scene knowledge. */
+export declare function createGeospatialCamera(options: GeospatialCameraOptions): GeospatialCamera;
+
+/** Create geospatial limits for a planet of the given radius, matching Babylon.js defaults. */
+export declare function createGeospatialLimits(planetRadius: number): GeospatialLimits;
+
+/** Build a `GlyphStorage`. If `initial` is provided, each curve-set is packed into its
+ *  own atlas synchronously. The passed inner maps are *adopted* by the storage — the
+ *  caller must not mutate them directly afterward (use `updateGlyphStorage` instead). */
+export declare function createGlyphStorage(initial?: Map<CurveSetId, Map<number, GlyphCurves>>): GlyphStorage;
+
 /** Create a GPU picker bound to the given scene. */
 export declare function createGpuPicker(scene: SceneContext): GpuPicker;
 
@@ -957,6 +1549,9 @@ export declare function createGroundFromHeightMap(engine: EngineContext, url: st
  *   const hknp = await HavokPhysics({ locateFile: () => "/HavokPhysics.wasm" });
  *   const world = createHavokWorld(scene, hknp);
  * ```
+ *
+ * For Large World Rendering, call {@link enableHavokFloatingOrigin} on the returned world (before
+ * creating any bodies) to opt into multi-region floating-origin simulation.
  */
 export declare function createHavokWorld(scene: SceneContext, hknp: any, gravity?: Vec3): PhysicsWorld;
 
@@ -974,6 +1569,11 @@ export declare function createHemisphericLight(direction?: [number, number, numb
  */
 export declare function createImageProcessingTask(config: ImageProcessingTaskConfig, engine: EngineContext, scene: SceneContext): Task;
 
+/** Build a display-only light gizmo and attach it to the utility layer.  The
+ *  per-light-type geometry is built lazily on the first `attachLightGizmoToLight`
+ *  (since the light type isn't known until then). */
+export declare function createLightGizmo(engine: EngineContext, layer: UtilityLayer, options?: LightGizmoOptions): LightGizmo;
+
 /** Create a linear-depth ShaderMaterial that writes `(d, d, d, 1)` per fragment.
  *  The depth is computed from the view-space z, normalized by the supplied
  *  near/far range (or 0.03/15 by default).  Override per material via the
@@ -1053,6 +1653,11 @@ export declare function createNavigationPluginAsync(options?: {
  */
 export declare function createNavMesh(plugin: NavigationPlugin, meshes: Mesh[], params: NavMeshParameters): void;
 
+/** Build a navmesh from raw CPU geometry sources. This is the non-rendering twin of
+ * `createNavMesh`: callers that already own procedural navigation geometry can avoid
+ * creating hidden GPU meshes just to feed Recast. */
+export declare function createNavMeshFromSources(plugin: NavigationPlugin, sources: NavMeshSource[], params: NavMeshParameters): void;
+
 /** Create a no-color view over a NodeMaterial source. */
 export declare function createNodeNoColorMaterialView(source: NodeMaterial): MaterialView;
 
@@ -1111,6 +1716,14 @@ export declare function createPhysicsShape(world: PhysicsWorld, options: Physics
 /** Create a plane (unit quad facing -Z). Caller must assign material. */
 export declare function createPlane(engine: EngineContext, options?: PlaneOptions): Mesh;
 
+export declare function createPlaneDragGizmo(engine: EngineContext, layer: UtilityLayer, options: PlaneDragGizmoOptions): PlaneDragGizmo;
+
+export declare function createPlaneRotationGizmo(engine: EngineContext, layer: UtilityLayer, options: PlaneRotationGizmoOptions): PlaneRotationGizmo;
+
+/** Build a PointerDrag descriptor.  The drag is inert until `registerPointerDrag`
+ *  is called against a utility layer with collider meshes assigned to it. */
+export declare function createPointerDrag(options: PointerDragOptions): PointerDrag;
+
 /**
  * Creates a point light that emits in all directions from `position` with distance falloff.
  * @param position - World-space position of the light.
@@ -1122,6 +1735,11 @@ export declare function createPointLight(position: [number, number, number], int
 /** Create a polyhedron (15 presets). Caller must assign material. */
 export declare function createPolyhedron(engine: EngineContext, options?: PolyhedronOptions): Mesh;
 
+/** Build a composite position gizmo.  Colors match BJS PositionGizmo
+ *  defaults: half-saturation red / green / blue along X / Y / Z
+ *  (`Color3.Red().scale(0.5)` etc.). */
+export declare function createPositionGizmo(engine: EngineContext, layer: UtilityLayer, options?: PositionGizmoOptions): PositionGizmo;
+
 /**
  * Creates a Gaussian Splatting mesh with `splatCount` placeholder splats and attaches
  * it to the scene's render pipeline. Useful for procedurally filling splat data later.
@@ -1181,11 +1799,33 @@ export declare function createRenderTargetTexture(engine: EngineContext, descrip
  *  Swapchain-targeted tasks acquire the swap view per-frame at execute time. */
 export declare function createRenderTask(config: RenderTaskConfig, engine: EngineContext, scene: SceneContext): RenderTask;
 
+/**
+ * Create an empty `Texture2D` usable as **both a render target and a sampled texture**
+ * (`RENDER_ATTACHMENT | TEXTURE_BINDING`). This is the building block for offscreen
+ * render-to-texture: render a pass into `tex.view`, then sample `tex` in a later pass
+ * (e.g. a fullscreen post-process). Defaults to the engine's swapchain format + a
+ * linear sampler so the result can be presented directly.
+ *
+ * To use the result as a `SpriteRenderer` target (via `setSpriteRendererTarget`), leave
+ * `format` at its default `engine.format` — sprite pipelines bake in that format, so a
+ * differently-formatted target trips WebGPU validation at render-pass begin. A custom
+ * `format` is for offscreen targets driven by some other pass, not the sprite renderer.
+ */
+export declare function createRenderTexture2D(engine: EngineContext, width: number, height: number, options?: RenderTexture2DOptions): Texture2D;
+
 /** Create a ribbon from an array of parallel Vec3 paths. Caller must assign material. */
 export declare function createRibbon(engine: EngineContext, options: RibbonOptions): Mesh;
 
-/** Create an empty scene context bound to the given engine. */
-export declare function createSceneContext(engine: EngineContext, options?: SceneContextOptions): SceneContext;
+export declare function createRotationGizmo(engine: EngineContext, layer: UtilityLayer, options?: RotationGizmoOptions): RotationGizmo;
+
+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
+ *  is built against the surface's format, MSAA configuration, and swapchain RT — the
+ *  scene is permanently bound to that surface. Pass `engine` directly (since
+ *  `EngineContext extends SurfaceContext`) for the common single-canvas case, or pass
+ *  an auxiliary surface created via `createSurface`. */
+export declare function createSceneContext(surface: SurfaceContext, options?: SceneContextOptions): SceneContext;
 
 /** Create a ShaderMaterial from WGSL sources and declarations, validating
  *  attributes, uniforms, samplers, and defines.
@@ -1193,6 +1833,22 @@ export declare function createSceneContext(engine: EngineContext, options?: Scen
  *  @returns The constructed `ShaderMaterial`. */
 export declare function createShaderMaterial(options: ShaderMaterialOptions): ShaderMaterial;
 
+/**
+ * Create a no-colour view over a ShaderMaterial source, used by the shadow caster pass.
+ *
+ * Unlike standard/PBR/node, a ShaderMaterial needs no feature flag to drop its colour output: the shader
+ * pipeline already omits the fragment stage when the render target has no colour attachment (the depth-only
+ * shadow map). The view exists purely so the caster gets its OWN renderable + system UBO (written with the
+ * shadow camera's view-projection) instead of clobbering the source material's main-pass UBO.
+ */
+export declare function createShaderNoColorMaterialView(source: ShaderMaterial): MaterialView;
+
+/** Wrap a ShaderMaterial as a normal-buffer view. The returned view renders the
+ *  source's geometry (instancing/displacement intact) but writes the geometric
+ *  normal instead of the material's colour. Idempotent-friendly: create one per
+ *  source and reuse it. */
+export declare function createShaderNormalMaterialView(source: ShaderMaterial, config?: ShaderNormalViewConfig): MaterialView;
+
 /** Create a 1×1 solid-color `Texture2D` from straight RGBA components in [0, 1].
  *  @param engine - Engine context.
  *  @param r - Red channel (0–1).
@@ -1241,7 +1897,11 @@ export declare function createSpriteAnimationManager(options?: SpriteAnimationMa
  * Pack `sources` into a single `SpriteAtlas`. Shelf-packs in input order: each
  * frame is placed left-to-right on the current shelf, wrapping to a new shelf
  * (row) when it would overflow `maxWidthPx`. The texture is sized exactly to the
- * packed content.
+ * packed content unless `options.capacityPx` is supplied to reserve headroom for
+ * later `appendSpriteAtlasFrames` calls.
+ *
+ * Pass `sources: []` together with `options.capacityPx` to create an empty atlas
+ * sized for future appends.
  */
 export declare function createSpriteAtlasFromFrames(engine: EngineContext, sources: readonly SpriteAtlasFrameSource[], options?: SpriteAtlasPackOptions): SpriteAtlas;
 
@@ -1258,8 +1918,11 @@ export declare function createSpriteAtlasFromFrames(engine: EngineContext, sourc
  */
 export declare function createSpriteFrameAnimation(target: SpriteAnimationTarget, from: number, to: number, loop: boolean, delayMs: number, options?: PlaySpriteAnimationOptions): SpriteFrameAnimation;
 
-/** Create a `SpriteRenderer` for `engine`, pre-warming pipelines for the layers' blend modes. */
-export declare function createSpriteRenderer(engine: EngineContext, opts: SpriteRendererOptions): SpriteRenderer;
+/** Create a `SpriteRenderer` for `surface`, pre-warming pipelines for the layers' blend
+ *  modes. Pass the engine directly for the common single-canvas case (since
+ *  `EngineContext extends SurfaceContext`); pass an auxiliary surface created via
+ *  `createSurface` for multi-canvas. */
+export declare function createSpriteRenderer(surface: SurfaceContext, opts: SpriteRendererOptions): SpriteRenderer;
 
 /** Create StandardMaterial with Babylon defaults. */
 export declare function createStandardMaterial(): StandardMaterialProps;
@@ -1268,6 +1931,32 @@ export declare function createStandardMaterial(): StandardMaterialProps;
  *  The view references the source; material state is never copied. */
 export declare function createStandardNoColorMaterialView(source: StandardMaterialProps): MaterialView;
 
+/**
+ * Create an auxiliary rendering surface bound to an existing engine. The surface
+ * configures its own `GPUCanvasContext` against `engine._device` and is appended to
+ * `engine.surfaces`. GPU resources (textures, buffers, pipelines) are shared across
+ * all surfaces of the same engine because they're device-scoped — render to multiple
+ * canvases by creating additional surfaces and binding scenes / renderers to each.
+ *
+ * The engine's own primary surface (`engine.surfaces[0] === engine`) is created
+ * automatically by `createEngine(canvas)`; use `createSurface` only for additional
+ * canvases beyond that one.
+ *
+ * Accepts either a DOM canvas (main thread) or an `OffscreenCanvas` (e.g. transferred
+ * to a Web Worker via `transferControlToOffscreen()`).
+ */
+export declare function createSurface(engine: EngineContext, canvas: RenderCanvas, options?: SurfaceOptions): SurfaceContext;
+
+/** Create a TextData bound to `storage`. If `runs` is omitted the TextData starts empty;
+ *  runs can be appended later via `updateTextData({ update: "addRun", … })`. */
+export declare function createTextData(storage: GlyphStorage, runs?: readonly GlyphRun[]): TextData;
+
+export declare function createTextLayer(data: TextData, options?: TextLayerOptions): TextLayer;
+
+export declare function createTextRenderable(data: TextData, options?: TextRenderableOptions): TextRenderable;
+
+export declare function createTextRenderer(surface: SurfaceContext, opts: TextRendererOptions): TextRenderer;
+
 /**
  * Create a `Texture2D` from a tightly-packed RGBA8 byte buffer.
  *
@@ -1282,6 +1971,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;
@@ -1306,6 +2007,14 @@ export declare function createUniformEffectRenderTask(config: UniformEffectRende
  */
 export declare function createUniformEffectWrapper(engine: EngineContext, options: UniformEffectWrapperOptions): UniformEffectWrapper;
 
+/** Create a utility layer attached to the given engine + main scene.
+ *  The returned `scene` shares the main scene's camera so view + projection
+ *  remain in sync without manual mirroring.  The utility scene renders with a
+ *  fresh-cleared depth buffer (so its gizmos appear on top of the main scene)
+ *  while keeping NORMAL intra-layer depth testing — solid gizmo bodies (e.g.
+ *  the camera-gizmo box + cylinders) occlude their own back faces correctly. */
+export declare function createUtilityLayer(engine: EngineContext, mainScene: SceneContext, options?: UtilityLayerOptions): UtilityLayer;
+
 /** Cross-fades from `fromGroup` to `toGroup`, fading the first to weight 0 and the second to `options.toWeight` (default 1). */
 export declare function crossFadeAnimationGroups(manager: AnimationManager, fromGroup: AnimationGroup, toGroup: AnimationGroup, options: CrossFadeAnimationGroupsOptions): void;
 
@@ -1354,6 +2063,39 @@ 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;
+}
+
+/** Approximate a cubic Bézier with two quadratics using the "3/4 rule" (matches Slug reference).
+ *  Exposed as a public helper so callers that ingest cubic outlines from their own font sources
+ *  (e.g. DirectWrite, FreeType) can convert into the quadratic-only format `GlyphCurves` expects. */
+export declare function cubicToQuadratics(p0x: number, p0y: number, c1x: number, c1y: number, c2x: number, c2y: number, p1x: number, p1y: number): [QuadCurve, QuadCurve];
+
+/** Identifier for a curve set (a font's glyph-curves map). Strings let callers use a
+ *  human-readable key (e.g. the font face name) for easy debugging. */
+export declare type CurveSetId = string;
+
 /** 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). */
@@ -1361,6 +2103,26 @@ export declare interface CustomShaderTexture {
     readonly texture: Texture2D;
 }
 
+/**
+ * CreateCylinder — matches Babylon.js MeshBuilder.CreateCylinder default options.
+ *
+ * Supports cylinders, cones (diameterTop=0), truncated cones, and prisms
+ * (low tessellation). Options are a subset of Babylon's MeshBuilder that
+ * covers the typical procedural use-case. Advanced options — `arc`,
+ * `enclose`, `hasRings`, `faceColors`, `faceUV`, `cap != CAP_ALL` — are
+ * intentionally omitted to keep the API small; the default behavior (full
+ * 360°, single ring, CAP_ALL) matches Babylon exactly.
+ *
+ * Index order and normal computation are ported verbatim from
+ * `@babylonjs/core/Meshes/Builders/cylinderBuilder.js` to guarantee parity.
+ */
+export declare interface CylinderData {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+
 /** Options for `createCylinderData`. Subset of Babylon's CreateCylinder. */
 export declare interface CylinderOptions {
     height?: number;
@@ -1371,6 +2133,69 @@ export declare interface CylinderOptions {
     subdivisions?: number;
 }
 
+/** 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 {
+    readonly [defaultTextDataBrand]: true;
+    /** Pixel-space width of the laid-out run (max line width). */
+    readonly width: number;
+    /** Pixel-space height of the laid-out run (lines × line-height). */
+    readonly height: number;
+
+declare const defaultTextDataBrand: unique symbol;
+
+/** Quality of the depth-of-field blur. Models BJS `ThinDepthOfFieldEffectBlurLevel`. */
+export declare enum DepthOfFieldBlurLevel {
+    /** Subtle blur — 1 blur level, kernel 15. */
+    Low = 0,
+    /** Medium blur — 2 blur levels, kernel 31. */
+    Medium = 1,
+    /** Large blur — 3 blur levels, kernel 51. */
+    High = 2
+}
+
+/** A composite depth-of-field post-process task: circle-of-confusion → CoC-weighted blur pyramid → merge. */
+export declare interface DepthOfFieldPostProcessTask extends Task, PostProcessTaskSettings {
+    readonly name: string;
+    sourceTexture: RenderTarget;
+    targetTexture: RenderTarget | null;
+    outputTexture: RenderTarget;
+    lensSize: number;
+    fStop: number;
+    focusDistance: number;
+    focalLength: number;
+    /** Recompute and upload the uniforms of every sub-pass (CoC, blurs, merge). */
+    updateUniforms(): void;
+}
+
+/**
+ * Configuration for `createDepthOfFieldPostProcessTask`.
+ *
+ * Models Babylon.js's `FrameGraphDepthOfFieldTask` + `ThinDepthOfFieldEffect`:
+ * a circle-of-confusion pass feeds a stack of CoC-weighted separable blurs,
+ * which are merged back over the sharp image for a physically-plausible
+ * depth-of-field effect.
+ */
+export declare interface DepthOfFieldPostProcessTaskConfig extends PostProcessTaskSettings {
+    /** Depth texture. With `depthNotNormalized` it stores camera-space (view)
+     *  depth; otherwise normalized [0,1] view depth. */
+    depthTexture: RenderTarget;
+    /** Camera used to read minZ/maxZ when the depth is normalized. */
+    camera: Camera;
+    /** Max lens size in scene units / 1000. Default 50. */
+    lensSize?: number;
+    /** F-Stop of the camera. Default 1.4. */
+    fStop?: number;
+    /** Distance from the camera to focus on, in scene units / 1000. Default 2000. */
+    focusDistance?: number;
+    /** Focal length of the camera in scene units / 1000. Default 50. */
+    focalLength?: number;
+    /** Blur quality. Default {@link DepthOfFieldBlurLevel.Low}. */
+    blurLevel?: DepthOfFieldBlurLevel;
+    /** When true the depth texture stores camera-space depth (0..maxZ). */
+    depthNotNormalized?: boolean;
+}
+
 export declare interface DirectionalLight extends LightBase {
     readonly lightType: "directional";
     direction: ObservableVec3;
@@ -1388,23 +2213,41 @@ export declare interface DiscOptions {
     arc?: number;
 }
 
+/** Dispose the gizmo: remove meshes, unregister pointer-drag, drop materials. */
+export declare function disposeAxisDragGizmo(gizmo: AxisDragGizmo, layer: UtilityLayer): void;
+
+export declare function disposeAxisScaleGizmo(gizmo: AxisScaleGizmo, layer: UtilityLayer): void;
+
+export declare function disposeBoundingBoxGizmo(gizmo: BoundingBoxGizmo, layer: UtilityLayer): void;
+
+export declare function disposeCameraGizmo(gizmo: CameraGizmo, layer: UtilityLayer): void;
+
 /** Frees the WASM memory backing a solid. The solid must not be used afterwards. */
 export declare function disposeCsg2(solid: Csg2Solid): void;
 
+/** Release the per-block GPU resources AND the underlying `GlyphStorage` owned by `data`. */
+export declare function disposeDefaultTextData(data: DefaultTextData): void;
+
 /** Unregister and free all GPU resources owned by the renderer. */
 export declare function disposeEffectRenderer(er: EffectRenderer): void;
 
 /** Destroy the uniform buffers and clear the cached pipelines, bind groups, and slots owned by the effect wrapper. */
 export declare function disposeEffectWrapper(wrapper: EffectWrapper): void;
 
-/** Release all engine-owned GPU resources (device + swapchain). Rendering contexts
- *  own their own GPU resources (frame graphs, render targets) and dispose them
- *  separately. */
+/** Release all engine-owned GPU resources (device + every attached surface's swapchain
+ *  context). Rendering contexts own their own GPU resources (frame graphs, render
+ *  targets) and dispose them separately. */
 export declare function disposeEngine(engine: EngineContext): void;
 
 /** Unregister and dispose all GPU resources owned by the standalone frame graph. */
 export declare function disposeFrameGraphContext(ctx: FrameGraphContext): void;
 
+/** Release every GPU atlas owned by `storage`. Idempotent. The caller is responsible for
+ *  ensuring no `TextData` is still drawing from this storage. */
+export declare function disposeGlyphStorage(storage: GlyphStorage): void;
+
+export declare function disposeLightGizmo(gizmo: LightGizmo, layer: UtilityLayer): void;
+
 /**
  * Removes and releases all bodies, then releases the native world. Call once when tearing down physics.
  * @param world - The physics world to dispose.
@@ -1414,6 +2257,16 @@ export declare function disposePhysics(world: PhysicsWorld): void;
 /** Dispose GPU resources owned by this picker. */
 export declare function disposePicker(picker: GpuPicker): void;
 
+export declare function disposePlaneDragGizmo(gizmo: PlaneDragGizmo, layer: UtilityLayer): void;
+
+export declare function disposePlaneRotationGizmo(gizmo: PlaneRotationGizmo, layer: UtilityLayer): void;
+
+export declare function disposePositionGizmo(gizmo: PositionGizmo, layer: UtilityLayer): void;
+
+export declare function disposeRotationGizmo(gizmo: RotationGizmo, layer: UtilityLayer): void;
+
+export declare function disposeScaleGizmo(gizmo: ScaleGizmo, layer: UtilityLayer): void;
+
 /** Release all GPU resources owned by this scene. */
 export declare function disposeScene(scene: SceneContext): void;
 
@@ -1432,9 +2285,29 @@ export declare function disposeSpriteAnimationBinding(binding: SpriteAnimationBi
  */
 export declare function disposeSpriteRenderer(sr: SpriteRenderer): void;
 
+/** Remove and unconfigure an auxiliary surface from its engine. Rendering contexts
+ *  registered on this surface are dropped from its list but not disposed — call their
+ *  own disposers (e.g. `disposeScene`) separately.
+ *
+ *  Throws if called on the engine's primary surface (`surface === engine`); use
+ *  `disposeEngine` to tear down the engine and all its surfaces. */
+export declare function disposeSurface(surface: SurfaceContext): void;
+
+/** Release per-block GPU resources owned by `data`. Does NOT dispose the bound
+ *  `GlyphStorage` — caller owns its lifetime and must dispose it separately via
+ *  `disposeGlyphStorage` once no `TextData` references it. */
+export declare function disposeTextData(data: TextData): void;
+
+export declare function disposeTextRenderable(renderable: TextRenderable): void;
+
+export declare function disposeTextRenderer(tr: TextRenderer): void;
+
 /** Destroy the uniform buffer and clear cached GPU objects owned by the uniform effect wrapper. */
 export declare function disposeUniformEffectWrapper(wrapper: UniformEffectWrapper): void;
 
+/** Dispose the utility layer's underlying scene. Idempotent. */
+export declare function disposeUtilityLayer(utility: UtilityLayer): void;
+
 /**
  * A per-pass draw binding produced by `Renderable.bind(engine, target)`.
  *
@@ -1549,6 +2422,38 @@ export declare function enableAnimationBlending(manager: AnimationManager): void
  */
 export declare function enableDetailedPicking(picker: GpuPicker): void;
 
+/**
+ * Opt a Havok world into multi-region floating-origin simulation (Large World Rendering).
+ *
+ * Loads the floating-origin runtime on demand (`physics/havok-floating-origin.ts`) so worlds that
+ * never call this — i.e. ordinary near-origin physics scenes — never pull that code into their
+ * bundle. Once enabled, bodies far apart in world space are simulated in separate regions (each
+ * within `floatingOriginWorldRadius` of its origin) so the float32 Havok solver keeps full
+ * precision. Node transforms remain true world coordinates; eye-relative rendering is handled
+ * independently by the floating-origin render path.
+ *
+ * Must be called **before** creating any bodies in the world. Pair it with an engine created with
+ * `useFloatingOrigin: true` so rendering and physics share the same far-from-origin handling.
+ * @param world - The physics world to enable floating origin on.
+ * @param floatingOriginWorldRadius - Region capture radius in metres (default 100000, matching Babylon.js).
+ */
+export declare function enableHavokFloatingOrigin(world: PhysicsWorld, floatingOriginWorldRadius?: number): Promise<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 +2463,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()`.
@@ -1569,43 +2478,68 @@ export declare function enableThinInstanceGpuCulling(mesh: Mesh, enabled?: boole
 /** CPU helper matching BJS `GaussianSplattingGpuPickingMaterialPlugin.EncodeIdToColor`. */
 export declare function encodeIdToColor(id: number): [number, number, number];
 
-/** Handle to the WebGPU engine — pure state, no attached methods. */
-export declare interface EngineContext {
-    readonly canvas: RenderCanvas;
-    readonly msaaSamples: number;
-    /** Preferred GPU texture format for the swapchain. Use as the `colorFormat`
-     *  for offscreen RTs that are sampled by main-pass materials. */
-    readonly format: GPUTextureFormat;
-    /** Number of GPU draw calls in the last rendered frame. */
+/**
+ * Handle to the WebGPU engine — pure state, no attached methods.
+ *
+ * The engine owns the `GPUDevice` and all device-scoped GPU resources (textures, buffers,
+ * pipelines, bind groups). It also **is itself a {@link SurfaceContext}** bound to the
+ * canvas passed into `createEngine` — the primary surface. Additional canvases can be
+ * attached via `createSurface(engine, canvas, ...)`; GPU resources are shared across all
+ * surfaces because they're device-scoped, while each surface owns its own swapchain
+ * context.
+ */
+export declare interface EngineContext extends SurfaceContext {
+    /** Rendering surfaces attached to this engine, in registration order. Index 0 is
+     *  the engine itself (the primary surface) — the tuple type guarantees at least
+     *  one entry so `engine.surfaces[0]` is always defined. Use
+     *  `createSurface(engine, canvas, ...)` to append more. */
+    readonly surfaces: readonly [SurfaceContext, ...SurfaceContext[]];
    /** Number of GPU draw calls in the last rendered frame, summed across all surfaces. */
     drawCallCount: number;
-    /** 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);
-     *  the default `Infinity` is unclamped (full devicePixelRatio). Mutable at runtime — set
-     *  before the next `resizeEngine` to take effect (mirrors `setHardwareScalingRatio`). */
-    maxDevicePixelRatio: 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;
 
 /**
- * Options for `createEngine`.
- * - `msaaSamples`: number of MSAA samples to use for the main render pass.
- *   WebGPU only permits `1` (no MSAA) or `4` (4x MSAA) per the spec
- *   (2x is not a valid WebGPU sample count). Defaults to `4`.
+ * Options for `createEngine`. Per-surface options for the primary surface (the canvas
+ * passed to `createEngine`) come from {@link SurfaceOptions} and are passed alongside
+ * the engine options as a single union: `createEngine(canvas, opts: EngineOptions & SurfaceOptions)`.
  */
-export declare interface EngineOptions {
-    msaaSamples?: 1 | 4;
+export declare interface EngineOptions extends SurfaceOptions {
     /**
-     * WebGPU canvas alpha mode. Use "premultiplied" to enable canvas transparency (clear color
-     * with `alpha < 1` will let HTML content underneath show through). Defaults to "opaque".
+     * Extra WebGPU device limits to request when calling `adapter.requestDevice()`.
+     * Use to raise per-device caps such as `maxColorAttachmentBytesPerSample` (default 32),
+     * which is required when rendering into many MRT attachments. Caller is responsible for
+     * staying within the adapter's reported limits.
      */
-    alphaMode?: GPUCanvasAlphaMode;
+    requiredLimits?: Record<string, GPUSize64 | undefined>;
     /**
-     * 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) —
-     * useful on high-DPI/iOS devices where `devicePixelRatio` is ~3. Defaults to unclamped
-     * (full devicePixelRatio). Equivalent to Babylon.js `setHardwareScalingRatio`.
+     * Enable Float64 intermediate precision for world matrix computations. Defaults to false.
      */
-    maxDevicePixelRatio?: number;
+    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;
 }
 
 /** GPU-resident environment textures. */
@@ -1652,6 +2586,11 @@ declare interface EulerProxy {
     set(x: number, y: number, z: number): void;
 }
 
+/** Extract outlines for the requested glyph ids and add them to `target`.
+ *  Skips ids already present in `target`. Glyphs with no outline are silently skipped.
+ *  Mutates `target` directly — no allocation when no new glyphs appear. */
+export declare function extractGlyphCurves(font: Font, glyphIds: ReadonlySet<number>, target: Map<number, GlyphCurves>): void;
+
 /** A post-process task that keeps only pixels whose luminance exceeds `threshold` and zeroes the rest. */
 export declare interface ExtractHighlightsPostProcessTask extends PostProcessTask {
     threshold: number;
@@ -1700,6 +2639,17 @@ export declare function findRandomPointAroundCircle(plugin: NavigationPlugin, po
 /** Mark thin instance data dirty after direct array manipulation. */
 export declare function flushThinInstances(mesh: Mesh): void;
 
+/**
+ * Smoothly animate a {@link GeospatialCamera} to new yaw/pitch/radius/centre over
+ * `durationMs`, driven by the scene's render loop. Yaw takes the shortest angular
+ * path; the centre follows a great-circle (with an optional parabolic hop).
+ *
+ * The returned promise resolves when the flight completes; it also resolves early
+ * if the flight is interrupted (by user input through `attachGeospatialControls`,
+ * or by a subsequent `flyGeospatialCameraToAsync` call). Only one flight runs at a time.
+ */
+export declare function flyGeospatialCameraToAsync(camera: GeospatialCamera, scene: SceneContext, options: GeospatialFlyOptions): Promise<void>;
+
 /** Fog configuration — plain data. */
 export declare interface FogConfig {
     mode: 0 | 1 | 2 | 3;
@@ -1709,6 +2659,11 @@ export declare interface FogConfig {
     color: [number, number, number];
 }
 
+export declare interface Font {
+    readonly [fontBrand]: true;
+
+declare const fontBrand: unique symbol;
+
 /** The frame graph — an ordered list of tasks. */
 export declare interface FrameGraph {
    /** Build (or rebuild) every task in execute order. */
     build(): void;
@@ -1721,7 +2676,8 @@ export declare interface FrameGraph {
    /** Build (or rebuild) every task in e
 /** A scene-less rendering context driven directly by a FrameGraph. */
 export declare interface FrameGraphContext extends RenderingContext_2 {
     readonly name: string;
-    readonly engine: EngineContext;
+    /** Surface this context renders into. */
+    readonly surface: SurfaceContext;
     readonly frameGraph: FrameGraph;
     clearColor: GPUColorDict;
 }
@@ -1779,6 +2735,251 @@ export declare interface GaussianSplattingMesh extends SceneNode {
    /** Numbe
     updateData(splatBuffer: ArrayBuffer): void;
 }
 
+export declare interface GeometryRendererTask extends Task {
+    readonly name: string;
+    /** The optional target texture the task wrote the real (lit) color into.
+     *  Equal to {@link GeometryRendererTaskConfig.targetTexture} when the
+     *  config provided one, otherwise `undefined`. */
+    readonly outputTexture: RenderTarget | undefined;
+    /** Single-attachment depth `RenderTarget` exposing the pass's depth/stencil
+     *  attachment. Downstream tasks (e.g. a `RenderTask` running after the
+     *  geometry pass) can consume this as a depth input to reuse the values
+     *  written here. When the caller supplied an external `depthTexture` in the
+     *  config, this returns that same RT; otherwise it wraps the MRT-owned
+     *  depth and is populated post-`record()`. */
+    readonly geometryDepthTexture: RenderTarget;
+    /** Per-type accessors. `null` when that type was not requested. Each value
+     *  is a single-attachment `RenderTarget` whose color slot aliases the
+     *  matching MRT attachment, so downstream tasks (copy-to-texture, etc.)
+     *  can consume it like an ordinary RT. */
+    readonly geometryIrradianceTexture: RenderTarget | null;
+    readonly geometryWorldPositionTexture: RenderTarget | null;
+    readonly geometryLocalPositionTexture: RenderTarget | null;
+    readonly geometryReflectivityTexture: RenderTarget | null;
+    readonly geometryViewDepthTexture: RenderTarget | null;
+    readonly geometryNormalizedViewDepthTexture: RenderTarget | null;
+    readonly geometryScreenspaceDepthTexture: RenderTarget | null;
+    readonly geometryViewNormalTexture: RenderTarget | null;
+    readonly geometryWorldNormalTexture: RenderTarget | null;
+    readonly geometryAlbedoTexture: RenderTarget | null;
+    readonly geometryLinearVelocityTexture: RenderTarget | null;
+    /** Skip a mesh from the velocity attachment's previous-world tracking. */
+    excludeFromVelocity(mesh: Mesh): void;
+    /** Re-include a mesh in velocity tracking. */
+    includeInVelocity(mesh: Mesh): void;
+}
+
+export declare interface GeometryRendererTaskConfig {
+    name?: string;
+    /** Caster meshes. When omitted, defaults to `scene.meshes`. */
+    meshes?: readonly Mesh[];
+    /** Per-pass camera override. Defaults to `scene.camera`. */
+    camera?: Camera | null;
+    /** Render-target size. Defaults to the scene's `surface`. */
+    size?: SurfaceContext | {
+        width: number;
+        height: number;
+    };
+    /** MSAA sample count. Defaults to 1. */
+    samples?: 1 | 4;
+    /** Externally-owned depth attachment. When omitted, the task creates its
+     *  own `depth32float` depth texture sized to match the color attachments. */
+    depthTexture?: RenderTarget | null;
+    /** Ordered list of MRT attachments (1..8). The array index becomes the
+     *  fragment shader's `@location(i)` and the render-pass color attachment slot. */
+    readonly textureDescriptions: readonly GeometryRendererTextureDescription[];
+    /** Flip culling direction. Default false. */
+    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
+     *  pixel size as the geometry MRT (size: `<surface>` with samples matching).
+     *  When omitted, no real-color attachment is added to the pass.
+     *
+     *  The target attachment uses `loadOp: "load"` (matches BJS), so the
+     *  caller must initialize the target's contents (e.g. via a clear pass)
+     *  before the geometry task runs — unless {@link targetTextureClearColor}
+     *  is provided. */
+    targetTexture?: RenderTarget;
+    /** When set together with {@link targetTexture}, the target attachment
+     *  uses `loadOp: "clear"` with this color at the start of the geometry
+     *  pass. Convenient for demo / standalone use where no prior task has
+     *  initialized the target's contents. */
+    targetTextureClearColor?: GPUColor;
+}
+
+/** One MRT color attachment requested by the user. */
+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. */
+    readonly format?: GPUTextureFormat;
+    /** Per-attachment clear-value override. Defaults to
+     *  {@link 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;
+}
+
+/**
+ * Geometry renderer texture types.
+ *
+ * Each enum value corresponds to a single geometry attachment that
+ * {@link createGeometryRendererTask} can write to. The companion
+ * {@link GEOMETRY_TEXTURE_DESCRIPTIONS} table provides the default
+ * per-type WebGPU format and the clear behaviour at the start of a
+ * geometry pass.
+ *
+ * The enum is intentionally a subset of Babylon.js'
+ * `MaterialHelperGeometryRendering.GeometryTextureDescriptions`. The
+ * following BJS types are excluded by design:
+ *   - `ALBEDO_SQRT`           — we only expose `ALBEDO`.
+ *   - `VELOCITY` (vec2 SS)    — we only expose `LINEAR_VELOCITY` (vec3 WS).
+ *   - `IRRADIANCE_LEGACY`     — we only expose `IRRADIANCE`.
+ *   - `COLOR`                 — handled separately via the geometry task's
+ *                               optional `targetTexture` color attachment
+ *                               (BJS `PREPASS_COLOR_INDEX`).
+ *
+ * Module is lazy-loaded by the geometry view and the geometry task only;
+ * existing scenes never import it.
+ */
+/** Identifies a single geometry texture supported by `createGeometryRendererTask`. */
+export declare enum GeometryTextureType {
+    /** Half-float RGBA — diffuse irradiance accumulated at the surface. */
+    IRRADIANCE = 0,
+    /** Half-float RGBA — world-space position. */
+    WORLD_POSITION = 1,
+    /** Half-float RGBA — object-local position (before world transform). */
+    LOCAL_POSITION = 2,
+    /** Unorm8 RGBA — material reflectivity (rgb) + roughness (a). */
+    REFLECTIVITY = 3,
+    /** Float R — linear view-space depth (camera-far at the far plane). Cleared to camera far. */
+    VIEW_DEPTH = 4,
+    /** Half-float R — view-space depth normalized to [0,1] (1 at the far plane). */
+    NORMALIZED_VIEW_DEPTH = 5,
+    /** Half-float R — clip-space depth in [0,1] (matches GPU depth buffer post-projection). */
+    SCREENSPACE_DEPTH = 6,
+    /** Half-float RGBA — view-space surface normal. */
+    VIEW_NORMAL = 7,
+    /** Half-float RGBA — world-space surface normal. */
+    WORLD_NORMAL = 8,
+    /** Unorm8 RGBA — surface albedo (diffuse colour, no lighting). */
+    ALBEDO = 9,
+    /** Half-float RGBA — per-pixel linear world-space velocity in units / frame. */
+    LINEAR_VELOCITY = 10
+}
+
+/** Camera that orbits a spherical planet centred at the world origin (Babylon.js `GeospatialCamera`).
+ *
+ *  Orientation is fully described by `center` (the anchored point on the globe in
+ *  ECEF coordinates), `yaw`, `pitch`, and `radius`. Setting any of these
+ *  recomputes the derived `position` / `upVector` and the view matrix.
+ *
+ *  Pure state — behaviour is provided by standalone functions
+ *  ({@link setGeospatialOrientation}, `attachGeospatialControls`,
+ *  `flyGeospatialCameraToAsync`). The camera never references the scene. */
+export declare interface GeospatialCamera extends Camera, IWorldMatrixProvider, IParentable {
+    /** The anchored point on the globe (ECEF). Assigning re-orbits around the new centre. */
+    center: Vec3;
+    /** Yaw about the geocentric up axis. Wrapped to [-π, π). 0 = north, π/2 = east. */
+    yaw: number;
+    /** Pitch from looking straight down (0) to the horizon (π/2). Wrapped to [-π, π). */
+    pitch: number;
+    /** Distance from the camera to its centre point (distinct from `planetRadius`). */
+    radius: number;
+    /** Limits governing yaw/pitch/radius clamping. Mutable; clamping applies on the next orientation change. */
+    limits: GeospatialLimits;
+    /** Derived world-space eye position. Read-only — driven by center/yaw/pitch/radius. */
+    readonly position: Vec3;
+    /** Derived camera up vector. Read-only. */
+    readonly upVector: Vec3;
+    fov: number;
+    nearPlane: number;
+    farPlane: number;
+    viewport?: NormalizedViewport;
+    children: SceneNode[];
+    parent: IWorldMatrixProvider | null;
+    readonly worldMatrix: Mat4;
+    readonly worldMatrixVersion: number;
+
+/** Options for {@link createGeospatialCamera}. */
+export declare interface GeospatialCameraOptions {
+    /** Radius of the planet being orbited. */
+    planetRadius: number;
+}
+
+/** Options for {@link attachGeospatialControls}. */
+export declare interface GeospatialControlOptions {
+    /** When true, zooming moves toward the point under the cursor; otherwise along the look vector. Default true. */
+    zoomToCursor?: boolean;
+    /** Enable simple sphere collision so the camera cannot dip below the surface. Default false. */
+    checkCollisions?: boolean;
+}
+
+/** Options for {@link flyGeospatialCameraToAsync}. Omitted target fields keep their current value. */
+export declare interface GeospatialFlyOptions {
+    /** Target yaw (radians). Shortest angular path is taken. */
+    yaw?: number;
+    /** Target pitch (radians). */
+    pitch?: number;
+    /** Target radius. */
+    radius?: number;
+    /** Target centre (ECEF). Animated along a great-circle (slerp). */
+    center?: Vec3;
+    /** Flight duration in ms. Default 1000. */
+    durationMs?: number;
+    /** Parabolic "hop" height scale for the centre animation (0 = none). */
+    centerHopScale?: number;
+}
+
+/** Pitch/yaw/radius bounds for a {@link GeospatialCamera}.
+ *
+ *  Pure state, mirroring Babylon.js `GeospatialLimits`. Behaviour
+ *  ({@link getEffectivePitchMax}, {@link clampZoomDistance}) lives in
+ *  standalone functions so unused limit logic is tree-shaken.
+ *
+ *  All angles are in radians. Pitch is measured from "looking straight down at
+ *  the planet centre" (0) to "looking at the horizon" (π/2). */
+export declare interface GeospatialLimits {
+    /** Radius of the planet — used for altitude/radius conversions. */
+    planetRadius: number;
+    /** Minimum camera distance from its centre point (closest zoom). Default 10. */
+    radiusMin: number;
+    /** Maximum camera distance from its centre point (farthest zoom). Default `planetRadius * 4`. */
+    radiusMax: number;
+    /** Minimum pitch angle (≈0 = looking straight down at the planet). */
+    pitchMin: number;
+    /** Maximum pitch angle (π/2 = looking at the horizon). */
+    pitchMax: number;
+    /**
+     * Controls how pitch is disabled as the camera zooms out.
+     * `x` = radius scale at which full pitch is allowed (e.g. 2 ⇒ 2·planetRadius),
+     * `y` = radius scale at which pitch is fully disabled (forced to `pitchMin`).
+     * `null` disables this feature (full pitch at every radius).
+     */
+    pitchDisabledRadiusScale: {
+        x: number;
+        y: number;
+    } | null;
+    /** Minimum yaw angle (rotation about the geocentric up axis). Default -Infinity. */
+    yawMin: number;
+    /** Maximum yaw angle. Default +Infinity. */
+    yawMax: number;
+}
+
+/** A delta to apply via {@link setGeospatialOrientation}; omitted fields keep their current value. */
+export declare interface GeospatialOrientation {
+    /** Yaw in radians (0 = north, π/2 = east). */
+    yaw?: number;
+    /** Pitch in radians (0 = looking straight down at the planet centre, π/2 = horizon). */
+    pitch?: number;
+    /** Distance from the camera to its centre point. */
+    radius?: number;
+    /** Anchor point on the globe (ECEF) that the camera orbits. */
+    center?: Vec3;
+}
+
 /** Get the current world position of an agent. */
 export declare function getAgentPosition(crowd: NavCrowd, index: number): Vec3;
 
@@ -1805,18 +3006,41 @@ 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;
 
+/**
+ * Computes the effective maximum pitch for a given camera radius. When
+ * `pitchDisabledRadiusScale` is set, pitch is interpolated from `pitchMax` down
+ * to `pitchMin` as the camera zooms out from `x·planetRadius` to `y·planetRadius`
+ * (so a fully zoomed-out camera looks straight down).
+ */
+export declare function getEffectivePitchMax(limits: GeospatialLimits, currentRadius: 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;
 
 /** Get the current seed used by Recast's randomized queries. */
 export declare function getNavigationRandomSeed(plugin: NavigationPlugin): number;
 
+/** Get or create a deduplicated sampler. Same config → same GPUSampler. */
+export declare function getOrCreateSampler(engine: EngineContext, desc?: GPUSamplerDescriptor): GPUSampler;
+
+/**
+ * Get a body's current linear velocity (m/s).
+ */
+export declare function getPhysicsBodyLinearVelocity(world: PhysicsWorld, body: PhysicsBody): Vec3;
+
 /**
- * Returns the world's current gravity vector.
+ * Returns the world's current gravity vector, or a specific region's when `worldPosition` is given.
  * @param world - The physics world.
+ * @param worldPosition - Optional world position selecting the region to read; omit for the world-wide gravity.
  * @returns Gravity acceleration in m/s².
  */
-export declare function getPhysicsGravity(world: PhysicsWorld): Vec3;
+export declare function getPhysicsGravity(world: PhysicsWorld, worldPosition?: Vec3): Vec3;
 
 /**
  * Returns the world's fixed simulation timestep in seconds.
@@ -1865,12 +3089,39 @@ 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. */
 export declare function getViewProjectionMatrix(camera: Camera, aspectRatio: number): Mat4;
 
+declare interface GizmoMaterialSet {
+    colored: StandardMaterialProps;
+    hover: StandardMaterialProps;
+    disabled: StandardMaterialProps;
+}
+
+/** Tiny single-event observable used by gizmos/pointer-drag (no dependency on
+ *  BJS's Observable, no module-level allocations). */
+declare class GizmoObservable<T> {
+    private _subs;
+    add(cb: (arg: T) => void): () => void;
+    notify(arg: T): void;
+    clear(): void;
+}
+
 /** Everything the animation system needs, parsed from a glTF file. */
 export declare interface GltfAnimationData {
     readonly clips: readonly AnimationClip[];
@@ -1888,6 +3139,61 @@ export declare interface GltfAnimationData {
     readonly excludedNodeIndices: ReadonlySet<number>;
 }
 
+export declare type GlyphBounds = {
+    readonly xMin: number;
+    readonly yMin: number;
+    readonly xMax: number;
+    readonly yMax: number;
+};
+
+export declare type GlyphCurves = {
+    readonly glyphId: number;
+    readonly curves: readonly QuadCurve[];
+    readonly bounds: GlyphBounds;
+
+export declare type GlyphRun = {
+    /** Which curve set this run's glyph ids index into. */
+    readonly curveSet: CurveSetId;
+    readonly glyphs: readonly PlacedGlyph[];
+    /** Font-units → pixels scale used by the layout. */
+    readonly pixelsPerFontUnit: number;
+    /** Optional default color for every glyph in this run, as linear RGBA in [0,1]. A glyph's
+     *  own `PlacedGlyph.color` takes precedence over this. When omitted, glyphs default to
+     *  opaque white. The rendered alpha is additionally scaled by the whole-block opacity. */
+    readonly defaultColor?: readonly [number, number, number, number];
+};
+
+/** Opaque bundle of glyph outlines (organized by curve-set) and the GPU atlases packed
+ *  from them. Holds an arbitrary number of curve-sets — each curve-set gets its own atlas.
+ *  Shared by reference across any number of `TextData`s that need the same glyph catalog. */
+export declare interface GlyphStorage {
+    readonly [glyphStorageBrand]: true;
+
+/** Glyph storage: per-curve-set CPU outline catalog plus the GPU atlas packed from it.
+ *
+ *  Layered:
+ *    - `GlyphStorage` is the opaque public handle. Holds one or more curve-sets keyed by
+ *      `CurveSetId` (typically a font family name). Each curve-set owns its glyph
+ *      outlines plus the `SharedAtlas` packed from them.
+ *    - `SharedAtlas` is the CPU staging: two `rgba32float`-shaped `Float32Array`s holding
+ *      quadratic curve control points and per-band curve-index lists, both append-only.
+ *    - Atlas packing (`packAppendGlyph`) and spatial-band partitioning (`buildGlyphBands`)
+ *      live here as internal helpers — they implement the storage's invariants and are
+ *      not callable from outside the module.
+ *    - GPU creation/upload (`SharedAtlasGpu`, `ensureSharedAtlasGpu`) lives in
+ *      `_gpu/text-textures.ts`; the shared types are exported from here. GPU teardown
+ *      is performed inline in `disposeGlyphStorage` to avoid a circular import edge.
+ *
+ *  Lifetime is caller-owned (matches `Texture2D` semantics):
+ *    - `createGlyphStorage(initial?)` allocates a fresh storage, optionally seeded.
+ *    - `updateGlyphStorage(storage, curveSetId, curves)` adds glyphs (creating the
+ *      curve-set on demand). Glyph ids already present are skipped.
+ *    - `disposeGlyphStorage(storage)` releases every atlas. The caller must ensure no
+ *      `TextData` is still drawing from it — using a disposed storage is undefined
+ *      behavior. Idempotent.
+ */
+declare const glyphStorageBrand: unique symbol;
+
 /** Seek to a specific frame, apply the pose, and pause. */
 export declare function goToFrame(group: AnimationGroup, frame: number, engine?: EngineContext): void;
 
@@ -2042,6 +3348,13 @@ export declare function initializeCsg2Async(): Promise<void>;
 
 declare type InterpMode = 0 | 1 | 2;
 
+/** Force every registered scene's cached render + shadow bundles to RE-RECORD on the next frame, by bumping
+ *  each rendering context's `_renderableVersion` (the same signal a mesh add/remove or `resizeMeshGeometry`
+ *  emits). Use after an out-of-band GPU buffer REALLOCATION that the cached bundles can't otherwise notice —
+ *  e.g. growing a thin-instanced mesh's matrix buffer past its capacity (the bundle captured the old buffer
+ *  handle and would bind a freed buffer). A no-op-cheap version bump; the actual re-record happens lazily. */
+export declare function invalidateRenderBundles(engine: EngineContext): void;
+
 /** Any object that can be attached to a parent in the scene hierarchy.
  *  When parent is null, position/rotation/scaling are in world space. */
 export declare interface IParentable {
@@ -2075,6 +3388,26 @@ export declare function isBillboardSpriteHandleAlive(handle: BillboardSpriteHand
 /** Returns whether the manifold-3d runtime has finished loading and CSG2 is usable. */
 export declare function isCsg2Ready(): boolean;
 
+/** Returns true when the gizmo dispatcher for `canvas` has an ACTIVE drag in
+ *  progress (a collider was pressed and is being dragged).  Unlike
+ *  {@link isGizmoInteracting} this ignores mere hover, so camera controls can
+ *  abort an optimistically-started orbit once a gizmo drag (recognised a frame
+ *  after pointer-down, since picking is async) reclaims the gesture — without
+ *  aborting a legitimate orbit when the cursor merely passes over a gizmo. */
+export declare function isGizmoDragging(canvas: HTMLCanvasElement): boolean;
+
+/** Returns true when the gizmo dispatcher for `canvas` currently has a pointer
+ *  hovering one of its colliders or an active drag in progress.  Camera
+ *  controls consult this on pointer-down so orbiting doesn't start when the
+ *  press lands on (or drags) a gizmo. */
+export declare function isGizmoInteracting(canvas: HTMLCanvasElement): boolean;
+
+/** Returns true while the gizmo dispatcher for `canvas` has a pointer-down GPU
+ *  pick still in flight.  Camera controls consult this to DEFER (not yet apply)
+ *  an orbit until the pick resolves, so a press that lands on a gizmo never
+ *  produces a stray orbit even if the async pick is slow. */
+export declare function isGizmoPickPending(canvas: HTMLCanvasElement): boolean;
+
 /**
  * Returns `true` if the sprite referenced by `handle` is still present in its layer.
  * @param handle - Handle to test.
@@ -2106,6 +3439,19 @@ export declare interface LightBase extends IWorldMatrixProvider, IParentable {
     readonly worldMatrix: Mat4;
     readonly worldMatrixVersion: number;
 
+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). */
+    readonly root: SceneNode;
+    readonly material: StandardMaterialProps;
+    /** Currently attached light — set via `attachLightGizmoToLight`. */
+    attachedLight: LightBase | null;
+
+export declare interface LightGizmoOptions {
+    /** RGB color for the light gizmo body material.  Defaults to grey. */
+    color?: [number, number, number];
+}
+
 /** Options for `createLinearDepthMaterial()`. */
 export declare interface LinearDepthMaterialOptions {
     /** Camera near plane (defaults to 0.03 to match the source playground). */
@@ -2116,6 +3462,9 @@ export declare interface LinearDepthMaterialOptions {
     name?: string;
 }
 
+/** Convert linear [0,1] to sRGB [0,255] using the IEC 61966-2-1 transfer curve. */
+export declare function linearToSrgbByte(v: number): number;
+
 /** Options for `loadSpriteAtlas`. PR 1 supports the `gridSize` path only. */
 export declare interface LoadAtlasOptions {
     /** Grid cell size `[w, h]` in pixels. Required in PR 1. */
@@ -2190,6 +3539,9 @@ export declare function loadEnvironment(scene: SceneContext, url: string, option
     brdfUrl: string;
 }): Promise<EnvironmentTextures>;
 
+/** Load a TTF or OTF font from a URL. */
+export declare function loadFont(url: string): Promise<Font>;
+
 /**
  * Load a .glb or .gltf file, parse it, and upload mesh + material data to GPU.
  * Supports both binary GLB and separate .gltf + .bin + image files.
@@ -2228,6 +3580,14 @@ export declare function loadHdrEnvironment(scene: SceneContext, url: string, opt
  */
 export declare function loadKtxTexture2D(engine: EngineContext, baseUrl: string, suffixes: string[], opts?: Texture2DOptions): Promise<Texture2D>;
 
+/**
+ * Resolve a node-block emitter, including the geometry-renderer terminal
+ * (`GeometryTextureOutputBlock`). Pass as `blockLoader` to
+ * `parseNodeMaterialFromSnippet` for node-material geometry-renderer scenes so
+ * ordinary node scenes don't bundle the geometry block.
+ */
+export declare function loadNodeBlockEmitterWithGeometry(className: string): Promise<BlockEmitter>;
+
 /** Load a skybox cube texture and register it on the scene.
  *  The auto-builder will create the pipeline and render it.
  *
@@ -2273,16 +3633,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 +3658,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 +3675,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 {
@@ -2331,7 +3733,12 @@ export declare interface MaterialVariantData {
  *  The view is also a Material: it inherits material state from {@link source}
  *  through the prototype chain and owns only render-feature bits. Keeping views
  *  material-compatible lets ordinary render paths read properties normally, so
- *  scenes that never create views do not retain view-specific unwrap branches. */
+ *  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
+ *  `_rebuildSingle` builds the right kind of Renderable — no per-family
+ *  branching is required in the core render-task. */
 export declare interface MaterialView extends Material {
     readonly source: Material;
 
@@ -2356,13 +3763,25 @@ export declare interface Mesh extends SceneNode {
     boundMax?: [number, number, number];
     /** Skeleton GPU data (skeletal animation). Type-only — no module dependency. */
     skeleton?: SkeletonData | null;
+    /** Baked vertex-animation (VAT) GPU data — replaces live skinning so the mesh thin-instances.
+     *  Mutually exclusive with live `skeleton` skinning. Type-only — no module dependency. */
+    vat?: VatData | null;
     /** Morph target GPU data. Type-only — no module dependency. */
     morphTargets?: MorphTargetData | null;
     /** 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;
+    thinInstances?: ThinInstanceData | null;
+    /** When `false`, the GPU picker skips this mesh.  Defaults to `true`
+     *  (undefined behaves as pickable).  Mirrors BJS `AbstractMesh.isPickable`. */
+    pickable?: boolean;
 
 /** Opaque GPU geometry handle (user never touches these). */
 export declare interface MeshGPU {
@@ -2445,6 +3864,12 @@ export declare interface NavMeshParameters {
     keepIntermediates?: boolean;
 }
 
+/** A single mesh source for navmesh construction. */
+export declare interface NavMeshSource {
+    positions: ArrayLike<number>;
+    indices: ArrayLike<number>;
+}
+
 /** Parsed block in the graph. */
 declare interface NodeBlock {
     readonly id: number;
@@ -2535,8 +3960,7 @@ declare interface NodeBuildState {
     hasSkeleton: boolean;
     /** When false (default), InstancesBlock passes through the uniform world
      *  matrix. Set to true when thin-instance attributes are bound. */
-    hasInstances: boolean;
-}
+    hasInstances: boolean;
 
 /** A single connection point on a block — input only.
  *  Output connection types are resolved by the emitter at graph-walk time. */
@@ -2652,6 +4076,9 @@ export declare interface NormalizedViewport {
     height: number;
 }
 
+/** Wrap an angle to [-π, π), matching Babylon.js `Scalar.NormalizeRadians`. */
+export declare function normalizeRadians(angle: number): number;
+
 /**
  * Normalizes the vector `(x, y, z)` to unit length.
  * @param x - X component.
@@ -2672,7 +4099,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,10 +4160,35 @@ 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;
 
+/** Convert a packed 0xRRGGBB sRGB color to a linear-RGBA tuple suitable for
+ *  text-renderer `defaultColor` / `PlacedGlyph.color`. */
+export declare function packedSrgbToLinearRgba(packed: number, alpha?: number): readonly [number, number, number, number];
+
 /** Parse a Babylon NME graph (by snippet ID or inline JSON), emit WGSL, compile
  *  the GPU pipeline, and return a ready-to-render `NodeMaterial`.
  *  @param engine - Engine context.
@@ -2776,6 +4233,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];
@@ -2925,8 +4386,7 @@ export declare interface PhysicsAggregateOptions {
 
 /** Opaque handle to a Havok rigid body, bound to a scene node and a motion type. */
 export declare interface PhysicsBody {
    readonly node: SceneNode;
-    readonly motionType: PhysicsMotionType;
-}
+    readonly motionType: PhysicsMotionType;
 
 /** How a body moves: `STATIC` (immovable), `ANIMATED` (driven by the node transform), or `DYNAMIC` (simulated). */
 export declare const enum PhysicsMotionType {
@@ -2970,7 +4430,7 @@ export declare const enum PhysicsShapeType {
 export declare interface PhysicsWorld {
 
 /** Pick the mesh at CSS-space canvas coordinates, matching Babylon.js Scene.pick. Returns a PickingInfo. */
-export declare function pickAsync(picker: GpuPicker, x: number, y: number): Promise<PickingInfo>;
+export declare function pickAsync(picker: GpuPicker, x: number, y: number, options?: PickOptions): Promise<PickingInfo>;
 
 /** Result of a GPU pick operation. */
 export declare interface PickingInfo {
@@ -2993,6 +4453,16 @@ export declare interface PickingInfo {
     ray: Ray | null;
 }
 
+/** Options for {@link pickAsync}. */
+export declare interface PickOptions {
+    /** Restrict the pick to a subset of the scene's meshes — return `true` for a mesh that may be picked,
+     *  `false` to ignore it entirely (it neither occludes nor is returned). Lets a caller provide its
+     *  "list of pickables" so decorative meshes (grass, foliage, particles, …) can't swallow a pick of a
+     *  structure behind/around them. When omitted, every mesh is pickable (previous behaviour). Applied
+     *  identically to the id-assignment and id-resolve passes so ids stay consistent. */
+    filter?: (mesh: Mesh) => boolean;
+}
+
 /** Sampler and format overrides for `createTexture2DFromPixels()`. */
 export declare interface PixelsTexture2DOptions {
     /** Address mode U. Default 'clamp-to-edge'. */
@@ -3016,6 +4486,36 @@ export declare interface PixelViewport {
     height: number;
 }
 
+export declare type PlacedGlyph = {
+    readonly glyphId: number;
+    /** Pixel position of glyph baseline origin. */
+    readonly x: number;
+    readonly y: number;
+    /** Optional per-glyph color as linear RGBA in [0,1]. When present this overrides the
+     *  run's `defaultColor` for this glyph. When omitted, the glyph falls back to the run's
+     *  `defaultColor`, and if that is also omitted, to opaque white. The rendered alpha is
+     *  additionally scaled by the whole-block opacity (e.g. `TextRenderable.opacity`). */
+    readonly color?: readonly [number, number, number, number];
+};
+
+export declare interface PlaneDragGizmo {
+    readonly root: SceneNode;
+    readonly drag: PointerDrag;
+    readonly onPositionChanged: GizmoObservable<Vec3>;
+    attachedNode: SceneNode | null;
+    /** When true, the plane normal rotates with the attached node each frame
+     *  (local-coord mode). When false, the normal stays world-aligned. */
+    useLocalCoordinates: boolean;
+    readonly materials: GizmoMaterialSet;
+
+export declare interface PlaneDragGizmoOptions {
+    /** World-space drag plane normal (unit vector). */
+    dragPlaneNormal: Vec3;
+    color?: [number, number, number];
+    hoverColor?: [number, number, number];
+    disableColor?: [number, number, number];
+}
+
 /** Options for `createPlaneData`. Subset of Babylon's CreatePlane. */
 export declare interface PlaneOptions {
     size?: number;
@@ -3023,6 +4523,33 @@ export declare interface PlaneOptions {
     height?: number;
 }
 
+export declare interface PlaneRotationGizmo {
+    readonly root: SceneNode;
+    readonly drag: PointerDrag;
+    readonly onRotationChanged: GizmoObservable<[number, number, number, number]>;
+    attachedNode: SceneNode | null;
+    /** Local-coord mode: plane normal rotates with the attached node. */
+    useLocalCoordinates: boolean;
+    readonly materials: GizmoMaterialSet;
+    /** ShaderMaterial driving the rotation-sector camembert visual.  Exposed so
+     *  callers can change the colour at runtime. */
+    readonly rotationDisplayMaterial: ShaderMaterial;
+
+export declare interface PlaneRotationGizmoOptions {
+    /** World-space rotation plane normal (unit vector). */
+    planeNormal: Vec3;
+    color?: [number, number, number];
+    hoverColor?: [number, number, number];
+    disableColor?: [number, number, number];
+    /** Torus tessellation.  Default 32 (matches BJS). */
+    tessellation?: number;
+    /** Tube thickness multiplier.  Default 1. */
+    thickness?: number;
+    /** Colour of the rotation "camembert" sector visual shown while dragging.
+     *  Defaults to the hover colour. */
+    rotationColor?: [number, number, number];
+}
+
 /** Start playing an animation group. */
 export declare function playAnimation(group: AnimationGroup): void;
 
@@ -3084,6 +4611,96 @@ 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 PointerDrag {
+    readonly options: Readonly<PointerDragOptions>;
+    enabled: boolean;
    /** Fired once when a pointer-down lands on one of `_colliders`. */
+    onDragStart: GizmoObservable<PointerDragStartEvent>;
+    /** Fired on every pointer-move while a drag is active. */
+    onDrag: GizmoObservable<PointerDragMoveEvent>;
+    /** Fired once when the pointer is released. */
+    onDragEnd: GizmoObservable<PointerDragEndEvent>;
+    /** Fired when the pointer hovers over one of `_colliders` (no button pressed).
+     *  Used by gizmos to swap to a hover-coloured material before any drag.
+     *  Always fires AFTER a previous `onHoverEnd` for a different drag, so the
+     *  receiver doesn't need to track which collider is currently hovered. */
+    onHoverStart: GizmoObservable<void>;
+    /** Fired when the pointer leaves a previously-hovered collider. */
+    onHoverEnd: GizmoObservable<void>;
+    /** True while a drag is in progress. */
+    dragging: boolean;
+    /** True while the pointer is hovering one of `_colliders` (no drag). */
+    hovering: boolean;
+}
+
+export declare interface PointerDragEndEvent {
+    pointerEvent: PointerEvent | null;
+}
+
+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). */
+    delta: Vec3;
+    /** Current world-space point on the drag plane (post-projection). */
+    dragPlanePoint: Vec3;
+    /** Signed scalar distance projected onto the drag axis since drag start
+     *  (axis-drag mode); for plane mode this is `delta.length()`. */
+    dragDistance: number;
+}
+
+export declare interface PointerDragOptions {
+    /** Drag along a single world-space axis (unit vector). Mutually exclusive
+     *  with `dragPlaneNormal`. */
+    dragAxis?: Vec3;
+    /** Drag inside a plane defined by this world-space normal.  Mutually
+     *  exclusive with `dragAxis`. */
+    dragPlaneNormal?: Vec3;
+    /** When false, the dispatcher fires events but doesn't move the picked
+     *  mesh.  Gizmos always set this to false and apply transforms to their
+     *  attached node themselves. */
+    moveAttached?: boolean;
+    /** Optional override for the drag-plane anchor point (plane mode only).
+     *  When it returns a point, the camera-facing drag plane passes through that
+     *  point instead of the picked surface point, so the screen→world scale is
+     *  taken at that depth.  The BoundingBoxGizmo body drag anchors at the
+     *  bounding-box CENTRE (matching BJS, whose body `_dragMesh` sits at the box
+     *  centroid) so the translation scale doesn't depend on where the press
+     *  landed on the (inset, camera-facing) body surface. */
+    getPlanePoint?: () => Vec3 | null;
+}
+
+export declare interface PointerDragStartEvent {
+    /** World-space point where the ray intersected the drag plane on drag start. */
+    dragPlanePoint: Vec3;
+    /** Browser pointer event that triggered drag start. */
+    pointerEvent: PointerEvent;
+}
+
 export declare interface PointLight extends LightBase {
     readonly lightType: "point";
     position: ObservableVec3;
@@ -3109,6 +4726,25 @@ export declare interface PolyhedronOptions {
     flat?: boolean;
 }
 
+export declare interface PositionGizmo {
+    readonly xGizmo: AxisDragGizmo;
+    readonly yGizmo: AxisDragGizmo;
+    readonly zGizmo: AxisDragGizmo;
+    readonly xPlaneGizmo: PlaneDragGizmo | null;
+    readonly yPlaneGizmo: PlaneDragGizmo | null;
+    readonly zPlaneGizmo: PlaneDragGizmo | null;
+    attachedNode: SceneNode | null;
+}
+
+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`
+     *  defaults to false and must be opted into. */
+    planarEnabled?: boolean;
+    /** Tube thickness multiplier for the axis arrows. */
+    thickness?: number;
+}
+
 /** Output blend mode: `0` opaque, `1` additive, `2` premultiplied, `7` non-premultiplied alpha. */
 export declare type PostProcessAlphaMode = 0 | 1 | 2 | 7;
 
@@ -3190,6 +4826,15 @@ export declare interface PropertyAnimationTrackOptions {
     readonly quaternion?: boolean;
 }
 
+export declare type QuadCurve = {
+    readonly p0x: number;
+    readonly p0y: number;
+    readonly p1x: number;
+    readonly p1y: number;
+    readonly p2x: number;
+    readonly p2y: number;
+};
+
 /** Quaternion rotation */
 declare interface Quat {
     x: number;
@@ -3249,27 +4894,59 @@ export declare interface RefractionProps {
     dispersion?: number;
 }
 
-/** Register the effect renderer with its engine. Idempotent — a second call is a no-op. */
+/** Register the effect renderer with its surface. Idempotent — a second call is a no-op. */
 export declare function registerEffectRenderer(er: EffectRenderer): void;
 
-/** Build and register the standalone frame-graph context with its engine. */
+/** Build and register the standalone frame-graph context with its surface. */
 export declare function registerFrameGraphContext(ctx: FrameGraphContext): void;
 
+/** Register the drag's colliders + handlers with the per-canvas dispatcher for
+ *  this utility layer.  Returns a function that unregisters the drag.  When the
+ *  last drag for a canvas is unregistered, the dispatcher tears itself down
+ *  (canvas listeners are detached, the GPU picker is disposed, the cache entry
+ *  is removed) so disposing all gizmos doesn't leak listeners or GPU resources. */
+export declare function registerPointerDrag(layer: UtilityLayer, canvas: HTMLCanvasElement, drag: PointerDrag): () => void;
+
 /**
  * Register a scene with the engine. Builds deferred work, sorts renderables by order,
- * and adds the scene to the engine's render list in overlay order.
+ * and adds the scene to its bound surface's render list in overlay order. The scene is
+ * always attached to `scene.surface` (which equals the engine itself in the
+ * single-canvas case).
  */
-export declare function registerScene(engine: EngineContext, scene: SceneContext): Promise<void>;
+export declare function registerScene(scene: SceneContext): Promise<void>;
 
 /**
  * Register a scene with the engine and install the scene-owned shadow frame-graph task.
- * Use only for scenes that generate shadow maps.
+ * Use only for scenes that generate shadow maps. Like {@link registerScene}, the scene
+ * is attached to `scene.surface` (and its owning engine is `scene.surface.engine`).
  */
-export declare function registerSceneWithShadowSupport(engine: EngineContext, scene: SceneContext): Promise<void>;
+export declare function registerSceneWithShadowSupport(scene: SceneContext): Promise<void>;
 
 /** Push the renderer onto its engine's `_renderingContexts`. Idempotent — a second call is a no-op. */
 export declare function registerSpriteRenderer(sr: SpriteRenderer): void;
 
+export declare function registerTextRenderer(tr: TextRenderer): void;
+
+/** Register the utility layer with the engine. Must be called after the main
+ *  scene has been registered so the swapchain overlay path is enabled. */
+export declare function registerUtilityLayer(utility: UtilityLayer): Promise<void>;
+
+/**
+ * Release a collision shape's native handle, freeing its WASM memory. Only call once no body still
+ * references the shape (e.g. after {@link removePhysicsBody}). Useful when rebuilding a changing set of
+ * static colliders so their shapes don't accumulate.
+ * @param world - The physics world.
+ * @param shape - The shape to release.
+ */
+export declare function releasePhysicsShape(world: PhysicsWorld, shape: PhysicsShape): void;
+
+/**
+ * Decrement ref count on a Texture2D.
+ * Calls `tex.texture.destroy()` when count reaches 0.
+ * Returns true if the texture was destroyed.
+ */
+export declare function releaseTexture(tex: Texture2D): boolean;
+
 /** Detaches `group` from `manager`, removing its animation task so it is no longer ticked. */
 export declare function removeAnimationGroup(manager: AnimationManager, group: AnimationGroup): void;
 
@@ -3300,6 +4977,16 @@ export declare function removeMeshFromTask(task: RenderTask, mesh: object): void
 /** Remove an obstacle previously added by `addBoxObstacle` / `addCylinderObstacle`. */
 export declare function removeObstacle(plugin: NavigationPlugin, obstacle: ObstacleHandle): void;
 
+/**
+ * Remove a single body from the world and release its native handle (the per-frame step skips it from
+ * now on). After this the body must not be reused. A body that isn't in the world is ignored, so this is
+ * safe to call once per body. Does NOT release the body's collision shape — release that separately with
+ * {@link releasePhysicsShape} if it isn't shared.
+ * @param world - The physics world.
+ * @param body - The body to remove.
+ */
+export declare function removePhysicsBody(world: PhysicsWorld, body: PhysicsBody): void;
+
 /**
  * Removes the sprite referenced by `handle`. Does nothing if it is already gone.
  * @param handle - Handle of the sprite to remove.
@@ -3326,6 +5013,8 @@ 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;
 
+export declare function removeTextRendererLayer(tr: TextRenderer, layer: TextLayer): boolean;
+
 /** Remove instance by index. Swap-removes: last instance fills the gap. */
 export declare function removeThinInstance(mesh: Mesh, index: number): void;
 
@@ -3355,6 +5044,8 @@ export declare interface Renderable {
  */
 export declare type RenderCanvas = HTMLCanvasElement | OffscreenCanvas;
 
+export declare function renderFrame(engine: EngineContext, delta: number): void;
+
 /**
  * Minimal surface an engine sees for anything it renders. Scenes (and any other
  * future renderable thing) register themselves as a `RenderingContext` and
@@ -3369,7 +5060,8 @@ export declare interface RenderPass extends Pass {
    /** Per-frame mutable sta
      *  before iterating its passes. */
     clearColor: GPUColorDict;
     /** True → loadOp `"clear"`, false → `"load"` (overlay mode). */
-    clear: boolean;
+    clear: boolean;
+}
 
 /** Body of a render pass — receives the live render-pass encoder and returns
  *  the number of draws issued. */
@@ -3381,22 +5073,22 @@ export declare interface RenderTarget {
 /** Describes a render target — what attachments to create, not the GPU objects
  *  themselves. GPU textures are allocated later by `buildRenderTarget`. */
 export declare interface RenderTargetDescriptor {
-    label?: string;
-    colorFormat?: GPUTextureFormat;
-    depthStencilFormat?: GPUTextureFormat;
    sampleCount: number;
-    /** 'canvas' means match the canvas pixel size. Otherwise explicit pixels. */
-    size: "canvas" | {
+    /** Debug label applied to the allocated GPU color/depth textures. */
+    lbl?: string;
+    /** Color attachment texture format (e.g. `"bgra8unorm"`, `"rgba16float"`). Omit for a depth-only target. */
+    format?: GPUTextureFormat;
+    /** Depth/stencil attachment format (e.g. `"depth24plus-stencil8"`). Omit for a color-only target (e.g. the swapchain). */
+    dFormat?: GPUTextureFormat;
    /** MSAA sample count: `1` = single-sample (no multisampling), `4` = 4x MSAA. */
+    samples: number;
+    /** A `SurfaceContext` to size to that surface's swapchain (re-resolved each
+     *  `buildRenderTarget`), or explicit `{ width, height }` in device pixels. Pass a
+     *  surface for canvas-sized RTs; the RT then tracks that specific surface in
+     *  multi-surface setups. In the common single-canvas case, pass the engine directly
+     *  (since `EngineContext extends SurfaceContext`). */
+    size: SurfaceContext | {
         width: number;
         height: number;
     };
-    /** If true, the color attachment resolves to the swapchain texture. The RT still
-     *  owns the MSAA texture (when sampleCount \> 1) and the depth texture; only the
-     *  final color is the swapchain view, acquired per frame and patched in at execute
-     *  time. With sampleCount === 1 the RT owns no color texture (the swap view is the
-     *  color attachment directly). */
-    resolveToSwapchain?: boolean;
-    /** Override projection Y-flip. Defaults to true for offscreen targets and false for swapchain targets. */
-    flipY?: boolean;
 }
 
 /** Signature of a render target's attachment set — enough to key a GPURenderPipeline. */
@@ -3421,10 +5113,32 @@ export declare interface RenderTaskConfig {
      *  management is virtualized, callers must provide the concrete target; once
      *  virtualized, the task should create/manage its own render target. */
     rt: RenderTarget;
+    /** Optional single-sample resolve target. When `rt` is multisampled
+     *  (`sampleCount > 1`), the color attachment resolves into this target's
+     *  color texture at end-of-pass — letting an MSAA render feed a post-process
+     *  that requires a single-sample source, without an extra resolve pass.
+     *  Caller contract (not validated): must be single-sample with a color
+     *  format and size matching `rt`; WebGPU errors at pass-encode time if not.
+     *  Ignored when `rt` is single-sample. */
+    rst?: RenderTarget;
+    /** Optional separate depth/stencil attachment. The pass binds this target's
+     *  depth view instead of `rt`'s own, and uses its `depthStencilFormat` for
+     *  pipeline signature matching. The colour `rt` must omit `depthStencilFormat`
+     *  (so it allocates no internal depth) and match this target in size + sample
+     *  count. Two ownership modes, distinguished by `_eager`:
+     *  - `_eager` depth (e.g. a `GeometryRendererTask` output): the task neither
+     *    builds nor clears nor disposes it — it loads it (`loadOp: "load"`) and the
+     *    caller owns clearing. This is how scenes reuse a pre-rendered depth buffer.
+     *  - non-`_eager` depth: the task owns it — builds/rebuilds it in `record()`,
+     *    clears it (`loadOp: "clear"`), and disposes it. Used by the default
+     *    single-sample scene task, whose colour `rt` is the depth-less
+     *    engine `scRT`. */
+    depth?: RenderTarget;
     /** Background clear color. May be mutated frame-to-frame. */
     clrColor?: GPUColorDict;
-    /** When true, controls color + depth `loadOp` ("clear"). When false, use "load"
-     *  so this pass overlays previous content (UI overlays, second scene, etc.). */
+    /** When true, color `loadOp` is "clear"; when false, "load" (overlays previous
+     *  color content). Depth is always cleared when rt-owned and always loaded when
+     *  supplied via `depth`. */
     clr?: boolean;
     /** Per-pass camera override. Null/undefined uses `scene.camera`. */
     cam?: Camera | null;
@@ -3438,21 +5152,60 @@ export declare interface RenderTaskConfig {
     };
 }
 
+/** Sampler / format overrides for `createRenderTexture2D()`. */
+export declare interface RenderTexture2DOptions {
+    /** Address mode U. Default 'clamp-to-edge'. */
+    addressModeU?: GPUAddressMode;
+    /** Address mode V. Default 'clamp-to-edge'. */
+    addressModeV?: GPUAddressMode;
+    /** Min filter. Default 'linear'. */
+    minFilter?: GPUFilterMode;
+    /** Mag filter. Default 'linear'. */
+    magFilter?: GPUFilterMode;
+    /**
+     * Color format. Default `engine.format` so it can be sampled and presented.
+     *
+     * ⚠️ Only the default `engine.format` is compatible with a `SpriteRenderer`
+     * target (`setSpriteRendererTarget`): sprite pipelines are created with
+     * `engine.format`, and a render pass whose color attachment format differs from
+     * the bound pipeline fails WebGPU validation at pass begin. Override this **only**
+     * for offscreen targets you render into by some OTHER means (a custom pass /
+     * `EffectRenderer`), never as a sprite-render target.
+     */
+    format?: GPUTextureFormat;
+}
+
 /**
  * Reset all variant-participating meshes to their original (default) materials.
  */
 export declare function resetVariant(container: AssetContainer): void;
 
-/** Resize the swapchain backing-store to match the canvas client size. When the size
- *  changes, asks every registered rendering context to rebuild its canvas-sized GPU
- *  resources via the optional `_resize` hook. If the canvas has not been laid out yet,
- *  preserves its explicit backing-store size.
- *
- *  Only DOM canvases are auto-sized from layout here. An `OffscreenCanvas` has no layout
- *  box, so its size is pushed in externally via {@link setEngineSize} (e.g. from the host
- *  thread that owns the visible canvas) and this call is a no-op for it. */
+/** Resize every surface attached to this engine (including the engine's own primary
+ *  surface). For DOM-canvas surfaces, snaps the swapchain backing store to the current
+ *  `clientWidth × clientHeight × devicePixelRatio` (capped by each surface's
+ *  `maxDevicePixelRatio`). For `OffscreenCanvas` surfaces this is a no-op per surface —
+ *  call `setSurfaceSize` on the specific surface instead, since an `OffscreenCanvas`
+ *  has no layout. */
 export declare function resizeEngine(engine: EngineContext): void;
 
+/** Replace a mesh's GPU geometry IN PLACE with new (possibly larger or smaller) buffers, reusing the
+ *  same Mesh object so existing references to it (scene entries, shadow-caster lists, materials) stay
+ *  valid. Unlike `updateMeshPositions`, this REALLOCATES the GPU buffers, so it's the way to GROW a
+ *  dynamically-generated mesh past its original vertex/index capacity (e.g. an ever-larger bridge whose
+ *  box budget overflows). The old GPU buffers are destroyed to free device memory. Recomputes bounds. */
+export declare function resizeMeshGeometry(engine: EngineContext, mesh: Mesh, positions: Float32Array, normals: Float32Array, indices: Uint32Array, uvs?: Float32Array, uvs2?: Float32Array, tangents?: Float32Array, colors?: Float32Array): void;
+
+/** Resize this surface's swapchain backing store to match the canvas client size. When
+ *  the size changes, asks every rendering context registered on this surface to rebuild
+ *  its canvas-sized GPU resources via the optional `_resize` hook. If the canvas has
+ *  not been laid out yet, preserves its explicit backing-store size.
+ *
+ *  Only DOM canvases are auto-sized from layout here. An `OffscreenCanvas` has no
+ *  layout box, so its size must be pushed in externally via {@link setSurfaceSize}
+ *  (e.g. from the host thread that owns the visible canvas) and this call is a no-op
+ *  for it. */
+export declare function resizeSurface(surface: SurfaceContext): void;
+
 /** Resolve a Babylon-style normalized viewport to integer render-target pixels.
  *  Babylon viewport y is normalized from the bottom; WebGPU viewport/scissor y is from the top. */
 export declare function resolveCameraViewport(camera: Camera | null | undefined, targetWidth: number, targetHeight: number): PixelViewport;
@@ -3465,6 +5218,31 @@ export declare interface RibbonOptions {
     offset?: number;
 }
 
+export declare interface RotationGizmo {
+    readonly xGizmo: PlaneRotationGizmo;
+    readonly yGizmo: PlaneRotationGizmo;
+    readonly zGizmo: PlaneRotationGizmo;
+    attachedNode: SceneNode | null;
+}
+
+export declare interface RotationGizmoOptions {
+    tessellation?: number;
+    thickness?: number;
+}
+
+export declare interface ScaleGizmo {
+    readonly xGizmo: AxisScaleGizmo;
+    readonly yGizmo: AxisScaleGizmo;
+    readonly zGizmo: AxisScaleGizmo;
+    /** Central uniform-scale gizmo (single arrow with uniformScaling = true). */
+    readonly uniformScaleGizmo: AxisScaleGizmo;
+    attachedNode: SceneNode | null;
+}
+
+export declare interface ScaleGizmoOptions {
+    thickness?: number;
+}
+
 /** Scattering sub-feature. Presence enables screen-space subsurface scattering.
  *  NOTE: PrePass/SSS pipeline is not yet implemented — this type is reserved. */
 declare interface ScatteringProps {
@@ -3474,9 +5252,23 @@ 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;
+    /** Surface this scene renders into. Set at scene-creation time and immutable
+     *  afterwards — the default render task is sized and MSAA-matched to this surface,
+     *  and `registerScene` attaches the scene to it. For the engine's primary surface
+     *  (the common single-canvas case) this is the engine itself. The owning engine is
+     *  reachable via `scene.surface.engine`. */
+    readonly surface: SurfaceContext;
     clearColor: GPUColorDict;
     camera: Camera | null;
     lights: LightBase[];
@@ -3527,6 +5319,29 @@ export declare interface SceneUniformUpdater {
     update(engine: EngineContext): void;
 }
 
+/**
+ * A captured frame, read back from the canvas swapchain.
+ *
+ * `data` is tightly-packed RGBA8 (4 bytes/pixel), row-major, top row first — the same
+ * layout `ImageData` expects, so it can be handed straight to a 2D canvas:
+ *
+ * ```ts
+ * const shot = await captureScreenshot(surface);
+ * const cv = new OffscreenCanvas(shot.width, shot.height);
+ * cv.getContext("2d")!.putImageData(new ImageData(shot.data, shot.width, shot.height), 0, 0);
+ * const url = await cv.convertToBlob({ type: "image/jpeg", quality: 0.85 });
+ * ```
+ *
+ * Alpha is forced to 255 (fully opaque): the swapchain is presented opaque, so its alpha
+ * channel is not meaningful for a saved image. Colours are the final, presented 8-bit
+ * values (BGRA swizzled to RGBA when the preferred canvas format is BGRA).
+ */
+export declare interface Screenshot {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8ClampedArray;
+}
+
 /**
  * Select a material variant by name on a loaded glTF asset.
  *
@@ -3577,6 +5392,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.
@@ -3593,13 +5444,26 @@ export declare function setEffectTexture(wrapper: EffectWrapper, bindingNameOrIn
  */
 export declare function setEffectUniforms(wrapper: EffectWrapper, data: ArrayBuffer | ArrayBufferView | Record<string | number, ArrayBuffer | ArrayBufferView>): void;
 
-/** Set the swapchain backing-store size directly, in device pixels. Use this when the
- *  engine renders into an `OffscreenCanvas` whose layout size is only known on another
- *  thread (the host posts the CSS size × devicePixelRatio). When the size changes, asks
- *  every registered rendering context to rebuild its canvas-sized GPU resources via the
- *  optional `_resize` hook. */
+/** Set the engine's primary-surface swapchain backing-store size directly, in device
+ *  pixels. Convenience wrapper around `setSurfaceSize(engine, w, h)` since the engine
+ *  *is* its own primary surface — for auxiliary surfaces, prefer calling `setSurfaceSize`
+ *  on the specific target. */
 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;
+
+/** Set one or more orientation fields at once (single recompute). Omitted fields keep their value. */
+export declare function setGeospatialOrientation(camera: GeospatialCamera, orientation: GeospatialOrientation): 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. */
@@ -3624,13 +5488,33 @@ export declare function setNavigationRandomSeed(plugin: NavigationPlugin, seed:
  */
 export declare function setParent(child: Mesh, parent: IWorldMatrixProvider | null): void;
 
+/**
+ * Set a body's angular velocity (rad/s).
+ */
+export declare function setPhysicsBodyAngularVelocity(world: PhysicsWorld, body: PhysicsBody, velocity: Vec3): void;
+
+/**
+ * Set a body's linear velocity (m/s) directly — e.g. to impart a throw velocity on release.
+ */
+export declare function setPhysicsBodyLinearVelocity(world: PhysicsWorld, body: PhysicsBody, velocity: Vec3): void;
+
 /**
  * Sets a body's mass and a matching diagonal inertia tensor.
  * @param world - The physics world.
  * @param body - The body to update.
  * @param mass - Mass in kilograms.
+ * @param centerOfMass - Optional body-local centre of mass (defaults to the origin). Use this when the
+ *   collision shape is offset from the body's reference frame (e.g. a prop whose body origin sits at
+ *   its base but whose shape is centred on its middle) so it tumbles around its real centre.
+ */
+export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBody, mass: number, centerOfMass?: Vec3): void;
+
+/**
+ * Switch a body's motion type at runtime (e.g. ANIMATED/kinematic while a prop is grabbed, then
+ * DYNAMIC on release). Mutates `body.motionType` so the per-frame step syncs it the right way
+ * (ANIMATED: node → body before the step; DYNAMIC: body → node after).
  */
-export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBody, mass: number): void;
+export declare function setPhysicsBodyMotionType(world: PhysicsWorld, body: PhysicsBody, motionType: PhysicsMotionType): void;
 
 /**
  * Assigns a collision shape to a body.
@@ -3641,11 +5525,20 @@ export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBod
 export declare function setPhysicsBodyShape(world: PhysicsWorld, body: PhysicsBody, shape: PhysicsShape): void;
 
 /**
- * Sets the world's gravity vector.
+ * Teleport a body to a world position + orientation (a pure transform set — velocities are left
+ * unchanged). For grab-follow, save-restore, and undo. Also updates the bound node so a render that
+ * reads the node before the next physics step stays consistent.
+ */
+export declare function setPhysicsBodyTransform(world: PhysicsWorld, body: PhysicsBody, position: Vec3, rotation: Quat): void;
+
+/**
+ * Sets gravity for the world, or for a single region when `worldPosition` is given.
+ * Passing a position is useful for planetary scenarios where gravity direction varies by location.
  * @param world - The physics world.
  * @param gravity - Gravity acceleration in m/s².
+ * @param worldPosition - Optional world position selecting the region to update; omit to update all regions.
  */
-export declare function setPhysicsGravity(world: PhysicsWorld, gravity: Vec3): void;
+export declare function setPhysicsGravity(world: PhysicsWorld, gravity: Vec3, worldPosition?: Vec3): void;
 
 /**
  * Sets a shape's surface material properties.
@@ -3671,11 +5564,22 @@ export declare function setPhysicsTimestep(world: PhysicsWorld, dt: number): voi
  */
 export declare function setPhysicsVelocityLimits(world: PhysicsWorld, maxLinear: number, maxAngular: number): void;
 
+export declare function setPositionGizmoLocalCoordinates(gizmo: PositionGizmo, useLocal: boolean): void;
+
+export declare function setRotationGizmoLocalCoordinates(gizmo: RotationGizmo, useLocal: boolean): void;
+
+/** Toggle local-coord mode on the per-axis scale arrows.  The uniform-scale
+ *  gizmo (centre) is always uniform so it ignores the flag. */
+export declare function setScaleGizmoLocalCoordinates(gizmo: ScaleGizmo, useLocal: boolean): void;
+
 /** 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`.
@@ -3731,6 +5635,18 @@ export declare function setSprite2DShaderParams(layer: Sprite2DLayer, params: re
  */
 export declare function setSprite2DUvOffset(layer: Sprite2DLayer, index: number, uvOffset: readonly [number, number]): void;
 
+/**
+ * Redirect a sprite renderer's output to an offscreen render {@link Texture2D} `target` (for
+ * render-to-texture / post-processing), or pass `null` to render to the swapchain (the
+ * default). Pair with {@link createRenderTexture2D} at its default format and the renderer's
+ * target size. The target's texture must be the engine's swapchain format: sprite pipelines
+ * are baked with `engine.format`, so a target of any OTHER format fails WebGPU validation at
+ * render-pass begin. A second renderer can then sample that texture (e.g. a fullscreen
+ * custom-shader layer) and present it. Renderers registered later run later, so register the
+ * offscreen scene pass before the presenting pass.
+ */
+export declare function setSpriteRendererTarget(sr: SpriteRenderer, target: Texture2D | null): void;
+
 /** Set `visible` on `node` and all descendants (via `node.children`). glTF
  *  KHR_node_visibility specifies that children inherit their parent's
  *  invisibility — we materialize this at set-time so the render hot-path
@@ -3739,14 +5655,39 @@ declare function setSubtreeVisible(node: SceneNode, v: boolean): void;
 export { setSubtreeVisible as setMeshVisible }
 export { setSubtreeVisible }
 
+/** Set this surface's swapchain backing-store size directly, in device pixels. Use this
+ *  when the surface renders into an `OffscreenCanvas` whose layout size is only known
+ *  on another thread (the host posts the CSS size × devicePixelRatio). When the size
+ *  changes, asks every rendering context registered on this surface to rebuild its
+ *  canvas-sized GPU resources via the optional `_resize` hook. */
+export declare function setSurfaceSize(surface: SurfaceContext, widthPx: number, heightPx: number): void;
+
+/** Update the layer's pixel position. Convenience wrapper. */
+export declare function setTextLayerPosition(layer: TextLayer, x: number, y: number): void;
+
+/** Update ONE instance's RGBA color in place — the color twin of `setThinInstanceMatrix`. Only the
+ *  touched span re-uploads (dirty-range), so per-instance color churn (e.g. streamed instances carrying
+ *  per-slot animation timestamps) stays cheap on large pools. Requires colors to have been set via
+ *  `setThinInstanceColors` first. */
+export declare function setThinInstanceColor(mesh: Mesh, index: number, r: number, g: number, b: number, a: number): void;
+
 /** Set per-instance RGBA colors for a thin-instanced mesh. */
 export declare function setThinInstanceColors(mesh: Mesh, colors: Float32Array): void;
 
+/** Update ONLY the active instance count (and re-upload the [0,count) matrix range), leaving `_capacity`
+ *  — and therefore the already-allocated GPU buffer — untouched. This is the way to vary how many instances
+ *  draw FRAME-TO-FRAME on an established thin-instanced mesh WITHOUT recreating the GPU buffer (which would
+ *  invalidate any cached render/shadow bundle that captured the old buffer handle). Pre-size the buffer once
+ *  with `setThinInstances(mesh, matrices, capacity)`, then call this each update with `count <= capacity`.
+ *  The draw reads `count` live, so the bundle stays valid. Caller must keep writing into the SAME `matrices`
+ *  array the mesh already references. No-op if the mesh isn't thin-instanced yet. */
+export declare function setThinInstanceCount(mesh: Mesh, count: number): void;
+
 /** Update one instance's matrix. */
 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,10 +5724,14 @@ 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;
-    readonly depthCompare: GPUCompareFunction;
+    readonly depthCompare: GPUCompareFunction;
+    readonly depthBias: number;
+    readonly depthBiasSlopeScale: number;
 
 /** Options describing a ShaderMaterial: WGSL sources, attributes, uniforms,
  *  samplers, defines, and blend/depth state. Passed to `createShaderMaterial()`. */
@@ -3803,16 +5748,51 @@ 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;
     readonly depthCompare?: GPUCompareFunction;
+    /** Constant depth-bias added in the pipeline's depth-stencil state (units of the depth format's minimum
+     *  representable value). Lets a surface that hugs another (e.g. tiles overlapping a cone, decals) win the
+     *  depth test consistently and avoid z-fighting. Default 0 (no bias). */
+    readonly depthBias?: number;
+    /** Slope-scaled depth bias — extra bias proportional to the depth gradient, so steeply-angled (grazing)
+     *  surfaces get more bias. Pairs with `depthBias` to kill z-fighting at oblique angles. Default 0. */
+    readonly depthBiasSlopeScale?: number;
+}
+
+/** Configuration for {@link createShaderNormalMaterialView}. */
+export declare interface ShaderNormalViewConfig {
+    /** Name of the world-position varying the source vertex stage emits. Default `"vWorldPos"`. */
+    readonly worldPosVarying?: string;
+    /** `@location()` of that varying in the vertex output struct. Default `0`. */
+    readonly worldPosLocation?: number;
+    /** Output space of the encoded normal: `"view"` (default — ready for
+     *  Blender-style screen-space curvature) or `"world"`. */
+    readonly space?: "view" | "world";
+    /** When set, the output ALPHA encodes the fragment's view distance normalized by this range
+     *  (`clamp(viewZ / range, 0, 1)`) so a consumer can fade the effect with distance. Clear the target's
+     *  alpha to `1` as the "no geometry" sentinel. When omitted, alpha is a flat `1` (validity only). */
+    readonly distanceEncodeRange?: number;
 }
 
 /** A sampler declaration: WGSL identifier and the bound texture's sample type. */
 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. */
@@ -4102,15 +6082,31 @@ export declare interface SpriteAtlas {
     readonly texture: Texture2D;
     readonly textureSizePx: readonly [number, number];
     readonly frames: readonly SpriteFrame[];
-    readonly premultipliedAlpha: boolean;
-}
+    readonly premultipliedAlpha: boolean;
 
-/** One source frame for `createSpriteAtlasFromFrames`. */
+/** One source frame for `createSpriteAtlasFromFrames` / `appendSpriteAtlasFrames`. The packed
+ *  region is `width × height` texels. By default the source is read as a tightly-packed RGBA8
+ *  buffer of exactly that size starting at byte 0; the optional `srcX` / `srcY` / `srcStrideBytes`
+ *  fields let the source describe a sub-rectangle of a larger buffer without forcing the caller
+ *  to copy out the sub-rect first. */
 export declare interface SpriteAtlasFrameSource {
-    /** Tightly packed RGBA8 bytes — `width * height * 4`, row-major, top-to-bottom, straight alpha. */
+    /** RGBA8 bytes, row-major, top-to-bottom, straight alpha. When `srcX` / `srcY` /
+     *  `srcStrideBytes` are all defaulted, this must be exactly `width * height * 4` bytes;
+     *  when sub-rect fields are supplied, it must be large enough to cover the rect
+     *  (see those fields' docs). */
     readonly pixels: Uint8Array;
+    /** Width of the frame to pack (texels written to the atlas). */
     readonly width: number;
+    /** Height of the frame to pack (texels written to the atlas). */
     readonly height: number;
+    /** Top-left x of the sub-rect to pack, in texels into `pixels`. Default `0`. */
+    readonly srcX?: number;
+    /** Top-left y of the sub-rect to pack, in texels into `pixels`. Default `0`. */
+    readonly srcY?: number;
+    /** Bytes between consecutive rows of `pixels`. Default `width * 4` (tightly packed).
+     *  Must satisfy `(srcX + width) * 4 <= srcStrideBytes` — i.e. each row's sub-rect window
+     *  must fit within one stride, so reads do not spill into the next row. */
+    readonly srcStrideBytes?: number;
     /** Pivot in [0,1] of the frame. Default `[0.5, 0.5]`. */
     readonly pivot?: readonly [number, number];
     /** Recorded on the emitted `SpriteFrame.name`. */
@@ -4126,6 +6122,11 @@ export declare interface SpriteAtlasPackOptions {
     /** Min/mag filter for the packed texture. Default `"nearest"`. */
     sampling?: SpriteSampling;
     premultipliedAlpha?: boolean;
+    /** Pre-allocate the atlas texture at this `[width, height]` regardless of initial-content
+     *  size, leaving headroom for later `appendSpriteAtlasFrames` calls (which never grow the
+     *  texture). Required when `sources` is empty. Defaults to the size required by the initial
+     *  `sources` (no append headroom). */
+    capacityPx?: readonly [number, number];
 }
 
 /**
@@ -4230,6 +6231,9 @@ export declare interface SpriteRendererOptions {
 /** Texture sampling mode for a sprite atlas. */
 export declare type SpriteSampling = "linear" | "nearest";
 
+/** Inverse of `linearToSrgbByte` — sRGB byte [0,255] → linear [0,1]. */
+export declare function srgbByteToLinear(b: number): number;
+
 /** Which shader stage an emitter writes into. Neutral blocks can run in either;
  *  the walker places them in the stage of their consumer (fragment by default). */
 declare type Stage = "vertex" | "fragment";
@@ -4246,6 +6250,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];
@@ -4361,6 +6369,60 @@ export declare interface SubSurfaceProps {
     refraction?: RefractionProps;
 }
 
+/**
+ * Per-canvas rendering surface — owns the GPU canvas context, swapchain format, MSAA
+ * configuration, and the list of `RenderingContext`s (scenes, effect renderers,
+ * frame-graph contexts, sprite/text renderers) that present to this canvas.
+ *
+ * The `EngineContext` *is itself a `SurfaceContext`* (the primary one, bound to the
+ * canvas passed into `createEngine`). Additional surfaces for auxiliary canvases are
+ * created via {@link createSurface}. GPU resources (textures, buffers, pipelines, bind
+ * groups) live on the {@link EngineContext} (device-scoped) and are shared across all
+ * surfaces of the same engine — only the swapchain output is per-surface.
+ */
+export declare interface SurfaceContext {
+    /** Owning engine. For the engine's primary surface this points back to the engine
+     *  itself (`engine.engine === engine`). */
+    readonly engine: EngineContext;
+    /** Canvas this surface presents to. */
+    readonly canvas: RenderCanvas;
+    /** Swapchain texture format for this surface. Use as the `format` for offscreen
+     *  RTs that will be composited onto this surface. */
+    readonly format: GPUTextureFormat;
+    /** MSAA sample count for the main render pass into this surface (1 or 4). */
+    readonly msaaSamples: number;
    /**
+     * Surface-owned color-only render target that wraps this canvas's swapchain texture.
+     * Its `_colorTexture`/`_colorView` are re-acquired from `context.getCurrentTexture()`
+     * once per frame (see `_refreshScRT`), so it is always single-sample and carries no
+     * depth. Render/post-process/copy tasks target it (or resolve into it) to present to
+     * the canvas. It is `_eager` — `buildRenderTarget` and `disposeRenderTarget` both
+     * no-op on it and the surface owns its textures, so its shared `_descriptor` must
+     * never be mutated.
+     */
+    readonly scRT: RenderTarget;
+    /** Clamps the effective device pixel ratio used for this surface's swapchain backing
+     *  store. The backing store is sized at `min(devicePixelRatio, maxDevicePixelRatio) * cssPixels`.
+     *  `maxDevicePixelRatio = 1` renders at native CSS-pixel resolution (no DPR upscaling);
+     *  the default `Infinity` is unclamped (full devicePixelRatio). Mutable at runtime — set
+     *  before the next `resizeSurface` to take effect (mirrors Babylon `setHardwareScalingRatio`). */
+    maxDevicePixelRatio: number;
+
+/** Options for {@link createSurface}, and for the per-surface portion of `createEngine`. */
+export declare interface SurfaceOptions {
+    /** MSAA sample count for the main render pass. WebGPU only permits `1` (no MSAA)
+     *  or `4` (4x MSAA). Defaults to `4`. */
+    msaaSamples?: 1 | 4;
+    /** WebGPU canvas alpha mode. Use `"premultiplied"` to enable canvas transparency
+     *  (clear color with `alpha < 1` will let HTML content underneath show through).
+     *  Defaults to `"opaque"`. */
+    alphaMode?: GPUCanvasAlphaMode;
+    /** Override the swapchain format. Defaults to `navigator.gpu.getPreferredCanvasFormat()`. */
+    format?: GPUTextureFormat;
+    /** Clamps the effective device pixel ratio used for the swapchain backing store.
+     *  Defaults to unclamped (full devicePixelRatio). */
+    maxDevicePixelRatio?: number;
+}
+
 declare type TargetPath = 0 | 1 | 2 | 3 | 4;
 
 /** Polymorphic interface that all frame-graph tasks implement: records `Pass` objects during `record()` and is executed once per frame. */
@@ -4376,6 +6438,125 @@ export declare interface Task {
     dispose(): void;
 }
 
+export declare interface TextData {
+    readonly [textDataBrand]: true;
+    /** Live, in-insertion-order view of the runs currently rendered. Mutated by
+     *  `updateTextData`. Do not mutate from outside. */
+    readonly runs: readonly GlyphRun[];
+
+declare const textDataBrand: unique symbol;
+
+/** Discriminated union driving `updateTextData`. Each variant's `update` field is the
+ *  discriminator. Arrays/maps passed inside any variant are *adopted* by the `TextData`
+ *  and must not be read or mutated by the caller afterward. */
+export declare type TextDataUpdate = {
+    /** Rebuild runs and/or swap to a different storage. Both `runs` and `storage`
+     *  are optional; missing fields default to the TextData's current value, so
+     *  `{ update: "reset" }` with neither performs a pure compaction pass that
+     *  re-lays-out the slot allocator without dead slots or gaps.
+     *  Invalidates any previously-passed `GlyphRun` references when `runs` is set. */
+    update: "reset";
+    runs?: GlyphRun[];
+    storage?: GlyphStorage;
+} | {
+    /** Append a new run to the live runs list, or insert it before the run currently at
+     *  `insertBefore`. The run's `curveSet` must already exist in the bound storage. */
+    update: "addRun";
+    run: GlyphRun;
+    /** Index in `data.runs` to insert before. Default = append at end. */
+    insertBefore?: number;
+} | {
+    /** Remove a previously-added run. Accepts either the `GlyphRun` reference or its
+     *  current index in `data.runs`. */
+    update: "removeRun";
+    run: GlyphRun | number;
+} | {
+    /** Replace one run's contents in place. The new run takes the slot in `data.runs`
+     *  that the previous run occupied. Cheapest when the new run has the same glyph
+     *  count and the same `curveSet` as the previous one. */
+    update: "replaceRun";
+    previous: GlyphRun | number;
+    run: GlyphRun;
+};
+
+/** Pure-data 2D text layer. Mutate fields directly between frames. */
+export declare interface TextLayer {
    readonly data: TextData;
+    positionPx: {
+        x: number;
+        y: number;
+    };
+    rotationRad: number;
+    scale: number;
+    order: number;
+    opacity: number;
+    visible: boolean;
+
+export declare interface TextLayerOptions {
+    /** Top-left origin (in canvas pixels) for the layer's local coordinate frame. Default (0, 0). */
+    readonly positionPx?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Z-axis rotation about `positionPx`, in radians. Default 0. */
+    readonly rotationRad?: number;
+    /** Uniform scale applied to the laid-out text. Default 1. */
+    readonly scale?: number;
+    /** Sort order within a renderer (lower draws first). Default 0. */
+    readonly order?: number;
+    /** Alpha multiplier in [0, 1]. Default 1. */
+    readonly opacity?: number;
+    /** Default true. */
+    readonly visible?: boolean;
+}
+
+export declare type TextLayoutOptions = {
+    /** Max line width in pixels before word-wrap. Default: Infinity. */
+    readonly maxWidth?: number;
+    /** Line-height multiplier. Default: 1.2. */
+    readonly lineHeight?: number;
+    /** Horizontal alignment. Default: "left". */
+    readonly align?: "left" | "center" | "right";
+    /** Extra spacing in font units. Default: 0. */
+    readonly letterSpacing?: number;
+    /** Tab size in spaces. Default: 4. */
+    readonly tabSize?: number;
+};
+
+export declare interface TextRenderable extends Renderable {
    readonly position: ObservableVec3;
+    readonly rotation: EulerProxy;
+    readonly rotationQuaternion: ObservableQuat;
+    readonly scaling: ObservableVec3;
+    /** Whole-block opacity in [0,1]. Color is supplied per-glyph by the `TextData` descriptor. */
+    opacity: number;
+    ignoreDepth: boolean;
+    order: number;
+
+export declare interface TextRenderableOptions {
+    readonly position?: Readonly<Vec3>;
+    readonly rotationQuaternion?: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    readonly scaling?: Readonly<Vec3>;
+    /** Whole-block opacity in [0,1]. Default 1. Per-glyph/per-run color comes from the `TextData`
+     *  descriptor (`PlacedGlyph.color` / `GlyphRun.defaultColor`), not from the renderable. */
+    readonly opacity?: number;
+    readonly ignoreDepth?: boolean;
+    readonly order?: number;
+}
+
+export declare interface TextRenderer extends RenderingContext_2 {
    readonly layers: readonly TextLayer[];
+
+export declare interface TextRendererOptions {
+    layers: readonly TextLayer[];
+    /** Default true. Set false for HUD overlays so the text pass preserves existing scene color. */
+    clear?: boolean;
+    /** Default `{ r: 0, g: 0, b: 0, a: 1 }`. */
+    clearValue?: GPUColorDict;
+}
+
 /** A loaded 2D texture: the GPU texture, its default view and sampler, pixel
  *  dimensions, and an optional per-texture UV transform. This is the public
  *  texture handle returned by `loadTexture2D()`, `createSolidTexture2D()`, etc. */
@@ -4445,8 +6626,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 +6643,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 +6709,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[];
@@ -4520,18 +6762,21 @@ export declare interface UniformEffectWrapperOptions {
     uniformByteLength: number;
 }
 
-/** Unregister the effect renderer from its engine. No-op if not registered. */
+/** Unregister the effect renderer from its surface. No-op if not registered. */
 export declare function unregisterEffectRenderer(er: EffectRenderer): void;
 
-/** Unregister the standalone frame-graph context from its engine. */
+/** Unregister the standalone frame-graph context from its surface. */
 export declare function unregisterFrameGraphContext(ctx: FrameGraphContext): void;
 
-/** Remove a previously-registered scene. Idempotent. Does not dispose scene resources. */
-export declare function unregisterScene(engine: EngineContext, scene: SceneContext): void;
+/** Remove a previously-registered scene. Idempotent. Does not dispose scene resources.
+ *  The scene is always removed from `scene.surface`. */
+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;
 
+export declare function unregisterTextRenderer(tr: TextRenderer): void;
+
 /** Advances every active task by `deltaMs` (or by `fixedDeltaMs` when set), running the category handler first.
  *  Ignores non-finite or negative steps. */
 export declare function updateAnimationManager(manager: AnimationManager, deltaMs: number): void;
@@ -4553,6 +6798,28 @@ export declare function updateBillboardSprite(handle: BillboardSpriteHandle, pat
  */
 export declare function updateBillboardSpriteIndex(system: BillboardSpriteSystem, index: number, patch: Partial<BillboardSpriteInit>): void;
 
+/** Re-shape `text` and apply the new run via `updateTextData(replaceRun)`. New glyphs are
+ *  added to the storage in place. When `textColor` is omitted, the live run's existing
+ *  `defaultColor` is preserved (so any caller-driven color override survives a text re-shape). */
+export declare function updateDefaultTextData(data: DefaultTextData, text: string, textColor?: readonly [number, number, number, number]): void;
+
+/** Add glyphs to the named curve-set, creating it if it doesn't exist yet. Glyph ids
+ *  already present in the curve-set are skipped (the existing outline + atlas slot wins).
+ *  Safe to call between frames: the atlas grows in place and the next render uploads the
+ *  new glyphs. */
+export declare function updateGlyphStorage(storage: GlyphStorage, curveSetId: CurveSetId, curves: ReadonlyMap<number, GlyphCurves>): void;
+
+/** Re-upload (part of) a mesh's COLOR buffer — the twin of `updateMeshNormals`/`updateMeshPositions`
+ *  for dynamically re-generated geometry whose per-vertex colors change (e.g. a procedural mesh whose
+ *  parts are re-tinted each rebuild). The color attribute is vec4 (16 bytes/vertex). No-op if the mesh
+ *  was created without colors. Zero-allocation GPU upload only. */
+export declare function updateMeshColors(engine: EngineContext, mesh: Mesh, colors: Float32Array, vertexOffset?: number): void;
+
+/** Re-upload (part of) a mesh's NORMAL buffer — the twin of `updateMeshPositions` for dynamically
+ *  re-generated geometry whose per-vertex normals change (e.g. a swept tube re-fitted each rebuild).
+ *  No-op if the mesh was created without normals. Zero-allocation GPU upload only. */
+export declare function updateMeshNormals(engine: EngineContext, mesh: Mesh, normals: Float32Array, vertexOffset?: number): void;
+
 /** Update a mesh's GPU vertex positions in place (e.g. CPU vertex animation).
  *  `positions` must hold tightly-packed XYZ floats matching the mesh's vertex count.
  *  `vertexOffset` is the first vertex to overwrite (defaults to 0).
@@ -4560,6 +6827,24 @@ export declare function updateBillboardSpriteIndex(system: BillboardSpriteSystem
  *  Zero-allocation GPU upload only — CPU-side picking geometry is not refreshed. */
 export declare function updateMeshPositions(engine: EngineContext, mesh: Mesh, positions: Float32Array, vertexOffset?: number): void;
 
+/** Re-upload (part of) a mesh's TANGENT buffer — the twin of `updateMeshColors` for dynamically
+ *  re-generated geometry whose per-vertex tangent (vec4) payload changes each rebuild (e.g. a procedural
+ *  batch that streams a per-vertex coordinate frame / mask through the tangent slot). The tangent attribute
+ *  is vec4 (16 bytes/vertex). No-op if the mesh was created without tangents. Zero-allocation GPU upload only. */
+export declare function updateMeshTangents(engine: EngineContext, mesh: Mesh, tangents: Float32Array, vertexOffset?: number): void;
+
+/** Re-upload (part of) a mesh's second UV buffer (uv2) — the twin of `updateMeshUvs` for dynamically
+ *  re-generated geometry whose per-vertex uv2 payload changes each rebuild (e.g. a procedural batch that
+ *  re-bakes per-vertex AO / gradient data). The uv2 attribute is vec2 (8 bytes/vertex). No-op if the mesh
+ *  was created without uv2. Zero-allocation GPU upload only. */
+export declare function updateMeshUv2(engine: EngineContext, mesh: Mesh, uvs2: Float32Array, vertexOffset?: number): void;
+
+/** Re-upload (part of) a mesh's UV buffer — the twin of `updateMeshNormals`/`updateMeshColors` for
+ *  dynamically re-generated geometry whose per-vertex UVs change (e.g. a procedural mesh whose parts
+ *  carry per-rebuild UV payloads). The uv attribute is vec2 (8 bytes/vertex). No-op if the mesh was
+ *  created without UVs. Zero-allocation GPU upload only. */
+export declare function updateMeshUvs(engine: EngineContext, mesh: Mesh, uvs: Float32Array, vertexOffset?: number): void;
+
 /** Advance the crowd simulation by `dt` seconds. */
 export declare function updateNavCrowd(crowd: NavCrowd, dt: number): void;
 
@@ -4585,6 +6870,41 @@ export declare function updateSprite2DIndex(layer: Sprite2DLayer, index: number,
  */
 export declare function updateSpriteAnimationManager(manager: SpriteAnimationManager, deltaMs: number): void;
 
+export declare function updateTextData(data: TextData, update: TextDataUpdate): 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;
+
+/** UtilityLayer handle. The `scene` field is a regular `SceneContext` — pass it
+ *  to gizmo factories so their meshes are added there instead of the main
+ *  scene. */
+export declare interface UtilityLayer {
+    readonly scene: SceneContext;
+    readonly mainScene: SceneContext;
+}
+
+export declare interface UtilityLayerOptions {
+    /** Add a built-in hemispheric light so gizmo materials are visible without
+     *  the caller adding one. Defaults to true. */
+    addDefaultLight?: boolean;
+    /** Default light intensity when `addDefaultLight` is true. Defaults to 1.0. */
+    lightIntensity?: number;
+}
+
 /** Per-mesh original + variant material entry. */
 declare interface VariantMeshEntry {
     mesh: Mesh;
@@ -4593,6 +6913,75 @@ declare interface VariantMeshEntry {
 
 declare interface Varying {
 
+/** Result of baking — the GPU texture plus a per-clip row map for choosing playback params. */
+export declare interface VatBakeResult {
+    readonly texture: GPUTexture;
+    readonly boneCount: number;
+    readonly frameCount: number;
+    /** Clip name → row range, for building the per-mesh/per-instance (fromRow,toRow,offset,fps) params. */
+    readonly clips: Record<string, VatClip>;
+}
+
+/** Where one clip landed in the baked texture: its first row, its frame count, and its native fps. */
+export declare interface VatClip {
+    readonly fromRow: number;
+    readonly frameCount: number;
+    readonly fps: number;
+}
+
+/** VAT (Vertex Animation Texture) GPU data — BAKED skinning. Attached to `mesh.vat` by vat/vat-baker.ts.
+ *  The skeletal animation is pre-evaluated into `texture` (one frame per row); the shader reads bone
+ *  matrices from the current frame's row instead of a live per-frame upload, so the mesh thin-instances.
+ *  Reuses the same joints/weights vertex-buffer field names as SkeletonData so the renderable binds either. */
+declare interface VatData {
+    readonly boneCount: number;
+    /** Baked bone-matrix texture: rgba32float, (boneCount*4) × frameCount, one animation frame per row
+     *  (identical per-row layout to the live bone texture in skeleton/create-skeleton.ts). */
+    readonly texture: GPUTexture;
+    readonly frameCount: number;
+    /** UBO consumed by the VAT vertex fragment: `params` vec4 = (fromRow, toRow, frameOffset, fps);
+     *  `clock` vec4 .x = elapsed seconds. Advanced by the VAT manager (vat/vat-baker.ts). */
+    readonly settingsBuffer: GPUBuffer;
+    readonly jointsBuffer: GPUBuffer;
+    readonly weightsBuffer: GPUBuffer;
+    readonly joints1Buffer: GPUBuffer | null;
+    readonly weights1Buffer: GPUBuffer | null;
+    /** Optional per-instance VAT params texture (rgba32float, (2*instanceCount) x 1): TWO texels per
+     *  thin-instance — A=(fromRow,toRow,offset,fps), B=(fromRow,toRow,blend,fps) — so each instance plays
+     *  its own clip + phase (and can blend two clips) from the one shared baked texture. Present + the mesh
+     *  thin-instanced ⇒ the VAT vertex path reads its frame rows from this texture indexed by
+     *  `@builtin(instance_index)` instead of the shared settings UBO. Set via the VatHandle. */
+    instanceTexture?: GPUTexture | null;
+}
+
+/** Runtime VAT playback handle for one mesh (the analogue of BJS BakedVertexAnimationManager + the
+ *  per-mesh settings). Advance `update()` each frame; set the active clip with `play()`. */
+export declare interface VatHandle {
+    /** The mesh this drives (its `mesh.vat` is set). */
+    readonly mesh: Mesh;
+    /** Baked clip row map. */
+    readonly clips: Record<string, VatClip>;
+    /** Select the clip to play (by name) or set explicit playback params. */
+    play(clip: string, opts?: {
+        offset?: number;
+        fps?: number;
+    }): void;
+    /** Advance the animation clock by `dtSeconds` and upload it. */
+    update(dtSeconds: number): void;
+    /** Enable/refresh PER-INSTANCE VAT: upload one vec4 (fromRow, toRow, timeOffset, fps) per thin-instance,
+     *  so every instance plays its own clip + phase from the one shared baked texture (all instances in a
+     *  single draw call). `params.length` must be `4 * instanceCount`. Call this BEFORE registerScene the
+     *  first time — it sets `mesh.vat.instanceTexture`; a VAT mesh that is thin-instanced then takes the
+     *  per-instance vertex path. Later calls re-upload in place. Use `clips` to look up each clip's
+     *  fromRow/toRow/fps when building `params`. (Internally expanded to the dual-clip layout, blend 0.) */
+    setInstances(params: Float32Array): void;
+    /** PER-INSTANCE DUAL-CLIP VAT: like setInstances, but each instance carries TWO clips that are blended,
+     *  so gait cross-fades stay smooth. `params.length` must be `8 * instanceCount` — two vec4s per instance:
+     *  A = (fromRowA, toRowA, timeOffset, fpsA), B = (fromRowB, toRowB, blendWeight, fpsB), where blendWeight
+     *  in [0,1] lerps A→B and B reuses A's timeOffset. Same per-instance VAT path as setInstances. */
+    setInstancesBlend(params: Float32Array): void;
+}
+
 /** 3-component vector (position, direction, color) */
 export declare interface Vec3 {
     x: number;