@4site/engrid-scripts 0.25.1 → 0.25.2

package/dist/engrid.d.ts

@@ -15,6 +15,16 @@ export declare abstract class ENGrid {
     static getPageNumber(): any;
     static isThankYouPage(): boolean;
     static getPageID(): any;
+    /**
+     * Parse the numeric Page ID out of a Engaging Networks URL.
+     * EN page URLs follow the pattern `https://<host>/page/<PAGE_ID>/<slug>/...`.
+     * Used by the Iframe Queue component to match Thank-You-page pings from
+     * embedded iframes against the queued URL that was submitted.
+     *
+     * @param url Full URL string to parse.
+     * @returns The numeric Page ID, or 0 if it could not be parsed.
+     */
+    static getPageIdFromUrl(url: string): number;
     static getClientID(): any;
     static getDataCenter(): "us" | "ca";
     static getPageType(): "DONATION" | "ECARD" | "SURVEY" | "EMAILTOTARGET" | "ADVOCACY" | "SUBSCRIBEFORM" | "EVENT" | "SUPPORTERHUB" | "UNSUBSCRIBE" | "TWEETPAGE" | "UNKNOWN";

package/dist/engrid.js

@@ -178,6 +178,24 @@ export class ENGrid {
             return window.pageJson.campaignPageId;
         return 0;
     }
+    /**
+     * Parse the numeric Page ID out of a Engaging Networks URL.
+     * EN page URLs follow the pattern `https://<host>/page/<PAGE_ID>/<slug>/...`.
+     * Used by the Iframe Queue component to match Thank-You-page pings from
+     * embedded iframes against the queued URL that was submitted.
+     *
+     * @param url Full URL string to parse.
+     * @returns The numeric Page ID, or 0 if it could not be parsed.
+     */
+    static getPageIdFromUrl(url) {
+        if (!url)
+            return 0;
+        const match = url.match(/\/page\/(\d+)(?:\/|$|\?|#)/);
+        if (!match)
+            return 0;
+        const id = parseInt(match[1], 10);
+        return Number.isFinite(id) ? id : 0;
+    }
     // Return the client ID
     static getClientID() {
         if ("pageJson" in window)

package/dist/events/iframe-queue-events.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Singleton event hub for the Iframe Queue component.
+ *
+ * Mirrors the structure of RememberMeEvents: private constructor,
+ * static `getInstance()`, internal dispatchers exposed via `.asEvent()`
+ * getters, and `dispatch*` methods called by the IframeQueue class.
+ *
+ * External code subscribes to these events to react to queue
+ * lifecycle without holding a reference to the IframeQueue itself.
+ * The TNC Bequest Lightbox, for example, will subscribe to
+ * `onChainComplete` so it only opens after the QCB opt-in chain has
+ * finished submitting.
+ *
+ * @example
+ *   IframeQueueEvents.getInstance().onChainComplete.subscribe(() => {
+ *     openBequestLightbox();
+ *   });
+ */
+import { IframeQueueItem, IframeQueueErrorPayload } from "../interfaces/iframe-queue-options";
+export declare class IframeQueueEvents {
+    private logger;
+    private _onChainComplete;
+    private _onChainError;
+    private _onItemStart;
+    private _onItemComplete;
+    private _onItemError;
+    private static instance;
+    private constructor();
+    /** Returns the shared IframeQueueEvents singleton. */
+    static getInstance(): IframeQueueEvents;
+    /**
+     * Fires once when the entire queue completes successfully.
+     * Use to trigger work that must wait for all chained iframe submits
+     * (e.g. opening a bequest lightbox after QCB opt-ins are recorded).
+     */
+    get onChainComplete(): import("strongly-typed-events").ISignal;
+    /**
+     * Fires when the queue aborts due to an error (timeout, iframe load
+     * error, or error message from an embedded page). Carries the failed
+     * item (if known) and the underlying error.
+     */
+    get onChainError(): import("strongly-typed-events").ISimpleEvent<IframeQueueErrorPayload>;
+    /** Fires immediately before an item begins processing. */
+    get onItemStart(): import("strongly-typed-events").ISimpleEvent<IframeQueueItem>;
+    /** Fires when an item completes (its iframe reached its Thank You page). */
+    get onItemComplete(): import("strongly-typed-events").ISimpleEvent<IframeQueueItem>;
+    /** Fires when an item fails. The queue aborts after this event. */
+    get onItemError(): import("strongly-typed-events").ISimpleEvent<{
+        item: IframeQueueItem;
+        error: Error;
+    }>;
+    /** Internal — called by IframeQueue when the queue drains successfully. */
+    dispatchChainComplete(): void;
+    /** Internal — called by IframeQueue when the queue aborts on error. */
+    dispatchChainError(payload: IframeQueueErrorPayload): void;
+    /** Internal — called by IframeQueue immediately before an item starts. */
+    dispatchItemStart(item: IframeQueueItem): void;
+    /** Internal — called by IframeQueue when an item finishes successfully. */
+    dispatchItemComplete(item: IframeQueueItem): void;
+    /** Internal — called by IframeQueue when an item errors. */
+    dispatchItemError(item: IframeQueueItem, error: Error): void;
+}

package/dist/events/iframe-queue-events.js

@@ -0,0 +1,90 @@
+/**
+ * Singleton event hub for the Iframe Queue component.
+ *
+ * Mirrors the structure of RememberMeEvents: private constructor,
+ * static `getInstance()`, internal dispatchers exposed via `.asEvent()`
+ * getters, and `dispatch*` methods called by the IframeQueue class.
+ *
+ * External code subscribes to these events to react to queue
+ * lifecycle without holding a reference to the IframeQueue itself.
+ * The TNC Bequest Lightbox, for example, will subscribe to
+ * `onChainComplete` so it only opens after the QCB opt-in chain has
+ * finished submitting.
+ *
+ * @example
+ *   IframeQueueEvents.getInstance().onChainComplete.subscribe(() => {
+ *     openBequestLightbox();
+ *   });
+ */
+import { SignalDispatcher, SimpleEventDispatcher } from "strongly-typed-events";
+import { EngridLogger } from "..";
+export class IframeQueueEvents {
+    constructor() {
+        this.logger = new EngridLogger("IframeQueueEvents");
+        this._onChainComplete = new SignalDispatcher();
+        this._onChainError = new SimpleEventDispatcher();
+        this._onItemStart = new SimpleEventDispatcher();
+        this._onItemComplete = new SimpleEventDispatcher();
+        this._onItemError = new SimpleEventDispatcher();
+    }
+    /** Returns the shared IframeQueueEvents singleton. */
+    static getInstance() {
+        if (!IframeQueueEvents.instance) {
+            IframeQueueEvents.instance = new IframeQueueEvents();
+        }
+        return IframeQueueEvents.instance;
+    }
+    /**
+     * Fires once when the entire queue completes successfully.
+     * Use to trigger work that must wait for all chained iframe submits
+     * (e.g. opening a bequest lightbox after QCB opt-ins are recorded).
+     */
+    get onChainComplete() {
+        return this._onChainComplete.asEvent();
+    }
+    /**
+     * Fires when the queue aborts due to an error (timeout, iframe load
+     * error, or error message from an embedded page). Carries the failed
+     * item (if known) and the underlying error.
+     */
+    get onChainError() {
+        return this._onChainError.asEvent();
+    }
+    /** Fires immediately before an item begins processing. */
+    get onItemStart() {
+        return this._onItemStart.asEvent();
+    }
+    /** Fires when an item completes (its iframe reached its Thank You page). */
+    get onItemComplete() {
+        return this._onItemComplete.asEvent();
+    }
+    /** Fires when an item fails. The queue aborts after this event. */
+    get onItemError() {
+        return this._onItemError.asEvent();
+    }
+    /** Internal — called by IframeQueue when the queue drains successfully. */
+    dispatchChainComplete() {
+        this.logger.log("dispatchChainComplete");
+        this._onChainComplete.dispatch();
+    }
+    /** Internal — called by IframeQueue when the queue aborts on error. */
+    dispatchChainError(payload) {
+        this.logger.log(`dispatchChainError: ${payload.message}`);
+        this._onChainError.dispatch(payload);
+    }
+    /** Internal — called by IframeQueue immediately before an item starts. */
+    dispatchItemStart(item) {
+        this.logger.log(`dispatchItemStart: ${item.url}`);
+        this._onItemStart.dispatch(item);
+    }
+    /** Internal — called by IframeQueue when an item finishes successfully. */
+    dispatchItemComplete(item) {
+        this.logger.log(`dispatchItemComplete: ${item.url}`);
+        this._onItemComplete.dispatch(item);
+    }
+    /** Internal — called by IframeQueue when an item errors. */
+    dispatchItemError(item, error) {
+        this.logger.log(`dispatchItemError: ${item.url} - ${error.message}`);
+        this._onItemError.dispatch({ item, error });
+    }
+}

package/dist/events/index.d.ts

@@ -3,4 +3,5 @@ export * from "./donation-amount";
 export * from "./donation-frequency";
 export * from "./processing-fees";
 export * from "./remember-me-events";
+export * from "./iframe-queue-events";
 export * from "./country";

package/dist/events/index.js

@@ -3,4 +3,5 @@ export * from "./donation-amount";
 export * from "./donation-frequency";
 export * from "./processing-fees";
 export * from "./remember-me-events";
+export * from "./iframe-queue-events";
 export * from "./country";

package/dist/iframe-queue.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Iframe Queue — load embedded EN pages sequentially.
+ *
+ * **This component is opt-in.** Like `OptInLadder`, it is exported from
+ * `@4site/engrid-scripts` but is **not** auto-constructed by ENgrid's
+ * core bootstrap (`app.ts`). To use it, instantiate it once in your
+ * theme's bootstrap:
+ *
+ * ```ts
+ * import { IframeQueue } from "@4site/engrid-scripts";
+ * new IframeQueue();
+ * ```
+ *
+ * On client themes that don't use this component, **nothing in this
+ * file runs**: no `message` listener is registered, no singleton is
+ * allocated, no bundle code beyond the unused class definition.
+ *
+ * **Why this exists.** Engaging Networks' platform handles concurrent
+ * iframe submissions inconsistently — when several embedded EN forms
+ * are submitted in parallel (e.g. QCB opt-ins for postal mail, mobile
+ * phone, and double opt-in email), roughly 40% of records are lost.
+ * Loading the iframes sequentially (without `?chain`) resolves the
+ * issue. This component generalises that pattern.
+ *
+ * **What it does.** In _parent_ mode (top-level page) it holds an
+ * ordered queue of {@link IframeQueueItem} configs and processes them
+ * one at a time: create iframe → wait for `load` → post a populate
+ * message with field values → wait for the embedded page to reach a
+ * Thank You page → advance. In _embedded_ mode (running inside an
+ * iframe owned by an IframeQueue parent) it listens for the populate
+ * message, fills the form fields via {@link ENGrid.setFieldValue}, and
+ * submits via {@link EnForm.submitForm} when `autoSubmit` is true.
+ *
+ * **Why not `?chain`?** Engaging Networks' `?chain` URL parameter is
+ * unreliable for sequential iframe submission; the agreed solution is
+ * to pass field data via `postMessage` instead. The queue defensively
+ * strips any `chain` query parameter from queued URLs.
+ *
+ * **Page ID matching.** The Thank-You-page ping (sent by the iFrame
+ * component, see iframe.ts) carries the Page ID of the submitting
+ * form. The queue compares it against the Page ID parsed from the
+ * queued URL so that pings from unrelated EN iframes on the same
+ * parent page (such as an Embedded Ecard iframe) are ignored.
+ *
+ * **Events.** Lifecycle events are dispatched via the
+ * {@link IframeQueueEvents} singleton. External code subscribes there
+ * rather than holding a reference to the queue itself.
+ *
+ * @example Programmatic API
+ *   const queue = IframeQueue.getInstance();
+ *   queue.enqueue({
+ *     url: "https://example.org/page/123/data/1",
+ *     fields: { "supporter.emailAddress": "donor@example.org" },
+ *     autoSubmit: true,
+ *   });
+ *   queue.process().then(() => console.log("done"));
+ *
+ * @example Declarative API (set on the EN page before the bundle loads)
+ *   window.EngridIframeQueue = {
+ *     items: [
+ *       { url: "https://example.org/page/123/data/1",
+ *         fields: { "supporter.emailAddress": "donor@example.org" } },
+ *     ],
+ *     autoStart: true,
+ *   };
+ */
+import { IframeQueueItem } from "./interfaces/iframe-queue-options";
+export declare class IframeQueue {
+    private static instance;
+    private logger;
+    private events;
+    private _form;
+    private queue;
+    private _isProcessing;
+    private _aborted;
+    private inFlightPromise;
+    /**
+     * Returns the shared IframeQueue singleton. The bootstrap in app.ts
+     * instantiates this once via `new IframeQueue()`, but consumers that
+     * need to enqueue items programmatically should always go through
+     * `getInstance()` so they share the same queue state.
+     */
+    static getInstance(): IframeQueue;
+    constructor();
+    /** Whether the queue is currently processing. */
+    get isProcessing(): boolean;
+    /** Number of items currently in the queue (not counting the in-flight item). */
+    get size(): number;
+    /**
+     * Add an item to the back of the queue. Items are processed in
+     * insertion order. Calling `enqueue` while the queue is processing is
+     * supported — the new item joins the chain and will be picked up
+     * after the current item completes.
+     */
+    enqueue(item: IframeQueueItem): void;
+    /**
+     * Add many items at once, preserving order. Equivalent to calling
+     * {@link enqueue} repeatedly.
+     */
+    enqueueAll(items: IframeQueueItem[]): void;
+    /**
+     * Begin processing the queue. Resolves when the queue drains
+     * successfully and rejects on the first error. If already processing,
+     * returns the in-flight promise so callers don't start a second drain.
+     */
+    process(): Promise<void>;
+    /**
+     * Empty the queue without processing. Stops the in-flight item if
+     * any (the in-flight item rejects with an abort error which is
+     * surfaced via `onChainError`).
+     */
+    clear(): void;
+    /**
+     * In parent mode the constructor checks `window.EngridIframeQueue`
+     * for declarative startup config, enqueues those items, and (if
+     * `autoStart` is true) calls `process()` after DOMContentLoaded.
+     */
+    private setupParentMode;
+    /**
+     * Reads `window.EngridIframeQueue` and returns merged options, or
+     * null if no valid config is present.
+     */
+    private readWindowConfig;
+    /** Process queued items strictly one at a time. */
+    private drain;
+    /**
+     * Process a single item: create the iframe, post populate, wait for
+     * the matching Thank-You ping (or error/timeout). Resolves on success
+     * and rejects on error/timeout.
+     */
+    private processItem;
+    /**
+     * Normalise the URL for a queued iframe:
+     *  1. Strip any `chain` query parameter defensively — the queue
+     *     replaces `?chain` with sequential processing.
+     *  2. Inherit a small allowlist of loader / dev-mode params (see
+     *     {@link PROPAGATED_PARENT_PARAMS}) when they're not already set
+     *     on the item URL. Each key is resolved with the same precedence
+     *     `loader.ts#getOption` uses: parent URL param first, then
+     *     `window.EngridLoader[key]`.
+     *
+     * Item-specified params always take precedence over inherited ones.
+     * Returns the original string unchanged if URL parsing fails.
+     */
+    private prepareIframeUrl;
+    /** Returns the parent page's URLSearchParams, or null on failure. */
+    private getParentSearchParams;
+    /**
+     * Returns the parent page's `window.EngridLoader` object if set, or
+     * null. Used by {@link prepareIframeUrl} as a fallback source for
+     * loader/dev-mode param values when EN has stripped URL parameters
+     * from the Thank You page.
+     */
+    private getParentEngridLoader;
+    /**
+     * Decide whether to leave a failed iframe in the DOM (for
+     * inspection) instead of removing it. True when the item explicitly
+     * asks for it via `keepIframeOnError`, OR whenever ENgrid debug
+     * mode is on (since debugging is when this is useful and we don't
+     * want to make consumers opt in just to inspect failures).
+     */
+    private shouldKeepIframeOnError;
+    /**
+     * Reposition and style a failed iframe so it's visible in the
+     * viewport (overriding the visually-hidden default), and tag it
+     * with a class + tooltip so the developer knows why it's there.
+     * Right-click the iframe → Inspect frame to dive in.
+     */
+    private markIframeFailed;
+    /** Create a hidden iframe element for a queue item. */
+    private createIframe;
+    /**
+     * In embedded mode we register a `message` listener that accepts
+     * populate messages from `window.parent`, fills form fields, and
+     * (optionally) submits. The Thank-You-page ping is sent by the iFrame
+     * component (iframe.ts) — not here — so this method does not need to
+     * concern itself with completion signalling.
+     */
+    private setupEmbeddedMode;
+    /** Handle a populate message sent by an IframeQueue parent. */
+    private handlePopulate;
+    /**
+     * Strip every "disabled" marker from the EN submit button so the
+     * programmatic `submitForm()` click is honoured. Removes:
+     *   - the `disabled` DOM property/attribute on the button,
+     *   - the `en__submit--disabled` BEM modifier (EN's own class),
+     *   - the `en__submit--disabled` modifier on the `.en__submit`
+     *     wrapper (some templates style the wrapper instead),
+     *   - ENgrid's own loader markup if a previous `disableSubmit()`
+     *     call left it in place.
+     *
+     * Used only by embedded-mode populate flow when `autoSubmit` is on.
+     */
+    private forceEnableSubmitButton;
+    /** True when this script is executing inside an iframe. */
+    private inIframe;
+}

package/dist/iframe-queue.js

@@ -0,0 +1,658 @@
+/**
+ * Iframe Queue — load embedded EN pages sequentially.
+ *
+ * **This component is opt-in.** Like `OptInLadder`, it is exported from
+ * `@4site/engrid-scripts` but is **not** auto-constructed by ENgrid's
+ * core bootstrap (`app.ts`). To use it, instantiate it once in your
+ * theme's bootstrap:
+ *
+ * ```ts
+ * import { IframeQueue } from "@4site/engrid-scripts";
+ * new IframeQueue();
+ * ```
+ *
+ * On client themes that don't use this component, **nothing in this
+ * file runs**: no `message` listener is registered, no singleton is
+ * allocated, no bundle code beyond the unused class definition.
+ *
+ * **Why this exists.** Engaging Networks' platform handles concurrent
+ * iframe submissions inconsistently — when several embedded EN forms
+ * are submitted in parallel (e.g. QCB opt-ins for postal mail, mobile
+ * phone, and double opt-in email), roughly 40% of records are lost.
+ * Loading the iframes sequentially (without `?chain`) resolves the
+ * issue. This component generalises that pattern.
+ *
+ * **What it does.** In _parent_ mode (top-level page) it holds an
+ * ordered queue of {@link IframeQueueItem} configs and processes them
+ * one at a time: create iframe → wait for `load` → post a populate
+ * message with field values → wait for the embedded page to reach a
+ * Thank You page → advance. In _embedded_ mode (running inside an
+ * iframe owned by an IframeQueue parent) it listens for the populate
+ * message, fills the form fields via {@link ENGrid.setFieldValue}, and
+ * submits via {@link EnForm.submitForm} when `autoSubmit` is true.
+ *
+ * **Why not `?chain`?** Engaging Networks' `?chain` URL parameter is
+ * unreliable for sequential iframe submission; the agreed solution is
+ * to pass field data via `postMessage` instead. The queue defensively
+ * strips any `chain` query parameter from queued URLs.
+ *
+ * **Page ID matching.** The Thank-You-page ping (sent by the iFrame
+ * component, see iframe.ts) carries the Page ID of the submitting
+ * form. The queue compares it against the Page ID parsed from the
+ * queued URL so that pings from unrelated EN iframes on the same
+ * parent page (such as an Embedded Ecard iframe) are ignored.
+ *
+ * **Events.** Lifecycle events are dispatched via the
+ * {@link IframeQueueEvents} singleton. External code subscribes there
+ * rather than holding a reference to the queue itself.
+ *
+ * @example Programmatic API
+ *   const queue = IframeQueue.getInstance();
+ *   queue.enqueue({
+ *     url: "https://example.org/page/123/data/1",
+ *     fields: { "supporter.emailAddress": "donor@example.org" },
+ *     autoSubmit: true,
+ *   });
+ *   queue.process().then(() => console.log("done"));
+ *
+ * @example Declarative API (set on the EN page before the bundle loads)
+ *   window.EngridIframeQueue = {
+ *     items: [
+ *       { url: "https://example.org/page/123/data/1",
+ *         fields: { "supporter.emailAddress": "donor@example.org" } },
+ *     ],
+ *     autoStart: true,
+ *   };
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ENGrid, EngridLogger } from ".";
+import { EnForm, IframeQueueEvents } from "./events";
+import { IframeQueueOptionsDefaults, } from "./interfaces/iframe-queue-options";
+/** Wire-format type for the populate message sent parent → iframe. */
+const MSG_POPULATE = "engrid-iframe-queue:populate";
+/** Wire-format type for the Thank-You-page ping sent iframe → parent. */
+const MSG_THANK_YOU = "engrid-iframe-queue:thank-you";
+/** Wire-format type for an error message sent iframe → parent. */
+const MSG_ERROR = "engrid-iframe-queue:error";
+/** Default per-item timeout in milliseconds. */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Parameters that are automatically inherited from the parent page
+ * onto each queued iframe URL. These are all ENgrid loader / dev-mode
+ * flags — adding them to the parent is meant to affect "the ENgrid
+ * bundle running on this browser tab," which conceptually includes
+ * the embedded forms loaded by the queue.
+ *
+ * For each key, the value is resolved with the same precedence used by
+ * `loader.ts#getOption`:
+ *   1. The item's own URL — if the consumer hard-coded the param on
+ *      the iframe URL, that wins.
+ *   2. The parent page's URL parameter (`?assets=local`).
+ *   3. `window.EngridLoader[key]` on the parent page — useful when EN
+ *      strips URL params on the Thank You page, so themes set
+ *      `<script>window.EngridLoader = { assets: 'local' };</script>`
+ *      to pin the bundle source.
+ *
+ * Notable use case: any of the three works for forcing local-asset
+ * loading on every queued QCB iframe during testing.
+ */
+const PROPAGATED_PARENT_PARAMS = [
+    "assets",
+    "engridjs",
+    "engridcss",
+    "repo-name",
+    "repo-owner",
+    "debug",
+    "mode",
+];
+/** Default visually-hidden style for queue iframes. */
+const DEFAULT_HIDDEN_STYLE = {
+    position: "absolute",
+    width: "1px",
+    height: "1px",
+    left: "-9999px",
+    top: "0",
+    opacity: "0",
+    border: "0",
+};
+export class IframeQueue {
+    /**
+     * Returns the shared IframeQueue singleton. The bootstrap in app.ts
+     * instantiates this once via `new IframeQueue()`, but consumers that
+     * need to enqueue items programmatically should always go through
+     * `getInstance()` so they share the same queue state.
+     */
+    static getInstance() {
+        if (!IframeQueue.instance) {
+            IframeQueue.instance = new IframeQueue();
+        }
+        return IframeQueue.instance;
+    }
+    constructor() {
+        this.logger = new EngridLogger("IframeQueue", "white", "#1f6feb", "🚂");
+        this.events = IframeQueueEvents.getInstance();
+        this._form = EnForm.getInstance();
+        this.queue = [];
+        this._isProcessing = false;
+        this._aborted = false;
+        this.inFlightPromise = null;
+        // Singleton guard: if called via `new IframeQueue()` after an
+        // instance already exists (e.g. by app.ts), return the existing
+        // instance so behaviour stays consistent with `getInstance()`.
+        if (IframeQueue.instance) {
+            return IframeQueue.instance;
+        }
+        IframeQueue.instance = this;
+        if (this.inIframe()) {
+            this.setupEmbeddedMode();
+        }
+        else {
+            this.setupParentMode();
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Public API (parent mode)
+    // ---------------------------------------------------------------------------
+    /** Whether the queue is currently processing. */
+    get isProcessing() {
+        return this._isProcessing;
+    }
+    /** Number of items currently in the queue (not counting the in-flight item). */
+    get size() {
+        return this.queue.length;
+    }
+    /**
+     * Add an item to the back of the queue. Items are processed in
+     * insertion order. Calling `enqueue` while the queue is processing is
+     * supported — the new item joins the chain and will be picked up
+     * after the current item completes.
+     */
+    enqueue(item) {
+        if (!item || typeof item.url !== "string" || !item.url) {
+            this.logger.danger("enqueue() called with invalid item; ignoring");
+            return;
+        }
+        this.queue.push(item);
+        this.logger.log(`enqueue: ${item.url} (queue size = ${this.queue.length})`);
+    }
+    /**
+     * Add many items at once, preserving order. Equivalent to calling
+     * {@link enqueue} repeatedly.
+     */
+    enqueueAll(items) {
+        if (!Array.isArray(items))
+            return;
+        for (const item of items)
+            this.enqueue(item);
+    }
+    /**
+     * Begin processing the queue. Resolves when the queue drains
+     * successfully and rejects on the first error. If already processing,
+     * returns the in-flight promise so callers don't start a second drain.
+     */
+    process() {
+        if (this._isProcessing && this.inFlightPromise) {
+            this.logger.log("process: already processing; returning in-flight promise");
+            return this.inFlightPromise;
+        }
+        if (this.queue.length === 0) {
+            this.logger.log("process: queue empty; nothing to do");
+            return Promise.resolve();
+        }
+        this._aborted = false;
+        this._isProcessing = true;
+        this.inFlightPromise = this.drain()
+            .then(() => {
+            this.events.dispatchChainComplete();
+        })
+            .finally(() => {
+            this._isProcessing = false;
+            this.inFlightPromise = null;
+        });
+        return this.inFlightPromise;
+    }
+    /**
+     * Empty the queue without processing. Stops the in-flight item if
+     * any (the in-flight item rejects with an abort error which is
+     * surfaced via `onChainError`).
+     */
+    clear() {
+        this.logger.log(`clear: dropping ${this.queue.length} queued item(s)`);
+        this.queue = [];
+        this._aborted = true;
+    }
+    // ---------------------------------------------------------------------------
+    // Parent-mode internals
+    // ---------------------------------------------------------------------------
+    /**
+     * In parent mode the constructor checks `window.EngridIframeQueue`
+     * for declarative startup config, enqueues those items, and (if
+     * `autoStart` is true) calls `process()` after DOMContentLoaded.
+     */
+    setupParentMode() {
+        this.logger.log("setupParentMode");
+        const config = this.readWindowConfig();
+        if (!config)
+            return;
+        if (Array.isArray(config.items) && config.items.length > 0) {
+            this.enqueueAll(config.items);
+        }
+        const shouldAutoStart = typeof config.autoStart === "boolean"
+            ? config.autoStart
+            : this.queue.length > 0;
+        if (!shouldAutoStart || this.queue.length === 0)
+            return;
+        const start = () => {
+            this.process().catch((err) => {
+                this.logger.danger(`Auto-started queue rejected: ${err}`);
+            });
+        };
+        if (document.readyState !== "loading") {
+            start();
+        }
+        else {
+            document.addEventListener("DOMContentLoaded", start);
+        }
+    }
+    /**
+     * Reads `window.EngridIframeQueue` and returns merged options, or
+     * null if no valid config is present.
+     */
+    readWindowConfig() {
+        const raw = window
+            .EngridIframeQueue;
+        if (!raw || typeof raw !== "object")
+            return null;
+        return Object.assign(Object.assign({}, IframeQueueOptionsDefaults), raw);
+    }
+    /** Process queued items strictly one at a time. */
+    drain() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            while (this.queue.length > 0) {
+                if (this._aborted) {
+                    this.logger.log("drain: aborted; stopping");
+                    return;
+                }
+                const item = this.queue.shift();
+                try {
+                    yield this.processItem(item);
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    this.events.dispatchItemError(item, error);
+                    try {
+                        (_a = item.onError) === null || _a === void 0 ? void 0 : _a.call(item, error);
+                    }
+                    catch (cbErr) {
+                        this.logger.danger(`onError callback threw: ${cbErr}`);
+                    }
+                    this.events.dispatchChainError({
+                        message: error.message,
+                        failedItem: item,
+                        cause: error,
+                    });
+                    // Abort the rest of the chain.
+                    this.queue = [];
+                    throw error;
+                }
+            }
+        });
+    }
+    /**
+     * Process a single item: create the iframe, post populate, wait for
+     * the matching Thank-You ping (or error/timeout). Resolves on success
+     * and rejects on error/timeout.
+     */
+    processItem(item) {
+        return new Promise((resolve, reject) => {
+            var _a, _b;
+            const url = this.prepareIframeUrl(item.url);
+            const expectedPageId = ENGrid.getPageIdFromUrl(url);
+            if (!expectedPageId) {
+                reject(new Error(`IframeQueue: could not parse Page ID from URL "${item.url}".`));
+                return;
+            }
+            this.events.dispatchItemStart(item);
+            const container = (_a = item.container) !== null && _a !== void 0 ? _a : document.body;
+            const iframe = this.createIframe(url, item.iframeStyle);
+            const timeoutMs = (_b = item.timeout) !== null && _b !== void 0 ? _b : DEFAULT_TIMEOUT_MS;
+            let settled = false;
+            let timeoutId = null;
+            const detachListeners = () => {
+                if (timeoutId !== null) {
+                    window.clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                window.removeEventListener("message", onMessage);
+                iframe.removeEventListener("load", onIframeLoad);
+                iframe.removeEventListener("error", onIframeError);
+            };
+            const removeIframe = () => {
+                if (iframe.parentNode) {
+                    iframe.parentNode.removeChild(iframe);
+                }
+            };
+            const succeed = () => {
+                var _a;
+                if (settled)
+                    return;
+                settled = true;
+                detachListeners();
+                removeIframe();
+                this.events.dispatchItemComplete(item);
+                try {
+                    (_a = item.onComplete) === null || _a === void 0 ? void 0 : _a.call(item);
+                }
+                catch (cbErr) {
+                    this.logger.danger(`onComplete callback threw: ${cbErr}`);
+                }
+                resolve();
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                detachListeners();
+                if (this.shouldKeepIframeOnError(item)) {
+                    this.markIframeFailed(iframe, error);
+                    this.logger.danger(`Item failed — iframe kept in DOM for inspection: ${error.message}`);
+                }
+                else {
+                    removeIframe();
+                }
+                reject(error);
+            };
+            const onMessage = (event) => {
+                var _a;
+                // Only accept messages from this specific iframe — origin
+                // string matching is unreliable because EN may serve embedded
+                // pages from different subdomains. `event.source` identity is
+                // what matters here.
+                if (event.source !== iframe.contentWindow)
+                    return;
+                const data = event.data;
+                if (!data || typeof data !== "object" || !data.type)
+                    return;
+                if (data.type === MSG_THANK_YOU) {
+                    if (data.pageId !== expectedPageId) {
+                        this.logger.log(`Ignoring thank-you ping with mismatched pageId ` +
+                            `(expected ${expectedPageId}, got ${data.pageId})`);
+                        return;
+                    }
+                    this.logger.log(`Item complete: ${url} (pageId ${expectedPageId})`);
+                    succeed();
+                }
+                else if (data.type === MSG_ERROR) {
+                    if (data.pageId !== expectedPageId)
+                        return;
+                    fail(new Error(`IframeQueue: embedded page reported error: ${(_a = data.message) !== null && _a !== void 0 ? _a : "unknown error"}`));
+                }
+            };
+            const onIframeLoad = () => {
+                var _a, _b;
+                if (settled)
+                    return;
+                const populate = {
+                    type: MSG_POPULATE,
+                    pageId: expectedPageId,
+                    fields: (_a = item.fields) !== null && _a !== void 0 ? _a : {},
+                    autoSubmit: item.autoSubmit !== false, // default true
+                };
+                this.logger.log(`Posting populate to iframe (pageId=${expectedPageId}, ` +
+                    `fieldCount=${Object.keys(populate.fields).length}, ` +
+                    `autoSubmit=${populate.autoSubmit})`);
+                // Use "*" for the same reason origin matching is skipped on
+                // inbound messages — EN may serve embedded pages from a
+                // different subdomain than the host page.
+                (_b = iframe.contentWindow) === null || _b === void 0 ? void 0 : _b.postMessage(populate, "*");
+            };
+            const onIframeError = () => {
+                fail(new Error(`IframeQueue: iframe failed to load: ${url}`));
+            };
+            window.addEventListener("message", onMessage);
+            iframe.addEventListener("load", onIframeLoad);
+            iframe.addEventListener("error", onIframeError);
+            timeoutId = window.setTimeout(() => {
+                fail(new Error(`IframeQueue: timed out after ${timeoutMs}ms waiting for ` +
+                    `Thank-You-page ping from ${url}`));
+            }, timeoutMs);
+            this.logger.log(`Item start: ${url} (pageId ${expectedPageId}, timeout ${timeoutMs}ms)`);
+            container.appendChild(iframe);
+        });
+    }
+    /**
+     * Normalise the URL for a queued iframe:
+     *  1. Strip any `chain` query parameter defensively — the queue
+     *     replaces `?chain` with sequential processing.
+     *  2. Inherit a small allowlist of loader / dev-mode params (see
+     *     {@link PROPAGATED_PARENT_PARAMS}) when they're not already set
+     *     on the item URL. Each key is resolved with the same precedence
+     *     `loader.ts#getOption` uses: parent URL param first, then
+     *     `window.EngridLoader[key]`.
+     *
+     * Item-specified params always take precedence over inherited ones.
+     * Returns the original string unchanged if URL parsing fails.
+     */
+    prepareIframeUrl(rawUrl) {
+        let url;
+        try {
+            url = new URL(rawUrl, window.location.href);
+        }
+        catch (_a) {
+            return rawUrl;
+        }
+        url.searchParams.delete("chain");
+        const parentUrlParams = this.getParentSearchParams();
+        const parentLoader = this.getParentEngridLoader();
+        const inherited = [];
+        for (const key of PROPAGATED_PARENT_PARAMS) {
+            if (url.searchParams.has(key))
+                continue;
+            let value = null;
+            let source = "";
+            if (parentUrlParams) {
+                const v = parentUrlParams.get(key);
+                if (v !== null) {
+                    value = v;
+                    source = "url";
+                }
+            }
+            if (value === null && parentLoader) {
+                const v = parentLoader[key];
+                if (typeof v === "string" && v !== "") {
+                    value = v;
+                    source = "EngridLoader";
+                }
+            }
+            if (value !== null) {
+                url.searchParams.set(key, value);
+                inherited.push(`${key}=${value} (from parent ${source})`);
+            }
+        }
+        if (inherited.length > 0) {
+            this.logger.log(`Inherited parent params on iframe URL: ${inherited.join(", ")}`);
+        }
+        return url.href;
+    }
+    /** Returns the parent page's URLSearchParams, or null on failure. */
+    getParentSearchParams() {
+        try {
+            return new URL(window.location.href).searchParams;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * Returns the parent page's `window.EngridLoader` object if set, or
+     * null. Used by {@link prepareIframeUrl} as a fallback source for
+     * loader/dev-mode param values when EN has stripped URL parameters
+     * from the Thank You page.
+     */
+    getParentEngridLoader() {
+        const w = window;
+        if (!w.EngridLoader || typeof w.EngridLoader !== "object")
+            return null;
+        return w.EngridLoader;
+    }
+    /**
+     * Decide whether to leave a failed iframe in the DOM (for
+     * inspection) instead of removing it. True when the item explicitly
+     * asks for it via `keepIframeOnError`, OR whenever ENgrid debug
+     * mode is on (since debugging is when this is useful and we don't
+     * want to make consumers opt in just to inspect failures).
+     */
+    shouldKeepIframeOnError(item) {
+        if (item.keepIframeOnError)
+            return true;
+        try {
+            return ENGrid.debug === true;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+    /**
+     * Reposition and style a failed iframe so it's visible in the
+     * viewport (overriding the visually-hidden default), and tag it
+     * with a class + tooltip so the developer knows why it's there.
+     * Right-click the iframe → Inspect frame to dive in.
+     */
+    markIframeFailed(iframe, error) {
+        Object.assign(iframe.style, {
+            position: "fixed",
+            top: "10px",
+            right: "10px",
+            bottom: "auto",
+            left: "auto",
+            width: "min(600px, 90vw)",
+            height: "min(500px, 80vh)",
+            opacity: "1",
+            zIndex: "99999",
+            border: "3px solid #d33",
+            background: "white",
+            boxShadow: "0 4px 24px rgba(0, 0, 0, 0.25)",
+        });
+        iframe.classList.add("engrid-iframe--queue-failed");
+        iframe.title = `Iframe Queue: failed item — ${error.message}`;
+    }
+    /** Create a hidden iframe element for a queue item. */
+    createIframe(url, styleOverride) {
+        const iframe = document.createElement("iframe");
+        iframe.setAttribute("src", url);
+        iframe.setAttribute("frameborder", "0");
+        iframe.setAttribute("scrolling", "no");
+        iframe.setAttribute("aria-hidden", "true");
+        iframe.setAttribute("title", "ENgrid Iframe Queue");
+        iframe.classList.add("engrid-iframe", "engrid-iframe--queue");
+        const style = Object.assign(Object.assign({}, DEFAULT_HIDDEN_STYLE), (styleOverride !== null && styleOverride !== void 0 ? styleOverride : {}));
+        Object.assign(iframe.style, style);
+        return iframe;
+    }
+    // ---------------------------------------------------------------------------
+    // Embedded-mode internals
+    // ---------------------------------------------------------------------------
+    /**
+     * In embedded mode we register a `message` listener that accepts
+     * populate messages from `window.parent`, fills form fields, and
+     * (optionally) submits. The Thank-You-page ping is sent by the iFrame
+     * component (iframe.ts) — not here — so this method does not need to
+     * concern itself with completion signalling.
+     */
+    setupEmbeddedMode() {
+        this.logger.log("setupEmbeddedMode");
+        window.addEventListener("message", (event) => {
+            if (event.source !== window.parent)
+                return;
+            const data = event.data;
+            if (!data || typeof data !== "object" || data.type !== MSG_POPULATE) {
+                return;
+            }
+            this.handlePopulate(data);
+        });
+    }
+    /** Handle a populate message sent by an IframeQueue parent. */
+    handlePopulate(data) {
+        var _a, _b;
+        const fields = (_a = data.fields) !== null && _a !== void 0 ? _a : {};
+        const autoSubmit = data.autoSubmit !== false;
+        this.logger.log(`Received populate (pageId=${data.pageId}, ` +
+            `fieldCount=${Object.keys(fields).length}, autoSubmit=${autoSubmit})`);
+        try {
+            for (const [name, value] of Object.entries(fields)) {
+                // Pass `dispatchEvents = true` so each field fires
+                // `change` + `blur` after the value is set. Without that,
+                // EN's form-validation state machine doesn't see the new
+                // values and leaves `en__submit--disabled` on the submit
+                // button, causing the auto-click below to no-op.
+                ENGrid.setFieldValue(name, value, true, true);
+            }
+            if (autoSubmit) {
+                // Defer slightly so any synchronous EN dependency parsing in
+                // setFieldValue settles before the form is submitted.
+                window.setTimeout(() => {
+                    // Belt-and-braces: clear EN's "submit disabled" state in
+                    // case its validators didn't re-evaluate (e.g. async
+                    // validators that hadn't completed when the events fired).
+                    this.forceEnableSubmitButton();
+                    this._form.submitForm();
+                }, 0);
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.logger.danger(`handlePopulate failed: ${error.message}`);
+            window.parent.postMessage({
+                type: MSG_ERROR,
+                pageId: (_b = data.pageId) !== null && _b !== void 0 ? _b : ENGrid.getPageID(),
+                message: error.message,
+            }, "*");
+        }
+    }
+    /**
+     * Strip every "disabled" marker from the EN submit button so the
+     * programmatic `submitForm()` click is honoured. Removes:
+     *   - the `disabled` DOM property/attribute on the button,
+     *   - the `en__submit--disabled` BEM modifier (EN's own class),
+     *   - the `en__submit--disabled` modifier on the `.en__submit`
+     *     wrapper (some templates style the wrapper instead),
+     *   - ENgrid's own loader markup if a previous `disableSubmit()`
+     *     call left it in place.
+     *
+     * Used only by embedded-mode populate flow when `autoSubmit` is on.
+     */
+    forceEnableSubmitButton() {
+        const button = document.querySelector("form .en__submit button");
+        if (button) {
+            if (button.disabled)
+                button.disabled = false;
+            button.removeAttribute("disabled");
+            button.classList.remove("en__submit--disabled");
+        }
+        const wrapper = document.querySelector(".en__submit");
+        if (wrapper) {
+            wrapper.classList.remove("en__submit--disabled");
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    /** True when this script is executing inside an iframe. */
+    inIframe() {
+        try {
+            return window.self !== window.top;
+        }
+        catch (_a) {
+            return true;
+        }
+    }
+}

package/dist/iframe.d.ts

@@ -4,6 +4,22 @@ export declare class iFrame {
     private logger;
     constructor();
     private onLoaded;
+    /**
+     * Posts a `engrid-iframe-queue:thank-you` message to the parent window
+     * when the embedded EN page reaches its Thank You page (the last page
+     * in the page sequence). Carries the Page ID of the submitting form so
+     * the IframeQueue parent can match the ping against the queued item it
+     * is waiting on, ignoring pings from unrelated EN iframes that may exist
+     * on the same parent page (e.g. an Embedded Ecard iframe).
+     *
+     * Only fires when:
+     *   - the script is running inside an iframe (already guaranteed by the
+     *     code path that calls onLoaded()), AND
+     *   - the embedded page is a Thank You page (ENGrid.isThankYouPage()).
+     *
+     * Consumed by: IframeQueue (engrid/packages/scripts/src/iframe-queue.ts).
+     */
+    private sendIframeQueueThankYouPing;
     private sendIframeHeight;
     private sendIframeFormStatus;
     private getIFrameByEvent;

package/dist/iframe.js

@@ -137,6 +137,11 @@ export class iFrame {
         window.parent.postMessage({
             scroll: this.shouldScroll(),
         }, "*");
+        // Iframe Queue: signal Thank-You-page completion to the parent window.
+        // The IframeQueue component (in parent mode) listens for this ping and
+        // matches it by Page ID to advance to the next queued iframe. Fires
+        // exactly once per Thank-You-page load. See iframe-queue.ts.
+        this.sendIframeQueueThankYouPing();
         // On click fire the resize event
         document.addEventListener("click", (e) => {
             this.logger.log("iFrame Event - click");
@@ -147,6 +152,35 @@ export class iFrame {
         // Watch for errors and send the height
         ENGrid.watchForError(this.sendIframeHeight.bind(this));
     }
+    /**
+     * Posts a `engrid-iframe-queue:thank-you` message to the parent window
+     * when the embedded EN page reaches its Thank You page (the last page
+     * in the page sequence). Carries the Page ID of the submitting form so
+     * the IframeQueue parent can match the ping against the queued item it
+     * is waiting on, ignoring pings from unrelated EN iframes that may exist
+     * on the same parent page (e.g. an Embedded Ecard iframe).
+     *
+     * Only fires when:
+     *   - the script is running inside an iframe (already guaranteed by the
+     *     code path that calls onLoaded()), AND
+     *   - the embedded page is a Thank You page (ENGrid.isThankYouPage()).
+     *
+     * Consumed by: IframeQueue (engrid/packages/scripts/src/iframe-queue.ts).
+     */
+    sendIframeQueueThankYouPing() {
+        if (!ENGrid.isThankYouPage())
+            return;
+        const pageId = ENGrid.getPageID();
+        const message = {
+            type: "engrid-iframe-queue:thank-you",
+            pageId,
+            pageNumber: ENGrid.getPageNumber(),
+            pageCount: ENGrid.getPageCount(),
+            url: window.location.href,
+        };
+        this.logger.log(`iFrame Event - Iframe Queue thank-you ping (pageId=${pageId})`);
+        window.parent.postMessage(message, "*");
+    }
     sendIframeHeight() {
         let height = document.body.offsetHeight;
         this.logger.log("iFrame Event - Sending iFrame height of: " + height + "px"); // check the message is being sent correctly

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { UpsellOptions, UpsellOptionsDefaults, } from "./interfaces/upsell-optio
 export { TranslateOptions, TranslateOptionsDefaults, } from "./interfaces/translate-options";
 export { ExitIntentOptions, ExitIntentOptionsDefaults, } from "./interfaces/exit-intent-options";
 export { FrequencyUpsellOptions, FrequencyUpsellOptionsDefaults, FrequencyUpsellABTestConfig, FrequencyUpsellConfig, } from "./interfaces/frequency-upsell-options";
+export { IframeQueueOptions, IframeQueueOptionsDefaults, IframeQueueItem, IframeQueueErrorPayload, } from "./interfaces/iframe-queue-options";
 export * from "./loader";
 export * from "./app";
 export * from "./amount-label";
@@ -18,6 +19,7 @@ export * from "./click-to-expand";
 export * from "./advocacy";
 export * from "./data-attributes";
 export * from "./iframe";
+export * from "./iframe-queue";
 export * from "./input-has-value-and-focus";
 export * from "./input-placeholders";
 export * from "./media-attribution";

package/dist/index.js

@@ -4,6 +4,7 @@ export { UpsellOptionsDefaults, } from "./interfaces/upsell-options";
 export { TranslateOptionsDefaults, } from "./interfaces/translate-options";
 export { ExitIntentOptionsDefaults, } from "./interfaces/exit-intent-options";
 export { FrequencyUpsellOptionsDefaults, } from "./interfaces/frequency-upsell-options";
+export { IframeQueueOptionsDefaults, } from "./interfaces/iframe-queue-options";
 export * from "./loader";
 export * from "./app";
 export * from "./amount-label";
@@ -18,6 +19,7 @@ export * from "./click-to-expand";
 export * from "./advocacy";
 export * from "./data-attributes";
 export * from "./iframe";
+export * from "./iframe-queue";
 export * from "./input-has-value-and-focus";
 export * from "./input-placeholders";
 export * from "./media-attribution";

package/dist/interfaces/iframe-queue-options.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Configuration interfaces for the Iframe Queue component.
+ *
+ * The Iframe Queue loads a sequence of embedded Engaging Networks pages
+ * one at a time, passes field values into them via `postMessage`, and
+ * exposes a global `IframeQueueEvents` instance so external code can
+ * subscribe to chain-completion. See iframe-queue.ts for the component.
+ *
+ * Configuration may be supplied either programmatically (via
+ * `IframeQueue.getInstance().enqueue(...).process()`) or declaratively
+ * by setting `window.EngridIframeQueue` on the host EN page before
+ * the ENgrid bundle loads.
+ */
+/**
+ * A single embedded EN page to load and submit as part of the queue.
+ *
+ * The queue creates an iframe for each item, posts an
+ * `engrid-iframe-queue:populate` message to the iframe with the
+ * item's `fields`, and waits for an `engrid-iframe-queue:thank-you`
+ * ping (sent by the iFrame component on the embedded Thank You page)
+ * before advancing to the next item.
+ */
+export interface IframeQueueItem {
+    /**
+     * Full URL of the EN page to load. The queue strips any `chain` query
+     * parameter defensively; do not rely on `?chain` for data passing.
+     */
+    url: string;
+    /**
+     * Field name → value pairs to populate in the embedded form via
+     * postMessage. Field names match the `name` attribute of the EN form
+     * input (e.g. `supporter.emailAddress`).
+     */
+    fields?: Record<string, string>;
+    /**
+     * If true, the embedded iframe submits the form once fields are
+     * populated. Default: true.
+     */
+    autoSubmit?: boolean;
+    /**
+     * Maximum time (ms) to wait for the Thank-You-page ping before
+     * treating the item as failed and aborting the queue. Default: 30000.
+     */
+    timeout?: number;
+    /**
+     * Element to append the iframe to. Default: document.body.
+     */
+    container?: HTMLElement;
+    /**
+     * Override iframe styles. Default: visually hidden
+     * (position:absolute; width:1px; height:1px; left:-9999px; opacity:0;).
+     */
+    iframeStyle?: Partial<CSSStyleDeclaration>;
+    /**
+     * Optional per-item callback fired when the item completes
+     * successfully. Useful for ad-hoc consumers that don't want to
+     * subscribe to the global IframeQueueEvents singleton.
+     */
+    onComplete?: () => void;
+    /**
+     * Optional per-item callback fired when the item fails (timeout,
+     * iframe load error, or message error from the embedded page).
+     */
+    onError?: (error: Error) => void;
+    /**
+     * If true, when this item fails (timeout / load error / embedded
+     * error message) the queue does NOT remove the iframe from the DOM
+     * and instead repositions it as a visible, framed overlay so a
+     * developer can inspect it (right-click → Inspect frame, view its
+     * console, etc.). Default: false.
+     *
+     * Independent of this flag, failed iframes are also kept and made
+     * visible automatically whenever ENgrid debug mode is on
+     * (`window.EngridOptions.Debug === true` or `?debug=true`).
+     */
+    keepIframeOnError?: boolean;
+}
+/**
+ * Payload dispatched by `IframeQueueEvents.onChainError` when the queue
+ * aborts due to an error. `failedItem` may be undefined if the error
+ * occurred before any item started processing.
+ */
+export interface IframeQueueErrorPayload {
+    message: string;
+    failedItem?: IframeQueueItem;
+    cause?: Error;
+}
+/**
+ * Declarative configuration set on `window.EngridIframeQueue` to
+ * preload items and optionally auto-start the queue at page load.
+ */
+export interface IframeQueueOptions {
+    /** Items to enqueue at startup. */
+    items?: IframeQueueItem[];
+    /**
+     * Whether to call `process()` automatically once items are enqueued
+     * at startup. Default: true if `items` is non-empty, else false.
+     */
+    autoStart?: boolean;
+}
+export declare const IframeQueueOptionsDefaults: IframeQueueOptions;

package/dist/interfaces/iframe-queue-options.js

@@ -0,0 +1,17 @@
+/**
+ * Configuration interfaces for the Iframe Queue component.
+ *
+ * The Iframe Queue loads a sequence of embedded Engaging Networks pages
+ * one at a time, passes field values into them via `postMessage`, and
+ * exposes a global `IframeQueueEvents` instance so external code can
+ * subscribe to chain-completion. See iframe-queue.ts for the component.
+ *
+ * Configuration may be supplied either programmatically (via
+ * `IframeQueue.getInstance().enqueue(...).process()`) or declaratively
+ * by setting `window.EngridIframeQueue` on the host EN page before
+ * the ENgrid bundle loads.
+ */
+export const IframeQueueOptionsDefaults = {
+    items: [],
+    autoStart: true,
+};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const AppVersion = "0.25.1";
+export declare const AppVersion = "0.25.2";

package/dist/version.js

@@ -1 +1 @@
-export const AppVersion = "0.25.1";
+export const AppVersion = "0.25.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4site/engrid-scripts",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "description": "Scripts for the ENGRID Project",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,7 +25,7 @@
     "strongly-typed-events": "^2.0.9"
   },
   "homepage": "https://github.com/4site-interactive-studios/engrid#readme",
-  "gitHead": "408f1d5237c46b5d530347056a2adedab3913739",
+  "gitHead": "9ca2921968167be0cea2cfdbb35a85109e9d46bc",
   "devDependencies": {
     "nodemon": "^2.0.20"
   }