@salla.sa/twilight-components 3.0.24 → 3.0.25

package/dist/collection/components/salla-conditional-offer/salla-conditional-offer.js

@@ -3,7 +3,7 @@
  */
 import { Host, h } from "@stencil/core";
 import { DiscountType, OfferType, } from "./interfaces";
-import { getCartFreeGiftItems, getCartItemCount, hasAuthoritativeCartData, refreshCartFreeGifts, } from "../../shared/cart-free-gifts";
+import { getCartFreeGiftItems, getCartItemCount, getCartProductLines, hasAuthoritativeCartData, refreshCartFreeGifts, } from "../../shared/cart-free-gifts";
 import { CART_UPDATE_COALESCE_MS } from "./cart-update-window";
 import { NO_STAGE_REACHED, OfferStageMeasure, computeOfferStageProgress, getRemainingToStage, isUsableThreshold, sortByThreshold, } from "../../shared/offer-stages";
 /** Root of every translation key this component uses. */
@@ -69,6 +69,19 @@ const RELOCATION_ANCESTOR_LIMIT = 3;
  * DOM with no cart in it. Past this deadline the full-width banner is the final answer.
  */
 const RELOCATION_WATCH_MS = 5000;
+/**
+ * CP-2171 — how long the picker stays locked after an add succeeded when no fresh cart
+ * lines arrive (a missed `cart::updated`). Long enough to cover the coalescing window and the
+ * cart lookup; short enough that a lost event never leaves Add ignoring taps for long. Past it
+ * the lock goes and the lines are read again — see `unlockOnStaleLines`.
+ */
+const FREE_PRODUCT_UNLOCK_FALLBACK_MS = 5000;
+/** CP-2171 — how long the cart page fetch for new lines may take before falling back to a reload. */
+const CART_PAGE_FETCH_TIMEOUT_MS = 8000;
+/** `sessionStorage` key of the cart page reload guard (see `reloadForMissingCartLines`). */
+const CART_PAGE_RELOAD_KEY = 'salla-conditional-offer:reloaded-for';
+/** A theme's cart line forms. Product option forms (`.cart-options`) carry an `item-` id too, but are not lines. */
+const CART_LINE_FORMS = 'form[id^="item-"]:not(.cart-options form)';
 /**
  * Clear space kept between the ⓘ popover and the viewport edge when it is nudged back
  * inside. Purely cosmetic — one gutter, both edges, both directions.
@@ -101,10 +114,32 @@ const EN_FALLBACKS = {
     details_title: 'Offer details',
     free_gift: 'Free Gift',
     free_products_title: 'Free products selected from the offer',
+    // CP-5033 — the gift tier is reached but none of its gifts can be added.
+    free_products_unavailable: 'The free products are currently unavailable',
+    // CP-2171 — the free product picker.
+    free_products_choose: 'Choose :count free products',
+    // Its own key, not :count = 2: Arabic uses the dual form, with no number.
+    free_products_choose_two: 'Choose 2 free products',
+    free_product_choose_one: 'Choose your free product',
+    // The banner line at the gift tier: "…Choose it/them now" while no gift is picked yet, then
+    // the plain line once one is. Same one / two / :count split as the picker title.
+    free_product_got_one: 'You got a free product',
+    free_product_got_pick_one: 'You got a free product! Choose it now',
+    free_products_got: 'You got :count free products',
+    free_products_got_pick: 'You got :count free products! Choose them now',
+    free_products_got_pick_two: 'You got 2 free products! Choose them now',
+    free_products_got_two: 'You got 2 free products',
+    // A picker tier's reward in "Add :remaining and get :reward" and the tooltip rows, instead of
+    // the server's count-less "Free Gift". Same one / two / :count split.
+    free_product_reward_one: 'a free product',
+    free_products_reward: ':count free products',
+    free_products_reward_two: '2 free products',
     guidance_conditions_unmet: 'Your cart doesn’t meet the conditions for the next reward yet',
     guidance_next: 'Add :remaining and get :reward',
     guidance_next_generic: 'Add :remaining to unlock the next reward',
     manage_offer: 'Manage offer',
+    // The picker's toggle. Its own key, so offers without a picker keep master's "Manage offer".
+    offer_toggle: 'Offer',
     tier_requirement: 'Spend :threshold and get :reward',
     tier_requirement_count: 'Buy :threshold and get :reward',
     tier_requirement_count_generic: 'Buy :threshold to unlock this offer',
@@ -114,6 +149,15 @@ const EN_FALLBACKS = {
 /** The gift price label reuses the platform's existing "free of charge" string. */
 const FREE_LABEL_KEY = 'pages.checkout.free_charge';
 const FREE_LABEL_FALLBACK = 'Free';
+/**
+ * CP-2171 — the picker's add label is the platform's shared "Add", not a cart-offer key of its
+ * own: the dictionaries keep one string per meaning.
+ */
+const ADD_LABEL_KEY = 'common.elements.add';
+const ADD_LABEL_FALLBACK = 'Add';
+// The "Free products" panel title reuses the loyalty program's existing "Free products".
+const FREE_PRODUCTS_TITLE_KEY = 'pages.loyalty_program.free_product_title';
+const FREE_PRODUCTS_TITLE_FALLBACK = 'Free products';
 /**
  * Escape a merchant-controlled string before it is substituted into a translation
  * template that we then render with `innerHTML`.
@@ -219,6 +263,37 @@ export class SallaConditionalOffer {
         this.canRender = true;
         /** Free-gift cart LINES belonging to this offer — the "ادارة العرض" card. */
         this.gifts = [];
