sapdon 3.5.3 → 3.6.0

package/prod/core/index.d.ts

@@ -458,6 +458,20 @@ declare class BasicBlock {
      * @param {Map|Object} component 组件 Map 或普通对象
      */
     addPermutation(condition: string, component: Map<any, any> | Object): this;
+    /**
+     * 提交前的自检（由 `registry.submit()` → `runValidators()` 在序列化之前调用一次）。
+     *
+     * ⚠️ 不能在 `registerBlock` 里做这类检查：`BlockAPI.createXxx()` 是「先注册、后 addComponent」，
+     *    注册那一刻用户还没挂组件，检查必然看不到容器组件。真守卫就是这里。
+     *
+     * 检查两件事，都**只 warn、不改产物**：
+     *
+     * 1. 方块 components 里出现 `minecraft:inventory` —— 它是**实体**组件，不是方块组件，
+     *    引擎必然拒绝（`not present in the Schema`）。容器请走实体路线。
+     * 2. `minecraft:block_entity.container.slot_count` 超出官方文档的 `[1, 54]`
+     *    （`BlockComponent.setBlockEntity({container})` 已经抛错；这里兜住"手写组件对象 / 裸 Map"的写法）。
+     */
+    validate(): void;
     /**
      * 将方块对象转换为 JSON 格式
      * @returns {Object} JSON 格式的方块对象
@@ -497,8 +511,7 @@ declare class Block extends BasicBlock {
     #private;
 }
 
-/** @template T */
-declare class BlockComponent<T> {
+declare class BlockComponent {
     /**
      * @param {string} texture - 纹理短名
      * @param {Object|string} [options] - 可选参数对象，或旧版 tint_method 字符串
@@ -714,10 +727,88 @@ declare class BlockComponent<T> {
     static setSelectionBoxCustom(origin: any[], size: any[]): Map<string, any>;
     /**
      * 设置方块实体（Block Entity，实验性功能，需开启 Upcoming Creator Features）。
-     * @param {Boolean} [dynamic_properties=false] - 是否启用动态属性存储。
+     *
+     * 两种调用方式（都支持，互不干扰）：
+     * ```js
+     * BlockComponent.setBlockEntity()                    // → { dynamic_properties: false }（历史产物，逐字节不变）
+     * BlockComponent.setBlockEntity(true)                // → { dynamic_properties: true }（历史产物，逐字节不变）
+     * BlockComponent.setBlockEntity(true, { container: { slot_count: 27 } })
+     * BlockComponent.setBlockEntity({ container: 54 })   // 只给容器时也可以省掉第一个参数
+     * ```
+     *
+     * ⚠️ **`container` 是「方块容器」的规范写法**（官方文档
+     * <https://learn.microsoft.com/en-us/minecraft/creator/reference/content/blockreference/examples/blockcomponents/minecraftblock_block_entity>
+     * ：`container.slot_count`，`>= 1` 且 `<= 54`，超限**抛错**），
+     * 但**当前引擎版本仍会拒绝该成员**。**要现在就能用的容器，请走实体路线**：
+     * `BlockAPI.createTileBlock(identifier, category, textures_arr, { inventory_size })`。
+     * 引擎拒绝的原文与版本见 `doc/dev/known-pitfalls.md`。
+     *
+     * ⚠️ `combineComponents` 是「**后者覆盖前者**」：要同时给 `dynamic_properties` 与 `container`，
+     *    请像上面那样**一次调用写完**；把两个 `setBlockEntity(...)` 合并会让先出现的那个被整份丢掉
+     *    （框架不在 `combineComponents` 里做隐式深合并 —— 那会把"覆盖"这条既有语义改掉）。
+     *
+     * @param {Boolean|Object} [dynamic_properties=false] 是否启用动态属性存储；也可以直接传 `options` 对象
+     *   （此时读 `options.dynamic_properties`，缺省 false）。
+     * @param {Object} [options] 可选参数。
+     * @param {Object|number} [options.container] 方块容器：`{ slot_count }`（`inventory_size` 亦可作别名），
+     *   或直接给槽位数。必须是 `[1, 54]` 的整数，超限抛错。
      * @returns {Map<string, any>} - 新的组件集合。
      */
-    static setBlockEntity(dynamic_properties?: boolean): Map<string, any>;
+    static setBlockEntity(dynamic_properties?: boolean | Object, options?: {
+        container?: number | Object | undefined;
+    }): Map<string, any>;
+    /**
+     * 设置方块容器 —— ⚠️ **已废弃（deprecated），且当前引擎版本拒绝该组件**。
+     *
+     * ## 为什么废弃
+     * 本方法产出的是**方块** `components` 里的 `minecraft:inventory`。但 `minecraft:inventory`
+     * 是**实体**组件（官方文档在 Entity Components 下：
+     * <https://learn.microsoft.com/en-us/minecraft/creator/reference/content/entityreference/examples/entitycomponents/minecraftcomponent_inventory>），
+     * **不是**方块组件（Block Components 列表里没有它）。于是真机引擎直接拒绝：
+     * ```
+     * -> components -> minecraft:inventory: this component was found in the input,
+     *    but is not present in the Schema
+     * ```
+     * ⇒ 把实体组件写在方块里，**在任何版本上都不成立**（不是"版本太旧"的问题）。
+     * 也就是说：**框架此前产不出任何可用的方块容器**，这条 API 是误导性的。
+     *
+     * ## 现在该怎么做
+     * - **要能用的容器 → 实体路线**（当前引擎版本下**唯一可用**）：
+     *   `BlockAPI.createTileBlock(identifier, category, textures_arr, { inventory_size, container_type, can_be_siphoned_from })`
+     *   —— 方块带承载实体、实体的行为文件里挂 `minecraft:inventory`。
+     *   已在用的 `TileBlock` 也可以直接改 `tile.entity.behavior.addComponent(EntityComponent.setInventoryProperties({...}))`。
+     * - **要规范的方块容器 JSON → `BlockComponent.setBlockEntity(true, { container: { slot_count } })`**
+     *   （`slot_count` 官方文档限制 `[1,54]`）。它会生成正确的 `minecraft:block_entity.container`，
+     *   但**当前引擎版本同样会拒** —— 等引擎支持后即可直接用。
+     *
+     * ## 为什么保留签名（而不是删掉 / 改成别的产物）
+     * 1. 已有项目调用它时，产物里的键、字段**一个字节都不变** —— 不会出现"升个框架版本构建就报错"，
+     *    也不会因为改成 `block_entity.container` 而与用户自己写的 `setBlockEntity(...)` 抢同一个 JSON 键
+     *    （`combineComponents` 是后者覆盖前者，改键会让容器信息在某些写法下**被静默吞掉**）。
+     * 2. 真正的错误（把实体组件当方块组件用）由**构建期 warn** 明确指出，并给出两条新路线。
+     * 3. `inventory_size` 超过 54 的写法在这里仍可表达（实体组件文档**没有**上限）。
+     *
+     * @deprecated 改用实体路线（`createTileBlock` 的 `inventory_size`），或
+     *   `BlockComponent.setBlockEntity(true, { container: { slot_count } })` 产出规范写法。
+     * @param {Object} options - 容器参数。
+     * @param {number} options.inventory_size - 槽位数（正整数，必填；实体组件文档未给上限）。
+     * @param {boolean} [options.private] - 是否仅所有者可访问。
+     * @param {string} [options.container_type] - 容器音效/行为类型。官方文档列出的取值：
+     *   `horse` / `minecart_chest` / `chest_boat` / `minecart_hopper` / `inventory` / `container` / `hopper`
+     *   （此处不做白名单，避免把未文档化但可用的值写死掉）。
+     * @param {boolean} [options.can_be_siphoned_from] - 能否用漏斗抽取。
+     * @param {number} [options.additional_slots_per_strength] - 每级强度的额外槽位（非负整数）。
+     * @param {boolean} [options.restrict_to_owner] - 是否限制为所有者可打开。
+     * @returns {Map<string, any>} - 组件集合（仅 `minecraft:inventory`）。
+     */
+    static setInventory(options?: {
+        inventory_size: number;
+        private?: boolean | undefined;
+        container_type?: string | undefined;
+        can_be_siphoned_from?: boolean | undefined;
+        additional_slots_per_strength?: number | undefined;
+        restrict_to_owner?: boolean | undefined;
+    }): Map<string, any>;
     /**
      * 设置方块的活塞移动行为。
      * @param {String} movement_type - 移动类型: "immovable" | "popped" | "push" | "push_pull"。
@@ -1305,10 +1396,39 @@ declare class Entity {
 declare class TileBlock {
     /**
      * 带实体的方块类
+     *
+     * 容器走**实体**路线：`minecraft:inventory` 是**实体**组件，挂在 `${identifier}_entity` 的
+     * 行为文件上。这是当前引擎版本下**唯一可用**的方块容器方案（方块侧的
+     * `minecraft:block_entity.container` 成员会被引擎拒：
+     * `-> minecraft:block_entity -> container: … is not present in the Schema`）。
+     *
      * @param {*} identifier
      * @param {*} category
      * @param {*} textures_arr
      * @param {*} options
+     * @param {boolean} [options.hide_in_command=false] 是否在命令中隐藏（透传给 `BasicBlock`）。
+     * @param {string} [options.group] 创造菜单分组（透传给 `BasicBlock` → `menu_category.group`）。
+     *   ⚠️ 与 `createBasicBlock` 取值一致：**不传 = undefined**（产物里 `menu_category` 只有
+     *   `category` 与 `is_hidden_in_commands`）。分组名是**本地化键**，项目须在
+     *   `RP/texts/*.lang` 里定义，否则显示裸键名。
+     * @param {string} [options.format_version] 方块 JSON 的 `format_version`（默认 `1.26.30`）。
+     * @param {string} [options.entity_texture] 客户端实体的贴图**资源路径**
+     *   （如 `"textures/blocks/entity/normal"`，省略扩展名）。
+     *   默认 = `textures_arr[0]`（**历史行为，逐字节不变**）。
+     *   ⚠️ `textures_arr[0]` 在**方块**侧是 terrain_texture.json 的**键**、在**实体**侧却必须是
+     *   资源路径 —— 两者不是一回事。只给短名的项目（如 `"machineblock_0"`）必须传本参数，
+     *   否则客户端实体会报 `Missing referenced asset`。
+     * @param {number} [options.inventory_size=27] 实体容器槽位数（正整数）。
+     *   ⚠️ 官方文档（<https://learn.microsoft.com/en-us/minecraft/creator/reference/content/entityreference/examples/entitycomponents/minecraftcomponent_inventory>）
+     *   只写 "Number of slots the container has"、**未给上限** —— 别照搬方块路线 `[1,54]` 的限制。
+     * @param {string} [options.container_type="minecart_chest"] 容器音效/行为类型。官方文档列出的取值：
+     *   `horse` / `minecart_chest` / `chest_boat` / `minecart_hopper` / `inventory` / `container` / `hopper`
+     *   （此处不做白名单，避免把未文档化但可用的值写死掉）。
+     * @param {boolean} [options.can_be_siphoned_from=true] 能否用漏斗抽取。
+     *   ⚠️ **没有**「延迟 despawn」这类入口，而且**不要**去加：
+     *   往 `item_despawn` 组的 `minecraft:transformation` 上加 `delay` 会让同组的
+     *   `minecraft:instant_despawn` 先把实体删掉 ⇒ **整容器一个都不掉**（真机教训，
+     *   见 `doc/dev/known-pitfalls.md` §4.15）。
      */
     constructor(identifier: any, category: any, textures_arr: any, options?: any);
     block: BasicBlock;
@@ -1941,7 +2061,7 @@ declare class EntityComponent {
     static setInventoryProperties(options: {
         additionalSlotsPerStrength?: number | undefined;
         canBeSiphonedFrom?: boolean | undefined;
-        containerType?: "minecart_chest" | "horse" | "chest_boat" | undefined;
+        containerType?: "horse" | "chest_boat" | "minecart_chest" | undefined;
         inventorySize?: number | undefined;
         isPrivate?: boolean | undefined;
         restrictToOwner?: boolean | undefined;
@@ -2276,6 +2396,7 @@ declare namespace BlockAPI {
     function createBasicBlock(identifier: string, category: string, textures_arr: any[], options?: {
         group: string;
         hide_in_command: boolean;
+        format_version?: string | undefined;
     }): BasicBlock;
     function createBlock(identifier: string, category: string, variantDatas: any[], options?: {
         group: string;
@@ -2283,22 +2404,36 @@ declare namespace BlockAPI {
         ambient_occlusion: boolean;
         face_dimming: boolean;
         render_method: string;
+        format_version?: string | undefined;
     }): Block;
     function createRotatableBlock(identifier: string, category: string, textures_arr: any[], options?: {
         group: string;
         hide_in_command: boolean;
         rotationType: string;
         yRotationOffset: number;
+        format_version?: string | undefined;
     }): RotatableBlock;
     function createGeometryBlock(identifier: any, category: any, geometry: any, material_instances: any, options?: {}): GeometryBlock;
+    function createTileBlock(identifier: string, category: string, textures_arr: any[], options?: {
+        group?: string | undefined;
+        hide_in_command?: boolean | undefined;
+        format_version?: string | undefined;
+        entity_texture?: string | undefined;
+        inventory_size?: number | undefined;
+        container_type?: string | undefined;
+        can_be_siphoned_from?: boolean | undefined;
+    }): TileBlock;
     function createOreBlock(identifier: any, category: any, textures_arr: any, options?: {}): OreBlock;
-    function createHeadBlock(identifier: string, category: string, texture: any, options?: {
+    function createHeadBlock(identifier: string, category: string, texture: string, options?: {
         group: string;
         hide_in_command: boolean;
         ambient_occlusion: boolean;
         face_dimming: boolean;
         render_method: string;
-    }): CropBlock;
+        tick_interval?: any[] | undefined;
+        custom_components?: any[] | undefined;
+        format_version?: string | undefined;
+    }): HeadBlock;
     function createGlassBlock(identifier: any, category: any, texture: any, options?: {}): GlassBlock;
     function createFenceBlock(identifier: any, category: any, textures_arr: any, options?: {}): FenceBlock;
     function createStairBlock(identifier: any, category: any, textures_arr: any, options?: {}): StairBlock;
@@ -2991,9 +3126,9 @@ declare class UISystem {
 
 /** 共享 UI 类型定义（JSON UI 规范的受控映射） */
 /** 尺寸向量（像素数字或百分比/计算字符串），如 [320, 207] / ["50%", "100%"] */
-type Size2 = [number | string, number | string];
+type Size2$1 = [number | string, number | string];
 /** 偏移向量 [x, y]（像素） */
-type Offset2 = [number, number];
+type Offset2$1 = [number, number];
 /** 锚点（anchor_from / anchor_to）可选值 */
 type Anchor = 'top_left' | 'top_middle' | 'top_right' | 'left_middle' | 'center' | 'right_middle' | 'bottom_left' | 'bottom_middle' | 'bottom_right';
 /** 数据绑定类型 */
@@ -3158,7 +3293,7 @@ declare class Control {
     propagate_alpha: boolean;
     clips_children: boolean;
     allow_clipping: boolean;
-    clip_offset: Offset2;
+    clip_offset: Offset2$1;
     clip_state_change_event: string;
     enable_scissor_test: boolean;
     property_bag: JsonUIBag;
@@ -3171,7 +3306,7 @@ declare class Control {
     ignored: boolean;
     variables: JsonUIBag;
     modifications: unknown[];
-    grid_position: Offset2;
+    grid_position: Offset2$1;
     collection_index: number;
     /**
      * 设置控件的可见性。
@@ -3220,7 +3355,7 @@ declare class Control {
      * @param {Offset2} offset - 裁剪偏移量，格式为 [x, y]（默认值：[0, 0]）
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setClipOffset(offset?: Offset2): this;
+    setClipOffset(offset?: Offset2$1): this;
     /**
      * 设置裁剪状态更改事件。
      * @param {string} event - 裁剪状态更改时触发的事件名称
@@ -3298,7 +3433,7 @@ declare class Control {
      * @param {Offset2} position - 网格位置，格式为 [行, 列]
      * @returns {Control} 返回当前实例以支持链式调用
      */
-    setGridPosition(position: Offset2): this;
+    setGridPosition(position: Offset2$1): this;
     /**
      * 设置控件在集合中的索引。
      * @param {number} index - 要设置的索引
@@ -3328,13 +3463,13 @@ declare class Control {
  */
 
 type AnchorOrString = Anchor | string;
-type SizeOrString = Size2 | string;
+type SizeOrString = Size2$1 | string;
 declare class Layout {
     [key: string]: unknown;
     size: SizeOrString;
-    max_size: Size2;
-    min_size: Size2;
-    offset: Offset2;
+    max_size: Size2$1;
+    min_size: Size2$1;
+    offset: Offset2$1;
     anchor_from: AnchorOrString;
     anchor_to: AnchorOrString;
     inherit_max_sibling_width: boolean;
@@ -3354,19 +3489,19 @@ declare class Layout {
      * @param {Size2} maxSize - 最大大小，格式为 [width, height]（默认值：["default", "default"]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setMaxSize(maxSize?: Size2): this;
+    setMaxSize(maxSize?: Size2$1): this;
     /**
      * 设置 UI 元素的最小大小。
      * @param {Size2} minSize - 最小大小，格式为 [width, height]（默认值：["default", "default"]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setMinSize(minSize?: Size2): this;
+    setMinSize(minSize?: Size2$1): this;
     /**
      * 设置 UI 元素相对于父元素的位置。
      * @param {Offset2} offset - 偏移量，格式为 [x, y]（默认值：[0, 0]）
      * @returns {Layout} 返回当前实例以支持链式调用
      */
-    setOffset(offset?: Offset2): this;
+    setOffset(offset?: Offset2$1): this;
     /**
      * 设置父元素中的锚点。
      * @param {AnchorOrString} anchorFrom - 锚点（可能值：top_left, top_middle, top_right, left_middle, center, right_middle, bottom_left, bottom_middle, bottom_right）（默认值：center）
@@ -3921,14 +4056,18 @@ declare class ItemComponent {
     static setDurability(max_durability: number, damage_chance_min?: number, damage_chance_max?: number): ItemComponentMap;
     /**
      * 设置放置方块组件
-     * @param block 被放置的方块标识符
+     * @param block 被放置的方块：标识符字符串，或 BlockDescriptor
+     *              （`{ name, states }` / `{ tags }`）。
+     *              ⚠️ `minecraft:block_placer.block` 是否接受 BlockDescriptor 取决于引擎版本
+     *              —— 传之前先按目标引擎验一次（`doc/dev/known-pitfalls.md` §2.3）。
      * @param options 放置配置
-     * @param options.replaceBlockItem 是否替换原方块物品
+     * @param options.replaceBlockItem 是否替换原方块物品（要求物品 id 与方块 id 相同）
      * @param options.alignedPlacement 是否启用对齐放置
      * @param options.useOn 允许放置的目标方块描述符列表；省略则可放置于任何方块
      * @returns 组件 Map
+     * @throws block 不是「非空字符串」也不是「含 string 类型 name 或 tags 的对象」
      */
-    static setBlockPlacer(block: string, options?: BlockPlacerOptions): ItemComponentMap;
+    static setBlockPlacer(block: string | BlockDescriptor, options?: BlockPlacerOptions): ItemComponentMap;
     /**
    * 设置自定义组件列表
    * @param custom_components 自定义组件 ID 数组
@@ -4643,7 +4782,7 @@ declare class Grid extends CollectionPanel {
     grid: GridProp;
     constructor(id: string, template?: string);
     setGridProp(grid_prop: GridProp): this;
-    addGridItem(grid_position: Offset2, content: UIElement | JsonUIBag, name?: string, debugColor?: [number, number, number, number]): this;
+    addGridItem(grid_position: Offset2$1, content: UIElement | JsonUIBag, name?: string, debugColor?: [number, number, number, number]): this;
     protected serializableSources(): object[];
     serialize(): SerializedElement;
 }
@@ -4767,7 +4906,7 @@ declare class StackPanel extends Panel {
     orientation: string;
     stackNum: number;
     constructor(id: string, template?: string);
-    addStack(size: Size2 | string, content: UIElement | JsonUIBag, debug?: boolean): this;
+    addStack(size: Size2$1 | string, content: UIElement | JsonUIBag, debug?: boolean): this;
     /**
      * Possible values:
        vertical
@@ -4802,10 +4941,270 @@ declare class ChestUISystem {
     static registerContainerUI(new_container_title: string, ui_system_root_panel: string): void;
 }
 
+/**
+ * 容器槽位的版面换算 —— 纯函数模块。
+ *
+ * 只做三件事：槽号 ↔ `grid_position`、像素坐标 ↔ 格位 `offset`、槽位声明校验。
+ * **零 import**，因此 Node 里可直接加载、可离线单测（不依赖 UI 元素类与构建管道）。
+ *
+ * 坐标系约定：`pos` / `gridOrigin` 都是**面板左上角为原点**的像素坐标（`top_left` 锚）。
+ */
+type Offset2 = [number, number];
+type Size2 = [number | string, number | string];
+/**
+ * 槽位语义：`input` 不写标志位；`output` / `display` 写 `enabled: false`。
+ *
+ * ⚠️ 这只是**缺省值**：声明里显式给了 `enabled` 时一律以显式值为准（见 `SlotSpec.enabled`）。
+ */
+type SlotKind = 'input' | 'output' | 'display';
+/** 声明的槽位语义全集（用于校验与遍历） */
+declare const SLOT_KINDS: readonly SlotKind[];
+/**
+ * 该槽位语义的**缺省**门控值：`output` / `display` → `false`（`input` → 不写该键）。
+ *
+ * 它只在调用方**没有**显式给 `enabled` 时生效 —— 显式值永远优先（`resolveSlot`）。
+ */
+declare function isGatedKind(kind: SlotKind): boolean;
+/** 格位尺寸：单数字 = 正方形边长；二元组 = [宽, 高] */
+type CellSizeInput = number | Offset2;
+/** 九宫格切分：单数字或 [x0, y0, x1, y1] */
+type NineSlice = number | [number, number, number, number];
+/** 格位背景：纹理路径，或带九宫格切分的纹理描述 */
+type SlotBackground = string | {
+    texture: string;
+    nineslice_size?: NineSlice;
+};
+/** 内层格位控件的锚点（与 `SLOT_CALIBRATION.anchor` 同步） */
+type SlotAnchor = 'top_left' | 'center';
+/** 原版 `common.container_item` 可覆盖变量子集 */
+interface ItemRendererSpec {
+    /** `$item_renderer`：渲染器控件引用 */
+    ref?: string;
+    /** `$item_renderer_size` */
+    size?: Offset2;
+    /** `$item_renderer_offset` */
+    offset?: Offset2;
+    /** `$item_renderer_panel_size` */
+    panelSize?: Offset2;
+}
+/** 槽位声明（`addSlot` 的入参；旧接口路径可用 `gridPosition` / `offset` 直传） */
+interface SlotSpec {
+    /** 容器槽位号（与 `gridPosition` 二选一；两者都给时以 `gridPosition` 为准） */
+    slot?: number;
+    /** 面板内像素坐标（`top_left` 锚）；与 `offset` 二选一（都给时以 `offset` 为准） */
+    pos?: Offset2;
+    /** 显式网格位置 `[列, 行]`（旧接口路径；给了就不再由 `slot` 换算） */
+    gridPosition?: Offset2;
+    /** 显式偏移（旧接口路径；给了就不再由 `pos` 换算） */
+    offset?: Offset2;
+    /** 槽位语义，默认 `input` */
+    kind?: SlotKind;
+    /**
+     * 该槽的**视觉**格位尺寸（默认取标定表）。
+     *
+     * 只影响内层控件的 `$cell_image_size` / `size`，**不参与**基座与网格尺寸换算 ——
+     * 网格几何一律由 `setSlotDefaults({ cellSize })`（或标定表）决定；比格位大的视觉尺寸
+     * 会从格位左上角向外溢出（原版槽位模板允许，用于画长条进度槽之类）。
+     */
+    cellSize?: CellSizeInput;
+    /** 内层控件尺寸（不给则等于 `cellSize`） */
+    size?: Size2;
+    /**
+     * 显式写进内层控件的 `enabled` 值。**给了就以此为准**，覆盖 `kind` 的缺省门控。
+     *
+     * 缺省行为：`input` 不写该键（继承原版默认 `true`）、`output` / `display` 写 `false`。
+     * 传 `true` 可让被门控的槽位恢复交互（例如「产物要能取出来」的输出槽）。
+     */
+    enabled?: boolean;
+    /** 格位背景纹理（框架据此生成背景 image 控件） */
+    background?: SlotBackground;
+    /** `$background_images`：直接指定已有的背景控件引用 */
+    backgroundImages?: string;
+    /** 原版 item renderer 变量覆盖 */
+    itemRenderer?: ItemRendererSpec;
+    /** 其余原版可覆盖变量，键名不带 `$` 与 `|default` 后缀 */
+    vars?: Record<string, unknown>;
+}
+/** 槽位默认值（`setSlotDefaults` 的入参：除 `slot` / `pos` / `gridPosition` / `offset` 外均可） */
+type SlotDefaults = Omit<SlotSpec, 'slot' | 'pos' | 'gridPosition' | 'offset'>;
+/** 标定表 */
+interface SlotCalibration {
+    anchor: SlotAnchor;
+    originPadding: Offset2;
+    cellSize: Offset2;
+    columns: number;
+    /** 未调用 `setGridOrigin` 时网格的默认原点（给顶部标题留高度） */
+    defaultGridOrigin: Offset2;
+}
+/**
+ * ★ 待真机校准项 —— 整套「格位基座」假设集中在此，校准只需改这一个对象。
+ *
+ * 假设：格位基座 = 网格原点 + 该格在网格里的序号 × **网格统一格位尺寸**，且格位锚点在左上角。
+ * 真机实测若证明锚点其实在格位中心（offset 整体差半格），把 `anchor` 改成 `'center'`
+ * 即可同时翻转换算与写进产物的 `anchor_from` / `anchor_to`，不必改调用方。
+ */
+declare const SLOT_CALIBRATION: Readonly<SlotCalibration>;
+/** 换算参数 */
+interface CellLayoutOptions {
+    /** 网格在面板内的原点（`top_left` 锚，像素） */
+    gridOrigin?: Offset2;
+    /** 槽号所在网格的列数（默认取标定表） */
+    columns?: number;
+    /**
+     * **网格统一格位尺寸**（几何）：整张网格的格位尺寸，同一网格内只有这一个值
+     * （来自 `setSlotDefaults({ cellSize })` 或标定表）。
+     *
+     * 逐槽声明的 `cellSize` **不参与**基座换算，它只决定内层控件的视觉尺寸（可溢出格位）。
+     * 传入逐槽尺寸会让偏移与网格尺寸互相矛盾。
+     */
+    gridCellSize?: CellSizeInput;
+    /** 标定表覆盖（默认 `SLOT_CALIBRATION`） */
+    calibration?: SlotCalibration;
+}
+/** 解析标定表：缺省字段回落 `SLOT_CALIBRATION` */
+declare function resolveCalibration(calibration?: Partial<SlotCalibration>): SlotCalibration;
+/** 把 `number | [宽, 高]` 归一成 `[宽, 高]`；非法输入回落 `fallback` */
+declare function normalizeCellSize(size: CellSizeInput | undefined, fallback?: Offset2): Offset2;
+/**
+ * 槽号 → 网格位置 `[列, 行]`（行优先）。
+ * @param slot 容器槽位号，须为非负整数
+ * @param columns 网格列数，默认取标定表（1 = 单列）
+ */
+declare function slotToGridPosition(slot: number, columns?: number): Offset2;
+/** 一组网格位置 → `grid_dimensions` `[列, 行]`（至少 `[1, 1]`） */
+declare function gridDimensionsFor(positions: Offset2[]): Offset2;
+/**
+ * 单个格位的基座坐标（面板像素）。
+ *
+ * 这是「网格原点 + 序号 × 网格统一格位尺寸」假设的**唯一落点**；锚点由标定表的 `anchor` 决定
+ * （`top_left` 时基座即格位左上角，`center` 时再加半个格位）。
+ *
+ * ⚠️ 格位尺寸取 `options.gridCellSize`（整张网格一个值）；**不要**传某个槽自己的视觉尺寸 ——
+ * 引擎的网格格位是均匀的，逐槽尺寸只会让偏移与网格尺寸互相矛盾。
+ */
+declare function cellBase(slot: number, options?: CellLayoutOptions): Offset2;
+/**
+ * 像素坐标 → 格位 `offset`（相对格位基座）。
+ * @param pos 目标位置（面板左上角为原点的像素坐标）
+ * @param slot 容器槽位号
+ */
+declare function posToOffset(pos: Offset2, slot: number, options?: CellLayoutOptions): Offset2;
+/** 与标定表同步的锚点属性（写进内层格位控件） */
+declare function anchorProps(calibration?: Partial<SlotCalibration>): {
+    anchor_from: SlotAnchor;
+    anchor_to: SlotAnchor;
+};
+/** 归一化背景描述：字符串 → `{ texture }`；非法输入 → `undefined` */
+declare function normalizeBackground(background: SlotBackground | undefined): {
+    texture: string;
+    nineslice_size?: NineSlice;
+} | undefined;
+/**
+ * 校验一条槽位声明。
+ * @returns 警告文案数组（空数组 = 通过）；**任何输入都不会抛错**
+ */
+declare function validateSlotSpec(spec: SlotSpec | undefined, context?: {
+    existingSlots?: number[];
+}): string[];
+/** 门控键（同时会用作 `ui/<name>.json` 的文件名）允许的字符 */
+declare const UI_NAME_PATTERN: RegExp;
+/** 门控键是否可安全用作 UI 文件名 */
+declare function isSafeUIName(name: unknown): boolean;
+/**
+ * 校验门控键 / UI 文件名。
+ * @returns 不合规时的说明文案；合规返回 `undefined`
+ */
+declare function checkUIName(name: unknown): string | undefined;
+/** 已解析的槽位：默认值已合并、`grid_position` 与 `offset` 已换算完毕 */
+interface ResolvedSlot {
+    slot: number;
+    kind: SlotKind;
+    /** 写进产物的 `grid_position` `[列, 行]` */
+    gridPosition: Offset2;
+    /** 面板像素坐标（显式 `gridPosition` 路径下为格位基座） */
+    pos: Offset2;
+    /** 写进产物的 `offset` */
+    offset: Offset2;
+    /** 该槽的**视觉**格位尺寸（网格几何由 `setSlotDefaults` 决定，见 `CellLayoutOptions.gridCellSize`） */
+    cellSize: Offset2;
+    /** 调用方是否显式声明了 `cellSize`（决定是否写出 `$cell_image_size` / `size`） */
+    cellSizeDeclared: boolean;
+    /** 写进 `enabled` 的值；`undefined` = 不写该键 */
+    enabled: boolean | undefined;
+    /** 是否由 `pos` 换算得到 offset（是则同时写锚点，保证换算前提成立） */
+    derived: boolean;
+    background?: {
+        texture: string;
+        nineslice_size?: NineSlice;
+    };
+    backgroundImages?: string;
+    size?: Size2;
+    itemRenderer?: ItemRendererSpec;
+    vars: Record<string, unknown>;
+}
+/**
+ * 把一条槽位声明解析成可写进产物的槽位记录（合并默认值 + 换算 `grid_position` / `offset`）。
+ *
+ * `gridPosition` / `offset` 任一显式给出时走旧接口路径：该维度原样使用，不参与换算。
+ */
+declare function resolveSlot(spec: SlotSpec, options?: CellLayoutOptions & {
+    defaults?: SlotDefaults;
+}): ResolvedSlot;
+
 type Any = any;
+/** 旧式格位声明（`addGridItem` / `addInputGrid` / `addOutputGrid` 的 options） */
+interface LegacyGridItemOptions {
+    /** @deprecated 用 `enabled`；JSON UI 的属性名是 `enabled` 不是 `enable` */
+    enable?: boolean;
+    /** 是否写 `enabled`；给了就覆盖 `kind` 的缺省门控，不给则只有 `output` / `display` 写 `false` */
+    enabled?: boolean;
+    /** 内层控件尺寸 */
+    size?: Any;
+    /** `$background_images` 背景控件引用 */
+    background_images?: Any;
+}
+/** `setPanel` 的入参 */
+interface PanelOptions {
+    /** 根面板尺寸（像素） */
+    size?: Size2;
+    /** 面板背景纹理 */
+    background?: SlotBackground;
+}
+/** 进度指示图的裁切方向：露出的是**该侧**的比例那一段（`'left'` = 从左往右填） */
+type ProgressClipDirection = 'left' | 'right' | 'up' | 'down' | 'center';
+/** `addProgressSlot` 的入参 */
+interface ProgressSlotOptions {
+    /** 容器槽位号 */
+    slot: number;
+    /** 面板内像素坐标（左上角原点），与 `addSlot` 同义 */
+    pos: Offset2;
+    /** 按比例裁开的填充图（纹理路径），例如 `textures/ui/arrow_active` */
+    fill: string;
+    /** 垫在下面的静止底图（可选）；给了的话即使裁切没生效也还看得见轮廓 */
+    base?: string;
+    /** 视觉尺寸（像素），默认 `[22, 15]`（原版熔炉箭头尺寸） */
+    size?: Offset2;
+    /** 裁切方向，默认 `'left'`；从下往上烧的火焰用 `'down'` */
+    clipDirection?: ProgressClipDirection;
+    /**
+     * 贴图是否**保持纵横比**，默认 `false`（= 按 `size` 拉伸铺满）。
+     *
+     * 默认拉伸，是因为这个槽的契约就是「这块就是 `size` 像素」；原版箭头的贴图恰与尺寸同比例，
+     * 两者无差别。**贴图与 `size` 比例不同时**（例如把一根竖长条压进矮格子）必须显式决定：
+     * `false` = 拉伸变形；`true` = 按比例缩放（会留边，实际宽度不再是 `size`）。
+     */
+    keepRatio?: boolean;
+    /** 比例来源的集合名，默认 `"container_items"`（小箱子与大箱子都是它） */
+    collection?: string;
+    /** 额外写进槽位的原版变量（可覆盖内置的两条） */
+    vars?: Record<string, unknown>;
+}
 /**
- * 自定义容器 UI 系统类，用于创建和管理容器界面。
- * 支持动态添加网格项、设置标题、调整尺寸等功能。
+ * 自定义容器 UI 系统：把「容器槽位」声明成面板内的像素版面。
+ *
+ * 坐标系为面板左上角原点的像素坐标（`top_left` 锚）；`grid_position` 与格位基座的换算见
+ * `containerLayout.ts`（其中 `SLOT_CALIBRATION` 是唯一的待真机校准点）。
+ * 面板背景与已声明槽位在每次修改后整体重建，故可自由链式调用。
  */
 declare class ContainerUISystem {
     #private;
@@ -4813,61 +5212,125 @@ declare class ContainerUISystem {
     title: string;
     root_panel_size: [number, number];
     gridDimension: [number, number];
-    output_grids: number[][];
+    /** 输出槽记录（`setOutputSlots` 写入）；不参与版面，版面由槽位声明的 `kind` 决定 */
+    outputSlots: number[][];
     main_panel: Panel;
     grids: Grid;
     constructor(identifier: string, path: string);
+    /**
+     * 设置面板尺寸与背景图。
+     * @param {PanelOptions} [options] - `size` 为像素尺寸；`background` 为纹理路径或 `{ texture, nineslice_size? }`
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    setPanel(options?: PanelOptions): this;
+    /**
+     * 设置网格在面板内的原点（未调用时取标定表的默认原点，已为顶部标题让开一行）。
+     * @param {Offset2} origin - 像素坐标 [x, y]
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    setGridOrigin(origin: Offset2): this;
+    /**
+     * 合并槽位默认值（对之后声明的每个槽生效）。
+     *
+     * ★ `cellSize` 是**整张网格的统一格位尺寸（几何）**：基座换算与网格尺寸都用它。
+     * 逐槽声明 `addSlot({ cellSize })` 只改该格的视觉尺寸（可溢出格位），不参与几何。
+     * @param {SlotDefaults} defaults - 除 `slot` / `pos` / `gridPosition` / `offset` 外的槽位字段
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    setSlotDefaults(defaults?: SlotDefaults): this;
+    /**
+     * 声明一个容器槽位：`slot` 定槽号、`pos` 定面板内像素位置，框架负责换算 `grid_position` 与 `offset`。
+     *
+     * `kind` 为 `output` / `display` 时写 `enabled: false`；`input`（默认）不写该键。
+     * 显式传 `enabled` 则一律以它为准（`{ kind: 'output', enabled: true }` = 产物格可交互）。
+     * 声明不合规时只 `console.warn`，不抛错。
+     * @param {SlotSpec} spec - 槽位声明
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    addSlot(spec: SlotSpec): this;
+    /**
+     * 向主面板中添加一个控件。
+     * @param {UIElement | Any} element - 控件（UIElement 实例或原生 JSON UI 控件对象）
+     * @param {Offset2} [pos] - 面板内像素坐标 [x, y]；给了就按 `top_left` 锚定位
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    addControl(element: UIElement | Any, pos?: Offset2): this;
+    /**
+     * 向主面板中添加一个控件（`addControl` 的别名）。
+     * @param {UIElement | Any} element - 控件
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    addElementToMain(element: UIElement | Any): this;
+    /**
+     * 声明一个「进度指示槽」：`base` 垫底、`fill` 按 `clipDirection` 裁开，比例取**本格物品的耐久**。
+     *
+     * 与 `addSlot` 的区别：除了声明槽位，还会生成一个自定控件、经 `$cell_overlay_ref`
+     * 注入到格子内部（`common.container_item` 的 `item_cell`）。它在格内，
+     * 所以保留每格的 collection 上下文，读的是**本格自己**的绑定 —— 每格可以各显示各的进度。
+     *
+     * 典型用法：脚本往该槽写一个可损耗物品、让「剩余耐久 = 进度」
+     * （见 `examples/mob_chest/scripts/progress_bar.js`），即可用原版箭头/火焰贴图画出进度，
+     * **不需要任何进度条贴图**。
+     *
+     * 同时会关掉引擎自带的耐久条（`$durability_bar_required`）并把格子的浅灰底换成零尺寸面板
+     * （`$background_images`），否则会看到「灰方块 + 图」。`vars` 可覆盖这两条内置变量。
+     * @param {ProgressSlotOptions} options 槽位声明
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    addProgressSlot(options: ProgressSlotOptions): this;
+    /**
+     * 旧式网格项：直接给 `grid_position` 与 `offset`，不做坐标换算。
+     * @param {Offset2} grid_position - 网格位置 [列, 行]
+     * @param {Offset2} offset - 内层控件的偏移 [x, y]
+     * @param {LegacyGridItemOptions} [options] - 可选覆盖
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
+     */
+    addGridItem(grid_position: Offset2, offset: Offset2, options?: LegacyGridItemOptions): this;
+    /**
+     * 旧式输入槽（等价 `addGridItem`）。
+     * @param {Offset2} grid_position - 网格位置 [列, 行]
+     * @param {Offset2} offset - 内层控件的偏移 [x, y]
+     * @param {LegacyGridItemOptions} [options] - 可选覆盖
+     */
+    addInputGrid(grid_position: Offset2, offset: Offset2, options?: LegacyGridItemOptions): void;
+    /**
+     * 旧式输出槽：在该格位内层控件上写 `enabled: false`。
+     *
+     * ⚠️ 该标志位**整体禁用这一格**（既放不进、也取不出）⇒ 需要能取出产物的输出槽
+     * 请用 `addSlot({ kind: 'output', enabled: true })`。
+     * @param {Offset2} grid_position - 网格位置 [列, 行]
+     * @param {Offset2} offset - 内层控件的偏移 [x, y]
+     * @param {LegacyGridItemOptions} [options] - 可选覆盖（本方法不转发 `enabled` ⇒ 恒为 `false`）
+     */
+    addOutputGrid(grid_position: Offset2, offset: Offset2, options?: LegacyGridItemOptions): void;
+    /**
+     * 记录输出槽数组（供上层读取）；不改变已声明槽位的版面与语义。
+     * @param {number[][]} output_arr - 输出槽记录
+     */
+    setOutputSlots(output_arr: number[][]): void;
+    /**
+     * @deprecated 名字写反了（它存的是输出槽），改用 `setOutputSlots`
+     * @param {number[][]} output_arr - 输出槽记录
+     */
     setInputGrid(output_arr: number[][]): void;
     /**
-     * 向网格中添加一个网格项。
-     * @param {number[]} grid_position - 网格项的位置 [行, 列] 用于定位实体的背包槽。
-     * @param {number[]} offset - 网格项的偏移量 [x, y]。
-     * @param {Object} [options] - 可选参数，用于配置网格项。
-     * @param {boolean} [options.enable=true] - 是否启用该网格项，默认为 true。
-     * @param {number[]} [options.size] - 网格项的大小 [宽度, 高度]。
-     * @param {UIElement[]} [options.background_images] - 网格项的背景图片控件。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    addGridItem(grid_position: Offset2, offset: Offset2, options?: {
-        enable?: boolean;
-        size?: Any;
-        background_images?: Any;
-    }): this;
-    addInputGrid(grid_position: Offset2, offset: Offset2, options?: {
-        enable?: boolean;
-        size?: Any;
-        background_images?: Any;
-    }): void;
-    addOutputGrid(grid_position: Offset2, offset: Offset2, options?: {
-        enable?: boolean;
-        size?: Any;
-        background_images?: Any;
-    }): void;
-    /**
-     * 向主面板中添加一个 UI 元素。
-     * @param {Any} element - 要添加的 UI 元素。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
-     */
-    addElementToMain(element: Any): this;
-    /**
-     * 设置网格的维度（行和列）。
-     * @param {number[]} dimension - 网格的维度 [行数, 列数]。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     * 设置网格的行列数（显式覆盖；不调用则按已声明槽位自动推导）。
+     * @param {number[]} dimension - 网格维度 [列数, 行数]
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
      */
     setGridDimension(dimension: number[]): this;
     /**
      * 设置容器的标题。
-     * @param {string} title - 容器的标题。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     * @param {string} title - 容器的标题
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
      */
     setTitle(title: string): this;
     /**
      * 设置根面板的尺寸。
-     * @param {number[]} size - 根面板的尺寸 [宽度, 高度]。
-     * @returns {ContainerUISystem} 返回当前实例以支持链式调用。
+     * @param {number[]} size - 根面板的尺寸 [宽度, 高度]（像素）
+     * @returns {ContainerUISystem} 返回当前实例以支持链式调用
      */
     setSize(size: number[]): this;
-    setItemMatrix(n: number, matrix: number[][]): void;
 }
 
 /**
@@ -4957,7 +5420,19 @@ declare class FormButtonGrid {
     });
     /** 给每个格子描红调试框 */
     enableDebug(): this;
-    /** 加一枚内容：index 决定基准格（off_col = index%c, off_row = index/c）；给 pos 则叠加。仅 FormButton 注入集合/门控绑定。 */
+    /**
+     * 加一枚内容。
+     *
+     * ⚠️ index 必须是该按钮在**运行期 form 里的槽位序号**（不是视觉序号）：
+     *    index 被编码成 grid_position（col = index%c, row = index/c），而 Bedrock 的集合格盘
+     *    正是靠 grid_position（行优先序号）**把格子绑到对应的 form 按钮**；
+     *    按钮最终落在哪一格由第二个参数 pos 决定（offset = -基准格 + pos）。
+     *    例：表单前 3 个槽被 prev/home/next 占用时，第 i 张卡要写 addButton(3 + i, card, [i, 0])；
+     *    若误传视觉序号（0/1/2…），卡片会绑到 no_prev/no_home/no_next 等占位槽，
+     *    门控 `($binding_button_text = #form_button_text)` 不成立 → 卡片整片不显示。
+     *
+     * 仅 FormButton 注入集合/门控绑定。
+     */
     addButton(index: number, btn: FormButton | UIElement, pos?: [number, number]): this;
     /** 注入 FormButton 的集合/门控绑定（离开 Grid 则无效） */
     private injectBindings;
@@ -4981,13 +5456,45 @@ declare class SapdonTexturedButton extends UIElement {
  * SapdonGuideBook —— 帕秋莉式手册（分类索引 INDEX + 词条列表 CAT + 内容页 ENT + home/prev/next 导航）。
  *
  * 线协议（运行时发射）：
- *   body = "INDEX"          → 显示分类索引网格（子按钮 = 各分类，setBinding 精确门控）
- *   body = "CAT:<id>|p<N>"   → 分类页（p0 左简介/右 list，p1+ 左右 list）
+ *   body = "INDEX"              → 索引页 p0（左封面 + 右半页 ≤16 张分类卡）
+ *   body = "IDX|p<N>"           → 索引页 p1+（左右半页各 ≤8 张卡，先填左列再填右列）
+ *   body = "CAT:<id>|p<N>"      → 分类页（p0 左简介/右 list，p1+ 左右 list）
  *   body = "ENT:<id>:<gi>|p<N>" → 词条内容页（按 pageType 渲染、可分页）
  *   title = "sapdon_ui:<name>"
- *   button(...)             → 集合 form_buttons：分类按钮 or 导航，均 exact-match 门控
+ *   button(...)                 → 集合 form_buttons：分类按钮 idx<i> or 导航，均 exact-match 门控
+ *
+ * 索引页（INDEX）分页规则：
+ *   每页最多 IDX_PER_PAGE(16) 张分类卡；p0 用右半页（4 列 × ≤4 行 = ≤16），
+ *   p1+ 左右半页各一列（4 列 × ≤2 行 = ≤8/列），**先填左列再填右列**；
+ *   卡片绑定名 = 分类在 build() 入参里的全局序号（idx0..idxN），跨页唯一。
+ *   分类 ≤16 时只有 p0，body 仍是历史上的 "INDEX"（旧脚本无需改动）。
+ *
+ * ⚠️ p1+ 的 body 用 "IDX|p<N>" 而非 "INDEX|p<N>"：门控是「包含」匹配（见 gateLayout），
+ *    "INDEX|p1" 会同时命中 p0 的 "INDEX"，让封面与 p0 卡格一起亮起来；
+ *    "IDX|p1" 不含 "INDEX" 子串，两页互斥。
  */
 type GuideBookPageType = 'text' | 'crafting' | 'spotlight' | 'image';
+/**
+ * 手册里由框架渲染的固定标签（i18n 接入点）。
+ *
+ * ⚠️ 框架**不做任何 lang 键解析**：这里拿到什么字符串就原样交给 `Text.setText`，
+ *    JSON UI 自己会解析 `fz.gb.ui.chapter` 这类键。所以传 lang 键的项目**必须**
+ *    在 `RP/texts/*.lang` 里定义该键，否则界面显示裸键名。
+ * ⚠️ 默认值 = 历史上的中文字面量，**故意保持现状**：不传 labels 的项目产物逐字节不变
+ *    （回归基线见 AGENTS.md / doc/guidebook.md：guidebook_demo 的 book.json 587870 字节）。
+ */
+interface GuideBookLabels {
+    /** CAT 页章节列表的标题 */
+    chapter: string;
+    /** INDEX 页索引卡列的标题 */
+    category: string;
+}
+/** 手册固定标签的默认值（= 历史字面量，改它会让所有既有项目产物变化） */
+declare const DEFAULT_GUIDE_BOOK_LABELS: GuideBookLabels;
+interface GuideBookOptions {
+    /** 覆盖框架渲染的固定标签（只传要改的键，其余走默认值） */
+    labels?: Partial<GuideBookLabels>;
+}
 interface GuideBookChapter {
     name: string;
     icon: string;
@@ -5030,12 +5537,20 @@ declare class SapdonGuideBook {
     private size;
     private background;
     private debug;
+    /** 框架渲染的固定标签（i18n；默认值 = 历史中文字面量） */
+    private labels;
     private coverTitle;
     private coverLines;
-    constructor(identifier: string, size?: [number, number], background?: string);
+    constructor(identifier: string, size?: [number, number], background?: string, options?: GuideBookOptions);
     enableDebug(): this;
     /** 自定义封面：标题（可含 \n）+ 简介行 */
     setCover(title: string, lines: string[]): this;
+    /**
+     * 覆盖框架渲染的固定标签（章节 / 类别）。
+     * 只传要改的键，其余保持**当前值**（增量合并，可反复调用）——
+     * 传 lang 键如 'fz.gb.ui.chapter' 时由 JSON UI 自行解析。
+     */
+    setLabels(labels: Partial<GuideBookLabels>): this;
     /** 布局容器：<tag> 命中 #form_text（含 tag 即显示） */
     private gateLayout;
     private navButton;
@@ -5057,6 +5572,22 @@ declare class SapdonGuideBook {
     private catPages;
     /** ENT 词条内容页（L3）：按 pageType 分派布局；text 按 5 行/半页分页；门控 ENT:<id>:<gi>|p<N> */
     private entPages;
+    /** 一张索引卡：上图标、下名称（绑定名 = 分类全局序号 idx<i>） */
+    private catCard;
+    /**
+     * 往 col 里挂一列索引卡：空 5% / 标题 10% / 分割线 3% / 卡格 rows 行 / 分割线 3% / 余量。
+     * 卡格 = 4 列 × rows 行的 FormButtonGrid，装 cards[start, end)（全局序号，先左后右逐行填）。
+     * ids 由调用方给定，便于 p0 沿用历史元素名（right_index / cat_row / sp_end …）。
+     *
+     * ⚠️ slotBase = 本列第一张卡在运行期 form 里的**槽位序号**（INDEX 页固定 3：prev/home/next 占 0-2）。
+     *    FormButtonGrid.addButton 的 index 会被编码成 grid_position，而 Bedrock 的集合格盘是靠
+     *    grid_position（行优先序号）**把格子绑到对应的 form 按钮**上；视觉落点由第二个参数 pos 决定。
+     *    所以 index 必须是槽位序号（历史上就是 `3 + i`），写成 0/1/2… 会让卡片绑到 no_prev/no_home/
+     *    no_next 等占位槽，门控 `($binding_button_text = #form_button_text)` 全部不成立 → 卡片整片消失。
+     */
+    private addIndexColumn;
+    /** 索引卡分几页：p0 容量 16，p1+ 每页 16（左 8 + 右 8） */
+    private indexPageCount;
     build(categories: GuideBookCategory[]): this;
     getSystem(): UISystem;
 }
@@ -5134,9 +5665,24 @@ declare const f64: (literal: FloatLiteral) => {
 };
 declare function isRawJSON(v: any): boolean;
 
+/**
+ * Client
+ */
+declare class GRegistry {
+    static debug: boolean;
+    /**
+     * 生成注册器
+     * @param {string} name 文件名字
+     * @param {string} root 根目录，如 "behavior"、"resource" 等
+     * @param {string} path 数据的路径，如 "blocks/"、"items/"、"recipes/" 等
+     * @param {object} data 数据操作类实例 通过toObject方法转成正确格式json文本
+     */
+    static register(name: string, root: string, path: string, data: object): void;
+    static submit(): void;
+}
 declare namespace registry {
     function submit(): void;
 }
 
-export { AddonAnimationController, AddonAnimationStateMachine, AddonAttachable, AddonAttachableDefinition, AddonAttachableDescription, AddonBiome, AddonBiomeDefinition, AddonBiomeDescription, AddonBlock, AddonBlockDefinition, AddonBlockDescription, AddonClientEntity, AddonClientEntityDefinition, AddonClientEntityDescription, AddonEntity, AddonEntityDefinition, AddonEntityDescription, AddonFeatureRule, AddonFeatureRuleDecription, AddonFeatureRuleDenifition, AddonItem, AddonItemDefinition, AddonItemDescription, AddonManifest, AddonManifestDependency, AddonManifestHeader, AddonManifestMetadata, AddonManifestModule, AddonMenuCategory, AddonOreFeature, AddonOreFeatureDefinition, AddonOreFeatureDescription, AddonRecipe, AddonRecipeFurnace, AddonRecipeFurnace_1_12, AddonRecipeFurnace_1_17, AddonRecipeShaped, AddonRecipeShaped_1_12, AddonRecipeShaped_1_17, AddonRecipeShaped_1_19, AddonRecipeShaped_1_20, AddonRecipeShapeless, AddonRecipeShapeless_1_12, AddonRecipeShapeless_1_17, AddonRenderController, AddonRenderControllerGroup, AddonSemanticVersion, Armor, ArmorType, Attachable, BasicBlock, BasicBundle, BasicEntity, BasicMovementBundle, Biome, BiomeAPI, BiomeComponent, BiomeFilter, Block, BlockAPI, BlockComponent, BlockCustomComponentBuilder, Button, ButtonMapping, ChestUISystem, ClientEntity, CollectionPanel, ContainerUISystem, Control, CoordinateDistribution, CropBlock, DataBinding, DataBindingObject, DummyEntity, Entity, EntityAPI, EntityComponent, Factory, FeatureAPI, FeatureConditions, FeatureDistribution, FeatureRule, FenceBlock, FlipbookItem, FlipbookTextureConfig, FlipbookTextures, FollowMobBehavior, FollowParentBehavior, Food, FormButton, FormButtonGrid, GeometryBlock, GlassBlock, GoHomeBehavior, Grid, GridProp, HeadBlock, HudProgressBar, HudStatePanel, HudUISystem, Image, Input, Item, ItemAPI, ItemCatalog, ItemCategory, ItemComponent, ItemTextureManager, Label, Layout, Modifications, MoveTowardsHomeRestrictionBehavior, NativeEntity, NativeEntityData, Navigation, NearestAttackableTargetBehavor, NonNullMap, OreBlock, OreFeature, Panel, PickupItemsBehavior, Projectile, RandomStrollBehavior, RecipeAPI, RecipeInputTags, RecipeTags, RecipeTypes, RotatableBlock, RotationTypes, SapdonGuideBook, SapdonPanel, SapdonServerUI, SapdonTexturedButton, ScrollView, ScrollingPanel, Serializable, Serializer, Sound, Sprite, StackPanel, StairBlock, TemptBehavior, TerrainTextureManager, Text, TextureVariationConfig, TileBlock, TintMethod, TrapdoorBlock, UIElement, UISystem, UISystemRegistry, UiAPI, decode, defaultSerializer, encode, f64, getMetadata, getOrCreateMetadata, isRawJSON, jsonEncodeDecoder, jsonEncoderReplacer, mixin, registerBlock, registerEntity, registry, serialize };
-export type { ArmorOptions, ArmorSpec, BeforeOnPlayerPlaceEvent, BlockCustomComponentHandlers, BlockDescriptor, BlockPlacerOptions, ConstructorOf, CooldownOptions, CreateModelItemOptions, DiggerOptions, DurabilitySensorOptions, DurabilityThreshold, EncodeDecoder, EntityPlacerOptions, FlipbookEntry, FlipbookItemOptions, FloatLiteral, FoodComponentOptions, FoodOptions, GuideBookCategory, GuideBookChapter, GuideBookPageType, ISerializer, IconTextures, ItemCatalogCategory, ItemCatalogGroupOptions, ItemComponentMap, ItemOptions, ItemRarity, KineticWeaponOptions, ModelBoneTransform, OnBlockStateChangeEvent, OnBreakEvent, OnEntityEvent, OnEntityFallOnEvent, OnPlaceEvent, OnPlayerBreakEvent, OnPlayerInteractEvent, OnRandomTickEvent, OnRedstoneUpdateEvent, OnStepOffEvent, OnStepOnEvent, OnTickEvent, PiercingWeaponOptions, Range, RawType, RecordOptions, RepairItem, SapdonPageRegistration, SerializedElement, ShooterAmmunition, ShooterOptions, StorageItemOptions, SwingSoundsOptions, TextureEntry, TextureVariation, ThrowableOptions, UseModifiersOptions };
+export { AddonAnimationController, AddonAnimationStateMachine, AddonAttachable, AddonAttachableDefinition, AddonAttachableDescription, AddonBiome, AddonBiomeDefinition, AddonBiomeDescription, AddonBlock, AddonBlockDefinition, AddonBlockDescription, AddonClientEntity, AddonClientEntityDefinition, AddonClientEntityDescription, AddonEntity, AddonEntityDefinition, AddonEntityDescription, AddonFeatureRule, AddonFeatureRuleDecription, AddonFeatureRuleDenifition, AddonItem, AddonItemDefinition, AddonItemDescription, AddonManifest, AddonManifestDependency, AddonManifestHeader, AddonManifestMetadata, AddonManifestModule, AddonMenuCategory, AddonOreFeature, AddonOreFeatureDefinition, AddonOreFeatureDescription, AddonRecipe, AddonRecipeFurnace, AddonRecipeFurnace_1_12, AddonRecipeFurnace_1_17, AddonRecipeShaped, AddonRecipeShaped_1_12, AddonRecipeShaped_1_17, AddonRecipeShaped_1_19, AddonRecipeShaped_1_20, AddonRecipeShapeless, AddonRecipeShapeless_1_12, AddonRecipeShapeless_1_17, AddonRenderController, AddonRenderControllerGroup, AddonSemanticVersion, Armor, ArmorType, Attachable, BasicBlock, BasicBundle, BasicEntity, BasicMovementBundle, Biome, BiomeAPI, BiomeComponent, BiomeFilter, Block, BlockAPI, BlockComponent, BlockCustomComponentBuilder, Button, ButtonMapping, ChestUISystem, ClientEntity, CollectionPanel, ContainerUISystem, Control, CoordinateDistribution, CropBlock, DEFAULT_GUIDE_BOOK_LABELS, DataBinding, DataBindingObject, DummyEntity, Entity, EntityAPI, EntityComponent, Factory, FeatureAPI, FeatureConditions, FeatureDistribution, FeatureRule, FenceBlock, FlipbookItem, FlipbookTextureConfig, FlipbookTextures, FollowMobBehavior, FollowParentBehavior, Food, FormButton, FormButtonGrid, GRegistry, GeometryBlock, GlassBlock, GoHomeBehavior, Grid, GridProp, HeadBlock, HudProgressBar, HudStatePanel, HudUISystem, Image, Input, Item, ItemAPI, ItemCatalog, ItemCategory, ItemComponent, ItemTextureManager, Label, Layout, Modifications, MoveTowardsHomeRestrictionBehavior, NativeEntity, NativeEntityData, Navigation, NearestAttackableTargetBehavor, NonNullMap, OreBlock, OreFeature, Panel, PickupItemsBehavior, Projectile, RandomStrollBehavior, RecipeAPI, RecipeInputTags, RecipeTags, RecipeTypes, RotatableBlock, RotationTypes, SLOT_CALIBRATION, SLOT_KINDS, SapdonGuideBook, SapdonPanel, SapdonServerUI, SapdonTexturedButton, ScrollView, ScrollingPanel, Serializable, Serializer, Sound, Sprite, StackPanel, StairBlock, TemptBehavior, TerrainTextureManager, Text, TextureVariationConfig, TileBlock, TintMethod, TrapdoorBlock, UIElement, UISystem, UISystemRegistry, UI_NAME_PATTERN, UiAPI, anchorProps, cellBase, checkUIName, decode, defaultSerializer, encode, f64, getMetadata, getOrCreateMetadata, gridDimensionsFor, isGatedKind, isRawJSON, isSafeUIName, jsonEncodeDecoder, jsonEncoderReplacer, mixin, normalizeBackground, normalizeCellSize, posToOffset, registerBlock, registerEntity, registry, resolveCalibration, resolveSlot, serialize, slotToGridPosition, validateSlotSpec };
+export type { ArmorOptions, ArmorSpec, BeforeOnPlayerPlaceEvent, BlockCustomComponentHandlers, BlockDescriptor, BlockPlacerOptions, CellLayoutOptions, CellSizeInput, ConstructorOf, CooldownOptions, CreateModelItemOptions, DiggerOptions, DurabilitySensorOptions, DurabilityThreshold, EncodeDecoder, EntityPlacerOptions, FlipbookEntry, FlipbookItemOptions, FloatLiteral, FoodComponentOptions, FoodOptions, GuideBookCategory, GuideBookChapter, GuideBookLabels, GuideBookOptions, GuideBookPageType, ISerializer, IconTextures, ItemCatalogCategory, ItemCatalogGroupOptions, ItemComponentMap, ItemOptions, ItemRarity, ItemRendererSpec, KineticWeaponOptions, LegacyGridItemOptions, ModelBoneTransform, NineSlice, Offset2, OnBlockStateChangeEvent, OnBreakEvent, OnEntityEvent, OnEntityFallOnEvent, OnPlaceEvent, OnPlayerBreakEvent, OnPlayerInteractEvent, OnRandomTickEvent, OnRedstoneUpdateEvent, OnStepOffEvent, OnStepOnEvent, OnTickEvent, PanelOptions, PiercingWeaponOptions, ProgressClipDirection, ProgressSlotOptions, Range, RawType, RecordOptions, RepairItem, ResolvedSlot, SapdonPageRegistration, SerializedElement, ShooterAmmunition, ShooterOptions, Size2, SlotAnchor, SlotBackground, SlotCalibration, SlotDefaults, SlotKind, SlotSpec, StorageItemOptions, SwingSoundsOptions, TextureEntry, TextureVariation, ThrowableOptions, UseModifiersOptions };