@lingfan-engine/core 0.2.0 → 0.3.0

package/src/runtime/ops/media/instances.ts

@@ -0,0 +1,312 @@
+/**
+ * 音频实例族：`audio_play` / `audio_stop` / `audio_volume`。
+ *
+ * 实例与四通道**并存**，不是替换：通道是叙事语义（bgm / se / ambient / voice，
+ * 各有一档玩家偏好），实例是作者的编排单元（数量不定、名字自起、各自独立叠放）。
+ * 实例靠状态里的 `channel` 决定偏好归口，读侧乘的是同一个 `effectiveVolume`。
+ */
+import {
+  AUDIO_INSTANCE_ID_PATTERN,
+  MAX_AUDIO_INSTANCES,
+  SYS,
+  isAudioChannel,
+  isAudioInstanceId,
+  isAudioInstanceTable,
+  type AudioChannel,
+  type AudioChannelState,
+  type AudioInstanceTable,
+  type AudioInstanceState,
+  type StoryCommand,
+} from "../../../contracts/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+import {
+  AUDIO_FIELDS,
+  audioFade,
+  audioVolume,
+  isPlayState,
+  readPausedPlayStates,
+} from "./shared.ts";
+
+/**
+ * 暂停记账里实例项的键前缀。
+ *
+ * 实例 id 与通道名同字符集（`bgm` / `se` / `ambient` / `voice` 都是合法实例名），
+ * 两者共用一张记账表时不能拿裸 id 当键：通道恢复会读到某个同名实例的播放态，
+ * 把别人的资源写回自己的通道。
+ */
+const PAUSE_KEY_PREFIX = "inst:";
+
+/** 读实例表：形状不合（外部改坏）按空表处理，不让一条脏值卡死整个音频域 */
+function instanceTableOf(ctx: OpContext): AudioInstanceTable {
+  const value = ctx.get(SYS.audioInstances);
+  return isAudioInstanceTable(value) ? value : {};
+}
+
+/** 整表新建后写回：**不得原地改** `table[id].state`，否则回溯会拿到被污染的值 */
+function writeInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  instanceId: string,
+  channel: AudioChannel,
+  state: AudioChannelState,
+): void {
+  const next: Record<string, AudioInstanceState> = { ...table };
+  next[instanceId] = { channel, state };
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+}
+
+/**
+ * 音频实例 op 的执行：`audio_play` / `audio_stop` / `audio_volume`。
+ *
+ * 实例与四通道**并存**，不是替换：通道是叙事语义（bgm / se / ambient / voice，
+ * 各有一档玩家偏好），实例是作者的编排单元（数量不定、名字自起、各自独立叠放）。
+ * 实例靠状态里的 `channel` 决定偏好归口，读侧乘的是同一个 `effectiveVolume`。
+ *
+ * 三个 op 的分工：`audio_play` 创建或更新；`audio_stop` 停一个（缺 `inst` = 停全部）；
+ * `audio_volume` **只改音量，不重播也不递增 seq**——音量的变化由值比较感知，
+ * 递增序号会让渲染层误判成一次重播，把正在放的那一轨打断。
+ */
+export function execAudioInstance(ctx: OpContext, cmd: StoryCommand): boolean {
+  const known = AUDIO_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;
+  }
+  const table = instanceTableOf(ctx);
+  if (cmd.op === "audio_stop") return stopInstance(ctx, table, cmd);
+  if (cmd.op === "audio_volume") return setInstanceVolume(ctx, table, cmd);
+  return playInstance(ctx, table, cmd);
+}
+
+/** `audio_play`：创建或更新一个实例（同资源 = 更新，换资源 = 重播） */
+function playInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_play-invalid-instance",
+      `audio_play 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const channel = cmd.channel;
+  if (!isAudioChannel(channel)) {
+    ctx.fail(
+      "audio_play-invalid-channel",
+      `audio_play 的 channel 不合法：${JSON.stringify(channel)}（须为 bgm / se / ambient / voice 之一）`,
+    );
+    return false;
+  }
+  if (typeof cmd.resource !== "string" || cmd.resource === "") {
+    ctx.fail(
+      "audio_play-invalid-resource",
+      "audio_play 需要非空 resource 字符串",
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (
+    previous === undefined &&
+    Object.keys(table).length >= MAX_AUDIO_INSTANCES
+  ) {
+    // 上限在这里先拦一次（判据里也有，但那时已经写进存档了，错误发现得太晚）
+    ctx.fail(
+      "audio_play-instance-limit",
+      `音频实例已达上限 ${MAX_AUDIO_INSTANCES}：${instanceId} 无处安放（先 audio_stop 掉不用的实例）`,
+    );
+    return false;
+  }
+  const volume = audioVolume(ctx, cmd.volume, "audio_play", channel);
+  if (volume === null) return false;
+  const fade = audioFade(ctx, cmd.fade, "audio_play");
+  if (fade === null) return false;
+  const restart = cmd.restart === true;
+  const sameTrack =
+    previous !== undefined &&
+    previous.state.kind === "play" &&
+    previous.state.resource === cmd.resource;
+  const state: AudioChannelState = {
+    kind: "play",
+    resource: cmd.resource,
+    volume,
+    loop: cmd.loop !== false,
+    fadeMs: fade,
+  };
+  if (restart || !sameTrack) {
+    // 新实例 / 换资源 / 显式重播都要给一个新序号：渲染层据此判定「这是一次新的起播」
+    ctx.mediaSeq += 1;
+    state.seq = ctx.mediaSeq;
+    if (restart) state.restart = true;
+  } else if (
+    previous.state.kind === "play" &&
+    previous.state.seq !== undefined
+  ) {
+    // 同资源原地更新：**沿用旧序号**。沿用而不是省掉，是为了让「这一轨还是那一轨」
+    // 在状态里始终可辨认；不递增则保证渲染层不会把它当成一次新起播。
+    state.seq = previous.state.seq;
+  }
+  writeInstance(ctx, table, instanceId, channel, state);
+  return true;
+}
+
+/** `audio_stop`：停一个实例；缺 `inst` = 停全部实例 */
+function stopInstance(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const fade = audioFade(ctx, cmd.fade, "audio_stop");
+  if (fade === null) return false;
+  const ids = Object.keys(table);
+  if (cmd.inst === undefined) {
+    if (ids.length === 0) return true; // 没有实例可停：不是错误
+    const next: Record<string, AudioInstanceState> = { ...table };
+    for (const id of ids) {
+      ctx.mediaSeq += 1;
+      next[id] = {
+        channel: table[id]!.channel,
+        // 每个实例各领一个序号：连续两次全停必须是两次独立事件
+        state: { kind: "stop", fadeMs: fade, seq: ctx.mediaSeq },
+      };
+    }
+    ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+    return true;
+  }
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_stop-invalid-instance",
+      `audio_stop 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (previous === undefined) {
+    ctx.fail(
+      "audio_stop-unknown-instance",
+      `audio_stop 找不到实例 ${instanceId}（当前实例：${ids.join(", ") || "无"}）`,
+    );
+    return false;
+  }
+  ctx.mediaSeq += 1;
+  writeInstance(ctx, table, instanceId, previous.channel, {
+    kind: "stop",
+    fadeMs: fade,
+    seq: ctx.mediaSeq,
+  });
+  return true;
+}
+
+/** `audio_volume`：只改音量（双向闭环入口），不重播、不递增 seq */
+function setInstanceVolume(
+  ctx: OpContext,
+  table: AudioInstanceTable,
+  cmd: StoryCommand,
+): boolean {
+  const instanceId = cmd.inst;
+  if (!isAudioInstanceId(instanceId)) {
+    ctx.fail(
+      "audio_volume-invalid-instance",
+      `audio_volume 的 inst 不合法：${JSON.stringify(instanceId)}（须匹配 ${AUDIO_INSTANCE_ID_PATTERN.source}）`,
+    );
+    return false;
+  }
+  const previous = table[instanceId];
+  if (previous === undefined) {
+    ctx.fail(
+      "audio_volume-unknown-instance",
+      `audio_volume 找不到实例 ${instanceId}（当前实例：${Object.keys(table).join(", ") || "无"}）`,
+    );
+    return false;
+  }
+  if (cmd.volume === undefined) {
+    ctx.fail("audio_volume-missing-volume", "audio_volume 需要 volume");
+    return false;
+  }
+  if (previous.state.kind !== "play") {
+    ctx.fail(
+      "audio_volume-instance-stopped",
+      `实例 ${instanceId} 当前是停止状态：先 audio_play 起播再调音量`,
+    );
+    return false;
+  }
+  const volume = audioVolume(ctx, cmd.volume, "audio_volume", previous.channel);
+  if (volume === null) return false;
+  writeInstance(ctx, table, instanceId, previous.channel, {
+    ...previous.state,
+    volume,
+  });
+  return true;
+}
+
+/**
+ * 暂停全部实例：正在出声的实例转 `pause` 态，暂停前的播放态进 `SYS.audioPaused`。
+ *
+ * 常驻四通道由 `audio_pause` 覆盖，实例是另一张表，必须单独走一遍——否则
+ * 「引擎暂停」只让 BGM 收声，故事里正在放的环境音实例照旧出声。
+ * 记账与通道共用同一张表（同一概念一处声明），实例键加 `inst:` 前缀区分归属。
+ *
+ * 不经 op、直接改状态：这是引擎级暂停的内部步骤，不产生命令面的语义
+ * （作者手写的 `audio_pause` 只作用于四通道，暂停态仍由同一把「引擎已暂停」的闸门拦住推进）。
+ */
+export function pauseAudioInstances(ctx: OpContext): void {
+  const table = instanceTableOf(ctx);
+  const ids = Object.keys(table);
+  if (ids.length === 0) return;
+  const paused = readPausedPlayStates(ctx);
+  const next: Record<string, AudioInstanceState> = { ...table };
+  let changed = false;
+  for (const id of ids) {
+    const entry = table[id];
+    if (entry === undefined || !isPlayState(entry.state)) continue;
+    ctx.mediaSeq += 1;
+    paused[PAUSE_KEY_PREFIX + id] = entry.state;
+    next[id] = {
+      channel: entry.channel,
+      state: { kind: "pause", seq: ctx.mediaSeq } satisfies AudioChannelState,
+    };
+    changed = true;
+  }
+  if (!changed) return;
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+  ctx.setSystem(SYS.audioPaused, paused);
+}
+
+/**
+ * 恢复全部实例：按记账写回暂停前的播放态并递增 `seq`。
+ *
+ * 只认 `pause` 态：暂停期间被命令改成 `stop` 的实例不复活——留着一条「该出声却
+ * 永远不出声」的实例比让它停着更糟，与通道恢复同一口径。
+ */
+export function resumeAudioInstances(ctx: OpContext): void {
+  const table = instanceTableOf(ctx);
+  const ids = Object.keys(table);
+  if (ids.length === 0) return;
+  const paused = readPausedPlayStates(ctx);
+  const next: Record<string, AudioInstanceState> = { ...table };
+  let changed = false;
+  for (const id of ids) {
+    const entry = table[id];
+    if (entry === undefined || entry.state.kind !== "pause") continue;
+    const key = PAUSE_KEY_PREFIX + id;
+    const resumed = paused[key];
+    if (resumed === undefined) continue;
+    delete paused[key];
+    ctx.mediaSeq += 1;
+    next[id] = {
+      channel: entry.channel,
+      state: { ...resumed, seq: ctx.mediaSeq },
+    };
+    changed = true;
+  }
+  if (!changed) return;
+  ctx.setSystem(SYS.audioInstances, next satisfies AudioInstanceTable);
+  ctx.setSystem(SYS.audioPaused, paused);
+}

