@lingfan-engine/core 0.2.0 → 0.3.1

package/src/shared/guards.ts

@@ -61,17 +61,51 @@ export function isPlainObject(
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** 是否是已知的场景类型（非法值由解析层 fail-closed，这里只做收窄） */
+/**
+ * 是否是契约承认的场景类型（**只认 `game` / `ui`**）。
+ *
+ * 调用点都在「拒绝非法输入」的位置：故事文件里写别的值一律 fail-closed 报错，
+ * 不静默当剧情——那种错要等存档/回溯出问题才发现，代价极高。
+ */
 export function isSceneType(value: unknown): value is SceneType {
-  return value === "game" || value === "menu" || value === "ui";
+  return value === "game" || value === "ui";
+}
+
+/**
+ * 把外部输入的场景类型拼写归一为契约值：`game` / `ui`。
+ *
+ * **单一归一函数**：解析层已用 `isSceneType` fail-closed 拒绝非法值，
+ * 这里只负责「缺省」这一种合法输入——`undefined` → `game`。
+ *
+ * 为什么仍单独成函数：`type` 的缺省语义（不写 = 剧情）在 JSON 解析、DSL 解析、
+ * 读侧兜底三处都要用，散写三份 `?? "game"` 会让「缺省是什么」出现三个答案。
+ *
+ * 注意：**归一是读侧兜底，不是校验**。故事文件里的非法 `type` 要 fail-closed 报错，
+ * 那是解析层（`columnShapeDefect`）的职责，不靠这里静默吃掉。
+ */
+export function normalizeSceneType(raw: unknown): SceneType {
+  return isSceneType(raw) ? raw : "game";
 }
 
 /**
- * 该列是否参与历史与存档：`type` 缺省按 `game` 算，`menu` / `ui` 不参与。
+ * 该列是否参与历史与存档：`type` 缺省按 `game` 算，`ui` 不参与。
  *
  * **单一判定点**——引擎的写入守卫与编辑器的章节分组都调用这里，谁都不许另写一份，
  * 否则两侧对「哪些列进存档」的理解会分叉。
  */
 export function isReplayableColumn(column: Pick<StoryColumn, "type">): boolean {
-  return (column.type ?? "game") === "game";
+  return sceneTypeOf(column) === "game";
+}
+
+/**
+ * 列的**归一化**运行语义类型：缺省（以及解析层已 fail-closed 的非法值）一律取 `game`。
+ *
+ * **为什么需要它**：`isReplayableColumn` 只回答「参不参与存档」，回答不了「是哪一种」。
+ * 宿主列清单与状态读口要的是具体类型，若各自写 `column.type ?? "game"`，
+ * 缺省口径就分叉了。归一口径本身归 `normalizeSceneType`，这里只是它的列级入口。
+ *
+ * 注意：**这是读侧归一**。故事文件里的非法 `type` 由解析层拒收，不靠这里兜底。
+ */
+export function sceneTypeOf(column: Pick<StoryColumn, "type">): SceneType {
+  return normalizeSceneType(column.type);
 }

package/src/shared/index.ts

@@ -2,6 +2,9 @@
  * 通用出口：没有业务含义的取值判据与小工具，不依赖包内其他层，任何层都可以引用。
  * 实现按用途分文件，消费方只从这里取。
  */
+export * from "./audio.ts";
 export * from "./guards.ts";
+export * from "./mounts.ts";
 export * from "./numbers.ts";
 export * from "./ordering.ts";
+export * from "./ui-name.ts";

package/src/shared/mounts.ts

@@ -0,0 +1,42 @@
+/**
+ * 挂载表的读入判据：把运行期到手的 `unknown` 收窄成契约里的挂载表。
+ *
+ * 契约层只声明形态，挂载表却可能来自存档、来自被改坏的工程文件，
+ * 所以每次读入都得先判后用（与 `audio.ts` 的实例表同一套纪律：判不过就由调用方
+ * fail-closed，这里不抛错也不猜默认值）。
+ *
+ * 三条规则一次判清，缺一条都会让坏数据漏进渲染层：
+ * - 表是普通对象（数组与 `null` 不算——数组会把下标当 UI 名）
+ * - 键合 UI 名形态（名字同时是宿主预加载键与目录名，形态必须统一）
+ * - 值只有 `visible: boolean` 与 `props: 普通对象` 两项
+ */
+import type { MountEntry, MountTable } from "../contracts/runtime/index.ts";
+import { isPlainObject } from "./guards.ts";
+import { isUiName } from "./ui-name.ts";
+
+/** 是否是合形态的挂载记录 */
+export function isMountEntry(value: unknown): value is MountEntry {
+  if (!isPlainObject(value)) return false;
+  if (typeof value.visible !== "boolean") return false;
+  return isPlainObject(value.props);
+}
+
+/** 是否是合形态的挂载表：普通对象 + 键合 UI 名 + 值合记录 */
+export function isMountTable(value: unknown): value is MountTable {
+  if (!isPlainObject(value)) return false;
+  for (const name of Object.keys(value)) {
+    if (!isUiName(name)) return false;
+    if (!isMountEntry(value[name])) return false;
+  }
+  return true;
+}
+
+/**
+ * 取挂载表的 UI 名清单（码点序）：不合形态的表按空表处理。
+ *
+ * 渲染层按名字排序后下发才能保证「同一份状态 → 同一串挂载动作」，
+ * 否则对象键序会让同一存档在两台机器上挂出不同顺序的组件。
+ */
+export function mountNames(value: unknown): readonly string[] {
+  return isMountTable(value) ? Object.keys(value).sort() : [];
+}

package/src/shared/ui-name.ts

@@ -0,0 +1,41 @@
+/**
+ * 列级 UI 名字的形态与定序：名字 = `src/ui/<名>/` 的目录名。
+ *
+ * 为什么名字要卡形态：名字同时是**产物里的字符串**、宿主的**预加载键**、以及
+ * 目录/文件名的来源。不卡形态的话，`Hub` 与 `hub` 会在不同文件系统上落到同一个目录、
+ * 却成为两个不同的产物键，产物与实现就对不上了。
+ *
+ * 形态与扩展 id / 玩法系统 id 同源（`SHORT_ID_PATTERN`）：同一个系统不出现两种写法，
+ * 且名字作为产物字段时仍然短小可读。
+ */
+import { SHORT_ID_PATTERN } from "../contracts/identifiers.ts";
+import { compareOrdinal } from "./ordering.ts";
+
+/** 合法 UI 名：小写字母开头，其后小写字母 / 数字 / `_` / `-`，总长 1..32 */
+export const UI_NAME_PATTERN = SHORT_ID_PATTERN;
+
+/** 是否为合法 UI 名（类型收窄到 `string`，可直接用于过滤未校验的 JSON 数组） */
+export function isUiName(value: unknown): value is string {
+  return typeof value === "string" && UI_NAME_PATTERN.test(value);
+}
+
+/**
+ * 归一列级 `uis`：**去重 + 按名字码点序**。
+ *
+ * 为什么必须归一：`uis` 是产物字节的一部分，而它的来源（导入语句的书写顺序、
+ * 文件系统的目录枚举顺序）在不同机器上不一样。不归一的产物会「同源不同字节」，
+ * 缓存与逐字节比对全部失效。码点序（而非 locale 序）才与运行环境的语言无关。
+ *
+ * 这是全链路唯一的定序点：解析、汇编、写出三处都调这里，不各写一份比较器。
+ */
+export function normalizeUiNames(names: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const name of names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    unique.push(name);
+  }
+  unique.sort(compareOrdinal);
+  return unique;
+}

