@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-headless-replatform/scripts/generate-scene-contract.mjs

@@ -1,288 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, parseArgs, readJson, resolveOutputDir, writeJson } from "./lib/common.mjs";
-
-async function main() {
-  const args = parseArgs();
-  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
-  const contract = await generateSceneContract({ outputDir });
-  if (args.json) process.stdout.write(`${JSON.stringify(contract, null, 2)}\n`);
-}
-
-export async function generateSceneContract({ outputDir, pages: suppliedPages, interactionMap: suppliedInteractionMap } = {}) {
-  const docs = docsDir(outputDir);
-  const interactionMap = suppliedInteractionMap || await readJson(path.join(docs, "interaction-map.json"));
-  let sourceMap = null;
-  if (!suppliedPages) {
-    try {
-      sourceMap = await readJson(path.join(docs, "source-map.json"));
-    } catch {
-      // Standalone interaction extraction embeds enriched pages in interaction-map.json.
-    }
-  }
-  const pages = suppliedPages || sourceMap?.pages || interactionMap.pages || [];
-  const interactions = interactionMap.interactions || [];
-  const media = interactionMap.structural?.media || [];
-  const scenes = pages.flatMap((page) => (page.sections || []).map((section) => buildScene({ page, section, interactions, media }))).filter(Boolean);
-  const contract = {
-    schemaVersion: 3,
-    generatedAt: new Date().toISOString(),
-    sourceUrl: interactionMap.sourceUrl || pages[0]?.url || "",
-    scenes,
-  };
-  await writeJson(path.join(docs, "scene-contract.json"), contract);
-  return contract;
-}
-
-export function buildScene({ page, section, interactions, media }) {
-  const sectionInteractions = page.interactionDiscovery?.sectionInteractions?.find((entry) => entry.sectionId === section.id)?.interactions || [];
-  const kinds = new Set(sectionInteractions.map((item) => item.kind));
-  const classText = `${section.kind || ""} ${section.className || ""} ${(section.domRef?.classTokens || []).join(" ")} ${section.heading || ""}`.toLowerCase();
-  const isHero = section.kind === "hero" || /hero/.test(classText) || section === page.sections?.[0];
-  if (isHero && media.some((item) => item.role === "background")) kinds.add("embedded-media");
-  if (/carousel|slider|rail|gallery/.test(classText)) kinds.add("carousel");
-  if (/scroll|scene|sticky|pinned/.test(classText)) {
-    if (interactions.some((item) => item.kind === "scroll-state")) kinds.add("scroll-state");
-    if (interactions.some((item) => item.kind === "tabs")) kinds.add("tabs");
-  }
-  if (!kinds.size) return null;
-
-  const sceneInteractions = interactions.filter((item) =>
-    item.sectionIds?.includes(section.id) || sectionInteractions.some((summary) => interactionMatchesSummary(item, summary))
-  );
-  const sceneMedia = media.filter((item) => {
-    const tokenText = `${item.domRef?.id || ""} ${(item.domRef?.classTokens || []).join(" ")} ${(item.domRef?.parentClassTokens || []).join(" ")} ${(item.domRef?.sectionClassTokens || []).join(" ")}`.toLowerCase();
-    if (isHero) return item.id === media.find((candidate) => candidate.role === "background")?.id;
-    if (kinds.has("scroll-state")) return item.role === "background" && /scroll|scene|sticky|pin|embed/.test(tokenText);
-    return false;
-  });
-  const activeKinds = Array.from(kinds);
-  const primitive = modelFor(activeKinds);
-  const requirements = [];
-  if (sceneMedia.some((item) => item.src)) requirements.push("Render each listed source-backed media surface with the recorded playback flags and scene role.");
-  if (sceneMedia.some((item) => item.fallback?.policy === "fallback-only")) requirements.push("Treat recorded posters/backgrounds as loading, blocked-media, or error fallbacks only; do not visibly blend them behind active media.");
-  if (sceneMedia.some((item) => !item.src)) requirements.push("Recreate the recorded runtime visual surface and its scene behavior; do not replace it with unrelated static imagery.");
-  if (kinds.has("carousel")) requirements.push("Render a finite-width data-rp-viewport that clips or scrolls a wider data-rp-track, preserve the captured card geometry, separation mechanism, and exact initial active state, then manage the captured active-card state on click plus every captured hover state.");
-  if (kinds.has("scroll-state")) requirements.push("Implement both entry progress and internal scroll progress: preserve media framing/sideways expansion through the captured entry and pinned phases, while applying transforms only to the measured motion owner and keeping static copy outside the visual scale scope.");
-  if (kinds.has("tabs")) requirements.push("Implement visible labels as buttons and switch the captured content state without replacing the scene background.");
-  const acceptance = [];
-  if (sceneMedia.some((item) => item.src)) acceptance.push("The implementation references the exact source URLs and preserves applicable playback flags.");
-  if (sceneMedia.some((item) => item.fallback?.policy === "fallback-only")) acceptance.push("No full-cover poster or image remains visibly composited with the active video/iframe.");
-  if (sceneMedia.some((item) => !item.src)) acceptance.push("The implementation preserves the runtime surface's visual role and recorded state changes.");
-  if (kinds.has("carousel")) acceptance.push("The viewport is narrower than the content track, and clicking a card changes its active/expanded state rather than only scrolling.");
-  if (kinds.has("scroll-state")) acceptance.push("Each captured scroll phase produces the corresponding distinct media/copy geometry; add a midpoint phase if source evidence has only endpoints.");
-  if (kinds.has("tabs")) acceptance.push("Each visible tab changes the text/content state while the section remains a single scene.");
-  return {
-    id: `${safeId(page)}-${section.id}`,
-    sectionId: section.id,
-    heading: section.heading || section.tag || "Untitled scene",
-    sourceScreenshot: screenshotFor(section, page),
-    interactionIds: sceneInteractions.map((item) => item.id),
-    media: sceneMedia,
-    states: sceneInteractions.map(sceneStateFor),
-    implementation: {
-      model: primitive,
-      primitive,
-      runtimeAdapter: runtimeAdapterFor(primitive),
-      runtimeModule: "/site-clone/rp-interactions-bootstrap.mjs",
-      bootstrap: "<script type=\"module\" src=\"/site-clone/rp-interactions-bootstrap.mjs\"></script>",
-      markerContract: markerContractFor(primitive, sceneInteractions),
-      initialState: initialStateFor(primitive, sceneInteractions),
-      assertions: assertionsFor({ primitive, interactions: sceneInteractions, media: sceneMedia }),
-      recipe: recipeFor(primitive),
-      requirements,
-      acceptance,
-    },
-    manualContentInventory: kinds.has("carousel") && !(page.repeaters || []).length,
-  };
-}
-
-function sceneStateFor(item) {
-  return {
-    id: item.id,
-    kind: item.kind,
-    trigger: item.trigger,
-    importance: item.importance,
-    interactionMapRef: `interaction-map.json#${item.id}`,
-    states: item.states,
-    ...(item.scope ? { scope: item.scope } : {}),
-    ...(item.timeline ? {
-      timelineSummary: {
-        sampledAtMs: item.timeline.sampledAtMs,
-        observedSettleMs: item.timeline.observedSettleMs,
-        changedNodeCount: item.timeline.changedNodeCount,
-        changedNodes: (item.timeline.changes || []).slice(0, 16).map((change) => ({
-          path: change.path,
-          role: change.role,
-          changedProperties: change.changedProperties,
-        })),
-        animations: item.timeline.animations || [],
-      },
-    } : {}),
-    ...(item.invariants ? { invariants: item.invariants } : {}),
-    screenshot: item.evidence?.screenshot || null,
-  };
-}
-
-function interactionMatchesSummary(interaction, summary) {
-  if (summary.id) return summary.id === interaction.id;
-  const interactionTrigger = typeof interaction.trigger === "string" ? interaction.trigger : interaction.trigger?.type;
-  const summaryTrigger = typeof summary.trigger === "string" ? summary.trigger : summary.trigger?.type;
-  return interaction.kind === summary.kind && interaction.label === summary.label && interactionTrigger === summaryTrigger;
-}
-
-function markerContractFor(primitive, interactions = []) {
-  const base = { scene: "data-rp-scene", initialized: "data-rp-initialized" };
-  if (primitive === "active-card-rail") {
-    const mode = interactions.find((item) => item.kind === "carousel")?.invariants?.initialState || "single-active";
-    return { ...base, initialState: `data-rp-initial-state=\"${mode}\"`, viewport: "data-rp-viewport", track: "data-rp-track", item: "data-rp-item", hoverTarget: "data-rp-hover-target", activate: "data-rp-activate", control: "data-rp-direction", active: "data-rp-active=true" };
-  }
-  if (primitive === "content-switcher") {
-    return { ...base, item: "data-rp-item", activate: "data-rp-activate", active: "data-rp-active=true", panel: "data-rp-panel", state: "data-rp-state" };
-  }
-  if (primitive === "scroll-scene") {
-    return { ...base, phase: "data-rp-phase", visual: "data-rp-visual", content: "data-rp-content", curtain: "data-rp-curtain", panel: "data-rp-panel", item: "data-rp-item", activate: "data-rp-activate", active: "data-rp-active=true", state: "data-rp-state" };
-  }
-  return base;
-}
-
-function initialStateFor(primitive, interactions) {
-  if (primitive !== "active-card-rail") return null;
-  const invariants = interactions.find((item) => item.kind === "carousel")?.invariants || {};
-  return {
-    mode: invariants.initialState || "single-active",
-    activeIndexes: invariants.initialActiveIndexes || [],
-  };
-}
-
-function runtimeAdapterFor(primitive) {
-  if (primitive === "active-card-rail") return "bindActiveItemRail";
-  if (primitive === "content-switcher") return "bindContentSwitcher";
-  if (primitive === "scroll-scene") return "bindScrollScene + bindContentSwitcher";
-  return null;
-}
-
-function assertionsFor({ primitive, interactions, media }) {
-  const assertions = [];
-  if (primitive === "active-card-rail") {
-    const observed = interactions.find((item) => item.kind === "carousel")?.invariants || {};
-    assertions.push(
-      { kind: "scene-present" },
-      { kind: "runtime-initialized", primitive: "active-card-rail" },
-      { kind: "minimum-item-count", value: Math.max(3, Number(observed.itemCount) || 3) },
-      { kind: "horizontal-overflow", minimumRatio: roundTolerance(observed.horizontalOverflowRatio, 0.8, 1.05) },
-      { kind: "initial-active-item-count", value: Number(observed.initialActiveCount) || 0 },
-      { kind: "single-active-item", value: 1 },
-      { kind: "activation-changes-state" },
-    );
-    if (Number(observed.expandedWidthRatio) > 1.1) {
-      assertions.push({ kind: "active-item-width-ratio", minimumRatio: roundTolerance(observed.expandedWidthRatio, 0.8, 1.15) });
-    }
-    if (Number(observed.observedSettleMs) > 0) {
-      assertions.push({ kind: "transition-settles", maximumMs: Math.ceil(Number(observed.observedSettleMs) * 1.5 + 100) });
-    }
-    if (observed.separation) assertions.push({ kind: "item-separation", observed: observed.separation });
-    if (interactions.some((item) => (typeof item.trigger === "string" ? item.trigger : item.trigger?.type) === "hover")) {
-      assertions.push({ kind: "hover-changes-visual-state" });
-    }
-  }
-  if (primitive === "content-switcher" || primitive === "scroll-scene" && interactions.some((item) => item.kind === "tabs")) {
-    assertions.push({ kind: "runtime-initialized", primitive: "content-switcher" });
-    assertions.push({ kind: "activation-changes-content" }, { kind: "single-active-item", value: 1 });
-  }
-  if (primitive === "scroll-scene") {
-    assertions.push({ kind: "runtime-initialized", primitive: "scroll-scene" });
-    assertions.push({ kind: "scroll-produces-distinct-phases", minimumPhaseCount: 2 });
-    const scrollInteraction = interactions.find((item) => item.kind === "scroll-state") || {};
-    const phases = scrollInteraction.states || [];
-    if (JSON.stringify(phases).includes('"position":"fixed"')) assertions.push({ kind: "visual-pins-during-scroll" });
-    const expansion = scrollInteraction.invariants?.visualExpansion;
-    const expansionRatio = Math.max(Number(expansion?.score) || 1, Number(expansion?.widthRatio) || 1, Number(expansion?.transformScaleRatio) || 1);
-    if (expansionRatio > 1.1) {
-      assertions.push({
-        kind: "scroll-visual-expansion",
-        minimumRatio: rangeRatioTolerance(expansionRatio, 0.8, 1.05),
-      });
-    }
-    const contentMotion = scrollInteraction.invariants?.motionOwnership?.content;
-    if (contentMotion && contentMotion.scales === false) {
-      assertions.push({ kind: "scroll-content-scale-bound", maximumRatio: Number(contentMotion.maximumAllowedScaleRatio) || 1.03 });
-    }
-  }
-  for (const item of media.filter((entry) => entry.src)) {
-    assertions.push({ kind: "media-source-present", source: item.src, playback: item.playback || {} });
-    if (item.fallback?.policy === "fallback-only") assertions.push({ kind: "exclusive-media-layer", fallbackSource: item.fallback.src });
-  }
-  return assertions;
-}
-
-function recipeFor(primitive) {
-  const common = {
-    bootstrap: "Add exactly once near the end of the document: <script type=\"module\" src=\"/site-clone/rp-interactions-bootstrap.mjs\"></script>",
-    warning: "A raw browser script must not import a relative module from src/. Use the public bootstrap above, or use the framework's compiled source import without type=module.",
-  };
-  if (primitive === "active-card-rail") return {
-    ...common,
-    steps: [
-      "Put data-rp-viewport on a finite-width overflow-x:auto or overflow:hidden element.",
-      "Put data-rp-track on its wider max-content flex/grid row; never put overflow on a max-content track.",
-      "Put data-rp-item on every card and data-rp-activate on the card activation control.",
-      "Set data-rp-initial-state to the captured invariant. Use all-collapsed when the source has no active item; never pre-open a card for visual variety.",
-      "Reproduce the recorded separation mechanism (track gap, margins, divider, or inner inset) rather than guessing a generic gap.",
-      "Mark the element with the source hover treatment as data-rp-hover-target and reproduce that treatment with :hover/:focus-visible CSS.",
-      "Style data-rp-active=true to reproduce the observed expanded/collapsed ratio; keep active links above any activation hit target.",
-    ],
-  };
-  if (primitive === "scroll-scene") return {
-    ...common,
-    steps: [
-      "Give the scene enough scroll height and mark only the measured pinned/scaled wrapper with data-rp-visual.",
-      "Mark independently positioned copy with data-rp-content. Do not nest it inside a scaling visual wrapper unless the source evidence explicitly records content scaling.",
-      "Use --rp-entry-progress for the approach expansion and --rp-scroll-progress for pinned/release phases.",
-      "When the source uses side curtains/masks, mark both with data-rp-curtain and reduce their widths as entry progress increases.",
-      "If tabs exist, give controls and panels matching data-rp-state values.",
-      "Do not render a fallback poster at the same time as an opaque active video/iframe.",
-    ],
-  };
-  if (primitive === "content-switcher") return {
-    ...common,
-    steps: [
-      "Give each visible control data-rp-item, data-rp-activate, and a unique data-rp-state.",
-      "Give its content panel the matching data-rp-panel and data-rp-state.",
-    ],
-  };
-  return common;
-}
-
-function roundTolerance(value, factor, floor) {
-  const numeric = Number(value) || 0;
-  return Math.round(Math.max(floor, numeric * factor) * 1000) / 1000;
-}
-
-function rangeRatioTolerance(value, factor, floor) {
-  const numeric = Math.max(1, Number(value) || 1);
-  return Math.round(Math.max(floor, 1 + (numeric - 1) * factor) * 1000) / 1000;
-}
-
-function modelFor(kinds) {
-  if (kinds.includes("scroll-state")) return "scroll-scene";
-  if (kinds.includes("carousel")) return "active-card-rail";
-  if (kinds.includes("tabs")) return "content-switcher";
-  return "media-scene";
-}
-
-function screenshotFor(section, page) {
-  if (section.kind === "hero") return page.screenshots?.desktop || null;
-  return page.screenshots?.desktop || page.screenshots?.tablet || null;
-}
-
-function safeId(page) {
-  return `${page.area || "page"}-${String(page.path || "home").replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "") || "home"}`;
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch((error) => {
-    console.error(error.stack || error.message);
-    process.exit(1);
-  });
-}

