@decantr/essence-spec 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/index.js

@@ -1,29 +1,66 @@
 // src/types.ts
+function isV3(essence) {
+  return (essence.version === "3.0.0" || essence.version === "3.1.0") && "dna" in essence && "blueprint" in essence;
+}
+function flattenPages(blueprint) {
+  if (blueprint.sections && blueprint.sections.length > 0) {
+    return blueprint.sections.flatMap(
+      (s) => s.pages.map((p) => ({
+        ...p,
+        shell_override: p.shell_override ?? (s.shell !== blueprint.shell ? s.shell : void 0)
+      }))
+    );
+  }
+  return blueprint.pages ?? [];
+}
 function isSectioned(essence) {
+  if (isV3(essence)) return false;
   return "sections" in essence && Array.isArray(essence.sections);
 }
 function isSimple(essence) {
+  if (isV3(essence)) return false;
   return "archetype" in essence && !("sections" in essence);
 }
 
 // src/validate.ts
 import Ajv from "ajv";
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var schemaPath = join(__dirname, "..", "schema", "essence.v2.json");
+var v2SchemaPath = join(__dirname, "..", "schema", "essence.v2.json");
+var v3SchemaPath = join(__dirname, "..", "schema", "essence.v3.json");
 var cachedAjv = null;
-var cachedValidate = null;
-function getValidator() {
-  if (cachedValidate) return cachedValidate;
+var validatorCache = /* @__PURE__ */ new Map();
+function getAjv() {
+  if (!cachedAjv) {
+    cachedAjv = new Ajv({ allErrors: true, strict: false, validateSchema: false });
+  }
+  return cachedAjv;
+}
+function getValidator(version) {
+  if (validatorCache.has(version)) return validatorCache.get(version);
+  const schemaPath = version === "v3" ? v3SchemaPath : v2SchemaPath;
+  if (!existsSync(schemaPath)) return null;
   const schema = JSON.parse(readFileSync(schemaPath, "utf-8"));
-  cachedAjv = new Ajv({ allErrors: true, strict: false, validateSchema: false });
-  cachedValidate = cachedAjv.compile(schema);
-  return cachedValidate;
+  const ajv = getAjv();
+  const validate = ajv.compile(schema);
+  validatorCache.set(version, validate);
+  return validate;
+}
+function detectVersion(data) {
+  if (typeof data === "object" && data !== null && "version" in data) {
+    const v = data.version;
+    if (v === "3.0.0" || v === "3.1.0") return "v3";
+  }
+  return "v2";
 }
 function validateEssence(data) {
-  const validate = getValidator();
+  const version = detectVersion(data);
+  const validate = getValidator(version);
+  if (!validate) {
+    return { valid: false, errors: [`No schema available for ${version} documents`] };
+  }
   const valid = validate(data);
   if (valid) {
     return { valid: true, errors: [] };
@@ -49,7 +86,7 @@ var MAX_GAP = 10;
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
 }
-function computeDensity(personality, recipeSpatial) {
+function computeDensity(personality, spatialHints) {
   const lower = personality.map((c) => c.toLowerCase());
   let level = "comfortable";
   let gap = 4;
@@ -60,11 +97,11 @@ function computeDensity(personality, recipeSpatial) {
       break;
     }
   }
-  if (recipeSpatial?.density_bias) {
-    gap += recipeSpatial.density_bias;
+  if (spatialHints?.density_bias) {
+    gap += spatialHints.density_bias;
   }
-  if (recipeSpatial?.content_gap_shift) {
-    gap += recipeSpatial.content_gap_shift;
+  if (spatialHints?.content_gap_shift) {
+    gap += spatialHints.content_gap_shift;
   }
   gap = clamp(gap, MIN_GAP, MAX_GAP);
   if (gap <= 3) level = "compact";
@@ -72,22 +109,173 @@ function computeDensity(personality, recipeSpatial) {
   else level = "comfortable";
   return { level, content_gap: String(gap) };
 }
+var DENSITY_SCALES = {
+  compact: 0.65,
+  comfortable: 1,
+  spacious: 1.4
+};
+var BASE_TOKENS = {
+  "--d-section-py": 5,
+  "--d-interactive-py": 0.5,
+  "--d-interactive-px": 1,
+  "--d-surface-p": 1.25,
+  "--d-data-py": 0.625,
+  "--d-control-py": 0.5,
+  "--d-content-gap": 1
+};
+function roundTo3(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+function toRemString(value) {
+  const rounded = roundTo3(value);
+  return `${rounded}rem`;
+}
+function computeSpatialTokens(density, spatialHints) {
+  const scale = DENSITY_SCALES[density];
+  const biasMultiplier = 1 + (spatialHints?.density_bias ?? 0) / 10;
+  const result = {};
+  for (const [key, base] of Object.entries(BASE_TOKENS)) {
+    const tokenKey = key;
+    if (tokenKey === "--d-section-py" && spatialHints?.section_padding) {
+      const pxMatch = spatialHints.section_padding.match(/^(\d+(?:\.\d+)?)px$/);
+      if (pxMatch) {
+        const remValue = parseFloat(pxMatch[1]) / 16;
+        result[tokenKey] = toRemString(remValue * scale * biasMultiplier);
+        continue;
+      }
+    }
+    let computed = base * scale * biasMultiplier;
+    if (tokenKey === "--d-content-gap" && spatialHints?.content_gap_shift) {
+      computed += spatialHints.content_gap_shift * 0.25;
+    }
+    result[tokenKey] = toRemString(computed);
+  }
+  return result;
+}
 
 // src/guard.ts
-function evaluateGuard(essence, context) {
-  const guard = essence.guard;
+function checkThemeModeCompatibility(essence, context) {
+  if (!context.themeRegistry) return null;
+  let themeId;
+  let mode;
+  if (isV3(essence)) {
+    themeId = essence.dna.theme?.id ?? null;
+    mode = essence.dna.theme?.mode ?? null;
+  } else {
+    themeId = isSimple(essence) ? essence.theme?.id : null;
+    mode = isSimple(essence) ? essence.theme?.mode : null;
+  }
+  if (!themeId || !mode) return null;
+  const theme = context.themeRegistry.get(themeId);
+  if (!theme) {
+    return null;
+  }
+  if (!theme.modes.includes(mode) && mode !== "auto") {
+    const supportedModes = theme.modes.join(", ");
+    const suggestion = theme.modes.length > 0 ? `Use mode: "${theme.modes[0]}" instead, or choose a theme that supports ${mode} mode.` : void 0;
+    return {
+      rule: "theme-mode",
+      severity: "error",
+      message: `Theme "${themeId}" does not support "${mode}" mode. Supported modes: ${supportedModes}.`,
+      suggestion,
+      ...isV3(essence) ? { layer: "dna", autoFixable: false } : {}
+    };
+  }
+  return null;
+}
+function collectPatternIds(item, ids) {
+  if (typeof item === "string") {
+    ids.add(item);
+    return;
+  }
+  if (typeof item === "object" && item !== null) {
+    if ("pattern" in item && typeof item.pattern === "string") {
+      ids.add(item.pattern);
+    }
+    if ("cols" in item && Array.isArray(item.cols)) {
+      for (const col of item.cols) {
+        if (typeof col === "string") {
+          ids.add(col);
+        }
+      }
+    }
+  }
+}
+function findSimilarPatterns(target, registry) {
+  const similar = [];
+  const targetLower = target.toLowerCase();
+  for (const id of registry.keys()) {
+    const idLower = id.toLowerCase();
+    if (idLower.includes(targetLower) || targetLower.includes(idLower)) {
+      similar.push(id);
+    }
+  }
+  return similar.slice(0, 3);
+}
+function checkPatternExistence(essence, context) {
+  if (!context.patternRegistry) return [];
+  const violations = [];
+  const referencedPatterns = /* @__PURE__ */ new Set();
+  const pages = getAllPages(essence);
+  for (const page of pages) {
+    for (const item of page.layout || []) {
+      collectPatternIds(item, referencedPatterns);
+    }
+  }
+  for (const patternId of referencedPatterns) {
+    if (!context.patternRegistry.has(patternId)) {
+      const similar = findSimilarPatterns(patternId, context.patternRegistry);
+      const suggestion = similar.length > 0 ? `Similar patterns: ${similar.join(", ")}` : `Run "decantr search ${patternId}" to find alternatives.`;
+      violations.push({
+        rule: "pattern-exists",
+        severity: isV3(essence) ? "warning" : "error",
+        message: `Pattern "${patternId}" is referenced but does not exist in the registry.`,
+        suggestion,
+        ...isV3(essence) ? { layer: "blueprint", autoFixable: false } : {}
+      });
+    }
+  }
+  return violations;
+}
+function checkAccessibility(essence, context) {
+  const accessibility = isV3(essence) ? essence.dna.accessibility : "accessibility" in essence ? essence.accessibility : void 0;
+  if (!accessibility?.wcag_level || accessibility.wcag_level === "none") {
+    return null;
+  }
+  if (context.a11y_issues && context.a11y_issues.length > 0) {
+    const issueList = context.a11y_issues.slice(0, 3).join(", ");
+    const moreCount = context.a11y_issues.length > 3 ? ` (+${context.a11y_issues.length - 3} more)` : "";
+    return {
+      rule: "accessibility",
+      severity: "error",
+      message: `WCAG ${accessibility.wcag_level} compliance required. Issues found: ${issueList}${moreCount}`,
+      suggestion: "Fix accessibility issues before proceeding. Run an accessibility audit for details.",
+      ...isV3(essence) ? { layer: "dna", autoFixable: false } : {}
+    };
+  }
+  return null;
+}
+function evaluateGuard(essence, context = {}) {
+  const guard = isV3(essence) ? essence.meta.guard : essence.guard;
   if (guard.mode === "creative") {
     return [];
   }
   const violations = [];
   const isStrict = guard.mode === "strict";
   if (context.style) {
-    const essenceStyle = isSimple(essence) ? essence.theme.style : null;
-    if (essenceStyle && context.style !== essenceStyle && guard.enforce_style !== false) {
+    let essenceStyle;
+    if (isV3(essence)) {
+      essenceStyle = essence.dna.theme.id;
+    } else {
+      essenceStyle = isSimple(essence) ? essence.theme.id : null;
+    }
+    const enforceStyle = isV3(essence) ? true : guard.enforce_style !== false;
+    if (essenceStyle && context.style !== essenceStyle && enforceStyle) {
       violations.push({
         rule: "style",
         severity: "error",
-        message: `Style "${context.style}" does not match essence theme "${essenceStyle}". Change the essence theme first.`
+        message: `Style "${context.style}" does not match essence theme "${essenceStyle}". Change the essence theme first.`,
+        ...isV3(essence) ? { layer: "dna", autoFixable: false } : {}
       });
     }
   }
@@ -97,8 +285,13 @@ function evaluateGuard(essence, context) {
     if (!pageExists) {
       violations.push({
         rule: "structure",
-        severity: "error",
-        message: `Page "${context.pageId}" does not exist in essence structure. Add it to the essence first.`
+        severity: isV3(essence) ? "warning" : "error",
+        message: `Page "${context.pageId}" does not exist in essence structure. Add it to the essence first.`,
+        ...isV3(essence) ? {
+          layer: "blueprint",
+          autoFixable: true,
+          autoFix: { type: "add_page", patch: { id: context.pageId } }
+        } : {}
       });
     }
   }
@@ -114,41 +307,94 @@ function evaluateGuard(essence, context) {
       if (!matches) {
         violations.push({
           rule: "layout",
-          severity: "error",
-          message: `Layout for page "${context.pageId}" deviates from essence. Expected: [${essenceLayout.join(", ")}].`
+          severity: isV3(essence) ? "warning" : "error",
+          message: `Layout for page "${context.pageId}" deviates from essence. Expected: [${essenceLayout.join(", ")}].`,
+          ...isV3(essence) ? {
+            layer: "blueprint",
+            autoFixable: true,
+            autoFix: { type: "update_layout", patch: { page: context.pageId, layout: context.layout } }
+          } : {}
         });
       }
     }
   }
-  if (context.recipe && guard.enforce_recipe !== false) {
-    const essenceRecipe = isSimple(essence) ? essence.theme.recipe : null;
-    if (essenceRecipe && context.recipe !== essenceRecipe) {
-      violations.push({
-        rule: "recipe",
-        severity: "error",
-        message: `Recipe "${context.recipe}" does not match essence recipe "${essenceRecipe}".`
-      });
-    }
-  }
   if (isStrict && context.density_gap) {
-    if (context.density_gap !== essence.density.content_gap) {
+    let expectedGap;
+    if (isV3(essence)) {
+      const overriddenDensity = getPageDensityOverride(essence, context.pageId);
+      expectedGap = overriddenDensity ?? essence.dna.spacing.content_gap;
+    } else {
+      expectedGap = essence.density.content_gap;
+    }
+    if (context.density_gap !== expectedGap) {
       violations.push({
         rule: "density",
         severity: "warning",
-        message: `Content gap "${context.density_gap}" does not match essence density "${essence.density.content_gap}".`
+        message: `Content gap "${context.density_gap}" does not match essence density "${expectedGap}".`,
+        ...isV3(essence) ? { layer: "dna", autoFixable: false } : {}
       });
     }
   }
+  const themeModeViolation = checkThemeModeCompatibility(essence, context);
+  if (themeModeViolation) {
+    violations.push(themeModeViolation);
+  }
+  const patternViolations = checkPatternExistence(essence, context);
+  violations.push(...patternViolations);
+  const accessibilityViolation = checkAccessibility(essence, context);
+  if (accessibilityViolation) {
+    violations.push(accessibilityViolation);
+  }
+  if (isV3(essence)) {
+    const v3Guard = guard;
+    if (v3Guard.dna_enforcement === "off") {
+      return violations.filter((v) => v.layer !== "dna");
+    }
+    if (v3Guard.dna_enforcement === "warn") {
+      for (const v of violations) {
+        if (v.layer === "dna") {
+          v.severity = "warning";
+        }
+      }
+    }
+    if (v3Guard.blueprint_enforcement === "off") {
+      return violations.filter((v) => v.layer !== "blueprint");
+    }
+  }
   return violations;
 }
 function getAllPages(essence) {
+  if (isV3(essence)) {
+    const pages = flattenPages(essence.blueprint);
+    return pages.map((page) => ({
+      id: page.id,
+      shell: page.shell_override ?? essence.blueprint.shell ?? "",
+      layout: page.layout,
+      ...page.surface ? { surface: page.surface } : {}
+    }));
+  }
   if (isSimple(essence)) return essence.structure;
   if (isSectioned(essence)) return essence.sections.flatMap((s) => s.structure);
-  return [];
+  throw new Error("Unknown EssenceFile type");
+}
+function getPageDensityOverride(essence, pageId) {
+  if (!pageId) return void 0;
+  const pages = flattenPages(essence.blueprint);
+  const page = pages.find((p) => p.id === pageId);
+  if (!page?.dna_overrides?.density) return void 0;
+  const densityGapMap = {
+    compact: "2",
+    comfortable: "4",
+    spacious: "6"
+  };
+  return densityGapMap[page.dna_overrides.density] ?? void 0;
 }
 
 // src/normalize.ts
 function normalizeEssence(input) {
+  if (input.version === "3.0.0") {
+    return input;
+  }
   if (input.theme && input.platform) {
     return input;
   }
@@ -167,9 +413,8 @@ function normalizeSimple(v1) {
     version: "2.0.0",
     archetype: v1.terroir ?? v1.vignette ?? v1.archetype,
     theme: {
-      style: vintage?.style ?? "",
+      id: vintage?.style ?? "",
       mode: vintage?.mode ?? "dark",
-      recipe: vintage?.recipe ?? "",
       ...vintage?.shape ? { shape: vintage.shape } : {}
     },
     // Accept both old 'character' and new 'personality' field names
@@ -207,9 +452,8 @@ function normalizeSectioned(v1) {
       path: section.path,
       archetype: section.terroir ?? section.vignette ?? section.archetype,
       theme: {
-        style: section.vintage?.style ?? "",
-        mode: section.vintage?.mode ?? "dark",
-        recipe: section.vintage?.recipe ?? ""
+        id: section.vintage?.style ?? "",
+        mode: section.vintage?.mode ?? "dark"
       },
       structure: (section.structure ?? []).map(normalizeStructurePage),
       ...section.tannins ? { features: section.tannins } : {}
@@ -241,7 +485,6 @@ function normalizeGuard(cork) {
   };
   return {
     ...cork.enforce_style !== void 0 ? { enforce_style: cork.enforce_style } : {},
-    ...cork.enforce_recipe !== void 0 ? { enforce_recipe: cork.enforce_recipe } : {},
     mode: modeMap[cork.mode ?? "creative"] ?? "creative"
   };
 }
@@ -249,11 +492,194 @@ function stripGapPrefix(gap) {
   const match = gap.match(/^_gap(\d+)$/);
   return match ? match[1] : gap;
 }
+
+// src/migrate.ts
+function migrateV2ToV3(essence) {
+  if (isV3(essence)) return essence;
+  if (isSectioned(essence)) {
+    return migrateSectionedToV3(essence);
+  }
+  if (isSimple(essence)) {
+    return migrateSimpleToV3(essence);
+  }
+  throw new Error("Unknown EssenceFile type \u2014 cannot migrate");
+}
+function migrateSimpleToV3(essence) {
+  const dna = buildDNA(essence);
+  const blueprint = buildBlueprintFromSimple(essence);
+  const meta = buildMeta(essence);
+  return {
+    version: "3.0.0",
+    dna,
+    blueprint,
+    meta,
+    ...essence._impression ? { _impression: essence._impression } : {}
+  };
+}
+function migrateSectionedToV3(essence) {
+  const firstSection = essence.sections[0];
+  const syntheticSimple = {
+    theme: firstSection.theme,
+    density: essence.density,
+    guard: essence.guard,
+    accessibility: essence.accessibility
+  };
+  const dna = buildDNA(syntheticSimple);
+  dna.personality = essence.personality;
+  const pages = essence.sections.flatMap(
+    (section) => section.structure.map((page) => ({
+      id: page.id,
+      shell_override: page.shell,
+      layout: page.layout,
+      ...page.surface ? { surface: page.surface } : {}
+    }))
+  );
+  const allFeatures = [
+    ...essence.shared_features ?? [],
+    ...essence.sections.flatMap((s) => s.features ?? [])
+  ];
+  const blueprint = {
+    shell: firstSection.structure[0]?.shell ?? "top-nav-main",
+    pages,
+    features: [...new Set(allFeatures)]
+  };
+  const meta = {
+    archetype: firstSection.archetype,
+    target: essence.target,
+    platform: essence.platform,
+    guard: migrateGuard(essence.guard.mode)
+  };
+  return {
+    version: "3.0.0",
+    dna,
+    blueprint,
+    meta,
+    ...essence._impression ? { _impression: essence._impression } : {}
+  };
+}
+function buildDNA(essence) {
+  const shape = essence.theme.shape ?? "rounded";
+  const radiusBase = inferRadiusBase(shape);
+  return {
+    theme: {
+      id: essence.theme.id,
+      mode: essence.theme.mode,
+      ...essence.theme.shape ? { shape: essence.theme.shape } : {}
+    },
+    spacing: {
+      base_unit: 4,
+      scale: "linear",
+      density: essence.density?.level ?? "comfortable",
+      content_gap: essence.density?.content_gap ?? "4"
+    },
+    typography: {
+      scale: "modular",
+      heading_weight: 600,
+      body_weight: 400
+    },
+    color: {
+      palette: "semantic",
+      accent_count: 1,
+      cvd_preference: essence.accessibility?.cvd_preference ?? "auto"
+    },
+    radius: {
+      philosophy: shape,
+      base: radiusBase
+    },
+    elevation: {
+      system: "layered",
+      max_levels: 3
+    },
+    motion: {
+      preference: "subtle",
+      duration_scale: 1,
+      reduce_motion: true
+    },
+    accessibility: {
+      wcag_level: essence.accessibility?.wcag_level ?? "AA",
+      focus_visible: true,
+      skip_nav: true
+    },
+    personality: essence.personality ?? ["professional"]
+  };
+}
+function buildBlueprintFromSimple(essence) {
+  const defaultShell = essence.structure[0]?.shell ?? "top-nav-main";
+  return {
+    shell: defaultShell,
+    pages: essence.structure.map((page) => ({
+      id: page.id,
+      ...page.shell !== defaultShell ? { shell_override: page.shell } : {},
+      layout: page.layout,
+      ...page.surface ? { surface: page.surface } : {}
+    })),
+    features: essence.features ?? []
+  };
+}
+function buildMeta(essence) {
+  return {
+    archetype: essence.archetype,
+    target: essence.target,
+    platform: essence.platform,
+    guard: migrateGuard(essence.guard.mode)
+  };
+}
+function migrateGuard(mode) {
+  switch (mode) {
+    case "strict":
+      return { mode: "strict", dna_enforcement: "error", blueprint_enforcement: "warn" };
+    case "guided":
+      return { mode: "guided", dna_enforcement: "error", blueprint_enforcement: "off" };
+    case "creative":
+    default:
+      return { mode: "creative", dna_enforcement: "off", blueprint_enforcement: "off" };
+  }
+}
+function inferRadiusBase(shape) {
+  switch (shape) {
+    case "pill":
+      return 12;
+    case "rounded":
+      return 8;
+    case "sharp":
+      return 2;
+    default:
+      return 8;
+  }
+}
+function migrateV30ToV31(essence) {
+  if (essence.version === "3.1.0" || essence.blueprint.sections) {
+    return essence;
+  }
+  const section = {
+    id: essence.meta.archetype,
+    role: "primary",
+    shell: essence.blueprint.shell ?? "top-nav-main",
+    features: essence.blueprint.features,
+    description: "",
+    pages: essence.blueprint.pages ?? []
+  };
+  return {
+    ...essence,
+    version: "3.1.0",
+    blueprint: {
+      ...essence.blueprint,
+      sections: [section],
+      pages: void 0,
+      routes: {}
+    }
+  };
+}
 export {
   computeDensity,
+  computeSpatialTokens,
   evaluateGuard,
+  flattenPages,
   isSectioned,
   isSimple,
+  isV3,
+  migrateV2ToV3,
+  migrateV30ToV31,
   normalizeEssence,
   validateEssence
 };