@nextcommerce/campaigns-os 1.54.0 → 1.57.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,
@@ -24,13 +25,20 @@ import {
   commonTestOrderPlan,
   fullTestOrderPaths,
   OFFER_PAGE_TYPES,
+  checkoutPathPages,
+  checkoutStepPages,
+  findPaymentPage,
+  isCheckoutStepTopologyPage,
   pageAtUrl,
+  paymentPagesForTopology,
   remainingActionDisposition,
   resolveTestOrderTopology,
   terminalAtUrl,
 } from "./qa-test-order-topology.mjs";
 import {
   CART_ENTRY_CODES,
+  CART_ENTRY_BUNDLE_CARD_SELECTOR,
+  CART_ENTRY_CHECKOUT_BUTTON_SELECTOR,
   CART_ENTRY_CONTROL_SELECTOR,
   cartEntryHrefFor,
   CART_ENTRY_ROUTE_ATTRIBUTE,
@@ -159,13 +167,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);
@@ -186,7 +198,9 @@ export async function runBrowserChecks(topologies, args = {}, options = {}) {
 }
 
 export async function runBrowserTestOrders(topologies, args = {}, runId = "local", options = {}) {
-  const checkoutPage = findPage(topologies, "checkout");
+  // The Checkout (the page that takes payment) on the first entry path, never
+  // the first page typed checkout: on a split checkout that is step 1 (#641).
+  const checkoutPage = findPaymentPage(topologies);
   if (!checkoutPage?.url) {
     const coverage = upsellActionCoverageAssertion({ topologies, orders: [], checkoutPage });
     return {
@@ -1085,6 +1099,10 @@ async function runPageBrowserChecks(context, page, args, options = {}, policyLin
     }
     if (page.page_type === "checkout") {
       assertions.push(...await checkoutPaymentSurfaceAssertions(browserPage, page));
+    }
+    // Exit-intent and promo-code surfaces may sit on any checkout-flow page
+    // (#641); each assertion runs only where the spec declares the surface.
+    if (["select", "checkout_step", "checkout"].includes(page.page_type)) {
       assertions.push(...await checkoutOfferSurfaceAssertions(browserPage, page));
     }
     assertions.push(...await templateResidueAssertions(browserPage, page, options));
@@ -1313,7 +1331,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)];
 }
 
@@ -1321,6 +1339,54 @@ 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" || pageType === "checkout_step" || 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 [];
+  // A checkout_step's form submits to its declared next step the same way the
+  // Checkout's submits to its success route: the SDK navigates, not the form.
+  if (["checkout", "checkout_step"].includes(String(page.page_type).toLowerCase())) {
+    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 —
@@ -1336,19 +1402,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,
@@ -1358,7 +1426,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();
 
@@ -1391,9 +1459,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
@@ -1582,15 +1650,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",
@@ -1599,7 +1700,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;
@@ -1630,7 +1731,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}`,
@@ -2311,7 +2412,10 @@ function promoCodeSurfaceAssertion({ page, declaration, evidence }) {
 
 function contractPageType(page) {
   const type = String(page?.page_type || "").toLowerCase();
-  return type === "thankyou" ? "receipt" : type;
+  if (type === "thankyou") return "receipt";
+  // A checkout step renders the family's checkout surface without taking
+  // payment (campaigns-os#641); the brand contract keys that surface "checkout".
+  return type === "checkout_step" ? "checkout" : type;
 }
 
 // The palette-residue rows (style, logo, payment chrome) take their severity
@@ -3189,8 +3293,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 };
@@ -3200,6 +3306,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 = {
@@ -3617,7 +3725,12 @@ async function runSingleBrowserTestOrder(context, checkoutPage, plan, args, runI
   let orderDeadline = null;
   let events = { requests: [], responses: [], failed: [], console: [], pageErrors: [] };
   const email = testEmail(planArgs);
-  const entryPage = resolveCartEntryPage(options.topologies, checkoutPage);
+  // The checkout path this order walks (campaigns-os#641): any checkout_step
+  // pages before the Checkout. The cart is entered into the first form page
+  // of the path, and the step pages are submitted in order before payment.
+  const stepPages = checkoutStepPagesFor(options.topologies, checkoutPage);
+  const formEntryPage = stepPages[0] || checkoutPage;
+  const entryPage = resolvePathEntryPage(options.topologies, formEntryPage, stepPages);
   let tracking = null;
   try {
     tracking = options.tracking ? options.tracking.observe(planId(normalizedPlan)) : null;
@@ -3738,6 +3851,7 @@ async function runSingleBrowserTestOrder(context, checkoutPage, plan, args, runI
         ladder,
         checkoutPage,
         entryPage,
+        stepPages,
         topologyPlan: normalizedPlan.topology_plan,
         path,
         args: planArgs,
@@ -3745,6 +3859,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)}`,
@@ -3823,11 +3940,15 @@ 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, stepPages = [], 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);
+  // The page the cart enters and the form filling starts on: the first
+  // checkout_step of a multi-step path, else the Checkout itself.
+  const formEntryPage = stepPages[0] || checkoutPage;
   const selectedPackages = parseCart(args["select-package"]);
