@pushwoosh/websdk-common 0.0.0 → 6.17.0

package/web-popups/types.d.ts

@@ -0,0 +1,660 @@
+import type { ReactNode } from 'react';
+/** Text styles a slot can use ('icon' = emoji line, 'eyebrow' = small caps kicker). */
+export type WebPopupTextVariant = 'icon' | 'eyebrow' | 'h1' | 'h2' | 'h3' | 'body' | 'caption';
+export type WebPopupTextAlign = 'left' | 'center' | 'right';
+export type WebPopupButtonVariant = 'primary' | 'secondary';
+/**
+ * What a button does: open a URL, dismiss the popup, switch to another page
+ * (`page` = WebPopupPageParams.key), or ask for push permission.
+ */
+export type WebPopupButtonAction = 
+/** `target` absent / anything but '_self' = a new tab (the historical behavior). */
+{
+    type: 'href';
+    url: string;
+    target?: '_blank' | '_self';
+} | {
+    type: 'close';
+} | {
+    type: 'page';
+    page: string;
+}
+/** Ask the browser for notification permission and subscribe the visitor. */
+ | {
+    type: 'subscribe';
+};
+/** What the host's subscribe handler settled on — the browser's permission after the ask. */
+export type WebPopupSubscribeResult = 'granted' | 'denied' | 'default';
+/**
+ * Input kinds an email-subscription-form slot renders — the same set the
+ * subscription-form service accepts in a submission ('custom' entries land in
+ * the `customFields` map under the field's `tag`).
+ */
+export type WebPopupFormFieldKind = 'email' | 'firstName' | 'lastName' | 'phone' | 'custom';
+export type WebPopupFormField = {
+    /** Stable id within the slot ('field-N'), not a display name. */
+    key: string;
+    kind: WebPopupFormFieldKind;
+    /** Caption above the input; empty = no caption. */
+    label: string;
+    placeholder: string;
+    required: boolean;
+    /** The tag a 'custom' field submits under; other kinds ignore it. */
+    tag?: string;
+};
+/** The consent row of a form slot: a required checkbox with a policy link. */
+export type WebPopupFormPrivacy = {
+    checkboxLabel: string;
+    /** Policy page URL, rendered through safeUrl like every popup link. */
+    url: string;
+    linkLabel: string;
+};
+/** What a `timer` slot does once its deadline has passed. */
+export type WebPopupTimerExpireAction = 'keep' | 'hide-popup' | 'page';
+/** A countdown to a fixed deadline; the field contract is the email builder's timer block. */
+export type WebPopupTimerSlot = {
+    type: 'timer';
+    key: string;
+    /** Countdown target as local wall-clock time in `timezone`. */
+    endTime: string;
+    /** IANA zone name; empty = UTC. */
+    timezone: string;
+    /** Unit-label language (ISO 639-1); empty/unknown = 'en'. */
+    language: string;
+    showLabels: boolean;
+    /** Behavior past the deadline; 'hide-popup' is the host's call, see webPopupExpired. */
+    onExpire: WebPopupTimerExpireAction;
+    /** Target page key for onExpire 'page'; normalization drops a pageless 'page' to 'keep'. */
+    expirePage?: string;
+};
+/** How a `choice` slot renders its options. */
+export type WebPopupChoiceControl = 'checkbox' | 'chips';
+export type WebPopupChoiceOption = {
+    /** Stable value within the slot — and what is written to the tag when `tagValue` is absent. */
+    value: string;
+    label: string;
+    /** Tag value this option submits, when it differs from `value`. */
+    tagValue?: string;
+};
+/** A topic picker written to a LIST device tag; no callback or no `tagName` = inert. */
+export type WebPopupChoiceSlot = {
+    type: 'choice';
+    key: string;
+    control: WebPopupChoiceControl;
+    /** The device tag the choice is written to; '' = the slot is inert. */
+    tagName: string;
+    options: WebPopupChoiceOption[];
+    /** Selection bounds against the option count; 0 = unbounded. */
+    min: number;
+    max: number;
+    submitLabel: string;
+    submitVariant: WebPopupButtonVariant;
+    /** Replaces the slot after a successful submit. */
+    successMessage: string;
+};
+/** A rating slot's scale: 11 buttons (0..10), 5 stars, or 2 thumbs. */
+export type WebPopupRatingScale = 'nps' | 'stars' | 'thumbs';
+/** 'instant' posts the score on tap; 'button' waits for the submit pill. */
+export type WebPopupRatingSubmitMode = 'instant' | 'button';
+/** A rating question; the score leaves as an EVENT, and no callback or no `eventName` = inert. */
+export type WebPopupRatingSlot = {
+    type: 'rating';
+    key: string;
+    scale: WebPopupRatingScale;
+    /** Captions under the extremes of the scale; '' = none. */
+    labels: {
+        low: string;
+        high: string;
+    };
+    submitMode: WebPopupRatingSubmitMode;
+    submitLabel: string;
+    /** The event the score is posted as; '' = the slot is inert. */
+    eventName: string;
+    /** Replaces the slot after a successful submit. */
+    successMessage: string;
+};
+/** The icon whitelist: inline svg only — no icon package in the widget bundle, no svg from json. */
+export type WebPopupGlyphName = 'bell' | 'gift' | 'cart' | 'chart' | 'lock' | 'calendar' | 'check' | 'star' | 'clock' | 'tag' | 'mail' | 'phone' | 'download' | 'play' | 'shield' | 'sparkle' | 'percent' | 'truck' | 'ticket' | 'user';
+export type WebPopupGlyphSize = 24 | 32 | 48;
+/** A single icon; named `glyph` because WebPopupTextVariant already spends `icon` on its emoji line. */
+export type WebPopupGlyphSlot = {
+    type: 'glyph';
+    key: string;
+    /** Whitelisted name; an unknown one drops the slot (no geometry to draw). */
+    name: WebPopupGlyphName;
+    size: WebPopupGlyphSize;
+    /** Hex '#rrggbb'; '' = the palette accent. */
+    color: string;
+};
+/** One entry of a page's content stack, in display order. */
+export type WebPopupSlot = {
+    type: 'text';
+    key: string;
+    variant: WebPopupTextVariant;
+    html: string;
+    /** Per-slot alignment override; absent = the page kind's layout.align. */
+    align?: WebPopupTextAlign;
+} | {
+    type: 'button';
+    key: string;
+    variant: WebPopupButtonVariant;
+    label: string;
+    action: WebPopupButtonAction;
+}
+/**
+ * An email-subscription form: input fields + a submit button, bound to a
+ * Pushwoosh subscription form entity by `formCode`. The fields are the
+ * slot's own (seeded from the form's configuration by the editor) — the
+ * runtime renders straight from the json and never fetches the form. The
+ * host submits via WebPopupReaderProps.onSubmitForm; without the callback
+ * (editor canvas, previews) the form renders inert. NOTE: engine builds
+ * that predate this slot type cannot render a popup containing it.
+ */
+ | {
+    type: 'email-subscription-form';
+    key: string;
+    /** Bound subscription form code; '' until picked — the form is inert. */
+    formCode: string;
+    fields: WebPopupFormField[];
+    submitLabel: string;
+    submitVariant: WebPopupButtonVariant;
+    /** Absent = no consent checkbox (submits policyAccepted: true). */
+    privacy?: WebPopupFormPrivacy;
+    /** Replaces the form after a subscribed / already-subscribed result. */
+    successMessage: string;
+    /** Replaces the form after the double-opt-in confirm-email result. */
+    confirmEmailMessage: string;
+} | WebPopupTimerSlot | WebPopupChoiceSlot | WebPopupRatingSlot | WebPopupGlyphSlot;
+/** What a media param plays instead of drawing its image; the param's `src` stays the poster, so engines predating video degrade to it. */
+export type WebPopupVideo = {
+    /** Video url, rendered through safeUrl like every popup link. */
+    src: string;
+    /** Absent = chromeless playback (no browser controls). */
+    controls?: boolean;
+    /** Absent = loop; false = play once. */
+    loop?: boolean;
+};
+/**
+ * An image parameter: the data plus its presentation. WHERE it renders is
+ * the layout tree's business (an `Image` node or a container's
+ * `backgroundImage` reference this by key); HOW it renders — fit, blur — is
+ * the image's own, per-popup editable like the src.
+ */
+export type WebPopupImage = {
+    key: string;
+    /** Shown as the field label in the editor rail. */
+    label: string;
+    src: string;
+    /** Drawn instead of `src` in the dark scheme (a light logo would stay light
+     * on a dark background); absent = `src` in both. */
+    srcDark?: string;
+    /** uuid of the media-gallery file `srcDark` was picked from; editor-only, like `mediaId`. */
+    mediaIdDark?: string;
+    /** Set = the param renders as a muted autoplaying video with `src` as its poster. */
+    video?: WebPopupVideo;
+    /**
+     * uuid of the media-gallery file `src` was picked from, kept alongside the
+     * url for dedup and gallery back-reference. Absent for externally-typed urls
+     * (no gallery entry) and legacy documents. The runtime ignores it — it
+     * renders by `src`; only the editor reads it.
+     */
+    mediaId?: string;
+    /**
+     * How the image fills its box when drawn by an `Image` node; a container
+     * background always covers. Absent = natural flow (full width, auto height).
+     */
+    fit?: 'cover' | 'contain';
+    /** Blur radius px applied when drawn (backdrop-filter over a container
+     * background, css filter on an image node). Absent / 0 = no blur. */
+    blur?: number;
+    /**
+     * Scrim: a dark translucent layer (0 = none … 1 = black) drawn over the
+     * image when it's a container BACKGROUND, keeping the copy above readable
+     * on light photos. `Image` nodes ignore it. Absent / 0 = no scrim.
+     */
+    dim?: number;
+};
+export type WebPopupVAnchor = 'top' | 'middle' | 'bottom';
+export type WebPopupHAnchor = 'left' | 'center' | 'right';
+/** Viewport placement: a 3×3 anchor plus the gutter from the anchored edges. */
+export type WebPopupPlacement = {
+    v: WebPopupVAnchor;
+    h: WebPopupHAnchor;
+    /** Distance from the anchored edges, px (0 = flush). */
+    offset: number;
+};
+/** The page dim behind the popup; absent on params = no dimming. */
+export type WebPopupOverlay = {
+    color: string;
+    /** 0 (transparent) to 1 (opaque). */
+    opacity: number;
+};
+export type WebPopupAnimation = 'none' | 'fade' | 'slide';
+/**
+ * The popup palette — every color that varies. What derives from it is fixed:
+ * buttons pair the accent with white (primary = accent fill + white label,
+ * secondary = white fill + accent outline).
+ */
+export type WebPopupColors = {
+    /** Popup background color. */
+    background: string;
+    /** Brand accent: primary button fill, secondary button outline. */
+    accent: string;
+    /** Main copy: h1–h3 and body ('icon' inherits it). */
+    text: string;
+    /** Secondary copy: caption and eyebrow. */
+    textSecondary: string;
+    /**
+     * Copy in inverse-tone zones (over a background image). Secondary variants
+     * (eyebrow/body/caption) derive their translucency from it per
+     * webPopupTextColor. Default white — set it dark for light photos.
+     */
+    textInverse: string;
+};
+/** Which of the two authored palettes a popup is being drawn with. */
+export type WebPopupColorScheme = 'light' | 'dark';
+/** What a host asks the reader for; 'auto' follows the visitor's `prefers-color-scheme`. */
+export type WebPopupColorSchemePref = WebPopupColorScheme | 'auto';
+/** The dark-scheme palette; `enabled: false` keeps it around while the popup
+ * renders light, which is what the editor's checkbox needs. */
+export type WebPopupDark = {
+    enabled: boolean;
+    colors: WebPopupColors;
+    /** Page dim for the dark scheme; absent = the chrome's own overlay. */
+    overlay?: WebPopupOverlay;
+    /** Box shadow for the dark scheme ('none' = drop it); absent = the chrome's own. */
+    boxShadow?: string;
+};
+/** What a renderer draws with: the scheme's five authored roles plus the ones
+ * derived from them, which used to be hardcoded light values. */
+export type WebPopupResolvedColors = WebPopupColors & {
+    /** Which palette this resolved from — 'light' for a popup with dark mode off. */
+    scheme: WebPopupColorScheme;
+    /** Fill of the cards that sit ON the popup background: inputs, secondary buttons. */
+    surface: string;
+    /** Copy inside a `surface` card. */
+    surfaceText: string;
+    /** Idle border of an input card. */
+    border: string;
+    /** Label over an accent fill: a primary button, a selected option. */
+    onAccent: string;
+    /** Validation errors and the generic retry line. */
+    error: string;
+    /** Glyph on a service chip drawn over the popup — today the ✕ button. */
+    chromeIcon: string;
+};
+/**
+ * The popup-level look shared by all pages: size, colors, viewport placement,
+ * page dim, animation and the box chrome. The retired top-level
+ * `background`/`accent` fields are folded into `colors` by parseWebPopupJson
+ * and mirrored back by stringifyWebPopup (so older engine builds keep
+ * rendering newly-saved popups) — they never appear on this type.
+ */
+export type WebPopupChrome = {
+    /** Width px. Absent = stretch to the available viewport width. A page may
+     * override it (WebPopupPageParams.width). */
+    width?: number;
+    /** Height px. Absent = grow with content; a number = fixed, content
+     * scrolls; 'stretch' = fill the viewport height (both vertical edges pinned
+     * at the placement offset, like the width-absent horizontal stretch —
+     * engine builds that predate the value treat it as absent and grow with
+     * content). A page may override it. */
+    height?: number | 'stretch';
+    colors: WebPopupColors;
+    /** Dark-scheme palette; absent or disabled = the popup always renders light. */
+    dark?: WebPopupDark;
+    placement: WebPopupPlacement;
+    overlay?: WebPopupOverlay;
+    animation: WebPopupAnimation;
+    /** Corner radius px. 0 = sharp corners. */
+    borderRadius: number;
+    /** CSS box-shadow string; 'none' = no shadow. */
+    boxShadow: string;
+};
+/** A named group of slots a layout `Content` node binds to by key. */
+export type WebPopupContentZone = {
+    /** Stable zone id (referenced by the layout tree), not a display name. */
+    key: string;
+    /** Shown as the zone's name in the editor. */
+    label: string;
+    slots: WebPopupSlot[];
+};
+/** A css length unit a `length` control accepts. */
+export type WebPopupLengthUnit = 'px' | '%' | 'em' | 'rem' | 'fr';
+/** Min/max bounds for a length amount — a control's default or one unit's override. */
+export type WebPopupLengthRange = {
+    min?: number;
+    max?: number;
+};
+/**
+ * Which editor control a value param is edited with. Editor metadata (the
+ * runtime never reads it), stored in json like an image's label so
+ * API/AI-authored pages get knobs too. Absent / unknown = a plain text input.
+ */
+export type WebPopupValueControl = 
+/**
+ * A number input with a unit. `min`/`max` bound the amount; `ranges` narrows
+ * them per unit (e.g. 120–480px but 20–60%) — a unit falls back to the flat
+ * `min`/`max` when it has no entry.
+ */
+{
+    kind: 'length';
+    min?: number;
+    max?: number;
+    units?: WebPopupLengthUnit[];
+    ranges?: Partial<Record<WebPopupLengthUnit, WebPopupLengthRange>>;
+}
+/** A 0–100 slider writing 'NN%'. */
+ | {
+    kind: 'percent';
+    min?: number;
+    max?: number;
+} | {
+    kind: 'select';
+    options: {
+        value: string;
+        label: string;
+    }[];
+} | {
+    kind: 'text';
+};
+/**
+ * A named style value the page's layout tree references as a `$key` token
+ * (whole string prop or a whitespace-separated token inside a `sizes`
+ * template) — the third page-param family after images and contents: WHERE
+ * the value applies is the tree's business, the value itself is the param's
+ * own, per-popup editable. resolveWebPopupPages substitutes values BEFORE
+ * the layout normalization, so a substituted value passes the same
+ * whitelists/clamps as a literal one. Binding keys (`content`, `image`,
+ * `backgroundImage`) are never substituted.
+ */
+export type WebPopupValueParam = {
+    /** Stable id the tree references as `$key`; not a display name. */
+    key: string;
+    /** Shown as the field label in the editor rail. */
+    label: string;
+    /** The current value, substituted into the tree verbatim. */
+    value: string;
+    control?: WebPopupValueControl;
+};
+/** A px number or a whitelisted css length string ('12px', '55%', '1.5em'). */
+export type WebPopupCssLength = string | number;
+export type WebPopupBoxSides = {
+    top?: WebPopupCssLength;
+    right?: WebPopupCssLength;
+    bottom?: WebPopupCssLength;
+    left?: WebPopupCssLength;
+};
+export type WebPopupAlignItems = 'start' | 'center' | 'end' | 'stretch';
+export type WebPopupJustifyContent = 'start' | 'center' | 'end' | 'space-between';
+/**
+ * A `$key` reference to a page value (WebPopupValueParam) in an AUTHORED
+ * (template/catalog/stored) tree — resolveWebPopupPages substitutes it before
+ * normalization, so a normalized tree only carries literal values. Every
+ * enum container prop accepts it (substitution walks all string props).
+ */
+export type WebPopupValueRef = `$${string}`;
+export type WebPopupContainerType = 'Vertical' | 'Horizontal' | 'Columns' | 'Rows';
+export type WebPopupContainerProps = {
+    gap?: WebPopupCssLength;
+    padding?: WebPopupCssLength | WebPopupBoxSides;
+    alignItems?: WebPopupAlignItems | WebPopupValueRef;
+    justifyContent?: WebPopupJustifyContent | WebPopupValueRef;
+    /**
+     * Vertical distribution of the container's rows — visible only when the
+     * container is taller than its content (a 'stretch'-height page's root
+     * container fills the box). Same value set as justifyContent.
+     */
+    alignContent?: WebPopupJustifyContent | WebPopupValueRef;
+    /** Key into page images: the container draws it as a cover background. */
+    backgroundImage?: string;
+    /**
+     * Columns/Rows track template: N equal tracks, or a whitelist-validated
+     * template string ('1fr 220px'). Absent = one equal track per child.
+     * Ignored on Vertical/Horizontal.
+     */
+    sizes?: number | string;
+    /**
+     * 'reverse' renders the children in reverse order; on Columns/Rows the
+     * `sizes` template reverses with them, so each child keeps its track.
+     * Applied (and consumed) by normalizeWebPopupLayout — a normalized tree
+     * has the children already reordered and no `order` left.
+     */
+    order?: 'normal' | 'reverse' | WebPopupValueRef;
+};
+/** Text palette of a Content zone; 'inverse' = white copy over a dark image. */
+export type WebPopupContentTone = 'default' | 'inverse';
+export type WebPopupContentNode = {
+    type: 'Content';
+    props: {
+        /** WebPopupContentZone key; an unknown key renders as an empty zone. */
+        content: string;
+        /** Default text alignment; a text slot's own `align` overrides it. */
+        align?: WebPopupTextAlign;
+        tone?: WebPopupContentTone;
+    };
+};
+export type WebPopupImageNode = {
+    type: 'Image';
+    props: {
+        /** WebPopupImage key; an unknown key renders nothing. How the image
+         * renders (fit, blur) lives on the image param itself. */
+        image: string;
+    };
+};
+export type WebPopupContainerNode = {
+    type: WebPopupContainerType;
+    props?: WebPopupContainerProps;
+    children: WebPopupLayoutNode[];
+};
+export type WebPopupLayoutNode = WebPopupContainerNode | WebPopupContentNode | WebPopupImageNode;
+/**
+ * One page of the popup. `key` is unique within the popup; button `page`
+ * actions point at it. The layout tree is EMBEDDED (copied from the kind by
+ * the editor on save), so the display engine renders the page self-contained
+ * — no kind catalog at runtime, and new kinds render on older engine builds.
+ */
+export type WebPopupPageParams = {
+    key: string;
+    /** WebPopupKind id — editor metadata only; the runtime never resolves it. */
+    kind: string;
+    layout: WebPopupLayoutNode;
+    images: WebPopupImage[];
+    contents: WebPopupContentZone[];
+    /** Named style values the layout tree references as `$key` tokens. */
+    values?: WebPopupValueParam[];
+    /**
+     * The page's own box size, overriding the chrome's: a number = px, `null` =
+     * explicitly auto (needed when the chrome default IS a number), absent =
+     * the chrome's width/height. Engine builds that predate the field ignore it
+     * and show every page at the chrome size.
+     */
+    width?: number | null;
+    /** See `width`; auto height = grow with content, a number = fixed
+     * (scrolls), 'stretch' = fill the viewport height. */
+    height?: number | 'stretch' | null;
+};
+export type WebPopupParams = WebPopupChrome & {
+    /** The pages, in order; at least one. Only one shows at a time. */
+    pages: WebPopupPageParams[];
+    /** Key of the page shown first; absent/unknown = the first page. */
+    startPage?: string;
+};
+export type WebPopupKind = {
+    id: string;
+    label: string;
+    layout: WebPopupLayoutNode;
+    /** The chrome a fresh popup of this kind opens with in the editor gallery. */
+    chrome: WebPopupChrome;
+    /** The default content a new page of this kind opens with. */
+    content: {
+        images: WebPopupImage[];
+        contents: WebPopupContentZone[];
+    };
+    /**
+     * The value params the layout references as `$key` tokens; `value` is the
+     * default a fresh page's `values` open with.
+     */
+    params?: WebPopupValueParam[];
+};
+/**
+ * A system layout template — a blessed, parameterized arrangement the editor
+ * kinds instantiate instead of hand-writing trees (a kind may still carry its
+ * own tree where no template fits). The tree references `$key` value params
+ * and binds the canonical zone/image keys ('main', 'image'); the kind catalog
+ * may rebind those when instantiating. Editor-only, like the kind catalog.
+ */
+export type WebPopupTemplate = {
+    name: string;
+    layout: WebPopupLayoutNode;
+    /** The template's knobs; `value` holds the default. */
+    params: WebPopupValueParam[];
+};
+/** A page with its layout tree validated/normalized — the renderable unit. */
+export type WebPopupResolvedPage = {
+    key: string;
+    layout: WebPopupLayoutNode;
+    images: WebPopupImage[];
+    contents: WebPopupContentZone[];
+    /** The page's FINAL box width px (page ?? chrome, validated); absent =
+     * stretch to the available viewport width. */
+    width?: number;
+    /** Final box height: px, or 'stretch' = fill the viewport height; absent =
+     * grow with content. */
+    height?: number | 'stretch';
+};
+/** The stored format — PopupFormContent.json parses into this. */
+export type WebPopupJson = {
+    /** Format version; content without it predates this engine and is unrenderable. */
+    version: number;
+    params: WebPopupParams;
+};
+export type WebPopupReaderMode = 'live' | 'preview';
+/**
+ * What an email-subscription-form slot submits — mirrors the
+ * subscription-form service's submit request (the host adds transport fields
+ * like userId itself). Custom fields land under their `tag` (falling back to
+ * the field key).
+ */
+export type WebPopupFormSubmitPayload = {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    customFields?: Record<string, string>;
+    /** True when the slot has no privacy checkbox. */
+    policyAccepted: boolean;
+};
+/** A countdown's remaining time at some instant, broken down for display. */
+export type WebPopupTimerRemaining = {
+    /** Whole milliseconds left; 0 = the deadline has passed (or can't be computed). */
+    total: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+};
+/** The service's submit outcomes; 'confirm-email' = double-opt-in pending. */
+export type WebPopupFormSubmitResult = 'subscribed' | 'confirm-email' | 'already-subscribed';
+/**
+ * Submits a form slot's payload to the bound subscription form. Rejects on
+ * network/server failure — the slot shows a generic retryable error.
+ */
+export type WebPopupFormSubmitHandler = (formCode: string, payload: WebPopupFormSubmitPayload) => Promise<WebPopupFormSubmitResult>;
+/** What a `choice` slot submits: the picked options' tag values, in option order. */
+export type WebPopupChoiceSubmitPayload = {
+    slotKey: string;
+    tagName: string;
+    values: string[];
+};
+/** Writes a choice slot's selection to the device tag; a rejection is what leaves the slot retryable. */
+export type WebPopupChoiceSubmitHandler = (payload: WebPopupChoiceSubmitPayload) => Promise<void>;
+/** What a `rating` slot submits: the score plus the scale it was given on. */
+export type WebPopupRatingSubmitPayload = {
+    slotKey: string;
+    eventName: string;
+    score: number;
+    scale: WebPopupRatingScale;
+};
+/** Posts a rating slot's score as an event. Rejects on failure — see above. */
+export type WebPopupRatingSubmitHandler = (payload: WebPopupRatingSubmitPayload) => Promise<void>;
+/**
+ * Editor-only overrides for the tree's data-binding LEAVES. The container
+ * interpretation (grid divs, background images, dim, blur) is deliberately
+ * NOT overridable — rendering it here is what guarantees an editor canvas
+ * matches the runtime pixel for pixel. The runtime never passes these.
+ */
+export type WebPopupLeafRenderers = {
+    /** Replaces a Content leaf's slot stack. Unknown zone keys still render nothing. */
+    renderZone?: (zone: WebPopupContentZone, node: WebPopupContentNode) => ReactNode;
+    /**
+     * Replaces an Image leaf's <img>. Called whenever the image param exists —
+     * including an empty src the runtime would hide (editors want a
+     * placeholder there). Unknown image keys still render nothing.
+     */
+    renderImage?: (image: WebPopupImage, node: WebPopupImageNode) => ReactNode;
+};
+export type WebPopupReaderProps = {
+    params: WebPopupParams;
+    /**
+     * 'live' (default): fixed-position chrome — overlay, viewport placement,
+     * enter animation, close button. 'preview': the popup box rendered inline
+     * (relative), for editor/list previews.
+     */
+    mode?: WebPopupReaderMode;
+    /** Palette to draw with; default 'auto' — the visitor's OS setting, watched live. */
+    colorScheme?: WebPopupColorSchemePref;
+    /** Close requests: the ✕ button, the overlay click and 'close'-action buttons. */
+    onRequestClose?: () => void;
+    /** Form-slot submits; absent = form slots render inert (previews, editor). */
+    onSubmitForm?: WebPopupFormSubmitHandler;
+    /** Choice-slot submits; absent = choice slots render inert. */
+    onSubmitChoice?: WebPopupChoiceSubmitHandler;
+    /** Rating-slot submits; absent = rating slots render inert. */
+    onSubmitRating?: WebPopupRatingSubmitHandler;
+    /** `subscribe`-action buttons; absent = they render inert (previews, editor). */
+    onRequestSubscribe?: () => Promise<WebPopupSubscribeResult>;
+    /** Editor-only leaf overrides — see WebPopupLeafRenderers. */
+    leafRenderers?: WebPopupLeafRenderers;
+};
+/** Props of WebPopupSlotView — one slot, drawn the runtime's way; the defaults are the inert ones an editor wants. */
+export type WebPopupSlotViewProps = {
+    slot: WebPopupSlot;
+    align: WebPopupTextAlign;
+    /** Inverse tone (over a dark image) — the zone node's, not the slot's. */
+    inverse: boolean;
+    colors: WebPopupResolvedColors;
+    /** Default 'live'; an editor canvas or a preview card passes 'preview'. */
+    mode?: WebPopupReaderMode;
+    onRequestClose?: () => void;
+    onPageChange?: (page: string) => void;
+    onSubmitForm?: WebPopupFormSubmitHandler;
+    onSubmitChoice?: WebPopupChoiceSubmitHandler;
+    onSubmitRating?: WebPopupRatingSubmitHandler;
+    /** `subscribe`-action buttons; absent = they render inert (previews, editor). */
+    onRequestSubscribe?: () => Promise<WebPopupSubscribeResult>;
+};
+/** Props of WebPopupBox — one resolved page's box, no viewport chrome. */
+export type WebPopupBoxProps = {
+    page: WebPopupResolvedPage;
+    params: WebPopupParams;
+    /** What the box is drawn for; default 'live'. 'preview' reaches the leaves: no autoplay, no interval. */
+    mode?: WebPopupReaderMode;
+    /** Palette to draw with; default 'light'. The reader resolves 'auto' before it gets here. */
+    colorScheme?: WebPopupColorScheme;
+    /** Editor-only leaf overrides — see WebPopupLeafRenderers. */
+    leafRenderers?: WebPopupLeafRenderers;
+    /** Play the page-switch fade on this render (the reader sets it after navigation). */
+    animatePage?: boolean;
+    onRequestClose?: () => void;
+    /** `page`-action buttons; absent = they render inert (editor canvas). */
+    onPageChange?: (page: string) => void;
+    /** Form-slot submits; absent = form slots render inert (previews, editor). */
+    onSubmitForm?: WebPopupFormSubmitHandler;
+    /** Choice-slot submits; absent = choice slots render inert. */
+    onSubmitChoice?: WebPopupChoiceSubmitHandler;
+    /** Rating-slot submits; absent = rating slots render inert. */
+    onSubmitRating?: WebPopupRatingSubmitHandler;
+    /** `subscribe`-action buttons; absent = they render inert (previews, editor). */
+    onRequestSubscribe?: () => Promise<WebPopupSubscribeResult>;
+};

package/web-popups/types.js

@@ -0,0 +1,10 @@
+// The web-popup model. The stored/wire shape is WebPopupJson —
+// { version: 2, params } serialized into PopupFormContent.json. A popup is a
+// set of PAGES (each page = a layout TREE plus named content zones and
+// images) under a shared CHROME (size, colors, placement, overlay,
+// animation, ...). Only one page shows at a time; `page`-action buttons
+// switch between them. The editor (smart-blocks) produces the json;
+// WebPopupReader renders it on the customer's site (WebSDK) and in previews
+// (content). Pure types only — constants live in constants.tsx, helpers in
+// helpers.ts, layout-tree validation in layout.ts.
+export {};