@nextcommerce/campaigns-os 1.50.0 → 1.53.0

package/src/readback.mjs

@@ -8,7 +8,9 @@
  * most once, plus two fixed Git metadata files for the staleness comparison
  * (the nearest `.git` entry at the target or one of its ancestors — funnels are
  * usually subdirectories of their enclosing campaign repository — to locate the
- * Git directory, and that directory's `logs/HEAD` reflog). It writes nothing,
+ * Git directory, and that directory's `logs/HEAD` reflog), plus the CampaignSpec
+ * and normalized Campaign Build Brief the Build Packet names, whose current
+ * content decides each stage's effective status. It writes nothing,
  * starts no process, and touches no network. That contract is why the CLI
  * exempts `readback` from lifecycle-journal capture the way it exempts doctor
  * inspection: a command declared read-only must not append a journal entry.
@@ -49,6 +51,9 @@ import { closeSync, fstatSync, openSync, readdirSync, readSync, statSync } from
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { assessInputCurrency, currentPacketInputs, effectiveStageStatus } from "./input-currency.mjs";
+import { deriveAssemblyReportSummary } from "./stage-ledger.mjs";
+
 export const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 export const MAX_GIT_METADATA_BYTES = 64 * 1024;
 
@@ -1268,22 +1273,52 @@ export function renderBlocker(blocker) {
   return `(non-string entry, shown as written) ${rendered}`;
 }
 
-function renderStages(views, lines) {
+/**
+ * The campaign's current inputs, read through the projected Build Packet: the
+ * material of the CampaignSpec and of the normalized brief it names. A value
+ * that cannot be read is null, and the stages that depend on it read unknown.
+ */
+export function readbackInputs(views) {
+  const packet = artifactData(views, "packet");
+  if (packet === null) return { briefMaterial: null, specMaterial: null };
+  return currentPacketInputs({ packet, packetPath: resolve(views.packet.path) });
+}
+
+// Superseded records shown per stage, newest last (the report keeps five).
+const HISTORY_RENDER_CAP = 5;
+
+/**
+ * Each stage at its effective status against `inputs` (readbackInputs): a
+ * stage owed again by a brief or CampaignSpec change reads `required`, one
+ * whose inputs cannot be confirmed reads `unknown`, and where that differs
+ * from the record the line adds the recorded status and the reason. The
+ * header carries the report's recorded status beside the one recomputed from
+ * the effective statuses. Superseded records are listed only under the
+ * "history (not current proof)" label.
+ */
+function renderStages(views, lines, inputs = null) {
   const report = artifactData(views, "report");
   if (report === null) return;
-  lines.push(`STAGES  [assembly report; report status: ${recorded(report.status)}]`);
+  const current = { briefMaterial: inputs?.briefMaterial ?? null, specMaterial: inputs?.specMaterial ?? null };
+  const currency = assessInputCurrency({ report, ...current });
+  const effectiveReport = deriveAssemblyReportSummary(report, current).status;
+  lines.push(`STAGES  [assembly report; report status: ${recorded(report.status)}; effective: ${effectiveReport}]`);
   const stages = report.stages;
   if (isPlainObject(stages)) {
     for (const [name, stage] of Object.entries(stages)) {
       if (!isPlainObject(stage)) continue;
       const status = stage.status ?? "(no status recorded)";
+      const effective = effectiveStageStatus(name, stage, currency);
+      const shown = effective === stage.status
+        ? status
+        : `${effective.padEnd(10)} (recorded: ${status}; ${currency.reasons?.[name] ?? "status_unrecognized"})`;
       const counters = [];
       const blockers = stage.blockers;
       const warnings = stage.warnings;
       if (Array.isArray(blockers) && blockers.length) counters.push(`${blockers.length} blocker(s)`);
       if (Array.isArray(warnings) && warnings.length) counters.push(`${warnings.length} warning(s)`);
       const suffix = counters.length ? `  (${counters.join(", ")})` : "";
-      lines.push(`  ${name.padEnd(14)} ${status}${suffix}`);
+      lines.push(`  ${name.padEnd(14)} ${shown}${suffix}`);
       if (Array.isArray(blockers) && blockers.length) {
         for (const blocker of blockers.slice(0, BLOCKER_RENDER_CAP)) {
           lines.push(`    blocker: ${renderBlocker(blocker)}`);
@@ -1291,6 +1326,16 @@ function renderStages(views, lines) {
         const hidden = blockers.length - BLOCKER_RENDER_CAP;
         if (hidden > 0) lines.push(`    ... and ${hidden} more blocker(s) recorded in the assembly report`);
       }
+      const history = Array.isArray(stage.history) ? stage.history.filter(isPlainObject) : [];
+      if (history.length) {
+        lines.push(`    history (not current proof): ${history.length} superseded record(s)`);
+        for (const entry of history.slice(-HISTORY_RENDER_CAP)) {
+          lines.push(
+            `      ${oneLine(String(recorded(entry.archived_at)))} ${oneLine(String(recorded(entry.reason_code)))}: ` +
+              `was ${oneLine(String(recorded(entry.status)))}${entry.archived_by ? ` (archived by ${oneLine(String(entry.archived_by))})` : ""}`,
+          );
+        }
+      }
     }
   }
   lines.push("");
@@ -1496,8 +1541,10 @@ function renderFindings(views, lines) {
  * artifact table says nothing about how the packet was chosen. The
  * one-argument form keeps working: the artifact table shows each loaded
  * artifact's generated_at regardless of whether an assessment was supplied.
+ * `inputs` is readbackInputs(views); when omitted, every input reads as not
+ * readable, so a build, Polish or QA record reads unknown.
  */
-export function projectReadback(views, staleness = null, packetSelection = null) {
+export function projectReadback(views, staleness = null, packetSelection = null, inputs = null) {
   const lines = [
     "CAMPAIGNS OS RUN-ARTIFACT READBACK",
     "A read-only projection of this run's emitted artifacts. Campaigns OS",
@@ -1509,7 +1556,7 @@ export function projectReadback(views, staleness = null, packetSelection = null)
   renderStaleness(staleness, lines);
   renderArtifactTable(views, lines, packetSelection);
   renderIdentity(views, lines);
-  renderStages(views, lines);
+  renderStages(views, lines, inputs);
   renderContext(views, lines);
   renderDoctor(views, lines);
   renderVerdict(views, lines);
@@ -1806,7 +1853,7 @@ export function resolvePaths(root, overrides = {}) {
 export function projectTarget(root, overrides = {}) {
   const { paths, packetSelection, packetView } = resolveProjection(root, overrides);
   const views = loadArtifacts(paths, { packet: packetView });
-  return { views, staleness: assessStaleness(root, views), packetSelection };
+  return { views, staleness: assessStaleness(root, views), packetSelection, inputs: readbackInputs(views) };
 }
 
 // The bundled synthetic sample `--example` projects. It is already on the
@@ -1837,6 +1884,7 @@ export const EXAMPLE_HEAD_DETAIL =
 export function projectExample() {
   const { paths, packetSelection, packetView } = resolveProjection(EXAMPLE_ROOT, {});
   const views = loadArtifacts(paths, { packet: packetView });
+  const inputs = readbackInputs(views);
   for (const view of Object.values(views)) {
     const within = view.path.slice(EXAMPLE_ROOT.length).replace(/\\/g, "/").replace(/^\/+/, "");
     view.path = `${EXAMPLE_RELATIVE_ROOT}/${within}`;
@@ -1844,7 +1892,7 @@ export function projectExample() {
   const staleness = assessStaleness(EXAMPLE_ROOT, views, {
     headMovement: { time: null, detail: EXAMPLE_HEAD_DETAIL },
   });
-  return { views, staleness, packetSelection };
+  return { views, staleness, packetSelection, inputs };
 }
 
 const OVERRIDE_FLAGS = {
@@ -1938,9 +1986,9 @@ export function runReadbackCommand(args) {
     if (error instanceof ReadbackUsageError) return { exitCode: 2, text: `${error.message}\n` };
     throw error;
   }
-  const { views, staleness, packetSelection } = projection;
+  const { views, staleness, packetSelection, inputs } = projection;
   const text = request.json
     ? `${JSON.stringify(buildJsonPayload(views, staleness, packetSelection), null, 2)}\n`
-    : projectReadback(views, staleness, packetSelection);
+    : projectReadback(views, staleness, packetSelection, inputs);
   return { exitCode: 0, text };
 }

package/src/sdk-attribute-index.mjs

@@ -210,3 +210,74 @@ export function isKnownCheckoutFieldName(value) {
   return SDK_CHECKOUT_FIELD_NAMES.includes(name)
     || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
 }
+
+// The Campaign Cart template placeholders, for the raw cart placeholder check
+// (built_output.cart_placeholders). Generated from the SDK renderers at the
+// same tag as the attribute index above, v0.4.38:
+//
+//   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
+//   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
+//     228-240,256-314 ({item.*} and its {line.*} alias, {property.*},
+//     {discount.*})
+//   src/features/cart/package-selector/package-selector.renderer.ts:26
+//     ({package.<any key>})
+//   src/features/cart/bundle-selector/bundle-selector.renderer.ts:37-42
+//     ({bundle.<any key>})
+//   src/features/cart/package-toggle/package-toggle.enhancer.ts:59-65
+//     ({toggle.<any key>})
+//   src/features/cart/quantity-control/quantity-control.renderer.ts:69-70
+//     ({quantity}, {step})
+//   src/features/cart/remove-item/remove-item.renderer.ts:26 ({quantity})
+//   src/features/display/quantity-text/quantity-text.enhancer.ts:124,149
+//     ({qty...} and {singular|plural})
+//
+// Every namespaced renderer replaces any `{<namespace>.<key>}` in its
+// template (item.property.<key> and the package, bundle and toggle keys are
+// open-ended; an unmapped key renders empty), so the namespace alone makes a
+// token known. `{tax}` is not a cart-summary var at this tag. Regenerate the
+// lists whole from the renderers when the index pin advances; never edit them
+// by hand.
+export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
+  cart_summary_vars: Object.freeze([
+    "subtotal",
+    "total",
+    "shipping",
+    "shippingName",
+    "shippingCode",
+    "shippingOriginal",
+    "shippingDiscountAmount",
+    "shippingDiscountPercentage",
+    "totalDiscount",
+    "totalDiscountPercentage",
+    "discounts",
+    "currency",
+    "isCalculating",
+    "isEmpty",
+    "itemCount",
+    "totalQuantity",
+    "isFreeShipping",
+    "hasShippingDiscount",
+    "hasDiscounts",
+  ]),
+  namespaces: Object.freeze(["item", "line", "discount", "property", "package", "bundle", "toggle"]),
+  // Tokens the SDK substitutes in live markup, and the elements that own them.
+  live_tokens: Object.freeze(["quantity", "step", "qty"]),
+  // [data-next-quantity="increase|decrease|set"]: {quantity} and {step}.
+  quantity_control: Object.freeze({ attribute: "data-next-quantity", values: Object.freeze(["increase", "decrease", "set"]), tokens: Object.freeze(["quantity", "step"]) }),
+  // [data-next-remove-item]: {quantity} only.
+  remove_item: Object.freeze({ attribute: "data-next-remove-item", tokens: Object.freeze(["quantity"]) }),
+  // [data-next-quantity-text]: {qty...} and the singular/plural form.
+  // `qty_forms` is the renderer's own {qty} pattern (quantity-text.enhancer.ts:
+  // 124, /\{qty([*+\-]?\d*)\}/): {qty}, {qty*2}, {qty+1}, {qty-1}.
+  quantity_text: Object.freeze({ attribute: "data-next-quantity-text", tokens: Object.freeze(["qty"]), qty_forms: "qty[*+\\-]?\\d*" }),
+  // Item lists whose innerHTML the SDK uses as the row template or replaces
+  // (cart-item-list.enhancer.ts:21-35, order-item-list.enhancer.ts:26-36).
+  item_list_containers: Object.freeze(["data-next-cart-items", "data-next-order-items"]),
+  item_template_selector: "data-item-template-selector",
+  item_template: "data-item-template",
+});
+
+// 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 and v0.4.40). 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"]);

package/src/sdk-markup.mjs

@@ -86,7 +86,7 @@ export const SDK_MARKUP_CODES = Object.freeze({
 
 // Attributes whose value names a <template> by id. The SDK reads the template
 // they point at, so that template is SDK-owned wherever it sits.
-const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
+export const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 
 // Containers whose DIRECT <template> child the SDK clones (each does a
 // `:scope > template` lookup at v0.4.38: cart-summary and its
@@ -98,7 +98,7 @@ const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
 // package-toggle).
 // Only the direct child: a vendor template nested deeper inside SDK chrome is
 // never read, so it may use any syntax.
-const TEMPLATE_CONTAINER_ATTRIBUTES = [
+export const TEMPLATE_CONTAINER_ATTRIBUTES = [
   "data-next-cart-summary",
   "data-summary-lines",
   "data-next-discounts",

package/src/sdk-storage-compatibility.mjs

@@ -1,6 +1,7 @@
 // Read-only source evidence. SDK migration names come exclusively from the supplied manifest.
 import { parse as parseJs } from 'acorn';
 import { parse as parseHtml } from 'parse5';
+import { parseDocument, isSeq, isScalar, LineCounter } from 'yaml';
 import { execFileSync } from 'node:child_process';
 import { readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { resolve, relative, dirname, posix, sep } from 'node:path';
@@ -261,6 +262,35 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
   visit(ast, null);
   return findings;
 }
+// Page Kit's campaign_asset filter serves src/<slug>/assets/<path>, <slug> being
+// the campaign folder the template sits in. A layout's {% for script in scripts %}
+// loop loads each page's frontmatter `scripts:` entries through the same filter.
+const CAMPAIGN_ASSET_SRC = /^\{\{-?\s*(?:'([^']*)'|"([^"]*)"|([A-Za-z_]\w*))\s*\|\s*campaign_asset\s*-?\}\}$/;
+function campaignAssetRoot(path) {
+  const match = /^((?:.*\/)?src\/[^/]+)\//.exec(path);
+  return match ? `${match[1]}/assets` : null;
+}
+function loopsOverPageScripts(text, name) {
+  return new RegExp(`\\{%-?\\s*for\\s+${name}\\s+in\\s+(?:page\\.)?scripts\\b`).test(text);
+}
+// Each local-or-remote entry of a page's frontmatter `scripts:` list with the
+// file line it is declared on, or an error naming why the list cannot be read.
+function frontmatterScripts(text) {
+  const block = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!block) return { scripts: [] };
+  const lineCounter = new LineCounter();
+  const document = parseDocument(block[1], { lineCounter });
+  if (document.errors.length) {
+    const { line } = lineCounter.linePos(document.errors[0].pos[0]);
+    return { error: `Frontmatter is not valid YAML (${document.errors[0].code}); review the scripts this page loads.`, line: line + 1 };
+  }
+  const scripts = document.get('scripts', true);
+  if (scripts === undefined || scripts === null || (isScalar(scripts) && scripts.value === null)) return { scripts: [] };
+  if (!isSeq(scripts) || !scripts.items.every(item => isScalar(item) && typeof item.value === 'string'))
+    return { error: 'Frontmatter scripts is not a list of paths; review the scripts this page loads.', line: lineCounter.linePos(scripts.range?.[0] ?? 0).line + 1 };
+  // linePos is 1-based within the YAML block, which starts on the file's line 2.
+  return { scripts: scripts.items.map(item => ({ value: item.value, line: lineCounter.linePos(item.range[0]).line + 1 })) };
+}
 export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVersion, manifestPath, scope, exclude = [] }) {
   version(targetSdkVersion);
   if (!Array.isArray(scope) || !scope.length)
@@ -320,20 +350,50 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
       for (const child of node.childNodes ?? []) findBase(child);
     }
     findBase(document);
+    const assetRoot = campaignAssetRoot(path);
+    const requireSelected = (sourcePath, line) => {
+      if (!selected.includes(sourcePath))
+        unknown(path, 'shared-script-outside-scope', sourcePath, line);
+    };
+    // Page Kit serves campaign_asset paths from the assets folder only; an entry
+    // that normalizes outside it is not a file the page loads from there.
+    const requireAsset = (asset, line) => {
+      const sourcePath = posix.normalize(`${assetRoot}/${asset.split(/[?#]/)[0]}`);
+      if (sourcePath.startsWith(`${assetRoot}/`)) requireSelected(sourcePath, line);
+      else unknown(path, 'shared-script-outside-scope', `${asset} resolves outside ${assetRoot}`, line);
+    };
+    if (assetRoot) {
+      const frontmatter = frontmatterScripts(text);
+      if (frontmatter.error)
+        unknown(path, 'shared-script-outside-scope', frontmatter.error, frontmatter.line);
+      for (const { value, line } of frontmatter.scripts ?? []) {
+        if (/^(?:[a-z]+:)?\/\//i.test(value) || value.startsWith('data:')) continue;
+        requireAsset(value, line);
+      }
+    }
     function html(node) {
       if (node.tagName === 'script') {
         const attrs = Object.fromEntries((node.attrs ?? []).map(a => [a.name, a.value]));
         const type = (attrs.type ?? '').trim().toLowerCase();
         if (!type || ['module', 'text/javascript', 'application/javascript', 'text/ecmascript', 'application/ecmascript'].includes(type)) {
-          if (attrs.src) {
+          const campaignAsset = attrs.src ? CAMPAIGN_ASSET_SRC.exec(attrs.src.trim()) : null;
+          if (campaignAsset) {
+            const line = node.sourceCodeLocation?.startLine ?? 1;
+            const literal = campaignAsset[1] ?? campaignAsset[2];
+            if (assetRoot && literal !== undefined)
+              requireAsset(literal, line);
+            else if (!assetRoot || !loopsOverPageScripts(text, campaignAsset[3]))
+              unknown(path, 'shared-script-outside-scope', attrs.src, line);
+            // A frontmatter scripts loop: each page's own entries are checked above.
+          }
+          else if (attrs.src) {
             if (baseHref !== null && !attrs.src.startsWith('/') && !/^[a-z]+:/i.test(attrs.src)) {
               unknown(path, 'html-base-script-resolution', `Relative script ${attrs.src} resolves against base ${baseHref}; include/review the actual dependency.`, node.sourceCodeLocation?.startLine ?? 1);
             }
             if (!/^(?:[a-z]+:)?\/\//i.test(attrs.src) && !attrs.src.startsWith('data:')) {
               const localSource = attrs.src.split(/[?#]/)[0];
               const sourcePath = posix.normalize(localSource.startsWith('/') ? localSource.slice(1) : posix.join(posix.dirname(path), localSource));
-              if (!selected.includes(sourcePath))
-                unknown(path, 'shared-script-outside-scope', sourcePath, node.sourceCodeLocation?.startLine ?? 1);
+              requireSelected(sourcePath, node.sourceCodeLocation?.startLine ?? 1);
             }
           }
           else if (node.sourceCodeLocation?.startTag) {

package/src/source-prep.mjs

@@ -8,7 +8,7 @@
 // source asset crawl (source_asset.* codes) so the two checks never disagree
 // about the same reference.
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { collectDocumentWrapperNames } from "./adapter-decision-contract.mjs";
 
 export const SOURCE_PREP_DOCUMENT_WRAPPER = "source_html.prep.document_wrapper";
@@ -201,7 +201,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
     const policyNote = wrapperPolicy === "preserve_document_wrappers"
       ? " The adapter contract records wrapper_policy \"preserve_document_wrappers\", so this is reported without blocking."
       : "";
-    return `Mapped source HTML is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
+    return `Mapped source HTML (the converted page-kit page once it exists at page_kit.output_path, else the design) is a full browser document, not page-kit-ready source: ${listed}${more}. Strip <!doctype>, <html>, <head>, and <body> so the campaign layout can wrap the page, or, for a standalone page meant to stay whole, record wrapper_policy "preserve_document_wrappers" as an explicit adapter decision: re-run start or prepare-build with --wrapper-policy preserve_document_wrappers, or set "wrapper_policy" in the source-html manifest.${policyNote} See ${docs}.`;
   }
   if (code === SOURCE_PREP_FRONTMATTER_RESIDUE) {
     const listed = sample.map((page) => {
@@ -220,6 +220,26 @@ function describeFinding(code, pages, { wrapperPolicy }) {
   return `Mapped source HTML still links to source files instead of CampaignSpec routes: ${listed}${more}. Replace internal links and CTA destinations with CampaignSpec-derived routes, usually via campaign_link; source filenames like checkout.html are not built campaign URLs. See ${docs}.`;
 }
 
+// The converted page-kit page for a mapped design (page_kit.output_path under
+// the target repo), when it has been written.
+function convertedPageContent(targetRoot, page) {
+  const outputPath = page?.page_kit?.output_path;
+  if (!isNonEmptyString(targetRoot) || !isNonEmptyString(outputPath)) return null;
+  // output_path is repo-relative. One that is absolute or climbs out of the
+  // target repo is not a converted page of this campaign, so it reads like a
+  // missing one and the design is checked instead.
+  const root = resolve(targetRoot);
+  const fullPath = resolve(root, outputPath);
+  const rel = relative(root, fullPath);
+  if (isAbsolute(outputPath) || rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  if (!safeIsFile(fullPath)) return null;
+  try {
+    return { path: toPosixPath(outputPath), content: readFileSync(fullPath, "utf8") };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Evaluates the page-kit source-preparation expectations for every mapped
  * source page. Deterministic: same files in, same findings out. Unreadable or
@@ -227,7 +247,7 @@ function describeFinding(code, pages, { wrapperPolicy }) {
  *
  * @returns {{ checked_page_count: number, findings: Array<{code, severity, message, docs, pages}> }}
  */
-export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null }) {
+export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolicy = null, targetRoot = null }) {
   const mappedPaths = new Set(
     pages
       .map((page) => (isNonEmptyString(page?.path) ? toPosixPath(page.path) : null))
@@ -247,14 +267,24 @@ export function evaluateSourcePreparation({ sourceRoot, pages = [], wrapperPolic
       continue;
     }
     checked += 1;
-    const pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    let pageFindings = inspectPageContent({ content, sourceRoot, pagePath: page.path, mappedPaths });
+    // Wrappers are stripped when the design is converted into the page-kit
+    // page at page_kit.output_path, the file page-kit builds. Once that page
+    // exists, it is the one checked; the design keeps its wrappers.
+    const converted = convertedPageContent(targetRoot, page);
+    if (converted) {
+      pageFindings = pageFindings.filter((finding) => finding.code !== SOURCE_PREP_DOCUMENT_WRAPPER);
+      const wrappers = collectDocumentWrapperNames(converted.content);
+      if (wrappers.length) pageFindings.push({ code: SOURCE_PREP_DOCUMENT_WRAPPER, wrappers, path: converted.path });
+    }
     for (const finding of pageFindings) {
       if (!byCode.has(finding.code)) byCode.set(finding.code, new Map());
       const pagesForCode = byCode.get(finding.code);
-      if (!pagesForCode.has(page.path)) {
-        pagesForCode.set(page.path, { page_id: page.page_id || null, path: page.path, wrappers: [], hrefs: [], variants: [] });
+      const findingPath = finding.path || page.path;
+      if (!pagesForCode.has(findingPath)) {
+        pagesForCode.set(findingPath, { page_id: page.page_id || null, path: findingPath, wrappers: [], hrefs: [], variants: [] });
       }
-      const entry = pagesForCode.get(page.path);
+      const entry = pagesForCode.get(findingPath);
       if (finding.wrappers) entry.wrappers.push(...finding.wrappers);
       if (finding.hrefs) entry.hrefs.push(...finding.hrefs);
       if (finding.variant) entry.variants.push({ variant: finding.variant, lines: finding.lines || [] });