Wix Headless Replatform

scripts/site-clone.mjs

#!/usr/bin/env node
import { assertPublicHttpUrl } from "./lib/url-safety.mjs";
import path from "node:path";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { readFile, rm } from "node:fs/promises";
import {
  businessNameFromProject,
  docsDir,
  ensureDir,
  parseArgs,
  writeJson,
  writeText,
} from "./lib/common.mjs";
import {
  createFrontendAutomationState,
  renderScopeSummary,
  resolveFrontendContext,
  updateScopeSummaryCheckpoint,
  writeFrontendAutomationState,
} from "./lib/frontend-automation-state.mjs";
import { discover } from "./discover-urls.mjs";
import { ensureBrowserExtractionReady } from "./lib/browser-tooling.mjs";
import { extractPage } from "./extract-page.mjs";
import { extractAssets } from "./extract-assets.mjs";
import { extractInteractions } from "./extract-interactions.mjs";
import { extractSeoForUrl } from "./extract-seo.mjs";
import { extractDesignSystem } from "./extract-design-system.mjs";
import { generateDesignMd } from "./generate-design-md.mjs";
import { generateSceneContract } from "./generate-scene-contract.mjs";
import { generateLayoutBlueprint } from "./generate-layout-blueprint.mjs";
import { generateUiNormalization } from "./generate-ui-normalization.mjs";
import { generateControlStateContract } from "./generate-control-state-contract.mjs";
import { generateVisualAssets } from "./generate-visual-assets.mjs";
import { createWixProject, ensureYarnProjectBoundary, verifyWixRuntimeProject } from "./create-wix-project.mjs";
import { validateProjectFontFaces } from "./lib/font-contract.mjs";
import { visualQa } from "./visual-qa.mjs";
import { buildExtractedHomepage } from "./build-extracted-homepage.mjs";
import { resolveHomePage } from "./resolve-home-page.mjs";
import { assembleExtraction } from "./assemble-extraction.mjs";
import { finalizeExtractionReport } from "./finalize-extraction-report.mjs";

const execFileAsync = promisify(execFile);

