@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/schema/catalog.ts

@@ -0,0 +1,300 @@
+/**
+ * op 目录：op 标签/分组（含分组顺序与中文标签，单一事实源）+ 字段呈现语义（label/kind）。
+ * 字段的类型/必填/可选值/默认值以 opSchemas（Zod）为唯一事实源——本文件只承载
+ * 呈现与诊断语义元数据，字段名集合与 schema 由互锁测试锁定（schema.test.ts）。
+ * 字段语义以执行器为权威（packages/core/src/runtime/ops/）。
+ */
+
+import type { FieldKind, OpGroup, OpMeta } from "../contracts/index.ts";
+
+/**
+ * op 分组顺序（与时间线插入菜单一致）。
+ *
+ * 放在本数据叶子里：`surface`（扩展 op 归组校验）与 `elementPalette`（分组渲染）
+ * 都要取用，两者又分处依赖链两端。
+ */
+export const OP_GROUP_ORDER: readonly OpGroup[] = [
+  "narrative",
+  "presentation",
+  "flow",
+  "variables",
+  "save",
+  "audio",
+  "video",
+  "minigame",
+];
+
+/** op 分组中文标签（单一事实源） */
+export const OP_GROUP_LABELS: Readonly<Record<OpGroup, string>> = {
+  narrative: "叙事",
+  presentation: "表现",
+  flow: "流程",
+  variables: "变量",
+  save: "存档",
+  audio: "音频",
+  video: "视频",
+  minigame: "小游戏",
+};
+
+export const OP_META: readonly OpMeta[] = [
+  { op: "say", label: "对话", group: "narrative" },
+  { op: "menu", label: "选项", group: "narrative" },
+  { op: "input", label: "输入", group: "narrative" },
+  { op: "notify", label: "通知", group: "narrative" },
+  { op: "nvl", label: "NVL 模式", group: "presentation" },
+  { op: "character", label: "角色定义", group: "presentation" },
+  { op: "uncharacter", label: "角色注销", group: "presentation" },
+  { op: "wait", label: "等待", group: "flow" },
+  { op: "pause", label: "暂停", group: "flow" },
+  { op: "random", label: "随机数", group: "flow" },
+  { op: "jump", label: "跳转", group: "flow" },
+  { op: "navigate", label: "导航", group: "flow" },
+  { op: "func", label: "函数定义", group: "flow" },
+  { op: "call", label: "调用函数", group: "flow" },
+  { op: "return", label: "函数返回", group: "flow" },
+  { op: "if", label: "条件分支", group: "flow" },
+  { op: "while", label: "循环", group: "flow" },
+  { op: "for", label: "遍历循环", group: "flow" },
+  { op: "foreach", label: "集合迭代", group: "flow" },
+  { op: "switch", label: "多路分支", group: "flow" },
+  { op: "break", label: "跳出循环", group: "flow" },
+  { op: "continue", label: "下一轮循环", group: "flow" },
+  { op: "assert", label: "断言校验", group: "flow" },
+  { op: "guard", label: "守卫校验", group: "flow" },
+  { op: "set", label: "赋值", group: "variables" },
+  { op: "define", label: "全局定义", group: "variables" },
+  { op: "let", label: "块级变量", group: "variables" },
+  { op: "local", label: "块级变量", group: "variables" },
+  { op: "undef", label: "销毁变量", group: "variables" },
+  { op: "array", label: "数组定义", group: "variables" },
+  { op: "array_push", label: "数组追加", group: "variables" },
+  { op: "array_pop", label: "数组弹出", group: "variables" },
+  { op: "dict", label: "字典定义", group: "variables" },
+  { op: "dict_set", label: "字典写入", group: "variables" },
+  { op: "save", label: "存档", group: "save" },
+  { op: "load", label: "读档", group: "save" },
+  { op: "auto_save", label: "自动存档开关", group: "save" },
+  { op: "save_delete", label: "删除存档", group: "save" },
+  { op: "bgm", label: "背景乐", group: "audio" },
+  { op: "stop_bgm", label: "停止背景乐", group: "audio" },
+  { op: "se", label: "音效", group: "audio" },
+  { op: "ambient", label: "环境音", group: "audio" },
+  { op: "stop_ambient", label: "停止环境音", group: "audio" },
+  { op: "voice", label: "语音", group: "audio" },
+  { op: "stop_voice", label: "停止语音", group: "audio" },
+  { op: "video", label: "视频", group: "video" },
+  { op: "cutscene", label: "过场", group: "video" },
+  { op: "seek_video", label: "视频跳转", group: "video" },
+  { op: "pause_video", label: "视频暂停", group: "video" },
+  { op: "resume_video", label: "视频恢复", group: "video" },
+  { op: "stop_video", label: "停止视频", group: "video" },
+  { op: "video_skipable", label: "视频可跳开关", group: "video" },
+  { op: "minigame", label: "小游戏", group: "minigame" },
+  { op: "interaction", label: "玩法系统接管", group: "minigame" },
+  // 元素系统
+  { op: "show", label: "显示元素", group: "presentation" },
+  { op: "hide", label: "隐藏元素", group: "presentation" },
+  { op: "background", label: "设置背景", group: "presentation" },
+  { op: "bg_switch", label: "切换背景", group: "presentation" },
+  { op: "zindex", label: "调整层级", group: "presentation" },
+  { op: "style", label: "元素样式", group: "presentation" },
+  { op: "window", label: "对话框显隐", group: "presentation" },
+  { op: "animate", label: "元素动画", group: "presentation" },
+  { op: "animate_block", label: "多属性动画", group: "presentation" },
+  { op: "transition", label: "转场", group: "presentation" },
+  { op: "shake", label: "屏幕震动", group: "presentation" },
+  { op: "text_typewriter", label: "打字机设置", group: "presentation" },
+];
+
+interface FieldMeta {
+  label: string;
+  kind: FieldKind;
+}
+
+/**
+ * 字段元数据：键 = `<op>.<字段路径>`；嵌套项内字段以 `[]` 标注项路径
+ * （如 menu.options[].text）。kind 语义见 contracts/forms.ts FieldKind。
+ */
+export const FIELD_META: Readonly<Record<string, FieldMeta>> = {
+  "say.text": { label: "文本", kind: "text" },
+  "say.speaker": { label: "说话人", kind: "text" },
+  // 说话人颜色**覆盖**（本句有效，优先于 character 定义的颜色）；十六进制
+  "say.color": { label: "说话人颜色（本句）", kind: "text" },
+  // 本句字体覆盖（字体名 = Resources/Fonts 文件名去扩展名；优先于角色/列级字体）
+  "say.font": { label: "本句字体", kind: "string" },
+  "say.clickable": { label: "点击后继续", kind: "boolean" },
+  "say.noskip": { label: "禁止跳过", kind: "boolean" },
+  "say.instant": { label: "瞬间显示", kind: "boolean" },
+  "say.typewriter": { label: "打字机速度", kind: "number" },
+  "say.voice": { label: "本句语音", kind: "resource" },
+  "say.template": { label: "对话框模板", kind: "string" },
+  "say.z": { label: "层级（实例）", kind: "number" },
+  "menu.prompt": { label: "提示语", kind: "text" },
+  "menu.options": { label: "选项", kind: "array" },
+  "menu.options[].text": { label: "选项文本", kind: "text" },
+  "menu.options[].target": { label: "目标列", kind: "identifier" },
+  "menu.z": { label: "层级（实例）", kind: "number" },
+  "input.prompt": { label: "提示语", kind: "text" },
+  "input.store": { label: "存入变量", kind: "identifier" },
+  "input.z": { label: "层级（实例）", kind: "number" },
+  "notify.text": { label: "文本", kind: "text" },
+  "notify.type": { label: "类型", kind: "string" },
+  "notify.duration": { label: "时长（毫秒）", kind: "number" },
+  "notify.z": { label: "层级（实例）", kind: "number" },
+  "nvl.mode": { label: "模式", kind: "enum" },
+  "character.key": { label: "角色键", kind: "identifier" },
+  "character.name": { label: "显示名", kind: "text" },
+  "character.color": { label: "颜色", kind: "string" },
+  "character.size": { label: "字号", kind: "string" },
+  "character.font": { label: "字体", kind: "string" },
+  "character.textColor": { label: "文字颜色", kind: "string" },
+  "character.screen": { label: "对话框模板", kind: "string" },
+  "uncharacter.key": { label: "角色键", kind: "identifier" },
+  "wait.seconds": { label: "秒数", kind: "number" },
+  "wait.skipable": { label: "可跳过", kind: "boolean" },
+  "pause.seconds": { label: "秒数", kind: "number" },
+  "random.seed": { label: "种子", kind: "integer" },
+  "random.range": { label: "范围 [min, max]", kind: "tuple" },
+  "random.var": { label: "写入变量", kind: "identifier" },
+  "jump.target": { label: "目标列", kind: "identifier" },
+  "navigate.path": { label: "路径/列", kind: "identifier" },
+  "navigate.scene": { label: "场景列", kind: "identifier" },
+  "func.name": { label: "函数名", kind: "identifier" },
+  "func.params": { label: "形参", kind: "array" },
+  "func.body": { label: "函数体", kind: "body" },
+  "call.target": { label: "函数名", kind: "identifier" },
+  "call.args": { label: "实参", kind: "array" },
+  "call.into": { label: "结果绑定名", kind: "identifier" },
+  "return.value": { label: "返回值", kind: "value" },
+  "if.cond": { label: "条件", kind: "expression" },
+  "if.then": { label: "则", kind: "body" },
+  "if.elif": { label: "否则如果", kind: "array" },
+  "if.elif[].cond": { label: "条件", kind: "expression" },
+  "if.elif[].then": { label: "则", kind: "body" },
+  "if.else": { label: "否则", kind: "body" },
+  "while.cond": { label: "条件", kind: "expression" },
+  "while.body": { label: "循环体", kind: "body" },
+  "assert.cond": { label: "断言条件", kind: "expression" },
+  "assert.message": { label: "失败提示", kind: "text" },
+  "guard.fn": { label: "守卫名", kind: "identifier" },
+  "guard.args": { label: "参数", kind: "object" },
+  "for.var": { label: "循环变量", kind: "identifier" },
+  "for.in": { label: "序列表达式", kind: "expression" },
+  "for.body": { label: "循环体", kind: "body" },
+  "foreach.var": { label: "元素变量", kind: "identifier" },
+  "foreach.key": { label: "集合变量", kind: "identifier" },
+  "foreach.body": { label: "循环体", kind: "body" },
+  "switch.on": { label: "分支表达式", kind: "expression" },
+  "switch.cases": { label: "分支", kind: "array" },
+  "switch.cases[].value": { label: "匹配值", kind: "value" },
+  "switch.cases[].body": { label: "分支体", kind: "body" },
+  "switch.default": { label: "缺省分支", kind: "body" },
+  "set.key": { label: "变量名", kind: "identifier" },
+  "set.value": { label: "值", kind: "value" },
+  "define.key": { label: "变量名", kind: "identifier" },
+  "define.value": { label: "值", kind: "value" },
+  "let.key": { label: "变量名", kind: "identifier" },
+  "let.value": { label: "值", kind: "value" },
+  "local.key": { label: "变量名", kind: "identifier" },
+  "local.value": { label: "值", kind: "value" },
+  "undef.key": { label: "变量名", kind: "identifier" },
+  "array.key": { label: "变量名", kind: "identifier" },
+  "array.items": { label: "初始项", kind: "array" },
+  "array.once": { label: "已存在时跳过", kind: "boolean" },
+  "array_push.key": { label: "目标数组", kind: "identifier" },
+  "array_push.value": { label: "值", kind: "value" },
+  "array_pop.key": { label: "目标数组", kind: "identifier" },
+  "dict.key": { label: "变量名", kind: "identifier" },
+  "dict.value": { label: "初始字段", kind: "object" },
+  "dict.once": { label: "已存在时跳过", kind: "boolean" },
+  "dict_set.key": { label: "目标字典", kind: "identifier" },
+  "dict_set.field": { label: "字段名", kind: "identifier" },
+  "dict_set.value": { label: "值", kind: "value" },
+  "save.slot": { label: "槽位", kind: "identifier" },
+  "save.title": { label: "标题", kind: "text" },
+  "load.slot": { label: "槽位", kind: "identifier" },
+  "auto_save.enabled": { label: "启用", kind: "boolean" },
+  "save_delete.slot": { label: "槽位", kind: "identifier" },
+  "bgm.resource": { label: "资源", kind: "resource" },
+  "bgm.volume": { label: "音量", kind: "number" },
+  "bgm.loop": { label: "循环", kind: "boolean" },
+  "bgm.fade": { label: "淡入（毫秒）", kind: "number" },
+  "bgm.restart": { label: "回起点重播", kind: "boolean" },
+  "stop_bgm.fade": { label: "淡出（毫秒）", kind: "number" },
+  "se.resource": { label: "资源", kind: "resource" },
+  "se.volume": { label: "音量", kind: "number" },
+  "ambient.resource": { label: "资源", kind: "resource" },
+  "ambient.volume": { label: "音量", kind: "number" },
+  "ambient.loop": { label: "循环", kind: "boolean" },
+  "ambient.fade": { label: "淡入（毫秒）", kind: "number" },
+  "ambient.restart": { label: "回起点重播", kind: "boolean" },
+  "stop_ambient.fade": { label: "淡出（毫秒）", kind: "number" },
+  "voice.resource": { label: "资源", kind: "resource" },
+  "voice.volume": { label: "音量", kind: "number" },
+  "voice.auto_stop": { label: "推进即停", kind: "boolean" },
+  "voice.restart": { label: "回起点重播", kind: "boolean" },
+  "stop_voice.fade": { label: "淡出（毫秒）", kind: "number" },
+  "video.resource": { label: "资源", kind: "resource" },
+  "video.volume": { label: "音量", kind: "number" },
+  "video.loop": { label: "循环", kind: "boolean" },
+  "video.z": { label: "层级（实例）", kind: "number" },
+  "cutscene.resource": { label: "资源", kind: "resource" },
+  "cutscene.volume": { label: "音量", kind: "number" },
+  "cutscene.skipable": { label: "可跳过", kind: "boolean" },
+  "cutscene.z": { label: "层级（实例）", kind: "number" },
+  "seek_video.seconds": { label: "目标秒数", kind: "number" },
+  "video_skipable.value": { label: "启用", kind: "boolean" },
+  "minigame.game": { label: "游戏 ID", kind: "identifier" },
+  "minigame.config": { label: "配置", kind: "object" },
+  "minigame.on_success": { label: "成功跳转列", kind: "identifier" },
+  "minigame.on_fail": { label: "失败跳转列", kind: "identifier" },
+  "minigame.reward": { label: "奖励", kind: "array" },
+  "minigame.reward[].key": { label: "奖励变量", kind: "identifier" },
+  "minigame.reward[].value": { label: "奖励值", kind: "value" },
+  "minigame.z": { label: "层级（实例）", kind: "number" },
+  "interaction.system": { label: "玩法系统标识", kind: "identifier" },
+  "interaction.config": { label: "配置", kind: "object" },
+  "interaction.on_success": { label: "成功跳转列", kind: "identifier" },
+  "interaction.on_fail": { label: "失败跳转列", kind: "identifier" },
+  "interaction.z": { label: "层级（实例）", kind: "number" },
+  // —— 元素增删改 ——
+  "show.target": { label: "资源路径", kind: "resource" },
+  "show.x": { label: "X（数字或 CSS 长度）", kind: "string" },
+  "show.y": { label: "Y（数字或 CSS 长度）", kind: "string" },
+  "show.id": { label: "元素 id", kind: "identifier" },
+  "show.name": { label: "分组名", kind: "identifier" },
+  "show.background": { label: "作为背景（底层）", kind: "boolean" },
+  "hide.target": { label: "目标（id / 分组 / 资源）", kind: "identifier" },
+  "background.resource": { label: "资源", kind: "resource" },
+  "bg_switch.resource": { label: "资源", kind: "resource" },
+  "zindex.target": { label: "目标元素", kind: "identifier" },
+  "zindex.value": { label: "层级", kind: "number" },
+  "style.target": { label: "目标元素", kind: "identifier" },
+  "style.props": { label: "样式属性", kind: "object" },
+  "window.mode": { label: "模式", kind: "enum" },
+  // —— 帧驱动表现 ——
+  "animate.target": { label: "目标元素", kind: "identifier" },
+  "animate.property": { label: "属性名", kind: "string" },
+  "animate.value": { label: "目标值", kind: "number" },
+  "animate.duration": { label: "时长（秒）", kind: "number" },
+  "animate.easing": { label: "缓动", kind: "string" },
+  "animate_block.target": { label: "目标元素", kind: "identifier" },
+  "animate_block.x": { label: "X", kind: "number" },
+  "animate_block.y": { label: "Y", kind: "number" },
+  "animate_block.opacity": { label: "不透明度", kind: "number" },
+  "animate_block.rotation": { label: "旋转（度）", kind: "number" },
+  "animate_block.scale": { label: "缩放", kind: "number" },
+  "animate_block.duration": { label: "时长（秒）", kind: "number" },
+  "animate_block.easing": { label: "缓动", kind: "string" },
+  "transition.type": { label: "效果名", kind: "string" },
+  "transition.duration": { label: "时长（秒）", kind: "number" },
+  "shake.intensity": { label: "强度", kind: "number" },
+  "shake.duration": { label: "时长（秒）", kind: "number" },
+  "text_typewriter.enabled": { label: "启用", kind: "boolean" },
+  "text_typewriter.speed": { label: "速度（字符/秒）", kind: "number" },
+};
+
+/** 文本插值面（诊断扫描用）：text kind 字段集合的查询入口 */
+export function fieldMetaOf(key: string): FieldMeta | undefined {
+  return FIELD_META[key];
+}

