@xenia-martech/sdk-js 1.0.0-dev.26 → 1.0.0-dev.28

package/dist/client/react/index.js

@@ -20,6 +20,7 @@ var MESSAGE_POSITIONS = /* @__PURE__ */ new Set([
   "top",
   "bottom"
 ]);
+var WIDGET_TYPES = /* @__PURE__ */ new Set(["standard", "spin-wheel"]);
 var ALL_TYPES = /* @__PURE__ */ new Set([
   "swap",
   "hide",
@@ -66,15 +67,67 @@ function toAction(raw) {
     message: asString(raw.message),
     imageUrl: asString(raw.imageUrl),
     html: asString(raw.html),
-    cta: cta && cta.label ? cta : void 0,
+    // A link-only CTA (empty label, e.g. a spin-wheel's data-xenia-wheel-cta —
+    // label is meaningless there, the winHtml/lossHtml design supplies its own button text)
+    // must still parse through — gating on `cta.label` alone silently dropped it.
+    cta: cta && (cta.label || cta.url) ? cta : void 0,
     dismissAfterMs: asNumber(raw.dismissAfterMs),
-    position: asMessagePosition(raw.position)
+    position: asMessagePosition(raw.position),
+    widgetType: asWidgetType(raw.widgetType),
+    segments: asSegments(raw.segments),
+    formSubmit: asFormSubmit(raw.formSubmit),
+    style: asWidgetStyle(raw.style),
+    spinnerHtml: asString(raw.spinnerHtml),
+    winHtml: asString(raw.winHtml),
+    lossHtml: asString(raw.lossHtml)
   };
 }
 function asMessagePosition(v) {
   const s = asString(v);
   return s && MESSAGE_POSITIONS.has(s) ? s : void 0;
 }
+function asWidgetType(v) {
+  const s = asString(v);
+  return s && WIDGET_TYPES.has(s) ? s : void 0;
+}
+function asSegments(v) {
+  if (!Array.isArray(v)) return void 0;
+  const segments = [];
+  for (const entry of v) {
+    if (!isObject(entry)) continue;
+    const id = asString(entry.id);
+    const label = asString(entry.label);
+    if (!id || !label) continue;
+    segments.push({
+      id,
+      label,
+      colorHex: asString(entry.colorHex),
+      isLoss: entry.isLoss === true
+    });
+  }
+  return segments.length ? segments : void 0;
+}
+function asFormSubmit(v) {
+  if (!isObject(v)) return void 0;
+  const mode = asString(v.mode);
+  if (!mode) return void 0;
+  return {
+    requiresResolve: v.requiresResolve === true,
+    mode,
+    flowRef: asString(v.flowRef),
+    bindingRef: asString(v.bindingRef),
+    successDisplayMs: asNumber(v.successDisplayMs)
+  };
+}
+function asWidgetStyle(v) {
+  if (!isObject(v)) return void 0;
+  const style = {
+    hideCloseButton: v.hideCloseButton === true,
+    hideOverlay: v.hideOverlay === true
+  };
+  const hasAny = style.hideCloseButton || style.hideOverlay;
+  return hasAny ? style : void 0;
+}
 function parseActions(body) {
   let list;
   if (Array.isArray(body)) {
@@ -257,6 +310,12 @@ var TokenProvider = class {
 };
 
 // src/core/api.ts
+function isJsonObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function asWidgetPrize(v) {
+  return v !== void 0 && isJsonObject(v) ? v : void 0;
+}
 function compact(obj) {
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
@@ -326,6 +385,39 @@ var XeniaApi = class {
       receivedAt: Date.now()
     };
   }
+  /**
+   * Widget form submission — `POST /widget-submissions?ref={bindingRef}`. Used whenever the
+   * action's `formSubmit.requiresResolve` is true (spin-wheel, which must have a
+   * server-resolved outcome before anything renders) or `mode === "endpoint"` — the common
+   * plain-popup case (`mode === "journey" && !requiresResolve`) bypasses this entirely and calls
+   * {@link webhook} against `flowRef` instead (see `XeniaClient.submitWidgetForm`'s endpoint
+   * selection).
+   *
+   * Not retried (`noRetry: true`), styled like {@link webhook} — a retried POST must never
+   * double-fire a journey or double-resolve a prize server-side.
+   */
+  async submitWidget(ref, body) {
+    const { response, data: rawBody } = await this.http.request({
+      method: "POST",
+      path: "/widget-submissions",
+      query: { ref },
+      headers: await this.authHeaders(),
+      body: body ?? {},
+      noRetry: true
+    });
+    const obj = isJsonObject(rawBody) ? rawBody : {};
+    return {
+      status: response.status,
+      body: rawBody,
+      actions: parseActions(rawBody),
+      prize: asWidgetPrize(obj.prize),
+      alreadyPlayed: obj.alreadyPlayed === true,
+      dispatched: obj.dispatched === true,
+      dispatchError: typeof obj.dispatchError === "string" ? obj.dispatchError : void 0,
+      widgetType: typeof obj.widgetType === "string" ? obj.widgetType : void 0,
+      receivedAt: Date.now()
+    };
+  }
   /**
    * Unified event batch (max 100/request per the backend) — `POST /api/events/v1`.
    * Records analytics for every event and matches/advances a journey for any
@@ -971,6 +1063,40 @@ var Identity = class {
       return null;
     }
   }
+  // ── Customer id / email ──────────────────────────────────────────────────
+  //
+  // Ambient, persisted the same way as the visitor id, so a value set once
+  // (typically alongside `identify()`) rides on every later `resolve()` call
+  // without the caller having to pass it again — the SDK-provided-fields
+  // parity list on the Personalization Resolve trigger includes both.
+  setCustomerId(customerId) {
+    try {
+      if (customerId) localStorage.setItem(this.key("customer_id"), customerId);
+      else localStorage.removeItem(this.key("customer_id"));
+    } catch {
+    }
+  }
+  getCustomerId() {
+    try {
+      return localStorage.getItem(this.key("customer_id"));
+    } catch {
+      return null;
+    }
+  }
+  setEmail(email) {
+    try {
+      if (email) localStorage.setItem(this.key("email"), email);
+      else localStorage.removeItem(this.key("email"));
+    } catch {
+    }
+  }
+  getEmail() {
+    try {
+      return localStorage.getItem(this.key("email"));
+    } catch {
+      return null;
+    }
+  }
   // ── Session id ───────────────────────────────────────────────────────────────
   /**
    * Resolve the current session id: reused while activity continues within
@@ -1059,6 +1185,316 @@ function resolveCookieConfig(opt) {
   return { sameSite, secure, maxAgeDays: o.maxAgeDays ?? 365, domain: o.domain };
 }
 
+// src/client/widgets/form.ts
+function collectFields(root) {
+  const fields = {};
+  root.querySelectorAll("[data-xenia-field]").forEach((el) => {
+    const name = el.getAttribute("data-xenia-field");
+    if (!name) return;
+    fields[name] = fieldValue(el);
+  });
+  return fields;
+}
+function fieldValue(el) {
+  if (el instanceof HTMLInputElement) {
+    if (el.type === "checkbox") return el.checked ? el.value || "on" : "";
+    if (el.type === "radio") return el.checked ? el.value : "";
+    return el.value;
+  }
+  if (el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return el.value;
+  return el.textContent?.trim() ?? "";
+}
+function setDisabled(el, disabled) {
+  if (!el) return;
+  if (el instanceof HTMLButtonElement || el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement || el instanceof HTMLFieldSetElement) {
+    el.disabled = disabled;
+  } else if (disabled) {
+    el.setAttribute("aria-disabled", "true");
+  } else {
+    el.removeAttribute("aria-disabled");
+  }
+}
+function showError(root, message) {
+  const el = root.querySelector("[data-xenia-error]");
+  if (el) el.textContent = message;
+}
+var SUBMIT_STYLE_ID = "xenia-form-submit-style";
+function ensureSubmitStyles(root) {
+  if (root.querySelector(`#${SUBMIT_STYLE_ID}`)) return;
+  const style = document.createElement("style");
+  style.id = SUBMIT_STYLE_ID;
+  style.textContent = "@keyframes xenia-submit-spin{to{transform:rotate(360deg)}}[data-xenia-submitting]::after{content:'';display:inline-block;width:0.85em;height:0.85em;margin-left:0.5em;vertical-align:-0.15em;border:2px solid currentColor;border-right-color:transparent;border-radius:50%;animation:xenia-submit-spin 0.6s linear infinite}";
+  root.prepend(style);
+}
+function setSubmitting(el, submitting) {
+  if (!el) return;
+  if (submitting) el.setAttribute("data-xenia-submitting", "");
+  else el.removeAttribute("data-xenia-submitting");
+}
+function fadeOutAndDismiss(root, dismiss) {
+  if (!dismiss) return;
+  const host = root instanceof ShadowRoot ? root.host : root;
+  if (host instanceof HTMLElement) {
+    host.style.transition = "opacity 220ms ease, transform 220ms ease";
+    host.style.opacity = "0";
+    host.style.transform = "scale(0.96)";
+    window.setTimeout(dismiss, 220);
+  } else {
+    dismiss();
+  }
+}
+var DEFAULT_SUCCESS_DISPLAY_MS = 900;
+function revealSuccess(root, form) {
+  const successEl = root.querySelector("[data-xenia-success]");
+  if (!successEl) return false;
+  if (successEl instanceof HTMLElement) successEl.hidden = false;
+  else successEl.removeAttribute("hidden");
+  if (form) {
+    form.hidden = true;
+  } else {
+    root.querySelectorAll("[data-xenia-field], [data-xenia-submit]").forEach((el) => {
+      el.hidden = true;
+    });
+  }
+  return true;
+}
+function wireFormSubmit(root, action, ctx) {
+  const form = root.querySelector("form");
+  let submitting = false;
+  ensureSubmitStyles(root);
+  const run = (control, fields) => {
+    if (submitting) return;
+    if (!action.formSubmit) {
+      showError(root, "This form isn't connected yet.");
+      return;
+    }
+    submitting = true;
+    showError(root, "");
+    setDisabled(control, true);
+    setSubmitting(control, true);
+    const startedAt = Date.now();
+    const minDisplayMs = action.formSubmit.successDisplayMs ?? DEFAULT_SUCCESS_DISPLAY_MS;
+    ctx.submitWidgetForm(fields).then(() => {
+      setSubmitting(control, false);
+      revealSuccess(root, form);
+      const wait = Math.max(0, minDisplayMs - (Date.now() - startedAt));
+      window.setTimeout(() => fadeOutAndDismiss(root, ctx.dismiss), wait);
+    }).catch(() => {
+      setSubmitting(control, false);
+      setDisabled(control, false);
+      showError(root, "Something went wrong. Please try again.");
+    }).finally(() => {
+      submitting = false;
+    });
+  };
+  if (form) {
+    form.addEventListener("submit", (ev) => {
+      ev.preventDefault();
+      const formFields = {};
+      new FormData(form).forEach((value, key) => {
+        if (typeof value === "string") formFields[key] = value;
+      });
+      const submitter = ev.submitter ?? form.querySelector('[type="submit"], button:not([type])');
+      run(submitter, { ...collectFields(root), ...formFields });
+    });
+  }
+  root.querySelectorAll("[data-xenia-submit]").forEach((el) => {
+    if (form?.contains(el)) return;
+    el.addEventListener("click", () => run(el, collectFields(root)));
+  });
+}
+
+// src/client/widgets/types.ts
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+  return escapeHtml(s).replace(/"/g, "&quot;");
+}
+function wireCloseAffordances(root, dismiss) {
+  if (dismiss) {
+    const closeEls = root.querySelectorAll(
+      ".xenia-close, [data-xenia-close], [class*='close' i], [id*='close' i], [class*='backdrop' i], [id*='backdrop' i]"
+    );
+    closeEls.forEach((el) => {
+      el.removeAttribute("onclick");
+      el.addEventListener("click", dismiss);
+    });
+  }
+  root.querySelectorAll("[class*='backdrop' i], [id*='backdrop' i]").forEach((el) => {
+    if (el instanceof HTMLElement && el.children.length === 0 && !el.textContent?.trim()) {
+      el.style.opacity = "0.5";
+    }
+  });
+}
+
+// src/client/widgets/spin-wheel.ts
+var WHEEL_SIZE = 260;
+var RADIUS = WHEEL_SIZE / 2;
+var CENTER = WHEEL_SIZE / 2;
+var DEFAULT_COLORS = ["#7c3aed", "#2563eb", "#059669", "#d97706", "#dc2626", "#0891b2"];
+var SPIN_TRANSITION = "transform 3.2s cubic-bezier(0.15, 0.85, 0.25, 1)";
+var WHEEL_POINTER_HTML = '<div class="xenia-wheel-pointer" aria-hidden="true"></div>';
+var REVEAL_TRANSITION_MS = 320;
+var REVEAL_TRANSITION = `opacity ${REVEAL_TRANSITION_MS}ms ease, transform ${REVEAL_TRANSITION_MS}ms ease`;
+var REVEAL_PERSPECTIVE_PX = 900;
+var revealTransform = (scale, depthPx) => `perspective(${REVEAL_PERSPECTIVE_PX}px) translateZ(${depthPx}px) scale(${scale})`;
+function polarPoint(angleDeg, radius) {
+  const rad = angleDeg * Math.PI / 180;
+  return { x: CENTER + radius * Math.sin(rad), y: CENTER - radius * Math.cos(rad) };
+}
+function segmentPath(startAngle, endAngle) {
+  const start = polarPoint(startAngle, RADIUS);
+  const end = polarPoint(endAngle, RADIUS);
+  const largeArc = endAngle - startAngle > 180 ? 1 : 0;
+  return `M ${CENTER},${CENTER} L ${start.x},${start.y} A ${RADIUS},${RADIUS} 0 ${largeArc} 1 ${end.x},${end.y} Z`;
+}
+function computeSpinRotation(segmentIndex, segmentCount, extraSpins = 0) {
+  if (segmentCount <= 0) return 0;
+  const segmentAngle = 360 / segmentCount;
+  const centerAngle = segmentIndex * segmentAngle + segmentAngle / 2;
+  const landingAngle = (360 - centerAngle) % 360;
+  return extraSpins * 360 + landingAngle;
+}
+function crossFadeReveal(outgoing, incoming) {
+  const outContent = outgoing ? Array.from(outgoing.children) : [];
+  const inContent = incoming ? Array.from(incoming.children) : [];
+  if (incoming) incoming.hidden = false;
+  inContent.forEach((el) => {
+    if (!(el instanceof HTMLElement)) return;
+    el.style.transition = "none";
+    el.style.opacity = "0";
+    el.style.transform = revealTransform(0.94, -60);
+  });
+  nextFrame(() => {
+    outContent.forEach((el) => {
+      if (!(el instanceof HTMLElement)) return;
+      el.style.transition = REVEAL_TRANSITION;
+      el.style.opacity = "0";
+      el.style.transform = revealTransform(0.94, -60);
+    });
+    inContent.forEach((el) => {
+      if (!(el instanceof HTMLElement)) return;
+      el.style.transition = REVEAL_TRANSITION;
+      el.style.opacity = "1";
+      el.style.transform = revealTransform(1, 0);
+    });
+  });
+  if (outgoing) {
+    setTimeout(() => {
+      outgoing.hidden = true;
+    }, REVEAL_TRANSITION_MS);
+  }
+}
+function nextFrame(fn) {
+  if (typeof requestAnimationFrame === "function") requestAnimationFrame(fn);
+  else setTimeout(fn, 0);
+}
+function wheelSvg(segments) {
+  const n = segments.length || 1;
+  const segmentAngle = 360 / n;
+  const slices = segments.map((seg, i) => {
+    const start = i * segmentAngle;
+    const end = start + segmentAngle;
+    const color = seg.colorHex || DEFAULT_COLORS[i % DEFAULT_COLORS.length];
+    const labelAngle = start + segmentAngle / 2;
+    const labelPoint = polarPoint(labelAngle, RADIUS * 0.62);
+    return `<path d="${segmentPath(start, end)}" fill="${escapeAttr(color)}" stroke="#fff" stroke-width="1"></path><text x="${labelPoint.x}" y="${labelPoint.y}" fill="#fff" font-size="12" text-anchor="middle" transform="rotate(${labelAngle} ${labelPoint.x} ${labelPoint.y})">${escapeHtml(seg.label)}</text>`;
+  }).join("");
+  return `<svg class="xenia-wheel-svg" viewBox="0 0 ${WHEEL_SIZE} ${WHEEL_SIZE}" width="${WHEEL_SIZE}" height="${WHEEL_SIZE}"><g class="xenia-wheel-dial">${slices}</g><circle class="xenia-wheel-hub" cx="${CENTER}" cy="${CENTER}" r="6"></circle></svg>`;
+}
+var spinWheelRenderer = {
+  html(action) {
+    return `<div class="xenia-spin-wheel"><div data-xenia-wheel-face>${action.spinnerHtml ?? ""}</div><div class="xenia-widget-result" data-xenia-wheel-result hidden>${action.winHtml ?? ""}</div><div class="xenia-widget-result" data-xenia-wheel-loss hidden>${action.lossHtml ?? ""}</div></div>`;
+  },
+  wire(root, action, ctx) {
+    wireCloseAffordances(root, ctx.dismiss);
+    const segments = action.segments ?? [];
+    const wheelFace = root.querySelector("[data-xenia-wheel-face]");
+    const spinBtn = root.querySelector("[data-xenia-spin]");
+    const winEl = root.querySelector("[data-xenia-wheel-result]");
+    const lossEl = root.querySelector("[data-xenia-wheel-loss]");
+    const errorEl = root.querySelector("[data-xenia-error]");
+    const slotEl = root.querySelector("[data-xenia-wheel-slot]");
+    if (slotEl) slotEl.insertAdjacentHTML("afterbegin", wheelSvg(segments) + WHEEL_POINTER_HTML);
+    const dial = root.querySelector(".xenia-wheel-dial");
+    if (!spinBtn || !action.formSubmit) return;
+    root.querySelectorAll("[data-xenia-wheel-cta]").forEach((btn) => {
+      btn.addEventListener("click", () => ctx.fireCta());
+    });
+    const revealResult = (prizeLabel, isLoss, canRetry) => {
+      root.querySelectorAll("[data-xenia-wheel-prize]").forEach((el) => {
+        el.textContent = prizeLabel;
+      });
+      const shown = isLoss ? lossEl : winEl;
+      const other = isLoss ? winEl : lossEl;
+      if (other) other.hidden = true;
+      crossFadeReveal(wheelFace, shown);
+      if (!canRetry) {
+        playsExhausted = true;
+        root.querySelectorAll("[data-xenia-spin-again]").forEach((btn) => {
+          btn.hidden = true;
+        });
+      }
+    };
+    let spinning = false;
+    let playsExhausted = false;
+    root.querySelectorAll("[data-xenia-spin-again]").forEach((btn) => {
+      btn.addEventListener("click", () => {
+        if (playsExhausted) return;
+        const shown = winEl && !winEl.hidden ? winEl : lossEl && !lossEl.hidden ? lossEl : null;
+        if (!shown) return;
+        spinning = false;
+        spinBtn.disabled = false;
+        if (errorEl) errorEl.textContent = "";
+        crossFadeReveal(shown, wheelFace);
+      });
+    });
+    spinBtn.addEventListener("click", () => {
+      if (spinning) return;
+      spinning = true;
+      spinBtn.disabled = true;
+      if (errorEl) errorEl.textContent = "";
+      const fields = collectFields(root);
+      ctx.submitWidgetForm(fields).then((response) => {
+        const index = segments.findIndex((s) => s.id === response.prize?.segmentId);
+        const prizeLabel = response.prize?.label ?? segments[index]?.label ?? "";
+        const isLoss = index >= 0 && !!segments[index]?.isLoss;
+        const canRetry = response.alreadyPlayed !== true;
+        if (index < 0 || !dial) {
+          revealResult(prizeLabel, isLoss, canRetry);
+          return;
+        }
+        const extraSpins = 3 + Math.floor(Math.random() * 3);
+        const rotation = computeSpinRotation(index, segments.length || 1, extraSpins);
+        const priorMatch = /rotate\(([-\d.]+)deg\)/.exec(dial.style.transform);
+        const priorRotation = priorMatch ? parseFloat(priorMatch[1]) : 0;
+        dial.style.transition = "none";
+        dial.style.transform = `rotate(${priorRotation % 360}deg)`;
+        void dial.getBoundingClientRect();
+        dial.style.transition = SPIN_TRANSITION;
+        const onTransitionEnd = () => {
+          dial.removeEventListener("transitionend", onTransitionEnd);
+          revealResult(prizeLabel, isLoss, canRetry);
+        };
+        dial.addEventListener("transitionend", onTransitionEnd);
+        nextFrame(() => {
+          dial.style.transform = `rotate(${rotation}deg)`;
+        });
+      }).catch(() => {
+        spinning = false;
+        spinBtn.disabled = false;
+        if (errorEl) errorEl.textContent = "Something went wrong. Please try again.";
+      });
+    });
+  }
+};
+
+// src/client/widgets/index.ts
+var WIDGET_RENDERERS = {
+  "spin-wheel": spinWheelRenderer
+};
+
 // src/client/renderer.ts
 function resolveTarget(target, root = document) {
   if (!target) return null;
@@ -1116,6 +1552,7 @@ var ActionRenderer = class {
   messageTemplate;
   messageStyles;
   messageComponent;
+  submitWidgetFormFn;
   /** Unmount callbacks for currently-mounted framework components, keyed by their container. */
   mounted = /* @__PURE__ */ new Map();
   constructor(onCta, opts) {
@@ -1123,6 +1560,7 @@ var ActionRenderer = class {
     this.messageTemplate = opts?.messageTemplate;
     this.messageStyles = opts?.messageStyles;
     this.messageComponent = opts?.messageComponent;
+    this.submitWidgetFormFn = opts?.submitWidgetForm;
   }
   /** Apply a list of actions. Returns the count successfully applied. */
   apply(actions) {
@@ -1205,7 +1643,8 @@ ${this.messageStyles}` : STYLES;
     const wrap = document.createElement("div");
     const posClass = this.positionClass(action.type, action.position);
     const customBgClass = action.html !== void 0 ? " xenia-custom-bg" : "";
-    wrap.className = `xenia-msg xenia-${action.type}${posClass ? ` ${posClass}` : ""}${customBgClass}`;
+    const noOverlayClass = action.style?.hideOverlay ? " xenia-no-overlay" : "";
+    wrap.className = `xenia-msg xenia-${action.type}${posClass ? ` ${posClass}` : ""}${customBgClass}${noOverlayClass}`;
     shadow.appendChild(wrap);
     const dismiss = () => {
       this.unmount(wrap);
@@ -1218,7 +1657,10 @@ ${this.messageStyles}` : STYLES;
       this.wireCard(wrap, action, dismiss);
     }
     if (action.dismissAfterMs && action.dismissAfterMs > 0) {
-      setTimeout(dismiss, action.dismissAfterMs);
+      const timer = setTimeout(dismiss, action.dismissAfterMs);
+      const cancelAutoDismiss = () => clearTimeout(timer);
+      wrap.addEventListener("click", cancelAutoDismiss, { once: true });
+      wrap.addEventListener("focusin", cancelAutoDismiss, { once: true });
     }
     return true;
   }
@@ -1262,38 +1704,32 @@ ${this.messageStyles}` : STYLES;
     return "";
   }
   cardHtml(action, variant) {
+    const widget = action.widgetType ? WIDGET_RENDERERS[action.widgetType] : void 0;
+    if (widget) return widget.html(action, variant);
     if (action.html !== void 0) return wrapCustomHtml(action.html, variant);
     if (this.messageTemplate) {
       const ctx = {
         action,
         variant,
-        escapeHtml,
-        escapeAttr
+        escapeHtml: escapeHtml2,
+        escapeAttr: escapeAttr2
       };
       return this.messageTemplate(ctx);
     }
-    const img = action.imageUrl ? `<img class="xenia-img" src="${escapeAttr(action.imageUrl)}" alt="" />` : "";
-    const title = action.title ? `<div class="xenia-title">${escapeHtml(action.title)}</div>` : "";
-    const msg = action.message ? `<div class="xenia-body">${escapeHtml(action.message)}</div>` : "";
-    const cta = action.cta ? `<button class="xenia-cta" type="button">${escapeHtml(action.cta.label)}</button>` : "";
+    const img = action.imageUrl ? `<img class="xenia-img" src="${escapeAttr2(action.imageUrl)}" alt="" />` : "";
+    const title = action.title ? `<div class="xenia-title">${escapeHtml2(action.title)}</div>` : "";
+    const msg = action.message ? `<div class="xenia-body">${escapeHtml2(action.message)}</div>` : "";
+    const cta = action.cta ? `<button class="xenia-cta" type="button">${escapeHtml2(action.cta.label)}</button>` : "";
     const close = variant === "inline" ? "" : `<button class="xenia-close" type="button" aria-label="Close">\xD7</button>`;
     return `<div class="xenia-card">${close}${img}<div class="xenia-content">${title}${msg}${cta}</div></div>`;
   }
   wireCard(root, action, dismiss) {
-    if (dismiss) {
-      const closeEls = root.querySelectorAll(
-        ".xenia-close, [data-xenia-close], [class*='close' i], [id*='close' i], [class*='backdrop' i], [id*='backdrop' i]"
-      );
-      closeEls.forEach((el) => {
-        el.removeAttribute("onclick");
-        el.addEventListener("click", dismiss);
-      });
+    const widget = action.widgetType ? WIDGET_RENDERERS[action.widgetType] : void 0;
+    if (widget) {
+      widget.wire(root, action, this.buildWidgetCtx(action, dismiss));
+      return;
     }
-    root.querySelectorAll("[class*='backdrop' i], [id*='backdrop' i]").forEach((el) => {
-      if (el instanceof HTMLElement && el.children.length === 0 && !el.textContent?.trim()) {
-        el.style.opacity = "0.5";
-      }
-    });
+    wireCloseAffordances(root, dismiss);
     const ctaBtn = root.querySelector(".xenia-cta, [data-xenia-cta]");
     if (ctaBtn && action.cta) {
       ctaBtn.addEventListener("click", () => {
@@ -1302,6 +1738,29 @@ ${this.messageStyles}` : STYLES;
         dismiss?.();
       });
     }