package/src/runtime/ops/media/notify.ts

@@ -0,0 +1,32 @@
+/**
+ * 出站通知：`notify` 只发事件，不碰状态（覆盖层的 toast 归宿主渲染）。
+ */
+import {
+  SYS,
+  type OutboundEvent,
+  type OutboundPayload,
+  type StoryCommand,
+} from "../../../contracts/index.ts";
+import { interpolateText } from "../../expr/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+
+/** 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);
+}

package/src/runtime/ops/media/shared.ts

@@ -0,0 +1,133 @@
+/**
+ * 媒体域共用：op 负载白名单与音量 / 淡出解析。
+ *
+ * 白名单是 fail-closed 的唯一来源——执行器只查这里，未知字段一律拒绝；
+ * 音量与淡出是音频与视频两族共用的窄化，口径必须一处（否则同一个
+ * `volume` 在两条命令上会有两种边界行为）。
+ */
+import {
+  SYS,
+  type AudioChannel,
+  type AudioChannelState,
+} from "../../../contracts/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+
+/** 音频 op 已知负载字段（未知字段 fail-closed） */
+export 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"]),
+  stop_se: new Set(["op", "fade"]),
+  voice: new Set(["op", "resource", "volume", "auto_stop", "restart"]),
+  stop_voice: new Set(["op", "fade"]),
+  audio_play: new Set([
+    "op",
+    "inst",
+    "channel",
+    "resource",
+    "volume",
+    "loop",
+    "fade",
+    "restart",
+  ]),
+  audio_stop: new Set(["op", "inst", "fade"]),
+  audio_volume: new Set(["op", "inst", "volume"]),
+  audio_pause: new Set(["op", "channel"]),
+  audio_resume: new Set(["op", "channel"]),
+};
+
+/** 停止类 op → 目标常驻通道系统键 */
+export const AUDIO_STOP_KEY: Record<string, string> = {
+  stop_bgm: SYS.audioBgm,
+  stop_ambient: SYS.audioAmbient,
+  stop_voice: SYS.audioVoice,
+};
+
+/** 音频通道 op → 常驻通道系统键（se 为一次性触发，不在表内） */
+export const AUDIO_CHANNEL_KEY: Record<string, string> = {
+  bgm: SYS.audioBgm,
+  ambient: SYS.audioAmbient,
+  voice: SYS.audioVoice,
+};
+
+/**
+ * volume 三级解析：命令显式值 ?? 工程默认（`shell.audio.volumes[通道]`）?? 1。
+ *
+ * 顺序不能反：显式值是作者在这一条命令上的意图，工程默认是整部作品的口径，
+ * 内建 1 只在前两级都缺席时兜底（与「不指定 = 满音量」的既有语义逐字节一致）。
+ * 玩家偏好不在这里——它是渲染层最外层的乘算，混进来会让「换个工程，玩家设置
+ * 被这个工程的默认值改掉」。
+ *
+ * `channel` 缺省（视频族）表示没有工程默认级：视频音量只认命令与内建 1。
+ * 非有限数字一律 fail-closed（作者写错不能静默当满音量），越界按物理范围钳制。
+ */
+export function audioVolume(
+  ctx: OpContext,
+  raw: unknown,
+  op: string,
+  channel?: AudioChannel,
+): number | null {
+  let explicit: number | undefined;
+  if (raw !== undefined) {
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      ctx.fail(`${op}-invalid-volume`, `${op} 的 volume 必须是有限数字`);
+      return null;
+    }
+    explicit = raw;
+  }
+  const fallback =
+    channel === undefined ? 1 : (ctx.audioConfig.volumes[channel] ?? 1);
+  return Math.min(1, Math.max(0, explicit ?? fallback));
+}
+
+/** fade 窄化：缺省 0；负数/非有限数字 fail-closed */
+export 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;
+}
+
+/**
+ * 播放态判定：暂停记账只记录「有东西可续播」的状态。
+ *
+ * `pause` 态本身不带资源、`stop` 态已经结束，两者都没有可写回的播放态。判据按契约
+ * 形状严格比对——记账表随快照 / 存档随行，读回来的可能是被外部改坏的值，把非 play
+ * 态当成 play 态会让恢复写回一条没有资源的播放态。
+ */
+export function isPlayState(value: unknown): value is AudioChannelState {
+  if (value === null || typeof value !== "object") return false;
+  const state = value as { kind?: unknown; resource?: unknown };
+  return state.kind === "play" && typeof state.resource === "string";
+}
+
+/**
+ * 读 `SYS.audioPaused` 暂停记账表：逐项只留 play 态，形状不合按空表处理。
+ *
+ * 同一张表按两套键空间分区存放：常驻通道项用通道名（`bgm` / `ambient` / `voice`），
+ * 音频实例项用 `inst:<实例id>`。这里原样返回全部键，由调用方按自己的键空间取值——
+ * 在读函数里按前缀过滤会让另一族读不到自己的项。
+ *
+ * 外部改坏的值一律静默过滤：一条脏值不该让整条暂停 / 恢复路径失败。
+ */
+export function readPausedPlayStates(
+  ctx: OpContext,
+): Record<string, AudioChannelState> {
+  const value = ctx.get(SYS.audioPaused);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const out: Record<string, AudioChannelState> = {};
+  for (const [key, state] of Object.entries(value as Record<string, unknown>)) {
+    if (isPlayState(state)) out[key] = state;
+  }
+  return out;
+}

