@nikkory/vibe-engine 4.0.0

package/README.md

@@ -0,0 +1,1267 @@
+# @nikkory/vibe-engine
+
+**Framework-Agnostic Code Generation Engine for Nikkory Vibe**
+
+Zero-token UI/UX code generation with 24-factor design system support.
+
+[![npm version](https://img.shields.io/npm/v/@nikkory/vibe-engine.svg)](https://www.npmjs.com/package/@nikkory/vibe-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- 🎨 **12 Design Systems**: Material Design, iOS HIG, Glassmorphism, Neumorphism, Brutalism, Minimalism, Cyberpunk, Flat Design, Retro Vintage, Fluent Design, Carbon Design, Ant Design
+- 🎯 **24-Factor System**: Comprehensive design configuration (Color, Size, Variant, Shape, Position, State, Animation, Elevation, A11y, Alignment, Orientation, Density, Loading, Responsive, Theme, Spacing, Typography, Border, Opacity, Overflow, Cursor, Z-Index, Transition)
+- 📦 **169 Components**: Button, Input, Card, Modal, Tabs, and 45+ more component types
+- 🔧 **Framework-Agnostic**: Use with React, Vue, Svelte, or any framework
+- 🏛️ **3-Tier Quality**: Basic (30-50 LOC), Standard (50-150 LOC), Enterprise (150-300 LOC)
+- 📊 **Component Registry**: Search, filter, browse 169 pre-configured components
+- 🎭 **Style Generation**: Runtime style generation with design tokens
+- 🛡️ **Type-Safe**: Full TypeScript support with strict mode
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @nikkory/vibe-engine
+
+# pnpm
+pnpm add @nikkory/vibe-engine
+
+# yarn
+yarn add @nikkory/vibe-engine
+```
+
+---
+
+## Quick Start
+
+### Style Generation
+
+```typescript
+import { generateStyles, cn } from '@nikkory/vibe-engine';
+
+// Generate component styles
+const styles = generateStyles({
+  componentType: 'button',
+  variant: 'filled',
+  size: 'md',
+  color: 'primary',
+});
+
+// Merge class names
+const className = cn('base-class', 'additional-class', {
+  'conditional-class': true,
+  'hidden-class': false,
+});
+```
+
+### Component Registry
+
+```typescript
+import {
+  ALL_COMPONENTS,
+  getComponent,
+  searchComponents,
+  getStableComponents,
+} from '@nikkory/vibe-engine';
+
+// Get all 169 components
+console.log(ALL_COMPONENTS.length); // 169
+
+// Get a specific component
+const button = getComponent('button');
+console.log(button.name); // "Button"
+
+// Search components
+const buttons = searchComponents('button'); // 10 results
+
+// Get stable components only
+const stable = getStableComponents(); // 169 components
+```
+
+### Design Systems
+
+```typescript
+import { CURRENT_DESIGN_SYSTEMS, DESIGN_SYSTEM_INFO } from '@nikkory/vibe-engine';
+
+// Available design systems (12 total)
+console.log(CURRENT_DESIGN_SYSTEMS);
+// ['material-design', 'ios-hig', 'glassmorphism', ...]
+
+// Get design system info
+const materialInfo = DESIGN_SYSTEM_INFO['material-design'];
+console.log(materialInfo.name); // "Material Design 3"
+```
+
+### Quality Tiers
+
+```typescript
+import { TIERS, TIER_INFO } from '@nikkory/vibe-engine';
+
+// Available tiers
+console.log(TIERS); // ['basic', 'standard', 'enterprise']
+
+// Get tier details
+const enterprise = TIER_INFO.enterprise;
+console.log(enterprise.features);
+// ['memo', 'useCallback', 'analytics', 'ARIA', 'error boundaries']
+```
+
+### 24-Factor Configuration
+
+```typescript
+import {
+  // Basic factors (1-6)
+  COLORS,
+  SIZES,
+  VARIANTS,
+  SHAPES,
+  POSITIONS,
+  ICON_POSITIONS,
+
+  // Standard factors (7-11)
+  STATES,
+  ANIMATIONS,
+  ELEVATIONS,
+  A11Y_LEVELS,
+  ALIGNMENTS,
+
+  // Enterprise factors (12-24)
+  ORIENTATIONS,
+  DENSITIES,
+  LOADING_STATES,
+  RESPONSIVE_BREAKPOINTS,
+  THEMES,
+  SPACINGS,
+  TYPOGRAPHIES,
+  BORDERS,
+  OPACITIES,
+  OVERFLOWS,
+  CURSORS,
+  Z_INDICES,
+  TRANSITIONS,
+} from '@nikkory/vibe-engine';
+
+// Use factors in configuration
+const config = {
+  color: COLORS[0], // 'primary'
+  size: SIZES[1], // 'md'
+  variant: VARIANTS[0], // 'filled'
+  animation: ANIMATIONS[0], // 'fadeIn'
+  elevation: ELEVATIONS[1], // 'medium'
+  a11yLevel: A11Y_LEVELS[1], // 'enhanced'
+};
+```
+
+---
+
+## API Reference
+
+### Style Generation
+
+#### `generateStyles(config: StyleConfig): GeneratedStyles`
+
+Generate component styles from configuration.
+
+**Parameters**:
+
+- `config.componentType`: Component type (`'button'`, `'input'`, etc.)
+- `config.variant`: Style variant (`'filled'`, `'outlined'`, etc.)
+- `config.size`: Component size (`'sm'`, `'md'`, `'lg'`)
+- `config.color`: Color scheme (`'primary'`, `'secondary'`, etc.)
+
+**Returns**: `{ className: string, styles: object }`
+
+#### `cn(...inputs: ClassValue[]): string`
+
+Merge class names with conditional support.
+
+**Parameters**:
+
+- `inputs`: Class names, objects, or arrays
+
+**Returns**: Merged class name string
+
+### Component Registry
+
+#### `ALL_COMPONENTS: RegistryComponentDefinition[]`
+
+Array of all 169 registered components.
+
+#### `getComponent(id: string): RegistryComponentDefinition | undefined`
+
+Get a component by ID.
+
+#### `searchComponents(query: string): RegistryComponentDefinition[]`
+
+Search components by name, tags, or category.
+
+#### `getStableComponents(): RegistryComponentDefinition[]`
+
+Get all components with `status: 'stable'`.
+
+#### `getPopularComponents(): RegistryComponentDefinition[]`
+
+Get all components marked as popular (15 components).
+
+#### `getNewComponents(): RegistryComponentDefinition[]`
+
+Get all components marked as new (7 components).
+
+### Constants
+
+#### `CURRENT_DESIGN_SYSTEMS: DesignSystem[]`
+
+Available design systems (12 total).
+
+#### `TIERS: Tier[]`
+
+Available quality tiers: `['basic', 'standard', 'enterprise']`.
+
+#### `CURRENT_COMPONENT_TYPES: ComponentType[]`
+
+Available component types (50 total).
+
+### Types
+
+```typescript
+import type {
+  // Core types
+  DesignSystem,
+  Tier,
+  ComponentType,
+  Factor24Config,
+  StyleConfig,
+  GeneratedStyles,
+
+  // Section Architecture types
+  SectionConfig,
+  SectionTemplate,
+  SectionFactors,
+  SectionCategory,
+  SlotConfig,
+  StoredComponentInSlot,
+  TemplateVisibility,
+  TemplateMetadata,
+
+  // Unified Granularity Architecture types
+  GranularityLevel,
+  GranularityConfig,
+  GranularityTemplate,
+  GranularitySlotConfig,
+  GranularitySlotPosition,
+  GranularityFactorDefinition,
+  GranularityFactorCategory,
+  GranularityFactorValues,
+  GranularityLayoutConfig,
+  ChildReference,
+  // Level-specific aliases
+  AtomConfig,
+  ComponentConfig,
+  PageConfig,
+  TemplateConfig,
+} from '@nikkory/vibe-engine';
+```
+
+---
+
+## 24-Factor Design System
+
+### Factors 1-6 (Basic Tier)
+
+| Factor           | Values                                            | Description     |
+| ---------------- | ------------------------------------------------- | --------------- |
+| 1. Color         | primary, secondary, success, error, warning, info | Color schemes   |
+| 2. Size          | xs, sm, md, lg, xl, 2xl                           | Component sizes |
+| 3. Variant       | filled, outlined, text, ghost                     | Style variants  |
+| 4. Shape         | rectangle, rounded, pill, circle                  | Corner radius   |
+| 5. Position      | top, right, bottom, left, center                  | Positioning     |
+| 6. Icon Position | left, right, top, bottom                          | Icon placement  |
+
+### Factors 7-11 (Standard Tier)
+
+| Factor        | Values                                  | Description         |
+| ------------- | --------------------------------------- | ------------------- |
+| 7. State      | default, hover, active, focus, disabled | Interaction states  |
+| 8. Animation  | none, fadeIn, slideIn, bounce, pulse    | Entry animations    |
+| 9. Elevation  | none, low, medium, high, highest        | Shadow depth        |
+| 10. A11y      | basic, enhanced, full                   | Accessibility level |
+| 11. Alignment | left, center, right, justify            | Text alignment      |
+
+### Factors 12-16 (Standard Extended)
+
+| Factor            | Values                        | Description      |
+| ----------------- | ----------------------------- | ---------------- |
+| 12. Orientation   | horizontal, vertical          | Layout direction |
+| 13. Density       | compact, normal, comfortable  | Spacing density  |
+| 14. Loading State | idle, loading, success, error | Async state      |
+| 15. Responsive    | xs, sm, md, lg, xl            | Breakpoints      |
+| 16. Theme         | light, dark, auto             | Color theme      |
+
+### Factors 17-24 (Enterprise Tier)
+
+| Factor         | Values                        | Description       |
+| -------------- | ----------------------------- | ----------------- |
+| 17. Spacing    | none, xs, sm, md, lg, xl      | Margins/padding   |
+| 18. Typography | xs, sm, base, lg, xl, 2xl     | Font sizes        |
+| 19. Border     | none, thin, medium, thick     | Border width      |
+| 20. Opacity    | 0, 25, 50, 75, 100            | Transparency      |
+| 21. Overflow   | visible, hidden, scroll, auto | Overflow behavior |
+| 22. Cursor     | default, pointer, wait, text  | Cursor style      |
+| 23. Z-Index    | 0, 10, 20, 30, 40, 50         | Stacking order    |
+| 24. Transition | none, fast, normal, slow      | Animation speed   |
+
+---
+
+## Algorithm Engine Registries
+
+**New in v4.0.0**: Registry-based architecture for the 24-Factor × 3-Tier × 12-Design-Systems generation engine.
+
+### Registry Overview
+
+| Registry                | Purpose                                       | Total Entries |
+| ----------------------- | --------------------------------------------- | ------------- |
+| Tiers Registry          | Maps tiers to factor ranges and code features | 3             |
+| Factors Registry        | 24 Factor definitions with metadata           | 24            |
+| Components Registry     | 34 Components with factor applicability       | 34            |
+| Design Systems Registry | 12 Design systems with factor values          | 12            |
+
+### Components Registry Usage
+
+```typescript
+import {
+  COMPONENT_REGISTRY,
+  getComponentEntry,
+  getAllComponentTypes,
+  getApplicableFactors,
+  getSkippedFactors,
+  getFactorApplicability,
+  componentSupportsDesignSystem,
+  searchComponents,
+} from '@nikkory/vibe-engine';
+
+// Get all 34 component types
+const types = getAllComponentTypes();
+console.log(types); // ['button', 'input', 'card', ...]
+
+// Get component entry with factor applicability
+const button = getComponentEntry('button');
+console.log(button.category); // 'basic'
+console.log(button.elementType); // 'button'
+
+// Get applicable factors for a component
+const factors = getApplicableFactors('button');
+console.log(factors); // [1, 2, 3, 4, 6, 7, 8, ...] (applicable factor IDs)
+
+// Get skipped factors (null applicability)
+const skipped = getSkippedFactors('button');
+console.log(skipped); // [5, 11, 12, ...] (Position, Alignment, Orientation)
+
+// Check factor applicability with overrides
+const applicability = getFactorApplicability('avatar', 4);
+console.log(applicability); // 'circle' (override value for Shape)
+
+// Search components
+const results = searchComponents('modal');
+```
+
+### Design Systems Registry Usage
+
+```typescript
+import {
+  DESIGN_SYSTEM_REGISTRY,
+  getDesignSystemEntry,
+  getAllDesignSystems,
+  getFactorValue,
+  getFactorTailwindClasses,
+  getDesignSystemCssVariables,
+  generateThemeCss,
+  mergeFactorValues,
+} from '@nikkory/vibe-engine';
+
+// Get all 12 design systems
+const systems = getAllDesignSystems();
+console.log(systems); // ['material-design', 'ios-hig', ...]
+
+// Get design system entry
+const md = getDesignSystemEntry('material-design');
+console.log(md.name); // 'Material Design'
+console.log(md.description); // 'Google Material Design 3...'
+
+// Get factor value for a design system
+const colorValue = getFactorValue('material-design', 1);
+console.log(colorValue?.tailwindClasses); // 'bg-blue-500 text-white hover:bg-blue-600'
+console.log(colorValue?.cssVariables); // { '--md-color-primary': '#2196f3' }
+
+// Get Tailwind classes directly
+const classes = getFactorTailwindClasses('brutalism', 4);
+console.log(classes); // 'rounded-none'
+
+// Get CSS variables for Tailwind v4 @theme
+const vars = getDesignSystemCssVariables('glassmorphism');
+console.log(vars['--glass-blur']); // '16px'
+
+// Generate @theme CSS block for Tailwind v4
+const themeCss = generateThemeCss('material-design');
+console.log(themeCss);
+// @theme {
+//   --md-color-primary: #2196f3;
+//   --md-color-secondary: #9c27b0;
+//   ...
+// }
+
+// Merge design system values with custom overrides
+const merged = mergeFactorValues('material-design', {
+  1: { factorId: 1, value: 'custom', tailwindClasses: 'bg-red-500' },
+});
+```
+
+### Factor Applicability Pattern
+
+Each component defines which of the 24 factors apply:
+
+```typescript
+type FactorApplicability = null | true | string;
+
+// null = factor not applicable (skip)
+// true = factor applicable with design system default
+// string = factor applicable with specific override value
+
+// Example: Avatar component
+{
+  factorApplicability: {
+    1: true,      // Color - use default
+    4: 'circle',  // Shape - override to circular
+    21: 'hidden', // Overflow - clip to shape
+  }
+}
+```
+
+### Tailwind v4 Integration
+
+Design systems provide CSS variables for Tailwind v4 `@theme` integration:
+
+```css
+/* Generated by generateThemeCss('material-design') */
+@theme {
+  --md-color-primary: #2196f3;
+  --md-color-secondary: #9c27b0;
+  --md-shape-corner-small: 4px;
+  --md-shape-corner-medium: 8px;
+  --md-motion-duration-short: 100ms;
+}
+```
+
+---
+
+## Section Architecture
+
+**New in v4.0.0**: Complete Section Architecture for building pages from configurable sections.
+
+### SectionConfig (14 Fields)
+
+```typescript
+import type {
+  SectionConfig,
+  SectionTemplate,
+  SectionFactors,
+  SectionCategory,
+  SlotConfig,
+  StoredComponentInSlot,
+} from '@nikkory/vibe-engine';
+
+// Create a section configuration
+const heroSection: SectionConfig = {
+  // Section-Level Fields (6)
+  sectionId: 'hero-1',
+  sectionType: 'hero',
+  title: 'Welcome to Our Platform',
+  subtitle: 'Build amazing experiences',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+
+  // Layout Fields (3)
+  layout: 'flex',
+  columns: 2,
+  spacing: 'lg',
+
+  // Generation Fields (2)
+  slots: [],
+  itemCount: 1,
+
+  // Component-Specific Fields (3)
+  showCta: true,
+  showMedia: true,
+  styleOverrides: { className: 'hero-custom' },
+};
+```
+
+### Section Categories (10 Types)
+
+| Category     | Description           | Typical Layout |
+| ------------ | --------------------- | -------------- |
+| hero         | Landing page hero     | flex, 1-2 cols |
+| features     | Feature grid/list     | grid, 3-4 cols |
+| testimonials | Customer testimonials | carousel       |
+| pricing      | Pricing plans         | grid, 3 cols   |
+| cta          | Call-to-action        | flex, 1 col    |
+| faq          | Frequently asked      | accordion      |
+| team         | Team members grid     | grid, 3-4 cols |
+| contact      | Contact form          | flex, 2 cols   |
+| gallery      | Image gallery         | masonry        |
+| stats        | Statistics/metrics    | grid, 4 cols   |
+
+### SectionTemplate (22 Fields = 14 Config + 8 Metadata)
+
+```typescript
+const heroTemplate: SectionTemplate = {
+  // SectionConfig (14 fields)
+  ...heroSection,
+
+  // TemplateMetadata (8 fields)
+  templateId: 'hero-material-001',
+  templateName: 'Material Hero',
+  description: 'Material Design 3 hero section with gradient',
+  author: 'nikkory-team',
+  version: '1.0.0',
+  tags: ['hero', 'material', 'enterprise', 'landing'],
+  visibility: 'public', // 'private' | 'team' | 'public'
+  thumbnail: 'https://cdn.nikkory.com/templates/hero-material.png',
+};
+```
+
+### SectionFactors (13 Factors)
+
+Factors that propagate from Section to Components:
+
+```typescript
+const factors: SectionFactors = {
+  // Visual Factors (6)
+  colorPrimary: '#2196f3',
+  colorText: '#1a1a1a',
+  colorBackground: '#ffffff',
+  typography: 'default', // 'compact' | 'default' | 'relaxed' | 'spacious'
+  borderRadius: 'md', // 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
+  elevation: 'sm', // 'none' | 'sm' | 'md' | 'lg' | 'xl'
+
+  // Layout Factors (4)
+  padding: 'lg',
+  gap: 'md',
+  alignment: 'center', // 'start' | 'center' | 'end' | 'stretch' | 'between'
+  maxWidth: 'xl', // 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
+
+  // Behavior Factors (3)
+  animation: 'smooth', // 'none' | 'subtle' | 'smooth' | 'dynamic' | 'playful'
+  responsive: { mobile: 'stack', tablet: 'grid', desktop: 'grid' },
+  a11yLevel: 'enhanced', // 'standard' | 'enhanced' | 'maximum'
+};
+```
+
+### Slot System
+
+Place components in section slots:
+
+```typescript
+const slotConfig: SlotConfig = {
+  slotId: 'hero-cta-slot',
+  position: 'content', // 'header' | 'content' | 'footer' | 'sidebar' | 'overlay'
+  allowedComponents: ['button', 'input', 'chip'],
+  maxComponents: 3,
+  defaultComponent: 'button',
+};
+
+const componentInSlot: StoredComponentInSlot = {
+  componentRef: 'button',
+  instanceId: 'hero-cta-button-1',
+  propOverrides: {
+    variant: 'filled',
+    size: 'lg',
+    label: 'Get Started',
+  },
+  order: 0,
+  visible: true,
+};
+```
+
+### Hybrid Storage (Visibility-Based)
+
+- `private`: JSON file only (local machine)
+- `team`: JSON + Cloud sync to team workspace
+- `public`: JSON + Cloud sync + Marketplace listing
+
+```typescript
+import type { LocalStorageConfig, CloudSyncConfig } from '@nikkory/vibe-engine';
+
+const localConfig: LocalStorageConfig = {
+  basePath: './.nikkory/templates',
+  fileExtension: '.section.json',
+  prettyPrint: true,
+  createBackups: true,
+};
+
+const cloudConfig: CloudSyncConfig = {
+  apiEndpoint: 'https://api.nikkory.com/templates',
+  syncInterval: 60000, // 1 minute
+  conflictResolution: 'newest-wins',
+  enableOfflineQueue: true,
+};
+```
+
+---
+
+## Unified Granularity Architecture
+
+**New in v4.0.0**: Generic type system for all 6 granularity levels with dynamic factor cascade.
+
+### GranularityConfig<G> - Generic Interface
+
+Replace duplicate Section/Page/Layout/Template patterns with ONE generic interface:
+
+```typescript
+import type {
+  GranularityLevel,
+  GranularityConfig,
+  GranularityTemplate,
+  GranularitySlotConfig,
+  GranularityFactorDefinition,
+} from '@nikkory/vibe-engine';
+
+// 6 Granularity Levels
+type GranularityLevel = 'atom' | 'component' | 'section' | 'page' | 'layout' | 'template';
+
+// Generic config for ANY granularity level
+const sectionConfig: GranularityConfig<'section'> = {
+  id: 'hero-section-1',
+  granularity: 'section',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  title: 'Hero Section',
+  layout: { type: 'flex', alignment: 'center' },
+  factors: { spacing: 'lg', colorPrimary: '#3B82F6' },
+};
+
+const pageConfig: GranularityConfig<'page'> = {
+  id: 'landing-page-1',
+  granularity: 'page',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  title: 'Landing Page',
+  children: [
+    { childGranularity: 'section', ref: 'hero-section-1', slot: 'main' },
+    { childGranularity: 'section', ref: 'features-section-1', slot: 'main' },
+  ],
+};
+```
+
+### Granularity Hierarchy
+
+Factors cascade DOWN from higher levels to lower levels:
+
+```
+template (Level 6) - Highest
+    ↓
+layout (Level 5)
+    ↓
+page (Level 4)
+    ↓
+section (Level 3)
+    ↓
+component (Level 2)
+    ↓
+atom (Level 1) - Lowest
+```
+
+```typescript
+import { GRANULARITY_HIERARCHY, getGranularityRank } from '@nikkory/vibe-engine';
+
+// Check hierarchy
+console.log(GRANULARITY_HIERARCHY);
+// ['template', 'layout', 'page', 'section', 'component', 'atom']
+
+// Compare levels
+console.log(getGranularityRank('template')); // 6
+console.log(getGranularityRank('page')); // 4
+console.log(getGranularityRank('atom')); // 1
+```
+
+### GranularityTemplate<G> - With Metadata
+
+Templates extend configs with 8 metadata fields for sharing and versioning:
+
+```typescript
+const heroTemplate: GranularityTemplate<'section'> = {
+  // Config fields
+  id: 'hero-instance-1',
+  granularity: 'section',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  title: 'Hero Section',
+
+  // 8 Metadata fields
+  templateId: 'hero-section-v1',
+  templateName: 'Hero Section Template',
+  description: 'Full-width hero with headline and CTA',
+  author: 'Nikkory Team',
+  version: '1.0.0',
+  tags: ['hero', 'landing', 'cta'],
+  visibility: 'public', // 'private' | 'team' | 'public'
+  thumbnail: 'https://nikkory.com/templates/hero.png',
+};
+```
+
+### Factor Cascade System
+
+Factors are defined with `level` and `cascadeDown` - no more hardcoded arrays:
+
+```typescript
+import type { GranularityFactorDefinition } from '@nikkory/vibe-engine';
+
+const spacingFactor: GranularityFactorDefinition = {
+  id: 'spacing',
+  name: 'Spacing',
+  category: 'layout',
+  level: 'template', // Minimum level where this factor applies
+  cascadeDown: true, // Cascade to page → section → component → atom
+  defaults: {
+    'material-design': 'md',
+    'ios-hig': 'sm',
+  },
+  options: ['xs', 'sm', 'md', 'lg', 'xl'],
+  description: 'Controls spacing between elements',
+};
+
+// Dynamic factor resolution (replaces hardcoded 8/13/24 arrays)
+// getFactorsForLevel('page') → Returns all factors for page level
+// getFactorsForLevel('section') → Returns all factors for section level
+```
+
+### Level-Specific Slot Positions
+
+Slots vary by granularity level:
+
+```typescript
+import type { GranularitySlotPosition } from '@nikkory/vibe-engine';
+
+// Page slots (6 positions)
+type PageSlots = GranularitySlotPosition<'page'>;
+// = 'header' | 'main' | 'sidebar' | 'footer' | 'overlay' | 'floating'
+
+// Section slots (5 positions)
+type SectionSlots = GranularitySlotPosition<'section'>;
+// = 'header' | 'content' | 'footer' | 'sidebar' | 'overlay'
+
+// Layout slots (4 positions)
+type LayoutSlots = GranularitySlotPosition<'layout'>;
+// = 'header' | 'main' | 'sidebar' | 'footer'
+
+// Template slots (3 positions)
+type TemplateSlots = GranularitySlotPosition<'template'>;
+// = 'pages' | 'shared' | 'assets'
+```
+
+### Level-Specific Type Aliases
+
+Convenience type aliases for each level:
+
+```typescript
+import type {
+  AtomConfig,
+  ComponentConfig,
+  SectionGranularityConfig,
+  PageConfig,
+  LayoutGranularityConfig,
+  TemplateConfig,
+  // Template types
+  AtomTemplate,
+  ComponentTemplate,
+  SectionGranularityTemplate,
+  PageTemplate,
+  LayoutTemplate,
+  TemplateGranularityTemplate,
+} from '@nikkory/vibe-engine';
+
+// These are aliases for GranularityConfig<Level>
+const atom: AtomConfig = { id: '1', granularity: 'atom', ... };
+const component: ComponentConfig = { id: '2', granularity: 'component', ... };
+const section: SectionGranularityConfig = { id: '3', granularity: 'section', ... };
+const page: PageConfig = { id: '4', granularity: 'page', ... };
+const layout: LayoutGranularityConfig = { id: '5', granularity: 'layout', ... };
+const template: TemplateConfig = { id: '6', granularity: 'template', ... };
+```
+
+### Factor Resolution Types
+
+```typescript
+import type {
+  GranularityFactorResolutionResult,
+  GranularityFactorOverride,
+  GranularityFactorQueryOptions,
+  GranularityFactorCascadeConfig,
+} from '@nikkory/vibe-engine';
+import { FACTOR_PRIORITY } from '@nikkory/vibe-engine';
+
+// Factor priority (higher wins)
+console.log(FACTOR_PRIORITY.DEFAULT); // 0
+console.log(FACTOR_PRIORITY.CASCADE); // 25
+console.log(FACTOR_PRIORITY.CONFIG); // 50
+console.log(FACTOR_PRIORITY.USER); // 100 (always wins)
+```
+
+---
+
+## Composition Generator
+
+**New in v4.0.0**: Generate higher-level compositions (pages from sections, layouts from pages, templates from pages).
+
+### Usage
+
+```typescript
+import { CompositionGenerator } from '@nikkory/vibe-engine';
+import type { CompositionConfig } from '@nikkory/vibe-engine';
+
+const generator = new CompositionGenerator();
+
+// Generate a landing page from sections
+const result = generator.generateComposition({
+  parent: LANDING_PAGE_DEFINITION,
+  children: [HERO_SECTION, FEATURES_SECTION, CTA_SECTION],
+  strategy: 'slots',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  outputDir: './src/pages',
+});
+
+console.log(result.componentPath); // './src/pages/MaterialDesignLandingPageEnterprise.tsx'
+console.log(result.linesOfCode); // 150-300 for enterprise tier
+console.log(result.displayName); // 'MaterialDesignLandingPageEnterprise'
+```
+
+### Composition Strategies
+
+**1. Slot Composition** - Pages compose sections via named slots:
+
+```typescript
+strategy: 'slots';
+// Parent: Page definition
+// Children: Section definitions
+// Result: Page component with section slots
+```
+
+**2. Children Composition** - Layouts compose pages via children prop:
+
+```typescript
+strategy: 'children';
+// Parent: Layout definition
+// Children: Page definitions
+// Result: Layout component with page children
+```
+
+**3. Template Composition** - Templates compose multiple pages:
+
+```typescript
+strategy: 'template';
+// Parent: Template definition
+// Children: Page definitions
+// Result: Template with all pages
+```
+
+### Generation Result
+
+```typescript
+interface GenerationResult {
+  success: boolean;
+  componentPath: string; // Generated file path
+  linesOfCode: number; // Total LOC (varies by tier)
+  displayName: string; // Component display name
+  error?: string; // Error message if failed
+}
+```
+
+### Tier Features
+
+The generator respects tier-specific features:
+
+| Tier           | LOC     | Features                             |
+| -------------- | ------- | ------------------------------------ |
+| **Basic**      | 30-50   | Core composition, basic imports      |
+| **Standard**   | 50-150  | + forwardRef, displayName, variants  |
+| **Enterprise** | 150-300 | + memo, useCallback, analytics, ARIA |
+
+---
+
+## Matrix Multiplication Code Generation
+
+**New in v4.0.0**: Dynamic code generation using matrix multiplication algorithm.
+
+### Overview
+
+The Matrix Multiplication System replaces hardcoded component generation with a dynamic algorithm that multiplies 4 matrices to produce component configurations:
+
+```
+Component = Matrix1 × Matrix2 × Matrix3 × Matrix4 + Override
+```
+
+### The 4 Matrices
+
+| Matrix       | Input                     | Output             | Source                                 |
+| ------------ | ------------------------- | ------------------ | -------------------------------------- |
+| **Matrix 1** | Component ID              | HTML Element Type  | COMPONENT_REGISTRY                     |
+| **Matrix 2** | Factor ID + Design System | Factor Values      | FACTOR_REGISTRY + user overrides       |
+| **Matrix 3** | Tier                      | React Patterns     | Tier definitions                       |
+| **Matrix 4** | Component × Factor        | Applicable Factors | COMPONENT_REGISTRY.factorApplicability |
+
+### Usage
+
+```typescript
+import { MatrixResolver, TemplateEngine } from '@nikkory/vibe-engine/matrix';
+
+// Initialize resolver
+const resolver = new MatrixResolver();
+const templateEngine = new TemplateEngine();
+
+// Resolve component configuration
+const config = resolver.resolve({
+  componentId: 'button',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  factor24Config: {
+    4: 'md', // borderRadius = md (rounded corners)
+    5: 'md', // shadowStyle = md (elevation)
+    17: 'md', // spacing = md
+  },
+});
+
+// Generate React component code
+const code = templateEngine.generate(config);
+console.log(config.classNames);
+// → ['rounded-md', 'shadow-md', 'px-4 py-2']
+```
+
+### ResolvedComponentConfig
+
+The `resolve()` method returns a complete configuration:
+
+```typescript
+interface ResolvedComponentConfig {
+  componentName: string; // 'ButtonMaterialDesignEnterprise'
+  elementType: string; // 'button' (from COMPONENT_REGISTRY)
+  tier: Tier; // 'enterprise'
+  designSystem: DesignSystem; // 'material-design'
+  classNames: readonly string[]; // ['rounded-md', 'shadow-md', ...]
+  imports: readonly string[]; // React imports for tier
+  wrappers: readonly string[]; // ['memo', 'forwardRef']
+  features: readonly string[]; // ['displayName', 'analytics']
+}
+```
+
+### Matrix 2: Factor Override System
+
+User overrides take precedence over design system defaults:
+
+```typescript
+const config = resolver.resolve({
+  componentId: 'button',
+  designSystem: 'material-design', // Default: borderRadius = 'md'
+  tier: 'enterprise',
+  factor24Config: {
+    4: 'xl', // Override: borderRadius = 'xl' (more rounded)
+  },
+});
+
+console.log(config.classNames);
+// → ['rounded-xl', 'shadow-md', 'px-4 py-2']
+//    ^^^^^^^^^^^ User override applied!
+```
+
+### Design System Differentiation
+
+Different design systems produce different code:
+
+```typescript
+// Material Design: Rounded corners + shadows
+const material = resolver.resolve({
+  componentId: 'button',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  factor24Config: { 4: 'md', 5: 'md', 17: 'md' },
+});
+console.log(material.classNames);
+// → ['rounded-md', 'shadow-md', 'px-4 py-2']
+
+// Brutalism: Sharp corners + no shadows
+const brutalism = resolver.resolve({
+  componentId: 'button',
+  designSystem: 'brutalism',
+  tier: 'enterprise',
+  factor24Config: { 4: 'none', 5: 'none', 17: 'md' },
+});
+console.log(brutalism.classNames);
+// → ['rounded-none', 'shadow-none', 'px-4 py-2']
+```
+
+### Tier Patterns (Matrix 3)
+
+Each tier generates different React patterns:
+
+| Tier           | Imports                                      | Wrappers             | Features                   | LOC     |
+| -------------- | -------------------------------------------- | -------------------- | -------------------------- | ------- |
+| **Basic**      | `React`                                      | `React.FC`           | None                       | 30-50   |
+| **Standard**   | `React`, `forwardRef`                        | `forwardRef`         | `displayName`              | 50-150  |
+| **Enterprise** | `React`, `forwardRef`, `memo`, `useCallback` | `memo`, `forwardRef` | `displayName`, `analytics` | 150-300 |
+
+### Generated Code Example
+
+**Enterprise Tier with Material Design:**
+
+```typescript
+/**
+ * ButtonMaterialDesignEnterprise Component
+ *
+ * Generated by Nikkory Vibe Matrix Generator
+ * Powered by Nikkory
+ */
+
+import * as React from 'react';
+import { forwardRef, memo, useCallback } from 'react';
+
+export const ButtonMaterialDesignEnterprise = memo(
+  forwardRef<HTMLButtonElement, ButtonMaterialDesignEnterpriseProps>(
+    ({ children, className, ...props }, ref) => {
+      return (
+        <button
+          ref={ref}
+          className={`rounded-md shadow-md px-4 py-2 ${className ?? ''}`}
+          {...props}
+        >
+          {children}
+        </button>
+      );
+    }
+  )
+);
+
+ButtonMaterialDesignEnterprise.displayName = 'ButtonMaterialDesignEnterprise';
+```
+
+### ComponentGenerator Integration
+
+**As of v4.0.0**, the `ComponentGenerator` class internally uses the Matrix Multiplication system for all code generation:
+
+```typescript
+import { ComponentGenerator } from '@nikkory/vibe-engine';
+
+const generator = new ComponentGenerator();
+
+// ComponentGenerator now uses MatrixResolver + TemplateEngine internally
+const result = generator.generate({
+  componentType: 'button',
+  designSystem: 'material-design',
+  tier: 'enterprise',
+  factorOverrides: { 2: 'lg' }, // Size override
+});
+
+console.log(result.code.componentCode); // Clean, performant code (39-44 LOC)
+console.log(result.style.tailwindClasses); // Resolved classes
+```
+
+**Benefits**:
+
+- ✅ **Performance**: 0.05ms average generation time (100x faster than target)
+- ✅ **Memory**: 1.47MB usage (3x under target)
+- ✅ **Output Quality**: 39-44 lines (under 100-line target)
+- ✅ **Backward Compatible**: Public API unchanged
+
+### Testing
+
+Test the matrix system with the included test script:
+
+```bash
+# Run matrix tests
+npx tsx packages/engine/src/matrix/test-matrix.ts
+```
+
+**Test Output:**
+
+```
+✅ Material Design Button Test Complete
+  Component Name: ButtonMaterialDesignEnterprise
+  Class Names: rounded-md, px-4 py-2
+
+✅ Brutalism Button Test Complete
+  Component Name: ButtonBrutalismEnterprise
+  Class Names: rounded-none, px-4 py-2
+
+🎯 Result: ✅ DIFFERENT (PASS)
+✅ Design systems generate DIFFERENT code (Target State met!)
+```
+
+---
+
+## Advanced Usage
+
+### Validators
+
+```typescript
+import {
+  isValidColorScheme,
+  isValidSize,
+  isValidAnimation,
+  validateFactor24Completeness,
+} from '@nikkory/vibe-engine';
+
+// Validate individual factors
+if (isValidColorScheme('primary')) {
+  console.log('Valid color');
+}
+
+// Validate complete configuration
+const result = validateFactor24Completeness(config);
+if (!result.isComplete) {
+  console.log('Missing factors:', result.missing);
+}
+```
+
+### Result/Option Types
+
+```typescript
+import { Result, Option } from '@nikkory/vibe-engine';
+
+// Result type for error handling
+function generateCode(): Result<string, Error> {
+  try {
+    const code = '...';
+    return Result.ok(code);
+  } catch (error) {
+    return Result.fail(new Error('Generation failed'));
+  }
+}
+
+const result = generateCode();
+if (result.isSuccess()) {
+  console.log(result.getValue());
+} else {
+  console.error(result.getError());
+}
+
+// Option type for nullable values
+const maybeComponent = Option.fromNullable(getComponent('button'));
+if (maybeComponent.isSome()) {
+  console.log(maybeComponent.unwrap().name);
+}
+```
+
+---
+
+## Package Structure
+
+```
+@nikkory/vibe-engine/
+├── dist/
+│   ├── index.js         # CommonJS
+│   ├── index.mjs        # ES Module
+│   ├── index.d.ts       # TypeScript types
+│   ├── browser.js       # Browser build
+│   └── browser.mjs
+├── src/
+│   ├── generator/       # Style generation
+│   ├── presets/         # Component registry
+│   ├── constants/       # Design systems, tiers
+│   ├── types/           # TypeScript definitions
+│   └── utils/           # Utility functions
+└── package.json
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with strict mode enabled:
+
+```typescript
+import type {
+  // Core types
+  DesignSystem,
+  Tier,
+  ComponentType,
+  Framework,
+
+  // Configuration types
+  Factor24Config,
+  StyleConfig,
+  GenerationConfig,
+
+  // Registry types
+  RegistryComponentDefinition,
+  ComponentCategory,
+  ComponentStatus,
+
+  // Utility types
+  Result,
+  Option,
+} from '@nikkory/vibe-engine';
+```
+
+---
+
+## Browser Support
+
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- Node.js: ≥18.0.0
+
+---
+
+## Related Packages
+
+- **[@nikkory/vibe-react](https://npmjs.com/package/@nikkory/vibe-react)** - React component library
+- **[@nikkory/vibe-patterns](https://npmjs.com/package/@nikkory/vibe-patterns)** - 634 pre-built patterns
+- **[@nikkory/vibe-types](https://npmjs.com/package/@nikkory/vibe-types)** - Shared TypeScript types
+
+---
+
+## Migration from v3.x
+
+See [Migration Guide](../../docs/MIGRATION-v3-to-v4.md) for detailed instructions.
+
+**Quick migration**:
+
+```bash
+# Replace old package
+npm uninstall @nikkory/vibe-core @nikkory/vibe-shared
+npm install @nikkory/vibe-engine
+
+# Update imports
+# Old: import { ... } from '@nikkory/vibe-core'
+# New: import { ... } from '@nikkory/vibe-engine'
+```
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT © Nikkory
+
+---
+
+## Support
+
+- **Documentation**: https://docs.nikkory.com
+- **GitHub Issues**: https://github.com/kemonra/nikkory-vibe/issues
+- **Discord**: https://discord.gg/nikkory
+- **Email**: dev@nikkory.com
+
+---
+
+**Powered by Nikkory**
+*https://nikkory.com*