🎨 Visual Editor vs Programmatic Access

Critical Understanding: The visual canvas editor shows a curated subset of modules for clarity. The actual system has NO restrictions!

🎯 THE KEY PRINCIPLE

"Visual editor constraints are UI choices, not system limitations!"

What This Means:

• The visual canvas filters module types for clarity and usability
• The system itself allows any module type anywhere
• Other tools (vibe coding, API, Singularity) have full access

🏗️ VISUAL EDITOR FILTERS

Universe Level Canvas - Shows:

✅ Layout   - Defines grid structure
✅ Galaxy   - Route collections
✅ World    - Page containers

Universe Level Canvas - HIDES (but still accessible):

👁️ Navigation  - Hidden from visual canvas
👁️ Feature     - Hidden from visual canvas
👁️ Widget      - Hidden from visual canvas
👁️ Data Provider - Hidden from visual canvas
👁️ Flow        - Hidden from visual canvas
👁️ Page        - Hidden from visual canvas
👁️ Custom      - Hidden from visual canvas

Why? Visual clarity! At universe level, you're designing structure, not adding individual widgets/features.

🔓 FULL ACCESS VIA OTHER TOOLS

1. Vibe Coding / Prompts

// User types:
"Add a shopping cart feature at universe level"

// System creates:
{
  type: 'feature',
  name: 'Shopping Cart',
  parentId: null, // Top-level!
  universeId: 'universe_123'
}

// Visual editor: Doesn't show it (by design)
// But it EXISTS in the database!
// Accessible via API, Singularity, other views

2. API / Programmatic

// Direct API call:
POST /api/modules/install
{
  "universeId": "universe_123",
  "type": "widget",
  "name": "Custom Header",
  "parentId": null // Top-level widget!
}

// Result: Created successfully!
// Visual canvas: Won't display (structural view only)
// Tree view / list view: Shows it!

3. Singularity (Logic Builder)

Navigate to module in Singularity
→ Create nested logic
→ Add any module type
→ No restrictions!

🌌 EXAMPLE: The Same Universe, Different Views

Visual Canvas View (Structural):

Universe
├─ 📦 Layout: Main
├─ 🌌 Galaxy: App
└─ 🌍 World: Dashboard

(Only showing structural modules)

Tree/List View (Complete):

Universe
├─ 📦 Layout: Main
├─ 🌌 Galaxy: App
├─ 🌍 World: Dashboard
├─ 🧭 Navigation: TopNav        ← Hidden in canvas
├─ 🎯 Feature: Shopping Cart    ← Hidden in canvas
├─ 🧩 Widget: Custom Header     ← Hidden in canvas
└─ 📊 Data: Products API        ← Hidden in canvas

(Showing ALL modules)

Vibe Coding View (Natural Language):

"My universe has:"
- Main layout with 3 zones
- App galaxy for main routes
- Dashboard world with analytics
- TopNav navigation (always visible)
- Shopping cart feature (global)
- Custom header widget (branded)
- Products API for data

(All modules described, regardless of visual editor)

🎨 WHY VISUAL FILTERING?

Without Filtering (Overwhelming):

Universe Canvas:
[100+ modules scattered everywhere]
- Widgets mixed with Galaxies
- Features floating next to Layouts
- Data Providers everywhere
- Complete chaos!

With Smart Filtering (Clear):

Universe Canvas:
[3-5 structural modules]
- Main Layout (defines structure)
- App Galaxy (main routes)
- Admin Galaxy (admin routes)

(Everything else is nested inside or accessed via other tools)

🔄 HOW IT WORKS TECHNICALLY

Visual Editor Component:

// libs/universe-map/.../universal-canvas.component.ts

if (level === 'universe') {
  // VISUAL EDITOR FILTER
  const VISUAL_EDITOR_UNIVERSE_TYPES = ['layout', 'galaxy', 'world'];
  
  filtered = allModules.filter(m => {
    const hasNoParent = !m.parentId;
    const isVisuallyRelevant = VISUAL_EDITOR_UNIVERSE_TYPES.includes(m.type);
    
    if (hasNoParent && !isVisuallyRelevant) {
      console.log('👁️ Module hidden in visual editor (still exists!)');
    }
    
    return hasNoParent && isVisuallyRelevant;
  });
}

Key Points:

• ✅ Query fetches ALL modules from database
• ✅ Filter is applied IN THE COMPONENT (visual layer only)
• ✅ Other tools query the same database without filters
• ✅ Modules exist regardless of visual display

🏗️ NESTED LEVELS: NO FILTERS

Inside Galaxy/World:

if (level === 'galaxy' || level === 'world') {
  // NO TYPE FILTERING!
  filtered = allModules.filter(m => m.parentId === parentId);
  
  // Shows ALL nested modules:
  // - Pages, Widgets, Features, Navigation, etc.
  // - Complete flexibility!
}

Why? Once you're inside a Galaxy/World, you're editing content, not structure. Show everything!

💡 PRACTICAL SCENARIOS

Scenario 1: Building with Visual Editor

User: *Drags Layout, Galaxy, World onto canvas*
Result: Clean structural view
Hidden: Any top-level widgets/features (created via vibe coding)
Access: Navigate to List View to see all modules

Scenario 2: Vibe Coding

User: "Add a global notification system"
System: Creates 'feature' module at universe level
Visual Canvas: Doesn't show it (by design)
List View: Shows it
API: Returns it
Singularity: Can edit it

Scenario 3: Mixed Workflow

1. Visual Editor: Create Galaxy structure
2. Vibe Coding: Add features/widgets
3. Singularity: Wire up logic
4. Visual Editor: See structural changes only
5. List View: See complete picture

🎯 MODULE TYPE VISIBILITY MATRIX

* Hidden = Not displayed in visual canvas, but still exists and accessible via other tools!

✅ DESIGN PHILOSOPHY

Visual Editor Purpose:

• Spatial thinking - See structure visually
• Clarity - Focus on architecture
• Drag-drop - Intuitive layout design
• Grid-based - When using Layout modules

Vibe Coding Purpose:

• Natural language - Describe what you want
• No constraints - Create anything anywhere
• Fast - Type instead of drag
• Flexible - Mix structural and functional

API Purpose:

• Programmatic - Full control
• Automation - Batch operations
• Integration - Connect external systems
• No limits - Absolute freedom

Singularity Purpose:

• Logic - Wire up behaviors
• Deep editing - Module internals
• Flows - Complex interactions
• Visual programming - Node-based

🚀 FUTURE: CONTEXT-AWARE FILTERING

Coming Soon:

// Smart filtering based on context
if (isVisualStructureView) {
  // Show structural modules
  filter = ['layout', 'galaxy', 'world'];
} else if (isContentView) {
  // Show content modules
  filter = ['page', 'widget', 'feature'];
} else if (isLogicView) {
  // Show logic modules
  filter = ['flow', 'data', 'custom'];
} else {
  // Show everything
  filter = null; // No filter
}

✅ SUMMARY

Key Takeaways:

1. Visual editor filters = UI choice, not system limitation
2. All modules exist in the database, always accessible
3. Other tools have full access (vibe coding, API, Singularity)
4. Nested levels show everything (inside Galaxy/World = no filters)
5. Multiple views for different needs (structure vs content vs logic)

Remember:

The visual canvas is ONE WAY to interact with your universe, not the ONLY way!

Created: November 10, 2025 9:00 PM
Status: 📖 CRITICAL CONCEPT
Impact: Prevents confusion about system capabilities