melina 1.0.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "melina",
+  "version": "1.0.0",
+  "description": "A lightweight, islands-architecture web framework for Bun with Next.js-style routing.",
+  "module": "./src/web.ts",
+  "main": "./src/web.ts",
+  "bin": {
+    "melina": "./bin/melina"
+  },
+  "files": [
+    "src",
+    "bin",
+    "docs",
+    "GUIDE.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/web.ts",
+    "./web": "./src/web.ts",
+    "./Link": "./src/Link.tsx",
+    "./island": "./src/island.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mements/melina.js"
+  },
+  "author": {
+    "name": "Mements Team"
+  },
+  "bugs": "https://github.com/mements/melina.js/issues",
+  "homepage": "https://github.com/mements/melina.js#readme",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "server",
+    "framework",
+    "typescript",
+    "web",
+    "ssr",
+    "islands",
+    "islands-architecture",
+    "hydration",
+    "nextjs",
+    "app-router",
+    "react",
+    "partial-hydration"
+  ],
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3"
+  },
+  "dependencies": {
+    "@ments/utils": "^1.2.1",
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@solana/kit": "^2.1.0",
+    "@tailwindcss/postcss": "^4.1.10",
+    "autoprefixer": "^10.4.21",
+    "postcss": "^8.5.6",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "ts-dedent": "^2.2.0",
+    "zod": "^3.24.4"
+  }
+}

package/src/IslandOrchestrator.tsx

