@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/src/qa-cart-entry.mjs

@@ -35,6 +35,10 @@ export const CART_ENTRY_CODES = Object.freeze({
   ENTRY_CONTROL_MISSING: "cart_entry_control_missing",
   // The control was clicked but the page never reached the checkout URL.
   ENTRY_NO_NAVIGATION: "cart_entry_no_navigation",
+  // A select page's bundle slot shows an empty variant control (size,
+  // colour) with no in-stock option to choose, so its Next would refuse.
+  // Fired before the checkout control is clicked (campaigns-os#667).
+  ENTRY_VARIANT_UNFILLED: "cart_entry_variant_unfilled",
   // The SDK cart held zero items at submit time. Fired before the budget
   // reservation and before the submit click.
   CART_EMPTY_BEFORE_SUBMIT: "cart_empty_before_submit",
@@ -127,6 +131,17 @@ export function cartEntryHrefFor(element, { cartEntrySelector, cartEntryRouteAtt
   }
 }
 
+// A select page (campaigns-os#641) has no add-to-cart control: its swap-mode
+// bundle selector writes the cart when a card is chosen, the SDK persists the
+// cart between pages, and a checkout button or link moves on. The runner
+// treats "bundle cards plus one of these" as a cart-entry control: the SDK's
+// checkout action, or a plain link into the next page. Matched by this one
+// selector so the chosen control replays with nth().
+export const CART_ENTRY_CHECKOUT_BUTTON_SELECTOR = '[data-next-action="checkout"], a[href]';
+
+// The bundle cards a select page renders, outside the cart summary.
+export const CART_ENTRY_BUNDLE_CARD_SELECTOR = "[data-next-bundle-card]";
+
 // Route-shaped spellings the runner used to consult and no longer does,
 // because the SDK never declares them. They are not routes, but a page that
 // carries one is reported so an operator can tell "the runner narrowed its
@@ -138,8 +153,10 @@ export const UNDECLARED_ROUTE_ATTRIBUTES = Object.freeze(["data-next-href", "dat
 // shop-single-step landing declares; the rest are the entry-like types
 // `deriveEntryUrls` already recognises.
 // Pages that can only follow the checkout: the checkout itself plus the
-// topology module's own offer and receipt sets, so the two never drift.
-const POST_CHECKOUT_PAGE_TYPES = new Set(["checkout", ...OFFER_PAGE_TYPES, ...RECEIPT_PAGE_TYPES]);
+// topology module's own offer and receipt sets, so the two never drift. A
+// checkout_step is never a cart entry either: it is a form page of the
+// checkout path itself (campaigns-os#641).
+const POST_CHECKOUT_PAGE_TYPES = new Set(["checkout", "checkout_step", ...OFFER_PAGE_TYPES, ...RECEIPT_PAGE_TYPES]);
 const PREFERRED_ENTRY_PAGE_TYPES = ["select", "landing", "product", "presell", "entry", "lander", "advertorial", "listicle", "review", "opt-in", "optin"];
 
 export function codedError(code, message) {
@@ -234,18 +251,22 @@ export function summarizeSelectionSurface(surface) {
   return parts.length ? parts.join(", ") : "none";
 }
 
-// evaluate() body: the cart-entry controls the entry page renders. Two kinds:
-//   add_to_cart   the SDK action controls (CART_ENTRY_CONTROL_SELECTOR); the
-//                 SDK adds the package and navigates via data-next-url;
-//   checkout_link a plain link into the checkout URL carrying
-//                 `?forcePackageId=`, which the SDK reads on the checkout page
-//                 to pre-load the cart. This is what the certified
-//                 shop-single-step landing renders today.
+// evaluate() body: the cart-entry controls the entry page renders. Three kinds:
+//   add_to_cart     the SDK action controls (CART_ENTRY_CONTROL_SELECTOR); the
+//                   SDK adds the package and navigates via data-next-url;
+//   checkout_link   a plain link into the checkout URL carrying
+//                   `?forcePackageId=`, which the SDK reads on the checkout
+//                   page to pre-load the cart. This is what the certified
+//                   shop-single-step landing renders today;
+//   checkout_button on a page with bundle cards only: the SDK checkout action
+//                   or a plain link into the checkout URL. The selected card
+//                   is the cart; `bundle_package_ids` lists what the cards
+//                   carry so --select-package can name one (campaigns-os#641).
 // Each control reports its visibility, text, and the package id it carries
 // (own attribute, nearest card, or the forcePackageId ref), so the caller can
 // prefer a visible SDK control and honour --select-package in one round trip.
 export function cartEntryControlsScript() {
-  return ({ selector, checkoutUrl }) => {
+  return ({ selector, checkoutUrl, checkoutButtonSelector = null, bundleCardSelector = null }) => {
     const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
     const isVisible = (element) => {
       const rect = element.getBoundingClientRect();
@@ -313,7 +334,39 @@ export function cartEntryControlsScript() {
         }];
       })
       : [];
-    return [...actions, ...links];
+    const cards = Array.from(document.querySelectorAll(bundleCardSelector || "[data-next-bundle-card]"))
+      .filter((card) => !card.closest("[data-next-cart-summary], [data-next-upsell-context], [data-next-upsell], template"));
+    const bundlePackageIds = [...new Set(cards.flatMap((card) => {
+      const own = clean(card.getAttribute("data-next-package-id"));
+      const nested = Array.from(card.querySelectorAll("[data-next-package-id]")).map((node) => clean(node.getAttribute("data-next-package-id")));
+      return [own, ...nested].filter(Boolean);
+    }))];
+    const buttons = cards.length && checkoutButtonSelector
+      ? Array.from(document.querySelectorAll(checkoutButtonSelector)).flatMap((element, index) => {
+        const isAction = element.getAttribute("data-next-action") === "checkout";
+        if (!isAction) {
+          const href = element.getAttribute("href");
+          if (!checkout || canonical(href) !== checkout) return [];
+          try {
+            if (new URL(href, document.baseURI).searchParams.get("forcePackageId")) return [];
+          } catch {
+            return [];
+          }
+        }
+        return [{
+          kind: "checkout_button",
+          index,
+          visible: isVisible(element),
+          text: label(element),
+          package_id: null,
+          bundle_package_ids: bundlePackageIds,
+          quantity: 1,
+          next_url: isAction ? null : element.getAttribute("href"),
+          tag: element.tagName.toLowerCase(),
+        }];
+      })
+      : [];
+    return [...actions, ...links, ...buttons];
   };
 }
 
@@ -323,7 +376,7 @@ export function cartEntryControlsScript() {
 // control is only used when nothing is visible.
 export function chooseCartEntryControl(controls = [], requested = []) {
   const list = Array.isArray(controls) ? controls : [];
-  if (!list.length) return { control: null, reason: "no add-to-cart control or forcePackageId checkout link rendered on the entry page" };
+  if (!list.length) return { control: null, reason: "no add-to-cart control, forcePackageId checkout link, or bundle cards with a checkout button rendered on the entry page" };
   const wanted = Array.isArray(requested) ? requested.filter((item) => item?.packageId) : [];
   if (wanted.length > 1) {
     return {
@@ -331,9 +384,24 @@ export function chooseCartEntryControl(controls = [], requested = []) {
       reason: `--select-package requested ${wanted.length} refs, but a landing-page entry can select at most one package before the SDK navigates to checkout`,
     };
   }
+  // A select page's checkout button carries no package of its own: the
+  // requested package is the bundle card the runner clicks before it. Used
+  // only when no add-to-cart control or forcePackageId link carries the ref.
+  const buttons = list.filter((control) => control.kind === "checkout_button");
+  const carriers = list.filter((control) => control.kind !== "checkout_button");
   const byRef = wanted.length
-    ? list.filter((control) => String(control.package_id) === String(wanted[0].packageId))
-    : list;
+    ? carriers.filter((control) => String(control.package_id) === String(wanted[0].packageId))
+    : carriers;
+  if (!byRef.length && buttons.length) {
+    const pick = (pool) => pool.find((control) => control.visible) || pool[0];
+    if (!wanted.length) return { control: pick(buttons), reason: null };
+    const withCard = buttons.filter((control) => (control.bundle_package_ids || []).map(String).includes(String(wanted[0].packageId)));
+    if (withCard.length) return { control: pick(withCard), select_card: wanted[0], reason: null };
+    return {
+      control: null,
+      reason: `--select-package ${wanted[0].packageId}: no bundle card on the entry page carries package ${wanted[0].packageId} (rendered: ${[...new Set(buttons.flatMap((control) => control.bundle_package_ids || []))].join(", ") || "(none)"})`,
+    };
+  }
   if (!byRef.length) {
     return {
       control: null,
@@ -363,6 +431,107 @@ export function chooseCartEntryControl(controls = [], requested = []) {
 // returns the store's `totalQuantity` — and the debugger's cart store second
 // (`window.nextDebug.stores.cart`, present with `?debugger=true`), which is
 // the only public place the line items and their package ids are readable.
+// The variant controls a select page renders per bundle slot: the
+// campaign-cart SDK injects a native select into each slot's
+// [data-next-variant-selectors] (inside a .next-slot-variant-field). The
+// olympus-mv-two-step starter, and pages built from it, hide that select behind
+// a visible os-dropdown (a toggle button plus os-dropdown-item rows carrying
+// `value`); a row click is what sets the select and dispatches `change`.
+export const SLOT_VARIANT_SELECT_SELECTOR = "[data-next-variant-selectors] select, .next-slot-variant-field select";
+export const SLOT_VARIANT_FIELD_SELECTOR = ".next-slot-variant-field";
+export const SLOT_VARIANT_DROPDOWN_TOGGLE_SELECTOR = "os-dropdown .os-card__variant-dropdown-toggle";
+export const SLOT_VARIANT_DROPDOWN_ROW_SELECTOR = "os-dropdown os-dropdown-item";
+
+export const slotVariantKey = ({ bundle_id: bundleId, slot, variant_code: code } = {}) => `${bundleId ?? ""}|${slot}|${code ?? ""}`;
+
+// evaluate() body: the next slot variant action, one per call because a
+// choice can re-render its slot. In document order over the visible slot
+// variant selects (a select counts as visible when it or its field is):
+//   - a field showing a dropdown UI whose key is not in `picked` gets a pick:
+//     the row matching the select's current value when that row is in stock
+//     (so the cart stays what the SDK chose), else the first in-stock row. The
+//     caller clicks the toggle and the row like a shopper, because a page may
+//     count a field as chosen only when a row was clicked. Pre-filled selects
+//     are picked too. Returned as { pick } with the field's index among
+//     SLOT_VARIANT_FIELD_SELECTOR matches and the row's index among the
+//     field's SLOT_VARIANT_DROPDOWN_ROW_SELECTOR matches;
+//   - a select with no dropdown UI is filled here only when it is empty, with
+//     its first in-stock option and input + change dispatched ({ filled });
+//     a pre-filled one is left alone.
+// In stock: enabled, not hidden, non-empty value; for a row also not
+// [disabled], aria-disabled, .next-oos, .next-variant-unavailable or
+// data-available="false", and its native option not disabled. Nothing to
+// choose returns { unfillable } naming the slot; nothing left returns
+// { done: true }.
+export function slotVariantStepScript() {
+  return ({ selector, fieldSelector, toggleSelector, rowSelector, picked = [] }) => {
+    const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const isVisible = (element) => {
+      if (!element) return false;
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+    };
+    const holderOf = (select) => select.closest(fieldSelector) || select.closest("[data-next-variant-selectors]");
+    const visible = Array.from(new Set(document.querySelectorAll(selector)))
+      .filter((select) => !select.disabled && (isVisible(select) || isVisible(holderOf(select))));
+    const slotRoots = Array.from(new Set(visible.map((select) => select.closest("[data-next-variant-selectors]") || holderOf(select))));
+    const fields = Array.from(document.querySelectorAll(fieldSelector));
+    const describe = (select) => {
+      const field = select.closest(fieldSelector);
+      const index = Number.parseInt(field?.getAttribute("data-next-slot-index") ?? "", 10);
+      const root = select.closest("[data-next-variant-selectors]") || holderOf(select);
+      return {
+        bundle_id: clean(field?.getAttribute("data-next-bundle-id")) || null,
+        slot: Number.isFinite(index) ? index + 1 : slotRoots.indexOf(root) + 1,
+        variant_code: clean(select.getAttribute("data-next-variant-code") || select.getAttribute("data-variant-code") || field?.getAttribute("data-next-variant-code") || select.name) || null,
+      };
+    };
+    const keyOf = (info) => `${info.bundle_id ?? ""}|${info.slot}|${info.variant_code ?? ""}`;
+    const optionInStock = (option) => !option.disabled && !option.hidden && clean(option.value) !== "";
+    for (const select of visible) {
+      const info = describe(select);
+      const field = select.closest(fieldSelector);
+      const toggle = field ? Array.from(field.querySelectorAll(toggleSelector)).find(isVisible) : null;
+      if (toggle) {
+        if (picked.includes(keyOf(info))) continue;
+        const rows = Array.from(field.querySelectorAll(rowSelector));
+        // One in-stock rule: a row is in stock when its own markup says so and
+        // its native option (if any) passes optionInStock.
+        const optionsByValue = new Map(Array.from(select.options).map((option) => [clean(option.value), option]));
+        const rowInStock = (row) => {
+          const value = clean(row.getAttribute("value"));
+          if (!value || row.hidden || row.hasAttribute("disabled") || row.getAttribute("aria-disabled") === "true") return false;
+          if (row.classList.contains("next-oos") || row.classList.contains("next-variant-unavailable") || row.getAttribute("data-available") === "false") return false;
+          const option = optionsByValue.get(value);
+          return !option || optionInStock(option);
+        };
+        const current = clean(select.value);
+        const row = (current && rows.find((candidate) => clean(candidate.getAttribute("value")) === current && rowInStock(candidate))) || rows.find(rowInStock);
+        if (!row) return { unfillable: { ...info, options: rows.length, via: "dropdown" } };
+        const fieldIndex = fields.indexOf(field);
+        const rowIndex = rows.indexOf(row);
+        if (fieldIndex < 0 || rowIndex < 0) {
+          return { unfillable: { ...info, options: rows.length, via: "dropdown", detail: `the dropdown ${fieldIndex < 0 ? "field" : "row"} could not be located` } };
+        }
+        return { pick: { ...info, value: clean(row.getAttribute("value")), field_index: fieldIndex, row_index: rowIndex } };
+      }
+      if (clean(select.value) !== "") continue;
+      const option = Array.from(select.options).find(optionInStock);
+      if (!option) return { unfillable: { ...info, options: select.options.length, via: "select" } };
+      select.value = option.value;
+      select.dispatchEvent(new Event("input", { bubbles: true }));
+      select.dispatchEvent(new Event("change", { bubbles: true }));
+      return { filled: { ...info, value: option.value } };
+    }
+    return { done: true };
+  };
+}
+
+export function slotVariantLabel({ bundle_id: bundleId, slot, variant_code: code } = {}) {
+  return `slot ${slot}${bundleId ? ` (bundle "${bundleId}")` : ""}${code ? ` ${code}` : " variant"}`;
+}
+
 // The enriched line list on `getCartData()` is deliberately NOT read: it is
 // always empty on the shipped SDK (campaign-cart#36; see the cart-state
 // verification section of docs/qa-and-test-orders.md), so it would call every

package/src/qa-node.mjs

@@ -1,5 +1,5 @@
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "./spec-source-identity.mjs";
-import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, starterResidueIsExpected } from "./local-preview-policy.mjs";
+import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD, ensureUrlTrailingSlash, normalizeQaBaseUrl, starterResidueIsExpected } from "./local-preview-policy.mjs";
 import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion, scriptParseAssertion } from './qa-binding-evidence.mjs';
 import { shellToken } from "./shell-token.mjs";
 import { currentBriefMaterial } from "./input-currency.mjs";
@@ -37,7 +37,7 @@ import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
 import { trackingQaAssertion, trackingRunScopeRows } from "./qa-tracking-params.mjs";
 import { contentParamNotRequestedRows, contentParamQaAssertion } from "./qa-content-params.mjs";
 import { policyLinkNotRequestedRows, policyLinkQaAssertion } from "./qa-policy-links.mjs";
-import { createVerdict, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
+import { createVerdict, formatTestOrderSummary, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
 import { normalizeSdkMetaName, lookupSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { annotateQaAssertionCauses, formatCauseReportLines, formatCauseTag } from "./finding-cause.mjs";
 import { promoteQaVerdict, writeQaSidecar } from "./qa-sidecar.mjs";
@@ -61,8 +61,10 @@ import {
   declineRouteTarget,
   forwardRouteTarget,
   inapplicableForwardFields,
+  upgradeCampaignSpec,
 } from "../campaign-spec/dist/index.js";
 import { evaluateThemeGate } from "./theme-gate.mjs";
+import { findPaymentPage } from "./qa-test-order-topology.mjs";
 import { probeRouteUrls, ROUTE_PROBE_DEFAULT_TIMEOUT_MS } from "./qa-route-probe.mjs";
 import { resolveCommerceCatalog, resolvePacketCommerceCatalogPath, resolveTemplateBrandContract } from "./private-template-source.mjs";
 import { computeBuildFingerprint, resolveBuiltSiteScope, topologiesFromBuiltSiteScope } from "./built-site-scope.mjs";
@@ -85,6 +87,7 @@ import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, tar
 import { loadParityFixture } from "./qa-parity-fixture.mjs";
 import { assessParityCapture, resolveParityScenario, runParityCapture } from "./qa-parity-capture.mjs";
 import { loadPageKitCampaignEntry, PAGE_KIT_CAMPAIGNS_REL_PATH } from "./page-kit-campaign-config.mjs";
+import { publicRouteForPage } from "./source-html-intake.mjs";
 import {
   evaluatePageKitStoreProfile,
   PAGE_KIT_STORE_PROFILE_FIELDS,
@@ -115,7 +118,7 @@ import {
   liveRefsNotRunMessage,
   readLiveCampaignForPacket,
 } from "./live-campaign-refs.mjs";
-import { specPackageRefs, specShippingRefs } from "./doctor/checks.mjs";
+import { entryPageKitServingRoute, isRootRoutedEntryPage, specPackageRefs, specShippingRefs } from "./doctor/checks.mjs";
 
 // The producing runtime identity on every verdict. Read from package.json so
 // a verdict names the release that made it; a literal here outlived three
@@ -464,7 +467,6 @@ async function resolveQaInputs(args, {
   }
   const normalized = normalizeSpec(rawSpec);
   const publicRouteSlug = resolvePublicRouteSlug({ packet, spec: normalized, rawSpec });
-  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
   // Packet 01: the analytics legs capture ONE URL derived from resolved
   // identity (public_route_slug + route_root), composed here where the raw
   // operator/deploy base is still in hand.
@@ -475,6 +477,7 @@ async function resolveQaInputs(args, {
     routeRoot: resolveCampaignRouteRoot({ packet, spec: normalized, rawSpec, publicRouteSlug, notes: routeRootNotes }),
     routeRootNote: routeRootNotes[0] || null,
   });
+  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
   const specHash = computeSpecHash(rawSpec);
   // The brief material this run is judged against, bound at run start beside
   // the spec hash: the QA stage write stamps it, not the material at write time.
@@ -484,7 +487,16 @@ async function resolveQaInputs(args, {
     || stringArg(normalized?.campaign?.preferred_template_family)
     || null;
   const commerceStructureContract = loadCommerceStructureContract({ packet, packetPath, templateFamily });
-  const topologies = extractTopologies(normalized, { baseUrl, publicRouteSlug, templateFamily, commerceStructureContract });
+  const targetRepo = checkpointPreflight?.targetRepo || (packetPath && packet ? targetRepoFor(packetPath, packet) : null);
+  const targetOutputDir = targetRepo && packet?.assembly?.output_dir ? resolve(targetRepo, packet.assembly.output_dir) : null;
+  const mappingById = new Map((packet?.source_html?.pages || []).map((page) => [page.page_id, page]));
+  const topologies = extractTopologies(normalized, {
+    baseUrl, publicRouteSlug, templateFamily, commerceStructureContract,
+    entryServingRoute: (page) => entryPageKitServingRoute(targetRepo, publicRouteSlug, page, {
+      targetOutputDir,
+      mapping: mappingById.get(page.id),
+    }),
+  });
   const themeGate = resolveThemeGate({
     packetPath,
     topologies,
@@ -971,7 +983,9 @@ function resolvePolishGate({
   return gate;
 }
 
-const THEME_GATE_COMMERCE_TYPES = new Set(["checkout", "upsell", "downsell", "receipt", "thankyou"]);
+// select and checkout_step pages render the family's checkout surface without
+// taking payment (campaigns-os#641); the brand theme applies to them as well.
+const THEME_GATE_COMMERCE_TYPES = new Set(["select", "checkout_step", "checkout", "upsell", "downsell", "receipt", "thankyou"]);
 
 function themeGateScopeFromTopologies(topologies = []) {
   const built_pages = [];
@@ -3234,7 +3248,10 @@ async function maybeRunLegacyApiTestOrders({ args, resolved, runId, assertions }
   const apiBase = stringArg(args["campaigns-api-base"]) || process.env.CAMPAIGNS_API_BASE;
   if (!apiKey || !apiBase) throw new Error("Legacy direct API test orders require --api-key/QA_CAMPAIGNS_API_KEY and --campaigns-api-base/CAMPAIGNS_API_BASE.");
   const { cart, paths } = legacyTestOrderInputs(args);
-  const checkout = findPage(resolved.topologies, "checkout");
+  // The Checkout on the tested path, never the first page typed checkout: on a
+  // split checkout that was the first step, whose forward link is the next
+  // step, so the order's success URL pointed back into checkout (#641).
+  const checkout = findPaymentPage(resolved.topologies);
   if (!checkout?.url) throw new Error("--test-order requires a checkout page URL.");
   const upsell = findPage(resolved.topologies, "upsell");
   const orders = [];
@@ -3318,22 +3335,25 @@ async function createTestOrder({ apiBase, apiKey, cart, runId, successUrl, spec,
   }
 }
 
+// QA reads the v5 page vocabulary: a v4 spec's `checkout → checkout` chain is
+// retyped `checkout_step` on read (campaigns-os#641). The raw spec is untouched,
+// so the spec hash still covers the bytes as written.
 function normalizeSpec(raw) {
-  if (Array.isArray(raw?.funnels)) return raw;
+  if (Array.isArray(raw?.funnels)) return upgradeCampaignSpec(raw);
   if (Array.isArray(raw?.funnel_pages)) {
     return { ...raw, funnels: [{ id: "default", name: "Default", weight: 100, pages: raw.funnel_pages }] };
   }
   return { ...raw, funnels: [] };
 }
 
-function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templateFamily = null, commerceStructureContract = null } = {}) {
+function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templateFamily = null, commerceStructureContract = null, entryServingRoute = null } = {}) {
   const pageById = new Map();
   for (const funnel of spec.funnels || []) {
     for (const page of funnel.pages || []) pageById.set(page.id, page);
   }
   const urlById = new Map();
   for (const [id, page] of pageById) {
-    urlById.set(id, resolvePageUrl(page, baseUrl, publicRouteSlug));
+    urlById.set(id, resolvePageUrl(page, baseUrl, publicRouteSlug, entryServingRoute?.(page)));
   }
   return (spec.funnels || []).map((funnel) => ({
     funnel_id: funnel.id || "default",
@@ -3388,13 +3408,13 @@ function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templ
   }));
 }
 
-function resolvePageUrl(page, baseUrl, publicRouteSlug = null) {
+function resolvePageUrl(page, baseUrl, publicRouteSlug = null, entryServingRoute = null) {
   if (typeof page.url === "string" && page.url.trim()) return page.url.trim();
   if (!baseUrl) return null;
-  const route = typeof page.page_url === "string" && page.page_url.trim()
-    ? runtimeRelativeRouteForSpecValue(page.page_url, publicRouteSlug)
-    : page.is_entry
-      ? ""
+  const route = isRootRoutedEntryPage(page, publicRouteSlug)
+    ? entryServingRoute?.route || ""
+    : typeof page.page_url === "string" && page.page_url.trim()
+      ? runtimeRelativeRouteForSpecValue(page.page_url, publicRouteSlug)
       : defaultRouteForType(page.type);
   if (isAbsoluteHttpUrl(route)) return route;
   try {
@@ -3406,6 +3426,7 @@ function resolvePageUrl(page, baseUrl, publicRouteSlug = null) {
 
 function defaultRouteForType(type) {
   if (type === "thankyou") return "receipt/";
+  if (type === "checkout_step") return "checkout-step/";
   if (["presell", "landing", "checkout", "upsell", "downsell"].includes(type)) return `${type}/`;
   return `${type || "page"}/`;
 }
@@ -3556,6 +3577,8 @@ function output(value, args) {
       console.log("This is a passing proof with exceptions. Report these exceptions to the operator; do not clear or waive them, or change markup just to make them pass.");
     }
     console.log(`Counts: ${Object.entries(value.counts).map(([status, count]) => `${count} ${status}`).join(", ")}`);
+    const testOrderSummary = formatTestOrderSummary(value.verdict);
+    if (testOrderSummary) console.log(testOrderSummary);
     printCauseLines(value.verdict);
     printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
     if (value.commercial) {
@@ -3929,21 +3952,6 @@ function normalizeBaseUrl(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function normalizeQaBaseUrl(value, publicRouteSlug) {
-  const baseUrl = normalizeBaseUrl(value);
-  if (!baseUrl) return null;
-  const slug = normalizePublicRouteSlug(publicRouteSlug);
-  if (!slug) return ensureUrlTrailingSlash(baseUrl);
-  try {
-    const url = new URL(ensureUrlTrailingSlash(baseUrl));
-    const segments = url.pathname.split("/").filter(Boolean);
-    if (segments.at(-1) === slug) return ensureUrlTrailingSlash(url.toString());
-    return new URL(`${slug}/`, url).toString();
-  } catch {
-    return ensureUrlTrailingSlash(baseUrl);
-  }
-}
-
 // The campaign's served route root — "/", "/<slug>/", or null — read by the
 // one rule every stage shares (route-identity.mjs): the packet under its exact
 // canonical form, the spec under prepare-build's intake form. A declaration
@@ -4051,10 +4059,6 @@ function resolvePublicRouteSlug({ packet, spec, rawSpec }) {
     || null;
 }
 
-function ensureUrlTrailingSlash(value) {
-  return value.endsWith("/") ? value : `${value}/`;
-}
-
 function stripOrigin(value) {
   try {
     const url = new URL(value);

package/src/qa-test-order-topology.mjs

@@ -5,9 +5,126 @@ const ACTIONS = Object.freeze([
   ["accept", "expected_accept_url"],
 ]);
 
+// The page types of a checkout path, as pageType() spells them (lowercase, `_`
+// and `-` dropped). `checkout` is the page that takes payment; `select` and
+// `checkout_step` lead into it without placing an order (campaigns-os#641).
+const PAYMENT_PAGE_TYPE = "checkout";
+const PRE_PAYMENT_PAGE_TYPES = new Set(["select", "checkoutstep"]);
+
+export function isPaymentTopologyPage(page) {
+  return pageType(page) === PAYMENT_PAGE_TYPE;
+}
+
+export function isCheckoutStepTopologyPage(page) {
+  return pageType(page) === "checkoutstep";
+}
+
+// Follow forward links (expected_next_url) from `start` to the page that takes
+// payment. Null when the walk leaves the topology, loops, or reaches any page
+// that is neither a pre-payment page nor the Checkout.
+export function paymentPageFrom(topology, start) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  const seen = new Set();
+  let page = start || null;
+  while (page && !seen.has(page)) {
+    seen.add(page);
+    if (isPaymentTopologyPage(page)) return page;
+    const key = canonicalHttpUrl(page.expected_next_url);
+    const next = key ? pages.find((candidate) => canonicalHttpUrl(candidate?.url) === key) : null;
+    if (!next) return null;
+    if (!isPaymentTopologyPage(next) && !PRE_PAYMENT_PAGE_TYPES.has(pageType(next))) return null;
+    page = next;
+  }
+  return null;
+}
+
+// The topology's entry pages: flagged is_entry, else those no page links to
+// (offer and receipt pages excluded: an orphaned upsell is not where a shopper
+// starts), else the first page. Never decided by page names.
+function topologyEntryPages(pages) {
+  const flagged = pages.filter((page) => page?.is_entry === true);
+  if (flagged.length) return flagged;
+  const targeted = new Set();
+  for (const page of pages) {
+    for (const field of ["expected_next_url", "expected_accept_url", "expected_decline_url"]) {
+      const key = canonicalHttpUrl(page?.[field]);
+      if (key && key !== canonicalHttpUrl(page?.url)) targeted.add(key);
+    }
+  }
+  const roots = pages.filter((page) => {
+    const key = canonicalHttpUrl(page?.url);
+    const type = pageType(page);
+    return !(key && targeted.has(key)) && !OFFER_PAGE_TYPES.has(type) && !RECEIPT_PAGE_TYPES.has(type);
+  });
+  return roots.length ? roots : pages.slice(0, 1);
+}
+
+// Every Checkout the topology's entry paths reach, in entry order, then any
+// Checkout no entry path reaches (a landing CTA into checkout declares no
+// forward field). "The first page typed checkout" is never the answer on its
+// own: on a multi-step path it is a step, and with split-test paths there are
+// several (campaigns-os#641).
+export function paymentPagesForTopology(topology) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  const out = [];
+  for (const entry of topologyEntryPages(pages)) {
+    const checkout = paymentPageFrom(topology, entry);
+    if (checkout && !out.includes(checkout)) out.push(checkout);
+  }
+  for (const page of pages) if (isPaymentTopologyPage(page) && !out.includes(page)) out.push(page);
+  return out;
+}
+
+// The Checkout of the first entry path of the first topology that has one.
+export function findPaymentPage(topologies = []) {
+  for (const topology of Array.isArray(topologies) ? topologies : []) {
+    const page = paymentPagesForTopology(topology)[0];
+    if (page) return page;
+  }
+  return null;
+}
+
+// The pages a shopper passes through to reach `checkoutPage`, in order and
+// ending with it: an optional select page, then each checkout_step, then the
+// Checkout. Walks backwards over forward links, so it holds whichever path the
+// Checkout sits on; where two pages lead into the same page a checkout_step is
+// preferred over a select page, which can only start the chain.
+export function checkoutPathPages(topology, checkoutPage) {
+  const pages = Array.isArray(topology?.pages) ? topology.pages : [];
+  if (!checkoutPage) return [];
+  const chain = [checkoutPage];
+  const seen = new Set(chain);
+  let current = checkoutPage;
+  for (;;) {
+    const key = canonicalHttpUrl(current?.url);
+    if (!key) break;
+    const leading = pages.filter((page) => !seen.has(page)
+      && PRE_PAYMENT_PAGE_TYPES.has(pageType(page))
+      && canonicalHttpUrl(page?.expected_next_url) === key);
+    const previous = leading.find(isCheckoutStepTopologyPage) || leading[0] || null;
+    if (!previous) break;
+    chain.unshift(previous);
+    seen.add(previous);
+    if (!isCheckoutStepTopologyPage(previous)) break;
+    current = previous;
+  }
+  return chain;
+}
+
+// Only the checkout_step pages of that path, in order.
+export function checkoutStepPages(topology, checkoutPage) {
+  return checkoutPathPages(topology, checkoutPage).filter(isCheckoutStepTopologyPage);
+}
+
 export function resolveTestOrderTopology(topology = {}, checkoutPage = null) {
   const pages = Array.isArray(topology?.pages) ? topology.pages : [];
-  const checkout = checkoutPage || pages.find((page) => pageType(page) === "checkout") || null;
+  // A caller may hand in a select or checkout_step page; the path's Checkout is
+  // the page whose forward link leads to the offers. Starting from a step made
+  // its next step a `nonterminal_target` and hid every offer path.
+  const given = checkoutPage && !isPaymentTopologyPage(checkoutPage) && PRE_PAYMENT_PAGE_TYPES.has(pageType(checkoutPage))
+    ? paymentPageFrom(topology, checkoutPage) || checkoutPage
+    : checkoutPage;
+  const checkout = given || paymentPagesForTopology(topology)[0] || null;
   const pagesByUrl = new Map();
   for (const page of pages) {
     const key = canonicalHttpUrl(page?.url);

package/src/qa-verdict-discovery.mjs

@@ -13,7 +13,7 @@ import { resolveCampaignIdentity, localQaIdentifier } from "./spec-source-identi
 
 import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { QA_OUTPUT_REL_PATH } from "./campaign-workspace.mjs";
 import { absentOrMalformed } from "./fs-identity.mjs";
 import { isPlainObject as isObject, normalizeString as optionalString } from "./repo-scan.mjs";
@@ -53,7 +53,8 @@ export function qaVerdictDir(root, identifier) {
 
 // The verdict paths the Assembly Report's qa stage records (any `*.json`
 // string under a path/file/verdict/output-named key, or inside outputs[] /
-// artifacts[] / qa), relative to the report unless absolute.
+// artifacts[] / qa), relative to the target root unless absolute. Older
+// report-relative hints remain readable.
 export function qaVerdictPathHints(report) {
   const paths = [];
   const visit = (value) => {
@@ -90,7 +91,8 @@ function sha256File(path) {
 }
 
 // Every verdict candidate for a campaign: the files the report records
-// (source "assembly_report", resolved against the report) and every `*.json`
+// (source "assembly_report", resolved against the report first, then the target)
+// and every `*.json`
 // under `qa-output/<identifier>/` beneath each root (source "qa_output").
 //   { path, repoRelPath, source, verdict, sha256, mtimeMs, identityMatch, trusted }
 // `verdict` is null for a recorded path that exists but is not a JSON object
@@ -141,8 +143,14 @@ export function* iterateQaVerdicts({ packet = null, report = null, reportPath =
   };
 
   const reportBase = reportPath ? dirname(resolve(reportPath)) : null;
+  const targetRoot = uniqueTargetRoot(roots, reportBase);
   for (const hint of qaVerdictPathHints(report)) {
-    const found = candidate(reportBase ? resolve(reportBase, hint) : hint, "assembly_report", null);
+    const reportRelative = (isAbsolute(hint) || reportBase)
+      ? candidate(isAbsolute(hint) ? hint : resolve(reportBase, hint), "assembly_report", null)
+      : null;
+    const found = reportRelative || (!isAbsolute(hint) && targetRoot
+      ? candidate(resolve(targetRoot, hint), "assembly_report", null)
+      : null);
     if (found) yield found;
   }
 
@@ -172,6 +180,15 @@ export function* iterateQaVerdicts({ packet = null, report = null, reportPath =
   }
 }
 
+function uniqueTargetRoot(roots, reportBase) {
+  for (let directory = reportBase; directory; directory = dirname(directory)) {
+    if (basename(directory) === ".campaign-runtime") return dirname(directory);
+    if (dirname(directory) === directory) break;
+  }
+  const candidates = [...new Set(roots.filter((root) => typeof root === "string" && root).map((root) => resolve(root)))];
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
 export function discoverQaVerdicts(options = {}) {
   return [...iterateQaVerdicts(options)];
 }