@lingfan-engine/editor 0.0.0-stage → 0.1.0

package/src/schema/opSchemas/commands.ts

@@ -0,0 +1,374 @@
+/**
+ * op 负载 schema 全集：每条命令一个 `z.strictObject`，`.strict()` 拒绝未知字段
+ * （编辑期 fail-closed）。字段面以执行器为权威（packages/core/src/runtime/ops/）。
+ */
+import { z } from "zod";
+import { isValidSayColor } from "@lingfan-engine/core";
+import {
+  Body,
+  Fade,
+  Finite,
+  InstanceZ,
+  NonEmpty,
+  SlotName,
+  StateValue,
+  Value,
+} from "./fragments.ts";
+
+const saySchema = z.strictObject({
+  text: NonEmpty,
+  speaker: z.string().optional(),
+  /**
+   * 说话人颜色覆盖（覆盖整句/说话人）。
+   *
+   * **判据直接复用引擎的 `isValidSayColor`**（不在此重写正则）——
+   * 两处各写一份判据 ⇒ 必然漂移——
+   * 判据只此一份，投影/校验读同一份。
+   * 与**行内标记** `{color=…}`（写在文本内部）是两件事。
+   */
+  color: z
+    .string()
+    .refine(isValidSayColor, {
+      message: "必须为十六进制颜色（如 #FFD700 / #888 / #FFD700CC）",
+    })
+    .optional(),
+  /**
+   * 本句字体（字体名 = Resources/Fonts 文件名去扩展名）。
+   * 名字是否在注册表内不在此校验（schema 看不见资源目录）——构建期 fail-closed +
+   * 运行期渲染闸门回退负责，这里只收非空字符串。
+   */
+  font: NonEmpty.optional(),
+  clickable: z.boolean().optional(),
+  noskip: z.boolean().optional(),
+  instant: z.boolean().optional(),
+  typewriter: z.number().optional(),
+  voice: NonEmpty.optional(),
+  template: NonEmpty.optional(),
+  z: InstanceZ, // dialogue 层实例 z
+});
+
+const menuSchema = z.strictObject({
+  prompt: z.string().optional(),
+  options: z.array(z.strictObject({ text: NonEmpty, target: NonEmpty })).min(1),
+  z: InstanceZ, // choices 层实例 z
+});
+
+const inputSchema = z.strictObject({
+  prompt: NonEmpty,
+  store: NonEmpty,
+  z: InstanceZ, // choices 层实例 z
+});
+
+const notifySchema = z.strictObject({
+  text: NonEmpty,
+  type: z.string().optional(),
+  duration: z.number().optional(),
+  z: InstanceZ, // notifications 层实例 z
+});
+
+const nvlSchema = z.strictObject({
+  mode: z.enum(["enter", "auto", "clear", "exit"]).optional(),
+});
+
+const characterSchema = z.strictObject({
+  key: NonEmpty,
+  name: z.string().optional(),
+  color: z.string().optional(),
+  size: z.string().optional(),
+  font: z.string().optional(),
+  textColor: z.string().optional(),
+  screen: NonEmpty.optional(),
+});
+
+const uncharacterSchema = z.strictObject({ key: NonEmpty });
+
+const waitSchema = z.strictObject({
+  seconds: z.number(),
+  skipable: z.boolean().optional(),
+});
+
+const pauseSchema = z.strictObject({
+  seconds: z.number(),
+});
+
+const randomSchema = z.strictObject({
+  seed: z.number().int(),
+  range: z.tuple([z.number(), z.number()]),
+  var: NonEmpty,
+});
+
+const jumpSchema = z.strictObject({
+  target: NonEmpty,
+});
+
+const navigateSchema = z.strictObject({
+  path: NonEmpty,
+  scene: NonEmpty.optional(),
+});
+
+/** `call`：target 必填；`into` 为结果绑定名（ret 带值返回时声明成调用方局部变量，无带值 ret 则绑 `null`） */
+const callSchema = z.strictObject({
+  target: NonEmpty,
+  args: z.array(Value).optional(),
+  into: NonEmpty.optional(),
+});
+
+const returnSchema = z.strictObject({
+  value: Value.optional(),
+});
+/** 函数定义：name/params/body 三者引擎均必填（`data/format/validate/blocks.ts` `case "func"`） */
+const funcSchema = z.strictObject({
+  name: NonEmpty,
+  params: z.array(NonEmpty),
+  body: Body,
+});
+
+const ifSchema = z.strictObject({
+  cond: NonEmpty,
+  then: Body,
+  elif: z.array(z.strictObject({ cond: NonEmpty, then: Body })).optional(),
+  else: Body.optional(),
+});
+
+const whileSchema = z.strictObject({
+  cond: NonEmpty,
+  body: Body,
+});
+
+const assertSchema = z.strictObject({
+  cond: NonEmpty,
+  message: z.string().optional(),
+});
+
+const guardSchema = z.strictObject({
+  fn: NonEmpty,
+  /**
+   * 原样**运输**的宿主参数：嵌套 JSON 合法（同 `minigame.config` 口径；运行期
+   * `findJsonValueError` 兜底 JSON 安全）。值口径原则：**被求值的走 `Value`
+   * （call args / reward / set），被运输的走 JSON**（guard args / minigame config）。
+   */
+  args: z.record(z.string(), z.unknown()).optional(),
+});
+
+const forSchema = z.strictObject({
+  var: NonEmpty,
+  in: NonEmpty,
+  body: Body,
+});
+
+const foreachSchema = z.strictObject({
+  var: NonEmpty,
+  key: NonEmpty,
+  body: Body,
+});
+
+const switchSchema = z.strictObject({
+  on: NonEmpty,
+  cases: z.array(z.strictObject({ value: Value, body: Body })).min(1),
+  default: Body.optional(),
+});
+
+const emptySchema = z.strictObject({});
+
+const assignSchema = z.strictObject({ key: NonEmpty, value: StateValue });
+
+const undefSchema = z.strictObject({ key: NonEmpty });
+
+const arraySchema = z.strictObject({
+  key: NonEmpty,
+  items: z.array(StateValue),
+  once: z.boolean().optional(),
+});
+
+const arrayPushSchema = z.strictObject({ key: NonEmpty, value: StateValue });
+
+const arrayPopSchema = z.strictObject({ key: NonEmpty });
+
+const dictSchema = z.strictObject({
+  key: NonEmpty,
+  value: z.record(z.string(), StateValue),
+  once: z.boolean().optional(),
+});
+
+const dictSetSchema = z.strictObject({
+  key: NonEmpty,
+  field: NonEmpty,
+  value: StateValue,
+});
+
+const saveSchema = z.strictObject({
+  slot: SlotName,
+  title: z.string().optional(),
+});
+
+const loadSchema = z.strictObject({ slot: NonEmpty });
+
+const autoSaveSchema = z.strictObject({
+  enabled: z.boolean(),
+});
+
+const saveDeleteSchema = z.strictObject({ slot: SlotName });
+
+const playFields = {
+  resource: NonEmpty,
+  volume: Finite.optional(),
+};
+const bgmSchema = z.strictObject({
+  ...playFields,
+  loop: z.boolean().optional(),
+  fade: Fade.optional(),
+  restart: z.boolean().optional(),
+});
+const seSchema = z.strictObject({ ...playFields });
+const voiceSchema = z.strictObject({
+  ...playFields,
+  auto_stop: z.boolean().optional(),
+  restart: z.boolean().optional(),
+});
+const stopSchema = z.strictObject({ fade: Fade.optional() });
+
+const videoSchema = z.strictObject({
+  ...playFields,
+  loop: z.boolean().optional(),
+  z: InstanceZ, // video 层实例 z
+});
+const cutsceneSchema = z.strictObject({
+  ...playFields,
+  skipable: z.boolean().optional(),
+  z: InstanceZ, // video 层实例 z
+});
+const seekVideoSchema = z.strictObject({
+  seconds: z.number().finite().min(0),
+});
+const videoSkipableSchema = z.strictObject({ value: z.boolean() });
+
+/** minigame：config 原样透传 UI（任意 JSON）；reward 键值数组（value 执行期求值 → 标量/{expr}） */
+const minigameSchema = z.strictObject({
+  game: NonEmpty,
+  config: z.record(z.string(), z.unknown()).optional(),
+  on_success: NonEmpty.optional(),
+  on_fail: NonEmpty.optional(),
+  reward: z.array(z.strictObject({ key: NonEmpty, value: Value })).optional(),
+  z: InstanceZ, // minigame 层实例 z
+});
+
+/** 外部玩法系统接管（与 minigame 同形；无 reward——那是小游戏专属语义） */
+const interactionSchema = z.strictObject({
+  system: NonEmpty,
+  config: z.record(z.string(), z.unknown()).optional(),
+  on_success: NonEmpty.optional(),
+  on_fail: NonEmpty.optional(),
+  z: InstanceZ, // 与 minigame 同层（外部系统整屏接管）
+});
+
+// ====== 元素系统（元素增删改 + 表现类）======
+// 字段面以执行器为权威（runtime/ops/element/visual.ts 的 ELEMENT_OP_FIELDS）；x/y 允许数字或 CSS 长度串。
+
+/** 元素增删改（`show` / `hide` / `background` / `bg_switch` / `zindex` / `style` / `window`） */
+const showSchema = z.strictObject({
+  target: NonEmpty,
+  x: z.union([Finite, z.string()]).optional(),
+  y: z.union([Finite, z.string()]).optional(),
+  id: NonEmpty.optional(),
+  name: NonEmpty.optional(),
+  background: z.boolean().optional(),
+});
+const hideSchema = z.strictObject({ target: NonEmpty });
+const backgroundSchema = z.strictObject({ resource: NonEmpty });
+const bgSwitchSchema = z.strictObject({ resource: NonEmpty });
+const zindexSchema = z.strictObject({ target: NonEmpty, value: Finite });
+const styleSchema = z.strictObject({
+  target: NonEmpty,
+  props: z.record(z.string(), Value),
+});
+const windowSchema = z.strictObject({ mode: z.enum(["auto", "show", "hide"]) });
+
+/** 帧驱动表现类（`animate` / `animate_block` / `transition` / `shake` / `text_typewriter`） */
+const animateSchema = z.strictObject({
+  target: NonEmpty,
+  property: NonEmpty,
+  value: Finite,
+  duration: Fade.optional(),
+  easing: NonEmpty.optional(),
+});
+const animateBlockSchema = z.strictObject({
+  target: NonEmpty,
+  x: Finite.optional(),
+  y: Finite.optional(),
+  opacity: Finite.optional(),
+  rotation: Finite.optional(),
+  scale: Finite.optional(),
+  duration: Fade.optional(),
+  easing: NonEmpty.optional(),
+});
+const transitionSchema = z.strictObject({
+  type: NonEmpty,
+  duration: Fade.optional(),
+});
+const shakeSchema = z.strictObject({
+  intensity: Finite.optional(),
+  duration: Fade.optional(),
+});
+const textTypewriterSchema = z.strictObject({
+  enabled: z.boolean().optional(),
+  speed: z.number().finite().positive().optional(),
+});
+
+export {
+  saySchema,
+  menuSchema,
+  inputSchema,
+  notifySchema,
+  nvlSchema,
+  characterSchema,
+  uncharacterSchema,
+  waitSchema,
+  pauseSchema,
+  randomSchema,
+  jumpSchema,
+  navigateSchema,
+  callSchema,
+  returnSchema,
+  funcSchema,
+  ifSchema,
+  whileSchema,
+  assertSchema,
+  guardSchema,
+  forSchema,
+  foreachSchema,
+  switchSchema,
+  emptySchema,
+  assignSchema,
+  undefSchema,
+  arraySchema,
+  arrayPushSchema,
+  arrayPopSchema,
+  dictSchema,
+  dictSetSchema,
+  saveSchema,
+  loadSchema,
+  autoSaveSchema,
+  saveDeleteSchema,
+  bgmSchema,
+  seSchema,
+  voiceSchema,
+  stopSchema,
+  videoSchema,
+  cutsceneSchema,
+  seekVideoSchema,
+  videoSkipableSchema,
+  minigameSchema,
+  interactionSchema,
+  showSchema,
+  hideSchema,
+  backgroundSchema,
+  bgSwitchSchema,
+  zindexSchema,
+  styleSchema,
+  windowSchema,
+  animateSchema,
+  animateBlockSchema,
+  transitionSchema,
+  shakeSchema,
+  textTypewriterSchema,
+};