async function main() {
  const args = parseArgs();
  const context = await resolveFrontendContext({ args });
  const requestedSourceUrl = context.sourceUrl;
  // The source URL is caller-supplied: refuse loopback, private and internal hosts before touching the network.
  await assertPublicHttpUrl(requestedSourceUrl);
  let sourceUrl = requestedSourceUrl;
  const scope = context.scope;
  const outputDir = context.outputDir;
  const projectName = path.basename(outputDir);
  const docs = docsDir(outputDir);
  const runId = `site-clone-${Date.now().toString(36)}`;
  const automationState = createFrontendAutomationState(context);

  if (scope !== "home" || context.explicitUrls.length) {
    throw new Error("Only the home-page workflow is currently implemented. Remove --urls and use --scope home; additional-page resolution requires a future approved workflow.");
  }

  // Standalone runs must own one runnable project directory. Create it before
  // writing extraction artifacts: the Wix CLI will not scaffold into a folder
  // that already contains docs/site-clone or downloaded assets.
  const shouldProvision = context.mode === "standalone" && scope === "home" && !context.explicitUrls.length;
  let wixProject = null;
  if (shouldProvision) {
    wixProject = await ensureStandaloneWixProject({ sourceUrl, outputDir, projectName, args });
  } else if (context.mode === "migration_phase" && context.frontendPhase === "build") {
    await ensureYarnProjectBoundary(outputDir);
    const runtime = await verifyWixRuntimeProject(outputDir);
    if (!runtime.ok) {
      throw new Error(`Migration phase build requires the existing frontend project to be runnable: ${runtime.summary}`);
    }
    wixProject = { executed: true, reused: true, migrationManaged: true, ...runtime };
  }
  await ensureDir(docs);
  await assertNoLegacyResume(docs, args);
  await prepareCanonicalDocsDir(docs);
  console.log("[site-clone] resolving home page");
  const resolution = await resolveHomePage(requestedSourceUrl);
  if (!resolution.artifact) {
    await writeJson(path.join(docs, "page-resolution.spec.json"), {
      schemaVersion: "0083.1",
      kind: "page-resolution",
      gaps: resolution.gaps,
    });
    const error = new Error(resolution.gaps[0]?.reason || "Home-page resolution failed");
    error.code = "PAGE_RESOLUTION_BLOCKED";
    throw error;
  }
  sourceUrl = resolution.artifact.source.resolvedUrl;
  await writeJson(path.join(docs, "page-resolution.spec.json"), resolution.artifact);
  await writeJson(path.join(docs, "run-manifest.json"), {
    runId,
    sourceUrl,
    outputDir,
    mode: context.mode,
    automationMode: context.automationMode,
    frontendPhase: context.frontendPhase,
    handoffPath: context.handoffPath,
    startedAt: new Date().toISOString(),
  });
  await writeFrontendAutomationState(outputDir, automationState);

  const explicitUrls = context.explicitUrls;
  console.log(`[site-clone] discovery started (${scope}${explicitUrls.length ? `, explicit URLs: ${explicitUrls.length}` : ""})`);
  const discovery = await discover({ sourceUrl, scope, explicitUrls });
  await writeJson(path.join(docs, "discovery.json"), discovery);
  const scopeSummaryPath = path.join(docs, "scope-summary.md");
  await writeText(scopeSummaryPath, renderScopeSummary(context, discovery));
  console.log(`[site-clone] discovery complete: ${discovery.totalDiscovered} page(s), ${discovery.representativePages.length} representative page(s)`);

  if (discovery.requiresConfirmation && !args.yes && !context.autoApprove) {
    updateScopeSummaryCheckpoint(automationState, {
      status: "pending",
      discovery,
      artifactRefs: ["docs/site-clone/discovery.json", "docs/site-clone/scope-summary.md"],
      notes: "Non-homepage scope requires confirmation before extraction/building in manual mode.",
    });
    await writeFrontendAutomationState(outputDir, automationState);
    printConfirmationSummary(discovery, outputDir);
    console.log("");
    console.log("Review the scope above, then rerun with --yes to continue or pass --urls/--scope to adjust.");
    return;
  }
  updateScopeSummaryCheckpoint(automationState, {
    status: "approved",
    discovery,
    artifactRefs: ["docs/site-clone/discovery.json", "docs/site-clone/scope-summary.md"],
    decidedBy: context.autoApprove ? "agent" : discovery.requiresConfirmation ? "user" : "system",
    notes: context.autoApprove
      ? "Migration phase 1-click mode auto-approved the frontend scope summary."
      : discovery.requiresConfirmation
        ? "Scope summary confirmed by explicit --yes continuation."
        : "Scope confirmation was not required for this run.",
  });
  await writeFrontendAutomationState(outputDir, automationState);

  console.log("[site-clone] browser preflight started");
  const browserTooling = await ensureBrowserExtractionReady({ startDir: outputDir });
  console.log("[site-clone] browser preflight complete");
  const extractionWarnings = [];

  const pages = [];
  const pagesDir = path.join(docs, "pages");
  await ensureDir(pagesDir);
  for (const page of discovery.representativePages) {
    console.log(`[site-clone] extracting page ${page.path || page.url}`);
    const extracted = await extractPage(page.url, { outputDir, screenshots: args.screenshots !== "false", browserTooling });
    pages.push(extracted);
    await writeJson(path.join(pagesDir, `${safePageName(page)}.json`), extracted);
  }

  console.log("[site-clone] extracting SEO and assets");
  const seo = await extractSeoForUrl(sourceUrl);
  const assets = await extractAssets(sourceUrl, { outputDir, download: args.download !== "false" });
  await writeJson(path.join(docs, "seo.json"), seo);
  await writeJson(path.join(docs, "assets.json"), assets);
  await writeJson(path.join(docs, "fonts.json"), assets.fonts);

  console.log("[site-clone] extracting interactions");
  const interactionMap = await loadOrExtractInteractions({ sourceUrl, outputDir, browserTooling });
  await writeJson(path.join(docs, "interaction-map.json"), interactionMap);
  const enrichedPages = interactionMap.pages?.length ? interactionMap.pages : pages;
  pages.length = 0;
  pages.push(...enrichedPages);
  for (const page of pages) {
    await writeJson(path.join(pagesDir, `${safePageName(page)}.json`), page);
  }

  const sourceMap = {
    sourceUrl,
    normalizedAt: new Date().toISOString(),
    scope: discovery.scope,
    project: {
      name: projectName,
      outputDir,
      businessName: args["business-name"] || businessNameFromProject(projectName),
    },
    discovery,
    pages,
    assets: assets.assets,
    fonts: {
      families: assets.fonts?.families || [],
      faceCount: assets.fonts?.faces?.length || 0,
      contentScripts: assets.fonts?.contentScripts || [],
    },
    interactions: {
      interactionCount: interactionMap.summary?.interactionCount || 0,
      kinds: interactionMap.summary?.kinds || {},
      targetCount: interactionMap.summary?.targetCount || 0,
      meaningfulCaptureCount: interactionMap.summary?.meaningfulCaptureCount || 0,
    },
    seo,
    tokens: {},
    extractionWarnings,
  };
  await writeJson(path.join(docs, "source-map.json"), sourceMap);

  console.log("[site-clone] extracting design system");
  const designSystem = await extractDesignSystem({
    sourceUrl,
    outputDir,
    extractor: args["design-extractor"],
    browserTooling,
  });
  const tokens = designSystem.tokens;
  sourceMap.tokens = tokens;
  sourceMap.designExtraction = {
    selectedExtractor: designSystem.selectedExtractor,
    actualExtractor: designSystem.actualExtractor || designSystem.extractor,
    fallbackReason: designSystem.fallbackReason,
    attempts: designSystem.attempts || [],
  };
  await writeJson(path.join(docs, "tokens.json"), tokens);
  await writeJson(path.join(docs, "source-map.json"), sourceMap);

  console.log("[site-clone] projecting interaction, visual, and layout observations");
  const sceneContract = await generateSceneContract({ outputDir, pages, interactionMap });
  const controlStateContract = await generateControlStateContract({ outputDir, interactionMap });
  const visualAssets = await generateVisualAssets({ outputDir, pages, assets });
  const layoutBlueprint = await generateLayoutBlueprint({ outputDir, pages, interactionMap, sceneContract });
  const uiNormalization = await generateUiNormalization({ outputDir, pages, interactionMap, sceneContract, layoutBlueprint });
  const designMd = designSystem.designMd?.trim()
    ? designSystem.designMd
    : await generateDesignMd({ outputDir, sourceUrl });
  await writeText(path.join(docs, "design.md"), `${designMd.trim()}\n\n${renderVisualAssetsDesignSummary(visualAssets)}\n\n${renderControlStateDesignSummary(controlStateContract)}\n\n${renderLayoutBlueprintDesignSummary(layoutBlueprint)}\n\n${renderUiNormalizationDesignSummary(uiNormalization)}\n`);
  console.log("[site-clone] assembling and freezing extraction specs");
  const decisionPatches = args["decision-patches"]
    ? JSON.parse(await readFile(path.resolve(String(args["decision-patches"])), "utf8"))
    : [];
  const extraction = await assembleExtraction({
    outputDir,
    requestedUrl: requestedSourceUrl,
    resolvedUrl: sourceUrl,
    canonicalUrl: resolution.artifact.source.canonicalUrl,
    page: pages[0],
    assets,
    seo,
    tokens,
    interactionMap,
    sceneContract,
    layoutBlueprint,
    uiNormalization,
    controlStateContract,
    visualAssets,
    sourceFingerprint: resolution.artifact.source.fingerprint,
    decisionPatches: Array.isArray(decisionPatches) ? decisionPatches : decisionPatches.patches || [],
    pageResolutionArtifact: resolution.artifact,
  });
  await removeLegacyExtractionHandoffs(docs);
  if (context.frontendPhase === "build" && scope === "home") {
    console.log(`[site-clone] building home page from frozen manifest ${extraction.manifest.manifestHash}`);
    await installInteractionRuntime(outputDir);
    await buildExtractedHomepage({ outputDir });
  }

  if (!wixProject && context.mode === "standalone") {
    console.log("[site-clone] preparing Wix project metadata");
    wixProject = await createWixProject({
      sourceUrl,
      outputDir,
      projectName,
      businessName: args["business-name"] || businessNameFromProject(projectName),
      template: args.template,
      execute: Boolean(args["execute-create"]),
    });
  }
  if (wixProject?.executed) {
    const runtime = await verifyWixRuntimeProject(outputDir);
    if (!runtime.ok) throw new Error(`Wix project contract failed: ${runtime.summary}`);
  }

  let qa = null;
  let fontValidation = null;
  if (context.frontendPhase === "build") {
    console.log("[site-clone] running visual QA");
    qa = await visualQa({ outputDir });
    fontValidation = await validateProjectFontFaces({ projectRoot: outputDir, fontManifest: assets.fonts });
    await writeJson(path.join(docs, "qa", "visual-qa.json"), qa);
    await writeJson(path.join(docs, "qa", "font-validation.json"), fontValidation);
    const finalReport = await finalizeExtractionReport({ outputDir });
    console.log(`[site-clone] reconstruction status: ${finalReport.status}`);
  }
  await writeJson(path.join(docs, "run-manifest.json"), {
    runId,
    sourceUrl,
    outputDir,
    scope: discovery.scope,
    mode: context.mode,
    automationMode: context.automationMode,
    frontendPhase: context.frontendPhase,
    handoffPath: context.handoffPath,
    representativePages: discovery.representativePages.map((page) => page.url),
    actualDesignExtractor: designSystem.actualExtractor || designSystem.extractor,
    completedAt: new Date().toISOString(),
  });

  console.log(`Site clone artifacts written to ${docs}`);
  console.log(`Output project: ${outputDir}`);
  if (context.frontendPhase === "plan") {
    console.log("Migration phase plan mode completed: extraction and planning artifacts were refreshed, and build-only project verification/QA were intentionally skipped.");
  } else if (!wixProject?.executed) {
    console.log("Wix project creation command prepared:");
    console.log(wixProject.command);
    console.log("Run with --execute-create when ready to create the Wix Headless project.");
  }
  if (wixProject?.localOutputRename) {
    console.log(`Wix CLI folder name normalized to "${wixProject.wixFolderName}" and should be renamed to "${projectName}" after creation.`);
  }
  if (qa) {
    console.log(`Heuristic QA score: ${qa.score}/100`);
    console.log("After implementation: start the clone, run post-build-gap.mjs with --result-url, review every screenshot pair, then complete the bounded gap-fix loop.");
  }
}

