@pushwoosh/websdk-common 0.0.0 → 6.17.0

package/web-popups/helpers.js

@@ -0,0 +1,687 @@
+import { SAFE_URL_PROTOCOL, WEB_POPUP_CHOICE_DEFAULTS, WEB_POPUP_DEFAULT_COLORS, WEB_POPUP_FORM_DEFAULTS, WEB_POPUP_MAX_CHOICE_OPTIONS, WEB_POPUP_RATING_DEFAULTS, WEB_POPUP_VERSION } from './constants';
+import { WEB_POPUP_GLYPH_NAMES, WEB_POPUP_GLYPH_SIZES } from './glyphs';
+import { normalizeWebPopupLayout, substituteWebPopupLayoutValues, WEB_POPUP_VALUE_KEY_PATTERN } from './layout';
+import { autoDarkWebPopupColors } from './palette';
+import { webPopupTimeZoneSupported, webPopupWallClockMs } from './timer';
+// Sanitize a user-entered button URL before it lands in an href: https/http/
+// mailto/tel and page-relative links only.
+export function safeUrl(url) {
+  const trimmed = (url || '').trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith('#') || trimmed.startsWith('/') || trimmed.startsWith('?')) return trimmed;
+  if (SAFE_URL_PROTOCOL.test(trimmed)) return trimmed;
+  return undefined;
+}
+/**
+ * The target/rel pair a popup link renders with: only an exact '_self' opts
+ * out of the default new tab (and of its noreferrer, which same-tab
+ * navigation doesn't need). One rule for both link kinds — the reader's
+ * button anchors and the sanitizer's inline text links.
+ */
+export function webPopupLinkTargetAttrs(target) {
+  return target === '_self' ? {
+    target: '_self'
+  } : {
+    target: '_blank',
+    rel: 'noreferrer'
+  };
+}
+const SANITIZE_ALLOWED_TAGS = new Set(['STRONG', 'B', 'EM', 'I', 'U', 'BR', 'A']);
+function copySanitized(from, to, doc) {
+  for (const child of Array.from(from.childNodes)) {
+    if (child.nodeType === 3 /* text */) {
+      to.appendChild(doc.createTextNode(child.textContent ?? ''));
+      continue;
+    }
+    if (child.nodeType !== 1 /* element */) continue;
+    const el = child;
+    // Unknown tags are unwrapped — their children survive as plain content.
+    if (!SANITIZE_ALLOWED_TAGS.has(el.tagName)) {
+      copySanitized(el, to, doc);
+      continue;
+    }
+    const clean = doc.createElement(el.tagName.toLowerCase());
+    if (el.tagName === 'A') {
+      const href = safeUrl(el.getAttribute('href') ?? undefined);
+      if (href) clean.setAttribute('href', href);
+      const {
+        target,
+        rel
+      } = webPopupLinkTargetAttrs(el.getAttribute('target'));
+      clean.setAttribute('target', target);
+      if (rel) clean.setAttribute('rel', rel);
+    }
+    to.appendChild(clean);
+    copySanitized(el, clean, doc);
+  }
+}
+/**
+ * Sanitize a text slot's html before it's injected into the page. The editor
+ * only ever writes inline formatting, but the json travels through a public
+ * API and renders on customers' sites — so on render only the inline tags
+ * survive (anything else is unwrapped to its text), every attribute is
+ * dropped, and links keep only a safeUrl-approved href plus their tab choice
+ * (target="_self" stays; everything else opens in a new tab).
+ */
+export function sanitizeWebPopupHtml(html) {
+  // No '<' → no elements can form; entities in plain text are already-valid
+  // html and pass through untouched.
+  if (!html.includes('<')) return html;
+  const parsed = new DOMParser().parseFromString(html, 'text/html');
+  const out = parsed.createElement('div');
+  copySanitized(parsed.body, out, parsed);
+  return out.innerHTML;
+}
+function colorString(value) {
+  return typeof value === 'string' && value ? value : undefined;
+}
+/**
+ * The popup palette from API-writable params: `colors` entries when present,
+ * the legacy top-level background/accent underneath, palette defaults for the
+ * rest — always a complete WebPopupColors.
+ */
+export function normalizeWebPopupColors(params) {
+  const colors = typeof params.colors === 'object' && params.colors !== null ? params.colors : {};
+  return {
+    background: colorString(colors.background) ?? colorString(params.background) ?? WEB_POPUP_DEFAULT_COLORS.background,
+    accent: colorString(colors.accent) ?? colorString(params.accent) ?? WEB_POPUP_DEFAULT_COLORS.accent,
+    text: colorString(colors.text) ?? WEB_POPUP_DEFAULT_COLORS.text,
+    textSecondary: colorString(colors.textSecondary) ?? WEB_POPUP_DEFAULT_COLORS.textSecondary,
+    textInverse: colorString(colors.textInverse) ?? WEB_POPUP_DEFAULT_COLORS.textInverse
+  };
+}
+// A page dim from API-writable json: both fields or nothing, opacity clamped.
+function normalizeOverlay(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const overlay = raw;
+  const color = colorString(overlay.color);
+  if (!color) return undefined;
+  const opacity = typeof overlay.opacity === 'number' && Number.isFinite(overlay.opacity) ? Math.max(0, Math.min(1, overlay.opacity)) : 1;
+  return {
+    color,
+    opacity
+  };
+}
+// Authored dark entries over the ones autogenerated from the light palette.
+// Absent `dark` = no dark mode; an authored palette switched off is not that.
+export function normalizeWebPopupDark(params, light) {
+  const raw = params.dark;
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const dark = raw;
+  const authored = typeof dark.colors === 'object' && dark.colors !== null ? dark.colors : {};
+  const auto = autoDarkWebPopupColors(light);
+  const overlay = normalizeOverlay(dark.overlay);
+  return {
+    enabled: dark.enabled === true,
+    colors: {
+      background: colorString(authored.background) ?? auto.background,
+      accent: colorString(authored.accent) ?? auto.accent,
+      text: colorString(authored.text) ?? auto.text,
+      textSecondary: colorString(authored.textSecondary) ?? auto.textSecondary,
+      textInverse: colorString(authored.textInverse) ?? auto.textInverse
+    },
+    ...(overlay ? {
+      overlay
+    } : {}),
+    ...(colorString(dark.boxShadow) ? {
+      boxShadow: dark.boxShadow
+    } : {})
+  };
+}
+// Parse stored PopupFormContent.json into the popup model. Returns null for
+// anything that isn't a version-2 popup with at least one page — including
+// the retired version-1 flat-layout format and pre-engine content with no
+// `version` field at all, which callers should treat as broken. The palette
+// comes out complete: colors entries → legacy top-level background/accent →
+// defaults.
+export function parseWebPopupJson(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== 'object' || raw === null) return null;
+  const candidate = raw;
+  if (candidate.version !== WEB_POPUP_VERSION) return null;
+  const params = candidate.params;
+  if (typeof params !== 'object' || params === null) return null;
+  if (!Array.isArray(params.pages) || params.pages.length === 0) return null;
+  const colors = normalizeWebPopupColors(params);
+  const dark = normalizeWebPopupDark(params, colors);
+  return {
+    version: WEB_POPUP_VERSION,
+    params: {
+      ...params,
+      colors,
+      ...(dark ? {
+        dark
+      } : {})
+    }
+  };
+}
+/** The editor's save path: model → PopupFormContent.json string. */
+export function stringifyWebPopup(params) {
+  const compat = {
+    ...params,
+    background: params.colors.background,
+    accent: params.colors.accent
+  };
+  const payload = {
+    version: WEB_POPUP_VERSION,
+    params: compat
+  };
+  return JSON.stringify(payload);
+}
+const IMAGE_FITS = ['cover', 'contain'];
+const MAX_IMAGE_BLUR = 100;
+// Bomb protection for the page content, mirroring the layout tree's
+// depth/node caps: the tree allows up to ~100 Content nodes and several may
+// reference the same zone, so unbounded zones/slots would amplify into
+// thousands of sanitize+render passes on the customer's page.
+const MAX_IMAGES = 20;
+const MAX_ZONES = 20;
+const MAX_ZONE_SLOTS = 50;
+// A media param's video, or undefined when it has none / an unusable url —
+// then the param stays a plain image and the poster is all that renders.
+function normalizeVideo(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const video = raw;
+  const src = safeUrl(typeof video.src === 'string' ? video.src : undefined);
+  if (!src) return undefined;
+  return {
+    src,
+    ...(video.controls === true ? {
+      controls: true
+    } : {}),
+    ...(video.loop === false ? {
+      loop: false
+    } : {})
+  };
+}
+// The images come from API-writable json — keep only well-formed entries,
+// with the presentation props (fit/blur) validated like the layout tree's.
+function normalizeImages(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const img of raw) {
+    if (out.length >= MAX_IMAGES) break;
+    if (typeof img !== 'object' || img === null) continue;
+    if (typeof img.key !== 'string' || !img.key) continue;
+    if (typeof img.src !== 'string') continue;
+    const video = normalizeVideo(img.video);
+    out.push({
+      key: img.key,
+      label: typeof img.label === 'string' ? img.label : '',
+      src: img.src,
+      ...(typeof img.srcDark === 'string' && img.srcDark ? {
+        srcDark: img.srcDark
+      } : {}),
+      ...(video ? {
+        video
+      } : {}),
+      ...(typeof img.mediaId === 'string' && img.mediaId ? {
+        mediaId: img.mediaId
+      } : {}),
+      ...(typeof img.mediaIdDark === 'string' && img.mediaIdDark ? {
+        mediaIdDark: img.mediaIdDark
+      } : {}),
+      ...(IMAGE_FITS.includes(img.fit) ? {
+        fit: img.fit
+      } : {}),
+      ...(typeof img.blur === 'number' && Number.isFinite(img.blur) && img.blur > 0 ? {
+        blur: Math.min(img.blur, MAX_IMAGE_BLUR)
+      } : {}),
+      ...(typeof img.dim === 'number' && Number.isFinite(img.dim) && img.dim > 0 ? {
+        dim: Math.min(img.dim, 1)
+      } : {})
+    });
+  }
+  return out;
+}
+const MAX_VALUES = 20;
+const MAX_VALUE_LENGTH = 64;
+const MAX_SELECT_OPTIONS = 20;
+const LENGTH_CONTROL_UNITS = ['px', '%', 'em', 'rem', 'fr'];
+function finiteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+// Per-unit { min?, max? } overrides for a length control, keyed by a
+// whitelisted unit. Non-object input, unknown unit keys and non-finite bounds
+// are dropped; an all-empty map returns undefined so the field is omitted.
+function normalizeControlRanges(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const out = {};
+  for (const unit of LENGTH_CONTROL_UNITS) {
+    const entry = raw[unit];
+    if (typeof entry !== 'object' || entry === null) continue;
+    const min = finiteNumber(entry.min);
+    const max = finiteNumber(entry.max);
+    if (min === undefined && max === undefined) continue;
+    out[unit] = {
+      ...(min !== undefined ? {
+        min
+      } : {}),
+      ...(max !== undefined ? {
+        max
+      } : {})
+    };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+// The control is editor metadata from API-writable json: enum-whitelisted
+// kind, clamped numbers, capped options. Anything malformed drops to
+// undefined — the editor falls back to a plain text input.
+function normalizeValueControl(raw) {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const control = raw;
+  if (control.kind === 'text') return {
+    kind: 'text'
+  };
+  if (control.kind === 'length' || control.kind === 'percent') {
+    const min = finiteNumber(control.min);
+    const max = finiteNumber(control.max);
+    const units = control.kind === 'length' && Array.isArray(control.units) ? control.units.filter(u => LENGTH_CONTROL_UNITS.includes(u)) : [];
+    // Per-unit min/max overrides: whitelisted unit keys, finite bounds. Any
+    // malformed entry is skipped; an empty result drops the whole field.
+    const ranges = control.kind === 'length' ? normalizeControlRanges(control.ranges) : undefined;
+    return {
+      kind: control.kind,
+      ...(min !== undefined ? {
+        min
+      } : {}),
+      ...(max !== undefined ? {
+        max
+      } : {}),
+      ...(units.length > 0 ? {
+        units
+      } : {}),
+      ...(ranges ? {
+        ranges
+      } : {})
+    };
+  }
+  if (control.kind === 'select' && Array.isArray(control.options)) {
+    const options = [];
+    for (const option of control.options) {
+      if (options.length >= MAX_SELECT_OPTIONS) break;
+      if (typeof option !== 'object' || option === null) continue;
+      if (typeof option.value !== 'string' || option.value.length > MAX_VALUE_LENGTH) continue;
+      options.push({
+        value: option.value,
+        label: typeof option.label === 'string' ? option.label : option.value
+      });
+    }
+    if (options.length > 0) return {
+      kind: 'select',
+      options
+    };
+  }
+  return undefined;
+}
+/**
+ * The page's named layout values from API-writable json: capped count,
+ * whitelisted keys, short '$'-free value strings (substitution is single-pass
+ * and this keeps refs from even *looking* chainable), validated controls.
+ */
+export function normalizeWebPopupValues(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const value of raw) {
+    if (out.length >= MAX_VALUES) break;
+    if (typeof value !== 'object' || value === null) continue;
+    if (typeof value.key !== 'string' || !WEB_POPUP_VALUE_KEY_PATTERN.test(value.key)) continue;
+    if (typeof value.value !== 'string' || value.value.length > MAX_VALUE_LENGTH || value.value.includes('$')) continue;
+    if (out.some(v => v.key === value.key)) continue;
+    const control = normalizeValueControl(value.control);
+    out.push({
+      key: value.key,
+      label: typeof value.label === 'string' ? value.label : '',
+      value: value.value,
+      ...(control ? {
+        control
+      } : {})
+    });
+  }
+  return out;
+}
+/** The values as a substitution map (see substituteWebPopupLayoutValues). */
+export function webPopupValuesMap(values) {
+  return Object.fromEntries(values.map(v => [v.key, v.value]));
+}
+const FORM_FIELD_KINDS = ['email', 'firstName', 'lastName', 'phone', 'custom'];
+const BUTTON_VARIANTS = ['primary', 'secondary'];
+const MAX_FORM_FIELDS = 10;
+// A form slot's fields from API-writable json: capped, whitelisted kinds,
+// deduped keys. The submit contract needs an email — when none survives, one
+// is injected up front (the slot stays renderable/editable rather than being
+// dropped: the editor canvas resolves through this same pipeline). Email
+// fields are always required — the payload can't form without a value.
+function normalizeFormFields(raw) {
+  const out = [];
+  if (Array.isArray(raw)) {
+    for (const field of raw) {
+      if (out.length >= MAX_FORM_FIELDS) break;
+      if (typeof field !== 'object' || field === null) continue;
+      if (typeof field.key !== 'string' || !field.key) continue;
+      if (!FORM_FIELD_KINDS.includes(field.kind)) continue;
+      if (out.some(f => f.key === field.key)) continue;
+      out.push({
+        key: field.key,
+        kind: field.kind,
+        label: typeof field.label === 'string' ? field.label : '',
+        placeholder: typeof field.placeholder === 'string' ? field.placeholder : '',
+        required: field.kind === 'email' || field.required === true,
+        ...(field.kind === 'custom' && typeof field.tag === 'string' && field.tag ? {
+          tag: field.tag
+        } : {})
+      });
+    }
+  }
+  if (!out.some(f => f.kind === 'email')) {
+    let key = 'field-email';
+    while (out.some(f => f.key === key)) key = `${key}-1`;
+    out.unshift({
+      key,
+      kind: 'email',
+      label: 'Email',
+      placeholder: '',
+      required: true
+    });
+  }
+  return out.slice(0, MAX_FORM_FIELDS);
+}
+const CHOICE_CONTROLS = ['checkbox', 'chips'];
+const RATING_SCALES = ['nps', 'stars', 'thumbs'];
+const RATING_SUBMIT_MODES = ['instant', 'button'];
+const TIMER_EXPIRE_ACTIONS = ['keep', 'hide-popup', 'page'];
+const LANGUAGE_CODE = /^[a-z]{2}$/i;
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+// Authored strings from API-writable json land in the popup's own markup on a
+// customer's page — capped so a 100kB "label" can't be one.
+const MAX_SLOT_STRING = 120;
+const MAX_SLOT_MESSAGE = 500;
+function slotString(value, max = MAX_SLOT_STRING) {
+  return typeof value === 'string' ? value.trim().slice(0, max) : '';
+}
+// A capped string with a fallback for when the json omits it (or sends blanks).
+function slotStringOr(value, fallback, max = MAX_SLOT_STRING) {
+  return slotString(value, max) || fallback;
+}
+/** An ISO 639-1 code, lowercased; anything else = '' (the renderer's 'en'). */
+function normalizeLanguage(value) {
+  const code = slotString(value, 8);
+  return LANGUAGE_CODE.test(code) ? code.toLowerCase() : '';
+}
+// Capped, non-empty values, deduped, label falling back to the value. An
+// option-less slot survives, like an unbound form: the editor must still edit it.
+function normalizeChoiceOptions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const option of raw) {
+    if (out.length >= WEB_POPUP_MAX_CHOICE_OPTIONS) break;
+    if (typeof option !== 'object' || option === null) continue;
+    const value = slotString(option.value);
+    if (!value) continue;
+    if (out.some(existing => existing.value === value)) continue;
+    const tagValue = slotString(option.tagValue);
+    out.push({
+      value,
+      label: slotStringOr(option.label, value),
+      ...(tagValue ? {
+        tagValue
+      } : {})
+    });
+  }
+  return out;
+}
+// The selection bounds against the surviving option count: 0 = unbounded, and
+// a max under the min would leave the slot unsubmittable — the min wins.
+function normalizeChoiceBounds(slot, options) {
+  const bound = value => {
+    const n = finiteNumber(value);
+    return n === undefined || n <= 0 ? 0 : Math.min(Math.floor(n), options);
+  };
+  const min = bound(slot.min);
+  const max = bound(slot.max);
+  return {
+    min,
+    max: max > 0 ? Math.max(min, max) : 0
+  };
+}
+// Per-type slot validation. Text and button entries pass through UNTOUCHED
+// when well-formed (stored popups predate this check — don't rewrite them);
+// a form slot is rebuilt field by field; an unknown slot type is dropped so
+// slot types added after this engine build degrade to absence, not a crash.
+function normalizeSlots(raw) {
+  const out = [];
+  for (const slot of raw) {
+    if (out.length >= MAX_ZONE_SLOTS) break;
+    if (typeof slot !== 'object' || slot === null) continue;
+    if (typeof slot.key !== 'string' || !slot.key) continue;
+    if (slot.type === 'text') {
+      if (typeof slot.html === 'string') out.push(slot);
+      continue;
+    }
+    if (slot.type === 'button') {
+      // An action-less button would crash the renderer on the action switch.
+      if (typeof slot.action === 'object' && slot.action !== null && typeof slot.action.type === 'string') {
+        out.push(slot);
+      }
+      continue;
+    }
+    if (slot.type === 'timer') {
+      // An unsupported zone name degrades to the contract's UTC rather than
+      // dropping the countdown.
+      const zone = slotString(slot.timezone, 64);
+      const timezone = webPopupTimeZoneSupported(zone) ? zone : '';
+      const endTime = slotString(slot.endTime, 32);
+      // No computable deadline = nothing to count down to.
+      if (webPopupWallClockMs(endTime, timezone) === null) continue;
+      const expirePage = slotString(slot.expirePage);
+      const onExpire = TIMER_EXPIRE_ACTIONS.includes(slot.onExpire) ? slot.onExpire : 'keep';
+      // 'page' without a target page is 'keep' — the renderer never has to
+      // guess where a pageless jump should land.
+      const expires = onExpire === 'page' && !expirePage ? 'keep' : onExpire;
+      out.push({
+        type: 'timer',
+        key: slot.key,
+        endTime,
+        timezone,
+        language: normalizeLanguage(slot.language),
+        showLabels: slot.showLabels !== false,
+        onExpire: expires,
+        ...(expires === 'page' ? {
+          expirePage
+        } : {})
+      });
+      continue;
+    }
+    if (slot.type === 'choice') {
+      const options = normalizeChoiceOptions(slot.options);
+      const {
+        min,
+        max
+      } = normalizeChoiceBounds(slot, options.length);
+      out.push({
+        type: 'choice',
+        key: slot.key,
+        control: CHOICE_CONTROLS.includes(slot.control) ? slot.control : 'checkbox',
+        tagName: slotString(slot.tagName),
+        options,
+        min,
+        max,
+        submitLabel: slotStringOr(slot.submitLabel, WEB_POPUP_CHOICE_DEFAULTS.submitLabel),
+        submitVariant: BUTTON_VARIANTS.includes(slot.submitVariant) ? slot.submitVariant : 'primary',
+        successMessage: slotStringOr(slot.successMessage, WEB_POPUP_CHOICE_DEFAULTS.successMessage, MAX_SLOT_MESSAGE)
+      });
+      continue;
+    }
+    if (slot.type === 'rating') {
+      const labels = typeof slot.labels === 'object' && slot.labels !== null ? slot.labels : {};
+      out.push({
+        type: 'rating',
+        key: slot.key,
+        // A malformed scale renders as stars: five buttons read the same in
+        // every language, which an 0..10 row does not.
+        scale: RATING_SCALES.includes(slot.scale) ? slot.scale : 'stars',
+        labels: {
+          low: slotString(labels.low),
+          high: slotString(labels.high)
+        },
+        submitMode: RATING_SUBMIT_MODES.includes(slot.submitMode) ? slot.submitMode : 'instant',
+        submitLabel: slotStringOr(slot.submitLabel, WEB_POPUP_RATING_DEFAULTS.submitLabel),
+        eventName: slotString(slot.eventName),
+        successMessage: slotStringOr(slot.successMessage, WEB_POPUP_RATING_DEFAULTS.successMessage, MAX_SLOT_MESSAGE)
+      });
+      continue;
+    }
+    if (slot.type === 'glyph') {
+      // An unknown icon name has no geometry to draw — dropped, exactly like
+      // an unknown slot type.
+      if (!WEB_POPUP_GLYPH_NAMES.includes(slot.name)) continue;
+      out.push({
+        type: 'glyph',
+        key: slot.key,
+        name: slot.name,
+        size: WEB_POPUP_GLYPH_SIZES.includes(slot.size) ? slot.size : WEB_POPUP_GLYPH_SIZES[0],
+        color: typeof slot.color === 'string' && HEX_COLOR.test(slot.color) ? slot.color : ''
+      });
+      continue;
+    }
+    if (slot.type === 'email-subscription-form') {
+      out.push({
+        type: 'email-subscription-form',
+        key: slot.key,
+        formCode: typeof slot.formCode === 'string' ? slot.formCode : '',
+        fields: normalizeFormFields(slot.fields),
+        submitLabel: typeof slot.submitLabel === 'string' && slot.submitLabel ? slot.submitLabel : WEB_POPUP_FORM_DEFAULTS.submitLabel,
+        submitVariant: BUTTON_VARIANTS.includes(slot.submitVariant) ? slot.submitVariant : 'primary',
+        ...(typeof slot.privacy === 'object' && slot.privacy !== null && typeof slot.privacy.checkboxLabel === 'string' ? {
+          privacy: {
+            checkboxLabel: slot.privacy.checkboxLabel,
+            url: typeof slot.privacy.url === 'string' ? slot.privacy.url : '',
+            linkLabel: typeof slot.privacy.linkLabel === 'string' ? slot.privacy.linkLabel : ''
+          }
+        } : {}),
+        successMessage: typeof slot.successMessage === 'string' && slot.successMessage ? slot.successMessage : WEB_POPUP_FORM_DEFAULTS.successMessage,
+        confirmEmailMessage: typeof slot.confirmEmailMessage === 'string' && slot.confirmEmailMessage ? slot.confirmEmailMessage : WEB_POPUP_FORM_DEFAULTS.confirmEmailMessage
+      });
+    }
+    // Unknown slot type → dropped.
+  }
+  return out;
+}
+// The zones come from API-writable json — keep only well-formed entries
+// (capped, see above) so the renderer can trust the shape.
+function normalizeContents(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const zone of raw) {
+    if (out.length >= MAX_ZONES) break;
+    if (typeof zone !== 'object' || zone === null) continue;
+    if (typeof zone.key !== 'string' || !zone.key) continue;
+    if (!Array.isArray(zone.slots)) continue;
+    out.push({
+      key: zone.key,
+      label: typeof zone.label === 'string' ? zone.label : '',
+      slots: normalizeSlots(zone.slots)
+    });
+  }
+  return out;
+}
+/**
+ * Every subscription form code the popup's form slots reference (unique,
+ * empty codes skipped) — what a host records view stats for. Reads the RAW
+ * params (tolerant of malformed slots), so it works on parsed-but-unresolved
+ * json.
+ */
+export function collectWebPopupFormCodes(params) {
+  const out = new Set();
+  for (const page of params.pages) {
+    if (!Array.isArray(page?.contents)) continue;
+    for (const zone of page.contents) {
+      if (!Array.isArray(zone?.slots)) continue;
+      for (const slot of zone.slots) {
+        if (typeof slot !== 'object' || slot === null) continue;
+        if (slot.type !== 'email-subscription-form') continue;
+        if (typeof slot.formCode === 'string' && slot.formCode) out.add(slot.formCode);
+      }
+    }
+  }
+  return [...out];
+}
+// Has a 'hide-popup' countdown run out? The HOST asks before showing, at SHOW
+// time; any page counts, and a malformed timer reads as 'not expired'.
+export function webPopupExpired(params, nowMs) {
+  for (const page of params.pages) {
+    if (!Array.isArray(page?.contents)) continue;
+    for (const zone of page.contents) {
+      if (!Array.isArray(zone?.slots)) continue;
+      for (const slot of zone.slots) {
+        if (typeof slot !== 'object' || slot === null) continue;
+        if (slot.type !== 'timer' || slot.onExpire !== 'hide-popup') continue;
+        if (typeof slot.endTime !== 'string') continue;
+        const timezone = typeof slot.timezone === 'string' ? slot.timezone : '';
+        const deadline = webPopupWallClockMs(slot.endTime, timezone);
+        if (deadline !== null && deadline <= nowMs) return true;
+      }
+    }
+  }
+  return false;
+}
+/**
+ * The popup box-size ceiling px, mirroring the layout tree's px clamp: the
+ * json is API-writable and the size lands as inline style on the customer's
+ * page. The editor clamps its Width/Height inputs to it too.
+ */
+export const WEB_POPUP_MAX_SIZE_PX = 2000;
+function validSize(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.min(value, WEB_POPUP_MAX_SIZE_PX) : undefined;
+}
+export function resolveWebPopupPageSize(own, shared, axis) {
+  if (own === null) return undefined;
+  let resolved;
+  if (own === 'stretch') resolved = 'stretch';else resolved = validSize(own) ?? (shared === 'stretch' ? 'stretch' : validSize(shared));
+  return axis === 'width' && resolved === 'stretch' ? undefined : resolved;
+}
+/**
+ * The renderable pages: each page carries its own embedded layout tree — no
+ * kind catalog at runtime. The page's named values are substituted into the
+ * tree first ($key tokens), then the result is validated/normalized
+ * (whitelisted props, unknown container types degrade to a Vertical stack) —
+ * so substituted values pass the same clamps as literals; pages whose layout
+ * isn't a tree at all are dropped. An empty result means the popup can't be
+ * rendered. width/height come out FINAL (page override ?? chrome, validated)
+ * — the renderer never falls back itself.
+ */
+export function resolveWebPopupPages(params) {
+  const out = [];
+  for (const page of params.pages) {
+    const values = normalizeWebPopupValues(page.values);
+    const layout = normalizeWebPopupLayout(substituteWebPopupLayoutValues(page.layout, webPopupValuesMap(values)));
+    if (!layout) continue;
+    const width = resolveWebPopupPageSize(page.width, params.width, 'width');
+    const height = resolveWebPopupPageSize(page.height, params.height, 'height');
+    out.push({
+      key: page.key,
+      layout,
+      images: normalizeImages(page.images),
+      contents: normalizeContents(page.contents),
+      ...(width !== undefined ? {
+        width
+      } : {}),
+      ...(height !== undefined ? {
+        height
+      } : {})
+    });
+  }
+  return out;
+}
+/** The page shown first: startPage when it exists, else the first page. */
+export function startPageOf(params, pages) {
+  return pages.find(p => p.key === params.startPage) ?? pages[0];
+}
+export function placementMaxSize(placement) {
+  return `calc(100% - ${placement.offset * 2}px)`;
+}