@fragments-sdk/context 0.4.2 → 0.4.4

package/dist/{chunk-2UQY4VNM.js → chunk-AW6Q5736.js}

@@ -81,7 +81,68 @@ function generateMarkdownContext(fragments, include, compact, blocks) {
         lines.push("");
       }
     }
-    if (include.props && Object.keys(fragment.props).length > 0) {
+    if (fragment.ai?.compositionPattern) {
+      const ai = fragment.ai;
+      const parts = [`**Composition:** ${ai.compositionPattern}`];
+      if (ai.subComponents && ai.subComponents.length > 0) {
+        parts.push(`Sub-components: ${ai.subComponents.map((s) => `${fragment.meta.name}.${s}`).join(", ")}`);
+      }
+      if (ai.requiredChildren && ai.requiredChildren.length > 0) {
+        parts.push(`Required: ${ai.requiredChildren.map((c) => `${fragment.meta.name}.${c}`).join(", ")}`);
+      }
+      lines.push(parts.join(" | "));
+      lines.push("");
+      if (ai.commonPatterns && ai.commonPatterns.length > 0) {
+        lines.push("**Patterns:**");
+        for (const pattern of ai.commonPatterns) {
+          lines.push(`- \`${pattern}\``);
+        }
+        lines.push("");
+      }
+    }
+    if (fragment.contract) {
+      const contract = fragment.contract;
+      if (contract.propsSummary && contract.propsSummary.length > 0) {
+        lines.push(`**Props:** ${contract.propsSummary.join(", ")}`);
+        lines.push("");
+      } else if (include.props && Object.keys(fragment.props).length > 0) {
+        lines.push("**Props:**");
+        for (const [name, prop] of Object.entries(fragment.props)) {
+          lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
+        }
+        lines.push("");
+      }
+      if (contract.compoundChildren && Object.keys(contract.compoundChildren).length > 0) {
+        lines.push("**Sub-components:**");
+        for (const [childName, childMeta] of Object.entries(contract.compoundChildren)) {
+          const parts = [`\`${fragment.meta.name}.${childName}\``];
+          if (childMeta.required) parts.push("(required)");
+          if (childMeta.description) parts.push(`\u2014 ${childMeta.description}`);
+          lines.push(`- ${parts.join(" ")}`);
+        }
+        lines.push("");
+      }
+      if (contract.canonicalUsage && contract.canonicalUsage.length > 0) {
+        lines.push("**Usage examples:**");
+        for (const usage of contract.canonicalUsage) {
+          lines.push("```tsx");
+          lines.push(usage);
+          lines.push("```");
+        }
+        lines.push("");
+      }
+      if (contract.a11yRules && contract.a11yRules.length > 0) {
+        lines.push(`**A11y:** ${contract.a11yRules.join(", ")}`);
+        lines.push("");
+      }
+      if (contract.bans && contract.bans.length > 0) {
+        lines.push("**Banned patterns:**");
+        for (const ban of contract.bans) {
+          lines.push(`- \`${ban.pattern}\`: ${ban.message}`);
+        }
+        lines.push("");
+      }
+    } else if (include.props && Object.keys(fragment.props).length > 0) {
       lines.push("**Props:**");
       for (const [name, prop] of Object.entries(fragment.props)) {
         lines.push(`- \`${name}\`: ${formatPropType(prop)}${prop.required ? " (required)" : ""}`);
@@ -159,6 +220,35 @@ function generateJsonContext(fragments, include, compact, blocks) {
         if (whenFiltered.length > 0) component.whenToUse = whenFiltered;
         if (whenNotFiltered.length > 0) component.whenNotToUse = whenNotFiltered;
       }
+      if (fragment.ai?.compositionPattern) {
+        const ai = fragment.ai;
+        const comp = { pattern: ai.compositionPattern };
+        if (ai.subComponents && ai.subComponents.length > 0) {
+          comp.subComponents = ai.subComponents;
+        }
+        if (ai.requiredChildren && ai.requiredChildren.length > 0) {
+          comp.requiredChildren = ai.requiredChildren;
+        }
+        if (ai.commonPatterns && ai.commonPatterns.length > 0) {
+          comp.commonPatterns = ai.commonPatterns;
+        }
+        component.composition = comp;
+      }
+      if (fragment.contract?.propsSummary && fragment.contract.propsSummary.length > 0) {
+        component.propsSummary = fragment.contract.propsSummary;
+      }
+      if (fragment.contract?.compoundChildren && Object.keys(fragment.contract.compoundChildren).length > 0) {
+        component.compoundChildren = fragment.contract.compoundChildren;
+      }
+      if (fragment.contract?.canonicalUsage && fragment.contract.canonicalUsage.length > 0) {
+        component.canonicalUsage = fragment.contract.canonicalUsage;
+      }
+      if (fragment.contract?.a11yRules && fragment.contract.a11yRules.length > 0) {
+        component.a11yRules = fragment.contract.a11yRules;
+      }
+      if (fragment.contract?.bans && fragment.contract.bans.length > 0) {
+        component.bans = fragment.contract.bans;
+      }
       if (include.props && Object.keys(fragment.props).length > 0) {
         component.props = {};
         for (const [name, prop] of Object.entries(fragment.props)) {

package/dist/{chunk-U7P5372N.js → chunk-BZ6SGVA2.js}

@@ -35,6 +35,19 @@ var CLI_COMMAND_CATEGORIES = {
 };
 var CLI_COMMANDS = [
   // ── Setup ──
+  {
+    name: "setup",
+    description: "Configure @fragments-sdk/ui in a consumer project (styles, providers, Next.js config)",
+    category: "setup",
+    usage: "fragments setup [options]",
+    options: [
+      { flags: "--root <dir>", description: "Project root directory" },
+      { flags: "-y, --yes", description: "Skip interactive prompts" },
+      { flags: "--brand <color>", description: "Brand color hex (e.g., #6366f1)" },
+      { flags: "--scss", description: "Create SCSS seed file for build-time theming" },
+      { flags: "--mcp", description: "Configure MCP server for AI tooling" }
+    ]
+  },
   {
     name: "init",
     description: "Initialize fragments in a project (interactive by default)",

package/dist/{chunk-FGBRIJOT.js → chunk-RTJ3JOPA.js}

@@ -288,6 +288,21 @@ var MCP_TOOL_DEFINITIONS = [
       }
     },
     required: ["component"]
+  },
+  {
+    key: "generate_ui",
+    description: "Generate a complete UI from a natural language description. Returns a structured element tree that can be rendered with Fragments components. Optionally pass an existing element tree to refine it.",
+    params: {
+      prompt: {
+        type: "string",
+        description: 'Natural language description of the UI to generate (e.g., "a settings page with profile section and notification preferences")'
+      },
+      currentTree: {
+        type: "object",
+        description: "Optional existing element tree to refine. When provided, the AI will modify this tree based on the prompt instead of generating from scratch."
+      }
+    },
+    required: ["prompt"]
   }
 ];
 var CLI_TOOL_EXTENSIONS = [

package/dist/cli-commands/index.js

@@ -1,7 +1,7 @@
 import {
   CLI_COMMANDS,
   CLI_COMMAND_CATEGORIES
-} from "../chunk-U7P5372N.js";
+} from "../chunk-BZ6SGVA2.js";
 export {
   CLI_COMMANDS,
   CLI_COMMAND_CATEGORIES

package/dist/generate/index.d.ts

@@ -1,5 +1,5 @@
 import { CompiledFragment, CompiledBlock } from '../types/index.js';
-import '../types-RAbbckR4.js';
+import '../types-ExvGbLOm.js';
 
 /**
  * Context generation for AI agents.

package/dist/generate/index.js

@@ -2,7 +2,7 @@ import {
   PLACEHOLDER_PATTERNS,
   filterPlaceholders,
   generateContext
-} from "../chunk-2UQY4VNM.js";
+} from "../chunk-AW6Q5736.js";
 export {
   PLACEHOLDER_PATTERNS,
   filterPlaceholders,

package/dist/graph/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ComponentGraph, G as GraphEdgeType, a as GraphEdge, I as ImpactResult, P as PathResult, N as NeighborResult, b as CompositionTree, c as GraphHealth, d as ComponentNode, S as SerializedComponentGraph } from '../types-RAbbckR4.js';
-export { E as EDGE_TYPE_WEIGHTS, f as GRAPH_EDGE_TYPES, e as SerializedEdge } from '../types-RAbbckR4.js';
+import { C as ComponentGraph, G as GraphEdgeType, a as GraphEdge, I as ImpactResult, P as PathResult, N as NeighborResult, b as CompositionTree, c as GraphHealth, d as ComponentNode, S as SerializedComponentGraph } from '../types-ExvGbLOm.js';
+export { E as EDGE_TYPE_WEIGHTS, f as GRAPH_EDGE_TYPES, e as SerializedEdge } from '../types-ExvGbLOm.js';
 
 /**
  * ComponentGraphEngine — query engine for the design-system relationship graph.

package/dist/index.d.ts

@@ -8,4 +8,4 @@ export { AST_SUPPORTED_LANGUAGES, ChangedFiles, FileEntry, GrammarMapping, INDEX
 export { ChunkMapping, CitationDocumentBlock, CitationDocumentOptions, DocumentMapping, RawCitation, ResolvedCitation, buildCitationDocuments, resolveCitation, resolveCitations } from './citations/index.js';
 export { CLI_TOOL_EXTENSIONS, CliToolExtension, MCP_TOOL_DEFINITIONS, McpToolDefinition, McpToolParam, buildMcpTools, buildToolNames } from './mcp-tools/index.js';
 export { CLI_COMMANDS, CLI_COMMAND_CATEGORIES, CliCategoryInfo, CliCommandCategory, CliCommandDef, CliOptionDef } from './cli-commands/index.js';
-import './types-RAbbckR4.js';
+import './types-ExvGbLOm.js';

package/dist/index.js

@@ -3,11 +3,11 @@ import {
   MCP_TOOL_DEFINITIONS,
   buildMcpTools,
   buildToolNames
-} from "./chunk-FGBRIJOT.js";
+} from "./chunk-RTJ3JOPA.js";
 import {
   CLI_COMMANDS,
   CLI_COMMAND_CATEGORIES
-} from "./chunk-U7P5372N.js";
+} from "./chunk-BZ6SGVA2.js";
 import {
   chunkByAST,
   chunkByLines,
@@ -36,7 +36,7 @@ import {
   PLACEHOLDER_PATTERNS,
   filterPlaceholders,
   generateContext
-} from "./chunk-2UQY4VNM.js";
+} from "./chunk-AW6Q5736.js";
 import {
   buildCitationDocuments,
   resolveCitation,

package/dist/mcp-tools/index.js

@@ -3,7 +3,7 @@ import {
   MCP_TOOL_DEFINITIONS,
   buildMcpTools,
   buildToolNames
-} from "../chunk-FGBRIJOT.js";
+} from "../chunk-RTJ3JOPA.js";
 export {
   CLI_TOOL_EXTENSIONS,
   MCP_TOOL_DEFINITIONS,

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-import { S as SerializedComponentGraph } from '../types-RAbbckR4.js';
+import { S as SerializedComponentGraph } from '../types-ExvGbLOm.js';
 
 /**
  * Compiled fragment types — shared between CLI and MCP packages.
@@ -73,6 +73,14 @@ interface FragmentContract {
     scenarioTags?: string[];
     /** Per-component performance budget override in bytes (gzipped) */
     performanceBudget?: number;
+    /** Sub-component slot metadata for compound components */
+    compoundChildren?: Record<string, {
+        required?: boolean;
+        accepts?: string[];
+        description?: string;
+    }>;
+    /** Canonical JSX usage examples showing how to assemble the component */
+    canonicalUsage?: string[];
 }
 /**
  * Provenance tracking for generated fragments
@@ -87,7 +95,7 @@ interface FragmentGenerated {
  * AI-specific metadata
  */
 interface AIMetadata {
-    compositionPattern?: "compound" | "simple" | "controlled";
+    compositionPattern?: "compound" | "simple" | "controlled" | "wrapper";
     subComponents?: string[];
     requiredChildren?: string[];
     commonPatterns?: string[];

package/dist/{types-RAbbckR4.d.ts → types-ExvGbLOm.d.ts}

@@ -12,7 +12,7 @@ interface ComponentNode {
     name: string;
     category: string;
     status: string;
-    compositionPattern?: 'compound' | 'simple' | 'controlled';
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
     subComponents?: string[];
 }
 interface GraphEdge {
@@ -84,7 +84,7 @@ interface CompositionTree {
     /** The root component */
     component: string;
     /** Composition pattern */
-    compositionPattern?: 'compound' | 'simple' | 'controlled';
+    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
     /** Direct sub-components */
     subComponents: string[];
     /** Components that declare this component as their parent */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/context",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "license": "FSL-1.1-MIT",
   "description": "Code intelligence and RAG primitives for design system and codebase indexing",
   "author": "Conan McNicholl",