+    wireFormSubmit(root, action, this.buildWidgetCtx(action, dismiss));
+  }
+  /** Build the imperative hooks (`dismiss`/`fireCta`/`submitWidgetForm`) handed to a widget's `wire()`. */
+  buildWidgetCtx(action, dismiss) {
+    const idempotencyKey = generateUlid();
+    return {
+      dismiss,
+      fireCta: () => {
+        if (action.cta?.event) this.onCta?.(action.cta.event, action.cta);
+        if (action.cta?.url) window.location.assign(action.cta.url);
+        dismiss?.();
+      },
+      submitWidgetForm: (fields) => {
+        if (!action.formSubmit || !this.submitWidgetFormFn) {
+          return Promise.reject(
+            new Error(
+              "xenia: this action has no formSubmit config, or no submitWidgetForm handler is wired (construct the ActionRenderer via XeniaClient to get one)"
+            )
+          );
+        }
+        return this.submitWidgetFormFn(action.formSubmit, fields, { idempotencyKey });
+      }
+    };
   }
 };
 function wrapCustomHtml(html, variant) {
@@ -1310,11 +1769,11 @@ function wrapCustomHtml(html, variant) {
   }
   return `<div class="xenia-custom-html"><style>.xenia-custom-html{position:relative}.xenia-custom-html>*{position:static!important;inset:auto!important;top:auto!important;right:auto!important;bottom:auto!important;left:auto!important}</style>${html}</div>`;
 }
