@yaoxiu/marketing-dsl 2.2.1 → 2.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { normalizeViews, createTicker, evaluate, resolveNodeStyle, interpolateDeep, interpolate, toLength, toCssStyle, parseEndTime, computeParts, formatParts } from './chunk-DTHKC5AL.js';
-export { ACTION_TYPES, ALLOWED_STYLE_KEYS, BANNER_MIN_ASPECT_RATIO, CLOSE_POSITIONS, DEFAULT_USER_FIELDS, DSL_VERSION, NODE_TYPES, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, USER_FIELD_LABELS, check, computeParts, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, toCssStyle, toLength, validate, validateUserFields } from './chunk-DTHKC5AL.js';
+import { normalizeViews, nextScopeUid, createTicker, createCssBuilder, declarations, toCssStyle, interpolateDeep, evaluate, resolveNodeStyle, interpolate, toLength, computeParts, formatParts, parseEndTime } from './chunk-DT3ZINDI.js';
+export { ACTION_TYPES, ALLOWED_EASINGS, ALLOWED_STYLE_KEYS, BANNER_MIN_ASPECT_RATIO, CLOSE_POSITIONS, CSS_NAME_PATTERN, DEFAULT_USER_FIELDS, DSL_VERSION, NODE_TYPES, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, USER_FIELD_LABELS, check, computeParts, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isKeyframeOffset, isLength, isValidEasing, isValidEndTime, normalizeViews, parseEndTime, sanitizeCssValue, toCssStyle, toLength, validate, validateUserFields } from './chunk-DT3ZINDI.js';
 
 // src/url.ts
 var SAFE_PROTOCOLS = ["http:", "https:", "mailto:", "tel:"];