+  const currencyLoad = pathCurrencyLoad(args);
   let checkoutDisplay = null;
   let cartBeforeSubmit = null;
 
@@ -3843,7 +3964,8 @@ 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: formEntryPage, entryPage, selectedPackages, args, budget, selectorProbeCache, tracking, currencyLoad,
+    startsOnCheckoutStep: formEntryPage !== checkoutPage,
   }), { timeoutMs: budget() });
   const enteredViaLanding = Boolean(entry && typeof entry === "object" && entry.entered);
   // Responses captured from here on belong to the checkout the ladder drives.
@@ -3851,17 +3973,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: formEntryPage, 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 () => {
@@ -3874,8 +3997,20 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     const fieldTrace = createFieldTrace();
     await ladder.run("customer_fields_filled", async () => {
       ensurePageFillable(page, checkoutPage.url);
-      await fillCheckoutFields(page, args, email, { trace: fieldTrace, actionTimeoutMs: budget() });
+      // On a multi-step path each page renders only its own fields, so every
+      // field is filled where it is present and skipped where it is not. The
+      // SDK's step validation refuses to advance when one is missing, which
+      // the step rung below reports by name.
+      await fillCheckoutFields(page, args, email, { trace: fieldTrace, actionTimeoutMs: budget(), presentOnly: stepPages.length > 0 });
     }, { timeoutMs: budget(), evidence: () => fieldTrace.summary() });
+    // Walk the path: submit each checkout_step and assert it lands on the
+    // step's declared next page, then fill what the arrived page renders. No
+    // order is placed until the Checkout (campaigns-os#641).
+    for (const [index, step] of stepPages.entries()) {
+      await ladder.run("checkout_step_submitted", () => submitCheckoutStepAndArrive({
+        page, step, index, args, email, budget, checkoutUrl: checkoutPage.url, tracking,
+      }), { timeoutMs: budget() });
+    }
     await ladder.run("coupon_applied", async () => {
       const code = stringArg(args["apply-coupon"]);
       if (!code) return { skip: "no --apply-coupon code requested" };
@@ -3884,7 +4019,7 @@ async function executeTestOrderPath({ page, events, email, ladder, checkoutPage,
     }, { timeoutMs: budget() });
     await ladder.run("card_fields_filled", async () => {
       ensurePageFillable(page, checkoutPage.url);
-      return fillPaymentFields(page, args);
+      return fillPaymentFields(page, args, { readyTimeoutMs: cardReadyTimeoutMs });
     }, { timeoutMs: budget() });
     await ladder.run("cart_created", async () => {
       const cart = cartCreationEvidence(events);
@@ -3940,6 +4075,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,
@@ -4136,7 +4272,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(() => {});
@@ -4145,14 +4281,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, startsOnCheckoutStep = false }) {
   // 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
@@ -4169,7 +4305,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) {
@@ -4188,6 +4324,15 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
       evidence: { checkout_selection_surface: surface, ...probeEvidence },
     };
   }
+  if (!entryPage?.url && startsOnCheckoutStep) {
+    // A path that begins on its first checkout_step has no page before it to
+    // fill the cart from; the step page fills it (the family's main package).
+    // The empty-cart guard before submit still refuses an empty cart by name.
+    return {
+      skip: "the checkout path begins on its first checkout step and no page routes into it; the step page fills the cart, and the guard before submit checks it",
+      evidence: { checkout_selection_surface: surface, ...probeEvidence },
+    };
+  }
   if (!entryPage?.url) {
     throw codedError(
       CART_ENTRY_CODES.ENTRY_UNRESOLVED,
@@ -4195,18 +4340,50 @@ 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(() => []);
+  const readControls = () => page.evaluate(cartEntryControlsScript(), {
+    selector: CART_ENTRY_CONTROL_SELECTOR,
+    checkoutUrl: checkoutPage.url,
+    checkoutButtonSelector: CART_ENTRY_CHECKOUT_BUTTON_SELECTOR,
+    bundleCardSelector: CART_ENTRY_BUNDLE_CARD_SELECTOR,
+  }).catch(() => []);
+  let controls = await readControls();
+  // A two-step select page can hold its checkout button in a second step that
+  // a variant control reveals (olympus-mv-two-step: "Select Color & Size").
+  // When no checkout button is visible yet, click that control once and read
+  // the controls again, so a hidden decoy link is never chosen over the
+  // button the reveal shows.
+  const checkoutButtons = controls.filter((entry) => entry.kind === "checkout_button");
+  if (checkoutButtons.length && !checkoutButtons.some((entry) => entry.visible)) {
+    const reveal = page.locator('[data-next-action="select-variants"]:visible').first();
+    if (await reveal.count().catch(() => 0)) {
+      await clickControl(reveal, { timeout: 5000 }).catch(() => {});
+      await page.locator(CART_ENTRY_CHECKOUT_BUTTON_SELECTOR).filter({ visible: true }).first()
+        .waitFor({ state: "visible", timeout: Math.max(1000, Math.min(budget(), 8000)) }).catch(() => {});
+      controls = await readControls();
+    }
+  }
   const choice = chooseCartEntryControl(controls, selectedPackages);
   if (!choice.control) {
     throw codedError(CART_ENTRY_CODES.ENTRY_CONTROL_MISSING, `${choice.reason} (entry page ${redactUrlQuery(entryPage.url)})`);
   }
   const control = choice.control;
+  // A select page (#641): the bundle card is the cart. --select-package clicks
+  // the matching data-next-bundle-card first, strictly, as on a checkout that
+  // selects for itself; otherwise the page's pre-selected card stands.
+  let cardSelection = null;
+  if (control.kind === "checkout_button") {
+    cardSelection = choice.select_card ? await selectPackageCard(page, choice.select_card, []) : null;
+    control.package_id = choice.select_card?.packageId || await selectedBundleCardPackage(page);
+  }
   // The index is the control's position among what its own locator matches,
   // so it replays with nth(); no selector is rebuilt from an attribute value.
-  const target = page.locator(control.kind === "add_to_cart" ? CART_ENTRY_CONTROL_SELECTOR : "a[href]").nth(control.index);
+  const controlSelector = control.kind === "add_to_cart"
+    ? CART_ENTRY_CONTROL_SELECTOR
+    : control.kind === "checkout_button" ? CART_ENTRY_CHECKOUT_BUTTON_SELECTOR : "a[href]";
+  const target = page.locator(controlSelector).nth(control.index);
   const perpetual = await scrollControlIntoView(target);
   await clickControl(target, { timeout: 8000, perpetual });
 
@@ -4236,6 +4413,7 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
       control_text: control.text || null,
       control_kind: control.kind,
       package_id: control.package_id || null,
+      ...(cardSelection ? { bundle_card_selection: cardSelection } : {}),
       sdk_ready: sdkReady,
       arrived_url: redactUrlQuery(safePageUrl(page)),
       checkout_selection_surface: surface,
@@ -4244,6 +4422,92 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
   };
 }
 
+// The package of the bundle card a select page shows as selected, or null.
+async function selectedBundleCardPackage(page) {
+  return page.evaluate((cardSelector) => {
+    const card = Array.from(document.querySelectorAll(cardSelector)).find((node) => (
+      node.classList.contains("next-selected") || node.getAttribute("data-next-selected") === "true" || node.getAttribute("aria-checked") === "true"
+    ));
+    const holder = card && (card.hasAttribute("data-next-package-id") ? card : card.querySelector("[data-next-package-id]"));
+    const value = holder ? String(holder.getAttribute("data-next-package-id") || "").trim() : "";
+    return value || null;
+  }, CART_ENTRY_BUNDLE_CARD_SELECTOR).catch(() => null);
+}
+
+// One checkout_step rung: the page must be on this step, its form's submit is
+// clicked, and the page must land on the step's declared next page. Then the
+// fields the arrived page renders are filled. The SDK owns the navigation
+// (data-next-checkout-step on the form); the runner only waits for it.
+async function submitCheckoutStepAndArrive({ page, step, index, args, email, budget, checkoutUrl, tracking = null }) {
+  ensurePageFillable(page, checkoutUrl);
+  const here = safePageUrl(page);
+  if (!checkoutUrlPredicate(step.url)(here)) {
+    throw new Error(`expected to be on checkout step "${step.page_id || index + 1}" (${redactUrlQuery(step.url)}) but the page is at ${redactUrlQuery(here) || "(unknown)"}`);
+  }
+  const expected = step.expected_next_url;
+  if (!expected) throw new Error(`checkout step "${step.page_id || index + 1}" declares no next page; the spec must route it (next_page) toward its Checkout`);
+  await tracking?.readDocument(page);
+  await submitCheckoutStep(page);
+  const atNext = checkoutUrlPredicate(expected);
+  const timeout = Math.max(1000, Math.min(budget(), numberArg(args["browser-timeout"], DEFAULT_BROWSER_TIMEOUT_MS)));
+  const arrived = await page.waitForURL((url) => atNext(url.toString()), { timeout }).then(() => true, () => false);
+  if (!arrived) {
+    throw new Error(`submitted checkout step "${step.page_id || index + 1}" but the page did not reach its declared next page ${redactUrlQuery(expected)} within ${timeout}ms (now at ${redactUrlQuery(safePageUrl(page)) || "(unknown)"}); a required field the step validates may be missing`);
+  }
+  await page.waitForLoadState("networkidle", { timeout: DEFAULT_SETTLE_TIMEOUT_MS }).catch(() => {});
+  await page.waitForTimeout(500);
+  ensurePageFillable(page, checkoutUrl);
+  const fieldTrace = createFieldTrace();
+  await fillCheckoutFields(page, args, email, { trace: fieldTrace, actionTimeoutMs: budget(), presentOnly: true });
+  return {
+    detail: `step ${index + 1} "${step.page_id || "(unnamed)"}": submitted and landed on its declared next page ${redactUrlQuery(expected)}`,
+    evidence: {
+      step_page_id: step.page_id || null,
+      step_number: index + 1,
+      expected_next_url: redactUrlQuery(expected),
+      arrived_url: redactUrlQuery(safePageUrl(page)),
+      fields: fieldTrace.summary(),
+    },
+  };
+}
+
+// The submit control of a checkout_step form. The step contract puts
+// data-next-checkout-step on the checkout form itself, so a page without one
+// is reported rather than submitted some other way.
+async function submitCheckoutStep(page) {
+  await closeAddressAutocomplete(page);
+  const scope = "form[data-next-checkout-step]";
+  // Never an express-wallet button: on a step page those place an order.
+  const notWallet = ":not([data-next-express-checkout]):not([data-next-express-checkout] *)";
+  const submit = page.locator([`button[type="submit"]`, "button:not([type])", `input[type="submit"]`]
+    .map((control) => `${scope} ${control}${notWallet}`).join(", ")).first();
+  if (!await submit.count().catch(() => 0)) {
+    throw new Error("checkout step page renders no form[data-next-checkout-step] with a submit control; the step form must carry data-next-checkout-step and data-next-step-number");
+  }
+  await submit.waitFor({ state: "visible" });
+  const perpetual = await scrollControlIntoView(submit);
+  await clickControl(submit, { forceFallback: false, perpetual });
+}
+
+// The checkout_step pages on the path into `checkoutPage`, read from the
+// topology that holds it.
+function checkoutStepPagesFor(topologies, checkoutPage) {
+  if (!checkoutPage) return [];
+  const owner = (Array.isArray(topologies) ? topologies : []).find((topology) => (topology?.pages || []).includes(checkoutPage))
+    || (Array.isArray(topologies) ? topologies : []).find((topology) => (topology?.pages || []).some((page) => checkoutUrlPredicate(checkoutPage.url)(page?.url)));
+  return owner ? checkoutStepPages(owner, checkoutPage) : [];
+}
+
+// The page the cart is entered from. Into a Checkout, the usual resolution.
+// Into a first checkout_step, only a page that routes straight into it: the
+// order-and-type fallbacks would pick another path's page in a campaign with
+// parallel paths, and a path that starts on its step has none (#641).
+function resolvePathEntryPage(topologies, formEntryPage, stepPages) {
+  const resolved = resolveCartEntryPage(topologies, formEntryPage);
+  if (!stepPages.length) return resolved;
+  return resolved?.resolution === "routes_into_checkout" ? resolved : null;
+}
+
 // The SDK installs `window.next` late in boot. Bounded and tolerant: a page
 // without the SDK (a plain forcePackageId link) still has a cart entry.
 async function waitForSdkReady(page, timeoutMs) {
@@ -4491,24 +4755,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) ---
@@ -4518,16 +4907,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();
@@ -4549,14 +4939,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 {
@@ -4570,7 +4982,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);
@@ -4587,10 +4999,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) {
@@ -4622,9 +5043,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`);
   }
@@ -4635,18 +5062,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}`);
 }
 