+        /** CP-2171 — every cart line (paid and free), for the picker's per-product state. */
+        this.cartLines = [];
+        /**
+         * CP-2171 — whether `cartLines` came from a cart lookup that answered. Until then the
+         * lines are `[]`: the "Free products" panel and the gift-pick banner line wait for it.
+         */
+        this.cartLinesLoaded = false;
+        /** CP-2171 — the picker's product cards, keyed by ENCODED product id. */
+        this.freeProductCards = {};
+        /**
+         * CP-2171 — the product (encoded id) an add is in flight for. Held until cart lines read
+         * AFTER the add arrive, not just until the request ends: the cart refresh starts only after
+         * the coalescing window, and a tap in between is ignored, so a double tap adds one unit.
+         */
+        this.pendingFreeProduct = null;
+        /** `giftsGeneration` when the pending change succeeded; a cart load started after it unlocks. */
+        this.pendingFreeProductSettledAt = null;
+        this.pendingFreeProductTimer = null;
+        /**
+         * `giftsGeneration` when an add from the picker succeeded: the first cart lines read after it
+         * are checked against the page (see `showMissingCartLines`). Kept apart from the
+         * button lock on purpose: the lock's fallback can fire before those lines arrive, and the
+         * page still has to show the new line when they do.
+         */
+        this.cartPageCheckAfter = null;
+        /** A cart page fetch for missing lines is in flight; lines read meanwhile wait in `pendingCartPageLines`. */
+        this.insertingCartLines = false;
+        this.pendingCartPageLines = null;
+        /** Re-reads of the cart after a failed lookup while a picker change waits; see `retryPickerCartLookup`. */
+        this.pickerLookupRetries = 0;
+        this.pickerLookupTimer = null;
         /**
          * How many LINES the cart holds — `null` while that is genuinely UNKNOWN.
          *
@@ -484,6 +559,9 @@ export class SallaConditionalOffer {
             clearTimeout(this.cartRefreshTimer);
             this.cartRefreshTimer = null;
         }
+        // A dead host has no picker to unlock; drop the fallback timer with the rest.
+        this.unlockFreeProduct();
+        this.clearPickerLookupRetry();
         // Likewise: the timer goes, `cartLookupRetryPending` stays.
         if (this.cartLookupRetryTimer !== null) {
             clearTimeout(this.cartLookupRetryTimer);
@@ -973,6 +1051,8 @@ export class SallaConditionalOffer {
             return;
         this.cartRefreshPending = false;
         this.refresh();
+        // A new cart change starts a new picker retry episode: this pass asks again itself.
+        this.clearPickerLookupRetry();
         refreshCartFreeGifts().then(() => this.loadCart(), () => this.loadCart());
     }
     /**
@@ -1039,6 +1119,14 @@ export class SallaConditionalOffer {
         const text = salla.lang.get(FREE_LABEL_KEY);
         return text && text !== FREE_LABEL_KEY ? text : FREE_LABEL_FALLBACK;
     }
+    getAddLabel() {
+        return this.sharedLabel(ADD_LABEL_KEY, ADD_LABEL_FALLBACK);
+    }
+    /** A platform-wide label (not `blocks.cart_offer.*`): its own text, or `fallback` when missing. */
+    sharedLabel(key, fallback) {
+        const text = salla.lang.get(key);
+        return text && text !== key ? text : fallback;
+    }
     /**
      * Read a `blocks.cart_offer.*` translation.
      *
@@ -1168,6 +1256,7 @@ export class SallaConditionalOffer {
             // Re-asked now that `this.offer` is known, because the gift filter is keyed to
             // the offer id — the early pass in `load()` could only answer the COUNT.
             this.loadCart();
+            this.loadFreeProductCards();
         }
         catch (error) {
             if (this.isSuperseded(generation))
@@ -1232,8 +1321,8 @@ export class SallaConditionalOffer {
      */
     loadCart() {
         const generation = ++this.giftsGeneration;
-        return Promise.all([getCartFreeGiftItems(), getCartItemCount()])
-            .then(([items, count]) => {
+        return Promise.all([getCartFreeGiftItems(), getCartItemCount(), getCartProductLines()])
+            .then(([items, count, lines]) => {
             if (generation !== this.giftsGeneration || this.isDisconnected)
                 return;
             /**
@@ -1247,6 +1336,8 @@ export class SallaConditionalOffer {
              */
             if (this.cartRefreshPending)
                 return;
+            // Was this pass the cart, or a failed lookup's fallback? See below.
+            const answered = hasAuthoritativeCartData();
             /**
              * NEVER walks a KNOWN count back to `null`. `count` is `null` whenever the
              * shared lookup could not answer — which, on the removal path, is every
@@ -1283,6 +1374,28 @@ export class SallaConditionalOffer {
                 this.deferredByEmptyCart = false;
                 this.refresh();
             }
+            /**
+             * A failed lookup hands back the cached lines, or `[]` right after a cart
+             * update — not the cart. Publishing them would show an added gift as Add
+             * again (one more tap is a PAID unit) and end the post-change checks below
+             * as though fresh lines had arrived. Keep what we had, and while a picker
+             * change is waiting on real lines — or a shown picker has never had any, so
+             * Add is still disabled — ask again: the count alone schedules no retry once
+             * the cart event has supplied one. A cart with no items (no banner) asks
+             * nothing more.
+             *
+             * An offer without a picker has none of this at stake and goes on as it always
+             * did: its gift card must still follow a removed gift, and nothing would retry.
+             */
+            const hasPicker = this.getPickerStage(this.getStages()) !== null;
+            const awaitsPickerChange = this.pendingFreeProductSettledAt !== null || this.cartPageCheckAfter !== null;
+            if (!answered && (hasPicker || awaitsPickerChange)) {
+                if (awaitsPickerChange || (!this.cartLinesLoaded && this.hasCartItems())) {
+                    this.retryPickerCartLookup();
+                }
+                return;
+            }
+            this.clearPickerLookupRetry();
             /**
              * The gift card is keyed to the offer, so it can only be filled once the
              * offer is known. The early pass fired from `load()` runs BEFORE
@@ -1292,6 +1405,16 @@ export class SallaConditionalOffer {
              * one.
              */
             this.gifts = this.offer ? this.selectOwnGifts(items) : [];
+            this.cartLines = this.offer ? lines : [];
+            this.cartLinesLoaded = !!this.offer;
+            // These lines were read after the pending change landed: the picker may act again.
+            if (this.pendingFreeProductSettledAt !== null && generation > this.pendingFreeProductSettledAt) {
+                this.unlockFreeProduct();
+            }
+            if (this.cartPageCheckAfter !== null && generation > this.cartPageCheckAfter) {
+                this.cartPageCheckAfter = null;
+                this.showMissingCartLines(lines);
+            }
         })
             .catch(error => {
             this.safeLog('cart lookup failed', error);
@@ -1323,6 +1446,27 @@ export class SallaConditionalOffer {
             this.loadCart();
         }, CART_LOOKUP_RETRY_DELAYS_MS[this.cartLookupRetries]);
     }
+    /**
+     * Ask for the cart again after a lookup that could not answer while a picker change is
+     * waiting on real lines. Its own bounded episode, on the count retry's delays: that one
+     * ends as soon as the cart event has supplied a count, which is exactly when this is needed.
+     */
+    retryPickerCartLookup() {
+        if (this.pickerLookupTimer !== null || this.pickerLookupRetries >= CART_LOOKUP_RETRY_DELAYS_MS.length)
+            return;
+        this.pickerLookupTimer = setTimeout(() => {
+            this.pickerLookupTimer = null;
+            this.pickerLookupRetries++;
+            this.loadCart();
+        }, CART_LOOKUP_RETRY_DELAYS_MS[this.pickerLookupRetries]);
+    }
+    clearPickerLookupRetry() {
+        this.pickerLookupRetries = 0;
+        if (this.pickerLookupTimer === null)
+            return;
+        clearTimeout(this.pickerLookupTimer);
+        this.pickerLookupTimer = null;
+    }
     /**
      * End the retry episode: a lookup answered, or the cart changed under it. The count
      * goes back to zero so a LATER failure gets its own full set of attempts.
@@ -1379,7 +1523,7 @@ export class SallaConditionalOffer {
      * an older backend — is measured by the offer-level value exactly as before.
      */
     getProgress(stages) {
-        return computeOfferStageProgress(this.offer?.details?.current_value, stages.map(({ min_spend }) => min_spend), this.offer?.details?.start_value, stages.map(({ is_applied }) => is_applied), stages.map(({ current_value }) => current_value));
+        return computeOfferStageProgress(this.offer?.details?.current_value, stages.map(({ min_spend }) => min_spend), this.offer?.details?.start_value, stages.map(({ is_applied }) => is_applied), stages.map(({ current_value }) => current_value), stages.map(({ can_add_free }) => can_add_free));
     }
     /**
      * A tier's render key. `id` is the stable identity across refetches; the array
@@ -1436,6 +1580,15 @@ export class SallaConditionalOffer {
      * why every caller has a reward-less sentence to fall back to.
      */
     getRewardText(discount) {
+        // CP-2171 — Figma: "Add 140 and get 2 free products". The server's label has no count.
+        if (this.isPickerTier(discount)) {
+            const limit = Math.max(1, Math.floor(Number(discount.max_free_products) || 1));
+            if (limit === 1)
+                return this.trans('free_product_reward_one');
+            if (limit === 2)
+                return this.trans('free_products_reward_two');
+            return this.trans('free_products_reward', { count: `${limit}` });
+        }
         return (discount?.reward_label ?? '').trim();
     }
     /**
@@ -1457,7 +1610,13 @@ export class SallaConditionalOffer {
     getGuidanceMessage(stages, progress) {
         if (progress.nextUnmetIndex === NO_STAGE_REACHED)
             return '';
-        const remainingValue = getRemainingToStage(progress.nextUnmetIndex, progress, this.stageMeasure());
+        // CP-2171 — the engine's own gap for a picker tier, when the server sends it: `current_value`
+        // counts the gift units the tier would free, so it can read as past the threshold while the
+        // tier is still short ("conditions unmet" with no amount).
+        const engineAmountNeeded = Number(stages[progress.nextUnmetIndex]?.amount_needed);
+        const remainingValue = this.isPickerTier(stages[progress.nextUnmetIndex]) && Number.isFinite(engineAmountNeeded) && engineAmountNeeded > 0
+            ? engineAmountNeeded
+            : getRemainingToStage(progress.nextUnmetIndex, progress, this.stageMeasure());
         if (remainingValue <= 0)
             return this.trans('guidance_conditions_unmet');
         const remaining = this.formatRequirement(remainingValue);
@@ -1735,26 +1894,403 @@ export class SallaConditionalOffer {
                 }, innerHTML: this.getTierSentence(discount, index, progress) }))));
         }))));
     }
+    /**
+     * CP-2171 — the tier the free product picker belongs to: the first `free_product` tier that
+     * carries a non-empty `free_products` list. `null` on an offer without one, which keeps the
+     * read-only gift card exactly as before. An empty list (every listed product unavailable) is
+     * treated as no picker: there is nothing to choose, so a "Choose N" header would be a dead end.
+     */
+    getPickerStage(stages) {
+        return stages.find(stage => this.isPickerTier(stage)) ?? null;
+    }
+    isPickerTier(stage) {
+        return stage?.type === DiscountType.FREE_PRODUCT && Array.isArray(stage.free_products) && stage.free_products.length > 0;
+    }
+    /**
+     * CP-5033 — the furthest tier the cart's value reaches is a gift tier with none of its gifts
+     * addable (the server lists only what can be added: out of stock, hidden and deleted are left
+     * out), and the cart holds none of this offer's gifts. The engine pays nothing for that tier,
+     * so neither "congrats" nor "conditions unmet" is true.
+     */
+    areGiftsUnavailable(stages, progress) {
+        const stage = stages[progress.lastReachedIndex];
+        return stage?.type === DiscountType.FREE_PRODUCT
+            && Array.isArray(stage.free_products) && stage.free_products.length === 0
+            && this.gifts.length === 0;
+    }
+    /**
+     * Load the picker's product cards (name, image, price) — one `salla.product.fetch` for
+     * the ids not loaded yet. Never rejects: a failed lookup leaves the cards out, not the banner.
+     */
+    loadFreeProductCards() {
+        const stage = this.getPickerStage(this.getStages());
+        const ids = (stage?.free_products ?? [])
+            .map(ref => String(ref.id))
+            .filter(id => id && !this.freeProductCards[id]);
+        if (!ids.length)
+            return Promise.resolve();
+        const listedIds = new Set((stage.free_products ?? []).map(ref => String(ref.id)));
+        return Promise.resolve()
+            .then(() => salla.product.fetch({ source: 'selected', source_value: ids }))
+            .then((response) => {
+            if (this.isDisconnected)
+                return;
+            const cards = { ...this.freeProductCards };
+            (Array.isArray(response?.data) ? response.data : []).forEach((product) => {
+                const id = String(product?.id ?? '');
+                if (!id || !listedIds.has(id))
+                    return;
+                cards[id] = {
+                    id,
+                    name: String(product.name ?? ''),
+                    imageUrl: String(product.image?.url ?? ''),
+                    imageAlt: String(product.image?.alt ?? product.name ?? ''),
+                    price: Number.isFinite(Number(product.price)) ? Number(product.price) : null,
+                };
+            });
+            this.freeProductCards = cards;
+        })
+            .catch(error => this.safeLog('free product lookup failed', error));
+    }
+    /**
+     * The picker's view of the cart for this offer.
+     *
+     * - `freeCount`: products a line of THIS offer made free — the engine's own verdict, read
+     *   off the cart lines (`added_by_offer` + `offer_id`), never re-derived here. Gifts of other
+     *   offers (another cart offer, Buy X Get Y) are not counted against this offer's limit.
+     * - `reached`: the tier's threshold is met. Read from `current_value` against `min_spend`,
+     *   NOT from `is_applied`: a free product tier is only "applied" once a listed product is
+     *   in the cart, so gating "Add" on it would never let the customer add the first one.
+     */
+    getPickerState(stage) {
+        const allFreeLines = this.cartLines.filter(line => line.freeQuantity > 0);
+        const freeLines = this.selectOwnFreeLines(allFreeLines);
+        const free = new Set(freeLines.map(line => line.productId).filter(id => id !== null));
+        const limit = Math.max(1, Math.floor(Number(stage.max_free_products) || 1));
+        // The engine's answer when the server sends it; `current_value >= min_spend` is only a
+        // fallback — it is gross of earlier discounts, so it can say "choose" while the engine
+        // would still charge for the product.
+        const value = Number(stage.current_value ?? this.offer?.details?.current_value ?? 0);
+        const reached = typeof stage.can_add_free === 'boolean'
+            ? stage.can_add_free
+            : Number.isFinite(value) && value >= Number(stage.min_spend);
+        return { limit, reached, freeCount: free.size };
+    }
+    /**
+     * The free lines this offer granted — the SAME rule as `selectOwnGifts`, so the picker and
+     * the gifts card never disagree: lines matching the offer id; only when none match, the
+     * lines whose `offer_id` is unreadable.
+     */
+    selectOwnFreeLines(lines) {
+        const offerId = Number(this.offer?.id);
+        if (!Number.isFinite(offerId))
+            return lines;
+        const owned = lines.filter(line => line.offerId !== null && Number(line.offerId) === offerId);
+        return owned.length ? owned : lines.filter(line => line.offerId === null);
+    }
+    /**
+     * Add a free product to the cart — always from the cart page, never a redirect.
+     *
+     * Quick-add, exactly like the single free product was auto-added before CP-2171: a variant
+     * (SKU) product gets its default SKU — `is_default` first, or the first in stock when stock
+     * is per SKU (`AddToCart::addItemToCart()`) — with that SKU's option values. Any listed
+     * product in the cart counts, so the engine then frees it. A failed add is left to the SDK,
+     * which already shows the shopper its error notice.
+     */
+    addFreeProduct(card) {
+        if (this.pendingFreeProduct)
+            return;
+        this.pendingFreeProduct = card.id;
+        this.runFreeProductChange(() => Promise.resolve(salla.cart.addItem(card.id)).then(() => { this.cartPageCheckAfter = this.giftsGeneration; }), 'free product add failed');
+    }
+    /** Its own method so specs can observe it; the mock window cannot reload. */
+    reloadPage() {
+        window.location.reload();
+    }
+    /**
+     * Its own method so specs can stub it; the mock window has no `fetch`. Aborted after
+     * `CART_PAGE_FETCH_TIMEOUT_MS`: a fetch that never settles would hold `insertingCartLines`
+     * for the page view, and every later line would only be queued behind it.
+     */
+    fetchCartPageHtml() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), CART_PAGE_FETCH_TIMEOUT_MS);
+        // `no-store`: a cached copy of the page would lack the new line and force the reload.
+        return fetch(window.location.href, { cache: 'no-store', credentials: 'same-origin', headers: { Accept: 'text/html' }, signal: controller.signal })
+            .then(response => (response.ok ? response.text() : Promise.reject(new Error(`cart page ${response.status}`))))
+            .finally(() => clearTimeout(timer));
+    }
+    /**
+     * Show the cart lines an add from the picker created that the page has no `form#item-<id>`
+     * for. Themes render cart lines on the server and only refresh lines already on the page, so
+     * the new line (and its price) would otherwise appear only after a manual refresh.
+     *
+     * The cart page is fetched again and the missing line forms are inserted, in the server's
+     * order — no reload. The fetched markup is fresh, so its prices need no update. Its inline
+     * handlers and web components work as on a loaded page; only what the theme's own script wires
+     * to a line at page load (e.g. raed's loading overlay on a quantity change) is missing.
+     * Any failure (fetch, a line the fetched page lacks) falls back to `reloadForMissingCartLines`.
+     *
+     * Left alone on a page with no cart line forms at all (not a cart page this can reason about).
+     * One fetch at a time; lines read meanwhile are checked again after it.
+     */
+    showMissingCartLines(lines) {
+        if (this.insertingCartLines) {
+            this.pendingCartPageLines = lines;
+            return;
+        }
+        const missing = this.missingCartLineIds(lines);
+        if (!missing.length)
+            return;
+        this.insertingCartLines = true;
+        // Started inside the chain, so a synchronous throw (no `fetch`) still reaches `catch` and `finally`.
+        Promise.resolve()
+            .then(() => this.fetchCartPageHtml())
+            .then(html => {
+            if (this.isDisconnected || this.cartChangedDuringPageFetch())
+                return;
+            const stillMissing = this.missingCartLineIds(this.cartLines);
+            if (stillMissing.length && !this.insertCartLineForms(html, stillMissing)) {
+                this.reloadForMissingCartLines(stillMissing);
+            }
+        })
+            .catch(error => {
+            this.safeLog('cart page fetch for the new lines failed, reloading', error);
+            if (this.isDisconnected || this.cartChangedDuringPageFetch())
+                return;
+            this.reloadForMissingCartLines(this.missingCartLineIds(this.cartLines));
+        })
+            .finally(() => {
+            this.insertingCartLines = false;
+            const pending = this.pendingCartPageLines;
+            this.pendingCartPageLines = null;
+            if (pending && !this.isDisconnected)
+                this.showMissingCartLines(pending);
+        });
+    }
+    /**
+     * A picker change started while the cart page was fetched (e.g. a second add),
+     * so neither the fetched page nor the cart lines can be trusted: inserting now could bring
+     * back a line the cart no longer has. The answer is dropped and the cart read after that
+     * change checks the page again (the change itself arms `cartPageCheckAfter` when it lands;
+     * armed here too, for a change that fails and so arms nothing).
+     *
+     * Lines are always read from `cartLines` once the page arrives, never from the call's own
+     * `lines`: a change that landed during the fetch has already replaced them there.
+     */
+    cartChangedDuringPageFetch() {
+        // Lines not read since a change (the lock timed out on them) are no basis either.
+        if (this.pendingFreeProduct === null && this.cartLinesLoaded)
+            return false;
+        if (this.cartPageCheckAfter === null)
+            this.cartPageCheckAfter = this.giftsGeneration;
+        return true;
+    }
+    /** Ids of `lines` the page has no form for, sorted; empty on a page with no cart line forms. */
+    missingCartLineIds(lines) {
+        try {
+            if (!document.querySelector(CART_LINE_FORMS))
+                return [];
+            return lines.map(line => line.id).filter(id => !document.getElementById(`item-${id}`)).sort();
+        }
+        catch (error) {
+            this.safeLog('cart page check after a free product add failed', error);
+            return [];
+        }
+    }
+    /**
+     * Insert the `missing` line forms from the fetched cart page `html`, each right before the next
+     * line the page already has (in the fetched order), else after the last one. Returns false —
+     * nothing inserted — when the fetched page lacks any of them.
+     */
+    insertCartLineForms(html, missing) {
+        try {
+            const fetched = Array.from(new DOMParser().parseFromString(html, 'text/html').querySelectorAll(CART_LINE_FORMS));
+            // `getAttribute`, not `form.id`: a line form holds an `<input name="id">`, which shadows the property.
+            const fetchedIds = fetched.map(form => form.getAttribute('id'));
+            if (missing.some(id => !fetchedIds.includes(`item-${id}`)))
+                return false;
+            fetched.forEach((form, index) => {
+                const id = fetchedIds[index];
+                if (!missing.includes(id.slice('item-'.length)) || document.getElementById(id))
+                    return;
+                // Moved, not cloned: inserting adopts it into this document, and its web components
+                // upgrade once connected. Its inline handlers (`onchange`, delete `onclick`) come along.
+                const next = fetchedIds.slice(index + 1).map(nextId => document.getElementById(nextId)).find(Boolean);
+                if (next) {
+                    next.parentNode.insertBefore(form, next);
+                }
+                else {
+                    const onPage = document.querySelectorAll(CART_LINE_FORMS);
+                    const last = onPage[onPage.length - 1];
+                    last.parentNode.insertBefore(form, last.nextSibling);
+                }
+            });
+            return missing.every(id => document.getElementById(`item-${id}`));
+        }
+        catch (error) {
+            this.safeLog('cart line insert failed', error);
+            return false;
+        }
+    }
+    /**
+     * Reload once, when the missing lines could not be inserted. Never twice for the same missing
+     * lines, so a line a theme never renders cannot loop the page. The guard lives in
+     * `sessionStorage`; where storage is blocked the page still reloads, but never twice in a row.
+     */
+    reloadForMissingCartLines(missing) {
+        if (!missing.length)
+            return;
+        const signature = missing.join(',');
+        const stored = this.readReloadGuard();
+        if (stored === signature)
+            return;
+        if (stored === undefined && this.pageWasReloaded())
+            return;
+        this.writeReloadGuard(signature);
+        this.reloadPage();
+    }
+    /** The reload guard, or `undefined` when storage cannot be read (blocked, disabled). */
+    readReloadGuard() {
+        try {
+            return window.sessionStorage.getItem(CART_PAGE_RELOAD_KEY);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    writeReloadGuard(signature) {
+        try {
+            window.sessionStorage.setItem(CART_PAGE_RELOAD_KEY, signature);
+        }
+        catch {
+            // Storage full or blocked: pageWasReloaded() is the guard on the next load.
+        }
+    }
+    /** Whether this page load is itself a reload — the guard when storage is unavailable. */
+    pageWasReloaded() {
+        try {
+            const navigation = window.performance?.getEntriesByType?.('navigation')?.[0];
+            return navigation?.type === 'reload';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Run one add. A failure unlocks at once — nothing changed. A success stays locked
+     * until a cart load that started after it publishes (see `loadCart`), or the fallback fires.
+     */
+    runFreeProductChange(change, failure) {
+        Promise.resolve()
+            .then(change)
+            .then(() => {
+            if (this.isDisconnected)
+                return this.unlockFreeProduct();
+            this.pendingFreeProductSettledAt = this.giftsGeneration;
+            this.pendingFreeProductTimer = setTimeout(() => this.unlockOnStaleLines(), FREE_PRODUCT_UNLOCK_FALLBACK_MS);
+        })
+            .catch(error => {
+            this.safeLog(failure, error);
+            this.unlockFreeProduct();
+            // A failed change fires no cart event, so nothing else checks a cart page answer
+            // that was dropped while this change was in flight.
+            if (this.cartPageCheckAfter !== null)
+                this.loadCart();
+        });
+    }
+    /**
+     * The lock's fallback: no cart lines read after the change have arrived, so the lines on
+     * screen are the ones from BEFORE it. Release the lock, mark the lines unread and ask again
+     * on a fresh read — `loadCart` retries within its bound while the picker has no lines.
+     */
+    unlockOnStaleLines() {
+        this.unlockFreeProduct();
+        this.cartLinesLoaded = false;
+        this.clearPickerLookupRetry();
+        refreshCartFreeGifts().then(() => this.loadCart(), () => this.loadCart());
+    }
+    unlockFreeProduct() {
+        if (this.pendingFreeProductTimer !== null)
+            clearTimeout(this.pendingFreeProductTimer);
+        this.pendingFreeProductTimer = null;
+        this.pendingFreeProductSettledAt = null;
+        this.pendingFreeProduct = null;
+    }
+    /**
+     * CP-2171 — Figma's banner line at the gift tier: "You got N free products", with
+     * "Choose them now" while none is picked yet. N is the tier's limit, not the count picked.
+     */
+    pickerGotMessage(limit, awaitsPick) {
+        if (limit === 1)
+            return this.trans(awaitsPick ? 'free_product_got_pick_one' : 'free_product_got_one');
+        if (limit === 2)
+            return this.trans(awaitsPick ? 'free_products_got_pick_two' : 'free_products_got_two');
+        return this.trans(awaitsPick ? 'free_products_got_pick' : 'free_products_got', { count: `${limit}` });
+    }
+    getPickerCards(stage) {
+        return (stage.free_products ?? [])
+            .map(ref => this.freeProductCards[String(ref.id)])
+            .filter(Boolean);
+    }
+    /** CP-2171 — Figma "Choose N free products": the counter, then one card per listed product. */
+    renderPicker(stage) {
+        const state = this.getPickerState(stage);
+        const cards = this.getPickerCards(stage);
+        // Cards still loading, or the lookup failed: no header and counter over an empty list.
+        if (!cards.length)
+            return null;
+        return (h("div", { class: "s-conditional-offer-picker", "data-picker-reached": state.reached ? 'true' : 'false' }, h("div", { class: "s-conditional-offer-picker-header" }, h("span", { class: "s-conditional-offer-picker-counter", "aria-label": `${state.freeCount}/${state.limit}` }, `${state.freeCount}/${state.limit}`), h("span", { class: "s-conditional-offer-picker-title" }, state.limit === 1
+            ? this.trans('free_product_choose_one')
+            : state.limit === 2
+                ? this.trans('free_products_choose_two')
+                : this.trans('free_products_choose', { count: `${state.limit}` }))), h("ul", { class: "s-conditional-offer-picker-list" }, cards.map(card => this.renderPickerCard(card)))));
+    }
+    /**
+     * One picker card: the product, its normal price and Add — the same on every card, whether
+     * the product is in the cart, free or not. Add is never disabled: every tap adds one unit at
+     * the normal price (also once the product is in the cart, and after the free limit is used
+     * up) and the engine decides what is free. What IS free shows in the "Free products" panel
+     * below, never on the card. A tap while the previous add is still in flight is ignored
+     * (`addFreeProduct`), so one double tap is one unit.
+     *
+     * No remove: the picker never deletes a cart line. A free line can also hold paid units, and
+     * deleting it would take what the customer bought with the gift — products leave the cart
+     * from their own cart line only.
+     */
+    renderPickerCard(card) {
+        return (h("li", { class: "s-conditional-offer-picker-card", "data-product-id": card.id }, h("span", { class: "s-conditional-offer-picker-thumb" }, card.imageUrl ? (h("img", { class: "s-conditional-offer-picker-image", src: card.imageUrl, alt: card.imageAlt || card.name, loading: "lazy", decoding: "async" })) : (h("i", { class: "sicon-gift", "aria-hidden": "true" }))), h("span", { class: "s-conditional-offer-picker-name" }, card.name), card.price !== null ? (h("span", { class: "s-conditional-offer-picker-prices" }, h("span", { class: "s-conditional-offer-picker-price-regular", innerHTML: salla.money(card.price) }))) : null, h("span", { class: "s-conditional-offer-picker-actions" }, h("button", { type: "button", class: "s-conditional-offer-picker-add", onClick: () => this.addFreeProduct(card) }, this.getAddLabel()))));
+    }
     /**
      * "ادارة العرض". Rendered TWICE with complementary responsive visibility rather than
      * moved with `order:`: desktop wants it inline with the banner row, mobile wants a
      * full-width bar BELOW the gifts card, and those are different places
      * in the flow, not a different order within one flex line.
      */
-    renderGiftsToggle(variant) {
+    renderGiftsToggle(variant, hasPicker) {
         return (h("button", { type: "button", id: this.elementId(`toggle-${variant}`), class: {
                 's-conditional-offer-toggle': true,
                 's-conditional-offer-toggle-inline': variant === 'inline',
                 's-conditional-offer-toggle-bar': variant === 'bar',
-            }, "aria-expanded": this.isGiftsOpen ? 'true' : 'false', "aria-controls": this.elementId('gifts'), onClick: () => (this.isGiftsOpen = !this.isGiftsOpen) }, h("span", null, this.trans('manage_offer')), h("i", { class: {
+            }, "aria-expanded": this.isGiftsOpen ? 'true' : 'false', "aria-controls": this.elementId('gifts'), onClick: () => (this.isGiftsOpen = !this.isGiftsOpen) }, h("span", null, this.trans(hasPicker ? 'offer_toggle' : 'manage_offer')), h("i", { class: {
                 'sicon-keyboard_arrow_down': true,
                 's-conditional-offer-toggle-icon': true,
                 's-conditional-offer-toggle-icon-open': this.isGiftsOpen,
             }, "aria-hidden": "true" })));
     }
-    /** Spec §5 — the gifts card: one read-only row per gift line. */
-    renderGiftsCard() {
-        return (h("div", { class: "s-conditional-offer-panel", id: this.elementId('gifts') }, h("div", { class: "s-conditional-offer-gifts-header" }, h("span", { class: "s-conditional-offer-gifts-icon" }, h("i", { class: "sicon-gift", "aria-hidden": "true" })), h("span", { class: "s-conditional-offer-gifts-title" }, this.trans('free_products_title'))), h("ul", { class: "s-conditional-offer-gifts-list" }, this.gifts.map(gift => this.renderGiftRow(gift)))));
+    /**
+     * Spec §5 — the gifts card: one row per gift line. Read-only on an offer without a picker,
+     * exactly as before; with the CP-2171 picker it becomes the Figma "Free products" panel,
+     * shown only once a gift is in the cart. Its rows are read-only, as are the picker cards: a
+     * gift leaves the cart from its own cart line.
+     */
+    renderGiftsCard(pickerStage = null) {
+        // No picker: the card exactly as before CP-2171 — no wrapper, so no new box styling.
+        if (!pickerStage) {
+            return (h("div", { class: "s-conditional-offer-panel", id: this.elementId('gifts') }, h("div", { class: "s-conditional-offer-gifts-header" }, h("span", { class: "s-conditional-offer-gifts-icon" }, h("i", { class: "sicon-gift", "aria-hidden": "true" })), h("span", { class: "s-conditional-offer-gifts-title" }, this.trans('free_products_title'))), h("ul", { class: "s-conditional-offer-gifts-list" }, this.gifts.map(gift => this.renderGiftRow(gift)))));
+        }
+        const state = this.getPickerState(pickerStage);
+        return (h("div", { class: "s-conditional-offer-panel", id: this.elementId('gifts') }, state.reached ? this.renderPicker(pickerStage) : null, this.gifts.length ? (h("div", { class: "s-conditional-offer-gifts" }, h("div", { class: "s-conditional-offer-gifts-header" }, h("span", { class: "s-conditional-offer-gifts-icon" }, h("i", { class: "sicon-gift", "aria-hidden": "true" })), h("span", { class: "s-conditional-offer-gifts-title" }, this.sharedLabel(FREE_PRODUCTS_TITLE_KEY, FREE_PRODUCTS_TITLE_FALLBACK))), h("ul", { class: "s-conditional-offer-gifts-list" }, this.gifts.map(gift => this.renderGiftRow(gift))))) : null));
     }
     renderGiftRow(gift) {
         return (h("li", { class: "s-conditional-offer-gift", "data-item-id": gift.id }, h("span", { class: "s-conditional-offer-gift-thumb" }, gift.imageUrl ? (h("img", { class: "s-conditional-offer-gift-image", src: gift.imageUrl, alt: gift.imageAlt || gift.name, loading: "lazy", decoding: "async" })) : (h("i", { class: "sicon-gift", "aria-hidden": "true" }))), h("div", { class: "s-conditional-offer-gift-body" }, h("span", { class: "s-conditional-offer-gift-name" }, gift.name || this.trans('free_gift')), h("span", { class: "s-conditional-offer-gift-prices" }, h("span", { class: "s-conditional-offer-gift-free" }, this.getFreeLabel()), gift.originalPrice !== null ? (
@@ -1801,12 +2337,26 @@ export class SallaConditionalOffer {
         const progress = this.getProgress(stages);
         const guidance = this.getGuidanceMessage(stages, progress);
         const detailsTitle = this.trans('details_title');
-        // Spec §2 — the accordion exists only when there is something to manage.
-        const hasGifts = this.gifts.length > 0;
-        return (h(Host, { class: "s-conditional-offer-root" }, h("div", { class: "s-conditional-offer-banner" }, h("div", { class: "s-conditional-offer-lead" }, this.renderBadges(stages, progress), h("div", { class: "s-conditional-offer-text" }, h("div", { class: "s-conditional-offer-heading", onMouseEnter: () => (this.isTooltipHovered = true), onMouseLeave: () => (this.isTooltipHovered = false) }, h("span", { class: "s-conditional-offer-name" }, this.offer.title), h("span", { class: "s-conditional-offer-info", ref: (el) => (this.infoAnchorEl = el) }, h("button", { type: "button", class: "s-conditional-offer-info-trigger", ref: (el) => (this.infoTriggerEl = el), "aria-label": detailsTitle, title: detailsTitle, "aria-expanded": this.isTooltipOpen ? 'true' : 'false', "aria-describedby": this.elementId('tooltip'), onClick: () => this.toggleTooltip() }, h(InformationIcon, { class: "s-conditional-offer-info-icon" })), this.isTooltipOpen ? this.renderTooltip(stages, progress) : null)), progress.allMet ? (h("div", { class: "s-conditional-offer-message", role: "status" }, this.trans('congrats'))) : guidance ? (
+        // Spec §2 — the accordion exists only when there is something to manage: gift lines,
+        // or (CP-2171) a free product picker — shown only once the customer has reached its
+        // stage, then before anything is picked too.
+        const pickerStage = this.getPickerStage(stages);
+        const pickerState = pickerStage !== null ? this.getPickerState(pickerStage) : null;
+        const isPickerReached = pickerState?.reached ?? false;
+        const hasGifts = this.gifts.length > 0 || (isPickerReached && this.getPickerCards(pickerStage).length > 0);
+        // The gift tier is reached but none of this offer's gifts is in the cart: the engine
+        // grants that tier only once one is, and pays nothing until then (no fallback to a lower
+        // tier). So neither "congrats" nor "conditions unmet" is true — ask for the pick. Only
+        // once the cart lines are read, or a cart that holds the gift would flash this line.
+        const awaitsGiftPick = isPickerReached && this.cartLinesLoaded && pickerState.freeCount === 0;
+        // "You got N free products" replaces congrats only when the gift tier is the offer's last:
+        // below a higher tier, `guidance` (or congrats for that higher tier) is the truer line.
+        const gotGifts = progress.allMet && isPickerReached && pickerState.freeCount > 0
+            && stages[stages.length - 1] === pickerStage;
+        return (h(Host, { class: "s-conditional-offer-root" }, h("div", { class: "s-conditional-offer-banner" }, h("div", { class: "s-conditional-offer-lead" }, this.renderBadges(stages, progress), h("div", { class: "s-conditional-offer-text" }, h("div", { class: "s-conditional-offer-heading", onMouseEnter: () => (this.isTooltipHovered = true), onMouseLeave: () => (this.isTooltipHovered = false) }, h("span", { class: "s-conditional-offer-name" }, this.offer.title), h("span", { class: "s-conditional-offer-info", ref: (el) => (this.infoAnchorEl = el) }, h("button", { type: "button", class: "s-conditional-offer-info-trigger", ref: (el) => (this.infoTriggerEl = el), "aria-label": detailsTitle, title: detailsTitle, "aria-expanded": this.isTooltipOpen ? 'true' : 'false', "aria-describedby": this.elementId('tooltip'), onClick: () => this.toggleTooltip() }, h(InformationIcon, { class: "s-conditional-offer-info-icon" })), this.isTooltipOpen ? this.renderTooltip(stages, progress) : null)), awaitsGiftPick || gotGifts ? (h("div", { class: "s-conditional-offer-message", role: "status" }, this.pickerGotMessage(pickerState.limit, awaitsGiftPick))) : this.areGiftsUnavailable(stages, progress) ? (h("div", { class: "s-conditional-offer-message", role: "status" }, this.trans('free_products_unavailable'))) : progress.allMet ? (h("div", { class: "s-conditional-offer-message", role: "status" }, this.trans('congrats'))) : guidance ? (
         // innerHTML: the `:remaining` half carries `salla.money()` markup;
         // the reward half is escaped in `getGuidanceMessage`.
-        h("div", { class: "s-conditional-offer-message", innerHTML: guidance })) : null)), hasGifts ? this.renderGiftsToggle('inline') : null), hasGifts && this.isGiftsOpen ? this.renderGiftsCard() : null, hasGifts ? this.renderGiftsToggle('bar') : null));
+        h("div", { class: "s-conditional-offer-message", innerHTML: guidance })) : null)), hasGifts ? this.renderGiftsToggle('inline', !!pickerStage) : null), hasGifts && this.isGiftsOpen ? this.renderGiftsCard(pickerStage) : null, hasGifts ? this.renderGiftsToggle('bar', !!pickerStage) : null));
     }
     static get is() { return "salla-conditional-offer"; }
     static get originalStyleUrls() {
@@ -1825,6 +2375,10 @@ export class SallaConditionalOffer {
             "isLoading": {},
             "canRender": {},
             "gifts": {},
+            "cartLines": {},
+            "cartLinesLoaded": {},
+            "freeProductCards": {},
+            "pendingFreeProduct": {},
             "cartItemCount": {},
             "isTooltipHovered": {},
             "isTooltipPinned": {},