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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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 };