async function ensureStandaloneWixProject({ sourceUrl, outputDir, projectName, args }) {
  const packagePath = path.join(outputDir, "package.json");
  try {
    await readFile(packagePath, "utf8");
    await ensureYarnProjectBoundary(outputDir);
    const existing = await verifyWixRuntimeProject(outputDir);
    if (!existing.ok) throw new Error(`Existing standalone output is not a runnable Wix project: ${existing.summary}`);
    console.log("[site-clone] reusing existing Wix project");
    return { executed: true, reused: true, ...existing };
  } catch (error) {
    if (error?.code !== "ENOENT") throw error;
  }
  console.log("[site-clone] provisioning Wix project before extraction");
  return createWixProject({
    sourceUrl,
    outputDir,
    projectName,
    businessName: args["business-name"] || businessNameFromProject(projectName),
    template: args.template,
    execute: true,
  });
}

async function loadOrExtractInteractions({ sourceUrl, outputDir, browserTooling }) {
  const artifact = path.join(docsDir(outputDir), "interaction-map.json");
  try {
    const existing = JSON.parse(await readFile(artifact, "utf8"));
    if (existing.sourceUrl === sourceUrl && Array.isArray(existing.interactions)) {
      console.log("[site-clone] reusing completed interaction map");
      return existing;
    }
  } catch {
    // No compatible checkpoint; perform a fresh extraction below.
  }
  return extractInteractionsIsolated({ sourceUrl, outputDir, browserTooling });
}

