Widget Variant System - Module Integration Strategy

🎯 Ultimate Vision Alignment

Goal: Build the most advanced, groundbreaking, intelligent, robust platform builder in the universe.

Core Principle: Everything must be a reusable module that can be discovered, composed, and AI-generated.

🧩 Module System Integration

Current Module Philosophy (from AGENTS.md)

Every feature is a self-contained, reusable module that:

• 📦 Self-registers via manifests
• 🔄 Communicates through ActionRegistry and EventBus
• 💾 Stores data using storage-system with flash-persistence
• 🎯 Exposes capabilities through standardized interfaces
• 🤖 AI-trainable for intelligent code generation

How Variants Fit Into This

Variants ARE Modules! Each variant should:

interface VariantAsModule {
  // Module Identity
  manifest: ModuleManifest;
  
  // Variant-Specific Data
  variantData: WidgetVariant;
  
  // Module Capabilities
  actions: {
    'apply-to-widget': (widgetId: string) => Promise<void>;
    'get-preview': () => Promise<string>;
    'duplicate': () => Promise<WidgetVariant>;
    'export': () => Promise<WidgetModuleDefinition>;
  };
  
  // Module Events
  events: {
    'variant-applied': { widgetId: string; variantId: string };
    'variant-updated': { variantId: string };
    'variant-promoted-to-module': { moduleId: string };
  };
}

🏗️ Architecture Integration

Layer 1: Storage (✅ Complete)

• Three-tier scoping (global/universe/space)
• Flash persistence
• CRUD operations

Layer 2: Module Registry Integration (🔄 Next)

• Register variants as discoverable modules
• Expose variant actions through ActionRegistry
• Emit events through EventBus

Layer 3: Widget Builder Integration (🔄 Next)

• Variant picker component
• Live preview with variant application
• "Promote to Module" functionality

Layer 4: AI Discovery (🔮 Future)

• Variants discoverable by AI through manifests
• Natural language variant generation
• Automatic variant suggestions

🎨 Variant → Module → Platform Flow

The Complete Lifecycle

1. Space Builder Creates Variant
   ↓
2. Variant Stored (universe/space scope)
   ↓
3. Variant Registered as Module
   ↓
4. Module Exposes Actions (apply, duplicate, export)
   ↓
5. AI Discovers Variant via Manifest
   ↓
6. Space Builder Uses Variant Everywhere
   ↓
7. Variant Promoted to Full Widget Module
   ↓
8. Module Published to Platform Marketplace
   ↓
9. Other Builders Discover & Use

Key Integration Points

A. Variant Storage Service ↔ Module Registry

// When variant is created
await variantStorage.createVariant(params, userId);
// Also register as module
await moduleRegistry.registerModule({
  id: `variant-${variantId}`,
  type: 'widget-variant',
  manifest: generateVariantManifest(variant),
  actions: variantActions
});

B. Widget Builder ↔ Action Registry

// Expose variant actions
actionRegistry.registerAction('widget-variant', 'apply', async (params) => {
  const variant = await variantStorage.getVariant(params);
  await applyVariantToWidget(params.widgetId, variant);
  eventBus.emit('variant-applied', { widgetId, variantId });
});

C. AI System ↔ Module Manifests

// AI discovers variants
const variants = await moduleRegistry.findModules({
  type: 'widget-variant',
  tags: ['button', 'primary']
});

// AI generates new variants
const newVariant = await aiService.generateVariant({
  baseWidget: 'button',
  prompt: 'Create a glowing neon button for dark theme',
  references: existingVariants
});

🔄 Revised Implementation Phases

Phase 1: Storage Foundation (✅ COMPLETE)

• Variant types and interfaces
• Storage service with three-tier scoping
• 31 global variants across 5 widget types
• CRUD operations

Phase 2: Module Integration (🎯 PRIORITY)

Goal: Make variants discoverable as modules

2.1 Variant Module Wrapper

