@jay-framework/jay-stack-cli 0.24.5 → 0.24.7

package/dist/index.js

@@ -7,22 +7,24 @@ import path$1 from "path";
 import fs$1, { promises } from "fs";
 import YAML from "yaml";
 import { getLogger, setDevLogger, createDevLogger } from "@jay-framework/logger";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseAction, parseContract, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseContract, compileContract, parseAction, generateElementFile, generateServerElementFile, htmlElementTagNameMap, loadLinkedContract, getLinkedContractDir } from "@jay-framework/compiler-jay-html";
+import { checkValidationErrors, JAY_CONTRACT_EXTENSION as JAY_CONTRACT_EXTENSION$1, loadPluginManifest as loadPluginManifest$1, normalizeActionEntry as normalizeActionEntry$1, JAY_EXTENSION as JAY_EXTENSION$1, RuntimeMode as RuntimeMode$1, GenerateTarget, findDynamicContract, isEnumType as isEnumType$1, equalJayTypes, prettifyHtml } from "@jay-framework/compiler-shared";
 import fs$2 from "node:fs/promises";
 import * as path from "node:path";
 import path__default from "node:path";
+import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
 import { createRequire } from "module";
 import jsBeautify from "js-beautify";
-import { scanPlugins, sortPluginsByDependencies, getServiceRegistry, actionRegistry, resolveServices, ActionRegistry, discoverPluginsWithInit, executePluginServerInits, runInitCallbacks, registerService } from "@jay-framework/stack-server-runtime";
 import "node:crypto";
 import * as fs from "node:fs";
 import fs__default from "node:fs";
 import { createRequire as createRequire$1 } from "node:module";
 import { isJayAction, isJayStreamAction, isJayCliCommand, CONSOLE_CONTEXT } from "@jay-framework/fullstack-component";
+import { parse, NodeType, HTMLElement } from "node-html-parser";
 import { Command } from "commander";
 import chalk from "chalk";
-import { loadPluginManifest as loadPluginManifest$1, normalizeActionEntry as normalizeActionEntry$1, JAY_EXTENSION, RuntimeMode as RuntimeMode$1, GenerateTarget, JAY_CONTRACT_EXTENSION, findDynamicContract } from "@jay-framework/compiler-shared";
 import { glob } from "glob";
+import postcss from "postcss";
 import { fileURLToPath } from "node:url";
 import { select, confirm, input } from "@inquirer/prompts";
 const DEFAULT_CONFIG = {
@@ -88,12 +90,13 @@ function updateConfig(updates) {
     getLogger().warn(`Failed to update .jay config file: ${error}`);
   }
 }
-async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
-  for (const route of routes) {
-    const jayHtmlPath = route.fsRoute.jayHtmlPath;
+async function generatePageDefinitionFiles(jayHtmlPaths, tsConfigPath, projectRoot) {
+  for (const jayHtmlPath of jayHtmlPaths) {
     if (!fs$1.existsSync(jayHtmlPath)) {
       continue;
     }
+    const dirname = path$1.dirname(jayHtmlPath);
+    const filename = path$1.basename(jayHtmlPath);
     const definitionFilePath = jayHtmlPath + ".d.ts";
     try {
       const [sourceStats, defStats] = await Promise.all([
@@ -107,8 +110,6 @@ async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
     }
     try {
       const jayHtml = await fs$1.promises.readFile(jayHtmlPath, "utf-8");
-      const filename = path$1.basename(jayHtmlPath);
-      const dirname = path$1.dirname(jayHtmlPath);
       const parsedJayHtml = await parseJayFile(
         jayHtml,
         filename,
@@ -132,6 +133,71 @@ async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
     }
   }
 }
+const generatePageDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  generatePageDefinitionFiles
+}, Symbol.toStringTag, { value: "Module" }));
+const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", "build", "dist", ".git", ".cache"]);
+async function generateContractDefinitionFiles(root) {
+  const contractFiles = await collectContractFiles(root);
+  for (const contractPath of contractFiles) {
+    const definitionFilePath = contractPath + ".d.ts";
+    try {
+      const [sourceStats, defStats] = await Promise.all([
+        fs$1.promises.stat(contractPath),
+        fs$1.promises.stat(definitionFilePath).catch(() => null)
+      ]);
+      if (defStats && defStats.mtime >= sourceStats.mtime) {
+        continue;
+      }
+    } catch (error) {
+    }
+    try {
+      const code = await fs$1.promises.readFile(contractPath, "utf-8");
+      const filename = path$1.basename(contractPath);
+      const parsed = parseContract(code, filename);
+      const tsCode = await compileContract(parsed, contractPath, JAY_IMPORT_RESOLVER);
+      if (tsCode.validations.length > 0) {
+        getLogger().warn(
+          `failed to generate .d.ts for ${contractPath} with validation errors: ${tsCode.validations.join("\n")}`
+        );
+        continue;
+      }
+      await fs$1.promises.writeFile(definitionFilePath, checkValidationErrors(tsCode), "utf-8");
+      getLogger().info(`📦 Generated contract definition file: ${definitionFilePath}`);
+    } catch (error) {
+      getLogger().error(`Failed to generate definition file for ${contractPath}: ${error}`);
+    }
+  }
+}
+async function collectContractFiles(root) {
+  const results = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await fs$1.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path$1.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+          continue;
+        }
+        await walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(JAY_CONTRACT_EXTENSION$1)) {
+        results.push(fullPath);
+      }
+    }
+  }
+  await walk(root);
+  return results;
+}
+const generateContractDefinitionFiles$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  generateContractDefinitionFiles
+}, Symbol.toStringTag, { value: "Module" }));
 async function startDevServer(options = {}) {
   const projectPath = options.projectPath || process.cwd();
   if (projectPath !== process.cwd()) {
@@ -177,7 +243,14 @@ async function startDevServer(options = {}) {
       app.get(route.path, route.handler);
     });
   });
