Dreamweaving Operations Specification

[ProjectLiminality]

Overview

Epic 6 implements Dreamweaving Operations - the vertical integration system that allows DreamNodes to incorporate external dependencies through Obsidian canvas parsing and git submodule management. This creates sovereign, self-contained DreamNodes that can be cloned without dependency issues.

Architecture

Core Components

1. Canvas Parser Service

   • Parses Obsidian .canvas JSON files (graph structure with nodes/edges)
   • Identifies file nodes with external paths (outside current DreamNode)
   • Uses vault-relative path analysis to detect cross-DreamNode references
   • Integrates with existing Git State Indicators for safety checks

2. Submodule Manager Service

   • Manages git submodule operations for external DreamNode dependencies
   • Handles path updates after submodule import
   • Ensures clean git state before operations (safety mechanisms)
   • Automatic commit of submodule additions and path updates

3. DreamSong Interface System

   • 3D flip animation for DreamNode3D component
   • Topological sort of canvas dependency graph (edges between file/text nodes)
   • Linear story flow generation from canvas relationships
   • Flip-flop layout pattern (alternating text/media positioning)

4. Full-Screen Experience

   • DreamTalk: Opens media files in new Obsidian leaf
   • DreamSong: Opens full-screen story interface in new leaf
   • Circular masking for quick-peek on DreamNode back side

Implementation Plan

Phase 1: Canvas Analysis Foundation

• Canvas JSON parser for node/edge extraction
• Path analysis service (vault-relative detection)
• External dependency detection algorithm
• Git state safety checks integration

Phase 2: Submodule Operations

• Git submodule management service
• Path rewriting after submodule import
• Automated commit workflows
• "Sync Submodules" command palette command

Phase 3: DreamSong Visualization

• DreamNode3D flip animation system
• Topological sorting algorithm for canvas dependencies
• Linear story flow React component
• Hover state flip button UI (bottom-center of DreamNode)

Phase 4: Full-Screen Integration

• Obsidian leaf management for full-screen experiences
• DreamSong full-screen component
• Media file opening via Obsidian API
• Circular masking for embedded DreamSong preview

User Experience

Canvas Creation Workflow

1. User creates .canvas file in DreamNode using Obsidian
2. References media files from anywhere in vault (cross-DreamNode)
3. Works normally without thinking about dependencies
4. Lightweight tracker shows "external dependencies" status
5. User triggers "Sync Submodules" command when ready
6. Canvas becomes sovereign (all dependencies internalized)

DreamSong Interaction

1. Hover over DreamNode reveals flip button (bottom-center)
2. Click flip button triggers 3D animation to back side
3. Back side shows DreamSong: linear story flow from canvas
4. Flip-flop text/media layout with scrolling
5. Full-screen button opens expanded story view
6. Flip button present on both sides (DreamTalk ↔ DreamSong)

Safety & Sovereignty

• Git state validation before submodule operations
• External dependency warnings/indicators
• Conscious user-triggered synchronization (not automatic)
• Results in truly portable, clonable DreamNodes

Feature Breakdown

Canvas Parser & Dependency Detection (#TBD)

• Parse .canvas JSON structure
• Identify file nodes with external paths
• Detect cross-DreamNode references via path analysis
• Integrate with git state indicators for safety

Git Submodule Management System (#TBD)

• Submodule import operations
• Path rewriting after import
• Safety checks and error handling
• Command palette integration

DreamNode Flip Animation & DreamSong UI (#TBD)

• 3D flip animation for DreamNode3D
• Topological sorting for canvas dependencies
• Linear story flow component
• Hover state controls (flip button)

Full-Screen DreamSong Experience (#TBD)

• Obsidian leaf management
• Full-screen story interface
• Media file integration
• Circular masking for preview

Technical Requirements

Dependencies

• Existing DreamNode3D component architecture
• Git state indicator system from Epic 3
• Obsidian Canvas API for file operations
• React Three Fiber for 3D animations

Performance Considerations

• Lazy loading for DreamSong content
• Efficient canvas parsing (JSON parsing only)
• Minimal git operations (user-triggered only)
• Smooth 3D animations without frame drops

Safety Mechanisms

• Clean git state validation before submodule operations
• Error handling for missing external dependencies
• User confirmation for destructive operations
• Rollback capabilities for failed imports

Definition of Done

• Canvas parser identifies external dependencies accurately
• Git submodule operations work reliably with safety checks
• DreamNode flip animation works smoothly in 3D space
• DreamSong interface displays linear story flow correctly
• Full-screen mode opens properly in Obsidian leaves
• "Sync Submodules" command works end-to-end
• Hover state controls function on both DreamNode sides
• All features integrated and tested
• Documentation complete with usage examples