@lingfan-engine/ui 0.0.0-stage → 0.1.0

package/src/templates/registry.ts

@@ -0,0 +1,79 @@
+/**
+ * 挂载点模板注册表（通用形态：语义骨架挂点 + 皮肤类）。
+ *
+ * 每个渲染挂载点（对话 / 选择 / 通知 / …）都有自己的 `TemplateInput`（宿主投影的渲染状态）
+ * 与 `TemplateView`（各挂点内容 + 根皮肤类）。本类只承载**注册与解析语义**，
+ * 与具体挂载点无关：
+ * - 空名 = 「无模板」哨兵，不可被注册占用（`resolve("")` 始终走默认）
+ * - 未知名 / null / undefined = 回退默认（展示层缺失应有兜底）
+ * - 未设默认 = `null`（宿主用自己的内建实现兜底）
+ *
+ * **与元素/小游戏注册表的口径差异**：那些是 `fail-closed`（未知类型/未注册命令不伪造），
+ * 本表是 `fail-soft`——模板只影响「长什么样」，缺失回退默认不会伪造语义。
+ */
+export interface TemplateViewBase {
+  /** 根皮肤类（宿主布局类之上叠加） */
+  rootClass: string;
+}
+
+/** 模板函数：吃宿主投影出的渲染状态，吐该挂点的内容与根皮肤类（纯函数，不碰 DOM、无副作用） */
+export type TemplateFn<TInput, TView extends TemplateViewBase> = (
+  input: TInput,
+) => TView;
+
+/**
+ * 模板注册与解析：按名存模板，解析时未知名 / null / 空串一律回退默认，未设默认则返回 `null`。
+ *
+ * 用法：宿主装配期 `register` 一批模板（可指定其中之一为兜底），渲染挂载点时用 `resolve` 取函数。
+ * 模板缺失不算错误——由宿主的内建实现兜底，因此本表是 fail-soft 的。
+ * 本类不持有渲染状态，同一实例可跨挂载点共享。
+ */
+export class TemplateRegistry<TInput, TView extends TemplateViewBase> {
+  /**
+   * 模板表：模板名 → 模板函数。`register` 写入（同名覆盖），`resolve` / `has` / `names` 读取。
+   * 空串是「无模板」哨兵，`register` 直接拒收，所以键集合恰好等于真正注册过的模板名；
+   * Map 保插入序，`names()` 就按这个顺序返回。引用只读，内容随注册变化。
+   */
+  private readonly templates = new Map<string, TemplateFn<TInput, TView>>();
+  /** 默认模板名（`register` 传 `makeDefault: true` 时改成它）；`null` = 未设默认，解析时返回 `null` */
+  private defaultName: string | null = null;
+
+  /** 注册模板（同名覆盖更新——注册即生效的可选语义） */
+  register(
+    name: string,
+    fn: TemplateFn<TInput, TView>,
+    opts: { makeDefault?: boolean } = {},
+  ): void {
+    if (name === "") return; // 空名 = 「无模板」哨兵，不可被注册占用
+    this.templates.set(name, fn);
+    if (opts.makeDefault === true) this.defaultName = name;
+  }
+
+  /** 该名是否已被注册（**不走回退**：问的是表里有没有这个名字） */
+  has(name: string): boolean {
+    return this.templates.has(name);
+  }
+
+  /** 已注册模板名（诊断 / 帮助面板用） */
+  names(): string[] {
+    return [...this.templates.keys()];
+  }
+
+  /** 按名解析：未知名/null/空串回退默认；未设默认 = null（宿主兜底） */
+  resolve(name?: string | null): TemplateFn<TInput, TView> | null {
+    if (name !== null && name !== undefined && name !== "") {
+      const hit = this.templates.get(name);
+      if (hit !== undefined) return hit;
+    }
+    if (this.defaultName === null) return null;
+    return this.templates.get(this.defaultName) ?? null;
+  }
+}
+
+/** 造一张空的模板注册表（未设默认）；默认模板需在 `register` 时用 `makeDefault: true` 指定 */
+export function createTemplateRegistry<
+  TInput,
+  TView extends TemplateViewBase,
+>(): TemplateRegistry<TInput, TView> {
+  return new TemplateRegistry<TInput, TView>();
+}

package/src/video/index.ts

