minerender 2.1.0-alpha.86 → 2.1.0-alpha.87

package/dist/browser/index.d.mts

@@ -3156,6 +3156,41 @@ declare class AnvilParser {
     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>;
+/** Cache limits passed to `new AnvilWorldSource(readRegion, options)`. */
+interface AnvilWorldSourceOptions {
+    /** Maximum cached regions, including missing regions. Defaults to 4; 0 disables caching. */
+    maxCachedRegions?: number;
+    /** Maximum retained region bytes. 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 cachedBytes;
+    constructor(readRegion: AnvilRegionReader, options?: AnvilWorldSourceOptions);
+    /** Decodes one column at absolute chunk coordinates. 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. */
@@ -3315,6 +3350,73 @@ interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
     maxAtlasSize?: number;
 }
 
+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} backed by the DOM. Uses nothing outside of standard browser APIs and
  * localforage, so it stays free of Node polyfills.
@@ -3352,4 +3454,4 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 
-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, BrowserCache, BrowserEnv, 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, 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, type VideoExportOptions, VideoExporter, 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, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, 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 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, BrowserCache, BrowserEnv, 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, 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, type VideoExportOptions, VideoExporter, type WorldChunkSource, WorldStreamer, type WorldStreamerOptions, 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, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };

package/dist/browser/index.d.ts