// File: libs/libs-widgets/widgets-manager/src/lib/modules/variant-module-wrapper.ts
class VariantModuleWrapper implements BrowserModuleContract {
  constructor(private variant: WidgetVariant) {}
  
  get manifest(): ModuleManifest {
    return {
      id: `variant-${this.variant.id}`,
      name: this.variant.name,
      description: this.variant.description,
      category: 'widget-variant',
      tags: [...(this.variant.tags || []), this.variant.baseWidget],
      publicActions: {
        apply: { /* ... */ },
        preview: { /* ... */ },
        duplicate: { /* ... */ }
      }
    };
  }
  
  // Implement BrowserModuleContract methods
  async initialize() { /* ... */ }
  async start() { /* ... */ }
  // ...
}

2.2 Module Registry Integration

// Auto-register variants when loaded
class VariantModuleIntegrationService {
  async registerVariantsAsModules(universeId: string, spaceId?: string) {
    const variants = await variantStorage.getAllVariants({
      widgetType: 'all',
      universeId,
      spaceId
    });
    
    for (const variant of variants) {
      const wrapper = new VariantModuleWrapper(variant);
      await moduleRegistry.registerModule(wrapper);
    }
  }
}

2.3 Action Registry Integration

// Expose variant actions
class VariantActionProvider {
  registerActions() {
    // Apply variant to widget
    actionRegistry.register('variant', 'apply', async (params) => {
      const { variantId, widgetId } = params;
      const variant = await variantStorage.getVariant(variantId);
      await this.applyVariantToWidget(widgetId, variant);
      eventBus.emit('variant:applied', { variantId, widgetId });
    });
    
    // Get variant preview
    actionRegistry.register('variant', 'preview', async (params) => {
      const { variantId } = params;
      const variant = await variantStorage.getVariant(variantId);
      return this.generatePreview(variant);
    });
    
    // Duplicate variant
    actionRegistry.register('variant', 'duplicate', async (params) => {
      const { variantId } = params;
      return await variantStorage.duplicateVariant(variantId);
    });
    
    // Promote to module
    actionRegistry.register('variant', 'promote-to-module', async (params) => {
      const { variantId } = params;
      return await this.promoteVariantToModule(variantId);
    });
  }
}

Phase 3: Variant Creator UI (🔄 Next)

Goal: Visual interface for creating variants

3.1 Variant Creator Modal

• Property configuration panel
• Style editor (CSS variables)
• Live preview
• Scope selector (universe/space)
• NEW: "Expose as Module Action" toggle
• NEW: Module manifest preview

3.2 Integration with Module System

• When variant created → auto-register as module
• Show module ID and available actions
• Allow editing module manifest

Phase 4: Widget Builder Integration (🔄 Next)

Goal: Use variants seamlessly in widget builder

4.1 Variant Picker Component

• Browse global + user variants
• Filter by tags, category
• Live preview on hover
• Click to apply

4.2 Module Action Integration

• Right-click variant → "Apply to Widget" (uses ActionRegistry)
• Drag variant from palette (uses module system)
• AI suggestions (queries module manifests)

Phase 5: Core Component Detail Page (🔄 Next)

Goal: Comprehensive variant management

5.1 Variant Management UI

• List global variants (read-only)
• List user variants (editable)
• Create new variant button
• Variant actions: edit, duplicate, delete, favorite, promote to module

5.2 Module Integration

• Show module status for each variant
• Display available actions
• Show usage analytics (via events)

Phase 6: Widget Gallery Playground (🔄 Next)

Goal: Interactive variant testing and creation

6.1 Live Playground

• Property editor
• Style customization
• Real-time preview
• "Save as Variant" → auto-registers as module

6.2 Module Discovery

• AI-powered variant suggestions
• Similar variant recommendations
• Usage statistics from events

🤖 AI Integration Strategy

Variant Discovery

// AI can discover variants through module manifests
const aiPrompt = "Find me all primary button variants for dark theme";

