@decantr/core 1.0.0-beta.8 → 1.0.0

package/dist/index.js

@@ -89,15 +89,19 @@ function routePath(pageId, index) {
 function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
-function buildNavItems(pages) {
+function buildNavItems(pages, routes) {
+  const routeLookup = new Map(
+    (routes ?? []).map((route) => [route.pageId, route.path])
+  );
   return pages.map((page, i) => ({
-    href: routePath(page.id, i),
+    href: routeLookup.get(page.id) ?? routePath(page.id, i),
     icon: NAV_ICONS[page.id] || "circle",
     label: capitalize(page.id.replace(/-/g, " "))
   }));
 }
-function buildRecipeDecoration(recipe) {
-  const shell = recipe.shell;
+function buildThemeDecoration(theme) {
+  const shell = theme.shell;
+  if (!shell) return null;
   const shellAny = shell;
   return {
     root: shell.root || "",
@@ -105,7 +109,7 @@ function buildRecipeDecoration(recipe) {
     header: shell.header || "",
     brand: shellAny["brand"] || "",
     navLabel: shellAny["navLabel"] || "",
-    // AUTO: default nav style is 'pill' per Decantr framework convention
+    // AUTO: default nav style is 'pill' when the theme does not declare one
     navStyle: shell.nav_style || "pill",
     defaultNavState: shellAny["default_nav_state"] || "expanded",
     dimensions: shell.dimensions || null
@@ -113,20 +117,18 @@ function buildRecipeDecoration(recipe) {
 }
 function buildTheme(essence, isAddon) {
   return {
-    style: essence.theme.style,
+    id: essence.theme.id,
     mode: essence.theme.mode,
     shape: essence.theme.shape || null,
-    recipe: essence.theme.recipe,
     isAddon
   };
 }
 function buildThemeFromV3(essence, isAddon) {
   const dna = essence.dna;
   return {
-    style: dna.theme.style,
+    id: dna.theme.id,
     mode: dna.theme.mode,
     shape: dna.radius.philosophy || dna.theme.shape || null,
-    recipe: dna.theme.recipe,
     isAddon
   };
 }
@@ -138,6 +140,23 @@ function blueprintPageToStructurePage(page, defaultShell) {
     ...page.surface ? { surface: page.surface } : {}
   };
 }
+function buildV3Routes(essence, blueprintPages, structurePages) {
+  const explicitRoutes = /* @__PURE__ */ new Map();
+  for (const [path, entry] of Object.entries(essence.blueprint.routes ?? {})) {
+    if (entry?.page && !explicitRoutes.has(entry.page)) {
+      explicitRoutes.set(entry.page, path);
+    }
+  }
+  for (const page of blueprintPages) {
+    if (page.route && !explicitRoutes.has(page.id)) {
+      explicitRoutes.set(page.id, page.route);
+    }
+  }
+  return structurePages.map((page, i) => ({
+    path: explicitRoutes.get(page.id) ?? routePath(page.id, i),
+    pageId: page.id
+  }));
+}
 function convertWiring(wiringResults) {
   if (wiringResults.length === 0) return null;
   const signals = [];
@@ -166,12 +185,13 @@ function convertWiring(wiringResults) {
   }
   return { signals, props, hooks: [...hookSet], hookProps };
 }
-function resolveVisualEffects(recipe, pattern, _slot) {
-  if (!recipe.visual_effects?.enabled) return null;
-  const typeMapping = recipe.visual_effects.type_mapping || {};
-  const componentFallback = recipe.visual_effects.component_fallback || {};
-  const intensity = recipe.visual_effects.intensity || "medium";
-  const intensityValues = recipe.visual_effects.intensity_values || {};
+function resolveVisualEffects(theme, pattern, _slot) {
+  const effects = theme.effects;
+  if (!effects?.enabled) return null;
+  const typeMapping = effects.type_mapping || {};
+  const componentFallback = effects.component_fallback || {};
+  const intensity = effects.intensity || "medium";
+  const intensityValues = effects.intensity_values || {};
   let decorators = [];
   for (const comp of pattern.components || []) {
     const effectType = componentFallback[comp];
@@ -216,30 +236,30 @@ async function resolveEssence(essence, resolver) {
   } else {
     throw new Error("Invalid essence format");
   }
-  let recipe = null;
-  const recipeResult = await resolver.resolve("recipe", simpleEssence.theme.recipe);
-  if (recipeResult) {
-    recipe = recipeResult.item;
+  let registryTheme = null;
+  const themeResult = await resolver.resolve("theme", simpleEssence.theme.id);
+  if (themeResult) {
+    registryTheme = themeResult.item;
   }
-  const recipeSpatial = recipe?.spatial_hints;
-  const density = computeDensity(simpleEssence.personality, recipeSpatial ? {
-    density_bias: recipeSpatial.density_bias,
-    content_gap_shift: recipeSpatial.content_gap_shift
+  const themeSpatial = registryTheme?.spatial;
+  const density = computeDensity(simpleEssence.personality, themeSpatial ? {
+    density_bias: themeSpatial.density_bias,
+    content_gap_shift: themeSpatial.content_gap_shift
   } : void 0);
-  const style = simpleEssence.theme.style;
-  const isAddon = style.startsWith("custom:") || !CORE_STYLES.has(style);
+  const themeId = simpleEssence.theme.id;
+  const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
   const theme = buildTheme(simpleEssence, isAddon);
-  const resolvedPages = await resolvePages(simpleEssence.structure, resolver, recipe);
+  const resolvedPages = await resolvePages(simpleEssence.structure, resolver, registryTheme);
   const shellType = simpleEssence.structure[0]?.shell || "sidebar-main";
   const brand = pascalCase(simpleEssence.archetype);
   const nav = buildNavItems(simpleEssence.structure);
-  const recipeDecoration = recipe ? buildRecipeDecoration(recipe) : null;
+  const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
   const shell = {
     type: shellType,
     brand,
     nav,
     inset: false,
-    recipe: recipeDecoration
+    decoration
   };
   const routes = simpleEssence.structure.map((page, i) => ({
     path: routePath(page.id, i),
@@ -248,7 +268,7 @@ async function resolveEssence(essence, resolver) {
   return {
     essence,
     pages: resolvedPages,
-    recipe,
+    registryTheme,
     density: { gap: density.content_gap, level: density.level },
     theme,
     shell,
@@ -259,48 +279,45 @@ async function resolveEssence(essence, resolver) {
 }
 async function resolveV3Essence(essence, resolver) {
   const { dna, blueprint, meta } = essence;
-  let recipe = null;
-  const recipeResult = await resolver.resolve("recipe", dna.theme.recipe);
-  if (recipeResult) {
-    recipe = recipeResult.item;
-  }
-  const recipeSpatial = recipe?.spatial_hints;
-  const density = computeDensity(dna.personality, recipeSpatial ? {
-    density_bias: recipeSpatial.density_bias,
-    content_gap_shift: recipeSpatial.content_gap_shift
+  let registryTheme = null;
+  const themeResult = await resolver.resolve("theme", dna.theme.id);
+  if (themeResult) {
+    registryTheme = themeResult.item;
+  }
+  const themeSpatial = registryTheme?.spatial;
+  const density = computeDensity(dna.personality, themeSpatial ? {
+    density_bias: themeSpatial.density_bias,
+    content_gap_shift: themeSpatial.content_gap_shift
   } : void 0);
   const densityResult = {
     gap: dna.spacing.content_gap || density.content_gap,
     level: dna.spacing.density || density.level
   };
-  const style = dna.theme.style;
-  const isAddon = style.startsWith("custom:") || !CORE_STYLES.has(style);
+  const themeId = dna.theme.id;
+  const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
   const theme = buildThemeFromV3(essence, isAddon);
   const blueprintPages = blueprint.pages ?? (blueprint.sections ? blueprint.sections.flatMap((s) => s.pages) : [{ id: "home", layout: ["hero"] }]);
   const defaultShell = blueprint.shell ?? (blueprint.sections?.[0]?.shell ?? "sidebar-main");
   const structurePages = blueprintPages.map(
     (p) => blueprintPageToStructurePage(p, defaultShell)
   );
-  const resolvedPages = await resolvePages(structurePages, resolver, recipe);
+  const resolvedPages = await resolvePages(structurePages, resolver, registryTheme);
   const shellType = defaultShell;
   const brand = pascalCase(meta.archetype);
-  const nav = buildNavItems(structurePages);
-  const recipeDecoration = recipe ? buildRecipeDecoration(recipe) : null;
+  const routes = buildV3Routes(essence, blueprintPages, structurePages);
+  const nav = buildNavItems(structurePages, routes);
+  const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
   const shell = {
     type: shellType,
     brand,
     nav,
     inset: false,
-    recipe: recipeDecoration
+    decoration
   };
-  const routes = structurePages.map((page, i) => ({
-    path: routePath(page.id, i),
-    pageId: page.id
-  }));
   return {
     essence,
     pages: resolvedPages,
-    recipe,
+    registryTheme,
     density: densityResult,
     theme,
     shell,
@@ -309,7 +326,7 @@ async function resolveV3Essence(essence, resolver) {
     isV3Source: true
   };
 }
-async function resolvePages(pages, resolver, recipe) {
+async function resolvePages(pages, resolver, registryTheme) {
   const resolvedPages = [];
   for (const page of pages) {
     const refs = extractLayoutRefs(page.layout);
@@ -320,7 +337,7 @@ async function resolvePages(pages, resolver, recipe) {
         const preset = resolvePatternPreset(
           patternResult.item,
           ref.explicitPreset,
-          recipe?.pattern_preferences?.default_presets
+          registryTheme?.pattern_preferences?.default_presets
         );
         const key = ref.alias || ref.id;
         patterns.set(key, { pattern: patternResult.item, preset });
@@ -340,32 +357,30 @@ function isPatternRef2(item) {
 function isColumnLayout2(item) {
   return typeof item === "object" && "cols" in item;
 }
-function shouldWrapInCard(pattern, preset, recipe) {
+function shouldWrapInCard(pattern, preset, theme) {
   const layout = preset.layout.layout;
   if (layout === "hero" || layout === "row") return false;
   if (pattern.contained === false) return false;
-  const cardWrapping = recipe?.spatial_hints?.card_wrapping;
+  const cardWrapping = theme?.spatial?.card_wrapping;
   if (cardWrapping === "none") return false;
   if (cardWrapping === "minimal") {
     return Object.keys(pattern.presets).length > 0;
   }
   return true;
 }
-function buildCardWrapping(pattern, recipe) {
-  const mode = recipe?.spatial_hints?.card_wrapping || "always";
-  const overrides = recipe?.pattern_overrides?.[pattern.id];
+function buildCardWrapping(pattern, theme) {
+  const mode = theme?.spatial?.card_wrapping || "always";
   return {
     mode,
-    headerLabel: pattern.name,
-    background: overrides?.background?.join(" ")
+    headerLabel: pattern.name
   };
 }
-function buildPatternNode(patternId, alias, resolved, wiring, recipe, density, layer) {
+function buildPatternNode(patternId, alias, resolved, wiring, theme, density, layer) {
   const pattern = resolved?.pattern;
   const preset = resolved?.preset;
   const layout = preset?.layout.layout || "column";
   const isStandalone = layout === "hero" || layout === "row";
-  const contained = pattern && preset ? shouldWrapInCard(pattern, preset, recipe) : false;
+  const contained = pattern && preset ? shouldWrapInCard(pattern, preset, theme) : false;
   const components = pattern?.components || [];
   const patternMeta = {
     patternId,
@@ -377,9 +392,9 @@ function buildPatternNode(patternId, alias, resolved, wiring, recipe, density, l
     code: preset?.code ? { imports: preset.code.imports, example: preset.code.example } : null,
     components
   };
-  const card = contained && !isStandalone && pattern ? buildCardWrapping(pattern, recipe) : null;
+  const card = contained && !isStandalone && pattern ? buildCardWrapping(pattern, theme) : null;
   const wireProps = wiring?.props[alias] || wiring?.props[patternId] || null;
-  const visualEffects = recipe && pattern ? resolveVisualEffects(recipe, pattern) : null;
+  const visualEffects = theme && pattern ? resolveVisualEffects(theme, pattern) : null;
   return {
     type: "pattern",
     id: alias,
@@ -392,16 +407,16 @@ function buildPatternNode(patternId, alias, resolved, wiring, recipe, density, l
     ...layer ? { layer } : {}
   };
 }
-function buildPageIR(page, resolvedPatterns, wiring, recipe, density, layer) {
+function buildPageIR(page, resolvedPatterns, wiring, theme, density, layer) {
   const children = [];
   for (const item of page.layout) {
     if (typeof item === "string") {
       const resolved = resolvedPatterns.get(item);
-      children.push(buildPatternNode(item, item, resolved, wiring, recipe, density, layer));
+      children.push(buildPatternNode(item, item, resolved, wiring, theme, density, layer));
     } else if (isPatternRef2(item)) {
       const alias = item.as || item.pattern;
       const resolved = resolvedPatterns.get(alias) || resolvedPatterns.get(item.pattern);
-      children.push(buildPatternNode(item.pattern, alias, resolved, wiring, recipe, density, layer));
+      children.push(buildPatternNode(item.pattern, alias, resolved, wiring, theme, density, layer));
     } else if (isColumnLayout2(item)) {
       const cols = item.cols;
       const breakpoint = item.at || null;
@@ -416,7 +431,7 @@ function buildPageIR(page, resolvedPatterns, wiring, recipe, density, layer) {
       const gridChildren = [];
       for (const col of cols) {
         const resolved = resolvedPatterns.get(col);
-        gridChildren.push(buildPatternNode(col, col, resolved, wiring, recipe, density, layer));
+        gridChildren.push(buildPatternNode(col, col, resolved, wiring, theme, density, layer));
       }
       const totalCols = normalizedSpans ? Object.values(normalizedSpans).reduce((a, b) => a + b, 0) : cols.length;
       const breakpoints = item.breakpoints?.map((bp) => ({ at: bp.at, cols: bp.cols })) || null;
@@ -461,10 +476,15 @@ async function runPipeline(essence, options) {
     throw new Error(`Invalid essence: ${validation.errors.join(", ")}`);
   }
   const effectiveEssence = isV32(essence) ? essence : migrateV2ToV3(essence);
-  const resolver = createResolver({
-    contentRoot: options.contentRoot,
-    overridePaths: options.overridePaths
-  });
+  const resolver = options.resolver ?? (() => {
+    if (!options.contentRoot) {
+      throw new Error("Pipeline options must include either a contentRoot or a resolver.");
+    }
+    return createResolver({
+      contentRoot: options.contentRoot,
+      overridePaths: options.overridePaths
+    });
+  })();
   const resolved = await resolveEssence(effectiveEssence, resolver);
   const layer = resolved.isV3Source ? "blueprint" : void 0;
   const pageNodes = [];
@@ -473,7 +493,7 @@ async function runPipeline(essence, options) {
       rp.page,
       rp.patterns,
       rp.wiring,
-      resolved.recipe,
+      resolved.registryTheme,
       { gap: resolved.density.gap },
       layer
     );
@@ -557,14 +577,853 @@ function validateIR(root) {
   });
   return errors;
 }
+
+// src/packs.ts
+import { isV3 as isV33, migrateV2ToV3 as migrateV2ToV32 } from "@decantr/essence-spec";
+var EXECUTION_PACK_SCHEMA_URLS = {
+  scaffold: "https://decantr.ai/schemas/scaffold-pack.v1.json",
+  section: "https://decantr.ai/schemas/section-pack.v1.json",
+  page: "https://decantr.ai/schemas/page-pack.v1.json",
+  mutation: "https://decantr.ai/schemas/mutation-pack.v1.json",
+  review: "https://decantr.ai/schemas/review-pack.v1.json"
+};
+var PACK_MANIFEST_SCHEMA_URL = "https://decantr.ai/schemas/pack-manifest.v1.json";
+var EXECUTION_PACK_BUNDLE_SCHEMA_URL = "https://decantr.ai/schemas/execution-pack-bundle.v1.json";
+var SELECTED_EXECUTION_PACK_SCHEMA_URL = "https://decantr.ai/schemas/selected-execution-pack.v1.json";
+var DEFAULT_TARGET = {
+  platform: "web",
+  framework: null,
+  runtime: null,
+  adapter: "generic-web"
+};
+var DEFAULT_TOKEN_BUDGET = {
+  target: 1400,
+  max: 2200,
+  strategy: [
+    "Prefer route summaries over repeated prose.",
+    "Use compact vocabulary lists instead of large reference tables.",
+    "Include only task-relevant examples and checks."
+  ]
+};
+var DEFAULT_SUCCESS_CHECKS = [
+  {
+    id: "route-topology",
+    label: "Routes and page IDs match the compiled topology.",
+    severity: "error"
+  },
+  {
+    id: "shell-consistency",
+    label: "The declared shell contract is preserved unless the task explicitly mutates it.",
+    severity: "error"
+  },
+  {
+    id: "theme-consistency",
+    label: "Theme identity and mode remain consistent across scaffolded routes.",
+    severity: "warn"
+  }
+];
+var DEFAULT_SECTION_SUCCESS_CHECKS = [
+  {
+    id: "section-route-coherence",
+    label: "Section pages and routes remain coherent with the compiled topology.",
+    severity: "error"
+  },
+  {
+    id: "section-shell-consistency",
+    label: "The section shell contract stays consistent across its routes.",
+    severity: "error"
+  },
+  {
+    id: "section-pattern-coverage",
+    label: "Primary section patterns are represented without adding off-contract filler sections.",
+    severity: "warn"
+  }
+];
+var DEFAULT_PAGE_SUCCESS_CHECKS = [
+  {
+    id: "page-route-contract",
+    label: "The page keeps the compiled route, shell, and section contract intact.",
+    severity: "error"
+  },
+  {
+    id: "page-pattern-contract",
+    label: "The page preserves its primary compiled patterns instead of drifting into unrelated layouts.",
+    severity: "error"
+  },
+  {
+    id: "page-state-contract",
+    label: "Any declared wiring signals remain coherent with the rendered page structure.",
+    severity: "warn"
+  }
+];
+var DEFAULT_MUTATION_SUCCESS_CHECKS = {
+  "add-page": [
+    {
+      id: "mutation-essence-first",
+      label: "New pages are declared in the essence before any code generation begins.",
+      severity: "error"
+    },
+    {
+      id: "mutation-shell-contract",
+      label: "New routes inherit an existing shell and section contract unless the essence changes first.",
+      severity: "error"
+    },
+    {
+      id: "mutation-refresh",
+      label: "Refresh compiled packs after the mutation so downstream tasks read current topology.",
+      severity: "warn"
+    }
+  ],
+  modify: [
+    {
+      id: "mutation-existing-topology",
+      label: "Modified routes remain coherent with the compiled topology unless the essence changes first.",
+      severity: "error"
+    },
+    {
+      id: "mutation-theme-contract",
+      label: "Theme, shell, and page identity stay aligned with the current contract during edits.",
+      severity: "error"
+    },
+    {
+      id: "mutation-page-pack-first",
+      label: "Route-local edits should start from the compiled page pack rather than improvised structure.",
+      severity: "warn"
+    }
+  ]
+};
+var DEFAULT_REVIEW_SUCCESS_CHECKS = [
+  {
+    id: "review-contract-baseline",
+    label: "Review findings should use the compiled route, shell, and theme contract as the baseline.",
+    severity: "error"
+  },
+  {
+    id: "review-evidence",
+    label: "Each critique finding should cite concrete evidence from the generated workspace.",
+    severity: "error"
+  },
+  {
+    id: "review-remediation",
+    label: "Suggested fixes should point back to code changes or essence updates when contract drift exists.",
+    severity: "warn"
+  }
+];
+var DEFAULT_REVIEW_ANTI_PATTERNS = [
+  {
+    id: "inline-styles",
+    summary: "Avoid inline style literals as the primary styling path.",
+    guidance: "Move visual styling into tokens.css and treatments.css instead of component-local style objects."
+  },
+  {
+    id: "hardcoded-colors",
+    summary: "Avoid hardcoded color literals.",
+    guidance: "Use CSS variables and theme decorators instead of hex, rgb, or hsl values."
+  },
+  {
+    id: "utility-framework-leakage",
+    summary: "Avoid utility-framework leakage as the primary design language.",
+    guidance: "Prefer compiled Decantr treatments and contract vocabulary over ad hoc utility class stacks."
+  }
+];
+function collectPatternIds(page) {
+  const patternIds = [];
+  walkIR(page, (node) => {
+    if (node.type !== "pattern") return;
+    const patternNode = node;
+    patternIds.push(patternNode.pattern.patternId);
+  });
+  return [...new Set(patternIds)];
+}
+function summarizeRoutes(appNode) {
+  return appNode.children.map((page) => {
+    const pageNode = page;
+    const route = appNode.routes.find((entry) => entry.pageId === pageNode.pageId);
+    return {
+      pageId: pageNode.pageId,
+      path: route?.path || `/${pageNode.pageId}`,
+      patternIds: collectPatternIds(pageNode)
+    };
+  });
+}
+function summarizeSectionRoutes(appNode, input) {
+  return summarizeRoutes(appNode).filter((route) => input.pageIds.includes(route.pageId));
+}
+function summarizePageRoute(appNode, pageId) {
+  return summarizeRoutes(appNode).find((route) => route.pageId === pageId) ?? null;
+}
+function findPageNode(appNode, pageId) {
+  const page = appNode.children.find((node) => node.pageId === pageId);
+  return page ? page : null;
+}
+function collectPagePatterns(page) {
+  const patterns = [];
+  walkIR(page, (node) => {
+    if (node.type !== "pattern") return;
+    const patternNode = node;
+    patterns.push({
+      id: patternNode.pattern.patternId,
+      alias: patternNode.pattern.alias,
+      preset: patternNode.pattern.preset,
+      layout: patternNode.pattern.layout
+    });
+  });
+  return patterns;
+}
+function mergeTokenBudget(overrides) {
+  return {
+    target: overrides?.target ?? DEFAULT_TOKEN_BUDGET.target,
+    max: overrides?.max ?? DEFAULT_TOKEN_BUDGET.max,
+    strategy: overrides?.strategy ?? DEFAULT_TOKEN_BUDGET.strategy
+  };
+}
+function renderList(title, entries) {
+  if (entries.length === 0) return [];
+  return [title, ...entries.map((entry) => `- ${entry}`), ""];
+}
+function renderExecutionPackMarkdown(pack) {
+  const lines = [];
+  lines.push(`# ${pack.packType.charAt(0).toUpperCase()}${pack.packType.slice(1)} Pack`);
+  lines.push("");
+  lines.push(`**Objective:** ${pack.objective}`);
+  lines.push(`**Target:** ${pack.target.adapter}${pack.target.framework ? ` (${pack.target.framework})` : ""}`);
+  lines.push(`**Scope:** pages=${pack.scope.pageIds.join(", ") || "none"} | patterns=${pack.scope.patternIds.join(", ") || "none"}`);
+  lines.push("");
+  if (pack.packType === "scaffold") {
+    const scaffoldPack = pack;
+    lines.push("## Scaffold Contract");
+    lines.push(`- Shell: ${scaffoldPack.data.shell}`);
+    lines.push(`- Theme: ${scaffoldPack.data.theme.id} (${scaffoldPack.data.theme.mode})`);
+    lines.push(`- Routing: ${scaffoldPack.data.routing}`);
+    if (scaffoldPack.data.features.length > 0) {
+      lines.push(`- Features: ${scaffoldPack.data.features.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("## Route Plan");
+    for (const route of scaffoldPack.data.routes) {
+      const patterns = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+      lines.push(`- ${route.path} -> ${route.pageId} [${patterns}]`);
+    }
+    lines.push("");
+  }
+  if (pack.packType === "section") {
+    const sectionPack = pack;
+    lines.push("## Section Contract");
+    lines.push(`- Section: ${sectionPack.data.sectionId}`);
+    lines.push(`- Role: ${sectionPack.data.role}`);
+    lines.push(`- Shell: ${sectionPack.data.shell}`);
+    lines.push(`- Theme: ${sectionPack.data.theme.id} (${sectionPack.data.theme.mode})`);
+    if (sectionPack.data.features.length > 0) {
+      lines.push(`- Features: ${sectionPack.data.features.join(", ")}`);
+    }
+    if (sectionPack.data.description) {
+      lines.push(`- Description: ${sectionPack.data.description}`);
+    }
+    lines.push("");
+    lines.push("## Section Routes");
+    for (const route of sectionPack.data.routes) {
+      const patterns = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+      lines.push(`- ${route.path} -> ${route.pageId} [${patterns}]`);
+    }
+    lines.push("");
+  }
+  if (pack.packType === "page") {
+    const pagePack = pack;
+    lines.push("## Page Contract");
+    lines.push(`- Page: ${pagePack.data.pageId}`);
+    lines.push(`- Path: ${pagePack.data.path}`);
+    lines.push(`- Shell: ${pagePack.data.shell}`);
+    if (pagePack.data.sectionId) {
+      const role = pagePack.data.sectionRole ? ` (${pagePack.data.sectionRole})` : "";
+      lines.push(`- Section: ${pagePack.data.sectionId}${role}`);
+    }
+    lines.push(`- Theme: ${pagePack.data.theme.id} (${pagePack.data.theme.mode})`);
+    if (pagePack.data.features.length > 0) {
+      lines.push(`- Features: ${pagePack.data.features.join(", ")}`);
+    }
+    if (pagePack.data.surface) {
+      lines.push(`- Surface: ${pagePack.data.surface}`);
+    }
+    lines.push("");
+    lines.push("## Page Patterns");
+    for (const pattern of pagePack.data.patterns) {
+      lines.push(`- ${pattern.alias} -> ${pattern.id} [${pattern.layout}${pattern.preset ? ` | ${pattern.preset}` : ""}]`);
+    }
+    lines.push("");
+    if (pagePack.data.wiringSignals.length > 0) {
+      lines.push("## Wiring Signals");
+      for (const signal of pagePack.data.wiringSignals) {
+        lines.push(`- ${signal}`);
+      }
+      lines.push("");
+    }
+  }
+  if (pack.packType === "mutation") {
+    const mutationPack = pack;
+    lines.push("## Mutation Contract");
+    lines.push(`- Operation: ${mutationPack.data.mutationType}`);
+    lines.push(`- Shell: ${mutationPack.data.shell}`);
+    lines.push(`- Theme: ${mutationPack.data.theme.id} (${mutationPack.data.theme.mode})`);
+    lines.push(`- Routing: ${mutationPack.data.routing}`);
+    if (mutationPack.data.features.length > 0) {
+      lines.push(`- Features: ${mutationPack.data.features.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("## Route Topology");
+    for (const route of mutationPack.data.routes) {
+      const patterns = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+      lines.push(`- ${route.path} -> ${route.pageId} [${patterns}]`);
+    }
+    lines.push("");
+    if (mutationPack.data.workflow.length > 0) {
+      lines.push("## Workflow");
+      for (const step of mutationPack.data.workflow) {
+        lines.push(`- ${step}`);
+      }
+      lines.push("");
+    }
+  }
+  if (pack.packType === "review") {
+    const reviewPack = pack;
+    lines.push("## Review Contract");
+    lines.push(`- Review Type: ${reviewPack.data.reviewType}`);
+    lines.push(`- Shell: ${reviewPack.data.shell}`);
+    lines.push(`- Theme: ${reviewPack.data.theme.id} (${reviewPack.data.theme.mode})`);
+    lines.push(`- Routing: ${reviewPack.data.routing}`);
+    if (reviewPack.data.features.length > 0) {
+      lines.push(`- Features: ${reviewPack.data.features.join(", ")}`);
+    }
+    lines.push("");
+    lines.push("## Review Topology");
+    for (const route of reviewPack.data.routes) {
+      const patterns = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+      lines.push(`- ${route.path} -> ${route.pageId} [${patterns}]`);
+    }
+    lines.push("");
+    if (reviewPack.data.focusAreas.length > 0) {
+      lines.push("## Focus Areas");
+      for (const focusArea of reviewPack.data.focusAreas) {
+        lines.push(`- ${focusArea}`);
+      }
+      lines.push("");
+    }
+    if (reviewPack.data.workflow.length > 0) {
+      lines.push("## Review Workflow");
+      for (const step of reviewPack.data.workflow) {
+        lines.push(`- ${step}`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("## Required Setup");
+  if (pack.requiredSetup.length === 0) {
+    lines.push("- None declared.");
+  } else {
+    lines.push(...pack.requiredSetup.map((entry) => `- ${entry}`));
+  }
+  lines.push("");
+  lines.push("## Allowed Vocabulary");
+  if (pack.allowedVocabulary.length === 0) {
+    lines.push("- None declared.");
+  } else {
+    lines.push(...pack.allowedVocabulary.map((entry) => `- ${entry}`));
+  }
+  lines.push("");
+  lines.push(...renderList("## Success Checks", pack.successChecks.map((entry) => `${entry.label} [${entry.severity}]`)));
+  lines.push(...renderList("## Anti-Patterns", pack.antiPatterns.map((entry) => `${entry.summary}: ${entry.guidance}`)));
+  lines.push(...renderList("## Examples", pack.examples.map((entry) => `${entry.label} (${entry.language})`)));
+  lines.push("## Token Budget");
+  lines.push(`- Target: ${pack.tokenBudget.target}`);
+  lines.push(`- Max: ${pack.tokenBudget.max}`);
+  lines.push(...pack.tokenBudget.strategy.map((entry) => `- ${entry}`));
+  lines.push("");
+  return lines.join("\n").trimEnd() + "\n";
+}
+function resolvePackAdapter(target, platformType) {
+  if (target === "react" && platformType === "spa") return "react-vite";
+  if (target === "react") return "react-web";
+  if (target === "vue" && platformType === "spa") return "vue-vite";
+  if (target === "svelte" && platformType === "spa") return "sveltekit";
+  if (target) return target;
+  return "generic-web";
+}
+function listPackSections(essence) {
+  const declaredSections = essence.blueprint.sections;
+  if (declaredSections && declaredSections.length > 0) {
+    return declaredSections.map((section) => ({
+      id: section.id,
+      role: section.role,
+      shell: section.shell,
+      description: section.description,
+      features: section.features,
+      pageIds: section.pages.map((page) => page.id)
+    }));
+  }
+  const pages = essence.blueprint.pages ?? [{ id: "home", layout: ["hero"] }];
+  return [{
+    id: essence.meta.archetype || "default",
+    role: "primary",
+    shell: essence.blueprint.shell ?? "sidebar-main",
+    description: `${essence.meta.archetype || "Application"} section`,
+    features: essence.blueprint.features || [],
+    pageIds: pages.map((page) => page.id)
+  }];
+}
+function listPackPages(essence) {
+  const declaredSections = essence.blueprint.sections;
+  if (declaredSections && declaredSections.length > 0) {
+    return declaredSections.flatMap(
+      (section) => section.pages.map((page) => ({
+        pageId: page.id,
+        shell: page.shell_override ?? section.shell,
+        sectionId: section.id,
+        sectionRole: section.role,
+        features: section.features
+      }))
+    );
+  }
+  const pages = essence.blueprint.pages ?? [{ id: "home", layout: ["hero"] }];
+  const defaultShell = essence.blueprint.shell ?? "sidebar-main";
+  return pages.map((page) => ({
+    pageId: page.id,
+    shell: page.shell_override ?? defaultShell,
+    sectionId: essence.meta.archetype || "default",
+    sectionRole: "primary",
+    features: essence.blueprint.features || []
+  }));
+}
+function buildScaffoldPack(appNode, options = {}) {
+  const routes = summarizeRoutes(appNode);
+  const scopePatternIds = [...new Set(routes.flatMap((route) => route.patternIds))];
+  const pack = {
+    $schema: EXECUTION_PACK_SCHEMA_URLS.scaffold,
+    packVersion: "1.0.0",
+    packType: "scaffold",
+    objective: options.objective ?? `Scaffold the ${appNode.theme.id} app shell and declared routes.`,
+    target: {
+      ...DEFAULT_TARGET,
+      ...options.target
+    },
+    preset: options.preset ?? null,
+    scope: {
+      appId: appNode.id,
+      pageIds: routes.map((route) => route.pageId),
+      patternIds: scopePatternIds
+    },
+    requiredSetup: options.requiredSetup ?? [
+      "Treat the declared routes as the topology source of truth.",
+      "Preserve the resolved theme and shell contract unless the task explicitly mutates them."
+    ],
+    allowedVocabulary: [.../* @__PURE__ */ new Set([
+      appNode.shell.config.type,
+      appNode.theme.id,
+      appNode.theme.mode,
+      ...appNode.features,
+      ...scopePatternIds
+    ])],
+    examples: options.examples ?? [],
+    antiPatterns: options.antiPatterns ?? [],
+    successChecks: options.successChecks ?? DEFAULT_SUCCESS_CHECKS,
+    tokenBudget: mergeTokenBudget(options.tokenBudget),
+    data: {
+      shell: appNode.shell.config.type,
+      theme: {
+        id: appNode.theme.id,
+        mode: appNode.theme.mode,
+        shape: appNode.theme.shape
+      },
+      routing: appNode.routing,
+      features: appNode.features,
+      routes
+    },
+    renderedMarkdown: ""
+  };
+  pack.renderedMarkdown = renderExecutionPackMarkdown(pack);
+  return pack;
+}
+function buildSectionPack(appNode, input, options = {}) {
+  const routes = summarizeSectionRoutes(appNode, input);
+  const scopePatternIds = [...new Set(routes.flatMap((route) => route.patternIds))];
+  const pack = {
+    $schema: EXECUTION_PACK_SCHEMA_URLS.section,
+    packVersion: "1.0.0",
+    packType: "section",
+    objective: options.objective ?? `Implement the ${input.id} section using the compiled ${input.shell} shell contract.`,
+    target: {
+      ...DEFAULT_TARGET,
+      ...options.target
+    },
+    preset: options.preset ?? null,
+    scope: {
+      appId: appNode.id,
+      pageIds: routes.map((route) => route.pageId),
+      patternIds: scopePatternIds
+    },
+    requiredSetup: options.requiredSetup ?? [
+      "Use the declared section routes as the source of truth for this slice of the app.",
+      "Keep the section shell consistent unless the task explicitly changes the shell contract."
+    ],
+    allowedVocabulary: [.../* @__PURE__ */ new Set([
+      input.id,
+      input.role,
+      input.shell,
+      appNode.theme.id,
+      appNode.theme.mode,
+      ...input.features,
+      ...scopePatternIds
+    ])],
+    examples: options.examples ?? [],
+    antiPatterns: options.antiPatterns ?? [],
+    successChecks: options.successChecks ?? DEFAULT_SECTION_SUCCESS_CHECKS,
+    tokenBudget: mergeTokenBudget(options.tokenBudget),
+    data: {
+      sectionId: input.id,
+      role: input.role,
+      shell: input.shell,
+      description: input.description,
+      features: input.features,
+      theme: {
+        id: appNode.theme.id,
+        mode: appNode.theme.mode,
+        shape: appNode.theme.shape
+      },
+      routes
+    },
+    renderedMarkdown: ""
+  };
+  pack.renderedMarkdown = renderExecutionPackMarkdown(pack);
+  return pack;
+}
+function buildPagePack(appNode, input, options = {}) {
+  const pageNode = findPageNode(appNode, input.pageId);
+  const route = summarizePageRoute(appNode, input.pageId);
+  if (!pageNode || !route) {
+    throw new Error(`Unknown page for page pack: ${input.pageId}`);
+  }
+  const patterns = collectPagePatterns(pageNode);
+  const pack = {
+    $schema: EXECUTION_PACK_SCHEMA_URLS.page,
+    packVersion: "1.0.0",
+    packType: "page",
+    objective: options.objective ?? `Implement the ${input.pageId} route using the compiled page contract.`,
+    target: {
+      ...DEFAULT_TARGET,
+      ...options.target
+    },
+    preset: options.preset ?? null,
+    scope: {
+      appId: appNode.id,
+      pageIds: [route.pageId],
+      patternIds: [...new Set(patterns.map((pattern) => pattern.id))]
+    },
+    requiredSetup: options.requiredSetup ?? [
+      "Keep the compiled route and shell contract stable for this page.",
+      "Treat the listed page patterns as the primary structure for this route."
+    ],
+    allowedVocabulary: [...new Set([
+      input.pageId,
+      input.shell,
+      input.sectionId ?? "",
+      input.sectionRole ?? "",
+      appNode.theme.id,
+      appNode.theme.mode,
+      ...input.features,
+      ...patterns.flatMap((pattern) => [pattern.id, pattern.alias, pattern.layout])
+    ].filter(Boolean))],
+    examples: options.examples ?? [],
+    antiPatterns: options.antiPatterns ?? [],
+    successChecks: options.successChecks ?? DEFAULT_PAGE_SUCCESS_CHECKS,
+    tokenBudget: mergeTokenBudget(options.tokenBudget),
+    data: {
+      pageId: route.pageId,
+      path: route.path,
+      shell: input.shell,
+      sectionId: input.sectionId,
+      sectionRole: input.sectionRole,
+      features: input.features,
+      surface: pageNode.surface,
+      theme: {
+        id: appNode.theme.id,
+        mode: appNode.theme.mode,
+        shape: appNode.theme.shape
+      },
+      wiringSignals: pageNode.wiring?.signals.map((signal) => signal.name) ?? [],
+      patterns
+    },
+    renderedMarkdown: ""
+  };
+  pack.renderedMarkdown = renderExecutionPackMarkdown(pack);
+  return pack;
+}
+function buildMutationPack(appNode, options) {
+  const routes = summarizeRoutes(appNode);
+  const scopePatternIds = [...new Set(routes.flatMap((route) => route.patternIds))];
+  const defaultWorkflow = options.mutationType === "add-page" ? [
+    "Declare the new page in the essence before generating code.",
+    "Refresh Decantr context so section and page packs include the new route.",
+    "Read the relevant section pack and new page pack before implementation."
+  ] : [
+    "Read the page pack for the route you are modifying first.",
+    "Stop and update the essence before changing route, shell, or pattern contracts.",
+    "Validate and check drift after code changes complete."
+  ];
+  const pack = {
+    $schema: EXECUTION_PACK_SCHEMA_URLS.mutation,
+    packVersion: "1.0.0",
+    packType: "mutation",
+    objective: options.objective ?? `Execute the ${options.mutationType} workflow against the compiled app contract.`,
+    target: {
+      ...DEFAULT_TARGET,
+      ...options.target
+    },
+    preset: options.preset ?? null,
+    scope: {
+      appId: appNode.id,
+      pageIds: routes.map((route) => route.pageId),
+      patternIds: scopePatternIds
+    },
+    requiredSetup: options.requiredSetup ?? [
+      "Treat the compiled topology as the source of truth until the essence changes.",
+      "Refresh Decantr context after structural mutations so downstream tasks read current packs."
+    ],
+    allowedVocabulary: [.../* @__PURE__ */ new Set([
+      options.mutationType,
+      appNode.shell.config.type,
+      appNode.theme.id,
+      appNode.theme.mode,
+      ...appNode.features,
+      ...scopePatternIds
+    ])],
+    examples: options.examples ?? [],
+    antiPatterns: options.antiPatterns ?? [],
+    successChecks: options.successChecks ?? DEFAULT_MUTATION_SUCCESS_CHECKS[options.mutationType],
+    tokenBudget: mergeTokenBudget(options.tokenBudget),
+    data: {
+      mutationType: options.mutationType,
+      shell: appNode.shell.config.type,
+      theme: {
+        id: appNode.theme.id,
+        mode: appNode.theme.mode,
+        shape: appNode.theme.shape
+      },
+      routing: appNode.routing,
+      features: appNode.features,
+      routes,
+      workflow: options.workflow ?? defaultWorkflow
+    },
+    renderedMarkdown: ""
+  };
+  pack.renderedMarkdown = renderExecutionPackMarkdown(pack);
+  return pack;
+}
+function buildReviewPack(appNode, options = {}) {
+  const routes = summarizeRoutes(appNode);
+  const scopePatternIds = [...new Set(routes.flatMap((route) => route.patternIds))];
+  const reviewType = options.reviewType ?? "app";
+  const focusAreas = options.focusAreas ?? [
+    "route-topology",
+    "theme-consistency",
+    "treatment-usage",
+    "accessibility",
+    "responsive-design"
+  ];
+  const workflow = options.workflow ?? [
+    "Read the scaffold pack and page packs before evaluating generated code.",
+    "Compare findings against the compiled route, shell, and theme contract first.",
+    "Escalate contract drift into essence updates when the requested output intentionally changes topology or theme identity."
+  ];
+  const pack = {
+    $schema: EXECUTION_PACK_SCHEMA_URLS.review,
+    packVersion: "1.0.0",
+    packType: "review",
+    objective: options.objective ?? "Review generated output against the compiled Decantr contract.",
+    target: {
+      ...DEFAULT_TARGET,
+      ...options.target
+    },
+    preset: options.preset ?? null,
+    scope: {
+      appId: appNode.id,
+      pageIds: routes.map((route) => route.pageId),
+      patternIds: scopePatternIds
+    },
+    requiredSetup: options.requiredSetup ?? [
+      "Read the compiled scaffold and route packs before reviewing code.",
+      "Use concrete evidence from the workspace instead of purely stylistic intuition."
+    ],
+    allowedVocabulary: [.../* @__PURE__ */ new Set([
+      reviewType,
+      appNode.shell.config.type,
+      appNode.theme.id,
+      appNode.theme.mode,
+      ...appNode.features,
+      ...scopePatternIds,
+      ...focusAreas
+    ])],
+    examples: options.examples ?? [],
+    antiPatterns: options.antiPatterns ?? DEFAULT_REVIEW_ANTI_PATTERNS,
+    successChecks: options.successChecks ?? DEFAULT_REVIEW_SUCCESS_CHECKS,
+    tokenBudget: mergeTokenBudget(options.tokenBudget),
+    data: {
+      reviewType,
+      shell: appNode.shell.config.type,
+      theme: {
+        id: appNode.theme.id,
+        mode: appNode.theme.mode,
+        shape: appNode.theme.shape
+      },
+      routing: appNode.routing,
+      features: appNode.features,
+      routes,
+      focusAreas,
+      workflow
+    },
+    renderedMarkdown: ""
+  };
+  pack.renderedMarkdown = renderExecutionPackMarkdown(pack);
+  return pack;
+}
+async function compileExecutionPackBundle(essence, options = {}) {
+  const effectiveEssence = isV33(essence) ? essence : migrateV2ToV32(essence);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const sharedTarget = {
+    framework: effectiveEssence.meta.target || null,
+    runtime: effectiveEssence.meta.platform.type || null,
+    adapter: resolvePackAdapter(effectiveEssence.meta.target, effectiveEssence.meta.platform.type)
+  };
+  const pipeline = await runPipeline(essence, {
+    contentRoot: options.contentRoot,
+    overridePaths: options.overridePaths,
+    resolver: options.resolver
+  });
+  const scaffold = buildScaffoldPack(pipeline.ir, {
+    target: sharedTarget
+  });
+  const review = buildReviewPack(pipeline.ir, {
+    target: sharedTarget
+  });
+  const sections = listPackSections(effectiveEssence).map((section) => buildSectionPack(pipeline.ir, section, {
+    target: sharedTarget
+  }));
+  const pages = listPackPages(effectiveEssence).map((page) => buildPagePack(pipeline.ir, page, {
+    target: sharedTarget
+  }));
+  const mutations = ["add-page", "modify"].map((mutationType) => buildMutationPack(pipeline.ir, {
+    mutationType,
+    target: sharedTarget
+  }));
+  const manifest = {
+    $schema: PACK_MANIFEST_SCHEMA_URL,
+    version: "1.0.0",
+    generatedAt,
+    scaffold: {
+      id: "scaffold",
+      markdown: "scaffold-pack.md",
+      json: "scaffold-pack.json"
+    },
+    review: {
+      id: "review",
+      markdown: "review-pack.md",
+      json: "review-pack.json"
+    },
+    sections: listPackSections(effectiveEssence).map((section) => ({
+      id: section.id,
+      markdown: `section-${section.id}-pack.md`,
+      json: `section-${section.id}-pack.json`,
+      pageIds: section.pageIds
+    })),
+    pages: listPackPages(effectiveEssence).map((page) => ({
+      id: page.pageId,
+      markdown: `page-${page.pageId}-pack.md`,
+      json: `page-${page.pageId}-pack.json`,
+      sectionId: page.sectionId,
+      sectionRole: page.sectionRole
+    })),
+    mutations: ["add-page", "modify"].map((mutationType) => ({
+      id: mutationType,
+      markdown: `mutation-${mutationType}-pack.md`,
+      json: `mutation-${mutationType}-pack.json`,
+      mutationType
+    }))
+  };
+  return {
+    $schema: EXECUTION_PACK_BUNDLE_SCHEMA_URL,
+    generatedAt,
+    sourceEssenceVersion: essence.version,
+    manifest,
+    scaffold,
+    review,
+    sections,
+    pages,
+    mutations
+  };
+}
+function selectExecutionPackFromBundle(bundle, selector) {
+  const id = selector.id ?? null;
+  let pack = null;
+  switch (selector.packType) {
+    case "scaffold":
+      pack = bundle.scaffold;
+      break;
+    case "review":
+      pack = bundle.review;
+      break;
+    case "section":
+      pack = id ? bundle.sections.find((entry) => entry.data.sectionId === id) ?? null : null;
+      break;
+    case "page":
+      pack = id ? bundle.pages.find((entry) => entry.data.pageId === id) ?? null : null;
+      break;
+    case "mutation":
+      pack = id ? bundle.mutations.find((entry) => entry.data.mutationType === id) ?? null : null;
+      break;
+    default:
+      pack = null;
+      break;
+  }
+  if (!pack) {
+    return null;
+  }
+  return {
+    $schema: SELECTED_EXECUTION_PACK_SCHEMA_URL,
+    generatedAt: bundle.generatedAt,
+    sourceEssenceVersion: bundle.sourceEssenceVersion,
+    manifest: bundle.manifest,
+    selector: {
+      packType: selector.packType,
+      id
+    },
+    pack
+  };
+}
+async function compileSelectedExecutionPack(essence, selector, options = {}) {
+  const bundle = await compileExecutionPackBundle(essence, options);
+  return selectExecutionPackFromBundle(bundle, selector);
+}
 export {
+  EXECUTION_PACK_BUNDLE_SCHEMA_URL,
+  EXECUTION_PACK_SCHEMA_URLS,
+  PACK_MANIFEST_SCHEMA_URL,
+  SELECTED_EXECUTION_PACK_SCHEMA_URL,
+  buildMutationPack,
   buildPageIR,
+  buildPagePack,
+  buildReviewPack,
+  buildScaffoldPack,
+  buildSectionPack,
+  compileExecutionPackBundle,
+  compileSelectedExecutionPack,
   countPatterns,
   findNodes,
+  listPackPages,
+  listPackSections,
   pascalCase,
+  renderExecutionPackMarkdown,
   resolveEssence,
+  resolvePackAdapter,
   resolveVisualEffects,
   runPipeline,
+  selectExecutionPackFromBundle,
   validateIR,
   walkIR
 };