@decantr/core 1.0.1 → 1.0.3

package/dist/index.js

@@ -1,9 +1,6 @@
-// src/pipeline.ts
-import { validateEssence, isV3 as isV32, migrateV2ToV3 } from "@decantr/essence-spec";
-import { createResolver } from "@decantr/registry";
-
 // src/resolve.ts
-import { isSimple, isSectioned, isV3, computeDensity } from "@decantr/essence-spec";
+import { computeDensity, isSectioned, isSimple, isV3 } from "@decantr/essence-spec";
+import { detectWirings, resolvePatternPreset } from "@decantr/registry";
 
 // src/utils.ts
 function pascalCase(str) {
@@ -11,7 +8,6 @@ function pascalCase(str) {
 }
 
 // src/resolve.ts
-import { resolvePatternPreset, detectWirings } from "@decantr/registry";
 var NAV_ICONS = {
   overview: "layout-dashboard",
   dashboard: "layout-dashboard",
@@ -58,7 +54,11 @@ function extractLayoutRefs(layout) {
       refs.push({ id: item.pattern, explicitPreset: item.preset, alias: item.as });
     } else if (isColumnLayout(item)) {
       for (const col of item.cols) {
-        refs.push({ id: col });
+        if (typeof col === "string") {
+          refs.push({ id: col });
+        } else {
+          refs.push({ id: col.pattern, explicitPreset: col.preset, alias: col.as });
+        }
       }
     }
   }
@@ -249,10 +249,13 @@ async function resolveEssence(essence, resolver) {
     registryTheme = themeResult.item;
   }
   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 density = computeDensity(
+    simpleEssence.personality,
+    themeSpatial ? {
+      density_bias: themeSpatial.density_bias,
+      content_gap_shift: themeSpatial.content_gap_shift
+    } : void 0
+  );
   const themeId = simpleEssence.theme.id;
   const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
   const theme = buildTheme(simpleEssence, isAddon);
@@ -293,10 +296,13 @@ async function resolveV3Essence(essence, resolver) {
     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 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
@@ -305,10 +311,17 @@ async function resolveV3Essence(essence, resolver) {
   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 defaultShell = blueprint.shell ?? blueprint.sections?.[0]?.shell ?? "sidebar-main";
   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)];
+    (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);
@@ -390,15 +403,20 @@ function buildPatternNode(patternId, alias, resolved, wiring, theme, density, la
   const isStandalone = layout === "hero" || layout === "row";
   const contained = pattern && preset ? shouldWrapInCard(pattern, preset, theme) : false;
   const components = pattern?.components || [];
+  const presetName = preset?.preset || "default";
+  const presetDescription = pattern?.presets?.[presetName]?.description;
+  const interactions = Array.isArray(pattern?.interactions) ? pattern.interactions : void 0;
   const patternMeta = {
     patternId,
-    preset: preset?.preset || "default",
+    preset: presetName,
     alias,
     layout,
     contained,
     standalone: isStandalone,
     code: preset?.code ? { imports: preset.code.imports, example: preset.code.example } : null,
-    components
+    components,
+    ...presetDescription ? { presetDescription } : {},
+    ...interactions && interactions.length > 0 ? { interactions } : {}
   };
   const card = contained && !isStandalone && pattern ? buildCardWrapping(pattern, theme) : null;
   const wireProps = wiring?.props[alias] || wiring?.props[patternId] || null;
@@ -426,27 +444,32 @@ function buildPageIR(page, resolvedPatterns, wiring, theme, density, layer) {
       const resolved = resolvedPatterns.get(alias) || resolvedPatterns.get(item.pattern);
       children.push(buildPatternNode(item.pattern, alias, resolved, wiring, theme, density, layer));
     } else if (isColumnLayout2(item)) {
-      const cols = item.cols;
+      const colEntries = item.cols.map((col) => ({
+        id: typeof col === "string" ? col : col.pattern,
+        alias: typeof col === "string" ? col : col.as ?? col.pattern
+      }));
       const breakpoint = item.at || null;
       const spans = item.span || null;
       let normalizedSpans = null;
       if (spans) {
         normalizedSpans = {};
-        for (const col of cols) {
-          normalizedSpans[col] = spans[col] || 1;
+        for (const entry of colEntries) {
+          normalizedSpans[entry.id] = spans[entry.id] || spans[entry.alias] || 1;
         }
       }
       const gridChildren = [];
-      for (const col of cols) {
-        const resolved = resolvedPatterns.get(col);
-        gridChildren.push(buildPatternNode(col, col, resolved, wiring, theme, density, layer));
+      for (const entry of colEntries) {
+        const resolved = resolvedPatterns.get(entry.alias) || resolvedPatterns.get(entry.id);
+        gridChildren.push(
+          buildPatternNode(entry.id, entry.alias, resolved, wiring, theme, density, layer)
+        );
       }
-      const totalCols = normalizedSpans ? Object.values(normalizedSpans).reduce((a, b) => a + b, 0) : cols.length;
+      const totalCols = normalizedSpans ? Object.values(normalizedSpans).reduce((a, b) => a + b, 0) : colEntries.length;
       const breakpoints = item.breakpoints?.map((bp) => ({ at: bp.at, cols: bp.cols })) || null;
       const responsive = item.responsive || null;
       const gridNode = {
         type: "grid",
-        id: `grid-${cols.join("-")}`,
+        id: `grid-${colEntries.map((e) => e.id).join("-")}`,
         children: gridChildren,
         cols: totalCols,
         spans: normalizedSpans,
@@ -460,7 +483,7 @@ function buildPageIR(page, resolvedPatterns, wiring, theme, density, layer) {
     }
   }
   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`;
+  const surface = page.surface || `_flex _col ${gapAtom}`;
   return {
     type: "page",
     id: page.id,
@@ -472,12 +495,63 @@ function buildPageIR(page, resolvedPatterns, wiring, theme, density, layer) {
   };
 }
 
+// src/ir-helpers.ts
+function walkIR(node, visitor, parent = null) {
+  visitor(node, parent);
+  for (const child of node.children) {
+    walkIR(child, visitor, node);
+  }
+}
+function findNodes(root, type) {
+  const results = [];
+  walkIR(root, (node) => {
+    if (node.type === type) {
+      results.push(node);
+    }
+  });
+  return results;
+}
+function countPatterns(root) {
+  return findNodes(root, "pattern").length;
+}
+function validateIR(root) {
+  const errors = [];
+  walkIR(root, (node, parent) => {
+    if (node.type === "grid") {
+      const grid = node;
+      if (grid.children.length === 0) {
+        errors.push(`Grid node "${grid.id}" has no children`);
+      }
+    }
+    if (node.type === "pattern") {
+      const pattern = node;
+      if (!pattern.pattern) {
+        errors.push(`Pattern node "${pattern.id}" is missing pattern meta`);
+      }
+      if (!pattern.pattern.patternId) {
+        errors.push(`Pattern node "${pattern.id}" has no patternId`);
+      }
+    }
+    if (node.type === "page") {
+      if (!node.id) {
+        errors.push("Page node is missing id");
+      }
+    }
+  });
+  return errors;
+}
+
+// src/packs.ts
+import { isV3 as isV33, migrateV2ToV3 as migrateV2ToV32 } from "@decantr/essence-spec";
+
 // src/pipeline.ts
+import { isV3 as isV32, migrateV2ToV3, validateEssence } from "@decantr/essence-spec";
+import { createResolver } from "@decantr/registry";
 function extractRouting(essence) {
   if (isV32(essence)) {
-    return essence.meta.platform.routing || "hash";
+    return essence.meta.platform.routing || "history";
   }
-  return essence.platform?.routing || "hash";
+  return essence.platform?.routing || "history";
 }
 async function runPipeline(essence, options) {
   const validation = validateEssence(essence);
@@ -538,57 +612,10 @@ async function runPipeline(essence, options) {
     store: storeNode,
     features: resolved.features
   };
-  return { ir: appNode };
-}
-
-// src/ir-helpers.ts
-function walkIR(node, visitor, parent = null) {
-  visitor(node, parent);
-  for (const child of node.children) {
-    walkIR(child, visitor, node);
-  }
-}
-function findNodes(root, type) {
-  const results = [];
-  walkIR(root, (node) => {
-    if (node.type === type) {
-      results.push(node);
-    }
-  });
-  return results;
-}
-function countPatterns(root) {
-  return findNodes(root, "pattern").length;
-}
-function validateIR(root) {
-  const errors = [];
-  walkIR(root, (node, parent) => {
-    if (node.type === "grid") {
-      const grid = node;
-      if (grid.children.length === 0) {
-        errors.push(`Grid node "${grid.id}" has no children`);
-      }
-    }
-    if (node.type === "pattern") {
-      const pattern = node;
-      if (!pattern.pattern) {
-        errors.push(`Pattern node "${pattern.id}" is missing pattern meta`);
-      }
-      if (!pattern.pattern.patternId) {
-        errors.push(`Pattern node "${pattern.id}" has no patternId`);
-      }
-    }
-    if (node.type === "page") {
-      if (!node.id) {
-        errors.push("Page node is missing id");
-      }
-    }
-  });
-  return errors;
+  return { ir: appNode, registryTheme: resolved.registryTheme };
 }
 
 // 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",
@@ -748,12 +775,14 @@ 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
-    }];
+    return [
+      {
+        pageId: pageNode.pageId,
+        path: route.path,
+        patternIds: collectPatternIds(pageNode),
+        shell: route.shell
+      }
+    ];
   });
 }
 function summarizeSectionRoutes(appNode, input) {
@@ -775,7 +804,9 @@ function collectPagePatterns(page) {
       id: patternNode.pattern.patternId,
       alias: patternNode.pattern.alias,
       preset: patternNode.pattern.preset,
-      layout: patternNode.pattern.layout
+      layout: patternNode.pattern.layout,
+      ...patternNode.pattern.presetDescription ? { presetDescription: patternNode.pattern.presetDescription } : {},
+      ...patternNode.pattern.interactions && patternNode.pattern.interactions.length > 0 ? { interactions: patternNode.pattern.interactions } : {}
     });
   });
   return patterns;
@@ -791,43 +822,108 @@ function renderList(title, entries) {
   if (entries.length === 0) return [];
   return [title, ...entries.map((entry) => `- ${entry}`), ""];
 }
+function formatHotkeySemantics(semantics) {
+  if (!semantics) return "";
+  const parts = [];
+  if (typeof semantics.chord_window_ms === "number") {
+    parts.push(`chord window ${semantics.chord_window_ms}ms`);
+  }
+  if (semantics.input_guard === true) parts.push("suppress during text-input focus");
+  if (semantics.input_guard === false) parts.push("fire even while typing (explicit)");
+  if (semantics.modifier_suppression === true) parts.push("ignore when modifier held");
+  if (semantics.modifier_suppression === false) parts.push("allow modifier passthrough (explicit)");
+  if (semantics.match_case === true) parts.push("case-sensitive");
+  return parts.join("; ");
+}
+function routingImplementationHint(routing) {
+  switch (routing) {
+    case "hash":
+      return "HashRouter from react-router-dom; URLs prefixed with /# (e.g. /#/login). Only for static-only hosts without SPA fallback.";
+    case "history":
+      return "BrowserRouter from react-router-dom; regular URLs (e.g. /login). Works on Vite dev, Vercel, Netlify, Cloudflare Pages.";
+    case "pathname":
+      return "pathname-based routing (Next.js App Router file conventions).";
+    default:
+      return String(routing);
+  }
+}
 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(
+    `**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))];
+    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(
+        `- Shells: ${[`${scaffoldPack.data.shell} (primary)`, ...secondaryShells].join(", ")}`
+      );
     }
     lines.push(`- Theme: ${scaffoldPack.data.theme.id} (${scaffoldPack.data.theme.mode})`);
-    lines.push(`- Routing: ${scaffoldPack.data.routing}`);
+    lines.push(
+      `- Routing: ${scaffoldPack.data.routing} \u2192 ${routingImplementationHint(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");
+      const cp = scaffoldPack.data.navigation.commandPalette;
+      if (cp) {
+        if (typeof cp === "object") {
+          lines.push("  - Command palette:");
+          if (cp.trigger) lines.push(`    - Trigger: ${cp.trigger}`);
+          if (cp.styling)
+            lines.push(`    - Styling: ${cp.styling}${cp.width ? ` (width ${cp.width})` : ""}`);
+          else if (cp.width) lines.push(`    - Width: ${cp.width}`);
+          if (cp.placeholder) lines.push(`    - Placeholder: "${cp.placeholder}"`);
+          if (cp.commands && cp.commands.length > 0) {
+            lines.push(`    - Commands (${cp.commands.length}):`);
+            for (const command of cp.commands) {
+              const parts = [];
+              if (command.section) parts.push(command.section);
+              parts.push(command.label);
+              if (command.hotkey) parts.push(`[${command.hotkey}]`);
+              if (command.route) parts.push(`\u2192 ${command.route}`);
+              lines.push(`      - ${command.id}: ${parts.join(" \xB7 ")}`);
+            }
+          }
+        } else {
+          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}` : ""}`);
+      const globalSemantics = scaffoldPack.data.navigation.hotkeySemantics;
+      if (scaffoldPack.data.navigation.hotkeys.length > 0) {
+        const semanticsSummary = formatHotkeySemantics(globalSemantics);
+        lines.push(`  - Hotkeys${semanticsSummary ? ` (${semanticsSummary})` : ""}:`);
+        for (const hotkey of scaffoldPack.data.navigation.hotkeys) {
+          const target = [hotkey.label, hotkey.route].filter(Boolean).join(" \u2014 ");
+          const perKeySemantics = formatHotkeySemantics(hotkey.semantics);
+          const suffix = perKeySemantics ? ` _(${perKeySemantics})_` : "";
+          lines.push(`    - ${hotkey.key}${target ? `: ${target}` : ""}${suffix}`);
+        }
       }
     }
     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(
+        `- ${route.path} -> ${route.pageId}${route.shell ? ` @ ${route.shell}` : ""} [${patterns}]`
+      );
     }
     lines.push("");
   }
@@ -848,9 +944,57 @@ function renderExecutionPackMarkdown(pack) {
     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(
+        `- ${route.path} -> ${route.pageId}${route.shell ? ` @ ${route.shell}` : ""} [${patterns}]`
+      );
     }
     lines.push("");
+    if (sectionPack.data.navigationItems && sectionPack.data.navigationItems.length > 0) {
+      lines.push("## Section Navigation");
+      lines.push("");
+      lines.push(
+        "Render these items in the shell's primary navigation. Exact match on label, route, and icon."
+      );
+      lines.push("");
+      for (const item of sectionPack.data.navigationItems) {
+        const parts = [`${item.label} \u2192 ${item.route}`];
+        if (item.icon) parts.push(`icon: ${item.icon}`);
+        if (item.hotkey) parts.push(`hotkey: ${item.hotkey}`);
+        if (item.badge) parts.push(`badge: ${item.badge}`);
+        if (item.active_match) parts.push(`active match: \`${item.active_match}\``);
+        lines.push(`- ${parts.join(" \xB7 ")}`);
+      }
+      lines.push("");
+    }
+    if (sectionPack.data.directives && sectionPack.data.directives.length > 0) {
+      lines.push("## Section Directives");
+      lines.push("");
+      lines.push(
+        "Execution-level rules every page in this section must obey. Follow exactly \u2014 these live in the pack contract, not narrative prose."
+      );
+      lines.push("");
+      for (const directive of sectionPack.data.directives) {
+        lines.push(`- ${directive}`);
+      }
+      lines.push("");
+    }
+    if (sectionPack.data.themeDecorators && sectionPack.data.themeDecorators.length > 0) {
+      const escCell = (s) => s.replace(/\|/g, "\\|");
+      lines.push(`## Required Theme Decorators (${sectionPack.data.theme.id})`);
+      lines.push("");
+      lines.push(
+        `These classes carry the active theme's visual identity. Tokens alone give bones; decorators give personality. Generated source MUST apply these \u2014 without them, the page reads as "themed colors only" with no theme character.`
+      );
+      lines.push("");
+      lines.push("| Class | Intent | Apply to |");
+      lines.push("|-------|--------|----------|");
+      for (const entry of sectionPack.data.themeDecorators) {
+        lines.push(
+          `| \`.${entry.class}\` | ${escCell(entry.intent)} | ${escCell(entry.applyTo)} |`
+        );
+      }
+      lines.push("");
+    }
   }
   if (pack.packType === "page") {
     const pagePack = pack;
@@ -872,7 +1016,18 @@ function renderExecutionPackMarkdown(pack) {
     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(
+        `- ${pattern.alias} -> ${pattern.id} [${pattern.layout}${pattern.preset ? ` | ${pattern.preset}` : ""}]`
+      );
+      if (pattern.presetDescription) {
+        lines.push(`  > ${pattern.presetDescription}`);
+      }
+      if (pattern.interactions && pattern.interactions.length > 0) {
+        lines.push(`  **Interactions (MUST implement each \u2014 see DECANTR.md "Interaction Requirements"):**`);
+        for (const interaction of pattern.interactions) {
+          lines.push(`  - [ ] ${interaction}`);
+        }
+      }
     }
     lines.push("");
     if (pagePack.data.wiringSignals.length > 0) {
@@ -882,6 +1037,16 @@ function renderExecutionPackMarkdown(pack) {
       }
       lines.push("");
     }
+    if (pagePack.data.directives && pagePack.data.directives.length > 0) {
+      lines.push("## Page Directives");
+      lines.push("");
+      lines.push("Execution-level rules for this route. Follow exactly.");
+      lines.push("");
+      for (const directive of pagePack.data.directives) {
+        lines.push(`- ${directive}`);
+      }
+      lines.push("");
+    }
   }
   if (pack.packType === "mutation") {
     const mutationPack = pack;
@@ -889,7 +1054,9 @@ function renderExecutionPackMarkdown(pack) {
     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}`);
+    lines.push(
+      `- Routing: ${mutationPack.data.routing} \u2192 ${routingImplementationHint(mutationPack.data.routing)}`
+    );
     if (mutationPack.data.features.length > 0) {
       lines.push(`- Features: ${mutationPack.data.features.join(", ")}`);
     }
@@ -897,7 +1064,9 @@ function renderExecutionPackMarkdown(pack) {
     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(
+        `- ${route.path} -> ${route.pageId}${route.shell ? ` @ ${route.shell}` : ""} [${patterns}]`
+      );
     }
     lines.push("");
     if (mutationPack.data.workflow.length > 0) {
@@ -922,7 +1091,9 @@ function renderExecutionPackMarkdown(pack) {
     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(
+        `- ${route.path} -> ${route.pageId}${route.shell ? ` @ ${route.shell}` : ""} [${patterns}]`
+      );
     }
     lines.push("");
     if (reviewPack.data.focusAreas.length > 0) {
@@ -940,6 +1111,14 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("");
     }
   }
+  if (pack.packType === "page") {
+    lines.push("## Shared Contract");
+    lines.push(
+      "Required setup, allowed vocabulary, success checks, anti-patterns, and token budget are shared across every page pack. The full list lives in the pack JSON sidecar (`page-<id>-pack.json`) and in the pack-manifest. Refer there instead of re-reading the same boilerplate 16 times."
+    );
+    lines.push("");
+    return lines.join("\n").trimEnd() + "\n";
+  }
   lines.push("## Required Setup");
   if (pack.requiredSetup.length === 0) {
     lines.push("- None declared.");
@@ -954,9 +1133,24 @@ function renderExecutionPackMarkdown(pack) {
     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(
+    ...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}`);
@@ -976,35 +1170,45 @@ 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}`)
+      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);
+      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
+        pageIds,
+        ...Array.isArray(section.navigation_items) && section.navigation_items.length > 0 ? { navigationItems: section.navigation_items } : {},
+        ...Array.isArray(section.directives) && section.directives.length > 0 ? { directives: section.directives } : {}
       };
     }).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)
-  }];
+  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}`)
+      Object.values(essence.blueprint.routes ?? {}).map(
+        (entry) => `${entry.section}:${entry.page}`
+      )
     );
     return declaredSections.flatMap(
       (section) => section.pages.map((page) => ({
@@ -1012,8 +1216,11 @@ function listPackPages(essence) {
         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}`))
+        features: section.features,
+        ...Array.isArray(page.directives) && page.directives.length > 0 ? { directives: page.directives } : {}
+      })).filter(
+        (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${page.sectionId}:${page.pageId}`)
+      )
     );
   }
   const pages = essence.blueprint.pages ?? [{ id: "home", layout: ["hero"] }];
