@decantr/core 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { EssenceFile, EssenceV3, StructurePage } from '@decantr/essence-spec';
-import { ContentResolver, Pattern, ResolvedPreset, Theme } from '@decantr/registry';
+import { StructurePage, EssenceFile, EssenceV3 } from '@decantr/essence-spec';
+import { Pattern, ResolvedPreset, Theme, ContentResolver } from '@decantr/registry';
 
 type IRNodeType = 'app' | 'shell' | 'page' | 'pattern' | 'grid' | 'nav' | 'store';
 interface IRSpatial {
@@ -35,6 +35,17 @@ interface IRPatternMeta {
         example?: string;
     } | null;
     components: string[];
+    /**
+     * Per-preset prose from pattern.presets[preset].description. Threaded
+     * into PagePackPattern so the page-pack renderer can emit preset-specific
+     * guidance instead of the blueprint-generic pattern root description.
+     */
+    presetDescription?: string;
+    /**
+     * v2.1 Tier C1. Declared runtime interactions from the pattern JSON.
+     * Page-pack renderer surfaces these as a checkbox checklist.
+     */
+    interactions?: string[];
 }
 interface IRVisualEffect {
     decorators: string[];
@@ -137,6 +148,24 @@ interface IRStoreNode extends IRNode {
     }[];
 }
 