async function extractInteractionsIsolated({ sourceUrl, outputDir, browserTooling }) {
  const script = new URL("./extract-interactions.mjs", import.meta.url);
  try {
    await execFileAsync(process.execPath, [
      script.pathname,
      sourceUrl,
      "--out",
      outputDir,
      "--project-root",
      browserTooling.projectRoot,
    ], { timeout: 240000, maxBuffer: 1024 * 1024 });
  } catch (error) {
    throw new Error(`interaction extraction failed: ${error.stderr || error.message}`);
  }
  const artifact = path.join(docsDir(outputDir), "interaction-map.json");
  try { return JSON.parse(await readFile(artifact, "utf8")); }
  catch { throw new Error("interaction extraction exited without interaction-map.json"); }
}

async function prepareCanonicalDocsDir(docs) {
  const generatedPaths = [
    "pages",
    "components",
    "screenshots",
    "design-md-generator",
    ".design-md-generator-run",
    "design.md",
    "discovery.json",
    "routes.json",
    "repeater-cms.json",
    "repeater-cms.md",
    "source-map.json",
    "seo.json",
    "assets.json",
    "interaction-qa.json",
    "scene-contract.json",
    "control-state-contract.json",
    "control-state-contract.md",
    "visual-assets.json",
    "visual-assets.md",
    "layout-blueprint.json",
    "layout-blueprint.md",
    "ui-normalization.json",
    "ui-normalization.md",
    "fonts.json",
    "font-validation.json",
    "tokens.json",
    "visual-qa.json",
    "scope-summary.md",
    "frontend-automation-state.json",
    "run-manifest.json",
    "page-resolution.spec.json",
    "extraction",
    "build",
    "qa",
    "gap-analysis",
    "final-report.json",
    "final-report.md",
  ];
  for (const relativePath of generatedPaths) {
    await rm(path.join(docs, relativePath), { recursive: true, force: true });
  }
}

async function assertNoLegacyResume(docs, args) {
  try {
    await readFile(path.join(docs, "run-manifest.json"), "utf8");
  } catch (error) {
    if (error?.code === "ENOENT") return;
    throw error;
  }
  try {
    await readFile(path.join(docs, "extraction", "latest.json"), "utf8");
    return;
  } catch (error) {
    if (error?.code !== "ENOENT") throw error;
  }
  if (args["restart-0083"] === true || args["restart-0083"] === "true") return;
  throw new Error("This output contains a headless run from before the extraction-first workflow and cannot be resumed. Rerun with --restart-0083 to discard its generated frontend evidence and restart from home-page resolution plus fresh capture.");
}

