@drip-apex/sdk 0.1.0

package/src/commerce-price.ts

@@ -0,0 +1,941 @@
+import type { Assignment, CommercePriceSettings } from "./types";
+import { formatCentsLike, parseDisplayedCents } from "./money";
+
+type PriceAssignmentAuthorization = (assignment: Assignment) => boolean;
+
+export const COMMERCE_PRICE_SELECTORS =
+  '.price,.price__regular,.price-item,.price-item--regular,.product__price,.product-price,[data-price],[itemprop="price"]'.split(
+    ",",
+  );
+export const COMMERCE_PRICE_EXCLUSIONS =
+  's,del,.price__compare,.price-item--compare,[class*="compare-at"]'.split(",");
+
+type ShopifyWindow = Window & {
+  Shopify?: { currency?: { active?: string } };
+  ShopifyAnalytics?: {
+    meta?: {
+      page?: { pageType?: string; handle?: string };
+      product?: {
+        handle?: string;
+        variants?: Array<{ id?: string | number; price?: string | number }>;
+      };
+    };
+  };
+};
+
+const ZERO_DECIMAL =
+  /^(BIF|CLP|DJF|GNF|ISK|JPY|KMF|KRW|PYG|RWF|UGX|VND|VUV|XAF|XOF|XPF)$/;
+let observer: MutationObserver | null = null;
+let rootObserver: MutationObserver | null = null;
+let variantForm: HTMLFormElement | null = null;
+const handleVariantFormEvent = () => guardedSwapPass();
+let originals = new Map<Text, { original: string; applied: string }>();
+let originalAriaLabels = new Map<
+  Element,
+  { original: string; applied: string }
+>();
+let compareAtNodes: HTMLElement[] = [];
+let hiddenCompareAtNodes = new Map<HTMLElement, string>();
+let renderedDisplayAssignment: Assignment | null = null;
+let exposureChanged: (() => void) | undefined;
+let current: {
+  settings: CommercePriceSettings;
+  assignments: Assignment[];
+  isCohortStampedOnCart: () => boolean | "pending";
+  isAssignmentAuthorized: PriceAssignmentAuthorization;
+} | null = null;
+let applying = false;
+let metaRetryTimer: ReturnType<typeof setTimeout> | null = null;
+let stampCheckTimer: ReturnType<typeof setTimeout> | null = null;
+let stampCheckDeadline = 0;
+let pendingActivation: {
+  settings: CommercePriceSettings;
+  assignments: Assignment[];
+  isCohortStampedOnCart: () => boolean | "pending";
+  deadline: number;
+  onResolved?: () => void;
+  isAssignmentAuthorized: PriceAssignmentAuthorization;
+} | null = null;
+
+/** Whether price teardown has state to restore, disconnect, or cancel. */
+export function hasCommercePriceState(): boolean {
+  return (
+    observer !== null ||
+    rootObserver !== null ||
+    originals.size > 0 ||
+    originalAriaLabels.size > 0 ||
+    current !== null ||
+    applying ||
+    metaRetryTimer !== null ||
+    stampCheckTimer !== null ||
+    pendingActivation !== null
+  );
+}
+
+/**
+ * How long activation may wait for the cohort stamp to be confirmed. The tested
+ * price is not shown until Shopify has accepted the signed cart attributes — a
+ * shopper must never be shown a price we cannot prove Shopify will charge.
+ */
+const STAMP_CONFIRM_TIMEOUT_MS = 8000;
+
+/**
+ * Shopify populates ShopifyAnalytics.meta.product AFTER the SDK boots (measured on a
+ * live storefront: SDK at 43ms, meta.product still absent at 46ms). Activation must
+ * therefore be retried instead of failing permanently, or the swap never runs on a
+ * real store.
+ */
+const META_RETRY_INTERVAL_MS = 60;
+const META_RETRY_WINDOW_MS = 5000;
+
+function shopifyProductMetaReady(): boolean {
+  if (typeof window === "undefined") return false;
+  const meta = (window as ShopifyWindow).ShopifyAnalytics?.meta;
+  return Boolean(
+    (window as ShopifyWindow).Shopify && Array.isArray(meta?.product?.variants),
+  );
+}
+
+function cancelMetaRetry(): void {
+  if (metaRetryTimer != null) clearTimeout(metaRetryTimer);
+  metaRetryTimer = null;
+}
+
+function cancelStampCheck(): void {
+  if (stampCheckTimer != null) clearTimeout(stampCheckTimer);
+  stampCheckTimer = null;
+  stampCheckDeadline = 0;
+}
+
+function scheduleStampCheck(): void {
+  if (stampCheckTimer != null) return;
+  if (stampCheckDeadline === 0)
+    stampCheckDeadline = Date.now() + STAMP_CONFIRM_TIMEOUT_MS;
+  stampCheckTimer = setTimeout(() => {
+    stampCheckTimer = null;
+    if (!current) return;
+    const status = current.isCohortStampedOnCart();
+    if (status === false) {
+      // The cohort will never reach the cart: restore the published price.
+      cleanupCommercePrice();
+      return;
+    }
+    if (status === "pending") {
+      if (Date.now() >= stampCheckDeadline) {
+        // Unconfirmed for too long — fail closed rather than keep showing a price
+        // the Cart Transform may not apply.
+        cleanupCommercePrice();
+        return;
+      }
+      scheduleStampCheck();
+    }
+  }, 25);
+}
+
+function activeExperiments(
+  settings: CommercePriceSettings,
+  assignments: Assignment[],
+  isAssignmentAuthorized: PriceAssignmentAuthorization = () => true,
+) {
+  if (typeof window === "undefined") return [];
+  const w = window as ShopifyWindow;
+  const meta = w.ShopifyAnalytics?.meta;
+  if (
+    !w.Shopify ||
+    meta?.page?.pageType !== "product" ||
+    !Array.isArray(meta.product?.variants)
+  )
+    return [];
+  const currency = w.Shopify.currency?.active;
+  const pageVariantIds = new Set(
+    meta.product.variants
+      .filter((variant) => variant.id != null)
+      .map((variant) => String(variant.id)),
+  );
+  const active = [];
+  for (const experiment of settings.experiments) {
+    const assignment = assignments.find(
+      (item) => item.experimentId === experiment.experiment_id,
+    );
+    const adjustments = assignment
+      ? experiment.variants[assignment.variationId]
+      : undefined;
+    const targetsCurrentProduct = adjustments?.some((adjustment) => {
+      const variantId = adjustment.variant_gid.split("/").pop();
+      return variantId != null && pageVariantIds.has(variantId);
+    });
+    const epochMatches =
+      experiment.assignment_epoch == null ||
+      experiment.assignment_epoch === assignment?.assignmentEpoch;
+    if (
+      assignment &&
+      isAssignmentAuthorized(assignment) &&
+      epochMatches &&
+      !assignment.isControl &&
+      currency === experiment.currency &&
+      adjustments &&
+      targetsCurrentProduct
+    ) {
+      active.push({ experiment, assignment, currency });
+    }
+  }
+  return active;
+}
+
+function hasActiveChargedPrice(
+  settings: CommercePriceSettings,
+  assignments: Assignment[],
+  isAssignmentAuthorized: PriceAssignmentAuthorization,
+): boolean {
+  const active = activeExperiments(
+    settings,
+    assignments,
+    isAssignmentAuthorized,
+  );
+  if (active.length > 0)
+    return active.some(({ experiment, assignment }) =>
+      experiment.variants[assignment.variationId]?.some(
+        (adjustment) => typeof adjustment.fixedPricePerUnit === "string",
+      ),
+    );
+  // Before metadata or authorization arrives, retain the strict charged-arm
+  // barrier so activation can be revisited when the cart proof lands.
+  return settings.experiments.some((experiment) => {
+    const assignment = assignments.find(
+      (candidate) =>
+        candidate.experimentId === experiment.experiment_id &&
+        !candidate.isControl,
+    );
+    return Boolean(
+      assignment &&
+      (experiment.assignment_epoch == null ||
+        experiment.assignment_epoch === assignment.assignmentEpoch) &&
+      experiment.variants[assignment.variationId]?.some(
+        (adjustment) => typeof adjustment.fixedPricePerUnit === "string",
+      ),
+    );
+  });
+}
+
+/**
+ * True when a price treatment is assigned AND the page either is eligible now or could
+ * still become eligible (Shopify has not published product metadata yet). The reveal
+ * barrier uses this so a metadata-late PDP cannot flash the ORIGINAL price before the
+ * swap lands. The anti-flicker timeout still caps how long content can stay hidden.
+ */
+export function isCommercePriceWorkPending(
+  settings: CommercePriceSettings | undefined,
+  assignments: Assignment[],
+  isAssignmentAuthorized: PriceAssignmentAuthorization = () => true,
+): boolean {
+  if (!settings) return false;
+  if (isCommercePriceActive(settings, assignments, isAssignmentAuthorized))
+    return true;
+  if (shopifyProductMetaReady()) return false;
+  return settings.experiments.some((experiment) =>
+    assignments.some(
+      (assignment) =>
+        assignment.experimentId === experiment.experiment_id &&
+        isAssignmentAuthorized(assignment) &&
+        !assignment.isControl &&
+        (experiment.assignment_epoch == null ||
+          experiment.assignment_epoch === assignment.assignmentEpoch),
+    ),
+  );
+}
+
+export function isCommercePriceActive(
+  settings: CommercePriceSettings | undefined,
+  assignments: Assignment[],
+  isAssignmentAuthorized: PriceAssignmentAuthorization = () => true,
+): boolean {
+  try {
+    return Boolean(
+      settings &&
+      activeExperiments(settings, assignments, isAssignmentAuthorized).length,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isStrictlyLowerPrice(candidate: string, current: string): boolean {
+  return Number(candidate) < Number(current);
+}
+
+function treatmentUnits(value: string, minorUnits: number): number | null {
+  const match = value.match(/^(\d+)(?:\.(\d+))?$/);
+  if (!match) return null;
+  const fraction = match[2] ?? "";
+  const discarded = fraction.slice(minorUnits);
+  if (/[^0]/.test(discarded)) return null;
+  const units = Number(
+    match[1] + (fraction + "0".repeat(minorUnits)).slice(0, minorUnits),
+  );
+  return Number.isSafeInteger(units) ? units : null;
+}
+
+function replaceNumericText(
+  value: string,
+  targets: Map<number, number>,
+  minorUnits: number,
+): string | null {
+  const parsed = parseDisplayedCents(value, minorUnits);
+  if (!parsed) return null;
+  const replacement = targets.get(parsed.cents);
+  if (replacement == null || Number.isNaN(replacement)) return null;
+  return (
+    value.slice(0, parsed.start) +
+    formatCentsLike(replacement, parsed.convention) +
+    value.slice(parsed.end)
+  );
+}
+
+function applyAccessibleLabel(
+  node: Text,
+  container: Element,
+  targets: Map<number, number>,
+  minorUnits: number,
+): void {
+  const labelled = node.parentElement?.closest("[aria-label]");
+  if (!labelled || !container.contains(labelled)) return;
+  const label = labelled.getAttribute("aria-label");
+  if (label == null) return;
+  const replacement = replaceNumericText(label, targets, minorUnits);
+  if (replacement == null || replacement === label) return;
+  const previous = originalAriaLabels.get(labelled);
+  originalAriaLabels.set(labelled, {
+    original:
+      previous && label === previous.applied ? previous.original : label,
+    applied: replacement,
+  });
+  labelled.setAttribute("aria-label", replacement);
+}
+
+function guardedSwapPass(): void {
+  try {
+    swapPass();
+  } catch {
+    cleanupCommercePrice();
+  }
+}
+
+function productHandleFromUrl(value: string): string | null {
+  try {
+    const path = new URL(value, location.href).pathname;
+    const match = path.match(/\/products\/([^/]+)/i);
+    return match?.[1] ? decodeURIComponent(match[1]).toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+function currentProductHandle(): string | null {
+  const meta = (window as ShopifyWindow).ShopifyAnalytics?.meta;
+  const metadataHandle = meta?.page?.handle ?? meta?.product?.handle;
+  if (typeof metadataHandle === "string" && metadataHandle.trim()) {
+    return metadataHandle.trim().toLowerCase();
+  }
+  const canonical = document.querySelector<HTMLLinkElement>(
+    'link[rel="canonical"][href]',
+  );
+  return canonical ? productHandleFromUrl(canonical.href) : null;
+}
+
+function isElementLinkedToDifferentProduct(
+  node: Element,
+  currentHandle: string | null,
+): boolean {
+  const wrappingAnchor = node.closest<HTMLAnchorElement>(
+    'a[href*="/products/"]',
+  );
+  const labelledContainer = node.closest(
+    "li,article,[data-product-id],[class*='product-card'],[class*='product-item'],[class*='card']",
+  );
+  const siblingContainer =
+    node.parentElement && node.parentElement !== document.body
+      ? node.parentElement
+      : null;
+  const container = labelledContainer ?? siblingContainer;
+  const productAnchors = container
+    ? Array.from(
+        container.querySelectorAll<HTMLAnchorElement>('a[href*="/products/"]'),
+      ).filter(
+        (candidate) =>
+          labelledContainer != null || candidate.parentElement === container,
+      )
+    : [];
+  const linkedHandles = new Set(
+    productAnchors
+      .map((candidate) => productHandleFromUrl(candidate.href))
+      .filter((handle): handle is string => handle != null),
+  );
+  // A descendant link is ownership evidence only inside the nearest explicit
+  // product/card container (or the price's direct parent for sibling labels),
+  // and only when that container identifies one product. A recommendation
+  // elsewhere under a broad PDP ancestor must not claim the main price.
+  const anchor =
+    wrappingAnchor ??
+    (linkedHandles.size === 1 ? (productAnchors[0] ?? null) : null);
+  if (!anchor) return false;
+  const linkedHandle = productHandleFromUrl(anchor.href);
+  if (!linkedHandle) return false;
+  // If current-product identity is unavailable, fail open only for unlinked
+  // candidates: rewriting any product-linked price could corrupt another item.
+  return currentHandle == null || linkedHandle !== currentHandle;
+}
+
+function isLinkedToDifferentProduct(
+  node: Text,
+  currentHandle: string | null,
+): boolean {
+  return node.parentElement
+    ? isElementLinkedToDifferentProduct(node.parentElement, currentHandle)
+    : currentHandle == null;
+}
+
+function currentVariantId(
+  variants: Array<{ id?: string | number; price?: string | number }>,
+): string | null {
+  const currentHandle = currentProductHandle();
+  const productForm = Array.from(
+    document.querySelectorAll<HTMLFormElement>('form[action*="/cart/add"]'),
+  ).find((form) => !isElementLinkedToDifferentProduct(form, currentHandle));
+  const selected = productForm?.querySelector<
+    HTMLInputElement | HTMLSelectElement
+  >(
+    "[name=id][type=radio]:checked,select[name=id],input[name=id]:not([type=radio])",
+  )?.value;
+  if (selected && variants.some((variant) => String(variant.id) === selected))
+    return selected;
+  const urlVariant = new URL(location.href).searchParams.get("variant");
+  if (
+    urlVariant &&
+    variants.some((variant) => String(variant.id) === urlVariant)
+  )
+    return urlVariant;
+  return variants.length === 1 && variants[0]?.id != null
+    ? String(variants[0].id)
+    : null;
+}
+
+function swapPass(): void {
+  if (!current || applying) return;
+  const stampStatus = hasActiveChargedPrice(
+    current.settings,
+    current.assignments,
+    current.isAssignmentAuthorized,
+  )
+    ? current.isCohortStampedOnCart()
+    : true;
+  if (stampStatus === false) {
+    cleanupCommercePrice();
+    return;
+  }
+  if (stampStatus === "pending") scheduleStampCheck();
+  applying = true;
+  try {
+    const active = activeExperiments(
+      current.settings,
+      current.assignments,
+      current.isAssignmentAuthorized,
+    );
+    const variants = (window as ShopifyWindow).ShopifyAnalytics?.meta?.product
+      ?.variants;
+    if (!active.length || !Array.isArray(variants)) return;
+    const currency = active[0]!.currency;
+    const minorUnits = ZERO_DECIMAL.test(currency) ? 0 : 2;
+    // ShopifyAnalytics keeps prices on Shopify's two-decimal stored scale even
+    // when the storefront formats a zero-decimal currency such as JPY.
+    const shopifyStoredScale = minorUnits ? 1 : 100;
+    const published = new Map<string, number>();
+    for (const variant of variants) {
+      const price = Number(variant.price);
+      if (variant.id != null && Number.isSafeInteger(price) && price >= 0)
+        published.set(String(variant.id), price);
+    }
+    const selectedByVariant = new Map<string, string>();
+    for (const candidate of active) {
+      for (const adjustment of candidate.experiment.variants[
+        candidate.assignment.variationId
+      ]) {
+        if (typeof adjustment.fixedPricePerUnit !== "string") continue;
+        const id = adjustment.variant_gid.split("/").pop();
+        if (!id || !published.has(id)) continue;
+        const selected = selectedByVariant.get(id);
+        if (
+          selected == null ||
+          isStrictlyLowerPrice(adjustment.fixedPricePerUnit, selected)
+        ) {
+          selectedByVariant.set(id, adjustment.fixedPricePerUnit);
+        }
+      }
+    }
+    const compareByVariant = new Map<
+      string,
+      {
+        compare: { mode: "set"; amount: string } | { mode: "clear" };
+        assignment: Assignment;
+      }
+    >();
+    // Launch-side conflict screening rejects concurrent price tests on one
+    // variant, but the projection can still briefly carry both. Deterministic
+    // tie-break instead of last-iterated-wins: process in experiment-id order
+    // and keep the FIRST adjustment per variant, so every shopper session
+    // resolves the same collision identically.
+    const compareCandidates = [...active].sort((left, right) =>
+      left.experiment.experiment_id < right.experiment.experiment_id ? -1 : 1,
+    );
+    for (const candidate of compareCandidates) {
+      for (const adjustment of candidate.experiment.variants[
+        candidate.assignment.variationId
+      ]) {
+        const id = adjustment.variant_gid.split("/").pop();
+        if (
+          id &&
+          published.has(id) &&
+          adjustment.compareAt &&
+          !compareByVariant.has(id)
+        ) {
+          compareByVariant.set(id, {
+            compare: adjustment.compareAt,
+            assignment: candidate.assignment,
+          });
+        }
+      }
+    }
+    const targets = new Map<number, number>();
+    // The Function records every colliding experiment but charges the lowest
+    // authorized match. Keep every assignment exposure-eligible while using
+    // that same winner solely for the shopper-facing display.
+    for (const [id, fixedPricePerUnit] of selectedByVariant) {
+      const source = published.get(id);
+      const treatmentDisplayAmount = treatmentUnits(
+        fixedPricePerUnit,
+        minorUnits,
+      );
+      // The display plane must mirror the Cart Transform's decrease-only
+      // invariant. Invalid, equal, or higher treatment prices fail closed.
+      if (
+        source == null ||
+        treatmentDisplayAmount == null ||
+        treatmentDisplayAmount * shopifyStoredScale >= source
+      )
+        continue;
+      if (source % shopifyStoredScale) continue;
+      const sourceDisplayAmount = source / shopifyStoredScale;
+      const existing = targets.get(sourceDisplayAmount);
+      targets.set(
+        sourceDisplayAmount,
+        existing == null || existing === treatmentDisplayAmount
+          ? treatmentDisplayAmount
+          : NaN,
+      );
+    }
+    // Compare-at framing must describe a real discount. Reject malformed,
+    // equal, or lower reference prices instead of hiding the theme's native
+    // framing and manufacturing a false sale signal.
+    for (const [id, { compare }] of compareByVariant) {
+      if (compare.mode !== "set") continue;
+      const source = published.get(id);
+      const compareAmount = treatmentUnits(compare.amount, minorUnits);
+      const sourceAmount =
+        source != null && source % shopifyStoredScale === 0
+          ? source / shopifyStoredScale
+          : null;
+      const displayedAmount =
+        sourceAmount == null ? null : targets.get(sourceAmount) || sourceAmount;
+      if (
+        compareAmount == null ||
+        displayedAmount == null ||
+        compareAmount <= displayedAmount
+      ) {
+        compareByVariant.delete(id);
+      }
+    }
+    // A later DOM/variant pass can invalidate previously rendered framing.
+    // Continue through reconciliation when display eligibility was previously
+    // granted so stale treatment UI and exposure state are both withdrawn.
+    if (
+      !targets.size &&
+      !compareByVariant.size &&
+      renderedDisplayAssignment === null
+    )
+      return;
+
+    const productHandle = currentProductHandle();
+    const exclusion = COMMERCE_PRICE_EXCLUSIONS.join(",");
+    const containers = Array.from(
+      document.querySelectorAll(COMMERCE_PRICE_SELECTORS.join(",")),
+    );
+    const selectedVariantId = currentVariantId(variants);
+    const selectedCompare = selectedVariantId
+      ? compareByVariant.get(selectedVariantId)
+      : undefined;
+    const compare = selectedCompare?.compare;
+    let nextRenderedDisplayAssignment: Assignment | null = null;
+    compareAtNodes = compareAtNodes.filter((node) => node.isConnected);
+    const removeInjectedFraming = () => {
+      for (const node of compareAtNodes) node.remove();
+      compareAtNodes = [];
+    };
+    const removeApexCompareAt = () => {
+      removeInjectedFraming();
+      for (const [node, display] of hiddenCompareAtNodes)
+        node.style.display = display;
+      hiddenCompareAtNodes = new Map();
+    };
+    if (compare) {
+      const existingCompareNodes = new Set<HTMLElement>();
+      for (const container of containers) {
+        if (isElementLinkedToDifferentProduct(container, productHandle))
+          continue;
+        const scope = container.parentElement ?? container;
+        for (const existing of Array.from(
+          scope.querySelectorAll<HTMLElement>(exclusion),
+        )) {
+          if (existing.hasAttribute("data-apex-compare-at")) continue;
+          if (isElementLinkedToDifferentProduct(existing, productHandle))
+            continue;
+          existingCompareNodes.add(existing);
+        }
+      }
+      for (const existing of existingCompareNodes) {
+        if (!hiddenCompareAtNodes.has(existing))
+          hiddenCompareAtNodes.set(existing, existing.style.display);
+        existing.style.display = "none";
+      }
+      if (compare.mode === "set") {
+        const amount = treatmentUnits(compare.amount, minorUnits);
+        const source = selectedVariantId
+          ? published.get(selectedVariantId)
+          : undefined;
+        // The current price is read from Shopify and is never replaced for a
+        // compare-at-only arm. Only add merchant-authored reference framing.
+        if (amount != null && source != null) {
+          const eligible = containers.filter(
+            (container) =>
+              !isElementLinkedToDifferentProduct(container, productHandle),
+          );
+          // Prefer a LEAF price node: an outer wrapper's textContent bundles
+          // regular/sale/compare labels, and cloning it into the injected <s>
+          // renders duplicated or garbled prices.
+          const selector = COMMERCE_PRICE_SELECTORS.join(",");
+          const leaves = eligible.filter(
+            (container) => !container.querySelector(selector),
+          );
+          for (const container of leaves.length > 0 ? leaves : eligible) {
+            let node =
+              container.parentElement?.querySelector<HTMLElement>(
+                "[data-apex-compare-at]",
+              ) ?? null;
+            if (!node) {
+              node = document.createElement("s");
+              node.dataset.apexCompareAt = "true";
+              node.className = "apex-compare-at";
+              container.parentElement?.insertBefore(node, container);
+              compareAtNodes.push(node);
+            }
+            const sourceDisplayAmount = source / shopifyStoredScale;
+            const currentText = container.textContent ?? "";
+            const parsedCurrent = parseDisplayedCents(currentText, minorUnits);
+            // A node whose text still holds several amounts is not safe to
+            // clone-and-replace; format only the configured amount using the
+            // leaf's convention.
+            const singleAmount = parsedCurrent
+              ? parseDisplayedCents(
+                  currentText.slice(0, parsedCurrent.start) +
+                    currentText.slice(parsedCurrent.end),
+                  minorUnits,
+                ) === null
+              : false;
+            const nextText = singleAmount
+              ? (replaceNumericText(
+                  currentText,
+                  new Map([[sourceDisplayAmount, amount]]),
+                  minorUnits,
+                ) ??
+                (parsedCurrent
+                  ? currentText.slice(0, parsedCurrent.start) +
+                    formatCentsLike(amount, parsedCurrent.convention) +
+                    currentText.slice(parsedCurrent.end)
+                  : compare.amount))
+              : parsedCurrent
+                ? formatCentsLike(amount, parsedCurrent.convention)
+                : compare.amount;
+            if (node.textContent !== nextText) node.textContent = nextText;
+          }
+          if (compareAtNodes.some((node) => node.isConnected)) {
+            nextRenderedDisplayAssignment = selectedCompare!.assignment;
+          }
+          if (eligible.length === 0) removeApexCompareAt();
+        } else removeApexCompareAt();
+      }
+      // A clear arm's treatment IS the hidden native strikethrough: remove
+      // only injected framing and keep the natives hidden until the
+      // assignment ends or the variant's mode changes.
+      if (compare.mode === "clear") {
+        removeInjectedFraming();
+        if (hiddenCompareAtNodes.size > 0) {
+          nextRenderedDisplayAssignment = selectedCompare!.assignment;
+        }
+      }
+    } else {
+      removeApexCompareAt();
+    }
+    for (const container of containers) {
+      if (container.matches(exclusion) || container.closest(exclusion))
+        continue;
+      const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+      let node: Text | null;
+      while ((node = walker.nextNode() as Text | null)) {
+        if (node.parentElement?.closest(exclusion)) continue;
+        if (isLinkedToDifferentProduct(node, productHandle)) continue;
+        const replacement = replaceNumericText(node.data, targets, minorUnits);
+        if (replacement == null || replacement === node.data) continue;
+        applyAccessibleLabel(node, container, targets, minorUnits);
+        const previous = originals.get(node);
+        originals.set(node, {
+          original:
+            previous && node.data === previous.applied
+              ? previous.original
+              : node.data,
+          applied: replacement,
+        });
+        node.data = replacement;
+      }
+    }
+    observer?.disconnect();
+    rootObserver?.disconnect();
+    observer = new MutationObserver(guardedSwapPass);
+    containers.forEach((container) =>
+      observer!.observe(container, {
+        childList: true,
+        characterData: true,
+        subtree: true,
+      }),
+    );
+    rootObserver = new MutationObserver((records) => {
+      const selector = COMMERCE_PRICE_SELECTORS.join(",");
+      if (
+        records.some((record) =>
+          Array.from(record.addedNodes).some(
+            (node) =>
+              node instanceof Element &&
+              (node.matches(selector) || Boolean(node.querySelector(selector))),
+          ),
+        )
+      )
+        guardedSwapPass();
+    });
+    rootObserver.observe(document.body, { childList: true, subtree: true });
+    const eligibilityChanged =
+      nextRenderedDisplayAssignment !== renderedDisplayAssignment;
+    renderedDisplayAssignment = nextRenderedDisplayAssignment;
+    if (eligibilityChanged) exposureChanged?.();
+    const nextVariantForm =
+      Array.from(
+        document.querySelectorAll<HTMLFormElement>('form[action*="/cart/add"]'),
+      ).find(
+        (form) => !isElementLinkedToDifferentProduct(form, productHandle),
+      ) ?? null;
+    if (variantForm !== nextVariantForm) {
+      variantForm?.removeEventListener("change", handleVariantFormEvent);
+      variantForm?.removeEventListener("input", handleVariantFormEvent);
+      variantForm = nextVariantForm;
+      variantForm?.addEventListener("change", handleVariantFormEvent);
+      variantForm?.addEventListener("input", handleVariantFormEvent);
+    }
+  } finally {
+    applying = false;
+  }
+}
+
+function activateCommercePrice(
+  settings: CommercePriceSettings,
+  assignments: Assignment[],
+  isCohortStampedOnCart: () => boolean | "pending",
+  deadline: number,
+  onResolved?: () => void,
+  isAssignmentAuthorized: PriceAssignmentAuthorization = () => true,
+): void {
+  const stampStatus = hasActiveChargedPrice(
+    settings,
+    assignments,
+    isAssignmentAuthorized,
+  )
+    ? isCohortStampedOnCart()
+    : true;
+  if (stampStatus === "pending") {
+    if (stampCheckDeadline === 0) {
+      stampCheckDeadline = Date.now() + STAMP_CONFIRM_TIMEOUT_MS;
+    }
+    if (Date.now() >= stampCheckDeadline) {
+      cancelStampCheck();
+      const resolve = pendingActivation?.onResolved ?? onResolved;
+      if (pendingActivation) pendingActivation.onResolved = undefined;
+      resolve?.();
+      return;
+    }
+    if (stampCheckTimer == null) {
+      stampCheckTimer = setTimeout(() => {
+        stampCheckTimer = null;
+        activateCommercePrice(
+          settings,
+          assignments,
+          isCohortStampedOnCart,
+          deadline,
+          onResolved,
+          isAssignmentAuthorized,
+        );
+      }, 25);
+    }
+    return;
+  }
+  cancelStampCheck();
+  if (stampStatus === false) {
+    pendingActivation = null;
+    // No cohort on the cart: the Function cannot charge the tested price, so the
+    // published price must stay on screen. Resolve the reveal barrier immediately.
+    cancelMetaRetry();
+    onResolved?.();
+    return;
+  }
+  if (!isCommercePriceActive(settings, assignments, isAssignmentAuthorized)) {
+    // Retry only while the page could still BECOME eligible — i.e. Shopify has not
+    // published product metadata yet. Every other inactive reason (control cohort,
+    // currency mismatch, non-product page) is final and must not spin.
+    if (!shopifyProductMetaReady() && Date.now() < deadline) {
+      metaRetryTimer = setTimeout(
+        () =>
+          activateCommercePrice(
+            settings,
+            assignments,
+            isCohortStampedOnCart,
+            deadline,
+            onResolved,
+            isAssignmentAuthorized,
+          ),
+        META_RETRY_INTERVAL_MS,
+      );
+      return;
+    }
+    // Activation is final and inactive — release the reveal barrier.
+    cancelMetaRetry();
+    pendingActivation = null;
+    onResolved?.();
+    return;
+  }
+  cancelMetaRetry();
+  pendingActivation = null;
+  current = {
+    settings,
+    assignments,
+    isCohortStampedOnCart,
+    isAssignmentAuthorized,
+  };
+  try {
+    swapPass();
+  } catch {
+    cleanupCommercePrice();
+  }
+  // The swap has landed (or failed and restored): content may be revealed.
+  onResolved?.();
+}
+
+export function applyCommercePrice(
+  settings: CommercePriceSettings | undefined,
+  assignments: Assignment[],
+  isCohortStampedOnCart: () => boolean | "pending" = () => false,
+  onResolved?: () => void,
+  isAssignmentAuthorized: PriceAssignmentAuthorization = () => true,
+): void {
+  cleanupCommercePrice();
+  if (!settings) {
+    onResolved?.();
+    return;
+  }
+  const deadline = Date.now() + META_RETRY_WINDOW_MS;
+  pendingActivation = {
+    settings,
+    assignments,
+    isCohortStampedOnCart,
+    deadline,
+    onResolved,
+    isAssignmentAuthorized,
+  };
+  activateCommercePrice(
+    settings,
+    assignments,
+    isCohortStampedOnCart,
+    deadline,
+    onResolved,
+    isAssignmentAuthorized,
+  );
+}
+
+/** Revisit a timed-out activation when the in-flight Shopify cart write lands. */
+export function notifyCommerceCartStampConfirmed(): void {
+  if (!pendingActivation) return;
+  const activation = pendingActivation;
+  activation.deadline = Math.max(
+    activation.deadline,
+    Date.now() + META_RETRY_WINDOW_MS,
+  );
+  activateCommercePrice(
+    activation.settings,
+    activation.assignments,
+    activation.isCohortStampedOnCart,
+    activation.deadline,
+    activation.onResolved,
+    activation.isAssignmentAuthorized,
+  );
+}
+
+/** Whether a display-only price assignment has produced shopper-visible framing. */
+export function isCommercePriceExposureEligible(
+  settings: CommercePriceSettings | undefined,
+  assignment: Assignment,
+): boolean {
+  const adjustments = settings?.experiments.find(
+    (experiment) => experiment.experiment_id === assignment.experimentId,
+  )?.variants[assignment.variationId];
+  return Boolean(
+    assignment.isControl ||
+    !adjustments?.some((adjustment) => adjustment.compareAt) ||
+    adjustments.some(
+      (adjustment) => typeof adjustment.fixedPricePerUnit === "string",
+    ) ||
+    renderedDisplayAssignment === assignment,
+  );
+}
+
+export const setCommercePriceExposureListener = (listener: () => void) => {
+  exposureChanged = listener;
+};
+
+export function cleanupCommercePrice(): void {
+  observer?.disconnect();
+  observer = null;
+  rootObserver?.disconnect();
+  rootObserver = null;
+  variantForm?.removeEventListener("change", handleVariantFormEvent);
+  variantForm?.removeEventListener("input", handleVariantFormEvent);
+  variantForm = null;
+  for (const [node, value] of originals) node.data = value.original;
+  originals = new Map();
+  for (const [element, value] of originalAriaLabels)
+    element.setAttribute("aria-label", value.original);
+  originalAriaLabels = new Map();
+  for (const node of compareAtNodes) node.remove();
+  compareAtNodes = [];
+  for (const [node, display] of hiddenCompareAtNodes)
+    node.style.display = display;
+  hiddenCompareAtNodes = new Map();
+  renderedDisplayAssignment = null;
+  current = null;
+  pendingActivation = null;
+  applying = false;
+  cancelMetaRetry();
+  cancelStampCheck();
+}