minerender 2.1.0-alpha.78 → 2.1.0-alpha.79

package/dist/node/index.d.mts

@@ -524,6 +524,8 @@ interface ItemModel extends Model {
     gui_light?: GuiLight;
     special?: SpecialItemRenderer;
     tints?: ItemTintSource[];
+    /** Ordered composite children, each with its own textures, display pose, and tint sources. */
+    parts?: ItemModel[];
 }
 /** An sRGB packed `0xRRGGBB` value or an RGB triple with components from 0 to 1. */
 type ItemTintColor = number | TripleArray;
@@ -1187,26 +1189,46 @@ declare class Fonts {
     private static bitmap;
 }
 
+/** Caller-supplied item-preview state passed to {@link Models.getMerged}. */
+interface ItemModelContext {
+    /** Context used by display-context selectors, overriding `properties`. Defaults to GUI. */
+    displayContext?: DisplayPosition | "none";
+    /** Explicit property overrides. Nodes with the same ID share one override, regardless of their parameters. */
+    properties?: Record<string, boolean | string | number>;
+    /** Supplied component JSON by ID. Item-registry defaults are not added; component selectors compare structural JSON values. */
+    components?: Record<string, unknown>;
+    /** Stack count, as a nonnegative integer. Defaults to 1; absent `max_stack_size` also defaults to 1. */
+    count?: number;
+    /** Item-model keys by reference-node ID, such as `minecraft:bundle/selected_item`. Unset references draw nothing. */
+    itemReferences?: Record<string, AssetKey>;
+}
 /** Loads and caches Java block/item models, including inherited geometry and textures. */
 declare class Models {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
     /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
     static getItemList(): Promise<string[]>;
-    static loadAndMerge(key: AssetKey): Promise<Maybe<Model>>;
+    static loadAndMerge(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     private static getItemModel;
-    private static defaultItemModel;
+    private static contextIdentifier;
+    private static snapshotContext;
+    private static contextKey;
+    private static snapshotJson;
+    private static propertyValue;
+    private static selectItemModel;
     /** Loads one model file without resolving its parents. Returns `undefined` when the file is missing. */
     static getRaw(key: AssetKey): Promise<Maybe<Model>>;
     /**
      * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
-     * Item keys use GUI context, false conditions, and zero numeric properties.
+     * 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 getMerged(key: AssetKey): Promise<Maybe<Model>>;
+    static getMerged(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     /** Alias for {@link getMerged}. */
-    static get(key: AssetKey): Promise<Maybe<Model>>;
+    static get(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
     static clearCache(): Promise<void>;
 }
@@ -1363,6 +1385,7 @@ declare class ModelObject extends SceneObject {
     private atlasTexture?;
     private unsubscribeAtlas?;
     private readonly specialMaterials;
+    private readonly geometries;
     blockParent: Maybe<BlockObject>;
     private meshesCreated;
     constructor(originalModel: Model, options?: Partial<ModelObjectOptions>);
@@ -3213,4 +3236,4 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelContext, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };

package/dist/node/index.d.ts

@@ -524,6 +524,8 @@ interface ItemModel extends Model {
     gui_light?: GuiLight;
     special?: SpecialItemRenderer;
     tints?: ItemTintSource[];
+    /** Ordered composite children, each with its own textures, display pose, and tint sources. */
+    parts?: ItemModel[];
 }
 /** An sRGB packed `0xRRGGBB` value or an RGB triple with components from 0 to 1. */
 type ItemTintColor = number | TripleArray;
@@ -1187,26 +1189,46 @@ declare class Fonts {
     private static bitmap;
 }
 
+/** Caller-supplied item-preview state passed to {@link Models.getMerged}. */
+interface ItemModelContext {
+    /** Context used by display-context selectors, overriding `properties`. Defaults to GUI. */
+    displayContext?: DisplayPosition | "none";
+    /** Explicit property overrides. Nodes with the same ID share one override, regardless of their parameters. */
+    properties?: Record<string, boolean | string | number>;
+    /** Supplied component JSON by ID. Item-registry defaults are not added; component selectors compare structural JSON values. */
+    components?: Record<string, unknown>;
+    /** Stack count, as a nonnegative integer. Defaults to 1; absent `max_stack_size` also defaults to 1. */
+    count?: number;
+    /** Item-model keys by reference-node ID, such as `minecraft:bundle/selected_item`. Unset references draw nothing. */
+    itemReferences?: Record<string, AssetKey>;
+}
 /** Loads and caches Java block/item models, including inherited geometry and textures. */
 declare class Models {
     private static _persistentCache;
     private static get PERSISTENT_CACHE();
     /** Lists item filenames from the asset source's `_list.json`, with a legacy model-directory fallback. */
     static getItemList(): Promise<string[]>;
-    static loadAndMerge(key: AssetKey): Promise<Maybe<Model>>;
+    static loadAndMerge(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     private static getItemModel;
-    private static defaultItemModel;
+    private static contextIdentifier;
+    private static snapshotContext;
+    private static contextKey;
+    private static snapshotJson;
+    private static propertyValue;
+    private static selectItemModel;
     /** Loads one model file without resolving its parents. Returns `undefined` when the file is missing. */
     static getRaw(key: AssetKey): Promise<Maybe<Model>>;
     /**
      * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
-     * Item keys use GUI context, false conditions, and zero numeric properties.
+     * 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 getMerged(key: AssetKey): Promise<Maybe<Model>>;
+    static getMerged(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     /** Alias for {@link getMerged}. */
-    static get(key: AssetKey): Promise<Maybe<Model>>;
+    static get(key: AssetKey, context?: ItemModelContext): Promise<Maybe<Model>>;
     /** Clears persisted models. Use {@link Caching.clear} to also discard in-memory assets. */
     static clearCache(): Promise<void>;
 }
@@ -1363,6 +1385,7 @@ declare class ModelObject extends SceneObject {
     private atlasTexture?;
     private unsubscribeAtlas?;
     private readonly specialMaterials;
+    private readonly geometries;
     blockParent: Maybe<BlockObject>;
     private meshesCreated;
     constructor(originalModel: Model, options?: Partial<ModelObjectOptions>);
@@ -3213,4 +3236,4 @@ declare class NodeCache extends PersistentCache<LocalStorage> {
     forEach<T>(callback: (v: T, k: string) => void): Promise<void>;
 }
 
-export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };
+export { AXES, type AnimationFrame, type AnimationMeta, type AnimatorFunction, type AnvilChunk, AnvilParser, type AnvilRegion, ArchiveAssetSource, type ArchiveAssetSourceOptions, type ArchiveEntry, type ArchiveProxy, AssetKey, AssetLoadError, AssetLoader, AssetParser, AssetSource, type AssetType, Assets, Axis, BUILTIN_ENTITY, BUILTIN_GENERATED, BasicAssetKey, type BasicMinecraftAsset, BatchedExecutor, type BedrockBone, type BedrockCube, type BedrockEntityDescription, type BedrockEntityFile, type BedrockGeometry, type BedrockGeometryFile, type BitmapFont, type BitmapGlyph, type Block, BlockEntities, type BlockEntityEntry, type BlockEntityIndex, type BlockEntityPart, type BlockEntityRotation, type BlockFluidState, type BlockInfo, type BlockModel, type BlockModelTextures, BlockObject, type BlockObjectOptions, type BlockState, type BlockStateMultipart, type BlockStateProperties, type BlockStateProperty, type BlockStatePropertyDefaults, type BlockStatePropertyValue, BlockStateResolver, type BlockStateVariant, type BlockStateVariants, BlockStates, BlockTints, type BoxGeometryKey, BrowserArchiveProxy, CUBE_FACES, CUBE_FACE_OFFSETS, type CacheKey, Caching, type CameraOptions, CanvasImage, type CapeLayout, Chunk, ChunkData, Colormaps, type CompatCanvas, type CompatImage, type ComposerOptions, type ControlsOptions, CubeFace, CubeFaceIndex, DEFAULT_ELEMENTS, DEFAULT_NAMESPACE, DEFAULT_ROOT, DEFAULT_UV, DISPLAY_POSITIONS, type DebugOptions, type DeepPartial, DefaultBlockStates, DisplayPosition, DisplayTransforms, type Disposable, type DoubleArray, ENTITY_ANIMATION_CHANNELS, type ElementFace, type ElementRotation, Entities, type EntityAnimation, type EntityAnimationBone, type EntityAnimationChannel, type EntityAnimationFile, type EntityAnimationKeyframe, type EntityAnimationOptions, EntityAnimationPlayer, type EntityAnimationPose, type EntityLayer, type EntityModel, type EntityModelCube, type EntityModelFile, type EntityModelLayer, type EntityModelOptions, type EntityModelPart, type EntityModelPass, EntityObject, type EntityObjectOptions, type EntityRenderMode, type EntityTransformOp, Env, type EnvProvider, type ExtractableImageData, type FluidKind, FluidModelObject, type FluidSample, type FluidSampler, Fonts, type FrameCallback, type FromTo, GUI_CONTAINER_LAYOUTS, Geometries, type GuiBookButtonState, type GuiBookOptions, type GuiBossBarColor, type GuiBossBarOptions, type GuiContainerType, GuiHelper, type GuiItemLayer, type GuiLayer, GuiLight, GuiObject, type GuiObjectOptions, type GuiRecipe, type GuiRecipeIngredient, type GuiRecipeOptions, type GuiSpriteScaling, type GuiText, type GuiTextLayer, type GuiTextLayout, type GuiTextOptions, type GuiTextRun, type GuiTextStyle, type GuiTextureLayer, type GuiTooltipOptions, HostedAssetSource, type IModelTextures, ITEM_GENERATED, type ImageInfo, ImageLoader, type ImageSizeInfo, InstanceManager, InstanceReference, type Instanceable, type ItemModel, type ItemModelContext, type ItemModelTextures, type ItemTintColor, type ItemTintSource, ItemTints, type ListAsset, type LoadedSceneDocument, type LoadedSceneObject, MapControls, type MaterialKey, Materials, type Maybe, type MeshKey, Meshes, MineRenderError, MineRenderScene, type MineRenderSceneOptions, MineRenderWorld, type MineRenderWorldOptions, type MinecraftAsset, MinecraftCubeTexture, MinecraftFaceUV, type MinecraftTextureMeta, type Model, ModelCulling, type ModelDisplay, type ModelElement, type ModelFaces, ModelGenerator, ModelMerger, ModelObject, type ModelObjectOptions, ModelTextures, Models, type MultiBlockBlock, type MultiBlockEntity, type MultiBlockStructure, type MultipartCondition, type NBTAsset, NBTHelper, NodeCache, NodeEnv, OrbitControls, type PackFormat, PackFormats, PackMetadata, PersistentCache, type PositionedGuiGlyph, type QuadArray, type RawImageKey, type RenderOptions, Renderer, type RendererFrame, type RendererOptions, type RequestConfig, RequestError, type RequestResponse, Requests, type ResolvedBlockEntity, type ResponseParser, SKIN_PARTS, type SceneBlockDefinition, type SceneDocument, SceneDocumentLoader, type SceneEntityDefinition, SceneExporter, type SceneGLTFExportOptions, type SceneGuiDefinition, type SceneGuiLayer, SceneInspector, type SceneModelDefinition, SceneObject, type SceneObjectDefinition, type SceneObjectDefinitionBase, type SceneObjectOptions, type SceneSkinDefinition, type SceneSkinPosePart, SceneStats, SceneStatsDisplay, SchematicParser, type SchematicParserOptions, SectionMesh, type SectionMeshEntry, type SectionMeshTemplate, SectionModels, type Serializable, type SkinGeometries, SkinImage, SkinObject, type SkinObjectOptions, SkinPart, type SkinTexture, type SkinTextureCoordinates, SkinTextures, Skins, type SpecialItemPart, type SpecialItemRenderer, SpecialItems, type StructureNBT, StructureParser, type TextureAsset, TextureAtlas, type TextureKey, TextureLoader, Textures, Ticker, type TickerFunction, TintColors, type Transformable, type TripleArray, UVMapper, WrappedImage, addBox3WireframeToObject, addWireframeToMesh, addWireframeToObject, applyElementRotation, applyGenericRotation, axisToVec3, base64decode, base64encode, capeTextureSizes, captureException, changeEvent, clampRotationDegrees, classicSkinGeometries, classicSkinTextureCoordinates, computeMorphedAttributes, createCanvas, createFluidGeometry, createGuiTextGeometry, createGuiTextureGeometry, createImage, entityAnimationTime, estimateBytesUsed, getBlockFluidState, getFluidKind, interleaveAttributes, isAssetKey, isBasicAssetKey, isBlockObject, isDisposable, isDoubleArray, isEntityObject, isGuiObject, isInstanceManager, isInstanceReference, isInstanceable, isInstancedMesh, isMesh, isMineRenderScene, isModelObject, isObject3D, isOrthographicCamera, isPerspectiveCamera, isQuadArray, isSceneObject, isTransformable, isTripleArray, isVector3, layoutGuiText, md5, mergeBufferAttributes, mergeBufferGeometries, mergeVertices, parseSceneDocument, prefix, registerNodeEnv, sampleEntityAnimation, sampleEntityKeyframes, sampleFluid, serializeBoxGeometryKey, serializeImageKey, serializeMaterialKey, serializeMeshKey, serializeTextureKey, sha1, sha256, sha512, shutdown, sleep, slimSkinGeometries, slimSkinTextureCoordinates, timingEnd, timingStart, toDegrees, toRadians, toTrianglesDrawMode, trimCanvas };

package/dist/node/index.js

@@ -1528,6 +1528,8 @@ var init_ModelMerger = __esm({
     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]) {
@@ -1588,6 +1590,7 @@ var init_Models = __esm({
     init_PersistentCache();
     init_AssetKey();
     init_AssetParsers();
+    init_DisplayPosition();
     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
@@ -1602,34 +1605,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-v3:${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 } };
+          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, ...selected.special && { special: selected.special }, ...selected.tints && { tints: selected.tints } };
+          };
+          return load(this.selectItemModel(result.asset.model, key, preview));
         });
-        return model ? { ...model, key: Object.assign(new AssetKey("", ""), model.key) } : void 0;
+        const restore = (model2) => ({
+          ...model2,
+          key: Object.assign(new AssetKey("", ""), model2.key),
+          ...model2.parts && { parts: model2.parts.map(restore) }
+        });
+        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-v3:${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;
@@ -1650,17 +1793,29 @@ 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()}`);
@@ -1687,25 +1842,28 @@ var init_Models = __esm({
       }
       /**
        * Loads a model and resolves its parent chain. Returns `undefined` when the model is missing.
-       * Item keys use GUI context, false conditions, and zero numeric properties.
+       * 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) {
+      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);
         });
       }
       /** Alias for {@link getMerged}. */
-      static async get(key) {
-        return this.getMerged(key);
+      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() {
@@ -5576,9 +5734,10 @@ 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());
@@ -5587,14 +5746,36 @@ var init_ModelObject = __esm({
         this.DEFAULT_OPTIONS = (0, import_ts_deepmerge5.default)({}, SceneObject.DEFAULT_OPTIONS, {});
       }
       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);
           const transform = this.options.displayPosition ? DisplayTransforms.getMatrix(this.originalModel.display, this.options.displayPosition) : new import_three25.Matrix4();
           transform.multiply(new import_three25.Matrix4().makeTranslation(-8, -8, -8));
           try {
-            for (const part of parts) {
+            for (const part of parts2) {
               const object3 = new EntityObject(part.model, { flip: false, wireframe: this.options.wireframe });
               object3.matrix.copy(transform).multiply(part.transform);
               object3.matrixWorldNeedsUpdate = true;
@@ -5645,6 +5826,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) => {
@@ -5698,10 +5880,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 import_three25.BoxGeometry(16, 16, 16);
             if (displayTransform) DisplayTransforms.apply(combinedGeo, displayTransform);
           }
+          this.geometries.add(combinedGeo);
           combinedGeo.computeBoundingBox();
           let mesh;
           if (this.options.instanceMeshes) {
@@ -5726,6 +5912,9 @@ var init_ModelObject = __esm({
           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;
@@ -5734,7 +5923,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;
@@ -5750,6 +5941,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();
@@ -5769,6 +5963,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();
       }
     };
@@ -9868,7 +10064,6 @@ init_SceneObject();
 init_Materials();
 init_ModelObject();
 init_DisplayPosition();
-init_GuiLight();
 var GuiObject = class extends SceneObject {
   constructor(textureLayers, options) {
     super({ ...options, instanceMeshes: false, mergeMeshes: false });
@@ -9936,12 +10131,16 @@ var GuiObject = class extends SceneObject {
             mesh2.geometry.computeBoundingBox();
             bounds.union(mesh2.geometry.boundingBox.clone().applyMatrix4(new import_three26.Matrix4().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 import_three26.Vector2(bounds.min.x, -bounds.max.y));
+            this.bounds.expandByPoint(new import_three26.Vector2(bounds.max.x, -bounds.min.y));
+          }
+          depth += 0.01;
           this.bounds.expandByPoint(new import_three26.Vector2(x, y));
           this.bounds.expandByPoint(new import_three26.Vector2(x + width2, y + height2));
-          this.bounds.expandByPoint(new import_three26.Vector2(bounds.min.x, -bounds.max.y));
-          this.bounds.expandByPoint(new import_three26.Vector2(bounds.max.x, -bounds.min.y));
           continue;
         }
         const key = typeof layer.texture === "string" ? AssetKey.parse("textures", layer.texture) : layer.texture;
@@ -9981,15 +10180,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;