@@ -0,0 +1,259 @@
+'use client';
+
+/**
+ * IslandOrchestrator - Single React Root + Portals Architecture
+ * 
+ * This component manages ALL islands in the application from a single React root.
+ * Each island is rendered as a React Portal into its placeholder in the DOM.
+ * 
+ * Benefits:
+ * - Single React instance (no duplicate bundles)
+ * - Shared state context across all islands
+ * - Islands persist across navigation (portals just re-target)
+ * - View Transitions work naturally (same React tree)
+ */
+
+import React, { useState, useEffect, useCallback, useSyncExternalStore } from 'react';
+import { createPortal, flushSync } from 'react-dom';
+
+// Types
+interface IslandConfig {
+    name: string;
+    props: Record<string, any>;
+    target: HTMLElement;
+    instanceId: string;
+}
+
+interface LoadedIsland extends IslandConfig {
+    Component: React.ComponentType<any>;
+}
+
+// Global component cache - shared across all orchestrator instances
+const componentCache: Record<string, React.ComponentType<any>> = {};
+
+// Get island meta from the page
+function getIslandMeta(): Record<string, string> {
+    const metaEl = document.getElementById('__MELINA_META__');
+    if (!metaEl) return {};
+    try {
+        return JSON.parse(metaEl.textContent || '{}');
+    } catch {
+        return {};
+    }
+}
+
+// Collect all island placeholders from the DOM
+function collectIslandPlaceholders(): IslandConfig[] {
+    const elements = document.querySelectorAll('[data-island]');
+    const islands: IslandConfig[] = [];
+
+    elements.forEach((el, index) => {
+        const name = el.getAttribute('data-island');
+        if (!name) return;
+
+        const propsStr = (el.getAttribute('data-props') || '{}').replace(/&quot;/g, '"');
+        let props = {};
+        try {
+            props = JSON.parse(propsStr);
+        } catch (e) {
+            console.warn(`[Melina] Invalid props for island ${name}:`, e);
+        }
+
+        // Generate stable instance ID
+        const instanceId = el.getAttribute('data-instance') || `${name}-${index}`;
+
+        islands.push({
+            name,
+            props,
+            target: el as HTMLElement,
+            instanceId
+        });
+    });
+
+    return islands;
+}
+
+// Load a component module dynamically
+async function loadComponent(name: string): Promise<React.ComponentType<any> | null> {
+    // Check cache first
+    if (componentCache[name]) {
+        return componentCache[name];
+    }
+
+    const meta = getIslandMeta();
+    const bundlePath = meta[name];
+
+    if (!bundlePath) {
+        console.warn(`[Melina] No bundle found for island: ${name}`);
+        return null;
+    }
+
+    try {
+        const module = await import(/* @vite-ignore */ bundlePath);
+        // Try named export first, then default
+        const Component = module[name] || module.default;
+
+        if (Component) {
+            componentCache[name] = Component;
+            console.log(`[Melina] Loaded component: ${name}`);
+            return Component;
+        } else {
+            console.warn(`[Melina] No export found for component: ${name}`);
+            return null;
+        }
+    } catch (e) {
+        console.error(`[Melina] Failed to load component ${name}:`, e);
+        return null;
+    }
+}
+
+// Island wrapper - renders the component in a portal
+function IslandPortal({ island }: { island: LoadedIsland }) {
+    const { Component, props, target, name, instanceId } = island;
+
+    // Mark as hydrated
+    useEffect(() => {
+        target.setAttribute('data-hydrated', 'true');
+        return () => {
+            target.removeAttribute('data-hydrated');
+        };
+    }, [target]);
+
+    return createPortal(
+        <Component {...props} />,
+        target
+    );
+}
+
+// Navigation state store (external store pattern for React 18)
+let currentPath = typeof window !== 'undefined' ? window.location.pathname : '/';
+const pathListeners = new Set<() => void>();
+
+function subscribePath(callback: () => void) {
+    pathListeners.add(callback);
+    return () => pathListeners.delete(callback);
+}
+
+function getPath() {
+    return currentPath;
+}
+
+function setPath(newPath: string) {
+    currentPath = newPath;
+    pathListeners.forEach(cb => cb());
+}
+
+// Listen for navigation events
+if (typeof window !== 'undefined') {
+    window.addEventListener('melina:navigation-start', (e: any) => {
+        const to = e.detail?.to || window.location.pathname;
+        setPath(to);
+    });
+
+    window.addEventListener('popstate', () => {
+        setPath(window.location.pathname);
+    });
+}
+
+/**
+ * IslandOrchestrator Component
+ * 
+ * Manages all islands from a single React root using portals.
+ */
+export function IslandOrchestrator() {
+    const [islands, setIslands] = useState<LoadedIsland[]>([]);
+    const [isLoading, setIsLoading] = useState(true);
+
+    // Track current path for re-rendering on navigation
+    const path = useSyncExternalStore(subscribePath, getPath, () => '/');
+
+    // Scan and load islands
+    const scanAndLoadIslands = useCallback(async () => {
+        const placeholders = collectIslandPlaceholders();
+
+        // Load all components in parallel
+        const loaded: LoadedIsland[] = [];
+
+        await Promise.all(
+            placeholders.map(async (config) => {
+                const Component = await loadComponent(config.name);
+                if (Component) {
+                    loaded.push({ ...config, Component });
+                }
+            })
+        );
+
+        // Use flushSync during navigation to ensure view transition captures correct state
+        if (document.startViewTransition) {
+            flushSync(() => setIslands(loaded));
+        } else {
+            setIslands(loaded);
+        }
+
+        setIsLoading(false);
+        console.log(`[Melina] Orchestrator: ${loaded.length} islands active`);
+    }, []);
+
+    // Initial scan
+    useEffect(() => {
+        scanAndLoadIslands();
+    }, [scanAndLoadIslands]);
+
+    // Re-scan on navigation
+    useEffect(() => {
+        const handleNavigated = () => {
+            // Small delay to let DOM update complete
+            requestAnimationFrame(() => {
+                scanAndLoadIslands();
+            });
+        };
+
+        window.addEventListener('melina:navigated', handleNavigated);
+        return () => window.removeEventListener('melina:navigated', handleNavigated);
+    }, [scanAndLoadIslands]);
+
+    // Also re-scan when path changes (for layout islands that conditionally render)
+    useEffect(() => {
+        scanAndLoadIslands();
+    }, [path, scanAndLoadIslands]);
+
+    // Render all islands as portals
+    return (
+        <>
+            {islands.map((island) => (
+                <IslandPortal
+                    key={island.instanceId}
+                    island={island}
+                />
+            ))}
+        </>
+    );
+}
+
+/**
+ * Initialize the Island Orchestrator
+ * Call this from the runtime script to bootstrap the single React root
+ */
+export 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);
+    }
+
+    // Create single React root
+    const root = createRoot(container);
+    root.render(React.createElement(IslandOrchestrator));
+
+    console.log('[Melina] Island Orchestrator initialized (Single Root + Portals)');
+
+    return root;
+}
+
+export default IslandOrchestrator;

package/src/Link.tsx

