@lingfan-engine/ui 0.0.0-stage → 0.1.0

package/src/notify/templates.ts

@@ -0,0 +1,60 @@
+/**
+ * 通知层模板（挂载点模板的一例：单条 toast 的内容 + rootClass 皮肤）。
+ *
+ * 与 Ren'Py `notify` screen 的差别：它的 screen 里可挂任意控件（甚至写 `timer` 控制消失），
+ * 本模板只给「渲染一条通知所需的数据」，**消失时机归宿主**（`duration`）——
+ * 模板不得控制生命周期，否则回溯/并发通知的语义会漂移。
+ *
+ * 未知名 / null 回退默认（模板只影响展示）。
+ */
+import {
+  TemplateRegistry,
+  createTemplateRegistry,
+} from "../templates/registry";
+import { renderDialogueLine } from "../dialogue/textView";
+
+/** 通知层级（作者可选；模板据以换装/加图标） */
+export type NotifyTone = "info" | "warning" | "error";
+
+/** 通知模板输入：单条通知的渲染投影 */
+export interface NotifyTemplateInput {
+  /** 通知文本（原文；经统一接缝渲染） */
+  text: string;
+  /** 通知类型（`notify` op 的 `type`；未声明 = info） */
+  tone: NotifyTone;
+}
+
+/** 通知模板输出：语义骨架挂点内容 */
+export interface NotifyTemplateView {
+  /** 通知项根皮肤类 */
+  rootClass: string;
+  /** 通知正文 HTML（经统一接缝转义） */
+  bodyHtml: string;
+}
+
+/** 通知层模板：吃投影出的单条通知，吐骨架挂点内容。纯函数——不控消失时机、不挂定时器 */
+export type NotifyTemplateFn = (
+  input: NotifyTemplateInput,
+) => NotifyTemplateView;
+
+/** 通知层模板注册表：按名存 `NotifyTemplateFn`，按名解析，未知名回退默认 */
+export type NotifyTemplateRegistry = TemplateRegistry<
+  NotifyTemplateInput,
+  NotifyTemplateView
+>;
+
+/** 造一张空的通知层模板注册表；宿主在装配期向它 `register` 模板（本函数不装内建默认） */
+export function createNotifyTemplateRegistry(): NotifyTemplateRegistry {
+  return createTemplateRegistry<NotifyTemplateInput, NotifyTemplateView>();
+}
+
+/** 通知类型归一（未知/缺省 → info；不静默丢信息） */
+export function toNotifyTone(raw: unknown): NotifyTone {
+  return raw === "warning" || raw === "error" ? raw : "info";
+}
+
+/** 内置默认模板：正文转义 + 按类型加皮肤类 */
+export const builtinNotifyTemplate: NotifyTemplateFn = (input) => ({
+  rootClass: `tpl-notify tpl-notify-${input.tone}`,
+  bodyHtml: renderDialogueLine({ text: input.text }).html,
+});

package/src/overlay/choices-view.ts