-function escapeHtml(s) {
+function escapeHtml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function escapeAttr(s) {
-  return escapeHtml(s).replace(/"/g, "&quot;");
+function escapeAttr2(s) {
+  return escapeHtml2(s).replace(/"/g, "&quot;");
 }
 var STYLES = `
 :host { all: initial; }
@@ -1331,12 +1790,14 @@ var STYLES = `
 .xenia-modal { inset: 0; display: flex; align-items: center; justify-content: center;
   background: var(--xenia-modal-backdrop, rgba(0,0,0,.12)); }
 .xenia-modal.xenia-custom-bg { background: transparent; }
+.xenia-modal.xenia-no-overlay { background: transparent; }
 .xenia-card { position: relative; background: var(--xenia-card-bg, #fff); color: var(--xenia-card-color, #111);
   border-radius: var(--xenia-card-radius, 12px); box-shadow: var(--xenia-card-shadow, 0 10px 40px rgba(0,0,0,.18));
   padding: var(--xenia-card-padding, 16px 18px); display: flex; gap: var(--xenia-card-gap, 12px);
   align-items: center; }
 .xenia-banner .xenia-card { border-radius: var(--xenia-banner-card-radius, 0); justify-content: center; }
 .xenia-modal .xenia-card { max-width: var(--xenia-modal-max-width, 440px); width: calc(100% - 32px); }
+.xenia-card.xenia-widget { flex-direction: column; align-items: center; text-align: center; }
 .xenia-img { width: var(--xenia-img-size, 56px); height: var(--xenia-img-size, 56px); object-fit: cover;
   border-radius: var(--xenia-img-radius, 8px); }
 .xenia-title { font-weight: var(--xenia-title-weight, 600); font-size: var(--xenia-title-size, 15px);
@@ -1348,6 +1809,38 @@ var STYLES = `
   font-size: var(--xenia-cta-size, 14px); cursor: pointer; }
 .xenia-close { position: absolute; top: 6px; right: 8px; background: none; border: 0;
   font-size: var(--xenia-close-size, 20px); line-height: 1; cursor: pointer; color: var(--xenia-close-color, #999); }
+.xenia-wheel-dial { transform-box: fill-box; transform-origin: center; }
+.xenia-wheel-hub { fill: var(--xenia-wheel-pointer-color, #111); }
+.xenia-wheel-wrap { position: relative; display: inline-block; }
+.xenia-wheel-pointer { position: absolute; top: -6px; left: 50%; transform: translateX(-50%);
+  width: 0; height: 0; border-left: 9px solid transparent; border-right: 9px solid transparent;
+  border-top: 14px solid var(--xenia-wheel-pointer-color, #111); pointer-events: none; }
+.xenia-wheel-spin { margin-top: 10px; background: var(--xenia-cta-bg, #111); color: var(--xenia-cta-color, #fff);
+  border: 0; border-radius: var(--xenia-cta-radius, 8px); padding: var(--xenia-cta-padding, 8px 14px);
+  font-size: var(--xenia-cta-size, 14px); font-family: inherit; cursor: pointer; }
+.xenia-wheel-spin:disabled { opacity: 0.6; cursor: default; }
+/* No animation/transform here \u2014 spin-wheel's win/loss screens are ALWAYS full
+   custom HTML now (winHtml/lossHtml), never this class's own generated icon/title/prize/cta
+   content (those sub-classes below are unreachable dead CSS, kept only for backwards-compat with
+   any already-saved artifact that might still reference them). A transform on THIS wrapper
+   would make it the CSS containing block for any fixed/absolute-positioned descendant the
+   author's own HTML uses (a real, common case \u2014 a "full-screen overlay" win/loss design) \u2014 the
+   fixed child would then size/position itself relative to this wrapper's own small, in-flow,
+   often off-center box instead of the true browser viewport, visibly popping in from/toward
+   whatever corner the wrapper happens to sit at instead of scaling from the real screen center.
+   spin-wheel.ts's crossFadeReveal owns the actual reveal transition (applied to the author's own
+   top-level element, never this wrapper) \u2014 this class stays a bare, transform-free layout box. */
+.xenia-widget-result { display: flex; flex-direction: column; align-items: center; gap: 4px;
+  padding: 8px 4px 2px; text-align: center; }
+.xenia-widget-result[hidden] { display: none; }
+.xenia-widget-result-icon { font-size: 40px; line-height: 1; }
+.xenia-widget-result-title { font-weight: var(--xenia-title-weight, 700); font-size: var(--xenia-title-size, 17px); }
+.xenia-widget-result-prize { font-weight: 600; font-size: 15px; color: var(--xenia-cta-bg, #111);
+  background: var(--xenia-result-prize-bg, rgba(0,0,0,.06)); border-radius: var(--xenia-cta-radius, 8px);
+  padding: 6px 14px; }
+.xenia-widget-result-cta { margin-top: 8px; background: var(--xenia-cta-bg, #111); color: var(--xenia-cta-color, #fff);
+  border: 0; border-radius: var(--xenia-cta-radius, 8px); padding: var(--xenia-cta-padding, 8px 14px);
+  font-size: var(--xenia-cta-size, 14px); font-family: inherit; cursor: pointer; }
 `;
 
 // src/client/xenia-client.ts
@@ -1372,7 +1865,8 @@ var XeniaClient = class {
     this.renderer = new ActionRenderer((event, cta) => this.onCtaEvent(event, cta), {
       messageTemplate: options.messageTemplate,
       messageStyles: options.messageStyles,
-      messageComponent: options.messageComponent
+      messageComponent: options.messageComponent,
+      submitWidgetForm: (submit, fields, subOpts) => this.submitWidgetForm(submit, fields, subOpts)
     });
     this.consentState = { ...options.consent };
     this.analyticsQueue = new AnalyticsQueue({
@@ -1434,10 +1928,16 @@ var XeniaClient = class {
    * Persist a visitor id, attached to every subsequent event, and bind it to
    * a known user server-side (`POST /api/events/v1/identify`, fire-and-
    * forget — resolves to an `"identify"` client event carrying `personId`).
+   *
+   * `extra.customerId`/`extra.email`, when supplied, are also persisted
+   * ambiently (like the visitor id) so they ride on every later `resolve()`
+   * call automatically — part of the SDK-provided-fields parity list.
    */
-  identify(visitorId) {
+  identify(visitorId, extra) {
     this.identity.identify(visitorId);
-    void this.api.identify({ xeniaVisitorId: visitorId }).then((res) => this.emit("identify", res)).catch((err) => this.emitError(err));
+    if (extra?.customerId !== void 0) this.identity.setCustomerId(extra.customerId);
+    if (extra?.email !== void 0) this.identity.setEmail(extra.email);
+    void this.api.identify({ xeniaVisitorId: visitorId, userId: extra?.customerId, email: extra?.email }).then((res) => this.emit("identify", res)).catch((err) => this.emitError(err));
   }
   /** Override the customer-journey UUID (else derived from utm_id). */
   setJourneyId(id) {
@@ -1555,15 +2055,40 @@ var XeniaClient = class {
     return this.identity.getVisitorId() ?? this.identity.getDeviceId() ?? void 0;
   }
   /**
-   * Stamp the SDK-owned visitor id into the resolve `data` under the reserved
-   * `_xenia_vid` key so the backend can bucket holdout experiments and record
-   * exposure per visitor (it reads visitor identity from `data`). Set last so a
-   * caller can't override it; a no-op when no visitor id is resolvable yet.
+   * Stamp the full set of SDK-provided fields into the resolve `data` —
+   * `path`, `query`, `deviceId`, `visitorId`, `customerId`, `email`, `url`,
+   * `referrer`, and the five `utm*` fields — the same field-name/type parity
+   * the webhook trigger's "SDK-provided fields" already promises, now native
+   * (always attached, no marketer toggle) for the Personalization Resolve
+   * trigger too. Plus the reserved `_xenia_vid` key the backend reads for
+   * holdout/exposure bucketing. All of these are spread LAST (after the
+   * caller's own `data`) so none can be overridden per call — the same
+   * override-protection guarantee `_xenia_vid` alone used to have, now
+   * widened to the full set. A no-op (returns `opts` unchanged) when nothing
+   * is resolvable yet (e.g. called before `init()` on a fresh visit with no
+   * page context available).
    */
   withVisitor(opts) {
+    const ctx = this.identity.collectContext();
     const vid = this.resolveVisitorId();
-    if (!vid) return opts;
-    return { ...opts, data: { ...opts?.data ?? {}, _xenia_vid: vid } };
+    const sdkFields = compact({
+      path: ctx.path,
+      query: ctx.query,
+      deviceId: this.identity.getDeviceId() ?? void 0,
+      visitorId: vid,
+      customerId: this.identity.getCustomerId() ?? void 0,
+      email: this.identity.getEmail() ?? void 0,
+      url: ctx.url,
+      referrer: ctx.referrer,
+      utmSource: ctx.utmSource,
+      utmMedium: ctx.utmMedium,
+      utmCampaign: ctx.utmCampaign,
+      utmContent: ctx.utmContent,
+      utmId: ctx.utmId
+    });
+    if (vid) sdkFields._xenia_vid = vid;
+    if (Object.keys(sdkFields).length === 0) return opts;
+    return { ...opts, data: { ...opts?.data ?? {}, ...sdkFields } };
   }
   dntBlocked() {
     if (this.options.respectDnt === false) return false;
@@ -1613,6 +2138,55 @@ var XeniaClient = class {
   getResponse(key) {
     return this.responses.get(key);
   }
+  /**
+   * Submit a widget's captured form values (standard/custom popup submit, or a spin-wheel/
+   * spin-wheel's resolve request) and apply any returned `xeniaActions`, exactly like
+   * {@link request}.
+   *
+   * **Endpoint selection is config-driven, not SDK-decided** (per the cross-repo contract): a
+   * `flowRef` (present only when `mode === "journey" && !requiresResolve` — the common
+   * plain-popup case) bypasses the resolve endpoint entirely and POSTs straight to the existing
+   * public `/flow` fast path; otherwise this POSTs to `/widget-submissions` via `bindingRef`. The
+   * SDK is agnostic to *why* — it just follows whichever ref field the backend populated.
+   *
+   * The full ambient-context parity list {@link request}/`withVisitor()` already build
+   * (visitorId, deviceId, url, referrer, path, query, `utm*`) rides on every call, plus `fields`
+   * and `submit.mode`/the resolved ref, relayed verbatim/uninterpreted — the SDK never branches
+   * on `mode`'s value itself, that's server-side.
+   *
+   * `opts.idempotencyKey` defaults to a freshly generated ULID; pass the SAME key back in on a
+   * retried submit of the same interaction so a network retry can't double-fire a journey or
+   * double-resolve a prize server-side.
+   */
+  async submitWidgetForm(submit, fields, opts) {
+    const ctx = this.identity.collectContext();
+    const idempotencyKey = opts?.idempotencyKey ?? generateUlid();
+    const ref = submit.flowRef ?? submit.bindingRef;
+    const ambient = {
+      visitorId: this.resolveVisitorId(),
+      deviceId: this.identity.getDeviceId() ?? void 0,
+      idempotencyKey,
+      mode: submit.mode,
+      ref,
+      url: ctx.url,
+      referrer: ctx.referrer,
+      path: ctx.path,
+      query: ctx.query,
+      utmSource: ctx.utmSource,
+      utmMedium: ctx.utmMedium,
+      utmCampaign: ctx.utmCampaign,
+      utmContent: ctx.utmContent,
+      utmId: ctx.utmId
+    };
+    const response = submit.flowRef ? await this.api.webhook(submit.flowRef, compact({ ...ambient, ...fields }), "POST") : await this.api.submitWidget(
+      submit.bindingRef ?? "",
+      compact({ ...ambient, fields })
+    );
+    this.emit("response", { triggerId: ref, response });
+    const apply = opts?.apply ?? this.options.autoApplyActions !== false;
+    if (apply && response.actions.length) this.applyActions(response.actions);
+    return response;
+  }
   // ── Imperative render helpers ─────────────────────────────────────────────────
   swapContent(target, content) {
     return swapContent(target, content);