🏗️ How to Build Your Universe

Your Question: "How can I add another galaxy into the universe? Or a world? Or modify the structure/grid?"

Answer: Here's the complete, tested workflow!

🎯 QUICK START: Adding Modules

Step 1: Open Universe Map

Navigate to: /space/{your-space}/universe-map
Tab: Structure (should be active)

You'll see:

• Left Panel: Module Library (list of module types)
• Center Canvas: Your universe (where modules appear)
• Right Panel: Properties (when you select a module)

Step 2: Add a Galaxy

Method 1: Drag & Drop (Recommended)

1. Find "Galaxy" in the left panel under "Structural Modules"
2. Click and hold on the Galaxy card
3. Drag onto the canvas (purple background)
4. Release to drop

What Happens:

🚀 Drag started from library: galaxy
📦 Setting drag data: {type: 'module-type', moduleType: 'galaxy'}
📦 Drag over canvas: {types: ['application/json', 'text/plain'], ...}
🎯 Canvas Drop Event: ...
📍 Creating module at position: {canvasX: 450, canvasY: 300}
✅ Module created: {id: 'mod_...', name: 'galaxy-...', type: 'galaxy'}

Result: New Galaxy card appears on canvas! 🌌

Method 2: Click to Create (Alternative)

1. Click the Galaxy card in library
2. Click the "+ Create" button
3. Module appears at default position (50, 50)

Step 3: Add a World

Same process as Galaxy:

1. Drag "World" from library
2. Drop on canvas
3. World appears! 🌍

Step 4: Add ANY Module Type

All 10 types work the same way:

Structural Modules:

• 🌌 Galaxy - Drag & drop
• 🌍 World - Drag & drop
• 📄 Page - Drag & drop
• 📦 Layout - Drag & drop ✅ NOW WORKS!

Functional Modules:

• 🧭 Navigation - Drag & drop
• 🎯 Feature - Drag & drop
• 🧩 Widget - Drag & drop ✅ NOW WORKS!
• 📊 Data Provider - Drag & drop ✅ NOW WORKS!
• 🔄 Flow - Drag & drop ✅ NOW WORKS!
• ⚙️ Custom - Drag & drop ✅ NOW WORKS!

🔄 NESTING: Creating Structure

Goal: Put a World inside a Galaxy

Current Status:

Right now, modules are created at top-level. To nest them:

Planned (Coming Soon):

1. Drag a World onto a Galaxy card
2. Drop on top of the Galaxy
3. World becomes child of Galaxy

Current Workaround:

1. Create modules on canvas
2. Select a module
3. In properties panel, manually set parentId

🎨 POSITIONING MODULES

Move Mode (Lock/Unlock)

Default: Locked 🔒

• Modules stay in place
• Click modules to select (no movement)
• Canvas panning always works

Unlocked: Move Mode ↔️

1. Click the lock icon in canvas controls (top-right)
2. Icon changes to arrows (blue)
3. Now you can drag modules to reposition
4. Click arrows again to lock

📍 CANVAS CONTROLS

Pan the Canvas:

• Hold Space + drag
• Middle mouse button + drag
• Click empty canvas + drag

Zoom:

• Scroll wheel to zoom in/out
• Ctrl + Plus to zoom in
• Ctrl + Minus to zoom out
• Ctrl + 0 to reset zoom

Fit to View:

• Shift + 1 (coming soon)

Snap to Grid:

• Press G to toggle
• Modules align to 50px grid when dragging

🎯 WORKING WITH MODULES

Select a Module:

• Single click on module card
• Properties panel opens on right

Multi-Select:

• Shift + Click to add to selection
• Ctrl/Cmd + Click to toggle selection

Edit Properties:

1. Select module
2. Properties panel shows:
   • Name - Click to edit
   • Route - Click to edit
   • Type - Shows module type
   • Quick Actions:
     • Zoom Into (for Galaxy/World)
     • Add Logic (opens Singularity)
     • Delete

Delete Modules:

• Select + Press Delete or Backspace
• Or click Delete in properties panel

🏗️ COMPLETE WORKFLOW EXAMPLE

Building an E-Commerce Universe:

Step 1: Create Top-Level Structure