+interface ResolvedPatternEntry {
+    pattern: Pattern;
+    preset: ResolvedPreset;
+}
+/** Build IR tree for a single page from its resolved structure + patterns */
+declare function buildPageIR(page: StructurePage, resolvedPatterns: Map<string, ResolvedPatternEntry>, wiring: IRWiring | null, theme: Theme | null, density: {
+    gap: string;
+}, layer?: IRLayer): IRPageNode;
+
+/** Depth-first walk of IR tree, calling visitor on each node */
+declare function walkIR(node: IRNode, visitor: (node: IRNode, parent: IRNode | null) => void, parent?: IRNode | null): void;
+/** Find all nodes of a specific type */
+declare function findNodes<T extends IRNode>(root: IRNode, type: string): T[];
+/** Count total patterns in an IR tree */
+declare function countPatterns(root: IRNode): number;
+/** Validate IR tree structure (no orphaned grids, patterns have meta, etc.) */
+declare function validateIR(root: IRNode): string[];
+
 type ExecutionPackType = 'scaffold' | 'section' | 'page' | 'mutation' | 'review';
 declare const EXECUTION_PACK_SCHEMA_URLS: {
     readonly scaffold: "https://decantr.ai/schemas/scaffold-pack.v1.json";
@@ -238,14 +267,52 @@ interface ScaffoldPackData {
     routing: 'hash' | 'history' | 'pathname';
     features: string[];
     navigation?: {
-        commandPalette: boolean;
+        /**
+         * true  = palette enabled with implicit defaults.
+         * false = not enabled.
+         * object = explicit structured contract (see CommandPaletteContract).
+         */
+        commandPalette: boolean | CommandPaletteContract;
         hotkeys: Array<{
             key: string;
             route?: string;
             label?: string;
+            semantics?: HotkeySemantics;
         }>;
+        /** Default hotkey semantics applied unless per-hotkey semantics override. */
+        hotkeySemantics?: HotkeySemantics;
     };
     routes: ScaffoldPackRoute[];
+    /**
+     * Required theme decorator contract — surfaced ONCE at the project level
+     * here, then referenced (not duplicated) in each section pack. Cold-LLM
+     * runs reported the table was duplicated 7-10× across context files
+     * (~270-540 redundant lines per scaffold) when each section pack carried
+     * its own copy. Centralizing in scaffold-pack — which the cold prompt
+     * tells AI to read first — keeps the contract authoritative without the
+     * per-section repetition.
+     */
+    themeDecorators?: ThemeDecoratorEntry[];
+}
+interface CommandPaletteContract {
+    trigger?: string;
+    placeholder?: string;
+    width?: string;
+    styling?: 'modal' | 'sheet' | 'inline' | 'fullscreen';
+    commands?: Array<{
+        id: string;
+        label: string;
+        section?: string;
+        hotkey?: string;
+        action?: string;
+        route?: string;
+    }>;
+}
+interface HotkeySemantics {
+    chord_window_ms?: number;
+    input_guard?: boolean;
+    modifier_suppression?: boolean;
+    match_case?: boolean;
 }
 interface ScaffoldExecutionPack extends ExecutionPackBase<ScaffoldPackData> {
     packType: 'scaffold';
@@ -257,6 +324,18 @@ interface SectionPackInput {
     description: string;
     features: string[];
     pageIds: string[];
+    navigationItems?: SectionNavigationItemPack[];
+    /** Execution-level directives — short imperative rules for this section. */
+    directives?: string[];
+}
+/** Navigation item contract for a section's primary navigation. */
+interface SectionNavigationItemPack {
+    label: string;
+    route: string;
+    icon?: string;
+    hotkey?: string;
+    active_match?: string;
+    badge?: string;
 }
 interface SectionPackRoute {
     pageId: string;
@@ -276,6 +355,26 @@ interface SectionPackData {
         shape: string | null;
     };
     routes: SectionPackRoute[];
+    /** Contract for items rendered in this section's primary navigation. */
+    navigationItems?: SectionNavigationItemPack[];
+    /** Execution-level directives emitted into the section-pack rendering. */
+    directives?: string[];
+    /**
+     * Required theme decorator contract surfaced into the compact pack.
+     * Mirrors the long-form section-context "Required Theme Decorators" table.
+     * Cold prompts instruct AI assistants to read packs first, so the strong
+     * decorator contract has to live HERE, not just in the long-form file.
+     */
+    themeDecorators?: ThemeDecoratorEntry[];
+}
+/** Compact, render-ready decorator entry for pack contracts. */
+interface ThemeDecoratorEntry {
+    /** Decorator class name without leading dot, e.g. "lum-glass". */
+    class: string;
+    /** Authored intent describing what the decorator does. */
+    intent: string;
+    /** Authored slot hints listing where to apply it (joined from usage[]). */
+    applyTo: string;
 }
 interface SectionExecutionPack extends ExecutionPackBase<SectionPackData> {
     packType: 'section';
@@ -286,12 +385,28 @@ interface PagePackInput {
     sectionId: string | null;
     sectionRole: string | null;
     features: string[];
+    /** Execution-level directives — short imperative rules for this page. */
+    directives?: string[];
 }
 interface PagePackPattern {
     id: string;
     alias: string;
     preset: string;
     layout: string;
+    /**
+     * Per-preset prose from the pattern's preset.description. When present,
+     * the page-pack renderer emits it as a short description line so cold
+     * LLMs read preset-specific guidance instead of having to look up the
+     * pattern's root description.
+     */
+    presetDescription?: string;
+    /**
+     * v2.1 Tier C1. Declared interactions from the pattern JSON. Rendered
+     * as a checkbox checklist so cold LLMs in generation mode see a
+     * hard-edged list they can't categorize as "philosophy". Enforced by
+     * decantr check --strict (C5 guard rule).
+     */
+    interactions?: string[];
 }
 interface PagePackData {
     pageId: string;
@@ -308,6 +423,8 @@ interface PagePackData {
     };
     wiringSignals: string[];
     patterns: PagePackPattern[];
+    /** Execution-level directives emitted into the page-pack rendering. */
+    directives?: string[];
 }
 interface PageExecutionPack extends ExecutionPackBase<PagePackData> {
     packType: 'page';
@@ -384,13 +501,22 @@ interface ScaffoldPackBuilderOptions {
     successChecks?: ExecutionPackSuccessCheck[];
     tokenBudget?: Partial<ExecutionPackTokenBudget>;
     navigation?: {
-        commandPalette: boolean;
+        commandPalette: boolean | CommandPaletteContract;
         hotkeys: Array<{
             key: string;
             route?: string;
             label?: string;
+            semantics?: HotkeySemantics;
         }>;
+        hotkeySemantics?: HotkeySemantics;
     };
+    /**
+     * Required theme decorator contract surfaced into the scaffold pack.
+     * The scaffold pack is read first per cold-prompt rules, so the canonical
+     * decorator contract belongs here. Section packs reference this without
+     * duplicating to avoid the 7-10× repetition cold-LLM runs reported.
+     */
+    themeDecorators?: ThemeDecoratorEntry[];
 }
 interface SectionPackBuilderOptions extends ScaffoldPackBuilderOptions {
 }
@@ -436,6 +562,13 @@ interface PipelineOptions {
 interface PipelineResult {
     /** The framework-agnostic intermediate representation */
     ir: IRAppNode;
+    /**
+     * The fully-resolved registry theme record, including `decorator_definitions`
+     * and other rich theme data not carried in the lite IR `theme` node.
+     * Consumers (e.g. pack builders) need this to render decorator contracts
+     * into compiled artifacts.
+     */
+    registryTheme: Theme | null;
 }
 /**
  * Run the Design Pipeline:
@@ -446,15 +579,6 @@ interface PipelineResult {
  */
 declare function runPipeline(essence: EssenceFile, options: PipelineOptions): Promise<PipelineResult>;
 
-interface ResolvedPatternEntry {
-    pattern: Pattern;
-    preset: ResolvedPreset;
-}
-/** Build IR tree for a single page from its resolved structure + patterns */
-declare function buildPageIR(page: StructurePage, resolvedPatterns: Map<string, ResolvedPatternEntry>, wiring: IRWiring | null, theme: Theme | null, density: {
-    gap: string;
-}, layer?: IRLayer): IRPageNode;
-
 interface ResolvedPage {
     page: StructurePage;
     patterns: Map<string, {
@@ -482,15 +606,6 @@ declare function resolveVisualEffects(theme: Theme, pattern: Pattern, _slot?: st
 /** Resolve all external references in an Essence file */
 declare function resolveEssence(essence: EssenceFile, resolver: ContentResolver): Promise<ResolvedEssence>;
 
-/** Depth-first walk of IR tree, calling visitor on each node */
-declare function walkIR(node: IRNode, visitor: (node: IRNode, parent: IRNode | null) => void, parent?: IRNode | null): void;
-/** Find all nodes of a specific type */
-declare function findNodes<T extends IRNode>(root: IRNode, type: string): T[];
-/** Count total patterns in an IR tree */
-declare function countPatterns(root: IRNode): number;
-/** Validate IR tree structure (no orphaned grids, patterns have meta, etc.) */
-declare function validateIR(root: IRNode): string[];
-
 /** Convert a kebab-case or snake_case string to PascalCase */
 declare function pascalCase(str: string): string;