@ibgib/space-gib 0.0.33 → 0.0.34

package/src/client/ui/shell/cosmic-big-bang.mts

@@ -0,0 +1,844 @@
+/**
+ * @module cosmic-big-bang
+ *
+ * Cosmic Big Bang wireframe controller for space-gib Spaces view.
+ * Handles:
+ *   - Background starry canvas with gentle drift and twinkling (bulletproof rendering).
+ *   - "Big Bang" particle explosion / shockwave effect.
+ *   - 1st-order node unfolding (Identity, Superspace, Agent Chat).
+ *   - 2nd-order satellite unfolding (Code Space </>, Text Space 📝).
+ *   - Sequential app launch:
+ *       1. Superspace galaxy moves to top-left header.
+ *       2. Activity Bar expands on left.
+ *       3. Code Space / Text Space buttons move to their Activity Bar slots.
+ *       4. Left Panel expands with new user empty-state (0 repos).
+ *       5. Center Panel presents new-user onboarding view.
+ *   - Clicking the spinning galaxy in top-left (or activity bar cosmos button) returns to Cosmos view.
+ */
+
+export interface AttachedSpace {
+    id: string;
+    type: 'code' | 'text';
+    name: string;
+    shortLabel: string;
+    icon: string;
+}
+
+export interface CosmicBigBangOptions {
+    onSwitchToRepos?: () => void;
+    onLaunchApp?: (space: AttachedSpace) => void;
+    onReturnToCosmos?: () => void;
+}
+
+export class CosmicBigBangController {
+    private canvas: HTMLCanvasElement | null = null;
+    private ctx: CanvasRenderingContext2D | null = null;
+    private animFrameId: number | null = null;
+    private resizeObserver: ResizeObserver | null = null;
+
+    // Stars
+    private stars: Array<{ x: number; y: number; r: number; alpha: number; speed: number; phase: number }> = [];
+
+    // Particles (for Big Bang explosion)
+    private particles: Array<{
+        x: number;
+        y: number;
+        vx: number;
+        vy: number;
+        r: number;
+        color: string;
+        alpha: number;
+        decay: number;
+    }> = [];
+
+    // Shockwave
+    private shockwaveRadius = 0;
+    private shockwaveAlpha = 0;
+
+    private isClusterExpanded = false;
+    private areSatellitesUnfolded = false;
+    private isIdentityDocked = false;
+    private isAgentDocked = false;
+
+    // Dynamic Cosmos Spaces
+    private attachedSpaces: AttachedSpace[] = [];
+    private codeSpaceCounter = 0;
+    private textSpaceCounter = 0;
+    private activeSpaceId: string | null = null;
+
+    private onSwitchToRepos?: () => void;
+    private onLaunchApp?: (space: AttachedSpace) => void;
+    private onReturnToCosmos?: () => void;
+
+    constructor(options?: CosmicBigBangOptions) {
+        this.onSwitchToRepos = options?.onSwitchToRepos;
+        this.onLaunchApp = options?.onLaunchApp;
+        this.onReturnToCosmos = options?.onReturnToCosmos;
+    }
+
+    public init(): void {
+        this.canvas = document.getElementById('cosmic-canvas') as HTMLCanvasElement | null;
+        if (!this.canvas) return;
+
+        this.ctx = this.canvas.getContext('2d');
+        if (!this.ctx) return;
+
+        this.resizeCanvas();
+
+        // Use ResizeObserver for bulletproof container tracking
+        if (typeof window !== 'undefined' && 'ResizeObserver' in window && this.canvas.parentElement) {
+            this.resizeObserver = new ResizeObserver(() => {
+                this.resizeCanvas();
+            });
+            this.resizeObserver.observe(this.canvas.parentElement);
+        }
+
+        window.addEventListener('resize', () => this.resizeCanvas());
+
+        this.initStars();
+        this.startLoop();
+        this.bindEvents();
+    }
+
+    public ensureStars(): void {
+        this.resizeCanvas();
+        if (this.stars.length === 0) {
+            this.initStars();
+        }
+
+        // Re-check after slight timeouts to ensure post-layout dimensions are caught
+        setTimeout(() => {
+            this.resizeCanvas();
+            if (this.stars.length === 0) {
+                this.initStars();
+            }
+        }, 50);
+
+        setTimeout(() => {
+            this.resizeCanvas();
+        }, 200);
+    }
+
+    private resizeCanvas(): void {
+        if (!this.canvas) return;
+        const parent = this.canvas.parentElement;
+        const parentW = parent && parent.clientWidth > 0 ? parent.clientWidth : window.innerWidth;
+        const parentH = parent && parent.clientHeight > 0 ? parent.clientHeight : (window.innerHeight - 100);
+        const targetW = Math.max(300, Math.floor(parentW));
+        const targetH = Math.max(300, Math.floor(parentH));
+
+        if (this.canvas.width !== targetW || this.canvas.height !== targetH) {
+            this.canvas.width = targetW;
+            this.canvas.height = targetH;
+            if (this.stars.length === 0) {
+                this.initStars();
+            }
+        }
+    }
+
+    private initStars(): void {
+        if (!this.canvas) return;
+        const w = Math.max(300, this.canvas.width);
+        const h = Math.max(300, this.canvas.height);
+        this.stars = [];
+        const count = Math.max(100, Math.min(250, Math.floor((w * h) / 3600)));
+        for (let i = 0; i < count; i++) {
+            this.stars.push({
+                x: Math.random() * w,
+                y: Math.random() * h,
+                r: Math.random() * 1.6 + 0.4,
+                alpha: Math.random() * 0.75 + 0.25,
+                speed: Math.random() * 0.015 + 0.005,
+                phase: Math.random() * Math.PI * 2,
+            });
+        }
+    }
+
+    private startLoop(): void {
+        const loop = () => {
+            this.render();
+            this.animFrameId = requestAnimationFrame(loop);
+        };
+        this.animFrameId = requestAnimationFrame(loop);
+    }
+
+    private render(): void {
+        if (!this.ctx || !this.canvas) return;
+        const ctx = this.ctx;
+        const width = this.canvas.width;
+        const height = this.canvas.height;
+
+        if (width < 50 || height < 50) {
+            this.resizeCanvas();
+            return;
+        }
+
+        // Clear with transparent void
+        ctx.clearRect(0, 0, width, height);
+
+        // Guarantee stars are populated
+        if (this.stars.length === 0) {
+            this.initStars();
+        }
+
+        // Draw Twinkling Stars (with bound wrapping)
+        for (const star of this.stars) {
+            if (star.x > width) star.x %= width;
+            if (star.y > height) star.y %= height;
+            star.phase += star.speed;
+            const currentAlpha = Math.max(0.15, Math.min(1, star.alpha + Math.sin(star.phase) * 0.35));
+            ctx.fillStyle = `rgba(255, 255, 255, ${currentAlpha})`;
+            ctx.beginPath();
+            ctx.arc(star.x, star.y, star.r, 0, Math.PI * 2);
+            ctx.fill();
+        }
+
+        // Draw Shockwave
+        if (this.shockwaveAlpha > 0.01) {
+            ctx.save();
+            ctx.beginPath();
+            ctx.arc(width / 2, height / 2, this.shockwaveRadius, 0, Math.PI * 2);
+            ctx.strokeStyle = `rgba(120, 248, 126, ${this.shockwaveAlpha * 0.6})`;
+            ctx.lineWidth = 3;
+            ctx.stroke();
+
+            ctx.beginPath();
+            ctx.arc(width / 2, height / 2, Math.max(0, this.shockwaveRadius - 20), 0, Math.PI * 2);
+            ctx.strokeStyle = `rgba(180, 100, 255, ${this.shockwaveAlpha * 0.4})`;
+            ctx.lineWidth = 2;
+            ctx.stroke();
+            ctx.restore();
+
+            this.shockwaveRadius += 14;
+            this.shockwaveAlpha *= 0.94;
+        }
+
+        // Draw Particles
+        if (this.particles.length > 0) {
+            for (let i = this.particles.length - 1; i >= 0; i--) {
+                const p = this.particles[i];
+                p.x += p.vx;
+                p.y += p.vy;
+                p.vx *= 0.96;
+                p.vy *= 0.96;
+                p.alpha -= p.decay;
+
+                if (p.alpha <= 0.02) {
+                    this.particles.splice(i, 1);
+                    continue;
+                }
+
+                ctx.fillStyle = p.color.replace('ALPHA', p.alpha.toFixed(2));
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2);
+                ctx.fill();
+            }
+        }
+    }
+
+    private triggerBigBangExplosion(): void {
+        if (!this.canvas) return;
+        const cx = this.canvas.width / 2;
+        const cy = this.canvas.height / 2;
+
+        this.shockwaveRadius = 10;
+        this.shockwaveAlpha = 1.0;
+        this.particles = [];
+
+        const colors = [
+            'rgba(120, 248, 126, ALPHA)', // ibgib green
+            'rgba(180, 100, 255, ALPHA)', // cosmic violet
+            'rgba(68, 170, 255, ALPHA)',  // cyan blue
+            'rgba(255, 204, 68, ALPHA)',  // starlight gold
+            'rgba(255, 255, 255, ALPHA)', // white
+        ];
+
+        const particleCount = 140;
+        for (let i = 0; i < particleCount; i++) {
+            const angle = Math.random() * Math.PI * 2;
+            const speed = Math.random() * 12 + 3;
+            const color = colors[Math.floor(Math.random() * colors.length)];
+            this.particles.push({
+                x: cx,
+                y: cy,
+                vx: Math.cos(angle) * speed,
+                vy: Math.sin(angle) * speed,
+                r: Math.random() * 3 + 1,
+                color,
+                alpha: 1.0,
+                decay: Math.random() * 0.025 + 0.015,
+            });
+        }
+    }
+
+    private bindEvents(): void {
+        // Singularity Button
+        const btnBigBang = document.getElementById('btn-big-bang');
+        if (btnBigBang) {
+            btnBigBang.addEventListener('click', () => this.initiateBigBang());
+        }
+
+        // Identity Node
+        const btnIdentity = document.getElementById('btn-cosmic-identity');
+        if (btnIdentity) {
+            btnIdentity.addEventListener('click', () => this.handleIdentityClick());
+        }
+
+        // Superspace (Galaxy) Node
+        const btnSuperspace = document.getElementById('btn-cosmic-superspace');
+        if (btnSuperspace) {
+            btnSuperspace.addEventListener('click', () => this.handleSuperspaceClick());
+        }
+
+        // Code Space Satellite (</>)
+        const btnCode = document.getElementById('btn-cosmic-code');
+        if (btnCode) {
+            btnCode.addEventListener('click', () => this.triggerAddSpace('code'));
+        }
+
+        // Text Space Satellite (📝)
+        const btnNotes = document.getElementById('btn-cosmic-notes');
+        if (btnNotes) {
+            btnNotes.addEventListener('click', () => this.triggerAddSpace('text'));
+        }
+
+        // Agent Chat Node (🤖)
+        const btnAgent = document.getElementById('btn-cosmic-agent');
+        if (btnAgent) {
+            btnAgent.addEventListener('click', () => this.handleAgentClick());
+        }
+
+        // Agent Footer/FAB Button
+        const agentFabBtn = document.getElementById('agent-fab-btn') || document.getElementById('btn-footer-agent');
+        if (agentFabBtn) {
+            agentFabBtn.addEventListener('click', () => {
+                alert('🤖 ibgib Agent: "Hello! I am your AI assistant across superspaces. How can I help you today?"');
+            });
+        }
+
+        // Reset Button
+        const btnReset = document.getElementById('btn-cosmic-reset');
+        if (btnReset) {
+            btnReset.addEventListener('click', () => this.resetToSingularity());
+        }
+
+        // Header Brand Galaxy (Return to Cosmos)
+        const brandLink = document.getElementById('space-gib-title-link');
+        if (brandLink) {
+            brandLink.addEventListener('click', (e) => {
+                e.preventDefault();
+                this.returnToCosmos();
+            });
+        }
+
+        // Activity Bar Cosmos Button (Top of Rail)
+        const activityCosmosBtn = document.getElementById('activity-btn-cosmos');
+        if (activityCosmosBtn) {
+            activityCosmosBtn.addEventListener('click', () => this.returnToCosmos());
+        }
+
+        // Onboarding Cosmos Return Buttons
+        const onboardingCosmosBtn = document.getElementById('btn-onboarding-cosmos');
+        if (onboardingCosmosBtn) {
+            onboardingCosmosBtn.addEventListener('click', () => this.returnToCosmos());
+        }
+        const onboardingCosmosTextBtn = document.getElementById('btn-onboarding-cosmos-text');
+        if (onboardingCosmosTextBtn) {
+            onboardingCosmosTextBtn.addEventListener('click', () => this.returnToCosmos());
+        }
+
+        // Side view Add Space (+) button
+        const btnSideAddSpace = document.getElementById('btn-side-add-space');
+        if (btnSideAddSpace) {
+            btnSideAddSpace.addEventListener('click', () => {
+                this.returnToCosmos();
+                // Automatically unfold satellites
+                const satellites = document.getElementById('superspace-satellites');
+                if (satellites) {
+                    satellites.classList.remove('collapsed');
+                    satellites.classList.add('unfolded');
+                    this.areSatellitesUnfolded = true;
+                }
+            });
+        }
+
+        // Side view Cosmos Settings (⚙️) button
+        const btnSideCosmosSettings = document.getElementById('btn-side-cosmos-settings');
+        if (btnSideCosmosSettings) {
+            btnSideCosmosSettings.addEventListener('click', () => {
+                alert('⚙️ Cosmos Project Settings\n\nCosmos: my-cosmos\nTopology: Decentralized Multi-Space\nProtocol: ibgib v1 (Merkle DAG)');
+            });
+        }
+
+        // Empty state buttons
+        const btnEmptyInit = document.getElementById('btn-empty-init-space');
+        if (btnEmptyInit) {
+            btnEmptyInit.addEventListener('click', () => {
+                alert('🚀 Initialize Space\n\nCreating a new content-addressed DAG in browser storage.\n(Next phase implementation)');
+            });
+        }
+        const btnEmptyClone = document.getElementById('btn-side-clone-space');
+        if (btnEmptyClone) {
+            btnEmptyClone.addEventListener('click', () => {
+                alert('⬇ Clone Space\n\nConnect to remote ibgib space via address or URL.\n(Next phase implementation)');
+            });
+        }
+        const btnEmptyInitText = document.getElementById('btn-empty-init-text');
+        if (btnEmptyInitText) {
+            btnEmptyInitText.addEventListener('click', () => {
+                alert('📝 Create Note\n\nCreating a new markdown metatext node with inverted soft rel8n.\n(Next phase implementation)');
+            });
+        }
+    }
+
+    public initiateBigBang(): void {
+        const singularityContainer = document.getElementById('cosmic-singularity-container');
+        const cluster = document.getElementById('cosmic-cluster');
+        const controls = document.getElementById('cosmic-controls');
+
+        // Trigger particles & shockwave
+        this.triggerBigBangExplosion();
+
+        // Animate singularity collapse
+        if (singularityContainer) {
+            singularityContainer.classList.add('collapsed');
+        }
+
+        // Reset animation on drift wrappers so they start fresh from 0%
+        const nodeIdentityWrapper = document.getElementById('node-identity-wrapper');
+        const nodeAgentWrapper = document.getElementById('node-agent-wrapper');
+        if (nodeIdentityWrapper) {
+            nodeIdentityWrapper.classList.remove('shooting-to-top-right');
+            nodeIdentityWrapper.style.animation = 'none';
+            void nodeIdentityWrapper.offsetHeight; // trigger reflow
+            nodeIdentityWrapper.style.animation = '';
+        }
+        if (nodeAgentWrapper) {
+            nodeAgentWrapper.classList.remove('shooting-to-bottom-right');
+            nodeAgentWrapper.style.animation = 'none';
+            void nodeAgentWrapper.offsetHeight; // trigger reflow
+            nodeAgentWrapper.style.animation = '';
+        }
+
+        // Unfold 1st-order cluster after brief burst delay
+        setTimeout(() => {
+            if (cluster) {
+                cluster.classList.remove('hidden');
+                cluster.classList.add('expanded');
+            }
+            if (controls) {
+                controls.classList.remove('hidden');
+            }
+            this.isClusterExpanded = true;
+        }, 300);
+    }
+
+    public handleIdentityClick(): void {
+        if (this.isIdentityDocked) return;
+        const nodeIdentityWrapper = document.getElementById('node-identity-wrapper');
+        const identityHeaderContainer = document.getElementById('identity-header-container');
+
+        if (nodeIdentityWrapper) {
+            nodeIdentityWrapper.classList.add('shooting-to-top-right');
+        }
+
+        setTimeout(() => {
+            this.isIdentityDocked = true;
+            if (identityHeaderContainer) {
+                identityHeaderContainer.classList.add('identity-active-highlight');
+            }
+        }, 600);
+    }
+
+    public handleSuperspaceClick(): void {
+        const satellites = document.getElementById('superspace-satellites');
+        if (!satellites) { return; }
+
+        this.areSatellitesUnfolded = !this.areSatellitesUnfolded;
+        if (this.areSatellitesUnfolded) {
+            satellites.classList.remove('collapsed');
+            satellites.classList.add('unfolded');
+        } else {
+            satellites.classList.remove('unfolded');
+            satellites.classList.add('collapsed');
+        }
+    }
+
+    /**
+     * Staggered sequence for dynamically adding a Space (Code Space or Text Space):
+     *   1. (0ms) Superspace galaxy moves towards top-left header.
+     *   2. (380ms) Activity Bar and Left Panel expand.
+     *   3. (650ms) Clicked button moves towards its new Activity Bar rail slot.
+     *   4. (1000ms) Space is instantiated, appended to Activity Bar, and its views are presented.
+     */
+    public triggerAddSpace(appType: 'code' | 'text'): void {
+        const nodeSuperspaceWrapper = document.getElementById('node-superspace-wrapper');
+        const headerBrandGalaxy = document.getElementById('header-brand-galaxy');
+        const activityBar = document.getElementById('activity-bar');
+        const leftPanel = document.getElementById('left-panel');
+        const btnCode = document.getElementById('btn-cosmic-code');
+        const btnNotes = document.getElementById('btn-cosmic-notes');
+
+        // Stage 1 (0ms): Superspace galaxy shoots towards top-left
+        if (nodeSuperspaceWrapper) {
+            nodeSuperspaceWrapper.classList.add('shooting-to-top-left');
+        }
+
+        // Stage 2 (380ms): Header galaxy activates; Activity Bar & Left Panel expand
+        setTimeout(() => {
+            if (headerBrandGalaxy) {
+                headerBrandGalaxy.classList.add('brand-galaxy-active');
+            }
+            if (activityBar) {
+                activityBar.classList.remove('collapsed');
+                activityBar.classList.add('expanded');
+            }
+            if (leftPanel) {
+                leftPanel.classList.remove('collapsed');
+                leftPanel.classList.add('expanded');
+            }
+        }, 380);
+
+        // Stage 3 (650ms): The clicked satellite button animates towards the rail
+        setTimeout(() => {
+            if (appType === 'code' && btnCode) {
+                btnCode.classList.add('shooting-to-activity-code');
+            } else if (appType === 'text' && btnNotes) {
+                btnNotes.classList.add('shooting-to-activity-text');
+            }
+        }, 650);
+
+        // Stage 4 (1000ms): Instantiate space, append to rail, and switch view
+        setTimeout(() => {
+            const space = this.createSpace(appType);
+            this.switchToSpace(space.id);
+
+            // Reset cluster elements for when user returns to Cosmos
+            if (btnCode) { btnCode.classList.remove('shooting-to-activity-code'); }
+            if (btnNotes) { btnNotes.classList.remove('shooting-to-activity-text'); }
+            const satellites = document.getElementById('superspace-satellites');
+            if (satellites) {
+                satellites.classList.remove('unfolded');
+                satellites.classList.add('collapsed');
+                this.areSatellitesUnfolded = false;
+            }
+            if (nodeSuperspaceWrapper) {
+                nodeSuperspaceWrapper.classList.remove('shooting-to-top-left');
+            }
+
+            this.onLaunchApp?.(space);
+        }, 1000);
+    }
+
+    private createSpace(type: 'code' | 'text'): AttachedSpace {
+        if (type === 'code') {
+            this.codeSpaceCounter++;
+            const id = `space-code-${this.codeSpaceCounter}`;
+            const space: AttachedSpace = {
+                id,
+                type: 'code',
+                name: `Code Space ${this.codeSpaceCounter}`,
+                shortLabel: `Code ${this.codeSpaceCounter}`,
+                icon: '&lt;/&gt;'
+            };
+            this.attachedSpaces.push(space);
+            this.appendSpaceToRail(space);
+            this.updateCosmosSettingsList();
+            return space;
+        } else {
+            this.textSpaceCounter++;
+            const id = `space-text-${this.textSpaceCounter}`;
+            const space: AttachedSpace = {
+                id,
+                type: 'text',
+                name: `Text Space ${this.textSpaceCounter}`,
+                shortLabel: `Text ${this.textSpaceCounter}`,
+                icon: '📝'
+            };
+            this.attachedSpaces.push(space);
+            this.appendSpaceToRail(space);
+            this.updateCosmosSettingsList();
+            return space;
+        }
+    }
+
+    private appendSpaceToRail(space: AttachedSpace): void {
+        const container = document.getElementById('activity-spaces-container');
+        if (!container) { return; }
+
+        const btn = document.createElement('button');
+        btn.className = 'activity-bar-btn activity-space-btn';
+        btn.id = `activity-btn-${space.id}`;
+        btn.type = 'button';
+        btn.setAttribute('data-space-id', space.id);
+        btn.title = space.name;
+        btn.innerHTML = `
+            <span class="activity-icon">${space.icon}</span>
+            <span class="activity-label">${space.shortLabel}</span>
+        `;
+        btn.addEventListener('click', () => {
+            this.switchToSpace(space.id);
+        });
+
+        container.appendChild(btn);
+    }
+
+    public switchToSpace(spaceId: string): void {
+        const space = this.attachedSpaces.find(s => s.id === spaceId);
+        if (!space) { return; }
+
+        this.activeSpaceId = spaceId;
+
+        // Activity Bar state
+        const actCosmos = document.getElementById('activity-btn-cosmos');
+        actCosmos?.classList.remove('active');
+
+        const allSpaceBtns = document.querySelectorAll('.activity-space-btn');
+        allSpaceBtns.forEach(btn => {
+            if (btn.getAttribute('data-space-id') === spaceId) {
+                btn.classList.add('active');
+            } else {
+                btn.classList.remove('active');
+            }
+        });
+
+        // Ensure panels are expanded
+        const activityBar = document.getElementById('activity-bar');
+        const leftPanel = document.getElementById('left-panel');
+        if (activityBar) {
+            activityBar.classList.remove('collapsed');
+            activityBar.classList.add('expanded');
+        }
+        if (leftPanel) {
+            leftPanel.classList.remove('collapsed');
+            leftPanel.classList.add('expanded');
+        }
+
+        // Left Panel Side Views
+        const leftCosmos = document.getElementById('left-panel-cosmos-view');
+        const leftCode = document.getElementById('left-panel-code-view');
+        const leftText = document.getElementById('left-panel-text-view');
+
+        if (leftCosmos) { leftCosmos.style.display = 'none'; }
+
+        if (space.type === 'code') {
+            if (leftCode) { leftCode.style.display = 'block'; }
+            if (leftText) { leftText.style.display = 'none'; }
+            const titleEl = document.getElementById('left-code-space-title');
+            if (titleEl) { titleEl.textContent = space.name; }
+        } else {
+            if (leftText) { leftText.style.display = 'block'; }
+            if (leftCode) { leftCode.style.display = 'none'; }
+            const titleEl = document.getElementById('left-text-space-title');
+            if (titleEl) { titleEl.textContent = space.name; }
+        }
+
+        // Center Views
+        const viewSpaces = document.getElementById('view-spaces');
+        const viewRepos = document.getElementById('view-repos');
+        const viewCodeOnboarding = document.getElementById('view-code-onboarding');
+        const viewTextOnboarding = document.getElementById('view-text-onboarding');
+
+        if (viewSpaces) { viewSpaces.style.display = 'none'; }
+        if (viewRepos) { viewRepos.style.display = 'none'; }
+
+        if (space.type === 'code') {
+            if (viewCodeOnboarding) { viewCodeOnboarding.style.display = 'flex'; }
+            if (viewTextOnboarding) { viewTextOnboarding.style.display = 'none'; }
+        } else {
+            if (viewTextOnboarding) { viewTextOnboarding.style.display = 'flex'; }
+            if (viewCodeOnboarding) { viewCodeOnboarding.style.display = 'none'; }
+            const textTitle = document.getElementById('text-onboarding-title');
+            if (textTitle) { textTitle.textContent = space.name; }
+        }
+    }
+
+    /**
+     * Injects Cosmos navigation component back into center panel,
+     * switches Left Panel to Cosmos Settings / Overview,
+     * and guarantees background stars are fully sparkling.
+     */
+    public returnToCosmos(): void {
+        this.activeSpaceId = null;
+
+        // Activity Bar state: Cosmos at top is active
+        const actCosmos = document.getElementById('activity-btn-cosmos');
+        actCosmos?.classList.add('active');
+
+        const allSpaceBtns = document.querySelectorAll('.activity-space-btn');
+        allSpaceBtns.forEach(btn => btn.classList.remove('active'));
+
+        // Left Panel: Cosmos Settings view
+        const leftCosmos = document.getElementById('left-panel-cosmos-view');
+        const leftCode = document.getElementById('left-panel-code-view');
+        const leftText = document.getElementById('left-panel-text-view');
+
+        if (leftCosmos) { leftCosmos.style.display = 'block'; }
+        if (leftCode) { leftCode.style.display = 'none'; }
+        if (leftText) { leftText.style.display = 'none'; }
+
+        this.updateCosmosSettingsList();
+
+        // Center Panel: Cosmos Spaces stage
+        const viewSpaces = document.getElementById('view-spaces');
+        const viewRepos = document.getElementById('view-repos');
+        const viewCodeOnboarding = document.getElementById('view-code-onboarding');
+        const viewTextOnboarding = document.getElementById('view-text-onboarding');
+
+        if (viewCodeOnboarding) { viewCodeOnboarding.style.display = 'none'; }
+        if (viewTextOnboarding) { viewTextOnboarding.style.display = 'none'; }
+        if (viewRepos) { viewRepos.style.display = 'none'; }
+        if (viewSpaces) { viewSpaces.style.display = 'flex'; }
+
+        // Reset header galaxy pulse
+        const headerBrandGalaxy = document.getElementById('header-brand-galaxy');
+        if (headerBrandGalaxy) {
+            headerBrandGalaxy.classList.remove('brand-galaxy-active');
+        }
+
+        // Reset stage elements if needed
+        const nodeSuperspaceWrapper = document.getElementById('node-superspace-wrapper');
+        if (nodeSuperspaceWrapper) {
+            nodeSuperspaceWrapper.classList.remove('shooting-to-top-left');
+        }
+
+        // Bulletproof stars guarantee
+        this.ensureStars();
+
+        this.onReturnToCosmos?.();
+    }
+
+    private updateCosmosSettingsList(): void {
+        const countEl = document.getElementById('cosmos-spaces-count');
+        const listEl = document.getElementById('cosmos-spaces-list');
+        if (countEl) { countEl.textContent = String(this.attachedSpaces.length); }
+
+        if (!listEl) { return; }
+
+        if (this.attachedSpaces.length === 0) {
+            listEl.innerHTML = `<p class="empty-list-note">No spaces added yet.<br>Click Code or Text in Cosmos to attach a space.</p>`;
+            return;
+        }
+
+        listEl.innerHTML = '';
+        for (const space of this.attachedSpaces) {
+            const item = document.createElement('div');
+            item.className = `cosmos-space-item ${this.activeSpaceId === space.id ? 'active' : ''}`;
+            item.setAttribute('data-space-id', space.id);
+            item.innerHTML = `
+                <span class="space-item-name">
+                    <span class="space-item-icon">${space.icon}</span>
+                    <span>${space.name}</span>
+                </span>
+                <span class="space-item-type">${space.type.toUpperCase()}</span>
+            `;
+            item.addEventListener('click', () => {
+                this.switchToSpace(space.id);
+            });
+            listEl.appendChild(item);
+        }
+    }
+
+    public handleAgentClick(): void {
+        if (this.isAgentDocked) return;
+        const nodeAgentWrapper = document.getElementById('node-agent-wrapper');
+        const agentFabContainer = document.getElementById('agent-fab-container');
+
+        if (nodeAgentWrapper) {
+            nodeAgentWrapper.classList.add('shooting-to-bottom-right');
+        }
+
+        setTimeout(() => {
+            this.isAgentDocked = true;
+            if (agentFabContainer) {
+                agentFabContainer.classList.remove('hidden');
+                agentFabContainer.classList.add('visible');
+            }
+        }, 600);
+    }
+
+    public resetToSingularity(): void {
+        this.attachedSpaces = [];
+        this.codeSpaceCounter = 0;
+        this.textSpaceCounter = 0;
+        this.activeSpaceId = null;
+
+        const spacesContainer = document.getElementById('activity-spaces-container');
+        if (spacesContainer) { spacesContainer.innerHTML = ''; }
+
+        const activityBar = document.getElementById('activity-bar');
+        const leftPanel = document.getElementById('left-panel');
+        if (activityBar) {
+            activityBar.classList.remove('expanded');
+            activityBar.classList.add('collapsed');
+        }
+        if (leftPanel) {
+            leftPanel.classList.remove('expanded');
+            leftPanel.classList.add('collapsed');
+        }
+
+        const singularityContainer = document.getElementById('cosmic-singularity-container');
+        const cluster = document.getElementById('cosmic-cluster');
+        const controls = document.getElementById('cosmic-controls');
+        const satellites = document.getElementById('superspace-satellites');
+        const nodeIdentityWrapper = document.getElementById('node-identity-wrapper');
+        const nodeAgentWrapper = document.getElementById('node-agent-wrapper');
+        const nodeSuperspaceWrapper = document.getElementById('node-superspace-wrapper');
+        const agentFabContainer = document.getElementById('agent-fab-container');
+        const identityHeaderContainer = document.getElementById('identity-header-container');
+        const headerBrandGalaxy = document.getElementById('header-brand-galaxy');
+        const btnCode = document.getElementById('btn-cosmic-code');
+        const btnNotes = document.getElementById('btn-cosmic-notes');
+
+        this.isClusterExpanded = false;
+        this.areSatellitesUnfolded = false;
+        this.isIdentityDocked = false;
+        this.isAgentDocked = false;
+
+        // Reset classes and animations
+        if (nodeIdentityWrapper) {
+            nodeIdentityWrapper.classList.remove('shooting-to-top-right');
+            nodeIdentityWrapper.style.animation = 'none';
+        }
+        if (nodeAgentWrapper) {
+            nodeAgentWrapper.classList.remove('shooting-to-bottom-right');
+            nodeAgentWrapper.style.animation = 'none';
+        }
+        if (nodeSuperspaceWrapper) {
+            nodeSuperspaceWrapper.classList.remove('shooting-to-top-left');
+        }
+        if (btnCode) {
+            btnCode.classList.remove('shooting-to-activity-code');
+        }
+        if (btnNotes) {
+            btnNotes.classList.remove('shooting-to-activity-text');
+        }
+        if (headerBrandGalaxy) {
+            headerBrandGalaxy.classList.remove('brand-galaxy-active');
+        }
+        if (identityHeaderContainer) {
+            identityHeaderContainer.classList.remove('identity-active-highlight');
+        }
+        if (agentFabContainer) {
+            agentFabContainer.classList.remove('visible');
+            agentFabContainer.classList.add('hidden');
+        }
+        if (satellites) {
+            satellites.classList.remove('unfolded');
+            satellites.classList.add('collapsed');
+        }
+        if (cluster) {
+            cluster.classList.remove('expanded');
+            cluster.classList.add('hidden');
+        }
+        if (controls) {
+            controls.classList.add('hidden');
+        }
+        if (singularityContainer) {
+            singularityContainer.classList.remove('collapsed');
+        }
+
+        // Return to Cosmos view in center
+        this.returnToCosmos();
+    }
+}