const variants = await moduleRegistry.findModules({
  type: 'widget-variant',
  tags: ['button', 'primary', 'dark-theme']
});

Variant Generation

// AI can generate new variants
const newVariant = await aiService.generateVariant({
  baseWidget: 'button',
  prompt: 'Create a glassmorphism button with subtle glow',
  style: 'modern',
  theme: 'dark'
});

// Auto-register generated variant as module
await variantStorage.createVariant(newVariant, 'ai-generated');
await moduleRegistry.registerModule(new VariantModuleWrapper(newVariant));

Variant Composition

// AI can compose multiple variants
const composedWidget = await aiService.composeWidget({
  variants: [
    'variant-button-primary',
    'variant-input-email',
    'variant-card-elevated'
  ],
  layout: 'vertical',
  prompt: 'Create a login form with these variants'
});

🎯 Success Metrics

Reusability

• ✅ Variants are modules (can be discovered)
• ✅ Variants expose actions (can be used programmatically)
• ✅ Variants emit events (can be tracked)
• ✅ Variants can be promoted to full modules

Discoverability

• ✅ AI can find variants via manifests
• ✅ Space builders can search variants
• ✅ Similar variants recommended
• ✅ Usage statistics available

Composability

• ✅ Variants can be combined
• ✅ Variants can be nested
• ✅ Variants can be themed
• ✅ Variants can be AI-generated

📊 Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                   SPACE BUILDER                             │
│  (Creates variants, uses AI, builds platforms)              │
└─────────────────┬───────────────────────────────────────────┘
                  │
    ┌─────────────▼─────────────┐
    │   VARIANT CREATOR UI      │
    │  - Property editor        │
    │  - Style customization    │
    │  - Live preview          │
    │  - Module toggle         │
    └─────────────┬─────────────┘
                  │
    ┌─────────────▼──────────────┐
    │  VARIANT STORAGE SERVICE   │
    │  - CRUD operations         │
    │  - Three-tier scoping      │
    │  - Flash persistence       │
    └─────────────┬──────────────┘
                  │
    ┌─────────────▼──────────────┐
    │  VARIANT MODULE WRAPPER    │
    │  - Implements module API   │
    │  - Exposes actions         │
    │  - Emits events           │
    └─────────────┬──────────────┘
                  │
    ┌─────────────▼──────────────┐
    │    MODULE REGISTRY         │
    │  - Discovers variants      │
    │  - Provides to AI          │
    │  - Enables composition     │
    └─────────────┬──────────────┘
                  │
    ┌─────────────▼──────────────┐
    │    ACTION REGISTRY         │
    │  - Apply variant           │
    │  - Duplicate variant       │
    │  - Promote to module       │
    └─────────────┬──────────────┘
                  │
    ┌─────────────▼──────────────┐
    │      EVENT BUS             │
    │  - variant-applied         │
    │  - variant-updated         │
    │  - variant-promoted        │
    └────────────────────────────┘

🚀 Next Steps (Prioritized)

Immediate (This Session)

1. ✅ Phase 1 & 2 complete (storage + global variants)
2. 🎯 Create VariantModuleWrapper (integrate with module system)
3. 🎯 Create VariantActionProvider (expose actions)
4. 🎯 Update variant storage (auto-register as modules)

Short Term (Next Session)

1. Build Variant Creator UI
2. Integrate with Widget Builder
3. Add Core Component Detail page enhancements

Medium Term

1. Widget Gallery playground
2. AI variant generation
3. Variant composition system

Long Term

1. Marketplace for variants
2. Variant analytics dashboard
3. Community variant sharing

💡 Key Insights

1. Variants = Modules: Every variant should be a discoverable module
2. Actions over UI: Expose capabilities through ActionRegistry first
3. Events for Analytics: Track usage via EventBus
4. AI-First: Design for AI discoverability from the start
5. Progressive Enhancement: Start simple, add intelligence gradually

Status: Strategic alignment complete. Ready to implement module integration. Next: Create VariantModuleWrapper and VariantActionProvider