@@ -1048,13 +1255,15 @@ function buildScaffoldPack(appNode, options = {}) {
       "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
-    ])],
+    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,
@@ -1098,15 +1307,17 @@ function buildSectionPack(appNode, input, options = {}) {
       "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
-    ])],
+    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,
@@ -1122,7 +1333,10 @@ function buildSectionPack(appNode, input, options = {}) {
         mode: appNode.theme.mode,
         shape: appNode.theme.shape
       },
-      routes
+      routes,
+      ...input.navigationItems && input.navigationItems.length > 0 ? { navigationItems: input.navigationItems } : {},
+      ...input.directives && input.directives.length > 0 ? { directives: input.directives } : {},
+      ...options.themeDecorators && options.themeDecorators.length > 0 ? { themeDecorators: options.themeDecorators } : {}
     },
     renderedMarkdown: ""
   };
@@ -1155,16 +1369,20 @@ function buildPagePack(appNode, input, options = {}) {
       "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))],
+    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,
@@ -1183,7 +1401,8 @@ function buildPagePack(appNode, input, options = {}) {
         shape: appNode.theme.shape
       },
       wiringSignals: pageNode.wiring?.signals.map((signal) => signal.name) ?? [],
-      patterns
+      patterns,
+      ...input.directives && input.directives.length > 0 ? { directives: input.directives } : {}
     },
     renderedMarkdown: ""
   };