-  generatePageDefinitionFiles(routes, jayOptions.tsConfigFilePath, process.cwd());
+  void (async () => {
+    await generatePageDefinitionFiles(
+      routes.map((route) => route.fsRoute.jayHtmlPath),
+      jayOptions.tsConfigFilePath,
+      process.cwd()
+    );
+    await generateContractDefinitionFiles(path$1.resolve("src"));
+  })();
   httpServer.listen(devServerPort, () => {
     log.important(`🚀 Jay Stack dev server started successfully!`);
     log.important(`📱 Dev Server: http://localhost:${devServerPort}`);
@@ -231,6 +304,8 @@ createRequire(import.meta.url);
 var __defProp2 = Object.defineProperty;
 var __defNormalProp2 = (obj, key, value) => key in obj ? __defProp2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField2 = (obj, key, value) => __defNormalProp2(obj, key + "", value);
+const JAY_EXTENSION = ".jay-html";
+const JAY_CONTRACT_EXTENSION = ".jay-contract";
 class JayAtomicType {
   constructor(name) {
     __publicField2(this, "kind", 0);
@@ -803,6 +878,172 @@ async function discoverPluginActions(pluginPath, projectRoot, registry = actionR
   }
   return registeredActions;
 }
+function readTemplateMeta(jayHtmlPath) {
+  let content;
+  try {
+    content = fs.readFileSync(jayHtmlPath, "utf-8");
+  } catch {
+    return {};
+  }
+  const root = parse(content);
+  const ref = root.querySelector('script[type="application/jay-data"]')?.getAttribute("contract");
+  const contractRef = ref ? path.resolve(path.dirname(jayHtmlPath), ref) : void 0;
+  const rawTitle = root.querySelector("title")?.text?.trim();
+  const staticTitle = rawTitle ? rawTitle.replace(/\{[^}]*\}/g, "").trim() : "";
+  return { contractRef, title: staticTitle.length > 0 ? staticTitle : void 0 };
+}
+function listTemplatesForContractFile(contractFile) {
+  if (!contractFile) return [];
+  const dir = path.dirname(contractFile);
+  const target = path.resolve(contractFile);
+  const contractBasename = path.basename(contractFile, JAY_CONTRACT_EXTENSION);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const variants = [];
+  for (const f of names) {
+    if (!f.endsWith(JAY_EXTENSION)) continue;
+    const jayHtmlPath = path.join(dir, f);
+    const meta = readTemplateMeta(jayHtmlPath);
+    if (meta.contractRef !== target) continue;
+    const stem = path.basename(f, JAY_EXTENSION);
+    variants.push({
+      path: jayHtmlPath,
+      variant: stem === contractBasename ? "" : stem,
+      ...meta.title && { title: meta.title }
+    });
+  }
+  return variants.sort((a, b) => a.variant.localeCompare(b.variant));
+}
+function hasTemplateForContractFile(contractFile) {
+  return listTemplatesForContractFile(contractFile).length > 0;
+}
+function readContractField(contractFile, field) {
+  try {
+    const parsed = YAML.parse(fs.readFileSync(contractFile, "utf-8"));
+    const value = parsed?.[field];
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findContractFilesSync(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findContractFilesSync(full));
+    else if (entry.name.endsWith(JAY_CONTRACT_EXTENSION)) out.push(full);
+  }
+  return out.sort();
+}
+function buildDesignSystemIndex(options) {
+  const { projectRoot, plugins, resolvePluginContractPath } = options;
+  const componentsBase = options.componentsBase ? path.resolve(projectRoot, options.componentsBase) : path.join(projectRoot, "src", "components");
+  const rel = (p) => "./" + path.relative(projectRoot, p).replace(/\\/g, "/");
+  const makeEntry = (contractFile, source, pluginName, nameOverride) => {
+    const name = nameOverride ?? readContractField(contractFile, "name") ?? path.basename(contractFile, JAY_CONTRACT_EXTENSION);
+    const description = readContractField(contractFile, "description");
+    const templates = listTemplatesForContractFile(contractFile).map((t) => ({
+      ...t,
+      path: rel(t.path)
+    }));
+    return {
+      name,
+      contractPath: rel(contractFile),
+      ...description && { description },
+      source,
+      ...pluginName && { plugin: pluginName },
+      templates
+    };
+  };
+  const components = [];
+  for (const contractFile of findContractFilesSync(componentsBase)) {
+    components.push(makeEntry(contractFile, "local", void 0));
+  }
+  for (const [, plugin] of plugins) {
+    const contracts = plugin.manifest.contracts;
+    if (!Array.isArray(contracts)) continue;
+    for (const contract of contracts) {
+      const spec = contract.contract;
+      if (!spec) continue;
+      const contractFile = resolvePluginContractPath(plugin, spec);
+      components.push(makeEntry(contractFile, "plugin", plugin.name, contract.name));
+    }
+  }
+  return { components };
+}
+function toKebabCase$1(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[\s_]+/g, "-").replace(/^-/, "");
+}
+function renderAddMenu(index) {
+  const lines = [];
+  lines.push("# Design-system elements you can add");
+  lines.push("");
+  lines.push(
+    "Generated by `jay-stack agent-kit`. Each component ships a contract and one or more"
+  );
+  lines.push(
+    "`.jay-html` templates you can flatten into a page as a `<jay:X>` region. Pick a variant,"
+  );
+  lines.push("paste its import + region, then run `jay-stack sync` to flatten the markup. See");
+  lines.push("`designer/design-system-guide.md`.");
+  lines.push("");
+  if (index.components.length === 0) {
+    lines.push("_No design-system components found._");
+    lines.push("");
+    return lines.join("\n");
+  }
+  for (const component of index.components) {
+    lines.push(
+      component.description ? `## ${component.name} — ${component.description}` : `## ${component.name}`
+    );
+    lines.push("");
+    if (component.templates.length === 0) {
+      lines.push(
+        "_No template yet (COMPONENT-NO-TEMPLATE) — this component can't be flattened until it ships a `.jay-html`._"
+      );
+      lines.push("");
+      continue;
+    }
+    lines.push("| Variant | Title | Template |");
+    lines.push("| --- | --- | --- |");
+    for (const template of component.templates) {
+      const variant = template.variant === "" ? "(default)" : template.variant;
+      lines.push(`| ${variant} | ${template.title ?? ""} | ${template.path} |`);
+    }
+    lines.push("");
+    const first = component.templates[0];
+    const regionTag = toKebabCase$1(component.name);
+    const contractAttr = component.source === "plugin" ? component.name : component.contractPath;
+    lines.push("```html");
+    lines.push("<script");
+    lines.push('  type="application/jay-headless"');
+    if (component.source === "plugin" && component.plugin) {
+      lines.push(`  plugin="${component.plugin}"`);
+    }
+    lines.push(`  contract="${contractAttr}"`);
+    lines.push(`  template="${first.path}"`);
+    lines.push("><\/script>");
+    lines.push("");
+    lines.push(
+      `<jay:${regionTag} ref="${regionTag}"><!-- flattened copy; edit freely --></jay:${regionTag}>`
+    );
+    lines.push("```");
+    lines.push("");
+    lines.push("Then run `jay-stack sync` to flatten it.");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 const require$1 = createRequire(import.meta.url);
 async function executeDynamicGenerator(plugin, config, projectRoot, services, verbose, viteServer) {
   const { pluginPath, name: pluginName, isLocal, packageName } = plugin;
@@ -932,6 +1173,15 @@ function resolveActionFilePath(actionPath, packageName, pluginPath, isLocal, pro
 function toKebabCase(str) {
   return str.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
 }
+function readComponentsBase(projectRoot) {
+  try {
+    const parsed = YAML.parse(fs.readFileSync(path.join(projectRoot, ".jay"), "utf-8"));
+    const base = parsed?.devServer?.componentsBase;
+    if (typeof base === "string" && base.length > 0) return base;
+  } catch {
+  }
+  return "./src/components";
+}
 async function materializeContracts(options, services = /* @__PURE__ */ new Map()) {
   const {
     projectRoot,
@@ -1151,13 +1401,26 @@ async function materializeContracts(options, services = /* @__PURE__ */ new Map(
       ...data.commands?.length && { commands: data.commands }
     }))
   };
+  const designSystem = buildDesignSystemIndex({
+    projectRoot,
+    componentsBase: readComponentsBase(projectRoot),
+    plugins,
+    resolvePluginContractPath: (plugin, spec) => resolveStaticContractPath(plugin, spec, projectRoot)
+  });
+  pluginsIndex.designSystemIndex = "./design-system-index.yaml";
   fs.mkdirSync(outputDir, { recursive: true });
   const agentKitDir = path.dirname(outputDir);
   const pluginsIndexPath = path.join(agentKitDir, "plugins-index.yaml");
   fs.writeFileSync(pluginsIndexPath, YAML.stringify(pluginsIndex), "utf-8");
+  const designSystemIndexPath = path.join(agentKitDir, "design-system-index.yaml");
+  fs.writeFileSync(designSystemIndexPath, YAML.stringify(designSystem), "utf-8");
+  const addMenuPath = path.join(agentKitDir, "design-system.md");
+  fs.writeFileSync(addMenuPath, renderAddMenu(designSystem), "utf-8");
   if (verbose) {
     getLogger().info(`
 ✅ Plugins index written to: ${pluginsIndexPath}`);
+    getLogger().info(`✅ Design-system index written to: ${designSystemIndexPath}`);
+    getLogger().info(`✅ Design-system add-menu written to: ${addMenuPath}`);
   }
   return {
     pluginsIndex,
@@ -1581,132 +1844,6 @@ async function initializeServicesForCli(projectRoot, viteServer, quiet = false)
   }
   return { services: getServiceRegistry2(), initErrors };
 }
-async function runDev(projectPath, options) {
-  const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
-  setDevLogger(createDevLogger(logLevel));
-  const testMode = options.testMode || options.timeout !== void 0;
-  await startDevServer({
-    projectPath: projectPath || process.cwd(),
-    testMode,
-    timeout: options.timeout,
-    logLevel
-  });
-}
-async function resolveProductionContext(projectPath, versionOverride) {
-  const resolvedPath = path__default.resolve(projectPath || process.cwd());
-  const jayConfigPath = path__default.join(resolvedPath, ".jay");
-  let pagesBase = "./src/pages";
-  let siteBaseUrl;
-  try {
-    const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
-    pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
-    siteBaseUrl = jayConfig?.site?.baseUrl;
-  } catch {
-  }
-  const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
-  return {
-    resolvedPath,
-    pagesRoot: path__default.resolve(resolvedPath, pagesBase),
-    buildRoot: path__default.join(resolvedPath, "build"),
-    version,
-    tsConfigFilePath: path__default.join(resolvedPath, "tsconfig.json"),
-    siteBaseUrl
-  };
-}
-async function resolveVersionFromPackageJson(projectRoot) {
-  try {
-    const pkgJson = JSON.parse(
-      await fs$2.readFile(path__default.join(projectRoot, "package.json"), "utf-8")
-    );
-    if (pkgJson.version) {
-      return pkgJson.version;
-    }
-  } catch {
-  }
-  return "1";
-}
-function initLogger(verbose) {
-  const logLevel = verbose ? "verbose" : "info";
-  setDevLogger(createDevLogger(logLevel));
-}
-async function runBuild(projectPath, options) {
-  initLogger(options.verbose);
-  const ctx = await resolveProductionContext(projectPath, options.version);
-  const { buildVersion } = await import("./index-B9vCxAZ1.js");
-  await buildVersion({
-    version: ctx.version,
-    projectRoot: ctx.resolvedPath,
-    pagesRoot: ctx.pagesRoot,
-    buildRoot: ctx.buildRoot,
-    concurrency: 4,
-    tsConfigFilePath: ctx.tsConfigFilePath,
-    minify: options.minify,
-    siteBaseUrl: ctx.siteBaseUrl
-  });
-}
-async function runServe(projectPath, options) {
-  initLogger(options.verbose);
-  const ctx = await resolveProductionContext(projectPath, options.version);
-  if (options.role === "renderer") {
-    const { startRendererServer } = await import("@jay-framework/production-server");
-    await startRendererServer({
-      buildRoot: ctx.buildRoot,
-      version: ctx.version,
-      port: parseInt(options.port, 10),
-      projectRoot: ctx.resolvedPath,
-      pagesRoot: ctx.pagesRoot,
-      tsConfigFilePath: ctx.tsConfigFilePath,
-      siteBaseUrl: ctx.siteBaseUrl
-    });
-  } else {
-    const { startMainServer } = await import("@jay-framework/production-server");
-    await startMainServer({
-      buildRoot: ctx.buildRoot,
-      version: ctx.version,
-      port: parseInt(options.port, 10),
-      testMode: options.testMode,
-      publicBasePath: options.staticBaseUrl,
-      serveStatic: options.serveStatic
-    });
-  }
-}
-async function runRebuild(projectPath, options) {
-  initLogger(options.verbose);
-  const ctx = await resolveProductionContext(projectPath, options.version);
-  let params;
-  if (options.params) {
-    params = JSON.parse(options.params);
-  }
-  const { rebuild } = await import("@jay-framework/production-server");
-  let target;
-  if (options.contract) {
-    target = { mode: "contract", contractName: options.contract, params };
-  } else if (options.route) {
-    target = { mode: "route", routePattern: options.route, params };
-  } else if (options.url) {
-    target = { mode: "url", url: options.url };
-  } else {
-    getLogger().error(chalk.red("One of --contract, --route, or --url is required"));
-    process.exit(1);
-  }
-  const result = await rebuild({
-    projectRoot: ctx.resolvedPath,
-    pagesRoot: ctx.pagesRoot,
-    buildRoot: ctx.buildRoot,
-    version: ctx.version,
-    target,
-    tsConfigFilePath: ctx.tsConfigFilePath,
-    siteBaseUrl: ctx.siteBaseUrl
-  });
-  if (result.errors.length > 0) {
-    for (const err of result.errors) {
-      getLogger().error(
-        chalk.red(`  Error: ${err.route} ${JSON.stringify(err.params)}: ${err.error}`)
-      );
-    }
-    process.exit(1);
-  }
-}
 const s = createRequire(import.meta.url), e = s("typescript"), u = e;
 new Proxy(e, {
   get(t, r) {
@@ -1714,7 +1851,7 @@ new Proxy(e, {
   }
 });
 const FRAMEWORK_PROP_TYPES = /* @__PURE__ */ new Set(["PageProps", "RequestQuery"]);
-function checkComponentPropsAndParams(sourceCode, contract, contractName, contractPath, sourcePath) {
+function checkComponentPropsAndParams(sourceCode, contract, contractName2, contractPath, sourcePath) {
   const errors = [];
   const warnings = [];
   const sourceFile = u.createSourceFile(
@@ -1733,7 +1870,7 @@ function checkComponentPropsAndParams(sourceCode, contract, contractName, contra
       localInterfaces,
       contractImportedTypes,
       contract,
-      contractName,
+      contractName2,
       contractPath,
       sourcePath,
       errors,
@@ -1746,7 +1883,7 @@ function checkComponentPropsAndParams(sourceCode, contract, contractName, contra
       localInterfaces,
       contractImportedTypes,
       contract,
-      contractName,
+      contractName2,
       contractPath,
       sourcePath,
       errors,
@@ -1865,10 +2002,10 @@ function extractTypeNames(typeNode) {
   }
   return [];
 }
-function checkPropsConsistency(propsTypeName, localInterfaces, contractImportedTypes, contract, contractName, contractPath, sourcePath, errors, warnings) {
+function checkPropsConsistency(propsTypeName, localInterfaces, contractImportedTypes, contract, contractName2, contractPath, sourcePath, errors, warnings) {
   if (FRAMEWORK_PROP_TYPES.has(propsTypeName)) return;
   if (contractImportedTypes.has(propsTypeName)) return;
-  const prefix = `[${contractName}]`;
+  const prefix = `[${contractName2}]`;
   const iface = localInterfaces.get(propsTypeName);
   if (!iface) {
     if (!contract.props || contract.props.length === 0) {
@@ -1916,8 +2053,8 @@ function checkPropsConsistency(propsTypeName, localInterfaces, contractImportedT
     }
   }
 }
-function checkParamsConsistency(paramsTypeNames, localInterfaces, contractImportedTypes, contract, contractName, contractPath, sourcePath, errors, warnings) {
-  const prefix = `[${contractName}]`;
+function checkParamsConsistency(paramsTypeNames, localInterfaces, contractImportedTypes, contract, contractName2, contractPath, sourcePath, errors, warnings) {
+  const prefix = `[${contractName2}]`;
   if (!contract.params || contract.params.length === 0) {
     errors.push({
       type: "contract-invalid",
@@ -3679,14 +3816,14 @@ async function checkComponentContractConsistency(contract, context, result) {
   } catch {
     return;
   }
-  const contractName = contract.contract.replace(/\.jay-contract$/, "");
+  const contractName2 = contract.contract.replace(/\.jay-contract$/, "");
   const checkResult = checkComponentPropsAndParams(
     sourceCode,
     {
       props: parsed.val?.props,
       params: parsed.val?.params
     },
-    contractName,
+    contractName2,
     contractPath,
     sourcePath
   );
@@ -3958,36 +4095,731 @@ async function validateDynamicContracts(context, result) {
     }
   }
 }
-async function findJayFiles(dir) {
-  return await glob(`${dir}/**/*${JAY_EXTENSION}`);
+function overrideSpecFor(f) {
+  switch (f.kind) {
+    case "attribute":
+      return { target: "markup-attribute", path: f.path, value: f.name };
+    case "style-declaration":
+      return { target: "markup-attribute", path: f.path, value: `style.${f.property}` };
+    case "children":
+      return { target: "markup-attribute", path: f.path, value: "children" };
+    case "css-rule":
+      return { target: "css-comment", value: "" };
+    case "css-declaration":
+      return { target: "css-comment", value: f.property };
+  }
+}
+function facetLabel(f) {
+  switch (f.kind) {
+    case "attribute":
+      return `<${f.element.toLowerCase()}> attribute "${f.name}"`;
+    case "style-declaration":
+      return `<${f.element.toLowerCase()}> style "${f.property}"`;
+    case "children":
+      return `<${f.element.toLowerCase()}> children`;
+    case "css-rule":
+      return `css rule "${f.selector}"`;
+    case "css-declaration":
+      return `css "${f.selector}" declaration "${f.property}"`;
+  }
+}
+const CONTENT_MARKER = "jay-content";
+const META_ATTRS = /* @__PURE__ */ new Set(["jc", "override", "page-scope", CONTENT_MARKER]);
+function isMetaAttr(name) {
+  return META_ATTRS.has(name.toLowerCase());
+}
+function isRegionTag(el) {
+  return (el.tagName ?? "").toLowerCase().startsWith("jay:");
+}
+function readAttr(el, name) {
+  const v = el.getAttribute(name);
+  if (v !== void 0 && v !== null) return v;
+  const raw = el.rawAttributes ?? {};
+  return Object.prototype.hasOwnProperty.call(raw, name) ? raw[name] ?? "" : void 0;
+}
+function isPageScope(el) {
+  return readAttr(el, "page-scope") !== void 0;
+}
+const NO_SUPPRESSION = Object.freeze({
+  all: false,
+  attributes: /* @__PURE__ */ new Set(),
+  styleProps: /* @__PURE__ */ new Set(),
+  children: false
+});
+function emptySuppression() {
+  return { all: false, attributes: /* @__PURE__ */ new Set(), styleProps: /* @__PURE__ */ new Set(), children: false };
+}
+function parseFacetTokens(spec, sup) {
+  for (const token of spec.split(/[\s,]+/)) {
+    const t = token.trim();
+    if (!t) continue;
+    if (t.toLowerCase() === "children") sup.children = true;
+    else if (t.toLowerCase().startsWith("style."))
+      sup.styleProps.add(t.slice("style.".length).toLowerCase());
+    else sup.attributes.add(t.toLowerCase());
+  }
+}
+function parseOverride(el) {
+  if (isPageScope(el)) {
+    return { all: true, attributes: /* @__PURE__ */ new Set(), styleProps: /* @__PURE__ */ new Set(), children: false };
+  }
+  const raw = readAttr(el, "override");
+  const sup = emptySuppression();
+  if (raw === void 0) return sup;
+  const spec = raw.trim();
+  if (spec === "" || spec === "*") {
+    sup.all = true;
+    return sup;
+  }
+  parseFacetTokens(spec, sup);
+  return sup;
+}
+function parseContent(el) {
+  const raw = readAttr(el, CONTENT_MARKER);
+  const sup = emptySuppression();
+  if (raw === void 0) return sup;
+  const spec = raw.trim();
+  if (spec === "*") {
+    sup.all = true;
+    return sup;
+  }
+  if (spec === "") {
+    sup.children = true;
+    return sup;
+  }
+  parseFacetTokens(spec, sup);
+  return sup;
+}
+function unionSuppression(a, b) {
+  return {
+    all: a.all || b.all,
+    attributes: /* @__PURE__ */ new Set([...a.attributes, ...b.attributes]),
+    styleProps: /* @__PURE__ */ new Set([...a.styleProps, ...b.styleProps]),
+    children: a.children || b.children
+  };
 }
-async function findContractFiles(dir) {
-  return await glob(`${dir}/**/*${JAY_CONTRACT_EXTENSION}`);
+const BINDING = /\{[^}]*\}/g;
+function normalizeExpr(value) {
+  const bindingsCollapsed = value.replace(BINDING, (m) => m.replace(/\s+/g, ""));
+  return bindingsCollapsed.replace(/\s+/g, " ").trim();
+}
+function parseInlineStyle(style) {
+  const out = /* @__PURE__ */ new Map();
+  if (!style) return out;
+  for (const decl of splitDeclarations(style)) {
+    const idx = firstColon(decl);
+    if (idx < 0) continue;
+    const property = decl.slice(0, idx).trim().toLowerCase();
+    const value = decl.slice(idx + 1).trim();
+    if (property) out.set(property, value);
+  }
+  return out;
+}
+function serializeInlineStyle(decls) {
+  return [...decls].map(([property, value]) => `${property}: ${value}`).join("; ");
+}
+function splitDeclarations(style) {
+  const parts = [];
+  let depthParen = 0;
+  let depthBrace = 0;
+  let current = "";
+  for (const ch of style) {
+    if (ch === "(") depthParen++;
+    else if (ch === ")") depthParen = Math.max(0, depthParen - 1);
+    else if (ch === "{") depthBrace++;
+    else if (ch === "}") depthBrace = Math.max(0, depthBrace - 1);
+    if (ch === ";" && depthParen === 0 && depthBrace === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current);
+  return parts.filter((p) => p.trim());
+}
+function firstColon(decl) {
+  let depthParen = 0;
+  let depthBrace = 0;
+  for (let i = 0; i < decl.length; i++) {
+    const ch = decl[i];
+    if (ch === "(") depthParen++;
+    else if (ch === ")") depthParen = Math.max(0, depthParen - 1);
+    else if (ch === "{") depthBrace++;
+    else if (ch === "}") depthBrace = Math.max(0, depthBrace - 1);
+    else if (ch === ":" && depthParen === 0 && depthBrace === 0) return i;
+  }
+  return -1;
+}
+function diffBodies(sourceParent, regionParent) {
+  const out = [];
+  const ignoreClass = isRegionTag(regionParent) ? readAttr(regionParent, "ref") : void 0;
+  diffChildren([], sourceParent, regionParent, ignoreClass, out);
+  return out;
+}
+function diffChildren(parentPath, sParent, rParent, ignoreClass, out) {
+  const rSup = isElement(rParent) ? parseOverride(rParent) : NO_SUPPRESSION;
+  const sSup = isElement(sParent) ? parseContent(sParent) : NO_SUPPRESSION;
+  const sup = unionSuppression(rSup, sSup);
+  if (sup.all || sup.children) return;
+  const s2 = contentNodes(sParent);
+  const r = contentNodes(rParent);
+  if (!childrenAligned(s2, r)) {
+    const facet = { kind: "children", path: parentPath, element: tagOf(rParent) };
+    out.push({
+      facet,
+      change: "changed",
+      sourceValue: summarize(s2),
+      regionValue: summarize(r),
+      addedElementTags: addedElementTags(s2, r)
+    });
+    return;
+  }
+  for (let i = 0; i < r.length; i++) {
+    const rc = r[i];
+    if (rc.nodeType !== NodeType.ELEMENT_NODE) continue;
+    const re = rc;
+    if (isRegionTag(re)) continue;
+    const childIgnoreClass = parentPath.length === 0 ? ignoreClass : void 0;
+    diffElement([...parentPath, i], s2[i], re, childIgnoreClass, out);
+  }
+}
+function diffElement(path2, se, re, ignoreClass, out) {
+  const sup = unionSuppression(parseOverride(re), parseContent(se));
+  if (sup.all) return;
+  compareAttributes(path2, se, re, sup, ignoreClass, out);
+  compareStyle(path2, se, re, sup, out);
+  diffChildren(path2, se, re, void 0, out);
+}
+function compareAttributes(path2, se, re, sup, ignoreClass, out) {
+  const sm = attrMap(se);
+  const rm = attrMap(re);
+  const names = [.../* @__PURE__ */ new Set([...sm.keys(), ...rm.keys()])].sort();
+  for (const name of names) {
+    const sv = name === "class" ? stripClassToken(sm.get(name), ignoreClass) : sm.get(name);
+    const rv = name === "class" ? stripClassToken(rm.get(name), ignoreClass) : rm.get(name);
+    const change = scalarChange(sv, rv, (a, b) => normalizeExpr(a) === normalizeExpr(b));
+    if (!change) continue;
+    const facet = { kind: "attribute", path: path2, element: tagOf(re), name };
+    if (!sup.all && !sup.attributes.has(name))
+      out.push({ facet, change, sourceValue: sv, regionValue: rv });
+  }
+}
+function compareStyle(path2, se, re, sup, out) {
+  const sm = parseInlineStyle(se.getAttribute("style"));
+  const rm = parseInlineStyle(re.getAttribute("style"));
+  const props = [.../* @__PURE__ */ new Set([...sm.keys(), ...rm.keys()])].sort();
+  for (const property of props) {
+    const sv = sm.get(property);
+    const rv = rm.get(property);
+    const change = scalarChange(sv, rv, (a, b) => normalizeExpr(a) === normalizeExpr(b));
+    if (!change) continue;
+    const facet = { kind: "style-declaration", path: path2, element: tagOf(re), property };
+    if (!sup.all && !sup.styleProps.has(property))
+      out.push({ facet, change, sourceValue: sv, regionValue: rv });
+  }
+}
+function stripClassToken(value, token) {
+  if (value === void 0 || !token) return value;
+  const kept = value.split(/\s+/).filter((t) => t && t !== token);
+  return kept.length ? kept.join(" ") : void 0;
+}
+function scalarChange(sv, rv, equal) {
+  if (sv === void 0 && rv === void 0) return void 0;
+  if (sv === void 0) return "added";
+  if (rv === void 0) return "removed";
+  return equal(sv, rv) ? void 0 : "changed";
+}
+function attrMap(el) {
+  const map = /* @__PURE__ */ new Map();
+  const attrs = el.attributes;
+  for (const name of Object.keys(attrs)) {
+    const lower = name.toLowerCase();
+    if (isMetaAttr(lower) || lower === "style") continue;
+    map.set(lower, attrs[name] ?? "");
+  }
+  return map;
+}
+function contentNodes(parent) {
+  return parent.childNodes.filter((n) => {
+    if (n.nodeType === NodeType.TEXT_NODE) return normalizeExpr(nodeText(n)) !== "";
+    if (n.nodeType === NodeType.ELEMENT_NODE) return !isPageScope(n);
+    return false;
+  });
 }
-function flattenContractTags(tags, prefix) {
-  const result = [];
-  for (const tag of tags) {
-    const tagPath = prefix ? `${prefix}.${tag.tag}` : tag.tag;
-    result.push({ path: tagPath, required: tag.required === true });
-    if (tag.tags) {
-      result.push(...flattenContractTags(tag.tags, tagPath));
+function childrenAligned(s2, r) {
+  if (s2.length !== r.length) return false;
+  for (let i = 0; i < s2.length; i++) {
+    const sk = s2[i].nodeType;
+    const rk = r[i].nodeType;
+    if (sk !== rk) return false;
+    if (rk === NodeType.TEXT_NODE) {
+      if (normalizeExpr(nodeText(s2[i])) !== normalizeExpr(nodeText(r[i]))) return false;
+    } else {
+      if (tagOf(s2[i]).toLowerCase() !== tagOf(r[i]).toLowerCase()) return false;
+    }
+  }
+  return true;
+}
+function isElement(n) {
+  return n.nodeType === NodeType.ELEMENT_NODE;
+}
+function tagOf(n) {
+  return isElement(n) ? n.tagName ?? "(root)" : "(root)";
+}
+function nodeText(n) {
+  return n.rawText ?? n.text ?? "";
+}
+function addedElementTags(s2, r) {
+  const srcCounts = /* @__PURE__ */ new Map();
+  for (const n of s2)
+    if (n.nodeType === NodeType.ELEMENT_NODE) {
+      const t = tagOf(n).toLowerCase();
+      srcCounts.set(t, (srcCounts.get(t) ?? 0) + 1);
+    }
+  const added = [];
+  for (const n of r)
+    if (n.nodeType === NodeType.ELEMENT_NODE) {
+      const t = tagOf(n).toLowerCase();
+      const remaining = srcCounts.get(t) ?? 0;
+      if (remaining > 0) srcCounts.set(t, remaining - 1);
+      else added.push(t);
+    }
+  return added;
+}
+function summarize(nodes) {
+  return nodes.map(
+    (n) => n.nodeType === NodeType.ELEMENT_NODE ? `<${tagOf(n).toLowerCase()}>` : `"${normalizeExpr(nodeText(n))}"`
+  ).join("");
+}
+function diffCss(source, region) {
+  const s2 = buildUnits(source);
+  const r = buildUnits(region);
+  const out = [];
+  for (const key of [.../* @__PURE__ */ new Set([...s2.keys(), ...r.keys()])].sort()) {
+    const su = s2.get(key);
+    const ru = r.get(key);
+    if (su && !ru) {
+      out.push({
+        facet: { kind: "css-rule", selector: su.facetSelector },
+        change: "removed",
+        sourceValue: serialize(su)
+      });
+      continue;
+    }
+    if (!su && ru) {
+      if (ru.ruleOwned) continue;
+      out.push({
+        facet: { kind: "css-rule", selector: ru.facetSelector },
+        change: "added",
+        regionValue: serialize(ru)
+      });
+      continue;
+    }
+    if (!su || !ru) continue;
+    if (ru.ruleOwned) continue;
+    for (const property of [.../* @__PURE__ */ new Set([...su.decls.keys(), ...ru.decls.keys()])].sort()) {
+      const sv = su.decls.get(property);
+      const rv = ru.decls.get(property);
+      const change = declChange(sv, rv);
+      if (!change) continue;
+      if (ru.ownedProps.has(property)) continue;
+      out.push({
+        facet: { kind: "css-declaration", selector: ru.facetSelector, property },
+        change,
+        sourceValue: sv,
+        regionValue: rv
+      });
     }
   }
-  return result;
+  return out;
+}
+const OVERRIDE_RE = /^jay:override\s*(?::\s*([\w-]+))?\s*$/i;
+function buildUnits(css) {
+  const map = /* @__PURE__ */ new Map();
+  const root = postcss.parse(css);
+  root.walkRules((rule) => {
+    const scope = scopeOf(rule);
+    const decls = /* @__PURE__ */ new Map();
+    let ruleOwned = false;
+    const ownedProps = /* @__PURE__ */ new Set();
+    const applyComment = (text) => {
+      const m = text.trim().match(OVERRIDE_RE);
+      if (!m) return;
+      if (m[1]) ownedProps.add(m[1].toLowerCase());
+      else ruleOwned = true;
+    };
+    const prev = rule.prev();
+    if (prev?.type === "comment") applyComment(prev.text);
+    for (const node of rule.nodes ?? []) {
+      if (node.type === "decl") {
+        const decl = node;
+        decls.set(decl.prop.toLowerCase(), decl.value);
+      } else if (node.type === "comment") {
+        applyComment(node.text);
+      }
+    }
+    for (const selector of rule.selectors) {
+      const norm = normalizeExpr(selector);
+      if (!norm) continue;
+      const facetSelector = scope ? `${scope} ${norm}` : norm;
+      const key = `${scope}||${norm}`;
+      const existing = map.get(key);
+      if (existing) {
+        for (const [p, v] of decls) existing.decls.set(p, v);
+        existing.ruleOwned || (existing.ruleOwned = ruleOwned);
+        for (const p of ownedProps) existing.ownedProps.add(p);
+      } else {
+        map.set(key, {
+          scope,
+          selector: norm,
+          facetSelector,
+          decls: new Map(decls),
+          ruleOwned,
+          ownedProps: new Set(ownedProps)
+        });
+      }
+    }
+  });
+  return map;
 }
-function extractExpressions(text) {
-  const results = [];
-  const regex = /\{([^}]+)\}/g;
-  let match;
-  while ((match = regex.exec(text)) !== null) {
-    results.push(match[1].trim());
+function scopeOf(rule) {
+  const parts = [];
+  let node = rule.parent;
+  while (node) {
+    if (node.type === "atrule") {
+      const at = node;
+      if (at.name.toLowerCase() !== "scope") {
+        parts.unshift(`@${at.name} ${at.params}`.trim());
+      }
+    }
+    node = node.parent;
   }
-  return results;
+  return parts.join(" ");
 }
-function extractTagPath(expr) {
-  let cleaned = expr.replace(/^!/, "").trim();
-  cleaned = cleaned.split(/\s*[!=]==?\s*/)[0].trim();
-  if (cleaned === "." || cleaned === "") return null;
+function declChange(sv, rv) {
+  if (sv === void 0 && rv === void 0) return void 0;
+  if (sv === void 0) return "added";
+  if (rv === void 0) return "removed";
+  return normalizeExpr(sv) === normalizeExpr(rv) ? void 0 : "changed";
+}
+function serialize(u2) {
+  const body = [...u2.decls].map(([p, v]) => `${p}: ${v}`).join("; ");
+  return `${u2.selector} { ${body} }`;
+}
+function materialise(pageHtml, opts) {
+  const root = parse(pageHtml);
+  const errors = [];
+  const contributions = [];
+  fillRegions(root, [], opts, errors, contributions);
+  stripContentMarkers(root);
+  const serialized = root.toString();
+  return {
+    html: opts.prettify ? opts.prettify(serialized) : serialized,
+    css: coalesceCss(contributions),
+    errors
+  };
+}
+function coalesceCss(contributions) {
+  const groups = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const { key, selector, css, to } of contributions) {
+    if (selector === null) {
+      groups.push({ selectors: [], css });
+      continue;
+    }
+    const existing = byKey.get(key);
+    if (existing) {
+      if (!existing.selectors.includes(selector)) existing.selectors.push(selector);
+    } else {
+      const group = { selectors: [selector], css, to };
+      byKey.set(key, group);
+      groups.push(group);
+    }
+  }
+  return groups.map(
+    (g) => g.selectors.length > 0 ? scopeWrap(g.css, g.selectors.join(", "), g.to) : g.css
+  ).join("\n\n");
+}
+function fillRegions(container, stack, opts, errors, cssBlocks, parentScoped = false) {
+  for (const region of directRegions(container)) {
+    const name = contractName(region);
+    const templatePath = opts.resolveTemplate(name);
+    if (!templatePath) continue;
+    if (stack.includes(templatePath)) {
+      errors.push(
+        `template inclusion cycle: <jay:${name}> (${templatePath}) includes itself via ${[...stack, templatePath].join(" → ")}`
+      );
+      continue;
+    }
+    const template = opts.loadTemplate(templatePath);
+    if (!template) {
+      errors.push(
+        `cannot resolve template "${templatePath}" for <jay:${name}> — check the template= provenance`
+      );
+      continue;
+    }
+    const existing = region.innerHTML;
+    const filled = opts.preserveOverrides ? mergeOverrides(template.body, existing) : template.body;
+    region.set_content(filled);
+    const ref = readAttr(region, "ref");
+    let scoped = false;
+    if (template.css) {
+      const selector = (opts.scopeSelector ?? defaultScopeSelector)(region);
+      if (selector) {
+        scoped = true;
+        const to = [
+          ...new Set(
+            directRegions(region).filter((c) => opts.resolveTemplate(contractName(c)) !== null).map((c) => readAttr(c, "ref")).filter((r) => !!r).map((r) => `.${r}`)
+          )
+        ];
+        cssBlocks.push({
+          key: `${templatePath}\0${[...to].sort().join(",")}`,
+          selector,
+          css: scopeReadyCss(template.body, template.css),
+          to
+        });
+      } else {
+        cssBlocks.push({ key: templatePath, selector: null, css: template.css });
+      }
+    }
+    if (ref && (scoped || parentScoped)) stampScopeAnchor(region, ref);
+    fillRegions(region, [...stack, templatePath], opts, errors, cssBlocks, scoped);
+  }
+}
+function directRegions(container) {
+  const out = [];
+  const visit = (el) => {
+    for (const child of el.childNodes) {
+      if (!(child instanceof HTMLElement)) continue;
+      if (isRegionTag(child)) out.push(child);
+      else visit(child);
+    }
+  };
+  visit(container);
+  return out;
+}
+function contractName(region) {
+  return (region.tagName ?? "").slice("jay:".length).toLowerCase();
+}
+function defaultScopeSelector(region) {
+  const ref = readAttr(region, "ref");
+  return ref ? `.${ref}` : null;
+}
+function scopeWrap(css, selector, to) {
+  const limit = to && to.length ? ` to (${to.join(", ")})` : "";
+  return `@scope (${selector})${limit} {
+${css}
+}`;
+}
+function rootClassesOf(templateBody) {
+  const classes = /* @__PURE__ */ new Set();
+  for (const child of parse(templateBody).childNodes) {
+    if (child instanceof HTMLElement) {
+      for (const c of child.classList.values()) classes.add(c);
+    }
+  }
+  return classes;
+}
+function scopeReadyCss(templateBody, css) {
+  const rootClasses = rootClassesOf(templateBody);
+  if (rootClasses.size === 0) return css;
+  try {
+    const root = postcss.parse(css);
+    root.walkRules((rule) => {
+      rule.selectors = rule.selectors.map((sel) => rewriteRootSelector(sel, rootClasses));
+    });
+    return root.toString();
+  } catch {
+    return css;
+  }
+}
+function rewriteRootSelector(selector, rootClasses) {
+  return selector.replace(
+    /\.([A-Za-z0-9_-]+)/g,
+    (match, name) => rootClasses.has(name) ? ":scope" : match
+  );
+}
+function stampScopeAnchor(region, className) {
+  for (const child of region.childNodes) {
+    if (child instanceof HTMLElement) child.classList.add(className);
+  }
+}
+function mergeOverrides(templateBody, existingBody) {
+  const tRoot = parse(templateBody);
+  const eRoot = parse(existingBody);
+  mergeChildren(tRoot, eRoot);
+  stripContentMarkers(tRoot);
+  return tRoot.toString();
+}
+function stripContentMarkers(root) {
+  const visit = (el) => {
+    if (readAttr(el, CONTENT_MARKER) !== void 0) el.removeAttribute(CONTENT_MARKER);
+    for (const child of el.childNodes) if (child instanceof HTMLElement) visit(child);
+  };
+  visit(root);
+}
+function mergeChildren(tParent, eParent) {
+  const t = contentElements(tParent);
+  const e2 = contentElements(eParent);
+  if (!aligned(t, e2)) return;
+  for (let i = 0; i < t.length; i++) mergeElement(t[i], e2[i]);
+}
+function mergeElement(te, ee) {
+  if (isRegionTag(te)) {
+    te.set_content(ee.innerHTML);
+    return;
+  }
+  const sup = unionSuppression(parseOverride(ee), parseContent(te));
+  if (sup.all) {
+    te.replaceWith(ee.outerHTML);
+    return;
+  }
+  carryOwnedAttributes(te, ee, sup);
+  carryOwnedStyle(te, ee, sup);
+  carryMarkers(te, ee);
+  if (sup.children) {
+    te.set_content(ee.innerHTML);
+  } else {
+    mergeChildren(te, ee);
+  }
+}
+function carryOwnedAttributes(te, ee, sup) {
+  for (const name of sup.attributes) {
+    const v = readAttr(ee, name);
+    if (v === void 0) te.removeAttribute(name);
+    else te.setAttribute(name, v);
+  }
+}
+function carryOwnedStyle(te, ee, sup) {
+  if (sup.styleProps.size === 0) return;
+  const merged = parseInlineStyle(te.getAttribute("style"));
+  const pageStyle = parseInlineStyle(ee.getAttribute("style"));
+  for (const prop of sup.styleProps) {
+    const v = pageStyle.get(prop);
+    if (v === void 0) merged.delete(prop);
+    else merged.set(prop, v);
+  }
+  const serialized = serializeInlineStyle(merged);
+  if (serialized) te.setAttribute("style", serialized);
+  else te.removeAttribute("style");
+}
+function carryMarkers(te, ee) {
+  const override = readAttr(ee, "override");
+  if (override !== void 0) te.setAttribute("override", override);
+  if (isPageScope(ee)) te.setAttribute("page-scope", readAttr(ee, "page-scope") ?? "");
+}
+function contentElements(parent) {
+  return parent.childNodes.filter((n) => n instanceof HTMLElement);
+}
+function aligned(t, e2) {
+  if (t.length !== e2.length) return false;
+  for (let i = 0; i < t.length; i++) {
+    if ((t[i].tagName ?? "").toLowerCase() !== (e2[i].tagName ?? "").toLowerCase()) return false;
+  }
+  return true;
+}
+function buildMaterialiseOptions(pageDir, jayHtml, readFile, extra = {}) {
+  const nameToPath = /* @__PURE__ */ new Map();
+  for (const imp of jayHtml.headlessImports) {
+    if (imp.template) {
+      nameToPath.set(imp.contractName.toLowerCase(), path$1.resolve(pageDir, imp.template));
+    }
+  }
+  return {
+    resolveTemplate: (name) => nameToPath.get(name.toLowerCase()) ?? null,
+    loadTemplate: (absPath) => {
+      const content = readFile(absPath);
+      if (content === void 0) return null;
+      const root = parse(content);
+      const body = root.querySelector("body");
+      const styles = root.querySelectorAll("style");
+      const css = styles.map((s2) => s2.textContent).join("\n\n");
+      return {
+        body: body ? body.innerHTML : content,
+        css: css.trim() ? css : void 0
+      };
+    },
+    ...extra
+  };
+}
+function extractScopeBlock(css, selector) {
+  for (const { selectors, block } of splitScopeBlocks(css)) {
+    if (selectors.includes(selector)) return block;
+  }
+  return void 0;
+}
+function tokenizeCss(css) {
+  const out = [];
+  if (!css) return out;
+  const header = /@scope\s*\(\s*([^)]+?)\s*\)(?:\s*to\s*\(\s*([^)]+?)\s*\))?\s*\{/g;
+  let last = 0;
+  let m;
+  while ((m = header.exec(css)) !== null) {
+    let depth = 0;
+    let end = -1;
+    for (let i = m.index + m[0].length - 1; i < css.length; i++) {
+      const ch = css[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) {
+          end = i + 1;
+          break;
+        }
+      }
+    }
+    if (end === -1) break;
+    if (m.index > last) out.push({ type: "raw", text: css.slice(last, m.index) });
+    const selector = m[1];
+    const selectors = selector.split(",").map((s2) => s2.trim()).filter(Boolean);
+    const to = (m[2] ?? "").split(",").map((s2) => s2.trim()).filter(Boolean);
+    out.push({ type: "scope", selector, selectors, to, block: css.slice(m.index, end) });
+    last = end;
+    header.lastIndex = end;
+  }
+  if (last < css.length) out.push({ type: "raw", text: css.slice(last) });
+  return out;
+}
+function splitScopeBlocks(css) {
+  return tokenizeCss(css).filter((s2) => s2.type === "scope").map(({ selector, selectors, to, block }) => ({ selector, selectors, to, block }));
+}
+function scopeInnerBody(block) {
+  return block.replace(/^@scope\s*\([^)]*\)(?:\s*to\s*\([^)]*\))?\s*\{/, "").replace(/\}\s*$/, "");
+}
+function normalizeCssBody(body) {
+  return body.replace(/\s+/g, " ").replace(/\s*([{}:;,])\s*/g, "$1").replace(/;}/g, "}").trim();
+}
+async function findJayFiles(dir) {
+  return await glob(`${dir}/**/*${JAY_EXTENSION$1}`);
+}
+async function findContractFiles(dir) {
+  return await glob(`${dir}/**/*${JAY_CONTRACT_EXTENSION$1}`);
+}
+function flattenContractTags(tags, prefix) {
+  const result = [];
+  for (const tag of tags) {
+    const tagPath = prefix ? `${prefix}.${tag.tag}` : tag.tag;
+    result.push({ path: tagPath, required: tag.required === true });
+    if (tag.tags) {
+      result.push(...flattenContractTags(tag.tags, tagPath));
+    }
+  }
+  return result;
+}
+function extractExpressions(text) {
+  const results = [];
+  const regex = /\{([^}]+)\}/g;
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    results.push(match[1].trim());
+  }
+  return results;
+}
+function extractTagPath(expr) {
+  let cleaned = expr.replace(/^!/, "").trim();
+  cleaned = cleaned.split(/\s*[!=]==?\s*/)[0].trim();
+  if (cleaned === "." || cleaned === "") return null;
   if (/^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*)*$/.test(cleaned)) {
     return cleaned;
   }
@@ -4038,9 +4870,9 @@ function collectUsedTags(jayHtml) {
     const tagName = element.rawTagName?.toLowerCase();
     let childScopes = scopes;
     if (tagName?.startsWith("jay:")) {
-      const contractName = tagName.substring(4);
+      const contractName2 = tagName.substring(4);
       const idx = imports.findIndex(
-        (imp) => imp.contractName === contractName && imp.contract
+        (imp) => imp.contractName === contractName2 && imp.contract
       );
       if (idx !== -1) {
         childScopes = [...scopes, { importIndex: idx, prefix: "" }];
@@ -4204,9 +5036,9 @@ function checkRefElementTypes(jayHtml, file) {
     const tagName = element.rawTagName?.toLowerCase();
     let childScopes = scopes;
     if (tagName?.startsWith("jay:")) {
-      const contractName = tagName.substring(4);
+      const contractName2 = tagName.substring(4);
       const idx = imports.findIndex(
-        (imp) => imp.contractName === contractName && imp.contract
+        (imp) => imp.contractName === contractName2 && imp.contract
       );
       if (idx !== -1) {
         childScopes = [...scopes, { importIndex: idx, prefix: "" }];
@@ -4292,7 +5124,7 @@ const DOCUMENT_ACCESS_PATTERNS = [
 const DOM_SUPPRESS_COMMENT = "jay-dom: allow";
 function checkDirectDocumentAccess(jayHtmlPath) {
   const dirname = path$1.dirname(jayHtmlPath);
-  const basename = path$1.basename(jayHtmlPath, JAY_EXTENSION);
+  const basename = path$1.basename(jayHtmlPath, JAY_EXTENSION$1);
   const candidates = [path$1.join(dirname, `${basename}.ts`), path$1.join(dirname, "page.ts")];
   const compPath = candidates.find((p) => fs$1.existsSync(p));
   if (!compPath) return [];
@@ -4418,39 +5250,410 @@ const HEADLESS_SKIP_ATTRS = /* @__PURE__ */ new Set([
   "props",
   "key",
   "jay-coordinate-base",
-  "jay-scope"
+  "jay-scope",
+  "jc"
+  // component-provenance marker stamped on a flattened <jay:X> region (DL#196)
 ]);
 const PHASE_ORDER = {
   slow: 0,
   fast: 1,
   "fast+interactive": 2
 };
-function resolveBindingPhase(bindingPath, jayHtml) {
+function resolveBindingTag(bindingPath, jayHtml) {
   const segments = bindingPath.split(".");
   const root = segments[0];
   const keyedImport = jayHtml.headlessImports.find((i) => i.key === root && i.contract);
   if (keyedImport?.contract) {
     const tagPath = segments.slice(1).join(".");
     if (!tagPath) return void 0;
-    const tag = resolveContractTag(keyedImport.contract, tagPath);
-    if (!tag) return void 0;
-    return tag.phase || "slow";
+    return resolveContractTag(keyedImport.contract, tagPath);
   }
   if (jayHtml.contract) {
-    const tag = resolveContractTag(jayHtml.contract, bindingPath);
-    if (!tag) return void 0;
-    return tag.phase || "slow";
+    return resolveContractTag(jayHtml.contract, bindingPath);
   }
   return void 0;
 }
+function resolveBindingPhase(bindingPath, jayHtml) {
+  const tag = resolveBindingTag(bindingPath, jayHtml);
+  return tag ? tag.phase || "slow" : void 0;
+}
+function resolveBindingDataType(bindingPath, jayHtml) {
+  return resolveBindingTag(bindingPath, jayHtml)?.dataType;
+}
+function typeLabel(t) {
+  return isEnumType$1(t) ? `enum(${t.values.join(" | ")})` : t.name;
+}
+function collectRegionElements(root) {
+  const out = [];
+  const visit = (el) => {
+    for (const child of el.childNodes) {
+      if (child.nodeType !== NodeType.ELEMENT_NODE) continue;
+      const childEl = child;
+      if (isRegionTag(childEl)) out.push(childEl);
+      visit(childEl);
+    }
+  };
+  visit(root);
+  return out;
+}
+function directChildRegions(region) {
+  const out = [];
+  const visit = (el) => {
+    for (const child of el.childNodes) {
+      if (child.nodeType !== NodeType.ELEMENT_NODE) continue;
+      const childEl = child;
+      if (isRegionTag(childEl)) out.push(childEl);
+      else visit(childEl);
+    }
+  };
+  visit(region);
+  return out;
+}
+function formatRegionDrift(contractName2, template, entry) {
+  const label = facetLabel(entry.facet);
+  const values = entry.change === "added" ? ` (now ${entry.regionValue ?? ""})` : entry.change === "removed" ? ` (was ${entry.sourceValue ?? ""})` : ` (${entry.sourceValue ?? ""} → ${entry.regionValue ?? ""})`;
+  const spec = overrideSpecFor(entry.facet);
+  const mark = spec.target === "markup-attribute" ? `mark the node override="${spec.value}"` : spec.value ? `mark the CSS rule /* jay:override: ${spec.value} */` : "mark the CSS rule /* jay:override */";
+  const contentSlotHint = entry.facet.kind === "children" ? ` Or, if these children are a content slot, mark the node jay-content in the template "${template}" so consumer edits are expected.` : "";
+  return {
+    message: `<jay:${contractName2}> region differs from source template "${template}": ${label} ${entry.change}${values}.`,
+    suggestion: `To keep the page's version, ${mark}; to discard it and re-flatten from source, run \`jay-stack sync\`.${contentSlotHint}`
+  };
+}
+function checkRegionDrift(jayHtml, loadTemplate) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const warnings = [];
+  const templateBodyCache = /* @__PURE__ */ new Map();
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    let templateBody = templateBodyCache.get(imp.template);
+    if (templateBody === void 0) {
+      const content = loadTemplate(imp.template);
+      templateBody = (content ? parse(content).querySelector("body") : null) ?? null;
+      templateBodyCache.set(imp.template, templateBody);
+      if (!templateBody) {
+        warnings.push({
+          message: `<jay:${contractName2}> declares template="${imp.template}" but its source template could not be read.`,
+          suggestion: "Fix the path or remove the attribute."
+        });
+      }
+    }
+    if (!templateBody) continue;
+    for (const entry of diffBodies(templateBody, region)) {
+      warnings.push(formatRegionDrift(contractName2, imp.template, entry));
+    }
+  }
+  return warnings;
+}
+function extractStyleCss(templateHtml) {
+  return parse(templateHtml).querySelectorAll("style").map((s2) => s2.textContent).join("\n\n");
+}
+function checkRegionCssDrift(jayHtml, loadTemplate) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const pageCss = jayHtml.css ?? "";
+  const warnings = [];
+  const templateCssCache = /* @__PURE__ */ new Map();
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    const ref = region.getAttribute("ref");
+    if (!ref) continue;
+    let templateCss = templateCssCache.get(imp.template);
+    if (templateCss === void 0) {
+      const content = loadTemplate(imp.template);
+      if (content === void 0) {
+        templateCss = null;
+      } else {
+        const body = parse(content).querySelector("body");
+        templateCss = scopeReadyCss(body ? body.innerHTML : "", extractStyleCss(content));
+      }
+      templateCssCache.set(imp.template, templateCss);
+    }
+    if (templateCss === null) continue;
+    const pageBlock = extractScopeBlock(pageCss, `.${ref}`) ?? "";
+    if (!templateCss.trim() && !pageBlock.trim()) continue;
+    if (templateCss.trim() && !pageBlock.trim()) {
+      warnings.push({
+        message: `<jay:${contractName2}> (template="${imp.template}") has no @scope (.${ref}) CSS block on the page, but its source template ships CSS.`,
+        suggestion: "Run jay-stack sync to re-flatten the region CSS."
+      });
+      continue;
+    }
+    for (const entry of diffCss(templateCss, pageBlock)) {
+      warnings.push(formatRegionDrift(contractName2, imp.template, entry));
+    }
+  }
+  return warnings;
+}
+function checkRegionCssScoping(jayHtml) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const pageCss = jayHtml.css ?? "";
+  if (!pageCss.trim()) return [];
+  const templateOf = /* @__PURE__ */ new Map();
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    const ref = region.getAttribute("ref");
+    if (imp?.template && ref) templateOf.set(`.${ref}`, imp.template);
+  }
+  const warnings = [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const { selectors, to, block } of splitScopeBlocks(pageCss)) {
+    const known = selectors.filter((s2) => templateOf.has(s2));
+    if (known.length === 0) continue;
+    const templates = [...new Set(known.map((s2) => templateOf.get(s2)))];
+    if (templates.length > 1) {
+      warnings.push({
+        message: `A single @scope (${selectors.join(", ")}) block mixes refs from different source templates (${templates.join(", ")}); each region's CSS must be scoped to its own template.`,
+        suggestion: "Run jay-stack sync to re-flatten the region CSS."
+      });
+      continue;
+    }
+    const key = `${templates[0]}\0${scopeBody(block)}\0${[...to].sort().join(",")}`;
+    (groups.get(key) ?? groups.set(key, []).get(key)).push(selectors.join(", "));
+  }
+  for (const [key, blockSelectors] of groups) {
+    if (blockSelectors.length < 2) continue;
+    const template = key.split("\0")[0];
+    warnings.push({
+      message: `${blockSelectors.length} @scope blocks (${blockSelectors.join(" ; ")}) share template "${template}" and identical CSS but are not coalesced into one selector-list block.`,
+      suggestion: "Run jay-stack sync to coalesce the region CSS."
+    });
+  }
+  return warnings;
+}
+function checkNestedRegionRefs(jayHtml, loadTemplate) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const warnings = [];
+  const shipsCssCache = /* @__PURE__ */ new Map();
+  const templateShipsCss = (rel) => {
+    let v = shipsCssCache.get(rel);
+    if (v === void 0) {
+      const content = loadTemplate(rel);
+      v = content !== void 0 && extractStyleCss(content).trim() !== "";
+      shipsCssCache.set(rel, v);
+    }
+    return v;
+  };
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = (region.rawTagName ?? "").toLowerCase().substring(4);
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    const parentRef = region.getAttribute("ref");
+    if (!parentRef) continue;
+    if (!templateShipsCss(imp.template)) continue;
+    for (const child of directChildRegions(region)) {
+      const childName = (child.rawTagName ?? "").toLowerCase().substring(4);
+      const childImp = importsWithTemplate.find((i) => i.contractName === childName);
+      if (!childImp?.template) continue;
+      if (child.getAttribute("ref")) continue;
+      warnings.push({
+        message: `<jay:${childName}> is nested inside <jay:${contractName2}> (template="${imp.template}"), whose CSS is scoped as an @scope (.${parentRef}) donut, but <jay:${childName}> has no ref= — so its region cannot be isolated from the parent's styles.`,
+        suggestion: `Add a ref= to the <jay:${childName}> in template "${imp.template}" so sync can stamp its scope-anchor class and emit the \`to (.<ref>)\` boundary.`
+      });
+    }
+  }
+  return warnings;
+}
+const CONTENT_TAGS = /* @__PURE__ */ new Set([
+  // inline text semantics
+  "span",
+  "strong",
+  "b",
+  "em",
+  "i",
+  "u",
+  "s",
+  "small",
+  "mark",
+  "sub",
+  "sup",
+  "abbr",
+  "cite",
+  "q",
+  "code",
+  "kbd",
+  "samp",
+  "var",
+  "del",
+  "ins",
+  "time",
+  "data",
+  "bdi",
+  "bdo",
+  "ruby",
+  "rt",
+  "rp",
+  // links & line breaks
+  "a",
+  "br",
+  "wbr",
+  // media (content, not layout)
+  "img",
+  "picture",
+  "source",
+  "svg",
+  "use",
+  "path",
+  "icon",
+  "figure",
+  "figcaption",
+  "audio",
+  "video",
+  // lists
+  "ul",
+  "ol",
+  "li",
+  "dl",
+  "dt",
+  "dd",
+  // tables
+  "table",
+  "thead",
+  "tbody",
+  "tfoot",
+  "tr",
+  "td",
+  "th",
+  "caption",
+  "colgroup",
+  "col",
+  // text blocks & headings
+  "p",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "blockquote",
+  "pre",
+  "hr",
+  // form labels/copy (not controls, which imply structure)
+  "label"
+]);
+function isNonContentOverride(entry, contentTags) {
+  switch (entry.facet.kind) {
+    case "style-declaration":
+    case "css-rule":
+    case "css-declaration":
+      return true;
+    case "attribute":
+      return entry.facet.name.toLowerCase() === "class";
+    case "children":
+      return (entry.addedElementTags ?? []).some((tag) => !contentTags.has(tag));
+  }
+}
+function regionContractName(region) {
+  return (region.rawTagName ?? "").toLowerCase().substring(4);
+}
+function isRegionRuleSuppressed(imp, jayHtml, ruleId) {
+  if (imp?.suppressedValidations?.includes(ruleId)) return true;
+  if (ruleId === "REGION-NOT-LINKED" && imp) {
+    const allow = jayHtml.validationOverrides?.["jay-stack"]?.["allow-inline-region"];
+    const list = Array.isArray(allow) ? allow.map((v) => String(v).toLowerCase()) : [];
+    if (list.includes(imp.contractName.toLowerCase())) return true;
+  }
+  return false;
+}
+function checkRegionNotLinked(jayHtml, templatesFor) {
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = regionContractName(region);
+    if (seen.has(contractName2)) continue;
+    const imp = jayHtml.headlessImports.find((i) => i.contractName === contractName2);
+    if (!imp) continue;
+    if (imp.key || imp.template) continue;
+    const templates = templatesFor(imp);
+    if (templates.length === 0) continue;
+    if (isRegionRuleSuppressed(imp, jayHtml, "REGION-NOT-LINKED")) continue;
+    seen.add(contractName2);
+    const templateHint = templates.length === 1 ? `template="${templates[0].path}"` : `template= one of: ${templates.map((t) => `"${t.path}"`).join(", ")}`;
+    findings.push({
+      message: `<jay:${contractName2}> is hand-authored, but a design-system template exists for contract "${imp.contractName}". Prefer linking it as a design-system element.`,
+      suggestion: `Add ${templateHint} to the <script type="application/jay-headless"> import and run \`jay-stack sync\`. For a deliberate one-off, suppress on the import with jay-validations="REGION-NOT-LINKED" (or list the contract under allow-inline-region in <script type="application/jay-validations">). See agent-kit/designer/design-system-guide.md.`
+    });
+  }
+  return findings;
+}
+function checkRegionOverrideNonContent(jayHtml, loadTemplate, contentTags = CONTENT_TAGS) {
+  const importsWithTemplate = jayHtml.headlessImports.filter((imp) => imp.template);
+  if (importsWithTemplate.length === 0) return [];
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  const templateBodyCache = /* @__PURE__ */ new Map();
+  for (const region of collectRegionElements(jayHtml.body)) {
+    const contractName2 = regionContractName(region);
+    if (seen.has(contractName2)) continue;
+    const imp = importsWithTemplate.find((i) => i.contractName === contractName2);
+    if (!imp?.template) continue;
+    if (isRegionRuleSuppressed(imp, jayHtml, "REGION-OVERRIDE-NON-CONTENT")) continue;
+    let templateBody = templateBodyCache.get(imp.template);
+    if (templateBody === void 0) {
+      const content = loadTemplate(imp.template);
+      templateBody = (content ? parse(content).querySelector("body") : null) ?? null;
+      templateBodyCache.set(imp.template, templateBody);
+    }
+    if (!templateBody) continue;
+    const hasNonContent = diffBodies(templateBody, region).some(
+      (entry) => isNonContentOverride(entry, contentTags)
+    );
+    if (!hasNonContent) continue;
+    seen.add(contractName2);
+    findings.push({
+      message: `<jay:${contractName2}> changes its design-system template's look or structure (style, class, or net-new layout DOM) — that is a different design, not a content tweak.`,
+      suggestion: `Prefer a second design-system template (a new variant) for contract "${imp.contractName}" and link this region to it. Editing text/images, or enriching text with inline markup, is fine; use conditionals only for runtime state changes, not for a different design. To accept this override, suppress on the import with jay-validations="REGION-OVERRIDE-NON-CONTENT". See agent-kit/designer/design-system-guide.md.`
+    });
+  }
+  return findings;
+}
+function checkComponentNoTemplate(contractFile, contractName2, hasTemplate, allowNoTemplate) {
+  if (hasTemplate(contractFile)) return void 0;
+  const base = path$1.basename(contractFile, JAY_CONTRACT_EXTENSION$1).toLowerCase();
+  if (allowNoTemplate.has(contractName2.toLowerCase()) || allowNoTemplate.has(base))
+    return void 0;
+  return {
+    message: `Component "${contractName2}" ships no .jay-html template. If it renders UI, create a reusable design-system template so consumers flatten it (template= + jay-stack sync) instead of hand-authoring each usage.`,
+    suggestion: `Author a ${base}.jay-html next to the contract. If this component is intentionally UI-less (data/logic only), suppress project-wide with allow-no-template: ["${contractName2}"] in <script type="application/jay-validations">. See agent-kit/designer/design-system-guide.md.`
+  };
+}
+function checkNoDesignSystem(regionsSeen, templateImportsSeen, suppressed) {
+  if (suppressed || templateImportsSeen > 0) return void 0;
+  if (regionsSeen > 0) {
+    return {
+      message: "This project composes components but none are design-system elements (no template= imports). Ship a .jay-html template with a reused component and flatten it so pages share consistent, upgradable UI.",
+      suggestion: 'Add template= to a headless import and run `jay-stack sync`. Suppress project-wide with allow-no-design-system: true in <script type="application/jay-validations">. See agent-kit/designer/design-system-guide.md.'
+    };
+  }
+  return {
+    message: "This project shares no UI through design-system elements. Consider composing reusable sections as components with .jay-html templates — regions can be used without code, purely to flatten and share a design system.",
+    suggestion: 'See agent-kit/designer/design-system-guide.md. Suppress project-wide with allow-no-design-system: true in <script type="application/jay-validations">.'
+  };
+}
+function scopeBody(block) {
+  return block.replace(/^@scope\s*\([^)]*\)(?:\s*to\s*\([^)]*\))?\s*\{/, "").replace(/\}\s*$/, "").replace(/\s+/g, " ").trim();
+}
+function checkRegionRecursion(pageHtml, pageDir, jayHtml, readFile) {
+  if (!jayHtml.headlessImports.some((imp) => imp.template)) return [];
+  const { errors } = materialise(pageHtml, buildMaterialiseOptions(pageDir, jayHtml, readFile));
+  return errors.filter((e2) => e2.startsWith("template inclusion cycle"));
+}
 function checkHeadlessInstanceProps(jayHtml, file) {
   const imports = jayHtml.headlessImports;
   const warnings = [];
   function walkElement(element) {
     const tagName = element.rawTagName?.toLowerCase();
     if (tagName?.startsWith("jay:")) {
-      const contractName = tagName.substring(4);
-      const imp = imports.find((i) => i.contractName === contractName && i.contract);
+      const contractName2 = tagName.substring(4);
+      const imp = imports.find((i) => i.contractName === contractName2 && i.contract);
       if (imp?.contract) {
         const contract = imp.contract;
         const attrs = element.attributes ?? {};
@@ -4467,7 +5670,7 @@ function checkHeadlessInstanceProps(jayHtml, file) {
           for (const prop of passedProps) {
             if (!contractPropNamesLower.has(prop.toLowerCase())) {
               warnings.push(
-                `<jay:${contractName}> passes attribute "${prop}" but the "${contract.name}" contract does not declare it as a prop. Add to ${contractName}.jay-contract: props: [{ name: ${prop}, type: string }]`
+                `<jay:${contractName2}> passes attribute "${prop}" but the "${contract.name}" contract does not declare it as a prop. Add to ${contractName2}.jay-contract: props: [{ name: ${prop}, type: string }]`
               );
             }
           }
@@ -4477,7 +5680,7 @@ function checkHeadlessInstanceProps(jayHtml, file) {
           for (const contractProp of contract.props) {
             if (contractProp.required && !passedPropsLower.has(contractProp.name.toLowerCase())) {
               warnings.push(
-                `<jay:${contractName}> is missing required prop "${contractProp.name}" declared in the "${contract.name}" contract.`
+                `<jay:${contractName2}> is missing required prop "${contractProp.name}" declared in the "${contract.name}" contract.`
               );
             }
           }
@@ -4489,18 +5692,35 @@ function checkHeadlessInstanceProps(jayHtml, file) {
           }
           for (const contractProp of contract.props) {
             const attrValue = lowerAttrs[contractProp.name.toLowerCase()];
-            if (!attrValue) continue;
+            if (attrValue === void 0) continue;
+            const propType = contractProp.dataType;
             const bindingMatch = attrValue.match(/^\{(.+)\}$/);
-            if (!bindingMatch) continue;
+            if (!bindingMatch) {
+              if (attrValue.includes("{")) continue;
+              if (propType && isEnumType$1(propType)) {
+                if (!propType.values.includes(attrValue)) {
+                  warnings.push(
+                    `<jay:${contractName2}> prop "${contractProp.name}" = "${attrValue}" is not a declared value of enum(${propType.values.join(" | ")}). Use one of: ${propType.values.join(", ")}.`
+                  );
+                }
+              }
+              continue;
+            }
             const bindingPath = bindingMatch[1];
+            const sourceType = resolveBindingDataType(bindingPath, jayHtml);
+            if (propType && sourceType && !equalJayTypes(propType, sourceType)) {
+              warnings.push(
+                `<jay:${contractName2}> prop "${contractProp.name}" (${typeLabel(propType)}) is bound to {${bindingPath}} (${typeLabel(sourceType)}). The binding source type must match the prop type.`
+              );
+            }
             const sourcePhase = resolveBindingPhase(bindingPath, jayHtml);
             if (!sourcePhase) continue;
-            const propPhase = contractProp.phase ?? "slow";
+            const propPhase = imp.structural ? resolveContractTag(contract, contractProp.name)?.phase ?? contractProp.phase ?? "slow" : contractProp.phase ?? "slow";
             const sourceOrder = PHASE_ORDER[sourcePhase] ?? 0;
             const propOrder = PHASE_ORDER[propPhase] ?? 0;
             if (sourceOrder > propOrder) {
               warnings.push(
-                `<jay:${contractName}> prop "${contractProp.name}" (phase: ${propPhase}) is bound to {${bindingPath}} which is phase: ${sourcePhase}. The binding source phase must be ≤ the prop phase. Use a ${propPhase}-phase binding, a route param, or a literal value.`
+                `<jay:${contractName2}> prop "${contractProp.name}" (phase: ${propPhase}) is bound to {${bindingPath}} which is phase: ${sourcePhase}. The binding source phase must be ≤ the prop phase. Use a ${propPhase}-phase binding, a route param, or a literal value.`
               );
             }
           }
@@ -4666,13 +5886,17 @@ async function validateJayFiles(options = {}) {
   const warnings = [];
   const coverage = [];
   const parsedFiles = [];
+  let regionsSeen = 0;
+  let templateImportsSeen = 0;
   const pageJayHtmlFiles = await findJayFiles(scanDir);
   const componentJayHtmlFiles = await findJayFiles(componentsDir).catch(() => []);
   const jayHtmlFiles = [...pageJayHtmlFiles, ...componentJayHtmlFiles];
-  const contractFiles = [
-    ...await findContractFiles(scanDir),
-    ...await findContractFiles(componentsDir).catch(() => [])
-  ];
+  const componentJayHtmlFileSet = new Set(componentJayHtmlFiles);
+  const componentContractFiles = await findContractFiles(componentsDir).catch(
+    () => []
+  );
+  const contractFiles = [...await findContractFiles(scanDir), ...componentContractFiles];
+  const contractNameByFile = /* @__PURE__ */ new Map();
   if (options.verbose) {
     getLogger().info(chalk.gray(`Scanning directory: ${scanDir}`));
     getLogger().info(chalk.gray(`Found ${jayHtmlFiles.length} .jay-html files`));
@@ -4684,6 +5908,7 @@ async function validateJayFiles(options = {}) {
     try {
       const content = await promises.readFile(contractFile, "utf-8");
       const result = parseContract(content, path$1.basename(contractFile));
+      if (result.val?.name) contractNameByFile.set(contractFile, result.val.name);
       if (result.validations.length > 0) {
         for (const validation of result.validations) {
           errors.push({
@@ -4711,7 +5936,7 @@ async function validateJayFiles(options = {}) {
   }
   for (const jayFile of jayHtmlFiles) {
     const relativePath = path$1.relative(projectRoot, jayFile);
-    const filename = path$1.basename(jayFile.replace(JAY_EXTENSION, ""));
+    const filename = path$1.basename(jayFile.replace(JAY_EXTENSION$1, ""));
     const dirname = path$1.dirname(jayFile);
     try {
       const content = await promises.readFile(jayFile, "utf-8");
@@ -4774,12 +5999,95 @@ async function validateJayFiles(options = {}) {
       }
       const headlessPropResults = checkHeadlessInstanceProps(parsedFile.val, relativePath);
       for (const msg of headlessPropResults) {
-        if (msg.includes("is missing required prop") || msg.includes("source phase must be")) {
+        if (msg.includes("is missing required prop") || msg.includes("source phase must be") || msg.includes("is not a declared value of enum") || msg.includes("binding source type must match")) {
           errors.push({ file: relativePath, message: msg, stage: "generate" });
         } else {
           warnings.push({ file: relativePath, message: msg });
         }
       }
+      const readTemplateRel = (templatePath) => {
+        try {
+          return fs$1.readFileSync(path$1.resolve(dirname, templatePath), "utf-8");
+        } catch {
+          return void 0;
+        }
+      };
+      const driftWarnings = checkRegionDrift(parsedFile.val, readTemplateRel);
+      for (const finding of driftWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      const cssDriftWarnings = checkRegionCssDrift(parsedFile.val, readTemplateRel);
+      for (const finding of cssDriftWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      const cssScopingWarnings = checkRegionCssScoping(parsedFile.val);
+      for (const finding of cssScopingWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      const nestedRefWarnings = checkNestedRegionRefs(parsedFile.val, readTemplateRel);
+      for (const finding of nestedRefWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      regionsSeen += collectRegionElements(parsedFile.val.body).length;
+      templateImportsSeen += parsedFile.val.headlessImports.filter(
+        (imp) => imp.template
+      ).length;
+      const notLinkedWarnings = componentJayHtmlFileSet.has(jayFile) ? [] : checkRegionNotLinked(
+        parsedFile.val,
+        (imp) => listTemplatesForContractFile(imp.contractPath).map((t) => ({
+          ...t,
+          path: "./" + path$1.relative(projectRoot, t.path).replace(/\\/g, "/")
+        }))
+      );
+      for (const finding of notLinkedWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      const overrideWarnings = checkRegionOverrideNonContent(
+        parsedFile.val,
+        readTemplateRel
+      );
+      for (const finding of overrideWarnings) {
+        warnings.push({
+          file: relativePath,
+          message: finding.message,
+          suggestion: finding.suggestion
+        });
+      }
+      const recursionErrors = checkRegionRecursion(
+        content,
+        dirname,
+        parsedFile.val,
+        (absPath) => {
+          try {
+            return fs$1.readFileSync(absPath, "utf-8");
+          } catch {
+            return void 0;
+          }
+        }
+      );
+      for (const msg of recursionErrors) {
+        errors.push({ file: relativePath, message: msg, stage: "generate" });
+      }
       const fileCoverage = analyzeTagCoverage(parsedFile.val, relativePath);
       if (fileCoverage) {
         coverage.push(fileCoverage);
@@ -4852,6 +6160,44 @@ async function validateJayFiles(options = {}) {
       suggestion: "Add to .jay config:\n  site:\n    baseUrl: https://your-domain.com"
     });
   }
+  const allowNoTemplate = /* @__PURE__ */ new Set();
+  let allowNoDesignSystem = false;
+  for (const { parsed } of parsedFiles) {
+    const overrides = parsed.validationOverrides?.["jay-stack"];
+    if (!overrides) continue;
+    const list = overrides["allow-no-template"];
+    if (Array.isArray(list))
+      for (const name of list) allowNoTemplate.add(String(name).toLowerCase());
+    if (overrides["allow-no-design-system"] === true) allowNoDesignSystem = true;
+  }
+  for (const contractFile of componentContractFiles) {
+    const contractName2 = contractNameByFile.get(contractFile) ?? path$1.basename(contractFile, JAY_CONTRACT_EXTENSION$1);
+    const finding = checkComponentNoTemplate(
+      contractFile,
+      contractName2,
+      hasTemplateForContractFile,
+      allowNoTemplate
+    );
+    if (finding) {
+      warnings.push({
+        file: path$1.relative(projectRoot, contractFile),
+        message: finding.message,
+        suggestion: finding.suggestion
+      });
+    }
+  }
+  const noDesignSystem = checkNoDesignSystem(
+    regionsSeen,
+    templateImportsSeen,
+    allowNoDesignSystem
+  );
+  if (noDesignSystem) {
+    warnings.push({
+      file: ".jay",
+      message: noDesignSystem.message,
+      suggestion: noDesignSystem.suggestion
+    });
+  }
   const pluginValidators = await runPluginValidators(projectRoot, parsedFiles, errors, warnings);
   return {
     valid: errors.length === 0,
@@ -4988,6 +6334,20 @@ async function runValidate(scanPath, options) {
     process.exit(1);
   }
 }
+async function surfaceValidationIssues(projectPath, options) {
+  let result;
+  try {
+    result = await validateJayFiles({ path: projectPath, verbose: options.verbose });
+  } catch (error) {
+    getLogger().warn(chalk.yellow(`Skipped jay-html validation: ${error?.message ?? error}`));
+    return true;
+  }
+  if (!result.valid) {
+    printJayValidationResult(result, { verbose: options.verbose });
+    return false;
+  }
+  return true;
+}
 async function runValidatePlugin(pluginPath, options) {
   const result = await validatePlugin({
     pluginPath: pluginPath || process.cwd(),
@@ -5048,6 +6408,334 @@ function printPluginValidationResult(result, verbose) {
     logger.important(chalk.red(`${result.errors.length} errors found.`));
   }
 }
+const runValidate$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  runValidate,
+  runValidatePlugin,
+  surfaceValidationIssues
+}, Symbol.toStringTag, { value: "Module" }));
+async function runDev(projectPath, options) {
+  const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
+  setDevLogger(createDevLogger(logLevel));
+  if (!options.quiet) {
+    await surfaceValidationIssues(projectPath, { verbose: options.verbose });
+  }
+  const testMode = options.testMode || options.timeout !== void 0;
+  await startDevServer({
+    projectPath: projectPath || process.cwd(),
+    testMode,
+    timeout: options.timeout,
+    logLevel
+  });
+}
+async function resolveProductionContext(projectPath, versionOverride) {
+  const resolvedPath = path__default.resolve(projectPath || process.cwd());
+  const jayConfigPath = path__default.join(resolvedPath, ".jay");
+  let pagesBase = "./src/pages";
+  let siteBaseUrl;
+  try {
+    const jayConfig = YAML.parse(await fs$2.readFile(jayConfigPath, "utf-8"));
+    pagesBase = jayConfig?.devServer?.pagesBase || pagesBase;
+    siteBaseUrl = jayConfig?.site?.baseUrl;
+  } catch {
+  }
+  const version = versionOverride || await resolveVersionFromPackageJson(resolvedPath);
+  return {
+    resolvedPath,
+    pagesRoot: path__default.resolve(resolvedPath, pagesBase),
+    buildRoot: path__default.join(resolvedPath, "build"),
+    version,
+    tsConfigFilePath: path__default.join(resolvedPath, "tsconfig.json"),
+    siteBaseUrl
+  };
+}
+async function resolveVersionFromPackageJson(projectRoot) {
+  try {
+    const pkgJson = JSON.parse(
+      await fs$2.readFile(path__default.join(projectRoot, "package.json"), "utf-8")
+    );
+    if (pkgJson.version) {
+      return pkgJson.version;
+    }
+  } catch {
+  }
+  return "1";
+}
+function initLogger(verbose) {
+  const logLevel = verbose ? "verbose" : "info";
+  setDevLogger(createDevLogger(logLevel));
+}
+async function runBuild(projectPath, options) {
+  initLogger(options.verbose);
+  const { surfaceValidationIssues: surfaceValidationIssues2 } = await Promise.resolve().then(() => runValidate$1);
+  const valid = await surfaceValidationIssues2(projectPath, { verbose: options.verbose });
+  if (!valid) {
+    process.exit(1);
+  }
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  await generateDefinitionFiles(ctx);
+  const { buildVersion } = await import("./index-l6QVpvnY.js");
+  await buildVersion({
+    version: ctx.version,
+    projectRoot: ctx.resolvedPath,
+    pagesRoot: ctx.pagesRoot,
+    buildRoot: ctx.buildRoot,
+    concurrency: 4,
+    tsConfigFilePath: ctx.tsConfigFilePath,
+    minify: options.minify,
+    siteBaseUrl: ctx.siteBaseUrl
+  });
+}
+async function generateDefinitionFiles(ctx) {
+  const { glob: glob2 } = await import("glob");
+  const { generatePageDefinitionFiles: generatePageDefinitionFiles2 } = await Promise.resolve().then(() => generatePageDefinitionFiles$1);
+  const { generateContractDefinitionFiles: generateContractDefinitionFiles2 } = await Promise.resolve().then(() => generateContractDefinitionFiles$1);
+  const jayHtmlPaths = await glob2("**/page.jay-html", {
+    cwd: ctx.pagesRoot,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/build/**", "**/dist/**"]
+  });
+  await generatePageDefinitionFiles2(jayHtmlPaths, ctx.tsConfigFilePath, ctx.resolvedPath);
+  await generateContractDefinitionFiles2(path__default.resolve(ctx.resolvedPath, "src"));
+}
+async function runServe(projectPath, options) {
+  initLogger(options.verbose);
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  if (options.role === "renderer") {
+    const { startRendererServer } = await import("@jay-framework/production-server");
+    await startRendererServer({
+      buildRoot: ctx.buildRoot,
+      version: ctx.version,
+      port: parseInt(options.port, 10),
+      projectRoot: ctx.resolvedPath,
+      pagesRoot: ctx.pagesRoot,
+      tsConfigFilePath: ctx.tsConfigFilePath,
+      siteBaseUrl: ctx.siteBaseUrl
+    });
+  } else {
+    const { startMainServer } = await import("@jay-framework/production-server");
+    await startMainServer({
+      buildRoot: ctx.buildRoot,
+      version: ctx.version,
+      port: parseInt(options.port, 10),
+      testMode: options.testMode,
+      publicBasePath: options.staticBaseUrl,
+      serveStatic: options.serveStatic
+    });
+  }
+}
+async function runRebuild(projectPath, options) {
+  initLogger(options.verbose);
+  const ctx = await resolveProductionContext(projectPath, options.version);
+  let params;
+  if (options.params) {
+    params = JSON.parse(options.params);
+  }
+  const { rebuild } = await import("@jay-framework/production-server");
+  let target;
+  if (options.contract) {
+    target = { mode: "contract", contractName: options.contract, params };
+  } else if (options.route) {
+    target = { mode: "route", routePattern: options.route, params };
+  } else if (options.url) {
+    target = { mode: "url", url: options.url };
+  } else {
+    getLogger().error(chalk.red("One of --contract, --route, or --url is required"));
+    process.exit(1);
+  }
+  const result = await rebuild({
+    projectRoot: ctx.resolvedPath,
+    pagesRoot: ctx.pagesRoot,
+    buildRoot: ctx.buildRoot,
+    version: ctx.version,
+    target,
+    tsConfigFilePath: ctx.tsConfigFilePath,
+    siteBaseUrl: ctx.siteBaseUrl
+  });
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      getLogger().error(
+        chalk.red(`  Error: ${err.route} ${JSON.stringify(err.params)}: ${err.error}`)
+      );
+    }
+    process.exit(1);
+  }
+}
+function syncPageContent(rawPage, pageDir, jayHtml, readFile) {
+  const regions = countDesignSystemRegions(jayHtml);
+  if (regions === 0) {
+    return { content: rawPage, changed: false, regions: 0, errors: [] };
+  }
+  const opts = buildMaterialiseOptions(pageDir, jayHtml, readFile, { preserveOverrides: true });
+  const { html, css, errors } = materialise(rawPage, opts);
+  const merged = mergeScopeCss(html, css);
+  const content = prettifyHtml(merged);
+  const changed = content !== prettifyHtml(rawPage);
+  return { content, changed, regions, errors };
+}
+function countDesignSystemRegions(jayHtml) {
+  const named = new Set(
+    jayHtml.headlessImports.filter((i) => i.template).map((i) => i.contractName.toLowerCase())
+  );
+  if (named.size === 0) return 0;
+  let count = 0;
+  const visit = (el) => {
+    for (const child of el.childNodes ?? []) {
+      if (child.rawTagName === void 0) continue;
+      const tag = (child.rawTagName ?? "").toLowerCase();
+      if (tag.startsWith("jay:") && named.has(tag.substring(4))) count++;
+      visit(child);
+    }
+  };
+  visit(jayHtml.body);
+  return count;
+}
+function mergeScopeCss(html, aggregatedCss) {
+  if (!aggregatedCss.trim()) return html;
+  const root = parse(html);
+  const head = root.querySelector("head");
+  if (!head) return html;
+  const styleEl = head.querySelector("style");
+  const existingCss = styleEl ? styleEl.textContent : "";
+  const groups = splitScopeBlocks(aggregatedCss);
+  const groupOf = /* @__PURE__ */ new Map();
+  const canonicalBody = /* @__PURE__ */ new Map();
+  for (const g of groups) {
+    const nb = normalizeCssBody(scopeInnerBody(g.block));
+    for (const s2 of g.selectors) {
+      groupOf.set(s2, g);
+      canonicalBody.set(s2, nb);
+    }
+  }
+  const overridden = /* @__PURE__ */ new Set();
+  const kept = [];
+  for (const seg of tokenizeCss(existingCss)) {
+    if (seg.type === "raw") {
+      if (seg.text.trim()) kept.push(seg.text.trim());
+      continue;
+    }
+    const marked = hasOverrideMarker(seg.block);
+    const body = normalizeCssBody(scopeInnerBody(seg.block));
+    const keepMembers = seg.selectors.filter((s2) => {
+      if (!groupOf.has(s2)) return true;
+      const diverges = marked && body !== canonicalBody.get(s2);
+      if (diverges) overridden.add(s2);
+      return diverges;
+    });
+    if (keepMembers.length === seg.selectors.length) kept.push(seg.block);
+    else if (keepMembers.length > 0) kept.push(narrowScopeBlock(seg.block, keepMembers));
+  }
+  const appended = [];
+  for (const g of groups) {
+    const plain = g.selectors.filter((s2) => !overridden.has(s2));
+    if (plain.length === 0) continue;
+    appended.push(
+      plain.length === g.selectors.length ? g.block : narrowScopeBlock(g.block, plain)
+    );
+  }
+  const newCss = [...kept, ...appended].filter(Boolean).join("\n\n");
+  if (newCss === existingCss.trim()) return html;
+  if (styleEl) styleEl.set_content(newCss);
+  else head.insertAdjacentHTML("beforeend", `<style>${newCss}</style>`);
+  return root.toString();
+}
+function hasOverrideMarker(block) {
+  return /\/\*\s*jay:override\b/.test(block);
+}
+function narrowScopeBlock(block, selectors) {
+  return block.replace(
+    /^(@scope\s*\()\s*[^)]*?\s*(\)(?:\s*to\s*\([^)]*\))?\s*\{)/,
+    `$1${selectors.join(", ")}$2`
+  );
+}
+async function resolveTargets(projectRoot, scanDirs, target, all) {
+  if (target && !all) {
+    const file = target.split("#")[0];
+    const abs = path$1.isAbsolute(file) ? file : path$1.resolve(projectRoot, file);
+    return [abs];
+  }
+  const found = await Promise.all(
+    scanDirs.map((dir) => glob(`${dir}/**/*${JAY_EXTENSION$1}`).catch(() => []))
+  );
+  return [...new Set(found.flat())];
+}
+async function runSync(target, options = {}) {
+  const logger = getLogger();
+  const projectRoot = options.path ? path$1.resolve(options.path) : process.cwd();
+  if (target && target.includes("#")) {
+    logger.important(
+      chalk.yellow(
+        `Per-region targeting (#ref) is not yet supported — syncing the whole page "${target.split("#")[0]}".`
+      )
+    );
+  }
+  const resolvedConfig = getConfigWithDefaults(loadConfig(projectRoot));
+  const scanDirs = [
+    path$1.resolve(projectRoot, resolvedConfig.devServer.pagesBase),
+    path$1.resolve(projectRoot, resolvedConfig.devServer.componentsBase)
+  ];
+  const files = await resolveTargets(projectRoot, scanDirs, target, options.all ?? false);
+  let filesChanged = 0;
+  let regionsSynced = 0;
+  let hadError = false;
+  for (const file of files) {
+    const relativePath = path$1.relative(projectRoot, file);
+    let content;
+    try {
+      content = await promises.readFile(file, "utf-8");
+    } catch {
+      logger.error(chalk.red(`✗ ${relativePath}: could not read file`));
+      hadError = true;
+      continue;
+    }
+    const dirname = path$1.dirname(file);
+    const filename = path$1.basename(file.replace(JAY_EXTENSION$1, ""));
+    const parsed = await parseJayFile(
+      content,
+      filename,
+      dirname,
+      {},
+      JAY_IMPORT_RESOLVER,
+      projectRoot
+    );
+    if (parsed.validations.length > 0 || !parsed.val) {
+      logger.error(chalk.red(`✗ ${relativePath}: ${parsed.validations.join("; ")}`));
+      hadError = true;
+      continue;
+    }
+    const result = syncPageContent(content, dirname, parsed.val, (absPath) => {
+      try {
+        return fs$1.readFileSync(absPath, "utf-8");
+      } catch {
+        return void 0;
+      }
+    });
+    if (result.errors.length > 0) {
+      for (const err of result.errors) logger.error(chalk.red(`✗ ${relativePath}: ${err}`));
+      hadError = true;
+      continue;
+    }
+    if (result.regions === 0) continue;
+    if (result.changed) {
+      await promises.writeFile(file, result.content, "utf-8");
+      filesChanged++;
+      regionsSynced += result.regions;
+      logger.important(
+        chalk.green(`✓ synced ${result.regions} region(s) in ${relativePath}`)
+      );
+    } else if (options.verbose) {
+      logger.important(chalk.gray(`• ${relativePath} — already in sync`));
+    }
+  }
+  if (filesChanged === 0) {
+    logger.important("Nothing to sync.");
+  } else {
+    logger.important(
+      chalk.green(`Synced ${regionsSynced} region(s) across ${filesChanged} file(s).`)
+    );
+  }
+  if (hadError) process.exit(1);
+}
 const ALL_ROLES = ["designer", "developer", "plugin", "devops"];
 async function runAgentKit(options) {
   const projectRoot = process.cwd();
@@ -5122,6 +6810,11 @@ Materialized ${totalContracts} contracts`));
       getLogger().important(`   Static: ${result.staticCount}`);
       getLogger().important(`   Dynamic: ${result.dynamicCount}`);
       getLogger().important(`   Output: ${result.outputDir}`);
+      if (result.pluginsIndex.designSystemIndex) {
+        getLogger().important(
+          `   Design-system catalog: agent-kit/design-system-index.yaml + design-system.md`
+        );
+      }
     }
     return { initErrors, viteServer: keepViteAlive ? viteServer : void 0 };
   } catch (error) {
@@ -5384,7 +7077,7 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
   let viteServer;
   try {
     let pluginName;
-    let contractName;
+    let contractName2;
     if (contractRef.startsWith("@")) {
       const secondSlash = contractRef.indexOf("/", contractRef.indexOf("/") + 1);
       if (secondSlash === -1) {
@@ -5394,7 +7087,7 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
         process.exit(1);
       }
       pluginName = contractRef.substring(0, secondSlash);
-      contractName = contractRef.substring(secondSlash + 1);
+      contractName2 = contractRef.substring(secondSlash + 1);
     } else {
       const slashIndex = contractRef.indexOf("/");
       if (slashIndex === -1) {
@@ -5404,7 +7097,7 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
         process.exit(1);
       }
       pluginName = contractRef.substring(0, slashIndex);
-      contractName = contractRef.substring(slashIndex + 1);
+      contractName2 = contractRef.substring(slashIndex + 1);
     }
     if (options.verbose) {
       getLogger().info("Starting Vite for TypeScript support...");
@@ -5412,10 +7105,10 @@ async function runParams(contractRef, options, projectRoot, initializeServices)
     viteServer = await createViteForCli({ projectRoot });
     await initializeServices(projectRoot, viteServer);
     const { resolvePluginComponent } = await import("@jay-framework/compiler-shared");
-    const resolution = resolvePluginComponent(projectRoot, pluginName, contractName);
+    const resolution = resolvePluginComponent(projectRoot, pluginName, contractName2);
     if (resolution.validations.length > 0 || !resolution.val) {
       getLogger().error(
-        chalk.red(`❌ Could not resolve plugin "${pluginName}" contract "${contractName}"`)
+        chalk.red(`❌ Could not resolve plugin "${pluginName}" contract "${contractName2}"`)
       );
       for (const msg of resolution.validations) {
         getLogger().error(`   ${msg}`);
@@ -5915,6 +7608,17 @@ program.command("validate").description("Validate all .jay-html and .jay-contrac
     process.exit(1);
   }
 });
+program.command("sync [target]").description(
+  "Re-flatten design-system regions from their source templates (keeps override facets)"
+).option("-p, --path <path>", "Project root (default: cwd)").option("--all", "Sync every page in the project (default when no target is given)").option("-v, --verbose", "Show pages that are already in sync").action(async (target, options) => {
+  try {
+    await runSync(target, options);
+  } catch (error) {
+    getLogger().error(chalk.red("Sync failed:") + " " + error.message);
+    if (error.stack) getLogger().error(error.stack);
+    process.exit(1);
+  }
+});
 program.command("validate-plugin").description("Validate a Jay Stack plugin package").option("-p, --path <path>", "Plugin root (default: cwd)").option("--local", "Validate local plugins in src/plugins/").option("-v, --verbose", "Show detailed validation output").option("--strict", "Treat warnings as errors (for CI)").option("--generate-types", "Generate .d.ts files for contracts").action(async (options) => {
   try {
     await runValidatePlugin(options.path, options);