minerender 2.1.0-alpha.75 → 2.1.0-alpha.77

package/dist/browser/index.js

@@ -65,6 +65,7 @@ var init_PersistentCache = __esm({
       constructor(backing) {
         this.backing = backing;
       }
+      /** Opens a named store in the active environment using the current cache schema version. */
       static open(name) {
         return Env.provider.openCache(name, _PersistentCache.VERSION);
       }
@@ -263,6 +264,7 @@ var init_Caching = __esm({
           this.fontCache
         ];
       }
+      /** Invalidates in-memory entries so later lookups reload them. Persisted entries are retained. */
       static clear() {
         for (const cache of this.all) {
           cache.invalidateAll();
@@ -328,6 +330,7 @@ var init_Geometries = __esm({
         }
         return geometry;
       }
+      /** Returns shared geometry. Use {@link createBox} when the caller needs to modify or dispose it independently. */
       static getBox(key) {
         const keyStr = serializeBoxGeometryKey(key);
         return Caching.boxGeometryCache.get(keyStr, (k) => {
@@ -505,12 +508,15 @@ var init_Requests = __esm({
       }
     };
     Requests = class {
+      /** Queues a general request. Set `request.signal` to cancel it and `request.timeout` to limit each attempt. */
       static genericRequest(request) {
         return this.genericQueue.request(request);
       }
+      /** Queues a request separately from general traffic, using the configured asset base URL for relative paths. */
       static mcAssetRequest(request) {
         return this.mcAssetRequestQueue.request(request);
       }
+      /** Sets the base URL for relative asset requests. Use {@link AssetLoader.setVersion} to change Minecraft versions. */
       static setMcAssetRoot(root) {
         this.mcAssetRequestQueue.baseURL = root;
       }
@@ -565,6 +571,7 @@ var init_WrappedImage = __esm({
         }
         return false;
       }
+      /** Whether the dimensions form a vertical strip of square frames, without consulting `.mcmeta`. */
       get animated() {
         return this.height > this.width && this.height % this.width === 0;
       }
@@ -611,6 +618,7 @@ var init_ImageLoader = __esm({
       static _createImage() {
         return createImage();
       }
+      /** Resolves when an image URL has decoded, or rejects if decoding fails. */
       static async loadAsync(src) {
         return new Promise((resolve, reject) => {
           const image = this._createImage();
@@ -619,6 +627,7 @@ var init_ImageLoader = __esm({
           image.src = src;
         });
       }
+      /** Returns an image immediately. Use the callbacks to observe loading, or await {@link loadAsync}. */
       static loadElement(src, onload, onerr) {
         const image = this._createImage();
         if (onload)
@@ -646,6 +655,7 @@ var init_ImageLoader = __esm({
           throw err;
         }
       }
+      /** Decodes the supplied bytes into a canvas without fetching the source URL again. */
       static async infoToCanvasData(info) {
         const type = info.type === "jpg" ? "jpeg" : info.type ?? "png";
         const image = await _ImageLoader.loadAsync(`data:image/${type};base64,${info.data.toString("base64")}`);
@@ -662,12 +672,14 @@ var init_ImageLoader = __esm({
         const image = await this.infoToCanvasData(info);
         return image.data.getImageData(0, 0, image.width, image.height);
       }
+      /** Returns cached RGBA pixels for an image URL or data URL. Failed loads can be retried. */
       static async getData(src) {
         const keyStr = serializeImageKey({ src });
         return await Caching.imageDataCache.get(keyStr, (k) => {
           return _ImageLoader.loadData(src);
         });
       }
+      /** Returns a cached canvas context and dimensions for an image URL or data URL. */
       static async getCanvasData(src) {
         const keyStr = serializeImageKey({ src });
         return await Caching.canvasImageDataCache.get(keyStr, (k) => {
@@ -764,6 +776,7 @@ var init_TextureLoader = __esm({
         texture.rotation = rotation;
         return Textures.initTextureProps(texture);
       }
+      /** Loads image pixels in the background. `rotation` is in radians. Check {@link hasFailed} for load failures. */
       static load(src, format2 = import_three3.RGBAFormat, rotation = 0) {
         const texture = new import_three3.Texture();
         texture.colorSpace = THREE.SRGBColorSpace;
@@ -801,8 +814,8 @@ var init_Textures = __esm({
           for (let y = 0; y < size; y++) {
             for (let x = 0; x < size; x++) {
               const offset = (y * size + x) * 4;
-              const color = (x + y) % 2 === 0 ? 255 : 0;
-              data[offset] = data[offset + 2] = color;
+              const color2 = (x + y) % 2 === 0 ? 255 : 0;
+              data[offset] = data[offset + 2] = color2;
               data[offset + 3] = 255;
             }
           }
@@ -813,6 +826,7 @@ var init_Textures = __esm({
           return this.initTextureProps(texture);
         });
       }
+      /** Sets nearest-neighbor filters without changing the texture's color space. Returns the same texture. */
       static initTextureProps(texture) {
         texture.magFilter = THREE2.NearestFilter;
         texture.minFilter = THREE2.NearestFilter;
@@ -825,11 +839,13 @@ var init_Textures = __esm({
       static createAsset(key) {
         return new import_three4.Texture();
       }
+      /** Creates an sRGB color texture from a canvas. */
       static createCanvasTexture(canvas) {
         const texture = new import_three4.CanvasTexture(canvas);
         texture.colorSpace = THREE2.SRGBColorSpace;
         return this.initTextureProps(texture);
       }
+      /** Returns a shared texture immediately and loads its image asynchronously. Failed cached loads are retried. */
       static getImage(key) {
         const keyStr = serializeTextureKey(key);
         const cached2 = Caching.textureCache.peek(keyStr);
@@ -854,6 +870,7 @@ var init_Materials = __esm({
     init_TextureLoader();
     init_Caching();
     Materials = class _Materials {
+      /** Shared checkerboard material, created on first access. */
       static get MISSING_TEXTURE() {
         return Caching.materialCache.get("builtin:missing-texture", () => new import_three5.MeshBasicMaterial({
           map: Textures.getMissing(),
@@ -957,6 +974,7 @@ var init_Materials = __esm({
         if (tint !== void 0) material.color.multiply(new import_three5.Color(tint));
         return material;
       }
+      /** Creates an unlit, transparent GUI material without depth writes or tone mapping. */
       static createGuiCanvasMaterial(canvas) {
         const material = new import_three5.MeshBasicMaterial({
           map: Textures.createCanvasTexture(canvas),
@@ -1123,6 +1141,7 @@ var init_Materials = __esm({
         }
         return this.createBasicCanvasMaterial(canvas, transparent, shade);
       }
+      /** Returns a shared image material. Use {@link createImage} for a separate material instance. */
       static getImage(key) {
         const keyStr = serializeMaterialKey(key);
         const map = Caching.materialCache.peek(keyStr)?.map;
@@ -1297,6 +1316,14 @@ var init_AssetKey = __esm({
       }
     };
     AssetKey = class _AssetKey extends BasicAssetKey {
+      /**
+       * Creates a key from separate path components. Use {@link parse} for a combined reference.
+       *
+       * @param assetType - Asset directory, such as `models`, `textures`, or `blockstates`.
+       * @param type - Subdirectory, such as `block` or `item`.
+       * @param rootType - Top-level directory, usually `assets` or `data`.
+       * @param root - Base URL override for hosted asset sources.
+       */
       constructor(namespace, path, assetType, type, rootType = "assets", extension = ".json", root) {
         super(namespace, path);
         this.namespace = namespace;
@@ -1308,6 +1335,16 @@ var init_AssetKey = __esm({
         this.root = root;
         this.isAssetKey = true;
       }
+      /**
+       * Parses an asset reference such as `minecraft:block/stone`.
+       * A missing namespace defaults to the origin's namespace or `minecraft`.
+       *
+       * @param assetType - Asset category, such as `models` or `textures`.
+       * @param str - Path with an optional namespace and file extension.
+       * @param origin - Supplies the asset root, default namespace, and non-texture extension.
+       * @returns A key with the matching extension removed from its path. Textures use `.png`;
+       * other assets use the origin's extension or `.json`.
+       */
       static parse(assetType, str, origin) {
         let namespace = origin?.namespace || DEFAULT_NAMESPACE;
         if (str.includes(":")) {
@@ -1339,6 +1376,7 @@ var init_AssetKey = __esm({
         ];
         return a.join("/");
       }
+      /** Joins the type subdirectory and path without adding a namespace or file extension. */
       getFullPath() {
         let p10 = [];
         if (this.type) {
@@ -1350,6 +1388,7 @@ var init_AssetKey = __esm({
       toNamespacedString() {
         return this.namespace + ":" + this.getFullPath();
       }
+      /** Returns a cache identifier that includes the explicit root or {@link AssetLoader.ROOT}. */
       serialize() {
         return this.toString();
       }
@@ -1361,17 +1400,17 @@ var init_AssetKey = __esm({
 var DisplayPosition, DISPLAY_POSITIONS;
 var init_DisplayPosition = __esm({
   "src/model/DisplayPosition.ts"() {
-    DisplayPosition = /* @__PURE__ */ ((DisplayPosition2) => {
-      DisplayPosition2["THIRDPERSON_RIGHTHAND"] = "thirdperson_righthand";
-      DisplayPosition2["THIRDPERSON_LEFTHAND"] = "thirdperson_lefthand";
-      DisplayPosition2["FIRSTPERSON_RIGHTHAND"] = "firstperson_righthand";
-      DisplayPosition2["FIRSTPERSON_LEFTHAND"] = "firstperson_lefthand";
-      DisplayPosition2["GUI"] = "gui";
-      DisplayPosition2["HEAD"] = "head";
-      DisplayPosition2["GROUND"] = "ground";
-      DisplayPosition2["FIXED"] = "fixed";
-      DisplayPosition2["ON_SHELF"] = "on_shelf";
-      return DisplayPosition2;
+    DisplayPosition = /* @__PURE__ */ ((DisplayPosition3) => {
+      DisplayPosition3["THIRDPERSON_RIGHTHAND"] = "thirdperson_righthand";
+      DisplayPosition3["THIRDPERSON_LEFTHAND"] = "thirdperson_lefthand";
+      DisplayPosition3["FIRSTPERSON_RIGHTHAND"] = "firstperson_righthand";
+      DisplayPosition3["FIRSTPERSON_LEFTHAND"] = "firstperson_lefthand";
+      DisplayPosition3["GUI"] = "gui";
+      DisplayPosition3["HEAD"] = "head";
+      DisplayPosition3["GROUND"] = "ground";
+      DisplayPosition3["FIXED"] = "fixed";
+      DisplayPosition3["ON_SHELF"] = "on_shelf";
+      return DisplayPosition3;
     })(DisplayPosition || {});
     DISPLAY_POSITIONS = Object.values(DisplayPosition);
   }
@@ -1409,6 +1448,7 @@ var init_DisplayTransforms = __esm({
         const scale = new import_three7.Vector3(...transform.scale ?? [1, 1, 1]).clampScalar(-4, 4);
         return new import_three7.Matrix4().compose(translation, rotation, scale);
       }
+      /** Transforms geometry in place and reverses triangle winding when the matrix reflects it. */
       static apply(geometry, matrix) {
         geometry.applyMatrix4(matrix);
         if (matrix.determinant() < 0) {
@@ -1436,6 +1476,7 @@ var init_ModelMerger = __esm({
     init_AssetKey();
     init_DisplayTransforms();
     ModelMerger = class {
+      /** Loads the parent chain and returns a merged model without modifying the supplied definition. */
       static async mergeWithParents(model) {
         const models = await this.collectAllParents(model);
         let merged = {};
@@ -1503,6 +1544,7 @@ var init_Models = __esm({
       static get PERSISTENT_CACHE() {
         return this._persistentCache ?? (this._persistentCache = PersistentCache.open("minerender-models"));
       }
+      /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
       static async getItemList() {
         const key = new AssetKey(DEFAULT_NAMESPACE, "_list", "items");
         const legacyKey = new AssetKey(DEFAULT_NAMESPACE, "_list", "models", "item");
@@ -1573,6 +1615,7 @@ var init_Models = __esm({
         }
         throw new Error(`Unsupported item model ${node?.type ?? "definition"} for ${key.toNamespacedString()}`);
       }
+      /** Loads one model file without resolving its parents. Returns `undefined` when the file is missing. */
       static async getRaw(key) {
         if (!key.assetType) {
           key.assetType = "models";
@@ -1585,13 +1628,19 @@ var init_Models = __esm({
           return this.PERSISTENT_CACHE.getOrLoad(AssetLoader.persistentKey(keyStr), (k1) => {
             return AssetLoader.get(key, "model" /* MODEL */);
           });
-        }).then((asset) => {
-          if (asset) {
-            asset.key = key;
+        }).then((asset2) => {
+          if (asset2) {
+            asset2.key = key;
           }
-          return asset;
+          return asset2;
         });
       }
+      /**
+       * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
+       * Item keys use GUI context, false conditions, and zero numeric properties.
+       *
+       * @param key - Model key, for example `AssetKey.parse("models", "minecraft:item/diamond_sword")`.
+       */
       static async getMerged(key) {
         if (!key.assetType) {
           key.assetType = "models";
@@ -1604,9 +1653,11 @@ var init_Models = __esm({
           return _Models.loadAndMerge(key);
         });
       }
+      /** Alias for {@link getMerged}. */
       static async get(key) {
         return this.getMerged(key);
       }
+      /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
       static async clearCache() {
         return this.PERSISTENT_CACHE.clear();
       }
@@ -1629,6 +1680,7 @@ var init_BlockStates = __esm({
         return this._persistentCache ?? (this._persistentCache = PersistentCache.open("minerender-blockstates"));
       }
       // BlockState names are hardcoded
+      /** Returns blockstate filenames from the selected version's `_list.json`, or an empty list. */
       static async getList() {
         const key = new AssetKey(
           DEFAULT_NAMESPACE,
@@ -1649,6 +1701,7 @@ var init_BlockStates = __esm({
           return AssetLoader.get(key, "json" /* JSON */);
         });
       }
+      /** Looks up vanilla property definitions for the key's block path, or returns `undefined`. */
       static async getDefaultState(key) {
         const defaultStates = await this.getDefaultStates();
         if (!defaultStates) {
@@ -1656,6 +1709,7 @@ var init_BlockStates = __esm({
         }
         return defaultStates["minecraft:" + key.path];
       }
+      /** Loads a cached blockstate definition for {@link MineRenderScene.addBlock}, or returns `undefined`. */
       static async get(key) {
         if (!key.assetType) {
           key.assetType = "blockstates";
@@ -1668,11 +1722,11 @@ var init_BlockStates = __esm({
           return this.PERSISTENT_CACHE.getOrLoad(AssetLoader.persistentKey(keyStr), (k1) => {
             return AssetLoader.get(key, "blockstate" /* BLOCKSTATE */);
           });
-        }).then((asset) => {
-          if (asset) {
-            asset.key = key;
+        }).then((asset2) => {
+          if (asset2) {
+            asset2.key = key;
           }
-          return asset;
+          return asset2;
         });
       }
       static getAll(keys) {
@@ -1682,6 +1736,7 @@ var init_BlockStates = __esm({
         }
         return Promise.all(promises);
       }
+      /** Clears persisted blockstates. Use {@link Caching.clear} to also discard in-memory assets. */
       static async clearCache() {
         await this.PERSISTENT_CACHE.clear();
       }
@@ -1707,9 +1762,11 @@ var init_Assets = __esm({
       static parseAssetKey(assetType, str, origin) {
         return AssetKey.parse(assetType, str, origin);
       }
+      /** Loads a model with its parent chain resolved. See {@link Models.getMerged}. */
       static async getModel(key) {
         return Models.getMerged(key);
       }
+      /** Loads a blockstate definition. See {@link BlockStates.get}. */
       static async getBlockState(key) {
         return BlockStates.get(key);
       }
@@ -1756,6 +1813,10 @@ var init_BatchedExecutor = __esm({
   "src/util/BatchedExecutor.ts"() {
     import_jobqu2 = require("jobqu");
     BatchedExecutor = class {
+      /**
+       * @param interval - Delay between queue runs, in milliseconds.
+       * @param batch - Maximum tasks started per run and maximum tasks active at once.
+       */
       constructor(interval = 1, batch = 30) {
         if (!Number.isFinite(interval) || interval < 0) throw new RangeError("Batch interval must be finite and nonnegative");
         if (!Number.isInteger(batch) || batch < 1) throw new RangeError("Batch size must be a positive integer");
@@ -1763,9 +1824,11 @@ var init_BatchedExecutor = __esm({
         this.batch = batch;
         this.queue = new import_jobqu2.JobQueue(async (task) => task(), { interval, maxPerRun: batch, maxActive: batch });
       }
+      /** Queues a task and resolves with its result, or rejects with its error. */
       submit(task) {
         return this.queue.add(() => task());
       }
+      /** Rejects queued and future tasks. Tasks already running are allowed to finish. */
       stop() {
         this.queue.end();
       }
@@ -1812,29 +1875,29 @@ function applyGenericRotation(axis, rotation, obj) {
       break;
   }
 }
-function addBox3WireframeToObject(box, obj, color = 16777215, w = 2) {
+function addBox3WireframeToObject(box, obj, color2 = 16777215, w = 2) {
   let size = new import_three8.Vector3();
   box.getSize(size);
   let boxGeo = new import_three8.BoxGeometry(size.x, size.y, size.z, 1, 1, 1);
   let wireGeo = new import_three8.EdgesGeometry(boxGeo);
-  let wireMat = new import_three8.LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new import_three8.LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new import_three8.LineSegments(wireGeo, wireMat);
   obj.add(wireframe);
   let axes = new import_three8.AxesHelper(1);
   obj.add(axes);
 }
-function addWireframeToObject(obj, color = 16777215, w = 2) {
+function addWireframeToObject(obj, color2 = 16777215, w = 2) {
   let boxGeo = new import_three8.BoxGeometry(16, 16, 16, 1, 1, 1);
   let wireGeo = new import_three8.EdgesGeometry(boxGeo);
-  let wireMat = new import_three8.LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new import_three8.LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new import_three8.LineSegments(wireGeo, wireMat);
   obj.add(wireframe);
   let axes = new import_three8.AxesHelper(1);
   obj.add(axes);
 }
-function addWireframeToMesh(geo, mesh, color = 16777215, w = 2) {
+function addWireframeToMesh(geo, mesh, color2 = 16777215, w = 2) {
   let wireGeo = new import_three8.EdgesGeometry(geo);
-  let wireMat = new import_three8.LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new import_three8.LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new import_three8.LineSegments(wireGeo, wireMat);
   mesh.add(wireframe);
   let axes = new import_three8.AxesHelper(1);
@@ -1908,6 +1971,7 @@ var init_NBTHelper = __esm({
   "src/nbt/NBTHelper.ts"() {
     import_buffer2 = require("buffer");
     NBTHelper = class {
+      /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
       static async fromBuffer(data, format2) {
         const buffer = import_buffer2.Buffer.from(data instanceof Uint8Array ? data : new Uint8Array(data));
         const prismarineNbt = await import("prismarine-nbt");
@@ -1976,6 +2040,7 @@ var init_HostedAssetSource = __esm({
       retryDefaults: true
     };
     _HostedAssetSource = class _HostedAssetSource extends AssetSource {
+      /** Retries missing assets with the `minecraft` namespace and default root. Other failures reject. */
       async loadOrRetryWithDefaults(key, parser) {
         const direct = await this.load(key, parser);
         if (typeof direct !== "undefined") {
@@ -2033,6 +2098,10 @@ var init_HostedAssetSource = __esm({
       assetBasePath(key) {
         return `${key.root ?? this.root ?? AssetLoader.ROOT}/${key.rootType !== void 0 ? key.rootType + "/" : ""}${key.namespace !== void 0 ? key.namespace + "/" : ""}${key.assetType !== void 0 ? key.assetType + "/" : ""}`;
       }
+      /**
+       * Creates a hosted source for {@link AssetLoader.addSource}.
+       * Set `options.retryDefaults` to `false` to restrict lookups to the requested namespace and root.
+       */
       constructor(root, options) {
         super();
         this._root = root;
@@ -2125,6 +2194,11 @@ var init_BrowserArchiveProxy = __esm({
   "src/assets/source/archive/BrowserArchiveProxy.ts"() {
     import_zip = require("@zip.js/zip.js");
     BrowserArchiveProxy = class {
+      /**
+       * Opens a ZIP for asset lookup.
+       * @param id - Cache identity for this content. Change it when the pack changes.
+       * A File supplies an identity from its name, size, and modification time when omitted.
+       */
       constructor(blob, id) {
         this._blob = blob;
         this._reader = new import_zip.ZipReader(new import_zip.BlobReader(this._blob));
@@ -2254,27 +2328,27 @@ var init_PackFormats = __esm({
     init_Requests();
     PackFormats = class {
       /** Resolves pack formats from Mojang's client metadata hosted on assets.mcasset.cloud. */
-      static async get(version, type) {
-        let pending = this.versions.get(version);
+      static async get(version2, type) {
+        let pending = this.versions.get(version2);
         if (!pending || pending.expires <= Date.now()) {
           pending = {
-            formats: this.load(version),
-            expires: ["latest", "release", "snapshot"].includes(version) ? Date.now() + 3e5 : Infinity
+            formats: this.load(version2),
+            expires: ["latest", "release", "snapshot"].includes(version2) ? Date.now() + 3e5 : Infinity
           };
-          this.versions.set(version, pending);
+          this.versions.set(version2, pending);
         }
         try {
           return (await pending.formats)[type];
         } catch (cause) {
-          if (this.versions.get(version) === pending) this.versions.delete(version);
+          if (this.versions.get(version2) === pending) this.versions.delete(version2);
           const option = type === "assets" ? "resourcePackFormat" : "dataPackFormat";
           const reason = cause instanceof Error ? cause.message : String(cause);
-          throw new Error(`Could not resolve the pack format for Minecraft ${version}. Set ArchiveAssetSource ${option} explicitly. ${reason}`);
+          throw new Error(`Could not resolve the pack format for Minecraft ${version2}. Set ArchiveAssetSource ${option} explicitly. ${reason}`);
         }
       }
-      static async load(version) {
+      static async load(version2) {
         const response = await Requests.genericRequest({
-          url: `https://assets.mcasset.cloud/${encodeURIComponent(version)}/game-version.json`,
+          url: `https://assets.mcasset.cloud/${encodeURIComponent(version2)}/game-version.json`,
           responseType: "json"
         });
         const data = response.data;
@@ -2322,6 +2396,7 @@ var init_ArchiveAssetSource = __esm({
           dataPackFormat: copyFormat(options.dataPackFormat)
         };
       }
+      /** Creates a browser ZIP source from a Blob or File. */
       static blob(blob, options) {
         return new _ArchiveAssetSource(new BrowserArchiveProxy(blob), options);
       }
@@ -2362,7 +2437,7 @@ var init_ArchiveAssetSource = __esm({
       }
       async load(key, parser) {
         const path = `${this.assetBasePath(key)}${key.type !== void 0 ? key.type + "/" : ""}${key.path}${key.extension}`;
-        const version = AssetLoader.version;
+        const version2 = AssetLoader.version;
         let selectedPath = path;
         let url;
         try {
@@ -2370,7 +2445,7 @@ var init_ArchiveAssetSource = __esm({
           if (key.rootType === "assets" || key.rootType === "data") {
             const metadata = await this.getMetadata(key);
             if (metadata.hasOverlays) {
-              const format2 = (key.rootType === "assets" ? this.options.resourcePackFormat : this.options.dataPackFormat) ?? await PackFormats.get(version, key.rootType);
+              const format2 = (key.rootType === "assets" ? this.options.resourcePackFormat : this.options.dataPackFormat) ?? await PackFormats.get(version2, key.rootType);
               directories = metadata.overlayDirectories(format2);
             }
           }
@@ -2456,8 +2531,9 @@ var init_AssetLoader = __esm({
       static get version() {
         return this.ROOT.substring(this.ROOT.lastIndexOf("/") + 1);
       }
-      static setVersion(version) {
-        this.ROOT = `https://assets.mcasset.cloud/${version}`;
+      /** Selects an mcasset.cloud version, updates the vanilla source, and clears in-memory caches. */
+      static setVersion(version2) {
+        this.ROOT = `https://assets.mcasset.cloud/${version2}`;
         const source = new HostedAssetSource(this.ROOT, { retryDefaults: false });
         const index = this._SOURCES.findIndex((s) => s.key === "mcassets");
         if (index !== -1) {
@@ -2489,6 +2565,13 @@ var init_AssetLoader = __esm({
         return scope ? `${scope}
 ${key}` : key;
       }
+      /**
+       * Registers a source at the highest priority.
+       * Call {@link Caching.clear} after changing sources to discard previously loaded assets.
+       *
+       * @param key - Name used to replace or remove this source.
+       * @param override - Removes the first source with this name before adding the new one.
+       */
       static addSource(key, source, override = true) {
         if (override) {
           const existing = this.removeSource(key);
@@ -2499,6 +2582,7 @@ ${key}` : key;
         this._SOURCES.unshift({ key, source });
         console.log(p4, "Added AssetSource", key);
       }
+      /** Removes and returns the first source with this name. Call {@link Caching.clear} to reload assets. */
       static removeSource(key) {
         const index = this._SOURCES.findIndex((s) => s.key === key);
         if (index != -1) {
@@ -2509,12 +2593,13 @@ ${key}` : key;
         }
         return void 0;
       }
+      /** Loads from all sources and returns defined results in priority order. Any source failure rejects the call. */
       static async getAll(key, parser) {
         const sources = [...this._SOURCES];
         const results = [];
         for (const { source } of sources) {
-          const asset = await source.get(key, parser);
-          if (asset != void 0) results.push(asset);
+          const asset2 = await source.get(key, parser);
+          if (asset2 != void 0) results.push(asset2);
           if (await source.blocks(key)) break;
         }
         return results;
@@ -2553,6 +2638,7 @@ ${key}` : key;
         return void 0;
       }
     };
+    /** Default asset base URL. Use {@link setVersion} to select a Minecraft version. */
     _AssetLoader.ROOT = DEFAULT_ROOT;
     _AssetLoader._SOURCES = [];
     /** Used when a registered source cannot identify its content, so nothing persists past this session. */
@@ -2577,14 +2663,15 @@ var init_ModelTextures = __esm({
       static get PERSISTENT_META_CACHE() {
         return this._persistentMetaCache ?? (this._persistentMetaCache = PersistentCache.open("minerender-texturemeta"));
       }
+      /** Loads and decodes a texture into a readable canvas, or returns `undefined` when missing. */
       static async get(key) {
         const keyStr = key.serialize();
         const pending = this.preload(key);
         const cached2 = Caching.textureAssetCache.getIfPresent(keyStr);
         try {
-          const asset = await pending;
-          if (asset) {
-            return await ImageLoader.infoToCanvasData(asset);
+          const asset2 = await pending;
+          if (asset2) {
+            return await ImageLoader.infoToCanvasData(asset2);
           }
           return void 0;
         } catch (err) {
@@ -2594,16 +2681,18 @@ var init_ModelTextures = __esm({
           throw err;
         }
       }
+      /** Fetches and caches encoded texture bytes without decoding the pixels. */
       static async preload(key) {
         const keyStr = key.serialize();
         return Caching.textureAssetCache.get(keyStr, (k) => {
-          return AssetLoader.get(key, "image" /* IMAGE */).then((asset) => {
-            if (asset)
-              asset.key = key;
-            return asset;
+          return AssetLoader.get(key, "image" /* IMAGE */).then((asset2) => {
+            if (asset2)
+              asset2.key = key;
+            return asset2;
           });
         });
       }
+      /** Loads a texture's `.mcmeta` file, or returns `undefined` when no metadata file exists. */
       static async getMeta(key) {
         if (!key.extension || !key.extension.endsWith(".mcmeta")) {
           key = Object.assign(new AssetKey("", ""), key);
@@ -2612,14 +2701,15 @@ var init_ModelTextures = __esm({
         const keyStr = key.serialize();
         return Caching.textureMetaCache.get(keyStr, (k) => {
           return this.PERSISTENT_META_CACHE.getOrLoad(AssetLoader.persistentKey(keyStr), (k1) => {
-            return AssetLoader.get(key, "meta" /* META */).then((asset) => {
-              if (asset)
-                asset.key = key;
-              return asset;
+            return AssetLoader.get(key, "meta" /* META */).then((asset2) => {
+              if (asset2)
+                asset2.key = key;
+              return asset2;
             });
           });
         });
       }
+      /** Clears persisted texture metadata. Use {@link Caching.clear} to discard in-memory textures and metadata. */
       static async clearCache() {
         await this.PERSISTENT_META_CACHE.clear();
       }
@@ -2686,6 +2776,7 @@ var init_Ticker = __esm({
         }
         return handle;
       }
+      /** Starts or resumes the shared tick loop. Repeated calls have no effect. */
       static start() {
         if (this.interval) return;
         this.interval = this.schedule(() => {
@@ -2708,6 +2799,7 @@ var init_Ticker = __esm({
           _Ticker.fiveSecondTicks = 0;
         }, 1e3 * 5);
       }
+      /** Pauses the loop while retaining callbacks for a later {@link start}. */
       static stop() {
         if (this.interval) clearInterval(this.interval);
         if (this.oneSecondTicksTracker) clearInterval(this.oneSecondTicksTracker);
@@ -2716,12 +2808,14 @@ var init_Ticker = __esm({
         this.oneSecondTicksTracker = void 0;
         this.fiveSecondTicksTracker = void 0;
       }
+      /** Registers a callback, starts the loop if needed, and returns an ID for {@link remove}. */
       static add(tick) {
         this.start();
         const c = this.counter++;
         this._tickers.set(c, tick);
         return c;
       }
+      /** Removes a callback by ID and stops the timers when no callbacks remain. */
       static remove(c) {
         if (typeof c === "number") this._tickers.delete(c);
         if (!this._tickers.size) this.stop();
@@ -2735,6 +2829,7 @@ var init_Ticker = __esm({
       static get tpsFiveSeconds() {
         return this.fiveSecondTps;
       }
+      /** Stops the loop and removes all registered callbacks. */
       static dispose() {
         this.stop();
         this._tickers.clear();
@@ -2789,6 +2884,7 @@ var init_TextureAtlas = __esm({
           }
         };
       }
+      /** Copies pixels for a texture variable from its current atlas rectangle. */
       getData(texture) {
         const pos = this.positions[texture];
         const size = this.sizes[texture];
@@ -3066,6 +3162,7 @@ var init_UVMapper = __esm({
         }
         uv.needsUpdate = true;
       }
+      /** Returns the shared atlas for a keyed, merged model, creating it on first use. */
       static async getAtlas(model) {
         const keyStr = model.key.serialize();
         return Caching.modelTextureAtlasCache.get(keyStr, (k) => {
@@ -3136,6 +3233,11 @@ var init_UVMapper = __esm({
         }
         return [tl, tr, bl, br];
       }
+      /**
+       * Combines model textures and animation metadata into an atlas.
+       * Mapped UVs are stored on copies of the model's elements, available through the returned atlas.
+       * Returns `undefined` for models without a texture map.
+       */
       static async createAtlas(originalModel) {
         const textureMap = {};
         const metaMap = {};
@@ -3156,12 +3258,12 @@ var init_UVMapper = __esm({
             } else {
               uniqueTextureNames.push(textureKey);
               const assetKey = AssetKey.parse("textures", textureValue, model.key);
-              promises.push(ModelTextures.get(assetKey).then((asset) => {
-                if (!asset) {
+              promises.push(ModelTextures.get(assetKey).then((asset2) => {
+                if (!asset2) {
                   console.warn(p5, "Missing texture", assetKey);
                   return;
                 }
-                textureMap[textureKey] = new WrappedImage(asset);
+                textureMap[textureKey] = new WrappedImage(asset2);
               }));
               promises.push(ModelTextures.getMeta(assetKey).then((meta) => {
                 metaMap[textureKey] = meta;
@@ -3500,14 +3602,15 @@ var init_Entities = __esm({
     init_MineRenderError();
     init_ModelTextures();
     Entities = class {
+      /** Lists model paths in the `minecraft` namespace, including subdirectories and excluding `.json`. */
       static async getEntityList() {
         const collect = async (path) => {
           const prefix2 = path ? `${path}/` : "";
           const key = new AssetKey(DEFAULT_NAMESPACE, `${prefix2}_list`, void 0, void 0, "entity-models", ".json");
-          const list = await Caching.listAssetCache.get(key.serialize(), () => AssetLoader.get(key, "list" /* LIST */));
-          if (!list) return [];
-          const files = list.files.filter((file) => file.endsWith(".json") && file !== "_list.json").map((file) => `${prefix2}${file.slice(0, -5)}`);
-          const children = await Promise.all(list.directories.map((directory) => collect(`${prefix2}${directory}`)));
+          const list2 = await Caching.listAssetCache.get(key.serialize(), () => AssetLoader.get(key, "list" /* LIST */));
+          if (!list2) return [];
+          const files = list2.files.filter((file) => file.endsWith(".json") && file !== "_list.json").map((file) => `${prefix2}${file.slice(0, -5)}`);
+          const children = await Promise.all(list2.directories.map((directory) => collect(`${prefix2}${directory}`)));
           return [...files, ...children.flat()];
         };
         return collect("");
@@ -3517,6 +3620,7 @@ var init_Entities = __esm({
         const key = new AssetKey(modelKey.namespace, path, void 0, void 0, "entity-models", ".json", isAssetKey(modelKey) ? modelKey.root : void 0);
         return Caching.entityModelCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
       }
+      /** Returns selectable geometry-layer names, or an empty list when the model is missing. */
       static async getLayerList(modelKey) {
         return Object.keys((await this.getModelFile(modelKey))?.layers ?? {});
       }
@@ -3524,6 +3628,15 @@ var init_Entities = __esm({
       static async getPassList(modelKey) {
         return (await this.getModelFile(modelKey))?.passes ?? [];
       }
+      /**
+       * Loads the layers and textures to pass to {@link MineRenderScene.addEntity}.
+       * By default, selects `main`, unconditional passes, and passes enabled by `options.when`.
+       *
+       * @param modelKey - Dataset model, such as `new BasicAssetKey("minecraft", "zombie")`.
+       * @param textureKey - Texture override for the first selected layer.
+       * @param options - Layer selection, conditional passes, and per-layer texture overrides.
+       * @returns The selected model, or `undefined` when its dataset file is missing.
+       */
       static async getEntity(modelKey, textureKey, options) {
         const model = await this.getModelFile(modelKey);
         if (!model) return void 0;
@@ -3569,6 +3682,7 @@ var init_Entities = __esm({
         const file = await Caching.entityAnimationCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
         return file?.animations;
       }
+      /** Finds a fallback texture using the model path, its directory, and vanilla variant data. */
       static async resolveTexture(modelKey) {
         const path = isAssetKey(modelKey) ? modelKey.getFullPath() : modelKey.path;
         const root = isAssetKey(modelKey) ? modelKey.root : void 0;
@@ -3580,8 +3694,8 @@ var init_Entities = __esm({
             if (await ModelTextures.get(texture2)) return texture2;
           }
           const listKey = new AssetKey(modelKey.namespace, "_list", `${name}_variant`, void 0, "data", ".json", root);
-          const list = await AssetLoader.get(listKey, "list" /* LIST */);
-          const files = list?.files.filter((file2) => file2.endsWith(".json") && file2 !== "_list.json");
+          const list2 = await AssetLoader.get(listKey, "list" /* LIST */);
+          const files = list2?.files.filter((file2) => file2.endsWith(".json") && file2 !== "_list.json");
           const file = files?.find((file2) => file2 === "temperate.json") ?? files?.[0];
           if (!file) return void 0;
           const variantKey = new AssetKey(modelKey.namespace, file.slice(0, -5), `${name}_variant`, void 0, "data", ".json", root);
@@ -3686,27 +3800,27 @@ var init_EntityAnimationPlayer = __esm({
         for (const layer of layers) {
           const objects = [];
           if (poses) {
-            layer.traverse((object2) => {
-              if (poses.has(object2)) objects.push(object2);
+            layer.traverse((object3) => {
+              if (poses.has(object3)) objects.push(object3);
             });
           } else {
             for (const bone of Object.keys(animation.bones)) {
-              const object2 = layer.getObjectByName(`group:${bone}`);
-              if (object2) objects.push(object2);
+              const object3 = layer.getObjectByName(`group:${bone}`);
+              if (object3) objects.push(object3);
             }
           }
-          for (const object2 of objects) {
-            const bone = object2.name.slice("group:".length);
-            const pose = poses?.get(object2);
+          for (const object3 of objects) {
+            const bone = object3.name.slice("group:".length);
+            const pose = poses?.get(object3);
             this.parts.push({
               bone,
-              object: object2,
-              position: object2.position.clone(),
-              rotation: object2.rotation.clone(),
-              scale: object2.scale.clone(),
-              basePosition: pose ? new import_three11.Vector3(...pose.offset) : object2.position.clone(),
-              baseRotation: pose ? new import_three11.Euler(...pose.rotation, "ZYX") : object2.rotation.clone(),
-              baseScale: pose ? new import_three11.Vector3(...pose.scale ?? [1, 1, 1]) : object2.scale.clone()
+              object: object3,
+              position: object3.position.clone(),
+              rotation: object3.rotation.clone(),
+              scale: object3.scale.clone(),
+              basePosition: pose ? new import_three11.Vector3(...pose.offset) : object3.position.clone(),
+              baseRotation: pose ? new import_three11.Euler(...pose.rotation, "ZYX") : object3.rotation.clone(),
+              baseScale: pose ? new import_three11.Vector3(...pose.scale ?? [1, 1, 1]) : object3.scale.clone()
             });
           }
         }
@@ -3729,12 +3843,14 @@ var init_EntityAnimationPlayer = __esm({
         this._animation = void 0;
         this._time = 0;
       }
+      /** Applies the pose at an absolute playback time. Returns `false` when no clip is active. */
       setTime(seconds) {
         if (!this._animation) return false;
         this._time = seconds;
         this.apply();
         return true;
       }
+      /** Advances playback by elapsed seconds multiplied by the speed passed to {@link play}. */
       advance(deltaSeconds) {
         return this.setTime(this._time + deltaSeconds * this.speed);
       }
@@ -3772,6 +3888,7 @@ var init_InstanceReference = __esm({
         if (!this.instanceable.isInstanceActive(this.index, this)) throw new MineRenderError("Instance has been removed");
         return this.instanceable;
       }
+      /** Releases this placement's slot for reuse. Repeated calls have no effect. */
       removeFromScene() {
         if (this.instanceable.isInstanceActive(this.index, this)) this.instanceable.removeInstanceAt(this.index);
       }
@@ -3784,9 +3901,11 @@ var init_InstanceReference = __esm({
       setMatrix(matrix) {
         this.activeInstanceable.setMatrixAt(this.index, matrix);
       }
+      /** Hides or restores this placement while preserving its transform and allocated slot. */
       setVisible(visible) {
         this.activeInstanceable.setInstanceVisibleAt(this.index, visible);
       }
+      /** Updates the supplied transform components. Positions use scene units and rotations use radians. */
       setPositionRotationScale(position, rotation, scale) {
         this.activeInstanceable.setPositionRotationScaleAt(this.index, position, rotation, scale);
       }
@@ -3855,6 +3974,7 @@ var init_SceneObject = __esm({
       }
       async init() {
       }
+      /** Marks ancestor scenes for redraw and emits a `change` event. */
       notifyDirty() {
         this.traverseAncestors((parent) => {
           const scene = parent;
@@ -3890,15 +4010,17 @@ var init_SceneObject = __esm({
         return obj;
       }
       /**
-       * Get a group by its name
+       * Finds a named part, such as `head`, without the internal `group:` prefix.
+       * Returns `undefined` when the group does not exist.
        */
       getGroupByName(name) {
         return this.getObjectByName(`group:${name}`);
       }
       /**
-       * Toggle visibility of a group
-       * @param name name of the group
-       * @param visible set the visibility directly, if not set toggles it
+       * Changes a named group's visibility and requests a redraw.
+       * @param name - Part name without the `group:` prefix.
+       * @param visible - Visibility to assign. Omit it to toggle the current value.
+       * @returns The resulting visibility, or `false` if the group does not exist.
        */
       toggleGroupVisibility(name, visible) {
         return this.toggleObjectVisibility(this.getGroupByName(name), visible);
@@ -3949,15 +4071,16 @@ var init_SceneObject = __esm({
         return mesh;
       }
       /**
-       * Get a mesh by its name
+       * Finds a named mesh without the internal `mesh:` prefix, or returns `undefined`.
        */
       getMeshByName(name) {
         return this.getObjectByName(`mesh:${name}`);
       }
       /**
-       * Toggle visibility of a mesh
-       * @param name name of the mesh
-       * @param visible set the visibility directly, if not set toggles it
+       * Changes a named mesh's visibility and requests a redraw.
+       * @param name - Mesh name without the `mesh:` prefix.
+       * @param visible - Visibility to assign. Omit it to toggle the current value.
+       * @returns The resulting visibility, or `false` if the mesh does not exist.
        */
       toggleMeshVisibility(name, visible) {
         return this.toggleObjectVisibility(this.getMeshByName(name), visible);
@@ -4003,12 +4126,14 @@ var init_SceneObject = __esm({
       get isInstanced() {
         return this._isInstanced;
       }
+      /** Number of live placements, excluding released instance slots. */
       get instanceCounter() {
         return this._instanceCounter;
       }
       constructInstanceReference(i) {
         return new InstanceReference(this, i);
       }
+      /** Allocates a placement of this instanced object, reusing a released slot when available. */
       nextInstance() {
         const mesh = this.instanceMesh;
         if (!mesh) throw new MineRenderError("Object is not instanced");
@@ -4053,10 +4178,10 @@ var init_SceneObject = __esm({
           return new import_three12.InstancedBufferAttribute(array, attribute.itemSize, attribute.normalized, attribute.meshPerAttribute).setUsage(attribute.usage);
         };
         const matrix = grow(mesh.instanceMatrix, 0);
-        const color = mesh.instanceColor ? grow(mesh.instanceColor, 1) : null;
+        const color2 = mesh.instanceColor ? grow(mesh.instanceColor, 1) : null;
         mesh.dispose();
         mesh.instanceMatrix = matrix;
-        mesh.instanceColor = color;
+        mesh.instanceColor = color2;
       }
       *activeInstanceIndices() {
         if (this.instanceMesh) {
@@ -4155,6 +4280,7 @@ var init_SceneObject = __esm({
         vector.setFromMatrixScale(matrix);
         return vector;
       }
+      /** Updates supplied transform components. For a shared model, affects every live instance. */
       setPositionRotationScale(position, rotation, scale) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4173,6 +4299,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Sets position in scene units. For a shared model, updates every live instance. */
       setPosition(position) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4190,6 +4317,7 @@ var init_SceneObject = __esm({
           return this.position;
         }
       }
+      /** Sets rotation in radians. For a shared model, updates every live instance. */
       setRotation(rotation) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4207,6 +4335,7 @@ var init_SceneObject = __esm({
           return this.rotation;
         }
       }
+      /** Sets scale factors. For a shared model, updates every live instance. */
       setScale(scale) {
         if (this.isInstanced) {
           for (const i of this.activeInstanceIndices()) {
@@ -4225,15 +4354,15 @@ var init_SceneObject = __esm({
         }
       }
       //</editor-fold>
-      toggleObjectVisibility(object2, visible) {
-        if (object2) {
+      toggleObjectVisibility(object3, visible) {
+        if (object3) {
           if (typeof visible !== "undefined") {
-            object2.visible = visible;
+            object3.visible = visible;
           } else {
-            object2.visible = !object2.visible;
+            object3.visible = !object3.visible;
           }
           this.notifyDirty();
-          return object2.visible;
+          return object3.visible;
         }
         this.notifyDirty();
         return false;
@@ -4244,6 +4373,7 @@ var init_SceneObject = __esm({
         this.notifyDirty();
         super.dispose();
       }
+      /** Releases instance slots and removes children, disposing children that implement Disposable. */
       disposeAndRemoveAllChildren() {
         if (this.instanceMesh) {
           if (this._scene) this._scene.stats.instanceCount -= this.instanceReferences.size;
@@ -4266,6 +4396,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Detaches the object from its parent and requests a redraw. */
       removeFromScene() {
         this.notifyDirty();
         this.removeFromParent();
@@ -4421,12 +4552,15 @@ var init_EntityObject = __esm({
         if (this.animationPlayers.length) this.notifyDirty();
       }
       //</editor-fold>
+      /** Finds a selected draw by its layer key, such as `main` or `main#2`, or returns `undefined`. */
       getLayerGroup(name) {
         return super.getGroupByName(`layer:${name}`);
       }
+      /** Finds a part name without `group:`. Supply `layerName` to restrict the search to one draw. */
       getGroupByName(name, layerName) {
         return layerName === void 0 ? super.getGroupByName(name) : this.getLayerGroup(layerName)?.getObjectByName(`group:${name}`);
       }
+      /** Finds a mesh name without `mesh:`. Supply `layerName` to restrict the search to one draw. */
       getMeshByName(name, layerName) {
         return layerName === void 0 ? super.getMeshByName(name) : this.getLayerGroup(layerName)?.getObjectByName(`mesh:${name}`);
       }
@@ -4528,8 +4662,8 @@ var init_EntityObject = __esm({
               this.scrollMaterials.push({ material: mat, offset: mat.map.offset, speed: scroll });
             }
           }
-          this.getLayerGroup(name)?.traverse((object2) => {
-            if (isMesh(object2)) object2.material = mat;
+          this.getLayerGroup(name)?.traverse((object3) => {
+            if (isMesh(object3)) object3.material = mat;
           });
         }));
         if (!this.children.length) {
@@ -4859,8 +4993,8 @@ function toTrianglesDrawMode(geometry, drawMode) {
     return geometry;
   }
 }
-function computeMorphedAttributes(object2) {
-  if (object2.geometry.isBufferGeometry !== true) {
+function computeMorphedAttributes(object3) {
+  if (object3.geometry.isBufferGeometry !== true) {
     console.error("THREE.BufferGeometryUtils: Geometry is not of type BufferGeometry.");
     return null;
   }
@@ -4873,11 +5007,11 @@ function computeMorphedAttributes(object2) {
   const _morphA = new import_three22.Vector3();
   const _morphB = new import_three22.Vector3();
   const _morphC = new import_three22.Vector3();
-  function _calculateMorphedAttributeData(object3, material2, attribute, morphAttribute, morphTargetsRelative2, a2, b2, c2, modifiedAttributeArray) {
+  function _calculateMorphedAttributeData(object4, material2, attribute, morphAttribute, morphTargetsRelative2, a2, b2, c2, modifiedAttributeArray) {
     _vA.fromBufferAttribute(attribute, a2);
     _vB.fromBufferAttribute(attribute, b2);
     _vC.fromBufferAttribute(attribute, c2);
-    const morphInfluences = object3.morphTargetInfluences;
+    const morphInfluences = object4.morphTargetInfluences;
     if (material2.morphTargets && morphAttribute && morphInfluences) {
       _morphA.set(0, 0, 0);
       _morphB.set(0, 0, 0);
@@ -4903,10 +5037,10 @@ function computeMorphedAttributes(object2) {
       _vB.add(_morphB);
       _vC.add(_morphC);
     }
-    if (object3.isSkinnedMesh) {
-      object3.boneTransform(a2, _vA);
-      object3.boneTransform(b2, _vB);
-      object3.boneTransform(c2, _vC);
+    if (object4.isSkinnedMesh) {
+      object4.boneTransform(a2, _vA);
+      object4.boneTransform(b2, _vB);
+      object4.boneTransform(c2, _vC);
     }
     modifiedAttributeArray[a2 * 3 + 0] = _vA.x;
     modifiedAttributeArray[a2 * 3 + 1] = _vA.y;
@@ -4918,8 +5052,8 @@ function computeMorphedAttributes(object2) {
     modifiedAttributeArray[c2 * 3 + 1] = _vC.y;
     modifiedAttributeArray[c2 * 3 + 2] = _vC.z;
   }
-  const geometry = object2.geometry;
-  const material = object2.material;
+  const geometry = object3.geometry;
+  const material = object3.material;
   let a, b, c;
   const index = geometry.index;
   const positionAttribute = geometry.attributes.position;
@@ -4946,7 +5080,7 @@ function computeMorphedAttributes(object2) {
           b = index.getX(j + 1);
           c = index.getX(j + 2);
           _calculateMorphedAttributeData(
-            object2,
+            object3,
             groupMaterial,
             positionAttribute,
             morphPosition,
@@ -4957,7 +5091,7 @@ function computeMorphedAttributes(object2) {
             modifiedPosition
           );
           _calculateMorphedAttributeData(
-            object2,
+            object3,
             groupMaterial,
             normalAttribute,
             morphNormal,
@@ -4977,7 +5111,7 @@ function computeMorphedAttributes(object2) {
         b = index.getX(i + 1);
         c = index.getX(i + 2);
         _calculateMorphedAttributeData(
-          object2,
+          object3,
           material,
           positionAttribute,
           morphPosition,
@@ -4988,7 +5122,7 @@ function computeMorphedAttributes(object2) {
           modifiedPosition
         );
         _calculateMorphedAttributeData(
-          object2,
+          object3,
           material,
           normalAttribute,
           morphNormal,
@@ -5012,7 +5146,7 @@ function computeMorphedAttributes(object2) {
           b = j + 1;
           c = j + 2;
           _calculateMorphedAttributeData(
-            object2,
+            object3,
             groupMaterial,
             positionAttribute,
             morphPosition,
@@ -5023,7 +5157,7 @@ function computeMorphedAttributes(object2) {
             modifiedPosition
           );
           _calculateMorphedAttributeData(
-            object2,
+            object3,
             groupMaterial,
             normalAttribute,
             morphNormal,
@@ -5043,7 +5177,7 @@ function computeMorphedAttributes(object2) {
         b = i + 1;
         c = i + 2;
         _calculateMorphedAttributeData(
-          object2,
+          object3,
           material,
           positionAttribute,
           morphPosition,
@@ -5054,7 +5188,7 @@ function computeMorphedAttributes(object2) {
           modifiedPosition
         );
         _calculateMorphedAttributeData(
-          object2,
+          object3,
           material,
           normalAttribute,
           morphNormal,
@@ -5090,6 +5224,7 @@ var init_ModelCulling = __esm({
     import_three23 = require("three");
     init_CubeFace();
     ModelCulling = class {
+      /** Rotates a world-direction bit mask into model space. Bits follow {@link CUBE_FACES}. */
       static toLocalMask(worldMask, rotation) {
         let localMask = 0;
         for (const [localFace, offset] of CUBE_FACE_OFFSETS.entries()) {
@@ -5100,6 +5235,7 @@ var init_ModelCulling = __esm({
         }
         return localMask;
       }
+      /** Whether a model fills one block with opaque faces and can hide adjacent block faces. */
       static isOpaqueFullCube(atlas) {
         if (!atlas || atlas.hasTransparency !== false || atlas.model.elements?.length !== 1) return false;
         const element = atlas.model.elements[0];
@@ -5310,9 +5446,9 @@ var init_ItemTints = __esm({
         }));
         return colors;
       }
-      static rgb(color) {
-        if (!Array.isArray(color)) return color & 16777215;
-        const [red, green, blue] = color.map((channel) => Math.floor(Math.fround(Math.fround(channel) * 255)));
+      static rgb(color2) {
+        if (!Array.isArray(color2)) return color2 & 16777215;
+        const [red, green, blue] = color2.map((channel) => Math.floor(Math.fround(Math.fround(channel) * 255)));
         return red << 16 | green << 8 | blue;
       }
     };
@@ -5365,13 +5501,13 @@ var init_ModelObject = __esm({
           transform.multiply(new import_three25.Matrix4().makeTranslation(-8, -8, -8));
           try {
             for (const part of parts) {
-              const object2 = new EntityObject(part.model, { flip: false, wireframe: this.options.wireframe });
-              object2.matrix.copy(transform).multiply(part.transform);
-              object2.matrixWorldNeedsUpdate = true;
-              object2.matrixAutoUpdate = false;
-              this.add(object2);
-              await object2.init();
-              object2.iterateAllMeshes((mesh) => {
+              const object3 = new EntityObject(part.model, { flip: false, wireframe: this.options.wireframe });
+              object3.matrix.copy(transform).multiply(part.transform);
+              object3.matrixWorldNeedsUpdate = true;
+              object3.matrixAutoUpdate = false;
+              this.add(object3);
+              await object3.init();
+              object3.iterateAllMeshes((mesh) => {
                 const source = mesh.material;
                 let material = this.specialMaterials.get(source);
                 if (!material) {
@@ -5382,7 +5518,7 @@ var init_ModelObject = __esm({
                 mesh.material = material;
               });
               for (const [name, rotation] of Object.entries(part.rotations)) {
-                object2.getGroupByName(name)?.rotation.set(...rotation, "ZYX");
+                object3.getGroupByName(name)?.rotation.set(...rotation, "ZYX");
               }
             }
           } catch (error) {
@@ -5435,9 +5571,9 @@ var init_ModelObject = __esm({
                   if (tintIndex === void 0 || tintIndex < 0) continue;
                   const tint = this.options.tints[tintIndex];
                   if (tint === void 0) continue;
-                  const color = new import_three25.Color(tint);
+                  const color2 = new import_three25.Color(tint);
                   for (let vertex = 0; vertex < 4; vertex++) {
-                    color.toArray(colors, (faceIndex * 4 + vertex) * 3);
+                    color2.toArray(colors, (faceIndex * 4 + vertex) * 3);
                   }
                 }
                 elGeo.setAttribute("color", new import_three25.BufferAttribute(colors, 3));
@@ -5754,9 +5890,9 @@ var init_FluidModelObject = __esm({
           }
         }
         geometry.clearGroups();
-        const color = new import_three31.Color(this.options.tints?.[0] ?? (this.kind === "water" ? 4159204 : 16777215));
+        const color2 = new import_three31.Color(this.options.tints?.[0] ?? (this.kind === "water" ? 4159204 : 16777215));
         const colors = new Float32Array(geometry.getAttribute("position").count * 3);
-        for (let i = 0; i < colors.length; i += 3) color.toArray(colors, i);
+        for (let i = 0; i < colors.length; i += 3) color2.toArray(colors, i);
         geometry.setAttribute("color", new import_three31.BufferAttribute(colors, 3));
         geometry.computeBoundingBox();
         geometry.computeBoundingSphere();
@@ -5867,6 +6003,7 @@ __export(index_browser_exports, {
   RequestError: () => RequestError,
   Requests: () => Requests,
   SKIN_PARTS: () => SKIN_PARTS,
+  SceneDocumentLoader: () => SceneDocumentLoader,
   SceneExporter: () => SceneExporter,
   SceneInspector: () => SceneInspector,
   SceneObject: () => SceneObject,
@@ -5942,6 +6079,7 @@ __export(index_browser_exports, {
   mergeBufferAttributes: () => mergeBufferAttributes,
   mergeBufferGeometries: () => mergeBufferGeometries,
   mergeVertices: () => mergeVertices,
+  parseSceneDocument: () => parseSceneDocument,
   prefix: () => prefix,
   probeImageSize: () => probeImageSize,
   registerBrowserEnv: () => registerBrowserEnv,
@@ -6070,11 +6208,11 @@ var BrowserEnv = class {
   imageSize(data) {
     return probeImageSize(data);
   }
-  openCache(name, version) {
+  openCache(name, version2) {
     return new BrowserCache(import_localforage.default.createInstance({
       // IndexedDB schema upgrades retain records; each cache generation needs its own database.
-      name: name + version,
-      version
+      name: name + version2,
+      version: version2
     }));
   }
 };
@@ -6105,6 +6243,7 @@ var Meshes = class _Meshes {
   static createBox(key) {
     return new import_three6.Mesh(Geometries.getBox(key.geometry), Materials.getImage(key.material));
   }
+  /** Returns a shared Mesh object. Use {@link createBox} for a mesh with its own transform and parent. */
   static getBox(key) {
     const keyStr = serializeMeshKey(key);
     return Caching.boxMeshCache.get(keyStr, (k) => {
@@ -6217,6 +6356,7 @@ init_AssetParsers();
 init_ModelTextures();
 init_Caching();
 var Fonts = class {
+  /** Combines font definitions in source-priority order. Unsupported Unihex and TrueType providers are skipped. */
   static async get(key = "minecraft:default") {
     const fontKey = typeof key === "string" ? AssetKey.parse("font", key) : key;
     return await Caching.fontCache.get(fontKey.serialize(), () => this.load(fontKey, []));
@@ -6232,8 +6372,8 @@ var Fonts = class {
     const stack = await AssetLoader.getAll(key, "json" /* JSON */);
     if (stack.length === 0) throw new Error(`Could not load font ${key.toNamespacedString()}`);
     const glyphs = /* @__PURE__ */ new Map();
-    for (const asset of stack) {
-      for (const provider of asset.providers) {
+    for (const asset2 of stack) {
+      for (const provider of asset2.providers) {
         if (provider.filter?.uniform || provider.filter?.jp) continue;
         let provided;
         switch (provider.type) {
@@ -6372,13 +6512,13 @@ var OBJExporter = class {
    * @param {Object3D} object - The 3D object to export.
    * @return {string} The exported OBJ.
    */
-  parse(object2) {
+  parse(object3) {
     let output = "";
     let indexVertex = 0;
     let indexVertexUvs = 0;
     let indexNormals = 0;
     const vertex = new import_three16.Vector3();
-    const color = new import_three16.Color();
+    const color2 = new import_three16.Color();
     const normal = new import_three16.Vector3();
     const uv = new import_three16.Vector2();
     const face = [];
@@ -6477,9 +6617,9 @@ var OBJExporter = class {
           vertex.applyMatrix4(points.matrixWorld);
           output += "v " + vertex.x + " " + vertex.y + " " + vertex.z;
           if (colors !== void 0) {
-            color.fromBufferAttribute(colors, i);
-            import_three16.ColorManagement.workingToColorSpace(color, import_three16.SRGBColorSpace);
-            output += " " + color.r + " " + color.g + " " + color.b;
+            color2.fromBufferAttribute(colors, i);
+            import_three16.ColorManagement.workingToColorSpace(color2, import_three16.SRGBColorSpace);
+            output += " " + color2.r + " " + color2.g + " " + color2.b;
           }
           output += "\n";
         }
@@ -6491,7 +6631,7 @@ var OBJExporter = class {
       }
       indexVertex += nbVertex;
     }
-    object2.traverse(function(child) {
+    object3.traverse(function(child) {
       if (child.isMesh === true) {
         parseMesh(child);
       }
@@ -6519,9 +6659,9 @@ var PLYExporter = class {
    * @param {PLYExporter~Options} options - The export options.
    * @return {?(string|ArrayBuffer)} The exported PLY.
    */
-  parse(object2, onDone, options = {}) {
+  parse(object3, onDone, options = {}) {
     function traverseMeshes(cb) {
-      object2.traverse(function(child) {
+      object3.traverse(function(child) {
         if (child.isMesh === true || child.isPoints) {
           const mesh = child;
           const geometry = mesh.geometry;
@@ -6554,7 +6694,7 @@ var PLYExporter = class {
     for (const name of customAttributeNames) customTypes[name] = "float";
     let vertexCount = 0;
     let faceCount = 0;
-    object2.traverse(function(child) {
+    object3.traverse(function(child) {
       if (child.isMesh === true) {
         const mesh = child;
         const geometry = mesh.geometry;
@@ -7148,8 +7288,8 @@ function equalArray(array1, array2) {
     return element === array2[index];
   });
 }
-function stringToArrayBuffer(text) {
-  return new TextEncoder().encode(text).buffer;
+function stringToArrayBuffer(text2) {
+  return new TextEncoder().encode(text2).buffer;
 }
 function isIdentityMatrix(matrix) {
   return equalArray(matrix.elements, [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
@@ -7342,12 +7482,12 @@ var GLTFWriter = class {
    * @param {THREE.Object3D|THREE.Material|THREE.BufferGeometry|THREE.AnimationClip} object
    * @param {Object} objectDef
    */
-  serializeUserData(object2, objectDef) {
-    if (Object.keys(object2.userData).length === 0) return;
+  serializeUserData(object3, objectDef) {
+    if (Object.keys(object3.userData).length === 0) return;
     const options = this.options;
     const extensionsUsed = this.extensionsUsed;
     try {
-      const json = JSON.parse(JSON.stringify(object2.userData));
+      const json = JSON.parse(JSON.stringify(object3.userData));
       if (options.includeCustomExtensions && json.gltfExtensions) {
         if (objectDef.extensions === void 0) objectDef.extensions = {};
         for (const extensionName in json.gltfExtensions) {
@@ -7358,7 +7498,7 @@ var GLTFWriter = class {
       }
       if (Object.keys(json).length > 0) objectDef.extras = json;
     } catch (error) {
-      console.warn("THREE.GLTFExporter: userData of '" + object2.name + "' won't be serialized because of JSON.stringify error - " + error.message);
+      console.warn("THREE.GLTFExporter: userData of '" + object3.name + "' won't be serialized because of JSON.stringify error - " + error.message);
     }
   }
   /**
@@ -7867,9 +8007,9 @@ var GLTFWriter = class {
     if (material.isMeshStandardMaterial !== true && material.isMeshBasicMaterial !== true) {
       console.warn("GLTFExporter: Use MeshStandardMaterial or MeshBasicMaterial for best results.");
     }
-    const color = material.color.toArray().concat([material.opacity]);
-    if (!equalArray(color, [1, 1, 1, 1])) {
-      materialDef.pbrMetallicRoughness.baseColorFactor = color;
+    const color2 = material.color.toArray().concat([material.opacity]);
+    if (!equalArray(color2, [1, 1, 1, 1])) {
+      materialDef.pbrMetallicRoughness.baseColorFactor = color2;
     }
     if (material.isMeshStandardMaterial) {
       materialDef.pbrMetallicRoughness.metallicFactor = material.metalness;
@@ -8284,13 +8424,13 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object
    * @return {?number}
    */
-  processSkin(object2) {
+  processSkin(object3) {
     const json = this.json;
     const nodeMap = this.nodeMap;
-    const node = json.nodes[nodeMap.get(object2)];
-    const skeleton = object2.skeleton;
+    const node = json.nodes[nodeMap.get(object3)];
+    const skeleton = object3.skeleton;
     if (skeleton === void 0) return null;
-    const rootJoint = object2.skeleton.bones[0];
+    const rootJoint = object3.skeleton.bones[0];
     if (rootJoint === void 0) return null;
     const joints = [];
     const inverseBindMatrices = new Float32Array(skeleton.bones.length * 16);
@@ -8298,7 +8438,7 @@ var GLTFWriter = class {
     for (let i = 0; i < skeleton.bones.length; ++i) {
       joints.push(nodeMap.get(skeleton.bones[i]));
       temporaryBoneInverse.copy(skeleton.boneInverses[i]);
-      temporaryBoneInverse.multiply(object2.bindMatrix).toArray(inverseBindMatrices, i * 16);
+      temporaryBoneInverse.multiply(object3.bindMatrix).toArray(inverseBindMatrices, i * 16);
     }
     if (json.skins === void 0) json.skins = [];
     json.skins.push({
@@ -8314,19 +8454,19 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object Object3D to processNodeAsync
    * @return {Promise<number>} Index of the node in the nodes list
    */
-  async processNodeAsync(object2) {
+  async processNodeAsync(object3) {
     const json = this.json;
     const options = this.options;
     const nodeMap = this.nodeMap;
     if (!json.nodes) json.nodes = [];
-    if (object2.pivot !== null) {
-      return await this._processNodeWithPivotAsync(object2);
+    if (object3.pivot !== null) {
+      return await this._processNodeWithPivotAsync(object3);
     }
     const nodeDef = {};
     if (options.trs) {
-      const rotation = object2.quaternion.toArray();
-      const position = object2.position.toArray();
-      const scale = object2.scale.toArray();
+      const rotation = object3.quaternion.toArray();
+      const position = object3.position.toArray();
+      const scale = object3.scale.toArray();
       if (!equalArray(rotation, [0, 0, 0, 1])) {
         nodeDef.rotation = rotation;
       }
@@ -8337,28 +8477,28 @@ var GLTFWriter = class {
         nodeDef.scale = scale;
       }
     } else {
-      if (object2.matrixAutoUpdate) {
-        object2.updateMatrix();
+      if (object3.matrixAutoUpdate) {
+        object3.updateMatrix();
       }
-      if (isIdentityMatrix(object2.matrix) === false) {
-        nodeDef.matrix = object2.matrix.elements;
+      if (isIdentityMatrix(object3.matrix) === false) {
+        nodeDef.matrix = object3.matrix.elements;
       }
     }
-    if (object2.name !== "") nodeDef.name = String(object2.name);
-    this.serializeUserData(object2, nodeDef);
-    if (object2.isMesh || object2.isLine || object2.isPoints) {
-      const meshIndex = await this.processMeshAsync(object2);
+    if (object3.name !== "") nodeDef.name = String(object3.name);
+    this.serializeUserData(object3, nodeDef);
+    if (object3.isMesh || object3.isLine || object3.isPoints) {
+      const meshIndex = await this.processMeshAsync(object3);
       if (meshIndex !== null) nodeDef.mesh = meshIndex;
-    } else if (object2.isCamera) {
-      nodeDef.camera = this.processCamera(object2);
+    } else if (object3.isCamera) {
+      nodeDef.camera = this.processCamera(object3);
     }
-    if (object2.isSkinnedMesh) this.skins.push(object2);
+    if (object3.isSkinnedMesh) this.skins.push(object3);
     const nodeIndex = json.nodes.push(nodeDef) - 1;
-    nodeMap.set(object2, nodeIndex);
-    if (object2.children.length > 0) {
+    nodeMap.set(object3, nodeIndex);
+    if (object3.children.length > 0) {
       const children = [];
-      for (let i = 0, l = object2.children.length; i < l; i++) {
-        const child = object2.children[i];
+      for (let i = 0, l = object3.children.length; i < l; i++) {
+        const child = object3.children[i];
         if (child.visible || options.onlyVisible === false) {
           const childNodeIndex = await this.processNodeAsync(child);
           if (childNodeIndex !== null) children.push(childNodeIndex);
@@ -8367,7 +8507,7 @@ var GLTFWriter = class {
       if (children.length > 0) nodeDef.children = children;
     }
     await this._invokeAllAsync(function(ext) {
-      ext.writeNode && ext.writeNode(object2, nodeDef);
+      ext.writeNode && ext.writeNode(object3, nodeDef);
     });
     return nodeIndex;
   }
@@ -8376,19 +8516,19 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object Object3D with pivot
    * @return {Promise<number>} Index of the container node
    */
-  async _processNodeWithPivotAsync(object2) {
+  async _processNodeWithPivotAsync(object3) {
     const json = this.json;
     const options = this.options;
     const nodeMap = this.nodeMap;
-    const pivot = object2.pivot;
+    const pivot = object3.pivot;
     const containerDef = {};
-    const rotation = object2.quaternion.toArray();
+    const rotation = object3.quaternion.toArray();
     const position = [
-      object2.position.x + pivot.x,
-      object2.position.y + pivot.y,
-      object2.position.z + pivot.z
+      object3.position.x + pivot.x,
+      object3.position.y + pivot.y,
+      object3.position.z + pivot.z
     ];
-    const scale = object2.scale.toArray();
+    const scale = object3.scale.toArray();
     if (!equalArray(rotation, [0, 0, 0, 1])) {
       containerDef.rotation = rotation;
     }
@@ -8399,28 +8539,28 @@ var GLTFWriter = class {
       containerDef.scale = scale;
     }
     containerDef.extras = { pivot: pivot.toArray() };
-    if (object2.name !== "") containerDef.name = String(object2.name);
-    this.serializeUserData(object2, containerDef);
+    if (object3.name !== "") containerDef.name = String(object3.name);
+    this.serializeUserData(object3, containerDef);
     const containerIndex = json.nodes.push(containerDef) - 1;
-    nodeMap.set(object2, containerIndex);
+    nodeMap.set(object3, containerIndex);
     const childDef = {};
     const childPosition = [-pivot.x, -pivot.y, -pivot.z];
     if (!equalArray(childPosition, [0, 0, 0])) {
       childDef.translation = childPosition;
     }
-    if (object2.isMesh || object2.isLine || object2.isPoints) {
-      const meshIndex = await this.processMeshAsync(object2);
+    if (object3.isMesh || object3.isLine || object3.isPoints) {
+      const meshIndex = await this.processMeshAsync(object3);
       if (meshIndex !== null) childDef.mesh = meshIndex;
-    } else if (object2.isCamera) {
-      childDef.camera = this.processCamera(object2);
+    } else if (object3.isCamera) {
+      childDef.camera = this.processCamera(object3);
     }
-    if (object2.isSkinnedMesh) this.skins.push(object2);
+    if (object3.isSkinnedMesh) this.skins.push(object3);
     const childIndex = json.nodes.push(childDef) - 1;
     const containerChildren = [childIndex];
-    if (object2.children.length > 0) {
+    if (object3.children.length > 0) {
       const grandchildren = [];
-      for (let i = 0, l = object2.children.length; i < l; i++) {
-        const child = object2.children[i];
+      for (let i = 0, l = object3.children.length; i < l; i++) {
+        const child = object3.children[i];
         if (child.visible || options.onlyVisible === false) {
           const childNodeIndex = await this.processNodeAsync(child);
           if (childNodeIndex !== null) grandchildren.push(childNodeIndex);
@@ -8430,7 +8570,7 @@ var GLTFWriter = class {
     }
     containerDef.children = containerChildren;
     await this._invokeAllAsync(function(ext) {
-      ext.writeNode && ext.writeNode(object2, containerDef);
+      ext.writeNode && ext.writeNode(object3, containerDef);
     });
     return containerIndex;
   }
@@ -8873,10 +9013,10 @@ var GLTFMeshGpuInstancing = class {
     this.writer = writer;
     this.name = "EXT_mesh_gpu_instancing";
   }
-  writeNode(object2, nodeDef) {
-    if (!object2.isInstancedMesh) return;
+  writeNode(object3, nodeDef) {
+    if (!object3.isInstancedMesh) return;
     const writer = this.writer;
-    const mesh = object2;
+    const mesh = object3;
     const translationAttr = new Float32Array(mesh.count * 3);
     const rotationAttr = new Float32Array(mesh.count * 4);
     const scaleAttr = new Float32Array(mesh.count * 3);
@@ -9066,8 +9206,8 @@ var SceneExporter = class {
     }
   }
 };
-function localMatrix(object2) {
-  return object2.matrixAutoUpdate ? new import_three19.Matrix4().compose(object2.position, object2.quaternion, object2.scale) : object2.matrix.clone();
+function localMatrix(object3) {
+  return object3.matrixAutoUpdate ? new import_three19.Matrix4().compose(object3.position, object3.quaternion, object3.scale) : object3.matrix.clone();
 }
 function createSnapshot(root, gltf, bakeColors = false) {
   const scene = new import_three19.Scene();
@@ -9171,24 +9311,24 @@ function createSnapshot(root, gltf, bakeColors = false) {
       scene.add(copy);
     }
   };
-  const visit = (object2, parentWorld) => {
-    if (!object2.visible) return;
-    const world = parentWorld.clone().multiply(localMatrix(object2));
-    const mesh = object2;
+  const visit = (object3, parentWorld) => {
+    if (!object3.visible) return;
+    const world = parentWorld.clone().multiply(localMatrix(object3));
+    const mesh = object3;
     if (mesh.isMesh) {
       const instanced = mesh;
       if (instanced.isInstancedMesh) {
         for (let i = 0; i < instanced.count; i++) {
           const matrix = new import_three19.Matrix4();
           instanced.getMatrixAt(i, matrix);
-          const color = instanced.instanceColor ? new import_three19.Color().fromBufferAttribute(instanced.instanceColor, i) : void 0;
-          addMesh(mesh, world.clone().multiply(matrix), color);
+          const color2 = instanced.instanceColor ? new import_three19.Color().fromBufferAttribute(instanced.instanceColor, i) : void 0;
+          addMesh(mesh, world.clone().multiply(matrix), color2);
         }
       } else {
         addMesh(mesh, world);
       }
     }
-    for (const child of object2.children) visit(child, world);
+    for (const child of object3.children) visit(child, world);
   };
   try {
     const ancestors = [];
@@ -9264,13 +9404,13 @@ init_AssetKey();
 
 // src/gui/GuiText.ts
 var import_three20 = require("three");
-async function layoutGuiText(text, options = {}) {
+async function layoutGuiText(text2, options = {}) {
   const maxWidth = options.maxWidth ?? Infinity, lineHeight = options.lineHeight ?? 9;
   if (!(maxWidth > 0) || !Number.isFinite(lineHeight) || lineHeight <= 0) {
     throw new Error("Text wrap width and line height must be positive");
   }
   const font = await Fonts.get(options.font);
-  const runs = typeof text === "string" ? [{ text }] : text;
+  const runs = typeof text2 === "string" ? [{ text: text2 }] : text2;
   const glyphs = [], lineWidths = [];
   let line = [], width = 0;
   let trailingNewline = false;
@@ -9324,7 +9464,7 @@ function createGuiTextGeometry(layout, shadow = true) {
         batch = { image: glyph?.image, positions: [], uvs: [], colors: [], indices: [] };
         batches.push(batch);
       }
-      const color = new import_three20.Color(isShadow ? (style.color & 16579836) >> 2 : style.color);
+      const color2 = new import_three20.Color(isShadow ? (style.color & 16579836) >> 2 : style.color);
       const offset = isShadow ? 1 : 0;
       const top = glyph ? 7 - glyph.ascent : 0;
       const height = glyph ? glyph.height * glyph.scale : 8;
@@ -9352,7 +9492,7 @@ function createGuiTextGeometry(layout, shadow = true) {
         const v0 = glyph ? 1 - glyph.y / glyph.image.height : 1;
         const v1 = glyph ? 1 - (glyph.y + glyph.height) / glyph.image.height : 0;
         batch.uvs.push(u0, v0, u1, v0, u0, v1, u1, v1);
-        for (let i = 0; i < 4; i++) batch.colors.push(color.r, color.g, color.b);
+        for (let i = 0; i < 4; i++) batch.colors.push(color2.r, color2.g, color2.b);
         batch.indices.push(base, base + 2, base + 1, base + 2, base + 3, base + 1);
       };
       for (const boldOffset of style.bold ? [0, 1] : [0]) {
@@ -9386,12 +9526,19 @@ var GuiHelper = class {
       size: [width + 24, height + 24]
     }));
     let y = position[1];
-    lines.forEach((text, index) => {
-      layers.push({ ...textOptions, name: `tooltip-line-${index}`, text, position: [position[0], y] });
+    lines.forEach((text2, index) => {
+      layers.push({ ...textOptions, name: `tooltip-line-${index}`, text: text2, position: [position[0], y] });
       y += layouts[index].height + (index === 0 ? titleGap : 0);
     });
     return layers;
   }
+  /**
+   * Calculates a slot's top-left position in GUI pixels.
+   * @param slot - Zero-based slot index, or `[column, row]`.
+   * @param origin - Position of the first slot.
+   * @param offset - Horizontal and vertical spacing between slot origins, in pixels.
+   * @param rowSize - Slots per row when `slot` is an index.
+   */
   static inventorySlot(slot, origin = [0, 0], offset = [18, 18], rowSize = 9) {
     const [column, row] = typeof slot === "number" ? [slot % rowSize, Math.floor(slot / rowSize)] : slot;
     return [origin[0] + column * offset[0], origin[1] + row * offset[1]];
@@ -9836,29 +9983,29 @@ var SceneInspector = class {
     this.objectControlsContainer.innerHTML = "";
     this.addControls(targetObject, targetIntersection, instance);
   }
-  addControls(object2, intersection, instance) {
+  addControls(object3, intersection, instance) {
     const container = document.createElement("div");
     container.append(this.separator("Select Parent/Child"));
-    if (object2.parent) {
-      container.append(this.buttonControl("Select Parent " + object2.parent.constructor.name + " " + object2.parent.name, "P", () => {
-        this.selectObject(object2.parent, intersection, instance);
+    if (object3.parent) {
+      container.append(this.buttonControl("Select Parent " + object3.parent.constructor.name + " " + object3.parent.name, "P", () => {
+        this.selectObject(object3.parent, intersection, instance);
       }));
     }
-    if (object2.children.length > 0) {
+    if (object3.children.length > 0) {
       let i = 1;
-      for (let child of object2.children) {
+      for (let child of object3.children) {
         container.append(this.buttonControl("Select Child " + child.constructor.name + " " + child.name, "C" + i++, () => {
           this.selectObject(child, intersection, instance);
         }));
       }
     }
     container.append(this.separator());
-    const selectedInstance = instance && (object2 === instance.instanceable || object2 === intersection?.object) ? instance : void 0;
+    const selectedInstance = instance && (object3 === instance.instanceable || object3 === intersection?.object) ? instance : void 0;
     if (!selectedInstance) {
-      container.append(this.toggleControl("Visibility", "V", object2.visible, (v) => object2.visible = v));
+      container.append(this.toggleControl("Visibility", "V", object3.visible, (v) => object3.visible = v));
     }
     container.append(this.separator("Mesh"));
-    this.addObjectControls(object2, intersection, container, selectedInstance);
+    this.addObjectControls(object3, intersection, container, selectedInstance);
     container.append(this.separator());
     this.objectControlsContainer.append(container);
   }
@@ -10049,6 +10196,7 @@ var SceneStatsDisplay = class {
   appendTo(el) {
     el.append(this.statsContainer);
   }
+  /** Stops the refresh timer and removes the panel from the page. */
   dispose() {
     clearInterval(this.interval);
     this.interval = void 0;
@@ -10073,6 +10221,7 @@ var InstanceManager = class {
     this.isInstanceManager = true;
     this.instanceCache = {};
   }
+  /** Allocates a new placement of a cached model, or returns `undefined` if the key is unknown. */
   async get(key) {
     if (key in this.instanceCache) {
       console.debug(p9, "key in cache", key);
@@ -10080,6 +10229,7 @@ var InstanceManager = class {
     }
     return void 0;
   }
+  /** Allocates a placement, calling the supplier once when the shared model is first needed. */
   async getOrCreate(key, supplier) {
     if (key in this.instanceCache) {
       return await this.get(key);
@@ -10096,6 +10246,7 @@ var InstanceManager = class {
       throw error;
     }
   }
+  /** Forgets cached models without disposing them or releasing their existing placements. */
   reset() {
     for (let instanceCacheKey in this.instanceCache) {
       delete this.instanceCache[instanceCacheKey];
@@ -10141,6 +10292,7 @@ function matchesCondition(condition, state) {
   });
 }
 var BlockStateResolver = class {
+  /** Loads vanilla property defaults, falling back to preview values inferred from the blockstate file. */
   static async defaults(blockState) {
     const defaults = blockState.key ? await BlockStates.getDefaultState(blockState.key) : void 0;
     const state = {};
@@ -10160,9 +10312,11 @@ var BlockStateResolver = class {
     }
     return state;
   }
+  /** Selects matching models. Supply `choose` to control selection within each alternatives array. */
   static select(blockState, state, choose = this.choose) {
     return this.matching(blockState, state).map(choose);
   }
+  /** Returns matching model groups before choosing weighted alternatives. */
   static matching(blockState, state) {
     const out = [];
     if (blockState.variants) {
@@ -10186,6 +10340,7 @@ var BlockStateResolver = class {
     }
     return out;
   }
+  /** Selects a random alternative using positive integer weights, each defaulting to 1. */
   static choose(variants) {
     if (!Array.isArray(variants)) return variants;
     if (!variants.length) throw new MineRenderError("Blockstate variant arrays must not be empty");
@@ -10203,6 +10358,7 @@ var BlockStateResolver = class {
     }
     return variants[variants.length - 1];
   }
+  /** Converts blockstate rotations in degrees into the Euler rotation used by model rendering. */
   static rotation(variant) {
     const rotation = new import_three29.Euler();
     if (typeof variant.x !== "undefined") {
@@ -10265,29 +10421,29 @@ var BlockTints = class {
       }
     }
     if (!indices.size) return tints;
-    let color;
+    let color2;
     switch (rule.source) {
       case "constant":
-        color = rule.color;
+        color2 = rule.color;
         break;
       case "grass":
-        color = await Colormaps.grassColor(key);
+        color2 = await Colormaps.grassColor(key);
         break;
       case "redstone": {
         const power = Number(state.power ?? 0) / 15;
         const red = power * 0.6 + (power > 0 ? 0.4 : 0.3);
         const green = Math.max(0, power * power * 0.7 - 0.5);
         const blue = Math.max(0, power * power * 0.6 - 0.7);
-        color = Math.floor(red * 255) << 16 | Math.floor(green * 255) << 8 | Math.floor(blue * 255);
+        color2 = Math.floor(red * 255) << 16 | Math.floor(green * 255) << 8 | Math.floor(blue * 255);
         break;
       }
       case "stem": {
         const age = Number(state.age ?? 0);
-        color = age * 32 << 16 | 255 - age * 8 << 8 | age * 4;
+        color2 = age * 32 << 16 | 255 - age * 8 << 8 | age * 4;
         break;
       }
     }
-    return { ...Object.fromEntries([...indices].map((index) => [index, color])), ...tints };
+    return { ...Object.fromEntries([...indices].map((index) => [index, color2])), ...tints };
   }
 };
 
@@ -10424,8 +10580,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
       return false;
     }
     return this._models.some((model) => {
-      const object2 = isInstanceReference(model) ? model.instanceable : model;
-      return object2.isOpaqueFullCube && this.getModelCullMask(model, 63) === 63;
+      const object3 = isInstanceReference(model) ? model.instanceable : model;
+      return object3.isOpaqueFullCube && this.getModelCullMask(model, 63) === 63;
     });
   }
   getModelMatrix(model) {
@@ -10434,8 +10590,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
     return model.matrix.clone();
   }
   getModelCullMask(model, worldMask) {
-    const object2 = isInstanceReference(model) ? model.instanceable : model;
-    if (object2.options.displayPosition) return 0;
+    const object3 = isInstanceReference(model) ? model.instanceable : model;
+    if (object3.options.displayPosition) return 0;
     const position = new import_three32.Vector3();
     const rotation = new import_three32.Quaternion();
     const scale = new import_three32.Vector3();
@@ -10452,14 +10608,14 @@ var _BlockObject = class _BlockObject extends SceneObject {
           replacements.push(model);
           continue;
         }
-        const object2 = isInstanceReference(model) ? model.instanceable : model;
+        const object3 = isInstanceReference(model) ? model.instanceable : model;
         const cullMask = this.getModelCullMask(model, worldMask);
-        if (cullMask === (object2.options.cullMask ?? 0)) {
+        if (cullMask === (object3.options.cullMask ?? 0)) {
           replacements.push(model);
           continue;
         }
         const matrix = this.getModelMatrix(model);
-        const replacement = await this.scene.addModel(object2.originalModel, { ...object2.options, cullMask });
+        const replacement = await this.scene.addModel(object3.originalModel, { ...object3.options, cullMask });
         replacements.push(replacement);
         if (isInstanceReference(replacement)) {
           replacement.setMatrix(matrix);
@@ -10467,8 +10623,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
           replacement.matrix.copy(matrix);
           replacement.matrixWorldNeedsUpdate = true;
           matrix.decompose(replacement.position, replacement.quaternion, replacement.scale);
-          replacement.matrixAutoUpdate = object2.matrixAutoUpdate;
-          replacement.visible = object2.visible;
+          replacement.matrixAutoUpdate = object3.matrixAutoUpdate;
+          replacement.visible = object3.visible;
         }
       }
     } catch (error) {
@@ -10484,6 +10640,7 @@ var _BlockObject = class _BlockObject extends SceneObject {
     }
     this.notifyDirty();
   }
+  /** Selected property values. Use {@link setState} to change properties and rebuild the rendered models. */
   get state() {
     return this._state;
   }
@@ -10583,6 +10740,7 @@ var _BlockObject = class _BlockObject extends SceneObject {
     obj.setPosition(this.position);
     return obj;
   }
+  /** Clears selected properties and rebuilds models without reapplying property defaults. */
   async resetState() {
     this._previousState = this._state;
     this._state = {};
@@ -12486,6 +12644,11 @@ function compoundList(tags, name) {
 // src/model/multiblock/StructureParser.ts
 init_MineRenderError();
 var StructureParser = class {
+  /**
+   * Parses decoded NBT, omitting air blocks.
+   * @param _nbt - Structure data decoded by {@link NBTHelper.fromBuffer}.
+   * @param paletteIndex - Palette to select when the structure has several. Defaults to 0.
+   */
   static async parse(_nbt, paletteIndex) {
     const nbt = _nbt.value;
     let palette;
@@ -13320,6 +13483,7 @@ var SkinImage = class {
 // src/skin/SkinTextures.ts
 init_Textures();
 var SkinTextures = class {
+  /** Loads a skin URL. Pass `legacy` to override layout detection from the image dimensions. */
   static async get(src, legacy) {
     const image = await SkinImage.getData(src);
     const scale = image.width / 64;
@@ -13493,6 +13657,14 @@ var SkinObject = class extends SceneObject {
       }
     }
   }
+  /**
+   * Loads a skin texture, detecting slim arms and legacy layouts by default.
+   * To override detection, set `slim` or `legacy` in the options passed to
+   * `new SkinObject(options)` or `scene.addSkin(src, options)`.
+   * Use {@link setSlim} or {@link setLegacy} to change these settings later.
+   *
+   * @param src - URL of the skin texture.
+   */
   async setSkinTexture(src) {
     if (typeof src === "undefined") return;
     this.skinTextureSrc = src;
@@ -13600,59 +13772,60 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
     this.options = (0, import_ts_deepmerge8.default)({}, _MineRenderScene.DEFAULT_OPTIONS, options ?? {});
   }
   add(...objects) {
-    for (const object2 of objects) {
+    for (const object3 of objects) {
       this.dirty = true;
       try {
-        super.add(object2);
+        super.add(object3);
       } finally {
-        if (object2?.isObject3D && object2 !== this) {
-          this.updateObjectRegistration(object2, object2.parent === this);
+        if (object3?.isObject3D && object3 !== this) {
+          this.updateObjectRegistration(object3, object3.parent === this);
         }
       }
     }
     return this;
   }
   remove(...objects) {
-    for (const object2 of objects) {
-      if (!this.children.includes(object2)) continue;
+    for (const object3 of objects) {
+      if (!this.children.includes(object3)) continue;
       this.dirty = true;
-      this.updateObjectRegistration(object2, false);
+      this.updateObjectRegistration(object3, false);
       try {
-        super.remove(object2);
+        super.remove(object3);
       } finally {
-        this.updateObjectRegistration(object2, object2.parent === this);
+        this.updateObjectRegistration(object3, object3.parent === this);
       }
     }
     return this;
   }
-  updateObjectRegistration(object2, attached) {
-    if (this.observedObjects.has(object2) === attached) return;
-    const observable = object2;
+  updateObjectRegistration(object3, attached) {
+    if (this.observedObjects.has(object3) === attached) return;
+    const observable = object3;
     if (attached) {
-      this.observedObjects.add(object2);
+      this.observedObjects.add(object3);
       observable.addEventListener("change", this.onObjectChange);
     } else {
-      this.observedObjects.delete(object2);
+      this.observedObjects.delete(object3);
       observable.removeEventListener("change", this.onObjectChange);
     }
     const change = attached ? 1 : -1;
     this.stats.objectCount += change;
-    if (isSceneObject(object2)) {
+    if (isSceneObject(object3)) {
       this.stats.sceneObjectCount += change;
     }
   }
-  async initAndAdd(...object2) {
+  /** Initializes each object before attaching it to the scene. */
+  async initAndAdd(...object3) {
     this.dirty = true;
-    for (let obj of object2) {
+    for (let obj of object3) {
       await obj.init();
     }
-    return this.add(...object2);
+    return this.add(...object3);
   }
-  async addSceneObject(asset, objectSupplier, _options, parent = this) {
+  async addSceneObject(asset2, objectSupplier, _options, parent = this) {
     this.dirty = true;
     const obj = await objectSupplier();
-    if (obj?.options?.instanceMeshes && asset.key && asset.key?.assetType === "models") {
-      let key = asset.key.serialize();
+    if (obj?.options?.instanceMeshes && asset2.key && asset2.key?.assetType === "models") {
+      let key = asset2.key.serialize();
       if (isModelObject(obj)) {
         const { displayPosition, uvLockRotation, tints, cullMask } = obj.options;
         if (displayPosition) key += `|display:${displayPosition}`;
@@ -13676,13 +13849,33 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
       return obj;
     }
   }
+  /**
+   * Adds a model loaded with {@link Models.getMerged}.
+   * Set `options.instanceMeshes` to `false` to create a separate ModelObject.
+   *
+   * @param parent - Object to attach the model to. Defaults to this scene.
+   * @returns The model, or a reference to one placement of a shared model.
+   */
   async addModel(model, options, parent = this) {
     options = { ...options, tints: await ItemTints.get(model, options?.tints) };
     return this.addSceneObject(model, () => new ModelObject(model, options), options, parent);
   }
+  /**
+   * Adds the models selected by a blockstate loaded with {@link BlockStates.get}.
+   * Set `options.initialState` to choose block properties such as `facing` or `axis`.
+   * Use the returned object's `setPosition` method to move all of its model parts.
+   */
   async addBlock(blockState, options, parent = this) {
     return this.addSceneObject(blockState, () => new BlockObject(blockState, options), options, parent);
   }
+  /**
+   * Loads a skin and adds an initialized player model.
+   *
+   * @param skin - Texture URL, such as one returned by {@link Skins.fromUuidOrUsername}.
+   * Omit it to assign a texture later with {@link SkinObject.setSkinTexture}.
+   * @param options - Player settings, including `slim` and `legacy` detection overrides.
+   * @param parent - Object to attach the player to. Defaults to this scene.
+   */
   async addSkin(skin, options, parent = this) {
     this.dirty = true;
     const obj = new SkinObject(options);
@@ -13694,9 +13887,14 @@ var _MineRenderScene = class _MineRenderScene extends import_three34.Scene {
     parent.add(obj);
     return obj;
   }
+  /** Adds an entity loaded with {@link Entities.getEntity}, using its selected layers and textures. */
   async addEntity(entity, options, parent = this) {
     return this.addSceneObject(entity, () => new EntityObject(entity, options), options, parent);
   }
+  /**
+   * Adds GUI layers in draw order. One GUI pixel equals one scene unit.
+   * Layer positions start at the top left, with positive GUI y pointing down.
+   */
   async addGui(layers, options, parent = this) {
     const obj = new GuiObject(layers, options);
     obj.scene = this;
@@ -13727,11 +13925,11 @@ var _changeEvent = { type: "change" };
 var _startEvent = { type: "start" };
 var _endEvent = { type: "end" };
 var OrbitControls = class extends import_three35.EventDispatcher {
-  constructor(object2, domElement) {
+  constructor(object3, domElement) {
     super();
     if (domElement === void 0) console.warn('THREE.OrbitControls: The second parameter "domElement" is now mandatory.');
     if (domElement === document) console.error('THREE.OrbitControls: "document" should not be used as the target "domElement". Please use "renderer.domElement" instead.');
-    this.object = object2;
+    this.object = object3;
     this.domElement = domElement;
     this.domElement.style.touchAction = "none";
     this.enabled = true;
@@ -13788,7 +13986,7 @@ var OrbitControls = class extends import_three35.EventDispatcher {
     };
     this.update = function() {
       const offset = new import_three35.Vector3();
-      const quat = new import_three35.Quaternion().setFromUnitVectors(object2.up, new import_three35.Vector3(0, 1, 0));
+      const quat = new import_three35.Quaternion().setFromUnitVectors(object3.up, new import_three35.Vector3(0, 1, 0));
       const quatInverse = quat.clone().invert();
       const lastPosition = new import_three35.Vector3();
       const lastQuaternion = new import_three35.Quaternion();
@@ -14353,8 +14551,8 @@ var OrbitControls = class extends import_three35.EventDispatcher {
   }
 };
 var MapControls = class extends OrbitControls {
-  constructor(object2, domElement) {
-    super(object2, domElement);
+  constructor(object3, domElement) {
+    super(object3, domElement);
     this.screenSpacePanning = false;
     this.mouseButtons.LEFT = import_three35.MOUSE.PAN;
     this.mouseButtons.RIGHT = import_three35.MOUSE.ROTATE;
@@ -14513,6 +14711,7 @@ var _Renderer = class _Renderer {
   get element() {
     return this._element;
   }
+  /** Attaches the canvas to an element and sizes it to that element's dimensions. */
   appendTo(element) {
     if (this._disposed) return;
     this._element = element;
@@ -14540,6 +14739,7 @@ var _Renderer = class _Renderer {
     events.add(changeEvent2);
     dispatcher.addEventListener(changeEvent2, this._changeListener);
   }
+  /** Updates the camera and canvas size. Width and height are in CSS pixels. */
   resize(width, height) {
     if (this._disposed) return;
     if (isPerspectiveCamera(this.camera)) {
@@ -14578,12 +14778,14 @@ var _Renderer = class _Renderer {
       if (this._frameCallbacks.get(callback) === subscription) this._frameCallbacks.delete(callback);
     };
   }
+  /** Starts or resumes the animation loop and registered frame callbacks. */
   start() {
     if (this._disposed) return;
     this.stop();
     this._running = true;
     if (!this._inAnimationLoop) this.renderer.setAnimationLoop(this._animationLoop);
   }
+  /** Pauses rendering and frame callbacks. Call {@link start} to resume. */
   stop() {
     if (this._disposed) return;
     this._running = false;
@@ -14692,12 +14894,15 @@ var _Renderer = class _Renderer {
     const canvas = trim ? trimCanvas(this.renderer.domElement) : this.renderer.domElement;
     return canvas.toDataURL(mime, quality);
   }
+  /** Exports visible scene meshes as OBJ text, without texture images. */
   toObj() {
     return SceneExporter.toObj(this.scene);
   }
+  /** Exports visible scene meshes as PLY. Set `options.binary` for an ArrayBuffer. */
   toPLY(options) {
     return SceneExporter.toPLY(this.scene, options);
   }
+  /** Exports a static textured scene in the browser. Set `options.binary` for GLB output. */
   toGLTF(options) {
     return SceneExporter.toGLTF(this.scene, options);
   }
@@ -14775,16 +14980,244 @@ init_SceneObject();
 // src/index.ts
 init_request();
 
+// src/scene/SceneDocument.ts
+init_DisplayPosition();
+function fail(path, message) {
+  throw new Error(`${path}: ${message}`);
+}
+function object2(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail(path, "expected a JSON object");
+  for (const key of Object.keys(value)) {
+    if (["__proto__", "prototype", "constructor"].includes(key)) fail(`${path}.${key}`, "unsupported property");
+  }
+  return value;
+}
+function fields(value, path, allowed, required = []) {
+  const input = object2(value, path);
+  for (const key of required) if (input[key] === void 0) fail(`${path}.${key}`, "required");
+  for (const [key, entry] of Object.entries(input)) {
+    if (!Object.prototype.hasOwnProperty.call(allowed, key)) fail(`${path}.${key}`, "unsupported property");
+    if (entry !== void 0) allowed[key](entry, `${path}.${key}`);
+  }
+  return input;
+}
+var text = (value, path) => {
+  if (typeof value !== "string" || !value.trim()) fail(path, "expected a nonempty string");
+};
+var literalText = (value, path) => {
+  if (typeof value !== "string") fail(path, "expected a string");
+};
+var boolean = (value, path) => {
+  if (typeof value !== "boolean") fail(path, "expected a boolean");
+};
+var number = (value, path) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) fail(path, "expected a finite number");
+};
+var positive = (value, path) => {
+  number(value, path);
+  if (value <= 0) fail(path, "expected a positive number");
+};
+var nonnegative = (value, path) => {
+  number(value, path);
+  if (value < 0) fail(path, "expected a nonnegative number");
+};
+var color = (value, path) => {
+  number(value, path);
+  if (!Number.isInteger(value) || value < 0 || value > 16777215) {
+    fail(path, "expected an RGB integer from 0 to 16777215");
+  }
+};
+var asset = (value, path) => {
+  text(value, path);
+  if (!/^(?:[a-z0-9_.-]+:)?[a-z0-9_./-]+$/.test(value) || value.split(/[:/]/).some((part) => !part || part === "." || part === "..")) {
+    fail(path, "expected a resource ID such as minecraft:stone");
+  }
+};
+var version = (value, path) => {
+  text(value, path);
+  if (!/^[a-zA-Z0-9._-]+$/.test(value)) fail(path, "expected a Minecraft version without slashes");
+};
+var tuple = (size, item = number) => (value, path) => {
+  if (!Array.isArray(value) || value.length !== size) fail(path, `expected ${size} numbers`);
+  for (let index = 0; index < size; index++) item(value[index], `${path}[${index}]`);
+};
+var list = (item) => (value, path) => {
+  if (!Array.isArray(value)) fail(path, "expected an array");
+  for (let index = 0; index < value.length; index++) item(value[index], `${path}[${index}]`);
+};
+var dictionary = (item, numericKeys = false) => (value, path) => {
+  for (const [key, entry] of Object.entries(object2(value, path))) {
+    if (numericKeys && !/^\d+$/.test(key)) fail(`${path}.${key}`, "expected a nonnegative tint index");
+    item(entry, `${path}.${key}`);
+  }
+};
+var enumeration = (values) => (value, path) => {
+  if (!values.includes(value)) fail(path, `expected one of: ${values.join(", ")}`);
+};
+var textStyle = { color, bold: boolean, italic: boolean };
+function guiLayer(value, path) {
+  const layer = object2(value, path);
+  if (["texture", "item", "text"].filter((key) => layer[key] !== void 0).length !== 1) {
+    fail(path, "expected exactly one of texture, item, or text");
+  }
+  const layout = { name: text, position: tuple(2), size: tuple(2, positive) };
+  if (layer.texture !== void 0) {
+    fields(value, path, { ...layout, texture: asset, crop: (value2, path2) => {
+      tuple(4)(value2, path2);
+      const [x, y, width, height] = value2;
+      nonnegative(x, `${path2}[0]`);
+      nonnegative(y, `${path2}[1]`);
+      positive(width, `${path2}[2]`);
+      positive(height, `${path2}[3]`);
+    } });
+  } else if (layer.item !== void 0) {
+    fields(value, path, { ...layout, item: asset, tints: dictionary(color, true) });
+  } else {
+    fields(value, path, {
+      ...layout,
+      ...textStyle,
+      font: asset,
+      shadow: boolean,
+      maxWidth: positive,
+      lineHeight: positive,
+      text: (value2, path2) => {
+        if (typeof value2 === "string") return;
+        list((run, path3) => {
+          fields(run, path3, { text: literalText, ...textStyle }, ["text"]);
+        })(value2, path2);
+      }
+    });
+  }
+}
+function validateObject(value, path) {
+  const input = object2(value, path);
+  const common = { id: text, name: text, type: text, position: tuple(3), rotation: tuple(3), scale: tuple(3), visible: boolean };
+  const required = ["id", "type"];
+  const renderOptions = { wireframe: boolean };
+  switch (input.type) {
+    case "skin":
+      fields(value, path, {
+        ...common,
+        skin: text,
+        cape: (value2, path2) => {
+          fields(value2, path2, { texture: text, layout: enumeration(["minecraft", "optifine", "labymod"]) }, ["texture"]);
+        },
+        hiddenParts: list(enumeration(SKIN_PARTS)),
+        pose: (value2, path2) => {
+          fields(value2, path2, {
+            head: tuple(3),
+            body: tuple(3),
+            rightArm: tuple(3),
+            leftArm: tuple(3),
+            rightLeg: tuple(3),
+            leftLeg: tuple(3),
+            cape: tuple(3)
+          });
+        },
+        options: (value2, path2) => {
+          fields(value2, path2, { slim: boolean, legacy: boolean });
+        }
+      }, required);
+      break;
+    case "block":
+      fields(value, path, {
+        ...common,
+        asset,
+        state: dictionary(text),
+        options: (value2, path2) => {
+          fields(value2, path2, { ...renderOptions, tints: dictionary(color, true) });
+        }
+      }, [...required, "asset"]);
+      break;
+    case "item":
+    case "model":
+      fields(value, path, {
+        ...common,
+        asset,
+        options: (value2, path2) => {
+          fields(value2, path2, { ...renderOptions, displayPosition: enumeration(DISPLAY_POSITIONS), tints: dictionary(color, true) });
+        }
+      }, [...required, "asset"]);
+      break;
+    case "entity":
+      fields(value, path, {
+        ...common,
+        asset,
+        texture: asset,
+        layers: list(text),
+        when: list(text),
+        textures: dictionary(asset),
+        options: (value2, path2) => {
+          fields(value2, path2, {
+            ...renderOptions,
+            flip: boolean,
+            tints: dictionary((value3, path3) => {
+              typeof value3 === "string" ? text(value3, path3) : color(value3, path3);
+            })
+          });
+        },
+        animation: (value2, path2) => {
+          fields(value2, path2, { name: text, loop: boolean, speed: nonnegative, time: nonnegative, paused: boolean }, ["name"]);
+        }
+      }, [...required, "asset"]);
+      if (Array.isArray(input.layers) && !input.layers.length) fail(`${path}.layers`, "expected at least one layer");
+      break;
+    case "gui":
+      fields(value, path, { ...common, layers: list(guiLayer) }, [...required, "layers"]);
+      break;
+    default:
+      fail(`${path}.type`, "expected skin, block, item, entity, model, or gui");
+  }
+}
+function parseSceneDocument(value) {
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      fail("scene", "invalid JSON");
+    }
+  }
+  const input = fields(value, "scene", {
+    format: enumeration(["minerender-scene"]),
+    version: (value2, path) => {
+      if (value2 !== 1) fail(path, "only scene document version 1 is supported");
+    },
+    minecraftVersion: version,
+    camera: (value2, path) => {
+      fields(value2, path, { position: tuple(3), target: tuple(3) }, ["position", "target"]);
+    },
+    objects: list(validateObject)
+  }, ["format", "version", "objects"]);
+  const ids = /* @__PURE__ */ new Set();
+  for (const [index, entry] of input.objects.entries()) {
+    if (ids.has(entry.id)) fail(`scene.objects[${index}].id`, `duplicate object ID "${entry.id}"`);
+    ids.add(entry.id);
+  }
+  return JSON.parse(JSON.stringify(input));
+}
+
+// src/scene/SceneDocumentLoader.ts
+var import_three38 = require("three");
+init_AssetKey();
+init_AssetLoader();
+init_BlockStates();
+init_Entities();
+init_Models();
+init_DisplayPosition();
+init_SceneObject();
+
 // src/skin/Skins.ts
 init_Requests();
 var Skins = class {
   //<editor-fold desc="Skins">
+  /** Returns a skin URL for {@link MineRenderScene.addSkin}, or `undefined` if name lookup fails. */
   static async fromUuidOrUsername(uuidOrUsername) {
     if (uuidOrUsername.length === 32 || uuidOrUsername.length === 36) {
       return this.fromUuid(uuidOrUsername);
     }
     return this.fromUsername(uuidOrUsername);
   }
+  /** Builds a proxy URL for a UUID without downloading or checking the skin. */
   static async fromUuid(uuid) {
     return this.getMcProxySkinUrl(uuid);
   }
@@ -14796,6 +15229,7 @@ var Skins = class {
       return void 0;
     });
   }
+  /** Looks up a saved MineSkin skin and returns its texture URL, or `undefined` on lookup failure. */
   static async fromMineSkin(mineskinId) {
     return this.getMineSkin(mineskinId).then((mineskin) => {
       if (mineskin) {
@@ -14806,12 +15240,14 @@ var Skins = class {
   }
   //</editor-fold>
   //<editor-fold desc="Capes">
+  /** Resolves a player's Minecraft cape URL for {@link SkinObject.setCapeTexture}. */
   static async capeFromUuidOrUsername(uuidOrUsername) {
     if (uuidOrUsername.length === 32 || uuidOrUsername.length === 36) {
       return this.capeFromUuid(uuidOrUsername);
     }
     return this.capeFromUsername(uuidOrUsername);
   }
+  /** Builds a proxy URL without checking whether the player has a cape. */
   static async capeFromUuid(uuid) {
     return this.getMcProxyCapeUrl(uuid);
   }
@@ -14940,6 +15376,195 @@ var Skins = class {
   //</editor-fold>
 };
 
+// src/scene/SceneDocumentLoader.ts
+var DocumentObjectScene = class extends MineRenderScene {
+  async addSceneObject(_asset, supplier, _options, parent = this) {
+    const object3 = await supplier();
+    return this.initialize(object3, parent);
+  }
+  async initialize(object3, parent = this) {
+    object3.scene = this;
+    try {
+      await object3.init();
+      parent.add(object3);
+      return object3;
+    } catch (error) {
+      object3.dispose();
+      object3.removeFromParent();
+      throw error;
+    }
+  }
+  dispose() {
+    for (const child of [...this.children]) {
+      if (child.parent !== this) continue;
+      if (isSceneObject(child)) child.dispose();
+      child.removeFromParent();
+    }
+  }
+};
+async function skinTexture(value, cape = false) {
+  if (!/^[a-zA-Z0-9_-]{1,36}$/.test(value)) return value;
+  const texture = await (cape ? Skins.capeFromUuidOrUsername(value) : Skins.fromUuidOrUsername(value));
+  if (!texture) throw new Error(`Could not find ${cape ? "cape" : "skin"} for "${value}"`);
+  return texture;
+}
+var SceneDocumentLoader = class {
+  static parse(value) {
+    return parseSceneDocument(value);
+  }
+  /**
+   * Loads objects concurrently and attaches them in document order after every load succeeds.
+   * A failure waits for all loads, disposes staged objects, and reports the first error in document order.
+   */
+  static async load(scene, value, parent = scene) {
+    const definition = this.parse(value);
+    if (definition.minecraftVersion !== void 0 && definition.minecraftVersion !== AssetLoader.version) {
+      throw new Error(`Scene requires Minecraft ${definition.minecraftVersion}; call AssetLoader.setVersion("${definition.minecraftVersion}") before loading it`);
+    }
+    const root = new import_three38.Group();
+    root.name = "MineRender scene document";
+    const objects = [];
+    let disposed = false;
+    const loaded = {
+      root,
+      objects,
+      definition,
+      advanceAnimations: (delta) => {
+        if (!disposed) for (const object3 of objects) object3.advanceAnimation(delta);
+      },
+      dispose: () => {
+        if (disposed) return;
+        disposed = true;
+        root.removeFromParent();
+        for (const object3 of objects) object3.dispose();
+        root.clear();
+        scene.dirty = true;
+      }
+    };
+    try {
+      const results = await Promise.allSettled(definition.objects.map((object3) => this.loadValidatedObject(scene, object3)));
+      for (const result of results) if (result.status === "fulfilled") objects.push(result.value);
+      const failure = results.find((result) => result.status === "rejected");
+      if (failure) throw failure.reason;
+      for (const object3 of objects) root.add(object3.root);
+      parent.add(root);
+      scene.dirty = true;
+      return loaded;
+    } catch (error) {
+      loaded.dispose();
+      throw error;
+    }
+  }
+  /** Loads an independently editable object. Its root owns the document's position, rotation, and scale. */
+  static async loadObject(scene, value, parent = scene) {
+    const definition = this.parse({ format: "minerender-scene", version: 1, objects: [value] }).objects[0];
+    return this.loadValidatedObject(scene, definition, parent);
+  }
+  static async loadValidatedObject(scene, definition, parent) {
+    const root = new import_three38.Group();
+    root.name = definition.name ?? definition.id;
+    root.userData.sceneObjectId = definition.id;
+    root.position.fromArray(definition.position ?? [0, 0, 0]);
+    root.rotation.set(...definition.rotation ?? [0, 0, 0]);
+    root.scale.fromArray(definition.scale ?? [1, 1, 1]);
+    root.visible = definition.visible ?? true;
+    const content = new DocumentObjectScene();
+    root.add(content);
+    let object3;
+    try {
+      switch (definition.type) {
+        case "skin": {
+          const skin = new SkinObject({ ...definition.options, instanceMeshes: false });
+          object3 = skin;
+          const texture = definition.skin ? await skinTexture(definition.skin) : `${AssetLoader.ROOT}/assets/minecraft/textures/entity/player/${definition.options?.slim ? "slim/alex" : "wide/steve"}.png`;
+          await skin.setSkinTexture(texture);
+          await content.initialize(skin);
+          if (definition.cape) await skin.setCapeTexture(await skinTexture(definition.cape.texture, true), definition.cape.layout);
+          for (const [part, rotation] of Object.entries(definition.pose ?? {})) {
+            skin.getGroupByName(part)?.rotation.set(...rotation, "XYZ");
+          }
+          for (const part of definition.hiddenParts ?? []) {
+            const mesh = skin.getMeshByName(part);
+            if (mesh) mesh.visible = false;
+          }
+          break;
+        }
+        case "block": {
+          const state = await BlockStates.get(AssetKey.parse("blockstates", definition.asset));
+          if (!state) throw new Error(`Could not load block ${definition.asset}`);
+          object3 = await content.addBlock(state, { ...definition.options, initialState: definition.state, instanceMeshes: false });
+          break;
+        }
+        case "item":
+        case "model": {
+          let key = AssetKey.parse("models", definition.asset);
+          if (definition.type === "item" && key.type !== "item") {
+            key = new AssetKey(key.namespace, key.getFullPath(), "models", "item");
+          }
+          const model = await Models.getMerged(key);
+          if (!model) throw new Error(`Could not load ${definition.type} ${definition.asset}`);
+          object3 = await content.addModel(model, {
+            ...definition.type === "item" ? { displayPosition: "gui" /* GUI */ } : {},
+            ...definition.options,
+            instanceMeshes: false
+          });
+          break;
+        }
+        case "entity": {
+          const key = AssetKey.parse("entity-models", definition.asset);
+          const model = await Entities.getEntity(key, definition.texture ? AssetKey.parse("textures", definition.texture) : void 0, {
+            layers: definition.layers,
+            when: definition.when,
+            textures: definition.textures && Object.fromEntries(Object.entries(definition.textures).map(([name, texture]) => [name, AssetKey.parse("textures", texture)]))
+          });
+          if (!model) throw new Error(`Could not load entity ${definition.asset}`);
+          const entity = await content.addEntity(model, { ...definition.options, instanceMeshes: false });
+          object3 = entity;
+          if (definition.animation) {
+            const animations = await Entities.getAnimations(key);
+            const clip = animations?.[definition.animation.name];
+            if (!clip) throw new Error(`Entity ${definition.asset} has no animation "${definition.animation.name}"`);
+            entity.playAnimation(clip, definition.animation);
+          }
+          break;
+        }
+        case "gui":
+          object3 = await content.initialize(new GuiObject(definition.layers));
+          break;
+      }
+      let disposed = false;
+      const loaded = {
+        root,
+        object: object3,
+        definition,
+        advanceAnimation: (delta) => {
+          if (!disposed && definition.type === "entity" && !definition.animation?.paused) object3.advanceAnimation(delta);
+        },
+        dispose: () => {
+          if (disposed) return;
+          disposed = true;
+          root.removeFromParent();
+          object3.dispose();
+          object3.removeFromParent();
+          content.dispose();
+          root.clear();
+          scene.dirty = true;
+        }
+      };
+      parent?.add(root);
+      scene.dirty = true;
+      return loaded;
+    } catch (error) {
+      object3?.dispose();
+      object3?.removeFromParent();
+      content.dispose();
+      root.removeFromParent();
+      root.clear();
+      throw new Error(`Scene object "${definition.name ?? definition.id}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+};
+
 // src/texture/index.ts
 init_Colormaps();
 init_TextureAtlas();
@@ -14966,16 +15591,19 @@ var ChunkData = class _ChunkData {
     this.freeIds = [];
     this.nbt = /* @__PURE__ */ new Map();
   }
+  /** Returns a detached copy of a cell, or `undefined` for air. Indices range from 0 to 4095. */
   get(index) {
     _ChunkData.validateIndex(index);
     const entry = this.palette[this.indices[index]];
     return entry ? _ChunkData.copyBlock(entry.state, this.nbt.get(index)) : void 0;
   }
+  /** Captures a cell's data and returns a copy-producing reader that survives later cell changes. */
   snapshot(index) {
     _ChunkData.validateIndex(index);
     const entry = this.palette[this.indices[index]];
     return entry ? _ChunkData.copyBlock.bind(void 0, entry.state, this.nbt.get(index)) : void 0;
   }
+  /** Copies block data into a cell. An omitted block or an air block clears the cell. */
   set(index, block) {
     _ChunkData.validateIndex(index);
     let state;
@@ -15040,15 +15668,23 @@ var ChunkData = class _ChunkData {
 
 // src/world/AnvilParser.ts
 var AnvilParser = class {
+  /** Lists occupied chunk positions within the region, using local coordinates from 0 to 31. */
   static getChunkList(data) {
     return this.locations(this.bytes(data)).map(({ x, z }) => ({ x, z }));
   }
+  /** Decodes all stored chunks. Gzip, zlib, and uncompressed payloads are supported. */
   static async parse(data) {
     const bytes = this.bytes(data);
     const chunks = [];
     for (const location of this.locations(bytes)) chunks.push(await this.readChunk(bytes, location));
     return { chunks };
   }
+  /**
+   * 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 async parseChunk(data, localX, localZ) {
     if (![localX, localZ].every((value) => Number.isInteger(value) && value >= 0 && value < 32)) {
       throw new RangeError("Region-local chunk coordinates must be integers from 0 to 31");
@@ -15210,12 +15846,12 @@ var AnvilParser = class {
 };
 
 // src/world/Chunk.ts
-var import_three41 = require("three");
+var import_three42 = require("three");
 init_BlockStates();
 init_AssetKey();
 
 // src/world/MineRenderWorld.ts
-var import_three39 = require("three");
+var import_three40 = require("three");
 init_Model();
 init_BatchedExecutor();
 init_AssetKey();
@@ -15223,7 +15859,7 @@ init_BlockStates();
 init_CubeFace();
 
 // src/world/SectionModels.ts
-var import_three38 = require("three");
+var import_three39 = require("three");
 init_AssetKey();
 init_Models();
 init_CubeFace();
@@ -15253,6 +15889,7 @@ var SectionModels = class {
     this.templates = /* @__PURE__ */ new Set();
     if (!Number.isInteger(maxAtlasSize) || maxAtlasSize < 1) throw new RangeError("maxAtlasSize must be a positive integer");
   }
+  /** Returns a cube template, or `undefined` when the block requires an individual render object. */
   async get(blockState, properties = {}) {
     if (!blockState.variants || blockState.multipart) return void 0;
     let states = this.states.get(blockState);
@@ -15281,20 +15918,20 @@ var SectionModels = class {
       if (!models) this.models.set(model, models = /* @__PURE__ */ new Map());
       const key = JSON.stringify([rotation.x, rotation.y, rotation.z, variant.uvlock, tints]);
       const template = await cached(models, key, async () => {
-        const object2 = new SectionModel(model, {
+        const object3 = new SectionModel(model, {
           instanceMeshes: false,
           mergeMeshes: false,
           tints,
           uvLockRotation: variant.uvlock && (rotation.x !== 0 || rotation.y !== 0) ? [rotation.x, rotation.y, rotation.z] : void 0
         });
-        await object2.init();
-        const geometry = object2.children[0].geometry;
-        geometry.applyMatrix4(new import_three38.Matrix4().makeRotationFromEuler(rotation));
-        object2.clear();
+        await object3.init();
+        const geometry = object3.children[0].geometry;
+        geometry.applyMatrix4(new import_three39.Matrix4().makeRotationFromEuler(rotation));
+        object3.clear();
         const cullFaces = CUBE_FACES.map((face) => {
           const local = CUBE_FACES.findIndex((name) => name === atlas.model.elements[0].faces[face]?.cullface);
           if (local < 0) return 0;
-          const normal = new import_three38.Vector3(...CUBE_FACE_OFFSETS[local]).applyEuler(rotation);
+          const normal = new import_three39.Vector3(...CUBE_FACE_OFFSETS[local]).applyEuler(rotation);
           const world = CUBE_FACE_OFFSETS.findIndex(([x, y, z]) => Math.abs(normal.x - x) < 1e-6 && Math.abs(normal.y - y) < 1e-6 && Math.abs(normal.z - z) < 1e-6);
           return 1 << world;
         });
@@ -15306,6 +15943,7 @@ var SectionModels = class {
     }
     return { variants, templates };
   }
+  /** Disposes prepared geometry and clears this world's template caches. */
   clear() {
     for (const template of this.templates) template.geometry.dispose();
     this.templates.clear();
@@ -15324,20 +15962,20 @@ var MineRenderWorld = class {
   }
   getBlockAt(posOrX, y, z) {
     if (typeof posOrX == "number") {
-      return this.getBlockAt(new import_three39.Vector3(posOrX, y, z));
+      return this.getBlockAt(new import_three40.Vector3(posOrX, y, z));
     }
     if (isTripleArray(posOrX)) {
-      return this.getBlockAt(new import_three39.Vector3(posOrX[0], posOrX[1], posOrX[2]));
+      return this.getBlockAt(new import_three40.Vector3(posOrX[0], posOrX[1], posOrX[2]));
     }
     this.validatePosBounds(posOrX);
     return this.getChunkAt(posOrX)?.getBlockAt(posOrX);
   }
   async setBlockAt(posOrX, yOrBlock, z, block) {
     if (typeof posOrX == "number") {
-      return this.setBlockAt(new import_three39.Vector3(posOrX, yOrBlock, z), block);
+      return this.setBlockAt(new import_three40.Vector3(posOrX, yOrBlock, z), block);
     }
     if (isTripleArray(posOrX)) {
-      return this.setBlockAt(new import_three39.Vector3(posOrX[0], posOrX[1], posOrX[2]), yOrBlock);
+      return this.setBlockAt(new import_three40.Vector3(posOrX[0], posOrX[1], posOrX[2]), yOrBlock);
     }
     return this.placeBlock(posOrX, yOrBlock);
   }
@@ -15348,14 +15986,21 @@ var MineRenderWorld = class {
   }
   async setBlockVisibleAt(posOrX, yOrVisible, z, visible) {
     if (typeof posOrX === "number") {
-      return this.setBlockVisibleAt(new import_three39.Vector3(posOrX, yOrVisible, z), visible);
+      return this.setBlockVisibleAt(new import_three40.Vector3(posOrX, yOrVisible, z), visible);
     }
     if (isTripleArray(posOrX)) {
-      return this.setBlockVisibleAt(new import_three39.Vector3(...posOrX), yOrVisible);
+      return this.setBlockVisibleAt(new import_three40.Vector3(...posOrX), yOrVisible);
     }
     this.validatePosBounds(posOrX);
     await this.getChunkAt(posOrX)?.setBlockVisibleAt(posOrX, yOrVisible);
   }
+  /**
+   * Places a structure's blocks at their stored positions, then refreshes neighboring faces.
+   * Entity NBT is retained by the structure but is not rendered.
+   *
+   * @param useBatches - Uses bounded batches by default. Set to `false` for sequential placement.
+   * @param executor - Optional queue for batched placement. The caller remains responsible for stopping it.
+   */
   async placeMultiBlock(multiblock, useBatches = true, executor) {
     const changes = /* @__PURE__ */ new Map();
     try {
@@ -15368,7 +16013,7 @@ var MineRenderWorld = class {
     const collect = async (positions2) => {
       for (const pos of positions2) changes.set(pos.toArray().join(","), pos);
     };
-    const place = (block) => this.placeBlock(new import_three39.Vector3(...block.position), block, collect);
+    const place = (block) => this.placeBlock(new import_three40.Vector3(...block.position), block, collect);
     const keys = /* @__PURE__ */ new Map();
     for (const block of multiblock.blocks) {
       if (Chunk.isAir(block)) continue;
@@ -15452,6 +16097,7 @@ var MineRenderWorld = class {
       });
     }
   }
+  /** Removes all chunks and releases their block placements and section meshes. */
   async clear() {
     await this.culling;
     const chunks = [...this._chunks.values()];
@@ -15465,13 +16111,13 @@ var MineRenderWorld = class {
     for (const pos of positions) {
       this.pendingCulling.set(pos.toArray().join(","), pos.clone());
       for (const offset of CUBE_FACE_OFFSETS) {
-        const neighbor = pos.clone().add(new import_three39.Vector3(...offset));
+        const neighbor = pos.clone().add(new import_three40.Vector3(...offset));
         this.pendingCulling.set(neighbor.toArray().join(","), neighbor);
       }
       for (let y = -1; y <= 1; y++) {
         for (let z = -1; z <= 1; z++) {
           for (let x = -1; x <= 1; x++) {
-            const neighbor = pos.clone().add(new import_three39.Vector3(x, y, z));
+            const neighbor = pos.clone().add(new import_three40.Vector3(x, y, z));
             if (this.getBlockAt(neighbor)?.object?.fluidKind) {
               this.pendingCulling.set(neighbor.toArray().join(","), neighbor);
             }
@@ -15495,19 +16141,19 @@ var MineRenderWorld = class {
             }
             if (block.object?.fluidKind) {
               await block.object.updateFluid((x, y, z) => {
-                const neighbor = pos.clone().add(new import_three39.Vector3(x, y, z));
+                const neighbor = pos.clone().add(new import_three40.Vector3(x, y, z));
                 const section = this.getChunkAt(neighbor);
-                const object2 = section?.isBlockVisibleAt(neighbor) ? section.getBlockAt(neighbor)?.object : void 0;
+                const object3 = section?.isBlockVisibleAt(neighbor) ? section.getBlockAt(neighbor)?.object : void 0;
                 return {
-                  fluid: object2?.fluidKind,
-                  level: object2?.fluidLevel,
+                  fluid: object3?.fluidKind,
+                  level: object3?.fluidLevel,
                   solid: section?.isOccludingAt(neighbor) ?? false
                 };
               });
             }
             let mask = 0;
             for (const [face, offset] of CUBE_FACE_OFFSETS.entries()) {
-              const neighbor = pos.clone().add(new import_three39.Vector3(...offset));
+              const neighbor = pos.clone().add(new import_three40.Vector3(...offset));
               if (this.getChunkAt(neighbor)?.isOccludingAt(neighbor)) {
                 mask |= 1 << face;
               }
@@ -15537,18 +16183,21 @@ var MineRenderWorld = class {
     }
     return chunk;
   }
+  /** Returns the loaded chunk containing a world block position, without creating a chunk. */
   getChunkAt(pos) {
     return this._chunks.get(this.worldPosToChunkKey(pos));
   }
+  /** Converts block coordinates to scene units by multiplying each component by 16. */
   static worldToScenePosition(pos) {
-    return new import_three39.Vector3(
+    return new import_three40.Vector3(
       pos.x * 16,
       pos.y * 16,
       pos.z * 16
     );
   }
+  /** Converts scene units to block coordinates without rounding to an integer block. */
   static sceneToWorldPosition(pos) {
-    return new import_three39.Vector3(
+    return new import_three40.Vector3(
       pos.x / 16,
       pos.y / 16,
       pos.z / 16
@@ -15571,14 +16220,15 @@ var MineRenderWorld = class {
 init_Model();
 
 // src/world/SectionMesh.ts
-var import_three40 = require("three");
+var import_three41 = require("three");
 init_CanvasCompat();
 init_Materials();
-var SectionMesh = class _SectionMesh extends import_three40.Group {
+var SectionMesh = class _SectionMesh extends import_three41.Group {
   constructor() {
     super(...arguments);
     this.ownedMeshes = [];
   }
+  /** Builds section-local meshes from visible cube faces. `maxAtlasSize` limits each atlas dimension in pixels. */
   static build(entries, maxAtlasSize = 2048) {
     if (!Number.isInteger(maxAtlasSize) || maxAtlasSize < 1) throw new RangeError("Section atlas size must be a positive integer");
     const visible = entries.filter((entry) => entry.template.cullFaces.some((direction) => !(entry.cullMask & direction)));
@@ -15626,7 +16276,7 @@ var SectionMesh = class _SectionMesh extends import_three40.Group {
         const normal = template.geometry.getAttribute("normal");
         const uv = template.geometry.getAttribute("uv");
         const bounds = template.geometry.getAttribute("uvBounds");
-        const color = template.geometry.getAttribute("color");
+        const color2 = template.geometry.getAttribute("color");
         const sourceIndices = template.geometry.getIndex();
         const placement = locations.get(template.atlas).placement;
         const mapU = (u) => (placement.x + u * template.atlas.image.width) / page.width;
@@ -15648,24 +16298,24 @@ var SectionMesh = class _SectionMesh extends import_three40.Group {
               mapU(bounds?.getZ(vertex) ?? 1),
               mapV(bounds?.getW(vertex) ?? 1)
             );
-            colors.push(color?.getX(vertex) ?? 1, color?.getY(vertex) ?? 1, color?.getZ(vertex) ?? 1);
+            colors.push(color2?.getX(vertex) ?? 1, color2?.getY(vertex) ?? 1, color2?.getZ(vertex) ?? 1);
           }
           for (let corner = 0; corner < 6; corner++) indices.push(start + sourceIndices.getX(face * 6 + corner) - face * 4);
         }
       }
-      const geometry = new import_three40.BufferGeometry();
-      geometry.setAttribute("position", new import_three40.Float32BufferAttribute(positions, 3));
-      geometry.setAttribute("normal", new import_three40.Float32BufferAttribute(normals, 3));
-      geometry.setAttribute("uv", new import_three40.Float32BufferAttribute(uvs, 2));
-      geometry.setAttribute("uvBounds", new import_three40.Float32BufferAttribute(uvBounds, 4));
-      geometry.setAttribute("color", new import_three40.Float32BufferAttribute(colors, 3));
+      const geometry = new import_three41.BufferGeometry();
+      geometry.setAttribute("position", new import_three41.Float32BufferAttribute(positions, 3));
+      geometry.setAttribute("normal", new import_three41.Float32BufferAttribute(normals, 3));
+      geometry.setAttribute("uv", new import_three41.Float32BufferAttribute(uvs, 2));
+      geometry.setAttribute("uvBounds", new import_three41.Float32BufferAttribute(uvBounds, 4));
+      geometry.setAttribute("color", new import_three41.Float32BufferAttribute(colors, 3));
       geometry.setIndex(indices);
       geometry.computeBoundingBox();
       geometry.computeBoundingSphere();
       const material = Materials.createShadedCanvasMaterial(canvas, false, false, true);
       material.vertexColors = true;
       const texture = material.uniforms?.map?.value ?? material.map;
-      const mesh = new import_three40.Mesh(geometry, material);
+      const mesh = new import_three41.Mesh(geometry, material);
       section.add(mesh);
       section.ownedMeshes.push({ mesh, texture });
     }
@@ -15701,10 +16351,10 @@ var Chunk = class _Chunk {
   }
   getBlockAt(posOrX, y, z) {
     if (typeof posOrX == "number") {
-      return this.getBlockAt(new import_three41.Vector3(posOrX, y, z));
+      return this.getBlockAt(new import_three42.Vector3(posOrX, y, z));
     }
     if (isTripleArray(posOrX)) {
-      return this.getBlockAt(new import_three41.Vector3(posOrX[0], posOrX[1], posOrX[2]));
+      return this.getBlockAt(new import_three42.Vector3(posOrX[0], posOrX[1], posOrX[2]));
     }
     const pos = this.worldPosToChunkPos(posOrX);
     const index = _Chunk.chunkPosToBlockIndex(pos);
@@ -15712,10 +16362,10 @@ var Chunk = class _Chunk {
   }
   async setBlockAt(posOrX, yOrBlock, z, block) {
     if (typeof posOrX == "number") {
-      return this.setBlockAt(new import_three41.Vector3(posOrX, yOrBlock, z), block);
+      return this.setBlockAt(new import_three42.Vector3(posOrX, yOrBlock, z), block);
     }
     if (isTripleArray(posOrX)) {
-      return this.setBlockAt(new import_three41.Vector3(posOrX[0], posOrX[1], posOrX[2]), yOrBlock);
+      return this.setBlockAt(new import_three42.Vector3(posOrX[0], posOrX[1], posOrX[2]), yOrBlock);
     }
     const worldPos = posOrX;
     const pos = this.worldPosToChunkPos(worldPos);
@@ -15723,7 +16373,7 @@ var Chunk = class _Chunk {
     return this.setBlockInChunkAt(pos, block, worldPos);
   }
   /**
-   * Set a block at integer chunk-local coordinates from 0 to 15.
+   * Places a block at integer chunk-local coordinates from 0 to 15.
    */
   async setBlockInChunkAt(pos, block, worldPos, onBlocksChanged = this.onBlocksChanged) {
     if (typeof worldPos === "undefined") {
@@ -15736,7 +16386,7 @@ var Chunk = class _Chunk {
     this.renderedBlocks.get(index)?.object?.removeFromScene();
     if (this.sectionBlocks.delete(index)) this.meshDirty = true;
     this.renderedBlocks.delete(index);
-    let object2;
+    let object3;
     try {
       if (!readBlock) return void 0;
       const stored = readBlock();
@@ -15751,27 +16401,28 @@ var Chunk = class _Chunk {
         this.sectionBlocks.set(index, { index, template, cullMask: 0 });
         this.meshDirty = true;
       } else {
-        object2 = await this.scene.addBlock(blockState, {
+        object3 = await this.scene.addBlock(blockState, {
           mergeMeshes: true,
           instanceMeshes: true,
           maxInstanceCount: 2e3,
           initialState: stored.properties
         });
-        object2.setPosition(MineRenderWorld.worldToScenePosition(worldPos));
+        object3.setPosition(MineRenderWorld.worldToScenePosition(worldPos));
       }
       const info = { get block() {
         return readBlock();
-      }, object: object2 };
+      }, object: object3 };
       this.renderedBlocks.set(index, info);
       return info;
     } catch (error) {
       this.data.set(index, void 0);
-      object2?.removeFromScene();
+      object3?.removeFromScene();
       throw error;
     } finally {
       await onBlocksChanged?.([worldPos]);
     }
   }
+  /** Changes visibility at world block coordinates while preserving the block's data. */
   async setBlockVisibleAt(pos, visible) {
     const index = _Chunk.chunkPosToBlockIndex(this.worldPosToChunkPos(pos));
     const block = this.renderedBlocks.get(index);
@@ -15825,9 +16476,10 @@ var Chunk = class _Chunk {
     this.scene.dirty = true;
     this.meshDirty = false;
   }
+  /** Removes stored blocks and their render objects, then notifies the owning world of changed positions. */
   async clear(onBlocksChanged = this.onBlocksChanged) {
     const positions = [...this.renderedBlocks.keys()].map((index) => this.chunkPosToWorldPos(
-      new import_three41.Vector3(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
+      new import_three42.Vector3(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
     ));
     for (const info of this.renderedBlocks.values()) info.object?.removeFromScene();
     this.sectionBlocks.clear();
@@ -15845,6 +16497,7 @@ var Chunk = class _Chunk {
   static isAir(block) {
     return ChunkData.isAir(block);
   }
+  /** Maps chunk-local coordinates from 0 to 15 to a storage index, with x varying fastest, then z, then y. */
   static chunkPosToBlockIndex(pos) {
     if ([pos.x, pos.y, pos.z].some((value) => !Number.isInteger(value) || value < 0 || value >= 16)) {
       throw new RangeError("Block coordinates must be integers from 0 to 15 within a chunk");
@@ -15852,14 +16505,14 @@ var Chunk = class _Chunk {
     return pos.y * 16 * 16 + pos.z * 16 + pos.x;
   }
   worldPosToChunkPos(pos) {
-    return new import_three41.Vector3(
+    return new import_three42.Vector3(
       pos.x - this.x * 16,
       pos.y - this.y * 16,
       pos.z - this.z * 16
     );
   }
   chunkPosToWorldPos(pos) {
-    return new import_three41.Vector3(
+    return new import_three42.Vector3(
       this.x * 16 + pos.x,
       this.y * 16 + pos.y,
       this.z * 16 + pos.z