package/src/runtime/ops/media.ts

@@ -1,274 +0,0 @@
-/**
- * 媒体命令的执行：音频通道、视频命令流、出站通知。
- *
- * 这一族的共同点是「核心只写状态，播放交给宿主」——音频写四通道的通道对象，
- * 视频写单调递增的命令流，通知只发出站事件。渲染器按状态与事件执行，
- * 核心不持有播放器，也不关心播放是否成功。
- */
-import {
-  SYS,
-  type AudioChannelState,
-  type OutboundEvent,
-  type OutboundPayload,
-  type StoryCommand,
-  type VideoCommand,
-} from "../../contracts/index.ts";
-import { interpolateText } from "../expr/index.ts";
-import type { Frame, OpContext } from "../internal/index.ts";
-
-/** 音频 op 已知负载字段（未知字段 fail-closed） */
-const AUDIO_FIELDS: Record<string, ReadonlySet<string>> = {
-  bgm: new Set(["op", "resource", "volume", "loop", "fade", "restart"]),
-  se: new Set(["op", "resource", "volume"]),
-  ambient: new Set(["op", "resource", "volume", "loop", "fade", "restart"]),
-  stop_bgm: new Set(["op", "fade"]),
-  stop_ambient: new Set(["op", "fade"]),
-  voice: new Set(["op", "resource", "volume", "auto_stop", "restart"]),
-  stop_voice: new Set(["op", "fade"]),
-};
-
-/** 停止类 op → 目标常驻通道系统键 */
-const AUDIO_STOP_KEY: Record<string, string> = {
-  stop_bgm: SYS.audioBgm,
-  stop_ambient: SYS.audioAmbient,
-  stop_voice: SYS.audioVoice,
-};
-
-/** 音频通道 op → 常驻通道系统键（se 为一次性触发，不在表内） */
-const AUDIO_CHANNEL_KEY: Record<string, string> = {
-  bgm: SYS.audioBgm,
-  ambient: SYS.audioAmbient,
-  voice: SYS.audioVoice,
-};
-
-/** 视频族已知负载字段（未知字段 fail-closed） */
-const VIDEO_FIELDS: Record<string, ReadonlySet<string>> = {
-  video: new Set(["op", "resource", "volume", "loop", "z"]),
-  cutscene: new Set(["op", "resource", "volume", "skipable", "z"]),
-  seek_video: new Set(["op", "seconds"]),
-  pause_video: new Set(["op"]),
-  resume_video: new Set(["op"]),
-  stop_video: new Set(["op"]),
-  video_skipable: new Set(["op", "value"]),
-};
-
-/**
- * 四音频通道：核心只写状态，播放由 UI 适配器落地。
- * - bgm/ambient/voice 为常驻通道（写状态对象，随快照/存档随行）；se 为一次性触发（单调 seq）
- * - 同资源重写保留播放位置：重放不打断当前曲目（回滚 seek / 读档续播）
- * - stop_* 写 stop 形态（带淡出参数）；未知字段/非法负载 fail-closed
- */
-export function execAudio(ctx: OpContext, cmd: StoryCommand): boolean {
-  const unknown = Object.keys(cmd).filter(
-    (k) => !(AUDIO_FIELDS[cmd.op]?.has(k) ?? false),
-  );
-  if (unknown.length > 0) {
-    ctx.fail(
-      `${cmd.op}-unknown-field`,
-      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
-    );
-    return false;
-  }
-  const fade = audioFade(ctx, cmd.fade, cmd.op);
-  if (fade === null) return false;
-  if (
-    cmd.op === "stop_bgm" ||
-    cmd.op === "stop_ambient" ||
-    cmd.op === "stop_voice"
-  ) {
-    // 清通道为停止形态（淡出参数随状态走，不被丢弃）
-    const stopKey = AUDIO_STOP_KEY[cmd.op]!;
-    ctx.setSystem(stopKey, {
-      kind: "stop",
-      fadeMs: fade,
-    } satisfies AudioChannelState);
-    // 停止背景乐：播放位置归零（帧级键静默写）
-    if (cmd.op === "stop_bgm") ctx.state.set(SYS.bgmPosition, 0);
-    return true;
-  }
-  if (typeof cmd.resource !== "string" || cmd.resource === "") {
-    ctx.fail(
-      `${cmd.op}-invalid-resource`,
-      `${cmd.op} 需要非空 resource 字符串`,
-    );
-    return false;
-  }
-  const volume = audioVolume(ctx, cmd.volume, cmd.op);
-  if (volume === null) return false;
-  if (cmd.op === "se") {
-    ctx.mediaSeq += 1;
-    ctx.setSystem(SYS.audioSe, {
-      kind: "play",
-      resource: cmd.resource,
-      volume,
-      loop: false,
-      fadeMs: 0,
-      seq: ctx.mediaSeq,
-    } satisfies AudioChannelState);
-    return true;
-  }
-  const channelKey = AUDIO_CHANNEL_KEY[cmd.op]!;
-  const previous = ctx.get(channelKey) as AudioChannelState | null | undefined;
-  const restart = cmd.restart === true;
-  if (cmd.op === "bgm") {
-    // 首播/换曲/显式重播归零；同曲静默续播（回滚 seek / 读档续播）。
-    // 帧级键静默写（高频键不进事件流），UI 经通道事件重读位置。
-    const sameTrack =
-      previous?.kind === "play" && previous.resource === cmd.resource;
-    if (!sameTrack || restart) ctx.state.set(SYS.bgmPosition, 0);
-  }
-  const state: AudioChannelState = {
-    kind: "play",
-    resource: cmd.resource,
-    volume,
-    loop: cmd.op === "voice" ? false : cmd.loop !== false,
-    fadeMs: fade,
-  };
-  if (cmd.op === "voice") state.autoStop = cmd.auto_stop !== false;
-  if (restart) {
-    // 单调序号：同曲连续两次 restart 也是两次独立事件（渲染层据此重播）
-    ctx.mediaSeq += 1;
-    state.restart = true;
-    state.seq = ctx.mediaSeq;
-  }
-  ctx.setSystem(channelKey, state);
-  return true;
-}
-
-/** volume 窄化：缺省 1；非有限数字 fail-closed，越界按物理范围钳制 */
-function audioVolume(ctx: OpContext, raw: unknown, op: string): number | null {
-  if (raw === undefined) return 1;
-  if (typeof raw !== "number" || !Number.isFinite(raw)) {
-    ctx.fail(`${op}-invalid-volume`, `${op} 的 volume 必须是有限数字`);
-    return null;
-  }
-  return Math.min(1, Math.max(0, raw));
-}
-
-/** fade 窄化：缺省 0；负数/非有限数字 fail-closed */
-function audioFade(ctx: OpContext, raw: unknown, op: string): number | null {
-  if (raw === undefined) return 0;
-  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
-    ctx.fail(`${op}-invalid-fade`, `${op} 的 fade 必须是非负有限数字（毫秒）`);
-    return null;
-  }
-  return raw;
-}
-
-/**
- * 视频族：核心只写命令流（`__video`，seq 单调），渲染器按序执行。
- * - `video` = 非阻塞播放（故事继续）；`cutscene` = 阻塞过场（等待建立时提交检查点，
- *   同 menu/wait/input；ended/跳过解除）。
- * - `seek_video`/`pause_video`/`resume_video`/`stop_video` 为离散命令；
- *   `video_skipable` 设后续 video/cutscene 的缺省 skipable。
- */
-export function execVideo(
-  ctx: OpContext,
-  frame: Frame,
-  cmd: StoryCommand,
-  cutscene = false,
-): boolean {
-  const known = VIDEO_FIELDS[cmd.op]!;
-  const unknown = Object.keys(cmd).filter((k) => !known.has(k));
-  if (unknown.length > 0) {
-    ctx.fail(
-      `${cmd.op}-unknown-field`,
-      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
-    );
-    return false;
-  }
-  ctx.videoSeq += 1;
-  const seq = ctx.videoSeq;
-  if (cmd.op === "video" || cmd.op === "cutscene") {
-    if (ctx.rejectBadInstanceZ(cmd)) return false; // 先拒非法 z（不动状态）
-    ctx.setInstanceZ(SYS.videoZ, cmd.z); // 视频层实例 z（宿主解析后交 VideoPort.setZIndex）
-    if (typeof cmd.resource !== "string" || cmd.resource === "") {
-      ctx.fail(
-        `${cmd.op}-invalid-resource`,
-        `${cmd.op} 需要非空 resource 字符串`,
-      );
-      return false;
-    }
-    const volume = audioVolume(ctx, cmd.volume, cmd.op);
-    if (volume === null) return false;
-    // skipable：cutscene 显式参数 > video_skipable 持久开关（缺省可跳）
-    const skipable =
-      cutscene && cmd.skipable !== undefined
-        ? cmd.skipable === true
-        : ctx.get(SYS.videoSkipable) !== false;
-    ctx.setSystem(SYS.video, {
-      kind: "play",
-      resource: cmd.resource,
-      volume,
-      loop: cmd.loop === true,
-      cutscene,
-      skipable,
-      seq,
-    } satisfies VideoCommand);
-    if (cutscene) {
-      // 过场等待建立时提交检查点（同 menu/wait/input）；重放期同坐标原位替换
-      ctx.setSystem(SYS.waiting, "video");
-      ctx.commitCheckpoint(ctx.takeSnapshot(ctx.checkpointCoord(frame)));
-      ctx.liveCheckpointed = true;
-      ctx.autoSaveAtCheckpoint(); // cutscene 等待画面建立 = auto_save 消费点
-      frame.index += 1;
-    }
-    return true;
-  }
-  if (cmd.op === "seek_video") {
-    const seconds = cmd.seconds;
-    if (
-      typeof seconds !== "number" ||
-      !Number.isFinite(seconds) ||
-      seconds < 0
-    ) {
-      ctx.fail(
-        "seek_video-invalid-seconds",
-        "seek_video 需要非负有限数字（秒）",
-      );
-      return false;
-    }
-    ctx.setSystem(SYS.video, {
-      kind: "seek",
-      seconds,
-      seq,
-    } satisfies VideoCommand);
-    return true;
-  }
-  if (cmd.op === "pause_video") {
-    ctx.setSystem(SYS.video, { kind: "pause", seq } satisfies VideoCommand);
-    return true;
-  }
-  if (cmd.op === "resume_video") {
-    ctx.setSystem(SYS.video, { kind: "resume", seq } satisfies VideoCommand);
-    return true;
-  }
-  if (cmd.op === "stop_video") {
-    ctx.setSystem(SYS.video, { kind: "stop", seq } satisfies VideoCommand);
-    return true;
-  }
-  // video_skipable
-  ctx.setSystem(SYS.videoSkipable, cmd.value !== false);
-  return true;
-}
-
-/** notify：出站 toast 事件（覆盖层）；文本插值与 say 同语义 */
-export function execNotify(ctx: OpContext, cmd: StoryCommand): void {
-  if (ctx.rejectBadInstanceZ(cmd)) return; // 先拒非法 z（不动状态）
-  const { text, errors } = interpolateText(
-    ctx.translate(cmd.text as string),
-    ctx.resolveName,
-    ctx.draw,
-  );
-  for (const e of errors)
-    ctx.fail(e.code, ctx.texts.interpolationFallback(e.message));
-  ctx.setInstanceZ(SYS.notificationsZ, cmd.z); // 本条通知的实例 z（notifications 层）
-  const payload: OutboundPayload = {
-    kind: "notify",
-    text,
-    ...(typeof cmd.type === "string" ? { notifyType: cmd.type } : {}),
-    ...(typeof cmd.duration === "number" ? { duration: cmd.duration } : {}),
-  };
-  const event: OutboundEvent = { v: 1, kind: "event", payload };
-  for (const listener of ctx.eventListeners) listener(event);
-}