async function removeLegacyExtractionHandoffs(docs) {
  const obsolete = [
    "pages",
    "components",
    "source-map.json",
    "seo.json",
    "assets.json",
    "fonts.json",
    "tokens.json",
    "interaction-map.json",
    "scene-contract.json",
    "control-state-contract.json",
    "control-state-contract.md",
    "visual-assets.json",
    "visual-assets.md",
    "layout-blueprint.json",
    "layout-blueprint.md",
    "ui-normalization.json",
    "ui-normalization.md",
    "routes.json",
    "repeater-cms.json",
    "repeater-cms.md",
    "design.md",
    "page-resolution.spec.json",
  ];
  for (const relativePath of obsolete) await rm(path.join(docs, relativePath), { recursive: true, force: true });
}

export async function installInteractionRuntime(outputDir) {
  const source = new URL("./lib/interaction-runtime.mjs", import.meta.url);
  const sourceText = await readFile(source, "utf8");
  const target = path.join(outputDir, "src", "lib", "rp-interactions.mjs");
  let existing = "";
  try {
    existing = await readFile(target, "utf8");
  } catch (error) {
    if (error?.code !== "ENOENT") throw error;
  }
  if (!existing || existing.includes("@generated-source wix-headless-replatform")) {
    await ensureDir(path.dirname(target));
    await writeText(target, sourceText);
  }
  const publicDir = path.join(outputDir, "public", "site-clone");
  await ensureDir(publicDir);
  await writeText(path.join(publicDir, "rp-interactions.mjs"), sourceText);
  await writeText(
    path.join(publicDir, "rp-interactions-bootstrap.mjs"),
    await readFile(new URL("./lib/interaction-bootstrap.mjs", import.meta.url), "utf8"),
  );
  const normalizationCss = await readFile(new URL("./lib/ui-normalization.css", import.meta.url), "utf8");
  await writeText(path.join(publicDir, "rp-ui-normalize.css"), normalizationCss);
  const sourceStyleDir = path.join(outputDir, "src", "styles");
  await ensureDir(sourceStyleDir);
  const sourceStyleTarget = path.join(sourceStyleDir, "rp-ui-normalize.css");
  let existingStyle = "";
  try {
    existingStyle = await readFile(sourceStyleTarget, "utf8");
  } catch (error) {
    if (error?.code !== "ENOENT") throw error;
  }
  if (!existingStyle || existingStyle.includes("@generated-source wix-headless-replatform")) {
    await writeText(sourceStyleTarget, normalizationCss);
  }
}

function printConfirmationSummary(discovery, outputDir) {
  console.log(`Output directory: ${outputDir}`);
  console.log(`Discovered ${discovery.totalDiscovered} same-origin URL(s) for scope "${discovery.scope}".`);
  if (discovery.inScopePages) console.log(`In-scope implementation URL(s): ${discovery.inScopePages.length}`);
  if (discovery.preservedPages) console.log(`Preserved fallback URL(s): ${discovery.preservedPages.length}`);
  for (const [area, count] of Object.entries(discovery.countsByArea)) {
    console.log(`- ${area}: ${count}`);
  }
  const dynamicAreas = ["product", "product-category", "blog-post", "blog-index", "cms-content", "bookings", "events", "pricing"]
    .filter((area) => discovery.countsByArea[area]);
  if (dynamicAreas.length) {
    console.log("");
    console.log(`Dynamic Wix SDK-backed templates: ${dynamicAreas.join(", ")}`);
  }
  if (discovery.excluded.length) {
    console.log("");
    console.log(`Excluded URL records: ${discovery.excluded.length}`);
  }
}

function parseUrlList(value, sourceUrl) {
  if (!value) return [];
  return String(value)
    .split(",")
    .map((item) => new URL(item.trim(), sourceUrl).toString());
}

function safePageName(page) {
  return `${page.area}-${String(page.path || "home").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "") || "home"}`;
}

