@nextcommerce/campaigns-os 1.57.0 → 1.60.0

package/src/page-kit-build-summary.mjs

@@ -165,9 +165,29 @@ export function evaluatePageKitBuildSummary({
     }
   }
 
+  // page-kit >= 0.3.0 neither builds nor copies .html under assets/ and lists
+  // each such file in a top-level assetWarnings array (ASSET_IGNORED), never
+  // in pages[].warnings. A link or iframe to one 404s on the built site, and
+  // this is the only signal, so it is surfaced, but never escalated: removing
+  // or moving the file is the author's call. Entries carry no campaignSlug;
+  // the file path (src/<slug>/assets/...) names the campaign.
+  const assetWarnings = Array.isArray(summary.assetWarnings)
+    ? summary.assetWarnings.filter((warning) => typeof warning?.file === "string" && `/${warning.file.replace(/\\/g, "/")}`.includes(`/${publicRouteSlug}/assets/`))
+    : [];
+  for (const warning of assetWarnings) {
+    flagged += 1;
+    warnings.push({
+      code: "built_output.build_asset_warning",
+      message:
+        `Page Kit did not build or copy "${warning.file}": [${warning.code}] ${warning.message}. ` +
+        `A link or iframe to it 404s on the built site; move it out of assets/ if it is a page, or remove it.`,
+      detail: { file: warning.file, warning_code: warning.code },
+    });
+  }
+
   if (failed === 0 && flagged === 0) {
     ready.push(
-      `Page Kit build summary verified for "${publicRouteSlug}": ${campaignPages.length} page(s) built, no build errors or shape warnings`
+      `Page Kit build summary verified for "${publicRouteSlug}": ${campaignPages.length} page(s) built, no build errors, shape warnings or asset warnings`
     );
   }
 

package/src/page-kit-campaign-config.mjs

@@ -1,9 +1,28 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { compareVersions, extractVersion } from "./repo-scan.mjs";
 import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
 export const PAGE_KIT_CAMPAIGNS_REL_PATH = "_data/campaigns.json";
 
+// next-campaign-page-kit 0.3.0 stopped building or copying .html under a
+// campaign's top-level assets/. Source-page discovery follows the target's
+// installed page-kit, read from node_modules the way tooling setup reads it;
+// a missing, unreadable or malformed install keeps the 0.2.x rule. That is
+// deliberate: doctor's built-page lookup calls this from about ten checks, so
+// throwing would take doctor down over a broken install that the build itself
+// fails on loudly, and tooling setup already refuses a declared page-kit that
+// is not installed.
+export const PAGE_KIT_ASSETS_HTML_IGNORED_FROM = "0.3.0";
+export function pageKitIgnoresAssetsHtml(targetRepo) {
+  try {
+    const { version } = JSON.parse(readFileSync(join(targetRepo, "node_modules", "next-campaign-page-kit", "package.json"), "utf8"));
+    return extractVersion(version) !== null && compareVersions(version, PAGE_KIT_ASSETS_HTML_IGNORED_FROM) >= 0;
+  } catch {
+    return false;
+  }
+}
+
 // Public doctor/next/verdict evidence must never inherit arbitrary merchant
 // configuration from campaigns.json. The raw entry is validation-local; this
 // fixed projection is the only loader metadata safe to retain in artifacts.

package/src/polish-gate.mjs

