@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-headless-replatform/scripts/site-clone.mjs

@@ -1,658 +0,0 @@
-#!/usr/bin/env node
-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;
-  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: process.cwd() });
-  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);
-  });
-}