@@ -1221,14 +1440,16 @@ function buildMutationPack(appNode, options) {
       "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
-    ])],
+    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],
@@ -1286,15 +1507,17 @@ function buildReviewPack(appNode, options = {}) {
       "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
-    ])],
+    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,
@@ -1331,32 +1554,57 @@ async function compileExecutionPackBundle(essence, options = {}) {
     overridePaths: options.overridePaths,
     resolver: options.resolver
   });
+  const navMeta = effectiveEssence.meta.navigation;
+  const commandPaletteValue = typeof navMeta?.command_palette === "object" && navMeta.command_palette !== null ? navMeta.command_palette : Boolean(navMeta?.command_palette);
   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) => ({
+      commandPalette: commandPaletteValue,
+      hotkeys: Array.isArray(navMeta?.hotkeys) ? navMeta.hotkeys.filter(
+        (hotkey) => Boolean(
+          hotkey && typeof hotkey.key === "string" && typeof hotkey.label === "string"
+        )
+      ).map((hotkey) => ({
         key: hotkey.key,
         route: hotkey.route,
-        label: hotkey.label
-      })) : []
+        label: hotkey.label,
+        ...hotkey.semantics ? { semantics: hotkey.semantics } : {}
+      })) : [],
+      ...navMeta?.hotkey_semantics ? { hotkeySemantics: navMeta.hotkey_semantics } : {}
     }
   });
   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 themeDecorators = (() => {
+    const defs = pipeline.registryTheme?.decorator_definitions;
+    if (!defs) return void 0;
+    const entries = [];
+    for (const [name, def] of Object.entries(defs)) {
+      const intent = def.intent || def.description || "";
+      const applyTo = (def.usage || []).join(", ");
+      if (!intent && !applyTo) continue;
+      entries.push({ class: name, intent, applyTo });
+    }
+    return entries.length > 0 ? entries : void 0;
+  })();
+  const sections = listPackSections(effectiveEssence).map(
+    (section) => buildSectionPack(pipeline.ir, section, {
+      target: sharedTarget,
+      ...themeDecorators ? { themeDecorators } : {}
+    })
+  );
+  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",