package/src/schema/opSchemas/fragments.ts

@@ -0,0 +1,24 @@
+/**
+ * op 负载共享片段：被多条命令 schema 复用的最小判定单元，一处定义防漂移。
+ */
+import { z } from "zod";
+
+const NonEmpty = z.string().min(1);
+const SlotName = z
+  .string()
+  .regex(/^[A-Za-z0-9_-]{1,64}$/, "槽位名必须为字母数字/_/-，1..64");
+const Value = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * 状态类 op 的值域 = 共享 Value + null：状态槽允许「空值」占位
+ * （初始未定 / 条件性覆盖），变量销毁走 undef（undefined 永不入值域）。
+ * 不并入 Value：say/nvl 等叙事字段与 call/return/switch 等共享面
+ * 保持标量域，null 只属于状态槽位（set/define/let/local/array 族/dict 族）。
+ */
+const StateValue = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const Body = z.array(z.unknown());
+const Finite = z.number().finite();
+const Fade = z.number().finite().min(0);
+/** 实例级 z：非负有限数；仅拥有独立渲染层的命令接受 */
+const InstanceZ = z.number().finite().min(0).optional();
+
+export { NonEmpty, SlotName, Value, StateValue, Body, Finite, Fade, InstanceZ };

package/src/schema/opSchemas/index.ts