package/src/runtime/ops/media/video.ts

@@ -0,0 +1,118 @@
+/**
+ * 视频族：核心只写命令流（`__video`，seq 单调），渲染器按序执行。
+ */
+import {
+  SYS,
+  type StoryCommand,
+  type VideoCommand,
+} from "../../../contracts/index.ts";
+import type { Frame, OpContext } from "../../internal/index.ts";
+import { audioVolume } from "./shared.ts";
+
+/** 视频族已知负载字段（未知字段 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"]),
+};
+
+/**
+ * 视频族：核心只写命令流（`__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;
+}

package/src/runtime/ops/ui.ts

@@ -0,0 +1,95 @@
+/**
+ * UI 挂载的执行：把「哪个组件该不该出现在渲染树上、带什么入参」写成状态。
+ *
+ * 核心只写 `SYS.mounts` 这张表，不碰 DOM、不认识组件内部——挂载与卸载是宿主的活。
+ * `visible: false` 的语义是**从渲染树移除**（卸载），不是 `display: none`：
+ * 隐藏的组件不该继续跑生命周期与计时器。整表随快照 / 存档 / 回溯自动随行。
+ */
+import {
+  SYS,
+  type MountTable,
+  type StoryCommand,
+} from "../../contracts/index.ts";
+import { isMountTable, isUiName, UI_NAME_PATTERN } from "../../shared/index.ts";
+import { findJsonValueError } from "../state/stateContract.ts";
+import type { OpContext } from "../internal/index.ts";
+
+/** `mount` 已知负载字段（未知字段 fail-closed） */
+const MOUNT_OP_FIELDS: ReadonlySet<string> = new Set([
+  "op",
+  "name",
+  "visible",
+  "props",
+]);
+
+/** 读挂载表：形状不合（外部改坏）按空表处理，不让一条脏值卡死整个挂载域 */
+function mountTableOf(ctx: OpContext): MountTable {
+  const value = ctx.get(SYS.mounts);
+  return isMountTable(value) ? value : {};
+}
+
+/**
+ * 挂载 / 卸载一个 UI 组件：`mount(hub, true)`、`mount(hub, false, { scene: "forest" })`。
+ *
+ * - `visible` 必填布尔：没有「切换」语义，显式写显隐才能让回溯读到确定的终值
+ * - `props` 可选：给了就**整份替换**（不是浅合并）——合并语义会让「删掉一个入参」
+ *   无法表达，而组件的入参集合是它的契约，得能完整指定
+ * - 整表新建后写回：**不得原地改** `table[name]`，否则回溯会拿到被污染的值
+ */
+export function execMount(ctx: OpContext, cmd: StoryCommand): boolean {
+  const unknown = Object.keys(cmd).filter((k) => !MOUNT_OP_FIELDS.has(k));
+  if (unknown.length > 0) {
+    ctx.fail(
+      "mount-unknown-field",
+      `mount 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const { name, visible } = cmd;
+  if (!isUiName(name)) {
+    ctx.fail(
+      "mount-invalid-name",
+      `mount 的 name 不合法：${JSON.stringify(name)}（须匹配 ${UI_NAME_PATTERN.source}）`,
+    );
+    return false;
+  }
+  if (typeof visible !== "boolean") {
+    ctx.fail(
+      "mount-invalid-visible",
+      `mount 的 visible 必须是布尔：${JSON.stringify(visible)}`,
+    );
+    return false;
+  }
+  const rawProps = cmd.props;
+  let props: Record<string, unknown> = {};
+  if (rawProps !== undefined) {
+    if (
+      typeof rawProps !== "object" ||
+      rawProps === null ||
+      Array.isArray(rawProps)
+    ) {
+      ctx.fail(
+        "mount-invalid-props",
+        `mount 的 props 必须是对象：${JSON.stringify(rawProps)}`,
+      );
+      return false;
+    }
+    const unsafe = findJsonValueError(rawProps, "mount.props");
+    if (unsafe !== null) {
+      ctx.fail(
+        "mount-unsafe-props",
+        `mount 的 props 不是 JSON 安全的值——${unsafe}`,
+      );
+      return false;
+    }
+    props = rawProps as Record<string, unknown>;
+  }
+  const table = mountTableOf(ctx);
+  const next: Record<
+    string,
+    { visible: boolean; props: Record<string, unknown> }
+  > = { ...table };
+  next[name] = { visible, props };
+  ctx.setSystem(SYS.mounts, next satisfies MountTable);
+  return true;
+}