@@ -5008,10 +5439,13 @@ async function fillCheckoutFields(page, args, email, options = {}) {
   // Field order, progressive-disclosure calls and optional/onlyVisible flags
   // below are unchanged; only the per-field recording wrapper is new.
   const track = (field, action, fn, opts = {}) => (trace ? trace.inspect(field, action, fn, opts) : fn());
+  // presentOnly (a multi-step checkout page): every field optional and
+  // visible-only, because each page of the path renders only its own.
+  const present = options.presentOnly === true ? { optional: true, onlyVisible: true } : {};
   const fill = (field, value, opts = {}) =>
-    track(field, "fill", () => fillByField(page, field, value, { ...opts, actionTimeoutMs }), opts);
+    track(field, "fill", () => fillByField(page, field, value, { ...opts, ...present, actionTimeoutMs }), { ...opts, ...present });
   const select = (field, value, opts = {}) =>
-    track(field, "select", () => selectByField(page, field, value, { ...opts, actionTimeoutMs }), opts);
+    track(field, "select", () => selectByField(page, field, value, { ...opts, ...present, actionTimeoutMs }), { ...opts, ...present });
   const address = {
     firstName: stringArg(args["test-first-name"]) || "QA",
     lastName: stringArg(args["test-last-name"]) || "Playwright",
@@ -5092,7 +5526,7 @@ 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);
@@ -5100,7 +5534,7 @@ async function fillPaymentFields(page, args) {
   const card = normalizeCard(stringArg(args["test-card"]) || DEFAULT_TEST_CARD);
   const cvv = stringArg(args["test-cvv"]) || DEFAULT_TEST_CVV;
   const frames = await cardFrames(page);
-  const readyWaitMs = await waitForCardFieldsReady(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());
@@ -5136,12 +5570,13 @@ async function fillPaymentFields(page, args) {
 // 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.
-async function waitForCardFieldsReady(page) {
+// 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: CARD_READY_TIMEOUT_MS }).catch((error) => {
+  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 ${CARD_READY_TIMEOUT_MS / 1000}s: the checkout form still carries next-loading-spreedly, so the card script never finished loading`);
+    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;
 }
@@ -5426,23 +5861,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}` };
@@ -5475,10 +5916,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
@@ -5607,14 +6048,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]"))
@@ -5642,6 +6106,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,
@@ -5650,6 +6117,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,
@@ -5692,7 +6160,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" };
   }
@@ -5714,9 +6204,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
@@ -5724,23 +6242,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;
@@ -5750,10 +6269,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,
@@ -5761,6 +6285,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;
@@ -5772,8 +6303,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,
@@ -5799,25 +6348,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);
@@ -5861,6 +6434,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,
@@ -7035,7 +7611,7 @@ function testOrderPaths(mode, topologies = [], args = {}) {
 }
 
 function resolvePrimaryTestOrderTopology(topologies = []) {
-  const checkout = findPage(topologies, "checkout");
+  const checkout = findPaymentPage(topologies);
   const topology = (topologies || []).find((candidate) => (candidate?.pages || []).includes(checkout)) || { pages: [] };
   return resolveTestOrderTopology(topology, checkout);
 }
