@noego/forge 0.0.9 → 0.0.11

package/README.md

@@ -22,99 +22,85 @@ You get **fast first paint & SEO** (SSR) *and* **instant page transitions** (cli
 - **Data Loading**: Unified mechanism for data fetching in SSR and client-side
 - **Vite Integration**: Modern, fast development with hot module reloading
 
-## Quick Start
+## Getting Started
 
-### TL;DR – Run the demo in two commands 🚀
+### Prerequisites
 
-```bash
-# 1. Install dependencies (Forge + peers)
-npm install   # or pnpm / yarn
+Forge requires:
+- **Node.js**: 16.x or higher
+- **Express**: ^5.1.0 (peer dependency)
+- **Svelte**: ^5.28.2 (peer dependency)
 
-# 2. Launch the development server (Express *and* Vite)
-npm run dev   # -> http://localhost:3000
-```
+For development:
+- **Vite**: ^6.3.5 (recommended for hot-module reloading and builds)
+- **tsx**: ^4.19.3 (recommended for running TypeScript entry files)
 
-Vite is wired up as **middleware** inside Express (`middlewareMode: true`).
-That means hot-module-reloading, static files, and SSR all live behind the
-same port – you only ever need to open http://localhost:3000.
+The versions shown in the badge at the very top are the ones Forge is tested against. Newer minor/patch releases of Express and Svelte usually work fine as well.
 
 ### Installation
 
+Install Forge and its peer dependencies:
+
 ```bash
-npm i @noego/forge express svelte
-```
+# npm
+npm install @noego/forge express@^5 svelte@^5
 
-Forge is a thin wrapper around **Express** and **Svelte**. The command above installs all three runtime dependencies you need. For development, you'll also want Vite for hot-module-reloading:
+# yarn
+yarn add @noego/forge express@^5 svelte@^5
 
-```bash
-# development-only (HMR, build, …)
-npm i -D vite
+# pnpm
+pnpm add @noego/forge express@^5 svelte@^5
 ```
 
-The versions shown in the badge at the very top are always the ones that Forge
-is tested against; newer minor / patch releases of Express and Svelte usually
-work fine as well.
+Then add development dependencies:
 
-### Basic Setup
-
-## Example Project Structure
+```bash
+# npm
+npm install --save-dev vite@^6 tsx @sveltejs/vite-plugin-svelte
 
-Forge is completely agnostic about where you place your files – as long as the
-paths in your **options object** are correct everything will “just work”.  To make the
-following snippets less abstract, here is one possible layout for a **full
-stack** repository:
+# yarn
+yarn add --dev vite@^6 tsx @sveltejs/vite-plugin-svelte
 
-```
-.
-├─ frontend/             # Svelte + Forge source code
-│  ├─ components/
-│  ├─ openapi.yaml
-│  ├─ client.ts          # client hydration entry
-│  └─ server.ts          # Express SSR entry
-├─ backend/              # (optional) REST / database code
-├─ vite.config.js        # shared by both dev & prod builds
-├─ forge.config.ts       # (optional) central Forge options shared by client & server
-└─ package.json          # root-level scripts & deps
+# pnpm
+pnpm add --save-dev vite@^6 tsx @sveltejs/vite-plugin-svelte
 ```
 
-Feel free to flatten or reorganise folders – if you move `components/` for
-instance, simply update `component_dir` and the import paths keep resolving
-correctly.
+### Quickstart
 
-### How Forge resolves paths
+Here's the minimal setup to get a working Forge application running:
 
-Forge only really needs three absolute paths to bootstrap your app:
+#### 1. Create your Express server (`server.ts`)
 
-1. **`component_dir`** – look here for Svelte files referenced in the OpenAPI
-   schema (every `x-view` / `x-layout` is interpreted *relative* to this
-   directory).
-2. **`open_api_path`** – the location of your `openapi.yaml`.
-3. **`renderer`** – an HTML template that contains the placeholders
-   `{{{APP}}}`, `{{{HEAD}}}` and `{{{DATA}}}`.
+```ts
+import express from 'express';
+import { createServer } from '@noego/forge/server';
 
-All paths are resolved against **`process.cwd()`** (your *project root*):
+const app = express();
 
-* **Relative strings** – the preferred form. Pass `frontend/components` instead
-  of `./frontend/components` so that the value still resolves correctly when
-  your working directory changes (for instance when running tests).
-* **Absolute strings starting with `/`** – treated as root-relative, e.g.
-  `/frontend/components` ➜ `path.join(process.cwd(), 'frontend/components')`.
+const options = {
+  component_dir: 'components',
+  renderer: 'index.html',
+  open_api_path: 'openapi.yaml',
+};
 
-Avoid the `./` prefix – while it works most of the time it breaks as soon as you
-invoke Node from a different folder.
+await createServer(app, options);
 
-1. **Configure OpenAPI Schema**
+export default app;
+```
 
-Forge extends the OpenAPI 3 spec with a couple of `x-*` vendor extensions.  Two
-conventions are important from day one:
+#### 2. Create an entry file (`dev.ts`)
 
-* **Landing page must be explicit** – declare the `/` path manually, Forge will
-  not create a default route for you.
-* **`x-layout` is always an array** – even when there is only one layout
-  component.  That keeps the type consistent and makes it possible to add more
-  wrappers later without touching already deployed code.
+```ts
+import app from './server';
 
-Create `openapi.yaml` in your project root:
+const PORT = process.env.PORT || 3000;
+
+app.listen(PORT, () => {
+  console.log(`🚀 Listening at http://localhost:${PORT}`);
+});
+```
+
+#### 3. Create your OpenAPI spec (`openapi.yaml`)
 
 ```yaml
 openapi: '3.0.3'
@@ -122,88 +108,48 @@ info:
   title: My App
   version: '1.0.0'
 
-x-fallback-view: error/404.svelte # 404 page
+x-fallback-view: error/404.svelte
 
 paths:
   /:
     get:
       summary: Home page
       x-view: views/home.svelte
-      x-layout: 
-        - layout/main.svelte
-  
-  '/user/:id':
-    get:
-      summary: User profile
-      x-view: views/user_page.svelte
-      x-layout: 
+      x-layout:
         - layout/main.svelte
 ```
 
-2. **Build (but don’t start) the Express server**
-
-Keeping server construction and `listen()` separate makes automated testing a
-lot easier because you can import the app without opening a TCP port.
-
-```ts
-// server.ts – returns a fully configured Express application
-import express from 'express';
-import { createServer } from '@noego/forge/server';
-import { options } from './forge.config';
-
-export async function buildServer() {
-  const app = express();
-  await createServer(app, options);
-  return app;
-}
-```
-
-3. **Start the server in dev / prod scripts**
-
-Your actual entry file is now a tiny wrapper that calls `buildServer()` and then
-`listen()`.  Swap it out for a different bootstrapper in tests.
-
-```ts
-// dev.ts – used by `npm run dev`
-import { buildServer } from './server';
-
-const PORT = process.env.PORT ?? 3000;
+#### 4. Create components
 
-buildServer()
-  .then(app => app.listen(PORT))
-  .then(() => console.log(`🚀  http://localhost:${PORT}`))
-  .catch(err => {
-    console.error('Server failed to start', err);
-    process.exit(1);
-  });
-```
+```html
+<!-- components/layout/main.svelte -->
+<script>
+  let { children } = $props();
+</script>
 
-4. **Create Client Initialization File**
+<nav>
+  <a href="/">Home</a>
+</nav>
+<main>
+  {@render children()}
+</main>
 
-```typescript
-// client.ts
-import { createApp } from '@noego/forge/client';
-import { options } from './forge.config';
+<!-- components/views/home.svelte -->
+<h1>Welcome to Forge!</h1>
 
-document.addEventListener('DOMContentLoaded', () => {
-  createApp(document.getElementById('app'), options);
-});
+<!-- components/error/404.svelte -->
+<h1>Page not found</h1>
 ```
 
-5. **Create HTML Template**
+#### 5. Create HTML template (`index.html`)
 
 ```html
-<!-- index.html -->
 <!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>My Forge App</title>
-  <!-- 👇👇 **Important for Vite HMR during development** 👇👇  -->
-  <!-- This script connects the page to Vite's Hot-Module-Reloading client.            -->
-  <!-- It MUST be included before your own client bundle when running the dev server. -->
-  <!-- Vite HMR client (served from project root) -->
   <script type="module" src="/@vite/client"></script>
   <style>{{{CSS}}}</style>
   {{{HEAD}}}
@@ -211,309 +157,361 @@ document.addEventListener('DOMContentLoaded', () => {
 <body>
   <div id="app">{{{APP}}}</div>
   <script>window.__INITIAL_DATA__ = {{{DATA}}};</script>
-  <!-- Application client entry (served from Vite dev server root) -->
   <script type="module" src="/client.ts"></script>
 </body>
 </html>
 ```
 
-6. **Provide Forge Options** (file name & language are totally up to you)
+#### 6. Create client entry (`client.ts`)
 
 ```ts
-// forge.config.ts  (could also be .js / .mjs – only the exported object matters)
-import type { ServerOptions } from '@noego/forge/options';
+import { createApp } from '@noego/forge/client';
 
-export const options: ServerOptions = {
+const options = {
   component_dir: 'components',
   renderer: 'index.html',
-  assets: {
-    '/assets': ['public']
-  },
   open_api_path: 'openapi.yaml',
-  // Optional: directory containing server-side x-middleware modules
-  middleware_path: 'middleware'
 };
-```
-
-> See `docs/server_middleware.md` for more on declaring `x-middleware` chains.
-
-7. **Create Components**
 
-```html
-<!-- components/layout/main.svelte -->
-<script>
-  let { children } = $props();
-</script>
-
-<nav>
-  <a href="/">Home</a>
-  <a href="/user/1">User</a>
-</nav>
-<main>
-  {@render children()}
-</main>
-
-<!-- components/views/home.svelte -->
-<h1>Welcome to my app!</h1>
+document.addEventListener('DOMContentLoaded', () => {
+  createApp(document.getElementById('app'), options);
+});
+```
 
-<!-- components/views/user_page.svelte -->
-<script>
-  export let params = {};
-</script>
+#### 7. Add Vite config (`vite.config.js`)
 
-<h1>User {params.id}</h1>
+```js
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
 
-<!-- components/error/404.svelte -->
-<h1>Page not found</h1>
+export default defineConfig({
+  plugins: [svelte()],
+});
 ```
 
-8. **Start Development Server**
+#### 8. Add npm scripts to `package.json`
 
-Add to your package.json:
 ```json
-"scripts": {
-  "dev": "tsx dev.ts",
-  "watch": "tsx watch --ignore '**/*.svelte' dev.ts",
-  "typecheck": "tsc --noEmit && svelte-check"
+{
+  "scripts": {
+    "dev": "tsx dev.ts",
+    "watch": "tsx watch --ignore '**/*.svelte' dev.ts",
+    "build:client": "vite build",
+    "build:ssr": "SSR=true vite build --ssr",
+    "build": "npm run build:client && npm run build:ssr",
+    "typecheck": "tsc --noEmit && svelte-check"
+  }
 }
 ```
 
-Run the server:
+#### 9. Run the development server
+
 ```bash
 npm run dev
 ```
 
-## Available npm scripts
+Visit `http://localhost:3000` in your browser. Vite is running as middleware inside Express, so hot-module reloading (HMR) and SSR both live behind the same port.
 
-| Script | What it does |
-|--------|--------------|
-| `dev` | Express + Vite with HMR (default development mode) |
-| `watch` | Restarts Express when server-side files change |
-| `build` | Generates both client & SSR bundles (`vite build` twice) |
-| `typecheck` | Runs `tsc` and `svelte-check` |
+### Example Project Structure
 
-## Further documentation 📚
+Here's a recommended full-stack layout:
 
-The README is only the quick-start.  For deeper topics have a look at the
-markdown files under [`/docs`](./docs):
+```
+.
+├─ components/           # Svelte components
+│  ├─ layout/
+│  ├─ views/
+│  └─ error/
+├─ openapi.yaml         # OpenAPI specification
+├─ index.html           # HTML template
+├─ client.ts            # Client entry point
+├─ server.ts            # Server entry point
+├─ dev.ts               # Development entry
+├─ vite.config.js       # Vite configuration
+├─ package.json
+└─ tsconfig.json
+```
 
-| Document | What you will find |
-|----------|--------------------|
-| **layout_system.md** | How Forge composes nested layouts and views, best-practices, common pitfalls, and design guidelines. |
-| **load_functions.md** | How to fetch data safely on the server with `load()`, have it ready for SSR and client-side navigation, and access it via `$props()`. |
-| **state_sharing.md** | Pattern for reactive global state with Svelte 5 context and `$state`, including multi-property examples. |
-| **tailwind-layouts.md** | Design layouts with Tailwind CSS: global shells, nested wrappers, responsive tips. |
-| **FETCH_MIDDLEWARE.md** | Client-side fetch middleware: header injection, redirect handling, debugging helpers, security notes. |
+Feel free to organize files differently – the important thing is that paths in your options object point to the correct locations.
 
-More docs will be added over time—keep an eye on the folder when upgrading.
+## Usage
 
-9. **Create a `vite.config.js` (if you don't already have one)**
+### Defining Routes with OpenAPI
 
-Forge relies on Vite for both development (HMR) and production builds.  
-If your project was scaffolded from scratch you will need to add a minimal
-`vite.config.js` file at the root of the repository so Vite knows how to handle
-Svelte files:
+Forge extends OpenAPI 3 with custom `x-*` vendor extensions to define your application structure. Every route in your application is declared in `openapi.yaml`:
 
-```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import { svelte } from '@sveltejs/vite-plugin-svelte';
+#### Key OpenAPI Extensions
 
-export default defineConfig({
-  plugins: [svelte()],
-});
+| Extension | Description |
+|-----------|-------------|
+| `x-view` | Path to the Svelte component that renders the page view |
+| `x-layout` | Array of layout components (rendered outside-in) that wrap the view |
+| `x-fallback-view` | Component to render for 404 errors |
+| `x-fallback-layout` | Default layout when none is specified |
+| `x-middleware` | Array of middleware functions to run before rendering |
+
+#### Important Conventions
+
+1. **Landing page must be explicit** – Always declare the `/` path manually. Forge will not create a default route for you.
+2. **`x-layout` is always an array** – Even with one layout component. This keeps types consistent and lets you add more wrappers later without breaking deployed code.
+
+#### Example OpenAPI Schema
+
+```yaml
+openapi: '3.0.3'
+info:
+  title: My App
+  version: '1.0.0'
+
+x-fallback-view: error/404.svelte
+
+paths:
+  /:
+    get:
+      summary: Home page
+      x-view: views/home.svelte
+      x-layout:
+        - layout/main.svelte
+
+  '/user/:id':
+    get:
+      summary: User profile
+      x-view: views/user_page.svelte
+      x-layout:
+        - layout/main.svelte
+
+  '/products':
+    get:
+      summary: Product listing
+      x-view: views/products.svelte
+      x-layout:
+        - layout/main.svelte
+        - layout/products_layout.svelte
 ```
 
-This can of course be extended with any additional Vite options that your
-application requires – the only strict requirement is that the Svelte plugin is
-present so that `*.svelte` files are compiled correctly.
+### Path Resolution
 
-## Configuration Options
+Forge resolves paths relative to `process.cwd()` (your project root). Use one of these formats:
 
-### Server Options
+**Relative paths (recommended):**
+```ts
+const options = {
+  component_dir: 'components',           // ✅ Correct
+  renderer: 'index.html',
+  open_api_path: 'openapi.yaml',
+};
+```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `development` | boolean | `process.env.NODE_ENV !== 'production'` | Development mode flag |
-| `component_dir` | string | `/` | Directory containing Svelte components |
-| `build_dir` | string | `dist_ssr` | Output directory for production builds |
-| `renderer` | string \| IHTMLRender | `default` | HTML template path or renderer |
-| `open_api_path` | string | `process.cwd() + '/openapi.yaml'` | Path to OpenAPI specification |
-| `manifest_endpoint` | string | `/manifest.json` | Endpoint for manifest file |
-| `assets` | Record<string, string[]> | `undefined` | Map of URL paths to directories for static assets |
-| `viteOptions` | object | See code | Vite configuration options |
+**Root-relative paths (absolute in the project root):**
+```ts
+const options = {
+  component_dir: '/frontend/components',  // ✅ Also correct
+  renderer: '/frontend/index.html',
+};
+```
 
-### OpenAPI Extensions
+**Avoid relative paths with `./` prefix:**
+```ts
+const options = {
+  component_dir: './components',          // ❌ Breaks when Node is invoked from different directories
+};
+```
 
-Forge uses custom OpenAPI extensions to define your application structure:
+### HTML Template Placeholders
 
-| Extension | Description |
-|-----------|-------------|
-| `x-view` | Path to the Svelte component that handles the route |
-| `x-layout` | Array of layout components that wrap the view (rendered outside-in) |
-| `x-fallback-view` | Component to render for 404 errors |
-| `x-fallback-layout` | Default layout when none is specified |
+Your renderer (typically `index.html`) must contain these three placeholders:
 
-## Advanced Usage
+| Placeholder | Content |
+|-------------|---------|
+| `{{{APP}}}` | Server-rendered HTML from your Svelte components |
+| `{{{HEAD}}}` | Head tags generated by Svelte (meta, stylesheets, etc.) |
+| `{{{DATA}}}` | Initial data from `load()` functions, serialized as JSON |
 
-### Fetch Middleware for Authentication
+### Configuration Options
 
-Forge provides a client-side fetch middleware system that allows you to automatically modify all fetch requests, eliminating the need to manually add authentication headers to every API call.
+Create a central options file (typically `forge.config.ts` or `forge.config.js`):
 
-```typescript
-// client.ts
-import { createApp, fetch } from '@noego/forge/client';
-import { options } from './forge.config';
+```ts
+import type { ServerOptions } from '@noego/forge/options';
 
-// Configure fetch middleware to automatically add authentication headers
-fetch.configUpdate((url, init) => {
-  const token = localStorage.getItem('auth_token');
-  if (token) {
-    const headers = new Headers(init?.headers);
-    headers.set('Authorization', `Bearer ${token}`);
-    return {
-      ...init,
-      headers
-    };
-  }
-  return init;
-});
+export const options: ServerOptions = {
+  // Required
+  component_dir: 'components',
+  renderer: 'index.html',
+  open_api_path: 'openapi.yaml',
 
-document.addEventListener('DOMContentLoaded', () => {
-  createApp(document.getElementById('app'), options);
-});
+  // Optional
+  development: process.env.NODE_ENV !== 'production',
+  build_dir: 'dist_ssr',
+  manifest_endpoint: '/manifest.json',
+  middleware_path: 'middleware',
+
+  // Static assets mapping
+  assets: {
+    '/assets': ['public'],
+    '/images': ['resources/images'],
+  }
+};
 ```
 
-With this middleware configured, all fetch calls in your application will automatically include the Authorization header:
+### Component Data Loading
 
-```typescript
-// No need to manually add Authorization headers anymore
-const response = await fetch('/api/contractor-types', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'New Type' })
-});
+Components can export a server-only `load()` function to fetch and prepare data before rendering:
+
+```svelte
+<!-- components/views/user.svelte -->
+<script lang="ts">
+  export let data: any;
+
+  export async function load(request) {
+    const { params, query } = request;
+
+    // Fetch data from your API or database
+    const user = await fetchUser(params.id);
+
+    return {
+      user,
+      debug: { query }
+    };
+  }
+</script>
+
+<h1>{data.user.name}</h1>
 ```
 
-The middleware function receives the same parameters as the native `fetch()` function and should return the modified `RequestInit` object. You can use this pattern for:
+The `load()` function receives a `RequestData` object with:
 
-- Adding authentication tokens
-- Setting default headers
-- Logging requests
-- Transforming request data
+| Property | Description |
+|----------|-------------|
+| `url` | Full request URL |
+| `params` | Dynamic route parameters (e.g., `{ id: '123' }`) |
+| `query` | Query string parameters |
+| `headers` | Request headers |
+| `body` | Parsed request body (POST/PUT/etc.) |
+| `context` | Per-request context bag (mutated by middleware) |
+
+**Forge behavior:**
+1. During **SSR**: `load()` is called on the server, data is embedded in the HTML
+2. During **client-side navigation**: Forge automatically fetches the data as JSON from the same URL
+3. The component receives identical data in both cases
 
 ### Nested Layouts
 
-Forge supports nested layouts, rendered in the order specified:
+Layouts are composed in the order specified, wrapping each other:
 
 ```yaml
 paths:
-  '/product/:id':
+  '/admin/users':
     get:
-      x-view: views/product_page.svelte      # 👈 view component
+      x-view: views/admin/users_list.svelte
       x-layout:
-        - layout/main.svelte                # outer layout
-        - layout/product_layout.svelte      # inner (page-specific) layout
+        - layout/main.svelte           # outer layout
+        - layout/admin_layout.svelte   # middle layout
+        - layout/sidebar.svelte        # inner layout
 ```
 
-The resulting component tree:
+This creates the component tree:
 ```
 main.svelte
-  └── product_layout.svelte
-        └── product_page.svelte (view)
+  └── admin_layout.svelte
+        └── sidebar.svelte
+              └── users_list.svelte (view)
 ```
 
+Each layout receives a `children()` snippet to render inner content.
+
 ### Static Assets
 
-Configure multiple asset directories:
+Map URL paths to directories on disk:
 
-```typescript
-assets: {
-  '/assets': ['public'],
-  '/images': ['resources/images'],
-  '/docs': ['documentation']
-}
+```ts
+const options = {
+  assets: {
+    '/assets': ['public'],           // GET /assets/style.css → public/style.css
+    '/images': ['resources/images'], // GET /images/logo.png → resources/images/logo.png
+  }
+};
 ```
 
-⚠ **Important:** every directory listed in `assets` *must* exist at server
-start-up, otherwise `express.static` will throw an error and Forge will refuse to
-boot.  If you need to commit an empty folder simply add a dummy
-`public/.gitkeep` file so the directory makes it into version control.
+**Important**: All directories in `assets` must exist when the server starts, otherwise Express will throw an error. Use `.gitkeep` files to commit empty directories.
 
-### Component Data Loading
+### Client-Side Fetch Middleware
 
-Svelte components can export a **server-only** `load` function that returns the
-initial data for the page.
+Automatically modify all fetch requests (e.g., add authentication headers):
 
-Forge will:
-1. Invoke `load()` during SSR and embed the returned JSON into the HTML.
-2. On subsequent **client-side navigations** automatically issue an
-   `application/json` request to the same URL and pass the payload to the
-   destination component – you don’t have to write any extra code.
+```ts
+// client.ts
+import { createApp, fetch } from '@noego/forge/client';
+import { options } from './forge.config';
 
-```html
-<script lang="ts">
-  export let data: any;  // data returned by `load()`
-
-  /**
-   * `load()` is executed exactly once on the server.
-   * It receives a single argument – an object that describes the incoming
-   * request.  Forge then serialises the returned value and re-hydrates it on
-   * the client (or performs an automatic JSON fetch when navigating
-   * client-side).
-   */
-  export async function load(request) {
-    const { params, query } = request;
-    // Fetch data however you like (Database, internal service, etc.)
-    return {
-      username: `User #${params.id}`,
-      debug: { query }
-    };
+// Add a global fetch middleware
+fetch.configUpdate((url, init) => {
+  const token = localStorage.getItem('auth_token');
+  if (token) {
+    const headers = new Headers(init?.headers);
+    headers.set('Authorization', `Bearer ${token}`);
+    return { ...init, headers };
   }
-</script>
+  return init;
+});
 
-<h1>{data.username}</h1>
+document.addEventListener('DOMContentLoaded', () => {
+  createApp(document.getElementById('app'), options);
+});
 ```
 
-The `request` object passed to `load()` (alias: `RequestData`) contains:
+Now all fetch calls automatically include the token:
 
-| Property | Description |
-|----------|-------------|
-| `url`    | Full request URL. |
-| `params` | Dynamic route params parsed from the URL. |
-| `query`  | Query-string parameters. |
-| `headers`| Raw request headers. |
-| `body`   | Parsed request body (for POST/PUT …). |
-| `context`| Mutable per-request bag you can populate in middleware. |
+```ts
+// No manual headers needed
+const response = await fetch('/api/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'Alice' })
+});
+```
 
-## Building for Production
+## Advanced Topics
 
-1. **Add build scripts to package.json**:
+### Development vs. Production Behavior
 
-```json
-"scripts": {
-  "build:client": "vite build",
-  "build:ssr": "SSR=true vite build --ssr",
-  "build": "npm run build:client && npm run build:ssr"
-}
-```
+**Development mode** (`npm run dev`):
+- Vite runs as middleware inside Express (`middlewareMode: true`)
+- Hot Module Reloading (HMR) is enabled
+- Svelte components are compiled on-the-fly
+- All requests go through a single Express port
+
+**Production mode** (`NODE_ENV=production`):
+- Static pre-built client and SSR bundles are served
+- No Vite middleware (faster, smaller footprint)
+- Use `npm run build` to generate `dist/` and `dist_ssr/` directories
 
-2. **Run build**:
+### Building for Production
+
+1. Generate production bundles:
 
 ```bash
 npm run build
 ```
 
-3. **Start production server**:
+This runs two Vite builds:
+- **Client build**: Creates `dist/` for browser assets
+- **SSR build**: Creates `dist_ssr/` for server bundle
+
+2. Serve in production:
 
 ```bash
 NODE_ENV=production node server.js
 ```
 
-## Testing with Vitest / Jest
+Your Forge app will serve:
+- Pre-compiled client code from `dist/`
+- Server-side rendered HTML using `dist_ssr/`
+- No Vite runtime overhead
 
-When you test Forge apps with **Vitest** or **Jest** you usually drive the
-Express server via **supertest**:
+### Testing with Vitest / Jest
+
+Use **supertest** to drive your Express server in tests:
 
 ```ts
 import request from 'supertest';
@@ -532,88 +530,148 @@ afterAll(() => {
 });
 ```
 
-Two things to remember:
+**Key points:**
+- HTML is streamed, so use `res.text` not `res.body`
+- Always close the server after tests to release handles
+- `buildServer()` doesn't call `listen()`, so you control the lifecycle
 
-1. The **HTML is streamed**, so the response body is available in `res.text`.
-2. Always close the server after long-running suites to release file & WS handles.
+### Server-Side Middleware
 
-## Troubleshooting
+Define custom middleware in `x-middleware` arrays to run before rendering:
 
-### Common Issues
+```yaml
+paths:
+  '/admin':
+    get:
+      x-middleware:
+        - requireAuth
+        - loadUserData
+      x-view: views/admin.svelte
+```
 
-#### Components Not Loading
+Middleware files are loaded from your `middleware_path` and can modify the request context:
 
-Ensure your `component_dir` matches the directory structure and is accessible relative to your project root.
+```ts
+// middleware/requireAuth.ts
+export default (request) => {
+  if (!request.headers.authorization) {
+    throw new Error('Unauthorized');
+  }
+  request.context.user = parseToken(request.headers.authorization);
+};
+```
 
-#### SSR Hydration Errors
+See `docs/server_middleware.md` for detailed examples.
 
-- Check for components that use browser-specific APIs without checking for `typeof window !== 'undefined'`
-- Ensure components use the same data during SSR and client-side hydration
+### Stitch Integration (Modular OpenAPI)
 
-#### HMR not triggering inside WSL / Docker
+For large projects, split your OpenAPI spec into multiple files with **Stitch**:
 
-File system events can behave differently inside virtualised environments.  If
-you do not see hot-reloading updates, set `watch: { usePolling: true }` in
-`vite.config.js`.  This project’s config already enables it – the note is here
-so you know *why*.
+1. Create `stitch.yaml`:
 
-#### "Unexpected token <" / Hydration mismatch warnings
+```yaml
+stitch:
+  - openapi/base.yaml
+  - openapi/routes/*.yaml
+  - openapi/components/*.yaml
+```
 
-Usually indicates that the HTML the server sent does not match the DOM the
-client tries to hydrate.  Double-check that any data returned from a
-component’s `load()` function is identical on **both** sides.
+2. In your client, load YAML via `import.meta.glob()`:
 
-#### Route Not Found
+```ts
+const yamlFiles = import.meta.glob('./openapi/**/*.yaml', {
+  query: '?raw',
+  import: 'default',
+  eager: true
+});
 