@@ -0,0 +1,76 @@
+/**
+ * 选择层视图模型：菜单选项与输入等待两个形态共用一个提交点，**不碰任何节点**。
+ *
+ * 两个形态互斥（`input` 等待渲染输入表单，`menu` 等待渲染选项列表），因此给出的是
+ * `ChoicesLayerView | null`：`null` 表示整层隐藏。点击一律交核心：选项目标是**列 id**
+ * （不是显示文本），输入值经宿主提交路径送核心。
+ */
+import { builtinChoiceTemplate } from "../choices/templates";
+import type { ChoiceTemplateRegistry } from "../choices/templates";
+import type { ChoicesLayerView } from "./surface";
+
+/** 一次选择层重渲所需的渲染态（全部来自状态投影） */
+export interface ChoicesRenderInput {
+  waiting: string;
+  menuPrompt: string;
+  menuOptions: readonly { text: string; target: string }[];
+  inputPrompt: string;
+}
+
+/** 选择层文案（宿主可覆盖；缺省实现即内建文案） */
+export interface ChoicesTexts {
+  /** 输入提交按钮的显示文本 */
+  inputSubmit: string;
+}
+
+/**
+ * 选择层的装配输入。`choose` / `submitInput` 不在模型里——它们是端口上的两条出口
+ * （见 `OverlaySurface.onChoose` / `onSubmitInput`），视图模型不认识引擎。
+ */
+export interface ChoicesViewDeps {
+  /** 模板注册表（不传 = 内建模板） */
+  templates?: ChoiceTemplateRegistry;
+  /** 文案覆盖（不传 = 内建缺省） */
+  texts?: Partial<ChoicesTexts>;
+}
+
+/** 内建文案：不传 texts 时的缺省值 */
+const DEFAULT_CHOICES_TEXTS: ChoicesTexts = { inputSubmit: "确定" };
+
+/**
+ * 算出一层选择模型：等待态不是 `menu` / `input` 时返回 `null`（整层隐藏）。
+ *
+ * 输入形态不带皮肤类名（原文如此：`lf-choices` 基类由渲染侧拼，模板只服务菜单形态）；
+ * 菜单形态连同每个选项的三个字段一起给出——`html` 是呈现片段，`label` 是可访问名，
+ * 因此「innerHTML 不进无障碍名计算」这条口径在宿主侧照样能落实。
+ */
+export function choicesLayerView(
+  input: ChoicesRenderInput,
+  deps: ChoicesViewDeps = {},
+): ChoicesLayerView | null {
+  if (input.waiting === "input") {
+    const texts: ChoicesTexts = { ...DEFAULT_CHOICES_TEXTS, ...deps.texts };
+    return {
+      rootClass: "",
+      promptHtml: "",
+      options: [],
+      input: { prompt: input.inputPrompt, submitText: texts.inputSubmit },
+    };
+  }
+  if (input.waiting !== "menu") return null;
+
+  const built = (deps.templates?.resolve(null) ?? builtinChoiceTemplate)({
+    prompt: input.menuPrompt,
+    options: input.menuOptions,
+  });
+  return {
+    rootClass: built.rootClass,
+    promptHtml: built.promptHtml,
+    options: input.menuOptions.map((option, index) => ({
+      html: built.optionHtml[index] ?? "",
+      label: option.text,
+      target: option.target,
+    })),
+    input: null,
+  };
+}

package/src/overlay/create.ts

