@lingfan-engine/ui 0.1.5 → 0.3.0

package/src/mount/selection.ts

@@ -0,0 +1,61 @@
+/**
+ * 挂载选择：把「可见集合」和「名字 → 组件」表合成一份可直接渲染的清单。
+ *
+ * 三种宿主形态的模板各写一遍「按名字取组件、取不到就跳过」的后果不是代码重复，
+ * 而是同一份存档在三种宿主上挂出不同的组件集合——取不到时一种静默跳过、另一种抛错，
+ * 排查起来就是三套现象。选择逻辑收在这里，模板只负责把清单铺到自己的渲染树上。
+ *
+ * 取不到组件一律 fail-closed：**不渲染**那一条，并**逐条上报**名字。
+ * 静默跳过是这里最坏的选项——作者写了 `mount hub true` 却没看见组件，无从下手；
+ * 抛错则会让一个笔误黑掉整屏。上报走注入的回调，宿主决定写错误条还是打控制台。
+ */
+import { isMountTable } from "@lingfan-engine/core";
+import { mountProps, visibleMounts } from "./projection.ts";
+
+/** 一条可渲染的挂载：名字、组件本身、完整入参 */
+export interface MountSelection {
+  /** UI 名（= `src/ui/` 下的目录名，也是 `SYS.mounts` 的键） */
+  readonly name: string;
+  /** 组件：Vue / React 形态是组件对象，原生形态是工厂函数；本域不解释它 */
+  readonly component: unknown;
+  /** 该 UI 这一帧的完整入参（不可见时不会有这一条） */
+  readonly props: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 算出这一帧该渲染哪些 UI。
+ *
+ * @param raw `SYS.mounts` 的原始值（脏值按空表，不抛）
+ * @param table 「名字 → 组件」表（生成物 `uis`）
+ * @param onMissing 取不到组件时的上报口；缺省只静默跳过（不建议——见文件头）
+ */
+export function selectMounts(
+  raw: unknown,
+  table: Readonly<Record<string, unknown>>,
+  onMissing?: (name: string) => void,
+): readonly MountSelection[] {
+  const out: MountSelection[] = [];
+  for (const name of visibleMounts(raw)) {
+    const component = table[name];
+    if (component === undefined) {
+      onMissing?.(name);
+      continue;
+    }
+    out.push({ name, component, props: mountProps(raw, name) ?? {} });
+  }
+  return out;
+}
+
+/**
+ * 表里没有这个名字的可见 UI 名单（宿主用它做一次性诊断，避免每帧重复上报）。
+ *
+ * `selectMounts` 的 `onMissing` 是逐帧回调，命令式宿主适合直接接；
+ * 声明式宿主按帧重渲染，重复上报会刷屏——用它算「稳定差集」再自己决定上报时机。
+ */
+export function missingMounts(
+  raw: unknown,
+  table: Readonly<Record<string, unknown>>,
+): readonly string[] {
+  if (!isMountTable(raw)) return [];
+  return visibleMounts(raw).filter((name) => table[name] === undefined);
+}

package/src/mount/store.ts

@@ -0,0 +1,54 @@
+/**
+ * 挂载表订阅：把 `SYS.mounts` 的变化做成一个**宿主无关**的可订阅值。
+ *
+ * 三种宿主形态要的是同一件事——「现在该挂谁、各自带什么入参」，但拿值的方式不同：
+ * 命令式宿主（原生 DOM）要一个回调去算差量，声明式宿主（Vue / React）要一个能进各自
+ * 响应式系统的快照 + 订阅对。这里只提供最小面：`snapshot()` 读当前值、`subscribe()`
+ * 订阅变化、`set()` 由装配处把引擎状态推进来。
+ *
+ * 为什么不让各形态自己订阅引擎：订阅与退订就成了三份实现，任何一份漏掉退订都会在
+ * 页面拆掉之后继续往已销毁的渲染树里写。值在这里只有一条通路。
+ *
+ * 本文件不碰 DOM、不认识框架、没有模块级可变状态——一个 store 的全部状态都在闭包里。
+ */
+
+/** 只读视图：声明式宿主拿它渲染，命令式宿主拿它算差量 */
+export interface MountSource {
+  /** 当前 `SYS.mounts` 原始值；引擎还没写过时是 `undefined` */
+  snapshot(): unknown;
+  /** 订阅变化，返回退订函数。订阅时**不**立刻回调——调用方先自己读一次快照 */
+  subscribe(listener: (raw: unknown) => void): () => void;
+}
+
+/** 可写视图：只有装配处拿得到，写入口不在渲染器手里 */
+export interface MountStore extends MountSource {
+  /** 写入新值；与当前值是同一个引用时不通知（引擎写侧本就是整表新建） */
+  set(raw: unknown): void;
+}
+
+/**
+ * 造一个挂载表 store。
+ *
+ * @param initial 初始值；缺省 `undefined` 即「引擎还没报过」，投影按空表处理
+ */
+export function createMountStore(initial?: unknown): MountStore {
+  let current: unknown = initial;
+  const listeners = new Set<(raw: unknown) => void>();
+  return {
+    snapshot(): unknown {
+      return current;
+    },
+    set(raw: unknown): void {
+      if (Object.is(raw, current)) return;
+      current = raw;
+      // 复制一份再遍历：监听器里退订自己是常见写法，直接遍历 Set 会跳过后一个
+      for (const listener of [...listeners]) listener(current);
+    },
+    subscribe(listener: (raw: unknown) => void): () => void {
+      listeners.add(listener);
+      return (): void => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/overlay/choices-view.ts

@@ -15,6 +15,8 @@ export interface ChoicesRenderInput {
   menuPrompt: string;
   menuOptions: readonly { text: string; target: string }[];
   inputPrompt: string;
+  /** 输入候选（缺省空数组 = 只有输入框） */
+  inputCandidates?: readonly { text: string; value: string }[];
 }
 
 /** 选择层文案（宿主可覆盖；缺省实现即内建文案） */
@@ -50,11 +52,20 @@ export function choicesLayerView(
 ): ChoicesLayerView | null {
   if (input.waiting === "input") {
     const texts: ChoicesTexts = { ...DEFAULT_CHOICES_TEXTS, ...deps.texts };
+    // 候选与输入框并存：玩家可以点候选，也可以自己打字（两者走同一个提交出口）
+    const candidates = (input.inputCandidates ?? []).map((item) => ({
+      label: item.text,
+      value: item.value,
+    }));
     return {
       rootClass: "",
       promptHtml: "",
       options: [],
-      input: { prompt: input.inputPrompt, submitText: texts.inputSubmit },
+      input: {
+        prompt: input.inputPrompt,
+        submitText: texts.inputSubmit,
+        candidates,
+      },
     };
   }
   if (input.waiting !== "menu") return null;

package/src/overlay/create.ts

@@ -29,7 +29,7 @@ import { isGameInputTarget } from "../input/scope";
 import { createElementRegistry } from "../element/registry";
 import type { ElementRegistry } from "../element/registry";
 import { registerBuiltinElementRenderers } from "../element";
-import { DEFAULT_NOTIFY_MS } from "../host/duration";
+import { DEFAULT_NOTIFY_MS, DEFAULT_TEXT_CPS } from "../host/duration";
 import { choicesLayerView } from "./choices-view";
 import type { ChoicesViewDeps } from "./choices-view";
 import { dialogueLayerView } from "./dialogue-view";
@@ -72,7 +72,7 @@ export function createNarrativeOverlay(
   const reader = createStateReader(engine);
 
   const elements = options.elementRegistry ?? createBuiltinElementRegistry();
-  const textSpeed = options.textSpeed ?? 30;
+  const textSpeed = options.textSpeed ?? DEFAULT_TEXT_CPS;
 
   const layerZController = createLayerZController(surface, layerZ);
   // 表面可能由宿主先建（那时还不知道本实例的层默认表）：构造末尾统一下发一次，
@@ -138,6 +138,7 @@ export function createNarrativeOverlay(
           menuPrompt: s.menuPrompt,
           menuOptions: s.menuOptions,
           inputPrompt: s.inputPrompt,
+          inputCandidates: s.inputCandidates,
         },
         choicesDeps,
       ),

package/src/overlay/projector.ts

@@ -43,6 +43,8 @@ export interface RenderState {
   menuPrompt: string;
   menuOptions: Array<{ text: string; target: string }>;
   inputPrompt: string;
+  /** 输入候选（显示文本与要填的值成对；空数组 = 只有输入框） */
+  inputCandidates: Array<{ text: string; value: string }>;
   nvlMode: string;
   nvlBuffer: string[];
   elementList: ElementInstance[];
@@ -103,6 +105,7 @@ export function createProjector(deps: {
     menuPrompt: "",
     menuOptions: [],
     inputPrompt: "",
+    inputCandidates: [],
     nvlMode: "none",
     nvlBuffer: [],
     elementList: [],
@@ -190,6 +193,10 @@ export function createProjector(deps: {
       state.inputPrompt = reader.inputPrompt();
       return { kind: "render", targets: ["choices"] };
     }
+    if (key === SYS.inputOptions) {
+      state.inputCandidates = reader.inputCandidates();
+      return { kind: "render", targets: ["choices"] };
+    }
     if (key === SYS.nvlMode) {
       const next = reader.nvlMode();
       state.nvlMode = next === "" ? "none" : next;
@@ -218,6 +225,7 @@ export function createProjector(deps: {
     state.menuPrompt = reader.menuPrompt();
     readMenuOptions();
     state.inputPrompt = reader.inputPrompt();
+    state.inputCandidates = reader.inputCandidates();
     const mode = reader.nvlMode();
     state.nvlMode = mode === "" ? "none" : mode;
     state.nvlBuffer = reader.nvlLines();

package/src/overlay/surface.ts

@@ -62,6 +62,19 @@ export interface ChoicesLayerInput {
   prompt: string;
   /** 提交按钮显示文本 */
   submitText: string;
+  /**
+   * 候选快捷值（缺省空数组 = 只有输入框）：点一项即把该项 `value` 当输入值提交，
+   * 输入框仍可用。`label` 是显示文本（可能已翻译），`value` 是要写进变量的原样值。
+   */
+  candidates: readonly ChoicesLayerCandidate[];
+}
+
+/** 输入候选（显示文本与要填的值成对；与菜单选项不同——它不跳列，只替玩家填值） */
+export interface ChoicesLayerCandidate {
+  /** 显示文本（已走翻译；也用作按钮的可访问名） */
+  label: string;
+  /** 要填进变量的原样值（不进翻译表） */
+  value: string;
 }
 
 /**

package/src/save/continue.ts

@@ -0,0 +1,55 @@
+/**
+ * 「继续」该读哪一个槽：从存档摘要里挑出最近写入的那一槽。
+ *
+ * 为什么需要这一层：槽位清单由工程配置决定（`shell.saves.slots` → `slot_1..slot_N`），
+ * 而「哪个槽最近存过」只有存档端口知道（`SavePort.list()`）。宿主入口要的是**一个槽名**
+ * 或**没有槽**这两件事，中间的挑选规则归这里，各形态共用。
+ *
+ * 三条口径：
+ * - **只认配置内的槽**：`list()` 可能返回历史遗留的槽名（改过槽位数的工程），
+ *   不在当前清单里的一律不选——跳到一个界面上根本看不见的槽是没法解释的行为。
+ * - **按写入时间取最大**：`timestamp` 是毫秒时间戳；相同时间取清单里靠前的那个，
+ *   保证同一份摘要集必得同一结果（否则「继续」会随机跳两个槽）。
+ * - **没有可用摘要 = 不可点**：空数组是合法返回值（不是错误），
+ *   调用方据此置 `disabled` 并显示一行提示，不静默。
+ */
+import type { SlotSummary } from "@lingfan-engine/core";
+
+/**
+ * 挑出「继续」该读的槽。
+ *
+ * @param summaries 存档端口的摘要表（`SavePort.list()` 的结果，可能是空数组）。
+ * @param slots 当前工程的槽名清单（`slotIds(resolveSavesConfig(manifest).slots)`）。
+ * @returns 最近写入且在当前清单内的那条摘要；没有则 `undefined`。
+ * @example
+ * latestSave([{ slot: "slot_1", saveCount: 2, timestamp: 100, mode: "portable" }], ["slot_1", "slot_2"]);
+ * // → slot_1 那条
+ */
+export function latestSave(
+  summaries: readonly SlotSummary[],
+  slots: readonly string[],
+): SlotSummary | undefined {
+  const allowed = new Set(slots);
+  let best: SlotSummary | undefined;
+  for (const summary of summaries) {
+    if (!allowed.has(summary.slot)) continue;
+    if (best === undefined || summary.timestamp > best.timestamp)
+      best = summary;
+  }
+  return best;
+}
+
+/**
+ * 「继续」的可用状态：可读的槽名 + 要不要置灰。
+ *
+ * @param summaries 存档端口的摘要表。
+ * @param slots 当前工程的槽名清单。
+ * @returns `slot` 为 `undefined` 时按钮必须 `disabled`。
+ */
+export function continueSlot(
+  summaries: readonly SlotSummary[],
+  slots: readonly string[],
+): { readonly slot: string | undefined } {
+  const found = latestSave(summaries, slots);
+  return { slot: found?.slot };
+}

package/src/save/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 存档域出口：只放「读存档摘要之后怎么用」的纯逻辑，不碰 `SavePort` 实现。
+ *
+ * 端口实现（localStorage / Rust 命令 / 别的）在各平台适配器里；这里回答的是
+ * 与平台无关的问题——「哪一槽是最近写入的、宿主入口该不该可点」。
+ */
+export { continueSlot, latestSave } from "./continue.ts";

package/src/video/videoView.ts

@@ -6,6 +6,7 @@
  * 性能：sync 仅由 `__video` 事件与显式调用触发（回溯/读档后对齐），非逐帧。
  */
 import type {
+  PlayerPreferences,
   ResourcePort,
   VideoCommand,
   VideoPort,
@@ -23,6 +24,11 @@ export interface VideoRendererOptions {
   onError?: (message: string) => void;
   /** cutscene 自然播放结束（引擎据此解除 video 等待） */
   onVideoFinished?: () => void;
+  /**
+   * 玩家偏好：视频音轨按 `bgm` 通道的偏好音量衰减（视频没有独立通道，
+   * 且音轨语义属「背景音」）。不传 = 不衰减，行为与未接偏好时一致。
+   */
+  preferences?: PlayerPreferences;
 }
 
 /**
@@ -63,6 +69,13 @@ export function createVideoRenderer(
     }
   }
 
+  /** 播放命令的生效音量：op 音量 × `bgm` 通道偏好（静音由 effectiveVolume 归零） */
+  function effectiveVolume(volume: number): number {
+    const pref = options.preferences?.effectiveVolume("bgm");
+    if (pref === undefined || pref === 1) return volume;
+    return Math.min(1, Math.max(0, volume * pref));
+  }
+
   function execute(command: VideoCommand): void {
     generation += 1;
     const gen = generation;
@@ -71,7 +84,7 @@ export function createVideoRenderer(
         if (url === null || generation !== gen) return; // 已被更新命令取代
         port.play(
           url,
-          { volume: command.volume, loop: command.loop },
+          { volume: effectiveVolume(command.volume), loop: command.loop },
           command.cutscene ? () => options.onVideoFinished?.() : undefined,
         );
       });
@@ -109,12 +122,20 @@ export function createVideoRenderer(
   const off = engine.onStateChanged((change) => {
     if (change.key === SYS.video) sync();
   });
+  // 偏好变化：只调音量不重播（过场正在放时重播会把玩家看到的画面打断）
+  const offPrefs =
+    options.preferences?.onChange(() => {
+      const command = reader.videoCommand();
+      if (command === null || command.kind !== "play") return;
+      port.setVolume?.(effectiveVolume(command.volume));
+    }) ?? null;
   sync();
 
   return {
     sync,
     dispose(): void {
       off();
+      offPrefs?.();
       for (const url of urls.values()) resources.release(url);
       urls.clear();
     },

package/src/audio/audio.ts

@@ -1,331 +0,0 @@
-/**
- * 音频渲染：核心只写状态，此处把状态差量翻译成端口动作（可测纯逻辑），
- * 由适配器（infra/audioPort）落地播放；资源寻址经 ResourcePort，
- * 播放位置回写走帧级键。
- *
- * 状态经引擎的类型化读口读取（`createStateReader`）：通道形状校验与降级在引擎侧
- * 只有一份，本层只负责「差量 → 端口动作」。
- */
-import type {
-  AudioChannel,
-  AudioChannelState,
-  AudioPort,
-  PlayerPreferences,
-  ResourcePort,
-  StoryEngine,
-} from "@lingfan-engine/core";
-import { createStateReader, SYS } from "@lingfan-engine/core";
-import { createResourceUrlCache } from "../resources";
-
-/** 渲染视图：四通道状态 + bgm 播放位置（帧级键直读，不进事件流） */
-export interface AudioView {
-  bgm: AudioChannelState | null;
-  ambient: AudioChannelState | null;
-  voice: AudioChannelState | null;
-  se: AudioChannelState | null;
-  bgmPosition: number;
-}
-
-/** 端口动作：play = 播放/更新/定位/重播，stop = 停止（fadeMs 淡出） */
-export type AudioAction =
-  | {
-      type: "play";
-      channel: AudioChannel;
-      resource: string;
-      volume: number;
-      loop: boolean;
-      position: number;
-      fadeMs: number;
-      /** true = 回到 position 重播；false = 同资源无缝续播/更新 */
-      restart: boolean;
-    }
-  | { type: "stop"; channel: AudioChannel; fadeMs: number };
-
-/**
- * `AudioAction` 中 play 分支的别名（按 `type` 判别后的收窄形态）。
- * 它不是新的动作形状，字段仍以 `AudioAction` 的 play 分支为唯一来源，只是给
- * 「已经排除了 stop」的本地执行边界一个名字：`apply` 处理掉 stop 后把剩下的交给
- * `playAction` 逐条落地播放，参数用它写明「这里拿到的必然是 play」。
- */
-type PlayAction = Extract<AudioAction, { type: "play" }>;
-
-/** 常驻通道（se 为一次性触发，单独按 seq 判定） */
-const CHANNELS = ["bgm", "ambient", "voice"] as const;
-
-/** 位置差异阈值（秒）：小于此视为播放器噪声，不打断播放（seek 抖动防护） */
-const SEEK_THRESHOLD = 0.5;
-
-/** 空视图：渲染器初始差量基准（组合根创建顺序无关，引擎已推进也能补播） */
-export const EMPTY_AUDIO_VIEW: AudioView = {
-  bgm: null,
-  ambient: null,
-  voice: null,
-  se: null,
-  bgmPosition: 0,
-};
-
-/** 有效音量合成末端：op 音量 × 通道偏好（prefs 缺省/偏好 1 = 原样，不复制对象） */
-function withPrefs(
-  state: AudioChannelState | null,
-  pref: number | undefined,
-): AudioChannelState | null {
-  if (state === null || state.kind !== "play") return state;
-  if (pref === undefined || pref === 1) return state;
-  return { ...state, volume: Math.min(1, Math.max(0, state.volume * pref)) };
-}
-
-/** prefs 存在时各通道合成玩家有效音量（偏好在视图层落地，planAudioActions 差量自动感知） */
-export function readAudioView(
-  engine: StoryEngine,
-  prefs?: PlayerPreferences,
-): AudioView {
-  const reader = createStateReader(engine);
-  return {
-    bgm: withPrefs(reader.audioChannel("bgm"), prefs?.effectiveVolume("bgm")),
-    ambient: withPrefs(
-      reader.audioChannel("ambient"),
-      prefs?.effectiveVolume("ambient"),
-    ),
-    voice: withPrefs(
-      reader.audioChannel("voice"),
-      prefs?.effectiveVolume("voice"),
-    ),
-    se: withPrefs(reader.audioChannel("se"), prefs?.effectiveVolume("se")),
-    bgmPosition: reader.mediaPosition(),
-  };
-}
-
-/**
- * 状态差量 → 端口动作：
- * - 通道由 play 变 stop/null → stop（带淡出参数）
- * - 换资源 → play（bgm 从目标位置起播）
- * - 同资源 + 显式 restart（seq 变化）→ play 回到起点重播
- * - 同资源仅音量/循环变化 → play 更新（适配器不重头播）；bgm 位置差超阈值 → 定位
- * - se 按单调 seq 判定：每次执行都触发一次（同一资源连续触发亦然）
- */
-export function planAudioActions(
-  prev: AudioView,
-  next: AudioView,
-): AudioAction[] {
-  const actions: AudioAction[] = [];
-  for (const channel of CHANNELS) {
-    const before = prev[channel];
-    const after = next[channel];
-    if (after === null || after.kind !== "play") {
-      if (before !== null && before.kind === "play") {
-        actions.push({
-          type: "stop",
-          channel,
-          fadeMs: after !== null && after.kind === "stop" ? after.fadeMs : 0,
-        });
-      }
-      continue;
-    }
-    const position = channel === "bgm" ? next.bgmPosition : 0;
-    const sameResource =
-      before !== null &&
-      before.kind === "play" &&
-      before.resource === after.resource;
-    if (!sameResource) {
-      actions.push({
-        type: "play",
-        channel,
-        resource: after.resource,
-        volume: after.volume,
-        loop: after.loop,
-        position,
-        fadeMs: after.fadeMs,
-        restart: true,
-      });
-      continue;
-    }
-    // 同资源：显式重播优先于增量更新（seq 变化 = 这是一次新的重播请求）
-    if (after.restart === true && after.seq !== before.seq) {
-      actions.push({
-        type: "play",
-        channel,
-        resource: after.resource,
-        volume: after.volume,
-        loop: after.loop,
-        position: 0,
-        fadeMs: after.fadeMs,
-        restart: true,
-      });
-      continue;
-    }
-    if (before.volume !== after.volume || before.loop !== after.loop) {
-      actions.push({
-        type: "play",
-        channel,
-        resource: after.resource,
-        volume: after.volume,
-        loop: after.loop,
-        position,
-        fadeMs: after.fadeMs,
-        restart: false,
-      });
-      continue;
-    }
-    if (
-      channel === "bgm" &&
-      Math.abs(next.bgmPosition - prev.bgmPosition) > SEEK_THRESHOLD
-    ) {
-      actions.push({
-        type: "play",
-        channel,
-        resource: after.resource,
-        volume: after.volume,
-        loop: after.loop,
-        position,
-        fadeMs: 0,
-        restart: false,
-      });
-    }
-  }
-  const beforeSe = prev.se;
-  const afterSe = next.se;
-  if (
-    afterSe !== null &&
-    afterSe.kind === "play" &&
-    (beforeSe === null ||
-      beforeSe.kind !== "play" ||
-      beforeSe.seq !== afterSe.seq)
-  ) {
-    actions.push({
-      type: "play",
-      channel: "se",
-      resource: afterSe.resource,
-      volume: afterSe.volume,
-      loop: false,
-      position: 0,
-      fadeMs: 0,
-      restart: true,
-    });
-  }
-  return actions;
-}
-
-/** 音频渲染器：订阅通道事件 → 差量应用；位置回写由帧循环驱动 */
-export interface AudioRenderer {
-  /** 与引擎状态对齐（订阅外的显式同步，如读档/回溯完成） */
-  sync(): void;
-  /** 帧循环回写播放位置：帧级键静默写，不进事件流 */
-  pollPosition(): void;
-  dispose(): void;
-}
-
-/**
- * 宿主侧回调：解析失败的诊断出口；不传则该失败被静默忽略。
- * `preferences` 是唯一的可选注入——不传即无偏好，音量按引擎状态算。
- */
-export interface AudioRendererOptions {
-  /** 资源解析失败诊断（报错诊断：不静默吞错） */
-  onError?: (message: string) => void;
-  /** 玩家偏好（可选）：合成通道有效音量；偏好变化即时重规划（滑块/静音即时生效） */
-  preferences?: PlayerPreferences;
-}
-
-/**
- * 造一个音频渲染器并立即订阅四条通道的音频状态（构造末尾先自同步一次）。
- *
- * 它按通道分代际，迟到的旧解析结果不误播；资源 URL 经共享缓存取，`dispose` 时
- * 逐个 `resources.release` 并退订。位置回写不由本层计时——宿主每帧调 `pollPosition`。
- */
-export function createAudioRenderer(
-  engine: StoryEngine,
-  port: AudioPort,
-  resources: ResourcePort,
-  options: AudioRendererOptions = {},
-): AudioRenderer {
-  const audioKeys = new Set<string>([
-    SYS.audioBgm,
-    SYS.audioSe,
-    SYS.audioAmbient,
-    SYS.audioVoice,
-  ]);
-  const reader = createStateReader(engine);
-  let view: AudioView = EMPTY_AUDIO_VIEW;
-  /**
-   * 已解析 URL 缓存（逻辑资源 → URL）：常驻曲目复用解析结果，会话结束统一 release。
-   * 不做引用计数/中途回收——VN 的资源集合有界，改用 LRU + refcount 的前提是长会话大量换曲。
-   */
-  const urls = createResourceUrlCache((resource) =>
-    resources.resolve(resource),
-  );
-  /** 每通道动作代际：异步解析落地时若已被更新动作/停止取代，丢弃该次播放（防错播） */
-  const generations = new Map<AudioChannel, number>();
-
-  function invalidate(channel: AudioChannel): void {
-    generations.set(channel, (generations.get(channel) ?? 0) + 1);
-  }
-
-  async function resolveUrl(resource: string): Promise<string | null> {
-    try {
-      return await urls.resolve(resource);
-    } catch (e) {
-      options.onError?.(`资源解析失败：${resource}（${String(e)}）`);
-      return null; // fail-closed：不播放（诊断已上报，不静默）
-    }
-  }
-
-  async function playAction(action: PlayAction): Promise<void> {
-    // se 为一次性触发：每次独立播放，不参与代际取消（允许叠放）
-    const guarded = action.channel !== "se";
-    if (guarded) invalidate(action.channel);
-    const generation = generations.get(action.channel);
-    const url = await resolveUrl(action.resource);
-    if (url === null) return;
-    if (guarded && generations.get(action.channel) !== generation) return;
-    port.play(action.channel, url, {
-      volume: action.volume,
-      loop: action.loop,
-      position: action.position,
-      fadeMs: action.fadeMs,
-      restart: action.restart,
-    });
-  }
-
-  function apply(actions: AudioAction[]): void {
-    for (const action of actions) {
-      if (action.type === "stop") {
-        invalidate(action.channel); // 停止使在途解析作废
-        port.stop(action.channel, action.fadeMs);
-        continue;
-      }
-      void playAction(action);
-    }
-  }
-
-  function sync(): void {
-    const next = readAudioView(engine, options.preferences);
-    apply(planAudioActions(view, next));
-    view = next;
-  }
-
-  const offState = engine.onStateChanged((change) => {
-    if (audioKeys.has(change.key)) sync();
-  });
-  // 偏好变化（滑块/静音）→ 合成音量差量 → play 更新动作（同资源不重播）
-  const offPrefs = options.preferences?.onChange(() => sync()) ?? null;
-  sync();
-
-  return {
-    sync,
-    pollPosition(): void {
-      const bgm = reader.audioChannel("bgm");
-      if (bgm === null || bgm.kind !== "play") return;
-      const seconds = port.position("bgm");
-      if (seconds <= 0) return;
-      engine.reportMediaPosition(seconds);
-      // 同步视图：避免下一帧把自身回写当成 seek 目标
-      view = { ...view, bgmPosition: seconds };
-    },
-    dispose(): void {
-      offState();
-      offPrefs?.();
-      for (const url of urls.values()) resources.release(url);
-      urls.clear();
-      generations.clear();
-    },
-  };
-}