@@ -0,0 +1,6 @@
+/** 视频渲染域出口：命令流 → VideoPort 执行（可测纯编排）。 */
+export {
+  createVideoRenderer,
+  type VideoRenderer,
+  type VideoRendererOptions,
+} from "./videoView";

package/src/video/videoView.ts

@@ -0,0 +1,122 @@
+/**
+ * 视频渲染：引擎的 `__video` 命令流 → VideoPort 执行（可测纯编排）。
+ * - seq 去重：同一命令只执行一次（重放/读档恢复后的同 seq 不重放）
+ * - 资源经 ResourcePort 解析 + 代际取消（迟到的旧解析不误播）
+ * - cutscene 自然播放结束 → onVideoFinished（引擎解除 video 等待）
+ * 性能：sync 仅由 `__video` 事件与显式调用触发（回溯/读档后对齐），非逐帧。
+ */
+import type {
+  ResourcePort,
+  VideoCommand,
+  VideoPort,
+  StoryEngine,
+} from "@lingfan-engine/core";
+import { createStateReader, SYS } from "@lingfan-engine/core";
+import { createResourceUrlCache } from "../resources";
+
+/**
+ * 宿主侧回调：只收「出事了」与「放完了」两件本层无法自行处理的事。
+ * 都不传也能跑——只是解析失败会静默不播、cutscene 结束后引擎会一直等。
+ */
+export interface VideoRendererOptions {
+  /** 资源解析失败诊断（报错诊断：不静默吞错） */
+  onError?: (message: string) => void;
+  /** cutscene 自然播放结束（引擎据此解除 video 等待） */
+  onVideoFinished?: () => void;
+}
+
+/**
+ * 视频渲染器：命令的订阅与执行都在工厂内建好，外部只需处理偶尔的显式对齐。
+ */
+export interface VideoRenderer {
+  /** 与引擎命令流对齐（订阅外的显式同步，如回溯/读档完成） */
+  sync(): void;
+  dispose(): void;
+}
+
+/**
+ * 造一个视频渲染器并立即订阅引擎的 `__video` 命令流（构造末尾先自同步一次）。
+ *
+ * 它按 seq 去重、按代际取消迟到的解析结果；资源 URL 经共享缓存取，`dispose` 时逐个
+ * `resources.release` 并退订——释放与订阅成对，调用方不必自己记账。
+ */
+export function createVideoRenderer(
+  engine: StoryEngine,
+  port: VideoPort,
+  resources: ResourcePort,
+  options: VideoRendererOptions = {},
+): VideoRenderer {
+  let lastSeq = -1;
+  /** 解析代际：异步解析落地时若已被更新命令取代，丢弃该次播放（防错播） */
+  let generation = 0;
+  const urls = createResourceUrlCache((resource) =>
+    resources.resolve(resource),
+  );
+  const reader = createStateReader(engine);
+
+  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：不播放（诊断已上报，不静默）
+    }
+  }
+
+  function execute(command: VideoCommand): void {
+    generation += 1;
+    const gen = generation;
+    if (command.kind === "play") {
+      void resolveUrl(command.resource).then((url) => {
+        if (url === null || generation !== gen) return; // 已被更新命令取代
+        port.play(
+          url,
+          { volume: command.volume, loop: command.loop },
+          command.cutscene ? () => options.onVideoFinished?.() : undefined,
+        );
+      });
+      return;
+    }
+    if (command.kind === "pause") {
+      port.pause();
+      return;
+    }
+    if (command.kind === "resume") {
+      port.resume();
+      return;
+    }
+    if (command.kind === "seek") {
+      port.seek(command.seconds);
+      return;
+    }
+    port.stop();
+  }
+
+  function sync(): void {
+    const command = reader.videoCommand();
+    if (command === null) {
+      if (lastSeq >= 0) {
+        port.stop(); // 命令流被清空（重启/重建）：停播
+        lastSeq = -1;
+      }
+      return;
+    }
+    if (command.seq === lastSeq) return; // 同命令已执行（重放同 seq 不重放）
+    lastSeq = command.seq;
+    execute(command);
+  }
+
+  const off = engine.onStateChanged((change) => {
+    if (change.key === SYS.video) sync();
+  });
+  sync();
+
+  return {
+    sync,
+    dispose(): void {
+      off();
+      for (const url of urls.values()) resources.release(url);
+      urls.clear();
+    },
+  };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.