@@ -0,0 +1,254 @@
+/**
+ * 叙事覆盖层装配器：把一个宿主的覆盖层表面变成可运行的叙事覆盖层。
+ *
+ * **解决的问题**：把叙事能力嵌入已有游戏（2D/3D 引擎）时，宿主需要自行实现一份
+ * 参考宿主的渲染接线（五层视图模型 + 状态投影 + 打字机 + 帧循环 + 输入判据）。
+ * 本装配器把这套接线收进展示层：宿主只给一个覆盖层表面（`OverlaySurface`）与一个引擎实例。
+ *
+ * **设计约束（与引擎架构一致）**：
+ * - 引擎核心**不驱动帧**（帧归宿主），本装配器就是那个宿主：它持帧循环，
+ *   只做插值，不逐帧写状态（帧级高频键由引擎自己的静默写通道负责）。
+ * - 渲染落点全部经端口（`surface.setDialogue` / `setChoices` / `pushNotification` /
+ *   `setLayerZ`），本模块不出现任何平台类型；层骨架由宿主的实现建。
+ * - 模板注册表可选注入，不传即内建默认（模板只决定「长什么样」）。
+ * - **不自行绑定键盘**：宿主游戏的键位归宿主。本层只提供判据与命令入口，
+ *   并复用展示层唯一的输入判据（`isGameInputTarget`），不另立第二份口径。
+ *
+ * **不做什么**：不创建引擎、不装配平台端口（存档/资源/音频是平台能力，由宿主
+ * 经引擎选项注入）、不改叙事语义。
+ *
+ * 本模块只做**装配、接线与销毁编排**：各职责的实现分别在同目录的
+ * `projector` / `*-view`（视图模型）/ `element-tree` / `layer-z` 内，
+ * 帧循环则复用展示层的共享实现（`../host/frame-loop`，与各宿主的 `startHostFrameLoop` 同一份）。
+ * 所有状态都由各职责的工厂持有（每次调用装配器产出独立的一份），
+ * 因此两个覆盖层实例互不串扰。
+ */
+import { createStateReader, DEFAULT_LAYER_Z } from "@lingfan-engine/core";
+import type { LayerZTable } from "@lingfan-engine/core";
+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 { choicesLayerView } from "./choices-view";
+import type { ChoicesViewDeps } from "./choices-view";
+import { dialogueLayerView } from "./dialogue-view";
+import type { DialogueViewDeps } from "./dialogue-view";
+import { createElementTree } from "./element-tree";
+import { createFrameLoop } from "../host/frame-loop";
+import { createLayerZController } from "./layer-z";
+import { notifyLayerItem } from "./notify-view";
+import type { NotifyViewDeps } from "./notify-view";
+import { createProjector } from "./projector";
+import type { RenderTarget } from "./projector";
+import type { NarrativeOverlay, NarrativeOverlayOptions } from "./types";
+
+/** 内建元素渲染器注册表（36 类型全集） */
+function createBuiltinElementRegistry(): ElementRegistry {
+  const registry = createElementRegistry();
+  registerBuiltinElementRenderers(registry);
+  return registry;
+}
+
+/**
+ * 装配叙事覆盖层。
+ *
+ * ```ts
+ * const surface = createDomOverlaySurface(container);
+ * const overlay = createNarrativeOverlay({ surface, engine });
+ * engine.start();
+ * window.addEventListener("keydown", (e) => {
+ *   if (e.key === " " && overlay.shouldConsumeInput(e.target)) overlay.advance();
+ * });
+ * // 卸载：overlay.dispose();
+ * ```
+ */
+export function createNarrativeOverlay(
+  options: NarrativeOverlayOptions,
+): NarrativeOverlay {
+  const { surface, engine } = options;
+  const report = options.onError ?? ((m: string) => console.error(m));
+  const layerZ: LayerZTable = options.layerZ ?? DEFAULT_LAYER_Z;
+  const reader = createStateReader(engine);
+
+  const elements = options.elementRegistry ?? createBuiltinElementRegistry();
+  const textSpeed = options.textSpeed ?? 30;
+
+  const layerZController = createLayerZController(surface, layerZ);
+  // 表面可能由宿主先建（那时还不知道本实例的层默认表）：构造末尾统一下发一次，
+  // 此后层默认表与本实例一致；下发幂等，不产生渲染目标。
+  layerZController.apply();
+
+  const projector = createProjector({
+    reader,
+    engine,
+    layerZ: layerZController,
+    textSpeed,
+  });
+
+  const dialogueDeps: DialogueViewDeps = {
+    templates: options.dialogueTemplates,
+    readTemplateName: () => reader.dialogTemplate(),
+  };
+  const choicesDeps: ChoicesViewDeps = {
+    templates: options.choiceTemplates,
+    texts: options.choiceTexts,
+  };
+  const notifyDeps: NotifyViewDeps = { templates: options.notifyTemplates };
+
+  const elementTree = createElementTree({
+    registry: elements,
+    port: surface.elements,
+    engine,
+    commands: options.commands,
+    resolveResource: options.resolveResource,
+    report,
+  });
+
+  // 两条交互出口（DOM 侧的按钮点击与表单提交就是调用点）
+  surface.onChoose = (target) => engine.choose(target);
+  surface.onSubmitInput = (value) => engine.input(value);
+
+  /** 重渲对话层（正文 HTML 每次现算：打字帧下它就是变化的那部分） */
+  function renderDialogueNow(): void {
+    const s = projector.state;
+    surface.setDialogue(
+      dialogueLayerView(
+        {
+          speaker: s.speaker,
+          speakerColor: s.speakerColor,
+          dialogFont: s.dialogFont,
+          canAdvance: s.canAdvance,
+          dialogHidden: s.dialogHidden,
+          waiting: s.waiting,
+          lineHtml: projector.lineHtml(),
+        },
+        dialogueDeps,
+      ),
+    );
+  }
+
+  /** 重渲选择层（`null` = 整层隐藏） */
+  function renderChoicesNow(): void {
+    const s = projector.state;
+    surface.setChoices(
+      choicesLayerView(
+        {
+          waiting: s.waiting,
+          menuPrompt: s.menuPrompt,
+          menuOptions: s.menuOptions,
+          inputPrompt: s.inputPrompt,
+        },
+        choicesDeps,
+      ),
+    );
+  }
+
+  /** 重渲元素树 */
+  function renderElementsNow(): void {
+    elementTree.render(projector.state.elementList);
+  }
+
+  /** 按投影给出的目标顺序重渲（顺序即层间重渲顺序） */
+  function renderTargets(targets: readonly RenderTarget[]): void {
+    for (const target of targets) {
+      if (target === "dialogue") renderDialogueNow();
+      else if (target === "choices") renderChoicesNow();
+      else renderElementsNow();
+    }
+  }
+
+  /** 打字进度推进后：只重渲正文，再把投影变化通知宿主 */
+  function onTyped(): void {
+    renderDialogueNow();
+    options.onView?.(projector.view());
+  }
+
+  const offState = engine.onStateChanged(({ key, value }) => {
+    const effect = projector.applyChange(key, value);
+    // 层级 z 只改样式，不产生渲染目标，也不通知投影变化（其余键都通知）
+    if (effect.kind === "layers") return;
+    renderTargets(effect.targets);
+    options.onView?.(projector.view());
+  });
+
+  const offEvent = engine.onEvent(({ payload }) => {
+    if (payload.kind === "notify") {
+      surface.pushNotification(
+        notifyLayerItem(payload, notifyDeps),
+        payload.duration ?? DEFAULT_NOTIFY_MS,
+      );
+    } else if (payload.kind === "engine.error") report(payload.message);
+  });
+
+  // 帧循环的帧能力来自端口：无帧环境下帧源不回调，循环静默不启、功能仍可用
+  // 每帧顺序固定——推进打字机（变了才重渲正文），再交宿主做帧驱动表现
+  const frameLoop = createFrameLoop({
+    frame: surface.frame,
+    onTick: (dt) => {
+      if (projector.tickTypewriter(dt)) onTyped();
+      options.onFrame?.(dt);
+    },
+  });
+  frameLoop.start();
+
+  function sync(): void {
+    renderTargets(projector.sync());
+  }
+
+  function advance(): void {
+    if (projector.finishTypewriter()) {
+      onTyped();
+      return;
+    }
+    // 只有「推进类」等待态才交引擎：menu 归 choose、input 归 input、
+    // 外部接管归 resolve。否则引擎会回一条无效调用错误——那是误报，不是玩家错。
+    const waiting = projector.state.waiting;
+    if (waiting === "dialog" || waiting === "wait" || waiting === "video") {
+      engine.advance();
+    }
+  }
+
+  function choose(target: string): void {
+    engine.choose(target);
+  }
+
+  function submitInput(value: string): void {
+    engine.input(value);
+  }
+
+  function shouldConsumeInput(target: unknown): boolean {
+    // 复用展示层唯一判据：控件与 UI 面板内的输入不归叙事
+    return isGameInputTarget(target);
+  }
+
+  let disposed = false;
+
+  function dispose(): void {
+    if (disposed) return;
+    disposed = true;
+    frameLoop.stop();
+    offState();
+    offEvent();
+    surface.clear();
+  }
+
+  function setRunning(next: boolean): void {
+    frameLoop.setRunning(next);
+  }
+
+  renderDialogueNow();
+  renderChoicesNow();
+
+  return {
+    surface,
+    view: () => projector.view(),
+    sync,
+    setRunning,
+    shouldConsumeInput,
+    advance,
+    choose,
+    submitInput,
+    dispose,
+  };
+}

