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

package/dist/index.d.ts

@@ -11,9 +11,8 @@ type ThemeStyle = 'auradecantism' | 'clean' | 'glassmorphism' | 'retro' | 'biolu
 type ThemeMode = 'light' | 'dark' | 'auto';
 type ThemeShape = 'sharp' | 'rounded' | 'pill';
 interface Theme {
-    style: ThemeStyle | string;
+    id: string;
     mode: ThemeMode;
-    recipe: string;
     shape?: ThemeShape;
 }
 type PlatformType = 'spa' | 'ssr' | 'static';
@@ -50,10 +49,18 @@ interface Density {
     level: DensityLevel;
     content_gap: string;
 }
+interface SpatialTokens {
+    '--d-section-py': string;
+    '--d-interactive-py': string;
+    '--d-interactive-px': string;
+    '--d-surface-p': string;
+    '--d-data-py': string;
+    '--d-control-py': string;
+    '--d-content-gap': string;
+}
 type GuardMode = 'creative' | 'guided' | 'strict';
 interface Guard {
     enforce_style?: boolean;
-    enforce_recipe?: boolean;
     mode: GuardMode;
 }
 interface Impression {
@@ -64,6 +71,12 @@ interface Impression {
     novel_elements: string[];
 }
 type GeneratorTarget = 'decantr' | 'react' | 'vue' | 'svelte' | string;
+type WcagLevel = 'none' | 'A' | 'AA' | 'AAA';
+type CvdPreference = 'none' | 'auto' | 'deuteranopia' | 'protanopia' | 'tritanopia' | 'achromatopsia';
+interface Accessibility {
+    wcag_level?: WcagLevel;
+    cvd_preference?: CvdPreference;
+}
 interface Essence {
     $schema?: string;
     version: string;
@@ -76,6 +89,7 @@ interface Essence {
     density: Density;
     guard: Guard;
     target: GeneratorTarget;
+    accessibility?: Accessibility;
     _impression?: Impression;
 }
 interface EssenceSection {
@@ -96,9 +110,130 @@ interface SectionedEssence {
     density: Density;
     guard: Guard;
     target: GeneratorTarget;
+    accessibility?: Accessibility;
     _impression?: Impression;
 }
-type EssenceFile = Essence | SectionedEssence;
+interface EssenceDNA {
+    theme: Theme;
+    spacing: {
+        base_unit: number;
+        scale: string;
+        density: DensityLevel;
+        content_gap: string;
+    };
+    typography: {
+        scale: string;
+        heading_weight: number;
+        body_weight: number;
+    };
+    color: {
+        palette: string;
+        accent_count: number;
+        cvd_preference: CvdPreference | string;
+    };
+    radius: {
+        philosophy: ThemeShape | string;
+        base: number;
+    };
+    elevation: {
+        system: string;
+        max_levels: number;
+    };
+    motion: {
+        preference: string;
+        duration_scale: number;
+        reduce_motion: boolean;
+        timing?: string;
+        durations?: Record<string, string>;
+    };
+    accessibility: {
+        wcag_level: WcagLevel;
+        focus_visible: boolean;
+        skip_nav: boolean;
+    };
+    personality: string[];
+    constraints?: {
+        mode?: string;
+        typography?: string;
+        borders?: string;
+        corners?: string;
+        shadows?: string;
+        effects?: Record<string, string>;
+    };
+}
+/** Only density and mode may be overridden per-page. DNA axioms like wcag_level and theme.id are never overrideable. */
+interface DNAOverrides {
+    density?: DensityLevel;
+    mode?: ThemeMode;
+}
+interface BlueprintPage {
+    id: string;
+    route?: string;
+    shell_override?: ShellType | null;
+    layout: LayoutItem[];
+    patterns?: PatternRef[];
+    dna_overrides?: DNAOverrides;
+    surface?: string;
+}
+type ArchetypeRole = 'primary' | 'gateway' | 'public' | 'auxiliary';
+interface EssenceV31Section {
+    id: string;
+    role: ArchetypeRole;
+    shell: ShellType | string;
+    features: string[];
+    description: string;
+    pages: BlueprintPage[];
+    dna_overrides?: DNAOverrides;
+}
+interface RouteEntry {
+    section: string;
+    page: string;
+}
+interface EssenceBlueprint {
+    shell?: ShellType | string;
+    sections?: EssenceV31Section[];
+    pages?: BlueprintPage[];
+    features: string[];
+    routes?: Record<string, RouteEntry>;
+    icon_style?: string;
+    avatar_style?: string;
+}
+interface EssenceV3Guard {
+    mode: GuardMode;
+    dna_enforcement: 'error' | 'warn' | 'off';
+    blueprint_enforcement: 'warn' | 'off';
+}
+interface EssenceMeta {
+    archetype: string;
+    target: GeneratorTarget;
+    platform: Platform;
+    guard: EssenceV3Guard;
+    seo?: {
+        schema_org?: string[];
+        meta_priorities?: string[];
+    };
+    navigation?: {
+        hotkeys?: Array<{
+            key: string;
+            route?: string;
+            action?: string;
+            label: string;
+        }>;
+        command_palette?: boolean;
+    };
+}
+interface EssenceV3 {
+    $schema?: string;
+    version: '3.0.0' | '3.1.0';
+    dna: EssenceDNA;
+    blueprint: EssenceBlueprint;
+    meta: EssenceMeta;
+    _impression?: Impression;
+}
+type EssenceFile = Essence | SectionedEssence | EssenceV3;
+declare function isV3(essence: EssenceFile): essence is EssenceV3;
+/** Flatten sections into a flat page list (for guards and backward compat). */
+declare function flattenPages(blueprint: EssenceBlueprint): BlueprintPage[];
 declare function isSectioned(essence: EssenceFile): essence is SectionedEssence;
 declare function isSimple(essence: EssenceFile): essence is Essence;
 
@@ -108,26 +243,55 @@ interface ValidationResult {
 }
 declare function validateEssence(data: unknown): ValidationResult;
 
-interface RecipeSpatialHints {
+interface SpatialHints {
     density_bias?: number;
     content_gap_shift?: number;
 }
-declare function computeDensity(personality: string[], recipeSpatial?: RecipeSpatialHints): Density;
+declare function computeDensity(personality: string[], spatialHints?: SpatialHints): Density;
+interface SpatialTokenHints {
+    section_padding?: string | null;
+    density_bias?: number;
+    content_gap_shift?: number;
+}
+declare function computeSpatialTokens(density: DensityLevel, spatialHints?: SpatialTokenHints): SpatialTokens;
 
+interface AutoFix {
+    type: 'add_page' | 'update_layout' | 'update_blueprint';
+    patch: Record<string, unknown>;
+}
 interface GuardViolation {
-    rule: 'style' | 'structure' | 'layout' | 'recipe' | 'density';
+    rule: 'style' | 'structure' | 'layout' | 'density' | 'theme-mode' | 'pattern-exists' | 'accessibility';
     severity: 'error' | 'warning';
     message: string;
+    suggestion?: string;
+    layer?: 'dna' | 'blueprint';
+    autoFixable?: boolean;
+    autoFix?: AutoFix;
 }
 interface GuardContext {
     pageId?: string;
     style?: string;
-    recipe?: string;
     layout?: string[];
     density_gap?: string;
+    themeRegistry?: Map<string, {
+        modes: string[];
+    }>;
+    patternRegistry?: Map<string, unknown>;
+    a11y_issues?: string[];
 }
-declare function evaluateGuard(essence: EssenceFile, context: GuardContext): GuardViolation[];
+declare function evaluateGuard(essence: EssenceFile, context?: GuardContext): GuardViolation[];
 
 declare function normalizeEssence(input: Record<string, unknown>): EssenceFile;
 
-export { type ColumnLayout, type Density, type DensityLevel, type Essence, type EssenceFile, type EssenceSection, type GeneratorTarget, type Guard, type GuardContext, type GuardMode, type GuardViolation, type Impression, type LayoutItem, type PatternRef, type Platform, type PlatformType, type RoutingStrategy, type SectionedEssence, type ShellType, type StructurePage, type Theme, type ThemeMode, type ThemeShape, type ThemeStyle, type ValidationResult, computeDensity, evaluateGuard, isSectioned, isSimple, normalizeEssence, validateEssence };
+/**
+ * Migrate a v2 EssenceFile to v3 format (DNA/Blueprint/Meta split).
+ * If already v3, returns unchanged. SectionedEssence uses first section's theme.
+ */
+declare function migrateV2ToV3(essence: EssenceFile): EssenceV3;
+/**
+ * Migrate a v3.0 flat-page EssenceV3 to v3.1 sectioned format.
+ * If already v3.1 or has blueprint.sections, returns unchanged.
+ */
+declare function migrateV30ToV31(essence: EssenceV3): EssenceV3;
+
+export { type Accessibility, type ArchetypeRole, type AutoFix, type BlueprintPage, type ColumnLayout, type CvdPreference, type DNAOverrides, type Density, type DensityLevel, type Essence, type EssenceBlueprint, type EssenceDNA, type EssenceFile, type EssenceMeta, type EssenceSection, type EssenceV3, type EssenceV31Section, type EssenceV3Guard, type GeneratorTarget, type Guard, type GuardContext, type GuardMode, type GuardViolation, type Impression, type LayoutItem, type PatternRef, type Platform, type PlatformType, type RouteEntry, type RoutingStrategy, type SectionedEssence, type ShellType, type SpatialTokens, type StructurePage, type Theme, type ThemeMode, type ThemeShape, type ThemeStyle, type ValidationResult, type WcagLevel, computeDensity, computeSpatialTokens, evaluateGuard, flattenPages, isSectioned, isSimple, isV3, migrateV2ToV3, migrateV30ToV31, normalizeEssence, validateEssence };