function renderUiNormalizationDesignSummary(contract) {
  return `## Identity-Preserving UI Normalization\n\nIdentity locks outrank polish. Preserve content, section order/archetype, brand tokens, media, CTA hierarchy, and interaction model. Do not select a new design style.\n\nLoad once: \`<link rel="stylesheet" href="/site-clone/rp-ui-normalize.css">\`\n\nMotion: hover/focus is subtle and non-structural; click/activation may change major geometry only when required by the scene. Captured timing overrides defaults. Use easing and respect \`prefers-reduced-motion\`.\n\nSection recipes:\n${(contract.sections || []).map((section) => `- \`${section.sectionId}\` / \`${section.layout}\`: ${section.recipe.join(" ")}`).join("\n") || "- none"}`;
}

function renderLayoutBlueprintDesignSummary(contract) {
  return `## Section Layout Blueprints\n\nBuild each section independently in this order: canvas, background layers, container, semantic regions, relationships, responsive reflow, then UI normalization. Composition and background-media role are identity locks.\n\n${(contract.pages || []).flatMap((page) => page.sections || []).map((section) => `- \`${section.sectionId}\` / \`${section.composition}\` / \`${section.canvas.widthMode}-${section.canvas.heightMode}\`: ${section.implementation.steps.join(" ")}`).join("\n") || "- none"}`;
}

function renderControlStateDesignSummary(contract) {
  return `## Control State Fidelity\n\nImplement source-observed rest, hover, focus-visible, pressed, activated, current, and disabled deltas on their measured owner. Nested icon motion must not be promoted to the whole control.\n\n${(contract.controls || []).map((control) => `- \`${control.scope}/${control.role}\` ${(control.members || [control.label]).join(", ")}: ${Object.keys(control.states).map((state) => `\`${state}\``).join(", ") || "rest only"}`).join("\n") || "- no representative controls captured"}`;
}

function renderVisualAssetsDesignSummary(contract) {
  return `## Source Visual Assets\n\nLogos are identity locks: use exact source/materialized files, preserve every observed variant and target size, and never recreate a logo as text. Icons follow source asset → source library/sprite → style-matched established library fallback.\n\n${(contract.logos || []).map((logo) => `- \`${logo.id}\`: ${logo.localPath || logo.sourceUrl || logo.useHref || "captured markup"}`).join("\n") || "- BLOCKING: no logo candidate captured; inspect the source before implementing brand chrome."}`;
}

async function writeComponentSpecs({ docs, pages, routes, sceneContract, layoutBlueprint, uiNormalization, controlStateContract, visualAssets }) {
  const dir = path.join(docs, "components");
  await ensureDir(dir);
  for (const page of pages) {
    const relatedRoutes = routes.routes.filter((route) => route.representativeUrls?.includes(page.url));
    const pageScenes = (sceneContract?.scenes || []).filter((scene) => scene.id.startsWith(`${page.area || "page"}-`));
    const pageLayouts = (layoutBlueprint?.pages || []).find((candidate) => candidate.url === page.url)?.sections || [];
    const pageNormalization = (uiNormalization?.sections || []).filter((section) => section.pageUrl === page.url);
    const pageControls = (controlStateContract?.controls || []).filter((control) => control.scope !== "content" || page.url === pages[0]?.url);
    const pageLogos = (visualAssets?.logos || []).filter((asset) => asset.usages.some((usage) => usage.pageUrl === page.url));
    const pageIcons = (visualAssets?.icons || []).filter((asset) => asset.usages.some((usage) => usage.pageUrl === page.url));
    const title = page.title || page.seo?.title || page.url;
    const body = `# ${title}

Source URL: ${page.url}

Area: ${page.area}

Route strategy:

${relatedRoutes.map((route) => `- ${route.kind}: \`${route.targetRoute}\`${route.dataSource ? ` via ${route.dataSource}` : ""}`).join("\n") || "- static or not yet classified"}

## Blocking Interaction Checklist

Do this before visual polish. The page is incomplete until every item passes.

1. Add this exact tag once near the end of the document: \`<script type="module" src="/site-clone/rp-interactions-bootstrap.mjs"></script>\`.
2. Add this exact stylesheet once in the document head: \`<link rel="stylesheet" href="/site-clone/rp-ui-normalize.css">\`.
3. Do not use a raw \`type="module"\` script to import a relative file from \`src/\`; that browser URL will not resolve. The public bootstrap auto-binds marker-complete scenes.
4. Implement the following ${pageScenes.length} core scene(s) and their exact markers:
${pageScenes.map((scene) => `   - \`${scene.id}\` / \`${scene.implementation.primitive}\`: ${(scene.implementation.recipe?.steps || []).join(" ")}`).join("\n") || "   - none"}
5. Use the exact logos/icons in the visual asset inventory. A text recreation of a logo is a blocking failure.
6. Implement the dedicated control states below before generic UI normalization.
7. Implement each section's layout blueprint below before applying UI normalization. Composition, text geometry, and background-media role are identity locks.
8. Implement each identity-preserving UI normalization recipe below. Identity locks outrank polish.
9. Start the clone and run \`node skills/wix-headless-replatform/scripts/verify-interactions.mjs --out <project-dir> --clone-url <local-url> --project-root <host-project-root> --viewports 375,768,1440\`.
10. Fix every failed scene or normalization check, at every viewport. A missing \`interaction-qa.json\` or \`pass: false\` is a blocking failure, even if the static page looks close.

Ignored source infrastructure:
${(page.ignoredSurfaces || []).map((surface) => `- \`${surface.kind}\` / provider \`${surface.provider || "unknown"}\`: ${surface.creationPolicy === "ignore" ? "identify only; do not recreate as page UI" : surface.creationPolicy}`).join("\n") || "- none"}