package/src/overlay/dialogue-view.ts

@@ -0,0 +1,72 @@
+/**
+ * 对话层视图模型：把投影出的对话渲染态经模板算成一层模型，**不碰任何节点**。
+ *
+ * 骨架固定（说话人 / 正文 / 推进提示），模板只决定「长什么样」——本模块负责把模板产物与
+ * 渲染态合成 `DialogueLayerView`；落到哪个渲染体系由宿主的 `OverlaySurface` 决定。
+ * 每次重渲都整层重算（模板输出很灵活，增量 diff 会引入第二份骨架知识）。
+ */
+import { builtinBubbleTemplate } from "../dialogue/templates";
+import { sanitizeFont } from "../dialogue/inline";
+import type { DialogueTemplateRegistry } from "../dialogue/templates";
+import type { DialogueLayerView } from "./surface";
+
+/** 一次对话层重渲所需的渲染态（全部来自状态投影） */
+export interface DialogueRenderInput {
+  speaker: string;
+  speakerColor: string;
+  /** 本句对话字体（空串 = 无声明；正文回落宿主 CSS 变量或浏览器默认） */
+  dialogFont: string;
+  canAdvance: boolean;
+  dialogHidden: boolean;
+  waiting: string;
+  /** 当前正文 HTML（打字中 = 可见前缀） */
+  lineHtml: string;
+}
+
+/**
+ * 对话层的装配输入。模板名不是参数而是回调——它逐帧从引擎状态读，
+ * 因此对话框换装（角色 screen / 逐句 template）不需要重建视图。
+ */
+export interface DialogueViewDeps {
+  /** 模板注册表（不传 = 内建默认） */
+  templates?: DialogueTemplateRegistry;
+  /** 读当前模板名（`null` = 全局默认） */
+  readTemplateName: () => string | null;
+}
+
+/**
+ * 算出一层对话模型：骨架三段由模板给内容，本函数只做「合成 + 白名单校验 + 可见性判定」。
+ *
+ * 菜单、输入或视频等待期间整层不可见——是隐藏而非清空，避免恢复时闪一下。
+ * 字体只在非空且通过白名单时才写（同 `{font=}` 的口径），空串交给宿主 CSS 承接。
+ */
+export function dialogueLayerView(
+  input: DialogueRenderInput,
+  deps: DialogueViewDeps,
+): DialogueLayerView {
+  const template =
+    deps.templates?.resolve(deps.readTemplateName()) ?? builtinBubbleTemplate;
+  const built = template({
+    speaker: input.speaker,
+    speakerColor: input.speakerColor,
+    lineHtml: input.lineHtml,
+    canAdvance: input.canAdvance,
+  });
+
+  const font = input.dialogFont === "" ? null : sanitizeFont(input.dialogFont);
+  const visible =
+    !input.dialogHidden &&
+    input.waiting !== "menu" &&
+    input.waiting !== "input" &&
+    input.waiting !== "video";
+
+  return {
+    rootClass: built.rootClass,
+    visible,
+    speakerHtml: built.speakerHtml,
+    speakerColor: input.speakerColor,
+    bodyHtml: built.bodyHtml,
+    bodyFont: font ?? "",
+    hintHtml: built.hintHtml,
+  };
+}