@@ -0,0 +1,65 @@
+import React from 'react';
+
+export interface LinkProps {
+    href: string;
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+/**
+ * Link Component
+ * 
+ * Uses the Hangar runtime's navigation function (window.melinaNavigate)
+ * for proper View Transitions and island state preservation.
+ */
+export function Link({ href, children, className, style }: LinkProps) {
+    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+        // Allow default behavior for special clicks or external links
+        if (
+            e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0 ||
+            !href.startsWith('/') ||
+            e.currentTarget.hasAttribute('download')
+        ) {
+            return;
+        }
+
+        e.preventDefault();
+
+        // Use Hangar runtime's navigation function
+        if (typeof (window as any).melinaNavigate === 'function') {
+            (window as any).melinaNavigate(href);
+        } else {
+            // Fallback to regular navigation if runtime not loaded
+            console.warn('[Link] melinaNavigate not available, using direct navigation');
+            window.location.href = href;
+        }
+    };
+
+    return (
+        <a href={href} onClick={handleClick} className={className} style={style}>
+            {children}
+        </a>
+    );
+}
+
+// Hook for programmatic navigation
+export function useNavigate() {
+    return (href: string) => {
+        if (typeof (window as any).melinaNavigate === 'function') {
+            (window as any).melinaNavigate(href);
+        } else {
+            window.location.href = href;
+        }
+    };
+}
+
+// Direct navigation function
+export const clientNavigate = (href: string) => {
+    if (typeof (window as any).melinaNavigate === 'function') {
+        (window as any).melinaNavigate(href);
+    } else {
+        window.location.href = href;
+    }
+};
+

package/src/clientRegistry.ts