@@ -103,17 +103,13 @@ function createDispatcher(options) {
 // src/resolve.ts
 function resolveTree(input) {
   const { normalized, viewStack, ready } = input;
+  const css = createCssBuilder(input.scopeUid, input.keyframes, input.hover);
+  const pass = Object.assign({}, input, { css });
   const layers = viewStack.map((name) => ({ name, view: normalized.views[name] })).filter((item) => !!item.view);
   const hasPopup = layers.some((item) => item.view.type === "popup");
   const countdowns = { endTimes: [], precision: "s" };
   const renderLayers = ready ? layers.map(
-    (item, index) => resolveLayer(
-      item.name,
-      item.view,
-      index === layers.length - 1,
-      input,
-      countdowns
-    )
+    (item, index) => resolveLayer(item.name, item.view, index === layers.length - 1, pass, countdowns)
   ) : [];
   return {
     ready: ready && layers.length > 0,
@@ -124,7 +120,10 @@ function resolveTree(input) {
     rootStyle: { position: "relative" },
     layers: renderLayers,
     countdownEndTimes: countdowns.endTimes,
-    countdownPrecision: countdowns.precision
+    countdownPrecision: countdowns.precision,
+    // build 必须在 layers 算完之后调：hover 规则是遍历节点时才登记进来的
+    css: css.build(),
+    rootClassName: css.rootClassName
   };
 }
 function resolveLayer(name, view, isTop, input, countdowns) {
@@ -133,7 +132,7 @@ function resolveLayer(name, view, isTop, input, countdowns) {
   const isPopup = view.type === "popup";
   const rootLayout = stage.layout === "flow" ? "flow" : "absolute";
   const maskClosable = !!stage.maskClosable;
-  const onMaskClick = maskClosable ? () => closeTop("mask") : void 0;
+  const onMaskClick = maskClosable ? stage.maskAction ? () => input.dispatch(stage.maskAction, context) : () => closeTop("mask") : void 0;
   const nodes = (view.nodes || []).map(
     (node, index) => resolveNode(node, `${name}-${index}`, rootLayout, context, input, countdowns)
   ).filter((el) => !!el);
@@ -141,20 +140,26 @@ function resolveLayer(name, view, isTop, input, countdowns) {
     name,
     type: view.type,
     isTop,
-    // 只有栈顶那层画遮罩，否则两层遮罩叠加会明显变黑
-    mask: isPopup && stage.mask !== false && isTop,
-    onMaskClick,
+    /**
+     * 弹窗层恒画遮罩元素，**非栈顶时只是变透明**（见下方 maskStyle）。
+     *
+     * 【为什么不是「只有栈顶才画」】那样写视觉上也对（两层实心遮罩叠加会明显变黑，
+     * 所以下层必须让位），但下层的遮罩 DOM 会被整个移除、退回栈顶时再新建一个 ——
+     * 新元素身上的 `maskAnimate` 于是又播一遍：关掉二次挽留层回到主弹窗时，
+     * 背景会重新淡入一次，看起来就是「闪了一下」。元素常驻就没这问题。
+     */
+    mask: isPopup && stage.mask !== false,
+    // 非栈顶层整层 pointerEvents: none，遮罩点不到，这里也就不必给它挂回调
+    onMaskClick: isTop ? onMaskClick : void 0,
     layerStyle: layerStyle(isPopup, isTop),
-    maskStyle: {
-      position: "absolute",
-      top: "0",
-      right: "0",
-      bottom: "0",
-      left: "0",
-      background: "rgba(0, 0, 0, 0.55)"
-    },
+    // 合并顺序固定：内置默认 → stage.maskStyle 覆盖 → maskAnimate 的 animation 收尾。
+    // 遮罩样式也走一遍插值，切 tab 时能跟着变（同 stage.style）
+    maskStyle: maskStyle(stage, isTop, context, input),
     scrollStyle: scrollStyle(isPopup),
-    stageStyle: resolveStageStyle(stage, isPopup, context),
+    stageStyle: withAnimation(
+      resolveStageStyle(stage, isPopup, context),
+      input.css.animation(stage.animate)
+    ),
     clipStyle: {
       position: "relative",
       height: "100%",
@@ -162,10 +167,39 @@ function resolveLayer(name, view, isTop, input, countdowns) {
       overflow: "hidden",
       boxSizing: "border-box"
     },
-    closeButton: resolveCloseButton(stage.closeButton, name, closeTop),
+    closeButton: resolveCloseButton(stage.closeButton, name, closeTop, input, context),
     nodes
   };
 }
+function withAnimation(style, animation) {
+  if (animation) style.animation = animation;
+  return style;
+}
+function maskStyle(stage, isTop, context, input) {
+  const style = withAnimation(
+    Object.assign(
+      {
+        position: "absolute",
+        top: "0",
+        right: "0",
+        bottom: "0",
+        left: "0",
+        background: "rgba(0, 0, 0, 0.55)"
+      },
+      toCssStyle(interpolateDeep(stage.maskStyle, context))
+    ),
+    input.css.animation(stage.maskAnimate)
+  );
+  if (isTop) return style;
+  style.background = "transparent";
+  delete style.backdropFilter;
+  delete style.WebkitBackdropFilter;
+  return style;
+}
+function withHover(className, owner, css) {
+  const hoverClass = css.hoverClass(owner);
+  return hoverClass ? `${className} ${hoverClass}` : className;
+}
 function layerStyle(isPopup, isTop) {
   const style = isPopup ? {
     position: "fixed",
@@ -223,7 +257,8 @@ function resolveStageStyle(stage, isPopup, context) {
   }
   return style;
 }
-function resolveCloseButton(config, layerName, closeTop) {
+function resolveCloseButton(config, layerName, closeTop, input, context) {
+  const css = input.css;
   if (!config || config.show === false) return void 0;
   const offset = config.offset || [8, 8];
   const size = config.size === void 0 ? 26 : config.size;
@@ -261,12 +296,14 @@ function resolveCloseButton(config, layerName, closeTop) {
     style.right = toLength(offset[0]);
   }
   Object.assign(style, toCssStyle(config.style));
-  const onClick = () => closeTop("close-button");
+  withAnimation(style, css.animation(config.animate));
+  const className = withHover("dsl-close", config, css);
+  const onClick = config.action ? () => input.dispatch(config.action, context) : () => closeTop("close-button");
   if (iconMode === "image") {
     return {
       key: `${layerName}-close`,
       tag: "div",
-      className: "dsl-close",
+      className,
       style,
       onClick,
       children: [
@@ -289,7 +326,7 @@ function resolveCloseButton(config, layerName, closeTop) {
     return {
       key: `${layerName}-close`,
       tag: "div",
-      className: "dsl-close",
+      className,
       style,
       onClick,
       text: config.icon
@@ -298,7 +335,7 @@ function resolveCloseButton(config, layerName, closeTop) {
   return {
     key: `${layerName}-close`,
     tag: "div",
-    className: "dsl-close",
+    className,
     style,
     onClick,
     children: [closeIcon(`${layerName}-close-icon`, size)]
@@ -386,6 +423,12 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       layout
     )
   );
+  withAnimation(style, input.css.animation(node.animate));
+  const hoverClass = input.css.hoverClass(node);
+  const cls = (type, clickable) => {
+    const base = nodeClass(type, clickable);
+    return hoverClass ? `${base} ${hoverClass}` : base;
+  };
   const onClick = node.action ? () => input.dispatch(node.action, context) : void 0;
   if (onClick && !style.cursor) style.cursor = "pointer";
   switch (node.type) {
@@ -393,7 +436,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("box", !!onClick),
+        className: cls("box", !!onClick),
         style: Object.assign({ position: "relative" }, style),
         onClick,
         children: resolveChildren(
@@ -409,7 +452,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("flex", !!onClick),
+        className: cls("flex", !!onClick),
         style: Object.assign({ display: "flex" }, style),
         onClick,
         children: resolveChildren(node.children, key, "flow", context, input, countdowns)
@@ -418,7 +461,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("repeat", !!onClick),
+        className: cls("repeat", !!onClick),
         style: Object.assign({ display: "flex" }, style),
         onClick,
         children: resolveRepeat(node, key, context, input, countdowns)
@@ -427,7 +470,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("tabs", false),
+        className: cls("tabs", false),
         style: Object.assign({ display: "flex" }, style),
         children: resolveTabs(node, key, context, input)
       };
@@ -435,7 +478,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "img",
-        className: nodeClass("image", !!onClick),
+        className: cls("image", !!onClick),
         src: safeImageUrl(interpolate(node.src, context)),
         style: Object.assign({ display: "block", objectFit: "cover" }, style),
         onClick
@@ -444,7 +487,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("text", !!onClick),
+        className: cls("text", !!onClick),
         style: Object.assign({ wordBreak: "break-word" }, style),
         text: toText(interpolate(node.content, context)),
         onClick
@@ -453,7 +496,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
       return {
         key,
         tag: "div",
-        className: nodeClass("button", true),
+        className: cls("button", true),
         style: Object.assign(
           {
             display: "flex",
@@ -469,7 +512,7 @@ function resolveNode(node, key, layout, context, input, countdowns) {
         onClick
       };
     case "countdown":
-      return resolveCountdown(node, key, style, context, input, countdowns);
+      return resolveCountdown(node, key, style, context, input, countdowns, hoverClass);
     // 配置比解释器新时，未知类型降级为不渲染，不阻断整个弹窗
     default:
       return void 0;
@@ -531,10 +574,23 @@ function resolveTabs(node, key, context, input) {
     };
   });
 }
-function resolveCountdown(node, key, style, context, input, countdowns) {
-  var _a;
+function resolveCountdownEndTime(node, key, context, input) {
   const endTime = parseEndTime(interpolate(node.to, context));
+  if (endTime > 0) return endTime;
+  const duration = Number(interpolate(node.duration, context));
+  if (!isFinite(duration) || duration <= 0) return 0;
+  let start = input.countdownStarts.get(key);
+  if (start === void 0) {
+    start = Date.now();
+    input.countdownStarts.set(key, start);
+  }
+  return start + duration;
+}
+function resolveCountdown(node, key, style, context, input, countdowns, hoverClass) {
+  var _a;
+  const endTime = resolveCountdownEndTime(node, key, context, input);
   const parts = computeParts(endTime);
+  const cls = (base) => hoverClass ? `${base} ${hoverClass}` : base;
   countdowns.endTimes.push(endTime);
   if (node.precision === "cs") countdowns.precision = "cs";
   if (endTime && node.onEnd) {
@@ -551,7 +607,7 @@ function resolveCountdown(node, key, style, context, input, countdowns) {
     return {
       key,
       tag: "div",
-      className: "dsl-node dsl-text dsl-countdown",
+      className: cls("dsl-node dsl-text dsl-countdown"),
       style: Object.assign({ wordBreak: "break-word" }, style),
       text: node.endText || "\u5DF2\u7ED3\u675F"
     };
@@ -560,7 +616,7 @@ function resolveCountdown(node, key, style, context, input, countdowns) {
     return {
       key,
       tag: "div",
-      className: "dsl-node dsl-text dsl-countdown",
+      className: cls("dsl-node dsl-text dsl-countdown"),
       style: Object.assign({ wordBreak: "break-word" }, style),
       text: formatParts(parts, node.format)
     };
@@ -569,7 +625,7 @@ function resolveCountdown(node, key, style, context, input, countdowns) {
   return {
     key,
     tag: "div",
-    className: "dsl-node dsl-flex dsl-countdown",
+    className: cls("dsl-node dsl-flex dsl-countdown"),
     style: Object.assign({ display: "flex" }, style),
     children: resolveChildren(
       node.children,
@@ -585,6 +641,37 @@ function toText(value) {
   return value === void 0 || value === null ? "" : String(value);
 }
 
+// src/hover.ts
+function collectHoverStyles(views, uid, context) {
+  const rules = [];
+  const classOf = /* @__PURE__ */ new WeakMap();
+  const scope = `.dsl-r${uid}`;
+  let seed = 0;
+  const register = (owner, style) => {
+    if (!owner || !style || typeof style !== "object") return;
+    const body = declarations(toCssStyle(interpolateDeep(style, context)));
+    if (!body) return;
+    seed += 1;
+    const className = `dsl-hv-${uid}-${seed}`;
+    classOf.set(owner, className);
+    rules.push(`${scope} .${className}:hover{${body}}`);
+  };
+  const walkNode = (node) => {
+    if (!node || typeof node !== "object") return;
+    register(node, node.hoverStyle);
+    (node.children || []).forEach(walkNode);
+    walkNode(node.template);
+  };
+  Object.keys(views).forEach((name) => {
+    const view = views[name];
+    if (!view || typeof view !== "object") return;
+    const closeButton = view.stage && view.stage.closeButton;
+    register(closeButton, closeButton && closeButton.hoverStyle);
+    (view.nodes || []).forEach(walkNode);
+  });
+  return { rules, classOf };
+}
+
 // src/runtime.ts
 var noopEmit = () => {
 };
@@ -596,6 +683,7 @@ function createRuntime(dsl, options = {}) {
     editMode: !!options.editMode
   };
   const normalized = normalizeViews(dsl);
+  const scopeUid = nextScopeUid();
   let state = Object.assign({}, dsl.state || {});
   let resolvedData = {};
   let viewStack = [normalized.entry];
@@ -604,6 +692,7 @@ function createRuntime(dsl, options = {}) {
   let destroyed = false;
   const listeners = /* @__PURE__ */ new Set();
   const countdownEnds = /* @__PURE__ */ new Map();
+  const countdownStarts = /* @__PURE__ */ new Map();
   const notify = () => {
     if (destroyed) return;
     listeners.forEach((fn) => fn());
@@ -737,7 +826,9 @@ function createRuntime(dsl, options = {}) {
     });
   }
   loadData();
+  let hover;
   function getTree() {
+    if (!hover) hover = collectHoverStyles(normalized.views, scopeUid, buildContext());
     const tree = resolveTree({
       normalized,
       viewStack,
@@ -747,7 +838,11 @@ function createRuntime(dsl, options = {}) {
       dispatch,
       setState,
       closeTop,
-      countdownEnds
+      countdownEnds,
+      countdownStarts,
+      scopeUid,
+      keyframes: dsl.keyframes,
+      hover
     });
     ticker.sync(tree.countdownEndTimes, tree.countdownPrecision);
     return tree;
@@ -774,4 +869,19 @@ function createRuntime(dsl, options = {}) {
   };
 }
 
-export { createRuntime, safeImageUrl, safeUrl };
+// src/host-capabilities.ts
+var HOST_SOURCE_NAMES = ["shopAchievements", "listRenewTiers"];
+var HOST_HANDLER_NAMES = [];
+var HOST_SOURCE_LABELS = {
+  shopAchievements: "\u5E97\u94FA\u6210\u679C\u7EDF\u8BA1\uFF08\u5DF2\u4E0A\u67B6/\u8FD0\u884C\u4E2D/\u767D\u5E95\u56FE\u7B49\u683C\u5B50\u6570\u7EC4\uFF09",
+  listRenewTiers: "\u7EED\u8D39\u4EF7\u683C\u6863\u4F4D\u5217\u8868\uFF08\u6708\u4ED8/\u5B63\u4ED8/\u534A\u5E74/\u5E74\u4ED8\uFF0C\u542B\u4E0B\u5355\u5730\u5740\uFF09"
+};
+var HOST_HANDLER_LABELS = {};
+function isRegisteredHostSource(name) {
+  return HOST_SOURCE_NAMES.indexOf(name) > -1;
+}
+function isRegisteredHostHandler(name) {
+  return HOST_HANDLER_NAMES.indexOf(name) > -1;
+}
+
+export { HOST_HANDLER_LABELS, HOST_HANDLER_NAMES, HOST_SOURCE_LABELS, HOST_SOURCE_NAMES, createRuntime, isRegisteredHostHandler, isRegisteredHostSource, safeImageUrl, safeUrl };

package/dist/report/index.d.cts

@@ -1,4 +1,4 @@
-import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.cjs';
+import { I as RuntimeEventName, G as DslInteractionEvent } from '../types-8FNxDXp0.cjs';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。

package/dist/report/index.d.ts

@@ -1,4 +1,4 @@
-import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.js';
+import { I as RuntimeEventName, G as DslInteractionEvent } from '../types-8FNxDXp0.js';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。

package/dist/{types-Bj0xyWnx.d.cts → types-8FNxDXp0.d.cts}

@@ -15,6 +15,40 @@ type DslLength = number | string;
 type DslRect = [DslLength, DslLength, DslLength, DslLength];
 /** 样式对象，键必须在白名单内，值可以带 {{ }} */
 type DslStyle = Record<string, unknown>;
+/**
+ * 动画声明。
+ *
+ * 只描述「播哪一组 keyframes、怎么播」，关键帧本身写在 `Dsl.keyframes` 里。
+ * 解释器把它落成**行内** `animation` 简写，keyframes 定义才进 `RenderTree.css`——
+ * 这样同一份配置在页面上出现多次也不会互相污染（keyframes 名带作用域前缀）。
+ */
+interface DslAnimate {
+    /** keyframes 名：必须在 `dsl.keyframes` 里定义过 */
+    name: string;
+    /** 时长，毫秒 */
+    duration: number;
+    /** 延迟，毫秒，默认 0。交错入场就靠它错开 */
+    delay?: number;
+    /**
+     * 缓动函数。白名单：
+     * linear / ease / ease-in / ease-out / ease-in-out / step-start / step-end /
+     * cubic-bezier(x, x, x, x)。默认 `ease`
+     */
+    easing?: string;
+    /** 播放次数，默认 1；`'infinite'` 表示无限循环（呼吸、扫光这类） */
+    iteration?: number | 'infinite';
+    /** 播放方向，默认 `normal` */
+    direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+    /** 填充模式，默认 `both`（入场动画必须保留终态，否则播完会弹回初始值） */
+    fill?: 'none' | 'forwards' | 'backwards' | 'both';
+}
+/**
+ * 一组关键帧：偏移量 → 样式。
+ *
+ * 偏移量只接受 `'from'` / `'to'` / `'0%'` 这三种写法；
+ * 样式仍要过 style 白名单，写了白名单外的属性会被丢弃。
+ */
+type DslKeyframe = Record<string, DslStyle>;
 interface DslActionBase {
     type: string;
 }
@@ -65,6 +99,15 @@ interface DslNode {
     /** 表达式，为假时整个节点不渲染 */
     visibleWhen?: string;
     action?: DslAction;
+    /** 入场 / 循环动画 */
+    animate?: DslAnimate;
+    /**
+     * 鼠标悬停时叠加的样式。
+     *
+     * **只会生成 CSS 规则，不进行内联**——行内样式没有 `:hover` 这个东西，
+     * 想在行内做只能靠 JS 监听鼠标事件，那既要框架壳配合、又天然丢触屏。
+     */
+    hoverStyle?: DslStyle;
     /** box / flex / countdown */
     children?: DslNode[];
     /** repeat / tabs：数组来源表达式 */
@@ -86,6 +129,14 @@ interface DslNode {
     text?: string;
     /** countdown */
     to?: string;
+    /**
+     * countdown 的相对时长（毫秒）。
+     *
+     * 从**该视图展示那一刻**起算，「每次打开重新倒 5 分钟」这类写法用它。
+     * 与 `to` 同时存在时 `to` 优先（绝对时间更明确）。
+     * 起算时间戳钉在运行时里，重算渲染树不会把剩余时间刷回去。
+     */
+    duration?: number;
     precision?: 's' | 'cs';
     as?: string;
     format?: string;
@@ -95,6 +146,15 @@ interface DslNode {
 type DslClosePosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
 interface DslCloseButton {
     show?: boolean;
+    /**
+     * 点它做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」（多视图里等于弹栈退回上一层，单视图即整体关闭）。
+     * 配了就**只**执行这个动作、不再自动关层 —— 「点 ✕ 先弹二次挽留」正是靠它：
+     * `{ "type": "open", "view": "confirm", "mode": "stack" }`。
+     * 想在动作里顺带关掉，自己写 `close` / `closeAll` 进去。
+     */
+    action?: DslAction;
     position?: DslClosePosition;
     /** [x, y]，负值把按钮移到弹窗外面 */
     offset?: [DslLength, DslLength];
@@ -102,6 +162,10 @@ interface DslCloseButton {
     icon?: string;
     image?: string;
     style?: DslStyle;
+    /** 悬停样式，只生成 CSS 规则 */
+    hoverStyle?: DslStyle;
+    /** 关闭按钮自己的动画（如延迟淡入，先让用户看内容） */
+    animate?: DslAnimate;
 }
 interface DslStage {
     width?: DslLength;
@@ -110,8 +174,30 @@ interface DslStage {
     layout?: 'absolute' | 'flow';
     mask?: boolean;
     maskClosable?: boolean;
+    /**
+     * 点遮罩做什么。
+     *
+     * 不配就是默认行为「关掉当前这一层」。配了就执行这个动作而不关层
+     * （原页面点遮罩弹二次挽留就是这么来的）。
+     *
+     * 与 `maskClosable` 各管一件事、不冲突：`maskClosable: false` 时遮罩根本不响应点击，
+     * 这个动作也不会执行；`maskAction` 只决定「点了之后做什么」。
+     */
+    maskAction?: DslAction;
     closeButton?: DslCloseButton;
+    /**
+     * 遮罩自身样式，走 style 白名单。
+     *
+     * 内置默认是 `rgba(0, 0, 0, 0.55)` 纯色，这里配的会**覆盖**默认值
+     * （常用 `background` 改深浅、`backdropFilter: 'blur(4px)'` 加毛玻璃）。
+     * `maskAnimate` 生成的 `animation` 仍排在最后，不会被这里的配置盖掉。
+     */
+    maskStyle?: DslStyle;
     style?: DslStyle;
+    /** 舞台入场动画（弹窗主体的弹入 / 放大） */
+    animate?: DslAnimate;
+    /** 遮罩入场动画（一般是淡入，和舞台分开配才能各走各的时长） */
+    maskAnimate?: DslAnimate;
     /** 曝光埋点：数据就绪、视图真正展示时触发一次 */
     onShow?: DslAction;
     /** 关闭埋点：点 X、点遮罩、close 动作、被 replace 顶掉都会触发 */
@@ -145,6 +231,13 @@ interface Dsl extends Partial<DslView> {
     derived?: Record<string, DslDerived>;
     views?: Record<string, DslView>;
     entry?: string;
+    /**
+     * 关键帧库，`{ 名字: { 偏移量: 样式 } }`。
+     *
+     * 全配置共用一份（多视图之间也共用），`animate.name` 引用这里的名字。
+     * 名字只能是 `^[a-zA-Z][a-zA-Z0-9_-]{0,31}$`——它会被拼进 CSS 文本，必须可控。
+     */
+    keyframes?: Record<string, DslKeyframe>;
 }
 /** 已经算好的行内样式，键是 CSS 属性名（驼峰），值是最终字符串 */
 type CssStyle = Record<string, string>;
@@ -198,8 +291,15 @@ interface RenderLayer {
     name: string;
     type: DslViewType;
     isTop: boolean;
-    /** 画不画遮罩。只有栈顶的弹窗层才为 true */
+    /**
+     * 画不画遮罩元素。弹窗层恒为 true（`stage.mask: false` 除外），**包括非栈顶的层**。
+     *
+     * 遮挡效果由 `maskStyle` 控制：非栈顶层的底色是 transparent，实际遮挡永远只有栈顶那层
+     * （两层实心遮罩叠加会明显变黑）。元素本身常驻是刻意的 —— 按 isTop 增删这个 DOM 节点，
+     * 会让下层的 `maskAnimate` 在退回栈顶时重播一遍，表现为「关掉二次挽留层，背景闪了一下」。
+     */
     mask: boolean;
+    /** 点遮罩的回调。只有栈顶那层才有：非栈顶层整层 pointerEvents: none，点不到 */
     onMaskClick?: () => void;
     layerStyle: CssStyle;
     maskStyle: CssStyle;
@@ -227,6 +327,20 @@ interface RenderTree {
     countdownEndTimes: number[];
     /** 只要有一个倒计时要厘秒，整体就按厘秒刷 */
     countdownPrecision: 's' | 'cs';
+    /**
+     * 这份配置要注入页面的全部 CSS 文本（keyframes 定义 + hover 规则 + reduced-motion 兜底）。
+     *
+     * 没有动画也没有 hover 时是**空串**，此时框架壳不该建 `<style>` 元素。
+     * 内容已经过安全过滤，壳直接塞进 `<style>` 即可，**不得在壳里做任何生成或判断**。
+     */
+    css: string;
+    /**
+     * 根容器类名，形如 `dsl-renderer dsl-r3`。
+     *
+     * 后半截是这个运行时实例的作用域前缀，`css` 里的每条规则都挂在它下面——
+     * 同一个页面上出现多份物料时，各自的 hover 规则不会串台。
+     */
+    rootClassName: string;
 }
 type DslSource = (params: Record<string, unknown>, user: Record<string, unknown>) => unknown | Promise<unknown>;
 type DslHandler = (params: Record<string, unknown>) => void;
@@ -342,4 +456,4 @@ interface RuntimeOptions {
     emit?: RuntimeEmit;
 }
 
-export type { DslHandler as A, DslInteractionTrigger as B, CssStyle as C, Dsl as D, DslInteractionEvent as E, RuntimeEvents as F, RuntimeEventName as G, RuntimeEmit as H, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslActionBase as h, DslNavigateAction as i, DslCloseAction as j, DslCloseAllAction as k, DslOpenAction as l, DslSetStateAction as m, DslTrackAction as n, DslCallAction as o, DslSequenceAction as p, DslAction as q, DslNode as r, DslClosePosition as s, DslCloseButton as t, DslStage as u, DslSourceRef as v, DslDerived as w, RenderElement as x, RenderLayer as y, DslSource as z };
+export type { RenderLayer as A, DslSource as B, CssStyle as C, Dsl as D, DslHandler as E, DslInteractionTrigger as F, DslInteractionEvent as G, RuntimeEvents as H, RuntimeEventName as I, RuntimeEmit as J, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslAnimate as h, DslKeyframe as i, DslActionBase as j, DslNavigateAction as k, DslCloseAction as l, DslCloseAllAction as m, DslOpenAction as n, DslSetStateAction as o, DslTrackAction as p, DslCallAction as q, DslSequenceAction as r, DslAction as s, DslNode as t, DslClosePosition as u, DslCloseButton as v, DslStage as w, DslSourceRef as x, DslDerived as y, RenderElement as z };