@lingfan-engine/ui 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/ui",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "灵泛叙事引擎参考展示层：框架无关的可测纯逻辑（内联标记、打字机、音频差量规划）",
   "license": "Apache-2.0",
@@ -13,7 +13,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@lingfan-engine/core": "^0.2.0"
+    "@lingfan-engine/core": "^0.3.1"
   },
   "repository": {
     "type": "git",

package/src/audio/index.ts

@@ -1,11 +1,18 @@
-/** 音频渲染域出口：状态差量规划器 + 渲染器（可测纯逻辑，播放归适配器）。 */
+/**
+ * 音频渲染域出口：状态视图（view）、差量规划（plan）、渲染器（renderer）。
+ *
+ * 核心只写状态，本域把状态差量翻译成端口动作（可测纯逻辑），由适配器落地播放；
+ * 资源寻址经 ResourcePort，播放位置回写走帧级键。
+ */
 export {
   EMPTY_AUDIO_VIEW,
-  createAudioRenderer,
-  planAudioActions,
   readAudioView,
   type AudioAction,
+  type AudioView,
+} from "./view/index.ts";
+export { planAudioActions } from "./plan/index.ts";
+export {
+  createAudioRenderer,
   type AudioRenderer,
   type AudioRendererOptions,
-  type AudioView,
-} from "./audio";
+} from "./renderer/index.ts";

package/src/audio/plan/actions.ts

@@ -0,0 +1,184 @@
+/**
+ * 差量规划：视图快照前后的差异 → 端口动作序列（纯函数，可单测）。
+ *
+ * 规划器不知道端口长什么样，也不发起播放；它只回答「为了从 prev 变成 next 要下发哪些动作」。
+ */
+import type { AudioAction, AudioView } from "../view/index.ts";
+
+/** 常驻通道（se 为一次性触发，单独按 seq 判定） */
+const CHANNELS = ["bgm", "ambient", "voice"] as const;
+
+/** 位置差异阈值（秒）：小于此视为播放器噪声，不打断播放（seek 抖动防护） */
+const SEEK_THRESHOLD = 0.5;
+
+/**
+ * 状态差量 → 端口动作：
+ * - 通道由 play 变 stop/null → stop（带淡出参数）
+ * - 换资源 → play（bgm 从目标位置起播）
+ * - 同资源 + 显式 restart（seq 变化）→ play 回到起点重播
+ * - 同资源仅音量/循环变化 → play 更新（适配器不重头播）；bgm 位置差超阈值 → 定位
+ * - play 变 pause → pause（保留实例与位置）；pause 变 play → resume（不重播、不从头）
+ * - pause 变 stop/null → stop（暂停中的通道也要先停掉，否则实例一直占着）
+ * - se 按单调 seq 判定：每次执行都触发一次（同一资源连续触发亦然）；`stop` 形态同样按 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 === "pause") {
+      // 暂停：只有「正在出声」才需要收声；本来就是暂停/停止的通道无动作
+      if (before !== null && before.kind === "play") {
+        actions.push({ type: "pause", channel });
+      }
+      continue;
+    }
+    if (after === null || after.kind !== "play") {
+      if (
+        before !== null &&
+        (before.kind === "play" || before.kind === "pause")
+      ) {
+        actions.push({
+          type: "stop",
+          channel,
+          fadeMs: after !== null && after.kind === "stop" ? after.fadeMs : 0,
+        });
+      }
+      continue;
+    }
+    if (before !== null && before.kind === "pause") {
+      // 从暂停回到播放：走 resume 而不是 play——play 会从起点重播，
+      // 暂停的意义恰恰是保住位置（资源与位置都在端口的播放器实例里）
+      actions.push({ type: "resume", channel });
+      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,
+      });
+    }
+  }
+  actions.push(...planInstanceActions(prev, next));
+  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,
+    });
+  }
+  // 音效停止：与触发同样按单调 seq 判定（连续两次停止也是两次独立事件，
+  // 否则第二次停不掉第一次停止之后新触发的音效）
+  if (
+    afterSe !== null &&
+    afterSe.kind === "stop" &&
+    (beforeSe === null || beforeSe.seq !== afterSe.seq)
+  ) {
+    actions.push({ type: "stop", channel: "se", fadeMs: afterSe.fadeMs });
+  }
+  return actions;
+}
+
+/**
+ * 实例差量：只翻 play ↔ pause 这一对。
+ *
+ * 引擎暂停会把在播实例写成 `pause` 态（暂停前的 play 态记在 `SYS.audioPaused`），
+ * 恢复时再写回 play 态——两次都是整表替换，渲染层看到的就是这一对变迁。
+ * 实例的起播与收声不在这里：那是实例命令面（`audio_play` / `audio_stop`）的职责，
+ * 两边都下发会重复。按 id 排序遍历，保证动作序列确定（与实例表的排序口径一致）。
+ */
+function planInstanceActions(prev: AudioView, next: AudioView): AudioAction[] {
+  const actions: AudioAction[] = [];
+  const ids = Object.keys(next.instances);
+  for (const id of Object.keys(prev.instances)) {
+    if (!(id in next.instances)) ids.push(id);
+  }
+  ids.sort();
+  for (const instanceId of ids) {
+    const before = prev.instances[instanceId];
+    const after = next.instances[instanceId];
+    if (after !== undefined && after.kind === "pause") {
+      if (before !== undefined && before.kind === "play") {
+        actions.push({ type: "pauseInstance", instanceId });
+      }
+      continue;
+    }
+    if (after !== undefined && after.kind === "play") {
+      if (before !== undefined && before.kind === "pause") {
+        // 与通道同构：resume 而不是 play——play 会从头起播，暂停的意义是保住位置
+        actions.push({ type: "resumeInstance", instanceId });
+      }
+    }
+  }
+  return actions;
+}