## Source Visual Assets

Logos must use these exact source/materialized files and recorded usage sizes. Do not recreate them as text. Icons use source-first resolution; a matching established library is fallback-only.

Logos:
${pageLogos.map((asset) => `- \`${asset.id}\`: ${asset.localPath || asset.sourceUrl || asset.useHref || "captured source markup"}; ${asset.usages.filter((usage) => usage.pageUrl === page.url).map((usage) => `${usage.context}/${usage.variant} ${usage.renderedSize?.width || 0}×${usage.renderedSize?.height || 0}`).join(", ")}`).join("\n") || "- BLOCKING: none captured; inspect source chrome before implementation"}

Icons:
${pageIcons.map((asset) => `- \`${asset.id}\`: ${asset.localPath || asset.sourceUrl || asset.useHref || "captured source markup"}; ${asset.usages.filter((usage) => usage.pageUrl === page.url).map((usage) => usage.context).join(", ")}`).join("\n") || "- no standalone icon evidence captured"}

## Dedicated Control States

Implement state deltas on the recorded owner. \`focus-visible\` remains required for accessibility; nested icon motion must remain nested.

${pageControls.map((control) => `- \`${control.scope}/${control.role}\` ${(control.members || [control.label]).join(", ")}: ${Object.keys(control.states).map((state) => `\`${state}\``).join(", ") || "rest only"}; icon motion: ${control.iconMotion.join(", ") || "none"}`).join("\n") || "- no representative controls captured"}

## Section Layout Blueprints

Use the controlled terms and normalized rectangles as the source of truth. Build canvas and ordered background layers first. A background media layer is not a peer column.

${pageLayouts.map((section) => `### ${section.sectionId}: ${section.composition}\n\n- Canvas: \`${section.canvas.widthMode}/${section.canvas.heightMode}\`${section.canvas.pinned ? "; pinned" : ""}\n- Background: \`${section.background.kind}\` — ${section.background.layers.map((layer) => `\`${layer.role}:${layer.kind}\``).join(" -> ") || "none"}\n- Container: \`${section.container.widthMode}\`\n- Relationships: ${section.relationships.map((item) => `\`${item}\``).join(", ") || "none measured"}\n- Forbidden conversions: ${section.identityLocks.forbiddenConversions.map((item) => `\`${item}\``).join(", ") || "none"}\n\nRegions:\n${section.regions.map((region) => `- \`${region.role}\` / \`${region.placement}\` / \`${JSON.stringify(region.normalizedRect)}\`${region.textGeometry ? ` / text geometry \`${JSON.stringify({ ...region.textGeometry, responsive: region.responsiveTextGeometry || [] })}\`` : ""}${region.text ? `: ${region.text}` : ""}`).join("\n") || "- no measured regions; follow scene evidence and source screenshot"}\n\nBuild order:\n${section.implementation.steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}`).join("\n\n") || "_No section layout blueprint captured._"}

## Identity-Preserving UI Normalization

Allowed: spacing/alignment cleanup, consistent repeated-item geometry, responsive reflow within the same archetype, subtle hover/focus feedback, eased state transitions, accessibility, and reduced motion.

Forbidden: new visual style/palette/type, section reordering, archetype conversion, new CTA hierarchy, replaced media/interaction intent, or hiding source content to simplify layout.

${pageNormalization.map((section) => `### ${section.sectionId}: ${section.kind}/${section.variant}\n\nMarkers: \`${section.markerContract.section}\`; \`${section.markerContract.layout}\`\n\nRecipe:\n${section.recipe.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n\nRules:\n${section.rules.map((rule) => `- ${rule.id}: ${rule.requirement}`).join("\n")}\n\nAssertions:\n${section.assertions.map((assertion) => `- \`${assertion.kind}\`: ${JSON.stringify(assertion)}`).join("\n")}`).join("\n\n") || "_No section normalization contract captured._"}

## Sections

${(page.sections || []).map((section, index) => `### ${index + 1}. ${section.heading || section.tag || "Section"}\n\n${section.text || "_No text captured._"}`).join("\n\n") || "_No sections captured._"}

## Repeaters