@@ -45,11 +45,7 @@ function terminalAssembly(report) {
 }
 
 export function currentBuildFingerprint(report) {
-  return normalizeString(report?.stages?.assembly?.build_fingerprint)
-    || normalizeString(report?.stages?.assembly?.artifact_fingerprint)
-    || normalizeString(report?.build_fingerprint)
-    || normalizeString(report?.artifact_fingerprint)
-    || null;
+  return normalizeString(report?.stages?.assembly?.build_fingerprint) || null;
 }
 
 export function currentSourcePackageMaterialFingerprint(report) {

package/src/polish-node.mjs

@@ -3,7 +3,7 @@ import { NO_CAPTURABLE_ROUTES_CODE } from "./local-preview-policy.mjs";
 import { createHash } from "node:crypto";
 import { HIDDEN_EAGER_MEDIA_ACTIONS } from "./gate-actions.mjs";
 import { dirname, join, resolve } from "node:path";
-import { computeBuildFingerprint } from "./built-site-scope.mjs";
+import { computeBuildFingerprint, describeBuildOutputDrift } from "./built-site-scope.mjs";
 import {
   buildPageLoadCapture,
   MAX_POLISH_CAPTURE_URL_LENGTH,
@@ -402,7 +402,7 @@ export function createPolishCaptureBinding({ packet, report, plan, packetPath, t
   // an output that has drifted from what build recorded would be evidence
   // about a build that no longer exists, and an output that changes during the
   // browser pass fails the unchanged-binding assertion after it.
-  const outputFingerprint = boundOutputFingerprint(join(resolve(targetRepo), "_site", slug), slug, buildFingerprint);
+  const outputFingerprint = boundOutputFingerprint(join(resolve(targetRepo), "_site", slug), slug, buildFingerprint, report.stages.assembly);
   const runId = nonemptyString(report.run_id);
   const reportPacketPath = nonemptyString(report?.inputs?.packet_path);
   if (!runId || !reportPacketPath) {
@@ -585,7 +585,7 @@ function uncapturedPages(packet, plan) {
 // (permissions, a file vanishing mid-walk), or an output that no longer
 // matches what build recorded. None of them may surface as an uncaught
 // filesystem error, and none may bind as a null.
-function boundOutputFingerprint(outputRoot, slug, buildFingerprint) {
+function boundOutputFingerprint(outputRoot, slug, buildFingerprint, assembly = null) {
   let current;
   try {
     current = computeBuildFingerprint(outputRoot);
@@ -604,7 +604,8 @@ function boundOutputFingerprint(outputRoot, slug, buildFingerprint) {
   if (current.fingerprint !== buildFingerprint) {
     throw new Error(
       `polish capture refuses: built output under _site/${slug}/ no longer matches stages.assembly.build_fingerprint `
-      + `(recorded ${buildFingerprint}, current ${current.fingerprint}). Re-run build and record the current fingerprint first.`,
+      + `(recorded ${buildFingerprint}, current ${current.fingerprint}). ${describeBuildOutputDrift(assembly, current).summary} `
+      + "Re-run build and record the current fingerprint first.",
     );
   }
   return current.fingerprint;

package/src/progress-node.mjs

@@ -6,6 +6,7 @@ import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
 import {effectiveStageStatus} from './input-currency.mjs';
+import {qaRecordedBuildFingerprint} from './stage-ledger.mjs';
 import {sameFile} from './fs-identity.mjs';
 import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
@@ -64,7 +65,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   // The report is also bound to the spec material on disk now, so output and
   // verdict evidence recorded against it can match.
   const reportBound=stagesBound&&localHash===hash(report?.identity?.spec_material_hash);
-  const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
+  const qaSource=hash(qaRecordedBuildFingerprint(report));
   const verdict=qaResult?.verdict;
   const qa=verdict?{
     verdict_id:id(verdict.run_id),disposition:accepted(verdict.disposition,['ready','ready_with_exceptions','blocked']),

package/src/qa-browser.mjs

@@ -52,6 +52,13 @@ import {
   isCartEntryCode,
   resolveCartEntryPage,
   sdkCartSnapshotScript,
+  SLOT_VARIANT_DROPDOWN_ROW_SELECTOR,
+  SLOT_VARIANT_DROPDOWN_TOGGLE_SELECTOR,
+  SLOT_VARIANT_FIELD_SELECTOR,
+  SLOT_VARIANT_SELECT_SELECTOR,
+  slotVariantKey,
+  slotVariantLabel,
+  slotVariantStepScript,
   summarizeSelectionSurface,
   UNDECLARED_ROUTE_ATTRIBUTES,
 } from "./qa-cart-entry.mjs";
@@ -304,7 +311,7 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
       const identifier = planId(plan);
       const pageForPlan = (typeof plan === "object" && plan?.checkout_page?.url) ? plan.checkout_page : checkoutPage;
       const firstAttempt = await runSingle(context, pageForPlan, plan, args, runId, attemptOptions);
-      orders.push(firstAttempt.order);
+      orders.push(testOrderEntry(firstAttempt.order, identifier, 1));
       orderPlans.push(plan);
       // Every attempt this path actually SUBMITTED, in order. The confirmed
       // creation count is read from these and never from the deciding result
@@ -364,7 +371,7 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
               const rerunAttempt = await runSingle(context, pageForPlan, plan, args, runId, attemptOptions);
               attemptsForPlan.push(rerunAttempt);
               if (rerunAttempt.order) {
-                orders.push(rerunAttempt.order);
+                orders.push(testOrderEntry(rerunAttempt.order, identifier, 2));
                 orderPlans.push(plan);
               }
               if (rerunAttempt.budget_exhausted) {
@@ -500,6 +507,17 @@ async function dispatchTestOrderPlans({ context, plans, checkoutPage, args = {},
   return { orders, assertions, receiptAnalytics, journeyAnalytics, creationBudget, qcResults };
 }
 
+// One test_orders[] entry per attempt, never one per planned path: a re-run
+// places its own real order and the operator cleaning up test orders needs both.
+// So each entry names the planned path it belongs to (`plan_id`, the same id the
+// creation budget charges) and which attempt it was, 1-based, so a reader can
+// tell 5 paths with one retry each from 10 paths (#661). A copy, so the attempt
+// result the assertions read is left as the runner returned it.
+function testOrderEntry(order, identifier, attempt) {
+  if (!order || typeof order !== "object") return order;
+  return { ...order, plan_id: order.plan_id ?? identifier, attempt };
+}
+
 // Analytics-parity leg: capture the live dataLayer event stream + GTM/pixel
 // tag-fires on a baseline (legacy) URL and a candidate (migrated) URL, then
 // diff them into parity assertions. Highest-value target is the thank-you /
@@ -4378,6 +4396,11 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
     cardSelection = choice.select_card ? await selectPackageCard(page, choice.select_card, []) : null;
     control.package_id = choice.select_card?.packageId || await selectedBundleCardPackage(page);
   }
+  // Each bundle slot may need a variant (size, colour) before the page lets
+  // Next through (campaigns-os#667). Fill every visible empty slot variant
+  // select with its first in-stock option now, after the card that decides
+  // the slots, and refuse by name when one has nothing to choose.
+  const variantSelections = control.kind === "checkout_button" ? await fillSlotVariants(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 controlSelector = control.kind === "add_to_cart"
@@ -4414,6 +4437,7 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
       control_kind: control.kind,
       package_id: control.package_id || null,
       ...(cardSelection ? { bundle_card_selection: cardSelection } : {}),
+      ...(variantSelections.length ? { variant_selections: variantSelections } : {}),
       sdk_ready: sdkReady,
       arrived_url: redactUrlQuery(safePageUrl(page)),
       checkout_selection_surface: surface,
@@ -4422,6 +4446,117 @@ async function enterCartViaLanding({ page, checkoutPage, entryPage, selectedPack
   };
 }
 
+// Chooses a select page's slot variants one at a time (a choice can
+// re-render its slot) and returns the choices. A field showing a dropdown UI
+// is picked like a shopper, toggle then row, even when its select is
+// pre-filled, because a page may count a field as chosen only when a row was
+// clicked (campaigns-os#667). A select with no dropdown UI is filled only when
+// empty; a pre-filled native-only page returns [] untouched. Throws
+// ENTRY_VARIANT_UNFILLED, before any click on the checkout control, when a
+// field has no in-stock row or option, a pick cannot be clicked, or the page
+// keeps asking for more choices.
+const SLOT_VARIANT_FILL_LIMIT = 40;
+const SLOT_VARIANT_ROW_WAIT_MS = 2000;
+
+// The slot variant field a pick names, found again by its slot identity
+// (data-next-bundle-id, data-next-slot-index, variant code) so a re-render
+// since the pick was planned does not leave a stale index; the planned index
+// is the fallback for a field that carries no slot index.
+async function slotVariantField(page, pick) {
+  const fields = page.locator(SLOT_VARIANT_FIELD_SELECTOR);
+  const index = await fields.evaluateAll((nodes, want) => {
+    const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const found = nodes.findIndex((node) => {
+      const slotIndex = Number.parseInt(node.getAttribute("data-next-slot-index") ?? "", 10);
+      if (!Number.isFinite(slotIndex) || slotIndex + 1 !== want.slot) return false;
+      if ((clean(node.getAttribute("data-next-bundle-id")) || null) !== want.bundle_id) return false;
+      const select = node.querySelector("select");
+      const code = clean(select?.getAttribute("data-next-variant-code") || select?.getAttribute("data-variant-code") || node.getAttribute("data-next-variant-code") || select?.name) || null;
+      return code === want.variant_code;
+    });
+    return found >= 0 ? found : want.field_index;
+  }, pick).catch(() => pick.field_index);
+  return fields.nth(index);
+}
+
+// The pick's row, matched by its value among the field's rows (no selector is
+// built from the value), once it is visible; null if it does not show in time.
+async function visibleSlotVariantRow(page, pick, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const field = await slotVariantField(page, pick);
+    const rows = field.locator(SLOT_VARIANT_DROPDOWN_ROW_SELECTOR);
+    const index = await rows.evaluateAll((nodes, value) => nodes.findIndex((node) => {
+      if (String(node.getAttribute("value") || "").replace(/\s+/g, " ").trim() !== value) return false;
+      const rect = node.getBoundingClientRect();
+      const style = getComputedStyle(node);
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+    }), pick.value).catch(() => -1);
+    if (index >= 0) return rows.nth(index);
+    if (Date.now() >= deadline) return null;
+    await page.waitForTimeout(100);
+  }
+}
+async function fillSlotVariants(page) {
+  const selections = [];
+  const picked = [];
+  const step = () => page.evaluate(slotVariantStepScript(), {
+    selector: SLOT_VARIANT_SELECT_SELECTOR,
+    fieldSelector: SLOT_VARIANT_FIELD_SELECTOR,
+    toggleSelector: SLOT_VARIANT_DROPDOWN_TOGGLE_SELECTOR,
+    rowSelector: SLOT_VARIANT_DROPDOWN_ROW_SELECTOR,
+    picked,
+  }).catch(() => ({ done: true }));
+  for (let pass = 0; pass < SLOT_VARIANT_FILL_LIMIT; pass += 1) {
+    const result = await step();
+    if (result?.done) {
+      if (selections.length) await page.waitForLoadState("networkidle", { timeout: 3000 }).catch(() => {});
+      return selections;
+    }
+    if (result?.unfillable?.detail) {
+      throw codedError(CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED, `${slotVariantLabel(result.unfillable)}: ${result.unfillable.detail}; the page would refuse Next`);
+    }
+    if (result?.unfillable) {
+      throw codedError(
+        CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED,
+        `${slotVariantLabel(result.unfillable)} has no in-stock ${result.unfillable.via === "dropdown" ? "dropdown row" : "option"} to choose (${result.unfillable.options} ${result.unfillable.via === "dropdown" ? "row" : "option"}(s), all disabled or placeholder); the page would refuse Next`,
+      );
+    }
+    const choice = result.pick || result.filled;
+    if (result.pick) {
+      try {
+        const field = await slotVariantField(page, result.pick);
+        await clickControl(field.locator(SLOT_VARIANT_DROPDOWN_TOGGLE_SELECTOR).filter({ visible: true }).first(), { timeout: 5000 });
+        // The menu may open late or re-render on toggle: re-resolve the field
+        // and the row by its value, and wait for that row to show.
+        const row = await visibleSlotVariantRow(page, result.pick, SLOT_VARIANT_ROW_WAIT_MS);
+        if (!row) {
+          throw codedError(
+            CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED,
+            `${slotVariantLabel(choice)} dropdown row "${choice.value}" did not show within ${SLOT_VARIANT_ROW_WAIT_MS}ms of opening the dropdown; the page would refuse Next`,
+          );
+        }
+        await clickControl(row, { timeout: 5000 });
+      } catch (error) {
+        if (error?.code === CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED) throw error;
+        throw codedError(
+          CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED,
+          `${slotVariantLabel(choice)} dropdown row "${choice.value}" could not be clicked (${String(error?.message || error).split("\n")[0]}); the page would refuse Next`,
+        );
+      }
+      picked.push(slotVariantKey(choice));
+    }
+    selections.push({ bundle_id: choice.bundle_id, slot: choice.slot, variant_code: choice.variant_code, value: choice.value, via: result.pick ? "dropdown" : "select" });
+    await page.waitForTimeout(250);
+  }
+  const pending = await step();
+  if (pending?.done) return selections;
+  throw codedError(
+    CART_ENTRY_CODES.ENTRY_VARIANT_UNFILLED,
+    `${slotVariantLabel(pending.pick || pending.filled || pending.unfillable)} still needed a choice after ${SLOT_VARIANT_FILL_LIMIT} variant choices; the page keeps clearing them`,
+  );
+}
+
 // The package of the bundle card a select page shows as selected, or null.
 async function selectedBundleCardPackage(page) {
   return page.evaluate((cardSelector) => {

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",
@@ -427,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

@@ -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";
@@ -3577,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) {

package/src/qa-verdict.mjs

@@ -256,7 +256,8 @@ export function summarizePurchaseProof({ verdict = null, proofPolicy = null } =
   return {
     declared_order_path_depth: optionalString(proofPolicy?.order_path_depth),
     declared_typed_card_depth: optionalString(proofPolicy?.typed_card_depth),
-    order_paths_executed: orders.length,
+    order_paths_executed: orders.filter((order) => !isTestOrderRetry(order)).length,
+    test_order_attempts: orders.length,
     orders_created: created.length,
     orders_verified: orders.filter((order) => order.verification?.verified === true).length,
     // null, not false, when nothing ran: "no order was out of test mode" and
@@ -265,6 +266,28 @@ export function summarizePurchaseProof({ verdict = null, proofPolicy = null } =
   };
 }
 
+// A re-run of a planned path is its own test_orders[] entry with `attempt` 2;
+// it is an attempt, not another path. Entries written before `attempt` existed
+// each count as a path, which is what they were counted as then.
+function isTestOrderRetry(order) {
+  const attempt = Number(order?.attempt);
+  return Number.isInteger(attempt) && attempt > 1;
+}
+
+function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+// The human summary line for a run that drove typed-card test orders: planned
+// paths, attempts (a re-run is a second attempt at the same path) and orders
+// the platform created, kept apart so a path that was retried is not read as
+// two paths against the --max-test-orders cap. null when no order path ran.
+export function formatTestOrderSummary(verdict) {
+  const summary = summarizePurchaseProof({ verdict });
+  if (!summary.test_order_attempts) return null;
+  return `Test orders: ${plural(summary.order_paths_executed, "path")}, ${plural(summary.test_order_attempts, "attempt")}, ${plural(summary.orders_created, "order")} created`;
+}
+
 // The browser placeholder-text residue gate (H3.1) emits one assertion per
 // page as `template-residue:<page_id>:placeholder-text`. Both the emitter
 // (qa-browser.mjs) and the stage-ledger summary below build the id from this

package/src/sdk-attribute-index.mjs

@@ -2,7 +2,7 @@
 // checks (#303).
 //
 // Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
-// v0.4.41 (the SDK pin every certified starter family ships today): every
+// v0.4.42 (the SDK pin every certified starter family ships today): every
 // data-next-* name the SDK's non-test TypeScript names as a string, plus every
 // `dataset.next*` property it reads or writes, turned back into its
 // attribute. Only the data-next-* names are kept: the checks that read this
@@ -15,8 +15,8 @@
 // whole from the source at a named tag, never edited by hand.
 //
 //   paths=('src/**/*.ts' ':!src/**/*.test.ts' ':!src/**/tests/**' ':!src/docs/**')
-//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.41 -- "${paths[@]}"
-//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.41 -- "${paths[@]}" \
+//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.42 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.42 -- "${paths[@]}" \
 //       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
 //   } | sort -u
 //
@@ -30,14 +30,15 @@
 // manifests never did (the address block's, data-next-i18n,
 // data-next-bump-section, data-next-button-text, the variant option state).
 // At v0.4.41 it returns every name of the v0.4.38 list this replaces, plus
-// those and data-next-phone-e164 / data-next-phone-country.
+// those and data-next-phone-e164 / data-next-phone-country. At v0.4.42 it
+// returns the same 149 names as at v0.4.41.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
 import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.41";
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.42";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -364,8 +365,8 @@ export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
 });
 
 // The SDK versions whose renderer files above were verified unchanged from
-// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40 and v0.4.41, for
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40, v0.4.41 and v0.4.42, for
 // the eight renderer files cited above plus cart-item-list.enhancer.ts and
 // order-item-list.enhancer.ts). A page whose loader pins another version
 // cannot pass the placeholder check.
-export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41"]);
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41", "0.4.42"]);

package/src/source-html-intake.mjs

@@ -4,7 +4,7 @@ import {
 } from "./source-html-manifest.mjs";
 // Built output of campaign-spec (same import shape as src/page-kit-sdk-version.mjs),
 // so build-time wiring and spec-time analysis share one edge resolver.
-import { checkoutPathFrom, declineRouteTarget, forwardRouteTarget, forwardTargetPage, isCheckoutStepPage } from "../campaign-spec/dist/index.js";
+import { checkoutPathFrom, declineRouteTarget, forwardRouteTarget, forwardTargetPage, isCheckoutStepPage, isPrePaymentPage } from "../campaign-spec/dist/index.js";
 import { isAbsoluteHttpUrl, normalizePageKitRoute, normalizePublicRouteSlug, stripPublicRoutePrefix } from "./route-identity.mjs";
 
 const CPK_PAGE_TYPES = new Set(["product", "checkout", "upsell", "receipt"]);
@@ -570,11 +570,12 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir,
   const frontmatter = { page_type: pageType };
   if (permalinkRequired) frontmatter.permalink = publicRoute;
 
-  const nextUrl = nextUrlForPage(page, pageById, publicRouteSlug);
-  if (nextUrl) frontmatter.next_url = nextUrl;
+  const forwardUrl = nextUrlForPage(page, pageById, publicRouteSlug);
+  const checkoutFlow = checkoutFlowFrontmatter(page, forwardUrl, { specPages, pageById, publicRouteSlug });
+  if (checkoutFlow) Object.assign(frontmatter, checkoutFlow);
+  else if (forwardUrl) frontmatter.next_url = forwardUrl;
   const declineUrl = declineUrlForPage(page, pageById, publicRouteSlug);
-  if (declineUrl && declineUrl !== nextUrl) frontmatter.decline_url = declineUrl;
-  Object.assign(frontmatter, checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }));
+  if (declineUrl && declineUrl !== forwardUrl) frontmatter.decline_url = declineUrl;
 
   return {
     target_path: targetPath,
@@ -587,24 +588,32 @@ function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir,
   };
 }
 
-// Multi-step checkout wiring (campaigns-os#641), for any page that leads into a
-// Checkout without being it: a select page, a checkout_step, or a landing page
-// whose forward links reach a Checkout.
-//   success_url  the Checkout's post-payment destination (its own next_url).
-//                The page's next-success-url meta tag carries it, because the
-//                SDK reads that tag for express orders placed on this page; an
-//                express order on step 1 must land on the first upsell, not on
-//                step 2. Forward navigation never uses that tag: a step form
-//                navigates by data-next-checkout-step, a select page by a link.
+// Multi-step checkout wiring (campaigns-os#641) for a select or checkout_step
+// page on a path to a Checkout. The keys follow the starter-template contract
+// (campaign-cart-starter-templates#223). Null for any other page, whose
+// next_url stays its own forward link: a landing page's call-to-action reads
+// next_url, so pointing it past the Checkout would skip payment.
+//   next_url     where a completed order goes: the Checkout's post-payment
+//                destination (its own next_url), the meaning next_url has on a
+//                single-page checkout. The page's next-success-url meta tag
+//                carries it, because the SDK reads that tag for express orders
+//                placed on this page; an express order on step 1 must land on
+//                the first upsell, not on step 2.
+//   next_step    this page's forward link: a step form's
+//                data-next-checkout-step, a select page's checkout link.
 //   step_number  on a checkout_step only: its position among the steps of its
 //                path, from 1, for the form's data-next-step-number.
-function checkoutFlowFrontmatter(page, { specPages, pageById, publicRouteSlug }) {
-  if (!page || page.type === "checkout") return {};
+function checkoutFlowFrontmatter(page, forwardUrl, { specPages, pageById, publicRouteSlug }) {
+  // A path of two or more pages means the page has a resolvable forward link,
+  // so forwardUrl is set; the guard keeps the pair together regardless, never
+  // emitting the Checkout's destination without a next_step to navigate by.
+  if (!isPrePaymentPage(page) || !forwardUrl) return null;
   const path = checkoutPathFrom(specPages, page);
-  if (!path || path.length < 2) return {};
+  if (!path || path.length < 2) return null;
   const out = {};
   const successUrl = nextUrlForPage(path[path.length - 1], pageById, publicRouteSlug);
-  if (successUrl) out.success_url = successUrl;
+  if (successUrl) out.next_url = successUrl;
+  out.next_step = forwardUrl;
   if (isCheckoutStepPage(page)) out.step_number = checkoutStepNumber(page, specPages);
   return out;
 }