@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/qa-browser.mjs

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import { runWithDeadline } from "./deadline.mjs";
 import { PLACEHOLDER_TEXT_ASSERTION_SUFFIX, SEVERITY, STATUS } from "./qa-verdict.mjs";
 import { contrastToolkit } from "./contrast.mjs";
+import { boundedPolishDeadline } from "./polish-deadline.mjs";
 import { generatedTextRenders } from "./polish-readability.mjs";
 import {
   analyticsCaptureError,
@@ -16,7 +17,7 @@ import { attachAnalyticsCapture, diffAnalyticsParity } from "./qa-analytics-pari
 import { assessAnalyticsInventory } from "./qa-analytics-correctness.mjs";
 import { redactPersisted, redactUrlQueriesInText, redactUrlQuery } from "./qa-url-privacy.mjs";
 import { TRACKING_ADDED_BOUND_MS, TRACKING_OBSERVATION, createTrackingRun, trackingQaAssertion } from "./qa-tracking-params.mjs";
-import { runContentParamChecks } from "./qa-content-params.mjs";
+import { CONTENT_PARAM_LIMITS, runContentParamChecks } from "./qa-content-params.mjs";
 import { createPolicyLinkBudget, hasPolicyLinkFields, readPageAnchors, runPolicyLinkChecks } from "./qa-policy-links.mjs";
 import {
   canonicalHttpUrl,
@@ -77,6 +78,22 @@ const DEFAULT_TEST_CARD = "6011111111111117";
 const DEFAULT_TEST_CVV = "123";
 const DEFAULT_TEST_EXP_MONTH = "12";
 const DEFAULT_TEST_EXP_YEAR = "2030";
+// The card number and CVV iframes, matched by id prefix because each id ends
+// in a per-load suffix. SDK 0.4.40 and earlier mount Spreedly's iFrame v1
+// (spreedly-number-frame-1234); 0.4.41 mounts the Spreedly Checkout SDK fields
+// that NEXT's payments.29next.com/js/v1/payment.js loads
+// (spreedly-hosted-number-oujmii2uzjk). A page carries one generation or the
+// other, and each frame holds a single text input. fillPaymentFields refuses
+// by name unless exactly one number frame and one CVV frame match, so a page
+// mounting both generations, or two forms, fails at the card step instead of
+// on whichever frame happens to come first.
+const CARD_NUMBER_FRAME = 'iframe[id^="spreedly-number-frame"], iframe[id^="spreedly-hosted-number"]';
+const CARD_CVV_FRAME = 'iframe[id^="spreedly-cvv-frame"], iframe[id^="spreedly-hosted-cvv"]';
+// Typing the card is read back and retried this many times in all before the
+// card step fails by name.
+const CARD_TYPE_ATTEMPTS = 3;
+// How long the card step waits for the SDK to report the card fields ready.
+const CARD_READY_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_TEST_ORDERS = 6;
 // Planned-path ids listed in a refused --max-test-orders message before the
 // remainder is counted rather than printed.
@@ -143,13 +160,17 @@ export async function runBrowserChecks(topologies, args = {}, options = {}) {
     // Content parameters (options.spec analytics.params.content), after the
     // page checks: every load in its own fresh context with the same options,
     // closed after the load. The rows go to options.qcResults; their verdict
-    // assertions join the page checks'.
+    // assertions join the page checks'. options.contentParamLimits is an
+    // in-process test seam (never set from argv) that can only tighten the
+    // leg's CONTENT_PARAM_LIMITS, so a test of the budget or the readiness
+    // wait need not sit through the production bound.
     if (Array.isArray(options.qcResults)) {
       const contentParams = await runContentParamChecks({
         topologies,
         spec: options.spec,
         newContext: () => browser.newContext(contextOptions),
         withQueryParam,
+        limits: contentParamLimitsFrom(options.contentParamLimits),
       });
       options.qcResults.push(...contentParams.rows);
       assertions.push(...contentParams.assertions);
@@ -1297,7 +1318,7 @@ function sdkDebuggerEligible(page) {
 
 async function primaryCtaVisualAssertions(browserPage, page) {
   if (!primaryCtaCheckEligible(page)) return [];
-  const evidence = await inspectPrimaryCta(browserPage, page.expected_next_url);
+  const evidence = await inspectPrimaryCta(browserPage, page.expected_next_url, primaryCtaDeclaredRoutes(page), primaryCtaRoutelessForms(page));
   return [primaryCtaAssertionFromEvidence(page, evidence)];
 }
 
@@ -1305,6 +1326,52 @@ function primaryCtaCheckEligible(page) {
   return Boolean(page?.expected_next_url);
 }
 
+// Checkout, upsell and downsell: the page types whose forward controls go
+// where the page declares, not where they point.
+function primaryCtaPageRoutesSdkControls(page) {
+  const pageType = String(page?.page_type || "").toLowerCase();
+  return pageType === "checkout" || OFFER_PAGE_TYPES.has(pageType);
+}
+
+// The forms whose action is no route on this page, handed to the route rule
+// as its checkout-form selector. On a checkout, upsell or downsell the only
+// form-borne route is the one the page declares for its SDK control
+// (primaryCtaDeclaredRoutes), so no form's action is a route there: a
+// newsletter or search form beside the checkout form does not make its
+// submit button the route control. Elsewhere only the SDK checkout form,
+// which the SDK submits itself.
+function primaryCtaRoutelessForms(page) {
+  return primaryCtaPageRoutesSdkControls(page) ? "form" : CHECKOUT_FORM_SELECTOR;
+}
+
+// The SDK controls on this page that go to a route the page declares rather
+// than one they carry, each with that route: on a checkout, the checkout
+// form's submit button goes to the success route (the page's forward route);
+// on an upsell or downsell, each SDK upsell action goes to its accept or
+// decline route. The routes are the topology fields the static route-link
+// rows read, and the actions are the rendered upsell-control check's table.
+// A control is a route candidate when its route is the expected next route,
+// like any other. The submit button is any button that submits the form, so a
+// typeless one too, but not an express-checkout wallet button, which starts
+// the wallet flow; an upsell action counts only inside a [data-next-upsell]
+// container, the only place the SDK binds it.
+function primaryCtaDeclaredRoutes(page) {
+  if (!primaryCtaPageRoutesSdkControls(page)) return [];
+  if (String(page.page_type).toLowerCase() === "checkout") {
+    const notWallet = ":not([data-next-express-checkout]):not([data-next-express-checkout] *)";
+    const submit = ['button[type="submit"]', "button:not([type])", 'input[type="submit"]']
+      .map((control) => `${CHECKOUT_FORM_SELECTOR} ${control}${notWallet}`)
+      .join(", ");
+    return page.expected_next_url ? [{ selector: submit, url: page.expected_next_url }] : [];
+  }
+  return UPSELL_CONTROL_ROUTES
+    .filter(({ field }) => page[field])
+    .map(({ kind, field }) => ({
+      selector: UPSELL_ACTION_SPELLINGS[kind].map((action) => `[data-next-upsell] ${upsellActionSelector(action)}`).join(", "),
+      url: page[field],
+    }));
+}
+
 // Candidate CTAs: anything clickable, plus every SDK action control and the
 // SDK cart-entry control (the same locator the ladder's entry step and
 // advanceToCheckoutForm use). Only attributes the SDK declares are listed —
@@ -1320,19 +1387,21 @@ const PRIMARY_CTA_SELECTOR = ["a[href]", "button", "[role='button']", "[data-nex
 // stay free of module-scope references: the text is run in a fresh context by
 // a test (primary-CTA inspection script is self-contained) that would surface
 // a leaked identifier as a ReferenceError.
-function primaryCtaInspectionScript(expectedUrl) {
+function primaryCtaInspectionScript(expectedUrl, declaredRoutes = [], checkoutFormSelector = CHECKOUT_FORM_SELECTOR) {
   const args = {
     routeUrl: expectedUrl,
     ctaSelector: PRIMARY_CTA_SELECTOR,
     cartEntrySelector: CART_ENTRY_CONTROL_SELECTOR,
     cartEntryRouteAttribute: CART_ENTRY_ROUTE_ATTRIBUTE,
+    declaredRoutes,
+    checkoutFormSelector,
     ignoredRouteAttributes: [...UNDECLARED_ROUTE_ATTRIBUTES],
   };
   return `(${inspectPrimaryCtaScript.toString()})(${JSON.stringify(args)}, ${cartEntryHrefFor.toString()}, ${contrastToolkit.toString()}, ${generatedTextRenders.toString()})`;
 }
 
-async function inspectPrimaryCta(browserPage, expectedUrl) {
-  return browserPage.evaluate(primaryCtaInspectionScript(expectedUrl)).catch((error) => ({
+async function inspectPrimaryCta(browserPage, expectedUrl, declaredRoutes = [], checkoutFormSelector = CHECKOUT_FORM_SELECTOR) {
+  return browserPage.evaluate(primaryCtaInspectionScript(expectedUrl, declaredRoutes, checkoutFormSelector)).catch((error) => ({
     ok: false,
     reason: "inspection_error",
     expected_url: expectedUrl,
@@ -1342,7 +1411,7 @@ async function inspectPrimaryCta(browserPage, expectedUrl) {
   }));
 }
 
-function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, ignoredRouteAttributes }, hrefForImpl, contrastToolkitImpl, generatedTextImpl) {
+function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, cartEntryRouteAttribute, declaredRoutes, checkoutFormSelector, ignoredRouteAttributes }, hrefForImpl, contrastToolkitImpl, generatedTextImpl) {
   const CTA_SELECTOR = ctaSelector;
   const toolkit = contrastToolkitImpl();
 
@@ -1375,9 +1444,9 @@ function inspectPrimaryCtaScript({ routeUrl, ctaSelector, cartEntrySelector, car
       .join("");
     return `${tag}${id}${classes}`;
   };
-  // The route a control leads to: the shared cart-entry rule, evaluated
-  // against this document's origin and base.
-  const hrefFor = (element) => hrefForImpl(element, { cartEntrySelector, cartEntryRouteAttribute, origin: location.origin, baseHref: location.href });
+  // The route a control leads to: the shared cart-entry rule, with the
+  // page's declared routes, evaluated against this document's origin and base.
+  const hrefFor = (element) => hrefForImpl(element, { cartEntrySelector, cartEntryRouteAttribute, declaredRoutes, checkoutFormSelector, origin: location.origin, baseHref: location.href });
   // Route-shaped attributes the element carries that the rule above does not
   // consult: the undeclared spellings, plus the SDK route attribute on an
   // element that is not an SDK control (a decoy, not a route). Reported, not
@@ -1566,15 +1635,48 @@ function primaryCtaAssertionFromEvidence(page, evidence) {
   });
 }
 
+// The SDK's spellings of each upsell action: its upsell handler accepts the
+// offer on add or accept and declines it on skip or decline, and does nothing
+// on any other value. Every place QA locates an upsell control reads this one
+// table. The first spelling is the one reported when a page has none.
+export const UPSELL_ACTION_SPELLINGS = Object.freeze({
+  accept: Object.freeze(["add", "accept"]),
+  decline: Object.freeze(["skip", "decline"]),
+});
+
+// The SDK upsell actions and the page field that declares where each goes.
+// The rendered upsell-control check and the primary-CTA route rule read this
+// one table.
+const UPSELL_CONTROL_ROUTES = Object.freeze([
+  Object.freeze({ kind: "accept", field: "expected_accept_url" }),
+  Object.freeze({ kind: "decline", field: "expected_decline_url" }),
+]);
+
+function upsellActionSelector(...actions) {
+  return actions.map((action) => `[data-next-upsell-action="${action}"]`).join(", ");
+}
+
+// The spelling of an upsell action this page renders: the first spelling
+// present, or the first spelling when the page has none.
+async function presentUpsellAction(page, kind) {
+  const spellings = UPSELL_ACTION_SPELLINGS[kind];
+  for (const action of spellings) {
+    if (await page.locator(upsellActionSelector(action)).first().count().catch(() => 0)) return action;
+  }
+  return spellings[0];
+}
+
 async function renderedUpsellControlAssertions(browserPage, page) {
-  const checks = [
-    ["accept", "add", page.expected_accept_url],
-    ["decline", "skip", page.expected_decline_url],
-  ];
   const assertions = [];
-  for (const [kind, action, expectedUrl] of checks) {
+  for (const { kind, field } of UPSELL_CONTROL_ROUTES) {
+    const expectedUrl = page[field];
     if (!expectedUrl) continue;
-    const count = await browserPage.locator(`[data-next-upsell-action="${action}"]`).count().catch(() => 0);
+    const spellings = UPSELL_ACTION_SPELLINGS[kind];
+    const counts = [];
+    for (const action of spellings) counts.push(await browserPage.locator(upsellActionSelector(action)).count().catch(() => 0));
+    const count = counts.reduce((sum, n) => sum + n, 0);
+    const present = spellings.filter((_, index) => counts[index] > 0);
+    const selector = upsellActionSelector(...(present.length ? present : spellings.slice(0, 1)));
     assertions.push(assertion({
       id: `browser-upsell-control:${page.page_id}:${kind}`,
       family: "browser-runtime",
@@ -1583,7 +1685,7 @@ async function renderedUpsellControlAssertions(browserPage, page) {
       severity: count > 0 ? undefined : SEVERITY.WARN,
       expected: `rendered SDK ${kind} control`,
       actual: count > 0 ? `${count} matching control(s)` : "not found",
-      evidence: { selector: `[data-next-upsell-action="${action}"]`, expected_url: expectedUrl },
+      evidence: { selector, expected_url: expectedUrl },
     }));
   }
   return assertions;
@@ -1614,7 +1716,7 @@ async function checkoutPaymentSurfaceAssertions(browserPage, page) {
       card_number_selector: '[data-next-checkout-field="cc-number"], #spreedly-number',
       cvv_selector: '[data-next-checkout-field="cvv"], #spreedly-cvv',
       spreedly_frame_urls: spreedlyFrames.map((frame) => frame.url()).slice(0, 5),
-      next_step: "Run --test-order common for typed-card checkout proof (test cards bypass the gateway; no approval needed).",
+      next_step: "Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing test orders, which leave real store order records. Then run --test-order common for typed-card checkout proof (test cards bypass the gateway and create no transactions; no permission flag).",
     },
   }), assertion({
     id: `browser-payment-geometry:${page.page_id}`,
@@ -3173,8 +3275,10 @@ function createFieldTrace() {
 // before the bounded ladder step starts and updated before each operation that
 // can hang. Its synchronous summary survives when the timeout wins the race.
 function createUpsellActionTrace({ page, events, topologyPlan, stepIndex, path, inspectTimeoutMs = 1000 }) {
-  const requestedAction = path === "accept" ? "add" : "skip";
-  const selector = `[data-next-upsell-action="${requestedAction}"]`;
+  // The spelling the page renders, read again at each inspection.
+  const kind = path === "accept" ? "accept" : "decline";
+  let requestedAction = UPSELL_ACTION_SPELLINGS[kind][0];
+  let selector = upsellActionSelector(requestedAction);
   let actionNavigationCount = Array.isArray(events?.navigations) ? events.navigations.length : 0;
   let actionUpsellRequestCount = (events?.requests || []).filter((request) => isOrderUpsellsUrl(request?.url)).length;
   let element = { present: null, visible: null, enabled: null };
@@ -3184,6 +3288,8 @@ function createUpsellActionTrace({ page, events, topologyPlan, stepIndex, path,
   let stepCompleted = false;
 
   const inspect = async () => {
+    requestedAction = await presentUpsellAction(page, kind);
+    selector = upsellActionSelector(requestedAction);
     const control = page.locator(selector).first();
     const count = await control.count().catch(() => 0);
     element = {
@@ -3729,6 +3835,9 @@ async function runSingleBrowserTestOrder(context, checkoutPage, plan, args, runI
         reserveOrderCreation,
         selectorProbeCache: options.selectorProbeCache,
         tracking,
+        // An in-process test seam only, like trackingTestHooks: unset in
+        // every production run, so the card step waits CARD_READY_TIMEOUT_MS.
+        cardReadyTimeoutMs: shorterBound(options.cardReadyTimeoutMs, CARD_READY_TIMEOUT_MS),
       }),
       orderTimeoutMs + ORDER_TIMEOUT_GRACE_MS,
       `order-path:${planId(normalizedPlan)}`,
@@ -3807,11 +3916,12 @@ function stablePrivateCaptureError(value) {
   return projectAnalyticsCaptureError(value, { fallbackKind: "unreadable" });
 }
 
-async function executeTestOrderPath({ page, events, email, ladder, checkoutPage, entryPage = null, topologyPlan, path, args, deadline, reserveOrderCreation = null, selectorProbeCache = null, tracking = null }) {
+async function executeTestOrderPath({ page, events, email, ladder, checkoutPage, entryPage = null, topologyPlan, path, args, deadline, reserveOrderCreation = null, selectorProbeCache = null, tracking = null, cardReadyTimeoutMs = CARD_READY_TIMEOUT_MS }) {
   const stepTimeoutMs = numberArg(args["step-timeout-ms"], DEFAULT_STEP_TIMEOUT_MS);
   const budget = () => Math.min(stepTimeoutMs, deadline - Date.now());
   const hostedNow = () => hostedRedirectInfo(safePageUrl(page), checkoutPage.url);
   const selectedPackages = parseCart(args["select-package"]);
+  const currencyLoad = pathCurrencyLoad(args);
   let checkoutDisplay = null;
   let cartBeforeSubmit = null;
 
@@ -3827,7 +3937,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
   // page the probe left there rather than loading the same URL a second time,
   // which would fire the SDK's page-view events twice into the same capture.
   const entry = await ladder.run(CART_ENTRY_STEP, () => enterCartViaLanding({
-    page, checkoutPage, entryPage, selectedPackages, args, budget, selectorProbeCache, tracking,
+    page, checkoutPage, entryPage, selectedPackages, args, budget, selectorProbeCache, tracking, currencyLoad,
   }), { timeoutMs: budget() });
   const enteredViaLanding = Boolean(entry && typeof entry === "object" && entry.entered);
   // Responses captured from here on belong to the checkout the ladder drives.
@@ -3835,17 +3945,18 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
   // made before the hand-off.
   const checkoutResponseOffset = events.responses.length;
 
-  await ladder.run("opened_checkout", () => openCheckoutForPath({ page, checkoutPage, entry, args, tracking }), { timeoutMs: budget() });
+  await ladder.run("opened_checkout", () => openCheckoutForPath({ page, checkoutPage, entry, args, tracking, currencyLoad }), { timeoutMs: budget() });
   await ladder.run("selected_bundle", async () => {
     // The requested package was selected on the entry page, where the cards
     // live; checkout renders none, so re-running strict selection here would
     // fail for the wrong reason.
+    const selectedCards = [];
     const strictSelection = enteredViaLanding && selectedPackages.length
       ? `selected on entry page: ${entry.package_id || "(no package id on control)"}`
-      : await selectRequestedPackages(page, selectedPackages);
-    await selectRequestedCart(page, args);
+      : await selectRequestedPackages(page, selectedPackages, selectedCards);
+    const unappliedCart = await selectRequestedCart(page, args, { selectedPackages, selectedCards });
     await advanceToCheckoutForm(page);
-    if (strictSelection) return `selected requested package card(s): ${strictSelection}`;
+    if (strictSelection) return `selected requested package card(s): ${[strictSelection, ...unappliedCart].join("; ")}`;
     return parseCart(args.cart).length ? `requested cart ${args.cart}` : "default bundle selection";
   }, { timeoutMs: budget() });
   await ladder.run("bump_state", async () => {
@@ -3868,7 +3979,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     }, { timeoutMs: budget() });
     await ladder.run("card_fields_filled", async () => {
       ensurePageFillable(page, checkoutPage.url);
-      await fillPaymentFields(page, args);
+      return fillPaymentFields(page, args, { readyTimeoutMs: cardReadyTimeoutMs });
     }, { timeoutMs: budget() });
     await ladder.run("cart_created", async () => {
       const cart = cartCreationEvidence(events);
@@ -3924,6 +4035,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     display: checkoutDisplay,
     events,
     selected_packages: selectedPackages,
+    requested_cart: parseCart(args.cart),
   });
   order.verification.total_parity = assessOrderTotalParity({
     display: checkoutDisplay,
@@ -4120,7 +4232,7 @@ function createSelectorProbeCache() {
 // loaded it and found a selection surface; either way a second load of the
 // same URL is what is avoided. Anywhere else (a cached probe answer skipped the
 // load; a fresh page) the checkout is opened here, once.
-async function openCheckoutForPath({ page, checkoutPage, entry, args, tracking = null }) {
+async function openCheckoutForPath({ page, checkoutPage, entry, args, tracking = null, currencyLoad = null }) {
   const enteredViaLanding = Boolean(entry && typeof entry === "object" && entry.entered);
   if (enteredViaLanding) {
     await page.waitForLoadState("networkidle", { timeout: DEFAULT_SETTLE_TIMEOUT_MS }).catch(() => {});
@@ -4129,14 +4241,14 @@ async function openCheckoutForPath({ page, checkoutPage, entry, args, tracking =
   if (checkoutUrlPredicate(checkoutPage.url)(safePageUrl(page))) {
     return "already on checkout from the selector probe; not re-opened";
   }
-  await gotoAndSettle(page, checkoutPage.url, args, tracking);
+  await gotoAndSettle(page, checkoutPage.url, args, tracking, currencyLoad);
   return null;
 }
 
 // The entry step body. Resolves to `{ skip }` when the checkout selects for
 // itself, to `{ entered: true, ... }` when the runner came in through the entry
 // page, and throws a coded error (never a bare timeout) when it cannot.
-async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPackages, args, budget, selectorProbeCache = null, tracking = null }) {
+async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPackages, args, budget, selectorProbeCache = null, tracking = null, currencyLoad = null }) {
   // Probe the checkout first: whether it carries a selection surface is a fact
   // about the rendered page, not about the spec (the spec cannot say it yet —
   // that is the design half of #206). The probe's load is the checkout's only
@@ -4153,7 +4265,7 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
   let probe = cached ? "reused" : "loaded";
   let probeError = null;
   if (!surface) {
-    await gotoAndSettle(page, checkoutPage.url, args, tracking);
+    await gotoAndSettle(page, checkoutPage.url, args, tracking, currencyLoad);
     const probed = await page.evaluate(checkoutSelectionSurfaceScript())
       .then((value) => ({ value }), (error) => ({ value: null, error: error?.message || String(error) }));
     if (probed.value) {
@@ -4179,7 +4291,7 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
     );
   }
 
-  await gotoAndSettle(page, entryPage.url, args, tracking);
+  await gotoAndSettle(page, entryPage.url, args, tracking, currencyLoad);
   const sdkReady = await waitForSdkReady(page, Math.min(budget(), DEFAULT_SETTLE_TIMEOUT_MS));
   await tracking?.readDocument(page);
   const controls = await page.evaluate(cartEntryControlsScript(), { selector: CART_ENTRY_CONTROL_SELECTOR, checkoutUrl: checkoutPage.url }).catch(() => []);
@@ -4475,24 +4587,149 @@ function assessReceiptRendering(persistedLineCount, evidence = {}) {
   };
 }
 
+// `qa run --currency <code>`, validated and upper-cased. qa-node.mjs sets it
+// after its own check; a symbol, so no command-line flag can set it, and a
+// command that never validates --currency (qa parity) never loads with one.
+export const QA_RUN_CURRENCY = Symbol("qa run --currency");
+
+// One order path's currency: added to the path's first runner load only —
+// the checkout probe, the entry page when the probe answer was reused, or the
+// checkout opened directly. Campaign Cart keeps a URL currency in session
+// storage for the rest of the tab's session, so later loads in the tab are
+// the plain URL; the receipt reload in recovery is not a path load at all.
+function pathCurrencyLoad(args) {
+  const code = args?.[QA_RUN_CURRENCY];
+  let pending = typeof code === "string" && /^[A-Z]{3}$/.test(code) ? code : null;
+  return (url) => {
+    if (!pending) return url;
+    const entered = withQueryParam(url, "currency", pending);
+    pending = null;
+    return entered;
+  };
+}
+
 // With a tracking observer, the load is a runner navigation: before the
-// attempt's first page-initiated hop it carries the run's synthetic seeds.
-async function gotoAndSettle(page, url, args, tracking = null) {
-  const target = tracking ? tracking.runnerUrl(url, withQueryParam) : url;
+// attempt's first page-initiated hop it carries the run's synthetic seeds,
+// after the path's currency when this is the load that carries one.
+async function gotoAndSettle(page, url, args, tracking = null, currencyLoad = null) {
+  const entered = currencyLoad ? currencyLoad(url) : url;
+  const target = tracking ? tracking.runnerUrl(entered, withQueryParam) : entered;
   await page.goto(target, { waitUntil: "domcontentloaded", timeout: numberArg(args["browser-timeout"], DEFAULT_BROWSER_TIMEOUT_MS) });
   await page.waitForLoadState("networkidle", { timeout: DEFAULT_SETTLE_TIMEOUT_MS }).catch(() => {});
   await page.waitForTimeout(750);
 }
 
-async function selectRequestedCart(page, args) {
+// Returns one note per --cart ref left unapplied beside a --select-package
+// selection; the selected_bundle step reports them.
+async function selectRequestedCart(page, args, { selectedPackages = [], selectedCards = [] } = {}) {
   const cart = parseCart(args.cart);
+  if (!cart.length) return [];
+  if (selectedPackages.length) return applyCartBesideSelection(page, cart, { selectedPackages, selectedCards });
+  // A package a bundle card declares, asked for at an explicit quantity, is
+  // chosen by the card whose items carry it at that quantity. The first
+  // [data-next-package-id] for that package is usually the one-unit card's
+  // inner node, so the plain click below would reset a multi-unit selection.
+  // A bare ref names no quantity and clicks that first node, as it always has.
+  // The cards are read again for each ref: a click may re-render the selector.
   for (const item of cart) {
+    const ref = String(item.packageId);
+    const bundleCards = (await renderedPackageCardCandidates(page))
+      .filter((candidate) => candidate.bundle_id && Array.isArray(candidate.items));
+    if (item.quantityExplicit && bundleCards.some((card) => card.items.some((entry) => entry.package_id === ref))) {
+      await selectCartBundleCard(page, bundleCards, item);
+      continue;
+    }
     const target = page.locator(packageCardClickSelector({ package_id: item.packageId })).first();
     if (await target.count().catch(() => 0)) {
       const perpetual = await scrollControlIntoView(target);
       await clickControl(target, { timeout: 5000, forceFallback: false, perpetual }).catch(() => {});
     }
   }
+  return [];
+}
+
+function cardCarriesPackage(candidate, ref) {
+  return String(candidate?.package_id || "") === ref
+    || String(candidate?.bundle_id || "") === ref
+    || (Array.isArray(candidate?.items) && candidate.items.some((entry) => String(entry?.package_id || "") === ref));
+}
+
+// --cart beside --select-package: the card --select-package chose stays
+// selected. A --cart ref that card carries is already applied. Any other ref
+// is applied through its own control (an order bump toggle, or a card in a
+// selector group --select-package did not choose in), never by clicking
+// another card in the chosen card's group. A ref only such a click could
+// satisfy is left unapplied and named, so the order and its reconciliation
+// stay those of the card actually selected.
+async function applyCartBesideSelection(page, cart, { selectedPackages, selectedCards }) {
+  const chosenIdentities = new Set(selectedCards.map(packageCardIdentity));
+  const strictRefs = selectedPackages.map((item) => String(item.packageId));
+  const unapplied = [];
+  for (const item of cart) {
+    const ref = String(item.packageId);
+    const label = `--cart ${ref}:${item.quantity}`;
+    const candidates = await renderedPackageCardCandidates(page, { placement: true });
+    // Cards chosen on this page, or (when the choice was made on an entry
+    // page) the selected cards that carry a --select-package ref.
+    const chosen = candidates.filter((candidate) => !candidate.toggle && (
+      chosenIdentities.has(packageCardIdentity(candidate))
+      || (candidate.selected && strictRefs.some((strictRef) => cardCarriesPackage(candidate, strictRef)))
+    ));
+    const carrying = chosen.find((candidate) => cardCarriesPackage(candidate, ref));
+    if (carrying) {
+      const declared = carrying.items?.find((entry) => entry.package_id === ref)?.quantity;
+      if (item.quantityExplicit && declared != null && declared !== item.quantity) {
+        unapplied.push(`${label} not applied: the card --select-package chose declares ${ref}:${declared}`);
+      }
+      continue;
+    }
+    // A card in no recognised selector container may share the chosen card's
+    // selection, so it is locked like a card in the chosen card's group.
+    const lockedGroups = new Set(chosen.map((candidate) => candidate.group));
+    const reachable = candidates.filter((candidate) => (
+      cardCarriesPackage(candidate, ref)
+      && (candidate.toggle || (candidate.group != null && !lockedGroups.has(candidate.group)))
+    ));
+    if (!reachable.length) {
+      unapplied.push(candidates.some((candidate) => cardCarriesPackage(candidate, ref))
+        ? `${label} not applied: only another card in the selector --select-package chose carries it`
+        : `${label} not applied: no rendered card or control carries it`);
+      continue;
+    }
+    let target = reachable.find((candidate) => candidate.toggle);
+    if (!target) {
+      const declaringCards = reachable.filter((candidate) => candidate.items?.some((entry) => entry.package_id === ref));
+      try {
+        target = declaringCards.length ? resolvePackageCardCandidate(declaringCards, item) : reachable[0];
+      } catch (error) {
+        unapplied.push(`${label} not applied: ${error.message}`);
+        continue;
+      }
+    }
+    const control = page.locator(PACKAGE_CARD_QUERY).nth(target.element_index);
+    const perpetual = await scrollControlIntoView(control);
+    await clickControl(control, { timeout: 5000, forceFallback: false, perpetual }).catch(() => {});
+  }
+  return unapplied;
+}
+
+// Best-effort, like the rest of --cart: a ref no card satisfies leaves the
+// selection alone, and reconciliation reports the quantity the order carried.
+async function selectCartBundleCard(page, bundleCards, item) {
+  const ref = String(item.packageId);
+  const { selected_bundle_items: selected = [] } = await checkoutDisplayEvidence(page);
+  if (selected.some((card) => card.items?.some((entry) => entry.package_id === ref && entry.quantity === item.quantity))) return;
+  let candidate;
+  try {
+    candidate = resolvePackageCardCandidate(bundleCards, item);
+  } catch {
+    return;
+  }
+  const target = page.locator(packageCardClickSelector(candidate)).first();
+  if (await target.count().catch(() => 0)) {
+    const perpetual = await scrollControlIntoView(target);
+    await clickControl(target, { timeout: 5000, forceFallback: false, perpetual }).catch(() => {});
+  }
 }
 
 // --- Strict package/bundle card selection (--select-package) ---
@@ -4502,16 +4739,17 @@ async function selectRequestedCart(page, args) {
 // strict variant: the requested card must exist, be clickable, and an explicit
 // quantity must visibly enter the selected state — otherwise the
 // selected_bundle step fails instead of driving the wrong tier.
-async function selectRequestedPackages(page, requested) {
+// `cards` collects the card each item selected, for --cart to leave alone.
+async function selectRequestedPackages(page, requested, cards = []) {
   if (!requested.length) return null;
   const details = [];
   for (const item of requested) {
-    details.push(await selectPackageCard(page, item));
+    details.push(await selectPackageCard(page, item, cards));
   }
   return details.join("; ");
 }
 
-async function selectPackageCard(page, item) {
+async function selectPackageCard(page, item, cards = []) {
   const candidate = resolvePackageCardCandidate(await renderedPackageCardCandidates(page), item);
   const selector = packageCardClickSelector(candidate);
   const target = page.locator(selector).first();
@@ -4533,14 +4771,36 @@ async function selectPackageCard(page, item) {
   if (packageCardProofIdentity(selected) !== packageCardProofIdentity(candidate)) {
     throw new Error(`--select-package ${item.packageId}: rendered card composition changed after click`);
   }
+  cards.push(selected);
   const quantity = item.quantity || 1;
   return `${item.packageId}:${quantity} via ${selector}${state === "unknown" ? " (card exposes no selected-state marker; composition verified)" : ""}`;
 }
 
-async function renderedPackageCardCandidates(page) {
-  return page.locator("[data-next-bundle-card], [data-next-selector-card], [data-next-package-id], [data-next-bundle-id]").evaluateAll((elements) => {
+const PACKAGE_CARD_QUERY = "[data-next-bundle-card], [data-next-selector-card], [data-next-package-id], [data-next-bundle-id]";
+
+// `placement` adds where each card sits: its selector group (an index valid
+// for this read only, null for a card in no recognised selector container,
+// whose own wrapper says nothing about which cards it swaps with), whether it
+// is selected, whether it is an order-bump
+// style toggle rather than a selector card, and the index of its element in
+// PACKAGE_CARD_QUERY so that one exact element can be clicked.
+async function renderedPackageCardCandidates(page, { placement = false } = {}) {
+  return page.locator(PACKAGE_CARD_QUERY).evaluateAll((elements, withPlacement) => {
     const cards = [];
     const seen = new Set();
+    const groups = new Map();
+    const groupOf = (card) => {
+      const container = card.closest("[data-next-bundle-selector], [data-next-selector-id], [data-next-cart-selector]");
+      if (!container) return null;
+      if (!groups.has(container)) groups.set(container, groups.size);
+      return groups.get(container);
+    };
+    const isSelected = (card) => (
+      card.classList.contains("next-selected")
+      || card.getAttribute("data-next-selected") === "true"
+      || card.getAttribute("aria-checked") === "true"
+      || card.querySelector('input[type="radio"], input[type="checkbox"]')?.checked === true
+    );
     const parseItems = (value) => {
       if (!value) return null;
       try {
@@ -4554,7 +4814,7 @@ async function renderedPackageCardCandidates(page) {
         return null;
       }
     };
-    for (const element of elements) {
+    for (const [index, element] of elements.entries()) {
       const card = element.closest("[data-next-bundle-card], [data-next-selector-card]") || element;
       if (seen.has(card)) continue;
       seen.add(card);
@@ -4571,10 +4831,19 @@ async function renderedPackageCardCandidates(page) {
       if (!items && packageId && Number.isFinite(declaredQuantity) && declaredQuantity > 0) {
         items = [{ package_id: packageId, quantity: declaredQuantity }];
       }
-      cards.push({ bundle_id: bundleId, package_id: packageId, items });
+      const candidate = { bundle_id: bundleId, package_id: packageId, items };
+      if (withPlacement) {
+        Object.assign(candidate, {
+          group: groupOf(card),
+          selected: isSelected(card),
+          toggle: Boolean(element.closest("[data-next-package-toggle], [data-next-toggle-card], [data-next-bump]")),
+          element_index: index,
+        });
+      }
+      cards.push(candidate);
     }
     return cards;
-  }).catch(() => []);
+  }, placement).catch(() => []);
 }
 
 function packageCardIdentity(candidate) {
@@ -4606,9 +4875,15 @@ function packageCardClickSelector(candidate) {
 function resolvePackageCardCandidate(candidates, item) {
   const ref = String(item?.packageId || "");
   const quantity = Number(item?.quantity || 1);
-  const matchingRef = (candidates || []).filter((candidate) => (
+  const identityMatches = (candidates || []).filter((candidate) => (
     String(candidate?.bundle_id || "") === ref || String(candidate?.package_id || "") === ref
   ));
+  // A bundle card's package identity is also the package its
+  // data-next-bundle-items declares, whether or not an inner node repeats it.
+  const matchingRef = (candidates || []).filter((candidate) => (
+    identityMatches.includes(candidate)
+    || (Array.isArray(candidate?.items) && candidate.items.some((entry) => String(entry?.package_id || "") === ref))
+  ));
   if (!matchingRef.length) {
     throw new Error(`--select-package ${ref}: no rendered card exposes that package or bundle identity`);
   }
@@ -4619,18 +4894,22 @@ function resolvePackageCardCandidate(candidates, item) {
     throw new Error(`--select-package ${ref}: rendered bundle identity is ambiguous across ${exactBundle.length} cards`);
   }
 
-  const exactComposition = matchingRef.filter((candidate) => (
+  // A card matches when one of its declared items is the package at that
+  // quantity, however many items it declares. A card declaring that item
+  // alone is preferred over one declaring it among others (a 2x tier over a
+  // 2x-plus-accessory kit); the kit stays reachable by its bundle id.
+  const declaringItem = matchingRef.filter((candidate) => (
     Array.isArray(candidate?.items)
-    && candidate.items.length === 1
-    && String(candidate.items[0]?.package_id || "") === ref
-    && Number(candidate.items[0]?.quantity) === quantity
+    && candidate.items.some((entry) => String(entry?.package_id || "") === ref && Number(entry?.quantity) === quantity)
   ));
+  const declaringOnlyItem = declaringItem.filter((candidate) => candidate.items.length === 1);
+  const exactComposition = declaringOnlyItem.length ? declaringOnlyItem : declaringItem;
   if (exactComposition.length === 1) return exactComposition[0];
   if (exactComposition.length > 1) {
     throw new Error(`--select-package ${ref}:${quantity}: rendered package composition is ambiguous across ${exactComposition.length} cards`);
   }
-  const unknownComposition = matchingRef.filter((candidate) => !Array.isArray(candidate?.items));
-  if (quantity === 1 && matchingRef.length === 1 && unknownComposition.length === 1) return unknownComposition[0];
+  const unknownComposition = identityMatches.filter((candidate) => !Array.isArray(candidate?.items));
+  if (quantity === 1 && identityMatches.length === 1 && unknownComposition.length === 1) return unknownComposition[0];
   throw new Error(`--select-package ${ref}:${quantity}: no rendered card has exactly package ${ref} at quantity ${quantity}`);
 }
 
@@ -5076,21 +5355,77 @@ async function revealCheckoutForm(page, options = {}) {
   return true;
 }
 
-async function fillPaymentFields(page, args) {
+async function fillPaymentFields(page, args, { readyTimeoutMs = CARD_READY_TIMEOUT_MS } = {}) {
   await clickCreditPaymentMethod(page);
   await selectByField(page, "exp-month", stringArg(args["test-exp-month"]) || DEFAULT_TEST_EXP_MONTH);
   await selectYear(page, stringArg(args["test-exp-year"]) || DEFAULT_TEST_EXP_YEAR);
 
   const card = normalizeCard(stringArg(args["test-card"]) || DEFAULT_TEST_CARD);
   const cvv = stringArg(args["test-cvv"]) || DEFAULT_TEST_CVV;
-  const numberInput = page.frameLocator('iframe[id^="spreedly-number-frame"]').locator("input").first();
-  const cvvInput = page.frameLocator('iframe[id^="spreedly-cvv-frame"]').locator("input").first();
-  await numberInput.click();
-  await numberInput.pressSequentially(card, { delay: 20 });
-  await cvvInput.click();
-  await cvvInput.pressSequentially(cvv, { delay: 20 });
-  await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
-  await page.waitForTimeout(500);
+  const frames = await cardFrames(page);
+  const readyWaitMs = await waitForCardFieldsReady(page, readyTimeoutMs);
+  const numberInput = page.frameLocator(CARD_NUMBER_FRAME).locator("input").first();
+  const cvvInput = page.frameLocator(CARD_CVV_FRAME).locator("input").first();
+  const typed = async (input) => normalizeCard(await input.inputValue());
+  let attempts = 0;
+  let held = null;
+  while (attempts < CARD_TYPE_ATTEMPTS) {
+    attempts++;
+    if (attempts > 1) {
+      await numberInput.fill("");
+      await cvvInput.fill("");
+    }
+    await numberInput.click();
+    await numberInput.pressSequentially(card, { delay: 20 });
+    await cvvInput.click();
+    await cvvInput.pressSequentially(cvv, { delay: 20 });
+    await page.locator("body").click({ position: { x: 20, y: 20 } }).catch(() => {});
+    await page.waitForTimeout(500);
+    held = { number: await typed(numberInput), cvv: await typed(cvvInput) };
+    if (held.number === card && held.cvv === normalizeCard(cvv)) {
+      return { evidence: { ...frames, ready_wait_ms: readyWaitMs, attempts } };
+    }
+  }
+  throw new Error(`card fields did not keep the typed card after ${attempts} attempts: number field holds ${held.number.length} digit(s) ending ${held.number.slice(-4) || "(empty)"} (typed ${card.length} ending ${card.slice(-4)}), CVV field holds ${held.cvv.length} digit(s)`);
+}
+
+// Typing into the card fields before the SDK reports them ready can lose
+// keystrokes: on SDK 0.4.41 the Spreedly-hosted number input exists before
+// its script has loaded, and digits typed in that window are dropped (seen
+// as a number missing its leading digits, which the SDK then refuses without
+// tokenizing, so the order never posts). The checkout form carries
+// next-loading-spreedly from before the card iframes mount until the fields
+// are ready, in 0.4.38 through 0.4.41, so wait for it to clear. A page whose
+// SDK never set it is ready at once. The SDK also clears it when the card
+// script fails to load, so a class still set after the wait means the card
+// script never answered; the step refuses by name rather than type into
+// fields that may drop the number. `timeoutMs` is CARD_READY_TIMEOUT_MS in
+// every production run; only an in-process test passes a shorter wait.
+async function waitForCardFieldsReady(page, timeoutMs = CARD_READY_TIMEOUT_MS) {
+  const started = Date.now();
+  await page.waitForFunction(() => !document.querySelector(".next-loading-spreedly"), null, { timeout: timeoutMs }).catch((error) => {
+    if (error?.name !== "TimeoutError") throw error;
+    throw new Error(`card fields did not report ready within ${timeoutMs / 1000}s: the checkout form still carries next-loading-spreedly, so the card script never finished loading`);
+  });
+  return Date.now() - started;
+}
+
+// The card iframes the step is about to type into, once the SDK has mounted
+// them. Exactly one of each, of one generation, or the step fails by name.
+async function cardFrames(page) {
+  await page.locator(CARD_NUMBER_FRAME).first().waitFor({ state: "attached" });
+  await page.locator(CARD_CVV_FRAME).first().waitFor({ state: "attached" });
+  const ids = async (selector) => page.locator(selector).evaluateAll((nodes) => nodes.map((node) => node.id));
+  const number = await ids(CARD_NUMBER_FRAME);
+  const cvv = await ids(CARD_CVV_FRAME);
+  const all = [...number, ...cvv];
+  const generation = all.every((id) => id.startsWith("spreedly-hosted-"))
+    ? "spreedly-hosted"
+    : all.every((id) => /^spreedly-(number|cvv)-frame/.test(id)) ? "spreedly-iframe-v1" : "mixed";
+  if (number.length !== 1 || cvv.length !== 1 || generation === "mixed") {
+    throw new Error(`expected one card number iframe and one CVV iframe of one generation; found number=[${number.join(", ")}] cvv=[${cvv.join(", ")}]`);
+  }
+  return { generation, number_frame_id: number[0], cvv_frame_id: cvv[0] };
 }
 
 async function clickCreditPaymentMethod(page) {
@@ -5355,23 +5690,29 @@ async function clickControl(locator, { timeout, forceFallback = true, perpetual
 // single offer). Clicking the hidden action fails as not visible, so the
 // visible proxy is clicked instead, but only while the offer holds an SDK action
 // for it to forward to: otherwise the hidden action is clicked and fails as before.
+// The proxy forwards to the action of its own spelling.
 async function shopperUpsellControl(page, action) {
-  const actions = page.locator(`[data-next-upsell-action="${action}"]`);
+  const actions = page.locator(upsellActionSelector(action));
   if (!await actions.count().catch(() => 0)) return actions.first();
   const visibleAction = actions.filter({ visible: true }).first();
   if (await visibleAction.count().catch(() => 0)) return visibleAction;
   // The proxy forwards to `[data-next-upsell="offer"] [data-next-upsell-action]`
   // (upsells.js), so only an action inside the offer is a target.
-  const inOffer = page.locator(`[data-next-upsell="offer"] [data-next-upsell-action="${action}"]`);
+  const inOffer = page.locator(`[data-next-upsell="offer"] ${upsellActionSelector(action)}`);
   const proxy = page.locator(`[data-upsell-proxy="${action}"]`).filter({ visible: true }).first();
   if (await inOffer.count().catch(() => 0) && await proxy.count().catch(() => 0)) return proxy;
   return actions.first();
 }
 
-async function clickUpsellPath(page, path, { trace = null } = {}) {
+// `clickTimeoutMs` and `mutationTimeoutMs` are UPSELL_CLICK_TIMEOUT_MS and
+// UPSELL_MUTATION_TIMEOUT_MS in every production run; only an in-process test
+// that waits one of them out passes a shorter bound.
+async function clickUpsellPath(page, path, { trace = null, clickTimeoutMs, mutationTimeoutMs } = {}) {
+  const clickMs = shorterBound(clickTimeoutMs, UPSELL_CLICK_TIMEOUT_MS);
+  const mutationMs = shorterBound(mutationTimeoutMs, UPSELL_MUTATION_TIMEOUT_MS);
   const offerUrl = safePageUrl(page);
-  const action = path === "accept" ? "add" : "skip";
-  const selector = `[data-next-upsell-action="${action}"]`;
+  const action = await presentUpsellAction(page, path === "accept" ? "accept" : "decline");
+  const selector = upsellActionSelector(action);
   const control = await shopperUpsellControl(page, action);
   if (!await control.count().catch(() => 0)) {
     return { path, clicked: false, error: `Missing upsell control ${selector}` };
@@ -5404,10 +5745,10 @@ async function clickUpsellPath(page, path, { trace = null } = {}) {
         if (!root || root.method() !== "POST" || !isOrderUpsellsUrl(root.url())) return false;
         const startedAt = responseRequestStartedAt(response);
         return startedAt === null || startedAt >= armedAt;
-      }, { timeout: UPSELL_MUTATION_TIMEOUT_MS + (perpetual ? 0 : UPSELL_CLICK_TIMEOUT_MS) }).catch(() => null)
+      }, { timeout: mutationMs + (perpetual ? 0 : clickMs) }).catch(() => null)
     : Promise.resolve(null);
   trace?.markClickAttempted();
-  await clickControl(control, { timeout: UPSELL_CLICK_TIMEOUT_MS, perpetual });
+  await clickControl(control, { timeout: clickMs, perpetual });
   trace?.markClickCompleted();
   const mutationResponse = await mutationPromise;
   const bodyRead = mutationResponse
@@ -5536,14 +5877,37 @@ async function checkoutDisplayEvidence(browserPage) {
       text: clean(row.textContent).slice(0, 160),
     }));
 
-    const selectedBundles = Array.from(document.querySelectorAll("[data-next-bundle-card]"))
+    // A bundle card's packages are the ones its data-next-bundle-items
+    // declares, at the per-package quantity the SDK puts in the cart. Its
+    // data-next-bundle-id names the tier, not a package an order line can
+    // carry, so it stands in only for a card that declares no items.
+    const declaredItems = (card) => {
+      try {
+        const parsed = JSON.parse(card.getAttribute("data-next-bundle-items") || "null");
+        if (!Array.isArray(parsed)) return null;
+        const items = parsed.map((entry) => ({
+          package_id: String(entry?.packageId ?? entry?.package_id ?? ""),
+          quantity: Number(entry?.quantity ?? 1),
+        })).filter((entry) => entry.package_id && Number.isFinite(entry.quantity) && entry.quantity > 0);
+        return items.length ? items : null;
+      } catch {
+        return null;
+      }
+    };
+    const selectedBundleCards = Array.from(document.querySelectorAll("[data-next-bundle-card]"))
       .filter((card) => (
         card.classList.contains("next-selected")
         || card.getAttribute("data-next-selected") === "true"
         || card.getAttribute("aria-checked") === "true"
         || card.querySelector('input[type="radio"], input[type="checkbox"]')?.checked === true
-      ))
-      .map(idOf)
+      ));
+    // A card whose data-next-bundle-items is malformed or empty is kept with
+    // items: null, so reconciliation knows a selected card declared nothing.
+    const selectedBundleItems = selectedBundleCards
+      .filter((card) => card.hasAttribute("data-next-bundle-items"))
+      .map((card) => ({ bundle_id: card.getAttribute("data-next-bundle-id") || null, items: declaredItems(card) }));
+    const selectedBundles = selectedBundleCards
+      .flatMap((card) => declaredItems(card)?.map((item) => item.package_id) || [idOf(card)])
       .filter(Boolean);
 
     const activeToggles = Array.from(document.querySelectorAll("[data-next-package-toggle], [data-next-toggle-card], [data-next-bump]"))
@@ -5571,6 +5935,9 @@ async function checkoutDisplayEvidence(browserPage) {
       summary_present: summaries.length > 0,
       summary_rows: summaryRows.slice(0, 40),
       selected_bundle_package_ids: [...new Set(selectedBundles)],
+      // Uncapped, like selected_bundle_package_ids: every selected card's
+      // items are reconciled.
+      selected_bundle_items: selectedBundleItems,
       active_toggle_package_ids: [...new Set(activeToggles)],
       discount_rows: discountRows.slice(0, 20),
       total_text: totalNode ? clean(totalNode.textContent) : null,
@@ -5579,6 +5946,7 @@ async function checkoutDisplayEvidence(browserPage) {
     summary_present: false,
     summary_rows: [],
     selected_bundle_package_ids: [],
+    selected_bundle_items: [],
     active_toggle_package_ids: [],
     discount_rows: [],
     total_text: null,
@@ -5621,7 +5989,29 @@ function displayedPackageIds(display) {
   };
 }
 
-function reconcileOrderAgainstDisplay({ lines = [], display = null, events = null, selected_packages = [] } = {}) {
+// The packages and per-package quantities the selected bundle card(s)
+// declare. A package two selected cards declare at different quantities is
+// left out of `quantities`: the display itself does not say which one holds.
+// A card whose items are malformed or empty declares nothing.
+function selectedBundleDeclarations(display) {
+  const declared = new Map();
+  for (const card of display?.selected_bundle_items || []) {
+    for (const item of card?.items || []) {
+      const ref = String(item?.package_id ?? "");
+      const quantity = Number(item?.quantity);
+      if (!ref || !Number.isFinite(quantity) || quantity <= 0) continue;
+      declared.set(ref, [...new Set([...(declared.get(ref) || []), quantity])]);
+    }
+  }
+  return {
+    refs: new Set(declared.keys()),
+    quantities: [...declared]
+      .filter(([, quantities]) => quantities.length === 1)
+      .map(([packageId, [quantity]]) => ({ packageId, quantity })),
+  };
+}
+
+function reconcileOrderAgainstDisplay({ lines = [], display = null, events = null, selected_packages = [], requested_cart = [] } = {}) {
   if (!display) {
     return { comparable: false, reason: "checkout display evidence was not captured for this order" };
   }
@@ -5643,9 +6033,37 @@ function reconcileOrderAgainstDisplay({ lines = [], display = null, events = nul
   }
 
   const nonUpsellLines = (lines || []).filter((line) => !line?.is_upsell);
+  // A two-unit bundle card puts its package in the cart at quantity two, so a
+  // line resolves at the quantity the selected card declares; --select-package
+  // still wins for the packages it names.
+  const declarations = selectedBundleDeclarations(display);
+  const strictRefs = new Set((selected_packages || []).map((item) => String(item.packageId)));
+  const resolutionPackages = [
+    ...(selected_packages || []),
+    ...declarations.quantities.filter((item) => !strictRefs.has(item.packageId)),
+  ];
+  // Without --select-package, every explicit --cart <pkg>:<qty> is judged on
+  // its own: the order must carry that package at that quantity, whichever
+  // card, if any, declares it. Beside --select-package the order is judged
+  // against the card that flag chose; a --cart ref it left unapplied is named
+  // by selected_bundle.
+  const requestedCart = (selected_packages || []).length ? [] : (requested_cart || [])
+    .filter((item) => item?.quantityExplicit);
+  const requestedCartByRef = new Map(requestedCart.map((item) => [String(item.packageId), Number(item.quantity || 1)]));
   const displayed = new Set(resolved.displayed_package_ids);
   const summaryIds = new Set(resolved.summary_package_ids);
   const matchedSummaryIds = new Set();
+  // Refs a non-upsell line resolved to. A line resolves to a package only at
+  // the quantity --select-package names or the selected card declares, so
+  // for a declared item this proves the quantity too.
+  const chargedRefs = new Set();
+  // --cart refs a line resolved to, or whose quantity mismatch is named.
+  const answeredCartRefs = new Set();
+  const unresolvedLines = [];
+  const extra = [];
+  const unresolved = [];
+  const matchedQuantities = [];
+  const quantityMismatches = [];
   // A checkout order bump persists with is_upsell: true (the platform's
   // reporting tag), yet the checkout summary displays it. Such a line charges
   // a displayed row; an is_upsell line the summary does not show is a
@@ -5653,23 +6071,24 @@ function reconcileOrderAgainstDisplay({ lines = [], display = null, events = nul
   let bumpLineCount = 0;
   for (const line of (lines || []).filter((entry) => entry?.is_upsell)) {
     const resolution = events ? campaignPackageResolutionForLine(events, line, {
-      selected_packages,
+      selected_packages: resolutionPackages,
       preferred_refs: resolved.summary_package_ids,
     }) : null;
     const ref = resolution?.pkg?.ref_id == null ? null : String(resolution.pkg.ref_id);
     if (ref && summaryIds.has(ref)) {
       matchedSummaryIds.add(ref);
       bumpLineCount += 1;
+      if (requestedCartByRef.has(ref)) {
+        answeredCartRefs.add(ref);
+        const mismatch = packageQuantityMismatch(ref, Number(resolution.pkg.qty ?? resolution.pkg.quantity), requestedCartByRef.get(ref), Number(line.quantity));
+        if (mismatch) quantityMismatches.push(mismatch);
+      }
     }
   }
-  const extra = [];
-  const unresolved = [];
-  const matchedQuantities = [];
-  const quantityMismatches = [];
 
   for (const line of nonUpsellLines) {
     const resolution = events ? campaignPackageResolutionForLine(events, line, {
-      selected_packages,
+      selected_packages: resolutionPackages,
       preferred_refs: resolved.displayed_package_ids,
     }) : null;
     const meta = resolution?.pkg || null;
@@ -5679,10 +6098,15 @@ function reconcileOrderAgainstDisplay({ lines = [], display = null, events = nul
       // same tolerance linePriceDeltaEvidence applies). An unresolvable line
       // cannot prove a stray charge, so it is reported, never counted as one.
       unresolved.push({ title: line.title, quantity: line.quantity });
-      const mismatch = requestedPackageQuantityMismatch(events, line, selected_packages);
-      if (mismatch) quantityMismatches.push(mismatch);
+      unresolvedLines.push(line);
+      const mismatch = requestedPackageQuantityMismatch(events, line, [...selected_packages, ...requestedCart]);
+      if (mismatch) {
+        quantityMismatches.push(mismatch);
+        answeredCartRefs.add(mismatch.package_ref_id);
+      }
       continue;
     }
+    chargedRefs.add(ref);
     const unitQuantity = Number(meta.qty ?? meta.quantity);
     matchedQuantities.push({
       package_ref_id: ref,
@@ -5690,6 +6114,13 @@ function reconcileOrderAgainstDisplay({ lines = [], display = null, events = nul
       purchase_multiplier: resolution.purchaseMultiplier,
       persisted_quantity: Number(line.quantity),
     });
+    // The line resolved at the quantity the page selected; --cart asked for
+    // another, so the order is not the one requested.
+    if (requestedCartByRef.has(ref)) {
+      answeredCartRefs.add(ref);
+      const mismatch = packageQuantityMismatch(ref, unitQuantity, requestedCartByRef.get(ref), Number(line.quantity));
+      if (mismatch) quantityMismatches.push(mismatch);
+    }
     if (displayed.has(ref)) {
       if (summaryIds.has(ref)) matchedSummaryIds.add(ref);
       continue;
@@ -5701,8 +6132,26 @@ function reconcileOrderAgainstDisplay({ lines = [], display = null, events = nul
       price: line.price,
     });
   }
+  // An explicit --cart ref the order carries no line for is not the order
+  // requested either, as when a swap-mode selector kept only the last --cart
+  // ref's card. An unresolved line that is that package at that quantity
+  // still answers it.
+  const packages = latestEventPackages(events);
+  if (packages) {
+    for (const [ref, purchaseMultiplier] of requestedCartByRef) {
+      if (answeredCartRefs.has(ref)) continue;
+      const pkg = packages.find((candidate) => String(candidate?.ref_id ?? candidate?.package_id ?? candidate?.id ?? "") === ref);
+      if (pkg && unresolvedLines.some((line) => packageMatchesLine(pkg, line, { purchaseMultiplier }))) continue;
+      quantityMismatches.push(absentPackageMismatch(ref, Number(pkg?.qty ?? pkg?.quantity), purchaseMultiplier));
+    }
+  }
 
-  const missing = [...summaryIds].filter((id) => !matchedSummaryIds.has(id));
+  // Every item a selected bundle card declares must be charged, whether or not
+  // the summary renders a row for it.
+  const missing = [
+    ...[...summaryIds].filter((id) => !matchedSummaryIds.has(id)),
+    ...[...declarations.refs].filter((id) => !summaryIds.has(id) && !chargedRefs.has(id)),
+  ];
   return {
     comparable: true,
     ok: extra.length === 0 && missing.length === 0 && quantityMismatches.length === 0,
@@ -5728,25 +6177,49 @@ function requestedPackageQuantityMismatch(events, line, selectedPackages) {
       const ref = String(selected.packageId);
       const pkg = packages.find((candidate) => String(candidate?.ref_id ?? candidate?.package_id ?? candidate?.id ?? "") === ref);
       if (!pkg || !packageIdentityMatchesLine(pkg, line)) continue;
-      const unitQuantity = Number(pkg.qty ?? pkg.quantity);
-      const purchaseMultiplier = Number(selected.quantity || 1);
-      const requestedQuantity = unitQuantity * purchaseMultiplier;
-      const persistedQuantity = Number(line?.quantity || 0);
-      if (Number.isFinite(requestedQuantity) && requestedQuantity !== persistedQuantity) {
-        return {
-          package_ref_id: ref,
-          unit_quantity: unitQuantity,
-          purchase_multiplier: purchaseMultiplier,
-          requested_quantity: requestedQuantity,
-          persisted_quantity: persistedQuantity,
-          reason: `package ${ref} requested ${requestedQuantity} unit(s) (${unitQuantity} per package × ${purchaseMultiplier}) but persisted ${persistedQuantity}`,
-        };
-      }
+      const mismatch = packageQuantityMismatch(ref, Number(pkg.qty ?? pkg.quantity), Number(selected.quantity || 1), Number(line?.quantity || 0));
+      if (mismatch) return mismatch;
     }
   }
   return null;
 }
 
+function packageQuantityMismatch(ref, unitQuantity, purchaseMultiplier, persistedQuantity) {
+  const requestedQuantity = unitQuantity * purchaseMultiplier;
+  if (!Number.isFinite(requestedQuantity) || requestedQuantity === persistedQuantity) return null;
+  return {
+    package_ref_id: ref,
+    unit_quantity: unitQuantity,
+    purchase_multiplier: purchaseMultiplier,
+    requested_quantity: requestedQuantity,
+    persisted_quantity: persistedQuantity,
+    reason: `package ${ref} requested ${requestedQuantity} unit(s) (${unitQuantity} per package × ${purchaseMultiplier}) but persisted ${persistedQuantity}`,
+  };
+}
+
+function absentPackageMismatch(ref, unitQuantity, purchaseMultiplier) {
+  const known = Number.isFinite(unitQuantity);
+  return {
+    package_ref_id: ref,
+    unit_quantity: known ? unitQuantity : null,
+    purchase_multiplier: purchaseMultiplier,
+    requested_quantity: known ? unitQuantity * purchaseMultiplier : null,
+    persisted_quantity: 0,
+    reason: known
+      ? `package ${ref} requested ${unitQuantity * purchaseMultiplier} unit(s) (${unitQuantity} per package × ${purchaseMultiplier}) but the order carries no line for it`
+      : `package ${ref} requested at quantity ${purchaseMultiplier} but the order carries no line for it`,
+  };
+}
+
+function latestEventPackages(events) {
+  const responses = events?.responses || [];
+  for (let index = responses.length - 1; index >= 0; index -= 1) {
+    const packages = responses[index]?.body?.packages;
+    if (Array.isArray(packages)) return packages;
+  }
+  return null;
+}
+
 function packageIdentityMatchesLine(pkg, line) {
   if (pkg?.product_sku && line?.sku) return normalizeLabel(pkg.product_sku) === normalizeLabel(line.sku);
   if (pkg?.product_variant_id != null && line?.variant_id != null) return Number(pkg.product_variant_id) === Number(line.variant_id);
@@ -5790,6 +6263,9 @@ function orderDisplayParityAssertion(page, planIdentifier, order) {
   if (reconciliation.missing.length) {
     parts.push(`displayed but never charged: ${reconciliation.missing.join(", ")}`);
   }
+  if (reconciliation.quantity_mismatches?.length) {
+    parts.push(`ordered quantity differs from the request: ${reconciliation.quantity_mismatches.map((entry) => entry.reason).join("; ")}`);
+  }
   return assertion({
     ...base,
     status: STATUS.FAIL,
@@ -7596,7 +8072,7 @@ function extractReceiptLines(order) {
 
 async function waitForUpsellPageReady(page, args) {
   const timeoutMs = numberArg(args["browser-timeout"], DEFAULT_BROWSER_TIMEOUT_MS);
-  await page.locator('[data-next-upsell], [data-next-upsell-action="add"], [data-next-upsell-action="skip"]').first()
+  await page.locator(`[data-next-upsell], ${upsellActionSelector(...UPSELL_ACTION_SPELLINGS.accept, ...UPSELL_ACTION_SPELLINGS.decline)}`).first()
     .waitFor({ state: "visible", timeout: timeoutMs })
     .catch(() => {});
   await page.waitForLoadState("networkidle", { timeout: DEFAULT_SETTLE_TIMEOUT_MS }).catch(() => {});
@@ -8046,6 +8522,26 @@ function numberArg(value, fallback) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
+// A bound an in-process test seam passes, as the Polish deadlines take one
+// (boundedPolishDeadline): `value` when it is a positive safe integer no
+// larger than the production `fallback`, else `fallback`. A seam can shorten
+// a production wait, never lengthen it or switch it off (Playwright reads a
+// 0 timeout as none).
+const shorterBound = boundedPolishDeadline;
+
+// The content parameter leg's limits with options.contentParamLimits (an
+// in-process test seam, never set from argv) applied field by field, each
+// only where it is no larger than CONTENT_PARAM_LIMITS: a time bound is a
+// shorterBound, and maxPairs may also be zero, as runContentParamChecks
+// allows.
+function contentParamLimitsFrom(overrides) {
+  return Object.fromEntries(Object.entries(CONTENT_PARAM_LIMITS).map(([field, production]) => {
+    const value = overrides?.[field];
+    if (field !== "maxPairs") return [field, shorterBound(value, production)];
+    return [field, Number.isSafeInteger(value) && value >= 0 && value <= production ? value : production];
+  }));
+}
+
 function trim(value) {
   return String(value || "").replace(/\s+/g, " ").trim();
 }
@@ -8087,9 +8583,12 @@ export const __qaBrowserTestHooks = Object.freeze({
   primaryCtaAssertionFromEvidence,
   inspectPrimaryCta,
   primaryCtaInspectionScript,
+  primaryCtaDeclaredRoutes,
+  primaryCtaRoutelessForms,
   clickCouponApplyControl,
   isOrderUpsellsUrl,
   clickUpsellPath,
+  waitForUpsellPageReady,
   isPerpetuallyAnimated,
   readJsonResponseBody,
   readJsonResponseBodyWithin,
@@ -8148,6 +8647,7 @@ export const __qaBrowserTestHooks = Object.freeze({
   redactUrlQuery,
   enterCartViaLanding,
   openCheckoutForPath,
+  pathCurrencyLoad,
   createSelectorProbeCache,
   RESIDUE_PAGE_TYPES,
   computedStyleResidueAssertions,