@babylonjs/lite 0.2.0 → 1.0.1

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;
 
@@ -85,6 +88,27 @@ export declare function addFacingBillboardSystem(scene: SceneContext, system: Fa
  *  (compute / copy / object-list) needs the same surface. */
 export declare function addPassDependencies(pass: Pass, deps: RenderTarget | readonly RenderTarget[]): void;
 
+/**
+ * Adds a child shape to a container shape with an explicit local transform.
+ * @param world - The physics world.
+ * @param container - Parent container shape.
+ * @param child - Child shape to append.
+ * @param translation - Child translation in container space.
+ * @param rotation - Child rotation in container space.
+ * @param scale - Child scale in container space.
+ */
+export declare function addPhysicsShapeChild(world: PhysicsWorld, container: PhysicsShape, child: PhysicsShape, translation?: Vec3, rotation?: Quat, scale?: Vec3): void;
+
+/**
+ * Adds a child shape to a container, deriving its local transform from two scene nodes.
+ * @param world - The physics world.
+ * @param container - Parent container shape.
+ * @param parentNode - Scene node associated with the container shape.
+ * @param child - Child shape to append.
+ * @param childNode - Scene node associated with the child shape.
+ */
+export declare function addPhysicsShapeChildFromParent(world: PhysicsWorld, container: PhysicsShape, parentNode: SceneNode, child: PhysicsShape, childNode: SceneNode): void;
+
 /** Create a `RenderPass`, wire it to the task currently recording, and return
  *  it. Must be called from inside `Task.record()` so the FG can associate the
  *  new pass with the right task (mirrors BJS `frameGraph.addRenderPass`).
@@ -129,6 +153,11 @@ 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;
 
@@ -319,6 +348,53 @@ 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[];
+
+/**
+ * Applies a force for one fixed physics timestep, matching Babylon.js PhysicsBody.applyForce.
+ * @param world - The physics world.
+ * @param body - The physics body to update.
+ * @param force - Force vector.
+ * @param location - World-space application point.
+ */
+export declare function applyPhysicsBodyForce(world: PhysicsWorld, body: PhysicsBody, force: Vec3, location: Vec3): void;
+
+/**
+ * Applies a world-space impulse to a physics body.
+ * @param body - The physics body to update.
+ * @param impulse - Impulse vector.
+ * @param location - World-space application point.
+ */
+export declare function applyPhysicsBodyImpulse(body: PhysicsBody, impulse: Vec3, location: Vec3): void;
+
+/**
+ * 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.
@@ -408,6 +484,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:
@@ -426,7 +512,34 @@ export declare interface AssetContainer {
  * 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.
@@ -442,6 +555,38 @@ 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).
+ *  - Touch: single-finger drag = pan; two-finger pinch = zoom toward the centroid,
+ *    promoting to a pan once the centroid drifts ≥ 20 px.
+ *  - Keyboard: arrows = pan, Ctrl+arrows = tilt (pitch/yaw), +/- = zoom along the look vector.
+ *
+ * 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.
@@ -460,9 +605,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.
@@ -478,6 +690,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
@@ -637,6 +860,27 @@ 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).
@@ -655,6 +899,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;
 
@@ -667,6 +935,71 @@ export declare const CAP_NONE = 0;
 /** Cap mode: close only the start of the tube/extrusion. */
 export declare const CAP_START = 1;
 
+/**
+ * CreateCapsule — matches Babylon.js MeshBuilder.CreateCapsule default options.
+ *
+ * Generates a capsule (a cylinder capped by two hemispheres) or a "pill" when
+ * `radiusTop`/`radiusBottom` differ. Vertex/normal/UV generation and index
+ * winding are ported verbatim from `@babylonjs/core/Meshes/Builders/capsuleBuilder.js`
+ * to guarantee parity. The default Y-up orientation is used (the `orientation`
+ * remap of the Babylon builder is intentionally omitted to keep the API small).
+ */
+/** Geometry buffers produced by {@link createCapsuleData}. */
+export declare interface CapsuleData {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+
+/** Options for `createCapsuleData`. Subset of Babylon's CreateCapsule. */
+export declare interface CapsuleOptions {
+    /** Total height of the capsule including both caps. Default 1. */
+    height?: number;
+    /** Radius of the cylindrical body and both caps. Default 0.25. */
+    radius?: number;
+    /** Radius of the top cap; defaults to `radius`. */
+    radiusTop?: number;
+    /** Radius of the bottom cap; defaults to `radius`. */
+    radiusBottom?: number;
+    /** Number of radial segments around the capsule. Default 16. */
+    tessellation?: number;
+    /** Number of height segments along the cylindrical body. Default 2. */
+    subdivisions?: number;
+    /** Number of segments per cap; defaults applied to both caps. Default 6. */
+    capSubdivisions?: number;
+    /** Number of segments for the top cap; defaults to `capSubdivisions`. */
+    topCapSubdivisions?: number;
+    /** Number of segments for the bottom cap; defaults to `capSubdivisions`. */
+    bottomCapSubdivisions?: number;
+}
+
+/**
+ * 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;
@@ -683,6 +1016,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;
 
@@ -717,6 +1101,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;
 
@@ -798,9 +1185,80 @@ export declare interface ClusteredPointLightOptions {
     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`.
@@ -834,6 +1292,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.
@@ -844,6 +1306,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.
@@ -877,9 +1341,38 @@ 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 capsule (cylinder capped by two hemispheres) mesh. Caller must assign material. */
+export declare function createCapsule(engine: EngineContext, options?: CapsuleOptions): Mesh;
+
+/**
+ * Build capsule geometry data.
+ * @param options - Capsule dimensions and tessellation.
+ * @returns Positions, normals, UVs, and indices for the capsule mesh.
+ */
+export declare function createCapsuleData(options?: CapsuleOptions): CapsuleData;
+
 /**
  * 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.
@@ -889,6 +1382,19 @@ 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
@@ -909,6 +1415,8 @@ export declare function createClusteredLightContainer(options?: ClusteredLightCo
  */
 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.
@@ -944,6 +1452,8 @@ export declare function createCsmDirectionalShadowGenerator(engine: EngineContex
 /** Create a cylinder (or cone / truncated cone / prism) mesh. Caller must assign material. */
 export declare function createCylinder(engine: EngineContext, options?: CylinderOptions): Mesh;
 
+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
@@ -964,6 +1474,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.
@@ -983,7 +1515,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`.
@@ -1003,9 +1535,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>;
 
 /**
@@ -1038,12 +1576,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;
 
@@ -1080,9 +1638,21 @@ 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;
 
+/**
+ * Create a Havok heightfield collision shape. Attach it to a STATIC body bound to the
+ * ground mesh so the heightfield aligns with the visible terrain.
+ * @param world - The physics world.
+ * @param options - Ground mesh source or explicit heightfield parameters.
+ * @returns The created shape handle.
+ */
+export declare function createHeightFieldShape(world: PhysicsWorld, options: HeightFieldShapeOptions): PhysicsShape;
+
 /** Create a hemispheric light. Returns plain data — caller adds to scene.
  *  Matches Babylon.js HemisphericLight behavior. */
 export declare function createHemisphericLight(direction?: [number, number, number], intensity?: number): HemisphericLight;
@@ -1097,6 +1667,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
@@ -1176,6 +1751,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;
 
@@ -1209,7 +1789,7 @@ export declare function createPcfSpotlightShadowGenerator(engine: EngineContext,
 /**
  * Create a physics aggregate: body + shape + material wired together.
  * `mass === 0` → STATIC, `mass > 0` → DYNAMIC.
- * Shape geometry is auto-sized from the mesh bounding box when not specified.
+ * Primitive shape geometry is auto-sized from the mesh bounding box when not specified.
  */
 export declare function createPhysicsAggregate(world: PhysicsWorld, node: Mesh, type: PhysicsShapeType, options: PhysicsAggregateOptions): PhysicsAggregate;
 
@@ -1224,16 +1804,38 @@ export declare function createPhysicsAggregate(world: PhysicsWorld, node: Mesh,
 export declare function createPhysicsBody(world: PhysicsWorld, node: SceneNode, motionType: PhysicsMotionType, startsAsleep?: boolean): PhysicsBody;
 
 /**
- * Creates a collision shape (sphere, box, capsule, or cylinder) from the given options.
+ * Creates and enables a Havok constraint between two physics bodies.
+ * @param world - The physics world.
+ * @param bodyA - Parent body.
+ * @param bodyB - Child body.
+ * @param type - Constraint type.
+ * @param options - Pivot and axis options.
+ * @param limits - Optional 6DoF limits.
+ */
+export declare function createPhysicsConstraint(world: PhysicsWorld, bodyA: PhysicsBody, bodyB: PhysicsBody, type: PhysicsConstraintType, options?: PhysicsConstraintOptions, limits?: readonly PhysicsConstraintLimit[]): PhysicsConstraint;
+
+/**
+ * Creates a collision shape from the given options.
  * @param world - The physics world.
  * @param options - The shape type and its geometry parameters.
  * @returns The created shape handle.
  */
 export declare function createPhysicsShape(world: PhysicsWorld, options: PhysicsShapeOptions): PhysicsShape;
 
+/** Creates a tree-shakable Physics V2 debug viewer for a scene/world pair. */
+export declare function createPhysicsViewer(scene: SceneContext, world: PhysicsWorld, options?: PhysicsViewerOptions): PhysicsViewer;
+
 /** 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.
@@ -1245,6 +1847,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.
@@ -1304,11 +1911,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.
@@ -1316,6 +1945,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).
@@ -1364,7 +2009,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;
 
@@ -1381,8 +2030,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;
@@ -1391,6 +2043,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.
  *
@@ -1441,6 +2119,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;
 
@@ -1513,6 +2199,15 @@ export declare interface CsmDirectionalShadowGeneratorConfig {
     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). */
@@ -1520,6 +2215,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;
@@ -1530,6 +2245,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;
@@ -1547,32 +2325,63 @@ 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.
  */
 export declare function disposePhysics(world: PhysicsWorld): void;
 
+/** Disposes all physics debug meshes and unregisters the viewer update hook. */
+export declare function disposePhysicsViewer(viewer: PhysicsViewer): 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;
 
@@ -1591,9 +2400,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)`.
  *
@@ -1708,6 +2537,23 @@ 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`.
  *
@@ -1747,16 +2593,28 @@ 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;
-    /**
+    /** GPU time spent on the last measured frame, in milliseconds — 0 until the first measured frame and
+     *  while GPU timing is disabled (the default). Enable with {@link setGpuTimingEnabled}; query device
+     *  capability with {@link isGpuTimingSupported}. Updates a frame or two behind, since the timestamp
+     *  readback is async and off the render critical path, so reading it does not perturb the value. */
+    gpuFrameTimeMs: number;
    /**
      * When true, world matrices are computed using Float64 intermediate precision
      * and downcast to Float32 at GPU upload time. Defaults to false.
      */
@@ -1771,27 +2629,21 @@ export declare interface EngineContext {
      * dynamically imported during `createEngine` only when this flag is true,
      * so non-LWR engines never pull the module into their bundle.
      */
-    useFloatingOrigin: boolean;
-    /** Clamps the effective device pixel ratio used for the swapchain backing store.
-     *  The backing store is sized at `min(devicePixelRatio, maxDevicePixelRatio) * cssPixels`.
-     *  `maxDevicePixelRatio = 1` renders at native CSS-pixel resolution (no DPR upscaling);
-     *  the default `Infinity` is unclamped (full devicePixelRatio). Mutable at runtime — set
-     *  before the next `resizeEngine` to take effect (mirrors `setHardwareScalingRatio`). */
-    maxDevicePixelRatio: number;
+    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>;
     /**
      * Enable Float64 intermediate precision for world matrix computations. Defaults to false.
      */
@@ -1807,14 +2659,6 @@ export declare interface EngineOptions {
      * pattern as the F64 storage module).
      */
     useFloatingOrigin?: boolean;
-    /**
-     * Clamps the effective device pixel ratio used for the swapchain backing store.
-     * The backing store is sized at `min(devicePixelRatio, maxDevicePixelRatio) * cssPixels`.
-     * `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`.
-     */
-    maxDevicePixelRatio?: number;
 }
 
 /** GPU-resident environment textures. */
@@ -1861,6 +2705,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;
@@ -1909,6 +2758,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;
@@ -1918,6 +2778,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;
@@ -1930,7 +2795,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;
 }
@@ -1988,6 +2854,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;
 
@@ -2014,6 +3125,14 @@ 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
@@ -2026,12 +3145,21 @@ 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.
@@ -2066,6 +3194,9 @@ export declare function getPickedUV(info: PickingInfo): [number, number] | null;
 /** Compute the projection matrix for a camera. Cached per worldMatrixVersion + aspect. */
 export declare function getProjectionMatrix(camera: Camera, aspectRatio: number): Mat4;
 
+/** Return the latest task GPU timing snapshot without stalling the GPU or CPU. */
+export declare function getRenderTaskGpuTimings(engine: EngineContext): RenderTaskGpuTimings;
+
 /**
  * Resolves the current instance index of the sprite referenced by `handle`.
  * @param handle - Handle of the sprite to resolve.
@@ -2098,6 +3229,21 @@ 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[];
@@ -2115,6 +3261,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;
 
@@ -2237,6 +3438,27 @@ declare interface HdrLoadOptions {
     skyboxSize?: number;
 }
 
+/** Options for {@link createHeightFieldShape}. */
+export declare interface HeightFieldShapeOptions {
+    /**
+     * Ground mesh whose world-space vertex grid defines the heightfield. When set, the
+     * sample count, world size, and height data are derived from the mesh (the explicit
+     * fields below are ignored). The mesh must be a regular `(N+1)×(N+1)` grid such as the
+     * one produced by `createGroundFromHeightMap`.
+     */
+    groundMesh?: Mesh;
+    /** Explicit: number of height samples along X. */
+    numHeightFieldSamplesX?: number;
+    /** Explicit: number of height samples along Z. */
+    numHeightFieldSamplesZ?: number;
+    /** Explicit: world-space size along X. */
+    heightFieldSizeX?: number;
+    /** Explicit: world-space size along Z. */
+    heightFieldSizeZ?: number;
+    /** Explicit: row-major height samples (`numHeightFieldSamplesX * numHeightFieldSamplesZ`). */
+    heightFieldData?: Float32Array;
+}
+
 export declare interface HemisphericLight extends LightBase {
     readonly lightType: "hemispheric";
     direction: ObservableVec3;
@@ -2246,6 +3468,9 @@ export declare interface HemisphericLight extends LightBase {
     groundColor: [number, number, number];
 }
 
+/** Hides a body that was previously shown with {@link showPhysicsBody}. */
+export declare function hidePhysicsBody(viewer: PhysicsViewer, body: PhysicsBody): boolean;
+
 /** Image processing configuration. */
 export declare interface ImageProcessingConfig {
     exposure: number;
@@ -2269,6 +3494,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 {
@@ -2302,6 +3534,34 @@ 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;
+
+/** Whether GPU frame-time measurement is available on this engine's device — i.e. the adapter offered
+ *  the WebGPU `timestamp-query` feature (requested opportunistically by {@link createEngine}). When false,
+ *  {@link setGpuTimingEnabled} is a no-op and {@link EngineContext.gpuFrameTimeMs} stays 0. */
+export declare function isGpuTimingSupported(engine: EngineContext): boolean;
+
+/** Whether per-render-task GPU timing can run on this engine's WebGPU device. */
+export declare function isRenderTaskGpuTimingSupported(engine: EngineContext): boolean;
+
 /**
  * Returns `true` if the sprite referenced by `handle` is still present in its layer.
  * @param handle - Handle to test.
@@ -2333,6 +3593,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). */
@@ -2343,6 +3616,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. */
@@ -2417,6 +3693,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.
@@ -2455,6 +3734,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.
  *
@@ -2600,7 +3887,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;
 
@@ -2625,6 +3917,9 @@ 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.
@@ -2637,7 +3932,12 @@ export declare interface Mesh extends SceneNode {
      *  (`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;
+    /** Optional per-mesh GPU-picking clip volumes. Fragments inside any volume are ignored by the GPU picker. */
+    pickingClipVolumes?: readonly PickingClipVolume[] | null;
 
 /** Opaque GPU geometry handle (user never touches these). */
 export declare interface MeshGPU {
@@ -2720,6 +4020,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;
@@ -2810,8 +4116,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. */
@@ -2927,6 +4232,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.
@@ -3029,10 +4337,24 @@ export declare function onBeforeRender(scene: SceneContext, cb: (deltaMs: number
  */
 export declare function onCsmReceiverUpdate(sg: ShadowGenerator, cb: (data: Float32Array) => void): () => void;
 
+/**
+ * Registers a callback to run after each physics step, once dynamic body transforms have been
+ * synced back to their nodes and before the frame is rendered. Use this for per-step logic that
+ * must observe (or react to) the freshly-integrated state — e.g. tracking a marker to a body's
+ * post-step pose, or applying a force whose effect should integrate on the next step.
+ * @param world - The physics world to hook.
+ * @param cb - Callback invoked with the world timestep (seconds) after each step.
+ */
+export declare function onPhysicsAfterStep(world: PhysicsWorld, cb: (timestep: number) => 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.
@@ -3226,11 +4548,89 @@ export declare interface PhysicsAggregateOptions {
     center?: Vec3;
     startAsleep?: boolean;
     isTriggerShape?: boolean;
+    /**
+     * Optional pre-built shape. When provided, it is used directly and the
+     * primitive-shape build path is skipped. This lets callers supply
+     * mesh/convex-hull shapes (built via `createPhysicsShape`) without pulling
+     * the mesh-shape code into `createPhysicsAggregate` itself.
+     */
+    shape?: PhysicsShape;
 }
 
 /** 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;
+
+/** Opaque handle to a Havok constraint between two bodies. */
+export declare interface PhysicsConstraint {
    readonly bodyA: PhysicsBody;
+    readonly bodyB: PhysicsBody;
+    readonly type: PhysicsConstraintType;
+    readonly options: PhysicsConstraintOptions;
+    readonly limits?: readonly PhysicsConstraintLimit[];
+}
+
+/** Axis addressed by a Physics V2 constraint limit. */
+export declare const enum PhysicsConstraintAxis {
+    LINEAR_X = 0,
+    LINEAR_Y = 1,
+    LINEAR_Z = 2,
+    ANGULAR_X = 3,
+    ANGULAR_Y = 4,
+    ANGULAR_Z = 5,
+    LINEAR_DISTANCE = 6
+}
+
+/** Minimal constraint debug data consumed by the Lite PhysicsViewer. */
+export declare interface PhysicsConstraintDebug {
+    readonly bodyA: PhysicsBody;
+    readonly bodyB: PhysicsBody;
+    readonly pivotA: Vec3;
+    readonly pivotB: Vec3;
+    readonly axisA?: Vec3;
+    readonly axisB?: Vec3;
+    readonly perpAxisA?: Vec3;
+    readonly perpAxisB?: Vec3;
+    readonly type?: number;
+}
+
+/** Limit options used by 6DoF constraints. */
+export declare interface PhysicsConstraintLimit {
+    axis: PhysicsConstraintAxis;
+    minLimit?: number;
+    maxLimit?: number;
+    stiffness?: number;
+    damping?: number;
+}
+
+/** Pivot/axis options used to create a physics constraint. */
+export declare interface PhysicsConstraintOptions {
+    pivotA?: Vec3;
+    pivotB?: Vec3;
+    axisA?: Vec3;
+    axisB?: Vec3;
+    perpAxisA?: Vec3;
+    perpAxisB?: Vec3;
+    maxDistance?: number;
+    collision?: boolean;
+}
+
+/** Type of Havok Physics V2 constraint. */
+export declare const enum PhysicsConstraintType {
+    BALL_AND_SOCKET = 1,
+    DISTANCE = 2,
+    HINGE = 3,
+    SLIDER = 4,
+    LOCK = 5,
+    PRISMATIC = 6,
+    SIX_DOF = 7
+}
+
+/** Mass properties applied to a physics body. Omitted fields keep Havok's shape-derived values. */
+export declare interface PhysicsMassProperties {
+    centerOfMass?: Vec3;
+    mass?: number;
+    inertia?: Vec3;
+    inertiaOrientation?: Quat;
 }
 
 /** How a body moves: `STATIC` (immovable), `ANIMATED` (driven by the node transform), or `DYNAMIC` (simulated). */
@@ -3247,6 +4647,10 @@ export declare interface PhysicsShape {
 export declare interface PhysicsShapeOptions {
     type: PhysicsShapeType;
     parameters?: PhysicsShapeParameters;
+    /** Mesh or transform hierarchy used when `type` is `MESH` or `CONVEX_HULL`. */
+    mesh?: SceneNode;
+    /** When true, mesh and convex-hull shapes accumulate descendant meshes under `mesh`. */
+    includeChildMeshes?: boolean;
 }
 
 /** Geometry parameters describing a collision shape; which fields apply depends on the shape type. */
@@ -3271,11 +4675,31 @@ export declare const enum PhysicsShapeType {
     HEIGHTFIELD = 7
 }
 
+/** Pure-state handle for Havok Physics V2 debug rendering. */
+export declare interface PhysicsViewer {
+    readonly scene: SceneContext;
+    readonly world: PhysicsWorld;
+
+/** Options used when creating a physics debug viewer. */
+export declare interface PhysicsViewerOptions {
+    /** RGBA debug line color. Defaults to opaque white, matching Babylon.js PhysicsViewer. */
+    color?: readonly [number, number, number, number];
+}
+
 /** Pure-state handle to a Havok physics world: the WASM module, the native world, its bodies, and the timestep. */
 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>;
+
+/** Optional GPU-picking discard volume. The picker clips fragments in a bounded local frame:
+ *  `a=(origin.x, origin.z, tangent.x, tangent.z)`, `b=(baseY, halfWidth, springY, rise)`,
+ *  `c=(ringT, depthHalf, flatFlag, _)`. */
+declare interface PickingClipVolume {
+    readonly a: readonly [number, number, number, number];
+    readonly b: readonly [number, number, number, number];
+    readonly c: readonly [number, number, number, number];
+}
 
 /** Result of a GPU pick operation. */
 export declare interface PickingInfo {
@@ -3298,6 +4722,18 @@ 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;
+    /** Dev-only diagnostics: logs the pick ray, pixel, pick id/depth and resolved mesh. */
+    debugLabel?: string;
+}
+
 /** Sampler and format overrides for `createTexture2DFromPixels()`. */
 export declare interface PixelsTexture2DOptions {
     /** Address mode U. Default 'clamp-to-edge'. */
@@ -3321,6 +4757,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;
@@ -3328,6 +4794,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;
 
@@ -3415,6 +4908,70 @@ export declare interface PluginUboField {
     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;
@@ -3440,6 +4997,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;
 
@@ -3521,6 +5097,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;
@@ -3580,27 +5165,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;
 
@@ -3631,6 +5248,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.
@@ -3657,6 +5284,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;
 
@@ -3686,6 +5315,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
@@ -3700,7 +5331,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. */
@@ -3712,22 +5344,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. */
@@ -3752,38 +5384,132 @@ 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;
     /** Use canvas dimensions, not render-target dimensions, for this pass's scene UBO aspect. */
     cs?: boolean;
     /** Scene-texture transmission settings. `copyCount: 0` copies before every transmissive draw.
-     *  `generateMipmaps: false` allocates only mip 0 for the refraction texture and skips mip generation. */
+     *  `generateMipmaps: false` allocates only mip 0 for the refraction texture and skips mip generation.
+     *  `mipLevelCount` caps the generated chain when a material only samples low explicit LODs. */
     transmission?: {
         copyCount?: number;
         generateMipmaps?: boolean;
+        mipLevelCount?: number;
     };
 }
 
+/** GPU time measured for one frame-graph task in one rendered frame. */
+export declare interface RenderTaskGpuTiming {
+    /** Execution-order index within the measured frame. Useful when several tasks share the same name. */
+    readonly index: number;
+    /** The task's existing frame-graph label (`Task.name`, e.g. `"shadow"`, `"scene"`, `"post-process"`). */
+    readonly name: string;
+    /** GPU duration for this task in milliseconds. */
+    readonly durationMs: number;
+}
+
+/** Latest per-task GPU timing snapshot for an engine. */
+export declare interface RenderTaskGpuTimings {
+    /** `unsupported` when the WebGPU device lacks `timestamp-query`; `pending` until the first readback lands. */
+    readonly status: RenderTaskGpuTimingStatus;
+    /** Whether this engine's device exposes WebGPU timestamp queries. */
+    readonly supported: boolean;
+    /** Whether task timing is currently enabled and recording future frames. */
+    readonly enabled: boolean;
+    /** Monotonic profiler frame index for the snapshot. `0` means no measured frame has completed yet. */
+    readonly frameIndex: number;
+    /** Measured tasks in frame execution order. Empty until `status === "available"`. */
+    readonly tasks: readonly RenderTaskGpuTiming[];
+    /** Number of tasks skipped in that frame because the profiler's query-set capacity was exceeded. */
+    readonly droppedTaskCount: number;
+    /** Readback failure message when `status === "error"`. */
+    readonly error?: string;
+}
+
+/** Availability / lifecycle state for per-frame-graph-task GPU timings. */
+export declare type RenderTaskGpuTimingStatus = "unsupported" | "disabled" | "pending" | "available" | "error";
+
+/** 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;
@@ -3796,6 +5522,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 {
@@ -3816,7 +5567,12 @@ export declare interface SceneColorGrab {
 
 /** 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[];
@@ -3867,6 +5623,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.
  *
@@ -3969,11 +5748,10 @@ 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;
 
 /**
@@ -3987,6 +5765,27 @@ export declare function setEngineSize(engine: EngineContext, widthPx: number, he
  */
 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;
+
+/** Enable or disable per-frame GPU timing. Disabled by default and a no-op on devices where
+ *  {@link isGpuTimingSupported} is false. While on, {@link EngineContext.gpuFrameTimeMs} is updated each
+ *  frame with the measured GPU time — the time the GPU spends on that frame's work, not CPU/wall-clock
+ *  time — a frame or two behind via an async, non-blocking readback.
+ *
+ *  Implementation: the timer module is dynamic-imported on the first enable, so engines that never call
+ *  this ship none of it. Once loaded, three tiny per-frame hooks are installed on the engine; while timing
+ *  is off they are undefined and {@link renderFrame} only optional-chains them (a no-op short-circuit), so
+ *  scenes that never enable timing pay effectively nothing. The opening/closing timestamps are written into
+ *  the frame's command encoder so the GPU runs them contiguously around just that frame's passes. The first
+ *  enable takes effect a microtask later (the GPU resources are created lazily, then reused); subsequent
+ *  toggles are synchronous. */
+export declare function setGpuTimingEnabled(engine: EngineContext, enabled: boolean): void;
+
+/** Override the URL of the KTX2/Basis decoder script (and, optionally, the URLs of the WASM/JS transcoder
+ *  modules it pulls). Call before the first KHR_texture_basisu texture loads. */
+export declare function setKtx2DecoderUrl(url: string, wasmUrls?: Record<string, Record<string, string>>): 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. */
@@ -4011,13 +5810,48 @@ 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;
+
+/**
+ * Sets a body's mass properties, preserving Havok's shape-derived values for omitted fields.
+ * @param world - The physics world.
+ * @param body - The body to update.
+ * @param properties - Mass-property overrides.
+ */
+export declare function setPhysicsBodyMassProperties(world: PhysicsWorld, body: PhysicsBody, properties: PhysicsMassProperties): 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 setPhysicsBodyMotionType(world: PhysicsWorld, body: PhysicsBody, motionType: PhysicsMotionType): void;
+
+/**
+ * Enable or disable pre-step synchronization from a node transform to its Havok body.
+ * @param body - The physics body to update.
+ * @param enabled - When true, the node transform is written to Havok before each physics step.
  */
-export declare function setPhysicsBodyMass(world: PhysicsWorld, body: PhysicsBody, mass: number): void;
+export declare function setPhysicsBodyPreStep(body: PhysicsBody, enabled: boolean): void;
 
 /**
  * Assigns a collision shape to a body.
@@ -4028,11 +5862,36 @@ 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, worldPosition?: Vec3): void;
+
+/**
+ * Sets the Havok filter collide mask for a collision shape.
+ * @param world - The physics world.
+ * @param shape - The shape to update.
+ * @param collideMask - Bitmask describing which collision groups this shape collides with.
  */
-export declare function setPhysicsGravity(world: PhysicsWorld, gravity: Vec3): void;
+export declare function setPhysicsShapeFilterCollideMask(world: PhysicsWorld, shape: PhysicsShape, collideMask: number): void;
+
+/**
+ * Sets the Havok filter membership mask for a collision shape.
+ * @param world - The physics world.
+ * @param shape - The shape to update.
+ * @param membershipMask - Bitmask describing which collision group this shape belongs to.
+ */
+export declare function setPhysicsShapeFilterMembershipMask(world: PhysicsWorld, shape: PhysicsShape, membershipMask: number): void;
 
 /**
  * Sets a shape's surface material properties.
@@ -4058,6 +5917,23 @@ 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;
+
+/** Enable or disable per-frame-graph-task GPU timing.
+ *
+ * The profiling implementation is loaded with a dynamic import on first enable. Engines that never call this
+ * function do not fetch the profiler chunk or carry task-timing code in the always-fetched frame graph.
+ * The returned snapshot is `unsupported` if the device lacks WebGPU `timestamp-query`, `pending` immediately
+ * after enable, and `available` once a later frame's async timestamp readback completes.
+ */
+export declare function setRenderTaskGpuTimingEnabled(engine: EngineContext, enabled: boolean): Promise<RenderTaskGpuTimings>;
+
+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;
 
@@ -4067,6 +5943,9 @@ export declare function setShaderFloat(material: ShaderMaterial, name: string, v
  *  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) a declared read-only storage buffer. */
+export declare function setShaderStorageBuffer(material: ShaderMaterial, name: string, buffer: GPUBuffer | null): void;
+
 /** Bind (or clear) the texture for a declared sampler, enforcing that depth and
  *  non-depth samplers receive a matching `Texture2D`.
  *  @param material - Target material.
@@ -4121,6 +6000,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
@@ -4129,9 +6020,34 @@ 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;
 
@@ -4170,6 +6086,7 @@ export declare interface ShaderMaterial extends Material {
     readonly attributes: readonly ShaderAttributeName[];
     readonly uniformDecls: readonly ShaderUniformDecl[];
     readonly samplerDecls: readonly ShaderSamplerDecl[];
+    readonly storageBufferDecls: readonly ShaderStorageBufferDecl[];
     readonly defines: readonly ShaderDefine[];
     readonly needAlphaBlending: boolean;
     readonly blendMode: "alpha" | "additive";
@@ -4178,7 +6095,10 @@ export declare interface ShaderMaterial extends Material {
     readonly needAlphaTesting: boolean;
     readonly backFaceCulling: boolean;
     readonly depthWrite: boolean;
-    readonly depthCompare: GPUCompareFunction;
+    readonly depthCompare: GPUCompareFunction;
+    readonly depthOnlyFragment: boolean;
+    readonly depthBias: number;
+    readonly depthBiasSlopeScale: number;
 
 /** Options describing a ShaderMaterial: WGSL sources, attributes, uniforms,
  *  samplers, defines, and blend/depth state. Passed to `createShaderMaterial()`. */
@@ -4189,6 +6109,7 @@ export declare interface ShaderMaterialOptions {
     readonly attributes: readonly ShaderAttributeName[];
     readonly uniforms?: readonly ShaderUniformOption[];
     readonly samplers?: readonly ShaderSamplerOption[];
+    readonly storageBuffers?: readonly ShaderStorageBufferOption[];
     readonly defines?: ShaderDefineMap;
     readonly needAlphaBlending?: boolean;
     /** Blend equation used when `needAlphaBlending` is set. "alpha" (default) is
@@ -4206,6 +6127,32 @@ export declare interface ShaderMaterialOptions {
     readonly backFaceCulling?: boolean;
     readonly depthWrite?: boolean;
     readonly depthCompare?: GPUCompareFunction;
+    /** Compile/run the fragment stage even for depth-only render targets (no colour attachments).
+     *  Use for depth-only casters that need `discard` (alpha/clip masks). The fragment shader must not
+     *  declare colour outputs when drawn into a depth-only target. Default false. */
+    readonly depthOnlyFragment?: boolean;
+    /** 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. */
@@ -4223,6 +6170,15 @@ export declare interface ShaderSamplerDecl {
 /** A sampler entry: either a bare sampler name or an explicit declaration. */
 export declare type ShaderSamplerOption = string | ShaderSamplerDecl;
 
+/** A storage buffer declaration. `type` is the WGSL variable type, e.g. `array<vec4<f32>>`. */
+declare interface ShaderStorageBufferDecl {
+    readonly name: string;
+    readonly type: string;
+}
+
+/** A storage-buffer entry: a read-only WGSL storage binding declaration. */
+declare type ShaderStorageBufferOption = ShaderStorageBufferDecl;
+
 /** Built-in uniform names automatically populated by the renderer each frame
  *  (transforms, camera position, screen size, alpha cutoff). */
 export declare type ShaderSystemUniformName = "world" | "view" | "projection" | "viewProjection" | "worldView" | "worldViewProjection" | "cameraPosition" | "screenSize" | "alphaCutoff";
@@ -4251,6 +6207,91 @@ export declare interface ShadowTask extends Task {
     readonly name: "shadow";
 }
 
+/**
+ * Sweep a shape from `startPosition` to `endPosition` (orientation fixed) and return the
+ * first body it hits.
+ *
+ * `hitPoint` is the world-space contact point on the hit body; `fraction` is where along
+ * the sweep contact first occurs. Run at least one physics step first so the broadphase exists.
+ * @param world - The physics world to query.
+ * @param query - Swept shape, orientation, and start/end positions.
+ * @returns The cast result; `hasHit` is `false` when the sweep clears every body.
+ */
+export declare function shapeCast(world: PhysicsWorld, query: ShapeCastQuery): ShapeCastResult;
+
+/** Query parameters for {@link shapeCast}. */
+export declare interface ShapeCastQuery {
+    /** Shape to sweep through the world. */
+    shape: PhysicsShape;
+    /** World-space orientation held constant during the sweep. */
+    rotation: Quat;
+    /** World-space sweep start position. */
+    startPosition: Vec3;
+    /** World-space sweep end position. */
+    endPosition: Vec3;
+    /** Whether trigger volumes count as hits. Default `false`. */
+    shouldHitTriggers?: boolean;
+}
+
+/** Result of a {@link shapeCast} query. */
+export declare interface ShapeCastResult {
+    /** Whether the swept shape hit a body. */
+    hasHit: boolean;
+    /** Fraction along the sweep (`startPosition`→`endPosition`) where contact first occurs. */
+    fraction: number;
+    /** Contact point on the swept shape (query-shape space). */
+    inputHitPoint: Vec3;
+    /** Contact point on the hit body (world space). */
+    hitPoint: Vec3;
+    /** Surface normal at the swept-shape contact. */
+    inputHitNormal: Vec3;
+    /** Surface normal at the hit-body contact. */
+    hitNormal: Vec3;
+}
+
+/**
+ * Find the closest point between a query shape and the nearest body in the world.
+ *
+ * The query shape is positioned at `position`/`rotation` and tested against the world's
+ * broadphase. When a body is found within `maxDistance`, `inputHitPoint` is the closest
+ * point on the query shape and `hitPoint` is the closest point on the hit body (world
+ * space). Run at least one physics step first so the broadphase exists.
+ * @param world - The physics world to query.
+ * @param query - Query shape, transform, and search distance.
+ * @returns The proximity result; `hasHit` is `false` when nothing is within range.
+ */
+export declare function shapeProximity(world: PhysicsWorld, query: ShapeProximityQuery): ShapeProximityResult;
+
+/** Query parameters for {@link shapeProximity}. */
+export declare interface ShapeProximityQuery {
+    /** Shape to test for proximity. */
+    shape: PhysicsShape;
+    /** World-space position of the query shape. */
+    position: Vec3;
+    /** World-space orientation of the query shape. */
+    rotation: Quat;
+    /** Maximum distance to search for a nearby body. */
+    maxDistance: number;
+    /** Whether trigger volumes count as hits. Default `false`. */
+    shouldHitTriggers?: boolean;
+}
+
+/** Result of a {@link shapeProximity} query. */
+export declare interface ShapeProximityResult {
+    /** Whether a body was found within `maxDistance`. */
+    hasHit: boolean;
+    /** Distance between the closest points. */
+    distance: number;
+    /** Closest point on the query shape (query-shape local space in a zero-offset world). */
+    inputHitPoint: Vec3;
+    /** Closest point on the hit body (world space). */
+    hitPoint: Vec3;
+    /** Surface normal at the query-shape closest point. */
+    inputHitNormal: Vec3;
+    /** Surface normal at the hit-body closest point. */
+    hitNormal: Vec3;
+}
+
 /** Sheen layer properties. Maps to BJS PBRMaterial.sheen sub-object. */
 declare interface SheenProps {
     /** Whether sheen is active. Default false. */
@@ -4270,6 +6311,12 @@ declare interface SheenProps {
     albedoScaling?: boolean;
 }
 
+/** Shows a Havok Physics V2 body as a wireframe debug mesh. */
+export declare function showPhysicsBody(viewer: PhysicsViewer, body: PhysicsBody): Mesh | null;
+
+/** Shows a simplified Physics V2 constraint overlay: local axes (with arrowheads) plus angular-limit disks. */
+export declare function showPhysicsConstraint(viewer: PhysicsViewer, constraint: PhysicsConstraintDebug): Mesh[];
+
 /** Connects a skeleton to its GPU bone texture for per-frame updates. */
 declare interface SkeletonBinding {
     readonly jointNodes: readonly number[];
@@ -4507,15 +6554,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`. */
@@ -4531,6 +6594,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];
 }
 
 /**
@@ -4635,6 +6703,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";
@@ -4770,6 +6841,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. */
@@ -4785,6 +6910,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. */
@@ -4948,6 +7192,14 @@ export declare interface TransmissionOptions {
      *  stack) and just need the opaque scene color exposed to a custom transmissive
      *  `ShaderMaterial`. */
     linear?: boolean;
+    /** Override how many times the scene-colour grab is refreshed per frame. `0` means before every
+     *  transmissive draw; the default is once before the first transmissive draw. */
+    copyCount?: number;
+    /** Set false when the transmissive material never samples the scene-colour grab above mip 0. */
+    generateMipmaps?: boolean;
+    /** Cap the scene-colour grab mip chain. Use this when the material samples explicit low LODs only, so
+     *  unused tiny mips are not regenerated every frame. Ignored when `generateMipmaps` is false. */
+    mipLevelCount?: number;
 }
 
 /** Options for `createTubeData`: a circular cross-section swept along a path. */
@@ -4990,18 +7242,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;
@@ -5023,6 +7278,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).
@@ -5030,6 +7307,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;
 
@@ -5055,6 +7350,8 @@ 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.
  *
@@ -5072,6 +7369,22 @@ export declare function updateSpriteAnimationManager(manager: SpriteAnimationMan
  */
 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;
@@ -5080,6 +7393,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;