package/src/overlay/element-tree.ts

@@ -0,0 +1,109 @@
+/**
+ * 元素树接线：把舞台元素渲染进元素层，并把元素的交互语义翻译成引擎调用。
+ *
+ * 元素渲染本身归元素域（`renderElementTree`）；本模块只提供三样宿主侧能力：
+ * 交互激活（nav / ops / cmd 三条语义）、`disabled` 表达式求值、未注册类型上报。
+ * 求值一律经引擎的插值入口，本层不解析表达式语法——语法归核心层。
+ */
+import type { ElementInstance, StoryEngine } from "@lingfan-engine/core";
+import { resolveElementAction } from "../element/interaction";
+import { renderElementTree } from "../element/render";
+import type { ElementRegistry } from "../element/registry";
+import type { RenderPort } from "../element/spec";
+
+/** 元素 `cmd` 命令处理器（未注册 = fail-closed 上报） */
+export type ElementCommandHandler = (
+  value: string | undefined,
+  element: ElementInstance,
+) => void;
+
+/**
+ * 元素树渲染的装配输入。除 `engine` 外全部可选或可替换——
+ * `registry` 换掉即换元素类型全集，`commands` 不传则元素上的 `cmd` 一律走 fail-closed 上报。
+ */
+export interface ElementTreeDeps {
+  /** 元素渲染器注册表（36 类型全集，或宿主替换的实现） */
+  registry: ElementRegistry;
+  /** 元素层的渲染端口（元素树的物化目标；Web 侧由 `createDomRenderPort` 就地包装） */
+  port: RenderPort;
+  engine: StoryEngine;
+  /** 宿主注册的元素命令表 */
+  commands?: Map<string, ElementCommandHandler>;
+  /** 资源解析（元素 source/src/path → URL） */
+  resolveResource?: (path: string) => string | undefined;
+  /** 上报（错误与 fail-closed 诊断） */
+  report: (message: string) => void;
+}
+
+/**
+ * 元素树接线器：宿主只需调 `render` 提交一帧元素列表，交互语义由本层消化。
+ * 两个方法都是无状态的——元素数据每次由调用方给全，本层不缓存上一帧。
+ */
+export interface ElementTree {
+  /** `disabled` 表达式求值（返回 `null` = 求值失败，表达式语法归核心层） */
+  evalDisable(expression: string): boolean | null;
+  /** 整体重渲元素树（每次调用重建，不做增量 diff） */
+  render(elements: readonly ElementInstance[]): void;
+}
+
+/**
+ * 造一个元素树接线器。
+ *
+ * `evalDisable` 与 `activate` 共用同一套判定（同一组属性、同一个求值函数），
+ * 因此「看起来能点」与「点下去真的做了」不会分叉。元素列表逐帧传入、整体重渲，
+ * 本层不持有元素状态。
+ */
+export function createElementTree(deps: ElementTreeDeps): ElementTree {
+  const { engine } = deps;
+
+  function evalDisable(expression: string): boolean | null {
+    const out = engine.interpolate(expression);
+    if (out === "true") return true;
+    if (out === "false") return false;
+    return null;
+  }
+
+  function activate(element: ElementInstance): void {
+    const action = resolveElementAction(element.props, { evalDisable });
+    if (action.kind === "nav") {
+      engine.navigate(action.target);
+      return;
+    }
+    if (action.kind === "ops") {
+      if (!engine.runElementOps(action.ops)) {
+        deps.report("元素动作执行失败（等待/位置类 op 与畸形负载会被拒绝）");
+      }
+      return;
+    }
+    if (action.kind !== "cmd") return;
+    const handler = deps.commands?.get(action.name);
+    if (handler === undefined) {
+      deps.report(
+        `元素命令未注册：${action.name}（fail-closed：需宿主经命令注册表提供）`,
+      );
+      return;
+    }
+    handler(
+      action.value === undefined ? undefined : engine.interpolate(action.value),
+      element,
+    );
+  }
+
+  return {
+    evalDisable,
+    render(elements: readonly ElementInstance[]): void {
+      // 交互元素的 pointer-events 由渲染器自行恢复（有交互动词的节点由绑定层
+      // 置 cursor:pointer + pointer-events:auto）——本层不重判第二遍。
+      renderElementTree({
+        registry: deps.registry,
+        port: deps.port,
+        elements,
+        activate,
+        evalDisable,
+        resolveResource: deps.resolveResource,
+        onUnknownType: (type) =>
+          deps.report(`元素类型未注册：${type}（fail-closed：不伪造渲染）`),
+      });
+    },
+  };
+}