package/src/audio/plan/index.ts

@@ -0,0 +1,2 @@
+/** 规划子域出口：通道差量与实例差量。 */
+export { planAudioActions } from "./actions.ts";

package/src/audio/renderer/create.ts

@@ -0,0 +1,150 @@
+/**
+ * 渲染器：订阅音频状态键 → 重算视图 → 规划差量 → 落到端口。
+ *
+ * 资源解析、代际取消、释放都在这里；它不持有业务状态，唯一的本地态是「上一次的视图」。
+ */
+import type {
+  AudioChannel,
+  AudioPort,
+  ResourcePort,
+  StoryEngine,
+} from "@lingfan-engine/core";
+import { createStateReader, SYS } from "@lingfan-engine/core";
+import { createResourceUrlCache } from "../../resources";
+import { planAudioActions } from "../plan/index.ts";
+import { EMPTY_AUDIO_VIEW, readAudioView } from "../view/index.ts";
+import type { AudioAction, AudioView } from "../view/index.ts";
+import type { AudioRenderer, AudioRendererOptions } from "./types.ts";
+
+/**
+ * `AudioAction` 中 play 分支的别名（按 `type` 判别后的收窄形态）。
+ * 它不是新的动作形状，字段仍以 `AudioAction` 的 play 分支为唯一来源，只是给
+ * 「已经排除了 stop」的本地执行边界一个名字：`apply` 处理掉 stop 后把剩下的交给
+ * `playAction` 逐条落地播放，参数用它写明「这里拿到的必然是 play」。
+ */
+type PlayAction = Extract<AudioAction, { type: "play" }>;
+
+/**
+ * 造一个音频渲染器并立即订阅四条通道的音频状态（构造末尾先自同步一次）。
+ *
+ * 它按通道分代际，迟到的旧解析结果不误播；资源 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,
+    SYS.audioInstances,
+  ]);
+  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;
+      }
+      if (action.type === "pause") {
+        invalidate(action.channel); // 在途解析落地会立刻出声，暂停同样作废
+        port.pause(action.channel);
+        continue;
+      }
+      if (action.type === "resume") {
+        port.resume(action.channel);
+        continue;
+      }
+      if (action.type === "pauseInstance") {
+        // 端口未实现实例暂停就静默跳过：实例族是可选能力，缺它退化为
+        // 「实例不随引擎暂停」，不能因此整段音频停摆或反复报错
+        port.pauseInstance?.(action.instanceId);
+        continue;
+      }
+      if (action.type === "resumeInstance") {
+        port.resumeInstance?.(action.instanceId);
+        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/renderer/index.ts

@@ -0,0 +1,3 @@
+/** 渲染子域出口：渲染器工厂与它的形状。 */
+export { createAudioRenderer } from "./create.ts";
+export type { AudioRenderer, AudioRendererOptions } from "./types.ts";

package/src/audio/renderer/types.ts

@@ -0,0 +1,21 @@
+import type { PlayerPreferences } from "@lingfan-engine/core";
+
+/** 音频渲染器：订阅通道事件 → 差量应用；位置回写由帧循环驱动 */
+export interface AudioRenderer {
+  /** 与引擎状态对齐（订阅外的显式同步，如读档/回溯完成） */
+  sync(): void;
+  /** 帧循环回写播放位置：帧级键静默写，不进事件流 */
+  pollPosition(): void;
+  dispose(): void;
+}
+
+/**
+ * 宿主侧回调：解析失败的诊断出口；不传则该失败被静默忽略。
+ * `preferences` 是唯一的可选注入——不传即无偏好，音量按引擎状态算。
+ */
+export interface AudioRendererOptions {
+  /** 资源解析失败诊断（报错诊断：不静默吞错） */
+  onError?: (message: string) => void;
+  /** 玩家偏好（可选）：合成通道有效音量；偏好变化即时重规划（滑块/静音即时生效） */
+  preferences?: PlayerPreferences;
+}

