@markdy/core 1.2.0 → 1.3.1

package/README.md

@@ -1,11 +1,25 @@
 # @markdy/core
 
-The parser and AST types for [MarkdyScript](../../docs/SYNTAX.md) — a diagram-native DSL for animated architecture diagrams that AI agents can generate reliably.
+<p align="center">
+  <a href="https://markdy.com/playground/"><img src="https://img.shields.io/badge/⚡_Live_Studio-markdy.com%2Fplayground-3b82f6?style=for-the-badge" alt="Live Studio" /></a>
+  <a href="https://markdy.com/docs/"><img src="https://img.shields.io/badge/📖_Docs-Documentation-10b981?style=for-the-badge" alt="Documentation" /></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode"><img src="https://img.shields.io/badge/🔌_VS_Code-Extension-8b5cf6?style=for-the-badge" alt="VS Code Extension" /></a>
+</p>
+
+The zero-dependency parser, dynamic port multiplexer, and AST routing engine for [MarkdyScript](https://markdy.com/docs/) — a diagram-native DSL for animated architecture diagrams that AI agents generate reliably.
+
+> 🚀 **Try it live**: Test MarkdyScript in the browser at **[markdy.com/playground](https://markdy.com/playground/)**  
+> 📚 **Documentation**: Complete syntax guide and examples at **[markdy.com/docs](https://markdy.com/docs/)**  
+> 🌟 **Architecture Blueprints**: 30+ canonical production diagrams at **[markdy.com/examples](https://markdy.com/examples/)**
 
 ## Features
 
 - **Zero runtime dependencies** — pure TypeScript, no DOM or platform APIs (~14 KB minzipped)
 - **Single-pass parser** — line-by-line state machine with strict `ParseError` line-number diagnostics
+- **Dynamic Port Multiplexer & Smooth Router** — obstacle-aware orthogonal Manhattan routing with balanced multi-lane fan-in/fan-out and smooth fillet curves
+- **Code Provenance & Git In-Tree Grounding** — anchor architecture nodes directly to source files (`@src="path/file.ts#L10-L40"`) with automated path traversal security and bounds validation
+- **Architectural Evolution & Git-Diff Matrix** — deep structural and visual comparison of architecture states with auto-generated animated migration storyboards
+- **Native Vector Symbol Registry** — zero-dependency vector SVG icons for 20+ top cloud, database, runtime, and messaging technologies
 - **17 Specialized Layout Engines** — `architecture`, `flowchart`, `tree`, `sequence`, `state`, `layers`, `nested`, `swimlane`, `timeline`, `gantt`, `medallion`, `flywheel`, `constellation`, `quadrant`, `pyramid`, `radar`, `venn`
 - **10 Semantic Themes** — `paper`, `editorial`, `midnight`, `blueprint`, `graphite`, `nebula`, `terminal`, `sketchy`, `ink`, `doodle`
 - **Content-Adaptive Canvas Sizing** — automatically calculates optimal aspect ratio and bounds based on diagram items and topology
@@ -18,31 +32,22 @@ The parser and AST types for [MarkdyScript](../../docs/SYNTAX.md) — a diagram-
 pnpm add @markdy/core
 ```
 
-## Package position (text)
+## Package Position
 
 ```text
 @markdy/core
   -> parser + AST types (no DOM, no runtime deps)
+  -> dynamic port multiplexer & orthogonal router
+  -> code provenance & git verification
+  -> architectural evolution & diff matrix
+  -> native vector symbol registry
   -> foundation for renderer, CLI, language server, and integrations
 ```
 
-## Output preview
-
-<p align="center">
-  <a href="https://markdy.com/playground/">
-    <img src="https://raw.githubusercontent.com/HoangYell/markdy-com/main/website/public/images/scene-url-shortener.webp" alt="Markdy Core Parser Architecture Preview" width="900" />
-  </a>
-</p>
-<p align="center">
-  <a href="https://markdy.com/playground/">
-    <img src="https://raw.githubusercontent.com/HoangYell/markdy-com/main/website/public/images/scene-concurrency-decision-flowchart.webp" alt="Markdy Concurrency Flowchart Preview" width="900" />
-  </a>
-</p>
-
 ## Usage
 
 ```typescript
-import { parse, ParseError } from "@markdy/core";
+import { parse, ParseError, diffDiagramASTs, resolveVectorSymbol } from "@markdy/core";
 import type { DiagramAST } from "@markdy/core";
 
 const source = `
@@ -51,8 +56,9 @@ layout LR
 
 browser Client "Web Client"
 gateway Gateway "API Gateway"
-service Shortener "URL Service"
-cache Redis "Redis Cluster"
+service Shortener "URL Service" @src="src/url/service.ts#L15-L80"
+cache Redis "Redis Cluster" icon=redis
+database Postgres "PostgreSQL 16" icon=postgresql
 
 beat hit:
   show $nodes stagger=60ms
@@ -66,7 +72,7 @@ try {
   const ast: DiagramAST = parse(source);
 
   console.log(ast.meta);   // { width: 1280, height: 720, fps: 60, theme: "paper", direction: "LR", title: "Cache-Aside Architecture" }
-  console.log(ast.nodes);  // { Client: { kind: "browser", ... }, Gateway: { ... } }
+  console.log(ast.nodes);  // { Client: { kind: "browser", ... }, Shortener: { ... } }
   console.log(ast.beats);  // [{ name: "hit", cues: [...] }]
 } catch (e) {
   if (e instanceof ParseError) {
@@ -75,33 +81,31 @@ try {
 }
 ```
 
-## Exports
+## Key API Exports
 
 | Export | Type | Description |
 |---|---|---|
 | `parse` | `(source, opts?) => DiagramAST` | Parse MarkdyScript source into a diagram AST |
 | `compile` | `(ast) => RenderPlan` | Lay out nodes, route edges, and schedule cues |
-| `compilePlan` | `(ast, theme) => RenderPlan` | Compile AST against a resolved theme token set |
-| `computeAdaptiveDimensions` | `(ast, edges?) => { width, height }` | Compute content-adaptive canvas dimensions from topology & items |
-| `parseAndCompile` | `(source) => { ast, plan }` | Parse and compile in one call |
-| `ParseError` | class | Error with `.line` number for diagnostics |
-| `DiagramAST` | type | Parsed scene: meta, nodes, edges, groups, patterns, beats |
-| `RenderPlan` | type | Positioned nodes, routed edges, group zones, sequence messages, timed cues, beat ranges |
-| `SceneMeta` | type | Scene configuration; `meta.player` is authoritative, with deprecated flat mirrors retained for compatibility |
-| `PlayerConfig` / `resolvePlayer` | type / function | Grouped playback, controls, interaction, and chrome configuration with host resolution |
+| `routeOrthogonalEdge` | `(src, tgt, opts?) => RoutedPath` | Compute collision-aware orthogonal waypoints with smooth fillet curves |
+| `allocatePortLanes` | `(edges, boxes) => Map` | Dynamic port multiplexer distributing multi-edge lanes along node perimeters |
+| `parseCodeAnchor` / `extractDiagramCodeAnchors` | `functions` | Parse and extract `@src` code provenance anchors from diagram nodes |
+| `verifyCodeAnchorsWithReader` | `(anchors, reader) => Report` | Verify code anchors against local repository files and line counts |
+| `diffDiagramASTs` | `(astA, astB) => DiffResult` | Compare architecture versions and generate executable migration storyboards |
+| `resolveVectorSymbol` / `renderSymbolSvg` | `functions` | Zero-dependency vector SVG icon registry (AWS, K8s, Redis, Postgres, Kafka...) |
 | `generateThemeFromBrand` | `(hexColor, name?) => { light, dark }` | Generate WCAG-compliant light and dark theme palettes from any brand hex color |
-| `validateArchitectureRules` | `(ast) => Diagnostic[]` | Run Well-Architected rules: cycle detection, layer boundaries, and gateway checks |
-| `diffAST` | `(astA, astB) => ASTDiffResult` | Compare architecture versions, calculate diff metrics, and generate migration scenes |
-| `compressUrlState` / `decompressUrlState` | `(code, opts?) => string` | Zero-dependency URL hash state encoder for shareable playground links |
-| `THEMES` / `resolveTheme` | tokens / function | 10 Semantic theme palettes (`paper`, `editorial`, `nebula`, `midnight`, `blueprint`, `graphite`, `terminal`, `sketchy`, `ink`, `doodle`) |
+| `compressMarkdyToUrlHash` / `decompress` | `functions` | Lossless URL hash state encoder for shareable playground links |
+| `THEMES` / `resolveTheme` | tokens / function | 10 Semantic theme palettes |
 
-## Documentation
+## Ecosystem & Documentation
 
-- **[Syntax Reference](../../docs/SYNTAX.md)** — complete DSL language spec
-- **[Tutorial](../../docs/TUTORIAL.md)** — step-by-step guide
-- **[Agent Guide](https://markdy.com/agent/)** — structured reference for AI/LLM code generation
-- **[Architecture](../../docs/ARCHITECTURE.md)** — parser internals and design decisions
+- ⚡ **[Interactive Studio / Playground](https://markdy.com/playground/)** — edit MarkdyScript with instant live preview in your browser
+- 📖 **[Syntax Guide & Reference](https://markdy.com/docs/)** — complete language specification and keywords
+- 🌟 **[Canonical Blueprints](https://markdy.com/examples/)** — production-grade distributed system and cloud architectures
+- 🤖 **[Agent Engineering Guide](https://markdy.com/agent/)** — instructions for LLMs (Claude, GPT, Gemini) to generate valid Markdy
+- 🔌 **[VS Code Marketplace Extension](https://marketplace.visualstudio.com/items?itemName=hoangyell.markdy-vscode)** — syntax highlighting and live preview in editor
+- 📦 **[GitHub Repository](https://github.com/HoangYell/markdy-com)** — source code, benchmarks, and issue tracker
 
 ## License
 
-[MIT](../../LICENSE)
+[MIT](https://github.com/HoangYell/markdy-com/blob/main/LICENSE)

package/dist/index.d.ts

@@ -547,7 +547,8 @@ declare function classifyTechnology(id: string, label?: string): SemanticProfile
 
 /**
  * packages/core/src/diff.ts
- * Semantic AST Diffing and Architectural Evolution for MarkdyScript.
+ * Architectural Evolution and Git-Diff Engine for Markdy.
+ * Calculates structural deltas between two architectural states and generates animated migration storyboards.
  * Zero external dependencies.
  */
 
@@ -564,16 +565,30 @@ interface EdgeDiff {
     status: DiffChangeType;
     before?: EdgeDecl;
     after?: EdgeDecl;
+    changes: string[];
+}
+interface GroupDiff {
+    id: string;
+    status: DiffChangeType;
+    before?: GroupDecl;
+    after?: GroupDecl;
+    changes: string[];
 }
 interface DiagramDiffResult {
     nodes: NodeDiff[];
     edges: EdgeDiff[];
+    groups: GroupDiff[];
     addedNodesCount: number;
     removedNodesCount: number;
     modifiedNodesCount: number;
+    addedEdgesCount: number;
+    removedEdgesCount: number;
     summaryMarkdown: string;
     evolutionMarkdyScript: string;
 }
+/**
+ * Compares two Diagram ASTs to produce a comprehensive architectural evolution report.
+ */
 declare function diffDiagramASTs(beforeAST: DiagramAST, afterAST: DiagramAST): DiagramDiffResult;
 
 /**
@@ -586,7 +601,8 @@ declare function decompressMarkdyFromUrlHash(hash: string): Promise<string>;
 
 /**
  * packages/core/src/router.ts
- * Collision-aware Orthogonal Manhattan Router for Markdy.
+ * Collision-aware Orthogonal Manhattan Router with Dynamic Port Multiplexing.
+ * Clean-room re-engineered for Markdy.
  * Zero external dependencies.
  */
 interface Point {
@@ -600,6 +616,19 @@ interface Box {
     height: number;
 }
 type CardinalPort = "left" | "right" | "top" | "bottom";
+interface PortLane {
+    index: number;
+    total: number;
+}
+interface RouteOptions {
+    sourceLane?: PortLane;
+    targetLane?: PortLane;
+    sourcePort?: CardinalPort;
+    targetPort?: CardinalPort;
+    cornerRadius?: number;
+    margin?: number;
+    obstacles?: Box[];
+}
 interface RoutedPath {
     sourcePort: CardinalPort;
     targetPort: CardinalPort;
@@ -608,12 +637,116 @@ interface RoutedPath {
     waypoints: Point[];
     svgPathData: string;
 }
-declare function getBoxPortPosition(box: Box, port: CardinalPort): Point;
+/**
+ * Calculates the exact point of connection on a bounding box for a given cardinal port and dynamic lane.
+ */
+declare function getBoxPortPosition(box: Box, port: CardinalPort, lane?: PortLane): Point;
+/**
+ * Automatically chooses the optimal cardinal ports connecting two bounding boxes.
+ */
 declare function selectOptimalPorts(sourceBox: Box, targetBox: Box): {
     sourcePort: CardinalPort;
     targetPort: CardinalPort;
 };
-declare function routeOrthogonalEdge(sourceBox: Box, targetBox: Box): RoutedPath;
+/**
+ * Builds an SVG path string with optional smooth fillet rounded corners.
+ */
+declare function buildSmoothSvgPath(start: Point, waypoints: Point[], end: Point, cornerRadius?: number): string;
+/**
+ * Routes an orthogonal edge between two boxes with collision awareness and dynamic port multiplexing.
+ */
+declare function routeOrthogonalEdge(sourceBox: Box, targetBox: Box, options?: RouteOptions): RoutedPath;
+/**
+ * Dynamic Port Multiplexer:
+ * Allocates balanced, collision-free port lanes for multiple edges attaching to the same node boundary.
+ * Seamlessly handles multi-edge fan-in/fan-out and bidirectional request/response pairs without overlapping.
+ */
+declare function allocatePortLanes<T extends {
+    from: string;
+    to: string;
+    id?: string;
+}>(edges: T[], boxes: Record<string, Box>): Map<T, {
+    sourceLane?: PortLane;
+    targetLane?: PortLane;
+}>;
+
+/**
+ * packages/core/src/symbols.ts
+ * Native Zero-Dependency Vector Symbol Registry for Markdy.
+ * High-performance inline SVG paths for modern system architecture stacks.
+ */
+interface VectorSymbol {
+    name: string;
+    category: "cloud" | "database" | "compute" | "messaging" | "runtime" | "gateway" | "client" | "security" | "observability" | "data";
+    viewBox: string;
+    svgPaths: string;
+    brandColor?: string;
+}
+declare const VECTOR_SYMBOLS: Record<string, VectorSymbol>;
+/**
+ * Resolves a vector symbol definition by key or normalized alias.
+ */
+declare function resolveVectorSymbol(nameOrAlias: string): VectorSymbol | null;
+/**
+ * Returns a standalone SVG snippet string for a vector symbol.
+ */
+declare function renderSymbolSvg(symbol: VectorSymbol | string, options?: {
+    size?: number;
+    className?: string;
+    color?: string;
+}): string | null;
+/**
+ * Lists all available vector symbol names registered in Markdy.
+ */
+declare function listAvailableSymbols(): string[];
+
+/**
+ * packages/core/src/provenance.ts
+ * Code Provenance and Git Verification Engine for Markdy.
+ * Anchors architecture diagram components to physical source code references with deterministic proof.
+ * Zero runtime dependencies (Node fs/path utilized conditionally in verification CLI).
+ */
+
+interface CodeProvenanceAnchor {
+    raw: string;
+    filePath: string;
+    startLine?: number;
+    endLine?: number;
+    revision?: string;
+    resolvedHref?: string;
+}
+interface CodeProvenanceDiagnostic {
+    nodeId: string;
+    severity: "error" | "warning";
+    code: "provenance/path-invalid" | "provenance/path-escape" | "provenance/file-not-found" | "provenance/line-out-of-bounds" | "provenance/git-mismatch";
+    message: string;
+    filePath: string;
+    line?: number;
+    fixSuggestion?: string;
+}
+interface CodeProvenanceVerificationReport {
+    isValid: boolean;
+    totalAnchors: number;
+    verifiedCount: number;
+    anchors: Map<string, CodeProvenanceAnchor>;
+    diagnostics: CodeProvenanceDiagnostic[];
+    summaryMarkdown: string;
+}
+/**
+ * Parses a code anchor string (e.g. "src/auth/jwt.ts#L20-L85" or "prisma/schema.prisma#L110").
+ */
+declare function parseCodeAnchor(raw: unknown, repositoryUrl?: string, revision?: string): CodeProvenanceAnchor | null;
+/**
+ * Extracts all code provenance anchors declared on nodes across a DiagramAST.
+ */
+declare function extractDiagramCodeAnchors(ast: DiagramAST, repositoryUrl?: string, revision?: string): Map<string, CodeProvenanceAnchor>;
+/**
+ * Verifies code provenance anchors against a filesystem reader interface.
+ */
+declare function verifyCodeAnchorsWithReader(anchors: Map<string, CodeProvenanceAnchor>, fileReader: {
+    fileExists: (relPath: string) => boolean;
+    getLineCount: (relPath: string) => number;
+}): CodeProvenanceVerificationReport;
 
 /**
  * packages/core/src/syntax-diagnostics.ts
@@ -783,4 +916,219 @@ declare function getArchitectureSuggestions(docText: string): ArchitectureRecomm
 
 declare function formatScene(ast: DiagramAST): string;
 
-export { ARCH_RULE_PRESETS, type AnnotationDecl, type ArchRuleType, type ArchitecturePreset, type ArchitectureRecommendation, type ArchitectureRule, type ArchitectureViolation, type AutoRepairResult, BEAT_CUE_KEYWORDS, type BeatDecl, type BeatRange, type Box, CUE_ALIASES, type CardinalPort, type Cue, DIAGRAM_TYPES, type Diagnostic, type DiagnosticIssue, type DiagramAST, type DiagramContext, type DiagramDiffResult, type DiagramType, type DiffChangeType, EDGE_OPERATORS, type EdgeDecl, type EdgeDiff, type EdgeKind, type EdgeSelector, type ExtractedBeat, type ExtractedGroup, type ExtractedNode, type FlowSegment, type GhostTextSuggestion, type GroupBoundary, type GroupDecl, type IntelliCodeItem, type IntelliCodeItemKind, type LayoutDirection, type MarkdyConfig, NODE_ALIASES, NODE_KINDS, type NodeDecl, type NodeDiff, type NodeSelector, type NodeShape, OUTPUT_PRESETS, type OutputPreset, PLAYER_FLAT_KEYS, PLAYER_GROUPS, POPULAR_TECHS, ParseError, type ParseOptions, type ParseResult, type PatternDecl, type PlayerChromeConfig, type PlayerConfig, type PlayerControlsConfig, type PlayerInteractionConfig, type PlayerOverrides, type PlayerPlaybackConfig, type PlayerProgress, type PlayerScope, type Point, type PositionedNode, type RenderPlan, type RepairPromptBundle, type ResolvedPlayer, type RoutedEdge, type RoutedPath, type RuleSeverity, SCENE_KEYS, type SceneMeta, type SemanticProfile, type SequenceActivation, type SequenceMessage, type StyleDecl, type SyntaxDiagnosticReport, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, THEMES, type TechPreset, type ThemeGeneratorOptions, type ThemeTokens, type TimedCue, type TreeBus, VISUAL_PRIMITIVE_TYPES, analyzeAndBuildRepairPrompt, applyPlayerSetting, canonicalNodeKind, classifyTechnology, compile, compilePlan, compressMarkdyToUrlHash, computeAdaptiveDimensions, damerauLevenshteinDistance, decompressMarkdyFromUrlHash, diagnoseMarkdyCode, diffDiagramASTs, extractDiagramContext, findClosestMatch, formatScene, generateThemeFromBrand, getArchitectureSuggestions, getBoxPortPosition, getIntelliCodeCompletions, humanizeId, listOutputPresets, nodeRole, parse, parseAndCompile, predictNextLineSuggestion, repairMarkdyCode, resolveArchitectureConfig, resolveOutputPreset, resolvePlayer, resolveTheme, routeOrthogonalEdge, selectOptimalPorts, validateArchitecture };
+/**
+ * packages/core/src/recipes.ts
+ * Architectural Scenario Recipes & Recommendation Engine for Markdy.
+ * Clean-room re-engineered architectural pattern catalog and AI prompt matching.
+ * Zero external dependencies.
+ */
+interface ArchitectureRecipe {
+    id: string;
+    name: string;
+    category: "caching" | "streaming" | "microservices" | "security" | "data" | "ai" | "resilience" | "consensus" | "observability";
+    description: string;
+    keywords: string[];
+    recommendedLayout: "LR" | "TD" | "TB" | "RL";
+    primaryNodes: string[];
+    code: string;
+    highlights: string[];
+}
+declare const ARCHITECTURE_RECIPES: ArchitectureRecipe[];
+interface PatternRecommendationResult {
+    recipe: ArchitectureRecipe;
+    score: number;
+    matchedKeywords: string[];
+    rationale: string;
+}
+/**
+ * Recommends best architecture recipes for a user prompt or requirement query.
+ */
+declare function recommendArchitecturePattern(query: string): PatternRecommendationResult[];
+interface SynthesizedRecipeResult {
+    markdyScript: string;
+    detectedComponents: Array<{
+        id: string;
+        label: string;
+        kind: string;
+        icon?: string;
+    }>;
+    inferredPattern: string;
+    rationale: string;
+}
+/**
+ * Zero-token deterministic dynamic architecture synthesis engine.
+ * Parses user requirements and synthesizes custom tailor-made MarkdyScript diagrams.
+ */
+declare function synthesizeCustomRecipe(query: string): SynthesizedRecipeResult;
+/**
+ * Retrieves an architecture recipe by its exact ID or alias.
+ */
+declare function getArchitectureRecipe(id: string): ArchitectureRecipe | undefined;
+/**
+ * Lists all available architecture recipes.
+ */
+declare function listArchitectureRecipes(): ArchitectureRecipe[];
+
+/**
+ * packages/core/src/verifier.ts
+ * 9-Point Quality Gate & Responsive Viewport Verifier for Markdy.
+ * Clean-room re-engineered deterministic artifact validation and integrity reporting.
+ * Zero external dependencies.
+ */
+
+type QualityProfile = "standard" | "showcase";
+interface QualityCheckItem {
+    id: string;
+    name: string;
+    category: "syntax" | "geometry" | "governance" | "provenance" | "visual";
+    status: "pass" | "warn" | "fail";
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface DiagramQualityMetrics {
+    nodeCount: number;
+    edgeCount: number;
+    beatCount: number;
+    hasCodeProvenance: boolean;
+    provenanceAnchorCount: number;
+    symbolCount: number;
+    estimatedWidth: number;
+    estimatedHeight: number;
+    aspectRatio: number;
+}
+interface QualityGateReport {
+    passed: boolean;
+    qualityProfile: QualityProfile;
+    errorCount: number;
+    warningCount: number;
+    sha256Receipt: string;
+    checks: QualityCheckItem[];
+    metrics: DiagramQualityMetrics;
+    viewportCompliance: {
+        "1440x900": boolean;
+        "1600x1000": boolean;
+        "1920x1080": boolean;
+        "2048x1320": boolean;
+    };
+}
+interface QualityGateOptions {
+    profile?: QualityProfile;
+    strictCycles?: boolean;
+}
+/**
+ * Runs the complete 12-Point Quality Gate & Viewport Verification on a DiagramAST.
+ */
+declare function verifyDiagramQuality(astOrCode: DiagramAST | string, options?: QualityGateOptions): QualityGateReport;
+
+/**
+ * packages/core/src/c4.ts
+ * C4 Hierarchical Architecture Engine for Markdy.
+ * Supports L1 System Context, L2 Containers, L3 Components, and L4 Code Provenance views.
+ * Zero external dependencies.
+ */
+
+type C4Level = "context" | "container" | "component" | "code";
+interface C4NodeMeta {
+    id: string;
+    level: C4Level;
+    levelNumber: 1 | 2 | 3 | 4;
+    isExternal: boolean;
+    containerParent?: string;
+    hasCodeProvenance: boolean;
+}
+interface C4ModelReport {
+    ast: DiagramAST;
+    levelsPresent: Record<C4Level, number>;
+    nodesByLevel: Record<C4Level, string[]>;
+    summaryMarkdown: string;
+}
+/**
+ * Infers the C4 abstraction level of a node based on explicit @c4 prop or node characteristics.
+ */
+declare function inferNodeC4Level(node: NodeDecl): {
+    level: C4Level;
+    levelNumber: 1 | 2 | 3 | 4;
+};
+/**
+ * Analyzes the C4 model distribution of a Diagram AST.
+ */
+declare function analyzeC4Model(ast: DiagramAST): C4ModelReport;
+/**
+ * Filters a Diagram AST to a specific C4 abstraction ceiling (e.g. show all nodes up to L2 Container level).
+ */
+declare function filterC4Hierarchy(ast: DiagramAST, maxLevel?: C4Level | 1 | 2 | 3 | 4): {
+    filteredAst: DiagramAST;
+    visibleNodeIds: string[];
+};
+/**
+ * Automatically synthesizes a 4-beat interactive narrative storyboard zooming through C4 levels.
+ */
+declare function generateC4Storyboard(ast: DiagramAST): string;
+interface C4LevelViewExport {
+    level: C4Level;
+    levelNumber: 1 | 2 | 3 | 4;
+    title: string;
+    markdyScript: string;
+    nodeCount: number;
+    edgeCount: number;
+}
+/**
+ * Exports isolated, production-ready MarkdyScript blueprints for each of the 4 C4 levels.
+ */
+declare function exportC4LevelViews(ast: DiagramAST): Record<C4Level, C4LevelViewExport>;
+/**
+ * Validates cross-level containment and flags orphaned lower-level components.
+ */
+declare function validateC4Containment(ast: DiagramAST): {
+    isValid: boolean;
+    issues: string[];
+};
+
+/**
+ * packages/core/src/drift.ts
+ * Architecture Drift Detection and In-Tree Code Synchronization Engine for Markdy.
+ * Identifies drift between architecture models and real physical repository codebases.
+ * Zero external dependencies.
+ */
+
+interface BrokenAnchorDrift {
+    nodeId: string;
+    nodeLabel: string;
+    declaredPath: string;
+    reason: "file_not_found" | "path_escaped";
+}
+interface OrphanCodeServiceDrift {
+    suggestedId: string;
+    suggestedKind: string;
+    discoveredPath: string;
+}
+interface ArchitectureDriftReport {
+    isSynchronized: boolean;
+    totalAnchorsChecked: number;
+    validAnchorCount: number;
+    brokenAnchors: BrokenAnchorDrift[];
+    orphanCodeServices: OrphanCodeServiceDrift[];
+    summaryMarkdown: string;
+    healingMarkdySnippet?: string;
+}
+/**
+ * Detects architectural drift between a Diagram AST and a list of physical repository files.
+ */
+declare function detectArchitectureDrift(ast: DiagramAST, existingFiles?: string[]): ArchitectureDriftReport;
+interface AutoHealResult {
+    healedAst: DiagramAST;
+    healedMarkdyScript: string;
+    healedAnchorCount: number;
+    addedServiceCount: number;
+    healedMappings: Array<{
+        nodeId: string;
+        oldPath: string;
+        newPath: string;
+    }>;
+}
+/**
+ * Automatically heals broken architecture anchors and incorporates orphan code services.
+ */
+declare function autoHealArchitectureDrift(ast: DiagramAST, report: ArchitectureDriftReport, existingFiles?: string[]): AutoHealResult;
+
+export { ARCHITECTURE_RECIPES, ARCH_RULE_PRESETS, type AnnotationDecl, type ArchRuleType, type ArchitectureDriftReport, type ArchitecturePreset, type ArchitectureRecipe, type ArchitectureRecommendation, type ArchitectureRule, type ArchitectureViolation, type AutoHealResult, type AutoRepairResult, BEAT_CUE_KEYWORDS, type BeatDecl, type BeatRange, type Box, type BrokenAnchorDrift, type C4Level, type C4LevelViewExport, type C4ModelReport, type C4NodeMeta, CUE_ALIASES, type CardinalPort, type CodeProvenanceAnchor, type CodeProvenanceDiagnostic, type CodeProvenanceVerificationReport, type Cue, DIAGRAM_TYPES, type Diagnostic, type DiagnosticIssue, type DiagramAST, type DiagramContext, type DiagramDiffResult, type DiagramQualityMetrics, type DiagramType, type DiffChangeType, EDGE_OPERATORS, type EdgeDecl, type EdgeDiff, type EdgeKind, type EdgeSelector, type ExtractedBeat, type ExtractedGroup, type ExtractedNode, type FlowSegment, type GhostTextSuggestion, type GroupBoundary, type GroupDecl, type GroupDiff, type IntelliCodeItem, type IntelliCodeItemKind, type LayoutDirection, type MarkdyConfig, NODE_ALIASES, NODE_KINDS, type NodeDecl, type NodeDiff, type NodeSelector, type NodeShape, OUTPUT_PRESETS, type OrphanCodeServiceDrift, type OutputPreset, PLAYER_FLAT_KEYS, PLAYER_GROUPS, POPULAR_TECHS, ParseError, type ParseOptions, type ParseResult, type PatternDecl, type PatternRecommendationResult, type PlayerChromeConfig, type PlayerConfig, type PlayerControlsConfig, type PlayerInteractionConfig, type PlayerOverrides, type PlayerPlaybackConfig, type PlayerProgress, type PlayerScope, type Point, type PortLane, type PositionedNode, type QualityCheckItem, type QualityGateOptions, type QualityGateReport, type QualityProfile, type RenderPlan, type RepairPromptBundle, type ResolvedPlayer, type RouteOptions, type RoutedEdge, type RoutedPath, type RuleSeverity, SCENE_KEYS, type SceneMeta, type SemanticProfile, type SequenceActivation, type SequenceMessage, type StyleDecl, type SyntaxDiagnosticReport, type SynthesizedRecipeResult, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, THEMES, type TechPreset, type ThemeGeneratorOptions, type ThemeTokens, type TimedCue, type TreeBus, VECTOR_SYMBOLS, VISUAL_PRIMITIVE_TYPES, type VectorSymbol, allocatePortLanes, analyzeAndBuildRepairPrompt, analyzeC4Model, applyPlayerSetting, autoHealArchitectureDrift, buildSmoothSvgPath, canonicalNodeKind, classifyTechnology, compile, compilePlan, compressMarkdyToUrlHash, computeAdaptiveDimensions, damerauLevenshteinDistance, decompressMarkdyFromUrlHash, detectArchitectureDrift, diagnoseMarkdyCode, diffDiagramASTs, exportC4LevelViews, extractDiagramCodeAnchors, extractDiagramContext, filterC4Hierarchy, findClosestMatch, formatScene, generateC4Storyboard, generateThemeFromBrand, getArchitectureRecipe, getArchitectureSuggestions, getBoxPortPosition, getIntelliCodeCompletions, humanizeId, inferNodeC4Level, listArchitectureRecipes, listAvailableSymbols, listOutputPresets, nodeRole, parse, parseAndCompile, parseCodeAnchor, predictNextLineSuggestion, recommendArchitecturePattern, renderSymbolSvg, repairMarkdyCode, resolveArchitectureConfig, resolveOutputPreset, resolvePlayer, resolveTheme, resolveVectorSymbol, routeOrthogonalEdge, selectOptimalPorts, synthesizeCustomRecipe, validateArchitecture, validateC4Containment, verifyCodeAnchorsWithReader, verifyDiagramQuality };