@@ -7062,7 +7638,7 @@ function testOrderPlans(mode, topologies = [], args = {}, options = {}) {
   if (tiersMatch) return specTierPlans(topologies, args, tiersMatch[1] || "checkout", options);
   const selectPackage = stringArg(args["select-package"]);
   const applyCoupon = stringArg(args["apply-coupon"]);
-  const checkoutPage = findPage(topologies, "checkout");
+  const checkoutPage = findPaymentPage(topologies);
   const topologyPlan = resolvePrimaryTestOrderTopology(topologies);
   return testOrderPaths(mode, topologies, args).map((path) => ({
     path,
@@ -7093,24 +7669,31 @@ function specTierPlans(topologies, args, variant, { warn = (line) => process.std
   // fail for the wrong reason. A later funnel's checkout with declarations
   // but no resolvable URL cannot be driven; it is warned about, not dropped
   // silently.
-  const primary = findPage(topologies, "checkout");
+  const primary = findPaymentPage(topologies);
   if (!primary) {
     throw new Error("--test-order tiers requires a CampaignSpec-driven run with a checkout page; this spec/topology has no checkout page to derive tiers or coupons from (non-packet --site runs have none by design).");
   }
   const plans = [];
-  for (const topology of Array.isArray(topologies) ? topologies : []) {
-    const pages = Array.isArray(topology?.pages) ? topology.pages : [];
-    const checkoutPage = pages.find((page) => String(page?.page_type || "").toLowerCase() === "checkout");
-    if (!checkoutPage) continue;
-    const declaredTiers = declaredSelectorTiers(checkoutPage);
-    const bumps = declaredOrderBumps(checkoutPage);
+  // Every Checkout of every funnel: split-test paths in one funnel each reach
+  // their own (#641). A multi-step path declares its cart on the select page or
+  // first step, not on the Checkout, so tiers and bumps are read from every
+  // page of the path; coupons from the pages the runner fills (steps and the
+  // Checkout), since a select page is left before any form is filled.
+  const paymentPages = (Array.isArray(topologies) ? topologies : [])
+    .flatMap((topology) => paymentPagesForTopology(topology).map((checkoutPage) => ({ topology, checkoutPage })));
+  for (const { topology, checkoutPage } of paymentPages) {
+    const pathPages = checkoutPathPages(topology, checkoutPage);
+    const declaredTiers = uniqueTiers(pathPages.flatMap((page) => declaredSelectorTiers(page)));
+    const bumps = [...new Set(pathPages.flatMap((page) => declaredOrderBumps(page)))];
     if (bumps.length) {
       warn(`[qa:test-order] checkout page "${checkoutPage.page_id || checkoutPage.label || "(unnamed)"}" declares order bump package(s) ${bumps.join(", ")} (is_order_bump or is_upsell) — not planned as selector tiers; bump coverage comes from --cart.`);
     }
     for (const tier of declaredTiers) declaredIdentities.add(selectorTierIdentity(tier));
     for (const ref of bumps) bumpRefs.add(ref);
     const tiers = narrowTo ? declaredTiers.filter((tier) => narrowTo.has(selectorTierIdentity(tier))) : declaredTiers;
-    const coupons = declaredCheckoutCoupons(checkoutPage);
+    const coupons = mergeDeclaredCoupons(pathPages
+      .filter((page) => page === checkoutPage || isCheckoutStepTopologyPage(page))
+      .map((page) => declaredCheckoutCoupons(page)));
     if (!tiers.length && !coupons.length) continue;
     if (checkoutPage !== primary && !checkoutPage.url) {
       if (narrowTo && tiers.length) {
@@ -7232,6 +7815,28 @@ function selectorTierNarrowing(value) {
 // Declared coupons follow the repo's offer-surface rule (build-brief, cli
 // exit-pop gates): a surface counts only when `enabled === true` and it maps
 // an offer_code. Both surfaces mapping the same code collapse into one plan.
+// Tiers read from several pages of one path, first declaration kept.
+function uniqueTiers(tiers) {
+  const seen = new Set();
+  return tiers.filter((tier) => {
+    const identity = selectorTierIdentity(tier);
+    if (seen.has(identity)) return false;
+    seen.add(identity);
+    return true;
+  });
+}
+
+// Coupon lists from several pages of one path, merged by code.
+function mergeDeclaredCoupons(lists) {
+  const merged = [];
+  for (const coupon of lists.flat()) {
+    const existing = merged.find((entry) => normalizeLabel(entry.code) === normalizeLabel(coupon.code));
+    if (!existing) merged.push({ code: coupon.code, surfaces: [...coupon.surfaces] });
+    else for (const surface of coupon.surfaces) if (!existing.surfaces.includes(surface)) existing.surfaces.push(surface);
+  }
+  return merged;
+}
+
 function declaredCheckoutCoupons(checkoutPage) {
   const coupons = [];
   const add = (surface, block) => {
@@ -7561,7 +8166,7 @@ function describeCoverageDoubt(doubt) {
 
 // Page types that never carry an upsell action. Any other type, or none, does
 // not say either way.
-const NON_OFFER_PAGE_TYPES = new Set(["presell", "landing", "select", "product", "checkout", "thankyou", "receipt"]);
+const NON_OFFER_PAGE_TYPES = new Set(["presell", "landing", "select", "product", "checkout_step", "checkout", "thankyou", "receipt"]);
 const UPSELL_COVERAGE_UNASSESSABLE = Object.freeze({
   no_url: "no URL",
   unresolvable_url: "URL is not an absolute http(s) address",
@@ -7584,7 +8189,7 @@ export function upsellActionCoverageWithoutOrders(topologies = []) {
   return upsellActionCoverageAssertion({
     topologies,
     orders: [],
-    checkoutPage: findPage(topologies, "checkout"),
+    checkoutPage: findPaymentPage(topologies),
     testOrdersOff: true,
   });
 }
@@ -7667,7 +8272,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(() => {});
@@ -8047,14 +8652,6 @@ function persistedUpsellStep(step) {
   return projected;
 }
 
-function findPage(topologies, type) {
-  for (const topology of topologies || []) {
-    const page = (topology.pages || []).find((candidate) => candidate.page_type === type);
-    if (page) return page;
-  }
-  return null;
-}
-
 function parseCart(value) {
   if (!value) return [];
   return String(value).split(",").map((part) => {
@@ -8117,6 +8714,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();
 }
@@ -8158,9 +8775,12 @@ export const __qaBrowserTestHooks = Object.freeze({
   primaryCtaAssertionFromEvidence,
   inspectPrimaryCta,
   primaryCtaInspectionScript,
+  primaryCtaDeclaredRoutes,
+  primaryCtaRoutelessForms,
   clickCouponApplyControl,
   isOrderUpsellsUrl,
   clickUpsellPath,
+  waitForUpsellPageReady,
   isPerpetuallyAnimated,
   readJsonResponseBody,
   readJsonResponseBodyWithin,
@@ -8219,6 +8839,7 @@ export const __qaBrowserTestHooks = Object.freeze({
   redactUrlQuery,
   enterCartViaLanding,
   openCheckoutForPath,
+  pathCurrencyLoad,
   createSelectorProbeCache,
   RESIDUE_PAGE_TYPES,
   computedStyleResidueAssertions,