@@ -0,0 +1,16 @@
+/**
+ * op 全集 schema（Zod 单一事实源）：一份定义同时驱动属性面板表单派生与
+ * 编辑期 fail-closed 校验。字段面以执行器为权威（packages/core/src/runtime/ops/）：
+ * 未知 op / 未知负载字段 / 缺失必填 / 类型错误在编辑期标红，错误不过夜。
+ * 块体字段（then/body/…）按 z.unknown() 数组承载——嵌套命令的校验与指针定位由
+ * validateStory 沿表单描述符递归（嵌套命令才拿得到逐条 unknown-op 诊断）。
+ */
+export { OP_SCHEMAS } from "./map.ts";
+export type {
+  ScriptOpName,
+  CommandOf,
+  ScriptCommand,
+  ScriptValue,
+  StateScriptValue,
+} from "./types.ts";
+export { validateCommand } from "./validate.ts";

package/src/schema/opSchemas/map.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import {
+  saySchema,
+  menuSchema,
+  inputSchema,
+  notifySchema,
+  nvlSchema,
+  characterSchema,
+  uncharacterSchema,
+  waitSchema,
+  pauseSchema,
+  randomSchema,
+  jumpSchema,
+  navigateSchema,
+  funcSchema,
+  callSchema,
+  returnSchema,
+  ifSchema,
+  whileSchema,
+  forSchema,
+  foreachSchema,
+  switchSchema,
+  emptySchema,
+  assertSchema,
+  guardSchema,
+  assignSchema,
+  undefSchema,
+  arraySchema,
+  arrayPushSchema,
+  arrayPopSchema,
+  dictSchema,
+  dictSetSchema,
+  saveSchema,
+  loadSchema,
+  autoSaveSchema,
+  saveDeleteSchema,
+  bgmSchema,
+  stopSchema,
+  seSchema,
+  voiceSchema,
+  videoSchema,
+  cutsceneSchema,
+  seekVideoSchema,
+  videoSkipableSchema,
+  minigameSchema,
+  interactionSchema,
+  showSchema,
+  hideSchema,
+  backgroundSchema,
+  bgSwitchSchema,
+  zindexSchema,
+  styleSchema,
+  windowSchema,
+  animateSchema,
+  animateBlockSchema,
+  transitionSchema,
+  shakeSchema,
+  textTypewriterSchema,
+} from "./commands.ts";
+
+/** op → 负载 schema（不含 op 键本身）；字面量键形态 = `ScriptCommand` 判别联合的派生源。
+ * 新增 op = 加条目 = 表单 / 校验 / 类型三面自动出现（单一事实源，零重复定义） */
+export const OP_SCHEMA_MAP = {
+  say: saySchema,
+  menu: menuSchema,
+  input: inputSchema,
+  notify: notifySchema,
+  nvl: nvlSchema,
+  character: characterSchema,
+  uncharacter: uncharacterSchema,
+  wait: waitSchema,
+  pause: pauseSchema,
+  random: randomSchema,
+  jump: jumpSchema,
+  navigate: navigateSchema,
+  func: funcSchema,
+  call: callSchema,
+  return: returnSchema,
+  if: ifSchema,
+  while: whileSchema,
+  for: forSchema,
+  foreach: foreachSchema,
+  switch: switchSchema,
+  break: emptySchema,
+  continue: emptySchema,
+  assert: assertSchema,
+  guard: guardSchema,
+  set: assignSchema,
+  define: assignSchema,
+  let: assignSchema,
+  local: assignSchema,
+  undef: undefSchema,
+  array: arraySchema,
+  array_push: arrayPushSchema,
+  array_pop: arrayPopSchema,
+  dict: dictSchema,
+  dict_set: dictSetSchema,
+  save: saveSchema,
+  load: loadSchema,
+  auto_save: autoSaveSchema,
+  save_delete: saveDeleteSchema,
+  bgm: bgmSchema,
+  stop_bgm: stopSchema,
+  se: seSchema,
+  ambient: bgmSchema,
+  stop_ambient: stopSchema,
+  voice: voiceSchema,
+  stop_voice: stopSchema,
+  video: videoSchema,
+  cutscene: cutsceneSchema,
+  seek_video: seekVideoSchema,
+  pause_video: emptySchema,
+  resume_video: emptySchema,
+  stop_video: emptySchema,
+  video_skipable: videoSkipableSchema,
+  minigame: minigameSchema,
+  interaction: interactionSchema,
+  // 元素系统
+  show: showSchema,
+  hide: hideSchema,
+  background: backgroundSchema,
+  bg_switch: bgSwitchSchema,
+  zindex: zindexSchema,
+  style: styleSchema,
+  window: windowSchema,
+  animate: animateSchema,
+  animate_block: animateBlockSchema,
+  transition: transitionSchema,
+  shake: shakeSchema,
+  text_typewriter: textTypewriterSchema,
+};
+
+/** 运行期查找面（与 `OP_SCHEMA_MAP` 同一对象，键集恒等）；新增 op 自动可用 */
+export const OP_SCHEMAS: Readonly<Record<string, z.ZodType>> = OP_SCHEMA_MAP;

