npm - melina - Versions diffs - 1.0.0 - Mend

melina 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/GUIDE.md +538 -0
package/README.md +132 -0
package/bin/melina +95 -0
package/docs/ARCHITECTURE.md +856 -0
package/docs/islands-hydration.png +0 -0
package/package.json +68 -0
package/src/IslandOrchestrator.tsx +259 -0
package/src/Link.tsx +65 -0
package/src/clientRegistry.ts +81 -0
package/src/createIsland.tsx +121 -0
package/src/island.ts +69 -0
package/src/islands.ts +93 -0
package/src/loader.ts +226 -0
package/src/mcp.ts +716 -0
package/src/plugin.ts +236 -0
package/src/preload.ts +124 -0
package/src/preprocess.ts +204 -0
package/src/router.ts +192 -0
package/src/runtime/hangar.ts +399 -0
package/src/runtime.ts +223 -0
package/src/transform.ts +168 -0
package/src/web.ts +1324 -0

package/GUIDE.md ADDED Viewed

@@ -0,0 +1,538 @@
+# Melina.js Developer Guide
+**A lightweight, islands-architecture framework for Bun**
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Core Concepts](#core-concepts)
+3. [Quick Start](#quick-start)
+4. [Server Components](#server-components)
+5. [Client Components (Islands)](#client-components-islands)
+6. [The Router](#the-router)
+7. [Layouts](#layouts)
+8. [State Persistence](#state-persistence)
+9. [Cross-Island Communication](#cross-island-communication)
+10. [Best Practices & Gotchas](#best-practices--gotchas)
+11. [API Reference](#api-reference)
+---
+## Introduction
+Melina.js is a Next.js-compatible framework with a simpler architecture, built specifically for Bun. It uses the **Islands Architecture** where:
+- **Server Components**: Rendered on the server, sent as HTML
+- **Client Components (Islands)**: Interactive React components that hydrate on the client
+### Key Features
+- ✅ File-based routing (Next.js App Router style)
+- ✅ Nested layouts with automatic composition
+- ✅ Islands architecture for optimal performance
+- ✅ SPA-like navigation with partial page swaps
+- ✅ CSS animations that don't reset on navigation
+- ✅ Streaming HTML responses
+---
+## Core Concepts
+### The Two Graphs
+Melina.js separates your app into two distinct "graphs":
+1. **Server Graph** - Layouts and pages that render on the server
+2. **Client Graph** - Interactive components (islands) that run in the browser
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     SERVER (Bun)                            │
+│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐       │
+│  │  layout.tsx │ → │  page.tsx   │ → │   HTML      │ ──────┼──→
+│  └─────────────┘   └─────────────┘   └─────────────┘       │
+└─────────────────────────────────────────────────────────────┘
+                                                      │
+                                                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│                     BROWSER                                 │
+│  ┌────────────────────────────────────────────────────────┐│
+│  │  Static HTML + Islands (hydrated React components)     ││
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
+│  │  │ Counter  │  │ SearchBar│  │ JobTracker│             ││
+│  │  │ (island) │  │ (island) │  │ (island)  │             ││
+│  │  └──────────┘  └──────────┘  └──────────┘             ││
+│  └────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+### Partial Page Swaps
+When you navigate between pages, Melina.js doesn't replace the entire `<body>`. Instead:
+1. Fetches the new page HTML
+2. Finds `#melina-page-content` in both current and new page
+3. Only replaces that container's innerHTML
+4. **Header/footer remain untouched** (preserving state and animations!)
+---
+## Quick Start
+### Installation
+```bash
+bun add @anthropic/melina.js
+```
+### Create Your App Structure
+```
+my-app/
+├── app/
+│   ├── layout.tsx      # Root layout
+│   ├── page.tsx        # Home page (/)
+│   ├── about/
+│   │   └── page.tsx    # About page (/about)
+│   ├── components/
+│   │   ├── Counter.tsx     # 'use client' component
+│   │   └── SearchBar.tsx   # 'use client' component
+│   └── globals.css     # Global styles
+└── package.json
+```
+### Start the Dev Server
+```bash
+bunx melina start
+```
+---
+## Server Components
+Server Components are the default. They render on the server and send HTML to the client.
+```tsx
+// app/page.tsx - Server Component (default)
+export default function HomePage() {
+    const data = await fetchFromDatabase(); // Can use async!
+    return (
+        <div>
+            <h1>Welcome</h1>
+            <p>Data: {data}</p>
+        </div>
+    );
+}
+```
+### What Server Components CAN do:
+- ✅ Async/await directly in the component
+- ✅ Access databases, file systems, environment variables
+- ✅ Import other Server Components
+- ✅ Import Client Components (they'll become islands)
+### What Server Components CANNOT do:
+- ❌ Use `useState`, `useEffect`, or other hooks
+- ❌ Use browser APIs (`window`, `localStorage`)
+- ❌ Handle click events
+---
+## Client Components (Islands)
+Add `'use client'` at the top of your file to make it interactive:
+```tsx
+// app/components/Counter.tsx
+'use client';
+import { useState } from 'react';
+export function Counter({ initialCount = 0 }) {
+    const [count, setCount] = useState(initialCount);
+    return (
+        <button onClick={() => setCount(c => c + 1)}>
+            Count: {count}
+        </button>
+    );
+}
+```
+### Using Islands in Server Components
+Just import and use them:
+```tsx
+// app/page.tsx - Server Component
+import { Counter } from './components/Counter';
+export default function HomePage() {
+    return (
+        <div>
+            <h1>My Page</h1>
+            <Counter initialCount={10} />  {/* Island! */}
+        </div>
+    );
+}
+```
+The framework automatically:
+1. Renders the component on the server (for SEO/initial paint)
+2. Adds `data-melina-island` markers
+3. Hydrates on the client with React
+---
+## The Router
+### File-Based Routes
+```
+app/page.tsx           → /
+app/about/page.tsx     → /about
+app/blog/[id]/page.tsx → /blog/:id (dynamic)
+```
+### The `<Link>` Component
+Use `<Link>` for SPA-style navigation:
+```tsx
+import { Link } from '@anthropic/melina.js';
+export default function Nav() {
+    return (
+        <nav>
+            <Link href="/">Home</Link>
+            <Link href="/about">About</Link>
+        </nav>
+    );
+}
+```
+### Navigation Lifecycle
+When a user clicks a link:
+1. **Fetch**: Router fetches the new page HTML
+2. **Parse**: Parses it into a DOM tree
+3. **Swap**: Only replaces `#melina-page-content`
+4. **Hydrate**: Finds new islands and hydrates them
+**Elements outside `#melina-page-content` persist automatically!**
+### ⚡ What Happens to Islands During Navigation
+Each island is its own **independent React root**. Here's what happens:
+| Island Location | On Navigation | State |
+|-----------------|---------------|-------|
+| In Layout (header/footer) | **Persists** - DOM untouched | ✅ Preserved |
+| In Page | **Destroyed** - innerHTML replaced | ❌ Lost |
+| Same island on new page | New React root created | Fresh state |
+**Example:**
+```
+Navigate from /home to /about:
+┌─ Layout ────────────────────────────────────────┐
+│ <SearchBar />  ← React Root #1 (STAYS)         │
+│                  state preserved! ✅            │
+├─────────────────────────────────────────────────┤
+│ <main id="melina-page-content">                 │
+│   /home: <Counter />  ← Root #2 (DESTROYED) ❌ │
+│   /about: <ContactForm /> ← Root #3 (NEW) 🆕   │
+│ </main>                                         │
+├─────────────────────────────────────────────────┤
+│ <JobTracker />  ← React Root #4 (STAYS)        │
+│                   state preserved! ✅           │
+└─────────────────────────────────────────────────┘
+```
+**Key insight:** Even if both pages use `<Counter />`, they are **different React roots**. State doesn't transfer.
+---
+## Layouts
+### Root Layout
+Every app needs a root `layout.tsx`:
+```tsx
+// app/layout.tsx
+import { SearchBar } from './components/SearchBar';
+import { JobTracker } from './components/JobTracker';
+export default function RootLayout({ children }) {
+    return (
+        <html>
+            <body>
+                <header>
+                    <nav>...</nav>
+                    <SearchBar />  {/* Persists across navigation! */}
+                </header>
+                {/* Only this part swaps on navigation */}
+                <main id="melina-page-content">
+                    {children}
+                </main>
+                <footer>...</footer>
+                <JobTracker />  {/* Persists too! */}
+            </body>
+        </html>
+    );
+}
+```
+### Nested Layouts
+```
+app/
+├── layout.tsx          # Root layout
+└── dashboard/
+    ├── layout.tsx      # Dashboard layout (nested)
+    └── page.tsx        # Dashboard page
+```
+---
+## State Persistence
+### Why Islands Persist
+Islands in the layout (outside `#melina-page-content`) are never destroyed during navigation:
+```tsx
+// This SearchBar's React state survives navigation!
+<header>
+    <SearchBar />
+</header>
+<main id="melina-page-content">
+    {children}  {/* Only this changes */}
+</main>
+```
+### ⚠️ The Props Desynchronization Trade-off
+**This is important!** When navigating:
+1. Server renders new page with new props
+2. Router keeps old layout (to preserve state)
+3. **Old islands keep their OLD props!**
+**Example:**
+```tsx
+// layout.tsx
+<Header activeTab={pathname} />  // ❌ Props won't update!
+```
+If you're on `/home` and navigate to `/about`:
+- Server sends `activeTab="about"`
+- Router throws that away, keeps old Header
+- Header still shows `activeTab="home"` 😱
+### Solution: Use URL State
+Persistent islands should read from URL, not props:
+```tsx
+// ✅ CORRECT - Read from URL
+'use client';
+export function Header() {
+    const [activeTab, setActiveTab] = useState('/');
+    useEffect(() => {
+        // Read current path
+        setActiveTab(window.location.pathname);
+        // Update on navigation
+        const handleNav = () => setActiveTab(window.location.pathname);
+        window.addEventListener('melina:navigated', handleNav);
+        return () => window.removeEventListener('melina:navigated', handleNav);
+    }, []);
+    return (
+        <nav>
+            <Link href="/" className={activeTab === '/' ? 'active' : ''}>Home</Link>
+            <Link href="/about" className={activeTab === '/about' ? 'active' : ''}>About</Link>
+        </nav>
+    );
+}
+```
+---
+## Cross-Island Communication
+Islands are independent React roots. They can't share state directly.
+### Option 1: localStorage + Events
+```tsx
+// Island A: Emit event
+function submitJob(name) {
+    const job = { id: Date.now(), name };
+    localStorage.setItem('lastJob', JSON.stringify(job));
+    window.dispatchEvent(new CustomEvent('job:created', { detail: job }));
+}
+// Island B: Listen for events
+useEffect(() => {
+    const handler = (e) => setJobs(prev => [...prev, e.detail]);
+    window.addEventListener('job:created', handler);
+    return () => window.removeEventListener('job:created', handler);
+}, []);
+```
+### Option 2: Event Bus
+```tsx
+// eventBus.ts
+export const eventBus = {
+    emit(event: string, data: any) {
+        window.dispatchEvent(new CustomEvent(`app:${event}`, { detail: data }));
+    },
+    on(event: string, callback: (data: any) => void) {
+        const handler = (e: CustomEvent) => callback(e.detail);
+        window.addEventListener(`app:${event}`, handler);
+        return () => window.removeEventListener(`app:${event}`, handler);
+    }
+};
+```
+### Option 3: URL State
+For state that should survive refresh:
+```tsx
+// Read from URL
+const searchParams = new URLSearchParams(window.location.search);
+const filter = searchParams.get('filter');
+// Update URL
+function setFilter(value) {
+    const url = new URL(window.location.href);
+    url.searchParams.set('filter', value);
+    window.history.replaceState({}, '', url);
+}
+```
+---
+## Best Practices & Gotchas
+### ✅ Do's
+1. **Keep layouts lean** - Only put truly persistent elements there
+2. **Use URL state for persistent islands** - Don't rely on server props
+3. **Use `#melina-page-content`** - The router needs this container
+4. **Listen for `melina:navigated`** - Keep persistent islands synced
+### ❌ Don'ts
+1. **Don't pass dynamic props to persistent islands** - They won't update
+2. **Don't use global CSS transitions on body** - They'll restart on swap
+3. **Don't forget `display: contents`** - If island wrapper breaks layout
+### Common Patterns
+```tsx
+// ✅ Good: Persistent island reads URL
+function NavTabs() {
+    const [path, setPath] = useState('/');
+    useEffect(() => {
+        setPath(window.location.pathname);
+        window.addEventListener('melina:navigated', () => {
+            setPath(window.location.pathname);
+        });
+    }, []);
+    return <nav>...</nav>;
+}
+// ✅ Good: Cross-page data via localStorage
+function JobTracker() {
+    const [jobs, setJobs] = useState(() => {
+        return JSON.parse(localStorage.getItem('jobs') || '[]');
+    });
+    // ...
+}
+// ❌ Bad: Relying on props in persistent island
+function Header({ activeTab }) {  // Won't update on navigation!
+    return <nav className={activeTab}>...</nav>;
+}
+```
+---
+## API Reference
+### CLI Commands
+```bash
+melina init <project-name>  # Create new project
+melina start                # Start dev server
+```
+### Components
+```tsx
+import { Link } from '@anthropic/melina.js';
+<Link href="/path">Text</Link>
+```
+### Events
+```js
+// Fired after SPA navigation completes
+window.addEventListener('melina:navigated', () => {
+    console.log('Navigation complete!');
+});
+```
+### Server Functions
+```tsx
+import { serve, createAppRouter } from '@anthropic/melina.js';
+serve(createAppRouter({
+    appDir: './app',
+    defaultTitle: 'My App',
+}), { port: 3000 });
+```
+---
+## Troubleshooting
+### "My island doesn't update on navigation"
+You're probably relying on server props. See [Props Desynchronization](#️-the-props-desynchronization-trade-off).
+### "CSS animations restart on navigation"
+Make sure your animated elements are **outside** `#melina-page-content`.
+### "Islands don't communicate"
+Islands are separate React roots. Use localStorage/events. See [Cross-Island Communication](#cross-island-communication).
+---
+## Version History
+- **v0.2.0** - Partial page swap architecture, persistent islands
+- **v0.1.0** - Initial release with file-based routing
+---
+Built with ❤️ using Bun

package/README.md ADDED Viewed

@@ -0,0 +1,132 @@
+# Melina.js 🦊
+**A lightweight, islands-architecture web framework for Bun**
+[![npm version](https://img.shields.io/npm/v/@ments/web)](https://www.npmjs.com/package/@ments/web)
+[![Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1)](https://bun.sh)
+Melina.js is a Next.js-compatible framework with a radically simpler architecture. Built specifically for Bun, it eliminates the need for external bundlers by leveraging Bun's native build APIs.
+## ✨ Features
+- 🏝️ **Islands Architecture** — Only hydrate what needs to be interactive
+- 📁 **File-based Routing** — Next.js App Router style (`app/page.tsx` → `/`)
+- ⚡ **In-Memory Builds** — No `dist/` folder, assets built and served from RAM
+- 🔄 **Partial Page Swaps** — SPA-like navigation without the SPA complexity
+- 🎨 **Tailwind CSS v4** — Built-in support for CSS-first configuration
+- 🌐 **Import Maps** — Browser-native module resolution, no vendor bundles
+## 🚀 Quick Start
+```bash
+# Install
+bun add @ments/web
+# Create app structure
+mkdir -p app/components
+# Create a page
+cat > app/page.tsx << 'EOF'
+export default function Home() {
+  return <h1>Hello Melina! 🦊</h1>;
+}
+EOF
+# Create layout
+cat > app/layout.tsx << 'EOF'
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>
+        <main id="melina-page-content">{children}</main>
+      </body>
+    </html>
+  );
+}
+EOF
+# Start dev server
+bunx melina start
+```
+Open http://localhost:3000 🎉
+## 🏝️ Creating Islands (Client Components)
+```tsx
+// app/components/Counter.tsx
+'use client';
+import { useState } from 'react';
+import { island } from '@ments/web/island';
+function CounterImpl({ initialCount = 0 }) {
+  const [count, setCount] = useState(initialCount);
+  return (
+    <button onClick={() => setCount(c => c + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+export const Counter = island(CounterImpl, 'Counter');
+```
+Use in pages:
+```tsx
+// app/page.tsx
+import { Counter } from './components/Counter';
+export default function Home() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <Counter initialCount={10} />
+    </div>
+  );
+}
+```
+## 📖 Documentation
+- **[Developer Guide](./GUIDE.md)** — Core concepts, best practices, API reference
+- **[Architecture Deep Dive](./docs/ARCHITECTURE.md)** — Technical internals
+## 🔧 CLI
+```bash
+melina init <name>  # Create new project
+melina start        # Start dev server
+```
+## 📦 Project Structure
+```
+my-app/
+├── app/
+│   ├── layout.tsx       # Root layout
+│   ├── page.tsx         # Home page (/)
+│   ├── about/
+│   │   └── page.tsx     # /about
+│   ├── api/
+│   │   └── hello/
+│   │       └── route.ts # API route
+│   ├── components/
+│   │   └── Counter.tsx  # 'use client' component
+│   └── globals.css      # Global styles
+└── package.json
+```
+## 🤔 Why Melina?
+| Traditional SPA | Melina.js |
+|-----------------|-----------|
+| Bundle everything | Islands hydrate selectively |
+| Full page refresh or client routing | Partial page swaps |
+| Complex Webpack/Vite config | Zero config, Bun-native |
+| 100KB+ vendor chunks | Browser-native import maps |
+## License
+MIT © [Mements](https://github.com/mements)