@decantr/core 1.0.6 → 2.1.0

package/README.md

@@ -15,7 +15,7 @@ npm install @decantr/core
 
 ## Stability
 
-`@decantr/core` is published for advanced package consumers that need low-level execution-pack primitives. It is stable in the `1.x` line for the documented exports in this package, but it is still not the recommended first integration surface for most Decantr adopters.
+`@decantr/core` is published for advanced package consumers that need low-level execution-pack primitives. It is stable in the `2.x` line for the documented exports in this package, but it is still not the recommended first integration surface for most Decantr adopters.
 
 ## What It Exports
 
@@ -28,6 +28,18 @@ npm install @decantr/core
 
 In the current workflow architecture, `@decantr/core` owns the canonical adapter labels used by compiled packs, while runnable greenfield bootstrap adapters are resolved in the CLI on top of those labels.
 
+## FAQ
+
+Most teams should start with the CLI rather than this low-level package:
+
+```bash
+npx @decantr/cli new my-app
+npx @decantr/cli analyze
+npx @decantr/cli check
+```
+
+For common setup, brownfield, Studio, migration, CI, and agent-alignment questions, see the user-facing [Decantr FAQ](https://github.com/decantr-ai/decantr/blob/main/docs/faq.md).
+
 ## Example
 
 ```ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StructurePage, EssenceFile, EssenceV3 } from '@decantr/essence-spec';
+import { StructurePage, EssenceFile, EssenceV4 } from '@decantr/essence-spec';
 import { Pattern, ResolvedPreset, Theme, ContentResolver } from '@decantr/registry';
 
 type IRNodeType = 'app' | 'shell' | 'page' | 'pattern' | 'grid' | 'nav' | 'store';
@@ -42,7 +42,7 @@ interface IRPatternMeta {
      */
     presetDescription?: string;
     /**
-     * v2.1 Tier C1. Declared runtime interactions from the pattern JSON.
+     * Declared runtime interactions from the pattern JSON.
      * Page-pack renderer surfaces these as a checkbox checklist.
      */
     interactions?: string[];
@@ -92,7 +92,7 @@ interface IRRoute {
     shell: string;
     sectionId?: string;
 }
-/** Which v3 essence layer sourced this node */
+/** Which Essence v4 layer sourced this node */
 type IRLayer = 'dna' | 'blueprint' | 'meta';
 interface IRNode {
     type: IRNodeType;
@@ -100,7 +100,7 @@ interface IRNode {
     children: IRNode[];
     spatial?: IRSpatial;
     meta?: Record<string, unknown>;
-    /** When built from a v3 essence, indicates the originating layer */
+    /** When built from an Essence v4 document, indicates the originating layer */
     layer?: IRLayer;
 }
 interface IRAppNode extends IRNode {
@@ -407,7 +407,7 @@ interface PagePackPattern {
      */
     presetDescription?: string;
     /**
-     * v2.1 Tier C1. Declared interactions from the pattern JSON. Rendered
+     * 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).
@@ -544,8 +544,8 @@ interface CompileExecutionPackBundleOptions {
 }
 declare function renderExecutionPackMarkdown(pack: ExecutionPackBase<unknown>): string;
 declare function resolvePackAdapter(target: string | undefined, platformType: string | undefined): string;
-declare function listPackSections(essence: EssenceV3): SectionPackInput[];
-declare function listPackPages(essence: EssenceV3): PagePackInput[];
+declare function listPackSections(essence: EssenceV4): SectionPackInput[];
+declare function listPackPages(essence: EssenceV4): PagePackInput[];
 declare function buildScaffoldPack(appNode: IRAppNode, options?: ScaffoldPackBuilderOptions): ScaffoldExecutionPack;
 declare function buildSectionPack(appNode: IRAppNode, input: SectionPackInput, options?: SectionPackBuilderOptions): SectionExecutionPack;
 declare function buildPagePack(appNode: IRAppNode, input: PagePackInput, options?: PagePackBuilderOptions): PageExecutionPack;
@@ -585,6 +585,44 @@ interface PipelineResult {
  */
 declare function runPipeline(essence: EssenceFile, options: PipelineOptions): Promise<PipelineResult>;
 
+type RealizationAdapter = 'react-vite' | 'next-app' | 'generic-web' | string;
+interface RealizationRoute {
+    path: string;
+    sectionId: string;
+    sectionRole: string;
+    pageId: string;
+    shell: string;
+    patterns: string[];
+    states: Array<'empty' | 'loading' | 'error'>;
+}
+interface RealizationMockDataSeed {
+    id: string;
+    source: 'feature' | 'route';
+    shape: Record<string, unknown>;
+}
+interface RealizationInteractionPlaceholder {
+    id: string;
+    kind: 'command-palette' | 'hotkey' | 'auth-mock' | 'route-action';
+    route?: string;
+    label: string;
+}
+interface RealizationPlan {
+    version: '1.0.0';
+    sourceEssenceVersion: '4.0.0';
+    adapter: RealizationAdapter;
+    canRealizeFrameworkCode: boolean;
+    routes: RealizationRoute[];
+    shell: {
+        id: string;
+        theme: string;
+        mode: string;
+    };
+    mockData: RealizationMockDataSeed[];
+    interactions: RealizationInteractionPlaceholder[];
+    unsupportedReason?: string;
+}
+declare function compileRealizationPlan(essence: EssenceV4): RealizationPlan;
+
 interface ResolvedPage {
     page: ResolvedStructurePage;
     patterns: Map<string, {
@@ -609,8 +647,8 @@ interface ResolvedEssence {
     shell: IRShellConfig;
     routes: IRRoute[];
     features: string[];
-    /** True when the source essence was v3 (DNA/Blueprint/Meta) */
-    isV3Source: boolean;
+    /** True when the source essence uses the active DNA/Blueprint/Meta contract. */
+    isBlueprintSource: boolean;
 }
 declare function resolveVisualEffects(theme: Theme, pattern: Pattern, _slot?: string): IRVisualEffect | null;
 /** Resolve all external references in an Essence file */
@@ -619,4 +657,4 @@ declare function resolveEssence(essence: EssenceFile, resolver: ContentResolver)
 /** Convert a kebab-case or snake_case string to PascalCase */
 declare function pascalCase(str: string): string;
 
-export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };
+export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type RealizationAdapter, type RealizationInteractionPlaceholder, type RealizationMockDataSeed, type RealizationPlan, type RealizationRoute, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileRealizationPlan, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };