@decantr/core 1.0.0-beta.9 → 1.0.1

package/dist/index.js

@@ -89,9 +89,12 @@ 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, " "))
   }));
@@ -106,7 +109,7 @@ function buildThemeDecoration(theme) {
     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
@@ -137,6 +140,30 @@ 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);
+    }
+  }
+  if (explicitRoutes.size > 0) {
+    return structurePages.flatMap((page) => {
+      const path = explicitRoutes.get(page.id);
+      return path ? [{ path, pageId: page.id, shell: page.shell }] : [];
+    });
+  }
+  return structurePages.map((page, i) => ({
+    path: routePath(page.id, i),
+    pageId: page.id,
+    shell: page.shell
+  }));
+}
 function convertWiring(wiringResults) {
   if (wiringResults.length === 0) return null;
   const signals = [];
@@ -243,7 +270,8 @@ async function resolveEssence(essence, resolver) {
   };
   const routes = simpleEssence.structure.map((page, i) => ({
     path: routePath(page.id, i),
-    pageId: page.id
+    pageId: page.id,
+    shell: page.shell
   }));
   return {
     essence,
@@ -278,13 +306,14 @@ async function resolveV3Essence(essence, resolver) {
   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 structurePages = blueprint.pages ? blueprint.pages.map((page) => blueprintPageToStructurePage(page, defaultShell)) : blueprint.sections ? blueprint.sections.flatMap(
+    (section) => section.pages.map((page) => blueprintPageToStructurePage(page, section.shell ?? defaultShell))
+  ) : [blueprintPageToStructurePage({ id: "home", layout: ["hero"] }, defaultShell)];
   const resolvedPages = await resolvePages(structurePages, resolver, registryTheme);
   const shellType = defaultShell;
   const brand = pascalCase(meta.archetype);
-  const nav = buildNavItems(structurePages);
+  const routes = buildV3Routes(essence, blueprintPages, structurePages);
+  const nav = buildNavItems(structurePages, routes);
   const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
   const shell = {
     type: shellType,
@@ -293,10 +322,6 @@ async function resolveV3Essence(essence, resolver) {
     inset: false,
     decoration
   };
-  const routes = structurePages.map((page, i) => ({
-    path: routePath(page.id, i),
-    pageId: page.id
-  }));
   return {
     essence,
     pages: resolvedPages,
@@ -434,7 +459,8 @@ function buildPageIR(page, resolvedPatterns, wiring, theme, density, layer) {
       children.push(gridNode);
     }
   }
-  const surface = page.surface || `_flex _col _gap${density.gap} _p4 _overflow[auto] _flex1`;
+  const gapAtom = density.gap.startsWith("_") ? density.gap : density.gap.startsWith("gap") ? `_${density.gap}` : `_gap${density.gap}`;
+  const surface = page.surface || `_flex _col ${gapAtom} _p4 _overauto _flex1`;
   return {
     type: "page",
     id: page.id,
@@ -459,10 +485,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 = [];
@@ -555,14 +586,889 @@ 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.routes.flatMap((route) => {
+    const pageNode = findPageNode(appNode, route.pageId);
+    if (!pageNode) return [];
+    return [{
+      pageId: pageNode.pageId,
+      path: route.path,
+      patternIds: collectPatternIds(pageNode),
+      shell: route.shell
+    }];
+  });
+}
+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;
+    const scaffoldShells = [...new Set(scaffoldPack.data.routes.map((route) => route.shell).filter(Boolean))];
+    lines.push("## Scaffold Contract");
+    lines.push(`- Shell: ${scaffoldPack.data.shell}`);
+    if (scaffoldShells.length > 1) {
+      const secondaryShells = scaffoldShells.filter((shell) => shell !== scaffoldPack.data.shell);
+      lines.push(`- Shells: ${[`${scaffoldPack.data.shell} (primary)`, ...secondaryShells].join(", ")}`);
+    }
+    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(", ")}`);
+    }
+    if (scaffoldPack.data.navigation?.commandPalette || scaffoldPack.data.navigation?.hotkeys.length) {
+      lines.push("- Navigation:");
+      if (scaffoldPack.data.navigation.commandPalette) {
+        lines.push("  - command palette required");
+      }
+      for (const hotkey of scaffoldPack.data.navigation.hotkeys) {
+        const target = [hotkey.label, hotkey.route].filter(Boolean).join(" \u2014 ");
+        lines.push(`  - ${hotkey.key}${target ? `: ${target}` : ""}`);
+      }
+    }
+    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}${route.shell ? ` @ ${route.shell}` : ""} [${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}${route.shell ? ` @ ${route.shell}` : ""} [${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}${route.shell ? ` @ ${route.shell}` : ""} [${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}${route.shell ? ` @ ${route.shell}` : ""} [${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) {
+    const routedSectionPages = new Set(
+      Object.values(essence.blueprint.routes ?? {}).map((entry) => `${entry.section}:${entry.page}`)
+    );
+    return declaredSections.map((section) => {
+      const pageIds = section.pages.filter((page) => routedSectionPages.size === 0 || routedSectionPages.has(`${section.id}:${page.id}`)).map((page) => page.id);
+      return {
+        id: section.id,
+        role: section.role,
+        shell: section.shell,
+        description: section.description,
+        features: section.features,
+        pageIds
+      };
+    }).filter((section) => section.pageIds.length > 0);
+  }
+  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) {
+    const routedSectionPages = new Set(
+      Object.values(essence.blueprint.routes ?? {}).map((entry) => `${entry.section}:${entry.page}`)
+    );
+    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
+      })).filter((page) => routedSectionPages.size === 0 || routedSectionPages.has(`${page.sectionId}:${page.pageId}`))
+    );
+  }
+  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,
+      navigation: options.navigation,
+      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,
+    navigation: {
+      commandPalette: Boolean(effectiveEssence.meta.navigation?.command_palette),
+      hotkeys: Array.isArray(effectiveEssence.meta.navigation?.hotkeys) ? effectiveEssence.meta.navigation.hotkeys.filter((hotkey) => Boolean(
+        hotkey && typeof hotkey.key === "string" && typeof hotkey.label === "string"
+      )).map((hotkey) => ({
+        key: hotkey.key,
+        route: hotkey.route,
+        label: hotkey.label
+      })) : []
+    }
+  });
+  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
 };