-- Verify your OpenAPI paths are correctly defined
-- Check that component file paths in `x-view` and `x-layout` are correct
-- Ensure all referenced components exist
+await createApp(document.getElementById('app'), {
+  open_api_path: 'openapi/stitch.yaml',
+  component_dir: 'components'
+});
+```
 
-## Stitch Integration (Modular YAML)
+Forge automatically detects stitch files and merges them into a single spec. No build step required – hot reloading works automatically.
 
-Forge automatically detects and builds stitch configurations for modular OpenAPI development. Instead of maintaining a single large `openapi.yaml`, you can split your API specification into multiple files.
+### Hydration and SSR Debugging
 
-### Using Stitch Files
+**Common hydration mismatch issues:**
+- Component uses browser-only APIs (e.g., `window`, `document`) without checking `typeof window`
+- Different data is returned by `load()` on server vs. client
+- Non-deterministic data (dates, random numbers, etc.)
 
-1. **Create a stitch configuration** (`stitch.yaml`):
+**Debug tips:**
+```ts
+// ✅ Safe: check for browser environment
+export async function load(request) {
+  if (typeof window !== 'undefined') {
+    // Client-only code
+  }
+  return data;
+}
 
-```yaml
-stitch:
-  - openapi/base.yaml
-  - openapi/routes/*.yaml
-  - openapi/components/*.yaml
+// ✅ Deterministic: same data every time
+const data = {
+  timestamp: '2025-10-22T00:00:00Z',  // Fixed, not Date.now()
+  userId: params.id,
+};
+
+// ❌ Unsafe: different every render
+const data = { id: Math.random() };
 ```
 