package/src/overlay/index.ts

@@ -0,0 +1,16 @@
+export { createNarrativeOverlay } from "./create";
+export type {
+  NarrativeOverlay,
+  NarrativeOverlayOptions,
+  NarrativeOverlayView,
+} from "./types";
+export type { ChoicesTexts } from "./choices-view";
+export type {
+  ChoicesLayerInput,
+  ChoicesLayerOption,
+  ChoicesLayerView,
+  DialogueLayerView,
+  NotifyLayerItem,
+  OverlayLayerId,
+  OverlaySurface,
+} from "./surface";

package/src/overlay/layer-z.ts

@@ -0,0 +1,73 @@
+/**
+ * 层级 z 控制器：持有实例级覆盖表，并负责把它写回各层（经覆盖层端口下发）。
+ *
+ * 三级链由引擎的 `resolveInstanceZ` 决定（**实例显式指定 > 工程层默认 > 内建默认**），
+ * 本控制器只负责「收下覆盖值 → 重算 → 经端口下发」这一段接线。
+ *
+ * 与宿主模板绑定的同名概念区分：本控制器直接把 z 下发到覆盖层端口；宿主若要拿响应式镜像
+ * 给模板绑定（`:style="{ zIndex: zOf(...) }"`），那是宿主自己的控制器（如 playground 的
+ * `HostLayerZController`），承载面与层表都不同。
+ */
+import { resolveInstanceZ } from "@lingfan-engine/core";
+import type {
+  LayerId,
+  LayerZOverrides,
+  LayerZTable,
+} from "@lingfan-engine/core";
+import type { OverlaySurface } from "./surface";
+
+/** 层级 z 控制器（每实例一份覆盖表） */
+export interface LayerZController {
+  /** 实例级覆盖：只含显式指定过的层；未指定即回层默认 */
+  overrides: LayerZOverrides;
+  /** 把当前覆盖表应用到各层（幂等，可反复调用） */
+  apply(): void;
+}
+
+/** 收藏一个实例 z 键的新值（`undefined` = 取消该层覆盖） */
+export function setLayerOverride(
+  controller: LayerZController,
+  layer: LayerId,
+  instanceZ: number | undefined,
+): void {
+  controller.overrides = { ...controller.overrides, [layer]: instanceZ };
+}
+
+/**
+ * 造一个层级控制器：覆盖表初始为空（全部层走默认），需调 `apply()` 才下发 z。
+ *
+ * `layerZ` 是工程级的层默认表，控制器只在其上加一层「实例显式指定」的覆盖；
+ * 覆盖表逐实例持有，所以两个覆盖层不会互相改 z。下发是幂等的，重复调无副作用。
+ */
+export function createLayerZController(
+  surface: OverlaySurface,
+  layerZ: LayerZTable,
+): LayerZController {
+  const controller: LayerZController = {
+    overrides: {},
+    apply(): void {
+      const z = controller.overrides;
+      surface.setLayerZ(
+        "dialogue",
+        resolveInstanceZ("dialogue", z.dialogue, layerZ),
+      );
+      surface.setLayerZ(
+        "choices",
+        resolveInstanceZ("choices", z.choices, layerZ),
+      );
+      surface.setLayerZ(
+        "notifications",
+        resolveInstanceZ("notifications", z.notifications, layerZ),
+      );
+      surface.setLayerZ(
+        "takeover",
+        resolveInstanceZ("minigame", z.minigame, layerZ),
+      );
+      surface.setLayerZ(
+        "transition",
+        resolveInstanceZ("video", z.video, layerZ),
+      );
+    },
+  };
+  return controller;
+}