${(page.repeaters || []).map((repeater, index) => `### ${index + 1}. ${repeater.label || repeater.kind || "Repeater"}\n\n- kind: \`${repeater.kind}\`\n- source: \`${repeater.source}\`\n- items: ${repeater.itemCount || repeater.items?.length || 0}\n- schema: headings=${Boolean(repeater.schema?.hasHeading)}, paragraphs=${Boolean(repeater.schema?.hasParagraphs)}, images=${Boolean(repeater.schema?.hasImages)}, maxImagesPerItem=${repeater.schema?.maxImagesPerItem ?? 0}\n\n${(repeater.items || []).slice(0, 12).map((item, itemIndex) => `#### ${itemIndex + 1}. ${item.heading || "Item"}\n\n${(item.paragraphs || []).join("\n\n") || "_No text captured._"}\n\nImages:\n${(item.images || []).map((image) => `- ${image.src}`).join("\n") || "_No images captured._"}`).join("\n\n")}`).join("\n\n") || "_No repeaters captured._"}

## Repeater Diagnostics

${page.repeaterDiagnostics ? `- source: \`${page.repeaterDiagnostics.source || "unknown"}\`\n- accessibility snapshot available: ${Boolean(page.repeaterDiagnostics.accessibilitySnapshotAvailable)}\n- signal count: ${page.repeaterDiagnostics.signalCount ?? 0}\n- accepted repeaters: ${page.repeaterDiagnostics.acceptedRepeaterCount ?? 0}\n${(page.repeaterDiagnostics.warnings || []).length ? `- warnings:\n${page.repeaterDiagnostics.warnings.map((warning) => `  - ${warning}`).join("\n")}` : "- warnings: none"}` : "_No repeater diagnostics captured._"}

## Interactions

${page.interactionDiscovery ? `${(page.interactionDiscovery.requiredBehaviors || []).length ? `Required behaviors:\n${page.interactionDiscovery.requiredBehaviors.map((behavior) => `- \`${behavior}\``).join("\n")}` : "Required behaviors: none"}\n\n${(page.interactionDiscovery.sectionInteractions || []).filter((section) => section.interactions?.length).map((section) => `### ${section.sectionId}\n\n${section.interactions.map((interaction) => `- ${interaction.kind} / ${interaction.importance} / ${interaction.trigger?.type || interaction.trigger}${interaction.textChanged ? " / text-changes" : ""}`).join("\n")}`).join("\n\n") || "_No section interactions captured._"}` : "_No interaction discovery captured._"}

## Scene Implementation Contract

${pageScenes.map((scene) => `### ${scene.sectionId}: ${scene.implementation.primitive || scene.implementation.model}\n\nRuntime adapter: \`${scene.implementation.runtimeAdapter || "custom"}\`; preferred startup: \`${scene.implementation.runtimeModule || "/site-clone/rp-interactions-bootstrap.mjs"}\`\n\nScene marker: \`data-rp-scene="${scene.id}"\`\n\nMarkers:\n${Object.entries(scene.implementation.markerContract || {}).map(([role, marker]) => `- ${role}: \`${marker}\``).join("\n") || "- none"}\n\nRecipe:\n${(scene.implementation.recipe?.steps || []).map((step, index) => `${index + 1}. ${step}`).join("\n") || "- custom"}\n\nAssertions:\n${(scene.implementation.assertions || []).map((assertion) => `- \`${assertion.kind}\`: ${JSON.stringify(assertion)}`).join("\n") || "- none"}\n\nRequirements:\n${scene.implementation.requirements.map((requirement) => `- ${requirement}`).join("\n")}\n\nAcceptance:\n${scene.implementation.acceptance.map((criterion) => `- ${criterion}`).join("\n")}\n\nEvidence:\n${scene.states.map((state) => `- ${state.kind}: ${state.screenshot || "state data in scene-contract.json"}`).join("\n")}\n${scene.manualContentInventory ? "\n- Manual content inventory required: this interactive collection was not captured as a structured repeater; preserve all source items before coding.\n" : ""}`).join("\n\n") || "_No stateful scene contract captured._"}

## Media

${(page.interactionDiscovery?.media || []).map((media) => `- ${media.role} ${media.provider || media.tag}: ${media.src || "deferred source"} (autoplay: ${Boolean(media.playback?.autoplay)}, loop: ${Boolean(media.playback?.loop)}, muted: ${Boolean(media.playback?.muted)})`).join("\n") || "_No embedded media captured._"}

## Footer

${page.footer?.legalText || "_No structured footer content captured._"}

## Links

${(page.links || []).slice(0, 80).map((link) => `- [${link.text || link.url}](${link.url})`).join("\n") || "_No links captured._"}
`;
    await writeText(path.join(dir, `${safePageName(page)}.spec.md`), body);
  }
}

if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((error) => {
    console.error(error.stack || error.message);
    process.exit(1);
  });
}