-2. **Pre-load YAML modules** in your client application:
+### Additional Documentation
 
-```typescript
-// Client-side: Load YAML files into Vite's module cache
-const yamlFiles = import.meta.glob('./openapi/**/*.yaml', { query: '?raw', import: 'default', eager: true });
+For deeper topics, check the documentation in [`/docs`](./docs):
 
-await createApp(document.getElementById('app'), {
-  open_api_path: 'frontend/stitch.yaml',  // Framework auto-detects and builds
-  component_dir: 'frontend/components/views'
+| Document | Coverage |
+|----------|----------|
+| **layout_system.md** | Composing nested layouts, best practices, common pitfalls |
+| **load_functions.md** | Data fetching with `load()`, SSR and client-side behavior |
+| **state_sharing.md** | Reactive global state with Svelte 5 context and `$state` |
+| **tailwind-layouts.md** | Design layouts with Tailwind CSS |
+| **FETCH_MIDDLEWARE.md** | Client-side fetch middleware, authentication, security |
+| **server_middleware.md** | Per-route server middleware and request context |
+
+
+## Troubleshooting
+
+### Common Issues
+
+**Components Not Loading**
+
+Ensure your `component_dir` matches the directory structure and is accessible relative to your project root. Verify paths are resolved correctly against `process.cwd()`.
+
+**SSR Hydration Errors**
+
+Common causes:
+- Components use browser-only APIs (`window`, `document`) without checking `typeof window !== 'undefined'`
+- Component returns different data during SSR vs. client-side navigation
+- Non-deterministic data (random values, current timestamps)
+
+**HMR not triggering inside WSL / Docker**
+
+File system events behave differently in virtualized environments. Add this to `vite.config.js`:
+
+```js
+export default defineConfig({
+  plugins: [svelte()],
+  watch: { usePolling: true }
 });
 ```
 
-3. **Framework auto-detection** – Forge automatically:
-   - Detects stitch files by checking for the `stitch` root property
-   - Builds the final OpenAPI configuration using `@noego/stitch/browser`
-   - Uses the cached YAML modules from your `import.meta.glob` call
-   - Falls back to regular OpenAPI processing for non-stitch files
-
-### Benefits
+**"Unexpected token <" / Hydration mismatch warnings**
 
-- **No manual build steps** – No need for `npm run stitch:frontend`
-- **Modular development** – Split complex APIs into focused files
-- **Hot reloading** – Vite automatically reloads when YAML files change
-- **Backwards compatible** – Existing `openapi.yaml` files work unchanged
+The HTML from the server doesn't match the DOM the client tries to hydrate. Ensure:
+- Component `load()` functions return identical data on server and client
+- No random values or time-dependent logic in initial render
 
-### Requirements
+**Route Not Found**
 
-- Client applications must call `import.meta.glob('./openapi/**/*.yaml', ...)` for Vite caching
-- The glob pattern must be **static** and **top-level** for Vite's static analysis
-- YAML files are loaded into the browser bundle but only once (no duplication)
+Check:
+1. OpenAPI paths are correctly defined in `openapi.yaml`
+2. Component file paths in `x-view` and `x-layout` exist and are relative to `component_dir`
+3. All referenced component files exist on disk
 
 ## Contributing