@decantr/core 1.0.6 → 2.1.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/resolve.ts
-import { computeDensity, isSectioned, isSimple, isV3 } from "@decantr/essence-spec";
+import { computeDensity, isV4 } from "@decantr/essence-spec";
 import { detectWirings, resolvePatternPreset } from "@decantr/registry";
 
 // src/utils.ts
@@ -115,15 +115,7 @@ function buildThemeDecoration(theme) {
     dimensions: shell.dimensions || null
   };
 }
-function buildTheme(essence, isAddon) {
-  return {
-    id: essence.theme.id,
-    mode: essence.theme.mode,
-    shape: essence.theme.shape || null,
-    isAddon
-  };
-}
-function buildThemeFromV3(essence, isAddon) {
+function buildThemeFromV4(essence, isAddon) {
   const dna = essence.dna;
   return {
     id: dna.theme.id,
@@ -145,7 +137,7 @@ function blueprintPageToStructurePage(page, defaultShell, sectionId) {
 function routeIdentity(pageId, sectionId) {
   return sectionId ? `${sectionId}:${pageId}` : pageId;
 }
-function buildV3Routes(essence, structurePages) {
+function buildV4Routes(essence, structurePages) {
   const explicitRoutes = /* @__PURE__ */ new Map();
   for (const [path, entry] of Object.entries(essence.blueprint.routes ?? {})) {
     if (!entry?.page) continue;
@@ -230,81 +222,14 @@ function resolveVisualEffects(theme, pattern, _slot) {
   };
 }
 async function resolveEssence(essence, resolver) {
-  if (isV3(essence)) {
-    return resolveV3Essence(essence, resolver);
-  }
-  let simpleEssence;
-  if (isSimple(essence)) {
-    simpleEssence = essence;
-  } else if (isSectioned(essence)) {
-    const sectioned = essence;
-    if (sectioned.sections.length > 1) {
-      throw new Error(
-        `Sectioned essences with ${sectioned.sections.length} sections are not yet supported. Only single-section sectioned essences can be processed. Consider migrating to v3 format using migrateV2ToV3().`
-      );
-    }
-    const firstSection = sectioned.sections[0];
-    simpleEssence = {
-      version: sectioned.version,
-      archetype: firstSection.archetype,
-      theme: firstSection.theme,
-      personality: sectioned.personality,
-      platform: sectioned.platform,
-      structure: firstSection.structure,
-      features: firstSection.features || [],
-      density: sectioned.density,
-      guard: sectioned.guard,
-      target: sectioned.target
-    };
-  } else {
-    throw new Error("Invalid essence format");
-  }
-  let registryTheme = null;
-  const themeResult = await resolver.resolve("theme", simpleEssence.theme.id);
-  if (themeResult) {
-    registryTheme = themeResult.item;
+  if (!isV4(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
   }
-  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 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, registryTheme);
-  const shellType = simpleEssence.structure[0]?.shell || "sidebar-main";
-  const brand = pascalCase(simpleEssence.archetype);
-  const nav = buildNavItems(simpleEssence.structure);
-  const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
-  const shell = {
-    type: shellType,
-    brand,
-    nav,
-    inset: false,
-    decoration
-  };
-  const routes = simpleEssence.structure.map((page, i) => ({
-    path: routePath(page.id, i),
-    pageId: page.id,
-    shell: page.shell
-  }));
-  return {
-    essence,
-    pages: resolvedPages,
-    registryTheme,
-    density: { gap: density.content_gap, level: density.level },
-    theme,
-    shell,
-    routes,
-    features: simpleEssence.features ?? [],
-    isV3Source: false
-  };
+  return resolveV4Essence(essence, resolver);
 }
-async function resolveV3Essence(essence, resolver) {
+async function resolveV4Essence(essence, resolver) {
   const { dna, blueprint, meta } = essence;
   let registryTheme = null;
   const themeResult = await resolver.resolve("theme", dna.theme.id);
@@ -325,22 +250,17 @@ async function resolveV3Essence(essence, resolver) {
   };
   const themeId = dna.theme.id;
   const isAddon = themeId.startsWith("custom:") || !CORE_STYLES.has(themeId);
-  const theme = buildThemeFromV3(essence, isAddon);
-  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(
+  const theme = buildThemeFromV4(essence, isAddon);
+  const defaultShell = blueprint.shell ?? blueprint.sections[0]?.shell ?? "sidebar-main";
+  const structurePages = blueprint.sections.flatMap(
     (section) => section.pages.map(
       (page) => blueprintPageToStructurePage(page, section.shell ?? defaultShell, section.id)
     )
-  ) : [
-    blueprintPageToStructurePage(
-      { id: "home", layout: ["hero"] },
-      defaultShell
-    )
-  ];
+  );
   const resolvedPages = await resolvePages(structurePages, resolver, registryTheme);
   const shellType = defaultShell;
   const brand = pascalCase(meta.archetype);
-  const routes = buildV3Routes(essence, structurePages);
+  const routes = buildV4Routes(essence, structurePages);
   const nav = buildNavItems(structurePages, routes);
   const decoration = registryTheme ? buildThemeDecoration(registryTheme) : null;
   const shell = {
@@ -359,7 +279,7 @@ async function resolveV3Essence(essence, resolver) {
     shell,
     routes,
     features: blueprint.features ?? [],
-    isV3Source: true
+    isBlueprintSource: true
   };
 }
 async function resolvePages(pages, resolver, registryTheme) {
@@ -558,23 +478,19 @@ function validateIR(root) {
 }
 
 // src/packs.ts
-import { isV3 as isV33, migrateV2ToV3 as migrateV2ToV32 } from "@decantr/essence-spec";
+import { isV4 as isV42 } from "@decantr/essence-spec";
 
 // src/pipeline.ts
-import { isV3 as isV32, migrateV2ToV3, validateEssence } from "@decantr/essence-spec";
+import { validateEssence } from "@decantr/essence-spec";
 import { createResolver } from "@decantr/registry";
 function extractRouting(essence) {
-  if (isV32(essence)) {
-    return essence.meta.platform.routing || "history";
-  }
-  return essence.platform?.routing || "history";
+  return essence.meta.platform.routing || "history";
 }
 async function runPipeline(essence, options) {
   const validation = validateEssence(essence);
   if (!validation.valid) {
     throw new Error(`Invalid essence: ${validation.errors.join(", ")}`);
   }
-  const effectiveEssence = isV32(essence) ? essence : migrateV2ToV3(essence);
   const resolver = options.resolver ?? (() => {
     if (!options.contentRoot) {
       throw new Error("Pipeline options must include either a contentRoot or a resolver.");
@@ -584,8 +500,8 @@ async function runPipeline(essence, options) {
       overridePaths: options.overridePaths
     });
   })();
-  const resolved = await resolveEssence(effectiveEssence, resolver);
-  const layer = resolved.isV3Source ? "blueprint" : void 0;
+  const resolved = await resolveEssence(essence, resolver);
+  const layer = "blueprint";
   const pageNodes = [];
   for (const rp of resolved.pages) {
     const pageIR = buildPageIR(
@@ -779,13 +695,13 @@ var DEFAULT_REVIEW_ANTI_PATTERNS = [
   }
 ];
 function collectPatternIds(page) {
-  const patternIds = [];
+  const patternIds2 = [];
   walkIR(page, (node) => {
     if (node.type !== "pattern") return;
     const patternNode = node;
-    patternIds.push(patternNode.pattern.patternId);
+    patternIds2.push(patternNode.pattern.patternId);
   });
-  return [...new Set(patternIds)];
+  return [...new Set(patternIds2)];
 }
 function pageIdentity(pageId, sectionId) {
   return sectionId ? `${sectionId}/${pageId}` : pageId;
@@ -882,6 +798,16 @@ function routingImplementationHint(routing) {
 }
 function renderExecutionPackMarkdown(pack) {
   const lines = [];
+  const escapeMarkdownCell = (value) => {
+    let escaped = "";
+    for (const char of value) {
+      if (char === "\\") escaped += "\\\\";
+      else if (char === "|") escaped += "\\|";
+      else if (char === "\n" || char === "\r") escaped += "<br>";
+      else escaped += char;
+    }
+    return escaped;
+  };
   lines.push(`# ${pack.packType.charAt(0).toUpperCase()}${pack.packType.slice(1)} Pack`);
   lines.push("");
   lines.push(`**Objective:** ${pack.objective}`);
@@ -960,7 +886,6 @@ function renderExecutionPackMarkdown(pack) {
     }
     lines.push("");
     if (scaffoldPack.data.themeDecorators && scaffoldPack.data.themeDecorators.length > 0) {
-      const escScaffoldCell = (s) => s.replace(/\|/g, "\\|");
       lines.push(`## Required Theme Decorators (${scaffoldPack.data.theme.id})`);
       lines.push("");
       lines.push(
@@ -971,7 +896,7 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("|-------|--------|----------|");
       for (const entry of scaffoldPack.data.themeDecorators) {
         lines.push(
-          `| \`.${entry.class}\` | ${escScaffoldCell(entry.intent)} | ${escScaffoldCell(entry.applyTo)} |`
+          `| \`.${entry.class}\` | ${escapeMarkdownCell(entry.intent)} | ${escapeMarkdownCell(entry.applyTo)} |`
         );
       }
       lines.push("");
@@ -1029,7 +954,6 @@ function renderExecutionPackMarkdown(pack) {
       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(
@@ -1040,7 +964,7 @@ function renderExecutionPackMarkdown(pack) {
       lines.push("|-------|--------|----------|");
       for (const entry of sectionPack.data.themeDecorators) {
         lines.push(
-          `| \`.${entry.class}\` | ${escCell(entry.intent)} | ${escCell(entry.applyTo)} |`
+          `| \`.${entry.class}\` | ${escapeMarkdownCell(entry.intent)} | ${escapeMarkdownCell(entry.applyTo)} |`
         );
       }
       lines.push("");
@@ -1080,7 +1004,9 @@ function renderExecutionPackMarkdown(pack) {
         lines.push(`  > ${pattern.presetDescription}`);
       }
       if (pattern.interactions && pattern.interactions.length > 0) {
-        lines.push(`  **Interactions (MUST implement each \u2014 see DECANTR.md "Interaction Requirements"):**`);
+        lines.push(
+          `  **Interactions (MUST implement each \u2014 see DECANTR.md "Interaction Requirements"):**`
+        );
         for (const interaction of pattern.interactions) {
           lines.push(`  - [ ] ${interaction}`);
         }
@@ -1216,79 +1142,57 @@ function renderExecutionPackMarkdown(pack) {
   return lines.join("\n").trimEnd() + "\n";
 }
 function resolvePackAdapter(target, platformType) {
+  if (target === "html" || target === "vanilla" || target === "javascript" || target === "js") {
+    return "vanilla-vite";
+  }
   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 === "sveltekit") return "sveltekit";
+  if (target === "angular") return "angular";
+  if (target === "solid" || target === "solidjs") return "solid-vite";
   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,
-        ...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)
-    }
-  ];
+  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,
+      ...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);
 }
 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,
-        ...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"] }];
-  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 || []
-  }));
+  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,
+      ...Array.isArray(page.directives) && page.directives.length > 0 ? { directives: page.directives } : {}
+    })).filter(
+      (page) => routedSectionPages.size === 0 || routedSectionPages.has(`${page.sectionId}:${page.pageId}`)
+    )
+  );
 }
 function buildPageManifestEntries(pages) {
   const counts = /* @__PURE__ */ new Map();
@@ -1618,19 +1522,23 @@ function buildReviewPack(appNode, options = {}) {
   return pack;
 }
 async function compileExecutionPackBundle(essence, options = {}) {
-  const effectiveEssence = isV33(essence) ? essence : migrateV2ToV32(essence);
+  if (!isV42(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
+  }
   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)
+    framework: essence.meta.target || null,
+    runtime: essence.meta.platform.type || null,
+    adapter: resolvePackAdapter(essence.meta.target, essence.meta.platform.type)
   };
   const pipeline = await runPipeline(essence, {
     contentRoot: options.contentRoot,
     overridePaths: options.overridePaths,
     resolver: options.resolver
   });
-  const navMeta = effectiveEssence.meta.navigation;
+  const navMeta = essence.meta.navigation;
   const commandPaletteValue = typeof navMeta?.command_palette === "object" && navMeta.command_palette !== null ? navMeta.command_palette : Boolean(navMeta?.command_palette);
   const themeDecorators = (() => {
     const defs = pipeline.registryTheme?.decorator_definitions;
@@ -1665,8 +1573,8 @@ async function compileExecutionPackBundle(essence, options = {}) {
   const review = buildReviewPack(pipeline.ir, {
     target: sharedTarget
   });
-  const sectionInputs = listPackSections(effectiveEssence);
-  const pageInputs = listPackPages(effectiveEssence);
+  const sectionInputs = listPackSections(essence);
+  const pageInputs = listPackPages(essence);
   const sections = sectionInputs.map(
     (section) => buildSectionPack(pipeline.ir, section, {
       target: sharedTarget
@@ -1773,6 +1681,114 @@ async function compileSelectedExecutionPack(essence, selector, options = {}) {
   const bundle = await compileExecutionPackBundle(essence, options);
   return selectExecutionPackFromBundle(bundle, selector);
 }
+
+// src/realization.ts
+import { isV4 as isV43 } from "@decantr/essence-spec";
+var CERTIFIED_REALIZATION_ADAPTERS = /* @__PURE__ */ new Set([
+  "react-vite",
+  "next-app",
+  "vanilla-vite",
+  "vue-vite",
+  "sveltekit",
+  "angular",
+  "solid-vite"
+]);
+function routePath2(page, fallbackIndex) {
+  if (page.route) return page.route;
+  if (page.id === "home" || fallbackIndex === 0) return "/";
+  return `/${page.id}`;
+}
+function patternIds(layout) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const item of layout) {
+    if (typeof item === "string") {
+      ids.add(item);
+    } else if ("pattern" in item) {
+      ids.add(item.pattern);
+    } else if ("cols" in item) {
+      for (const col of item.cols) {
+        ids.add(typeof col === "string" ? col : col.pattern);
+      }
+    }
+  }
+  return [...ids];
+}
+function compileRealizationPlan(essence) {
+  if (!isV43(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
+  }
+  const packAdapter = resolvePackAdapter(essence.meta.target, essence.meta.platform.type);
+  const adapter = essence.meta.target === "nextjs" ? "next-app" : packAdapter;
+  const canRealizeFrameworkCode = CERTIFIED_REALIZATION_ADAPTERS.has(adapter);
+  const routes = [];
+  for (const section of essence.blueprint.sections) {
+    section.pages.forEach((page, pageIndex) => {
+      routes.push({
+        path: routePath2(page, routes.length + pageIndex),
+        sectionId: section.id,
+        sectionRole: section.role,
+        pageId: page.id,
+        shell: page.shell_override ?? section.shell,
+        patterns: patternIds(page.layout),
+        states: ["empty", "loading", "error"]
+      });
+    });
+  }
+  const mockData = [
+    ...essence.blueprint.features.map((feature) => ({
+      id: feature,
+      source: "feature",
+      shape: { enabled: true, status: "mocked" }
+    })),
+    ...routes.map((route) => ({
+      id: route.pageId,
+      source: "route",
+      shape: { title: route.pageId, items: [] }
+    }))
+  ];
+  const navigation = essence.meta.navigation;
+  const interactions = [
+    {
+      id: "auth-mock",
+      kind: "auth-mock",
+      label: "Authenticated user/session placeholder"
+    }
+  ];
+  if (navigation?.command_palette) {
+    interactions.push({
+      id: "command-palette",
+      kind: "command-palette",
+      label: "Command palette placeholder"
+    });
+  }
+  for (const hotkey of navigation?.hotkeys ?? []) {
+    interactions.push({
+      id: `hotkey-${hotkey.key}`,
+      kind: "hotkey",
+      route: hotkey.route,
+      label: hotkey.label
+    });
+  }
+  return {
+    version: "1.0.0",
+    sourceEssenceVersion: "4.0.0",
+    adapter,
+    canRealizeFrameworkCode,
+    routes,
+    shell: {
+      id: essence.blueprint.shell ?? essence.blueprint.sections[0]?.shell ?? "sidebar-main",
+      theme: essence.dna.theme.id,
+      mode: essence.dna.theme.mode
+    },
+    mockData,
+    interactions,
+    ...canRealizeFrameworkCode ? {} : {
+      unsupportedReason: "No certified realization adapter is available for this target yet. Use the V4 contract, execution packs, prompts, and Project Health without generated framework code."
+    }
+  };
+}
 export {
   EXECUTION_PACK_BUNDLE_SCHEMA_URL,
   EXECUTION_PACK_SCHEMA_URLS,
@@ -1785,6 +1801,7 @@ export {
   buildScaffoldPack,
   buildSectionPack,
   compileExecutionPackBundle,
+  compileRealizationPlan,
   compileSelectedExecutionPack,
   countPatterns,
   findNodes,