1. Drag "Galaxy" → Drop on canvas → Name: "Main App"
2. Drag "Galaxy" → Drop on canvas → Name: "Admin Panel"
3. Drag "Navigation" → Drop on canvas → Name: "TopNav"
4. Drag "Navigation" → Drop on canvas → Name: "Footer"
5. Drag "Layout" → Drop on canvas → Name: "Store Layout" ✅

Step 2: Add Functionality

6. Drag "Feature" → Drop on canvas → Name: "Shopping Cart"
7. Drag "Feature" → Drop on canvas → Name: "Checkout"
8. Drag "Data Provider" → Drop on canvas → Name: "Products API" ✅
9. Drag "Widget" → Drop on canvas → Name: "Product Card" ✅

Step 3: Position Them

10. Click lock icon → Enable move mode
11. Drag "Main App" galaxy to center
12. Drag "Admin Panel" galaxy to right
13. Drag other modules around it
14. Click arrows → Lock in place

Step 4: Edit Properties

15. Click "Main App" galaxy
16. Edit name in properties panel
17. Edit route: "/app"
18. Click other modules to edit

🐛 TROUBLESHOOTING

Module Doesn't Appear After Drop

Check Console (F12):

// Should see:
🎯 Canvas Drop Event: ...
📍 Creating module at position: {canvasX: X, canvasY: Y}
✅ Module created: {id: 'mod_...', ...}

If you see errors:

• ❌ No universe ID → Reload page
• ❌ Module creation failed → Check network tab
• ❌ No drop event → Try again, ensure dragging from library

Module Appears But Isn't Visible

Possible Causes:

1. Positioned off-screen → Pan canvas to find it
2. Behind other elements → Z-index issue (refresh)
3. Filtered out → Check console for filter logs

Solution:

• Press Ctrl + 0 to reset view
• Look for module in top-left area (default position)
• Check properties panel to see if it's selected

Can't Move Modules

Check: Is move mode enabled?

• Look for lock icon 🔒 in canvas controls
• If locked → Click to enable move mode ↔️
• If unlocked but still can't move → Refresh page

Drag-Drop Not Working

Check Browser Console:

// Should see when dragging:
🚀 Drag started from library: galaxy
📦 Setting drag data: ...
📦 Drag over canvas: ...

// Should see when dropping:
🎯 Canvas Drop Event: ...

If missing:

• No drag start → Library not responding (refresh)
• No drag over → Canvas not receiving events (z-index issue)
• No drop → Drop handler not working (report bug)

✅ CURRENT CAPABILITIES

🎯 NEXT STEPS

Immediate (This Week):

1. Test the workflow - Try creating a Galaxy, World, Layout
2. Report issues - If drag-drop doesn't work, check console
3. Position modules - Use move mode to arrange your universe

Coming Soon:

1. Module-on-Module nesting - Drag World onto Galaxy
2. Visual layout zones - See grid structure for layouts
3. Template system - Pre-built module combinations
4. Bulk operations - Multi-select actions
5. Keyboard shortcuts - Faster workflow

💡 PRO TIPS

Efficient Universe Building:

1. Plan structure first - Sketch on paper
2. Create top-level modules - Galaxies, Navigation, Layouts
3. Enable move mode - Position them spatially
4. Lock canvas - Prevent accidental moves
5. Edit properties - Give meaningful names and routes
6. Add nested modules - Worlds, Pages, Features (manual for now)

Canvas Navigation:

• Space + Drag - Pan around (most common)
• Scroll - Zoom in/out
• Ctrl + 0 - Reset view
• Click empty space - Deselect all

Module Management:

• Shift + Click - Multi-select related modules
• Delete - Remove selected
• G key - Toggle grid snap
• Escape - Clear selection

✅ SUMMARY

To Add a Galaxy:

1. Drag "Galaxy" from left panel
2. Drop on canvas
3. Done! ✅

To Add ANY Module:

• Same process - all 10 types work!

To Move Modules:

1. Click lock icon (enable move mode)
2. Drag modules
3. Click arrows (lock again)

To Edit Structure:

• Currently: Manual via properties panel
• Soon: Drag-and-drop nesting

Status: Drag-drop works for all 10 module types! 🎉
Next: Test it and report what doesn't work!

Created: November 10, 2025 8:45 PM
Status: 📚 ACTIVE USER GUIDE