@@ -3156,6 +3156,41 @@ declare class AnvilParser {
     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>;
+/** Cache limits passed to `new AnvilWorldSource(readRegion, options)`. */
+interface AnvilWorldSourceOptions {
+    /** Maximum cached regions, including missing regions. Defaults to 4; 0 disables caching. */
+    maxCachedRegions?: number;
+    /** Maximum retained region bytes. 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 cachedBytes;
+    constructor(readRegion: AnvilRegionReader, options?: AnvilWorldSourceOptions);
+    /** Decodes one column at absolute chunk coordinates. 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. */
@@ -3315,6 +3350,73 @@ interface MineRenderWorldOptions<SectionMeshing extends boolean = boolean> {
     maxAtlasSize?: number;
 }
 
+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} backed by the DOM. Uses nothing outside of standard browser APIs and
  * localforage, so it stays free of Node polyfills.
@@ -3352,4 +3454,4 @@ declare class BrowserCache extends PersistentCache<LocalForage> {
  */
 declare function probeImageSize(data: Uint8Array): ImageSizeInfo;
 
-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, BrowserCache, BrowserEnv, 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, 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, type VideoExportOptions, VideoExporter, 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, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, 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 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, BrowserCache, BrowserEnv, 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, 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, type VideoExportOptions, VideoExporter, type WorldChunkSource, WorldStreamer, type WorldStreamerOptions, 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, probeImageSize, registerBrowserEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };

package/dist/browser/index.js

@@ -18688,6 +18688,7 @@ var index_browser_exports = {};
 __export(index_browser_exports, {
   AXES: () => AXES,
   AnvilParser: () => AnvilParser,
+  AnvilWorldSource: () => AnvilWorldSource,
   ArchiveAssetSource: () => ArchiveAssetSource,
   AssetKey: () => AssetKey,
   AssetLoadError: () => AssetLoadError,
@@ -18791,6 +18792,7 @@ __export(index_browser_exports, {
   TintColors: () => TintColors,
   UVMapper: () => UVMapper,
   VideoExporter: () => VideoExporter,
+  WorldStreamer: () => WorldStreamer,
   WrappedImage: () => WrappedImage,
   addBox3WireframeToObject: () => addBox3WireframeToObject,
   addWireframeToMesh: () => addWireframeToMesh,
@@ -28896,6 +28898,134 @@ var AnvilParser = class {
   }
 };
 
+// src/world/AnvilWorldSource.ts
+init_MineRenderError();
+async function abortable2(promise, signal) {
+  if (!signal) return promise;
+  let abort;
+  const cancelled = new Promise((_, reject) => {
+    abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+  try {
+    return await Promise.race([promise, cancelled]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
+var AnvilWorldSource = class {
+  constructor(readRegion, options = {}) {
+    this.readRegion = readRegion;
+    this.regions = /* @__PURE__ */ new Map();
+    this.pending = /* @__PURE__ */ new Map();
+    this.cachedBytes = 0;
+    this.maxCachedRegions = options.maxCachedRegions ?? 4;
+    this.maxCachedBytes = options.maxCachedBytes ?? 64 * 1024 * 1024;
+    for (const [name, value] of Object.entries({ maxCachedRegions: this.maxCachedRegions, maxCachedBytes: this.maxCachedBytes })) {
+      if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a nonnegative safe integer`);
+    }
+  }
+  /** Decodes one column at absolute chunk coordinates. Aborting a caller leaves other shared readers active. */
+  async getChunk(x, z, signal) {
+    if (!Number.isSafeInteger(x) || !Number.isSafeInteger(z)) {
+      throw new RangeError("Chunk column coordinates must be safe integers");
+    }
+    const regionX = Math.floor(x / 32), regionZ = Math.floor(z / 32);
+    const data = await this.getRegion(regionX, regionZ, signal);
+    signal?.throwIfAborted();
+    if (!data) return void 0;
+    const chunk = await abortable2(AnvilParser.parseChunk(data, x - regionX * 32, z - regionZ * 32), signal);
+    signal?.throwIfAborted();
+    if (chunk && (chunk.x !== x || chunk.z !== z)) {
+      throw new MineRenderError(`Anvil chunk coordinates ${chunk.x},${chunk.z} do not match requested column ${x},${z}`);
+    }
+    return chunk;
+  }
+  /** Releases cached regions. Reads already in progress finish without repopulating this cache. */
+  clearCache() {
+    this.regions.clear();
+    this.pending.clear();
+    this.cachedBytes = 0;
+  }
+  getRegion(x, z, signal) {
+    signal?.throwIfAborted();
+    const key = `${x},${z}`;
+    const cached2 = this.regions.get(key);
+    if (cached2) {
+      this.regions.delete(key);
+      this.regions.set(key, cached2);
+      return Promise.resolve(cached2.data);
+    }
+    let loading = this.pending.get(key);
+    if (!loading) {
+      const controller = new AbortController();
+      loading = {
+        controller,
+        waiters: 0,
+        settled: false,
+        promise: Promise.resolve().then(() => {
+          controller.signal.throwIfAborted();
+          return this.readRegion(x, z, controller.signal);
+        }).then((data) => {
+          controller.signal.throwIfAborted();
+          let bytes = data instanceof Uint8Array ? data : data === void 0 ? void 0 : new Uint8Array(data);
+          if (bytes && bytes.byteLength !== bytes.buffer.byteLength) bytes = new Uint8Array(bytes);
+          if (bytes) AnvilParser.getChunkList(bytes);
+          loading.settled = true;
+          if (this.pending.get(key) === loading) this.cacheRegion(key, bytes);
+          return bytes;
+        }).finally(() => {
+          loading.settled = true;
+          if (this.pending.get(key) === loading) this.pending.delete(key);
+        })
+      };
+      this.pending.set(key, loading);
+    }
+    const read = loading;
+    read.waiters++;
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      const release = () => {
+        if (finished) return false;
+        finished = true;
+        signal?.removeEventListener("abort", abort);
+        read.waiters--;
+        return true;
+      };
+      const abort = () => {
+        if (!release()) return;
+        if (!read.waiters && !read.settled) {
+          if (this.pending.get(key) === read) this.pending.delete(key);
+          read.controller.abort(signal.reason);
+        }
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", abort, { once: true });
+      read.promise.then(
+        (data) => {
+          if (release()) resolve(data);
+        },
+        (error) => {
+          if (release()) reject(error);
+        }
+      );
+      if (signal?.aborted) abort();
+    });
+  }
+  cacheRegion(key, data) {
+    const size = data?.byteLength ?? 0;
+    if (!this.maxCachedRegions || size > this.maxCachedBytes) return;
+    this.regions.set(key, { data, size });
+    this.cachedBytes += size;
+    while (this.regions.size > this.maxCachedRegions || this.cachedBytes > this.maxCachedBytes) {
+      const oldest = this.regions.keys().next().value;
+      this.cachedBytes -= this.regions.get(oldest).size;
+      this.regions.delete(oldest);
+    }
+  }
+};
+
 // src/world/Chunk.ts
 var import_three42 = require("three");
 init_BlockStates();
@@ -29570,4 +29700,178 @@ var Chunk = class _Chunk {
     );
   }
 };
+
+// src/world/WorldStreamer.ts
+var WorldStreamer = class {
+  constructor(world, source, options = {}) {
+    this.world = world;
+    this.source = source;
+    this.loaded = /* @__PURE__ */ new Map();
+    this.owned = /* @__PURE__ */ new Map();
+    this.missing = /* @__PURE__ */ new Map();
+    this.failed = /* @__PURE__ */ new Map();
+    this.desired = [];
+    this.disposed = false;
+    this.loadRadius = options.loadRadius ?? 2;
+    this.unloadRadius = options.unloadRadius ?? Math.min(32, this.loadRadius + 1);
+    if (![this.loadRadius, this.unloadRadius].every((value) => Number.isInteger(value) && value >= 0 && value <= 32) || this.unloadRadius < this.loadRadius) {
+      throw new RangeError("Chunk radii must be integers from 0 to 32, with unloadRadius at least loadRadius");
+    }
+  }
+  /** Returns absolute coordinates of successfully placed columns, including retained columns. */
+  get loadedChunks() {
+    return [...this.loaded.values()].map((position) => ({ ...position }));
+  }
+  /** Returns source failures retained within the unload radius. Failed columns do not block other loads. */
+  get failedChunks() {
+    return [...this.failed.values()].map((failure) => ({ ...failure }));
+  }
+  /** Counts desired columns still waiting for a source read or placement, including the active column. */
+  get pendingChunks() {
+    return this.desired.filter((position) => this.needsLoad(position)).length;
+  }
+  /**
+   * 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.
+   */
+  async update(x, z) {
+    if (this.disposed) throw new Error("WorldStreamer is disposed");
+    if (![x, z].every((value) => Number.isSafeInteger(value) && Number.isSafeInteger(value - this.unloadRadius) && Number.isSafeInteger(value + this.unloadRadius))) {
+      throw new RangeError("Chunk coordinates must be safe integers within the streaming radius");
+    }
+    if (!this.center || this.center.x !== x || this.center.z !== z) {
+      this.center = { x, z };
+      this.desired = [];
+      for (let dz = -this.loadRadius; dz <= this.loadRadius; dz++) {
+        for (let dx = -this.loadRadius; dx <= this.loadRadius; dx++) {
+          this.desired.push({ x: x + dx, z: z + dz });
+        }
+      }
+      this.desired.sort((a, b) => (a.x - x) ** 2 + (a.z - z) ** 2 - (b.x - x) ** 2 - (b.z - z) ** 2);
+      if (this.loading && !this.within(this.loading.position, this.loadRadius)) {
+        this.loading.controller.abort();
+      }
+    }
+    return this.running ?? (this.running = Promise.resolve().then(() => this.drain()));
+  }
+  /** Updates from a camera or view-center position in scene units. One chunk spans 256 scene units. */
+  async updatePosition(position) {
+    if (![position.x, position.z].every(Number.isFinite)) throw new RangeError("Scene coordinates must be finite");
+    return this.update(Math.floor(position.x / 256), Math.floor(position.z / 256));
+  }
+  /** Forgets recorded source failures and retries desired columns at the latest center. */
+  async retryFailedChunks() {
+    if (this.disposed) throw new Error("WorldStreamer is disposed");
+    this.failed.clear();
+    if (this.center) await this.update(this.center.x, this.center.z);
+  }
+  /** Aborts source reads, waits for active work, then unloads owned columns. The world and source remain caller-owned. */
+  dispose() {
+    this.disposed = true;
+    this.desired = [];
+    this.center = void 0;
+    this.loading?.controller.abort();
+    return this.disposal ?? (this.disposal = Promise.resolve().then(async () => {
+      await this.running?.catch(() => void 0);
+      let failure;
+      let failed = false;
+      for (const position of this.owned.values()) {
+        try {
+          await this.unload(position);
+        } catch (error) {
+          failed = true;
+          failure ?? (failure = error);
+        }
+      }
+      this.missing.clear();
+      this.failed.clear();
+      if (failed) throw failure;
+    }).catch((error) => {
+      this.disposal = void 0;
+      throw error;
+    }));
+  }
+  async drain() {
+    try {
+      while (!this.disposed) {
+        for (const [key, position2] of this.missing) {
+          if (!this.within(position2, this.unloadRadius)) this.missing.delete(key);
+        }
+        for (const [key, position2] of this.failed) {
+          if (!this.within(position2, this.unloadRadius)) this.failed.delete(key);
+        }
+        const obsolete = [...this.owned.values()].find((position2) => !this.loaded.has(this.key(position2)) || !this.within(position2, this.unloadRadius));
+        if (obsolete) {
+          await this.unload(obsolete);
+          continue;
+        }
+        const position = this.desired.find((position2) => this.needsLoad(position2));
+        if (!position) return;
+        let chunk;
+        const controller = new AbortController();
+        this.loading = { position, controller };
+        try {
+          chunk = await this.source.getChunk(position.x, position.z, controller.signal);
+          if (chunk) this.validateChunk(chunk, position);
+        } catch (error) {
+          if (!controller.signal.aborted && !this.disposed && this.within(position, this.loadRadius)) {
+            this.failed.set(this.key(position), { ...position, error });
+          }
+          continue;
+        } finally {
+          this.loading = void 0;
+        }
+        if (controller.signal.aborted || this.disposed || !this.within(position, this.loadRadius)) continue;
+        if (!chunk) {
+          this.missing.set(this.key(position), position);
+          continue;
+        }
+        this.owned.set(this.key(position), position);
+        try {
+          await this.world.placeChunk(chunk);
+          this.loaded.set(this.key(position), position);
+        } catch (error) {
+          try {
+            await this.unload(position);
+          } catch (cleanupError) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            try {
+              Object.defineProperty(failure, "cause", { value: cleanupError, configurable: true });
+            } catch {
+              throw Object.assign(new Error(failure.message), { cause: cleanupError });
+            }
+            throw failure;
+          }
+          throw error;
+        }
+      }
+    } finally {
+      this.running = void 0;
+    }
+  }
+  needsLoad(position) {
+    const key = this.key(position);
+    return !this.loaded.has(key) && !this.missing.has(key) && !this.failed.has(key);
+  }
+  async unload(position) {
+    await this.world.unloadChunkColumn(position.x, position.z);
+    this.owned.delete(this.key(position));
+    this.loaded.delete(this.key(position));
+  }
+  validateChunk(chunk, position) {
+    if (chunk.x !== position.x || chunk.z !== position.z) {
+      throw new Error(`World source returned chunk ${chunk.x},${chunk.z} for ${position.x},${position.z}`);
+    }
+  }
+  within(position, radius) {
+    return !!this.center && Math.abs(position.x - this.center.x) <= radius && Math.abs(position.z - this.center.z) <= radius;
+  }
+  key(position) {
+    return `${position.x},${position.z}`;
+  }
+};
 //# sourceMappingURL=index.js.map