package/src/audio/view/empty.ts

@@ -0,0 +1,11 @@
+import type { AudioView } from "./types.ts";
+
+/** 空视图：渲染器初始差量基准（组合根创建顺序无关，引擎已推进也能补播） */
+export const EMPTY_AUDIO_VIEW: AudioView = {
+  bgm: null,
+  ambient: null,
+  voice: null,
+  se: null,
+  instances: {},
+  bgmPosition: 0,
+};

package/src/audio/view/index.ts

@@ -0,0 +1,4 @@
+/** 视图子域出口：形状、空视图、读口。 */
+export { EMPTY_AUDIO_VIEW } from "./empty.ts";
+export { readAudioView } from "./read.ts";
+export type { AudioAction, AudioView } from "./types.ts";

package/src/audio/view/read.ts

@@ -0,0 +1,69 @@
+/**
+ * 视图构建：把引擎状态读成一个可比较的快照。
+ *
+ * 状态经引擎的类型化读口读取（`createStateReader`）：通道形状校验与降级在引擎侧
+ * 只有一份，本层只负责「读回来」，不做二次校验。
+ */
+import type {
+  AudioChannelState,
+  PlayerPreferences,
+  StoryEngine,
+} from "@lingfan-engine/core";
+import {
+  createStateReader,
+  SYS,
+  isAudioInstanceTable,
+} from "@lingfan-engine/core";
+import type { AudioView } from "./types.ts";
+
+/** 有效音量合成末端：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)) };
+}
+
+/**
+ * 实例状态快照：形状不合按空表处理（与引擎侧同一判据，不重复做校验）。
+ *
+ * 实例不在类型化读口里——`StateReader` 只有四通道维度，实例表是「整表一个值」的
+ * 通用系统键，这里用引擎的通用读口取回后按契约判据收窄。实例音量不乘玩家偏好：
+ * 偏好按通道分档，实例的音量在命令面已按归属通道解析过一次。
+ */
+function readInstanceStates(
+  engine: StoryEngine,
+): Readonly<Record<string, AudioChannelState>> {
+  const table = engine.get(SYS.audioInstances);
+  if (!isAudioInstanceTable(table)) return {};
+  const states: Record<string, AudioChannelState> = {};
+  for (const id of Object.keys(table).sort()) {
+    const entry = table[id];
+    if (entry !== undefined) states[id] = entry.state;
+  }
+  return states;
+}
+
+/** 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")),
+    instances: readInstanceStates(engine),
+    bgmPosition: reader.mediaPosition(),
+  };
+}

package/src/audio/view/types.ts

@@ -0,0 +1,41 @@
+/**
+ * 音频渲染域的形状：视图（状态快照）与端口动作（差量结果）。
+ *
+ * 两者是「状态 → 动作」这一层的唯一形状来源：规划器只产出 `AudioAction`，渲染器只消费它，
+ * 中间不再有第二套中间态。
+ */
+import type { AudioChannel, AudioChannelState } from "@lingfan-engine/core";
+
+/**
+ * 渲染视图：四通道状态 + 实例状态 + bgm 播放位置（帧级键直读，不进事件流）。
+ *
+ * 实例表按 id 收进视图（`instanceId → 状态`），只取三态里的 kind 与 seq 做差量；
+ * 通道与实例是两张表，各自独立判定，互不代偿。
+ */
+export interface AudioView {
+  bgm: AudioChannelState | null;
+  ambient: AudioChannelState | null;
+  voice: AudioChannelState | null;
+  se: AudioChannelState | null;
+  instances: Readonly<Record<string, AudioChannelState>>;
+  bgmPosition: number;
+}
+
+/** 端口动作：play = 播放/更新/定位/重播，stop = 停止（fadeMs 淡出），pause/resume = 可恢复暂停 */
+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 }
+  | { type: "pause"; channel: AudioChannel }
+  | { type: "resume"; channel: AudioChannel }
+  | { type: "pauseInstance"; instanceId: string }
+  | { type: "resumeInstance"; instanceId: string };

package/src/dom/materialize.ts

@@ -41,6 +41,27 @@ function applyPatch(node: HTMLElement, patch: RenderEventPatch): void {
   if (patch.props !== undefined) applyProps(node, patch.props);
 }
 
