@lingfan-engine/ui 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 MoFeng-02
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@lingfan-engine/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "description": "灵泛叙事引擎参考展示层：框架无关的可测纯逻辑（内联标记、打字机、音频差量规划）",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@lingfan-engine/core": "^0.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MoFeng-02/LingFan.Engine.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/MoFeng-02/LingFan.Engine#readme",
+  "bugs": {
+    "url": "https://github.com/MoFeng-02/LingFan.Engine/issues"
+  },
+  "keywords": [
+    "narrative",
+    "ui",
+    "dialogue",
+    "typewriter",
+    "framework-agnostic"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/audio/audio.ts

@@ -0,0 +1,331 @@
+/**
+ * 音频渲染：核心只写状态，此处把状态差量翻译成端口动作（可测纯逻辑），
+ * 由适配器（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();
+    },
+  };
+}

package/src/audio/index.ts

@@ -0,0 +1,11 @@
+/** 音频渲染域出口：状态差量规划器 + 渲染器（可测纯逻辑，播放归适配器）。 */
+export {
+  EMPTY_AUDIO_VIEW,
+  createAudioRenderer,
+  planAudioActions,
+  readAudioView,
+  type AudioAction,
+  type AudioRenderer,
+  type AudioRendererOptions,
+  type AudioView,
+} from "./audio";

package/src/choices/index.ts

@@ -0,0 +1,10 @@
+/** 选择层挂载点出口（模板注册制）。 */
+export {
+  builtinChoiceTemplate,
+  createChoiceTemplateRegistry,
+  type ChoiceTemplateFn,
+  type ChoiceTemplateInput,
+  type ChoiceTemplateOption,
+  type ChoiceTemplateRegistry,
+  type ChoiceTemplateView,
+} from "./templates";

package/src/choices/templates.ts

@@ -0,0 +1,74 @@
+/**
+ * 选择层模板（挂载点模板的一例：提示行 + 选项列表 + rootClass 皮肤）。
+ *
+ * 骨架挂点（宿主渲染固定结构，模板只填内容）：
+ * - 提示行（`promptHtml`；空串 = 隐藏该行）
+ * - 选项列表（`options`：每项文本与可选禁用态；**点击与目标解析归宿主**，
+ *   模板不参与交互语义——那是核心层的 `choose(target)`）
+ *
+ * 与 Ren'Py `choice` screen 的差别：它的 `items` 里带 `action` 对象（可执行副作用），
+ * 本模板只给「渲染所需的数据」，动作仍由宿主 `choose(target)` 走核心语义——
+ * 模板无法绕过引擎改变叙事流向，破坏面因此被限制在展示层。
+ *
+ * 未知名 / null 回退默认（模板只影响展示，缺失应兜底——与元素/小游戏注册表的
+ * fail-closed 口径不同）。
+ */
+import {
+  TemplateRegistry,
+  createTemplateRegistry,
+} from "../templates/registry";
+import { renderDialogueLine } from "../dialogue/textView";
+
+/** 单个选项的渲染投影（宿主从 `SYS.menuOptions` 映射） */
+export interface ChoiceTemplateOption {
+  /** 选项文本（原文；经统一接缝渲染） */
+  text: string;
+  /** 选项目标列 id（宿主点击时交核心 `choose(target)`；模板不得改写） */
+  target: string;
+}
+
+/** 选择层模板输入：宿主投影的渲染状态 */
+export interface ChoiceTemplateInput {
+  /** 插值后的菜单提示（空 = 无提示行） */
+  prompt: string;
+  /** 选项列表（顺序即呈现顺序） */
+  options: readonly ChoiceTemplateOption[];
+  /** 当前所属场景（可选；模板可用于分场景换装） */
+  scene?: string;
+}
+
+/** 选择层模板输出：语义骨架各挂点内容 */
+export interface ChoiceTemplateView {
+  /** 选择层根皮肤类（宿主布局类叠加） */
+  rootClass: string;
+  /** 提示行 HTML（空串 = 隐藏）；经统一接缝转义 */
+  promptHtml: string;
+  /** 选项行 HTML 列表（与 `options` 等长、同序——宿主按序挂点击） */
+  optionHtml: readonly string[];
+}
+
+/** 选择层模板：吃投影出的选项状态，吐骨架各挂点内容。纯函数——不挂点击、不改 `target` */
+export type ChoiceTemplateFn = (
+  input: ChoiceTemplateInput,
+) => ChoiceTemplateView;
+
+/** 选择层模板注册表：按名存 `ChoiceTemplateFn`，按名解析，未知名回退默认 */
+export type ChoiceTemplateRegistry = TemplateRegistry<
+  ChoiceTemplateInput,
+  ChoiceTemplateView
+>;
+
+/** 造一张空的选择层模板注册表；宿主在装配期向它 `register` 模板（本函数不装内建默认） */
+export function createChoiceTemplateRegistry(): ChoiceTemplateRegistry {
+  return createTemplateRegistry<ChoiceTemplateInput, ChoiceTemplateView>();
+}
+
+/** 内置默认模板：提示行 + 逐项转义文本（与既有参考实现等价） */
+export const builtinChoiceTemplate: ChoiceTemplateFn = (input) => ({
+  rootClass: "tpl-choice",
+  promptHtml:
+    input.prompt === "" ? "" : renderDialogueLine({ text: input.prompt }).html,
+  optionHtml: input.options.map(
+    (opt) => renderDialogueLine({ text: opt.text }).html,
+  ),
+});

package/src/commands/index.ts

@@ -0,0 +1,6 @@
+/** 宿主命名命令域出口。 */
+export {
+  createCommandRegistry,
+  type CommandRegistry,
+  type NamedCommandHandler,
+} from "./registry";