melina 1.0.0

package/src/runtime.ts

@@ -0,0 +1,223 @@
+/**
+ * Melina.js Client-Side Runtime
+ * 
+ * Single bundle that handles:
+ * 1. Island Orchestrator initialization (single React root + portals)
+ * 2. Client-side navigation with View Transitions
+ * 3. Link interception
+ * 
+ * This is the ONLY client-side script needed - no per-island boilerplate.
+ */
+
+// ============================================================================
+// NAVIGATION
+// ============================================================================
+
+async function navigate(href: string) {
+    const fromPath = window.location.pathname;
+    const toPath = new URL(href, window.location.origin).pathname;
+
+    // Skip if same page
+    if (fromPath === toPath) return;
+
+    // Update URL immediately
+    window.history.pushState({}, '', href);
+
+    try {
+        // Fetch new page HTML
+        const response = await fetch(href, {
+            headers: { 'X-Melina-Nav': '1' }
+        });
+        const htmlText = await response.text();
+
+        // Parse new document
+        const parser = new DOMParser();
+        const newDoc = parser.parseFromString(htmlText, 'text/html');
+
+        // DOM update function - runs inside View Transition callback
+        const updateDOM = () => {
+            // Dispatch navigation-start INSIDE transition callback
+            // This lets islands update synchronously for view transition snapshot
+            window.dispatchEvent(new CustomEvent('melina:navigation-start', {
+                detail: { from: fromPath, to: toPath }
+            }));
+
+            // Update title
+            document.title = newDoc.title;
+
+            // PARTIAL SWAP: Only replace #melina-page-content
+            // Islands container (#melina-islands) is OUTSIDE, so React root persists
+            const currentContent = document.getElementById('melina-page-content');
+            const newContent = newDoc.getElementById('melina-page-content');
+
+            if (currentContent && newContent) {
+                currentContent.innerHTML = newContent.innerHTML;
+                console.log(`[Melina] Navigation ${fromPath} → ${toPath}`);
+            } else {
+                // Fallback: full body swap (but try to preserve islands container)
+                const islandsContainer = document.getElementById('melina-islands');
+                document.body.innerHTML = newDoc.body.innerHTML;
+                if (islandsContainer) {
+                    document.body.insertBefore(islandsContainer, document.body.firstChild);
+                }
+                console.log('[Melina] Full body swap (fallback)');
+            }
+
+            // Update island meta if present in new page
+            const newMeta = newDoc.getElementById('__MELINA_META__');
+            const currentMeta = document.getElementById('__MELINA_META__');
+            if (newMeta && currentMeta) {
+                currentMeta.textContent = newMeta.textContent;
+            }
+
+            // Scroll to top
+            window.scrollTo(0, 0);
+        };
+
+        // Execute update with View Transition if available
+        if (document.startViewTransition) {
+            const transition = document.startViewTransition(() => {
+                updateDOM();
+            });
+
+            // After transition completes, notify islands to re-scan
+            transition.finished.then(() => {
+                window.dispatchEvent(new CustomEvent('melina:navigated'));
+            });
+        } else {
+            updateDOM();
+            window.dispatchEvent(new CustomEvent('melina:navigated'));
+        }
+
+    } catch (error) {
+        console.error('[Melina] Navigation failed:', error);
+        // Fallback to full page load
+        window.location.href = href;
+    }
+}
+
+// Expose navigate globally for programmatic use
+(window as any).melinaNavigate = navigate;
+
+// ============================================================================
+// LINK INTERCEPTION
+// ============================================================================
+
+function initializeLinkInterception() {
+    document.addEventListener('click', (e) => {
+        const link = (e.target as Element).closest('a[href]');
+        if (!link) return;
+
+        const href = link.getAttribute('href');
+
+        // Skip: external links, downloads, modified clicks, non-local hrefs
+        if (
+            e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0 ||
+            link.hasAttribute('download') ||
+            link.hasAttribute('target') ||
+            link.hasAttribute('data-no-intercept') ||
+            !href || !href.startsWith('/')
+        ) {
+            return;
+        }
+
+        e.preventDefault();
+        navigate(href);
+    });
+
+    // Handle back/forward buttons
+    window.addEventListener('popstate', () => {
+        // On popstate, we need to fetch and render the page for the current URL
+        const href = window.location.pathname + window.location.search;
+
+        // Don't use navigate() since history is already updated
+        fetch(href, { headers: { 'X-Melina-Nav': '1' } })
+            .then(res => res.text())
+            .then(htmlText => {
+                const parser = new DOMParser();
+                const newDoc = parser.parseFromString(htmlText, 'text/html');
+
+                const updateDOM = () => {
+                    window.dispatchEvent(new CustomEvent('melina:navigation-start', {
+                        detail: { to: href }
+                    }));
+
+                    document.title = newDoc.title;
+
+                    const currentContent = document.getElementById('melina-page-content');
+                    const newContent = newDoc.getElementById('melina-page-content');
+
+                    if (currentContent && newContent) {
+                        currentContent.innerHTML = newContent.innerHTML;
+                    }
+                };
+
+                if (document.startViewTransition) {
+                    document.startViewTransition(() => updateDOM()).finished.then(() => {
+                        window.dispatchEvent(new CustomEvent('melina:navigated'));
+                    });
+                } else {
+                    updateDOM();
+                    window.dispatchEvent(new CustomEvent('melina:navigated'));
+                }
+            })
+            .catch(err => {
+                console.error('[Melina] Popstate navigation failed:', err);
+                window.location.reload();
+            });
+    });
+
+    console.log('[Melina] Link interception active');
+}
+
+// ============================================================================
+// ISLAND ORCHESTRATOR INITIALIZATION
+// ============================================================================
+
+async function initializeOrchestrator() {
+    const React = await import('react');
+    const { createRoot } = await import('react-dom/client');
+
+    // Create container if it doesn't exist
+    let container = document.getElementById('melina-islands');
+    if (!container) {
+        container = document.createElement('div');
+        container.id = 'melina-islands';
+        container.style.display = 'contents'; // Won't affect layout
+        document.body.insertBefore(container, document.body.firstChild);
+    }
+
+    // Import and instantiate the orchestrator
+    const { IslandOrchestrator } = await import('./IslandOrchestrator');
+
+    // Create single React root
+    const root = createRoot(container);
+    root.render(React.createElement(IslandOrchestrator));
+
+    console.log('[Melina] Island Orchestrator initialized');
+
+    return root;
+}
+
+// ============================================================================
+// BOOTSTRAP
+// ============================================================================
+
+async function bootstrap() {
+    // Initialize link interception first (synchronous)
+    initializeLinkInterception();
+
+    // Then initialize the Island Orchestrator (async)
+    await initializeOrchestrator();
+
+    console.log('[Melina] Runtime ready (Single Root + Portals architecture)');
+}
+
+// Run on DOM ready
+if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bootstrap);
+} else {
+    bootstrap();
+}
+
+export { navigate, initializeOrchestrator };

