sapdon 3.2.2 → 3.4.0

package/doc/user/api/recipe.md

@@ -0,0 +1,427 @@
+# 配方系统 API 参考
+
+---
+
+## RecipeAPI
+
+工厂函数集合，用于创建各类配方并自动注册到游戏系统。
+
+```typescript
+import { RecipeAPI, registry } from '@sapdon/core'
+```
+
+所有注册器方法均返回配方实例，支持链式调用。完成后调用 `registry.submit()` 提交数据。
+
+---
+
+### registerSimpleFurnace
+
+快速创建熔炉配方（自动设置 `furnace` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleFurnace(
+  identifier: string,
+  output: string,
+  input: string
+): AddonRecipeFurnace
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleFurnace('sapdon:smelt_ore', 'minecraft:iron_ingot', 'minecraft:iron_ore')
+```
+
+---
+
+### registerFurnace
+
+创建熔炉配方实例，返回 `AddonRecipeFurnace` 用于链式配置。
+
+```typescript
+RecipeAPI.registerFurnace(identifier: string): AddonRecipeFurnace
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerFurnace('sapdon:smelt_gold')
+  .input('minecraft:gold_ore', 0, 1)
+  .output('minecraft:gold_ingot')
+  .tags(['furnace'])
+```
+
+---
+
+### registerSimpleShaped
+
+快速创建有序工作台配方（自动设置 `crafting_table` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleShaped(
+  identifier: string,
+  output: string,
+  pattern: string[],
+  key: Record<string, any>
+): AddonRecipeShaped
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleShaped(
+  'sapdon:sword',
+  'sapdon:sword',
+  [' X ', ' X ', ' Y '],
+  { X: { item: 'minecraft:iron_ingot' }, Y: { item: 'minecraft:stick' } }
+)
+```
+
+---
+
+### registerShaped
+
+创建有序配方实例，返回 `AddonRecipeShaped` 用于链式配置。
+
+```typescript
+RecipeAPI.registerShaped(identifier: string): AddonRecipeShaped
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerShaped('sapdon:armor')
+  .key({ X: { item: 'minecraft:diamond' } })
+  .pattern(['XXX', 'X X', '   '])
+  .output({ item: 'sapdon:armor', count: 1 })
+  .tags(['crafting_table'])
+```
+
+---
+
+### registerSimpleShapeless
+
+快速创建无序工作台配方（自动设置 `crafting_table` 标签）。
+
+```typescript
+RecipeAPI.registerSimpleShapeless(
+  identifier: string,
+  output: string,
+  ingredients: any[]
+): AddonRecipeShapeless
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerSimpleShapeless(
+  'sapdon:alloy',
+  'sapdon:alloy_ingot',
+  [{ item: 'minecraft:iron_ingot' }, { item: 'minecraft:gold_ingot' }]
+)
+```
+
+---
+
+### registerShapeless
+
+创建无序配方实例，返回 `AddonRecipeShapeless` 用于链式配置。
+
+```typescript
+RecipeAPI.registerShapeless(identifier: string): AddonRecipeShapeless
+```
+
+**示例**
+
+```typescript
+RecipeAPI.registerShapeless('sapdon:mixture')
+  .ingredients([{ item: 'minecraft:diamond' }, { item: 'minecraft:emerald' }])
+  .output({ item: 'sapdon:mixture', count: 2 })
+  .tags(['crafting_table'])
+```
+
+---
+
+## AddonRecipe 基类
+
+所有配方类型继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipe } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `identifier(id: string)` | `this` | 设置配方标识符 |
+| `tags(tags: string[])` | `this` | 设置配方标签数组（覆盖） |
+| `getId(): string` | `string` | 获取配方标识符 |
+
+---
+
+## AddonRecipeShaped
+
+有序配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeShaped } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `assumeSymmetry(): void` | 无 | 启用对称假设，未定义键的字符自动视为相同 |
+| `key(key: Record<string, any>)` | `this` | 设置字符到物品的键映射 |
+| `pattern(pattern: string[])` | `this` | 设置 3 行图案数组 |
+| `priority(priority: number)` | `this` | 设置优先级（数值越小优先级越高） |
+| `output(item: string \| object)` | `this` | 设置输出，支持字符串或 `{ item, count }` |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeShaped_1_20()
+recipe
+  .identifier('sapdon:example')
+  .key({ A: { item: 'minecraft:iron_ingot' } })
+  .pattern(['AAA', 'A A', 'AAA'])
+  .output({ item: 'sapdon:example', count: 8 })
+  .assumeSymmetry()
+  .tags(['crafting_table'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeShaped_1_12` | `1.12` |
+| `AddonRecipeShaped_1_17` | `1.17` |
+| `AddonRecipeShaped_1_19` | `1.19` |
+| `AddonRecipeShaped_1_20` | `1.20` |
+
+---
+
+## AddonRecipeShapeless
+
+无序配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeShapeless } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `static create(ver, def)` | `AddonRecipeShapeless` | 静态工厂方法 |
+| `priority(priority: number)` | `this` | 设置优先级 |
+| `ingredients(ingredients: any[])` | `this` | 设置原料数组 |
+| `output(item: string \| object)` | `this` | 设置输出，支持字符串或 `{ item, count }` |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeShapeless_1_17()
+recipe
+  .identifier('sapdon:example')
+  .ingredients([
+    { item: 'minecraft:iron_ingot' },
+    { tag: 'minecraft:planks' }
+  ])
+  .output({ item: 'sapdon:example', count: 4 })
+  .tags(['crafting_table'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeShapeless_1_12` | `1.12` |
+| `AddonRecipeShapeless_1_17` | `1.17` |
+
+---
+
+## AddonRecipeFurnace
+
+熔炉配方类，继承自 `AddonRecipe`。
+
+```typescript
+import { AddonRecipeFurnace } from '@sapdon/core'
+```
+
+### 方法
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `static create(ver, def)` | `AddonRecipeFurnace` | 静态工厂方法 |
+| `input(item: string, data?, count?)` | `this` | 设置输入物品，可选副损伤值(data)和数量 |
+| `output(item: string)` | `this` | 设置输出物品 |
+| `tags(tags: string[])` | `this` | 继承自 `AddonRecipe`，设置配方标签 |
+
+**示例**
+
+```typescript
+const recipe = new AddonRecipeFurnace_1_17()
+recipe
+  .identifier('sapdon:smelt_ore')
+  .input('minecraft:iron_ore', 0)
+  .output('minecraft:iron_ingot')
+  .tags(['furnace'])
+```
+
+### 版本化类
+
+| 类 | format_version |
+|------|------|
+| `AddonRecipeFurnace_1_12` | `1.12` |
+| `AddonRecipeFurnace_1_17` | `1.17` |
+
+---
+
+## RecipeTags
+
+配方标签常量，用于指定配方适用的方块。
+
+```typescript
+import { RecipeTags } from '@sapdon/core'
+```
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `RecipeTags.Furnace` | `"furnace"` | 熔炉配方 |
+| `RecipeTags.smoker` | `"smoker"` | 烟熏炉配方 |
+| `RecipeTags.Campfire` | `"campfire"` | 篝火烹饪配方 |
+| `RecipeTags.SoulCampfire` | `"soul_campfire"` | 灵魂篝火烹饪配方 |
+| `RecipeTags.CraftingTable` | `"crafting_table"` | 工作台合成配方 |
+
+> 注意：`RecipeTags.smoker` 首字母小写，与其余常量命名不一致。
+
+**示例**
+
+```typescript
+// 同时适用于熔炉和烟熏炉
+recipe.tags([RecipeTags.Furnace, RecipeTags.smoker])
+```
+
+---
+
+## RecipeInputTags
+
+物品输入标签常量，用于原料的 `tag` 字段实现宽匹配。
+
+```typescript
+import { RecipeInputTags } from '@sapdon/core'
+```
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `RecipeInputTags.Armor` | `"minecraft:is_armor"` | 盔甲类物品 |
+| `RecipeInputTags.Arrows` | `"minecraft:arrow"` | 箭 |
+| `RecipeInputTags.Banners` | `"minecraft:banner"` | 旗帜 |
+| `RecipeInputTags.Boats` | `"minecraft:boats"` | 船 |
+| `RecipeInputTags.BookshelfBooks` | `"minecraft:bookshelf_books"` | 书架用书 |
+| `RecipeInputTags.ChainmailTier` | `"minecraft:chainmail_tier"` | 锁链级装备 |
+| `RecipeInputTags.ChestBoat` | `"minecraft:chest_boat"` | 带箱子的船 |
+| `RecipeInputTags.Coals` | `"minecraft:coals"` | 煤炭类 |
+| `RecipeInputTags.Cooked` | `"minecraft:is_cooked"` | 已烹饪食物 |
+| `RecipeInputTags.CrimsonStems` | `"minecraft:crimson_stems"` | 绯红菌柄 |
+| `RecipeInputTags.DiamondTier` | `"minecraft:diamond_tier"` | 钻石级装备 |
+| `RecipeInputTags.Digger` | `"minecraft:digger"` | 挖掘工具 |
+| `RecipeInputTags.Door` | `"minecraft:door"` | 门 |
+| `RecipeInputTags.Fish` | `"minecraft:is_fish"` | 鱼类 |
+| `RecipeInputTags.Food` | `"minecraft:is_food"` | 食物类 |
+| `RecipeInputTags.GoldenTier` | `"minecraft:golden_tier"` | 金质装备 |
+| `RecipeInputTags.HangingActor` | `"minecraft:hanging_actor"` | 悬挂实体 |
+| `RecipeInputTags.HangingSign` | `"minecraft:hanging_sign"` | 悬挂告示牌 |
+| `RecipeInputTags.Hatchet` | `"minecraft:is_axe"` | 斧 |
+| `RecipeInputTags.Hoe` | `"minecraft:is_hoe"` | 锄 |
+| `RecipeInputTags.HorseArmor` | `"minecraft:horse_armor"` | 马铠 |
+| `RecipeInputTags.IronTier` | `"minecraft:iron_tier"` | 铁质装备 |
+| `RecipeInputTags.LeatherTier` | `"minecraft:leather_tier"` | 皮革装备 |
+| `RecipeInputTags.LecternBooks` | `"minecraft:lectern_books"` | 讲台用书 |
+| `RecipeInputTags.Logs` | `"minecraft:logs"` | 原木类 |
+| `RecipeInputTags.LogsThatBurn` | `"minecraft:logs_that_burn"` | 可燃原木 |
+| `RecipeInputTags.MangroveLogs` | `"minecraft:mangrove_logs"` | 红树木 |
+| `RecipeInputTags.Meat` | `"minecraft:is_meat"` | 肉类 |
+| `RecipeInputTags.Minecart` | `"minecraft:is_minecart"` | 矿车 |
+| `RecipeInputTags.MusicDiscs` | `"minecraft:music_disc"` | 唱片 |
+| `RecipeInputTags.NetheriteTier` | `"minecraft:netherite_tier"` | 下界合金级装备 |
+| `RecipeInputTags.Pickaxe` | `"minecraft:is_pickaxe"` | 镐 |
+| `RecipeInputTags.PiglinLoved` | `"minecraft:piglin_loved"` | 猪灵喜爱物品 |
+| `RecipeInputTags.PiglinRepellents` | `"minecraft:piglin_repellents"` | 猪灵驱退物品 |
+| `RecipeInputTags.Planks` | `"minecraft:planks"` | 木板 |
+| `RecipeInputTags.Sand` | `"minecraft:sand"` | 沙子 |
+| `RecipeInputTags.Shovel` | `"minecraft:is_shovel"` | 锹 |
+| `RecipeInputTags.Sign` | `"minecraft:sign"` | 告示牌 |
+| `RecipeInputTags.SoulFireBaseBlocks` | `"minecraft:soul_fire_base_blocks"` | 灵魂火基底 |
+| `RecipeInputTags.SpawnEgg` | `"minecraft:spawn_egg"` | 刷怪蛋 |
+| `RecipeInputTags.StoneBricks` | `"minecraft:stone_bricks"` | 石砖 |
+| `RecipeInputTags.StoneCraftingMaterials` | `"minecraft:stone_crafting_materials"` | 石质合成材料 |
+| `RecipeInputTags.StoneTier` | `"minecraft:stone_tier"` | 石质装备 |
+| `RecipeInputTags.StoneToolMaterials` | `"minecraft:stone_tool_materials"` | 石质工具材料 |
+| `RecipeInputTags.Sword` | `"minecraft:is_sword"` | 剑 |
+| `RecipeInputTags.Tool` | `"minecraft:is_tool"` | 工具 |
+| `RecipeInputTags.VibrationDamper` | `"minecraft:vibration_damper"` | 振动阻尼 |
+| `RecipeInputTags.WarpedStems` | `"minecraft:warped_stems"` | 诡异菌柄 |
+| `RecipeInputTags.WoodenSlabs` | `"minecraft:wooden_slabs"` | 木台阶 |
+| `RecipeInputTags.WoodenTier` | `"minecraft:wooden_tier"` | 木质装备 |
+| `RecipeInputTags.Wool` | `"minecraft:wool"` | 羊毛 |
+
+**示例**
+
+```typescript
+import { RecipeAPI, registry, RecipeInputTags } from '@sapdon/core'
+
+// 使用标签匹配所有木板
+RecipeAPI.registerShapeless('sapdon:framed_plank')
+  .ingredients([
+    { tag: RecipeInputTags.Planks },
+    { tag: RecipeInputTags.Planks },
+    { tag: RecipeInputTags.Planks }
+  ])
+  .output('sapdon:framed_plank')
+  .tags(['crafting_table'])
+```
+
+---
+
+## 类型汇总
+
+```typescript
+// 工厂
+RecipeAPI.registerSimpleFurnace(id, output, input)
+RecipeAPI.registerFurnace(id)
+RecipeAPI.registerSimpleShaped(id, output, pattern, key)
+RecipeAPI.registerShaped(id)
+RecipeAPI.registerSimpleShapeless(id, output, ingredients)
+RecipeAPI.registerShapeless(id)
+
+// 有序配方
+class AddonRecipeShaped extends AddonRecipe
+  assumeSymmetry(): void
+  key(map): this
+  pattern(rows): this
+  priority(num): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 无序配方
+class AddonRecipeShapeless extends AddonRecipe
+  priority(num): this
+  ingredients(items): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 熔炉配方
+class AddonRecipeFurnace extends AddonRecipe
+  input(item, data?, count?): this
+  output(item): this
+  tags(tags[]): this  // 继承
+
+// 标签常量
+RecipeTags = { Furnace, smoker, Campfire, SoulCampfire, CraftingTable }
+RecipeInputTags = { Armor, Food, Logs, Planks, ... }
+```

package/doc/user/api/sapdon-ui.md

@@ -0,0 +1,185 @@
+# Sapdon UI 页面壳系统 API 参考
+
+Sapdon UI 是一套「sapdon_ui: 前缀标题路由 + 页面壳」的自定义 Server Form UI 系统。它用 TypeScript 声明式生成 `server_form.json` 路由结构与每个页面的独立 UI 文件，运行时通过 `ActionFormData` 的 title 前缀自动分流：`sapdon_ui:` 开头的标题渲染自定义全屏 UI，其它标题走原版原生表单。
+
+---
+
+## 目录
+
+1. [架构总览](#1-架构总览)
+2. [SapdonServerUI 类](#2-sapdonserverui-类)
+3. [SapdonPanel 类](#3-sapdonpanel-类)
+4. [SapdonButtonPanel 类](#4-sapdonbuttonpanel-类)
+5. [SapdonButton 类](#5-sapdonbutton-类)
+6. [运行时触发](#6-运行时触发)
+7. [已知注意点](#7-已知注意点)
+
+---
+
+## 1. 架构总览
+
+### 生成的文件（`registry.submit()` 后）
+
+| 文件 | 内容 |
+|------|------|
+| `ui/server_form.json` | 路由壳：屏幕、native/自定义分流、页面壳 `custom_panel_content`、按钮模板 `form_button` |
+| `ui/sapdon_ui_xxx.json` | 每个页面一个独立文件（内容面板 + 按键面板） |
+| `ui/_ui_defs.json` | 自动登记所有 UI 文件 |
+
+### 路由结构
+
+```
+third_party_server_screen@common.base_screen   (type: screen)
+└─ $screen_content = custom_full_screen
+   ├─ native_form@main_screen_content
+   │     visible = title 不含 'sapdon_ui:'
+   └─ sapdon_custom_full@sapdon_screen_content
+         visible = title 含 'sapdon_ui:'
+         └─ (每个注册页) @custom_panel_content   ← $panel_id 精确匹配 title
+              ├─ content@$user_content_panel    (下)
+              └─ buttons@$user_buttons_panel    (上, 后绘制覆盖)
+```
+
+### 脚本 ↔ JSON UI 绑定
+
+| ActionForm API | JSON UI 变量 | 说明 |
+|----------------|-------------|------|
+| `.title("sapdon_ui:xxx")` | `#title_text` | 前缀 `sapdon_ui:` = 自定义；`$panel_id` 精确匹配页面 |
+| `.button("text")` | `#form_button_*` | 集合 `form_buttons`，网格按放置顺序绑定各按钮数据 |
+
+---
+
+## 2. SapdonServerUI 类
+
+负责生成 `server_form.json` 的完整路由壳（屏幕、分流、页面壳、form_button 模板），并提供页面注册入口。
+
+```typescript
+import { SapdonServerUI } from '@sapdon/core'
+
+SapdonServerUI.registerPage({
+    panelId: "sapdon_ui:apple",          // title 精确匹配值（必须 sapdon_ui: 前缀）
+    name: "apple",                        // 页面控件名（默认 pageN）
+    contentPanel: "sapdon_ui_apple.apple_content_panel",  // 内容面板引用
+    buttonsPanel: "sapdon_ui_apple.apple_buttons_panel",  // 按键面板引用（可选）
+})
+```
+
+### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `panelId` | `string` | ✅ | 触发此页的 ActionForm title（须含 `sapdon_ui:` 前缀） |
+| `contentPanel` | `UIElement \| string` | ✅ | 内容面板元素或 `ns.name` 引用 |
+| `buttonsPanel` | `UIElement \| string` | ❌ | 按键面板元素或引用（壳固定渲染，缺省会报引用缺失，纯内容页请传空面板） |
+| `name` | `string` | ❌ | 注册在 `sapdon_screen_content` 里的控件名 |
+
+### 自动生成的内容
+
+- `third_party_server_screen@common.base_screen`：`$screen_content` 指向 `custom_full_screen`，附带退出动画抑制与 `menu_cancel → menu_exit` 映射。
+- `custom_full_screen`：`native_form`（`((#title_text - 'sapdon_ui:') = #title_text)` → 非自定义显示）与 `sapdon_screen_content`（取反）分流。
+- `sapdon_screen_content`：`sapdon_ui:` 前缀可见，承载所有注册页。
+- `custom_panel_content`：通用页面壳，`(#title_text = $panel_id)` 精确匹配，内容(下)+按键(上)两块。
+- `form_button@common_buttons.light_text_button`：框架固定提供的表单按钮模板（16×16，集合绑定 `form_buttons`）。
+
+---
+
+## 3. SapdonPanel 类
+
+每个页面一个独立 UI 文件。把「内容面板 + 按键面板」组装进该页面的命名空间。
+
+```typescript
+import { SapdonPanel } from '@sapdon/core'
+
+new SapdonPanel("sapdon_ui_apple")      // 生成 ui/sapdon_ui_apple.json (ns: sapdon_ui_apple)
+    .setContent(contentPanel)            // 内容面板 UIElement
+    .setButtons(buttonsPanel)            // 按键面板 UIElement
+    .build()
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setContent(panel)` | 设置内容面板元素（必须是 UIElement，其 id 即 `ns.xxx` 引用名） |
+| `setButtons(panel)` | 设置按键面板元素 |
+| `build()` | 返回生成的 `UISystem` |
+
+> 页面的内容/按键面板元素 id 会作为 `registerPage` 里 `contentPanel`/`buttonsPanel` 的引用名，例如 `new Panel("apple_content_panel")` → `"sapdon_ui_apple.apple_content_panel"`。
+
+---
+
+## 4. SapdonButtonPanel 类
+
+构建按键网格面板（grid）。网格通过 `collection_name: form_buttons` 提供每项数据上下文，`place()` 把按钮按 `grid_position` 摆到指定格（内部即 pos_wrap：面板包裹 + `grid_position`）。
+
+```typescript
+import { SapdonButtonPanel, SapdonButton } from '@sapdon/core'
+
+const buttons = new SapdonButtonPanel("apple_buttons_panel")
+    .setDimensions([2, 1])                       // [列, 行]
+    .setCollection("form_buttons")               // 注入表单按钮集合
+    .setSize(["100%", "100%"])
+    .place([0, 0], new SapdonButton("bt0").setAnchor("bottom_left"))
+    .place([1, 0], new SapdonButton("bt1").setAnchor("bottom_right"))
+    .build()
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setDimensions([cols, rows])` | 网格尺寸（**列 × 行**） |
+| `setCollection(name)` | 注入集合（表单场景固定 `form_buttons`） |
+| `setSize(size)` | 网格尺寸 |
+| `place([col, row], element)` | 摆一个按钮/控件到指定格（自动包一层 pos_wrap） |
+| `build()` | 返回 `Grid` |
+
+> **布局技巧**：`grid_dimensions [2,1]` 把面板切成左右两份；格子内控件默认左上对齐，改锚点 `bottom_left` / `bottom_right` / `top_right` 即可把按钮贴到对应角。
+
+---
+
+## 5. SapdonButton 类
+
+表单按钮的封装：默认模板固定为 `server_form.form_button`（吃 `form_buttons` 集合数据），无需手写模板引用。
+
+```typescript
+import { SapdonButton } from '@sapdon/core'
+
+new SapdonButton("bt0")                 // → bt0@server_form.form_button
+    .setAnchor("bottom_left")           // 锚点对齐，默认 32×32
+```
+
+| 方法 | 说明 |
+|------|------|
+| `setAnchor(anchor)` | 设置 `anchor_from`/`anchor_to` 对齐（如 `bottom_left`、`bottom_right`、`top_right`），默认尺寸 32×32 |
+
+> 右上角的「退出」这类非集合按钮，请用普通 `Button("exit", "common.button")` + `$pressed_button_name: "button.menu_exit"` 手写，不占用表单按钮集合。
+
+---
+
+## 6. 运行时触发
+
+```typescript
+import { world } from "@minecraft/server"
+import { ActionFormData } from "@minecraft/server-ui"
+
+world.afterEvents.itemUse.subscribe((event) => {
+    if (event.itemStack.typeId == "minecraft:apple") {
+        new ActionFormData()
+            .title("sapdon_ui:apple")          // 前缀路由 → 自定义页
+            .body("...")
+            .button("test1").button("test2")   // 喂给集合 form_buttons
+            .show(event.source)
+    }
+})
+```
+
+- title 含 `sapdon_ui:` → 自定义全屏 UI；否则原版原生表单。
+- 自定义页内的按钮点击通过 `button.form_button_click` 返回 `response.selection`（对应集合下标）。
+
+---
+
+## 7. 已知注意点
+
+1. **`grid_position` 顺序**：本项目约定为 `[列, 行]`（与 `grid_dimensions [列, 行]` 一致）。
+2. **grid 内 `offset` 无效**：网格接管子控件定位；要偏移请包一层 panel（pos_wrap），offset 放内层。
+3. **`collection_index` 不是合法 UI 属性**：引擎会报 `Unknown property [collection_index]`。每个按钮对应哪个表单按钮，靠 grid 的集合上下文按放置顺序确定，不要用 `collection_index`。
+4. **壳固定渲染 content+buttons 两块**：纯内容页也必须提供一个（空的）按键面板，否则 `$user_buttons_panel` 引用缺失报错。
+5. **grid 数量绑定**：`#maximum_grid_items` 需 int（用 `#form_button_length`）；collection_panel 才用数组 `#form_button_contents` → `#collection_length`。
+6. **裸引用**：页面壳里的 `content@$user_content_panel` / `buttons@$user_buttons_panel` 必须是裸引用（不带 `type`），否则网格类型被覆盖导致 `grid_dimensions`/`grid_position` 报未知属性。