package/skills/wix-headless-replatform/scripts/generate-ui-normalization.mjs

@@ -1,266 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { docsDir, parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
-
-async function main() {
-  const args = parseArgs();
-  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
-  const contract = await generateUiNormalization({ outputDir });
-  if (args.json) process.stdout.write(`${JSON.stringify(contract, null, 2)}\n`);
-}
-
-export async function generateUiNormalization({ outputDir, pages: suppliedPages, interactionMap: suppliedInteractionMap, sceneContract: suppliedSceneContract, layoutBlueprint: suppliedLayoutBlueprint } = {}) {
-  const docs = docsDir(outputDir);
-  const [sourceMap, interactionMap, sceneContract, layoutBlueprint] = await Promise.all([
-    suppliedPages ? null : readJson(path.join(docs, "source-map.json")),
-    suppliedInteractionMap || readJson(path.join(docs, "interaction-map.json")),
-    suppliedSceneContract || readJson(path.join(docs, "scene-contract.json")),
-    suppliedLayoutBlueprint || readJson(path.join(docs, "layout-blueprint.json")).catch(() => null),
-  ]);
-  const pages = suppliedPages || sourceMap?.pages || interactionMap.pages || [];
-  const sections = pages.flatMap((page) => (page.sections || []).map((section) => buildSectionNormalization({
-    page,
-    section,
-    interactionMap,
-    sceneContract,
-    layoutBlueprint,
-  })));
-  const contract = {
-    schemaVersion: 1,
-    generatedAt: new Date().toISOString(),
-    sourceUrl: interactionMap.sourceUrl || pages[0]?.url || "",
-    policy: identityPolicy(),
-    motionDefaults: motionDefaults(),
-    globalRules: globalRules(),
-    globalAssertions: [
-      { kind: "no-page-horizontal-overflow", maximumPixels: 2 },
-      { kind: "reduced-motion-available" },
-    ],
-    sections,
-  };
-  await writeJson(path.join(docs, "ui-normalization.json"), contract);
-  await writeText(path.join(docs, "ui-normalization.md"), renderNormalizationMarkdown(contract));
-  return contract;
-}
-
-export function buildSectionNormalization({ page, section, interactionMap, sceneContract, layoutBlueprint }) {
-  const scene = (sceneContract.scenes || []).find((candidate) => candidate.sectionId === section.id && candidate.id.startsWith(`${page.area || "page"}-`));
-  const blueprint = (layoutBlueprint?.pages || []).find((candidate) => candidate.url === page.url)?.sections?.find((candidate) => candidate.sectionId === section.id);
-  const interactions = (interactionMap.interactions || []).filter((interaction) =>
-    scene?.interactionIds?.includes(interaction.id) || interaction.sectionIds?.includes(section.id)
-  );
-  const layout = layoutFor(section, scene, page, blueprint);
-  const rules = baseSectionRules(section);
-  const assertions = [{ kind: "section-present" }];
-  const recipe = [
-    `Add data-rp-section="${section.id}" to the section root and data-rp-layout="${layout}".`,
-    "Preserve the extracted content, media, brand tokens, section order, and interaction primitive before applying polish.",
-  ];
-  const evidence = {};
-
-  if (layout === "horizontal-card-rail" || layout === "card-grid") {
-    const carousel = interactions.find((item) => item.kind === "carousel");
-    const heightEvidence = repeatedItemHeightEvidence(carousel);
-    evidence.repeatedItems = heightEvidence;
-    rules.push(
-      rule("stable-card-regions", "Reserve consistent media, body, and action regions so content length does not make peers look accidental."),
-      rule("aligned-card-actions", "Align equivalent card actions to the same block edge when their semantic role is shared."),
-      rule("subtle-hover", "Use hover/focus for subtle non-structural feedback; do not reflow peer cards."),
-    );
-    recipe.push(
-      "Mark repeated cards data-rp-item, their media data-rp-media, body data-rp-body, and equivalent CTA data-rp-action.",
-      "Use data-rp-motion=micro for hover/focus treatment and data-rp-motion=state for click/activation geometry.",
-    );
-    if (heightEvidence.sourceEqualHeight) {
-      rules.push(rule("equal-repeated-item-height", `Keep all peer cards at one block size. Source spread is ${heightEvidence.spreadRatio}; active state changes inline size, not height.`));
-      assertions.push(
-        { kind: "repeated-item-height-spread", maximumRatio: 0.03 },
-        { kind: "activation-preserves-item-height", maximumRatio: 0.03 },
-      );
-      recipe.push(`Set data-rp-equal-height="true" and --rp-item-block-size:${heightEvidence.medianHeight}px on the rail/grid root.`);
-    }
-    if (triggerType(carousel) === "click") {
-      assertions.push({ kind: "hover-preserves-item-layout", maximumInlineRatio: 0.05, maximumBlockRatio: 0.03 });
-    }
-    assertions.push({ kind: "eased-motion-present" });
-    if (layout === "horizontal-card-rail") {
-      rules.push(rule("local-horizontal-overflow", "Keep intentional overflow inside the rail viewport; the document itself must not overflow horizontally."));
-    }
-  }
-
-  if (scene?.implementation?.primitive === "scroll-scene") {
-    rules.push(
-      rule("stable-scroll-composition", "Keep media and copy in the extracted scroll relationship; polish spacing without converting the scene to an unrelated static layout."),
-      rule("stable-tab-anchor", "Keep tab controls anchored while panel content changes; transition opacity/transform rather than causing abrupt horizontal movement."),
-    );
-    recipe.push("Use the scroll-scene markers and progress variables first; normalize text measure, control spacing, and panel transitions inside that composition.");
-  }
-
-  if (blueprint) {
-    recipe.unshift(...blueprint.implementation.steps.map((step) => `Layout blueprint: ${step}`));
-    rules.unshift(rule("preserve-blueprint-composition", `Keep the blueprint's \`${blueprint.composition}\` composition, ordered background layers, and declared region relationships.`));
-    evidence.layoutBlueprint = {
-      composition: blueprint.composition,
-      backgroundKind: blueprint.background.kind,
-      relationships: blueprint.relationships,
-      confidence: blueprint.evidence.confidence,
-    };
-  }
-
-  if (section.kind === "hero") {
-    rules.push(rule("hero-identity-lock", "Preserve the hero media, headline hierarchy, copy anchor, and primary viewport footprint."));
-  }
-  if (section.capabilities?.hasCta) {
-    rules.push(rule("clear-action-affordance", "Give equivalent actions consistent size, focus treatment, and pointer affordance without inventing a new CTA hierarchy."));
-  }
-
-  const stateTimings = interactions.map((item) => Number(item.timeline?.observedSettleMs)).filter((value) => value > 0);
-  if (stateTimings.length) evidence.observedSettleMs = Math.max(...stateTimings);
-  return {
-    pageUrl: page.url,
-    sectionId: section.id,
-    kind: section.kind || "section",
-    variant: section.variant || "generic",
-    layout,
-    markerContract: {
-      section: `data-rp-section="${section.id}"`,
-      layout: `data-rp-layout="${layout}"`,
-      item: "data-rp-item",
-      media: "data-rp-media",
-      body: "data-rp-body",
-      action: "data-rp-action",
-      motion: "data-rp-motion",
-    },
-    identityLocks: sectionIdentityLocks(section, scene, layout, blueprint),
-    evidence,
-    rules,
-    assertions,
-    recipe,
-  };
-}
-
-function identityPolicy() {
-  return {
-    priority: ["content", "section-order", "section-archetype", "brand-tokens", "media", "interaction-model"],
-    allowedChanges: [
-      "spacing and alignment cleanup",
-      "consistent repeated-item geometry",
-      "responsive reflow inside the same archetype",
-      "subtle hover/focus feedback",
-      "eased state transitions",
-      "accessibility and reduced-motion behavior",
-    ],
-    forbiddenChanges: [
-      "new visual style, palette, or font pairing",
-      "section reordering or conversion to a different archetype",
-      "new content, CTA hierarchy, or conversion pattern",
-      "replacement of distinctive media or interaction intent",
-      "hiding source content merely to make geometry easier",
-    ],
-  };
-}
-
-function motionDefaults() {
-  return {
-    micro: {
-      durationMs: [140, 240],
-      easing: "cubic-bezier(0.2, 0, 0, 1)",
-      allowed: ["color", "background-color", "border-color", "box-shadow", "opacity", "transform"],
-      transformBudget: { scale: [0.98, 1.03], translatePx: 8, rotateDeg: 2 },
-      mustNot: ["reflow siblings", "hide required content", "activate a major state on touch-only devices"],
-    },
-    state: {
-      defaultDurationMs: [240, 600],
-      easing: "cubic-bezier(0.2, 0, 0, 1)",
-      mayChangeLayoutWhenRequiredByInteraction: true,
-      capturedTimelineOverridesDefault: true,
-    },
-    reducedMotion: "Remove non-essential interpolation while preserving immediate final state and focus visibility.",
-  };
-}
-
-function globalRules() {
-  return [
-    rule("identity-before-polish", "Do not apply a best practice that changes an identity lock."),
-    rule("content-reflow", "Essential text reflows without clipping at narrow widths, zoom, or text scaling."),
-    rule("focus-equivalence", "Every pointer interaction has an operable keyboard path and visible focus treatment."),
-    rule("intentional-overflow", "Only bounded carousels/rails may overflow horizontally; the page may not."),
-    rule("interruptible-motion", "Rapid activation may interrupt animation, but final semantic state and content must remain correct."),
-    rule("reduced-motion", "Respect prefers-reduced-motion without removing access to content or state."),
-  ];
-}
-
-function baseSectionRules(section) {
-  const rules = [
-    rule("preserve-archetype", `Keep this ${section.variant || section.kind || "section"} recognizable as the same source layout archetype.`),
-    rule("consistent-spacing", "Use a coherent local spacing rhythm and align equivalent edges."),
-    rule("responsive-without-clipping", "Reflow content at narrow widths without clipping, accidental overlap, or page-level horizontal overflow."),
-  ];
-  if (section.capabilities?.hasMedia) rules.push(rule("stable-media-region", "Give source media a deliberate bounded region and preserve its crop/fill intent."));
-  return rules;
-}
-
-function sectionIdentityLocks(section, scene, layout, blueprint) {
-  return {
-    order: section.id,
-    archetype: layout,
-    sourceClassification: `${section.kind || "section"}/${section.variant || "generic"}`,
-    heading: section.heading || "",
-    mediaRequired: Boolean(section.capabilities?.hasMedia || scene?.media?.length),
-    interactionPrimitive: scene?.implementation?.primitive || null,
-    backgroundKind: blueprint?.background?.kind || null,
-    forbiddenConversions: blueprint?.identityLocks?.forbiddenConversions || [],
-  };
-}
-
-function layoutFor(section, scene, page, blueprint) {
-  if (blueprint?.composition) return blueprint.composition;
-  if (scene?.implementation?.primitive === "active-card-rail" || section.capabilities?.isCarouselLike) return "horizontal-card-rail";
-  if (scene?.implementation?.primitive === "scroll-scene") return "scroll-narrative";
-  if (scene?.implementation?.primitive === "media-scene" && page.sections?.[0]?.id === section.id) return "hero";
-  if (section.kind === "card-collection") return "card-grid";
-  if (section.kind === "hero") return "hero";
-  if (section.kind === "footer") return "footer";
-  if (section.kind === "cta-strip") return "cta-band";
-  if (section.kind === "text-media") return "text-media";
-  return "content-section";
-}
-
-function repeatedItemHeightEvidence(carousel) {
-  const heights = (carousel?.states || []).flatMap((state) => (state.cards || []).map((card) => Number(card.height)).filter((height) => height > 0));
-  if (!heights.length) return { observed: false, sourceEqualHeight: false, heights: [] };
-  const sorted = [...heights].sort((left, right) => left - right);
-  const medianHeight = Math.round(sorted[Math.floor(sorted.length / 2)]);
-  const spreadRatio = round((Math.max(...heights) - Math.min(...heights)) / Math.max(1, medianHeight));
-  return {
-    observed: true,
-    heights,
-    medianHeight,
-    spreadRatio,
-    sourceEqualHeight: spreadRatio <= 0.05,
-  };
-}
-
-function triggerType(interaction) {
-  return typeof interaction?.trigger === "string" ? interaction.trigger : interaction?.trigger?.type || "";
-}
-
-function rule(id, requirement) {
-  return { id, requirement };
-}
-
-function renderNormalizationMarkdown(contract) {
-  const sections = contract.sections.map((section) => `## ${section.sectionId}: ${section.kind}/${section.variant}\n\nLayout: \`${section.layout}\`\n\nIdentity locks:\n${Object.entries(section.identityLocks).map(([key, value]) => `- ${key}: \`${String(value)}\``).join("\n")}\n\nRecipe:\n${section.recipe.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n\nRules:\n${section.rules.map((item) => `- **${item.id}:** ${item.requirement}`).join("\n")}\n\nAssertions:\n${section.assertions.map((assertion) => `- \`${assertion.kind}\`: ${JSON.stringify(assertion)}`).join("\n")}`).join("\n\n");
-  return `# Identity-preserving UI normalization\n\nUse this after source structure and interaction contracts. Identity locks outrank polish.\n\n## Allowed changes\n\n${contract.policy.allowedChanges.map((item) => `- ${item}`).join("\n")}\n\n## Forbidden changes\n\n${contract.policy.forbiddenChanges.map((item) => `- ${item}`).join("\n")}\n\n## Global rules\n\n${contract.globalRules.map((item) => `- **${item.id}:** ${item.requirement}`).join("\n")}\n\n${sections}\n`;
-}
-
-function round(value) {
-  return Math.round(value * 1000) / 1000;
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch((error) => {
-    console.error(error.stack || error.message);
-    process.exit(1);
-  });
-}