@yaoxiu/marketing-dsl 1.5.2 → 2.1.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { normalizeViews, createTicker, interpolateDeep, interpolate, evaluate, resolveNodeStyle, toLength, toCssStyle, parseEndTime, computeParts, formatParts } from './chunk-FKZKLCVV.js';
-export { ACTION_TYPES, ALLOWED_STYLE_KEYS, CLOSE_POSITIONS, DSL_VERSION, NODE_TYPES, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, check, computeParts, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, toCssStyle, toLength, validate } from './chunk-FKZKLCVV.js';
+import { normalizeViews, createTicker, evaluate, resolveNodeStyle, interpolateDeep, interpolate, toLength, toCssStyle, parseEndTime, computeParts, formatParts } from './chunk-7TWWOK7Q.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-7TWWOK7Q.js';
 
 // src/url.ts
 var SAFE_PROTOCOLS = ["http:", "https:", "mailto:", "tel:"];
@@ -22,13 +22,13 @@ function safeImageUrl(input) {
 // src/actions.ts
 function createDispatcher(options) {
   const { setState, emit, openView, closeTop, closeAll } = options;
-  function dispatch(action, context) {
+  function run(action, context, interaction) {
     if (!action || !action.type) return;
     const handlers = options.handlers || {};
     const editMode = !!options.editMode;
     switch (action.type) {
       case "sequence":
-        (action.actions || []).forEach((item) => dispatch(item, context));
+        (action.actions || []).forEach((item) => run(item, context, interaction));
         return;
       case "navigate": {
         const url = safeUrl(interpolate(action.url, context));
@@ -38,6 +38,7 @@ function createDispatcher(options) {
         }
         const target = action.target || "_blank";
         emit("navigate", { url, target });
+        if (!interaction.navigate) interaction.navigate = { url, target };
         if (editMode) return;
         if (typeof window === "undefined") return;
         if (target === "_self") window.location.href = url;
@@ -51,20 +52,25 @@ function createDispatcher(options) {
         return;
       // 关掉栈顶那层；只剩一层时就是整体关闭
       case "close":
+        interaction.closes = true;
         closeTop(action.reason);
         return;
       case "closeAll":
+        interaction.closes = true;
         closeAll(action.reason);
         return;
       case "setState":
         setState(action.key, interpolate(action.value, context));
         return;
-      case "track":
-        emit("track", {
+      case "track": {
+        const payload = {
           event: String(interpolate(action.event, context)),
           params: interpolateDeep(action.params || {}, context)
-        });
+        };
+        emit("track", payload);
+        if (!interaction.track) interaction.track = payload;
         return;
+      }
       case "call": {
         const handler = handlers[action.name];
         if (typeof handler !== "function") {
@@ -84,6 +90,13 @@ function createDispatcher(options) {
         });
     }
   }
+  function dispatch(action, context, meta) {
+    if (!action || !action.type) return;
+    const interaction = { trigger: (meta == null ? void 0 : meta.trigger) || "action" };
+    if ((meta == null ? void 0 : meta.reason) !== void 0) interaction.reason = meta.reason;
+    run(action, context, interaction);
+    emit("interaction", interaction);
+  }
   return dispatch;
 }
 
@@ -91,9 +104,7 @@ function createDispatcher(options) {
 function resolveTree(input) {
   const { normalized, viewStack, ready } = input;
   const layers = viewStack.map((name) => ({ name, view: normalized.views[name] })).filter((item) => !!item.view);
-  const hasPopup = Object.keys(normalized.views).some(
-    (name) => normalized.views[name].type === "popup"
-  );
+  const hasPopup = layers.some((item) => item.view.type === "popup");
   const countdowns = { endTimes: [], precision: "s" };
   const renderLayers = ready ? layers.map(
     (item, index) => resolveLayer(
@@ -107,8 +118,10 @@ function resolveTree(input) {
   return {
     ready: ready && layers.length > 0,
     hasPopup,
-    // 配置里有弹窗视图时，根容器要撑满宿主容器，弹窗层才有地方铺
-    rootStyle: hasPopup ? { position: "absolute", top: "0", right: "0", bottom: "0", left: "0" } : { position: "relative" },
+    // 根容器恒为 relative：它要待在宿主给的位置上（banner / 公告坑位是流式的普通 div，
+    // 根容器一脱流坑位就塌成 0、内容按最近定位祖先飘走）。弹窗铺满视口由弹窗层自己
+    // `position: fixed` 完成，不再靠根容器撑开，见 layerStyle。
+    rootStyle: { position: "relative" },
     layers: renderLayers,
     countdownEndTimes: countdowns.endTimes,
     countdownPrecision: countdowns.precision
@@ -154,7 +167,15 @@ function resolveLayer(name, view, isTop, input, countdowns) {
   };
 }
 function layerStyle(isPopup, isTop) {
-  const style = isPopup ? { position: "absolute", top: "0", right: "0", bottom: "0", left: "0" } : {};
+  const style = isPopup ? {
+    position: "fixed",
+    top: "0",
+    right: "0",
+    bottom: "0",
+    left: "0",
+    // 弹窗层可能挂在页面中段的坑位里，不提层会被后面的内容盖住
+    zIndex: "1000"
+  } : {};
   if (!isTop) style.pointerEvents = "none";
   return style;
 }
@@ -182,7 +203,7 @@ function resolveStageStyle(stage, isPopup, context) {
     base.margin = "auto";
     base.flex = "none";
   }
-  return Object.assign(
+  const style = Object.assign(
     base,
     {
       // width / height 支持数字（px）、'100%' / 'auto' / calc(...) 等相对单位，也支持 {{ }}
@@ -196,6 +217,11 @@ function resolveStageStyle(stage, isPopup, context) {
     // stage.style 也走一遍插值，这样切 tab 时弹窗本身的背景能跟着变
     toCssStyle(interpolateDeep(stage.style, context))
   );
+  if (!isPopup && style.maxWidth !== void 0 && style.margin === void 0) {
+    style.marginLeft = "auto";
+    style.marginRight = "auto";
+  }
+  return style;
 }
 function resolveCloseButton(config, layerName, closeTop) {
   if (!config || config.show === false) return void 0;
@@ -659,7 +685,11 @@ function createRuntime(dsl, options = {}) {
     const view = normalized.views[viewName];
     const action = view && view.stage && view.stage[hook];
     if (!action) return;
-    dispatch(action, Object.assign({}, buildContext(), extra));
+    const reason = extra && extra.closeReason;
+    dispatch(action, Object.assign({}, buildContext(), extra), {
+      trigger: hook === "onShow" ? "show" : "close",
+      reason: typeof reason === "string" ? reason : void 0
+    });
   }
   function loadData() {
     const data = dsl.data || {};
@@ -690,8 +720,8 @@ function createRuntime(dsl, options = {}) {
       resolvedData = resolved;
       loading = false;
       notify();
-      emit("ready", { keys: Object.keys(resolved) });
       fireLifecycle(normalized.entry, "onShow");
+      emit("ready", { keys: Object.keys(resolved) });
     }).catch((error) => {
       if (destroyed) return;
       loading = false;

package/dist/report/index.cjs

@@ -1,41 +1,58 @@
 'use strict';
 
 // src/report/map.ts
-function buildExposureReport(id) {
+function pickInteractionTrack(payload) {
+  const track = payload == null ? void 0 : payload.track;
+  if (!track) return void 0;
+  return { name: track.event, params: track.params };
+}
+function buildExposureReport(id, extra) {
   if (!id) return null;
-  return { id, event: "exposure" };
+  const params = { id, event: "exposure" };
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
 }
-function mapRuntimeEventToReport(id, event, payload) {
+function buildCloseReport(id, options) {
   if (!id) return null;
-  switch (event) {
-    case "track": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "track", name: data.event, params: data.params }
-      };
-    }
-    case "navigate": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "navigate", url: data.url }
-      };
-    }
-    case "close": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "close",
-        reason: data.reason
-      };
-    }
-    default:
-      return null;
+  const params = {
+    id,
+    event: "close",
+    reason: options == null ? void 0 : options.reason
+  };
+  const extra = options == null ? void 0 : options.extra;
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
+}
+function buildClickExtra(payload) {
+  const { track, navigate } = payload;
+  if (track) {
+    const extra = {
+      trigger: "track",
+      name: track.event,
+      params: track.params
+    };
+    if (navigate == null ? void 0 : navigate.url) extra.url = navigate.url;
+    return extra;
   }
+  if (navigate) return { trigger: "navigate", url: navigate.url };
+  return null;
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  if (event !== "interaction") return null;
+  const data = payload != null ? payload : {};
+  if (data.trigger !== "action") return null;
+  if (data.closes) return null;
+  const extra = buildClickExtra(data);
+  if (!extra) return null;
+  return { id, event: "click", extra };
 }
 
+exports.buildCloseReport = buildCloseReport;
 exports.buildExposureReport = buildExposureReport;
 exports.mapRuntimeEventToReport = mapRuntimeEventToReport;
+exports.pickInteractionTrack = pickInteractionTrack;

package/dist/report/index.d.cts

@@ -1,4 +1,4 @@
-import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
+import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.cjs';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。
@@ -19,23 +19,39 @@ import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
  * - `close` 关闭：用户关掉了这条物料
  */
 type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 运营配的埋点信息（`track` 动作的事件名与参数）
+ *
+ * 挂在 `stage.onShow` / `stage.onClose` 上的 `track` 属于「曝光埋点 / 关闭埋点」，
+ * **不算点击**，所以它们进的是 `exposure` / `close` 的 `extra`，而不是产出一条 `click`。
+ * 早期实现把这类埋点名一律映射成 `click`，直接把点击量放大了数倍。
+ */
+interface MarketingTrackExtra {
+    /** 运营在配置里写的埋点名 */
+    name?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
 /**
  * 点击上报的附加信息（**只在 `event='click'` 时有值**）
  *
  * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
  * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ *
+ * 一次点击里同时配了埋点和跳转（`sequence: [track, navigate]`，最常见的写法）时，
+ * 只产出**一条** click：`trigger='track'`，跳转地址并进 `url`。
  */
 interface MarketingClickExtra {
     /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
     trigger: 'track' | 'navigate';
     /** `trigger='track'` 时：运营在配置里写的埋点名 */
     name?: string;
-    /** `trigger='navigate'` 时：跳转目标地址 */
+    /** 跳转目标地址：`trigger='navigate'` 时必有；`trigger='track'` 时若同一次点击里还配了跳转也会带上 */
     url?: string;
     /** 运营在配置里写的自定义参数，原样透传 */
     params?: Record<string, unknown>;
 }
-/** 曝光上报入参：只有 id */
+/** 曝光上报入参：运营在 `stage.onShow` 里配了埋点时带上 `extra` */
 interface MarketingExposureReportParams {
     /** 物料 id，取自 `MarketingMaterial.id` */
     id: string;
@@ -43,8 +59,14 @@ interface MarketingExposureReportParams {
     event: 'exposure';
     /** 曝光事件无关闭原因 */
     reason?: never;
-    /** 曝光事件无点击附加信息 */
-    extra?: never;
+    /**
+     * 运营配在 `stage.onShow` 里的埋点名 / 参数，没配则不带。
+     *
+     * 【为什么并进曝光而不是单独上报】那条 `track` 记的就是「这条物料露出了」，
+     * 与曝光是同一件事，单独上报会与前台统一发的 exposure 重复计数；
+     * 但也不能直接丢掉 —— 运营配了就该在后端看得到。
+     */
+    extra?: MarketingTrackExtra;
 }
 /** 关闭上报入参：可带关闭原因 */
 interface MarketingCloseReportParams {
@@ -58,8 +80,8 @@ interface MarketingCloseReportParams {
      * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
      */
     reason?: string;
-    /** 关闭事件无点击附加信息 */
-    extra?: never;
+    /** 运营配在 `stage.onClose` 里的埋点名 / 参数，没配则不带 */
+    extra?: MarketingTrackExtra;
 }
 /** 点击上报入参：必须带 extra 说明点了什么 */
 interface MarketingClickReportParams {
@@ -76,7 +98,10 @@ interface MarketingClickReportParams {
  * 上报物料事件的入参（可辨识联合，按 `event` 区分）
  *
  * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
- * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 点击详情（`MarketingClickExtra`，带 `trigger`）只配 `click`，写错直接编译不过。
+ * `exposure` / `close` 的 `extra` 是另一种形态（`MarketingTrackExtra`，只有 `name` / `params`），
+ * 装的是运营配在 `stage.onShow` / `onClose` 里的埋点名 —— 它们不是点击，混不进 click 那一支。
+ * 不该出现的字段声明成 `?: never`
  * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
  * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
  */
@@ -88,39 +113,44 @@ type MarketingReportParams = MarketingExposureReportParams | MarketingCloseRepor
  * 前台坑位组件与后台调试台的「上报预览」共用这一份：
  * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
  * 前台改了口径而调试台忘了改，调试台就会骗人。
+ *
+ * 【只认 `interaction`，不认 `track` / `navigate`】
+ * 动作粒度的事件不能直接当上报口径：`sequence: [track, navigate]`（先埋点再跳转）
+ * 是最常见的写法，两个动作各报一条 → 点击量翻倍；而 `track` 还能挂在
+ * `stage.onShow` / `onClose` 上，动作粒度看不出时机 → 曝光和关闭也被算成点击。
+ * 解释器为此在**交互粒度**上多抛了一条 `interaction`（一次手势 / 一个时机一条），
+ * 上报只认它。
  */
 
 /**
  * 会产生上报的运行时事件及其载荷。
  *
- * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 字段一律可选（`Partial`）：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
  * 缺字段是允许的，不该在映射这一步炸掉。
  */
 interface MarketingReportableEventPayloads {
-    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
-    track: {
-        event?: string;
-        params?: Record<string, unknown>;
-    };
-    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
-    navigate: {
-        url?: string;
-        target?: string;
-    };
-    /** 关闭：`reason` 是关闭原因 */
-    close: {
-        reason?: string;
-    };
+    /** 一次交互的汇总事件，见 {@link DslInteractionEvent} */
+    interaction: Partial<DslInteractionEvent>;
 }
 /** 会产生上报的运行时事件名 */
 type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
 /**
  * 事件名 → 载荷类型。
  *
- * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
- * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ * 不产生上报的事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ * `view-change` / `ready` / `open`）载荷为 `unknown`：调用方照常传，映射返回 `null`。
  */
 type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 把交互事件里的埋点动作转成上报用的 `extra`（字段名 `event` → `name`）。
+ *
+ * 给宿主组装曝光 / 关闭上报用：`trigger='show'` / `'close'` 的 interaction 不产出点击，
+ * 但运营配的埋点名不能凭空消失，由宿主并进 exposure / close 的 `extra`。
+ *
+ * @param payload interaction 事件载荷
+ * @returns 埋点信息；没配埋点时返回 `undefined`
+ */
+declare function pickInteractionTrack(payload?: Partial<DslInteractionEvent> | null): MarketingTrackExtra | undefined;
 /**
  * 曝光上报载荷。
  *
@@ -128,17 +158,36 @@ type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends Market
  * 解释器根本不知道自己被画出来了。
  *
  * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @param extra 运营配在 `stage.onShow` 里的埋点信息，可用 {@link pickInteractionTrack} 从
+ *   `trigger='show'` 的 interaction 事件里取；没有则不带
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null, extra?: MarketingTrackExtra | null): MarketingExposureReportParams | null;
+/**
+ * 关闭上报载荷。
+ *
+ * 与曝光同理由：关闭由宿主统一上报一条 —— `close` 运行时事件才是「这条物料真的关了」，
+ * 运营配不配 `stage.onClose` 都得有这条。
+ *
+ * @param id 物料 id，为空时返回 `null`
+ * @param options `reason` 取自 `close` 运行时事件；`extra` 取自 `trigger='close'` 的 interaction
  * @returns 上报载荷，或 `null`
  */
-declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+declare function buildCloseReport(id: string | undefined | null, options?: {
+    reason?: string;
+    extra?: MarketingTrackExtra | null;
+}): MarketingCloseReportParams | null;
 /**
  * 把一个 DSL 运行时事件映射成上报载荷。
  *
  * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
- * - `track` → `click`，`extra = { trigger: 'track', name, params }`
- * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
- * - `close` → `close`，带 `reason`
- * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ * - `interaction` 且 `trigger='action'` → 一条 `click`，`extra` 见 {@link buildClickExtra}
+ * - `interaction` 且 `trigger='show'` / `'close'` → `null`：曝光 / 关闭由宿主统一上报，
+ *   运营配在这两个时机上的埋点名走 {@link buildExposureReport} / {@link buildCloseReport} 的 `extra`
+ * - `interaction` 且 `trigger='action'` 但 `closes` 为真（手势里执行了关闭动作）→ `null`：
+ *   点关闭按钮的本质是关闭，不再算一次点击
+ * - 其余事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ *   `view-change` / `ready` / `open`）不产生上报 —— 它们是动作粒度的事件，按它们上报会重复计数
  *
  * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
  * @param event 运行时事件名
@@ -147,4 +196,4 @@ declare function buildExposureReport(id: string | undefined | null): MarketingEx
  */
 declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
 
-export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, type MarketingTrackExtra, buildCloseReport, buildExposureReport, mapRuntimeEventToReport, pickInteractionTrack };

package/dist/report/index.d.ts

@@ -1,4 +1,4 @@
-import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
+import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.js';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。
@@ -19,23 +19,39 @@ import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
  * - `close` 关闭：用户关掉了这条物料
  */
 type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 运营配的埋点信息（`track` 动作的事件名与参数）
+ *
+ * 挂在 `stage.onShow` / `stage.onClose` 上的 `track` 属于「曝光埋点 / 关闭埋点」，
+ * **不算点击**，所以它们进的是 `exposure` / `close` 的 `extra`，而不是产出一条 `click`。
+ * 早期实现把这类埋点名一律映射成 `click`，直接把点击量放大了数倍。
+ */
+interface MarketingTrackExtra {
+    /** 运营在配置里写的埋点名 */
+    name?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
 /**
  * 点击上报的附加信息（**只在 `event='click'` 时有值**）
  *
  * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
  * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ *
+ * 一次点击里同时配了埋点和跳转（`sequence: [track, navigate]`，最常见的写法）时，
+ * 只产出**一条** click：`trigger='track'`，跳转地址并进 `url`。
  */
 interface MarketingClickExtra {
     /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
     trigger: 'track' | 'navigate';
     /** `trigger='track'` 时：运营在配置里写的埋点名 */
     name?: string;
-    /** `trigger='navigate'` 时：跳转目标地址 */
+    /** 跳转目标地址：`trigger='navigate'` 时必有；`trigger='track'` 时若同一次点击里还配了跳转也会带上 */
     url?: string;
     /** 运营在配置里写的自定义参数，原样透传 */
     params?: Record<string, unknown>;
 }
-/** 曝光上报入参：只有 id */
+/** 曝光上报入参：运营在 `stage.onShow` 里配了埋点时带上 `extra` */
 interface MarketingExposureReportParams {
     /** 物料 id，取自 `MarketingMaterial.id` */
     id: string;
@@ -43,8 +59,14 @@ interface MarketingExposureReportParams {
     event: 'exposure';
     /** 曝光事件无关闭原因 */
     reason?: never;
-    /** 曝光事件无点击附加信息 */
-    extra?: never;
+    /**
+     * 运营配在 `stage.onShow` 里的埋点名 / 参数，没配则不带。
+     *
+     * 【为什么并进曝光而不是单独上报】那条 `track` 记的就是「这条物料露出了」，
+     * 与曝光是同一件事，单独上报会与前台统一发的 exposure 重复计数；
+     * 但也不能直接丢掉 —— 运营配了就该在后端看得到。
+     */
+    extra?: MarketingTrackExtra;
 }
 /** 关闭上报入参：可带关闭原因 */
 interface MarketingCloseReportParams {
@@ -58,8 +80,8 @@ interface MarketingCloseReportParams {
      * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
      */
     reason?: string;
-    /** 关闭事件无点击附加信息 */
-    extra?: never;
+    /** 运营配在 `stage.onClose` 里的埋点名 / 参数，没配则不带 */
+    extra?: MarketingTrackExtra;
 }
 /** 点击上报入参：必须带 extra 说明点了什么 */
 interface MarketingClickReportParams {
@@ -76,7 +98,10 @@ interface MarketingClickReportParams {
  * 上报物料事件的入参（可辨识联合，按 `event` 区分）
  *
  * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
- * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 点击详情（`MarketingClickExtra`，带 `trigger`）只配 `click`，写错直接编译不过。
+ * `exposure` / `close` 的 `extra` 是另一种形态（`MarketingTrackExtra`，只有 `name` / `params`），
+ * 装的是运营配在 `stage.onShow` / `onClose` 里的埋点名 —— 它们不是点击，混不进 click 那一支。
+ * 不该出现的字段声明成 `?: never`
  * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
  * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
  */
@@ -88,39 +113,44 @@ type MarketingReportParams = MarketingExposureReportParams | MarketingCloseRepor
  * 前台坑位组件与后台调试台的「上报预览」共用这一份：
  * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
  * 前台改了口径而调试台忘了改，调试台就会骗人。
+ *
+ * 【只认 `interaction`，不认 `track` / `navigate`】
+ * 动作粒度的事件不能直接当上报口径：`sequence: [track, navigate]`（先埋点再跳转）
+ * 是最常见的写法，两个动作各报一条 → 点击量翻倍；而 `track` 还能挂在
+ * `stage.onShow` / `onClose` 上，动作粒度看不出时机 → 曝光和关闭也被算成点击。
+ * 解释器为此在**交互粒度**上多抛了一条 `interaction`（一次手势 / 一个时机一条），
+ * 上报只认它。
  */
 
 /**
  * 会产生上报的运行时事件及其载荷。
  *
- * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 字段一律可选（`Partial`）：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
  * 缺字段是允许的，不该在映射这一步炸掉。
  */
 interface MarketingReportableEventPayloads {
-    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
-    track: {
-        event?: string;
-        params?: Record<string, unknown>;
-    };
-    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
-    navigate: {
-        url?: string;
-        target?: string;
-    };
-    /** 关闭：`reason` 是关闭原因 */
-    close: {
-        reason?: string;
-    };
+    /** 一次交互的汇总事件，见 {@link DslInteractionEvent} */
+    interaction: Partial<DslInteractionEvent>;
 }
 /** 会产生上报的运行时事件名 */
 type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
 /**
  * 事件名 → 载荷类型。
  *
- * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
- * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ * 不产生上报的事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ * `view-change` / `ready` / `open`）载荷为 `unknown`：调用方照常传，映射返回 `null`。
  */
 type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 把交互事件里的埋点动作转成上报用的 `extra`（字段名 `event` → `name`）。
+ *
+ * 给宿主组装曝光 / 关闭上报用：`trigger='show'` / `'close'` 的 interaction 不产出点击，
+ * 但运营配的埋点名不能凭空消失，由宿主并进 exposure / close 的 `extra`。
+ *
+ * @param payload interaction 事件载荷
+ * @returns 埋点信息；没配埋点时返回 `undefined`
+ */
+declare function pickInteractionTrack(payload?: Partial<DslInteractionEvent> | null): MarketingTrackExtra | undefined;
 /**
  * 曝光上报载荷。
  *
@@ -128,17 +158,36 @@ type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends Market
  * 解释器根本不知道自己被画出来了。
  *
  * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @param extra 运营配在 `stage.onShow` 里的埋点信息，可用 {@link pickInteractionTrack} 从
+ *   `trigger='show'` 的 interaction 事件里取；没有则不带
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null, extra?: MarketingTrackExtra | null): MarketingExposureReportParams | null;
+/**
+ * 关闭上报载荷。
+ *
+ * 与曝光同理由：关闭由宿主统一上报一条 —— `close` 运行时事件才是「这条物料真的关了」，
+ * 运营配不配 `stage.onClose` 都得有这条。
+ *
+ * @param id 物料 id，为空时返回 `null`
+ * @param options `reason` 取自 `close` 运行时事件；`extra` 取自 `trigger='close'` 的 interaction
  * @returns 上报载荷，或 `null`
  */
-declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+declare function buildCloseReport(id: string | undefined | null, options?: {
+    reason?: string;
+    extra?: MarketingTrackExtra | null;
+}): MarketingCloseReportParams | null;
 /**
  * 把一个 DSL 运行时事件映射成上报载荷。
  *
  * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
- * - `track` → `click`，`extra = { trigger: 'track', name, params }`
- * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
- * - `close` → `close`，带 `reason`
- * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ * - `interaction` 且 `trigger='action'` → 一条 `click`，`extra` 见 {@link buildClickExtra}
+ * - `interaction` 且 `trigger='show'` / `'close'` → `null`：曝光 / 关闭由宿主统一上报，
+ *   运营配在这两个时机上的埋点名走 {@link buildExposureReport} / {@link buildCloseReport} 的 `extra`
+ * - `interaction` 且 `trigger='action'` 但 `closes` 为真（手势里执行了关闭动作）→ `null`：
+ *   点关闭按钮的本质是关闭，不再算一次点击
+ * - 其余事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ *   `view-change` / `ready` / `open`）不产生上报 —— 它们是动作粒度的事件，按它们上报会重复计数
  *
  * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
  * @param event 运行时事件名
@@ -147,4 +196,4 @@ declare function buildExposureReport(id: string | undefined | null): MarketingEx
  */
 declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
 
-export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, type MarketingTrackExtra, buildCloseReport, buildExposureReport, mapRuntimeEventToReport, pickInteractionTrack };