package/src/schema/elementForms.ts

@@ -0,0 +1,307 @@
+/**
+ * 舞台编辑：元素属性表单描述符（**契约驱动**）。
+ *
+ * 元素不是 op（无 op schema），字段面直接取自引擎元素契约（单一事实源）：
+ * - `ELEMENT_TYPES`（36 类型）
+ * - `ELEMENT_ATTRIBUTES`（通用属性全集）
+ * - `ELEMENT_SPECIFIC_ATTRS`（分类型属性，供高亮）
+ *
+ * 产出的 `FieldDescriptor` 与 op 表单同构 → 舞台编辑可直接复用 `FieldRow`。
+ */
+import type { FieldDescriptor, FieldKind } from "../contracts/index.ts";
+import {
+  ELEMENT_ATTRIBUTES,
+  ELEMENT_SPECIFIC_ATTRS,
+  ELEMENT_TYPES,
+} from "@lingfan-engine/core";
+
+/** 36 类型中文标签（新建菜单与画布角标） */
+const ELEMENT_LABELS: Readonly<Record<string, string>> = {
+  text: "文本",
+  dialog: "对话窗",
+  narrator: "旁白",
+  speaker: "说话人",
+  button: "按钮",
+  choice: "选项",
+  imagebutton: "图像按钮",
+  image: "图片",
+  background: "背景",
+  portrait: "立绘",
+  video: "视频",
+  panel: "面板",
+  frame: "框架",
+  window: "窗口",
+  dialogbox: "对话框",
+  choicebox: "选项框",
+  infobox: "信息框",
+  overlay: "遮罩",
+  popup: "浮窗",
+  vbox: "纵排",
+  hbox: "横排",
+  grid: "网格",
+  stack: "堆叠",
+  stackpanel: "堆叠面板",
+  canvas: "画布",
+  border: "边框",
+  scroll: "滚动",
+  scrollviewer: "滚动视图",
+  viewport: "视口",
+  bar: "进度条",
+  vbar: "纵向进度条",
+  progressbar: "进度条",
+  slider: "滑块",
+  checkbox: "复选框",
+  separator: "分隔线",
+  spacer: "留白",
+};
+
+/**
+ * 已声明但**当前无渲染语义**的属性（未实现属性清单：先保留解析、补实现按需）。
+ *
+ * 判定依据（代码事实）：这些键只在 `contracts/element.ts` 的 `ELEMENT_ATTRIBUTES` 里声明，
+ * `packages/ui` **零消费**（`elementStyle` / `renderers` 都不读）——写进故事**不生效也不报错**。
+ *
+ * 处置三条：① **保留在契约里**（`ELEMENT_ATTRIBUTES` 不动，避免历史工程解析失败）；
+ * ② **表单不下发**（`describeElement` 过滤掉，不再给作者"看起来能用"的控件）；
+ * ③ **编辑期 warning**（诊断码 `unimplemented-element-attr`）。
+ *
+ * 与「三面对齐互锁」测试的关系：该测试独立推导"契约 − 消费者"的差集，本清单是它的**显式白名单**，
+ * 两边不一致即测试变红（缺了「同时看这三面」的测试，这类差集就会长期潜伏）。
+ */
+export const UNIMPLEMENTED_ELEMENT_ATTRS: ReadonlySet<string> = new Set([
+  "valign",
+  "xalign",
+  "yalign",
+  // 例外：order 不是死属性——引擎装载期在用（z 兜底：
+  // packages/core/src/data/element.ts:157、runtime/internal/frame-stack.ts:62 消费）。
+  // 保留本条仅为维持现状行为（编辑器表单不下发 + unimplemented-element-attr warning +
+  // 互锁白名单 attr-alignment.test.ts），即「编辑器表单不暴露但引擎装载在用」。
+  "order",
+  "xoffset",
+  "yoffset",
+  "xanchor",
+  "yanchor",
+  // 互锁建立时反向逮出的一条：`image`/`imagebutton`/`portrait` 有表单
+  // （「拉伸方式」）但 `packages/ui` 零消费——这类差集须从契约全集反推
+  // 才能逮出，互锁测试从此守着这个洞。
+  "stretch",
+]);
+
+/** 属性 → 呈现语义（未列出者回退 `string`） */
+const ELEMENT_FIELD_META: Readonly<
+  Record<string, { label: string; kind: FieldKind }>
+> = {
+  id: { label: "元素 id", kind: "identifier" },
+  name: { label: "分组名", kind: "identifier" },
+  class: { label: "样式类", kind: "string" },
+  style: { label: "样式类（别名）", kind: "string" },
+  source: { label: "资源路径", kind: "resource" },
+  src: { label: "资源路径", kind: "resource" },
+  path: { label: "资源路径", kind: "resource" },
+  text: { label: "文本内容", kind: "text" },
+  align: { label: "对齐（别名）", kind: "string" },
+  halign: { label: "水平对齐", kind: "string" },
+  valign: { label: "垂直对齐", kind: "string" },
+  xalign: { label: "水平锚点", kind: "string" },
+  yalign: { label: "垂直锚点", kind: "string" },
+  // 「数字或 CSS 长度」一律 kind:value —— 纯数字须还原为数字，运行时 len() 才补 px；
+  // 退化成字符串 "120" 会被 CSS 判为非法并静默丢弃（元素停在 0,0）
+  x: { label: "X（数字或 CSS 长度）", kind: "value" },
+  y: { label: "Y（数字或 CSS 长度）", kind: "value" },
+  xoffset: { label: "X 偏移", kind: "value" },
+  yoffset: { label: "Y 偏移", kind: "value" },
+  xanchor: { label: "X 锚点", kind: "string" },
+  yanchor: { label: "Y 锚点", kind: "string" },
+  width: { label: "宽度", kind: "value" },
+  height: { label: "高度", kind: "value" },
+  minWidth: { label: "最小宽度", kind: "value" },
+  minHeight: { label: "最小高度", kind: "value" },
+  maxWidth: { label: "最大宽度", kind: "value" },
+  maxHeight: { label: "最大高度", kind: "value" },
+  margin: { label: "外边距", kind: "value" },
+  padding: { label: "内边距", kind: "value" },
+  right: { label: "右偏移", kind: "value" },
+  bottom: { label: "下偏移", kind: "value" },
+  fontSize: { label: "字号", kind: "value" },
+  size: { label: "字号（文本类别名）", kind: "value" },
+  font: { label: "字体", kind: "string" },
+  color: { label: "颜色", kind: "string" },
+  fontColor: { label: "文字颜色", kind: "string" },
+  textColor: { label: "文字颜色", kind: "string" },
+  textAlign: { label: "文本对齐", kind: "string" },
+  order: { label: "排列序", kind: "number" },
+  zindex: { label: "层级", kind: "number" },
+  opacity: { label: "不透明度", kind: "number" },
+  visible: { label: "可见", kind: "boolean" },
+  enabled: { label: "启用", kind: "boolean" },
+  // 布尔或表达式（`{player.gold < 10}`，点击时刻求值）——故用 value：控件接受两种形态
+  disabled: { label: "禁用（布尔或表达式）", kind: "value" },
+  clipToBounds: { label: "裁剪溢出", kind: "boolean" },
+  cursor: { label: "光标", kind: "string" },
+  rotation: { label: "旋转（度）", kind: "number" },
+  scale: { label: "缩放", kind: "number" },
+  scaleX: { label: "X 缩放", kind: "number" },
+  scaleY: { label: "Y 缩放", kind: "number" },
+  cornerRadius: { label: "圆角", kind: "value" },
+  borderBrush: { label: "边框色", kind: "string" },
+  borderColor: { label: "边框色", kind: "string" },
+  borderThickness: { label: "边框宽度", kind: "value" },
+  spacing: { label: "间距", kind: "number" },
+  direction: { label: "方向（vertical/horizontal）", kind: "string" },
+  // Grid 轨道：数字 → repeat(n, 1fr)（renderers 的 toTrack），故与长度类同用 value
+  columns: { label: "列（数量或 CSS 轨道）", kind: "value" },
+  rows: { label: "行（数量或 CSS 轨道）", kind: "value" },
+  col: { label: "Grid 列（0 基）", kind: "number" },
+  row: { label: "Grid 行（0 基）", kind: "number" },
+  colspan: { label: "跨列", kind: "number" },
+  rowspan: { label: "跨行", kind: "number" },
+  min: { label: "最小值", kind: "number" },
+  max: { label: "最大值", kind: "number" },
+  orientation: { label: "方向", kind: "string" },
+  checked: { label: "已选中", kind: "boolean" },
+  stretch: { label: "拉伸方式", kind: "string" },
+  scroll_h: { label: "允许横向滚动", kind: "boolean" },
+  scroll_v: { label: "允许纵向滚动", kind: "boolean" },
+  nav: { label: "跳转列", kind: "identifier" },
+  cmd: { label: "宿主命令", kind: "identifier" },
+  value: { label: "命令参数", kind: "value" },
+  // `ops` = 点击动作序列（一串 op）。用 `body` 形态：与 if.then/while.body 同一控件，
+  // 递归复用命令面板（插入/删除/上下移/逐字段编辑），零新控件。
+  ops: { label: "点击动作序列", kind: "body" },
+  hover_source: { label: "悬停资源", kind: "resource" },
+  hover_color: { label: "悬停颜色", kind: "string" },
+  hover_opacity: { label: "悬停不透明度", kind: "number" },
+  selected_source: { label: "选中资源", kind: "resource" },
+  selected_color: { label: "选中颜色", kind: "string" },
+  disabled_source: { label: "禁用资源", kind: "resource" },
+  disabled_color: { label: "禁用颜色", kind: "string" },
+  disabled_opacity: { label: "禁用不透明度", kind: "number" },
+};
+
+/** 表单字段优先序（结构 → 内容 → 布局 → 外观 → 交互），未列出的属性按契约序追加 */
+const FIELD_ORDER: readonly string[] = [
+  "id",
+  "name",
+  "text",
+  "source",
+  "src",
+  "path",
+  "x",
+  "y",
+  "width",
+  "height",
+  "zindex",
+  "opacity",
+  "visible",
+  "color",
+  "fontSize",
+  "font",
+  "size",
+  "halign",
+  "valign",
+  "align",
+  "textAlign",
+  "rotation",
+  "scale",
+  "scaleX",
+  "scaleY",
+  "margin",
+  "padding",
+  "xoffset",
+  "yoffset",
+  "xanchor",
+  "yanchor",
+  "right",
+  "bottom",
+  "minWidth",
+  "minHeight",
+  "maxWidth",
+  "maxHeight",
+  "cornerRadius",
+  "borderColor",
+  "borderThickness",
+  "direction",
+  "spacing",
+  "columns",
+  "rows",
+  "col",
+  "row",
+  "colspan",
+  "rowspan",
+  "min",
+  "max",
+  "orientation",
+  "checked",
+  "stretch",
+  "scroll_h",
+  "scroll_v",
+  "nav",
+  "ops",
+  "cmd",
+  "value",
+  "hover_source",
+  "hover_color",
+  "hover_opacity",
+  "selected_source",
+  "selected_color",
+  "disabled_source",
+  "disabled_color",
+  "disabled_opacity",
+  "disabled",
+  "enabled",
+  "clipToBounds",
+  "cursor",
+  "class",
+  "style",
+  "order",
+];
+
+export interface ElementFormDescriptor {
+  type: string;
+  label: string;
+  fields: FieldDescriptor[];
+}
+
+/** 元素类型判定 + 表单描述符（未知类型 = undefined，调用方 fail-closed） */
+export function describeElement(
+  type: string,
+): ElementFormDescriptor | undefined {
+  if (!(ELEMENT_TYPES as readonly string[]).includes(type)) return undefined;
+  // 不下发「已声明但无渲染语义」的属性（作者填了不生效 → 表单一律不给）
+  const allowed = new Set<string>(
+    [...ELEMENT_ATTRIBUTES, "id", "name"].filter(
+      (key) => !UNIMPLEMENTED_ELEMENT_ATTRS.has(key),
+    ),
+  );
+  const ordered = [
+    ...FIELD_ORDER.filter((key) => allowed.has(key)),
+    ...[...allowed].filter((key) => !FIELD_ORDER.includes(key)),
+  ];
+  return {
+    type,
+    label: ELEMENT_LABELS[type] ?? type,
+    fields: ordered.map((key) => ({
+      key,
+      label: ELEMENT_FIELD_META[key]?.label ?? key,
+      kind: ELEMENT_FIELD_META[key]?.kind ?? "string",
+      // 元素属性一律可选（`type` 是结构字段，不在表单里编辑）
+      required: false,
+      hasDefault: false,
+    })),
+  };
+}
+
+/** 36 类型（新建元素菜单） */
+export function listElementTypes(): readonly string[] {
+  return ELEMENT_TYPES;
+}
+
+/** 类型中文标签 */
+export function elementLabel(type: string): string {
+  return ELEMENT_LABELS[type] ?? type;
+}
+
+/** 该类型的专属属性（表单高亮用；通用属性表已含并集） */
+export function specificAttrsOf(type: string): readonly string[] {
+  return ELEMENT_SPECIFIC_ATTRS[type] ?? [];
+}