minerender 2.1.0-beta.1 → 2.1.0-beta.2

package/dist/browser/index.mjs

@@ -64,6 +64,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);
       }
@@ -259,9 +260,11 @@ var init_Caching = __esm({
           this.entityTextureCache,
           this.entityAnimationCache,
           this.blockEntityIndexCache,
-          this.fontCache
+          this.fontCache,
+          this.bannerPatternCache
         ];
       }
+      /** Invalidates in-memory entries so later lookups reload them. Persisted entries are retained. */
       static clear() {
         for (const cache of this.all) {
           cache.invalidateAll();
@@ -307,6 +310,7 @@ var init_Caching = __esm({
     _Caching.entityAnimationCache = _Caching.createAssetCache();
     _Caching.blockEntityIndexCache = _Caching.createAssetCache();
     _Caching.fontCache = _Caching.createAssetCache();
+    _Caching.bannerPatternCache = _Caching.createAssetCache();
     Caching = _Caching;
   }
 });
@@ -327,6 +331,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) => {
@@ -504,12 +509,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;
       }
@@ -564,6 +572,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;
       }
@@ -610,6 +619,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();
@@ -618,6 +628,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)
@@ -645,6 +656,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")}`);
@@ -661,12 +673,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) => {
@@ -749,7 +763,7 @@ var init_TextureLoader = __esm({
       static createTexture() {
         return new Texture();
       }
-      static loadInBackground(src, format = RGBAFormat, rotation = 0) {
+      static loadInBackground(src, format2 = RGBAFormat, rotation = 0) {
         const texture = this.createTexture();
         texture.colorSpace = THREE.SRGBColorSpace;
         const image = ImageLoader.loadElement(src, () => {
@@ -759,11 +773,12 @@ var init_TextureLoader = __esm({
           console.warn("Failed to load texture", src, error);
         });
         texture.image = image;
-        texture.format = format;
+        texture.format = format2;
         texture.rotation = rotation;
         return Textures.initTextureProps(texture);
       }
-      static load(src, format = RGBAFormat, rotation = 0) {
+      /** Loads image pixels in the background. `rotation` is in radians. Check {@link hasFailed} for load failures. */
+      static load(src, format2 = RGBAFormat, rotation = 0) {
         const texture = new Texture();
         texture.colorSpace = THREE.SRGBColorSpace;
         ImageLoader.getData(src).then((image) => {
@@ -773,7 +788,7 @@ var init_TextureLoader = __esm({
           this.failedTextures.add(texture);
           console.warn("Failed to load texture", src, error);
         });
-        texture.format = format;
+        texture.format = format2;
         texture.rotation = rotation;
         return Textures.initTextureProps(texture);
       }
@@ -800,8 +815,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;
             }
           }
@@ -812,6 +827,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;
@@ -824,11 +840,13 @@ var init_Textures = __esm({
       static createAsset(key) {
         return new Texture2();
       }
+      /** Creates an sRGB color texture from a canvas. */
       static createCanvasTexture(canvas) {
         const texture = new 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);
@@ -853,6 +871,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 MeshBasicMaterial({
           map: Textures.getMissing(),
@@ -924,6 +943,7 @@ var init_Materials = __esm({
             material.depthWrite = false;
             break;
           case "eyes":
+          case "no_outline":
             material.transparent = true;
             material.alphaTest = 0;
             material.depthWrite = false;
@@ -956,6 +976,7 @@ var init_Materials = __esm({
         if (tint !== void 0) material.color.multiply(new Color(tint));
         return material;
       }
+      /** Creates an unlit, transparent GUI material without depth writes or tone mapping. */
       static createGuiCanvasMaterial(canvas) {
         const material = new MeshBasicMaterial({
           map: Textures.createCanvasTexture(canvas),
@@ -981,7 +1002,7 @@ var init_Materials = __esm({
         };
         return material;
       }
-      static createShadedCanvasMaterial(canvas, transparent = false, shade = false) {
+      static createShadedCanvasMaterial(canvas, transparent = false, shade = false, boundUvs = false) {
         const vertShader = `
             uniform bool SHADE;
             
@@ -991,6 +1012,10 @@ var init_Materials = __esm({
             #else
             varying vec2 vUv;
             #endif
+            #ifdef BOUND_UVS
+            attribute vec4 uvBounds;
+            flat out vec4 vUvBounds;
+            #endif
             varying vec3 vTint;
             varying float light;
             varying float lift;
@@ -1026,13 +1051,17 @@ var init_Materials = __esm({
                 }
                 
                 vUv = uv;
+                #ifdef BOUND_UVS
+                vUvBounds = uvBounds;
+                #endif
                 vTint = color;
                
+                vec4 mvPosition = vec4(position, 1.0);
                 #ifdef USE_INSTANCING
-                    gl_Position = projectionMatrix * viewMatrix * modelMatrix * instanceMatrix * vec4(position, 1.0);
-                #else
-                    gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+                    mvPosition = instanceMatrix * mvPosition;
                 #endif
+                mvPosition = modelViewMatrix * mvPosition;
+                gl_Position = projectionMatrix * mvPosition;
                 
             }
         `;
@@ -1052,13 +1081,22 @@ var init_Materials = __esm({
             #else
             varying vec2 vUv;
             #endif
+            #ifdef BOUND_UVS
+            flat in vec4 vUvBounds;
+            #endif
             varying vec3 vTint;
             varying float light;
             varying float lift;
 
             void main(void)
             {
-                vec4 color = texture2D(map, vUv);
+                #ifdef BOUND_UVS
+                // Keep edge samples inside their texture even without centroid interpolation.
+                vec2 mapUv = clamp(vUv, vUvBounds.xy, vUvBounds.zw);
+                #else
+                vec2 mapUv = vUv;
+                #endif
+                vec4 color = texture2D(map, mapUv);
                 color.rgb *= vTint;
                 
                 if (color.a < 0.01) discard;
@@ -1079,7 +1117,8 @@ var init_Materials = __esm({
             }
         `;
         try {
-          return new ShaderMaterial({
+          const material = new ShaderMaterial({
+            defines: boundUvs ? { BOUND_UVS: true } : {},
             uniforms: {
               SHADE: { value: true },
               BRIGHTNESS: { value: 1 },
@@ -1097,11 +1136,14 @@ var init_Materials = __esm({
             side: transparent ? DoubleSide : FrontSide,
             alphaTest: 0.5
           });
+          Object.assign(material.defaultAttributeValues, { uvBounds: [0, 0, 1, 1] });
+          return material;
         } catch (e) {
           console.warn(e);
         }
         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;
@@ -1276,6 +1318,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;
@@ -1287,6 +1337,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(":")) {
@@ -1318,6 +1378,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) {
@@ -1329,6 +1390,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();
       }
@@ -1340,17 +1402,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);
   }
@@ -1388,6 +1450,7 @@ var init_DisplayTransforms = __esm({
         const scale = new Vector32(...transform.scale ?? [1, 1, 1]).clampScalar(-4, 4);
         return new 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) {
@@ -1415,7 +1478,10 @@ 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 parts = model.parts;
+        if (parts) return { ...model, parts: await Promise.all(parts.map((part) => this.mergeWithParents(part))) };
         const models = await this.collectAllParents(model);
         let merged = {};
         for (const source of [...models, model]) {
@@ -1427,6 +1493,7 @@ var init_ModelMerger = __esm({
         }
         merged.hierarchy = models.map((m) => m.parent).filter((p10) => `${p10}`);
         merged.hierarchy.push(`${merged.parent}`);
+        if (model.components) merged.components = model.components;
         return merged;
       }
       static async collectAllParents(model) {
@@ -1465,6 +1532,79 @@ var init_AssetParsers = __esm({
   }
 });
 
+// src/assets/BannerPatterns.ts
+var DYE_COLORS, BannerPatterns;
+var init_BannerPatterns = __esm({
+  "src/assets/BannerPatterns.ts"() {
+    init_AssetKey();
+    init_AssetLoader();
+    init_AssetParsers();
+    init_Caching();
+    DYE_COLORS = Object.freeze({
+      white: 16383998,
+      orange: 16351261,
+      magenta: 13061821,
+      light_blue: 3847130,
+      yellow: 16701501,
+      lime: 8439583,
+      pink: 15961002,
+      gray: 4673362,
+      light_gray: 10329495,
+      cyan: 1481884,
+      purple: 8991416,
+      blue: 3949738,
+      brown: 8606770,
+      green: 6192150,
+      red: 11546150,
+      black: 1908001
+    });
+    BannerPatterns = class {
+      /** Lists namespaced pattern IDs from the selected namespace's data directory. */
+      static async getList(namespace = "minecraft", root) {
+        const collect = async (path) => {
+          const prefix2 = path ? `${path}/` : "";
+          const key = new AssetKey(namespace, `${prefix2}_list`, "banner_pattern", void 0, "data", ".json", root);
+          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) => `${namespace}:${prefix2}${file.slice(0, -5)}`);
+          const children = await Promise.all(list2.directories.map((directory) => collect(`${prefix2}${directory}`)));
+          return [...files, ...children.flat()];
+        };
+        return collect("");
+      }
+      /** Returns the named dye's sRGB value, rejecting unknown colors. */
+      static getColor(color2) {
+        if (typeof color2 !== "string" || !Object.prototype.hasOwnProperty.call(DYE_COLORS, color2)) throw new Error(`Unsupported dye color ${color2}`);
+        return DYE_COLORS[color2];
+      }
+      /** Resolves the first 16 layers of a `banner_patterns` component, preserving their order. */
+      static async getLayers(value, target, root) {
+        if (value === void 0) return [];
+        if (!Array.isArray(value)) throw new Error("banner_patterns must be an array");
+        return Promise.all(value.slice(0, 16).map(async (layer) => {
+          if (!layer || typeof layer !== "object" || Array.isArray(layer)) throw new Error("Each banner pattern requires a pattern and dye color");
+          const color2 = this.getColor(layer.color);
+          let pattern2 = layer.pattern;
+          if (typeof pattern2 === "string") {
+            const id = this.identifier(pattern2);
+            const key = new AssetKey(id.namespace, id.getFullPath(), "banner_pattern", void 0, "data", ".json", root);
+            pattern2 = await Caching.bannerPatternCache.get(key.serialize(), () => AssetLoader.get(key, "json" /* JSON */));
+            if (!pattern2) throw new Error(`Missing banner pattern ${layer.pattern}`);
+          }
+          if (!pattern2 || typeof pattern2 !== "object" || Array.isArray(pattern2) || typeof pattern2.translation_key !== "string") throw new Error("Banner patterns require asset_id and translation_key");
+          const asset2 = this.identifier(pattern2.asset_id);
+          return { color: color2, texture: new AssetKey(asset2.namespace, `${target}/${asset2.getFullPath()}`, "textures", "entity", "assets", ".png", root) };
+        }));
+      }
+      static identifier(value) {
+        if (typeof value !== "string" || !/^(?:[a-z0-9_.-]+:)?[a-z0-9_./-]+$/.test(value)) throw new Error(`Invalid banner-pattern identifier ${value}`);
+        const [namespace, path] = value.includes(":") ? value.split(":") : ["minecraft", value];
+        return new AssetKey(namespace, path);
+      }
+    };
+  }
+});
+
 // src/assets/Models.ts
 var Models;
 var init_Models = __esm({
@@ -1476,12 +1616,15 @@ var init_Models = __esm({
     init_PersistentCache();
     init_AssetKey();
     init_AssetParsers();
+    init_DisplayPosition();
+    init_BannerPatterns();
     Models = class _Models {
       // opened lazily: touching the store at import time would hit IndexedDB/disk just for loading
       // the library, and would require an EnvProvider before any entry has had a chance to register
       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");
@@ -1489,34 +1632,174 @@ var init_Models = __esm({
           return (await AssetLoader.getFirst([key, legacyKey], "list" /* LIST */))?.asset;
         }).then((r) => r?.files ?? []);
       }
-      static async loadAndMerge(key) {
-        const model = key.type === "item" ? await this.getItemModel(key) : await this.getRaw(key);
+      static async loadAndMerge(key, context = {}) {
+        const model = key.type === "item" ? await this.getItemModel(key, context) : await this.getRaw(key);
         if (!model) {
           return void 0;
         }
         return ModelMerger.mergeWithParents(model);
       }
-      static async getItemModel(key) {
+      static async getItemModel(key, context = {}) {
+        const preview = this.snapshotContext(key, context);
         const itemKey = new AssetKey(key.namespace, key.path, "items", void 0, key.rootType, ".json", key.root);
-        const model = await this.PERSISTENT_CACHE.getOrLoad(`item-v2:${AssetLoader.persistentKey(itemKey.serialize())}`, async () => {
+        const cacheKey = itemKey.serialize() + this.contextKey(preview);
+        const model = await this.PERSISTENT_CACHE.getOrLoad(`item-v4:${AssetLoader.persistentKey(cacheKey)}`, async () => {
           const result = await AssetLoader.getFirst([itemKey, key], "json" /* JSON */);
           if (!result) return void 0;
-          if (result.key.assetType !== "items") return { ...result.asset, key };
-          const selected = this.defaultItemModel(result.asset.model, key);
-          const modelKey = AssetKey.parse("models", selected.model);
-          modelKey.root = key.root;
-          const model2 = await this.getRaw(modelKey);
-          if (!model2) throw new Error(`Item ${key.toNamespacedString()} references missing model ${selected.model}`);
-          return { ...model2, ...selected.special && { special: selected.special }, ...selected.tints && { tints: selected.tints } };
+          if (result.key.assetType !== "items") return { ...result.asset, key, components: preview.components };
+          const load = async (selected) => {
+            if ("parts" in selected) {
+              return { key, parts: await Promise.all(selected.parts.map(load)) };
+            }
+            if ("item" in selected) {
+              const model3 = await this.getItemModel(selected.item, { displayContext: preview.displayContext });
+              if (!model3) throw new Error(`Item ${key.toNamespacedString()} references missing item ${selected.item.toNamespacedString()}`);
+              return model3;
+            }
+            const modelKey = AssetKey.parse("models", selected.model);
+            modelKey.root = key.root;
+            const model2 = await this.getRaw(modelKey);
+            if (!model2) throw new Error(`Item ${key.toNamespacedString()} references missing model ${selected.model}`);
+            return { ...model2, components: preview.components, ...selected.special && { special: selected.special }, ...selected.tints && { tints: selected.tints } };
+          };
+          return load(this.selectItemModel(result.asset.model, key, preview));
+        });
+        const restore = (model2) => ({
+          ...model2,
+          key: Object.assign(new AssetKey("", ""), model2.key),
+          ...model2.parts && { parts: model2.parts.map(restore) }
         });
-        return model ? { ...model, key: Object.assign(new AssetKey("", ""), model.key) } : void 0;
+        return model ? restore(model) : void 0;
+      }
+      static contextIdentifier(id) {
+        if (typeof id !== "string" || !/^(?:[a-z0-9_.-]+:)?[a-z0-9_./-]+$/.test(id)) {
+          throw new Error(`Invalid item-preview identifier: ${id}`);
+        }
+        return id.includes(":") ? id : `minecraft:${id}`;
+      }
+      static snapshotContext(key, context) {
+        const displayContext = context.displayContext ?? "gui" /* GUI */;
+        if (displayContext !== "none" && !Object.values(DisplayPosition).includes(displayContext)) {
+          throw new Error(`Unsupported item display context: ${displayContext}`);
+        }
+        for (const map of [context.properties, context.components, context.itemReferences]) {
+          if (map !== void 0 && (!map || typeof map !== "object" || Array.isArray(map))) {
+            throw new Error("Item-preview properties, components, and references must be objects keyed by identifier");
+          }
+        }
+        const count = context.count === void 0 ? 1 : context.count;
+        if (!Number.isSafeInteger(count) || count < 0) throw new Error("Item-preview count must be a nonnegative safe integer");
+        const properties = {};
+        for (const [id, value] of Object.entries(context.properties ?? {})) {
+          const property = this.contextIdentifier(id);
+          if (!["boolean", "string", "number"].includes(typeof value) || typeof value === "number" && !Number.isFinite(value)) {
+            throw new Error(`Item-preview property ${property} must be a boolean, string, or finite number`);
+          }
+          if (Object.prototype.hasOwnProperty.call(properties, property)) throw new Error(`Duplicate item-preview property: ${property}`);
+          properties[property] = value;
+        }
+        const components = {};
+        for (const [id, value] of Object.entries(context.components ?? {})) {
+          const component = this.contextIdentifier(id);
+          if (Object.prototype.hasOwnProperty.call(components, component)) throw new Error(`Duplicate item-preview component: ${component}`);
+          components[component] = this.snapshotJson(value);
+        }
+        const itemReferences = {};
+        for (const [id, value] of Object.entries(context.itemReferences ?? {})) {
+          const reference = this.contextIdentifier(id);
+          if (!isAssetKey(value) || value.assetType !== "models" || value.type !== "item") {
+            throw new Error(`Item-preview reference ${reference} must be an item-model AssetKey`);
+          }
+          this.contextIdentifier(`${value.namespace}:${value.path}`);
+          if (Object.prototype.hasOwnProperty.call(itemReferences, reference)) throw new Error(`Duplicate item-preview reference: ${reference}`);
+          itemReferences[reference] = Object.assign(new AssetKey("", ""), value, { root: value.root ?? key.root });
+        }
+        return { displayContext, properties, components, count, itemReferences };
+      }
+      static contextKey(context) {
+        const itemReferences = Object.fromEntries(Object.entries(context.itemReferences).map(([id, key]) => [id, key.serialize()]));
+        return `|item-v4:${JSON.stringify(this.snapshotJson({ ...context, itemReferences }))}`;
       }
-      // Item previews use the GUI context, false conditions, and zero numeric properties.
-      static defaultItemModel(node, key) {
+      static snapshotJson(value, ancestors = /* @__PURE__ */ new Set()) {
+        if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return value;
+        if (typeof value !== "object" || ancestors.has(value) || !Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+          throw new Error("Item-preview components must contain finite JSON values without circular references");
+        }
+        ancestors.add(value);
+        const copy = Array.isArray(value) ? Array.from(value, (entry) => this.snapshotJson(entry, ancestors)) : Object.fromEntries(Object.keys(value).sort().map((key) => [key, this.snapshotJson(value[key], ancestors)]));
+        ancestors.delete(value);
+        return copy;
+      }
+      static propertyValue(node, context) {
+        const kind = node.type.replace(/^minecraft:/, "");
+        const property = node.property ? this.contextIdentifier(node.property) : void 0;
+        if (kind === "select" && property === "minecraft:display_context") return context.displayContext;
+        if (property && Object.prototype.hasOwnProperty.call(context.properties, property)) return context.properties[property];
+        const fallback = kind === "condition" ? false : kind === "range_dispatch" ? 0 : void 0;
+        const component = (id) => context.components[this.contextIdentifier(id)];
+        if (property === "minecraft:custom_model_data") {
+          const index = node.index ?? 0;
+          if (!Number.isSafeInteger(index) || index < 0) throw new Error("Item-model custom_model_data index must be a nonnegative integer");
+          const data = component("custom_model_data");
+          if (data === void 0) return fallback;
+          if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("Item-preview custom_model_data must be an object");
+          const field = kind === "condition" ? "flags" : kind === "select" ? "strings" : "floats";
+          const values = data[field];
+          if (values === void 0) return fallback;
+          if (!Array.isArray(values)) throw new Error(`Item-preview custom_model_data.${field} must be an array`);
+          return index < values.length ? values[index] : fallback;
+        }
+        if (kind === "condition" && property === "minecraft:has_component") {
+          if (node.ignore_default) throw new Error("Item-preview has_component with ignore_default requires an explicit properties override; item defaults are unavailable");
+          return Object.prototype.hasOwnProperty.call(context.components, this.contextIdentifier(node.component));
+        }
+        if (kind === "select") {
+          switch (property) {
+            case "minecraft:component":
+              return component(node.component);
+            case "minecraft:block_state": {
+              const state = component("block_state");
+              if (state === void 0) return void 0;
+              if (!state || typeof state !== "object" || Array.isArray(state)) throw new Error("Item-preview block_state must be an object");
+              if (typeof node.block_state_property !== "string") throw new Error("Item-model block_state requires block_state_property");
+              return Object.prototype.hasOwnProperty.call(state, node.block_state_property) ? state[node.block_state_property] : void 0;
+            }
+            case "minecraft:charge_type": {
+              const projectiles = component("charged_projectiles");
+              if (projectiles === void 0) return "none";
+              if (!Array.isArray(projectiles)) throw new Error("Item-preview charged_projectiles must be an array of item stacks");
+              const ids = projectiles.map((stack) => {
+                if (!stack || typeof stack !== "object" || Array.isArray(stack)) throw new Error("Item-preview charged_projectiles must contain item-stack objects");
+                return this.contextIdentifier(stack.id);
+              });
+              return !ids.length ? "none" : ids.includes("minecraft:firework_rocket") ? "rocket" : "arrow";
+            }
+          }
+        }
+        if (kind === "range_dispatch" && (property === "minecraft:damage" || property === "minecraft:count")) {
+          const damage = property === "minecraft:damage";
+          const maximumComponent = component(damage ? "max_damage" : "max_stack_size");
+          const maximum = maximumComponent === void 0 ? damage ? 0 : 1 : maximumComponent;
+          const damageComponent = component("damage");
+          const value = damage ? damageComponent === void 0 ? 0 : damageComponent : context.count;
+          if (typeof value !== "number" || typeof maximum !== "number" || maximum < 0) throw new Error(`Item-preview ${property} requires numeric components and a nonnegative maximum`);
+          const clamped = Math.max(0, Math.min(maximum, value));
+          return node.normalize === false ? clamped : clamped / maximum;
+        }
+        return fallback;
+      }
+      static selectItemModel(node, key, context) {
         if (!node || typeof node.type !== "string") {
           throw new Error(`Unsupported item model definition for ${key.toNamespacedString()}`);
         }
         switch (node.type.replace(/^minecraft:/, "")) {
+          case "composite":
+            if (Array.isArray(node.models)) return { parts: node.models.map((child) => this.selectItemModel(child, key, context)) };
+            break;
+          case "bundle/selected_item": {
+            const item = context.itemReferences["minecraft:bundle/selected_item"];
+            return item ? { item } : { parts: [] };
+          }
           case "model":
             if (typeof node.model === "string" && node.model) return { model: node.model, tints: node.tints };
             break;
@@ -1524,6 +1807,23 @@ var init_Models = __esm({
             if (!node.base || !node.model || typeof node.model !== "object") break;
             const special = node.model;
             switch (special.type) {
+              case "banner":
+              case "minecraft:banner":
+                if (typeof special.color === "string" && Object.prototype.hasOwnProperty.call(DYE_COLORS, special.color)) return { model: node.base, special };
+                break;
+              case "shield":
+              case "minecraft:shield":
+              case "trident":
+              case "minecraft:trident":
+              case "conduit":
+              case "minecraft:conduit":
+                return { model: node.base, special };
+              case "shulker_box":
+              case "minecraft:shulker_box":
+                if (typeof special.texture === "string" && special.texture && (special.openness === void 0 || typeof special.openness === "number" && Number.isFinite(special.openness)) && (special.orientation === void 0 || ["down", "up", "north", "south", "west", "east"].includes(special.orientation))) {
+                  return { model: node.base, special };
+                }
+                break;
               case "chest":
               case "minecraft:chest":
               case "bed":
@@ -1537,21 +1837,34 @@ var init_Models = __esm({
             }
             throw new Error(`Unsupported special item renderer ${special.type} for ${key.toNamespacedString()}`);
           }
-          case "condition":
-            return this.defaultItemModel(node.on_false, key);
+          case "condition": {
+            const value = this.propertyValue(node, context);
+            if (typeof value !== "boolean") throw new Error(`Item-preview condition ${node.property} requires a boolean`);
+            return this.selectItemModel(value ? node.on_true : node.on_false, key, context);
+          }
           case "select": {
-            const selected = node.property?.replace(/^minecraft:/, "") === "display_context" ? node.cases?.find((entry) => Array.isArray(entry.when) ? entry.when.includes("gui") : entry.when === "gui")?.model : void 0;
-            return this.defaultItemModel(selected ?? node.fallback, key);
+            const value = this.propertyValue(node, context);
+            const component = node.property && this.contextIdentifier(node.property) === "minecraft:component";
+            if (!component && value !== void 0 && typeof value !== "string") throw new Error(`Item-preview selector ${node.property} requires a string`);
+            const matches = (candidate) => component ? JSON.stringify(this.snapshotJson(candidate)) === JSON.stringify(this.snapshotJson(value)) : candidate === value;
+            const selected = value === void 0 ? void 0 : node.cases?.find((entry) => matches(entry.when) || Array.isArray(entry.when) && entry.when.some(matches))?.model;
+            return this.selectItemModel(selected ?? node.fallback, key, context);
           }
           case "range_dispatch": {
+            const value = this.propertyValue(node, context);
+            if (typeof value !== "number") throw new Error(`Item-preview range ${node.property} requires a number`);
+            if (Number.isNaN(value)) return this.selectItemModel(node.fallback, key, context);
+            const scaled = value * (node.scale ?? 1);
+            if (!Number.isFinite(scaled)) throw new Error(`Item-preview range ${node.property} requires a finite value and scale`);
             const selected = node.entries?.reduce((match, entry) => {
-              return entry.threshold <= 0 && (!match || entry.threshold >= match.threshold) ? entry : match;
+              return entry.threshold <= scaled && (!match || entry.threshold >= match.threshold) ? entry : match;
             }, void 0);
-            return this.defaultItemModel(selected?.model ?? node.fallback, key);
+            return this.selectItemModel(selected?.model ?? node.fallback, key, context);
           }
         }
         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";
@@ -1564,28 +1877,39 @@ 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;
         });
       }
-      static async getMerged(key) {
+      /**
+       * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
+       * Item keys default to GUI context and a stack count of 1. Unresolved conditions are false and numeric properties are zero.
+       * Pass `context` to supply component values, property overrides, and item references for a preview.
+       * Composite items retain independently merged children in `ItemModel.parts`.
+       *
+       * @param key - Model key, for example `AssetKey.parse("models", "minecraft:item/diamond_sword")`.
+       */
+      static async getMerged(key, context = {}) {
         if (!key.assetType) {
           key.assetType = "models";
         }
         if (!key.extension) {
           key.extension = ".json";
         }
-        const keyStr = key.serialize();
+        const preview = this.snapshotContext(key, context);
+        const keyStr = key.serialize() + (key.type === "item" ? this.contextKey(preview) : "");
         return Caching.mergedModelCache.get(keyStr, (k) => {
-          return _Models.loadAndMerge(key);
+          return _Models.loadAndMerge(key, preview);
         });
       }
-      static async get(key) {
-        return this.getMerged(key);
+      /** Alias for {@link getMerged}. */
+      static async get(key, context = {}) {
+        return this.getMerged(key, context);
       }
+      /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
       static async clearCache() {
         return this.PERSISTENT_CACHE.clear();
       }
@@ -1608,6 +1932,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,
@@ -1628,6 +1953,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) {
@@ -1635,6 +1961,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";
@@ -1647,11 +1974,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) {
@@ -1661,6 +1988,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();
       }
@@ -1686,9 +2014,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);
       }
@@ -1703,6 +2033,10 @@ var init_AssetSource = __esm({
     AssetSource = class {
       constructor() {
       }
+      /** Whether this source prevents lower-priority sources from supplying the key. Its own assets remain available. */
+      blocks(key) {
+        return false;
+      }
       /**
        * Identifies this source's content across sessions for persistent caching. Sources that
        * cannot tell whether their content changed (an unnamed archive, for example) return
@@ -1731,6 +2065,10 @@ var BatchedExecutor;
 var init_BatchedExecutor = __esm({
   "src/util/BatchedExecutor.ts"() {
     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");
@@ -1738,9 +2076,11 @@ var init_BatchedExecutor = __esm({
         this.batch = batch;
         this.queue = new JobQueue2(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();
       }
@@ -1788,29 +2128,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 Vector33();
   box.getSize(size);
   let boxGeo = new BoxGeometry2(size.x, size.y, size.z, 1, 1, 1);
   let wireGeo = new EdgesGeometry(boxGeo);
-  let wireMat = new LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new LineSegments(wireGeo, wireMat);
   obj.add(wireframe);
   let axes = new AxesHelper(1);
   obj.add(axes);
 }
-function addWireframeToObject(obj, color = 16777215, w = 2) {
+function addWireframeToObject(obj, color2 = 16777215, w = 2) {
   let boxGeo = new BoxGeometry2(16, 16, 16, 1, 1, 1);
   let wireGeo = new EdgesGeometry(boxGeo);
-  let wireMat = new LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new LineSegments(wireGeo, wireMat);
   obj.add(wireframe);
   let axes = new AxesHelper(1);
   obj.add(axes);
 }
-function addWireframeToMesh(geo, mesh, color = 16777215, w = 2) {
+function addWireframeToMesh(geo, mesh, color2 = 16777215, w = 2) {
   let wireGeo = new EdgesGeometry(geo);
-  let wireMat = new LineBasicMaterial({ color, linewidth: w });
+  let wireMat = new LineBasicMaterial({ color: color2, linewidth: w });
   let wireframe = new LineSegments(wireGeo, wireMat);
   mesh.add(wireframe);
   let axes = new AxesHelper(1);
@@ -1882,10 +2222,11 @@ var NBTHelper;
 var init_NBTHelper = __esm({
   "src/nbt/NBTHelper.ts"() {
     NBTHelper = class {
-      static async fromBuffer(data, format) {
+      /** Parses NBT bytes and preserves format and compression metadata. Omit `format` for automatic detection. */
+      static async fromBuffer(data, format2) {
         const buffer = Buffer3.from(data instanceof Uint8Array ? data : new Uint8Array(data));
         const prismarineNbt = await import("prismarine-nbt");
-        const { parsed, type, metadata } = await prismarineNbt.parse(buffer, format);
+        const { parsed, type, metadata } = await prismarineNbt.parse(buffer, format2);
         return Object.assign(parsed, {
           format: type,
           metadata,
@@ -1950,6 +2291,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") {
@@ -2007,6 +2349,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;
@@ -2099,6 +2445,11 @@ var BrowserArchiveProxy;
 var init_BrowserArchiveProxy = __esm({
   "src/assets/source/archive/BrowserArchiveProxy.ts"() {
     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 ZipReader(new BlobReader(this._blob));
@@ -2119,6 +2470,162 @@ var init_BrowserArchiveProxy = __esm({
   }
 });
 
+// src/assets/source/archive/PackMetadata.ts
+function object(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid ${field}: expected an object`);
+  }
+  return value;
+}
+function integer(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`Invalid ${field}: expected a nonnegative integer`);
+  }
+  return value;
+}
+function format(value, field, upper = false) {
+  const parts = Array.isArray(value) ? value : [value];
+  if (parts.length < 1 || parts.length > 2) {
+    throw new Error(`Invalid ${field}: expected a major version or [major, minor]`);
+  }
+  return [integer(parts[0], field), parts.length === 2 ? integer(parts[1], field) : upper ? Infinity : 0];
+}
+function compare(a, b) {
+  return a[0] === b[0] ? a[1] - b[1] : a[0] - b[0];
+}
+function overlay(value, field) {
+  const entry = object(value, field);
+  const directory = entry.directory;
+  if (typeof directory !== "string" || !directory || /[^-_a-zA-Z0-9.]/.test(directory) || directory === "." || directory === "..") {
+    throw new Error(`Invalid ${field}.directory: expected a directory name without path separators`);
+  }
+  let min, max;
+  if ("min_format" in entry || "max_format" in entry) {
+    min = format(entry.min_format, `${field}.min_format`);
+    max = format(entry.max_format, `${field}.max_format`, true);
+  } else {
+    const range = entry.formats;
+    let lower, upper;
+    if (typeof range === "number") {
+      lower = upper = range;
+    } else if (Array.isArray(range)) {
+      if (range.length !== 2) throw new Error(`Invalid ${field}.formats: expected [min, max]`);
+      [lower, upper] = range;
+    } else {
+      const bounds = object(range, `${field}.formats`);
+      lower = bounds.min_inclusive;
+      upper = bounds.max_inclusive;
+    }
+    min = [integer(lower, `${field}.formats.min_inclusive`), 0];
+    max = [integer(upper, `${field}.formats.max_inclusive`), Infinity];
+  }
+  if (compare(min, max) > 0) throw new Error(`Invalid ${field}: minimum format exceeds maximum format`);
+  return { directory, min, max };
+}
+function pattern(value, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") throw new Error(`Invalid ${field}: expected a regular expression string`);
+  try {
+    return new RegExp(value);
+  } catch (cause) {
+    throw new Error(`Invalid ${field}: ${String(cause)}`);
+  }
+}
+var PackMetadata;
+var init_PackMetadata = __esm({
+  "src/assets/source/archive/PackMetadata.ts"() {
+    PackMetadata = class _PackMetadata {
+      constructor(overlays, filters) {
+        this.overlays = overlays;
+        this.filters = filters;
+        this.hasOverlays = overlays.length > 0;
+      }
+      static parse(value) {
+        const metadata = object(value, "pack.mcmeta");
+        let overlays = [];
+        if ("overlays" in metadata) {
+          const entries = object(metadata.overlays, "overlays").entries;
+          if (!Array.isArray(entries)) throw new Error("Invalid overlays.entries: expected an array");
+          overlays = entries.map((entry, index) => overlay(entry, `overlays.entries[${index}]`));
+        }
+        let filters = [];
+        if ("filter" in metadata) {
+          const entries = object(metadata.filter, "filter").block;
+          if (!Array.isArray(entries)) throw new Error("Invalid filter.block: expected an array");
+          filters = entries.map((value2, index) => {
+            const field = `filter.block[${index}]`;
+            const entry = object(value2, field);
+            return { namespace: pattern(entry.namespace, `${field}.namespace`), path: pattern(entry.path, `${field}.path`) };
+          });
+        }
+        return new _PackMetadata(overlays, filters);
+      }
+      /** Returns applicable directories in lookup order, with the last declared overlay first. */
+      overlayDirectories(target) {
+        const selected = format(target, "target format");
+        return this.overlays.filter((entry) => compare(selected, entry.min) >= 0 && compare(selected, entry.max) <= 0).map((entry) => entry.directory).reverse();
+      }
+      blocks(namespace, path) {
+        return this.filters.some((entry) => entry.namespace?.test(namespace) ?? true) && this.filters.some((entry) => entry.path?.test(path) ?? true);
+      }
+    };
+  }
+});
+
+// src/assets/source/archive/PackFormats.ts
+var PackFormats;
+var init_PackFormats = __esm({
+  "src/assets/source/archive/PackFormats.ts"() {
+    init_Requests();
+    PackFormats = class {
+      /** Resolves pack formats from Mojang's client metadata hosted on assets.mcasset.cloud. */
+      static async get(version2, type) {
+        let pending = this.versions.get(version2);
+        if (!pending || pending.expires <= Date.now()) {
+          pending = {
+            formats: this.load(version2),
+            expires: ["latest", "release", "snapshot"].includes(version2) ? Date.now() + 3e5 : Infinity
+          };
+          this.versions.set(version2, pending);
+        }
+        try {
+          return (await pending.formats)[type];
+        } catch (cause) {
+          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 ${version2}. Set ArchiveAssetSource ${option} explicitly. ${reason}`);
+        }
+      }
+      static async load(version2) {
+        const response = await Requests.genericRequest({
+          url: `https://assets.mcasset.cloud/${encodeURIComponent(version2)}/game-version.json`,
+          responseType: "json"
+        });
+        const data = response.data;
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+          throw new Error("Expected version metadata to be an object");
+        }
+        const packs = data.pack_version;
+        if (typeof packs !== "number" && (!packs || typeof packs !== "object" || Array.isArray(packs))) {
+          throw new Error("Expected pack_version to be a number or an object");
+        }
+        const format2 = (type) => {
+          const modern = typeof packs === "object" && ["resource_major", "resource_minor", "data_major", "data_minor"].some((key) => key in packs);
+          const major = typeof packs === "number" ? packs : packs[modern ? `${type}_major` : type];
+          const minor = modern ? packs[`${type}_minor`] : 0;
+          if (typeof major !== "number" || !Number.isSafeInteger(major) || major < 0 || typeof minor !== "number" || !Number.isSafeInteger(minor) || minor < 0) {
+            throw new Error(`Invalid ${type} pack format in version metadata`);
+          }
+          return Object.freeze([major, minor]);
+        };
+        return { assets: format2("resource"), data: format2("data") };
+      }
+    };
+    PackFormats.versions = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/assets/source/archive/ArchiveAssetSource.ts
 var ArchiveAssetSource;
 var init_ArchiveAssetSource = __esm({
@@ -2127,35 +2634,78 @@ var init_ArchiveAssetSource = __esm({
     init_request();
     init_HostedAssetSource();
     init_BrowserArchiveProxy();
+    init_AssetLoader();
+    init_PackMetadata();
+    init_PackFormats();
     ArchiveAssetSource = class _ArchiveAssetSource extends AssetSource {
-      constructor(archiveProxy) {
+      constructor(archiveProxy, options = {}) {
         super();
-        console.log(archiveProxy);
         this._archiveProxy = archiveProxy;
+        const copyFormat = (format2) => typeof format2 === "object" ? [format2[0], format2[1]] : format2;
+        this.options = {
+          resourcePackFormat: copyFormat(options.resourcePackFormat),
+          dataPackFormat: copyFormat(options.dataPackFormat)
+        };
       }
-      static blob(blob) {
-        return new _ArchiveAssetSource(new BrowserArchiveProxy(blob));
+      /** Creates a browser ZIP source from a Blob or File. */
+      static blob(blob, options) {
+        return new _ArchiveAssetSource(new BrowserArchiveProxy(blob), options);
       }
       get cacheId() {
         const id = this._archiveProxy.id;
-        return id === void 0 ? void 0 : `archive:${id}`;
+        const formats = [this.options.resourcePackFormat ?? AssetLoader.version, this.options.dataPackFormat ?? AssetLoader.version];
+        return id === void 0 ? void 0 : `archive-metadata:1:${id}:${JSON.stringify(formats)}`;
       }
       async getEntries() {
-        return this._archiveProxy.getEntries();
+        return this.entries ?? (this.entries = this._archiveProxy.getEntries().catch((error) => {
+          this.entries = void 0;
+          throw error;
+        }));
       }
       async getEntry(path) {
         const entries = await this.getEntries();
         return entries.find((e) => e.filename === path);
       }
+      async getMetadata(key) {
+        try {
+          return await (this.metadata ?? (this.metadata = this.getEntry("pack.mcmeta").then(async (entry) => PackMetadata.parse(entry ? JSON.parse(await (await entry.getData()).text()) : {})).catch((error) => {
+            this.metadata = void 0;
+            throw error;
+          })));
+        } catch (cause) {
+          throw new AssetLoadError(this, key, "pack.mcmeta", cause);
+        }
+      }
+      async blocks(key) {
+        if (key.rootType !== "assets" && key.rootType !== "data") return false;
+        const metadata = await this.getMetadata(key);
+        const path = `${key.assetType !== void 0 ? key.assetType + "/" : ""}${key.getFullPath()}${key.extension}`;
+        return metadata.blocks(key.namespace, path);
+      }
       async get(key, parser) {
         const responseParser = HostedAssetSource.PARSER_MAP.get(parser);
         return this.load(key, responseParser);
       }
       async load(key, parser) {
         const path = `${this.assetBasePath(key)}${key.type !== void 0 ? key.type + "/" : ""}${key.path}${key.extension}`;
+        const version2 = AssetLoader.version;
+        let selectedPath = path;
         let url;
         try {
-          const entry = await this.getEntry(path);
+          let directories = [];
+          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(version2, key.rootType);
+              directories = metadata.overlayDirectories(format2);
+            }
+          }
+          let entry;
+          for (const directory of [...directories, ""]) {
+            selectedPath = directory ? `${directory}/${path}` : path;
+            entry = await this.getEntry(selectedPath);
+            if (entry) break;
+          }
           if (!entry) {
             return void 0;
           }
@@ -2168,7 +2718,8 @@ var init_ArchiveAssetSource = __esm({
           }
           return await parser.parse(response);
         } catch (cause) {
-          throw new AssetLoadError(this, key, path, cause);
+          if (cause instanceof AssetLoadError) throw cause;
+          throw new AssetLoadError(this, key, selectedPath, cause);
         } finally {
           if (url !== void 0) {
             URL.revokeObjectURL(url);
@@ -2201,6 +2752,8 @@ var init_archive = __esm({
     init_ArchiveEntry();
     init_ArchiveProxy();
     init_BrowserArchiveProxy();
+    init_PackFormats();
+    init_PackMetadata();
   }
 });
 
@@ -2229,8 +2782,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) {
@@ -2262,6 +2816,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);
@@ -2272,6 +2833,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) {
@@ -2282,14 +2844,16 @@ ${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) {
-        let promises = [];
-        for (const source of this._SOURCES) {
-          promises.push(source.source.get(key, parser));
+        const sources = [...this._SOURCES];
+        const results = [];
+        for (const { source } of sources) {
+          const asset2 = await source.get(key, parser);
+          if (asset2 != void 0) results.push(asset2);
+          if (await source.blocks(key)) break;
         }
-        return Promise.all(promises).then((results) => {
-          return results.filter((r) => r != void 0);
-        });
+        return results;
       }
       /** Returns the first defined result in source-priority order, without merging assets. */
       static async get(key, parser) {
@@ -2310,17 +2874,22 @@ ${key}` : key;
       /** Tries each path within a source before considering lower-priority sources. */
       static async getFirst(keys, parser) {
         const sources = [...this._SOURCES];
+        let remaining = [...keys];
         for (const source of sources) {
-          for (const key of keys) {
+          for (const key of remaining) {
             const result = await source.source.get(key, parser);
             if (result !== void 0) {
               return { key, asset: result };
             }
           }
+          const blocked = await Promise.all(remaining.map((key) => source.source.blocks(key)));
+          remaining = remaining.filter((_, index) => !blocked[index]);
+          if (!remaining.length) break;
         }
         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. */
@@ -2345,14 +2914,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) {
@@ -2362,16 +2932,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);
@@ -2380,14 +2952,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();
       }
@@ -2454,6 +3027,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(() => {
@@ -2476,6 +3050,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);
@@ -2484,12 +3059,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();
@@ -2503,6 +3080,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();
@@ -2557,6 +3135,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];
@@ -2767,6 +3346,37 @@ var init_UVMapper = __esm({
       static facesToUv(faces, originalTextureSize, actualTextureSize) {
         return new Float32BufferAttribute2(this.facesToUvArray(faces, originalTextureSize, actualTextureSize), 2);
       }
+      /** Bounds texture sampling to texel centres without changing cropped face UVs. */
+      static setAtlasUvBounds(geometry, faces, atlas) {
+        const uv = geometry.getAttribute("uv");
+        const bounds = new Float32Array(uv.count * 4);
+        for (const [faceIndex, faceName] of CUBE_FACES.entries()) {
+          const texture = faces[faceName]?.texture?.substring(1);
+          const position = texture && atlas.positions[texture];
+          const size = texture && atlas.sizes[texture];
+          let minU = Infinity, minV = Infinity, maxU = -Infinity, maxV = -Infinity;
+          if (position && size) {
+            minU = position[0] / atlas.image.width;
+            maxU = (position[0] + size[0]) / atlas.image.width;
+            minV = 1 - (position[1] + size[1]) / atlas.image.height;
+            maxV = 1 - position[1] / atlas.image.height;
+          } else {
+            for (let corner = 0; corner < 4; corner++) {
+              const index = faceIndex * 4 + corner;
+              minU = Math.min(minU, uv.getX(index));
+              minV = Math.min(minV, uv.getY(index));
+              maxU = Math.max(maxU, uv.getX(index));
+              maxV = Math.max(maxV, uv.getY(index));
+            }
+          }
+          const insetU = Math.min(0.5 / atlas.image.width, (maxU - minU) / 2);
+          const insetV = Math.min(0.5 / atlas.image.height, (maxV - minV) / 2);
+          for (let corner = 0; corner < 4; corner++) {
+            bounds.set([minU + insetU, minV + insetV, maxU - insetU, maxV - insetV], (faceIndex * 4 + corner) * 4);
+          }
+        }
+        geometry.setAttribute("uvBounds", new Float32BufferAttribute2(bounds, 4));
+      }
       static lockUvs(geometry, faces, atlas, rotation) {
         const uv = geometry.getAttribute("uv");
         for (let faceIndex = 0; faceIndex < CUBE_FACES.length; faceIndex++) {
@@ -2803,6 +3413,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) => {
@@ -2873,6 +3484,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 = {};
@@ -2893,12 +3509,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;
@@ -3237,14 +3853,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("");
@@ -3254,6 +3871,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 ?? {});
       }
@@ -3261,6 +3879,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;
@@ -3306,6 +3933,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;
@@ -3317,8 +3945,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);
@@ -3423,27 +4051,27 @@ var init_EntityAnimationPlayer = __esm({
         for (const layer of layers) {
           const objects = [];
           if (poses) {
-            layer.traverse((object) => {
-              if (poses.has(object)) objects.push(object);
+            layer.traverse((object3) => {
+              if (poses.has(object3)) objects.push(object3);
             });
           } else {
             for (const bone of Object.keys(animation.bones)) {
-              const object = layer.getObjectByName(`group:${bone}`);
-              if (object) objects.push(object);
+              const object3 = layer.getObjectByName(`group:${bone}`);
+              if (object3) objects.push(object3);
             }
           }
-          for (const object of objects) {
-            const bone = object.name.slice("group:".length);
-            const pose = poses?.get(object);
+          for (const object3 of objects) {
+            const bone = object3.name.slice("group:".length);
+            const pose = poses?.get(object3);
             this.parts.push({
               bone,
-              object,
-              position: object.position.clone(),
-              rotation: object.rotation.clone(),
-              scale: object.scale.clone(),
-              basePosition: pose ? new Vector35(...pose.offset) : object.position.clone(),
-              baseRotation: pose ? new Euler3(...pose.rotation, "ZYX") : object.rotation.clone(),
-              baseScale: pose ? new Vector35(...pose.scale ?? [1, 1, 1]) : object.scale.clone()
+              object: object3,
+              position: object3.position.clone(),
+              rotation: object3.rotation.clone(),
+              scale: object3.scale.clone(),
+              basePosition: pose ? new Vector35(...pose.offset) : object3.position.clone(),
+              baseRotation: pose ? new Euler3(...pose.rotation, "ZYX") : object3.rotation.clone(),
+              baseScale: pose ? new Vector35(...pose.scale ?? [1, 1, 1]) : object3.scale.clone()
             });
           }
         }
@@ -3466,12 +4094,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);
       }
@@ -3509,6 +4139,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);
       }
@@ -3521,9 +4152,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);
       }
@@ -3592,6 +4225,7 @@ var init_SceneObject = __esm({
       }
       async init() {
       }
+      /** Marks ancestor scenes for redraw and emits a `change` event. */
       notifyDirty() {
         this.traverseAncestors((parent) => {
           const scene = parent;
@@ -3627,15 +4261,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);
@@ -3686,15 +4322,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);
@@ -3740,12 +4377,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");
@@ -3790,10 +4429,10 @@ var init_SceneObject = __esm({
           return new 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) {
@@ -3892,6 +4531,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()) {
@@ -3910,6 +4550,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()) {
@@ -3927,6 +4568,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()) {
@@ -3944,6 +4586,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()) {
@@ -3962,15 +4605,15 @@ var init_SceneObject = __esm({
         }
       }
       //</editor-fold>
-      toggleObjectVisibility(object, visible) {
-        if (object) {
+      toggleObjectVisibility(object3, visible) {
+        if (object3) {
           if (typeof visible !== "undefined") {
-            object.visible = visible;
+            object3.visible = visible;
           } else {
-            object.visible = !object.visible;
+            object3.visible = !object3.visible;
           }
           this.notifyDirty();
-          return object.visible;
+          return object3.visible;
         }
         this.notifyDirty();
         return false;
@@ -3981,6 +4624,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;
@@ -4003,6 +4647,7 @@ var init_SceneObject = __esm({
         }
         this.notifyDirty();
       }
+      /** Detaches the object from its parent and requests a redraw. */
       removeFromScene() {
         this.notifyDirty();
         this.removeFromParent();
@@ -4158,12 +4803,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}`);
       }
@@ -4265,8 +4913,8 @@ var init_EntityObject = __esm({
               this.scrollMaterials.push({ material: mat, offset: mat.map.offset, speed: scroll });
             }
           }
-          this.getLayerGroup(name)?.traverse((object) => {
-            if (isMesh(object)) object.material = mat;
+          this.getLayerGroup(name)?.traverse((object3) => {
+            if (isMesh(object3)) object3.material = mat;
           });
         }));
         if (!this.children.length) {
@@ -4607,8 +5255,8 @@ function toTrianglesDrawMode(geometry, drawMode) {
     return geometry;
   }
 }
-function computeMorphedAttributes(object) {
-  if (object.geometry.isBufferGeometry !== true) {
+function computeMorphedAttributes(object3) {
+  if (object3.geometry.isBufferGeometry !== true) {
     console.error("THREE.BufferGeometryUtils: Geometry is not of type BufferGeometry.");
     return null;
   }
@@ -4621,11 +5269,11 @@ function computeMorphedAttributes(object) {
   const _morphA = new Vector310();
   const _morphB = new Vector310();
   const _morphC = new Vector310();
-  function _calculateMorphedAttributeData(object2, 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 = object2.morphTargetInfluences;
+    const morphInfluences = object4.morphTargetInfluences;
     if (material2.morphTargets && morphAttribute && morphInfluences) {
       _morphA.set(0, 0, 0);
       _morphB.set(0, 0, 0);
@@ -4651,10 +5299,10 @@ function computeMorphedAttributes(object) {
       _vB.add(_morphB);
       _vC.add(_morphC);
     }
-    if (object2.isSkinnedMesh) {
-      object2.boneTransform(a2, _vA);
-      object2.boneTransform(b2, _vB);
-      object2.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;
@@ -4666,8 +5314,8 @@ function computeMorphedAttributes(object) {
     modifiedAttributeArray[c2 * 3 + 1] = _vC.y;
     modifiedAttributeArray[c2 * 3 + 2] = _vC.z;
   }
-  const geometry = object.geometry;
-  const material = object.material;
+  const geometry = object3.geometry;
+  const material = object3.material;
   let a, b, c;
   const index = geometry.index;
   const positionAttribute = geometry.attributes.position;
@@ -4694,7 +5342,7 @@ function computeMorphedAttributes(object) {
           b = index.getX(j + 1);
           c = index.getX(j + 2);
           _calculateMorphedAttributeData(
-            object,
+            object3,
             groupMaterial,
             positionAttribute,
             morphPosition,
@@ -4705,7 +5353,7 @@ function computeMorphedAttributes(object) {
             modifiedPosition
           );
           _calculateMorphedAttributeData(
-            object,
+            object3,
             groupMaterial,
             normalAttribute,
             morphNormal,
@@ -4725,7 +5373,7 @@ function computeMorphedAttributes(object) {
         b = index.getX(i + 1);
         c = index.getX(i + 2);
         _calculateMorphedAttributeData(
-          object,
+          object3,
           material,
           positionAttribute,
           morphPosition,
@@ -4736,7 +5384,7 @@ function computeMorphedAttributes(object) {
           modifiedPosition
         );
         _calculateMorphedAttributeData(
-          object,
+          object3,
           material,
           normalAttribute,
           morphNormal,
@@ -4760,7 +5408,7 @@ function computeMorphedAttributes(object) {
           b = j + 1;
           c = j + 2;
           _calculateMorphedAttributeData(
-            object,
+            object3,
             groupMaterial,
             positionAttribute,
             morphPosition,
@@ -4771,7 +5419,7 @@ function computeMorphedAttributes(object) {
             modifiedPosition
           );
           _calculateMorphedAttributeData(
-            object,
+            object3,
             groupMaterial,
             normalAttribute,
             morphNormal,
@@ -4791,7 +5439,7 @@ function computeMorphedAttributes(object) {
         b = i + 1;
         c = i + 2;
         _calculateMorphedAttributeData(
-          object,
+          object3,
           material,
           positionAttribute,
           morphPosition,
@@ -4802,7 +5450,7 @@ function computeMorphedAttributes(object) {
           modifiedPosition
         );
         _calculateMorphedAttributeData(
-          object,
+          object3,
           material,
           normalAttribute,
           morphNormal,
@@ -4836,6 +5484,7 @@ var init_ModelCulling = __esm({
   "src/model/ModelCulling.ts"() {
     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()) {
@@ -4846,6 +5495,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];
@@ -4872,15 +5522,17 @@ var init_ModelCulling = __esm({
 });
 
 // src/model/SpecialItems.ts
-import { Matrix4 as Matrix48 } from "three";
+import { Euler as Euler7, Matrix4 as Matrix48 } from "three";
 var SpecialItems;
 var init_SpecialItems = __esm({
   "src/model/SpecialItems.ts"() {
     init_AssetKey();
     init_Entities();
+    init_BannerPatterns();
+    init_ModelTextures();
     SpecialItems = class {
       /** Resolves the static entity parts drawn by a special item renderer, in model units. */
-      static async getParts(special, root) {
+      static async getParts(special, root, components = {}) {
         const texture = (id, directory) => {
           const key = AssetKey.parse("textures", id);
           return new AssetKey(
@@ -4893,13 +5545,77 @@ var init_SpecialItems = __esm({
             root
           );
         };
-        const load = async (id, textureKey, transform, rotations = {}) => {
+        const load = async (id, textureKey, transform, rotations = {}, layers = ["main"]) => {
           const key = new AssetKey("minecraft", id, void 0, void 0, "entity-models", ".json", root);
-          const model = await Entities.getEntity(key, textureKey, { layer: "main" });
+          const model = await Entities.getEntity(key, textureKey, layers.length === 1 ? { layer: layers[0] } : {
+            layers,
+            textures: textureKey ? Object.fromEntries(layers.map((name) => [name, textureKey])) : void 0
+          });
           if (!model) throw new Error(`Missing entity model minecraft:${id} for special item ${special.type}`);
           return { model, transform, rotations };
         };
         switch (special.type) {
+          case "minecraft:trident":
+          case "trident":
+          case "minecraft:conduit":
+          case "conduit": {
+            const trident = special.type === "trident" || special.type === "minecraft:trident";
+            const part = await load(
+              trident ? "trident" : "conduit",
+              texture(trident ? "trident" : "conduit/base", ""),
+              trident ? new Matrix48().makeScale(1, -1, -1) : new Matrix48().makeTranslation(8, 8, 8),
+              {},
+              trident ? ["main"] : ["shell"]
+            );
+            part.model = { ...part.model, render: "solid", layers: part.model.layers && Object.fromEntries(
+              Object.entries(part.model.layers).map(([name, layer]) => [name, { ...layer, render: "solid" }])
+            ) };
+            return [part];
+          }
+          case "minecraft:banner":
+          case "banner":
+          case "minecraft:shield":
+          case "shield": {
+            const banner = special.type === "banner" || special.type === "minecraft:banner";
+            const color2 = banner ? BannerPatterns.getColor(special.color) : components["minecraft:base_color"] === void 0 ? void 0 : BannerPatterns.getColor(components["minecraft:base_color"]);
+            const patterns = await BannerPatterns.getLayers(components["minecraft:banner_patterns"], banner ? "banner" : "shield", root);
+            const patterned = banner || color2 !== void 0 || patterns.length > 0;
+            const baseTexture = texture(banner ? "banner_base" : patterned ? "shield_base" : "shield_base_nopattern", "");
+            const transform = banner ? new Matrix48().makeTranslation(8, 0, 8).multiply(new Matrix48().makeScale(2 / 3, -2 / 3, -2 / 3)) : new Matrix48().makeScale(1, -1, -1);
+            const part = await load(banner ? "standing_banner" : "shield", baseTexture, transform, {}, banner ? ["main", "flag"] : ["main"]);
+            const layers = Object.fromEntries(Object.entries(part.model.layers ?? { main: part.model }).map(([name, layer]) => [name, { ...layer, render: "solid" }]));
+            let overlay2;
+            if (banner) {
+              const flagLayer = layers.flag;
+              const flag = flagLayer?.layer.root.children.flag;
+              if (!flag) throw new Error("Banner entity model is missing its flag layer");
+              overlay2 = { ...flagLayer.layer, root: { ...flagLayer.layer.root, children: {
+                ...flagLayer.layer.root.children,
+                flag: { ...flag, pose: { ...flag.pose, rotation: [-25e-4 * Math.PI, flag.pose.rotation[1], flag.pose.rotation[2]] } }
+              } } };
+              layers.flag = { ...flagLayer, layer: overlay2 };
+            } else {
+              const main = layers.main.layer;
+              const plate = main.root.children.plate;
+              if (!plate) throw new Error("Shield entity model is missing its plate");
+              overlay2 = { ...main, root: { ...main.root, cubes: [], children: { plate } } };
+            }
+            const tints = {};
+            if (patterned) {
+              const draws = [{ texture: texture(`${banner ? "banner" : "shield"}/base`, ""), color: color2 ?? DYE_COLORS.white }, ...patterns];
+              draws.forEach((draw, index) => {
+                const name = index === 0 ? "pattern_base" : `pattern_${index - 1}`;
+                layers[name] = { key: draw.texture, texture: draw.texture, layer: overlay2, render: "no_outline", tint: name };
+                tints[name] = draw.color;
+              });
+            }
+            await Promise.all([...new Map(Object.values(layers).map((layer) => [layer.texture.serialize(), layer.texture])).values()].map(async (key) => {
+              if (!await ModelTextures.preload(key)) throw new Error(`Missing special item texture ${key.toNamespacedString()}`);
+            }));
+            part.model = { ...part.model, ...layers.main, layers };
+            part.tints = tints;
+            return [part];
+          }
           case "minecraft:chest":
           case "chest": {
             const angle = -(special.openness ?? 0) * Math.PI / 2;
@@ -4910,6 +5626,26 @@ var init_SpecialItems = __esm({
             chest.model = { ...chest.model, render: "solid", layers: void 0 };
             return [chest];
           }
+          case "minecraft:shulker_box":
+          case "shulker_box": {
+            const openness = special.openness === void 0 ? 0 : special.openness;
+            const orientation = special.orientation === void 0 ? "up" : special.orientation;
+            const directions = {
+              down: [Math.PI, 0, 0],
+              up: [0, 0, 0],
+              north: [Math.PI / 2, 0, Math.PI],
+              south: [Math.PI / 2, 0, 0],
+              west: [Math.PI / 2, 0, Math.PI / 2],
+              east: [Math.PI / 2, 0, -Math.PI / 2]
+            };
+            if (!Object.prototype.hasOwnProperty.call(directions, orientation)) throw new Error(`Unsupported shulker-box orientation ${orientation}`);
+            if (typeof openness !== "number" || !Number.isFinite(openness)) throw new Error("Shulker-box openness must be finite");
+            if (typeof special.texture !== "string" || !special.texture) throw new Error("Shulker-box texture is required");
+            const transform = new Matrix48().makeTranslation(8, 8, 8).multiply(new Matrix48().makeScale(0.9995, 0.9995, 0.9995)).multiply(new Matrix48().makeRotationFromEuler(new Euler7(...directions[orientation], "XYZ"))).multiply(new Matrix48().makeScale(1, -1, -1)).multiply(new Matrix48().makeTranslation(0, -16, 0));
+            const box = await load("shulker_box", texture(special.texture, "shulker"), transform, { lid: [0, openness * Math.PI * 1.5, 0] });
+            box.positions = { lid: [0, 24 - openness * 8, 0] };
+            return [box];
+          }
           case "minecraft:bed":
           case "bed": {
             const transform = new Matrix48().makeTranslation(0, 9, 0).multiply(new Matrix48().makeRotationX(Math.PI / 2)).multiply(new Matrix48().makeTranslation(8, 8, 8)).multiply(new Matrix48().makeRotationZ(Math.PI)).multiply(new Matrix48().makeTranslation(-8, -8, -8));
@@ -5024,6 +5760,7 @@ var init_ItemTints = __esm({
       static async get(model, tints) {
         const sources = model.tints;
         if (!sources?.length) return tints;
+        const components = model.components ?? {};
         const colors = { ...tints };
         await Promise.all(sources.map(async (source, index) => {
           if (colors[index] !== void 0) return;
@@ -5038,27 +5775,71 @@ var init_ItemTints = __esm({
               break;
             case "dye":
             case "minecraft:dye":
+              colors[index] = this.colorOrDefault(components["minecraft:dyed_color"], source.default, true);
+              break;
             case "potion":
-            case "minecraft:potion":
+            case "minecraft:potion": {
+              const value = typeof components["minecraft:potion_contents"] === "string" ? void 0 : this.componentField(components, "potion_contents", "custom_color");
+              colors[index] = this.colorOrDefault(value, source.default);
+              break;
+            }
             case "map_color":
             case "minecraft:map_color":
+              colors[index] = this.colorOrDefault(components["minecraft:map_color"], source.default);
+              break;
             case "firework":
-            case "minecraft:firework":
+            case "minecraft:firework": {
+              const values = this.componentField(components, "firework_explosion", "colors");
+              if (values !== void 0 && !Array.isArray(values)) throw new MineRenderError("Item tint firework_explosion.colors must be an array");
+              if (!values?.length) {
+                colors[index] = this.rgb(source.default);
+                break;
+              }
+              const rgb = values.map((value) => this.componentColor(value));
+              const red = Math.floor(rgb.reduce((sum, color2) => sum + (color2 >> 16 & 255), 0) / rgb.length);
+              const green = Math.floor(rgb.reduce((sum, color2) => sum + (color2 >> 8 & 255), 0) / rgb.length);
+              const blue = Math.floor(rgb.reduce((sum, color2) => sum + (color2 & 255), 0) / rgb.length);
+              colors[index] = red << 16 | green << 8 | blue;
+              break;
+            }
             case "team":
             case "minecraft:team":
-            case "custom_model_data":
-            case "minecraft:custom_model_data":
               colors[index] = this.rgb(source.default);
               break;
+            case "custom_model_data":
+            case "minecraft:custom_model_data": {
+              const colorIndex = source.index ?? 0;
+              if (!Number.isSafeInteger(colorIndex) || colorIndex < 0) throw new MineRenderError("Item tint custom_model_data index must be a nonnegative integer");
+              const values = this.componentField(components, "custom_model_data", "colors");
+              if (values !== void 0 && !Array.isArray(values)) throw new MineRenderError("Item tint custom_model_data.colors must be an array");
+              colors[index] = this.colorOrDefault(values?.[colorIndex], source.default, true);
+              break;
+            }
             default:
               throw new MineRenderError(`Unsupported item tint source ${source.type}`);
           }
         }));
         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 componentField(components, id, field) {
+        const value = components[`minecraft:${id}`];
+        if (value === void 0) return void 0;
+        if (!value || typeof value !== "object" || Array.isArray(value)) throw new MineRenderError(`Item tint ${id} must be an object`);
+        return value[field];
+      }
+      static colorOrDefault(value, fallback, allowTriple = false) {
+        return value === void 0 ? this.rgb(fallback) : this.componentColor(value, allowTriple);
+      }
+      static componentColor(value, allowTriple = false) {
+        if (typeof value === "number" && Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) return this.rgb(value);
+        if (allowTriple && Array.isArray(value) && value.length === 3 && value.every((channel) => typeof channel === "number" && Number.isFinite(channel))) {
+          return this.rgb(value) & 16777215;
+        }
+        throw new MineRenderError(`Item tint component color must be a packed integer${allowTriple ? " or RGB triple" : ""}`);
+      }
+      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)) & 255);
         return red << 16 | green << 8 | blue;
       }
     };
@@ -5066,7 +5847,7 @@ var init_ItemTints = __esm({
 });
 
 // src/model/scene/ModelObject.ts
-import { BoxGeometry as BoxGeometry5, BufferAttribute as BufferAttribute5, Color as Color9, Euler as Euler7, Matrix4 as Matrix49 } from "three";
+import { BoxGeometry as BoxGeometry5, BufferAttribute as BufferAttribute5, Color as Color9, Euler as Euler8, Matrix4 as Matrix49 } from "three";
 function isModelObject(obj) {
   return obj.isModelObject;
 }
@@ -5095,29 +5876,52 @@ var init_ModelObject = __esm({
         this.originalModel = originalModel;
         this.isModelObject = true;
         this.specialMaterials = /* @__PURE__ */ new Map();
+        this.geometries = /* @__PURE__ */ new Set();
         this.meshesCreated = false;
         this.options = (0, import_ts_deepmerge5.default)({}, _ModelObject.DEFAULT_OPTIONS, options ?? {});
-        if (originalModel.special) this.options.instanceMeshes = false;
+        if (originalModel.special || originalModel.parts) this.options.instanceMeshes = false;
         if (this.options.tints) this.options.tints = { ...this.options.tints };
         this.addEventListener("added", () => this.updateAnimationSubscription());
         this.addEventListener("removed", () => this.updateAnimationSubscription());
       }
       async init() {
+        const parts = this.originalModel.parts;
+        if (parts) {
+          try {
+            for (const part of parts) {
+              const object3 = new _ModelObject(part, { ...this.options, instanceMeshes: false });
+              this.add(object3);
+              await object3.init();
+            }
+            let order = 0;
+            this.iterateAllMeshes((mesh) => {
+              mesh.renderOrder = order++;
+              for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+                material.transparent = true;
+              }
+            });
+          } catch (error) {
+            this.disposeAndRemoveAllChildren();
+            throw error;
+          }
+          this.notifyDirty();
+          return;
+        }
         this.options.tints = await ItemTints.get(this.originalModel, this.options.tints);
         const special = this.originalModel.special;
         if (special) {
-          const parts = await SpecialItems.getParts(special, this.originalModel.key?.root);
+          const parts2 = await SpecialItems.getParts(special, this.originalModel.key?.root, this.originalModel.components);
           const transform = this.options.displayPosition ? DisplayTransforms.getMatrix(this.originalModel.display, this.options.displayPosition) : new Matrix49();
           transform.multiply(new Matrix49().makeTranslation(-8, -8, -8));
           try {
-            for (const part of parts) {
-              const object = new EntityObject(part.model, { flip: false, wireframe: this.options.wireframe });
-              object.matrix.copy(transform).multiply(part.transform);
-              object.matrixWorldNeedsUpdate = true;
-              object.matrixAutoUpdate = false;
-              this.add(object);
-              await object.init();
-              object.iterateAllMeshes((mesh) => {
+            for (const part of parts2) {
+              const object3 = new EntityObject(part.model, { flip: false, wireframe: this.options.wireframe, tints: part.tints });
+              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) {
@@ -5128,7 +5932,10 @@ var init_ModelObject = __esm({
                 mesh.material = material;
               });
               for (const [name, rotation] of Object.entries(part.rotations)) {
-                object.getGroupByName(name)?.rotation.set(...rotation, "ZYX");
+                object3.getGroupByName(name)?.rotation.set(...rotation, "ZYX");
+              }
+              for (const [name, position] of Object.entries(part.positions ?? {})) {
+                object3.getGroupByName(name)?.position.set(...position);
               }
             }
           } catch (error) {
@@ -5161,6 +5968,7 @@ var init_ModelObject = __esm({
           if (this.atlas.model.elements) {
             this.atlas.model.elements?.forEach((el) => {
               const elGeo = this._getBoxGeometryFromElement(el).clone();
+              this.geometries.add(elGeo);
               if (this.options.cullMask) {
                 const indices = Array.from(elGeo.getIndex().array);
                 elGeo.setIndex(indices.filter((_, index) => {
@@ -5171,8 +5979,9 @@ var init_ModelObject = __esm({
                 elGeo.clearGroups();
               }
               if (this.options.uvLockRotation) {
-                UVMapper.lockUvs(elGeo, el.faces, this.atlas, new Euler7(...this.options.uvLockRotation));
+                UVMapper.lockUvs(elGeo, el.faces, this.atlas, new Euler8(...this.options.uvLockRotation));
               }
+              UVMapper.setAtlasUvBounds(elGeo, el.faces, this.atlas);
               if (this.options.tints) {
                 const colors = new Float32Array(elGeo.getAttribute("position").count * 3).fill(1);
                 for (const [faceIndex, faceName] of CUBE_FACES.entries()) {
@@ -5180,9 +5989,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 Color9(tint);
+                  const color2 = new Color9(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 BufferAttribute5(colors, 3));
@@ -5213,10 +6022,14 @@ var init_ModelObject = __esm({
           let combinedGeo;
           if (allGeos.length > 0) {
             combinedGeo = mergeBufferGeometries(allGeos);
+            for (const geometry of allGeos) {
+              this.geometries.delete(geometry);
+            }
           } else {
             combinedGeo = new BoxGeometry5(16, 16, 16);
             if (displayTransform) DisplayTransforms.apply(combinedGeo, displayTransform);
           }
+          this.geometries.add(combinedGeo);
           combinedGeo.computeBoundingBox();
           let mesh;
           if (this.options.instanceMeshes) {
@@ -5238,9 +6051,12 @@ var init_ModelObject = __esm({
       }
       applyTextures() {
         if (this.atlas) {
-          const mat = Materials.createShadedCanvasMaterial(this.atlas.image.canvas, this.atlas.hasTransparency, false);
+          const mat = Materials.createShadedCanvasMaterial(this.atlas.image.canvas, this.atlas.hasTransparency, false, true);
           this.atlasMaterial = mat;
           this.atlasTexture = mat.uniforms?.map?.value ?? mat.map;
+          if (this.options.displayPosition === "gui" /* GUI */ && this.originalModel.gui_light === "front" /* FRONT */ && mat.uniforms?.SHADE) {
+            mat.uniforms.SHADE.value = false;
+          }
           this.iterateAllMeshes((mesh) => {
             if (mesh.geometry.hasAttribute("color")) mat.vertexColors = true;
             mesh.material = mat;
@@ -5249,7 +6065,9 @@ var init_ModelObject = __esm({
         }
       }
       updateAnimationSubscription() {
-        const active = !!this.parent && (!this.isInstanced || this.instanceCounter > 0);
+        let root = this;
+        while (root.parent && isModelObject(root.parent)) root = root.parent;
+        const active = !!root.parent && (!this.isInstanced || this.instanceCounter > 0);
         if (active && this.atlas?.hasAnimation && this.atlasTexture) {
           if (!this.unsubscribeAtlas) {
             this.atlasTexture.needsUpdate = true;
@@ -5265,6 +6083,9 @@ var init_ModelObject = __esm({
           this.unsubscribeAtlas?.();
           this.unsubscribeAtlas = void 0;
         }
+        for (const child of this.children) {
+          if (isModelObject(child)) child.updateAnimationSubscription();
+        }
       }
       nextInstance() {
         const reference = super.nextInstance();
@@ -5284,6 +6105,8 @@ var init_ModelObject = __esm({
         this.atlasMaterial = void 0;
         for (const material of this.specialMaterials.values()) material.dispose();
         this.specialMaterials.clear();
+        for (const geometry of this.geometries) geometry.dispose();
+        this.geometries.clear();
         super.disposeAndRemoveAllChildren();
       }
     };
@@ -5499,9 +6322,9 @@ var init_FluidModelObject = __esm({
           }
         }
         geometry.clearGroups();
-        const color = new Color10(this.options.tints?.[0] ?? (this.kind === "water" ? 4159204 : 16777215));
+        const color2 = new Color10(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 BufferAttribute6(colors, 3));
         geometry.computeBoundingBox();
         geometry.computeBoundingSphere();
@@ -5631,11 +6454,11 @@ var BrowserEnv = class {
   imageSize(data) {
     return probeImageSize(data);
   }
-  openCache(name, version) {
+  openCache(name, version2) {
     return new BrowserCache(localforage.createInstance({
       // IndexedDB schema upgrades retain records; each cache generation needs its own database.
-      name: name + version,
-      version
+      name: name + version2,
+      version: version2
     }));
   }
 };
@@ -5666,6 +6489,7 @@ var Meshes = class _Meshes {
   static createBox(key) {
     return new 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) => {
@@ -5715,6 +6539,7 @@ function shutdown() {
 init_AssetKey();
 init_AssetLoader();
 init_Assets();
+init_BannerPatterns();
 
 // src/assets/BlockEntities.ts
 init_AssetKey();
@@ -5778,6 +6603,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, []));
@@ -5793,8 +6619,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) {
@@ -5940,13 +6766,13 @@ var OBJExporter = class {
    * @param {Object3D} object - The 3D object to export.
    * @return {string} The exported OBJ.
    */
-  parse(object) {
+  parse(object3) {
     let output = "";
     let indexVertex = 0;
     let indexVertexUvs = 0;
     let indexNormals = 0;
     const vertex = new Vector37();
-    const color = new Color4();
+    const color2 = new Color4();
     const normal = new Vector37();
     const uv = new Vector22();
     const face = [];
@@ -6045,9 +6871,9 @@ var OBJExporter = class {
           vertex.applyMatrix4(points.matrixWorld);
           output += "v " + vertex.x + " " + vertex.y + " " + vertex.z;
           if (colors !== void 0) {
-            color.fromBufferAttribute(colors, i);
-            ColorManagement.workingToColorSpace(color, SRGBColorSpace3);
-            output += " " + color.r + " " + color.g + " " + color.b;
+            color2.fromBufferAttribute(colors, i);
+            ColorManagement.workingToColorSpace(color2, SRGBColorSpace3);
+            output += " " + color2.r + " " + color2.g + " " + color2.b;
           }
           output += "\n";
         }
@@ -6059,7 +6885,7 @@ var OBJExporter = class {
       }
       indexVertex += nbVertex;
     }
-    object.traverse(function(child) {
+    object3.traverse(function(child) {
       if (child.isMesh === true) {
         parseMesh(child);
       }
@@ -6093,9 +6919,9 @@ var PLYExporter = class {
    * @param {PLYExporter~Options} options - The export options.
    * @return {?(string|ArrayBuffer)} The exported PLY.
    */
-  parse(object, onDone, options = {}) {
+  parse(object3, onDone, options = {}) {
     function traverseMeshes(cb) {
-      object.traverse(function(child) {
+      object3.traverse(function(child) {
         if (child.isMesh === true || child.isPoints) {
           const mesh = child;
           const geometry = mesh.geometry;
@@ -6128,7 +6954,7 @@ var PLYExporter = class {
     for (const name of customAttributeNames) customTypes[name] = "float";
     let vertexCount = 0;
     let faceCount = 0;
-    object.traverse(function(child) {
+    object3.traverse(function(child) {
       if (child.isMesh === true) {
         const mesh = child;
         const geometry = mesh.geometry;
@@ -6750,8 +7576,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]);
@@ -6944,12 +7770,12 @@ var GLTFWriter = class {
    * @param {THREE.Object3D|THREE.Material|THREE.BufferGeometry|THREE.AnimationClip} object
    * @param {Object} objectDef
    */
-  serializeUserData(object, objectDef) {
-    if (Object.keys(object.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(object.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) {
@@ -6960,7 +7786,7 @@ var GLTFWriter = class {
       }
       if (Object.keys(json).length > 0) objectDef.extras = json;
     } catch (error) {
-      console.warn("THREE.GLTFExporter: userData of '" + object.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);
     }
   }
   /**
@@ -7333,7 +8159,7 @@ var GLTFWriter = class {
    * @param {string} mimeType export format
    * @return {number}     Index of the processed texture in the "images" array
    */
-  processImage(image, format, flipY, mimeType = "image/png") {
+  processImage(image, format2, flipY, mimeType = "image/png") {
     if (image !== null) {
       const writer = this;
       const cache = writer.cache;
@@ -7357,8 +8183,8 @@ var GLTFWriter = class {
         ctx.scale(1, -1);
       }
       if (image.data !== void 0) {
-        if (format !== RGBAFormat2) {
-          console.error("GLTFExporter: Only RGBAFormat is supported.", format);
+        if (format2 !== RGBAFormat2) {
+          console.error("GLTFExporter: Only RGBAFormat is supported.", format2);
         }
         if (image.width > options.maxTextureSize || image.height > options.maxTextureSize) {
           console.warn("GLTFExporter: Image size is bigger than maxTextureSize", image);
@@ -7469,9 +8295,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;
@@ -7886,13 +8712,13 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object
    * @return {?number}
    */
-  processSkin(object) {
+  processSkin(object3) {
     const json = this.json;
     const nodeMap = this.nodeMap;
-    const node = json.nodes[nodeMap.get(object)];
-    const skeleton = object.skeleton;
+    const node = json.nodes[nodeMap.get(object3)];
+    const skeleton = object3.skeleton;
     if (skeleton === void 0) return null;
-    const rootJoint = object.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);
@@ -7900,7 +8726,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(object.bindMatrix).toArray(inverseBindMatrices, i * 16);
+      temporaryBoneInverse.multiply(object3.bindMatrix).toArray(inverseBindMatrices, i * 16);
     }
     if (json.skins === void 0) json.skins = [];
     json.skins.push({
@@ -7916,19 +8742,19 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object Object3D to processNodeAsync
    * @return {Promise<number>} Index of the node in the nodes list
    */
-  async processNodeAsync(object) {
+  async processNodeAsync(object3) {
     const json = this.json;
     const options = this.options;
     const nodeMap = this.nodeMap;
     if (!json.nodes) json.nodes = [];
-    if (object.pivot !== null) {
-      return await this._processNodeWithPivotAsync(object);
+    if (object3.pivot !== null) {
+      return await this._processNodeWithPivotAsync(object3);
     }
     const nodeDef = {};
     if (options.trs) {
-      const rotation = object.quaternion.toArray();
-      const position = object.position.toArray();
-      const scale = object.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;
       }
@@ -7939,28 +8765,28 @@ var GLTFWriter = class {
         nodeDef.scale = scale;
       }
     } else {
-      if (object.matrixAutoUpdate) {
-        object.updateMatrix();
+      if (object3.matrixAutoUpdate) {
+        object3.updateMatrix();
       }
-      if (isIdentityMatrix(object.matrix) === false) {
-        nodeDef.matrix = object.matrix.elements;
+      if (isIdentityMatrix(object3.matrix) === false) {
+        nodeDef.matrix = object3.matrix.elements;
       }
     }
-    if (object.name !== "") nodeDef.name = String(object.name);
-    this.serializeUserData(object, nodeDef);
-    if (object.isMesh || object.isLine || object.isPoints) {
-      const meshIndex = await this.processMeshAsync(object);
+    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 (object.isCamera) {
-      nodeDef.camera = this.processCamera(object);
+    } else if (object3.isCamera) {
+      nodeDef.camera = this.processCamera(object3);
     }
-    if (object.isSkinnedMesh) this.skins.push(object);
+    if (object3.isSkinnedMesh) this.skins.push(object3);
     const nodeIndex = json.nodes.push(nodeDef) - 1;
-    nodeMap.set(object, nodeIndex);
-    if (object.children.length > 0) {
+    nodeMap.set(object3, nodeIndex);
+    if (object3.children.length > 0) {
       const children = [];
-      for (let i = 0, l = object.children.length; i < l; i++) {
-        const child = object.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);
@@ -7969,7 +8795,7 @@ var GLTFWriter = class {
       if (children.length > 0) nodeDef.children = children;
     }
     await this._invokeAllAsync(function(ext) {
-      ext.writeNode && ext.writeNode(object, nodeDef);
+      ext.writeNode && ext.writeNode(object3, nodeDef);
     });
     return nodeIndex;
   }
@@ -7978,19 +8804,19 @@ var GLTFWriter = class {
    * @param {THREE.Object3D} object Object3D with pivot
    * @return {Promise<number>} Index of the container node
    */
-  async _processNodeWithPivotAsync(object) {
+  async _processNodeWithPivotAsync(object3) {
     const json = this.json;
     const options = this.options;
     const nodeMap = this.nodeMap;
-    const pivot = object.pivot;
+    const pivot = object3.pivot;
     const containerDef = {};
-    const rotation = object.quaternion.toArray();
+    const rotation = object3.quaternion.toArray();
     const position = [
-      object.position.x + pivot.x,
-      object.position.y + pivot.y,
-      object.position.z + pivot.z
+      object3.position.x + pivot.x,
+      object3.position.y + pivot.y,
+      object3.position.z + pivot.z
     ];
-    const scale = object.scale.toArray();
+    const scale = object3.scale.toArray();
     if (!equalArray(rotation, [0, 0, 0, 1])) {
       containerDef.rotation = rotation;
     }
@@ -8001,28 +8827,28 @@ var GLTFWriter = class {
       containerDef.scale = scale;
     }
     containerDef.extras = { pivot: pivot.toArray() };
-    if (object.name !== "") containerDef.name = String(object.name);
-    this.serializeUserData(object, containerDef);
+    if (object3.name !== "") containerDef.name = String(object3.name);
+    this.serializeUserData(object3, containerDef);
     const containerIndex = json.nodes.push(containerDef) - 1;
-    nodeMap.set(object, 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 (object.isMesh || object.isLine || object.isPoints) {
-      const meshIndex = await this.processMeshAsync(object);
+    if (object3.isMesh || object3.isLine || object3.isPoints) {
+      const meshIndex = await this.processMeshAsync(object3);
       if (meshIndex !== null) childDef.mesh = meshIndex;
-    } else if (object.isCamera) {
-      childDef.camera = this.processCamera(object);
+    } else if (object3.isCamera) {
+      childDef.camera = this.processCamera(object3);
     }
-    if (object.isSkinnedMesh) this.skins.push(object);
+    if (object3.isSkinnedMesh) this.skins.push(object3);
     const childIndex = json.nodes.push(childDef) - 1;
     const containerChildren = [childIndex];
-    if (object.children.length > 0) {
+    if (object3.children.length > 0) {
       const grandchildren = [];
-      for (let i = 0, l = object.children.length; i < l; i++) {
-        const child = object.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);
@@ -8032,7 +8858,7 @@ var GLTFWriter = class {
     }
     containerDef.children = containerChildren;
     await this._invokeAllAsync(function(ext) {
-      ext.writeNode && ext.writeNode(object, containerDef);
+      ext.writeNode && ext.writeNode(object3, containerDef);
     });
     return containerIndex;
   }
@@ -8475,10 +9301,10 @@ var GLTFMeshGpuInstancing = class {
     this.writer = writer;
     this.name = "EXT_mesh_gpu_instancing";
   }
-  writeNode(object, nodeDef) {
-    if (!object.isInstancedMesh) return;
+  writeNode(object3, nodeDef) {
+    if (!object3.isInstancedMesh) return;
     const writer = this.writer;
-    const mesh = object;
+    const mesh = object3;
     const translationAttr = new Float32Array(mesh.count * 3);
     const rotationAttr = new Float32Array(mesh.count * 4);
     const scaleAttr = new Float32Array(mesh.count * 3);
@@ -8668,8 +9494,8 @@ var SceneExporter = class {
     }
   }
 };
-function localMatrix(object) {
-  return object.matrixAutoUpdate ? new Matrix47().compose(object.position, object.quaternion, object.scale) : object.matrix.clone();
+function localMatrix(object3) {
+  return object3.matrixAutoUpdate ? new Matrix47().compose(object3.position, object3.quaternion, object3.scale) : object3.matrix.clone();
 }
 function createSnapshot(root, gltf, bakeColors = false) {
   const scene = new Scene3();
@@ -8773,24 +9599,24 @@ function createSnapshot(root, gltf, bakeColors = false) {
       scene.add(copy);
     }
   };
-  const visit = (object, parentWorld) => {
-    if (!object.visible) return;
-    const world = parentWorld.clone().multiply(localMatrix(object));
-    const mesh = object;
+  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 Matrix47();
           instanced.getMatrixAt(i, matrix);
-          const color = instanced.instanceColor ? new Color7().fromBufferAttribute(instanced.instanceColor, i) : void 0;
-          addMesh(mesh, world.clone().multiply(matrix), color);
+          const color2 = instanced.instanceColor ? new Color7().fromBufferAttribute(instanced.instanceColor, i) : void 0;
+          addMesh(mesh, world.clone().multiply(matrix), color2);
         }
       } else {
         addMesh(mesh, world);
       }
     }
-    for (const child of object.children) visit(child, world);
+    for (const child of object3.children) visit(child, world);
   };
   try {
     const ancestors = [];
@@ -8863,16 +9689,17 @@ function copyDataTexture(source) {
 
 // src/gui/GuiHelper.ts
 init_AssetKey();
+init_ModelTextures();
 
 // src/gui/GuiText.ts
 import { BufferGeometry as BufferGeometry2, Color as Color8, Float32BufferAttribute as Float32BufferAttribute4 } from "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;
@@ -8926,7 +9753,7 @@ function createGuiTextGeometry(layout, shadow = true) {
         batch = { image: glyph?.image, positions: [], uvs: [], colors: [], indices: [] };
         batches.push(batch);
       }
-      const color = new Color8(isShadow ? (style.color & 16579836) >> 2 : style.color);
+      const color2 = new Color8(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;
@@ -8954,7 +9781,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]) {
@@ -8972,7 +9799,128 @@ function createGuiTextGeometry(layout, shadow = true) {
 }
 
 // src/gui/GuiHelper.ts
+var GUI_CONTAINER_LAYOUTS = {
+  generic_54: {
+    texture: "minecraft:gui/container/generic_54",
+    crop: [0, 0, 176, 222],
+    slotOrigin: [8, 18],
+    slotOffset: [18, 18],
+    rowSize: 9,
+    slotCount: 54
+  },
+  crafting_table: {
+    texture: "minecraft:gui/container/crafting_table",
+    crop: [0, 0, 176, 166],
+    slotOrigin: [30, 17],
+    slotOffset: [18, 18],
+    rowSize: 3,
+    slotCount: 9,
+    resultPosition: [124, 35]
+  }
+};
 var GuiHelper = class {
+  /**
+   * Creates a 182×5 boss bar using the active resource pack. Finite progress is clamped to 0–1.
+   * The fill crops the source image; explicit crops do not apply `.mcmeta` sprite scaling.
+   */
+  static async bossBar(options = {}) {
+    const { color: color2 = "pink", progress = 1, position = [0, 0] } = options;
+    this.validatePosition(position);
+    if (!["pink", "blue", "red", "green", "yellow", "purple", "white"].includes(color2)) {
+      throw new Error(`Unsupported boss bar color: ${color2}`);
+    }
+    if (!Number.isFinite(progress)) throw new Error("Boss bar progress must be finite");
+    const value = Math.max(0, Math.min(1, progress));
+    const width = value > 0 ? Math.floor(value * 181) + 1 : 0;
+    const texture = `minecraft:gui/sprites/boss_bar/${color2}`;
+    const layers = [{
+      name: "boss-bar-background",
+      texture: `${texture}_background`,
+      position: [...position],
+      size: [182, 5]
+    }];
+    if (width > 0) {
+      layers.push({
+        ...await this.cropTexture(`${texture}_progress`, [0, 0, width, 5], [182, 5], position),
+        name: "boss-bar-progress"
+      });
+    }
+    return layers;
+  }
+  /**
+   * Creates a 192×192 book page with optional arrows and supplied text. Buttons are hidden by default.
+   * Callers choose the page content and button states; this helper does not paginate or handle clicks.
+   */
+  static async book(options = {}) {
+    const {
+      position = [0, 0],
+      previous = "hidden",
+      next = "hidden",
+      text: text2,
+      color: color2 = 0,
+      shadow = false,
+      maxWidth = 114,
+      lineHeight = 9,
+      ...style
+    } = options;
+    this.validatePosition(position);
+    for (const state of [previous, next]) {
+      if (!["hidden", "normal", "hover"].includes(state)) throw new Error(`Unsupported book button state: ${state}`);
+    }
+    const layers = [{
+      ...await this.cropTexture("minecraft:gui/book", [0, 0, 192, 192], [256, 256], position),
+      name: "book-background"
+    }];
+    for (const [name, direction, state, x] of [
+      ["previous", "backward", previous, 43],
+      ["next", "forward", next, 116]
+    ]) {
+      if (state === "hidden") continue;
+      layers.push({
+        name: `book-${name}`,
+        texture: `minecraft:gui/sprites/widget/page_${direction}${state === "hover" ? "_highlighted" : ""}`,
+        position: [position[0] + x, position[1] + 157],
+        size: [23, 13]
+      });
+    }
+    if (text2 !== void 0) {
+      layers.push({
+        name: "book-text",
+        text: text2,
+        position: [position[0] + 36, position[1] + 30],
+        color: color2,
+        shadow,
+        maxWidth,
+        lineHeight,
+        ...style
+      });
+    }
+    return layers;
+  }
+  /** Creates a container background. Use {@link GUI_CONTAINER_LAYOUTS} with {@link inventorySlot} to place its items. */
+  static async container(type, position = [0, 0]) {
+    this.validatePosition(position);
+    if (type !== "generic_54" && type !== "crafting_table") throw new Error(`Unsupported GUI container: ${type}`);
+    const layout = GUI_CONTAINER_LAYOUTS[type];
+    return [{ ...await this.cropTexture(layout.texture, layout.crop, [256, 256], position), name: "background" }];
+  }
+  static validatePosition(position) {
+    if (!Array.isArray(position) || position.length !== 2 || !position.every(Number.isFinite)) {
+      throw new Error("GUI position must contain two finite coordinates");
+    }
+  }
+  static async cropTexture(texture, crop, referenceSize, position) {
+    const image = await ModelTextures.preload(AssetKey.parse("textures", texture));
+    if (!image) throw new Error(`Could not load GUI texture ${texture}`);
+    const [x, y, width, height] = crop;
+    const scaleX = image.width / referenceSize[0], scaleY = image.height / referenceSize[1];
+    return {
+      texture,
+      crop: [x * scaleX, y * scaleY, width * scaleX, height * scaleY],
+      position: [...position],
+      size: [width, height]
+    };
+  }
   /** Sizes a tooltip around supplied text; the first entry is its title. */
   static async tooltip(lines, options = {}) {
     if (!lines.length) return [];
@@ -8988,20 +9936,28 @@ 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]];
   }
   /** Creates crafting-table layers for ingredients and the result; stack counts are not drawn. */
   static recipe(recipe, options = {}) {
+    const layout = GUI_CONTAINER_LAYOUTS.crafting_table;
     const layers = [
-      { name: "background", texture: "minecraft:gui/container/crafting_table", crop: [0, 0, 176, 166] }
+      { name: "background", texture: layout.texture, crop: [...layout.crop] }
     ];
     const itemKey = (ingredient) => {
       const item = typeof ingredient === "string" && !ingredient.startsWith("#") ? ingredient : typeof ingredient === "object" && "item" in ingredient ? ingredient.item : options.resolveIngredient?.(ingredient);
@@ -9016,17 +9972,17 @@ var GuiHelper = class {
       layers.push({
         name: `ingredient-${slot}`,
         item: itemKey(ingredient),
-        position: this.inventorySlot(slot, [30, 17], [18, 18], 3)
+        position: this.inventorySlot(slot, layout.slotOrigin, layout.slotOffset, layout.rowSize)
       });
     };
     switch (recipe.type) {
       case "minecraft:crafting_shaped":
       case "crafting_shaped": {
-        const pattern = recipe.pattern;
-        if (!pattern.length || pattern.length > 3 || !pattern[0].length || pattern[0].length > 3 || pattern.some((row) => row.length !== pattern[0].length)) {
+        const pattern2 = recipe.pattern;
+        if (!pattern2.length || pattern2.length > 3 || !pattern2[0].length || pattern2[0].length > 3 || pattern2.some((row) => row.length !== pattern2[0].length)) {
           throw new Error("Crafting patterns must be rectangular, with 1\u20133 rows and columns");
         }
-        const cells = pattern.flatMap((row, y) => row.split("").map((symbol, x) => ({ symbol, x, y }))).filter((cell) => cell.symbol !== " ");
+        const cells = pattern2.flatMap((row, y) => row.split("").map((symbol, x) => ({ symbol, x, y }))).filter((cell) => cell.symbol !== " ");
         if (!cells.length) throw new Error("Crafting patterns must contain an ingredient");
         const minX = Math.min(...cells.map((cell) => cell.x)), maxX = Math.max(...cells.map((cell) => cell.x));
         const minY = Math.min(...cells.map((cell) => cell.y)), maxY = Math.max(...cells.map((cell) => cell.y));
@@ -9051,7 +10007,7 @@ var GuiHelper = class {
     layers.push({
       name: "result",
       item: itemKey("id" in recipe.result ? recipe.result.id : recipe.result.item),
-      position: [124, 35]
+      position: [...layout.resultPosition]
     });
     return layers;
   }
@@ -9145,7 +10101,6 @@ init_SceneObject();
 init_Materials();
 init_ModelObject();
 init_DisplayPosition();
-init_GuiLight();
 import { Box2, Box3 as Box32, DoubleSide as DoubleSide3, Group, Matrix4 as Matrix410, Mesh as Mesh6, MeshBasicMaterial as MeshBasicMaterial5, Vector2 as Vector23 } from "three";
 var GuiObject = class extends SceneObject {
   constructor(textureLayers, options) {
@@ -9214,12 +10169,16 @@ var GuiObject = class extends SceneObject {
             mesh2.geometry.computeBoundingBox();
             bounds.union(mesh2.geometry.boundingBox.clone().applyMatrix4(new Matrix410().multiplyMatrices(inverse, mesh2.matrixWorld)));
           });
-          item.position.z = depth - bounds.min.z;
-          depth += bounds.max.z - bounds.min.z + 0.01;
+          item.position.z = depth;
+          if (!bounds.isEmpty()) {
+            item.position.z -= bounds.min.z;
+            depth += bounds.max.z - bounds.min.z;
+            this.bounds.expandByPoint(new Vector23(bounds.min.x, -bounds.max.y));
+            this.bounds.expandByPoint(new Vector23(bounds.max.x, -bounds.min.y));
+          }
+          depth += 0.01;
           this.bounds.expandByPoint(new Vector23(x, y));
           this.bounds.expandByPoint(new Vector23(x + width2, y + height2));
-          this.bounds.expandByPoint(new Vector23(bounds.min.x, -bounds.max.y));
-          this.bounds.expandByPoint(new Vector23(bounds.max.x, -bounds.min.y));
           continue;
         }
         const key = typeof layer.texture === "string" ? AssetKey.parse("textures", layer.texture) : layer.texture;
@@ -9248,7 +10207,7 @@ var GuiObject = class extends SceneObject {
   }
   async createItem(layer, index) {
     const key = typeof layer.item === "string" ? AssetKey.parse("models", layer.item) : layer.item;
-    const model = await Models.getMerged(key);
+    const model = await Models.getMerged(key, { ...layer.context, displayContext: "gui" /* GUI */ });
     if (!model) throw new Error(`Could not load GUI item ${key.toNamespacedString()}`);
     const item = new ModelObject(model, {
       displayPosition: "gui" /* GUI */,
@@ -9259,15 +10218,13 @@ var GuiObject = class extends SceneObject {
     item.name = `group:${layer.name ?? index}`;
     this.add(item);
     await item.init();
-    item.iterateAllMeshes((mesh) => {
-      if (!model.special) this.geometries.add(mesh.geometry);
+    const meshes = [];
+    item.iterateAllMeshes((mesh) => meshes.push(mesh));
+    meshes.forEach((mesh, partIndex) => {
       mesh.name = `mesh:${layer.name ?? index}`;
-      mesh.renderOrder = index;
+      mesh.renderOrder = index + partIndex / (meshes.length + 1) * 0.5;
       for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
         material.transparent = true;
-        if (model.gui_light === "front" /* FRONT */ && material.uniforms?.SHADE) {
-          material.uniforms.SHADE.value = false;
-        }
       }
     });
     return item;
@@ -9438,29 +10395,29 @@ var SceneInspector = class {
     this.objectControlsContainer.innerHTML = "";
     this.addControls(targetObject, targetIntersection, instance);
   }
-  addControls(object, intersection, instance) {
+  addControls(object3, intersection, instance) {
     const container = document.createElement("div");
     container.append(this.separator("Select Parent/Child"));
-    if (object.parent) {
-      container.append(this.buttonControl("Select Parent " + object.parent.constructor.name + " " + object.parent.name, "P", () => {
-        this.selectObject(object.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 (object.children.length > 0) {
+    if (object3.children.length > 0) {
       let i = 1;
-      for (let child of object.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 && (object === instance.instanceable || object === 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", object.visible, (v) => object.visible = v));
+      container.append(this.toggleControl("Visibility", "V", object3.visible, (v) => object3.visible = v));
     }
     container.append(this.separator("Mesh"));
-    this.addObjectControls(object, intersection, container, selectedInstance);
+    this.addObjectControls(object3, intersection, container, selectedInstance);
     container.append(this.separator());
     this.objectControlsContainer.append(container);
   }
@@ -9651,6 +10608,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;
@@ -9675,6 +10633,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);
@@ -9682,6 +10641,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);
@@ -9698,6 +10658,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];
@@ -9731,7 +10692,7 @@ init_SpecialItems();
 init_BlockStates();
 init_MineRenderError();
 init_util();
-import { Euler as Euler8 } from "three";
+import { Euler as Euler9 } from "three";
 function matchesCondition(condition, state) {
   return Object.entries(condition).every(([key, value]) => {
     if (Array.isArray(value)) {
@@ -9743,6 +10704,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 = {};
@@ -9762,9 +10724,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) {
@@ -9788,6 +10752,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");
@@ -9805,8 +10770,9 @@ 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 Euler8();
+    const rotation = new Euler9();
     if (typeof variant.x !== "undefined") {
       rotation.x = toRadians(clampRotationDegrees(variant.x));
     }
@@ -9867,29 +10833,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 };
   }
 };
 
@@ -9901,7 +10867,7 @@ var import_ts_deepmerge6 = __toESM(require_dist());
 init_MineRenderError();
 init_InstanceReference();
 init_AssetKey();
-import { Euler as Euler9, Matrix4 as Matrix411, Quaternion as Quaternion5, Vector3 as Vector312 } from "three";
+import { Euler as Euler10, Matrix4 as Matrix411, Quaternion as Quaternion5, Vector3 as Vector312 } from "three";
 init_ModelCulling();
 init_FluidGeometry();
 init_Entities();
@@ -10026,8 +10992,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
       return false;
     }
     return this._models.some((model) => {
-      const object = isInstanceReference(model) ? model.instanceable : model;
-      return object.isOpaqueFullCube && this.getModelCullMask(model, 63) === 63;
+      const object3 = isInstanceReference(model) ? model.instanceable : model;
+      return object3.isOpaqueFullCube && this.getModelCullMask(model, 63) === 63;
     });
   }
   getModelMatrix(model) {
@@ -10036,14 +11002,14 @@ var _BlockObject = class _BlockObject extends SceneObject {
     return model.matrix.clone();
   }
   getModelCullMask(model, worldMask) {
-    const object = isInstanceReference(model) ? model.instanceable : model;
-    if (object.options.displayPosition) return 0;
+    const object3 = isInstanceReference(model) ? model.instanceable : model;
+    if (object3.options.displayPosition) return 0;
     const position = new Vector312();
     const rotation = new Quaternion5();
     const scale = new Vector312();
     this.getModelMatrix(model).decompose(position, rotation, scale);
     if (position.distanceToSquared(this.position) > 1e-10 || scale.distanceToSquared(new Vector312(1, 1, 1)) > 1e-10) return 0;
-    return ModelCulling.toLocalMask(worldMask, new Euler9().setFromQuaternion(rotation));
+    return ModelCulling.toLocalMask(worldMask, new Euler10().setFromQuaternion(rotation));
   }
   async setCullMask(worldMask) {
     worldMask &= 63;
@@ -10054,14 +11020,14 @@ var _BlockObject = class _BlockObject extends SceneObject {
           replacements.push(model);
           continue;
         }
-        const object = isInstanceReference(model) ? model.instanceable : model;
+        const object3 = isInstanceReference(model) ? model.instanceable : model;
         const cullMask = this.getModelCullMask(model, worldMask);
-        if (cullMask === (object.options.cullMask ?? 0)) {
+        if (cullMask === (object3.options.cullMask ?? 0)) {
           replacements.push(model);
           continue;
         }
         const matrix = this.getModelMatrix(model);
-        const replacement = await this.scene.addModel(object.originalModel, { ...object.options, cullMask });
+        const replacement = await this.scene.addModel(object3.originalModel, { ...object3.options, cullMask });
         replacements.push(replacement);
         if (isInstanceReference(replacement)) {
           replacement.setMatrix(matrix);
@@ -10069,8 +11035,8 @@ var _BlockObject = class _BlockObject extends SceneObject {
           replacement.matrix.copy(matrix);
           replacement.matrixWorldNeedsUpdate = true;
           matrix.decompose(replacement.position, replacement.quaternion, replacement.scale);
-          replacement.matrixAutoUpdate = object.matrixAutoUpdate;
-          replacement.visible = object.visible;
+          replacement.matrixAutoUpdate = object3.matrixAutoUpdate;
+          replacement.visible = object3.visible;
         }
       }
     } catch (error) {
@@ -10086,6 +11052,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;
   }
@@ -10185,6 +11152,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 = {};
@@ -11992,9 +12960,9 @@ var SchematicParser = class {
    * Parses a legacy schematic using custom mappings before the bundled defaults.
    * Keys are `id:metadata`; values are block states such as `minecraft:oak_log[axis=x]`.
    */
-  static async parse(nbt, customMappings = {}) {
+  static async parse(nbt, customMappings = {}, options = {}) {
     const tags = nbt.value;
-    if (tags.Materials?.type !== "string" || tags.Materials.value !== "Alpha") {
+    if (!options.lenient && (tags.Materials?.type !== "string" || tags.Materials.value !== "Alpha")) {
       throw new MineRenderError("Schematic Materials must be Alpha");
     }
     const size = ["Width", "Height", "Length"].map((name) => {
@@ -12035,8 +13003,16 @@ var SchematicParser = class {
       const id = high << 8 | ids.value[index] & 255;
       const metadata = data.value[index] & 255;
       const key = `${id}:${metadata}`;
-      const mapped = customMappings[key] ?? mapping[key];
-      if (!mapped) throw new MineRenderError(`Unsupported legacy block ${id}:${metadata} at schematic index ${index}`);
+      let mapped = customMappings[key] ?? mapping[key];
+      if (!mapped && options.lenient) {
+        mapped = customMappings[`${id}:0`] ?? mapping[`${id}:0`];
+      }
+      if (!mapped) {
+        if (options.lenient) {
+          continue;
+        }
+        throw new MineRenderError(`Unsupported legacy block ${id}:${metadata} at schematic index ${index}`);
+      }
       const [type, state] = mapped.split("[");
       if (type === "minecraft:air") continue;
       const properties = {};
@@ -12080,6 +13056,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;
@@ -12914,6 +13895,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;
@@ -13087,6 +14069,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;
@@ -13194,59 +14184,61 @@ var _MineRenderScene = class _MineRenderScene extends Scene4 {
     this.options = (0, import_ts_deepmerge8.default)({}, _MineRenderScene.DEFAULT_OPTIONS, options ?? {});
   }
   add(...objects) {
-    for (const object of objects) {
+    for (const object3 of objects) {
       this.dirty = true;
       try {
-        super.add(object);
+        super.add(object3);
       } finally {
-        if (object?.isObject3D && object !== this) {
-          this.updateObjectRegistration(object, object.parent === this);
+        if (object3?.isObject3D && object3 !== this) {
+          this.updateObjectRegistration(object3, object3.parent === this);
         }
       }
     }
     return this;
   }
   remove(...objects) {
-    for (const object of objects) {
-      if (!this.children.includes(object)) continue;
+    for (const object3 of objects) {
+      if (!this.children.includes(object3)) continue;
       this.dirty = true;
-      this.updateObjectRegistration(object, false);
+      this.updateObjectRegistration(object3, false);
       try {
-        super.remove(object);
+        super.remove(object3);
       } finally {
-        this.updateObjectRegistration(object, object.parent === this);
+        this.updateObjectRegistration(object3, object3.parent === this);
       }
     }
     return this;
   }
-  updateObjectRegistration(object, attached) {
-    if (this.observedObjects.has(object) === attached) return;
-    const observable = object;
+  updateObjectRegistration(object3, attached) {
+    if (this.observedObjects.has(object3) === attached) return;
+    const observable = object3;
     if (attached) {
-      this.observedObjects.add(object);
+      this.observedObjects.add(object3);
       observable.addEventListener("change", this.onObjectChange);
     } else {
-      this.observedObjects.delete(object);
+      this.observedObjects.delete(object3);
       observable.removeEventListener("change", this.onObjectChange);
     }
     const change = attached ? 1 : -1;
     this.stats.objectCount += change;
-    if (isSceneObject(object)) {
+    if (isSceneObject(object3)) {
       this.stats.sceneObjectCount += change;
     }
   }
-  async initAndAdd(...object) {
+  /** Initializes each object before attaching it to the scene. */
+  async initAndAdd(...object3) {
     this.dirty = true;
-    for (let obj of object) {
+    for (let obj of object3) {
       await obj.init();
     }
-    return this.add(...object);
+    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 (isModelObject(obj)) obj.options.tints = await ItemTints.get(obj.originalModel, obj.options.tints);
+    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}`;
@@ -13270,13 +14262,32 @@ var _MineRenderScene = class _MineRenderScene extends Scene4 {
       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);
@@ -13288,9 +14299,14 @@ var _MineRenderScene = class _MineRenderScene extends Scene4 {
     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;
@@ -13329,11 +14345,11 @@ var _changeEvent = { type: "change" };
 var _startEvent = { type: "start" };
 var _endEvent = { type: "end" };
 var OrbitControls = class extends EventDispatcher {
-  constructor(object, 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 = object;
+    this.object = object3;
     this.domElement = domElement;
     this.domElement.style.touchAction = "none";
     this.enabled = true;
@@ -13390,7 +14406,7 @@ var OrbitControls = class extends EventDispatcher {
     };
     this.update = function() {
       const offset = new Vector313();
-      const quat = new Quaternion6().setFromUnitVectors(object.up, new Vector313(0, 1, 0));
+      const quat = new Quaternion6().setFromUnitVectors(object3.up, new Vector313(0, 1, 0));
       const quatInverse = quat.clone().invert();
       const lastPosition = new Vector313();
       const lastQuaternion = new Quaternion6();
@@ -13955,8 +14971,8 @@ var OrbitControls = class extends EventDispatcher {
   }
 };
 var MapControls = class extends OrbitControls {
-  constructor(object, domElement) {
-    super(object, domElement);
+  constructor(object3, domElement) {
+    super(object3, domElement);
     this.screenSpacePanning = false;
     this.mouseButtons.LEFT = MOUSE.PAN;
     this.mouseButtons.RIGHT = MOUSE.ROTATE;
@@ -14115,6 +15131,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;
@@ -14142,6 +15159,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)) {
@@ -14180,12 +15198,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;
@@ -14294,12 +15314,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);
   }
@@ -14377,16 +15400,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
+init_AssetKey();
+init_AssetLoader();
+init_BlockStates();
+init_Entities();
+init_Models();
+init_DisplayPosition();
+import { Group as Group2 } from "three";
+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);
   }
@@ -14398,6 +15649,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) {
@@ -14408,12 +15660,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);
   }
@@ -14542,6 +15796,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 Group2();
+    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 Group2();
+    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();
@@ -14568,16 +16011,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;
@@ -14642,15 +16088,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");
@@ -14855,6 +16309,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);
@@ -14883,16 +16338,16 @@ 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 object = 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 object.init();
-        const geometry = object.children[0].geometry;
+        await object3.init();
+        const geometry = object3.children[0].geometry;
         geometry.applyMatrix4(new Matrix412().makeRotationFromEuler(rotation));
-        object.clear();
+        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;
@@ -14908,6 +16363,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();
@@ -14958,6 +16414,13 @@ var MineRenderWorld = class {
     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 {
@@ -15009,13 +16472,7 @@ var MineRenderWorld = class {
   async placeChunk(chunk, executor) {
     const changes = /* @__PURE__ */ new Map();
     try {
-      const previous = [...this._chunks.entries()].filter(([, section]) => section.x === chunk.x && section.z === chunk.z);
-      for (const [key, section] of previous) {
-        this._chunks.delete(key);
-        await section.clear(async (positions) => {
-          for (const pos of positions) changes.set(pos.toArray().join(","), pos);
-        });
-      }
+      await this.clearChunkColumn(chunk.x, chunk.z, changes);
       for (const section of chunk.sections) {
         const blocks = [];
         for (let index = 0; index < 4096; index++) {
@@ -15035,6 +16492,32 @@ var MineRenderWorld = class {
       await this.updateCulling([...changes.values()]);
     }
   }
+  /**
+   * Removes all sections at integer chunk-column coordinates, then refreshes neighboring faces and fluids.
+   * Coordinates match AnvilChunk.x/z, not block positions. Missing columns are ignored.
+   */
+  async unloadChunkColumn(x, z) {
+    if (!Number.isInteger(x) || !Number.isInteger(z)) {
+      throw new RangeError("Chunk column coordinates must be integers");
+    }
+    await this.culling;
+    const changes = /* @__PURE__ */ new Map();
+    try {
+      await this.clearChunkColumn(x, z, changes);
+    } finally {
+      await this.updateCulling([...changes.values()]);
+    }
+  }
+  async clearChunkColumn(x, z, changes) {
+    const previous = [...this._chunks.entries()].filter(([, section]) => section.x === x && section.z === z);
+    for (const [key, section] of previous) {
+      this._chunks.delete(key);
+      await section.clear(async (positions) => {
+        for (const pos of positions) changes.set(pos.toArray().join(","), pos);
+      });
+    }
+  }
+  /** Removes all chunks and releases their block placements and section meshes. */
   async clear() {
     await this.culling;
     const chunks = [...this._chunks.values()];
@@ -15080,10 +16563,10 @@ var MineRenderWorld = class {
               await block.object.updateFluid((x, y, z) => {
                 const neighbor = pos.clone().add(new Vector316(x, y, z));
                 const section = this.getChunkAt(neighbor);
-                const object = section?.isBlockVisibleAt(neighbor) ? section.getBlockAt(neighbor)?.object : void 0;
+                const object3 = section?.isBlockVisibleAt(neighbor) ? section.getBlockAt(neighbor)?.object : void 0;
                 return {
-                  fluid: object?.fluidKind,
-                  level: object?.fluidLevel,
+                  fluid: object3?.fluidKind,
+                  level: object3?.fluidLevel,
                   solid: section?.isOccludingAt(neighbor) ?? false
                 };
               });
@@ -15120,9 +16603,11 @@ 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 Vector316(
       pos.x * 16,
@@ -15130,6 +16615,7 @@ var MineRenderWorld = class {
       pos.z * 16
     );
   }
+  /** Converts scene units to block coordinates without rounding to an integer block. */
   static sceneToWorldPosition(pos) {
     return new Vector316(
       pos.x / 16,
@@ -15156,12 +16642,13 @@ init_Model();
 // src/world/SectionMesh.ts
 init_CanvasCompat();
 init_Materials();
-import { BufferGeometry as BufferGeometry8, Float32BufferAttribute as Float32BufferAttribute8, Group as Group2, Mesh as Mesh9 } from "three";
-var SectionMesh = class _SectionMesh extends Group2 {
+import { BufferGeometry as BufferGeometry8, Float32BufferAttribute as Float32BufferAttribute8, Group as Group3, Mesh as Mesh9 } from "three";
+var SectionMesh = class _SectionMesh extends Group3 {
   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)));
@@ -15203,14 +16690,17 @@ var SectionMesh = class _SectionMesh extends Group2 {
       for (const { atlas, x, y } of page.placements) {
         context.drawImage(atlas.image.canvas, x, y);
       }
-      const positions = [], normals = [], uvs = [], colors = [], indices = [];
+      const positions = [], normals = [], uvs = [], uvBounds = [], colors = [], indices = [];
       for (const { index, template, cullMask } of page.entries) {
         const position = template.geometry.getAttribute("position");
         const normal = template.geometry.getAttribute("normal");
         const uv = template.geometry.getAttribute("uv");
-        const color = template.geometry.getAttribute("color");
+        const bounds = template.geometry.getAttribute("uvBounds");
+        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;
+        const mapV = (v) => 1 - (placement.y + (1 - v) * template.atlas.image.height) / page.height;
         const offsetX = index % 16 * 16;
         const offsetY = Math.floor(index / 256) * 16;
         const offsetZ = Math.floor(index / 16) % 16 * 16;
@@ -15221,11 +16711,14 @@ var SectionMesh = class _SectionMesh extends Group2 {
             const vertex = face * 4 + corner;
             positions.push(position.getX(vertex) + offsetX, position.getY(vertex) + offsetY, position.getZ(vertex) + offsetZ);
             normals.push(normal.getX(vertex), normal.getY(vertex), normal.getZ(vertex));
-            uvs.push(
-              (placement.x + uv.getX(vertex) * template.atlas.image.width) / page.width,
-              1 - (placement.y + (1 - uv.getY(vertex)) * template.atlas.image.height) / page.height
+            uvs.push(mapU(uv.getX(vertex)), mapV(uv.getY(vertex)));
+            uvBounds.push(
+              mapU(bounds?.getX(vertex) ?? 0),
+              mapV(bounds?.getY(vertex) ?? 0),
+              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);
         }
@@ -15234,11 +16727,12 @@ var SectionMesh = class _SectionMesh extends Group2 {
       geometry.setAttribute("position", new Float32BufferAttribute8(positions, 3));
       geometry.setAttribute("normal", new Float32BufferAttribute8(normals, 3));
       geometry.setAttribute("uv", new Float32BufferAttribute8(uvs, 2));
+      geometry.setAttribute("uvBounds", new Float32BufferAttribute8(uvBounds, 4));
       geometry.setAttribute("color", new Float32BufferAttribute8(colors, 3));
       geometry.setIndex(indices);
       geometry.computeBoundingBox();
       geometry.computeBoundingSphere();
-      const material = Materials.createShadedCanvasMaterial(canvas, false);
+      const material = Materials.createShadedCanvasMaterial(canvas, false, false, true);
       material.vertexColors = true;
       const texture = material.uniforms?.map?.value ?? material.map;
       const mesh = new Mesh9(geometry, material);
@@ -15299,7 +16793,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") {
@@ -15312,7 +16806,7 @@ var Chunk = class _Chunk {
     this.renderedBlocks.get(index)?.object?.removeFromScene();
     if (this.sectionBlocks.delete(index)) this.meshDirty = true;
     this.renderedBlocks.delete(index);
-    let object;
+    let object3;
     try {
       if (!readBlock) return void 0;
       const stored = readBlock();
@@ -15327,27 +16821,28 @@ var Chunk = class _Chunk {
         this.sectionBlocks.set(index, { index, template, cullMask: 0 });
         this.meshDirty = true;
       } else {
-        object = await this.scene.addBlock(blockState, {
+        object3 = await this.scene.addBlock(blockState, {
           mergeMeshes: true,
           instanceMeshes: true,
           maxInstanceCount: 2e3,
           initialState: stored.properties
         });
-        object.setPosition(MineRenderWorld.worldToScenePosition(worldPos));
+        object3.setPosition(MineRenderWorld.worldToScenePosition(worldPos));
       }
       const info = { get block() {
         return readBlock();
-      }, object };
+      }, object: object3 };
       this.renderedBlocks.set(index, info);
       return info;
     } catch (error) {
       this.data.set(index, void 0);
-      object?.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);
@@ -15401,6 +16896,7 @@ 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 Vector317(index % 16, Math.floor(index / 256), Math.floor(index / 16) % 16)
@@ -15421,6 +16917,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");
@@ -15455,6 +16952,7 @@ export {
   Axis,
   BUILTIN_ENTITY,
   BUILTIN_GENERATED,
+  BannerPatterns,
   BasicAssetKey,
   BatchedExecutor,
   BlockEntities,
@@ -15479,6 +16977,7 @@ export {
   DEFAULT_ROOT,
   DEFAULT_UV,
   DISPLAY_POSITIONS,
+  DYE_COLORS,
   DefaultBlockStates,
   DisplayPosition,
   DisplayTransforms,
@@ -15489,6 +16988,7 @@ export {
   Env,
   FluidModelObject,
   Fonts,
+  GUI_CONTAINER_LAYOUTS,
   Geometries,
   GuiHelper,
   GuiLight,
@@ -15515,11 +17015,14 @@ export {
   Models,
   NBTHelper,
   OrbitControls,
+  PackFormats,
+  PackMetadata,
   PersistentCache,
   Renderer,
   RequestError,
   Requests,
   SKIN_PARTS,
+  SceneDocumentLoader,
   SceneExporter,
   SceneInspector,
   SceneObject,
@@ -15595,6 +17098,7 @@ export {
   mergeBufferAttributes,
   mergeBufferGeometries,
   mergeVertices,
+  parseSceneDocument,
   prefix,
   probeImageSize,
   registerBrowserEnv,