package/src/schema/opSchemas/types.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { OP_SCHEMA_MAP } from "./map.ts";
+import { Value, StateValue } from "./fragments.ts";
+
+// ====== 类型派生（与 schema 同源 ⇒ 字段面零漂移）======
+
+/** 内建 op 名字面量全集 */
+export type ScriptOpName = keyof typeof OP_SCHEMA_MAP & string;
+
+/**
+ * 单 op 命令类型：`CommandOf<"bgm">` = `{ op: "bgm" } & 负载形状`。
+ * 派生自 `OP_SCHEMA_MAP` ⇒ schema 增删字段时类型自动跟随。
+ *
+ * **条件类型必须保持可分发**（naked `K extends`）：不加分发时
+ * `CommandOf<ScriptOpName>` 会折叠成 `{ op: 全体字面量 } & (全体 infer 联合)`——
+ * 全可选负载（如 nvl）成为逃生舱，缺必填不再报红。
+ * 空 schema（strictObject({}) 的 infer = `Record<string, never>`，会与 op 键冲突）
+ * 特判为纯 `{ op: K }`。
+ */
+export type CommandOf<K extends ScriptOpName> = K extends ScriptOpName
+  ? z.infer<(typeof OP_SCHEMA_MAP)[K]> extends Record<string, never>
+    ? { op: K }
+    : { op: K } & z.infer<(typeof OP_SCHEMA_MAP)[K]>
+  : never;
+
+/**
+ * **内建 op 判别联合**（裸写命令的强类型形态）：`op` 决定可用字段——
+ * `op: "say"` ⇒ text/speaker/z… 编译期可查；未知 op / 未知字段 / 类型错编译期报红
+ * （与编辑期 `validateCommand` 的 unknown-op / unknown-field 同口径，提前到构建期）。
+ *
+ * **对内建 op 闭合，不带索引签名逃生舱**：联合里任何 `{[k: string]: unknown}`
+ * 成员都会让所有字面量可指派到它，废掉整个联合的多余属性检查。
+ * 扩展 op 走 `extOp()`（产物 = StoryCommand envelope）或显式 `: StoryCommand`
+ * 注解——显式逃生 > 隐式漏洞。
+ */
+export type ScriptCommand = CommandOf<ScriptOpName>;
+
+/** op 负载标量值（字面量 / `{expr}` 表达式串 / `+=` 复合赋值串——与 zod `Value` 同源） */
+export type ScriptValue = z.infer<typeof Value>;
+
+/** 状态类 op 负载值（共享 Value + null——与 zod `StateValue` 同源） */
+export type StateScriptValue = z.infer<typeof StateValue>;