@@ -0,0 +1,81 @@
+/**
+ * Client Component Registry
+ * 
+ * This registry stores information about client components (islands).
+ * When a Server Component tries to render a Client Component, 
+ * we render an island marker instead of the actual component.
+ */
+
+import React from 'react';
+
+// Registry of client component files
+const clientComponents = new Map<string, Set<string>>();
+
+/**
+ * Register a file as containing client components
+ */
+export function registerClientComponent(filePath: string, exportNames: string[]) {
+    clientComponents.set(filePath, new Set(exportNames));
+}
+
+/**
+ * Check if a file is a client component
+ */
+export function isClientComponent(filePath: string): boolean {
+    return clientComponents.has(filePath);
+}
+
+/**
+ * Create an island wrapper for a client component
+ * This renders the island marker on the server
+ */
+export function createIslandWrapper<P extends object>(
+    componentName: string,
+    _OriginalComponent?: React.ComponentType<P>
+): React.FC<P> {
+    const IslandMarker: React.FC<P> = (props) => {
+        const propsJson = JSON.stringify(props).replace(/"/g, '&quot;');
+
+        // Return the island marker element
+        return React.createElement('div', {
+            'data-melina-island': componentName,
+            'data-props': propsJson,
+            children: React.createElement('div', {
+                style: {
+                    padding: '1rem',
+                    background: '#f0f0f0',
+                    borderRadius: '4px',
+                    opacity: 0.7
+                }
+            }, `Loading ${componentName}...`)
+        });
+    };
+
+    IslandMarker.displayName = `Island(${componentName})`;
+    return IslandMarker;
+}
+
+/**
+ * Transform a client component module for server-side use
+ * Replaces all exports with island wrappers
+ */
+export function wrapClientModule(
+    originalModule: any,
+    componentNames: string[]
+): any {
+    const wrappedModule: any = {};
+
+    for (const name of componentNames) {
+        if (originalModule[name]) {
+            wrappedModule[name] = createIslandWrapper(name, originalModule[name]);
+        }
+    }
+
+    // Handle default export
+    if (originalModule.default) {
+        const defaultName = componentNames[0] || 'Default';
+        wrappedModule.default = createIslandWrapper(defaultName, originalModule.default);
+    }
+
+    return wrappedModule;
+}

package/src/createIsland.tsx

@@ -0,0 +1,121 @@
+import React from 'react';
+
+// Check if we're on the server
+const isServer = typeof window === 'undefined';
+
+// Global manifest of island chunks (populated by server)
+declare global {
+    interface Window {
+        __MELINA_MANIFEST__?: Record<string, string>;
+    }
+}
+
+/**
+ * createIsland - Wrap a Client Component for automatic island hydration
+ * 
+ * This is the bridge between Server and Client components in MelinaJS.
+ * 
+ * Usage:
+ * ```tsx
+ * // components/Counter.tsx
+ * 'use client';
+ * import { createIsland } from '@ments/web';
+ * 
+ * function CounterImpl({ initialCount = 0 }) {
+ *   const [count, setCount] = useState(initialCount);
+ *   return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+ * }
+ * 
+ * // Export the island-wrapped version
+ * export const Counter = createIsland(CounterImpl, 'Counter');
+ * ```
+ * 
+ * On the Server:
+ * - Renders: <div data-melina-island="Counter" data-props='{"initialCount":0}'>...</div>
+ * 
+ * On the Client:
+ * - Hydrates the component with full interactivity
+ */
+export function createIsland<P extends object>(
+    Component: React.ComponentType<P>,
+    name: string
+): React.FC<P> {
+    // Return a wrapper component
+    const IslandWrapper: React.FC<P> = (props) => {
+        if (isServer) {
+            // SERVER: Render the island marker
+            // We also try to render the component for SEO/initial content
+            let innerHtml = '';
+            try {
+                // Attempt to render for progressive enhancement
+                // This might fail if the component uses hooks
+                const ReactDOMServer = require('react-dom/server');
+                innerHtml = ReactDOMServer.renderToString(
+                    React.createElement(Component, props)
+                );
+            } catch (e) {
+                // Component uses hooks - can't SSR, just show placeholder
+                innerHtml = `<div class="melina-island-placeholder">Loading ${name}...</div>`;
+            }
+
+            // Return the island marker with serialized props
+            const propsJson = JSON.stringify(props).replace(/"/g, '&quot;');
+
+            return React.createElement('div', {
+                'data-melina-island': name,
+                'data-props': propsJson,
+                dangerouslySetInnerHTML: { __html: innerHtml }
+            });
+        } else {
+            // CLIENT: Render the actual component
+            return React.createElement(Component, props);
+        }
+    };
+
+    IslandWrapper.displayName = `Island(${name})`;
+    return IslandWrapper;
+}
+
+/**
+ * Island component - Alternative syntax for rendering islands
+ * 
+ * Usage:
+ * ```tsx
+ * // In a Server Component
+ * import { Island } from '@ments/web';
+ * import { Counter } from './components/Counter';
+ * 
+ * export default function Page() {
+ *   return <Island component={Counter} name="Counter" initialCount={5} />;
+ * }
+ * ```
+ */
+export function Island<P extends object>({
+    component: Component,
+    name,
+    ...props
+}: {
+    component: React.ComponentType<P>;
+    name: string;
+} & P): React.ReactElement {
+    const WrappedComponent = createIsland(Component, name);
+    return React.createElement(WrappedComponent, props as P);
+}
+
+/**
+ * ClientOnly - Render children only on the client
+ * 
+ * Useful for components that absolutely cannot be SSR'd
+ */
+export function ClientOnly({
+    children,
+    fallback = null
+}: {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}): React.ReactElement | null {
+    if (isServer) {
+        return fallback as React.ReactElement | null;
+    }
+    return children as React.ReactElement;
+}

package/src/island.ts

@@ -0,0 +1,69 @@
+/**
+ * Island Helper - Automatic SSR detection and island marker rendering
+ * 
+ * This is used internally by client components to automatically render
+ * as island markers when used in Server Components.
+ * 
+ * Usage in a client component:
+ * ```tsx
+ * 'use client';
+ * import { island } from '@ments/web';
+ * 
+ * function SearchBarImpl() {
+ *   const [query, setQuery] = useState('');
+ *   return <input value={query} onChange={e => setQuery(e.target.value)} />;
+ * }
+ * 
+ * // Export the island-wrapped version
+ * export const SearchBar = island(SearchBarImpl, 'SearchBar');
+ * ```
+ * 
+ * Or simpler - just export normally and the framework detects 'use client':
+ * ```tsx
+ * 'use client';
+ * 
+ * export function SearchBar() {
+ *   const [query, setQuery] = useState('');
+ *   return <input value={query} onChange={e => setQuery(e.target.value)} />;
+ * }
+ * ```
+ */
+
+import React from 'react';
+
+const isServer = typeof window === 'undefined';
+
+/**
+ * Wrap a component to auto-detect SSR and render island marker
+ */
+export function island<P extends object>(
+    Component: React.ComponentType<P>,
+    name: string
+): React.FC<P> {
+    const IslandComponent: React.FC<P> = (props) => {
+        if (isServer) {
+            // SERVER: Render EMPTY placeholder - the Hangar portal will fill it
+            // We do NOT SSR the component because:
+            // 1. It may have view-transition-name which would conflict with portal content
+            // 2. The component may use client-only APIs (window.location, etc.)
+            // 3. The portal will render immediately on hydration anyway
+            const propsJson = JSON.stringify(props).replace(/"/g, '&quot;');
+
+            return React.createElement('div', {
+                'data-melina-island': name,
+                'data-props': propsJson,
+                style: { display: 'contents' } // No layout impact
+            });
+            // No children - portal will fill this
+        }
+
+        // CLIENT: Render actual component
+        return React.createElement(Component, props);
+    };
+
+    IslandComponent.displayName = `Island(${name})`;
+    return IslandComponent;
+}
+
+// Re-export for convenience
+export { island as createIsland };