npm - melina - Versions diffs - 1.1.4 → 1.3.0 - Mend

melina 1.1.4 → 1.3.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 (14) hide show

package/GUIDE.md +194 -606
package/README.md +50 -155
package/package.json +3 -11
package/src/IslandOrchestrator.tsx +259 -259
package/src/createIsland.tsx +121 -119
package/src/loader.ts +226 -137
package/src/plugin.ts +46 -93
package/src/router.ts +192 -194
package/src/runtime/hangar.ts +399 -0
package/src/runtime.ts +263 -245
package/src/web.ts +89 -30
package/ARCHITECTURE.md +0 -115
package/CHANGELOG.md +0 -53
package/CONTRIBUTING.md +0 -132

package/GUIDE.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Melina.js Developer Guide
-**A comprehensive guide to building applications with Melina.js**
+**A lightweight, islands-architecture framework for Bun**
 ## Table of Contents
@@ -9,16 +9,12 @@
 3. [Quick Start](#quick-start)
 4. [Server Components](#server-components)
 5. [Client Components (Islands)](#client-components-islands)
-6. [Routing](#routing)
+6. [The Router](#the-router)
 7. [Layouts](#layouts)
 8. [State Persistence](#state-persistence)
-9. [View Transitions](#view-transitions)
-10. [Cross-Island Communication](#cross-island-communication)
-11. [API Routes](#api-routes)
-12. [Styling](#styling)
-13. [Best Practices & Gotchas](#best-practices--gotchas)
-14. [API Reference](#api-reference)
-15. [Troubleshooting](#troubleshooting)
+9. [Cross-Island Communication](#cross-island-communication)
+10. [Best Practices & Gotchas](#best-practices--gotchas)
+11. [API Reference](#api-reference)
 ---
@@ -35,9 +31,7 @@ Melina.js is a Next.js-compatible framework with a simpler architecture, built s
 - ✅ Nested layouts with automatic composition
 - ✅ Islands architecture for optimal performance
 - ✅ SPA-like navigation with partial page swaps
-- ✅ High-fidelity state preservation (Hangar architecture)
-- ✅ Native View Transitions API support
-- ✅ CSS animations that persist across navigation
+- ✅ CSS animations that don't reset on navigation
 - ✅ Streaming HTML responses
 ---
@@ -46,10 +40,10 @@ Melina.js is a Next.js-compatible framework with a simpler architecture, built s
 ### The Two Graphs
-Melina.js separates your app into two distinct execution contexts:
+Melina.js separates your app into two distinct "graphs":
-1. **Server Graph** — Layouts and pages that render on the server (Bun)
-2. **Client Graph** — Interactive components (islands) that run in the browser
+1. **Server Graph** - Layouts and pages that render on the server
+2. **Client Graph** - Interactive components (islands) that run in the browser
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -72,28 +66,9 @@ Melina.js separates your app into two distinct execution contexts:
 └─────────────────────────────────────────────────────────────┘
 ```
-### The Two Zones
-Your layout creates two distinct zones:
-1. **Persistent Zone** — Elements outside `#melina-page-content` (header, footer, sidebars)
-2. **Swappable Zone** — The `#melina-page-content` container
-```tsx
-<body>
-  <header>...</header>        {/* PERSISTENT: Never unmounts */}
-  <main id="melina-page-content">
-    {children}                {/* SWAPPABLE: Replaced on navigation */}
-  </main>
-  <footer>...</footer>        {/* PERSISTENT: Never unmounts */}
-</body>
-```
 ### Partial Page Swaps
-When you navigate between pages, Melina.js doesn't replace the entire page. Instead:
+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
@@ -107,7 +82,7 @@ When you navigate between pages, Melina.js doesn't replace the entire page. Inst
 ### Installation
 ```bash
-bun add melina
+bun add @anthropic/melina.js
 ```
 ### Create Your App Structure
@@ -140,40 +115,34 @@ Server Components are the default. They render on the server and send HTML to th
 ```tsx
 // app/page.tsx - Server Component (default)
-export default async function HomePage() {
-  const data = await fetchFromDatabase(); // Can use async!
-  return (
-    <div>
-      <h1>Welcome</h1>
-      <p>Data: {data}</p>
-    </div>
-  );
+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
+### 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
+### What Server Components CANNOT do:
 - ❌ Use `useState`, `useEffect`, or other hooks
 - ❌ Use browser APIs (`window`, `localStorage`)
-- ❌ Handle click events or other interactive behaviors
+- ❌ Handle click events
 ---
 ## Client Components (Islands)
-Add `'use client'` at the top of your file to make it interactive. Melina automatically handles the transformation!
-### Auto-Wrapping (Default)
-Just export your component normally — Melina transforms it during SSR:
+Add `'use client'` at the top of your file to make it interactive:
 ```tsx
 // app/components/Counter.tsx
@@ -182,39 +151,14 @@ Just export your component normally — Melina transforms it during SSR:
 import { useState } from 'react';
 export function Counter({ initialCount = 0 }) {
-  const [count, setCount] = useState(initialCount);
-  return (
-    <button onClick={() => setCount(c => c + 1)}>
-      Count: {count}
-    </button>
-  );
-}
-```
-That's it! No extra imports or wrappers required. The framework:
-1. Detects `'use client'` directive
-2. Automatically transforms exports to island wrappers during SSR
-3. Renders the actual component on the client
-### Manual Wrapping (Advanced)
-For more control, you can manually wrap with `island()`:
-```tsx
-'use client';
-import { useState } from 'react';
-import { island } from 'melina/island';
-function CounterImpl({ initialCount = 0 }) {
-  const [count, setCount] = useState(initialCount);
-  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
+    const [count, setCount] = useState(initialCount);
+    return (
+        <button onClick={() => setCount(c => c + 1)}>
+            Count: {count}
+        </button>
+    );
 }
-// Explicit island wrapper
-export const Counter = island(CounterImpl, 'Counter');
 ```
 ### Using Islands in Server Components
@@ -226,32 +170,30 @@ Just import and use them:
 import { Counter } from './components/Counter';
 export default function HomePage() {
-  return (
-    <div>
-      <h1>My Page</h1>
-      <Counter initialCount={10} />  {/* Island! */}
-    </div>
-  );
+    return (
+        <div>
+            <h1>My Page</h1>
+            <Counter initialCount={10} />  {/* Island! */}
+        </div>
+    );
 }
 ```
 The framework automatically:
-1. Renders an island placeholder on the server (for SEO/initial paint)
-2. Adds `data-melina-island` markers with serialized props
+1. Renders the component on the server (for SEO/initial paint)
+2. Adds `data-melina-island` markers
 3. Hydrates on the client with React
 ---
-## Routing
+## The Router
 ### File-Based Routes
 ```
 app/page.tsx           → /
 app/about/page.tsx     → /about
-app/blog/[slug]/page.tsx → /blog/:slug (dynamic)
-app/docs/[...path]/page.tsx → /docs/* (catch-all)
+app/blog/[id]/page.tsx → /blog/:id (dynamic)
 ```
 ### The `<Link>` Component
@@ -259,37 +201,58 @@ app/docs/[...path]/page.tsx → /docs/* (catch-all)
 Use `<Link>` for SPA-style navigation:
 ```tsx
-import { Link } from 'melina/Link';
+import { Link } from '@anthropic/melina.js';
 export default function Nav() {
-  return (
-    <nav>
-      <Link href="/">Home</Link>
-      <Link href="/about">About</Link>
-      <Link href="/blog/my-post">Blog Post</Link>
-    </nav>
-  );
+    return (
+        <nav>
+            <Link href="/">Home</Link>
+            <Link href="/about">About</Link>
+        </nav>
+    );
 }
 ```
-### Route Precedence
-| Priority | Type | Example | Description |
-|----------|------|---------|-------------|
-| 1 | Static | `/blog/my-post` | Exact match |
-| 2 | Dynamic | `/blog/[slug]` | Single segment |
-| 3 | Catch-all | `/blog/[...slug]` | Multiple segments |
 ### 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. **Transition**: Triggers View Transition (if supported)
-4. **Swap**: Only replaces `#melina-page-content`
-5. **Hydrate**: Finds and hydrates new islands
-6. **Event**: Dispatches `melina:navigated`
+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.
 ---
@@ -305,24 +268,24 @@ 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>
-        {/* CRITICAL: Only this part swaps on navigation */}
-        <main id="melina-page-content">
-          {children}
-        </main>
-        <footer>...</footer>
-        <JobTracker />  {/* Persists too! */}
-      </body>
-    </html>
-  );
+    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>
+    );
 }
 ```
@@ -336,20 +299,6 @@ app/
     └── page.tsx        # Dashboard page
 ```
-```tsx
-// app/dashboard/layout.tsx
-export default function DashboardLayout({ children }) {
-  return (
-    <div className="dashboard">
-      <Sidebar />
-      <div id="melina-page-content">
-        {children}
-      </div>
-    </div>
-  );
-}
-```
 ---
 ## State Persistence
@@ -359,25 +308,25 @@ export default function DashboardLayout({ children }) {
 Islands in the layout (outside `#melina-page-content`) are never destroyed during navigation:
 ```tsx
+// This SearchBar's React state survives navigation!
 <header>
-  <SearchBar />  {/* React state survives navigation */}
+    <SearchBar />
 </header>
 <main id="melina-page-content">
-  {children}  {/* Only this changes */}
+    {children}  {/* Only this changes */}
 </main>
 ```
 ### ⚠️ The Props Desynchronization Trade-off
-**Important!** When navigating:
+**This is important!** When navigating:
 1. Server renders new page with new props
-2. Router keeps existing layout (to preserve state)
-3. **Persistent islands keep their OLD 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!
@@ -385,10 +334,10 @@ Islands in the layout (outside `#melina-page-content`) are never destroyed durin
 If you're on `/home` and navigate to `/about`:
 - Server sends `activeTab="about"`
-- Router discards that, keeps old Header
+- Router throws that away, keeps old Header
 - Header still shows `activeTab="home"` 😱
-### ✅ Solution: Read from URL
+### Solution: Use URL State
 Persistent islands should read from URL, not props:
@@ -396,165 +345,25 @@ Persistent islands should read from URL, not props:
 // ✅ CORRECT - Read from URL
 'use client';
-import { useState, useEffect } from 'react';
-import { island } from 'melina/island';
-function HeaderImpl() {
-  const [activeTab, setActiveTab] = useState('/');
-  useEffect(() => {
-    // Read current path
-    setActiveTab(window.location.pathname);
+export function Header() {
+    const [activeTab, setActiveTab] = useState('/');
-    // 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>
-  );
-}
-export const Header = island(HeaderImpl, 'Header');
-```
-### Persisting State for Page Islands
-Page islands (inside `#melina-page-content`) lose state on navigation. Options:
-**Option 1: Move to Layout**
-```tsx
-// If the island should persist, put it in the layout
-<JobTracker />  // In layout = always persists
-```
-**Option 2: Use localStorage**
-```tsx
-function CounterImpl({ initialCount = 0 }) {
-  const [count, setCount] = useState(() => {
-    const saved = localStorage.getItem('counter');
-    return saved ? parseInt(saved) : initialCount;
-  });
-  useEffect(() => {
-    localStorage.setItem('counter', String(count));
-  }, [count]);
-  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
-}
-```
-**Option 3: Use URL State**
-```tsx
-function FilterPanel() {
-  const [filter, setFilter] = useState(() => {
-    return new URLSearchParams(window.location.search).get('filter') || 'all';
-  });
-  const updateFilter = (newFilter) => {
-    const url = new URL(window.location.href);
-    url.searchParams.set('filter', newFilter);
-    window.history.replaceState({}, '', url);
-    setFilter(newFilter);
-  };
-  return (
-    <select value={filter} onChange={e => updateFilter(e.target.value)}>
-      <option value="all">All</option>
-      <option value="active">Active</option>
-    </select>
-  );
-}
-```
----
-## View Transitions
-Melina.js leverages the browser-native [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for smooth, morphing animations between pages.
-### Basic Setup
-```css
-/* app/globals.css */
-/* Give elements a shared identity */
-.album-cover {
-  view-transition-name: album-cover;
-}
-/* Customize the transition */
-::view-transition-old(album-cover),
-::view-transition-new(album-cover) {
-  animation-duration: 0.3s;
-  animation-timing-function: ease-in-out;
-}
-```
-### Dynamic Transition Names
-Use inline styles for dynamic transition names:
-```tsx
-// List view
-<div
-  className="album-thumbnail"
-  style={{ viewTransitionName: `album-${album.id}` }}
->
-  <img src={album.cover} />
-</div>
-// Detail view
-<div
-  className="album-hero"
-  style={{ viewTransitionName: `album-${params.id}` }}
->
-  <img src={album.cover} />
-</div>
-```
-### Single-Instance Morphing
-Layout-level islands can transform between states:
-```tsx
-// MusicPlayer that morphs between mini and expanded
-function MusicPlayerImpl() {
-  const [path, setPath] = useState('/');
-  useEffect(() => {
-    setPath(window.location.pathname);
-    const handler = () => setPath(window.location.pathname);
-    window.addEventListener('melina:navigated', handler);
-    return () => window.removeEventListener('melina:navigated', handler);
-  }, []);
-  const isExpanded = path.startsWith('/album/');
-  return (
-    <div
-      className={isExpanded ? 'player-expanded' : 'player-mini'}
-      style={{ viewTransitionName: 'music-player' }}
-    >
-      {isExpanded ? <ExpandedView /> : <MiniView />}
-    </div>
-  );
-}
-```
-```css
-::view-transition-old(music-player),
-::view-transition-new(music-player) {
-  animation-duration: 0.4s;
+    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>
+    );
 }
 ```
@@ -562,212 +371,103 @@ function MusicPlayerImpl() {
 ## Cross-Island Communication
-Islands are independent React roots. They can't share state directly via React context.
+Islands are independent React roots. They can't share state directly.
-### Option 1: Custom Events
+### Option 1: localStorage + Events
 ```tsx
 // Island A: Emit event
 function submitJob(name) {
-  const job = { id: Date.now(), name };
-  window.dispatchEvent(new CustomEvent('job:created', { detail: job }));
+    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);
+    const handler = (e) => setJobs(prev => [...prev, e.detail]);
+    window.addEventListener('job:created', handler);
+    return () => window.removeEventListener('job:created', handler);
 }, []);
 ```
 ### Option 2: Event Bus
 ```tsx
-// lib/eventBus.ts
+// 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);
-  }
+    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);
+    }
 };
-// Usage
-eventBus.emit('user:login', { id: 1, name: 'Alice' });
-eventBus.on('user:login', (user) => console.log('Logged in:', user));
 ```
-### Option 3: localStorage + Storage Events
+### Option 3: URL State
-```tsx
-// Island A: Write
-localStorage.setItem('user', JSON.stringify(user));
-window.dispatchEvent(new Event('storage'));
-// Island B: Listen
-const [user, setUser] = useState(() =>
-  JSON.parse(localStorage.getItem('user') || 'null')
-);
-useEffect(() => {
-  const handler = () => {
-    setUser(JSON.parse(localStorage.getItem('user') || 'null'));
-  };
-  window.addEventListener('storage', handler);
-  return () => window.removeEventListener('storage', handler);
-}, []);
-```
----
-## API Routes
-### Basic API Route
-```tsx
-// app/api/hello/route.ts
-export async function GET(req: Request) {
-  return Response.json({
-    message: 'Hello from API!',
-    serverTime: new Date().toISOString()
-  });
-}
-export async function POST(req: Request) {
-  const body = await req.json();
-  // Process data...
-  return Response.json({ success: true });
-}
-```
-### Full Server Capabilities
-```tsx
-// app/api/data/route.ts
-import { readFileSync } from 'fs';
-import { db } from '../../../lib/database';
-export async function GET() {
-  // Read from file system
-  const config = readFileSync('./config.json', 'utf-8');
-  // Query database
-  const users = await db.query('SELECT * FROM users');
-  return Response.json({ config: JSON.parse(config), users });
-}
-```
-### Dynamic API Routes
-```tsx
-// app/api/users/[id]/route.ts
-export async function GET(req: Request, { params }) {
-  const user = await db.findUser(params.id);
-  if (!user) {
-    return Response.json({ error: 'Not found' }, { status: 404 });
-  }
-  return Response.json(user);
-}
-```
----
-## Styling
-### Global CSS
+For state that should survive refresh:
 ```tsx
-// app/layout.tsx
-import './globals.css';
-export default function Layout({ children }) {
-  return (
-    <html>
-      <head>
-        {/* CSS is automatically injected */}
-      </head>
-      <body>...</body>
-    </html>
-  );
-}
-```
-### Tailwind CSS v4
+// Read from URL
+const searchParams = new URLSearchParams(window.location.search);
+const filter = searchParams.get('filter');
-Melina.js has built-in Tailwind v4 support with CSS-first configuration:
-```css
-/* app/globals.css */
-@import "tailwindcss";
-/* Custom theme via CSS */
-@theme {
-  --color-primary: #667eea;
-  --color-accent: #764ba2;
+// Update URL
+function setFilter(value) {
+    const url = new URL(window.location.href);
+    url.searchParams.set('filter', value);
+    window.history.replaceState({}, '', url);
 }
 ```
-No `tailwind.config.js` needed!
 ---
 ## 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
-5. **Use `island()` wrapper** — Required for client components
+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 use React context across islands** — They're separate roots
-4. **Don't forget cleanup** — Remove event listeners in useEffect cleanup
+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 NavTabsImpl() {
-  const [path, setPath] = useState('/');
-  useEffect(() => {
-    setPath(window.location.pathname);
-    const handler = () => setPath(window.location.pathname);
-    window.addEventListener('melina:navigated', handler);
-    return () => window.removeEventListener('melina:navigated', handler);
-  }, []);
-  return <nav>...</nav>;
+function NavTabs() {
+    const [path, setPath] = useState('/');
+    useEffect(() => {
+        setPath(window.location.pathname);
+        window.addEventListener('melina:navigated', () => {
+            setPath(window.location.pathname);
+        });
+    }, []);
+    return <nav>...</nav>;
 }
-export const NavTabs = island(NavTabsImpl, 'NavTabs');
 // ✅ Good: Cross-page data via localStorage
-function JobTrackerImpl() {
-  const [jobs, setJobs] = useState(() => {
-    return JSON.parse(localStorage.getItem('jobs') || '[]');
-  });
-  // ...
+function JobTracker() {
+    const [jobs, setJobs] = useState(() => {
+        return JSON.parse(localStorage.getItem('jobs') || '[]');
+    });
+    // ...
 }
-export const JobTracker = island(JobTrackerImpl, 'JobTracker');
 // ❌ Bad: Relying on props in persistent island
-function HeaderImpl({ activeTab }) {  // Won't update on navigation!
-  return <nav className={activeTab}>...</nav>;
+function Header({ activeTab }) {  // Won't update on navigation!
+    return <nav className={activeTab}>...</nav>;
 }
 ```
@@ -782,118 +482,32 @@ melina init <project-name>  # Create new project
 melina start                # Start dev server
 ```
-### Core Imports
-```tsx
-// Programmatic API
-import { start, createApp, serve, createAppRouter } from 'melina';
-// Navigation component
-import { Link } from 'melina/Link';
-// Manual island wrapper (optional - auto-wrapping is default)
-import { island } from 'melina/island';
-```
-### Programmatic API
-#### `start(options?)` — Quickstart Function
-The easiest way to run Melina from your own script:
+### Components
 ```tsx
-import { start } from 'melina';
+import { Link } from '@anthropic/melina.js';
-// Basic usage
-await start();
-// With options
-await start({
-  appDir: './app',           // Default: './app'
-  port: 8080,                // Default: 3000
-  defaultTitle: 'My App',    // Default: 'Melina App'
-  globalCss: './app/styles.css',
-});
-```
-#### `createAppRouter(options)` — Router Factory
-Creates a request handler with file-based routing:
-```tsx
-import { serve, createAppRouter } from 'melina';
-const router = createAppRouter({
-  appDir: './app',
-  defaultTitle: 'My App',
-  globalCss: './app/globals.css',
-});
-// Use with custom middleware
-serve(async (req, measure) => {
-  // Custom logic before routing
-  if (req.url.endsWith('/health')) {
-    return new Response('OK');
-  }
-  return router(req, measure);
-}, { port: 3000 });
-```
-#### `createApp(options)` — Alias for `createAppRouter`
-```tsx
-import { createApp } from 'melina';
-const app = createApp({ appDir: './app' });
+<Link href="/path">Text</Link>
 ```
-#### `serve(handler, options)` — Low-Level Server
+### Events
-```tsx
-import { serve } from 'melina';
-serve(async (req, measure) => {
-  // Your custom handler
-  return new Response('Hello');
-}, {
-  port: 3000,
-  // Or unix socket for production
-  unix: '/tmp/melina.sock'
+```js
+// Fired after SPA navigation completes
+window.addEventListener('melina:navigated', () => {
+    console.log('Navigation complete!');
 });
 ```
-### The `island()` Function
-Manual island wrapper (usually not needed with auto-wrapping):
+### Server Functions
 ```tsx
-import { island } from 'melina/island';
+import { serve, createAppRouter } from '@anthropic/melina.js';
-// Basic usage
-export const Counter = island(CounterImpl, 'Counter');
-```
-### The `<Link>` Component
-```tsx
-import { Link } from 'melina/Link';
-<Link href="/path">Text</Link>
-<Link href="/path" className="nav-link">Styled Link</Link>
-```
-### Navigation Events
-```javascript
-// Fired when navigation starts
-window.addEventListener('melina:navigation-start', (e) => {
-  console.log('From:', e.detail.from, 'To:', e.detail.to);
-});
-// Fired after SPA navigation completes
-window.addEventListener('melina:navigated', () => {
-  console.log('Navigation complete!');
-});
+serve(createAppRouter({
+    appDir: './app',
+    defaultTitle: 'My App',
+}), { port: 3000 });
 ```
 ---
@@ -904,8 +518,6 @@ window.addEventListener('melina:navigated', () => {
 You're probably relying on server props. See [Props Desynchronization](#️-the-props-desynchronization-trade-off).
-**Solution:** Read from URL + listen for `melina:navigated`
 ### "CSS animations restart on navigation"
 Make sure your animated elements are **outside** `#melina-page-content`.
@@ -914,37 +526,13 @@ Make sure your animated elements are **outside** `#melina-page-content`.
 Islands are separate React roots. Use localStorage/events. See [Cross-Island Communication](#cross-island-communication).
-### "View Transitions aren't working"
-1. Ensure browser supports View Transitions API (Chrome 111+)
-2. Check that `view-transition-name` values match between pages
-3. Ensure no duplicate `view-transition-name` on the same page
-### "EADDRINUSE error on restart"
-The Unix socket wasn't cleaned up. Melina handles this automatically, but if it persists:
-```bash
-rm /tmp/melina.sock
-```
-### "Missing 'app' directory"
-Make sure you have an `app/` directory with at least a `page.tsx` or `layout.tsx`:
-```bash
-mkdir -p app
-echo 'export default () => <h1>Hello!</h1>;' > app/page.tsx
-```
 ---
 ## Version History
-- **v1.0.0** — Hangar architecture, View Transitions, high-fidelity persistence
-- **v0.2.0** — Partial page swap architecture, persistent islands
-- **v0.1.0** — Initial release with file-based routing
+- **v0.2.0** - Partial page swap architecture, persistent islands
+- **v0.1.0** - Initial release with file-based routing
 ---
-Built with ❤️ using [Bun](https://bun.sh) 🧅
+Built with ❤️ using Bun