@netrojs/fnetro 0.2.0 → 0.2.1

package/README.md

@@ -1,35 +1,50 @@
-# @netrojs/fnetro
+# FNetro
 
-> Full-stack [Hono](https://hono.dev) framework powered by **SolidJS v1.9+** — SSR, SPA, SEO, server & client middleware, TypeScript-first.
+> Full-stack [Hono](https://hono.dev) framework powered by **SolidJS v1.9+** —
+> SSR · SPA · SEO · server & client middleware · multi-runtime · TypeScript-first.
 
-[![npm version](https://img.shields.io/npm/v/@netrojs/fnetro)](https://www.npmjs.com/package/@netrojs/fnetro)
+[![CI](https://github.com/netrosolutions/fnetro/actions/workflows/ci.yml/badge.svg)](https://github.com/netrosolutions/fnetro/actions/workflows/ci.yml)
+[![npm @netrojs/fnetro](https://img.shields.io/npm/v/@netrojs/fnetro?label=%40netrojs%2Ffnetro)](https://www.npmjs.com/package/@netrojs/fnetro)
+[![npm create-fnetro](https://img.shields.io/npm/v/@netrojs/create-fnetro?label=%40netrojs%2Fcreate-fnetro)](https://www.npmjs.com/package/@netrojs/create-fnetro)
 [![license](https://img.shields.io/npm/l/@netrojs/fnetro)](./LICENSE)
 
 ---
 
 ## Table of contents
 
-1. [Quick start](#quick-start)
-2. [Installation](#installation)
-3. [Project structure](#project-structure)
-4. [Core concepts](#core-concepts)
-5. [Routing](#routing)
+1. [Packages](#packages)
+2. [Quick start](#quick-start)
+3. [How it works](#how-it-works)
+4. [Routing](#routing)
    - [definePage](#definepage)
    - [defineGroup](#definegroup)
    - [defineLayout](#definelayout)
    - [defineApiRoute](#defineapiroute)
-6. [Loaders](#loaders)
-7. [SEO](#seo)
-8. [Middleware](#middleware)
+5. [Loaders](#loaders)
+6. [SEO](#seo)
+7. [Middleware](#middleware)
    - [Server middleware](#server-middleware)
    - [Client middleware](#client-middleware)
-9. [SolidJS reactivity](#solidjs-reactivity)
-10. [Navigation](#navigation)
-11. [Asset handling](#asset-handling)
-12. [Multi-runtime `serve()`](#multi-runtime-serve)
-13. [Vite plugin](#vite-plugin)
+8. [SolidJS reactivity](#solidjs-reactivity)
+9. [Navigation](#navigation)
+10. [Asset handling](#asset-handling)
+11. [Multi-runtime serve()](#multi-runtime-serve)
+12. [Vite plugin](#vite-plugin)
+13. [Project structure](#project-structure)
 14. [TypeScript](#typescript)
-15. [API reference](#api-reference)
+15. [create-fnetro CLI](#create-fnetro-cli)
+16. [API reference](#api-reference)
+17. [Monorepo development](#monorepo-development)
+18. [Publishing & releases](#publishing--releases)
+
+---
+
+## Packages
+
+| Package | Description |
+|---|---|
+| [`@netrojs/fnetro`](./packages/fnetro) | Core framework — SSR renderer, SPA routing, SEO, middleware, Vite plugin |
+| [`@netrojs/create-fnetro`](./packages/create-fnetro) | Interactive project scaffolding CLI |
 
 ---
 
@@ -42,76 +57,43 @@ npm install
 npm run dev
 ```
 
----
-
-## Installation
+Or with other package managers:
 
 ```bash
-# npm
-npm install @netrojs/fnetro solid-js hono
-
-# Dev deps (build toolchain)
-npm install -D vite vite-plugin-solid @hono/vite-dev-server typescript
-```
-
-For Node.js runtime add:
-```bash
-npm install -D @hono/node-server
-```
-
-### Peer dependencies
-
-| Package | Version | Required? |
-|---|---|---|
-| `solid-js` | `>=1.9.11` | ✅ Always |
-| `hono` | `>=4.0.0` | ✅ Always |
-| `vite` | `>=5.0.0` | Build only |
-| `vite-plugin-solid` | `>=2.11.11` | Build only |
-
----
-
-## Project structure
-
-```
-my-app/
-├── app.ts              # Shared FNetro app — used by dev server and server.ts
-├── server.ts           # Production server entry — calls serve()
-├── client.ts           # Browser entry — calls boot()
-├── app/
-│   ├── layouts.tsx     # defineLayout() — shared nav/footer shell
-│   └── routes/
-│       ├── home.tsx    # definePage({ path: '/' })
-│       ├── about.tsx   # definePage({ path: '/about' })
-│       └── api.ts      # defineApiRoute('/api', ...)
-├── public/
-│   └── style.css       # Static assets served at /
-├── vite.config.ts
-└── tsconfig.json
+pnpm create @netrojs/fnetro@latest my-app
+bun create @netrojs/fnetro my-app
+deno run -A npm:create-fnetro my-app
 ```
 
 ---
 
-## Core concepts
-
-FNetro is built on three files:
-
-| File | Purpose |
-|---|---|
-| `@netrojs/fnetro` (core) | Route builders, SEO types, path matching utilities |
-| `@netrojs/fnetro/server` | Hono app factory, SSR renderer, Vite plugin, `serve()` |
-| `@netrojs/fnetro/client` | SolidJS hydration, SPA routing, client middleware |
-
-**Data flow:**
-
-```
-Request
-  → Hono middleware
-  → Route match
-  → Loader runs (server-side)
-  → SolidJS SSR renders HTML
-  → HTML + state injected into shell
-  → Client hydrates
-  → SPA navigation takes over (no full page reloads)
+## How it works
+
+```
+Browser                              Server (Hono)
+────────────────────────────────     ─────────────────────────────────────
+                                     Global middleware
+                                     ↓
+                                     Route match ([id], [...slug], *)
+                                     ↓
+                                     Route middleware
+                                     ↓
+                                     Loader (async, type-safe)
+                                     ↓
+                         SSR ──────  SolidJS renderToStringAsync()
+                          │          ↓
+HTML + hydration script ◄─┘          SEO <head> injection
+                                     ↓
+                                     HTML shell (state + params + seo embedded)
+                                     ↓
+                         SPA ──────  JSON payload (state + seo only)
+                          │
+hydrate() ◄───────────────┘
+↓
+Client middleware chain
+↓
+SolidJS reactive component tree
+(module-level signals persist across navigations)
 ```
 
 ---
@@ -120,77 +102,68 @@ Request
 
 ### `definePage`
 
-Define a page with a path, optional loader, optional SEO, and a SolidJS component.
+Define a route with an optional SSR loader, SEO config, and a SolidJS component.
 
 ```tsx
-// app/routes/home.tsx
+// app/routes/post.tsx
 import { definePage } from '@netrojs/fnetro'
 
 export default definePage({
-  path: '/',
+  path: '/posts/[slug]',
 
-  // Optional server-side data loader
   loader: async (c) => {
-    const data = await fetchSomeData()
-    return { items: data }
+    const slug = c.req.param('slug')
+    const post = await db.posts.findBySlug(slug)
+    if (!post) return c.notFound()
+    return { post }
   },
 
-  // Optional SEO (see § SEO)
-  seo: {
-    title:       'Home — My App',
-    description: 'Welcome to my app.',
-  },
+  seo: (data) => ({
+    title:       `${data.post.title} — My Blog`,
+    description: data.post.excerpt,
+    ogImage:     data.post.coverUrl,
+    twitterCard: 'summary_large_image',
+  }),
 
-  // SolidJS component — receives loader data + url + params
-  Page({ items, url, params }) {
-    return (
-      <ul>
-        {items.map(item => <li>{item.name}</li>)}
-      </ul>
-    )
+  Page({ post, url, params }) {
+    return <article>{post.title}</article>
   },
 })
 ```
 
-**Dynamic segments** use `[param]` syntax:
-
-```ts
-// matches /posts/hello-world → params.slug = 'hello-world'
-definePage({ path: '/posts/[slug]', ... })
+**Path patterns:**
 
-// catch-all: matches /files/a/b/c → params.rest = 'a/b/c'
-definePage({ path: '/files/[...rest]', ... })
-```
+| Pattern | Matches | `params` |
+|---|---|---|
+| `/posts/[slug]` | `/posts/hello-world` | `{ slug: 'hello-world' }` |
+| `/files/[...rest]` | `/files/a/b/c` | `{ rest: 'a/b/c' }` |
+| `/shop/*` | `/shop/anything` | *(positional)* |
 
 ---
 
 ### `defineGroup`
 
-Group routes under a shared prefix, layout, and middleware.
+Group routes under a shared URL prefix, layout, and middleware.
 
 ```ts
 import { defineGroup } from '@netrojs/fnetro'
-import { requireAuth } from './middleware/auth'
-import { AdminLayout } from './layouts'
-import dashboard from './routes/admin/dashboard'
-import users from './routes/admin/users'
 
 export const adminGroup = defineGroup({
   prefix:     '/admin',
-  layout:     AdminLayout,
-  middleware: [requireAuth],
-  routes:     [dashboard, users],
+  layout:     AdminLayout,   // optional — overrides app default
+  middleware: [requireAuth, auditLog],
+  routes:     [dashboard, users, settings],
 })
 ```
 
-Groups can be nested:
+Groups nest arbitrarily:
 
 ```ts
 defineGroup({
   prefix: '/api',
   routes: [
-    defineGroup({ prefix: '/v1', routes: [v1Routes] }),
-    defineGroup({ prefix: '/v2', routes: [v2Routes] }),
+    defineGroup({ prefix: '/v1', routes: [v1] }),
+    defineGroup({ prefix: '/v2', routes: [v2] }),
   ],
 })
 ```
@@ -199,18 +172,18 @@ defineGroup({
 
 ### `defineLayout`
 
-Create a shared layout component that wraps page content.
+Wrap every page with a shared shell (nav, footer, providers).
 
 ```tsx
 import { defineLayout } from '@netrojs/fnetro'
 import { createSignal } from 'solid-js'
 
-const [mobileOpen, setMobileOpen] = createSignal(false)
+// Module-level signal — persists across SPA navigations
+const [sidebarOpen, setSidebarOpen] = createSignal(false)
 
 export const RootLayout = defineLayout(({ children, url, params }) => (
   <div class="app">
-    <nav class="navbar">
-      <a href="/" class="logo">My App</a>
+    <nav>
       <a href="/" class={url === '/' ? 'active' : ''}>Home</a>
       <a href="/about" class={url === '/about' ? 'active' : ''}>About</a>
     </nav>
@@ -220,21 +193,21 @@ export const RootLayout = defineLayout(({ children, url, params }) => (
 ))
 ```
 
-**Per-page layout override:**
+**Per-page override:**
 
 ```ts
-// Use a different layout for this page
+// Use a different layout
 definePage({ path: '/landing', layout: LandingLayout, Page: ... })
 
-// No layout for this page
-definePage({ path: '/embed', layout: false, Page: ... })
+// Disable layout entirely
+definePage({ path: '/embed',   layout: false,         Page: ... })
 ```
 
 ---
 
 ### `defineApiRoute`
 
-Mount raw Hono routes at a path. Full Hono API available.
+Mount raw Hono sub-routes. Full Hono API — REST, RPC, WebSocket, streaming.
 
 ```ts
 import { defineApiRoute } from '@netrojs/fnetro'
@@ -242,28 +215,23 @@ import { zValidator } from '@hono/zod-validator'
 import { z } from 'zod'
 
 export const api = defineApiRoute('/api', (app) => {
-  app.get('/health', (c) => c.json({ status: 'ok', ts: Date.now() }))
+  app.get('/health', (c) =>
+    c.json({ status: 'ok', ts: Date.now() }),
+  )
 
   app.get('/users/:id', async (c) => {
     const user = await db.users.find(c.req.param('id'))
-    if (!user) return c.json({ error: 'Not found' }, 404)
-    return c.json(user)
+    return user ? c.json(user) : c.json({ error: 'not found' }, 404)
   })
 
   app.post(
     '/items',
     zValidator('json', z.object({ name: z.string().min(1) })),
     async (c) => {
-      const body = c.req.valid('json')
-      const item = await db.items.create(body)
+      const item = await db.items.create(c.req.valid('json'))
       return c.json(item, 201)
     },
   )
-
-  // WebSocket example
-  app.get('/ws', upgradeWebSocket(() => ({
-    onMessage(e, ws) { ws.send(`Echo: ${e.data}`) },
-  })))
 })
 ```
 
@@ -271,45 +239,37 @@ export const api = defineApiRoute('/api', (app) => {
 
 ## Loaders
 
-Loaders run **server-side on every request** (both SSR and SPA navigation).
-The return value is serialized to JSON and passed to the Page component as props.
+Loaders run **on the server on every request** — both initial SSR and SPA navigations. The return value is JSON-serialised and injected as page props.
 
 ```ts
 definePage({
-  path: '/posts/[slug]',
+  path: '/dashboard',
 
   loader: async (c) => {
-    // c is a Hono Context — access headers, cookies, query params, etc.
-    const slug  = c.req.param('slug')
-    const token = getCookie(c, 'session')
-    const post  = await db.posts.findBySlug(slug)
+    // Full Hono Context — headers, cookies, query params, env bindings
+    const session = getCookie(c, 'session')
+    if (!session) return c.redirect('/login')
 
-    if (!post) {
-      // Return a 404 response from the loader
-      return c.notFound()
-    }
-
-    return { post }
+    const user  = await auth.verify(session)
+    const stats = await db.stats.forUser(user.id)
+    return { user, stats }
   },
 
-  Page({ post }) { ... },
+  Page({ user, stats }) { /* typed */ },
 })
 ```
 
 **Type-safe loaders:**
 
 ```ts
-interface PostData {
-  post:   Post
-  author: User
-}
+interface DashboardData { user: User; stats: Stats }
 
-definePage<PostData>({
-  loader: async (c): Promise<PostData> => ({
-    post:   await db.posts.find(c.req.param('id')),
-    author: await db.users.find(post.authorId),
+definePage<DashboardData>({
+  loader: async (c): Promise<DashboardData> => ({
+    user:  await getUser(c),
+    stats: await getStats(c),
   }),
-  Page({ post, author }) { /* fully typed */ },
+  Page({ user, stats }) { /* DashboardData & { url, params } */ },
 })
 ```
 
@@ -318,10 +278,10 @@ definePage<PostData>({
 ## SEO
 
 Every page can declare `seo` as a **static object** or a **function of loader data**.
-App-level `seo` provides defaults; page-level values override them.
+App-level `seo` provides global defaults; page-level values override them.
 
 ```ts
-// app.ts — global defaults
+// app.ts — global defaults applied to every page
 createFNetro({
   seo: {
     ogType:      'website',
@@ -329,42 +289,49 @@ createFNetro({
     twitterCard: 'summary_large_image',
     twitterSite: '@myapp',
     robots:      'index, follow',
+    themeColor:  '#0d0f14',
   },
   routes: [...],
 })
+```
 
-// app/routes/post.tsx — page-level (merges with app defaults)
+```ts
+// app/routes/post.tsx — page overrides (merged with app defaults)
 definePage({
   path: '/posts/[slug]',
-  loader: async (c) => ({ post: await getPost(c.req.param('slug')) }),
+  loader: (c) => ({ post: await getPost(c.req.param('slug')) }),
 
-  // Function form — receives loader data and params
   seo: (data, params) => ({
     title:            `${data.post.title} — My Blog`,
     description:      data.post.excerpt,
-    canonical:        `https://myapp.com/posts/${params.slug}`,
+    canonical:        `https://example.com/posts/${params.slug}`,
     ogTitle:          data.post.title,
     ogDescription:    data.post.excerpt,
-    ogImage:          data.post.coverImageUrl,
+    ogImage:          data.post.coverUrl,
     ogImageWidth:     '1200',
     ogImageHeight:    '630',
     twitterTitle:     data.post.title,
-    twitterImage:     data.post.coverImageUrl,
+    twitterImage:     data.post.coverUrl,
     jsonLd: {
-      '@context': 'https://schema.org',
-      '@type':    'Article',
-      headline:   data.post.title,
-      author:     { '@type': 'Person', name: data.post.authorName },
+      '@context':    'https://schema.org',
+      '@type':       'Article',
+      headline:      data.post.title,
+      author:        { '@type': 'Person', name: data.post.authorName },
       datePublished: data.post.publishedAt,
+      image:         data.post.coverUrl,
     },
+    extra: [
+      { name: 'article:author', content: data.post.authorName },
+    ],
   }),
+
   Page({ post }) { ... },
 })
 ```
 
 ### All SEO fields
 
-| Field | HTML output |
+| Field | `<head>` output |
 |---|---|
 | `title` | `<title>` |
 | `description` | `<meta name="description">` |
@@ -389,10 +356,11 @@ definePage({
 | `twitterTitle` | `<meta name="twitter:title">` |
 | `twitterDescription` | `<meta name="twitter:description">` |
 | `twitterImage` | `<meta name="twitter:image">` |
+| `twitterImageAlt` | `<meta name="twitter:image:alt">` |
 | `jsonLd` | `<script type="application/ld+json">` |
-| `extra` | Custom `<meta>` tags |
+| `extra` | Arbitrary `<meta>` tags |
 
-**Client-side SEO sync:** On SPA navigation, all `<meta>` tags and `document.title` are updated automatically — no full reload needed.
+On SPA navigation, all `<meta>` tags and `document.title` are updated automatically — no full reload.
 
 ---
 
@@ -400,29 +368,29 @@ definePage({
 
 ### Server middleware
 
-Hono middleware applied at three levels:
+Hono middleware at three levels — global, group, and page.
 
 ```ts
 import { createFNetro } from '@netrojs/fnetro/server'
-import { cors } from 'hono/cors'
-import { logger } from 'hono/logger'
-import { bearerAuth } from 'hono/bearer-auth'
+import { cors }         from 'hono/cors'
+import { logger }       from 'hono/logger'
+import { bearerAuth }   from 'hono/bearer-auth'
 
-// 1. Global — runs before every route
 const fnetro = createFNetro({
-  middleware: [logger(), cors({ origin: 'https://myapp.com' })],
+  // 1. Global — runs on every request
+  middleware: [logger(), cors({ origin: 'https://example.com' })],
 
   routes: [
-    // 2. Group-level — runs for all routes in the group
+    // 2. Group-level — runs for every route in the group
     defineGroup({
-      prefix:     '/dashboard',
+      prefix:     '/admin',
       middleware: [bearerAuth({ token: process.env.API_KEY! })],
       routes: [
         // 3. Page-level — runs for this route only
         definePage({
-          path:       '/settings',
+          path:       '/reports',
           middleware: [rateLimiter({ max: 10, window: '1m' })],
-          Page:       Settings,
+          Page:       Reports,
         }),
       ],
     }),
@@ -445,73 +413,61 @@ const requireAuth: HonoMiddleware = async (c, next) => {
 
 ### Client middleware
 
-Client middleware runs before every **SPA navigation**. Register with `useClientMiddleware()` **before** calling `boot()`.
+Runs before every **SPA navigation**. Register with `useClientMiddleware()` **before** `boot()`.
 
 ```ts
 // client.ts
 import { boot, useClientMiddleware, navigate } from '@netrojs/fnetro/client'
 
-// Analytics
+// Analytics — fires after navigation completes
 useClientMiddleware(async (url, next) => {
   await next()
-  analytics.track('pageview', { url })
+  analytics.page({ url })
 })
 
-// Auth guard
+// Auth guard — redirects before navigation
 useClientMiddleware(async (url, next) => {
-  const protectedPaths = ['/dashboard', '/settings', '/profile']
-  const isProtected = protectedPaths.some(p => url.startsWith(p))
-
-  if (isProtected && !isAuthenticated()) {
-    await navigate(`/login?redirect=${encodeURIComponent(url)}`)
-    return  // cancel original navigation
+  if (!isLoggedIn() && url.startsWith('/dashboard')) {
+    await navigate('/login?redirect=' + encodeURIComponent(url))
+    return  // cancel the original navigation
   }
-
   await next()
 })
 
 // Loading indicator
 useClientMiddleware(async (url, next) => {
-  showLoadingBar()
-  try {
-    await next()
-  } finally {
-    hideLoadingBar()
-  }
+  NProgress.start()
+  try   { await next() }
+  finally { NProgress.done() }
 })
 
 boot({ routes, layout })
 ```
 
-Middleware runs in registration order. The chain is `mw1 → mw2 → ... → actual navigation`.
+The chain runs in registration order: `mw1 → mw2 → ... → fetch + render`. Omitting `next()` in any middleware cancels the navigation.
 
 ---
 
 ## SolidJS reactivity
 
-Use SolidJS primitives directly — no FNetro wrappers needed.
+Use SolidJS primitives directly — no FNetro wrappers.
+
+**Module-level signals** persist across SPA navigations (they live for the lifetime of the page JS):
 
 ```tsx
-import { createSignal, createMemo, createEffect, For, Show } from 'solid-js'
-import { createStore, produce } from 'solid-js/store'
+import { createSignal, createMemo, createEffect, For } from 'solid-js'
 import { definePage } from '@netrojs/fnetro'
 
-// Module-level signals persist across SPA navigations
 const [count, setCount] = createSignal(0)
 const doubled = createMemo(() => count() * 2)
 
 export default definePage({
   path: '/counter',
   Page() {
-    // Effects run automatically when signals they read change
-    createEffect(() => {
-      document.title = `Count: ${count()}`
-    })
-
+    createEffect(() => { document.title = `Count: ${count()}` })
     return (
       <div>
-        <p>Count: {count()}</p>
-        <p>Doubled: {doubled()}</p>
+        <p>{count()} × 2 = {doubled()}</p>
         <button onClick={() => setCount(n => n + 1)}>+</button>
       </div>
     )
@@ -519,20 +475,15 @@ export default definePage({
 })
 ```
 
-**Store example:**
+**Stores** for structured reactive state:
 
 ```tsx
 import { createStore, produce } from 'solid-js/store'
 
 interface Todo { id: number; text: string; done: boolean }
-
 const [todos, setTodos] = createStore<{ items: Todo[] }>({ items: [] })
 
-function addTodo(text: string) {
-  setTodos('items', l => [...l, { id: Date.now(), text, done: false }])
-}
-
-function toggleTodo(id: number) {
+function toggle(id: number) {
   setTodos('items', t => t.id === id, produce(t => { t.done = !t.done }))
 }
 
@@ -540,18 +491,16 @@ export default definePage({
   path: '/todos',
   Page() {
     return (
-      <ul>
-        <For each={todos.items}>
-          {todo => (
-            <li
-              style={{ 'text-decoration': todo.done ? 'line-through' : 'none' }}
-              onClick={() => toggleTodo(todo.id)}
-            >
-              {todo.text}
-            </li>
-          )}
-        </For>
-      </ul>
+      <For each={todos.items}>
+        {(todo) => (
+          <li
+            style={{ 'text-decoration': todo.done ? 'line-through' : 'none' }}
+            onClick={() => toggle(todo.id)}
+          >
+            {todo.text}
+          </li>
+        )}
+      </For>
     )
   },
 })
@@ -561,18 +510,15 @@ export default definePage({
 
 ## Navigation
 
-### Link-based (automatic)
+### Links — automatic interception
 
-Any `<a href="...">` pointing to a registered route is intercepted automatically — no special component needed.
+Any `<a href="...">` pointing to a registered route is intercepted automatically. No special component needed.
 
 ```tsx
-// These all work — SPA navigation, no full reload
-<a href="/about">About</a>
-<a href="/posts/hello">Read post</a>
-
-// Opt out with data-no-spa or rel="external"
-<a href="/legacy" data-no-spa>Legacy page</a>
-<a href="https://external.com" rel="external">External</a>
+<a href="/about">About</a>             {/* → SPA navigation */}
+<a href="/posts/hello">Post</a>        {/* → SPA navigation */}
+<a href="/legacy" data-no-spa>Legacy</a>   {/* → full page load */}
+<a href="https://example.com" rel="external">External</a>  {/* → full page load */}
 ```
 
 ### Programmatic navigation
@@ -580,14 +526,9 @@ Any `<a href="...">` pointing to a registered route is intercepted automatically
 ```ts
 import { navigate } from '@netrojs/fnetro/client'
 
-// Push to history (default)
-await navigate('/about')
-
-// Replace current history entry
-await navigate('/login', { replace: true })
-
-// Prevent scroll-to-top
-await navigate('/modal', { scroll: false })
+await navigate('/about')                          // push history
+await navigate('/login', { replace: true })       // replace history entry
+await navigate('/modal', { scroll: false })       // skip scroll-to-top
 ```
 
 ### Prefetch
@@ -595,18 +536,10 @@ await navigate('/modal', { scroll: false })
 ```ts
 import { prefetch } from '@netrojs/fnetro/client'
 
-// On hover/focus — warms the loader cache
-prefetch('/about')
+prefetch('/about')   // warm the loader cache on hover / focus
 ```
 
-Hover-based prefetching is enabled by default in `boot()`:
-
-```ts
-boot({
-  prefetchOnHover: true,  // default: true
-  routes,
-})
-```
+Hover-based prefetching is automatic when `prefetchOnHover: true` (the default) is set in `boot()`.
 
 ---
 
@@ -614,46 +547,44 @@ boot({
 
 ### Development
 
-`@hono/vite-dev-server` injects Vite's dev client automatically. No asset configuration needed.
+`@hono/vite-dev-server` injects Vite's dev client and HMR scripts automatically. No asset config needed.
 
 ### Production
 
-The Vite plugin produces a `manifest.json` alongside the client bundle. The server reads it at startup to inject correct hashed URLs into every HTML response.
+`vite build` produces a `manifest.json` alongside the hashed client bundle. The server reads the manifest at startup to resolve the correct filenames.
 
 ```ts
-// app.ts — production configuration
+// app.ts
 createFNetro({
   routes,
   assets: {
-    // Path to the directory containing manifest.json
-    manifestDir:   'dist/assets',
-    // Key in the manifest (usually the entry filename)
-    manifestEntry: 'client.ts',
+    manifestDir:   'dist/assets',  // directory containing manifest.json
+    manifestEntry: 'client.ts',    // key in the manifest (your client entry)
   },
 })
 ```
 
-**Manual asset paths** (edge runtimes / when manifest is unavailable):
+**Manual override** (edge runtimes / CDN-hosted assets):
 
 ```ts
 createFNetro({
   assets: {
-    scripts: ['/assets/client-abc123.js'],
-    styles:  ['/assets/style-def456.css'],
+    scripts: ['https://cdn.example.com/client-abc123.js'],
+    styles:  ['https://cdn.example.com/style-def456.css'],
   },
 })
 ```
 
-**Public directory:** Static files in `public/` (images, fonts, robots.txt) are served at the root path by the Node.js `serve()` helper automatically.
+**Public directory** — static files in `public/` (images, fonts, `robots.txt`, `favicon.ico`) are served at `/` by the Node.js `serve()` helper automatically.
 
 ---
 
-## Multi-runtime `serve()`
+## Multi-runtime serve()
 
 ```ts
 import { serve } from '@netrojs/fnetro/server'
 
-// Auto-detects the runtime
+// Auto-detects Node.js, Bun, or Deno
 await serve({ app: fnetro })
 
 // Explicit configuration
@@ -661,16 +592,18 @@ await serve({
   app:       fnetro,
   port:      3000,
   hostname:  '0.0.0.0',
-  runtime:   'node',       // 'node' | 'bun' | 'deno'
-  staticDir: './dist',     // where dist/assets/ lives
+  runtime:   'node',       // 'node' | 'bun' | 'deno' | 'edge'
+  staticDir: './dist',     // root for /assets/* and /* static files
 })
 ```
 
-**Edge runtimes** (Cloudflare Workers, Deno Deploy, etc.) — just export the handler:
+**Edge runtimes** (Cloudflare Workers, Deno Deploy, Fastly, etc.):
 
 ```ts
 // server.ts
 import { fnetro } from './app'
+
+// Export the Hono fetch handler — the platform calls it directly
 export default { fetch: fnetro.handler }
 ```
 
@@ -680,25 +613,25 @@ export default { fetch: fnetro.handler }
 
 ```ts
 // vite.config.ts
-import { defineConfig } from 'vite'
+import { defineConfig }     from 'vite'
 import { fnetroVitePlugin } from '@netrojs/fnetro/vite'
-import devServer from '@hono/vite-dev-server'
+import devServer            from '@hono/vite-dev-server'
 
 export default defineConfig({
   plugins: [
-    // Handles JSX transform (vite-plugin-solid) + production dual build
+    // Handles: SolidJS JSX transform, SSR server build, client bundle + manifest
     fnetroVitePlugin({
-      serverEntry:  'app/server.ts',   // default: 'app/server.ts'
-      clientEntry:  'client.ts',       // default: 'client.ts'
-      serverOutDir: 'dist/server',     // default: 'dist/server'
-      clientOutDir: 'dist/assets',     // default: 'dist/assets'
-      // Extra packages to externalize in the server bundle
-      serverExternal: ['@myorg/db'],
-      // Options forwarded to vite-plugin-solid
-      solidOptions: { extensions: ['.mdx'] },
+      serverEntry:    'server.ts',    // default: 'server.ts'
+      clientEntry:    'client.ts',    // default: 'client.ts'
+      serverOutDir:   'dist/server',  // default: 'dist/server'
+      clientOutDir:   'dist/assets',  // default: 'dist/assets'
+      serverExternal: ['@myorg/db'],  // extra server-bundle externals
+      solidOptions:   {},             // forwarded to vite-plugin-solid
     }),
 
-    // Dev server — serves the app with hot-reload
+    // Dev: serves the FNetro app through Vite with hot-reload
+    // app.ts default export must be the Hono *instance* (fnetro.app),
+    // NOT fnetro.handler (plain function, no .fetch property).
     devServer({ entry: 'app.ts' }),
   ],
 })
@@ -709,26 +642,65 @@ export default defineConfig({
 ```
 dist/
 ├── server/
-│   └── server.js          # SSR server bundle
+│   └── server.js            # SSR server bundle (ESM)
 └── assets/
-    ├── manifest.json       # Asset manifest (for hashed URL resolution)
-    ├── client-abc123.js    # Hydration bundle
-    └── style-def456.css    # CSS (if imported in JS)
+    ├── manifest.json        # Vite asset manifest (for hashed URL resolution)
+    ├── client-[hash].js     # Hydration + SPA bundle
+    └── style-[hash].css     # CSS (when imported from JS)
 ```
 
 ---
 
+## Project structure
+
+```
+my-app/
+│
+├── app.ts              # Shared FNetro app — used by dev server AND server.ts
+│                       # Default export must be fnetro.app (Hono instance)
+│
+├── server.ts           # Production entry — imports app.ts, calls serve()
+├── client.ts           # Browser entry — registers middleware, calls boot()
+│
+├── app/
+│   ├── layouts.tsx     # defineLayout() — root shell (nav, footer)
+│   └── routes/
+│       ├── home.tsx    # definePage({ path: '/' })
+│       ├── about.tsx   # definePage({ path: '/about' })
+│       ├── api.ts      # defineApiRoute('/api', fn)
+│       └── posts/
+│           ├── index.tsx       # /posts
+│           └── [slug].tsx      # /posts/:slug
+│
+├── public/
+│   ├── style.css       # Global CSS (served at /style.css)
+│   └── favicon.ico
+│
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+### `app.ts` vs `server.ts`
+
+| File | Purpose |
+|---|---|
+| `app.ts` | Creates the FNetro app. Exports `fnetro` (named) and `fnetro.app` (default). Used by `@hono/vite-dev-server` in dev and imported by `server.ts` in production. |
+| `server.ts` | Production-only entry point. Imports from `app.ts` and calls `serve()`. Never imported by the dev server. |
+
+---
+
 ## TypeScript
 
-`tsconfig.json` for a FNetro project:
+`tsconfig.json` for any FNetro project:
 
 ```json
 {
   "compilerOptions": {
-    "target":                     "ESNext",
+    "target":                     "ES2022",
     "module":                     "ESNext",
     "moduleResolution":           "bundler",
-    "lib":                        ["ESNext", "DOM"],
+    "lib":                        ["ES2022", "DOM"],
     "jsx":                        "preserve",
     "jsxImportSource":            "solid-js",
     "strict":                     true,
@@ -742,53 +714,293 @@ dist/
 }
 ```
 
+> **Important:** `jsxImportSource` must be `"solid-js"` — not `"hono/jsx"`. FNetro v0.2+ uses SolidJS for all rendering.
+
+---
+
+## create-fnetro CLI
+
+Scaffold a new project interactively or from CI:
+
+```bash
+npm create @netrojs/fnetro@latest [project-name] [flags]
+```
+
+### Interactive mode
+
+Running without flags opens a step-by-step prompt:
+
+```
+  ⬡  create-fnetro
+  Full-stack Hono + SolidJS — SSR · SPA · SEO · TypeScript
+
+  ✔ Project name: … my-app
+  ✔ Target runtime: › Node.js
+  ✔ Template: › Minimal
+  ✔ Package manager: › npm
+  ✔ Install dependencies now? … yes
+  ✔ Initialize a git repository? … yes
+```
+
+### CLI flags (non-interactive / CI)
+
+| Flag | Values | Default |
+|---|---|---|
+| `--ci` | — | `false` |
+| `--runtime` | `node` `bun` `deno` `cloudflare` `generic` | `node` |
+| `--template` | `minimal` `full` | `minimal` |
+| `--pkg-manager` | `npm` `pnpm` `yarn` `bun` `deno` | `npm` |
+| `--no-install` | — | installs |
+| `--no-git` | — | initialises |
+
+```bash
+# Non-interactive CI scaffold
+npm create @netrojs/fnetro@latest my-app \
+  --ci \
+  --runtime node \
+  --template full \
+  --pkg-manager pnpm \
+  --no-git
+```
+
+### Templates
+
+**`minimal`** — production-ready starter:
+```
+app.ts  server.ts  client.ts
+app/layouts.tsx
+app/routes/home.tsx     # GET /
+app/routes/about.tsx    # GET /about
+app/routes/api.ts       # GET /api/health  GET /api/hello
+public/style.css
+```
+
+**`full`** — includes SolidJS signal demo, dynamic routes, and shared store:
+```
+(everything in minimal, plus)
+app/store.ts                      # createSignal + createStore examples
+app/routes/counter.tsx            # GET /counter — signals demo
+app/routes/posts/index.tsx        # GET /posts  — SSR list
+app/routes/posts/[slug].tsx       # GET /posts/:slug — dynamic SSR + SEO
+```
+
+### Supported runtimes
+
+| Runtime | Dev command | Prod server |
+|---|---|---|
+| `node` | `vite` (via `@hono/vite-dev-server`) | `@hono/node-server` |
+| `bun` | `bun --bun vite` | `Bun.serve` |
+| `deno` | `deno run -A npm:vite` | `Deno.serve` |
+| `cloudflare` | `wrangler dev` | Cloudflare Workers |
+| `generic` | `vite` | WinterCG `export default { fetch }` |
+
 ---
 
 ## API reference
 
 ### `@netrojs/fnetro` (core)
 
-| Export | Description |
-|---|---|
-| `definePage(def)` | Define a page route |
-| `defineGroup(def)` | Define a route group |
-| `defineLayout(Component)` | Define a layout component |
-| `defineApiRoute(path, register)` | Define raw Hono sub-routes |
-| `resolveRoutes(routes, opts)` | Internal: flatten route tree |
-| `compilePath(path)` | Internal: compile a path pattern |
-| `matchPath(compiled, pathname)` | Internal: match a compiled path |
-| `SPA_HEADER` | `'x-fnetro-spa'` |
-| `STATE_KEY` | `'__FNETRO_STATE__'` |
-| `PARAMS_KEY` | `'__FNETRO_PARAMS__'` |
-| `SEO_KEY` | `'__FNETRO_SEO__'` |
-
-**Types:** `AppConfig`, `PageDef<T>`, `GroupDef`, `LayoutDef`, `ApiRouteDef`, `Route`, `PageProps<T>`, `LayoutProps`, `SEOMeta`, `HonoMiddleware`, `LoaderCtx`, `ClientMiddleware`, `ResolvedRoute`, `CompiledPath`
+**Functions:**
+
+| Export | Signature | Description |
+|---|---|---|
+| `definePage` | `<T>(def) → PageDef<T>` | Define a page route |
+| `defineGroup` | `(def) → GroupDef` | Group routes under a prefix |
+| `defineLayout` | `(Component) → LayoutDef` | Wrap pages in a shared shell |
+| `defineApiRoute` | `(path, register) → ApiRouteDef` | Mount raw Hono sub-routes |
+| `compilePath` | `(path) → CompiledPath` | Compile a path pattern to a regex |
+| `matchPath` | `(compiled, pathname) → params \| null` | Match a compiled path |
+| `resolveRoutes` | `(routes, opts) → { pages, apis }` | Flatten a route tree |
+
+**Constants:** `SPA_HEADER` · `STATE_KEY` · `PARAMS_KEY` · `SEO_KEY`
+
+**Types:** `AppConfig` · `PageDef<T>` · `GroupDef` · `LayoutDef` · `ApiRouteDef` · `Route` · `PageProps<T>` · `LayoutProps` · `SEOMeta` · `HonoMiddleware` · `LoaderCtx` · `ClientMiddleware` · `ResolvedRoute` · `CompiledPath`
 
 ---
 
 ### `@netrojs/fnetro/server`
 
-| Export | Description |
-|---|---|
-| `createFNetro(config)` | Create the FNetro/Hono app |
-| `serve(opts)` | Start server for Node/Bun/Deno |
-| `detectRuntime()` | Auto-detect the current JS runtime |
-| `fnetroVitePlugin(opts?)` | Vite plugin for SSR + client builds |
+**Functions:**
+
+| Export | Signature | Description |
+|---|---|---|
+| `createFNetro` | `(config: FNetroOptions) → FNetroApp` | Build the Hono app |
+| `serve` | `(opts: ServeOptions) → Promise<void>` | Start server for Node/Bun/Deno |
+| `detectRuntime` | `() → Runtime` | Auto-detect the current JS runtime |
+| `fnetroVitePlugin` | `(opts?) → Plugin[]` | Vite plugin for dual build |
+
+**`FNetroOptions`** (extends `AppConfig`):
 
-**Types:** `FNetroOptions`, `FNetroApp`, `ServeOptions`, `Runtime`, `AssetConfig`, `FNetroPluginOptions`
+```ts
+interface FNetroOptions {
+  layout?:     LayoutDef           // default layout for all pages
+  seo?:        SEOMeta             // global SEO defaults
+  middleware?: HonoMiddleware[]    // global Hono middleware
+  routes:      Route[]             // top-level routes
+  notFound?:   Component           // 404 component
+  htmlAttrs?:  Record<string,string> // attributes on <html>
+  head?:       string              // raw HTML appended to <head>
+  assets?:     AssetConfig         // production asset config
+}
+```
+
+**`AssetConfig`:**
+
+```ts
+interface AssetConfig {
+  scripts?:       string[]   // explicit script URLs
+  styles?:        string[]   // explicit stylesheet URLs
+  manifestDir?:   string     // directory containing manifest.json
+  manifestEntry?: string     // manifest key for client entry (default: 'client.ts')
+}
+```
+
+**`ServeOptions`:**
+
+```ts
+interface ServeOptions {
+  app:        FNetroApp
+  port?:      number          // default: process.env.PORT ?? 3000
+  hostname?:  string          // default: '0.0.0.0'
+  runtime?:   Runtime         // default: auto-detected
+  staticDir?: string          // default: './dist'
+}
+```
+
+**`FNetroPluginOptions`:**
+
+```ts
+interface FNetroPluginOptions {
+  serverEntry?:    string    // default: 'server.ts'
+  clientEntry?:    string    // default: 'client.ts'
+  serverOutDir?:   string    // default: 'dist/server'
+  clientOutDir?:   string    // default: 'dist/assets'
+  serverExternal?: string[]  // extra server-bundle externals
+  solidOptions?:   object    // passed to vite-plugin-solid
+}
+```
 
 ---
 
 ### `@netrojs/fnetro/client`
 
-| Export | Description |
-|---|---|
-| `boot(options)` | Hydrate SSR HTML and start SPA |
-| `navigate(to, opts?)` | Programmatic SPA navigation |
-| `prefetch(url)` | Pre-warm the loader cache |
-| `useClientMiddleware(fn)` | Register client navigation middleware |
+**Functions:**
+
+| Export | Signature | Description |
+|---|---|---|
+| `boot` | `(opts: BootOptions) → Promise<void>` | Hydrate SSR and start SPA |
+| `navigate` | `(to, opts?) → Promise<void>` | Programmatic navigation |
+| `prefetch` | `(url) → void` | Warm loader cache |
+| `useClientMiddleware` | `(fn: ClientMiddleware) → void` | Register nav middleware |
+
+**`BootOptions`** (extends `AppConfig`):
+
+```ts
+interface BootOptions extends AppConfig {
+  prefetchOnHover?: boolean   // default: true
+}
+```
+
+**`NavigateOptions`:**
+
+```ts
+interface NavigateOptions {
+  replace?: boolean   // replaceState instead of pushState
+  scroll?:  boolean   // scroll to top after navigation (default: true)
+}
+```
+
+**`ClientMiddleware`:**
+
+```ts
+type ClientMiddleware = (
+  url:  string,
+  next: () => Promise<void>,
+) => Promise<void>
+```
+
+---
+
+## Monorepo development
+
+```bash
+# Clone and install
+git clone https://github.com/netrosolutions/fnetro.git
+cd fnetro
+npm install                  # hoists all workspace deps to root node_modules
+
+# Build both packages
+npm run build
+
+# Typecheck both packages
+npm run typecheck
+
+# Clean all dist/ directories
+npm run clean
 
-**Types:** `BootOptions`, `NavigateOptions`
+# Watch mode (fnetro package)
+npm run build:watch --workspace=packages/fnetro
+```
+
+### Workspace structure
+
+```
+fnetro/                           root (private monorepo)
+├── packages/
+│   ├── fnetro/                   @netrojs/fnetro
+│   │   ├── core.ts               Shared types, path matching, constants
+│   │   ├── server.ts             Hono factory, SSR renderer, Vite plugin, serve()
+│   │   ├── client.ts             SolidJS hydration, SPA router, client middleware
+│   │   └── tsup.config.ts        Build config (3 separate entry points)
+│   └── create-fnetro/            @netrojs/create-fnetro
+│       └── src/index.ts          CLI scaffolding tool
+├── .changeset/                   Changeset version files
+│   └── config.json
+└── .github/
+    └── workflows/
+        ├── ci.yml                Typecheck, build, scaffold smoke tests
+        └── release.yml           Changeset-driven versioning + npm publish
+```
+
+---
+
+## Publishing & releases
+
+This monorepo uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
+
+### Day-to-day workflow
+
+**1. Make changes** to `packages/fnetro` and/or `packages/create-fnetro`.
+
+**2. Add a changeset** describing the change:
+```bash
+npm run changeset
+# → prompts you to select packages and bump type (patch/minor/major)
+# → writes a .changeset/*.md file — commit this with your changes
+```
+
+**3. Open a PR.** CI runs typecheck, build, and scaffold smoke tests on Node 18 / 20 / 22 / 24.
+
+**4. Merge to `main`.** The `release.yml` workflow runs automatically:
+- If `.changeset/*.md` files exist → opens / updates a **"Version Packages"** PR that bumps versions and updates `CHANGELOG.md`
+- If the "Version Packages" PR is merged → **publishes both packages to npm** with provenance attestation and creates a GitHub Release
+
+### Manual release
+
+```bash
+# Dry run — see what would be published
+npm run release:dry
+
+# Full release (build + changeset publish)
+npm run release
+```
+
+### Secrets required
+
+| Secret | Description |
+|---|---|
+| `NPM_TOKEN` | npm automation token (requires publish permission for `@netrojs`) |
+| `GITHUB_TOKEN` | Provided automatically by GitHub Actions |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netrojs/fnetro",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Full-stack Hono framework — SolidJS SSR/SPA, SEO, middleware, route groups, API routes",
   "type": "module",
   "license": "MIT",