+/**
+ * 取事件载荷：`target` 上有 `value` 字段且为标量才传，其余一律 `undefined`。
+ *
+ * 只做形态判定，**不做业务转换**——物化器不认识元素类型，`range` 输入给字符串是
+ * DOM 事实，转不转数字由渲染器决定（它知道自己渲染的是什么）。
+ */
+function readEventValue(domEvent: Event): RenderPropValue | undefined {
+  const target: unknown = domEvent.target;
+  if (target === null || typeof target !== "object") return undefined;
+  if (!("value" in target)) return undefined;
+  const raw = (target as { value: unknown }).value;
+  if (
+    typeof raw === "string" ||
+    typeof raw === "number" ||
+    typeof raw === "boolean"
+  ) {
+    return raw;
+  }
+  return undefined;
+}
+
 function bindEvents(
   node: HTMLElement,
   events: readonly RenderEvent[] | undefined,
@@ -48,7 +69,7 @@ function bindEvents(
   for (const event of events ?? []) {
     node.addEventListener(event.on, (domEvent) => {
       if (event.stopPropagation === true) domEvent.stopPropagation();
-      const patch = event.handler?.();
+      const patch = event.handler?.(readEventValue(domEvent));
       if (patch !== undefined) applyPatch(node, patch);
     });
   }

package/src/element/index.ts

@@ -15,6 +15,7 @@ export { registerBuiltinElementRenderers } from "./renderers";
 export { renderElementTree, type ElementTreeRenderOptions } from "./render";
 export {
   type RenderEvent,
+  type RenderEventName,
   type RenderEventPatch,
   type RenderKind,
   type RenderPort,
@@ -29,6 +30,12 @@ export {
   type ElementActionOptions,
   type ElementActionSource,
 } from "./interaction";
+export {
+  parseWritebackTarget,
+  routeElementValueChange,
+  type ElementWritebackPorts,
+  type WritebackTarget,
+} from "./writeback";
 export {
   easingFn,
   easingNames,

package/src/element/registry.ts

@@ -29,6 +29,16 @@ export interface ElementRenderContext {
   evalDisable?: (expression: string) => boolean | null;
   /** 资源解析（source/src/path → 可加载 URL）；缺省或失败返回 undefined（不静默伪造） */
   resolveResource?: (path: string) => string | undefined;
+  /**
+   * 控件值变化回写：渲染器把「哪个元素变成了什么值」交给宿主，**不自己写状态**。
+   *
+   * 落点由宿主决定（偏好 / 作用域状态 / 命名命令），UI 层不认识引擎；
+   * 未注入 = 宿主没接回写通道，控件仍可拖但值不落地（静默，不抛）。
+   */
+  onElementValueChange?: (
+    element: ElementInstance,
+    value: number | string | boolean,
+  ) => void;
 }
 
 /** 渲染器：产出元素的描述树（根节点承载类名/样式，子元素在 `children` 里） */

package/src/element/render.ts

@@ -13,7 +13,8 @@ import type { RenderPort, RenderSpec } from "./spec";
 
 /**
  * 一帧元素树的渲染请求：`registry` / `port` / `elements` 必给，
- * 其余三个回调不传即「没有对应的宿主能力」（表现为元素不可点、表达式不求解、资源显示替代文本）。
+ * 其余回调不传即「没有对应的宿主能力」（表现为元素不可点、表达式不求解、
+ * 资源显示替代文本、控件值不落地）。
  *
  * `port` 是宿主注入的渲染端口（Web 侧 `createDomRenderPort`）——渲染器只产出描述树，
  * 平台差异全部完成在端口实现里。
@@ -28,6 +29,14 @@ export interface ElementTreeRenderOptions {
   evalDisable?: (expression: string) => boolean | null;
   /** 资源解析（source/src/path → URL） */
   resolveResource?: (path: string) => string | undefined;
+  /**
+   * 控件值变化回写（`slider` 等带值控件用）：渲染器只上报「哪个元素变成了什么值」，
+   * 落点由宿主决定（偏好 / 作用域状态 / 命名命令）。不传 = 控件可操作但值不落地。
+   */
+  onElementValueChange?: (
+    element: ElementInstance,
+    value: number | string | boolean,
+  ) => void;
   /** 未注册类型上报（fail-closed；宿主负责可见诊断） */
   onUnknownType?: (type: string) => void;
 }
@@ -63,6 +72,7 @@ export function renderElementTree(options: ElementTreeRenderOptions): void {
       activate: options.activate,
       evalDisable: options.evalDisable,
       resolveResource: options.resolveResource,
+      onElementValueChange: options.onElementValueChange,
     });
     // 舞台内叠放序（两级叠放：元素之间在 stage 容器内独立比较）覆盖作者声明，
     // 帧驱动定位锚挂在根节点上（动画按 id 找节点）