interface item-stack {
    use data-components.{data-component};
    use enchantments.{enchantment};
    use text.{text-component};

    /// Represents an enchantment and its level.
    record enchantment-value {
        enchantment: enchantment,
        level: u32,
    }

    /// Represents a data component and its serialized value.
    record data-component-value {
        component: data-component,
        /// The serialized value of the component.
        value: list<u8>,
    }

    /// Represents one entry in an NBT compound tag.
    record nbt-entry {
        key: string,
        value: u32,
    }

    /// Represents a Minecraft NBT tag tree.
    record nbt-tree {
        root: u32,
        tags: list<nbt-tag>,
    }

    /// Represents a Minecraft NBT tag.
    variant nbt-tag {
        byte(s8),
        short(s16),
        int(s32),
        long(s64),
        float(f32),
        double(f64),
        byte-array(list<s8>),
        string-tag(string),
        list-tag(list<u32>),
        compound(list<nbt-entry>),
        int-array(list<s32>),
        long-array(list<s64>),
    }

    resource item-stack {
        constructor(registry-key: string, count: u8);

        /// Returns the unique registry key of the item (e.g., "minecraft:diamond").
        get-registry-key: func() -> string;
        
        /// Returns the number of items in the stack.
        get-count: func() -> u8;
        /// Sets the number of items in the stack.
        set-count: func(count: u8);

        /// Returns the maximum number of items that can be in this stack.
        get-max-count: func() -> u8;

        /// Returns all enchantments on this item stack.
        get-enchantments: func() -> list<enchantment-value>;
        /// Adds an enchantment to this item stack.
        add-enchantment: func(enchantment: enchantment, level: u32);
        /// Removes an enchantment from this item stack.
        remove-enchantment: func(enchantment: enchantment);

        /// Returns the lore of this item stack.
        get-lore: func() -> list<text-component>;
        /// Sets the lore of this item stack.
        set-lore: func(lore: list<text-component>);
        /// Adds a line to the lore of this item stack.
        add-lore: func(line: text-component);

        /// Returns the custom name of this item stack, if set.
        get-custom-name: func() -> option<text-component>;
        /// Sets the custom name of this item stack.
        set-custom-name: func(name: option<text-component>);

        /// Sets a namespaced custom data value on this item stack.
        set-custom-data: func(namespace: string, key: string, value: nbt-tree);
        /// Returns a namespaced custom data value from this item stack, if set.
        get-custom-data: func(namespace: string, key: string) -> option<nbt-tree>;
        /// Removes a namespaced custom data value from this item stack.
        remove-custom-data: func(namespace: string, key: string);
        /// Returns whether this item stack has a namespaced custom data value.
        has-custom-data: func(namespace: string, key: string) -> bool;

        /// Returns all data components on this item stack.
        get-components: func() -> list<data-component-value>;
        /// Sets a data component on this item stack.
        set-component: func(component: data-component, value: list<u8>);
        /// Removes a data component from this item stack.
        remove-component: func(component: data-component);
    }
}