package/src/transform.ts

@@ -0,0 +1,168 @@
+/**
+ * Melina.js Import Transformer
+ * 
+ * Transforms 'use client' modules on import during SSR.
+ * Uses Bun's Transpiler API for fast transformation.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+
+// Cache for transformed modules
+const transformCache = new Map<string, any>();
+const CACHE_DIR = path.join(process.cwd(), '.melina', 'cache');
+
+// Ensure cache dir exists
+try {
+    if (!existsSync(CACHE_DIR)) {
+        mkdirSync(CACHE_DIR, { recursive: true });
+    }
+} catch (e) {
+    // Ignore
+}
+
+/**
+ * Island wrapper helper code
+ */
+const ISLAND_HELPER = `
+const __MELINA_SSR__ = typeof window === 'undefined';
+function __island__(Impl, name) {
+    if (__MELINA_SSR__) {
+        const R = require('react');
+        return (p) => R.createElement('div', {
+            'data-melina-island': name,
+            'data-props': JSON.stringify(p||{}).replace(/"/g,'&quot;')
+        });
+    }
+    return Impl;
+}
+`;
+
+/**
+ * Check for 'use client' directive
+ */
+export function isClientComponent(content: string): boolean {
+    const lines = content.split('\n').slice(0, 5).join('\n');
+    return lines.includes("'use client'") || lines.includes('"use client"');
+}
+
+/**
+ * Extract component exports
+ */
+export function extractExports(content: string): string[] {
+    const exports: string[] = [];
+
+    for (const m of content.matchAll(/export\s+function\s+([A-Z]\w*)/g)) exports.push(m[1]);
+    for (const m of content.matchAll(/export\s+const\s+([A-Z]\w*)\s*=/g)) exports.push(m[1]);
+    for (const m of content.matchAll(/export\s+default\s+function\s+([A-Z]\w*)/g)) exports.push(m[1]);
+
+    return [...new Set(exports)];
+}
+
+/**
+ * Transform client component source
+ */
+export function transformSource(content: string): string {
+    const exports = extractExports(content);
+    if (exports.length === 0) return content;
+
+    let out = content;
+
+    // Insert helper
+    out = out.replace(/(['"]use client['"];?\s*\n)/, `$1${ISLAND_HELPER}\n`);
+
+    // Rename exports
+    for (const name of exports) {
+        out = out.replace(new RegExp(`export\\s+function\\s+${name}\\b`), `function ${name}$impl`);
+        out = out.replace(new RegExp(`export\\s+const\\s+${name}\\s*=`), `const ${name}$impl =`);
+    }
+
+    // Add wrapped exports
+    for (const name of exports) {
+        out += `\nexport const ${name} = __island__(${name}$impl, '${name}');`;
+    }
+
+    // Handle default
+    const defaultMatch = content.match(/export\s+default\s+function\s+([A-Z]\w*)/);
+    if (defaultMatch) {
+        const name = defaultMatch[1];
+        out = out.replace(/export\s+default\s+function\s+([A-Z]\w*)/, `function ${name}$impl`);
+        out += `\nexport default ${name};`;
+    } else if (content.match(/export\s+default\s+([A-Z]\w*)\s*;?$/m)) {
+        const m = content.match(/export\s+default\s+([A-Z]\w*)\s*;?$/m);
+        if (m) {
+            out = out.replace(/export\s+default\s+([A-Z]\w*)\s*;?$/m, `export default __island__(${m[1]}$impl, '${m[1]}');`);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Get cache file path
+ */
+function getCachePath(filePath: string, content: string): string {
+    const hash = createHash('sha256').update(content).digest('hex').slice(0, 12);
+    const basename = path.basename(filePath, path.extname(filePath));
+    return path.join(CACHE_DIR, `${basename}.${hash}.mjs`);
+}
+
+/**
+ * Import a client component with transformation
+ */
+export async function importClientComponent(filePath: string): Promise<any> {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+
+    // Check memory cache
+    if (transformCache.has(absolutePath)) {
+        return transformCache.get(absolutePath);
+    }
+
+    const content = readFileSync(absolutePath, 'utf-8');
+
+    // If not client component, import normally
+    if (!isClientComponent(content)) {
+        const mod = await import(absolutePath);
+        transformCache.set(absolutePath, mod);
+        return mod;
+    }
+
+    // Check disk cache
+    const cachePath = getCachePath(absolutePath, content);
+
+    if (!existsSync(cachePath)) {
+        // Transform and write to cache
+        const transformed = transformSource(content);
+
+        // Use Bun's transpiler to convert TSX to JS
+        const transpiler = new Bun.Transpiler({
+            loader: 'tsx',
+            target: 'bun',
+        });
+        const js = transpiler.transformSync(transformed);
+
+        writeFileSync(cachePath, js);
+        console.log(`🏝️ [Melina] Transformed: ${path.basename(filePath)}`);
+    }
+
+    // Import from cache
+    const mod = await import(cachePath);
+    transformCache.set(absolutePath, mod);
+    return mod;
+}
+
+/**
+ * Clear transform cache
+ */
+export function clearCache(): void {
+    transformCache.clear();
+}
+
+export default {
+    isClientComponent,
+    extractExports,
+    transformSource,
+    importClientComponent,
+    clearCache,
+};