@wix/agent-skills 1.33.0 → 1.34.0

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

@@ -0,0 +1,176 @@
+#!/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 generateControlStateContract({ outputDir });
+  if (args.json) process.stdout.write(`${JSON.stringify(contract, null, 2)}\n`);
+}
+
+export async function generateControlStateContract({ outputDir, interactionMap: suppliedInteractionMap } = {}) {
+  const docs = docsDir(outputDir);
+  const interactionMap = suppliedInteractionMap || await readJson(path.join(docs, "interaction-map.json"));
+  const controls = new Map();
+  for (const interaction of interactionMap.interactions || []) {
+    const trigger = typeof interaction.trigger === "string" ? interaction.trigger : interaction.trigger?.type;
+    if (!interaction.controlRole && !["hover", "focus", "press", "click"].includes(trigger)) continue;
+    const key = `${interaction.controlScope || "content"}\u0000${interaction.controlRole || "control"}\u0000${interaction.controlId || interaction.label || interaction.id}`;
+    const control = controls.get(key) || {
+      id: `control-${String(controls.size + 1).padStart(3, "0")}`,
+      label: interaction.label || "Unlabelled control",
+      role: interaction.controlRole || "control",
+      scope: interaction.controlScope || "content",
+      sourceInteractionIds: [],
+      states: {},
+      transition: null,
+      ownerTransitions: [],
+      iconMotion: [],
+    };
+    control.sourceInteractionIds.push(interaction.id);
+    const states = interaction.states || [];
+    if (!control.states.rest && states[0]) control.states.rest = { values: baseControlValues(states[0]), sourceObserved: true };
+    const stateName = trigger === "focus" ? "focus-visible" : trigger === "press" ? "pressed" : trigger === "click" ? "activated" : trigger;
+    if (stateName && states[1]) {
+      control.states[stateName] = {
+        values: compactChangedValues(states[1], interaction.changedProperties || []),
+        changedProperties: interaction.changedProperties || [],
+        sourceObserved: (interaction.changedProperties || []).length > 0 || interaction.textChanged,
+      };
+    }
+    const rest = states[0] || {};
+    if (!control.states.current && (rest.ariaCurrent || /(?:^|\s)(active|current|selected)(?:\s|$)/i.test(rest.className || ""))) {
+      control.states.current = { values: baseControlValues(rest), sourceObserved: true };
+    }
+    if (!control.states.disabled && rest.disabled) control.states.disabled = { values: baseControlValues(rest), sourceObserved: true };
+    if (!control.transition && states[0]?.styles) {
+      control.transition = {
+        property: states[0].styles.transitionProperty || "all",
+        duration: states[0].styles.transitionDuration || "0s",
+        easing: states[0].styles.transitionTimingFunction || "ease",
+      };
+    }
+    for (const child of states[0]?.visualChildren || []) {
+      const duration = child.styles?.transitionDuration || "0s";
+      if (duration === "0s" || control.ownerTransitions.some((item) => item.owner === `child:${child.key}`)) continue;
+      control.ownerTransitions.push({ owner: `child:${child.key}`, property: child.styles?.transitionProperty || "all", duration, easing: child.styles?.transitionTimingFunction || "ease" });
+    }
+    for (const pseudo of ["before", "after"]) {
+      const duration = states[0]?.pseudo?.[pseudo]?.transitionDuration || "0s";
+      if (duration !== "0s" && !control.ownerTransitions.some((item) => item.owner === `::${pseudo}`)) {
+        control.ownerTransitions.push({ owner: `::${pseudo}`, property: states[0].pseudo[pseudo].transitionProperty || "all", duration, easing: states[0].pseudo[pseudo].transitionTimingFunction || "ease" });
+      }
+    }
+    for (const property of interaction.changedProperties || []) {
+      if (/^child:|^::/.test(property) && /transform|translate|scale|rotate|top|left|right|bottom/.test(property)) {
+        if (!control.iconMotion.includes(property)) control.iconMotion.push(property);
+      }
+    }
+    controls.set(key, control);
+  }
+  const compiledControls = mergeEquivalentControls(Array.from(controls.values()));
+  const contract = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    sourceUrl: interactionMap.sourceUrl || "",
+    terminology: {
+      rest: "Pointer absent and control not focused or pressed.",
+      hover: "Pointer is over the control.",
+      "focus-visible": "Keyboard-visible focus state; must remain perceivable even when absent from the source.",
+      pressed: "Pointer or key is held down; CSS :active equivalent.",
+      activated: "State immediately after activation/click.",
+      current: "Current route, tab, or selected control.",
+      disabled: "Unavailable control.",
+    },
+    precedence: ["source-observed-state", "accessible-focus-fallback", "identity-preserving-normalization"],
+    controls: compiledControls,
+    requirements: [
+      "Implement every sourceObserved state delta on the target, pseudo-element, or child that owns it.",
+      "Do not apply an icon transform to the whole button when only the nested icon moved in source evidence.",
+      "Preserve source transition duration and easing; otherwise use a subtle eased transition and respect prefers-reduced-motion.",
+      "Add a perceivable focus-visible state when the source exposes none, without replacing captured hover/current styling.",
+    ],
+  };
+  await writeJson(path.join(docs, "control-state-contract.json"), contract);
+  await writeText(path.join(docs, "control-state-contract.md"), renderMarkdown(contract));
+  return contract;
+}
+
+function mergeEquivalentControls(controls) {
+  const groups = new Map();
+  for (const control of controls) {
+    const signature = JSON.stringify({ role: control.role, scope: control.scope, states: control.states, transition: control.transition, ownerTransitions: control.ownerTransitions, iconMotion: control.iconMotion });
+    const existing = groups.get(signature);
+    if (!existing) {
+      groups.set(signature, { ...control, members: [control.label] });
+      continue;
+    }
+    if (!existing.members.includes(control.label)) existing.members.push(control.label);
+    existing.sourceInteractionIds.push(...control.sourceInteractionIds);
+  }
+  return Array.from(groups.values()).map((control, index) => ({
+    ...control,
+    id: `control-${String(index + 1).padStart(3, "0")}`,
+    sourceInteractionIds: Array.from(new Set(control.sourceInteractionIds)),
+  }));
+}
+
+// A style the browser never reported is absent, not broken. It must still be
+// representable: the frozen manifest is content-hashed with canonical JSON, which
+// rejects `undefined` outright and would fail the whole run over one missing property.
+function observed(value) {
+  return value === undefined ? null : value;
+}
+
+function baseControlValues(snapshot = {}) {
+  const style = snapshot.styles || {};
+  return {
+    color: observed(style.color),
+    backgroundColor: observed(style.backgroundColor),
+    borderColor: observed(style.borderColor),
+    borderWidth: [style.borderTopWidth, style.borderRightWidth, style.borderBottomWidth, style.borderLeftWidth].map(observed),
+    textDecoration: {
+      line: observed(style.textDecorationLine),
+      color: observed(style.textDecorationColor),
+      thickness: observed(style.textDecorationThickness),
+      offset: observed(style.textUnderlineOffset),
+    },
+    outline: {
+      color: observed(style.outlineColor),
+      style: observed(style.outlineStyle),
+      width: observed(style.outlineWidth),
+      offset: observed(style.outlineOffset),
+    },
+    cursor: observed(style.cursor),
+    ariaCurrent: snapshot.ariaCurrent || "",
+    ariaSelected: snapshot.ariaSelected || "",
+    ariaExpanded: snapshot.ariaExpanded || "",
+    disabled: Boolean(snapshot.disabled),
+  };
+}
+
+function compactChangedValues(snapshot, properties) {
+  return Object.fromEntries((properties || []).map((property) => [property, observed(snapshotValue(snapshot, property))]));
+}
+
+function snapshotValue(snapshot = {}, property) {
+  const child = String(property).match(/^child:(.+?)(?:::(before|after))?\.([^.]+)$/);
+  if (child) {
+    const record = (snapshot.visualChildren || []).find((item) => item.key === child[1]);
+    return child[2] ? record?.pseudo?.[child[2]]?.[child[3]] : record?.styles?.[child[3]];
+  }
+  const pseudo = String(property).match(/^::(before|after)\.([^.]+)$/);
+  if (pseudo) return snapshot.pseudo?.[pseudo[1]]?.[pseudo[2]];
+  if (snapshot.styles && property in snapshot.styles) return snapshot.styles[property];
+  return snapshot[property];
+}
+
+function renderMarkdown(contract) {
+  return `# Control State Contract\n\nSource: ${contract.sourceUrl}\n\nState precedence: ${contract.precedence.map((item) => `\`${item}\``).join(" → ")}\n\n${contract.requirements.map((item) => `- ${item}`).join("\n")}\n\n## Representative controls\n\n${contract.controls.map((control) => `### ${control.label}\n\n- role/scope: \`${control.role}\` / \`${control.scope}\`\n- members: ${control.members.join(", ")}\n- states: ${Object.keys(control.states).map((state) => `\`${state}\``).join(", ") || "none observed"}\n- icon-owned motion: ${control.iconMotion.map((item) => `\`${item}\``).join(", ") || "none"}\n- owner transitions: ${control.ownerTransitions.map((item) => `\`${item.owner} ${item.duration} ${item.easing}\``).join(", ") || "none"}\n- evidence: ${control.sourceInteractionIds.map((id) => `\`interaction-map.json#${id}\``).join(", ")}`).join("\n\n") || "_No representative controls captured._"}\n`;
+}
+
+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-design-md.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeText } from "./lib/common.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const url = normalizeUrl(args._[0] || args.url).toString();
+  const outputDir = resolveOutputDir(url, args.out);
+  const markdown = await generateDesignMd({ outputDir, sourceUrl: url });
+  await writeText(path.join(docsDir(outputDir), "design.md"), markdown);
+  if (args.stdout) process.stdout.write(markdown);
+}
+
+export async function generateDesignMd({ outputDir, sourceUrl }) {
+  const dir = docsDir(outputDir);
+  const sourceMap = await safeRead(path.join(dir, "source-map.json"), { pages: [], project: {} });
+  const tokens = await safeRead(path.join(dir, "tokens.json"), sourceMap.tokens || {});
+  const assets = await safeRead(path.join(dir, "assets.json"), { assets: [] });
+  const fonts = await safeRead(path.join(dir, "fonts.json"), sourceMap.fonts || { faces: [] });
+  const seo = await safeRead(path.join(dir, "seo.json"), sourceMap.seo || {});
+  const title = seo.title || sourceMap.pages?.[0]?.title || new URL(sourceUrl).hostname;
+  const sections = sourceMap.pages?.flatMap((page) => page.sections || []).slice(0, 18) || [];
+  const chrome = sourceMap.pages?.find((page) => page.chrome)?.chrome || null;
+  const extraction = tokens.extraction || sourceMap.designExtraction || { source: "local" };
+  return `# Design System
+
+Source: ${sourceUrl}
+
+## Extraction
+
+- Source: ${extraction.source || "local"}
+- Selected extractor: ${extraction.selectedExtractor || sourceMap.designExtraction?.selectedExtractor || extraction.source || "local"}
+${extraction.fallbackReason ? `- Fallback reason: ${extraction.fallbackReason}` : "- Fallback reason: none"}
+${formatExtractionAttempts(extraction.attempts || sourceMap.designExtraction?.attempts || [])}
+${tokens.designMdGenerator ? "- design-md-generator artifacts: `docs/site-clone/design-md-generator/`" : "- design-md-generator artifacts: not available"}
+
+## Brand Summary
+
+- Site title: ${title}
+- Visual position: infer from source screenshots, brand assets, extracted design tokens, typography, and section rhythm.
+- Primary goal: preserve recognizable source brand while rebuilding as a Wix Headless Astro/Tailwind frontend.
+
+## Assets
+
+${(assets.assets || []).slice(0, 20).map((asset) => `- ${asset.type}: \`${asset.localPath}\` from ${asset.sourceUrl}`).join("\n") || "- No downloaded assets recorded yet."}
+
+## Color Tokens
+
+${list(tokens.colors, "No colors extracted. Inspect screenshots and CSS manually.")}
+
+Recommended Tailwind variables:
+
+${tailwindRecommendations(tokens)}
+
+## Typography
+
+Font families:
+
+${list(tokens.fontFamilies, "No font families extracted. Inspect computed styles and downloaded font files.")}
+
+Font sizes:
+
+${list(tokens.fontSizes, "No font sizes extracted. Use source screenshots and computed styles.")}
+
+- Copy the exact source \`@font-face\` blocks with local URLs substituted; do not pick a downloaded font file by family name alone.
+- Use \`docs/site-clone/fonts.json\` as the source of truth for \`font-family\`, \`font-style\`, \`font-weight\`, and \`unicode-range\`.
+- Map body and display roles from the extracted font families before building page sections.
+- Set body, headings, links, buttons, and small text explicitly.
+- Preserve source line-height and letter-spacing where the extracted tokens report them; otherwise derive them from screenshots and computed styles.
+
+### Extracted Font Faces
+
+${formatFontFaces(fonts)}
+
+## Layout And Spacing
+
+- Use source section order and rhythm as the baseline.
+- Define shared containers for narrow, default, and wide content.
+- Keep mobile and desktop layouts close enough rather than pixel-identical.
+- Avoid placeholder sections; every visible block should map back to source evidence.
+${tokens.spacing?.length ? `- Spacing scale: ${inlineList(tokens.spacing)}.` : "- Spacing scale: infer from section rhythm and component specs."}
+${tokens.breakpoints?.length ? `- Breakpoints: ${inlineList(tokens.breakpoints)}.` : "- Breakpoints: use desktop, tablet, and mobile screenshots as responsive checkpoints."}
+
+## Header And Navigation
+
+${chromeSummary(chrome)}
+
+## First Viewport Evidence
+
+${firstViewportSummary(chrome)}
+
+## Radii, Borders, Shadows
+
+Radii:
+
+${list(tokens.radii, "No radii extracted. Infer from cards, buttons, forms, and media corners.")}
+
+Shadows:
+
+${list(tokens.shadows, "No shadows extracted. Infer elevation from source UI.")}
+
+## Global CSS Recommendations
+
+- Define theme variables in one global stylesheet before writing sections.
+- Load local fonts from downloaded assets when available; otherwise use the closest source fallback stack.
+- Run \`node skills/wix-headless-replatform/scripts/validate-font-contract.mjs ${sourceUrl} --out ${outputDir}\` after implementing local \`@font-face\` declarations.
+- Set \`html\`, \`body\`, base text color, background color, link color, and focus styles globally.
+- Verify the implemented global font family and primary text color against extracted tokens before styling sections.
+- Add reusable utilities for source-aligned containers, section padding, product grids, and CTA groups.
+
+## Component Patterns
+
+- Header/nav: preserve menu labels, order, dropdown intent, and CTA priority.
+- Header behavior: if the source has a large static header and a smaller scrolled sticky/fixed header, approximate that pattern with a compact sticky state rather than pinning the large header.
+- Footer: preserve link groups, legal links, contact/social signals, and brand treatment.
+- Buttons/links: derive size, radius, colors, hover states, and typography from source CTAs.
+- Inputs: preserve source border, radius, focus, disabled, placeholder, and validation treatment.
+- Cards/forms/badges: use source spacing, border, radius, and shadow rules.
+- Menus: preserve dropdown hierarchy, mobile drawer behavior, spacing, and active states.
+- Hero content: render only text and CTAs visible in first-viewport source evidence; do not turn SEO titles or metadata into hero copy.
+- Dynamic data templates: build reusable Wix SDK-backed components for products, posts, categories, CMS items, bookings, and events.
+- Not-migrated fallback: use the same brand/layout system.
+
+## Source Section Inventory
+
+${sections.map((section, index) => `### ${index + 1}. ${section.heading || section.tag || "Section"}\n\n${section.text || "_No text captured._"}`).join("\n\n") || "_No sections captured._"}
+
+## Implementation Checklist
+
+- Set Tailwind/theme variables before building pages.
+- Add global CSS and local font loading.
+- Build shared header, footer, layout, and CTA components first.
+- Build static pages from component specs.
+- Build dynamic Wix SDK-backed routes for repeated data-driven templates.
+- Add branded not-migrated fallback.
+- Run build, link, SEO, and visual QA.
+`;
+}
+
+function list(values, empty) {
+  if (!values?.length) return `- ${empty}`;
+  return values.map((value) => `- \`${value}\``).join("\n");
+}
+
+function inlineList(values) {
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+function chromeSummary(chrome) {
+  if (!chrome) {
+    return [
+      "- No browser chrome evidence was captured.",
+      "- Manually inspect source screenshots for header height, sticky behavior, logo scale, dropdown hierarchy, and mobile menu behavior before implementing shared chrome.",
+    ].join("\n");
+  }
+  const lines = [];
+  lines.push(`- Source direction: \`${chrome.direction || "unknown"}\`.`);
+  for (const variant of chrome.header?.variants || []) {
+    const logo = variant.logo
+      ? ` Logo rendered about ${variant.logo.renderedWidth}x${variant.logo.renderedHeight}px.`
+      : "";
+    lines.push(`- Header ${variant.name}: ${variant.visible === false ? "not visible" : `${variant.height || 0}px high, ${variant.position || "unknown"} positioning at scrollY ${variant.visibleAtScrollY || 0}`}.${logo}`);
+  }
+  const stickyLimit = chrome.header?.maxStickyViewportRatio || 0.16;
+  lines.push(`- Do not keep a sticky/fixed header taller than about ${Math.round(stickyLimit * 100)}% of desktop viewport height unless source evidence shows that exact behavior.`);
+  const nav = chrome.navigation || [];
+  if (nav.length) {
+    const dropdowns = nav.filter((item) => item.children?.length);
+    lines.push(`- Top-level navigation items detected: ${nav.length}.`);
+    if (dropdowns.length) {
+      lines.push(`- Dropdown menus detected: ${dropdowns.map((item) => `${item.label || item.href} (${item.children.length} children)`).join(", ")}.`);
+      lines.push("- Preserve dropdown children as submenu items; do not promote them to top-level links at the same viewport.");
+    } else {
+      lines.push("- No dropdown hierarchy was detected in browser evidence; verify manually if source screenshots show menus.");
+    }
+  } else {
+    lines.push("- No structured navigation hierarchy was captured; use screenshots and DOM review before flattening links.");
+  }
+  for (const warning of chrome.warnings || []) lines.push(`- Warning: ${warning}.`);
+  return lines.join("\n");
+}
+
+function firstViewportSummary(chrome) {
+  const evidence = chrome?.heroEvidence;
+  if (!evidence) {
+    return "- No first-viewport text evidence was captured. Do not infer hero copy from SEO metadata without source visual evidence.";
+  }
+  const lines = [];
+  if (evidence.visibleText?.length) {
+    lines.push("- Visible first-viewport text samples:");
+    for (const text of evidence.visibleText.slice(0, 12)) lines.push(`  - ${text}`);
+  } else {
+    lines.push("- No non-header first-viewport text was captured; keep hero media clean unless screenshots show visible copy or CTAs.");
+  }
+  if (evidence.forbiddenSeoOnlyText?.length) {
+    lines.push("- SEO-only text not confirmed as visible hero content:");
+    for (const text of evidence.forbiddenSeoOnlyText.slice(0, 8)) lines.push(`  - ${text}`);
+    lines.push("- Do not render the SEO-only text above as hero copy unless visual evidence confirms it.");
+  }
+  return lines.join("\n");
+}
+
+function tailwindRecommendations(tokens) {
+  if (typeof tokens.recommendedTailwindTokens?.colors === "string") {
+    const recommendations = [
+      tokens.recommendedTailwindTokens.colors,
+      tokens.recommendedTailwindTokens.fonts,
+      tokens.recommendedTailwindTokens.spacing,
+      tokens.recommendedTailwindTokens.radii,
+      tokens.recommendedTailwindTokens.shadows,
+    ].filter(Boolean);
+    return recommendations.map((item) => `- ${item}`).join("\n");
+  }
+  return [
+    "`--background`",
+    "`--foreground`",
+    "`--primary`",
+    "`--primary-foreground`",
+    "`--secondary`",
+    "`--muted`",
+    "`--accent`",
+    "`--border`",
+  ].map((item) => `- ${item}`).join("\n");
+}
+
+function formatExtractionAttempts(attempts) {
+  if (!attempts?.length) return "- Fallback attempts: none recorded";
+  return `- Fallback attempts:\n${attempts.map((attempt) => `  - ${attempt.extractor}${attempt.mode ? `/${attempt.mode}` : ""}: ${attempt.status}${attempt.reason ? ` (${attempt.reason})` : ""}`).join("\n")}`;
+}
+
+function formatFontFaces(fonts) {
+  if (!fonts?.faces?.length) return "- No font-face declarations extracted.";
+  return fonts.faces
+    .slice(0, 18)
+    .map((face) => {
+      const sources = (face.sources || [])
+        .map((source) =>
+          source.kind === "url"
+            ? `\`${source.localPath || source.url}\`${source.localPath ? ` from ${source.url}` : ""}`
+            : `local(${source.value})`,
+        )
+        .join(", ");
+      return `- \`${face.family}\` / ${face.style} / ${face.weight}${face.unicodeRange ? ` / ${face.unicodeRange}` : ""} -> ${sources || "no URL sources"}`;
+    })
+    .join("\n");
+}
+
+async function safeRead(filePath, fallback) {
+  try {
+    return await readJson(filePath);
+  } catch {
+    return fallback;
+  }
+}
+
+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-extraction-validators.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const schemaDir = path.join(skillRoot, "schemas");
+const outputPath = path.join(skillRoot, "scripts", "lib", "extraction-validators.generated.mjs");
+const files = (await readdir(schemaDir)).filter((name) => name.endsWith(".schema.json") && name !== "common.schema.json").sort();
+const schemas = {};
+for (const file of files) schemas[file.replace(/\.schema\.json$/, "")] = JSON.parse(await readFile(path.join(schemaDir, file), "utf8"));
+
+const runtime = `// Generated by scripts/generate-extraction-validators.mjs. Do not hand-edit.\nconst SCHEMAS = ${JSON.stringify(schemas, null, 2)};\n\nexport const GENERATED_SCHEMA_VERSION = "0083.1";\nexport const GENERATED_SCHEMA_KINDS = Object.freeze(Object.keys(SCHEMAS).sort());\n\nexport function validateGeneratedArtifact(value, kind) {\n  const schema = SCHEMAS[kind];\n  if (!schema) return { ok: false, errors: [\`unsupported generated schema: \${kind}\`] };\n  const errors = [];\n  validate(value, schema, "$", errors, false);\n  return { ok: errors.length === 0, errors };\n}\n\nfunction validate(value, schema, at, errors, conditionOnly) {\n  if (!schema || typeof schema !== "object") return true;\n  const before = errors.length;\n  if (schema.const !== undefined && !same(value, schema.const)) errors.push(\`\${at}: must equal \${JSON.stringify(schema.const)}\`);\n  if (schema.enum && !schema.enum.some((entry) => same(value, entry))) errors.push(\`\${at}: must be one of \${schema.enum.map(String).join(", ")}\`);\n  if (schema.type && !matchesType(value, schema.type)) errors.push(\`\${at}: must be type \${Array.isArray(schema.type) ? schema.type.join("|") : schema.type}\`);\n  if (typeof value === "string") {\n    if (schema.minLength !== undefined && value.length < schema.minLength) errors.push(\`\${at}: must have length >= \${schema.minLength}\`);\n    if (schema.pattern && !new RegExp(schema.pattern, "u").test(value)) errors.push(\`\${at}: must match \${schema.pattern}\`);\n    if (schema.format === "uri") { try { new URL(value); } catch { errors.push(\`\${at}: must be a URI\`); } }\n  }\n  if (typeof value === "number") {\n    if (schema.minimum !== undefined && value < schema.minimum) errors.push(\`\${at}: must be >= \${schema.minimum}\`);\n    if (schema.maximum !== undefined && value > schema.maximum) errors.push(\`\${at}: must be <= \${schema.maximum}\`);\n  }\n  if (Array.isArray(value)) {\n    if (schema.minItems !== undefined && value.length < schema.minItems) errors.push(\`\${at}: must contain >= \${schema.minItems} items\`);\n    if (schema.maxItems !== undefined && value.length > schema.maxItems) errors.push(\`\${at}: must contain <= \${schema.maxItems} items\`);\n    if (schema.uniqueItems && new Set(value.map((entry) => JSON.stringify(entry))).size !== value.length) errors.push(\`\${at}: items must be unique\`);\n    if (schema.items) value.forEach((entry, index) => validate(entry, schema.items, \`\${at}[\${index}]\`, errors, conditionOnly));\n  }\n  if (value && typeof value === "object" && !Array.isArray(value)) {\n    for (const required of schema.required || []) if (!(required in value)) errors.push(\`\${at}.\${required}: is required\`);\n    const properties = schema.properties || {};\n    for (const [key, entry] of Object.entries(value)) {\n      if (properties[key]) validate(entry, properties[key], \`\${at}.\${key}\`, errors, conditionOnly);\n      else if (schema.additionalProperties === false) errors.push(\`\${at}.\${key}: additional property is not allowed\`);\n      else if (schema.additionalProperties && typeof schema.additionalProperties === "object") validate(entry, schema.additionalProperties, \`\${at}.\${key}\`, errors, conditionOnly);\n      if (schema.propertyNames?.pattern && !new RegExp(schema.propertyNames.pattern, "u").test(key)) errors.push(\`\${at}.\${key}: property name must match \${schema.propertyNames.pattern}\`);\n    }\n  }\n  for (const child of schema.allOf || []) validate(value, child, at, errors, conditionOnly);\n  if (schema.if) {\n    const probe = [];\n    validate(value, schema.if, at, probe, true);\n    if (!probe.length && schema.then) validate(value, schema.then, at, errors, conditionOnly);\n  }\n  if (conditionOnly && errors.length > before) return false;\n  return errors.length === before;\n}\n\nfunction matchesType(value, expected) {\n  const types = Array.isArray(expected) ? expected : [expected];\n  return types.some((type) => type === "null" ? value === null\n    : type === "array" ? Array.isArray(value)\n      : type === "object" ? Boolean(value) && typeof value === "object" && !Array.isArray(value)\n        : type === "integer" ? Number.isInteger(value)\n          : type === "number" ? typeof value === "number" && Number.isFinite(value)\n            : typeof value === type);\n}\n\nfunction same(left, right) { return JSON.stringify(left) === JSON.stringify(right); }\n`;
+
+if (process.argv.includes("--check")) {
+  let existing = "";
+  try { existing = await readFile(outputPath, "utf8"); } catch {}
+  if (existing !== runtime) {
+    console.error("Generated extraction validators are stale. Run node skills/wix-headless-replatform/scripts/generate-extraction-validators.mjs");
+    process.exit(1);
+  }
+} else {
+  await writeFile(outputPath, runtime);
+  console.log(outputPath);
+}