minerender 2.1.0-beta.2 → 2.1.0-beta.4

package/dist/node/index.d.ts

@@ -1,5 +1,5 @@
 import * as three from 'three';
-import { Vector3, PixelFormat, BoxGeometry, Material, ColorRepresentation, MeshBasicMaterial, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Box2, Scene, Object3DEventMap, Texture, Camera, MOUSE, TOUCH, WebGLRenderer, EventDispatcher, Raycaster, Intersection, Group, DataTexture, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
+import { Vector3, PixelFormat, BoxGeometry, Material, ColorRepresentation, MeshBasicMaterial, Mesh, Euler, Vector2, BufferAttribute, Float32BufferAttribute, BufferGeometry, Object3D, Box3, InstancedMesh, PerspectiveCamera, OrthographicCamera, Matrix4, Box2, Scene, Object3DEventMap, ShaderMaterial, Texture, Camera, MOUSE, TOUCH, Controls, WebGLRenderer, EventDispatcher, Raycaster, Intersection, Group, DataTexture, CanvasTexture, InterleavedBufferAttribute, TrianglesDrawModes, Line, Points } from 'three';
 import * as nodeCanvas from 'canvas';
 import { ImageData as ImageData$1, CanvasRenderingContext2D } from 'canvas';
 import { Buffer } from 'buffer';
@@ -11,6 +11,7 @@ export { PLYExporterOptions } from 'three/examples/jsm/exporters/PLYExporter.js'
 import Stats from 'stats.js';
 import { EffectComposer } from 'postprocessing';
 import { LocalStorage } from 'node-persist';
+import { Buffer as Buffer$1 } from 'node:buffer';
 
 /** Advances a texture animation by one tick. Return `false` when its pixels have not changed. */
 interface AnimatorFunction {
@@ -106,6 +107,8 @@ interface EnvProvider {
     /** Read width/height out of encoded image bytes without fully decoding them. */
     imageSize(data: Uint8Array): ImageSizeInfo;
     openCache(name: string, version: number): PersistentCache;
+    /** Optional worker support; returns undefined where unavailable. Only the browser ESM build ships worker files. */
+    createWorker?(name: "section"): Worker | undefined;
 }
 /**
  * Registry holding the active {@link EnvProvider}.
@@ -221,6 +224,7 @@ declare class AssetKey extends BasicAssetKey {
     /** Returns a cache identifier that includes the explicit root or {@link AssetLoader.ROOT}. */
     serialize(): string;
 }
+declare function isResourceLocation(value: unknown): value is string;
 declare function isBasicAssetKey(obj: any): obj is BasicAssetKey;
 declare function isAssetKey(obj: any): obj is AssetKey;
 
@@ -453,12 +457,16 @@ declare class Requests {
 /** Provides pixel and frame access to a canvas-backed image. Simple frame helpers assume a vertical strip of squares. */
 declare class WrappedImage {
     readonly dta: ExtractableImageData;
+    private alpha?;
     constructor(dta: ExtractableImageData);
     get data(): ImageData$1;
     get dataArray(): Uint8ClampedArray;
     get width(): number;
     get height(): number;
     get hasTransparency(): boolean;
+    /** Whether any pixel has partial alpha. Binary alpha renders as cutout, not blended. */
+    get hasTranslucency(): boolean;
+    private getAlpha;
     /** Whether the dimensions form a vertical strip of square frames, without consulting `.mcmeta`. */
     get animated(): boolean;
     get frameWidth(): number;
@@ -501,7 +509,7 @@ declare class ImageLoader {
     static getWrapped(src: string): Promise<WrappedImage>;
 }
 
-/** Vanilla dye colors used by banner and shield textures, as sRGB packed values. */
+/** @deprecated Fixed 1.21.11 palette. Use {@link BannerPatterns.getColors} for the selected version. */
 declare const DYE_COLORS: Readonly<{
     readonly white: 16383998;
     readonly orange: 16351261;
@@ -534,7 +542,9 @@ interface BannerPatternDraw {
 declare class BannerPatterns {
     /** Lists namespaced pattern IDs from the selected namespace's data directory. */
     static getList(namespace?: string, root?: string): Promise<string[]>;
-    /** Returns the named dye's sRGB value, rejecting unknown colors. */
+    /** Loads the selected version's texture dye colors as packed sRGB values. */
+    static getColors(root?: string): Promise<Record<DyeColor, number>>;
+    /** @deprecated Uses the fixed 1.21.11 palette. Use {@link getColors} for versioned colors. */
     static getColor(color: unknown): number;
     /** Resolves the first 16 layers of a `banner_patterns` component, preserving their order. */
     static getLayers(value: unknown, target: "banner" | "shield", root?: string): Promise<BannerPatternDraw[]>;
@@ -560,11 +570,13 @@ interface BlockModel extends Model {
 }
 /** Item preview data, including GUI lighting, tint sources, and supported special renderers. */
 interface ItemModel extends Model {
+    /** Original item ID, retained when resource packs select a different model. */
+    itemId?: string;
     textures?: ItemModelTextures;
     gui_light?: GuiLight;
     special?: SpecialItemRenderer;
     tints?: ItemTintSource[];
-    /** Stack-component snapshot with namespaced IDs, used by tint sources and special renderers. */
+    /** Stack-component snapshot with namespaced IDs, used by tint sources, glint, and special renderers. */
     components?: Record<string, unknown>;
     /** Ordered composite children, each with its own textures, display pose, and tint sources. */
     parts?: ItemModel[];
@@ -594,7 +606,13 @@ type SpecialItemRenderer = {
 } | {
     type: "shield" | "minecraft:shield";
 } | {
-    type: "trident" | "minecraft:trident" | "conduit" | "minecraft:conduit";
+    type: "decorated_pot" | "minecraft:decorated_pot";
+} | {
+    type: "trident" | "minecraft:trident" | "conduit" | "minecraft:conduit" | "player_head" | "minecraft:player_head";
+} | {
+    type: "copper_golem_statue" | "minecraft:copper_golem_statue";
+    texture: string;
+    pose: "standing" | "sitting" | "running" | "star";
 } | {
     type: "chest" | "minecraft:chest";
     texture: string;
@@ -658,6 +676,10 @@ declare class MinecraftCubeTexture {
 /** Texture animation and GUI scaling metadata read from a `.png.mcmeta` file. */
 interface MinecraftTextureMeta extends MinecraftAsset {
     animation?: AnimationMeta;
+    texture?: {
+        blur?: boolean;
+        clamp?: boolean;
+    };
     gui?: {
         scaling?: GuiSpriteScaling;
     };
@@ -767,6 +789,8 @@ declare function toRadians(degrees: number): number;
 declare function toDegrees(radians: number): number;
 /** Resolves after a delay in milliseconds. */
 declare function sleep(timeout: number): Promise<void>;
+/** Yields to the next macrotask without timer clamping when the platform supports it. */
+declare function yieldToEventLoop(): Promise<void>;
 /** Reduces an angle modulo 360, retaining a negative sign for negative inputs. */
 declare function clampRotationDegrees(deg: number): number;
 declare function isVector3(obj: any): obj is Vector3;
@@ -821,6 +845,7 @@ declare class TextureAtlas implements Disposable {
         [p: string]: AnimatorFunction;
     };
     readonly hasTransparency: boolean;
+    readonly hasTranslucency: boolean;
     ticker?: number;
     private readonly subscribers;
     constructor(model: Model, image: CanvasImage, sizes: {
@@ -829,7 +854,7 @@ declare class TextureAtlas implements Disposable {
         [texture: string]: DoubleArray;
     }, hasAnimation: boolean, animatorFunctions: {
         [p: string]: AnimatorFunction;
-    }, hasTransparency: boolean);
+    }, hasTransparency: boolean, hasTranslucency?: boolean);
     /** Calls subscribers when an animation frame changes; unused atlases do not tick. */
     subscribe(callback: () => void): () => void;
     /** Copies pixels for a texture variable from its current atlas rectangle. */
@@ -975,7 +1000,7 @@ declare class AssetLoader {
     /** Selects an mcasset.cloud version, updates the vanilla source, and clears in-memory caches. */
     static setVersion(version: string): void;
     /**
-     * Scope for persistent cache keys. Empty with only the default vanilla sources, so their
+     * Scope for persistent cache keys. Empty with only the default vanilla source, so its
      * entries stay valid across sessions; otherwise it names every added source (resource packs,
      * mirrors) so their results never masquerade as vanilla assets after a reload.
      */
@@ -1044,6 +1069,24 @@ declare class Assets {
     static getBlockState(key: AssetKey): Promise<Maybe<BlockState>>;
 }
 
+type BiomeColorKind = "grass" | "foliage" | "dry_foliage" | "water";
+/** Climate and color fields from a biome registry entry. Other registry fields are ignored. */
+interface Biome extends MinecraftAsset {
+    temperature: number;
+    downfall: number;
+    effects: Partial<Record<`${BiomeColorKind}_color`, number | string>> & {
+        grass_color_modifier?: "none" | "dark_forest" | "swamp";
+    };
+}
+/** Resolves biome colors through the selected version's registry and resource-pack colormaps. */
+declare class Biomes {
+    /** Loads a biome registry entry, or returns `undefined` when no source provides it. */
+    static get(id: string, origin?: AssetKey): Promise<Biome | undefined>;
+    /** Returns packed sRGB, or `undefined` when the biome or requested water color is missing. */
+    static getColor(id: string, kind: BiomeColorKind, origin?: AssetKey, x?: number, z?: number): Promise<number | undefined>;
+    private static parseColor;
+}
+
 type BlockStatePropertyValue = string | boolean | number;
 /** A vanilla block property's default and allowed values, loaded through {@link BlockStates.getDefaultState}. */
 interface BlockStateProperty {
@@ -1118,7 +1161,7 @@ declare class BlockStates {
     private static get PERSISTENT_CACHE();
     /** Returns blockstate filenames from the selected version's `_list.json`, or an empty list. */
     static getList(): Promise<string[]>;
-    static getDefaultStates(): Promise<Maybe<DefaultBlockStates>>;
+    static getDefaultStates(root?: string): Promise<Maybe<DefaultBlockStates>>;
     /** Looks up vanilla property definitions for the key's block path, or returns `undefined`. */
     static getDefaultState(key: AssetKey): Promise<Maybe<BlockStatePropertyDefaults>>;
     /** Loads a cached blockstate definition for {@link MineRenderScene.addBlock}, or returns `undefined`. */
@@ -1131,6 +1174,13 @@ declare class DefaultBlockStates implements MinecraftAsset {
     [k: string]: BlockStatePropertyDefaults;
 }
 
+type DecoratedPotSide = "back" | "left" | "right" | "front";
+/** Resolves Minecraft 1.21.11 pot decorations to the four side textures. */
+declare class DecoratedPots {
+    /** Reads up to four item IDs in back, left, right, front order; missing and unmapped items use plain sides. */
+    static getSideTextures(value: unknown, root?: string): Record<DecoratedPotSide, AssetKey>;
+}
+
 /** `entity-models/animations/<namespace>/<model id>.json`: native and sampled vanilla animation clips. */
 interface EntityAnimationFile extends MinecraftAsset {
     id: string;
@@ -1243,29 +1293,109 @@ declare class Fonts {
     private static bitmap;
 }
 
+interface MineRenderDatasets {
+    itemDefaults: Record<string, Record<string, unknown>>;
+    potionColors: {
+        effects: Record<string, number>;
+        potions: Record<string, {
+            id: string;
+            amplifier: number;
+        }[]>;
+    };
+    blockStates: Record<string, BlockStatePropertyDefaults>;
+    blockTints: Record<string, ({
+        source: "constant";
+        color: number;
+    } | {
+        source: "grass" | "stem" | "redstone";
+    }) & {
+        untinted?: number[];
+        biome?: BiomeColorKind;
+    }>;
+    fluids: Record<string, {
+        kind: "water" | "lava";
+        renderModel: boolean;
+        levelProperty?: string;
+    }>;
+    dyes: Record<string, {
+        id: number;
+        textureDiffuseColor: number;
+        fireworkColor: number;
+        textColor: number;
+    }>;
+    legacyBlocks: {
+        blocks: Record<string, string>;
+    };
+}
+interface MineRenderDataManifest {
+    schemaVersion: 1;
+    minecraftVersion: string;
+    dataVersion: number;
+    datasets: Partial<Record<keyof MineRenderDatasets, {
+        file: string;
+        sha256: string;
+        bytes: number;
+        provenance: Record<string, unknown>;
+    }>>;
+    unavailable: Record<string, string>;
+    extractor: {
+        repository: string;
+        revision: string;
+        sha256: string;
+    };
+}
+/** The requested asset version and the published data version used for its registries. */
+interface ResolvedMineRenderData {
+    requestedVersion: string;
+    version: string;
+    /** Registry lookup root. Rootless requests still allow registered sources to override this URL. */
+    root: string;
+    manifest: MineRenderDataManifest;
+}
+/** Loads extracted Minecraft registries from the active asset sources and version. */
+declare class MineRenderData {
+    /** Loads one registry. Missing files and invalid data reject the request. */
+    static get<K extends keyof MineRenderDatasets>(dataset: K, root?: string): Promise<MineRenderDatasets[K]>;
+    /**
+     * Uses the exact version when published. Otherwise, selects the nearest patch in the same
+     * release line (older on ties), then the latest earlier release or the oldest published release.
+     * Unpublished snapshots reject.
+     */
+    static resolve(root?: string): Promise<ResolvedMineRenderData>;
+    private static manifest;
+    private static load;
+    private static cached;
+    private static validDataset;
+}
+
 /** Caller-supplied item-preview state passed to {@link Models.getMerged}. */
 interface ItemModelContext {
     /** Context used by display-context selectors, overriding `properties`. Defaults to GUI. */
     displayContext?: DisplayPosition | "none";
     /** Explicit property overrides. Nodes with the same ID share one override, regardless of their parameters. */
     properties?: Record<string, boolean | string | number>;
-    /** Supplied component JSON by ID. Item-registry defaults are not added; component selectors compare structural JSON values. */
+    /** Supplied component JSON by ID, overriding built-in defaults. Component selectors compare structural JSON values. */
     components?: Record<string, unknown>;
-    /** Stack count, as a nonnegative integer. Defaults to 1; absent `max_stack_size` also defaults to 1. */
+    /** Stack count, as a nonnegative integer. Defaults to 1; items without listed defaults stack to 64. */
     count?: number;
     /** Item-model keys by reference-node ID, such as `minecraft:bundle/selected_item`. Unset references draw nothing. */
     itemReferences?: Record<string, AssetKey>;
 }
 /** Loads and caches Java block/item models, including inherited geometry and textures. */
 declare class Models {
+    private static readonly ITEM_CACHE_VERSION;
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
     /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
     static getItemList(): Promise<string[]>;
     static loadAndMerge(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     private static getItemModel;
+    private static getPreparedItemModel;
     private static contextIdentifier;
+    /** @internal */
+    static componentValue(components: Record<string, unknown>, id: string): unknown;
     private static snapshotContext;
+    private static applyDefaults;
     private static contextKey;
     private static snapshotJson;
     private static propertyValue;
@@ -1275,6 +1405,7 @@ declare class Models {
     /**
      * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
      * Item keys default to GUI context and a stack count of 1. Unresolved conditions are false and numeric properties are zero.
+     * Versioned stack-size, durability, and glint defaults apply unless components override them.
      * Pass `context` to supply component values, property overrides, and item references for a preview.
      * Composite items retain independently merged children in `ItemModel.parts`.
      *
@@ -1297,84 +1428,10 @@ declare class DisplayTransforms {
     static apply(geometry: BufferGeometry, matrix: Matrix4): void;
 }
 
-/** Resolves item-preview colors from vanilla tint definitions, stack components, and caller overrides. */
-declare class ItemTints {
-    /** Resolves preview colors from item definitions; explicit per-index colors take precedence. */
-    static get(model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
-    private static componentField;
-    private static colorOrDefault;
-    private static componentColor;
-    private static rgb;
-}
-
-/** Identifies fully opaque cubes and maps neighbor visibility to model-local face masks. */
-declare class ModelCulling {
-    /** Rotates a world-direction bit mask into model space. Bits follow {@link CUBE_FACES}. */
-    static toLocalMask(worldMask: number, rotation: Euler): number;
-    /** Whether a model fills one block with opaque faces and can hide adjacent block faces. */
-    static isOpaqueFullCube(atlas: Maybe<TextureAtlas>): boolean;
-}
-
-/** Builds extruded item-model elements from sprite pixels, including edges around transparent regions. */
-declare class ModelGenerator {
-    static readonly ITEM_LAYERS: string[];
-    /**
-     * Front and back faces plus one zero-thickness side face per run of texels that border a transparent texel,
-     * like vanilla's ItemModelGenerator. Pass the pixels of a single (first) animation frame.
-     */
-    static generateItemModel(imageData: Pick<ImageData$1, "width" | "height" | "data">, layer: string): ModelElement[];
-}
-
-/** Resolves Java model inheritance, with child elements and display poses overriding their parents. */
-declare class ModelMerger {
-    /** Loads the parent chain and returns a merged model without modifying the supplied definition. */
-    static mergeWithParents(model: Model): Promise<Model>;
-    protected static collectAllParents(model: Model): Promise<Model[]>;
-}
-
-/** Entity geometry and placement for a special item preview. Named part rotations use radians. */
-interface SpecialItemPart {
-    model: EntityModel;
-    transform: Matrix4;
-    rotations: Record<string, TripleArray>;
-    /** Absolute named-part positions in the entity model's coordinate system. */
-    positions?: Record<string, TripleArray>;
-    /** Colors for the entity model's named texture passes. */
-    tints?: Record<string, number>;
-}
-/** Loads entity geometry and texture passes for supported special item previews. */
-declare class SpecialItems {
-    /** Resolves the static entity parts drawn by a special item renderer, in model units. */
-    static getParts(special: SpecialItemRenderer, root?: string, components?: Record<string, unknown>): Promise<SpecialItemPart[]>;
-    /** An owned material with model-preview shading; its entity texture remains shared. */
-    static createMaterial(source: MeshBasicMaterial, shade: boolean): MeshBasicMaterial;
-}
-
-/** Block data passed to world setters. `type` is a namespaced ID such as `minecraft:oak_log`. */
-interface Block {
-    type: string;
-    properties?: BlockStateProperties;
-    nbt?: any;
-}
-
-/** Selects block models from property values, including multipart conditions and weighted alternatives. */
-declare class BlockStateResolver {
-    /** Loads vanilla property defaults, falling back to preview values inferred from the blockstate file. */
-    static defaults(blockState: BlockState): Promise<BlockStateProperties>;
-    /** Selects matching models. Supply `choose` to control selection within each alternatives array. */
-    static select(blockState: BlockState, state: BlockStateProperties, choose?: (variants: BlockStateVariant | BlockStateVariant[]) => BlockStateVariant): BlockStateVariant[];
-    /** Returns matching model groups before choosing weighted alternatives. */
-    static matching(blockState: BlockState, state: BlockStateProperties): (BlockStateVariant | BlockStateVariant[])[];
-    /** Selects a random alternative using positive integer weights, each defaulting to 1. */
-    static choose(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
-    /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
-    static rotation(variant: BlockStateVariant): Euler;
-}
-
-/** Supplies block-preview tint colors from block properties and the active resource pack. */
-declare class BlockTints {
-    /** Resolves block preview colors without biome context; explicit tints take precedence. */
-    static get(key: AssetKey | undefined, state: BlockStateProperties, model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
+/** Item components extracted from the selected Minecraft version; unlisted items stack to 64. */
+declare class ItemDefaults {
+    /** Returns a fresh map with namespaced component IDs; unlisted items get max_stack_size 64. */
+    static get(itemId: string, root?: string): Promise<Record<string, unknown>>;
 }
 
 /** A model that owns reusable instance slots and exposes per-slot transforms to {@link InstanceReference}. */
@@ -1435,6 +1492,246 @@ interface SceneObjectOptions {
     maxInstanceCount: number;
 }
 
+type FluidKind = "water" | "lava";
+/** Reads the fluid kind from bits 4 and 5 of a section cell byte. */
+declare function fluidKindOf(byte: number): FluidKind | undefined;
+/** A neighboring cell's fluid level and full-cube occlusion state. */
+interface FluidSample {
+    fluid?: FluidKind;
+    level?: number;
+    solid?: boolean;
+}
+/** Reads cells at integer block offsets relative to the fluid being rendered, with `(0, 0, 0)` as the center. */
+type FluidSampler = (x: number, y: number, z: number) => FluidSample;
+/** Fluid faces as quads centered on the block, four vertices each, in emission order. */
+interface FluidQuads {
+    positions: number[];
+    normals: number[];
+    uvs: number[];
+    sprites: number[];
+}
+/** Builds centered fluid quads with sprite 0 (still) or 1 (flowing). */
+declare function buildFluidQuads(kind: FluidKind, sample: FluidSampler): FluidQuads;
+
+/** Fluid contained in a block and whether the block's ordinary model is also drawn. */
+interface BlockFluidState {
+    kind: FluidKind;
+    level: number;
+    renderModel: boolean;
+}
+type FluidRules = MineRenderDatasets["fluids"];
+/** Finds water or lava from the block ID and properties, including waterlogged blocks and aquatic plants. */
+declare function getBlockFluidState(key?: AssetKey, state?: BlockStateProperties): Promise<BlockFluidState | undefined>;
+/** Resolves fluid state using rules already loaded for the block's asset version. */
+declare function resolveBlockFluidState(key: AssetKey | undefined, state: BlockStateProperties | undefined, rules: FluidRules): BlockFluidState | undefined;
+declare function getFluidKind(key?: AssetKey, state?: BlockStateProperties): Promise<FluidKind | undefined>;
+/** Builds centered fluid faces with material groups 0 (still) and 1 (flowing). */
+declare function createFluidGeometry(kind: FluidKind, sample: FluidSampler): BufferGeometry;
+
+/** Playback settings passed to {@link EntityObject.playAnimation}, {@link EntityObject.playAnimations}, or {@link EntityAnimationPlayer.play}. */
+interface EntityAnimationOptions {
+    /** Overrides the animation's own `loop` flag. */
+    loop?: boolean;
+    /** Playback rate applied to advanced time; defaults to 1. */
+    speed?: number;
+    /** Start time in seconds; defaults to 0. */
+    time?: number;
+}
+/**
+ * Poses part groups from a keyframe animation the way vanilla does: every update restores the
+ * default pose of each animated part, then adds the sampled offsets to its position, Euler angles and scale.
+ * It owns no timer; the owner advances it.
+ */
+declare class EntityAnimationPlayer {
+    private parts;
+    private _animation?;
+    private _time;
+    private loop;
+    private speed;
+    get animation(): EntityAnimation | undefined;
+    get time(): number;
+    /**
+     * Starts an animation on matching named parts. Supplied baked poses are the baseline for offsets;
+     * without them, the current pose is used. Stopping restores the pose from before playback.
+     */
+    play(layers: Object3D[], animation: EntityAnimation, options?: EntityAnimationOptions, poses?: ReadonlyMap<Object3D, EntityModelPart["pose"]>): void;
+    /** Restores the poses from before playback. Returns whether an animation was active. */
+    stop(): boolean;
+    /** Forgets the animation without touching the parts, for parts that no longer exist. */
+    clear(): void;
+    /** Applies the pose at an absolute playback time. Returns `false` when no clip is active. */
+    setTime(seconds: number): boolean;
+    /** Advances playback by elapsed seconds multiplied by the speed passed to {@link play}. */
+    advance(deltaSeconds: number): boolean;
+    private apply;
+}
+
+/** Renders selected entity layers as named part groups. Create it through {@link MineRenderScene.addEntity}. */
+declare class EntityObject extends SceneObject {
+    readonly entity: EntityModel;
+    readonly isEntityObject: true;
+    static readonly DEFAULT_OPTIONS: EntityObjectOptions;
+    readonly options: EntityObjectOptions;
+    private meshesCreated;
+    private readonly geometries;
+    private readonly disposeWireframes;
+    /** Scrolling materials are owned: their texture offset follows this entity's age. */
+    private readonly scrollMaterials;
+    private scrollTicker;
+    /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
+    age: number;
+    private readonly animationPlayers;
+    private readonly partPoses;
+    constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
+    /** An optional shared material replaces texture loading for every selected draw; its owner retains disposal. */
+    init(material?: Material): Promise<void>;
+    dispose(): void;
+    disposeAndRemoveAllChildren(): void;
+    private clearScrollMaterials;
+    private updateScrollSubscription;
+    /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
+    private updateScroll;
+    /** The first active clip, until playback is stopped or the object is disposed. */
+    get animation(): Maybe<EntityAnimation>;
+    /** Clips playing together, each targeting a separate geometry layer. */
+    get activeAnimations(): readonly EntityAnimation[];
+    /** Seconds since the animation started, before looping. */
+    get animationTime(): number;
+    /**
+     * Plays a clip from {@link Entities.getAnimations}, replacing all active clips.
+     * Offsets apply to the baked pose in the clip's layer (`main` by default), including repeated draws of that layer.
+     * The object owns no clock: call {@link advanceAnimation} per frame, or {@link setAnimationTime}.
+     */
+    playAnimation(animation: EntityAnimation, options?: EntityAnimationOptions): void;
+    /** Plays one clip per selected geometry layer, with a shared clock and no blending between clips. */
+    playAnimations(animations: readonly EntityAnimation[], options?: EntityAnimationOptions): void;
+    /** Stops all clips and restores the poses from before playback. */
+    stopAnimation(): void;
+    /** Poses the object at an explicit time in seconds. Has no effect without an animation. */
+    setAnimationTime(seconds: number): void;
+    /** Advances the animation by a frame delta in seconds, scaled by its speed. Has no effect without an animation. */
+    advanceAnimation(deltaSeconds: number): void;
+    /** Finds a selected draw by its layer key, such as `main` or `main#2`, or returns `undefined`. */
+    getLayerGroup(name: string): Maybe<Object3D>;
+    /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
+    getGroupByName(name: string, layerName?: string): Maybe<Object3D>;
+    /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
+    getMeshByName(name: string, layerName?: string): Maybe<Mesh>;
+    private get entityLayers();
+    private getTextureKey;
+    protected loadTextures(layer?: EntityLayer): Promise<Maybe<ExtractableImageData>>;
+    protected createMeshes(force?: boolean): void;
+    private createPart;
+    protected applyTextures(): Promise<void>;
+}
+/** Render settings passed to `scene.addEntity(entity, options)` or the EntityObject constructor. */
+interface EntityObjectOptions extends SceneObjectOptions {
+    /**
+     * `true` applies only vanilla's entity flip, scale (-1, -1, 1); `false` keeps raw model space.
+     * By default the model's dataset transform is used, or the flip for models without one.
+     */
+    flip?: boolean;
+    /** Colours for the dataset's tint labels, e.g. `{ wool_color: 0xf9801d }`; a pass whose label is absent stays untinted. */
+    tints?: Record<string, ColorRepresentation>;
+    /** Cube faces by layer key; omitted layers draw all six faces. */
+    faces?: Record<string, CubeFace[]>;
+}
+declare function isEntityObject(obj: any): obj is EntityObject;
+
+/** Controls the model parts selected by a blockstate. Create it through {@link MineRenderScene.addBlock}. */
+declare class BlockObject extends SceneObject {
+    readonly blockState: BlockState;
+    readonly isBlockObject: true;
+    static readonly DEFAULT_OPTIONS: BlockObjectOptions;
+    readonly options: BlockObjectOptions;
+    private readonly variantPosition?;
+    private _previousState;
+    private _state;
+    private _variant;
+    private _instanceState;
+    private _instanceVariant;
+    private _instanceModel;
+    private _variants;
+    private _models;
+    private _cullMask;
+    private _fluidKey?;
+    private _fluidRules;
+    private _fluidSampler?;
+    private readonly biomePosition?;
+    private waterTint?;
+    private _fluidModel?;
+    private _entities;
+    private _entityPlacement;
+    private _entityGeneration;
+    constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
+    init(): Promise<void>;
+    dispose(): void;
+    removeFromScene(): void;
+    private clearModels;
+    private removeModels;
+    private removeEntities;
+    /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
+    get blockEntities(): readonly EntityObject[];
+    /** Sets visibility for this block's model instances and block entities. */
+    setVisible(visible: boolean): void;
+    /**
+     * Draws the block through the dataset's block-entity index. Returns false, leaving nothing behind,
+     * when the block is not listed or one of its models cannot be loaded.
+     */
+    private createBlockEntities;
+    private placeEntities;
+    get isOccluding(): boolean;
+    private getModelMatrix;
+    private getModelCullMask;
+    /** World-space face mask currently applied to this block. */
+    get cullMask(): number;
+    setCullMask(worldMask: number): Promise<void>;
+    /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
+    get state(): {
+        [key: string]: string;
+    };
+    get fluidKind(): FluidKind | undefined;
+    get fluidLevel(): number;
+    /** Refreshes fluid surfaces from relative neighbors; standalone previews use air around the block. */
+    updateFluid(sample?: FluidSampler): Promise<void>;
+    nextInstance(): InstanceReference<SceneObject>;
+    protected mapStateToVariant(state: BlockStateProperties): Promise<BlockStateVariant[]>;
+    recreateModels(): Promise<void>;
+    private hasGeometry;
+    protected getSingleVariant(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
+    protected createAVariant(variants: BlockStateVariant | BlockStateVariant[], instanceInfo: Matrix4[]): Promise<void>;
+    protected createVariant(variant: BlockStateVariant): Promise<ModelObject | InstanceReference<ModelObject>>;
+    /** Clears selected properties and rebuilds models without reapplying property defaults. */
+    resetState(): Promise<void>;
+    /**
+     * Updates properties and rebuilds the selected models.
+     * Accepts `"facing=north,open=true"`, a property object, or a key and value.
+     * Properties omitted from the call keep their current values.
+     */
+    setState(string: string): any;
+    setState(state: BlockStateProperties): any;
+    setState(key: string, value: string): any;
+    protected _setState(stringOrKeyOrState: string | BlockStateProperties, value?: string): void;
+    setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
+    getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
+    setMatrixAt(index: number, matrix: Matrix4): void;
+    setPosition(position: Vector3): void;
+}
+/** Block settings passed to `scene.addBlock(blockState, options)` or the BlockObject constructor. */
+interface BlockObjectOptions extends ModelObjectOptions {
+    /** Loads vanilla property defaults before applying `initialState`. Defaults to `true`. */
+    applyDefaultState: boolean;
+    /** Properties applied before model creation, overriding defaults when applyDefaultState is enabled. */
+    initialState?: BlockStateProperties;
+    /** Absolute block coordinates for repeatable variants, copied at construction. Omit for random previews. */
+    variantPosition?: TripleArray;
+    /** Saved biome ID used for automatic grass, foliage, and water colors. */
+    biome?: string;
+    /** World block coordinates used by biome grass modifiers. Copied at construction; defaults to the origin. */
+    biomePosition?: TripleArray;
+}
+declare function isBlockObject(obj: any): obj is BlockObject;
+
 /** Builds render geometry from a merged Java model. Create it through {@link MineRenderScene.addModel}. */
 declare class ModelObject extends SceneObject {
     readonly originalModel: Model;
@@ -1447,6 +1744,8 @@ declare class ModelObject extends SceneObject {
     private unsubscribeAtlas?;
     private readonly specialMaterials;
     private readonly geometries;
+    private readonly hasGlint;
+    private glint?;
     blockParent: Maybe<BlockObject>;
     private meshesCreated;
     constructor(originalModel: Model, options?: Partial<ModelObjectOptions>);
@@ -1550,113 +1849,6 @@ interface SkinObjectOptions extends SceneObjectOptions {
     legacy?: boolean;
 }
 
-/** Playback settings passed to {@link EntityObject.playAnimation}, {@link EntityObject.playAnimations}, or {@link EntityAnimationPlayer.play}. */
-interface EntityAnimationOptions {
-    /** Overrides the animation's own `loop` flag. */
-    loop?: boolean;
-    /** Playback rate applied to advanced time; defaults to 1. */
-    speed?: number;
-    /** Start time in seconds; defaults to 0. */
-    time?: number;
-}
-/**
- * Poses part groups from a keyframe animation the way vanilla does: every update restores the
- * default pose of each animated part, then adds the sampled offsets to its position, Euler angles and scale.
- * It owns no timer; the owner advances it.
- */
-declare class EntityAnimationPlayer {
-    private parts;
-    private _animation?;
-    private _time;
-    private loop;
-    private speed;
-    get animation(): EntityAnimation | undefined;
-    get time(): number;
-    /**
-     * Starts an animation on matching named parts. Supplied baked poses are the baseline for offsets;
-     * without them, the current pose is used. Stopping restores the pose from before playback.
-     */
-    play(layers: Object3D[], animation: EntityAnimation, options?: EntityAnimationOptions, poses?: ReadonlyMap<Object3D, EntityModelPart["pose"]>): void;
-    /** Restores the poses from before playback. Returns whether an animation was active. */
-    stop(): boolean;
-    /** Forgets the animation without touching the parts, for parts that no longer exist. */
-    clear(): void;
-    /** Applies the pose at an absolute playback time. Returns `false` when no clip is active. */
-    setTime(seconds: number): boolean;
-    /** Advances playback by elapsed seconds multiplied by the speed passed to {@link play}. */
-    advance(deltaSeconds: number): boolean;
-    private apply;
-}
-
-/** Renders selected entity layers as named part groups. Create it through {@link MineRenderScene.addEntity}. */
-declare class EntityObject extends SceneObject {
-    readonly entity: EntityModel;
-    readonly isEntityObject: true;
-    static readonly DEFAULT_OPTIONS: EntityObjectOptions;
-    readonly options: EntityObjectOptions;
-    private meshesCreated;
-    private readonly geometries;
-    private readonly disposeWireframes;
-    /** Scrolling materials are owned: their texture offset follows this entity's age. */
-    private readonly scrollMaterials;
-    private scrollTicker;
-    /** Entity age in ticks, as vanilla's `ageInTicks`; drives the scrolling render modes. */
-    age: number;
-    private readonly animationPlayers;
-    private readonly partPoses;
-    constructor(entity: EntityModel, options?: Partial<EntityObjectOptions>);
-    init(): Promise<void>;
-    dispose(): void;
-    disposeAndRemoveAllChildren(): void;
-    private clearScrollMaterials;
-    private updateScrollSubscription;
-    /** Applies the entity age to the scrolling materials; the ticker calls this 20 times per second. */
-    private updateScroll;
-    /** The first active clip, until playback is stopped or the object is disposed. */
-    get animation(): Maybe<EntityAnimation>;
-    /** Clips playing together, each targeting a separate geometry layer. */
-    get activeAnimations(): readonly EntityAnimation[];
-    /** Seconds since the animation started, before looping. */
-    get animationTime(): number;
-    /**
-     * Plays a clip from {@link Entities.getAnimations}, replacing all active clips.
-     * Offsets apply to the baked pose in the clip's layer (`main` by default), including repeated draws of that layer.
-     * The object owns no clock: call {@link advanceAnimation} per frame, or {@link setAnimationTime}.
-     */
-    playAnimation(animation: EntityAnimation, options?: EntityAnimationOptions): void;
-    /** Plays one clip per selected geometry layer, with a shared clock and no blending between clips. */
-    playAnimations(animations: readonly EntityAnimation[], options?: EntityAnimationOptions): void;
-    /** Stops all clips and restores the poses from before playback. */
-    stopAnimation(): void;
-    /** Poses the object at an explicit time in seconds. Has no effect without an animation. */
-    setAnimationTime(seconds: number): void;
-    /** Advances the animation by a frame delta in seconds, scaled by its speed. Has no effect without an animation. */
-    advanceAnimation(deltaSeconds: number): void;
-    /** Finds a selected draw by its layer key, such as `main` or `main#2`, or returns `undefined`. */
-    getLayerGroup(name: string): Maybe<Object3D>;
-    /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
-    getGroupByName(name: string, layerName?: string): Maybe<Object3D>;
-    /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
-    getMeshByName(name: string, layerName?: string): Maybe<Mesh>;
-    private get entityLayers();
-    private getTextureKey;
-    protected loadTextures(layer?: EntityLayer): Promise<Maybe<ExtractableImageData>>;
-    protected createMeshes(force?: boolean): void;
-    private createPart;
-    protected applyTextures(): Promise<void>;
-}
-/** Render settings passed to `scene.addEntity(entity, options)` or the EntityObject constructor. */
-interface EntityObjectOptions extends SceneObjectOptions {
-    /**
-     * `true` applies only vanilla's entity flip, scale (-1, -1, 1); `false` keeps raw model space.
-     * By default the model's dataset transform is used, or the flip for models without one.
-     */
-    flip?: boolean;
-    /** Colours for the dataset's tint labels, e.g. `{ wool_color: 0xf9801d }`; a pass whose label is absent stays untinted. */
-    tints?: Record<string, ColorRepresentation>;
-}
-declare function isEntityObject(obj: any): obj is EntityObject;
-
 /** Text appearance set on a GUI text layer or overridden by an individual text run. */
 interface GuiTextStyle {
     /** sRGB 0xRRGGBB; defaults to white. */
@@ -1724,8 +1916,10 @@ interface GuiTextureLayer extends GuiLayerLayout {
 interface GuiItemLayer extends GuiLayerLayout {
     /** Model key, such as minecraft:item/stone; uses the model's GUI display pose. */
     item: AssetKey | string;
-    /** Supplied item state. GUI layers always select models in the GUI display context. */
+    /** Supplied item state, count label, and damage bar. Count zero leaves an empty slot; models always use the GUI display context. */
     context?: Omit<ItemModelContext, "displayContext">;
+    /** Draw count labels and durability bars. Defaults to true. */
+    decorations?: boolean;
     /** sRGB 0xRRGGBB colors by face tint index, overriding the item's automatic preview colors. */
     tints?: Record<number, number>;
 }
@@ -1749,6 +1943,10 @@ declare class GuiObject extends SceneObject {
     private initialized;
     constructor(textureLayers: readonly GuiLayer[], options?: Partial<GuiObjectOptions>);
     init(): Promise<void>;
+    private createText;
+    private textMaterial;
+    private itemOverlay;
+    private createItemOverlay;
     private createItem;
     private loadMaterial;
     disposeAndRemoveAllChildren(): void;
@@ -1876,141 +2074,157 @@ declare class SceneObject extends Object3D<Object3DEventMap & {
     /** Returns the live reference for a raycast hit on this object's instance mesh. */
     getInstanceReference(mesh: Object3D, index: number): Maybe<InstanceReference<SceneObject>>;
     isInstanceActive(index: number, reference: InstanceReference<Instanceable>): boolean;
-    removeInstanceAt(index: number): void;
-    private growInstances;
-    protected activeInstanceIndices(): Iterable<number>;
-    getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
-    setMatrixAt(index: number, matrix: Matrix4): void;
-    setInstanceVisibleAt(index: number, visible: boolean): void;
-    setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
-    setPositionAt(index: number, position: Vector3): void;
-    getPositionAt(index: number, vector?: Vector3): Vector3;
-    setRotationAt(index: number, rotation: Euler): void;
-    getRotationAt(index: number, euler?: Euler): Euler;
-    setScaleAt(index: number, scale: Vector3): void;
-    getScaleAt(index: number, vector?: Vector3): Vector3;
-    /** Updates supplied transform components. For a shared model, affects every live instance. */
-    setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
-    /** Sets position in scene units. For a shared model, updates every live instance. */
-    setPosition(position: Vector3): void;
-    getPosition(): Vector3;
-    /** Sets rotation in radians. For a shared model, updates every live instance. */
-    setRotation(rotation: Euler): void;
-    getRotation(): Euler;
-    /** Sets scale factors. For a shared model, updates every live instance. */
-    setScale(scale: Vector3): void;
-    getScale(): Vector3;
-    protected toggleObjectVisibility(object?: Object3D, visible?: boolean): boolean;
-    dispose(): void;
-    /** Releases instance slots and removes children, disposing children that implement Disposable. */
-    disposeAndRemoveAllChildren(): void;
-    /** Detaches the object from its parent and requests a redraw. */
-    removeFromScene(): void;
-}
-declare function isSceneObject(obj: any): obj is SceneObject;
-
-type FluidKind = "water" | "lava";
-/** Fluid contained in a block and whether the block's ordinary model is also drawn. */
-interface BlockFluidState {
-    kind: FluidKind;
-    level: number;
-    renderModel: boolean;
-}
-/** Finds water or lava from the block ID and properties, including waterlogged blocks and aquatic plants. */
-declare function getBlockFluidState(key?: AssetKey, state?: BlockStateProperties): BlockFluidState | undefined;
-declare function getFluidKind(key?: AssetKey, state?: BlockStateProperties): FluidKind | undefined;
-/** A neighboring cell's fluid level and full-cube occlusion state. */
-interface FluidSample {
-    fluid?: FluidKind;
-    level?: number;
-    solid?: boolean;
-}
-/** Reads cells at integer block offsets relative to the fluid being rendered, with `(0, 0, 0)` as the center. */
-type FluidSampler = (x: number, y: number, z: number) => FluidSample;
-/** Builds centered fluid faces with material groups 0 (still) and 1 (flowing). */
-declare function createFluidGeometry(kind: FluidKind, sample: FluidSampler): BufferGeometry;
-
-/** Controls the model parts selected by a blockstate. Create it through {@link MineRenderScene.addBlock}. */
-declare class BlockObject extends SceneObject {
-    readonly blockState: BlockState;
-    readonly isBlockObject: true;
-    static readonly DEFAULT_OPTIONS: BlockObjectOptions;
-    readonly options: BlockObjectOptions;
-    private _previousState;
-    private _state;
-    private _variant;
-    private _instanceState;
-    private _instanceVariant;
-    private _instanceModel;
-    private _variants;
-    private _models;
-    private _cullMask;
-    private _fluidKey?;
-    private _fluidSampler?;
-    private _fluidModel?;
-    private _entities;
-    private _entityPlacement;
-    private _entityGeneration;
-    constructor(blockState: BlockState, options?: Partial<BlockObjectOptions>);
-    init(): Promise<void>;
+    removeInstanceAt(index: number): void;
+    private growInstances;
+    protected activeInstanceIndices(): Iterable<number>;
+    getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
+    setMatrixAt(index: number, matrix: Matrix4): void;
+    setInstanceVisibleAt(index: number, visible: boolean): void;
+    setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
+    setPositionAt(index: number, position: Vector3): void;
+    getPositionAt(index: number, vector?: Vector3): Vector3;
+    setRotationAt(index: number, rotation: Euler): void;
+    getRotationAt(index: number, euler?: Euler): Euler;
+    setScaleAt(index: number, scale: Vector3): void;
+    getScaleAt(index: number, vector?: Vector3): Vector3;
+    /** Updates supplied transform components. For a shared model, affects every live instance. */
+    setPositionRotationScale(position?: Vector3, rotation?: Euler, scale?: Vector3): void;
+    /** Sets position in scene units. For a shared model, updates every live instance. */
+    setPosition(position: Vector3): void;
+    getPosition(): Vector3;
+    /** Sets rotation in radians. For a shared model, updates every live instance. */
+    setRotation(rotation: Euler): void;
+    getRotation(): Euler;
+    /** Sets scale factors. For a shared model, updates every live instance. */
+    setScale(scale: Vector3): void;
+    getScale(): Vector3;
+    protected toggleObjectVisibility(object?: Object3D, visible?: boolean): boolean;
     dispose(): void;
+    /** Releases instance slots and removes children, disposing children that implement Disposable. */
+    disposeAndRemoveAllChildren(): void;
+    /** Detaches the object from its parent and requests a redraw. */
     removeFromScene(): void;
-    private clearModels;
-    private removeModels;
-    private removeEntities;
-    /** Entity models drawn for this block instead of its block model; they are scene children, unlike the block. */
-    get blockEntities(): readonly EntityObject[];
-    /** Sets visibility for this block's model instances and block entities. */
-    setVisible(visible: boolean): void;
+}
+declare function isSceneObject(obj: any): obj is SceneObject;
+
+/** An owned glint material over item geometry; textures and geometry retain their owners. */
+declare class ItemGlint {
+    private readonly owner;
+    readonly material: ShaderMaterial;
+    private ticker?;
+    private constructor();
+    /** Enables glint for enchantments or a lodestone compass unless a boolean component overrides them. */
+    static enabled(components?: Record<string, unknown>, itemId?: string): boolean;
+    /** @internal */
+    static create(owner: SceneObject, baseMap?: Texture, root?: string, entityMeshes?: readonly {
+        mesh: Mesh;
+        parent?: Mesh;
+    }[]): Promise<ItemGlint>;
     /**
-     * Draws the block through the dataset's block-entity index. Returns false, leaving nothing behind,
-     * when the block is not listed or one of its models cannot be loaded.
+     * Maps glint before model centering and display transforms. Ordinary sprites approximate Minecraft's shared atlas density.
+     * @internal
      */
-    private createBlockEntities;
-    private placeEntities;
-    get isOccluding(): boolean;
-    private getModelMatrix;
-    private getModelCullMask;
-    setCullMask(worldMask: number): Promise<void>;
-    /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
-    get state(): {
-        [key: string]: string;
-    };
-    get fluidKind(): FluidKind | undefined;
-    get fluidLevel(): number;
-    /** Refreshes fluid surfaces from relative neighbors; standalone previews use air around the block. */
-    updateFluid(sample?: FluidSampler): Promise<void>;
-    nextInstance(): InstanceReference<SceneObject>;
-    protected mapStateToVariant(state: BlockStateProperties): Promise<BlockStateVariant[]>;
-    recreateModels(): Promise<void>;
-    private hasGeometry;
-    protected getSingleVariant(variants: BlockStateVariant | BlockStateVariant[]): BlockStateVariant;
-    protected createAVariant(variants: BlockStateVariant | BlockStateVariant[], instanceInfo: Matrix4[]): Promise<void>;
-    protected createVariant(variant: BlockStateVariant): Promise<ModelObject | InstanceReference<ModelObject>>;
-    /** Clears selected properties and rebuilds models without reapplying property defaults. */
-    resetState(): Promise<void>;
+    static mapUvs(geometry: BufferGeometry, faces: ModelFaces, atlas: TextureAtlas, itemId?: string, display?: DisplayPosition): void;
+    private updateTime;
+    /** @internal */
+    updateSubscription(active: boolean): void;
+    dispose(): void;
+}
+
+/** Resolves item-preview colors from vanilla tint definitions, stack components, and caller overrides. */
+declare class ItemTints {
+    /** Lists potion IDs from the selected version's registry. */
+    static getPotionList(root?: string): Promise<string[]>;
+    /** Resolves preview colors from item definitions; explicit per-index colors take precedence. */
+    static get(model: Model, tints?: Record<number, number>): Promise<Record<number, number> | undefined>;
+    /** Whether a potion component contains a known effect, including effects with hidden particles. */
+    static hasPotionEffects(value: unknown, root?: string): Promise<boolean>;
+    private static potionColor;
+    private static potionContents;
+    private static potionEffects;
+    private static componentField;
+    private static colorOrDefault;
+    private static componentColor;
+    private static rgb;
+}
+
+/** Identifies fully opaque cubes and maps neighbor visibility to model-local face masks. */
+declare class ModelCulling {
+    /** Rotates a world-direction bit mask into model space. Bits follow {@link CUBE_FACES}. */
+    static toLocalMask(worldMask: number, rotation: Euler): number;
+    /** Whether a model fills one block with opaque faces and can hide adjacent block faces. */
+    static isOpaqueFullCube(atlas: Maybe<TextureAtlas>): boolean;
+}
+
+/** Builds extruded item-model elements from sprite pixels, including edges around transparent regions. */
+declare class ModelGenerator {
+    static readonly ITEM_LAYERS: string[];
     /**
-     * Updates properties and rebuilds the selected models.
-     * Accepts `"facing=north,open=true"`, a property object, or a key and value.
-     * Properties omitted from the call keep their current values.
+     * Front and back faces plus one zero-thickness side face per run of texels that border a transparent texel,
+     * like vanilla's ItemModelGenerator. Pass the pixels of a single (first) animation frame.
      */
-    setState(string: string): any;
-    setState(state: BlockStateProperties): any;
-    setState(key: string, value: string): any;
-    protected _setState(stringOrKeyOrState: string | BlockStateProperties, value?: string): void;
-    setPositionRotationScaleAt(index: number, position?: Vector3, rotation?: Euler, scale?: Vector3): void;
-    getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
-    setMatrixAt(index: number, matrix: Matrix4): void;
-    setPosition(position: Vector3): void;
+    static generateItemModel(imageData: Pick<ImageData$1, "width" | "height" | "data">, layer: string): ModelElement[];
 }
-/** Block settings passed to `scene.addBlock(blockState, options)` or the BlockObject constructor. */
-interface BlockObjectOptions extends ModelObjectOptions {
-    /** Loads vanilla property defaults before applying `initialState`. Defaults to `true`. */
-    applyDefaultState: boolean;
-    /** Properties applied before model creation, overriding defaults when applyDefaultState is enabled. */
-    initialState?: BlockStateProperties;
+
+/** Resolves Java model inheritance, with child elements and display poses overriding their parents. */
+declare class ModelMerger {
+    /** Loads the parent chain and returns a merged model without modifying the supplied definition. */
+    static mergeWithParents(model: Model): Promise<Model>;
+    protected static collectAllParents(model: Model): Promise<Model[]>;
+}
+
+/** Entity geometry and placement for a special item preview. Named part rotations use radians. */
+interface SpecialItemPart {
+    model: EntityModel;
+    transform: Matrix4;
+    rotations: Record<string, TripleArray>;
+    /** Absolute named-part positions in the entity model's coordinate system. */
+    positions?: Record<string, TripleArray>;
+    /** Colors for the entity model's named texture passes. */
+    tints?: Record<string, number>;
+    faces?: Record<string, CubeFace[]>;
+    /** Shared prepared material; the renderer clones it and retains ownership of only that clone. */
+    material?: MeshBasicMaterial;
+}
+/** Loads entity geometry and texture passes for supported special item previews. */
+declare class SpecialItems {
+    /** Resolves the static entity parts drawn by a special item renderer, in model units. */
+    static getParts(special: SpecialItemRenderer, root?: string, components?: Record<string, unknown>): Promise<SpecialItemPart[]>;
+    /** An owned material with model-preview shading; its entity texture remains shared. */
+    static createMaterial(source: MeshBasicMaterial, shade: boolean): MeshBasicMaterial;
+}
+
+/** Block data passed to world setters. `type` is a namespaced ID such as `minecraft:oak_log`. */
+interface Block {
+    type: string;
+    properties?: BlockStateProperties;
+    nbt?: any;
+}
+
+/** Selects block models from property values, including multipart conditions and weighted alternatives. */
+declare class BlockStateResolver {
+    /** Loads vanilla property defaults, falling back to preview values inferred from the blockstate file. */
+    static defaults(blockState: BlockState): Promise<BlockStateProperties>;
+    /** Selects matching models. Supply `choose` to control selection within each alternatives array. */
+    static select(blockState: BlockState, state: BlockStateProperties, choose?: (variants: BlockStateVariant | BlockStateVariant[]) => BlockStateVariant): BlockStateVariant[];
+    /** Returns matching model groups before choosing weighted alternatives. */
+    static matching(blockState: BlockState, state: BlockStateProperties): (BlockStateVariant | BlockStateVariant[])[];
+    /** Selects by positive integer weights (default 1); world block coordinates make the choice repeatable. */
+    static choose(variants: BlockStateVariant | BlockStateVariant[], position?: Readonly<TripleArray>): BlockStateVariant;
+    private static positionSample;
+    /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
+    static rotation(variant: BlockStateVariant): Euler;
+}
+
+/** Supplies block tint colors from versioned rendering rules and the active resource pack. */
+declare class BlockTints {
+    /** Returns a block's versioned biome color source, leaving fixed-color blocks unchanged. */
+    static biomeSource(key?: AssetKey): Promise<BiomeColorKind | undefined>;
+    /** Resolves one block's biome tint at world block coordinates, without biome blending. */
+    static getBiomeColor(key?: AssetKey, biome?: string, position?: Readonly<TripleArray>): Promise<number | undefined>;
+    /** Resolves used tint indices from biome or preview colors; explicit tints take precedence. */
+    static get(key: AssetKey | undefined, state: BlockStateProperties, model: Model, tints?: Record<number, number>, biomeColor?: number | (() => Promise<number | undefined>)): Promise<Record<number, number> | undefined>;
 }
-declare function isBlockObject(obj: any): obj is BlockObject;
 
 /** Saved fluid levels and solid neighbors determine the geometry shared by an instance pool. */
 declare function sampleFluid(kind: FluidKind, sample: FluidSampler): {
@@ -2028,6 +2242,11 @@ declare class FluidModelObject extends ModelObject {
     disposeAndRemoveAllChildren(): void;
 }
 
+/** Resolves a numeric block using mappings for the selected asset version, with caller overrides. */
+declare function resolveLegacyBlock(id: number, metadata: number, customMappings?: Readonly<Record<string, string>>, lenient?: boolean, root?: string): Promise<Block | undefined>;
+/** Resolves a numeric block using a previously loaded mapping table. */
+declare function resolveLegacyBlockState(id: number, metadata: number, mapping: Readonly<Record<string, string>>, customMappings?: Readonly<Record<string, string>>, lenient?: boolean): Block | undefined;
+
 /** Parsed blocks and entity data for {@link MineRenderWorld.placeMultiBlock}. Dimensions and positions use blocks. */
 interface MultiBlockStructure {
     readonly size: TripleArray;
@@ -2035,7 +2254,7 @@ interface MultiBlockStructure {
     readonly dataVersion?: number;
     readonly entities?: MultiBlockEntity[];
 }
-/** Preserved entity position and NBT. World placement does not create a render object for it. */
+/** Preserved entity position and NBT. `MineRenderWorld` can render supported mobs with `renderEntities`. */
 interface MultiBlockEntity {
     position: TripleArray;
     blockPosition?: TripleArray;
@@ -2046,15 +2265,40 @@ interface MultiBlockBlock extends Block {
     position: TripleArray;
 }
 
+/** A named region with block and entity positions relative to the schematic origin. */
+interface LitematicaRegion extends MultiBlockStructure {
+    readonly name: string;
+    /** The selected first corner, relative to the schematic origin. */
+    readonly position: TripleArray;
+    /** Signed source dimensions. The inherited size contains their absolute values. */
+    readonly signedSize: TripleArray;
+}
+/** Combined blocks and the named regions that produced them. */
+interface LitematicaStructure extends MultiBlockStructure {
+    readonly regions: LitematicaRegion[];
+}
+/** Reads v5–7 `.litematic` files without migrating block states or entity NBT. */
+declare class LitematicaParser {
+    /**
+     * Parses decoded NBT, preserving subregion placement and omitting air.
+     * Later entries in regions replace earlier cells, including with air.
+     * Size encloses all region bounds; positions retain the schematic origin.
+     * Metadata and scheduled ticks are not imported. Named regions can be placed individually.
+     */
+    static parse(nbt: NBT): Promise<LitematicaStructure>;
+}
+
 /** Converts legacy Alpha `.schematic` NBT with numeric block IDs into modern block names and properties. */
 declare class SchematicParser {
     /**
-     * Parses a legacy schematic using custom mappings before the bundled defaults.
+     * Parses a legacy schematic using custom mappings before the selected version's defaults.
      * Keys are `id:metadata`; values are block states such as `minecraft:oak_log[axis=x]`.
      */
     static parse(nbt: NBT, customMappings?: Readonly<Record<string, string>>, options?: SchematicParserOptions): Promise<MultiBlockStructure>;
 }
 interface SchematicParserOptions {
+    /** Asset root used to select the legacy mapping version. Omit to use the active asset sources. */
+    root?: string;
     /**
      * Ignores Materials, tries metadata 0 for unmapped states, and skips unknown IDs. Defaults to false.
      * Dimensions, arrays, and entity data remain validated.
@@ -2062,6 +2306,16 @@ interface SchematicParserOptions {
     lenient?: boolean;
 }
 
+/** Converts Sponge v2/v3 `.schem` NBT into blocks and preserved entity data. */
+declare class SpongeSchematicParser {
+    /**
+     * Parses decoded NBT with a local block palette, omitting air blocks.
+     * Applies Offset to block and entity positions; size remains the source dimensions.
+     * Biomes and metadata are not imported, and DataVersion does not trigger migration.
+     */
+    static parse(nbt: NBT): Promise<MultiBlockStructure>;
+}
+
 /** Converts Java structure NBT into blocks and preserved entity data for world placement. */
 declare class StructureParser {
     /**
@@ -2370,7 +2624,6 @@ declare class Caching {
     static readonly modelTextureAtlasCache: AsyncLoadingCache<CacheKey, TextureAtlas>;
     static readonly blockStateCache: AsyncLoadingCache<CacheKey, BlockState>;
     static readonly listAssetCache: AsyncLoadingCache<CacheKey, ListAsset>;
-    static readonly defaultBlockStatesCache: AsyncLoadingCache<CacheKey, DefaultBlockStates>;
     static readonly blockTintCache: AsyncLoadingCache<CacheKey, number>;
     static readonly entityModelCache: AsyncLoadingCache<CacheKey, EntityModelFile>;
     static readonly entityTextureCache: AsyncLoadingCache<CacheKey, AssetKey>;
@@ -2378,6 +2631,9 @@ declare class Caching {
     static readonly blockEntityIndexCache: AsyncLoadingCache<CacheKey, BlockEntityIndex>;
     static readonly fontCache: AsyncLoadingCache<CacheKey, BitmapFont>;
     static readonly bannerPatternCache: AsyncLoadingCache<CacheKey, BannerPattern>;
+    static readonly mineRenderDataCache: AsyncLoadingCache<CacheKey, unknown>;
+    static readonly usernameUuidCache: AsyncLoadingCache<CacheKey, string>;
+    static readonly biomeCache: AsyncLoadingCache<CacheKey, Biome>;
     private static createAssetCache;
     /** Every cache above, so clear()/end() can never fall out of sync with the field list again. */
     private static get all();
@@ -2409,7 +2665,7 @@ interface SceneGLTFExportOptions {
     /** Maximum width and height of each exported texture, in pixels. */
     maxTextureSize?: number;
 }
-/** Exports the visible meshes at their current poses without changing the source scene. */
+/** Exports visible geometry at its current pose without changing the source scene. Animated item glint is omitted. */
 declare class SceneExporter {
     /** Returns OBJ geometry with normals and UVs; material files and textures are not included. */
     static toObj(root: Object3D): string;
@@ -2422,6 +2678,53 @@ declare class SceneExporter {
     static toGLTF(root: Object3D, options?: SceneGLTFExportOptions): Promise<Record<string, any> | ArrayBuffer>;
 }
 
+/** Settings passed to {@link Renderer.toVideo}. */
+interface VideoExportOptions {
+    /** Recording duration in seconds, greater than zero and at most 2147483.647. */
+    duration: number;
+    /** Requested capture rate (default 30). Rendering and browser scheduling can lower the actual rate. */
+    fps?: number;
+    /** Supported video MIME type. Defaults to WebM when available, then MP4. */
+    mimeType?: string;
+    /** Target video bitrate in bits per second, as a positive unsigned 32-bit integer. */
+    videoBitsPerSecond?: number;
+    /** Cancels recording and discards its output. */
+    signal?: AbortSignal;
+}
+/**
+ * Records fresh canvas frames in a browser, at a fixed size with an opaque black background.
+ * @internal
+ */
+declare class VideoExporter {
+    private readonly source;
+    /** Resolves after the recorder provides its final video data. */
+    readonly result: Promise<Blob>;
+    private readonly canvas;
+    private readonly context;
+    private readonly signal?;
+    private readonly duration;
+    private stream?;
+    private recorder?;
+    private timer?;
+    private readonly chunks;
+    private settled;
+    private stopping;
+    private resolve;
+    private reject;
+    constructor(source: HTMLCanvasElement, options: VideoExportOptions);
+    /** Copies a freshly drawn source frame before WebGL can clear its drawing buffer. */
+    capture(): void;
+    /** Cancels recording, releases its capture stream, and rejects {@link result}. */
+    cancel(reason?: unknown): void;
+    private readonly onStart;
+    private readonly onData;
+    private readonly onStop;
+    private readonly onError;
+    private readonly onAbort;
+    private readonly onTrackEnded;
+    private cleanup;
+}
+
 /** Container coordinates in GUI pixels. Crops refer to vanilla's 256×256 sheets; {@link GuiHelper.container} scales them for resource packs. */
 declare const GUI_CONTAINER_LAYOUTS: {
     readonly generic_54: {
@@ -2471,7 +2774,7 @@ declare class GuiHelper {
      * @param rowSize - Slots per row when `slot` is an index.
      */
     static inventorySlot(slot: number | readonly [number, number], origin?: readonly [number, number], offset?: readonly [number, number], rowSize?: number): [number, number];
-    /** Creates crafting-table layers for ingredients and the result; stack counts are not drawn. */
+    /** Creates crafting-table layers for ingredients and the result, including its stack count. */
     static recipe(recipe: GuiRecipe, options?: GuiRecipeOptions): GuiLayer[];
 }
 /** Settings passed to {@link GuiHelper.bossBar}. */
@@ -2609,20 +2912,139 @@ declare class MapControls extends OrbitControls {
     constructor(object: Camera, domElement?: HTMLElement);
 }
 
+/** Events dispatched by {@link FlyControls}. */
+interface FlyControlsEventMap {
+    /** The camera moved or turned. */
+    change: {};
+    /** Mouse look captured the pointer. */
+    lock: {};
+    /** Mouse look released the pointer. */
+    unlock: {};
+}
+/** Movement actions that {@link FlyControls.keys} binds to `KeyboardEvent.code` values. */
+type FlyAction = "forward" | "back" | "left" | "right" | "up" | "down" | "sprint";
+/**
+ * Creative-flight camera controls: WASD moves horizontally along the view direction, space and shift
+ * move up and down, R sprints, and the mouse turns the camera (pointer lock, or drag).
+ *
+ * Call {@link FlyControls.update} with the elapsed seconds once per frame; the `change` event marks the
+ * renderer dirty while keys are held. Speeds use scene units (16 per block). The element becomes focusable
+ * and keys apply while it has focus or the pointer is locked. A key pressed with Control, Alt, or Command
+ * stays a browser shortcut unless that modifier is bound. The wheel changes the speed, as in vanilla
+ * spectator mode. Touch input uses the left half of the element as a joystick and the right half for looking.
+ */
+declare class FlyControls extends Controls<FlyControlsEventMap, Camera> {
+    readonly isFlyControls: true;
+    /** Horizontal and vertical speed in scene units per second; vanilla creative flight by default. */
+    movementSpeed: number;
+    /** Speed multiplier while the sprint key is held. */
+    sprintMultiplier: number;
+    /** Radians per pixel of pointer movement. */
+    lookSpeed: number;
+    /** Smooth acceleration and deceleration, approximating vanilla flight momentum. */
+    enableDamping: boolean;
+    /** Portion of the remaining velocity change applied per 60 Hz frame (0–1) when damping is enabled. */
+    dampingFactor: number;
+    /** Capture the pointer on click so the mouse turns the camera without dragging; dragging works regardless. */
+    pointerLock: boolean;
+    /** Scroll the wheel to change `movementSpeed` within `speedRange`. */
+    enableWheelSpeed: boolean;
+    /** Minimum and maximum `movementSpeed` reachable with the wheel. */
+    speedRange: [number, number];
+    /** Touch joystick travel in CSS pixels for full speed. */
+    joystickRadius: number;
+    /** Key bindings by `KeyboardEvent.code`. */
+    keys: Record<FlyAction, string[]>;
+    private readonly _pressed;
+    private readonly _velocity;
+    private readonly _lastPosition;
+    private readonly _lastQuaternion;
+    private _position0;
+    private _quaternion0;
+    private _dragPointer?;
+    private _dragX;
+    private _dragY;
+    private _dragMoved;
+    private _dragTravel;
+    private _joystick?;
+    private _locked;
+    private _madeFocusable;
+    private _lastTime?;
+    private readonly _onKeyDown;
+    private readonly _onKeyUp;
+    private readonly _onPointerDown;
+    private readonly _onPointerMove;
+    private readonly _onPointerUp;
+    private readonly _onPointerLockChange;
+    private readonly _onContextMenu;
+    private readonly _onWheel;
+    private readonly _onBlur;
+    constructor(camera: Camera, domElement?: HTMLElement | null);
+    connect(element: HTMLElement): void;
+    disconnect(): void;
+    dispose(): void;
+    /** Whether mouse look currently owns the pointer. */
+    get locked(): boolean;
+    /** Requests pointer capture; browsers only allow this from a user gesture. */
+    lock(): void;
+    /** Releases a captured pointer. */
+    unlock(): void;
+    /** Stores the camera pose that {@link reset} restores. */
+    saveState(): void;
+    /** Restores the saved camera pose and stops movement. */
+    reset(): void;
+    /** Horizontal yaw in radians, where zero looks toward -Z. */
+    get yaw(): number;
+    /** Vertical pitch in radians, positive looking up. */
+    get pitch(): number;
+    /** Turns the camera; pitch is clamped to straight up and down. */
+    setRotation(yaw: number, pitch: number): void;
+    /** Points the camera at a position without rolling it. */
+    lookAt(target: Vector3): void;
+    /** Whether an action's key is held. */
+    isPressed(action: FlyAction): boolean;
+    /**
+     * Advances movement by `delta` seconds (measured since the previous call when omitted)
+     * and dispatches `change` when the camera moved.
+     * A step longer than 0.1 s is applied as 0.1 s.
+     */
+    update(delta?: number): void;
+    private move;
+    private notifyChange;
+    private releaseKeys;
+    private handleKey;
+    /** A key pressed with Control, Alt, or Command stays a browser shortcut unless that modifier is bound to an action. */
+    private isBrowserShortcut;
+    private actionFor;
+    private handlePointerDown;
+    private onJoystickSide;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleWheel;
+    private handlePointerLockChange;
+    private turn;
+}
+declare function isFlyControls(obj: any): obj is FlyControls;
+
 /**
  * Renders a Minecraft scene with a camera and an optional effects composer.
- * Requires a browser DOM and WebGL. Call {@link appendTo} to attach the canvas,
- * then {@link start} to render scene changes.
+ * Uses a browser canvas by default, or a caller-supplied {@link RendererSurface}.
+ * Call {@link start} for browser animation or {@link renderOnce} for a single frame.
  */
 declare class Renderer implements Disposable {
     static readonly DEFAULT_OPTIONS: RendererOptions;
     readonly options: RendererOptions;
     protected _element?: HTMLElement;
+    private readonly _surface?;
+    private _width;
+    private _height;
     protected _scene: MineRenderScene;
     protected _camera: Camera;
     protected _renderer: WebGLRenderer;
     protected _composer?: EffectComposer;
-    protected _controls?: OrbitControls;
+    protected _controls?: RendererControls;
+    private _controlsTime?;
+    private _orbitDistance?;
     protected _stats?: Stats;
     protected _dirty: boolean;
     protected _animationLoop: any;
@@ -2632,16 +3054,29 @@ declare class Renderer implements Disposable {
     private _running;
     private _inAnimationLoop;
     private _disposed;
+    private _videoExporter?;
     private readonly _frameCallbacks;
     private readonly _debugHelpers;
     private readonly _eventDispatchers;
     private readonly _changeListener;
-    constructor(options?: DeepPartial<RendererOptions>);
+    constructor(options?: DeepPartial<RendererOptions>, surface?: RendererSurface);
     protected createScene(): MineRenderScene;
     protected createCamera(): Camera;
     protected createRenderer(): WebGLRenderer;
     protected createComposer(): Maybe<EffectComposer>;
-    protected createControls(): Maybe<OrbitControls>;
+    protected createControls(): Maybe<RendererControls>;
+    private initialTarget;
+    private createControlsFor;
+    /**
+     * Replaces renderer-owned controls with the selected mode, keeping the camera where it is.
+     * Switching to orbit controls targets the point the camera looks at, at the previous orbit distance.
+     * The previous controls object is disposed, so its listeners and settings do not carry over.
+     * Returns the new controls, or undefined when controls were disabled at construction or after disposal.
+     */
+    setControlsMode(mode: ControlsMode): Maybe<RendererControls>;
+    private disposeControls;
+    /** Advances owned controls; without a frame time, flight movement does not progress. */
+    private updateControls;
     init(): void;
     get element(): Maybe<HTMLElement>;
     /** Attaches the canvas to an element and sizes it to that element's dimensions. */
@@ -2651,8 +3086,10 @@ declare class Renderer implements Disposable {
      * The renderer removes its listener on disposal; the caller retains ownership of the dispatcher.
      */
     registerEventDispatcher(dispatcher: EventDispatcher<any>, changeEvent?: string): void;
+    private unregisterEventDispatcher;
     /** Updates the camera and canvas size. Width and height are in CSS pixels. */
     resize(width: number, height: number): void;
+    private validateSurfaceSize;
     get dirty(): boolean;
     set dirty(dirty: boolean);
     /**
@@ -2661,9 +3098,9 @@ declare class Renderer implements Disposable {
      * Registering the same callback twice has no effect. Image exports do not invoke callbacks.
      */
     onFrame(callback: FrameCallback): () => void;
-    /** Starts or resumes the animation loop and registered frame callbacks. */
+    /** Starts or resumes the animation loop and registered frame callbacks. Has no effect while running. */
     start(): void;
-    /** Pauses rendering and frame callbacks. Call {@link start} to resume. */
+    /** Pauses rendering and frame callbacks, and cancels video export. Call {@link start} to resume. */
     stop(): void;
     /**
      * Stops rendering and releases owned resources. Repeated calls have no effect, and a disposed
@@ -2673,12 +3110,22 @@ declare class Renderer implements Disposable {
     dispose(): void;
     private animate;
     private drawFrame;
+    /** Draws a fresh frame without starting the animation loop or invoking frame callbacks. */
+    renderOnce(): void;
     /**
      * Renders a fresh frame and returns an image data URL, including while the animation loop is stopped.
      * Trimming removes transparent borders; an empty image becomes one transparent pixel.
      * MIME type support and lossy quality (0–1) follow the canvas encoder.
      */
     toImage(trim?: boolean, mime?: string, quality?: number): string;
+    /**
+     * Records a silent browser video in real time, including frame callbacks and animated textures.
+     * Keep the tab visible; browser scheduling and `render.fpsLimit` limit the capture rate.
+     * The video keeps the initial drawing-buffer size and fills transparent pixels with black.
+     * Temporarily starts a stopped renderer. Stop, disposal, or `options.signal` cancels the export.
+     * Only one export can run at a time. Use the returned Blob's type to select a file extension.
+     */
+    toVideo(options: VideoExportOptions): Promise<Blob>;
     /** Exports visible scene meshes as OBJ text, without texture images. */
     toObj(): string;
     /** Exports visible scene meshes as PLY. Set `options.binary` for an ArrayBuffer. */
@@ -2693,7 +3140,23 @@ declare class Renderer implements Disposable {
     get renderer(): WebGLRenderer;
     get composer(): Maybe<EffectComposer>;
     /** Renderer-owned controls, or undefined when disabled at construction or after disposal. */
-    get controls(): Maybe<OrbitControls>;
+    get controls(): Maybe<RendererControls>;
+    /** Renderer-owned OrbitControls, or undefined in fly mode or without controls. */
+    get orbitControls(): Maybe<OrbitControls>;
+    /** Renderer-owned {@link FlyControls}, or undefined in orbit mode or without controls. */
+    get flyControls(): Maybe<FlyControls>;
+    /** The active renderer-owned controls mode, or undefined without controls. */
+    get controlsMode(): Maybe<ControlsMode>;
+}
+/** Caller-owned canvas and WebGL 2 context for rendering without a browser DOM. */
+interface RendererSurface {
+    canvas: Pick<HTMLCanvasElement, "width" | "height" | "addEventListener" | "removeEventListener">;
+    context: WebGL2RenderingContext;
+    /** Initial logical dimensions, before applying `render.pixelRatio`. */
+    width: number;
+    height: number;
+    /** Resizes the native drawing buffer when assigning canvas dimensions is insufficient. */
+    resize?: (drawingBufferWidth: number, drawingBufferHeight: number) => void;
 }
 /** Timing passed to callbacks registered with {@link Renderer.onFrame}. */
 interface RendererFrame {
@@ -2749,9 +3212,15 @@ interface RenderOptions {
 interface ComposerOptions {
     enabled: boolean;
 }
-/** Set `controls: { enabled: true }` in the Renderer constructor to create owned OrbitControls. */
+/** Renderer-owned camera controls: orbiting around a target, or creative-style flight. */
+type ControlsMode = "orbit" | "fly";
+/** Controls created through `controls.enabled`; narrow with `isFlyControls` or {@link Renderer.controlsMode}. */
+type RendererControls = OrbitControls | FlyControls;
+/** Set `controls: { enabled: true }` in the Renderer constructor to create owned controls. */
 interface ControlsOptions {
     enabled: boolean;
+    /** `orbit` (default) creates OrbitControls; `fly` creates {@link FlyControls}. */
+    mode?: ControlsMode;
 }
 /** Scene helpers enabled through `debug` in the Renderer constructor options. */
 interface DebugOptions {
@@ -2863,6 +3332,14 @@ interface SceneBlockDefinition extends SceneObjectDefinitionBase {
         tints?: Record<number, number>;
     };
 }
+/** Supplied item state; see ItemModelContext. Item references are item IDs such as minecraft:apple. */
+interface SceneItemContext {
+    displayContext?: DisplayPosition | "none";
+    properties?: Record<string, boolean | string | number>;
+    components?: Record<string, unknown>;
+    count?: number;
+    itemReferences?: Record<string, string>;
+}
 interface SceneModelDefinition extends SceneObjectDefinitionBase {
     type: "item" | "model";
     asset: string;
@@ -2871,6 +3348,8 @@ interface SceneModelDefinition extends SceneObjectDefinitionBase {
         displayPosition?: DisplayPosition;
         tints?: Record<number, number>;
     };
+    /** Item state for `type: "item"` definitions only. */
+    context?: SceneItemContext;
 }
 interface SceneEntityDefinition extends SceneObjectDefinitionBase {
     type: "entity";
@@ -2894,8 +3373,9 @@ interface SceneEntityDefinition extends SceneObjectDefinitionBase {
 }
 type SceneGuiLayer = (Omit<GuiTextureLayer, "texture"> & {
     texture: string;
-}) | (Omit<GuiItemLayer, "item"> & {
+}) | (Omit<GuiItemLayer, "item" | "context"> & {
     item: string;
+    context?: Omit<SceneItemContext, "displayContext">;
 }) | (Omit<GuiTextLayer, "font"> & {
     font?: string;
 });
@@ -2936,6 +3416,20 @@ declare class SceneDocumentLoader {
     private static loadValidatedObject;
 }
 
+/** Resolves Minecraft profile components to resource textures or shared, prepared player skins. */
+declare class PlayerHeadTextures {
+    /** Resource textures retain their pixels; downloaded skins use the skin pipeline's legacy and opacity rules. */
+    static get(value: unknown, root?: string): Promise<{
+        texture: AssetKey;
+        material?: MeshBasicMaterial;
+    }>;
+    private static resource;
+    private static profile;
+    private static propertyUrl;
+    private static offlineUuid;
+    private static uuidString;
+}
+
 type SkinGeometries = Record<SkinPart, TripleArray>;
 declare const classicSkinGeometries: SkinGeometries;
 declare const slimSkinGeometries: SkinGeometries;
@@ -3007,6 +3501,8 @@ declare class Skins {
 declare class Colormaps {
     /** Samples the selected resource pack's grass colormap using Minecraft's climate coordinates. */
     static grassColor(origin?: AssetKey, temperature?: number, downfall?: number): Promise<number>;
+    /** Samples a resource-pack colormap at the supplied climate coordinates. */
+    static getColor(kind: "grass" | "foliage" | "dry_foliage", origin?: AssetKey, temperature?: number, downfall?: number): Promise<number>;
 }
 
 /** Creates sRGB textures immediately and fills their pixels after asynchronous image loading. */
@@ -3042,6 +3538,7 @@ declare function mergeVertices(geometry: BufferGeometry, tolerance?: number): Bu
 declare function toTrianglesDrawMode(geometry: BufferGeometry, drawMode: TrianglesDrawModes): BufferGeometry;
 declare function computeMorphedAttributes(object: Mesh | Line | Points): object;
 
+type PaletteState = Readonly<Pick<Block, "type" | "properties">>;
 /** Stores 4,096 block cells in a shared state palette, with separate NBT for each cell. */
 declare class ChunkData {
     private readonly indices;
@@ -3055,13 +3552,46 @@ declare class ChunkData {
     snapshot(index: number): Maybe<() => Block>;
     /** Copies block data into a cell. An omitted block or an air block clears the cell. */
     set(index: number, block?: Block): void;
+    /** Interns a normalized block state without changing cells. Air has palette id 0. */
+    intern(block: Maybe<Block>): number;
+    /** Assigns an interned state to a cell and replaces its NBT. `undefined` clears the NBT. */
+    assign(index: number, id: number, nbt?: unknown): void;
+    /** Replaces all cells from palette indices, normalizes air to 0, and clears NBT. */
+    fill(palette: readonly Maybe<Block>[], indices: Uint16Array): void;
+    /** Returns a cell's palette id, or 0 for air. */
+    idAt(index: number): number;
+    /** Returns a frozen state, or `undefined` for air or a freed palette id. */
+    stateAt(id: number): PaletteState | undefined;
+    /** Replaces cells, palette entries, and NBT with independent copies of another section. */
+    copyFrom(other: ChunkData): void;
     clear(): void;
     static isAir(block: Maybe<Block>): boolean;
+    /** Identifies a normalized block type and its sorted properties, excluding per-cell NBT. */
+    static paletteKey(block: Block): string;
     private static copyBlock;
     private static validateIndex;
 }
 
 type RegionInput = Uint8Array | ArrayBuffer;
+/** Reads `c.<x>.<z>.mcc` at absolute chunk coordinates, or returns `undefined` when the file is missing. */
+type AnvilExternalChunkReader = (x: number, z: number, signal?: AbortSignal) => Promise<Uint8Array | ArrayBuffer | undefined>;
+interface AnvilParseOptions {
+    /** Asset root used to select numeric block mappings. Omit to use the active asset sources. */
+    root?: string;
+    /** Overrides numeric `id:metadata` mappings with block states such as `minecraft:oak_log[axis=x]`. */
+    legacyMappings?: Readonly<Record<string, string>>;
+    /** For numeric blocks, tries metadata 0 for unmapped states and skips unknown IDs. Defaults to false. */
+    lenient?: boolean;
+    /** Region coordinates from `r.<x>.<z>.mca`, required when reading external chunks. */
+    region?: {
+        x: number;
+        z: number;
+    };
+    /** Reads external chunk payloads without their region-file header. */
+    readExternalChunk?: AnvilExternalChunkReader;
+    /** Cancels parsing and forwards the signal to external chunk reads. */
+    signal?: AbortSignal;
+}
 /** Chunk columns decoded from an Anvil region file. */
 interface AnvilRegion {
     chunks: AnvilChunk[];
@@ -3071,37 +3601,104 @@ interface AnvilChunk {
     x: number;
     z: number;
     dataVersion?: number;
+    /** DataVersion of the separate entity-region record; `dataVersion` belongs to the terrain. */
+    entityDataVersion?: number;
     sections: {
         y: number;
         data: ChunkData;
+        /** 64 saved biome IDs, indexed by x + z * 4 + y * 16 at 4-block resolution. */
+        biomes?: readonly string[];
     }[];
     entities?: MultiBlockEntity[];
 }
-/** Reads Java 1.13+ paletted `.mca` regions. Entity NBT is preserved without data-version migration. */
+/** Entities decoded from an entity region, with absolute chunk coordinates. */
+interface AnvilEntityChunk {
+    x: number;
+    z: number;
+    dataVersion?: number;
+    entities: MultiBlockEntity[];
+}
+/** Reads numeric and paletted Java terrain and entity `.mca` regions without data-version migration. */
 declare class AnvilParser {
     /** Lists occupied chunk positions within the region, using local coordinates from 0 to 31. */
     static getChunkList(data: RegionInput): {
         x: number;
         z: number;
     }[];
-    /** Decodes all stored chunks. Gzip, zlib, and uncompressed payloads are supported. */
-    static parse(data: RegionInput): Promise<AnvilRegion>;
+    /** Decodes all stored chunks. Gzip, zlib, LZ4, and uncompressed payloads are supported. */
+    static parse(data: RegionInput, options?: AnvilParseOptions): Promise<AnvilRegion>;
     /**
      * Decodes one chunk for {@link MineRenderWorld.placeChunk}.
      * @param localX - Chunk x within the region, from 0 to 31.
      * @param localZ - Chunk z within the region, from 0 to 31.
      * @returns The chunk with absolute coordinates, or `undefined` if the region has no chunk there.
      */
-    static parseChunk(data: RegionInput, localX: number, localZ: number): Promise<AnvilChunk | undefined>;
+    static parseChunk(data: RegionInput, localX: number, localZ: number, options?: AnvilParseOptions): Promise<AnvilChunk | undefined>;
+    /**
+     * Decodes one chunk from an `entities/r.x.z.mca` file without migrating its NBT.
+     * @param localX - Chunk x within the region, from 0 to 31.
+     * @param localZ - Chunk z within the region, from 0 to 31.
+     * @returns The entities with absolute chunk coordinates, or `undefined` if no chunk is stored there.
+     */
+    static parseEntityChunk(data: RegionInput, localX: number, localZ: number, options?: AnvilParseOptions): Promise<AnvilEntityChunk | undefined>;
+    private static location;
+    private static abortable;
     private static bytes;
     private static locations;
+    private static readNBT;
     private static readChunk;
+    private static numericSection;
+    private static entities;
+    private static biomes;
     private static compounds;
     private static integer;
     private static block;
     private static unpack;
 }
 
+/** Loads chunk columns at absolute integer chunk coordinates. */
+interface WorldChunkSource {
+    /** Returns the requested column, or `undefined` if absent. Honor signal to cancel discarded reads. */
+    getChunk(x: number, z: number, signal?: AbortSignal): Promise<AnvilChunk | undefined>;
+}
+
+/**
+ * Reads `r.<x>.<z>.mca` at integer region coordinates, or returns `undefined` when absent.
+ * Forward `signal` to file or network I/O; it aborts when every caller waiting for the region cancels.
+ */
+type AnvilRegionReader = (x: number, z: number, signal?: AbortSignal) => Promise<Uint8Array | ArrayBuffer | undefined>;
+/** Readers and cache limits passed to `new AnvilWorldSource(readRegion, options)`. */
+interface AnvilWorldSourceOptions extends Pick<AnvilParseOptions, "readExternalChunk" | "legacyMappings" | "lenient" | "root"> {
+    /** Reads a dimension's separate `entities/r.<x>.<z>.mca` files. Omit to use embedded entities only. */
+    readEntityRegion?: AnvilRegionReader;
+    /** Maximum cached regions per kind (terrain and entities), including missing regions. Defaults to 4 each; 0 disables caching. */
+    maxCachedRegions?: number;
+    /** Maximum retained bytes across both region types. Defaults to 64 MiB; larger regions are read without caching. */
+    maxCachedBytes?: number;
+}
+/** Reads selected Java Anvil chunk columns and caches raw regions within count and byte limits. */
+declare class AnvilWorldSource implements WorldChunkSource {
+    private readonly readRegion;
+    private readonly regions;
+    private readonly pending;
+    private readonly maxCachedRegions;
+    private readonly maxCachedBytes;
+    private readonly readEntityRegion?;
+    private readonly parseOptions;
+    private cachedBytes;
+    constructor(readRegion: AnvilRegionReader, options?: AnvilWorldSourceOptions);
+    /**
+     * Decodes a column at absolute chunk coordinates, including entity-only columns.
+     * A separate entity record replaces embedded entities, even when its list is empty.
+     * Missing entity files or records leave embedded entities intact. Aborting a caller leaves other shared readers active.
+     */
+    getChunk(x: number, z: number, signal?: AbortSignal): Promise<AnvilChunk | undefined>;
+    /** Releases cached regions. Reads already in progress finish without repopulating this cache. */
+    clearCache(): void;
+    private getRegion;
+    private cacheRegion;
+}
+
 /** A placed block's data snapshot and optional render object, returned by world and chunk accessors. */
 interface BlockInfo<SectionMeshing extends boolean = false> {
     /** Detached block data; use world or chunk setters to update stored blocks. */
@@ -3110,11 +3707,13 @@ interface BlockInfo<SectionMeshing extends boolean = false> {
     object: SectionMeshing extends false ? BlockObject : BlockObject | undefined;
 }
 
-/** Shared cube geometry and atlas data prepared for section merging. */
+/** Shared quad geometry and atlas data prepared for section merging. */
 interface SectionMeshTemplate {
     geometry: BufferGeometry;
     atlas: TextureAtlas;
-    cullFaces: readonly number[];
+    cullFaces: Uint8Array;
+    occludes: boolean;
+    layer: 0 | 1;
 }
 /** One block placement in a section, with its storage index and hidden-face mask. */
 interface SectionMeshEntry {
@@ -3122,24 +3721,44 @@ interface SectionMeshEntry {
     template: SectionMeshTemplate;
     cullMask: number;
 }
+/** Fluid cells for one section and the shared atlases of the kinds present. */
+interface SectionFluids {
+    cells: Uint8Array;
+    /** Linear RGB per section cell, indexed by (x + 16z + 256y) * 3. */
+    waterTints?: Float32Array;
+    water?: TextureAtlas;
+    lava?: TextureAtlas;
+}
 /** Merged terrain geometry and atlas pages for one 16×16×16 section. Owns its generated render resources. */
 declare class SectionMesh extends Group {
     private readonly ownedMeshes;
-    /** Builds section-local meshes from visible cube faces. `maxAtlasSize` limits each atlas dimension in pixels. */
-    static build(entries: readonly SectionMeshEntry[], maxAtlasSize?: number): SectionMesh;
+    /** Builds section-local meshes from visible quads. `maxAtlasSize` limits each atlas dimension in pixels. */
+    static build(entries: readonly SectionMeshEntry[], maxAtlasSize?: number, fluids?: SectionFluids): SectionMesh;
+    /** Builds section-local meshes in a browser worker when available, with synchronous fallback. */
+    static buildAsync(entries: readonly SectionMeshEntry[], maxAtlasSize?: number, fluids?: SectionFluids): Promise<SectionMesh>;
+    private static fromPages;
     dispose(): void;
 }
 
-/** Prepares and caches static opaque cube geometry for merged world sections. */
+/** Prepares and caches model geometry and fluid atlases for merged world sections. */
 declare class SectionModels {
     readonly maxAtlasSize: number;
     private states;
     private models;
     private readonly templates;
+    private readonly fluidAtlases;
     constructor(maxAtlasSize?: number);
-    /** Returns a cube template, or `undefined` when the block requires an individual render object. */
-    get(blockState: BlockState, properties?: BlockStateProperties): Promise<SectionMeshTemplate | undefined>;
+    /** Returns templates for the matched parts, or `undefined` when the block needs an individual render object. */
+    get(blockState: BlockState, properties?: BlockStateProperties, position?: Readonly<TripleArray>, biome?: string): Promise<SectionMeshTemplate[] | undefined>;
+    /** Resolves section templates for one tint palette, with a synchronous weighted choice for each cell. */
+    prepareState(blockState: BlockState, properties?: BlockStateProperties, biomeColor?: number | (() => Promise<number | undefined>)): Promise<{
+        pick(position?: Readonly<TripleArray>): SectionMeshTemplate[];
+    } | undefined>;
+    private state;
+    /** Returns the shared still/flow atlas used by per-block fluid objects. */
+    fluidAtlas(kind: FluidKind, root?: string): Promise<TextureAtlas>;
     private prepare;
+    private template;
     /** Disposes prepared geometry and clears this world's template caches. */
     clear(): void;
 }
@@ -3152,6 +3771,9 @@ declare class SectionModels {
 declare class Chunk<SectionMeshing extends boolean = false> {
     private readonly onBlocksChanged?;
     private readonly sectionModels?;
+    private readonly neighborCell?;
+    private readonly biomeAt?;
+    private readonly onBiomesChanged?;
     readonly scene: MineRenderScene;
     readonly x: number;
     readonly y: number;
@@ -3160,12 +3782,25 @@ declare class Chunk<SectionMeshing extends boolean = false> {
     private readonly renderedBlocks;
     private readonly sectionBlocks;
     private readonly hiddenBlocks;
+    private readonly fluidCells;
+    private readonly blockPosition;
+    private waterTints?;
+    private biomes?;
     private sectionMesh?;
     private meshDirty;
-    constructor(scene: MineRenderScene, x: number, y: number, z: number, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined, sectionModels?: SectionModels | undefined);
+    private meshGeneration;
+    constructor(scene: MineRenderScene, x: number, y: number, z: number, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined, sectionModels?: SectionModels | undefined, neighborCell?: ((x: number, y: number, z: number) => number) | undefined, biomeAt?: ((x: number, y: number, z: number) => Maybe<string>) | undefined, onBiomesChanged?: ((biomes?: readonly string[]) => Promise<void>) | undefined);
     getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
+    /** Returns the saved 4-block biome sample at integer world block coordinates, or `undefined` if absent. */
+    getBiomeAt(x: number, y: number, z: number): Maybe<string>;
+    getBiomeAt(pos: Vector3): Maybe<string>;
+    getBiomeAt(pos: TripleArray): Maybe<string>;
+    /** Copies 64 biome IDs in x + z * 4 + y * 16 order and refreshes placed blocks. Omit the array to clear biome data. */
+    setBiomes(biomes?: readonly string[]): Promise<void>;
+    /** Rebuilds biome-tinted blocks while preserving hidden blocks and unrelated render objects. */
+    refreshBiomes(): Promise<void>;
     /**
      * Places a block at integer world block coordinates. Pass `undefined` to remove it.
      */
@@ -3176,14 +3811,38 @@ declare class Chunk<SectionMeshing extends boolean = false> {
      * Places a block at integer chunk-local coordinates from 0 to 15.
      */
     setBlockInChunkAt(pos: Vector3, block?: Block, worldPos?: Vector3, onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<Maybe<BlockInfo<SectionMeshing>>>;
+    /** Places cells in input order and returns changed world positions without refreshing neighbors. */
+    placeBlocks(blocks: readonly {
+        index: number;
+        block: Maybe<Block>;
+    }[]): Promise<Vector3[]>;
+    /** Replaces every cell from parsed section data. The caller refreshes neighbor culling. */
+    placeSection(data: ChunkData): Promise<void>;
+    private positionAt;
+    private biomePosition;
+    private resolveState;
+    private setWaterTint;
     /** Changes visibility at world block coordinates while preserving the block's data. */
     setBlockVisibleAt(pos: Vector3, visible: boolean): Promise<void>;
     isBlockVisibleAt(pos: Vector3): boolean;
+    /** Reports whether a cell has a visible render object or section entry. */
+    isBlockVisibleIndex(index: number): boolean;
+    /** Fluid kind bits and level of a cell, or 0. Hidden cells report 0. */
+    fluidByteIndex(index: number): number;
+    /** Whether the cell holds a fluid, merged or per-block. */
+    isFluidIndex(index: number): boolean;
     isOccludingAt(pos: Vector3): boolean;
+    /** Reports whether a visible cell hides neighboring cube faces. */
+    isOccludingIndex(index: number): boolean;
     setCullMaskAt(pos: Vector3, mask: number): Promise<void>;
-    rebuildSectionMesh(): void;
-    /** Removes stored blocks and their render objects, then notifies the owning world of changed positions. */
-    clear(onBlocksChanged?: ((positions: Vector3[]) => Promise<void>) | undefined): Promise<void>;
+    /** Recomputes section masks and returns changed per-block masks. Omit indices to visit every cell. */
+    updateCullMasks(indices: Iterable<number> | undefined, occludes: (x: number, y: number, z: number) => boolean): [number, number][];
+    /** Updates hidden faces for a cell's section entry or individual render object. */
+    setCullMaskIndex(index: number, mask: number): Promise<void>;
+    /** Rebuilds visible section geometry and discards results superseded by another rebuild or clear. */
+    rebuildSectionMesh(): Promise<void>;
+    /** Removes stored blocks and render objects. Set `notify` to false to skip the owning world's update. */
+    clear(notify?: boolean): Promise<void>;
     dispose(): Promise<void>;
     static isAir(block: Maybe<Block>): boolean;
     /** Maps chunk-local coordinates from 0 to 15 to a storage index, with x varying fastest, then z, then y. */
@@ -3200,7 +3859,9 @@ declare class Chunk<SectionMeshing extends boolean = false> {
 declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     readonly scene: MineRenderScene;
     private readonly _chunks;
+    private readonly biomes;
     private readonly sectionModels?;
+    private readonly entities?;
     private readonly pendingCulling;
     private culling?;
     constructor(scene: MineRenderScene, options?: MineRenderWorldOptions<SectionMeshing>);
@@ -3208,6 +3869,10 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     getBlockAt(x: number, y: number, z: number): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: Vector3): Maybe<BlockInfo<SectionMeshing>>;
     getBlockAt(pos: TripleArray): Maybe<BlockInfo<SectionMeshing>>;
+    /** Returns the saved 4-block biome sample at integer world block coordinates, or `undefined` if absent. */
+    getBiomeAt(x: number, y: number, z: number): Maybe<string>;
+    getBiomeAt(pos: Vector3): Maybe<string>;
+    getBiomeAt(pos: TripleArray): Maybe<string>;
     /**
      * Places or replaces a block and refreshes neighboring faces.
      * Pass `undefined` or an air block to remove the block at these world block coordinates.
@@ -3225,22 +3890,24 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
     setBlockVisibleAt(pos: TripleArray, visible: boolean): Promise<void>;
     /**
      * Places a structure's blocks at their stored positions, then refreshes neighboring faces.
-     * Entity NBT is retained by the structure but is not rendered.
+     * With `renderEntities`, also places supported saved mobs and applies supported appearance fields.
      *
-     * @param useBatches - Uses bounded batches by default. Set to `false` for sequential placement.
+     * @param useBatches - Yields between chunks by default. Set to `false` for sequential placement.
      * @param executor - Optional queue for batched placement. The caller remains responsible for stopping it.
      */
     placeMultiBlock(multiblock: MultiBlockStructure, useBatches?: boolean, executor?: BatchedExecutor): Promise<void>;
     private placeBlocks;
-    /** Replaces one chunk column's blocks. Entity NBT remains available on the parsed chunk. */
+    private placeChunkGroups;
+    /** Replaces a chunk column's blocks and biome samples and, with `renderEntities`, its supported saved mobs. */
     placeChunk(chunk: AnvilChunk, executor?: BatchedExecutor): Promise<void>;
     /**
-     * Removes all sections at integer chunk-column coordinates, then refreshes neighboring faces and fluids.
+     * Removes blocks and owned entities at chunk-column coordinates, then refreshes neighboring faces and fluids.
      * Coordinates match AnvilChunk.x/z, not block positions. Missing columns are ignored.
      */
     unloadChunkColumn(x: number, z: number): Promise<void>;
     private clearChunkColumn;
-    /** Removes all chunks and releases their block placements and section meshes. */
+    private markSectionChanged;
+    /** Removes all chunks and releases their blocks, section meshes, and owned entities. */
     clear(): Promise<void>;
     private updateCulling;
     private getOrCreateChunkAt;
@@ -3255,12 +3922,166 @@ declare class MineRenderWorld<SectionMeshing extends boolean = false> {
 }
 /** Settings passed as the second argument to `new MineRenderWorld(scene, options)`. */
 interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
+    /** Render supported saved mobs at their position and yaw, including supported appearance fields. Defaults to false. */
+    renderEntities?: boolean;
     /** Merge static opaque cubes into section meshes. Merged blocks have no individual object. */
     sectionMeshing?: SectionMeshing;
     /** Maximum width and height of each section atlas page, in pixels. */
     maxAtlasSize?: number;
 }
 
+/** Static model geometry as quads: four vertices per quad, in quad order. */
+interface SectionTemplateData {
+    quads: number;
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    uvBounds: Float32Array;
+    colors: Float32Array;
+    indices: Uint16Array;
+    cullFaces: Uint8Array;
+    atlas: number;
+    layer: number;
+}
+/** The pixel dimensions and animation state of a source atlas. */
+interface SectionAtlasSize {
+    width: number;
+    height: number;
+    animated: boolean;
+}
+/** One fluid kind's sprite rectangles in atlas pixels and its linear-light vertex tint. */
+interface SectionFluidKind {
+    atlas: number;
+    still: [x: number, y: number, width: number, height: number];
+    flow: [x: number, y: number, width: number, height: number];
+    tint: [r: number, g: number, b: number];
+}
+/** Fluid cells of the section plus a one-cell shell, 18×18×18, x fastest, then z, then y. */
+interface SectionFluidInput {
+    /** Bit 128 marks a surface rendered elsewhere; the cell still supplies neighbor fluid samples. */
+    cells: Uint8Array;
+    /** Linear RGB per section cell, indexed by (x + 16z + 256y) * 3. Omission uses the water kind's tint. */
+    waterTints?: Float32Array;
+    water?: SectionFluidKind;
+    lava?: SectionFluidKind;
+}
+/** Section placements and their shared templates, ready for geometry building. */
+interface SectionGeometryInput {
+    count: number;
+    indices: Uint16Array;
+    templates: Uint16Array;
+    cullMasks: Uint8Array;
+    templateData: SectionTemplateData[];
+    atlases: SectionAtlasSize[];
+    maxAtlasSize: number;
+    fluids?: SectionFluidInput;
+}
+/** Merged quads and source-atlas placements for one atlas page. */
+interface SectionGeometryPage {
+    layer: number;
+    width: number;
+    height: number;
+    placements: {
+        atlas: number;
+        x: number;
+        y: number;
+    }[];
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    uvBounds: Float32Array;
+    colors: Float32Array;
+    indices: Uint32Array;
+}
+/** Builds section-local geometry from visible quads, with bounded atlas pages per layer. */
+declare function buildSectionGeometry(input: SectionGeometryInput): SectionGeometryPage[];
+/** Returns the buffers behind each page's typed arrays for transfer to another thread. */
+declare function sectionGeometryTransferables(pages: readonly SectionGeometryPage[]): ArrayBuffer[];
+
+/** Runs section geometry builds in the environment's shared worker. */
+declare class SectionWorker {
+    private worker;
+    private static initialized;
+    private static instance;
+    private nextId;
+    private readonly pending;
+    private constructor();
+    /** The shared worker, or undefined when the environment has none or a previous worker failed. */
+    static shared(): SectionWorker | undefined;
+    /** Builds geometry without transferring the input buffers away from the caller. */
+    build(input: SectionGeometryInput): Promise<SectionGeometryPage[]>;
+    /** Rejects pending builds, terminates the worker, and makes shared() return undefined. */
+    terminate(): void;
+    private fail;
+}
+
+interface WorldStreamerOptions {
+    /** Loads a square of chunk columns around the center. Integer from 0 to 32; defaults to 2. */
+    loadRadius?: number;
+    /** Retains loaded columns within this radius. Defaults to loadRadius + 1, capped at 32. */
+    unloadRadius?: number;
+}
+/**
+ * Loads nearby chunk columns in distance order and unloads distant columns.
+ * Updates coalesce to the latest center and serialize world mutations. Use a dedicated world:
+ * the streamer replaces columns it loads, and callers must await disposal before editing that world.
+ * The source remains caller-owned. Lighting, biome tint, and LOD are not added by streaming.
+ */
+declare class WorldStreamer {
+    private readonly world;
+    private readonly source;
+    private readonly loadRadius;
+    private readonly unloadRadius;
+    private readonly loaded;
+    private readonly owned;
+    private readonly missing;
+    private readonly failed;
+    private desired;
+    private center?;
+    private loading?;
+    private running?;
+    private disposal?;
+    private disposed;
+    constructor(world: Pick<MineRenderWorld<boolean>, "placeChunk" | "unloadChunkColumn">, source: WorldChunkSource, options?: WorldStreamerOptions);
+    /** Returns absolute coordinates of successfully placed columns, including retained columns. */
+    get loadedChunks(): readonly {
+        x: number;
+        z: number;
+    }[];
+    /** Returns source failures retained within the unload radius. Failed columns do not block other loads. */
+    get failedChunks(): readonly {
+        x: number;
+        z: number;
+        error: unknown;
+    }[];
+    /** Counts desired columns still waiting for a source read or placement, including the active column. */
+    get pendingChunks(): number;
+    /**
+     * Updates the center in absolute chunk coordinates. Repeated calls share the active drain.
+     * Source failures are recorded in failedChunks; other columns continue loading. Missing and failed
+     * columns are remembered within the retention radius. Call retryFailedChunks to retry source failures.
+     * Placement and unload failures reject the drain; call update again to retry those operations.
+     * Reads outside the latest load radius receive an abort signal; placement finishes before unloading.
+     * Sources should represent an unchanged world during streaming.
+     */
+    update(x: number, z: number): Promise<void>;
+    /** Updates from a camera or view-center position in scene units. One chunk spans 256 scene units. */
+    updatePosition(position: {
+        x: number;
+        z: number;
+    }): Promise<void>;
+    /** Forgets recorded source failures and retries desired columns at the latest center. */
+    retryFailedChunks(): Promise<void>;
+    /** Aborts source reads, waits for active work, then unloads owned columns. The world and source remain caller-owned. */
+    dispose(): Promise<void>;
+    private drain;
+    private needsLoad;
+    private unload;
+    private validateChunk;
+    private within;
+    private key;
+}
+
 /**
  * {@link EnvProvider} for headless Node.
  *
@@ -3300,4 +4121,38 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, type BannerPattern, type BannerPatternDraw, BannerPatterns, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, DYE_COLORS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, type DyeColor, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelContext, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+/** Renderer settings and logical image dimensions for {@link NodeRenderer.create}. */
+type NodeRendererOptions = DeepPartial<RendererOptions> & {
+    width: number;
+    height: number;
+};
+/** PNG export settings for {@link NodeRenderer.renderToBuffer}. */
+interface NodeImageOptions {
+    /** Removes transparent borders. An empty image becomes one transparent pixel. */
+    trim?: boolean;
+}
+/** Renders individual frames in Node using an injected or factory-owned WebGL 2 context. */
+declare class NodeRenderer extends Renderer {
+    private destroyContext?;
+    private nodeDisposed;
+    /**
+     * Uses a caller-owned surface; alpha-enabled contexts require `premultipliedAlpha: true`.
+     * Disposal releases renderer resources but retains the canvas and context.
+     */
+    constructor(options: DeepPartial<RendererOptions>, surface: RendererSurface);
+    /**
+     * Creates an owned native context through the optional `gl` package. Dimensions are in logical pixels.
+     * Native antialiasing is unavailable; increase `render.pixelRatio` for a larger output image.
+     */
+    static create(options: NodeRendererOptions): Promise<NodeRenderer>;
+    /** Draws and returns a PNG with straight alpha, including while stopped. Frame callbacks are not invoked. */
+    renderToBuffer(options?: NodeImageOptions): Promise<Buffer$1>;
+    /** Node renderers draw on demand. Use {@link renderOnce} or {@link renderToBuffer}. */
+    start(): never;
+    /** Node image capture returns encoded bytes through {@link renderToBuffer}. */
+    toImage(_trim?: boolean, _mime?: string, _quality?: number): never;
+    /** Releases renderer resources and destroys contexts created by {@link create}. */
+    dispose(): void;
+}
+
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, type AnvilEntityChunk, type AnvilExternalChunkReader, type AnvilParseOptions, AnvilParser, type AnvilRegion, type AnvilRegionReader, AnvilWorldSource, type AnvilWorldSourceOptions, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, type BannerPattern, type BannerPatternDraw, BannerPatterns, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type Biome, type BiomeColorKind, Biomes, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsMode, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, DYE_COLORS, type DebugOptions, type DecoratedPotSide, DecoratedPots, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, type DyeColor, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidQuads, type FluidRules, type FluidSample, type FluidSampler, type FlyAction, FlyControls, type FlyControlsEventMap, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, ItemDefaults, ItemGlint, type ItemModel, type ItemModelContext, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, LitematicaParser, type LitematicaRegion, type LitematicaStructure, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderData, type MineRenderDataManifest, type MineRenderDatasets, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, type NodeImageOptions, NodeRenderer, type NodeRendererOptions, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, PlayerHeadTextures, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererControls, type RendererFrame, type RendererOptions, type RendererSurface, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResolvedMineRenderData, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneItemContext, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, type SectionAtlasSize, type SectionFluidInput, type SectionFluidKind, type SectionFluids, type SectionGeometryInput, type SectionGeometryPage, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type SectionTemplateData, SectionWorker, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, SpongeSchematicParser, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, type VideoExportOptions, VideoExporter, type WorldChunkSource, WorldStreamer, type WorldStreamerOptions, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, buildFluidQuads, buildSectionGeometry, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, fluidKindOf, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isFlyControls, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isResourceLocation, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, resolveBlockFluidState, resolveLegacyBlock, resolveLegacyBlockState, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, sectionGeometryTransferables, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas, yieldToEventLoop };